# $Id: README,v 1.2 2004/03/10 21:35:45 manu Exp $
###########################################################################

		     ======================================
		       milter-greylist installation notes 
		       $Date: 2004/03/10 21:35:45 $
		     ======================================

		       Emmanuel Dreyfus <manu@netbsd.org>

Table of contents:  
==================

Run this command to produce a table of contents:
 sed '/^.====/{g;p;};h;d' README

 1 Building and installing milter-greylist 
 =========================================

Just do the usual ./configure && make && make install

If libpthread and libmilter are not automatically located, use
--with-libpthread and --with-libmilter flags to the configure
script.  If you intend to run milter-greylist under an unprivileged
UID, use the --with-user flag.

On the make install step, the Makefile will install a default config
file in /etc/mail/greylist.conf, except if there is already such
a file. In that case the original file is preserved.


 2 Configuring sendmail with milter-greylist
 ===========================================

You need a few options in sendmail.cf to use milter-greylist:

O InputMailFilters=greylist Xgreylist,
S=local:/var/milter-greylist/milter-greylist.sock O
Milter.macros.connect=j, {if_addr}


 3 Configuring milter-greylist 
 =============================

Edit /etc/mail/greylist.conf, and add addr lines for at least
all you local network addresses. Here is an example:

addr 192.0.2.0/24 
addr 10.0.0.0/8

Then consider adding addresses of all the friendly network you get
mail from. By friendly network, we mean network with no spammers:
Universities are usually friendly, some companies are friendly,
some other are not, and dial-up and ADSL ISP are definitively not
friendly at all.


 4 Trying it out for a few users 
 ===============================

Add some rcpt lines to /etc/mail/greylist.conf for the users that
want to try milter-greylist filtering. Here is an example:

rcpt John.Doe@example.net 
rcpt webmaster@example.net 
rcpt postmaster@example.net

Then start milter-greylist with the -T option, which will make
greylisting effective only for the users listed in the rcpt lines.

milter-greylist -T -u smmsp -p /var/milter-greylist/milter-greylist.sock

You might want to add -v and -D to get more debugging output. The
-w flag is used to choose how long we will refuse a given message.
If you want to check that things work, try 10 seconds with -w10.


 5 Running it for the whole site 
 ===============================

Remove the rcpt lines from /etc/mail/greylist.conf, and run
milter-greylist without the -T option:

milter-greylist -u smmsp -p /var/milter-greylist/milter-greylist.sock

If some of your users don't want greylisting, add a rcpt line for
them in /etc/mail/greylist.conf. Without the -T option, rcpt
lines will prevent greylisting for the corresponding users: every
message will get to them without any delay, including spam.


 6 Working with multiple MX
 ===========================

When running several MX, the client should try each server after
its message gets refused, thus causing greylist entries creation 
on each MX. Things should work, but with two minors problems:

* Some stupid clients don't try all the available MX. In that 
  situation, it could take some time before the message gets in,
  as the client might try a different MX each time and wait for 
  several hours between the retries.

* After a messages goes in, its entry is removed for one MX, 
  but not the others. Stale entries remain until being flushed
  because of a timeout. If a message with the same {IP, from, rcpt}
  gets in on a MX with a stale entry, it will be accepted 
  immediately, and the X-Greylist header will report it had been
  delayed for some time.

In order to address those issues, milter-greylist is now able to
sync the greylist among different MX. This can be configured in
the greylist.conf file, by adding one line per peer MX, just 
like this:
peer 192.0.2.17
peer 192.0.2.18


 7 Things to look at if things get wrong
 =======================================

First, read the milter-greylist(8) man page! :-)

Each message will get a X-Greylist header indicating how long the
message has been delayed. It looks like this:

X-Greylist: Delayed for 00:53:21 by milter-greylist-0.7 (mail.example.net
	    [192.0.2.16]); Wed, 3 Mar 2004 17:01:06 -0000

The file /var/milter-greylist/greylist.db is a dump of the greylist.
It is done every 5 minutes and is used to restore state after
milter-greylist has been restarted. The file contains an entry per
line, with four columns:  IP address, sender e-mail address,
recipient e-mail address, and time when the message will be accepted
(in seconds since 00:00:00 01-01-1970).  Here is an example:

10.0.23.1  <evilspammer@example.com>  <pooruser@example.net>  1078344409


 7 License
 =========

This software is available under a 3 clauses BSD license:

  Copyright (c) 2004 Emmanuel Dreyfus
  All rights reserved.

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:
  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.
  3. All advertising materials mentioning features or use of this software
     must display the following acknowledgement:
         This product includes software developed by Emmanuel Dreyfus

  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  OF THE POSSIBILITY OF SUCH DAMAGE.
