1MOSQUITTO(8) System management commands MOSQUITTO(8)
2
6 mosquitto - an MQTT broker
7
9 mosquitto [-c config file] [-d | --daemon] [-p port number] [-v]
10
12 mosquitto is a broker for the MQTT protocol version 5.0/3.1.1/3.1.
13
15 -c, --config-file
16 Load configuration from a file. If not given, then the broker will
17 listen on port 1883 bound to the loopback interface, and the
18 default values as described in mosquitto.conf(5) are used.
19 Important
21 See the -p option for a description of changes in behaviour
22 from 1.6.x to 2.0.
23 -d, --daemon
25 Run mosquitto in the background as a daemon. All other behaviour
26 remains the same.
27 -p, --port
29 Listen on the port specified. May be specified up to 10 times to
30 open multiple sockets listening on different ports.
31 Important
33 In version 1.6.x and earlier, the listener defined by -p (or
34 the default port of 1883) would be bound to all interfaces and
35 so be accessible from any network. It could also be used in
36 combination with -c.
37 From version 2.0 onwards, the listeners defined with -p are
39 bound to the loopback interface only, and so can only be
40 connected to from the local machine. If both -p is used and a
41 listener is defined in a configuration file, then the -p
42 options are IGNORED.
43 -v, --verbose
45 Use verbose logging. This is equivalent to setting log_type to all
46 in the configuration file. This overrides and logging options given
47 in the configuration file.
48
50 The broker can be configured using a configuration file as described in
51 mosquitto.conf(5) and this is the main point of information for
52 mosquitto. The files required for SSL/TLS support are described in
53 mosquitto-tls(7).
54
56 Some versions of Windows have limitations on the number of concurrent
57 connections due to the Windows API being used. In modern versions of
58 Windows, e.g. Windows 10 or Windows Server 2019, this is approximately
59 8192 connections. In earlier versions of Windows, this limit is 2048
60 connections.
61
63 Mosquitto supports MQTT v5.0, v3.1.1, and v3.1.
64 MQTT v5.0
66 Mosquitto provides full MQTT v5.0 support, but some features are not
67 used directly. The following sections describe the new features and
68 explain where Mosquitto does not make use of a feature.
69 Features
71 Enhanced authentication
72 Basic MQTT authentication uses username/password checks.
73 Enhanced authentication allows different authentication schemes
74 to be integrated into MQTT, and even those schemes with
75 multiple step processes. Clients request a particular type of
76 authentication and if the broker is configured for that scheme
77 the authentication continues. Mosquitto supports enhanced
78 authentication through plugins.
79 Error handling
81 Most MQTT packets now have the concept of a reason code which
82 indicates success or failure, and what the failure was.
83 Mosquitto provides full support for reason codes, but does not
84 make use of the reason string feature which can be used to
85 provide a human readable error string to explain the reason
86 code.
87 Flow control
89 The number of "in flight" messages for QoS 1 and QoS 2 can be
90 controlled by both the client and the broker.
91 Request / response
93 MQTT v5.0 adds a request/response pattern that allows a client
94 to publish a message and instruct the subscribers of that
95 message where to publish a response.
96 Server redirection
98 Server redirection is the concept of telling a client to
99 connect to a different MQTT broker, either on CONNECT or with a
100 broker initiated DISCONNECT. Mosquitto does not currently make
101 use of this feature.
102 Shared subscriptions
104 When multiple clients subscribe to the same shared
105 subscription, only one client out of the group will receive
106 each message which allows for distributing work loads.
107 Packet properties
109 MQTT v5.0 allows properties to be added to packets to control
110 certain behaviour. Unless noted, Mosquitto support the properties
111 listed below.
112 CONNECT
114 • Authentication data
116 • Authentication method
118 • Maximum packet size
120 • Receive maximum
122 • Request problem information - supported but not used
124 • Request response information - supported but not used
126 • Session expiry interval
128 • Topic alias maximum
130 • User property
132 Last will and testament
134 • Content type
136 • Correlation data
138 • Message expiry interval
140 • Payload format indicator
142 • Response topic
144 • User property
146 • Will delay interval
148 CONNACK
150 • Assigned client identifier
152 • Authentication data
154 • Authentication method
156 • Maximum packet size
158 • Maximum qos
160 • Reason string - supported but not used
162 • Receive maximum
164 • Response information - supported but not used
166 • Retain available
168 • Server keep alive
170 • Server reference - supported but not used
172 • Session expiry interval
174 • Shared subscription available
176 • Subscription identifiers available
178 • Topic alias maximum
180 • User property
182 • Wildcard subscription available
184 PUBLISH
186 • Content type
188 • Correlation data
190 • Message expiry interval
192 • Payload format indicator
194 • Response topic
196 • Subscription identifier
198 • Topic alias
200 • User property
202 PUBACK / PUBREC / PUBREL / PUBCOMP / SUBACK / SUBSCRIBE / SUBACK
204 • Reason string - supported but not used
206 • User property
208 SUBSCRIBE
210 • Subscription identifier
212 • User property
214 DISCONNECT
216 • Reason string - supported but not used
218 • Server reference - supported but not used
220 • Session expiry interval
222 • User property
224 AUTH
226 • Authentication method
228 • Authentication data
230 • Reason string - supported but not used
232 • User property
234 MQTT v3.1.1
236 Mosquitto provides full MQTT v3.1.1 support.
237 MQTT v3.1
239 Mosquitto provides full MQTT v3.1 support.
240 MQTT v3
242 MQTT v3 is an obsolete version of the protocol that does not support
243 username/password authentication and used the clean start flag in the
244 CONNECT packet which applied only to the start of a session. An MQTT v3
245 client will be able to successfully connect to a Mosquitto instance
246 that does not require authentication.
247
249 Clients can find information about the broker by subscribing to topics
250 in the $SYS hierarchy as follows. Topics marked as static are only sent
251 once per client on subscription. All other topics are updated every
252 sys_interval seconds. If sys_interval is 0, then updates are not sent.
253 Note that if you are using a command line client to interact with the
255 $SYS topics and your shell interprets $ as an environment variable, you
256 need to place the topic in single quotes '$SYS/...' or to escape the
257 dollar symbol: \$SYS/... otherwise the $SYS will be treated as an
258 environment variable.
259 $SYS/broker/bytes/received
261 The total number of bytes received since the broker started.
262 $SYS/broker/bytes/sent
264 The total number of bytes sent since the broker started.
265 $SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated)
267 The number of currently connected clients.
268 $SYS/broker/clients/expired
270 The number of disconnected persistent clients that have been
271 expired and removed through the persistent_client_expiration
272 option.
273 $SYS/broker/clients/disconnected, $SYS/broker/clients/inactive
275 (deprecated)
276 The total number of persistent clients (with clean session
277 disabled) that are registered at the broker but are currently
278 disconnected.
279 $SYS/broker/clients/maximum
281 The maximum number of clients that have been connected to the
282 broker at the same time.
283 $SYS/broker/clients/total
285 The total number of active and inactive clients currently connected
286 and registered on the broker.
287 $SYS/broker/connection/#
289 When bridges are configured to/from the broker, common practice is
290 to provide a status topic that indicates the state of the
291 connection. This is provided within $SYS/broker/connection/ by
292 default. If the value of the topic is 1 the connection is active,
293 if 0 then it is not active. See the Bridges section below for more
294 information on bridges.
295 $SYS/broker/heap/current size
297 The current size of the heap memory in use by mosquitto. Note that
298 this topic may be unavailable depending on compile time options.
299 $SYS/broker/heap/maximum size
301 The largest amount of heap memory used by mosquitto. Note that this
302 topic may be unavailable depending on compile time options.
303 $SYS/broker/load/connections/+
305 The moving average of the number of CONNECT packets received by the
306 broker over different time intervals. The final "+" of the
307 hierarchy can be 1min, 5min or 15min. The value returned represents
308 the number of connections received in 1 minute, averaged over 1, 5
309 or 15 minutes.
310 $SYS/broker/load/bytes/received/+
312 The moving average of the number of bytes received by the broker
313 over different time intervals. The final "+" of the hierarchy can
314 be 1min, 5min or 15min. The value returned represents the number of
315 bytes received in 1 minute, averaged over 1, 5 or 15 minutes.
316 $SYS/broker/load/bytes/sent/+
318 The moving average of the number of bytes sent by the broker over
319 different time intervals. The final "+" of the hierarchy can be
320 1min, 5min or 15min. The value returned represents the number of
321 bytes sent in 1 minute, averaged over 1, 5 or 15 minutes.
322 $SYS/broker/load/messages/received/+
324 The moving average of the number of all types of MQTT messages
325 received by the broker over different time intervals. The final "+"
326 of the hierarchy can be 1min, 5min or 15min. The value returned
327 represents the number of messages received in 1 minute, averaged
328 over 1, 5 or 15 minutes.
329 $SYS/broker/load/messages/sent/+
331 The moving average of the number of all types of MQTT messages sent
332 by the broker over different time intervals. The final "+" of the
333 hierarchy can be 1min, 5min or 15min. The value returned represents
334 the number of messages send in 1 minute, averaged over 1, 5 or 15
335 minutes.
336 $SYS/broker/load/publish/dropped/+
338 The moving average of the number of publish messages dropped by the
339 broker over different time intervals. This shows the rate at which
340 durable clients that are disconnected are losing messages. The
341 final "+" of the hierarchy can be 1min, 5min or 15min. The value
342 returned represents the number of messages dropped in 1 minute,
343 averaged over 1, 5 or 15 minutes.
344 $SYS/broker/load/publish/received/+
346 The moving average of the number of publish messages received by
347 the broker over different time intervals. The final "+" of the
348 hierarchy can be 1min, 5min or 15min. The value returned represents
349 the number of publish messages received in 1 minute, averaged over
350 1, 5 or 15 minutes.
351 $SYS/broker/load/publish/sent/+
353 The moving average of the number of publish messages sent by the
354 broker over different time intervals. The final "+" of the
355 hierarchy can be 1min, 5min or 15min. The value returned represents
356 the number of publish messages sent in 1 minute, averaged over 1, 5
357 or 15 minutes.
358 $SYS/broker/load/sockets/+
360 The moving average of the number of socket connections opened to
361 the broker over different time intervals. The final "+" of the
362 hierarchy can be 1min, 5min or 15min. The value returned represents
363 the number of socket connections in 1 minute, averaged over 1, 5 or
364 15 minutes.
365 $SYS/broker/messages/inflight
367 The number of messages with QoS>0 that are awaiting
368 acknowledgments.
369 $SYS/broker/messages/received
371 The total number of messages of any type received since the broker
372 started.
373 $SYS/broker/messages/sent
375 The total number of messages of any type sent since the broker
376 started.
377 $SYS/broker/publish/messages/dropped
379 The total number of publish messages that have been dropped due to
380 inflight/queuing limits. See the max_inflight_messages and
381 max_queued_messages options in mosquitto.conf(5) for more
382 information.
383 $SYS/broker/publish/messages/received
385 The total number of PUBLISH messages received since the broker
386 started.
387 $SYS/broker/publish/messages/sent
389 The total number of PUBLISH messages sent since the broker started.
390 $SYS/broker/retained messages/count
392 The total number of retained messages active on the broker.
393 $SYS/broker/store/messages/count, $SYS/broker/messages/stored
395 (deprecated)
396 The number of messages currently held in the message store. This
397 includes retained messages and messages queued for durable clients.
398 $SYS/broker/store/messages/bytes
400 The number of bytes currently held by message payloads in the
401 message store. This includes retained messages and messages queued
402 for durable clients.
403 $SYS/broker/subscriptions/count
405 The total number of subscriptions active on the broker.
406 $SYS/broker/version
408 The version of the broker. Static.
409
411 In addition to allowing clients to subscribe to specific topics,
412 mosquitto also allows the use of two wildcards in subscriptions. + is
413 the wildcard used to match a single level of hierarchy. For example,
414 for a topic of "a/b/c/d", the following example subscriptions will
415 match:
416 • a/b/c/d
418 • +/b/c/d
420 • a/+/c/d
422 • a/+/+/d
424 • +/+/+/+
426 The following subscriptions will not match:
428 • a/b/c
430 • b/+/c/d
432 • +/+/+
434 The second wildcard is # and is used to match all subsequent levels of
436 hierarchy. With a topic of "a/b/c/d", the following example
437 subscriptions will match:
438 • a/b/c/d
440 • #
442 • a/#
444 • a/b/#
446 • a/b/c/#
448 • +/b/c/#
450 The $SYS hierarchy does not match a subscription of "#". If you want to
452 observe the entire $SYS hierarchy, subscribe to $SYS/#.
453 Note that the wildcards must be only ever used on their own, so a
455 subscription of "a/b+/c" is not valid use of a wildcard. The # wildcard
456 must only ever be used as the final character of a subscription.
457
459 Multiple brokers can be connected together with the bridging
460 functionality. This is useful where it is desirable to share
461 information between locations, but where not all of the information
462 needs to be shared. An example could be where a number of users are
463 running a broker to help record power usage and for a number of other
464 reasons. The power usage could be shared through bridging all of the
465 user brokers to a common broker, allowing the power usage of all users
466 to be collected and compared. The other information would remain local
467 to each broker.
468 For information on configuring bridges, see mosquitto.conf(5).
470
472 On POSIX systems Mosquitto can receive signals and act on them as
473 described below. To send signals, use e.g. kill -HUP <process id of
474 mosquitto>
475 SIGHUP
477 Upon receiving the SIGHUP signal, mosquitto will attempt to reload
478 configuration file data, assuming that the -c argument was provided
479 when mosquitto was started. Not all configuration parameters can be
480 reloaded without restarting. See mosquitto.conf(5) for details.
481 If TLS certificates are in use, then mosquitto will also reload
483 certificate on receiving a SIGHUP.
484 SIGUSR1
486 Upon receiving the SIGUSR1 signal, mosquitto will write the
487 persistence database to disk. This signal is only acted upon if
488 persistence is enabled.
489 SIGUSR2
491 The SIGUSR2 signal causes mosquitto to print out the current
492 subscription tree, along with information about where retained
493 messages exist. This is intended as a testing feature only and may
494 be removed at any time.
495
497 /etc/mosquitto/mosquitto.conf
498 Configuration file. See mosquitto.conf(5).
499 /var/lib/mosquitto/mosquitto.db
501 Persistent message data storage location if persist enabled.
502 /etc/hosts.allow, /etc/hosts.deny
504 Host access control via tcp-wrappers as described in
505 hosts_access(5).
506
508 mosquitto bug information can be found at
509 https://github.com/eclipse/mosquitto/issues
510
512 mqtt(7), mosquitto-tls(7), mosquitto.conf(5), hosts_access(5),
513 mosquitto_ctrl(1), mosquitto_passwd(1), mosquitto_pub(1),
514 mosquitto_rr(1), mosquitto_sub(1), libmosquitto(3)
515
517 Thanks to Andy Stanford-Clark for being one of the people who came up
518 with MQTT in the first place. Thanks to Andy and Nicholas O'Leary for
519 providing clarifications of the protocol.
520 Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for
522 organising OggCamp, where Andy gave a talk that inspired mosquitto.
523
525 Roger Light <roger@atchoo.org>
526Mosquitto Project 09/18/2023 MOSQUITTO(8)