3.x.x to 4.0.x Migration Guide

This is a major HiveMQ upgrade. HiveMQ 4.0 comes with many new features and improvements and is the first HiveMQ version that is 100% compliant with MQTT version 5.0.
HiveMQ 4.0 is not compatible with any earlier HiveMQ version and is not a drop in replacement.

We strongly recommend that you upgrade to the latest version of HiveMQ. Since HiveMQ 3.4.4, you can export a convenient migration file from the Web UI of HiveMQ 3.4.4 and import into HiveMQ 4.2.1 or higher. For more information, see Migrate from HiveMQ 3 to HiveMQ 4.

HiveMQ Upgrade

  • Install Open JDK 11 or newer

  • Install HiveMQ 4 as described in the HiveMQ Installation Guide

  • Migrate the configuration files of your HiveMQ 3 installation to your new HiveMQ 4 instance.

  • Delete all content in the data folder. This action deletes all persistent data of HiveMQ 3.x.

HiveMQ 3 licenses

HiveMQ 3 licenses that have valid software and support subscriptions can be seamlessly migrated to HiveMQ 4.

Configuration File Upgrade

Manual steps are required to upgrade the configuration file of HiveMQ 3.x.x to HiveMQ 4.0.

Configuration File Changes

HiveMQ 4 introduces the following changes to the HiveMQ configuration file:

HiveMQ Control Center

In HiveMQ 4 the HiveMQ Web UI is renamed to HiveMQ Control Center.

In all HiveMQ 4 configuration options, the label <web-ui> changes to <control-center>.
See the Control Center Guide for details about possible configuration options.

Example HiveMQ Control Center Configuration
<?xml version="1.0"?>
 <hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...
   <control-center>
       <enabled>true</enabled>
    ...
   </control-center>
    ...
</hivemq>

Persistence

HiveMQ 4 removes the <persistences> configuration.

<mode>in-memory</mode> is no longer a configuration option. HiveMQ 4 always uses file persistence.

Replication

In your HiveMQ 4 <cluster> configuration, <replication-count> changes to <replica-count> and there is a change in how HiveMQ counts replicas.

To maintain your current level of replication, your new replica count setting must be one value higher than your previous HiveMQ 3 replication count.
For more information, see Cluster Replicas.

The following example shows how to configure HiveMQ 4 to maintain the same replication level as a HiveMQ 3 instance with a <replication-count>1</replication-count> setting.

Example Replication Count Configuration
 <?xml version="1.0"?>
 <hivemq>
    ...
    <cluster>
    ...
        <replication>
            <replica-count>2</replica-count>
        </replication>
     ...
     </cluster>
    ...
 </hivemq>

Listener Configuration

HiveMQ 4 removes the <client-ip> and <client-address> configuration options from all listeners.

MQTT-Specific Configuration Options

HiveMQ 4 supports all MQTT 5 features and provides several new configuration options for MQTT.
For more information, see MQTT Specific Configuration Options.

In compliance with the MQTT 5 specification, HiveMQ 4 removes the <retry-interval> setting from the <mqtt> configuration.
When a client reconnects with a Clean Start setting of 0 and a session is present, both the client and server MUST resend any unacknowledged PUBLISH packets (where QoS > 0) and PUBREL packets using their original packet identifiers.
This is the only circumstance where a client or server is REQUIRED to resend messages. Clients and servers MUST NOT resend messages at any other time.

Additionally, HiveMQ 4 removes the <client-session-ttl>, <publish-ttl>, and <retained-publish-ttl> settings from the <mqtt> configuration. MQTT 5 session-expiry and message-expiry now handle this functionality.

Example MQTT Configuration
<?xml version="1.0"?>
<hivemq>
   ...
    <mqtt>

       <queued-messages>
           <max-queue-size>1000</max-queue-size>
           <strategy>discard</strategy>
       </queued-messages>

       <topic-alias>
           <enabled>true</enabled>
           <max-per-client>5</max-per-client>
       </topic-alias>

       <message-expiry>
           <max-interval>4294967296</max-interval> <!-- this value means no message expiry -->
       </message-expiry>

       <session-expiry>
           <max-interval>4294967295</max-interval> <!-- ~ 130 years -->
       </session-expiry>

       <keep-alive>
           <allow-unlimited>true</allow-unlimited>
           <max-keep-alive>65535</max-keep-alive>
       </keep-alive>

       <packets>
           <max-packet-size>268435460</max-packet-size> <!-- 256 MB -->
       </packets>

       <receive-maximum>
           <server-receive-maximum>10</server-receive-maximum>
       </receive-maximum>

       <quality-of-service>
           <max-qos>2</max-qos>
       </quality-of-service>

       <wildcard-subscriptions>
           <enabled>true</enabled>
       </wildcard-subscriptions>

       <shared-subscriptions>
           <enabled>true</enabled>
       </shared-subscriptions>

       <subscription-identifier>
           <enabled>true</enabled>
       </subscription-identifier>

       <retained-messages>
           <enabled>true</enabled>
       </retained-messages>

   </mqtt>
   ...
