\begindata{text,19858780}
\textdsversion{12}
\template{help}
\define{global
}
\chapter{The AndrewSetup File: Site Configuration}


\section{What is the AndrewSetup file?}


\leftindent{The AndrewSetup file is the mechanism used for site configuration 
of the binary files that make up the software of Andrew.  This means that site 
administrators can specify various aspects of their Andrew environment without 
recompiling the system by adding or changing lines in the AndrewSetup file. 


Also, many Andrew programs, especially those involved in the Andrew Message 
System, and the help program,  read the AndrewSetup file for crucial 
site-dependent information.  Concentrating the information in a single file 
makes it easier to configure Andrew at each site. 


By recompiling all of the Andrew binaries, the site administrator can avoid 
the need for the AndrewSetup file; most of the values (but not all of them) 
have their defaults specified in the source files 
andrew/overhead/mail/lib/mailconf.c and andrew/overhead/util/lib/svcconf.c. 
 Still, it is useful to be able to reconfigure certain options without 
recompiling a large part of the system.

}\section{
}\section{ Andrew Build Options and the AndrewSetup File}


\indent{Some AndrewSetup options require that certain Andrew build options be 
included at compilation.  Andrew build options define certain environments, 
such as the availability of AFS (AFS_ENV), the desire to build the White Pages 
(WP_ENV), and the intention to run AMDS, the AMS Delivery System 
(RUN_AMDS_ENV).  For example, if the system is compiled without the "AFS_ENV" 
option, then special calls to the Andrew File System cannot be made. 
 Subsequently turning on an AndrewSetup option that says that the Andrew File 
System is running will not have any effect, because the appropriate code for 
dealing with the file system is not complied into the binaries.  When an 
AndrewSetup option depends on a build  option, this is noted in following 
documentation in a "Note" about the option.


It is impossible to turn on some options that were not enabled at compile 
time.  However,  it is possible to turn some options off at run time, even if 
they were on at compile time, by using certain AndrewSetup options.


The source file for Andrew build options is $\{ANDREWDIR\}/include/system.h.

}\leftindent{
}\section{Where is the AndrewSetup file?}


\indent{The AndrewSetup file may be located on the local disk of an AFS client 
or on a central server.  Therefore, a path search is defined in 
andrew/overhead/util/lib/config.c.    The first file found on the following 
list is used as the relevant AndrewSetup file.  If no AndrewSetup file is 
found, all the compile-time defaults will be used:

}\leftindent{
/AndrewSetup

/etc/AndrewSetup

LOCAL_ANDREW_SETUP_ENV (if this compilation option is defined)

/usr/vice/etc/AndrewSetup

DEFAULT_ANDREWDIR_ENV/etc/AndrewSetup

/usr/andrew/etc/AndrewSetup


The path search consists of four fixed elements and two compile time options; 
one of them,  LOCAL_ANDREW_SET UP_ENV, may contain several more elements.  The 
other compile time option depends on the value of DEFAULT_ANDREWDIR_ENV, which 
defaults to "/usr/andrew" in andrew/config/allsys.h.  You may define 
LOCAL_ANDREW_SETUP_ENV or DEFAULT_ANDREWDIR_ENV by editing your 
andrew/config/site.h file.


}\section{What goes into the AndrewSetup file?}


\leftindent{There are many options that can be set in the AndrewSetup file. 
 They are broken down here into the following categories:


\leftindent{Basic Andrew Configuration

Andrew File System Configuration

Printing Configuration

Help Configuration

Site Policy

Bulletin Board Database

Message System Printer Name Validation

Mail Address Validation

Mail Delivery System Configuration

}
The options in the AndrewSetup file are in the form:


keyword: value


In general, the keyword is not case-sensitive, but the values may well be (if 
they are file names).  Booleans may be specified as yes/1/true or no/0/false.


White space (space and tab characters) is not permitted in front of the 
keyword, within the keyword or before the colon.  Between the colon and the 
value there may be any amount of white space (including none).  For keywords 
that have multiple values separated by commas, spaces between the commas and 
the values (on either side of the comma) are not significant.


Although the options and their values in this help document are printed in 
italic, there should be no formatting in the AndrewSetup file.}


\section{Basic Andrew Configuration}


