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 the HiveMQ startup. To have changes that you make during runtime take effect, 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:

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

  • Clients that do not send a CONNECT message within 10 seconds after opening the TCP connection are disconnected

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

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 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 the broker accepts.
The default and maximum Maximum Packet Size is 268,435,460 bytes.

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 end additional PUBLISH messages until the broker acknowledges 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

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

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

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

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

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