installing an mqtt broker for home assistant core

What is MQTT and why do you want it ?

MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth.


In other words, it is a messaging protocol which is designed to be efficient for frequent message sending between different devices. A device can send messages to an mqtt topic, and your home assistant server could retrieve these messages from that topic.
Like the Installing zwave-js on home assistant core article, this component is actually installed out of the box on home assistant but not in the installation of the core version.

I keep the below info as a reference for myself, the document will be improved as I make changes.

Installation and configuration:

Install the package using apt. Like eg the zwave server, this will run as a separate daemon on your home assistant appliance (next to home assistant itself):

mosquitto/oldstable,now 1.5.7-1+deb10u1 armhf [installed]

go into /etc/mosquitto/ and add a custom configuration file to conf.d:

Set up a configuration:

# global
allow_anonymous false
password_file  /etc/mosquitto/conf.d/mosquitto_users

# default listener
port 1883

# ssl listenener
listener 8883
cafile /etc/mosquitto/certs/wf_ca.crt
certfile /etc/mosquitto/certs/mqtt.crt
keyfile /etc/mosquitto/certs/mqtt.key
#tls_version tlsv1.2

Here, I disable anonymous connections to the broker, configure a location for a user/password file and set up an ssl and a plaintext listener.

Configure a user:

mosquitto_passwd -c mosquitto_users mqttuser

(the -c is used to create the file so should be used only once. through -b you could add the password immediately on the cli).

Create some certificates for the ssl listener, you need:

  1. the certificate of your ca. this should be a private, internal ca.
  2. the certificate to be used for your mqtt broker
  3. the private key to be used for your mqtt broker.

place them into the certs folder:

ls -l certs/
total 16
-rw-r--r-- 1 root root  130 Nov 16  2019 README
-rw-r--r-- 1 root root 1859 Feb 10 15:01 mqtt.crt
-rw-r--r-- 1 root root 3244 Feb 10 15:01 mqtt.key
-rw-r--r-- 1 root root 1815 Feb 10 15:17 wf_ca.crt

You can now start the daemon.

Configuration in home assistant:

Unfortunately, not all settings can be configured through the gui (yet and at the time of writing). Notably configuring the ssl part. In your configuration.yml put:

  certificate: "/etc/mosquitto/certs/wf_ca.crt"
  broker: ""
  port: 8883
  username: mqttuser
  password: "thisismypassword"

Now go to settings/devices and verify the mqtt integration is there.

If you click ‘configure’ on the mqtt broker you can test it:

Leave a Reply

Your email address will not be published. Required fields are marked *