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.

Requirements to backup and restore with the REST API

  • All cluster nodes run HiveMQ version 4.4.0 or higher

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

The HiveMQ Control Center and REST API backup and restore functions are available for both HiveMQ Professional and Enterprise editions.

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.

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. For example, use the HiveMQ REST API to schedule a REST call that triggers a backup at a predefined interval.

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.

Requirements to restore from a backup file

The following requirements must be met to successfully restore data from a backup with the HiveMQ Control Center or REST API:

  • A fresh HiveMQ deployment. This means that no clients must be connected and no persistent data exists on every HiveMQ node. A fresh HiveMQ cluster is defined as follows:

    • No client sessions.

    • No subscriptions.

    • No retained messages.

    • No queued messages.
      If any of the data listed above is present in your cluster, HiveMQ does not start the import.

  • Message data that your HiveMQ extensions use is only restored if the corresponding extension is already started before the restore is started.