'\" t
.\"     Title: mosquitto
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/14/2019
.\"    Manual: System management commands
.\"    Source: Mosquitto Project
.\"  Language: English
.\"
.TH "MOSQUITTO" "8" "02/14/2019" "Mosquitto Project" "System management commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mosquitto \- an MQTT broker
.SH "SYNOPSIS"
.HP \w'\fBmosquitto\fR\ 'u
\fBmosquitto\fR [\-c\ \fIconfig\ file\fR] [\-d | \-\-daemon] [\-p\ \fIport\ number\fR] [\-v]
.SH "DESCRIPTION"
.PP
\fBmosquitto\fR
is a broker for the MQTT protocol version 3\&.1\&.1/3\&.1\&.
.SH "OPTIONS"
.PP
\fB\-c\fR, \fB\-\-config\-file\fR
.RS 4
Load configuration from a file\&. If not given, the default values as described in
\fBmosquitto.conf\fR(5)
are used\&.
.RE
.PP
\fB\-d\fR, \fB\-\-daemon\fR
.RS 4
Run
\fBmosquitto\fR
in the background as a daemon\&. All other behaviour remains the same\&.
.RE
.PP
\fB\-p\fR, \fB\-\-port\fR
.RS 4
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\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Use verbose logging\&. This is equivalent to setting
\fBlog_type\fR
to
\fBall\fR
in the configuration file\&. This overrides and logging options given in the configuration file\&.
.RE
.SH "CONFIGURATION"
.PP
The broker can be configured using a configuration file as described in
\fBmosquitto.conf\fR(5)
and this is the main point of information for mosquitto\&. The files required for SSL/TLS support are described in
\fBmosquitto-tls\fR(7)\&.
.SH "BROKER STATUS"
.PP
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
\fBsys_interval\fR
seconds\&. If
\fBsys_interval\fR
is 0, then updates are not sent\&.
.PP
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 \*(Aq$SYS/\&.\&.\&.\*(Aq or to escape the dollar symbol: \e$SYS/\&.\&.\&. otherwise the $SYS will be treated as an environment variable\&.
.PP
\fB$SYS/broker/bytes/received\fR
.RS 4
The total number of bytes received since the broker started\&.
.RE
.PP
\fB$SYS/broker/bytes/sent\fR
.RS 4
The total number of bytes sent since the broker started\&.
.RE
.PP
\fB$SYS/broker/clients/connected\fR, \fB$SYS/broker/clients/active\fR (deprecated)
.RS 4
The number of currently connected clients\&.
.RE
.PP
\fB$SYS/broker/clients/expired\fR
.RS 4
The number of disconnected persistent clients that have been expired and removed through the persistent_client_expiration option\&.
.RE
.PP
\fB$SYS/broker/clients/disconnected\fR, \fB$SYS/broker/clients/inactive\fR (deprecated)
.RS 4
The total number of persistent clients (with clean session disabled) that are registered at the broker but are currently disconnected\&.
.RE
.PP
\fB$SYS/broker/clients/maximum\fR
.RS 4
The maximum number of clients that have been connected to the broker at the same time\&.
.RE
.PP
\fB$SYS/broker/clients/total\fR
.RS 4
The total number of active and inactive clients currently connected and registered on the broker\&.
.RE
.PP
\fB$SYS/broker/connection/#\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/heap/current size\fR
.RS 4
The current size of the heap memory in use by mosquitto\&. Note that this topic may be unavailable depending on compile time options\&.
.RE
.PP
\fB$SYS/broker/heap/maximum size\fR
.RS 4
The largest amount of heap memory used by mosquitto\&. Note that this topic may be unavailable depending on compile time options\&.
.RE
.PP
\fB$SYS/broker/load/connections/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/bytes/received/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/bytes/sent/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/messages/received/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/messages/sent/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/publish/dropped/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/publish/received/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/publish/sent/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/load/sockets/+\fR
.RS 4
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\&.
.RE
.PP
\fB$SYS/broker/messages/inflight\fR
.RS 4
The number of messages with QoS>0 that are awaiting acknowledgments\&.
.RE
.PP
\fB$SYS/broker/messages/received\fR
.RS 4
The total number of messages of any type received since the broker started\&.
.RE
.PP
\fB$SYS/broker/messages/sent\fR
.RS 4
The total number of messages of any type sent since the broker started\&.
.RE
.PP
\fB$SYS/broker/publish/messages/dropped\fR
.RS 4
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
\fBmosquitto.conf\fR(5)
for more information\&.
.RE
.PP
\fB$SYS/broker/publish/messages/received\fR
.RS 4
The total number of PUBLISH messages received since the broker started\&.
.RE
.PP
\fB$SYS/broker/publish/messages/sent\fR
.RS 4
The total number of PUBLISH messages sent since the broker started\&.
.RE
.PP
\fB$SYS/broker/retained messages/count\fR
.RS 4
The total number of retained messages active on the broker\&.
.RE
.PP
\fB$SYS/broker/store/messages/count\fR, \fB$SYS/broker/messages/stored\fR (deprecated)
.RS 4
The number of messages currently held in the message store\&. This includes retained messages and messages queued for durable clients\&.
.RE
.PP
\fB$SYS/broker/store/messages/bytes\fR
.RS 4
The number of bytes currently held by message payloads in the message store\&. This includes retained messages and messages queued for durable clients\&.
.RE
.PP
\fB$SYS/broker/subscriptions/count\fR
.RS 4
The total number of subscriptions active on the broker\&.
.RE
.PP
\fB$SYS/broker/version\fR
.RS 4
The version of the broker\&. Static\&.
.RE
.SH "WILDCARD TOPIC SUBSCRIPTIONS"
.PP
In addition to allowing clients to subscribe to specific topics, mosquitto also allows the use of two wildcards in subscriptions\&.
\fB+\fR
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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/b/c/d
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
+/b/c/d
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/+/c/d
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/+/+/d
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
+/+/+/+
.RE
.PP
The following subscriptions will not match:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/b/c
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
b/+/c/d
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
+/+/+
.RE
.PP
The second wildcard is
\fB#\fR
and is used to match all subsequent levels of hierarchy\&. With a topic of "a/b/c/d", the following example subscriptions will match:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/b/c/d
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
#
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/#
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/b/#
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a/b/c/#
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
+/b/c/#
.RE
.PP
The $SYS hierarchy does not match a subscription of "#"\&. If you want to observe the entire $SYS hierarchy, subscribe to $SYS/#\&.
.PP
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
\fB#\fR
wildcard must only ever be used as the final character of a subscription\&.
.SH "BRIDGES"
.PP
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\&.
.PP
For information on configuring bridges, see
\fBmosquitto.conf\fR(5)\&.
.SH "SIGNALS"
.PP
SIGHUP
.RS 4
Upon receiving the SIGHUP signal, mosquitto will attempt to reload configuration file data, assuming that the
\fB\-c\fR
argument was provided when mosquitto was started\&. Not all configuration parameters can be reloaded without restarting\&. See
\fBmosquitto.conf\fR(5)
for details\&.
.RE
.PP
SIGUSR1
.RS 4
Upon receiving the SIGUSR1 signal, mosquitto will write the persistence database to disk\&. This signal is only acted upon if persistence is enabled\&.
.RE
.PP
SIGUSR2
.RS 4
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\&.
.RE
.SH "FILES"
.PP
/etc/mosquitto/mosquitto\&.conf
.RS 4
Configuration file\&. See
\fBmosquitto.conf\fR(5)\&.
.RE
.PP
/var/lib/mosquitto/mosquitto\&.db
.RS 4
Persistent message data storage location if persist enabled\&.
.RE
.PP
/etc/hosts\&.allow, /etc/hosts\&.deny
.RS 4
Host access control via tcp\-wrappers as described in
\fBhosts_access\fR(5)\&.
.RE
.SH "BUGS"
.PP
\fBmosquitto\fR
bug information can be found at
\m[blue]\fB\%https://github.com/eclipse/mosquitto/issues\fR\m[]
.SH "SEE ALSO"
\fBmqtt\fR(7), \fBmosquitto-tls\fR(7), \fBmosquitto.conf\fR(5), \fBhosts_access\fR(5), \fBmosquitto_passwd\fR(1), \fBmosquitto_pub\fR(1), \fBmosquitto_sub\fR(1), \fBlibmosquitto\fR(3)
.SH "THANKS"
.PP
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\*(AqLeary for providing clarifications of the protocol\&.
.PP
Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for organising OggCamp, where Andy gave a talk that inspired mosquitto\&.
.SH "AUTHOR"
.PP
Roger Light
<roger@atchoo\&.org>