Inessential AFS Version 1.1

Emanuel Jay Berkenbilt Student Information Processing Board January 19, 1991

Contents

1 What is AFS? 1 2 AFS Volume? Why do I care how loud my files are? 1 3 How Do I Use AFS? 2 4 File Protections Under AFS 3 5 Changing Protections in AFS 5 6 AFS Groups 7 7 Warning: It’s Uphill From Here 8 8 Disk Quotas in AFS 8 9 Backup and Read-only Volumes 9 10 Useful Arguments to fs, vos, and bos 10 11 System Type 12 12 AFS Cell Organization 13

12.1 More About AFS Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 12.2 AFS Volume Mountpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 12.3 Cell Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 12.4 Volume Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

13 Shortcuts for Advanced Users 16 14 Where to Go For More Information 17 15 Credits 17

1 What is AFS?

AFS, the Andrew File System^{1}, is a file system originally developed at Carnegie Mellon’s Project Andrew^{2}. AFS is now produced and supported by Transarc, Inc. Before there is any hope of understanding AFS, you must understand what a file system is.

A file system is simply a place where files are kept. The word can be used to refer to different things. A floppy disk on a PC could be called a file system as could a hard disk on the server you get your files from. The term “file system” can also be used to refer to a specific kind of file system. This is the way we use the term in this document. More information about file systems can be found in An Inessential Guide to Athena, available from the SIPB.

Like NFS, AFS is a network file system, or, as it is usually called, a distributed file system. This means that the files you gain access to through AFS do not actually reside on the workstation you are using. They are located, instead, on a remote server and are available over a wide geographic area. From an Athena workstation, you can look at AFS files from schools and institutions all over the country.

AFS is different from other network file systems that have been used at Project Athena. Most notably, all AFS files appear to be present on the workstation at all times. They are always available from the workstation under the directory /afs. Another major difference between AFS and other distributed file systems is that groups of AFS files can be replicated onto multiple servers in such a way that makes the failure of one server unnoticeable to a user. In addition, the file and directory structures most commonly used are temporarily cached, or stored, on the workstation to minimize network traffic to the server. This means that once an AFS file has been read once, subsequent reads of that file will be very fast.

2 AFS Volume? Why do I care how loud my files are?

No, no, no; that’s not what “AFS volume” means. In order to understand AFS, it is important to know some basic terminology. Following is a list of terms that you should understand before you really use AFS:

Volume: An AFS volume is a collection of files and directories that are grouped together as one unit. A volume can be backed up, renamed, moved from one server to another, replicated, created, or destroyed as a unit. It is also the entity upon which a disk quota is enforced.

User: A user is someone who is registered with AFS. You must be registered with AFS if you wish to be able to own files. All Athena users are registered with AFS.

1AFS and Andrew File System are trademarks of Transarc, Inc.

2Project Andrew is a large-scale distributed workstation experiment similar to Project Athena.

Group: A group is a list of users^{3}.

Cell: An AFS cell is essentially a domain of authority. It is the largest unit used in AFS. Each cell has a list of administrators, a list of users, a list of groups, and a list of volumes. Each of these lists is private to the cell. This means that an administrator in one cell may or may not have any access to another cell. A user in one cell may not even exist in another.

ACL: ACL stands for Access Control List. When referring to access control lists, some people say the initials (“A-C-L”) and others pronounce the acronym (“ackle”). An access control list pairs users and groups with the operations that they are allowed (or not allowed) to perform. Although access control lists are used for much more than just AFS, only AFS access control lists will be discussed here. A typical access control list would say something like, “The user potato is allowed to create files in this directory. The user soup is allowed to modify existing files and create new files in this directory. Anyone else is allowed only to read files in this directory.” AFS access control lists and how to use them are explained in more detail in the section on file protections (Section 4) in this document.

3 How Do I Use AFS?

In general, you use AFS in the same way you use any other network file system at Athena: just attach the file system you want without caring what kind of file system you use. You will probably not even notice whether files you are using come from AFS. In fact, if you have attached the sipb file system since September of 1989, you have probably been using AFS. It is also possible, however, to see all AFS files on a given workstation. To do this, just look under the directory /afs. Do this with caution though, because since you will be looking at files from all over the country, some things will be very slow.

