*** STWingCS Spam Assassin HOWTO ***

INTRODUCTION 

Spam Assassin is a SPAM filtration software that works with any current mail
setup on the STWingCS servers.  It works by filtering your mail before it
arrives in your INBOX with several intelligent rules to determine whether or
not it is SPAM.  If it detects a message as SPAM it moves it to a seperate
folder called "caughtspam" which you can clean out periodically rather then
having SPAM cluttering your INBOX.

REQUIREMENTS

There are no requirements for this software beyond that which is already
installed on all STWingCS servers.


SETUP

Run the program 'spamassassin-setup' from a command prompt while logged into
force.stwing.upenn.edu.  It will guide you through setting up Spam Assassin and
determine what needs to be done based on your current mail setup.  

NOTE: For Spam Assassin to be fully effective in filtering your mail; you must
forward all your mail to force.stwing.upenn.edu first so that it all passes
through the SPAM filter.  Please see the Mail Fowarding HOWTO listed in the
references section below for help with this.


USAGE

Once set up, SPAM filtration will start on your mail immediately.  All SPAM
will be moved to a folder called "caughtspam".  Please periodically go through
and delete mail in this folder.


ADDITIONAL INFORMATION (*technical*)

The local (ie. user) configuartion file for Spam Assassin is located in:
~/.spamassassin/user_prefs

1. Whitelist / Blacklist Directives:

whitelist_from <host>
whitelist_to <host>
blacklist_from <host>
blacklist_to <host>

These determine senders and recievers that you "know" are or are not spam and
therefore always or never want to recieve.  They would take the form of
something like this in the ~/.spamassassin/user_prefs file:

whitelist_from          *@*freshmeat.net
whitelist_from          *@*stwing.upenn.edu

2. SPAM hit threashold

required_hits <number>
default: 5

Spam Assassin runs a large number of tests on incomming mail and if they come up
positive, assignes a number of "hits" proportional to the probabilty that a msg
containing whatever the test was checking for is spam.  

If you find that it is moving mail that is not spam to the "caughtspam" folder
and in the report the "hits" is just over 5 you can raise this to something a
little higher.

It is recommended to add things to the whitelist rather then raise the hit
threshold overall since it reduces how effective spamassassin is.

3. Auto Whitelists

auto_whitelist_path <full path to autowhitelist file>
default: ~/.spamassassin/auto-whitelist

Spam Assassin includes an auto_whitelist feature which will track messages over
time and adjust the number of "hits" it assignes for tests.  In other words, it
will learn over time to detect the type of spam you generally recieve get better.

You can enable this feature by editing your: ~/.procmailrc file and adding "-a"
after the "-P" on the line that calles spamassassin.

When you get a message that is marked as spam but is really not, save it to a
text file and run:

spamassassin -W < e-mail_in_text_file

This will grab all the e-mails from the message and add them to your
auto_whitelist database.


REFERENCES

For information on how to setup mail forwarding:

http://www.stwing.upenn.edu/computing/faqs/Mail-Fowarding-HOWTO

For general information of the STWingCS setup or basic UNIX shell commands:

http://www.stwing.upenn.edu/computing/faqs/general.php

For more information on the Spam Assassin configuration file / options:

man Mail::SpamAssassin::Conf (this must be at a shell prompt on Force)

For a detailed description of sendmail (the UNIX mail server daemon):

http://www.sendmail.org


CREDITS

Written by Stephen Richter <richters@stwing.upenn.edu>. Copyright 2002.