HiveMQ Backup and Restore
Backups are an important part of every mission-critical MQTT deployment. All software that contains persistent data carries the risk of data loss due to power failures, hardware issues, or other outside influences. To reduce the impact of such risks, HiveMQ provides a backup solution that helps ensure minimum loss and quick recovery from potentially disastrous situations.
HiveMQ provides two convenient ways to backup and restore your data:
Back up and Restore from the HiveMQ Control Center
The HiveMQ Control Center allows you to create backups, import, and migrate data from HiveMQ simply and efficiently. Regardless of the deployment size, your backup files contain all of the relevant session data of your clients from the entire cluster. Our fully-integrated Control Center allows you to manage your backups from every available node in your cluster.
You can download all of your data in one compressed backup file.
In the Control Center, it is also possible to initiate a cluster-wide restoration of a backup. In case of a disaster, your backup files can be used to restore any previous cluster state. Additionally, the backup functionality can be used to migrate data to other infrastructure providers. Simply export cluster data and import it into a fresh cluster.
Requirements to backup and restore with the control center
-
All cluster nodes run HiveMQ version 4.2.0 or higher
-
Only one backup/restore can be executed at the same time
-
If Control Center Role Based Access Control is configured, only users with the right permissions can initiate backup and restore tasks
Back up and Restore with the HiveMQ REST API
The HiveMQ REST API provides endpoints that can be used to create, download, inspect, and restore HiveMQ backups. Regardless of the deployment size, your backup files contain all of the relevant session data of your clients from the entire cluster.
You can download all of your data in one compressed backup file.
It is also possible to use the HiveMQ REST API to initiate a cluster-wide restoration of a backup. In case of a disaster, your backup files can be used to restore any previous cluster state. Additionally, the backup functionality can be used to migrate data to other infrastructure providers. Simply export cluster data and import it into a fresh cluster.
Backup Content
The following data from your HiveMQ cluster is exported to a backup file when you initiate a backup
-
Sessions of persistent clients
-
Subscriptions of persistent clients
-
Queued messages
-
Queued messages of persistent clients
-
Queued messages of shared subscriptions
-
-
Message data that your HiveMQ extensions use. For example, the HiveMQ Enterprise Extension for Kafka.
|
A persistent client session is a session of a client that is persisted in HiveMQ after the client disconnects. For an MQTT 3 client this means setting clean-session = false. For an MQTT 5 client this means setting a session-expiry-interval > 0. |
Backup file location
The backup file is stored in the backup folder of the HiveMQ node where the backup is initiated.
You can use the Control Center on any HiveMQ node to download the backup.
If you want to manually download a backup file, you need to know on which node you started the export and the location of your HiveMQ backup folder.
If desired, you can change the location of your HiveMQ backup folder.
For more information, see Manually set specific HiveMQ folders.
|
Create a Backup
Backup creation is a simple action in either the Control Center or with the HiveMQ REST API. Manual backup generation is suitable for some use cases. However, we recommend an automated backup solution for all mission-critical deployments. To trigger an export automatically, you can use a JMX management action. The HiveMQ Control Center shows all available backups on the nodes. It does not matter if the backup was triggered manually or via JMX.
Requirements to create a backup file for export
The following requirements must be met to successfully create and export a backup from the HiveMQ Control Center or REST API:
-
All HiveMQ nodes have at least 1GB of free disk space (the actual amount of free disk space needed varies based on the state that is present on the HiveMQ cluster).
-
No cluster topology changes occur during the export.
| To avoid inconsistent data in the backup, HiveMQ immediately cancels the backup export if a topology change is detected. |
Restore from a backup file
You can use the Control Center or the HiveMQ REST API to restore from a backup.
Since HiveMQ 4.9.0, it is possible to restore from a backup file to a running HiveMQ cluster that contains data and has active client sessions.
HiveMQ resolves any data conflicts that occur during the live import of the backup as follows:
| Live Import Conflict | Resolution |
|---|---|
A retained message on the same topic is present in the backup file and on your cluster. |
HiveMQ keeps the retained message with the most recent timestamp. |
A client session is already present for a client on your cluster at the time of import. |
HiveMQ does not overwrite the existing session. |
A subscription to the same topic is present in the backup file and on your cluster. |
HiveMQ only adds subscriptions that do not yet exist on the cluster. No existing subscriptions are overwritten. |
Queued messages are already present on your cluster. |
HiveMQ appends PUBLISH messages to the end of the queue without packet IDs. |
A session attribute is already present for a key on your cluster. |
HiveMQ keeps the session attribute with the most recent timestamp. |
| Message data that your HiveMQ extensions use is only restored if the corresponding extension is already started before the restore is started. |
For further information on disaster detection and disaster recovery mechanisms in HiveMQ, see Cluster Disaster Recovery.