Restrictions

CPU, memory, and bandwidth are limited resources. To save resources and avoid malicious client attacks, it can be necessary to limit the number of TCP connections or restrict bandwidth usage for your HiveMQ deployment.

HiveMQ connection limits and connection-rate throttling properties are defined in the config.xml file of your HiveMQ instance. The restrictions tag of the HiveMQ config.xml file contains all of your global connection limit settings.

Maximum Connection Limit

You can set a global connection limit for HiveMQ. When the defined number of open MQTT connections is reached, HiveMQ automatically inhibits new client connections. Limiting connections in this manner can be crucial if your server hardware resources are limited.

By default, the max-connections property is set to -1, which means HiveMQ can accept an unlimited number of connections (setting the property to 0 also results in unlimited connections).

The max-connection property does not change the number of connections that your HiveMQ license allows. You are restricted to the maximum number of connections that is defined in your active HiveMQ license. For example, a trial license is restricted to 25 client connections.

Table 1. Maximum connection configuration settings
Property	Default	Description
`max-connections`	`-1 (unlimited)`	The maximum number of concurrent MQTT connections the HiveMQ instance allows

The number of connections that you configure in the max-connections setting defines the total number of concurrent connections that your HiveMQ instance can accept. If you configure multiple listeners, keep in mind that max-connections is a global setting that defines the total number of concurrent connections (not the per listener).

The following example shows how to configure HiveMQ to allow a maximum of 100 concurrent connections:

Example maximum concurrent connections configuration

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

    ...
   <restrictions>
       <max-connections>100</max-connections>
   </restrictions>
    ...
</hivemq>

If you set a max-connections limit that is higher than the connection limit listed in your HiveMQ license, HiveMQ uses the maximum number of connections your license allows.

Connect Overload Protection

To maintain uninterrupted operation during periods of unusually high demand and surges of new connections, HiveMQ provides dynamic connect overload protection by default. Dynamic connect overload protection (connection rate throttling) automatically scales with your cluster overload protection. HiveMQ calculates cluster overload protection internally, based on the current stress level of the cluster. When the cluster protection level of HiveMQ increases, dynamic connect overload protection automatically reduces the allowed CONNECT rate.

Dynamic connect overload protection ensures that HiveMQ consistently accepts MQTT CONNECT messages at a set <connect-rate>. Additionally, HiveMQ connect overload protection allows the broker to accept short increases in CONNECT message activity that do not exceed the configured <connect-burst-size>.

Configurable Dynamic Connect Overload Protection

This is a HiveMQ Enterprise Edition feature. Find out more about HiveMQ Editions.

In HiveMQ Enterprise editions version 4.7 or higher, you can enable, disable, and configure your connect overload protection to control the rate per second of MQTT CONNECT packets that HiveMQ allows.

The <connect-overload-protection> tag can be configured individually per listener. Flexible connect overload protection is particularly useful if your deployment uses extended authentication and/or authorization systems that can only handle a specific average rate of authentications per second.

When this feature is enabled, HiveMQ only allows MQTT CONNECT messages at the configured <connect-rate> over a sustained period of time. HiveMQ also allows brief bursts of CONNECT events up to the <connect-burst-size>.

If the rate of incoming CONNECT messages exceeds the level that you configure in the connect overload protection, HiveMQ temporarily stops reading from new sockets and disconnects newly connecting clients.

If you do not define a custom <connect-rate> HiveMQ does not limit the rate of incoming CONNECT messages as long as the HiveMQ cluster overload protection level is 0. In this case, HiveMQ dynamic connection overload protection starts automatically as soon as the cluster overload protection level reaches 1. When you define a custom <connect-rate>, HiveMQ applies the rate limit even when your cluster overload protection level is 0.

Table 2. Available connect overload protection parameters
Parameter	Default	Description
`enabled`	`true`	Enables connect overload protection. Possible values are `true` and `false`.
`connect-rate`	`500`	The maximum sustained rate of connects that the listener allows per second. Based on your system and authentication logic, you can enable, disable, and define different connection rates per listener.
`connect-burst-size`	`<connect-rate> * 2`	The maximum amount of simultaneous `CONNECT` messages that the listener allows for short periods. The burst size cannot be set to 0 (zero). When no burst rate is specified, the listener allows a burst rate that is double the defined connect rate.

Example connect overload protection 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>
            <connect-overload-protection>
                <enabled>true</enabled>
                <!-- 2000 C/s == 2C/ms -->
                <connect-rate>2000</connect-rate>
                <connect-burst-size>4000</connect-burst-size>
            </connect-overload-protection>
        </tcp-listener>
    </listeners>
   ...

</hivemq>

If cluster overload protection is disabled, your custom-defined connection rate limits still apply but do not scale with the cluster overload protection level. In this case, if no connect-rate is configured for the connect overload protection, no rate-limiting is applied.

Throttling SSL Handshakes

This is a HiveMQ Enterprise Edition feature. Find out more about HiveMQ Editions.

The number of SSL handshake operations per listener that can occur concurrently can be configured.

The <concurrent-handshake-limit> setting can be used to limit the amount of concurrently occurring SSL handshakes. This can work as an overload protection for the broker during bulk (re)-connection scenarios.

Table 3. Available ssl handshake overload protection configurations
Option	Required	Default Value	Description
`concurrent-handshake-limit`	`false`	`-1`	The maximum number of SSL handshakes, that can be in progress at any time (set to a positive non zero integer to activate)

Example SSL handshake overload protection configuration

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

        <listeners>
            ...
            <tls-tcp-listener>
                <port>8883</port>
                <bind-address>0.0.0.0</bind-address>
                <name>my-secure-tcp-listener</name>
                <tls>
                    <keystore>
                        <path>/path/to/the/key/store.jks</path>
                        <password>password-keystore</password>
                        <private-key-password>password-key</private-key-password>
                    </keystore>
                    <!-- Allow a maximumn of 500 concurrent SSL handshakes for this listener -->
                    <concurrent-handshake-limit>500</concurrent-handshake-limit>
                </tls>
            </tls-tcp-listener>
        </listeners>
   ...

</hivemq>

Throttling Bandwidth

You can configure HiveMQ to globally throttle the incoming network traffic for MQTT clients if you don’t want to reserve all your bandwidth for HiveMQ or if you want to artificially slow down all clients.

Throttling message throughput

A convenient way of limiting the message throughput of HiveMQ when you have many subscribers is to throttle the incoming traffic. If your system resources such as CPU and RAM are at premium this is an efficient and quick way to limit the maximum incoming messages. A sane global throttling by default can prevent resource exhaustion.

Available throttling bandwidth configurations

Option Default Value Description

Option	Default Value	Description
`incoming-bandwidth-throttling`	`0 (unlimited)`	The maximum incoming traffic as bytes per second (b/s).

incoming-bandwidth-throttling

0 (unlimited)

The maximum incoming traffic as bytes per second (b/s).

The following example makes the incoming traffic unlimited.

Example bandwidth throttling configuration

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

    ...
   <restrictions>
        <incoming-bandwidth-throttling>0</incoming-bandwidth-throttling>
   </restrictions>
    ...
</hivemq>

Connection Timeouts

MQTT, a layer 7 protocol in the OSI layer model, relies on TCP and requires MQTT clients to open a TCP connection before they send the MQTT CONNECT message that initiates an MQTT connection.

Since MQTT operates on the application layer, the fact that a client initiates a TCP connection does not guarantee that the client initiates an MQTT connection. Malicious MQTT clients can open a TCP connections and drain server resources without initiating an MQTT connection or sending an MQTT CONNECT message. This kind of client can attack your MQTT broker by quickly draining all system resources (for example, memory).

To avoid this kind of attack, it is important to disconnect clients that do not initiate an MQTT connection as quickly as possible.

By default, HiveMQ waits 10 seconds (10000 milliseconds) for the CONNECT message of a client before it closes an open TCP socket. You can adjust this behaviour to suite the needs of your application.

Available throttling bandwidth configurations

Option Default Value Description

Option	Default Value	Description
`no-connect-idle-timeout`	`10000`	The time in milliseconds that HiveMQ waits for a CONNECT message of a client before an open TCP socket is closed.

no-connect-idle-timeout

10000

The time in milliseconds that HiveMQ waits for a CONNECT message of a client before an open TCP socket is closed.

Change the idle timeout

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

    ...
    <!-- Disconnect idle clients after 10000 milliseconds / 10 seconds -->
    <restrictions>
        <no-connect-idle-timeout>10000</no-connect-idle-timeout>
    </restrictions>
    ...

</hivemq>

Clients with a slow connection

If you have clients that use a network with very high latency, a few seconds might not be enough time for the clients to connect. As a result, clients could get disconnected although they attempt to send a CONNECT message. Be sure that the timeout you configure is appropriate for your use case.

Restrict MQTT Client ID Length

You can configure HiveMQ to only accept MQTT client IDs up to a certain length. If a client tries to connect with an MQTT client ID that is longer than the 'max-client-id-length', the broker rejects the connection attempt. The maximum number of characters that HiveMQ can accept in an MQTT Client ID is 65535. The default setting for 'max-client-id-length' is 65535. The minimum value for 'max-client-id-length' is 1. If you configure a value less than 1 or more than 65535, HiveMQ uses the default value of 65535.

Option Default Value Description

Option	Default Value	Description
`max-client-id-length`	`65535`	The maximum number of characters HiveMQ accepts in an MQTT-client ID

max-client-id-length

65535

The maximum number of characters HiveMQ accepts in an MQTT-client ID

Change the max client ID length

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

    ...
    <!-- allow clients that have identifiers with up to 1000 characters-->
    <restrictions>
        <max-client-id-length>1000</max-client-id-length>
    </restrictions>
    ...

</hivemq>

Restrict Topic Length

You can configure HiveMQ to only accept topic strings up to a certain length. If a client tries to publish with a topic that is longer than the 'max-topic-length', the broker rejects the publish attempt. The broker also rejects subscriptions with topic filters that are longer than the configured 'max-topic-length' value. The maximum number of characters that HiveMQ can accept in a topic string is 65535. The default setting for 'max-topic-length' is 65535. If you configure a value less than 1 or more than 65535, HiveMQ uses the default value of 65535.

Option Default Value Description

Option	Default Value	Description
`max-topic-length`	`65535`	The maximum number of characters HiveMQ accepts in a topic string

max-topic-length

65535

The maximum number of characters HiveMQ accepts in a topic string

Change the max topic length

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

    <!-- allow topic strings with up to 1000 characters -->
    <restrictions>
        <max-topic-length>1000</max-topic-length>
    </restrictions>
    ...

</hivemq>