-
Notifications
You must be signed in to change notification settings - Fork 2.3k
/
mosquitto.8.xml
569 lines (554 loc) · 21.8 KB
/
mosquitto.8.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
<refentry xml:id="mosquitto" xmlns:xlink="http:https://www.w3.org/1999/xlink">
<refmeta>
<refentrytitle>mosquitto</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
<refmiscinfo class="manual">System management commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>mosquitto</refname>
<refpurpose>an MQTT broker</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>mosquitto</command>
<arg>-c <replaceable>config file</replaceable></arg>
<group>
<arg choice='plain'>-d</arg>
<arg choice='plain'>--daemon</arg>
</group>
<arg>-p <replaceable>port number</replaceable></arg>
<arg>-v</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>mosquitto</command> is a broker for the MQTT protocol version 5.0/3.1.1/3.1.</para>
</refsect1>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-c</option></term>
<term><option>--config-file</option></term>
<listitem>
<para>
Load configuration from a file. If not given, then the broker will listen on port 1883 bound to the loopback interface,
and the default values as described in <citerefentry><refentrytitle>mosquitto.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
are used.
</para>
<important><para>See the <option>-p</option> option for a description of changes in behaviour from 1.6.x to 2.0.</para></important>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option></term>
<term><option>--daemon</option></term>
<listitem>
<para>Run <command>mosquitto</command> in the background as a daemon. All other behaviour remains the same.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option></term>
<term><option>--port</option></term>
<listitem>
<para>Listen on the port specified. May be specified up to 10 times to open multiple sockets listening on different ports.</para>
<important><para>In version 1.6.x and earlier, the listener defined by <option>-p</option> (or the default port of 1883) would be
bound to all interfaces and so be accessible from any network. It could also be used in combination with <option>-c</option>.</para>
<para>From version 2.0 onwards, the listeners defined with <option>-p</option> are bound to the loopback interface only, and so can
only be connected to from the local machine. If both <option>-p</option> is used and a listener is defined in a configuration
file, then the <option>-p</option> options are IGNORED.</para></important>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<term><option>--verbose</option></term>
<listitem>
<para>Use verbose logging. This is equivalent to setting
<option>log_type</option> to <option>all</option> in
the configuration file. This overrides and logging
options given in the configuration file.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Configuration</title>
<para>The broker can be configured using a configuration file as
described in
<citerefentry><refentrytitle>mosquitto.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and this is the main point of information for mosquitto.
The files required for SSL/TLS support are described in
<citerefentry><refentrytitle>mosquitto-tls</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1>
<title>Broker Status</title>
<para>Clients can find information about the broker by subscribing to
topics in the $SYS hierarchy as follows. Topics marked as static are
only sent once per client on subscription. All other topics are updated
every <option>sys_interval</option> seconds. If
<option>sys_interval</option> is 0, then updates are not sent.</para>
<para>Note that if you are using a command line client to interact with the
$SYS topics and your shell interprets $ as an environment variable,
you need to place the topic in single quotes '$SYS/...' or to
escape the dollar symbol: \$SYS/... otherwise the $SYS will be
treated as an environment variable.</para>
<variablelist>
<varlistentry>
<term><option>$SYS/broker/bytes/received</option></term>
<listitem>
<para>The total number of bytes received since the broker
started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/bytes/sent</option></term>
<listitem>
<para>The total number of bytes sent since the broker
started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/clients/connected</option></term>
<term><option>$SYS/broker/clients/active</option> (deprecated)</term>
<listitem>
<para>The number of currently connected clients.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/clients/expired</option></term>
<listitem>
<para>The number of disconnected persistent clients that
have been expired and removed through the
persistent_client_expiration option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/clients/disconnected</option></term>
<term><option>$SYS/broker/clients/inactive</option> (deprecated)</term>
<listitem>
<para>The total number of persistent clients (with clean
session disabled) that are registered at the broker but are
currently disconnected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/clients/maximum</option></term>
<listitem>
<para>The maximum number of clients that have been
connected to the broker at the same time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/clients/total</option></term>
<listitem>
<para>The total number of active and inactive clients
currently connected and registered on the
broker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/connection/#</option></term>
<listitem>
<para>When bridges are configured to/from the broker,
common practice is to provide a status topic that
indicates the state of the connection. This is provided
within $SYS/broker/connection/ by default. If the value
of the topic is 1 the connection is active, if 0 then
it is not active. See the Bridges section below for
more information on bridges.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/heap/current size</option></term>
<listitem>
<para>The current size of the heap memory in use by
mosquitto. Note that this topic may be unavailable
depending on compile time options.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/heap/maximum size</option></term>
<listitem>
<para>The largest amount of heap memory used by
mosquitto. Note that this topic may be unavailable
depending on compile time options.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/connections/+</option></term>
<listitem>
<para>The moving average of the number of CONNECT packets
received by the broker over different time intervals.
The final "+" of the hierarchy can be 1min, 5min or
15min. The value returned represents the number of
connections received in 1 minute, averaged over 1, 5 or
15 minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/bytes/received/+</option></term>
<listitem>
<para>The moving average of the number of bytes received by
the broker over different time intervals. The final "+"
of the hierarchy can be 1min, 5min or 15min. The value
returned represents the number of bytes received in 1
minute, averaged over 1, 5 or 15 minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/bytes/sent/+</option></term>
<listitem>
<para>The moving average of the number of bytes sent by the
broker over different time intervals. The final "+" of
the hierarchy can be 1min, 5min or 15min. The value
returned represents the number of bytes sent in 1
minute, averaged over 1, 5 or 15 minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/messages/received/+</option></term>
<listitem>
<para>The moving average of the number of all types of MQTT
messages received by the broker over different time
intervals. The final "+" of the hierarchy can be 1min,
5min or 15min. The value returned represents the number
of messages received in 1 minute, averaged over 1, 5 or
15 minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/messages/sent/+</option></term>
<listitem>
<para>The moving average of the number of all types of MQTT
messages sent by the broker over different time
intervals. The final "+" of the hierarchy can be 1min,
5min or 15min. The value returned represents the number
of messages send in 1 minute, averaged over 1, 5 or 15
minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/publish/dropped/+</option></term>
<listitem>
<para>The moving average of the number of publish messages
dropped by the broker over different time intervals.
This shows the rate at which durable clients that are
disconnected are losing messages. The final "+" of the
hierarchy can be 1min, 5min or 15min. The value
returned represents the number of messages dropped in 1
minute, averaged over 1, 5 or 15 minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/publish/received/+</option></term>
<listitem>
<para>The moving average of the number of publish messages
received by the broker over different time intervals.
The final "+" of the hierarchy can be 1min, 5min or
15min. The value returned represents the number of
publish messages received in 1 minute, averaged over 1,
5 or 15 minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/publish/sent/+</option></term>
<listitem>
<para>The moving average of the number of publish messages
sent by the broker over different time intervals. The
final "+" of the hierarchy can be 1min, 5min or 15min.
The value returned represents the number of publish
messages sent in 1 minute, averaged over 1, 5 or 15
minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/load/sockets/+</option></term>
<listitem>
<para>The moving average of the number of socket
connections opened to the broker over different time
intervals. The final "+" of the hierarchy can be 1min,
5min or 15min. The value returned represents the number
of socket connections in 1 minute, averaged over 1, 5
or 15 minutes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/messages/inflight</option></term>
<listitem>
<para>The number of messages with QoS>0 that are awaiting
acknowledgments.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/messages/received</option></term>
<listitem>
<para>The total number of messages of any type received since the broker started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/messages/sent</option></term>
<listitem>
<para>The total number of messages of any type sent since the broker started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/publish/messages/dropped</option></term>
<listitem>
<para>The total number of publish messages that have been
dropped due to inflight/queuing limits. See the
max_inflight_messages and max_queued_messages options
in
<citerefentry><refentrytitle>mosquitto.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/publish/messages/received</option></term>
<listitem>
<para>The total number of PUBLISH messages received since the broker started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/publish/messages/sent</option></term>
<listitem>
<para>The total number of PUBLISH messages sent since the broker started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/retained messages/count</option></term>
<listitem>
<para>The total number of retained messages active on the broker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/store/messages/count</option></term>
<term><option>$SYS/broker/messages/stored</option> (deprecated)</term>
<listitem>
<para>The number of messages currently held in the message
store. This includes retained messages and messages
queued for durable clients.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/store/messages/bytes</option></term>
<listitem>
<para>The number of bytes currently held by message payloads
in the message store. This includes retained messages
and messages queued for durable clients.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/subscriptions/count</option></term>
<listitem>
<para>The total number of subscriptions active on the broker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$SYS/broker/version</option></term>
<listitem>
<para>The version of the broker. Static.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Wildcard Topic Subscriptions</title>
<para>In addition to allowing clients to subscribe to specific topics,
mosquitto also allows the use of two wildcards in subscriptions.
<option>+</option> is the wildcard used to match a single level of
hierarchy. For example, for a topic of "a/b/c/d", the following example
subscriptions will match:</para>
<itemizedlist mark="circle">
<listitem><para>a/b/c/d</para></listitem>
<listitem><para>+/b/c/d</para></listitem>
<listitem><para>a/+/c/d</para></listitem>
<listitem><para>a/+/+/d</para></listitem>
<listitem><para>+/+/+/+</para></listitem>
</itemizedlist>
<para>The following subscriptions will not match:</para>
<itemizedlist mark="circle">
<listitem><para>a/b/c</para></listitem>
<listitem><para>b/+/c/d</para></listitem>
<listitem><para>+/+/+</para></listitem>
</itemizedlist>
<para>The second wildcard is <option>#</option> and is used to match
all subsequent levels of hierarchy. With a topic of "a/b/c/d", the
following example subscriptions will match:</para>
<itemizedlist mark="circle">
<listitem><para>a/b/c/d</para></listitem>
<listitem><para>#</para></listitem>
<listitem><para>a/#</para></listitem>
<listitem><para>a/b/#</para></listitem>
<listitem><para>a/b/c/#</para></listitem>
<listitem><para>+/b/c/#</para></listitem>
</itemizedlist>
<para>The $SYS hierarchy does not match a subscription of
"#". If you want to observe the entire $SYS hierarchy, subscribe to
$SYS/#.</para>
<para>Note that the wildcards must be only ever used on their own, so a
subscription of "a/b+/c" is not valid use of a wildcard. The
<option>#</option> wildcard must only ever be used as the final
character of a subscription.</para>
</refsect1>
<refsect1>
<title>Bridges</title>
<para>Multiple brokers can be connected together with the bridging
functionality. This is useful where it is desirable to share
information between locations, but where not all of the information
needs to be shared. An example could be where a number of users are
running a broker to help record power usage and for a number of other
reasons. The power usage could be shared through bridging all of the
user brokers to a common broker, allowing the power usage of all
users to be collected and compared. The other information would remain
local to each
broker.</para>
<para>For information on configuring bridges, see
<citerefentry><refentrytitle>mosquitto.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title>Signals</title>
<variablelist>
<varlistentry>
<term>SIGHUP</term>
<listitem>
<para>Upon receiving the SIGHUP signal, mosquitto will
attempt to reload configuration file data, assuming that
the <option>-c</option> argument was provided when
mosquitto was started. Not all configuration parameters can
be reloaded without restarting. See
<citerefentry><refentrytitle>mosquitto.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details.</para>
<para>If TLS certificates are in use, then mosquitto will
also reload certificate on receiving a SIGHUP.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SIGUSR1</term>
<listitem>
<para>Upon receiving the SIGUSR1 signal, mosquitto will
write the persistence database to disk. This signal is only
acted upon if persistence is enabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SIGUSR2</term>
<listitem>
<para>The SIGUSR2 signal causes mosquitto to print out the
current subscription tree, along with information about
where retained messages exist. This is intended as a
testing feature only and may be removed at any time.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Files</title>
<variablelist>
<varlistentry>
<term><filename>/etc/mosquitto/mosquitto.conf</filename></term>
<listitem>
<para>Configuration file. See <citerefentry><refentrytitle>mosquitto.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/var/lib/mosquitto/mosquitto.db</filename></term>
<listitem>
<para>Persistent message data storage location if persist enabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/etc/hosts.allow</filename></term>
<term><filename>/etc/hosts.deny</filename></term>
<listitem>
<para>Host access control via tcp-wrappers as described in <citerefentry><refentrytitle>hosts_access</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Bugs</title>
<para><command>mosquitto</command> bug information can be found at
<ulink url="https://github.com/eclipse/mosquitto/issues"/></para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member>
<citerefentry>
<refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
<manvolnum>7</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto-tls-7.html">mosquitto-tls</link></refentrytitle>
<manvolnum>7</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="https://linux.die.net/man/5/hosts_access">hosts_access</link></refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto_ctrl-1.html">mosquitto_ctrl</link></refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto_passwd-1.html">mosquitto_passwd</link></refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto_pub-1.html">mosquitto_pub</link></refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto_rr-1.html">mosquitto_rr</link></refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="mosquitto_sub-1.html">mosquitto_sub</link></refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</member>
<member>
<citerefentry>
<refentrytitle><link xlink:href="libmosquitto-3.html">libmosquitto</link></refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>
</member>
</simplelist>
</refsect1>
<refsect1>
<title>Thanks</title>
<para>Thanks to Andy Stanford-Clark for being one of the people who
came up with MQTT in the first place. Thanks to Andy and Nicholas
O'Leary for providing clarifications of the protocol.</para>
<para>Thanks also to everybody at the Ubuntu UK Podcast and Linux
Outlaws for organising OggCamp, where Andy gave a talk that
inspired mosquitto.</para>
</refsect1>
<refsect1>
<title>Author</title>
<para>Roger Light <email>[email protected]</email></para>
</refsect1>
</refentry>