Untitled :: HiveMQ Documentation

MQTT Specific HiveMQ Edge Configuration Options

HiveMQ Edge is 100% compliant with the MQTT 3.1, MQTT 3.1.1,MQTT 5.0, and MQTT-SM 1.2.

Where applicable, HiveMQ Edge 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

In HiveMQ Edge, you can configure the maximum 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 Edge overrides the session expiry interval in the client CONNACK packet. The message expiry interval is overridden without informing the client. MQTT 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 your HiveMQ Edge MQTT 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 value is 4,294,967,296.

Example client 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 value is 4,294,967,296.

Example message expiry 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 defines the largest MQTT packet size in bytes that HiveMQ Edge 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 sever 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.

NOTE: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 Edge 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 Edge 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 Edge sets the max-per-client value of every client that connects to '0'.

Configuration

HiveMQ has four configuration options for topic alias usage.

Table 2. 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 Edge automatically validates your topic alias configuration.
If your configuration exceeds the limits, HiveMQ Edge logs a warning message that suggests the values to use instead.

Example HiveMQ Edge 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.

Example topic alias configurations in HiveMQ Edge

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>

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

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 Edge stores the information in the client session. When HiveMQ Edge forwards a received PUBLISH to a subscriber, HiveMQ Edge adds subscription identifiers to the outgoing PUBLISH message based on matching the subscription identifier and topic filter combinations of the receiving client’s subscriptions.

The subscription identifier value of can be a number from 1 to 268,435,455. If the topic of a PUBLISH matches multiple topic filters with the same identifier, the outgoing PUBLISH can 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.

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

Example configuration to enable 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 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 Wildcard Subscription Available property of a successful CONNACK packet.
By default, wildcard subscriptions are enabled.

Example wildcard subscription 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 HiveMQ Edge broker denies the subscription request.

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 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. To disable shared subscriptions, set <enabled> to false.

Example enabled 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 that contains a topic filter with shared subscription syntax, the HiveMQ broker denies the subscription request.

The way the HiveMQ broker handles shared subscription attempts when shared-subscriptions are disabled varies based on the MQTT protocol version used.

Table 4. Shared subscription error responses per MQTT protocol version
Protocol version	Handling
`MQTT 5`	HiveMQ returns a SUBACK message with the return code `158`(Shared Subscriptions not supported) for each topic filter that uses shared subscription syntax.
`MQTT 3.1.1`	HiveMQ returns a SUBACK message with the return code `128`(Failure) for each topic filter that uses shared subscription syntax.
`MQTT 3.1`	HiveMQ disconnects the client if a SUBSCRIBE message contains a topic filter that uses shared subscription syntax.

HiveMQ Edge Event Log output if an MQTT 3.1 client is disconnected due to disabled shared subscriptions:

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 defines the maximum Quality of Service (QoS) level the HiveMQ broker allows for of PUBLISH messages. 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. Possible max-qos values are 0 , 1 or 2.
The default maximum QoS level is 2(all quality of service levels are allowed).

Example default 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 that can be used in MQTT SUBSCRIBE messages.

Publish Messages with QoS

If the maximum QoS is restricted and a MQTT client sends a PUBLISH message with a higher QoS level than the configured max-qos value, the HiveMQ broker denies the PUBLISH request.

Table 5. Maximum QoS exceeded error response for PUBLISH messages per MQTT protocol version
Protocol version	Handling
`MQTT 5`	HiveMQ sends a DISCONNECT packet with the return code `155`(QoS not supported) and disconnects the client.
`MQTT 3.1.1`	HiveMQ disconnects the client.
`MQTT 3.1`	HiveMQ disconnects the client.

HiveMQ Edge Event Log output if a client sends a PUBLISH with a disallowed QoS level

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

Will Publish Messages with QoS

If a client sends a CONNECT package to the HiveMQ broker that contains a Will message with a QoS higher than the configured maximum QoS level, HiveMQ denies the connection.

Table 6. Maximum QoS exceeded connection error response for Will messages per MQTT protocol version
Protocol version	Handling
`MQTT 5`	HiveMQ sends a CONNACK packet with the return code `155`(QoS not supported) and disconnects the client.
`MQTT 3.1.1`	HiveMQ sends a CONNACK packet with the return code `5`(Not authorized) and disconnects the client.
`MQTT 3.1`	HiveMQ sends a CONNACK packet with the return code `5`(Not authorized) iand disconnects the client.

HiveMQ Edge Event Log output if a client sends a CONNECT with a 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 the retained messages feature is enabled on the HiveMQ broker. By default, retained messages are enabled.

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

When retained messages are disabled, the following restrictions apply:

Clients are not permitted to send a CONNECT package with a Will Retain flag set to true.
Clients are not permitted to send a PUBLISH package with a Retain flag set to true.

The following table shows the response if a client sends a CONNECT packet that contains a WIll message with the Retain flag set to true when retained messages are disabled.

Table 7. Will retain not supported connection error response per 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 response if a client sends a PUBLISH package with the Retain flag set to true when retained messages are disabled,

Table 8. .Retain not supported error response per 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 scenarios in which HiveMQ Edge queues messages for a client:

Messages are published on a topic for which an offline client that has an existing session on the broker (cleanSession=false) has a subscription.
An online client is not capable of consuming messages at the same speed as HiveMQ Edge wants to send messages to that client.

Table 9. Queued message configuration options
Value	Default Value	Description
`max-queue-size`	1000	Sets the maximum number of messages the HiveMQ broker can store per client.
`strategy`	discard	Defines how messages that arrive at the HiveMQ broker when the message queue of the corresponding client is full are handled. `discard`: HiveMQ Edge discards newly arriving messages when the client queue is full (default). `discard-oldest`: If the client queue is full, HiveMQ Edge discards 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

Several HiveMQ Edge configuration parameters 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 set to `true`, HiveMQ Edge automatically generates random client IDs, when the `clientId` parameter 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 set to `false`, no reason string and user property values are sent to clients.

Allow Empty Client ID

The allow-empty-client-id value defines whether the broker accepts connections from clients that do not provide a clientId value in their CONNECT packet. If set to true, the broker accepts the connection and generates a random ID for the client during the connection establishment. By default, the broker allows empty client IDs.

Example allow empty client ID configuration

<?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 the broker validates the PUBLISH payload when the Payload Format Indicator of the PUBLISH is set to 'UTF-8'. By default, payload format validation is disabled.

Example disabled 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 checks the UTF-8 validity of topic names and client IDs. By default, UF8-8 validation is enabled.

Example enabled 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, problem information requests are allowed.

Example allow request 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 on DISCONNECT, CONNACK, and PUBLISH packets.

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>

    </security>
    ...

</hivemq>