% $Id: afs.tex,v 1.35 1994/11/30 20:00:15 sorokin Exp $
% $Source: /afs/sipb.mit.edu/project/doc/afs/RCS/afs.tex,v $
% $Author: sorokin $
%         
% Version 2.alpha of Inessential AFS
%

\documentstyle[11pt,sipbdoc]{article-sipb}
\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{\tpsetup} {		%% setup for titlepage & toc
   \def\thefootnote{\fnsymbol{footnote}} %% symbols as footnote marks
   \pagenumbering{roman}
   \def\footnoterule{}
}
\newcommand{\tpundo} {		%% undo for \tpsetup
   \def\thefootnote{\arabic{footnote}}   %% back to numbers as footnote marks
   \pagenumbering{arabic}
   \def\footnoterule
      {\kern -3pt \hrule width .4\columnwidth \kern 2.6pt }
}


\newcommand{\UFS}{\product{UFS}}
\newcommand{\NFS}{\product{NFS}}
\newcommand{\AFS}{\product{AFS}}
\newcommand{\UNIX}{\product{UNIX}}
\def\home{\hbox{\hspace{-3pt}\~\hss}}

\tpsetup

\title {
  \begin{center}
    \vspace{1.5in}
    \hspace*{1mm}\special{psfile=funky-owl.PS hoffset=-100}\hspace*{1mm}
    \vspace{2cm}
  \end{center}
  {\huge Inessential AFS\footnotemark[2]} \\
  Version 2.00}

\footnotetext[2]{Copyright \copyright\ 1992 Student Information
    Processing Board of the Massachusetts Institute of Technology}

\author{The Student Information Processing Board \\ \\
  Emanuel Jay Berkenbilt \\
  Barbara Christine Manganis \\
  Albert Dvornik}

\date{September 14, 1992}

\maketitle
\thispagestyle{empty}
\newpage

\setcounter{page}{1}
\tableofcontents
\newpage

\tpundo
\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 SIPB}
\newcommand{\inessQ}{\docname{Inessential Q},
	available from SIPB}

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

%%% BEGINNING OF TEXT %%%


\section{Filesystems: An Introduction}

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

\subsection{Why Should I Care About All This?}

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

\begin{itemize}
\item{let other people read your files}
\item{let {\em some} other people read {\em some} of your files, and not
the others}
\item{get to know the basics of how filesystems actually work}
\end{itemize}

\subsection{Carrying Your Files Around}

Many physical devices can store and retrieve files, from punched tape to
laser discs. They can be connected to the computer you're using in two
basic ways:

\term{Local} filesystems handle files that are stored directly
on the computer you are using. These files may be stored on a local
hard disk, also called a \term{hard drive}.  On Athena, local drives
are used to hold programs and data needed to recover from reboots,
temporary user data, and certain system programs that are accessed
very frequently. 

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

% Chad suggested we combine UFS and AFS into one section. I agree.

\section{UFS and NFS}  \label{ufsandnfs}

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

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

\NFS\ is a distributed filesystem. Its files are stored on fileservers;
in order to access a \term{locker} of files, you have to \term{mount} it
to your computer.  On Athena, all you have to do to mount a locker
is type \command{attach \argument{lockername}}.
For example, if you wanted to attach the \pathname{bitbucket}
locker, you would type:

\begin{verbatim}
athena% attach bitbucket 
\end{verbatim}

And Athena would respond with something like this:

\begin{verbatim}
attach: filesystem bitbucket (JASON.MIT.EDU:/u1/bitbucket) mounted
  on /mit/bitbucket (read-write)
\end{verbatim}

Now, you can access the files in the directory \pathname{/mit/bitbucket};
the computer will contact the fileserver where the locker
\pathname{bitbucket} is stored whenever it needs to read or write something.
You can find a more detailed description of the \command{attach} command
in the \term{manual page}\footnote{Manual pages for
  UNIX commands are displayed by \command{man \argument{command}}.
  For more information, see section \ref{manpages} of \inessafs.}
for that command.

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

\subsection{File and Directory Permissions in UFS and NFS}

