1MOSQUITTO_CTRL(1) Commands MOSQUITTO_CTRL(1)
2
3
4
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
13 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
23 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
34 To enable TLS connections when using x509 certificates, one of either
35 --cafile or --capath must be provided as an option.
36
37 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
45 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
59 The config file may be specified manually with the -o config-file
60 option.
61
62 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
70 -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
75 --cafile
76 Define the path to a file containing PEM encoded CA certificates
77 that are trusted. Used to enable SSL communication.
78
79 See also --capath
80
81 --capath
82 Define the path to a directory containing PEM encoded CA
83 certificates that are trusted. Used to enable SSL communication.
84
85 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
89 See also --cafile
90
91 --cert
92 Define the path to a file containing a PEM encoded certificate for
93 this client, if required by the server.
94
95 See also --key.
96
97 --ciphers
98 An openssl compatible list of TLS ciphers to support in the client.
99 See ciphers(1) for more information.
100
101 -d, --debug
102 Enable debug messages.
103
104 -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
109 -D command identifier value
110
111 -D command identifier name value
112
113 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
117 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
122 value is the value of the property to add, with a data type that is
123 property specific.
124
125 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
129 --help
130 Display usage information.
131
132 -h, --host
133 Specify the host to connect to. Defaults to localhost.
134
135 -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
143 This option cannot be used at the same time as the --id-prefix
144 argument.
145
146 --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
156 --key
157 Define the path to a file containing a PEM encoded private key for
158 this client, if required by the server.
159
160 See also --cert.
161
162 --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
169 See also --tls-engine.
170
171 -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
176 If the scheme is mqtt:// then the port defaults to 1883. If the
177 scheme is mqtts:// then the port defaults to 8883.
178
179 --nodelay
180 Disable Nagle's algorithm for the socket. This means that latency
181 of sent messages is reduced, which is particularly noticable for
182 small, reasonably infrequent messages. Using this option may result
183 in more packets being sent than would normally be necessary.
184
185 -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
195 -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
199 -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
204 --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
212 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
215 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
219 --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
224 --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
228 -q, --qos
229 Specify the quality of service to use for messages, from 0, 1 and
230 2. Defaults to 1.
231
232 --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
237 --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
242 --tls-engine
243 A valid openssl engine id. These can be listed with openssl engine
244 command.
245
246 See also --keyform.
247
248 --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
255 See also --tls-engine.
256
257 --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
263 -u, --username
264 Provide a username to be used for authenticating with the broker.
265 See also the --pw argument.
266
267 --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
272 See the socket_domain option in mosquitto.conf[1m(5) to configure
273 Mosquitto to listen on a unix socket.
274
275 -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
285 Connect
286 • authentication-data (binary data - note treated as a string in
287 mosquitto_ctrl)
288
289 • authentication-method (UTF-8 string pair)
290
291 • maximum-packet-size (32-bit unsigned integer)
292
293 • receive-maximum (16-bit unsigned integer)
294
295 • request-problem-information (8-bit unsigned integer)
296
297 • request-response-information (8-bit unsigned integer)
298
299 • session-expiry-interval (32-bit unsigned integer, note use -x
300 instead)
301
302 • topic-alias-maximum (16-bit unsigned integer)
303
304 • user-property (UTF-8 string pair)
305
306 Publish
307 • content-type (UTF-8 string)
308
309 • correlation-data (binary data - note treated as a string in
310 mosquitto_ctrl)
311
312 • message-expiry-interval (32-bit unsigned integer)
313
314 • payload-format-indicator (8-bit unsigned integer)
315
316 • response-topic (UTF-8 string)
317
318 • topic-alias (16-bit unsigned integer)
319
320 • user-property (UTF-8 string pair)
321
322 Disconnect
323 • session-expiry-interval (32-bit unsigned integer)
324
325 • user-property (UTF-8 string pair)
326
327 Will properties
328 • content-type (UTF-8 string)
329
330 • correlation-data (binary data - note treated as a string in
331 mosquitto_ctrl)
332
333 • message-expiry-interval (32-bit unsigned integer)
334
335 • payload-format-indicator (8-bit unsigned integer)
336
337 • response-topic (UTF-8 string)
338
339 • user-property (UTF-8 string pair)
340
341 • 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
349 MQTT v3.1.1 CONNACK codes:
350
351 • 0 Success
352
353 • 1 Connection refused: Bad protocol version
354
355 • 2 Connection refused: Identifier rejected
356
357 • 3 Connection refused: Server unavailable
358
359 • 4 Connection refused: Bad username/password
360
361 • 5 Connection refused: Not authorized
362
363 MQTT v5 CONNACK codes:
364
365 • 0 Success
366
367 • 128 Unspecified error
368
369 • 129 Malformed packet
370
371 • 130 Protocol error
372
373 • 131 Implementation specific error
374
375 • 132 Unsupported protocol version
376
377 • 133 Client ID not valid
378
379 • 134 Bad username or password
380
381 • 135 Not authorized
382
383 • 136 Server unavailable
384
385 • 137 Server busy
386
387 • 138 Banned
388
389 • 139 Server shutting down
390
391 • 140 Bad authentication method
392
393 • 141 Keep alive timeout
394
395 • 142 Session taken over
396
397 • 143 Topic filter invalid
398
399 • 144 Topic name invalid
400
401 • 147 Receive maximum exceeded
402
403 • 148 Topic alias invalid
404
405 • 149 Packet too large
406
407 • 148 Message rate too high
408
409 • 151 Quota exceeded
410
411 • 152 Administrative action
412
413 • 153 Payload format invalid
414
415 • 154 Retain not supported
416
417 • 155 QoS not supported
418
419 • 156 Use another server
420
421 • 157 Server moved
422
423 • 158 Shared subscriptions not supported
424
425 • 159 Connection rate exceeded
426
427 • 160 Maximum connect time
428
429 • 161 Subscription IDs not supported
430
431 • 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>
443
444
445
446Mosquitto Project 08/16/2022 MOSQUITTO_CTRL(1)