%% \chapter{Build and Install}

This section describes how to build and install ZMailer.

{\bf Tip:} Consider joining the ZMailer user-community email list.
It is the place to meet the Gurus, in case you have problems.
See the ``{\tt Overview}'' file in the source distribution for more
information.

\section{Environment issues}%
\index{build!environment}

The cornerstone of everything in busy Internet email routing
is a well-working DNS server, and modern resolver library.
If you use the BIND nameserver, you should be using (or install)
a recent version, at least BIND 4.8. In this package there is also 
a bundled resolver from  bind-4.9.4, however it is a bit difficult
at BSD systems (because those developers use BSD themselves, and
make an assumption that verybody has their version of things...
On the other hand, those systems have reasonably modern resolvers,
so no need to worry about it -- I hope.) 

For performance reasons you should have {\bf local} instance of
nameserver. {\em Even when you don't have any DNS zone data to
originate yourself, an instance of nameserver is able to cache
replies it receives from the network, and thus be able to faster
yield replies for repeated questions.}

%\begin{multicols}{2}

\section{Autoconfiguration}%
\index{build!autoconfiguration}%
\index{autoconfiguration!build}

This system uses several preferably separate partitions for
different things:%
\index{build!disk partitions}%
\index{disk partitions!build}

\begin{itemize}
\item Software binaries, and databases: {\tt \$MAILVAR/, \$MAILSHARE/, \$MAILBIN/}
\item The mailbox spool: {\tt \$MAILBOX} (/var/mail)
\item The postoffice spool: {\tt \$POSTOFFICE} (/var/spool/postoffice)
\item The log directory: {\tt \$LOGDIR} (/var/log/mail)
\end{itemize}

The GNU-autoconfig mechanism is used, however, you still may need to
touch on some files after that system has run through:
You MUST define {\tt --prefix=} so that ZMailer components end up
in reasonable places.  The {\tt \$MAILBIN} (and {\tt \$MAILSHARE},
and {\tt \$MAILVAR}) variable values are derived from
the {\tt --prefix=}, which can cause surprises if you do
{\tt make install} with GNU autoconfig defaults.

When choosing your prefix, do try to keep is fairly short, as
there are a few scripts which catenate string-components of:%
\medskip\begin{alltt}
  "#! "+prefix+"/bin/router -f"
\end{alltt}\medskip%
and usually systems have a limit of 32 characters for that,
which gives at most 15 characters for your prefix!

Also, if the {\tt /etc/zmailer.conf} file exists, it is read
to initialize several different environment paths (including
{\tt \$MAILBIN}, et.al.!)

\begin{alltt}\hrule\medskip
# ./configure                             \verb/\/
  --prefix=/opt/mail                      \verb/\/
  --with-postoffice=/var/spool/postoffice \verb/\/
  --with-mailbox=/var/mail                \verb/\/
  --with-logdir=/var/log/mail             \verb/\/
  --with-zmailer-conf=/etc/zmailer.conf
\medskip\hrule\end{alltt}

Or an example from my development machine:\medskip
\nopagebreak
\begin{alltt}\hrule\medskip
$ ./configure --prefix=/opt/mail
creating cache ./config.cache
***
*** You can set  ZCONFIG  environment variable to define
*** the location of the (default) /etc/zmailer.conf -file
*** (You can use also   --with-zconfig=  -parameter)
***
*** Consider also setting following parameters:
***   --mandir=DIR     -- for man-pages
***   --libdir=DIR     -- for libzmailer(3)
***   --includedir=DIR -- for libzmailer(3)
*** (They can be outside the --prefix=DIR -tree)
***
*** You can set CC, and CFLAGS  environment variables to
*** choose the C-compiler, and its options, especially at
*** systems where there are multiple choices to use...
***
\medskip\hrule\end{alltt}\medskip

You can also go into a subdirectory, and configure and
compile there: (But it may need GNU-make as system ``{\tt make}''!)
\nopagebreak%
\begin{alltt}\medskip\hrule\medskip
  mkdir myhost ; cd myhost
  ../configure ...
  make ...
\medskip\hrule\end{alltt}\medskip

See if {\tt SiteConfig} makes sense now, if not, you can tune
most of the values with various {\tt --with-*=} keywords:
\nopagebreak%
\begin{alltt}\medskip\hrule\medskip
  ./configure --help
\medskip\hrule\end{alltt}\medskip
\nopagebreak\par
Explanations about these configuration options are listed
at chapter \vref{configure_options_list}.

Those options that you can't tune, you can edit at
the ``{\tt SiteConfig.in}'' file.
(Redo the configure with new parameters, if that looks
 to be necessary approach.)

Additional examples:
\begin{itemize}
\item DEC OSF/1 at nic.funet.fi with DECs best compiler\ldots

\begin{alltt}\hrule\medskip
CFLAGS="-O -g3 -std1"             \verb/\/
  CC="cc -migrate"  ./configure   \verb/\/
         --prefix=/l/mail         \verb/\/
         --with-system-malloc
\medskip\hrule\medskip\end{alltt}

\item Sun Solaris 2.5  at mailhost.utu.fi, SunSoft CC

