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.

In addition to the TCP listener configuration, which is visible on the default configuration file, these restrictions are configured by default:

  • The maximum allowed client identifier length is 65535

  • The maximum allowed topic length is 65535

  • No maximum concurrent connection limit is applied

  • No bandwidth throttling will take place

  • Clients will get disconnected if they don’t send a CONNECT message in 10 seconds after opening the TCP connection

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>

    <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>
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>
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.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

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.

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.

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

TLS

[1]

WebSocket

Secure WebSocket

[1]

Cluster discovery with IPv6

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:

  • 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 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

MQTT Specific Configuration Options

HiveMQ is 100% compliant with the MQTT 3.1, MQTT 3.1.1 and MQTT 5.0 specifications. For those parts of the specifications that leave some parts open to the broker implementation, HiveMQ uses sensible default values for all MQTT related settings.

Table 3. MQTT Configuration Options
Configuration Default Value Description

Session Expiry

4.294.967.296

Defines the max value which can be requested from the clients

Message Expiry

4.294.967.296

Defines the max value which can be requested from the clients

Max packet size

268435460

Defines the max packet size which will be accepted from clients

Server Receive Maximum

10

Defines how many concurrent publishes will be accepted from one client

Max Keep alive

65535

Defines the max value of keep alive which can set by the clients

Allow Unlimited Keep alive

true

Defines if the clients are allowed to have unlimited keep alive

Allow empty Id

true

Allows the client Id to be empty

Topic alias

true

Topic aliases can be used instead of long topics to reduce the packet size

Subscription Identifier

true

Subscription identifiers are used by MQTT clients to associate received publishes with their subscriptions

Wildcard Subscriptions

true

Defines if MQTT clients are allowed to use wildcard characters in a topic filter

Shared Subscriptions

true

Defines if MQTT clients are allowed to use shared subscriptions

Maximum QoS

2

Defines the maximum Quality of Service (QoS) level, which may be used in MQTT PUBLISH messages

Retained Messages

true

Defines whether retained messages are supported by HiveMQ

Queued Messages

1000

Defines the limit of messages that can be queued per client by HiveMQ

Session- and Message Expiry

HiveMQ allows the configuration of the max amount of time before a session or message expires. The time of expiration is requested by the clients in the CONNECT and PUBLISH packet. If the requested value exceeds the max value configured in the config.xml, HiveMQ will override the session expiry interval in the CONNACK packet. The message expiry interval will be overridden without informing the client. These configurations can help to free up some resources like disk memory or RAM. In scenarios, where a specific type of data (i.e. retained messages) is no longer useful after an extended period of time, it is recommended to configure an appropriate expiry time. Setting an expiry time may protect the broker from unexpected client behaviour.

Resources are not freed up immediately on expiration. The data will be marked as expired and ignored by the broker until it is cleaned up eventually.

Session Expiry

The session expiry max-interval value describes duration (in seconds) that has to pass after the client disconnected, before its session expires. In case the client (same client ID) reconnects before the expiry time ends, the timer is reset. All subscriptions, queued messages and unfinished message transmissions associated with the session are removed on expiration.
The default and maximum value is 4,294,967,296.

Changing the Client Session Time to Live 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>
Because an MQTT 3 client can’t set a session expiry, the max-interval will always be the Session Expiry Interval for the client.

Message Expiry

The message expiry max-interval value describes duration (in seconds) that has to pass after the message arrived at the broker, before it expires. An expired message is never published. Not publishing due to expiry can happen in the following cases:

  • A client consumes the message too slow.

  • The message has been queued for an offline client and the messages expires before the client can consume the message.

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

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

Changing the Message Time to Live Configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <!-- Changing message time to live 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 Message Expiry Interval for onward PUBLISH delivery.

Maximum Packet Size

The max-packet-size value refers to the maximum size of any MQTT packet in bytes that will be accepted by the broker.
The default and maximum value is 268,435,460.

