4.4.x to 4.5.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.5 is a drop in replacement for HiveMQ 4.4.x. Read about the new features and the release cadence in this Release Blogpost

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

Upgrade a HiveMQ Cluster

Rolling upgrades are supported and it is possible to run HiveMQ version 4.4 and version 4.5 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.4.x installation folder from which you want to migrate

  • Install HiveMQ 4.5 as described in the HiveMQ Installation Guide

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

Configuration File Changes

You can upgrade from HiveMQ 4.4.x to HiveMQ 4.5 without making changes to your configuration file.

Persistent Data Migration

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

Linux example
cp -r /opt/hivemq-4.4.5/data/* /opt/hivemq-4.5.0/data/

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

Default Authentication Behaviour

Since version 4.3, HiveMQ only allows MQTT clients to connect if a security extension is present. For testing purposes, HiveMQ includes a hivemq-allow-all-extension that authorizes all MQTT clients to connect to HiveMQ. Before you use HiveMQ in production, you must add an appropriate security extension and remove the hivemq-allow-all-extension. You can download security extensions from the HiveMQ Marketplace or develop your own security extension.

TLS changes

HiveMQ 4.5 has TLSv1.3 additionally enabled as default protocol for TLS between client and server. The default protocols are overwritten when any TLS protocol is set manually. For more Information on TLS, please take a look at the HiveMQ Security Guide. The previous behavior can be achieved by explicitly setting the protocols in the following way:

Configuring the previous TLS settings
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    ...
    <listeners>
        ...
        <tls-tcp-listener>
            <tls>
                ...
                <!-- Enable only TLS 1.2 and TLS 1.1 manually -->
                <protocols>
                    <protocol>TLSv1.2</protocol>
                    <protocol>TLSv1.1</protocol>
                </protocols>
                ...
            </tls>
        </tls-tcp-listener>
    </listeners>
    ...
</hivemq>