FreeBSD Manual Pages

home | help

MOSQUITTO_SUB(1) Commands MOSQUITTO_SUB(1)

NAME
mosquitto_sub - an MQTT version 5/3.1.1/3.1 client for subscribing to
topics

SYNOPSIS

mosquitto_sub [options] {-t message-topic... | -U unsubscribe-topic...}

options:
[auth-options] [connection-options] [misc-options]
[mqtt-options] [output-options] [tls-certificate-options |
tls-psk-options]

auth-options:
[-u username] [-P password]

connection-options:
{[-h hostname] [--unix socket path] [-p port-number]
| -L URL }
[-A bind-address] [--nodelay] [-S] [--ws]
[--proxy socks-url]

misc-options:
[-E] [-o config-file] [-W message-processing-timeout]

mqtt-options:
[-c] [-D command identifier value] [-i client-id]
[-I client-id-prefix] [-k keepalive-time]
[-q message-QoS] [--retain-as-published]
[--retain-handling always | new | never]
[-V protocol-version] [-x session-expiry-interval]
[--will-topic topic [--will-payload payload] [--will-qos qos] [--will-retain]]

output-options:
[-d] [-C msg-count] [--message-rate] [-N] [--pretty]
[--random-filter chance] [--remove-retained] [-R |
--retained-only] [--quiet] [-T filter-out...] [-v] [-w
| --watch]

tls-certificate-options:
[--no-tls]
{--cafile file | --capath dir}
[--tls-use-os-certs]
[--cert file] [--key file]
[--ciphers ciphers] [--insecure]
[--tls-alpn protocol] [--tls-keylog file]
[--tls-version version]
[--tls-engine engine]
[--keyform {pem | engine}]
[--tls-engine-kpass-sha1 kpass-sha1]

tls-psk-options:
--psk hex-key --psk-identity identity
[--ciphers ciphers] [--tls-version version]

mosquitto_sub [--help]

DESCRIPTION
mosquitto_sub is a simple MQTT version 5/3.1.1 client that will
subscribe to topics and print the messages that it receives.

In addition to subscribing to topics, mosquitto_sub can filter out
received messages so they are not printed (see the -T option) or
unsubscribe from topics (see the -U option). Unsubscribing from topics
is useful for clients connecting with clean session set to false.

ENCRYPTED CONNECTIONS
This client supports TLS encrypted connections. It is strongly
recommended that you use an encrypted connection for anything more than
the most basic setup.

To enable TLS connections when using x509 certificates, one of either
--cafile or --capath can be provided as an option.

Alternatively, if the -p 8883 option is used then the OS provided
certificates will be loaded and neither --cafile or --capath are
needed.

To enable TLS connections when using TLS-PSK, you must use the --psk
and the --psk-identity options.

OPTIONS
There are three ways to provide options to mosquitto_sub: the default
config file, a specified config file, or options on the command line.

Default Config File
The default config file is located at $XDG_CONFIG_HOME/mosquitto_sub or
$HOME/.config/mosquitto_sub on POSIX systems, or
%USERPROFILE%\mosquitto_sub on Windows.

The contents of the config file should consist of options, one per line
in the format: -option value. If options are also specified on the
command line, those options will override the same options set in the
config file. The exceptions to this are the message type options, of
which only one can be specified. Note also that currently some options
cannot be negated, e.g. -S. TLS encryption options can be negated with
the --no-tls option.

Config file lines that have a # as the first character are treated as
comments and not processed any further.

It is suggested that config files are primarily used for authentication
purposes. Use of a config file allows you to authenticate without the
need to show the username and password on the command line.

Config File
Available from version 2.1.

A config file can be specified on the command line using -o
config-file. If the -o option is used, the default config file will not
be loaded.

The format is the same as for the default config file.

The options
-A
Bind the outgoing connection to a local ip address/hostname. Use
this argument if you need to restrict network communication to a
particular interface.

-c, --disable-clean-session
Disable 'clean session' / enable persistent client mode. When this
argument is used, the broker will be instructed not to clean
existing sessions for the same client id when the client connects,
and sessions will never expire when the client disconnects. MQTT v5
clients can change their session expiry interval with the -x
argument.

