Welcome to SpamAssassin! ------------------------ SpamAssassin is a mail filter which attempts to identify spam using text analysis and several internet-based realtime blacklists. Using its rule base, it uses a wide range of heuristic tests on mail headers and body text to identify "spam", also known as unsolicited commercial email. Once identified, the mail can then be optionally tagged as spam for later filtering using the user's own mail user-agent application. In its most recent test, SpamAssassin differentiated between spam and non-spam mail correctly in 99.94% of cases. Since then, it's just been getting better and better! SpamAssassin also includes support for reporting spam messages automatically, and/or manually, to collaborative filtering databases such as Vipul's Razor [1]. [1]: http://razor.sourceforge.net/ The distribution provides "spamassassin", a command line tool to perform filtering, along with "Mail::SpamAssassin", a set of perl modules which implement a Mail::Audit plugin, allowing SpamAssassin to be used in a Mail::Audit filter or (possibly at some point) in a spam-protection proxy POP/IMAP server. In addition, Craig Hughes has contributed "spamd", a daemonized version of SpamAssassin, which runs persistently. Using "spamc", a lightweight C client, this allows an MTA to process large volumes of mail through SpamAssassin without having to fork/exec a perl interpreter for each one. SpamAssassin lives at http://spamassassin.taint.org/ or in CPAN, and is distributed under the same license as Perl itself. This module owes a lot of inspiration to Mark Jeftovic's filter.plx, which I used for a long time, and contributed some code to. However, SpamAssassin is a ground-up rewrite with a new, greatly improved ruleset, a different code model and installation system, and hopefully will be easy to adapt for a multitude of applications. [2]: http://AntiSpam.shmOOze.net/filter/ Questions regarding SpamAssassin should be sent to the mailing list: . Installing SpamAssassin ----------------------- The easiest way to do this is using CPAN.pm, like so: perl -MCPAN -e shell o conf prerequisites_policy ask install Mail::SpamAssassin quit Alternatively download the tarfile or zipfile from http://spamassassin.taint.org/ , and install that, like so: [unzip/untar the archive] cd Mail-SpamAssassin-* perl Makefile.PL make make install [as root] You will require the Mail::Audit module, and any modules it requires. Here's how to install this using CPAN.pm: perl -MCPAN -e shell o conf prerequisites_policy ask install Mail::Audit quit Optional Additional Modules --------------------------- In addition, the following modules will be used for some checks, if available. If they are not available, SpamAssassin will still work, just not as effectively -- some of the spam-detection tests will have to be skipped. - Net::DNS (from CPAN) Used to check the RBL, RSS, DUL etc. and perform MX checks. Recommended. perl -MCPAN -e shell o conf prerequisites_policy ask install Net::DNS quit - Razor http://razor.sourceforge.net/ Used to check message signatures against Vipul's Razor collaborative filtering network. Razor is not available from CPAN -- you have to download it from the URL above. Razor has a large number of dependencies on CPAN modules. Feel free to skip installing it, if this makes you nervous; SpamAssassin will still work well without it. Using SpamAssassin ------------------ Steps to take for every installation: - Install Mail::Audit and Mail::SpamAssassin on your mail server, as above. - Test it: spamassassin -t < sample-nonspam.txt > nonspam.out spamassassin -t < sample-spam.txt > spam.out Verify (using a text viewer, ie. "less" or "notepad") that nonspam.out has not been tagged as spam, and that spam.out has. The files should contain the full text and headers of the messages, the "spam.out" message should be annotated with "****SPAM****" in the subject line and a report from SpamAssassin, and there should be no errors when you run the commands. Even though sample-nonspam.txt is not spam, nonspam.out will contain a SpamAssassin report anyway. This is a side-effect of the "-t" (test) switch. However, there should be less than 5 hits accumulated; when the "-t" switch is not in use, the report text would not be added. If the commands do not work, DO NOT PROCEED TO THE NEXT STEP, as you will lose mail! If you want to use Mail::Audit: - run "perldoc Mail::SpamAssassin" and take a look at the synopsis, it outlines what you need to add to your audit script. - Copy the configuration files (see CUSTOMISING, below) to a known location, so your script can set the appropriate options for Mail::SpamAssassin to load them. If you're using procmail: - Make a backup of your .procmailrc (if it exists). cp ~/.procmailrc ~/.procmailrc.bak - add the following lines to ~/.procmailrc, at the top of the file before any existing recipes: :0fw | spamassassin -P :0e { EXITCODE=$? } :0: * ^Subject:.*\*\*\*\*SPAM\*\*\*\* caughtspam That'll process all mail through SA, and refile spam messages to a folder called "caughtspam" in your home directory. - Send yourself a mail message, and ensure it gets to you. If it does not, copy your old backed-up .procmailrc file back into place and ask your sysadmin for help! Here's commands to do that: cp ~/.procmailrc.bak ~/.procmailrc echo "Help!" | mail root If you want to use SpamAssassin site-wide: - take a look at the notes on the website, at http://spamassassin.taint.org/sitewide.html . You may want to use 'spamd' (see below). If you don't use any mail filter just yet: - Make a backup of your .forward (if it exists). cp ~/.forward ~/.forward.bak - Change your ~/.forward file so it reads like this: "| spamassassin || exit 75" - Send yourself a mail message, and ensure it gets to you. If it does not, copy your old backed-up .forward file back into place and ask your sysadmin for help! Here's commands to do that: cp ~/.forward.bak ~/.forward echo "Help!" | mail root Other installation notes: - If you get spammed, it is helpful to everyone else if you re-run spamassassin with the "-r" option to report the message in question as "verified spam". This will add it to Vipul's Razor (http://razor.sourceforge.net/), a collaborative spam filtering network, if you've installed the Razor modules. spamassassin -r < spam-message If you use mutt as your mail reader, this macro will bind the X key to report a spam message. macro index X "| spamassassin -r" This is, of course, optional -- but you'll get lots of good-netizen karma. ;) - Quite often, if you've been on the internet for a while, you'll have accumulated a few old email accounts that nowadays get nothing but spam. You can set these up as spam traps using SpamAssassin; see the ''SPAM TRAPPING'' section of the spamassassin manual page for details. If you don't want to go to the bother of setting up a system yourself to do this, feel free to set up a simple alias to forward any mails to -- replace "someaddress" with something to identify you, such as your email addr or website with non-alphanumeric chars replaced by underscores, or similar. This will feed it into my spam-trapping system running on taint.org, where it will be fed into Razor. - The distribution now includes 'spamd', a daemonized version of the perl script, and 'spamc', a low-overhead C client for this, contributed by Craig R. Hughes. This greatly reduces the overhead of checking large volumes of mail with SpamAssassin. Take a look in the 'spamd' directory for more details. - Scores and other user preferences can now be loaded from an SQL database; see the 'sql' subdirectory for more details. Customising ----------- When installing SpamAssassin, the configuration files defining the list of rules and the default user preferences are written to INSTALLSITELIB, or /usr/lib/perl5/site_perl/5.005 (or similar) on a typical UNIX system. Users who run "spamassassin" will receive a copy of the user preferences in their home directories as the file "~/.spamassassin.cf". This allows them to edit their preferences and reweight the rules, or to increase or decrease the "line in the sand" at which point a mail is judged spam (or not). Systems administrators can create the "/etc/spamassassin.cf" file to add new rules for all users on the system, or they can create "/etc/spamassassin.prefs" to set default preferences for their users. The default config files installed by SpamAssassin are generally written into the site_perl directory; this may be "/usr/lib/perl5/site_perl/5.005", or similar. This path changes, depending on your OS and the version of perl you have installed (unfortunately). These paths are pretty ugly, but since SpamAssassin uses Perl's Makefile-building system for portability and compatibility with CPAN, they're currently unavoidable. There is no difference in interpretation between the rules file and the preferences file, so users can add new rules for their own use in the "~/.spamassassin.cf" file, if they like -- as long as they're running SpamAssassin themselves, and not using the site-wide "spamd" filtering system. So, to summarise: - __SITE_PERL_DIRECTORY__/spamassassin.cf: Distributed configuration file, with all defaults. Do not modify this, as it is overwritten when you upgrade. - /etc/spamassassin.cf: Site config file, for system admins to create, modify, and add local rules and scores to. Modifications here will be added to the config loaded from the above file. - __SITE_PERL_DIRECTORY__/spamassassin.prefs: Distributed default preferences. Do not modify this, as it is overwritten when you upgrade. - /etc/spamassassin.prefs: Site default preferences, for system admins to create, modify, and set defaults for users preferences files. Takes precedence over the above prefs file, if it exists. - $USER_HOME/.spamassassin.cf: User preferences file. If it does not exist, one of the default prefs file from above will be copied here for the user to edit later, if they wish. Locali[sz]ation --------------- All text displayed to users is taken from the configuration files. This means that you can translate messages, test descriptions, and templates into other languages. If you do so, I would *really* appreciate if you could send a copy back of the updated messages; mail them to . Hopefully if it takes off, I can add them to the distribution as "official" translations and build in support for this. You will, of course, get credited for this work ;) Help With SpamAssassin ---------------------- There's a mailing list for support or discussion of SpamAssassin. It lives at . See http://spamassassin.taint.org/lists.html for the sign-up address and a link to the archive of past messages. Commercial Tests ---------------- There are several tests in the spamassassin configuration file which are turned off by default, namely the mail-abuse.org and bl.spamcop.net tests. The mail-abuse.org tests are RCVD_IN_RBL, RCVD_IN_RSS, and RCVD_IN_DUL; the bl.spamcop.net test is called RCVD_IN_BL_SPAMCOP_NET. These are commercial services, so you need to pay money to use them. Having said that, the bl.spamcop.net service gets my recommendation as the most useful blacklisting DNS service I've found. More information on it can be found at http://spamcop.net/bl.shtml . The mail-abuse.org tests are free for personal use, for now -- so if you're using SpamAssassin as a personal mail filter you may turn them on. More information on the mail-abuse.org services can be found here: http://mail-abuse.org/rbl+/ and http://www.mail-abuse.org/feestructure.html . To turn on the tests, simply assign them a non-zero score, e.g. by adding these lines to your ~/.spamassassin.cf file: score RCVD_IN_RBL 10 score RCVD_IN_RSS 1 score RCVD_IN_DUL 1 score RCVD_IN_BL_SPAMCOP_NET 4 (end of README) // vim:tw=74: