Primer

This document describes the basic features of AFS as impletented by the Stanford Computer Science Department. If you are mainly interested in the changes caused by the NFS to AFS transition, please check What is different about AFS?

Introduction to filesystems

Working on a computer involves creating and manipulating files. The data and the programs cannot be continuously stored in a computer's memory: they have to be stored in files that can be read by the computer when needed. The various methods for handling files are called filesystems.

You don't need to know much about filesystems to start using a computer. However, with a bit of information, you can:

Let other people read your files.
Let some other people read some of your files, and not the others.
Get to know the basics of how filesystems actually work.

Local filesystems handle files that are stored directly on the computer you are using. These files are stored on a local hard disk, sometimes called a hard drive. In the Computer Science Department, local drives are used to hold programs and data needed to recover from reboots, temporary user data (scratch space), and most commonly used application programs.

Distributed filesystems do not store files directly on the local computer, but rather in a central storage location that is accessible to a network of computers. This storage space, called a fileserver, is a computer with an extra large hard drive. All personal files are stored on fileservers and are accessible from any CS workstation. However, since all the files have to pass through the network to get to your workstation, access is a little bit slower than for local files.

Local filesystems and NFS

Local filesystems and NFS (Network File System) are two common filesystems in the department.

Local filesystems (like ufs on Solaris and ext2/ext3 on Linux) are found on machines running UNIX and similar operating systems. You will not normally have permissions to change or create any files on the local drives of any CS workstations, except in temporary directories, such as /tmp and /var/tmp.

NFS is a distributed filesystem. Its files are stored on fileservers; in order to access a files, you have to mount it to your computer. Because of the inherent insecurity of NFS, access to NFS filesystems is strictly regulated.

Except for mounting (which is needed in NFS), local filesystems and NFS are very similar to work with.

Local and NFS file and directory permissions

File permissions regulate file access. They allow you to control who can read, write, or execute any files you may own. File permissions in a local filesystem and in NFS are similar, and specified for each file and directory. The three basic permissions are:

read (r)
Having read permission on a file grants the right to read the contents of the file. Read permission on a directory implies the ability to list all the files in the directory.
write (w)
Write permission implies the ability to change the contents of the file (for a file) or create new files in the directory (for a directory).
execute (x)
Execute permission on files means the right to execute them, if they are programs. (Files that are not programs should not be given the execute permission.) For directories, execute permission allows you to enter the directory (i.e., cd into it), and to access any of its files.

Under both local filesystems and NFS, permissions exist separately for user, group, and others. User (u) permissions apply to the owner of the file. Group (g) permissions apply to all members of the group associated with the file. Permissions for others (o) apply to anyone else. The default owner of any file you create will be you. The group will be inherited from its parent directory.

The permissions, owner and group associated with a file or directory can be checked by looking at the output of ls -lg. The permissions are listed in the first field of the output. If the first character is d, the entry is a directory; the character - or the letter f signifies a normal file. The next three characters signify the user permissions: their values will be r, w or x (respectively) if the permission is granted, or - if it isn't. The following three characters represent the group permissions in the same way, and the last three represent others. The owner of the file is listed in the third field of the output; the fourth field lists the group associated with the file. So if a file notes looked like this:

  -rw-r-----  1 joeuser   joepals      10460 jun 17 11:27  notes

it would mean that the user joeuser has read and write permissions on the file notes, the members of the group joepals have only read permission, while everybody else has none. Note that the username root signifies the superuser. Anyone with the superuser privileges implicitly has read and write permissions, as well as the ability to change permissions, on all the files on the local disks.

The permissions can be changed by using the chmod command. Granting permissions is done by chmod who+permissions, where who is any combination of u, g and o, and permissions any combination of r, w and x. Similarly, permissions are withdrawn by using chmod who-permissions. You can change the group associated with a file by chgrp groupname file(s). For more information on these two commands, read the corresponding manual pages via man chown and man chgrp on any CS workstation.

AFS

NFS to AFS migration

