ACL & Client Management

ACL clients are the MQTT accounts registered in your broker's dynamic security system. Each client has credentials that devices use to authenticate and a set of permissions that control what topics they can publish to and subscribe to.

What ACL Clients Are

An ACL client entry controls two things:

• Authentication - the username and password a device uses to connect to the broker
• Authorization - what topics the client can publish to and subscribe to, determined by assigned roles and group memberships

Every device that connects to your BunkerM broker should have its own client entry. This gives you full visibility and the ability to disable or remove individual devices without affecting others.

Creating a New Client

1. Navigate to ACL > Clients in the sidebar.
2. Click Add Client.
3. Enter a Client ID - this is the MQTT client identifier and must be unique.
4. Enter a Username - used for authentication.
5. Enter a Password - stored as a secure hash, never in plaintext.
6. Optionally set the client status to Enabled or Disabled at creation time.
7. Click Save.

The client is active immediately and can connect using the provided credentials.

Enabling and Disabling a Client

You can toggle a client's enabled state directly from the ACL Clients page:

• Enabled - the client can connect and exchange messages normally.
• Disabled - the client cannot connect. If currently connected, it is kicked from the broker immediately.

Find the client in the list and click its enable/disable toggle. The change takes effect instantly on the broker.

Assigning Roles to a Client

Roles define what topics a client can access. You can assign one or more roles directly to a client:

1. Find the client in the list and open its detail view.
2. Click Add Role.
3. Select a role from the dropdown.
4. Optionally set a priority (higher priority roles are evaluated first when rules conflict).
5. Click Save.

The client immediately inherits all ACL rules defined in that role. You can assign multiple roles to the same client. See ACL Roles for details on creating and configuring roles.

Assigning Groups to a Client

Groups let you manage permissions for many clients at once. When a client belongs to a group, it inherits all roles assigned to that group.

1. Open the client detail view.
2. Click Add to Group.
3. Select the group from the dropdown.
4. Click Save.

See ACL Groups for more detail on group permissions and use cases.

Changing a Client's Password

1. Find the client and click Edit.
2. Enter a new password in the password field.
3. Click Save.

The password change takes effect immediately. Any currently connected session using the old password continues until it disconnects. New connections must use the new password.

Deleting a Client

1. Find the client and click Delete.
2. Confirm the deletion.

Deleting a client removes its credentials and all direct role and group assignments. If the client is currently connected, its session is terminated immediately. This action cannot be undone.

Import and Export

BunkerM supports importing and exporting your entire ACL configuration as a JSON file:

• Export: click the Export button on the ACL Clients page. A JSON file is downloaded containing all clients, roles, and groups.
• Import: click Import and select a previously exported JSON file. The import merges with or replaces your existing configuration depending on the mode selected.

Export is useful for backups, migration between BunkerM instances, and storing your ACL config in version control.

Importing from a Mosquitto Password File

If you have an existing Mosquitto deployment with a passwd file, you can import it into BunkerM:

1. Go to ACL > Clients.
2. Click Import from Password File.
3. Upload your Mosquitto passwd file.
4. BunkerM creates client entries for each user found in the file.

Password file imports create clients without roles or group assignments - you will need to assign roles after importing.

How Credentials Work

BunkerM uses Mosquitto's dynamic security plugin to manage client credentials. When a client connects:

1. The broker receives the MQTT CONNECT packet with a username and password.
2. Mosquitto checks the credentials against the dynamic security database.
3. If the credentials match and the client is enabled, the connection is allowed.
4. If the client is disabled or the credentials are wrong, the connection is rejected.

Passwords are stored as secure hashes - the broker never stores plaintext passwords.

Best Practices

• One client per device - avoid sharing credentials between multiple devices. If one is compromised, you can disable just that client.
• Least privilege - assign only the roles a client actually needs.
• Descriptive naming - use names that identify location and function.
• Disable before delete - when decommissioning a device, disable its client first to immediately cut access, then delete the entry later.
• Regular audit - periodically review your client list and remove entries for devices no longer in use.

ACL Clients vs Connected Clients

The ACL Clients page shows your full account database - all registered MQTT clients whether currently online or not. The Connected Clients page shows only clients with an active live connection right now. Use ACL Clients for account management and Connected Clients for live session monitoring.