Mosquitto Configuration

Relevant source files

• README.md
• docker-compose.yml
• mosquitto.conf

This document explains the configuration settings in the mosquitto.conf file, which controls the behavior of the Eclipse Mosquitto MQTT broker. This includes listener configuration, port assignments, protocol settings, and access control options.

For information about setting up the Cloudflare Tunnel to expose the broker, see Cloudflare Tunnel Configuration. For information about environment variable configuration, see Environment Variables. For advanced access control configurations available in other branches, see Topic Access Control (ACL)).

Configuration File Overview

The Mosquitto broker is configured through a single configuration file located at mosquitto.conf in the repository root. This file is mounted into the mosquitto Docker container at runtime via a volume mount defined in docker-compose.yml8

File Location and Mounting

The configuration is read by the mosquitto service when the container starts. Changes to the host file require a container restart to take effect.

Sources: docker-compose.yml:7-8 mosquitto.conf:1-6

Listener Configuration

The mosquitto.conf file defines two network listeners, each serving different MQTT client connection types. Each listener operates independently and can be configured with different protocols and security settings.

graph TB
    subgraph "mosquitto Container"
        Config["mosquitto.conf"]
Broker["Mosquitto Broker Process"]
subgraph "Listener 1883"
            L1883["listener 1883"]
TCP["Standard MQTT/TCP Protocol"]
Port1883["Port 1883"]
end
        
        subgraph "Listener 9001"
            L9001["listener 9001"]
WS["protocol websockets"]
Port9001["Port 9001"]
end
        
        Anonymous["allow_anonymous true"]
end
    
    subgraph "Cloudflared Routing"
        CFProxy["cloudflared proxy"]
PublicHostname["Public Hostname"]
end
    
 
   Config -->|Configures| L1883
 
   Config -->|Configures| L9001
 
   Config -->|Applies to all listeners| Anonymous
    
 
   L1883 --> TCP
 
   TCP --> Port1883
    
 
   L9001 --> WS
 
   WS --> Port9001
    
 
   PublicHostname -->|Routes to| CFProxy
 
   CFProxy -->|mosquitto:9001| Port9001
    
 
   Broker -->|Binds| Port1883
 
   Broker -->|Binds| Port9001

Listener Architecture

Sources: mosquitto.conf:1-6 docker-compose.yml:4-9 README.md62

Listener 1: Standard MQTT (Port 1883)

The first listener is configured at mosquitto.conf:1-2 and provides standard MQTT protocol support over TCP.

listener 1883
allow_anonymous true

This listener is suitable for:

• Standard MQTT client libraries
• IoT devices using native MQTT over TCP
• Local network connections within Docker's internal network

Note: This listener is not directly exposed through the Cloudflare Tunnel by default. Only the WebSocket listener (port 9001) is routed through Cloudflare as configured in README.md62

Sources: mosquitto.conf:1-2

Listener 2: WebSocket MQTT (Port 9001)

The second listener is configured at mosquitto.conf:4-5 and provides MQTT over WebSockets, enabling browser-based and web application clients.

listener 9001
protocol websockets

This listener is the primary entry point for external clients. The Cloudflare Tunnel routes public traffic to mosquitto:9001 as specified in the tunnel configuration described in README.md62

WebSocket Protocol Details

The protocol websockets directive at mosquitto.conf5 instructs Mosquitto to:

1. Accept WebSocket handshake requests on port 9001
2. Upgrade HTTP connections to WebSocket protocol
3. Extract MQTT control packets from WebSocket frames
4. Encapsulate MQTT responses in WebSocket frames

Sources: mosquitto.conf:4-5 README.md62

Access Control Configuration

Anonymous Access

The configuration file enables anonymous access at mosquitto.conf2:

allow_anonymous true

Security Implications

Important Security Considerations:

1. No Authentication: Any client that can reach the broker through the Cloudflare Tunnel can connect without providing credentials.