File permissions regulate file access.  They allow you to control who
can read, write, or execute any files you may own.  File permissions
in \UFS\ and in \NFS\ are similar, and specified for each file and
directory.  The three basic permissions are:
\begin{description}
\item{\term{read (r)\/}:} Having read permission on a file
  grants the right to read the contents of the file.  Read
  permission on a directory implies the ability to list
  all the files in the directory.
\item{\term{write (w)\/}:} Write permission implies the ability
  to change the contents of the file (for a file) or create new
  files in the directory (for a directory).
\item{\term{execute (x)\/}:} Execute permission on files means
  the right to execute them, if they are programs.  (files that
  are not programs should not be given the execute permission.) For
  directories, execute permission allows you to enter the directory
  (i.e., \command{cd} into it), and to access any of its 
  files.\footnote{If you have ``r'' and not ``x'' on a directory
  you have permission to list the directory, but not to access
  its files.}
\end{description}

Under both \UFS\ and \NFS, permissions exist separately for
\usr_or_group{user},
\usr_or_group{group}, and \usr_or_group{others}.
\usr_or_group{User (u)} permissions apply to the owner of the file. 
\usr_or_group{Group (g)} permissions apply to all members of the group
associated with the file. Permissions for \usr_or_group{others (o)}
apply to anyone else.  The default owner of any file you create will
be you.  The group will be inherited from its parent directory.  More
information on the system (Moira) groups is available in the Moira section
of \inessguide.

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

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

\end{verbatim}
it would mean that the user \user{joeuser} has read and write
permissions on the file \argument{notes}, the members of the group
\usr_or_group{joepals} have only read permission, while everybody else
has none.  Note that the username \user{root} signifies the \term{superuser}.
%%     Superusers usually cannot fly, but %% BAD PUN
Anyone with the superuser privileges
implicitly has read and write permissions, as well as the ability to
change permissions,\footnote{The superuser can also change the
ownership of a file by using the \command{chown} command.  There are
also  several ``special'' permissions that haven't been listed here.
For more information, see the
\command{chown} and \command{chmod} manual pages.} on all the files
on the local disks.  This does not include files that have been mounted.

The permissions can be changed by using the \command{chmod} command.
Granting permissions is done by \command{chmod \usr_or_group{who}+\argument
{permissions}}, where \usr_or_group{who} is any combination of \command{u},
\command{g} and \command{o}, and \usr_or_group{permissions} any combination
of \command{r}, \command{w} and \command{x}.
Similarly, permissions are withdrawn by using \command{chmod
\usr_or_group{who}-\usr_or_group {permissions}}.  You can change the
group associated with a file by \command{chgrp \group{groupname} 
\argument{file(s)}}. For more information on the \command{chmod}
command, read the corresponding manual page.

\section{AFS} \label{afs}

\subsection{The NFS to AFS migration}

\AFS\ stands for {\em Andrew File System}. It is a distributed filesystem
like \NFS.  In the summer of 1992, all
user accounts on Athena were moved from \NFS\ to \AFS.  Many \NFS\
commands also work on \AFS; however, there are many important
differences between \AFS\ and \NFS.  You may also notice new subdirectories
in your home directory:
\pathname{OldFiles}, \pathname{Public}, and \pathname{Private}. 
The purpose of these new directories will be addressed in the next few
sections.

\subsection{File Permissions in AFS} \label{afsacls}

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

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

To change the the ACL for a file or directory, you can use
the \command{fs} command, mentioned in section \ref{fspts} of \inessafs.

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

It is also possible to give users ``negative permissions'' on a directory,
thus specifically denying them the corresponding rights.  Negative
permissions are stronger than the positive ones.  Their use is
described in more detail in section \ref{afsgroups} of \inessafs. 

Each directory has its own ACL.  Whenever you create a new directory,
it ``inherits'' the ACL of its parent.  You always have the administer
rights on the top-level directories in your locker (or any other AFS
volume\footnote{For more information on \AFS\ volumes, see section
\ref{afsvol} of \inessafs.} you own).  You cannot take this
right away from yourself.


\subsection{AFS Groups} \label{afsgroups}

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

