README for EMAILFILTER Version 0.2
Author: Peter A. Donis
Release Date: 10 February 2008

The EMailFilter Program
=======================

EMailFilter is a customizable e-mail content filter
written in Python. It consists of the following
Python modules and shell scripts:

EMAILFILTER.PY -- the core filter logic; it allows
you to add as many Python filtering modules as you
want, and will give each filtering module a chance
to examine each e-mail message and (possibly) add
'X-' headers to record its findings.

EMAILFILTERD.PY -- the preferred mode of operation
for EMailFilter; it wraps EMAILFILTER.PY in a daemon
that listens on port 5590 and processes each e-mail
message sent to it through that port.

EMAILFILTERC.PY -- a command-line client program that
takes its standard input, sends it through a socket
to the daemon on port 5590, receives the processed
data back, and writes it to standard output. This
is *not* the preferred method of talking to the daemon;
see the EMAILFILTERC shell script below.

EMAILFILTERDEFS.PY -- common definitions for all
the above modules.

EMAILFILTERD -- shell script to invoke the daemon.

EMAILFILTERC -- shell script to invoke the client; it
can use EMAILFILTERC.PY above if necessary, but this
is slow because it requires a new instance of the Python
interpreter to be loaded for each e-mail message (the
message comes in on standard input and the processed
message is written to standard output). The preferred
method is to use the CFilter program (available on
SourceForge, see http://cfilter.sourceforge.net) as
the client; this is done by invoking this script with
the -c option.

Most e-mail clients can be set up to invoke any
desired filter program, sending it messages on standard
input and receiving processed messages on standard output;
thus, to use EMailFilter, simply tell your e-mail client
to invoke "emailfilterc -c" as the filter program (you
can leave out the -c, but as above, filtering will be
significantly slower).

Installation
------------

To install EMailFilter, you can simply run

$ python setup.py install

at a shell prompt from the directory into which you
unzipped the source tarball (the same directory that this
README file is in). However, since there are some
post-install scripts that should be run to fully set up
EMailFilter, a shell script is also provided; just run

$ install-all

at a shell prompt in the source directory. After running
the setup.py installation scripts, this shell script
runs each of the post-install scripts in the scripts
directory.

Copyright and License
=====================

EMailFilter is Copyright (C) 2008 by Peter A. Donis. It is
released under the GNU General Public License (GPL), Version 2
(but at your option, you may release your own modifications to
EMailFilter under any later GPL version). See the LICENSE file
for a copy of the license.
