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 {
  11   services.mosquitto = {
  12     enable = true;
  13     listeners = [ {
  14       acl = [ "pattern readwrite #" ];
  15       omitPasswordAuth = true;
  16       settings.allow_anonymous = true;
  17     } ];
  18   };
  19 }
  20 ```
  21
  22 This will start a broker on port 1883, listening on all interfaces of the machine, allowing
  23 read/write access to all topics to any user without password requirements.
  24
  25 User authentication can be configured with the `users` key of listeners. A config that gives
  26 full read access to a user `monitor` and restricted write access to a user `service` could look
  27 like
  28
  29 ```nix
  30 {
  31   services.mosquitto = {
  32     enable = true;
  33     listeners = [ {
  34       users = {
  35         monitor = {
  36           acl = [ "read #" ];
  37           password = "monitor";
  38         };
  39         service = {
  40           acl = [ "write service/#" ];
  41           password = "service";
  42         };
  43       };
  44     } ];
  45   };
  46 }
  47 ```
  48
  49 TLS authentication is configured by setting TLS-related options of the listener:
  50
  51 ```nix
  52 {
  53   services.mosquitto = {
  54     enable = true;
  55     listeners = [ {
  56       port = 8883; # port change is not required, but helpful to avoid mistakes
  57       # ...
  58       settings = {
  59         cafile = "/path/to/mqtt.ca.pem";
  60         certfile = "/path/to/mqtt.pem";
  61         keyfile = "/path/to/mqtt.key";
  62       };
  63     } ];
  64   };
  65 }
  66 ```
  67
  68 ## Configuration {#module-services-mosquitto-config}
  69
  70 The Mosquitto configuration has four distinct types of settings:
  71 the global settings of the daemon, listeners, plugins, and bridges.
  72 Bridges and listeners are part of the global configuration, plugins are part of listeners.
  73 Users of the broker are configured as parts of listeners rather than globally, allowing
  74 configurations in which a given user is only allowed to log in to the broker using specific
  75 listeners (eg to configure an admin user with full access to all topics, but restricted to
  76 localhost).
  77
  78 Almost all options of Mosquitto are available for configuration at their appropriate levels, some
  79 as NixOS options written in camel case, the remainders under `settings` with their exact names in
  80 the Mosquitto config file. The exceptions are `acl_file` (which is always set according to the
  81 `acl` attributes of a listener and its users) and `per_listener_settings` (which is always set to
  82 `true`).
  83
  84 ### Password authentication {#module-services-mosquitto-config-passwords}
  85
  86 Mosquitto can be run in two modes, with a password file or without. Each listener has its own
  87 password file, and different listeners may use different password files. Password file generation
  88 can be disabled by setting `omitPasswordAuth = true` for a listener; in this case it is necessary
  89 to either set `settings.allow_anonymous = true` to allow all logins, or to configure other
  90 authentication methods like TLS client certificates with `settings.use_identity_as_username = true`.
  91
  92 The default is to generate a password file for each listener from the users configured to that
  93 listener. Users with no configured password will not be added to the password file and thus
  94 will not be able to use the broker.
  95
  96 ### ACL format {#module-services-mosquitto-config-acl}
  97
  98 Every listener has a Mosquitto `acl_file` attached to it. This ACL is configured via two
  99 attributes of the config:
 100
 101   * the `acl` attribute of the listener configures pattern ACL entries and topic ACL entries
 102     for anonymous users. Each entry must be prefixed with `pattern` or `topic` to distinguish
 103     between these two cases.
 104   * the `acl` attribute of every user configures in the listener configured the ACL for that
 105     given user. Only topic ACLs are supported by Mosquitto in this setting, so no prefix is
 106     required or allowed.
 107
 108 The default ACL for a listener is empty, disallowing all accesses from all clients. To configure
 109 a completely open ACL, set `acl = [ "pattern readwrite #" ]` in the listener.