******************************************************************************
File: 00readme.txt                       Version 1.0     27-Nov-1994
                                         Niel Kempson <kempson@snowyowl.co.uk>
******************************************************************************


Configuring UltiMail/2 Lite for SMTP Mail
=========================================


Contents
--------

    1.  Introduction
    2.  Assumptions
    3.  Running the Sendmail Daemon
    4.  Configuring Sendmail
    5.  Sendmail aliases
    6.  Configuring UltiMail/2 Lite
    7.  Testing Your Setup
    8.  Testing Your Setup
    9.  Useful References
    10. Change Log



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

UltiMail/2 Lite is supplied as part of the Internet Access Kit (IAK)
accompanying the new OS/2 Warp 3.  UltiMail/2 Lite is described and
configured by IBM as a mail client using the Post Office Protocol (POP) to
exchange mail with a designated server machine.  Some Internet access
provides offer POP servers, but some do not and assume that your site is
capable of using the standard SMTP (Simple Mail Transfer Protocol) services.

This small kit describes how to set up your Warp/IAK system to use UltiMail/2
Lite as your mail package and exchange mail with the outside world using
SMTP rather than POP.  The instructions are by no means comprehensive and
they are probably unclear in places so please feed back any constructive
suggestions to improve this kit.



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 files specifications
to suit your system setup.



3. Running the Sendmail Daemon
------------------------------

To receive SMTP mail, your system must be running the sendmail daemon when
the SLIP 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
    -bd                             run in background ('daemon') mode
    -q5m                            check the outgoing queue every 5 minutes

You need to start the sendmail daemon *after* the 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 the C:\TCPIP\BIN\DIALUP.CMD batch
file, after the dialup/logon sequence has been completed.  The file should
look something like:

    /* call dialling and logging on script */
    if diallogon() then do
        say '** Connected'
        'route -fh' 
        'arp -f'
        'ifconfig sl0 158.152.22.209 158.152.1.65'
        'route add default 158.152.1.65 1' 

        /* This is the place to start sendmail and other daemons. */
        'start sendmail -Cc:\tcpip\etc\sendmail.uml -d1.1 -bd -q5m'
    end
    else do
        say '** Failed to connect'
        pause
        'killem slip.exe'  
    end



4.  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 it has been necessary to steal the standard
configuration provided with IBM TCP/IP and modify it for UltiMail/2 Lite. 

This kit includes the configuration file (SENDMAIl.UML) 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.

After configuring SENDMAIL.UML, copy it to the C:\TCPIP\ETC directory.
Also copy the accompanying SENDMAIL.HF file to the C:\TCPIP\ETC directory.



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

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

    # Alias file
    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 SLIP gateway:

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

and that the local machines forward their mail to the SLIP 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.  Configuring UltiMail/2 Lite
-------------------------------

Make sure that the SLIP connection is not running, then start the UltiMail/2
Lite "Mail Cabinet". You will soon see a pop-up box entitled "Not Connected
to the Internet" inviting you to connect now.  Click on the "Don't connect"
button.

When UltiMail is a little over halfway through its loading process, another
pop-up box entitled "Accessing a Mail Server" will appear.  The password and
Server fields should be empty - click on the "Cancel" button because you
don't want to connect to a POP server.

When the Mail Cabinet has started, click on the "Cabinet" menu and then the
"Settings" item of that menu.  A typical OS/2 settings notebook entitled
"UltiMail - Settings" will appear.  The important settings for SMTP use are
summarised below:

    Page 2 of 6

        Enter your full From and Reply-To addresses.  I use:

                Niel Kempson <kempson@snowyowl.co.uk>

        for both.

    Page 4 of 6

        Make sure that the "Logon" check box is set.

