HiveMQ Configuration

The default settings of HiveMQ are suitable for most typical use cases.

Configuration Files

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

HiveMQ uses a simple but powerful XML-based configuration.

HiveMQ reads the config.xml file one time during startup. To apply changes that you make during runtime, you must restart HiveMQ.

Default Configuration

The default HiveMQ configuration file uses sensible default values.

The default and standard TCP listener binds to all interfaces and port 1883.

In addition to the TCP listener configuration, the following restrictions are configured by default:

  • Maximum client identifier length of 65535 characters

  • Maximum allowed topic length of 65535 characters

  • Unlimited concurrent connections

  • No bandwidth throttling

  • Automatic disconnection of clients that fail to send a CONNECT message within 10 seconds after the TCP connection is established

Default HiveMQ configuration
<?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>

    <restrictions>
        <max-client-id-length>65535</max-client-id-length>
        <max-topic-length>65535</max-topic-length>
        <max-connections>-1</max-connections>
        <incoming-bandwidth-throttling>0</incoming-bandwidth-throttling>
        <no-connect-idle-timeout>10000</no-connect-idle-timeout>
    </restrictions>

</hivemq>
To help you get started quickly, HiveMQ provides several example configurations. All example configurations are located in the conf/examples/configuration folder. To use one of the example configurations, copy the example file to the conf folder of your HiveMQ installation and rename the file config.xml.

Environment Variables

HiveMQ offers placeholders that can be replaced with the content of environment variables when the configuration file is read.

You can insert ${ENV:VARIABLE_NAME} placeholders anywhere in the config.xml file. HiveMQ replaces the placeholder with the value of the specified environment variable during start up.

For example, when you run HiveMQ in a containerized environment it can be desirable to set environment variables on the system on which HiveMQ runs for items such as ports, bind addresses, or heap dump folder.

Environment variables can also be used in the configuration files of all HiveMQ Enterprise Extensions. For example, to provide secrets and other data.

Since HiveMQ 4.6.0, HiveMQ uses a new ${ENV:VARIABLE_NAME} environment variable pattern that broadens support for environment variables in the configuration of HiveMQ and HiveMQ enterprise extensions.
Example to set an environment variable
export HIVEMQ_PORT=1883
Example use of 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>${ENV:HIVEMQ_PORT}</port>
        </tcp-listener>
    </listeners>

</hivemq>
Example environment variable result in HiveMQ
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

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

</hivemq>
To access the environment variable, HiveMQ must start in the same context as the environment variable.

Manually Set Specific HiveMQ Folders

To facilitate maintenance, you can manually set specific HiveMQ folders.

To alter your configuration, add one or more of the following options to your bin/run.sh file:

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

You can also define environment variables:

export ...=/your/folder/here
If you set a Java option and an environment variable for the same folder, HiveMQ uses the value you set in the Java option.
Table 1. Folder Configuration Options
Java Option Environment Variable Affected folder

hivemq.home

HIVEMQ_HOME

Base folder (bin must be a sub folder of this folder)

hivemq.license.folder

HIVEMQ_LICENSE_FOLDER

License files 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

hivemq.backup.folder

HIVEMQ_BACKUP_FOLDER

HiveMQ backup folder

hivemq.audit.folder

HIVEMQ_AUDIT_FOLDER

Audit log folder

 — 

HIVEMQ_HEAPDUMP_FOLDER

HiveMQ heap dump folder

Example Java option:

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

Example environment variable:

export HIVEMQ_HOME=/mqtt/broker/hivemq

The result of either method sets the HiveMQ home folder to /mqtt/broker/hivemq.

Override default HiveMQ heap dump destination

By default, an out of memory event (OOM) in your HiveMQ instance automatically generates a heap dump to the HiveMQ home folder. The heap dump provides a memory snapshot of the HiveMQ process at the moment the OOM error occurs. The information the heap dump contains is valuable for support and troubleshooting purposes.

