<sect>Build and Install
<p>This section describes how to build and install ZMailer.

<bf>Tip:</bf> 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</tt> file for more information.

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.) 

<bf>Note:</bf> If you are on an Ultrix system, replace the <tt>mkdep</tt> and <tt>mklibdep</tt>
scripts in the <tt>bin</tt> directory with the versions provided in <tt>bin/Ultrix</tt>.
<sect1>Autoconfiguration
<p>This system uses several preferably separate partitions for
different things:<itemize>
<item>Software binaries, and databases: &dollar;MAILVAR/, &dollar;MAILSHARE/, &dollar;MAILBIN/
<item>The mailbox spool: MAILBOX (<tt>/var/mail</tt>)
<item>The postoffice spool: POSTOFFICE (<tt>/var/spool/postoffice</tt>)
<item>The log directory: LOGDIR (<tt>/var/log/mail</tt>)
</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=</tt> so that ZMailer components end up
in reasonable places.  The MAILBIN (and MAILSHARE, and MAILVAR)
variable values are derived from the <tt>--prefix=</tt>, which can cause
surprises if you do <tt>make install</tt> with GNU autoconfig defaults.

Also, if the <tt>/etc/zmailer.conf</tt> file exists, it is read
to initialize several different environment paths (including
MAILBIN, et.al.!)
<tscreen><verb>
# ./configure --prefix=/opt/mail                              \
              --with-postoffice=/var/spool/postoffice	      \
              --with-mailbox=/var/mail			      \
              --with-logdir=/var/log/mail		      \
              --with-zmailer-conf=/etc/zmailer.conf
</verb></tscreen>
Or an example from my development machine:
<tscreen><verb>
$ ./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...
***
</verb></tscreen>
See if <tt>SiteConfig</tt> makes sense now, if not, you can tune
most of the values with various <tt>--with-*=</tt> keywords:
<tscreen><verb>
./configure --help
</verb></tscreen>
and those that you can't tune, you can edit at the <tt>SiteConfig.in</tt>
file.  (Redo the configure with new parameters, if it looks to be
necessary.)

Additional examples:
<itemize><item>DEC OSF/1 at nic.funet.fi with DECs best compiler...
<tscreen><verb>
CFLAGS="-O -g3 -std1" CC="cc -migrate" ./configure   \
	--prefix=/l/mail  --with-bundled-libresolv   \
	--with-system-malloc
</verb></tscreen>
<item>Sun Solaris 2.5  at mailhost.utu.fi, SunSoft CC 
<tscreen><verb>CC="cc -O" ./configure --prefix=/opt/mail	\
	--with-bundled-libresolv
</verb></tscreen>
<item>Sun Solaris 2.5  at mailhost.utu.fi, gcc-2.7.2
<tscreen><verb>./configure --prefix=/opt/mail --with-bundled-libresolv \
	--with-gcc
</verb></tscreen>
<item>Linux-2.0.x/libc-5.4.2 at mea.cc.utu.fi, gcc-2.7.2 
<tscreen><verb>./configure --prefix=/l/mail
</verb></tscreen>
</itemize>
<sect1>Compilation
<p>At the toplevel, run
<tscreen><verb>make</verb></tscreen>
or perhaps:
<tscreen><verb>make clean all</verb></tscreen>
which at first cleans everything, and then makes -- great if you
changed some configuration parameters.

This should compile everything, and leave a <tt>zmailer.Config</tt> 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!)

<sect1>Installing and Upgrading
<p>This section describes how to install or upgrade ZMailer.

<sect2>Preparation
<p>If you are currently running a zmailer, kill off all mailer processes
using
<tscreen><verb>zmailer kill</verb></tscreen>
and save the state of your system.  This includes any active
contents of the 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</tt>
(aka <tt>/usr/sbin/sendmail</tt> on some systems).
The system attempts to automate the replacement, but it MAY present
a cry for help, if your system does not have functioning symlinks.
Also if <tt>test -h &dollar;(SENDMAILPATH)</tt> 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</tt>, for example)
binary back to <tt>/usr/lib/sendmail</tt>.

(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</tt>
does need its own gymnastics too.)

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.

<sect2>Installation
<p>Once you are safe, run either:
<tscreen><verb># make install</verb></tscreen>
(this installs all binaries and the default database files, which
still need editing! See below.)
or if you just want to have the new BINARIES without touching
at your configurations:
<tscreen><verb># make install-bin</verb></tscreen>
All programs are stored into  <tt>&dollar;MAILBIN/</tt>, and <tt>&dollar;MAILBIN/ta/</tt>, 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 for some customizable files, if
they exist new versions won't replace them).