You can create your own \term{user groups}, which will have names of
the form \group{user:groupname}, where \user{user} is your username,
and \group{groupname} is a name you choose for the the group.  For
instance, user \user{jis} could create group \group{jis:friends} for
his friends Jim, Mary and Bill, and another group \group{jis:6.001}
for his 6.001 classmates, Dave, Barbara and Tom.  Then he could, for
instance, give group
\group{jis:friends} read and lookup permissions on most of his directories
(\user{jis} trusts his friends).
Group \group{jis:6.001} could get read and lookup permissions on directories
\pathname{/mit/jis/scheme} and \pathname{/mit/jis/scheme/6.001}, and read,
lookup and insert on \pathname{/mit/jis/scheme/hacks}.  And so on.  For
some examples of how to create and manipulate groups, see \ref{fspts} of
\inessafs.

If you want to give permission to everyone in a group {\em except} someone,
you can exclude them using negative permissions, described in section
\ref{afsacls} of \inessafs.
Negative permissions deny rights to users or groups. They are stronger
than positive rights, so if \user{jis} gives a read permission to
\group{jis:6.001}, but denies it to Tom, who is a member of the group,
Tom will not be able to read the files.

\AFS\ groups also include \term{system groups.}
System groups have names of the form \group{\system:\discretionary{}{}{}
group\-name}. The group \group{\system:anyuser} includes any AFS user.
Giving read and lookup permissions to \group{\system:anyuser} will,
therefore, make the directory \term{world-readable:} anyone with
access to \AFS\ (literally around the globe!) will be able to read the files.
The group \group{\system:authuser} includes\footnote{These are
not real lists of users, but they behave as if they were.}
any user that has authenticated
themselves with \AFS\ locally\footnote{It does not include users whose
authentication originated outside of MIT (e.g., CMU).  Reciprocally,
for files at CMU, it doesn't include users from MIT...} (this includes
all Athena users).

Any other \AFS\ group \group{\system:groupname} corresponds to a Moira group
\group{groupname}. You cannot create Moira groups without assistance.
More information on Moira groups can be found in the Moira section
of \inessguide.


\section{AFS organization: Cells and Volumes} \label{afsvol}

The largest element in the \AFS\ structure is a \term{cell}.  A cell
constitutes a separate administrative domain of authority.  Each cell
keeps its own list of users, groups, and system administrators.  That
means that a user from one cell might not exist in another cell.  In
that case, [s]he will only be able to access the files in directories
that have the appropriate permission set to \group{\system:anyuser}.
An example of a cell is the \cellname{athena.mit.edu} cell (this is
the cell that contains Athena user home directories, along with course
lockers and most Athena software), or SIPB's own \cellname{sipb.mit.edu}
cell.

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

The whole multi-cell \AFS\ directory structure is accessible through the
directory \pathname{/afs}. The volume in \pathname{/afs} is named
\volumename{root.afs}.
The directory \pathname{/afs}
contains the mountpoints to the root volumes for each cell, which are
usually named \volumename{\argument{cellname}:root.cell}.
These volumes act like 
directories, and may in turn contain the mountpoints to other volumes.
Thus you can \command{cd} to \pathname{/afs/athena.mit.edu/user/a/u/autumn},
and be ``connected to'' the volume \volumename{user.autumn} in the cell
\cellname{athena.mit.edu}.  For the Athena cell, 
you can use just \pathname{/afs/athena/\dots}
instead of \pathname{/afs/athena.mit.edu/\dots} 
since the \volumename{root.afs} directory contains a symbolic link from
one to the other.  The same goes for other \address{.mit.edu} cells, too:
\pathname{/afs/sipb.mit.edu/\dots} and \pathname{/afs/sipb/\dots} are the
same.

Because of the way \AFS\ works, you do not have to explicitly attach any
volume or filesystem that is on \AFS\ in order to have access to it. All
you need, in order to access a file, is the pathname of the file.  For
example, if I wanted to get to the games locker, I could type
\command{cd \pathname{/afs/athena/contrib/games}}, without having to
do \command{attach games}.  However, this does not mean that you
shouldn't, in some circumstances, attach or add a volume.  For one
thing, attaching a volume subscribes you to some classes of Zephyr
messages, so you will be automatically notified if a portion of \AFS\
you are using is becoming unavailable (e.g., due to a server
shutdown).  Some programs will not work unless certain lockers are
attached.  Also, volumes that are in other cells (outside the \cellname{athena}
cell) will not recognize you or give you your proper permissions
unless you are authenticated to that cell (except for volumes where
the appropriate permissions are given to system:anyuser). To do this
you need to get tokens for the cell, which are analogous to separate
Kerberos tickets for individual \NFS\ fileservers.  Attaching or adding
a volume will automatically get you tokens (read the manual pages for
add and attach for more information).  Another way to get tokens is to
use the command
\command{aklog}, described later in this document.


