home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / popmail1.zip / readme < prev   
Text File  |  1993-02-08  |  13KB  |  299 lines
  1. ------------------------------------------------------------------------------
  2.  
  3.                  PopMail Version 1.0
  4.          OS/2 2.0 LaMail POP Interface for IBM TCP/IP v1.2.1
  5.  
  6.               David Bolen - db3l@ans.net
  7.  
  8.                     README
  9.  
  10. ------------------------------------------------------------------------------
  11.  
  12.  
  13. This file describes the contents of the POPMAIL.ZOO archive, and presents a
  14. brief description of how to get everything up and running.
  15.  
  16. This file contains the following sections:
  17.  
  18.     Archive Contents    Description of the contents of the archive
  19.     Installation        Basic Installation Instructions
  20.     Receiving Mail        Enabling mail receipt via PopMail
  21.     Sending Mail        Handling mail transmission via PopMail
  22.     Utilities        Some Additional Utilities
  23.     Other Comments        Some other usage suggestions
  24.     Reporting Problems    What procedure to follow to report problems
  25.     Administrivia        E-Mail addresses
  26.  
  27. There is currently no comprehensive documentation to PopMail.  It was a short
  28. project of mine for people in my office, and is being made available on an
  29. AS-IS basis.  If you are unable to get anything working using the information
  30. in this readme, please drop me a note.
  31.  
  32.  
  33. +------------------+
  34. | Archive Contents |
  35. +------------------+
  36.  
  37. The POPMAIL.ZOO archive contains the following files:
  38.  
  39.     readme        This file
  40.  
  41.     popmail.exe    The PopMail utility (sends or receives mail)
  42.     popmaild.exe    A version of the utility for generating debug info
  43.     lamcheck.exe    Simple program for checking INI file contents
  44.     lamfix.exe    Fixes LAM.INI to use PopMail to send messages
  45.     makendx.exe    Rebuilds a LaMail index file from a set of messages
  46.  
  47.  
  48. +--------------+
  49. | Installation |
  50. +--------------+
  51.  
  52. Installation is very simple.  Just copy the executables into some location
  53. that is part of your search path.  If you want, popmail.exe is really the
  54. only executable that must be in a directory in your path, and only if you
  55. will be using it to send mail.  Otherwise, you can just switch to whatever
  56. directory you load the files in to run them, or specify their full path
  57. location when running them from somewhere else.
  58.  
  59. In order for PopMail to work, you will have to have a userid on the central
  60. host that is to receive your mail, and that host must be running a POP3
  61. server.  Your mail should be sent and received by that host.
  62.  
  63.  
  64. +----------------+
  65. | Receiving Mail |
  66. +----------------+
  67.  
  68. To receive mail from a central host, start popmail using:
  69.  
  70.      popmail -r (host) (user) (password) (maildir) (indexfile) [cycletime]
  71.  
  72.      where:    host      = Hostname of the mail host with POP3 server.
  73.         user      = Your username on the mail host.
  74.         password  = Your password on the mail host.  Use * in order
  75.                 to be prompted for a password.
  76.         maildir   = Directory to store message file in.
  77.         indexfile = Location and name of LaMail index file.
  78.         cycletime = How often to check for new messages.  (optional)
  79.  
  80. Running "popmail -r" will tell PopMail to connect to the mail host and see if
  81. you have new messages.  If you used an asterix (*) for a password, you will
  82. first be prompted for a password, and then PopMail will connect to the host.
  83. If any new messages are detected, they will be fetched from the host and
  84. stored in the indicated directory, with an index entry for each message added
  85. to the specified index file.
  86.  
  87. If you don't specify a cycletime parameter, PopMail will exit at that point.
  88. However, if you supply cycletime, PopMail will continue to run, reconnecting
  89. to the mail host every 'cycletime' seconds to see if you have new mail.  In
  90. this case, you can stop PopMail by using Ctrl-C/Ctrl-Break.
  91.  
  92. For example, the command:
  93.  
  94.     popmail -r home db3l * c:\tcpip\mail c:\tcpip\mail\inbox.ndx 60
  95.  
  96. would tell PopMail to connect to the host 'home' using a userid of 'db3l' and
  97. a password that it prompted for right after it began running.  Any new
  98. messages would be stored in the c:\tcpip\mail directory, and the index file
  99. c:\tcpip\mail\inbox.ndx updated with an appropriate index entry.
  100.  
  101. In this case, if LaMail is configured to store the "In Basket" in the
  102. c:\tcpip\mail directory, all new messages would be automatically detected by
  103. LaMail.
  104.  
  105. One item of note - for the LaMail "In Basket", the inbox.ndx file is kept in
  106. the same directory as the rest of the messages.  For all other folders, the
  107. index file is one directory above the messages and the messages are in a
  108. sub-directory of the folder name.  For example if the folder "foo" was also
  109. in c:\tcpip\mail, the index "foo.ndx" would be in c:\tcpip\mail, and foo's
  110. messages would be in the directory c:\tcpip\mail\foo.
  111.  
  112.  
  113. Usage Hint
  114. ----------
  115.  
  116.   The easiest way to use PopMail for continuously receiving mail is to set
  117.   it up in the same startup file that starts all your other TCP/IP daemons 
  118.   and configures the system.  Just issue a "start" command for PopMail with 
  119.   the appropriate options, including a reasonable cycle time such as 60 or 
  120.   120 seconds.  If you use a * for a password, you'll have to enter your mail
  121.   host password once when the system starts up, but then you can leave it 
  122.   running.
  123.  
  124.  
  125. +--------------+
  126. | Sending Mail |
  127. +--------------+
  128.  
  129. To send mail through a central host, start popmail using:
  130.  
  131.      popmail -s (host) (user) (password)
  132.  
  133.      where:    host      = Hostname of the mail host with POP3 server.
  134.         user      = Your username on the mail host.
  135.         password  = Your password on the mail host.  Use * in order
  136.                 to be prompted for a password.
  137.  
  138. PopMail will then continue reading from standard input for the text of the
  139. message.  This message will be sent through the POP3 server using the
  140. Berkeley "XTND XMIT" command.  This extension must be supported by your
  141. server in order to be able to send mail.  The text of the message itself must
  142. be standard RFC822, and must contain the source and destination addresses for
  143. delivery - the POP3 server will just pass the text on to sendmail.
  144.  
  145.  
  146. Integrating Into LaMail
  147. -----------------------
  148.  
  149. WARNING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - WARNING
  150.  
  151.      The procedure described in this section results in a plain
  152.      ASCII version of the password for your mail host userid being
  153.      placed in the LAM.INI setup file.  Although LAM.INI itself is
  154.      a binary OS/2 INI file, this does represent a security exposure
  155.      that you have to consider.
  156.  
  157. WARNING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - WARNING
  158.  
  159. In order to have LaMail use PopMail to send messages instead of sendmail,
  160. you need to run the "lamfix" utility to adjust the LAM.INI file used by
  161. LaMail to hold setup information.  The syntax is:
  162.  
  163.      lamfix (ini_location) (host) (user) (password)
  164.  
  165.      where:  ini_location = Full path to LAM.INI (ie: c:\os2\lam.ini)
  166.          host         = Hostname of the mail host with POP3 server.
  167.          user         = Your username on the mail host.
  168.          password     = Your password on the mail host.
  169.  
  170. Unlike using "popmail -s", you must supply your password, as there is no
  171. opportunity for popmail to ask you to enter it when it is run from within
  172. LaMail.
  173.  
  174. You must not be running LaMail when you run lamfix, as LaMail will prevent
  175. lamfix from updating LAM.INI.
  176.  
  177. You can verify that lamfix worked using lamcheck, as:
  178.  
  179.      lamcheck (ini_location)
  180.  
  181. This must also be run when LaMail is not running, and will produce output
  182. of the form:
  183.  
  184.      Application: LAM
  185.       Key = AUTOSPATH
  186.       Key = CfgDir
  187.       (..many keys..)
  188.       Key = Mailer Name
  189.       Key = Mailer Options
  190.  
  191. The existence of the last two (Mailer Name/Options) entries signify that
  192. lamfix correctly updated the file.  To verify the contents you can run
  193. lamcheck with an additional command line option (it doesn't matter what it
  194. is), which will also dump the values of the keys, which should be the same
  195. arguments you originally gave to lamfix.
  196.  
  197.  
  198. +----------+
  199. | Utilites |
  200. +----------+
  201.  
  202. In the event that various message files get created without appropriate index
  203. entries being made, or if indices are lost while experimenting with PopMail,
  204. the makendx utility can be used to recreate a valid LaMail index file for a
  205. set of message files.  The syntax is:
  206.  
  207.      makendx (index_file) (message_file[s])
  208.  
  209.      where:    index_file    Name of index file to create
  210.         message_file[s]    Filenames (can use wildcards) for message
  211.                 files to catalog in index.
  212.  
  213. Note that you shouldn't use this utility to rebuild existing index files if
  214. you can help it because some information stored in the index can not be
  215. determined solely from the message file.  This includes items such as whether
  216. a message has been viewed or answered, or even the node of the sender in some
  217. instances.
  218.  
  219.  
  220. +----------------+
  221. | Other Comments |
  222. +----------------+
  223.  
  224. These represent some arbitrary usage comments or suggestions for PopMail:
  225.  
  226.       *    Make sure that you configure your LaMail note options appropriately
  227.     for your mailing address before sending mail through PopMail.  You
  228.     should configure your From: address to look as if you were sending
  229.     mail from the mail host.  That address will go directly through
  230.     PopMail into sendmail on that host where it will appear in the
  231.     final message.
  232.       *    If you have access to your site administrator responsible for the
  233.         POP3 daemon, and they are using the Berkeley "popper" code on a
  234.     Unix platform, they may want to fix what I consider a bug in the
  235.     XMIT extension.  Since XMIT passes all mail on to sendmail, and
  236.     since sendmail sends bounce messages for bad addresses, XMIT should
  237.     not return a failing POP code for a message that just has some
  238.     bad addresses in it.  The fix it to have the XMIT extension check
  239.     for an EX_NOUSER return from sendmail and still return a successful
  240.     POP code.  If anyone is interested, I can supply particulars as to
  241.     what code to fix (and what lines, if you have popper 1.83beta).
  242.       * In case anyone wonders, there is no restriction on having multiple
  243.         copies of PopMail running.  So you can leave a "popmail -r" running
  244.     permanently in the background and still start "popmail -s" whenever
  245.     you want, manually or through LaMail, for sending mail.
  246.       * All of the programs in this package (PopMail included) will give
  247.         a brief set of usage information if they are run without arguments.
  248.  
  249.  
  250. +--------------------+
  251. | Reporting Problems |
  252. +--------------------+
  253.  
  254. This code is supplied on an AS-IS basis, and I place no specific guarantees
  255. as to my support of any problems.  However, I do have users at my company
  256. that use this code, and it is likely that I will address any specific
  257. difficulties that are reported to me.
  258.  
  259. Since PopMail involves a central host at your site that runs a Pop Server,
  260. please first check with any local site support people to make sure that the
  261. problem you are experiencing is not due to something on your central host.  I
  262. can only address problems that are part of the PopMail code, or caused
  263. because of that code.
  264.  
  265. With that in mind, should anyone encounter problems, I'd appreciate the
  266. following being done whenever possible in order to best help me narrow down
  267. any problems.
  268.  
  269.      *    Record whatever information you can as to the circumstances
  270.     surrounding the crash, and any dump information.  If possible,
  271.     please see if the problem is reproduceable.
  272.      *  If possible, use the supplied popmaild.exe executable in lieu of
  273.         popmail.exe.  Before starting it up, create an empty file called
  274.     popmail.dbg in the same directory as popmaild.exe.  This file will
  275.     get filled with debugging information.  Then - please try to 
  276.     reproduce the problem with popmaild.
  277.      *  If the administrators of the central mail host are able - please
  278.         have them log the POP session with the popmail client, and include
  279.     that as debugging information.
  280.  
  281. After doing this, please send me as much information about the crash and the
  282. resulting debug information as you can.  Please be as verbose as you can
  283. about the environment in which you are running.  I may not need most of the
  284. information, but I may not automatically know up front what I do need.
  285.  
  286.  
  287. +---------------+
  288. | Administrivia |
  289. +---------------+
  290.  
  291. Just to keep this in one place - I can be reached via the following:
  292.  
  293.     David Bolen                e-mail:  db3l@ans.net
  294.     Advanced Network & Services, Inc.    phone:   +1 914 789-5327
  295.     100 Clearbook Road            fax:     +1 914 789-5310
  296.     Elmsford, NY  10523
  297.  
  298. E-mail is much preferred over any other contact method.
  299.