File: README

package info (click to toggle)
milter-greylist 3.0-3.1
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 920 kB
  • ctags: 787
  • sloc: ansic: 6,864; sh: 3,205; yacc: 736; lex: 321; makefile: 166
file content (557 lines) | stat: -rw-r--r-- 23,070 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
# $Id: README,v 1.42.2.1 2006/10/06 09:14:39 manu Exp $
###########################################################################

		     ======================================
		       milter-greylist installation notes 
		       $Date: 2006/10/06 09:14:39 $
		     ======================================

		       Emmanuel Dreyfus <manu@netbsd.org>

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

 1 Building and installing milter-greylist 
 2 Configuring sendmail with milter-greylist
 3 Configuring milter-greylist 
 4 Trying it out for a few users 
 5 Running it for the whole site 
 6 Lists and per-ACL settings
 7 Dealing with mail farms
 8 Working with multiple MXs
 9 Using DNSRBL
 10 Building with SPF
 11 Using DRAC
 12 Packaging
 13 Things to look at if things get wrong
 14 Known problems
 15 License

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

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

Build dependencies: 
- flex (AT&T lex cannot build milter-greylist sources)
- yacc or bison
- libmilter (comes with Sendmail)
- Any POSIX threads library (Provided by libc on some systems)

Optional dependencies: 
- libspf2, libspf_alt or libspf.

Before building milter-greylist, it might be wise to view the
configuration options by running:
./configure -help

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-3.0) 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.

Some startup scripts are available: rc-redhat.sh, rc-debian, rc-gentoo.sh,
rc-suse.sh for Linux, rc-bsd.sh for NetBSD and FreeBSD, and rc-solaris.sh
for Solaris. They are not installed by default; you have install the 
startup script manually 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

Note that InputMailFilters and Milter.macros.* options are shared 
with other milters, and the other milters you have set up may 
require additionnal macros. Therefore you need to merge what
milter-greylist needs with what other milters need. If you just
copy the lines proposed in this file, this is likely to break 
other milters setup. In this section we simply list the macros 
milter-greylist require. Your default sendmail.cf is likely to already 
contain the proper Milter.macros.* setup.

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}

If you want to use Sendmail access DB as a whitelisting source, you
will need {greylist} too. milter-greylist will whitelist a message
when the {greylist} macro is defined and set as WHITE.
O Milter.macros.envrcpt={greylist}

Alternatively, you can use the following m4 macro definitions 
if you build sendmail.cf with m4 (contributed by Hubert Ulliac).
Here again, confMILTER_MACROS_* are shared with other milters,
so you need to merge the definitions with what others milters 
require. Just copying the lines below is likely to cause other
milters to malfunction.

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}')
define(`confMILTER_MACROS_ENVRCPT', `{greylist}')

Ivan F. Martinez contributed the milter-greylist.m4 file that includes 
thoses definitions and will take care of adding the macros required by
milter-greylist instead of overwriting what has already been done. This 
should simplify an automatic generation of sendmail.cf.



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

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

acl whitelist addr 127.0.0.0/8
acl whitelist addr 192.0.2.0/24 
acl whitelist addr 10.0.0.0/8

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


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

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

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

Then finish your ACL with the default rule: here, anything that
is not for John.Doe@example.net, webmaster@example.net, or
postmaster@example.net will not get greylisted:

acl whitelist default

Now you can start milter-greylist:

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

If you have trouble with the socket file, check the permissions of
the directory where the socket is located.

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
disables this feature.


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

Remove the "acl greylist rcpt ..." lines from /etc/mail/greylist.conf, 
and replace "acl whitelist default" by

acl greylist default

Now greylisting is enabled for every recipient. If some of your 
users don't want greylisting, add a "acl whitelist rcpt" line for them 
in /etc/mail/greylist.conf. Make sure you put it before 
"acl greylist default": ordering does matter, as the ACL rules are
evaluated on a first match wins basis.

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:

acl greylist rcpt /.*@example\.net/
acl whitelist default


 6 Lists and per-ACL settings
 ============================

It is possible to have per-ACL greylisting and autowhitelisting
settings:

acl greylist rcpt /.*@example\.net/ delay 15m autowhite 3d
acl greylist default delay 30m autowhite 1d

Here, all messages to domain example.net will have a greylisting delay
of 15 minutes and will be autowhitelisted for 3 days, while messages
to other domains will be greylisted for 30 minutes and autowhitelisted
for one day.

milter-greylist is now also able to use lists, which is very useful for
factoring rules:

list "users" rcpt { user1@example.com user2@example.com user3@example.com }
acl greylist list "users"
acl whitelist default

Here message sent to members of the "users" list will be greylisted, while
other messages will not.

Theses two advanced features were added in release 2.1.7 and may not be
fully stable.


 7 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 real fix for the problem: SPF. SPF is a DNS based
mechanism that enables 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 in 
greylisting them.


 8 Working with multiple MXs
 ===========================

When running several MXs, 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 minor problems:

* Some stupid clients don't try all the available MXs. 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 is accepted, 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 an 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 these issues, milter-greylist is now able to
sync the greylist among different MXs. This can be configured in
the greylist.conf file, by adding one line per peer MX,  
like this:
peer 192.0.2.17
peer 192.0.2.18

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


 9 Using DNSRBL
 ==============

milter-greylist can use a DNSRBL to decide wether a host should be
greylisted or whitelisted. For instance, let us say that you cant to
greylist any host appearing in the SORBS dynamic pool list (this include
DSL and cable pools). You would do this:

# if IP a.b.c.d is positive, then nslookup of d.c.b.a.dnsbl.sorbs.net 
# returns 127.0.0.10
dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10
acl greylist dnsrbl "SORBS DUN"

You can combine it with variable greylisting delays so that dynamic hosts
get a greylisting delay of 12 hours while other hosts only get 15 minutes:

dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10
acl greylist dnsrbl "SORBS DUN" delay 12h
acl greylist default delay 15m

This feature was introduced in milter-greylist 2.1.7 and may not be
fully stable. You need the --enable-dnsrbl flag to configure to use 
it. You must link milter-greylist with a thread-safe resolver, else 
the milter will be unstable (see the explanation in the SPF section).

If your resolver is not thread safe, install BIND9, and use 
--with-libbind. If you know your resolver is thread-safe but 
configure tells otherwise (because you lack the res_ninit() function),
then use --with-thread-safe-resolver. 

If you install BIND9, make sure it includes libbind.a, since this is
what milter-greylist needs. libbind.a is not created in BIND9 default
build setup, so you might not have it in a precompiled package. If you 
cannot find a package that contains libbind.a, then you have to rebuild
BIND9 from sources, using the --enable-libbind 
flag to BIND9's configure.


 10 Building with SPF
 ====================

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

If you want to link with an older version of libspf2, you will
need one of the following configure flags:
For older libspf_alt: --with-libspf_alt=DIR
For older libspf2 up to version 1.0: --with-libspf2_10=DIR
For newer libspf2: --with-libspf2=DIR

WARNING: milter-greylist is a multithreaded program. The external
functions 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 from libc or libresolv is used. 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.


 11 Using DRAC
 =============

milter-greylist can be built with DRAC (Dynamic Relay Authorization
Control) support, by giving the --enable-drac flag to configure.
Location of the DRAC DB file can be chosen at build time with
--with-dracdb=PATH, and at runtime with the drac db "PATH"
configuration file option.

If built-in, DRAC can be disabled by the nodrac configuration file
option.

More information on DRAC can be obtained at 
http://mail.cc.umanitoba.ca/drac/
ksh: q: not found
 ============

milter-greylist is available from NetBSD pkgsrc and FreeBSD ports.
A .spec file is included in the distribution to build a RPM for
RedHat Linux. That is achieved by running rpmbuild on milter-greylist
source tarball: rpmbuild -bb  milter-greylist-1.7.3.tgz


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

First, read the milter-greylist(8) and greylist.conf(5) man page! :-)

