junkfilter a junk e-mail filter system for procmail Copyright 1997-2000 Gregory Sutter Version 20000313 README $Id: junkfilter.readme,v 2.14 2000/03/14 01:14:47 gsutter Exp $ Contents: 1. Use of junkfilter 2. How to get junkfilter 3. Mailing list 4. Installation instructions 5. Sample .procmailrc file 6. Forwarding missed spam 7. Contributors 1. Use of junkfilter junkfilter is copyright 1997-2000 Gregory Sutter. junkfilter is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA or see http://www.fsf.org/copyleft/gpl.html Alternative licensing is available; please contact the author for information. 2. How to get junkfilter The junkfilter web page is http://junkfilter.zer0.org/ junkfilter and this documentation are available at the web site. 3. Mailing lists junkfilter has two mailing lists, an announce list and a general-purpose list. If you wish to receive announcements of new releases, subscribe by sending a message to junkfilter-announce-subscribe@egroups.com. If you wish to also receive general mail from a two-way mailing list, subscribe by sending a message to junkfilter-users-subscribe@egroups.com. Thanks to egroups.com for hosting these lists. 4. Installation of junkfilter We assume you've already got procmail installed and running properly, as this is explicitly a "junk email filter system for procmail". Consult the procmail documentation if you need help installing procmail. Set the $PMDIR variable. We recommend that you make a directory ".procmail" in your home directory and a symlink from $HOME/.procmailrc to $HOME/.procmail/procmailrc. This file is not part of junkfilter; it is the procmailrc file that you already have installed. If you do this, you can set PMDIR=$HOME/.procmail Place the junkfilter files (junkfilter*, jf*) wherever you want them. This can be in $PMDIR or anywhere else. Set $JFDIR in your procmailrc to the directory in which you placed junkfilter. If you are installing junkfilter as a systemwide solution, and want each user to have customizable defaults, you can copy the junkfilter.config file to their home directories, calling it ".junkfilterrc". junkfilter will check $HOME/.junkfilterrc for local configuration overrides each time it is called. To call junkfilter, place a line in your procmailrc file that reads: INCLUDERC=$JFDIR/junkfilter This will call junkfilter. All other junkfilter files are called from within this first file. You now have a basic junkfilter setup. You now need to configure junkfilter to fit your every desire. Edit junkfilter.config and change the various options from 0 to 1 and vice-versa. 0 means "false"; 1 means "true". A given piece of code will only execute if it is set true. Please read the comments at the beginning of each one before changing anything. The file junkfilter.user is provided as a convenient place for you to store your own personal junk filtration recipes. If you follow the recommended format (given at the beginning of that file), junkfilter will treat your recipes the same as the rest of the files. The "user" section is the first section checked when junkfilter is called. In the distribution, the stock junkfilter.user is called junkfilter.user-default so that your personalized copy is not overwritten when you upgrade later. If you enable any of the user- rules or options in junkfilter, you MUST be sure that the files referenced by them in junkfilter.config exist! This means that you must rename the files distributed as *-default, removing the dash and the word "default". If you don't do this, all of your mail will end up in the slag heap. You can change the default action of jf to whatever you prefer. The only action command in junkfilter is to set the variable JFEXP to a relevant piece of text. It is up to you to then take some action. Since you've called junkfilter from your .procmailrc file, you can easily take action depending on the output (in the JFEXP variable) of junkfilter. The whitelist feature is a way of making sure that certain people/mails are not blocked, even if junkfilter would block them ordinarily. The implementation of the whitelist does not break compatibility with older releases of junkfilter, but does require that a more complex set of recipes be used to decide whether or not to take action on the message. I use this action in my .procmailrc directly after the INCLUDERC=$JFDIR/junkfilter statement: :0 * JFEXP ?? . { :0 f * JFSTATUS ?? 1 | formail -i "X-junkfilter: $JFVERSION" -i "X-Spammer: $JFEXP" :0 E : | formail -i "X-junkfilter: $JFVERSION" -i "X-Spammer: $JFEXP" \ >> junkmail } Instead of this, you can change it to whatever you prefer. The most common change will be the name of the mailbox in which the junk mail is stored. You can change it to /dev/null if you wish, but remember that no matter how good the filter, mistakes will be made. The author does NOT recommend immediately discarding any mail filtered by junkfilter. 5. Sample .procmailrc file that calls junkfilter Everything between the two lines of "----------" is the file. Note how $PMDIR and $JFDIR are set in this file. ---------- SHELL=/bin/sh PATH="$HOME/bin:/usr/bin:/usr/local/bin:/usr/include:/usr/local/sbin:/bin:/sbin:/usr/sbin" MAILDIR=$HOME/mail PMDIR=$HOME/.procmail JFDIR=$HOME/.procmail/junkfilter DEFAULT="inbox" LOGFILE=$PMDIR/log LOGABSTRACT=all VERBOSE=no # Procmail mailing list :0 : * ^Resent-From:.*procmail@Informatik.RWTH-Aachen.DE | formail -i "X-Fkey: procmail" >> procmail # Call junkfilter INCLUDERC=$JFDIR/junkfilter # Take action if junkfilter caught a junkmail. :0 * JFEXP ?? . { :0 f * JFSTATUS ?? 1 | formail -i "X-junkfilter: $JFVERSION" -i "X-Spammer: $JFEXP" :0 E : | formail -i "X-junkfilter: $JFVERSION" -i "X-Spammer: $JFEXP" \ >> junkmail } # Catches everything else. :0 : inbox ---------- 6. Forwarding missed spam junkfilter users who wish to see more of their spam caught by the filter in the future may wish to forward their spam (which was not caught by junkfilter) to an email address set up for this purpose. To do this, you should enable JF_OPT_SENDBACK in your junkfilter.config file. It's near the end. This will enable some settings that will mark each email that passes through junkfilter. If a spam has the headers added by this setting, it will be accepted at the email address . Spam sent here will be analysed and used to improve junkfilter. 7. Contributors to junkfilter Many people have contributed to junkfilter in various ways; the author would like to thank the following people in particular: Matthew Hunt , who co-developed junkfilter for the first few months. Thanks, Matt! Jeff A. Earickson Era Eriksson Brian Goetz Philip Guenther Brad Knowles Bryan D. McMeen John Perry Edward Sabol David Tamkin John Wilkes and the procmail mailing list EOF junkfilter.readme