When you run HiveMQ in a containerized environment such as Kubernetes that uses ephemeral storage, heap dump information written to the default heap dump folder location is lost when the container in which your HiveMQ instance runs crashes and restarts.

The HIVEMQ_HEAPDUMP_FOLDER environment variable allows you to adjust your HiveMQ start file and override the default heap dump destination for your HiveMQ instance. Set the environment variable HIVEMQ_HEAPDUMP_FOLDER to save your heap dumps to a shared folder of your choice.

Example override default heap dump destination:

export HIVEMQ_HEAPDUMP_FOLDER="/opt/heapdumps/"

IPv6

IPv6 is an internet protocol standard and the successor of the established IPv4. Since standardization in 1998, use of the IPv6 protocol has increased steadily.

With some minor adjustments, you can operate HiveMQ with IPv6. The following guide to using IPv6 for our more experimental users.

Adjust HiveMQ Configuration for IPv6

The default configuration of HiveMQ uses IPv4 addresses. 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.xml file must be configured with an IPv6 address:

Example bind address configuration
<?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 IPv6 Listeners

Listeners Status

TCP

TLS

[1]

WebSocket

Secure WebSocket

[1]

Cluster Discovery with IPv6

When you use IPv6, some cluster discovery restrictions apply. The following list shows the availability for each of the possible HiveMQ cluster discovery options:

  • Static discovery with IPv6 works as usual.

  • Broadcast discovery with IPv6 is not available.

  • Multicast discovery can’t be used for IPv6 in the current version of HiveMQ.

Special-use Addresses for IPv6

Table 2. IPv6 special-use addresses
Special-use address IPv4 IPv6 counterpart

Any

0.0.0.0

::

Loopback

127.0.0.1

::1

Default multicast

228.8.8.8

ff0e::8:8:8

MQTT Specific Configuration Options

HiveMQ is 100% compliant with the MQTT 3.1, MQTT 3.1.1 and MQTT 5.0 specifications.
For all MQTT-related settings in the specifications that are open to the broker implementation, HiveMQ uses sensible default values.

Table 3. MQTT Configuration Options
Configuration Default Value Description

Session Expiry

4.294.967.296

Defines the maximum session expiry value that clients can set

Message Expiry

4.294.967.296

Defines the maximum message expiry value that clients can set

Max Packet Size

268435460

Defines the maximum packet size that the broker accepts from clients

Server Receive Maximum

10

Defines the maximum number of concurrent publishes the broker accepts from one client

Max Keep Alive

65535

Defines the maximum keep alive value that a client can set

Allow Unlimited Keep alive

true

Defines whether clients can have unlimited keep alive

Allow Empty ID

true

Defines whether the broker accepts empty client IDs

Topic Alias

true

Defines whether clients can use topic aliases instead of long topics to reduce the packet size

Subscription Identifier

true

Defines whether clients can use subscription identifiers to associate received publishes with their subscriptions

Wildcard Subscriptions

true

Defines whether clients can use wildcard characters in topic filters

Shared Subscriptions

true

Defines whether clients can use shared subscriptions

Maximum QoS

2

Defines the maximum Quality of Service (QoS) level allowed in MQTT PUBLISH messages

Retained Messages

true

Defines whether retained messages are supported

Queued Messages

1000

Defines the maximum number of messages that can be queued per client

Session and Message Expiry

You can configure the length of time HiveMQ allows before a session or message expires. Clients request session expiry and message expiry times and in their CONNECT and PUBLISH packets. If the requested value exceeds the maximum value that is configured in the config.xml, HiveMQ overrides the session expiry interval in the CONNACK packet. The message expiry interval is overridden without informing the client.

Session and Message Expiry configurations can help free up system resources such as disk memory or RAM. In scenarios where the usefulness of a specific type of data decreases over time, best practice is to configure an appropriate expiry time. For example, to expire outdated retained messages. Setting an expiry time can protect the broker from unwanted client behavior.

