4.24.x to 4.25.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.25 is a drop in replacement for HiveMQ 4.24.x.

You can learn more about all the new features HiveMQ 4.25 introduces in our release blogpost.

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

Starting with the HiveMQ 4.9 LTS release, HiveMQ provides enhanced version compatibility for all HiveMQ releases.
For more information, see HiveMQ Rolling Upgrade Policy and our Introducing Flexible MQTT Platform Upgrades with HiveMQ blog post.

When you migrate from one HiveMQ version to another, 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.

Upgrade a HiveMQ Cluster

Rolling upgrades are supported, and it is possible to run HiveMQ version 4.24 and version 4.25 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.

For more information, see HiveMQ Clusters.

Upgrade a Single-node HiveMQ Instance

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

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

  • Migrate the contents of the configuration file from your old HiveMQ 4.24.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.25 installation.

Configuration File Changes

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

Persistent Data Migration

When you migrate, HiveMQ 4.25 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.24.x installation to the data folder of your new HiveMQ 4.25 installation.

Linux example
cp -r /opt/hivemq-4.24.0/data/* /opt/hivemq-4.25.0/data/

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

New Environment Variable for the Data Hub Scripting API

HiveMQ 4.25 introduces a new JAVET_DISABLE_PKU environment variable.

The new variable ensures system stability during the execution of JavaScript functions with the Data Hub Scripting API. If you use the Data Hub Transformations feature to add custom JavaScript-based transformation functions to Data Hub data policies, make sure that the variable is set to 1 when you launch HiveMQ.

If you use the HiveMQ containers images or the provided run.sh script to launch HiveMQ, no further action is required.

Changes in Container Images

HiveMQ 4.25 and 4.9.16 introduce small changes to their container images. These changes do not affect you if you are using the provided container images. Although very unlikely, the changes might affect you if you build your own images based on our images.

  • Changes in the base image hivemq/hivemq4:4.25.0 and hivemq/hivemq4:4.9.16:

    • Removed the HIVEMQ_GID and HIVEMQ_UID environment variables. They were not used at runtime and changing their values did not have an effect.

    • HiveMQ is now directly located in the /opt/hivemq folder. A version specific folder /opt/hivemq-{version} does not exist anymore and /opt/hivemq is no longer a symlink to /opt/hivemq-{version}.

  • Changes in the dns image hivemq/hivemq4:dns-4.25.0 and hivemq/hivemq4:dns-4.9.16:

    • All changes in the base image

    • /docker-entrypoint.d/40_dns_entrypoint.sh is not a symlink anymore, but the file directly. The symlink previously linked to /opt/pre-entry.sh which does not exist anymore.

  • Changes in the k8s image hivemq/hivemq4:k8s-4.25.0 and hivemq/hivemq4:k8s-4.9.16:

    • All changes in the dns image

    • The entrypoint is no longer /opt/hivemq/bin/pre-entry_1.sh but is inherited from the base image (/opt/docker-entrypoint.sh). The symlink from /opt/hivemq/bin/pre-entry_1.sh to /opt/docker-entrypoint.sh does not exist anymore.

    • The permissions of /opt/hivemq/conf/config.xml were aligned with the permissions in the base image: 0775 → 0770

    • The permissions of /opt/hivemq/extensions/hivemq-k8s-sync-extension were aligned with all other extensions: 0775 → 0770