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.

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.

Changed Configuration Options

HiveMQ 4 contains the following changes to the configuration file:

HiveMQ Control Center

The HiveMQ Web UI is now called HiveMQ Control Center.
<web-ui> changes to <control-center> in all HiveMQ configuration options.
For more information, see Control Center Configuration.

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

The <persistences> configuration has been removed.

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

Replication

In the 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

The <client-ip> and <client-address> configuration options have been removed from all listeners.

MQTT Configuration

HiveMQ 4 supports all MQTT 5 features and provides the 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 <replication-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.

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>

In addition to these MQTT settings, MQTT 5 offers a variety of security relevant configuration options.
For more information, see Security 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

<throttling> configuration options changed to <restrictions>.
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

The <reload-interval> configuration option for extension discovery has been removed.
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.
For more information, see Extension Developer Guide.
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

The following HiveMQ metrics have been renamed or removed. 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

-