When a session is persisted on the broker, the subscriptions for
the client will be maintained after it disconnects, along with
subsequent QoS 1 and QoS 2 messages that arrive. When the client
reconnects and does not clean the session, it will receive all of
the queued messages.

If using this option, the client id must be set manually with --id.

--cafile
Define the path to a file containing PEM encoded CA certificates
that are trusted. Used to enable SSL communication.

See also -F.

-V, --protocol-version
Specify which version of the MQTT protocol should be used when
connecting to the remote broker. Can be 5, 311, 31, or the more
verbose mqttv5, mqttv311, or mqttv31. Defaults to 311.

-W
Provide a timeout as an integer number of seconds. The client will
stop processing messages and disconnect after this number of
seconds has passed. The timeout starts just after the client has
connected to the broker.

-w, --watch
Available from version 2.1.

Messages will be printed on a fixed line number based on the topic
and order in which topics are received. Useful for monitoring
multiple topics that have single line payloads. Unexpected
behaviour will occur if there are more topics than lines in the
terminal, or if the payload occupies more than a single line. This
can be used in conjuction with other output options e.g. -F.

Requires ANSI escape code support in the terminal.

--will-payload
Specify a message that will be stored by the broker and sent out if
this client disconnects unexpectedly. This must be used in
conjunction with --will-topic.

--will-qos
The QoS to use for the Will. Defaults to 0. This must be used in
conjunction with --will-topic.

--will-retain
If given, if the client disconnects unexpectedly the message sent
out will be treated as a retained message. This must be used in
conjunction with --will-topic.

--will-topic
The topic on which to send a Will, in the event that the client
disconnects unexpectedly.

--ws
Connect using WebSockets instead of plain TCP.

-x
Set the session-expiry-interval property on the CONNECT packet. If
you use this option, the client will be set to be an MQTT v5
client. Set to 0-4294967294 to specify the session will expire in
that many seconds after the client disconnects, or use -1,
4294967295, or for a session that does not expire. Defaults to -1
if -c is also given, or 0 if -c not given.

If the session is set to never expire, either with -x or -c, then a
client id must be provided.

OUTPUT FORMAT
There are three ways of formatting the printed output. In all cases a
new-line character is appended for each message received unless the -N
argument is given.

Payload-only is the default output format and will print the payload
exactly as it is received.

Verbose mode is activated with -v and prints the message topic and the
payload, separated by a space.

The final option is formatted output, which allows the user to define a
custom output format. The behaviour is controlled with the -F
format-string option. The format string is a free text string where
interpreted sequences are replaced by different parameters. The
available interpreted sequences are described below.

Three characters are used to start an interpreted sequence: %, @ and \.
Sequences starting with % are either parameters related to the MQTT
message being printed, or are helper sequences to avoid the need to
type long date format strings for example. Sequences starting with @
are passed to the strftime(3) function (with the @ replaced with a % -
note that only the character immediately after the @ is passed to
strftime). This allows the construction of a wide variety of time based
outputs. The output options for strftime vary from platform to
platform, so please check what is available for your platform. One
extension to strftime is provided which is @N, which can be used to
obtain the number of nanoseconds passed in the current second. The
resolution of this option varies depending on the platform. The final
sequence character is \, which is used to input some characters that
would otherwise be difficult to enter.

Flag characters
The parameters %A, %C, %d, %E, %F, %f, %I, %l, %m, %p, %R, %S, %t, %x,
and %X can have optional flags immediately after the % character.

0
The value should be zero padded. This applies to the parameters %A,
%E, %d, %F, %f, %l, %m, %S, %X, and %x. It will be ignored for
other parameters. If used with the - flag, the 0 flag will be
ignored.

-
The value will be left aligned to the field width, padded with
blanks. The default is right alignment, with either 0 or blank
padding.

Field width
Some of the MQTT related parameters can be formatted with an option to
set their field width in a similar way to regular printf style formats,
i.e. this sets the minimum width when printing this parameter. If the
output length is smaller than this width, the field will be padded to
meet this width. This applies to the options %A, %C, %d, %E, %F, %f,
%I, %l, %m, %p, %R, %S, %t, %x, %X.

For example %10t would set the minimum topic field width to 10
characters.

Maximum width
Some of the MQTT related parameters can be formatted with an option to
set a maximum field width in a similar way to regular printf style
formats, for example %.20t for a maximum width of 20. This applies to
the options %C, %I, %R, %t.

