Mosquitto is an open-source message broker that implements the Message Queuing Telemetry Transport (MQTT) protocol. [[MQTT]] is a lightweight messaging protocol designed for constrained devices and low-bandwidth, high-latency or unreliable networks. Mosquitto Broker facilitates the exchange of messages between devices and applications using the MQTT protocol, enabling efficient communication in Internet of Things (IoT), machine-to-machine (M2M), and other distributed systems. Key features and characteristics of Mosquitto Broker include: 1. **MQTT Protocol Support:** Mosquitto Broker fully supports the MQTT protocol, including versions 3.1, 3.1.1, and 5. MQTT is a publish-subscribe messaging protocol that enables efficient, asynchronous communication between clients and servers. It is widely used in IoT applications due to its lightweight and low-overhead nature. 2. **Publish-Subscribe Messaging:** Mosquitto Broker follows the publish-subscribe messaging pattern, where clients can publish messages to topics and subscribe to topics to receive messages. This decoupled communication model allows for scalable and flexible messaging architectures, where multiple clients can exchange messages without direct point-to-point connections. 3. **Quality of Service (QoS) Levels:** Mosquitto supports different levels of Quality of Service (QoS) for message delivery, including QoS 0 (At most once), QoS 1 (At least once), and QoS 2 (Exactly once). These QoS levels provide varying degrees of reliability and delivery guarantees, allowing clients to choose the appropriate level based on their application requirements. 4. **Authentication and Authorization:** Mosquitto Broker supports authentication and authorization mechanisms to secure access to the broker and restrict client actions based on user roles and permissions. It can integrate with external authentication providers such as LDAP, OAuth, or custom authentication plugins. 5. **TLS/SSL Encryption:** Mosquitto Broker supports Transport Layer Security (TLS) and Secure Sockets Layer (SSL) encryption to secure communication between clients and the broker. TLS/SSL encryption provides confidentiality, integrity, and authenticity of messages exchanged over the network. 6. **Persistence:** Mosquitto Broker provides options for message persistence, allowing messages to be stored on disk or in-memory to ensure reliable message delivery and recovery in case of broker failures or restarts. 7. **Scalability and Performance:** Mosquitto is designed to be lightweight and scalable, capable of handling thousands to millions of concurrent connections and messages. It is optimized for low resource usage and high performance, making it suitable for deployment in resource-constrained environments and high-throughput applications. Overall, Mosquitto Broker is a versatile and reliable MQTT message broker that provides the essential infrastructure for building scalable, efficient, and secure IoT and M2M communication systems. It is widely used in various industries and applications, including home automation, industrial automation, smart cities, and telemetry monitoring. ## Installation In Home Assistant, go to "Settings" -> "Add-Ons" ![[Screenshot 2024-03-12 144125.png]] Then, search for "Mosquitto", and click on "Mosquittto Broker" (Mosquitto is spelled with 2 Ts) ![[Screenshot 2024-03-12 144151.png]] Click "Install" and wait. ![[Mosquitto Broker.jpg]] ## 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 your Home Assistant's frontend **Settings** -> **People** -> **Users** , (i.e. not on Mosquitto's **Configuration** tab). Notes: 1. This name cannot be `homeassistant` or `addons`, those are reserved usernames. 2. If you do not see the option to create a new user, ensure that **Advanced Mode** is enabled in your Home Assistant profile. 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 **Settings** -> **Devices & Services** -> **Integrations**. 2. MQTT should appear as a discovered 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. ## Configuration The following documentation shouldn't be necessary for most users, installing the Add-on from the frontend will install this code in your [[Configuration.yaml]] file. Add-on configuration: ``` logins: [] customize: 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: ``` logins: - username: user password: passwd ``` You can also optionally set a `password` value using the hashed password obtained from the `pw` command (which is present inside the Mosquitto container). If doing so, you must also specify `password_pre_hashed: true` alongside the `username` and `password` values: ``` $ pw -p "foo" PBKDF2$sha512$100000$qsU7xQ8YCV/9nRuBBJVTxA==$jqw94Ej3aEr97UofY6rClmVCRkTdDiubQW0A6ZYmUI+pZjW9Hax+2w2FeYB3y5ut1SliB7+HAwIl2iONLKkohw== ``` ``` logins: - username: user password: "PBKDF2$sha512$100000$qsU7xQ8YCV/9nRuBBJVTxA==$jqw94Ej3aEr97UofY6rClmVCRkTdDiubQW0A6ZYmUI+pZjW9Hax+2w2FeYB3y5ut1SliB7+HAwIl2iONLKkohw==" password_pre_hashed: true ``` #### Option: `customize.active` 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. Place this file in the Home Assistant `ssl` folder. ### Option: `certfile` A file containing a certificate, including its chain. Place this file in the Home Assistant `ssl` folder. **Note on `certfile` and `keyfile`** - If `certfile` and `keyfile` are _not_ provided - Unencrypted connections are possible on the unencrypted ports (default: `1883`, `1884` for websockets) - If `certfile` and `keyfile` are provided - Unencrypted connections are possible on the unencrypted ports (default: `1883`, `1884` for websockets) - Encrypted connections are possible on the encrypted ports (default: `8883`, `8884` for websockets) - In that case, the client must trust the server's certificate ### Option: `keyfile` A file containing the private key. Place this file in the Home Assistant `ssl` folder. **Note on `certfile` and `keyfile`** - If `certfile` and `keyfile` are _not_ provided - Unencrypted connections are possible on the unencrypted ports (default: `1883`, `1884` for websockets) - If `certfile` and `keyfile` are provided - Unencrypted connections are possible on the unencrypted ports (default: `1883`, `1884` for websockets) - Encrypted connections are possible on the encrypted ports (default: `8883`, `8884` for websockets) - In that case, the client must trust the server's certificate ### Option: `require_certificate` If set to `false`: - Client is **not required** to provide a certificate to connect, username/password is enough - `cafile` option is ignored If set to `true`: - Client is **required** to provide its own certificate to connect, username/password is _not_ enough - A certificate authority (CA) must be provided: `cafile` option - The client certificate must be signed by the CA provided (`cafile`) ### Option: `debug` If set to `true` turns on debug logging for mosquitto and its auth plugin. This an help when tracking down an issue however running with this long term is not recommended as sensitive information will be logged. ## 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/1884) 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](http://www.steves-internet-guide.com/topic-restriction-mosquitto-configuration/) - [Mosquitto.conf man page](https://mosquitto.org/man/mosquitto-conf-5.html) Add the following configuration to enable **unrestricted** access to all topics for `[YOUR_MQTT_USER]`. **Note:** Home Assistant expects the users `homeassistant` and `addons` to have unrestricted readwrite access to all topics. If you choose to enable ACLs, you should grant this access to these users as demonstrated below. Otherwise you will run into issues. 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 addons topic readwrite # user homeassistant topic readwrite # user [YOUR_MQTT_USER] topic readwrite # ``` The `/share` folder can be accessed via SMB, or on the host filesystem under `/usr/share/hassio/share`. ## Support Got questions? You have several options to get them answered: - The [Home Assistant Discord Chat Server](https://discord.gg/c5DvZ4e). - The Home Assistant [Community Forum](https://community.home-assistant.io/). - Join the [Reddit subreddit](https://reddit.com/r/homeassistant) in [/r/homeassistant](https://reddit.com/r/homeassistant) In case you've found a bug, please [open an issue on our GitHub](https://github.com/home-assistant/addons/issues).