mosquitto/man/mosquitto_sub.1.xml
Roger A. Light 68f3b8428c Man page fixes and add version info to command args
Closes #3468. Thanks to Tom Earp.
2026-02-02 16:33:37 +00:00

568 lines
21 KiB
XML

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry [
<!ENTITY commandname "mosquitto_sub">
<!ENTITY from-version21 SYSTEM "common/version-2.1.xml">
<!ENTITY options-intro SYSTEM "common/options-intro.xml">
]>
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
<refentry xml:id="mosquitto_sub"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<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>
<arg choice='opt'>options</arg>
<group choice='req'>
<arg choice='plain' rep='repeat'><option>-t</option> <replaceable>message-topic</replaceable></arg>
<arg choice='plain' rep='repeat'><option>-U</option> <replaceable>unsubscribe-topic</replaceable></arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>options:</command>
<sbr/>
<arg>auth-options</arg>
<arg>connection-options</arg>
<arg>misc-options</arg>
<arg>mqtt-options</arg>
<arg>output-options</arg>
<group>
<arg choice='plain'>tls-certificate-options</arg>
<arg choice='plain'>tls-psk-options</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>auth-options:</command>
<sbr/>
<arg><option>-u</option> <replaceable>username</replaceable></arg>
<arg><option>-P</option> <replaceable>password</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>connection-options:</command>
<sbr/>
<group choice='req'>
<arg choice='plain'>
<arg><option>-h</option> <replaceable>hostname</replaceable></arg>
<arg><option>--unix</option> <replaceable>socket path</replaceable></arg>
<arg><option>-p</option> <replaceable>port-number</replaceable></arg>
</arg>
<arg choice='plain'>
<arg choice='plain'><option>-L</option> <replaceable>URL</replaceable></arg>
</arg>
</group>
<sbr/>
<arg><option>-A</option> <replaceable>bind-address</replaceable></arg>
<arg><option>--nodelay</option></arg>
<arg><option>-S</option></arg>
<arg><option>--ws</option></arg>
<arg><option>--proxy</option> <replaceable>socks-url</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>misc-options:</command>
<sbr/>
<arg><option>-E</option></arg>
<arg><option>-o</option> <replaceable>config-file</replaceable></arg>
<arg><option>-W</option> <replaceable>message-processing-timeout</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>mqtt-options:</command>
<sbr/>
<arg><option>-c</option></arg>
<arg><option>-D</option> <replaceable>command</replaceable> <replaceable>identifier</replaceable> <replaceable>value</replaceable></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>-q</option> <replaceable>message-QoS</replaceable></arg>
<arg><option>--retain-as-published</option></arg>
<arg><option>--retain-handling</option> always | new | never</arg>
<arg><option>-V</option> <replaceable>protocol-version</replaceable></arg>
<arg><option>-x</option> <replaceable>session-expiry-interval</replaceable></arg>
<sbr/>
<xi:include href="common/synopsis-will.xml" />
</cmdsynopsis>
<cmdsynopsis>
<command>output-options:</command>
<sbr/>
<arg><option>-d</option></arg>
<arg><option>-C</option> <replaceable>msg-count</replaceable></arg>
<arg><option>--message-rate</option></arg>
<arg><option>-N</option></arg>
<arg><option>--pretty</option></arg>
<arg><option>--random-filter</option> <replaceable>chance</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>--quiet</option></arg>
<arg choice='opt' rep='repeat'><option>-T</option> <replaceable>filter-out</replaceable></arg>
<arg><option>-v</option></arg>
<group choice='opt'>
<arg choice='plain'><option>-w</option></arg>
<arg choice='plain'><option>--watch</option></arg>
</group>
</cmdsynopsis>
<xi:include href="common/synopsis-tls-certificate-options.xml" />
<xi:include href="common/synopsis-tls-psk-options.xml" />
<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>
<xi:include href="common/section-encrypted-connections.xml" />
<refsect1>
<title>Options</title>
&options-intro;
<refsect2>
<title>The options</title>
<variablelist>
<xi:include href="common/option-bind.xml" />
<xi:include href="common/option-clean-session.xml" />
<xi:include href="common/option-tls-cafile.xml" />
<xi:include href="common/option-tls-capath.xml" />
<xi:include href="common/option-tls-cert.xml" />
<xi:include href="common/option-tls-ciphers.xml" />
<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> or <option>--retain-handling never</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>
<xi:include href="common/option-debug.xml" />
<xi:include href="common/option-property.xml" />
<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>
<xi:include href="common/option-format.xml" />
<xi:include href="common/option-help.xml" />
<xi:include href="common/option-host.xml" />
<xi:include href="common/option-clientid.xml" />
<xi:include href="common/option-clientid-prefix.xml" />
<xi:include href="common/option-tls-insecure.xml" />
<xi:include href="common/option-keepalive.xml" />
<xi:include href="common/option-tls-key.xml" />
<xi:include href="common/option-tls-keyform.xml" />
<xi:include href="common/option-url.xml" />
<varlistentry>
<term><option>--message-rate</option></term>
<listitem>
&from-version21;
<para>
Instead of printing the messages received, print a count
of the messages received at one second intervals. Other
options related to output formatting are not valid when
this option is active.
</para>
</listitem>
</varlistentry>
<xi:include href="common/option-format-no-eol.xml" />
<xi:include href="common/option-nodelay.xml" />
<xi:include href="common/option-no-tls.xml" />
<xi:include href="common/option-config-file.xml" />
<xi:include href="common/option-port.xml" />
<xi:include href="common/option-password.xml" />
<xi:include href="common/option-format-pretty.xml" />
<xi:include href="common/option-proxy.xml" />
<xi:include href="common/option-tls-psk.xml" />
<xi:include href="common/option-tls-psk-identity.xml" />
<xi:include href="common/option-qos-incoming.xml" />
<xi:include href="common/option-quiet.xml" />
<xi:include href="common/option-hide-retain.xml" />
<varlistentry>
<term><option>--random-filter</option></term>
<listitem>
<para>
This option can be used to reduce the proportion of
messages that mosquitto_sub prints. The default
behaviour is to print all incoming messages. Setting the
<replaceable>chance</replaceable> to a floating point value
between 0.1 and 100.0 will ensure that on average that
percentage of messages will be printed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remove-retained</option></term>
<listitem>
<para>
If this argument is given, then 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>
<xi:include href="common/option-retain-handling.xml" />
<xi:include href="common/option-srv.xml" />
<varlistentry>
<term><option>-t</option></term>
<term><option>--topic</option></term>
<listitem>
<para>
The MQTT topic to subscribe to. See
<citerefentry><refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></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>
<xi:include href="common/option-tls-alpn.xml" />
<xi:include href="common/option-tls-engine.xml" />
<xi:include href="common/option-tls-engine-kpass-sha1.xml" />
<xi:include href="common/option-tls-keylog.xml" />
<xi:include href="common/option-tls-use-os-certs.xml" />
<xi:include href="common/option-tls-version.xml" />
<xi:include href="common/option-username.xml" />
<xi:include href="common/option-unix-socket.xml" />
<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>
<xi:include href="common/option-format-verbose.xml" />
<xi:include href="common/option-protocol-version.xml" />
<xi:include href="common/option-timeout.xml" />
<varlistentry>
<term><option>-w</option></term>
<term><option>--watch</option></term>
<listitem>
&from-version21;
<para>
Messages will be printed on a fixed line number based on
the topic and order in which topics are received. Useful
for monitoring multiple topics that have single line
payloads. Unexpected behaviour will occur if there are
more topics than lines in the terminal, or if the
payload occupies more than a single line.
This can be used in conjuction with other output options
e.g. <option>-F</option>.
</para>
<para>
Requires ANSI escape code support in the terminal.
</para>
</listitem>
</varlistentry>
<xi:include href="common/option-will-payload.xml" />
<xi:include href="common/option-will-qos.xml" />
<xi:include href="common/option-will-retain.xml" />
<xi:include href="common/option-will-topic.xml" />
<xi:include href="common/option-websockets.xml" />
<xi:include href="common/option-session-expiry-interval.xml" />
</variablelist>
</refsect2>
</refsect1>
<xi:include href="common/section-output-format.xml" />
<xi:include href="common/section-wills.xml" />
<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>
<xi:include href="common/section-properties-connect.xml" />
<xi:include href="common/section-properties-subscribe.xml" />
<xi:include href="common/section-properties-unsubscribe.xml" />
<xi:include href="common/section-properties-disconnect.xml" />
<xi:include href="common/section-properties-will.xml" />
</refsect1>
<xi:include href="common/section-exit-status.xml" />
<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>
<term><filename>$HOME/snap/mosquitto/current/.config/mosquitto_sub</filename> (for snap installs)</term>
<listitem>
<para>Configuration file for default options.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="common/section-bugs.xml" />
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto-7.html">mosquitto</link></refentrytitle>
<manvolnum>7</manvolnum>
</citerefentry>
</member>
<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>