For example %10.10t would set the minimum topic field width to 10
characters, and the maximum topic width to 10 characters, i.e. the
field will always be exactly 10 characters long.

Hexadecimal binary field width
The %x and %X parameters output the payload as a single hexadecimal
string by default. It is also possible to split the hexadecimal payload
into fields by a chosen length of nibbles. For example, %.2x would
split the payload into two nibble or one byte values, separated by
spaces and might produce an output of 18 83.

The separator character is a space by default, but can be changed to
one of !"#$&'()*+,-./:;<=>?@[\]^_`{|}~ by adding that character after
the binary field width. For example %.2:x might produce an output of
18:83.

Floating point number printing consideration
The output format supports only the IEEE 754 floating point standard as
described in Annex F of ISO/IEC 9899:1999. Don't try to use %f or %d if
the platform of the publisher uses a different floating point
representation standard than IEEE 754 or you will get invalid data. If
you are unsure what floating representation your platform is using,
then it is most likely IEEE 754. If you get malformed or unexpected
values, check if the floating point number in the payload from the
publisher is encoded in IEEE 754.

If want to print floats, make sure you only subscribe to topics that
send only IEEE 754 formatted floats. The processing is very strict
about floats and if anything that is not a float is received, an error
message will be printed.

MQTT related parameters
• %% a literal %.

• %A the MQTT v5 topic-alias property, if present.

• %C the MQTT v5 content-type property, if present.

• %D the MQTT v5 correlation-data property, if present. Note that
this property is specified as binary data, so may produce
non-printable characters.

• %d the payload treated as an 8 byte IEEE 754 float (double).

• %E the MQTT v5 message-expiry-interval property, if present.

• %F the MQTT v5 payload-format-indicator property, if present.

• %f the payload treated as an 4 byte IEEE 754 float.

• %l the length of the payload in bytes.

• %m the message id (only relevant for messages with QoS>0).

• %P the MQTT v5 user-property property, if present. This will be
printed in the form key:value. It is possible for any number of
user properties to be attached to a message, and to have duplicate
keys.

• %p the payload raw bytes (may produce non-printable characters
depending on the payload).

• %q the message QoS.

• %R the MQTT v5 response-topic property, if present.

• %r the retained flag for the message.

• %S the MQTT v5 subscription-identifier property, if present.

• %t the message topic.

• %x the payload with each byte as a hexadecimal number (lower case).

• %X the payload with each byte as a hexadecimal number (upper case).

Helpers
• %I ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100

