NOTE: Before upgrading from a previous version, terminate all running
scripts and then remove any files in /var/webfilt

------------------------------
1) Customize user installation
------------------------------
For personal installation:

  Copy all the scripts (.sh) somewhere under your home directory, for 
  instance '/home/username/webfilt'

  You must modify 'defines.sh' and change MYCODE, CMDFIFO and all other
  variables that are different on your system.

For system-wide (global) installation:

  Copy all the scripts (.sh) somewhere to a directory accessible to
  everyone, for instance '/usr/local/bin/webfilt'

  You must modify 'defines.sh' and change your system-specific paths 
  and binary locations, such as CMDFIFO, FILTERBIN, etc.

  Now, each user should create their own ~/.webfilt.rc to define
  MYCODE=somesecret
  BASEDIR=...


------------------------------------------------------------
2) Configure ~/.procmailrc so it calls 'storelast.sh'
   storelast.sh's parameter must be the spam state or score.
   Among the configurations in defines.sh is a decision on
   how this parameter will indicate positive spam (grep)
------------------------------------------------------------
	For each user, create a .procmailrc such as the following:

WEBFILT="/path/to/webfilt/storelast.sh"

:0
SCORE=| /usr/bin/spamprobe receive

:0wi
WFSCORE=| echo $SCORE | cut -f1 -d" "

:0 ci:
| $WEBFILT "$WFSCORE"


-------------------------------
3) Setup daily full reindexing
   This also cleans up old mail
-------------------------------

Add the following cronjob:
03 03 * * * /path/to/webfilt/genindex.sh


-----------------------------------------
4) Make directory for users' public FIFOs
   Note that you could create ~/webfilt/fifo instead, but
   you would have to make custom modifications to scripts
   and it would take some work to make this CGI-friendly.
-----------------------------------------
As root:

mkdir /var/webfilt
chgrp users /var/webfilt
chmod 1775 /var/webfilt


-----------------------------------
5) Install CGI script on web server
-----------------------------------
Copy webfilt.cgi to your web server's cgi-bin directory.

webfilt.cgi must be executable by the web server user (nobody). Note that
the script is designed to run "globally" for a site, and there is no
user-specific configuration. The only script content you may need to
modify is FIFODIR, which is by default /var/webfilt


---------------------------------
6) Configure web server for users
---------------------------------
This is where security becomes a concern. lastmail.sh (which is invoked by
procmail) will store copies of incoming mail to some directory. You may
choose to have this directory completely private (not accessible by the 
web server) in which case you can still use a web browser to read the 
local index.html file. This is safe, and works fine for local access.

Or, you may choose to have SPAMDIR and GOODDIR (from defines.sh)  
accessible by your web server. If you go that route you must configure
your web server to restrict access to the generated indexes.

	** WARNING: webfilt itself DOES NOT provide any authentication.
	** You must configure that through UNIX permissions/apache

Anyone who can read SPAMDIR and GOODDIR can read copies of your mail
stored in those directories! So you will obviously want to employ
passwords or host-based restrictions to make sure that your private mail 
doesn't get onto the Internet. If you are using Apache, look into: 
'.htaccess', and 'Allow', 'Deny', 'AuthUser' directives.

It would be a good idea to have all directories which must be accessible
by the webserver set to the webserver group, set the SGID bit on those
directories and remove all the access rights for the world at large.


--------------------------------
7) Have users launch userfilt.sh
--------------------------------
Provided procmailrc is configured correctly, incoming mail will be copied 
to the "last mail" directories indicated. However in order to allow the 
generated web pages in those directories to INTERACT with the user filter, 
you have to run a user-side script. This script communicates with the web 
CGI process via two named pipes (FIFOs) to accomplish privilege isolation.

# User can start userfilt interactively (good for debugging)
./userfilt.sh start

# The best is to run the userfilt in the background
./userfilt.sh daemon

# Stop and cleanup, or recover from premature termination
./userfilt.sh stop

After a system reboot, the user-side daemon will no longer be running. 
Because it is inconvenient to manually start userfilt.sh each time, the 
easiest solution is to change the crontab from step 3 as follows:

03 03 * * * (/path/to/webfilt/userfilt.sh stop;
             /path/to/webfilt/genindex.sh;
             /path/to/webfilt/userfilt.sh daemon) >/dev/null 2>&1

Note: this must all be on a single line.


--------------------------------
8) Generate the necessary files
--------------------------------
In order to begin using the system immediately, each user wanting to use
the system should run genindex.sh once manually. If this is not done,
(s)he will have to wait till the entered cronjob is run the next time.


=======================
SECURITY CONSIDERATIONS
=======================
The system presented here is inherently insecure IF the web server is
configured to access the directories storing mail. Depending on the
precise setup, users may be able to read other users' mail. You must
take appropriate measures to ensure that only authenticated users can
access their mail storage directories.

There is an additional security risk if the CGI scripts and user-side
daemons are enabled. The only measure that guards against one user from
playing with the mail classification of another user is the code stored
in .webfilt.rc. Make sure that file is properly guarded.

