Skip to content Skip to navigation

File Permissions (ACLs)

The most visible difference between AFS and a standard Unix filesystem is that AFS only allows you to set file permissions only on a per-directory basis. For every directory, something called an ACL (Access Control List) is set, and this ACL determines who has read and write access to all the files within that directory.

In standard Unix filesystems, you use chmod to set file permissions on a per-file basis, and different files within the same directory can have different access permissions. chmod limits you to setting file permissions at exactly three pre-defined levels: yourself, one particular standard Unix filesystem group, and everyone who has access to that machine. AFS ACLs are more flexible but less granular, providing you with the ability to give access to your directories to particular people individually, or to arbitrary groups whose membership you determine and control.

You'll still want to be aware of chmod, because you still use it to:

  • make files executable(useful when you're writing your own programs)

  • set file access permissions for files you'll be working with in non-AFS filesystems (e.g. /tmp)

ACL basics

Standard Unix filesystems only give you two read and write access level options: read and write -- but AFS ACLs give you seven read and write access level options:

l -- Lookup

Lookup is the most basic of all AFS file permissions. People who have Lookup privilege on a directory can obtain two things: (1) the ACL settings for that directory, and (2) a list of the contents of that directory.

The AFS filesystem uses Lookup privilege on behalf of users to determine which privileges a particular user has for that directory. This means that Lookup access is required for any of the other AFS file permissions to work as expected.

Another consequence of this is that, in order to give someone broader access to a subdirectory, that person must also be given Lookup access to all of that subdirectory's parent directories.

r -- Read

People who have Read privilege on a directory can read or execute files in that directory, or copy files from that directory to someplace else.

i -- Insert

People who have Insert privilege on a directory can create new files and subdirectories within that directory.

d -- Delete

People who have Delete privilege on a directory can delete files and empty subdirectories within that directory.

w -- Write

People who have Write privilege on a directory can modify the contents or attributes of any pre-existing file in the directory (e.g. they can use chmod to make a file executable).

k -- Lock

People who have Lock privilege on a directory can obtain an advisory lock on a file within that directory; having this lock helps ensure that no one else accidentally changes that file while one person is making modifications to it. This is the equivalent of flock(); it does NOT provide a mandatory lock.

a -- Administrative

People who have Administrative privilege can modify the ACL on that directory in any fashion -- they can add or delete privileges for specific users, or they can add or delete users or groups from the ACL.

Any new directories you create inherit the ACL from their parent directory.

An ACL can contain at most twenty entries (although this doesn't limit you to twenty people because one or more of your ACL entries may be groups).

Checking permissions

To obtain a list of the ACL entries for a particular directory in AFS (this command won't work for any directories on local disk), type this command at the system prompt:

fs listacl directoryname

Most AFS directories will show the following lines in their ACL listing:

system:backup rl
system:administrators rlidwka

system:backup read is required so that your files can be backed up nightly. If you remove this acl, that directory (and any sub-directories) won't be backed up.

system:administrators are the group of people who run AFS. You can remove it, but it can be added back at any time by those systems administrators. They use these privilieges to do file restores and other afs services. They take your privacy very seriously.

Changing permissions

To change the ACL on a particular directory, you use the following command at the system prompt:

fs setacl <directory> <sunetid or group> <privileges-list>

To change the ACL recursively for a particular directory and all of its subdirectories:

fsr setacl <directory> <sunetid or group> <privileges-list>

<privileges-list> will be some combination of the seven privileges outlined above. It may also be one of the following special keywords:

none

This is how you remove a user or group from an ACL.

read

Keyword for the combination "rl", which are the two privileges needed to make r (read) access work as expected.

write

Keyworkd for the combination "rlidwk" which are all the privileges needed to give someone full write access to a directory.

all

Keyword for the combination rlidwka. If you manage a group directory and need to give full access to the directory to somebody else (perhaps the person who will be taking over managing the group directory after you leave), this is how to give them the access privileges that they need.

There are two special "usernames" you can use to give access for a particular directory to a large number of people at once:

system:anyuser

This is the special "username" you use when you want to give the entire world privileges on a particular directory. This is the only way you can give people in other AFS cells (people outside of Stanford) access to your files.

system:authuser

This is the special "username" you use to give everyone in the Stanford AFS cell (ir.stanford.edu) privileges on a particular directory. Anyone with a valid token and a Stanford account will be able to access your files.

A directory ACL won't accept more than 20 entries (either users or groups), total.

Creating groups

When you need to put more than 20 users on an acl, or you've got a set of users that you need to assign to many of the same directories, you can create a group (called a pts group) to assign them to an acl together.

To work with groups, you use the following commands at the system prompt:

Creating a new Group
pts creategroup <your sunetid>:<name>
Listing the Members of a Group

groupname for the rest of the section is the entire "sunetid:name" name, e.g., jonpilat:friends

pts membership <groupname>
Adding a User to a Group You Own
pts adduser <sunetid> <groupname>
Removing a User from a Group You Own
pts removeuser <sunetid> <groupname>
Deleting an Entire Group
pts delete <groupname>

Note that adduser, removeuser, and delete will only work for groups you own, that is, groups where the prefix is your sunetid.

Symbolic links only

Because AFS only has ACLs for directories and does not have separate ACLs for individual files, you cannot create hard links between files in different directories in an AFS filesystem. This is disallowed because the interpretation of the permissions would be ambiguous: Which directory does the file really "live" in? Which directory's ACL should be used to control access? How does one know which directory the user has accessed the program from?

If you want to link to files in different directories, use symbolic links (ln -s).

Last modified February 15, 2010