\begin{alltt}\hrule\medskip
CC="cc -O" ./configure            \verb/\/
              --prefix=/opt/mail
\medskip\hrule\end{alltt}

\item Sun Solaris 2.5  at mailhost.utu.fi, gcc-2.7.2

\begin{alltt}\hrule\medskip
./configure --prefix=/opt/mail    \verb/\/
       --with-gcc
\medskip\hrule\end{alltt}

\item Linux-2.0.x/libc-5.4.2 at mea.cc.utu.fi, gcc-2.7.2

\begin{alltt}\hrule\medskip
./configure --prefix=/l/mail
\medskip\hrule\end{alltt}
\end{itemize}


\section{Compilation}

At the toplevel, run
\nopagebreak
\begin{alltt}\medskip\hrule\medskip
  make
\medskip\hrule\medskip\end{alltt}

or perhaps:
\nopagebreak
\begin{alltt}\medskip\hrule\medskip
  make clean all
\medskip\hrule\medskip\end{alltt}

which at first cleans everything, and then makes -- great if you
changed some configuration parameters.

This should compile everything, and leave a \hfill{}
{\tt zmailer.Config} file in
the toplevel directory.  Nothing outside the source area will be
touched at this point.

(If your system ``make'' lets your shell ``SHELL'' environment
affect its own execution environment, it may be that non sh/ksh/zsh
users detect weird phenomena, and failures. Beware!)


\section{Installing and Upgrading}

This section describes how to install or upgrade ZMailer.


\subsection{Install Preparation}%
\index{build!install/upgrade preparation}%
\index{installation!prepatations of,}

If you are currently running a zmailer, kill off all mailer processes
using
\begin{alltt}\medskip\hrule\medskip
  zmailer kill
\medskip\hrule\end{alltt}\medskip

and save the state of your system.  This includes any active
contents of the {\tt\$POSTOFFICE/}, as well as database files and
anything else in the installation areas you want to be sure
to keep.  This is just paranoia, the installation should not
overwrite precious files, and will save old versions of
distribution files in ``bak'' subdirectories.

The interface in between the commonly used sendmail, and ZMailer
is a ``compability program'', which is to replace the {\tt /usr/lib/sendmail}
(aka {\tt /usr/sbin/sendmail} on some systems).
The system attempts to automate the replacement, but it {\em may}
present a cry for help if your system does not have functioning symlinks.
Also if ``{\tt test -h \$\{SENDMAILPATH\}}'' does fault in mysterious ways,
the reason may be that your system does not have symlinks.

If you are currently running Sendmail, kill your SMTP server
and drain the Sendmail queue.  There is no automatic method
to requeue Sendmail messages under ZMailer.  If you later want
to back out to Sendmail, all you need to do is move the former
version of the sendmail (on {\tt /usr/lib/sendmail.bak}, for example)
binary back to {\tt /usr/lib/sendmail}.

(You may also need to do some magics with system startup scripts
in case you are running SysV-style init. BSD {\tt /etc/rc.local}
does need its own gymnastics too.
Sample SysV-init script is at file: ``{\tt proto/zmailer.init.sh}.'')

A sort of method to quickly handle your sendmail queue is to
start ZMailer's SMTP server, reconfigure the old sendmail to
use smarthost, which happens to be at the same machine.
(Or at an adjacent machine if you moved the queue, or ...)
Anyway the point is to get the sendmail to send its queue
via SMTP to the ZMailer.
An equally valid option is to drain the sendmail's queue by running
sendmail in queue drain mode only, although {\tt /usr/lib/sendmail}
points to ZMailer's ``sendmail.''


\subsection{Installation}%
\index{build!installation}\index{installation!entire ZMailer}

Once you are safe, run either:
\begin{alltt}\medskip\hrule\medskip
  # make install
\medskip\hrule\end{alltt}\medskip

(this installs all binaries and the default database files, which
still need editing! See below.)
or if you just want to have the new {\bf binaries} without touching
at your configurations:
\begin{alltt}\medskip\hrule\medskip
  # make install-bin
\medskip\hrule\end{alltt}\medskip

