mosquitto.conf Reference

Relevant source files

• mosquitto.conf

Purpose and Scope

This page provides complete technical reference documentation for the mosquitto.conf configuration file used in this system. The file defines the MQTT broker's runtime behavior, including network listeners, protocol support, and access control settings.

For conceptual information about Mosquitto configuration and setup procedures, see Mosquitto Configuration. For detailed documentation of the Mosquitto broker component itself, see Mosquitto MQTT Broker. For listener-specific implementation details, see MQTT Listeners and Anonymous Access.

Sources: mosquitto.conf:1-6

File Location and Integration

The mosquitto.conf file resides in the project root directory and is mounted as a read-only volume into the mosquitto container at runtime. The file is version-controlled and contains no secrets.

graph TB
    subgraph "Version Control"
        MosqConf["mosquitto.conf\n(Project Root)"]
end
    
    subgraph "Docker Compose"
        ComposeYML["docker-compose.yml"]
VolumeMount["Volume Mount Definition\n./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"]
end
    
    subgraph "Container Runtime"
        MosqContainer["mosquitto Container\n(eclipse-mosquitto:latest)"]
MosqProcess["mosquitto Process\nReads Config at Startup"]
end
    
 
   MosqConf --> ComposeYML
 
   ComposeYML --> VolumeMount
 
   VolumeMount --> MosqContainer
 
   MosqContainer --> MosqProcess

Docker Compose Integration

Diagram: mosquitto.conf Mount and Load Path

The configuration is mounted read-only (:ro flag) to prevent the container from modifying the configuration file. The mosquitto process reads this configuration file during container initialization.

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

Configuration Overview

The current mosquitto.conf implements a minimal configuration optimized for accessibility and simplicity. It defines two network listeners with different protocols and enables anonymous client connections.

graph TB
    subgraph "mosquitto.conf"
        RootConfig["Configuration Root"]
subgraph "First Listener Block"
            Listener1["listener 1883"]
Anonymous["allow_anonymous true"]
end
        
        subgraph "Second Listener Block"
            Listener2["listener 9001"]
Protocol["protocol websockets"]
end
        
 
       RootConfig --> Listener1
 
       Listener1 --> Anonymous
        
 
       RootConfig --> Listener2
 
       Listener2 --> Protocol
    end
    
    subgraph "Runtime Behavior"
        Port1883["TCP Port 1883\nStandard MQTT Protocol"]
Port9001["TCP Port 9001\nMQTT over WebSockets"]
AnonymousAccess["All Clients Accepted\nNo Authentication Required"]
end
    
 
   Listener1 --> Port1883
 
   Listener2 --> Port9001
 
   Anonymous --> AnonymousAccess

Active Configuration Structure

Diagram: Configuration Structure and Runtime Mapping

Sources: mosquitto.conf:1-6

Directive Reference

listener

Syntax: listener <port> [<bind_address>]

Purpose: Defines a network listener that accepts incoming MQTT client connections.

Parameters:

Behavior:

• Multiple listener directives create multiple independent listeners
• Each listener can be configured with different protocols and security settings
• Configuration directives following a listener apply to that specific listener until the next listener directive
• When no bind address is specified, the listener binds to all available network interfaces (0.0.0.0)

Current Usage:

mosquitto.conf1 defines the first listener:

listener 1883

This creates a listener on port 1883 (the IANA-registered standard MQTT port) bound to all interfaces.

mosquitto.conf4 defines the second listener:

listener 9001

This creates a listener on port 9001 (commonly used for MQTT WebSockets) bound to all interfaces.

Sources: mosquitto.conf1 mosquitto.conf4

allow_anonymous

Syntax: allow_anonymous <true|false>

Purpose: Controls whether clients can connect without providing authentication credentials.

Parameters:

Behavior:

• When set to true: Clients may connect without providing a username or password
• When set to false: All clients must authenticate using username/password or certificate-based authentication
• This setting applies to all listeners unless overridden by listener-specific configuration
• Default value: false (as of Mosquitto 2.0+)

Security Implications:

• Anonymous access is appropriate for trusted networks or development environments
• Production deployments should typically disable anonymous access and implement authentication
• When anonymous access is enabled, no per-client authorization checks occur unless ACLs are configured

Current Usage:

mosquitto.conf2 enables anonymous access:

allow_anonymous true

This configuration allows any client to connect to either listener (port 1883 or port 9001) without authentication.

Sources: mosquitto.conf2

protocol

Syntax: protocol <protocol_type>

Purpose: Specifies the MQTT protocol variant for a specific listener.

Parameters:

Behavior:

• Must be specified within a listener block (after a listener directive)
• Applies only to the immediately preceding listener
• When set to mqtt: Standard MQTT protocol over TCP (default behavior)
• When set to websockets: MQTT protocol encapsulated in WebSocket frames

Protocol Variants:

WebSocket Protocol Details:

• Enables MQTT communication from browser-based JavaScript clients
• WebSocket frames provide HTTP-compatible upgrade mechanism
• Allows MQTT traffic to traverse HTTP proxies and firewalls
• Implements RFC 6455 (WebSocket Protocol)

Current Usage:

mosquitto.conf5 configures the 9001 listener for WebSockets:

protocol websockets

This enables MQTT-over-WebSocket support on port 9001, while port 1883 uses standard MQTT (default when protocol is not specified).

Sources: mosquitto.conf5

graph LR
    subgraph "mosquitto.conf Directives"
        Line1["listener 1883\n(Line 1)"]
