Eclipse Mosquitto Cheat Sheet

Overview

Eclipse Mosquitto is an open-source message broker that implements MQTT protocol versions 5.0, 3.1.1, and 3.1. It is lightweight and suitable for use on all devices from low-power single-board computers to full servers. Mosquitto is widely used in IoT applications, home automation, and telemetry systems.

MQTT is a publish-subscribe protocol designed for constrained devices and low-bandwidth, high-latency networks. Mosquitto provides efficient message routing with QoS levels 0, 1, and 2, retained messages, last will and testament (LWT), and persistent sessions. It includes both broker and command-line client tools for publishing and subscribing.

Installation

Linux

# Ubuntu/Debian
sudo apt-get install mosquitto mosquitto-clients

# CentOS/RHEL
sudo yum install mosquitto

# Start and enable service
sudo systemctl start mosquitto
sudo systemctl enable mosquitto

macOS

brew install mosquitto
brew services start mosquitto

Docker

docker run -d --name mosquitto \
  -p 1883:1883 \
  -p 9001:9001 \
  -v $(pwd)/mosquitto.conf:/mosquitto/config/mosquitto.conf \
  -v $(pwd)/data:/mosquitto/data \
  -v $(pwd)/log:/mosquitto/log \
  eclipse-mosquitto:2

Core Commands

Publishing Messages

# Basic publish
mosquitto_pub -h localhost -t "sensor/temperature" -m "23.5"

# Publish with QoS 1
mosquitto_pub -h localhost -t "sensor/temperature" -m "23.5" -q 1

# Publish retained message
mosquitto_pub -h localhost -t "device/status" -m "online" -r

# Publish with authentication
mosquitto_pub -h broker.example.com -u myuser -P mypass \
  -t "data/reading" -m '{"temp": 23.5}'

# Publish from file
mosquitto_pub -h localhost -t "config/update" -f config.json

# Publish from stdin
echo "Hello MQTT" | mosquitto_pub -h localhost -t "test/topic" -l

Subscribing to Messages

# Subscribe to single topic
mosquitto_sub -h localhost -t "sensor/temperature"

# Subscribe with wildcard (single level)
mosquitto_sub -h localhost -t "sensor/+/temperature"

# Subscribe with wildcard (multi-level)
mosquitto_sub -h localhost -t "sensor/#"

# Subscribe with QoS 2
mosquitto_sub -h localhost -t "critical/alerts" -q 2

# Subscribe and print verbose (topic + payload)
mosquitto_sub -h localhost -t "#" -v

# Subscribe with timestamp
mosquitto_sub -h localhost -t "sensor/#" -v -F '%I %t %p'

# Subscribe to multiple topics
mosquitto_sub -h localhost -t "sensor/#" -t "device/#" -t "alert/#"

Client Command Options

Option	Description
-h <host>	Broker hostname
-p <port>	Broker port (default: 1883)
-u <user>	Username
-P <pass>	Password
-t <topic>	Topic to publish/subscribe
-m <msg>	Message payload
-q <qos>	QoS level (0, 1, or 2)
-r	Retain message
-d	Enable debug output
-i <id>	Client ID
-k <secs>	Keepalive interval
-V <ver>	MQTT version (mqttv31, mqttv311, mqttv5)

Configuration

Main Config (/etc/mosquitto/mosquitto.conf)

# Listener configuration
listener 1883
protocol mqtt

# WebSocket listener
listener 9001
protocol websockets

# Persistence
persistence true
persistence_location /mosquitto/data/
autosave_interval 1800

# Logging
log_dest file /mosquitto/log/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information
connection_messages true
log_timestamp true

# Security — disallow anonymous
allow_anonymous false
password_file /mosquitto/config/passwd

# Max connections
max_connections -1

# Message size limit (bytes)
message_size_limit 1048576

# Keepalive
max_keepalive 120

User Authentication

# Create password file
mosquitto_passwd -c /etc/mosquitto/passwd myuser

# Add additional user
mosquitto_passwd -b /etc/mosquitto/passwd newuser newpassword

# Delete user
mosquitto_passwd -D /etc/mosquitto/passwd olduser

ACL (Access Control)

# /etc/mosquitto/acl
# User-specific access
user admin
topic readwrite #

user sensor1
topic write sensor/1/#
topic read config/sensor/1/#

user dashboard
topic read sensor/#
topic read device/#

# Pattern-based ACL (client ID substitution)
pattern readwrite sensor/%c/#

Add to config:

acl_file /etc/mosquitto/acl

TLS/SSL Configuration

# In mosquitto.conf
listener 8883
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false
tls_version tlsv1.2

# Connect with TLS
mosquitto_pub -h broker.example.com -p 8883 \
  --cafile ca.crt \
  -t "secure/data" -m "encrypted payload"

# Connect with client certificate
mosquitto_sub -h broker.example.com -p 8883 \
  --cafile ca.crt \
  --cert client.crt --key client.key \
  -t "secure/#"

Advanced Usage

Bridging Two Brokers

# In mosquitto.conf on broker A
connection bridge-to-B
address brokerB.example.com:1883
topic sensor/# both 1
topic device/# in 1
remote_username bridge_user
remote_password bridge_pass
bridge_protocol_version mqttv311
cleansession true
try_private true
notifications true
notification_topic bridge/status

MQTT v5 Features

# Publish with message expiry (300 seconds)
mosquitto_pub -V mqttv5 -h localhost -t "alerts/fire" \
  -m "Fire detected" -D publish message-expiry-interval 300

# Publish with user properties
mosquitto_pub -V mqttv5 -h localhost -t "data/reading" \
  -m '{"temp":23}' -D publish user-property "source" "sensor-1"

# Subscribe with shared subscription
mosquitto_sub -V mqttv5 -h localhost \
  -t '$share/mygroup/sensor/#'

Monitoring

# Subscribe to broker statistics
mosquitto_sub -h localhost -t '$SYS/#' -v

# Key $SYS topics
# $SYS/broker/uptime
# $SYS/broker/clients/connected
# $SYS/broker/messages/received
# $SYS/broker/messages/sent
# $SYS/broker/bytes/received
# $SYS/broker/bytes/sent
# $SYS/broker/subscriptions/count
# $SYS/broker/heap/current

Troubleshooting

Issue	Solution
Connection refused	Check listener config; ensure port 1883 is open and broker is running
Authentication failed	Verify password file path and user credentials; run mosquitto_passwd
No messages received	Check topic spelling; wildcards + and # must match correctly
QoS 1/2 messages lost	Enable persistence; ensure clean session is false for durable subscriptions
WebSocket connection fails	Verify protocol websockets on the listener; check CORS settings
Bridge not connecting	Verify remote address and credentials; check firewall rules
High memory usage	Limit max inflight messages; reduce retained message count
Permission denied on topic	Review ACL file; check user-topic mappings