HiveMQ MQTT Listeners

MQTT listeners specify the IP address and port on which HiveMQ accepts incoming connections from MQTT clients.

By default, HiveMQ binds to the Internet Assigned Numbers Authority (IANA) standard port for MQTT: 1883 .

Depending on the message transport protocol you use, the listener requires different configuration parameters.
HiveMQ supports the following message transfer protocols:

  • Transmission Control Protocol (TCP): A standardized networking protocol that allows computers to communicate with each other (RFC 793).

  • Transport Layer (TLS): A standardized cryptographic protocol for secure communication and exchange of data over a computer network (RFC 5246).

  • WebSocket: A standardized communication protocol for bidirectional exchange of data between a browser and server over a persistent connection (RFC 6455).

You can add and configure the following MQTT listener types to your HiveMQ installation:

Table 1. Available MQTT listener types
Listener Description

TCP Listener

Listens for MQTT messages that use TCP

Secure TCP Listener

Listens for MQTT messages that use TLS

WebSocket Listener

Listens for MQTT messages over WebSockets

Secure WebSocket Listener

Listens for MQTT over secure WebSockets that use TLS

Multiple Listeners

HiveMQ provides flexible configuration options that allow you to use multiple listeners for different protocols and bind listeners to specific network interfaces. For example, you can configure HiveMQ to accept standard TCP connections on one port and secure TCP connections on another port.

Once a client connects to HiveMQ, the client can communicate through the broker with all other connected clients. The type of listener over which the client connects to the broker does not restrict the ability of the client to publish and subscribe through the broker to other clients.

You can easily add different listeners for different types of network interfaces. For example, configure a standard TCP listener for internal-only network interfaces and secure TLS listeners for interfaces that are externally accessible over the internet.

When you configure multiple listeners, clients can opt for a secure TCP connection with TLS connection or a basic non-TLS connection. The ability to choose the connection type is particularly useful for clients that have unreliable network connectivity or limited available bandwidth. In some use cases, low overhead and high bandwidth efficiency is more important than a secure connection.

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

    <listeners>

        <!-- Open to the outside world -->
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
            <name>open-world-listener</name>
        </tcp-listener>

        <!-- Only reachable for clients on the same machine -->
        <tcp-listener>
            <port>1884</port>
            <bind-address>127.0.0.1</bind-address>
            <name>same-machine-listener</name>
        </tcp-listener>

        <!-- Secure connection -->
        <tls-tcp-listener>
            <port>8883</port>
            <bind-address>0.0.0.0</bind-address>
            <name>secure-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>
            </tls>
        </tls-tcp-listener>

    </listeners>
    ...

</hivemq>
All HiveMQ MQTT listeners can be configured with connection overload protection.
Full example of multiple listener configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <listeners>

        <!-- Open to the outside world -->
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
            <connect-overload-protection>
                <!-- 2000 C/s == 2C/ms -->
                <connect-rate>2000</connect-rate>
                <connect-burst-size>4000</connect-burst-size>
            </connect-overload-protection>
        </tcp-listener>

        <!-- Only reachable for clients on the same machine -->
        <tcp-listener>
            <port>1884</port>
            <bind-address>127.0.0.1</bind-address>
            <name>same-machine-listener</name>
        </tcp-listener>

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

        <!-- Basic WebSocket connection -->
        <websocket-listener>
            <port>8000</port>
            <bind-address>0.0.0.0</bind-address>
            <path>/mqtt</path>
            <name>my-websocket-listener</name>
            <subprotocols>
                <subprotocol>mqttv3.1</subprotocol>
                <subprotocol>mqtt</subprotocol>
            </subprotocols>
            <allow-extensions>true</allow-extensions>
        </websocket-listener>

        <!-- Secure WebSocket connection -->
        <tls-websocket-listener>
            <port>8000</port>
            <bind-address>0.0.0.0</bind-address>
            <path>/mqtt</path>
            <subprotocols>
                <subprotocol>mqttv3.1</subprotocol>
                <subprotocol>mqtt</subprotocol>
            </subprotocols>
            <allow-extensions>true</allow-extensions>
            <tls>
                <keystore>
                    <path>/path/to/the/key/store.jks</path>
                    <password>password-keystore</password>
                    <private-key-password>password-key</private-key-password>
                </keystore>
                <client-authentication-mode>NONE</client-authentication-mode>
            </tls>
        </tls-websocket-listener>

    </listeners>
    ...

</hivemq>

TCP Listener

TCP listeners are the most common way to establish an MQTT connection. The HiveMQ broker and the MQTT client set up a standard TCP/IP connection on top of which the MQTT connection is established.

Unless otherwise specified, HiveMQ uses the IANA standard port for MQTT 1883.

For MQTT implementations such as web applications, we recommend the use of more sophisticated listeners such as secure Websocket listeners or TLS encrypted TCP listeners that provide a secure connection.
Table 2. TCP listener configuration properties
Property Name Default Description

port

The port used for TCP connections

bind-address

0.0.0.0

The host IP address on which the TCP listener is bound

name

tcp-listener-{port}

Optional setting to customize the name of the TCP listener

proxy-protocol

false

Optional setting to enables the support of the PROXY protocol

connect-overload-protection

Optional setting to configure the connection overload protection
Example TCP listener 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>
            <name>my-tcp-listener</name>
        </tcp-listener>
    </listeners>
    ...
</hivemq>

Secure TCP Listener

Transport Layer Security (TLS) and Secure Sockets Layer (SSL) provide a secure communication channel between an MQTT client and server. TLS and SSL are cryptographic protocols that use a handshake mechanism to negotiate various parameters and create a secure connection. After the handshake is complete, encrypted communication between the client and server prevents unauthorized access to any part of the communication.
For more information, see TLS/SSL - MQTT Security Fundamentals.

To enable TLS over TCP, add a tls-tcp-listener to the listeners section in the config.xml file of your HiveMQ installation. You can add an unlimited number of secure TCP listeners to your configuration file and bind to various network interfaces.

For MQTT over TLS, HiveMQ uses the IANA standard port for secure MQTT 8883.

The secure TCP listener has the same configuration options as the TCP Listener:

Table 3. Secure TCP listener configuration properties
Property Name Default Description

port

The port used for TCP connections

bind-address

0.0.0.0

The host IP address on which the Secure TCP listener is bound

name

tls-tcp-listener-{port}

Optional setting to customize the name of the Secure TCP listener

proxy-protocol

false

Optional setting to enables the support of the PROXY protocol

connect-overload-protection

Optional setting to configure the connection overload protection

tls

The TLS configuration for the listener

The tls element has the following properties:

Table 4. Available TLS configuration properties
Property Name Default Required Description

protocols

  • TLSv1.3

  • TLSv1.2

no

The enabled protocols.

NOTE: The default TLS protocol versions that are enabled on your system can vary based on the JDK that you use. For more information, see Communication Protocol.

cipher-suites

  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

  • TLS_RSA_WITH_AES_128_GCM_SHA256

  • TLS_RSA_WITH_AES_128_CBC_SHA

  • TLS_RSA_WITH_AES_256_CBC_SHA

no

The enabled cipher suites.
If desired, define specific cipher suites to limit the number of suites that are enabled.

NOTE: The available cipher suits are dependent on the SSL implementation that is used and not necessarily the same for all machines.

prefer-server-cipher-suites

The underlying SSL implementation determines how the cipher suite is selected

no

Optional setting that explicitly defines the criteria HiveMQ uses to pick a cipher suite for the MQTT listener.

  • false: HiveMQ uses the first cipher suite from the client list of cipher suites that both the server and the client support.

  • true: HiveMQ uses the first cipher suite from the server list of cipher suites that both the server and the client support.

client-authentication-mode

NONE

no

The way HiveMQ authenticates client certificates. The following options are available:

  • NONE: No client certificate is processed

  • OPTIONAL: If present, the client certificate is processed

  • REQUIRED: A client certificate must be present

handshake-timeout

10000

no

The number of milliseconds in which the SSL connection must be successfully established before the operation is halted

keystore.path

yes

The path to the key store where your certificate and private key are located

keystore.password

yes

The password to open the key store

keystore.private-key-password

no

The password for the private key (if applicable)

truststore.path

no

The path to the trust store that includes trusted client certificates

truststore.password

no

The password to open the trust store

concurrent-handshake-limit

-1

no

The maximum number of SSL handshakes that can be in progress at any time. When set to -1, HiveMQ processes one SSL handshake at a time (no concurrent handshakes are allowed). To permit concurrent SLL handshakes, set the property to a positive non-zero integer that indicates the desired maximum.

native-ssl

false

no

Defines whether HiveMQ uses BoringSSL for the TLS implementation of the listener instead of the TLS implementation of your JDK.

NOTE: BoringSSL is not compatible with some operating systems.

session-timeout

The underlying TLS implementation determines the default server TLS session timeout:

  • JDK: 24 hours.

  • BoringSSL: 5 minutes.

no

  • Positive value: Sets the TLS session timeout in seconds.

  • 0: Disables the TLS session.

The session-timeout setting has no impact when a combination of native-ssl and TLSv1.3 is used. If both of these values are set, there is no server-side state to regulate.
HiveMQ uses the event-driven client server framework Netty to implement TCP.
Example secure TCP listener 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>
                    <!-- Configuring the path to the key store -->
                    <path>/path/to/the/key/store.jks</path>
                    <!-- The password of the key store -->
                    <password>password-keystore</password>
                    <!-- The password of the private key -->
                    <private-key-password>password-key</private-key-password>
                </keystore>
            </tls>
        </tls-tcp-listener>
    </listeners>
    ...
</hivemq>

For step-by-step instructions on how to create and implement a self-signed Java Keystore for testing purposes, see HowTo configure server-side TLS with HiveMQ and Keytool.

Key stores in the JKS format can be used.

HiveMQ reloads key stores and trust stores during runtime. You do not need to restart HiveMQ when you add and remove client certificates from a trust store or change a server certificate in the key store. If the same master password is used, it is also possible to replace the key store or trust store file with no downtime.

Cipher Suite Preference for Secure TCP Listeners and Secure WebSocket Listeners (optional)

To establish a secure connection, HiveMQ and the MQTT client must successfully negotiate a mutually agreed upon cipher suite to encrypt and decrypt all communication between the client and HiveMQ. The selection of a single cipher suite takes place during the SSL handshake:

  1. To initiate a secure TCP connection, the MQTT client sends a ClientHello message to HiveMQ that contains a list of the cipher suites the client supports.

  2. Based on the cipher suite list in the ClientHello message, HiveMQ selects a cipher suite that both HiveMQ and the MQTT client support.

  3. HiveMQ responds to the MQTT client with a ServerHello message that contains the selected cipher suite.

To influence the way HiveMQ selects the cipher suite during the SSL handshake (step 2), you can add a prefer-server-cipher-suites to the tls configuration of the secure TCP listener or secure WebSocket listener:

  • When prefer-server-cipher-suites is set to true, HiveMQ selects the first cipher suite on the HiveMQ list of supported cipher suites that the client also supports.

    • Based on the following example cipher suite lists, HiveMQ must select TLS_RSA_WITH_AES_256_CBC_SHA because that is the first entry on the HiveMQ list of supported cipher suites that the MQTT client also supports.

  • When prefer-server-cipher-suites is set to false, HiveMQ selects the first cipher suite on the MQTT client list of supported cipher suites that HiveMQ also supports.

    • Based on the following example cipher suite lists, HiveMQ must select TLS_RSA_WITH_AES_128_CBC_SHA because that cipher suite is the first entry on the MQTT client list of supported cipher suites that also appears on the HiveMQ list.

  • When no prefer-server-cipher-suites value is set, the default of the underlying SSL implementation on which your HiveMQ instance runs determines whether the selection hierarchy is based on the order of the HiveMQ list or the MQTT client list.

    • Based on the following example cipher suite lists, when no preference is set, HiveMQ must select the cipher suite TLS_RSA_WITH_AES_256_CBC_SHA (if the underlying default is equivalent to true) or TLS_RSA_WITH_AES_128_CBC_SHA (if the underlying default is equivalent to false).

Example cipher suite list definitions
Example HiveMQ cipher suites list:
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
Example client cipher suites list:
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
View Cipher Suites in HiveMQ Log File

To view the cipher suites that are currently enabled for your HiveMQ listener and how the cipher suites are ordered, check your hivemq.log. The first cipher suite in the log entry, is the first cipher suite on the HiveMQ list of cipher suites:

Example HiveMQ log entry of the enabled cipher suites
2022-02-21 12:21:31,911 INFO  - Enabled cipher suites for TCP Listener with TLS at address 0.0.0.0 and port 8883: [TLS_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA]
Even when no cipher suites are explicitly defined in your HiveMQ configuration for a listener, you can check your hivemq.log to see all cipher suites that the underlying SSL implementation enables and how the cipher suites are ordered.

In general, you can interpret the order of the cipher suites from the log file as follows:

Example HiveMQ cipher suite ordering
<cipher-suites>
    <cipher-suite>TLS_RSA_WITH_AES_256_CBC_SHA</cipher-suite> <!-- First entry in HiveMQ cipher suite list-->
    <cipher-suite>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</cipher-suite>
    <cipher-suite>TLS_RSA_WITH_AES_128_CBC_SHA</cipher-suite> <!-- Last entry in HiveMQ cipher suite list-->
</cipher-suites>
Cipher Suite Preference Use Case Example

From a security perspective, it can be desirable to set a preference for a cipher suite order that you explicitly define in HiveMQ so that you can order the supported cipher suites from most secure to the least secure.

For example, if your use case includes legacy clients that only support weak cipher suites, a possible solution is to set a preference for the cipher suites of HiveMQ and explicitly define the cipher suites list so that the necessary weak cipher suites appear last in the list. This method enforces selection of secure cipher suites for newer clients but also permits the selection of specific weak/outdated cipher suites for your legacy clients.

The following configuration example defines the cipher suites that HiveMQ can accept and orders the list from secure cipher suites to weak cipher suites. Since the prefer-server-cipher-suites value is set to true, the HiveMQ cipher suite list determines the selection hierarchy. If you want to use strong cipher suites in general but need to support some weaker cipher suites for your legacy clients, this type of configuration is a useful option:

Example secure TCP listener with cipher suite preference configuration
<tls>
    ....
    <cipher-suites>
        <!-- cipher-suites section for new clients, are all considered secure in general -->
        <cipher-suite>most-secure-cipher-suite-for-new-clients</cipher-suite>
        <cipher-suite>...</cipher-suite>
        <cipher-suite>...</cipher-suite>
        <cipher-suite>least-secure-cipher-suite-for-new-clients</cipher-suite>

        <!-- section for legacy clients as they only support these outdated cipher suites, which are considered weak in general -->
        <cipher-suite>outdated-cipher-suite-1-for-legacy-clients</cipher-suite>
        <cipher-suite>...</cipher-suite>
        <cipher-suite>outdated-cipher-suite-n-for-legacy-clients</cipher-suite>
    </cipher-suites>
    <!-- works only with tls-tcp-listener and tls-websocket-listener -->
    <prefer-server-cipher-suites>true</prefer-server-cipher-suites>
</tls>

WebSockets

WebSocket is a network protocol that provides bidirectional communication between a browser and a web server.

HiveMQ implements all RFC6555 WebSocket standards and provides native support for all common WebSocket versions. The protocol was standardized in 2011 and all modern browsers provide built-in WebSocket support. Similar to MQTT, the WebSocket protocol is based on TCP. For more information, see WebSocket aligned browser versions.

When you use WebSockets with HiveMQ, you do not need a dedicated web server in front of a HiveMQ MQTT broker instance to forward the WebSocket connection. HiveMQ handles the HTTP WebSocket upgrade and the actual WebSockets transparently. The broker treats an MQTT client connection over WebSockets as equal to connections over a standard TCP connection.

HiveMQ also supports secure WebSockets. Secure WebSockets are a great way to increase security for your application. For more information, see secure WebSockets.

Native WebSocket Listener

MQTT over WebSockets enables the browser to leverage all MQTT features. To communicate with an MQTT broker over WebSockets, the MQTT broker must be able to handle native WebSockets. HiveMQ provides native WebSocket support.

To enable WebSockets, add a websocket-listener to the listeners section in the config.xml file of your HiveMQ installation.

When you add a WebSocket listener, you need to configure the properties of the websocket-listener configuration appropriately.
The tls element has the following properties:

Table 5. WebSocket listener configuration properties
Property Name Default Description

port

The port used for WebSocket connections

bind-address

0.0.0.0

The host IP address on which the WebSocket listener is bound

name

websocket-listener-{port}

Optional setting to customize the name of the WebSocket listener

subprotocols

  • mqttv3.1

  • mqtt

The subprotocols that the WebSocket can negotiate.

NOTE: When using Paho.js, you must set a subprotocol of mqttv3.1 or mqtt.

path

/mqtt

The last part of the path to the WebSocket. For the HiveMQ WebSocket listener, /mqtt routes to ws://broker.hivemq.com:8000/mqtt.

allow-extensions

true

Defines whether WebSocket extensions are allowed

proxy-protocol

false

Optional setting to enables the support of the PROXY protocol

connect-overload-protection

Optional setting to configure the connection overload protection
Example WebSocket listener configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <listeners>
        <websocket-listener>
            <port>8000</port>
            <bind-address>0.0.0.0</bind-address>
            <path>/mqtt</path>
            <name>my-websocket-listener</name>
            <subprotocols>
                <subprotocol>mqttv3.1</subprotocol>
                <subprotocol>mqtt</subprotocol>
            </subprotocols>
            <allow-extensions>true</allow-extensions>
        </websocket-listener>
        ...
    </listeners>
    ...
</hivemq>
The default subprotocols are mqttv3.1 and mqtt. The subprotocol setting mqtt represents MQTT 3.1.1 and MQTT 5. HiveMQ does not support other subprotocols.

Secure WebSocket Listener

With HiveMQ, you can seamlessly leverage Transport Layer Security (TLS) to use secure WebSockets with encryption of the whole connection.

To enable secure WebSockets, add a tls-websocket-listener to the listeners section in the config.xml file of your HiveMQ installation.

Secure WebSockets combine the properties of native WebSockets with the tls element of a secure TCP listener.

Table 6. Secure WebSocket listener configuration properties
Property Name Default Description

port

The port used for WebSocket connections

bind-address

0.0.0.0

The host IP address on which the WebSocket listener is bound

name

tls-websocket-listener-{port}

Optional setting to customize the name of the Secure WebSocket listener

subprotocols

  • mqttv3.1

  • mqtt

The subprotocols that the WebSocket can negotiate.

NOTE: When using Paho.js, you must set a subprotocol of mqttv3.1 or mqtt.

path

/mqtt

The last part of the path to the WebSocket. For the HiveMQ WebSocket listener, /mqtt routes to ws://broker.hivemq.com:8000/mqtt.

allow-extensions

true

Defines whether WebSocket extensions are allowed

proxy-protocol

false

Optional setting to enables the support of the PROXY protocol

connect-overload-protection

Optional setting to configure the connection overload protection

tls

The TLS configuration for the listener
Example secure WebSocket listener configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <listeners>
        <tls-websocket-listener>
            <port>8000</port>
            <bind-address>0.0.0.0</bind-address>
            <name>my-secure-websocket-listener</name>
            <path>/mqtt</path>
            <subprotocols>
                <subprotocol>mqttv3.1</subprotocol>
                <subprotocol>mqtt</subprotocol>
            </subprotocols>
            <allow-extensions>true</allow-extensions>
            <tls>
                <keystore>
                    <path>/path/to/the/key/store.jks</path>
                    <password>password-keystore</password>
                    <private-key-password>password-key</private-key-password>
                </keystore>
                <client-authentication-mode>NONE</client-authentication-mode>
            </tls>
        </tls-websocket-listener>
        ...
    </listeners>
    ...
</hivemq>
When you configure multiple listeners, you can use standard WebSockets and secure WebSockets simultaneously.

MQTT over WebSockets

Although connections over WebSockets are similar to standard TCP connections, there are some known issues. Many of these issues occur due to incomplete or incorrect WebSocket implementations in browsers:

  • Since MQTT is a binary protocol, HiveMQ only supports binary WebSocket frames. Use of a text WebSocket frame is not appropriate for a binary protocol such as MQTT. Most JavaScript libraries support binary WebSockets.

  • When you use secure WebSockets with a self-signed certificate, make sure your browser accepts the certificate. In most cases, you can browse directly to the endpoint (use https) and accept the certificate. Unfortunately, many browsers do not automatically provide support for accepting untrusted certificates for WebSockets.

  • Some browsers have severe bugs in the area of client certificate authentication. Although client certificate authentication is a great way to increase security, we recommended thorough testing of your solution on your target browsers.

  • Some Chrome versions have difficulty establishing a secure WebSocket connection if you have not accessed the resource with a classic HTTP GET method previously. To solve this issue, go to your browser window and send a request to the secure WebSocket listener directly https://{your-broker-ip}:{your-wss-port}. For example, https://localhost:8883.