mirror of
https://github.com/eclipse/mosquitto.git
synced 2025-05-08 08:40:13 +08:00
812 lines
31 KiB
XML
812 lines
31 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
|
|
|
|
<refentry xml:id="mosquitto" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refmeta>
|
|
<refentrytitle>mosquitto</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
|
|
<refmiscinfo class="manual">System management commands</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>mosquitto</refname>
|
|
<refpurpose>an MQTT broker</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>mosquitto</command>
|
|
<arg>-c <replaceable>config file</replaceable></arg>
|
|
<group>
|
|
<arg choice='plain'>-d</arg>
|
|
<arg choice='plain'>--daemon</arg>
|
|
</group>
|
|
<arg>-p <replaceable>port number</replaceable></arg>
|
|
<arg>-v</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para><command>mosquitto</command> is a broker for the MQTT protocol version 5.0/3.1.1/3.1.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-c</option></term>
|
|
<term><option>--config-file</option></term>
|
|
<listitem>
|
|
<para>
|
|
Load configuration from a file. If not given, then the broker will listen on port 1883 bound to the loopback interface,
|
|
and the default values as described in
|
|
<citerefentry><refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
are used.
|
|
</para>
|
|
<important><para>See the <option>-p</option> option for a description of changes in behaviour from 1.6.x to 2.0.</para></important>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-d</option></term>
|
|
<term><option>--daemon</option></term>
|
|
<listitem>
|
|
<para>Run <command>mosquitto</command> in the background as a daemon. All other behaviour remains the same.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-p</option></term>
|
|
<term><option>--port</option></term>
|
|
<listitem>
|
|
<para>Listen on the port specified. May be specified up to 10 times to open multiple sockets listening on different ports.</para>
|
|
<important><para>In version 1.6.x and earlier, the listener defined by <option>-p</option> (or the default port of 1883) would be
|
|
bound to all interfaces and so be accessible from any network. It could also be used in combination with <option>-c</option>.</para>
|
|
<para>From version 2.0 onwards, the listeners defined with <option>-p</option> are bound to the loopback interface only, and so can
|
|
only be connected to from the local machine. If both <option>-p</option> is used and a listener is defined in a configuration
|
|
file, then the <option>-p</option> options are IGNORED.</para></important>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-v</option></term>
|
|
<term><option>--verbose</option></term>
|
|
<listitem>
|
|
<para>Use verbose logging. This is equivalent to setting
|
|
<option>log_type</option> to <option>all</option> in
|
|
the configuration file. This overrides and logging
|
|
options given in the configuration file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Configuration</title>
|
|
<para>The broker can be configured using a configuration file as
|
|
described in
|
|
<citerefentry><refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
and this is the main point of information for mosquitto.
|
|
The files required for SSL/TLS support are described in
|
|
<citerefentry><refentrytitle><link xlink:href="mosquitto-tls-7.html">mosquitto-tls</link></refentrytitle><manvolnum>7</manvolnum></citerefentry>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Platform limitations</title>
|
|
<para>
|
|
Some versions of Windows have limitations on the number of
|
|
concurrent connections due to the Windows API being used. In
|
|
modern versions of Windows, e.g. Windows 10 or Windows Server
|
|
2019, this is approximately 8192 connections. In earlier
|
|
versions of Windows, this limit is 2048 connections.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>MQTT Support</title>
|
|
<para>Mosquitto supports MQTT v5.0, v3.1.1, and v3.1.</para>
|
|
|
|
<refsect2>
|
|
<title>MQTT v5.0</title>
|
|
<para>
|
|
Mosquitto provides full MQTT v5.0 support, but some features
|
|
are not used directly. The following sections describe the new
|
|
features and explain where Mosquitto does not make use of a feature.
|
|
</para>
|
|
|
|
<refsect3>
|
|
<title>Features</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>Enhanced authentication</option></term>
|
|
<listitem><para>
|
|
Basic MQTT authentication uses username/password
|
|
checks. Enhanced authentication allows different
|
|
authentication schemes to be integrated into MQTT,
|
|
and even those schemes with multiple step processes.
|
|
Clients request a particular type of authentication
|
|
and if the broker is configured for that scheme the
|
|
authentication continues. Mosquitto supports
|
|
enhanced authentication through plugins.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>Error handling</option></term>
|
|
<listitem><para>
|
|
Most MQTT packets now have the concept of a
|
|
<option>reason code</option>
|
|
which indicates success or failure, and what the failure
|
|
was. Mosquitto provides full support for reason codes,
|
|
but does not make use of the
|
|
<option>reason string</option>
|
|
feature which can be used to provide a human readable
|
|
error string to explain the reason code.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>Flow control</option></term>
|
|
<listitem><para>
|
|
The number of "in flight" messages for QoS 1 and QoS
|
|
2 can be controlled by both the client and the
|
|
broker.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>Request / response</option></term>
|
|
<listitem><para>
|
|
MQTT v5.0 adds a request/response pattern that
|
|
allows a client to publish a message and instruct
|
|
the subscribers of that message where to publish a
|
|
response.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>Server redirection</option></term>
|
|
<listitem><para>
|
|
Server redirection is the concept of telling a
|
|
client to connect to a different MQTT broker, either
|
|
on CONNECT or with a broker initiated DISCONNECT.
|
|
Mosquitto does not currently make use of this
|
|
feature.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>Shared subscriptions</option></term>
|
|
<listitem><para>
|
|
When multiple clients subscribe to the same shared
|
|
subscription, only one client out of the group will
|
|
receive each message which allows for distributing
|
|
work loads.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect3>
|
|
|
|
<refsect3>
|
|
<title>Packet properties</title>
|
|
<para>
|
|
MQTT v5.0 allows properties to be added to packets to
|
|
control certain behaviour. Unless noted, Mosquitto
|
|
support the properties listed below.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>CONNECT</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Authentication data</para></listitem>
|
|
<listitem><para>Authentication method</para></listitem>
|
|
<listitem><para>Maximum packet size</para></listitem>
|
|
<listitem><para>Receive maximum</para></listitem>
|
|
<listitem><para>Request problem information - supported but not used</para></listitem>
|
|
<listitem><para>Request response information - supported but not used</para></listitem>
|
|
<listitem><para>Session expiry interval</para></listitem>
|
|
<listitem><para>Topic alias maximum</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>Last will and testament</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Content type</para></listitem>
|
|
<listitem><para>Correlation data</para></listitem>
|
|
<listitem><para>Message expiry interval</para></listitem>
|
|
<listitem><para>Payload format indicator</para></listitem>
|
|
<listitem><para>Response topic</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
<listitem><para>Will delay interval</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>CONNACK</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Assigned client identifier</para></listitem>
|
|
<listitem><para>Authentication data</para></listitem>
|
|
<listitem><para>Authentication method</para></listitem>
|
|
<listitem><para>Maximum packet size</para></listitem>
|
|
<listitem><para>Maximum qos</para></listitem>
|
|
<listitem><para>Reason string - supported but not used</para></listitem>
|
|
<listitem><para>Receive maximum</para></listitem>
|
|
<listitem><para>Response information - supported but not used</para></listitem>
|
|
<listitem><para>Retain available</para></listitem>
|
|
<listitem><para>Server keep alive</para></listitem>
|
|
<listitem><para>Server reference - supported but not used</para></listitem>
|
|
<listitem><para>Session expiry interval</para></listitem>
|
|
<listitem><para>Shared subscription available</para></listitem>
|
|
<listitem><para>Subscription identifiers available</para></listitem>
|
|
<listitem><para>Topic alias maximum</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
<listitem><para>Wildcard subscription available</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>PUBLISH</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Content type</para></listitem>
|
|
<listitem><para>Correlation data</para></listitem>
|
|
<listitem><para>Message expiry interval</para></listitem>
|
|
<listitem><para>Payload format indicator</para></listitem>
|
|
<listitem><para>Response topic</para></listitem>
|
|
<listitem><para>Subscription identifier</para></listitem>
|
|
<listitem><para>Topic alias</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>PUBACK / PUBREC / PUBREL / PUBCOMP / SUBACK / SUBSCRIBE / SUBACK</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Reason string - supported but not used</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>SUBSCRIBE</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Subscription identifier</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>DISCONNECT</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Reason string - supported but not used</para></listitem>
|
|
<listitem><para>Server reference - supported but not used</para></listitem>
|
|
<listitem><para>Session expiry interval</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>AUTH</option></term>
|
|
<listitem>
|
|
<itemizedlist>
|
|
<listitem><para>Authentication method</para></listitem>
|
|
<listitem><para>Authentication data</para></listitem>
|
|
<listitem><para>Reason string - supported but not used</para></listitem>
|
|
<listitem><para>User property</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect3>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>MQTT v3.1.1</title>
|
|
<para>Mosquitto provides full MQTT v3.1.1 support.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>MQTT v3.1</title>
|
|
<para>Mosquitto provides full MQTT v3.1 support.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>MQTT v3</title>
|
|
<para>
|
|
MQTT v3 is an obsolete version of the protocol that does not
|
|
support username/password authentication and used the
|
|
<option>clean start</option> flag in the CONNECT packet which
|
|
applied only to the start of a session. An MQTT v3 client
|
|
will be able to successfully connect to a Mosquitto instance
|
|
that does not require authentication.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Broker Status</title>
|
|
<para>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 <option>sys_interval</option> seconds. If
|
|
<option>sys_interval</option> is 0, then updates are not sent.</para>
|
|
<para>Note that if you are using a command line client to interact with the
|
|
$SYS topics and your shell interprets $ as an environment variable,
|
|
you need to place the topic in single quotes '$SYS/...' or to
|
|
escape the dollar symbol: \$SYS/... otherwise the $SYS will be
|
|
treated as an environment variable.</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/bytes/received</option></term>
|
|
<listitem>
|
|
<para>The total number of bytes received since the broker
|
|
started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/bytes/sent</option></term>
|
|
<listitem>
|
|
<para>The total number of bytes sent since the broker
|
|
started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/clients/connected</option></term>
|
|
<term><option>$SYS/broker/clients/active</option> (deprecated)</term>
|
|
<listitem>
|
|
<para>The number of currently connected clients.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/clients/expired</option></term>
|
|
<listitem>
|
|
<para>The number of disconnected persistent clients that
|
|
have been expired and removed through the
|
|
persistent_client_expiration option.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/clients/disconnected</option></term>
|
|
<term><option>$SYS/broker/clients/inactive</option> (deprecated)</term>
|
|
<listitem>
|
|
<para>The total number of persistent clients (with clean
|
|
session disabled) that are registered at the broker but are
|
|
currently disconnected.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/clients/maximum</option></term>
|
|
<listitem>
|
|
<para>The maximum number of clients that have been
|
|
connected to the broker at the same time.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/clients/total</option></term>
|
|
<listitem>
|
|
<para>The total number of active and inactive clients
|
|
currently connected and registered on the
|
|
broker.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/connection/#</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/heap/current size</option></term>
|
|
<listitem>
|
|
<para>The current size of the heap memory in use by
|
|
mosquitto. Note that this topic may be unavailable
|
|
depending on compile time options.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/heap/maximum size</option></term>
|
|
<listitem>
|
|
<para>The largest amount of heap memory used by
|
|
mosquitto. Note that this topic may be unavailable
|
|
depending on compile time options.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/connections/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/bytes/received/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/bytes/sent/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/messages/received/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/messages/sent/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/publish/dropped/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/publish/received/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/publish/sent/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/load/sockets/+</option></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/messages/inflight</option></term>
|
|
<listitem>
|
|
<para>The number of messages with QoS>0 that are awaiting
|
|
acknowledgments.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/messages/received</option></term>
|
|
<listitem>
|
|
<para>The total number of messages of any type received since the broker started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/messages/sent</option></term>
|
|
<listitem>
|
|
<para>The total number of messages of any type sent since the broker started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/publish/messages/dropped</option></term>
|
|
<listitem>
|
|
<para>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
|
|
<citerefentry><refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for more information.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/publish/messages/received</option></term>
|
|
<listitem>
|
|
<para>The total number of PUBLISH messages received since the broker started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/publish/messages/sent</option></term>
|
|
<listitem>
|
|
<para>The total number of PUBLISH messages sent since the broker started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/retained messages/count</option></term>
|
|
<listitem>
|
|
<para>The total number of retained messages active on the broker.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/store/messages/count</option></term>
|
|
<term><option>$SYS/broker/messages/stored</option> (deprecated)</term>
|
|
<listitem>
|
|
<para>The number of messages currently held in the message
|
|
store. This includes retained messages and messages
|
|
queued for durable clients.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/store/messages/bytes</option></term>
|
|
<listitem>
|
|
<para>The number of bytes currently held by message payloads
|
|
in the message store. This includes retained messages
|
|
and messages queued for durable clients.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/subscriptions/count</option></term>
|
|
<listitem>
|
|
<para>The total number of subscriptions active on the broker.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>$SYS/broker/version</option></term>
|
|
<listitem>
|
|
<para>The version of the broker. Static.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Wildcard Topic Subscriptions</title>
|
|
<para>In addition to allowing clients to subscribe to specific topics,
|
|
mosquitto also allows the use of two wildcards in subscriptions.
|
|
<option>+</option> 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:</para>
|
|
<itemizedlist mark="circle">
|
|
<listitem><para>a/b/c/d</para></listitem>
|
|
<listitem><para>+/b/c/d</para></listitem>
|
|
<listitem><para>a/+/c/d</para></listitem>
|
|
<listitem><para>a/+/+/d</para></listitem>
|
|
<listitem><para>+/+/+/+</para></listitem>
|
|
</itemizedlist>
|
|
<para>The following subscriptions will not match:</para>
|
|
<itemizedlist mark="circle">
|
|
<listitem><para>a/b/c</para></listitem>
|
|
<listitem><para>b/+/c/d</para></listitem>
|
|
<listitem><para>+/+/+</para></listitem>
|
|
</itemizedlist>
|
|
<para>The second wildcard is <option>#</option> and is used to match
|
|
all subsequent levels of hierarchy. With a topic of "a/b/c/d", the
|
|
following example subscriptions will match:</para>
|
|
<itemizedlist mark="circle">
|
|
<listitem><para>a/b/c/d</para></listitem>
|
|
<listitem><para>#</para></listitem>
|
|
<listitem><para>a/#</para></listitem>
|
|
<listitem><para>a/b/#</para></listitem>
|
|
<listitem><para>a/b/c/#</para></listitem>
|
|
<listitem><para>+/b/c/#</para></listitem>
|
|
</itemizedlist>
|
|
<para>The $SYS hierarchy does not match a subscription of
|
|
"#". If you want to observe the entire $SYS hierarchy, subscribe to
|
|
$SYS/#.</para>
|
|
<para>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
|
|
<option>#</option> wildcard must only ever be used as the final
|
|
character of a subscription.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Bridges</title>
|
|
<para>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.</para>
|
|
<para>For information on configuring bridges, see
|
|
<citerefentry><refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Signals</title>
|
|
<para>
|
|
On POSIX systems Mosquitto can receive signals and act on them as
|
|
described below. To send signals, use e.g.
|
|
<command>kill -HUP <process id of mosquitto></command>
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>SIGHUP</term>
|
|
<listitem>
|
|
<para>Upon receiving the SIGHUP signal, mosquitto will
|
|
attempt to reload configuration file data, assuming that
|
|
the <option>-c</option> argument was provided when
|
|
mosquitto was started. Not all configuration parameters can
|
|
be reloaded without restarting. See
|
|
<citerefentry><refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for details.</para>
|
|
<para>If TLS certificates are in use, then mosquitto will
|
|
also reload certificate on receiving a SIGHUP.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>SIGUSR1</term>
|
|
<listitem>
|
|
<para>Upon receiving the SIGUSR1 signal, mosquitto will
|
|
write the persistence database to disk. This signal is only
|
|
acted upon if persistence is enabled.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>SIGUSR2</term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Files</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><filename>/etc/mosquitto/mosquitto.conf</filename></term>
|
|
<listitem>
|
|
<para>Configuration file. See <citerefentry><refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><filename>/var/lib/mosquitto/mosquitto.db</filename></term>
|
|
<listitem>
|
|
<para>Persistent message data storage location if persist enabled.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><filename>/etc/hosts.allow</filename></term>
|
|
<term><filename>/etc/hosts.deny</filename></term>
|
|
<listitem>
|
|
<para>Host access control via tcp-wrappers as described in <citerefentry><refentrytitle><link xlink:href="https://linux.die.net/man/5/hosts_access">hosts_access</link></refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Bugs</title>
|
|
<para><command>mosquitto</command> bug information can be found at
|
|
<ulink url="https://github.com/eclipse/mosquitto/issues"/></para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<simplelist type="inline">
|
|
<member>
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
</citerefentry>
|
|
</member>
|
|
<member>
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="mosquitto-tls-7.html">mosquitto-tls</link></refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
</citerefentry>
|
|
</member>
|
|
<member>
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle>
|
|
<manvolnum>5</manvolnum>
|
|
</citerefentry>
|
|
</member>
|
|
<member>
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="https://linux.die.net/man/5/hosts_access">hosts_access</link></refentrytitle>
|
|
<manvolnum>5</manvolnum>
|
|
</citerefentry>
|
|
</member>
|
|
<member>
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="mosquitto_ctrl-1.html">mosquitto_ctrl</link></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</member>
|
|
<member>
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="mosquitto_passwd-1.html">mosquitto_passwd</link></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</member>
|
|
<member>
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="mosquitto_pub-1.html">mosquitto_pub</link></refentrytitle>
|
|
<manvolnum>1</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="libmosquitto-3.html">libmosquitto</link></refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</citerefentry>
|
|
</member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Thanks</title>
|
|
<para>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.</para>
|
|
<para>Thanks also to everybody at the Ubuntu UK Podcast and Linux
|
|
Outlaws for organising OggCamp, where Andy gave a talk that
|
|
inspired mosquitto.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Author</title>
|
|
<para>Roger Light <email>roger@atchoo.org</email></para>
|
|
</refsect1>
|
|
</refentry>
|