1MOSQUITTO(8)              System management commands              MOSQUITTO(8)
2
3
4

NAME

6       mosquitto - an MQTT broker
7

SYNOPSIS

9       mosquitto [-c config file] [-d | --daemon] [-p port number] [-v]
10

DESCRIPTION

12       mosquitto is a broker for the MQTT protocol version 3.1.1/3.1.
13

OPTIONS

15       -c, --config-file
16           Load configuration from a file. If not given, the default values as
17           described in mosquitto.conf(5) are used.
18
19       -d, --daemon
20           Run mosquitto in the background as a daemon. All other behaviour
21           remains the same.
22
23       -p, --port
24           Listen on the port specified instead of the default 1883. This acts
25           in addition to the port setting in the config file. May be
26           specified multiple times to open multiple sockets listening on
27           different ports. This socket will be bound to all network
28           interfaces.
29
30       -v, --verbose
31           Use verbose logging. This is equivalent to setting log_type to all
32           in the configuration file. This overrides and logging options given
33           in the configuration file.
34

CONFIGURATION

36       The broker can be configured using a configuration file as described in
37       mosquitto.conf(5) and this is the main point of information for
38       mosquitto. The files required for SSL/TLS support are described in
39       mosquitto-tls(7).
40

BROKER STATUS

42       Clients can find information about the broker by subscribing to topics
43       in the $SYS hierarchy as follows. Topics marked as static are only sent
44       once per client on subscription. All other topics are updated every
45       sys_interval seconds. If sys_interval is 0, then updates are not sent.
46
47       Note that if you are using a command line client to interact with the
48       $SYS topics and your shell interprets $ as an environment variable, you
49       need to place the topic in single quotes '$SYS/...' or to escape the
50       dollar symbol: \$SYS/... otherwise the $SYS will be treated as an
51       environment variable.
52
53       $SYS/broker/bytes/received
54           The total number of bytes received since the broker started.
55
56       $SYS/broker/bytes/sent
57           The total number of bytes sent since the broker started.
58
59       $SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated)
60           The number of currently connected clients.
61
62       $SYS/broker/clients/expired
63           The number of disconnected persistent clients that have been
64           expired and removed through the persistent_client_expiration
65           option.
66
67       $SYS/broker/clients/disconnected, $SYS/broker/clients/inactive
68       (deprecated)
69           The total number of persistent clients (with clean session
70           disabled) that are registered at the broker but are currently
71           disconnected.
72
73       $SYS/broker/clients/maximum
74           The maximum number of clients that have been connected to the
75           broker at the same time.
76
77       $SYS/broker/clients/total
78           The total number of active and inactive clients currently connected
79           and registered on the broker.
80
81       $SYS/broker/connection/#
82           When bridges are configured to/from the broker, common practice is
83           to provide a status topic that indicates the state of the
84           connection. This is provided within $SYS/broker/connection/ by
85           default. If the value of the topic is 1 the connection is active,
86           if 0 then it is not active. See the Bridges section below for more
87           information on bridges.
88
89       $SYS/broker/heap/current size
90           The current size of the heap memory in use by mosquitto. Note that
91           this topic may be unavailable depending on compile time options.
92
93       $SYS/broker/heap/maximum size
94           The largest amount of heap memory used by mosquitto. Note that this
95           topic may be unavailable depending on compile time options.
96
97       $SYS/broker/load/connections/+
98           The moving average of the number of CONNECT packets received by the
99           broker over different time intervals. The final "+" of the
100           hierarchy can be 1min, 5min or 15min. The value returned represents
101           the number of connections received in 1 minute, averaged over 1, 5
102           or 15 minutes.
103
104       $SYS/broker/load/bytes/received/+
105           The moving average of the number of bytes received by the broker
106           over different time intervals. The final "+" of the hierarchy can
107           be 1min, 5min or 15min. The value returned represents the number of
108           bytes received in 1 minute, averaged over 1, 5 or 15 minutes.
109
110       $SYS/broker/load/bytes/sent/+
111           The moving average of the number of bytes sent by the broker over
112           different time intervals. The final "+" of the hierarchy can be
113           1min, 5min or 15min. The value returned represents the number of
114           bytes sent in 1 minute, averaged over 1, 5 or 15 minutes.
115
116       $SYS/broker/load/messages/received/+
117           The moving average of the number of all types of MQTT messages
118           received by the broker over different time intervals. The final "+"
119           of the hierarchy can be 1min, 5min or 15min. The value returned
120           represents the number of messages received in 1 minute, averaged
121           over 1, 5 or 15 minutes.
122
123       $SYS/broker/load/messages/sent/+
124           The moving average of the number of all types of MQTT messages sent
125           by the broker over different time intervals. The final "+" of the
126           hierarchy can be 1min, 5min or 15min. The value returned represents
127           the number of messages send in 1 minute, averaged over 1, 5 or 15
128           minutes.
129
130       $SYS/broker/load/publish/dropped/+
131           The moving average of the number of publish messages dropped by the
132           broker over different time intervals. This shows the rate at which
133           durable clients that are disconnected are losing messages. The
134           final "+" of the hierarchy can be 1min, 5min or 15min. The value
135           returned represents the number of messages dropped in 1 minute,
136           averaged over 1, 5 or 15 minutes.
137
138       $SYS/broker/load/publish/received/+
139           The moving average of the number of publish messages received by
140           the broker over different time intervals. The final "+" of the
141           hierarchy can be 1min, 5min or 15min. The value returned represents
142           the number of publish messages received in 1 minute, averaged over
143           1, 5 or 15 minutes.
144
145       $SYS/broker/load/publish/sent/+
146           The moving average of the number of publish messages sent by the
147           broker over different time intervals. The final "+" of the
148           hierarchy can be 1min, 5min or 15min. The value returned represents
149           the number of publish messages sent in 1 minute, averaged over 1, 5
150           or 15 minutes.
151
152       $SYS/broker/load/sockets/+
153           The moving average of the number of socket connections opened to
154           the broker over different time intervals. The final "+" of the
155           hierarchy can be 1min, 5min or 15min. The value returned represents
156           the number of socket connections in 1 minute, averaged over 1, 5 or
157           15 minutes.
158
159       $SYS/broker/messages/inflight
160           The number of messages with QoS>0 that are awaiting
161           acknowledgments.
162
163       $SYS/broker/messages/received
164           The total number of messages of any type received since the broker
165           started.
166
167       $SYS/broker/messages/sent
168           The total number of messages of any type sent since the broker
169           started.
170
171       $SYS/broker/publish/messages/dropped
172           The total number of publish messages that have been dropped due to
173           inflight/queuing limits. See the max_inflight_messages and
174           max_queued_messages options in mosquitto.conf(5) for more
175           information.
176
177       $SYS/broker/publish/messages/received
178           The total number of PUBLISH messages received since the broker
179           started.
180
181       $SYS/broker/publish/messages/sent
182           The total number of PUBLISH messages sent since the broker started.
183
184       $SYS/broker/retained messages/count
185           The total number of retained messages active on the broker.
186
187       $SYS/broker/store/messages/count, $SYS/broker/messages/stored
188       (deprecated)
189           The number of messages currently held in the message store. This
190           includes retained messages and messages queued for durable clients.
191
192       $SYS/broker/store/messages/bytes
193           The number of bytes currently held by message payloads in the
194           message store. This includes retained messages and messages queued
195           for durable clients.
196
197       $SYS/broker/subscriptions/count
198           The total number of subscriptions active on the broker.
199
200       $SYS/broker/version
201           The version of the broker. Static.
202

