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, a client id will be
159 generated depending on the MQTT version being used. For
160 v3.1.1/v3.1, the client generates a client id in the format
161 mosq-XXXXXXXXXXXXXXXXXX, where the X are replaced with random
162 alphanumeric characters. For v5.0, the client sends a zero length
163 client id, and the server will generate a client id for the client.
164 This option cannot be used at the same time as the --id-prefix
166 argument.
167 -I, --id-prefix
169 Provide a prefix that the client id will be built from by appending
170 the process id of the client. This is useful where the broker is
171 using the clientid_prefixes option. Cannot be used at the same time
172 as the --id argument.
173 --insecure
175 When using certificate based encryption, this option disables
176 verification of the server hostname in the server certificate. This
177 can be useful when testing initial server configurations but makes
178 it possible for a malicious third party to impersonate your server
179 through DNS spoofing, for example. Use this option in testing only.
180 If you need to resort to using this option in a production
181 environment, your setup is at fault and there is no point using
182 encryption.
183 -k, --keepalive
185 The number of seconds between sending PING commands to the broker
186 for the purposes of informing it we are still connected and
187 functioning. Defaults to 60 seconds.
188 --key
190 Define the path to a file containing a PEM encoded private key for
191 this client, if required by the server.
192 See also --cert.
194 --keyform
196 Specifies the type of private key in use when making TLS
197 connections.. This can be "pem" or "engine". This parameter is
198 useful when a TPM module is being used and the private key has been
199 created with it. Defaults to "pem", which means normal private key
200 files are used.
201 See also --tls-engine.
203 -L, --url
205 Specify specify user, password, hostname, port and topic at once as
206 a URL. The URL must be in the form:
207 mqtt(s)://[username[:password]@]host[:port]/topic
208 If the scheme is mqtt:// then the port defaults to 1883. If the
210 scheme is mqtts:// then the port defaults to 8883.
211 -N
213 Do not append an end of line character to the payload when
214 printing. This allows streaming of payload data from multiple
215 messages directly to another application unmodified. Only really
216 makes sense when not using -v.
217 -p, --port
219 Connect to the port specified. If not given, the default of 1883
220 for plain MQTT or 8883 for MQTT over TLS will be used.
221 -P, --pw
223 Provide a password to be used for authenticating with the broker.
224 Using this argument without also specifying a username is invalid
225 when using MQTT v3.1 or v3.1.1. See also the --username option.
226 --proxy
228 Specify a SOCKS5 proxy to connect through. "None" and "username"
229 authentication types are supported. The socks-url must be of the
230 form socks5h://[username[:password]@]host[:port]. The protocol
231 prefix socks5h means that hostnames are resolved by the proxy. The
232 symbols %25, %3A and %40 are URL decoded into %, : and @
233 respectively, if present in the username or password.
234 If username is not given, then no authentication is attempted. If
236 the port is not given, then the default of 1080 is used.
237 More SOCKS versions may be available in the future, depending on
239 demand, and will use different protocol prefixes as described in
240 curl(1).
241 --psk
243 Provide the hexadecimal (no leading 0x) pre-shared-key matching the
244 one used on the broker to use TLS-PSK encryption support.
245 --psk-identity must also be provided to enable TLS-PSK.
246 --psk-identity
248 The client identity to use with TLS-PSK support. This may be used
249 instead of a username if the broker is configured to do so.
250 -q, --qos
252 Specify the quality of service desired for the incoming messages,
253 from 0, 1 and 2. Defaults to 0. See mqtt(7) for more information on
254 QoS.
255 The QoS is identical for all topics subscribed to in a single
257 instance of mosquitto_sub.
258 --quiet
260 If this argument is given, no runtime errors will be printed. This
261 excludes any error messages given in case of invalid user input
262 (e.g. using --port without a port).
263 -R
265 If this argument is given, messages that are received that have the
266 retain bit set will not be printed. Messages with retain set are
267 "stale", in that it is not known when they were originally
268 published. When subscribing to a wildcard topic there may be a
269 large number of retained messages. This argument suppresses their
270 display.
271 --remove-retained
273 If this argument is given, the when mosquitto_sub receives a
274 message with the retained bit set, it will send a message to the
275 broker to clear that retained message. This applies to all received
276 messages except those that are filtered out by the -T option. This
277 option still takes effect even if -R is used. See also the
278 --retain-as-published and --retained-only options.
279 Example 1. Remove all retained messages on the server, assuming we
281 have access to do so, and then exit:
282 mosquitto_sub -t '#' --remove-retained --retained-only
284 Example 2. Remove a whole tree, with the exception of a single
286 topic:
287 mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained
289 --retained-only
291 If this argument is given, only messages that are received that
292 have the retain bit set will be printed. Messages with retain set
293 are "stale", in that it is not known when they were originally
294 published. With this argument in use, the receipt of the first
295 non-stale message will cause the client to exit. See also the
296 --retain-as-published option.
297 --retain-as-published
299 If this argument is given, the subscriptions will have the "retain
300 as published" option set. This means that the retain flag on an
301 incoming message will be exactly as set by the publishing client,
302 rather than indicating whether the message is fresh/stale.
303 This option is not valid for MQTT v3.1/v3.1.1 clients.
305 -S
307 Use SRV lookups to determine which host to connect to. Performs
308 lookups to _mqtt._tcp.<host> when used in conjunction with -h,
309 otherwise uses _mqtt._tcp.<local dns domain>.
310 -t, --topic
312 The MQTT topic to subscribe to. See mqtt(7) for more information on
313 MQTT topics.
314 This option may be repeated to subscribe to multiple topics.
316 -T, --filter-out
318 Suppress printing of topics that match the filter. This allows
319 subscribing to a wildcard topic and only printing a partial set of
320 the wildcard hierarchy.
321 For example, subscribe to the BBC tree, but suppress output from
323 Radio 3:
324 · mosquitto_sub -t bbc/# -T bbc/radio3
326 This option may be repeated to filter out multiple topics or topic
328 trees.
329 --tls-alpn
331 Provide a protocol to use when connecting to a broker that has
332 multiple protocols available on a single port, e.g. MQTT and
333 WebSockets.
334 --tls-engine
336 A valid openssl engine id. These can be listed with openssl engine
337 command.
338 See also --keyform.
340 --tls-engine-kpass-sha1
342 SHA1 of the private key password when using an TLS engine. Some TLS
343 engines such as the TPM engine may require the use of a password in
344 order to be accessed. This option allows a hex encoded SHA1 hash of
345 the password to the engine directly, instead of the user being
346 prompted for the password.
347 See also --tls-engine.
349 --tls-version
351 Choose which TLS protocol version to use when communicating with
352 the broker. Valid options are tlsv1.3, tlsv1.2 and tlsv1.1. The
353 default value is tlsv1.2. Must match the protocol version used by
354 the broker.
355 -u, --username
357 Provide a username to be used for authenticating with the broker.
358 See also the --pw argument.
359 -U, --unsubscribe
361 A topic that will be unsubscribed from. This may be used on its own
362 or in conjunction with the --topic option and only makes sense when
363 used in conjunction with --clean-session.
364 If used with --topic then subscriptions will be processed before
366 unsubscriptions.
367 Note that it is only possible to unsubscribe from subscriptions
369 that have previously been made. It is not possible to punch holes
370 in wildcard subscriptions. For example, subscribing to sensors/#
371 and then unsubscribing from sensors/+/temperature as shown below
372 will still result in messages matching the sensors/+/temperature
373 being delivered to the client.
374 · mosquitto_sub -t sensors/# -U sensors/+/temperature -v
376 Note also that because retained messages are published by the
378 broker on receipt of a SUBSCRIBE command, subscribing and
379 unsubscribing to the same topic may result in messages being
380 received at the client.
381 This option may be repeated to unsubscribe from multiple topics.
383 -v, --verbose
385 Print received messages verbosely. With this argument, messages
386 will be printed as "topic payload". When this argument is not
387 given, the messages are printed as "payload".
388 -V, --protocol-version
390 Specify which version of the MQTT protocol should be used when
391 connecting to the remote broker. Can be 5, 311, 31, or the more
392 verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.
393 -W
395 Provide a timeout as an integer number of seconds. mosquitto_sub
396 will stop processing messages and disconnect after this number of
397 seconds has passed. The timeout starts just after the client has
398 connected to the broker.
399 --will-payload
401 Specify a message that will be stored by the broker and sent out if
402 this client disconnects unexpectedly. This must be used in
403 conjunction with --will-topic.
404 --will-qos
406 The QoS to use for the Will. Defaults to 0. This must be used in
407 conjunction with --will-topic.
408 --will-retain
410 If given, if the client disconnects unexpectedly the message sent
411 out will be treated as a retained message. This must be used in
412 conjunction with --will-topic.
413 --will-topic
415 The topic on which to send a Will, in the event that the client
416 disconnects unexpectedly.
417
419 There are three ways of formatting the output from mosquitto_sub. In
420 all cases a new-line character is appended for each message received
421 unless the -N argument is passed to mosquitto_sub.
422 Payload-only is the default output format and will print the payload
424 exactly as it is received.
425 Verbose mode is activated with -v and prints the message topic and the
427 payload, separated by a space.
428 The final option is formatted output, which allows the user to define a
430 custom output format. The behaviour is controlled with the -F
431 format-string option. The format string is a free text string where
432 interpreted sequences are replaced by different parameters. The
433 available interpreted sequences are described below.
434 Three characters are used to start an interpreted sequence: %, @ and \.
436 Sequences starting with % are either parameters related to the MQTT
437 message being printed, or are helper sequences to avoid the need to
438 type long date format strings for example. Sequences starting with @
439 are passed to the strftime(3) function (with the @ replaced with a % -
440 note that only the character immediately after the @ is passed to
441 strftime). This allows the construction of a wide variety of time based
442 outputs. The output options for strftime vary from platform to
443 platform, so please check what is available for your platform.
444 mosquitto_sub does provide one extension to strftime which is @N, which
445 can be used to obtain the number of nanoseconds passed in the current
446 second. The resolution of this option varies depending on the platform.
447 The final sequence character is \, which is used to input some
448 characters that would otherwise be difficult to enter.
449 MQTT related parameters
451 · %% a literal %.
452 · %l the length of the payload in bytes.
454 · %m the message id (only relevant for messages with QoS>0).
456 · %p the payload raw bytes (may produce non-printable characters
458 depending on the payload).
459 · %q the message QoS.
461 · %r the retained flag for the message.
463 · %t the message topic.
465 · %x the payload with each byte as a hexadecimal number (lower case).
467 · %X the payload with each byte as a hexadecimal number (upper case).
469 Helpers
471 · %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
472 · %j JSON output of message parameters and timestamp, with a quoted
474 and escaped payload. For example
475 {"tst":1470825369,"topic":"greeting","qos":0,"retain":0,"payload":"hello
476 world"}
477 · %J JSON output of message parameters and timestamp, with a
479 non-quoted and non-escaped payload - this means the payload must
480 itself be valid JSON. For example:
481 {"tst":1470825369,"topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}.
482 · %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
484 · %U Unix timestamp with nanoseconds, e.g. 1470818943.786368637
486 Time related parameters
488 · @@ a literal @.
489 · @X pass the character represented by X to the strftime function as
491 %X. The options supported are platform dependent.
492 · @N the number of nanoseconds that have passed in the current
494 second, with varying timing resolution depending on platform.
495 Escape characters
497 · \\ a literal \.
498 · \0 a null character. Can be used to separate different parameters
500 that may contain spaces (e.g. topic, payload) so that processing
501 with tools such as xargs(1) is easier.
502 · \a alert/bell.
504 · \e the escape sequence, which can be used with ANSI colour codes to
506 provide coloured output for example.
507 · \n end of line.
509 · \r carriage return.
511 · \t horizontal tab.
513 · \v vertical tab.
515
517 mosquitto_sub can register a message with the broker that will be sent
518 out if it disconnects unexpectedly. See mqtt(7) for more information.
519 The minimum requirement for this is to use --will-topic to specify
521 which topic the will should be sent out on. This will result in a
522 non-retained, zero length message with QoS 0.
523 Use the --will-retain, --will-payload and --will-qos arguments to
525 modify the other will parameters.
526
528 The -D / --property option allows adding properties to different stages
529 of the mosquitto_sub run. The properties supported for each command are
530 as follows:
531 Connect
533 · authentication-data (binary data - note treated as a string in
534 mosquitto_sub)
535 · authentication-method (UTF-8 string pair)
537 · maximum-packet-size (32-bit unsigned integer)
539 · receive-maximum (16-bit unsigned integer)
541 · request-problem-information (8-bit unsigned integer)
543 · request-response-information (8-bit unsigned integer)
545 · session-expiry-interval (32-bit unsigned integer)
547 · topic-alias-maximum (16-bit unsigned integer)
549 · user-property (UTF-8 string pair)
551 Subscribe
553 · user-property (UTF-8 string pair)
554 Unsubscribe
556 · user-property (UTF-8 string pair)
557 Disconnect
559 · session-expiry-interval (32-bit unsigned integer)
560 · user-property (UTF-8 string pair)
562 Will properties
564 · content-type (UTF-8 string)
565 · correlation-data (binary data - note treated as a string in
567 mosquitto_sub)
568 · message-expiry-interval (32-bit unsigned integer)
570 · payload-format-indicator (8-bit unsigned integer)
572 · response-topic (UTF-8 string)
574 · user-property (UTF-8 string pair)
576 · will-delay-interval (32-bit unsigned integer)
578
580 mosquitto_sub returns zero on success, or non-zero on error. If the
581 connection is refused by the broker at the MQTT level, then the exit
582 code is the CONNACK reason code. If another error occurs, the exit code
583 is a libmosquitto return value.
584 MQTT v3.1.1 CONNACK codes:
586 · 0 Success
588 · 1 Connection refused: Bad protocol version
590 · 2 Connection refused: Identifier rejected
592 · 3 Connection refused: Server unavailable
594 · 4 Connection refused: Bad username/password
596 · 5 Connection refused: Not authorized
598 MQTT v5 CONNACK codes:
600 · 0 Success
602 · 128 Unspecified error
604 · 129 Malformed packet
606 · 130 Protocol error
608 · 131 Implementation specific error
610 · 132 Unsupported protocol version
612 · 133 Client ID not valid
614 · 134 Bad username or password
616 · 135 Not authorized
618 · 136 Server unavailable
620 · 137 Server busy
622 · 138 Banned
624 · 139 Server shutting down
626 · 140 Bad authentication method
628 · 141 Keep alive timeout
630 · 142 Session taken over
632 · 143 Topic filter invalid
634 · 144 Topic name invalid
636 · 147 Receive maximum exceeded
638 · 148 Topic alias invalid
640 · 149 Packet too large
642 · 148 Message rate too high
644 · 151 Quota exceeded
646 · 152 Administrative action
648 · 153 Payload format invalid
650 · 154 Retain not supported
652 · 155 QoS not supported
654 · 156 Use another server
656 · 157 Server moved
658 · 158 Shared subscriptions not supported
660 · 159 Connection rate exceeded
662 · 160 Maximum connect time
664 · 161 Subscription IDs not supported
666 · 162 Wildcard subscriptions not supported
668
670 Note that these really are examples - the subscriptions will work if
671 you run them as shown, but there must be something publishing messages
672 on those topics for you to receive anything.
673 Subscribe to temperature information on localhost with QoS 1:
675 · mosquitto_sub -t sensors/temperature -q 1
677 Subscribe to hard drive temperature updates on multiple machines/hard
679 drives. This expects each machine to be publishing its hard drive
680 temperature to sensors/machines/HOSTNAME/temperature/HD_NAME.
681 · mosquitto_sub -t sensors/machines/+/temperature/+
683 Subscribe to all broker status messages:
685 · mosquitto_sub -v -t \$SYS/#
687 Specify the output format as "ISO-8601 date : topic : payload in hex"
689 · mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#'
691 Specify the output format as "seconds since epoch.nanoseconds :
693 retained flag : qos : mid : payload length"
694 · mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#'
696 Topic and payload output, but with colour where supported.
698 · mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#'
700
702 $XDG_CONFIG_HOME/mosquitto_sub, $HOME/.config/mosquitto_sub
703 Configuration file for default options.
704
706 mosquitto bug information can be found at
707 https://github.com/eclipse/mosquitto/issues
708
710 mqtt(7), mosquitto_pub(1), mosquitto_rr(1), mosquitto(8),
711 libmosquitto(3), mosquitto-tls(7)
712
714 Roger Light <roger@atchoo.org>
715Mosquitto Project 08/19/2020 MOSQUITTO_SUB(1)