  
  		BCR Mail Handler, version 3.1
  
  	      Copyright (c) 1994 Bill C. Riemers
  		  All Rights Reserved
  
-------------------------------------------------------------------------------
BCR MAIL HANDLER FEATURES:

  - Does not require root privileges.
  - Handles automatic binary and ascii file transfers.
  - Handles compressed files.
  - Handles unlimited file sizes.  (No spliting is done.)
  - Includes a generic "daemon" command that can be used for other
    applications.  (SEE README.daemon)
  - Handles automaticly forwarding of private e-mail to a file, another
    internet user, or uploading with "term".  (SEE README.term)
  - Lots of redundant code to avoid circular mailing, and machine thrashing.
  - Refuses to send the same file request twice within  a two day period.
  - Logs all errors and all outgoing mail.
  - A limited amount of access control.
  - Very easy installation for "HP-UX", "TitanOS", and "Linux"...  Other
    OS's will require a small amount of porting.
  - Does not require the user to figure out complicated things like adding
    custom header lines, or remembering complicated commands.

-------------------------------------------------------------------------------
HOW THE BCR MAIL HANDLER WORKS:

The BCR Mail Handler consists of an e-mail filter "getmail" and
the "daemon".  Modify your .forward  to use "getmail" and then
start your daemon's to process incoming mail.  (See the respective manual
pages.)  I'll add an FAQ as people raise questions.  For right now
the best thing to do is look at an example.  So here is what I use:

.forward:
"|getmail -b /opt/ftp/pub/Linux -m 200k -t"

Note: The quotes are manditory!

Look in the examples directory at the following example files:

Mail/getmail.deny
Maiil/form-letter
crontab


Also look at the other README files.

                                  Bill
  
  		BCR Mail Handler, version 3.1
  
  	      Copyright (c) 1994 Bill C. Riemers
  		  All Rights Reserved
  
---------------------------------------------------------------------

OK, this file describes the rules you should use in setting up your
directory tree of files to be forwarded.  To take a look at an
actual working example:
  ftp bohr.physics.purdue.edu
  login: anonymous
  passwd: <your e-mail address>
  cd /pub/Linux
If you want e-mail me at "bcr@physics.purdue.edu" with various test subjects
to see how the mail handler responds.


Here is a set of guidelines and instructions.
  1. In each subdirectory create a ".default" or ".default.gz" file that
     gives an index, help message, or such.

  2. All filenames should be in lowercase.  Anything in uppercase will
     not be accessable by e-mail.  Likewise any filename with a "-" will
     not be accessable.  ("-" gets converted to "/")

  3. Compressed files should use a ".z" or ".gz" extention.

  4. The BCRMailHandler is not smart enough to recognize binary
     files.  If you have any binary files, then everything should
     be transfered in binary (use the -m 0 option). 

                             Bill


  
  		BCR Mail Handler, version 3.1
  
  	      Copyright (c) 1994 Bill C. Riemers
  		  All Rights Reserved
  
----------------------------------------------------------------------

2. Q: I mailed a message with the subject "help" from my account and
      never received my file /home/info/help.  Why?

   A: "getmail" will not mail itself.  Try it from another users account
      on a different machine.  Or you can fake mail, by piping a message
      from your mailbox to your getmail command.  i.e.
         getmail -b /home/info -m 200k < $MAIL

3. Q: I mailed a message with the subject "help" from the another user's
      account on the local machine and never received a reply.  How
      do I fix this?

   A: Remove ?*@localhost and ?*@YOUR-HOSTNAME from the getmail.deny
      file.  Otherwise permission will be denied for all local users to
      queue on the same machine.

4. Q: I have the mail handler running.  Why do I still receive mail?

   A: You are suppose to receive mail.  I run the mail handler under the
      same account I receive private e-mail.  You will receive anything
      that is either a special subject (such as "bugs"), when queueing
      permission is denied, or the subject doesn't match any file names
      file name.

5. Q: Why did I receive this particular letter?  

   A: Look at the message headers with the command "less $MAIL".  Each
      letter will have the following two lines in the header:
        Received: by YOUR-HOSTNAME with getmail
        	Private REASON-GIVEN-HERE 

6. Q: Why did I receive a message without the Received: by ... with getmail
      line?

   A: This message bypassed your .forward file and went directly to your 
      mailbox.  This is possable by addressing e-mail with a leading \.
      i.e.  mailx -s test '\bcr'

7. Q: Why do I keep receiving messages with a permission denied to access the
      queue reason?

   A: Check your queue.deny file.  You probably have a regulare expression
      that is matching almost everyone.

8. Q: I suspect I'm lossing private mail, what should I do?

   A: Try listing yourself in the .forward file with a leading \.  Forexample,
      when debugging new changes I use:
        \bcr,"|/c/bcr/bin/getmail -b /opt/ftp/pub/Linux -m 200k"

9. Q: Why is the mail handler so complicated?

   A: Originally I started off with a simple 30 line script, but I found it
      was very easy to accidently introduce recursive mailings for any
      program written in a non-compiled language.  Since converting to C
      there have been constant increase in the amount of code to improve
      performance as new bugs/problems appear.  Forexample, yesterday I patched
      in Private because messages into the mail hearder.

10. Q: Why does daemon stop as soon as I start it?

    A: Daemon always stops when it doesn't have anything to do.  It will
       restart as soon as there is more work for it to do.

11. Q: Why doesn't the daemon work when I logout?

    A: You probably started daemon with the "-d" option.  When you logout
       your shell will kill it as a stopped job.  When you are done debugging,
       restart the daemon without the "-d" option, and it should survive your
       logout.

  
  		BCR Mail Handler, version 3.1
  
  	      Copyright (c) 1994 Bill C. Riemers
  		  All Rights Reserved
  
----------------------------------------------------------------------

HOWTO INSTALL THE BCR MAIL HANDLER:

  1. Edit the HOSTNAMES in the Makefile.config.

  2. Change any other paths that look inapropriate in Makefile.config.

  3. Type "make DO=install `uname`"

  4. If step 3 fails edit Makefile.ostype and retry step 3.

  5. Create a "form-letter" in your ~/Mail directory.

  6. Create ".default" files in the directory tree people will be
     requesting files from.

  7. Edit your .forward file with the getmail options you want. i.e.
      "|getmail -b /home/info/help_files -m 200k"
     NOTE: The quotes are manditory!

  8. Either create crontab entries or manually start any daemons you
     want running.  It is a good idea to restart them on a regular
     basis. i.e.
       daemon -o


  
  		BCR Mail Handler, version 3.1
  
  	      Copyright (c) 1994 Bill C. Riemers
  		  All Rights Reserved
-----------------------------------------------------------------------

This file contains information for sending and receiving mail with
"term".  If you aren't using "term", then there is no point in reading
this file.

SETTING-UP INCOMING MAIL:
  
  This is a brief summary of how to forward mail with "getmail" and
  "daemon" over term.

  SETUP 1 (as an ordinary user):

    1. Put
         "|/.../getmail -t"
       in your remote .forward file. *

    2. Put
         "|/.../getmail"
       in your local .forward file. *

    * Replace "..." with the correct path.

  ACTIVATION OF SETUP 1:
    To start the term forwarding daemon on your remote machine:
      daemon -t

  DEACTIVATION OF SETUP 1:
    To stop the term forwarding daemon on your remote machine:
      daemon -t -k


  SETUP 2 (as root on your local machine):

    1. Put
         "|/.../getmail -f YOUR-LOCAL-ADDRESS -p 4025"
       in your remote .forward file. *
       Example: "|/home/bcr/getmail -f bcr -p 4025"

    2. Put:
