readme.txt 3.1  2005 0501 1409
Copyleft Copyright © 2005 John G. Derrickson  JGD@freeVEDA.org  ALL RIGHTS RESERVED

Notice Copyleft license at: http://www.freeveda.org/copyleft/
EvALUEwARE(TM) -- full-featured product offered free -- money-back guarantee before-the-fact.
Register for update notice by email (http://www.freeveda.org/buddy/register.htm).
Purchase to get the newest version (http://www.freeveda.org/buddy/purchase.htm).
Bug reports, fixes, changes are here: (http://www.freeveda.org/buddy/changes.html).
EvALUEwARE is a trademark of John G. Derrickson (http://www.freeveda.org/EvALUEwARE)
Covered by the GNU General Public License (http://www.gnu.org/copyleft/gpl.html).
Note the OSDL Linux Legal Defense Fund (http://www.osdl.org/about_osdl/legal/lldf/).
Thanks for inspiration from Paul Graham and John Rauser.

Buddy-List_Mail-O-Mat was tested using PHP 4.3.10 with CLI enabled and Apache 1.3.29.
Run "php -v" at your console to tell whether php has CLI enabled:

Files in archive (as blmom31.zip and blmom.tgz):
  addbuddy.php - add an address to a shared buddy list file
  changes.txt - bug reports, fixes, changes
  codeword.inc - set SecretCodeWord
  guide.htm - User Guide
  list.php - the main program
  popmail.php - process the mail
  pop_mail.sh - run popmail.php from cron
  readme.txt - this file
  road.php - on-the-road version of the main program
  rotate_mail.sh - rename [content,collect,dates,stdlog,stderr].txt files to _prev
  setup.php - build user files
  shared.php - build the shared buddy list file

Setup instructions:

  Copy the programs to your web page folder (e.g. ~/yourdomain.com/Buddy-List_Mail-O-Mat).
  These programs require the execute attribute: rotate_mail.sh, pop_mail.sh

  Edit [YourDomain] in rotate_mail.sh and pop_mail.sh for your system.

  Edit [YourSecretCodeWord] in codeword.inc for your system.

  Add to your crontab (remember to run "crontab [YourCrontabFile]"):
  # min hour day month weekday command-line
  51 * * * * [ProgramFolder]/pop_mail.sh
  20 0 * * 0 [ProgramFolder]/rotate_mail.sh

  Build .htaccess file in the folder that holds the web site
  or at least in the Buddy-List_Mail-O-Mat folder
  (or code into Apache configuration) like this:
    AddType x-mapp-php4 .html .htm .php3
    <FilesMatch "\.(bak|inc|log|old|sh|txt)$">
    Order Deny,Allow
    Deny from All
    </FilesMatch>

Setup for each user:

  Optionally create the [UserDomain]/[Mailbox] folder.

  Optionally copy block and/or buddy lists to the [UserDomain]/[Mailbox] folder
  named block.old and buddy.old; one address per line like "name@domain.com".

  Optionally copy the token count and/or model lists to the [UserDomain]/[Mailbox] folder
  named count.old; one token per line, each with tab mail-count and tab spam-count 
  and/or named model.old; one token per line, each with tab spam-score (0 to 99).

  The buddy version 2 block, buddy and count files meet these formats.
  However, you might prefer to start anew with a copy of only your buddy list.

  For each user, run:
    setup.php?c=[YourSecretCodeWord]&d=[UserDomain]&m=[Mailbox]&s=[SpamScore]&p=[PopOpen]
  with [parameters] changed appropriately.
  Use [YourSecretCodeWord] as changed in codeword.inc.
  Note that [PopOpen] is coded as "[PopServer],[PopUserid],[PopPassword]" where:
    [PopServer] is like: {pop.server.com:110/pop3}INBOX
    [PopUserid] is the actual mailbox name which may be different than [Mailbox].
  Note that "&s=[SpamScore]" is optional.
  Example:
    /setup.php?c=secret&d=userdomain.com&m=userid&p={pop.server.com:110/pop3}INBOX,addr,passwd
  It builds these files in the [UserDomain]/[Mailbox] folder:
    index.html - user-entry to Buddy-List_Mail-O-Mat
    road.html - user-entry to Buddy-List_Mail-O-Mat On-The-Road version
    popmail.inc - set PopServer, PopUserid, PopPassword, SpamScore

  Build .htaccess file for each user in the [UserDomain]/[Mailbox] folder
  (or use your service provider folder protection method) like this:
    AuthType Basic
    AuthName "Access for /[YourDomain]/Buddy-List_Mail-O-Mat/[UserDomain]/[Mailbox]" 
    AuthUserFile /[LocationOfPasswords]/htpasswd
    require user [PrivateUserID]

Setup for each domain:

  If you have a buddy list shared by several users in the same domain,
  copy the shared buddy list to the [UserDomain] folder
  named share.old; one address per line like "name@domain.com".
  Then, for each domain with a shared buddy list, run:
    shared.php?c=[YourSecretCodeWord]&d=[UserDomain]

  It should be noted that you can allow web site visitors and/or
  your order processing system add visitor/customer mail addresses
  to your buddy list. Full addresses only, and no wildcards.
  Here is sample PHP code:
    $drop=file('[URL]?c=[YourSecretCodeWord]&d=[UserDomain]&f='.$EmailAddress);
  Where [URL] is like http://www.yourdomain.com/Buddy-List_Mail-O-Mat/addbuddy.php

The user will access Buddy-List_Mail-O-Mat like this:
  http://[YourDomain]/Buddy-List_Mail-O-Mat/[UserDomain]/[Mailbox]/
  where:
  [YourDomain] is the domain name where Buddy-List_Mail-O-Mat is located.
  [UserDomain] is the domain name part of the user mail address name.
  [Mailbox] is the mail address name used for sending and receiving mail.
  Note: [Mailbox]@[UserDomain] should be the user's email address
  You may want to use "https" instead of "http" if you have SSL support.

File in the [UserDomain] folder:
  share.txt - list of shared addresses
Files in the [UserDomain]/[Mailbox] folder:
  block.txt - list of addresses
  buddy.txt - list of addresses
  collect.txt - collection of messages
  content.txt - list of mail, both good and evil
  count.txt - terms with counts
  dates.txt - list of first entry in content per date
  model.txt - terms with ratings
  mail.txt - samples of good mail
  spam.txt - samples of evil mail
  stderr.txt - error log
  stdlog.txt - message log
dates.txt contains for each day: date, byte position in content
content contains for each message:
  date-time|subject|from-address|to-address|rating|message-length|byte-position-in-collect