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
datafolder. 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.
<?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.
<?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.
<?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.
<?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.
<?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:topicis 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|