Skip to main content
Listeners define the network interfaces and ports on which HiveMQ accepts client connections. HiveMQ supports multiple listener types to accommodate different protocols and security requirements.

​
Listener Types

HiveMQ Community Edition supports four types of listeners:
  1. TCP Listener - Standard MQTT over TCP
  2. TLS TCP Listener - MQTT over TCP with TLS/SSL encryption
  3. WebSocket Listener - MQTT over WebSockets
  4. TLS WebSocket Listener - MQTT over WebSockets with TLS/SSL encryption

​
TCP Listener

The basic TCP listener for unencrypted MQTT connections.

​
Configuration

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

​
Options

OptionTypeRequiredDefaultDescription
portInteger (0-65535)Yes-The port to listen on
bind-addressStringNo0.0.0.0The IP address to bind to
nameStringNo-A descriptive name for the listener

​
TLS TCP Listener

TCP listener with TLS/SSL encryption for secure MQTT connections.

​
Configuration

<listeners>
    <tls-tcp-listener>
        <port>8883</port>
        <bind-address>0.0.0.0</bind-address>
        <name>my-tls-listener</name>
        <tls>
            <keystore>
                <path>/path/to/keystore.jks</path>
                <password>keystore-password</password>
                <private-key-password>key-password</private-key-password>
            </keystore>
            <client-authentication-mode>NONE</client-authentication-mode>
        </tls>
    </tls-tcp-listener>
</listeners>

​
TLS Options

OptionTypeRequiredDefaultDescription
keystore.pathStringYes-Path to the Java keystore file
keystore.passwordStringYes-Keystore password
keystore.private-key-passwordStringYes-Private key password
truststore.pathStringNo-Path to the truststore file
truststore.passwordStringNo-Truststore password
client-authentication-modeEnumNoNONEClient certificate authentication: NONE, OPTIONAL, REQUIRED
handshake-timeoutIntegerNo10000TLS handshake timeout in milliseconds
protocolsListNoJVM defaultsEnabled TLS protocols
cipher-suitesListNoJVM defaultsEnabled cipher suites
prefer-server-cipher-suitesBooleanNo-Whether to prefer server cipher suites

​
Client Authentication

To require client certificates, configure a truststore and set the authentication mode: 
<tls>
    <keystore>
        <path>/path/to/keystore.jks</path>
        <password>keystore-password</password>
        <private-key-password>key-password</private-key-password>
    </keystore>
    <truststore>
        <path>/path/to/truststore.jks</path>
        <password>truststore-password</password>
    </truststore>
    <client-authentication-mode>REQUIRED</client-authentication-mode>
</tls>

​
WebSocket Listener

MQTT over WebSockets for browser-based clients.

​
Configuration

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

​
Options

OptionTypeRequiredDefaultDescription
portInteger (0-65535)Yes-The port to listen on
bind-addressStringNo0.0.0.0The IP address to bind to
pathStringNo/mqttThe WebSocket endpoint path
nameStringNo-A descriptive name for the listener
subprotocolsListNo-Allowed WebSocket subprotocols
allow-extensionsBooleanNofalseWhether to allow WebSocket extensions

​
TLS WebSocket Listener

WebSocket listener with TLS/SSL encryption.

​
Configuration

<listeners>
    <tls-websocket-listener>
        <port>8443</port>
        <bind-address>0.0.0.0</bind-address>
        <path>/mqtt</path>
        <name>my-secure-websocket-listener</name>
        <tls>
            <keystore>
                <path>/path/to/keystore.jks</path>
                <password>keystore-password</password>
                <private-key-password>key-password</private-key-password>
            </keystore>
        </tls>
    </tls-websocket-listener>
</listeners>
The TLS configuration options are the same as for TLS TCP listeners.

​
Multiple Listeners

You can configure multiple listeners of different types: 
<listeners>
    <tcp-listener>
        <port>1883</port>
        <bind-address>0.0.0.0</bind-address>
    </tcp-listener>
    
    <tls-tcp-listener>
        <port>8883</port>
        <bind-address>0.0.0.0</bind-address>
        <tls>
            <keystore>
                <path>/path/to/keystore.jks</path>
                <password>password</password>
                <private-key-password>password</private-key-password>
            </keystore>
        </tls>
    </tls-tcp-listener>
    
    <websocket-listener>
        <port>8000</port>
        <bind-address>0.0.0.0</bind-address>
        <path>/mqtt</path>
    </websocket-listener>
</listeners>

​
Best Practices

  • Use TLS listeners for production environments
  • Bind to specific IP addresses instead of 0.0.0.0 when possible
  • Use descriptive names for listeners to aid in debugging
  • Configure appropriate timeouts for your use case
  • Enable client authentication for enhanced security

Build docs developers (and LLMs) love

Get started for freeTalk to us