_
__ _| |
\ \ /\ / / |
\ 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>.