\documentstyle{article}
\title{CWIS Queue Operations Documentation}
\author{Bruce Lewis}
\date{\today}

% Default margins are too wide.
\addtolength{\oddsidemargin}{-.5in}
\addtolength{\evensidemargin}{-.5in}
\addtolength{\textwidth}{1in}

\begin{document}

\maketitle
\newpage
\tableofcontents
\newpage

\section{Functional Overview}

The CWIS queue is just a shared mh folder in AFS.  When people on the
cwis-request mailing list wants to answer questions, they scan that
folder, refile a question or two into a private folder, and then answer.
This prevents multiple people from answering at the same time.

The directory for this mh folder has permissions system:anyuser lik so
that anybody can {\tt inc} into the directory, but random people can't
read, erase or overwrite messages.

The cwis-help queue is exactly like the CWIS queue; just a different
address and a different directory to {\tt inc} into.

\section{Server Characteristics}

This service really is nothing more than a mail file on the server that
gets {\tt inc}'ed into the appropriate directory every 15 minutes or so.
It makes sense to run this service on a server that is already {\tt
mkserv mail}.

\subsection{Compatibility}

This service should not interfere with any other service.

\subsection{Security}

This service is as secure as feeding mail into discuss meetings.

\subsection{CPU Loading}

This is a low-load service.  Its presence will be hardly noticeable.

\subsection{Network Loading}

No significant network load is introduced by this service, provided
nobody is spamming the email address.

\section{Requirements and Dependencies}

This service depends on the existence of two directories, currently {\tt
/afs/athena.mit.edu/org/c/cwis/Mail/inbox} and {\tt
/afs/athena.mit.edu/org/c/cwis/Mail/cwis-help}, with AFS permissions
{\tt system:anyuser lik}.  It relies on /usr/athena/bin/inc being
available on the server, although if it's sometimes unavailable, it will
only delay things, not cause a mail bounce.  No other mh library files
or other executables are required.

\subsection{Required}
\begin{itemize}
\item {\it srvtab} - NO
\item {\it Kerberos} - NO
\item {\it Athena} - any release
\item {\it Platforms} - anywhere {\tt cron}, {\tt mkserv mail} and {\tt
	inc} are available
\item {\it Hesiod} - NO
\end{itemize}

\subsection{Optional}
\begin{itemize}
\item {\it syslog} - sendmail will syslog any errors
\end{itemize}

\subsection{Not Required}
\begin{itemize}
\item {\it root access} - Does not need to run as root.
\item {\it name service} - Does not depend on name services.
\item {\it disk space} - Has no notable disk space requirements.
\item {\it swap space/real memory} - Has no notable memory requirements.
\item {\it peripherals} - requires no special peripherals
\item {\it /srvd} - {\tt /usr/athena/bin/inc} must be there
\end{itemize}

\section{Dependents}

If this service is unavailable, cwis-request and cwis-help people need
to fall back on answering questions from the discuss meeting and cc'ing
the group.  No other services depend on this service.

\section{Building}

No code needs to be compiled.

\section{Installation}

\begin{enumerate}

\item Create a directory /Mail mode 770, group daemon.  No mail is
stored in this directory, but {\tt inc} will complain if it can't write
{\tt /Mail/context}.

\item Create one non-login passwd entry named ``cwisq'', and another
named ``cwishelp''.  The UID may be 1 or anything you like.

\item Add crontab entries like the following, except all on one line:

\begin{verbatim}
0,15,30,45 * * * * /usr/athena/bin/inc
                      +/afs/athena.mit.edu/org/c/cwis/Mail/inbox
                      -file /usr/spool/mail/cwisq -truncate
0,15,30,45 * * * * /usr/athena/bin/inc
                      +/afs/athena.mit.edu/org/c/cwis/Mail/cwis-help
                      -file /usr/spool/mail/cwishelp -truncate
\end{verbatim}

They can be run as root or as cwisq/cwishelp, whichever you prefer.

\item Create a .private.sync with the following: 

\begin{verbatim}
	copy usr/athena/bin -f
	copy usr/athena/bin/inc -p -f 
\end{verbatim}

so that inc is local.

\end{enumerate}

\section{Maintenance}

\subsection{Periodic Maintenance}

Same as any other service that receives mail.

\subsection{Relocation}

Notify cwis-admin@mit.edu of the date of any relocation.  If you are
moving the service from {\em oldhost} to {\em newhost}, instruct them to
type

{\tt blanche cwis-request -a cwisq@}{\em oldhost}.local {\tt -d
cwisq@}{\em newhost}.local

{\tt blanche cwis-help -a cwishelp@}{\em oldhost}.local {\tt -d
cwishelp@}{\em newhost}.local

\subsection{Reconfiguration}

If cwis-admin for some reason relocates the mh folder for the cwis
queue, edit the crontab entry file and replace {\tt
/afs/athena.mit.edu/org/c/cwis/Mail/inbox} with the new path.
Similar for cwis-help.

\subsection{Restarts}

In the unlikely event that sendmail dies, you may restart it with the
following command:

\begin{verbatim}
/usr/lib/sendmail -bd -q30m
\end{verbatim}

\subsection{Updates}

If an update is needed, follow the instructions for installation.

\subsection{Shutdowns}

No special shutdown procedure.  Just remember that for as long as the
service is down, mail piles up on the mailhub.  It shouldn't make a big
difference for outages of less than a day.  After 3 days mail starts
bouncing.

\subsection{Removal from Service}

Give cwis-admin@mit.edu at least two weeks notice if you're going to
punt this service, and provide instructions for setting up the service
on a private workstation.

\subsection{Backups and Restores}

No backups needed.

\section{Troubleshooting}

\subsection{Diagnostics}

If the service fails to work, edit the crontab entry to direct errors
somewhere you can see them.

\subsection{Known/Predicted Failure Modes}

If /usr/spool/mail/cwisq does not exist, sendmail will not create it.
Same for mail/cwishelp.

\subsection{Service}

Send bug reports to the bugs@mit.edu list.

\section{State Information}

The only local state information is that the last 15 minutes or less of
mail is kept in /usr/spool/mail.

\end{document}