|MOSQUITTO(8)||System management commands||MOSQUITTO(8)|
mosquitto - an MQTT broker
mosquitto [-c config file] [-d | --daemon] [-p port number] [-v]
mosquitto is a broker for the MQTT protocol version 5.0/3.1.1/3.1.
See the -p option for a description of changes in behaviour from 1.6.x to 2.0.
In version 1.6.x and earlier, the listener defined by -p (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 -c.
From version 2.0 onwards, the listeners defined with -p are bound to the loopback interface only, and so can only be connected to from the local machine. If both -p is used and a listener is defined in a configuration file, then the -p options are IGNORED.
The broker can be configured using a configuration file as described in mosquitto.conf(5) and this is the main point of information for mosquitto. The files required for SSL/TLS support are described in mosquitto-tls(7).
Mosquitto supports MQTT v5.0, v3.1.1, and v3.1.
Mosquitto provides full MQTT v5.0 support, but some features are not used directly. The following sections describe the new features and explain where Mosquitto does not make use of a feature.
Request / response
MQTT v5.0 allows properties to be added to packets to control certain behaviour. Unless noted, Mosquitto support the properties listed below.
Last will and testament
PUBACK / PUBREC / PUBREL / PUBCOMP / SUBACK / SUBSCRIBE / SUBACK
Mosquitto provides full MQTT v3.1.1 support.
Mosquitto provides full MQTT v3.1 support.
MQTT v3 is an obsolete version of the protocol that does not support username/password authentication and used the clean start flag in the CONNECT packet which applied only to the start of a session. An MQTT v3 client will be able to successfully connect to a Mosquitto instance that does not require authentication.
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 sys_interval seconds. If sys_interval is 0, then updates are not sent.
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.
$SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated)
$SYS/broker/clients/disconnected, $SYS/broker/clients/inactive (deprecated)
$SYS/broker/store/messages/count, $SYS/broker/messages/stored (deprecated)
WILDCARD TOPIC SUBSCRIPTIONS¶
In addition to allowing clients to subscribe to specific topics, mosquitto also allows the use of two wildcards in subscriptions. + 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:
The following subscriptions will not match:
The second wildcard is # and is used to match all subsequent levels of hierarchy. With a topic of "a/b/c/d", the following example subscriptions will match:
The $SYS hierarchy does not match a subscription of "#". If you want to observe the entire $SYS hierarchy, subscribe to $SYS/#.
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 # wildcard must only ever be used as the final character of a subscription.
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.
For information on configuring bridges, see mosquitto.conf(5).
If TLS certificates are in use, then mosquitto will also reload certificate on receiving a SIGHUP.
mosquitto bug information can be found at https://github.com/eclipse/mosquitto/issues
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.
Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for organising OggCamp, where Andy gave a talk that inspired mosquitto.
Roger Light <email@example.com>