\subsection{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 volume is a regular
volume that can be read and written---just as the name implies. A
read-write volume may have associated with it zero, one, or many
read-only volumes.  Read-only volumes cannot be modified by normal
users.  They have special properties, the most important of which is
that many copies of a read-only volume can exist at once.  If an \AFS\
mountpoint is read-only and a read-only volume exists with the right
name, \AFS\ just picks one read-only volume to read from.  If that
volume disappears or somehow becomes unreachable, \AFS\ will start using
another one without the user ever knowing the difference.  Backup
volumes are also special.  There can be only one backup volume for a
read-write volume.  Read-only volumes cannot have backup volumes.  In
other words, a backup volume can be associated only with a read-write
volume. A backup volume is a read-only copy of a read-write volume
that {\em actually shares the same disk space as the read-write
volume}.  These volumes are often known as
\term{clones}.  When a volume is backed up, that volume
initially takes a very small amount of space on disk.  As the
read-write volume and the backup volume get further out of
synchronization, data is actually copied.  The next time the volume is
backed up, the old copied data is destroyed.  That means that, once a
volume has been backed up once, subsequent backups of the volume may
actually reduce the total amount of disk spaced used!

\subsection{\pathname{OldFiles}} \label{oldfiles}

You should have a backup volume mountpoint in your home directory,
called \pathname{OldFiles}. As with the volumes in the directory 
\pathname{/afs}, this is not an actual directory. It is a mountpoint
for the volume \volumename{user.\user{username}.backup}, but for all intents
and purposes it behaves like a directory.  (Of course, it doesn't use up
your quota.)  All your files are backed up
a few times every week.  If you want to retrieve a file that you
have accidentally removed, all you have to do is cd to the appropriate
directory and use the command \command{cp}\footnote{Read the manual
pages.} to copy the file into your home directory.

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

\noindent
\command{fs mkmount \home/OldFiles user.user{username}.backup}

For more information about the command \command{fs}, see section
\ref{fspts} of \inessafs.

% {\em
% Needs to be rewritten, the end is confusing.
% }

\section{Disk Quotas}

Regular quotas in \UNIX\ are done on a per-user basis.  A quota on
the \NFS\ filesystem is generally something like
``User $a$ is allowed to store $b$ blocks of data on disk $c$.''
Although this 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, some \NFS\ filesystems on Athena
do have group quotas.
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 (see section \ref{fspts} of \inessafs).

You should note that the space your \pathname{OldFiles} backup volume
takes does not count against your user quota.

\section{AFS Commands} \label{fspts}

\subsection{Yeah, this is all neat, but....}

You may be wondering how you actually do all this neat stuff, like
change permissions and check quota and create groups. In many cases,
NFS commands will still work in AFS.  However, there are a few
commands that are different, and a few commands that have AFS
counterparts that may be easier or faster.

\subsection{fs}

The command \command{fs} is actually not a single command, but a whole
group of commands\footnote{Many AFS commands are of this type, i.e., a
suite of related commands rather than many distinct commands.} that
allow you to query the fileserver and set permissions.

One important command to know is \command{fs listquota} (abbreviated
\command{fs lq}). This returns the disk usage and quota for whatever
volume you happen to be in (if there are no arguments) or for whatever
volume you give it. For example,
\begin{verbatim}
athena% fs lq /afs/sipb/project/sipb
Volume Name            Quota    Used    % Used   Partition
project.sipb.readonly  110000  109849      100%<<       87%     <<WARNING
\end{verbatim}
This shows you the disk quota and the usage for the volume 
\term{volume.sipb.readonly}. Note that this is a readonly volume,
as described in section \ref{backupro}.

Two other commands are \command{fs setacl} (or \command{fs sa}), and
\command{fs listacl} (or \command{fs la}). These commands allow you
to change and list the permissions on any particular directory. For
example, suppose user \user{jis} wanted to make his \pathname{scheme}
directory world-readable. To find out what the current permissions on
the directory
are, he would do the following:
\begin{verbatim}
athena% fs la ~/scheme
Access list for /mit/jis/scheme is
Normal rights:
  system:expunge ld
  jis rlidwka
\end{verbatim}
This shows that \user{jis} has all permissions on his
\pathname{scheme} directory, while the group
\group{\system:\fixedname{expunge}}
(the magical little demons who clean out your deleted files every once
in a while) has list and delete permissions. Now, he wants give anyone
the ability to read his scheme directory. While he is at it, he wants
to give his trusted friend \user{srz} write permission on his scheme
directory.  He would type:
\begin{verbatim}
athena% fs sa ~/scheme system:anyuser read
athena% fs sa ~/scheme srz write
\end{verbatim}
Note that the syntax of the \command{setacl} command is 
\command{fs sa \argument{directory} \argument{who} \argument{permissions}}.
Note also that in this example we used the aliases \term{read} and
\term{write}.  In all there are four such aliases: \accesstype{read},
which is the same  \accesstype{r\/} and
\accesstype{l\/} access; \accesstype{write}, which expands to
\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 sets no access.

Now \user{jis} wants to see his new list of acls, so he types:
\begin{verbatim}
athena% fs la ~/scheme
Access list for /mit/jis/scheme is
Normal rights:
  system:expunge ld
  system:anyuser rl
  srz rlidwk
  jis rlidwka
\end{verbatim}
In addition to the \command{fs listacl} and \command{fs setacl} commands,
there are other \command{fs} command arguments which allow you to do 
everything from create mountpoints (see section \ref{oldfiles}) to 
query the servers.  For example:
\begin{description}
\item{\command{fs mkmount}, or \command{fs mkm}}: As mentioned
before, this command allows you to create a mountpoint,
such as the one used for \pathname{OldFiles}.
\item{\command{fs lsmount}, or \command{fs lsm}}: This lists
information about a mountpoint, most importantly the specific name
of the mounted volume. For example,
\command{fs lsm /afs/sipb} gives the following: 
\begin{verbatim}
'/mit/sipb' is a symbolic link, leading to a mount point for volume
  '#project.sipb'
\end{verbatim}

\item{\command{fs whereis}}: This command tells you on which server a
file or a directory is located. You can use it in the form 
\command{fs whereis \home} to find out on which server your home
directory is stored.
\item{\command{fs checkservers}, or \command{fs checks}}:  This command will
tell you what servers are currently down.
\item{\command{fs help}}: This will give you information about various
\command{fs}
arguments and what each one does. You can also type \command{fs help
{\em argument}} for more information about a particular argument.
\end{description}

\subsection{pts}

The command \command{pts} is used to contact the \product{AFS Protection
Server}, an AFS server that stores all the information on \AFS\ users and
groups. You can create your own groups and add members to them with
the commands
\command{pts creategroup} and \command{pts adduser}. You can remove users from
groups with \command{pts removeuser} 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}.

