\newcommand{\AFS}{{\em AFS}\/}

\section{\AFS: The Andrew Filesystem}

Any particular method for handling files of data is called a {\em
filesystem.\/} Athena currently uses \AFS, the {\em Andrew
Filesystem}\footnote{\AFS\ was developed at Carnegie Mellon's {\em
Project Andrew\/}, which is a large-scale distributed workstation
experiment similar to {\em Project Athena}, the predecessor of today's
{\em Athena.} It has since become a commercial package sold by {\em
Transarc Corporation.}}, as the filesystem for all user home
directories and most of the other lockers.

\AFS\ is a {\it distributed}\/ filesystem.  This means that the files
stored using \AFS\ are located on a remote server, so you can access
them from any Athena workstation.  In fact, the owner can make the
files available from any computer running \AFS\ in the whole world.

You don't have to attach \AFS\ filesystems\footnote{You might want to use
the {\tt attach} command for Athena file systems anyway -- this is discussed
later.}; they are always available from the workstation under the directory
{\em /afs}.  Another major
difference between \AFS\ and other distributed filesystems 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, files and directory structures are cached locally to
minimize network traffic to the server.  This makes access to \AFS\
files very fast after the first time a file is read.

\subsection{\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 to provide you with some important background
for when you use \AFS:

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

\item{\bf 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.  The process of telling \AFS\ who are you is called {\em
authentication}. 

\item{\bf Group:} A group is a list of users.  Currently, it is
not possible for a group to contain other groups.

\item{\bf Cell:} An \AFS\ cell is essentially a domain
of authority.  It is currently 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.  A cell is also a domain of
authentication.  If you are the user {\em qjb}\/ in the {\it
athena.mit.edu}\/ cell, you may not have any access at all to
files belonging to a user named {\em qjb}\/ in the {\it
andrew.cmu.edu}\/ cell.  Likewise, someone who has
administrative capabilities in the {\em sipb.mit.edu}\/ cell may
not be able to touch the {\em athena.mit.edu}\/ cell.

\item{\bf 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 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 {\em potato}\/
is allowed to create files in this directory.  The user {\it
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 later in this document.
\end{description}

\subsection{How do I use \AFS?}

In general, you won't even notice whether files you are using
come from \AFS\ or not.
The time when it really does make a difference, however, is when
you want to change file protections, and this is critical since
your Athena home directory is in \AFS\ space.

If you wish to list or change protections, you will need to become
somewhat familiar with the program {\tt fs}.  This program 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 {\bf
File Protection}\/ section of this document.

The {\tt fs} command has a built-in help feature.  Typing {\tt
fs help} will give you a lot of information on how to use
various subcommands.  All the commands that you will probably
want to use, though, are described here.

\subsection{Authenticating to \AFS}

Before \AFS\ can know who you are, you have to be {\em
authenticated}\/ to the cell.  Authentication is just the name
given to confirming your identity.  There are several ways to
authenticate to \AFS.  The most common way will be through the
{\tt attach} command.  If you attach a filesystem that is in
\AFS, you will be authenticated automatically to it.  Should you
have to reauthenticate for some reason, you can just reattach
whatever it is that you are trying to use.

{\tt attach} authenticates to \AFS\ by using a program called
{\tt aklog}.  Generally, typing {\tt aklog}
with no arguments will reauthenticate you to whatever you are
using.  To be safe, however, you can specify the path of the
file you need to reach.  For example, if you are working in the
{\em potato}\/ locker, you can type {\tt aklog
/mit/potato} to reauthenticate.

\subsection{File protections under \AFS}

\AFS\ offers considerably more flexibility in directory protections
than regular UNIX.  Unfortunately, though, protections currently can
be set on files only in a limited way.  Protections in \AFS\ are
enforced with access control lists instead of with bit fields as
in regular UNIX.  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.

There are seven types of access that can be granted:
\begin{description}
\item{\bf Read (r):} Read access on a directory implies
permission to read the contents of all the files in that directory.
It has no implications about access to subdirectories.
\item{\bf 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. 
{\bf If you do not have lookup access to a directory, no other form
of access can be used.}
\item{\bf 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{\bf 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{\bf 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{\bf 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 applications programmers.
\item{\bf 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, and like all other types, is useless without lookup
access.  Administer access, contrary to some people's intuition,
cannot be ``forced'' onto subdirectories.  It only applies to
the directory on which it is set, not that directory's subdirectories.
\end{description}

In addition, the {\em user}\/ portion of a files UNIX mode bits
(described in the {\bf File Protections}\/ section of this document)
apply to all users, not just the owner of a file.  That means that if
a file's {\em 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 {\em 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 {\it UNIX group}\/ of the
file are currently ignored in \AFS\footnote{Well, actually, the
{\em UNIX group}\/ field and {\em group}\/ mode bits are used in
a limited way for {\it setgid}\/ executables, but this is beyond
the scope of this document.}.  If you didn't understand that,
ignore it.

The owner of a volume has automatic administer access to all
directories in the volume.  The owner of a directory has
automatic administer rights to that directory.  

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

Other groups can be one of two types: {\em system}\/ groups or {\it
user}\/ groups.  System groups have names that start with {\it
system:}.  They are controlled by the system administrators.
User groups start with {\em $<$user$>$:}, where {\em $<$user$>$}\/ is
the name of the user who created 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 and the operations they are allowed to perform.  To
find out what the access control list on a directory is, you
can use the command {\tt fs listacl <directory>} where {\it
$<$directory$>$} is the name of the directory you are interested in.
Note that {\tt fs la} is short for {\tt fs listacl}.  

\begin{flushleft}
For example:
\begin{verbatim}
athena% attach sipb
sipb: AFS mounted /afs/sipb.mit.edu/project/sipb on /mit/sipb (read-only)
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 {\it
system:gsipbbin}\/ have full access to {\em /mit/sipb} and all other
users have read and lookup access only.

\begin{flushleft}
Here is another example:
\begin{verbatim}
athena% attach qjb
qjb: AFS mounted /afs/sipb.mit.edu/user/qjb on /mit/qjb (read-write)
athena% fs la /mit/qjb
Access list for /mit/qjb is
Normal rights:
  qjb:plorq rla
  qjb:all rlidwka
  system:anyuser rl
\end{verbatim}
\end{flushleft}

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

\subsection{Where to go for more}

The SIPB also publishes a guide called {\bf Inessential AFS}.
This document contains everything you see here and some
additional information about changing access control list,
quotas, and other \AFS\ programs.  Good luck!





