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 bi-directional 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.

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>

If you do not define a TCP listener name in your configuration, HiveMQ uses the default name: tcp-listener-{port}.

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.

When you add a secure TCP listener, you need to configure the tls element in the tls-tcp-listener appropriately.
The tls element has the following properties:

Table 2. Available TLS configuration properties
Property Name	Default	Required	Description
`protocols`	`TLSv1.3` `TLSv1.2`	no	Optional setting to explicitly define the protocols HiveMQ enables. NOTE: The default TLS versions that HiveMQ enables correspond to the default TLS versions of your JDK. If you need to support a legacy TLS version, see Communication Protocol.
`cipher-suites`		no	Optional setting to explicitly define the enabled cipher-suites. If desired, you can 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. The cipher-suites HiveMQ enables by default correspond to the default cipher-suites of your JDK.
`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.

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>

If you do not define a secure TCP listener name in your configuration, HiveMQ uses the default name: tls-tcp-listener-{port}.

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.

WebSockets

WebSocket is a network protocol that provides bi-directional 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 3. WebSocket listener configuration properties
Property Name	Default	Description
`bind-address`		The IP address on which WebSockets is located
`port`		The port used for WebSockets
`name`		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

If you do not define the name of the WebSocket listener in your configuration, HiveMQ uses the default name: websocket-listener-{port}.

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.

If you do not define the name of the secure WebSocket listener in your configuration, HiveMQ uses the default name: 'tls-websocket-listener-{port}'.

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.