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 .

The message transport protocol determines the required listener 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 with different protocols and bind to specific network interfaces. For example, configure HiveMQ to accept standard TCP connections on one port and secure TCP connections on another port.

After a client connects to HiveMQ, the client communicates through the broker with all other connected clients. The listener type 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 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 externally accessible interfaces.

When you configure multiple listeners, clients can opt for a secure 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 web-based MQTT implementations, we recommend secure Websocket listeners or TLS encrypted TCP listeners.

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 that enables PROXY protocol support
`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 that enables PROXY protocol support
`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:

Property Name Default Required Description

protocols

TLSv1.3
TLSv1.2

The enabled protocols.

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_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

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

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

TLS_RSA cipher suites are disabled by default in Java 21.0.10 and later versions due to lack of forward secrecy. Use ECDHE cipher suites for secure connections.

prefer-server-cipher-suites

The underlying SSL implementation determines how the cipher suite is selected

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

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

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 JKS keystore file that holds the server certificate and private key.
*Do not use when you configure PEM certificate files with keystore.key-path and keystore.cert-path.

keystore.password

yes*

The password for the keystore file.
*Use with keystore.path only.

keystore.private-key-password

The password for the private key (if applicable)

keystore.key-path

The path to a PEM-encoded private key file (.key or .pem). Use together with keystore.cert-path as an alternative to a keystore file. For more information, see PEM certificate files.

keystore.cert-path

The path to a PEM-encoded X.509 certificate file (.crt or .pem). The file can contain the full certificate chain, with the server certificate first. Use together with keystore.key-path.

keystore.ca-path

Optional path to a PEM-encoded CA certificate bundle that completes the certificate chain of keystore.cert-path with intermediate or root CA certificates.

truststore.path

The path to the JKS truststore file that holds the trusted client certificates.
Do not use with truststore.cert-path.

truststore.password

The password for the truststore file.

truststore.cert-path

The path to a PEM-encoded bundle of one or more trusted CA certificates. Use as an alternative to a truststore file for client certificate authentication.

concurrent-handshake-limit

-1

The maximum number of SSL handshakes that can be in progress simultaneously. The default setting, -1 , allows an unlimited number of SSL handshakes.
To allow up to a specific number of concurrent SSL handshakes, set the property to a positive integer that indicates the desired maximum.
If set to 1, HiveMQ processes one SSL handshake at a time (no concurrent handshakes are allowed).
When no value is set, or a negative integer is entered, HiveMQ allows an unlimited number of concurrent SSL handshakes.

native-ssl

false

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

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.

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.

Keystores in the JKS format can be used. Alternatively, you can configure PEM certificate files directly, without a keystore file.

HiveMQ reloads keystores, truststores, and PEM certificate files during runtime. You do not need to restart HiveMQ after you change a certificate. If the master password stays the same, you can also replace the entire keystore or truststore file without downtime.

PEM Certificate Files (Alternative to Keystores)

HiveMQ can load the TLS server certificate and private key directly from PEM-encoded files (.pem, .crt, .key). You do not need a Java keystore. This option removes the keytool conversion step in environments that issue certificates as PEM files. For example, in Kubernetes and OpenShift deployments in which cert-manager provides certificates as mounted secrets (tls.key, tls.crt, ca.crt).

PEM certificate files are not available in the HiveMQ Community Edition.

To use PEM certificate files, configure key-path and cert-path in the keystore section instead of path and password. The two configuration styles are mutually exclusive within one keystore or truststore tag.

Example secure TCP listener configuration with PEM certificate files

<?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>
                    <!-- The PEM-encoded private key -->
                    <key-path>/etc/certificates/tls.key</key-path>
                    <!-- The PEM-encoded server certificate (or full chain, server certificate first) -->
                    <cert-path>/etc/certificates/tls.crt</cert-path>
                    <!-- Optional: CA certificates that complete the chain -->
                    <ca-path>/etc/certificates/ca.crt</ca-path>
                </keystore>
                <!-- Optional: PEM CA bundle with trusted client certificates for client certificate authentication -->
                <truststore>
                    <cert-path>/etc/certificates/client-ca.crt</cert-path>
                </truststore>
            </tls>
        </tls-tcp-listener>
    </listeners>
    ...
</hivemq>

The following rules apply:

RSA and EC private keys in PKCS#8 (BEGIN PRIVATE KEY) and traditional OpenSSL (BEGIN RSA/EC PRIVATE KEY) formats are supported. Ed25519 and Ed448 keys are also supported but require the JDK SSL provider (native-ssl disabled); this applies to key stores as well. OpenSSL text preambles such as Bag Attributes, CRLF line endings, and a missing trailing newline are tolerated. The files must not start with a UTF-8 byte order mark (BOM).
For an encrypted private key, set the passphrase with the optional private-key-password tag. Keys that cert-manager and comparable issuers produce are typically unencrypted.
cert-path can contain a single certificate or the full certificate chain, with the server certificate first. If ca-path is set, HiveMQ builds the served certificate chain from both files and automatically removes duplicate and unrelated certificates.
A single PEM file that contains both the private key and the certificate can be referenced by key-path and cert-path at the same time. A ca-path is still needed when that file does not contain the full certificate chain.
Relative paths in listener configurations are resolved against the HiveMQ home folder. In the REST API, Control Center, and cluster transport configurations, use absolute paths.
At startup, HiveMQ verifies that the private key matches the configured certificate. On a mismatch — as with every other key material problem, for example, a missing file or a private key that cannot be decrypted — HiveMQ logs an error and shuts down.
HiveMQ does not check certificate validity periods: an expired or not-yet-valid certificate is loaded and served without a warning.
For MQTT listeners, the HiveMQ REST API, and the HiveMQ Control Center, HiveMQ monitors the PEM files at runtime exactly like key store files. When a certificate rotation replaces the file contents, for example, on renewal of a cert-manager secret, HiveMQ picks up the new certificate without a restart. If a monitored PEM file becomes unreadable at runtime, HiveMQ logs a warning on every check and continues to serve the previously loaded certificate.
The cluster transport reads its TLS configuration only at startup. Certificate rotation on the cluster transport requires a restart of the node.

The key-path, cert-path, ca-path, and truststore.cert-path options are also available for other TLS configurations. You can use the options for secure WebSocket listeners, the HiveMQ Control Center, the HiveMQ REST API, and the HiveMQ cluster transport.

The HiveMQ diagnostic archive never includes the referenced key and certificate files, and the private-key-password value is redacted in the configuration file that the archive contains.

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:

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.
Based on the cipher suite list in the ClientHello message, HiveMQ selects a cipher suite that both HiveMQ and the MQTT client support.
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_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 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_ECDHE_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_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 (if the underlying default is equivalent to true) or TLS_ECDHE_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_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Example client cipher suites list:

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

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

2026-02-16 12:21:31,911 INFO  - Enabled cipher suites for TCP Listener with TLS at address 0.0.0.0 and port 8883: [TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256]

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>TTLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</cipher-suite> <!-- First entry in HiveMQ cipher suite list-->
    <cipher-suite>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</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:

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.

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 that enables PROXY protocol support

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.

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.

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 that enables PROXY protocol support

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.