---> CUT HERE <---
smtp	stream  tcp     nowait  root    /usr/sbin/tcpd	/usr/bin/rsmtp	-bs
---> CUT HERE <---
       in your local /etc/inetd.conf (if it is not already there.

  ACTIVATION OF SETUP 2:
    To start the term forwarding daemon on your remote machine:
      tredir 4025 25
      daemon -f LOCAL-EMAIL-ADDRESS -p 4025

  DEACTIVATION OF SETUP 2:
    To stop the term forwarding daemon on your remote machine:
      daemon -t -k

  PROBLEMS:
    1. Race conditions still have occassional problems.
    2. All e-mail goes to one user...


SETTING-UP OUTGOING MAIL:

  This requires you have installed tcpip, loopback, and smail.

  SETUP:

    1. Append the following line to your local /etc/services file.
termsmtp	4025/tcp	mail

    2. Append the following to /usr/lib/smail/transports

--> CUT HERE <--
#------------------------------------------------------------------------------
# Transport using an smtp port redirected with term.
#
smartterm:
	driver = tcpsmtp,		# We use tcpsmtp for service
	-received,			# termmail puts in a received line
	error_transport=termmail,	# when there is an error use termmail
	remove_header = from,		# we correct the from: line
	append_header = "From: \"$sender_name\" <$sender>";
	service = "${if def:sender_proto:${if eq{sender_proto}{termsmtp}:termsmtp}}"
#------------------------------------------------------------------------------
# This changes the from line, and either queues or delivers the message
#
termmail:
        driver = pipe;                  # send the message to a pipe
	cmd="/usr/lib/smail/termsmartmail \"$sender_name\"",
                                        # use termsmartmail
        user=root,                      # execute getmail as "root"
        group=mail,                     # execute getmail as "mail"
        parent_env,                     # environment info from parent addr
        -pipe_as_user,                  # don't use user-id associated w. addr
        umask = 0007,                   # umask for child process
#------------------------------------------------------------------------------
--> CUT HERE <--

    4. Replace /usr/lib/smail/routers with the following:

--> CUT HERE <--
smart_host:
	driver=smarthost,		# special-case driver
	transport=smartterm;		# smart delivery of mail with term
--> CUT HERE <--
  
    5. Replace /usr/lib/smail/config with the following:

--> CUT HERE <--
visible_domain=via.term.none
smtp_accept_max=10
smtp_banner="$primary_name Linux Smail$version #$compile_num ready at $date"
postmaster=root
smart_path=localhost
received_field="Received: \ 
	${if def:sender_host \ 
		{from $sender_host by $primary_name \ 
		${if def:sender_proto: with $sender_proto}\ 
		\n\t(Linux Smail$version #$compile_num) }\ 
	else{by $primary_name ${if def:sender_proto:with $sender_proto }\ 
		(Linux Smail$version #$compile_num)\n\t}}\ 
	id $message_id; $spool_date" 
smart_user = $user@YOUR-REMOTE-HOSTNAME
--> CUT HERE <--

    6. Copy the example script "termsmartmail" to /usr/lib/smail/. on your 
       local machine.

    7. Each user may set there own internet reply address with the command
       "echo alias from REMOTE-EMAIL-ADDRESS > ~/.mailrc".  So if each user
       has an account on another machine, they can forward to there own account
       over a shared term connection.

  ACTIVATION:
    tredir 4025 25  (After establishing your term connection.)
    runq            (To deliver queued mail.)

  PROBLEMS:
    1. I haven't done much testing with this new method.
    2. You must not do something like /usr/lib/sendmail -q10m as
       this will cause problems with locked files.

OK, 3.10 is probably the first stable release, so I'll start from here.

3.10 --> 3.11

- Changed "parseheaders" to accept From: line information.  Also I
  added a check incase the From:, Return-Path:, or Reply-To:
  strips the domainname.  (This type of error was the primary reason
  I was previously ignoring the From: line.)
- It seems this sanity check is not sufficient, so I changed it back.
  Oh well at least the code is alittle cleaner now.
- Changed the version number in the copyright notices.
- Added a check for both "from" and "reply" addresses rather than just
  "from" address.  So now I don't autoreply to everyone on the same 
  linux-activists channel.
- It seems that "/bin/sh -c" doesn't work right under HP-UX, so I changed
  the HP-UX default to "/bin/ksh".
- Fixed mailme to correctly add extra lines. 

3.11 --> 3.12

- Created README.term
- Added a check of "To: ", "Cc: ", "Bcc: ", and "Appearently-To: " lines
  to check mail forwarded via a mailing list, not actually intended for
  the mail handler.  (This was needed so I could subscribe to the "wt"
  mailing list.)
- Added in support for "regex.h" instead of "regexp.h" to improve Posix
  compatability.  To still use "regexp.h", USE_STEP needs to be defined
  in config.h.  (As is done for TitanOS.)
- Moved To and From field defs into the config.h file.

3.12 --> 3.13

- I discovered some mailers think ?*! is a valid way to start an e-mail
  address.  So I added this format to the "usercmp" routine.
- Added in quoting of the replyto address with <>'s.
- Added "incoming" keywords.
- Added support for quotes in the from and replyto addresses.
- Switched from "mailx" to "/usr/lib/sendmail".  Set the precedence to "bulk".
- Modified termforward() to accept a forward address for the remote machine.
  The receiver should put "|getmail" in thier .forward file.
- Modified getmail to work for local users by editing the getmail.deny file.
- Added Private because information to the message headers.
- Renamed "getmail.deny" and "getmail.allow" to "queue.allow" and "queue.deny".
- Finially started an FAQ.
- Heavily revised the README.term file with a new method of outgoing mail
  I just figured out.  Outgoing mail can will automatically be queued if 
  term is not running!  (There is no need for uucp.)
- I split "Makefile" up into multiple files, so normally users should only
  need to edit "Makefile.config".
- Added the config options USE_TERM and USE_QUEUE, so users can build smaller
  binaries.
- Changed all the copyright notices.

3.13 -> 3.14
- I discovered a bug with "rindex()" under __hpux.  so I've added my own rindex
  function for this platform.  Rindex()
- I now use smtp commands for forwarding.  This means that getmail isn't needed
  on the receiving network machine, and I don't need to worry about HOP count
  problems anymore.
- I've added a "-p" option to specify the socket.  So term forwarding can be 
  done with tredir.
- renamed "receive" to "forward"
Changes needed for 3.20
 - More testing
 - Convert "termsmartmail" to C.