AFS is a distributed filesystem like NFS. Starting in the spring of 2004, all user accounts on CS machines maintained by Computer Facilities will be moved from NFS to AFS. Many NFS commands also work on AFS; however, there are many important differences between AFS and NFS. You may also notice new subdirectories in your home directory such as .backup and .public. The purpose of .backup will be addressed in the next few sections.

AFS organization: cell and volumes

The largest element in the AFS structure is a cell. A cell constitutes a separate administrative domain of authority. Each cell keeps its own list of users, groups, and system administrators. That means that a user from one cell might not exist in another cell. In that case, they will only be able to access the files in directories that have the appropriate permission set to system:anyuser. An example of a cell is the cs.stanford.edu cell (this is the cell that contains CS user home directories, along with course and research group files.

If you need access to a foreign cell which is not currently visible in the /afs directory, please send a request on http://support.cs.stanford.edu to have it added.

Each cell is made up of volumes. A volume is a collection of files and directories that are grouped together and given a name. Your home directory is a volume, the volume user.username. Once created, each volume can (as a unit) be moved from one server to another, backed up, replicated or destroyed. Files and directories can be created, modified or deleted only in an existing volume.

The whole multi-cell AFS directory structure is accessible through the directory /afs. The volume in /afs is named root.afs. The directory /afs contains the mountpoints to the root volumes for each cell, which are usually named cellname:root.cell. These volumes act like directories, and may in turn contain the mountpoints to other volumes. Thus you can cd to /afs/cs.stanford.edu/etc, and be connected to the volume etc in the cell cs.stanford.edu. For the CS cell, you can use /afs/cs/ instead of /afs/cs.stanford.edu since the root.afs directory contains a symbolic link from one to the other.

Because of the way AFS works, you do not have to explicitly attach any volume or filesystem that is on AFS in order to have access to it. All you need, in order to access a file, is the pathname of the file. For example, if I wanted to get to the software tree, I could type cd /afs/cs/software.

Volumes that are in other cells (outside the cs.stanford.edu cell) will not recognize you or give you your proper permissions unless you are authenticated to that cell (except for volumes where the appropriate permissions are given to system:anyuser). To do this you need to get tokens for the cell, which are analogous to separate Kerberos tickets for individual NFS fileservers. The most common way to get tokens is to use the command klog, described later on this page.

Backup and read-only volumes

There are three types of volumes: read-write, read-only, and backup. A read-write volume is a regular volume that can be read and written-just as the name implies. A read-write volume may have associated with it zero, one, or many read-only volumes. Read-only volumes cannot be modified by normal users. They have special properties, the most important of which is that many copies of a read-only volume can exist at once. If an AFS mountpoint is read-only and a read-only volume exists with the right name, AFS just picks one read-only volume to read from. If that volume disappears or somehow becomes unreachable, AFS will start using another one without the user ever knowing the difference.

Backup volumes are also special. There can be only one backup volume for a read-write volume. Read-only volumes cannot have backup volumes. In other words, a backup volume can be associated only with a read-write volume. A backup volume is a read-only copy of a read-write volume that actually shares the same disk space as the read-write volume. These volumes are often known as clones. When a volume is backed up, that volume initially takes a very small amount of space on disk. As the read-write volume and the backup volume get further out of synchronization, data is actually copied. The next time the volume is backed up, the old copied data is destroyed. That means that, once a volume has been backed up once, subsequent backups of the volume may actually reduce the total amount of disk spaced used.

Online backups via .backup

You should have a backup volume mountpoint in your home directory, called .backup. As with the volumes in the directory /afs, this is not an actual directory. It is a mountpoint for the volume user.username.backup, but for all intents and purposes it behaves like a directory. (Of course, it doesn't use up your quota.) All your files are backed up nightly. If you want to retrieve a file that you have accidentally removed, all you have to do is cd to the appropriate directory within .backup and use the command cp to copy the file back into your home directory.

AFS file permissions

In NFS and local filesystems, you can set permissions on a file-by-file basis. In AFS, file permissions are specified for each directory, and apply to the directory and to all the files that this directory contains. They do not apply to the subdirectories of a directory, since the subdirectories have their own permissions; however, any newly created subdirectory will inherit the permissions of its parent directory. These directory permissions are flexible; they can be applied individually for each user. You can give Jim, Mary and Bill the permission to see the list of all files in your home directory, Valerie the permission to list and read them, and Tom the permission to list, read and write them. The list of all users that have permissions, along with their permissions, is called the access control list or ACL of the directory. ACL is often pronounced ackle.

There are seven types of access that you can grant:

Lookup
With lookup access on a directory, it is possible to look at the directory's ACL and to list the contents of the directory (i.e., what files and directories are in it). It does not imply read access to the files. You must have lookup permission to use any other permission (except administer).
Read
Read access on a directory implies permission to read the contents of all the files in a directory. (This says nothing about the right to read files in its subdirectories.)
Write
Write access on a directory grants permission to modify existing files and subdirectories within a directory, and to change permissions on the files in that directory. It implies neither insert nor delete access to the directory.
Insert
Insert access on a directory implies permission to create files or subdirectories in the directory. It does not imply the ability to modify the files once they are created, however. Insert access without write access is useful mainly for the case when you want to allow someone to create files or subdirectories in a given directory but not to modify files that are already there.
Delete
Delete access on a directory gives the ability to remove files or empty subdirectories from the directory. Like insert, delete access does not imply write access.
Administer
With administer access on a directory, it is possible to change the ACL of the directory. Administer access does not imply any other kind of access. As with all other rights, setting or resetting administer access on a directory only affects that particular directory. It does not affect pre-existing subdirectories.
Lock
A user with lock access on a directory can put advisory locks on files within the directory. This is typically useful only to programmers.

To change the ACL for a file or directory, you can use the fs command, described later on this page.

The UNIX-style file permissions still exist for files in AFS, but their meaning is different. The user field of the file permissions can be used to further restrict the access rights on the AFS files and directories. Withdrawing the user permissions will deny the right of access to all the users who would normally have that right, including the owner of the file. For example, if the user read permission for a file is set (as it normally is), then anyone who has an AFS read permission on the directory can access the file. However, if you withdraw the user read permission using the chmod command, then no one (including you) will be able to read the file, even if they have AFS read permission on the directory. If you set all the UNIX-style permissions on a file, then the right of access that file will be determined solely from the ACL on the directory. (The group and other fields of the file permissions are generally not used.)

It is also possible to give users negative permissions on a directory, thus specifically denying them the corresponding rights. Negative permissions are stronger than the positive ones. Their use is described in more details later on this page.

Each directory has its own ACL. Whenever you create a new directory, it inherits the ACL of its parent. You always have the administer rights on the top-level directories in your home directory (or any other AFS volume you own). You cannot take this right away from yourself.

AFS groups

If several users need to appear together on many ACLs, it is usually easier to put them in a group, and regulate them together. A group is simply a list of users. You can give permissions to a group in the same way that you give permissions to users, and these permissions will then apply to all members of the group.

You can create your own user groups, which will have names of the form user:groupname, where user is your username, and groupname is a name you choose for the the group. For instance, user joe could create group joe:friends for his friends Jim, Mary and Bill, and another group joe:cs106 for his CS 106 classmates, Dave, Barbara and Tom. Then he could, for instance, give group joe:friends read and lookup permissions on most of his directories (joe trusts his friends). Group joe:cs106 could get read and lookup permissions on directories /afs/cs/u/joe/classes and /afs/cs/u/joe/classes/cs106, and read, lookup and insert on /afs/cs/u/joe/classes/cs106/project. And so on. For some examples of how to create and manipulate groups, see section 6.3 of this document.

If you want to give permission to everyone in a group except someone, you can exclude them using negative permissions, described earlier on this page. Negative permissions deny rights to users or groups. They are stronger than positive rights, so if joe gives a read permission to joe:cs106, but denies it to Tom, who is a member of the group, Tom will not be able to read the files.

AFS groups also include some pre-existing system groups. System groups have names of the form system:groupname, as well. The group system:anyuser includes any AFS user. Giving read and lookup permissions to system:anyuser will, therefore, make the directory world-readable: anyone with access to AFS (literally around the globe!) will be able to read the files. The group system:authuser includes any user that has authenticated themselves with AFS locally (this includes all the CS users).

The UNIX-style groups still exist for files under AFS, but they are completely ignored. So you should ignore the group name that you can see with the ls -lg command.

AFS disk quotas

Regular quotas in UNIX are done on a per-user basis. A quota on the NFS filesystem is generally something like ``User a is allowed to store b blocks of data on disk c.'' Although this used to work fine when machines had few disks and few users, it doesn't work well at all for shared space. In AFS, quotas are set on a per-volume basis. That means it doesn't matter who writes into an AFS volume, it only has a fixed amount of space. The quota on an AFS volume can be examined with the fs listquota command (see later on this page).

You should note that the space your .backup backup volume takes does not count against your user quota.

AFS commands

You may be wondering how you actually do all these things, such as changing permissions and checking quota and creating groups. In many cases, NFS commands will still work in AFS. However, there are a few commands that are different, and a few commands that have AFS counterparts that may be easier or faster.

The fs command

The command fs is actually not a single command, but a whole group of commands that allow you to query the fileserver and set permissions.

One important command to know is fs listquota (abbreviated fs lq). This returns the disk usage and quota for whatever volume you happen to be in (if there are no arguments) or for whatever volume you give it. For example,

	$ fs lq /afs/cs/etc
	Volume Name                   Quota      Used %Used   Partition
	etc.readonly                   5000        23    0%         65%

This shows you the disk quota and the usage for the volume etc.

Two other commands are fs setacl (or fs sa), and fs listacl (or fs la). These commands allow you to change and list the permissions on any particular directory. For example, suppose user joe wanted to make his classes directory world-readable. To find out what the current permissions on the directory are, he would do the following:

  $ fs la classes
  Access list for classes is
  Normal rights:
    joe rlidwka

This shows that joe has all permissions on his classes directory. Now, he wants to give anyone the ability to read his classes directory. While he is at it, he wants to give his trusted friend sara write permission on his classes directory. He would type:

  $ fs sa classes system:anyuser read
  $ fs sa classes sara write

Note that the syntax of the setacl command is fs sa directory who permissions. Note also that in this example we used the aliases read and write. In all there are four such aliases: read, which is the same as r and l access; write, which expands to r, l, i, d, w, and k access; all, which means all types of access (r, l, i, d, w, k, and a); and none, which sets no access.

Now joe wants to see his new list of acls, so he types:

  $ fs la classes
  Access list for classes is
  Normal rights:
    system:anyuser rl
    joe rlidwka
    sara rlidwk

In addition to the fs listacl and fs setacl commands, there are other fs command arguments which allow you to do everything from create mountpoints (see ealier on this page) to query the servers. For example:

fs mkmount, or fs mkm

As mentioned before, this command allows you to create a mountpoint, such as the one used for .backup. For example:

      $ fs mkm .backup username.backup

fs lsmount, or fs lsm

This lists information about a mountpoint, most importantly the specific name of the mounted volume. For example:

      $ fs lsm /afs/cs.stanford.edu
      '/afs/cs.stanford.edu' is a mount point for volume '#root.cell'

fs whereis

This command tells you on which server a file or a directory is located. You can use it in the form fs whereis ~ to find out on which server your home directory is stored.

fs checkservers, or fs checks

This command will tell you what servers are currently down.

fs help

This will give you information about various fs arguments and what each one does. You can also type fs help argument for more information about a particular argument.

The pts command

The command pts is used to contact the AFS Protection Server, an AFS server that stores all the information on AFS users and groups. You can create your own groups and add members to them with the commands pts creategroup and pts adduser. You can remove users from groups with pts removeuser and delete groups with pts delete. You can get the members of a group with pts membership and find out information about a group with pts examine.

Suppose joe wants to create the group called joe:cs106. He will first check to see whether the group exists. Then he will create it and add some people to it.

  $ pts examine joe:cs106
  pts: User or group doesn't exist so couldn't look up id for joe:cs106
  $ pts creategroup joe:cs106
  group joe:cs106 has id -65574
  $ pts adduser joe joe:cs106
  $ pts adduser lnp joe:cs106
  $ pts adduser cuban joe:cs106
  $ pts membership joe:cs106
  Members of joe:cs106 are:
  lnp
  joe
  cuban

Note that joe must add himself to the group joe:cs106; you are not by default a member of any group you create.

Now that the group exists, he can give its members access to his scheme directory.

  $ fs sa classes joe:cs106 all
  $ fs la classes
  Access list for classes is
  Normal rights:
    joe:cs106 rlidwka
    system:anyuser rl
    john rlidwka
    sara rlidwk

You can use pts membership to get the members of most system-controlled lists.

Note that unlike NFS groups, you do not have to wait for system updates for changes to AFS groups to take effect. They take effect as soon as the user re-authenticates to the cell. The easiest way to do that is to type aklog.

The aklog command

As mentioned before, you do not need to explicitly attach a volume to access its files. However, if the volume is in another cell, the cell may not recognize you and grant you the proper permissions. You can use the command aklog to identify, or authenticate, yourself to a the cs.stanford.edu cell. Under normal circumstances, you don't need to run this command because your AFS tokens are automatically obtained for you when you login. However, your tokens eventually expire, and simply running aklog will obtain new ones for you.

If you need to authenticate yourself to foreign cells (like ir.stanford.edu for your Leland account), you may need to use the command klog instead. aklog only works if you already have Kerberos ticket from the cell. To authenticate to ir.stanford.edu, run klog SUNetID@ir.stanford.edu, where SUNetID is your SUNetID/Leland user name.

Conversely, if you are in a foreign cell (like ir.stanford.edu), you can use klog to get access to your cs.stanford.edu files by running klogCSID@cs.stanford.edu, where CS ID is your CS ID / xenon user name.

The vos command

The command vos is primarily of interest to system administrators, but it does have a few functions of interest to general users. Specifically, it is used to query and manipulate volumes.

The command vos examine is used to find out general information about a volume. This information includes the volume identification number of the volume itself, as well as the volume identification number of the backup and read-only volumes associated with it (if they exist). It also tells what server the volume is located on and when the volume has last been released or backed up. In addition, it tells you when the volume was last changed, and what the maximum quota of the volume is. Here is an example:

 $ vos examine etc
 etc                               536871014 RW         23 K  On-line
    cs-afs-3.Stanford.EDU /vicepa
    RWrite  536871014 ROnly  536871015 Backup  536871016
    MaxQuota       5000 K
    Creation    Tue Feb 24 09:35:52 2004
    Last Update Mon Mar 15 17:08:13 2004
    1 accesses in the past day (i.e., vnode references)

    RWrite: 536871014     ROnly: 536871015     Backup: 536871016
    number of sites -> 4
        server cs-afs-3.Stanford.EDU partition /vicepa RW Site
        server cs-afs-1.Stanford.EDU partition /vicepa RO Site
        server cs-afs-2.Stanford.EDU partition /vicepa RO Site
        server cs-afs-3.Stanford.EDU partition /vicepa RO Site

Suppose joe wants to know when his volume was last backed up. He can use the same command on user.joe.backup to find out:

 $ vos examine user.joe.backup
 user.joe.backup                 536870920 BK     890998 K  On-line
    cs-afs-1.Stanford.EDU /vicepa
    RWrite  536870918 ROnly          0 Backup  536870920
    MaxQuota   10000000 K
    Creation    Mon Mar 15 23:30:19 2004
    Last Update Mon Mar 15 23:30:19 2004
    0 accesses in the past day (i.e., vnode references)

    RWrite: 536870918     Backup: 536870920
    number of sites -> 1
        server cs-afs-1.Stanford.EDU partition /vicepa RW Site

This tells joe that the backup volume was last updated on Monday, March 15 at 11:30 PM.

Another useful command is vos listvldb. In the form vos listvldb -name volumename (where volumename is the name of the volume in the form given by fs lsm), this command will tell you what server the volume volumename is on (among other things), even if that server is down.

For more information on the command vos, type vos help at the UNIX prompt.

For more information

Many organizations have been using AFS for years, and extensive information about AFS can be found on the web. The following are some of the more useful links:

Credits

This document is modeled after Inessential AFS written by E. Jay Berkenbilt, Barbara Manganis, and Albert Dvornik from MIT's SIPB documentation project.