\begindata{text,539034680}
\textdsversion{12}
\template{default}
\define{global
}
\define{footnote

attr:[Flags OverBar Int Set]
attr:[FontSize PreviousFontSize Point -2]}
\chapter{1	Building and Installing Snapified Clients and Servers}


There are three distinct parts to building and installing snapified AMS 
interfaces.  The first involves building and installing snap, the simple 
network access protocol, the messageserver, and guardian, which allows 
snapified AMS interfaces to communicate with the messageserver.  The second 
part involves creating the administrative scripts that run guardian and the 
messageserver.  The third part involves building and installing the snapified 
AMS interfaces.


\section{1.1	Building and Installing Snap, Guardian, and the Messageserver

}
\subsection{1.1.1	Setting Andrew System Options}


Andrew system options determine what parts of the Andrew software will be 
compiled into the system binaries.  If a system option is defined, then the 
code related to that option may be built and installed; if  system option is 
not defined, code that depends on that option will be ignored.  Changes to 
Andrew system options should be made in  \typewriter{andrew/config/site.h; 
}they  will be included in the installed version of \typewriter{andyenv.h} the 
next time the the system is compiled.


It should be noted that almost every program in Andrew uses the options 
defined in \typewriter{andyenv.h}.  Therefore, when changes are made to this 
file, much of the system will have to be recompiled.


The message server requires that the following system options are defined:


\indent{\italic{AMS_ENV} - The Andrew Message System Environment.  This option 
must be on to build any part of the Andrew Message System.


\italic{SNAP_ENV }- The Snap Environment.  This option must be on to build the 
message server.

}
\subsection{1.1.2	Building and Installing the Snap, Guardian, and the 
Messageserver}


Once \italic{SNAP_ENV} has been defined, you can compile and install the 
various parts of snap, guardian, and the messageserver.  The messageserver 
depends on snap, so snap must be built first.  


The sources for snap, guardian, and various other related libraries and 
programs are located in subtrees of \typewriter{andrew/overhead/snap2}.  To 
build the software in this tree, connect to \typewriter{andrew/overhead/snap2} 
and type 

\typewriter{
make Install}


Once the programs in\typewriter{ andrew/overhead/snap2} have been successfully 
built and installed, you can build and install the messageserver.  First, 
build the messageserver libraries, by connecting to 
\typewriter{andrew/ams/lib/ms} and typing:


\typewriter{make Install}


Once you have installed the messageserver libraries, you can build the 
messageserver.  To do this, connect to \typewriter{andrew/ams/ms} and type:


\typewriter{make Install}


\section{1.2	Creating a Message Server Machine}


Snap, guardian, and the messageserver can be run from any unix machine.  In a 
distributed computing environment, it is not necessary to dedicate a machine 
to run as a message server.  In many cases, though, a dedicated message server 
machine can be useful.  For example, if a large number of users use this 
facility, a dedicated message server improves performance.  In this case a 
dedicated message server will be more secure.  This section  assumes that you 
will set up a single dedicated message server, or a group of dedicated message 
servers.  However, most of these procedures may be used to set up guardian and 
messageserver on a non-dedicated machine.


\subsection{1.2.1	Files on the Local Disk}


There are several files that should be on the local disk of the message server 
machine.:


\indent{1.  All files that were built from the\typewriter{ 
andrew/overhead/snap2} subtrees.


2. A file named \typewriter{guardian.svc} should be located on the\typewriter{ 
/etc} directory on the local disk.  This file contains a list of valid servers 
that are started and serviced by the guardian.  Some versions of the AMS 
clients only communicate with certain versions of the messageserver; the 
\typewriter{guardian.svc} file is used to match client versions to 
messageserver versions.


3. If you are running AMS delivery, a file called 
\typewriter{RemoteGuardianRequests} must be stored in the\typewriter{ /} 
(root) directory.  This file contains a single line of text.  The file is used 
to set the startup switches that control how guardian is run on the local 
server.  Please see the chapter\bold{ Administering Non-Unix Clients }for more 
information about guardian startup switches.


4. If you generate guardian daemon logs, and want to store old logs in a 
location other than the local server disk, you must write a script that moves 
the files from the local disk to the location where they are to be stored.  At 
sites that run AMS delivery this script must be called \typewriter{LogToAFS}, 
and be stored in the \typewriter{/etc} directory. 


}\paragraph{1.2.1.1	Creating a Guardian.svc file


}The file \typewriter{guardian.svc} is used to by the guardian to start 
servers that communicate with the client through the guardian.   Each server 
has a single line in this file that describes how the server process should be 
run on the server machine.


Each line in \typewriter{guardian.svc} contains five fields, each separated by 
a space:


\indent{1. The first field contains the name of the server.  For instance, if 
you are running only the most recent version of the messageserver, the first 
field in \typewriter{guardian.svc} for this server would by 
\typewriter{MESSAGESERVER}.


2. The second field defines the type of connections that this server can 
handle.  Possible values are \typewriter{AUTH_ONLY}, \typewriter{UNAUTH_ONLY}, 
 and \typewriter{BOTH}.  \typewriter{AUTH_ONLY} specifies that the server can 
be run only by an  who have AFS authentication.  \typewriter{UNAUTH_ONLY} 
specifies that the server can be run only by an owner who does not have AFS 
authentication.  \typewriter{BOTH} specifies that the server can be run by 
either an authenticated owner, or a non-authenticated owner.


3. The third field specifies whether the server process should be run setuid 
to the user who requested it.  Possible values are \typewriter{TRUE} and 
\typewriter{FALSE}.  \typewriter{TRUE} specifies that guardian should setuid 
the server to the user.  \typewriter{FALSE} specifies that the server should 
run as root.


4. The fourth field specifies the maximum number of clients that can be 
serviced by each server.  When the maximum number of clients is reached, 
guardian will start a new server to handle the next request.  The  value of 
this field is an integer greater than 0.


5. The fifth field specifies the full path location of the server.  This 
string will be used by the guardian to start the server.}