Suppose \usr_or_group{jis} wants to create the group 
called \usr_or_group{jis:6.001}. He will first check to see
whether the group exists.  Then he will create it and add some
people to it.
\begin{verbatim}
athena% pts examine jis:6.001
pts: User or group doesn't exist so couldn't look up id for jis:6.001
athena% pts creategroup jis:6.001
group jis:6.001 has id -65574
athena% pts adduser jis jis:6.001
athena% pts adduser lnp jis:6.001
athena% pts adduser cuban jis:6.001
athena% pts membership jis:6.001
Members of jis:6.001 are:
  lnp
  jis
  cuban
\end{verbatim}
Note that \usr_or_group{jis} must add himself to the group 
\usr_or_group{jis:6.001}; you are {\em not} by default a member
of any group you create.

Now that he has created the group, he can give its members access
to his scheme directory.
\begin{verbatim}
athena% fs sa scheme jis:6.001 all
athena% fs la 
Access list for scheme is
Normal rights:
  jis:6.001 rlidwka
  system:expunge ld
  system:anyuser rl
  jis rlidwka
  srz rlidwk
\end{verbatim}

You can use \command{pts membership\/} to get the members of most
system-controlled lists\footnote{The exceptions are specifically
``hidden'' system lists.} as well as of user-controlled lists.  Even
though \product{Moira\/} can give you this information as well, it is
sometimes faster to get the information from \AFS.

