Mosquitto
Mosquitto is a MQTT broker often used for IoT or home automation
data transport.
Quickstart
A minimal configuration for Mosquitto is
services.mosquitto = {
enable = true;
listeners = [ {
acl = [ "pattern readwrite #" ];
omitPasswordAuth = true;
settings.allow_anonymous = true;
} ];
};
This will start a broker on port 1883, listening on all interfaces
of the machine, allowing read/write access to all topics to any
user without password requirements.
User authentication can be configured with the
users key of listeners. A config that gives
full read access to a user monitor and
restricted write access to a user service could
look like
services.mosquitto = {
enable = true;
listeners = [ {
users = {
monitor = {
acl = [ "read #" ];
password = "monitor";
};
service = {
acl = [ "write service/#" ];
password = "service";
};
};
} ];
};
TLS authentication is configured by setting TLS-related options of
the listener:
services.mosquitto = {
enable = true;
listeners = [ {
port = 8883; # port change is not required, but helpful to avoid mistakes
# ...
settings = {
cafile = "/path/to/mqtt.ca.pem";
certfile = "/path/to/mqtt.pem";
keyfile = "/path/to/mqtt.key";
};
} ];
Configuration
The Mosquitto configuration has four distinct types of settings:
the global settings of the daemon, listeners, plugins, and
bridges. Bridges and listeners are part of the global
configuration, plugins are part of listeners. Users of the broker
are configured as parts of listeners rather than globally,
allowing configurations in which a given user is only allowed to
log in to the broker using specific listeners (eg to configure an
admin user with full access to all topics, but restricted to
localhost).
Almost all options of Mosquitto are available for configuration at
their appropriate levels, some as NixOS options written in camel
case, the remainders under settings with their
exact names in the Mosquitto config file. The exceptions are
acl_file (which is always set according to the
acl attributes of a listener and its users) and
per_listener_settings (which is always set to
true).
Password authentication
Mosquitto can be run in two modes, with a password file or
without. Each listener has its own password file, and different
listeners may use different password files. Password file
generation can be disabled by setting
omitPasswordAuth = true for a listener; in
this case it is necessary to either set
settings.allow_anonymous = true to allow all
logins, or to configure other authentication methods like TLS
client certificates with
settings.use_identity_as_username = true.
The default is to generate a password file for each listener
from the users configured to that listener. Users with no
configured password will not be added to the password file and
thus will not be able to use the broker.
ACL format
Every listener has a Mosquitto acl_file
attached to it. This ACL is configured via two attributes of the
config:
the acl attribute of the listener
configures pattern ACL entries and topic ACL entries for
anonymous users. Each entry must be prefixed with
pattern or topic to
distinguish between these two cases.
the acl attribute of every user
configures in the listener configured the ACL for that given
user. Only topic ACLs are supported by Mosquitto in this
setting, so no prefix is required or allowed.
The default ACL for a listener is empty, disallowing all
accesses from all clients. To configure a completely open ACL,
set acl = [ "pattern readwrite #" ]
in the listener.