ACL file

The built-in ACL sets rules through files, which is simple and lightweight to use. It is suitable for projects with predictable number of rules, no change or small change requirements.

ACL rules file:

etc/acl.conf

TIP

The built-in ACL has the lowest priority and can be overridden by the ACL plugin. If you want to disable it, you can comment all the rules. After the rules file is changed, EMQ X Broker needs to be restarted to make them taking effect.

Define ACL

The built-in ACL is the lowest priority rule table. If it is not hit after all the ACL checks are completed, the default ACL rule is checked.

The rules file is described in Erlang syntax:

%% Allow "dashboard" users to subscribe to "$ SYS / #" topics
{allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.

%% Allow users with IP address "127.0.0.1" to publish/subscribe to topics "# SYS/#", "#"
{allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.

%% Deny "All Users" subscribe to "$ SYS/#" "#" Topics
{deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.

%% Allow any other publish/subscribe operation
{allow, all}.

1. The first rule allows clients to publish and subscribe to all topics
2. The second rule prohibits all clients from subscribing to the topics $ SYS / # and #
3. The third rule allows clients with IP address 127.0.0.1 to publish / subscribe to the topics $ SYS / #and #, which makes a special case for the second rule
4. The fourth rule allows clients with the username dashboard to subscribe to the topic $ SYS / #, which makes a special case for the second rule

It can be seen that the default ACL is mainly to restrict the client's permissions on the system topic $SYS/# and the all wildcard topic #.

acl.conf Writing rules

The rules in the acl.conf file are matched from top to bottom in writing order.

The syntax rules of acl.conf are included in the comments at the top. Those familiar with Erlang syntax can read the comments at the top of the file directly or refer to the following descriptions:

• Line comments are expressed as %%.
• Each rule consists of four tuples and ends with ..
• The first position of the tuple indicates that after the rule is successfully hit, the permission control operation is performed. The possible values are:
  • allow
  • deny
• The second position of the tuple indicates the user to which the rule takes effect. The format that can be used is:
  • {user, "dashboard"}：The rule only takes effect for users whose Username is dashboard
  • {clientid, "dashboard"}：The rule only takes effect for users whose ClientId is dashboard
  • {ipaddr, "127.0.0.1"}：The rule only takes effect for users whose Source Address is "127.0.0.1"
  • all：The rule takes effect for all users
• The third position of the tuple indicates the operation controlled by the rule with the possible value:
  • publish：The rule applies to PUBLISH operations
  • subscribe：The rule applies to SUBSCRIBE operations
  • pubsub：The rule applies to both PUBLISH and SUBSCRIBE operations
• The fourth position of the tuple means the list of topics restricted by the rule. The content is given in the form of an array. For example:
  • "$SYS/#"：a Topic Filter which means that the rule can hit topics that match $ SYS / #; for example, it can hit "$\text{SYS/\#" and "}$SYS/a/b/c"
  • {eq, "#"}：It indicates full equivalence of characters. The rule can only hit strings with the topic #. It cannot hit /a/b/c, etc.
• In addition, there are two special rules:
  • {allow, all}：Allow all operations
  • {deny, all}：Deny all operations

After the acl.conf modification is completed, it will not be automatically loaded into the EMQ X Broker system, but needs to be performed manually:

./bin/emqx_ctl acl reload

TIP

Only a few simple and general rules is contained in acl.conf that make it a system-based ACL principle. If you need to support complex, large amounts of ACL content, you should implement it in an authentication plugin.