Line2["allow_anonymous true\n(Line 2)"]
Line4["listener 9001\n(Line 4)"]
Line5["protocol websockets\n(Line 5)"]
end
    
    subgraph "Listener 1 Runtime Config"
        L1Port["Bind Port: 1883"]
L1Protocol["Protocol: mqtt (default)"]
L1Auth["Auth: Anonymous Allowed"]
end
    
    subgraph "Listener 2 Runtime Config"
        L2Port["Bind Port: 9001"]
L2Protocol["Protocol: websockets"]
L2Auth["Auth: Anonymous Allowed (inherited)"]
end
    
 
   Line1 --> L1Port
 
   Line1 --> L1Protocol
 
   Line2 --> L1Auth
 
   Line2 --> L2Auth
    
 
   Line4 --> L2Port
 
   Line5 --> L2Protocol

Complete Configuration Map

The following diagram shows how each directive in mosquitto.conf maps to runtime broker behavior:

Diagram: Directive-to-Runtime Configuration Mapping

Sources: mosquitto.conf:1-6

Configuration Directives Not Present

The current configuration uses only three directives. Mosquitto supports numerous additional directives for advanced functionality. Common directives not present in this configuration include:

Authentication and Authorization

TLS/SSL Configuration

Persistence and Logging

Connection Limits

For advanced configuration including ACL-based access control, see the protected-no-wildcard branch documentation at Topic Access Control (ACL)).

Sources: mosquitto.conf:1-6

graph TB
    subgraph "Configuration Layer"
        MosqConf["mosquitto.conf"]
ComposeYML["docker-compose.yml"]
EnvFile[".env"]
end
    
    subgraph "Container Layer"
        MosqContainer["mosquitto container\n(eclipse-mosquitto:latest)"]
CFDContainer["cloudflared container"]
end
    
    subgraph "Mosquitto Configuration Application"
        Listener1883["Listener: Port 1883\nProtocol: mqtt\nFrom: mosquitto.conf:1"]
Listener9001["Listener: Port 9001\nProtocol: websockets\nFrom: mosquitto.conf:4-5"]
AuthPolicy["Anonymous Access: Enabled\nFrom: mosquitto.conf:2"]
end
    
    subgraph "Traffic Flow"
        CFProxy["cloudflared proxies to\nmosquitto:9001"]
ExternalClients["External MQTT Clients\n(via Cloudflare Tunnel)"]
InternalClients["Internal MQTT Clients\n(direct to port 1883)"]
end
    
 
   MosqConf -->|Volume Mount| MosqContainer
 
   ComposeYML -->|Orchestrates| MosqContainer
 
   ComposeYML -->|Orchestrates| CFDContainer
 
   EnvFile -->|Provides Token to| CFDContainer
    
 
   MosqContainer --> Listener1883
 
   MosqContainer --> Listener9001
 
   MosqContainer --> AuthPolicy
    
 
   CFProxy -->|WebSocket Connection| Listener9001
 
   ExternalClients -->|Through Cloudflare| CFProxy
 
   InternalClients -->|Direct TCP| Listener1883
    
 
   AuthPolicy -.->|Applies to| Listener1883
 
   AuthPolicy -.->|Applies to| Listener9001

Relationship to System Architecture

The mosquitto.conf file configures the MQTT broker component within the larger system architecture:

Diagram: mosquitto.conf in System Context

The configuration file directly controls broker behavior, while Docker Compose handles orchestration and the Cloudflare tunnel handles external routing. Note that cloudflared proxies specifically to port 9001 (WebSocket listener), making this the primary entry point for external clients.

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

Configuration Modification Guidelines

Modifying the Configuration

1. Edit mosquitto.conf in the project root directory

2. Restart the mosquitto container to apply changes:

3. Verify configuration by checking container logs:

Common Configuration Changes

Disabling Anonymous Access:

allow_anonymous false
password_file /mosquitto/config/password.txt

Enabling TLS on WebSocket Listener:

listener 9001
protocol websockets
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

Adding Standard MQTT over TLS:

listener 8883
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

Note that any additional files (passwords, certificates, ACLs) must be mounted into the container via additional volume mounts in docker-compose.yml.

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

Validation and Testing

After modifying mosquitto.conf, validate the configuration before deployment:

Syntax Validation

The mosquitto process validates configuration on startup. Invalid configurations will prevent container startup. Check logs for validation errors:

Configuration errors appear in startup logs with the format:

Error: <description of error>

Testing Listener Configuration

Test each configured listener independently:

Port 1883 (Standard MQTT):

Port 9001 (WebSockets): Requires a WebSocket-capable MQTT client. Browser-based clients can connect to:

ws://localhost:9001

For testing WebSocket connectivity through the Cloudflare tunnel, use the public hostname configured in the Cloudflare dashboard.

Sources: mosquitto.conf:1-6

File Format Specifications

Syntax Rules

Directive Scope

Configuration directives fall into two categories:

Global Directives:

• Apply to the entire broker instance
• Examples: allow_anonymous, persistence, log_dest
• Typically appear before any listener directives

Listener-Specific Directives:

• Apply only to the immediately preceding listener
• Examples: protocol, cafile, certfile
• Must follow a listener directive

In mosquitto.conf:1-6 allow_anonymous is a global directive (line 2) that applies to all listeners, while protocol is listener-specific (line 5) and applies only to the port 9001 listener.

Sources: mosquitto.conf:1-6