\subsection{1.2.2	Starting Guardian}


The procedure for starting a guardian daemon on the server depends on whether 
or not your site is running the AMS delivery system.  At sites that run AMS 
delivery, guardian can be started in the same script that starts the delivery 
system on the local machine.  At sites that do not run AMS delivery, the 
command to start guardian must be written into the system startup procedures.


\paragraph{1.2.2.1	Starting Guardian at Sites that Run AMS Delivery}


At sites that run AMS delivery, guardian is started from 
\typewriter{/etc/startmailsystem}.  The same script is used to start the 
queuemail daemon on local machines.  


The \typewriter{startmailsystem} script is created via the macro processing 
scripts in \typewriter{andrew/overhead/pobbconf}.   If you are running AMS 
delivery, the startmailsystem script will be run at startup time.  This script 
does two guardian related actions:


\indent{Checks to see whether the script\typewriter{ /etc/LogToAFS} exists. 
 If it does, the script is executed.


Checks for the \typewriter{/RemoteGuardianRequests} file, and uses the 
contents of the file to start the guardian daemon.  If the 
\typewriter{/RemoteGuardianRequests} file does not exist, a guardian is 
started that will not accept remote requests.

}
\paragraph{1.2.2.2	Starting Guardian at Sites that Do Not Run AMS Delivery}


If your site does not run AMS delivery, then you will have to add the commands 
to start the guardian to your system startup procedure.  Consult the chapter 
\bold{Administering Non-Unix Clients} for information on guardian startup 
switches.


\section{1.3	Building and Installing Snapified Clients 

}
It is very easy to build snapified clients that run on unix machines. 
  Snapfied AMS clients are built using almost exactly the same procedure as 
non-snapified AMS clients. 


The sources for \typewriter{cui}, the common user interface, and 
\typewriter{vui}, the visual user interface, are located in 
\typewriter{andrew/ams/msclients/cui}, and 
\typewriter{andrew/ams/msclients/vui} respectively.  The sources for 
\typewriter{messages}, the ATK-based AMS client, are located in 
\typewriter{andrew/atkams/messages}\footnote{\
\begindata{fnote,539314696}
\textdsversion{12}
You must build ATK to succesfully build messages\
\enddata{fnote,539314696}
\view{fnotev,539314696,1450,0,0}}  .  


\subsection{1.3.1	Necessary Andrew System Options}


To  build any snapified AMS clients,  you must define the Andrew system 
options \italic{AMS_ENV}, and \italic{SNAP_ENV}.  If you have built the 
necessary servers, these options will already be defined.


\subsection{1.3.2	Building the CUI Snap Library}


Before you can build any snapified AMS clients, you must build the cuisnap 
library (libcuis.a).  The sources for this library are located in 
\typewriter{andrew/ams/libs/snap}.  To build cuisnap library, connect to 
\typewriter{andrew/ams/libs/snap} and type:


\typewriter{make install

}
\subsection{1.3.3	Building  Cui and Vui


}There are several commands that can be used to build snapified versions of 
cui and vui.  The best command to use at your site will depend on the exactly 
what you want to install.


To build and install just \typewriter{cuis}, which is the snapified version of 
cui, connect to \typewriter{andrew/ams/msclients/cui}, and type


\typewriter{make cuis}


To build and install both \typewriter{cuis} and \typewriter{cuin}, which is 
the nonsnapified version of cui, connect to 
\typewriter{andrew/ams/msclients/cui} and type


\typewriter{make all}


Similarly, to build and install just \typewriter{vuis}, which is the snapified 
version of vui, connect to \typewriter{andrew/ams/msclients/vui }and type


\typewriter{make vuis}


To build and install both \typewriter{vuis} and \typewriter{vuin}, which is 
the nonsnapified version of vui, connect to 
\typewriter{andrew/ams/msclients/vui} and type


\typewriter{make all}


To build and install \typewriter{cuis}, \typewriter{cuin}, \typewriter{vuis}, 
and\typewriter{ vuin}, connect to \typewriter{andrew/ams/msclients} and type


\typewriter{make Install}


\subsection{1.3.4	Building  Messages}


To build any version of messages, ATK must be built and installed.


The first time you build messages, it is easiest to build both 
\typewriter{messagess}, which is the snapified version of messages, and 
\typewriter{messagesn}, which is the nonsnapified version of messages.  To do 
this, connect to \typewriter{andrew/atkams} and type


\typewriter{make Install}


This command builds and installs all libraries and scripts that are associated 
with messages, as well as building and installing messagess and messagesn. 
 After the libraries and scripts are in place, you can build just 
\typewriter{messagess} by connecting to \typewriter{andrew/atkams/messages/cmd} 
and typing


\typewriter{make messagess}

















\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1452,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,539034680}

.
