File: greylist.conf.5

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 (657 lines) | stat: -rw-r--r-- 19,744 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
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
.\"
.\" $Id: greylist.conf.5,v 1.43.2.1 2006/09/18 18:04:33 manu Exp $
.\"
.\" 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.
.\"
.TH "greylist.conf" "5" "May 10, 2005" "" ""
.SH NAME
.B greylist.conf
- milter-greylist configuration file
.SH DESCRIPTION
.B greylist.conf 
configures 
.B milter-greylist(8)
operation. The format is simple: each line contains a keyword and 
optional arguments. Any line starting with a # is considered as a comment
and is ignored. Blank lines are ignored as well. Comments at the end of
lines are accepted in some situations, but do not take them as granted.
A statement can be continued on the next line by using a backslash. Anything
after the backslash will be ignored.
.SH WHITELIST
The primary use of 
.B greylist.conf
is to setup 
.B milter-greylist(8)
whitelist. It also offers a handy blacklist feature. 
Access-lists (ACL) are used to do that. ACL enable the administrator 
to specify complex conditions on sender IP, sender DNS address, 
sender e-mail address, and recipient e-mail address. If support for
DNSRBL was built-in, it is even possible to use DNSRBL in ACL.
.PP
An access-list entry starts with the
.I acl
keyword followed by the
.I greylist\fR,
.I whitelist\fR,
or
.I blacklist
keyword, and by any set of the 6 clauses: 
.I addr\fR,
.I domain\fR,
.I from\fR,
.I rcpt\fR,
.I sm_macro\fR,
and (if built with \-\-enable-dnsrbl)
.I dnsrbl\fR.
A message will match an ACL entry when it complies with all of its clauses.
.TP
.I addr
This clause is used to specify a netblock of source IP 
addresses. The syntax is an IP address followed by a slash and a CIDR
netmask. Here is an example:
.IP
  acl whitelist addr 127.0.0.0/8
  acl whitelist addr 192.168.3.0/24
  acl whitelist addr ::1
.IP
If the netmask is ommitted, /32 is assumed for an IPv4 address and
/128 is assumed for an IPv6 address.
.IP
You should at least whitelist localhost (127.0.0.1/8), and if you have
some user clients connecting to the machine, you should whitelist the
addresses they connect from if you don't want them to get error 
messages when sending e-mail.
.TP
.I domain
This clause selects source machines based on their DNS name, performing 
a suffix search.
For instance, this will whitelist any machine in the 
.I example.net
domain:
.IP
  acl whitelist domain example.net
.IP
The name resolution is made by Sendmail, which hands it to 
.B milter-greylist(8)\fR.
As a result, it is impossible to use DNS aliases here. On the other
hand, this will work even if your DNS resolver is not thread-safe.
.TP
.I from
This is used to select sender e-mail addresses. You should not use
that feature, because sender e-mail addresses can be trivially forged.
Example:
.IP
  acl whitelist from postmaster@example.com
.TP
.I rcpt
This is used to select recipient addresses. Example:
.IP
  acl greylist rcpt John.Doe@example.net
.TP
.I sm_macro 
This is used to select a Sendmail macro value. See the section on that
topic for more information.
.TP
.I dnsrbl
This is used to select a DNSRBL. See the section on that topic for
more information.
.PP
The
.I domain\fR,
.I from\fR,
and
.I rcpt
clauses may be used with regular expressions. The regular expressions must be
enclosed by slashes (/). No escaping is available to provide a slash
inside a regular expression, so just do not use it. Regular expressions
follow the format described in 
.B re_format(7)\fR.
Here is an example:
.PP
  acl greylist rcpt /.*@example\\.net/
.PP
When regular expressions are not used, 
.I from\fR,
and
.I rcpt
perform a case insensitive substring match with leading and trailing brackets,
spaces and tabs stripped out. 
.I domain
performs a case insensitive suffix match.
.PP
An ACL entry can also hold various optional parameter used on match: 
.I delay\fR,
.I autowhite\fR,
.I flushaddr\fR,
.I code\fR,
.I ecode\fR,
and
.I msg\fR
.TP
.I delay
Specify the greylisting delay used before the message can be accepted.
This overrides the 
.I greylist
global setting, and it only  makes sense on an 
.I acl greylist
entry. 
.TP
.I autowhite
Specify the autowhitelisting duration for messages matching this ACL.
This overrides the
.I autowhite
global setting, and it only makes sense on an
.I acl greylist
entry. Example:
.IP
  acl greylist rcpt JDoe@example.net delay 15m autowhite 3d
  acl greylist rcpt root@example.net delay 1h autowhite 3d
.TP
.I flushaddr
If a message matches the rule, any entry in the greylist or autowhite
databases matching the sender IP is removed. Used with a DNSRBL blacklist
ACL, it is useful for freeing the database from entries set up by a 
machine which is known to be a spamer. Example:
.IP
  acl blacklist dnsrbl "known-spamers" flushaddr