Since AFS files are not actually stored on the workstation you are using, there needs to be a way for you to tell AFS who you are. Before AFS can know who you are, you have to be authenticated to the cell. Authentication is just the name given to the act of proving your identity. Fortunately, authentication to AFS is handled automatically through the attach command. Should you have to reauthenticate for some reason, you can just reattach whatever it is that you are trying to use.

Currently, attach authenticates to AFS by using a program called aklog. Although the aklog program is not generally intended for use by users directly, it is available in the Athena release. The aklog program is discussed briefly in the section on shortcuts for advanced users (Section 13).

3AFS groups cannot currently contain other groups. However, since Athena groups can, our interface to group membership for AFS groups handles this automatically. If you don’t understand this footnote, forget it.

4 File Protections Under AFS

AFS offers considerably more flexibility in directory protections than regular UNIX^{4}. In addition the bit fields used in regular UNIX file protections, protections in AFS are enforced with access control lists set on directories. This means that in AFS it is possible, for example, to give one set of users read access to a directory, one set of users write access, and another set no access at all.

If you wish to list or change protections, you will need to become somewhat familiar with the command fs. This command allows you to get various kinds of information about AFS files and directories and to change and look up protections on directories. Although it is not necessary for you to understand standard UNIX file protections in order to understand AFS file protections, it will probably help you if you do. Standard UNIX file protections are explained in the file protection section of An Inessential Guide to Athena, available from the SIPB.

The fs command has a built-in help feature. Typing fs help will give you a list of available subcommands and some information on how to use them. For help on any individual subcommand, you can type fs help subcommand. All the commands that you will probably want to use, though, are described in this document.

There are seven types of access that can be granted. In each case, a given type of access refers only to the directory on which it is set or to the files in the directory. Having a certain kind of access on one directory has no implications about having the same kind of access to subdirectories.

Read (r): Read access on a directory implies permission to read the contents of all the files in a directory.

Lookup (l): With lookup access on a directory, it is possible to look at the directory’s access control list 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. If you do not have lookup access to a directory, no form of access other than administer access can be used.

Insert (i): 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 that are created, however. Insert access without write access is useful mainly for the case when you want to allow someone to create subdirectories in a given directory but not to modify files that are already there.

Delete (d): Delete access on a directory implies the ability to remove files or empty subdirectories from the directory. Like insert, delete access does not imply write access.

Write (w): Write access on a directory grants permission to modify files and subdirectories within a directory. It implies neither insert nor delete access to the directory.

4UNIX is a trademark of AT&T.

Lock (k): A user with lock access on a directory can put advisory locks on files within the directory. This is typically useful only to application programmers.

Administer (a): With administer access on a directory, it is possible to change the access control list of the directory. Administer access does not imply any other kind of access. Administer access, contrary to some people’s intuition, cannot be “forced” onto subdirectories. It applies only to the directory on which it is set; it does not apply to that directory’s subdirectories.

In addition to the access control lists described above, some of the regular UNIX protections apply as well but in a more limited way. Specifically, the user portion of a file’s UNIX mode bits applies to all users, not just the owner of a file. That means that if a file’s user mode bits show the file to be unreadable, the file will not be readable by anyone regardless of the access control list set on its parent directory. Likewise, if the user mode bits are set to give read, write, and execute access, then access to the file is determined completely by the AFS access control list on the directory. The group and other bits as well as the UNIX group of the file are currently ignored in AFS^{5}. If you didn’t understand that, ignore it.

The owner of a volume has automatic implicit administer access to all directories in the volume. The owner of a directory has automatic administer rights to that directory. That means that if you own a directory, no one can take administer access away from you for that directory even if they use the fs command to take you off the access control list. If you own a volume, no one can remove your administer access from any directory in the volume. (You own a volume when you own the top-level directory of the volume.) This also means that you can not accidentally remove your own administer access to a directory you own.

Access can be granted to individual users or to groups. There are two special groups: system:anyuser and system:authuser. The group system:anyuser includes all users whether or not they are known to the cell. The group system:authuser includes any user who is registered with the cell and has been authenticated (i.e., anyone who has told AFS who they are)^{6}.

Other groups can be one of two types: system groups or user groups. System groups have names that start with system:. They are controlled by the system administrators and by regular users through Moira. (See the Moira section of An Inessential Guide to Athena, available from the SIPB.) User groups start with ⟨user⟩:, where ⟨user⟩ is the name of the user who owns the group. It is possible for any user to create his or her own groups in AFS. Information about how to do this appears below.

