| <?php include '../_includes/header.php' ?><div class="refentry"> |
| <a name="mosquitto_pub"></a><div class="titlepage"></div> |
| <div class="refnamediv"> |
| <h2>Name</h2> |
| <p>mosquitto_pub — an MQTT version 3.1/3.1.1 client for publishing simple messages</p> |
| </div> |
| <div class="refsynopsisdiv"> |
| <h2>Synopsis</h2> |
| <div class="cmdsynopsis"><p><code class="command">mosquitto_pub</code> [<code class="option">-A</code> <em class="replaceable"><code>bind_address</code></em>] [<code class="option">-d</code>] [<code class="option">-h</code> <em class="replaceable"><code>hostname</code></em>] [<code class="option">-i</code> <em class="replaceable"><code>client_id</code></em>] [<code class="option">-I</code> <em class="replaceable"><code>client id prefix</code></em>] [<code class="option">-k</code> <em class="replaceable"><code>keepalive time</code></em>] [<code class="option">-p</code> <em class="replaceable"><code>port number</code></em>] [<code class="option">-q</code> <em class="replaceable"><code>message QoS</code></em>] [<code class="option">--quiet</code>] [<code class="option">-r</code>] [<code class="option">-S</code>] { <code class="option">-f</code> <em class="replaceable"><code>file</code></em> | <code class="option">-l</code> | <code class="option">-m</code> <em class="replaceable"><code>message</code></em> | <code class="option">-n</code> | <code class="option">-s</code> } [ |
| [<code class="option">-u</code> <em class="replaceable"><code>username</code></em>] |
| [<code class="option">-P</code> <em class="replaceable"><code>password</code></em>] |
| ] [ |
| <code class="option">--will-topic</code> <em class="replaceable"><code>topic</code></em> |
| [<code class="option">--will-payload</code> <em class="replaceable"><code>payload</code></em>] |
| [<code class="option">--will-qos</code> <em class="replaceable"><code>qos</code></em>] |
| [<code class="option">--will-retain</code>] |
| ] [[ |
| { <code class="option">--cafile</code> <em class="replaceable"><code>file</code></em> | <code class="option">--capath</code> <em class="replaceable"><code>dir</code></em> } |
| [<code class="option">--cert</code> <em class="replaceable"><code>file</code></em>] |
| [<code class="option">--key</code> <em class="replaceable"><code>file</code></em>] |
| [<code class="option">--ciphers</code> <em class="replaceable"><code>ciphers</code></em>] |
| [<code class="option">--tls-version</code> <em class="replaceable"><code>version</code></em>] |
| [<code class="option">--insecure</code>] |
| ] | [ |
| <code class="option">--psk</code> <em class="replaceable"><code>hex-key</code></em> |
| <code class="option">--psk-identity</code> <em class="replaceable"><code>identity</code></em> |
| [<code class="option">--ciphers</code> <em class="replaceable"><code>ciphers</code></em>] |
| [<code class="option">--tls-version</code> <em class="replaceable"><code>version</code></em>] |
| ]] [<code class="option">--proxy</code> <em class="replaceable"><code>socks-url</code></em>] [<code class="option">-V</code> <em class="replaceable"><code>protocol-version</code></em>] <code class="option">-t</code> <em class="replaceable"><code>message-topic</code></em> </p></div> |
| <div class="cmdsynopsis"><p><code class="command">mosquitto_pub</code> [<code class="option">--help</code>] </p></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49139696"></a><h2>Description</h2> |
| <p><span class="command"><strong>mosquitto_pub</strong></span> is a simple MQTT version 3.1 client that will publish a single message on a topic and exit.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49141104"></a><h2>Options</h2> |
| <p>The options below may be given on the command line, but may also |
| be placed in a config file located at |
| <code class="option">$XDG_CONFIG_HOME/mosquitto_pub</code> or |
| <code class="option">$HOME/.config/mosquitto_sub</code> with one pair of |
| <code class="option">-option <em class="replaceable"><code>value</code></em></code> |
| per line. The values in the config file will be used as defaults |
| and can be overridden by using the command line. 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. <code class="option">-S</code>. Config file lines that have a |
| <code class="option">#</code> as the first character are treated as comments |
| and not processed any further.</p> |
| <div class="variablelist"><dl class="variablelist"> |
| <dt><span class="term"><code class="option">-A</code></span></dt> |
| <dd><p>Bind the outgoing connection to a local ip |
| address/hostname. Use this argument if you need to |
| restrict network communication to a particular |
| interface.</p></dd> |
| <dt><span class="term"><code class="option">--cafile</code></span></dt> |
| <dd> |
| <p>Define the path to a file containing PEM encoded CA |
| certificates that are trusted. Used to enable SSL |
| communication.</p> |
| <p>See also <code class="option">--capath</code></p> |
| </dd> |
| <dt><span class="term"><code class="option">--capath</code></span></dt> |
| <dd> |
| <p>Define the path to a directory containing PEM encoded CA |
| certificates that are trusted. Used to enable SSL |
| communication.</p> |
| <p>For <code class="option">--capath</code> to work correctly, the |
| certificate files must have ".crt" as the file ending |
| and you must run "c_rehash <path to capath>" each |
| time you add/remove a certificate.</p> |
| <p>See also <code class="option">--cafile</code></p> |
| </dd> |
| <dt><span class="term"><code class="option">--cert</code></span></dt> |
| <dd> |
| <p>Define the path to a file containing a PEM encoded |
| certificate for this client, if required by the |
| server.</p> |
| <p>See also <code class="option">--key</code>.</p> |
| </dd> |
| <dt><span class="term"><code class="option">--ciphers</code></span></dt> |
| <dd><p>An openssl compatible list of TLS ciphers to support |
| in the client. See |
| <span class="citerefentry"><span class="refentrytitle">ciphers</span>(1)</span> |
| for more information.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-d</code>, </span><span class="term"><code class="option">--debug</code></span> |
| </dt> |
| <dd><p>Enable debug messages.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-f</code>, </span><span class="term"><code class="option">--file</code></span> |
| </dt> |
| <dd><p>Send the contents of a file as the message.</p></dd> |
| <dt><span class="term"><code class="option">--help</code></span></dt> |
| <dd><p>Display usage information.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-h</code>, </span><span class="term"><code class="option">--host</code></span> |
| </dt> |
| <dd><p>Specify the host to connect to. Defaults to localhost.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-i</code>, </span><span class="term"><code class="option">--id</code></span> |
| </dt> |
| <dd><p>The id to use for this client. If not given, defaults |
| to mosquitto_pub_ appended with the process id of the |
| client. Cannot be used at the same time as the |
| <code class="option">--id-prefix</code> argument.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-I</code>, </span><span class="term"><code class="option">--id-prefix</code></span> |
| </dt> |
| <dd><p>Provide a prefix that the client id will be built |
| from by appending the process id of the client. This is |
| useful where the broker is using the clientid_prefixes |
| option. Cannot be used at the same time as the |
| <code class="option">--id</code> argument.</p></dd> |
| <dt><span class="term"><code class="option">--insecure</code></span></dt> |
| <dd><p>When using certificate based encryption, this option |
| disables verification of the server hostname in the |
| server certificate. This can be useful when testing |
| initial server configurations but makes it possible for |
| a malicious third party to impersonate your server |
| through DNS spoofing, for example. Use this option in |
| testing <span class="emphasis"><em>only</em></span>. If you need to |
| resort to using this option in a production |
| environment, your setup is at fault and there is no |
| point using encryption.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-k</code>, </span><span class="term"><code class="option">--keepalive</code></span> |
| </dt> |
| <dd><p>The number of seconds between sending PING commands |
| to the broker for the purposes of informing it we are still |
| connected and functioning. Defaults to 60 seconds.</p></dd> |
| <dt><span class="term"><code class="option">--key</code></span></dt> |
| <dd> |
| <p>Define the path to a file containing a PEM encoded |
| private key for this client, if required by the |
| server.</p> |
| <p>See also <code class="option">--cert</code>.</p> |
| </dd> |
| <dt> |
| <span class="term"><code class="option">-l</code>, </span><span class="term"><code class="option">--stdin-line</code></span> |
| </dt> |
| <dd><p>Send messages read from stdin, splitting separate lines into separate messages. Note that blank lines won't be sent.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-m</code>, </span><span class="term"><code class="option">--message</code></span> |
| </dt> |
| <dd><p>Send a single message from the command line.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-n</code>, </span><span class="term"><code class="option">--null-message</code></span> |
| </dt> |
| <dd><p>Send a null (zero length) message.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-p</code>, </span><span class="term"><code class="option">--port</code></span> |
| </dt> |
| <dd><p>Connect to the port specified instead of the default 1883.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-P</code>, </span><span class="term"><code class="option">--pw</code></span> |
| </dt> |
| <dd><p>Provide a password to be used for authenticating with |
| the broker. Using this argument without also specifying a |
| username is invalid. This requires a broker that supports |
| MQTT v3.1. See also the <code class="option">--username</code> option.</p></dd> |
| <dt><span class="term"><code class="option">--proxy</code></span></dt> |
| <dd> |
| <p>Specify a SOCKS5 proxy to connect through. "None" and |
| "username" authentication types are supported. The |
| <code class="option">socks-url</code> must be of the form |
| <code class="option">socks5h://[username[:password]@]host[:port]</code>. |
| The protocol prefix <code class="option">socks5h</code> means that |
| hostnames are resolved by the proxy. The symbols %25, |
| %3A and %40 are URL decoded into %, : and @ |
| respectively, if present in the username or |
| password.</p> |
| <p>If username is not given, then no authentication is |
| attempted. If the port is not given, then the default |
| of 1080 is used.</p> |
| <p>More SOCKS versions may be available in the future, |
| depending on demand, and will use different protocol |
| prefixes as described in <span class="citerefentry"><span class="refentrytitle">curl</span>(1)</span>.</p> |
| </dd> |
| <dt><span class="term"><code class="option">--psk</code></span></dt> |
| <dd><p>Provide the hexadecimal (no leading 0x) |
| pre-shared-key matching the one used on the broker to |
| use TLS-PSK encryption support. |
| <code class="option">--psk-identity</code> must also be provided |
| to enable TLS-PSK.</p></dd> |
| <dt><span class="term"><code class="option">--psk-identity</code></span></dt> |
| <dd><p>The client identity to use with TLS-PSK support. This |
| may be used instead of a username if the broker is |
| configured to do so.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-q</code>, </span><span class="term"><code class="option">--qos</code></span> |
| </dt> |
| <dd><p>Specify the quality of service to use for the message, from 0, 1 and 2. Defaults to 0.</p></dd> |
| <dt><span class="term"><code class="option">--quiet</code></span></dt> |
| <dd><p>If this argument is given, no runtime errors will be |
| printed. This excludes any error messages given in case of |
| invalid user input (e.g. using <code class="option">--port</code> without a |
| port).</p></dd> |
| <dt> |
| <span class="term"><code class="option">-r</code>, </span><span class="term"><code class="option">--retain</code></span> |
| </dt> |
| <dd><p>If retain is given, the message will be retained as a "last known good" value on the broker. See <span class="citerefentry"><span class="refentrytitle">mqtt</span>(7)</span> for more information.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-s</code>, </span><span class="term"><code class="option">--stdin-file</code></span> |
| </dt> |
| <dd><p>Send a message read from stdin, sending the entire content as a single message.</p></dd> |
| <dt><span class="term"><code class="option">-S</code></span></dt> |
| <dd><p>Use SRV lookups to determine which host to connect |
| to. Performs lookups to |
| <code class="option">_mqtt._tcp.<host></code> when used in |
| conjunction with <code class="option">-h</code>, otherwise uses |
| <code class="option">_mqtt._tcp.<local dns |
| domain></code>.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-t</code>, </span><span class="term"><code class="option">--topic</code></span> |
| </dt> |
| <dd><p>The MQTT topic on which to publish the message. See <span class="citerefentry"><span class="refentrytitle">mqtt</span>(7)</span> for more information on MQTT topics.</p></dd> |
| <dt><span class="term"><code class="option">--tls-version</code></span></dt> |
| <dd><p>Choose which TLS protocol version to use when |
| communicating with the broker. Valid options are |
| <code class="option">tlsv1.2</code>, <code class="option">tlsv1.1</code> and |
| <code class="option">tlsv1</code>. The default value is |
| <code class="option">tlsv1.2</code>. If the installed version of |
| openssl is too old, only <code class="option">tlsv1</code> will be |
| available. Must match the protocol version used by the |
| broker.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-u</code>, </span><span class="term"><code class="option">--username</code></span> |
| </dt> |
| <dd><p>Provide a username to be used for authenticating with |
| the broker. This requires a broker that supports MQTT v3.1. |
| See also the <code class="option">--pw</code> argument.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-V</code>, </span><span class="term"><code class="option">--protocol-version</code></span> |
| </dt> |
| <dd><p>Specify which version of the MQTT protocol should be |
| used when connecting to the rmeote broker. Can be |
| <code class="option">mqttv31</code> or <code class="option">mqttv311</code>. |
| Defaults to <code class="option">mqttv31</code>.</p></dd> |
| <dt><span class="term"><code class="option">--will-payload</code></span></dt> |
| <dd><p>Specify a message that will be stored by the broker |
| and sent out if this client disconnects unexpectedly. This |
| must be used in conjunction with <code class="option">--will-topic</code>.</p></dd> |
| <dt><span class="term"><code class="option">--will-qos</code></span></dt> |
| <dd><p>The QoS to use for the Will. Defaults to 0. This must |
| be used in conjunction with <code class="option">--will-topic</code>.</p></dd> |
| <dt><span class="term"><code class="option">--will-retain</code></span></dt> |
| <dd><p>If given, if the client disconnects unexpectedly the |
| message sent out will be treated as a retained message. |
| This must be used in conjunction with <code class="option">--will-topic</code>.</p></dd> |
| <dt><span class="term"><code class="option">--will-topic</code></span></dt> |
| <dd><p>The topic on which to send a Will, in the event that |
| the client disconnects unexpectedly.</p></dd> |
| </dl></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49233648"></a><h2>Wills</h2> |
| <p>mosquitto_sub can register a message with the broker that will be |
| sent out if it disconnects unexpectedly. See |
| <span class="citerefentry"><span class="refentrytitle">mqtt</span>(7)</span> |
| for more information.</p> |
| <p>The minimum requirement for this is to use <code class="option">--will-topic</code> to |
| specify which topic the will should be sent out on. This will result in |
| a non-retained, zero length message with QoS 0.</p> |
| <p>Use the <code class="option">--will-retain</code>, |
| <code class="option">--will-payload</code> and <code class="option">--will-qos</code> |
| arguments to modify the other will parameters.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49238320"></a><h2>Examples</h2> |
| <p>Publish temperature information to localhost with QoS 1:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>mosquitto_pub <code class="literal">-t</code> sensors/temperature <code class="literal">-m</code> 32 <code class="literal">-q</code> 1</p></li></ul></div> |
| <p>Publish timestamp and temperature information to a remote host on a non-standard port and QoS 0:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>mosquitto_pub <code class="literal">-h</code> 192.168.1.1 |
| <code class="literal">-p</code> 1885 <code class="literal">-t</code> |
| sensors/temperature <code class="literal">-m</code> "1266193804 |
| 32"</p></li></ul></div> |
| <p>Publish light switch status. Message is set to retained because there may be a long period of time between light switch events:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>mosquitto_pub <code class="literal">-r</code> <code class="literal">-t</code> switches/kitchen_lights/status <code class="literal">-m</code> "on"</p></li></ul></div> |
| <p>Send the contents of a file in two ways:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> |
| <li class="listitem" style="list-style-type: circle"><p>mosquitto_pub <code class="literal">-t</code> my/topic <code class="literal">-f</code> ./data</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>mosquitto_pub <code class="literal">-t</code> my/topic <code class="literal">-s</code> < ./data</p></li> |
| </ul></div> |
| <p>Send parsed electricity usage data from a Current Cost meter, reading from stdin with one line/reading as one message:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>read_cc128.pl | mosquitto_pub <code class="literal">-t</code> sensors/cc128 <code class="literal">-l</code></p></li></ul></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49253984"></a><h2>Files</h2> |
| <div class="variablelist"><dl class="variablelist"> |
| <dt> |
| <span class="term"><code class="filename">$XDG_CONFIG_HOME/mosquitto_pub</code>, </span><span class="term"><code class="filename">$HOME/.config/mosquitto_pub</code></span> |
| </dt> |
| <dd><p>Configuration file for default options.</p></dd> |
| </dl></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49257456"></a><h2>Bugs</h2> |
| <p><span class="command"><strong>mosquitto_pub</strong></span> bug information can be found at <code class="uri">https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Mosquitto</code></p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49259488"></a><h2>See Also</h2> |
| <span class="simplelist"> |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="mqtt-7.php" target="_top">mqtt</a></span>(7)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="mosquitto_sub-1.php" target="_top">mosquitto_sub</a></span>(1)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="mosquitto-8.php" target="_top">mosquitto</a></span>(8)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="libmosquitto-3.php" target="_top">libmosquitto</a></span>(3)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="mosquitto-tls-7.php" target="_top">mosquitto-tls</a></span>(7)</span> |
| </span> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49270544"></a><h2>Author</h2> |
| <p>Roger Light <code class="email"><<a class="email" href="mailto:roger@atchoo.org">roger@atchoo.org</a>></code></p> |
| </div> |
| </div><?php include '../_includes/footer.php' ?> |
