Question
I have an old installation of homeassistant in a VM paired with IOTstack in another VM.
It is no longer possible to upgrade this setup because it is too many versions behind.
I have created a new VM with HAOS installed and this time I would like to use the Mosquitto integration in HAOS. There have been significant changes in MQTT to HA interactions (naming) and I don’t want to blindly transfer the existing MQTT and Zigbee configs.
I have a significant number of Zigbee sensors/switches and also WiFi-based Tasmota actuators.
Also a few shelly wifi devices.
I want to stay with Zigbee2MQTT and Tasmota. I have tried ESPHome but found it to be much more likely to brick devices than Tasmota. I am not interested in ZHA.
Because parts of the whole-system configuration exists in pairings and possibly device configs I want to keep the Zigbee and Tasmota configs as is and use an approach where I shutdown the production environment (IOTstack and HAOS-old) and the start a staging system (HAOS-new (with Mosquitto)). Would that allow me to roll back at any time?
How would I keep the Zigbee, Tasmota, Shelly configs stable in this approach?
What is the migration path? Is there a point of no return?
Short answer (TL; DR)
If you copy the configuration directories (Zigbee2MQTT data dir and Mosquitto passwords/ACLs), keep the same coordinator stick + network key and leave every end-device untouched, you can shut the old VMs down, boot the new HAOS VM, and all devices will reconnect. If anything goes wrong you merely power the staging VM off and start the old pair again; nothing in the RF mesh or in the Wi-Fi devices has changed, so roll-back is instant.
The only irreversible step is changing something on the devices themselves (flashing firmware, re-pairing Zigbee, rewriting the MQTT broker address in Tasmota/Shelly). Delay those edits until you’ve confirmed the staging system works.
Step-by-step migration playbook
| Phase | Action | Notes / “gotchas” |
|---|---|---|
| 1 Audit & back up | • Snapshot both VMs.• Tar/zip: • /opt/zigbee2mqtt (or wherever data sit). • /etc/mosquitto incl. passwd, acl. | The Zigbee2MQTT data dir contains coordinator_backup.json, network_key, pan_id, and the cached device list—keep all of it. |
| 2 Freeze production | • Gracefully stop Home Assistant first (so it saves state).• Stop Zigbee2MQTT container.• Stop Mosquitto last.• Leave both old VMs powered off and do not touch the stick. | This prevents retained messages from getting out of sync while you test. |
| 3 Copy configs into HAOS-new | 1. Insert the same USB coordinator stick in the new VM and expose it to HAOS‐new.2. Install the Official Zigbee2MQTT add-on (or a community repo) and bind-mount or copy your saved data dir into /config/zigbee2mqtt.3. In the add-on options, point serial: to the new /dev/ttyUSBx path, but leave the network key & channel untouched.4. Install the Mosquitto broker add-on and drop mosquitto.conf, passwd, acl into /share/mosquitto/ (or recreate the same users/passwords via the add-on UI). | HAOS add-ons run under Docker but paths are kept under /config or /share; use the add-on’s Configuration > Map additional volumes feature if you want to bind-mount. |
| 4 Preserve broker reachability | Easiest: give the new HAOS VM the same LAN IP the old Mosquitto VM used.Alternative: in Tasmota ≥ 12 you can set a primary + secondary broker (MqttHost / MqttHost2) so you can test without losing the old address. | Not touching device configs = zero point-of-no-return. |
| 5 Bring up staging | • Start Mosquitto add-on.• Start Zigbee2MQTT add-on and watch its log—every device should re-appear within ~2 min.• In HAOS Settings → Integrations the Mosquitto broker will auto-discover. Add the Zigbee2MQTT MQTT integration if you used MQTT discovery before.• Walk around and verify sensors update and Tasmota/Shelly relays toggle. | Expect the entity IDs to be slightly different in modern HA (e.g. binary_sensor.front_door_contact instead of legacy _state). You can use Aliases or batch-rename inside HA after testing. |
| 6 Cut-over | Once satisfied, delete or re-IP the old VMs to avoid two brokers on the network. | Keep the snapshots for a while—nothing prevents you from rolling back months later if necessary. |
Keeping configurations stable
| Device type | What must stay identical | Where it lives | Risk if changed |
|---|---|---|---|
| Zigbee (Zigbee2MQTT) | • Coordinator IEEE address & firmware• PAN ID• Network key• Channel | In configuration.yaml + state/**.json inside Z2M data dir | If any of these differ you must repair every sensor. |
| Tasmota | MqttHost, MqttPort, user/pass | Stored in each device’s flash (SetOption8, etc.) | Only risk is if you re-flash or change broker IP. |
| Shelly | Same as Tasmota if you use MQTT, or leave them on the native Shelly integration and they’re unaffected | Shelly UI or script | Changing protocol is reversible but means extra testing. |
“Point of no return”
- Re-pairing Zigbee devices (or flashing a new coordinator firmware) → the old network key is lost, rollback is painful.
- Bulk updating MQTT host/user on Wi-Fi devices → you would need to run the change twice (once to leave, once to come back).
- Deleting the old VM snapshots.
If you avoid those three, you can always shut the new VM down and boot the old pair—your house keeps working.
Practical rollback tip
If you want zero downtime while testing, plug a second coordinator stick into HAOS-new and form a parallel Zigbee network on a different channel (e.g. 25). Pair one or two sacrificial sensors first. Once confident, swap in the real stick and copy the data dir; takes ~30 seconds.
Final checklist
- VM snapshots taken
- Zigbee2MQTT data dir copied into HAOS add-on
- Mosquitto users/ACL recreated
- New VM answers at the old broker IP
- Staging system proven for ≥24 h
- Old VMs powered off or re-IP’d
Once every box is ticked you’re running on a fully-supported HAOS install, but nothing in the physical devices ever noticed the change—exactly the safety net you’re after.