An access control list on a directory contains a list of users and groups each paired with the operations they are allowed to perform. To find out what the access control list on a directory is, you can use the command fs listacl ⟨directory⟩ where ⟨directory⟩ is the name of the directory you are interested in. Note that fs la is short for fs listacl.

5Well, actually, the UNIX group field and group mode bits are used in a limited way for setgid executables, but this is beyond the scope of this document.

6These groups don’t really include people, they just behave as if they do. If you don’t understand this footnote, forget it.

For example:

athena% attach sipb
attach: /afs/athena.mit.edu/contrib/sipb linked to /mit/sipb for filesystem sipb
athena% fs la /mit/sipb
Access list for /mit/sipb is
Normal rights:
  system:gsipbbin rlidwka
  system:anyuser rl

This means that members of the system-controlled group system:gsipbbin have full access to /mit/sipb and all other users have read and lookup access only.

Here is another example:

athena% attach qjb
attach: /afs/athena.mit.edu/user/q/qjb linked to /mit/qjb for filesystem qjb
athena% fs la /mit/qjb
Access list for /mit/qjb is
Normal rights:
  qjb:all rlidwka
  qjb:friends rla
  system:anyuser rl

This means that the user-controlled group qjb:all has all access to /mit/qjb, the user-controlled group qjb:friends has read, lookup, and administer access to /mit/qjb, and everyone else has read and lookup access only.

5 Changing Protections in AFS

