Chapter 4. Build and Install

Table of Contents
4.1. Environment Issues
4.2. Autoconfiguration
4.3. Compilation
4.4. Installing and Upgrading

4.1. Environment Issues

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 local instance of nameserver. 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.

You may also choose to use ``whoson'' services provided by a utility package at ``contrib/'' subdirectory. If you do, then do install that before configuring and installing the ZMailer.

4.2. Autoconfiguration

This system uses several preferably separate partitions for different things:

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 --prefix= so that ZMailer components end up in reasonable places. The $MAILBIN/ (and $MAILSHARE/, and $MAILVAR/) variable values are derived from the --prefix=, which can cause surprises if you do 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:%
  "#! "+prefix+"/bin/router -f"
and usually systems have a limit of 32 characters for that, which gives at most 15 characters for your prefix!

Also, if the /etc/zmailer.conf file exists[1], it is read to initialize several different environment paths (including $MAILBIN/, et.al.!)
# ./configure                             \
  --prefix=/opt/mail                      \
  --with-postoffice=/var/spool/postoffice \
  --with-mailbox=/var/mail                \
  --with-logdir=/var/log/mail             \
  --with-zconfig=/etc/zmailer.conf

Or an example from my development machine:
  $ ./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...
  ***

You can also go into a subdirectory, and configure and compile there: (But it may need GNU make as system ``make''!)
  $ mkdir myhost ; cd myhost
  $ ../configure ...
  $ make ...

See if SiteConfig makes sense now, if not, you can tune most of the values with various --with-*= keywords:
  $ ./configure --help
Explanations about these configuration options are listed at chapter Chapter 7.

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

Additional examples:

4.3. Compilation

At the toplevel, run
  $ make
or perhaps:
  $ make clean all
which at first cleans everything, and then makes — great if you changed some configuration parameters.

This should compile everything, and leave a 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!)

4.4. Installing and Upgrading

This section describes how to install or upgrade ZMailer.

4.4.1. Install Preparation

If you are currently running a zmailer, kill off all mailer processes using
  $ zmailer kill
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 /usr/lib/sendmail (aka /usr/sbin/sendmail 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 ``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 /usr/lib/sendmail.bak, for example) binary back to /usr/lib/sendmail.

(You may also need to do some magics with system startup scripts in case you are running SysV-style init. BSD /etc/rc.local does need its own gymnastics too. Sample SysV-init script is at file: ``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 /usr/lib/sendmail points to ZMailer's ``sendmail.''

4.4.2. Installation

Once you are safe, run either:
  # make install
(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:
  # make install-bin
however this method might not be a complete success in case boilerplate configurations need to be updated as well to match the programs.

There exists also a way to do the installation into a ``parallel universe'' by means of install-time ``prefix'' environment variable:
  # prefix=/var/tmp/build make install-bin
which of course expects to have ``/var/tmp/build/'' directory in existence, and possibly some others under it, but you will soon see, what it needs.

Important: FIXME! FIXME! (Update with POST-INSTALL.SH program!)

All programs are stored into $MAILBIN/, and $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 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 $MAILSHARE/cf/*, $MAILVAR/db/aliases, $MAILVAR/db/routes, and $MAILVAR/db/localnames files are never replaced if they already exist. The $MAILSHARE/forms/* files are always replaced, but the old files will be saved in a ``bak/'' directory.

4.4.3. Installing the Manual Pages.

Because for a long time the installation location of ZMailer's man-pages has not had an obvious destination location, normal ``make install'' does not install them!

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

4.4.4. The Router Configuration File ($MAILSHARE/router.cf).

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

You need to create $MAILSHARE/router.cf.

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

Some real-life samples of router.cf are at the proto/ directory in the source tree.

Notes

[1]

Default location is /etc/zmailer.conf, and it can be changed with --with-zconfig= option.