WILDCARD TOPIC SUBSCRIPTIONS

204       In addition to allowing clients to subscribe to specific topics,
205       mosquitto also allows the use of two wildcards in subscriptions.  + is
206       the wildcard used to match a single level of hierarchy. For example,
207       for a topic of "a/b/c/d", the following example subscriptions will
208       match:
209
210       ·   a/b/c/d
211
212       ·   +/b/c/d
213
214       ·   a/+/c/d
215
216       ·   a/+/+/d
217
218       ·   +/+/+/+
219
220       The following subscriptions will not match:
221
222       ·   a/b/c
223
224       ·   b/+/c/d
225
226       ·   +/+/+
227
228       The second wildcard is # and is used to match all subsequent levels of
229       hierarchy. With a topic of "a/b/c/d", the following example
230       subscriptions will match:
231
232       ·   a/b/c/d
233
234       ·   #
235
236       ·   a/#
237
238       ·   a/b/#
239
240       ·   a/b/c/#
241
242       ·   +/b/c/#
243
244       The $SYS hierarchy does not match a subscription of "#". If you want to
245       observe the entire $SYS hierarchy, subscribe to $SYS/#.
246
247       Note that the wildcards must be only ever used on their own, so a
248       subscription of "a/b+/c" is not valid use of a wildcard. The # wildcard
249       must only ever be used as the final character of a subscription.
250

BRIDGES

252       Multiple brokers can be connected together with the bridging
253       functionality. This is useful where it is desirable to share
254       information between locations, but where not all of the information
255       needs to be shared. An example could be where a number of users are
256       running a broker to help record power usage and for a number of other
257       reasons. The power usage could be shared through bridging all of the
258       user brokers to a common broker, allowing the power usage of all users
259       to be collected and compared. The other information would remain local
260       to each broker.
261
262       For information on configuring bridges, see mosquitto.conf(5).
263

SIGNALS

265       SIGHUP
266           Upon receiving the SIGHUP signal, mosquitto will attempt to reload
267           configuration file data, assuming that the -c argument was provided
268           when mosquitto was started. Not all configuration parameters can be
269           reloaded without restarting. See mosquitto.conf(5) for details.
270
271       SIGUSR1
272           Upon receiving the SIGUSR1 signal, mosquitto will write the
273           persistence database to disk. This signal is only acted upon if
274           persistence is enabled.
275
276       SIGUSR2
277           The SIGUSR2 signal causes mosquitto to print out the current
278           subscription tree, along with information about where retained
279           messages exist. This is intended as a testing feature only and may
280           be removed at any time.
281

FILES

283       /etc/mosquitto/mosquitto.conf
284           Configuration file. See mosquitto.conf(5).
285
286       /var/lib/mosquitto/mosquitto.db
287           Persistent message data storage location if persist enabled.
288
289       /etc/hosts.allow, /etc/hosts.deny
290           Host access control via tcp-wrappers as described in
291           hosts_access(5).
292

BUGS

294       mosquitto bug information can be found at
295       https://github.com/eclipse/mosquitto/issues
296

SEE ALSO

298       mqtt(7), mosquitto-tls(7), mosquitto.conf(5), hosts_access(5),
299       mosquitto_passwd(1), mosquitto_pub(1), mosquitto_rr(1),
300       mosquitto_sub(1), libmosquitto(3)
301

THANKS

303       Thanks to Andy Stanford-Clark for being one of the people who came up
304       with MQTT in the first place. Thanks to Andy and Nicholas O'Leary for
305       providing clarifications of the protocol.
306
307       Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for
308       organising OggCamp, where Andy gave a talk that inspired mosquitto.
309

AUTHOR

311       Roger Light <roger@atchoo.org>
312
313
314
315Mosquitto Project                 08/19/2020                      MOSQUITTO(8)
Impressum