How Access Control Lists (ACLs) work and how to use them
· 10 min read
Table Of Contents
I often use ACLs when I have to give permissions to specific users or groups without compromising security. But I never fully understood how they work, as they are pretty complex. This guide will explain how they work and how to use them.
I assume experience with Linux and the command line.
ACLs must be supported and enabled by the filesystem (mounted with the
acl option). As
systemd depends on the
acl package and the most common filesystems have ACLs enabled by default, any modern Linux distribution should work.
If you are unsure if ACLs are enabled, you can check this with the following command:
tune2fs -l /dev/sdXY | grep "Default mount options:"
If enabled, the output should look something like this:
Default mount options: user_xattr acl
acl as a default mount option for a filesystem, use the
tune2fs -o acl /dev/sdXY
What exactly are ACLs
Access Control Lists allow for more fine-grained and flexible permissions for files and directories. Based on the draft for POSIX 1003.1e, ACLs are a superset of standard Linux permissions.
They are handy if you have complex permission requirements. For example, you got a docroot of your Web application owned by the
www-data user and the
developer group. The new product owner needs read access to the log files of the application. Now what? She does not have the same UID as the
www-data user, and adding her to the
developer group would be too permissive.
This situation can be tricky as standard Linux permissions only allow one user and one group. Sure, you could make everything read-only to everyone, but that would be a bad idea. You can solve this situation with ACLs by adding a new user with read-only permissions to the docroot.
The situation above is just a simple example, and there are way more complex scenarios that ACLs can solve.
Even though the draft never made it to an official release, most Unix-like systems implemented Access Control Lists.
Recap the Basics
Before we dive in, let’s quickly recap how basic permissions on Linux work. Linux gives us three entities for which we can manage permissions separately:
- User (owner)
- Group (owner group)
- Other (everyone else)
For each entity, we can set three permissions (there are more, but for the sake of simplicity, we will ignore them for now):
- Read (octal 4)
- Write (octal 2)
- eXecute (octal 1)
drwxr-x--- 2 cassidy developer 4096 Sep 11 13:05 exampledir
Here we can see that the owner is the user
cassidy and the owner group is
developer. Cassidy can read and create files in the directory, whereas the group members can only read/list the directory’s content. Everyone else has no access at all.
Viewing current ACLs
After we reviewed how basic permissions work, let’s look at identifying files with Access Control Lists. Luckily
ls knows about ACLs and indicates what files have ACLs by appending a
+ to the permissions:
drwxr-x---+ 2 cassidy developer 4096 Sep 11 13:05 exampledir
Now that we know that this file has ACLs let’s display all ACLs by using the
[root@lab docroot]# getfacl exampledir # file: exampledir # owner: cassidy # group: developer user::rwx user:finley:rwx #effective:r-x group::r-x mask::r-x other::--- default:user::rwx default:user:finley:rwx #effective:r-x default:group::r-x default:mask::r-x default:other::---
That’s a lot to digest. Let’s break it down.
How ACLs work
The first three lines display the filename, the owner, and the owner group:
# file: exampledir # owner: cassidy # group: developer
The next block specifies individual user permissions. This example shows that the user
finley has read and execution rights for this directory. The first line without a user name,
user::rwx, equals to the permission of the owner (Cassidy):
The third block contains group permissions. In this case, there are only the permissions of the owner group, but there could be a named entry like
group:management:r-x, which would allow the
management group to access the contents of this directory:
Next, we have the mask block. Masks can be challenging, and we will cover them later in detail. For now, keep in mind that masks limit access rights, and the comments like
#effective:r-x display the actual permissions.
Next up is the
other block. It works like the previous blocks and specifies the permissions for everyone else:
Lastly, we have the
default block. This block exists only on directories and includes all other blocks mentioned before. Here we can specify what permission should apply to new files within a directory.
default:user::rwx default:user:finley:rwx #effective:r-x default:group::r-x default:mask::r-x default:other::---
ACLs with only the three base entries
other:: are called minimal ACLs. ACLs containing named entries are called extended ACLs.
Masks and effective rights explained
After looking at the output, let’s address probably the most confusing aspect about Access Control Lists: Masks and effective rights.
Standard permissions can’t reflect complex ACLs. Therefore the working group agreed on a complex masking mechanism to preserve maximum compatibility between basic permissions and ACLs.
To better understand masks, let’s start with five simple statements that always will be true:
- If the ACL has no mask entry, the permissions of the owner group will correspond to the ACL group.
- If the ACL has named users or groups, it will have a mask entry.
- If the ACL has a mask entry, the permissions of the owner group will correspond to the mask entry.
- Unless otherwise stated, the mask entry’s permissions will be the union of all permissions affected by an ACL and recalculate on every change.
- Masks denote maximum access rights that can be granted by a named user entry, named group entry, or the
The first statement is pretty self-explanatory. As long as there is no mask, the permissions of the owner group and the
group:: entry will be the same. Changes to the owner group will be reflected in the
group:: entry and the other way around.
The next one states that as soon as you add named user or group entries,
setfacl will automatically add a mask entry if it does not exist.
The third statement is where it gets interesting. If a mask exists, the meaning of the owner group will change. The owner group will equal the mask entry. Changes with
chmod to the owner group will change the mask entry. Changes via
setfacl to the mask entry will change the owner group’s permissions.
But how can we manage the permissions of the owner group without changing the mask? Don’t worry. You can change permissions for the owner group via the
Thanks to the fourth statement, we know that the mask’s permissions can change and always equal the union of named users, named groups, and the
To prevent the mask from recalculating on change, use
The last statement lets us know, and this is important, that you can’t grant more permissions than specified in the mask for named users, named groups, and
group:: entries. This restriction is what causes the so-called effective rights.
For example, if we add the following ACL and mask:
finley only has the rights
w is not allowed by the mask.
Like every other entry, we can change the mask explicitly:
setfacl -m m:rw
Unless you use
-n to prevent the mask from recalculating, all following changes will overwrite your mask again.
Precedence of ACLs
One last thing to understand is the following order in which the algorithm checks for permission:
- File owner.
- Named user entries.
- Owner group (or
- Named group entries
The first match determines the access to the resource. The order is essential, as it will deny writing access if a named user entry with
r exists even when the user is a member of matching group entry with correct permissions:
[root@lab docroot]# getfacl exampledir # file: exampledir # owner: cassidy # group: developer user::rwx user:finley:r-x group::rwx mask::rwx other::r-x [finley@lab docroot]$ groups finley developer [finley@lab docroot]$ touch exampledir/testfile touch: cannot touch 'exampledir/testfile': Permission denied
Working with ACL entries
At this point, we should have a good understanding of how Access Control Lists work. Finally, let’s modify ACLs. Fortunately, this is pretty straightforward. To set or remove ACLS, use the
setfacl command. The syntax is always:
setfacl [option] [action/specification] file
A colon separates the specification into three sections: object type, associated object, and permissions. Here is a list of all object types:
The following example indicates that we want to modify the permissions for the user
finley. It is possible to use UIDs and specify permissions as octal numbers or characters:
You can modify multiple entries simultaneously by separating specifications with a comma:
If you use
setfacl on a file system that does not support ACLs,
setfacl tries to reflect the desired permissions via the standard permissions and output an error. Be aware that this could lead to unexpected results.
Here are some common options for
setfacl, but I will explain them in detail in the following sections.
If you are unsure if your ACL results in the expected outcome, you can use the
--test option to display the new ACL entries without changing the current ones.
||Modify or add an ACL entry (always needs to be the last option).|
||Sets ACL entry as default (Only works on directories).|
||Recursively applies changes.|
||Removes specified entry.|
||Removes all default entries.|
||Removes all entries.|
||Prevents the mask from being recalculated.|
How to create/modify ACL entries
To create or modify ACLs, use the modify option
-m and follow it with your specification explained above. If the same object exists, the new entry will overwrite existing permissions. For example, to add or change the permissions for the user
rwx, execute the following:
setfacl -m u:finely:rwx exampledir
It is crucial that after the option
-m, the specification follows immediately. So if you want to change the permissions recursively, you have to write
-mR will result in an error!
If you want to apply read-only permissions for files and directories recursively, you can use
rX. A capital
X only applies execution rights to directories. So all files would get
r permissions, and all directories would become
Creating default permissions for new files
If you want newly created files to get specific permissions automatically, you can specify default permissions on the parent directory:
setfacl -dm u:finely:rwx exampledir
This only works for directories (
-Rdm ignores files). All new files and directories in
exampledir will inherit these permissions (new directories will also inherit the default entries). Unfortunately, this applies only to newly created files, not copied ones.
Removing ACL entries
To remove single entries, use the
-x option instead of
setfacl -x g:accounting exampledir
Like with the
-m option, you can use the
-d switch to remove single default entries:
To remove all default entries, use the
setfacl -k exampledir
If you want to remove all ACL entries, you can nuke them with the
-b option, but be careful when to use it!
setfacl -b exampledir
Furthermore, be aware that unless you use the
-n switch, the mask will recalculate when removing entries. So check for possible breaking changes!
You have now learned how Linux Access Control Lists work and how to use them. I hope it helps to solve complex permission structures more confidently.
If you want to read more about ACLs, I recommend the article from Andreas Grünbacher, one of the draft’s authors for POSIX ACLs. Not to mention the man pages for
- POSIX Access Control Lists on Linux by Andreas Grünbacher
- acl - Linux man page
- getfacl - Linux man page
- setfacl - Linux man page
If you found any mistakes or want to say hi, send me a message.