------------------------------------------------------------------------------

			     PopMail Version 1.0
	     OS/2 2.0 LaMail POP Interface for IBM TCP/IP v1.2.1

			  David Bolen - db3l@ans.net

				    README

------------------------------------------------------------------------------


This file describes the contents of the POPMAIL.ZOO archive, and presents a
brief description of how to get everything up and running.

This file contains the following sections:

	Archive Contents	Description of the contents of the archive
	Installation		Basic Installation Instructions
	Receiving Mail		Enabling mail receipt via PopMail
	Sending Mail		Handling mail transmission via PopMail
	Utilities		Some Additional Utilities
	Other Comments		Some other usage suggestions
	Reporting Problems	What procedure to follow to report problems
	Administrivia		E-Mail addresses

There is currently no comprehensive documentation to PopMail.  It was a short
project of mine for people in my office, and is being made available on an
AS-IS basis.  If you are unable to get anything working using the information
in this readme, please drop me a note.


+------------------+
| Archive Contents |
+------------------+

The POPMAIL.ZOO archive contains the following files:

	readme		This file

	popmail.exe	The PopMail utility (sends or receives mail)
	popmaild.exe	A version of the utility for generating debug info
	lamcheck.exe	Simple program for checking INI file contents
	lamfix.exe	Fixes LAM.INI to use PopMail to send messages
	makendx.exe	Rebuilds a LaMail index file from a set of messages


+--------------+
| Installation |
+--------------+

Installation is very simple.  Just copy the executables into some location
that is part of your search path.  If you want, popmail.exe is really the
only executable that must be in a directory in your path, and only if you
will be using it to send mail.  Otherwise, you can just switch to whatever
directory you load the files in to run them, or specify their full path
location when running them from somewhere else.

In order for PopMail to work, you will have to have a userid on the central
host that is to receive your mail, and that host must be running a POP3
server.  Your mail should be sent and received by that host.


+----------------+
| Receiving Mail |
+----------------+

To receive mail from a central host, start popmail using:

     popmail -r (host) (user) (password) (maildir) (indexfile) [cycletime]

     where:	host      = Hostname of the mail host with POP3 server.
		user      = Your username on the mail host.
		password  = Your password on the mail host.  Use * in order
			    to be prompted for a password.
		maildir   = Directory to store message file in.
		indexfile = Location and name of LaMail index file.
		cycletime = How often to check for new messages.  (optional)

Running "popmail -r" will tell PopMail to connect to the mail host and see if
you have new messages.  If you used an asterix (*) for a password, you will
first be prompted for a password, and then PopMail will connect to the host.
If any new messages are detected, they will be fetched from the host and
stored in the indicated directory, with an index entry for each message added
to the specified index file.

If you don't specify a cycletime parameter, PopMail will exit at that point.
However, if you supply cycletime, PopMail will continue to run, reconnecting
to the mail host every 'cycletime' seconds to see if you have new mail.  In
this case, you can stop PopMail by using Ctrl-C/Ctrl-Break.

For example, the command:

	popmail -r home db3l * c:\tcpip\mail c:\tcpip\mail\inbox.ndx 60

would tell PopMail to connect to the host 'home' using a userid of 'db3l' and
a password that it prompted for right after it began running.  Any new
messages would be stored in the c:\tcpip\mail directory, and the index file
c:\tcpip\mail\inbox.ndx updated with an appropriate index entry.

In this case, if LaMail is configured to store the "In Basket" in the
c:\tcpip\mail directory, all new messages would be automatically detected by
LaMail.

One item of note - for the LaMail "In Basket", the inbox.ndx file is kept in
the same directory as the rest of the messages.  For all other folders, the
index file is one directory above the messages and the messages are in a
sub-directory of the folder name.  For example if the folder "foo" was also
in c:\tcpip\mail, the index "foo.ndx" would be in c:\tcpip\mail, and foo's
messages would be in the directory c:\tcpip\mail\foo.


Usage Hint
----------

  The easiest way to use PopMail for continuously receiving mail is to set
  it up in the same startup file that starts all your other TCP/IP daemons 
  and configures the system.  Just issue a "start" command for PopMail with 
  the appropriate options, including a reasonable cycle time such as 60 or 
  120 seconds.  If you use a * for a password, you'll have to enter your mail
  host password once when the system starts up, but then you can leave it 
  running.


+--------------+
| Sending Mail |
+--------------+

To send mail through a central host, start popmail using:

     popmail -s (host) (user) (password)

     where:	host      = Hostname of the mail host with POP3 server.
		user      = Your username on the mail host.
		password  = Your password on the mail host.  Use * in order
			    to be prompted for a password.

PopMail will then continue reading from standard input for the text of the
message.  This message will be sent through the POP3 server using the
Berkeley "XTND XMIT" command.  This extension must be supported by your
server in order to be able to send mail.  The text of the message itself must
be standard RFC822, and must contain the source and destination addresses for
delivery - the POP3 server will just pass the text on to sendmail.


Integrating Into LaMail
-----------------------

