AFS Tutorial

AFS, the Andrew File System, is a distributed file system allowing a potentially large set of machines to share access to a set of files in a uniform manner.

AFS uses the client/server model, where all the data is stored on file server machines. File are transferred to client machines as necessary and cached locally.

1.1. Cells and filenames

A single administrative group of servers and clients is known as an AFS cell . Our local cell name is psi.ch.

Files within AFS are named as /afs/cellname/filepath, and such path names are uniform on all AFS clients anywhere in the world. So, for example, paths such as /afs/psi.ch/project/ait/ or /afs/transarc.com/common/etc/CellServDB are valid from any AFS client in the world.

1.2. Using the system type in a path

If the string @sys appears in a file name to be used in AFS, it is automatically replaced with AFS's concept of the type of the machine that the file name is being expanded on.

So, the path /afs/psi.ch/sys/@sys is replaced with /afs/psi.ch/sys/i386_sl4 if running on a workstation running ScientificLinux Version; on a Sun running Solaris 5.8, the pathname becomes /afs/psi.ch/sys/sun4x_58.

This feature may be used in pathnames or symbolic links to allow them to be machine independent. For example, you may link bin in your home directory to @sys/bin. As another example, the links in /usr/pack on most Linux systems are links to a location in /afs/psi.ch/sys/@sys, and the correct binaries are chosen automatically.

1.3. Volumes

UNIX divides disks into partitions . AFS further divides partitions into subsections called volumes . A volume houses a subtree of related files and directories. Normally, volumes are considerably smaller than traditional file systems. For example, each user's home directory would normally be stored in a separate volume. Each sub-directory of /afs/psi.ch/user/x/ and /afs/psi.ch/project would also be stored in a separate volume. Large sub-directories are further sub-divided.

You do not need to know which file server houses any volume. AFS will locate the volume automatically. Indeed, it may move during its lifetime. If you wish to know where a volume is currently stored, see section Volume location.

Volumes have a size limit, or quota . You may receive error messages if the volume you are writing into exceeds its quota. See section "More on Volumes" for more details.

Access to volumes is provided through mount points (see section Mount points). Mount points appear in the file system as directories. When you cd into a directory, you may be crossing a mount point and accessing a new volume, which may be stored on a different machine.

1.4. Tokens

AFS does not use UNIX user IDs for authentication. In order to access files which are not world access-able using AFS, you must have a valid AFS token . You may see what tokens you currently hold using the tokens command.

For example: $ tokens Tokens held by the Cache Manager: User's (AFS ID 5122) tokens for afs@psi.ch [Expires Jun 1 15:04] --End of list--

This output says that the user holds a token for the cell psi.ch for AFS user ID 5122. You may hold extra tokens for different cells, but you may not have more than one token for a particular cell, so if you use klog again, your old token will be discarded.

Tokens expire after 25 hours, and may need to be renewed using the klog command. See section Authentication for more details.

1.5. Checking if the AFS file servers are up

You may check if the AFS file servers for the cell are up using the fs checkservers command: $ fs checkservers All servers are running

1.6. File protections

File protections do not work the same way in AFS as they do in UNIX. AFS augments the standard UNIX file protection mechanism, using a more precise mechanism for controlling access to files: an access control list (ACL).

See section "Access control lists" for more details.

1.7. The fs command

The most generally useful AFS command is fs. This command is effectively a suite of commands of the form fs command args. Type fs help for a full list. To find out the syntax for a particular command, you can type fs help command.

For example: $ fs help listquota fs listquota: list volume quota aliases: lq Usage: fs listquota [-path <dir/file path>+] [-help]

The help lists any aliases for the command, and the arguments that the command accepts. In general, the switches to an AFS command may be omitted if the arguments are given in the order listed in the help message. So, valid commands include: fs lq fs lq /afs/psi.ch/user fs lq -dir /afs/psi.ch/user

This chapter provide some more details about volumes. For even more details, see the AFS User's Guide, or the AFS Command Reference Guide.

2.1. Volume quota

To examine the quota on a volume within AFS, the fs listquota command may be used. fs listquota responds with the name of the volume containing the specified directory, the quota size, amount used, percent used, and the percent of space used on the partition containing the volume.

Example (all sizes are in kilo-bytes): $ fs listquota /afs/psi.ch/ Volume Name Quota Used %Used Partition root.cell.readonly 5000 19 0% 41%

2.2. Mount points

You may find out if a particular directory, or list of directories, is a mount point using the fs lsmount command.

Example: $ cd /afs/psi.ch/sys $ fs lsm * 'afs' is a mount point for volume '#sys.afs' 'alpha_dux40' is a mount point for volume '#alpha_dux40' 'alpha_dux51' is a mount point for volume '#alpha_dux51' 'common' is a mount point for volume '#sys.common' 'i386_linux22' is a mount point for volume '#i386_linux22' 'i386_linux24' is a symbolic link, leading to a mount point for volume '#i386_linux22' 'i386_nt40' is not a mount point. 'i386_sl4' is a mount point for volume '#i386_sl4' 'sgi_65' is a mount point for volume '#sgi_65' 'sun4x_56' is a mount point for volume '#sun4x_56' 'sun4x_57' is a mount point for volume '#sun4x_57' 'sun4x_58' is a mount point for volume '#sun4x_58' 'sys/x86_64_sl4' is a mount point for volume '#x86_64_sl4'

This output shows that all of the directories listed except i386_linux24 are mount points for volumes. One can then use fs lq to get information about the quotas of the various volumes.

2.3. Volume location

