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 5.0/3.1.1/3.1.
13

OPTIONS

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
20               Important
21               See the -p option for a description of changes in behaviour
22               from 1.6.x to 2.0.
23
24       -d, --daemon
25           Run mosquitto in the background as a daemon. All other behaviour
26           remains the same.
27
28       -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
32               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
38               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
44       -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

CONFIGURATION

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

PLATFORM LIMITATIONS

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

MQTT SUPPORT

63       Mosquitto supports MQTT v5.0, v3.1.1, and v3.1.
64
65   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
70       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
80           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
88           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
92           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
97           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
103           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
108       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
113           CONNECT
114
115               •   Authentication data
116
117               •   Authentication method
118
119               •   Maximum packet size
120
121               •   Receive maximum
122
123               •   Request problem information - supported but not used
124
125               •   Request response information - supported but not used
126
127               •   Session expiry interval
128
129               •   Topic alias maximum
130
131               •   User property
132
133           Last will and testament
134
135               •   Content type
136
137               •   Correlation data
138
139               •   Message expiry interval
140
141               •   Payload format indicator
142
143               •   Response topic
144
145               •   User property
146
147               •   Will delay interval
148
149           CONNACK
150
151               •   Assigned client identifier
152
153               •   Authentication data
154
155               •   Authentication method
156
157               •   Maximum packet size
158
159               •   Maximum qos
160
161               •   Reason string - supported but not used
162
163               •   Receive maximum
164
165               •   Response information - supported but not used
166
167               •   Retain available
168
169               •   Server keep alive
170
171               •   Server reference - supported but not used
172
173               •   Session expiry interval
174
175               •   Shared subscription available
176
177               •   Subscription identifiers available
178
179               •   Topic alias maximum
180
181               •   User property
182
183               •   Wildcard subscription available
184
185           PUBLISH
186
187               •   Content type
188
189               •   Correlation data
190
191               •   Message expiry interval
192
193               •   Payload format indicator
194
195               •   Response topic
196
197               •   Subscription identifier
198
199               •   Topic alias
200
201               •   User property
202
203           PUBACK / PUBREC / PUBREL / PUBCOMP / SUBACK / SUBSCRIBE / SUBACK
204
205               •   Reason string - supported but not used
206
207               •   User property
208
209           SUBSCRIBE
210
211               •   Subscription identifier
212
213               •   User property
214
215           DISCONNECT
216
217               •   Reason string - supported but not used
218
219               •   Server reference - supported but not used
220
221               •   Session expiry interval
222
223               •   User property
224
225           AUTH
226
227               •   Authentication method
228
229               •   Authentication data
230
231               •   Reason string - supported but not used
232
233               •   User property
234
235   MQTT v3.1.1
236       Mosquitto provides full MQTT v3.1.1 support.
237
238   MQTT v3.1
239       Mosquitto provides full MQTT v3.1 support.
240
241   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

BROKER STATUS

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
254       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
260       $SYS/broker/bytes/received
261           The total number of bytes received since the broker started.
262
263       $SYS/broker/bytes/sent
264           The total number of bytes sent since the broker started.
265
266       $SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated)
267           The number of currently connected clients.
268
269       $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
274       $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
280       $SYS/broker/clients/maximum
281           The maximum number of clients that have been connected to the
282           broker at the same time.
283
284       $SYS/broker/clients/total
285           The total number of active and inactive clients currently connected
286           and registered on the broker.
287
288       $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
296       $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
300       $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
304       $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
311       $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
317       $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
323       $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
330       $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
337       $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
345       $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
352       $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
359       $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
366       $SYS/broker/messages/inflight
367           The number of messages with QoS>0 that are awaiting
368           acknowledgments.
369
370       $SYS/broker/messages/received
371           The total number of messages of any type received since the broker
372           started.
373
374       $SYS/broker/messages/sent
375           The total number of messages of any type sent since the broker
376           started.
377
378       $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
384       $SYS/broker/publish/messages/received
385           The total number of PUBLISH messages received since the broker
386           started.
387
388       $SYS/broker/publish/messages/sent
389           The total number of PUBLISH messages sent since the broker started.
390
391       $SYS/broker/retained messages/count
392           The total number of retained messages active on the broker.
393
394       $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
399       $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
404       $SYS/broker/subscriptions/count
405           The total number of subscriptions active on the broker.
406
407       $SYS/broker/version
408           The version of the broker. Static.
409

WILDCARD TOPIC SUBSCRIPTIONS

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
417       •   a/b/c/d
418
419       •   +/b/c/d
420
421       •   a/+/c/d
422
423       •   a/+/+/d
424
425       •   +/+/+/+
426
427       The following subscriptions will not match:
428
429       •   a/b/c
430
431       •   b/+/c/d
432
433       •   +/+/+
434
435       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
439       •   a/b/c/d
440
441       •   #
442
443       •   a/#
444
445       •   a/b/#
446
447       •   a/b/c/#
448
449       •   +/b/c/#
450
451       The $SYS hierarchy does not match a subscription of "#". If you want to
452       observe the entire $SYS hierarchy, subscribe to $SYS/#.
453
454       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

BRIDGES

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
469       For information on configuring bridges, see mosquitto.conf(5).
470

SIGNALS

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
476       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
482           If TLS certificates are in use, then mosquitto will also reload
483           certificate on receiving a SIGHUP.
484
485       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
490       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

FILES

497       /etc/mosquitto/mosquitto.conf
498           Configuration file. See mosquitto.conf(5).
499
500       /var/lib/mosquitto/mosquitto.db
501           Persistent message data storage location if persist enabled.
502
503       /etc/hosts.allow, /etc/hosts.deny
504           Host access control via tcp-wrappers as described in
505           hosts_access(5).
506

BUGS

508       mosquitto bug information can be found at
509       https://github.com/eclipse/mosquitto/issues
510

SEE ALSO

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

THANKS

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
521       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

AUTHOR

525       Roger Light <roger@atchoo.org>
526
527
528
529Mosquitto Project                 09/18/2023                      MOSQUITTO(8)
Impressum