Access Control Lists (ACLs)

The Access Control List (ACL) is an advanced permissions scheme that gives you tighter control over who can and cannot access files and directories. Instead of just allowing or denying access based on the owner, group, and everyone else, you can now grant access to individual specified users and groups. You can also set a maximum permission mask for the users and groups that are granted access through an ACL that will override the actual permissions given by the ACL.

ACLs are usually not necessary for desktop workstation users, and they're also seldom used in typical Internet server applications. However, in cases where complex group ownership is necessary, such as in a research environment where different lab groups must be able to contribute to a common pool of data, ACLs can provide the necessary level of granularity in permissions in a way that's simply not possible with traditional UNIX permissions.

For an ACL to work, the kernel must be properly configured with support for UFS extended attributes. If you are using a FreeBSD installation that was newly created using FreeBSD 5.0 or later, your kernel is up-to-date and you don't need to make any modifications to the kernel or create any support files for UFS extended attributes; skip ahead to "Enabling ACLs on Your Mounted Filesystems." However, if you're using an old version of FreeBSD or one whose filesystems were created prior to FreeBSD 5.0, you should read the next two sections to see how to add the necessary kernel and filesystem support for ACLs.

Configuring the Kernel to Support ACLs

There are two versions of the UFS (FFS) filesystem: UFS1 and UFS2. UFS2, which was made the default format for newly created filesystems in FreeBSD 5.0, contains built-in support for UFS extended attributes, which are necessary for ACLs to work. UFS1, however, requires that the kernel be modified to support the extended attributes. If your installation of FreeBSD was created prior to FreeBSD 5.0, you need to add the appropriate options and rebuild the kernel.

To see whether your kernel has UFS Extensions enabled, look for the following lines in your kernel configuration file. Unless you have already built a custom kernel, your kernel configuration file will be /usr/src/sys/i386/conf/GENERIC on an Intel x86-based system (adjust the i386 portion accordingly, otherwise). The following lines should be present in order for the ACL feature to work:

options      UFS_EXTATTR options      UFS_EXTTR_AUTOSTART options      UFS_ACL

If these options are already present in your kernel configuration file, you don't need to do anything. If they are not present, you will need to add these options and then build a new kernel. See Chapter 18, "Kernel Configuration," for full details on how to configure, build, and install a new kernel.

Tip

Further documentation on the kernel modifications necessary for ACLs can be found in the source tree, in the README.* files in /sys/ufs/ufs.

After you have installed the new kernel and rebooted, you will need to configure the filesystems you want to use the ACL with.

Configuring UFS1 Filesystems to Use ACLs

On UFS1 filesystems (those created using FreeBSD versions prior to 5.0), you need to use the extattrctl command to set up the support files for the extended attributes necessary for ACLs. You must set up these support files on each filesystem where you want to use an ACL. For example, to enable an ACL on the filesystem mounted as /usr, follow this procedure:

1.	As the root user, create the directories /usr/.attribute and /usr/.attribute/system (using the -p option to create them both at once): # mkdir -p /usr/.attribute/system
2.	Change to the newly created /usr/.attribute/system directory (cd /usr/.attribute/system) and then run the extattrctl command to initialize the ACL attributes on the filesystem: # extattrctl initattr -p /usr 388 posix1e.acl_access On large filesystems, this command can take several minutes to complete, so be patient as the command generates the backing files needed to support the ACL feature.
3.	When the first command has finished executing, run the extattrctl command one more time with another filename as the argument: # extattrctl initattr -p /usr 388 posix1e.acl_default Once again, on a large filesystem, this command can take several minutes to complete, so be patient.
4.	Reboot the system or remount the filesystems in question for the changes to take effect. After you have done so, the ACLs for the filesystem will be enabled.

Caution

The files created by the commands in the ACL-enabling process can be extremely large, possibly taking up several gigabytes of disk space on large filesystems. Make sure you have plenty of free disk space before running the commands.

Enabling ACLs on Your Mounted Filesystems

Whether you have modern UFS2 filesystems that natively support ACLs or older UFS1 filesystems that you had to configure manually in the preceding sections, the final step in preparing your system to use ACLs is to tell the mount program to use them when mounting the disk partitions at boot time. To do this, edit the /etc/fstab file and add the flag acls to the options on each filesystem you want to use ACLs with:

/dev/ad0s1f   /usr   ufs    rw,acls   2    2

Reboot the system to enable these changes. You can also use the acls flag when mounting a filesystem manually:

# mount -o acls /dev/ad0s1f /usr

Getting Information About Current ACL Settings

Use the getfacl command to obtain information about existing ACL settings on files or directories. For example, on a newly created file named acltest.txt with no ACL set and with default 644 permissions, issuing getfacl acltest.txt will return the following:

#file:acltest.txt #owner:0 #group:0 user::rw- group::r-- other::---

The first line simply shows the name of the file. The next two lines show the UID and GID, respectively, of the owner and group the file belongs to (in this case, the file is owned by root and wheel). The final three lines show the current permissions on the file. Notice that "other" does not have any permissions on this file.

Setting the Maximum Permissions Mask

The maximum permissions mask controls the maximum permissions that will be given to any user or group added to the ACL list. Note that the mask applies only to users and groups that are given access to the file or directory with an ACL entry; the mask doesn't affect the owner's permissions. It also does not affect the permissions that the default group has, nor does it affect the permissions of the rest of the users on the system. For anyone not listed in an ACL entry, the standard file access permissions apply.

The setfacl command is used to add, modify, or delete entries from the ACL list. The syntax is:

# setfacl action permissions filename

where action is a flag specifying the action that should be performed (adding an entry, modifying an entry, deleting an entry, and so on), permissions is the string representing the ACL permissions that should be set, and filename is, of course, the name of the file or directory that the ACL should be applied to. The following example adds an ACL maximum permissions mask of "read" to the file acltest.txt:

# setfacl -m m::r acltest.txt # getfacl acltest.txt #file:acltest.txt #owner:0 #group:0 user::rw- group::r-- mask::r-- other::---

In the setfacl command, the -m option means that you want to add or modify the ACL entry. The m:: specifies that you want to set a mask, and the r simply means "read." If you want to also set the mask to allow write permissions, you would use m::rw. The last argument is, of course, the name of the file you want this operation to be performed on.

After you have set the mask, getfacl displays the same information it displayed the first time, but this time it shows that there is a mask set.

Adding a User or Group to an ACL

The strength of an ACL is that it allows you to specify more than one rule for a given permission context. For example, even though standard permissions on acltest.txt might state that only the owner (root) gets read access and all other users have no access, an ACL can specify explicit privileges for users or groups other than the owner, as you will see here.

To add a user or group to an ACL, you once again use the setfacl command. For example, to give the user frank read access to the file acltest.txt, you can use the following command:

# setfacl -m u:frank:r acltest.txt # getfacl acltest.txt #file:acltest.txt #owner:0 #group:0 user::rw- user:frank:r-- group::r-- mask::r-- other::---

As you can see, an entry has been added to the ACL for the user frank (users specified by name in ACLs are listed in the field between the first pair of colons). This user will now have read access to the file, even though the standard file permissions would not normally give it to him.

So, what happens if you try to give the user write permissions as well as read permissions? The following command would give frank both read and write permissions on the file:

# setfacl -m u:foobar:rw acltest.txt # getfacl acltest.txt #file:acltest.txt #owner:0 #group:0 user::rw- user:frank:rw- group::r-- mask::rw- other::---

The getfacl output shows that frank was indeed given write permissions to the file. Notice also that the mask has been updated automatically to give a maximum permission of read and write. If this behavior is undesirable (in other words, you do not want the mask to be updated), use the -n option when setting the ACL. For example, the following command sets an ACL that gives the user frank read and write access to the file:

# setfacl -n -m u:foobar:rw acltest.txt

This command won't update the mask, however, even if the current mask does not allow write access. See man setfacl for a discussion of what exactly this means about how the permissions will be applied under varying circumstances.

Tip

The order of the options is important. The -n option must come before the action option (in this case, -m). If you reverse the order of the two options, you will get the following error:

setfacl: acl_from_text() failed: Invalid argument.

Caution

Remember that if you set a new ACL without using the -n option, the maximum permissions mask will automatically be updated to allow the permissions. For example, if the mask is currently set to allow maximum permissions of read-only, and you add an ACL for a user that allows read and write, the mask is updated automatically to allow both read and write privileges. Always remember to use the -n option if you do not want this to happen.

Tip

When the -n option is not used and the mask is automatically updated, it will increase the permissions if a new ACL is added that has greater permissions than the mask currently allows. The mask will also automatically be lowered to the maximum permissions needed to support all the entries in the ACL. For example, if you delete an ACL entry that allows read and write access to a certain user, and after you delete this entry there are no other entries left that require write access, write access will automatically be removed from the mask. Just as you can use the n option to prevent the automatic raising of the mask, you can use the option to prevent the automatic lowering of the mask.

After giving frank read and write access to the file, your ACL should now look like this:

#file:acltest.txt #owner:0 #group:0 user::rw- user:frank:rw- group::r-- mask::rw- other::---

If you want to change your mask back so that it allows maximum ACL permissions of read-only, use the following command:

# setfacl -m m::r acltest.txt

If you then run the getfacl command again, you get the following output:

#file:acltest.txt #owner:0 #group:0 user::rw- user:frank:rw-                # effective: r-- group::r-- mask::r-- other::---

Notice that the user frank still has read and write permissions listed. However, because of the mask, frank's effective permissions are read-only.

You can also add several ACLs with a single command line by separating them with commas. Here's an example:

# setfacl -n -m u:frank:rw,u:guest:r,g:visitors:r acltest.txt

This command gives read and write access to the user frank, read access to the user guest, and read access to the group visitors. In addition, the use of the -n option prevents the mask from being updated, even if the current mask doesn't allow some of the permissions you assign in this statement.

Denying Access with ACLs

Just as an ACL can be used to allow users and groups to have access to a file or directory that they otherwise could not access, it can also be used to deny access to users and groups that otherwise would have access. For example, the following command creates an ACL entry for the user frank that contains no permissions:

# setfacl -m u:frank: acltest.txt

In this case, the user frank is denied all access to the file acltest.txt, even if frank is a member of the group that owns the file and that group has access to the file. The ACL overrules the standard file permissions and denies the user access, even if the standard file permissions would allow him access.

It's important to realize, however, that denying access on an individual user basis is far less secure than simply denying access by default and then enabling access for trusted users. It's always possible, after all, that a user you're trying to block might be able to access the system through another account that isn't blocked by the ACL.

Deleting ACL Entries

Use the -x option with setfacl to delete an ACL entry. For example, the following command removes the entire entry for the user frank:

# setfacl -x u:frank: acltest.txt

Use the -b option to remove all the ACL entries on the file. Here's an example:

# setfacl -b acltest.txt

For more information on the capabilities of ACLs, including the capability to set default ACLs for directories, see the man pages for getfacl and setfacl.