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
datafolder. 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.
<?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>
<?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.
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.
<?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.
<?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.
<?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
-
The syntax
$share:group:topicis longer valid. All shared subscriptions must now follow the syntax$share/group/topic -
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.
HiveMQ Metric Changes
The following HiveMQ metrics have been renamed or removed. These changes need to be considered in your HiveMQ Monitoring, when moving from HiveMQ 3.x to HiveMQ 4.x.
| HiveMQ 3 Metric | HiveMQ 4 metric |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|