1greylist.conf(5) greylist.conf(5)
2
6 greylist.conf - milter-greylist configuration file
7
9 greylist.conf configures milter-greylist(8) operation. The format is
10 simple: each line contains a keyword and optional arguments. Any line
11 starting with a # is considered as a comment and is ignored. Blank
12 lines are ignored as well. Comments at the end of lines are accepted in
13 some situations, but do not take them as granted. A statement can be
14 continued on the next line by using a backslash. Anything after the
15 backslash will be ignored.
16
18 The primary use of greylist.conf is to setup milter-greylist(8)
19 whitelist. It also offers a handy blacklist feature. Access-lists
20 (ACL) are used to do that. ACL enable the administrator to specify com‐
21 plex conditions on sender IP, sender DNS address, sender e-mail
22 address, and recipient e-mail address. If support for DNSRBL was built-
23 in, it is even possible to use DNSRBL in ACL.
24 An access-list entry starts with the acl keyword followed by the
26 greylist, whitelist, or blacklist keyword, and by any set of the 6
27 clauses: addr, domain, from, rcpt, sm_macro, and (if built with
28 --enable-dnsrbl) dnsrbl. A message will match an ACL entry when it
29 complies with all of its clauses.
30 addr This clause is used to specify a netblock of source IP
32 addresses. The syntax is an IP address followed by a slash and a
33 CIDR netmask. Here is an example:
34 acl whitelist addr 127.0.0.0/8
36 acl whitelist addr 192.168.3.0/24
37 acl whitelist addr ::1
38 If the netmask is ommitted, /32 is assumed for an IPv4 address
40 and /128 is assumed for an IPv6 address.
41 You should at least whitelist localhost (127.0.0.1/8), and if
43 you have some user clients connecting to the machine, you should
44 whitelist the addresses they connect from if you don't want them
45 to get error messages when sending e-mail.
46 domain This clause selects source machines based on their DNS name,
48 performing a suffix search. For instance, this will whitelist
49 any machine in the example.net domain:
50 acl whitelist domain example.net
52 The name resolution is made by Sendmail, which hands it to mil‐
54 ter-greylist(8). As a result, it is impossible to use DNS
55 aliases here. On the other hand, this will work even if your DNS
56 resolver is not thread-safe.
57 from This is used to select sender e-mail addresses. You should not
59 use that feature, because sender e-mail addresses can be triv‐
60 ially forged. Example:
61 acl whitelist from postmaster@example.com
63 rcpt This is used to select recipient addresses. Example:
65 acl greylist rcpt John.Doe@example.net
67 sm_macro
69 This is used to select a Sendmail macro value. See the section
70 on that topic for more information.
71 dnsrbl This is used to select a DNSRBL. See the section on that topic
73 for more information.
74 The domain, from, and rcpt clauses may be used with regular expres‐
76 sions. The regular expressions must be enclosed by slashes (/). No
77 escaping is available to provide a slash inside a regular expression,
78 so just do not use it. Regular expressions follow the format described
79 in re_format(7). Here is an example:
80 acl greylist rcpt /.*@example\.net/
82 When regular expressions are not used, from, and rcpt perform a case
84 insensitive substring match with leading and trailing brackets, spaces
85 and tabs stripped out. domain performs a case insensitive suffix
86 match.
87 An ACL entry can also hold various optional parameter used on match:
89 delay, autowhite, flushaddr, code, ecode, and msg
90 delay Specify the greylisting delay used before the message can be
92 accepted. This overrides the greylist global setting, and it
93 only makes sense on an acl greylist entry.
94 autowhite
96 Specify the autowhitelisting duration for messages matching this
97 ACL. This overrides the autowhite global setting, and it only
98 makes sense on an acl greylist entry. Example:
99 acl greylist rcpt JDoe@example.net delay 15m autowhite 3d
101 acl greylist rcpt root@example.net delay 1h autowhite 3d
102 flushaddr
104 If a message matches the rule, any entry in the greylist or
105 autowhite databases matching the sender IP is removed. Used with
106 a DNSRBL blacklist ACL, it is useful for freeing the database
107 from entries set up by a machine which is known to be a spamer.
108 Example:
109 acl blacklist dnsrbl "known-spamers" flushaddr
111 code
113 ecode
115 msg These 3 values can be used to choose the SMTP code, extended
117 code and reply message for temporary failures and rejects. Exam‐
118 ple:
119 acl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
121 acl greylist default code "451" ecode "4.7.1"
122 None of the last 3 values makes sense for a whitelist entry.
124 Entries in the access-list are evaluated sequentially, so order is very
126 important. The first matching entry is used to decide if a message will
127 be whitelisted or greylisted. A special default clause can be used in
128 the last ACL entry as a wildcard. Here are a few complete ACL exam‐
129 ples:
130 Example 1:
132 acl whitelist from friend@toto.com rcpt grandma@example.com
134 acl whitelist from other.friend@example.net rcpt grandma@example.com
135 acl greylist rcpt grandma@example.com
136 acl whitelist default
137 Example 2:
139 acl whitelist addr 193.54.0.0/16 domain friendly.com
141 acl greylist rcpt user1@atmine.com
142 acl greylist rcpt user2@atmine.com
143 acl greylist rcpt user3@atmine.com
144 acl whitelist default
145 Example 3:
147 acl whitelist rcpt /.*@.*otherdomain\.org/
149 acl whitelist addr 192.168.42.0/24 rcpt user1@mydomain.org
150 acl whitelist from friend@example.net rcpt /.*@.*mydomain\.org/
151 acl whitelist rcpt user2@mydomain.org
152 acl greylist rcpt /.*@.*mydomain\.org/
153 acl whitelist default
154
156 It is often useful to group several users or sender IP addresses in a
157 single ACL. This can be done with lists. Lists must be first defined
158 and given a name before they can be used in ACL entries. Here is an
159 example:
160 list "my users" rcpt { user1@example.com user2@example.com }
162 list "local" addr { 192.0.2.0/24 10.0.0.0/8 }
163 acl whitelist list "local"
165 acl greylist list "my users"
166 acl whitelist default
167
170 Previous versions of milter-greylist(8) used addr, domain, from, and
171 rcpt lines, without the acl keyword. Access-list management is
172 intended to replace them. These lines are still accepted by milter-
173 greylist(8), but they are deprecated. milter-greylist(8) handles them
174 as access-list entries with a single clause. They are added at the head
175 of the access-list so the use of these keywords and access-lists may
176 lead to unspecified behaviour. Do not mix them.
177 test mode (using -T) is also deprecated. Access-list semantics do not
179 depend on this flag.
180
182 Synchronization of the greylist among multiple MX is configured using
183 the peer keyword. List each other MX IP addresses using the peer key‐
184 word. Here is an example:
185 peer 192.0.2.18
187 peer 192.0.2.17
188 You can list the local machine in the peer statements, it will be
190 ignored.
191 By default, milter-greylist will listen on all interfaces using TCP
193 port 5252 or the port number given by service named mxglsync if defined
194 in /etc/services or other directory service. This behaviour can be
195 changed by using the syncaddr keyword. Here are a few examples:
196 syncaddr *
198 syncaddr * port 7689
199 syncaddr 192.0.2.2 port 9785
200 syncaddr 2001:db8::1:c3b5:123
201 syncaddr 2001:db8::1:c3b5:123 port 1234
202 Using '*' as the address means to bind to all local interfaces'
204 addresses. Note that if you are not using the default port, all MXs
205 must use the same port number.
206 For outbound connections the system is selecting one of the possible
208 adresses. If you want to use a specific ip you can use:
209 syncsrcaddr 123.456.78.9
211
213 milter-greylist(8) uses a text dump of its database to resume operation
214 after a crash. The dump is performed at regular time interval, but as
215 it is a heavy operation, you might want to configure a particular time
216 interval, using the dumpfreq option.
217 If the dumpfreq value is too small, it will kill performance. If it is
219 too high, you will loose a bigger part of the database on a crash.
220 Set dumpfreq to 0 to get a dump on each change (kills performance), Set
222 it to -1 to never dump to a file (unsafe as you lose the whole greylist
223 on each crash), or give a time value for the delay between dumps. The
224 time is given in seconds, except if a unit is given: m for minutes, h
225 for hours, and d for days.
226 You may further improve the performance of the dump operation at the
228 expense of humanly readable timestamp which by default appears as a
229 comment at the end of each line in the dumpfile. You may disable gener‐
230 ation of this comment by specifying dump_no_time_translation option in
231 the configuration file. This is specifficaly recommended if your dump‐
232 file grows to 100's of megabytes - it can reduce the time needed for
233 the dump operation by the order of magnitude!
234
236 By default, milter-greylist(8) will add a X-Greylist header to any mes‐
237 sage it handles. The header shows what happened to the message: delayed
238 or not delayed, and why. The following options can be used in
239 greylist.conf to alter this behavior:
240 report none
242 Never add a X-Greylist header.
243 report delays
245 Only add a header if the message was delayed.
246 report nodelays
248 Add a header if the message was not delayed. The header explains
249 why the message was not delayed.
250 report all
252 Always add a header. This is the default.
253
255 Sender callback systems are another anti-spam measure that attempts to
256 send a DSN to the sender address before accepting a message. If that
257 fails, then the sender address is wrong and the message is rejected.
258 Such systems usually stop their callback check at the RCPT stage of the
259 SMTP transaction.
260 Greylisting temporarily rejects at the RCPT stage, so sender callback
262 and greylisting love to fight each others. milter-greylist(8) proposes
263 a workaround to that problem with the delayedreject option. For mes‐
264 sages coming from <> (that is, for DSN), it will cause the temporary
265 reject to happen at the DATA stage of the SMTP transaction instead of
266 the RCPT stage. That way, milter-greylist(8) will cope much better with
267 sender callback systems.
268 This has a minor drawback (and this is why it is not enabled by
270 default): for a multi recipient DSN, whitelisted recipient will not be
271 honoured: the message will be delayed for everyone.
272
274 Any sendmail macro can be used as a clause in the access list. You need
275 to define a (macro, value) pair using the sm_macro keyword before using
276 it. Here is an example that uses the {client_resolve} macro to apply a
277 larger greylisting delay to hosts that have a bogus reverse DNS:
278 sm_macro "maybe_forged" "{client_resolve}" "FORGED"
280 acl greylist sm_macro "maybe_forged" delay 1h
282 acl greylist default 15m
283 A regular expression can be used as the macro value. It must be sur‐
285 rounded with slashes and not by quotes. The special value unset can
286 also be used to match an unset macro:
287 sm_macro "not_foo" "{foo}" unset
289 Note that any Sendmail macro that is not exported using the Mil‐
291 ter.macros.envrcpt setting of sendmail.cf will be seen as unset from
292 milter-greylist.
293
295 DNS Reverse Black List can be used to toggle an ACL. They must be
296 defined and named before they can be used. Here is an example which
297 uses a bigger greylisting delay for hosts caught in the SORBS dynamic
298 pool DNRSBL (this will include DSL and cable customers pools, which are
299 well known to be massively infected by spamwares):
300 dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10
302 acl greylist dnsrbl "SORBS DUN" delay 1h
304 acl greylist default delay 15m
305 The definition of a DNSRBL starts by the dnsrbl keyword, followed by
307 the quoted name of the DNSRBL, the DNS domain on which addresses should
308 be looked up, and the answer we should consider as a positive hit.
309 DNSRBL support is only available if enabled through the --enable-dnsrbl
311 config flag. Please make sure milter-greylist(8) is linked against a
312 thread-safe DNS resolver, otherwise it shall crash.
313
315 Most milter-greylist(8) command-line options have equivalent options
316 that can be set in the configuration file. Note that if a command line
317 option is supplied, it will always override the configuration file.
318 If a command-line equivalent keyword is used more than once, the last
320 keyword will override the previous ones.
321 verbose
323 Enable debug output. This is equivalent to the -v flag.
324 quiet Do not tell clients how much time remains before their e-mail
326 will be accepted. This is equivalent to the -q flag.
327 nodetach
329 Do not fork and go into the background. This is equivalent to
330 the -D flag.
331 noauth Greylist clients regardless if they succeeded SMTP AUTH. Equiva‐
333 lent to the -A flag.
334 noaccessdb
336 Normally milter-greylist(8) will whitelist a message if send‐
337 mail(8) defines a ${greylist} macro set to WHITE. This enables
338 complex whitelisting rules based on the Sendmail access DB. This
339 option inhibits this behavior.
340 nospf Greylist clients regardless if they are SPF-compliant. Equiva‐
342 lent to the -S flag.
343 testmode
345 Enable test mode. Equivalent to the -T flag. This option is dep‐
346 recated.
347 greylist
349 The argument sets how much time milter-greylist(8) will want the
350 client to wait between the first attempt and the time the mes‐
351 sage is accepted. The time is given in seconds, except if a unit
352 is given: m for minutes, h for hours, and d for days. The
353 greylist keyword is equivalent to the -w option. Here is an
354 example that sets the delay to 45 minutes:
355 greylist 45m
357 autowhite
359 This sets the auto-whitelisting duration, equivalent to the -a
360 command-line option. As for the greylist keyword, units can be
361 supplied. Here is an example for a 3 day long auto-whitelisting:
362 autowhite 3d
364 pidfile
366 This causes milter-greylist(8) to write its PID into the file
367 given as argument, like the -P command line argument does. The
368 path to the file must be absolute and it must be enclosed in
369 quotes. Here is an example:
370 pidfile "/var/run/greylist.pid"
372 dumpfile
374 This chooses the location of the greylist dump file, like the -d
375 command line option does. The path must be absolute and enclosed
376 in quotes. Example:
377 dumpfile "/var/lib/milter-greylist/db/greylist.db"
379 subnetmatch
381 This is equivalent to the -L command line option. It takes a
382 slash followed by a CIDR mask as argument, and it commands the
383 subnet matching feature. Example, for a class C wide matching:
384 subnetmatch /24
386 subnetmatch6
388 This is equivalent to the -M command line option. It takes a
389 slash followed by a prefixlen as argument, and it commands the
390 subnet matching feature. Example, for a subnet wide matching:
391 subnetmatch6 /64
393 socket Like the -p command line option, this keyword is used to specify
395 the socket used to communicate with sendmail(8). It must be
396 enclosed in quotes:
397 socket "/var/run/milter-greylist/milter-greylist.sock"
399 user This keyword should be followed by a quoted user login. Like the
401 -u option, this is used to run milter-greylist(8) as a non root
402 user. Here is an example:
403 user "smmsp"
405
407 These options have no command line equivalent:
408 timeout
410 is used to control how long greylist tuples are retained in the
411 database. Value is in seconds, except if a suffix is given (m
412 for minutes, h for hours, d for days). Default is 5 days.
413 extendedregex
415 Use extended regular expressions instead of basic regular
416 expressions.
417 lazyaw Make auto-whitelist look at just the IP instead of the (sender
419 IP, sender e-mail address, recipient e-mail address) tuple.
420 drac db
422 Tell where the DRAC DB file is. This is only available if DRAC
423 support was compiled in. Here is an example:
424 drac db "/usr/local/etc/drac.db"
426 nodrac Disable DRAC.
428 logexpired
430 This option causes greylist entries that expire to be logged via
431 syslog. This allows you to easily collect the IP addresses and
432 sender names and use them for blacklisting, SPAM scoring, etc.
433 Normally, expirations are only logged if the debug option is
434 set, but that generates a lot of extra messages.
435 The configuration file is reloaded automatically once it is modified
437 when new e-mail arrives. Most configuration keywords will take effect
438 immediately, except the following, which will only take effect after a
439 restart of milter-greylist(8): nodetach, pidfile, socket, and user.
440 The dumpfreq option can be changed dynamically, but the change will
442 only take effect after the next dump.
443
445 Emmanuel Dreyfus <manu@netbsd.org>
446 milter-greylist received many contributions from (in alphabetical
448 order): Aida Shinra, Gary Aitken, Joel Bertrand, Moritz Both, Attila
449 Bruncsak, Pavel Cahyna, Remy Card, Alexandre Cherif, Eugene Crosser,
450 Elrond, Cyril Guibourg, Klas Heggemann, Matthieu Herrb, Dan Hollis, Per
451 Holm, Romain Kang, Guido Kerkewitz, Matt Kettler, Petr Kristof,
452 Stephane Lentz, Alexander Lobodzinski, Ivan F. Martinez, Martin Paul,
453 Christian Pelissier, Fredrik Pettai, Alexey Popov, Jeff Rife, Matthias
454 Scheler, Jobst Schmalenbach, Thomas Scheunemann, Wolfgang Solfrank,
455 Fabien Tassin, Hajimu Umemoto, Lev Walkin, and Ranko Zivojnovic
456 Thanks to Helmut Messerer and Thomas Pfau for their feedback on the
458 first releases of this software.
459
461 milter-greylist(8), sendmail(8), syslogd(8).
462 Evan Harris's paper:
464 http://projects.puremagic.com/greylisting/
465 milter-greylist's web site:
467 http://hcpnet.free.fr/milter-greylist/
468 May 10, 2005 greylist.conf(5)