'\" -*- coding: us-ascii -*- .if \n(.g .ds T< \\FC .if \n(.g .ds T> \\F[\n[.fam]] .de URL \\$2 \(la\\$1\(ra\\$3 .. .if \n(.g .mso www.tmac .TH mosquitto 8 "5 February 2012" "" "" .SH NAME mosquitto \- an mqtt broker .SH SYNOPSIS 'nh .fi .ad l \fBmosquitto\fR \kx .if (\nx>(\n(.l/2)) .nr x (\n(.l/5) 'in \n(.iu+\nxu [\fB-c\fR \fIconfig file\fR] [\fB-d\fR | \fB--daemon\fR] [\fB-p\fR \fIport number\fR] 'in \n(.iu-\nxu .ad b 'hy .SH DESCRIPTION \fBmosquitto\fR is a broker for the mqtt protocol version 3.1. .SH OPTIONS .TP \*(T<\fB\-c\fR\*(T>, \*(T<\fB\-\-config\-file\fR\*(T> Load configuration from a file. If not given, the default values as described in \fBmosquitto.conf\fR(5) are used. .TP \*(T<\fB\-d\fR\*(T>, \*(T<\fB\-\-daemon\fR\*(T> Run \fBmosquitto\fR in the background as a daemon. All other behaviour remains the same. .TP \*(T<\fB\-p\fR\*(T>, \*(T<\fB\-\-port\fR\*(T> 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. .SH LIMITATIONS \fBmosquitto\fR implements all of the mqtt protocol version 3.1, but there are some limitations compared to rsmb. .TP 0.2i \(bu There are fewer configuration options. .TP 0.2i \(bu There is less logging information. .TP 0.2i \(bu It isn't as well tested or documented... .PP It should be noted that all of the above limitations should have "currently" included in them. They will all be fixed at some point. .SH "BROKER STATUS" 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. .TP \*(T<\fB$SYS/broker/bytes/per second/received\fR\*(T> The average number of bytes received per second since the broker started. .TP \*(T<\fB$SYS/broker/bytes/per second/sent\fR\*(T> The average number of bytes sent per second since the broker started. .TP \*(T<\fB$SYS/broker/bytes/received\fR\*(T> The total number of bytes received since the broker started. .TP \*(T<\fB$SYS/broker/bytes/sent\fR\*(T> The total number of bytes sent since the broker started. .TP \*(T<\fB$SYS/broker/changeset\fR\*(T> The repository changeset (revision) associated with this build. Static. .TP \*(T<\fB$SYS/broker/clients/active\fR\*(T> The number of currently connected clients .TP \*(T<\fB$SYS/broker/clients/inactive\fR\*(T> The total number of persistent clients (with clean session disabled) that are registered at the broker but are currently disconnected. .TP \*(T<\fB$SYS/broker/clients/maximum\fR\*(T> The maximum number of active clients that have been connected to the broker. This is only calculated when the $SYS topic tree is updated, so short lived client connections may not be counted. .TP \*(T<\fB$SYS/broker/clients/total\fR\*(T> The total number of active clients currently connected to the broker. .TP \*(T<\fB$SYS/broker/heap/current size\fR\*(T> The current size of the heap memory in use by mosquitto. Note that this topic may be unavailable depending on compile time options. .TP \*(T<\fB$SYS/broker/heap/maximum size\fR\*(T> The largest amount of heap memory used by mosquitto. Note that this topic may be unavailable depending on compile time options. .TP \*(T<\fB$SYS/broker/messages/inflight\fR\*(T> The number of messages with QoS>0 that are awaiting acknowledgments. .TP \*(T<\fB$SYS/broker/messages/per second/received\fR\*(T> The average number of messages received per second since the broker started. .TP \*(T<\fB$SYS/broker/messages/per second/sent\fR\*(T> The average number of messages sent per second since the broker started. .TP \*(T<\fB$SYS/broker/messages/received\fR\*(T> The total number of messages received since the broker started. .TP \*(T<\fB$SYS/broker/messages/sent\fR\*(T> The total number of messages sent since the broker started. .TP \*(T<\fB$SYS/broker/messages/stored\fR\*(T> The number of messages currently held in the message store. .TP \*(T<\fB$SYS/broker/timestamp\fR\*(T> The timestamp at which this particular build of the broker was made. Static. .TP \*(T<\fB$SYS/broker/uptime\fR\*(T> The amount of time in seconds the broker has been online. .TP \*(T<\fB$SYS/broker/version\fR\*(T> The version of the broker. Static. .SH "WILDCARD TOPIC SUBSCRIPTIONS" In addition to allowing clients to subscribe to specific topics, mosquitto also allows the use of two wildcards in subscriptions. \*(T<\fB+\fR\*(T> 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: .TP 0.2i \(bu a/b/c/d .TP 0.2i \(bu +/b/c/d .TP 0.2i \(bu a/+/c/d .TP 0.2i \(bu a/+/+/d .TP 0.2i \(bu +/+/+/+ .PP The following subscriptions will not match: .TP 0.2i \(bu a/b/c .TP 0.2i \(bu b/+/c/d .TP 0.2i \(bu +/+/+ .PP The second wildcard is \*(T<\fB#\fR\*(T> and is used to match all subsequent levels of hierarchy. With a topic of "a/b/c/d", the following example subscriptions will match: .TP 0.2i \(bu a/b/c/d .TP 0.2i \(bu # .TP 0.2i \(bu a/# .TP 0.2i \(bu a/b/# .TP 0.2i \(bu a/b/c/# .TP 0.2i \(bu +/b/c/# .PP The $SYS hierarchy does not match a subscription of "#". If you want to observe the entire $SYS hierarchy, subscribe to $SYS/#. .PP 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 \*(T<\fB#\fR\*(T> wildcard must only ever be used as the final character of a subscription. .SH BRIDGES 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. .PP For information on configuring bridges, see \fBmosquitto.conf\fR(5). .SH SIGNALS .TP SIGHUP Upon receiving the SIGHUP signal, mosquitto will attempt to reload configuration file data, assuming that the \*(T<\fB\-c\fR\*(T> argument was provided when mosquitto was started. Not all configuration parameters can be reloaded without restarting. See \fBmosquitto.conf\fR(5) for details. .TP SIGUSR1 Upon receiving the SIGUSR1 signal, mosquitto will write the persistence database to disk. This signal is only acted upon if persistence is enabled. .TP SIGHUP Upon receiving the SIGHUP signal, mosquitto will attempt to reload its configuration. Not all configuration parameters can be reloaded without a restart. See \fBmosquitto.conf\fR(5) for details. .TP SIGUSR2 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. .SH FILES .TP \*(T<\fI/etc/mosquitto/mosquitto.conf\fR\*(T> Configuration file. See \fBmosquitto.conf\fR(5). .TP \*(T<\fI/var/lib/mosquitto/mosquitto.db\fR\*(T> Persistent message data storage location if persist enabled. .TP \*(T<\fI/etc/hosts.allow\fR\*(T>, \*(T<\fI/etc/hosts.deny\fR\*(T> Host access control via tcp-wrappers as described in \fBhosts_access\fR(5). .SH BUGS \fBmosquitto\fR bug information can be found at http://launchpad.net/mosquitto .SH "SEE ALSO" \fBmqtt\fR(7) \fBmosquitto.conf\fR(5) \fBhosts_access\fR(5) \fBmosquitto_pub\fR(1) \fBmosquitto_sub\fR(1) \fBlibmosquitto\fR(3) .SH THANKS 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. .PP Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for organising OggCamp, where Andy gave a talk that inspired mosquitto. .SH AUTHOR Roger Light <\*(T>