Note that unlike \NFS\ groups, you do not have to wait for
system updates for changes to \AFS\ groups to take effect.  They
take effect as soon as the user re-authenticates to the cell.
The easiest way to do that is to type \command{renew}, and then
enter your Athena password at the \fixedname{Password:} prompt.

\subsection{aklog}

As mentioned before, you do not need to explicitly attach a volume
to access its files.  However, if the volume is in another cell, the cell may
not ``recognize'' you and grant you proper permissions.  You can use the
command \command{aklog} to identify, or \term{authenticate} yourself
to an MIT-based cell\footnote{To authenticate with a non-MIT cell, you need
to have an account there.  World-readable files are accessible without
authentication.}.  Basically, \command{aklog}
uses your Kerberos tickets\footnote{For more information about Kerberos,
see \inessguide.} to get you \term{tokens} for the cell. To use aklog, 
you can type \command{aklog -c \argument{cellname}}, or you can cd to a 
volume in the cell and type \command{aklog .} (``.'' is an abbreviation
for the current directory).  For more information, you can read the
manual page for \command{aklog.}  Note that if you attach or add a 
volume, the command \command{aklog} will be called as a part of the 
attach process.

\subsection{vos}
 
The command \command{vos} is primarily of interest to system
administrators, but it does have a few functions of interest to
general users.  Specifically, it is used to query and manipulate
volumes.  The \command{vos} is in the \pathname{afsuser}
locker.  To use it, you should first \command{add afsuser}. 

The command \command{vos examine} is used to find out general
information about a volume.  This information includes the volume
identification number of the volume itself, as well as the volume
identification number of the backup and read-only volumes associated
with it (if they exist).  It also tells what server the volume is
located on and when the volume has last been released or backed up. In
addition, it tells you when the volume was last changed, and what the
maximum quota of the volume is. Here is an example:
\begin{verbatim}
athena% vos examine user.autumn
user.autumn                       536956932 RW       2077 K  On-line
    CIRCE.MIT.EDU /vicepa
    Parent  536956932 Clone          0 Backup  536956934
    MaxQuota       5000 K
    Creation    Fri May 22 15:52:21 1992
    Last Update Fri Jun 26 15:42:15 1992
    1539 accesses in the past day

        readWriteID 536956932   valid
        readOnlyID  0           invalid
        backUpID    536956934   valid
    number of sites -> 1
    server CIRCE.MIT.EDU partition /vicepa RW Site
\end{verbatim}
Suppose I want to know when my account was last backed up. I can use the
same command on \pathname{user.autumn.backup} to find out:
\begin{verbatim}
athena% vos examine user.autumn.backup
user.autumn.backup                536956934 BK       2087 K  On-line
    CIRCE.MIT.EDU /vicepa
    Parent  536956932 Clone          0 Backup  536956934
    MaxQuota       5000 K
    Creation    Sun Jun 28 23:03:11 1992
    Last Update Sun Jun 28 23:03:11 1992
    0 accesses in the past day

        readWriteID 536956932   valid
        readOnlyID  0           invalid
        backUpID    536956934   valid
    number of sites -> 1
    server CIRCE.MIT.EDU partition /vicepa RW Site
\end{verbatim}
This tells me that my backup volume was last updated on Sunday, June
28.  

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

For more information on the command \command{vos}, you can type
\command{man vos} at the \command{athena\%} prompt.

\subsection{Special string \pathname{@sys}}