.TP
.I code
.TP
.I ecode
.TP
.I msg
These 3 values can be used to choose the SMTP code, extended code and
reply message for temporary failures and rejects. Example:
.IP
  acl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
  acl greylist default code "451" ecode "4.7.1"
.TP
None of the last 3 values makes sense for a whitelist entry. 
.PP
Entries in the access-list are evaluated sequentially, so order is
very important. The first matching entry is used to decide if 
a message will be whitelisted or greylisted. A special
.I default
clause can be used in the last ACL entry as a wildcard. 
Here are a few complete ACL examples:
.PP
Example 1:
.nf

acl whitelist from friend@toto.com rcpt grandma@example.com
acl whitelist from other.friend@example.net rcpt grandma@example.com
acl greylist rcpt grandma@example.com
acl whitelist default
.fi
.PP
Example 2:
.nf

acl whitelist addr 193.54.0.0/16 domain friendly.com
acl greylist rcpt user1@atmine.com
acl greylist rcpt user2@atmine.com
acl greylist rcpt user3@atmine.com
acl whitelist default
.fi
.PP
Example 3:
.nf

acl whitelist rcpt /.*@.*otherdomain\\.org/
acl whitelist addr 192.168.42.0/24 rcpt user1@mydomain.org
acl whitelist from friend@example.net rcpt /.*@.*mydomain\\.org/
acl whitelist rcpt user2@mydomain.org
acl greylist rcpt /.*@.*mydomain\\.org/
acl whitelist default
.fi
.SH LISTS
It is often useful to group several users or sender IP addresses in a single
ACL. This can be done with lists. Lists must be first defined and given 
a name before they can be used in ACL entries. Here is an example:
.IP
  list "my users" rcpt { user1@example.com user2@example.com }
  list "local" addr { 192.0.2.0/24 10.0.0.0/8 }

  acl whitelist list "local"
  acl greylist list "my users"
  acl whitelist default

.SH BACKWARD COMPATIBILITY
Previous versions of 
.B milter-greylist(8)
used 
.I addr\fR,
.I domain\fR,
.I from\fR,
and
.I rcpt
lines, without the
.I acl
keyword.
Access-list management is intended to replace them.
These lines are still accepted by
.B milter-greylist(8)\fR,
but they are deprecated.
.B milter-greylist(8)
handles them as access-list entries with a single clause. They are added 
at the head of the access-list so the use of these keywords and 
access-lists may lead to unspecified behaviour. Do not mix them.
.PP
test mode (using
.B \-T\fR)
is also deprecated. Access-list semantics do not depend on this flag.
.SH MX SYNC
Synchronization of the greylist among multiple MX is configured using the 
.I peer 
keyword. List each other MX IP addresses using the 
.I peer 
keyword. Here is
an example:
.PP
  peer 192.0.2.18
  peer 192.0.2.17
.PP
You can list the local machine in the peer statements, it will be ignored.
.PP
By default, milter-greylist will listen on all interfaces using TCP port
5252 or the port number given by service named mxglsync if defined in 
.I /etc/services
or other directory service. This behaviour can be changed by using the
.I syncaddr
keyword. Here are a few examples:
.PP
  syncaddr *
  syncaddr * port 7689
  syncaddr 192.0.2.2 port 9785
  syncaddr 2001:db8::1:c3b5:123
  syncaddr 2001:db8::1:c3b5:123 port 1234
.PP
Using '*' as the address means to bind to all local interfaces' addresses.
Note that if you are not using the default port, all MXs must use the same 
port number. 
.PP
For outbound connections the system is selecting one of the possible adresses.
If you want to use a specific ip you can use:
.PP
  syncsrcaddr 123.456.78.9
