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 file contents of your old HiveMQ installation

  • Delete all contents in the data folder. This will delete all persistent data of HiveMQ 3.x.

HiveMQ 3 licenses

HiveMQ 3 licenses, which have valid software and support subscriptions, can also be seamlessly used with HiveMQ 4.

Configuration File Upgrade

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

Changed Configuration Options

HiveMQ 4 comes with a number of changes to the configuration file, as listed below.

HiveMQ Control Center

The HiveMQ Web UI has been renamed HiveMQ Control Center. <web-ui> changed to <control-center> accordingly in the configuration options. See the Control Center Guide for details about possible configuration options.

Example HiveMQ Control Center Config
<?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.

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

Replication

HiveMQ 4 still allows the configuring of the replica count as part of the <cluster> configuration. Please note that <replication-count> changed to <replica-count> and there has been a change in how HiveMQ counts replications. Your replica count needs to be one more than the replication count used to be in order to achieve the same replication.
More details can be found in the replication chapter of the user guide.
Below is an example, showing the necessary changes if your HiveMQ 3 setting was <replication-count>1</replication-count>

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 following new configuration options for MQTT.
See the MQTT Specific Configuration Options chapter in the user guide for details.

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.
See the Security Configuration Options chapter in the user guide for details.

Security Config
<?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>.
See the restrictions chapter in the user guide for details.

Restriction Config
<?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, when using Extension Discovery, has been removed. HiveMQ 4 Extensions should be developed with that in mind and offer a configuration option for the extension reload interval. For the official pre-built extensions for HiveMQ 4 this is true.

Extension System Upgrade

HiveMQ 4 comes with a completely re-worked Extension System.
Existing HiveMQ Extensions for HiveMQ 3 need to be re-written with the new Extension System.
Check the Extension Developer Guide for details.
In case you have any questions regarding the migration of a HiveMQ Extension from HiveMQ 3 to 4, feel free to contact support@hivemq.com.

Shared Subscriptions

There have been slight changes in regards to Shared Subscriptions

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

  2. If a client has overlapping shared subscriptions (e.g. $share/group/topic and $share/group/#) these subscriptions will be handled by the broker individually. Consequently it is possible that single shared subscribers receives a PUBLISH more than once if it matches more than one of its shared subscriptions.