1MOSQUITTO_SUB(1)                   Commands                   MOSQUITTO_SUB(1)
2
3
4

NAME

6       mosquitto_sub - an MQTT version 5/3.1.1/3.1 client for subscribing to
7       topics
8

SYNOPSIS

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
25       mosquitto_sub [--help]
26

DESCRIPTION

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

ENCRYPTED CONNECTIONS

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
41       To enable TLS connections when using x509 certificates, one of either
42       --cafile or --capath must be provided as an option.
43
44       To enable TLS connections when using TLS-PSK, you must use the --psk
45       and the --psk-identity options.
46

OPTIONS

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
58       -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
63       -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
70           If using this option, the client id must be set manually with --id
71
72       --cafile
73           Define the path to a file containing PEM encoded CA certificates
74           that are trusted. Used to enable SSL communication.
75
76           See also --capath
77
78       --capath
79           Define the path to a directory containing PEM encoded CA
80           certificates that are trusted. Used to enable SSL communication.
81
82           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
86           See also --cafile
87
88       --cert
89           Define the path to a file containing a PEM encoded certificate for
90           this client, if required by the server.
91
92           See also --key.
93
94       --ciphers
95           An openssl compatible list of TLS ciphers to support in the client.
96           See ciphers(1) for more information.
97
98       -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
103           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
107       -d, --debug
108           Enable debug messages.
109
110       -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
115           -D command identifier value
116
117           -D command identifier name value
118
119           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
124           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
129           value is the value of the property to add, with a data type that is
130           property specific.
131
132           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
136       -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
143       -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
148           This option overrides the -v option, but does not override the -N
149           option.
150
151       --help
152           Display usage information.
153
154       -h, --host
155           Specify the host to connect to. Defaults to localhost.
156
157       -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
165           This option cannot be used at the same time as the --id-prefix
166           argument.
167
168       -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
174       --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
184       -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
189       --key
190           Define the path to a file containing a PEM encoded private key for
191           this client, if required by the server.
192
193           See also --cert.
194
195       --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
202           See also --tls-engine.
203
204       -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
209           If the scheme is mqtt:// then the port defaults to 1883. If the
210           scheme is mqtts:// then the port defaults to 8883.
211
212       -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
218       -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
222       -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
227       --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
235           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
238           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
242       --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
247       --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
251       -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
256           The QoS is identical for all topics subscribed to in a single
257           instance of mosquitto_sub.
258
259       --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
264       -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
272       --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
280           Example 1.  Remove all retained messages on the server, assuming we
281           have access to do so, and then exit:
282
283               mosquitto_sub -t '#' --remove-retained --retained-only
284
285           Example 2.  Remove a whole tree, with the exception of a single
286           topic:
287
288               mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained
289
290       --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
298       --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
304           This option is not valid for MQTT v3.1/v3.1.1 clients.
305
306       -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
311       -t, --topic
312           The MQTT topic to subscribe to. See mqtt(7) for more information on
313           MQTT topics.
314
315           This option may be repeated to subscribe to multiple topics.
316
317       -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
322           For example, subscribe to the BBC tree, but suppress output from
323           Radio 3:
324
325           ·   mosquitto_sub -t bbc/# -T bbc/radio3
326
327           This option may be repeated to filter out multiple topics or topic
328           trees.
329
330       --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
335       --tls-engine
336           A valid openssl engine id. These can be listed with openssl engine
337           command.
338
339           See also --keyform.
340
341       --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
348           See also --tls-engine.
349
350       --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
356       -u, --username
357           Provide a username to be used for authenticating with the broker.
358           See also the --pw argument.
359
360       -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
365           If used with --topic then subscriptions will be processed before
366           unsubscriptions.
367
368           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
375           ·   mosquitto_sub -t sensors/# -U sensors/+/temperature -v
376
377           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
382           This option may be repeated to unsubscribe from multiple topics.
383
384       -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
389       -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
394       -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
400       --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
405       --will-qos
406           The QoS to use for the Will. Defaults to 0. This must be used in
407           conjunction with --will-topic.
408
409       --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
414       --will-topic
415           The topic on which to send a Will, in the event that the client
416           disconnects unexpectedly.
417

OUTPUT FORMAT

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
423       Payload-only is the default output format and will print the payload
424       exactly as it is received.
425
426       Verbose mode is activated with -v and prints the message topic and the
427       payload, separated by a space.
428
429       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
435       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
450   MQTT related parameters
451       ·   %% a literal %.
452
453       ·   %l the length of the payload in bytes.
454
455       ·   %m the message id (only relevant for messages with QoS>0).
456
457       ·   %p the payload raw bytes (may produce non-printable characters
458           depending on the payload).
459
460       ·   %q the message QoS.
461
462       ·   %r the retained flag for the message.
463
464       ·   %t the message topic.
465
466       ·   %x the payload with each byte as a hexadecimal number (lower case).
467
468       ·   %X the payload with each byte as a hexadecimal number (upper case).
469
470   Helpers
471       ·   %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
472
473       ·   %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
478       ·   %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
483       ·   %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100
484
485       ·   %U Unix timestamp with nanoseconds, e.g. 1470818943.786368637
486
487   Time related parameters
488       ·   @@ a literal @.
489
490       ·   @X pass the character represented by X to the strftime function as
491           %X. The options supported are platform dependent.
492
493       ·   @N the number of nanoseconds that have passed in the current
494           second, with varying timing resolution depending on platform.
495
496   Escape characters
497       ·   \\ a literal \.
498
499       ·   \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
503       ·   \a alert/bell.
504
505       ·   \e the escape sequence, which can be used with ANSI colour codes to
506           provide coloured output for example.
507
508       ·   \n end of line.
509
510       ·   \r carriage return.
511
512       ·   \t horizontal tab.
513
514       ·   \v vertical tab.
515

