Getting started

Prerequisites

Be sure that your system has procmail and perl installed:

$ procmail -v
$ perl -v



---

Download

Download a copy of the program: spamfilter.tgz

Untar the program to your home directory (tar -cvzf) -- you should end up with the following:

  /home/username/spamfilter/
                          spamfilter.pl
                          test-good.msg
                          test-spam.msg

  /home/username/spamfilter/conf/
                          block.conf
                          spamfilter.conf

  /home/username/spamfilter/log/
                          spam.log

  /home/username/spamfilter/ex/
                         ex.forward
                         ex.procmailrc
    

---

Configuration

Configure your spamfilter.pl, spamfilter.conf and block.conf files.

Edit /spamfilter/spamfilter.pl and change this line to reflect your system setup:

$spamf_conf = '/home/username/spamfilter/conf/spamfilter.conf';

Edit /spamfilter/conf/spamfilter.conf:

  block_conf:     full path to your block.conf file
  logdir:         directory in which you want log files written
  spammax:        maximum amount of spam received before log email is sent
  debug:          set to 1 to receive command-line debugging information
  home:           full path to your home directory
  spamcount:      current spamcount (this value will change)
  logemail:       email address to send log files to when spamcount is exceeded
  sendmailloc:    location of your sendmail program
  autoaddblock:   automatically add offending email addresses to block list
       

Edit /spamfilter/conf/block.conf as follows:

Under the "FROM DOMAIN PASS" section, add your domain:

domain,pass,yourdomain.org

Under the "TO EMAIL PASS" section, add your email:

temail,pass,username@yourdomain.org
cc,pass,username@yourdomain.org

---

Testing

Before we start diverting mail into the filter, it's a good idea to make sure everything's working properly. Included are a couple of files to test your spamfilter. Perform the tests as follows:

Edit the test-good.msg and add your email in the 'to' area as follows:

To: username@yourdomain.org

Now, pass it into the spamfilter (be cure that you have debug set to 1 in the spamfilter.conf):

$ ./spamfilter.pl < test-good.msg

You should get a response like this:

  [snip]
  *****
  "username@yourdomain.org" matches "username@yourdomain.org" in block.conf -- temail:pass...
  Saving config file to /home/username/spamfilter/procmail/dev/conf/spamfilter.conf...
  exit status=0
      

Given the previous test came out allright, now try to pass some spam into the filter:

$ ./spamfitler.pl < test-spam.msg

You should get a response like this:

  [snip]
  *****
  spammer@spam.com is probably spam...tagged as email,block due to to:someone else  field!
  Saving config file to /home/username/spamfilter/procmail/dev/conf/spamfilter.conf...
  exit status=1
      

---

Final Installation

If everything checked out above, you can actually install the spamfilter. This is the tricky part, as you don't want to loose any mail. I recommend using Pine so that you can define folders to divert potentially unwanted mail without actually deleting it. If anyone comes up with a way to do this using a different mail program, please send me the results and I'll post them.

Edit your .forward file -- replace username (leave the #). Also, be sure that the path to procmail is correct. You can check by issuing this command: $ which procmail

"|IFS=' ' && exec /usr/bin/procmail || exit 75 #username"

Edit your .procmailrc file as follows (Note: this example assumes that you are using Pine as your mailer.):

  MAILDIR=/home/username/mail
  LOGFILE=/home/username/spamfilter/log/procmail.log
  VERBOSE=no

  # code to prevent mail from looping
  :0
  * ! ^X-Loop: username@yourdomain\.org
  {
     # safety net (backup mail - just in case)
     :0c:
     backup

     :0 fhw
     | formail -A "X-Loop: username@yourdomain.org"
  
     # spam filter (do not pass go. do not collect $200)
     :0:spam.lock
     * ? $HOME/spamfilter/spamfilter.pl
     potential-spam

     :0:
     ${DEFAULT}
  }

  #discard any loops
  :0
  * ^X-Loop: username@yourdomain\org.
  looping

That's it! Any mail sent to your email address will automatically be filtered by the program. Spam will be diverted from your inbox to the "potential-spam" folder in Pine. The "backup" diversion is there only for safety and can be removed once you are confident that you aren't loosing any mail. If you decide to keep it, be sure to empty that folder every now-and-then so that you don't waste space.

If you have any questions, problems, or suggestions, please email me at skeplin@one.net.