What:

 This document describes how to use bogofilter to filter mail that

 passes through a postfix mail server.

Theory:

 The idea is to setup bogofilter on the mail server and have it filter

 all incoming mail.

 There are several advantages to doing so:

 1. Mail users on non-Unix platforms will benefit from bogofilter spam

    filtering.

 2. bogofilter learns better since it has access to a larger corpus.

 There is also a mechanism for users to register new spam/non-spam

 messages, as well as correcting misclassifications.

Assumptions:

- Most of the steps described here require root privileges.

- postfix is installed into /usr. If you installed postfix

  from rpm, it is probably installed there. If you installed from

  source, it is installed into /usr/local unless you changed its

  configuration.

- bogofilter is installed in /usr/bin/bogofilter on the mail server.

Installation:

- Build the initial spam and non-spam databases by feeding your corpus of mail.

   Assuming there are two files in mbox format in /home/bogofilter, you say:

   # cd /home/bogofilter

   # bogofilter -d . -s < spam.mbx

   # bogofilter -d . -n < nonspam.mbx

Filtering:

- Create a script to invoke bogofilter, say

  /home/bogofilter/postfix-filter.sh, modeled on the following:

	#!/bin/sh

	FILTER=/usr/bin/bogofilter

	FILTER_DIR=/var/spool/filter

	# WARNING! The -i is crucial, else you may see

	# messages truncated at the first period that is alone on a line

	# (which can happen with several kinds of messages, particularly

	# quoted-printable)

	# -G is ignored before Postfix 2.3 and tells it that the message

	# does not originate on the local system (Gateway submission),

	# so Postfix avoids some of the local expansions that can leave

	# misleading traces in headers, such as local address

	# canonicalizations.

	POSTFIX="/usr/sbin/sendmail -G -i"

	export BOGOFILTER_DIR=/home/bogofilter

	# Exit codes from <sysexits.h>

	EX_TEMPFAIL=75

	EX_UNAVAILABLE=69

	cd $FILTER_DIR || \

	    { echo $FILTER_DIR does not exist; exit $EX_TEMPFAIL; }

	# Clean up when done or when aborting.

	trap "rm -f msg.$$ ; exit $EX_TEMPFAIL" 0 1 2 3 15

	# bogofilter -e returns: 0 for OK, nonzero for error

	rm -f msg.$$ || exit $EX_TEMPFAIL

	$FILTER -p -u -e > msg.$$ || exit $EX_TEMPFAIL

	exec 

	rm -f msg.$$ # safe, we hold the file descriptor

	exec $POSTFIX "$@"

	exit $EX_TEMPFAIL

   Make sure the script is executable!

   Given a good initial corpus, it is better to have bogofilter update

   its lists based on the message classification, since it is quite

   likely to get it right.  Misclassifications MUST be corrected later.

- Modify your /etc/postfix/master.cf to run the filter.

    After the line that starts "smtp " and ends in "smtpd" (don't

    confuse it with the one that ends in "smtp", mind the "d"!) and add the

    following line, you must indent it with some spaces or tabs:

	    -o content_filter=filter:

    At the end of the file, add the following two lines:

	filter	  unix	-	n	n	-	-	pipe

	    flags=Rq user=filter argv=/home/bogofilter/postfix-filter.sh -f ${sender} -- ${recipient}

- Now, every incoming message will have the header line

	X-Bogosity: ...

  added to the headers.

  A bogofilter classified spam messages will have the entry:

	X-Bogosity: Spam ...

  Note that the actual header name is configurable at compile time and

  may have been changed.

- Educate your users on how to filter their spam based on the value of

  the X-Bogosity header.  Spam messages should be diverted to a spam

  mailbox, rather than deleted.

Registration and Correction:

  To use external filtering with Postfix, create a Unix group on the

  server named "filter".

  Next, create a user account named "filter" on the server and make it a

  member of group "filter".  This will be a least-privileged account

  used by the scripts. 

  No other user should belong to group "filter".  Logins for the

  "filter" account should be locked (e. g. 'passwd -l filter' on Linux and

  Solaris) and the shell in /etc/passwd should be set to an invalid

  shell such as /bin/false.

  Arrange for users to send misclassified mail to a particular mailbox 

  and make sure that the database is updated regularly.

  If you cannot arrange for regular corrections, remove the "-u" from 

  the bogofilter command in the script above, and update the database 

  as the need arises by registering more mail.

- Make sure the script is executable

	# chmod +x /home/bogofilter/postfix-filter.sh

- Change the ownership of /home/bogofilter to the filter user

       # chown -R filter:filter /home/bogofilter

- Done!

Author:

 David Relson <relson@osagesoftware.com>

 Matthias Andree <matthias.andree@gmx.de>