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

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

	<refnamediv>
		<refname>mosquitto_pub</refname>
		<refpurpose>an MQTT version 5/3.1.1/3.1 client for publishing simple messages</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>mosquitto_pub</command>
			<arg choice='opt'>options</arg>
			<arg choice='plain'><option>-t</option> <replaceable>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>
			<arg>publish-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'><option>-L</option> <replaceable>URL</replaceable></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>
			<sbr/>
			<arg><option>--proxy</option> <replaceable>socks-url</replaceable></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>misc-options:</command>
			<sbr/>
			<arg><option>-o</option> <replaceable>config-file</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>-x</option> <replaceable>session-expiry-interval</replaceable></arg>
			<arg><option>-V</option> <replaceable>protocol-version</replaceable></arg>
			<sbr/>
			<xi:include href="common/synopsis-will.xml" />
		</cmdsynopsis>
		<cmdsynopsis>
			<command>output-options:</command>
			<sbr/>
			<arg><option>-d</option></arg>
			<arg><option>--quiet</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>-l</option></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>
		<cmdsynopsis>
			<command>publish-options:</command>
			<sbr/>
			<arg><option>-q</option> <replaceable>message-QoS</replaceable></arg>
			<arg><option>-r</option></arg>
			<arg><option>--repeat</option> <replaceable>count</replaceable></arg>
			<arg><option>--repeat-delay</option> <replaceable>seconds</replaceable></arg>
		</cmdsynopsis>
		<xi:include href="common/synopsis-tls-certificate-options.xml" />
		<xi:include href="common/synopsis-tls-psk-options.xml" />

		<cmdsynopsis>
			<command>mosquitto_pub</command>
			<group choice='plain'>
				<arg><option>--help</option></arg>
			</group>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			<command>mosquitto_pub</command> is a simple MQTT version 5/3.1.1
			client that will publish a single message on a topic and exit.
		</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" />
				<xi:include href="common/option-payload-file.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>-l</option></term>
					<term><option>--stdin-line</option></term>
					<listitem>
						<para>
							Send messages read from stdin, splitting separate lines into separate messages.
						</para>
					</listitem>
				</varlistentry>
				<xi:include href="common/option-payload-message.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-proxy.xml" />
				<xi:include href="common/option-tls-psk.xml" />
				<xi:include href="common/option-tls-psk-identity.xml" />
				<varlistentry>
					<term><option>-q</option></term>
					<term><option>--qos</option></term>
					<listitem>
						<para>
							Specify the quality of service to use for the message,
							from 0, 1 and 2. Defaults to 0.
						</para>
					</listitem>
				</varlistentry>
				<xi:include href="common/option-quiet.xml" />
				<varlistentry>
					<term><option>-r</option></term>
					<term><option>--retain</option></term>
					<listitem>
						<para>
							If retain is given, the message will be retained as a
							"last known good" value on the broker. See
							<citerefentry><refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle><manvolnum>7</manvolnum></citerefentry>
							for more information. Note that zero length payloads
							are never retained. If you send a zero length
							payload retained message it will clear any retained
							message on the topic.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--repeat</option></term>
					<listitem>
						<para>
							If the publish mode is<option>-m</option>,
							<option>-f</option>, or <option>-s</option> (i.e. the modes
							where only a single message is sent), then
							<option>--repeat</option> can be used to specify that the
							message will be published multiple times.
						</para>
						<para>
							See also <option>--repeat-delay</option>.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--repeat-delay</option></term>
					<listitem>
						<para>
							If using <option>--repeat</option>, then the default
							behaviour is to publish repeated messages as soon as the
							previous message is delivered. Use
							<option>--repeat-delay</option> to specify the number of
							seconds to wait after the previous message was delivered
							before publishing the next. Does not need to be an integer
							number of seconds.
						</para>
						<para>
							Note that there is no guarantee as to the actual interval
							between messages, this option simply defines the minimum
							time from delivery of one message to the start of the
							publish of the next.
						</para>
					</listitem>
				</varlistentry>
				<xi:include href="common/option-payload-stdin-file.xml" />
				<xi:include href="common/option-srv.xml" />
				<varlistentry>
					<term><option>-t</option></term>
					<term><option>--topic</option></term>
					<listitem>
						<para>
							The MQTT topic on which to publish the message. See
							<citerefentry><refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle><manvolnum>7</manvolnum></citerefentry>
							for more information on MQTT topics.
						</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-protocol-version.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-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_pub
			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-disconnect.xml" />
		<xi:include href="common/section-properties-will.xml" />
	</refsect1>

	<xi:include href="common/section-exit-status.xml" />

	<refsect1>
		<title>Examples</title>
		<para>Publish temperature information to localhost with QoS 1:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_pub <literal>-t</literal> sensors/temperature <literal>-m</literal> 32 <literal>-q</literal> 1</para></listitem>
		</itemizedlist>
		<para>Publish timestamp and temperature information to a remote host on a non-standard port and QoS 0:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_pub <literal>-h</literal> 192.168.1.1
			<literal>-p</literal> 1885 <literal>-t</literal>
			sensors/temperature <literal>-m</literal> "1266193804
			32"</para></listitem>
		</itemizedlist>
		<para>Publish light switch status. Message is set to retained because there may be a long period of time between light switch events:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_pub <literal>-r</literal> <literal>-t</literal> switches/kitchen_lights/status <literal>-m</literal> "on"</para></listitem>
		</itemizedlist>
		<para>Send the contents of a file in two ways:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_pub <literal>-t</literal> my/topic <literal>-f</literal> ./data</para></listitem>
			<listitem><para>mosquitto_pub <literal>-t</literal> my/topic <literal>-s</literal> &lt; ./data</para></listitem>
		</itemizedlist>
		<para>Send parsed electricity usage data from a Current Cost meter, reading from stdin with one line/reading as one message:</para>
		<itemizedlist mark="circle">
			<listitem><para>read_cc128.pl | mosquitto_pub <literal>-t</literal> sensors/cc128 <literal>-l</literal></para></listitem>
		</itemizedlist>
		<para>Power on an appliance using zigbee2mqtt and an appropriately configured power socket:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_pub <literal>-t</literal> zigbee2mqtt/power-microwave/set <literal>-m</literal> '{"state":"ON"}'</para></listitem>
		</itemizedlist>
	</refsect1>

	<refsect1>
		<title>Files</title>
		<variablelist>
			<varlistentry>
				<term><filename>$XDG_CONFIG_HOME/mosquitto_pub</filename></term>
				<term><filename>$HOME/.config/mosquitto_pub</filename></term>
				<term><filename>$HOME/snap/mosquitto/current/.config/mosquitto_pub</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_rr-1.html">mosquitto_rr</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>
