1
'\" -*- coding: us-ascii -*-
3
.if \n(.g .ds T> \\F[\n[.fam]]
7
.if \n(.g .mso www.tmac
8
.TH mosquitto 8 "29 April 2011" "" ""
10
mosquitto \- an mqtt broker
16
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
18
[\fB-c\fR \fIconfig file\fR] [\fB-d\fR | \fB--daemon\fR] [\fB-p\fR \fIport number\fR]
23
\fBmosquitto\fR is a broker for the mqtt protocol version 3.1.
25
It is intended to be a drop in replacement for rsmb, but it's a little way off yet.
28
\*(T<\fB\-c\fR\*(T>, \*(T<\fB\-\-config\-file\fR\*(T>
29
Load configuration from a file. If not given, the default values as described in \fBmosquitto.conf\fR(5) are used.
31
\*(T<\fB\-d\fR\*(T>, \*(T<\fB\-\-daemon\fR\*(T>
32
Run \fBmosquitto\fR in the background as a daemon. All other behaviour remains the same.
34
\*(T<\fB\-p\fR\*(T>, \*(T<\fB\-\-port\fR\*(T>
35
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.
37
\fBmosquitto\fR implements all of the mqtt protocol version 3.1, but there are some significant limitations compared to rsmb.
40
There is only basic bridge support.
43
There are fewer configuration options.
46
There is less logging information.
49
The $SYS hierarchy is smaller.
52
It isn't as well tested or documented...
54
It should be noted that all of the above limitations should have "currently" included in them. They will all be fixed at some point.
56
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 \*(T<\fBsys_interval\fR\*(T> seconds. If \*(T<\fBsys_interval\fR\*(T> is 0, then updates are not sent.
58
\*(T<\fB$SYS/broker/bytes/received\fR\*(T>
59
The total number of bytes received since the broker started.
61
\*(T<\fB$SYS/broker/bytes/sent\fR\*(T>
62
The total number of bytes sent since the broker started.
64
\*(T<\fB$SYS/broker/changeset\fR\*(T>
65
The repository changeset (revision) associated with this build.
67
\*(T<\fB$SYS/broker/clients/total\fR\*(T>
68
The total number of clients currently either connected to the broker or disconnected but with clean session not set.
70
\*(T<\fB$SYS/broker/heap/current size\fR\*(T>
71
The current size of the heap memory in use by
72
mosquitto. Note that this topic may be unavailable
73
depending on compile time options.
75
\*(T<\fB$SYS/broker/messages/stored\fR\*(T>
76
The number of messages currently held in the message store.
78
\*(T<\fB$SYS/broker/messages/received\fR\*(T>
79
The total number of messages received since the broker started.
81
\*(T<\fB$SYS/broker/messages/sent\fR\*(T>
82
The total number of messages sent since the broker started.
84
\*(T<\fB$SYS/broker/timestamp\fR\*(T>
85
The timestamp at which this particular build of the broker was made. Static.
87
\*(T<\fB$SYS/broker/uptime\fR\*(T>
88
The amount of time in seconds the broker has been online.
90
\*(T<\fB$SYS/broker/version\fR\*(T>
91
The version of the broker. Static.
92
.SH "WILDCARD TOPIC SUBSCRIPTIONS"
93
In addition to allowing clients to subscribe to specific topics,
94
mosquitto also allows the use of two wildcards in subscriptions.
95
\*(T<\fB+\fR\*(T> is the wildcard used to match a single level of
96
hierarchy. For example, for a topic of "a/b/c/d", the following example
97
subscriptions will match:
114
The following subscriptions will not match:
125
The second wildcard is \*(T<\fB#\fR\*(T> and is used to match
126
all subsequent levels of hierarchy. With a topic of "a/b/c/d", the
127
following example subscriptions will match:
147
The $SYS hierarchy does not match a subscription of
148
"#". If you want to observe the entire $SYS hierarchy, subscribe to
151
Note that the wildcards must be only ever used on their own, so a
152
subscription of "a/b+/c" is not valid use of a wildcard. The
153
\*(T<\fB#\fR\*(T> wildcard must only ever be used as the final
154
character of a subscription.
156
Multiple brokers can be connected together with the bridging
157
functionality. This is useful where it is desirable to share
158
information between locations, but where not all of the information
159
needs to be shared. An example could be where a number of users are
160
running a broker to help record power usage and for a number of other
161
reasons. The power usage could be shared through bridging all of the
162
user brokers to a common broker, allowing the power usage of all
163
users to be collected and compared. The other information would remain
167
For information on configuring bridges, see
168
\fBmosquitto.conf\fR(5).
172
Upon receiving the SIGUSR1 signal, mosquitto will write the persistence database to disk. This signal is only acted upon if persistence is enabled.
175
\*(T<\fI/etc/mosquitto.conf\fR\*(T>
176
Configuration file. See \fBmosquitto.conf\fR(5).
178
\*(T<\fI/var/lib/mosquitto/mosquitto.db\fR\*(T>
179
Persistent message data storage location if persist enabled.
181
\*(T<\fI/etc/hosts.allow\fR\*(T>, \*(T<\fI/etc/hosts.deny\fR\*(T>
182
Host access control via tcp-wrappers as described in \fBhosts_access\fR(5).
184
\fBmosquitto\fR bug information can be found at http://launchpad.net/mosquitto.
186
\fBmosquitto.conf\fR(5)
187
\fBhosts_access\fR(5)
188
\fBmosquitto_pub\fR(1)
189
\fBmosquitto_sub\fR(1)
190
\fBlibmosquitto\fR(3)
192
Thanks to Andy Stanford-Clark for being one of the people who came up with MQTT in the first place and providing clarifications of the protocol.
194
Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for organising OggCamp, where Andy gave a talk that inspired mosquitto.
196
Roger Light <\*(T<roger@atchoo.org\*(T>>