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 <msg.$$ || exit $EX_TEMPFAIL
	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>