******************************************************************************
File: sendmail.txt                       Version 2.0               05-Feb-1995
                                         Niel Kempson <kempson@snowyowl.co.uk>
******************************************************************************


Configuring sendmail for use with the Warp Internet Access Kit
==============================================================


Contents
--------

     1. Introduction
     2. Assumptions
     3. Configuring sendmail
        3.1 Delivering mail to UltiMail/2
        3.2 Delivering mail to LAMail
     4. The HOSTS file
     5. Sendmail aliases
     6. Running the sendmail daemon
     7. Testing your sendmail setup
     8. Sendmail error codes
     9. Frequently encountered problems (FEPs)
    10. What if it still doesn't work ?
    11. Useful references
    12. Change log



1. Introduction
---------------

Please make sure that you have read the accompanying file 00README.TXT
which explains the purpose of this kit.

The critical link in the SMTP chain is the sendmail.exe program.  It
delivers outgoing messages using SMTP and also acts as a server waiting
for incoming messages.  This document tells describes how to configure
sendmail to work on your Warp/IAK system to exchange mail with the
outside world using SMTP.

The instructions are by no means comprehensive and they are probably
unclear in places so please feed back any constructive suggestions
(including typos) so that I can improve this kit.  All of the information
in this guide has been gleaned from books, examination of binary files
etc.  There's nothing in here that could possibly be construed as
official IBM information.



2. Assumptions
--------------

Throughout this document I have assumed that the IAK software has been
installed under the C:\TCPIP directory.  If you have not installed it in
this directory, you will need to adjust the examples quoting file
specifications to suit your system setup.



3. Configuring sendmail
-----------------------

Sendmail's behaviour is largely defined by a single configuration file
(usually called sendmail.cf), the contents of which resemble a knitting
pattern!  The Warp IAK does not provide a working sendmail configuration
file for use with SMTP mail, so I have included my working configuration
file.  It was derived from the standard configuration provided with IBM
TCP/IP, which in turn was derived from the Berkeley Unix distribution.

This kit includes an example configuration file (SENDMAIL.CF) that I use
to allow UltiMail/2 Lite to work as an SMTP client rather than the usual
POP client.  As supplied, the configuration file supports:

    o   my official host name: snowyowl.demon.co.uk

    o   mail also accepted for other aliases: sos-gate.demon.co.uk,
        snowyowl.com, snowyowl.co.uk & sos.co.uk

    o   IBM Warp IAK installed in C:\TCPIP

    o   all outgoing mail is sent to post.demon.co.uk for onward routing
        and delivery

You will need to edit this file and customise it for your setup.

NOTE:   You must use an editor that preserves TAB characters.  Do NOT use
        the EPM or TEDIT editors that come with OS/2 - they expand TABs
        into spaces and will cause the configuration file to be useless.
        The E editor is OK.

Search for the string "---EDIT---" in this file and edit the following
line(s) in accordance with the notes in the adjacent comment block.  There
are 10 occurrences of "---EDIT---" to check.  PLEASE make sure that you check
each of them before firing up sendmail.  

The changes that you need to make are summarised below:

    EDIT---01   define the name of your host (without any domain
                appended), plus any aliases within the same domain for
                which you will accept incoming mail.

    EDIT---02   define the domain in which your host lives.

    EDIT---03   define the "smart" mail relay, to which you send all
                outgoing mail for onward transmission.

    EDIT---04   define the location of the sendmail aliases file.

    EDIT---05   define the location of the sendmail help text file.

    EDIT---06   define the directory holding mail messages queued for
                transmission.

    EDIT---07   define the location of the sendmail statistics file.

    EDIT---08   define any aliases in another domain for which you will
                accept incoming mail.

    EDIT---09   define any aliases in another domain for which you will
                accept incoming mail.

    EDIT---10   define the command used to deliver incoming messages to
                your local mail program (e.g. UltiMail/2, LAMail).

