How-to
Run a secure Mosquitto MQTT lab broker with Node-RED
Short answer
Run Mosquitto on port 8883 with TLS, per-user passwords and an ACL that lets each team write only under lab/teamN/# and read all of lab/#, with a separate Node-RED user that reads everything. Distribute ca.crt only, and prove the ACL by publishing to another team's prefix and seeing nothing arrive.
On this page
Run Mosquitto on port 8883 with TLS, per-user passwords and a topic ACL, and give Node-RED its own user: one broker then serves a whole workshop without any student being able to publish as another team. Port 8883 is the registered port for MQTT over TLS, as 1883 is for plain MQTT. Each team writes only under its own lab/teamN/# prefix and reads all of lab/#, so a spoofed publisher or a buggy flow cannot corrupt another team's data. Hand clients the CA certificate only, keep the server key on the broker, and prove the ACL with a denial test before the first session.
The listener profile to commit to #
Commit to TLS with authentication from the first session, not as a later upgrade. On a plain listener, usernames, passwords and payloads cross the wire unencrypted, so any student with a packet capture reads every credential in the room. The default profile is one listener on 8883 with the certificate files, allow_anonymous false, a password file and an ACL file. Keep a second, plain listener on 1883 only while some ESP32 firmware cannot yet load a CA certificate, bind that listener to the isolated lab interface, and remove it the moment every sketch loads the CA. Teaching authorization on day one costs one configuration file; retrofitting it after credentials have circulated costs a full re-issue.
Create the lab CA and server certificate #
- Create a lab certificate authority and keep its private key on the server, never on a client.
- Generate the broker's server key and certificate from that CA.
- Set the certificate's subject alternative name to the exact string students type as the host. If they connect to
mqtt-lab.local, that name must be in the SAN; an IP address used as the host string must be in it too, because the TLS client validates the server name against this field and a mismatch fails the handshake. - Place
ca.crt,server.crtandserver.keyunder/etc/mosquitto/certs/, and restrict the key so only the broker's service user can read it.
Configure the TLS listener #
Put the listener in a file under /etc/mosquitto/conf.d/, for example TLSconfig.conf, and restart the service:
listener 8883
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl
Restart the broker and read its log before any client connects: certificate-path and file-permission errors surface there on the first start. When the service exits immediately instead of staying up, the log names the file at fault — the same pattern as a Mosquitto broker exiting with code 3 at startup after a configuration change.
Add users and the topic ACL #
- Create one user per team with
mosquitto_passwd, plus a separate user for Node-RED. Students never receive the Node-RED credentials. - Build
/etc/mosquitto/aclfromuser <username>blocks: the ACL format defines each user's topic permissions in the block under their name. - Give team N write only on
lab/teamN/#and read onlab/#. Team 3 can publish tolab/team3/sensorand nothing underlab/team4/. - Give the Node-RED user read on
lab/#, and write on a command subtree only if an exercise drives outputs. - Restart the broker, re-check the log, and distribute
ca.crtalone to every client. The server key never leaves the broker.
The same password-file and ACL pattern applies outside the classroom; it is the standard approach when configuring Mosquitto authentication for ChirpStack brokers.
Point Node-RED at the secure listener #
If Node-RED is not on the server yet, installing Node-RED natively on a Linux edge computer puts it beside the broker as a plain system service.
- Open the MQTT broker configuration node and set the host to the same name that sits in the certificate's SAN, with port 8883.
- Enable TLS in that node and load
ca.crt; Node-RED validates the broker exactly as a device does. - Enter the Node-RED user's name and password, then deploy.
- Subscribe an MQTT-in node to
lab/#, parse with a JSON node, and store or display the result. Keep payloads as JSON such as{"temp":23.4,"unit":"C"}so one flow serves every team.
When a publish reaches the broker but nothing appears in Node-RED, the hop-by-hop method that fixes MQTT sensor data missing in Node-RED finds the broken hop — most often the subscription filter.
Give the ESP32 a valid clock before TLS #
A device client fails the TLS handshake for one of three reasons: the CA is not loaded, the host string does not match the SAN, or the board's clock is wrong. An ESP32 that boots without a time sync can sit decades in the past and treat a valid certificate as not yet valid, so sync over NTP before the first connect and have the sketch use the same host string that is in the SAN. The same client-side checks apply to any MQTT TLS client setup against a Mosquitto broker, from a cellular gateway to a desktop tool.
Verify the whole chain before the session #
- From a second machine on the lab network, confirm TCP to 8883 reaches the broker.
- Start
mosquitto_subwithca.crt, team1's credentials and the filterlab/#. - Publish ten JSON readings as team1 to
lab/team1/sensor: the subscriber prints 10 of 10. - Publish ten more as team1 to
lab/team2/led: the count stays at 10. Twenty published minus ten received equals ten dropped, exactly the ten aimed at another team's prefix, and team1's client reported no error on any of them. - Attempt a connection with no credentials and confirm the broker refuses it.
- Flash one ESP32 with the final sketch, confirm the NTP-synced TLS connection in the broker log, and watch one JSON reading arrive in Node-RED.
With 10 of 10 delivered on a team's own prefix, 0 of 10 delivered on another team's prefix and anonymous connections refused, the lab is safe to open. If any cross-team message arrives, that team's user block grants too much — check the prefix spelling and case first.
What fails on the day #
| Symptom | Cause | Fix |
|---|---|---|
| Two students disconnect each other in a loop | Identical client IDs; the broker drops the older session | Derive the client ID from team name or chip ID |
| Some clients connect, others never reach the broker | Access-point client isolation or a different subnet | Put server and clients on one lab network and confirm with ping |
| ESP32 connects on 1883 but not 8883 | Missing CA, SAN mismatch or an unset clock | Load ca.crt, match the SAN to the host string, sync over NTP |
Both recurring faults — duplicate client IDs and denied publishes — are fixed on the broker or sketch side, which is the point of this profile: the broker enforces the rules, and no student's hardware can break them for anyone else.
Questions asked
Why does an ESP32 fail the TLS handshake right after boot but connect later in the session?
The board starts with no valid time, treats the broker certificate as not yet valid, and refuses the handshake. Once an NTP sync runs, the clock falls inside the certificate's validity window and the connection works. Sync time over NTP before the first connect, and make the SAN match the exact host string the sketch uses, because a name mismatch fails the same handshake for a different reason.
Why does a student's publish report success when nobody receives the message?
The broker accepts a publish and silently drops it when the ACL denies that topic for that user; MQTT returns no error to the publisher, so success only means the packet left the client. Run the same publish from a desktop client such as MQTT Explorer with that team's credentials and watch a subscriber on the receiving prefix. If nothing arrives, the topic string differs from the ACL by case or prefix.
Should each student get a broker user, or one per team?
One per team is enough for a workshop: the ACL is scoped to the team prefix, so extra users add no protection. Go per student only when you must attribute a publish to a person, because mosquitto_passwd then needs an entry per student and the log grows one line per user. The topic rules stay identical either way.
Does the Node-RED user need write access too?
Only if an exercise drives outputs, such as a command topic that switches a team's LED. Give the Node-RED user write on the command subtree alone, for example lab/teamN/cmd/#, and read on all of lab/#. Keep it off the sensor prefixes so a buggy flow cannot overwrite another team's readings, and never share this user's credentials with students.