• %j JSON output of message parameters and timestamp, with a quoted
and escaped payload. For example
{"tst":"2020-05-06T22:12:00.000000+0100","topic":"greeting","qos":0,"retain":0,"payload":"hello
world"}

• %J JSON output of message parameters and timestamp, with a
non-quoted and non-escaped payload - this means the payload must
itself be valid JSON. For example:
{"tst":"2020-05-06T22:12:00.000000+0100","topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}.

If the payload is not valid JSON, then the error message "Error:
Message payload is not valid JSON on topic <topic>" will be printed
to stderr.

• %U Unix timestamp with nanoseconds, e.g. 1470818943.786368637

Time related parameters
• @@ a literal @.

• @X pass the character represented by X to the strftime function as
%X. The options supported are platform dependent.

• @N the number of nanoseconds that have passed in the current
second, with varying timing resolution depending on platform.

Escape characters
• \\ a literal \.

• \0 a null character. Can be used to separate different parameters
that may contain spaces (e.g. topic, payload) so that processing
with tools such as xargs(1) is easier.

• \a alert/bell.

• \e the escape sequence, which can be used with ANSI colour codes to
provide coloured output for example.

• \n end of line.

• \r carriage return.

• \t horizontal tab.

• \v vertical tab.

WILLS
The client can register a message with the broker that will be sent out
if it disconnects unexpectedly. See mqtt(7) for more information.

The minimum requirement for this is to use --will-topic to specify
which topic the will should be sent out on. This will result in a
non-retained, zero length message with QoS 0.

Use the --will-retain, --will-payload and --will-qos arguments to
modify the other will parameters.

PROPERTIES
The -D / --property option allows adding properties to different stages
of the mosquitto_sub run. The properties supported for each command are
as follows:

Connect
• authentication-data (binary data - note treated as a string)

• authentication-method (UTF-8 string pair)

• maximum-packet-size (32-bit unsigned integer)

• receive-maximum (16-bit unsigned integer)

• request-problem-information (8-bit unsigned integer)

• request-response-information (8-bit unsigned integer)

• session-expiry-interval (32-bit unsigned integer, note use -x
instead)

• topic-alias-maximum (16-bit unsigned integer)

• user-property (UTF-8 string pair)

Subscribe
• user-property (UTF-8 string pair)

Unsubscribe
• user-property (UTF-8 string pair)

Disconnect
• session-expiry-interval (32-bit unsigned integer)

• user-property (UTF-8 string pair)

Will properties
• content-type (UTF-8 string)

• correlation-data (binary data - note treated as a string)

• message-expiry-interval (32-bit unsigned integer)

• payload-format-indicator (8-bit unsigned integer)

• response-topic (UTF-8 string)

• user-property (UTF-8 string pair)

• will-delay-interval (32-bit unsigned integer)

EXIT STATUS
Zero on success, or non-zero on error. If the connection is refused by
the broker at the MQTT level, then the exit code is the CONNACK reason
code. If another error occurs, the exit code is a libmosquitto return
value.

MQTT v3.1.1 CONNACK codes:

• 0 Success

• 1 Connection refused: Bad protocol version

• 2 Connection refused: Identifier rejected

• 3 Connection refused: Server unavailable

• 4 Connection refused: Bad username/password

• 5 Connection refused: Not authorized

MQTT v5 CONNACK codes:

• 0 Success

• 128 Unspecified error

• 129 Malformed packet

• 130 Protocol error

• 131 Implementation specific error

• 132 Unsupported protocol version

• 133 Client ID not valid

• 134 Bad username or password

• 135 Not authorized

• 136 Server unavailable

• 137 Server busy

• 138 Banned

• 139 Server shutting down

• 140 Bad authentication method

• 141 Keep alive timeout

• 142 Session taken over

• 143 Topic filter invalid

• 144 Topic name invalid

• 147 Receive maximum exceeded

• 148 Topic alias invalid

• 149 Packet too large

• 148 Message rate too high

• 151 Quota exceeded

• 152 Administrative action

• 153 Payload format invalid

• 154 Retain not supported

• 155 QoS not supported

• 156 Use another server

• 157 Server moved

• 158 Shared subscriptions not supported

• 159 Connection rate exceeded

• 160 Maximum connect time

• 161 Subscription IDs not supported

• 162 Wildcard subscriptions not supported

Other codes:

• 27 Timed out waiting for message

EXAMPLES
Note that these really are examples - the subscriptions will work if
you run them as shown, but there must be something publishing messages
on those topics for you to receive anything.

Subscribe to temperature information on localhost with QoS 1:

• mosquitto_sub -t sensors/temperature -q 1

Subscribe to hard drive temperature updates on multiple machines/hard
drives. This expects each machine to be publishing its hard drive
temperature to sensors/machines/HOSTNAME/temperature/HD_NAME.

• mosquitto_sub -t sensors/machines/+/temperature/+

Subscribe to all broker status messages:

• mosquitto_sub -v -t \$SYS/#

Specify the output format as "ISO-8601 date : topic : payload in hex"

• mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#'

Specify the output format as "seconds since epoch.nanoseconds :
retained flag : qos : mid : payload length"

• mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#'

Topic and payload output, but with colour where supported.

• mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#'

FILES
$XDG_CONFIG_HOME/mosquitto_sub, $HOME/.config/mosquitto_sub,
$HOME/snap/mosquitto/current/.config/mosquitto_sub (for snap installs)
Configuration file for default options.

BUGS
mosquitto bug information can be found at
https://github.com/eclipse-mosquitto/mosquitto/issues

SEE ALSO
mosquitto(7), mqtt(7), mosquitto_pub(1), mosquitto_rr(1), mosquitto(8),
libmosquitto(3), mosquitto-tls(7)

AUTHOR
Roger Light <roger@atchoo.org>

Mosquitto Project 06/11/2026 MOSQUITTO_SUB(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mosquitto_sub&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages