We all know how basic Unix permissions work. They only control permissions specifically for a single user, a single group, and everyone else. Although this is sufficient for most purposes, it is not very specific. Access control lists (ACLs) allow the specification of a complete permissions set for any number of individual users and groups. If implemented on your system, ACLs can provide an easy, safe, and effective mechanism for granting data access on an individual user basis.

The availability of access control lists depends on two things:

• whether they are implemented on the filesystem in question (they are available on ext2/ext3/ext4 on linux)
• if the filesystem has been mounted with ACLs enabled. This may require using the acl option during the mount (this will be discussed later under filesystems). Currently, ACLs are on by default on our filesystems.
  

Creation and examination of access control lists uses the utilities setfacl(1) and getfacl(1) on linux. Unfortunately, the POSIX ACL standard was withdrawn, although many Unix systems (as well as linux) implement it, so the utilities that manage ACLs may have slightly different names. For example, OSX uses options on chmod and ls, rather than having separate tools. The syntax will differ but, assuming the draft standard was followed carefully, the implementation should be similar.

On linux, you can tell that a file (or directory) has an ACL by examining its permissions using ls -l. If an ACL is present, the permissions block of the ls -l output will have a plus sign appended. (See below)

ACLs and ls -l permissions

Before we discuss ACLs, we must discuss how they interact with the basic permissions. 

First, the easy part. There is only one owner. The owner's permissions are shown in the user permissions of the ls -l output. This is true whether you modify the owner's permissions using chmod or by the set access control list utility setfacl. If a file has an ACL, the only permissions you can rely on in the output of ls -l are the permissions for the owner.

Next, the permissions for other shown by the output of ls -l. These permissions still apply to any user who is neither the owner, nor has a user access control list nor is in the file's group nor in a group that has a group access control list (whew!). Stated differently, the meaning of 'other' changes to exclude anyone specified in an access control list. Since you cannot know what users are affected by the file's ACL unless you examine the ACL, the permissions for other shown by ls -l have little meaning by themselves.

The group permissions show the maximum permissions provided by any access control list. Read on.

ACLs and ls -l group permissions

