4.1.x to 4.2.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.2 is a drop in replacement for HiveMQ 4.1.x

No manual steps are required to upgade from HiveMQ 4.1 to HiveMQ 4.2.

Cluster Upgrade

This HiveMQ version supports rolling upgrade, and it is possible to run HiveMQ version 4.1 and version 4.2 simultaneously in the same cluster. By default, the HiveMQ cluster enables all new cluster features once all nodes are upgraded to the new version.
No manual intervention is required.

To ensure a seamless and successful rolling upgrade process, see HiveMQ Rolling Upgrade.

For more information, see HiveMQ Clusters.

Upgrade a Single-node HiveMQ Instance

  • Create a backup of the entire HiveMQ installation folder

  • Install HiveMQ 4.2 as described in the HiveMQ Installation Guide

  • Migrate the configuration-file contents of your old HiveMQ installation

  • To migrate the persistent data, copy all contents in the data folder from your backup to the new HiveMQ 4.2 data folder. On first start, HiveMQ 4.2 will migrate the persistent data from your previous installation into its new persistent storage.

HiveMQ is specifically designed to deliver the highly-available ultra-scalable MQTT clusters that professional MQTT deployments require. To fully benefit from the advantages the HiveMQ Enterprise and Professional editions offer, we recommend running HiveMQ in a cluster environment. For more information, see https://www.hivemq.com/docs/hivemq/latest/user-guide/cluster.[HiveMQ Cluster].

Configuration File Changes

HiveMQ 4.2 introduces additional options to the configuration file.

The control center configuration now allows you to disable the default user admin. If you choose not to set this configuration, the behaviour is similar to HiveMQ 4.1.

The new control center audit log feature introduced in 4.2 can be configured with the value <control-center-audit-log> in the security configuration.

You can upgrade from HiveMQ 4.1.x to HiveMQ 4.2 without making changes to your config file.

Persistent Data Migration

HiveMQ 4.2 automatically migrates all data in your data folder from previous versions to updated file storage formats.

To allow HiveMQ to migrate the persistent data from previous versions you have to copy the contents of your data folder from the previous installation to the data folder of the new installation.

Linux example
cp -r /opt/hivemq-4.1.1/data/* /opt/hivemq-4.2.0/data/

On the first start up HiveMQ 4.2 will automatically migrate the persistent data from your previous installation into its new persistent storage.

Inflight Window

To allow more network throughput from the broker to the clients, HiveMQ 4.2 introduces support for a larger inflight window for MQTT PUBLISH messages.

The inflight window is the amount of MQTT PUBLISH messages that are sent to a client simultaneously without the client having sent back an PUBACK or PUBCOMP.

HiveMQ 4.1 has a default inflight window of maximum 4 messages, with HiveMQ 4.2 the inflight window is now 50 by default. HiveMQ 4.1 only allowed 1 inflight message per topic, while HiveMQ 4.2 can send multiple messages per topic simultaneously. The messages are sent in order and the receive maximum of the client is respected. The inflight window for specific clients can be changed in extensions with the client settings.