<?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>
