Home / Unix Timeshare / Tutorials / AFS Primer

UCSC AFS Primer

Description This document describes the basic features of AFS as impletented under UCSC/Athena.

Introduction to filesystems

UFS and NFS

File and directory permissions

AFS

NFS to AFS migration
Cells and volumes
Backup and read-only volumes
OldFiles
File permissions
Groups
Disk quotas

AFS commands

fs
pts
aklog
vos

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. On UCSC/Athena, local drives are used to hold programs and data needed to recover from reboots, temporary user data, 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. On UCSC/Athena, all personal files (except those on meow) are stored on fileservers and are accessible from any UCSC/Athena 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.

UFS and NFS

UFS (UNIX File System) and NFS (Network File System) are two common filesystems in the UCSC/Athena environment.

UFS is the standard local filesystem for machines running UNIX, including the UCSC/Athena workstations. You will not normally have permissions to change or create any files on the local drives of any UCSC/Athena workstations, except in temporary directories, such as /tmp and /usr/tmp.

NFS is a distributed filesystem. Its files are stored on fileservers; in order to access a locker of files, you have to mount it to your computer. On UCSC/Athena, all you have to do to mount a locker is type attach lockername. For example, to attach the bitbucket locker, you would type:

% attach bitbucket
attach: filesystem bitbucket (DROSOPHILE.UCSC.EDU:/b/lockers/bitbucket)
mounted on /cats/bitbucket (read-write)

Now, you can access the files in the directory /cats/bitbucket; the computer will contact the fileserver where the locker bitbucket is stored whenever it needs to read or write something.

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

UFS 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 UFS 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 UFS 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. More information on the system (Moira) groups is available in the Moira section of An Inessential Guide to Athena, available from MIT/SIPB.

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. This does not include files that have been mounted.

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).

AFS

NFS to AFS migration

AFS is a distributed filesystem like NFS. In the winter of 1998, all user accounts on UCSC/Athena were 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 OldFiles. The purpose of OldFiles 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 cats.ucsc.edu cell (this is the cell that contains UCSC/Athena user home directories, along with course lockers and most UCSC/Athena software).

