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 3.1.1/3.1.
13
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 -d, --daemon
20 Run mosquitto in the background as a daemon. All other behaviour
21 remains the same.
22 -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 -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
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
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 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 $SYS/broker/bytes/received
54 The total number of bytes received since the broker started.
55 $SYS/broker/bytes/sent
57 The total number of bytes sent since the broker started.
58 $SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated)
60 The number of currently connected clients.
61 $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 $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 $SYS/broker/clients/maximum
74 The maximum number of clients that have been connected to the
75 broker at the same time.
76 $SYS/broker/clients/total
78 The total number of active and inactive clients currently connected
79 and registered on the broker.
80 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $SYS/broker/messages/inflight
160 The number of messages with QoS>0 that are awaiting
161 acknowledgments.
162 $SYS/broker/messages/received
164 The total number of messages of any type received since the broker
165 started.
166 $SYS/broker/messages/sent
168 The total number of messages of any type sent since the broker
169 started.
170 $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 $SYS/broker/publish/messages/received
178 The total number of PUBLISH messages received since the broker
179 started.
180 $SYS/broker/publish/messages/sent
182 The total number of PUBLISH messages sent since the broker started.
183 $SYS/broker/retained messages/count
185 The total number of retained messages active on the broker.
186 $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 $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 $SYS/broker/subscriptions/count
198 The total number of subscriptions active on the broker.
199 $SYS/broker/version
201 The version of the broker. Static.
202
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 · a/b/c/d
211 · +/b/c/d
213 · a/+/c/d
215 · a/+/+/d
217 · +/+/+/+
219 The following subscriptions will not match:
221 · a/b/c
223 · b/+/c/d
225 · +/+/+
227 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 · a/b/c/d
233 · #
235 · a/#
237 · a/b/#
239 · a/b/c/#
241 · +/b/c/#
243 The $SYS hierarchy does not match a subscription of "#". If you want to
245 observe the entire $SYS hierarchy, subscribe to $SYS/#.
246 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
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 For information on configuring bridges, see mosquitto.conf(5).
263
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 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 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
283 /etc/mosquitto/mosquitto.conf
284 Configuration file. See mosquitto.conf(5).
285 /var/lib/mosquitto/mosquitto.db
287 Persistent message data storage location if persist enabled.
288 /etc/hosts.allow, /etc/hosts.deny
290 Host access control via tcp-wrappers as described in
291 hosts_access(5).
292
294 mosquitto bug information can be found at
295 https://github.com/eclipse/mosquitto/issues
296
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
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 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
311 Roger Light <roger@atchoo.org>
312Mosquitto Project 08/19/2020 MOSQUITTO(8)