Skip to main content
Version: Mosquitto 2.6

Roles

This section describes how to manage roles and ACLs (Access Control Lists). A role contains a number of ACLs, which either specifically allow or deny an action. Add as many ACLs as you need to a role.

Roles are part of the dynamic security of Mosquitto. See here for a detailed description of the concepts of dynamic security.

info

The dynamic security feature is available since version 2.0 of Eclipse Mosquitto. If you are still using version 1.6, see this guide on how to migrate.

Roles Overview

The roles overview lists all roles showing their name, text name and description. The Access Control List for a role has to be defined in the pages for editing or creating a role.

Following a sample roles table listing some sample roles:

Below the table you can select how many roles are displayed on one page of the table. Clicking on the arrow button will show the next or previous set of roles, if there are more roles defined than visible on one page.

Create roles

Create a role by clicking the "New Role" Button in the bottom right corner. Set a name and description to remind yourself, why you added this particular role.

You can not set the ACLs in this page. You can edit the ACLs by clicking on a role on the overview table to edit it and then switching from the "Details" tab to the "ACLs" tab.

Edit roles

Here you can edit the properties for the role. Two tabs allow you to define these. Initially the role details are editable:

Role Details

  • Name: Enter a unique name for the role
  • Text Name: Enter an optional additional name for the role
  • Description: Enter an optional description for the role to decribe the purpose of the role

In addition, the Role ACLs can be edited by switching the tab.

Role ACLs

The following ACL types are available:

  • publishClientSend: Restrict the topics this client is allowed to use when publishing to the broker
  • publishClientReceive: Restrict the topics this client is allowed to use when receiving published messages from the broker
  • subscribeLiteral: Restrict the exact topic filters that this client is allowed to subscribe to. Setting to # would mean the client cannot subscribe to the # topic, but could subscribe to test/topic, for example.
  • subscribePattern: Restrict a range of topic filters that this client is allowed to subscribe to.
  • unsubscribeLiteral: Restrict the exact topic filters that this client is allowed to unsubscribe from. Setting to # would mean the client cannot unsubscribe from the # topic, but could unsubscribe from test/topic, for example.
  • unsubscribePattern: Restrict a range of topic filters that this client is allowed to unsubscribe from.

Select the ACL type in the dropdown, define the topic and priority of the ACL and decide between "allow" and "deny".

Configuring default access

The initial configuration sets the default ACL type behaviors to:

  • publishClientSend: deny
  • publishClientReceive: allow
  • subscribe: deny
  • unsubscribe: allow

You can edit the default settings by clicking on the "edit default ACL Access" icon at the top right of the roles overview table.