Remember that the sendmail.cf contains notes above each of the "EDIT---"
points, explaining what you need to do.  If they are unclear, please let
me know.


    3.1  Delivering mail to UltiMail/2
    ----------------------------------

    If you use UltiMail/2 as your local mail program, you need to:
    
        o   make sure that you have selected the appropriate "Mlocal"
            line under "EDIT---10" to call the umailer.exe program.
            
        o   copy the configured SENDMAIL.CF to C:\TCPIP\ETC\SENDMAIL.UML.

        o   copy SENDMAIL.HF to C:\TCPIP\ETC\SENDMAIL.HF.
        
        o   read the accompanying file ULTIMAIL.TXT


    3.2  Delivering mail to LAMail
    ------------------------------

    If you use LAMail as your local mail program, you need to:
    
        o   make sure that you have selected the appropriate "Mlocal"
            line under "EDIT---10" to call the mail.exe program.
            
        o   copy the configured SENDMAIL.CF to C:\TCPIP\ETC\SENDMAIL.CF.

        o   copy SENDMAIL.HF to C:\TCPIP\ETC\SENDMAIL.HF.
        


4. The HOSTS file
-----------------

When connected to the Internet, you will normally use the Domain Name
Service (DNS) to resolve host names and addresses.  When you try to queue
or deliver a mail message, sendmail attempts to resolve the IP address of
destination host.  If your dial-up link isn't running, sendmail will be
unable to access the DNS to resolve the host and will bounce the message
with an "error 68 - unknown host" message.

If the DNS is unavailable, IBM TCP/IP will look in the C:\TCPIP\ETC\HOSTS
file for the host name.  Since you can't reasonably put all possible
destination hosts in your HOSTS file, the best way to avoid this problem
is always to send outgoing mail via a "smart" mail host and make sure
that this host is included in the hosts file.  

Make sure that the DV macro is defined in sendmail.cf to send mail via
a "smart" mail host, usually your provider's mail host, and make sure
that this host is defined in the HOSTS file.  A minimum HOSTS file would
be:

    127.0.0.1       localhost
    a.b.c.d         yourhost.your.domain yourhost   # change this line
    w.x.y.z         smart.mail.host                 # change this line

For Demon Internet subscribers, I strongly recommend that you route all
outgoing mail via post.demon.co.uk and edit your SENDMAIL.CF and HOSTS
files to contain these entries:

    SENDMAIL.CF:

        #---EDIT---03---
        DVpost.demon.co.uk

    HOSTS:

        127.0.0.1       localhost
        158.152.1.72    post.demon.co.uk  post
        158.152.x.y     yourhost.demon.co.uk yourhost   # change this line



5. Sendmail aliases
-------------------

Sendmail supports an external alias file to allow redirection of SMTP mail.
By default, the alias file is C:\TCPIP\ETC\ALIASES and is in the following
format:

    #
    # Comment lines begin with hashes
    #
    alias:      real-address
    alias:      real-1,real-2

The alias must be a local name (i.e. no "@" in the name), but the
real-address part can be non-local.  Aliases are not case-sensitive, but
aliases referenced by other aliases MUST be lower case.  You can use the
aliases file to ensure that incoming mail is routed to a single mailbox:

    # Alias file
    postmaster:         kempson
    root:               kempson
    MAILER-DAEMON:      kempson
    help:               kempson,smith

If you are using your dial-up machine as a mail gateway between a local
network and the Internet, the alias file provides a convenient means of
forwarding incoming mail to the internal network users.  It's a good idea
to alias postmaster (which every Internet host must support) to your
normal e-mail address.

For example, Internet mail to snowyowl.com users will arrive via the
PPP/SLIP connection and then could be forwarded to systems on the
internal network by using an alias file like:

    # Alias file
    postmaster:         kempson
    help:               kempson,smith
    kempson:            kempson@host1.snowyowl.com
    jones:              jones@host2.snowyowl.com
    smith:              smith@host2.snowyowl.com

When sending out mail, the user systems should ensure that the "Reply-To"
address is set to that of the dial-up gateway:

    Reply-to: John Smith <smith@snowyowl.com>

and that the local machines forward their mail to the dial-up gateway for
onward delivery.

