% 
% $Header: /afs/sipb/project/doc/guide/RCS/moira.tex,v 1.7 2003/10/02 06:38:37 ocschwar Exp $
% $Source: /afs/sipb/project/doc/guide/RCS/moira.tex,v $
% $Author: ocschwar $
%
% This is the moira section of the Inessential guide
%

\newcommand{\moira}{{\em Moira}\/}

\section{\moira: Athena glue-all, or Your Fate}

As you may have gathered by this time, you, as a user of Project
Athena, are aided by a fairly large number of services.  You are
served by {\em NFS}\/ and {\em AFS}\/ which bring you your
files, by {\em Kerberos}\/ which allows you to convince Athena
that you are who you say you are, by {\em Hesiod}\/ which allows
you to look up information about many things, by {\em Zephyr}\/
which allows you to locate users and communicate with them
electronically, by the post offices which allow you to send mail
-- the list goes on.  It would be virtually impossible for a
single person to keep all of these services under control and
consistent with each other.  This is why we have \moira, the
Service Management System. \moira\ is an alternate spelling for
{\em moera}, which means fate.  The three aspects of fate were
Clotho, who spun the thread of life; Lachesis, who wove the
thread into the tapestry of life setting a person's destiny; and
Atropos, who cut the threads at the appropriate time.
Similarly, \moira, the system, creates user accounts, controls
the user's home placement and quota, and deactivates user
accounts\footnote{Until the beginning of 1989, \moira\ was
known as {\em SMS}\/, which stands for {\em Service Management
System}.  Since so many other things were called {\em SMS}\/,
and since almost everything else at Athena had a greek name, it
was decided that the Service Management System should be
renamed.}.

\moira\ is a very large database containing most of the
information that is necessary to keep Athena running smoothly.
Although \moira\ is not needed for someone to log in and use the
system (unlike {\em Kerberos}, which must be available all the time),
without it, nobody would be able to change anything about any service.
This means you couldn't add anyone to a mailing list, create a new
filesystem, or any number of similar operations.

Even though \moira\ controls a vast array of things and can perform
several tasks, there are only two things that you will probably ever
need to use \moira\ for: changing or inspecting lists and updating
finger information.  Both of these are explained in this section.

\subsection{Things Not To Do}

It is possible for you to put yourself into a situation that you won't
be able to get out of.  For example, you can change the administrator of
a list you own to someone else.  If you do this, {\bf you will not be
able to reclaim the list without help from an administrator}.  When you
make a change, especially a transfer of authority, think about whether
you'll be able to undo it.  If you really get messed up, you can call
the user accounts consultant at x3-1325.

\subsection{How to manage lists}

To \moira, a list is simply, well, a list.  The items on an
\moira\ list are called {\em members}\/.  Each member of an
\moira\ list has two attributes: a type and a name.  A \moira\
list can have several types of members.  The only ones useful to most
users are users, other lists, and arbitrary strings such as electronic
mail addresses.  

Lists can serve several functions.  The two most common are UNIX
groups and mailing lists.  Your list is a {\em Unix AFS group}\/.  You use
it to control file access.  For more information about AFS groups,
look at the manual pages for the AFS {\tt fs} utility, and {\tt
chmod} (change mode) by typing {\tt add afsuser; man fs} and {\tt man chmod}.
You can also find information in this guide in SIPB's 
{\em Inessential AFS} guide and in the OLC answers repository
({\tt olc answers}).

The main tool that you will use to manipulate lists is {\tt
listmaint}.  {\tt Listmaint} is a fairly self-explanatory,
menu-based program.  To run {\tt listmaint}, just type {\tt
listmaint}.  Here is what the top-level menu of {\tt listmaint}
looks like:

\begin{samepage}
\begin{verbatim}
athena% listmaint

                                   List Menu 
 1. (show)         Display information about a list.
 2. (add)          Create new List.
 3. (update)       Update characteristics of a list.
 4. (delete)       Delete a List.
 5. (query_remove) Interactively remove an item from all lists.
 6. (members)      Member Menu - Change/Show Members of a List..
 7. (list_info)    List Info Menu.
 8. (quotas)       Quota Menu.
 9. (help)         Print Help.
 t. (toggle)       Toggle logging on and off.
 q. (quit)         Quit.
 t. (toggle)       Toggle logging on and off.
 q. (quit)         Quit.
Command: 

\end{verbatim}
\end{samepage}

To add someone to your list, select {\sl members} from {\tt
listmaint}'s top-level menu.  This will ask you for the name of
a list and then put you in a submenu entitled {\tt
Change/Display membership of '}{\em list}\verb+'+, where {\em
list}\/ is the list you specified.  As you may expect, you will
want to select {\sl add} from this menu.  You will be asked
what type of member you wish to add.  The answer to this
question should be {\em user}.  You will then be asked
for the name of the user you wish to add.  At this prompt, enter
the user's username.  You will be told whether the operation
completed successfully.

Using {\tt listmaint} is rather straight-forward.  Once you get
the hang of things, you will probably be able to figure out how
to do mostly anything you want to.

You can also use {\tt blanche} instead of listmaint. {\tt blanche} can
perform a number of the operations listmaint performs, and for those
operations is much quicker. For a quick list of the functions {\tt
blanche} can perform, simply type {\tt man blanche}.  For more detailed
information, read the manpages for all of the above.

\subsection{Getting information through moira}
In Unix, it is possible to {\tt finger} a user to find out more
information about him or her.  To do this, just type {\tt finger
user}.  You can change this information about yourself
with the {\tt chfn} command.  The use of the command is very
straight forward.  Just type {\tt chfn}.  You will then be told
what your current information is and prompted for new
information.  The new information that you entered will be
available to people who use {\tt finger user} within a
day or so.

You can also find {\tt finger user@mitdir} to get the ``official''
information about a person; this service is maintained by Distributed
Computing and Network Services and any changes of information must go
through the Registrar's Office (for students) or Personnel (for staff).
You cannot change this finger information yourself.

\subsection{What are you waiting for?}

One last point.  Because of the way \moira\ works, the changes
you make won't take effect right away.  If you add someone to
your list, \moira\ will know right away, but the rest of the
world won't know for between 15 minutes and three hours or so.  You
may remember that your account wasn't ready until the day after
you registered.  In future versions of \moira, it may be
possible to do this updating without delay.

\subsection{But wait!  There's more}

There are more \moira\ programs than just {\tt listmaint} and {\tt chfn}.
The program {\tt moira} is the master \moira\ client.  You could also have
changed any of this information from the {\tt moira} program, but it
would have been slightly more complicated to do so.  

To find more information on these other programs, refer to {\tt moira}
locker, which contains binaries and manual pages for the various moira
clients. These programs are listed in the file README in {\em
/mit/moira}.