Skip to content
Branch: master
Find file Copy path
Find file Copy path
7 contributors

Users who have contributed to this file

@pvizeli @frenck @ThomDietrich @balloob @jensihnow @gerard33 @cogneato
168 lines (107 sloc) 5.67 KB

Home Assistant Add-on: Mosquitto broker

MQTT broker for Home Assistant.

Supports aarch64 Architecture Supports amd64 Architecture Supports armhf Architecture Supports armv7 Architecture Supports i386 Architecture


You can use this add-on to install Eclipse Mosquitto, which is an open-source (EPL/EDL licensed) message broker that implements the MQTT protocol. Mosquitto is lightweight and is suitable for use on all devices from low power single board computers to full servers. For more information, please see mosquitto.


Follow these steps to get the add-on installed on your system:

  1. Navigate in your Home Assistant frontend to Supervisor -> Add-on Store.
  2. Find the "Mosquitto broker" add-on and click it.
  3. Click on the "INSTALL" button.

How to use

The add-on has a couple of options available. To get the add-on running:

  1. Start the add-on.
  2. Have some patience and wait a couple of minutes.
  3. Check the add-on log output to see the result.

Create a new user for MQTT via the Configuration -> Users (manage users). Note: This name cannot be homeassistant or addon, those are reserved usernames.

To use the Mosquitto as a broker, go to the integration page and install the configuration with one click:

  1. Navigate in your Home Assistant frontend to Configuration -> Integrations.
  2. MQTT should appear as a dicovered integration at the top of the page
  3. Select it and check the box to enable MQTT discovery if desired, and hit submit.

If you have old MQTT settings available, remove this old integration and restart Home Assistant to see the new one.


Add-on configuration:

logins: []
anonymous: false
  active: false
  folder: mosquitto
certfile: fullchain.pem
keyfile: privkey.pem
require_certificate: false

Option: logins (optional)

A list of local users that will be created with username and password. You don’t need to do this because you can use Home Assistant users too, without any configuration. If a local user is specifically desired:

  - username: user
    password: passwd

Option: anonymous

Allow anonymous connections. If logins are set, the anonymous user can only read data.

Default value: false


If set to true additional configuration files will be read, see the next option.

Default value: false

Option: customize.folder

The folder to read the additional configuration files (*.conf) from.

Option: cafile (optional)

A file containing a root certificate.

Option: certfile

A file containing a certificate, including its chain.

Option: keyfile

A file containing the private key.

Option: require_certificate

If set to true encryption will be enabled using the cert- and keyfile options.

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 Home Assistant ecosystem, we register homeassistant and addons, so these may not be used as user names.

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:

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

  1. Enable the customize flag

        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 #

    For anonymous mode ( "anonymous": true ), your have to remove the user [YOUR_MQTT_USER] line like so:

    topic readwrite #

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

Known issues and limitations

  • Since version 4.1 of the add-on, an explicit ACL definition is now required if you plan to use legacy logins and "anonymous": true see these instructions.


Got questions?

You have several options to get them answered:

In case you've found a bug, please open an issue on our GitHub.

You can’t perform that action at this time.