%
% $Id: afs.tex,v 1.5 91/05/11 22:38:52 jik Exp $
% $Source: /afs/sipb.mit.edu/project/doc/afs/RCS/afs.tex,v $
% $Author: jik $
%
% Version 1 of Inessential AFS
%
\documentstyle[11pt,sipbdoc]{article}
\raggedbottom
\setlength{\topmargin}{.5in}
\setlength{\headsep}{0in}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8in}
\setlength{\parskip}{2ex}
\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}
\setlength{\parindent}{2em}
\setlength{\unitlength}{4pt}
\begin{document}

\newcommand{\AFS}{\product{AFS}}

\title{Inessential AFS \\
Version 1.1}
\author{Emanuel Jay Berkenbilt \\
Student Information Processing Board}
\date{January 19, 1991}

\maketitle
\pagenumbering{roman}
\thispagestyle{empty}
\tableofcontents
\newpage

\pagenumbering{arabic}
\setcounter{page}{1}

%
% If this is Inessential AFS, use the first set of definitions;
% otherwise, use the second.
%

\newcommand{\inessafs}{this document}
\newcommand{\inessguide}{\docname{An Inessential Guide to Athena}, 
	available from the SIPB}

%\newcommand{\inessafs}{\docname{Inessential AFS}, available from the SIPB}
%\newcommand{\inessguide}{this document}

\section{What is \AFS\/?}

\AFS, the \product{Andrew File System\/}\footnote{\AFS\/ and
\product{Andrew File System\/} are trademarks of Transarc,
Inc.}, is a \term{file system\/}
originally developed at Carnegie Mellon's \product{Project
Andrew\/}\footnote{\product{Project Andrew\/} is a large-scale
distributed workstation experiment similar to \product{Project
Athena}.}.  \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 \inessguide.

