1MOSQUITTO_CTRL(1)                  Commands                  MOSQUITTO_CTRL(1)
2
3
4

NAME

6       mosquitto_ctrl - a tool for initialising/configuring a Mosquitto broker
7       instance
8

SYNOPSIS

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

DESCRIPTION

26       mosquitto_ctrl is a tool for helping configure a Mosquitto broker
27       instance.
28

ENCRYPTED CONNECTIONS

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

MODULES

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

CONNECTION OPTIONS

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(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

PROPERTIES

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
286authentication-data (binary data - note treated as a string in
287           mosquitto_ctrl)
288
289authentication-method (UTF-8 string pair)
290
291maximum-packet-size (32-bit unsigned integer)
292
293receive-maximum (16-bit unsigned integer)
294
295request-problem-information (8-bit unsigned integer)
296
297request-response-information (8-bit unsigned integer)
298
299session-expiry-interval (32-bit unsigned integer, note use -x
300           instead)
301
302topic-alias-maximum (16-bit unsigned integer)
303
304user-property (UTF-8 string pair)
305
306   Publish
307content-type (UTF-8 string)
308
309correlation-data (binary data - note treated as a string in
310           mosquitto_ctrl)
311
312message-expiry-interval (32-bit unsigned integer)
313
314payload-format-indicator (8-bit unsigned integer)
315
316response-topic (UTF-8 string)
317
318topic-alias (16-bit unsigned integer)
319
320user-property (UTF-8 string pair)
321
322   Disconnect
323session-expiry-interval (32-bit unsigned integer)
324
325user-property (UTF-8 string pair)
326
327   Will properties
328content-type (UTF-8 string)
329
330correlation-data (binary data - note treated as a string in
331           mosquitto_ctrl)
332
333message-expiry-interval (32-bit unsigned integer)
334
335payload-format-indicator (8-bit unsigned integer)
336
337response-topic (UTF-8 string)
338
339user-property (UTF-8 string pair)
340
341will-delay-interval (32-bit unsigned integer)
342

EXIT STATUS

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
3510 Success
352
3531 Connection refused: Bad protocol version
354
3552 Connection refused: Identifier rejected
356
3573 Connection refused: Server unavailable
358
3594 Connection refused: Bad username/password
360
3615 Connection refused: Not authorized
362
363       MQTT v5 CONNACK codes:
364
3650 Success
366
367128 Unspecified error
368
369129 Malformed packet
370
371130 Protocol error
372
373131 Implementation specific error
374
375132 Unsupported protocol version
376
377133 Client ID not valid
378
379134 Bad username or password
380
381135 Not authorized
382
383136 Server unavailable
384
385137 Server busy
386
387138 Banned
388
389139 Server shutting down
390
391140 Bad authentication method
392
393141 Keep alive timeout
394
395142 Session taken over
396
397143 Topic filter invalid
398
399144 Topic name invalid
400
401147 Receive maximum exceeded
402
403148 Topic alias invalid
404
405149 Packet too large
406
407148 Message rate too high
408
409151 Quota exceeded
410
411152 Administrative action
412
413153 Payload format invalid
414
415154 Retain not supported
416
417155 QoS not supported
418
419156 Use another server
420
421157 Server moved
422
423158 Shared subscriptions not supported
424
425159 Connection rate exceeded
426
427160 Maximum connect time
428
429161 Subscription IDs not supported
430
431162 Wildcard subscriptions not supported
432

BUGS

434       mosquitto bug information can be found at
435       https://github.com/eclipse/mosquitto/issues
436

SEE ALSO

438       mqtt(7), mosquitto_rr(1), mosquitto_pub(1), mosquitto_sub(1),
439       mosquitto(8), libmosquitto(3), mosquitto-tls(7)
440

AUTHOR

442       Roger Light <roger@atchoo.org>
443
444
445
446Mosquitto Project                 08/16/2022                 MOSQUITTO_CTRL(1)
Impressum