mosquitto_ctrl - Man Page

a tool for initialising/configuring a Mosquitto broker instance

Synopsis

mosquitto_ctrl [options | -o config-file] module-name module-command [command-options]

options: [auth-options] [connection-options] [mqtt-options] [output-options] [tls-certificate-options | tls-psk-options]

auth-options:
[-u username] [-P password]

connection-options:
{[-h hostname] [--unix socket path] [-p port-number]  | -L URL}
[-A bind-address]
[--proxy socks-url]

mqtt-options:
[-c] [-i client-id] [-q message-QoS] [-V protocol-version]

output-options:
[-d] [--quiet]

tls-certificate-options:
[--no-tls]
{--cafile file | --capath dir}
[--tls-use-os-certs]
[--cert file] [--key file]
[--ciphers ciphers] [--insecure] [--tls-alpn protocol] [--tls-keylog file] [--tls-version version]
[--tls-engine engine] [--keyform {pem | engine}] [--tls-engine-kpass-sha1 kpass-sha1]

tls-psk-options:
--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]

mosquitto_ctrl [connection-options] (interactive shell mode)

mosquitto_ctrl [--help]

Description

mosquitto_ctrl is a tool for helping configure a Mosquitto broker instance​.

It can be run primarily as a straightforward command line tool, as described here, or as an interactive shell as described in mosquitto_ctrl_shell(1)​. The interactive shell makes most operations very straightforward and is recommended for ease of use​.

Encrypted Connections

mosquitto_ctrl supports TLS encrypted connections​. It is strongly recommended that you use an encrypted connection for all remote use of mosquitto_ctrl​.

To enable TLS connections when using x509 certificates, one of either --cafile or --capath must be provided as an option​.

To enable TLS connections when using TLS-PSK, you must use the --psk and the --psk-identity options​.

Modules

Dynamic security

Authentication, and role based access control with users and groups​. Uses the dynsec module name​. See: mosquitto_ctrl_dynsec(1)

External modules

mosquitto_ctrl has the ability to load external modules in the form of shared libraries​. For example using the module name example will try to load the external module mosquitto_ctrl_example​.so or mosquitto_ctrl_example​.dll, depending on platform​. This allows new functionality to be added to Mosquitto by combining a plugin and mosquitto_ctrl module, without having to recompile any Mosquitto source code​.

Connection Options

The options below may be given on the command line, but may also be placed in a config file located at $XDG_CONFIG_HOME/mosquitto_ctrl or $HOME/​.config/mosquitto_ctrl​.

The config file may be specified manually with the -o config-file option​.

The config file should have one pair of -option value per line​. The values in the config file will be used as defaults and can be overridden by using the command line​. The exceptions to this are the message type options, of which only one can be specified​. Note also that currently some options cannot be negated, e​.g​. -S​. Config file lines that have a # as the first character are treated as comments and not processed any further​.

-A

Bind the outgoing connection to a local ip address/hostname​. Use this argument if you need to restrict network communication to a particular interface​.

--cafile

Define the path to a file containing PEM encoded CA certificates that are trusted​. Used to enable SSL communication​.

See also --capath

--capath

Define the path to a directory containing PEM encoded CA certificates that are trusted​. Used to enable SSL communication​.

For --capath to work correctly, the certificate files must have "​.crt" as the file ending and you must run "openssl rehash <path to capath>" each time you add/remove a certificate​.

See also --cafile

--cert

Define the path to a file containing a PEM encoded certificate for this client, if required by the server​.

See also --key and the Encrypted Connections section​.

--ciphers

An openssl compatible list of TLS ciphers to support in the client​. See ciphers(1) for more information​.

-d,  --debug

Enable debug messages​.

-D,  --property

Set MQTT v5 properties for with this client​. If you use this option, the client will be set to be an MQTT v5 client​. This option has two forms:

-D command identifier value

-D command identifier name value

command is the MQTT command/packet identifier and can be one of Connect, Publish, PUBACK, PUBREC, PUBCOMP, SUBSCRIBE, UNSUBSCRIBE, Disconnect, AUTH, or WILL​. The properties available for each command are listed in the Properties section​.

