'\" t
|
.\" Title: mosquitto_sub
|
.\" Author: [see the "Author" section]
|
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
.\" Date: 06/18/2019
|
.\" Manual: Commands
|
.\" Source: Mosquitto Project
|
.\" Language: English
|
.\"
|
.TH "MOSQUITTO_SUB" "1" "06/18/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 <path to capath>" 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, defaults to mosquitto_sub_ appended with the process id of the client\&. 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\&.<host>\fR
|
when used in conjunction with
|
\fB\-h\fR, otherwise uses
|
\fB_mqtt\&._tcp\&.<local dns domain>\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
|
<roger@atchoo\&.org>
|