If you add an access control list for a second user (a user other than the owner) or a second group (a group other than the file's group), the output of the permissions in the ls -l listing may show a + appended to indicate an ACL exists, however, on if the file also has an extended attribute (which most files now have), the + will be changed to a period. In addition, the group permissions may change. Suppose we had a file with the following permissions:

$ ls -l hello
-rw-r----- 1 gboyd users 6 Jul  8 17:45 hello

Suppose we add an ACL to give rw permission to the user student using setfacl. Afterwards, the ls -l listing has changed:

$ ls -l hello
-rw-rw----+ 1 gboyd users 6 Jul  8 17:45 hello

The + indicates that ACLs are present (but remember, if a period appears, it may hide the +), but the alteration of the group permissions is an illusion: the permissions for the group users have not changed - they are still read-only. The group permissions appear as the union of the former group permissions and all the permissions granted by ACLs. You can see the actual group permissions by examining the ACLs:

In the output above, the true group permissions are shown by the group::r-- ACL, showing that the file's current group (users) has the permissions of read-only.

Although the group permissions shown in the ls -l output is an illusion, there is an actual relationship between ACLs and the group permissions. If you modify the group permissions using chmod after ACLs have been created you will modify the ACLs. In our example, if you reset the group permissions of hello to read-only after the ACLs are in place, the ACLs will be effectively masked with the new group permissions:

A seen, resetting the group permissions to read-only effectively disabled the w and x permission from every ACL. (This is shown by the mask::r-- output, as well as by the comment on student's ACL permissions that only the read permission is effective.) This can be undone by either adding the permission back using chmod (which then affects the permissions for both the user student and the group users) or adding a new ACL later.

In short, you should not modify the group permissions of any file that has access control lists. If you want to totally control permissions, the simplest and safest method is to delete all permissions for group and other, then add specific permissions using ACLs.

Note: on most linux systems, the group permissions are unused. This is because each user is placed in their own group, which is their default group. In this case there is never a reason to modify group permissions using chmod (as the only user in the group is the owner).

Specifying access rights for an object

ACLs are specified as a colon-delimited record of three fields. The first can be user or group to specify whether the ACL applies to a user or a group. This is followed by the username or groupname. Last is the permissions, in either rwx format or as a single octal digit. 

For example, the ACLs

user:jheinz:rw

user:ggrimhau:0

group:sys:5

give jheinz rw permissions, ggrimhau no permissions, and the group sys r-x permissions. (You cannot specify a dash in the permissions section of an ACL, thus a perm of 5 is written in text as rx.) For brevity, user can be specified as u and group can be specified as g. Thus, the following ACLs are equivalent

user:gboyd:rw

u:gboyd:6

user:gboyd:6

An access control list that denies any permissions for a user or group should use the octal number 0 to specify permissions.

Modifying (adding) an access control list

You add and modify an access list by using setfacl with the -m option

setfacl -m ACL[,ACL,ACL...] objects

In the first example of ACLs above, all of the ACLs could be set for the file logfile using 

setfacl -m u:jheinz:rw,u:ggrimhau:0,g:sys:5 logfile

Deleting an access control list

Similarly, an access list can be deleted by using the -x option to setfacl and specifying the access list. It is not necessary to specify the permissions in the access list to delete it.

setfacl -x ACL[,ACL,ACL...] objects

Examining an access control list

You can examine the access control list of objects using getfacl. If the ACL of the file 

$ ls -l hello
-rw-r--r-- 1 gboyd gboyd 6 Jul  9 18:44 hello

is set using 

$ setfacl -m u:sue01:6,u:jose42:x hello

Here is the result

Note that the group permissions appear to have been modified by setfacl:

$ ls -l hello
-rw-rwxr--+ 1 gboyd gboyd 6 Jul  9 18:44 hello

The group permissions, in fact, are unchanged. The actual permissions for each of user, group and other appear in the output of getfacl as ACLs with no user indicated. If you examine the output above, you see that the permissions of group are read-only:

group::r--

$ chmod g=r hello
$ ls -l hello
-rw-r--r--+ 1 gboyd gboyd 6 Jul  9 18:44 hello

But in fact it has masked the ACLs for jose42 and sue01, as shown by the effective notation:

$ getfacl hello
# file: hello
# owner: gboyd
# group: gboyd
user::rw-
user:jose42:--x                 #effective:---
user:sue01:rw-                  #effective:r--
group::r--
mask::r--
other::r--

When jose42 attempts to access hello, although the file appears to be readable by everyone according to the ls -l permissions, the effective ACL for him denies all permissions:

[jose42]$ ls -l hello
-rw-r--r--+ 1 gboyd gboyd 6 Jul  9 18:44 hello
[jose42]$ cat hello
cat: hello: Permission denied

default ACLs for directories

ACLs for directories work the same as ACLs for files. However, a special type of ACL can be added to a directory. These default ACLs define ACLs that will be applied to any object created in the directory, rather than to the directory itself. (Note: the discussion below applies to the creation of new data. If you are copying data and want to apply default ACLs, be sure to read the caveat!)

Suppose we want to allow jose42, in addition to the owner, to have read and write access to the directory work and to any file that is created in it. First, we create an ACL for jose42 in the directory work:

[gboyd]$ ls -ld work
drwxr-xr-x 2 gboyd gboyd 4096 Jul  9 19:38 work
[gboyd]$ setfacl -m u:jose42:rwx work
[gboyd]$ getfacl work
# file: work
# owner: gboyd
# group: gboyd
user::rwx
user:jose42:rwx
group::r-x
mask::rwx
other::r-x

This allows jose42 as well as gboyd (the owner) to create and delete files and directories in work. However, if gboyd creates a file in work, jose42 does not have access to it, as gboyd's default permissions apply:

If we want jose42 to have write access to the file hello we could add the ACL for him. Similarly, we could do this for other files as we create them. Alternately, we could add a default ACL for jose42 in the directory work. A default ACL can only be created in a directory. It looks like a regular ACL, but has the prefix default: added. The default ACL does not apply to the directory - it is only for purposes of inheritance. Any object created in a directory with a default ACL will have a copy of that ACL created for it: files will have a matching file ACL. Directories will have a matching file ACL and a matching default ACL. 

[gboyd]$ setfacl -m default:u:jose42:rwx work
[gboyd]$ getfacl work
# file: work
# owner: gboyd
# group: gboyd
user::rwx
user:jose42:rwx
group::r-x
mask::rwx
other::r-x
default:user::rwx
default:user:jose42:rwx
default:group::r-x
default:mask::rwx
default:other::r-x

Then, whenever an object is created in work, it will inherit that ACL, automatically propigating permissions for jose42. So that you can see that only the default ACL affects the propigation of ACLs, we will first remove the ACL for jose42 in work, leaving only the default ACL. (Note: you would not normally do this - this will remove the ability of jose42 to create objects in work, but give him the ability to create objects in subdirectories of work.)

Now let's see what happens when we create a subdirectory in work:

As you can see, the subdirectory now has a matching ACL for jose42 as well as a matching default ACL. Let's see what happens when we create a file in work:

Note that an ACL for jose42 was created, but the x permission is now ineffective. This is because the default permissions for files (666) still apply and are the default to which the ACL is applied. The ACL, like umask, can only delete permissions from this default, not add them. Thus, it is not possible to create a default ACL that will add the x permission for files created in its directory, just like it is not possible to create a umask value that will allow the x permission for files created with it. (At least I couldn't do it - if anyone else can, let me know.)

Of course, if your purpose was to share access rights between gboyd and jose42 in and beneath the directory work, you should add a default ACL for gboyd as well so that any objects created by jose42 are writable by gboyd.

(Again, make sure you read the caveats about copying data into directories that have default ACLs.)

Options to setfacl

Besides the -m and -x options, the following options are especially useful for setfacl:

-b - remove all ACLs for the object

-R - recursive. Apply ACL modifications recursively.

Very Important Caveats

Besides the annoying interaction between changing group permissions using chmod and ACLs, there are several issues you should be aware of when using ACLs.

• default ACLs cannot override default permissions! If you are copying data into a directory with a default ACL and the original data has limited group permissions, those permissions will mask the permissions applied using the default ACL. Ensure that group permissions of any data you are copying have all permissions that you want the ACLs to grant. This applies when you are scp-ing data and the destination has a default ACL.If you want to cp or scp some data and ensure the ACLs are applied successfully at the destination, the group permissions of the data should be rw- or rwx.
• although the documentation indicates that you must use the -p option of cp(1) when copying files with ACLs to preserve them, the cp command seems to work fine without it. I would recommend using the -p option to avoid any modification of the permissions by umask during the copy. Note that using the -p option with cp prevents any new ACLs from being applied if the destination has a default ACL!
  
• the documentation also says that tar(1) does not support acls, but the current version of tar has an option --acls to write the ACLs to the archive. Once the ACLS are on the archive, they appear to be restored correctly.
• in order to make ACLs work on a filesystem, the filesystem must be mounted with the acl mount option. NFS filesystems do not yet understand ACLs, although there is current work on this issue. If you modify an NFS-mounted file's ACL you may get the incorrect output when you examine the ACL later. I'm not sure why this is - perhaps some sort of caching is going on - but if you update the file using touch the ACL will be displayed correctly. (Again, I believe the issue is the output you see, not whether the ACL is manipulated correctly)
• one reason to use an ACL is to allow a specific user to modify a system file or to examine a log file. Since system updates and log rotations may recreate these files, it is not clear how useful ACLs would be in this situation. Of course you could add a default ACL to the log directory, but this may give more permissions than you intended.
• ACLs dont work as you expect when you scp a file to another system. If the directory you are scp-ing into has a default ACL, it will add the ACL to the file, but since scp chmod's the file after it copies it (to set the permissions to match the original file + the local system's umask), the ACL may very well be masked. If you want to scp a file and ensure the ACLs are applied successfully on the receiving system, the group permissions of the data should be rw- or rwx.
  

setfacl(1), getfacl(1), acl(5),  http://acl.bestbits.at/

Creating a Collaborative Directory

There are some situations where you want a group of people to have access to a common directory and allow each of them to update it independently. With a combination of ACLs and SGID, this can be accomplished easily:

1. Create a group and place each of the collaborators in that group.
2. Create the collaborative directory, place it in that group and make it setgid. This means that each new item created in that directory will be in the group.
3. Add an access control list for that group with all permissions. This means that each member of the group will have all permissions to add, delete, rename items in the collaborative directory.
   
4. Add a default access control list for that group with all permissions. Now any new object created in that directory will have full permissions for the group.
   

NFSv4 ACLs (optional section)

NFS version 4 implements ACLs based on Windows NT. NFSv4 ACLs have more (and different) permissions than POSIX ACLs, but a POSIX ACL can be mapped to an NFSv4 ACL nearly perfectly. Thus, a linux system that stores data on NFSv4 can nearly perfectly translate between NFSv4 and POSIX ACLs to store data and retreive it again. I am not an expert in NFSv4 ACLs (perhaps because I had to use that W word when describing them) but there appears to be two issues, neither of which is serious:

• there must be a reliable way to map uids and gids (of the POSIX ACL) to the user and group names required by NFSv4 ACLs and back.
• if a user's access is governed by the groups they are in, and they request two types of access to a file, such as read and write, POSIX ACLs will deny that request if it uses permissions from two different ACLs, whereas NFSv4 would permit it. Thus if joe is a member of group1 and group2 and group1 has a read-only ACL and group2 has a write-only ACL, joe would only be able to read or write the file - he could not simultaneously open it for reading and writing, such as opening it in an editor.