MQTT Protocol Listeners

Loading…

MQTT Protocol Listeners

Relevant source files

• mosquitto.conf

Purpose and Scope

This document describes the MQTT listener configuration in the Mosquitto broker, specifically the two listeners defined in mosquitto.conf:1-6 It explains the purpose, protocol, and routing behavior of each listener. For broader Mosquitto broker configuration, see Mosquitto Configuration. For access control settings, see Anonymous Access. For Cloudflare tunnel routing configuration, see Cloudflared Tunnel Service.

Sources : mosquitto.conf, README.md

Listener Configuration Overview

The Mosquitto broker is configured with two distinct listeners, each serving different transport protocols and use cases. Both listeners are defined in mosquitto.conf:1-6 and operate simultaneously within the mosquitto container.

<old_str>

TCP Listener"] end 
    
    
    subgraph external["External Network"]
        Internet["Public Internet"]
    end
    
    OtherContainer -->|"Direct MQTT/TCP"| MosquittoPort1883
    Internet -.->|"Not Accessible"| MosquittoPort1883
    
    
    
    **Listener Configuration Structure**
    
    | Listener | Port | Protocol | Anonymous Access | Primary Use Case |
    |----------|------|----------|------------------|------------------|
    | <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1" min=1  file-path="mosquitto.conf">Hii</FileRef> | 1883 | Standard MQTT/TCP | Enabled globally <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2" min=2  file-path="mosquitto.conf">Hii</FileRef> | Direct MQTT client connections |
    | <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L5" min=4 max=5 file-path="mosquitto.conf">Hii</FileRef> | 9001 | MQTT over WebSockets | Enabled globally <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2" min=2  file-path="mosquitto.conf">Hii</FileRef> | Browser-based clients, Cloudflare tunnel |
    
    **Sources**: mosquitto.conf
    
    ---
    
    ## Listener 1883: Standard MQTT TCP
    
    The first listener, configured at <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1" min=1  file-path="mosquitto.conf">Hii</FileRef> binds to port 1883 and provides standard MQTT protocol over TCP. This is the default MQTT port and is used by most native MQTT client libraries.
    
    ### Configuration Directives
    
    

