HiveMQ Edge MQTT Listeners

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

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

HiveMQ Edge can be configured to use multiple listeners for different message transfer protocols. Depending on the message transport protocol you use, the listener requires different configuration parameters.

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

Table 1. Available HiveMQ Edge MQTT listener types
Listener	Description
TCP Listener	A listener for MQTT that uses TCP.
Secure TCP Listener	A secure listener for MQTT that uses TLS.
WebSocket Listener	A listener for MQTT over WebSockets.
Secure WebSocket Listener	A secure listener for MQTT over secure WebSockets (TLS).
UDP Listener	A listener for MQTT-SN that uses UDP.

Multiple HiveMQ Edge Listeners

HiveMQ Edge can be configured to run with multiple listeners.

For example, you can configure HiveMQ Edge to accept standard TCP connections on one port and secure TCP connections on another port. This is completely transparent and all clients can communicate among themselves via Publish/Subscribe regardless how they are connected to the broker.

Once a client connects to HiveMQ Edge, the client can communicate through the broker with all other connected clients. The type of listener over which the client connects to HiveMQ Edge 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. For some use cases, low overhead and high bandwidth efficiency can provide more benefits than a secure connection.

Example multiple listener configuration

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

    <mqtt-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>

    </mqtt-listeners>
   ...

</hivemq>

TCP Listener

TCP listeners are the most common way to establish an MQTT connection. In this case, the HiveMQ Edge MQTT broker and MQTT client establish a standard TCP/IP connection on top of which the MQTT connection is established.

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

Example configuration to add a TCP listener

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

    ...
    <mqtt-listeners>
        ...
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
            <name>my-tcp-listener</name>
        </tcp-listener>
    </mqtt-listeners>
    ...
</hivemq>

Standard MQTT port

The standard Internet Assigned Numbers Authority (IANA) port for MQTT is 1883

Secure TCP Listener

To enable TLS (over TCP), you need to add a tls-tcp-listener to the listeners in the config.xml file. You can add multiple tls-tcp-listener configurations to your config.xml file with different network interface bindings.

Secure TCP Listeners need to have a proper configuration for the XML tls element. The tls element has the following properties:

Table 2. TLS element options
Name	Default	Mandatory	Description
`protocols`	`All protocols enabled by Netty`	`no`	The enabled protocols
`cipher-suites`	`All cipher suites enabled by Netty`	`no`	The enabled cipher-suites
`client-authentication-mode`	`"NONE"`	`no`	The client authentication mode, possibilities are NONE, OPTIONAL (client certificate is used if presented), REQUIRED (client certificate is required)
`handshake-timeout`	`10000`	`no`	The SSL handshake timeout in milliseconds
`keystore.path`	`none`	`yes`	The path to the key store where your certificate and private key are included
`keystore.password`	`none`	`yes`	The password to open the key store
`keystore.private-key-password`	`none`	`no`	The password for the private key (if any)
`truststore.path`	`none`	`no`	The path for the trust store which includes trusted client certificates
`truststore.password`	`none`	`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 (set to a positive non-zero integer to activate)
`native-ssl`	`false`	`no`	Activates the usage of the native SSL implementation (BoringSSL)

Example configuration to add a secure TCP listener

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

    ...
    <mqtt-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>
    </mqtt-listeners>
    ...
</hivemq>

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

A detailed description on how to create and implement a self-signed Java Keystore for testing purposes can found in the HowTos section.

Standard port

The IANA standard port for MQTT over TLS is 8883

Key stores in the JKS format can be used.

Autoreload

Key and trust stores are reloaded during runtime. This means for you that adding or removing client certificates from the trust store or changing the server certificate in the key store can be done without downtime. Even the replacing of the key and trust store file is possible if the same master password is used.

UDP Listener

UDP listeners are the most common way to establish an MQTT-SN connection. In this case, the HiveMQ broker and the MQTT client establish a two-way datagram conversation on top of which the MQTT-SN connection is established.

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

Example configuration to add a UDP listener

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

    ...
    <mqtt-sn-listeners>
        ...
        <udp-listener>
            <port>2442</port>
            <bind-address>0.0.0.0</bind-address>
            <name>my-udp-listener</name>
        </udp-listener>
    </mqtt-sn-listeners>
    ...
</hivemq>

Standard MQTT-SN port

HiveMQ Edge exposes the standard MQTT-SN port 2442.

WebSockets

HiveMQ Edge offers native support for all common WebSocket versions. All major browsers are supported. For more information, see WebSocket browser support.

When you use WebSockets with HiveMQ Edge, there is no need to use a separate webserver to handle HTTP requests and the WebSocket upgrade. HiveMQ handles the requests and upgrades transparently.

HiveMQ Edge also supports secure WebSockets out of the box. Secure WebSockets allow secure communication over WebSockets and are a great way to increase security for your application. For more information, see secure WebSockets.

Native WebSocket Listener

To enable WebSockets, you need to specify a WebSocket listener. The following properties can be configured to enable WebSockets:

Table 3. Properties of a WebSocket listener
Property Name	Description
`bind-address`	The IP address on which WebSockets is bound.
`port`	The port used for WebSockets.
`name`	The name of the listener. The default setting is `websocket-listener-{port}`.
`subprotocols`	The subprotocols used for WebSockets. When using Paho.js, use `mqttv3.1` or `mqtt`.
`path`	The path for the WebSocket.
`allow-extensions`	Defines whether WebSocket extensions are allowed.

The default sub-protocols are mqttv3.1 and mqtt. If your really use case requires the use of a WebSocket subprotocol other than mqttv3.1 or mqtt, you can set subprotocols to some other value.
However, HiveMQ only implements MQTT 3.1, MQTT 3.1.1, and MQTT 5.

The following example shows a WebSocket listener configuration:

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

WebSocket Listener

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

   <mqtt-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>
       ...
   </mqtt-listeners>
    ...
</hivemq>

Secure WebSocket Listener

To enable secure WebSockets, add a tls-websocket-listener.

Secure WebSockets combine native WebSockets properties and the same <tls> element as the secure TCP listener.

The following example shows a secure WebSocket listener configuration:

If you do not define the name of the secure WebSocket listener in your configuration, HiveMQ Edge 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">

   <mqtt-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>
       ...
   </mqtt-listeners>
    ...
</hivemq>

When you configure multiple listeners, you can use standard WebSockets and secure WebSockets simultaneously.

MQTT over WebSockets

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

Since MQTT is a binary protocol, HiveMQ Edge 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.
If you have not accessed the resource with a classic HTTP GET method previously, some Chrome versions have difficulty establishing a secure WebSocket connection. 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.