forked from mirrors/nixpkgs
148 lines
5.5 KiB
XML
148 lines
5.5 KiB
XML
|
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-mosquitto">
|
||
|
<title>Mosquitto</title>
|
||
|
<para>
|
||
|
Mosquitto is a MQTT broker often used for IoT or home automation
|
||
|
data transport.
|
||
|
</para>
|
||
|
<section xml:id="module-services-mosquitto-quickstart">
|
||
|
<title>Quickstart</title>
|
||
|
<para>
|
||
|
A minimal configuration for Mosquitto is
|
||
|
</para>
|
||
|
<programlisting language="bash">
|
||
|
services.mosquitto = {
|
||
|
enable = true;
|
||
|
listeners = [ {
|
||
|
acl = [ "pattern readwrite #" ];
|
||
|
omitPasswordAuth = true;
|
||
|
settings.allow_anonymous = true;
|
||
|
} ];
|
||
|
};
|
||
|
</programlisting>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
<para>
|
||
|
User authentication can be configured with the
|
||
|
<literal>users</literal> key of listeners. A config that gives
|
||
|
full read access to a user <literal>monitor</literal> and
|
||
|
restricted write access to a user <literal>service</literal> could
|
||
|
look like
|
||
|
</para>
|
||
|
<programlisting language="bash">
|
||
|
services.mosquitto = {
|
||
|
enable = true;
|
||
|
listeners = [ {
|
||
|
users = {
|
||
|
monitor = {
|
||
|
acl = [ "read #" ];
|
||
|
password = "monitor";
|
||
|
};
|
||
|
service = {
|
||
|
acl = [ "write service/#" ];
|
||
|
password = "service";
|
||
|
};
|
||
|
};
|
||
|
} ];
|
||
|
};
|
||
|
</programlisting>
|
||
|
<para>
|
||
|
TLS authentication is configured by setting TLS-related options of
|
||
|
the listener:
|
||
|
</para>
|
||
|
<programlisting language="bash">
|
||
|
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";
|
||
|
};
|
||
|
} ];
|
||
|
</programlisting>
|
||
|
</section>
|
||
|
<section xml:id="module-services-mosquitto-config">
|
||
|
<title>Configuration</title>
|
||
|
<para>
|
||
|
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).
|
||
|
</para>
|
||
|
<para>
|
||
|
Almost all options of Mosquitto are available for configuration at
|
||
|
their appropriate levels, some as NixOS options written in camel
|
||
|
case, the remainders under <literal>settings</literal> with their
|
||
|
exact names in the Mosquitto config file. The exceptions are
|
||
|
<literal>acl_file</literal> (which is always set according to the
|
||
|
<literal>acl</literal> attributes of a listener and its users) and
|
||
|
<literal>per_listener_settings</literal> (which is always set to
|
||
|
<literal>true</literal>).
|
||
|
</para>
|
||
|
<section xml:id="module-services-mosquitto-config-passwords">
|
||
|
<title>Password authentication</title>
|
||
|
<para>
|
||
|
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
|
||
|
<literal>omitPasswordAuth = true</literal> for a listener; in
|
||
|
this case it is necessary to either set
|
||
|
<literal>settings.allow_anonymous = true</literal> to allow all
|
||
|
logins, or to configure other authentication methods like TLS
|
||
|
client certificates with
|
||
|
<literal>settings.use_identity_as_username = true</literal>.
|
||
|
</para>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
</section>
|
||
|
<section xml:id="module-services-mosquitto-config-acl">
|
||
|
<title>ACL format</title>
|
||
|
<para>
|
||
|
Every listener has a Mosquitto <literal>acl_file</literal>
|
||
|
attached to it. This ACL is configured via two attributes of the
|
||
|
config:
|
||
|
</para>
|
||
|
<itemizedlist spacing="compact">
|
||
|
<listitem>
|
||
|
<para>
|
||
|
the <literal>acl</literal> attribute of the listener
|
||
|
configures pattern ACL entries and topic ACL entries for
|
||
|
anonymous users. Each entry must be prefixed with
|
||
|
<literal>pattern</literal> or <literal>topic</literal> to
|
||
|
distinguish between these two cases.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
the <literal>acl</literal> 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.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
The default ACL for a listener is empty, disallowing all
|
||
|
accesses from all clients. To configure a completely open ACL,
|
||
|
set <literal>acl = [ "pattern readwrite #" ]</literal>
|
||
|
in the listener.
|
||
|
</para>
|
||
|
</section>
|
||
|
</section>
|
||
|
</chapter>
|