Mosquitto

Last reviewed Aug 26, 2026 · 820 words

Mosquitto 2.0 refuses connections from anyone by default, and half of the "my sensors stopped talking" threads on the internet are people who upgraded from 1.x and never wrote a config file. Since the 2.0 release, a broker with no listener line binds to localhost only, and a broker without allow_anonymous true rejects clients that do not authenticate. Both are correct decisions for the thing that carries every door sensor and every light command in your house, and the whole setup is a 6-line config file once you know the shape of it. The broker itself is the least demanding service you will run: 64 MB of RAM is generous, it is written in C, EPL-2.0 licensed, and it has been the default MQTT broker in smart homes since 2009.

The config file that actually works

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log
    restart: unless-stopped

And ./config/mosquitto.conf:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

Create users with the bundled tool, which hashes the password into the file:

docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd homeassistant
docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd zigbee2mqtt

Restart, then test from any machine with the clients installed: mosquitto_sub -h broker-ip -u homeassistant -P secret -t '#' -v prints every message on the broker as it arrives, which is also the single best debugging tool in home automation. Its sibling mosquitto_pub -t test/hello -m on with the same credentials confirms the write path, and if both work the broker is done and every remaining problem lives in a client. Persistence matters more than it looks: retained messages (the last known state of every device) and queued messages for offline subscribers survive a restart only if that line is present and the data directory is a real volume.

One user per client, and an ACL when you can be bothered

The lazy pattern is one shared username for everything. The better pattern costs a minute per device: a user for Home Assistant, one for Zigbee2MQTT, one for Frigate, one per ESP board, each with a password nobody has to remember because it lives in that client's config. Then an acl_file line restricts each to its own topics:

user zigbee2mqtt
topic readwrite zigbee2mqtt/#
topic readwrite homeassistant/#

user frigate
topic readwrite frigate/#

This means a compromised camera container cannot publish a fake "front door open" event to the topic Home Assistant trusts. It is the cheapest security improvement in the whole smart-home stack and almost nobody does it.

TLS is for anything that leaves the LAN

On a home network the plaintext 1883 listener is normal. The moment a client is on another network, whether a remote sensor on cellular or a bridge to a broker on a VPS, add a second listener on 8883 with certfile, keyfile and cafile pointing at a real certificate, and leave require_certificate false unless you intend to hand out client certificates. Mosquitto's bridge feature is the other tool for that job: a connection block with address, remote_username and one or more topic lines replicates chosen topics between two brokers, which is how people link a holiday-home broker to the main one without exposing either.

A websockets listener on 9001 (protocol websockets) lets browser dashboards subscribe directly; it is optional and off by default.

What Mosquitto is not, and what sits beside it

The catalogue is right that this is "just a broker, not automation". It moves messages and remembers the last one per topic; it makes no decisions. The decisions live in Home Assistant's automations or in Node-RED, both of which connect as ordinary MQTT clients. There is no management UI beyond the log file; MQTT Explorer on a desktop is the graphical tool most people settle on for browsing topics. If you want a broker with a web dashboard, clustering and rule engines, that is EMQX, at roughly 10 times the memory and a complexity a house does not need. Mosquitto's boring reliability is why it is still the default in the Home Assistant first month and in most smart homes since.

What I'd do

Mosquitto 2 in Docker with the config above, a separate user per client, the ACL file from the first day, persistence on and the data directory in backups. Plain 1883 on the LAN, 8883 with a proper certificate only if something remote needs in, and a bridge rather than an exposed port for a second site. Then leave it alone; my instance has restarted for kernel updates and nothing else in years, which is the highest compliment I can pay a piece of infrastructure.