To set access control lists, you use the command fs setacl, which may be abbreviated fs sa. The format of this command is fs sa ⟨directory⟩ ⟨user or group⟩ ⟨access⟩ where ⟨user or group⟩ is the user or group to which you wish to give access and ⟨access⟩ is the type of access you wish to grant. The format of the access specification is a string of characters that correspond to the different access types. In addition, four shortcuts are understood: read, which means r and l access; write, which means r, l, i, d, w, and k access; all, which means all kinds of access (r, l, i, d, w, k, and a; and none, which means no access.

Here is an example of setting an access control list.

First, let’s look at the access control list that is already set.

athena% fs la test
Access list for test is
Normal rights:
  qjb rlidwka

Now, let’s give testuser write access to the directory and check to make sure that it worked.

athena% fs sa test testuser write
athena% fs la test
Access list for test is
Normal rights:
  qjb rlidwka
  testuser rlidwk

Now, let’s say that anyone authenticated to the cell can read from this directory.

athena% fs sa test system:authuser read
athena% fs la test
Access list for test is
Normal rights:
  system:authuser rl
  qjb rlidwka
  testuser rlidwk

Now, let’s remove access from testuser.

athena% fs sa test testuser none
athena% fs la test
Access list for test is
Normal rights:
  system:authuser rl
  qjb rlidwka

If no access has been explicitly set for a directory (such as when the directory is first created), the directory will inherit its access control list from its parent. Changing the access control list of a directory, however, has no effect on the access control lists of its subdirectories.

AFS also supports negative acls. Negative acls provide a way to deny a user or group access to a directory. There is no guarantee that negative acls will always be supported by AFS. Currently, you can set a negative acl by simply adding the -negative commandline flag to the fs sa command. Setting a negative acl does not cancel a positive acl. That is, the command fs sa testuser none is not the same as fs sa testuser all -negative. If you don’t understand this paragraph, forget it.

6 AFS Groups

At Project Athena, the AFS system-controlled group called system:⟨groupname⟩ corresponds to the Moira group called ⟨groupname⟩. The Moira section of An Inessential Guide to Athena, available from the SIPB, explains how to use these groups. Since there is a group on Athena corresponding to each username, you have an AFS group of your very own called system:⟨user⟩ where ⟨user⟩ is your username.

As you use the command fs to manipulate file protections, you use the command pts to perform operations on users and groups. You can create your own groups and add members to them with the commands pts creategroup and pts add. You can remove users from groups with pts remove 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.

For example, suppose I, the user qjb, create a group called qjb:potato^{7}. I will first check to see whether the group exists. Then I will create it and add some people to it.

athena% pts examine qjb:potato
pts: User or group doesn't exist so couldn't look up id for qjb:potato
athena% pts creategroup qjb:potato
group qjb:potato has id -65574
athena% pts add qjb qjb:potato
athena% pts add lnp qjb:potato
athena% pts add cuban qjb:potato
athena% pts membership qjb:potato
Members of qjb:potato are:
  lnp
  qjb
  cuban

Now that I have created the group, I can give its members access to some directory.

7I would probably do this because I happen to like potatoes.

athena% fs sa test qjb:potato all
athena% fs la test
Access list for test is
Normal rights:
  qjb:potato rlidwka
  system:authuser rl
  qjb rlidwka

Now that I have finished this demonstration, I can clean up and delete the group.

athena% fs sa test qjb:potato none
athena% pts remove qjb qjb:potato
athena% pts remove lnp qjb:potato
athena% pts remove cuban qjb:potato
athena% pts examine qjb:potato
Name: qjb:potato, id: -65574, owner: qjb, creator: qjb,
  membership: 0, flags: S-M--, group quota: 0.
athena% pts delete qjb:potato

You can use pts membership to get the members of a system-controlled list as well as of a user-controlled list. 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, which can be done by reattaching the file system in question or by using the aklog program discussed in the section on shortcuts for advanced users (Section 13).

7 Warning: It’s Uphill From Here

The remaining sections of this document are more difficult than those that you have seen so far. You are encouraged to continue, but don’t worry if you have to skip parts. Many of the remaining sections can be read without understanding the others.

8 Disk Quotas in AFS

Regular quotas in UNIX are done on a per-user basis. A quota on an NFS file system is generally something like, “User a is allowed to store b blocks of data on disk c.” Although this worked fine in the days when machines had few disks and few users, it doesn’t work well at all for shared space^{8}. 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.

athena% fs listquota /afs/athena.mit.edu/contrib/sipb
Volume Name            Quota    Used    % Used   Partition
contrib.sipb.readonly   90000   81336       90%<<       88%     <<WARNING

The above shows that the volume contrib.sipb.readonly has a ninety megabyte quota and has 81 megabytes worth of stuff in it. Notice information given was about contrib.sipb.readonly instead of contrib.sipb. This is because /afs/athena.mit.edu/contrib/sipb is a read-only mountpoint and a read-only copy of the contrib.sipb volume exists. If a read-only copy of this volume did not exist, then fs would have given us information about the read-write volume even though this is a read-only mountpoint.

9 Backup and Read-only Volumes

There are three types of volumes: read-write, read-only, and backup. A read-write is a regular volume that can be read and written—just as the name implies. A read-only volume cannot be modified. Read-only volumes have special properties. The most important one 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 you make a backup of a volume, 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!

8Actually, at Athena, we do have group quotas in NFS. A group quota would say something like “Users in group a are allowed to store b blocks of data on disk c.” This works better than regular user quotas, but it still has its share of problems.

10 Useful Arguments to fs, vos, and bos

In addition the the fs and pts commands that we have seen so far, there are two other commands: vos and bos. These commands are primarily of interest to system administrators, but they do have a few functions of interest to general users. The vos and bos commands are in the afsuser locker. To use them, you should first add afsuser. The vos command is used to manipulate volumes. The bos command is used for the overall maintenance of the cell.

Most of the times you use the fs command, you will be looking at mountpoints or reading or editing access control lists. There are a few other options that can occasionally be useful, however.

fs checkservers, abbreviated fs checks, tells the workstation to check all the AFS servers it knows about and report which ones are down. This command can be useful for debugging and can also be useful to help a workstation notice when a server has come back up again after going down. If AFS thinks that a server is down and you believe the contrary, you may wish to try the fs checks command. AFS would tell you that a server is down by printing a message like

Dec  4 21:52:03 soup vmunix: afs: Lost contact with file
server 18.72.1.52 in cell testers.athena.mit.edu

in your console window.

fs checkbackups, abbreviated fs checkb tells the workstation to invalidate its idea of when a read-only volume has last been updated. Read-only volumes get updated by being copied from their corresponding read-write volumes. This process is called releasing a volume. It usually takes the workstation about an hour to notice when a read-only volume has been changed. If you know that a volume has just been updated, you can use the fs checkb command to force the workstation to see the new version of the volume.

In addition, there are a few vos and bos commands that can be useful to general users. Most options to vos and bos are useful only to system administrators. These, however, are useful to everyone:

vos examine, formerly called vos volinfo is used to find out general information about a volume. This information includes the volume identification number of the volume itself and 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. The last backup time and the server name are perhaps the most useful things that vos examine can give.

For example, suppose I wanted to know when the sipb volume was last backed up. First, I would find out what the name of the volume is:

athena% fs lsm /mit/sipb
'/mit/sipb' is a symbolic link, leading to a mount point for
volume '#contrib.sipb'

The volume is called contrib.sipb. The # at the beginning of the volume name tells us that this is a read-only mountpoint. Let’s look at the volume information.

athena% vos examine contrib.sipb
_____________________________________________
contrib.sipb                      536871090 RW      85438 K  On-line
ARTEMIS.MIT.EDU /vicepe
Parent 536871090  Clone 536876390  Backup 536871092
MaxQuota      90000 K
Creation Wed Apr 19 22:09:01 1989
Last Update Sun Oct 28 15:12:32 1990
        readWriteID 536871090   valid
        readOnlyID  536876390   valid
        backUpID    536871092   valid
number of sites -> 2
    server ARTEMIS.MIT.EDU partition /vicepe RW Site
    server ARTEMIS.MIT.EDU partition /vicepe RO Site
_____________________________________________

Gee. When I look at this, the first line shows that this is information about the read-write volume:

contrib.sipb                      536871090 RW      85438 K  On-line

Maybe I should have looked at the backup volume:

athena% vos examine contrib.sipb.backup
_____________________________________________
contrib.sipb.backup               536871092 BK      85438 K  On-line
ARTEMIS.MIT.EDU /vicepe
Parent 536871090  Clone 536876390  Backup 536871092
MaxQuota      90000 K
Creation Sun Oct 28 21:56:43 1990
Last Update Sun Oct 28 21:56:43 1990
readWriteID 536871090   valid
readOnlyID  536876390   valid
backUpID    536871092   valid
number of sites -> 2
    server ARTEMIS.MIT.EDU partition /vicepe RW Site
    server ARTEMIS.MIT.EDU partition /vicepe RO Site
_____________________________________________

Much better. This volume was created on Sunday October 28, 1990 at 9:56:43 p.m. The creation time of the backup volume corresponds to the time that the volume was last backed up. This also tells me that the volume is on the server ARTEMIS.MIT.EDU. Although at the time of this writing the contrib.sipb volume happened to have its read-only and read-write copies on the same machine, this is not generally the case.

bos status is used to check the status of a specific AFS server. You probably won’t use this command very often if at all. It is useful, however, to diagnose problems. It could be useful to you if you want more specific information after you get a “lost contact with server” message on your workstation.

11 System Type

Since AFS is designed to look the same on different kinds of machines, the special string @sys, when it appears at the end of a component of a filename^{9}, has a different meaning on each machine/operating system pair. When the system parses a pathname, it automatically replaces the string “@sys” with a string that is of the form machine-type operating-system. For example, on a IBM RT running AOS 4.3 (as Athena RT’s do), @sys has the value rt aos4. Thus, a file called whoami.rt aos4 could be referenced as whoami.@sys on an RT. For example:

9Filename components are the parts of filenames that are separated by slashes.

athena% machtype
rt
athena% cat > whoami.rt_aos4
Hello.  I'm an RT running AOS4.3
athena% cat whoami.@sys
Hello.  I'm an RT running AOS4.3
athena% cat whoami.rt_aos4
Hello.  I'm an RT running AOS4.3

At the time of the writing of this document, there were three @sys names in use at Athena: rt aos4 for the RT, vax bsd43 for the vax, and pmax ul3 for the pmax (DECstation). A list of known values for @sys on Athena can be found in the file /afs/athena/service/systypes. If you want to find out what the value for @sys is on your machine, you can type the command fs

sysname.

One use for @sys would be for names of directories to contain binary files. Currently, there is some disagreement over what convention should be used for this. Many lockers use @sys itself for the name of this directory. Others use things such as bin/@sys, bin.@sys, or bin as a symbolic link to .bin/@sys. Since the convention has not been fully established, be aware that different people will do this in different ways.

12 AFS Cell Organization

This section discusses the way the athena.mit.edu AFS cell is laid out. It is more advanced and assumes deeper knowledge of the system than other sections do. Skipping this section will not make it more difficult to understand other sections of this document.

There are no hard and fast rules about how a cell should be laid out, but considerable thought was put into the athena.mit.edu cell, so it can be taken as an example. In addition, there are some conventions that many cells follow.

Before the cell layout can be discussed, more background information must be covered.

12.1 More About AFS Volumes

Near the beginning of this document (Section 2), the term AFS volume was defined as follows: An AFS volume is a collection of files and directories that are grouped together as one unit. A volume can be backed up, renamed, moved from one server to another, replicated, created, or destroyed as a unit. It is also the entity upon which a disk quota is enforced.

Volumes, like files, have their own names. Volume names are allowed to contain alpha-numeric characters, periods, hyphens, and underscore characters. All other characters are illegal. There are certain conventions imposed upon volume names. AFS itself imposes some of these conventions. AFS will not let a user give a volume a name that ends with .backup or .readonly since it reserves these for its own use.

When you look at /afs on any machine that runs AFS, you are looking at a volume called root.afs^{10}. By convention, the volume that contains the top level directory of a given AFS cell is called root.cell. These concepts are discussed in more detail later in this section of this document.

12.2 AFS Volume Mountpoints

AFS is mounted on a UNIX workstation in very much the same way as NFS file systems or local disks are mounted. The usual configuration of a workstation running AFS is to have one regular UNIX mountpoint into AFS^{11}. This mountpoint will be for one volume in one cell, the workstation’s local cell. Usually the volume that is mounted is called root.afs, but this can be overridden. From there on down, other volumes must be “mounted” within AFS. These mountpoints are usually referred to as AFS mountpoints and are distinct from UNIX mountpoints. They are really more like symbolic links as all they consist of is the name of the cell and volume that is being mounted. AFS mountpoints can be created only in AFS. In addition to the ordinary access required to create or delete any file (insert or delete), a user must have administer access to a directory in order to create or delete an AFS volume there. The commands fs mkmount and fs rmmount are used to create and delete AFS mountpoints.

12.3 Cell Layout

Now we are ready to discuss the actual layout of volumes in the athena.mit.edu AFS cell. In each cell, there exists a volume called root.afs. This volume consists entirely of AFS mountpoints to the top level volumes of other cells. Each file in root.afs (which can be found under /afs) is the top level directory for the AFS cell of the same name. To look under the athena.mit.edu cell, you can look under the directory /afs/athena.mit.edu^{12}. The directory /afs/athena.mit.edu is an AFS mountpoint to the volume root.cell in the cell athena.mit.edu. This is written all together as athena.mit.edu:root.cell. If you examine this directory, you can see that. AFS mountpoints can be inspected with the command fs lsmount, or fs lsm for short.

athena% fs lsm /afs/athena.mit.edu
'/afs/athena.mit.edu' is a mount point for volume '#athena.mit.edu:root.cell'

10Actually, it is possible to start AFS so that /afs is some volume other than root.afs, but root.afs is the default.

11Actually, this is currently the only way to configure a workstation, but that could change at any time.

12We also have /afs/athena set up as a symbolic link to save typing.

The # at the beginning of the name means that this is a read-only mountpoint. For local cells, in addition to an /afs/⟨cellname⟩ mountpoint, there is often a directory called /afs/.⟨cellname⟩ that is a read-write mountpoint to the cell ⟨cellname⟩. If the volume name started with %, it would be a read-write mountpoint. For example:

athena% % fs lsm /afs/.athena.mit.edu
'/afs/.athena.mit.edu' is a mount point for volume '%athena.mit.edu:root.cell'

The behavior of read-only versus read-write mountpoints is slightly counterintuitive. As you traverse the file system to arrive at a given volume, if any mountpoint in the path is read-write, a volume mountpoint will get you the read-write copy of a volume. Thus, even though both /afs/.athena/project and /afs/athena/project are read-only mountpoints to the same volume, of the two pathnames, you could modify files under only the directory /afs/.athena/project since /afs/.athena is the read-write mountpoint. If you didn’t understand this paragraph, forget it.

Looking under /afs/athena.mit.edu, we can see a number of directories. These are each volume mountpoints themselves and correspond to categorical divisions of the athena.mit.edu cell.

athena% ls /afs/athena.mit.edu
activity  astaff    contrib   course    project   service   system    user

In most cases, the directory names tell what is under them. The directory activity contains lockers for activities. The directory astaff contains more divisions and is used by the staff of Project Athena. The directory contrib consists of directories for public use that are contributed by various groups. The consult, sipb, and watchmaker lockers are all under /afs/athena/contrib. The course directory contains course lockers. The project directory contains lockers for projects that are not officially supported by Athena. system contains system software. The directory user contains users’ home directories. The directory service is so named by convention. Most cells will have a service directory right below their top level. The service directory holds information that may be useful to someone trying to use the cell. The aklog program used for authentication to AFS is in this directory. Another interesting file there is /afs/athena.mit.edu/service/systypes which discusses the legal @sys values in the athena.mit.edu cell. The meaning of @sys is discussed in the System Type section (Section 11) of this document.

12.4 Volume Naming Conventions

If you probe around with fs lsmount, you may notice some patterns in volume names. Any pattern you notice is merely a convention. There is nothing magic about any of our choices. In the MIT cells, volume names generally have this format: category.specific.extension.extension.extension...

Volumes mounted under the cell’s top level directory often have only category names. For example:

athena% fs lsm /afs/athena.mit.edu/contrib
'/afs/athena.mit.edu/contrib is a mount point for volume '#contrib'

Most volumes don’t have any extensions in their names. In general the specific section of the name is the same as the name as the directory.

athena% fs lsm /afs/athena.mit.edu/contrib/sipb
'/afs/athena.mit.edu/contrib/sipb' is a mount point for volume '#contrib.sipb'

One extension in common use is .nb. This means that we do not want the volumes to get automatic daily backups.

athena% fs lsm /afs/athena.mit.edu/contrib/xpix
'/afs/athena.mit.edu/contrib/xpix' is a mount point for volume '#contrib.xpix.nb'

13 Shortcuts for Advanced Users

As was mentioned earlier, AFS files are always available from the workstation. That means that you often don’t have to attach AFS file systems to use them. You can use Hesiod to determine where an AFS file system really lives. For example, the xpix file system is currently located under

/afs/athena.mit.edu/contrib/xpix:
athena% hesinfo xpix filsys
AFS /afs/athena.mit.edu/contrib/xpix r /mit/xpix
athena% ls /afs/athena.mit.edu/contrib/xpix
RCS         bindecmips  decmips_30  ps2bin      src
README      binps2      lost+found  rt_aos4     vax_43
README.~1~  binrt       pictures    rt_r3       vax_bsd43
README~     binvax      pmax_ul3    rtbin       vaxbin

If you plan to use such shortcuts, there are a few things of which you should be aware. Attaching a file system does more than just make the file system available under /mit. It also authenticates you to AFS, and subscribes you to some Zephyr notifications about status of the AFS cell. In addition, some programs rely on pathnames to work correctly. A good rule of thumb would be to attach at least one AFS file system when you log in if you wish to use AFS. Also, if something isn’t working the way you think it should be, and you are referring to it directly under /afs, you may want to try reattaching the file system or making sure that its path within AFS has not changed.

If you really want to do everything yourself, you may want to learn to use the aklog command. The aklog command takes cells and path names as command line arguments and authenticates you to all cells necessary for you to have your rightful access to that cell or file. You can find out more about the aklog program by reading its manual page. Just type man aklog.

Feel free to explore under /afs/athena.mit.edu. Be aware that if you look under /afs, you will be looking at some cells that are in other parts of the country. Sometimes the speed of file access can be very low. If you’re patient, however, you can find a lot of interesting things under /afs. If you look under /afs/andrew.cmu.edu/usr, you can find the home directories of students at Carnegie Mellon University!

14 Where to Go For More Information

The fs and pts commands both have built-in help. Typing fs help or pts help will give you a lot of information about various subcommands of each. Most of this information will be hard to understand at first but can be very useful once you get the hang of what is going on. The fs and pts commands also have manual pages. Unfortunately, the manual page for pts is not currently installed. You can get more information about fs, however, by typing man fs from the Athena prompt. In addition, there are two more commands: vos and bos that are generally of use only to administrators. There are some useful things that a normal user can do, however, such as checking the status of various file servers. You are encouraged to experiment. There is nothing that you can “break” by playing with these commands. Anything dangerous requires special privileges to use.

If you find bugs in AFS software, you can report them with the sendbug command just as you would with any other bug you would encounter on Athena. Have fun!

15 Credits

This document was written by E. Jay Berkenbilt. I would like to thank the people who helped me by reading over this document in its several stages and who make helpful suggestions as I was working on it. I would also like to thank the SIPB as a whole for being patient while I procrastinated writing this. Please send comments about this document, including corrections and suggestions for

improvement, to bug-sipb@ATHENA.MIT.EDU.