pyrox.dev
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">
13services.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">
35services.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">
56services.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>