1MOSQUITTO_SUB(1) Commands MOSQUITTO_SUB(1)
2
6 mosquitto_sub - an MQTT version 5/3.1.1/3.1 client for subscribing to
7 topics
8
10 mosquitto_sub
11 {[-h hostname] [-p port-number] [ [-u username] [-P password] ] -t message-topic...
12 | -L URL [-t message-topic...] } [-A bind-address] [-c]
13 [-C msg-count] [-d] [-D command identifier value] [-E]
14 [-i client-id] [-I client-id-prefix] [-k keepalive-time]
15 [-N] [-q message-QoS] [--remove-retained] [-R |
16 --retained-only] [--retain-as-published] [-S]
17 [-T filter-out...] [-U unsub-topic...] [-v]
18 [-V protocol-version] [-W message-processing-timeout]
19 [--proxy socks-url] [--quiet]
20 [--will-topic topic [--will-payload payload] [--will-qos qos] [--will-retain]]
21 [[{--cafile file | --capath dir} [--cert file] [--key file] [--tls-version version] [--tls-alpn protocol] [--tls-engine engine] [--keyform {pem | engine}] [--tls-engine-kpass-sha1 kpass-sha1] [--insecure]]
22 |
23 [--psk hex-key --psk-identity identity [--tls-version version]]]
24 mosquitto_sub [--help]
26
28 mosquitto_sub is a simple MQTT version 5/3.1.1 client that will
29 subscribe to topics and print the messages that it receives.
30 In addition to subscribing to topics, mosquitto_sub can filter out
32 received messages so they are not printed (see the -T option) or
33 unsubscribe from topics (see the -U option). Unsubscribing from topics
34 is useful for clients connecting with clean session set to false.
35
37 mosquitto_sub supports TLS encrypted connections. It is strongly
38 recommended that you use an encrypted connection for anything more than
39 the most basic setup.
40 To enable TLS connections when using x509 certificates, one of either
42 --cafile or --capath must be provided as an option.
43 To enable TLS connections when using TLS-PSK, you must use the --psk
45 and the --psk-identity options.
46
48 The options below may be given on the command line, but may also be
49 placed in a config file located at $XDG_CONFIG_HOME/mosquitto_sub or
50 $HOME/.config/mosquitto_sub with one pair of -option value per line.
51 The values in the config file will be used as defaults and can be
52 overridden by using the command line. The exceptions to this are -t and
53 -T, which if given in the config file will not be overridden. Note also
54 that currently some options cannot be negated, e.g. -S. Config file
55 lines that have a # as the first character are treated as comments and
56 not processed any further.
57 -A
59 Bind the outgoing connection to a local ip address/hostname. Use
60 this argument if you need to restrict network communication to a
61 particular interface.
62 -c, --disable-clean-session
64 Disable the 'clean session' flag. This means that all of the
65 subscriptions for the client will be maintained after it
66 disconnects, along with subsequent QoS 1 and QoS 2 messages that
67 arrive. When the client reconnects, it will receive all of the
68 queued messages.
69 If using this option, the client id must be set manually with --id
71 --cafile
73 Define the path to a file containing PEM encoded CA certificates
74 that are trusted. Used to enable SSL communication.
75 See also --capath
77 --capath
79 Define the path to a directory containing PEM encoded CA
80 certificates that are trusted. Used to enable SSL communication.
81 For --capath to work correctly, the certificate files must have
83 ".crt" as the file ending and you must run "openssl rehash <path to
84 capath>" each time you add/remove a certificate.
85 See also --cafile
87 --cert
89 Define the path to a file containing a PEM encoded certificate for
90 this client, if required by the server.
91 See also --key.
93 --ciphers
95 An openssl compatible list of TLS ciphers to support in the client.
96 See ciphers(1) for more information.
97 -C
99 Disconnect and exit the program immediately after the given count
100 of messages have been received. This may be useful in shell scripts
101 where on a single status value is required, for example.
102 Combine with -R to print only the first set of fresh messages (i.e.
104 that does not have the retained flag set), or with -T to filter
105 which topics are processed.
106 -d, --debug
108 Enable debug messages.
109 -D, --property
111 Use an MQTT v5 property with this publish. If you use this option,
112 the client will be set to be an MQTT v5 client. This option has two
113 forms:
114 -D command identifier value
116 -D command identifier name value
118 command is the MQTT command/packet identifier and can be one of
120 CONNECT, PUBACK, PUBREC, PUBCOMP, SUBSCRIBE, UNSUBSCRIBE,
121 DISCONNECT, AUTH, or WILL. The properties available for each
122 command are listed in the Properties section.
123 identifier is the name of the property to add. This is as described
125 in the specification, but with '-' as a word separator. For
126 example: payload-format-indicator. More details are in the
127 Properties section.
128 value is the value of the property to add, with a data type that is
130 property specific.
131 name is only used for the user-property property as the first of
133 the two strings in the string pair. In that case, value is the
134 second of the strings in the pair.
135 -E
137 If this option is given, mosquitto_sub will exit immediately that
138 all of its subscriptions have been acknowledged by the broker. In
139 conjunction with -c this allows a durable client session to be
140 initialised on the broker for future use without requiring any
141 messages to be received.
142 -F
144 Specify output printing format. This option allows you to choose
145 what information from each message is printed to the screen. See
146 the Output Format section below for full details.
147 This option overrides the -v option, but does not override the -N
149 option.
150 --help
152 Display usage information.
153 -h, --host
155 Specify the host to connect to. Defaults to localhost.
156 -i, --id
158 The id to use for this client. If not given, defaults to
159 mosquitto_sub_ appended with the process id of the client. Cannot
160 be used at the same time as the --id-prefix argument.
161 -I, --id-prefix
163 Provide a prefix that the client id will be built from by appending
164 the process id of the client. This is useful where the broker is
165 using the clientid_prefixes option. Cannot be used at the same time
166 as the --id argument.
167 --insecure
169 When using certificate based encryption, this option disables
170 verification of the server hostname in the server certificate. This
171 can be useful when testing initial server configurations but makes
172 it possible for a malicious third party to impersonate your server
173 through DNS spoofing, for example. Use this option in testing only.
174 If you need to resort to using this option in a production
175 environment, your setup is at fault and there is no point using
176 encryption.
177 -k, --keepalive
179 The number of seconds between sending PING commands to the broker
180 for the purposes of informing it we are still connected and
181 functioning. Defaults to 60 seconds.
182 --key
184 Define the path to a file containing a PEM encoded private key for
185 this client, if required by the server.
186 See also --cert.
188 --keyform
190 Specifies the type of private key in use when making TLS
191 connections.. This can be "pem" or "engine". This parameter is
192 useful when a TPM module is being used and the private key has been
193 created with it. Defaults to "pem", which means normal private key
194 files are used.
195 See also --tls-engine.
197 -L, --url
199 Specify specify user, password, hostname, port and topic at once as
200 a URL. The URL must be in the form:
201 mqtt(s)://[username[:password]@]host[:port]/topic
202 If the scheme is mqtt:// then the port defaults to 1883. If the
204 scheme is mqtts:// then the port defaults to 8883.
205 -N
207 Do not append an end of line character to the payload when
208 printing. This allows streaming of payload data from multiple
209 messages directly to another application unmodified. Only really
210 makes sense when not using -v.
211 -p, --port
213 Connect to the port specified. If not given, the default of 1883
214 for plain MQTT or 8883 for MQTT over TLS will be used.
215 -P, --pw
217 Provide a password to be used for authenticating with the broker.
218 Using this argument without also specifying a username is invalid.
219 See also the --username option.
220 --proxy
222 Specify a SOCKS5 proxy to connect through. "None" and "username"
223 authentication types are supported. The socks-url must be of the
224 form socks5h://[username[:password]@]host[:port]. The protocol
225 prefix socks5h means that hostnames are resolved by the proxy. The
226 symbols %25, %3A and %40 are URL decoded into %, : and @
227 respectively, if present in the username or password.
228 If username is not given, then no authentication is attempted. If
230 the port is not given, then the default of 1080 is used.
231 More SOCKS versions may be available in the future, depending on
233 demand, and will use different protocol prefixes as described in
234 curl(1).
235 --psk
237 Provide the hexadecimal (no leading 0x) pre-shared-key matching the
238 one used on the broker to use TLS-PSK encryption support.
239 --psk-identity must also be provided to enable TLS-PSK.
240 --psk-identity
242 The client identity to use with TLS-PSK support. This may be used
243 instead of a username if the broker is configured to do so.
244 -q, --qos
246 Specify the quality of service desired for the incoming messages,
247 from 0, 1 and 2. Defaults to 0. See mqtt(7) for more information on
248 QoS.
249 The QoS is identical for all topics subscribed to in a single
251 instance of mosquitto_sub.
252 --quiet
254 If this argument is given, no runtime errors will be printed. This
255 excludes any error messages given in case of invalid user input
256 (e.g. using --port without a port).
257 -R
259 If this argument is given, messages that are received that have the
260 retain bit set will not be printed. Messages with retain set are
261 "stale", in that it is not known when they were originally
262 published. When subscribing to a wildcard topic there may be a
263 large number of retained messages. This argument suppresses their
264 display.
265 --remove-retained
267 If this argument is given, the when mosquitto_sub receives a
268 message with the retained bit set, it will send a message to the
269 broker to clear that retained message. This applies to all received
270 messages except those that are filtered out by the -T option. This
271 option still takes effect even if -R is used. See also the
272 --retain-as-published and --retained-only options.
273 Example 1. Remove all retained messages on the server, assuming we
275 have access to do so, and then exit:
276 mosquitto_sub -t '#' --remove-retained --retained-only
278 Example 2. Remove a whole tree, with the exception of a single
280 topic:
281 mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained
283 --retained-only
285 If this argument is given, only messages that are received that
286 have the retain bit set will be printed. Messages with retain set
287 are "stale", in that it is not known when they were originally
288 published. With this argument in use, the receipt of the first
289 non-stale message will cause the client to exit. See also the
290 --retain-as-published option.
291 --retain-as-published
293 If this argument is given, the subscriptions will have the "retain
294 as published" option set. This means that the retain flag on an
295 incoming message will be exactly as set by the publishing client,
296 rather than indicating whether the message is fresh/stale.
297 This option is not valid for MQTT v3.1/v3.1.1 clients.
299 -S
301 Use SRV lookups to determine which host to connect to. Performs
302 lookups to _mqtt._tcp.<host> when used in conjunction with -h,
303 otherwise uses _mqtt._tcp.<local dns domain>.
304 -t, --topic
306 The MQTT topic to subscribe to. See mqtt(7) for more information on
307 MQTT topics.
308 This option may be repeated to subscribe to multiple topics.
310 -T, --filter-out
312 Suppress printing of topics that match the filter. This allows
313 subscribing to a wildcard topic and only printing a partial set of
314 the wildcard hierarchy.
315 For example, subscribe to the BBC tree, but suppress output from
317 Radio 3:
318 · mosquitto_sub -t bbc/# -T bbc/radio3
320 This option may be repeated to filter out multiple topics or topic
322 trees.
323 --tls-alpn
325 Provide a protocol to use when connecting to a broker that has
326 multiple protocols available on a single port, e.g. MQTT and
327 WebSockets.
328 --tls-engine
330 A valid openssl engine id. These can be listed with openssl engine
331 command.
332 See also --keyform.
334 --tls-engine-kpass-sha1
336 SHA1 of the private key password when using an TLS engine. Some TLS
337 engines such as the TPM engine may require the use of a password in
338 order to be accessed. This option allows a hex encoded SHA1 hash of
339 the password to the engine directly, instead of the user being
340 prompted for the password.
341 See also --tls-engine.
343 --tls-version
345 Choose which TLS protocol version to use when communicating with
346 the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
347 default value is tlsv1.2. Must match the protocol version used by
348 the broker.
349 -u, --username
351 Provide a username to be used for authenticating with the broker.
352 See also the --pw argument.
353 -U, --unsubscribe
355 A topic that will be unsubscribed from. This may be used on its own
356 or in conjunction with the --topic option and only makes sense when
357 used in conjunction with --clean-session.
358 If used with --topic then subscriptions will be processed before
360 unsubscriptions.
361 Note that it is only possible to unsubscribe from subscriptions
363 that have previously been made. It is not possible to punch holes
364 in wildcard subscriptions. For example, subscribing to sensors/#
365 and then unsubscribing from sensors/+/temperature as shown below
366 will still result in messages matching the sensors/+/temperature
367 being delivered to the client.
368 · mosquitto_sub -t sensors/# -U sensors/+/temperature -v
370 Note also that because retained messages are published by the
372 broker on receipt of a SUBSCRIBE command, subscribing and
373 unsubscribing to the same topic may result in messages being
374 received at the client.
375 This option may be repeated to unsubscribe from multiple topics.
377 -v, --verbose
379 Print received messages verbosely. With this argument, messages
380 will be printed as "topic payload". When this argument is not
381 given, the messages are printed as "payload".
382 -V, --protocol-version
384 Specify which version of the MQTT protocol should be used when
385 connecting to the remote broker. Can be 5, 311, 31, or the more
386 verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
387 -W
389 Provide a timeout as an integer number of seconds. mosquitto_sub
390 will stop processing messages and disconnect after this number of
391 seconds has passed. The timeout starts just after the client has
392 connected to the broker.
393 --will-payload
395 Specify a message that will be stored by the broker and sent out if
396 this client disconnects unexpectedly. This must be used in
397 conjunction with --will-topic.
398 --will-qos
400 The QoS to use for the Will. Defaults to 0. This must be used in
401 conjunction with --will-topic.
402 --will-retain
404 If given, if the client disconnects unexpectedly the message sent
405 out will be treated as a retained message. This must be used in
406 conjunction with --will-topic.
407 --will-topic
409 The topic on which to send a Will, in the event that the client
410 disconnects unexpectedly.
411
413 There are three ways of formatting the output from mosquitto_sub. In
414 all cases a new-line character is appended for each message received
415 unless the -N argument is passed to mosquitto_sub.
416 Payload-only is the default output format and will print the payload
418 exactly as it is received.
419 Verbose mode is activated with -v and prints the message topic and the
421 payload, separated by a space.
422 The final option is formatted output, which allows the user to define a
424 custom output format. The behaviour is controlled with the -F
425 format-string option. The format string is a free text string where
426 interpreted sequences are replaced by different parameters. The
427 available interpreted sequences are described below.
428 Three characters are used to start an interpreted sequence: %, @ and \.
430 Sequences starting with % are either parameters related to the MQTT
431 message being printed, or are helper sequences to avoid the need to
432 type long date format strings for example. Sequences starting with @
433 are passed to the strftime(3) function (with the @ replaced with a % -
434 note that only the character immediately after the @ is passed to
435 strftime). This allows the construction of a wide variety of time based
436 outputs. The output options for strftime vary from platform to
437 platform, so please check what is available for your platform.
438 mosquitto_sub does provide one extension to strftime which is @N, which
439 can be used to obtain the number of nanoseconds passed in the current
440 second. The resolution of this option varies depending on the platform.
441 The final sequence character is \, which is used to input some
442 characters that would otherwise be difficult to enter.
443 MQTT related parameters
445 · %% a literal %.
446 · %l the length of the payload in bytes.
448 · %m the message id (only relevant for messages with QoS>0).
450 · %p the payload raw bytes (may produce non-printable characters
452 depending on the payload).
453 · %q the message QoS.
455 · %r the retained flag for the message.
457 · %t the message topic.
459 · %x the payload with each byte as a hexadecimal number (lower case).
461 · %X the payload with each byte as a hexadecimal number (upper case).
463 Helpers
465 · %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
466 · %j JSON output of message parameters and timestamp, with a quoted
468 and escaped payload. For example
469 {"tst":1470825369,"topic":"greeting","qos":0,"retain":0,"payload":"hello
470 world"}
471 · %J JSON output of message parameters and timestamp, with a
473 non-quoted and non-escaped payload - this means the payload must
474 itself be valid JSON. For example:
475 {"tst":1470825369,"topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}.
476 · %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
478 · %U Unix timestamp with nanoseconds, e.g. 1470818943.786368637
480 Time related parameters
482 · @@ a literal @.
483 · @X pass the character represented by X to the strftime function as
485 %X. The options supported are platform dependent.
486 · @N the number of nanoseconds that have passed in the current
488 second, with varying timing resolution depending on platform.
489 Escape characters
491 · \\ a literal \.
492 · \0 a null character. Can be used to separate different parameters
494 that may contain spaces (e.g. topic, payload) so that processing
495 with tools such as xargs(1) is easier.
496 · \a alert/bell.
498 · \e the escape sequence, which can be used with ANSI colour codes to
500 provide coloured output for example.
501 · \n end of line.
503 · \r carriage return.
505 · \t horizontal tab.
507 · \v vertical tab.
509
511 mosquitto_sub can register a message with the broker that will be sent
512 out if it disconnects unexpectedly. See mqtt(7) for more information.
513 The minimum requirement for this is to use --will-topic to specify
515 which topic the will should be sent out on. This will result in a
516 non-retained, zero length message with QoS 0.
517 Use the --will-retain, --will-payload and --will-qos arguments to
519 modify the other will parameters.
520
522 The -D / --property option allows adding properties to different stages
523 of the mosquitto_sub run. The properties supported for each command are
524 as follows:
525 Connect
527 · authentication-data (binary data - note treated as a string in
528 mosquitto_sub)
529 · authentication-method (UTF-8 string pair)
531 · maximum-packet-size (32-bit unsigned integer)
533 · receive-maximum (16-bit unsigned integer)
535 · request-problem-information (8-bit unsigned integer)
537 · request-response-information (8-bit unsigned integer)
539 · session-expiry-interval (32-bit unsigned integer)
541 · topic-alias-maximum (16-bit unsigned integer)
543 · user-property (UTF-8 string pair)
545 Subscribe
547 · user-property (UTF-8 string pair)
548 Unsubscribe
550 · user-property (UTF-8 string pair)
551 Disconnect
553 · session-expiry-interval (32-bit unsigned integer)
554 · user-property (UTF-8 string pair)
556 Will properties
558 · content-type (UTF-8 string)
559 · correlation-data (binary data - note treated as a string in
561 mosquitto_sub)
562 · message-expiry-interval (32-bit unsigned integer)
564 · payload-format-indicator (8-bit unsigned integer)
566 · response-topic (UTF-8 string)
568 · user-property (UTF-8 string pair)
570 · will-delay-interval (32-bit unsigned integer)
572
574 Note that these really are examples - the subscriptions will work if
575 you run them as shown, but there must be something publishing messages
576 on those topics for you to receive anything.
577 Subscribe to temperature information on localhost with QoS 1:
579 · mosquitto_sub -t sensors/temperature -q 1
581 Subscribe to hard drive temperature updates on multiple machines/hard
583 drives. This expects each machine to be publishing its hard drive
584 temperature to sensors/machines/HOSTNAME/temperature/HD_NAME.
585 · mosquitto_sub -t sensors/machines/+/temperature/+
587 Subscribe to all broker status messages:
589 · mosquitto_sub -v -t \$SYS/#
591 Specify the output format as "ISO-8601 date : topic : payload in hex"
593 · mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#'
595 Specify the output format as "seconds since epoch.nanoseconds :
597 retained flag : qos : mid : payload length"
598 · mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#'
600 Topic and payload output, but with colour where supported.
602 · mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#'
604
606 $XDG_CONFIG_HOME/mosquitto_sub, $HOME/.config/mosquitto_sub
607 Configuration file for default options.
608
610 mosquitto bug information can be found at
611 https://github.com/eclipse/mosquitto/issues
612
614 mqtt(7), mosquitto_pub(1), mosquitto_rr(1), mosquitto(8),
615 libmosquitto(3), mosquitto-tls(7)
616
618 Roger Light <roger@atchoo.org>
619Mosquitto Project 04/30/2019 MOSQUITTO_SUB(1)