@@ -0,0 +1,147 @@
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>