Copyright 2007 by Kim Minh Kaplan

[[http://www.kim-minh.com/pub/greyfix/][Greyfix]] is the greylisting policy daemon for [[http://www.postfix.org/][Postfix]] written by
[[mailto:kaplan+greyfix@kim-minh.com][Kim Minh Kaplan]].  [[http://projects.puremagic.com/greylisting/][Greylisting]] is an anti spam technique described by
Evan Harris.  Postfix is a popular mail transport agent developped by
Wietse Zweitze Venema.  Greyfix uses Postfix policy mechanism to
enable greylisting with Postfix.

Latest version:
http://www.kim-minh.com/pub/greyfix/greyfix-0.3.2.tar.gz,
http://www.kim-minh.com/pub/greyfix/greyfix-0.3.2.tar.gz.asc

<contents>

* Features

   - Low and tunable resource usage and high efficiency.  The program
     is written in C and uses Berkeley DB to track mailers.  By itself it
     allocates memory only for a single request and the Berkeley DB library
     can be configured to use very few RAM.
   - Integrates with Postfix's master daemon.  Postfix will shutdown
     greyfix when it is not used completely freeing its runtime
     resources.
   - No administrative burden.  Everything happens "automagically".
     Well...  Currently this is not completely true, records are not
     yet expired.
   - No need for a database server.  Uses Berkeley DB.

* Requirements

   - [[http://www.kim-minh.com/pub/greyfix/][Postfix]]
   - [[http://www.oracle.com/database/berkeley-db/index.html][Berkeley DB]]

* Quickstart

Greyfix uses GNU's build system.  To install the greyfix daemon just
type the following commands:

<example>
    $ gzip -cd greyfix-0.3.2.tar.gz | tar xf -
    $ cd greyfix-0.3.2
    $ ./configure
    $ make
    $ su -c 'make install'
</example>

Edit Postfix's master configuration file, =/etc/postfix/master.cf=, and
add the following:

<example>
greyfix    unix  -       n       n       -       -       spawn
  user=nobody argv=/usr/local/sbin/greyfix -/ 24
</example>

Edit Postfix's main configuration file, =/etc/postfix/main.cf= and add
the following:

<example>
smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination, check_policy_service unix:private/greyfix
</example>

If there is already a =smtpd_recipient_restrictions= configuration line
you should edit it rather than add a new one.  The important part for
greyfix is that you should add <code>check_policy_service
unix:private/greyfix</code> to it.

Finally have postfix reload its configuration with <code>postfix
reload</code>.

* Usage

<example>
greyfix [-v] [-d] [-h <Berkeley DB home directory>] [-g <greylist delay>]
    [-b <bloc maximum idle>] [-p <pass maximum idle>] [-/ <network bits>]

    -b <seconds>, --bloc-max-idle <seconds>

	This determines how many seconds of life are given to a record
	that is created from a new mail (ip, from, to) triplet.  Note
	that the window created by this setting for passing mails is
	reduced by the amount set for --greylist-delay.  NOTE: See
	also --pass-max-idle.  Defaults to 18000 (5 hours).

    -d, --debug

	Debug logging

    -g <seconds>, --greylist-delay <seconds>

	This determines how many seconds we will block inbound mail
	that is from a previously unknown (ip, from, to) triplet.  If
	it is set to zero, incoming mail association will be learned,
	but no deliveries will be tempfailed.  Use a setting of zero
	with caution, as it will learn spammers as well as legitimate
	senders.  Defaults to 3480 (58 minutes).

    -h <Berkeley DB home directory>, --home <Berkeley DB home directory>

	Location of the Berkeley DB environment home location (the
	default is autoconf's $localstatedir/greyfix
	i.e. /usr/local/var/lib/greyfix).

    -p <seconds>, --pass-max-idle <seconds>

	How much life (in secs) to give to a record we are updating
	from an allowed (passed) email.

	The default is 36 days, which should be enough to handle
	messages that may only be sent once a month, or on things like
	the first monday of the month (which sometimes means 5 weeks).
	Plus, we add a day for a delivery buffer.

    -v, --verbose

	Verbose logging

    -/ <nbits>, --network-prefix <nbits>

	Only consider the first <nbits> bits of an IPv4 address.
	Defaults to 32 i.e. the whole adresse is significant.
</example>

* Notes

GNU Autoconf's default value for =$(localstatedir)= is
=/usr/local/var/lib= which is quite different from what most Unix
distribution use.  You'll probably want to invoke configure like this:

<example>
    $ ./configure --localstatedir=/var/lib
</example>

This makes Greyfix DB be located in =/var/lib/greyfix=.  Alternatively
you can use the =-h <DB home>= command line option but do not forget
to create the directory and give it correct permissions so that
Greyfix can access it.

Greyfix uses syslog with facility =LOG_MAIL=.  As such the log messages
should appear along postfix's.

You should use some whitelisting of some sort for some servers.  A
good starting base is the whitelist distributed with postgrey (I'm
planning on including it in Greyfix distribution).  You'd use it like
this:

<example>
smtpd_client_restrictions = check_client_access hash:/etc/postfix/access
</example>

* Download

The latest version is [[http://www.kim-minh.com/pub/greyfix/greyfix-0.3.2.tar.gz][greyfix-0.3.2.tar.gz]] ([[http://www.kim-minh.com/pub/greyfix/greyfix-0.3.2.tar.gz.asc][PGP signature]])

Older versions are still available:

   - [[http://www.kim-minh.com/pub/greyfix/greyfix-0.3.1.tar.gz][greyfix-0.3.1.tar.gz]] ([[http://www.kim-minh.com/pub/greyfix/greyfix-0.3.1.tar.gz.asc][PGP signature]])
   - [[http://www.kim-minh.com/pub/greyfix/greyfix-0.3.tar.gz][greyfix-0.3.tar.gz]] ([[http://www.kim-minh.com/pub/greyfix/greyfix-0.3.tar.gz.asc][PGP signature]])
   - [[http://www.kim-minh.com/pub/greyfix/greyfix-0.2.tar.gz][greyfix-0.2.tar.gz]] ([[http://www.kim-minh.com/pub/greyfix/greyfix-0.2.tar.gz.asc][PGP signature]])
   - [[http://www.kim-minh.com/pub/greyfix/greyfix-0.1.tar.gz][greyfix-0.1.tar.gz]] ([[http://www.kim-minh.com/pub/greyfix/greyfix-0.1.tar.gz.asc][PGP signature]])

* TODO

   - Real documentation
   - Automatic removal of expired triplets
   - Configurable delay message
   - Statistic collection
   - Use Berkeley DB Transactional Data Store instead of Concurrent Data Store,
   - Auto whitelisting of mail relays that pass greylisting repeatedly
   - SPF?  This could render <code>--network-prefix</code> unnecessary,
   - Use Milter protocol?
