junkfilter

a junk e-mail filter system for procmail

Copyright 1997-98, Gregory Sutter <gsutter@pobox.com>

Version 19990331 README
$Id: junkfilter.readme,v 2.10 1999/03/31 11:07:13 gsutter Exp $

Contents:
	1.  Use of junkfilter
	2.  How to get junkfilter
	3.  Mailing list
	4.  Installation instructions
	5.  Sample .procmailrc file
	6.  Contributors

1.  Use of junkfilter
	junkfilter is copyright 1997-98 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

2.  How to get junkfilter
	The junkfilter web page is 
	http://www.pobox.com/~gsutter/junkfilter/
	junkfilter and this documentation are available at the web site.

3.  Mailing list
	The junkfilter mailing list is jf-users@jpunix.com.  To
	subscribe or unsubscribe, send a message with "(un)?subscribe" on
	the first line to jf-users-request@jpunix.com.  DO NOT send
	administrative requests to the distribution address!  Many thanks
	to John Perry <perry@jpunix.com> for hosting this list.

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.
	
	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 authors do 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=/usr/local/etc/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.  Contributors to junkfilter
	Many people have contributed to junkfilter in various ways; the
	authors would like to thank the following people in particular:

	Matthew Hunt <mph@pobox.com>, who co-developed junkfilter for the
			 	      first few months.  Thanks, Matt!
	Era Eriksson <era@iki.fi>
	David Tamkin <dattier@wwa.com>
	Brian Goetz <brian@quiotix.com>
	Edward Sabol <sabol@alderaan.gsfc.nasa.gov>
	Bryan D. McMeen <bryan.mcmeen@symtecinc.com>
	Jeff A. Earickson <jaearick@colby.edu>
	Philip Guenther <guenther@gac.edu>
	John Wilkes <john@wilkes.com>
	Brad Knowles <brad@his.com>
	John Perry <perry@jpunix.com>
	and
	the procmail mailing list <procmail@Informatik.RWTH-Aachen.DE>

EOF junkfilter.readme