Second, reread the installation notes at the beginning this file! ;-)

Each message will get an X-Greylist header indicating either how long the
message has been delayed, or that it has been passed through because of
whitelisting. It looks something like this:

For messages which were delayed because of greylisting:
  X-Greylist: Delayed for 00:53:21 by milter-greylist-M.m
      (mail.example.net [192.0.2.16]); Wed, 3 Mar 2004 17:01:06 -0000

For messages which were not delayed because of whitelisting (e.g. they
are whitelisted in the configuration file):
  X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-M.m
      (mail.example.net [192.0.2.16]); Wed, 3 Mar 2004 17:01:06 -0000
  X-Greylist: Sender DNS name whitelisted, not delayed by milter-greylist-M.m
      (mail.example.net [192.0.2.16]); Wed, 3 Mar 2004 17:01:06 -0000

For messages which were not delayed because of auto-whitelisting from a
previously resent and accepted message:
  X-Greylist: IP, sender and recipient auto-whitelisted, not delayed by
      milter-greylist-M.m (mail.example.net [192.0.2.16]); Wed, 3 Mar 2004
      17:01:06 -0000

where M.m is the major and minor version number of milter-greylist.

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.

Examining the tail of this file may reveal problems with domains which
use multiple MX servers or whose mail is actually served by another site.

 14 Known problems
 =================

If milter-greylist terminates during its operation, first check your
system limits with ulimit (sh/ksh/bash) or limit (csh/tcsh). As it stores 
its complete database in memory, milter-greylist can eat a large amount of 
memory on a busy mail server. Each incoming connection uses a socket, so
file descriptors can easily be exhausted too. Any resource shortage will
cause milter-greylist to quit. This is not specific to milter-greylist; 
all milters do that.

When SPF support is compiled in, if milter-greylist hangs and/or crashes
regularly, check that you linked your SPF library with a thread-safe
resolver. This can be done by running nm(1) on milter-greylist: if
nres_init is referenced, you are fine.  If res_init is referenced, you 
are probably at risk.

When DNSRBL support is compiled in, you also need to make sure that
milter-greylist itself is linked with a thread-safe resolver.

On Solaris 2.8, milter-greylist may grow out of memory rather quickly 
due to some bugs in the pthread nsl and socket libraries. It is strongly 
recommended that you install the latest revision of patch 108993 (sparc) 
or 108994 (x86). Solaris 9 and later do not seem to be affected.
Solaris patches are available from <http://sunsolve.sun.com/>

On Solaris, and on some IRIX releases, the file descriptor field 
of <stdio.h>'s FILE structure is a char, and thus no more than 255 
streams can be open at once. This will cause failures in milter-greylist 
when handling a large number of connections. If you are not sure whether 
your system is affected or not, check your system headers for the FILE 
definition. On Solaris, the problem only exists with the 32 bit ABI, 
so rebuilding milter-greylist with a 64 bit compiler will fix the problem.

On IRIX, milter-greylist has to be compiled with the same ABI as
libmilter. If libmilter was built with the MIPSpro compiler,
milter-greylist should be too, because of binary incompatibility
between gcc and the MIPSpro compilers. This can be achieved by invoking
configure with the CC environment variable set to cc. This
incompatibility may be fixed in gcc 3.4.


 15 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 clause 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.