\leftindent{\italic{ANDREWDIR: pathname

}\leftindent{Default: /usr/andrew

This specifies the directory where Andrew software exists on your system.  The 
reason this is a configuration option in addition to an environment variable 
is that environment variables are not accessible to programs not descended 
from your login shell.  Several Andrew programs, notably the messageserver, 
pcserver, and anything spawned by those processes, are not descended from your 
login shell.}


\italic{LOCALDIR: pathname}

\indent{Default: /usr/local

This specifies the directory where local files and programs exist on your 
system.

}
\italic{Venus: boolean}

\leftindent{Default: yes

"Yes" specifies that the workstation is running the Andrew Cache Manager and 
that Console expects to get its error messages and mariner information via UDP 
sockets.  "No" specifies that the workstation is running a process venus and 
that Console expects to get its error messages and mariner information via TCP 
sockets.

}
\italic{ThisDomain: string

}\leftindent{Default: ^

This gives the fully qualified internet domain name to which all options in 
the AndrewSetup file apply.   ThisDomain can be set to a text string in the 
form of a fully qualified internet domain name, or to one of three special 
characters.  The character "*" will be replaced by the fully qualified domain 
name of the workstation (see ThisDomainSuffix, below).  The character "&" will 
be replaced by the name of the AFS cell to which the workstation belongs if 
AFS is running; otherwise, it will be replaced by the fully qualified domain 
name of the workstation (see ThisDomainSuffix, below).  The character "^" will 
be replaced by the cell name if AFS is running and either the option 
AMS_DefaultToAFSCellMail is set to "yes" or AMS_LocalMailSystemExists is set 
to "no".  Otherwise, "^" will be replaced by the workstation name (see 
ThisDomainSuffix, below).  In all three cases, the workstation name will be 
obtained as the result of the gethostname(2) system call, which should be a 
fully-qualified domain name.


}\italic{ThisDomainSuffix: string

}\leftindent{Default: none

When AMS or the WP wants to know the fully-qualified domain name of the 
current workstation, including when it's figuring out what ThisDomain is, it 
generates that full domain name as follows.  First it issues the 
gethostname(2) system call.  Then it builds a candidate suffix for that name, 
first by looking for the AndrewSetup variable ThisDomainSuffix (default value: 
none), and then, if that wasn't found and the compile-time variable 
GETDOMAIN_ENV is set, by issuing the getdomainname(2) system call.  If the 
result of that search for a suffix results in a non-null name that is also 
neither the single-character string ``.'' nor a name that is already the 
suffix of the gethostname(2) result, the suffix is appended to the 
gethostname(2) result to generate the full domain name of the workstation.


Thus, for example, in systems in which gethostname(2) is not set to the 
fully-qualified domain name of a workstation, ThisDomainSuffix may be set to 
the necessary domain-system qualifier.  For example, if on zeus.toaster.com 
gethostname(2) returns ``zeus'', ThisDomainSuffix may be set to 
``toaster.com''.  If the getdomainname(2) result is undesirable in this 
context (for example, if the domain name to which it refers has little to do 
with the internet domain system), its use may be disabled either by undefining 
GETDOMAIN_ENV or by setting ThisDomainSuffix to the one-character string 
``.''.


}\italic{AMS_UseWP: boolean

}\leftindent{Default: see Note

"Yes" specifies that the White Pages are to be used for user id to login name 
translation, and for cross-cell versions of getcpw*, and getvpw*.  "No" 
specifies that the White Pages are not to be used.

\bold{Note:}  If compiled with WHITEPAGES_ENV then the default is "yes."  If 
compiled without WHITEPAGES_ENV the default is "no" and cannot be set to 
"yes."}


\italic{ThisDomainWPDirectory: string

}\leftindent{Default: none

Normally, the White Pages database for some domain DOMAINNAME (often 
ThisDomain) is found in directory

	/afs/DOMAINNAME/service/wp

Sites that have wanted to use the White Pages without using AFS have had to 
fabricate this path name on their systems.  However, as a special case, the 
Andrew installer may set the ThisDomainWPDirectory to be the name of the 
directory in which the White Pages for domain ThisDomain may be found.

}
\italic{AMS_OnAIX: boolean

}\leftindent{Default: no

"No" specifies that the AIX variant of the UNIX operating system is not being 
used.  "Yes" specifies that AIX is being used.}


\italic{AMS_NonAMSDelivery: boolean

}\leftindent{Default: see Note

"No" specifies that ThisDomain is running the AMS delivery system.  "Yes" 
specifies that ThisDomain is not running the AMS delivery system.  This option 
is used by Console to determine where to monitor new mail.  On a system that 
runs AMS delivery, Console monitors a Mailbox directory.  On a system that 
doesn't run AMS delivery, Console monitors a mail file.

\bold{Note:} If compiled with RUN_AMDS_ENV the default is "no".  If compiled 
without RUN_AMDS_ENV the default is "yes" and cannot be changed to "no".}


\italic{AMS_LocalMailSystemExists: boolean}\leftindent{

Default: see Note

"Yes" specifies that an AFS client machine runs its own mail system that is 
separate from the mail system of the AFS cell to which it is connected. This 
option can be "yes" even if the AFS cell runs AMS delivery, as long as the AFS 
client retains its own mail system to interpret local mail addresses.   "No" 
specifies that the AFS client does not run a separate mail system.

\bold{Note:} If ThisDomain is set to the AFS client name, and the client name 
is different from the cell name, or if AMS_NonViceHost is "yes", then the 
default is "yes".  Otherwise, the default is "no".}

\leftindent{
}}\indent{\italic{AMS_DefaultToAFSCellMail: boolean}\leftindent{

Default: see Note

This option tells AMS whether to use a user's workstation authentication or 
the AFS authentication in the connected cell to find the location where a user 
receives and files mail when the user has not specified an *.AMSHome 
preference.  Preferences are read from the first file found on the following 
list: $HOME/preferences, $HOME/.preferences,  $HOME/.Xdefaults.

}}\indent{\indent{\bold{Note: } If compiled with RUN_AMDS_ENV, the default is 
yes.  If compiled without RUN_AMDS_ENV  the default is "no". 

\leftindent{
}}}\leftindent{\italic{AMS_WSRunsQueuemail: boolean}\leftindent{

Default: see Note

"Yes" specifies that local workstations run a queuemail daemon.  "No" 
specifies that local workstations do not run a queuemail daemon.  This option 
can be used to speed-up delivery of mail from a workstation connected to a 
cell that is not running AMS delivery for a user whose AMS Home is a cell that 
runs AMS delivery.

\bold{Note:} If compiled with RUN_AMDS_ENV, the default is "yes", if compiled 
without RUN_AMDS_ENV, the default is "no".

}
\italic{AMS_ThisDomainAuthFromWS: boolean}

\indent{Default: see Note

"Yes" specifies that, when a user sends a message from a workstation whose 
name is different from \italic{ThisDomain}, the user will be identified as 
"userid@\italic{ThisDomain"} in the "From: " line of the message.   If the 
system is compiled with AFS_ENV, the user will be identified as 
"userid@\italic{ThisDomain}" even if he is not authenticated in 
\italic{ThisDomain}.    "No" specifies that the user must be authenticated in 
\italic{ThisDomain} to be identified as "userid@\italic{ThisDomain}" in the 
"From: " line of a message.

\bold{Note:} If compiled with AFS_ENV, the default is "no".  If compiled 
without AFS_ENV, the default is "yes".

}
\italic{Print.NonAndrew: boolean}

