Listeners

By default HiveMQ binds to port 1883, which is the default MQTT port.

HiveMQ can be configured to use multiple listeners for different protocols. These listeners can be bound to specific network interfaces.

The following listener types are available:

Table 1. Available listener types
Listener Description

TCP Listener

A listener for MQTT which uses TCP

Secure TCP Listener

A secure listener for MQTT which uses TLS

WebSocket Listener

A listener for MQTT over WebSockets

Secure WebSocket Listener

A secure listener for MQTT over secure WebSockets (TLS)

Multiple Listeners

HiveMQ can be configured to run with multiple listeners. It’s e.g. possible to handle standard TCP connections on one port and secure 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. Clients can decide if they want to use secure or a "standard" TCP, non TLS connection. This is extremely useful when some clients only have a unreliable network connectivity and/or very limited available bandwidth where every additional byte overhead matters and bandwidth efficiency is more important than a secure connection. In this case, these clients can connect to HiveMQ via the unsecured port while other clients can use a secure connection via the TLS enabled port.

Multiple Listeners Example
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">

    <listeners>

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

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

        <!-- Secure connection -->
           <tls-tcp-listener>
               <port>8883</port>
               <bind-address>0.0.0.0</bind-address>
               <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>
You can bind different listeners to different network interfaces. If you want for example to use a plain MQTT listener only to network interfaces for internal networks and MQTT-TLS listeners to an internet reachable interface, this is easy to configure.
All listener can be configured with a connection overload protection.

TCP Listener

The most standard and common way of establishing an MQTT connection is to it via TCP listeners. Broker and client establish a standard TCP/IP connection on top of which the MQTT connection is established.
More sophisticated listeners options, such as Websocket Listeners that can be used for web application or TLS encrypted TCP Listeners that provide a secure connection, can be found further down this chapter.

Adding a TCP listener
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">

    ...
    <listeners>
        ...
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
        </tcp-listener>
    </listeners>
    ...