identifier is the name of the property to add​. This is as described in the specification, but with '-' as a word separator​. For example: payload-format-indicator​. More details are in the Properties section​.

value is the value of the property to add, with a data type that is property specific​.

name is only used for the user-property property as the first of the two strings in the string pair​. In that case, value is the second of the strings in the pair​.

--help

Display usage information​.

-h,  --host

Specify the host to connect to​. Defaults to localhost​.

-i,  --id

The id to use for this client​. If not given, a client id will be generated depending on the MQTT version being used​. For v3​.1​.1/v3​.1, the client generates a client id in the format mosq-XXXXXXXXXXXXXXXXXX, where the X are replaced with random alphanumeric characters​. For v5​.0, the client sends a zero length client id, and the server will generate a client id for the client​.

--insecure

When using certificate based encryption, this option disables verification of the server hostname in the server certificate​. This can be useful when testing initial server configurations but makes it possible for a malicious third party to impersonate your server through DNS spoofing, for example​. Use this option in testing only​. If you need to resort to using this option in a production environment, your setup is at fault and there is no point using encryption​.

--key

Define the path to a file containing a PEM encoded private key for this client, carrying out mutual TLS with the server​.

See also --cert and the Encrypted Connections section​.

--keyform

Specifies the type of private key in use when making TLS connections​.​. This can be "pem" or "engine"​. This parameter is useful when a TPM module is being used and the private key has been created with it​. Defaults to "pem", which means normal private key files are used​.

See also --tls-engine​.

-L,  --url

Specify specify user, password, hostname, port and topic at once as a URL​. The URL must be in the form: mqtt(s)://[username[:password]@]host[:port]/topic or ws(s)://[username[:password]@]host[:port]/path

Depending on the scheme, the port will default to different values​. mqtt:// - 1883, mqtts:// - 8883, ws:// - 80, wss:// - 443​.

--nodelay

Disable Nagle's algorithm for the socket​. This means that latency of sent messages is reduced, which is particularly noticeable for small, reasonably infrequent messages​. Using this option may result in more packets being sent than would normally be necessary​.

-o config-file

Provide a path to a config file to load options from​. The config file should have one pair of -option value per line​. The values in the config file will be used as defaults and can be overridden by using the command line​. The exceptions to this are the message type options, of which only one can be specified​. Note also that currently some options cannot be negated, e​.g​. -S​. Config file lines that have a # as the first character are treated as comments and not processed any further​.

-p,  --port

Connect to the port specified​. If not given, the default of 1883 for plain MQTT or 8883 for MQTT over TLS will be used​.

-P,  --pw

Provide a password to be used for authenticating with the broker​. Using this argument without also specifying a username is invalid when using MQTT v3​.1 or v3​.1​.1​.

See also the --username option​.

--proxy

Specify a SOCKS5 proxy to connect through​. "None" and "username" authentication types are supported​. The socks-url must be of the form socks5h://[username[:password]@]host[:port]​. The protocol prefix socks5h means that hostnames are resolved by the proxy​. The symbols %25, %3A and %40 are URL decoded into %, : and @ respectively, if present in the username or password​.

If username is not given, then no authentication is attempted​. If the port is not given, then the default of 1080 is used​.

If the host is given as an IPv6 address, it must be enclosed in square brackets, e​.g​. socks5h://[::1]:1080​. Note that square brackets have special meaning in some shells, so the proxy url may need quoting in double or single quotes​.

More SOCKS versions may be available in the future, depending on demand, and will use different protocol prefixes as described in curl(1)​.

--psk

Provide the hexadecimal (no leading 0x) pre-shared-key matching the one used on the broker to use TLS-PSK encryption support​. --psk-identity must also be provided to enable TLS-PSK​.

--psk-identity

The client identity to use with TLS-PSK support​. This may be used instead of a username if the broker is configured to do so​.

-q,  --qos

Specify the quality of service to use for messages, from 0, 1 and 2​. Defaults to 1​.

--quiet

If this argument is given, no runtime errors will be printed​. This excludes any error messages given in case of invalid user input (e​.g​. using --port without a port)​.

--tls-alpn

Provide a protocol to use when connecting to a broker that has multiple protocols available on a single port, e​.g​. MQTT and WebSockets​.

