HiveMQ 4.56.x to 4.57.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.57 changes the JSON payload of the Client Lifecycle Topic add-on. HiveMQ 4.57 also changes the TLS behavior of HiveMQ, the HiveMQ Enterprise Bridge Extension, and the HiveMQ Enterprise Security Extension. Review the upgrade-relevant changes before you upgrade.

You can learn more about all the new features HiveMQ 4.57 introduces in the HiveMQ release notes.

The HiveMQ software bundle 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.

HiveMQ 4.55 is the current HiveMQ LTS (Long Term Support) release. The previous 4.28.x LTS release is supported through February 2027. To upgrade from the previous 4.28 LTS to HiveMQ 4.57, you must first upgrade to the 4.55 LTS version.
For more information, see HiveMQ Rolling Upgrade Policy
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.
Note changes that are relevant to your use case and adjust your configuration as needed.

Changes to Review Before You Upgrade to HiveMQ 4.57 from HiveMQ 4.56

HiveMQ 4.57 renames the fields of the Client Lifecycle Topic payload. Review your consumers of the $client-events topics before you upgrade. HiveMQ 4.57 also validates TLS certificate files, keystores, and truststores at startup. Review your TLS configurations before you upgrade.

Client Lifecycle Topic Payload Field Names

HiveMQ 4.56 introduced the Client Lifecycle Topic add-on. The field names of its JSON payload contained spaces and punctuation, which made the fields hard to access in most JSON tools.

HiveMQ 4.57 renames all fields to camelCase, consistent with the HiveMQ REST API. Field values, topics, and the conditions that determine when a field is present do not change.

Table 1. Client Lifecycle Topic payload field names in HiveMQ 4.56 and HiveMQ 4.57
HiveMQ 4.56 HiveMQ 4.57

Event type

eventType

Disconnect initiator

disconnectInitiator

Disconnect reason code

disconnectReasonCode

Timestamp

timestamp

Time elapsed since connect

timeElapsedSinceConnect

Client IP address

sourceIp

Client ID

clientId

Was client ID broker-assigned?

clientIdBrokerAssigned

Node IP address

nodeIp

Listener port

listenerPort

Is secure connection?

tlsConnection

MQTT protocol version

mqttVersion

MQTT username

username

TLS: Common Name

certificateCommonName

TLS: Subject Alternative Name

certificateSubjectAlternativeNames

Before you upgrade to HiveMQ 4.57, prepare every consumer of the $client-events topics for the new camelCase field names. Consumers include MQTT subscribers, scripts, dashboards, and pipelines that use the HiveMQ Enterprise Extension for Kafka.

After the upgrade, consumers that ignore unknown fields do not report an error. These consumers look for old field names that no longer exist and receive empty values without warning. To prevent incorrect results, check each consumer for references to the HiveMQ 4.56 field names.
During a rolling upgrade of a HiveMQ cluster, each cluster node publishes the events of the clients that are connected to that node. Until all nodes run HiveMQ 4.57, a subscriber can receive events with the HiveMQ 4.56 field names and events with the HiveMQ 4.57 field names on the same subscription. If your consumers must process events without interruption during the rolling upgrade, configure them to accept both sets of field names. For example, read eventType and fall back to Event type when eventType is absent.

PEM Certificate File Validation in HiveMQ and the HiveMQ Enterprise Bridge Extension

HiveMQ 4.57 and the HiveMQ Enterprise Bridge Extension no longer accept some PEM files that HiveMQ 4.56 accepted. If a configuration contains one of the following files, HiveMQ or the extension does not start:

  • A private key file with more than one private key: HiveMQ 4.56 used the first private key in the file.

  • A certificate file with a BEGIN TRUSTED CERTIFICATE block: This block contains OpenSSL trust settings. HiveMQ 4.56 skipped the block and its certificate.

Before you upgrade:

  • Make sure that each private key file contains exactly one private key.

  • Convert each trusted certificate to a plain certificate. For example, with openssl x509 -in trusted.pem -out certificate.pem.

Keystore and Truststore Validation in the HiveMQ Enterprise Bridge Extension

