HiveMQ 4.9 (LTS) to 4.28 (LTS) Migration Guide

HiveMQ 4.28 is the new Long Term Support (LTS) version of the HiveMQ Platform.
HiveMQ 4.28 LTS is a drop in replacement for HiveMQ 4.9.x LTS.

HiveMQ is prepackaged with all the HiveMQ Enterprise Extensions (disabled), the open-source MQTT CLI tool, and the HiveMQ Swarm load-testing tool (both located in the tools folder of your HiveMQ installation). If necessary, adapt your deployment pipeline to accommodate these changes.

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.
To learn more about the differences between the 4.9 LTS and the new 4.28 LTS version, see Newly Released Features in HiveMQ Enterprise MQTT Platform 4.28 LTS.

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.
To help ensure a smooth transition from one LTS version to the next, we compiled the changes listed in upgrade guides 4.9 to 4.28. For more information, see Change List for HiveMQ 4.9 to 4.28.

Upgrade a HiveMQ Cluster

Rolling upgrades are supported and it is possible to run HiveMQ version 4.9 and version 4.28 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 Clustering Documentation.

Upgrade a Single-node HiveMQ Instance

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

  • Install HiveMQ 4.28 as described in the HiveMQ Installation Guide

  • Migrate the contents of the configuration file from your old HiveMQ 4.9.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.28 installation. The first time you start HiveMQ 4.28, the file storage formats of the persistent data from your previous installation are automatically updated in the new persistent storage.

HiveMQ Configuration File Changes

The upgrade from HiveMQ 4.9.x to HiveMQ 4.28 does not require changes to your configuration file.

HiveMQ Persistent Data Migration

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

