MQTT Specific Configuration

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

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

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

Tip	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 sever 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 2. 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 3. 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-sub}[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 4. 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>

Note	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 5. 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 6. 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 7. 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 8. 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.

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>

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

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>

    </security>
    ...

</hivemq>