</hivemq>

HiveMQ 4 also supports MQTT all the new security-relevant configuration options that MQTT 5 introduces.
For more information, see Configuration Options.

Example Security Configuration
<?xml version="1.0"?>
<hivemq>
   ...
   <security>

      <payload-format-validation>
          <enabled>false</enabled>
      </payload-format-validation>

      <utf8-validation>
          <enabled>true</enabled>
      </utf8-validation>

      <allow-empty-client-id>
          <enabled>true</enabled>
      </allow-empty-client-id>

       <allow-request-problem-information>
           <enabled>true</enabled>
       </allow-request-problem-information>

   </security>
   ...
</hivemq>

Restrictions Configuration

HveMQ 4 changes the name of the <throttling> configuration section to <restrictions> and removes the [.line-through]# <plugin-service-limit> # tag.
For more information, see Restrictions.

Example Restriction Configuration
<?xml version="1.0"?>
<hivemq>
  ....
   <restrictions>
       <max-connections>-1</max-connections>
       <max-client-id-length>65535</max-client-id-length>
       <no-connect-idle-timeout>10000</no-connect-idle-timeout>
       <incoming-bandwidth-throttling>0</incoming-bandwidth-throttling>
   </restrictions>
  ...
</hivemq>

Extension Discovery Interval

Starting with HiveMQ 4, plugins are referred to as extensions.

HiveMQ 4 removes the <reload-interval> configuration option for extension discovery.

When you develop HiveMQ 4 extensions, we recommend that you include a configuration option for the extension reload interval. All official pre-built extensions for HiveMQ 4 include the option to configure the extension reload interval by default.

Extension System Upgrade

HiveMQ 4 ships with a completely reworked extension system.
Existing HiveMQ extensions for HiveMQ 3 must be rewritten with the new extension system.

If you have questions about your migration of a HiveMQ extension from HiveMQ 3 to 4, feel free to contact support@hivemq.com.

Shared Subscriptions

HiveMQ 4 introduces significant changes to Shared Subscriptions

  • The syntax $share:group:topic is no longer valid. All shared subscriptions must now follow the syntax $share/group/topic

  • If a client has overlapping shared subscriptions (for example, $share/group/topic and $share/group/#), HiveMQ 4 handles each subscription individually.
    In cases where a PUBLISH message matches multiple shared subscriptions of a single shared subscriber, the subscriber can receive the PUBLISH message more than once.

HiveMQ Metric Changes

HiveMQ 4 removes or renames the following metrics.

Metric changes can impact your HiveMQ monitoring.
Be sure to adjust your monitoring as needed when you migrate from HiveMQ 3.x to HiveMQ 4.x.
HiveMQ 3 Metric HiveMQ 4 Metric

com.hivemq.plugin.executor.*

com.hivemq.extensions.managed-executor.*

com.hivemq.web-ui.executor.*

com.hivemq.control-center.executor.*

com.hivemq.messages.dropped.qos-0-queue-not-empty.count

-

com.hivemq.clients.half-full-queue.count

-

com.hivemq.messages.dropped.not-connected.count

-

com.hivemq.messages.dropped.in-flight-window.count

-

com.hivemq.messages.dropped.before-publish-send.count

-

com.hivemq.plugin.callbacks.ping.time

-

com.hivemq.plugin.callbacks.session-ready.time

-

com.hivemq.queues.publish.size

-

com.hivemq.queues.publish.rate

-

com.hivemq.persistence.executor.outgoing-message-flow.tasks

-

com.hivemq.persistence.executor.client-group.tasks

-

com.hivemq.persistence.executor.client-group.tasks

-

com.hivemq.persistence.executor.nonempty-queues

-

com.hivemq.persistence.executor.outgoing-message-flow.time

-

com.hivemq.persistence.executor.client-group.time

-

com.hivemq.direct-memory.used

-