splam v2.0 ========== (the mail filtering program formerly known as ignore-spam) (C) Christi Alice Scarborough (ccs95@aber.ac.uk) 1996,1997 Released under the GNU public licence - see file COPYING for details Abstract -------- splam is a program that prevents you from receiving email from sites known to harbour Internet spammers, and also performs some checks to see if mail messages are junk email. It seems that those who send unsolicited email are not concerned about whether it is actually wanted or not. Sadly it's difficult to know beforehand whether any piece of email constitutes spam without actually reading it, but once you do know, there's now a way to prevent yourself ever receiving mail from that machine again. Hopefully if enough people do this, the spammers will understand that their mail is never seen, so the whole exercise becomes counter-productive and hopefully stops. A note for those upgrading from ignore-spam ------------------------------------------- Splam has undergone significant changes since its previous incarnation as ignore-spam, so much so that most of the code is new for this release. If you are upgrading from ignore-spam, that it is probably best to start from scratch with the configuration file, although the contents of your existing spam-approved, spam-accept and spam-reject files can be cut and paste into the spam.hosts file if you so wish. Prerequisites ------------- Splam requires Perl 5 to be installed on your mailserver. It expects to run in a UNIX environment, but may work in other systems. A mail filtering program is also required, and you will need a text editor to alter the configuration files. It also requires an SMTP service to be provided on port 25 of the machine it is running on. This will normally be the case. If you need to know more about mail filtering and how it works, please look at Nancy McGough's Mail Filtering FAQ at http://www.jazzie.com/ii/faqs/archive/mail/filtering-faq/ Disclaimer ---------- Splam is provided completely free of charge for use within commercial and non-commercial organisations as a service to the Internet community. It is provided AS IS, without any warranties implicit or otherwise. It should be considered unsupported, although I will do my best to offer any help I can via email, time permitting. Quick Start ----------- (Less experienced users should skip down to the section marked Introduction.) 1) Copy splam, .splamrc and splam.hosts to a suitable directory 2) Edit .splamrc and splam.hosts to suit your setup 3) Pipe incoming mail through splam using your filter program Installation ------------ First copy the files splam, .splamrc and splam.hosts to an appropriate directory. Splam will look for its configuration file in the following places 1) your home directory 2) the path from which the program was run 3) the current directory 4) the file pointed to by the environment variable SPLAMRC You should use the fourth option if you wish to call the configuration file anything other than .splamrc. Installation is then a three stage process. Edit the configuration file, .splamrc, and change the variables to suit your personal environment. The file explains in detail what each option does. In particular, you should change the password that people can use to contact you. To disable the password option, you should put the names of spamming hosts in the black list rather than the grey list of the spam.hosts file (see below for details). Next edit the splam.hosts file. This file tells the program what text to search for in the message headers. It is split into three sections 1) The white list If you get mail that contains an address which contains (or is the same as) any entry in this list in the From: field, splam will automatically accept this mail. It will not check to see if this is spam. This is useful if you correspond with a user at a site that is on the grey list or black list (see below), since including them on the white list will mean that they will not have to supply the password each time they mail you. 2) The grey list If you get email from a site on this list, then splam throws this mail away and they will be sent a message telling them that their mail has been ignored. If, however, the correct password appears on the Subject: line, the mail will get through to you. 3) The black list Any email address (or site) that you put on a line of this section will NEVER be able to send you mail, even if they include the password in the subject field. Use this section with extreme caution (if at all). The final stage is to install the script. To do this, you need to be using some kind of filtering software. Splam works by returning a 0 to the filter program (to indicate successful delivery) if it has intercepted the mail. Otherwise it returns a 1 (to indicate failure to deliver) which hands back control to the filtering program, which will hopefully go on to deliver the mail. Here are recipes for two popular filtering programs. If you use a different program, then you should consult your manual pages for details of how to set this up. 1) procmail Add these lines to the bottom of your .procmailrc file, replacing with the location of the program. :0:? * . | /splam 2) PP (untested) Add the following to the bottom of your .mailfilter file, replacing with the location of the program. should be the command that you normally use to deliver mail to you. For example, mine might be `unixfile "/aber/ccs95/Mail/INBOX"` but it will depend on what method you are using to read your mail. Contact your system administrator for advice if you are unsure what command to use. Note that if there is another line containing only the text "if (!delivered) {" in your .mailfilter, then this is probably the command that I'm talking about, and you should just insert the first three lines below into the .mailfilter file above this line. if (!delivered) { pipe "/splam"; } if (!delivered) { ; } 3) exim (untested) Add the following line to the bottom of your .forward file. pipe "/splam" where is the complete path to the program. Usage ----- That's all there is to it, mail will now be filtered automatically without you having to manually edit any filtering files. If you wish to change splam's hosts file, you can do this using the command line options. The command syntax is splam [-b|-g|-w|-d] where -b adds to the "black list" -g adds to the "grey list" -w adds to the "white list" -d removes all references to from all of the lists If no switch is supplied, splam assumes -g, so splam naughty.com would add the host naughty.com to the grey list. Mail loops ---------- splam should not cause mail loops, since it will not send replies to the same address more than three times in any one day. Dedication ---------- This program is dedicated to Gaz "madwolf" Barnes, for his help and ideas. Revision History ---------------- v2.0 - July 28th 1997 o Splam now checks for suspect headers and can thus pick up even more junk mail. What splam regards as suspect can be altered using UNIX regexps. o Added proper config file support. Hopefully this will make maintaining splam much easier. The program now has only two subsidiary files (the config file and the hosts file) and two log files (rejected mail and errors). o Splam no longer requires sendmail to run. It will now work with any mail transfer agent. o Added error logging. This seemed like a good idea, since splam runs unattended most of the time, so if something were going wrong, you might not know about. Splam also contains better logging of reasons for ignoring mail (in the main log file) and code to stop the log files growing indefinately. o Proper command line options now mean that the hosts file can be changed completely from the command line without any need to edit the file. o Changed the name to splam (short for "splat spam"). I know, I know. I just wanted something a bit snappier than ignore-spam, and couldn't think of anything better. Sorry. o Lots of minor fixes. (Thanks to C. T. Nadovich for pointing one of these out.) v1.21 - April 9th 1997 o Whoops, I missed another small date bug. ignore-spam now correctly reports the month in which the spam was received. v1.2 - April 8th 1997 o fixed a small bug in the logging code that meant two dates (such as 11th Feb 1997 and 1st Dec 1997) would be given the same date code. This also makes the dates a lot easier for human beings to read (even if it is in the British format :P ). o ignore-spam will now send a copy of the headers of the original message with rejection notices. In some rare cases rejection notices go to the postmaster at the site where the spam appears to have originated. This should help them to track down the perpetrator. This feature can be turned off by commenting out a line at the top of the program. v1.1 - December 10th 1996 o ignore-spam now searches more aggressively for spam addresses o slightly better detection of reply addresses o It's now possible to use substrings in the approved and reject files, so if you wanted to never receive mail from anyone at xxx.net, unless it was from anyone using yyy.xxx.net then you could add the line xxx.net to your spam-reject file, but place yyy.xxx.net in your spam-approved file. v1.0 - November 23rd 1996 o Initial release Legal Gibberish --------------- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.