For Unix users, there is no equivalent to the "newaliases" or "sendmail -bi"
commands to build an indexed database of aliases - the alias file is read
each time sendmail is started.



6. Running the sendmail daemon
------------------------------

To receive SMTP mail, your system must be running the sendmail daemon
when the dial-up connection to the Internet is active.  It will listen
for incoming SMTP connections (receiving mail) and will periodically
examine the local mail queue and attempt to send any messages waiting
there.

The command used to start the sendmail daemon is:

    c:\tcpip\bin\sendmail -Cc:\tcpip\etc\sendmail.uml -d1.1 -bd -q5m

where the options mean:

    -Cc:\tcpip\etc\sendmail.uml     specify the configuration file 
    -d1.1                           log incoming messages ("-d" generates
                                    *lots* of debugging information)
    -bd                             run in background ('daemon') mode
    -q5m                            check the outgoing queue every 5 minutes

You need to start the sendmail daemon *after* the PPP/SLIP connection is
up and running.  If you try to start it beforehand, sendmail will stop
with the error message "TCP/IP not functioning; exit sendmail".

A convenient place to start sendmail is in a separate command file that
tests to see if the link is up and running before launching any network
applications.  The file should look something like:

    ECHO Waiting for SLIP link to start ...
    slipwait 600
    
    IF ERRORLEVEL 1 GOTO noslip
        ECHO SLIP link is running, starting sendmail ... 
        start /n sendmail -Cc:\tcpip\etc\sendmail.uml -d1.1 -bd -q5m
    
        GOTO exitlabel
    :noslip
        ECHO SLIP not running - no daemons started
    :exitlabel

In this example, SLIPWAIT waits for up to 600 seconds to see if the SLIP
connection is running.  If it is, SLIPWAIT exits with an ERRORLEVEL of 0,
otherwise an ERRORLEVEL of 1 indicates that the link has not been
started.

The bad news is that SLIPWAIT does not detect when a PPP link has been
successfully established and IBM hasn't provided a PPPWAIT command :-(

IBM's sendmail is broadly compatible with the Unix implementations of
sendmail v5.65, but not the newer sendmail v8.  Some of the command line
options available are: -bd, -bt, -C, -d, -d#.#, -q<time>, -f <addr>, -t.
Command line options not available include -ba, -bi, -bm, -bp, -bs, -bv,
-bz, -v.



7. Testing your sendmail setup
------------------------------

o   make sure that the mail queue directory (C:\TCPIP\ETC\MQUEUE) is
    empty

o   delete or rename the SENDMAIL.LOG and SENDMAIL.ERR files in
    C:\TCPIP\ETC

o   create a test message file called "LOCAL.TXT" containing these five
    lines:

        >To: userid@yourhost.your.domain
        >From: userid@yourhost.your.domain
        >Subject: local test
        >
        >Hello

    where ">" denotes the beginning of the line - don't include it!
    
o   make sure that the PPP/SLIP connection is not running and then start
    sendmail to deliver the message with this command (all on *one* line):
    
        sendmail -t -af local.txt

    but replace "userid@yourhost.your.domain" with your official e-mail
    address.  
    
o   If the PPP/SLIP connection has never been started since you booted
    the machine, you'll see something like:
    
        IBM OS/2 SENDMAIL VERSION 1.3.6)
        Reading c:\tcpip\etc\sendmail.cf 10
        TCP/IP not functioning; message queued

    If you have a look in the mail queue directory (C:\TCPIP\ETC\MQUEUE),
    you should see two files called dfAAxxxx and qfAAxxxx, where xxxx is
    a four digit number.  The file dfAAxxxx contains your message and
    qfAAxxx is the control file that contains the mail headers and other
    information.  It should be in a similar format to this:

        P1025
        T791407275
        DdfAA0019
        Suserid@yourhost.your.domain
        Ruserid@yourhost.your.domain
        H?P?return-path: <yourhost.your.domain>
        Hreceived: by yourhost.your.domain
                (IBM OS/2 SENDMAIL VERSION 1.3.6)/(1.1sos)
	        id AA0019; Sun, 5 Feb 95 19:21:15 GMT
        H?D?date: Sun, 5 Feb 95 19:21:15 GMT
        H?F?from: userid@yourhost.your.domain
        H?x?full-name: 
        H?M?message-id: <9502051921.AA0019@yourhost.your.domain>
        Hsubject: local test

