'\" t
.\" Title: mosquitto_sub
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 11/28/2019
.\" Manual: Commands
.\" Source: Mosquitto Project
.\" Language: English
.\"
.TH "MOSQUITTO_SUB" "1" "11/28/2019" "Mosquitto Project" "Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mosquitto_sub \- an MQTT version 5/3\&.1\&.1/3\&.1 client for subscribing to topics
.SH "SYNOPSIS"
.HP \w'\fBmosquitto_sub\fR\ 'u
\fBmosquitto_sub\fR {[\fB\-h\fR\ \fIhostname\fR]\ [\fB\-p\fR\ \fIport\-number\fR]\ [\fB\-u\fR\ \fIusername\fR]\ [\fB\-P\fR\ \fIpassword\fR]\ \fB\-t\fR\ \fImessage\-topic\fR... | \fB\-L\fR\ \fIURL\fR\ [\fB\-t\fR\ \fImessage\-topic\fR...] } [\fB\-A\fR\ \fIbind\-address\fR] [\fB\-c\fR] [\fB\-C\fR\ \fImsg\-count\fR] [\fB\-d\fR] [\fB\-D\fR\ \fIcommand\fR\ \fIidentifier\fR\ \fIvalue\fR] [\fB\-E\fR] [\fB\-i\fR\ \fIclient\-id\fR] [\fB\-I\fR\ \fIclient\-id\-prefix\fR] [\fB\-k\fR\ \fIkeepalive\-time\fR] [\fB\-N\fR] [\fB\-q\fR\ \fImessage\-QoS\fR] [\fB\-\-remove\-retained\fR] [\fB\-R\fR | \fB\-\-retained\-only\fR] [\fB\-\-retain\-as\-published\fR] [\fB\-S\fR] [\fB\-T\fR\ \fIfilter\-out\fR...] [\fB\-U\fR\ \fIunsub\-topic\fR...] [\fB\-v\fR] [\fB\-V\fR\ \fIprotocol\-version\fR] [\fB\-W\fR\ \fImessage\-processing\-timeout\fR] [\fB\-\-proxy\fR\ \fIsocks\-url\fR] [\fB\-\-quiet\fR] [\fB\-\-will\-topic\fR\ \fItopic\fR\ [\fB\-\-will\-payload\fR\ \fIpayload\fR]\ [\fB\-\-will\-qos\fR\ \fIqos\fR]\ [\fB\-\-will\-retain\fR]] [[{\fB\-\-cafile\fR\ \fIfile\fR\ |\ \fB\-\-capath\fR\ \fIdir\fR}\ [\fB\-\-cert\fR\ \fIfile\fR]\ [\fB\-\-key\fR\ \fIfile\fR]\ [\fB\-\-tls\-version\fR\ \fIversion\fR]\ [\fB\-\-tls\-alpn\fR\ \fIprotocol\fR]\ [\fB\-\-tls\-engine\fR\ \fIengine\fR]\ [\fB\-\-keyform\fR\ {\fIpem\fR\ |\ \fIengine\fR}]\ [\fB\-\-tls\-engine\-kpass\-sha1\fR\ \fIkpass\-sha1\fR]\ [\fB\-\-insecure\fR]] | [\fB\-\-psk\fR\ \fIhex\-key\fR\ \fB\-\-psk\-identity\fR\ \fIidentity\fR\ [\fB\-\-tls\-version\fR\ \fIversion\fR]]]
.HP \w'\fBmosquitto_sub\fR\ 'u
\fBmosquitto_sub\fR [\fB\-\-help\fR]
.SH "DESCRIPTION"
.PP
\fBmosquitto_sub\fR
is a simple MQTT version 5/3\&.1\&.1 client that will subscribe to topics and print the messages that it receives\&.
.PP
In addition to subscribing to topics,
\fBmosquitto_sub\fR
can filter out received messages so they are not printed (see the
\fB\-T\fR
option) or unsubscribe from topics (see the
\fB\-U\fR
option)\&. Unsubscribing from topics is useful for clients connecting with clean session set to false\&.
.SH "ENCRYPTED CONNECTIONS"
.PP
\fBmosquitto_sub\fR
supports TLS encrypted connections\&. It is strongly recommended that you use an encrypted connection for anything more than the most basic setup\&.
.PP
To enable TLS connections when using x509 certificates, one of either
\fB\-\-cafile\fR
or
\fB\-\-capath\fR
must be provided as an option\&.
.PP
To enable TLS connections when using TLS\-PSK, you must use the
\fB\-\-psk\fR
and the
\fB\-\-psk\-identity\fR
options\&.
.SH "OPTIONS"
.PP
The options below may be given on the command line, but may also be placed in a config file located at
\fB$XDG_CONFIG_HOME/mosquitto_sub\fR
or
\fB$HOME/\&.config/mosquitto_sub\fR
with one pair of
\fB\-option \fR\fB\fIvalue\fR\fR
per line\&. The values in the config file will be used as defaults and can be overridden by using the command line\&. The exceptions to this are
\fB\-t\fR
and
\fB\-T\fR, which if given in the config file will not be overridden\&. Note also that currently some options cannot be negated, e\&.g\&.
\fB\-S\fR\&. Config file lines that have a
\fB#\fR
as the first character are treated as comments and not processed any further\&.
.PP
\fB\-A\fR
.RS 4
Bind the outgoing connection to a local ip address/hostname\&. Use this argument if you need to restrict network communication to a particular interface\&.
.RE
.PP
\fB\-c\fR, \fB\-\-disable\-clean\-session\fR
.RS 4
Disable the \*(Aqclean session\*(Aq flag\&. This means that all of 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, it will receive all of the queued messages\&.
.sp
If using this option, the client id must be set manually with
\fB\-\-id\fR
.RE
.PP
\fB\-\-cafile\fR
.RS 4
Define the path to a file containing PEM encoded CA certificates that are trusted\&. Used to enable SSL communication\&.
.sp
See also
\fB\-\-capath\fR
.RE
.PP
\fB\-\-capath\fR
.RS 4
Define the path to a directory containing PEM encoded CA certificates that are trusted\&. Used to enable SSL communication\&.
.sp
For
\fB\-\-capath\fR
to work correctly, the certificate files must have "\&.crt" as the file ending and you must run "openssl rehash " each time you add/remove a certificate\&.
.sp
See also
\fB\-\-cafile\fR
.RE
.PP
\fB\-\-cert\fR
.RS 4
Define the path to a file containing a PEM encoded certificate for this client, if required by the server\&.
.sp
See also
\fB\-\-key\fR\&.
.RE
.PP
\fB\-\-ciphers\fR
.RS 4
An openssl compatible list of TLS ciphers to support in the client\&. See
\fBciphers\fR(1)
for more information\&.
.RE
.PP
\fB\-C\fR
.RS 4
Disconnect and exit the program immediately after the given count of messages have been received\&. This may be useful in shell scripts where on a single status value is required, for example\&.
.sp
Combine with
\fB\-R\fR
to print only the first set of fresh messages (i\&.e\&. that does not have the retained flag set), or with
\fB\-T\fR
to filter which topics are processed\&.
.RE
.PP
\fB\-d\fR, \fB\-\-debug\fR
.RS 4
Enable debug messages\&.
.RE
.PP
\fB\-D\fR, \fB\-\-property\fR
.RS 4
Use an MQTT v5 property with this publish\&. If you use this option, the client will be set to be an MQTT v5 client\&. This option has two forms:
.sp
\fB\-D command identifier value\fR
.sp
\fB\-D command identifier name value\fR
.sp
\fBcommand\fR
is the MQTT command/packet identifier and can be one of CONNECT, PUBACK, PUBREC, PUBCOMP, SUBSCRIBE, UNSUBSCRIBE, DISCONNECT, AUTH, or WILL\&. The properties available for each command are listed in the Properties section\&.
.sp
\fBidentifier\fR
is the name of the property to add\&. This is as described in the specification, but with \*(Aq\-\*(Aq as a word separator\&. For example:
\fBpayload\-format\-indicator\fR\&. More details are in the
Properties
section\&.
.sp
\fBvalue\fR
is the value of the property to add, with a data type that is property specific\&.
.sp
\fBname\fR
is only used for the
\fBuser\-property\fR
property as the first of the two strings in the string pair\&. In that case,
\fBvalue\fR
is the second of the strings in the pair\&.
.RE
.PP
\fB\-E\fR
.RS 4
If this option is given,
\fBmosquitto_sub\fR
will exit immediately that all of its subscriptions have been acknowledged by the broker\&. In conjunction with
\fB\-c\fR
this allows a durable client session to be initialised on the broker for future use without requiring any messages to be received\&.
.RE
.PP
\fB\-F\fR
.RS 4
Specify output printing format\&. This option allows you to choose what information from each message is printed to the screen\&. See the
Output Format
section below for full details\&.
.sp
This option overrides the
\fB\-v\fR
option, but does not override the
\fB\-N\fR
option\&.
.RE
.PP
\fB\-\-help\fR
.RS 4
Display usage information\&.
.RE
.PP
\fB\-h\fR, \fB\-\-host\fR
.RS 4
Specify the host to connect to\&. Defaults to localhost\&.
.RE
.PP
\fB\-i\fR, \fB\-\-id\fR
.RS 4
The id to use for this client\&. If not given, a client id will be generated depending on the MQTT version being used\&. For v3\&.1\&.1/v3\&.1, the client generates a client id in the format
\fBmosq\-XXXXXXXXXXXXXXXXXX\fR, where the
\fBX\fR
are replaced with random alphanumeric characters\&. For v5\&.0, the client sends a zero length client id, and the server will generate a client id for the client\&.
.sp
This option cannot be used at the same time as the
\fB\-\-id\-prefix\fR
argument\&.
.RE
.PP
\fB\-I\fR, \fB\-\-id\-prefix\fR
.RS 4
Provide a prefix that the client id will be built from by appending the process id of the client\&. This is useful where the broker is using the clientid_prefixes option\&. Cannot be used at the same time as the
\fB\-\-id\fR
argument\&.
.RE
.PP
\fB\-\-insecure\fR
.RS 4
When using certificate based encryption, this option disables verification of the server hostname in the server certificate\&. This can be useful when testing initial server configurations but makes it possible for a malicious third party to impersonate your server through DNS spoofing, for example\&. Use this option in testing
\fIonly\fR\&. If you need to resort to using this option in a production environment, your setup is at fault and there is no point using encryption\&.
.RE
.PP
\fB\-k\fR, \fB\-\-keepalive\fR
.RS 4
The number of seconds between sending PING commands to the broker for the purposes of informing it we are still connected and functioning\&. Defaults to 60 seconds\&.
.RE
.PP
\fB\-\-key\fR
.RS 4
Define the path to a file containing a PEM encoded private key for this client, if required by the server\&.
.sp
See also
\fB\-\-cert\fR\&.
.RE
.PP
\fB\-\-keyform\fR
.RS 4
Specifies the type of private key in use when making TLS connections\&.\&. This can be "pem" or "engine"\&. This parameter is useful when a TPM module is being used and the private key has been created with it\&. Defaults to "pem", which means normal private key files are used\&.
.sp
See also
\fB\-\-tls\-engine\fR\&.
.RE
.PP
\fB\-L\fR, \fB\-\-url\fR
.RS 4
Specify specify user, password, hostname, port and topic at once as a URL\&. The URL must be in the form: mqtt(s)://[username[:password]@]host[:port]/topic
.sp
If the scheme is mqtt:// then the port defaults to 1883\&. If the scheme is mqtts:// then the port defaults to 8883\&.
.RE
.PP
\fB\-N\fR
.RS 4
Do not append an end of line character to the payload when printing\&. This allows streaming of payload data from multiple messages directly to another application unmodified\&. Only really makes sense when not using
\fB\-v\fR\&.
.RE
.PP
\fB\-p\fR, \fB\-\-port\fR
.RS 4
Connect to the port specified\&. If not given, the default of 1883 for plain MQTT or 8883 for MQTT over TLS will be used\&.
.RE
.PP
\fB\-P\fR, \fB\-\-pw\fR
.RS 4
Provide a password to be used for authenticating with the broker\&. Using this argument without also specifying a username is invalid when using MQTT v3\&.1 or v3\&.1\&.1\&. See also the
\fB\-\-username\fR
option\&.
.RE
.PP
\fB\-\-proxy\fR
.RS 4
Specify a SOCKS5 proxy to connect through\&. "None" and "username" authentication types are supported\&. The
\fBsocks\-url\fR
must be of the form
\fBsocks5h://[username[:password]@]host[:port]\fR\&. The protocol prefix
\fBsocks5h\fR
means that hostnames are resolved by the proxy\&. The symbols %25, %3A and %40 are URL decoded into %, : and @ respectively, if present in the username or password\&.
.sp
If username is not given, then no authentication is attempted\&. If the port is not given, then the default of 1080 is used\&.
.sp
More SOCKS versions may be available in the future, depending on demand, and will use different protocol prefixes as described in
\fBcurl\fR(1)\&.
.RE
.PP
\fB\-\-psk\fR
.RS 4
Provide the hexadecimal (no leading 0x) pre\-shared\-key matching the one used on the broker to use TLS\-PSK encryption support\&.
\fB\-\-psk\-identity\fR
must also be provided to enable TLS\-PSK\&.
.RE
.PP
\fB\-\-psk\-identity\fR
.RS 4
The client identity to use with TLS\-PSK support\&. This may be used instead of a username if the broker is configured to do so\&.
.RE
.PP
\fB\-q\fR, \fB\-\-qos\fR
.RS 4
Specify the quality of service desired for the incoming messages, from 0, 1 and 2\&. Defaults to 0\&. See
\fBmqtt\fR(7)
for more information on QoS\&.
.sp
The QoS is identical for all topics subscribed to in a single instance of mosquitto_sub\&.
.RE
.PP
\fB\-\-quiet\fR
.RS 4
If this argument is given, no runtime errors will be printed\&. This excludes any error messages given in case of invalid user input (e\&.g\&. using
\fB\-\-port\fR
without a port)\&.
.RE
.PP
\fB\-R\fR
.RS 4
If this argument is given, messages that are received that have the retain bit set will not be printed\&. Messages with retain set are "stale", in that it is not known when they were originally published\&. When subscribing to a wildcard topic there may be a large number of retained messages\&. This argument suppresses their display\&.
.RE
.PP
\fB\-\-remove\-retained\fR
.RS 4
If this argument is given, the when mosquitto_sub receives a message with the retained bit set, it will send a message to the broker to clear that retained message\&. This applies to all received messages except those that are filtered out by the
\fB\-T\fR
option\&. This option still takes effect even if
\fB\-R\fR
is used\&. See also the
\fB\-\-retain\-as\-published\fR
and
\fB\-\-retained\-only\fR
options\&.
.PP
\fBExample\ \&1.\ \&\fR
Remove all retained messages on the server, assuming we have access to do so, and then exit:
.sp
.if n \{\
.RS 4
.\}
.nf
mosquitto_sub \-t \*(Aq#\*(Aq \-\-remove\-retained \-\-retained\-only
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&\fR
Remove a whole tree, with the exception of a single topic:
.sp
.if n \{\
.RS 4
.\}
.nf
mosquitto_sub \-t \*(Aqbbc/#\*(Aq \-T bbc/bbc1 \-\-remove\-retained
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-\-retained\-only\fR
.RS 4
If this argument is given, only messages that are received that have the retain bit set will be printed\&. Messages with retain set are "stale", in that it is not known when they were originally published\&. With this argument in use, the receipt of the first non\-stale message will cause the client to exit\&. See also the
\fB\-\-retain\-as\-published\fR
option\&.
.RE
.PP
\fB\-\-retain\-as\-published\fR
.RS 4
If this argument is given, the subscriptions will have the "retain as published" option set\&. This means that the retain flag on an incoming message will be exactly as set by the publishing client, rather than indicating whether the message is fresh/stale\&.
.sp
This option is not valid for MQTT v3\&.1/v3\&.1\&.1 clients\&.
.RE
.PP
\fB\-S\fR
.RS 4
Use SRV lookups to determine which host to connect to\&. Performs lookups to
\fB_mqtt\&._tcp\&.\fR
when used in conjunction with
\fB\-h\fR, otherwise uses
\fB_mqtt\&._tcp\&.\fR\&.
.RE
.PP
\fB\-t\fR, \fB\-\-topic\fR
.RS 4
The MQTT topic to subscribe to\&. See
\fBmqtt\fR(7)
for more information on MQTT topics\&.
.sp
This option may be repeated to subscribe to multiple topics\&.
.RE
.PP
\fB\-T\fR, \fB\-\-filter\-out\fR
.RS 4
Suppress printing of topics that match the filter\&. This allows subscribing to a wildcard topic and only printing a partial set of the wildcard hierarchy\&.
.sp
For example, subscribe to the BBC tree, but suppress output from Radio 3:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-t
bbc/#
\-T
bbc/radio3
.RE
.sp
This option may be repeated to filter out multiple topics or topic trees\&.
.RE
.PP
\fB\-\-tls\-alpn\fR
.RS 4
Provide a protocol to use when connecting to a broker that has multiple protocols available on a single port, e\&.g\&. MQTT and WebSockets\&.
.RE
.PP
\fB\-\-tls\-engine\fR
.RS 4
A valid openssl engine id\&. These can be listed with openssl engine command\&.
.sp
See also
\fB\-\-keyform\fR\&.
.RE
.PP
\fB\-\-tls\-engine\-kpass\-sha1\fR
.RS 4
SHA1 of the private key password when using an TLS engine\&. Some TLS engines such as the TPM engine may require the use of a password in order to be accessed\&. This option allows a hex encoded SHA1 hash of the password to the engine directly, instead of the user being prompted for the password\&.
.sp
See also
\fB\-\-tls\-engine\fR\&.
.RE
.PP
\fB\-\-tls\-version\fR
.RS 4
Choose which TLS protocol version to use when communicating with the broker\&. Valid options are
\fBtlsv1\&.3\fR,
\fBtlsv1\&.2\fR
and
\fBtlsv1\&.1\fR\&. The default value is
\fBtlsv1\&.2\fR\&. Must match the protocol version used by the broker\&.
.RE
.PP
\fB\-u\fR, \fB\-\-username\fR
.RS 4
Provide a username to be used for authenticating with the broker\&. See also the
\fB\-\-pw\fR
argument\&.
.RE
.PP
\fB\-U\fR, \fB\-\-unsubscribe\fR
.RS 4
A topic that will be unsubscribed from\&. This may be used on its own or in conjunction with the
\fB\-\-topic\fR
option and only makes sense when used in conjunction with
\fB\-\-clean\-session\fR\&.
.sp
If used with
\fB\-\-topic\fR
then subscriptions will be processed before unsubscriptions\&.
.sp
Note that it is only possible to unsubscribe from subscriptions that have previously been made\&. It is not possible to punch holes in wildcard subscriptions\&. For example, subscribing to
\fBsensors/#\fR
and then unsubscribing from
\fBsensors/+/temperature\fR
as shown below will still result in messages matching the
\fBsensors/+/temperature\fR
being delivered to the client\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-t
sensors/#
\-U
sensors/+/temperature
\-v
.RE
.sp
Note also that because retained messages are published by the broker on receipt of a SUBSCRIBE command, subscribing and unsubscribing to the same topic may result in messages being received at the client\&.
.sp
This option may be repeated to unsubscribe from multiple topics\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Print received messages verbosely\&. With this argument, messages will be printed as "topic payload"\&. When this argument is not given, the messages are printed as "payload"\&.
.RE
.PP
\fB\-V\fR, \fB\-\-protocol\-version\fR
.RS 4
Specify which version of the MQTT protocol should be used when connecting to the remote broker\&. Can be
\fB5\fR,
\fB311\fR,
\fB31\fR, or the more verbose
\fBmqttv5\fR,
\fBmqttv311\fR, or
\fBmqttv31\fR\&. Defaults to
\fB311\fR\&.
.RE
.PP
\fB\-W\fR
.RS 4
Provide a timeout as an integer number of seconds\&. mosquitto_sub 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\&.
.RE
.PP
\fB\-\-will\-payload\fR
.RS 4
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
\fB\-\-will\-topic\fR\&.
.RE
.PP
\fB\-\-will\-qos\fR
.RS 4
The QoS to use for the Will\&. Defaults to 0\&. This must be used in conjunction with
\fB\-\-will\-topic\fR\&.
.RE
.PP
\fB\-\-will\-retain\fR
.RS 4
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
\fB\-\-will\-topic\fR\&.
.RE
.PP
\fB\-\-will\-topic\fR
.RS 4
The topic on which to send a Will, in the event that the client disconnects unexpectedly\&.
.RE
.SH "OUTPUT FORMAT"
.PP
There are three ways of formatting the output from mosquitto_sub\&. In all cases a new\-line character is appended for each message received unless the
\fB\-N\fR
argument is passed to mosquitto_sub\&.
.PP
Payload\-only is the default output format and will print the payload exactly as it is received\&.
.PP
Verbose mode is activated with
\fB\-v\fR
and prints the message topic and the payload, separated by a space\&.
.PP
The final option is formatted output, which allows the user to define a custom output format\&. The behaviour is controlled with the
\fB\-F format\-string\fR
option\&. The format string is a free text string where interpreted sequences are replaced by different parameters\&. The available interpreted sequences are described below\&.
.PP
Three characters are used to start an interpreted sequence:
\fB%\fR,
\fB@\fR
and
\fB\e\fR\&. Sequences starting with
\fB%\fR
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
\fB@\fR
are passed to the
\fBstrftime\fR(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\&. mosquitto_sub does provide one extension to strftime which is
\fB@N\fR, 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
\fB\e\fR, which is used to input some characters that would otherwise be difficult to enter\&.
.SS "MQTT related parameters"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%%\fR
a literal %\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%l\fR
the length of the payload in bytes\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%m\fR
the message id (only relevant for messages with QoS>0)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%p\fR
the payload raw bytes (may produce non\-printable characters depending on the payload)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%q\fR
the message QoS\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%r\fR
the retained flag for the message\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%t\fR
the message topic\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%x\fR
the payload with each byte as a hexadecimal number (lower case)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%X\fR
the payload with each byte as a hexadecimal number (upper case)\&.
.RE
.SS "Helpers"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%I\fR
ISO\-8601 format date and time, e\&.g\&. 2016\-08\-10T09:47:38+0100
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%j\fR
JSON output of message parameters and timestamp, with a quoted and escaped payload\&. For example
{"tst":1470825369,"topic":"greeting","qos":0,"retain":0,"payload":"hello world"}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%J\fR
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":1470825369,"topic":"foo","qos":0,"retain":0,"payload":{"temperature":27\&.0,"humidity":57}}\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%I\fR
ISO\-8601 format date and time, e\&.g\&. 2016\-08\-10T09:47:38+0100
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB%U\fR
Unix timestamp with nanoseconds, e\&.g\&. 1470818943\&.786368637
.RE
.SS "Time related parameters"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB@@\fR
a literal @\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB@X\fR
pass the character represented by
\fBX\fR
to the strftime function as
\fB%X\fR\&. The options supported are platform dependent\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB@N\fR
the number of nanoseconds that have passed in the current second, with varying timing resolution depending on platform\&.
.RE
.SS "Escape characters"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\e\e\fR
a literal \e\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\e0\fR
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
\fBxargs\fR(1)
is easier\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\ea\fR
alert/bell\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\ee\fR
the escape sequence, which can be used with ANSI colour codes to provide coloured output for example\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\en\fR
end of line\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\er\fR
carriage return\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\et\fR
horizontal tab\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\ev\fR
vertical tab\&.
.RE
.SH "WILLS"
.PP
mosquitto_sub can register a message with the broker that will be sent out if it disconnects unexpectedly\&. See
\fBmqtt\fR(7)
for more information\&.
.PP
The minimum requirement for this is to use
\fB\-\-will\-topic\fR
to specify which topic the will should be sent out on\&. This will result in a non\-retained, zero length message with QoS 0\&.
.PP
Use the
\fB\-\-will\-retain\fR,
\fB\-\-will\-payload\fR
and
\fB\-\-will\-qos\fR
arguments to modify the other will parameters\&.
.SH "PROPERTIES"
.PP
The
\fB\-D\fR
/
\fB\-\-property\fR
option allows adding properties to different stages of the mosquitto_sub run\&. The properties supported for each command are as follows:
.SS "Connect"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBauthentication\-data\fR
(binary data \- note treated as a string in mosquitto_sub)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBauthentication\-method\fR
(UTF\-8 string pair)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmaximum\-packet\-size\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBreceive\-maximum\fR
(16\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBrequest\-problem\-information\fR
(8\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBrequest\-response\-information\fR
(8\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBsession\-expiry\-interval\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBtopic\-alias\-maximum\fR
(16\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Subscribe"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Unsubscribe"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Disconnect"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBsession\-expiry\-interval\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.SS "Will properties"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcontent\-type\fR
(UTF\-8 string)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcorrelation\-data\fR
(binary data \- note treated as a string in mosquitto_sub)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmessage\-expiry\-interval\fR
(32\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpayload\-format\-indicator\fR
(8\-bit unsigned integer)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBresponse\-topic\fR
(UTF\-8 string)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBuser\-property\fR
(UTF\-8 string pair)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBwill\-delay\-interval\fR
(32\-bit unsigned integer)
.RE
.SH "EXAMPLES"
.PP
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\&.
.PP
Subscribe to temperature information on localhost with QoS 1:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-t
sensors/temperature
\-q
1
.RE
.PP
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\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-t
sensors/machines/+/temperature/+
.RE
.PP
Subscribe to all broker status messages:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-v
\-t
\e$SYS/#
.RE
.PP
Specify the output format as "ISO\-8601 date : topic : payload in hex"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-F \*(Aq@Y\-@m\-@dT@H:@M:@S@z : %t : %x\*(Aq
\-t
\*(Aq#\*(Aq
.RE
.PP
Specify the output format as "seconds since epoch\&.nanoseconds : retained flag : qos : mid : payload length"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-F \*(Aq%@s\&.@N : %r : %q : %m : %l\*(Aq
\-q 2
\-t
\*(Aq#\*(Aq
.RE
.PP
Topic and payload output, but with colour where supported\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_sub
\-F \*(Aq\ee[92m%t \ee[96m%p\ee[0m\*(Aq
\-q 2
\-t
\*(Aq#\*(Aq
.RE
.SH "FILES"
.PP
$XDG_CONFIG_HOME/mosquitto_sub, $HOME/\&.config/mosquitto_sub
.RS 4
Configuration file for default options\&.
.RE
.SH "BUGS"
.PP
\fBmosquitto\fR
bug information can be found at
\m[blue]\fB\%https://github.com/eclipse/mosquitto/issues\fR\m[]
.SH "SEE ALSO"
\fBmqtt\fR(7), \fBmosquitto_pub\fR(1), \fBmosquitto_rr\fR(1), \fBmosquitto\fR(8), \fBlibmosquitto\fR(3), \fBmosquitto-tls\fR(7)
.SH "AUTHOR"
.PP
Roger Light