Readme file for qq-rbl.pl
-------------------------

LICENSE
=======

This package is licensed - as you may have expected - under the GPL (GNU
Public License). A copy of this license is included here.

You may modify this script to (hopefully) fit your needs, and I would be
glad if you drop me a line (see bottom of this README file) what you have
improved and how you did the trick.


WHAT IS qq-rbl?
===============

qq-rbl.pl is a little perl script for use with the qmail MTA (www.qmail.org,
cr.yp.to/qmail.html) and the perl interpreter.


WHO SHOULD USE IT?
==================

Almost everyone to prevent spam flooding in his mailbox. But this script is
intended especially for people who get lots of spam each day.


PREREQUISITES
=============

- qmail 1.03 with the QMAILQUEUE patch (find this file included in this
  package)

- Perl 5.005.03 or newer (older versions may work, but not tested)

- The modules Mail::RBL, Net::DNS, Time::localtime (the latter usually
  comes with perl, the others are available at CPAN, ftp.cpan.org)


HOW IT WORKS
============

This script is wedged between qmail-queue and qmail-smtpd, so all messages
crossing the mail system are passed to it and can be checked.

If you have this installed and qmail delivers some mail to you, this script
is invoked, extracts the message header and checks for some spam-typical
properties.

1) Is one of the IP addresses in the mail header listed on a RBL-DNS-list
   (= real time blacklisting, see www.osirusoft.com or www.orbz.org)?

2) Can sender-address and return path of the mail be reverse-looked-up
   via DNS (exists a MX or at least an A entry for that host)?

3) Are there strings like "unknown" or "unverified" in the
   "Received:"-Headers?

4) Contain(s) one or more of the From:/Sender:/Subject:/Received: - headers
   at least one word from the word blacklist (a good example list is
   shipped with this package)?

5) Has at least one of the passed MTA's added warning-lines, such as
   "X-Authentication-Warning:" or "X-Date-warning:"?

6) Are there special headers which are typical for spam mails (X-PMFLAGS and
   so on)?

7) Are the most important and RFC-compliant headers
   (To/From/Subject/Date/Message-ID) included in the message header?

8) Is the subject suspicious (dollar signs, lots of uppercase letters
   following each other)?

If one or more of these criterias was matched, an appropriate
"X-Spam-Warning: ..." header is added to the message so it looks forward to
being filtered on the procmail level.

You could then set up a .procmailrc like this:

:0
* ^X-Spam-Warning:.*
/dev/null

If you want your messages to be kept in a special folder (which I suggest),
you have to replace "/dev/null" with a file name and add a ":" on the end of
the first line (after the zero sign).


EFFECTIVITY
===========

Because of the different filtering methods explained above, this script
works very effective. It's false-negative rate is very, very slow, the
false-positive rate - thank God - is, too.

Though you shouldn't decide to send all filtered messages to /dev/null
because I decline to be responsible for important mails to be deleted by
this script. You better set up a special folder where suspicious messages
are placed in and which is checked less often than your default mail folder.

So you don't get annoyed any more by User-Agent-windows full of spam subject
lines.


INSTALLATION
============

As mentioned above, you will need your qmail be patched with the QMAILQUEUE
patch written by Bruce Guenter. This patch is included in this package.

After that, you have to set up the environment variable "QMAILQUEUE". Its
value must be the path to our perl script, qq-rbl.pl.

That means, qq-rbl.pl is used as alternative qmail queue and passes the
message along to the "real", old qmail queue included in the qmail package
after its spam checking is finished.

To get this script to run, you additionally need the perl modules listed
above. You set them up like any other perl module:

	% tar xvzf module-package.tar.gz
	% cd module-package
	% perl Makefile.PL
	% make
	% make install

If you use perl 5.005, you probably have to change the file RBL.pm a little
bit by removing the "require" line and change the "our" in the "VERSION"
line to "my". Remove the "use warnings" line, too. Then it looks like this:

--8<--
#require 5.005_62;
use strict;
use Carp;

my $VERSION = '1.00';
--8<--

I recommend to copy our script, qq-rbl.pl, to the qmail binary folder
(usually /var/qmail/bin).

You have to customize some settings within the script, so open it with an
editor (like vi or joe) and set these values like you want them (important:
you have to set up the path to your word-blacklist!)

This script supports logging to a file. You can disable this feature by
setting $logging to 0 in the code. With $logfile, you can adjust the path to
your logfile. But you should show respect to the prerequisite that it has to
be writable by the user qmail is running as (usually qmaild). Because of
this, /tmp is a good place for the logfile.

RUNNING THIS WITH OTHER QMAIL-EXTENSIONS
========================================

You can use this script in combination with other qmail extensions, of
course. It's a little, little bit tricky because you have to take care that
each script (e. g. qmail-scanner-queue.pl) receives the message from the
script executed before.

If you're using, for example, the qmail-scanner with its
qmail-scanner-queue.pl, you simply have to change the variable $qmail_queue
in qq-rbl.pl to the path of qmail-scanner-queue.pl.
qmail-scanner-queue.pl hands the messages back to the "real" qmail queue
when its virus scans are finished.


THE AUTHOR
==========

If you have questions, problems or suggestions, you can reach me via e-mail
at lf-router@web.de. Alternatively, I would be glad if you visited by
website at http://prinzess.dyndns.org.
