Sharing AFS Directories Using Access Control Lists

In the example session above, you were able to copy a foreign file to your local AFS filespace in the ualberta.ca cell because the owner of the foreign directories has permitted such access to all AFS users. This permission was set up with an AFS Access Control List (ACL), an easy-to-use tool that makes it possible to share directories, files, and programs among AFS users.

The biggest obvious difference between ACLs and traditional UNIX file permissions is that an ACL is used to apply permissions to an entire directory in an AFS volume; it cannot be used to apply permissions to individual files within a directory a la the UNIX chmod command. Related to this, the ACL of a parent AFS directory is also automatically inherited by any new child subdirectories created in or moved into the parent directory. The only way to change the ACL of the child subdirectory is to separately apply a different ACL to it.

ACLs are created, modified, and examined with the AFS fileserver command (fs) followed by various subcommands and ACL arguments. For example, to examine the default ACL applied to your GPU Logon Server home directory, enter the following at the GPU prompt:

gpu{jdoe}: fs listacl ~jdoe

The information returned by this command indicates that only the system administrator and yourself have access rights to your home directory. This is the default for all the AFS directories in the ualberta. ca cell.

To examine the ACLs of the files within a directory, cd to the directory and enter the following at the UNIX system prompt:

gpu{jdoe}: fs listacl *

Access Control Rights
Before exploring in more detail the commands for creating and modifying ACLs, it's important to understand that there are seven types of ACL permissions, called access control rights, which can be applied to an AFS directory. These rights, shown below, can be given to other AFS users by the owner of the AFS directory in question. In AFS terms, the user who has the rights is called the possessor.
r (read)
This right allows the possessor to both list and read the files in the directory
l (lookup)
This right allows the possessor to list the files in the directory using the ls and associated UNIX commands
i (insert)
This right allows the possessor to add/copy/move new files and subdirectories to the directory
d (delete)
This right allows the possessor to remove files and subdirectories
w (write)
This right allows the possessor to modify the files in the directory and to change the UNIX protection bits of individual files using chmod
k (lock)
This right allows the possessor to run programs in the directory that require file-locking
a (administer)
This right allows the possessor to change the ACL of the directory
As a convenient option, the separate access control rights shown above can also be grouped together to form four different packages of access control rights. These four packages are:
write
This rights package gives the possessor read, lookup, insert, delete, write, and lock rights (i.e., rlidwk)
read
This rights package gives the possessor read and lookup rights (i.e., rl) to an AFS directory
all
This package of rights gives the possessor read, lookup, insert, delete, write, lock, and administer rights (i.e., rlidwka)
none
This option removes from the possessor all previously granted access control rights to an AFS directory

Sharing with a Single User

Now that we've covered the different types of access control rights, let's try a few real-life scenarios of sharing AFS directories among different GPU Logon Server account holders. Remember that while these example sharing scenarios are using the AFS client program running on GPU, they are really taking place within the local AFS ualberta.ca cell which is independent of GPU and part of the global AFS megadirectory. A different AFS client program besides the one running on GPU could be used to share AFS directories in the very same way.

Let's assume that you are the GPU user jdoe who wants to share the contents of a directory in your AFS volume with a colleague who has the GPU ID co-worker. The first thing to do is to create, in your home directory, the new directory you want to share:

gpu{jdoe}: mkdir shared.stuff

Put the files/programs you want to share in the new shared.stuff directory. Now, cd to your home directory and then examine the ACL of shared.stuff:

gpu{jdoe}: fs listacl shared.stuff

The command above returns the following ACL information: 

Access list for /afs/ualberta.ca/j/d/jdoe/shared.stuff is
Normal rights:    
system:administrators rlidwka    
jdoe rlidwka
The returned information is the default ACL for directories in the ualberta.ca cell; it signifies that only the system administrator and yourself currently have full access to the shared.stuff directory. A new ACL must be applied to the directory so that the GPU ID co-worker can share its contents. To do this, cd to the directory that contains the shared.stuff directory (i.e., the directory above shared.stuff) and issue one of the following commands at the GPU UNIX system prompt. Both of these commands give all the ACL access control rights to co-worker except the administer right, i.e., the right to change the directory's ACL:

gpu{jdoe}: fs setacl shared.stuff co-worker rlidwk

... or ...

gpu{jdoe}: fs setacl shared.stuff co-worker write

If you don't want to give co-worker the ability to add, change, or delete files in shared.stuff, but only the ability to list and read/copy the files, modify the ACL for the directory with one of the following commands:

gpu{jdoe}: fs setacl shared.stuff co-worker rl

... or ...

gpu{jdoe}: fs setacl shared.stuff co-worker read

