Backup, restore and updates

Why this matters

Over time EMQX builds up two kinds of thing you do not want to lose: configuration and data. The configuration is the structure — Authentication, Authorization (ACL), rules, connectors and sinks. The data is what sits in the built-in database: accounts, API keys, the blacklist and retained messages. The day you change one ACL rule by mistake and take every light in the house offline, or the day the Home Assistant host has to be replaced, no backup means rebuilding from nothing.

By the end of this chapter you will know where the add-on keeps its data, which files have to go into the backup, and what a restore actually takes you back to. You will also be able to run an add-on update safely, and to see what has to move across when you swap Mosquitto for EMQX.

Core concepts

EMQX keeps its runtime data in one place, the data directory (data dir), and the add-on puts it under /data/emqx. It breaks into three parts: /data/emqx/data (EMQX data, and the persisted built-in database), /data/emqx/etc (config files), and /data/emqx/plugins (plugins). Logs go somewhere else, to /config/log, which is outside that backup scope.

A Home Assistant backup (Backup) covers the add-on's /data, which makes it the least-effort way to restore everything in one go. If you would rather carry the configuration around at the file level, use the EMQX CLI: emqx ctl data export packs the configuration and the built-in DB into emqx-export-YYYY-MM-DD-HH-mm-ss.sss.tar.gz and writes it to the backup subfolder of the data directory, and emqx ctl data import loads it back.

Watch what the version numbers mean: add-on 5.9.0 only adds the ngrok TCP tunnel, and the core is still EMQX 5.8.9. A newer release in the add-on store does not necessarily mean the broker version has moved — the CHANGELOG is what decides.

Terms at a glance

Anyone whose backups carry passwords and tokens has to be that much more careful: any backup file holding credentials or an API key belongs somewhere only you can read, never in a repo or a public location.

Hands-on

1. Create a backup in Home Assistant

   Go to Settings → System → Backups in Home Assistant and click "Back up now". A full backup takes in the add-on's /data, and therefore /data/emqx with it. Sync the backup file to somewhere safe.

2. (Optional) Export a config bundle with the EMQX CLI

   Run emqx ctl data export in the add-on terminal or inside the container. It produces emqx-export-*.tar.gz, a file-level way to carry the configuration, and it suits you if you want to keep the configuration on its own or move it to an EMQX of the same version.

3. The order to restore in

   To restore the whole host, roll straight back to that backup. If you are replacing EMQX only (after a reinstall), stop the add-on first, put the contents of /data/emqx back where they belong, then start EMQX. Finally, check in the Dashboard that the accounts and the ACL rules are all there.

4. Update the add-on

   On the add-on page, click "Check for updates" at the bottom. Only click update once a new version shows up (5.9.0, for example), and restart as prompted when it finishes. Take a backup before you update. If the release only adds ngrok and leaves the EMQX core alone, the regression risk is relatively low.

What the backup covers

The add-on README states the principle as "a backup contains everything under /data/emqx". The table gives the exact scope.

Read against the EMQX documentation, an export tar usually covers: authentication and authorization settings; Data Integration (Rules/Connectors/Sinks/Sources); Listener and Gateway settings; the built-in database (Dashboard users and REST API keys, client password-based authentication and enhanced authentication, PSK, Authorization rules, Blacklist); and retained messages. TLS certificates and ACL files that sit inside the data directory travel with it.

If your certificate files or ACL files sit outside the data directory, neither one is in the archive, and you have to move them back by hand before you restore. That is exactly why so many people end up saying "I did take a backup, and the ACL is still missing" after a restore.

Restoring and importing from the CLI

If you import from the CLI, you can name the file you are bringing back by absolute path, by relative path, or — once it is in the backup subfolder of the data directory — by file name alone. The EMQX 5.8 documentation lists a few hard conditions:

• The EMQX node has to be running when you import.
• In a core + replica cluster, import on a core node only.
• Data exported from the Enterprise edition cannot be imported into Open Source.
• The file you import must not be renamed.

An import means "add it in, and update what is there"; it does not delete the other data you already have. In a few cases it can be incompatible with the existing data — if the authentication method differs (salt position, password storage mode), old user credentials may stop working after the import. Which is why backing up first and restoring carefully is the right way round.

If you run EMQX Enterprise, System → Backup & Restore in the Dashboard can create and restore backup files as well; but this Woow add-on ships 5.8.9 Open Source, so you are more likely to work with the CLI or with host-level backups.

What matters when migrating from Mosquitto

When you move Home Assistant from Mosquitto to EMQX, the thing that matters most is that port 1883 has only one winner: Mosquitto and Woow EMQX cannot run at the same time, because both of them bind 1883.

1. Stop Mosquitto

   Stop (or remove) the Mosquitto add-on to free up 1883.

2. Move the configuration to EMQX

   Recreate the same users in EMQX — you can keep the credentials you set up before — and rebuild the ACL rules there; EMQX manages them under Access Control.

3. Point everything at EMQX

   Change the broker address in HA's MQTT integration, in Zigbee2MQTT and on each external device to EMQX (homeassistant, 1883), and sign in with the EMQX users.

4. Verify, and finish up

   Confirm that HA, Z2M and every device connect, and that you can see them on the Clients page. If the old Mosquitto had ACL rules built up over a long time, reviewing them one by one as you convert them to EMQX Authorization is what keeps you from letting something through by mistake.

The backup principle applies here too: before you migrate, keep a record of the old Mosquitto configuration as it stands, so you can fall back if the migration fails.

Troubleshooting

• /data/emqx is not in the backup: check that the Home Assistant backup includes add-on data (in some cases you back up the system only, or only certain add-ons). If you are replacing EMQX alone and want to restore the existing configuration at the file level, a CLI export gives you more control.
• The Dashboard will not open after a restore: check whether another service is holding 1883/18083 and stop whatever conflicts first; then read the Log and confirm the data directory went back to the right place.
• The CLI import reports "file not found": the import file must not be renamed; if it sits in the backup subdirectory, the basename is enough. A relative path is resolved against the EMQX root directory.
• The version looks unchanged after an update: read the CHANGELOG first. Add-on 5.9.0 only adds ngrok TCP; the EMQX core is still 5.8.9. If what you were expecting was a new core feature, you may have to wait for another version.

FAQ

Official sources

• Woow EMQX add-on README (pinned commit: the data storage and backup section)
• EMQX 5.8 Backup and Restore (pinned docs)
• Woow EMQX CHANGELOG (the version facts)