SMTP - a simple SMTP client for OS/2
------------------------------------

This is a very simple and basic SMTP client, which will take mail
messages (stored one per file) and send them to an SMTP server.  It is
designed to work only with my SMTP server, available separately.  It is
not sophisticated, but it is small and fast.

All companion programs are available from the same place:

     http://www.tavi.co.uk/os2pages/mail.html

Installation
------------

Copy the SMTP.EXE file to any suitable directory which is named in the
system PATH (actually, this isn't strictly necessary but it can make
life easier).  Copy the NETLIB.DLL file to any directory on the LIBPATH.

Configuration
-------------

First, ensure that you have a line in CONFIG.SYS of the form:

     SET TZ=....

This defines your time zone setting, names, and daylight saving rules.
If you don't have one, you need to add it; the actual value can be quite
complex.  For the United Kingdom, the line is:

     SET TZ=GMT0BST,3,-1,0,3600,10,-1,0,7200,3600

For other areas, download the TZCALC utility from the same place as this
program.  This will work out the correct setting for you.  It will be
necessary to reboot in order to pick up this setting, but wait until you
have completed the rest of these instructions.

Now edit CONFIG.SYS, adding a new line of the form:

     SET SMTP=directoryname

where 'directoryname' is the name of a directory (which must exist)
where outgoing mail is to be stored.

This step is not strictly necessary, as it is possible to specify this
when the program is started, but it will be necessary anyway for the
SMTP daemon.  No other files should be kept in this directory, as ALL
files are treated as potential mail!

It will be necessary to reboot in order to pick up this setting (and the TZ
one if you needed to add it), but wait until you have completed the rest
of these instructions.

Locate the directory described by the ETC environment variable.  If you
are not sure, type the command:

     SET ETC

at a command prompt.  You need take no action, but note that this is
where the logfile (see below) is stored.

Logfile
-------

If the -zf option is used (or neither it, nor the -zs option are used),
SMTP maintains a logfile called SMTP.LOG in the \MPTN\ETC directory. 
This will grow without bound if not pruned regularly!

If the -zs option is used, then the log information is sent instead to
the SYSLOG daemon, if it is running.  Normally, this sends the output to
the file SYSLOG.MSG in the \MPTN\ETC directory, although this behaviour
can be altered by editing the file \MPTN\ETC\SYSLOG.CNF (this file
contains comments which explain what to edit).  Unfortunately,
SYSLOG.MSG is locked open by the SYSLOG daemon, so to read its contents
it is easiest to use the command sequence:

     TYPE SYSLOG.MSG > Z
     E Z                     (or use any other program to view the file Z)


The spool directory
-------------------

Outgoing mail is taken from the spool directory specified by the SMTP
environment variable.

Files must have a special (but simple) format; the message needs to be
stored "as is", but preceded by lines specifying sender and recipient(s).
This format is generated by the SMTPD server program (available
separately).

Using the program
-----------------

To connect to an SMTP server and send all pending messages in the spool
directory, simply run the program. The following command line flags
are recognised:

        -d      Specify the name of the spool directory
	-e	Send ETRN for domain (see below)
        -h      Display a brief help message
	-p	Specify password for authentication
        -s      Specify the name of the SMTP server
	-u	Specify username for authentication
        -v      Turn on verbose mode (extra advisory messages)
        -zf     Log to file (default)
	-zs	Log to SYSLOG

For example, to send all mail to the server abc.xyz.net, with verbose
mode on:

        smtp -v -sabc.xyz.net

Authentication is an extension to SMTP; omit -p and -u unless you
actually need them.  There are a number of different authentication
mechanisms in use; the program currently supports the PLAIN and LOGIN
mechanisms (see RFC 2554 for more details).  If you have a need for
support for another mechanism (and if authentication fails, the program
will tell you the mechanisms your server supports), let me know and I
will try to include it. 

The -e option is special, and generally not combined with options
involving the sending of mail.  Its purpose is to perform one specific
task; to send an ETRN command to the specified server.  This command is
used to 'kick' a server into sending queued mail for a particular
domain, and is primarily intended to initiate delivery FROM an SMTP
server elsewhere, TO a local SMTP server for a particular domain.  The
parameter following -e specifies the domain for which mail should be
de-queued.  For more details, see RFC 1985.  Here is an example, asking
the server secondary-mx.co.uk to send queued mail for the domain
ml1.org.uk:

	smtp -ssecondary-mx.co.uk -eml1.org.uk

Return codes
------------

SMTP exits with a zero status if all mail is transferred correctly;
otherwise, it exits with a nonzero status. 

Feedback
--------

SMTP was written by me, Bob Eager. I can be contacted at rde@tavi.co.uk.

Please let me know if you actually use this program.  Suggestions for
improvements are welcomed.

History
-------

1.0     Initial version.
1.1     Use new thread-safe logging module.
        Use OS/2 type definitions.
        Added -v option to display progress of mail transmission.
1.2     New, simplified network interface module.
1.3     Does not make connection at all if there are no messages
        to send.
1.4     Corrected failure to dot-stuff on sending.
1.5     Modified to use NETLIB DLL.
2.0     Added BLDLEVEL string.
        Diagnostics for occasional logfile open failures.
        Additional error checking in logging module.
        Grouped initialisation code together to improve paging performance.
3.0	Recompiled using 32-bit TCP/IP toolkit, in 16-bit mode.
3.1	Added support for ESMTP function AUTH (LOGIN, PLAIN mechanisms).
4.0	Added support for logging to 'syslog' instead of to file,
	selectable by '-z' option. This has the advantage of
	avoiding clashing logfile usage.
4.1	Fixed error in handling an EHLO response where there are
	no SMTP extensions reported.
4.2	Added -q flag for quiet operation.
4.3	Corrected exit code inversion (0 for failure!).
4.4	Added support for sending ETRN to server.
4.5	Fixed problem where multiline replies to the initial connect
	were not being handled properly.
	Fixed problem when an unsupported authorisation method could be
	mistaken as supported.

Bob Eager
rde@tavi.co.uk
December 2004
