% -*-latex-*-
% Document name: /afs/athena.mit.edu/user/l/lwvanels/olcadm/Guides/server_maint.tex
% Creator: Lucien W. Van Elsen [lwvanels@fionavar.mit.edu]
% Creation Date: Wed Feb  6 15:31:37 1991
\documentstyle[fullpage]{article}
\begin{document}
\begin{titlepage}
\let\footnotesize\small \let\footnoterule\relax \setcounter{page}{0}
\null
\vfil
\vskip 60pt \begin{center}
{\LARGE OLC:\\ Technical Overview and Setup \par} \vskip 3em {\large \lineskip .75em
\begin{tabular}[t]{c} Lucien Van Elsen
\end{tabular}\par}
\vskip 1.5em {\large April 2, 1991 \par} \end{center} \par
\vfill
\begin{flushright}
\copyright 1991 Massachusetts Institute of Technology\\

Project Athena, Athena, Athena MUSE, Discuss, Hesiod, Kerberos, Moira, and
Zephyr are trademarks of the Massachusetts Institute of Technology (MIT).
No commercial use of these trademarks may be made without prior written
permission of MIT.
\end{flushright}
\null
\end{titlepage}
\tableofcontents
\newpage
\section{Overview}

The part of the document is intended to provide a general technical overview
of the OLC service, with references to the relevant sections of source code.
It assumes you have a working knowledge of user interface and concepts of
the OLC system; it is not meant to be a general overview of the OLC system,
but rather a guide to the installation, customization, and maintenance of an
OLC system.

\subsection{OLC Server}

The OLC server is composed of a three daemons and a database that reside on
a common machine.  It also uses several services present on the machine
(such as the ability to export NFS, and Discuss), as well as services
present on the network (such as Zephyr, Hesiod, and Kerberos).  While these
services are necessary to have the full functionality of OLC, some
functionality can be had without these services.

\subsubsection{Locking Daemon: {\em olcd}}

This daemon handles all changes to the database.  It handles a wide variety
of requests\footnote{For a long time, this was the {\em only\/} daemon.  See
{\tt src/include/olc/requests.h} for a description of the protocol and a
list of the requests and options it can take.  The actual routines to handle
the requests are in {\tt src/server/olcd/requests\_olc.c} and {\tt
src/server/olcd/requests\_admin.c}.}, and handles the direct communication
with the users via write and zephyr when their question status changes, and
also broadcasts notifications of status changes via Zephyr.  It is also
responsible for keeping the kerberos ticket file that it and the polling
daemon use to authenticate themselves to the various services.

Additionally, this daemon is responsible for automatically connecting new
questions to consultants based on the consultants available, their
specialties, and other information about the question and
consultant\footnote{The routine that does this is {\tt match\_maker} in {\tt
src/server/olcd/data\_utils.c}}.

When a question is resolved, this server moves the log of the question to
discuss\footnote{Actually, a small lie.  It actually calls the {\em
lumberjack\/} program to move the question log to discuss.}, notifies the
user and the consultant, and removes the question and the associated user
information from the database.

\subsubsection{Polling Daemon: {\em polld}}
This daemon does not directly communication with the client programs, but
instead uses Zephyr and finger to keep track of the login status of the
users who have questions currently active in OLC, and to information the
Locking Daemon when their status changes so it can update the database.

