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 disaster situations.

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 in a fresh cluster.

The backup and restore functions are available for both HiveMQ Professional Edition and HiveMQ Enterprise Edition customers.

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

  • Client data of persistent clients added by Extensions

  • Shared subscriptions

  • Retained messages

  • 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.

General Requirements

Some prerequisites are necessary to create a backup or restore from a backup:

  • All HiveMQ nodes have at least version 4.2.0

  • Only one backup/restore can be executed at the same time

  • Only users with the right permissions can perform this backup and restore tasks if Control Center Role Based Access Control is configured

Export Requirements

The following requirements are necessary to successfully create a backup:

  • 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. The backup is aborted when the topology changes to avoid inconsistent data in the backup. therefore an export is aborted should a topology change occur.

Restore Requirements

The requirements to successfully restore data from a backup are:

  • A clean HiveMQ deployment. This means that no clients must be connected and no persistent data exists on every HiveMQ node. The import will not start if there is data available in your cluster.

  • Message data used by Extensions are only restored if the corresponding extension is already started before the restore is started.

Create a Backup

Creating a backup is as easy as clicking one button in the Control Center. Triggering backups manually as needed can be sufficient for some deployments. 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.

Restore from a Backup

You can use the Control Center to restore from a backup.