POSIX Access Control Lists

Access Control Lists (ACLs) are a way of modifying file permissions in a way that is far more granular and flexible than standard Unix file permissions. Unfortunately, ACLs are also more complex and can lead to very confusing situations if you're not careful. Consequently, we don't recommend using ACLs unless you find yourself in a situation that cannot work with the standard permission model. (When in doubt, you can always email support@cs.jhu.edu for help with our systems.)

There are two types of ACLs in use on our systems. This page covers POSIX ACLs, which are used on our undergrad Linux clients. For our graduate Linux clients, please see the page on NFSv4 Access Control Lists.

Our filesystems also support POSIX Access Control Lists (ACLs). We don't recommend using them unless you have a specific reason to do so, because they can easily add a confusing amount of complexity to your file permissions. Still, we're mentioning them, if briefly, for completeness.

ACL Overview

The standard Unix permissions allow you to specify permissions for exactly one account (which is almost always your account), exactly one group, and "everyone else". Sometimes you might want more flexibility than that. You might, for example, want members of one group to be able to change a file, members of another group to be able to read it, and no access for everyone else. The standard Unix file permissions can't do that.

Enter ACLs.

ACLs are things you attach to files and directories that basically just list additional accounts and groups with permissions specific to each account and group. You look at ACLs with the getfacl command and set them with the setfacl command. If a file or directory has ACLs, it will show a "+" symbol at the end of the ls -l permission listing, like the README file here:

-rw-r-----+ 1 account users 4153 Apr 16  2013 README

ACLs (unlike standard Unix permissions) have only one format, which is used for both setting and displaying them:

permission-set:account-or-group:permissions

"permission-set" is one of "user", "group", and "other". (When setting ACLs, you can abbreviate those to "u", "g", and "o".) "account-or-group" is the account name for "user" ACLs and the group name for "group" ACLs. If you leave the "account-or-group" section empty, you'll affect the equivalent standard Unix permission set. (So setfacl -m group::rw file is the same as chmod g=rw file.) "permissions" is some combination of "r", "w", and "x", for read, write, and execute permissions, or a "-" to signify no permissions. ACLs don't have the extra properties for set UID, set GID, and sticky bit.

Viewing ACLs

The output of getfacl will look something like this:

# file: README
# owner: account
# group: users
user::rw-
user:bob:r--
group::---
mask::r--
other::---

That shows that the "bob" account has read access to the file, even though no one (aside from the owner) has any permissions for it. (We'll cover the "mask" line shortly.)

Setting and Changing ACLs

To add an ACL to a file (or to change the permissions on an existing ACL), use setfacl -m :

setfacl -m u:bob:rw file

To remove an ACL, use setfacl -x, without the permission section of the ACL:

setfacl -x u:bob file

ACL Masks

One nonintuitive thing that comes up with ACLs is the ACL mask. As soon as you add an ACL to a file, you will see a "mask" line show up in the getfacl output in addition to the ACL you added. The works a little like the symbolic representation of a umask: it gives the maximum permissions allowed to any account or group with its own ACL. It is also what's shown in the "group" section of the output of ls -l.

To repeat that for emphasis: Once you add an ACL to an object, ls -l will show the ACL mask in its middle set of permissions, not the permissions corresponding to the group that owns the object. The README example above shows this: the users group has no permissions for the file even though ls -l shows "-rw-r-----+".

Normally, setfacl will set the mask appropriately for the ACLs on the file. In some circumstances, especially if you use chmod on a file with ACLs, the mask may get out of sync with the other ACLs, in which case getfacl will show things like this:

user:bob:rw-                    #effective:r--
mask::r--

That means, roughly, "bob has an ACL that should give him read and write permissions, but because of the mask, he'll really only have read permissions."

To reset the mask, you can run:

setfacl --mask -m m::- file

Default ACLs

Finally, directories can have "default ACLs". They have the same format as regular ACLs, but with "default:" at the beginning. (You can shorten that to "d:" if you want.) When a file is created in a directory with default ACLs, it automatically gets ACLs based on the defaults. When a directory is created in a directory with default ACLs, it gets ACLs based on the defaults (just like a file) and also gets its own copies of the default ACLs. Here's an example:

$ mkdir example
$ setfacl -m default:user:bob:rw example
$ touch example/foo
$ getfacl -c example/foo
user::rw-
user:bob:rw-
group::---
mask::rw-
other::---

Summary

In summary, ACLs are useful, but can be potentially confusing (especially if you set them and then forget about them later). We don't really recommend using them unless you absolutely need to do so.