.PP
.SH TEXT DUMP
.B milter-greylist(8)
uses a text dump of its database to resume operation after a crash. The dump
is performed at regular time interval, but as it is a heavy operation,
you might want to configure a particular time interval, using the
.I dumpfreq
option. 
.PP
If the
.I dumpfreq
value is too small, it will kill performance. If it is too high, 
you will loose a bigger part of the database on a crash. 
.PP
Set 
.I dumpfreq
to 0 to get a dump on each change (kills performance),
Set it to \-1 to never dump to a file (unsafe as you lose the whole 
greylist on each crash), or give a time value for the delay between dumps.
The time is given in seconds, except if a unit is given: m for minutes, 
h for hours, and d for days.
.PP
You may further improve the performance of the dump operation at the expense
of humanly readable timestamp which by default appears as a comment at 
the end of each line in the dumpfile. You may disable generation of
this comment by specifying
.I dump_no_time_translation
option in the configuration file. This is specifficaly recommended if
your dumpfile grows to 100's of megabytes - it can reduce the time
needed for the dump operation by the order of magnitude!
.SH REPORTING
By default, 
.B milter-greylist(8)
will add a 
.I X-Greylist
header to any message it handles. The header shows what happened to the
message: delayed or not delayed, and why. The following options can be
used in
.B greylist.conf
to alter this behavior:
.TP
.I report none
Never add a 
.I X-Greylist
header.
.TP
.I report delays
Only add a header if the message was delayed.
.TP
.I report nodelays
Add a header if the message was not delayed. The header explains why 
the message was not delayed.
.TP
.I report all
Always add a header. This is the default.
.SH SENDER CALLBACK SYSTEMS
Sender callback systems are another anti-spam measure that attempts to
send a DSN to the sender address before accepting a message. If that
fails, then the sender address is wrong and the message is rejected. 
Such systems usually stop their callback check at the RCPT stage of 
the SMTP transaction. 
.PP
Greylisting temporarily rejects at the RCPT stage, so sender callback
and greylisting love to fight each others. 
.B milter-greylist(8)
proposes a workaround to that problem with the 
.I delayedreject
option. For messages coming from <> (that is, for DSN), it will cause 
the temporary reject to happen at the DATA stage of the SMTP transaction 
instead of the RCPT stage. That way,
.B milter-greylist(8)
will cope much better with sender callback systems. 
.PP
This has a minor drawback (and this is why it is not enabled by default): 
for a multi recipient DSN, whitelisted recipient will not be honoured: 
the message will be delayed for everyone. 
.SH SENDMAIL MACROS
Any sendmail macro can be used as a clause in the access list. You need to 
define a (macro, value) pair using the 
.I sm_macro
keyword before using it.  Here is an example that uses the 
.I {client_resolve}
macro to apply a larger greylisting delay to hosts that have a bogus 
reverse DNS:
.IP
  sm_macro "maybe_forged" "{client_resolve}" "FORGED"

  acl greylist sm_macro "maybe_forged" delay 1h
  acl greylist default 15m
.PP
A regular expression can be used as the macro value. 
It must be surrounded with slashes and not by quotes.
The special value 
.I unset
can also be used to match an unset macro:
.IP
  sm_macro "not_foo" "{foo}" unset
.PP
Note that any Sendmail macro that is not exported using the
.I Milter.macros.envrcpt 
setting of 
.I sendmail.cf
will be seen as unset from milter-greylist.
.SH DNSRBL
DNS Reverse Black List can be used to toggle an ACL. They must be defined
and named before they can be used. Here is an example which uses 
a bigger greylisting delay for hosts caught in the SORBS dynamic pool 
DNRSBL (this will include DSL and cable customers pools, which are well 
known to be massively infected by spamwares):
.IP
  dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10

  acl greylist dnsrbl "SORBS DUN" delay 1h
  acl greylist default delay 15m
.PP
The definition of a DNSRBL starts by the
.I dnsrbl
keyword, followed by the quoted name of the DNSRBL, the DNS domain on 
which addresses should be looked up, and the answer we should consider
as a positive hit.
.PP
DNSRBL support is only available if enabled through the \-\-enable-dnsrbl
config flag. Please make sure
.B milter-greylist(8)
is linked against a thread-safe DNS resolver, otherwise it shall crash.
.SH COMMAND-LINE FLAG EQUIVALENTS
Most 
.B milter-greylist(8)
command-line options have equivalent options that can be set in the 
configuration file. Note that if a command line option is supplied,
it will always override the configuration file.
.PP
If a command-line equivalent keyword is used more than once, the last 
keyword will override the previous ones.
.TP
.I verbose
Enable debug output. This is equivalent to the
.B \-v
flag.
.TP
.I quiet
Do not tell clients how much time remains before their e-mail will
be accepted. This is equivalent to the
.B \-q
flag.
.TP
.I nodetach
Do not fork and go into the background. This is equivalent to the
.B \-D
flag.
.TP
.I noauth
Greylist clients regardless if they succeeded SMTP AUTH. Equivalent to the
.B \-A
flag.
.TP
.I noaccessdb
Normally 
.B milter-greylist(8)
will whitelist a message if 
.B sendmail(8)
defines a ${greylist} macro set to WHITE. This enables complex whitelisting
rules based on the Sendmail access DB. This option inhibits this behavior.
.TP
.I nospf
Greylist clients regardless if they are SPF-compliant. Equivalent to the
.B \-S
flag.
.TP
.I testmode
Enable test mode. Equivalent to the
.B \-T
flag. This option is deprecated.
.TP
.I greylist
The argument sets how much time 
.B milter-greylist(8)
will want the client to wait between the first attempt and the time
the message is accepted. The time is given in seconds, except if a 
unit is given: m for minutes, h for hours, and d for days. 
The 
.I greylist 
keyword is equivalent to the
.B \-w 
option. Here is an example that sets the delay to 45 minutes:
.IP
  greylist 45m