\indent{Default: no

"No" specifies that standard UNIX printing is not used, and Console will 
attempt to monitor a user's outstanding print requests by checking for files 
in the user's PrintDir directory.  "Yes" specifies that standard UNIX printing 
is not in use, and Console will not try to monitor a user's outstanding 
printing requests.  

}
}\section{Andrew File System Configuration}\leftindent{


\italic{AMS_NonViceHost: boolean

}\leftindent{Default: see Note

 "Yes" specifies that the Andrew File System is not is use.  "No" specifies 
that the Andrew File System is in use.  If AMS_NonViceHost is "no", then an 
experiment is performed at runtime to ensure that the pioctl() system call 
doesn't generate a SIGSYS signal.  If it does, the AMS_NonViceHost is set to 
"yes".

\bold{Note:} If compiled with AFS_ENV the default is "no" and can be changed 
to "yes."  If compiled without AFS_ENV the default is "yes" and cannot be 
changed to "no".}


\italic{ViceFile: pathname

}\leftindent{Default: see Note

This specifies the name of a file guaranteed to be in the Andrew File System, 
if you are using it.

\bold{Note}:  If the file /usr/vice/etc/cacheinfo is present, the default is 
the contents of this file up to the first colon.  If /usr/vice/etc/cacheinfo 
is not present, the default is "/afs".}

}
\section{Printing Configuration\leftindent{

}}
\leftindent{\italic{PrinterType: string}

\leftindent{Default: psc

The default printer type string that will be passed to troff.  The printing 
software look for a file named ".PrinterType " in the print spooling 
directory.  If it finds this, it will use it to override the 
default.}\leftindent{\quotation{

}}
\italic{FormatCommand:string}

\leftindent{Default: eqn -T$PRINTERTYPE /tmp/%s.n | troff -T$PRINTERTYPE - | 

This string is used as a template to sprintf for the purposes of indicating 
how the output is to be formatted for printing and previewing. The %s string 
will be replaced by the base name of the input file, resulting in the proper 
name for the temporary troff file. Note that the default assumes that ditroff 
has been linked to the name troff. The PRINTERTYPE environment will be set in 
the shell by print.do module as outlined above. }


\italic{TroffFontMapFile:string

}\leftindent{Default: $\{ANDREWDIR\}/lib/tmac/PrintFontMap

This defines the location of the file used to map display fonts into troff 
fonts. 

}
\italic{PrintCommand:string}

\leftindent{Default: lpr -n

The default print command that will receive the output from ditroff, which may 
contain embedded troff.  At CMU we use a print command that takes a -O %s 
argument, to inform it the name of the file to put on the cover sheet.

}
\italic{PSCPrintCommand:string}

\leftindent{Default: lpr

The default print command for pure PostScript.  Not generally used. 

}
\italic{PreviewCommand:string}

\leftindent{Default:preview -o %s 

The default preview  command, that is fed the output of the format command 
above.  Sites with interactive postscript previewers may wish to play with 
this. }


\italic{SpoolPath:string}

\leftindent{Default: /usr/spool/ }

\italic{Printer:string}

\leftindent{Default: lpr 

The default spool path and directory within that spoolpath.  If the variable 
"PRINTER" is defined in the user's environment, the software will use this as 
the PRINTER.  This is only used by the ATK print module to determine the 
PRINTERTYPE, as above.  The PRINTCOMMAND  is responsible for the actual 
spooling. }}

\leftindent{
}\section{Help Configuration}


\indent{\italic{HelpIndex: string}

\indent{Default: /lib/help.index

This specifies the location in $\{ANDREWDIR\} of the help index.  For example, 
the default "/lib/help.index" specifies that the help index is located in 
\{ANDREWDIR\}/lib/help.index.

}
\italic{HelpLib: string}

\indent{Default: /lib

This specifies the subdirectory of $\{ANDREWDIR\} in which the panel setup 
files are located.

}
\italic{HelpDir: string}

\indent{Default: /help

This specifies the subdirectory of $\{ANDREWDIR\} in which the help files are 
located.

}
 \italic{HelpChangeDir: string}

\indent{Default: /help

This specifies subdirectory of $\{LOCALDIR\} in which "change" documents are 
located.  Change documents describe updates to programs and applications.}


\italic{HelpTutorialDir: string}

\indent{Default: /help

This specifies the subdirectory of $\{ANDREWDIR\} in which tutorials are 
located.

}
\italic{HelpSendCommentOnAddress: string}

\indent{Default: HelpComments+@andrew.cmu.edu

This specifies the mailing address for comments submitted via the "Send 
Comment on Help" command.

}}
\section{Site Policy}


\leftindent{\italic{AMS_UseShortFileNames: boolean

}}\leftindent{\leftindent{Default: no

"Yes" specifies that the Andrew Message System and other applications should 
"try to" keep all file names under 14 characters.  "No" specifies that they 
should not try to keep file names short, and probably won't.}


\italic{AMS_UsersAreGrownups: boolean

}\leftindent{Default: no

"No" specifies that the Andrew Message System should try to force people to 
read the "networks-access" help file, which contains hints on network mail 
etiquette and warnings about chain letters and solicitations, before allowing 
them to send external mail. "Yes" specifies that no restrictions on access to 
external networks are enforced by the Andrew Message System.}


\italic{AMS_UsersHandleFormatting: boolean}\indent{

}\leftindent{Default: see Note

"Yes" specifies that users in ThisDomain can be expected to receive 
ATK-formatted mail without complaint.  "No" specifies that local users cannot 
receive ATK-formatted mail without complaint.

\bold{Note}: If compiled with RUN_AMDS_ENV, the default is "yes".  If compiled 
without RUN_AMDS_ENV, the default is "no".

}
\italic{AMS_DevConsoleIsSacred: boolean

}\leftindent{Default: no

"Yes" specifies that the Andrew Message System should not try to send its 
error messages to /dev/console as a last resort.  "No" specifies that the 
Andrew Message System may try to send its messages to /dev/console as a last 
resort.}


\italic{WPIUpdateReqAddr: string}

\indent{Default: see Note

This string is the mailing address to which automatic White Pages change 
requests are submitted.

\bold{Note:} If compiled with CMU_ENV, the default is 
"wd00+WPI-UPDATE-REQUEST@andrew.cmu.edu".  If not compiled with CMU_ENV, the 
default is "postmaster".

}
\italic{MessagesAutoBugAddress: string

}\leftindent{Default: see Note

This string is the mailing address to which automatic bug reports from the 
Messages program should be directed.  If it is null, the option to send a bug 
report will not appear.

\bold{Note:} If compiled with CMU_ENV the default is 
"postman+auto-messages-bugs@andrew.cmu.edu".  If compiled without CMU_ENV the 
default is "postmaster".}


\italic{WelcomeMailFile: pathname

}\leftindent{Default: $\{ANDREWDIR\}/lib/Hello

This specifies the name of the file that contains a piece of mail that can be 
given to each new user of the system as his or her first piece of mail. A 
multi-media message is provided, and installed in the appropriate place, with 
the standard Andrew distribution.   This mail is placed in a user's Mailbox or 
mailfile when the mail folder is created.

}
\italic{AMS_OnlyMail: boolean

}\leftindent{Default: see Note

"No" specifies that reading of anything other than mail (e.g. bboards) is not 
prohibited.  "Yes" specifies that use of the Andrew Message System to read 
anything other than mail should be prohibited.

\bold{Note:} If compiled with RUN_AMDS_ENV the default is "no".  If compiled 
without RUN_AMDS_ENV, the default is "yes". 


}}\indent{\italic{AMS_InitialDeathKnell:  integer}

\indent{Default: 1800

Specifies the initial time limit in seconds for the messageserver's DeathKnell 
value.  In this case, the default is thirty minutes. The DeathKnell value is 
the length of time in seconds that a messageserver can be inactive before it 
times out.

}
\italic{AMS_MaximumDeathKnell: integer}

\indent{Default: 3600

Specifies the maximum time limit in seconds for the DeathKnell.  In this case, 
the default is one hour. The DeathKnell can be set by the user who starts the 
messageserver, by using the ms.deathknell preference option.  This preference 
option may be set to any length of time less than or equal to the 
AMS_MaximumDeathKnell.

}
}\section{Bulletin Board Database}


\leftindent{\italic{LocalBboardRoot: pathname

}}\leftindent{\leftindent{Default: /afs/andrew.cmu.edu/usr0/bb/.MESSAGES

Specifies the pathname to where the local bboard tree is rooted.}


\italic{ExternalBboardRoot: pathname}

\leftindent{Default: /afs/andrew.cmu.edu/usr0/netbb/.MESSAGES

Specifies the pathname to where the external bboard tree is rooted.}


\italic{OfficialBboardRoot: pathname}

\leftindent{Default: /afs/andrew.cmu.edu/usr0/bb/off/.MESSAGES

Specifies the pathname to where the official bboard tree is rooted.}


\italic{OldLocalBboardRoot: pathname}

\leftindent{Default: /cmu/itc/bb/.MESSAGES

The previous value of the LocalBboardRoot before it was last moved. }


\italic{OldExternalBboardRoot: pathname}

\leftindent{Default: /cmu/itc/netbb/.MESSAGES

The previous value of the ExternalBboardRoot before it was last moved.}


\italic{OldOfficialBboardRoot: pathname}

\leftindent{Default: /cmu/itc/bb/off/.MESSAGES

The previous value of the OfficialBboardRoot before it was last moved.}


\italic{DefaultMSPath: pathname}

\leftindent{Default: see Note

Specifies the default path giving the roots of all the message trees a user 
will be able to see.  Users can override this with their *.mspath preference.

\bold{Note:} If compiled with RUN_AMDS_ENV the default is 
"$MAIL:$OFFICIAL:$LOCAL:$EXTERNAL".  If compiled without RUN_AMDS_ENV the 
default is "$MAIL".}


\italic{RequiredSubsFile: pathname}

\leftindent{Default: $\{LOCALDIR\}/lib/RequiredSubscriptions

Specifies the pathname to a file which lists the bboards to which everyone at 
a site is required to subscribe.  Each line in that file is of the form 
\italic{shortname:pathname. }}


\italic{ChangedSubsFile: pathname}

\leftindent{Default: see Note

Specifies the pathname to the file where changes to the location of bboards 
are listed.  Each line of that file is of the form\italic{ oldname newname 
comment}.  When a user subscribes to a bboard and that bboard ceases to exist, 
he or she will usually get a "delete your subscription?" question, but if 
there is an  entry in this file the user will get a "change your subscription 
to a new location?" question, instead.

\bold{Note}: If compiled with CMU_ENV, the default is 
"afs/andrew.cmu.edu/usr0/postman/ChangedSubscriptions".  if compiled without 
CMU_ENV, the default is "/usr/postman/ChangedSubscriptions".}}


\section{Message System Printer Name Validation}


\leftindent{When a user chooses the \bold{Set Printer }command in an Andrew 
Message System program, the messageserver  tries to make sure that the named 
printer exists.  The following options affect that check.  A printer name is 
only considered invalid if it cannot be found after passing through all of the 
allowed options.

}
\leftindent{\italic{AMS_PrinterNamesInSpoolDirectories: boolean

}}\leftindent{\leftindent{Default: yes

"Yes" specifies that there are print spooling directories and that each 
subdirectory in the spooling directory corresponds to a printer of the same 
name.  The names of the print spooling directories are listed by the option 
AMS_PrintSpoolDirectories. "No" specifies that printer names can not be found 
in spool directories.

}
\italic{AMS_PrintSpoolDirectories: string

}\leftindent{Default: see Note

This specifies a list of directories in which the per-printer subdirectories 
can be found.

\bold{Note:} If compiled with CMU_ENV, the default is 
"/afs/andrew.cmu.edu/service/printing/spool", NULL.  If compiled without 
CMU_ENV, the default is NULL.}


\italic{AMS_PrinterNamesInPrintcap: boolean

}\leftindent{Default: yes

"Yes" specifies that the  /etc/printcap  file may be used to determine the 
names of valid printers on the system.  "No" specifies that /etc/printcap will 
not be used to determine the names of valid printers on the system.}


\italic{AMS_NamedValidPrinters: string

}\leftindent{Default: NULL

This is an explicit list of printers, separated by commas.  All of the 
printers named in this line are considered valid by the messageserver.}}


\section{Address Validation}


\indent{The process of validating mail is site-dependent, and may be 
controlled by the following options.  There are two things that can be 
validated: names of remote hosts and local addresses.  When a user types a 
destination address and sends a message, the messageserver tries to "validate" 
the address to make sure that it is a valid mail address before handing it off 
to the delivery system.  This informs the user immediately of some common 
kinds of address errors. 

}\leftindent{
\bold{Remote Host Name Validation}


\italic{AMS_ValidateDestHosts: boolean

}\leftindent{Default: yes

"Yes" specifies that some form of hostname validation takes place.  "No" 
specifies that all forms of hostname validation are turned off.  If the value 
is set to "no," all other hostname validation options are irrelevant.}


\italic{AMS_HardHostValidationErrors: boolean

}\leftindent{Default: yes

"Yes" specifies that if host name validation fails, an error results and the 
mail should not be sent.  "No" specifies that if host name validation fails, a 
"soft" error should be ask the user to confirm that he or she is sure that the 
host really exists before sending the mail.  The "no" option is useful if the 
delivery system being used supports some strange addresses not accessible to 
the validation routine.}


\italic{AMS_UUCPSupported: boolean

}\leftindent{Default: no

"No" specifies that UUCP-style addresses (foo!bar!baz) are not considered 
external addresses.  "Yes" specifies that a UUCP-style address is considered 
an external address.}


The following validation options listed in the AndrewSetup file will be 
attempted in the order they appear here until the host is validated.  A host 
is only considered invalid if it remains unvalidated after passing through all 
of the allowed validation mechanisms unsuccessfully.


\italic{AMS_ValidDomainSuffixes: string

}\leftindent{Default: see Note

The list specified should be a list of domain suffixes separated by commas 
that should be considered "always valid" in host name validation.  This is 
useful if your delivery system uses a non-standard method for supporting 
non-domain addresses, like "foo.bitnet" for all Bitnet hosts.  

\bold{Note: } When compiled with CMU_ENV, the default is ".bitnet".  When 
compiled without CMU_ENV, the default is NULL.  The AMS_ValidDomainSuffixes 
option should always be used in conjunction with AMS_ValidDomainRelays.}


\italic{AMS_ValidDomainRelays: list

}\leftindent{Default: see Note

The list should parallel the list for AMS_ValidDomainSuffixes with a list of 
mail relay machines to which addresses with the given suffix should be sent.

\bold{Note:} If compiled with CMU_ENV, the default is "vma.cc.cmu.edu".  If 
compiled without CMU_ENV, the default is NULL. The AMS_ValidDomainRelays 
option is only interpreted by the AMS delivery system.

}
\italic{AMS_DeliveryViaDomainMXAddress: boolean

}\leftindent{Default: see Note

"Yes" specifies that host names are valid if the domain system says that they 
have either a valid MX record or a valid IP address record.  "No" specifies 
that MX or IP address records in the Internet domain system  are not checked 
in the process of validating an address.

\bold{Note:} If compiled with RESOLVER_ENV the default is "yes" and can be 
changed to "no."  If compiled without RESOLVER_ENV the default is "no" and can 
not be meaningfully changed to "yes."}


\italic{AMS_DeliveryViaDomainAddress: boolean

}\leftindent{Default: see Note

"Yes" specifies that host names are valid if the domain system says that they 
have a valid IP address via the domain system.  "No" specifies that host names 
are not checked   for an IP address via the domain system. 

\bold{Note:} If compiled with RESOLVER_ENV the default is "yes" and can be 
changed to "no."  If compiled without RESOLVER_ENV the default is "no" and can 
not be meaningfully changed to "yes."}


\italic{AMS_DeliveryViaHostTable: boolean

}\leftindent{Default: yes

"Yes" specifies that host names can be validated by looking for them in 
/etc/hosts.  "No" specifies that host names should not be validated by looking 
in /etc/hosts.}


\italic{AMS_DeliveryViaGethostbyname: boolean

}\leftindent{Default: no

"No" specifies that host names can not be validated by the local site's 
gethostbyname(3) function.  "Yes" specifies that host names can be validated 
by the local site's gethostbyname function.  This is for sites where 
gethostbyname consults sources of information not referred to by the other 
AndrewSetup AMS_DeliveryVia options, such as Sun's Yellow Pages.}


\bold{Local Address Validation}


\italic{AMS_NameSeparator: integer

}\leftindent{Default: -1

If greater than 0, validated local addresses are written by replacing spaces 
in the pw_gecos field with the ASCII character cooresponding to this integer. 
 For example, if set to 46 a period character will be used to replace the 
spaces in the pw_gecos field.  Other popular choices are underscores (95) and 
spaces (32).   The default of -1 specifies that validated local addresses will 
be written as the pw_name value. }


\italic{AMS_GecosHacks: boolean

}\leftindent{Default: see Note

"No" specifies that the entire pw_gecos field of a line in /etc/passwd is 
considered to be a user name when validating local addresses.  "Yes" specifies 
that the AMS will try to understand the pw_gecos field and extract a user name 
from it, using the standard BSD or SystemV conventions.

\bold{Note:} If compiled with RUN_AMDS_ENV the default is "no".  If compiled 
without RUN_AMDS_ENV the default is "yes".   Note also that if  /etc/passwd is 
configured in standard Berkeley or SystemV formats, the pw_gecos field may 
contain information besides a user name.  

}}\indent{
}\indent{\italic{ AMS_AliasesValidation: boolean}}\indent{

\indent{Default: see Note

"Yes" specifies that /usr/lib/aliases may be used for local validation.  "No" 
specifies that /usr/lib/aliases is not used for local validation.  If this 
option is "yes", validation via /usr/lib/aliases is always tried before other 
validation mechanisms.

\bold{Note: } If compiled with RUN_AMDS_ENV, the default is "no".  if compiled 
without RUN_AMDS_ENV, the default is "yes".

}}\indent{\indent{
}}The next three options are used to determine how local addresses are 
validated.  All three values take an integer as an option.  Options with a 
value of zero are not used for local address validation.  Options with values 
greater than zero are taken in order from smallest value to largest.  If two 
options are assigned the same number, they are taken in arbitrary order. 
  Names are considered valid if they can be validated by any of the following 
options whose value is greater than 0.


\leftindent{\italic{AMS_WPValidation: integer

}\leftindent{Default: see Note

A value greater than 0 specifies that the White Pages may be used in local 
name validation.  0 specifies that the White Pages will not be used in local 
name validation.

\bold{Note: } If compiled with RUN_AMDS_ENV the default is "1".  If compiled 
without RUN_AMDS_ENV the default is "0."}


\italic{AMS_PasswdValidation: integer

}\leftindent{Default: see Note

A value greater than 0  specifies that /etc/passwd may be used for local 
validation. "0" specifies that /etc/passwd is not used for local validation.  

\bold{Note:}  If compiled with RUN_AMDS_ENV the default is "0".  If compiled 
without RUN_AMDS_ENV the default is "1."}


\italic{AMS_LocalDatabaseValidation: integer

}\leftindent{Default: 0

A value greater than 0 specifies that there is a local mechanism for local 
name validation being used.  0 specifies that there is no other local 
mechanism for local name validation being used. 

\bold{Note: } If you want to use this option you must change the procedure 
LookupInLocalDatabase in "andrew/ams/libs/ms/mswp.c" to implement your local 
mechanism.

}
}\section{Configuring a Delivery System}


\leftindent{The AMS can be made to run on top of several very different 
delivery systems.  Delivery systems differ primarily in two ways: how new mail 
is read in, and how mail is sent.  The following sets of configuration options 
are described in this section:


AMS delivery

Standard Unix mail delivery

Some other delivery system


\bold{AMS Delivery


}The options in this section are only used when the AMS delivery system is 
running.


\italic{PostmasterName: string

}\leftindent{Default: "postman"

This string is the userid of the postmaster account.

\bold{Note:} This option is not relevant unless compiled with both AFS_ENV and 
RUN_AMDS_ENV.


}\italic{PostmasterTitle: string}

\indent{Default: Postmaster

This specifies the title for the system postmaster.  This value is used in 
generating certain mail headers for automatically-generated error report 
messages.

}
\italic{PostmasterMailbox: pathname}

\indent{Default: /afs/andrew.cmu.edu/usr0/postman/Mailbox

This specifies the pathname for the local postmaster's mail dropoff directory. 
 PostmasterMailbox is used to receive automatically-generated error report 
messages.

}
\italic{LocalQueue: pathname}

\indent{Default: /usr/spool/ViceMsgQueue

This specifies the location of the mail delivery queue on the local 
workstation.

}
\italic{vicemail: pathname}

\indent{Default: $\{ANDREWDIR\}/etc/vicemail

This specifies the location of the vicemail program.

}
\italic{trymail: pathname}

\indent{Default: $\{ANDREWDIR\}/etc/trymail

This specifies the location of the trymail program.

}
\italic{switchmail: pathname}

\indent{Default: $\{ANDREWDIR\}/etc/switchmail

This specifies the location of the switchmail program.

}
\italic{queuemail: pathname}

\indent{Default: /etc/queuemail

This specifies the location of the queuemail program.

}
\italic{logpgm: pathname}

\indent{Default: $\{ANDREWDIR\}/bin/log

This specifies the location of the log program.  

}
\italic{arpadatepgm:  pathname}

\indent{Default: $\{ANDREWDIR\}/etc/arpadate

Specifies the location of the arpadate program.

}\indent{
}\italic{nntpxmit: pathname}\indent{

Default: $\{ANDREWDIR\}/etc/nntpxmit

Specifies the location of the nntpxmit program.


}\italic{DuplicateDB:  pathname}

\indent{Default: /usr/spool/log

This specifies the location of the duplicate-delivery database.

}
\italic{SentSuffix: string}

\indent{Default: SENT

Specifies the file name for the database that identifies delivered messages. 
 This database is in DBM format.

}
\italic{NNTPSuffix: string}

\indent{Default: NNTP

Specifies the file name for the database for received netnews articles.  This 
database is in DBM format.

}
\italic{CaptSuffix: string}

\indent{Default: Captured

Specifies the filename for a log of the "From:" lines of all mail.

}
\italic{MailboxName: string}

\indent{Default: Mailbox

Specifies the subdirectory for mail delivery in the user's home directory.

}
\italic{lastDitchPrefixes: string}

\indent{Default:  see Note

Specifies  where queuemail error notices will be filed, when all else fails.

\bold{Note:} If compiled with CMU_ENV, the default is 
"/afs/andrew.cmu.edu/usr0/postman/errors","/usr/spool/MailErrors".  If 
compiled without CMU_ENV, the default is "/usr/spool/MailErrors".

}
\italic{bailoutPrefixes: string}

\indent{Default: see Note

Specifies where vicemail error notices will be filed, when all else fails.

\bold{Note}: If compiled with CMU_ENV, the default is 
"/afs/andrew.cmu.edu/usr0/postman/errors","/usr/spool/MailErrors","/tmp", 
"/usr/tmp".  If compiled without CMU_ENV, the default is 
"/usr/spool/MailErrors","/tmp", "/usr/tmp".


}\italic{ForwardingName: string}

\indent{Default: .forward

Specifies the file in a user's home directory to check for mail forwarding 
information. 

}
\italic{OutgoingName: string}

\indent{Default: .Outgoing}

\indent{Specifies the subdirectory, in each user's home directory, in which 
outgoing messages from the user are queued.

}
\italic{Organization: string}

\indent{Default: see Note

Specifies the string for the Organization header for netnews messages.

\bold{Note:} If compiled with CMU_ENV, the default is "Carnegie Mellon, 
Pittsburgh, PA".  If compiled without CMU_ENV, the default is "Andrew Message 
System"

}
\italic{NNTPhost:  string}

\indent{Default: see Note

Specifies the domain name of the machine that the local system polls for 
netnews.

\bold{Note:} If compiled with CMU_ENV, the default is "pt.cs.cmu.edu".  If 
compiled without CMU_ENV, the default is "news.yoursite.edu".

}
\italic{NNPTuser: string}

\indent{Default: see Note

Specifies the default poster of netnews on the local system.

\bold{Note:} If compiled with CMU_ENV, the default is "postman+".  if compiled 
without CMU_ENV, the default is "postmaster".


}\italic{DefaultSurfaceAddress: string}

\indent{Default: see Note

Specifies the default address for non-electronic mail for users of the local 
system.

\bold{Note}: If compiled with CMU_ENV, the default is "Campus Mail, Carnegie 
Mellon, Pittsburgh, PA 15213".  If compiled without CMU_ENV, the default is 
"Anytown, Anywhere".

}
\italic{AMS_ViceQueueLifetime: number}

\indent{Default: 691200

The number represents the amount of time, in seconds, that a message will be 
left in an Andrew File System mail queue before being rejected to the sender 
for "normal" reasons. In this case, the default is eight days.  A recipient 
being over quota and unable to receive mail is considered a "normal" reason.  

}
\italic{AMS_ExtraViceQueueLifetime: number}

\indent{Default: 432000

The number represents the amount of time, in seconds, in addition to the 
ViceQueueLifetime, that a message will be left in an Andrew File System mail 
queue before being rejected for "abnormal" reasons.    In this case, the 
default is five days.  The mail is rejected to the postmaster, not the sender. 


}
\italic{AMS_CrossCellQueueLifetime: number}

\indent{Default: 28800

The number represents the amount of time, in seconds, that a message will be 

}
left in an Andrew File System mail queue awaiting delivery directly into a 
cooperating AFS cell (running AMDS).  This behavior is useful when remote AFS 
cells are defined locally, but the servers for those cells are not yet 
running.  The default value is eight hours. \italic{AMS_ViceQueueLifetimeCap: 
number}

\indent{Default: 2246400

The number represents the amount of time, in seconds, that a message is 
seriously considered to have been left in an Andrew File System mail queue. 
 In this case, the default is twenty-six days.  If a message looks like it has 
been in the queue longer than this amount, it is simply left in the queue. 
 For example, if a file appears to have been in a queue for ten years, it is 
more likely that there is a problem with a clock, rather than with mail 
delivery.   

}
\subheading{Standard Unix mail Delivery

}
Because no site is quite the same as the "standard distribution," there are 
several options that can be used to tell AMS where to find new mail, and how 
to read mail from that location.


\italic{AMS_MailBoxPrefix: pathname}

\indent{Default: see Note

Specifies the prefix for mail reading on machines that are not running AMS 
delivery. For each userid, mail is read from 
$\{AMS_MailBoxPrefix\}/\italic{userid}.

\bold{Note:} On machines running SystemV Unix, the default is "/usr/mail".  On 
machines running BSD Unix , the default is "/usr/spool/mail".

}

Standard unix mail delivers mail by appending it to 
$\{AMS_MailBoxPrefix\}/\italic{userid}.  Because the mail is simply appended, 
there is no foolproof algorithm for determining where one piece of mail stops 
and another begins.  Different mail delivery agents use a variety of 
conventions for determining this boundary.  Many mail delivery agents assume 
that a line starting with "From " is the beginning of a new piece of mail. 
 Depending on the method used by your delivery system, many of the following 
options may be used to tailor AMS to work with your delivery agent. 


\italic{AMS_DemandSeparatingCharacter: boolean}

\indent{Default: no}

\indent{"Yes" specifies that the messageserver assumes that someone has 
changed the local delivery system so that files in 
$\{AMS_MailBoxPrefix\}/\italic{userid} will have the mail pieces separated by 
a designated separating character.  By default this character is ^C, but it 
can be changed using the following option.

}
\italic{AMS_SeparatingCharacter: integer}

\indent{Default: 3

An integer specifying the above mentioned separating character as an ASCII 
value. 

}
\italic{AMS_CheckAddressInSeparatingFrom: boolean}

\indent{Default: yes

"Yes" specifies that the "From" line which apparently starts a new piece of 
mail should have a reasonable looking address before it is considered the 
start of new mail.  "No" specifies that the "From " line is not checked.

}
\italic{AMS_CheckDateInSeparatingFrom: boolean}

\indent{Default: yes

"Yes" specifies that the "From" line which apparently starts a new piece of 
mail should have a date before it is considered the start of new mail.  "No" 
specifies that the "From" line is not checked.

}
\italic{AMS_AllowColonInSeparatingFrom: boolean}

\indent{Default: no

"No" specifies that the only thing to look for is "From ".  "Yes" specifies 
that the "From" line separating pieces of mail may start with either "From:" 
or  "From  ".


}\italic{AMS_StrictStandaloneLocking: boolean}

\indent{Default: no

"Yes" specifies that a serious attempt should be made to safely lock the 
$\{AMS_MailBoxPrefix\}/\italic{userid} file before accessing information in 
it.

\bold{Note:} In the standard system, strict locking is possible only if 
$\{AMS_MailBoxPrefix\} is writable by everyone.

}
\italic{SpoolMailLockTemp: pathname}

\indent{Default: /usr/tmp/AMS_XXXXXX

This specifies the pathname to a file where BSD format mail files get linked 
during the locking process.  It should be a template for mktemp.  This might 
not work if that isn't on the same partition as $\{AMS_MailBoxPrefix\}. 
 Suggestions on how to better configure this are welcome.

}
\subheading{Some Other Delivery System}


As stated above, AMS has been made to run on delivery systems other than the 
AMS delivery system or the "standard" Unix system.  In general, the two things 
you need to configure are 1) how outgoing mail gets dropped off, and 2) how 
incoming mail gets collected.  Other than that, you should just make sure that 
AMS delivery is turned off, by setting AMS_NonAMSDelivery to "yes".


\italic{OldSendmailProgram: pathname}

\indent{Default: see Note

This specifies the pathname of the BSD sendmail program, or something that can 
emulate it.   The program (possibly a shell script) should be able to handle 
user dropoff using arguments similar to those of sendmail.  AMS dropoff will 
call sendmail with "$\{OldSendmailProgram\} -oem address-list", with each 
address as a separate argument.  Your sendmail substitute could ignore the 
-oem argument.

\bold{Note:} If compiled with RUN_AMDS_ENV, the default is "/etc/oldsendmail". 
 If compiled without RUN_AMDS_ENV, the default is "/usr/lib/sendmail".

}
\italic{AMS_MailCollectionCommand: pathname and arguments}

\indent{Default: NULL

This specifies a command that will be executed before the user's Mailbox is 
checked for new mail.  It should, therefore, be a command string (to be 
executed with system(3)) that will collect new incoming mail from wherever the 
delivery system stores it and put it in the user's home Mailbox directory as a 
separate file for each piece of new mail.  Once this happens, the 
messageserver routines can do their normal reading of the Mailbox files.

}

}\section{Related Tools}\leftindent{


Select (highlight) one of the italicized names, and choose "Show Help on 
Selected Word" from the pop-up menu to see the help document for: 

\italic{
}\helptopic{ams}\italic{

}\helptopic{help}\italic{

}\helptopic{white-pages}}\italic{

}
\begindata{bp,19854496}
\enddata{bp,19854496}
\view{bpv,19854496,10,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,19858780}
