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 Clients can find information about the broker by subscribing to topics
57 in the $SYS hierarchy as follows. Topics marked as static are only sent
58 once per client on subscription. All other topics are updated every
59 sys_interval seconds. If sys_interval is 0, then updates are not sent.
60 Note that if you are using a command line client to interact with the
62 $SYS topics and your shell interprets $ as an environment variable, you
63 need to place the topic in single quotes '$SYS/...' or to escape the
64 dollar symbol: \$SYS/... otherwise the $SYS will be treated as an
65 environment variable.
66 $SYS/broker/bytes/received
68 The total number of bytes received since the broker started.
69 $SYS/broker/bytes/sent
71 The total number of bytes sent since the broker started.
72 $SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated)
74 The number of currently connected clients.
75 $SYS/broker/clients/expired
77 The number of disconnected persistent clients that have been
78 expired and removed through the persistent_client_expiration
79 option.
80 $SYS/broker/clients/disconnected, $SYS/broker/clients/inactive
82 (deprecated)
83 The total number of persistent clients (with clean session
84 disabled) that are registered at the broker but are currently
85 disconnected.
86 $SYS/broker/clients/maximum
88 The maximum number of clients that have been connected to the
89 broker at the same time.
90 $SYS/broker/clients/total
92 The total number of active and inactive clients currently connected
93 and registered on the broker.
94 $SYS/broker/connection/#
96 When bridges are configured to/from the broker, common practice is
97 to provide a status topic that indicates the state of the
98 connection. This is provided within $SYS/broker/connection/ by
99 default. If the value of the topic is 1 the connection is active,
100 if 0 then it is not active. See the Bridges section below for more
101 information on bridges.
102 $SYS/broker/heap/current size
104 The current size of the heap memory in use by mosquitto. Note that
105 this topic may be unavailable depending on compile time options.
106 $SYS/broker/heap/maximum size
108 The largest amount of heap memory used by mosquitto. Note that this
109 topic may be unavailable depending on compile time options.
110 $SYS/broker/load/connections/+
112 The moving average of the number of CONNECT packets received by the
113 broker over different time intervals. The final "+" of the
114 hierarchy can be 1min, 5min or 15min. The value returned represents
115 the number of connections received in 1 minute, averaged over 1, 5
116 or 15 minutes.
117 $SYS/broker/load/bytes/received/+
119 The moving average of the number of bytes received by the broker
120 over different time intervals. The final "+" of the hierarchy can
121 be 1min, 5min or 15min. The value returned represents the number of
122 bytes received in 1 minute, averaged over 1, 5 or 15 minutes.
123 $SYS/broker/load/bytes/sent/+
125 The moving average of the number of bytes sent by the broker over
126 different time intervals. The final "+" of the hierarchy can be
127 1min, 5min or 15min. The value returned represents the number of
128 bytes sent in 1 minute, averaged over 1, 5 or 15 minutes.
129 $SYS/broker/load/messages/received/+
131 The moving average of the number of all types of MQTT messages
132 received by the broker over different time intervals. The final "+"
133 of the hierarchy can be 1min, 5min or 15min. The value returned
134 represents the number of messages received in 1 minute, averaged
135 over 1, 5 or 15 minutes.
136 $SYS/broker/load/messages/sent/+
138 The moving average of the number of all types of MQTT messages sent
139 by the broker over different time intervals. The final "+" of the
140 hierarchy can be 1min, 5min or 15min. The value returned represents
141 the number of messages send in 1 minute, averaged over 1, 5 or 15
142 minutes.
143 $SYS/broker/load/publish/dropped/+
145 The moving average of the number of publish messages dropped by the
146 broker over different time intervals. This shows the rate at which
147 durable clients that are disconnected are losing messages. The
148 final "+" of the hierarchy can be 1min, 5min or 15min. The value
149 returned represents the number of messages dropped in 1 minute,
150 averaged over 1, 5 or 15 minutes.
151 $SYS/broker/load/publish/received/+
153 The moving average of the number of publish messages received by
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 publish messages received in 1 minute, averaged over
157 1, 5 or 15 minutes.
158 $SYS/broker/load/publish/sent/+
160 The moving average of the number of publish messages sent by the
161 broker over different time intervals. The final "+" of the
162 hierarchy can be 1min, 5min or 15min. The value returned represents
163 the number of publish messages sent in 1 minute, averaged over 1, 5
164 or 15 minutes.
165 $SYS/broker/load/sockets/+
167 The moving average of the number of socket connections opened to
168 the broker over different time intervals. The final "+" of the
169 hierarchy can be 1min, 5min or 15min. The value returned represents
170 the number of socket connections in 1 minute, averaged over 1, 5 or
171 15 minutes.
172 $SYS/broker/messages/inflight
174 The number of messages with QoS>0 that are awaiting
175 acknowledgments.
176 $SYS/broker/messages/received
178 The total number of messages of any type received since the broker
179 started.
180 $SYS/broker/messages/sent
182 The total number of messages of any type sent since the broker
183 started.
184 $SYS/broker/publish/messages/dropped
186 The total number of publish messages that have been dropped due to
187 inflight/queuing limits. See the max_inflight_messages and
188 max_queued_messages options in mosquitto.conf(5) for more
189 information.
190 $SYS/broker/publish/messages/received
192 The total number of PUBLISH messages received since the broker
193 started.
194 $SYS/broker/publish/messages/sent
196 The total number of PUBLISH messages sent since the broker started.
197 $SYS/broker/retained messages/count
199 The total number of retained messages active on the broker.
200 $SYS/broker/store/messages/count, $SYS/broker/messages/stored
202 (deprecated)
203 The number of messages currently held in the message store. This
204 includes retained messages and messages queued for durable clients.
205 $SYS/broker/store/messages/bytes
207 The number of bytes currently held by message payloads in the
208 message store. This includes retained messages and messages queued
209 for durable clients.
210 $SYS/broker/subscriptions/count
212 The total number of subscriptions active on the broker.
213 $SYS/broker/version
215 The version of the broker. Static.
216
218 In addition to allowing clients to subscribe to specific topics,
219 mosquitto also allows the use of two wildcards in subscriptions. + is
220 the wildcard used to match a single level of hierarchy. For example,
221 for a topic of "a/b/c/d", the following example subscriptions will
222 match:
223 • a/b/c/d
225 • +/b/c/d
227 • a/+/c/d
229 • a/+/+/d
231 • +/+/+/+
233 The following subscriptions will not match:
235 • a/b/c
237 • b/+/c/d
239 • +/+/+
241 The second wildcard is # and is used to match all subsequent levels of
243 hierarchy. With a topic of "a/b/c/d", the following example
244 subscriptions will match:
245 • a/b/c/d
247 • #
249 • a/#
251 • a/b/#
253 • a/b/c/#
255 • +/b/c/#
257 The $SYS hierarchy does not match a subscription of "#". If you want to
259 observe the entire $SYS hierarchy, subscribe to $SYS/#.
260 Note that the wildcards must be only ever used on their own, so a
262 subscription of "a/b+/c" is not valid use of a wildcard. The # wildcard
263 must only ever be used as the final character of a subscription.
264
266 Multiple brokers can be connected together with the bridging
267 functionality. This is useful where it is desirable to share
268 information between locations, but where not all of the information
269 needs to be shared. An example could be where a number of users are
270 running a broker to help record power usage and for a number of other
271 reasons. The power usage could be shared through bridging all of the
272 user brokers to a common broker, allowing the power usage of all users
273 to be collected and compared. The other information would remain local
274 to each broker.
275 For information on configuring bridges, see mosquitto.conf(5).
277
279 SIGHUP
280 Upon receiving the SIGHUP signal, mosquitto will attempt to reload
281 configuration file data, assuming that the -c argument was provided
282 when mosquitto was started. Not all configuration parameters can be
283 reloaded without restarting. See mosquitto.conf(5) for details.
284 If TLS certificates are in use, then mosquitto will also reload
286 certificate on receiving a SIGHUP.
287 SIGUSR1
289 Upon receiving the SIGUSR1 signal, mosquitto will write the
290 persistence database to disk. This signal is only acted upon if
291 persistence is enabled.
292 SIGUSR2
294 The SIGUSR2 signal causes mosquitto to print out the current
295 subscription tree, along with information about where retained
296 messages exist. This is intended as a testing feature only and may
297 be removed at any time.
298
300 /etc/mosquitto/mosquitto.conf
301 Configuration file. See mosquitto.conf(5).
302 /var/lib/mosquitto/mosquitto.db
304 Persistent message data storage location if persist enabled.
305 /etc/hosts.allow, /etc/hosts.deny
307 Host access control via tcp-wrappers as described in
308 hosts_access(5).
309
311 mosquitto bug information can be found at
312 https://github.com/eclipse/mosquitto/issues
313
315 mqtt(7), mosquitto-tls(7), mosquitto.conf(5), hosts_access(5),
316 mosquitto_ctrl(1), mosquitto_passwd(1), mosquitto_pub(1),
317 mosquitto_rr(1), mosquitto_sub(1), libmosquitto(3)
318
320 Thanks to Andy Stanford-Clark for being one of the people who came up
321 with MQTT in the first place. Thanks to Andy and Nicholas O'Leary for
322 providing clarifications of the protocol.
323 Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for
325 organising OggCamp, where Andy gave a talk that inspired mosquitto.
326
328 Roger Light <roger@atchoo.org>
329Mosquitto Project 04/03/2021 MOSQUITTO(8)