mirror of
https://github.com/SebastianWendel/nixpkgs.git
synced 2024-09-20 12:29:02 +02:00
nixos/mosquitto: add module documentation
This commit is contained in:
parent
d09952fea8
commit
0343045a92
102
nixos/modules/services/networking/mosquitto.md
Normal file
102
nixos/modules/services/networking/mosquitto.md
Normal file
|
@ -0,0 +1,102 @@
|
||||||
|
# Mosquitto {#module-services-mosquitto}
|
||||||
|
|
||||||
|
Mosquitto is a MQTT broker often used for IoT or home automation data transport.
|
||||||
|
|
||||||
|
## Quickstart {#module-services-mosquitto-quickstart}
|
||||||
|
|
||||||
|
A minimal configuration for Mosquitto is
|
||||||
|
|
||||||
|
```nix
|
||||||
|
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
|
||||||
|
|
||||||
|
```nix
|
||||||
|
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:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
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 {#module-services-mosquitto-config}
|
||||||
|
|
||||||
|
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 {#module-services-mosquitto-config-passwords}
|
||||||
|
|
||||||
|
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 {#module-services-mosquitto-config-acl}
|
||||||
|
|
||||||
|
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.
|
|
@ -257,7 +257,7 @@ let
|
||||||
|
|
||||||
users = mkOption {
|
users = mkOption {
|
||||||
type = attrsOf userOptions;
|
type = attrsOf userOptions;
|
||||||
example = { john = { password = "123456"; acl = [ "topic readwrite john/#" ]; }; };
|
example = { john = { password = "123456"; acl = [ "readwrite john/#" ]; }; };
|
||||||
description = ''
|
description = ''
|
||||||
A set of users and their passwords and ACLs.
|
A set of users and their passwords and ACLs.
|
||||||
'';
|
'';
|
||||||
|
@ -278,6 +278,7 @@ let
|
||||||
description = ''
|
description = ''
|
||||||
Additional ACL items to prepend to the generated ACL file.
|
Additional ACL items to prepend to the generated ACL file.
|
||||||
'';
|
'';
|
||||||
|
example = [ "pattern read #" "topic readwrite anon/report/#" ];
|
||||||
default = [];
|
default = [];
|
||||||
};
|
};
|
||||||
|
|
||||||
|
@ -654,5 +655,10 @@ in
|
||||||
|
|
||||||
};
|
};
|
||||||
|
|
||||||
meta.maintainers = with lib.maintainers; [ pennae ];
|
meta = {
|
||||||
|
maintainers = with lib.maintainers; [ pennae ];
|
||||||
|
# Don't edit the docbook xml directly, edit the md and generate it:
|
||||||
|
# `pandoc mosquitto.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > mosquitto.xml`
|
||||||
|
doc = ./mosquitto.xml;
|
||||||
|
};
|
||||||
}
|
}
|
||||||
|
|
147
nixos/modules/services/networking/mosquitto.xml
Normal file
147
nixos/modules/services/networking/mosquitto.xml
Normal file
|
@ -0,0 +1,147 @@
|
||||||
|
<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>
|
Loading…
Reference in a new issue