<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry [
	<!ENTITY from-version21 SYSTEM "common/version-2.1.xml">
]>
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>

<refentry xml:id="mosquitto"
		xmlns:xlink="http://www.w3.org/1999/xlink"
		xmlns:xi="http://www.w3.org/2001/XInclude">

	<refmeta>
		<refentrytitle>mosquitto</refentrytitle>
		<manvolnum>8</manvolnum>
		<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
		<refmiscinfo class="manual">Mosquitto</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>mosquitto</refname>
		<refpurpose>an MQTT broker</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>mosquitto</command>
			<arg><option>-c</option> <replaceable>config file</replaceable></arg>
			<group>
				<arg choice='plain'><option>-d</option></arg>
				<arg choice='plain'><option>--daemon</option></arg>
			</group>
			<arg><option>-p</option> <replaceable>port number</replaceable></arg>
			<arg><option>-q</option></arg>
			<arg><option>-v</option></arg>
			<arg><option>--tls-keylog</option> <replaceable>file</replaceable></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>
		<para>
			It is part of the overall mosquitto project. See
			<citerefentry><refentrytitle><link xlink:href="mosquitto-7.html">mosquitto</link></refentrytitle><manvolnum>7</manvolnum></citerefentry>
			for an overview of all man pages.
		</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>-q</option></term>
				<term><option>--quiet</option></term>
				<listitem>
					&from-version21;
					<para>Disable all logging. This is equivalent to setting
						<option>log_type</option> to <option>none</option> in
						the configuration file. This overrides any logging
						options given in the configuration file and also
						overrides <option>--verbose</option>.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>--test-config</option></term>
				<listitem>
					&from-version21;
					<para>
						Load the config file specified with <option>-c</option>,
						and verify that it is valid but do not start the broker.
						The broker exit code will be 0 if the config was valid,
						or non-zero if no config file was specified or the
						config file was invalid.
					</para>
				</listitem>
			</varlistentry>

			<xi:include href="common/option-tls-keylog.xml" />

			<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 any 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 connected and disconnected client
						sessions currently 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/connections/socket/count</option></term>
				<listitem>
					<para>
						The total number of socket connections that have been
						made to the broker, whether or not the MQTT connections
						were ultimately successful.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/heap/current</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</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/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/mqtt/connect/received</option></term>
				<listitem>
					<para>The total number of MQTT CONNECT messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/connack/sent</option></term>
				<listitem>
					<para>The total number of MQTT CONNACK messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/publish/dropped</option></term>
				<term><option>$SYS/broker/publish/messages/dropped</option></term>
				<listitem>
					<para>
						The total number of MQTT 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/mqtt/publish/received</option></term>
				<term><option>$SYS/broker/publish/messages/received</option></term>
				<listitem>
					<para>The total number of MQTT PUBLISH messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/publish/sent</option></term>
				<term><option>$SYS/broker/publish/messages/sent</option></term>
				<listitem>
					<para>The total number of MQTT PUBLISH messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/puback/received</option></term>
				<listitem>
					<para>The total number of MQTT PUBACK messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/puback/sent</option></term>
				<listitem>
					<para>The total number of MQTT PUBACK messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pubrec/received</option></term>
				<listitem>
					<para>The total number of MQTT PUBREC messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pubrec/sent</option></term>
				<listitem>
					<para>The total number of MQTT PUBREC messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pubrel/received</option></term>
				<listitem>
					<para>The total number of MQTT PUBREL messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pubrel/sent</option></term>
				<listitem>
					<para>The total number of MQTT PUBREL messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pubcomp/received</option></term>
				<listitem>
					<para>The total number of MQTT PUBCOMP messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pubcomp/sent</option></term>
				<listitem>
					<para>The total number of MQTT PUBCOMP messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/subscribe/received</option></term>
				<listitem>
					<para>The total number of MQTT SUBSCRIBE messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/suback/sent</option></term>
				<listitem>
					<para>The total number of MQTT SUBACK messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/unsubscribe/received</option></term>
				<listitem>
					<para>The total number of MQTT UNSUBSCRIBE messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/unsuback/sent</option></term>
				<listitem>
					<para>The total number of MQTT UNSUBACK messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pingreq/received</option></term>
				<listitem>
					<para>The total number of MQTT PINGREQ messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/pingresp/sent</option></term>
				<listitem>
					<para>The total number of MQTT PINGRESP messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/disconnect/received</option></term>
				<listitem>
					<para>The total number of MQTT DISCONNECT messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/disconnect/sent</option></term>
				<listitem>
					<para>The total number of MQTT DISCONNECT messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/auth/received</option></term>
				<listitem>
					<para>The total number of MQTT AUTH messages received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/mqtt/auth/sent</option></term>
				<listitem>
					<para>The total number of MQTT AUTH messages sent since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/packet/out/count</option></term>
				<listitem>
					<para>
						The current number of packets queued for delivery across
						all clients. A large and increasing value here may
						indicate messages are being sent faster than the network
						can handle.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/packet/out/bytes</option></term>
				<listitem>
					<para>
						The current number of bytes in packets queued for
						delivery across all clients. A large and increasing
						value here may indicate messages are being sent faster
						than the network can handle.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/publish/bytes/received</option></term>
				<listitem>
					<para>The total number of PUBLISH payload bytes received since the broker started.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>$SYS/broker/publish/bytes/sent</option></term>
				<listitem>
					<para>The total number of PUBLISH payload bytes 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/shared_subscriptions/count</option></term>
				<listitem>
					<para>The total number of shared subscriptions active on the broker.</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 &lt;process id of mosquitto&gt;</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>
					<para>
						The logs will also be closed and reopened.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>SIGRTMIN</term>
				<listitem>
					<para>
						Upon receiving the SIGRTMIN signal, mosquitto will
						close and reopen the logs to support log rotation.
					</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>Environment Variables</title>
		<variablelist>
			<xi:include href="common/env-var-mosquitto-unsafe-allow-symlinks.xml" />
		</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>

	<xi:include href="common/section-bugs.xml" />

	<refsect1>
		<title>See Also</title>
		<simplelist type="inline">
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-7.html">mosquitto</link></refentrytitle>
					<manvolnum>7</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
					<manvolnum>7</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-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="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>