--tls-engine

A valid openssl engine id​. These can be listed with the openssl engine command​.

See also --keyform​.

--tls-engine-kpass-sha1

SHA1 of the private key password when using an TLS engine​. Some TLS engines such as the TPM engine may require the use of a password in order to be accessed​. This option allows a hex encoded SHA1 hash of the password to the engine directly, instead of the user being prompted for the password​.

See also --tls-engine​.

--tls-use-os-certs

If used, this will load and trust the OS provided CA certificates​. This can be used in conjunction with --cafile and --capath and can be used on its own to enable TLS mode​. This will be set by default if -L mqtts://​.​.​. is used, or if port is 8883 and no other certificate options are used​.

--tls-version

Choose which TLS protocol version to use when communicating with the broker​. Valid options are tlsv1​.3 and tlsv1​.2​. The default value is tlsv1​.2​. Must match the protocol version used by the broker​.

-u,  --username

Provide a username to be used for authenticating with the broker​.

See also the --pw argument​.

--unix

Connect to a broker through a local unix domain socket instead of a TCP socket​. This is a replacement for -h and -L​. For example: mosquitto_ctrl --unix /tmp/mosquitto​.sock ​.​.​.

See the socket_domain option in mosquitto​.conf(5) to configure Mosquitto to listen on a unix socket​.

-V,  --protocol-version

Specify which version of the MQTT protocol should be used when connecting to the remote broker​. Can be 5, 311, 31, or the more verbose mqttv5, mqttv311, or mqttv31​. Defaults to 311​.

Properties

The -D / --property option allows adding properties to different stages of the mosquitto_ctrl run​. The properties supported for each command are as follows:

Connect

  • authentication-data (binary data - note treated as a string)
  • authentication-method (UTF-8 string pair)
  • maximum-packet-size (32-bit unsigned integer)
  • receive-maximum (16-bit unsigned integer)
  • request-problem-information (8-bit unsigned integer)
  • request-response-information (8-bit unsigned integer)
  • session-expiry-interval (32-bit unsigned integer, note use -x instead)
  • topic-alias-maximum (16-bit unsigned integer)
  • user-property (UTF-8 string pair)

Publish

  • content-type (UTF-8 string)
  • correlation-data (binary data - note treated as a string)
  • message-expiry-interval (32-bit unsigned integer)
  • payload-format-indicator (8-bit unsigned integer)
  • response-topic (UTF-8 string)
  • topic-alias (16-bit unsigned integer)
  • user-property (UTF-8 string pair)

Disconnect

  • session-expiry-interval (32-bit unsigned integer)
  • user-property (UTF-8 string pair)

Will properties

  • content-type (UTF-8 string)
  • correlation-data (binary data - note treated as a string)
  • message-expiry-interval (32-bit unsigned integer)
  • payload-format-indicator (8-bit unsigned integer)
  • response-topic (UTF-8 string)
  • user-property (UTF-8 string pair)
  • will-delay-interval (32-bit unsigned integer)

Exit Status

Zero on success, or non-zero on error​. If the connection is refused by the broker at the MQTT level, then the exit code is the CONNACK reason code​. If another error occurs, the exit code is a libmosquitto return value​.

MQTT v3​.1​.1 CONNACK codes:

MQTT v5 CONNACK codes:

Other codes:

Environment Variables

MOSQUITTO_UNSAFE_ALLOW_SYMLINKS

By default, sensitive file with a path including a symbolic link will be refused to be loaded​. Set this environment variable to any value to allow load files through symbolic links​. Note that making use of this variable could expose you to symlink attacks and so it should only be used in cases where you are absolutely sure this is not a risk​.

Bugs

mosquitto bug information can be found at https://github.com/eclipse-mosquitto/mosquitto/issues

See Also

mosquitto(7), mqtt(7), mosquitto_ctrl_shell(1), mosquitto_rr(1), mosquitto_pub(1), mosquitto_sub(1), mosquitto(8), libmosquitto(3), mosquitto-tls(7)

Author

Roger Light <roger@atchoo​.org>

Info

11/18/2026 Mosquitto Project Commands