<?xml version='1.0' encoding='UTF-8'?>
|
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
|
|
<refentry xml:id="mosquitto_sub" xmlns:xlink="http://www.w3.org/1999/xlink">
|
<refmeta>
|
<refentrytitle>mosquitto_sub</refentrytitle>
|
<manvolnum>1</manvolnum>
|
<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
|
<refmiscinfo class="manual">Commands</refmiscinfo>
|
</refmeta>
|
|
<refnamediv>
|
<refname>mosquitto_sub</refname>
|
<refpurpose>an MQTT version 5/3.1.1/3.1 client for subscribing to topics</refpurpose>
|
</refnamediv>
|
|
<refsynopsisdiv>
|
<cmdsynopsis>
|
<command>mosquitto_sub</command>
|
<group choice='req'>
|
<arg choice='plain'>
|
<arg><option>-h</option> <replaceable>hostname</replaceable></arg>
|
<arg><option>-p</option> <replaceable>port-number</replaceable></arg>
|
<arg><option>-u</option> <replaceable>username</replaceable></arg>
|
<arg><option>-P</option> <replaceable>password</replaceable></arg>
|
<arg choice='plain' rep='repeat'><option>-t</option> <replaceable>message-topic</replaceable></arg>
|
</arg>
|
<arg choice='plain'>
|
<arg choice='plain'><option>-L</option> <replaceable>URL</replaceable></arg>
|
<arg choice='opt' rep='repeat'><option>-t</option> <replaceable>message-topic</replaceable></arg>
|
</arg>
|
</group>
|
<arg><option>-A</option> <replaceable>bind-address</replaceable></arg>
|
<arg><option>-c</option></arg>
|
<arg><option>-C</option> <replaceable>msg-count</replaceable></arg>
|
<arg><option>-d</option></arg>
|
<arg><option>-D</option> <replaceable>command</replaceable> <replaceable>identifier</replaceable> <replaceable>value</replaceable></arg>
|
<arg><option>-E</option></arg>
|
<arg><option>-i</option> <replaceable>client-id</replaceable></arg>
|
<arg><option>-I</option> <replaceable>client-id-prefix</replaceable></arg>
|
<arg><option>-k</option> <replaceable>keepalive-time</replaceable></arg>
|
<arg><option>-N</option></arg>
|
<arg><option>-q</option> <replaceable>message-QoS</replaceable></arg>
|
<arg><option>--remove-retained</option></arg>
|
<group choice='opt'>
|
<arg choice='plain'><option>-R</option></arg>
|
<arg choice='plain'><option>--retained-only</option></arg>
|
</group>
|
<arg><option>--retain-as-published</option></arg>
|
<arg><option>-S</option></arg>
|
<arg choice='opt' rep='repeat'><option>-T</option> <replaceable>filter-out</replaceable></arg>
|
<arg choice='opt' rep='repeat'><option>-U</option> <replaceable>unsub-topic</replaceable></arg>
|
<arg><option>-v</option></arg>
|
<arg><option>-V</option> <replaceable>protocol-version</replaceable></arg>
|
<arg><option>-W</option> <replaceable>message-processing-timeout</replaceable></arg>
|
<arg><option>--proxy</option> <replaceable>socks-url</replaceable></arg>
|
<arg><option>--quiet</option></arg>
|
<arg>
|
<option>--will-topic</option> <replaceable>topic</replaceable>
|
<arg><option>--will-payload</option> <replaceable>payload</replaceable></arg>
|
<arg><option>--will-qos</option> <replaceable>qos</replaceable></arg>
|
<arg><option>--will-retain</option></arg>
|
</arg>
|
<group>
|
<arg>
|
<group choice='req'>
|
<arg choice='plain'><option>--cafile</option> <replaceable>file</replaceable></arg>
|
<arg choice='plain'><option>--capath</option> <replaceable>dir</replaceable></arg>
|
</group>
|
<arg><option>--cert</option> <replaceable>file</replaceable></arg>
|
<arg><option>--key</option> <replaceable>file</replaceable></arg>
|
<arg><option>--tls-version</option> <replaceable>version</replaceable></arg>
|
<arg><option>--tls-alpn</option> <replaceable>protocol</replaceable></arg>
|
<arg><option>--tls-engine</option> <replaceable>engine</replaceable></arg>
|
<arg><option>--keyform</option>
|
<group choice='req'>
|
<arg choice='plain'><replaceable>pem</replaceable></arg>
|
<arg choice='plain'><replaceable>engine</replaceable></arg>
|
</group></arg>
|
<arg><option>--tls-engine-kpass-sha1</option> <replaceable>kpass-sha1</replaceable></arg>
|
<arg><option>--insecure</option></arg>
|
</arg>
|
<arg>
|
<arg choice='plain'><option>--psk</option> <replaceable>hex-key</replaceable></arg>
|
<arg choice='plain'><option>--psk-identity</option> <replaceable>identity</replaceable></arg>
|
<arg><option>--tls-version</option> <replaceable>version</replaceable></arg>
|
</arg>
|
</group>
|
</cmdsynopsis>
|
<cmdsynopsis>
|
<command>mosquitto_sub</command>
|
<group choice='plain'>
|
<arg><option>--help</option></arg>
|
</group>
|
</cmdsynopsis>
|
</refsynopsisdiv>
|
|
<refsect1>
|
<title>Description</title>
|
<para><command>mosquitto_sub</command> is a simple MQTT version 5/3.1.1
|
client that will subscribe to topics and print the messages that
|
it receives.</para>
|
<para>In addition to subscribing to topics,
|
<command>mosquitto_sub</command> can filter out received messages
|
so they are not printed (see the <option>-T</option> option) or
|
unsubscribe from topics (see the <option>-U</option> option).
|
Unsubscribing from topics is useful for clients connecting with
|
clean session set to false. </para>
|
</refsect1>
|
|
<refsect1>
|
<title>Encrypted Connections</title>
|
<para><command>mosquitto_sub</command> supports TLS encrypted
|
connections. It is strongly recommended that you use an encrypted
|
connection for anything more than the most basic setup.</para>
|
<para>To enable TLS connections when using x509 certificates, one of
|
either <option>--cafile</option> or <option>--capath</option> must
|
be provided as an option.</para>
|
<para>To enable TLS connections when using TLS-PSK, you must use the
|
<option>--psk</option> and the <option>--psk-identity</option>
|
options.</para>
|
</refsect1>
|
|
<refsect1>
|
<title>Options</title>
|
<para>The options below may be given on the command line, but may also
|
be placed in a config file located at
|
<option>$XDG_CONFIG_HOME/mosquitto_sub</option> or
|
<option>$HOME/.config/mosquitto_sub</option> with one pair of
|
<option>-option <replaceable>value</replaceable></option>
|
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 <option>-t</option> and <option>-T</option>, which if
|
given in the config file will not be overridden. Note also that
|
currently some options cannot be negated, e.g.
|
<option>-S</option>. Config file lines that have a
|
<option>#</option> as the first character are treated as comments
|
and not processed any further.</para>
|
<variablelist>
|
<varlistentry>
|
<term><option>-A</option></term>
|
<listitem>
|
<para>Bind the outgoing connection to a local ip
|
address/hostname. Use this argument if you need to
|
restrict network communication to a particular
|
interface.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-c</option></term>
|
<term><option>--disable-clean-session</option></term>
|
<listitem>
|
<para>Disable the 'clean session' 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.</para>
|
<para>If using this option, the client id must be set
|
manually with <option>--id</option></para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--cafile</option></term>
|
<listitem>
|
<para>Define the path to a file containing PEM encoded CA
|
certificates that are trusted. Used to enable SSL
|
communication.</para>
|
<para>See also <option>--capath</option></para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--capath</option></term>
|
<listitem>
|
<para>Define the path to a directory containing PEM encoded CA
|
certificates that are trusted. Used to enable SSL
|
communication.</para>
|
<para>For <option>--capath</option> 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.</para>
|
<para>See also <option>--cafile</option></para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--cert</option></term>
|
<listitem>
|
<para>Define the path to a file containing a PEM encoded
|
certificate for this client, if required by the
|
server.</para>
|
<para>See also <option>--key</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--ciphers</option></term>
|
<listitem>
|
<para>An openssl compatible list of TLS ciphers to support
|
in the client. See
|
<citerefentry><refentrytitle>ciphers</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
for more information.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-C</option></term>
|
<listitem>
|
<para>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.</para>
|
<para>Combine with <option>-R</option> to print only the
|
first set of fresh messages (i.e. that does not have
|
the retained flag set), or with <option>-T</option> to
|
filter which topics are processed.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-d</option></term>
|
<term><option>--debug</option></term>
|
<listitem>
|
<para>Enable debug messages.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-D</option></term>
|
<term><option>--property</option></term>
|
<listitem>
|
<para>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:</para>
|
<para><option>-D command identifier value</option></para>
|
<para><option>-D command identifier name value</option></para>
|
<para><option>command</option> 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.</para>
|
|
<para><option>identifier</option> is the name of the
|
property to add. This is as described in the
|
specification, but with '-' as a word separator. For
|
example:
|
<option>payload-format-indicator</option>. More details
|
are in the <link linkend='properties'>Properties</link>
|
section.</para>
|
|
<para><option>value</option> is the value of the property
|
to add, with a data type that is property
|
specific.</para>
|
|
<para><option>name</option> is only used for the
|
<option>user-property</option> property as the first of
|
the two strings in the string pair. In that case,
|
<option>value</option> is the second of the strings in
|
the pair.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-E</option></term>
|
<listitem>
|
<para>If this option is given,
|
<command>mosquitto_sub</command> will exit immediately
|
that all of its subscriptions have been acknowledged by
|
the broker. In conjunction with <option>-c</option>
|
this allows a durable client session to be initialised
|
on the broker for future use without requiring any
|
messages to be received.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-F</option></term>
|
<listitem>
|
<para>Specify output printing format. This option allows
|
you to choose what information from each message is
|
printed to the screen. See the <link
|
linkend='outputformat'>Output Format</link> section
|
below for full details.</para>
|
<para>This option overrides the <option>-v</option> option,
|
but does not override the <option>-N</option>
|
option.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--help</option></term>
|
<listitem>
|
<para>Display usage information.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-h</option></term>
|
<term><option>--host</option></term>
|
<listitem>
|
<para>Specify the host to connect to. Defaults to localhost.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-i</option></term>
|
<term><option>--id</option></term>
|
<listitem>
|
<para>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
|
<option>--id-prefix</option> argument.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-I</option></term>
|
<term><option>--id-prefix</option></term>
|
<listitem>
|
<para>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
|
<option>--id</option> argument.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--insecure</option></term>
|
<listitem>
|
<para>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 <emphasis>only</emphasis>. 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.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-k</option></term>
|
<term><option>--keepalive</option></term>
|
<listitem>
|
<para>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.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--key</option></term>
|
<listitem>
|
<para>Define the path to a file containing a PEM encoded
|
private key for this client, if required by the
|
server.</para>
|
<para>See also <option>--cert</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--keyform</option></term>
|
<listitem>
|
<para>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.</para>
|
<para>See also <option>--tls-engine</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-L</option></term>
|
<term><option>--url</option></term>
|
<listitem>
|
<para>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</para>
|
<para>If the scheme is mqtt:// then the port defaults to
|
1883. If the scheme is mqtts:// then the port defaults
|
to 8883.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-N</option></term>
|
<listitem>
|
<para>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
|
<option>-v</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-p</option></term>
|
<term><option>--port</option></term>
|
<listitem>
|
<para>Connect to the port specified. If not given, the
|
default of 1883 for plain MQTT or 8883 for MQTT over
|
TLS will be used.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-P</option></term>
|
<term><option>--pw</option></term>
|
<listitem>
|
<para>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 <option>--username</option> option.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--proxy</option></term>
|
<listitem>
|
<para>Specify a SOCKS5 proxy to connect through. "None" and
|
"username" authentication types are supported. The
|
<option>socks-url</option> must be of the form
|
<option>socks5h://[username[:password]@]host[:port]</option>.
|
The protocol prefix <option>socks5h</option> 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.</para>
|
<para>If username is not given, then no authentication is
|
attempted. If the port is not given, then the default
|
of 1080 is used.</para>
|
<para>More SOCKS versions may be available in the future,
|
depending on demand, and will use different protocol
|
prefixes as described in <citerefentry>
|
<refentrytitle>curl</refentrytitle>
|
<manvolnum>1</manvolnum> </citerefentry>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--psk</option></term>
|
<listitem>
|
<para>Provide the hexadecimal (no leading 0x)
|
pre-shared-key matching the one used on the broker to
|
use TLS-PSK encryption support.
|
<option>--psk-identity</option> must also be provided
|
to enable TLS-PSK.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--psk-identity</option></term>
|
<listitem>
|
<para>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.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-q</option></term>
|
<term><option>--qos</option></term>
|
<listitem>
|
<para>Specify the quality of service desired for the
|
incoming messages, from 0, 1 and 2. Defaults to 0. See
|
<citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
for more information on QoS.</para>
|
<para>The QoS is identical for all topics subscribed to in
|
a single instance of mosquitto_sub.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--quiet</option></term>
|
<listitem>
|
<para>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 <option>--port</option> without a
|
port).</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-R</option></term>
|
<listitem>
|
<para>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.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--remove-retained</option></term>
|
<listitem>
|
<para>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 <option>-T</option>
|
option. This option still takes effect even if
|
<option>-R</option> is used. See also the
|
<option>--retain-as-published</option> and
|
<option>--retained-only</option> options.</para>
|
|
<example title="remove-retained-example-1" label="1">
|
<para>Remove all retained messages on the server,
|
assuming we have access to do so, and then exit:</para>
|
|
<programlisting language="config">
|
mosquitto_sub -t '#' --remove-retained --retained-only</programlisting>
|
</example>
|
|
<example title="remove-retained-example-2" label="2">
|
<para>Remove a whole tree, with the exception of a
|
single topic:</para>
|
|
<programlisting language="config">
|
mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained</programlisting>
|
</example>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--retained-only</option></term>
|
<listitem>
|
<para>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
|
<option>--retain-as-published</option> option.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--retain-as-published</option></term>
|
<listitem>
|
<para>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.</para>
|
<para>This option is not valid for MQTT v3.1/v3.1.1
|
clients.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-S</option></term>
|
<listitem>
|
<para>Use SRV lookups to determine which host to connect
|
to. Performs lookups to
|
<option>_mqtt._tcp.<host></option> when used in
|
conjunction with <option>-h</option>, otherwise uses
|
<option>_mqtt._tcp.<local dns
|
domain></option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-t</option></term>
|
<term><option>--topic</option></term>
|
<listitem>
|
<para>The MQTT topic to subscribe to. See
|
<citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
for more information on MQTT topics.</para>
|
<para>This option may be repeated to subscribe to multiple topics.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-T</option></term>
|
<term><option>--filter-out</option></term>
|
<listitem>
|
<para>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.</para>
|
<para>For example, subscribe to the BBC tree, but suppress output from Radio 3:</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-t</literal>
|
bbc/# <literal>-T</literal>
|
bbc/radio3</para></listitem>
|
</itemizedlist>
|
<para>This option may be repeated to filter out multiple
|
topics or topic trees.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--tls-alpn</option></term>
|
<listitem>
|
<para>Provide a protocol to use when connecting to a broker
|
that has multiple protocols available on a single port,
|
e.g. MQTT and WebSockets.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--tls-engine</option></term>
|
<listitem>
|
<para>A valid openssl engine id. These can be listed with
|
openssl engine command.</para>
|
<para>See also <option>--keyform</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--tls-engine-kpass-sha1</option></term>
|
<listitem>
|
<para>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.</para>
|
<para>See also <option>--tls-engine</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--tls-version</option></term>
|
<listitem>
|
<para>Choose which TLS protocol version to use when
|
communicating with the broker. Valid options are
|
<option>tlsv1.3</option>, <option>tlsv1.2</option> and
|
<option>tlsv1.1</option>. The default value is
|
<option>tlsv1.2</option>. Must match the protocol
|
version used by the broker.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-u</option></term>
|
<term><option>--username</option></term>
|
<listitem>
|
<para>Provide a username to be used for authenticating with
|
the broker. See also the <option>--pw</option>
|
argument.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-U</option></term>
|
<term><option>--unsubscribe</option></term>
|
<listitem>
|
<para>A topic that will be unsubscribed from. This may be
|
used on its own or in conjunction with the
|
<option>--topic</option> option and only makes sense
|
when used in conjunction with
|
<option>--clean-session</option>.</para>
|
<para>If used with <option>--topic</option> then
|
subscriptions will be processed before
|
unsubscriptions.</para>
|
<para>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 <option>sensors/#</option> and
|
then unsubscribing from
|
<option>sensors/+/temperature</option> as shown below
|
will still result in messages matching the
|
<option>sensors/+/temperature</option> being delivered
|
to the client.</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-t</literal> sensors/# <literal>-U</literal> sensors/+/temperature <literal>-v</literal></para></listitem>
|
</itemizedlist>
|
|
<para>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.</para>
|
|
<para>This option may be repeated to unsubscribe from multiple topics.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-v</option></term>
|
<term><option>--verbose</option></term>
|
<listitem>
|
<para>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".</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-V</option></term>
|
<term><option>--protocol-version</option></term>
|
<listitem>
|
<para>Specify which version of the MQTT protocol should be
|
used when connecting to the remote broker. Can be
|
<option>5</option>, <option>311</option>,
|
<option>31</option>, or the more verbose
|
<option>mqttv5</option>, <option>mqttv311</option>, or
|
<option>mqttv31</option>.
|
Defaults to <option>311</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>-W</option></term>
|
<listitem>
|
<para>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.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--will-payload</option></term>
|
<listitem>
|
<para>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 <option>--will-topic</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--will-qos</option></term>
|
<listitem>
|
<para>The QoS to use for the Will. Defaults to 0. This must
|
be used in conjunction with <option>--will-topic</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--will-retain</option></term>
|
<listitem>
|
<para>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 <option>--will-topic</option>.</para>
|
</listitem>
|
</varlistentry>
|
<varlistentry>
|
<term><option>--will-topic</option></term>
|
<listitem>
|
<para>The topic on which to send a Will, in the event that
|
the client disconnects unexpectedly.</para>
|
</listitem>
|
</varlistentry>
|
</variablelist>
|
</refsect1>
|
|
<refsect1 id='outputformat'>
|
<title>Output format</title>
|
<para>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 <option>-N</option> argument is passed to
|
mosquitto_sub.</para>
|
<para>Payload-only is the default output format and will
|
print the payload exactly as it is received.</para>
|
<para>Verbose mode is activated with <option>-v</option> and prints the
|
message topic and the payload, separated by a space.</para>
|
<para>The final option is formatted output, which allows the user to
|
define a custom output format. The behaviour is controlled with
|
the <option>-F format-string</option> option. The format string is
|
a free text string where interpreted sequences are replaced by
|
different parameters. The available interpreted sequences are
|
described below.</para>
|
<para>Three characters are used to start an interpreted sequence:
|
<option>%</option>, <option>@</option> and <option>\</option>.
|
Sequences starting with <option>%</option> 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 <option>@</option> are passed to the
|
<citerefentry><refentrytitle>strftime</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
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
|
<option>@N</option>, 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 <option>\</option>, which is used to input some
|
characters that would otherwise be difficult to enter.</para>
|
|
<refsect2>
|
<title>MQTT related parameters</title>
|
<itemizedlist mark="circle">
|
<listitem><para><option>%%</option> a literal %.</para></listitem>
|
<listitem><para><option>%l</option> the length of the payload in bytes.</para></listitem>
|
<listitem><para><option>%m</option> the message id (only relevant for messages with QoS>0).</para></listitem>
|
<listitem><para><option>%p</option> the payload raw bytes (may produce non-printable characters depending on the payload).</para></listitem>
|
<listitem><para><option>%q</option> the message QoS.</para></listitem>
|
<listitem><para><option>%r</option> the retained flag for the message.</para></listitem>
|
<listitem><para><option>%t</option> the message topic.</para></listitem>
|
<listitem><para><option>%x</option> the payload with each byte as a hexadecimal number (lower case).</para></listitem>
|
<listitem><para><option>%X</option> the payload with each byte as a hexadecimal number (upper case).</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
|
<refsect2>
|
<title>Helpers</title>
|
<itemizedlist mark="circle">
|
<listitem><para><option>%I</option> ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100</para></listitem>
|
<listitem><para><option>%j</option> JSON output of message
|
parameters and timestamp, with a quoted and escaped
|
payload. For example
|
<code>{"tst":1470825369,"topic":"greeting","qos":0,"retain":0,"payload":"hello
|
world"}</code></para></listitem>
|
<listitem><para><option>%J</option> 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:
|
<code>{"tst":1470825369,"topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}</code>.</para></listitem>
|
<listitem><para><option>%I</option> ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100</para></listitem>
|
<listitem><para><option>%U</option> Unix timestamp with nanoseconds, e.g. 1470818943.786368637</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
|
<refsect2>
|
<title>Time related parameters</title>
|
<itemizedlist mark="circle">
|
<listitem><para><option>@@</option> a literal @.</para></listitem>
|
<listitem><para><option>@X</option> pass the character represented
|
by <option>X</option> to the strftime function as
|
<option>%X</option>. The options supported are platform
|
dependent.</para></listitem>
|
<listitem><para><option>@N</option> the number of nanoseconds that
|
have passed in the current second, with varying timing
|
resolution depending on platform.</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
|
<refsect2>
|
<title>Escape characters</title>
|
<itemizedlist mark="circle">
|
<listitem><para><option>\\</option> a literal \.</para></listitem>
|
<listitem><para><option>\0</option> 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
|
<citerefentry><refentrytitle>xargs</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
is easier.</para></listitem>
|
<listitem><para><option>\a</option> alert/bell.</para></listitem>
|
<listitem><para><option>\e</option> the escape sequence, which can
|
be used with ANSI colour codes to provide coloured output
|
for example.</para></listitem>
|
<listitem><para><option>\n</option> end of line.</para></listitem>
|
<listitem><para><option>\r</option> carriage return.</para></listitem>
|
<listitem><para><option>\t</option> horizontal tab.</para></listitem>
|
<listitem><para><option>\v</option> vertical tab.</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
</refsect1>
|
|
<refsect1>
|
<title>Wills</title>
|
<para>mosquitto_sub can register a message with the broker that will be
|
sent out if it disconnects unexpectedly. See
|
<citerefentry><refentrytitle>mqtt</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
for more information.</para>
|
<para>The minimum requirement for this is to use <option>--will-topic</option> to
|
specify which topic the will should be sent out on. This will result in
|
a non-retained, zero length message with QoS 0.</para>
|
<para>Use the <option>--will-retain</option>, <option>--will-payload</option> and <option>--will-qos</option> arguments to
|
modify the other will parameters.</para>
|
</refsect1>
|
|
<refsect1 id='properties'>
|
<title>Properties</title>
|
<para>The <option>-D</option> / <option>--property</option> option
|
allows adding properties to different stages of the mosquitto_sub
|
run. The properties supported for each command are as
|
follows:</para>
|
|
<refsect2>
|
<title>Connect</title>
|
<itemizedlist>
|
<listitem><para><option>authentication-data</option> (binary data - note treated as a string in mosquitto_sub)</para></listitem>
|
<listitem><para><option>authentication-method</option> (UTF-8 string pair)</para></listitem>
|
<listitem><para><option>maximum-packet-size</option> (32-bit unsigned integer)</para></listitem>
|
<listitem><para><option>receive-maximum</option> (16-bit unsigned integer)</para></listitem>
|
<listitem><para><option>request-problem-information</option> (8-bit unsigned integer)</para></listitem>
|
<listitem><para><option>request-response-information</option> (8-bit unsigned integer)</para></listitem>
|
<listitem><para><option>session-expiry-interval</option> (32-bit unsigned integer)</para></listitem>
|
<listitem><para><option>topic-alias-maximum</option> (16-bit unsigned integer)</para></listitem>
|
<listitem><para><option>user-property</option> (UTF-8 string pair)</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
|
<refsect2>
|
<title>Subscribe</title>
|
<itemizedlist>
|
<listitem><para><option>user-property</option> (UTF-8 string pair)</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
|
<refsect2>
|
<title>Unsubscribe</title>
|
<itemizedlist>
|
<listitem><para><option>user-property</option> (UTF-8 string pair)</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
|
<refsect2>
|
<title>Disconnect</title>
|
<itemizedlist>
|
<listitem><para><option>session-expiry-interval</option> (32-bit unsigned integer)</para></listitem>
|
<listitem><para><option>user-property</option> (UTF-8 string pair)</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
|
<refsect2>
|
<title>Will properties</title>
|
<itemizedlist>
|
<listitem><para><option>content-type</option> (UTF-8 string)</para></listitem>
|
<listitem><para><option>correlation-data</option> (binary data - note treated as a string in mosquitto_sub)</para></listitem>
|
<listitem><para><option>message-expiry-interval</option> (32-bit unsigned integer)</para></listitem>
|
<listitem><para><option>payload-format-indicator</option> (8-bit unsigned integer)</para></listitem>
|
<listitem><para><option>response-topic</option> (UTF-8 string)</para></listitem>
|
<listitem><para><option>user-property</option> (UTF-8 string pair)</para></listitem>
|
<listitem><para><option>will-delay-interval</option> (32-bit unsigned integer)</para></listitem>
|
</itemizedlist>
|
</refsect2>
|
</refsect1>
|
|
<refsect1>
|
<title>Examples</title>
|
<para>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.</para>
|
<para>Subscribe to temperature information on localhost with QoS 1:</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-t</literal> sensors/temperature <literal>-q</literal> 1</para></listitem>
|
</itemizedlist>
|
<para>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.</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-t</literal> sensors/machines/+/temperature/+</para></listitem>
|
</itemizedlist>
|
<para>Subscribe to all broker status messages:</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-v</literal> <literal>-t</literal> \$SYS/#</para></listitem>
|
</itemizedlist>
|
|
<para>Specify the output format as "ISO-8601 date : topic : payload in hex"</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-F '@Y-@m-@dT@H:@M:@S@z : %t : %x'</literal> <literal>-t</literal> '#'</para></listitem>
|
</itemizedlist>
|
|
<para>Specify the output format as "seconds since epoch.nanoseconds : retained flag : qos : mid : payload length"</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-F '%@s.@N : %r : %q : %m : %l'</literal> <literal>-q 2</literal> <literal>-t</literal> '#'</para></listitem>
|
</itemizedlist>
|
|
<para>Topic and payload output, but with colour where supported.</para>
|
<itemizedlist mark="circle">
|
<listitem><para>mosquitto_sub <literal>-F '\e[92m%t \e[96m%p\e[0m'</literal> <literal>-q 2</literal> <literal>-t</literal> '#'</para></listitem>
|
</itemizedlist>
|
</refsect1>
|
|
<refsect1>
|
<title>Files</title>
|
<variablelist>
|
<varlistentry>
|
<term><filename>$XDG_CONFIG_HOME/mosquitto_sub</filename></term>
|
<term><filename>$HOME/.config/mosquitto_sub</filename></term>
|
<listitem>
|
<para>Configuration file for default options.</para>
|
</listitem>
|
</varlistentry>
|
</variablelist>
|
</refsect1>
|
|
<refsect1>
|
<title>Bugs</title>
|
<para><command>mosquitto</command> bug information can be found at
|
<ulink url="https://github.com/eclipse/mosquitto/issues"/></para>
|
</refsect1>
|
|
<refsect1>
|
<title>See Also</title>
|
<simplelist type="inline">
|
<member>
|
<citerefentry>
|
<refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
|
<manvolnum>7</manvolnum>
|
</citerefentry>
|
</member>
|
<member>
|
<citerefentry>
|
<refentrytitle><link xlink:href="mosquitto_pub-1.html">mosquitto_pub</link></refentrytitle>
|
<manvolnum>1</manvolnum>
|
</citerefentry>
|
</member>
|
<member>
|
<citerefentry>
|
<refentrytitle><link xlink:href="mosquitto_rr-1.html">mosquitto_rr</link></refentrytitle>
|
<manvolnum>1</manvolnum>
|
</citerefentry>
|
</member>
|
<member>
|
<citerefentry>
|
<refentrytitle><link xlink:href="mosquitto-8.html">mosquitto</link></refentrytitle>
|
<manvolnum>8</manvolnum>
|
</citerefentry>
|
</member>
|
<member>
|
<citerefentry>
|
<refentrytitle><link xlink:href="libmosquitto-3.html">libmosquitto</link></refentrytitle>
|
<manvolnum>3</manvolnum>
|
</citerefentry>
|
</member>
|
<member>
|
<citerefentry>
|
<refentrytitle><link xlink:href="mosquitto-tls-7.html">mosquitto-tls</link></refentrytitle>
|
<manvolnum>7</manvolnum>
|
</citerefentry>
|
</member>
|
</simplelist>
|
</refsect1>
|
|
<refsect1>
|
<title>Author</title>
|
<para>Roger Light <email>roger@atchoo.org</email></para>
|
</refsect1>
|
</refentry>
|
