_
__      _| |
\ \ /\ / / |
 \ V  V /| |
  \_/\_/ |_|
  

Download: wl-1.0.tgz

===================================================
 wl -- Regular expression email whitelisting
===================================================

wl is an email "filtering" program: it reads an email 
on standard input and writes it back out on standard
output.  If certain criteria are met based upon the
headers of the email, an X-Whitelist or X-Blacklist
header will be added to the email.  Hopefully, you
can configure your mail reader (or maildrop/procmail)
to do something useful based upon the existence of
these headers.

If an error is encountered while processing your rule
sets, a X-Wl-Error header will be added to your email
with more details.

FEATURES
--------

In a nutshell, wl was created to make a whitelisting
program that is simple, effective, fast, and bug
free. 

There are lots of capable python- and perl- based
whitelisting systems; do we really need perl for this?

Given the number of emails a busy server will handle,
and the relative simplicity of this problem, loading
a perl interpreter for ever incoming email seems a bit
silly.  That's why this project exists.  :c)

More detail:

 * very fast execution speed: wl is written in ocaml, 
   so it compiles to a native executable (on ocamlopt 
   supported platforms) that runs approximately as 
   fast as C, without the worry about buffer overflows,
   memory leaks, and core dumps

 * low resource utilization: wl's only growing allocation
   is the size of the message's headers; after 
   the headers are read, and the whitelist checks are
   performed, a `cat`-like stdin to stdout happens
   with a 4k buffer and speeds approaching /bin/cat

 * powerful: match against any header, with any regular 
   expression

 * flexible: because wl only adds headers, it's
   completely up to you to decide what a match
   means.

 * simple: only two configuration files, no cli options,
   one data path (stdin -> stdout).  The codebase is
   only a few hundred lines long.  Does whitelisting
   really need more than that?

 * reliable: wl is designed to not bork on bad email.
   you can pipe any file to it, and it will 
   simply 'cat' it out if it doesn't recognize it as 
   an rfc822-compatible format.  Also, if you mess up
   a rule in your whitelist/blacklist file, the
   program will terminate normally, and your message
   will still be piped to stdout.  You'll be notifed
   of the error via the X-Wl-Error header.

REQUIREMENTS
------------

wl is written in ocaml, and is intended to be run 
as a native-code program.  

 * You need to be running some type of POSIX-compatible
   system, specifically one supported by ocamlopt
   (BSDs, Linux, many others...) 

 * You need ocaml installed (recommended 3.0 +)

   Get it here:
   http://caml.inria.fr/ocaml/distrib.html

INSTALLATION
------------

1.) Download the latest version of wl from 

    http://www.jamwt.com/wl/

2.) Unpack the tarball

    $ tar zxvf wl-<version>.tgz

3.) Change directory into the source directory

    $ cd wl-<version>

4.) Execute 'make' (if you're on *BSD, 'gmake')

    $ make

5.) Execute 'make install' as root

    $ su
    # make install

wl installs itself at /usr/local/bin/wl

CONFIGURATION
-------------

When wl is run, it tries to change directory to
~/.wl.  That's a directory called '.wl' in your
home directory.

Inside that directory it looks for two files: one 
called 'whitelist' and one called 'blacklist'.  
The format of the lines in these files is:

<header><whitespace><regular expression>

where 'header' is the name of the header 
(case-insensitive), 'whitespace' is any 
combination of spaces and tabs, and 'regular 
expression' is a standard emacs-style (think 
grep, sed, vim, etc) regular expression 
(case-insensitive).

See the some examples in the 'whitelist' and
'blacklist' files in examples/.

Please note that these are *not* perl-compatible 
regular expressions; pcre extensions won't work.
For the purposes of an email whitelist program, 
requiring pcre-ocaml is overkill.

So, if I added the following line:

from user@domain\.com

to the file ~/.wl/whitelist, any email with
"user@domain.com" in the From: header would be
flagged by wl with a

X-Whitelist: Yes (from user@domain\.com)

header added.  Similarly, if this line were in
~/.wl/blacklist, the header would be:

X-Blacklist: Yes (from user@domain\.com)

Matches always specify the corresponding 
line from the configuration file.


Note: If the directory ~/.wl does not exist, 
wl will add a X-Wl-Warning header letting you
know.  If the directory does exist, but 
either 'whitelist' or 'blacklist' do not exist,
whitelisting and/or blacklist will simply be 
skipped.  So you can whitelist without
blacklisting, and vice-versa.

USAGE
-----

Processing.  Somehow, your message needs to 
get piped to wl's standard input.  Somehow, 
the next link in the chain needs to read wl's 
standard output.  The ways to do this are 
numerous, and beyond the scope of this README.

Look in these directions:

 * procmail, maildrop, dot-qmail, getmail,
   fetchmail

Interpreting.  Your mail user agent, or 
procmail/maildrop, or something else, needs
to look for X-Whitelist and X-Blacklist 
headers, and do something about them.

Do something probably means:

 * File the mail in an appropriate directory
 * Discard the mail altogether
 * Forward the mail to someone else
 * and so on...

AUTHOR
------

wl was written by Jamie Turner <jamwt@jamwt.com>.