#ident	"@(#)smail:RELEASE-3_2_0_115:INSTALL,v 1.32 2003/06/18 07:01:21 woods Exp"

INITIAL UNPACKING

After you've unpacked the source (and thus been able to read this far in
this file), we strongly recommend you begin by first checking the entire
distribution into some form of source code control system.  We heartily
recommend the use of CVS, as it offers what is called "vendor branch
support" thus making it trivial to merge local changes with new "vendor"
releases of a product.  It will also make it far easier for you to
submit accurate patches to the Smail developer(s) (see below for
information about submitting patches).

To check this release of Smail into CVS (assuming you already have CVS
installed and a default repository created) you might do something like
this:

    cvs import -I ! -m 'Smail RELEASE-3_2_0_115 Distribution' smail SMAIL RELEASE-3_2_0_115

If you don't have CVS, but are familiar with RCS, or SCCS, you can also
use those tools to track any local changes you might make during the
course of installation and configuration and local customisation of
Smail.

If you do use CVS, you should not run "make depend" (use "make clobber
all" for builds instead), or if you do happen to run it you should not
check in the changed Makefiles.  If you wish to / need to make local
changes to the Makefiles, you should do so in a freshly checked out
working directory, and *not* run "make depend", but rather run "make
clobber" between builds.  Once you've verified and checked in your
changes, you may then run "make depend" to speed subsequent builds, but
remember *not* to check in the Makefiles with the dependencies.


BUILD CONFIGURATION

We recommend that you read through the various manual pages before
setting up and installing Smail.  To generate the manual pages, change to
the man directory and type "make".  This will generate manual pages for
the default Smail configuration.  Detailed information on Smail can be
found in the manual pages smail(5) and smail(8), with further details on
the specific configuration files in the other section 5 manual pages..

All run-time configuration files are optional, and the smail program
itself creates anything that it absolutely needs.  Thus in the
simplest example, the installation procedure is simply to setup the
base internal configuration and type the various make commands.

The only file that you must edit is conf/EDITME, which drives the
compilation process for the smail binary and the several accompanying
utilities.  This file describes the locations of various files and
directories, enables or disables various capabilities, and points to a
file describing your architecture and operating system.  It should be
copied from the source file conf/EDITME-dist, or from one of the small
example files (conf/EDITME-*) if one happens to nearly match your
system.  Note that if you generated the Smail manual pages, the
conf/EDITME file will have already been created for you, though you
should still review and edit it or replace it with one of the other
simple examples.

Future patches to Smail will be applied to conf/EDITME-dist (and the
examples) and it will be your responsibility to make sure that these
changes are reflected in conf/EDITME, as needed.  (This is one place
where source code control tools such as RCS, or SCCS might be most
useful.  CVS keeps track of the entire project, of course.)

The full conf/EDITME-dist mentions just about every compilation and
installation option available in Smail.  It appears to be very large and
complex at first glance.  However you'll see some tiny sample
configurations in other files named conf/EDITME-*.  These files are
actual working configurations used for production systems.  In general
the configuration system is set up in such a way that if you define only
the compiler flags (CPPFLAGS, CFLAGS, LDFLAGS, etc.), and set the
OS_TYPE, Smail will build and install as if it were to be the native
vendor-supplied mailer for the system, and will attempt to mimic (and
thus replace) a sendmail installation in terms of the command-line
interface and standard supplementary files such as the aliases table.

Some sites may also need to create (or fix) an operating system
description file.  To do this, change to the conf/os directory and copy
the file "template" to a name descriptive of your operating system.
Then edit the copy as appropriate.  The basename of this file can then
be used as a value for the OS_TYPE variable in the conf/EDITME file.  If
you create a new operating system description file, please mail it to us
so that we may add it to the distribution.

A simple way to test Smail is to set the variable TEST_BASE in the
conf/EDITME file to a test installation directory.  A "make install"
will create a tree under this directory, with all of the Smail binaries
and utilities.  Smail can then be tested in this directory without
affecting the operation of any other mailers currently working on your
system, including a previous installation of Smail itself.

WARNING:  TEST_BASE is little tested itself, and it is somewhat
	  fragile.  It can affect things outside the test directory if
	  the entire configuration is not complete.

If you're trying to debug an EDITME file, or an OS_TYPE file, you can
simply generate defs.* files in the conf directory by running the
following command from within the conf directory:

	  ROOT=.. sh lib/mkdefs.sh


BUILDING AND INSTALLATION

NOTE:  You should probably do a test build install before installing
       Smail onto a live system.  To do this, setup the TEST_BASE
       variable as described above, paying heed to the warning above
       too, and go through the steps in this section.  Then, to install
       on to a live system, comment out TEST_BASE in the conf/EDITME
       file and perform these steps again.  The second time around, it
       will not be necessary to build the makefile dependencies.


  Dependencies:

When everything is setup, you may optionally create the Makefile
dependencies for your system and configuration.  These dependencies are
stored in ".depend" files in each sub-directory of the source tree.
Some versions of "make" read these files automatically if they exist but
just in case your version doesn't all the "make" commands run by the top
level make will automatically specify these files explicitly wherever
they matter most.

To build all the ".depend" files, type:

	make depend 2>&1 | tee mkdep.out

If you are a C shell (/bin/csh, or tcsh) user (poor you!), try:

	make depend |& tee mkdep.out

at the top of the Smail source tree.

NOTE:  If you have any problems with "make depend" then you might want
       to start over completely and skip this step.  Just remember that
       you'll probably have to do "make clean && make" if you are doing
       any fixing or making other changes to the sources.

If you ran "make depend", scan the output produced by for any errors.
In particular, watch out for missing include files.  If any messages
about missing include files are generated, please send us mail
describing your operating system and the name of the include file which
was not found (you should also enclose your conf/EDITME file, and any
conf/os file you might have modified and be using for the failed build.
Please tell us of any similarly named include files which DO exist,
which may be used instead.

NOTE:  If you do not run "make depend", you should be aware that you'll
likely have to run "make clean" if you change anything between builds to
ensure everything is properly up to date.  This applies especially to
changes in the conf/EDITME file.


  The Build:

The next stop is to build the binaries, utilities and localised manual
pages with the command:

	make 2>&1 | tee mk.out

or for those stuck on csh:

	make |& tee mk.out

(use "-a" with "tee" if you want to preserve the previous contents of
the output log file)

If any errors were encountered, please mail them to us.  Please send a
complete copy of the mk.out file, and a copy of your conf/EDITME file
along with a "patch" (i.e. context diff) of any changes you've made to
the official distribution sources.  In particular if you wrote your own
operating system configuration file, please send that, too.  If you have
any comments, or if you have your own fixes, please send those as well.


  The Install:

When Smail builds correctly, install it by typing:

	make install

NOTE:  Some operating systems prevent a running binary from being
over-written and others exhibit strange behaviour when the running
program is replaced.  If you are re-installing Smail on a system where
it is already running it is best to stop it first.

WARNING:  If you had installed the manual pages for any very old release
of Smail (i.e. one which included routers.5, transports.5, config.5,
etc.), you should remove these old manual pages from the destination
directory.  These manual pages have been renamed and now have the prefix
"smail" as part of their names.

These commands may be typed in any individual directory, as well, to
build or install within a limited context.  Most make command at any
level within the tree will descend to lower levels within the source
hierarchy and execute the same make command.

The following additional make commands can be useful:

	make clean	- to clear out make intermediate files.
	make clobber	- to clean intermediate and target files.


GENERAL COMPILATION NOTES

On ISC's Interactive UNIX (aka 386/ix), and probably on other systems as
well, if you don't use an ANSI C compiler you will get the following
messages while compiling:

	../../util/dbm_compat.h: 13: bad include syntax
	../../util/dbm_compat.h: 22: bad include syntax

Ignore these messages.  They result from an #ifdef'd out:

	#include DBM_INCLUDE

where the C compiler does not allow macros to name include files.  This
doesn't cause any problems when compiling on Interactive, beyond the
generation of the above messages.  If your compiler really bombs out,
remove the offending lines from util/dbm_compat.h.

Smail now makes use of some C data types which may not be defined in the
standard system headers on some older systems.  These include "time_t",
"off_t", "size_t", and the like.  If you get compiler errors related to
definitions or declarations related to these data types, you may be able
to work around the problem by adding appropriate #define statements in
the MISC_DEFINES clause of your conf/EDITME file.  Please see the
instructions in conf/EDITME-dist to see how the syntax for this usage
might work, and consult your system manuals for the appropriate basic
types to substitute for these standard types.


SYSTEM-SPECIFIC CAVEATS

  * There have been reports that some versions of sed(1) [in particular
    the one supplied with HP/UX 9.x and HP/UX 10.x and of course earlier
    HP/UX versions too; as well as Digital UNIX 3.x] cannot handle the
    number of expressions in the defs.sed files produced by the mkdefs
    script, and indeed cause other kinds of breakage when generating the
    "defs.h" files.  The easy work-around is to install a more capable
    version of sed that doesn't trip over this limit, such as the GNU
    Sed.  No other fixes are expected, or desired, as this problem will
    hopefully be moot with the intended conversion to GNU Autoconf.

  * HP/UX 10.50 and 11.00 seem to work fine with the conf/os/hp-ux9.x
    OS_TYPE file provided that you have replaced sed (as above), and
    that you add NEED_HSTRERROR and "-Dconst=" as recommended in
    conf/EDITME-dist.

  * On MIPS systems, and possibly on other dual-universe systems, be
    sure to set the BSD and System V time-zones to the same value.  For
    MIPS systems, the System V time-zone is in /etc/TIMEZONE.  The
    time-zone value used by BSD routines is stored in the kernel and is
    set by the date command.  For example, if you are in the Pacific
    time-zone, set /etc/TIMEZONE to:

	TZ=PST8PDT
	export TZ

    and set the kernel time-zone with:

	date -t 480

    At least one user was surprised to find Smail using a different time-zone
    than some other commands.

  * On SGI systems running IRIX 5.x (and possibly others) the
    <unistd.h> file defines an undocumented instance of "EX_OK" which
    clashes with the normal manifest of the same name in <sysexits.h>.
    You'll get a warning something like this:

	cfe: Warning 581: /usr/include/sysexits.h:107: Macro EX_OK redefined.

    This is OK, though if you see /usr/include/unistd.h instead then you
    may have a problem as the unistd.h value is incorrect for our use.
    In this case you should try re-ordering the include files to make
    sure that <sysexits.h> comes *after* <unistd.h>.

  * Unfortunately SunOS 5.6 (and earlier) still seems to use extremely
    ancient and buggy BIND 4.9.3 resolver code, even in the
    "libresolv.so.2" version introduced by one of the patches.  If you
    do not first install a modern version of BIND, *and* its associated
    resolver library, you will get the following errors at link time:

	Undefined                       first referenced
	 symbol                             in file
	hstrerror                           bindlib.o
	inet_net_pton                       lookup.o
	inet_net_ntop                       smtprecv.o

    You may also get errors like this earlier on if you've got various
    compiler warnings enabled:

	smtprecv.c:342: warning: implicit declaration of function `inet_net_ntop'

    You MUST install and link against the resolver from either
    BIND-4.9.7 or the latest BIND-8.2 release in order to correct this
    problem.

  * SunOS 5.x uses a "name service cache daemon" that's not very
    effective at what it's supposed to do (in particular it gets in the
    way of a real DNS cache and can cause delays and thrashing on a
    system that does a lot of DNS lookups).  If you really insist on
    using the native resolver code then you should consider either
    disabling nscd completely, or at minimum adding "enable-cache hosts
    no" to /etc/nscd.conf to avoid it getting in the way of DNS lookups.

  * It is said that some systems with 32-bit UIDs (eg. Linux with
    glibc2) will suffer problems in places if the nobody ID isn't set
    right.


CREATING CONFIGURATION FILES

If you have need of a more complex configuration than can be provided
with the internal defaults, read over the manual pages carefully.  We
believe that the process of writing files is reasonably straightforward,
though if you have any questions, or if you dispute this claim, please
send mail to the smail3-users list mentioned in the README.

The complete current (live) configuration can be displayed with the
command:

	 smail -v -bP ALL

Note that this is a concatenation of *all* of the configuration files.
See the manual page smail(8) to learn how to extract a specific
configuration file's default content.

If you run this command without any config files, or specify , it will
display the default compiled in configuration and if you already have
config files in place you can fool it into ignoring them:

       smail -v -oL /nosuchdirectory -bP ALL

The configurations printed with '-bP' can be redirected to a temporary
filename, edited as necessary, and copied to the appropriate file.

It is *strongly* recommended that you create only the configuration
files you absolutely need to make Smail work for your environment and
requirements.  Otherwise you should stick as close as possible to the
default configuration and don't set anything that you are not explicitly
setting different from the default.  This way any improvements in future
releases to default parameters will not be hidden by your local
configuration values (eg. the "Received:" header format).

Note also that the old example files are of extremely limited value.
The new default configurations include many improvements over the old
examples from previous releases and indeed some old examples are not
compatible with the current code.

If you're running a simple "leaf" Internet node for one or a few local
domains you likely only need a 'config' file with only a very few custom
settings such as "domains", possibly "visible_name" and
"more_hostnames", and maybe "smtp_accept_max" and "smtp_accept_queue".
Some of the newer security related settings may also be of interest.

If you have been running previous releases of Smail it is *critical*
that you read down through the CHANGES file until you come to the notes
regarding the version you are, or were, running.  There may be important
differences between this release and any previous releases that may
affect the proper operation of Smail in your environment.


RUNNING SMAIL

Smail is used in basically the same way as Sendmail.  It is normally run
as a stand-alone daemon that both listens for incoming SMTP connections
(assuming you've used one of the *-network driver configurations) as
well as periodically checking for and attempting to deliver any messages
in the input queue(s).  It is started in this way with a command like
"sendmail -bd -q30m" and with the '-bd' flag it will automatically put
itself into the background and continue running.  If your system already
runs sendmail then the startup call for it is probably already in
place.  See the smail(8) manual page for further information

Smail normally checks each of its configuration files at the start of
every queue run and if any are found to be newer than the start time of
the current process then smail will restart itself automatically in
order to have the new configuration take effect.

There's also a maintenance script called 'checkerr' that you should run
periodically (daily, or perhaps weekly) from 'cron'.  See the manual
page for checkerr(8) for further information.


SMAIL ON THE INTERNET (VERY IMPORTANT FOR INTERNET USERS)

Users on the Internet should configure Smail to use the Domain Name
Service for routing on the Internet.  To use the DNS, you will have to
have the bind resolver library, and you will have to tell Smail that you
have it.  For some systems, these are configured into Smail by default.
For other systems, you will need to configure in the bind router driver
by modifying the EDITME file.  This involves adding the setting:

	DRIVER_CONFIGURATION=arpa-network

and adding "BIND" to the HAVE list.  See the EDITME file in the conf
directory for more details.


SMAIL WITH SYSTEM V RELEASE 2&3 AND SUNOS-4

SunOS-4 and System V Release 2&3 systems typically have a /bin/mail
program that both delivers mail and reads mail.  Smail provides a
replacement for the /bin/mail program, in pd/binmail, that uses the old
/bin/mail for reading mail, and Smail for delivering mail.  To use the
replacement /bin/mail, you will need to define the LMAIL variable in
conf/EDITME.  See conf/EDITME for more instructions.

The System V mailx utility will need to be updated to know how to find
Smail.  Presuming that Smail is installed as /usr/lib/sendmail, you
will need to add the following line to the file /usr/lib/mailx/mailx.rc:

	set sendmail=/usr/lib/sendmail

The SunOS-4 Mail utility already has this defined.

In any case you should ensure that /usr/lib/sendmail is included in
conf/EDITME as either the value for SMAIL_NAME, or is included in the
OTHER_SMAIL_NAMES setting.  For example on SunOS-4:

	OTHER_SMAIL_NAMES=/usr/lib/sendmail:/usr/ucb/mailq


SMAIL AND SCO UNIX

Smail under SCO UNIX must be installed as both /bin/rmail and
/usr/lib/mail/execmail.  To do this, set OTHER_SMAIL_NAMES in the
conf/EDITME file to "/bin/rmail:/usr/lib/mail/execmail".  Some newer SCO
UNIX systems also have a /usr/bin/rmail, as a link to /usr/bin/mailx.
This link should be deleted.  Note that (at least in 3.2v4.2)
/usr/bin/mailx, /usr/bin/mail, and /bin/mail are all links to the same
binary and they can all be left that way.

Some versions of SCO UNIX store mail messages in /usr/spool/mail,
while others use /usr/mail, like System V.  If your system uses
/usr/spool/mail, you will need to add the following line to the
conf/EDITME file:

	MAILBOX_DIR=/usr/spool/mail

Current SCO releases use MMDF mailbox file formats.  Many users prefer
to use public domain mail readers, such as elm or mush, that can be
configured to use regular UNIX mailbox files.  Smail will use MMDF
format by default on SCO UNIX systems unless you add NO_MMDF_MAILBOXES
to MISC_DEFINES.

The SCO MMDF version of mailx supplies its own From: line using a
hostname taken from an MMDF configuration file.  I have no idea why
they decided it was a good idea to hard-code the hostname in a
configuration file, but they did.  Thus, if you change your hostname,
your From: lines won't change until you change the MMDF configuration
file.  To correct the From: line change the MLDOMAIN and MLNAME
definitions in /usr/mmdf/mmdftailor.

To get the MMDF-ified SCO to call Smail via /usr/lib/mail/execmail from
mailx, add the line:

	set execmail

to the file /usr/lib/mail/mailrc.  I'm not sure if this really does
anything, or not though, as in tests on SCO UNIX 3.2v4.2 mailx always
invoked /usr/lib/mail/execmail.


SMAIL AND SYSTEM V RELEASE 4

On many SVR4 implementations the mailbox file format defines a
Content-Length field that indicates the length of each message, in
bytes.  This obviates the need for inserting "> before lines beginning
with "From " (and indeed, there are some problems with the AT&T-supplied
version of mailx concerning message splitting, if you don't use the
Content-Length header).  Smail can be configured to generated
Content-Length fields (and Content-Type fields).  However, the
compiled-in transports cannot do this.  To configure generation of these
fields, copy the file samples/generic/transports to the /usr/lib/smail
directory, and modify it as suggested at the top of the file.

In SVR4 the uux command is given message grades by using long names,
which differs from older versions of HoneyDanBer UUCP, where message
grades were a single character.  Smail does not support these longer
names.  Fortunately, you can configure SVR4 to support single
character message grades.  To make SVR4 compatible with Smail, add the
following lines to your /etc/uucp/Grades file:

9	9	Any	User	Any
A	A	Any	User	Any
C	C	Any	User	Any
a	a	Any	User	Any
n	n	Any	User	Any

This list is sufficient for the default list of Precedence header
field values supported by Smail.

It is possible to configure an SVR4 system to call Smail by replacing
the file /etc/mail/mailsurr with the line:

	'(.+)'	'(.+)'	'< /usr/local/smail/bin/smail -em -i \\2'

This works, but it has the annoying side effect of invoking smail
multiple times for each address given as an argument to /bin/mail or
/bin/rmail.  It is preferable to replace /bin/rmail with smail, and to
replace /bin/mail with the mail program supplied in pd/binmail.

To configure SVR4 to use Smail for handling SMTP, move the file
/etc/rc2.d/S88smtpd to /etc/rc2.d/no-S88smtpd, move the file
/etc/rc0.d/K74smtpd to /etc/rc0.d/no-S74smtpd, and then add a new file
/etc/rc2.d/S88smail containing:

	/usr/lib/sendmail -bd -q30m

Then, kill any existing smtpd program and start Smail by executing the
above command.

To convert an SVR4.2 system create the same file above, remove the
smtpd entry in /etc/inetd.conf, then execute the following commands:

	sacadm -k -p inetd
	sacadm -s -p inetd
	/usr/lib/sendmail -bd -q30m


SMAIL AND 4.3BSD OR ULTRIX

Some versions of Ultrix, plus stock 4.3BSD, have had problems in with
some shell scripts supplied with Smail.  We have made some attempts to
simplify the offending shell scripts to avoid problems.  However, if
errors are still encountered with /bin/sh, then use a different shell,
such as ksh, zsh, pdksh, or bash, by compiling and installing Smail with
commands like:

	make SHELL=/bin/ksh depend
	make SHELL=/bin/ksh all
	make SHELL=/bin/ksh install

Some problems have also been reported with /bin/sh on Xenix.  I don't
know if there is an alternate shell available on Xenix, though I expect
pdksh would install and work just fine.  I realize that it seems absurd
that regular /bin/sh cannot be used on some systems.  Hopefully the
specific problems encountered can be found and remedied for future
releases.


RFC1413 SUPPORT

Smail contains support for RFC1413 identification of incoming SMTP/TCP
traffic.  This allows tracking of who sent mail within a trusting
community.  (By "trusting community", we mean that if you don't trust
root on the sending system then you cannot trust the RFC1413 ident
info supplied by the sending system.)  It also allows you to record the
identity of the connection originator from the sending system should
they ever request it back from you (often the sending system will encode
a cryptographically secure token that will be returned by Smail's ident
query.  This token will be logged by the sending system, and of course
by Smail too, which will enable either site to establish the identity of
the sending user should this ever be required.

The support is via the libident library, which is not part of the Smail
package.  Libident, currently at version 0.22 (November 4, 1998), is
available from a number of sites (use http://ftpsearch.lycos.com/, etc.,
to find one) or get it from the master site by anonymous FTP:

	<URL:ftp://ftp.lysator.liu.se/pub/ident/libs/>

This site also has information about RFC1413, servers for RFC1413 and
all sorts of other ident related goodies.

When you have the library code, you must compile it, and put the library
somewhere where it will be seen by the compiler and linker (use the "-I"
and "-L" switches in EDITME for CFLAGS and LDFLAGS respectively).
Change EDITME to define "RFC1413" in the HAVE lines and add "-lident" to
the LIBS.


WHOSON SUPPORT

Smail contains support for Eugene Crosser's WHOSON daemon.  This daemon
allows use of the special keyword "whoson" to be used when testing remote
client IP addresses for authorisation of such functions as remote SMTP
mail relay (i.e. in the configuration variable "smtp_remote_allow" and
other related variables).  If you have integrated WHOSON support into
your RADIUS daemon (or other authentication servers, such as your
POP/IMAP servers) then you may wish include WHOSON support in Smail to
allow roaming users to also use your system as an outgoing mail relay
just as they would if they were connecting from one of your own access
points of presence.

The WHOSON package is not part of the Smail distribution.  It is
currently at version 1.09 (Sept. 3, 1999) and is available separately
from a number of sites (use http://ftpsearch.lycos.com/, etc., to find
one) as well as from its master site by anonymous FTP:

	  <URL:ftp://ftp.average.org/pub/whoson/>

Change your conf/EDITME to define "LIBWRAP" in the HAVE lines and add
"-lwrap" to the LIBS.  Remember to add the necessary "-I" and/or "-L"
switches for CFLAGS and LDFLAGS respectively in your conf/EDITME as
necessary.

For more information about the WHOSON protocol and daemon please see the
following WWW site:

	  <URL:http://www.average.org/whoson/>


MEMORY ALLOCATION DEBUGGING SUPPORT

Smail contains support for memory allocation debugging.  Currently only
the SunOS-4 debugging malloc and Malloc Library by Mark Moraes (U. of
Toronto CSRI Malloc, or "Yet another malloc()") are supported.  You can
probably only use the former if you're running on SunOS-4 (or perhaps
under NetBSD with SunOS-4 emulation).  The latter library is available
from the following FTP site:

	<URL:ftp://ftp.cs.utoronto.ca/pub/moraes/>

Please see the conf/EDITME-dist file for more details.