2. No Authorization: Connected clients have unrestricted access to:

   • Publish to any topic
   • Subscribe to any topic
   • Use wildcard subscriptions (#, +)

3. Network-Level Security Only: Security relies entirely on:

   • Cloudflare's edge network protections
   • The secrecy of the public hostname
   • Optional Cloudflare Zero Trust policies (not configured by default)

4. Trust Boundary: The configuration assumes all traffic reaching the mosquitto container through cloudflared is trusted. There is no defense-in-depth at the MQTT layer.

For enhanced security configurations with user authentication and topic-level ACLs, see Topic Access Control (ACL)) which documents the protected-no-wildcard branch implementation.

Sources: mosquitto.conf2 README.md:5-11

Configuration Directives Reference

The table below provides a complete reference for all directives present in mosquitto.conf:1-6:

Sources: mosquitto.conf:1-6

graph TB
    subgraph "Host Filesystem"
        HostFile["./mosquitto.conf\nRepository root"]
HostContent["Line 1: listener 1883\nLine 2: allow_anonymous true\nLine 4: listener 9001\nLine 5: protocol websockets"]
end
    
    subgraph "Docker Volume Mount"
        Mount["Volume Mount Definition\ndocker-compose.yml:7-8"]
end
    
    subgraph "mosquitto Container"
        ContainerFile["/mosquitto/config/mosquitto.conf"]
MosqProcess["mosquitto process\nreads config at startup"]
Listener1["Listener 1883\nTCP"]
Listener2["Listener 9001\nWebSockets"]
end
    
 
   HostFile -->|Contains| HostContent
 
   HostContent -->|Mounted via| Mount
 
   Mount -->|As| ContainerFile
 
   ContainerFile -->|Read by| MosqProcess
 
   MosqProcess -->|Creates| Listener1
 
   MosqProcess -->|Creates| Listener2

Configuration in Docker Context

Volume Mount Mechanism

The mosquitto configuration file is made available to the container through Docker's volume mounting mechanism:

Mount Details:

Configuration Loading Process

1. Container Start: Docker Compose starts the mosquitto container per docker-compose.yml:4-9
2. Volume Mount: Docker mounts ./mosquitto.conf into the container before process execution
3. Process Initialization: The mosquitto process starts and reads /mosquitto/config/mosquitto.conf
4. Listener Creation: Mosquitto binds to ports 1883 and 9001 based on listener directives
5. Ready State: Container enters healthy state, ready to accept connections

Runtime Behavior:

• Changes to mosquitto.conf on the host filesystem do not automatically apply to the running container
• The mosquitto process must be restarted to reload configuration: docker compose restart mosquitto
• During development, use docker compose down and docker compose up to ensure clean configuration reload

Sources: docker-compose.yml:4-9 mosquitto.conf:1-6

Configuration File Location in Project Structure

The mosquitto.conf file is:

• Located in the repository root directory
• Tracked in version control (committed to Git)
• Mounted into the container at runtime
• Safe to modify and commit (contains no secrets)

This is in contrast to:

• .env file: Contains secrets, excluded via .gitignore
• data/ directory: Contains runtime data, excluded via .gitignore

Sources: docker-compose.yml:7-8 mosquitto.conf:1-6

Minimal Configuration Justification

The current mosquitto.conf implements a minimal viable configuration with only essential directives. This design choice provides:

Advantages

Omitted Configurations

The following common Mosquitto directives are not present in mosquitto.conf:1-6:

• password_file: No password-based authentication
• acl_file: No topic-level access control
• persistence: No message persistence across restarts
• log_dest: Uses default logging to stdout (captured by Docker)
• max_connections: No connection limit imposed
• max_queued_messages: Uses Mosquitto defaults
• message_size_limit: Uses Mosquitto defaults

For implementations requiring these features, see Topic Access Control (ACL)) and Production Considerations.

Sources: mosquitto.conf:1-6