Cash Collection Wiki

Space shortcuts

Page tree

Mosquitto.conf

1. Project Overview

Purpose and Scope:
This configuration file sets up a Mosquitto MQTT broker for development and testing purposes. It enables unencrypted, unauthenticated MQTT communication on port 1883, allowing rapid prototyping and local integration with MQTT clients (such as the Freeport FMI subscriber described previously).

Primary Use Cases:

  • Local development and testing of MQTT-based applications.
  • Integration testing with clients that publish or subscribe to sensor data topics.

What the System Explicitly Does Not Handle:

  • Production-grade security (no authentication, no TLS/mTLS).
  • Access control or topic-level permissions.

2. System Architecture

Core Components and Responsibilities:

  • Mosquitto Broker: Listens for MQTT connections on port 1883, accepts anonymous clients, and persists messages.
  • Persistence Layer: Stores broker state and messages at /var/lib/mosquitto/.
  • Logging: Outputs logs to stdout with various log levels enabled.

Data and Control Flow:

  • Clients connect to the broker (no authentication required).
  • Clients can publish/subscribe to any topic (no restrictions).
  • Broker logs all connection, subscription, and message events.

External Services and Dependencies:

  • None required for broker operation; clients connect over the network.

3. Core Concepts & Domain Logic

Key Abstractions and Domain Terms:

  • MQTT Listener: Accepts incoming MQTT connections on a specified port.
  • Anonymous Access: No username/password required for client connections.
  • Persistence: Broker state and messages are saved to disk for durability.
  • Topic Structure: Expected topics follow the pattern FCTS/FAE/<site>/SolvExtract/<pi_tag>.

Business or Technical Invariants:

  • All clients are treated equally (no authentication or authorization).
  • Message size is limited to 10MB.
  • Up to 1000 concurrent connections and 1000 queued messages are allowed.

Mental Model:

  • The broker is open and permissive, suitable only for isolated development environments.

4. Codebase Structure

High-level Layout:

  • Single configuration file for Mosquitto.
  • No code; all behavior is declaratively specified.

Responsibility Boundaries:

  • Broker configuration (network, persistence, logging, limits).
  • No application logic or message processing.

What Changes Together:

  • Security settings (authentication, TLS) must be updated together for production.
  • Topic structure and message expectations should be coordinated with client applications.

5. Configuration & Environment

Environment Variables:

  • Not used; all configuration is static in the file.

Configuration Files:

  • This file configures the Mosquitto broker.

Differences Between Local, Staging, and Production:

  • This configuration is for local/development only. Production should:
    • Disable allow_anonymous.
    • Enable authentication and TLS/mTLS.
    • Restrict topics and apply access controls.

6. Runtime Behavior

Startup Sequence:

  • Mosquitto reads this configuration on startup.
  • Listens on port 1883 for incoming connections.
  • Initializes persistence and logging.

Normal Execution Flow:

  • Accepts client connections and subscriptions.
  • Handles message publishing and delivery.
  • Logs all relevant events to stdout.

Error Handling and Logging Strategy:

  • Logs errors, warnings, notices, information, subscribe/unsubscribe events.
  • No advanced error handling; relies on Mosquitto defaults.

7. Deployment & Operations

Build Process:

  • None; deploy Mosquitto and provide this config file.

Deployment Method:

  • Start Mosquitto with this configuration (e.g., mosquitto -c /path/to/config).

Runtime Dependencies:

  • File system access to /var/lib/mosquitto/ for persistence.

Scaling and Rollback Considerations:

  • Supports up to 1000 concurrent connections.
  • Rollback is as simple as restoring a previous config file.

8. Extending the System

Where and How to Add New Features:

  • For security, add authentication and TLS/mTLS sections.
  • For access control, define ACLs and restrict topics.
  • For production, disable allow_anonymous and set password_file and cafile.

Recommended Patterns:

  • Use separate config files for development and production.
  • Version control configuration files.

Anti-patterns and Risk Areas:

  • Never use this configuration in production.
  • Avoid exposing port 1883 to untrusted networks.

Testing Strategy:

  • Test with local clients for connectivity and message flow.
  • Validate persistence and logging behavior.

9. Security & Compliance

Authentication and Authorization:

  • None enabled; all clients are anonymous.

Secrets Handling:

  • None present in this config.

Data Sensitivity Considerations:

  • All data is accessible to any client; do not use for sensitive or production data.

10. Common Pitfalls & Gotchas

  • No Security: Anyone can connect and publish/subscribe to any topic.
  • Persistence Location: Ensure /var/lib/mosquitto/ is writable and has sufficient space.
  • Message Size Limit: Messages over 10MB are rejected.
  • Connection Limits: Exceeding 1000 connections or queued messages will result in dropped connections/messages.
  • Logging: All logs go to stdout; may need redirection or log rotation in some environments.
  • TODOs: The configuration explicitly notes that security is not implemented and must be addressed before production use.