Like \product{NFS}, \AFS\/ is a network file system, or, as
it is usually called, a \term{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
\pathname{/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
\term{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.

\section{\AFS\/ Volume?  Why do I care how loud my files are?} \label{terms}

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\/:

\begin{description}
\item{\term{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.

\item{\term{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.

\item{\term{Group\/}:} A group is a list of users\footnote{\AFS\/
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.}.

\item{\term{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.  

\item{\term{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
\user_or_group{potato\/} is allowed to create files in this
directory.  The user \user_or_group{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
\ref{fileprot}) in \inessafs.
\end{description}

\section{How Do I Use \AFS\/?}

In general, you use \AFS\/ in the same way you use any other
network file system at Athena: just \command{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
\filesystem{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
\pathname{/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
\term{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
\command{attach\/} command.  Should you have to reauthenticate for some
reason, you can just reattach whatever it is that you are trying
to use.

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

\section{File Protections Under \AFS} \label{fileprot}

\AFS\/ offers considerably more flexibility in directory protections
than regular UNIX\footnote{UNIX is a trademark of AT\&T.}.  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 \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 \inessguide.

The \command{fs\/} command has a built-in help feature.  Typing
\command{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 \command{fs help
subcommand\/}.  All the commands that you will probably want to
use, though, are described in \inessafs.

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.

\begin{description}
\item{\term{Read (r)\/}:} Read access on a directory implies
permission to read the contents of all the files in a directory.
\item{\term{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 ({\em 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.
\item{\term{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.
\item{\term{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.
\item{\term{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.
\item{\term{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.
\item{\term{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.
\end{description}

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 \term{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
{\em read}, {\em write}, and {\em execute\/}
access, then access to the file is determined completely by the
\AFS\/ access control list on the directory.  The {\em group\/}
and {\em other\/} bits as well as the UNIX group of the
file are currently ignored in {\AFS\/}\footnote{Well, actually, the
UNIX group field and group mode bits are used in
a limited way for \term{setgid\/} executables, but this is beyond
the scope of this document.}.  If you didn't understand that,
ignore it.

The owner of a {\em 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 \command{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: \user_or_group{system:anyuser\/} and
\user_or_group{system:authuser}.  The group
\user_or_group{system:anyuser\/} includes all users whether or not
they are known to the cell.  The group \user_or_group{system:authuser\/}
includes any user who is registered with the cell and has been
authenticated ({\em i.e.}, anyone who has told
\AFS\/ who they are)\footnote{These groups don't really include
people, they just behave as if they do.  If you don't understand
this footnote, forget it.}.

Other groups can be one of two types: \term{system\/} groups or
\term{user\/} groups.  System groups have names that start with
\user_or_group{system:}.  They are controlled by the system administrators
and by regular users through \product{Moira}.  (See the
\product{Moira\/} section of \inessguide.)  User groups start with
\user_or_group{$\langle$user$\rangle$:}, where
\user_or_group{$\langle$user$\rangle$} 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 \command{fs listacl
$\langle$\pathname{directory\/}$\rangle$} where
\pathname{$\langle$directory$\rangle$} is the name 
of the directory you are interested in.  Note that \command{fs
la\/} is short for \command{fs listacl}.

\begin{flushleft}
For example:
\begin{verbatim}
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
\end{verbatim}
\end{flushleft}

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

\begin{flushleft}
Here is another example:
\begin{verbatim}
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
\end{verbatim}
\end{flushleft}

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

\section{Changing Protections in \AFS}

To set access control lists, you use the command \command{fs
setacl}, which may be abbreviated \command{fs sa}.  The format
of this command is \command{fs sa
$\langle$\pathname{directory\/}$\rangle$
\user_or_group{$\langle$user or group$\rangle$}
$\langle$\accesstype{access\/}$\rangle$} where
\user_or_group{$\langle$user or group$\rangle$}
is the user or group to which you wish to give access and
\accesstype{$\langle$access$\rangle$} 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:
\accesstype{read}, which means \accesstype{r\/} and
\accesstype{l\/} access; \accesstype{write}, which means
\accesstype{r, l, i, d, w}, and \accesstype{k\/} access;
\accesstype{all}, which means all kinds of access
(\accesstype{r, l, i, d, w, k, {\rm and} a\/}; and
\accesstype{none}, which means no access.

\newpage
\begin{flushleft}
Here is an example of setting an access control list.

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

\begin{verbatim}
athena% fs la test
Access list for test is
Normal rights:
  qjb rlidwka
\end{verbatim}

Now, let's give \user_or_group{testuser\/} write access to the directory
and check to make sure that it worked.

\begin{verbatim}
athena% fs sa test testuser write
athena% fs la test
Access list for test is
Normal rights:
  qjb rlidwka
  testuser rlidwk
\end{verbatim}

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

\begin{verbatim}
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
\end{verbatim}

Now, let's remove access from \user_or_group{testuser}.

\begin{verbatim}
athena% fs sa test testuser none
athena% fs la test
Access list for test is
Normal rights:
  system:authuser rl
  qjb rlidwka
\end{verbatim}
\end{flushleft}

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 \term{negative acls}.  Negative acls
provide a way to {\em 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 \command{-negative\/} commandline flag to the
\command{fs sa\/} command.  Setting a negative acl does not
cancel a positive acl.  That is, the command \command{fs sa
\user_or_group{testuser\/} none\/} is {\em not\/} the same as
\command{fs sa \user_or_group{testuser\/} all -negative\/}. If
you don't understand this paragraph, forget it.

\section{\AFS\/ Groups}

At Project Athena, the \AFS\/ system-controlled group called
\user_or_group{system:$\langle$groupname$\rangle$} corresponds to
the \product{Moira\/} group called
\user_or_group{$\langle$groupname$\rangle$}.  The \product{Moira\/}
section of \inessguide, 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
\user_or_group{system:$\langle$user$\rangle$} where
\user_or_group{$\langle$user$\rangle$} is your username.  

As you use the command \command{fs\/} to manipulate file
protections, you use the command \command{pts\/} to perform
operations on users and groups.  You can create your own groups
and add members to them with the commands \command{pts
creategroup\/} and \command{pts add}.  You can remove users from
groups with \command{pts remove\/} and delete groups with
\command{pts delete}.  You can get the members of a group with
\command{pts membership\/} and find out information about a group
with \command{pts examine}.

\begin{flushleft}

For example, suppose I, the user \user_or_group{qjb}, create a group
called \user_or_group{qjb:potato}\footnote{I would probably do this
because I happen to like potatoes.}.  I will first check to see
whether the group exists.  Then I will create it and add some
people to it.

\begin{verbatim}
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
\end{verbatim}

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

\begin{verbatim}
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
\end{verbatim}

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

\begin{verbatim}
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
\end{verbatim}
\end{flushleft}

You can use \command{pts membership\/} to get the members of a
system-controlled list as well as of a user-controlled list.
Even though \product{Moira\/} can give you this information as
well, it is sometimes faster to get the information from \AFS.

Note that unlike \product{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 \command{aklog\/} program discussed in the section on
shortcuts for advanced users (Section \ref{shortcuts}). 


\section{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.  


\section{Disk Quotas in \AFS}

Regular quotas in UNIX are done on a per-user basis.  A quota on
an \product{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\footnote{Actually, at Athena, we do have group quotas in
\product{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.}. 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 \command{fs
listquota\/} command.

\begin{verbatim}
athena% fs listquota /afs/athena.mit.edu/contrib/sipb
Volume Name            Quota    Used    % Used   Partition
contrib.sipb.readonly   90000   81336       90%<<       88%     <<WARNING
\end{verbatim}

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


\section{Backup and Read-only Volumes} \label{backupro}

There are three types of volumes: \term{read-write},
\term{read-only}, and \term{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 {\em actually
shares the same disk space as the read-write volume}.  These
volumes are often known as \term{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!


\section{Useful Arguments to \command{fs}, \command{vos}, and
\command{bos\/}}

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

Most of the times you use the \command{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.

\begin{description}
\item{\command{fs checkservers},} abbreviated \command{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 \command{fs checks\/} command.
\AFS\/ would tell you that a server is down by printing a
message like 
\begin{verbatim}
Dec  4 21:52:03 soup vmunix: afs: Lost contact with file
server 18.72.1.52 in cell testers.athena.mit.edu 
\end{verbatim}
in your console window.

\item{\command{fs checkbackups},} abbreviated \command{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 \term{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 \command{fs checkb\/} command to force
the workstation to see the new version of the volume.
\end{description}

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

\begin{description}
\item{\command{vos examine},} formerly called \command{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 \command{vos examine\/}
can give.

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

\begin{verbatim}
athena% fs lsm /mit/sipb
'/mit/sipb' is a symbolic link, leading to a mount point for
volume '#contrib.sipb'
\end{verbatim}

The volume is called \volumename{contrib.sipb\/}.  The
\volumename{\#} at the beginning of the volume name tells us
that this is a read-only mountpoint.  Let's look at the volume
information.

\begin{verbatim}
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 
_____________________________________________
\end{verbatim}

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

\newpage
\begin{verbatim}
contrib.sipb                      536871090 RW      85438 K  On-line
\end{verbatim}

Maybe I should have looked at the backup volume:

\begin{verbatim}
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 
_____________________________________________
\end{verbatim}

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
\volumename{contrib.sipb\/} volume happened to have its read-only
and read-write copies on the same machine, this is not generally
the case.


\item{\command{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. 
\end{description}


\section{System Type} \label{systype}

Since \AFS\/ is designed to look the same on different kinds of
machines, the special string \pathname{@sys}, when it appears at
the end of a component of a filename\footnote{Filename
components are the parts of filenames that are separated by
slashes.}, has a different meaning on each machine/operating
system pair.  When the system parses a pathname, it
automatically replaces the string ``\pathname{@sys\/}'' with a
string that is of the form
\term{machine-type\_operating-system}.  For example, on a IBM RT
running AOS 4.3 (as Athena RT's do), \pathname{@sys\/} has the
value
\pathname{rt\_aos4}.  Thus, a file called
\pathname{whoami.rt\_aos4\/} could be 
referenced as \pathname{whoami.@sys\/} on an RT.  For example:

\begin{verbatim}
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
\end{verbatim}

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

One use for \pathname{@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
\pathname{@sys\/} itself for the name of this directory.  Others use
things such as \pathname{bin/@sys}, \pathname{bin.@sys}, or
\pathname{bin\/} as a 
symbolic link to \pathname{.bin/@sys}.  Since the convention has
not been fully established, be aware that different people will
do this in different ways.


\section{\AFS\/ Cell Organization}

This section discusses the way the \cellname{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
\cellname{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.


\subsection{More About \AFS\/ Volumes}

Near the beginning of this document (Section \ref{terms}), the
term \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 \volumename{.backup\/} or
\volumename{.readonly\/} since it reserves these for its own use.

When you look at \pathname{/afs\/} on any machine that runs \AFS, you
are looking at a volume called \volumename{root.afs}\footnote{Actually,
it is possible to start \AFS\/ so that \pathname{/afs\/} is some volume other
than \volumename{root.afs}, but \volumename{root.afs\/} is the default.}.  By
convention, the volume that contains the top level directory of
a given \AFS\/ cell is called \volumename{root.cell}.  These concepts
are discussed in more detail later in this section of this document.


\subsection{\AFS\/ Volume Mountpoints}

\AFS\/ is mounted on a UNIX workstation in very much the same way
as \product{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\/}\footnote{Actually, this is currently the only way to
configure a workstation, but that could change at any time.}.
This mountpoint will be for one volume in one cell, the
workstation's \term{local cell}.  Usually the volume that is
mounted is called \volumename{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 \term{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
\command{fs mkmount\/} and
\command{fs rmmount\/} are used to create and delete \AFS\/
mountpoints. 


\subsection{Cell Layout}

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

\begin{verbatim}
athena% fs lsm /afs/athena.mit.edu
'/afs/athena.mit.edu' is a mount point for volume '#athena.mit.edu:root.cell'
\end{verbatim}

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

\begin{verbatim}
athena% % fs lsm /afs/.athena.mit.edu
'/afs/.athena.mit.edu' is a mount point for volume '%athena.mit.edu:root.cell'
\end{verbatim}

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 {\em 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 \pathname{/afs/.athena/project\/} and
\pathname{/afs/athena/project\/} are read-only
mountpoints to the same volume, of the two pathnames, you could
modify files under only the directory
\pathname{/afs/.athena/project\/} since
\pathname{/afs/.athena\/} 
is the read-write mountpoint.  If you didn't understand this
paragraph, forget it.

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

\begin{verbatim}
athena% ls /afs/athena.mit.edu
activity  astaff    contrib   course    project   service   system    user
\end{verbatim}

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

\subsection{Volume Naming Conventions}

If you probe around with \command{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:

\volumename{category.specific.extension.extension.extension...}

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

\begin{verbatim}
athena% fs lsm /afs/athena.mit.edu/contrib
'/afs/athena.mit.edu/contrib is a mount point for volume '#contrib'
\end{verbatim}

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.

\begin{verbatim}
athena% fs lsm /afs/athena.mit.edu/contrib/sipb
'/afs/athena.mit.edu/contrib/sipb' is a mount point for volume '#contrib.sipb'
\end{verbatim}

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

\begin{verbatim}
athena% fs lsm /afs/athena.mit.edu/contrib/xpix
'/afs/athena.mit.edu/contrib/xpix' is a mount point for volume '#contrib.xpix.nb'
\end{verbatim}


\section{Shortcuts for Advanced Users} \label{shortcuts}

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 \product{Hesiod\/}
to determine where an \AFS\/ file system really lives.  For
example, the \filesystem{xpix} file system is currently
located under \pathname{/afs/athena.mit.edu/contrib/xpix\/}:
\begin{verbatim}
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
\end{verbatim}

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 \pathname{/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
\pathname{/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 \command{aklog\/} command.  The \command{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 \command{aklog\/} program by reading its manual page.
Just type \command{man aklog}.

Feel free to explore under \pathname{/afs/athena.mit.edu}.  Be
aware that if you look under \pathname{/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
\pathname{/afs}.  If you look under
\pathname{/afs/andrew.cmu.edu/usr}, you can find the home
directories of students at Carnegie Mellon University!


\section{Where to Go For More Information}

The \command{fs\/} and \command{pts\/} commands both have
built-in help.  Typing \command{fs help\/} or \command{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 \command{fs\/} and \command{pts\/}
commands also have manual pages.  Unfortunately, the manual page
for \command{pts\/} is not currently installed.  You can get
more information about \command{fs\/}, however, by typing
\command{man fs\/} from the Athena prompt.  In addition, there
are two more commands: \command{vos\/} and \command{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
\command{sendbug\/} command just as you would with any other bug
you would encounter on Athena.  Have fun!


\section{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
\address{bug-sipb@ATHENA.MIT.EDU}.  


\end{document}
