Install Mosquitto on Raspberry Pi 5: Secure MQTT Broker Setup

This guide turns a Raspberry Pi 5 into a local MQTT broker for ESP32/ESP8266 devices, Node-RED flows and other clients. You will install Mosquitto and its command-line tools, confirm the service starts automatically, test a message on the Pi itself, and then configure authenticated access for clients on your trusted LAN.

One detail matters particularly for Mosquitto 2.0 and later: a broker started without an explicit listener is local-only by default. A successful local test does not prove an ESP32 on another machine can connect. This secure default prevents accidentally opening a broker to a network before its access policy is configured.

These commands assume a current Raspberry Pi OS installation with internet access and sudo privileges. Package versions and configuration details can change; use the official Mosquitto docs if your release behaves differently.

1. Install Mosquitto and client tools

Open a terminal on Raspberry Pi 5 or connect with SSH, then run:

sudo apt update sudo apt install -y mosquitto mosquitto-clients

The mosquitto package provides the broker service. mosquitto-clients provides utilities such as mosquitto_pub and mosquitto_sub, which let you test MQTT independently of firmware. If the command-line test fails, do not debug the ESP32 yet.

Check the installed tools and service status:

mosquitto -h sudo systemctl is-active mosquitto sudo systemctl status mosquitto --no-pager

An active service means systemd considers the broker running; it does not guarantee remote access, correct credentials or a topic ACL.

2. Enable Mosquitto at boot

Enable and start the service:

sudo systemctl enable --now mosquitto

Check separately:

sudo systemctl is-enabled mosquitto sudo systemctl is-active mosquitto

The first should report enabled; the second should report active while the broker is running. After configuration changes, use sudo systemctl restart mosquitto and check the journal if it does not return to active:

sudo journalctl -u mosquitto -n 80 --no-pager

Keep the Pi updated and use stable power and storage. If MQTT is part of an automation system, decide what happens when the broker is unavailable rather than assuming the service always stays online.

3. Test publish and subscribe locally

Open two terminals on the Pi. In the first, subscribe:

mosquitto_sub -h 127.0.0.1 -t 'solderhub/test' -v

In the second, publish:

mosquitto_pub -h 127.0.0.1 -t 'solderhub/test' -m 'hello from Raspberry Pi 5'

The subscriber should display the topic and message. This confirms that a local client can reach the broker. If the default configuration is local-only, this is expected to work before LAN access is configured.

If it fails, check the service and log first. Do not open the firewall or create a listener merely to fix a malformed local command.

4. Understand the local-only listener default

Mosquitto 2.0 changed listener behavior. When there is no configured listener, the broker binds to loopback interfaces such as 127.0.0.1 and ::1 and allows local testing under its documented default behavior. Other computers and microcontrollers cannot connect through the Pi's LAN address in this mode.

Read the official Mosquitto 2.0 migration notes. The correct next step is not to turn anonymous access on; it is to configure a listener, decide who may connect, and restrict which topics each client may read or write.

5. Create a password file and configure LAN access

For a small lab, the classic password-file approach can be used when supported by the installed Mosquitto version. Create a dedicated configuration file:

sudo nano /etc/mosquitto/conf.d/solderhub.conf

For a straightforward lab configuration on versions supporting these options, use:

listener 1883 allow_anonymous false password_file /etc/mosquitto/passwd

Create a broker username and password interactively:

sudo mosquitto_passwd -c /etc/mosquitto/passwd solderhub_client

The command prompts for a password; do not type a real password into a shared screenshot or commit it into an article. Protect the password file and confirm the service account can read it according to your OS package configuration. Then restart and check the service:

sudo systemctl restart mosquitto sudo systemctl is-active mosquitto

Mosquitto's newer release documentation evolves the recommended authentication configuration; Mosquitto 2.1 deprecates per_listener_settings and recommends authentication plugins for more advanced deployments. Check the current configuration manual and authentication-methods guide for your installed major version before using these directives in production.

6. Test with authentication enabled

In a terminal, test using the username and a local test password:

mosquitto_sub -h 127.0.0.1 -t 'solderhub/test' -u solderhub_client -P 'REPLACE_WITH_TEST_PASSWORD' -v

Publish from a second terminal with the same test account:

mosquitto_pub -h 127.0.0.1 -t 'solderhub/test' -u solderhub_client -P 'REPLACE_WITH_TEST_PASSWORD' -m 'authenticated test'

Replace the placeholder locally. Passing a password on a command line may expose it through shell history or process inspection; use an isolated lab account and safer credential handling for real secrets. Avoid reusing one broad-privilege account for every device in a larger deployment.

For remote clients, replace 127.0.0.1 with the Pi's LAN address only after the listener is reachable and network rules permit it. If local testing works but LAN testing does not, investigate listener binding, routing and firewall rules before changing credentials.

7. Plan topic permissions before adding more devices

Authentication tells the broker who is connecting; authorization decides which topics that client may read or write. A temperature sensor may need to publish to its own telemetry topic but should not be able to issue relay commands. Use individual identities and topic permissions where possible.

Mosquitto supports ACL and plugin-based mechanisms, but the recommended configuration depends on the major version. Follow the official authentication guide instead of copying an old sample blindly. Do not expose a broker with anonymous access to the public internet. Password authentication without TLS can expose credentials to someone able to observe the path, so use TLS or an appropriately secured private network when traffic crosses untrusted links.

8. Connect an ESP32 or Node-RED

Find the Pi's LAN address using hostname -I or your router's device list. On a separate client, use that address as the broker host—not 127.0.0.1, which means the client itself. Confirm the port and security settings match the broker listener.

For Node-RED, configure the MQTT broker connection in MQTT In/Out node settings. For ESP32, set the same host, port, credentials and topic names in firmware. Use unique client IDs and subscribe again after reconnecting.

Continue with Node-RED with MQTT: Connect Mosquitto, Publish & Subscribe, ESP32 MQTT Tutorial: Publish and Subscribe with Arduino IDE, and MQTT Troubleshooting: Connection Refused, rc=-2 and rc=5.

Troubleshooting

The service is active but remote clients fail: check whether an explicit listener is configured and bound to an address reachable by those clients. The local-only default is intentional.

The broker fails to restart: inspect journalctl for Mosquitto, check configuration syntax, and verify password/ACL files exist and are readable by the service.

Clients get disconnected: look for duplicate client IDs, authentication failures, network instability and broker logs.

Authentication fails: confirm username and password, then check which configuration file and authentication method the running service loaded.

Do not solve every failure with anonymous mode. A quick insecure configuration can make a demo connect while leaving the broker open to unintended publishers and subscribers.

Security checklist

• Keep the broker updated and inspect current configuration documentation.
• Use a specific listener and explicit authentication policy.
• Use distinct credentials per device or trust boundary.
• Apply topic-level authorization where needed.
• Use TLS, a VPN or a secured private network for untrusted paths.
• Do not expose the broker directly to the public internet without a deliberate security architecture.
• Back up configuration and verify a restart loads the intended policy.
• Test unauthorized access, not only successful login.

Official references: Mosquitto 2.0 migration guide, configuration manual, and authentication methods.

Next steps

Continue with Test MQTT without Hardware, learn MQTT topic naming best practices, and connect a board using the ESP32 MQTT tutorial.

The best broker setup is not the one with the fewest lines of configuration. It is the one whose listener scope, credentials, permissions and recovery behavior are appropriate for the environment in which it runs.