Check to see that the ACL rights for the shared.stuff directory have been changed to what you want by issuing the fs listacl command once more.

Now that you have applied a new ACL to the shared.stuff directory, co-worker is free to share the contents of the directory according to the access control rights stipulated in the fs setacl command. For example, the write package of rights gives the GPU ID co-worker the power to remove a file called old.txt from your shared.stuff directory with the following command:

gpu{co-worker}: rm ~jdoe/shared.stuff/old.txt

The owner of the co-worker ID could also copy a file called new.txt from his/her home directory to your shared.stuff directory with the command:

gpu{co-worker}: cp new.txt ~jdoe/shared.stuff/new.txt

Note that the last part of the command above is the filename given to the copied file by co-worker.

In like manner, the owner of the co-worker ID could open and edit a file called agenda.txt in shared.stuff using a file editor such as Pico:

gpu{co-worker}: pico ~jdoe/shared.stuff/agenda.txt

Sharing with a Group of Users

The kinds of sharing that are possible between individual AFS users are also applicable to defined groups of AFS users. There are two general types of AFS groups that can be used to collectively share the contents of AFS directories -- predefined system-wide protection groups, and user-defined protection groups.
System-Wide Groups
The three default system-wide AFS protection groups are:

- system:administrators

(This group is comprised of University system administrators who have all access control rights to all directories in the ualberta.ca cell)

- system:authuser

(This group is made of all Kerberos-authenticated users in the local ualberta.ca cell)

- system:anyuser

(This group is comprised of all users, including non-AFS users,whether they are authenticated or not)

Typically, you would use a default system-wide protection group like system:anyuser to share a directory with the whole world, such as your public_html directory on GPU where you can store and share your World Wide Web home page and other HyperText Markup Language (HTML) documents. To do this, first apply the following fs setacl command to your home directory:

gpu{jdoe}: fs setacl ~jdoe system:anyuser l

This command gives all users lookup (l) access to your home directory (they can list the directory's contents, but not read or copy). This is required so that Web client programs can navigate through your home directory to your public_html directory.

Now, apply one of the following commands to your public_html directory:

gpu{jdoe}: fs setacl public_html system:anyuser rl

... or ...

gpu{jdoe}: fs setacl public_html system:anyuser read

Both of the previous commands give all users read and lookup access to your public_html directory, the required setup for sharing Web documents.

User-Defined Groups
User-defined AFS protection groups are very useful as they allow you to be very selective in your sharing. As an example, let's assume that you are the GPU user jdoe who wants to share the contents of the directory collaboration with a group of three colleagues on GPU -- co-worker1, co-worker2, and co-worker3. This involves four steps:
  1. Creating the new collaboration directory in your home directory and putting the files/programs in the new directory that you want to share.
  2. Creating an AFS group with the AFS protection server (pts) creategroup command.
  3. Defining members of the group with the AFS protection server (pts) adduser command.
  4. Applying the correct ACL to the directory with the fs setacl command.
First, create the new directory, in your home directory, that you want to share:

gpu{jdoe}: mkdir collaboration

Put the files/programs you want to share in the collaboration directory. Now, create an AFS group, e.g., group1, by issuing a command in the following form:

gpu{jdoe}: pts creategroup jdoe:group1

Define the members of group1 with a command in the following form:

gpu{jdoe}: pts adduser co-worker1 jdoe:group1

You can add members to the AFS group individually, as shown above, or you can simultaneously add multiple members to the AFS group with a command in the following form:

gpu{jdoe}: pts adduser -user co-worker1 co-worker2 co-worker3 -group jdoe:group1

Once you have added users to the AFS group, check to see that the membership is correct with the following command:

gpu{jdoe}: pts membership jdoe:group1

Now you are ready to apply an ACL to the collaboration directory which will give group1 the bundle of access control rights of your choosing. First, cd to the directory which contains the collaboration directory, then enter:

gpu{jdoe}: fs setacl collaboration jdoe:group1 rlidwk

Files and programs within the collaboration directory can now be shared by the members of group1.

In future, if you want to remove a member from group1, enter a command in the following form:

gpu{jdoe}: pts removeuser co-worker2 jdoe:group1

If you ever want to rename group1, enter a command in the following form:

gpu{jdoe}: pts rename jdoe:group1 jdoe:new-group-name

If, at some point, you want to delete the AFS group entirely, issue a command in the form:

gpu{jdoe}: pts delete jdoe:group1
 
 

This document is taken from the CNS, please refer to the original copy to make sure.
Edward Wong ecw@ualberta.ca
Edgar Wong edgar@ualberta.ca
Howard Shum kshum@ualberta.ca
Patrick Li pwli@ualberta.ca