WILLS

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
520       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
524       Use the --will-retain, --will-payload and --will-qos arguments to
525       modify the other will parameters.
526

PROPERTIES

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
532   Connect
533       ·   authentication-data (binary data - note treated as a string in
534           mosquitto_sub)
535
536       ·   authentication-method (UTF-8 string pair)
537
538       ·   maximum-packet-size (32-bit unsigned integer)
539
540       ·   receive-maximum (16-bit unsigned integer)
541
542       ·   request-problem-information (8-bit unsigned integer)
543
544       ·   request-response-information (8-bit unsigned integer)
545
546       ·   session-expiry-interval (32-bit unsigned integer)
547
548       ·   topic-alias-maximum (16-bit unsigned integer)
549
550       ·   user-property (UTF-8 string pair)
551
552   Subscribe
553       ·   user-property (UTF-8 string pair)
554
555   Unsubscribe
556       ·   user-property (UTF-8 string pair)
557
558   Disconnect
559       ·   session-expiry-interval (32-bit unsigned integer)
560
561       ·   user-property (UTF-8 string pair)
562
563   Will properties
564       ·   content-type (UTF-8 string)
565
566       ·   correlation-data (binary data - note treated as a string in
567           mosquitto_sub)
568
569       ·   message-expiry-interval (32-bit unsigned integer)
570
571       ·   payload-format-indicator (8-bit unsigned integer)
572
573       ·   response-topic (UTF-8 string)
574
575       ·   user-property (UTF-8 string pair)
576
577       ·   will-delay-interval (32-bit unsigned integer)
578

EXIT STATUS

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
585       MQTT v3.1.1 CONNACK codes:
586
587       ·   0 Success
588
589       ·   1 Connection refused: Bad protocol version
590
591       ·   2 Connection refused: Identifier rejected
592
593       ·   3 Connection refused: Server unavailable
594
595       ·   4 Connection refused: Bad username/password
596
597       ·   5 Connection refused: Not authorized
598
599       MQTT v5 CONNACK codes:
600
601       ·   0 Success
602
603       ·   128 Unspecified error
604
605       ·   129 Malformed packet
606
607       ·   130 Protocol error
608
609       ·   131 Implementation specific error
610
611       ·   132 Unsupported protocol version
612
613       ·   133 Client ID not valid
614
615       ·   134 Bad username or password
616
617       ·   135 Not authorized
618
619       ·   136 Server unavailable
620
621       ·   137 Server busy
622
623       ·   138 Banned
624
625       ·   139 Server shutting down
626
627       ·   140 Bad authentication method
628
629       ·   141 Keep alive timeout
630
631       ·   142 Session taken over
632
633       ·   143 Topic filter invalid
634
635       ·   144 Topic name invalid
636
637       ·   147 Receive maximum exceeded
638
639       ·   148 Topic alias invalid
640
641       ·   149 Packet too large
642
643       ·   148 Message rate too high
644
645       ·   151 Quota exceeded
646
647       ·   152 Administrative action
648
649       ·   153 Payload format invalid
650
651       ·   154 Retain not supported
652
653       ·   155 QoS not supported
654
655       ·   156 Use another server
656
657       ·   157 Server moved
658
659       ·   158 Shared subscriptions not supported
660
661       ·   159 Connection rate exceeded
662
663       ·   160 Maximum connect time
664
665       ·   161 Subscription IDs not supported
666
667       ·   162 Wildcard subscriptions not supported
668

EXAMPLES

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
674       Subscribe to temperature information on localhost with QoS 1:
675
676       ·   mosquitto_sub -t sensors/temperature -q 1
677
678       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
682       ·   mosquitto_sub -t sensors/machines/+/temperature/+
683
684       Subscribe to all broker status messages:
685
686       ·   mosquitto_sub -v -t \$SYS/#
687
688       Specify the output format as "ISO-8601 date : topic : payload in hex"
689
690       ·   mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#'
691
692       Specify the output format as "seconds since epoch.nanoseconds :
693       retained flag : qos : mid : payload length"
694
695       ·   mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#'
696
697       Topic and payload output, but with colour where supported.
698
699       ·   mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#'
700

FILES

702       $XDG_CONFIG_HOME/mosquitto_sub, $HOME/.config/mosquitto_sub
703           Configuration file for default options.
704

BUGS

706       mosquitto bug information can be found at
707       https://github.com/eclipse/mosquitto/issues
708

SEE ALSO

710       mqtt(7), mosquitto_pub(1), mosquitto_rr(1), mosquitto(8),
711       libmosquitto(3), mosquitto-tls(7)
712

AUTHOR

714       Roger Light <roger@atchoo.org>
715
716
717
718Mosquitto Project                 08/19/2020                  MOSQUITTO_SUB(1)
Impressum