'\" t
.\"     Title: mosquitto_sub
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 08/06/2014
.\"    Manual: Commands
.\"    Source: Mosquitto Project
.\"  Language: English
.\"
.TH "MOSQUITTO_SUB" "1" "08/06/2014" "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 3\&.1 client for subscribing to topics
.SH "SYNOPSIS"
.HP \w'\fBmosquitto_sub\fR\ 'u
\fBmosquitto_sub\fR [\fB\-A\fR\ \fIbind_address\fR] [\fB\-c\fR] [\fB\-d\fR] [\fB\-h\fR\ \fIhostname\fR] [\fB\-i\fR\ \fIclient_id\fR] [\fB\-I\fR\ \fIclient\ id\ prefix\fR] [\fB\-k\fR\ \fIkeepalive\ time\fR] [\fB\-p\fR\ \fIport\ number\fR] [\fB\-q\fR\ \fImessage\ QoS\fR] [\fB\-R\fR] [\fB\-S\fR] [\fB\-N\fR] [\fB\-\-quiet\fR] [\fB\-v\fR] [[\fB\-u\fR\ \fIusername\fR]\ [\fB\-P\fR\ \fIpassword\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\-\-insecure\fR]] | [\fB\-\-psk\fR\ \fIhex\-key\fR\ \fB\-\-psk\-identity\fR\ \fIidentity\fR\ [\fB\-\-tls\-version\fR\ \fIversion\fR]]] [\fB\-T\fR\ \fIfilter\-out\fR...] \fB\-t\fR\ \fImessage\-topic\fR...
.HP \w'\fBmosquitto_sub\fR\ 'u
\fBmosquitto_sub\fR [\fB\-\-help\fR] 
.SH "DESCRIPTION"
.PP
\fBmosquitto_sub\fR
is a simple MQTT version 3\&.1 client that will subscribe to a topic and print the messages that it receives\&.
.SH "OPTIONS"
.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, it is recommended that the client id is 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 "c_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\-d\fR, \fB\-\-debug\fR
.RS 4
Enable debug messages\&.
.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\-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 instead of the default 1883\&.
.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\&. This requires a broker that supports MQTT v3\&.1\&. See also the
\fB\-\-username\fR
option\&.
.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\-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\-version\fR
.RS 4
Choose which TLS protocol version to use when communicating with the broker\&. Valid options are
\fBtlsv1\&.2\fR,
\fBtlsv1\&.1\fR
and
\fBtlsv1\fR\&. The default value is
\fBtlsv1\&.2\fR\&. If the installed version of openssl is too old, only
\fBtlsv1\fR
will be available\&. 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\&. This requires a broker that supports MQTT v3\&.1\&. See also the
\fB\-\-pw\fR
argument\&.
.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\-\-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 "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 "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
.SH "BUGS"
.PP
\fBmosquitto_sub\fR
bug information can be found at
http://launchpad\&.net/mosquitto
.SH "SEE ALSO"
\fBmqtt\fR(7), \fBmosquitto_pub\fR(1), \fBmosquitto\fR(8), \fBlibmosquitto\fR(3), \fBmosquitto-tls\fR(7)
.SH "ACKNOWLEDGEMENTS"
.PP
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit\&. (http://www\&.openssl\&.org/)
.PP
This product includes cryptographic software written by Eric Young (eay@cryptsoft\&.com)
.PP
This product includes software written by Tim Hudson (tjh@cryptsoft\&.com)
.SH "AUTHOR"
.PP
Roger Light
<roger@atchoo\&.org>