\pathname{@sys} is not really a command, but a special string. 
Since \AFS\ is designed to look the same on different kinds of
machines, the special string \pathname{@sys}, when it appears in a
pathname, 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 legal
value
\pathname{rt\_aos4} in the athena cell.  On an Athena VAXstation, 
\pathname{@sys} has the value \pathname{vax\_bsd43}. On an Athena DECstation,
it's \pathname{pmax\_ul4}; on an Athena RS6000, it's
\pathname{rs\_aix31}\footnote{The values of
\pathname{@sys} for various Athena machines can be found in the file
\pathname{/afs/athena/service/systypes}.}. Thus the directory 
\pathname{/mit/sipb/@sys} on different machines corresponds to
different directories.  If I am on a VAXstation, I will end up in
\pathname{/mit/sipb/vax\_bsd43}; if I am on an IBM RT/PC, I will end up in 
\pathname{/mit/sipb/rt\_aos4}. And so on.  

One use for \pathname{@sys}, as we have seen above, is in the naming
of directories to contain binary files. Binary files are programs that
have been compiled and are ready to run.  These files are different
for different machine architectures; VAX binaries will not run on a
Sun or a DEC or an RT.  Therefore, these files  are
often kept in separate directories.  Many lockers use
\pathname{@sys} itself as the names of these directories.  Thus a single
command, such as \pathname{/afs/sipb/project/sipb/@sys/xscreensaver},
can be used to start an application, such as xscreensaver, on any
machine.  However, you should note that there is no fixed
convention for the naming of these directories.  Although using
\pathname{@sys} might be ``most standard,'' some lockers use
different names, 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 lockers sometimes
use different methods.  Note again that attaching a locker with the
command \command{add} puts the correct pathname into your path; you
will be able to execute the correct binary by simply typing the 
filename\footnote{For more information, read the manual page for
\command{add}.}.

\section{Where to Go For More Information} \label{moreinfo} \label{manpages}

% try expanding this...

\begin{description}
\item{\term{\UNIX\ manual pages}, commonly known as \term{manpages},}
  are an on-line copy of the documentation from the \UNIX\ Reference Manual
  and other documents.
  They give out information on \UNIX\ commands and most other software
  (including all Athena and SIPB programs), \UNIX\ system calls, standard
  library functions and file formats.  Manpages are an extremely useful
  source of information\footnote{Older users will often point this fact out
  to the less experienced ones by using a word of sage advice, ``RTFM'',
  which stands for ``Read The Friendly Manual''.}.  To access a manpage about
  a command, type \command{man \argument{commandname}}.  If you are looking
  for a command that does something specific you need, use the
  \command{apropos}
  command\footnote{Further information can be found in the manpage for the
  \command{apropos} command.}
\item{\term{On-Line Consultants}} are provided by Athena to answer users'
  questions.  To contact an on-line consultant, type \command{olc}.
\item{\term{OLC stock answers}} are a collection of consultants' answers
  to frequently asked questions. It can be reached by typing \command{olc
  answers}.
\item{\term{Online Help}} is an interactive help program. Enter
  \command{olh \&} to start.
\item{Athena documents \docname{AFS on Athena} and \docname{NFS2AFS Fact
  Sheet}} give additional information on AFS.
\item{Commands \command{fs}, \command{pts} and \command{vos}} have built-in
  help. To list the options, type \command{\argument{command} help}; to
  get help on a particular option, use \command{\argument{command}
  \argument{option(s)} -help}.
\item{\term{SIPB office} in W20-557} has free copies of all SIPB documents,
%%%%%%%%%% COULDN'T FIX THIS WITH \inessguide/\inessafs...  FIX BY HAND
  including this document and \docname{An Inessential Guide to Athena}.
%%%%%%%%%% COULDN'T FIX THIS WITH \inessguide/\inessafs...  FIX BY HAND
  We also answer user questions.
\end{description}

\newpage

\section{Credits}

This document was originally written by E. Jay Berkenbilt and revised
by Barbara Manganis and Albert Dvornik.  We would like to thank the
people who helped us by reading over this document in its many
stages and making helpful suggestions.  We would also like to thank
the SIPB as a whole, and in particular those members who gave us AFS
tutorials and moral support late at night over Zephyr. Please send comments
about this document, including corrections and suggestions for improvement, to
\address{bug-sipb@ATHENA.MIT.EDU}, or bring them to the SIPB office
in W20-557.  

\end{document}