Linux example
cp -r /opt/hivemq-4.9.0/data/* /opt/hivemq-4.28.0/data/

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

Upgrade Relevant Changes from HiveMQ 4.9 to 4.28

For your convenience, the following section is a summary of the upgrade guide entries between HiveMQ 4.9 and 4.28.

New Validation Behavior for HiveMQ Configuration File

HiveMQ 4.10 adds an XML Schema Definition (XSD) file that defines the structure HiveMQ uses for validation. The XSD specifies the elements and attributes that can be used in a HiveMQ configuration.

During startup, HiveMQ references the XSD to automatically validate the values that are currently entered in your config.xml file.

If HiveMQ detects one or more invalid values in the configuration file, your HiveMQ deployment does not start.

When a startup fails due to an invalid configuration, HiveMQ logs detailed information about each configuration error to the hivemq.log file. For more information, see Configuration Validation.
To continue the HiveMQ startup, we recommend that you review your log statements and enter valid configuration values where indicated.

In HiveMQ versions 4.9.x and lower, invalid configuration values detected during validation do not prevent HiveMQ startup. In these versions, when an invalid value is detected during startup, HiveMQ automatically uses the HiveMQ default configuration values, continues the startup, and logs a warning.

It is possible to revert to the legacy configuration validation behavior of HiveMQ versions 4.9.x and lower.
For more information, see Change Configuration Validation Behavior

The automatic configuration validation of the HiveMQ broker can impact HiveMQ deployments that you manage with the HiveMQ Kubernetes Operator. For more information, see HiveMQ Kubernetes Operators.

Location Change for HiveMQ Enterprise Extension Configuration Files

To increase consistency and ease of use, the HiveMQ 4.15 platform release unifies the default configuration file location for all HiveMQ Enterprise extensions.

Starting with HiveMQ 4.15, the configuration location for each enterprise extension is conf/config.xml:

  • HiveMQ Enterprise Extension for Kafka: HIVEMQ_HOME/extensions/hivemq-kafka-extension/conf/config.xml

  • HiveMQ Enterprise Security Extension: HIVEMQ_HOME/extensions/hivemq-enterprise-security-extension/conf/config.xml

  • HiveMQ Enterprise Distributed Tracing Extension: HIVEMQ_HOME/extensions/hivemq-distributed-tracing-extension/conf/config.xml

  • HiveMQ Enterprise Bridge Extension: HIVEMQ_HOME/extensions/hivemq-bridge-extension/conf/config.xml

  • HiveMQ Enterprise Extension for Google Cloud Pub/Sub: HIVEMQ_HOME/extensions/hivemq-google-cloud-pubsub-extension/conf/config.xml

HiveMQ platform file structure
└─ <HiveMQ folder>
├── README.txt
├── audit
├── backup
├── bin
├── conf
├── data
├── extensions
│   ├── hivemq-<enterprise-extension-name>
│   │   ├── conf
│   │   │   ├── config.xml (needs to be added by the user)
│   │   │   ├── config.xsd
│   │   │   └── examples
│   │   │       └── config.xml (an example configuration)
│   │   ├── <enterprise-extension-name>.jar
│   │   ├── hivemq-extension.xml
│   │   └── third-party-licenses
│   │
├── license
├── log
├── third-party-licenses
└── tools
The previously-used configuration file locations are still supported, but can be deprecated in future versions. We recommend that you move your existing configurations to the new location.

New Control Center Permissions

HiveMQ 4.19 added the option to hide granular cluster data and active license information in the HiveMQ Control Center. (In this case, aggregated cluster data is shown instead.)

If you currently use the HiveMQ Enterprise Security Extension to restrict access to your control center and you want specific users to continue to have access to such information, you must grant the new permissions to these users.

You can assign one or both of the new permissions to the appropriate users or roles as desired.

Table 1. New control center permissions
Permission Description

HIVEMQ_VIEW_DATA_CLUSTER_NODES

Allows the user to see granular node information.

HIVEMQ_VIEW_DATA_ACTIVE_LICENSE

Allows the user to view active license data.

For more information, see Control Center Access Control Permissions

HiveMQ Container Image Enhancements

File Changes in the 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 HiveMQ 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.

Improved Linux User Handling in the Container Images

The Linux user handling in the hivemq/hivemq4:4.28.0, hivemq/hivemq4:dns-4.28.0, and hivemq/hivemq4:k8s-4.28.0 container images has been improved in the following ways:

  • The Linux user hivemq is no longer available; utilize the numerical user ID 10000 instead.

  • The Linux group hivemq is no longer available.

  • Containers now run as a non-root user with the numerical ID 10000 by default. Previously, containers started as root by default, and stepped down from the root privilege.

  • When you use a FROM hivemq/hivemq4:… command in your Dockerfile to build custom images from the official HiveMQ images, all your commands run with the user 10000. To override the default behavior, you can add a USER 0 command before, and a USER 10000 command after your own commands.

  • If you execute a command in a HiveMQ container (for example, docker exec), the command is executed by user 10000. If you require root permissions, you must explicitly specify the user (for example, docker exec -u 0).

Improved File Permissions in the Container Images

In the hivemq/hivemq4:4.28.0, hivemq/hivemq4:dns-4.28.0, and hivemq/hivemq4:k8s-4.28.0 container images, unnecessary file write and execute permissions have been removed.

Instead of 770 permissions for all files and directories under /opt/hivemq, …

  • Directories now have 750 permissions, except …

    • Directories in which files may be created have 770 permissions, for example /opt/hivemq/extensions.

  • Files now have 640 permissions, except …

    • Files that might be executed have 750 permissions, for example /opt/hivemq/bin/run.sh.

    • Files that might be written to have 660 permissions, for example /opt/hivemq/conf/config.xml.

These changes do not affect operation of HiveMQ when using the official HiveMQ container images. The changes might affect you if you build custom images based on the official HiveMQ images, and you require more permissions on some files inside your Dockerfile. To get access to more file permissions, temporarily change to user 0 with a USER 0 command before, and a USER 10000 command after your own commands.

Availability of unzip in the Container Images

The hivemq/hivemq4:4.28.0 and hivemq/hivemq4:dns-4.28.0 container images no longer have the unzip tool installed.

The unzip tool is still installed in the hivemq/hivemq4:k8s-4.28.0 container image.

When you use a FROM hivemq/hivemq4:… command in your Dockerfile to build custom images from the official HiveMQ images, you cannot use unzip in your RUN commands.

We recommend that you use an additional build stage for any unzip operation and copy over the unzipped files into the final image. For more information, see Multi-stage Docker builds. It is also possible to install the package before your RUN commands.