You may find out what machine, or machines, have copies of a file (or, more accurately, it's containing volume) using the fs whereis command. For example: $ fs whereis /afs/psi.ch/sys/i386_sl4 File /afs/psi.ch/sys/i386_sl4 is on host afs05.psi.ch

The chapter contains some more details about authentication and tokens for AFS.

3.1. Getting a token

If you login to a system with home-directories on AFS, then a token has been automatically obtained for you. You can verify that you have a valid token with the tokens command. If you do not obtain a token automatically during login, you may obtain a token using the klog command: $ klog Password: YOURPASSWORD If you wish to access another users files temporarily, it is not necessary to log out and log in again. Just issue a klog USER command and continue as the other user.

3.2. Getting rid of a token

If you wish to destroy your token for a cell, you can use the unlog command. This is useful, for example, when you authenticate as someone else temporarily, and then want to destroy the token.

3.3. Changing your AFS password

You may change your AFS password from any machine within the cell using the kpasswd command. The change takes effect throughout the cell immediately. Example: $ kpasswd Password for gsell@PSI.CH: OLDPASSWORD Enter new password: NEWPASSWORD Enter it again: NEWPASSWORD Password changed.

Access control lists (ACLs) are the main way that AFS uses to control access to files and directories. The most important point to bear in mind when discussing ACLs is that only directories have ACLs in AFS; access to files is controlled by the ACL of the containing directory. Another important point to bear in mind is that when you create a new subdirectory, it automatically inherits the ACL that the parent had at the time it was created, i.e., changing the parent ACL in the future will not change the child. ACLs override or replace almost all of the UNIX protection bits. See section "Unix bits in AFS" for more details.

4.1. Examining the ACL for a directory

You may use the command fs la or fs listacl to examine the access control list that applies to a directory. For example: $ fs la /afs/psi.ch/sys Access list for /afs/psi.ch/sys/ is Normal rights: swinst rlidwk system:administrators rlidwka system:anyuser rl linuxsepp rlidwka Most ACL contains system:administrators rlidwka'; the entry may safely be ignored. The rest of this ACL says that anyone can read files in this directory, and list the contents of the directory. Members of the swinst protection group (see section "Protection groups"), can also write files in the directory, and add/delete files in the directory. Additionally, members of the group linuxsepp may change the ACLs for the directory.

4.2. How to decode an ACL

Unlike UNIX, which has only three basic rights that may be controlled, AFS has seven different rights which may be individually controlled. These rights are subdivided into two groups: four directory access rights, and three file access rights.

4.2.1. Directory access rights

The four rights in this group apply to the directory itself. They are:

• lookup: ' l ' The lookup right allows the possessor:
  • to list the names of the files and subdirectories in the directory. It does not allow the possessor to list the contents of subdirectories unless she also has the lookup right in the subdirectories ACL.
  • to access the directory's subdirectories, subject to their own ACLs.

• insert: ' i ' The insert right allows the possessor to add new files and subdirectories to the directory.

• delete: ' d ' The delete right allows the possessor to remove files and subdirectories from the directory.

• administer: ' a ' The administer right allows the possessor to change the ACL for the directory.

4.2.2. File access rights

The three rights in this group only apply to files in the directory. They are:

• read: ' r ' The read right allows the possessor to look at the contents of the directory. For files in the directory, the possessor can read the actual data in the file.
• write: ' w ' The write * right allows the possessor to modify the contents of files in the directory and to modify their UNIX mode bits.
• lock: ' k ' The lock right allows the possessor to run programs that need to '_flock_ ' files in the directory.

4.3. Changing the ACL of a directory

The ACL of a directory may be changed using the fs setacl command. By default, fs sa adds to or alters the existing ACL, rather than replacing it entirely. So, for example, if you wish to give user joe the right to insert and delete files in a directory, you can say fs sa /afs/psi.ch/user/j/joe di As well as accepting any combination of the seven valid AFS rights as an argument, `fs sa' also accepts the following shorthand notations:

• ' write ' All rights except administer.
• ' read ' Read and lookup rights (rl).
• ' all ' All seven rights (rlidwka).
• ' none ' No rights - this removes the user's entry from the ACL entirely.

So, if you wish to remove system:anyuser' from an ACL and allow `system:authuser' to read files, you could say: fs sa /afs/psi.ch/foo/bar system:anyuser none system:authuser read It is also possible to set negative access rights on a directory, denying access, but this won't be discussed here.

4.4. Unix bits in AFS

The UNIX mode bits set on a directory have no effect in AFS and may be safely ignored. However, the first three bits (the user bits) of a file's mode bits do have a meaning in AFS. The file bits may be used to further restrict access to a file that the ACL allows access to. So, for example, if the AFS ACL allows write access to a directory, but the file bits look like -r--??????, then the user will not be allowed to write to the file. Remember, however, that the user bits are applied to anyone who has access to the file; the owner of the file is irrelevant. Also, anyone who has write access to the file through the ACL will be allowed to change the protection bits.

4.5. Protection groups

An AFS protection group is a somewhat similar concept to a UNIX user group, except that it is used exclusively for file protection in access control lists. Another difference is that AFS protection groups are managed by the distributed database component of AFS, and therefore is always up to date and may be modified from any AFS client in the cell.

AFS provides a number of predefined protection groups that may be used in any ACL: $ system:anyuser : This is similar to world permissions in UNIX. Any AFS user ( anywhere in the world) can access files or directories made accessible using this ACL. $ system:authuser : This is a more restrictive version of system:anyuser only users who have authenticated within the local cell may access files made accessible using this ACL.

Users may create or manage their own protection groups, that can be used by any user in any ACL. See the AFS User's Guide for more details.