</hivemq>
Standard port
The IANA standard 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 an arbitrary number of tls-tcp-listener`s to your config 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

Activate the usage of the native SSL implementation (BoringSSL).
Adding a secure TCP listener
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">

    ...
    <listeners>
        ...
        <tls-tcp-listener>
            <port>8883</port>
            <bind-address>0.0.0.0</bind-address>
            <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>

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.

WebSockets

HiveMQ offers native support for all common WebSocket versions. All major browsers are supported. Here is an exhaustive list of all supported browsers.

When using WebSockets with HiveMQ, there is no need to use a separate web server for handling the HTTP requests and the WebSocket upgrade, HiveMQ handles this transparently.

There is also support for secure WebSockets out of the box. Secure WebSockets allow secure communication over WebSockets and are a great way to increase security for your application. See secure WebSockets for more information.

Native WebSocket Listener

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

Table 3. Properties of a WebSocket listener
Property Name Description

bind-address

The IP address on which WebSockets will be bound

port

The port used for WebSockets.

subprotocols

The subprotocols used for WebSockets. When using Paho.js this should be mqttv3.1 or mqtt

path

The path for the WebSocket

allow-extensions

Defines if WebSocket extensions are allowed

The default sub-protocols are mqttv3.1 and mqtt. If you really want to use a WebSocket sub-protocol other than mqttv3.1 and mqtt, set subprotocols to any value you like. Please bear in mind that HiveMQ only implements MQTT 3.1 and MQTT 3.1.1.

The following example shows a configuration of the WebSocket listener configuration:

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

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

Secure WebSocket Listener

To enable secure WebSockets, use a tls-websocket-listener. It consists of the native WebSockets properties and the same <tls> element as the secure TCP listener.

The following example shows the configuration of a secure WebSocket listener configuration:

Secure WebSocket Listener
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">

   <listeners>
      <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>
You can use standard WebSockets and secure WebSockets simultaneously when configuring different listeners.

Gotchas

Although a connection over WebSockets is not much different to standard TCP connections for HiveMQ, there are some gotchas. Most of them occur due to incomplete and incorrect WebSocket implementations in browsers, which you should be aware of:

  • Only binary WebSocket frames are supported as MQTT is a binary protocol. All MQTT Javascript libraries should support Binary WebSockets [1].

  • If you are using secure WebSockets, make sure that you don’t use a self signed certificate or that your browser accepts the certificate. In most cases you can browse directly to the Endpoint (use https!) and accept the certificate. Unfortunately most browsers do not support accepting untrusted certificates for WebSockets out of the box.

  • Client Certificate Authentication *should* work in theory but most browsers have severe bugs in this area at the time of writing. Although client certificate authentication is a great way to increase security, it is recommended to test thoroughly if your targeted browsers work for you.

  • If you are using secure WebSockets, many Chrome versions have issues with establishing the connection if you did not 'visit' the resource via classic HTTP GET first. The solution for the issue can be found in this support forum thread.

Advanced Listener Configuration

Like all configuration options of HiveMQ, the following advanced listener configuration options are set to a sensible value by default. Unless you have a specific reason for changing them and know exactly what you are doing, we would strongly recommend leaving them at the default values. These values will be working well for most MQTT use cases.

Socket Options

It is possible to add a <socket-options> tag to every listener. This tag exposes some low-level networking options. Further information can be found here or through the man setsockopt and man 7 socket bash commands. None of the options are required and null is the default value.

The following options are exposed:

Table 4. Available socket options
Option Description

socket-receive-buffer-size

Sets the maximum socket receive buffer size in bytes (SO_RCVBUF), the kernel doubles this value. The minimum (doubled) is 2048.

socket-send-buffer-size

Sets the maximum socket send buffer size in bytes (SO_SNDBUF), the kernel doubles this value. the minimum (doubled) is 256.
Socket options example
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="hivemq-config.xsd">

    <listeners>
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
            <socket-options>
                <!-- 64 kB -->
                <socket-receive-buffer-size>65536</socket-receive-buffer-size>
                <!-- 32 kB -->
                <socket-send-buffer-size>32768</socket-send-buffer-size>
            </socket-options>
        </tcp-listener>
    </listeners>
   ...

</hivemq>
A good TCP buffer size is double the value for delay times bandwidth. If your ping gives you a round trip time, which is double the delay, of 1s and your bandwidth is 1Gb/s ⇒ buffer-size should be set to 1Gb = 125MB ⇒ socket-receive-buffer-size and socket-send-buffer-size should be set to 62.500.000 (half the desired value).
A large socket buffer size can severely tax your main memory.

Client write buffer options

The <client-write-buffer> enables the fine grained configuration of the write buffer behavior for each connection served by this listener.

Table 5. Available client write buffer options
Option Default value Description

high-threshold

65536

The high fill state of the write buffer for each client connection, measured in bytes. If this state is reached for a client HiveMQ will prevent additional buffering of writes. QoS 0 messages will be dropped.

low-threshold

32768

The low fill state of the write buffer for each client connection, measured in bytes. If the write buffer previously exceeded the write-buffer-high-threshold, buffering of writes will resume once it drops below the write-buffer-low-threshold.
The <low-threshold> must be grater than 0 (zero) and the <high-threshold> must be grater than the <low-threshold>.
Client write buffer example
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="hivemq-config.xsd">

    <listeners>
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
            <client-write-buffer>
                <high-threshold>98304</high-threshold>
                <low-threshold>65536</low-threshold>
            </client-write-buffer>
        </tcp-listener>
    </listeners>
   ...

</hivemq>
If HiveMQ should resume immediately writing to the buffer, when it becomes available again, set the <low-threshold> close to the <high-threshold>.
1. It would hardly make sense to use Text WebSocket Frames for a binary protocol like MQTT.