When a message or session expires, the associated resources do not become available immediately. Data is marked as expired and not used by the broker until it is permanently removed during regular clean-up operations.

Session Expiry

The session expiry max-interval value defines the length of time in seconds that can pass after the client disconnects until the session of the client expires. If a client with the same client ID reconnects before the defined length of time elapses, the session expiry timer resets. When a session expires, the broker removes all subscriptions, queued messages, and incomplete message transmissions that are associated with the session.
The default and maximum Session Expiry value is 4,294,967,296 seconds.

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

    ...
    <!-- Changing client session time to live to one hour -->
    <mqtt>
        <session-expiry>
            <max-interval>3600</max-interval>
        </session-expiry>
    </mqtt>
    ...
</hivemq>
MQTT 3 clients cannot set a session expiry. For MQTT 3 clients, the max-interval is used as the Session Expiry Interval.

Message Expiry

The message expiry max-interval value defines the length of time in seconds that can pass after a message arrives at the broker until the message expires. An expired message is never published. Message expiry can occur for several reasons:

  • A client takes too long to consume the message.

  • The client remains offline and the message expires before the client can consume it.

  • A retained message that is stored on the broker expires.

The default and maximum Message Expiry value is 4,294,967,296 seconds.

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

    ...
    <!-- Sets message expiry to one hour -->
    <mqtt>
        <message-expiry>
            <max-interval>3600</max-interval>
        </message-expiry>
    </mqtt>
    ...
</hivemq>
If the publisher is an MQTT 3 client, the configured max-interval is used as the Message Expiry Interval for onward PUBLISH delivery.

Maximum Packet Size

The max-packet-size value defines the largest MQTT packet size in bytes that HiveMQ accepts.
The default max-packet-size value is set to the maximum packet size the MQTT protocol allows: 268,435,460 bytes (equivalent to 256 MB).

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

    ...
    <mqtt>
        <packets>
            <max-packet-size>268435460</max-packet-size>
        </packets>
    </mqtt>
    ...

</hivemq>

Server Receive Maximum

The server-receive-maximum value defines the maximum number of PUBLISH messages that are not yet acknowledged by the broker, each client can send. When the maximum is reached, the client cannot send additional PUBLISH messages until the broker acknowledges the existing PUBLISH messages.
By default the Server Receive Maximum is set to 10.

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

    ...
    <mqtt>
        <receive-maximum>
            <server-receive-maximum>10</server-receive-maximum>
        </receive-maximum>
    </mqtt>
    ...

</hivemq>

Maximum Keep Alive

The max-keep-alive value defines the maximum value that the broker accepts in the keepAlive field in the CONNECT packet of a client.

Keep alive refers to the number of seconds that the broker permits between when a client finishes sending one MQTT packet and starts to send the next. The broker must disconnect a client that does not send a message or a PINGREQ packet in one and a half times the stated keep alive interval.

If a client sends a CONNECT packet with a keepAlive value that exceeds the max-keep-alive value, the broker returns a CONNACK with the configured max-keep-alive value and sets the keepAlive value of the client accordingly.

The default max-keep-alive value is 65,535.

Maximum Keep Alive is an MQTT 5 feature. MQTT 3 clients cannot interpret the max-keep-alive value that the broker sends in the CONNACK packet and retain their original keep alive value. In this case, the broker accepts the keepAlive value that the MQTT 3 client provided in their CONNECT packet.
Example for maximum keep alive configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <mqtt>
        <keep-alive>
            <max-keep-alive>65535</max-keep-alive>
        </keep-alive>
    </mqtt>
    ...

</hivemq>

Allow Unlimited Keep Alive

The allow-unlimited value defines whether the broker accepts connections from clients that send a CONNECT packet with a keepAlive=0 setting.
By default unlimited keep alive values are allowed.