Example for max packet size
<?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 refers to the maximum amount of PUBLISH messages, which have not yet been acknowledged by the broker, each client is allowed to send. When the maximum is reached the client is not allowed to send additional PUBLISH messages until the broker acknowledges existing PUBLISH messages.
By default the server receive maximum is set to 10.

Example for max packet Size
<?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 refers to the maximum value of the keepAlive field in the CONNECT packet of the client that will be accepted by the broker. If a client sends a CONNECT with a keepAlive value that exceeds this value, the broker will not accept the connection.
The default value is 65,535.

Example for max packet Size
<?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 or not the broker will accept connections by clients that sent a CONNECT packet with a keepAlive=0 setting.
By default unlimited keep alive values are allowed.

Example for max packet Size
<?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

MQTT 5 introduces the Topic Alias feature.

Its purpose is to reduce the packet size of PUBLISH messages, as the topic can be substituted with an alias. Topic aliases must be number between 1 and 65535. '0' is not allowed.

When a client sends a PUBLISH with a topic and a topic alias, the topic and alias will be correlated to each other for the duration of the established connection. Subsequent PUBLISH messages sent by the same client on the same topic can then be sufficiently qualified via 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.

The client will be disconnected by the server with a TOPIC_ALIAS_INVALID(0x94) reason code when it sends a PUBLISH with:

  • A topic alias with value '0'.

  • A topic alias larger than the maximum allowed by the broker.

  • An empty topic with an unknown topic alias.

  • An empty topic without a topic alias.

When topic aliases are disabled in the configuration, every connecting client will receive '0' as topic aliases maximum from the broker.

Configuration

HiveMQ has four configuration options for topic alias usage.

Table 4. Configuration for topic alias
Configuration Default Limits Description

enabled

true

-

Are topic aliases enabled by the broker?

max-per-client

5

1-65535

The amount of topic aliases available per client.

Topic alias configuration will be validated by HiveMQ. When the configuration is not within the limits described in the table above, HiveMQ will log a warning message, showing the values that will 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

Enabled and configured topic aliases
<?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>
Disabled topic alias usage
<?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

MQTT 5 introduces the Subscription Identifier feature. Subscription identifiers are used by MQTT clients to associate received PUBLISH messages with corresponding subscriptions.

A subscription identifier can be sent by the client with each SUBSCRIBE message. The identifier is associated with every topic filter in the SUBSCRIBE message. This information is stored by the broker within the client session. When a received PUBLISH is forwarded to a subscriber by the broker, the broker will add subscription identifiers to the outgoing PUBLISH messages based on matching subscription identifier / topic filter combinations of that receiving client’s subscriptions.

The value of a subscription identifier may range 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 will be 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, the subscription will be denied by HiveMQ.

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

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

MQTT 3.1.1

SUBACK with return code 128(Failure) will be returned for each topic filter that contains a wildcard character.

MQTT 3.1

The client will be 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 for 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 a MQTT client sends a SUBSCRIBE message containing a topic filter that uses the shared subscription syntax, the subscription will be denied by HiveMQ.

The following table lists the broker’s response to a forbidden shared subscription attempt for each MQTT protocol version.

Table 6. Error Handling
Protocol version Handling

MQTT 5

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

MQTT 3.1.1

SUBACK with return code 128(Failure) will be returned for each topic filter that uses the shared subscription syntax.

MQTT 3.1

The client will be 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 for 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 for 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 will 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

  • 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 for 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.

Allow empty id example
<?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.

Payload Format Validation configuration example
<?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 or not the broker will check UTF-8 validity for topic names and client ids. By default UF8-8 validation is enabled.

Topic and Client Id UTF-8-Validation configuration example
<?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 or not clients are allowed to request reason string and user property values from the broker. By default the requesting of problem information is allowed.

Allow resource problem information example
<?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.

Control center audit log example
<?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>


Example

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

Setting the security properties
<?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