AFS Overview

AFS, originally developed at Carnegie Mellon University under the name Andrew File System, is a distributed file system which allows users to share files throughout the network. It uses the client/server model where all files are stored on servers and accessed through a cache manager on the client machines.

AFS is organized into independent administrative groups called cells, and each cell is a directory under the /afs tree. AFS will be accessible on the Helix Systems using the existing cell alw.nih.gov which has been in use by the Advanced Laboratory Workstation (ALW) project since June 1991. AFS file pathnames begin /afs/alw.nih.gov/... and can be accessed from the local cell as well as from foreign cells. In the local cell /afs/nih/ is symbolically linked to /afs/alw.nih.gov.

Helix users who require more than the 100MB of disk space allocated to their home directories may use the ptr command to request storage space on AFS. The AFS space will be accessible from the pathname /afs/nih/helix/users/[a-z]/username. To make life simpler, you can create a symbolic link from your home directory to your AFS space. For example:

helix% ln -s /afs/nih/helix/users/[a-z]/username ~/afs

Then files can be referenced as ~/afs/filename/.

Login and Authentication

Helix passwords and AFS passwords are not necessarily the same. Users need to use both passwords to have access to the alw.nih.gov cell from the Helix Systems. AFS uses the Kerberos authentication mechanism to validate users. Therefore, in addition to logging in with your Helix password, you must use the klog command with your AFS password to obtain an AFS token. The token is then used to grant you access to your AFS files. At NIH, the token is valid for 100 hours.

The klog command obtains tokens.

helix% klog
Password: AFSpassword

The tokens command allows you to check on the status of your token or tokens. It lists the AFS tokens currently held and their expiration times.

helix% tokens
Tokens held by the Cache Manager:
Tokens for afs@alw.nih.gov [Expires Oct 24 20:44]
--End of list--

The unlog command allows you to give up your tokens, thereby, losing authentication and access to files.

To change your AFS password, you must use the kpasswd command, which works as follows:

helix% kpasswd
Changing password for `username' in cell `alw.nih.gov.'
Old password: oldAFSpassword
New password (RETURN to abort): newAFSpassword
Retype new password: newAFSpassword
Password changed.

Note that to change your helix password, you must continue to use the passwd command.

Access Control Lists

AFS allows users to protect their files with access control lists (ACLs). ACLs give certain access rights to specific users or groups of users. Each directory has its own ACL which grants rights to the directory and the files within it. By default, a subdirectory has the same ACL as its parent unless its ACL is changed by the owner. The accepted single-character abbreviations of the access rights appear in bold type.

The following four rights apply to the directory itself:

l - lookup The lookup right allows the holder to list the files in the directory with the ls command. It also allows the holder to list the access rights of that directory. However, it does not allow the holder to read the files in the directory.

d - delete The delete right allows the holder to remove files and subdirectories or move them to another directory where he possesses insert rights.

i - insert The insert right allows the holder to create new files and subdirectories.

a - administer The administer right allows the holder to change the ACL of the directory. It does not affect pre-existing subdirectories.

There are three rights which apply to the files within the directory. However, the holder must also possess the lookup right in order to use them.

r - read The read right allows the holder to read the files in the directory.

k - lock The lock right allows the holder to lock files within the directory.

w - write The write right allows the holder to modify files within the directory.

There are four shorthand notations that can be used when granting rights. They are the following:

read - (rl) Read and lookup rights.

write - (rldikw) All rights except administer.

all - (rldikwa) All seven rights.

none - No rights.

Unix mode bits in AFS

AFS is only interested in the owner permissions of the file. Once a user has gained access to a directory, the Unix owner permissions are consulted. These permissions control what can be done to that file by any user. For example, if the `r' permission is turned on and the user has read and lookup rights to that directory, then the user can read that file. Likewise, if the `r' permission is turned off and the user has read and lookup rights to that directory, the user is unable to read that file. The Unix group and other permissions are ignored.

AFS has three predefined groups that can be used when granting privileges:

system:administrators This group contains the system administrators of the AFS cell where the files are stored.

system: anyuser This group contains anyone who has access to AFS anywhere, irrespective of their AFS tokens.

system: authuser This group contains anyone who is an authenticated user in the AFS cell where the files are stored.

User groups

AFS allows users to create groups which can be placed on ACLs to grant members access rights to specific directories. Groups are usually of the form user:groupname where user is the username of the owner of the group and groupname is any name that the owner chooses. By default only the group owner can add and delete members from the group. Once a group is created, it can be used by any user who wants to grant permissions to the members of that group. Each user is allowed to make 20 groups. For examples on how to create groups, please see the section on pts commands below.

Common AFS Commands

There are several commands that might be useful to users. They are the fs suite and the pts suite of commands and their shortcuts.

The fs commands are used to query the file server and to set permissions to access user files. The following are a few of the most common fs commands:

fs listacl or fs la lists the access rights of a directory (defaults to current directory)

helix% fs la /afs/alw.nih.gov/dcrt

Access list for /afs/alw.nih.gov/dcrt is

Normal rights: system:administrators rlidwka

system:anyuser rl

The above shows that the group system:administrators has full access rights to this directory, and the group system:anyone only has read and lookup rights.

fs setacl or fs sa sets the access rights of the directory

helix% fs sa /afs/nih/helix/username/test system:anyuser read

The above gives the group system:anyuser read and lookup permissions to the directory /afs/nih/helix/username/test.

fs listquota shows quota information about the volume:

helix% fs lq                                                 
Volume Name      Quota     Used     % Used     Partition     
u.username       20000     2121     11%        60%

The above displays the volume name, quota and size in kilobytes, percent used of quota, and the percent used of the disk partition that the volume is on.

fs checkservers checks to see if servers are running

fs help lists all the fs commands

The pts commands are used to create and maintain groups. The following are a few of the most common commands:

pts examine or pts ex lists information about a group

helix% pts examine username:class
Name: username:class, id: -1413, owner: username, creator: username,
membership: 3, flags: S-M--, group quota: 0.

The above displays the group name, username:class, its id number, the owner, the creator, the number of members, its privacy flags, and the group quota (which is meaningless in this case, and, therefore, set to zero). The privacy flags show privileges that can be given to the owner, to members of the group, or to everyone. The flag can be a dash, a lowercase character, or an uppercase character. If the flag is a dash, the privilege is only given to the owner. If the flag is lowercase, the privilege is only given to the group's members, and if the flag is uppercase, the privilege is given to everyone. These five flags correspond to `S', the ability to examine the group, `O', the ability to list the groups owned by a user or group, `M', the ability to list the members of the group, `A', the ability to add users to the group, `R', the ability to remove users from the group. In the above case, everyone can examine the group and can list its members. Only the owner is allowed to list the owned groups, add members to the group, and remove members from the group.

pts creategroup <group> or pts cg creates a user-owned group

helix% pts creategroup username:class
group username:class has id -1413

pts adduser or pts ad adds a user to a group

helix% pts adduser student username:class

pts removeuser or pts rem removes a user from a group

helix% pts rem student username:class

pts membership or pts mem lists members of the group

helix% pts mem username:class
Members of username:class (id: -1413) are:
mary
peter
paul

pts listowned lists groups owned by a user

helix% pts listowned student
Groups owned by username (id: 1268) are:
username:class

pts delete deletes the group:

helix% pts delete username:class

pts help lists all the pts commands

Last Updated
June 21, 1996

Printed documentation is available to registered users through the Technical Assistance and Support Center (TASC), Building 12A, Room 1011. Users can order documentation at the CIT Publications website.