| <?php include '../_includes/header.php' ?><div class="refentry"> |
| <a name="mosquitto_sub"></a><div class="titlepage"></div> |
| <div class="refnamediv"> |
| <h2>Name</h2> |
| <p>mosquitto_sub — an MQTT version 3.1 client for subscribing to topics</p> |
| </div> |
| <div class="refsynopsisdiv"> |
| <h2>Synopsis</h2> |
| <div class="cmdsynopsis"><p><code class="command">mosquitto_sub</code> [<code class="option">-1</code>] [<code class="option">-A</code> <em class="replaceable"><code>bind_address</code></em>] [<code class="option">-c</code>] [<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">-R</code>] [<code class="option">-S</code>] [<code class="option">-N</code>] [<code class="option">--quiet</code>] [<code class="option">-v</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">--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">--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>filter-out</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_sub</code> [<code class="option">--help</code>] </p></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49139792"></a><h2>Description</h2> |
| <p><span class="command"><strong>mosquitto_sub</strong></span> is a simple MQTT version 3.1 |
| client that will subscribe to a topic and print the messages that it |
| receives.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49141328"></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_sub</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 <code class="option">-t</code> and <code class="option">-T</code>, which if |
| given in the config file will not be overridden. 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">-1</code></span></dt> |
| <dd> |
| <p>Disconnect and exit the program immediately after the |
| first message is received. This may be useful in shell |
| scripts where on a single status value is required, for |
| example.</p> |
| <p>Combine with <code class="option">-R</code> to print only the |
| first fresh message (i.e. that does not have the |
| retained flag set), or with <code class="option">-T</code> to |
| filter which topics are processed.</p> |
| </dd> |
| <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">-c</code>, </span><span class="term"><code class="option">--disable-clean-session</code></span> |
| </dt> |
| <dd> |
| <p>Disable the 'clean session' flag. This means that all |
| of the subscriptions for the client will be maintained |
| after it disconnects, along with subsequent QoS 1 and QoS 2 |
| messages that arrive. When the client reconnects, it will |
| receive all of the queued messages.</p> |
| <p>If using this option, it is recommended that the |
| client id is set manually with <code class="option">--id</code></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">--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_sub_ 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">-N</code></span></dt> |
| <dd><p>Do not append an end of line character to the payload |
| when printing. This allows streaming of payload data |
| from multiple messages directly to another application |
| unmodified. Only really makes sense when not using |
| <code class="option">-v</code>.</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 desired for the |
| incoming messages, from 0, 1 and 2. Defaults to 0. See |
| <span class="citerefentry"><span class="refentrytitle">mqtt</span>(7)</span> |
| for more information on QoS.</p> |
| <p>The QoS is identical for all topics subscribed to in |
| a single instance of mosquitto_sub.</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></dt> |
| <dd><p>If this argument is given, messages that are received |
| that have the retain bit set will not be printed. |
| Messages with retain set are "stale", in that it is not |
| known when they were originally published. When |
| subscribing to a wildcard topic there may be a large |
| number of retained messages. This argument suppresses |
| their display.</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 to subscribe to. See |
| <span class="citerefentry"><span class="refentrytitle">mqtt</span>(7)</span> |
| for more information on MQTT topics.</p> |
| <p>This option may be repeated to subscribe to multiple topics.</p> |
| </dd> |
| <dt> |
| <span class="term"><code class="option">-T</code>, </span><span class="term"><code class="option">--filter-out</code></span> |
| </dt> |
| <dd> |
| <p>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.</p> |
| <p>For example, subscribe to the BBC tree, but suppress output from Radio 3:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>mosquitto_sub <code class="literal">-t</code> |
| bbc/# <code class="literal">-T</code> |
| bbc/radio3</p></li></ul></div> |
| <p>This option may be repeated to filter out multiple |
| topics or topic trees.</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">--verbose</code></span> |
| </dt> |
| <dd><p>Print received messages verbosely. With this |
| argument, messages will be printed as "topic payload". When |
| this argument is not given, the messages are printed as |
| "payload".</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="idp49240288"></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="idp49244784"></a><h2>Examples</h2> |
| <p>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.</p> |
| <p>Subscribe to temperature information on 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_sub <code class="literal">-t</code> sensors/temperature <code class="literal">-q</code> 1</p></li></ul></div> |
| <p>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.</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>mosquitto_sub <code class="literal">-t</code> sensors/machines/+/temperature/+</p></li></ul></div> |
| <p>Subscribe to all broker status messages:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>mosquitto_sub <code class="literal">-v</code> <code class="literal">-t</code> \$SYS/#</p></li></ul></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49252912"></a><h2>Files</h2> |
| <div class="variablelist"><dl class="variablelist"> |
| <dt> |
| <span class="term"><code class="filename">$XDG_CONFIG_HOME/mosquitto_sub</code>, </span><span class="term"><code class="filename">$HOME/.config/mosquitto_sub</code></span> |
| </dt> |
| <dd><p>Configuration file for default options.</p></dd> |
| </dl></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49256384"></a><h2>Bugs</h2> |
| <p><span class="command"><strong>mosquitto_sub</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="idp49258416"></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_pub-1.php" target="_top">mosquitto_pub</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="idp49269472"></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' ?> |
