Advanced Topics

Relevant source files

• README.md
• mosquitto.conf

This page covers advanced configuration options and production-ready features available in the protected-no-wildcard branch of the repository. While the main branch provides a straightforward MQTT broker setup with anonymous access and no encryption, the advanced branch introduces ACL-based topic restrictions, encrypted retained message storage, and additional safeguards for multi-tenant environments.

For step-by-step deployment instructions, see Getting Started. For basic component documentation, see Components. This page focuses on enhanced security features and production considerations not present in the base configuration.

Sources : README.md:5-11

Advanced Branch Overview

The repository maintains two primary branches with different security and feature profiles:

The protected-no-wildcard branch addresses security concerns in scenarios where:

• Multiple users share a single MQTT broker
• Topic privacy between users must be enforced
• Retained messages contain sensitive data requiring encryption at rest
• Filesystem-level message persistence protection is needed

Sources : README.md:5-11

Architecture Comparison

The following diagram illustrates the architectural differences between the two branches:

Diagram: Main vs Protected Branch Architecture

graph TB
    subgraph "main Branch Architecture"
        direction TB
        MQ_Main["mosquitto Container\n(main branch)"]
Conf_Main["mosquitto.conf\nallow_anonymous: true"]
Data_Main["data/\nPlaintext Storage"]
Conf_Main -->|Configures| MQ_Main
 
       MQ_Main -->|Writes Retained Messages| Data_Main
    end
    
    subgraph "protected-no-wildcard Branch Architecture"
        direction TB
        MQ_Protected["mosquitto Container\n(protected-no-wildcard)"]
Conf_Protected["mosquitto.conf\nallow_anonymous: false\nacl_file /mosquitto/config/aclfile"]
ACL["aclfile\nUser-based Topic Rules"]
Gocryptfs["gocryptfs Container\nEncryption Layer"]
Data_Encrypted["data-encrypted/\nEncrypted Filesystem"]
Data_Decrypted["data/\nDecrypted Mount Point"]
Conf_Protected -->|Configures| MQ_Protected
 
       ACL -->|Restricts Topics| MQ_Protected
 
       MQ_Protected -->|Writes to| Data_Decrypted
 
       Gocryptfs -->|Mounts| Data_Decrypted
 
       Gocryptfs -->|Encrypts to| Data_Encrypted
    end
    
    Client_Main["MQTT Client\n(Any)"]
Client_Protected["MQTT Client\n(Authenticated)"]
Client_Main -->|Anonymous Connect| MQ_Main
 
   Client_Protected -->|Username/Password| MQ_Protected

The protected branch introduces two key architectural components not present in the main branch:

1. ACL File : Located at mosquitto/aclfile in the protected branch, this file defines user-specific topic access patterns
2. Gocryptfs Layer : A separate container that provides transparent encryption for the data/ directory

Sources : README.md:5-11 mosquitto.conf:1-6

Topic Access Control (ACL)

The protected-no-wildcard branch implements an ACL (Access Control List) system that restricts MQTT topic access based on username. The implementation follows a naive but effective pattern where:

• The first level of each topic must match the authenticated username
• Users can only publish and subscribe to topics under their own namespace
• Wildcard subscriptions (#, +) are restricted to prevent cross-user topic enumeration

Example ACL Pattern :

# User "alice" can only access topics starting with "alice/"
user alice
topic readwrite alice/#

# User "bob" can only access topics starting with "bob/"
user bob
topic readwrite bob/#

This approach prevents a scenario where user alice subscribes to bob/# or # to discover or intercept messages from other users.

For detailed ACL configuration and examples, see Topic Access Control (ACL)).

Sources : README.md7

Encrypted Retained Messages

MQTT retained messages persist on the broker's filesystem and are delivered to new subscribers. In the main branch, these messages are stored in plaintext within the data/ directory. The protected-no-wildcard branch adds filesystem-level encryption using gocryptfs.

Data Flow with Encryption :

The encryption operates transparently to Mosquitto. The broker reads and writes to data/ as if it were a normal directory, while gocryptfs handles encryption/decryption automatically. The actual encrypted data resides in data-encrypted/, which is stored on the Docker host filesystem.

Key characteristics:

• Algorithm : AES-256-GCM authenticated encryption
• Scope : Encrypts retained messages only (not in-flight messages)
• Performance : Minimal overhead for typical MQTT workloads
• Recovery : Requires the encryption password to mount the filesystem

For implementation details and configuration, see Encrypted Retained Messages.

Sources : README.md:8-9

Auto-Save Retained Messages

The protected-no-wildcard branch includes functionality to automatically persist retained messages to disk after every message write. This contrasts with Mosquitto's default behavior where:

• In-memory messages may be lost on unclean shutdown
• Persistence is typically triggered by shutdown signals or intervals

The auto-save feature ensures that:

1. Each retained message write triggers a disk synchronization
2. Retained messages survive unexpected container restarts
3. Message persistence guarantees are stronger in high-availability scenarios

Trade-offs :

• Pros : Better data durability, reduced risk of message loss
• Cons : Increased I/O operations, potential performance impact for high-volume retained message workloads

Sources : README.md9

Branch Comparison and Migration

The following table summarizes when to use each branch:

Migration Path : Moving from main to protected-no-wildcard requires:

1. Adding user authentication credentials to Mosquitto configuration
2. Creating an ACL file with appropriate topic rules
3. Configuring and initializing the gocryptfs encrypted filesystem
4. Updating client applications to provide authentication credentials
5. Restructuring topic hierarchies to follow the username-first pattern

Sources : README.md:5-11

Accessing Advanced Features

To explore or deploy the advanced features:

1. View the diff : Compare the branches to understand specific changes

2. Checkout the branch :

3. Review documentation : Each subsection below provides detailed configuration instructions:

   • Topic Access Control (ACL)) - User authentication and ACL file configuration
   • Encrypted Retained Messages - Gocryptfs setup and encryption key management
   • Production Considerations - Scaling, monitoring, and hardening recommendations

Sources : README.md11

Configuration File Locations

The following files are specific to the protected-no-wildcard branch and do not exist in main:

Files that exist in both branches but have different configurations:

Sources : README.md7 mosquitto.conf:1-6

Next Steps : For detailed implementation guides for each advanced feature, proceed to the subsections:

• Topic Access Control (ACL)) for multi-user topic isolation
• Encrypted Retained Messages for filesystem encryption setup
• Production Considerations for deployment best practices