HiveMQ 4.57 changes how the HiveMQ Enterprise Bridge Extension reads the keystore and truststore files of a bridge:

  • File names: The extension reads JKS and PKCS #12 files with any file name. HiveMQ 4.56 ignored files with names that did not end in .jks or .p12 and connected the bridge without them.

  • Unreadable files: If the extension cannot read a keystore or truststore file, the extension does not start. HiveMQ 4.56 ignored an unreadable PKCS #12 file and connected the bridge without it.

  • Truststore passwords: If a JKS truststore has a password, you must set the password element. HiveMQ 4.56 did not require this element.

Before you upgrade:

  • Make sure that the extension can open each keystore and truststore file.

  • For each truststore that has a password, add the password element.

TLS Changes for SQL Realms in the HiveMQ Enterprise Security Extension

HiveMQ 4.57 changes the TLS behavior of SQL realms in the HiveMQ Enterprise Security Extension (ESE). The first two changes do not apply to realms that use MySQL Connector/J:

  • Startup validation: The ESE now reads the keystore, truststore, and PEM files of an SQL realm when the extension starts. If a file is missing or unreadable, or a password is incorrect, the ESE does not start. HiveMQ 4.56 loaded the files each time a realm opened a database connection.

  • Hostname verification: The ESE now uses the hostname verification of the Java Runtime Environment. The extension compares the db-host value with the subject alternative names (SANs) of the server certificate. The ESE uses the common name (CN) only if the certificate contains no DNS names. HiveMQ 4.56 used the hostname verification of the JDBC driver.

  • Microsoft SQL Server and Azure SQL: If verifyHostname is set to false, these realms no longer verify the hostname. HiveMQ 4.56 ignored this setting and always verified the hostname.

  • MySQL and MariaDB with the included MariaDB driver: The private-key-password must decrypt all private keys in the keystore. Otherwise, the ESE does not start. If the private-key-password was wrong, HiveMQ 4.56 connected without a client certificate.

  • PostgreSQL without a keystore: These realms now use the keystore that is configured for your system (javax.net.ssl.keyStore), as MySQL and MariaDB realms already do. HiveMQ 4.56 sent no client certificate for these realms.

  • MySQL Connector/J before 8.0.13: If TLS is configured and the database server does not offer TLS, these SQL realms cannot connect. HiveMQ 4.56 connected to such a server without TLS.

Before you upgrade:

  • Make sure that the certificate of each database server lists the configured db-host value.

  • Make sure that the ESE can open each keystore, truststore, and PEM file with the configured passwords.

OIDC Realm Keystore Validation in the HiveMQ Enterprise Security Extension

The ESE now loads the keystore of an OIDC realm with tls-client-auth or private-key-jwt when the extension starts. The ESE does not start in the following cases:

  • The keystore is missing or unreadable.

  • A password is incorrect.

  • The keystore-entry-alias does not exist in the keystore.

  • For tls-client-auth: The private-key-password cannot decrypt all private keys in the keystore.

HiveMQ 4.56 loaded the keystore at the first Control Center login. If the keystore had one of these problems, the login failed.

Before you upgrade:

  • Make sure that the ESE can open the configured keystore and its private keys with the configured passwords.

Known Issues

HiveMQ 4.57 has no known issues.

Upgrade a HiveMQ Cluster

Rolling upgrades are supported, and it is possible to run HiveMQ version 4.56 and version 4.57 simultaneously in the same cluster. By default, the HiveMQ cluster enables all new cluster features once 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.

Upgrade a Single-node HiveMQ Instance

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

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

  • Migrate the content of the config.xml and license files from your old HiveMQ 4.56.x installation. For more information, see HiveMQ Configuration File Changes.

  • To migrate your persistent data, copy everything from the data folder of your backup to the data folder of the new HiveMQ 4.57 installation.

HiveMQ Configuration File Changes

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

HiveMQ Persistent Data Migration

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

Linux example
cp -r /opt/hivemq-4.56.0/data/* /opt/hivemq-4.57.0/data/

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