| <?php include '../_includes/header.php' ?><div class="refentry"> |
| <a name="mosquitto"></a><div class="titlepage"></div> |
| <div class="refnamediv"> |
| <h2>Name</h2> |
| <p>mosquitto — an MQTT broker</p> |
| </div> |
| <div class="refsynopsisdiv"> |
| <h2>Synopsis</h2> |
| <div class="cmdsynopsis"><p><code class="command">mosquitto</code> [-c <em class="replaceable"><code>config file</code></em>] [ -d | --daemon ] [-p <em class="replaceable"><code>port number</code></em>] [-v]</p></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp48961536"></a><h2>Description</h2> |
| <p><span class="command"><strong>mosquitto</strong></span> is a broker for the MQTT protocol version 3.1.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp48962944"></a><h2>Options</h2> |
| <div class="variablelist"><dl class="variablelist"> |
| <dt> |
| <span class="term"><code class="option">-c</code>, </span><span class="term"><code class="option">--config-file</code></span> |
| </dt> |
| <dd><p>Load configuration from a file. If not given, the default values as described in <span class="citerefentry"><span class="refentrytitle">mosquitto.conf</span>(5)</span> are used.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-d</code>, </span><span class="term"><code class="option">--daemon</code></span> |
| </dt> |
| <dd><p>Run <span class="command"><strong>mosquitto</strong></span> in the background as a daemon. All other behaviour remains the same.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-p</code>, </span><span class="term"><code class="option">--port</code></span> |
| </dt> |
| <dd><p>Listen on the port specified instead of the default 1883. This acts in addition to the port setting in the config file. May be specified multiple times to open multiple sockets listening on different ports. This socket will be bound to all network interfaces.</p></dd> |
| <dt> |
| <span class="term"><code class="option">-v</code>, </span><span class="term"><code class="option">--verbose</code></span> |
| </dt> |
| <dd><p>Use verbose logging. This is equivalent to setting |
| <code class="option">log_type</code> to <code class="option">all</code> in |
| the configuration file. This overrides and logging |
| options given in the configuration file.</p></dd> |
| </dl></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp48975120"></a><h2>Configuration</h2> |
| <p>The broker can be configured using a configuration file as |
| described in |
| <span class="citerefentry"><span class="refentrytitle">mosquitto.conf</span>(5)</span> |
| and this is the main point of information for mosquitto. |
| The files required for SSL/TLS support are described in |
| <span class="citerefentry"><span class="refentrytitle">mosquitto-tls</span>(7)</span>. |
| </p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp48977952"></a><h2>Broker Status</h2> |
| <p>Clients can find information about the broker by subscribing to |
| topics in the $SYS hierarchy as follows. Topics marked as static are |
| only sent once per client on subscription. All other topics are updated |
| every <code class="option">sys_interval</code> seconds. If |
| <code class="option">sys_interval</code> is 0, then updates are not sent.</p> |
| <div class="variablelist"><dl class="variablelist"> |
| <dt><span class="term"><code class="option">$SYS/broker/bytes/received</code></span></dt> |
| <dd><p>The total number of bytes received since the broker |
| started.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/bytes/sent</code></span></dt> |
| <dd><p>The total number of bytes sent since the broker |
| started.</p></dd> |
| <dt> |
| <span class="term"><code class="option">$SYS/broker/clients/connected</code>, </span><span class="term"><code class="option">$SYS/broker/clients/active</code> (deprecated)</span> |
| </dt> |
| <dd><p>The number of currently connected clients.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/clients/expired</code></span></dt> |
| <dd><p>The number of disconnected persistent clients that |
| have been expired and removed through the |
| persistent_client_expiration option.</p></dd> |
| <dt> |
| <span class="term"><code class="option">$SYS/broker/clients/disconnected</code>, </span><span class="term"><code class="option">$SYS/broker/clients/inactive</code> (deprecated)</span> |
| </dt> |
| <dd><p>The total number of persistent clients (with clean |
| session disabled) that are registered at the broker but are |
| currently disconnected.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/clients/maximum</code></span></dt> |
| <dd><p>The maximum number of clients that have been |
| connected to the broker at the same time.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/clients/total</code></span></dt> |
| <dd><p>The total number of active and inactive clients |
| currently connected and registered on the |
| broker.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/connection/#</code></span></dt> |
| <dd><p>When bridges are configured to/from the broker, |
| common practice is to provide a status topic that |
| indicates the state of the connection. This is provided |
| within $SYS/broker/connection/ by default. If the value |
| of the topic is 1 the connection is active, if 0 then |
| it is not active. See the Bridges section below for |
| more information on bridges.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/heap/current size</code></span></dt> |
| <dd><p>The current size of the heap memory in use by |
| mosquitto. Note that this topic may be unavailable |
| depending on compile time options.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/heap/maximum size</code></span></dt> |
| <dd><p>The largest amount of heap memory used by |
| mosquitto. Note that this topic may be unavailable |
| depending on compile time options.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/connections/+</code></span></dt> |
| <dd><p>The moving average of the number of CONNECT packets |
| received by the broker over different time intervals. |
| The final "+" of the hierarchy can be 1min, 5min or |
| 15min. The value returned represents the number of |
| connections received in 1 minute, averaged over 1, 5 or |
| 15 minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/bytes/received/+</code></span></dt> |
| <dd><p>The moving average of the number of bytes received by |
| the broker over different time intervals. The final "+" |
| of the hierarchy can be 1min, 5min or 15min. The value |
| returned represents the number of bytes received in 1 |
| minute, averaged over 1, 5 or 15 minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/bytes/sent/+</code></span></dt> |
| <dd><p>The moving average of the number of bytes sent by the |
| broker over different time intervals. The final "+" of |
| the hierarchy can be 1min, 5min or 15min. The value |
| returned represents the number of bytes sent in 1 |
| minute, averaged over 1, 5 or 15 minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/messages/received/+</code></span></dt> |
| <dd><p>The moving average of the number of all types of MQTT |
| messages received by the broker over different time |
| intervals. The final "+" of the hierarchy can be 1min, |
| 5min or 15min. The value returned represents the number |
| of messages received in 1 minute, averaged over 1, 5 or |
| 15 minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/messages/sent/+</code></span></dt> |
| <dd><p>The moving average of the number of all types of MQTT |
| messages sent by the broker over different time |
| intervals. The final "+" of the hierarchy can be 1min, |
| 5min or 15min. The value returned represents the number |
| of messages send in 1 minute, averaged over 1, 5 or 15 |
| minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/publish/dropped/+</code></span></dt> |
| <dd><p>The moving average of the number of publish messages |
| dropped by the broker over different time intervals. |
| This shows the rate at which durable clients that are |
| disconnected are losing messages. The final "+" of the |
| hierarchy can be 1min, 5min or 15min. The value |
| returned represents the number of messages dropped in 1 |
| minute, averaged over 1, 5 or 15 minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/publish/received/+</code></span></dt> |
| <dd><p>The moving average of the number of publish messages |
| received by the broker over different time intervals. |
| The final "+" of the hierarchy can be 1min, 5min or |
| 15min. The value returned represents the number of |
| publish messages received in 1 minute, averaged over 1, |
| 5 or 15 minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/publish/sent/+</code></span></dt> |
| <dd><p>The moving average of the number of publish messages |
| sent by the broker over different time intervals. The |
| final "+" of the hierarchy can be 1min, 5min or 15min. |
| The value returned represents the number of publish |
| messages sent in 1 minute, averaged over 1, 5 or 15 |
| minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/load/sockets/+</code></span></dt> |
| <dd><p>The moving average of the number of socket |
| connections opened to the broker over different time |
| intervals. The final "+" of the hierarchy can be 1min, |
| 5min or 15min. The value returned represents the number |
| of socket connections in 1 minute, averaged over 1, 5 |
| or 15 minutes.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/messages/inflight</code></span></dt> |
| <dd><p>The number of messages with QoS>0 that are awaiting |
| acknowledgments.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/messages/received</code></span></dt> |
| <dd><p>The total number of messages of any type received since the broker started.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/messages/sent</code></span></dt> |
| <dd><p>The total number of messages of any type sent since the broker started.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/messages/stored</code></span></dt> |
| <dd><p>The number of messages currently held in the message |
| store. This includes retained messages and messages |
| queued for durable clients.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/publish/messages/dropped</code></span></dt> |
| <dd><p>The total number of publish messages that have been |
| dropped due to inflight/queuing limits. See the |
| max_inflight_messages and max_queued_messages options |
| in |
| <span class="citerefentry"><span class="refentrytitle">mosquitto.conf</span>(5)</span> |
| for more information.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/publish/messages/received</code></span></dt> |
| <dd><p>The total number of PUBLISH messages received since the broker started.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/publish/messages/sent</code></span></dt> |
| <dd><p>The total number of PUBLISH messages sent since the broker started.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/retained messages/count</code></span></dt> |
| <dd><p>The total number of retained messages active on the broker.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/subscriptions/count</code></span></dt> |
| <dd><p>The total number of subscriptions active on the broker.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/timestamp</code></span></dt> |
| <dd><p>The timestamp at which this particular build of the broker was made. Static.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/uptime</code></span></dt> |
| <dd><p>The amount of time in seconds the broker has been online.</p></dd> |
| <dt><span class="term"><code class="option">$SYS/broker/version</code></span></dt> |
| <dd><p>The version of the broker. Static.</p></dd> |
| </dl></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49038608"></a><h2>Wildcard Topic Subscriptions</h2> |
| <p>In addition to allowing clients to subscribe to specific topics, |
| mosquitto also allows the use of two wildcards in subscriptions. |
| <code class="option">+</code> is the wildcard used to match a single level of |
| hierarchy. For example, for a topic of "a/b/c/d", the following example |
| subscriptions will match:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> |
| <li class="listitem" style="list-style-type: circle"><p>a/b/c/d</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>+/b/c/d</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>a/+/c/d</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>a/+/+/d</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>+/+/+/+</p></li> |
| </ul></div> |
| <p>The following subscriptions will not match:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> |
| <li class="listitem" style="list-style-type: circle"><p>a/b/c</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>b/+/c/d</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>+/+/+</p></li> |
| </ul></div> |
| <p>The second wildcard is <code class="option">#</code> and is used to match |
| all subsequent levels of hierarchy. With a topic of "a/b/c/d", the |
| following example subscriptions will match:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> |
| <li class="listitem" style="list-style-type: circle"><p>a/b/c/d</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>#</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>a/#</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>a/b/#</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>a/b/c/#</p></li> |
| <li class="listitem" style="list-style-type: circle"><p>+/b/c/#</p></li> |
| </ul></div> |
| <p>The $SYS hierarchy does not match a subscription of |
| "#". If you want to observe the entire $SYS hierarchy, subscribe to |
| $SYS/#.</p> |
| <p>Note that the wildcards must be only ever used on their own, so a |
| subscription of "a/b+/c" is not valid use of a wildcard. The |
| <code class="option">#</code> wildcard must only ever be used as the final |
| character of a subscription.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49052000"></a><h2>Bridges</h2> |
| <p>Multiple brokers can be connected together with the bridging |
| functionality. This is useful where it is desirable to share |
| information between locations, but where not all of the information |
| needs to be shared. An example could be where a number of users are |
| running a broker to help record power usage and for a number of other |
| reasons. The power usage could be shared through bridging all of the |
| user brokers to a common broker, allowing the power usage of all |
| users to be collected and compared. The other information would remain |
| local to each |
| broker.</p> |
| <p>For information on configuring bridges, see |
| <span class="citerefentry"><span class="refentrytitle">mosquitto.conf</span>(5)</span>.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp48903824"></a><h2>Signals</h2> |
| <div class="variablelist"><dl class="variablelist"> |
| <dt><span class="term">SIGHUP</span></dt> |
| <dd><p>Upon receiving the SIGHUP signal, mosquitto will |
| attempt to reload configuration file data, assuming that |
| the <code class="option">-c</code> argument was provided when |
| mosquitto was started. Not all configuration parameters can |
| be reloaded without restarting. See |
| <span class="citerefentry"><span class="refentrytitle">mosquitto.conf</span>(5)</span> |
| for details.</p></dd> |
| <dt><span class="term">SIGUSR1</span></dt> |
| <dd><p>Upon receiving the SIGUSR1 signal, mosquitto will |
| write the persistence database to disk. This signal is only |
| acted upon if persistence is enabled.</p></dd> |
| <dt><span class="term">SIGUSR2</span></dt> |
| <dd><p>The SIGUSR2 signal causes mosquitto to print out the |
| current subscription tree, along with information about |
| where retained messages exist. This is intended as a |
| testing feature only and may be removed at any time.</p></dd> |
| </dl></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49070768"></a><h2>Files</h2> |
| <div class="variablelist"><dl class="variablelist"> |
| <dt><span class="term"><code class="filename">/etc/mosquitto/mosquitto.conf</code></span></dt> |
| <dd><p>Configuration file. See <span class="citerefentry"><span class="refentrytitle">mosquitto.conf</span>(5)</span>.</p></dd> |
| <dt><span class="term"><code class="filename">/var/lib/mosquitto/mosquitto.db</code></span></dt> |
| <dd><p>Persistent message data storage location if persist enabled.</p></dd> |
| <dt> |
| <span class="term"><code class="filename">/etc/hosts.allow</code>, </span><span class="term"><code class="filename">/etc/hosts.deny</code></span> |
| </dt> |
| <dd><p>Host access control via tcp-wrappers as described in <span class="citerefentry"><span class="refentrytitle">hosts_access</span>(5)</span>.</p></dd> |
| </dl></div> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49079248"></a><h2>Bugs</h2> |
| <p><span class="command"><strong>mosquitto</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="idp49081280"></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-tls-7.php" target="_top">mosquitto-tls</a></span>(7)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="mosquitto-conf-5.php" target="_top">mosquitto.conf</a></span>(5)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="http://www.linuxmanpages.com/man5/hosts_access.5.php" target="_top">hosts_access</a></span>(5)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="mosquitto_passwd-1.php" target="_top">mosquitto_passwd</a></span>(1)</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_sub-1.php" target="_top">mosquitto_sub</a></span>(1)</span> |
| , |
| <span class="citerefentry"><span class="refentrytitle"><a class="link" href="libmosquitto-3.php" target="_top">libmosquitto</a></span>(3)</span> |
| </span> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49098112"></a><h2>Thanks</h2> |
| <p>Thanks to Andy Stanford-Clark for being one of the people who |
| came up with MQTT in the first place. Thanks to Andy and Nicholas |
| O'Leary for providing clarifications of the protocol.</p> |
| <p>Thanks also to everybody at the Ubuntu UK Podcast and Linux |
| Outlaws for organising OggCamp, where Andy gave a talk that |
| inspired mosquitto.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="idp49100016"></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' ?> |