.TP
.I autowhite
This sets the auto-whitelisting duration, equivalent to the
.B \-a
command-line option. As for the 
.I greylist
keyword, 
units can be
supplied. Here is an example for a 3 day long auto-whitelisting:
.IP
  autowhite 3d
.TP
.I pidfile
This causes
.B milter-greylist(8)
to write its PID into the file given as argument, like the 
.B \-P
command line argument does. The path to the file
must be absolute and it must be enclosed in quotes. Here is an example:
.IP
  pidfile "/var/run/greylist.pid"
.TP
.I dumpfile
This chooses the location of the greylist dump file, like the
.B \-d
command line option does. The path must be absolute and enclosed in quotes.
Example:
.IP
  dumpfile "/var/milter-greylist/greylist.db"
.TP
.I subnetmatch
This is equivalent to the 
.B \-L 
command line option. It takes a slash followed by a CIDR mask as argument, 
and it commands the subnet matching feature. Example, for a class C wide
matching:
.IP
  subnetmatch /24
.TP
.I subnetmatch6
This is equivalent to the
.B \-M
command line option. It takes a slash followed by a prefixlen as argument,
and it commands the subnet matching feature. Example, for a subnet wide
matching:
.IP
  subnetmatch6 /64
.TP
.I socket
Like the 
.B \-p
command line option, this keyword is used to specify the socket used
to communicate with
.B sendmail(8)\fR.
It must be enclosed in quotes:
.IP
  socket "/var/milter-greylist/milter-greylist.sock"
.TP
.I user
This keyword should be followed by a quoted user login. Like the 
.B \-u
option, this is used to run
.B milter-greylist(8)
as a non root user.  Here is an example:
.IP
  user "smmsp"
.SH MISCELLANEOUS
These options have no command line equivalent:
.TP
.I timeout
is used to control how long greylist tuples are retained in the database. 
Value is in seconds, except if a suffix is given (m for minutes, h for hours,
d for days). Default is 5 days.
.TP
.I extendedregex
Use extended regular expressions instead of basic regular expressions.
.TP
.I lazyaw
Make auto-whitelist look at just the IP instead of the (sender IP,
sender e-mail address, recipient e-mail address) tuple.
.TP
.I drac db
Tell where the DRAC DB file is. This is only available if DRAC support
was compiled in. Here is an example:
.IP
  drac db "/usr/local/etc/drac.db"
.TP
.I nodrac
Disable DRAC.
.TP
.I logexpired
This option causes greylist entries that expire to be logged via syslog.
This allows you to easily collect the IP addresses and sender names and
use them for blacklisting, SPAM scoring, etc.  Normally, expirations are
only logged if the
.B debug
option is set, but that generates a lot of extra messages.
.PP
The configuration file is reloaded automatically once it is modified when
new e-mail arrives. Most configuration keywords will take effect
immediately, except the following, which will only take effect after 
a restart of 
.B milter-greylist(8)\fR: 
.I nodetach\fR,
.I pidfile\fR,
.I socket\fR,
and 
.I user\fR.
.PP
The 
.I dumpfreq
option can be changed dynamically, but the change will only take effect 
after the next dump.
.SH AUTHORS
Emmanuel Dreyfus <manu@netbsd.org>
.PP
.B milter-greylist
received many contributions from (in alphabetical order):
Aida Shinra,
Gary Aitken,
Joel Bertrand,
Moritz Both,
Attila Bruncsak,
Pavel Cahyna,
Remy Card,
Alexandre Cherif,
Eugene Crosser,
Elrond,
Cyril Guibourg,
Klas Heggemann,
Matthieu Herrb,
Dan Hollis,
Per Holm,
Romain Kang,
Guido Kerkewitz,
Matt Kettler,
Petr Kristof,
Stephane Lentz,
Alexander Lobodzinski,
Ivan F. Martinez,
Martin Paul,
Christian Pelissier,
Fredrik Pettai,
Alexey Popov,
Jeff Rife,
Matthias Scheler,
Jobst Schmalenbach,
Thomas Scheunemann,
Wolfgang Solfrank,
Fabien Tassin,
Hajimu Umemoto,
Lev Walkin, and
Ranko Zivojnovic
.PP    
Thanks to
Helmut Messerer 
and    
Thomas Pfau
for their feedback on the first releases of this software.
.SH SEE ALSO
milter-greylist(8),
sendmail(8), 
syslogd(8).
.TP
Evan Harris's paper:
.I http://projects.puremagic.com/greylisting/
.TP
milter-greylist's web site:
.I http://hcpnet.free.fr/milter-greylist/