When you install Mosquitto on a Raspberry Pi you get a fast, lightweight MQTT broker that keeps working on your local network even when the internet does not. In this tutorial you will install mosquitto raspberry pi packages from the OS repository, configure a listener with password authentication, test it from the command line and decide when a local broker is enough and when it should bridge to a cloud broker. Every config file is complete and copy-ready.
When a Local Mosquitto Broker Makes Sense
A broker on the Pi is a good fit for some jobs and a poor fit for others. Be honest about which one you have before investing time in it.
| Situation | Local Mosquitto on the Pi | Cloud broker |
|---|---|---|
| All devices on one LAN, nothing needed remotely | Good fit | Optional |
| Must keep working through internet outages | Good fit | Combine with a local broker |
| Devices in several buildings or on mobile networks | Poor fit, needs port forwarding | Good fit |
| Phone apps and dashboards from anywhere | Poor fit, needs VPN or open ports | Good fit |
| You want someone else to handle TLS, auth and updates | Poor fit | Good fit |
| Very low latency between local devices | Good fit | Adds an internet round trip |
The pattern that combines both is common in practice: devices talk to a local Mosquitto on the Pi, and Mosquitto bridges selected topics to a cloud broker. Local automations keep running offline, and the cloud side gets the data for dashboards and remote access. That is where this tutorial ends up. If you want a refresher on the broker's role first, see what an MQTT broker does.
Step 1: Install Mosquitto on Raspberry Pi OS
Raspberry Pi OS Bookworm ships Mosquitto 2.0 in its repository, which is recent enough for most uses:
sudo apt update
sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto
mosquitto -h | head -n 1
systemctl status mosquitto --no-pager
The mosquitto-clients package adds mosquitto_pub and mosquitto_sub, which you will use for testing.
Out of the box, Mosquitto 2.0 is deliberately locked down: with no listener configured it only accepts connections from the Pi itself (localhost) and refuses anonymous remote clients. That surprises people who followed older guides, where the broker accepted anyone on port 1883. It is the right default, and the next step opens it up safely.
Step 2: Create Users and a Password File
Create a password file with one user per device or service. The -c flag creates the file, so use it only for the first user:
sudo mosquitto_passwd -c /etc/mosquitto/passwd sensors
sudo mosquitto_passwd /etc/mosquitto/passwd nodered
sudo mosquitto_passwd /etc/mosquitto/passwd dashboard
Each command prompts for a password and stores a salted hash, not the plain text. Restrict the file so only root and the broker can read it:
sudo chown root:mosquitto /etc/mosquitto/passwd
sudo chmod 0640 /etc/mosquitto/passwd
Recent Mosquitto releases warn in the log when the password file is readable by everyone, and future versions may refuse it, so set the permissions now.
Step 3: Configure the Listener
Keep the main /etc/mosquitto/mosquitto.conf as shipped; it includes every file in /etc/mosquitto/conf.d/. Add your own config there:
sudo nano /etc/mosquitto/conf.d/local.conf
# Local network listener with authentication
per_listener_settings true
listener 1883 0.0.0.0
allow_anonymous false
password_file /etc/mosquitto/passwd
# Limits that protect a small Pi
max_connections 200
max_inflight_messages 20
max_queued_messages 1000
message_size_limit 262144
# Keep the SD card happy: persistence is on by default in the main file,
# save to disk every 5 minutes rather than continuously
autosave_interval 300
A few notes on these settings. per_listener_settings true lets each listener have its own authentication, which you will need if you later add a WebSocket listener with different rules. message_size_limit stops a misbehaving client from sending huge payloads to a Pi with limited RAM. autosave_interval controls how often the in-memory persistence database is written, which matters for SD card wear.
Restart and check the log:
sudo systemctl restart mosquitto
sudo journalctl -u mosquitto -n 30 --no-pager
The log should show Opening ipv4 listen socket on port 1883. If the service fails, the log line just above the failure names the bad option.
Step 4: Test the Local Broker
In one terminal on the Pi, subscribe with the dashboard user:
mosquitto_sub -h localhost -p 1883 -u dashboard -P 'dashboard-password' \
-i test-sub -t 'home/#' -v
In another terminal, or from a laptop on the same network using the Pi's IP address, publish as sensors:
mosquitto_pub -h 192.168.1.50 -p 1883 -u sensors -P 'sensors-password' \
-i test-pub -t home/kitchen/temperature -m 21.6
The subscriber prints home/kitchen/temperature 21.6. Now try without credentials to confirm anonymous access is refused:
mosquitto_pub -h 192.168.1.50 -p 1883 -i anon-test -t home/x -m test
# Connection error: Connection Refused: not authorised.
For more command-line patterns, see the mosquitto_pub and mosquitto_sub examples.
Step 5: Optional WebSocket Listener for Local Dashboards
If a browser dashboard on your LAN needs to talk to the Pi broker, add a WebSocket listener to the same file:
listener 9001 0.0.0.0
protocol websockets
allow_anonymous false
password_file /etc/mosquitto/passwd
Because per_listener_settings is on, this listener needs its own allow_anonymous and password_file lines. Plain ws:// is acceptable on a trusted LAN but not across the internet.
Hardening Checklist After You Install Mosquitto on Raspberry Pi
- Change the Pi's default user password and keep the OS updated with
sudo apt full-upgrade. - Do not forward port 1883 on your router. Exposing an unencrypted broker to the internet invites password guessing and traffic sniffing.
- Use a separate MQTT user per device or service, so you can revoke one without touching the rest.
- Add a firewall rule so only your LAN reaches the broker:
sudo ufw allow from 192.168.1.0/24 to any port 1883. - Move persistence to an SSD or reduce writes if the Pi runs from an SD card for years.
- Monitor the Pi itself; the Raspberry Pi system stats publisher reports disk and temperature.
For access to the broker from outside, resist the urge to open ports. That is the job a cloud broker does better.
Bridging the Local Mosquitto Broker to ConnectMQ
Here is where the local broker and a cloud broker meet. Mosquitto has a built-in bridge: it connects out to a remote broker as an ordinary MQTT client and forwards the topics you choose. ConnectMQ is a cloud MQTT broker, so from its point of view your Pi is just another client that logs in with the username, password and client ID generated in the portal. No special bridge feature is needed on the cloud side, and no inbound port is opened on your network.
A minimal bridge file, /etc/mosquitto/conf.d/bridge-connectmq.conf, looks like this:
connection connectmq
address broker.connectmq.com:8883
bridge_capath /etc/ssl/certs
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
bridge_protocol_version mqttv311
try_private false
cleansession false
notifications false
start_type automatic
# Local topic home/... appears in the cloud as site1/home/...
topic home/# out 1 "" site1/
# Commands from the cloud reach local devices
topic home/+/set in 1 "" site1/
Restart Mosquitto and the log shows Connecting bridge connectmq. Messages published locally on home/kitchen/temperature now also appear on site1/home/kitchen/temperature at ConnectMQ, where the portal's live topic explorer and dashboard can display them. If the internet drops, local devices keep talking to the Pi, and with cleansession false and QoS 1 the outgoing messages queue locally until the bridge reconnects, up to the max_queued_messages limit.
The cloud broker uses a Let's Encrypt certificate, which is why bridge_capath /etc/ssl/certs is all the TLS setup required. try_private false matters: it stops Mosquitto from using a Mosquitto-specific protocol flag that other brokers do not expect. The full option-by-option walkthrough, including loop prevention and testing, is in the Mosquitto bridge configuration guide.
If you eventually find that you are keeping the Pi broker only to reach the cloud, consider removing it entirely and pointing devices straight at the cloud. The guide to migrating Mosquitto to a cloud broker covers that path.
Troubleshooting
| Error or symptom | Cause | Fix |
|---|---|---|
Connection refused from other machines |
No listener on 0.0.0.0 | Add listener 1883 0.0.0.0 |
not authorised |
Wrong user or password, or file not readable by broker | Re-run mosquitto_passwd, check chown root:mosquitto |
| Service fails after editing config | Duplicate listener or typo | Read journalctl -u mosquitto |
| Clients keep disconnecting | Two clients share an ID | Use unique client IDs |
| Bridge connects then drops | Client ID or credentials mismatch | Copy all three from the portal exactly |
Get Started with ConnectMQ
Keep Mosquitto for fast local traffic and let a managed broker handle everything that crosses the internet. Create a free Serverless broker at app.connectmq.com, no credit card required, copy the generated credentials into your bridge file and watch your local topics appear in the portal. More Pi projects are collected in the Raspberry Pi MQTT tutorial.
Frequently Asked Questions
Why does Mosquitto refuse connections from other devices after install?
Mosquitto 2.0 listens only on localhost and rejects anonymous clients unless you configure a listener. Add listener 1883 0.0.0.0 with allow_anonymous false and a password file.
Should I expose my Raspberry Pi Mosquitto broker to the internet?
It is not recommended. Bridge outbound to a cloud broker instead, so remote access goes through a TLS-secured service and your router keeps all inbound ports closed.
Can Mosquitto on a Raspberry Pi handle many devices?
For a home or small site, a Pi handles typical sensor traffic easily. The limits you hit first are usually SD card wear and maintenance effort rather than raw throughput.
Does the bridge need a special account on ConnectMQ?
No. The bridge is a normal MQTT client, so it uses the same username, password and client ID that the portal generates for any device.
