OS/2 Shareware BBS: 35 Internet/35-Internet.zip/lampop11.zip/readme

Text File | 1993-04-08 | 16KB | 358 lines

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

                             LamPOP Version 1.1
          OS/2 LaMail POP Interface for IBM's TCP/IP

                          David Bolen - [e-mail]

                                    README

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


           Note to previous "PopMail" users - this software is now
           called LamPOP, in order to more directly associate it with
           LaMail, as well as to avoid a conflict with an already
           existing PopMail program


This file describes the contents of the LamPOP 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 LamPOP
        Sending Mail            Handling mail transmission via LamPOP
        Utilities               Some Additional Utilities
        Other Comments          Some other usage suggestions
        Reporting Problems      What procedure to follow to report problems
        Administrivia           How to contact me

There is currently no comprehensive documentation to LamPOP.  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 feel free to drop me a note and I'll do my best to see
if I can help.


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

The LamPOP archive contains the following files:

        readme          This file

        lampop.exe      The LamPOP utility (sends or receives mail)
        lampopd.exe     A debugging version (to help diagnose any problems)
        lamcheck.exe    Simple program for checking INI file contents
        lamfix.exe      Fixes LAM.INI to use LamPOP to send messages
        makendx.exe     Rebuilds a LaMail index file from a set of messages
        makendxd.exe    A debugging version of makendx


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

NOTE: LamPOP requires OS/2 version 2.0 or later, and IBM's TCP/IP v1.2.1
      or later.  I also have available versions of LamPOP that support
      OS/2 1.x and/or TCP/IP v1.1 - contact me for further information
      (see Administrivia)


Installation is very simple.  Just copy the executables into some location
that is part of your search path.  If you want, lampop.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 LamPOP 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.

There is also one other item to check.  LamPOP determines the port to connect
to the POP server on by looking up the "pop" entry in the "services" file
located in the "etc" directory (pointed to by the ETC environment variable -
generally an etc subdirectory beneath the location TCP/IP was installed in).
You need to make sure that this entry is set to port 110 (POP3) and not to
port 109 (POP2).  Just verify that you have a line like:

                pop             110/tcp         postoffice

in the services file.  If it isn't 110, edit the file (using your favorite
editor, or the system editor), and change the port number to 110.

If you do not check this entry, the typical failure will be an error during
the "USER" command, as a POP2 server does not support the USER or PASS
commands.


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

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

     lampop -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 files in.
                indexfile = Location and name of LaMail index file.
                cycletime = How often to check for new messages.  (optional)

Running "lampop -r" will tell LamPOP 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 LamPOP 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, LamPOP will exit at that point.
However, if you supply cycletime, LamPOP 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 LamPOP by using Ctrl-C/Ctrl-Break.

For example, the command:

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

would tell LamPOP to connect to the host 'home' using a userid of 'db3l',
prompting for the password for db3l just after LamPOP started.  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.

The paths given to LamPOP must already exist - LamPOP will not create any
directories.  It will, however, create the index file if necessary when the
first message is received.


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

  The easiest way to use LamPOP 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 LamPOP 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 LamPOP using:

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

LamPOP 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.  This procedure also uses LAM.INI
     settings that are (as far as I know) undocumented, and may be
     subject to change in future versions of LaMail.

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

In order to have LaMail use LamPOP 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 "lampop -s", you must supply your password, as there is no
opportunity for LamPOP 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" and "Mailer 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.

Using LamPOP this way has the same requirement on the host POP3 server
as when using LamPOP to send a message interactively - namely that the
server support the Berkeley "XMIT" extension.


+-----------+
| Utilities |
+-----------+

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

     makendx [-h (hostname)] (index_file) (message_file[s])

     where:     hostname    Optional hostname to use for messages that
                have From/To fields without nodes.
        index_file      Name of index file to create.
                message_file[s] Filenames (can use wildcards) for message
                                files to catalog in index.

The -h option should be used if you receive messages where the From: or To:
header lines give addresses consisting only of a userid, but no node.  In
this case, you should specify the hostname of your POP server following the
-h option, and it will be used to complete such addresses.


WARNING: You should use this utility cautiously, refraining from rebuilding
     existing index files wherever possible.  Some of the information
     kept in the index can not be determined solely from the message
     file, and will therefore be lost if makendx is run.  This includes
     items such as the status of messages (viewed, answered, etc..), or
     even the node of the sender or recipient of a message in some
     instances (and if the -h option is not used).


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

These represent various usage comments or suggestions for LamPOP:

      * Make sure that you configure your LaMail note options appropriately
        for your mailing address before sending mail through LamPOP.  You
        should configure your From: address to look as if you were sending
        mail from the mail host.  That address will go directly through
        LamPOP 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 LamPOP running.  So you can leave a "lampop -r" running
        permanently in the background and still start "lampop -s" whenever
        you want, manually or through LaMail, for sending mail.
      * All of the programs in this package (LamPOP included) will give
        a brief set of usage information if they are run without arguments.
      * It is quite possible to use LamPOP to receive mail, but still
        continue to use the OS/2 TCP/IP Sendmail to transmit messages.  The
    advantage to this approach is that your POP server need not support
    the XMIT extension.  You will still gain the advantage of receiving
    mail on a central host (thus not requiring your OS/2 machine to
    be active on the network and running Sendmail at all times), while
    allowing LaMail to start a copy of sendmail when necessary to
    transmit an outgoing piece of mail.


+--------------------+
| 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 LamPOP 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 LamPOP 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 (often times the problem is reproduceable), use the
        debugging version of LamPOP (lampopd.exe) to obtain debugging
        information.  Before starting it up, create an empty file called
        lampop.dbg in the same directory as lampopd.exe.  This file will
        get filled with debugging information.  Then, attempt to reproduce
        the problem.
     *  If the administrators of the central mail host are able - please
        have them log the POP session that occurs between LamPOP and the
        POP server, and include that as debugging information.

After doing this, please send me any crash information along with any
debugging information you have gathered.  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:  [e-mail]
        Advanced Network & Services, Inc.       phone:   [phone]
        100 Clearbook Road                      fax:     [phone]
        Elmsford, NY  10523

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