It does this by periodically reading the list of active questions from the
database\footnote{The frequency can be controlled by changing {\tt
CYCLE\_TIME} in src/include/polld.h}.  It zlocates the user, and uses the
locations it gets from zephyr and the last known location it got from the
database to build a list of possible locations.  From this, it then fingers
at each of the locations, looking for the user.  If the login status has
changed from what it found in the database, it makes a request of the
Locking Daemon to change the users's status\footnote{Note that this daemon
uses the kerberos ticket file maintained by the locking daemon to make
requests of the locking daemon.  In order to make the user status change
requests, the principle in the kerberos ticket file maintained by the olc
server (commonly `olc.hostname') must be on the admin acl of the OLC server.}.

\subsubsection{Query Daemon: {\em rpd}}
 This daemon is used to provide a quick means of retrieving information from
the database.  It cannot change the database state, but only retrieve
information from it.  Specifically, it is used to retrieve the logs of
questions, the unseen messages for consultants and users, and the current
queue listing.  These functions were separated from the locking daemon
because they don't change the state, and because they are some of the most
common requests made\footnote{Based on profiling information, our average
breakdown of requests shows that 18\% are requests for logs, 12\% are for
unseen messages, and 15\% are for the current queue listing}.

The daemon caches this information in memory, and keeps the file descriptors
of the information it's caching open as well.  When a request comes in, it
checks it's cache, and if it finds the requested information, stats the file
to make sure it has the most up to date copy.  If it finds newer
information, it reads it into memory, and then ships the information down
the socket to the user.

The cache uses a pseudo-LRU (`clock') algorithm for its caching; in
practice, cache hits average around 80\%.  Additionally, it uses a smaller,
more streamlined protocol than the locking daemon.

\subsubsection{Database}
  The database stores the information that represents the ``state'' of the
  OLC server at any given time.  This information consists of:
  \begin{itemize}
    \item {\bf Location}: This is the current/last known location of the user.
          This information is 
          used by the polling daemon to determine if the user is logged in,
          and is included as part of the queue listing to help consultants
          in answering the question.
    \item {\bf Login status} of the user.  This information is used in matching
          up users and consultants, and is included as part of the queue
          listing to help consultants in answering the question.
    \item {\bf Question log:} This is a plain ascii file that contains a log of
          all the actions taken on the question to date.  There may be a
          ``censored'' version as well as an uncensored version if private
          comments were made.
    \item {\bf Unseen messages:} This is a plain ascii file that contains the
          messages that a user has not viewed yet; it is separate from the
          question log (although the information is present in both places)
          to allow easy access to the new messages separate from other
          information in the log.
    \item {\bf Unanswered questions:} A list of all the questions that have
          yet to 
          be resolved and the information associated with them.
    \item {\bf MOTD}: The message of the day and the times that it should start
          being displayed and the time it should stop.
    \item {\bf ACLs}: The access control lists used by the server.  For more
          information on these, see section~\ref{sec:acls}
    \item {\bf Specialties}: The list of topics which consultants have special
          knowledge in, which is used when determining who to automatically
          connect a question to.  For more information, see
          section~\ref{sec:specialties}.
    \item {\bf Topics}: This is the list of the topics that the server
          supports.
          For more information, see section~\ref{sec:topics}.
  \end{itemize}

\subsection{Discuss}
Discuss is a conferencing system that is used to store the logs of resolved
questions.  The logs of resolved questions are not directly used by the
server, but are useful in order to perform checks on the quality of answers
given and other administrative functions.  Additionally, it provides a
reference of past answers that can be searched by consultants, to see if a
similar question has been answered in the past.

\subsection{Mail}
Mail can be used to provide a means to enter questions into OLC; while this
entry point cannot be authenticated (unlike all the other requests made of
the server) there are some environments where the benefits gained by the
ability to enter questions by mail outweigh the possible disadvantages.

\subsection{NFS}
NFS\footnote{Sun's network file system; all trademarks are copyright their
respective owners. {\tiny that's our lawyer speaking}}
is not used directly  by the server, but can be used to provide a convenient
way for the OLC Administrator to access the various files that make up the
OLC database.  Using this, various administrative changes (such as changing
user/consultant titles) can be made in the database with necessarily having
to log in to the server machine.

\subsection{Remote Access}
Again, remote access is a convenience which is useful to maintain the
machine.  At Project Athena, this service is not turned on by default; if
you're outside of Athena, this may different.

\section{Building the binaries}

In order to build the binaries from the distribution, you will need the {\tt
imake} and {\tt makedepend} utilities that are distributed along with X.  It
is useful if you have the other Athena services, motif, and emacs, but they
are not necessary to build a bare-bones system.

\subsection{Configuration files}
Before building the distribution, it is necessary to modify the
configuration files to reflect the preferences at your site.  The files that
must be modified are:
  \begin{itemize}
    \item {\tt src/config/site.def} This is used to determine what services
          and systems you have present a your site.  Some of the more
          non-obvious ones are:
    \begin{itemize}
      \item TestInstall: If this is true, the binaries will be installed in
            an alternate location when ``make install'' is run.  The
            locations are determine by the individual Imakefiles in the
            directories involved.
      \item HaveSysWrited: If this is true, you already have a ``writed''
            for handling network writes.  I am not sure if this is true
            anywhere outside of MIT.
      \item HaveSysWCL: If this is true, you already have ``WCL\footnote{The
            widget creation library, developed by David E. Smyth. and
            copyright Auto-trol Technology Corp.  For a full description of
            the copyright and such, see the directory {\tt wcl}.}
            ''.  Note that the version of wcl used in
            the code is 1.0.4, not 1.0.5 which is the most current.
      \item DoLogging: If this is true, the server will log all requests
            made of it to a file.  Useful for debugging, or for profiling
            usage.
      \item DoUsageLog: If this is true, the clients will log their usage.
            A host must be set up in the {\tt .h} files of the respective
            clients, and the {\tt logger/bbd} program must be running on the
            host which is specified.
      \item AthenaCompat: Should be false for sites outside of MIT.
      \item HaveMotif: Should be true if you have Motif, and want the
            motif-based client built.
    \end{itemize}
    Additionally, {\tt site.def} is used to specify the locations of various
    system libraries if they are present.

    \item {\tt src/config/Imake.template}: This is used to set the defaults
          for several OS-dependent flags.  Usually, this information is set
          in the MacroIncludeFile (e.g.\ {\tt machtype.cf}) in the config
          directory for each platform, but if you wish to provide new
          defaults, you can do it here. 
    \item {\tt src/config/{\em machtype}.cf}:  This is used to set platform
          specific flags.  These configuration files are provided for all
          the platforms that OLC has been tested on so far, but you may need
          to tweak them to suit your local environment, or you may need to
          add a new one if you have a different platform. 

          These flags are:
    \begin{itemize}
      \item {\bf HaveTermIO}: If 1, it uses SYSV termio style terminal control;
            if it is 0, it uses BSD-style.
      \item {\bf HaveDefErrno}: If 0, /usr/include/sys/errno.h does not
            define errno or sys\_errlist, and they need to be defined when
            they are used.
      \item {\bf HaveSelectMacros}: If 0, /usr/include/sys/types.h does not
            provide the macros for working with the file descriptor sets
            used by selected (FD\_SET, FD\_ZERO, et. al.)
      \item {\bf HaveAnsiIncludes}: This should be 1 if you are using an
            ansi compiler and your system provide ANSI-compiliant include
            files; otherwise, it will try to use its own.
      \item {\bf HasVFork}: Set this if your system provides vfork;
            otherwise, fork is used in all cases.
      \item {\bf HasPutenv}: Set this is your system does not provide
            setenv; putenv will be used instead.
      \item {\bf HasGcc}: Set if you want to use gcc instead of the standard
            cc.
      \item {\bf HasSaberC}: Set if you want to have rules for debugging
            under Saber included.
    \end{itemize}
    \item {\tt Include files}:  If you want to change the default location
          of files, you will need to modify the appropriate include files in
          {\tt src/include} and {\tt src/include/olc}.  The default
          directory setup that OLC expects is:
    \begin{itemize}
      \item {\bf /usr/spool/olc} to store the question database and logs
      \item {\bf /usr/spool/olc/donelogs} to store the logs of the resolved
            questions temporarily before they are moved to discuss.
      \item {\bf /usr/lib/olc} to store the kerberos srvtab, the
            motd and hours files, and the server configuration files.
      \item {\bf /usr/lib/olc/acls} to store the ACLs.
      \item {\bf /usr/lib/olc/specialties} to store consultant's specialties.
      \item {\bf /usr/local} to store a local copy of olcr used by the
            daemon that handles questions entered by mail.
      \item {\bf /usr/adm/olc} Used for storing error logs and statistics.

    \end{itemize}

    It would be wise to go through all of the .h files in these
    directories and double check that the locations of the various files,
    programs, and services are set up as you expect.

    \item {\tt Imakefile}s:  If you wish to change the locations the
          binaries will be installed in, you will need to change the
          individual Imakefiles.  Currently, the server binaries are
          installed in {\tt /usr/etc}, the client binaries in {\tt
          /usr/athena}, and the help files stored in {\tt
          /usr/athena/lib/olc}.
  \end{itemize}

Once the configuration has been set up, you should be able to type ``make
world'' at the top level, and it will go through and make the makefiles, add
the dependencies, and then proceed to build the binaries.  Once this is
done, you can do a ``make install'' to install the binaries.

\section{Use without Athena services}
\subsection{Hesiod}
Use of OLC without the Hesiod naming service will have the following
effects:
  \begin{itemize}
    \item For the (oreplay/olist/oshow) clients, you must always explicitly
          specify a server to use with the -s option.
    \item For the (olcr/olc) clients, you must always explicitly specify the
          {\tt -server} option when invoking them, or set the OLCD\_HOST
          environment variable.
    \item For the {\em polld\/} daemon, you must explicitly specify a {\tt
          -host machinename} option so it can find the locking daemon.
    \item for the {\em olcd\/} daemon, you must explicity sepcify a {\tt
          -host machinename} option so it can find itself.  Additionally,
          all users asking questions must be in the password file of the
          server in order to have the ``real name'' associated with their
          username be correct; if it cannot find them in the password file,
          their real name will be ``The Unknown User''.
  \end{itemize}

\subsection{Zephyr}
Use of OLC without the Zephyr location/messaging service will have the
following effects\footnote{Note: you must have the {\tt com\_err} package if
you zephyr; it is available from athena-dist.mit.edu, and is also used in
the kerberos and zephyr distributions}: 
  \begin{itemize}
    \item All workstations on which the clients are going to be used must
          have the {\tt writed} server installed to allow write to work
          across the network.
    \item No broadcast notifications of status changes will be sent out, so
          the Emacs OLCR client will not be able to automatically update its
          state.
    \item The polling daemon will have reduced usefulness, since it can not
          use zephyr to track the users as they move around.  However, it
          can still be somewhat effective using the ``last known location''
          information that is stored in the database to determine when they
          leave that particular workstation.
  \end{itemize}
\subsection{Kerberos}
Use of OLC without the Kerberos authentication service will have the following
effects: 
  \begin{itemize}
    \item There is no proof that anyone using the system is who they say
          they are; all that is/can be checked is that the username and uid
          they claim to be is on the correct acl.
    \item In the file {\tt src/server/rpd/acl\_files.c} you must set the
          default realm of your site; without kerberos, this can be anything
          you chose to standardize upon, but this still needs to be set.
    \item Kerberized clients can work with a non-kerberized server, but
          non-kerberized clients cannot work with a kerberized server.
  \end{itemize}
\subsection{Discuss}
  \begin{itemize}
    \item There is no way to save the logs of resolved questions and old
          MOTDs; they are just deleted.
    \item It would be easy to drop in hooks to another conferencing system;
          you just need to replace the functionality of the ``lumberjack''
          program in {\tt src/server/lumberjack}, which takes the logs and
          their associated control files from {\tt /usr/spool/olc/donelogs}
          and moves them to the appropriate place.  If you need to change
          the interface to whatever does the moving of the logs, the call to
          the external program is in the file {\tt src/server/olcd/log.c} in
          the routine dispose\_of\_log().
  \end{itemize}
\subsection{``Athena''}
  If the ``Athena-compat'' flag is not set in the site.def file, you'll need
  to specify different default fallback values than the ones used at Athena.
  Additionally, some of the ``friendly'' error messages will need to be
  changed to reflect your site, as will the help files\footnote{For example,
  the phone number of our help desk, and ``Contact Athena Operations'' are
  appropriate to have at Project Athena; they would not be appropriate for
  other sites.}

  \begin{itemize}
    \item If you are using kerberos, you will need to set server's default
          realm DFLT\_SERVER\_REALM in {\tt src/include/olcd.h}.
    \item Verification of the user's mail address will not be done; your
          mail delivery service will most likely be sufficiently different
          that the routines we use here will not work.  If you wish to
          enable it, replace the Athena-specific routine to do this in {\tt
          src/clients/lib/utils.c}.
    \item You will need to specify the local kerberos realm in {\tt
          src/server/olcd/acl\_files.c}
    \item In order to have information on the machine the client is running
          on included as part of the question, you will need to have the
          ``machtype'' program from Athena, or some equivalent at your site.
          Since this is not portable, no machine information will be sent by
          default.
          This is called from {\tt src/clients/lib/ask.c}, in the OAsk()
          routine, if you wish to install your own method for determining
          the type of machine the client is running on.
    \item Several clients use the ``attach'' command to mount other
          filesystems for them; the widest use of this is to mount the
          filesystem that contains the stock answers.  Depending on your
          setup, you may be able to get rid of the call to attach completely
          (if you know that the files will be accessible), or change the
          command to whatever is appropriate at your site.
  \end{itemize}

\section{Installation}

Once you have the sources compiled to your satisfaction, you will need to
install the binaries and set up the system configuration to allow the
clients and server to work together smoothly.

\subsection{OLC Clients}
\subsubsection{olc/olcr}

{\tt olc}, the ``user'' clients, and {\tt olcr}, the ``consultant'' client
are actually one and the same binary; it just uses the name it was invoked
with to determine which of the commands to make available.  The commands
available in {\tt olc} are a subset of the commands available in {\tt olcr}.

These clients also expect to find their help files by default in the
directories {\tt /usr/athena/lib/olc/olc\_help} and {\tt
/usr/athena/lib/olc/olcr\_help} respectively.  These locations are
set in {\tt src/include/olc/olc.h} in the defines {\tt OLC\_HELP\_DIR} and
{\tt OLCR\_HELP\_DIR}.

\subsubsection{Xolc} 

This client depends on being able to find its resources (defined in the file
({\tt src/clients/motif/Xolc}) in order to function properly; if not, the
user interface will look very strange.  It expects to find its help files in
the directory defined in {\tt src/clients/motif/data.h} in the define {\tt
HELP\_PATH}.  Additionally, it expects the X-based stock answer browser
program to be installed in the location specified by {\tt SA\_LOC} in the
same file.

\subsubsection{Emacs OLCR}

The emacs client is not included in the main source tree build, given the
different nature of its source files.  Additionally, it has a separate set
of configuration and setup instructions, which are in {\tt
src/Emacs/INSTALL}.  There also is comprehensive documentation for it in the
directory {\tt src/Emacs/dvi}.

\subsubsection{Stock Answers}

The stock answers system is actually separate from the OLC system; it will
work fine on its own, with no athena services, and without any of the OLC
programs.  Depending on your site, it may be useful to have an entry point
to these stock answers outside of your OLC system.  There is a script {\tt
src/browser/curses/olc\_answers} that invokes the browser outside of the OLC
programs.  If you use it, you will need to modify the script so that it
points to the location of the stock answers in your file system, and adapt
the ``attach'' to be a mount, or whatever is appropriate for your site.

The call to olc\_browser is
\begin{verbatim}
olc_browser -r directoryname
\end{verbatim}

where directoryname is the ``root'' of the stock answer tree.  To test this
out, you can use the set of sample stock answers included in the
distribution; to do this, you'd use

\begin{verbatim}
olc_browser -r samples/stock_answers
\end{verbatim}

For more information on setting up the stock answers, see the information in
{\tt stock\_answers\_guide.tex} in {\tt doc/guides}.

\subsection{OLC Daemons}

These daemons reside on the OLC server.  Typically, they are owned by root,
and reside in {\tt /usr/etc} and in {\tt /usr/local}.

\subsubsection{olcd}

A typical startup for olcd is

{\tt /usr/etc/olcd -inst olx -host fionavar}

which is placed in {\tt /etc/rc} or a similar file so that it is started at
boot time.  The ``inst'' argument is only necessary if the ``instance'' of
this server is different than the default one specified in {\tt
src/include/olc/olc.h} in the define {\tt OLC\_SERVICE}.  The ``-host'' is
only necessary if the SLOC hesiod information for that name does not point
to the current location, or if there is no hesiod SLOC information.

\subsubsection{polld}

A typical startup for polld is

{\tt /usr/etc/polld -inst olx -host fionavar}

The arguments are the same as for olcd.  Note that this should be placed
after olcd in the startup, so that it does not try to contact olcd
server with location updates while olcd is still starting up.  A short
($\approx$10 sec) sleep may be necessary before the call to polld to do
this.

\subsubsection{rpd}

A typical startup for rpd is

{\tt /usr/etc/rpd}

No arguments are needed.

\subsection{System files}
Several system files need to be modified:

  \begin{itemize}
    \item {\bf /etc/services}:  Add the lines
    \begin{verbatim}
write           811/tcp                         # Network write daemon
olc             2051/tcp                        # OLC locking daemon
ols             2052/tcp                        # OLC query daemon
    \end{verbatim}
    \item {\bf /etc/inetd.conf}: Add the line for the network write service:
\begin{verbatim}
write   stream  tcp     nowait  root    /etc/writed     writed
\end{verbatim}
    \item {\bf /etc/syslog.conf}: Add the line
\begin{verbatim}
local6.debug	/usr/adm/olc/syslog
\end{verbatim}
  \end{itemize}

\subsubsection{writed}

This needs to be installed on the machines on which the client is going to
be run; the typical location is in {\tt /etc/writed}.

\subsection{Hesiod}
If you are using Hesiod, you will need to register the location of the OLC
service.  It expects to find two entries

  \begin{tabular}{lll}
{\bf Name}&{\bf HesiodNameType}& {\bf Value} \\ \hline
olc & SLOC & foo.bar.baz \\
olc & SERVICE & olc tcp 2051
  \end{tabular}

where ``foo.bar.baz'' is the name of the machine running the OLC server.

\subsection{Kerberos}
If you are using kerberos, you will need to get a ``srvtab'', or shared
secret, for the olc server so that it can authenticate requests and
authenticate itself to zephyr.  The srvtab should have entries for the
services ``olc'' (and discuss, if you're going to run authenticated
discuss), with the instance being the name of the machine the server resides
on.  For example, on the machine ``fionavar.mit.edu'', there would be
entries for ``olc.fionavar'' and ``discuss.fionavar''.

This srvtab needs to be placed in the locations specified by the
SRVTAB\_FILE defines in {\tt src/include/olcd.h} and {\tt src/include/olcm.h}.

\subsection{Discuss}

If you are going to be using discuss to archive the logs of resolved
questions, you will need to create the discuss meetings, and set up a
configuration file with their location.  The configuration file {\tt
/usr/lib/olc/ds\_prefix} should contain a line of the form
\begin{verbatim}
HOSTNAME.FOO.BAR:/usr/spool/discuss/o
\end{verbatim}

where ``hostname.foo.bar'' is the name of the machine that the discuss
meetings are stored on (usually the name of the local machine), and
``/usr/spool/discuss'' is the location of the discuss meetings file.  The
``o'' is the standard prefix appended to the name the server uses to find
the location of the meeting\footnote{I.e, the meeting {\tt
/usr/spool/discuss/oemacs} would contain the logs of the questions on the
``emacs'' topic, \ldots{}/discuss/omotd would contain the archived motds,
etc.}.  The standard meetings the server expects to find are:
\begin{itemize}
  \item {\bf topic} One discuss meeting for each topic, named with the
        prefix above.
  \item {\bf motd} to archive the motds
  \item {\bf hno} for canceled questions
  \item {\bf oga} for unsolvable questions, marked as such via ``forward
        -unanswered''.
\end{itemize}

\subsection{Mail}
If you want to take questions via mail, you will need to have the ``olcm''
program available on the machine that is taking mail, and add an entry to
the mail aliases file of the form\footnote{ If you are on athena, it will be
of the form: {\tt olc-test@fionavar.LOCAL: "|/site/usr/local/olcm -s fionavar -t test -k olc.fionavar"@fionavar.LOCAL}}:
\begin{verbatim}
olc-test: "|/usr/etc/olcm -s fionavar -t test -k olc.fionavar"
\end{verbatim}

where the -s option specifies the name of the OLC server to be used, the -t
option specifies the topic it is to be entered under, and the -k specifies
the kerberos principle to be used (which must be present in the srvtab
of the machine receiving the mail).  The principle must also be on the {\tt
gask} acl of the OLC server.

\section{Initial configuration}
\subsection{User Database}
\subsection{Acls}\label{sec:acls}
The acls are used to control who has access to what functions on the OLC
server.  Each acl is stored in a separate file in the directory specified by
{\tt ACL\_DIR} in the file {\tt src/include/olcd.h}\footnote{By default, this
is {\tt /usr/lib/olc/acls}}.  The acls currently used are:
  \begin{itemize}
    \item {\bf admin}: A consultant must be on this acl in order to change
          or list any acls, or to load information about another user from the
          database into the server.  Additionally, in order to change the
          hours, you must be on this acl.  Also, in order to change a users
          login status, you must be on this acl.
    \item {\bf consult}: In order to be able to done or cancel questions
          they are connected to, a consultant must be on this ACL.
          Additionally, a consultant must be on this acl in order to comment
          on or change the descriptions or topics of questions they are
          connected to. They must also be on this acl in order to grab
          questions in their specialty.
    \item {\bf gask}: A consultant must be on this acl in order to ask
          questions on behalf of other people.
    \item {\bf gchtopic}: A consultant must be on this acl in order to
          change the topic of a question he is not connected to.
    \item {\bf gcomment}: A consultant must be on this acl in order to be
          able to comment on or change the description of questions they are
          not connected to.
    \item {\bf gmessage}: In order to be able to send messages or mail to
          users you are not connected to, you must be on this acl.
    \item {\bf grab}: A consultant must be on this ACL in order to be able
          to grab questions that are not among one of his specialties.
    \item {\bf gresolve}: In order to be able to done, cancel, or forward
          questions other people are connected to, a consultant must be on
          this ACL.  Additionally, you must be on this acl to sign another
          consultant ``off duty''
    \item {\bf monitor}: In order to be able to find out information about
          another user, including their current status in OLC or to see the
          log of their question, the consultant must be on this ACL.
    \item {\bf motd}: A consultant must be on this acl in order to change
          the message of the day.
    \item {\bf olc}: A user must be on this ACL in order to ask questions,
          find out the topics that a server supports, get the motd, or get the
          hours.
    \item {\bf on}: In order to be able to sign ``on'' and get automatically
          connected to questions, the consultant must be on this ACL.
  \end{itemize}

For a typical setup, all of the consultants would be on the acls:
  \begin{verbatim}
consult
gcomment
grab
monitor
on
  \end{verbatim}


The OLC administrator(s) would be on the acls:
  \begin{verbatim}
admin
consult
gask
gchtopic
gcomment
gmessage
grab
gresolve
monitor
motd
on
  \end{verbatim}


To allow everyone to ask questions, everybody would need to be on the
acl\footnote{This is done by having the acl entry be {\tt
*.*@YOUR.REALM.NAME}}: 
\begin{verbatim}
olc
\end{verbatim}

A sample set of acls can be found in the directory {\tt
samples/usr.lib.olc/acls}.  These acls are read in when the person affected
first accesses OLC after the locking daemon starts up, or when the {\tt
dbload username} command in {\tt olcr} is used to re-load them for a
specific person.

\subsection{Topic List}\label{sec:topics}
The list of topics is stored in the file {\tt /usr/lib/olc/topics} on the
server, and is read when the locking daemon starts up.  The topics are
listed one per line, and must consist of a single world.  Anything after a
``\#'' on the line is ignored.  This file is send verbatim (including the
text after the ``\#'') when a client asks for a list of topics.  So, to have
the topics ``emacs'', ``latex'', ``mail'', ``unix'', and ``zephyr'', you'd
have a topics file that looked like:

\begin{verbatim}
#########  Supported software
emacs             # the standard Athena editor
latex             # text formatter
mail              # how to send/receive/delete mail, including other sites
unix              # operating system commands and other unix utilities
xwindows          # how to manipulate/create/manage windows on the screen
\end{verbatim}

A sample topics file can be found in {\tt samples/usr.lib.olc/topics}.

\subsection{Specialties}\label{sec:specialties}

The lists of consultants who have a specialty\footnote{This ``specialty'' is
used when deciding which consultants to connect automatically to incoming
questions} in each topic are stored in the directory {\tt
/usr/lib/olc/specialties} on the server, in files named {\tt {\em
topic}.acl}.  The format of entries in these files is the same as the acl
files.  

A sample set of specialties can be found in {\tt
samples/usr.lib.olc/specialties}. These specialties are read in when the person
affected first accesses OLC after the locking daemon starts up, or when the
{\tt dbload username} command in {\tt olcr} is used to re-load them for a
specific person.

\subsection{Database}
This database is used to override the default titles and number of questions
allowed on a per-user basis.  A sample of this file can be found in {\tt
samples/usr.lib.olc/database}; the format is self-explanatory.

If it is desired to override the overall defaults for the number of questions
allowed to be asked/answered, this can be done by editing the lines

\begin{verbatim}
  user->max_ask = 1;
  user->max_answer = 2;
\end{verbatim}

in the function init\_dbinfo in the file server/olcd/data\_utils.c to have the
values you desire.

\subsection{Machine Information Translation}
If you have compiled the source with Athena compatibility and have access to
the ``machtype'' command, the locking daemon will do some translation of the
machine information that is inserted after each question into a more
``readable'' form for humans\footnote{Specifically, the routine {\tt
init\_log} in the file {\tt src/server/olcd/log.c} calls the {\tt
trans\_m\_i} function in the same file to do this work}.  If this is not the
case, you can skip this section.

The server expects a comma-separated list of things that make up the machine
information to be passed over; it is in the form {\tt PROCESSOR,
\{DISPLAY,\}$^{*}$ MEMORY}.  The locking daemon reads in the translations
from the file {\tt /usr/lib/olc/translations} when it first receives a
question.  This file is of the form
\begin{verbatim}
#_OF_PROCESSOR_TRANSLATIONS
ABBREV_1
FULL_NAME_1
ABBREV_2
FULL_NAME_2
....
#_OF_DISPLAY_TRANSLATIONS
ABBREV_1
FULL_NAME_1
ABBREV_2
FULL_NAME_2
....
\end{verbatim}

A sample translations file can be found in {\tt
samples/usr.lib.olc/translations}.
\newpage
\section{Support}
All of the software and documentation that make up this release are provided
under the standard MIT copyright; a copy of this can be found in {\tt
src/include/mit-copyright.h}.  In part, it says:

\begin{quote}
\ldots{} Permission to use, copy, modify, and distribute this software and
its documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that both
that copyright notice and this permission notice appear in supporting
documentation, and that the name of M.I.T. not be used in advertising or
publicity pertaining to distribution of the software without specific,
written prior permission.  M.I.T. makes no representations about the
suitability of this software for any purpose.  It is provided "as is"
without express or implied warranty.
\end{quote}

{\tt olc-users@ATHENA.MIT.EDU} is a mailing list set up for discussing issues
relating to OLC, as well as the place where new releases of the OLC software
will announced.  Additionally, the mailing list {\tt olc-users@ATHENA.MIT.EDU}
may be able to provide a reference to consulting expertise in the areas of:

\begin{itemize}
\item Setting up an on-line consulting organization;
\item Installing OLC in your environment;
\item Maintaining OLC in your environment;
\item OLC training and documentation ;
\item Stock answer development and other on-line consulting tools;
\item Modifying and augmenting OLC for your environment;
\item and other similar development and organizational issues.
\end{itemize}

Any such referral is not an endorsement by M.I.T of the services
provided by such an organization.  M.I.T makes no representations with
regard to the suitability or quality of services provided by the
referred firms.  The reference is made without express or implied
warranty.

If you would like to subscribe to it, send a request to
{\tt olc-request@ATHENA.MIT.EDU}.

If you find bugs, please mail them to {\tt olc-bugs@ATHENA.MIT.EDU}.
\end{document}