parent
d09952fea8
commit
0343045a92
@ -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. |
@ -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 new issue