<!-- \segment{zinstall}{chapter}{Build and Install}			-->
<!-- %begin{latexonly}							-->
<!-- \cleardoublepage							-->
<!-- %end{latexonly}							-->
<!-- 									-->

<PART ID="ZINSTALL"><?dbhtml filename="zinstall.html">
<TITLE>Build and Install</TITLE>

<PARTINTRO>
<PARA>
This section describes how to build and install ZMailer.
</PARA>

<TIP><PARA>Consider joining the ZMailer user-community email list.
It is the place to meet the Gurus, in case you have problems.
See the ``<FILENAME>Overview</>'' file in the source distribution
for more information.</PARA></TIP>

</PARTINTRO>


<!-- ############################################################### -->


<CHAPTER ID=ch.zins.build-and-install><?dbhtml filename="zins-buildinstall.html">
<TITLE>Build and Install</TITLE>
<SECT1 ID="build.environment"><TITLE>Environment Issues</>

<PARA>
The cornerstone of everything in busy Internet email routing
is a well-working DNS server, and modern resolver library.
If you use the BIND name-server, 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 everybody has their version of things&hellip;

On the other hand, those systems have reasonably modern resolvers,
so no need to worry about it &mdash; I hope.) 
</PARA>

<PARA>
For performance reasons you should have <EMPHASIS>local</> instance of
name-server. <EMPHASIS>Even when you don't have any DNS zone data to
originate yourself, an instance of name-server is able to cache
replies it receives from the network, and thus be able to faster
yield replies for repeated questions.</EMPHASIS>
</PARA>

<PARA>
You may also choose to use ``<APPLICATION>whoson</>'' services provided by
a utility package at ``<FILENAME CLASS="DIRECTORY">contrib/</>'' sub-directory.
If you do, then do install that before configuring and installing the ZMailer.
(More on section <XREF LINKEND="installing-whoson-service">.)
</PARA>

<PARA>
You may also want to support any of following facilities by pre-installing
them into your system (before compiling and installing ZMailer, that is):
<ITEMIZEDLIST>
  <LISTITEM>
    <PARA>
      OpenSSL for in- and outbound encrypted SMTP sessions
    </PARA>
  </LISTITEM>
  <LISTITEM>
    <PARA>
      TCP-Wrapper
    </PARA>
  </LISTITEM>
  <LISTITEM>
    <PARA>
      LDAP client library
    </PARA>
  </LISTITEM>
  <LISTITEM>
    <PARA>
      Private replacement library for  <FUNCTION>getpwnam</>(), and/or
      for  <FUNCTION>zgetpwnam</>()
    </PARA>
  </LISTITEM>
  <LISTITEM>
    <PARA>
      Whoson service to tie in with e.g. POP and IMAP servers for
      authenticating SMTP relaying.
    </PARA>
  </LISTITEM>
</ITEMIZEDLIST>
</PARA>

<PARA>
</PARA>

</SECT1>

<!-- ############################################################### -->

<SECT1 ID="build.autoconfiguration"><TITLE>Auto-configuration</TITLE>

<PARA>
The <FILENAME>zmailer.conf</> file carries various so called
``ZMailer Environment'' configuration variables.
</PARA>
<PARA>
In following we refer to those often in style of:
<SCREEN>
  $MAILVAR   $MAILSHARE   ...
</SCREEN>
Which essentially means expanding in Bourne-shell like manner given
<EMPHASIS>ZENV-variable</> from this file.
</PARA>
<PARA>
The location of this file is defined at system configuration, originally
it was at: <FILENAME>$MAILSHARE/zmailer.conf</>, but these days more often
at the <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILVAR</>/</>.
</PARA>

<PARA>
<INDEXTERM ID=idx.build.disk.partitions><primary>build</><SECONDARY>disk partitions</></>

This system uses several preferably separate partitions for
different things:

<ITEMIZEDLIST>
<LISTITEM><PARA>Software binaries, and databases:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILVAR</>/</> (node local db's),
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILSHARE</>/</> (site shared),
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILBIN</>/</> (read-only, site shared)
</PARA></LISTITEM>
<LISTITEM><PARA>The mailbox spool:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILBOX</>/</>
  (<FILENAME CLASS="DIRECTORY">/var/mail</>)</></>
<LISTITEM><PARA>The postoffice spool:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/</>
  (<FILENAME CLASS="DIRECTORY">/var/spool/postoffice/</>)</></>
<LISTITEM><PARA>The log directory:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>LOGDIR</>/</>
  (<FILENAME>/var/log/mail</>)</></>
</ITEMIZEDLIST>
</PARA>


<IMPORTANT>
<PARA>
<EMPHASIS>
A filesystem without following two properties is not suitable for ZMailer's
</EMPHASIS>
<FILENAME CLASS=DIRECTORY>$<VARNAME>POSTOFFICE</>/</>:
<ITEMIZEDLIST>
<LISTITEM><PARA><EMPHASIS>
Files must succeed to be <FUNCTION>link</>(2):ed in between directories
within the filesystem without copying them.
</EMPHASIS></PARA></LISTITEM>
<LISTITEM><PARA><EMPHASIS>
The file i-node numbers must not change with <FUNCTION>rename</>(2) or
<FUNCTION>link</>(2) calls applied to them.
</EMPHASIS></PARA></LISTITEM>
</ITEMIZEDLIST>
</PARA>

<PARA>
The <FILENAME CLASS=DIRECTORY>$<VARNAME>POSTOFFICE</>/</> directory must be
a single partition within which files can be <FUNCTION>link</>(2)ed from one
directory to another, as well as moved around with <FUNCTION>rename</>(2).
</PARA>

<PARA>
People have asked several times if e.g.
 <FILENAME CLASS=DIRECTORY>$<VARNAME>POSTOFFICE</>/public/</>, and
 <FILENAME CLASS=DIRECTORY>$<VARNAME>POSTOFFICE</>/transport/</>
could be at separate partitions.  No they can't!
</PARA>
</IMPORTANT>

<PARA>
The <APPLICATION>GNU autoconf</> mechanism is used, however, you
still may need to touch on some files after that system has run through:
You MUST define <OPTION>&dd;prefix=</> so that ZMailer components end up
in reasonable places.  The <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILBIN</>/</>
(and <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILSHARE</>/</>, and
 <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILVAR</>/</>)
variable values are derived from the <OPTION>&dd;prefix=</>, which can
cause surprises if you do <COMMAND>make install</> with
<APPLICATION>GNU autoconf</> defaults.
</PARA>

<PARA>
When choosing your prefix, do try to keep is fairly short, as
there are a few scripts which concatenate string-components of:
<SCREEN>
  "#! "+prefix+"/bin/router -f"
</SCREEN>
and usually systems have a limit of 32 characters for that,
which gives at most 15 characters for your prefix!
</PARA>

<PARA>
Also, if the <FILENAME>$<VARNAME>MAILSHARE</>/zmailer.conf</> file
exists<FOOTNOTE><PARA>Default location is <FILENAME>$MAILSHARE/zmailer.conf</>,
and it can be changed with <OPTION>&dd;with-zconfig=</> option.
</PARA></FOOTNOTE>,
it is read to initialize several different environment paths (including
<FILENAME CLASS="DIRECTORY">$<VARNAME>MAILBIN</>/</>, et.al.!)

<SCREEN>
<PROMPT>#</> <USERINPUT>./configure                             \
  &dd;prefix=/opt/mail                      \
  &dd;with-postoffice=/var/spool/postoffice \
  &dd;with-mailbox=/var/mail                \
  &dd;with-logdir=/var/log/mail</USERINPUT></SCREEN></PARA>

<PARA>
Or an example from my development machine:
<SCREEN>
  <PROMPT>$ </><USERINPUT>./configure &dd;prefix=/opt/mail</>
  creating cache ./config.cache
  ***
  *** You can set  ZCONFIG  environment variable to define
  *** the location of the (default) /opt/mail/zmailer.conf -file
  *** (You can use also   &dd;with-zconfig=  -parameter)
  ***
  *** Consider also setting following parameters:
  ***   &dd;mandir=DIR     &dd; for man-pages
  ***   &dd;libdir=DIR     &dd; for libzmailer(3)
  ***   &dd;includedir=DIR &dd; for libzmailer(3)
  *** (They can be outside the &dd;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...
  ***
</SCREEN>
</PARA>

<PARA>
You can also go into a sub-directory, and configure and
compile there: (But it may need <APPLICATION>GNU make</>
as system ``<COMMAND>make</>''!)
<SCREEN>
  <PROMPT>$ </><USERINPUT>mkdir myhost ; cd myhost</>
  <PROMPT>$ </><USERINPUT>../configure ...</>
  <PROMPT>$ </><USERINPUT>make </>...
</SCREEN>
</PARA>

<PARA>
See if <FILENAME>SiteConfig</> makes sense now, if not, you can tune
most of the values with various <OPTION>&dd;with-*=</> keywords:
<SCREEN>
  <PROMPT>$ </><USERINPUT>./configure &dd;help</>
</SCREEN>
Explanations about these configuration options are listed
at chapter <XREF LINKEND="zins.configure-options-list">.
</PARA>

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

<PARA>
Additional examples:
<ITEMIZEDLIST>
<LISTITEM><PARA>DEC OSF/1 at nic.funet.fi with DECs best compiler&hellip;
<SCREEN>
  <PROMPT>$ </><USERINPUT>CFLAGS="-O -g3 -std1" CC="cc -migrate" \</>
    <USERINPUT>./configure &dd;prefix=/l/mail</>
</SCREEN></PARA></LISTITEM>

<LISTITEM><PARA>Sun Solaris 2.5  at mailhost.utu.fi, SunSoft CC
<SCREEN>
  <PROMPT>$ </><USERINPUT>CC="cc -O" ./configure &dd;prefix=/opt/mail</>
</SCREEN></PARA></LISTITEM>

<LISTITEM><PARA>Sun Solaris 2.5  at mailhost.utu.fi, gcc-2.7.2
<SCREEN>
  <PROMPT>$ </><USERINPUT>./configure &dd;prefix=/opt/mail &dd;with-gcc</>
</SCREEN></PARA></LISTITEM>

<LISTITEM><PARA>Sun Solaris 8  at marsu.funet.fi, gcc-2.95.2 (egcs-1.1.2)
<SCREEN>
  <PROMPT>$ </><USERINPUT>'CC='gcc' CFLAGS='-g -O'  ./configure    \</>
       <USERINPUT>&dd;prefix=/opt/mail &dd;with-ipv6        \</> 
       <USERINPUT>&dd;with-zconfig=/opt/mail/zmailer.conf</>
</SCREEN></PARA></LISTITEM>

<LISTITEM><PARA>Linux-2.0.x/libc-5.4.2 at mea.cc.utu.fi, gcc-2.7.2
<SCREEN>
  <PROMPT>$ </><USERINPUT>./configure &dd;prefix=/l/mail</>
</SCREEN></PARA></LISTITEM>
</ITEMIZEDLIST>
</PARA>
</SECT1>

<!-- ############################################################### -->


<SECT1 ID=zins.compilation><TITLE>Compilation</>

<PARA>
At the top-level, run
<SCREEN>
  <PROMPT>$ </><USERINPUT>make</>
</SCREEN>
or perhaps:
<SCREEN>
  <PROMPT>$ </><USERINPUT>make clean all</>
</SCREEN>
which at first cleans everything, and then makes &mdash; great if you
changed some configuration parameters.
</PARA>

<PARA>
This should compile everything, and leave a <FILENAME>zmailer.Config</>
file in the top-level directory.  Nothing outside the source area will be
touched at this point.
</PARA>

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

</SECT1>

<!-- ############################################################### -->

<SECT1 ID=zins.install-and-upgrade><TITLE>Installing and Upgrading</TITLE>

<PARA>
This section describes how to install or upgrade ZMailer.
</PARA>

<SECT2 ID=zins-install-preparation><TITLE>Install Preparation</TITLE>
<INDEXTERM ID=idx.build.upgrade.preparation><PRIMARY>build</><SECONDARY>upgrade preparation</></>
<INDEXTERM ID=idx.install.preparations><PRIMARY>installation</><SECONDARY>preparations</></>

<PARA>
If you are currently running a zmailer, kill off all mailer processes
using
<SCREEN>
  <PROMPT>$ </><USERINPUT>zmailer kill</>
</SCREEN>
and save the state of your system.  This includes any active contents
of the <FILENAME CLASS="DIRECTORY">$<VARNAME>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
``<FILENAME CLASS="DIRECTORY">bak/</>'' sub-directories.
</PARA>

<PARA>
The interface in between the commonly used sendmail, and ZMailer
is a ``compatibility program'', which is to replace the
<FILENAME>/usr/lib/sendmail</FILENAME>
(a.k.a. <FILENAME>/usr/sbin/sendmail</> on some systems).
The system attempts to automate the replacement, but it <EMPHASIS>may</>
present a cry for help if your system does not have functioning symlinks.
Also if ``<COMMAND>test -h $<VARNAME>SENDMAILPATH</></>'' does fault in mysterious ways,
the reason may be that your system does not have symlinks.
</PARA>

<PARA>
If you are currently running Sendmail, kill your SMTP server
and drain the Sendmail queue.  There is no automatic method
to re-queue 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 <FILENAME>/usr/lib/sendmail.bak</>,
for example) binary back to <FILENAME>/usr/lib/sendmail</>.
</PARA>

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

<PARA>
A sort of method to quickly handle your sendmail queue is to
start ZMailer's SMTP server, reconfigure the old sendmail to
use smart-host, 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 <FILENAME>/usr/lib/sendmail</>
points to ZMailer's ``<COMMAND>sendmail</>.''
</PARA>

</SECT2>

<SECT2 ID=zins.install><TITLE>Installation</>
<INDEXTERM ID=idx.build.installation><PRIMARY>build</><SECONDARY>installation</></>
<INDEXTERM ID=idx.install.entire-zmailer><PRIMARY>installation</><SECONDARY>entire ZMailer</></>

<PARA>
Once you are safe, run:
<SCREEN>
  <PROMPT># </><USERINPUT>make install</>
  <PROMPT># </><USERINPUT>$<VARNAME>MAILBIN</>/post-install -MD5</>
</SCREEN>
<EMPHASIS>(Substitute <USERINPUT>$<VARNAME>MAILBIN</></> with the path
 where your binaries go)</EMPHASIS>
</PARA>

<PARA>
This installs all binaries and the default configuration and database files,
as well as creates <FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/</>
directories.   The configurations will still need editing! See below.
</PARA>

<PARA>
The <COMMAND>post-install</> handles important activity in tracking the
base versions of configuration files by storing MD5 check-sums of original
files with <FILENAME>.md5</> suffix tagged to them into their original
location (<FILENAME CLASS="DIRECTORY">proto/</> sub-directories).
This way when sysadmin changes something, the new run of
<COMMAND>post-install</> will detect the changes and not write over such
file.
</PARA>

<PARA>
There exists also a way to do the installation into a ``parallel universe''
by means of install-time ``prefix'' environment variable:
<SCREEN>
  <PROMPT># </><USERINPUT>make install prefix=/var/tmp/build</>
</SCREEN>
which of course expects to have ``<FILENAME>/var/tmp/build/</>'' directory
in existence, and possibly some others under it, but you will soon see, what
it needs.  (But <COMMAND>post-install</> does not support that, and so
it needs to be used at the last stage of packaged ZMailer's installation)
</PARA>

</SECT2>

<SECT2 ID=zins.install-man-pages><TITLE>Installing the Manual Pages.</TITLE>
<INDEXTERM ID=idx.build.man-page-install><PRIMARY>build</><SECONDARY>man-page install</></>
<INDEXTERM ID=idx.install.man-pages><PRIMARY>installation</><SECONDARY>man-pages</></>

<PARA>
Because for a long time the installation location of ZMailer's man-pages
has not had an obvious destination location, normal ``make install''
run at the top-level does <EMPHASIS>not</> install them!
</PARA>

<PARA>
Go into the <FILENAME CLASS="DIRECTORY">man/</> directory,
and install the manual pages by hand:
<SCREEN>
  <PROMPT># </><USERINPUT>cd man</>
  <PROMPT># </><USERINPUT>make</>
</SCREEN>
This will tell what you can order it doing, and what is the default for
<VARNAME>MANDIR</> is at the moment.  If the default is right:
<SCREEN>
  <PROMPT># </><USERINPUT>make install</>
</SCREEN>
or in case the default guessing didn't get it right:
<SCREEN>
  <PROMPT># </><USERINPUT>make install MANDIR=/our/manpages</>
</SCREEN>
</PARA>

</SECT2>
</SECT1>
</CHAPTER>

<CHAPTER ID=ch.zins.system-configuring><?dbhtml filename="zins-sysconfig.html">
<TITLE>System Configuring</>
<INDEXTERM ID=idx.build.config><PRIMARY>build</><SECONDARY>config</></>
<INDEXTERM ID=idx.config.basic-zm-install><PRIMARY>configuration</><SECONDARY>basic ZMailer installation</></>

<!-- ############################################################### -->

<SECT1 ID=zins.run-time-files><TITLE>Run-time files</TITLE>
<PARA>
This section describes the configuration in short. More detailed information 
can be found in section FIXME! FIXME! xxxxx....
</PARA>

<SECT2 ID=zins-rtf-zmailer.conf><TITLE><FILENAME>zmailer.conf</></>
<PARA>
The <FILENAME>zmailer.conf</> file carries various so called
``ZMailer Environment'' configuration variables.
</PARA>
<PARA>
In following we refer to those often in style of:
<SCREEN>
  $MAILVAR   $MAILSHARE   ...
</SCREEN>
Which essentially means expanding in Bourne-shell like manner given
<EMPHASIS>ZENV-variable</> from this file.
</PARA>
<PARA>
The location of this file is defined at system configuration, originally
it was at: <FILENAME>$<VARNAME>MAILSHARE</>/zmailer.conf</>, but these days
more often at the <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILVAR</>/</>.
</PARA>

<PARA>
<INDEXTERM ID=idx.build.disk-partitions.2><primary>build</><SECONDARY>disk partitions</></>

This system uses several preferably separate partitions for
different things:

<ITEMIZEDLIST>
<LISTITEM><PARA>Software binaries, and databases:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILVAR</>/</> (node local db's),
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILSHARE</>/</> (site shared),
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILBIN</>/</> (read-only, site shared)
</PARA></LISTITEM>
<LISTITEM><PARA>The mailbox spool:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILBOX</>/</>
  (<FILENAME CLASS="DIRECTORY">/var/mail</>)</></>
<LISTITEM><PARA>The postoffice spool:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/</>
  (<FILENAME CLASS="DIRECTORY">/var/spool/postoffice/</>)</></>
<LISTITEM><PARA>The log directory:
  <FILENAME CLASS="DIRECTORY">$<VARNAME>LOGDIR</>/</>
  (<FILENAME>/var/log/mail</>)</></>
</ITEMIZEDLIST>
</PARA>

</SECT2>

<SECT2 ID=zins-rtf.etc.group><TITLE><FILENAME>/etc/group</></>
<INDEXTERM ID=idx.build.etc.group.entries><PRIMARY>build</><SECONDARY><FILENAME>/etc/group</> entries</></>
<INDEXTERM ID=idx.build.security.note.etc.group><PRIMARY>build</><SECONDARY>security note: <FILENAME>/etc/group</> entries</></>

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

<PARA>
The usual <EMPHASIS>minimal</> set is: <LITERAL>root,daemon,uucp</>.
(Note: At some machines ``daemon'' is called ``daemons'';
<EMPHASIS>It must be on that group for the smtpserver to be able to work
 properly!</>)
</PARA>

<WARNING><PARA>
<EMPHASIS>SECURITY ITEM</>: Those users at <LITERAL>zmailer</> group
<EMPHASIS ROLE="BOLD">must not</> contain <LITERAL>nobody</>!
</PARA><PARA>
The <LITERAL>nobody</> is used to prevent externally given inputs from being
able to execute arbitrary programs at the system, or from writing to
arbitrary files.</PARA></WARNING>

</SECT2>

<SECT2 ID=zins-rtf.etc.services><TITLE><FILENAME>/etc/services</></>

<PARA>
Add the following line to <FILENAME>/etc/services</> in the section for
host-specific services:
<SCREEN>
mailq   174/tcp  # Mailer transport queue
</SCREEN>
Indeed this isn't <EMPHASIS>quite</> mandatory, as the <COMMAND>scheduler</>
subsystem can be configured to use different IPC socket.
See more about this at Scheduler's PARAM entries: <XREF LINKEND="scheduler.param.entries">.
</PARA>

</SECT2>
</SECT1>

<!-- ############################################################### -->

<SECT1 ID=zins.the.router.subsystem><TITLE>The <COMMAND>Router</> subsystem</TITLE>

<SECT2 ID=zins.the.router.cfgfile><TITLE>The <COMMAND>Router</> Configuration File (<FILENAME>$<VARNAME>MAILSHARE</>/router.cf</>).</>
<INDEXTERM ID=idx.build.config.routercfg><PRIMARY>build</><SECONDARY>config</><TERTIARY>router configuration; <FILENAME>router.cf</></></>
<INDEXTERM ID=idx.router.cf.routercfg.config><PRIMARY><FILENAME>router.cf</>; router configuration</><SECONDARY>config</></>

<PARA>
You must now pick a top-level router configuration file.
The default is provided in <FILENAME>proto/cf/SMTP.cf(.in)</>.
(The <COMMAND>post-install</> places it into
 <FILENAME>$<VARNAME>MAILSHARE</>/router.cf</>).
</PARA>

<PARA>
You need to <EMPHASIS>verify</> <FILENAME>$<VARNAME>MAILSHARE</>/router.cf</>.
</PARA>

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

</SECT2>


<SECT2 ID=zins.router.mail.conf><TITLE><FILENAME>$<VARNAME>MAILVAR</>/mail.conf</></>
<INDEXTERM ID=idx.build.config.mail.conf><PRIMARY>build</><SECONDARY>config</><TERTIARY><FILENAME>$<VARNAME>MAILVAR</>/mail.conf</></></>
<INDEXTERM ID=idx.build.mail.conf-file><PRIMARY><FILENAME>$<VARNAME>MAILVAR</>/mail.conf</>-file</></>

<PARA>
If you are using the default configuration setup, the <FILENAME>router.cf</>
file expects to find a <FILENAME>$<VARNAME>MAILVAR</>/mail.conf</> file
containing three variable definitions:
<SCREEN>
  # Where am I?
  orgdomain=domain
  # Who am I?
  hostname=host.subdomain.$orgdomain
  # Who do I claim to be?
  mydomain=subdomain.$orgdomain
</SCREEN>
</PARA>

<PARA>
For example:
<SCREEN>
  orgdomain=toronto.edu
  hostname=relay.cs.$orgdomain
  mydomain=cs.$orgdomain
</SCREEN>
</PARA>

<PARA>
Create <FILENAME>$<VARNAME>MAILVAR</>/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 (<FILENAME>UT*.cf</>) for examples of this.
</PARA>

<PARA>
Location of this file is written in
<FILENAME>$<VARNAME>MAILSHARE</>/router.cf</>.
By editing that entry you can alter it.
</PARA>

<CAUTION>
<PARA>
Note that ``hostname='' entry above <EMPHASIS>is not alone sufficient</>
for getting the system to know all of the domains it should consider
as local.  See below about <FILENAME>localnames</> database.
</PARA>
</CAUTION>

</SECT2>

<SECT2 ID=zins.verify.router.start><TITLE>Verifying That the <COMMAND>Router</> Starts</TITLE>
<INDEXTERM ID=idx.build.router.start.verify><PRIMARY>build</><SECONDARY>router start verify</></>
<INDEXTERM ID=idx.install.router.start.verify><PRIMARY>installation</><SECONDARY>router start verify</></>

<PARA>
At this point, you should be able to start the <COMMAND>router</> process in
interactive mode.  Run:
<SCREEN>
  <PROMPT># </><USERINPUT>$MAILBIN/router -i</>
</SCREEN>
or
<SCREEN>
  <PROMPT># </><USERINPUT>/usr/lib/sendmail -bt</>
</SCREEN>
</PARA>

<PARA>
You should see something like:
<SCREEN>
  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-2001 Matti Aarnio
  Configured with command: 'CC='gcc -Wall' CFLAGS='-g -O' ../configure ...'
  
  z#
</SCREEN>
</PARA>

<PARA>
If there are errors in the configuration file, you will be told here.
The ``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 <USERINPUT>exit</>.
</PARA>

</SECT2>

<SECT2 ID="zins-router-db-files"><TITLE>The <COMMAND>Router</> Database Files</>
<INDEXTERM ID=idx.build.config.router-databases.1>
<PRIMARY>build</><SECONDARY>config</><TERTIARY>router-databases</></>
<INDEXTERM ID=idx.build.config.router-databases.2>
<PRIMARY>build</><SECONDARY>config</><TERTIARY>forms files</></>
<INDEXTERM ID=idx.build.config.router-databases.3>
<PRIMARY>configuration</><SECONDARY>forms files</></>
<INDEXTERM ID=idx.build.config.router-databases.4>
<PRIMARY>configuration</><SECONDARY>databases</></>

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

<PARA>
In older systems users had fixed choices on which databases to have
at the <COMMAND>router</> subsystem for which looked up relation.
Newer systems have <FILENAME>$<VARNAME>MAILBAR</>/db/dbases.conf</>
configuration file to tell the association of database to look-up relations,
and also the source files.
</PARA>

<SECT3 ID=zins.zmailer.script><TITLE><FILENAME>$<VARNAME>MAILBIN</>/zmailer</> script</>

<PARA>
You may want to add a symbolic link from some directory in your path
to <FILENAME>$<VARNAME>MAILBIN</>/zmailer</>, if you don't already have this.
I put this link in <FILENAME CLASS="DIRECTORY">/usr/local/sbin</>.
</PARA>

<PARA>
This script is skeleton driver for lots of things in the ZMailer,
including <EMPHASIS>the not so small a feat</> of acting as SysV-Init's
init-script as well.
</PARA>
</SECT3>

<SECT3 ID=zins.db.dbases.conf.file><TITLE><FILENAME>$<VARNAME>MAILVAR</>/db/dbases.conf</> file</>

<PARA>
As mentioned above, this file configures (when exists) database look-up
functions versus actual back-end databases.
</PARA>

<PARA>
With this file one can have e.g. multiple <EMPHASIS>aliases</> databases
which are bound together in pre-determined query order (first matcher wins).
</PARA>

<PARA>
This configuration file is used to translate a semi-vague idea
about what database sources (in what forms) are mapped together
under which look-up names, and what format they are, etc..
</PARA>

<PARA>
This is used by  ``<COMMAND>zmailer newdb</>''  command to generate
all databases described here, and to produce relevant  <FILENAME>.zmsh</>
scripts for the <COMMAND>router</> to use things.
The  ``<COMMAND>zmailer newdb</>'' invocation does not mandate
<COMMAND>router</> restart in case the database definitions have
not changed; reverse is true: If definitions are added/modified/removed,
the <COMMAND>router</> <EMPHASIS>must</> be restarted!
</PARA>

<PARA>
<EMPHASIS>When you use ``<COMMAND>zmailer newdb</>'' command, you recompile
all databases defined in the <FILENAME>dbases.conf</> file -- or if you don't
have that file, then all databases listed below, as creation/update of those
are the system defaults.</EMPHASIS>
</PARA>

<PARA>
For more complete example, see the default boilerplate version of this file.
</PARA>


<FIGURE ID="fig.inst.dbases.conf" PGWIDE="1" FLOAT="1">
<TITLE>Sample of ``<FILENAME>$<VARNAME>MAILVAR</>/db/dbases.conf</>'' file</TITLE>
<SCREEN>

#|Fields:
#|     relation-name
#|         dbtype(,subtype)
#|              dbpriv control data (or "-")
#|                  newdb_compile_options (-a for aliases!)
#|                     dbfile (or "-")
#|                         dbflags (or "-") ...
#|
#| The  dbtype  can be "magic" '$DBTYPE', or any other valid database
#| type for the Router.  Somewhat magic treatment (newdb runs) are
#| done when the dbtype is any of: *DBTYPE/dbm/gdbm/ndbm/btree
#|
#| The "dbfile" need not be located underneath of $MAILVAR, as long as
#| it is in system local file-system (for performance reasons.)  E.g.
#| one can place one of e.g. aliases files to some persons directory.
#|

aliases     $DBTYPE 0:0:644    -la $MAILVAR/db/aliases     -lm
aliases     $DBTYPE majordomo:0:644 -la /opt/Majordomo/md-aliases -lm

fqdnaliases $DBTYPE root:0:644 -la $MAILVAR/db/fqdnaliases -lm%
userdb      $DBTYPE root:0:644 -la $MAILVAR/db/userdb      -lm

routesdb    $DBTYPE -    -l  $MAILVAR/db/routes      -lm% -d pathalias
thishost    $DBTYPE -    -l  $MAILVAR/db/localnames  -lm  -d pathalias

</SCREEN>
</FIGURE>


</SECT3>

<SECT3 ID=zins.db.aliases.file><TITLE><FILENAME>$<VARNAME>MAILVAR</>/db/aliases</> file</>

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

<PARA>
Choose one of the following methods to rebuild the database:
<SCREEN>
  <PROMPT># </><USERINPUT>$MAILBIN/newaliases</>
  <PROMPT># </><USERINPUT>$MAILBIN/zmailer newaliases</>
  <PROMPT># </><USERINPUT>/usr/lib/sendmail -bi</>
  <PROMPT># </><USERINPUT>/usr/bin/newaliases</>
  <PROMPT># </><USERINPUT>$MAILBIN/zmailer newdb</>
</SCREEN>
</PARA>

<PARA>
If there are errors, correct them in the ``<FILENAME>aliases</>'' file,
and repeat the command until the alias database has been initialized.
The final message should look something like:
<SCREEN>
 319 aliases, longest 209 bytes, 16695 bytes total
</SCREEN>
exact numbers vary, of course...
</PARA>

<PARA>
See also IETF's 
<ULINK URL="http://www.ietf.org/rfc/rfc2142.txt"><CITETITLE>RFC 2142:
``Mailbox Names for Common Services, Roles and Functions''</CITETITLE></ULINK>
(file <FILENAME>doc/rfc/rfc2142.txt</>)
for other suggested aliases you may need. 
</PARA>

<SECT4 ID=zins.router.alias-expansion><TITLE>Alias expansion</TITLE>

<PARA>
Read the notes on alias expansion in the file <FILENAME>doc/guides/aliases</>
and on mailing list maintenance in <XREF LINKEND="mailing-list-maintenance">, 
<EMPHASIS>Mailing Lists and <FILENAME>~/.forward</>.</EMPHASIS>
</PARA>

</SECT4>
</SECT3>

<SECT3 ID=zins.db.fqdnaliases><TITLE><FILENAME>$<VARNAME>MAILVAR</>/db/fqdnaliases</> file</>

<PARA>
The <FILENAME>fqdnaliases</> database is for mapping fully-qualified
user addresses to others &mdash; for example your 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 as shown at
<XREF LINKEND="fig.inst.fqdnaliases">.
</PARA>

<FIGURE ID="fig.inst.fqdnaliases" PGWIDE="1" FLOAT="1">
<TITLE>Sample of ``<FILENAME>fqdnaliases</>'' file</TITLE>
<SCREEN>
  postmaster@domain1: person1
  postmaster@domain2: person2
  postmaster@domain3: person3, person4
</SCREEN>
</FIGURE>

<PARA>
It is also possible to shunt all recipient addresses for given domain to
some arbitrary addresses as shown at <XREF LINKEND="fig.inst.fqdnaliases-2">.
</PARA>

<FIGURE ID="fig.inst.fqdnaliases-2" PGWIDE="1" FLOAT="1">
<TITLE>Second sample of ``<FILENAME>fqdnaliases</>'' file</TITLE>
<SCREEN>
  @domain4:  person4
  @domain5:  %1@domain6
</SCREEN>
</FIGURE>

<PARA>
This facility is always in stand-by &mdash; just add the file, and
you have it at the next router start-up.
</PARA>

<PARA>
The ``<USERINPUT>%1</>'' local part is special (and experimental, as of
21-Feb-2001) substitution pattern where <EMPHASIS>local part (user)</>
can be replaced into the looked up data.
More details at <XREF LINKEND=zmshref.dblookup>,
and at <XREF LINKEND=zmshref.relation>
</PARA>

<PARA>
You may even handle just a few users for each of those domains, and then
have the ``<FILENAME>routes</>'' entry (see above at
<XREF LINKEND="fig.inst.routes">) to declare something
suitable:
<SCREEN>
  .domain1  error!nosuchuser
  .domain1  error!nosuchuser!%0
</SCREEN>
which combined with the ``<FILENAME>fqdnalias</>'' method will let
``<FILENAME>postmaster@domain1</>'' to exist, and report error on all others.
</PARA>

<PARA>
Choose one of the following methods to rebuild the database:
<SCREEN>
  <PROMPT># </><USERINPUT>$<VARNAME>MAILBIN</>/newfqdnaliases</>
</SCREEN>
or either of:
<SCREEN>
  <PROMPT># </><USERINPUT>$<VARNAME>MAILBIN</>/zmailer newfqdnaliases</>
  <PROMPT># </><USERINPUT>$<VARNAME>MAILBIN</>/zmailer newdb</>
</SCREEN>
</PARA>

<PARA>
If there are errors, correct them in the ``<FILENAME>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.
</PARA>

<PARA>
If you have multiple fqdnaliases databases defined at the
<FILENAME>dbases.conf</>, you must use the ``<COMMAND>zmailer newdb</>''.
(See <XREF LINKEND=zref-zmailer-newdb>.)
</PARA>

</SECT3>

<SECT3 ID="configure-localnames-file">
<TITLE><FILENAME>$<VARNAME>MAILVAR</>/db/localnames</> file</>

<INDEXTERM ID=idx.build.db.localnames><PRIMARY>build</><SECONDARY><FILENAME>$<VARNAME>MAILVAR</>/db/localnames</></></>

<PARA>
Add the host-names you want ZMailer to do local delivery for, to the
<FILENAME>$<VARNAME>MAILVAR</>/db/localnames</> file.
Due to my own belief in Murphy, I usually add partially qualified
domain names and nicknames in addition to canonized names.
If you want to do local delivery for mail clients, put their names
in here too.
You may use pathalias style ``<EMPHASIS ROLE="BOLD">.domain</>'' names
in this file, to indicate everything under some subdomain.
</PARA>

<PARA>
With the sample config files for ZMailer-2.98, and latter,
this <FILENAME>localnames</> is actually a mapping of those various
names to the desired forms of the canonical name, thus an example as seen
in figure <XREF LINKEND="fig.inst.localnames">.
</PARA>

<FIGURE ID="fig.inst.localnames" PGWIDE="1" FLOAT="1">
<TITLE>Sample of ``<FILENAME>localnames</>'' file</TITLE>
<SCREEN>
#
# Left:  input name
# Right: what is wanted to be shown out
#
# List here <EMPHASIS ROLE="BOLD">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
</SCREEN>
</FIGURE>

<PARA>
In certain cases the <COMMAND>router</> is able to deduce some of the names,
<EMPHASIS>however smtpserver anti-relay policy compiler will not be able
 to do so, and needs this data!</EMPHASIS>
</PARA>

<PARA>
<EMPHASIS ROLE="BOLD">THUS: All names that the host may ever have are
 best listed in here!</EMPHASIS>
It reminds you of them, and makes sure a message destined into the host
really is accepted.
</PARA>

<PARA>
Compile this into run-time binary database with command:
<SCREEN>
  <PROMPT># </><USERINPUT>zmailer newdb</>
</SCREEN>
(fall-back method is sequential re-scan of the text file)
</PARA>

</SECT3>

<SECT3 ID=zins.db.routes.file><TITLE><FILENAME>$<VARNAME>MAILVAR</>/db/routes</> file</>

<PARA>
Add any UUCP neighbours or other special cases to this file.
For an example see <XREF LINKEND="fig.inst.routes">.
</PARA>

<PARA>
You can compile the file into binary database with command:
<SCREEN>
  <PROMPT># </><USERINPUT>zmailer newdb</>
</SCREEN>
</PARA>

<FIGURE ID="fig.inst.routes" PGWIDE="1" FLOAT="1">
<TITLE>Sample of ``<FILENAME>routes</>'' file</TITLE>
<SCREEN>
  #
  # ``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
</SCREEN>
</FIGURE>
</SECT3>


<SECT3 ID=zins.router.uucp.node.names><TITLE>UUCP Node Names</>

<PARA>
If your hostname and UUCP node name are not identical, put your
UUCP node name in the file <FILENAME>/etc/name.uucp</>
(or <FILENAME>/etc/uucpname</>).
</PARA>

</SECT3>
</SECT2>

<SECT2 ID=zins.checking.the.routing><TITLE>Checking the Routing</>

<PARA>
At this point, you should be able to start the router again in
interactive mode, and ask it to route addresses.  Try either of:
<SCREEN>
  <PROMPT># </><USERINPUT>/usr/lib/sendmail -bt</>
  <PROMPT># </><USERINPUT>$MAILBIN/router -i</>
</SCREEN>
at the prompt:
<SCREEN>
  <PROMPT>z# </><USERINPUT>router you</>
</SCREEN>
(where ``you'' is your login-id, naturally) should print out:
<SCREEN>
  (((local you you default_attributes)))
</SCREEN>
</PARA>

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

<PARA>
To give more feeling of what goes on during the ``<COMMAND>route</>''-command,
you can give command ``<COMMAND>rtrace</>'' before trying to use
``<COMMAND>route</>.''
</PARA>
</SECT2>
</SECT1>


<!-- ############################################################### -->

<SECT1 ID=zins.the.smtpserver.subsystem>
<TITLE>The <COMMAND>Smtpserver</> subsystem</TITLE>

<PARA>
The <COMMAND>smtpserver</> implements RFC-821 server along with lots
of latter extensions.
</PARA>

<PARA>
Configurable subsystems are:
<ITEMIZEDLIST>
<LISTITEM><PARA>
Generic server parametrization with ``<FILENAME>smtpserver.conf</>'' file.
</PARA></LISTITEM>
<LISTITEM><PARA>
Relaying policy control via ``<FILENAME>smtp-policy</>'' database.
</PARA></LISTITEM>
<LISTITEM><PARA>
Optional PAM authentication framework for SMTP AUTH extension.
</PARA></LISTITEM>
</ITEMIZEDLIST>
</PARA>

<SECT2 ID=zins.smtps-smtpserver.conf-file>
<TITLE>The ``<FILENAME>smtpserver.conf</>'', and smtp-policy databases</>
<INDEXTERM ID=idx.build-smtpserver.conf-file><PRIMARY>smtpserver</><SECONDARY><FILENAME>smtpserver.conf</>-file</></>
<INDEXTERM ID=idx.build-smtpserver.conf-file2><PRIMARY><FILENAME>smtpserver.conf</></><SECONDARY>install</></>

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

<PARA>
Basically you want to install the boilerplates and the tool scripts,
edit them a bit, and run <COMMAND>policy-builder.sh</> script.
For further details on this, see chapter
<XREF LINKEND="zadm-smtpserver-policy-filtering">.
</PARA>

<PARA>
In <COMMAND>smtpserver</> front you may need to lower the strict standards
of the basic RFC-821 SMTP protocol and allow acceptance of non-qualified
addresses &mdash; ones without any sort of domain name in them.
</PARA>

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

<PARA>
Both of these things are handled by ``EHLO-style options'' described
at chapter <XREF LINKEND="zadm-smtpserver-conf-ehlostyle">.
</PARA>

</SECT2>

<SECT2 ID=zins.testing.smtpserver1>
<TITLE>Testing smtpserver operationality</TITLE>
<PARA>
The <COMMAND>smtpserver</> can be tested fully with fairly simple
method -- as long as input databases are readable by the test runner:
</PARA>

<SCREEN>
  <PROMPT>$ </><USERINPUT>$MAILBIN/smtpserver -i -d 1 -T '[1.2.3.4]'</>
  <PROMPT>$ </><USERINPUT>$MAILBIN/smtpserver -i -d 1 -T '[ipv6.11::33]'</>
</SCREEN>

<PARA>
Above the bracketed dotted decimal address literal is source address
used at policy function testing, and one should vary there systems
which <EMPHASIS>are</> allowed to relay thru the server, and also
systems which are not allowed to relay thru the server.
</PARA>

<PARA>
Do testing by issuing normal SMTP protocol transactions, and observing
the results:
</PARA>

<SCREEN>
 000- Lots of debug information
 ....
 220 some greeting
 <USERINPUT>EHLO foobar</>
 000- Lots of debug information
 ....
 250-local.host.name Hello foobar
 250-8BITMIME
 250-PIPELINING
 ....
 250 HELP
 <USERINPUT>MAIL FROM:&lt;&gt</>
 000- Lots of debug information
 ....
 250 Ok ...
 <USERINPUT>RCPT TO:&lt;user@some.where&gt;</>
 000- Lots of debug information
 ....
 250 Ok ...
</SCREEN>

<PARA>
If you want to do testing without excessive amount of debug information,
do leave out ``-d 1'' part of the start arguments.
</PARA>

</SECT2>
</SECT1>

<!-- ############################################################### -->

<SECT1 ID=zins.scheduler.subsystem>
<TITLE>The <COMMAND>Scheduler</> subsystem</TITLE>

<SECT2 ID=zins.checking.scheduler.1>
<TITLE>Checking the <COMMAND>Scheduler</></TITLE>

<PARA>
The location of the <FILENAME>scheduler.conf</> on running system is
<FILENAME>$<VARNAME>MAILSHARE</>/scheduler.conf</>
</PARA>

<PARA>
For normal operations of the system the current sample
of ``<FILENAME>scheduler.conf</>''
<INDEXTERM ID=idx.zins-scheduler.conf-file><PRIMARY><FILENAME>scheduler.conf</></></>
file is quite sufficient, but in case you want to do something
unusual, like using <APPLICATION>procmail</> for local delivery,
do read on.
</PARA>

<PARA>
In <XREF LINKEND="fig.inst.scheduler1"> there are some salient points
about tuning the ``<FILENAME>local</>'' channel behaviour.
</PARA>

<FIGURE ID="fig.inst.scheduler1" FLOAT="1" PGWIDE="1">
<TITLE>Sample of ``<FILENAME>scheduler.conf</>'' passage
for ``<FILENAME>local/*</>'' selector</TITLE>
<SCREEN>
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"
</SCREEN>
</FIGURE>

<PARA>
There are three variants of the ``<FILENAME>command=</>'' entry:
<VARIABLELIST TERMLENGTH="99">
<VARLISTENTRY>
<TERM><FILENAME>command="mailbox -8"</></TERM>
<LISTITEM><PARA>
The normal ZMailer <COMMAND>mailbox</>(8) channel program.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><FILENAME>command="sm -8c $channel procm"</></TERM>
<LISTITEM><PARA>
Variant for running <APPLICATION>procmail</>.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><FILENAME>command="sm -8c $channel cyrus"</></TERM>
<LISTITEM><PARA>
Variant for using <APPLICATION>CMU Cyrus</> message store server.
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>
</PARA>

<PARA>
For more information regarding <EMPHASIS>scheduler</> configuration language,
see <XREF LINKEND="zref.schedulerconfig">.
</PARA>
</SECT2>

<SECT2 ID="zins.sm.conf"><TITLE>Checking <FILENAME>sm.conf</> file</>
<INDEXTERM ID=idx.zins-sm.conf-file><PRIMARY><FILENAME>sm.conf</>-file</></>

<PARA>
For some uses the scheduler runs <COMMAND>sm</>(8) program &mdash; called
``sendmail-like mailer''.
</PARA>

<PARA>
This supports <EMPHASIS>most</> of <APPLICATION>sendmail</>'s
<FILENAME>M</>-entry flags, at least flags with versions previous to 8.x
</PARA>

<PARA>
The ZMailer <COMMAND>sm</>(8) channel program is used to create support
for things like:
<ITEMIZEDLIST>
<LISTITEM><PARA><EMPHASIS>uucp</> transmits
</PARA></LISTITEM>
<LISTITEM><PARA><APPLICATION>procmail</> as local delivery agent
</PARA></LISTITEM>
<LISTITEM><PARA>supporting <APPLICATION>CMU Cyrus message store</>
as local delivery agent </PARA></LISTITEM>
</ITEMIZEDLIST>
</PARA>

<PARA>
For more information, see <XREF LINKEND="zref-ta-sm-config">.
</PARA>
</SECT2>

<SECT2 ID=zins.sched.custom.diag.messages>
<TITLE>Customizing ZMailer Messages</TITLE>

<PARA>
Edit several of the canned error messages and programs (scripts)
to reflect your local configuration:
<FILENAME CLASS="DIRECTORY">$<VARNAME>MAILSHARE</>/forms/</> files and
<FILENAME>$<VARNAME>MAILBIN</>/ta/usenet</> (injected message).
</PARA>

<PARA>
Normally the boilerplate messages looks something like these:
<SCREEN>
HDR From:    The Post Office &lt;postmaster&gt;
HDR Sender:  mailer-daemon
SUB Subject: Errors: No such user(s)
ADR Bcc:     &lt;postmaster&gt;

This is a collection of reports about email delivery
process concerning a message you originated:
</SCREEN>
In these, ``ADR'' lines define header lines which are to be analyzed
for <EMPHASIS>recipient</> addresses, while ``HDR'' lines can carry
anything which doesn't get output as <EMPHASIS>envelope</> address.
The ``ADR'' line contained addresses <EMPHASIS ROLE="BOLD">must</> be in
brackets, and there can be only one address per such header.  If there
are more, only the first one is picked.
</PARA>

<PARA>
<EMPHASIS>FIXME: FIXME: XREF to Scheduler</>
</PARA>

</SECT2>


</SECT1>


<!-- ############################################################### -->

<SECT1 ID=zins.bootup-scripts>
<TITLE>Boot-up Scripts</TITLE>

<PARA>
Add something like the following lines to boot-up scripts
(<FILENAME>/etc/rc.local</> or <FILENAME>/etc/rc2.d/S99local</> or similar):
<SCREEN>
  if [ -r /etc/zmailer.conf ]; then
    . /etc/zmailer.conf
    if [ ${MAILSERVER-NONE} = NONE -a
         -x $MAILBIN/zmailer ]; then
      $MAILBIN/zmailer bootclean
      $MAILBIN/zmailer && (echo -n ' zmailer') >/dev/console
    fi
  fi
</SCREEN>
</PARA>

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

</SECT1>

<!-- ############################################################### -->

<SECT1 ID=zins.checking.log.files>
<TITLE>Checking the Log Files</>

<PARA>
Start ZMailer:
<SCREEN>
  <PROMPT># </><USERINPUT>$MAILBIN/zmailer</>
</SCREEN>
</PARA>

<PARA>
Keep an eye on the log files (<FILENAME>$<VARNAME>LOGDIR</>/router</>,
<FILENAME>$<VARNAME>LOGDIR</>/scheduler</>), the
<FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/postman/</> directory
for malformed message files, and
<FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/deferred/</> in case
of resource problems.
</PARA>

</SECT1>

<!-- ############################################################### -->

<SECT1 ID=zins.crontab>
<TITLE>Crontab</TITLE>

<PARA>
See <XREF LINKEND="fig.inst.crontab"> for three crontab entires for
the root to run.  Those are:
<ORDEREDLIST NUMERATION="ARABIC">
<LISTITEM><PARA>
This will ``<COMMAND>resubmit</>'' messages that have been deferred
with no useful processing possible at time of deferral.
Adjust the re-submission interval to suit your environment.
<EMPHASIS>Having files in ``deferred'' state is a sign of troubles!
Always investigate!</>
</PARA></LISTITEM>

<LISTITEM><PARA>
This ``<COMMAND>cleanup</>'' is to regularly clean out
the ``<FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/public/</>'', and
``<FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/postman/</>''
directories.
</PARA></LISTITEM>

<LISTITEM><PARA>
The automatic log-file trimmer/rotater is a good idea to have, but
you need to customize it for your environment.  More of that below.
</PARA></LISTITEM>
</ORDEREDLIST>
</PARA>

<PARA>
You may want to hard-wire the location of the <COMMAND>zmailer</> script.
</PARA>


<FIGURE ID="fig.inst.crontab" PGWIDE="1" FLOAT="1">
<TITLE>ZMailer related crontab entries for root user</>
<SCREEN>
  # 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
FIXME!FIXME!
  # This third one will not per default be installed into your system
  0  0      * * * . /etc/zmailer.conf ; $MAILBIN/rotate-logs.sh
</SCREEN>
</FIGURE>

</SECT1>


<!-- ############################################################### -->

<SECT1 ID=zins.trim-down.of.logging>
<TITLE>Trim-down of Logging</TITLE>

<PARA>
Once satisfied that things appear to work, you may want to trim down
logging: there are four kinds of logging to deal with:
<ITEMIZEDLIST>
<LISTITEM><PARA>Router logs:</PARA>
<PARA>
Usually kept in <FILENAME>$<VARNAME>LOGDIR</>/router</>.
This is the stdout and stderr output of the router daemon.
If you wish to turn it off,
see <FILENAME>$<VARNAME>MAILSHARE</>/cf/standard.cf</> for routine
dribble()},
and especially its invocations!
Alternatively use ``<OPTION>-L /dev/null</>'' to divert everything
to the ``dev null.''
</PARA></LISTITEM>

<LISTITEM><PARA>Scheduler logs:</PARA>
<PARA>
Usually kept in <FILENAME>$<VARNAME>LOGDIR</>/scheduler</>.
Same as router.
The <COMMAND>scheduler</> prints there <EMPHASIS>only</> when
it feels bad about something.<FOOTNOTE><PARA>
At least this is the theory, practice may be different, though.
</PARA></FOOTNOTE>
</PARA></LISTITEM>

<LISTITEM><PARA>Syslog Control ZENV variable:</PARA>
<PARA>
<EMPHASIS>ZENV variable</> $<VARNAME>SYSLOGFLG</> contains a set of
single-character flags: ``S'', ``C'', ``R'', and/or ``T''.
FIXME! FIXME! Explain Smtpserver/sCheduler/Router/Transport agents!
</PARA></LISTITEM>

<LISTITEM><PARA>General Mail Logs:</PARA>
<PARA>
Usually kept in syslog files, depending on how you have configured
the syslog utility (<FILENAME>/etc/syslog.conf</FILENAME>).
All ZMailer programs log using the <FILENAME>LOG_MAIL</> facility code
for normal messages.  You can deal with this specifically in your
<COMMAND>syslog</> configuration file on systems with a 4.3bsd-based syslog.
The following reflects the recommended configuration on SunOS 4.0:
<SCREEN>
  mail.crit   /var/log/syslog
  mail.debug  /var/log/mail/mail.syslog
</SCREEN>
</PARA>

<PARA>
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).
</PARA></LISTITEM>

<LISTITEM><PARA>
By default, the postmaster will <EMPHASIS>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 <VARNAME>FORMSDIR</>
(<FILENAME CLASS="DIRECTORY">proto/forms</> in the distribution,
or <FILENAME CLASS="DIRECTORY">$<VARNAME>MAILSHARE</>/forms</> when installed).
You should review these in any case to make sure the text is
appropriate for your site.
</PARA></LISTITEM>
</ITEMIZEDLIST>
</PARA>

</SECT1>
</CHAPTER>

<CHAPTER ID=ch.zins-clientinstall><?dbhtml filename="zins-clientinst.html">
<TITLE>Installation to Clients</>

<PARA>
This section describes the installation at clients.
</PARA>

<!-- ############################################################### -->

<SECT1 ID=zins.client.req.files>
<TITLE>Required Files</TITLE>

<VARIABLELIST TERMLENGTH="99">
<TITLE>The following files/programs are needed on clients:</TITLE>
<VARLISTENTRY><TERM><FILENAME>$<VARNAME>MAILVAR</>/zmailer.conf</></>
<LISTITEM><PARA>
The $<VARNAME>MAILSERVER</> variable may be set to the mail server host's name.
This is not required as <COMMAND>mailq</> will usually be able to discover this
by itself.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><FILENAME>/usr/lib/sendmail</></>
<LISTITEM><PARA>
to submit mail
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><COMMAND>mailq</></>
<LISTITEM><PARA>
should be installed in the site's local <FILENAME CLASS="DIRECTORY">bin</>
so people can query the mail server.
(Remember to update <FILENAME>/etc/services</>)
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/</></>
<LISTITEM><PARA>
This directory from the server should be mounted and writable.
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>

</SECT1>

<!-- ############################################################### -->

<SECT1 ID=zins.client.mount.via.nfs>
<TITLE>Mounting <FILENAME>$<VARNAME>MAILBOX</></>es and/or
<FILENAME>$<VARNAME>POSTOFFICE</>/</> Hierarchies via NFS</>

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

<PARA>
If you for some obscure reason are mounting
<FILENAME CLASS="DIRECTORY">$<VARNAME>MAILBOX</></>es
and/or <FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</></>
hierarchies via NFS, do it with options to disable various attribute caches:
<SCREEN>
              actimeo=0
    alias:    noac
</SCREEN>
</PARA>

<PARA>
<EMPHASIS>The best advice is to NOT to mount anything over NFS</>,
but some people can't be persuaded...
</PARA>

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

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

<PARA>
Often if the mail folder directory is shared, also
one of following (depending upon the system):
<SCREEN>
   /usr/mail
   /usr/spool/mail
   /var/mail
   /var/spool/mail
</SCREEN>
</PARA>

</SECT1>
</CHAPTER>

<!-- ############################################################### -->

<CHAPTER ID="ZINS.CONFIGURE-OPTIONS-LIST">
<?dbhtml filename="zins-configure-options.html">
<TITLE><FILENAME>./configure</> options</>
<INDEXTERM ID=idx.zins.build.configure.options><PRIMARY>build</><SECONDARY>configure</><TERTIARY>options</></>
<INDEXTERM ID=idx.zins.configure.options><PRIMARY>configure</><SECONDARY>options</></>

<PARA>
configure  options of ZMailer package, per version 2.99.50.
</PARA>

<PARA>
The  configure  script has three kinds of parameters for it:
</PARA>
<ITEMIZEDLIST>
<LISTITEM><PARA>(optional) environment variables for CC="..." et.al.</></>
<LISTITEM><PARA>ZENV data pulled in from <FILENAME>$<VARNAME>ZCONFIG</></>
 file (if it exists)</></>
<LISTITEM><PARA>various  <OPTION>&dd;with-*</>  et.al. options</></>
</ITEMIZEDLIST>

<!-- ############################################################### -->

<SECT1 ID=zins.config.envars>
<TITLE>Used environment variables</TITLE>

<VARIABLELIST TERMLENGTH="99">
<TITLE>User environment variables</TITLE>
<VARLISTENTRY><TERM><VARNAME>ZCONFIG</>="/file/path"</TERM>
<LISTITEM><PARA>
Using this is alternate for using ``<OPTION>&dd;with-zconfig=../</>'' option.
Not needed if the <OPTION>&dd;prefix=</> derived
<FILENAME>$<VARNAME>MAILSHARE</>/zmailer.conf</> is used.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><VARNAME>CC</>="command"</>
<TERM><VARNAME>CFLAGS</>="options"</>
<LISTITEM><PARA>
Obvious ones, compiler, and possible "-g -O" flags...
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><VARNAME>CPPDEP</>="command"</>
<LISTITEM><PARA>
Not normally needed &mdash; builds dependencies
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><VARNAME>INEWSBIN</>=/file/path</>
<LISTITEM><PARA>
If you want to pre-define where your `inews' program
is &mdash; for possible use of `usenet' channel.
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>

<PARA>
Recycled ZENV variables (from $<VARNAME>ZCONFIG</> file):
<SCREEN>
  For these see  SiteConfig(.in)  file

  ZCONFIG=
  MAILBOX=
  POSTOFFICE=
  MAILSHARE=
  MAILVAR=
  MAILBIN=
  LOGDIR=
  NNTPSERVER=
  SCHEDULEROPTIONS=
  ROUTEROPTIONS=
  SMTPOPTIONS=
  LOGDIR=
  SENDMAILPATH=
  RMAILPATH=
  SELFADDRESSES=
</SCREEN>
</PARA>

</SECT1>

<!-- ############################################################### -->

<SECT1 ID=zins.configure.options>
<TITLE>Options for various facilities</TITLE>

<VARIABLELIST TERMLENGTH="99">
<TITLE>Options for various facilities</TITLE>
<VARLISTENTRY>
<TERM><OPTION>&dd;prefix=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>
The only really mandatory option, gives actually defaults for
<EMPHASIS>ZENV variables</>:
 <FILENAME>$<VARNAME>MAILSHARE</></>,
 <FILENAME>$<VARNAME>MAILVAR</></>,
 <FILENAME>$<VARNAME>MAILBIN</></>.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-gcc</OPTION></TERM>
<LISTITEM><PARA>
Compile with GCC even when you have "cc" around.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-zconfig=/FILE/PATH</OPTION></TERM>
<LISTITEM><PARA>
Where the run-time  <FILENAME>zmailer.conf</>   file is located
at (and with what name).  This is <EMPHASIS>the only</>
hard-coded info within libraries and thus programs using them.
Everything else is run-time relocatable by means of using
"variables" listed in this file.
</PARA>

<PARA>
Default: <FILENAME>$<VARNAME>MAILSHARE</>/zmailer.conf</>
</PARA>

<PARA>
Lots of <ENVAR>ZCONFIG</> environment variables are pre-set from values
present in pre-existing file.
</PARA>

<PARA>
When environment variable <ENVAR>ZCONFIG</> is set and exported to the
<COMMAND>./configure</> script, use of ``<OPTION>&dd;with-zconfig=no</>''
will set the location of the file, but prevents pre-load of various values
from it to the auto-configuration environment.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-mailbox=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>
Overrides system-dependent location of the user mail-boxes.
Defaults are looked up thru list of directories:
<SCREEN>
 /var/mail
 /var/spool/mail
 /usr/mail
 /usr/spool/mail
</SCREEN>
First found directory will be the default &mdash; or then
system yields  <FILENAME CLASS="DIRECTORY">/usr/spool/mail</>.
</PARA></LISTITEM></VARLISTENTRY>


<VARLISTENTRY>
<TERM><OPTION>&dd;with-postoffice=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>
Overrides system-dependent location of
the ``<FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</></>'' directory
under which system stores queued email.
Will try directories
<FILENAME CLASS="DIRECTORY">/{usr,var}/spool/postoffice/</> to
see, if previously installed directory tree exists.
Default will be  <FILENAME CLASS="DIRECTORY">/var/spool/postoffice/</>
in case there is no previously created postoffice directory.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-mailshare=/DIR/PATH</OPTION></TERM>
<!-- <LISTITEM></LISTITEM></VARLISTENTRY><VARLISTENTRY> -->
<TERM><OPTION>&dd;with-mailvar=/DIR/PATH</OPTION></TERM>
<!-- <LISTITEM></LISTITEM></VARLISTENTRY><VARLISTENTRY> -->
<TERM><OPTION>&dd;with-mailbin=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>
These are overrides for values derived from  <OPTION>&dd;prefix=/DIR</>
option, or possibly pre-loaded from <ENVAR>ZCONFIG</> file.</PARA>

<PARA><VARNAME>MAILSHARE</> = "$PREFIX", <VARNAME>MAILVAR</> = "$PREFIX",
but <FILENAME>MAILBIN</> = "$PREFIX/bin".
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-logdir=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>
Explicit value to replace $<VARNAME>LOGDIR</> ZENV value and/or to
override default value of:  <FILENAME CLASS="DIRECTORY">/var/log/mail/</>
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-nntpserver=HOST</OPTION></TERM>
<LISTITEM><PARA>
If you want to use ``<COMMAND>usenet</>'' channel, you need to name
NNTP server into which you feed news with NNTP.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-sendmailpath=/FILE/PATH</OPTION></TERM>
<LISTITEM><PARA>
Overrides for default location(s) of sendmail program.
ZENV variable $<VARNAME>SENDMAILPATH</> can be overridden with this.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-rmailpath=/FILE/PATH</OPTION></TERM>
<LISTITEM><PARA>
Overrides for default location(s) of rmail program.
ZENV variable $<VARNAME>RMAILPATH</> can be overridden with this.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-selfaddresses="NAME,NAME"</OPTION></TERM>
<LISTITEM><PARA>
Obsolete option regarding providing into in ZENV variable
to yield system internal names auto-magically for the SMTP
transport channel uses, and also for the router to see,
if destination IP address is local at the system.
</PARA><PARA>
Usage of this option may become necessary at load-balance clusters,
but even then, setting the value to the <ENVAR>ZCONFIG</> file is
easier than pre-configuring them.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-system-malloc</OPTION></TERM>
<LISTITEM><PARA>
Use system <FUNCTION>malloc</>() library, don't compile own:
Alternate for using: <OPTION>&dd;with-libmalloc=system</>
This is default.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-libmalloc=LIBNAME</OPTION></TERM>
<LISTITEM><PARA>
Where ``LIBNAME'' is one of:
</PARA>
<VARIABLELIST TERMLENGTH="99">
<VARLISTENTRY>
<TERM><OPTION>system</OPTION></TERM>
<LISTITEM><PARA>
System <FUNCTION>malloc</>() as is.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>malloc</OPTION></TERM>
<LISTITEM><PARA>
Bundled "libmalloc" without debugging things.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>malloc_d</OPTION></TERM>
<LISTITEM><PARA>
Bundled "libmalloc" <EMPHASIS>with</> debugging things.
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>

</LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-yp</OPTION></TERM>
<LISTITEM><PARA>
Want to use YP, and has it at default locations
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-yp-lib='-L... -lyp'</OPTION></TERM>
<LISTITEM><PARA>
If needed to define linking-time options to find the YP-library.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-ldap-prefix=DIRPREFIX</OPTION></TERM>
<LISTITEM><PARA>
If UMich/NetScape <APPLICATION>LDAP</> are available thru
<FILENAME CLASS="DIRECTORY">DIRPREFIX/include/</>
and <FILENAME CLASS="DIRECTORY">DIRPREFIX/lib/</>
locations, this is a short-hand to find the interface &mdash; with files
in the system primary include and lib locations,
``<FILENAME CLASS="DIRECTORY">/usr</>'' is a special value which
will be ignored.  There is no default value for
<FILENAME CLASS="DIRECTORY">DIRPREFIX</>.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-ldap-include-dir=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>
Special over-rider for compilation include directory of LDAP
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-ldap-library-dir=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>
Special over-rider for linkage library directory of LDAP
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;disable-pam</OPTION></TERM>
<LISTITEM><PARA>
Disable PAM(3) facility from becoming auto-configured even when
its API headers and libraries are present.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;without-fsync</OPTION></TERM>
<LISTITEM><PARA>
At systems where the local file-system is log-based/journaling,
doing   <FUNCTION>fsync</>()  is wasteful.  This disables
<FUNCTION>fsync</>() in cases where it is not needed.
(In others it may boost your system performance by about 20% &mdash;
 with dangers..
On the other hand, once a system disk(?) fault which hang mailer at
spool directory access did cause severe damage all over, and probably
use of this option would not have made any difference..
 <COMMAND>fsck</> was mighty unhappy..)
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-bundled-libresolv</OPTION></TERM>
<LISTITEM><PARA>
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!
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-ipv6</OPTION></TERM>
<LISTITEM><PARA>
Use IPv6 at things where it is supported.  This is often
highly experimental, although many subsystems in ZMailer
are built with  <FUNCTION>getnameinfo</>()  et.al. interfaces, which
works both on IPv4 and IPv6.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-ipv6-replacement-libc</OPTION></TERM>
<LISTITEM><PARA>
If the system needs more support for user-space IPv6
things, this generates those.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;without-maillock</OPTION></TERM>
<LISTITEM><PARA>
Don't use <FUNCTION>maillock</>(3) even if system has it.
(Solaris <FUNCTION>maillock</>(3) is ok, some early Linux
 versions weren't..)
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;without-rfc822-tabs</OPTION></TERM>
<LISTITEM><PARA>
Some systems dislike getting RFC-822 headers with form of:

<SCREEN>
   "Headername: &lt;TAB&gt; value"
</SCREEN>

With this option, no TABs are used and instead "ordinary"
space character is used.
</PARA>
<PARA>
In real life, this feature is superseded by the <COMMAND>router</>
to <EMPHASIS>always</> <EMPHASIS>TABifying</> all headers, and
the transport-agent header write-out to <EMPHASIS>untabifying</>
them, if ZENV variable <VARNAME>RFC822TABS=</> has value ``0''.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-tcp-wrappers</OPTION></TERM>
<!-- <LISTITEM></LISTITEM></VARLISTENTRY><VARLISTENTRY> -->
<TERM><OPTION>&dd;with-tcp-wrappers=/DIR/PATH</OPTION></TERM>
<LISTITEM><PARA>

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

<VARLISTENTRY>
<TERM><OPTION>&dd;with-ta-mmap</OPTION></TERM>
<LISTITEM><PARA>
On some systems with good <FUNCTION>mmap</>(2) with
``<CONSTANT>MAP_FILE|MAP_SHARED</>,'' and well behaving
<FUNCTION>munmap</>()  it does make sense to replace
<FUNCTION>read</>()/<FUNCTION>write</>() thru a file-descriptor to
the file with <FUNCTION>mmap</>() &mdash; however that requires
<FUNCTION>munmap</>() not to scrub away in-mapped blocks any more actively,
than the buffer-cache works at <FUNCTION>read</>()/<FUNCTION>write</>() blocks.
</PARA>

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

<VARLISTENTRY>
<TERM><OPTION>&dd;with-mboxquotacheck</OPTION></TERM>
<LISTITEM><PARA>
Set 'CHECK_MB_SIZE' #define for mailbox.c compilation, and expect
<FUNCTION>checkmbsize</>() function to be found via
<OPTION>&dd;with-generic-lib=</> referred library.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-privateauth"</OPTION></TERM>
<LISTITEM><PARA>
Use ``<FILENAME CLASS="DIRECTORY">private/</>'' sub-directory in a part of
<COMMAND>smtpserver</> program compilation.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-privatembox"</OPTION></TERM>
<LISTITEM><PARA>
Use ``<FILENAME CLASS="DIRECTORY">private/</>'' sub-directory in a part of
<COMMAND>mailbox</> program compilation.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-getpwnam-library="-L... -l..."</OPTION></TERM>
<LISTITEM><PARA>
Certain sites have expressed wishes to use their own libraries
to replace the standard <FUNCTION>getpwnam</>() (and possibly
<FUNCTION>getpwuid</>()) routines.
These are used in <COMMAND>router</>, <COMMAND>scheduler</>,
<COMMAND>mailbox</>, <COMMAND>hold</>, and <COMMAND>vacation</> programs.
</PARA>

<PARA>
These programs use <FUNCTION>getpwnam</>() libary call to look up various
customer user-names to whatever the system needs them for.
</PARA><PARA>
For ZMailer needs the library must support user-ids:
<ITEMIZEDLIST>
<LISTITEM><PARA>root</></>
<LISTITEM><PARA>daemon, or daemons</></>
<LISTITEM><PARA>nobody</></>
</ITEMIZEDLIST>
and whatever others your local system magic needs.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-generic-include="-I/..."</OPTION></TERM>
<LISTITEM><PARA>
This parameter allows ubiquitous ``<OPTION>-I/...</>'' options to be used
in all program compilations throughout the package.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-generic-library="-L/..."</OPTION></TERM>
<LISTITEM><PARA>
This parameter allows ubiquitous ``<OPTION>-L/...</>'' options to be used
in all program linkages throughout the package.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-openssl</OPTION></TERM>
<!-- <LISTITEM></LISTITEM></VARLISTENTRY><VARLISTENTRY> -->
<TERM><OPTION>&dd;with-openssl-prefix="/dir/prefix"</OPTION></TERM>
<!-- <LISTITEM></LISTITEM></VARLISTENTRY><VARLISTENTRY> -->
<TERM><OPTION>&dd;with-openssl-include="/dir/incl"</OPTION></TERM>
<!-- <LISTITEM></LISTITEM></VARLISTENTRY><VARLISTENTRY> -->
<TERM><OPTION>&dd;with-openssl-lib="/dir/lib"</OPTION></TERM>
<LISTITEM><PARA>
Search for, and use OpenSSL, if it can be found.
(For optional in and outbound SMTP traffic encryption on the Internet.)
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY>
<TERM><OPTION>&dd;with-whoson</OPTION></TERM>
<!-- <LISTITEM></LISTITEM></VARLISTENTRY><VARLISTENTRY> -->
<TERM><OPTION>&dd;with-whoson="/dir/prefix"</OPTION></TERM>
<LISTITEM><PARA>
This does explicit integration with ``<APPLICATION>whoson</>'' server; see
the ``<FILENAME>whoson-*.tar.gz</>'' file in
the ``<FILENAME CLASS="DIRECTORY">contrib/</>'' sub-directory.
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>

</SECT1>
</CHAPTER>

<CHAPTER ID=ch.zins.verification><?dbhtml filename="zins-verification.html">
<TITLE>Verifying the System</TITLE>

<PARA>
FIXME! FIXME! <EMPHASIS> TO BE WRITTEN !</>
</PARA>

</CHAPTER>
</PART>