o   If the PPP/SLIP connection has been started since you booted the
    machine, the TCP/IP stack will still be running and you'll see
    something like:
    
        IBM OS/2 SENDMAIL VERSION 1.3.6)
        Reading c:\tcpip\etc\sendmail.cf 10
        02/05/95 19:32:09 mail delivered from: userid@yourhost.your.domain

    If you've already configured your local mailer, it should let you
    know that a mail message has arrived.



8. Sendmail error codes
-----------------------

Sendmail is capable of exiting with a fair number of status values,
nearly all of which indicate an error of some sort.  Both LAMail and
UltiMail/2 report the error number but offer little or no explanation.
The standard Berkeley Unix distribution includes source code for
sendmail, so I've stolen the bits that document the exit status values
(sysexits.c, sysexits.h) and included extracts here.  Naturally, IBM may
have re-interpreted some of the status values or introduced new ones.

    Status  Meaning
    ---------------------------------------------------------------------
    0       EX_OK: successful termination.

    64      EX_USAGE: sendmail was called incorrectly, e.g. with the
            wrong number of arguments, a bad flag, a bad syntax in a
            parameter etc.
                    
    65      EX_DATAERR: the input data was incorrect in some way.  This
            should only be used for user's data & not system files.
            
            This error commonly occurs when you queue a message for
            delivery after shutting down a dial-up PPP/SLIP connection.
            For some reason, the IBM TCP/IP stack remains loaded and
            sendmail.exe (plus most other applications) think that the
            network is still running.  Sendmail tries to deliver the
            message and naturally fails to make contact with the host at
            the other end and returns error 65 when the transaction times
            out.

    66      EX_NOINPUT: an input file (not a system file) did not exist or
            was not readable.  This could also include errors like "No
            message" to a mailer (if it cared to catch it).

    67      EX_NOUSER: the user specified did not exist.  This might be
            used for mail addresses or remote logins.

    68      EX_NOHOST: the host specified did not exist.  This is used in
            mail addresses or network requests.

            At the time of sending the mail message, sendmail tries to
            resolve the IP address of the destination host.  If the
            network is not running, sendmail cannot use the domain name
            service and will only be able to resolve hosts specified in
            the \TCPIP\ETC\HOSTS file.  If the destination host isn't
            specified in the HOSTS file, sendmail will reject your
            message with error 68.

            The best way to avoid this is always to send outgoing mail
            via a "smart" mail host and make sure that this host is
            included in the hosts file.

    69      EX_UNAVAILABLE: a service is unavailable.  This can occur if
            a support program or file does not exist.  This can also be
            used as a catchall message when something you wanted to do
            doesn't work, but you don't know why.

    70      EX_SOFTWARE: an internal software error has been detected.
            This should be limited to non-operating system related errors
            wherever possible.

    71      EX_OSERR: an operating system error has been detected.  This
            is intended to be used for such things as "cannot fork",
            "cannot create pipe", or the like.  It includes things like
            getuid returning a user that does not exist in the passwd
            file.

    72      EX_OSFILE: some system file (e.g. /etc/passwd, /etc/utmp,
            etc.) does not exist, cannot be opened, or has some sort of
            error (e.g. syntax error).

    73      EX_CANTCREATE: a (user specified) output file cannot be
            created.

    74      EX_IOERR: an error occurred while doing I/O on some file.

    75      EX_TEMPFAIL: temporary failure, indicating something that is
            not really an error.  In sendmail, this means that a mailer
            (e.g.) could not create a connection, and the request should
            be reattempted later.

    76      EX_PROTOCOL: the remote system returned something that was
            "not possible" during a protocol exchange.

    77      EX_NOPERM: you did not have sufficient permission to perform
            the operation.  This is not intended for file system problems
            (which should use EX_NOINPUT or EX_CANTCREAT) but rather for
            higher level permissions.

    78      EX_CONFIG: sendmail detected an error in its configuration
            file (SENDMAIL.CF).