The allow-unlimited keep-alive setting does not apply to MQTT 3 clients. When you disable unlimited keep alive (allow-unlimited=false), MQTT 3 clients can still send a CONNECT packet with a keepAlive=0 setting.
Example unlimited keep alive configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <mqtt>
        <keep-alive>
            <allow-unlimited>true</allow-unlimited>
        </keep-alive>
    </mqtt>
    ...

</hivemq>

Topic Alias

Topic Aliases are an MQTT 5 feature.

A topic alias is an integer value that a client can use as a substitute for the name of a topic. Use of a topic alias in place of the UTF-8 string topic name can reduce the size of your PUBLISH message.

The MQTT client that sends the message can set a topic alias value in the PUBLISH message, following the topic name. The topic alias value must be a number between 1 and 65535. A topic alias value of '0' is not permitted.

When a client sends a PUBLISH with a topic and a topic alias, HiveMQ persists a mapping between the topic alias and topic name for the duration of the established connection. Subsequent PUBLISH messages that the same client sends on the same topic can be sent with the topic alias alone, as long as the topic itself is empty. When another PUBLISH containing a not empty value for both topic and topic alias is sent by the client, the matching of those values will be overridden by the broker.

During connection establishment, the broker tells the client in the CONNACK message how many topic aliases the client may use.

HiveMQ disconnects clients with a TOPIC_ALIAS_INVALID(0x94) reason code for the following reasons:

  • The PUBLISH message has a topic alias value set to '0'.

  • The topic alias of the PUBLISH message exceeds the maximum number of topic aliases that are allowed per client.

  • The PUBLISH message has an empty topic name and an unknown topic alias.

  • The PUBLISH message has an empty topic name wand an empty topic alias.

When you disable topic aliases in your HiveMQ configuration, HiveMQ sets the max-per-client value of every client that connects to '0'.

Configuration

Table 4. Topic alias configuration options
Configuration Default Limits Description

enabled

true

-

Defines whether topic aliases are enabled by the broker. To disable the feature, set to false.

max-per-client

5

1-65535

The number of topic aliases available per client.

HiveMQ automatically validates your topic alias configuration.
If your configuration is not within the limits, HiveMQ logs a warning message that shows the values that are be used instead.

Example HiveMQ log statement
2018-01-01 01:02:03.040 - The configured topic alias maximum per client (0) is too small. It was set to 1 instead.

Examples

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

    ...
   <mqtt>
       <topic-alias>
           <enabled>true</enabled>
           <max-per-client>5</max-per-client>
       </topic-alias>
   </mqtt>
    ...
</hivemq>
Example disabled topic alias
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <mqtt>
        <topic-alias>
            <enabled>false</enabled>
        </topic-alias>
    </mqtt>
    ...
</hivemq>

Subscription Identifier

Subscription Identifier is an MQTT 5 feature. MQTT clients can use a subscription identifier to associate received PUBLISH messages with the corresponding subscriptions.

Clients can send a subscription identifier with each SUBSCRIBE message. The identifier is associated with every topic filter in the SUBSCRIBE message. HiveMQ stores the information in the client session. When HiveMQ forwards a received PUBLISH to a subscriber, HiveMQ adds subscription identifiers to the outgoing PUBLISH message based on matching the subscription identifier and topic filter combinations of that receiving client’s subscriptions.

The subscription identifier value of the can be a number from 1 to 268,435,455. In case the topic of a PUBLISH matches multiple topic filters with the same identifier, the outgoing PUBLISH will contain the same subscription identifier multiple times. Unlike topic aliases, subscription identifiers do not replace the topic filter for publish messages. The client can override subscription identifiers by sending a new SUBSCRIBE message with the same topic filter and a different identifier.

Configuration

The subscription identifier feature can be disabled completely. If the feature is disabled and a client sends a subscription identifier to the broker, the client is disconnected.

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

