Aktualizováno: 2026-10-08 · Platí pro: 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 na Umbrelu krok za krokem

Cíl: rozběhnout Mosquitto z Umbrel App Store jako zaheslovaný MQTT broker a připojit k němu Home Assistant a Zigbee2MQTT. Aplikace po instalaci pouští anonymní klienty, takže nejdůležitější krok je zapnout hesla.¹
Předpoklady: Umbrel (např. Umbrel Home nebo Raspberry Pi s 8 GB a víc), přístup do Settings → Advanced settings → Terminal, u Zigbee síťový coordinator (např. SLZB-MR3) s pevnou IP.

Potřebné aplikace

Syntéza: HA na Umbrelu je kontejner bez aplikací (dřív add-ony), takže „Mosquitto broker“ z HA OS tu není a HA neumí broker zaheslovat sám. Uživatele zakládáš ručně podle kroku 2.

Postup

1. Nainstaluj Mosquitto z App Store (kategorie automatizace). Pokud chceš Zigbee2MQTT, Umbrel ho bez Mosquitto nenainstaluje.¹
2. Založ uživatele. V terminálu umbrelOS spusť nástroj mosquitto_passwd, který je v image brokeru.² Kontejner se jmenuje 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 soubor vytvoří (a přepíše), proto jen u prvního uživatele. Heslo se zadává interaktivně. Syntéza: každá služba svého uživatele, ať jde jednu odpojit bez dopadu na ostatní. Na hostiteli soubor najdeš v ~/umbrel/app-data/mosquitto/data/mosquitto/.¹
3. Uprav konfiguraci: sudo nano ~/umbrel/app-data/mosquitto/data/config/mosquitto.conf.¹ Místo allow_anonymous true a zakomentovaného #password_file dej:

   allow_anonymous false
   plugin /usr/lib/mosquitto_password_file.so
   plugin_opt_password_file /mosquitto/data/mosquitto.password_file
   

   Od 2.1 je password_file zastaralý a nahrazuje ho plugin password-file, ve verzi 3.0 zmizí.³ Cesta k pluginu a volba plugin_opt_password_file jsou podle oficiálního Docker image.² Bez per_listener_settings platí ověření pro oba listenery, tedy i pro WebSockets na 9021.²
4. Restartuj broker: sudo docker restart mosquitto_broker_1, nebo restart aplikace v UI Umbrelu. Pak sudo docker logs --tail 30 mosquitto_broker_1: broker musí běžet bez chyb. Chybný soubor s hesly broker v 2.1 ukončí.³
5. Home Assistant: Settings → Devices & services → Add integration → MQTT, zadej broker, port 1883, uživatele ha a heslo.⁴ Jako broker zadej 127.0.0.1: HA běží v síti hostitele a Mosquitto má port 1883 publikovaný na hostitele.¹ Discovery prefix nech výchozí homeassistant.⁴
6. Zigbee2MQTT (volitelně): nainstaluj a projdi úvodního průvodce. Spustí se, dokud neexistuje configuration.yaml, a umí najít adaptér přes mDNS, jinak zadáš port a typ ručně.⁵
   • síťový coordinator: port: tcp://<ip>:6638, výchozí socket SLZB je 6638⁶
   • typ: ember pro Silicon Labs (EFR32), zstack pro TI (CC26xx). Hodnoty vypíše generátor konfigurace v SLZB-OS.^5,6
7. Zigbee2MQTT → broker s heslem. Aplikace nastavuje jen adresu serveru.¹ Doplň do ~/umbrel/app-data/zigbee2mqtt/data/configuration.yaml (složka data je v kontejneru /app/data)¹:

   mqtt:
     user: z2m
     password: '!secret.yaml password'
   homeassistant:
     enabled: true
   

   a heslo do secret.yaml vedle (password: …).⁵ homeassistant.enabled zapne MQTT discovery do HA.⁵ Pak restartuj aplikaci Zigbee2MQTT.
8. ZHA vypni. Coordinator obsluhuje vždy jen jedna služba. Objevenou ZHA integraci v HA smaž a ignoruj.⁷

Ověření

• Log brokeru po restartu bez chyb, při připojení klientů v něm vidíš jejich jména (sudo docker logs -f mosquitto_broker_1). Syntéza
• MQTTX Web: nové spojení na umbrel.local, port 9021 (WebSockets), uživatel a heslo. Bez hesla se nepřipojíš, s heslem odebírej #.¹
• HA: integrace MQTT bez chyby. V jejím nastavení „Listen to a topic“ s # ukáže provoz.⁴
• Z2M: frontend ukáže coordinator a v HA se po spárování objeví zařízení přes discovery.

Volitelně: ACL

Plugin acl-file omezí, kdo smí číst a psát do kterých topiců: plugin /usr/lib/mosquitto_acl_file.so a plugin_opt_acl_file /mosquitto/data/mosquitto.aclfile.² Řádky user <jméno> a pod nimi topic [read|write|readwrite|deny] <topic>.²

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

user ha
topic readwrite #

Syntéza: se zapnutými ACL je všechno ostatní zakázané, takže Z2M potřebuje i homeassistant/# kvůli discovery. ACL přidávej až po ověření, že bez nich všechno funguje.

Rollback

• Vrať allow_anonymous true, zakomentuj oba řádky plugin a restartuj broker.
• Soubory s hesly a ACL nech na místě, ať jde změnu zopakovat.

Troubleshooting

• Broker nenastartuje: špatná cesta k souboru nebo pluginu. Vždy cesta v kontejneru (/mosquitto/...), ne na hostiteli (~/umbrel/...).² Od 2.1 jde konfiguraci zkontrolovat přes --test-config.³
• „not authorised“ / odmítnuté připojení: špatné jméno nebo heslo, nebo klient ještě běží bez hesla (typicky Z2M po kroku 3). Syntéza
• Velké zprávy padají: od 2.1 je max_packet_size výchozí 2 MB místo 256 MB.³
• Přístup zvenku: broker do internetu nevystavuj, vzdálený přístup přes VPN, viz Mosquitto. Umbrel sám doporučuje při vystavení autentizaci.¹

Souvislosti

• Mosquitto, MQTT, Zigbee2MQTT, Home Assistant, Home Assistant Connect SLZB, Umbrel Home, Raspberry Pi, SLZB-MR3, ZHA (Zigbee Home Automation), Docker

Zdroje

1. Umbrel App Store: aplikace Mosquitto ↗ — aplikace Mosquitto, Zigbee2MQTT, Home Assistant a MQTTX Web v Umbrel App Store.
2. Eclipse Mosquitto: Docker image 2.1 a mosquitto.conf(5) ↗ — oficiální Docker image Mosquitto 2.1 (pluginy, cesty) a mosquitto.conf(5).
3. Mosquitto blog: release notes 2.0.19–2.1.2 ↗ — změny v 2.1.
4. Home Assistant documentation (instalace, pojmy, zálohy, MQTT, ZHA, SMLIGHT, UniFi) ↗ — nastavení integrace MQTT.
5. Zigbee2MQTT documentation (Zigbee network, stabilita, binding, párování) ↗ — MQTT, adaptér, integrace s HA, úvodní průvodce.
6. SLZB-OS (SMLIGHT Manuals) ↗ — socket síťového coordinatoru.
7. Home Assistant Connect ZBT-2 (Nabu Casa Support) ↗ — ZHA vedle Z2M.