# $Id: README,v 1.22 2004/06/17 20:03:25 manu Exp $
###########################################################################

		     ======================================
		       milter-greylist installation notes 
		       $Date: 2004/06/17 20:03:25 $
		     ======================================

		       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 
 =========================================

Build dependencies: 
- lex or flex
- yacc or bison
- libmilter (comes with Sendmail)
- Any POSIX threads library (Provided by libc on some systems)

Optionnal dependencies: 
- libspf_alt or libspf.

To build 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.

A Makefile is supplied in the distribution in case you run into real 
trouble with configure and are unable to get it generating a Makefile
suited to your system. Of course this Makefile is not likely to work 
on your system (it is configured for NetBSD-1.6.x) and it will probably
need manual tweaks.

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.

Two startup scripts are available: rc-linux.sh for Linux and rc-bsd.sh
for NetBSD and FreeBSD. They are not installed by default, you have
install the startup script by hand if you want to use one.


 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}
O Milter.macros.envfrom=i

If you want to bypass greylisting for users that succeeded SMTP AUTH, 
You also need {auth_authen} in Milter.macros.envfrom:
O Milter.macros.envfrom=i, {auth_authen}

If you want to bybass greylisting for users that use STARTTLS with 
a client certificate, you also need {verify} and {cert_subject}
in Milter.macros.helo: 
O Milter.macros.helo={verify},{cert_subject}

Alternatively, you can use the following m4 macros definitions 
if you bouild sendmail.cf with m4 (contributed by Hubert Ulliac):

INPUT_MAIL_FILTER(`greylist',
`S=local:/var/milter-greylist/milter-greylist.sock')
define(`confMILTER_MACROS_CONNECT', `j, {if_addr}')
define(`confMILTER_MACROS_HELO', `{verify}, {cert_subject}')
define(`confMILTER_MACROS_ENVFROM', `i, {auth_authen}')


 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.

The -a option controls auto-whitelisting. Once a (sender IP, sender e-mail,
recipient e-mail) tuple has been accepted, it is marked autowhitelisted,
and similar tuples will be accepted with no retry for one day. Using -a0
disable this feature.


 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.

If your mail server handles several domains and you want to enable
milter-greylist for a whole domain but not for everyone, this is 
possible: just use a regular expression and run in testmode:

rcpt /.*@example\.net/


 6 Dealing with mail farms
 =========================

Some Internet service provider such as Hotmail feature mail farms,
where several different machines are able to resend an e-mail. The
message is likely to be resent from different IP addresses, and this
is likely to break with milter-greylist.

The -L option is an ad-hoc hack for this problem. It provides
milter-greylist a CIDR mask to use when comparing IPv4 addresses. 
With -L24, the match mask is 255.255.255.0, and any address in a 
class C network is considered the same.

There is also a right fix for the problem: SPF. SPF is a DNS based
mechanism that enable domains to publish the identity of machines
allowed to send mail on behalf of the domain. milter-greylist knows 
how to use SPF through libspf or libspf_alt. See section 8 of this
document: Building with SPF

Another workaround is simply to whitelist the netblocks allocated to 
mail farms. As any machine in theses IP address ranges are real SMTP 
servers that will always resend their messages, there is no point into 
greylisting them.


 7 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

If you have firewalls between your MX? you should enable TCP 
connections in both directions between random unprivileged 
source ports and destination port 5252.


 8 Building with SPF
 ===================

milter-greylist can use either libspf or libspf_alt to perform SPF
checks. Use --with-libspf=DIR or --with-libspf_alt=DIR to enable
this feature. DIR must be the base directory where include and lib
directories containing the headers and library can be found. 

WARNING: milter-greylist is a multithreaded program. The external
function it uses must be thread-safe. While libspf and libspf_alt
contain only thread-safe code, they use the DNS resolver. By default,
the DNS resolver is used from libc or libresolv. If this resolver
is not thread-safe, milter-greylist with SPF will quickly crash or
hang.

You need to make sure that libspf or libspf_alt are linked against
a thread-safe DNS resolver. For instance, NetBSD-1.6.2 libc-supplied
resolver is from BIND 4, and it is not thread safe. In order to get
a stable milter-greylist, you need to link with a BIND 8.2 or higher
resolver.

When building with libspf_alt-0.4, you might encounter problems if
libbind is only available as a static library. It seems to be the
default with BIND 8, which causes troubles. BIND 9 is fine.


 9 Working with IPv6
 ===================

milter-greylist does not know about IPv6 yet. This is not a real problem
since spamming from IPv6 addresses is not a real-life issue yet.

Any mail sent from a non-IPv4 address (this include message generated
locally and mail sent from IPv6 addresses), will be whitelisted. 


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

First, read the milter-greylist(8) and greylist.conf(5) 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 on each change 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

Additionally, you can find a human-readable time in the comment at the
end of each line.

At the end of the file, you will find entries with the keyword AUTO
at the end of the line. Theses are auto-whitelisted tuples. The date
tells you when the entry will expire.


 11 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.

If you run on a non-BSD system, two files with different licenses might
be required for building or installing. The configure script has a
different license as well.

install-sh has a MIT BSD-like license:
  Copyright 1991 by the Massachusetts Institute of Technology
 
  Permission to use, copy, modify, distribute, and sell this software and its
  documentation for any purpose is hereby granted without fee, provided that
  the above copyright notice appear in all copies and that both that
  copyright notice and this permission notice appear in supporting
  documentation, and that the name of M.I.T. not be used in advertising or
  publicity pertaining to distribution of the software without specific,
  written prior permission.  M.I.T. makes no representations about the
  suitability of this software for any purpose.  It is provided "as is"
  without express or implied warranty.


queue.h has a 4 clauses BSD license:
  Copyright (c) 1991, 1993
 	The Regents of the University of California.  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 the University of
 	California, Berkeley and its contributors.
  4. Neither the name of the University nor the names of its contributors
     may be used to endorse or promote products derived from this software
     without specific prior written permission.
 
  THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.


The configure script has the following license:
  Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002
  Free Software Foundation, Inc.
  This configure script is free software; the Free Software Foundation
  gives unlimited permission to copy, distribute and modify it.

