Configuration

Configuration

HiveMQ is configured with sensible default settings. Therefore most users will find it sufficient to use the default values to get started.

Configuration Files

All configuration files are located in the conf folder of the HiveMQ directory.

HiveMQ uses a simple but powerful XML based configuration.

The config.xml file is read only once during the HiveMQ startup. A HiveMQ restart is required to make changes that were made during runtime take effect.

Default Configuration

HiveMQ is designed to use sensible default values. The default and standard TCP listener binds to all interfaces and port 1883.

HiveMQ Default Config

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

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

Tip	Example Configurations HiveMQ comes with many example configurations to get you started quickly. All example configurations reside in the conf/examples/configuration folder. If you want to use one of the example configurations, copy it to the conf folder and name it config.xml.

Environment variables

In many cases like a containerized environment it can be beneficial or even necessary to configure your ports, bind addresses etc. by setting environment variables on the system HiveMQ runs on.
HiveMQ supports this by providing placeholders which will be replaced with the content of environment variables at the time the configuration file is read.

You can use ${YOUR_ENVVAR_NAME} anywhere in the config.xml file and it will be replaced with the value of the specified environment variable.

Set environment variable

export HIVEMQ_PORT=1883

Use the environment variable in the configuration file

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <listeners>
        <tcp-listener>
            <port>${HIVEMQ_PORT}</port>
        </tcp-listener>
    </listeners>

</hivemq>

For HiveMQ this will result in

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <listeners>
        <tcp-listener>
            <port>1883</port>
        </tcp-listener>
    </listeners>

</hivemq>

Note	Make sure that HiveMQ is started in the same context as your environment variables are set, otherwise HiveMQ will not be able to access the environment variables.

Manually set specific HiveMQ folders

HiveMQ allows manual setting of specific folders for an easier maintenance.

To do so you need to add one or several of the following options to your bin/run.sh file.

JAVA_OPTS="$JAVA_OPTS -D...=/your/folder/here"

Alternatively you can define environment variables.

export ...=/your/folder/here

If both a Java option and environment variable are set for the same folder, the value of the Java option is used.

Table 1. Folder Configuration Options

Java Option	Environment Variable	Affected folder
hivemq.home	HIVEMQ_HOME	Base folder (bin needs to be a sub folder of this folder)
hivemq.log.folder	HIVEMQ_LOG_FOLDER	Log files folder
hivemq.config.folder	HIVEMQ_CONFIG_FOLDER	Configuration files folder
hivemq.extensions.folder	HIVEMQ_EXTENSION_FOLDER	Extension binaries folder
hivemq.data.folder	HIVEMQ_DATA_FOLDER	HiveMQ data folder

Example for Java option:

JAVA_OPTS="$JAVA_OPTS -Dhivemq.home=/mqtt/broker/hivemq"

Example for environment variable:

export HIVEMQ_HOME=/mqtt/broker/hivemq

Sets the HiveMQ home folder to /mqtt/broker/hivemq.

In-memory Persistence

HiveMQ can be configured to store persistent data in-memory. This is useful on systems with very limited disk space or when disk input/output (I/O) must be limited.

Note	Operations such as reading the config.xml and writing logs always require disk I/O operations. The In-memory Persistence setting does not affect these operations.

In-memory Persistence stores the following persistent data in memory:

• Client session information

• Queued messages

• Will messages

• Retained messages

• Subscriptions

Note	When HiveMQ is stopped, data that is stored in-memory is lost.

Configuration

Setting the persistence property

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <persistence>
        <mode>in-memory</mode>
    </persistence>
    ...

</hivemq>

IPv6

IPv6 is an internet protocol standard and the successor of the established IPv4. Since the standardization in 1998 the usage is continuously increasing.

With some small touches HiveMQ is able to operate, using IPv6. Here is a guide to using IPv6 for our more experimental users.

Warning

Running HiveMQ with IPv6 in a production environment is currently not supported.

Necessary changes

HiveMQ uses IPv4 addresses by default. This setting can be changed in the run-script:

#Stop preferring IPv4 addresses
JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv4Stack=false"

#Prefer IPv6 addresses
JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv6Addresses=true"

The bind-address in your config needs to be configured with an IPv6 address:

config.xml

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <listeners>
        <tcp-listener>
            <port>1883</port>
            <!-- '::' instead of 0.0.0.0 -->
            <bind-address>::</bind-address>
        </tcp-listener>
    </listeners>

</hivemq>

Available listeners with IPv6

Listeners	Status
TCP	yes
TLS	? [1]
WebSocket	yes
Secure WebSocket	? [1]

Special-use addresses for IPv6

Table 2. IPv6 special-use addresses

Special-use addresses	IPv4	IPv6 counterpart
Any	0.0.0.0	::
Loopback	127.0.0.1	::1
Default multicast	228.8.8.8	ff0e::8:8:8

---

1. No MQTT Client Library available for testing this feature with IPv6