UltiMail/2 Lite is now ready to use with SMTP.  You do not need to have the
SLIP connection running ("Not Connected to the Internet" pop-up) to compose
mail and you must not specify the POP server and password ("Accessing a
Mail Server" pop-up).



7.  Testing Your Setup
----------------------

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

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

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

o   make sure that the SLIP connection is NOT running and then start
    UltiMail/2 Lite and open the In-Basket window.

o   Compose a message to yourself at your local mail address 
    (e.g kempson@snowyowl.demon.co.uk) and send it.  You should see a dd
    pop-up box entitled "Letter Sent or Queued Successfully".  The message
    will not be delivered into your UltiMail/2 InBox until the SLIP
    connection and the sendmail daemon are started.  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:

        P1485
        T785972470
        DdfAA0285
        Skempson
        Rkempson@snowyowl.co.uk
        H?P?return-path: <kempson@snowyowl.demon.co.uk>
        Hreceived: by snowyowl.demon.co.uk
                        (IBM OS/2 SENDMAIL VERSION 1.3.6)/(1.0sos)
	                id AA0285; Sun, 27 Nov 94 21:41:10 GMT
        H?x?full-name: 
        H?M?message-id: <9411272141.AA0285@snowyowl.demon.co.uk>
        Hmime-version: 1.0
        Hdate: Sun, 27 Nov 94 21:40:52 +0000
        HFrom: Niel Kempson <kempson@snowyowl.co.uk>
        HTo: "Niel Kempson" <kempson@snowyowl.co.uk>
        HReply-To: Niel Kempson <kempson@snowyowl.co.uk>
        Hsubject: Test 1
        Hx-mailer: Ultimedia Mail/2 Lite, IBM T. J. Watson Research Center
        Hcontent-type: text/plain; charset="US-ASCII"
        Hcontent-id: <284_71_1_785990454>
        Hcontent-transfer-encoding: 7Bit
        Hcontent-description: <none>

o   make sure that the UltiMail/2 In-Basket window is still open, then start
    the SLIP connection and then the sendmail daemon (see section 3 above).
    Just after the sendmail daemon starts, you should see a message in its
    window saying that it has delivered a mail message to you and UltiMail/2
    will chime shortly afterwards.
    
o   try sending some external mail messages to make sure that mail is
    accepted from other hosts.  Three automatic ways spring to mind:
    
    o   send to a mail "mirror" that automatically replies to you.
        Unfortunately, I don't know of any :-((

    o   send mail to yourself via another system using the "percent hack".
        E.g. I can send to "kempson%snowyowl.com@post.demon.co.uk" to make
        the mail go to post.demon.co.uk before coming back to me;
        
    o   send a "help" message to one of the Bitnet list servers.  E.g. send a
        message to "listserv@hearn.nic.surfnet.nl" with a message text of
        "help".
    
    Whichever method you use should result in a reply, possibly within a
    minute if your network connection is lightly loaded.  When the reply
    arrives, UltiMail/2 should chime again.



8.  What if it 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
and UltiMail/2:

    C:\TCPIP\ETC\SENDMAIL.ERR
    C:\TCPIP\ETC\SENDMAIL.LOG
    C:\TCPIP\UMAIL\UMAIL.ERR
    C:\TCPIP\UMAIL\UMAIL.LOG
    
It is possible to make sendmail and UltiMail/2 create large quantities of
debugging information by specifying appropriate command line options.

    Sendmail: start it with the "-d" option rather than the "-d1.1" quoted in
    section 3.

    UltiMail/2: start it from the command line rather than by clicking on an
    icon:

    	C:
    	CD \TCPIP\UMAIL
    	UMAIL /LOGLEVEL=C_FLOW



9.  Useful References
---------------------

Internet RFCs providing useful information about SMTP and POP services
and mail:

    RFC-822     Standard for the format of ARPA Internet text messages.
    RFC-1123    Requirements for Internet hosts - application and support.  
    RFC-1082    Post Office Protocol: Version 3: Extended service offerings.  
    RFC-1225    Post Office Protocol version 3

RFCs are available by 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.



10. Change Log
--------------

    1.0 [27-Nov-1994] Niel Kempson <snowyowl.co.uk>
        Initial Version.

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