1MOSQUITTO_CTRL(1) Commands MOSQUITTO_CTRL(1)
2
6 mosquitto_ctrl - a tool for initialising/configuring a Mosquitto broker
7 instance
8
10 mosquitto_ctrl [connection-options | -o config-file] module-name
11 module-command [command-options]
12 connection-options:
14 {[-h hostname] [--unix socket path] [-p port-number] [-u username] [-P password]
15 | -L URL} [-A bind-address] [-c] [-d]
16 [-i client-id] [-q message-QoS] [--quiet]
17 [-V protocol-version]
18 [[{--cafile file | --capath dir} [--cert file] [--key file] [--ciphers ciphers] [--tls-version version] [--tls-alpn protocol] [--tls-engine engine] [--keyform {pem | engine}] [--tls-engine-kpass-sha1 kpass-sha1] [--insecure]]
19 |
20 [--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]]]
21 [--proxy socks-url]
22 mosquitto_ctrl [--help]
24
26 mosquitto_ctrl is a tool for helping configure a Mosquitto broker
27 instance.
28
30 mosquitto_ctrl supports TLS encrypted connections. It is strongly
31 recommended that you use an encrypted connection for all remote use of
32 mosquitto_ctrl.
33 To enable TLS connections when using x509 certificates, one of either
35 --cafile or --capath must be provided as an option.
36 To enable TLS connections when using TLS-PSK, you must use the --psk
38 and the --psk-identity options.
39
41 Dynamic security
42 Authentication, and role based access control with users and
43 groups. Uses the dynsec module name. See: mosquitto_ctrl_dynsec(1)
44 External modules
46 mosquitto_ctrl has the ability to load external modules in the form
47 of shared libraries. For example using the module name example will
48 try to load the external module mosquitto_ctrl_example.so or
49 mosquitto_ctrl_example.dll, depending on platform. This allows new
50 functionality to be added to Mosquitto by combining a plugin and
51 mosquitto_ctrl module, without having to recompile any Mosquitto
52 source code.
53
55 The options below may be given on the command line, but may also be
56 placed in a config file located at $XDG_CONFIG_HOME/mosquitto_ctrl or
57 $HOME/.config/mosquitto_ctrl.
58 The config file may be specified manually with the -o config-file
60 option.
61 The config file should have one pair of -option value per line. The
63 values in the config file will be used as defaults and can be
64 overridden by using the command line. The exceptions to this are the
65 message type options, of which only one can be specified. Note also
66 that currently some options cannot be negated, e.g. -S. Config file
67 lines that have a # as the first character are treated as comments and
68 not processed any further.
69 -A
71 Bind the outgoing connection to a local ip address/hostname. Use
72 this argument if you need to restrict network communication to a
73 particular interface.
74 --cafile
76 Define the path to a file containing PEM encoded CA certificates
77 that are trusted. Used to enable SSL communication.
78 See also --capath
80 --capath
82 Define the path to a directory containing PEM encoded CA
83 certificates that are trusted. Used to enable SSL communication.
84 For --capath to work correctly, the certificate files must have
86 ".crt" as the file ending and you must run "openssl rehash <path to
87 capath>" each time you add/remove a certificate.
88 See also --cafile
90 --cert
92 Define the path to a file containing a PEM encoded certificate for
93 this client, if required by the server.
94 See also --key.
96 --ciphers
98 An openssl compatible list of TLS ciphers to support in the client.
99 See ciphers(1) for more information.
100 -d, --debug
102 Enable debug messages.
103 -D, --property
105 Use an MQTT v5 property with this publish. If you use this option,
106 the client will be set to be an MQTT v5 client. This option has two
107 forms:
108 -D command identifier value
110 -D command identifier name value
112 command is the MQTT command/packet identifier and can be one of
114 CONNECT, PUBLISH, PUBREL, DISCONNECT, AUTH, or WILL. The properties
115 available for each command are listed in the Properties section.
116 identifier is the name of the property to add. This is as described
118 in the specification, but with '-' as a word separator. For
119 example: payload-format-indicator. More details are in the
120 Properties section.
121 value is the value of the property to add, with a data type that is
123 property specific.
124 name is only used for the user-property property as the first of
126 the two strings in the string pair. In that case, value is the
127 second of the strings in the pair.
128 --help
130 Display usage information.
131 -h, --host
133 Specify the host to connect to. Defaults to localhost.
134 -i, --id
136 The id to use for this client. If not given, a client id will be
137 generated depending on the MQTT version being used. For
138 v3.1.1/v3.1, the client generates a client id in the format
139 mosq-XXXXXXXXXXXXXXXXXX, where the X are replaced with random
140 alphanumeric characters. For v5.0, the client sends a zero length
141 client id, and the server will generate a client id for the client.
142 This option cannot be used at the same time as the --id-prefix
144 argument.
145 --insecure
147 When using certificate based encryption, this option disables
148 verification of the server hostname in the server certificate. This
149 can be useful when testing initial server configurations but makes
150 it possible for a malicious third party to impersonate your server
151 through DNS spoofing, for example. Use this option in testing only.
152 If you need to resort to using this option in a production
153 environment, your setup is at fault and there is no point using
154 encryption.
155 --key
157 Define the path to a file containing a PEM encoded private key for
158 this client, if required by the server.
159 See also --cert.
161 --keyform
163 Specifies the type of private key in use when making TLS
164 connections.. This can be "pem" or "engine". This parameter is
165 useful when a TPM module is being used and the private key has been
166 created with it. Defaults to "pem", which means normal private key
167 files are used.
168 See also --tls-engine.
170 -L, --url
172 Specify specify user, password, hostname, port and topic at once as
173 a URL. The URL must be in the form:
174 mqtt(s)://[username[:password]@]host[:port]/topic
175 If the scheme is mqtt:// then the port defaults to 1883. If the
177 scheme is mqtts:// then the port defaults to 8883.
178 --nodelay
180 Disable Nagle's algorithm for the socket. This means that latency
181 of sent messages is reduced, which is particularly noticeable for
182 small, reasonably infrequent messages. Using this option may result
183 in more packets being sent than would normally be necessary.
184 -o config-file
186 Provide a path to a config file to load options from. The config
187 file should have one pair of -option value per line. The values in
188 the config file will be used as defaults and can be overridden by
189 using the command line. The exceptions to this are the message type
190 options, of which only one can be specified. Note also that
191 currently some options cannot be negated, e.g. -S. Config file
192 lines that have a # as the first character are treated as comments
193 and not processed any further.
194 -p, --port
196 Connect to the port specified. If not given, the default of 1883
197 for plain MQTT or 8883 for MQTT over TLS will be used.
198 -P, --pw
200 Provide a password to be used for authenticating with the broker.
201 Using this argument without also specifying a username is invalid
202 when using MQTT v3.1 or v3.1.1. See also the --username option.
203 --proxy
205 Specify a SOCKS5 proxy to connect through. "None" and "username"
206 authentication types are supported. The socks-url must be of the
207 form socks5h://[username[:password]@]host[:port]. The protocol
208 prefix socks5h means that hostnames are resolved by the proxy. The
209 symbols %25, %3A and %40 are URL decoded into %, : and @
210 respectively, if present in the username or password.
211 If username is not given, then no authentication is attempted. If
213 the port is not given, then the default of 1080 is used.
214 More SOCKS versions may be available in the future, depending on
216 demand, and will use different protocol prefixes as described in
217 curl(1).
218 --psk
220 Provide the hexadecimal (no leading 0x) pre-shared-key matching the
221 one used on the broker to use TLS-PSK encryption support.
222 --psk-identity must also be provided to enable TLS-PSK.
223 --psk-identity
225 The client identity to use with TLS-PSK support. This may be used
226 instead of a username if the broker is configured to do so.
227 -q, --qos
229 Specify the quality of service to use for messages, from 0, 1 and
230 2. Defaults to 1.
231 --quiet
233 If this argument is given, no runtime errors will be printed. This
234 excludes any error messages given in case of invalid user input
235 (e.g. using --port without a port).
236 --tls-alpn
238 Provide a protocol to use when connecting to a broker that has
239 multiple protocols available on a single port, e.g. MQTT and
240 WebSockets.
241 --tls-engine
243 A valid openssl engine id. These can be listed with openssl engine
244 command.
245 See also --keyform.
247 --tls-engine-kpass-sha1
249 SHA1 of the private key password when using an TLS engine. Some TLS
250 engines such as the TPM engine may require the use of a password in
251 order to be accessed. This option allows a hex encoded SHA1 hash of
252 the password to the engine directly, instead of the user being
253 prompted for the password.
254 See also --tls-engine.
256 --tls-version
258 Choose which TLS protocol version to use when communicating with
259 the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
260 default value is tlsv1.2. Must match the protocol version used by
261 the broker.
262 -u, --username
264 Provide a username to be used for authenticating with the broker.
265 See also the --pw argument.
266 --unix
268 Connect to a broker through a local unix domain socket instead of a
269 TCP socket. This is a replacement for -h and -L. For example:
270 mosquitto_ctrl --unix /tmp/mosquitto.sock ...
271 See the socket_domain option in mosquitto.conf[1m(5) to configure
273 Mosquitto to listen on a unix socket.
274 -V, --protocol-version
276 Specify which version of the MQTT protocol should be used when
277 connecting to the rmeote broker. Can be 5, 311, 31, or the more
278 verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
279
281 The -D / --property option allows adding properties to different stages
282 of the mosquitto_ctrl run. The properties supported for each command
283 are as follows:
284 Connect
286 • authentication-data (binary data - note treated as a string in
287 mosquitto_ctrl)
288 • authentication-method (UTF-8 string pair)
290 • maximum-packet-size (32-bit unsigned integer)
292 • receive-maximum (16-bit unsigned integer)
294 • request-problem-information (8-bit unsigned integer)
296 • request-response-information (8-bit unsigned integer)
298 • session-expiry-interval (32-bit unsigned integer, note use -x
300 instead)
301 • topic-alias-maximum (16-bit unsigned integer)
303 • user-property (UTF-8 string pair)
305 Publish
307 • content-type (UTF-8 string)
308 • correlation-data (binary data - note treated as a string in
310 mosquitto_ctrl)
311 • message-expiry-interval (32-bit unsigned integer)
313 • payload-format-indicator (8-bit unsigned integer)
315 • response-topic (UTF-8 string)
317 • topic-alias (16-bit unsigned integer)
319 • user-property (UTF-8 string pair)
321 Disconnect
323 • session-expiry-interval (32-bit unsigned integer)
324 • user-property (UTF-8 string pair)
326 Will properties
328 • content-type (UTF-8 string)
329 • correlation-data (binary data - note treated as a string in
331 mosquitto_ctrl)
332 • message-expiry-interval (32-bit unsigned integer)
334 • payload-format-indicator (8-bit unsigned integer)
336 • response-topic (UTF-8 string)
338 • user-property (UTF-8 string pair)
340 • will-delay-interval (32-bit unsigned integer)
342
344 mosquitto_sub returns zero on success, or non-zero on error. If the
345 connection is refused by the broker at the MQTT level, then the exit
346 code is the CONNACK reason code. If another error occurs, the exit code
347 is a libmosquitto return value.
348 MQTT v3.1.1 CONNACK codes:
350 • 0 Success
352 • 1 Connection refused: Bad protocol version
354 • 2 Connection refused: Identifier rejected
356 • 3 Connection refused: Server unavailable
358 • 4 Connection refused: Bad username/password
360 • 5 Connection refused: Not authorized
362 MQTT v5 CONNACK codes:
364 • 0 Success
366 • 128 Unspecified error
368 • 129 Malformed packet
370 • 130 Protocol error
372 • 131 Implementation specific error
374 • 132 Unsupported protocol version
376 • 133 Client ID not valid
378 • 134 Bad username or password
380 • 135 Not authorized
382 • 136 Server unavailable
384 • 137 Server busy
386 • 138 Banned
388 • 139 Server shutting down
390 • 140 Bad authentication method
392 • 141 Keep alive timeout
394 • 142 Session taken over
396 • 143 Topic filter invalid
398 • 144 Topic name invalid
400 • 147 Receive maximum exceeded
402 • 148 Topic alias invalid
404 • 149 Packet too large
406 • 148 Message rate too high
408 • 151 Quota exceeded
410 • 152 Administrative action
412 • 153 Payload format invalid
414 • 154 Retain not supported
416 • 155 QoS not supported
418 • 156 Use another server
420 • 157 Server moved
422 • 158 Shared subscriptions not supported
424 • 159 Connection rate exceeded
426 • 160 Maximum connect time
428 • 161 Subscription IDs not supported
430 • 162 Wildcard subscriptions not supported
432
434 mosquitto bug information can be found at
435 https://github.com/eclipse/mosquitto/issues
436
438 mqtt(7), mosquitto_rr(1), mosquitto_pub(1), mosquitto_sub(1),
439 mosquitto(8), libmosquitto(3), mosquitto-tls(7)
440
442 Roger Light <roger@atchoo.org>
443Mosquitto Project 09/18/2023 MOSQUITTO_CTRL(1)