4.16.x to 4.17.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.17 is a drop in replacement for HiveMQ 4.16.x.

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

HiveMQ is prepackaged with multiple 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).

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.16 and version 4.17 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.16.x installation folder from which you want to migrate

  • Install HiveMQ 4.17 as described in the HiveMQ Installation Guide

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

Configuration File Changes

You can upgrade from HiveMQ 4.16.x to HiveMQ 4.17 without making changes to your configuration file.

Since 4.10.0, HiveMQ prevents the startup if your configuration file contains invalid values. For more information, see New Validation Behavior for HiveMQ Configuration File.

Persistent Data Migration

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

Linux example
cp -r /opt/hivemq-4.16.0/data/* /opt/hivemq-4.17.0/data/

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

License Change for the HiveMQ Data Hub

HiveMQ version 4.17 introduces a flexible new licensing model for the HiveMQ Data Hub that uses a dedictated license.

The new model makes it easier to handle Data Hub licenses since the Data Hub License can be added to any deployment without the necessity to touch your HiveMQ broker license.

If you currently use the closed beta version of the HiveMQ Data Hub, the special HiveMQ broker license (file ending lic) is no longer valid for use with the Data Hub. All participants in the HiveMQ Data Hub closed beta must update to the new .plic license file. If you are a member of the closed beta and have not yet received a replacement license file from you account representative, contact our sales team for assistance.

Additionally, starting with HiveMQ version 4.17, a free version of the Data Hub is included in the HiveMQ Platform bundle. The free mode of the Data Hub allows you to create one policy and gives you access to limited functionality.

The licensed versions provide all available functionality and allow you to create different numbers of policies according to the terms of the license. All dedicated Data Hub licenses use the file extension .plic.

HiveMQ Data Hub license
└─ <HiveMQ folder>
├── README.txt
├── audit
├── backup
├── bin
├── conf
├── data
├── extensions
├── license
│   ├── broker.lic
│   └── data-hub.plic
├── log
├── third-party-licenses
└── tools