home-assistant.io/source/_addons/mosquitto.markdown

title, description, featured

title	description	featured
Mosquitto MQTT broker	Fast and reliable MQTT broker.	true

Set up Mosquitto as MQTT broker.

{
  "logins": [
    {"username": "local-user", "password": "mypw"}
  ],
  "anonymous": false,
  "customize": {
    "active": false,
    "folder": "mosquitto"
  },
  "certfile": "fullchain.pem",
  "keyfile": "privkey.pem"
}

Since version 4.1 of the addon, an explicit ACL definition is now required, see these instructions.

{% configuration %} anonymous: description: Allow anonymous connections. If logins is set, the anonymous user can only read data. required: false default: false type: boolean logins: description: A list of local users that will be created with username and password. You don't need do this because you can use Home Assistant users too without any configuration. required: false type: list customize: description: If you enable it, it reads additional configuration files (*.conf) from /share/mosquitto. required: false type: [boolean, string] default: false {% endconfiguration %}

Home Assistant user management

This add-on is attached to the Home Assistant user system, so mqtt clients can make use of these credentials. Local users may also still be set independently within the configuration options for the add-on. For the internal Hass.io ecosystem we register homeassistant and addons, so these may not be used as user names.

Home Assistant configuration

To use the Mosquitto as broker, go to the integration page and install the configuration with one click. If you have old MQTT settings available, remove this old integration and restart Home Assistant to see the new one.

Using Mosquitto with Hass.io

1. Install the Mosquitto add-on with the default configuration via 'Hass.io > ADD-ON STORE'. (Don't forget to start the add-on & verify that 'Start on boot' is enabled.)

2. Create a new user for MQTT via the Configuration > Users (manage users). (Note: This name cannot be "homeassistant" or "addon")

3. Once back on-line, return to Configuration > Integrations and select configure next to MQTT.

  Broker: YOUR_HASSIO_IP_ADDRESS
  Port: 1883
  Username: MQTT_USERNAME
  Password: MQTT_PASSWORD

Note: .yaml modifications are not required. See testing your setup to verify the steps above.

Disable listening on insecure (1883) ports

Remove the ports from the add-on page network card (set them as blank) to disable them.

Access Control Lists (ACLs)

It is possible to restrict access to topics based upon the user logged in to Mosquitto. In this scenario it is recommended to create individual users for each of your clients and create an appropriate ACL.

See the following links for more information:

• Mosquitto topic restrictions
• Mosquitto.conf man page

Add the following configuration to enable unrestricted access to all topics.

1. Enable the customize flag

  "customize": {
    "active": true,
    "folder": "mosquitto"
  },

2. Create /share/mosquitto/acl.conf with the contents:

acl_file /share/mosquitto/accesscontrollist

3. Create /share/mosquitto/accesscontrollist with the contents:

user [YOUR_MQTT_USER]
topic readwrite #

The /share folder can be accessed via SMB, or on the host filesystem under /usr/share/hassio/share.