**README** for EMAILFILTER Version 0.6

:Author:        Peter A. Donis
:Release Date:  14 December 2009

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 a user-specific port (currently the
  port number is 5590 + the user id) 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 the appropriate port, 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**: a shell script to invoke the daemon.

- **EMAILFILTERC**: a 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 either 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) or the "TCP/IP swiss army knife"
  netcat program (this is done by invoking the script with
  either the ``-n`` option, if netcat goes by the command
  name ``nc``, or the ``-t`` option if it goes by the
  command name ``netcat`` -- which name it will be depends
  on which specific flavor of Unix/Linux you are running).

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). This will install EMailFilter, and then
run each of the post-install scripts in the scripts
directory.

EMailFilter requires the PLIB Python library package,
which is available from the Python Package Index under the
name ``plib``. However, the helper module used by EMailFilter's
setup script, ``SetupHelper``, can automatically detect if
you don't have PLIB installed, and if so, it will download
and install it for you before installing EMailFilter.

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

EMailFilter is Copyright (C) 2008-2009 by Peter A. Donis.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version. (See the LICENSE file for a
copy of version 2 of the License.)

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
