UNPKG

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