9. Frequently encountered problems (FEPs)
-----------------------------------------

The most common problems encountered with sendmail are summarised below.


Problem:    After starting sendmail, it immediately exits with the
            message "TCP/IP not functioning; exit sendmail".

Reason:     Sendmail doesn't recognise that the TCP/IP is running.  This
            is probably because the PPP/SLIP link is not running.  
            
            There have been some reports that the sendmail.exe supplied
            with Warp cannot detect the TCP/IP stack provided by IBM
            TCP/IP v2.  The solution is apparently to revert to the
            version of sendmail supplied with IBM TCP/IP (it's sendmail
            v1.2.10).


Problem:    Sendmail produces lots of messages complaining about
            "invalid rewrite rules" when it starts up.

Reason:     The sendmail configuration file has been edited by a
            TAB-expanding editor
        

Problem:    After sending a mail message, you receive a message from
            MAILER_DAEMON reporting a sendmail error 65.

Reason:     Sendmail couldn't connect to the destination host, even
            though it thinks that the network is running.  The mail will
            be queued for transmission later.


Problem:    After sending a mail message, you receive a message from
            MAILER_DAEMON reporting sendmail error 68.

Reason:     Sendmail can't resolve the IP address of the destination
            host, usually because the DNS is unreachable (you're
            off-line) and the host isn't in your HOSTS file.  The message
            will be bounced back to you.
                

Problem:    Sendmail doesn't recognise incoming mail as destined for the
            local host.
        
Reason:     The "Cw" and "Dw" definitions in the configuration file
            (under "---EDIT---01") are usually missing or wrong


Problem:    Mail arrives but isn't delivered to the local mail program
            for you to read.
        
Reason:     The "Mlocal" line usually specifies the wrong mail program or
            disk + directories



10. What if it still doesn't work ?
-----------------------------------

Unfortunately, there are many things that can go wrong with SMTP mail.  The
clues will usually be found in the log and error files created by sendmail:

    C:\TCPIP\ETC\SENDMAIL.ERR
    C:\TCPIP\ETC\SENDMAIL.LOG
    
It is possible to make sendmail create large quantities of debugging
information by starting it with the "-d" option rather than the "-d1.1"
(see section 6).

If you contact me for help, be prepared for me to ask you to send me the
files C:\TCPIP\ETC\SENDMAIL.* as a UUencoded ZIP file.



11. Useful references
--------------------

Internet RFCs providing useful information about SMTP services and mail:

    RFC-822     Standard for the format of ARPA Internet text messages.
    RFC-1123    Requirements for Internet hosts - application and support.  

RFCs are available by anonymous FTP from many sites, including:

    flash.bellcore.com:/pub/rfc
    ftp.demon.co.uk:/pub/doc/rfc
    gatekeeper.dec.com:/.3/net/info/rfc
    munnari.oz.au:/rfc
    nic.ddn.mil:/rfc
    sunsite.doc.ic.ac.uk:/pub/rfc

"Sendmail" by Bryan Costales with Eric Allman & Neil Rickert.
O'Reilly & Associates Inc.  ISBM 1-56592-056-2.

    An authoritative 800 page book on the internals of sendmail and its
    configuration.  This book is a must if you want to understand and
    hack sendmail configuration files, but otherwise it's probably a bit
    too esoteric for general reading.

Sendmail source code has been released as part of the Berkeley Unix
distribution.  It contains the authoritative documentation for sendmail,
but it's really only for those who can't afford the sendmail book or find
that it's missing some vital information.  The sendmail source code is
available by anonymous FTP from many sites, including:

    ftp.demon.co.uk:/pub/BSD/4.4BSD-Lite/usr/src/usr.sbin/sendmail



12. Change log
--------------

    2.0 [05-Feb-1995] Niel Kempson <snowyowl.co.uk>
        Initial version in the revised format.

********************************* END OF FILE ********************************
