# 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