Troubleshooting HiveMQ

General Information

HiveMQ has different configuration settings based on which version one is running. Please be sure to refer to the proper documentation for the version you are using/troubleshooting on the website.

Installation

Download and install HiveMQ per their instructions for your operating system at their website https://www.hivemq.com. General installation is straightforward, unzip the download and run the appropriate bash/bat file to start it up.

If running on a Raspberry Pi, you may have to install other dependencies, such as the Java runtime
By default, HiveMQ allows anonymous connections on all interfaces on port 1883

Running HiveMQ

Out of the box, the web interface for HiveMQ listens at port 8080. If you are running it on a machine with something else already listening on that port, you can change the port that HiveMQ uses so that they may co-exist peacefully.

The setup for config file varies depending on which version of HiveMQ one is using, i.e. it differs from 3.4 to the 4.3 that I am referencing for this writeup. If the version of HiveMQ installed is an early version, refer to the documentation on their website.

In the directory where you unzipped HiveMQ, navigate to the “conf” directory. The configuration file we want to edit to change the port of HiveMQ web interface is “config.xml”. Open it up in an editor of your choice. A plain out-of-the-box config file should appear as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="config.xsd">

    <listeners>
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
        </tcp-listener>
    </listeners>

    <anonymous-usage-statistics>
        <enabled>true</enabled>
    </anonymous-usage-statistics>

</hivemq>

In order to change the listening port (and bind address if you wish), add the “control-center” section and edit the config file to appear as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="config.xsd">

    <listeners>
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
        </tcp-listener>
    </listeners>

    <control-center>
        <enabled>true</enabled>
        <listeners>
            <http>
                <port>9090</port>
                <bind-address>localhost</bind-address>
            </http>
        </listeners>
    </control-center>
	
    <anonymous-usage-statistics>
        <enabled>true</enabled>
    </anonymous-usage-statistics>

</hivemq>

Re-start HiveMQ to see the changes.

Disconnects on large packets sent by MQTT

A client was having issues with disconnects after attempting to send backfill messages on the order of ~120kb. The QA team was able to replicate the behavior on our end by configuring a test HiveMQ broker to only accept small packets.

Some general information regarding MQTT and HiveMQ are as follows:

The MQTT specification for maximum message size is stated at 256MB.
According to the HiveMQ website, the broker does support the size
One can set limits within the configuration for HiveMQ to further restrict max by editing the config.xml file. Doing such is covered in a subsequent section of this document.

Adjusting maximum packet size for the broker

Using your editor of choice, open up the file “config.xml” file in the “conf” directory. Add the “mqtt” block, save the file and restart the broker. An example config file with a 20k maximum message size is as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="config.xsd">

    <listeners>
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
        </tcp-listener>
    </listeners>

    <control-center>
        <enabled>true</enabled>
        <listeners>
            <http>
                <port>9090</port>
                <bind-address>localhost</bind-address>
            </http>
        </listeners>
    </control-center>
    
    <mqtt>
        <packets>
            <max-packet-size>20000</max-packet-size>
        </packets>
    </mqtt>

    <anonymous-usage-statistics>
        <enabled>true</enabled>
    </anonymous-usage-statistics>

</hivemq>

With the value set low, one should see messages from the Sparkplug logs similar to the following:

If the value for size is set large enough to allow through all packets, one should see logs as follows:

Extensions

HiveMQ has an extensive list of extensions for the broker on their website. If the client is having issues, one should inquire as to what extensions they are utilizing.

Cloud hosting

When hosting HiveMQ on the cloud, there may be other limitations that one cannot control, such as the ones outlined on this page.