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 3 licenses, which have valid software and support subscriptions, can also be seamlessly used with HiveMQ 4.
|Manual steps are required for upgrading the configuration file of HiveMQ 3.x.x to HiveMQ 4.0.|
HiveMQ 4 comes with a number of changes to the configuration file, as listed below.
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>
<persistences> configuration has been removed.
HiveMQ 4 still allows the configuring of the replica count as part of the
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
<?xml version="1.0"?> <hivemq> ... <cluster> ... <replication> <replica-count>2</replica-count> </replication> ... </cluster> ... </hivemq>
<client-address> configuration options have been removed from all listeners.
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.
<?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>
<throttling> configuration options changed to
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>
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 firstname.lastname@example.org.
There have been slight changes in regards to Shared Subscriptions
$share:group:topicis longer valid. All shared subscriptions must now follow the syntax
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.