ACL Roles

Roles are reusable permission templates. Each role holds a set of ACL rules that specify which MQTT topics a client can publish to, subscribe to, or is denied access to. Assign one role to many clients instead of configuring permissions per device.

What Roles Are

A role contains one or more ACL rules. Each rule specifies:

A topic pattern - which topic or set of topics the rule applies to
An action - whether the rule controls publishing, subscribing, or both
An effect - whether the action is allowed or denied

When a client attempts to publish or subscribe, Mosquitto evaluates the ACL rules from all roles assigned to that client (directly and through groups). If a matching allow rule is found, the action proceeds. If a deny rule matches first, the action is blocked.

Creating a Role

Navigate to ACL > Roles in the sidebar.
Click Add Role.
Enter a Role Name - use something descriptive like sensor-read-only or admin-full-access.
Click Save. The role is created empty.
Click on the role to open it and add ACL rules.

Adding ACL Rules to a Role

Open the role and click Add Rule.
Enter a Topic Pattern.
Select the Action: subscribe, publish, or all (both).
Select the Effect: allow or deny.
Click Save.

Repeat for each rule you want in the role.

Understanding Topic Patterns

Topic patterns support two MQTT wildcards:

`#` - Multi-level wildcard

Matches everything from that position in the hierarchy downward.

sensor/#

Matches: sensor/temp, sensor/humidity, sensor/floor2/temp, sensor/floor2/room1/temp. Use # at the end of a pattern to grant access to an entire subtree.

`+` - Single-level wildcard

Matches exactly one topic level.

sensor/+/temperature

Matches: sensor/kitchen/temperature, sensor/bedroom/temperature. Does not match sensor/temperature or sensor/floor2/room1/temperature.

Assigning a Role to a Client

Go to ACL > Clients and open the client detail view.
Click Add Role.
Select the role from the dropdown.
Set an optional priority and click Save.

The client immediately gains all permissions defined in that role.

Assigning a Role to a Group

Go to ACL > Groups and open the group detail view.
Click Add Role.
Select the role and click Save.

All clients in the group immediately inherit the role's permissions.

Editing and Deleting a Role

To edit, open the role from ACL > Roles and add, edit, or remove individual ACL rules. Changes take effect immediately on all clients that have this role assigned.

To delete, find the role and click Delete. Deleting a role removes it from all clients and groups. Those clients lose the permissions the role was granting - make sure you are not removing access that devices depend on.

Priority and Rule Ordering

When a client has multiple roles, Mosquitto evaluates rules in priority order. Higher priority numbers take precedence over lower ones. Within a single role, rules are evaluated in the order they are listed - the first matching rule wins.

A deny rule matching before an allow rule will block the action.
If no rule matches, the action is denied by default (Mosquitto's default-deny behavior).
Use explicit deny rules to carve exceptions out of broad allow rules.

Common Role Examples

Sensor publish-only

For sensors that should only publish data and not subscribe to anything:

Topic: sensor/+/data   Action: publish   Effect: allow

Actuator command receiver

For actuators that receive commands and report status:

Topic: actuator/+/command   Action: subscribe   Effect: allow
Topic: actuator/+/status    Action: publish     Effect: allow

Dashboard read-all

For monitoring tools that need to read all traffic:

Topic: #   Action: subscribe   Effect: allow

Admin full access

For administrative clients that need unrestricted access:

Topic: #   Action: all   Effect: allow

Deny exception pattern

Allow everything in a subtree except one sensitive topic. Rules are evaluated by priority - the deny rule has a higher priority and fires first:

Priority 10: home/private/#   all   deny
Priority 5:  home/#           all   allow

← ACL Clients ACL Groups →