HiveMQ 4.52.x to 4.53.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.53 is a drop-in replacement for HiveMQ 4.52.x.

You can learn more about all the new features HiveMQ 4.53 introduces in our release blog post.

HiveMQ is prepackaged with all HiveMQ Enterprise Extensions (disabled), HiveMQ Data Hub, the open-source MQTT CLI tool, and the HiveMQ Swarm load-testing tool (MQTT CLI and HiveMQ Swarm are located in the tools folder of your HiveMQ installation).

HiveMQ 4.28 is the current HiveMQ LTS release. If you have not already done so, we recommend upgrading to HiveMQ version 4.28 or above.
To upgrade from the previous 4.9 LTS to HiveMQ 4.29 and above, you must first upgrade to the new 4.28 LTS version.
For more information, see the HiveMQ 4.9 to 4.28 Migration Guide, HiveMQ Rolling Upgrade Policy^, and our Managing HiveMQ Releases and Support blog post.
When you migrate from one HiveMQ version to another, we recommend that you review the upgrade information for each version between your current HiveMQ version and the target HiveMQ version.
Note changes that are relevant to your use case and adjust your configuration as needed.

New Minimum Kafka Broker Version for the HiveMQ Enterprise Extension for Kafka

As of HiveMQ 4.53, the minimum Kafka broker version changes from 0.10.2 to 2.1.

Before you upgrade to HiveMQ 4.53, confirm your Kafka brokers run version 2.1 or higher.

Deprecations and Upcoming Breaking Changes

The next HiveMQ LTS release will introduce breaking changes in the HiveMQ Enterprise Extension SDK and HiveMQ Enterprise Bridge Extension configuration.

HiveMQ 4.53 deprecates the affected APIs and logs warnings, so you can prepare early.

Control Center v1 Removal (Enterprise Extension SDK)

The next LTS release removes ControlCenterService.addView() and ControlCenterService.addViews() as part of the Control Center v1 retirement.

LoginLoadOutput.showLoginComponents() will be removed for the same reason.

Starting in HiveMQ 4.53, these methods are deprecated and usage logs a warning. To prepare, remove these method calls from your extensions before you upgrade to the next LTS.

Jakarta EE 10 Migration (Enterprise Extension SDK)

Extensions that register a RestApplication through RestServicePerExtension.setRestApplication() currently use javax.ws.rs (JAX-RS 2.x).

The next LTS release migrates HiveMQ to Jakarta EE 10. This change moves the package namespace to jakarta.ws.rs, which introduces a breaking change in these method calls.

Starting in HiveMQ 4.53, RestServicePerExtension.setRestApplication() logs a deprecation warning when the broker detects a javax.ws.rs (JAX-RS) application. To prepare, migrate your annotations and exception types to the jakarta.* namespace before you upgrade to the next LTS.

Netty 4.2 Hostname Verification (Bridge Extension)

The next LTS release upgrades HiveMQ to Netty 4.2. Netty then enforces hostname verification for all outbound TLS connections. Bridges whose remote broker certificate does not list the configured hostname in its CN or SANs will fail to connect.

Starting in HiveMQ 4.53, the broker logs a warning that names the affected bridge client and target hostname. To prepare, make sure each remote broker certificate includes the configured hostname before you upgrade to the next LTS.

Known Issues

HiveMQ 4.53 has no known issues.

Upgrade a HiveMQ Cluster

Rolling upgrades are supported, and it is possible to run HiveMQ version 4.52 and version 4.53 simultaneously in the same cluster. By default, the HiveMQ cluster enables all new cluster features when all nodes are upgraded to the new version. No manual intervention is required.

Please follow the instructions in our user guide to ensure a seamless and successful rolling upgrade.

Upgrade a Single-node HiveMQ Instance

  • Create a backup of the entire HiveMQ 4.52.x installation folder from which you want to migrate.

  • Install HiveMQ 4.53 as described in the HiveMQ Installation Guide.

  • Migrate the content of the config.xml and license files from your old HiveMQ 4.52.x installation.

  • To migrate your persistent data, copy everything from the data folder of your backup to the data folder of the new HiveMQ 4.53 installation.

HiveMQ Configuration File Changes

HiveMQ prevents the startup if your configuration file contains invalid values. For more information, see Configuration Validation.

HiveMQ Persistent Data Migration

When you migrate, HiveMQ automatically updates the file storage formats of all the data that you copied into your new data folder.

To migrate the persistent data, you must copy everything in the data folder of the previous HiveMQ 4.52.x installation to the data folder of your new HiveMQ 4.53 installation.

Linux example
cp -r /opt/hivemq-4.52.0/data/* /opt/hivemq-4.53.0/data/

The first time you start HiveMQ 4.53, the file storage formats of the persistent data from your previous installation are automatically updated in the new persistent storage.