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, 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
162       -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
168       --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
178       -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
183       --key
184           Define the path to a file containing a PEM encoded private key for
185           this client, if required by the server.
186
187           See also --cert.
188
189       --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
196           See also --tls-engine.
197
198       -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
203           If the scheme is mqtt:// then the port defaults to 1883. If the
204           scheme is mqtts:// then the port defaults to 8883.
205
206       -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
212       -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
216       -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
221       --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
229           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
232           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
236       --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
241       --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
245       -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
250           The QoS is identical for all topics subscribed to in a single
251           instance of mosquitto_sub.
252
253       --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
258       -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
266       --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
274           Example 1.  Remove all retained messages on the server, assuming we
275           have access to do so, and then exit:
276
277               mosquitto_sub -t '#' --remove-retained --retained-only
278
279           Example 2.  Remove a whole tree, with the exception of a single
280           topic:
281
282               mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained
283
284       --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
292       --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
298           This option is not valid for MQTT v3.1/v3.1.1 clients.
299
300       -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
305       -t, --topic
306           The MQTT topic to subscribe to. See mqtt(7) for more information on
307           MQTT topics.
308
309           This option may be repeated to subscribe to multiple topics.
310
311       -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
316           For example, subscribe to the BBC tree, but suppress output from
317           Radio 3:
318
319           ·   mosquitto_sub -t bbc/# -T bbc/radio3
320
321           This option may be repeated to filter out multiple topics or topic
322           trees.
323
324       --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
329       --tls-engine
330           A valid openssl engine id. These can be listed with openssl engine
331           command.
332
333           See also --keyform.
334
335       --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
342           See also --tls-engine.
343
344       --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
350       -u, --username
351           Provide a username to be used for authenticating with the broker.
352           See also the --pw argument.
353
354       -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
359           If used with --topic then subscriptions will be processed before
360           unsubscriptions.
361
362           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
369           ·   mosquitto_sub -t sensors/# -U sensors/+/temperature -v
370
371           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
376           This option may be repeated to unsubscribe from multiple topics.
377
378       -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
383       -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
388       -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
394       --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
399       --will-qos
400           The QoS to use for the Will. Defaults to 0. This must be used in
401           conjunction with --will-topic.
402
403       --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
408       --will-topic
409           The topic on which to send a Will, in the event that the client
410           disconnects unexpectedly.
411

OUTPUT FORMAT

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

WILLS

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
514       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
518       Use the --will-retain, --will-payload and --will-qos arguments to
519       modify the other will parameters.
520

PROPERTIES

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

EXAMPLES

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
578       Subscribe to temperature information on localhost with QoS 1:
579
580       ·   mosquitto_sub -t sensors/temperature -q 1
581
582       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
586       ·   mosquitto_sub -t sensors/machines/+/temperature/+
587
588       Subscribe to all broker status messages:
589
590       ·   mosquitto_sub -v -t \$SYS/#
591
592       Specify the output format as "ISO-8601 date : topic : payload in hex"
593
594       ·   mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#'
595
596       Specify the output format as "seconds since epoch.nanoseconds :
597       retained flag : qos : mid : payload length"
598
599       ·   mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#'
600
601       Topic and payload output, but with colour where supported.
602
603       ·   mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#'
604

FILES

606       $XDG_CONFIG_HOME/mosquitto_sub, $HOME/.config/mosquitto_sub
607           Configuration file for default options.
608

BUGS

610       mosquitto bug information can be found at
611       https://github.com/eclipse/mosquitto/issues
612

SEE ALSO

614       mqtt(7), mosquitto_pub(1), mosquitto_rr(1), mosquitto(8),
615       libmosquitto(3), mosquitto-tls(7)
616

AUTHOR

618       Roger Light <roger@atchoo.org>
619
620
621
622Mosquitto Project                 04/26/2019                  MOSQUITTO_SUB(1)
Impressum