IMD SolutionComputing LibraryShop main store

How-to

Run a secure Mosquitto MQTT lab broker with Node-RED

Edge computing and IIoT Published 5 min read

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
  1. The listener profile to commit to
  2. Create the lab CA and server certificate
  3. Configure the TLS listener
  4. Add users and the topic ACL
  5. Point Node-RED at the secure listener
  6. Give the ESP32 a valid clock before TLS
  7. Verify the whole chain before the session
  8. What fails on the day
  9. Questions asked

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 #

  1. Create a lab certificate authority and keep its private key on the server, never on a client.
  2. Generate the broker's server key and certificate from that CA.
  3. 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.
  4. Place ca.crt, server.crt and server.key under /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 #

  1. Create one user per team with mosquitto_passwd, plus a separate user for Node-RED. Students never receive the Node-RED credentials.
  2. Build /etc/mosquitto/acl from user <username> blocks: the ACL format defines each user's topic permissions in the block under their name.
  3. Give team N write only on lab/teamN/# and read on lab/#. Team 3 can publish to lab/team3/sensor and nothing under lab/team4/.
  4. Give the Node-RED user read on lab/#, and write on a command subtree only if an exercise drives outputs.
  5. Restart the broker, re-check the log, and distribute ca.crt alone 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.

  1. Open the MQTT broker configuration node and set the host to the same name that sits in the certificate's SAN, with port 8883.
  2. Enable TLS in that node and load ca.crt; Node-RED validates the broker exactly as a device does.
  3. Enter the Node-RED user's name and password, then deploy.
  4. 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 #

  1. From a second machine on the lab network, confirm TCP to 8883 reaches the broker.
  2. Start mosquitto_sub with ca.crt, team1's credentials and the filter lab/#.
  3. Publish ten JSON readings as team1 to lab/team1/sensor: the subscriber prints 10 of 10.
  4. 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.
  5. Attempt a connection with no credentials and confirm the broker refuses it.
  6. 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.

Keep reading

  • How-to

    Harden a Node-RED OPC UA server exposing PLC tags

    A default Node-RED OPC UA server accepts any client that can reach its port until three changes land: set message security mode to SignAndEncrypt with the Basic256Sha256 policy, remove mode None and anonymous login, and admit clients only through application-certificate trust lists. Those three changes are the whole decision; the rest is execution.

    Edge computing and IIoT

  • Troubleshooting

    Fix MQTT sensor data missing in Node-RED

    A green MQTT connection in Node-RED proves only a broker session, not that the GSM module published a value or that the flow subscribes to its topic. An http in node cannot receive MQTT publications at all: use an mqtt in node. Trace RS-485 acquisition, publish result, broker identity and topic match in order, and fix the first stage with no positive result.

    Edge computing and IIoT

  • How-to

    Run Python and Node-RED beside PLC code on an edge PC

    Keep the IEC 61131-3 program in the controller runtime and run Python and Node-RED as separate Docker containers on the same edge PC. Exchange data over one MQTT interface with a fixed publish period, and declare data stale after three missed periods. One container per workload, and nothing from Python or Node-RED inside the control project.

    Edge computing and IIoT

Configuring TLS in the Node-RED Sparkplug node