Configuration (HiveMQ 3.4)

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

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

When using IPv6 some restrictions in terms of cluster discovery apply. The following lists the availability for each of the possible HiveMQ cluster discovery options:

The MQTT specification 3.1.1 allows client identifier lengths up to 65535 bytes.

Most applications don’t need to have such long client identifiers, so it may be useful to restrict client identifier lengths to your use case.

The following examples shows how to change the maximum client identifier length limit:

If a client uses a client identifier with more bytes in the CONNECT message, HiveMQ will reject the connection with a Connection Refused, identifier rejected error code.

MQTT systems implement the Quality of Service 1 guarantees with a two-way and the Quality of Service 2 guarantees with a four way message flow. We recommend to read this blog post if you’re interested in the details how Quality of Service Flows work. The broker (as well as the client) is required to re-send a message if it never received an acknowledgement for a particular message in the quality of service flow.

HiveMQ by default does not retry to send a message.

If you are dealing with very unreliable networks and very high latency on a regular basis, it may be useful to resend messages, in case an acknowledgement takes up a large amount of time.

The following example shows how to set a retry interval:

MQTT, as layer 7 protocol in the OSI layer model, relies on TCP and so it’s required for clients to open a TCP connection before they can send a MQTT CONNECT message to initiate the MQTT connection.

The fact that MQTT operates at application layer means that just because a client initiates a TCP connection, doesn’t necessarily mean that it initiates a MQTT connection. So malicious MQTT clients could drain server resources by opening a TCP connection and never initiating a MQTT connection by sending a MQTT CONNECT message. These kind of clients can attack your MQTT broker by draining all system resources (like memory) quickly.

To avoid these kind of attacks, it’s important that you disconnect clients which don’t initiate a MQTT connection as soon as possible.

HiveMQ by default waits 10 seconds for the CONNECT message of a client before it closes an open TCP socket. You can tune this behaviour to your application needs.

The MQTT specification states that topics must be treated as Ordered Topics. Ordered topics guarantee, that each QoS 1 or 2 message flow for a specific topic finishes before the next QoS message flow starts. That means that it is guaranteed that all QoS 1 and 2 messages are delivered in order.

HiveMQ treats all topics which are subscribed by a specific client as Ordered Topics.

This also means, that HiveMQ will queue QoS 1 and 2 messages which can’t get delivered immediately to a client because another message flow for the topic is in progress. If the client consumes messages slower than new matching messages are received by HiveMQ, these new messages will queue up for that specific client. Because this can drain system resources (memory) quickly, HiveMQ will discard messages if the configured max-queued-messages limit is exceeded for a specific client.

The queued message limit is the limit for all queued messages of an individual client, independent of the number of concrete topics the client subscribed to.

The following example sets a lower queued in-flight message limit:

The utf8-validation value defines whether or not the broker will check UTF-8 validity for topic names and client ids. By default UF8-8 validation is enabled.

HiveMQ allows the configuration of an amount of time after which a certain type of data expires. A general time to live for each type can be set in the config.xml. It may be overwritten by plugins for a more specific configuration. These configurations can help to free up some resources like disk memory or RAM. In scenarios where a type of data (i.e. retained messages) is no longer useful after an extended period of time, it is recommended to configure an appropriate time to live. Setting a time to live may also protect the broker from unexpected client behaviour. For example if data is stored for a client ID or a topic, that is not reused or removed by a client, it will be stored indefinitely if no time to live is configured.

The client session time to live only applies to clients that connected with clean session = false. It describes the amount of time (in seconds), that has to pass since the client disconnected, before its session expires. In case the client (same client ID) reconnects with clean session = false before the time to live ends, the timer is reset. All subscriptions, queued messages and unfinished message transmissions associated with the session are removed on expiration. By default the client session time to live is set to -1 which is treated as unlimited, therefore the session will never expire. The maximum value for client session time to live is 2147483647.

The publish message time to live describes the amount of time (in seconds), that has to pass since the publish message arrived at the broker, before it expires. An expired publish message is never published. Not publishing due to expiry can happen in the following cases:

By default the publish message time to live is set to -1 which is treated as unlimited, therefore the publish message will never expire. Max value of publish message time to live is 2147483647.

The retained message time to live describes the amount of time (in seconds), that has to pass since the retained message arrived at the broker, before it expires. An expired retained message is never published. Not publishing due to expiry can happen in the following cases:

By default the retained message time to live is set to -1 which is treated as unlimited, therefore the retained message will never expire. Max value of retained message time to live is 2147483647.

The HiveMQ Persistence Subsystem consists of the following components which can be configured separately:

By default, all persistence stores are backed by the file system of the machine HiveMQ is running on. So even if HiveMQ stops or restarts no state is lost and after restarting the broker, all clients keep their persistent sessions, all queued messages for offline persistent clients are preserved, MQTT message flows can resume and retained messages are available.

HiveMQ has various mechanisms to get maximum write and read performance but in the end the performance for persisting data is I/O bound. So if you experience that disk reads and write are too slow, using better hardware (like SSDs) can help boosting performance.

While file persistence is the default mode, you can explicitly enable file persistence by using

for each individual persistence. The following configuration file shows how to manually set file persistence to each persistence store.

If you’re in doubt if the disk performance is good enough for you, we suggest benchmarking HiveMQ with QoS 1 and 2 messages and persistent clients. You can also look at the benchmarks at our website.

If it’s not important for you that persistent clients retain their subscriptions or if you don’t need HiveMQ to hold state between broker restarts but you are looking for extreme performance, then you should consider using in-memory persistence.

In-Memory persistence offers stellar performance and latencies at the cost of losing all state after restarting HiveMQ. This option is often used with clustering, since new cluster nodes receive state from other cluster nodes on startup and cluster nodes are often ephemeral.

Each persistence store can be configured individually to run in file persistence or in-memory mode. The following configuration shows an example with all persistence stores configured to run in-memory:

It’s possible to disable message queuing for offline clients if you don’t need this MQTT functionality.

To disable the message queuing, set the the max-queued-messages setting to 0.

It’s also recommended to use in-memory persistence for queued messages. This saves some disk space.