If you need access to a foreign cell which is not currently visible in the /afs directory, please e-mail the ITS Support Center 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 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/cats.ucsc.edu/project/public, and be connected to the volume public in the cell cats.ucsc.edu. For the UCSC cell, you can use /afs/cats/ instead of /afs/cats.ucsc.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 (i.e. locker) 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 public locker, I could type cd /afs/cats/project/public, without having to do add public. However this does not mean that you should not, in some circumstances, attach a volume (i.e. by using the add command). For one thing, attaching a volume subscribes you to some classes of Zephyr messages, so you will be automatically notified if a portion of AFS you are using is becoming unavailable (e.g. due to a server shutdown). In addition, adding a locker also modifies your PATH, so that you will be able to access the programs stored in the locker. Also, volumes that are in other cells (outside the UCSC 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. Attaching or adding a volume will automatically get you tokens. Another way to get tokens is to use the command aklog, 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!

OldFiles

You should have a backup volume mountpoint in your home directory, called OldFiles. As with the volumes in the directory /afs, this is not an actual directory. It is a mountpoint for the volume 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 a few times every week. If you want to retrieve a file that you have accidentally removed, all you have to do is cd to the appropriate directory within OldFiles and use the command cp to copy the file back into your home directory.

If you don't have an OldFiles mountpoint, you can create one using the fs mkmount command. Type:


% fs mkmount OldFiles username.backup

The fs command is described more completely later on this page.

AFS file permissions

In NFS and UFS, 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 UFS file permissions still exist for files in AFS, but their meaning is different. The user field of the UFS 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 UFS 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 UFS 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 locker (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. Groups are managed with the listmaint program. In listmaint, you refer to the group by its short name: groupname; in AFS commands, you refer to the group by its full name system:groupname.

You automatically have one user group. Its name is the same as your username (use the name username in listmaint, but use the name system:username when using an AFS command such as fs). If you want additional user groups you need to request them from the ITS Support Center. Once the group is created by the ITS HelpDesk, you can manage it yourself with the listmaint program.

For instance, user john could request the group system:johnfriends for his friends: Jim, Mary and Bill; and another group system:johnsoc10 for his Sociology 10 classmates: Dave, Barbara and Tom. Then he could, for instance, give group system:johnfriends read and lookup permissions on most of his directories (john trusts his friends). Group system:johnsoc10 could get read and lookup permissions on directories /cats/john/scheme and /cats/john/scheme/soc10, and read, lookup and insert on /cats/john/scheme/hacks. And so on. Some examples of how to create and manipulate groups are described later on this page.

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 john gives a read permission to system:johnsoc10, 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 UCSC/Athena users).

The UFS 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 OldFiles 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/cats/project/public
Volume Name  Quota    Used  % Used  Partition
public      600000  439337     73%        11%

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

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 john wanted to make his scheme directory world-readable. To find out what the current permissions on the directory are, he would do the following:


% fs la scheme
Access list for scheme is
Normal rights:
  john rlidwka

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


% fs sa scheme system:anyuser read
% fs sa scheme 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 john wants to see his new list of acls, so he types:


% fs la scheme
Access list for scheme is
Normal rights:
  system:anyuser rl
  john 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 OldFiles. For example:


% fs mkm OldFiles 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/cats
'/afs/cats' is a symbolic link, leading to a mount point for volume '#cats.ucsc.edu: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 not used much at UCSC since groups are managed through moira with listmaint. The pts creategroup has been disabled at UCSC to make sure that there is ony one authoritative list (i.e. the one in moira).

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 get the members of a group with pts membership and find out information about a group with pts examine.

Suppose john wants to create the group called system:johnsoc10. He will first check to see whether the group exists. Then he will request it from the IRC, then add some people to it.


% pts examine system:johnsoc10
pts: User or group doesn't exist so couldn't look up id for system:johnsoc10
% mail help@ucsc.edu
Subject: New group request
Please create the group johnsoc10.
  ...(Time passes. John gets a message from the IRC that the group has been created)...
% listmaint
  ...(John uses listmaint to add users john, lnp and cuban to the johnsoc10 list, then wait 2 hours for it to take effect)...
% pts membership system:johnsoc10
Members of system:johnsoc10 are:
  lnp
  john
  cuban

Note that john must add himself to the group johnsoc10; 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 scheme system:johnsoc10 all
% fs la scheme
Access list for scheme is
Normal rights:
  system:johnsoc10 rlidwka
  system:anyuser rl
  john rlidwka
  sara rlidwk

You can use pts membership to get the members of most system-controlled lists. Even though Moira can give you this information as well, it is sometimes faster to get the information from AFS.

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 renew, and then enter your UCSC/Athena password at the Password: prompt.

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 UCSC-based cell. Basically, aklog uses your Kerberos tickets to get you tokens for the cell. To use aklog, you can type aklog -c cellname, or you can cd to a volume in the cell and type aklog . ("." is an abbreviation for the current directory). For more information, you can read the manual page for aklog. Note that if you attach or add a volume, the command aklog will be called as a part of the attach process.

If you need to authenticate yourself to foreign cells, you may need to use the command klog instead. aklog only works if you already have Kerberos ticket from the cell (such as you do when you use Athena).

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 public
public  536871263 RW  439337 K  On-line
    ailurophile.UCSC.EDU /vicepc
    RWrite 536871263   ROnly 536871264   Backup 536871265
    MaxQuota    600000 K
    Creation    Mon Aug  4 18:45:35 1997
    Last Update Tue Nov 25 14:13:53 1997
    2058 accesses in the past day (i.e., vnode references)
    RWrite: 536871263  Backup: 536871265
    number of sites -> 1
       server ailurophile.UCSC.EDU partition /vicepc RW Site

Suppose I want to know when the locker public was last backed up. I can use the same command on public.backup to find out:


% vos examine public.backup
public.backup  536871265 BK  439182 K  On-line
    ailurophile.UCSC.EDU /vicepc
    RWrite 536871263   ROnly 536871264   Backup 536871265
    MaxQuota    600000 K
    Creation    Tue Nov 25 01:30:18 1997
    Last Update Tue Nov 25 01:30:18 1997
    0 accesses in the past day (i.e., vnode references)
    RWrite: 536871263  Backup: 536871265
    number of sites -> 1
       server ailurophile.UCSC.EDU partition /vicepc RW Site

This tells me that the backup volume was last updated on Tuesday, November 25.

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.

This document is modeled after Inessential AFS written by E. Jay Berkenbilt, Barbara Manganis, and Albert Dvornik from MIT's SIPB documentation project. It has been adapted for UC Santa Cruz by Jacques Delsemme.