Updated: 2026-10-08 · Applies to: umbrelOS 1.x/2.x; Umbrel app mosquitto 2.1.2, zigbee2mqtt 2.14.2, home-assistant 2026.10.0, mqttx-web 1.13.1

Mosquitto on Umbrel step by step

Goal: get Mosquitto from the Umbrel App Store running as a password-protected MQTT broker and connect Home Assistant and Zigbee2MQTT to it. After installation the app lets anonymous clients in, so the most important step is turning on passwords.¹
Prerequisites: Umbrel (e.g. Umbrel Home or a Raspberry Pi with 8 GB or more), access to Settings → Advanced settings → Terminal, for Zigbee a network coordinator (e.g. SLZB-MR3) with a static IP.

Required apps

App (Umbrel App Store)	Version	Needed	Purpose
Mosquitto	2.1.2	always	broker, port 1883 (MQTT) and 9021 (web and MQTT over WebSockets)¹
Home Assistant	2026.10.0	usually	MQTT integration, runs in the host network (`network_mode: host`)¹
Zigbee2MQTT	2.14.2	for Zigbee over MQTT	has Mosquitto as a dependency and connects to `mqtt://mosquitto_broker_1:1883`¹
MQTTX Web	1.13.1	optional	in-browser MQTT client for debugging, connects over WebSockets¹

Synthesis: HA on Umbrel is a container without apps (formerly add-ons), so the "Mosquitto broker" from HA OS is not available here and HA cannot set up broker passwords by itself. You create users manually in step 2.

Procedure

Install Mosquitto from the App Store (automation category). If you want Zigbee2MQTT, Umbrel won't install it without Mosquitto.¹
Create users. In the umbrelOS terminal run mosquitto_passwd, which ships in the broker image.² The container is named mosquitto_broker_1¹:
```
sudo docker exec -it mosquitto_broker_1 mosquitto_passwd -c /mosquitto/data/mosquitto.password_file ha
sudo docker exec -it mosquitto_broker_1 mosquitto_passwd /mosquitto/data/mosquitto.password_file z2m
```
-c creates (and overwrites) the file, so only for the first user. The password is entered interactively. Synthesis: one user per service, so one can be cut off without affecting the others. On the host the file is in ~/umbrel/app-data/mosquitto/data/mosquitto/.¹
Edit the config: sudo nano ~/umbrel/app-data/mosquitto/data/config/mosquitto.conf.¹ Replace allow_anonymous true and the commented-out #password_file with:
```
allow_anonymous false
plugin /usr/lib/mosquitto_password_file.so
plugin_opt_password_file /mosquitto/data/mosquitto.password_file
```
Since 2.1 password_file is deprecated in favour of the password-file plugin and will be removed in 3.0.³ The plugin path and plugin_opt_password_file follow the official Docker image.² Without per_listener_settings authentication applies to both listeners, including WebSockets on 9021.²
Restart the broker: sudo docker restart mosquitto_broker_1, or restart the app in the Umbrel UI. Then sudo docker logs --tail 30 mosquitto_broker_1: the broker must run without errors. In 2.1 a broken password file makes the broker exit.³
Home Assistant: Settings → Devices & services → Add integration → MQTT, enter the broker, port 1883, user ha and password.⁴ Use 127.0.0.1 as the broker: HA runs in the host network and Mosquitto publishes port 1883 on the host.¹ Keep the default discovery prefix homeassistant.⁴
Zigbee2MQTT (optional): install it and go through the onboarding wizard. It runs while no configuration.yaml exists and can find the adapter via mDNS, otherwise you enter port and type manually.⁵
- network coordinator: port: tcp://<ip>:6638, the default SLZB socket is 6638⁶
- type: ember for Silicon Labs (EFR32), zstack for TI (CC26xx). The SLZB-OS config generator prints the values.^5,6
Zigbee2MQTT → password-protected broker. The app only sets the server address.¹ Add to ~/umbrel/app-data/zigbee2mqtt/data/configuration.yaml (the data folder is /app/data in the container)¹:
```
mqtt:
  user: z2m
  password: '!secret.yaml password'
homeassistant:
  enabled: true
```
and the password into secret.yaml next to it (password: …).⁵ homeassistant.enabled turns on MQTT discovery into HA.⁵ Then restart the Zigbee2MQTT app.
Turn off ZHA. Only one service can drive the coordinator. Delete and ignore the discovered ZHA integration in HA.⁷

Verification

Broker log without errors after restart; connecting clients show up with their user names (sudo docker logs -f mosquitto_broker_1). Synthesis
MQTTX Web: new connection to umbrel.local, port 9021 (WebSockets), user and password. Without a password it won't connect; with one, subscribe to #.¹
HA: MQTT integration without errors. "Listen to a topic" with # in its settings shows the traffic.⁴
Z2M: the frontend shows the coordinator, and paired devices appear in HA through discovery.

Optional: ACL

The acl-file plugin limits who may read and write which topics: plugin /usr/lib/mosquitto_acl_file.so and plugin_opt_acl_file /mosquitto/data/mosquitto.aclfile.² Lines user <name> with topic [read|write|readwrite|deny] <topic> below.²

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

user ha
topic readwrite #

Synthesis: with ACLs on, everything else is denied, so Z2M also needs homeassistant/# for discovery. Add ACLs only after verifying everything works without them.

Rollback

Restore allow_anonymous true, comment out both plugin lines and restart the broker.
Keep the password and ACL files in place so the change can be repeated.

Troubleshooting

Broker won't start: wrong path to the file or plugin. Always use the path inside the container (/mosquitto/...), not on the host (~/umbrel/...).² Since 2.1 the config can be checked with --test-config.³
"not authorised" / refused connection: wrong user or password, or a client still running without a password (typically Z2M after step 3). Synthesis
Large messages fail: since 2.1 max_packet_size defaults to 2 MB instead of 256 MB.³
Access from outside: don't expose the broker to the internet, use a VPN for remote access, see Mosquitto. Umbrel itself recommends authentication when exposing it.¹

Mosquitto, MQTT, Zigbee2MQTT, Home Assistant, Home Assistant Connect SLZB, Umbrel Home, Raspberry Pi, SLZB-MR3, ZHA, Docker

Sources

Umbrel App Store: the Mosquitto app ↗ — Mosquitto, Zigbee2MQTT, Home Assistant and MQTTX Web apps in the Umbrel App Store.
Eclipse Mosquitto: Docker image 2.1 and mosquitto.conf(5) ↗ — official Mosquitto 2.1 Docker image (plugins, paths) and mosquitto.conf(5).
Mosquitto blog: release notes 2.0.19–2.1.2 ↗ — changes in 2.1.
Home Assistant documentation (installation, concepts, backups, MQTT, ZHA, SMLIGHT, UniFi) ↗ — MQTT integration setup.
Zigbee2MQTT documentation (Zigbee network, stability, binding, pairing) ↗ — MQTT, adapter, HA integration, onboarding.
SLZB-OS (SMLIGHT Manuals) ↗ — network coordinator socket.
Home Assistant Connect ZBT-2 (Nabu Casa Support) ↗ — ZHA next to Z2M.