<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry [
	<!ENTITY commandname "mosquitto_rr">
	<!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_rr"
		xmlns:xlink="http://www.w3.org/1999/xlink"
		xmlns:xi="http://www.w3.org/2001/XInclude">

	<refmeta>
		<refentrytitle>mosquitto_rr</refentrytitle>
		<manvolnum>1</manvolnum>
		<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
		<refmiscinfo class="manual">Commands</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>mosquitto_rr</refname>
		<refpurpose>an MQTT version 5/3.1.1 client for request/response messaging</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>mosquitto_rr</command>
			<arg choice='opt'>options</arg>
			<arg choice='plain'><option>-e</option> <replaceable>response-topic</replaceable></arg>
			<arg choice='plain' rep='repeat'><option>-t</option> <replaceable>message-topic</replaceable></arg>
			<arg choice='req'>payload-options</arg>
		</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>--latency</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-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>-N</option></arg>
			<arg><option>--pretty</option></arg>
			<arg><option>--quiet</option></arg>
			<arg><option>-R</option></arg>
			<arg><option>-v</option></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>payload-options:</command>
			<sbr/>
			<group choice='plain'>
				<arg choice='plain'><option>-f</option> <replaceable>file</replaceable></arg>
				<arg choice='plain'><option>-m</option> <replaceable>message</replaceable></arg>
				<arg choice='plain'><option>-n</option></arg>
				<arg choice='plain'><option>-s</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_rr</command>
			<group choice='plain'>
				<arg><option>--help</option></arg>
			</group>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			<command>mosquitto_rr</command> is an MQTT version 5/3.1.1 client
			that can be used to publish a request message and wait for a
			response. When using MQTT v5, which is the default, <command>mosquitto_rr</command>
			will use the Request-Response feature.
		</para>
		<para>
			The important options are <option>-t</option>, <option>-e</option>,
			and one of <option>-f</option>, <option>-m</option>, <option>-n</option>,
			and <option>-s</option>.
		</para>
		<para>
			Example: <code>mosquitto_rr -t request-topic -e response-topic -m message</code>
		</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" />
				<xi:include href="common/option-debug.xml" />
				<xi:include href="common/option-property.xml" />
				<varlistentry>
					<term><option>-e</option></term>
					<listitem>
						<para>
							Response topic. The client will subscribe to this topic to wait for a response.
						</para>
					</listitem>
				</varlistentry>
				<xi:include href="common/option-payload-file.xml" />
				<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>--latency</option></term>
					<listitem>
						&from-version21;
						<para>
							If this option is specified, mosquitto_rr will print out
							the latency between it starting to publish a request and
							the response arriving. This number includes both the
							broker and client processing times, as well as any
							inherent network latency.
						</para>

						<para>
							This can be used to measure message delivery latency
							very simply by specifying an identical request and
							response topic.
						</para>
						<para>
							The <option>--nodelay</option> option will be automatically
							used when <option>--latency</option> is in use.
						</para>
					</listitem>
				</varlistentry>
				<xi:include href="common/option-payload-message.xml" />
				<xi:include href="common/option-format-no-eol.xml" />
				<xi:include href="common/option-payload-null.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" />
				<xi:include href="common/option-retain-handling.xml" />
				<xi:include href="common/option-srv.xml" />
				<xi:include href="common/option-payload-stdin-file.xml" />
				<varlistentry>
					<term><option>-t</option></term>
					<term><option>--topic</option></term>
					<listitem>
						<para>
							The MQTT topic where the request message will be sent.
						</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" />
				<xi:include href="common/option-format-verbose.xml" />
				<xi:include href="common/option-protocol-version.xml" />
				<xi:include href="common/option-timeout.xml" />
				<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_rr
			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-publish.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>Files</title>
		<variablelist>
			<varlistentry>
				<term><filename>$XDG_CONFIG_HOME/mosquitto_rr</filename></term>
				<term><filename>$HOME/.config/mosquitto_rr</filename></term>
				<term><filename>$HOME/snap/mosquitto/current/.config/mosquitto_rr</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_sub-1.html">mosquitto_sub</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>
