How-to
Writing MQTT Distributor ACL topic filters for Sparkplug B
Short answer
Give each Sparkplug B edge node its own credential with one write filter, spBv1.0/GroupID/+/EdgeNodeID/#, and two read filters, STATE/PrimaryHostID and the same node filter. The ACL is a plain MQTT topic matcher: pin the namespace, group and node as literals, wildcard the message type with + and the device level with #. Any publish or subscribe outside the granted filters disconnects the client, so the NDEATH will and the STATE subscription must be inside the entries.
On this page
Scope each Sparkplug B edge node with its own username and two ACL entries in the Distributor: a write filter, spBv1.0/GroupID/+/EdgeNodeID/#, and read filters, STATE/PrimaryHostID plus spBv1.0/GroupID/+/EdgeNodeID/#, with the node's actual Group ID, Edge Node ID and primary host ID substituted in. The ACL is not Sparkplug-aware — it is a plain MQTT topic-filter matcher — but the Sparkplug topic structure is exactly what lets one entry cover everything a node does. The documented example W device_one/temp/#,R state/# shows the whole grammar: W grants publish, R grants subscribe, and a comma separates entries. Design around one behavior: outside the granted filters, the Distributor drops the client.
What the ACL entry matches #
| Element | Meaning |
|---|---|
W |
Write privilege: the client may publish to topics matching the filter |
R |
Read privilege: the client may subscribe to topics matching the filter |
, |
Separates entries in the ACL field |
/ |
Topic level separator |
+ |
Matches exactly one topic level |
# |
Matches any number of remaining levels, parent included, and must be the last character |
Entries attach to a username and password pair, so the scope travels with the credential, not with the IP address. The policy behaves like a firewall rule set: a broad wildcard covers everything, and once you narrow the filters, every topic the client touches must be permitted explicitly. The wildcards are where most filters go wrong, so understand the failure modes behind mixing up # and * in topic rules before writing yours.
Map the Sparkplug topic onto the filter #
The Sparkplug specification defines the topic namespace as namespace/group_id/message_type/edge_node_id/[device_id] — five levels, the last present only on device messages. Map each level to a filter strategy:
| Level | Element | Strategy |
|---|---|---|
| 1 | spBv1.0 |
Literal. Pin the namespace. |
| 2 | Group ID | Literal. This is the isolation boundary between publishers. |
| 3 | Message type | +. One level covers every verb the protocol uses. |
| 4 | Edge Node ID | Literal. This is the per-gateway boundary. |
| 5 | Device ID, optional | #. Covers node-level and device-level topics together. |
The message type sits between the group and the node, so no prefix wildcard can pin both ends — the single-level + at level 3 is what makes the pattern work. The eight message types split across two depths: NBIRTH, NDATA, NDEATH and NCMD are node topics at four levels; DBIRTH, DDATA, DDEATH and DCMD are device topics at five. Because # also matches its parent level, one filter catches both depths: spBv1.0/PlantA/NDATA/Line1 (4 levels) and spBv1.0/PlantA/DDATA/Line1/Motor1 (5 levels) both match spBv1.0/PlantA/+/Line1/#.
The decision at level 3: never pin it to a literal. A node must publish births, data and its own death message, so the + stays no matter how narrow you make the rest.
The entries that scope one edge node #
W spBv1.0/GroupID/+/EdgeNodeID/#
R STATE/PrimaryHostID, spBv1.0/GroupID/+/EdgeNodeID/#
Enter these against a dedicated username and password created for that one gateway, whether the client is an Ignition edge node or a third-party Sparkplug B box. Read the entry in plain words: this credential may publish every Sparkplug message type for exactly this group and node, including every device under it, and may read the primary host's state topic plus its own command topics. GroupID, EdgeNodeID and PrimaryHostID are the exact strings configured on the gateway and the host application — substitution is the only edit you make.
The operations that disconnect a narrowed client #
- The NDEATH will. A Sparkplug node registers its death topic,
spBv1.0/PlantA/NDEATH/Line1, as the MQTT Will inside the CONNECT packet. If the will topic falls outside the write filter, the connection is refused or torn down at connect time, before the first birth ever publishes. The filter above already covers it, because+occupies the message-type level. - The state subscription. The node subscribes to the host application's state topic to decide whether the primary host is online;
STATE/PrimaryHostIDin the read entries is what permits that subscription, and omitting it drops the client like any other denied operation. Applying role-based rules on the STATE/PrimaryHostID topic is its own design subject when several hosts share a broker. The primary host registers its own will on that same topic, a separate rejection path covered in why a broker rejects a Sparkplug client over its STATE will. - Command subscriptions. The node subscribes to
NCMDandDCMDfor its own node, which is why the read entry mirrors the write entry. If commands still fail once the ACL is correct, the causes are the ones behind Sparkplug B sending data but receiving no SCADA commands. - Additional Group IDs. One gateway configured with a second transmitter set — a different Group ID or node ID — needs its own
WandRentries for that set, or the client drops the moment the extra set publishes.
Worked example: one node, three devices #
Take a gateway with Group ID PlantA, Edge Node ID Line1, devices Motor1, Pump2 and VFD3, and a primary host SCADA1.
Write filter: spBv1.0/PlantA/+/Line1/#. Count what that one entry covers:
- Node-level publishes: 3 message types (
NBIRTH,NDATA,NDEATH) × 1 node = 3 topics. - Device-level publishes: 3 message types (
DBIRTH,DDATA,DDEATH) × 3 devices = 9 topics. - Total: 3 + 9 = 12 publish topics matched by a single entry.
Read side: 1 NCMD topic + 3 DCMD topics + STATE/SCADA1 = 5 subscriptions, covered by the two read filters. Written out as literal topics, the same scope is 12 write entries plus 5 read entries — 17 lines. The two wildcards collapse that to 3.
Level check: spBv1.0/PlantA/NBIRTH/Line1 is 4 levels, spBv1.0/PlantA/DDATA/Line1/Motor1 is 5 levels, the + consumes exactly level 3 and # the remainder, so one filter spans both depths.
Rejection check: a test node publishing spBv1.0/PlantB/NDATA/Line1 misses at level 2 (PlantB does not equal PlantA), the publish is denied, and the Distributor disconnects the client. That is the acceptance test: if the rogue publish succeeds, the ACL is not applied to that credential.
Apply the entries step by step #
- Record the exact Group ID, Edge Node ID and primary host ID from the gateway configuration.
- Create a dedicated username and password in the Distributor for that one node; do not share the credential across gateways.
- In the lab, start permissive:
W spBv1.0/#andR spBv1.0/#plusSTATE/#, and confirm the node connects, births and streams. - Subscribe to
#with an administrator credential and capture every topic the node publishes and subscribes to. - Narrow the entries to
W spBv1.0/PlantA/+/Line1/#andR STATE/SCADA1, spBv1.0/PlantA/+/Line1/#. - Restart the gateway connection and verify birth, data and a command round-trip.
- Point a test gateway at a foreign Group ID and confirm the Distributor disconnects it — run this in the lab, never against the running plant.
- Repeat per node and roll the entries to production in a maintenance window.
Failure signatures #
| Symptom | Likely ACL cause | Fix |
|---|---|---|
| Connects, then drops, repeating | Publish or subscribe outside the filters — often the NDEATH will or a second transmitter set | Compare the captured topic list with the entries and add the exact missing topic |
| Connects but never births | Write filter does not span the message-type level | Use spBv1.0/PlantA/+/Line1/#, not a filter with level 3 pinned or missing |
| Data flows but commands never reach the device | Read entries miss the node's NCMD/DCMD scope |
Mirror the write filter in the read entries |
| Disconnects as soon as it subscribes to the host state | STATE/PrimaryHostID absent from the read entries |
Add the state topic to the read list |
What the primary host credential needs #
The consuming side holds the inverse scope. The host application reads the whole namespace it serves — one entry, R spBv1.0/# — and writes the command topics it issues, which follow the same namespace: spBv1.0/PlantA/NCMD/Line1 for node commands, spBv1.0/PlantA/DCMD/Line1/Motor1 for device commands, plus its own STATE/SCADA1 topic where it publishes online and offline. Give the host one broad read entry, write entries limited to the command topics of the groups it actually commands, and a state write scoped to its own host ID. The consuming module's side is worked through entry by entry in the MQTT Engine ACL configuration for Sparkplug B.
Questions asked
Is the ACL scope tied to the username or the IP address?
To the username. ACL entries attach to a username and password pair in the Distributor, so the scope follows the credential wherever the gateway connects from. That is why each edge node needs its own username: two gateways sharing one credential inherit the same filters, and whichever node is not named in the entries is disconnected on its first publish.
Does capitalization matter in the topic filters?
Yes. Topic filters are case-sensitive, so the Group ID and Edge Node ID in the filter must match the gateway configuration character for character. A trailing space in either identifier is a common failure: the filter then names a node that does not exist, every publish misses it, and the client is disconnected. Copy the identifiers from the configuration rather than retyping them.
Can one credential cover a whole group instead of one node?
Yes. Write and read spBv1.0/PlantA/# grants that credential every node and device in group PlantA. Use it only when one gateway genuinely owns the whole group, for example a single box publishing several edge nodes under one Group ID. When separate gateways share a group, pin the Edge Node ID as well, so a misconfigured device cannot publish over a neighbor's data.
Do these ACL rules also work for non-Sparkplug MQTT devices?
Yes, because the ACL is a plain MQTT topic matcher and knows nothing about Sparkplug. For a device publishing ordinary topics, grant write on its own prefix, for example W workshop3/oven/#, and read only on the topics it actually subscribes to. Sparkplug simply hands you stable topic levels to pin; with arbitrary topics you choose the boundary yourself, and the same disconnect rule applies.