pyrox.dev
lol
nixos/mosquitto: add module documentation
+257
-2
+102
nixos/modules/services/networking/mosquitto.md
+102
nixos/modules/services/networking/mosquitto.md
···
1
+
# Mosquitto {#module-services-mosquitto}
2
+
3
+
Mosquitto is a MQTT broker often used for IoT or home automation data transport.
4
+
5
+
## Quickstart {#module-services-mosquitto-quickstart}
6
+
7
+
A minimal configuration for Mosquitto is
8
+
9
+
```nix
10
+
services.mosquitto = {
11
+
enable = true;
12
+
listeners = [ {
13
+
acl = [ "pattern readwrite #" ];
14
+
omitPasswordAuth = true;
15
+
settings.allow_anonymous = true;
16
+
} ];
17
+
};
18
+
```
19
+
20
+
This will start a broker on port 1883, listening on all interfaces of the machine, allowing
21
+
read/write access to all topics to any user without password requirements.
22
+
23
+
User authentication can be configured with the `users` key of listeners. A config that gives
24
+
full read access to a user `monitor` and restricted write access to a user `service` could look
25
+
like
26
+
27
+
```nix
28
+
services.mosquitto = {
29
+
enable = true;
30
+
listeners = [ {
31
+
users = {
32
+
monitor = {
33
+
acl = [ "read #" ];
34
+
password = "monitor";
35
+
};
36
+
service = {
37
+
acl = [ "write service/#" ];
38
+
password = "service";
39
+
};
40
+
};
41
+
} ];
42
+
};
43
+
```
44
+
45
+
TLS authentication is configured by setting TLS-related options of the listener:
46
+
47
+
```nix
48
+
services.mosquitto = {
49
+
enable = true;
50
+
listeners = [ {
51
+
port = 8883; # port change is not required, but helpful to avoid mistakes
52
+
# ...
53
+
settings = {
54
+
cafile = "/path/to/mqtt.ca.pem";
55
+
certfile = "/path/to/mqtt.pem";
56
+
keyfile = "/path/to/mqtt.key";
57
+
};
58
+
} ];
59
+
```
60
+
61
+
## Configuration {#module-services-mosquitto-config}
62
+
63
+
The Mosquitto configuration has four distinct types of settings:
64
+
the global settings of the daemon, listeners, plugins, and bridges.
65
+
Bridges and listeners are part of the global configuration, plugins are part of listeners.
66
+
Users of the broker are configured as parts of listeners rather than globally, allowing
67
+
configurations in which a given user is only allowed to log in to the broker using specific
68
+
listeners (eg to configure an admin user with full access to all topics, but restricted to
69
+
localhost).
70
+
71
+
Almost all options of Mosquitto are available for configuration at their appropriate levels, some
72
+
as NixOS options written in camel case, the remainders under `settings` with their exact names in
73
+
the Mosquitto config file. The exceptions are `acl_file` (which is always set according to the
74
+
`acl` attributes of a listener and its users) and `per_listener_settings` (which is always set to
75
+
`true`).
76
+
77
+
### Password authentication {#module-services-mosquitto-config-passwords}
78
+
79
+
Mosquitto can be run in two modes, with a password file or without. Each listener has its own
80
+
password file, and different listeners may use different password files. Password file generation
81
+
can be disabled by setting `omitPasswordAuth = true` for a listener; in this case it is necessary
82
+
to either set `settings.allow_anonymous = true` to allow all logins, or to configure other
83
+
authentication methods like TLS client certificates with `settings.use_identity_as_username = true`.
84
+
85
+
The default is to generate a password file for each listener from the users configured to that
86
+
listener. Users with no configured password will not be added to the password file and thus
87
+
will not be able to use the broker.
88
+
89
+
### ACL format {#module-services-mosquitto-config-acl}
90
+
91
+
Every listener has a Mosquitto `acl_file` attached to it. This ACL is configured via two
92
+
attributes of the config:
93
+
94
+
* the `acl` attribute of the listener configures pattern ACL entries and topic ACL entries
95
+
for anonymous users. Each entry must be prefixed with `pattern` or `topic` to distinguish
96
+
between these two cases.
97
+
* the `acl` attribute of every user configures in the listener configured the ACL for that
98
+
given user. Only topic ACLs are supported by Mosquitto in this setting, so no prefix is
99
+
required or allowed.
100
+
101
+
The default ACL for a listener is empty, disallowing all accesses from all clients. To configure
102
+
a completely open ACL, set `acl = [ "pattern readwrite #" ]` in the listener.
+8
-2
nixos/modules/services/networking/mosquitto.nix
+8
-2
nixos/modules/services/networking/mosquitto.nix
···
257
257
258
258
users = mkOption {
259
259
type = attrsOf userOptions;
260
-
example = { john = { password = "123456"; acl = [ "topic readwrite john/#" ]; }; };
260
+
example = { john = { password = "123456"; acl = [ "readwrite john/#" ]; }; };
261
261
description = ''
262
262
A set of users and their passwords and ACLs.
263
263
'';
···
278
278
description = ''
279
279
Additional ACL items to prepend to the generated ACL file.
280
280
'';
281
+
example = [ "pattern read #" "topic readwrite anon/report/#" ];
281
282
default = [];
282
283
};
283
284
···
654
655
655
656
};
656
657
657
-
meta.maintainers = with lib.maintainers; [ pennae ];
658
+
meta = {
659
+
maintainers = with lib.maintainers; [ pennae ];
660
+
# Don't edit the docbook xml directly, edit the md and generate it:
661
+
# `pandoc mosquitto.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > mosquitto.xml`
662
+
doc = ./mosquitto.xml;
663
+
};
658
664
}
+147
nixos/modules/services/networking/mosquitto.xml
+147
nixos/modules/services/networking/mosquitto.xml
···
1
+
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-mosquitto">
2
+
<title>Mosquitto</title>
3
+
<para>
4
+
Mosquitto is a MQTT broker often used for IoT or home automation
5
+
data transport.
6
+
</para>
7
+
<section xml:id="module-services-mosquitto-quickstart">
8
+
<title>Quickstart</title>
9
+
<para>
10
+
A minimal configuration for Mosquitto is
11
+
</para>
12
+
<programlisting language="bash">
13
+
services.mosquitto = {
14
+
enable = true;
15
+
listeners = [ {
16
+
acl = [ "pattern readwrite #" ];
17
+
omitPasswordAuth = true;
18
+
settings.allow_anonymous = true;
19
+
} ];
20
+
};
21
+
</programlisting>
22
+
<para>
23
+
This will start a broker on port 1883, listening on all interfaces
24
+
of the machine, allowing read/write access to all topics to any
25
+
user without password requirements.
26
+
</para>
27
+
<para>
28
+
User authentication can be configured with the
29
+
<literal>users</literal> key of listeners. A config that gives
30
+
full read access to a user <literal>monitor</literal> and
31
+
restricted write access to a user <literal>service</literal> could
32
+
look like
33
+
</para>
34
+
<programlisting language="bash">
35
+
services.mosquitto = {
36
+
enable = true;
37
+
listeners = [ {
38
+
users = {
39
+
monitor = {
40
+
acl = [ "read #" ];
41
+
password = "monitor";
42
+
};
43
+
service = {
44
+
acl = [ "write service/#" ];
45
+
password = "service";
46
+
};
47
+
};
48
+
} ];
49
+
};
50
+
</programlisting>
51
+
<para>
52
+
TLS authentication is configured by setting TLS-related options of
53
+
the listener:
54
+
</para>
55
+
<programlisting language="bash">
56
+
services.mosquitto = {
57
+
enable = true;
58
+
listeners = [ {
59
+
port = 8883; # port change is not required, but helpful to avoid mistakes
60
+
# ...
61
+
settings = {
62
+
cafile = "/path/to/mqtt.ca.pem";
63
+
certfile = "/path/to/mqtt.pem";
64
+
keyfile = "/path/to/mqtt.key";
65
+
};
66
+
} ];
67
+
</programlisting>
68
+
</section>
69
+
<section xml:id="module-services-mosquitto-config">
70
+
<title>Configuration</title>
71
+
<para>
72
+
The Mosquitto configuration has four distinct types of settings:
73
+
the global settings of the daemon, listeners, plugins, and
74
+
bridges. Bridges and listeners are part of the global
75
+
configuration, plugins are part of listeners. Users of the broker
76
+
are configured as parts of listeners rather than globally,
77
+
allowing configurations in which a given user is only allowed to
78
+
log in to the broker using specific listeners (eg to configure an
79
+
admin user with full access to all topics, but restricted to
80
+
localhost).
81
+
</para>
82
+
<para>
83
+
Almost all options of Mosquitto are available for configuration at
84
+
their appropriate levels, some as NixOS options written in camel
85
+
case, the remainders under <literal>settings</literal> with their
86
+
exact names in the Mosquitto config file. The exceptions are
87
+
<literal>acl_file</literal> (which is always set according to the
88
+
<literal>acl</literal> attributes of a listener and its users) and
89
+
<literal>per_listener_settings</literal> (which is always set to
90
+
<literal>true</literal>).
91
+
</para>
92
+
<section xml:id="module-services-mosquitto-config-passwords">
93
+
<title>Password authentication</title>
94
+
<para>
95
+
Mosquitto can be run in two modes, with a password file or
96
+
without. Each listener has its own password file, and different
97
+
listeners may use different password files. Password file
98
+
generation can be disabled by setting
99
+
<literal>omitPasswordAuth = true</literal> for a listener; in
100
+
this case it is necessary to either set
101
+
<literal>settings.allow_anonymous = true</literal> to allow all
102
+
logins, or to configure other authentication methods like TLS
103
+
client certificates with
104
+
<literal>settings.use_identity_as_username = true</literal>.
105
+
</para>
106
+
<para>
107
+
The default is to generate a password file for each listener
108
+
from the users configured to that listener. Users with no
109
+
configured password will not be added to the password file and
110
+
thus will not be able to use the broker.
111
+
</para>
112
+
</section>
113
+
<section xml:id="module-services-mosquitto-config-acl">
114
+
<title>ACL format</title>
115
+
<para>
116
+
Every listener has a Mosquitto <literal>acl_file</literal>
117
+
attached to it. This ACL is configured via two attributes of the
118
+
config:
119
+
</para>
120
+
<itemizedlist spacing="compact">
121
+
<listitem>
122
+
<para>
123
+
the <literal>acl</literal> attribute of the listener
124
+
configures pattern ACL entries and topic ACL entries for
125
+
anonymous users. Each entry must be prefixed with
126
+
<literal>pattern</literal> or <literal>topic</literal> to
127
+
distinguish between these two cases.
128
+
</para>
129
+
</listitem>
130
+
<listitem>
131
+
<para>
132
+
the <literal>acl</literal> attribute of every user
133
+
configures in the listener configured the ACL for that given
134
+
user. Only topic ACLs are supported by Mosquitto in this
135
+
setting, so no prefix is required or allowed.
136
+
</para>
137
+
</listitem>
138
+
</itemizedlist>
139
+
<para>
140
+
The default ACL for a listener is empty, disallowing all
141
+
accesses from all clients. To configure a completely open ACL,
142
+
set <literal>acl = [ "pattern readwrite #" ]</literal>
143
+
in the listener.
144
+
</para>
145
+
</section>
146
+
</section>
147
+
</chapter>