mirror of
https://github.com/eclipse-mosquitto/mosquitto.git
synced 2026-05-21 12:24:29 +02:00
411 lines
18 KiB
XML
411 lines
18 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
|
|
|
|
<refentry xml:id="mosquitto_pub" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<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>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>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 xmlns:xi="http://www.w3.org/2001/XInclude" 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 xmlns:xi="http://www.w3.org/2001/XInclude" href="common/synopsis-tls-certificate-options.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 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 xmlns:xi="http://www.w3.org/2001/XInclude" href="common/section-encrypted-connections.xml" />
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<para>
|
|
There are three ways to provide options to mosquitto_pub: the
|
|
default config file, a specified config file, or options on
|
|
the command line.
|
|
</para>
|
|
<para>
|
|
The default config file is located at
|
|
<option>$XDG_CONFIG_HOME/mosquitto_pub</option> or
|
|
<option>$HOME/.config/mosquitto_pub</option> on POSIX systems, or
|
|
<option>%USERPROFILE%\mosquitto_pub</option> on Windows.
|
|
</para>
|
|
<para>
|
|
A config file can be specified on the command line using
|
|
<option>-o <replaceable>config-file</replaceable></option>.
|
|
If the <option>-o</option> option is used, the default config
|
|
file will not be loaded.
|
|
</para>
|
|
<para>
|
|
In both cases, the contents of the config file should consist of
|
|
options, one per line in the format:
|
|
<option>-option <replaceable>value</replaceable></option>. If
|
|
options are also specified on the command line, those
|
|
options will override the same options set in the config
|
|
file. The exceptions to this are the message type options, of which
|
|
only one can be specified. Note also that currently some options
|
|
cannot be negated, e.g. <option>-S</option>. TLS encryption options
|
|
can be negated with the <option>--no-tls</option> option.
|
|
</para>
|
|
<para>
|
|
Config file lines that have a <option>#</option> as the first
|
|
character are treated as comments and not processed any further.
|
|
</para>
|
|
<para>
|
|
It is suggested that config files are primarily used for
|
|
authentication purposes. Use of a config file allows you to
|
|
authenticate without the need to show the username and password
|
|
on the command line.
|
|
</para>
|
|
<variablelist>
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-bind.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-clean-session.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-cafile.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-capath.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-cert.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-ciphers.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-debug.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-property.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-payload-file.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-help.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-host.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-clientid.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-clientid-prefix.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-insecure.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-keepalive.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-key.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-keyform.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 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 xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-payload-message.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-payload-null.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-nodelay.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-no-tls.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-port.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-password.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-proxy.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-psk.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 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 xmlns:xi="http://www.w3.org/2001/XInclude" 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 xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-payload-stdin-file.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 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 xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-alpn.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-engine.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-engine-kpass-sha1.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-keylog.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-use-os-certs.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-tls-version.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-username.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-unix-socket.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-protocol-version.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-will-payload.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-will-qos.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-will-retain.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-will-topic.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-websockets.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-session-expiry-interval.xml" />
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 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 xmlns:xi="http://www.w3.org/2001/XInclude" href="common/section-properties-connect.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/section-properties-publish.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/section-properties-disconnect.xml" />
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/section-properties-will.xml" />
|
|
</refsect1>
|
|
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 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> < ./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 xmlns:xi="http://www.w3.org/2001/XInclude" 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>
|