4.14.x to 4.15.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.15 is a drop in replacement for HiveMQ 4.14.x.

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

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

Upgrade a HiveMQ Cluster

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

  • Install HiveMQ 4.15 as described in the HiveMQ Installation Guide

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

Configuration File Changes

You can upgrade from HiveMQ 4.14.x to HiveMQ 4.15 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.15 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.14.x installation to the data folder of your new HiveMQ 4.15 installation.

Linux example
cp -r /opt/hivemq-4.14.0/data/* /opt/hivemq-4.15.0/data/

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

Native SSL Default Communication Protocols

Due to security concerns, the OpenJDK Java platform no longer enables TLSv1 and TLSv1.1 by default. As a result, Java applications such as HiveMQ that use TLS to communicate now require TLS 1.2 or above to establish a connection.

To align with the OpenJDK Java platform, from HiveMQ 4.7 onwards, HiveMQ only enables the following TLS protocols by default for native SSL:

  • TLSv1.3

  • TLSv1.2

If you still need to support legacy TLS versions such as TLSv1 or TLSv1.1 for your Native SSL implementation, you must explicitly enable the versions in your tls-tcp-listener configuration. For more information, see Communication Protocol and Native SSL.
Example configuration for native SSL with explicit legacy TLS configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <listeners>
        ...
        <tls-tcp-listener>
            <tls>
                ...
                <!-- Enable specific TLS versions manually -->
                <protocols>
                    <protocol>TLSv1.1</protocol>
                </protocols>
                <native-ssl>true</native-ssl>
                ...
            </tls>
        </tls-tcp-listener>
    </listeners>
    ...
</hivemq>

New Validation Behavior for HiveMQ Configuration File

Since HiveMQ 4.10, HiveMQ automatically validates the values that are currently entered in your config.xml file during startup.

HiveMQ 4.10 added 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.

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 configuration validation behavior of HiveMQ versions 4.9.x and lower.
You can enable the legacy startup validation behavior in two ways:

  • Add a line with the following Java system property to your bin/run.sh file: : JAVA_OPTS="$JAVA_OPTS -Dhivemq.config.skip-validation=true" -or-

  • Provide the environment variable: export HIVEMQ_SKIP_CONFIG_VALIDATION=true

For more information, see Change Configuration Validation Behavior

The new configuration validation of the HiveMQ broker can impact HiveMQ deployments that you manage with the HiveMQ Kubernetes Operator. For more information, see HiveMQ Kubernetes Operator - Configure Your HiveMQ Cluster.

New Location 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 Extension for Amazon Kinesis: HIVEMQ_HOME/extensions/hivemq-amazon-kinesis-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.