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 racl keyword followed by an
26 optional id quoted string, then the greylist, whitelist, blacklist, or
27 continue keyword, and by any set of the following clauses: addr,
28 domain, from, rawfrom, rcpt, rcptcount, helo, sm_macro, time, auth,
29 tls, spf (if build with SPF support), geoip (if build with GeoIP sup‐
30 port), p0f (if build with p0f support), ldapcheck (if build with
31 --with-openldap), urlcheck (if built with --with-libcurl), dnsrbl (if
32 built with --enable-dnsrbl), and nsupdate (if supported by the DNS
33 resolver). A message will match an ACL entry when it complies with all
34 of its clauses.
35 The greylist, whitelist, and blacklist keywords will cause the message
37 to be respectively greylisted, accepted or rejected if all ACL clauses
38 match, and ACL evaluation is terminated there. If an ACL with continue
39 keyword does match, nothing is decided and next ACL are evaluated.
40 Clauses can be negated, by prefixing them by the not keyword. Here is
42 the detail of all possible clauses.
43 addr This clause is used to specify a netblock of source IP
45 addresses. The syntax is an IP address followed by a slash and a
46 CIDR netmask. Here is an example:
47 racl whitelist addr 127.0.0.0/8
49 racl whitelist addr 192.168.3.0/24
50 racl whitelist addr ::1
51 If the netmask is omitted, /32 is assumed for an IPv4 address
53 and /128 is assumed for an IPv6 address.
54 You should at least whitelist localhost (127.0.0.1/8), and if
56 you have some user clients connecting to the machine, you should
57 whitelist the addresses they connect from if you don't want them
58 to get error messages when sending e-mail.
59 domain This clause selects source machines based on their DNS name,
61 performing a suffix search. For instance, this will whitelist
62 any machine in the example.net domain:
63 racl whitelist domain example.net
65 Suffix search matching means, for example, that gle.com will
67 match google.com. If you want domain names to match on subdomain
68 boundaries (e.g. gle.com will match mail.gle.com and gle.com
69 but not google.com) then enable domainexact
70 The name resolution is made by Sendmail, which hands it to milter-
72 greylist(8). As a result, it is impossible to use DNS aliases here. On
73 the other hand, this will work even if your DNS resolver is not thread-
74 safe.
75 from This is used to select sender e-mail addresses You should not
77 use that feature, because sender e-mail addresses can be triv‐
78 ially forged.
79 Please note that the sender e-mail is cleared from spaces and
81 anything leading an equal (=) sign so that mailing-lists return-
82 address with unique return paths can still match. If you need
83 unedited sender address, use a rawfrom clause.
84 Here is an example:
86 racl whitelist from postmaster@example.com
88 rawfrom
90 Same as from but the sender e-mail address is not modified to
91 stip anything. rcpt This is used to select recipient addresses.
92 Example:
93 racl greylist rcpt John.Doe@example.net
95 rcptcount
97 Followed by an operator and a recipient count, this is used to
98 select the amount of recipients. Example:
99 racl blacklist rcptcount >= 25 msg "No more than 25 recipi‐
101 ents, please"
102 helo Followed by a quoted string or a regular expression, this can be
104 used to filter on the HELO string.
105 sm_macro
107 This is used to select a Sendmail macro value. See the section
108 on that topic for more information.
109 time This is used to specify a time set. It should be followed by a
111 quoted string of crontab(5)-like time specification. Here is an
112 example that whitelists mail addressed to a single recipient
113 during office hours (from 8:00 to 16:59 from monday to friday):
114 racl whitelist time "* 8-16 * * 1-5" rcpt info@example.net
116 geoip This is used to specify a country, as reported by GeoIP. The
118 country code must be upper case, and is only available if mil‐
119 ter-greylist was built with GeoIP support. Special country code
120 ZZ is used when the country cannot be determined (this happens
121 for private addresses, for instance). The geoipdb statement can
122 be used to specify the location of GeoIP database. geoipv6db
123 statement can be used to specify the location of GeoIPv6 data‐
124 base. geoip2db statement can be used to specify the location of
125 GeoIP2 (maxminddb) database.
126 p0f This is used to match against the remote system OS fingerprint
128 genre and detail,obtained from p0f. It is only available if mil‐
129 ter-greylist was built with p0f support. p0f clauses can be
130 used with a quoted string for case-insensitive substring match,
131 or against regular expressions. The p0fsock statement can be
132 used to specify the location of the p0f socket.
133 auth This is used to select a user that succeeded SMTP AUTH. In order
135 to select any user that succeeds SMTP AUTH, you can use a regu‐
136 lar expression matching, like below;
137 racl whitelist auth /.*/
139 Using such a clause automatically disable global STARTTLS and
141 SMTP AUTH whitelisting, like if the noauth keyword would have
142 been used.
143 tls This is used to select the distinguished name (DN) of a user
145 that succeeded STARTTLS. Using such a clause automatically dis‐
146 able global STARTTLS and SMTP AUTH whitelisting, like if the
147 noauth keyword would have been used.
148 spf This is used to test SPF status. Possible values are pass, soft‐
150 fail, fail, neutral, unknown, error, none, and self. The first
151 seven values are plain SPF validation status. The self value is
152 a special test that checks the server's local IP address against
153 the sender's SPF record. If that test validates, odds are good
154 that the sender SPF record is wide open, and this is hint that
155 SPF should not be trusted.
156 In order to use spf self, Postfix users must specify the local
158 address in the configuration file, using the localaddr option.
159 Absence of any value after the spf keyword is a synonym for spf
161 pass. This is present for backward compatibility.
162 The spf clause is only available if SPF support was compiled in.
164 Using it will disable global SPF whitelisting, like if the nospf
165 keyword would have been used.
166 ldapcheck
168 This is used to query an LDAP directory. See the section on
169 that topic for more information.
170 urlcheck
172 This is used to query an external configuration source through
173 an URL. See the section on that topic for more information.
174 dnsrbl This is used to select a DNSRBL. See the section on that topic
176 for more information.
177 nsupdate
179 This always-matching clause performs a DNS update, see the sec‐
180 tion on that topic for more information.
181 The domain, from, and rcpt clauses may be used with regular expres‐
183 sions. The regular expressions must be enclosed by slashes (/). No
184 escaping is available to provide a slash inside a regular expression,
185 so just do not use it. Regular expressions follow the format described
186 in re_format(7). Here is an example:
187 racl greylist rcpt /@example\.net$/
189 When regular expressions are not used, from, and rcpt perform a case
191 insensitive substring match with leading and trailing brackets, spaces
192 and tabs stripped out. domain performs a case insensitive suffix
193 match. This means, for example, that gle.com will match google.com. If
194 you want domain names to match on subdomain boundaries (e.g. gle.com
195 will match mail.gle.com and gle.com but not google.com) then enable
196 domainexact
197 An ACL entry can also hold various optional parameter used on match:
199 delay, autowhite, flushaddr, nolog, code, ecode, report, maxpeek,
200 addheader, addfooter, and msg
201 delay Specify the greylisting delay used before the message can be
203 accepted. This overrides the greylist global setting, and it
204 only makes sense on an racl greylist entry.
205 autowhite
207 Specify the autowhitelisting duration for messages matching this
208 ACL. This overrides the autowhite global setting, and it only
209 makes sense on an racl greylist entry. Example:
210 racl greylist rcpt JDoe@example.net delay 15m autowhite 3d
212 racl greylist rcpt root@example.net delay 1h autowhite 3d
213 flushaddr
215 If a message matches the rule, any entry in the greylist or
216 autowhite databases matching the sender IP is removed. Used with
217 a DNSRBL blacklist ACL, it is useful for freeing the database
218 from entries set up by a machine which is known to be a spammer.
219 Example:
220 racl blacklist dnsrbl "known-spammer" flushaddr
222 nolog Do not generate syslog message if this rule matches. Example:
224 racl whitelist default nolog
226 code
228 ecode
230 msg These 3 values can be used to choose the SMTP code, extended
232 code and reply message for temporary failures and rejects. Exam‐
233 ple:
234 racl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
236 racl greylist default code "451" ecode "4.7.1"
237 The msg strings accepts format string substitution as documented
239 in the FORMAT STRINGS section. For instance, %A gets substituted
240 by the ACL line number.
241 None of the last 3 values makes sense for a whitelist entry.
243 report This value overrides the text displayed in the X-Greylist
245 header, for messages that milter-greylist(8) lets pass through,
246 either because they are whitelisted, or because they passed
247 greylisting (see REPORTING). This string can be substituted as
248 documented in the FORMAT STRINGS section.
249 maxpeek
251 This parameter only makes sense in a RCPT-stage ACL. It over‐
252 rides the global maxpeek setting for DATA-stage handling of the
253 message. It has no effect if global maxpeek is set to 0.
254 addheader
256 This quoted string is a RFC822 header that gets added to the
257 message. Format string substitution is supported. No check is
258 done for header length standard compliance, so make sure the
259 substituted string is shorter than 2048 characters. Headers are
260 appended to the bottom, unless an optionnal comma-separated pos‐
261 itive index is specified after the quoted string; in this case
262 the header will be inserted at this index point from the top.
263 Here is an example:
264 racl continue addheader "X-Personnal-Header: Hello world!",1
265 addfooter
267 Append a footer to the message. Usual escape sequences such as
268 \n can be used to get special characters. The string is subject
269 to format string expantion as described in the FORMAT STRINGS
270 section. The footer will not be append if milter-greylist was
271 not able to capture the whole message, therefore maxpeek must be
272 set approriately.
273 Entries in the access-list are evaluated sequentially, so order is very
275 important. The first matching entry is used to decide if a message will
276 be whitelisted or greylisted. A special default clause can be used in
277 the last ACL entry as a wildcard. Here are a few complete ACL exam‐
278 ples:
279 Example 1:
281 racl whitelist from friend@toto.com rcpt grandma@example.com
283 racl whitelist from other.friend@example.net rcpt grandma@example.com
284 racl greylist rcpt grandma@example.com
285 racl whitelist default
286 Example 2:
288 racl whitelist addr 193.54.0.0/16 domain friendly.com
290 racl greylist rcpt user1@atmine.com
291 racl greylist rcpt user2@atmine.com
292 racl greylist rcpt user3@atmine.com
293 racl whitelist default
294 Example 3:
296 racl whitelist rcpt /@.*otherdomain\.org$/
298 racl whitelist addr 192.168.42.0/24 rcpt user1@mydomain.org
299 racl whitelist from friend@example.net rcpt /@.*mydomain\.org$/
300 racl whitelist rcpt user2@mydomain.org
301 racl greylist rcpt /@.*mydomain\.org$/
302 racl whitelist default
303
305 ACL using the racl keyword are evaluated at the RCPT stage of the SMTP
306 transaction. It is also possible to have ACL evaluated at the DATA
307 stage of the SMTP transaction, using the dacl keyword, provided the
308 message went through RCPT-stage ACL, and possibly greylisting. Note
309 that you cannot use the greylist action at DATA-stage if the RCPT-stage
310 ACL that matched had a greylist action itself. The following clauses
311 can be used to work on message content:
312 dkim DKIM status (if build with DKIM support). Possible values are
314 pass, fail, unknown, error, and none,
315 header String or regular expression searched in message headers
317 body String or regular expression searched in message body
319 msgsize
321 Operator followed by a message size (k or M suffix allowed for
322 kilobytes or megabytes). Example:
323 dacl blacklist msgsize >= 4M msg "No more than 4 MB please"
325 spamd SpamAssassin score (if build with SpamAssassin support). If used
327 without comparison operator spamd is true if the score is above
328 threshold. The spamdsock keyword can be used to specify the
329 location of the spamd socket.
330 Example 1:
332 spamdsock unix "/var/spamassassin/spamd.sock"
334 racl whitelist default
335 dacl greylist spamd
336 Example 2:
338 spamdsock inet "127.0.0.1:783"
340 racl whitelist default
341 dacl blacklist spamd > 15 msg "Your message is considered spam."
342 dacl greylist spamd > 10 delay 2h
343 dacl greylist spamd > 5 delay 1h
344 Note that if there are multiple recipient, a rcpt clause at DATA stage
346 evaluates to true if it matches any of them. If you want to match an
347 exact set of recipients, you can use multiple rcpt clauses along with a
348 rcptcount clause.
349
351 It is often useful to group several users or sender IP addresses in a
352 single ACL. This can be done with lists. Lists must be first defined
353 and given a name before they can be used in ACL entries. Here is an
354 example:
355 list "my users" rcpt { user1@example.com user2@example.com }
357 list "local" addr { 192.0.2.0/24 10.0.0.0/8 }
358 racl whitelist list "local"
360 racl greylist list "my users"
361 racl whitelist default
362
365 Previous versions of milter-greylist(8) used addr, domain, from, and
366 rcpt lines, without the racl keyword. Access-list management is
367 intended to replace them. These lines are still accepted by milter-
368 greylist(8), but they are deprecated. milter-greylist(8) handles them
369 as access-list entries with a single clause. They are added at the head
370 of the access-list so the use of these keywords and access-lists may
371 lead to unspecified behaviour. Do not mix them.
372 test mode (using -T) is also deprecated. Access-list semantics do not
374 depend on this flag.
375 milter-greylist(8) also used to only have a RCPT-stage ACL, which was
377 configured through acl statements. These have been replaced by racl
378 statements (as opposed to dacl statements for DATA-stage ACL). acl
379 statements are still accepted for backward compatibility and are a syn‐
380 onym for racl statements.
381
383 Synchronization of the greylist among multiple MX is configured using
384 the peer keyword. List each other MX IP addresses using the peer key‐
385 word. Here is an example:
386 peer 192.0.2.18
388 peer 192.0.2.17
389 peer 192.0.2.22 timeout 7
390 peer 192.0.2.38 timeout 5m
391 You can list the local machine in the peer statements, it will be
393 ignored.
394 The timeout clause sets a peer communication timeout to have proper
396 retrial in case of slow MX peer. The default value is 3 seconds. The
397 special value of 0 disables the connection retrials.
398 By default, milter-greylist will listen on all interfaces using TCP
400 port 5252 or the port number given by service named mxglsync if defined
401 in /etc/services or other directory service. This behaviour can be
402 changed by using the syncaddr keyword. Here are a few examples:
403 syncaddr *
405 syncaddr * port 7689
406 syncaddr 192.0.2.2 port 9785
407 syncaddr 2001:db8::1:c3b5:123
408 syncaddr 2001:db8::1:c3b5:123 port 1234
409 Using '*' as the address means to bind to all local interfaces'
411 addresses. Note that if you are not using the default port, all MXs
412 must use the same port number.
413 For outbound connections the system is selecting one of the possible
415 addresses. If you want to use a specific IP you can use:
416 syncsrcaddr 123.456.78.9
418
420 milter-greylist(8) uses a text dump of its database to resume operation
421 after a crash. The dump is performed at regular time interval, but as
422 it is a heavy operation, you might want to configure a particular time
423 interval, using the dumpfreq option.
424 If the dumpfreq value is too small, it will kill performance. If it is
426 too high, you will loose a bigger part of the database on a crash.
427 Set dumpfreq to 0 to get a dump on each change (kills performance), Set
429 it to -1 to never dump to a file (unsafe as you lose the whole greylist
430 on each crash), or give a time value for the delay between dumps. The
431 time is given in seconds, except if a unit is given: m for minutes, h
432 for hours, and d for days.
433 You may further improve the performance of the dump operation at the
435 expense of humanly readable timestamp which by default appears as a
436 comment at the end of each line in the dumpfile. You may disable gener‐
437 ation of this comment by specifying dump_no_time_translation option in
438 the configuration file. This is specifically recommended if your dump‐
439 file grows to 100's of megabytes - it can reduce the time needed for
440 the dump operation by the order of magnitude!
441
443 By default, milter-greylist(8) will add a X-Greylist header to any mes‐
444 sage it handles. The header shows what happened to the message: delayed
445 or not delayed, and why. The following options can be used in
446 greylist.conf to alter this behavior:
447 report none
449 Never add a X-Greylist header.
450 report delays
452 Only add a header if the message was delayed.
453 report nodelays
455 Add a header if the message was not delayed. The header explains
456 why the message was not delayed.
457 report all
459 Always add a header. This is the default.
460
462 Sender callback systems are another anti-spam measure that attempts to
463 send a DSN to the sender address before accepting a message. If that
464 fails, then the sender address is wrong and the message is rejected.
465 Such systems usually stop their callback check at the RCPT stage of the
466 SMTP transaction.
467 Greylisting temporarily rejects at the RCPT stage, so sender callback
469 and greylisting love to fight each other. milter-greylist(8) proposes
470 a workaround to that problem with the delayedreject option. For mes‐
471 sages coming from <> (that is, for DSN), it will cause the temporary
472 reject to happen at the DATA stage of the SMTP transaction instead of
473 the RCPT stage. That way, milter-greylist(8) will cope much better with
474 sender callback systems.
475 This has a minor drawback (and this is why it is not enabled by
477 default): for a multi recipient DSN, whitelisted recipient will not be
478 honoured: the message will be delayed for everyone.
479
481 Any sendmail macro can be used as a clause in the access list. You need
482 to define a (macro, value) pair using the sm_macro keyword before using
483 it. Here is an example that uses the {client_resolve} macro to apply a
484 larger greylisting delay to hosts that have a bogus reverse DNS:
485 sm_macro "maybe_forged" "{client_resolve}" "FORGED"
487 racl greylist sm_macro "maybe_forged" delay 1h
489 racl greylist default delay 15m
490 A regular expression can be used as the macro value. It must be sur‐
492 rounded with slashes and not by quotes. The special value unset can
493 also be used to match an unset macro:
494 sm_macro "not_foo" "{foo}" unset
496 Note that any Sendmail macro that is not exported using the Mil‐
498 ter.macros.envrcpt setting of sendmail.cf will be seen as unset from
499 milter-greylist.
500
502 DNS Reverse Black List can be used to toggle an ACL. They must be
503 defined and named before they can be used. Here is an example which
504 uses a bigger greylisting delay for hosts caught in the SORBS dynamic
505 pool DNRSBL (this will include DSL and cable customers pools, which are
506 well known to be massively infected by spamwares):
507 dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10/32
509 racl greylist dnsrbl "SORBS DUN" delay 1h
511 racl greylist default delay 15m
512 The definition of a DNSRBL starts by the dnsrbl keyword, followed by
514 the quoted name of the DNSRBL, the DNS domain on which addresses should
515 be looked up, and the answer we should consider as a positive hit.
516 DNSRBL support is only available if enabled through the --enable-dnsrbl
518 config flag. Please make sure milter-greylist(8) is linked against a
519 thread-safe DNS resolver, otherwise it shall crash.
520
522 ACL are able to trigger a DNS update, which can be used to feed a
523 DNSRBL. That functionnality is enabled at build time if the DNS
524 resolver has DNS update support.
525 Configuration is done with the nsupdate statement, which may be used
527 several times, and the optionnal tsig statement, if you want ot use
528 authenticated DNS update. Here is an example syntax:
529 tsig "dns-update" "hmac-md5" "1B2M2Y8AsgTpgAmY7PhCfg=="
531 nsupdate "bl.example.net" { rname "%j.bl.example.net" rvalue
532 "127.0.0.2" tsig "dns-update" }
533 The options for nsupdate are:
535 rname Created record name, which uses format strings.
537 rvalue Created record value, which uses format strings.
539 servers
541 Quoted comma-separated list of DNS server the update should be
542 sent to. Default is to use the system confifugration, usualy
543 from /etc/resolv.conf
544 ttl TTL of created DNS record. Default is 0 seconds.
546 class Created record class, as numeric value. Default is 1, for IN
548 class.
549 type Created record type, as numeric value. Default is 1, for A type.
551 tsig The name of a tsig configuration, which must have been supplied
553 before. If unspecified, unauthenticated DNS updates are per‐
554 formed.
555 Once configured, DNS updates can be used in any ACL:
557 racl blacklist rcpt spamtrap@example.net nsupdate "bl.exam‐
559 ple.net"
560
562 Properties are variables that can be set, evaluated and printed in ACL.
563 A property may be dropped once the current recipient is processed, or
564 it can be retained until the message is processed. They can be created
565 through the following always-matching ACL clauses:
566 set $name="value"
568 This sets a property that will be retained for all next recipi‐
569 ents. Right hand side of the clause may be a quoted string
570 (which will be substituted using format strings, as described in
571 the FORMAT STRINGS section), a number, or another property name
572 (which will be substituted by the property value).
573 rset $name="value"
575 Same as set clause, except that the property will be droped once
576 the current user will have been processed.
577 urlcheck
579 These clause will cause properties to be fetched from an exter‐
580 nal web service. See the URL checks section below for details.
581 ldapcheck
583 These clause will cause properties to be fetched from a LDAP
584 directory See the LDAP CHECKS section below for details.
585 Properties can be used as left-hand side part of ACL clauses:
587 racl blacklist $name "badvalue"
589 racl blacklist $name /badregex/
590 If used left-hand side and prefixed by a star, the property will be
592 evaluated as a glob(7) pattern, In the example below, if sender DNS
593 domain is test.example.net and $domain is *.example.net, we get a
594 match.
595 racl blacklist *$domain "%f"
597 They are also available as right-hand side of many ACL clauses:
599 racl continue set $badword="spam"
601 racl blacklist body $badword
602 Values of properties can be obtained in any quoted string that is sub‐
604 ject to format string expantion:
605 racl continue set $webmaster="webmaster@example.net"
607 racl blacklist domain evil.net msg "blacklisted, ask $P{web‐
608 master} why"
609 When the property value is a number, it can be increased or decreased
611 using this syntax:
612 racl continue set $score+=5
614 racl continue set $score-=5
615 Here again, right hand side may be a quoted string, a number or another
617 property. For the quoted string and property cases, a conversion is
618 first made to an integer, using 0 as a value on failure. Note that no
619 arithmetic evaluation occurs. For instance, the quoted string "1 + 1"
620 will be evaluated as 0.
621 The log ACL clause can be helpful when one need to figure what happens
623 to property values during the ACL flow. See the CUSTOM REPORT section
624 for more details.
625
627 milter-greylist(8) is able to query external sources of information
628 through various URL, if it was built with --with-libcurl. Here is an
629 example:
630 urlcheck "glusr" "http://www.example.net/mgl-config?rcpt=%r" 5
632 racl greylist urlcheck "glusr" delay 15m
634 racl whitelist default
635 The trailing 5 at the end of the urlcheck definition is the maximum
637 number of simultaneous connections we want to launch on this URL. For
638 each message, the URL will be queried, with % format tags being sub‐
639 stituted. For instance, %r is substituted by the recipient. See the
640 FORMAT STRINGS section for the complete list of substitutions.
641 milter-greylist(8) expects an answer containing a list of \n terminated
643 lines, with key: value pairs. The most basic answer to get a match is:
644 milterGreylistStatus: Ok
646 TRUE can be used as an alias for Ok here.
648 The answer can be more complex, with keys that will overload the ACL
650 settings:
651 milterGreylistDelay
653 The greylisting delay to use (time unit suffix allowed).
654 milterGreylistAutowhite
656 The autowhite delay to use (time unit suffix allowed).
657 milterGreylistFlushAddr
659 The value is ignored. If this key is present, then the IP
660 address for the sender machine will be flushed from greylist and
661 autowhite databases.
662 milterGreylistCode
664 The SMTP code to return (e.g.: 551).
665 milterGreylistECode
667 The SMTP extended code to return (e.g.: 5.7.1)
668 milterGreylistMsg
670 The string to return with SMTP codes.
671 milterGreylistReport
673 The string to display in the X-Greylist header.
674 milterGreylistIgnore
676 This line will be ignored, without warnings in the logs.
677 milterGreylistAction
679 This feature is nifty but use it with caution, as it makes the
680 access list a bit difficult to understand. By specifying the
681 values greylist, whitelist, or blacklist, it is possible to
682 overload the ACL action itself.
683 The ACL will match if any of the above key is returned: milterGreylist‐
685 Status is not mandatory.
686 Optional keywords can be appended to a urlcheck definition:
688 postmsg
690 On DATA-stage ACL, This causes the message to be sent (up to
691 maxpeek bytes) in a POST request. Here is an example:
692 urlcheck "extfilter" "http://www.example.net/f.cgi" 5 postmsg
694 dacl blacklist urlcheck "extfilter"
696 dacl whitelist default
697 getprop
699 Gather the properties returned by the URL and reuse them in the
700 ACL. The gathered properties can be accessed in the current and
701 following ACL by prefixing them by a dollar ($).
702 clear This causes gathered properties to be cleared on each new recip‐
704 ient. This avoids properties for several recipients to mix.
705 fork Tells milter-greylist(8) to fork a separate instance of itself
707 for performing the queries. Use it if you encounter thread-
708 safety problems. fork is not compatible with postmsg.
709 domatch
711 Cause the ldapcheck clause to be evaluated in ACL. Default
712 behavior is to ignore the result and just fecth properties,
713 except if the LDAP directory is unreachecable, in which case a
714 temporary failure occurs. The fixldapcheck gloabal settings may
715 also be used to globaly cause all ldapcheck and urlcheck clauses
716 to match.
717 Here is an example that will use various DNSRBL depending on a per-
719 recipient setting stored in the dnsrbl attribute of a LDAP directory.
720 dnsrbl "RBL2" "rbl.example.net" "127.0.0.2"
722 dnsrbl "RBL3" "rbl.example.net" "127.0.0.3"
723 dnsrbl "RBL4" "rbl.example.net" "127.0.0.4"
724 urlcheck "userconf" "ldap://localhost/dc=example,dc=net?mil‐
725 terGreylistStatus,dnsrbl?one?mail=%r" 5 getprop clear
726 racl blacklist urlcheck "userconf" $dnsrbl "RBL2" dnsrbl
728 "RBL2"
729 racl blacklist $dnsrbl "RBL3" dnsrbl "RBL3"
730 racl blacklist $dnsrbl "RBL4" dnsrbl "RBL4"
731 Note that when matching gathered properties, format strings and regex
733 can be used.
734
736 If milter-greylist was built with --with-openldap, then you can also
737 use ldapcheck for pulling information from an LDAP directory. This
738 works exactly like urlcheck, except that properties are always col‐
739 lected: The getprop option is implicit.
740 A list of LDAP URL to use can be specified with the ldapconf keyword.
742 The network timeout is optional.
743 ldapconf "ldap://localhost ldaps://ldap.example.net" timeout
745 2s
746 When ldaps:// is used, the system's ldap.conf file is used to locate
748 x509 certificates.
749 When defining LDAP queries with the ldapcheck statement, note that the
751 scheme and host part of the URL are ignored. Servers listed in ldap‐
752 conf are used instead.
753
755 The ratelimit keyword specifies a ratelimit configuration to be used in
756 access lists. It must be followed by the rate limit configuration name,
757 what is being accounted (i.e.: session for SMTP sessions, rcpt for
758 recipients, data for bytes in body and headers), the actual limit, and
759 the sampling period. Example:
760 ratelimit "internalclients" rcpt 10 / 1m
762 racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
764 msg "you speak too much"
765 The ratelimit keyword can also have an option key statement, which
767 determine the set of key for message accounting. The default is %i for
768 per IP address accounting (see the FORMAT STRINGS sections for the pos‐
769 sible syntax of this field). Here is an example that configures a rate
770 limit of 100 messages per hour for each individual recipient-IP set.
771 ratelimit "internalclients" rcpt 100 / 1h key "%r%i"
773 racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
775 msg "you speak too much"
776
778 The stat keyword can be used to specify a custom report for milter-
779 greylist activity. It should be supplied with an output (either file
780 or external command) and a format string. Here is an example:
781 stat ">>/var/log/milter-greylist.log" "%T{%T},%i,%f,%r,%A\n"
783 If the output starts by >> or > then it is a file. Use >> to append to
785 an existing file, and use > to overwrite it. If the output starts by a
786 | then the output is a shell command, like in the example below:
787 stat "|logger -p local7.info" "%T{%T},%i,%f,%r,%A\n"
789 The format string gets substituted as URL checks format string: %r gets
791 substituted by the recipient, %f by the sender, and so on. See the FOR‐
792 MAT STRINGS section for a complete list of available substitutions.
793 There is also an always-matching log ACL clause that can be used to
795 send a formated string to syslog with LOG_INFO level. Here is an exam‐
796 ple:
797 racl continue rcpt /@example\.com$/ log "I was here"
799
801 Most milter-greylist(8) command-line options have equivalent options
802 that can be set in the configuration file. Note that if a command line
803 option is supplied, it will always override the configuration file.
804 If a command-line equivalent keyword is used more than once, the last
806 keyword will override the previous ones.
807 verbose
809 Enable debug output. This is equivalent to the -v flag.
810 quiet Do not tell clients how much time remains before their e-mail
812 will be accepted. This is equivalent to the -q flag.
813 nodetach
815 Do not fork and go into the background. This is equivalent to
816 the -D flag.
817 noauth Greylist clients regardless if they succeeded SMTP AUTH or
819 STARTTLS. Equivalent to the -A flag.
820 noaccessdb
822 Normally milter-greylist(8) will whitelist a message if send‐
823 mail(8) defines a ${greylist} macro set to WHITE. This enables
824 complex whitelisting rules based on the Sendmail access DB. This
825 option inhibits this behavior.
826 nospf Greylist clients regardless if they are SPF-compliant. Equiva‐
828 lent to the -S flag.
829 testmode
831 Enable test mode. Equivalent to the -T flag. This option is dep‐
832 recated.
833 greylist
835 The argument sets how much time milter-greylist(8) will want the
836 client to wait between the first attempt and the time the mes‐
837 sage is accepted. The time is given in seconds, except if a unit
838 is given: m for minutes, h for hours, and d for days. The
839 greylist keyword is equivalent to the -w option. Here is an
840 example that sets the delay to 45 minutes:
841 greylist 45m
843 autowhite
845 This sets the auto-whitelisting duration, equivalent to the -a
846 command-line option. As for the greylist keyword, units can be
847 supplied. Here is an example for a 3 day long auto-whitelisting:
848 autowhite 3d
850 pidfile
852 This causes milter-greylist(8) to write its PID into the file
853 given as argument, like the -P command line argument does. The
854 path to the file must be absolute and it must be enclosed in
855 quotes. Here is an example:
856 pidfile "/var/run/greylist.pid"
858 dumpfile
860 This chooses the location of the greylist dump file, like the -d
861 command line option does. The path must be absolute and enclosed
862 in quotes. It can optionally be followed by an octal permission
863 mode. Example:
864 dumpfile "/var/lib/milter-greylist/db/greylist.db" 640
866 subnetmatch
868 This is equivalent to the -L command line option. It takes a
869 slash followed by a CIDR mask as argument, and it commands the
870 subnet matching feature. Example, for a class C wide matching:
871 subnetmatch /24
873 subnetmatch6
875 This is equivalent to the -M command line option. It takes a
876 slash followed by a prefixlen as argument, and it commands the
877 subnet matching feature. Example, for a subnet wide matching:
878 subnetmatch6 /64
880 socket Like the -p command line option, this keyword is used to specify
882 the socket used to communicate with sendmail(8). It must be
883 enclosed in quotes and can optionally be followed by an octal
884 permission mode (valid values are 666, 660 or 600, other values
885 cause an error):
886 socket "/run/milter-greylist/milter-greylist.sock" 660
888 user This keyword should be followed by a quoted user login and
890 optionally a colon followed by a groupname. Like the -u option,
891 this is used to run milter-greylist(8) as a non root user. Here
892 is an example:
893 user "smmsp"
895
897 These options have no command line equivalent:
898 logfac Sets the syslog facility for messages. Can be set to any of the
900 standard facilities: kern, user, mail, daemon, auth, syslog,
901 lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2,
902 local3, local4, local5, local6, local7. Can also be set to none
903 to disable syslog output completely.
904 timeout
906 is used to control how long greylist tuples are retained in the
907 database. Value is in seconds, except if a suffix is given (m
908 for minutes, h for hours, d for days). Default is 5 days.
909 extendedregex
911 Use extended regular expressions instead of basic regular
912 expressions.
913 unbracket
915 Attempt to resolve sender address when the MTA handed it as
916 bracketed IP address (e.g.: [192.0.2.18] ). Default is to leave
917 it as is.
918 maxpeek
920 Limit (in bytes) how much of messages are examined for header
921 and body searches.
922 lazyaw Make auto-whitelist look at just the IP instead of the (sender
924 IP, sender e-mail address, recipient e-mail address) tuple.
925 domainexact
927 match on subdomain boundaries instead of the default suffix
928 matching. E.g. if domainexact is not enabled (the default) then
929 gle.com will match google.com in addition to gle.com. If
930 domainexact is enabled then, domain names will match on subdo‐
931 main boundaries (e.g. gle.com will match mail.gle.com and
932 gle.com but not google.com)
933 drac db
935 Tell where the DRAC DB file is. This is only available if DRAC
936 support was compiled in. Here is an example:
937 drac db "/usr/local/etc/drac.db"
939 nodrac Disable DRAC.
941 logexpired
943 This option causes greylist entries that expire to be logged via
944 syslog. This allows you to easily collect the IP addresses and
945 sender names and use them for blacklisting, SPAM scoring, etc.
946 Normally, expiration's are only logged if the debug option is
947 set, but that generates a lot of extra messages.
948 localaddr
950 This keyword can be used to manually define the local MTA's IP
951 address for such uses as spf self and p0f in absence of the mil‐
952 ter-API {if_addr} macro support in your MTA (Postfix, Sun/Oracle
953 CommSuite Messaging Server). This is not so useful when using
954 Sendmail, since it serves the macro and the local address can be
955 detected automatically.
956 The configuration file is reloaded automatically once it is modified
958 when new e-mail arrives. Most configuration keywords will take effect
959 immediately, except the following, which will only take effect after a
960 restart of milter-greylist(8): nodetach, pidfile, socket, and user.
961 The dumpfreq option can be changed dynamically, but the change will
963 only take effect after the next dump.
964 multiracl
966 By default, once a RCPT-stage ACL whitelists a recipient, next
967 recipient gets automatically whitelisted. This historical behav‐
968 ior can be considered a bug, and this option disables it.
969
971 Various statements in the configuration file accept format strings,
972 where the following % prefixed tokens are substituted. Here is the com‐
973 plete list of available substitutions (Note that some substitutions are
974 not relevant in any context).
975 %r the message recipient e-mail address. This is not substituted
977 for DATA stage ACL since there can be multiple recipients for
978 the message.
979 %f the message sender e-mail address
981 %i the sender machine IP address
983 %j the reversed sender machine IP address. For instance, 192.0.2.12
985 becomes 12.2.0.192.
986 %I the sender machine IP address masked by a CIDR. Example: %I{/24}
988 %d the sender machine DNS address
990 %h the SMTP transaction HELO string
992 %mr the mailbox part of %r (before the @ sign). This is not substi‐
994 tuted for DATA stage ACL since there can be multiple recipients
995 for the message.
996 %sr the site part of %r (after the @ sign). This is not substituted
998 for DATA stage ACL since there can be multiple recipients for
999 the message.
1000 %mf the mailbox part of %f (before the @ sign)
1002 %sf the site part of %f (after the @ sign)
1004 %md the machine part of %d (before the first . sign)
1006 %sd the site part of %d (after the first . sign)
1008 %Xc the SMTP code returned
1010 %Xe the SMTP extended code returned
1012 %Xm the SMTP message returned
1014 %Xh the message displayed in the X-Greylist header
1016 %D Comma-separated list of DNSRBL for which the sender host matched
1018 %M a sendmail macro value. Examples: %Mj or %M{if_addr}
1020 %g a regex back reference. For instance, %g{\2} is substituted by
1022 the string matching the second parenthesis group in all ACL
1023 regex clauses
1024 %T a brace-enclosed strftime(3) format string that will be substi‐
1026 tuted by the system time. Example: %T{%Y%m%d:%H%M%S}
1027 %v milter-greylist's version
1029 %G Offset to GMT (e.g.: -0100)
1031 %C Sender IP country code, as reported by GeoIP. This is only
1033 available if milter-greylist was built with GeoIP support
1034 %Fx p0f OS fingerprint genre and detail. This is only available if
1036 milter-greylist was built with p0f support.
1037 %V Shortcut to "milter-greylist-%v (%Mj [%M{if_addr}]); %T{%a, %d
1039 %b %Y %T} %G (%T{%Z})"
1040 %S the action performed: accept, tempfail, or reject.
1042 %A the line number of the ACL that caused the action.
1044 %a the id string of the ACL that caused the action. If no id was
1046 given, the line number is used instead.
1047 %cA the line number of the ACL being evaluated, whether it matches
1049 or not.
1050 %ca the id string of the ACL being avaluated, whether it matches or
1052 not. If no id was given, the line number is used instead.
1053 %Et total elapsed time in seconds before a greylisted message has
1055 been accepted
1056 %Eh hours elapsed
1058 %Em minutes elapsed (modulo one hour)
1060 %Es seconds elapsed (modulo one minute)
1062 %E shortcut to %Eh:%Em:Es
1064 %Rt total remaining time in seconds before a greylisted message will
1066 be accepted
1067 %Rh hours remaining
1069 %Rm minutes remaining (modulo one hour)
1071 %Rs seconds remaining (modulo one minute)
1073 %R shortcut to %Rh:%Rm:Rs
1075 %Hs SpamAssassin score (if build with SpamAssassin support)
1077 %pn Name of last LDAP or CURL gathered property that matched an ACL.
1079 %pv Value of last LDAP or CURL gathered property that matched an
1081 ACL.
1082 %pr Recipient that caused storage of the last matching LDAP or CURL
1084 gathered property. %P a LDAP or CURL gathered propery. Example:
1085 %P{mail} Note that this copes very badly with multivalued prop‐
1086 erties.
1087 %Qd DKIM query result (pass, fail, etc.), if built with DKIM sup‐
1089 port.
1090 %Qs SPF query result (pass, (soft)fail, etc.), if built with SPF
1092 support.
1093 %QA Authentication results summary, suitable for Authentication-
1095 Results header. Will included formatted query results from DKIM
1096 and SPF if checked.
1097 %QS SPF result, suitable for Received-SPF header. Available when
1099 compiled with libspf2.
1100 %% a single % character
1102
1104 Emmanuel Dreyfus <manu@netbsd.org>
1105 milter-greylist received many contributions from (in alphabetical
1107 order): Adrian Dabrowski, Aida Shinra, Adam Katz, Alexander Lobodzin‐
1108 ski, Alexandre Cherif, Alexey Popov, Andrew McGill, Attila Bruncsak,
1109 Benoit Branciard, Bernhard Schneider, Bob Smith, Constantine A.
1110 Murenin, Chris Bennett, Christian Pelissier, Cyril Guibourg, Dan Hol‐
1111 lis, David Binderman, Denis Solovyov, Elrond, Enrico Scholz, Eugene
1112 Crosser, Fabien Tassin, Fredrik Pettai, Gary Aitken, Georg Horn, Gert
1113 Doering, Greg Troxel, Guido Kerkewitz, Hajimu Umemoto, Hideki ONO, Ivan
1114 F. Martinez, Jacques Beigbeder, Jean Benoit, Jean-Jacques Puig, Jeff
1115 Rife, Jim Klimov, Jobst Schmalenbach, Joe Pruett, Joel Bertrand, Johann
1116 E. Klasek, Johann Klasek, John Thiltges, John Wood, Jorgen Lundman,
1117 Kazuyuki Yoshida, Klas Heggemann, Kouhei Sutou, Laurence Moindrot, Lev
1118 Walkin, Manuel Badzong, Markus Wennrich, Mart Pirita, Martin Paul, Matt
1119 Kettler, Mattheu Herrb, Matthias Scheler, Matthieu Herrb, Michael
1120 Fromme, Moritz Both, Nerijus Baliunas, Ole Hansen, Pavel Cahyna, Pascal
1121 Lalonde, Per Holm, Petar Bogdanovic, Petr Kristof, Piotr Wadas, R P
1122 Herrold, Ralf S. Engelschall, Ranko Zivojnovic, Remy Card, Rick Adams,
1123 Rogier Maas, Romain Kang, Rudy Eschauzier, Stephane Lentz, Steven His‐
1124 cocks, Thomas Scheunemann, Tim Mooney, Vincent Dufresne, Wolfgang Sol‐
1125 frank, and Yaroslav Boychuk.
1126 Thanks to Helmut Messerer and Thomas Pfau for their feedback on the
1128 first releases of this software.
1129
1131 milter-greylist(8), sendmail(8), syslogd(8).
1132 Evan Harris's paper:
1134 http://projects.puremagic.com/greylisting/
1135 milter-greylist's web site:
1137 http://hcpnet.free.fr/milter-greylist/
1138 May 10, 2005 greylist.conf(5)