{\bf\Large ?!}
All programs are stored into  {\tt \$MAILBIN/}, and {\tt \$MAILBIN/ta/}, and
possible older binaries are saved into ``bak'' subdirectories.
This step should be non-destructive (anything replaced will be
saved in a ``bak'' directory, and {\sf for some customizable files, if
they exist, new versions won't replace them}).

{\bf\Large ?!}{\sloppy
If this is not a from-scratch installation, be aware that the install
procedure will {\bf not} replace some of the files in {\tt \$MAILSHARE}
with the equivalents from the distribution.
Specifically, the {\tt \$MAILSHARE/cf/*}, {\tt \$MAILVAR/db/aliases},
{\tt \$MAILVAR/db/routes}, and {\tt \$MAILVAR/db/localnames} files are
never replaced if they already exist.
The {\tt \$MAILSHARE/forms/*} files are always replaced, but the
old files will be saved in a ``bak'' directory.
}

\subsubsection{The Router Configuration File (\$MAILSHARE/router.cf).}%
\index{build!config!router configuration; {\tt router.cf}}%
\index{{\tt router.cf}; router configuration!config}

You must now pick a toplevel router configuration file.  The
default is provided in {\tt proto/cf/SMTP+UUCP.cf} (by now copied to
{\tt \$MAILSHARE/cf/SMTP+UUCP.cf}).

You need to create {\tt \$MAILSHARE/router.cf}.

The simplest method is to make it symbolic link to, or copy of,
the {\tt cf/SMTP+UUCP.cf} file.

Some real-life samples of {\tt router.cf} are at the {\tt proto/} directory.


\subsubsection{Installing the Manual Pages.}%
\index{build!man-page install}%
\index{installation!man-pages}

Go into the {\tt man} directory, and install the manual pages by hand:
\nopagebreak
\begin{alltt}\medskip\hrule\medskip
  cd man ; make install
\medskip\hrule\end{alltt}\medskip

or in case the default guessing didn't get it right:
\nopagebreak
\begin{alltt}\medskip\hrule\medskip
  cd man ;
  make install MANDIR=/our/manpages
\medskip\hrule\end{alltt}\medskip


\section{System Configuring}%
\index{build!config}%
\index{configuration!basic ZMailer installation}%

This section describes the configuration in short. More detailed information 
can be found in section {\em xxxxx....\/}.


\subsection{/etc/mail.conf}%
\index{build!config!{\tt /etc/mail.conf}}%
\index{{\tt /etc/mail.conf}-file}

If you are using the default configuration setup, the {\tt router.cf} file
expects to find a {\tt /etc/mail.conf} file containing three variable
definitions:
\begin{alltt}\medskip\hrule\medskip
  # Where am I?
  orgdomain=domain
  # Who am I?
  hostname=host.subdomain.$orgdomain
  # Who do I claim to be?
  mydomain=subdomain.$orgdomain
\medskip\hrule\medskip
\end{alltt}

For example:
\nopagebreak
\begin{alltt}\medskip\hrule\medskip
  orgdomain=toronto.edu
  hostname=relay.cs.$orgdomain
  mydomain=cs.$orgdomain
\medskip\hrule\medskip
\end{alltt}

Create {\tt /etc/mail.conf} with appropriate contents.  If you are a
multi-host site, determining these things can be automated according
to your local policies and conventions.  See the files specific to
the University of Toronto ({\tt UT*.cf}) for examples of this.

Location of this file is written in {\tt \$MAILSHARE/router.cf}.
By editing that entry you can alter it -- into {\tt \$MAILSHARE/mail.conf},
for example.

{\em Note that ``{\tt hostname=}'' entry above {\bf is not alone sufficient}
for getting the system to know all of the domains it should consider
as local.  See below about {\tt localnames} database.}


\subsection{/etc/group}%
\index{build!{\tt /etc/group} entries}%
\index{build!security note: {\tt /etc/group} entries}

The default configuration also expects to find names of trusted users
listed at  {\tt /etc/group} entry {\tt zmailer}.  Users (unames) listed there
will be able to claim any addresses at the message headers, etc.
(See {\tt \$MAILSHARE/cf/trusted.cf} for its usage there.)

The usual {\bf minimal} set is: {\tt root,daemon,uucp}.
(Note: At some machines `daemon' is called `daemons';  {\em It must be
 on that group for the smtpserver to be able to work properly!})

{\bf SECURITY ITEM:} Those users at {\tt zmailer} group {\bf must not} contain {\tt nobody}!
(The {\tt nobody} is used to prevent externally given inputs from being
able to execute arbitary programs at the system, or from writing to
arbitary files.)



\subsection{Verifying That the Router Starts}%
\index{build!router start verify}%
\index{installation!router start verify}

At this point, you should be able to start the router process in
interactive mode.  Run:
\nopagebreak\par
\vbox{
\begin{alltt}\medskip\hrule\medskip
  $MAILBIN/router -i
\medskip\hrule\end{alltt}\medskip
or
\begin{alltt}\medskip\hrule\medskip
  /usr/lib/sendmail -bt
\medskip\hrule\end{alltt}\medskip
}%\vbox

You should see something like:
\begin{alltt}\medskip\hrule\medskip
ZMailer router (2.99.50 #4: Sun May 10 15:24:09 EEST 1998)
you@hostname:/some/path/to/src/zmailer/router
Copyright 1992 Rayan S. Zachariassen
Copyright 1992-1998 Matti Aarnio

z#
\medskip\hrule\end{alltt}\medskip

If there are errors in the configuration file, you will be told here.
The ``{\tt z\#}'' is the interactive prompt for root.
It is unlikely you can do anything useful before setting up the data files,
so get out of this by hitting EOF, or type {\tt exit}.


\subsection{The Database Files}%
\index{build!config!databases}%
\index{build!config!forms files}%
\index{configuration!forms files}%
\index{configuration!databases}

Now you should merge, replace, and very least check the default database
and forms files against your previous setup.

Pay particular attention to the following items:

\subsubsection{{\tt \$MAILBIN/zmailer} script}

You may want to add a symbolic link from some directory in your path
to {\tt \$MAILBIN/zmailer}, if you don't already have this.  I put this link
in {\tt /usr/local/sbin}.

\subsubsection{{\tt \$MAILVAR/db/aliases} file}

The provided skeleton aliases file on purpose contains syntax errors,
so you are reminded to change the contents.

Choose one of the following methods to rebuild the database:
\begin{alltt}\medskip\hrule\medskip
# $MAILBIN/newaliases
# $MAILBIN/zmailer newaliases
# /usr/lib/sendmail -bi
# /usr/bin/newaliases
\medskip\hrule\medskip\end{alltt}

If there are errors, correct them in the ``{\tt aliases}'' file,
and repeat the command until the alias database has been initialized.
The final message should look something like:
\begin{alltt}\medskip\hrule\medskip
 319 aliases, longest 209 bytes, 16695 bytes total
\medskip\hrule\end{alltt}\medskip

See also IETF's RFC 2142: ``Mailbox Names for Common Services, Roles and
Functions'' (file {\tt rfc2142.txt} in the {\tt doc/rfc} directory) 
for other suggestable aliases you may need. 


\subsubsection{{\tt \$MAILVAR/db/localnames} file}

\index{build!{\tt \$MAILVAR/db/localnames} file}%
\label{configure_localnames_file}

Add the hostnames you want ZMailer to do local delivery for, to the
{\tt \$MAILVAR/db/localnames} file.  Due to my own belief in Murphy,
I usually add partially qualified domain names and nicknames in
addition to canonicalized names.  If you want to do local delivery
for mail clients, put their names in here too.  You may use pathalias 
style {\tt.domain} names in this file, to indicate everything under some
subdomain.

With the sample config files for Zmailer-2.98, and latter,
this {\tt localnames} is actually a mapping of those various names to
the desired forms of the canonic name, thus an example as seen
in figure \vref{fig:inst:localnames}

\begin{figure*}
\begin{alltt}\hrule\medskip
#
# Left:  input name
# Right: what is wanted to be shown out
#
# List here {\bf all} names for the system
#
astro.utu.fi         astro.utu.fi
oj287                astro.utu.fi
oj287.astro.utu.fi   oj287.astro.utu.fi
oj287.utu.fi         astro.utu.fi
sirius               sirius.utu.fi
sirius.astro.utu.fi  sirius.utu.fi
sirius.utu.fi        sirius.utu.fi
\medskip\hrule\medskip\end{alltt}
\caption{\label{fig:inst:localnames}Sample of ``{\tt localnames}'' file}
\end{figure*}

In certain cases the router is able to deduce some of the names,
{\em however smtpserver anti-relay policy compiler will not be able
 to do so, and needs this data!}

Thus: {\bf All names that the host may ever have are best listed in here!}
It reminds you of them, and makes sure a message destined into the host
really is accepted.

Compile this into runtime binary database with command:
\begin{alltt}\medskip\hrule\medskip
  zmailer new-localnames
\medskip\hrule\medskip\end{alltt}
(fall-back method is sequential rescan of the text file)

\subsubsection{{\tt \$MAILVAR/db/routes} file}

Add any UUCP neighbours or other special cases to this file.
For an example see figure \vref{fig:inst:routes}.

You can compile the file into binary database with command:
\begin{alltt}\medskip\hrule\medskip
  zmailer new-routes
\medskip\hrule\medskip\end{alltt}

\begin{figure*}
\begin{alltt}\hrule\medskip
#
# ``routes'' mapping file
#
.toronto.ca      error!err.wrongname
.toronto.cdn     error!err.wrongname
alberta          uucp!alberta
atina            smtp![140.191.2.2]
calgary          smtp!cs-sun-fsa.cpsc.ucalgary.ca
icnucevm.bitnet  smtp!icnucevm.cnuce.cnr.it
\medskip\hrule\end{alltt}\medskip
\caption{\label{fig:inst:routes}Sample of ``{\tt routes}'' file}
\end{figure*}

\subsubsection{{\tt \$MAILVAR/db/fqdnaliases} file}

The {\tt fqdnaliases} database is for mapping fully-qualified user
addresses to others -- for example you machine has a set of
domain-names for it to consider local, but you want to have
separate people to be postmasters for each of them:
\begin{alltt}\medskip\hrule\medskip
postmaster@domain1: person1
postmaster@domain2: person2
postmaster@domain3: person3, person4
\medskip\hrule\medskip\end{alltt}

It is also possible to shunt all recipient addresses for given domain
to some arbitary addresses:
\begin{alltt}\medskip\hrule\medskip
@domain4:  person4
\medskip\hrule\medskip\end{alltt}

This facility is always in stand-by -- just add the file, and
you have it.

You may even handle just a few users for each of those domains, and then
have the ``{\tt routes}'' entry (see above) to declare something suitable:
\begin{alltt}\medskip\hrule\medskip
.domain1  error!nosuchuser
\medskip\hrule\medskip\end{alltt}

which combined with the ``{\tt fqdnalias}'' method will let
``{\tt postmaster@domain1}'' to exist, and report error on all others.

Choose one of the following methods to rebuild the database:
\begin{alltt}\medskip\hrule\medskip
# $MAILBIN/newfqdnaliases
\medskip\hrule\medskip\end{alltt}
or
\begin{alltt}\medskip\hrule\medskip
# $MAILBIN/zmailer newfqdnaliases
\medskip\hrule\medskip\end{alltt}

If there are errors, correct them in the ``{\tt fqdnaliases}'' file,
and repeat the command until the alias database has been initialized.
The final message looks similar to that of the ordinary aliases case.


\subsection{UUCP Node Names}

If your hostname and UUCP node name are not identical, put your
UUCP node name in the file {\tt /etc/name.uucp} (or {\tt /etc/uucpname}).

\subsection{Checking the Routing}

At this point, you should be able to start the router again in
interactive mode, and ask it to route addresses.  Try:
\begin{alltt}\medskip\hrule\medskip
/usr/lib/sendmail -bt
\medskip\hrule\end{alltt}\medskip

at the prompt:
\begin{alltt}\medskip\hrule\medskip
z# router you
\medskip\hrule\end{alltt}\medskip

should print out:
\begin{alltt}\medskip\hrule\medskip
(((local you you default_attributes)))
\medskip\hrule\end{alltt}\medskip


Keep playing around with various addresses until you get a feel for it.
Modify the configuration file if your setup requires it.

To give more feeling of what goes on during the ``{\em route}''-command,
you can give command ``{\em rtrace}'' before trying to use ``{\em route}.''

\subsection{/etc/services}

Add the following line to {\tt /etc/services} in the section for
host-specific services:
\begin{alltt}\medskip\hrule\medskip
mailq   174/tcp  # Mailer transport queue
\medskip\hrule\end{alltt}

\subsection{Checking the Scheduler}

The location of the {\tt scheduler.conf} on running system is
{\tt \$MAILSHARE/scheduler.conf}

For normal operations of the system the current sample
of ``{\tt scheduler.conf}''\index{\tt scheduler.conf} file
is quite sufficient, but in case you want to do something
unusual, like using {\tt procmail} for local delivery,
do read on.

In the figure \vref{fig:inst:scheduler1} there are some salient
points about tuning the ``{\tt local}'' channel behaviour.

\begin{figure*}
\begin{alltt}\medskip\hrule\medskip
local/*
    interval=5m
    idlemax=9m
    expiry=3d
    # want 20 channel slots, but only one HOST
    maxchannel=15
    maxring=5
    # Do MIME text/plain; Quoted-Printable -> text/plain; 8BIT
    # conversion on flight!
    command="mailbox -8"
    # Or with PROCMAIL as the local delivery agent:
    #command="sm -8c $channel procm"
    # Or with CYRUS server the following might do:
    #command="sm -8c $channel cyrus"
\medskip\hrule\medskip\end{alltt}
\caption{\label{fig:inst:scheduler1}Sample of ``{\tt scheduler.conf}'' passage for ``{\tt local/*}'' selector}
\end{figure*}

There are three variants of the ``{\tt command=}'' entry:
\begin{description}
\item[{\tt command="mailbox -8"}] \mbox{}

The normal {\em ZMailer} {\tt mailbox}(8) channel program.

\item[{\tt command="sm -8c \$channel procm"}] \mbox{}

Variant for running {\em procmail}.

\item[{\tt command="sm -8c \$channel cyrus"}] \mbox{}

Variant for using {\em CMU Cyrus} message store server.
\end{description}

For more information regarding {\em scheduler} configuration language,
see chapter \vref{schedulerconfig}.

\subsection{Checking {\tt sm.conf} file}%
\index{{\tt sm.conf}-file}

For some uses the scheduler runs {\tt sm}(8) program -- called
``sendmail-like mailer''.

This supports {\em most} of {\em sendmail}'s {\tt M}-entry flags,
at least flags with versions previous to 8.x

The {\em ZMailer} {\tt sm}(8) channel program is used to create support
for things like:
\begin{itemize}
\item {\em uucp} transmits
\item {\em procmail} as local delivery agent
\item supporting {\em CMU Cyrus message store} as local delivery agent
\end{itemize}

For more information, see chapter \vref{smconfig}.


\subsection{The ``{\tt smtpserver.conf}'', and smtp-policy databases}
\index{smtpserver!{\tt smtpserver.conf}-file}

These take care of such a things as preventing relay-hijack type
of abuse of your system.

Basically you want to install the boilerplates and the tool scripts,
edit them a bit, and run {\em policy-builder.sh} script.
For further details on this, see chapter \vref{adm:smtp_policy_filtering}.

In {\em smtpserver} front you may need to lower the strict standards
of the basic RFC-821 SMTP protocol and allow acceptance of non-qualified
addresses -- ones without any sort of domain name in them.

Another thing to allow is (sigh) MS-Windows-CE 1.0/2.0 gadgets with
their totally broken SMTP sending system.

Both of these things are handled by ``EHLO-style options'' described
at chapter \vref{adm:smtpserver:ehlostyle}

\subsection{Bootup Scripts}

Add something like the following lines to bootup scripts ({\tt /etc/rc.local}
or {\tt /etc/rc2.d/S99local} or similar):
\begin{alltt}\medskip\hrule\medskip
if [ -r /etc/zmailer.conf ]; then
(
  . /etc/zmailer.conf
  if [ ${MAILSERVER-NONE} = NONE -a
       -x $MAILBIN/zmailer ]; then
    $MAILBIN/zmailer bootclean
    $MAILBIN/zmailer & \verb/\/
      (echo -n ' zmailer') >/dev/console
  fi
)
fi
\medskip\hrule\end{alltt}\medskip


For SysV-init environments, see source-tree file: {\tt utils/zmailer.init.sh}.
You may want to comment out startup of the Sendmail daemon,
if you have it to begin with.


\subsection{Checking the Log Files}

Start ZMailer:
\begin{alltt}\medskip\hrule\medskip
  $MAILBIN/zmailer
\medskip\hrule\end{alltt}\medskip


Keep an eye on the log files ({\tt \$LOGDIR/router, \$LOGDIR/scheduler}),
the {\tt \$POSTOFFICE/postman/} directory for malformed message files,
and {\tt \$POSTOFFICE/deferred/} in case of resource problems.

\subsection{Crontab}

\begin{figure*}
\begin{alltt}\hrule\medskip
# Two ZMailer related root's CRONTAB entries:
28 0,8,16 * * * . /etc/zmailer.conf ; $MAILBIN/zmailer resubmit
7  4      * * * . /etc/zmailer.conf ; $MAILBIN/zmailer cleanup
# {\rm This third one will not per default be installed into your system}
0  0      * * * . /etc/zmailer.conf ; $MAILBIN/rotate-logs.sh
\medskip\hrule\end{alltt}\medskip
\caption{\label{fig:inst:crontab}ZMailer related crontab entries for root user}
\end{figure*}

See figure \vref{fig:inst:crontab} for two crontab entires for
the root to run.  There are three entries:
\begin{enumerate}
\item
This will ``{\tt resubmit}'' messages that have been deferred with
no useful processing possible at time of deferral.  Adjust the
resubmission interval to suit your environment.
{\em Having files in ``deferred'' state is a sign of troubles!
Always investigate!}

\item
This ``{\tt cleanup}'' is to regularly clean out
the ``{\tt \$POSTOFFICE/public}'', and ``{\tt \$POSTOFFICE/postman}''
directories.

\item
The automatic logfile trimmer/rotater is a good idea to have, but
you need to customize it for your environment.  More of that below.
\end{enumerate}

You may want to hardwire the location of the zmailer script.


\subsection{Customizing ZMailer Messages}

Edit several of the canned error messages and programs (scripts)
to reflect your local configuration: {\tt \$MAILSHARE/forms/} files and
{\tt \$MAILBIN/ta/usenet} (injected message).

{\large\em XREF to Scheduler}

\subsection{Alias expansion}

Read the notes on alias expansion in the file {\tt doc/guides/aliases} and
on mailing list maintenance in \vref{mailing_list_maintenance}, 
{\em Mailing Lists and \tt\~{}/.forward}.


\subsection{Trimdown of Logging}

Once satisfied that things appear to work, you may want to trim down
logging: there are four kinds of logging to deal with:
\begin{itemize}
\item Router logs:

Usually kept in {\tt \$LOGDIR/router}.  This is the stdout
and stderr output of the router daemon.  If you wish to turn it off,
see {\tt\$MAILSHARE/cf/standard.cf} for routine  {\tt dribble()},
and especially its invocations!

\item Scheduler logs:

Usually kept in {\tt \$LOGDIR/scheduler}.  Same as router.

\vspace{1pt}
\item General Mail Logs:

Usually kept in syslog files, depending on how you have configured
the syslog utility ({\tt /etc/syslog.conf}).
All ZMailer programs log using the LOG\_MAIL facility code for normal
messages.  You can deal with this specifically in your {\tt syslog}
configuration file on systems with a 4.3bsd-based syslog.  The
following reflects the recommended configuration on SunOS 4.0:
\begin{alltt}\medskip\hrule\medskip
mail.crit   /var/log/syslog
mail.debug  /var/log/mail/mail.syslog
\medskip\hrule\end{alltt}\medskip

For pre-4.3bsd-based syslogs, you may want the syslog log file
to be just for important messages (e.g. LOG\_NOTICE and higher
priority), and have a separate file for informational messages
(LOG\_DEBUG and up).

\item By default, the postmaster will {\bf not} receive a copy
of all bounced mail; this can be turned on selectively by simply
editing the various canned forms used to create the error messages.
These forms are located in the FORMSDIR ({\tt proto/forms} in
the distribution, or {\tt \$MAILSHARE/forms} when installed).
You should review these in any case to make sure the text is
appropriate for your site.

\end{itemize}


\section{Installation to Clients}

This section describes the installation at clients.


\subsection{Required Files}

The following files/programs are needed on clients:
\begin{itemize}
\item {\tt /etc/zmailer.conf}

The {\tt \$MAILSERVER} variable may be set to the mail server host's name.
This is not required as {\tt mailq} will usually be able to discover this
by itself.

\vspace{1pt}
\item {\tt /usr/lib/sendmail}

to submit mail

\vspace{1pt}
\item {\tt mailq}

should be installed in the site's local {\tt bin} so people
can query the mail server. (Remember to update {\tt /etc/services})

\vspace{1pt}
\item {\tt \$POSTOFFICE}

This directory from the server should be mounted and writable.
\end{itemize}


\subsection{Mounting {\tt \$MAILBOX}es and/or {\tt \$POSTOFFICE} Hierarchies via NFS}

This is mostly for client machines,
but the NFS may plaque you also at servers.

If you for some obscure reason are mounting {\tt \$MAILBOX}es
and/or {\tt \$POSTOFFICE} hierarchies via NFS, do it with
options to disable various attribute caches:
\begin{alltt}
              actimeo=0
    alias:    noac
\end{alltt}

{\bf The best advice is to NOT to mount anything over NFS},
but some people can't be persuaded...

Lots of things are done where file attributes play important
role, and they are extremely important to be in sync!
(Sure, the `noac' slows down the system, but avoids errors
caused by bad attribute caches.)

If you are mounting people's home directories ({\tt .forward} et al.)
via NFS, consider the same rule!

Often if the mail folder directory is shared, also
one of following (depending upon the system):
\begin{alltt}
    /usr/mail
    /usr/spool/mail
    /var/mail
    /var/spool/mail
\end{alltt}


\subsection{{\tt ./configure} options}%
\index{build!configure!options}%
\index{configure!options}%
\label{configure_options_list}

configure  options of ZMailer package, per version 2.99.50.


The  configure  script has three kinds of parameters for it:
\begin{itemize}
\item (optional) environment variables for CC="..." et.al.
\item ZENV data pulled in from {\tt \$ZCONFIG} file (if it exists)
\item various  \verb/--with-*/  et.al. options
\end{itemize}


\subsubsection{Used environment variables}

\begin{description}
\item[\tt ZCONFIG="/file/path"] \mbox{}

Using this is alternate for using "\verb/--with-zconfig=../" option.
Not needed if the default of {\tt /etc/zmailer.conf} is used.

\item[\tt CC="command"]
\item[\tt CFLAGS="options"] \mbox{}

Obvious ones, compiler, and possible "-g -O" flags...

\item[\tt CPPDEP="command"] \mbox{}

Not normally needed -- builds dependencies

\item[\tt INEWSBIN=/file/path] \mbox{}

If you want to pre-define where your `inews' program
is -- for possible use of `usenet' channel.
\end{description}

Recycled ZENV variables (from {\tt \$ZCONFIG} file):
\begin{alltt}\medskip
  For these see  SiteConfig(.in)  file

  ZCONFIG=
  MAILBOX=
  POSTOFFICE=
  MAILSHARE=
  MAILVAR=
  MAILBIN=
  LOGDIR=
  NNTPSERVER=
  SCHEDULEROPTIONS=
  ROUTEROPTIONS=
  SMTPOPTIONS=
  LOGDIR=
  SENDMAILPATH=
  RMAILPATH=
  SELFADDRESSES=
\end{alltt}

\subsubsection{Options for various facilities}

\begin{description}
\item[\tt --prefix=/DIR/PATH] \mbox{}

The only really mandatory option, gives actually
defaults for \verb:MAILSHARE/MAILVAR/MAILBIN:.

\item[\tt --with-gcc] \mbox{}

Compile with GCC even when you have "cc" around.

\item[\tt --with-zconfig=/FILE/PATH] \mbox{}

Where the runtime   {\tt zmailer.conf}   file is located
at (and with what name).  This is {\bf the only} hard-coded
info within libraries and thus programs using them.
Everything else is runtime relocatable by means of using
"variables" listed in this file.

Default: {\tt /etc/zmailer.conf}

\item[\tt --with-mailbox=/DIR/PATH] \mbox{}

Overrides system-dependent location of the user mail-boxes.
Defaults are looked up thru list of directories:
\begin{alltt}
 /var/mail
 /var/spool/mail
 /usr/mail
 /usr/spool/mail
\end{alltt}
First found directory will be the default -- or then
system yields  {\tt /usr/spool/mail}

\item[\tt --with-postoffice=/DIR/PATH] \mbox{}

Overrides system-dependent location of the "{\tt \$POSTOFFICE}"
directory under which system stores queued email.
Will try directories \verb:/{usr,var}/spool/postoffice/: to
see, if previously installed directory tree exists.
Default will be  \verb:/var/spool/postoffice/:
in case there is no previously created postoffice directory.

\item[\tt --with-mailshare=/DIR/PATH]
\item[\tt --with-mailvar=/DIR/PATH]
\item[\tt --with-mailbin=/DIR/PATH] \mbox{}

These are overrides for values derived from  \verb:--prefix=/DIR:
option.  {\tt MAILSHARE = "\$PREFIX"}, {\tt MAILVAR = "\$PREFIX"},
but the last is {\tt MAILBIN = "\$PREFIX/bin"}

\item[\tt --with-logdir=/DIR/PATH] \mbox{}

Explicite value to replace {\tt \$LOGDIR} ZENV value and/or to
override default value of:  {\tt /var/log/mail}

\item[\tt --with-nntpserver=HOST] \mbox{}

If you want to use `{tt usenet}' channel, you need to name
NNTP server into which you feed news with NNTP.

\item[\tt --with-sendmailpath=/FILE/PATH] \mbox{}

Overrider for default location(s) of sendmail program.
ZENV variable \verb:$SENDMAILPATH: can be overridden with this.

\item[\tt --with-rmailpath=/FILE/PATH] \mbox{}

Overrider for default location(s) of rmail program.
ZENV variable \verb:$RMAILPATH: can be overridden with this.

\item[\tt --with-selfaddresses="NAME,NAME"] \mbox{}

Obsolete option regarding providing into in ZENV variable
to yield system internal names automagically for the SMTP
transport channel uses, and also for the router to see,
if destination IP address is local at the system.

\item[\tt --with-system-malloc] \mbox{}

Use system malloc() library, don't compile own:
Alternate for using: \verb:--with-libmalloc=system:
This is default.

\item[\tt --with-libmalloc=LIBNAME] \mbox{}

Where "{\tt LIBNAME}" is one of:
\begin{description}
\item[\tt system] \mbox{} 

System malloc() as is.

\item[\tt malloc] \mbox{}

Bundled "libmalloc" without debugging things.

\item[\tt malloc\_d] \mbox{}

Bundled "libmalloc" {\bf with} debugging things.
\end{description}

\item[\tt --with-yp] \mbox{}

Want to use YP, and has it at default locations

\item[\tt --with-yp-lib='-L... -lyp'] \mbox{}

If needed to define linking-time options to find the YP-library.

\item[\tt --with-ldap-prefix=DIRPREFIX] \mbox{}

If UMich/NetScape {\em LDAP} are available thru {\tt DIRPREFIX/include/}
and {\tt DIRPREFIX/lib/} locations, this is a short-hand to find
the interface -- with files in the system primary include
and lib locations,  "{\tt /usr}" is a special value which will be
ignored.  No default value for {\tt DIRPREFIX}.

\item[\tt --with-ldap-include-dir=/DIR/PATH] \mbox{}

Special overrider for compilation include directory of LDAP

\item[\tt --with-ldap-library-dir=/DIR/PATH] \mbox{}

Special overrider for linkage library directory of LDAP

\item[\tt --without-fsync] \mbox{}

At systems where the local filesystem is log-based/journaling,
doing   fsync()  is wastefull.  This disables fsync() in
cases where it is not needed.    (In others it may boost
your system performance by about 20% -- with dangers..
On the other hand, recently a system disk(?) fault which
hang mailer at spool directory access did cause severe
damage all over, and propably use of this option would
not have made any difference..  fsck was mighty unhappy..)

\item[\tt --with-bundled-libresolv] \mbox{}

If your system is not very modern, you may consider using
this option to compile in a resolver from bind-4.9.4-REL.
On the other hand, if your system is modern, it may have
even newer resolver in it.  At such time, don't use this!

\item[\tt --with-ipv6] \mbox{}

Use IPv6 at things where it is supported.  This is often
highly experimental, although many subsystems in ZMailer
are built with   getnameinfo()  et.al. interfaces, which
works both on IPv4 and IPv6.

\item[\tt --with-ipv6-replacement-libc] \mbox{}

If the system needs more support for user-space IPv6
things, this generates those.

\item[\tt --without-rfc822-tabs] \mbox{}

Some systems dislike getting RFC-822 headers with form of:
\begin{alltt}
   "Headername: <HTAB> value"
\end{alltt}
With this option, no HTABs are used and instead "ordinary"
space character is used.

\item[\tt --with-tcp-wrappers]
\item[\tt --with-tcp-wrappers=/DIR/PATH] \mbox{}

Optional  {\tt =/DIR/PATH}  value gives directory where there are
{\tt <tcpd.h>}  and  {\tt libwrap.a}  files.
Without value this option looks for several common locations
for those files, and if finds them, yields compile and linking
hooks,

\item[\tt --with-ta-mmap] \mbox{}

On some systems with good {\tt mmap()} with ``MAP\_FILE\verb/|/MAP\_SHARED,''
and well behaving  {\tt munmap()}  it does make sense to replace
read()/write() thru a file-descriptor to the file with
mmap() -- however that requires munmap() {\bf not to} scrub
away in-mapped blocks any more actively, than the buffer-cache
works at read()/write() blocks.

This was default for a while, however most systems don't
have really well-behaved munmap()s :-/
(Perhaps IBM AIX is the only exception ?)

\item[\tt --with-getpwnam-library="-L... -l..."] \mbox{}

Certain sites have expressed wishes to use their own libraries
to replace the standard {\tt getpwnam()} (and possibly {\tt getpwuid()}
routines.
These are used in router, scheduler, mailbox, hold, and vacation
programs.

These programs use {\tt getpwnam()} libary call to look up
various customer usernames to whatever the system needs them
for.

For {\em ZMailer} needs the library must support userids:
\begin{itemize}
\item {\tt root}
\item {\tt daemon}, or {\tt daemons}
\item {\tt nobody}
\end{itemize}
and whatever others your local system magic needs.
\end{description}

\section{Verifying the System}

{\em\large TO BE WRITTEN}


%\end{multicols}
