How mosquitto Works: Architecture, System Design & Code Deep Dive

Project Overview

Mosquitto is an open-source message broker that robustly implements the MQTT protocol versions 3.1, 3.1.1, and 5. It serves as a central hub for lightweight publish/subscribe messaging, primarily facilitating communication between devices in Internet of Things (IoT), mobile, and embedded environments. It comprises both a high-performance broker daemon, `mosquitto`, and a C client library, `libmosquitto`, enabling applications to interact with MQTT brokers.

Category

iot-messaging

Difficulty

intermediate

Tech Stack

Unknown

Author

eclipse

Tags

mqtt, pubsub, iot

How mosquitto Works

Mosquitto is an open-source message broker that robustly implements the MQTT protocol versions 3.1, 3.1.1, and 5. It serves as a central hub for lightweight publish/subscribe messaging, primarily facilitating communication between devices in Internet of Things (IoT), mobile, and embedded environments. It comprises both a high-performance broker daemon, `mosquitto`, and a C client library, `libmosquitto`, enabling applications to interact with MQTT brokers.

Data Flow

Data in Mosquitto primarily flows as MQTT packets over TCP/IP connections, optionally secured with TLS. Client applications (using `libmosquitto`) generate MQTT CONNECT, SUBSCRIBE, PUBLISH, PINGREQ, DISCONNECT packets which are serialized by `lib/packet_mosq.c` and transmitted via `lib/net_mosq.c` (and `lib/tls_mosq.c` if TLS is enabled). These packets arrive at the broker via `src/net.c`, where they are deserialized. Core data (client sessions, subscriptions, retained messages, in-flight QoS messages) is managed and persisted by `src/database.c`. Configuration data, parsed from `mosquitto.conf` by `src/conf.c`, informs the broker's operational parameters, including security rules (`src/security.c`). Outgoing MQTT packets (CONNACK, SUBACK, PUBLISH, PINGRESP) are generated by the broker's handlers (`src/handle_connect.c`, `src/handle_publish.c`, etc.) and sent back to clients through `src/net.c` (and `lib/tls_mosq.c`).

Key Modules & Components

• MQTT Broker Core: Provides the central message routing and management capabilities of the Mosquitto broker, handling client connections, subscriptions, message delivery, and session persistence. This module ensures reliable and efficient communication between MQTT clients based on published topics and client subscriptions.
  Key files: src/mosquitto.c, src/net.c, src/database.c
• Client Connectivity and Communication: Enables MQTT client applications to connect to, communicate with, and disconnect from the Mosquitto broker. This module manages the lifecycle of MQTT client connections, including establishing the network connection, handling MQTT packet serialization and deserialization, and managing message flow.
  Key files: lib/mosquitto.c, lib/net_mosq.c, lib/packet_mosq.c
• Security and Access Control: Manages authentication and authorization for MQTT clients connecting to the broker. This module enforces access control policies based on usernames, passwords, and topic-based permissions, ensuring that only authorized clients can publish or subscribe to specific topics. It also supports integration with external authentication and authorization systems through a plugin architecture.
  Key files: src/security.c, include/mosquitto_broker.h, src/handle_connect.c
• Secure Communication Channel: Provides TLS/SSL encryption for secure communication between MQTT clients and the broker, or between brokers in a bridged configuration. This module protects sensitive data from eavesdropping and tampering by establishing an encrypted communication channel using industry-standard cryptographic protocols.
  Key files: lib/tls_mosq.c, src/net.c
• Broker Configuration Management: Parses and applies configuration settings to the Mosquitto broker, allowing administrators to customize the broker's behavior. This module reads configuration directives from the `mosquitto.conf` file, validates them, and applies them to various operational parameters, including listeners, security options, persistence, logging, bridges, and plugin settings.
  Key files: src/conf.c, mosquitto.conf
• Build and Platform Adaptation: Defines the build process and configures platform-specific adaptations for the Mosquitto project. This module handles compiler definitions based on the operating system, and enables or disables support for features like TLS, cJSON, and `pthread_cancel` based on build flags or platform detection.
  Key files: CMakeLists.txt, config.h