...
    <mqtt>
        <subscription-identifier>
            <enabled>true</enabled>
        </subscription-identifier>
    </mqtt>
...
</hivemq>

Wildcard Subscriptions

The wildcard-subscriptions value defines whether or not the wildcard subscription feature is enabled on the broker. A wildcard subscription is a subscription with a topic filter that contains wildcard characters (# and +). The server sends the information if wildcard subscriptions are enabled or disabled to MQTT 5 clients in the property Wildcard Subscription Available as part of a successful CONNACK packet.
By default, wildcard subscriptions are enabled.

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

    ...
    <mqtt>
        <wildcard-subscriptions>
            <enabled>true</enabled>
        </wildcard-subscriptions>
    </mqtt>
    ...

</hivemq>

If wildcard subscriptions are disabled and a MQTT client sends a SUBSCRIBE message containing a topic filter with a wildcard character, HiveMQ disconnects the client.

The following table lists the broker’s response for a denied wildcard subscription for each MQTT protocol version.

Table 5. Error Handling
Protocol version Handling

MQTT 5

DISCONNECT with return code 162(Wildcard Subscriptions not supported) is returned for each topic filter that contains a wildcard character.

MQTT 3.1.1

The client is disconnected if a SUBSCRIBE message contains a topic filter that contains a wildcard character.

MQTT 3.1

The client is disconnected if a SUBSCRIBE message contains a topic filter that contains a wildcard character.
Event Log output if an MQTT 3.1 client is disconnected
2018-01-01 01:02:03.040 - Client ID: my-client-id, IP:123.123.123.123 was disconnected. reason: Sent a SUBSCRIBE with a wildcard character in the topic filter 'topic/#', although wildcard subscriptions are disabled.

Shared Subscriptions

The shared-subscriptions value defines whether or not the Shared Subscription feature is enabled on the broker. The server sends the information if shared subscriptions are enabled or disabled to MQTT 5 clients in the property Shared Subscription Available as part of a successful CONNACK packet.
By default, shared subscriptions are enabled.

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

    ...
    <mqtt>
        <shared-subscriptions>
            <enabled>true</enabled>
        </shared-subscriptions>
    </mqtt>
    ...

</hivemq>

If shared subscriptions are disabled and an MQTT client sends a SUBSCRIBE message with a topic filter that uses shared subscription syntax, HiveMQ disconnects the client.

The following table shows how HiveMQ responds to forbidden shared subscription attempts for each MQTT protocol version.

Table 6. Error Handling
Protocol version Response

MQTT 5

DISCONNECT with return code 158(Shared Subscriptions not supported) is returned for each topic filter that uses the shared subscription syntax.

MQTT 3.1.1

The client is disconnected if a SUBSCRIBE message contains a topic filter that uses the shared subscription syntax.

MQTT 3.1

The client is disconnected if a SUBSCRIBE message contains a topic filter that uses the shared subscription syntax.
Event Log output if an MQTT 3.1 client is disconnected
2018-01-01 01:02:03.040 - Client ID: my-client-id, IP:123.123.123.123 was disconnected. reason: Sent a SUBSCRIBE, which matches a shared subscription '$share/group1/#', although shared subscriptions are disabled.

Maximum Quality of Service

The max-qos value refers to the maximum quality of service level of PUBLISH messages that is allowed by the broker. The server sends the maximum Quality of Service level to MQTT 5 clients in the property Maximum QoS as part of a successful CONNACK packet. max-qos must be 0 , 1 or 2.
By default the maximum QoS level is 2, allowing all quality of service levels.

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

    ...
    <mqtt>
        <quality-of-service>
            <max-qos>2</max-qos>
        </quality-of-service>
    </mqtt>
    ...

</hivemq>
In accordance with the MQTT 5 specification, this configuration does not restrict the maximum QoS level tha can be used in MQTT SUBSCRIBE messages.

Publishes with QoS

If the maximum QoS is restricted and a MQTT client sends a PUBLISH message with a higher QoS level than configured, the PUBLISH will be denied by the broker.

The following table lists the broker’s response for a denied PUBLISH for each MQTT protocol version.

Table 7. Error Handling for PUBLISH messages
Protocol version Handling

MQTT 5

DISCONNECT with return code 155(QoS not supported) will be sent by the broker and the client will be disconnected.

MQTT 3.1.1

The client will be disconnected.

MQTT 3.1

The client will be disconnected.
Event Log output if a client sends a PUBLISH with disallowed QoS
2018-01-01 01:02:03.040 - Client ID: my-client-id, IP:123.123.123.123 was disconnected. reason: Sent PUBLISH with QoS (2) higher than the allowed maximum (1).

Connections with Will

If a CONNECT message is sent to the broker, which contains a Will QoS (Quality of Service Level of the client’s Will publish) higher than the configured maximum QoS level, the connection is denied by HiveMQ. The following table lists the handling of a denied CONNECT due to forbidden Will QoS level for each MQTT protocol version.

Table 8. Error Handling for Will QoS
Protocol version Handling

MQTT 5

CONNACK with return code 155(QoS not supported) is sent by the broker and the client is disconnected.

MQTT 3.1.1

CONNACK with return code 5(Not authorized) is sent by the Broker and the client is disconnected.

MQTT 3.1

CONNACK with return code 5(Not authorized) is sent by the Broker and the client is disconnected.
Event Log output if a client sends a CONNECT with disallowed Will QoS
2018-01-01 01:02:03.040 - Client ID: my-client-id, IP:123.123.123.123 was disconnected. reason: Sent CONNECT with Will QoS (2) higher than the allowed maximum (1).

Retained Messages

The retained-messages value defines whether or not the retained messages feature is enabled on the broker. By default retained messages are enabled.

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

    ...
    <mqtt>
        <retained-messages>
            <enabled>true</enabled>
        </retained-messages>
    </mqtt>
    ...

</hivemq>

MQTT 5 clients receive information about the availability of the retained messages feature in the Retain Available property of a successful CONNACK packet.

If retained messages are disabled, clients must not do the following:

  • Send a CONNECT message with the Will Retain flag set to true.

  • Send a PUBLISH message with the Retain flag set to true.

The following table shows the broker’s response in case a client sends a CONNECT message with the Will Retain flag set to true although retained messages are disabled, for each MQTT protocol version.

Protocol version Handling`

MQTT 5.0

CONNACK message with reason code 154 (Retain not supported) is sent to the client.

MQTT 3.1.1

CONNACK message with return code 5 (Not authorized) is sent to the client.

MQTT 3.1

CONNACK message with return code 5 (Not authorized) is sent to the client.

The following table shows the broker’s response in case a client sends a PUBLISH message with the Retain flag set to true although retained messages are disabled, for each MQTT protocol version.

Protocol version Handling

MQTT 5.0

DISCONNECT message with reason code 154 (Retain not supported) is sent to the client.

MQTT 3.1.1

The client is disconnected.

MQTT 3.1

The client is disconnected.

Queued Messages

There are two possible scenarios under which HiveMQ may queue messages for a client.

  1. Messages are published on a topic for which an offline client that has an existing session on the broker (cleanSession=false) has a subscription.

  2. An online client is not capable of consuming messages at the same speed as HiveMQ wants to send messages to that client.

The following lists available configuration options for queued messages.

Table 9. Queued Message Configuration Options
Value Default Value Description

max-queue-size

1000

Maximum amount of messages per client that will be stored on the broker.

strategy

discard

Discard strategy when message arrives at the broker and the corresponding client’s message queue is full.
discard for discarding newly arriving messages. discard-oldest to discard the oldest message in the queue when a new message arrives.
Example queued messages configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <mqtt>
        <queued-messages>
            <max-queue-size>1000</max-queue-size>
            <strategy>discard</strategy>
        </queued-messages>
    </mqtt>
    ...

</hivemq>

Security Configuration

The following lists available configuration options that have security relevance.

Table 10. Security Configuration Options
Value Default Value Description

allow-empty-client-id

true

Allows the use of empty client ids. If this is set to true, HiveMQ automatically generates random client ids, when clientId in the CONNECT packet is empty.

payload-format-validation

false

Enables the UTF-8 validation of UTF-8 PUBLISH payloads.

utf8-validation

true

Enables the UTF-8 validation of topic names and client ids.

allow-request-problem-information

true

Allows the client to request the problem information. If this is set to false, no reason string and user property values will be sent to clients.

control-center-audit-log

true

If audit logging for the control center is enabled.

Allow Empty Client ID

The allow-empty-client-id value defines whether or not the broker will accept connections from clients that did not set a clientId value in the CONNECT packet. If this is set to true, the broker will generate a random id for the client upon connection establishment. By default the broker allows empty client ids.

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

    ...
    <security>
        <!-- Allows the use of empty client ids -->
        <allow-empty-client-id>
            <enabled>true</enabled>
        </allow-empty-client-id>
    </security>
    ...

</hivemq>

Payload Format Validation

The payload-format-validation value defines whether or not the broker will validate a PUBLISH payload, whenever the Payload Format Indicator of that PUBLISH is set to 'UTF-8'. By default payload format validation is disabled.

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

    ...
    <security>
        <!-- Disables validation for UTF-8 PUBLISH payloads -->
        <payload-format-validation>
            <enabled>false</enabled>
        </payload-format-validation>
    </security>
    ...

</hivemq>

Topic and Client ID UTF-8 Validation

The utf8-validation value defines whether the broker verifies the UTF-8 validity of topic names and client IDs. By default, UTF-8 validation is enabled.

Example topic and client ID UTF-8 validation configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <security>
        <!-- Enables the UTF-8 validation of topic names and client ids -->
        <utf8-validation>
            <enabled>true</enabled>
        </utf8-validation>
    </security>
    ...

</hivemq>

Request Problem Information

The allow-request-problem-information value defines whether clients are allowed to request reason string and user property values from the broker. By default, the requesting of problem information is allowed.

Example allow resource problem information configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <security>
        <!-- Allows clients to request problem information -->
        <allow-request-problem-information>
            <enabled>true</enabled>
        </allow-request-problem-information>
    </security>
    ...

</hivemq>
The attribute 'allow-request-problem-information' has no effect for the packets DISCONNECT, CONNACK and PUBLISH.


Control center audit log

The value control-center-audit-log defines whether or not the audit log of the control center is enabled. By default, the audit log is enabled.

Example control center audit log configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <security>
        <!-- Enables audit logging for the control center -->
        <control-center-audit-log>
            <enabled>true</enabled>
        </control-center-audit-log>
    </security>
    ...

</hivemq>


Full Security Properties Configuration Example

The following example provides an example configuration for all security-relevant MQTT options.

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

    ...
    <security>

        <!-- Disables the validation of UTF-8 PUBLISH payloads -->
        <payload-format-validation>
            <enabled>false</enabled>
        </payload-format-validation>

        <!-- Enables the UTF-8 validation of topic names and client ids -->
        <utf8-validation>
            <enabled>true</enabled>
        </utf8-validation>

        <!-- Allows the use of empty client ids -->
        <allow-empty-client-id>
            <enabled>true</enabled>
        </allow-empty-client-id>

        <!-- Allows the client to request the problem information -->
        <allow-request-problem-information>
            <enabled>true</enabled>
        </allow-request-problem-information>

        <!-- Enables audit logging for the control center -->
        <control-center-audit-log>
            <enabled>true</enabled>
        </control-center-audit-log>

    </security>
    ...

</hivemq>
1. No MQTT client library available for testing this feature with IPv6