If this is not a from-scratch installation, be aware that the
install procedure will NOT replace some of the files in MAILSHARE
with the equivalents from the distribution.  Specifically, the
<tt>&dollar;MAILSHARE/cf/*</tt>, <tt>&dollar;MAILVAR/db/aliases</tt>, <tt>&dollar;MAILVAR/db/routes</tt>, and
<tt>&dollar;MAILVAR/db/localnames</tt> files are never replaced if they already
exist.  The <tt>&dollar;MAILSHARE/forms/*</tt> files are always replaced, but the
old files will be saved in a ``bak'' directory.

<sect3>The Router Configuration File (&dollar;MAILSHARE/router.cf).
<p>

You must now pick a toplevel router configuration file.  The
default is provided in <tt>proto/cf/SMTP+UUCP.cf</tt> (by now copied to
<tt>&dollar;MAILSHARE/cf/SMTP+UUCP.cf</tt>). You need to create <tt>&dollar;MAILSHARE/router.cf</tt>.
The simplest method is to make it symbolic link to, or copy of,
the <tt>cf/SMTP+UUCP.cf</tt> file.
Some real-life samples of <tt>router.cf</tt> are at the <tt>proto/</tt> directory.

<sect3>Installing the Manual Pages.
<p>

Go into the <tt>man</tt> directory, and install the manual pages by hand:
<tscreen><verb>cd man ; make install</verb></tscreen>
or in case the default guessing didn't get it right:
<tscreen><verb>cd man ; make install MANDIR=/our/manpages</verb></tscreen>

<sect1>Configuring
<p>This section describes the configuration in short. More detailed information 
can be found in section <em>xxxxx....</em>.
<sect2>/etc/mail.conf
<p>If you are using the default configuration setup, the <tt>router.cf</tt> file
expects to find a <tt>/etc/mail.conf</tt> file containing three variable
definitions:
<tscreen><verb># Where am I?
orgdomain=domain
# Who am I?
hostname=host.subdomain.$orgdomain
# Who do I claim to be?
mydomain=subdomain.$orgdomain
</verb></tscreen>
For example:
<tscreen><verb>
orgdomain=toronto.edu
hostname=relay.cs.$orgdomain
mydomain=cs.$orgdomain
</verb></tscreen>
Create <tt>/etc/mail.conf</tt> 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</tt>) for examples of this.

Location of this file is written in <tt>&dollar;MAILSHARE/router.cf</tt>, at which
you can alter it. Into <tt>&dollar;MAILSHARE/mail.conf</tt> -- for example.
<sect2>/etc/group
<p>The default configuration also expects to find names of trusted users
listed at  <tt>/etc/group</tt> entry <tt>zmailer</tt>.  Users (unames) listed there
will be able to claim any addresses at the message headers, etc.
(See <tt>&dollar;MAILSHARE/cf/trusted.cf</tt> for its usage there.)
Usual set is: <tt>root,daemon,uucp</tt>.
(Note: At some machines `daemon' is called `daemons'; it is
the one with UID=1)

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

<sect2>Verifying That the Router Starts
<p>At this point, you should be able to start the router process in
interactive mode.  Run:
<tscreen><verb>$MAILBIN/router -i</verb></tscreen>
or
<tscreen><verb>/usr/lib/sendmail -bt</verb></tscreen>
You should see something like:
<tscreen><verb>
ZMailer router (2.99.49p5 #4: Wed Jul 23 01:24:37 EET DST 1997)
you@hostname:/some/path/to/src/zmailer/router
Copyright 1992 Rayan S. Zachariassen
Copyright 1992-1997 Matti Aarnio

z#    
</verb></tscreen>

If there are errors in the configuration file, you will be told here.
The `z&num;' 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</tt>.

<sect2>The Database and Forms Files
<p>Now you should merge, replace, or check the default database and
forms files with your previous setup.

Pay particular attention to the following items:
<itemize>
<item>You may want to add a symbolic link from some directory in your path
to <tt>&dollar;MAILBIN/zmailer</tt>, if you don't already have this.  I put this link
in <tt>/usr/local/sbin</tt>.
<item><tt>&dollar;MAILVAR/db/aliases</tt> file:	The provided skeleton aliases file on purpose contains syntax errors,
so you are reminded to change the contents.

The aliases database is rebuilt using the <tt>&dollar;MAILBIN/newaliases</tt> script.
This can be invoked in several ways: directly as a command if you
have <tt>/usr/ucb/newaliases</tt> symlinked properly, or by <tt>zmailer newaliases</tt>
or <tt>sendmail -bi</tt> if the ZMailer sendmail replacement is installed.

Choose one of the following methods to rebuild the database:
<tscreen><verb>
# $MAILBIN/newaliases
# $MAILBIN/zmailer newaliases
# /usr/lib/sendmail -bi
# ln -s /usr/lib/sendmail /usr/ucb/newaliases ; /usr/ucb/newaliases
</verb></tscreen>
If there are errors, correct them in the <tt>&dollar;MAILVAR/db/aliases</tt> file
and repeat the command until the alias database has been initialized.
The final message should look something like:
<tscreen><verb>319 aliases, longest 209 bytes, 16695 bytes total
</verb></tscreen>
See also IETF's RFC 2142: ``Mailbox Names for Common Services, Roles and
Functions'' (file <tt>rfc2142.txt</tt> in the <tt>doc/rfc</tt> directory) 
for other suggestable aliases you may need. 
                                                               

<item><tt>&dollar;MAILVAR/db/localnames</tt> file: Add the hostnames you want ZMailer to do local delivery for, to the
<tt>&dollar;MAILVAR/db/localnames</tt> 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 .domain names in this file, to indicate everything under some
subdomain. <bf>Remember to sort the file.</bf>

With the sample config files for mea's Zmailer-2.98, and latter
this <tt>localnames</tt> is actually a mapping of those various names to
the desired forms of the canonic name, thus an example:
<tscreen><verb>
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
</verb></tscreen>
REMEMBER: 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.

<item><tt>&dollar;MAILVAR/db/routes</tt> file: Add any UUCP neighbours or other special cases to this file.  For
example (remember to keep the entries sorted):
<tscreen><verb>
.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
</verb></tscreen>
<item><tt>&dollar;MAILVAR/db/fqdnaliases</tt> file: The <tt>fqdnaliases</tt> 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:
<tscreen><verb>postmaster@domain1: person1
postmaster@domain2: person2
postmaster@domain3: person3
</verb></tscreen>
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</tt> entry (see above) to declare something suitable:
<tscreen><verb>.domain1	error!nosuchuser
</verb></tscreen>
which combined with the <tt>fqdnalias</tt> method will let <tt>postmaster@domain1</tt>
to exist, and report error on all others.

The <tt>fqdnaliases</tt> database is rebuilt using the <tt>&dollar;MAILBIN/newfqdnaliases</tt>
script.  This can be invoked in several ways: directly as a command
by executing <tt>&dollar;MAILBIN/newfqdnaliases</tt>, or by <tt>zmailer newfqdnaliases</tt>.

Choose one of the following methods to rebuild the database:
<tscreen><verb># $MAILBIN/newfqdnaliases</verb></tscreen>
or
<tscreen><verb># $MAILBIN/zmailer newfqdnaliases
</verb></tscreen>

If there are errors, correct them in the <tt>&dollar;MAILVAR/db/fqdnaliases</tt> file
and repeat the command until the alias database has been initialized.
The final message looks similar to that of the ordinary aliases case.
</itemize>

<sect2>UUCP and BITNET Node Names
<p>If your hostname and UUCP node name are not identical, put your
UUCP node name in the file <tt>/etc/name.uucp</tt> (or <tt>/etc/uucpname</tt>).

If you are on BITNET, put your BITNET node name in <tt>/etc/name.bitnet</tt>
(or <tt>/usr/lib/urep/BITNETNAME</tt>). (And if you really need BITNET stuff, have a look at:
<tt>ftp://ftp.funet.fi/pub/unix/networking/bitnet/</tt>)

<sect2>Checking the Routing
<p>At this point, you should be able to start the router again in
interactive mode, and ask it to route addresses.  Try:
<tscreen><verb>
/usr/lib/sendmail -bt
</verb></tscreen>
at the prompt:
<tscreen><verb>z# router you</verb></tscreen>
should print out:
<tscreen><verb>
(((local you you default_attributes)))
</verb></tscreen>

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

<sect2>/etc/services
<p>Add the following line to <tt>/etc/services</tt> in the section for
host-specific services:
<tscreen><verb>mailq		174/tcp			# Mailer transport queue</verb></tscreen>

<sect2>Bootup Scripts
<p>Add something like the following lines to bootup scripts (<tt>/etc/rc.local</tt>
or <tt>/etc/rc2.d/S99local</tt> or similar):
<tscreen><verb>
if [ -r /etc/zmailer.conf ]; then
(
	. /etc/zmailer.conf
	if [ ${MAILSERVER-NONE} = NONE -a -x $MAILBIN/zmailer ]; then
		$MAILBIN/zmailer bootclean
		$MAILBIN/zmailer &ero; (echo -n ' zmailer')	>/dev/console
	fi
)
fi
</verb></tscreen>
For SysV-init environments, see <tt>utils/zmailer.init.sh</tt>.
You may want to comment out startup of the Sendmail daemon, if you have it to begin with.

<sect2>Checking the Log Files
<p>Start ZMailer:
<tscreen><verb>$MAILBIN/zmailer</verb></tscreen>

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

<sect2>Crontab
<p>Add the following entry (or equivalent) to your <tt>crontab</tt>:
<tscreen><verb>
28 0,8,16 * * * . /etc/zmailer.conf ; $MAILBIN/zmailer resubmit
</verb></tscreen>
This will resubmit messages that have been deferred with no
useful processing possible at time of deferral.  Adjust the
resubmission interval to suit your environment.

You may also want to regularly clean out the <tt>&dollar;POSTOFFICE/public</tt>
and <tt>&dollar;POSTOFFICE/postman</tt> directories:
<tscreen><verb>
7 4 * * * . /etc/zmailer.conf ; $MAILBIN/zmailer cleanup
</verb></tscreen>
You may want to hardwire the location of the zmailer script.

<sect2>Customizing ZMailer Messages
<p>Edit several of the canned error messages and programs (scripts)
to reflect your local configuration: <tt>&dollar;MAILSHARE/forms/</tt> files and
<tt>&dollar;MAILBIN/ta/usenet</tt> (injected message).

<sect2>Alias expansion
<p>Read the notes on alias expansion in the file <tt>doc/guides/aliases</tt> and
on mailing list maintenance in <ref id="mailing_list_maintenance">, 
Mailing Lists and ~/.forward, page <pageref id="mailing_list_maintenance">.

<sect2>Trimdown of Logging
<p>Once satisfied that things appear to work, you may want to trim down
logging: there are 4 kinds of logging to deal with:
<itemize><item>router logs, usually kept in <tt>&dollar;LOGDIR/router</tt>.  This is the stdout
and stderr output of the router daemon.  If you wish to turn it off,
invoke router with a <tt>-L/dev/null</tt> option, i.e. change the zmailer
script.  Alternatively, modify the <tt>log()</tt> function in the
configuration file, or its invocations.

*** NOTE, THIS IS INCORRECT INFO, see  &dollar;MAILSHARE/cf/standard.cf for
*** routine   dribble(),  and especially its invocations!
<item>scheduler logs, usually kept in <tt>&dollar;LOGDIR/scheduler</tt>.  Same as router.
<item>general mail logs, usually kept in syslog files, depending on how
you have configured the syslog utility (<tt>/etc/syslog.conf</tt>).  All
ZMailer programs log using the LOG_MAIL facility code for normal
messages.  You can deal with this specifically in your <tt>syslog</tt>
configuration file on systems with a 4.3bsd-based syslog.  The
following reflects the recommended configuration on SunOS 4.0:
<tscreen><verb>
mail.crit		/var/log/syslog
mail.debug		/var/log/mail
</verb></tscreen>
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 receive a copy of all bounced
mail; this can be turned off selectively by simply editing the
various canned forms used to create the error messages.  These
forms are located in the FORMSDIR (<tt>proto/forms</tt> in the distribution,
or <tt>&dollar;MAILSHARE/forms</tt> when installed).  You should review these
in any case to make sure the text is appropriate for your site.
</itemize>

<sect1>Installation on Clients
<p>This section describes the installation on clients.
<sect2>Required Files
<p>The following files/programs are needed on clients:
<itemize><item><tt>/etc/zmailer.conf</tt> - the MAILSERVER variable may be set to the
mail server host's name.  This is not required as <tt>mailq</tt> will usually be able
to discover this by itself.
<item><tt>/usr/lib/sendmail</tt> - to submit mail
<item><tt>mailq</tt> - should be installed in the site's local
<tt>bin</tt> so people can query the mail server. (Remember to update <tt>/etc/services</tt>)
<item><tt>&dollar;POSTOFFICE</tt> - this directory from the server should be mounted and writable.
</itemize>

<sect2>Mounting MAILBOXes and/or POSTOFFICE Hierarchies via NFS
<p>Mostly at client machines, but also at servers.

If you for some obscure reason are mounting MAILBOXes
and/or POSTOFFICE hierarchies via NFS, do it with
options to disable various attribute caches:
<tscreen><verb>
		actimeo=0
alias:		noac
</verb></tscreen>
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 caches.)

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

Often if the mail folder directory is shared, also (depending upon the system):
<tscreen><verb>
/usr/mail
/usr/spool/mail
/var/mail
/var/spool/mail
</verb></tscreen>

<sect1>Verifying the System
<p>Text to be inserted here.