listener 1883 allow_anonymous true
    
    
    **Directive Breakdown**:
    - `listener 1883` <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1" min=1  file-path="mosquitto.conf">Hii</FileRef>: Binds the Mosquitto broker to TCP port 1883
    - `allow_anonymous true` <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2" min=2  file-path="mosquitto.conf">Hii</FileRef>: Applies globally to all listeners, allowing clients to connect without authentication
    
    ### Protocol Characteristics
    
    This listener implements the standard MQTT 3.1.1 and MQTT 5.0 protocols over raw TCP connections. It supports:
    - Binary MQTT protocol framing
    - Persistent TCP connections
    - Quality of Service (QoS) levels 0, 1, and 2
    - Last Will and Testament (LWT) messages
    - Retained messages
    
    ### Network Accessibility
    
    The 1883 listener is **not** directly exposed through the Cloudflare tunnel in the current configuration. It operates only within Docker's internal network, accessible to other containers in the same Docker Compose stack.
    
    ```mermaid
    graph LR
        subgraph "Docker Internal Network"
            OtherContainer["Other Docker Container"]
            MosquittoPort1883["mosquitto:1883<br/>TCP Listener"]
        end
        
        subgraph "External Network"
            Internet["Public Internet"]
        end
        
        OtherContainer -->|"Direct MQTT/TCP"| MosquittoPort1883
        Internet -.->|"Not Accessible"| MosquittoPort1883
    

**Sources** : mosquitto.conf, README.md

* * *

## Listener 9001: MQTT over WebSockets

The second listener, configured at [mosquitto.conf:4-5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L5) binds to port 9001 and provides MQTT protocol encapsulated over WebSockets. This is the primary listener exposed to external clients via the Cloudflare tunnel.

### Configuration Directives
    
    
    listener 9001
    protocol websockets
    

**Directive Breakdown** :

  * `listener 9001` [mosquitto.conf4](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L4): Binds the Mosquitto broker to TCP port 9001
  * `protocol websockets` [mosquitto.conf5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L5-L5): Configures this listener to accept WebSocket connections with MQTT payloads



### Protocol Characteristics

This listener encapsulates MQTT protocol messages within WebSocket frames, enabling:

  * HTTP/WebSocket upgrade handshake
  * Browser-based MQTT clients (JavaScript)
  * Compatibility with web proxies and CDNs
  * TLS/SSL termination at the proxy layer (Cloudflare)



The WebSocket protocol wrapper does not alter the MQTT protocol itself; it only provides an HTTP-compatible transport layer.

### Cloudflare Tunnel Routing

The 9001 listener is configured as the target for the Cloudflare tunnel in the Zero Trust dashboard. The tunnel configuration specifies `mosquitto:9001` as the service URL [README.md62](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L62-L62) routing external MQTT WebSocket connections through the `cloudflared` container to this listener.


### Network Accessibility

Unlike the 1883 listener, the 9001 listener is indirectly exposed to the public internet through the Cloudflare tunnel. The routing path is:

  1. External client connects to Cloudflare public hostname
  2. Cloudflare Edge routes to `cloudflared` container via tunnel
  3. `cloudflared` proxies HTTP traffic to `mosquitto:9001`
  4. Mosquitto 9001 listener accepts WebSocket connection



**Sources** : mosquitto.conf, README.md

* * *

## Traffic Routing Architecture

The following diagram illustrates how traffic is routed to each listener based on the source and transport protocol:


**Routing Configuration References** :

  * Cloudflare tunnel target: `mosquitto:9001` [README.md62](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L62-L62)
  * WebSocket listener: [mosquitto.conf:4-5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L5)
  * TCP listener: [mosquitto.conf1](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1)
  * Container name resolution: `mosquitto` from `docker-compose.yml`



**Sources** : mosquitto.conf, README.md

* * *

## Configuration Reference

### Listener Directive Syntax

The `listener` directive defines a network interface and port for the broker to bind to:
    
    
    listener <port> [bind_address]
    

**Current Configuration** :

  * [mosquitto.conf1](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1): `listener 1883` \- Binds to port 1883 on all interfaces (no bind_address specified)
  * [mosquitto.conf4](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L4): `listener 9001` \- Binds to port 9001 on all interfaces



### Protocol Directive

The `protocol` directive specifies the transport protocol for a listener:
    
    
    protocol <mqtt|websockets>
    

**Current Configuration** :

  * Listener 1883: No protocol directive (defaults to `mqtt`)
  * [mosquitto.conf5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L5-L5): `protocol websockets` \- Configures listener 9001 for WebSocket transport



### Anonymous Access Directive

The `allow_anonymous` directive controls whether clients can connect without authentication:
    
    
    allow_anonymous <true|false>
    

**Current Configuration** :

  * [mosquitto.conf2](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2): `allow_anonymous true` \- Applies globally to all listeners



This directive appears once and affects both listeners. For production deployments requiring authentication, this should be set to `false` and appropriate authentication mechanisms configured. See [Anonymous Access](2-1-2-authentication-and-access-control.md) for detailed security implications.

### Configuration Interaction Matrix

Configuration Aspect| Listener 1883| Listener 9001  
---|---|---  
**Port**|  1883 [mosquitto.conf1](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1)| 9001 [mosquitto.conf4](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L4)  
**Protocol**|  MQTT/TCP (implicit default)| WebSockets [mosquitto.conf5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L5-L5)  
**Anonymous Access**|  Enabled [mosquitto.conf2](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2)| Enabled [mosquitto.conf2](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2)  
**Cloudflare Routing**|  Not configured| Configured [README.md62](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L62-L62)  
**External Accessibility**|  Docker internal only| Via Cloudflare tunnel  
  
**Sources** : mosquitto.conf, README.md

* * *

## Use Case Selection

### When to Use Listener 1883 (TCP)

  * **Native MQTT client libraries** : Python Paho, Mosquitto C library, MQTT.js with TCP
  * **High-performance IoT devices** : Minimal protocol overhead
  * **Internal Docker services** : Direct container-to-container communication
  * **Legacy MQTT applications** : Standard MQTT port compatibility



### When to Use Listener 9001 (WebSockets)

  * **Browser-based clients** : JavaScript MQTT clients in web applications
  * **Cloudflare tunnel access** : External clients connecting via the public hostname
  * **Firewall-restricted networks** : HTTP/WebSocket traffic often allowed through corporate firewalls
  * **CDN/proxy compatibility** : Works with HTTP-based reverse proxies



### Current System Configuration

The current deployment configures the Cloudflare tunnel to route exclusively to listener 9001. This means:

  * External clients **must** use MQTT over WebSockets
  * The public hostname [README.md60](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L60-L60) resolves to listener 9001
  * Listener 1883 remains available only for internal Docker network access



To expose listener 1883 externally, additional Cloudflare tunnel configuration would be required, though this is uncommon since WebSocket transport provides broader compatibility.

**Sources** : mosquitto.conf, README.md

Dismiss

Refresh this wiki

Enter email to refresh
<hr style="margin-top: 3rem; border: none; border-top: 1px solid #e0e0e0;">

<div class="doc-footer" style="text-align: center; padding: 1.5rem 0; color: #666">
  <p style="margin: 0;">Documentation generated on January 04, 2026 at 00:40 UTC</p>
  
  <p style="margin: 0.5rem 0 0 0;">
    <a href="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel" rel="noopener noreferrer" style="color: #667eea; text-decoration: none;">jzombie/docker-mqtt-mosquitto-cloudflare-tunnel</a>
  </p>
  
</div>