WARNING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - WARNING

     The procedure described in this section results in a plain
     ASCII version of the password for your mail host userid being
     placed in the LAM.INI setup file.  Although LAM.INI itself is
     a binary OS/2 INI file, this does represent a security exposure
     that you have to consider.

WARNING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - WARNING

In order to have LaMail use PopMail to send messages instead of sendmail,
you need to run the "lamfix" utility to adjust the LAM.INI file used by
LaMail to hold setup information.  The syntax is:

     lamfix (ini_location) (host) (user) (password)

     where:  ini_location = Full path to LAM.INI (ie: c:\os2\lam.ini)
	     host         = Hostname of the mail host with POP3 server.
	     user         = Your username on the mail host.
	     password     = Your password on the mail host.

Unlike using "popmail -s", you must supply your password, as there is no
opportunity for popmail to ask you to enter it when it is run from within
LaMail.

You must not be running LaMail when you run lamfix, as LaMail will prevent
lamfix from updating LAM.INI.

You can verify that lamfix worked using lamcheck, as:

     lamcheck (ini_location)

This must also be run when LaMail is not running, and will produce output
of the form:

     Application: LAM
	  Key = AUTOSPATH
	  Key = CfgDir
	  (..many keys..)
	  Key = Mailer Name
	  Key = Mailer Options

The existence of the last two (Mailer Name/Options) entries signify that
lamfix correctly updated the file.  To verify the contents you can run
lamcheck with an additional command line option (it doesn't matter what it
is), which will also dump the values of the keys, which should be the same
arguments you originally gave to lamfix.


+----------+
| Utilites |
+----------+

In the event that various message files get created without appropriate index
entries being made, or if indices are lost while experimenting with PopMail,
the makendx utility can be used to recreate a valid LaMail index file for a
set of message files.  The syntax is:

     makendx (index_file) (message_file[s])

     where:	index_file	Name of index file to create
		message_file[s]	Filenames (can use wildcards) for message
				files to catalog in index.

Note that you shouldn't use this utility to rebuild existing index files if
you can help it because some information stored in the index can not be
determined solely from the message file.  This includes items such as whether
a message has been viewed or answered, or even the node of the sender in some
instances.


+----------------+
| Other Comments |
+----------------+

These represent some arbitrary usage comments or suggestions for PopMail:

      *	Make sure that you configure your LaMail note options appropriately
	for your mailing address before sending mail through PopMail.  You
	should configure your From: address to look as if you were sending
	mail from the mail host.  That address will go directly through
	PopMail into sendmail on that host where it will appear in the
	final message.
      *	If you have access to your site administrator responsible for the
        POP3 daemon, and they are using the Berkeley "popper" code on a
	Unix platform, they may want to fix what I consider a bug in the
	XMIT extension.  Since XMIT passes all mail on to sendmail, and
	since sendmail sends bounce messages for bad addresses, XMIT should
	not return a failing POP code for a message that just has some
	bad addresses in it.  The fix it to have the XMIT extension check
	for an EX_NOUSER return from sendmail and still return a successful
	POP code.  If anyone is interested, I can supply particulars as to
	what code to fix (and what lines, if you have popper 1.83beta).
      * In case anyone wonders, there is no restriction on having multiple
        copies of PopMail running.  So you can leave a "popmail -r" running
	permanently in the background and still start "popmail -s" whenever
	you want, manually or through LaMail, for sending mail.
      * All of the programs in this package (PopMail included) will give
        a brief set of usage information if they are run without arguments.


+--------------------+
| Reporting Problems |
+--------------------+

This code is supplied on an AS-IS basis, and I place no specific guarantees
as to my support of any problems.  However, I do have users at my company
that use this code, and it is likely that I will address any specific
difficulties that are reported to me.

Since PopMail involves a central host at your site that runs a Pop Server,
please first check with any local site support people to make sure that the
problem you are experiencing is not due to something on your central host.  I
can only address problems that are part of the PopMail code, or caused
because of that code.

With that in mind, should anyone encounter problems, I'd appreciate the
following being done whenever possible in order to best help me narrow down
any problems.

     *	Record whatever information you can as to the circumstances
	surrounding the crash, and any dump information.  If possible,
	please see if the problem is reproduceable.
     *  If possible, use the supplied popmaild.exe executable in lieu of
        popmail.exe.  Before starting it up, create an empty file called
	popmail.dbg in the same directory as popmaild.exe.  This file will
	get filled with debugging information.  Then - please try to 
	reproduce the problem with popmaild.
     *  If the administrators of the central mail host are able - please
        have them log the POP session with the popmail client, and include
	that as debugging information.

After doing this, please send me as much information about the crash and the
resulting debug information as you can.  Please be as verbose as you can
about the environment in which you are running.  I may not need most of the
information, but I may not automatically know up front what I do need.


+---------------+
| Administrivia |
+---------------+

Just to keep this in one place - I can be reached via the following:

	David Bolen				e-mail:  db3l@ans.net
	Advanced Network & Services, Inc.	phone:   +1 914 789-5327
	100 Clearbook Road			fax:     +1 914 789-5310
	Elmsford, NY  10523

E-mail is much preferred over any other contact method.
