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.
125 p0f This is used to match against the remote system OS fingerprint
127 genre and detail,obtained from p0f. It is only available if mil‐
128 ter-greylist was built with p0f support. p0f clauses can be
129 used with a quoted string for case-insensitive substring match,
130 or against regular expressions. The p0fsock statement can be
131 used to specify the location of the p0f socket.
132 auth This is used to select a user that succeeded SMTP AUTH. In order
134 to select any user that succeeds SMTP AUTH, you can use a regu‐
135 lar expression matching, like below;
136 racl whitelist auth /.*/
138 Using such a clause automatically disable global STARTTLS and
140 SMTP AUTH whitelisting, like if the noauth keyword would have
141 been used.
142 tls This is used to select the distinguished name (DN) of a user
144 that succeeded STARTTLS. Using such a clause automatically dis‐
145 able global STARTTLS and SMTP AUTH whitelisting, like if the
146 noauth keyword would have been used.
147 spf This is used to test SPF status. Possible values are pass, soft‐
149 fail, fail, neutral, unknown, error, none, and self. The first
150 seven values are plain SPF validation status. The self value is
151 a special test that checks the server's local IP address against
152 the sender's SPF record. If that test validates, odds are good
153 that the sender SPF record is wide open, and this is hint that
154 SPF should not be trusted.
155 In order to use spf self, Postfix users must specify the local
157 address in the configuration file, using the localaddr option.
158 Absence of any value after the spf keyword is a synonym for spf
160 pass. This is present for backward compatibility.
161 The spf clause is only available if SPF support was compiled in.
163 Using it will disable global SPF whitelisting, like if the nospf
164 keyword would have been used.
165 ldapcheck
167 This is used to query an LDAP directory. See the section on
168 that topic for more information.
169 urlcheck
171 This is used to query an external configuration source through
172 an URL. See the section on that topic for more information.
173 dnsrbl This is used to select a DNSRBL. See the section on that topic
175 for more information.
176 nsupdate
178 This always-matching clause performs a DNS update, see the sec‐
179 tion on that topic for more information.
180 The domain, from, and rcpt clauses may be used with regular expres‐
182 sions. The regular expressions must be enclosed by slashes (/). No
183 escaping is available to provide a slash inside a regular expression,
184 so just do not use it. Regular expressions follow the format described
185 in re_format(7). Here is an example:
186 racl greylist rcpt /@example\.net$/
188 When regular expressions are not used, from, and rcpt perform a case
190 insensitive substring match with leading and trailing brackets, spaces
191 and tabs stripped out. domain performs a case insensitive suffix
192 match. This means, for example, that gle.com will match google.com. If
193 you want domain names to match on subdomain boundaries (e.g. gle.com
194 will match mail.gle.com and gle.com but not google.com) then enable
195 domainexact
196 An ACL entry can also hold various optional parameter used on match:
198 delay, autowhite, flushaddr, nolog, code, ecode, report, maxpeek,
199 addheader, addfooter, and msg
200 delay Specify the greylisting delay used before the message can be
202 accepted. This overrides the greylist global setting, and it
203 only makes sense on an racl greylist entry.
204 autowhite
206 Specify the autowhitelisting duration for messages matching this
207 ACL. This overrides the autowhite global setting, and it only
208 makes sense on an racl greylist entry. Example:
209 racl greylist rcpt JDoe@example.net delay 15m autowhite 3d
211 racl greylist rcpt root@example.net delay 1h autowhite 3d
212 flushaddr
214 If a message matches the rule, any entry in the greylist or
215 autowhite databases matching the sender IP is removed. Used with
216 a DNSRBL blacklist ACL, it is useful for freeing the database
217 from entries set up by a machine which is known to be a spammer.
218 Example:
219 racl blacklist dnsrbl "known-spammer" flushaddr
221 nolog Do not generate syslog message if this rule matches. Example:
223 racl whitelist default nolog
225 code
227 ecode
229 msg These 3 values can be used to choose the SMTP code, extended
231 code and reply message for temporary failures and rejects. Exam‐
232 ple:
233 racl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
235 racl greylist default code "451" ecode "4.7.1"
236 The msg strings accepts format string substitution as documented
238 in the FORMAT STRINGS section. For instance, %A gets substituted
239 by the ACL line number.
240 None of the last 3 values makes sense for a whitelist entry.
242 report This value overrides the text displayed in the X-Greylist
244 header, for messages that milter-greylist(8) lets pass through,
245 either because they are whitelisted, or because they passed
246 greylisting (see REPORTING). This string can be substituted as
247 documented in the FORMAT STRINGS section.
248 maxpeek
250 This parameter only makes sense in a RCPT-stage ACL. It over‐
251 rides the global maxpeek setting for DATA-stage handling of the
252 message. It has no effect if global maxpeek is set to 0.
253 addheader
255 This quoted string is a RFC822 header that gets added to the
256 message. Format string substitution is supported. No check is
257 done for header length standard compliance, so make sure the
258 substituted string is shorter than 2048 characters. Headers are
259 appended to the bottom, unless an optionnal comma-separated pos‐
260 itive index is specified after the quoted string; in this case
261 the header will be inserted at this index point from the top.
262 Here is an example:
263 racl continue addheader "X-Personnal-Header: Hello world!",1
264 addfooter
266 Append a footer to the message. Usual escape sequences such as
267 \n can be used to get special characters. The string is subject
268 to format string expantion as described in the FORMAT STRINGS
269 section. The footer will not be append if milter-greylist was
270 not able to capture the whole message, therefore maxpeek must be
271 set approriately.
272 Entries in the access-list are evaluated sequentially, so order is very
274 important. The first matching entry is used to decide if a message will
275 be whitelisted or greylisted. A special default clause can be used in
276 the last ACL entry as a wildcard. Here are a few complete ACL exam‐
277 ples:
278 Example 1:
280 racl whitelist from friend@toto.com rcpt grandma@example.com
282 racl whitelist from other.friend@example.net rcpt grandma@example.com
283 racl greylist rcpt grandma@example.com
284 racl whitelist default
285 Example 2:
287 racl whitelist addr 193.54.0.0/16 domain friendly.com
289 racl greylist rcpt user1@atmine.com
290 racl greylist rcpt user2@atmine.com
291 racl greylist rcpt user3@atmine.com
292 racl whitelist default
293 Example 3:
295 racl whitelist rcpt /@.*otherdomain\.org$/
297 racl whitelist addr 192.168.42.0/24 rcpt user1@mydomain.org
298 racl whitelist from friend@example.net rcpt /@.*mydomain\.org$/
299 racl whitelist rcpt user2@mydomain.org
300 racl greylist rcpt /@.*mydomain\.org$/
301 racl whitelist default
302
304 ACL using the racl keyword are evaluated at the RCPT stage of the SMTP
305 transaction. It is also possible to have ACL evaluated at the DATA
306 stage of the SMTP transaction, using the dacl keyword, provided the
307 message went through RCPT-stage ACL, and possibly greylisting. Note
308 that you cannot use the greylist action at DATA-stage if the RCPT-stage
309 ACL that matched had a greylist action itself. The following clauses
310 can be used to work on message content:
311 dkim DKIM status (if build with DKIM support). Possible values are
313 pass, fail, unknown, error, and none,
314 header String or regular expression searched in message headers
316 body String or regular expression searched in message body
318 msgsize
320 Operator followed by a message size (k or M suffix allowed for
321 kilobytes or megabytes). Example:
322 dacl blacklist msgsize >= 4M msg "No more than 4 MB please"
324 spamd SpamAssassin score (if build with SpamAssassin support). If used
326 without comparison operator spamd is true if the score is above
327 threshold. The spamdsock keyword can be used to specify the
328 location of the spamd socket.
329 Example 1:
331 spamdsock unix "/var/spamassassin/spamd.sock"
333 racl whitelist default
334 dacl greylist spamd
335 Example 2:
337 spamdsock inet "127.0.0.1:783"
339 racl whitelist default
340 dacl blacklist spamd > 15 msg "Your message is considered spam."
341 dacl greylist spamd > 10 delay 2h
342 dacl greylist spamd > 5 delay 1h
343 Note that if there are multiple recipient, a rcpt clause at DATA stage
345 evaluates to true if it matches any of them. If you want to match an
346 exact set of recipients, you can use multiple rcpt clauses along with a
347 rcptcount clause.
348
350 It is often useful to group several users or sender IP addresses in a
351 single ACL. This can be done with lists. Lists must be first defined
352 and given a name before they can be used in ACL entries. Here is an
353 example:
354 list "my users" rcpt { user1@example.com user2@example.com }
356 list "local" addr { 192.0.2.0/24 10.0.0.0/8 }
357 racl whitelist list "local"
359 racl greylist list "my users"
360 racl whitelist default
361
364 Previous versions of milter-greylist(8) used addr, domain, from, and
365 rcpt lines, without the racl keyword. Access-list management is
366 intended to replace them. These lines are still accepted by milter-
367 greylist(8), but they are deprecated. milter-greylist(8) handles them
368 as access-list entries with a single clause. They are added at the head
369 of the access-list so the use of these keywords and access-lists may
370 lead to unspecified behaviour. Do not mix them.
371 test mode (using -T) is also deprecated. Access-list semantics do not
373 depend on this flag.
374 milter-greylist(8) also used to only have a RCPT-stage ACL, which was
376 configured through acl statements. These have been replaced by racl
377 statements (as opposed to dacl statements for DATA-stage ACL). acl
378 statements are still accepted for backward compatibility and are a syn‐
379 onym for racl statements.
380
382 Synchronization of the greylist among multiple MX is configured using
383 the peer keyword. List each other MX IP addresses using the peer key‐
384 word. Here is an example:
385 peer 192.0.2.18
387 peer 192.0.2.17
388 peer 192.0.2.22 timeout 7
389 peer 192.0.2.38 timeout 5m
390 You can list the local machine in the peer statements, it will be
392 ignored.
393 The timeout clause sets a peer communication timeout to have proper
395 retrial in case of slow MX peer. The default value is 3 seconds. The
396 special value of 0 disables the connection retrials.
397 By default, milter-greylist will listen on all interfaces using TCP
399 port 5252 or the port number given by service named mxglsync if defined
400 in /etc/services or other directory service. This behaviour can be
401 changed by using the syncaddr keyword. Here are a few examples:
402 syncaddr *
404 syncaddr * port 7689
405 syncaddr 192.0.2.2 port 9785
406 syncaddr 2001:db8::1:c3b5:123
407 syncaddr 2001:db8::1:c3b5:123 port 1234
408 Using '*' as the address means to bind to all local interfaces'
410 addresses. Note that if you are not using the default port, all MXs
411 must use the same port number.
412 For outbound connections the system is selecting one of the possible
414 addresses. If you want to use a specific IP you can use:
415 syncsrcaddr 123.456.78.9
417
419 milter-greylist(8) uses a text dump of its database to resume operation
420 after a crash. The dump is performed at regular time interval, but as
421 it is a heavy operation, you might want to configure a particular time
422 interval, using the dumpfreq option.
423 If the dumpfreq value is too small, it will kill performance. If it is
425 too high, you will loose a bigger part of the database on a crash.
426 Set dumpfreq to 0 to get a dump on each change (kills performance), Set
428 it to -1 to never dump to a file (unsafe as you lose the whole greylist
429 on each crash), or give a time value for the delay between dumps. The
430 time is given in seconds, except if a unit is given: m for minutes, h
431 for hours, and d for days.
432 You may further improve the performance of the dump operation at the
434 expense of humanly readable timestamp which by default appears as a
435 comment at the end of each line in the dumpfile. You may disable gener‐
436 ation of this comment by specifying dump_no_time_translation option in
437 the configuration file. This is specifically recommended if your dump‐
438 file grows to 100's of megabytes - it can reduce the time needed for
439 the dump operation by the order of magnitude!
440
442 By default, milter-greylist(8) will add a X-Greylist header to any mes‐
443 sage it handles. The header shows what happened to the message: delayed
444 or not delayed, and why. The following options can be used in
445 greylist.conf to alter this behavior:
446 report none
448 Never add a X-Greylist header.
449 report delays
451 Only add a header if the message was delayed.
452 report nodelays
454 Add a header if the message was not delayed. The header explains
455 why the message was not delayed.
456 report all
458 Always add a header. This is the default.
459
461 Sender callback systems are another anti-spam measure that attempts to
462 send a DSN to the sender address before accepting a message. If that
463 fails, then the sender address is wrong and the message is rejected.
464 Such systems usually stop their callback check at the RCPT stage of the
465 SMTP transaction.
466 Greylisting temporarily rejects at the RCPT stage, so sender callback
468 and greylisting love to fight each other. milter-greylist(8) proposes
469 a workaround to that problem with the delayedreject option. For mes‐
470 sages coming from <> (that is, for DSN), it will cause the temporary
471 reject to happen at the DATA stage of the SMTP transaction instead of
472 the RCPT stage. That way, milter-greylist(8) will cope much better with
473 sender callback systems.
474 This has a minor drawback (and this is why it is not enabled by
476 default): for a multi recipient DSN, whitelisted recipient will not be
477 honoured: the message will be delayed for everyone.
478
480 Any sendmail macro can be used as a clause in the access list. You need
481 to define a (macro, value) pair using the sm_macro keyword before using
482 it. Here is an example that uses the {client_resolve} macro to apply a
483 larger greylisting delay to hosts that have a bogus reverse DNS:
484 sm_macro "maybe_forged" "{client_resolve}" "FORGED"
486 racl greylist sm_macro "maybe_forged" delay 1h
488 racl greylist default delay 15m
489 A regular expression can be used as the macro value. It must be sur‐
491 rounded with slashes and not by quotes. The special value unset can
492 also be used to match an unset macro:
493 sm_macro "not_foo" "{foo}" unset
495 Note that any Sendmail macro that is not exported using the Mil‐
497 ter.macros.envrcpt setting of sendmail.cf will be seen as unset from
498 milter-greylist.
499
501 DNS Reverse Black List can be used to toggle an ACL. They must be
502 defined and named before they can be used. Here is an example which
503 uses a bigger greylisting delay for hosts caught in the SORBS dynamic
504 pool DNRSBL (this will include DSL and cable customers pools, which are
505 well known to be massively infected by spamwares):
506 dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10/32
508 racl greylist dnsrbl "SORBS DUN" delay 1h
510 racl greylist default delay 15m
511 The definition of a DNSRBL starts by the dnsrbl keyword, followed by
513 the quoted name of the DNSRBL, the DNS domain on which addresses should
514 be looked up, and the answer we should consider as a positive hit.
515 DNSRBL support is only available if enabled through the --enable-dnsrbl
517 config flag. Please make sure milter-greylist(8) is linked against a
518 thread-safe DNS resolver, otherwise it shall crash.
519
521 ACL are able to trigger a DNS update, which can be used to feed a
522 DNSRBL. That functionnality is enabled at build time if the DNS
523 resolver has DNS update support.
524 Configuration is done with the nsupdate statement, which may be used
526 several times, and the optionnal tsig statement, if you want ot use
527 authenticated DNS update. Here is an example syntax:
528 tsig "dns-update" "hmac-md5" "1B2M2Y8AsgTpgAmY7PhCfg=="
530 nsupdate "bl.example.net" { rname "%j.bl.example.net" rvalue
531 "127.0.0.2" tsig "dns-update" }
532 The options for nsupdate are:
534 rname Created record name, which uses format strings.
536 rvalue Created record value, which uses format strings.
538 servers
540 Quoted comma-separated list of DNS server the update should be
541 sent to. Default is to use the system confifugration, usualy
542 from /etc/resolv.conf
543 ttl TTL of created DNS record. Default is 0 seconds.
545 class Created record class, as numeric value. Default is 1, for IN
547 class.
548 type Created record type, as numeric value. Default is 1, for A type.
550 tsig The name of a tsig configuration, which must have been supplied
552 before. If unspecified, unauthenticated DNS updates are per‐
553 formed.
554 Once configured, DNS updates can be used in any ACL:
556 racl blacklist rcpt spamtrap@example.net nsupdate "bl.exam‐
558 ple.net"
559
561 Properties are variables that can be set, evaluated and printed in ACL.
562 A property may be dropped once the current recipient is processed, or
563 it can be retained until the message is processed. They can be created
564 through the following always-matching ACL clauses:
565 set $name="value"
567 This sets a property that will be retained for all next recipi‐
568 ents. Right hand side of the clause may be a quoted string
569 (which will be substituted using format strings, as described in
570 the FORMAT STRINGS section), a number, or another property name
571 (which will be substituted by the property value).
572 rset $name="value"
574 Same as set clause, except that the property will be droped once
575 the current user will have been processed.
576 urlcheck
578 These clause will cause properties to be fetched from an exter‐
579 nal web service. See the URL checks section below for details.
580 ldapcheck
582 These clause will cause properties to be fetched from a LDAP
583 directory See the LDAP CHECKS section below for details.
584 Properties can be used as left-hand side part of ACL clauses:
586 racl blacklist $name "badvalue"
588 racl blacklist $name /badregex/
589 If used left-hand side and prefixed by a star, the property will be
591 evaluated as a glob(7) pattern, In the example below, if sender DNS
592 domain is test.example.net and $domain is *.example.net, we get a
593 match.
594 racl blacklist *$domain "%f"
596 They are also available as right-hand side of many ACL clauses:
598 racl continue set $badword="spam"
600 racl blacklist body $badword
601 Values of properties can be obtained in any quoted string that is sub‐
603 ject to format string expantion:
604 racl continue set $webmaster="webmaster@example.net"
606 racl blacklist domain evil.net msg "blacklisted, ask $P{web‐
607 master} why"
608 When the property value is a number, it can be increased or decreased
610 using this syntax:
611 racl continue set $score+=5
613 racl continue set $score-=5
614 Here again, right hand side may be a quoted string, a number or another
616 property. For the quoted string and property cases, a conversion is
617 first made to an integer, using 0 as a value on failure. Note that no
618 arithmetic evaluation occurs. For instance, the quoted string "1 + 1"
619 will be evaluated as 0.
620 The log ACL clause can be helpful when one need to figure what happens
622 to property values during the ACL flow. See the CUSTOM REPORT section
623 for more details.
624
626 milter-greylist(8) is able to query external sources of information
627 through various URL, if it was built with --with-libcurl. Here is an
628 example:
629 urlcheck "glusr" "http://www.example.net/mgl-config?rcpt=%r" 5
631 racl greylist urlcheck "glusr" delay 15m
633 racl whitelist default
634 The trailing 5 at the end of the urlcheck definition is the maximum
636 number of simultaneous connections we want to launch on this URL. For
637 each message, the URL will be queried, with % format tags being sub‐
638 stituted. For instance, %r is substituted by the recipient. See the
639 FORMAT STRINGS section for the complete list of substitutions.
640 milter-greylist(8) expects an answer containing a list of \n terminated
642 lines, with key: value pairs. The most basic answer to get a match is:
643 milterGreylistStatus: Ok
645 TRUE can be used as an alias for Ok here.
647 The answer can be more complex, with keys that will overload the ACL
649 settings:
650 milterGreylistDelay
652 The greylisting delay to use (time unit suffix allowed).
653 milterGreylistAutowhite
655 The autowhite delay to use (time unit suffix allowed).
656 milterGreylistFlushAddr
658 The value is ignored. If this key is present, then the IP
659 address for the sender machine will be flushed from greylist and
660 autowhite databases.
661 milterGreylistCode
663 The SMTP code to return (e.g.: 551).
664 milterGreylistECode
666 The SMTP extended code to return (e.g.: 5.7.1)
667 milterGreylistMsg
669 The string to return with SMTP codes.
670 milterGreylistReport
672 The string to display in the X-Greylist header.
673 milterGreylistIgnore
675 This line will be ignored, without warnings in the logs.
676 milterGreylistAction
678 This feature is nifty but use it with caution, as it makes the
679 access list a bit difficult to understand. By specifying the
680 values greylist, whitelist, or blacklist, it is possible to
681 overload the ACL action itself.
682 The ACL will match if any of the above key is returned: milterGreylist‐
684 Status is not mandatory.
685 Optional keywords can be appended to a urlcheck definition:
687 postmsg
689 On DATA-stage ACL, This causes the message to be sent (up to
690 maxpeek bytes) in a POST request. Here is an example:
691 urlcheck "extfilter" "http://www.example.net/f.cgi" 5 postmsg
693 dacl blacklist urlcheck "extfilter"
695 dacl whitelist default
696 getprop
698 Gather the properties returned by the URL and reuse them in the
699 ACL. The gathered properties can be accessed in the current and
700 following ACL by prefixing them by a dollar ($).
701 clear This causes gathered properties to be cleared on each new recip‐
703 ient. This avoids properties for several recipients to mix.
704 fork Tells milter-greylist(8) to fork a separate instance of itself
706 for performing the queries. Use it if you encounter thread-
707 safety problems. fork is not compatible with postmsg.
708 domatch
710 Cause the ldapcheck clause to be evaluated in ACL. Default
711 behavior is to ignore the result and just fecth properties,
712 except if the LDAP directory is unreachecable, in which case a
713 temporary failure occurs. The fixldapcheck gloabal settings may
714 also be used to globaly cause all ldapcheck and urlcheck clauses
715 to match.
716 Here is an example that will use various DNSRBL depending on a per-
718 recipient setting stored in the dnsrbl attribute of a LDAP directory.
719 dnsrbl "RBL2" "rbl.example.net" "127.0.0.2"
721 dnsrbl "RBL3" "rbl.example.net" "127.0.0.3"
722 dnsrbl "RBL4" "rbl.example.net" "127.0.0.4"
723 urlcheck "userconf" "ldap://localhost/dc=example,dc=net?mil‐
724 terGreylistStatus,dnsrbl?one?mail=%r" 5 getprop clear
725 racl blacklist urlcheck "userconf" $dnsrbl "RBL2" dnsrbl
727 "RBL2"
728 racl blacklist $dnsrbl "RBL3" dnsrbl "RBL3"
729 racl blacklist $dnsrbl "RBL4" dnsrbl "RBL4"
730 Note that when matching gathered properties, format strings and regex
732 can be used.
733
735 If milter-greylist was built with --with-openldap, then you can also
736 use ldapcheck for pulling information from an LDAP directory. This
737 works exactly like urlcheck, except that properties are always col‐
738 lected: The getprop option is implicit.
739 A list of LDAP URL to use can be specified with the ldapconf keyword.
741 The network timeout is optional.
742 ldapconf "ldap://localhost ldaps://ldap.example.net" timeout
744 2s
745 When ldaps:// is used, the system's ldap.conf file is used to locate
747 x509 certificates.
748 When defining LDAP queries with the ldapcheck statement, note that the
750 scheme and host part of the URL are ignored. Servers listed in ldap‐
751 conf are used instead.
752
754 The ratelimit keyword specifies a ratelimit configuration to be used in
755 access lists. It must be followed by the rate limit configuration name,
756 what is being accounted (i.e.: session for SMTP sessions, rcpt for
757 recipients, data for bytes in body and headers), the actual limit, and
758 the sampling period. Example:
759 ratelimit "internalclients" rcpt 10 / 1m
761 racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
763 msg "you speak too much"
764 The ratelimit keyword can also have an option key statement, which
766 determine the set of key for message accounting. The default is %i for
767 per IP address accounting (see the FORMAT STRINGS sections for the pos‐
768 sible syntax of this field). Here is an example that configures a rate
769 limit of 100 messages per hour for each individual recipient-IP set.
770 ratelimit "internalclients" rcpt 100 / 1h key "%r%i"
772 racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
774 msg "you speak too much"
775
777 The stat keyword can be used to specify a custom report for milter-
778 greylist activity. It should be supplied with an output (either file
779 or external command) and a format string. Here is an example:
780 stat ">>/var/log/milter-greylist.log" "%T{%T},%i,%f,%r,%A\n"
782 If the output starts by >> or > then it is a file. Use >> to append to
784 an existing file, and use > to overwrite it. If the output starts by a
785 | then the output is a shell command, like in the example below:
786 stat "|logger -p local7.info" "%T{%T},%i,%f,%r,%A\n"
788 The format string gets substituted as URL checks format string: %r gets
790 substituted by the recipient, %f by the sender, and so on. See the FOR‐
791 MAT STRINGS section for a complete list of available substitutions.
792 There is also an always-matching log ACL clause that can be used to
794 send a formated string to syslog with LOG_INFO level. Here is an exam‐
795 ple:
796 racl continue rcpt /@example\.com$/ log "I was here"
798
800 Most milter-greylist(8) command-line options have equivalent options
801 that can be set in the configuration file. Note that if a command line
802 option is supplied, it will always override the configuration file.
803 If a command-line equivalent keyword is used more than once, the last
805 keyword will override the previous ones.
806 verbose
808 Enable debug output. This is equivalent to the -v flag.
809 quiet Do not tell clients how much time remains before their e-mail
811 will be accepted. This is equivalent to the -q flag.
812 nodetach
814 Do not fork and go into the background. This is equivalent to
815 the -D flag.
816 noauth Greylist clients regardless if they succeeded SMTP AUTH or
818 STARTTLS. Equivalent to the -A flag.
819 noaccessdb
821 Normally milter-greylist(8) will whitelist a message if send‐
822 mail(8) defines a ${greylist} macro set to WHITE. This enables
823 complex whitelisting rules based on the Sendmail access DB. This
824 option inhibits this behavior.
825 nospf Greylist clients regardless if they are SPF-compliant. Equiva‐
827 lent to the -S flag.
828 testmode
830 Enable test mode. Equivalent to the -T flag. This option is dep‐
831 recated.
832 greylist
834 The argument sets how much time milter-greylist(8) will want the
835 client to wait between the first attempt and the time the mes‐
836 sage is accepted. The time is given in seconds, except if a unit
837 is given: m for minutes, h for hours, and d for days. The
838 greylist keyword is equivalent to the -w option. Here is an
839 example that sets the delay to 45 minutes:
840 greylist 45m
842 autowhite
844 This sets the auto-whitelisting duration, equivalent to the -a
845 command-line option. As for the greylist keyword, units can be
846 supplied. Here is an example for a 3 day long auto-whitelisting:
847 autowhite 3d
849 pidfile
851 This causes milter-greylist(8) to write its PID into the file
852 given as argument, like the -P command line argument does. The
853 path to the file must be absolute and it must be enclosed in
854 quotes. Here is an example:
855 pidfile "/var/run/greylist.pid"
857 dumpfile
859 This chooses the location of the greylist dump file, like the -d
860 command line option does. The path must be absolute and enclosed
861 in quotes. It can optionally be followed by an octal permission
862 mode. Example:
863 dumpfile "/var/lib/milter-greylist/db/greylist.db" 640
865 subnetmatch
867 This is equivalent to the -L command line option. It takes a
868 slash followed by a CIDR mask as argument, and it commands the
869 subnet matching feature. Example, for a class C wide matching:
870 subnetmatch /24
872 subnetmatch6
874 This is equivalent to the -M command line option. It takes a
875 slash followed by a prefixlen as argument, and it commands the
876 subnet matching feature. Example, for a subnet wide matching:
877 subnetmatch6 /64
879 socket Like the -p command line option, this keyword is used to specify
881 the socket used to communicate with sendmail(8). It must be
882 enclosed in quotes and can optionally be followed by an octal
883 permission mode (valid values are 666, 660 or 600, other values
884 cause an error):
885 socket "/run/milter-greylist/milter-greylist.sock" 660
887 user This keyword should be followed by a quoted user login and
889 optionally a colon followed by a groupname. Like the -u option,
890 this is used to run milter-greylist(8) as a non root user. Here
891 is an example:
892 user "smmsp"
894
896 These options have no command line equivalent:
897 logfac Sets the syslog facility for messages. Can be set to any of the
899 standard facilities: kern, user, mail, daemon, auth, syslog,
900 lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2,
901 local3, local4, local5, local6, local7. Can also be set to none
902 to disable syslog output completely.
903 timeout
905 is used to control how long greylist tuples are retained in the
906 database. Value is in seconds, except if a suffix is given (m
907 for minutes, h for hours, d for days). Default is 5 days.
908 extendedregex
910 Use extended regular expressions instead of basic regular
911 expressions.
912 unbracket
914 Attempt to resolve sender address when the MTA handed it as
915 bracketed IP address (e.g.: [192.0.2.18] ). Default is to leave
916 it as is.
917 maxpeek
919 Limit (in bytes) how much of messages are examined for header
920 and body searches.
921 lazyaw Make auto-whitelist look at just the IP instead of the (sender
923 IP, sender e-mail address, recipient e-mail address) tuple.
924 domainexact
926 match on subdomain boundaries instead of the default suffix
927 matching. E.g. if domainexact is not enabled (the default) then
928 gle.com will match google.com in addition to gle.com. If
929 domainexact is enabled then, domain names will match on subdo‐
930 main boundaries (e.g. gle.com will match mail.gle.com and
931 gle.com but not google.com)
932 drac db
934 Tell where the DRAC DB file is. This is only available if DRAC
935 support was compiled in. Here is an example:
936 drac db "/usr/local/etc/drac.db"
938 nodrac Disable DRAC.
940 logexpired
942 This option causes greylist entries that expire to be logged via
943 syslog. This allows you to easily collect the IP addresses and
944 sender names and use them for blacklisting, SPAM scoring, etc.
945 Normally, expiration's are only logged if the debug option is
946 set, but that generates a lot of extra messages.
947 localaddr
949 This keyword can be used to manually define the local MTA's IP
950 address for such uses as spf self and p0f in absence of the mil‐
951 ter-API {if_addr} macro support in your MTA (Postfix, Sun/Oracle
952 CommSuite Messaging Server). This is not so useful when using
953 Sendmail, since it serves the macro and the local address can be
954 detected automatically.
955 The configuration file is reloaded automatically once it is modified
957 when new e-mail arrives. Most configuration keywords will take effect
958 immediately, except the following, which will only take effect after a
959 restart of milter-greylist(8): nodetach, pidfile, socket, and user.
960 The dumpfreq option can be changed dynamically, but the change will
962 only take effect after the next dump.
963 multiracl
965 By default, once a RCPT-stage ACL whitelists a recipient, next
966 recipient gets automatically whitelisted. This historical behav‐
967 ior can be considered a bug, and this option disables it.
968
970 Various statements in the configuration file accept format strings,
971 where the following % prefixed tokens are substituted. Here is the com‐
972 plete list of available substitutions (Note that some substitutions are
973 not relevant in any context).
974 %r the message recipient e-mail address. This is not substituted
976 for DATA stage ACL since there can be multiple recipients for
977 the message.
978 %f the message sender e-mail address
980 %i the sender machine IP address
982 %j the reversed sender machine IP address. For instance, 192.0.2.12
984 becomes 12.2.0.192.
985 %I the sender machine IP address masked by a CIDR. Example: %I{/24}
987 %d the sender machine DNS address
989 %h the SMTP transaction HELO string
991 %mr the mailbox part of %r (before the @ sign). This is not substi‐
993 tuted for DATA stage ACL since there can be multiple recipients
994 for the message.
995 %sr the site part of %r (after the @ sign). This is not substituted
997 for DATA stage ACL since there can be multiple recipients for
998 the message.
999 %mf the mailbox part of %f (before the @ sign)
1001 %sf the site part of %f (after the @ sign)
1003 %md the machine part of %d (before the first . sign)
1005 %sd the site part of %d (after the first . sign)
1007 %Xc the SMTP code returned
1009 %Xe the SMTP extended code returned
1011 %Xm the SMTP message returned
1013 %Xh the message displayed in the X-Greylist header
1015 %D Comma-separated list of DNSRBL for which the sender host matched
1017 %M a sendmail macro value. Examples: %Mj or %M{if_addr}
1019 %g a regex back reference. For instance, %g{\2} is substituted by
1021 the string matching the second parenthesis group in all ACL
1022 regex clauses
1023 %T a brace-enclosed strftime(3) format string that will be substi‐
1025 tuted by the system time. Example: %T{%Y%m%d:%H%M%S}
1026 %v milter-greylist's version
1028 %G Offset to GMT (e.g.: -0100)
1030 %C Sender IP country code, as reported by GeoIP. This is only
1032 available if milter-greylist was built with GeoIP support
1033 %Fx p0f OS fingerprint genre and detail. This is only available if
1035 milter-greylist was built with p0f support.
1036 %V Shortcut to "milter-greylist-%v (%Mj [%M{if_addr}]); %T{%a, %d
1038 %b %Y %T} %G (%T{%Z})"
1039 %S the action performed: accept, tempfail, or reject.
1041 %A the line number of the ACL that caused the action.
1043 %a the id string of the ACL that caused the action. If no id was
1045 given, the line number is used instead.
1046 %cA the line number of the ACL being evaluated, whether it matches
1048 or not.
1049 %ca the id string of the ACL being avaluated, whether it matches or
1051 not. If no id was given, the line number is used instead.
1052 %Et total elapsed time in seconds before a greylisted message has
1054 been accepted
1055 %Eh hours elapsed
1057 %Em minutes elapsed (modulo one hour)
1059 %Es seconds elapsed (modulo one minute)
1061 %E shortcut to %Eh:%Em:Es
1063 %Rt total remaining time in seconds before a greylisted message will
1065 be accepted
1066 %Rh hours remaining
1068 %Rm minutes remaining (modulo one hour)
1070 %Rs seconds remaining (modulo one minute)
1072 %R shortcut to %Rh:%Rm:Rs
1074 %Hs SpamAssassin score (if build with SpamAssassin support)
1076 %pn Name of last LDAP or CURL gathered property that matched an ACL.
1078 %pv Value of last LDAP or CURL gathered property that matched an
1080 ACL.
1081 %pr Recipient that caused storage of the last matching LDAP or CURL
1083 gathered property. %P a LDAP or CURL gathered propery. Example:
1084 %P{mail} Note that this copes very badly with multivalued prop‐
1085 erties.
1086 %Qd DKIM query result (pass, fail, etc.), if built with DKIM sup‐
1088 port.
1089 %Qs SPF query result (pass, (soft)fail, etc.), if built with SPF
1091 support.
1092 %QA Authentication results summary, suitable for Authentication-
1094 Results header. Will included formatted query results from DKIM
1095 and SPF if checked.
1096 %QS SPF result, suitable for Received-SPF header. Available when
1098 compiled with libspf2.
1099 %% a single % character
1101
1103 Emmanuel Dreyfus <manu@netbsd.org>
1104 milter-greylist received many contributions from (in alphabetical
1106 order): Adrian Dabrowski, Aida Shinra, Adam Katz, Alexander Lobodzin‐
1107 ski, Alexandre Cherif, Alexey Popov, Andrew McGill, Attila Bruncsak,
1108 Benoit Branciard, Bernhard Schneider, Bob Smith, Constantine A.
1109 Murenin, Chris Bennett, Christian Pelissier, Cyril Guibourg, Dan Hol‐
1110 lis, David Binderman, Denis Solovyov, Elrond, Enrico Scholz, Eugene
1111 Crosser, Fabien Tassin, Fredrik Pettai, Gary Aitken, Georg Horn, Gert
1112 Doering, Greg Troxel, Guido Kerkewitz, Hajimu Umemoto, Hideki ONO, Ivan
1113 F. Martinez, Jacques Beigbeder, Jean Benoit, Jean-Jacques Puig, Jeff
1114 Rife, Jim Klimov, Jobst Schmalenbach, Joe Pruett, Joel Bertrand, Johann
1115 E. Klasek, Johann Klasek, John Thiltges, John Wood, Jorgen Lundman,
1116 Kazuyuki Yoshida, Klas Heggemann, Kouhei Sutou, Laurence Moindrot, Lev
1117 Walkin, Manuel Badzong, Mart Pirita, Martin Paul, Matt Kettler, Mattheu
1118 Herrb, Matthias Scheler, Matthieu Herrb, Michael Fromme, Moritz Both,
1119 Nerijus Baliunas, Ole Hansen, Pavel Cahyna, Pascal Lalonde, Per Holm,
1120 Petar Bogdanovic, Petr Kristof, Piotr Wadas, R P Herrold, Ralf S.
1121 Engelschall, Ranko Zivojnovic, Remy Card, Rick Adams, Rogier Maas,
1122 Romain Kang, Rudy Eschauzier, Stephane Lentz, Steven Hiscocks, Thomas
1123 Scheunemann, Tim Mooney, Vincent Dufresne, Wolfgang Solfrank, and
1124 Yaroslav Boychuk.
1125 Thanks to Helmut Messerer and Thomas Pfau for their feedback on the
1127 first releases of this software.
1128
1130 milter-greylist(8), sendmail(8), syslogd(8).
1131 Evan Harris's paper:
1133 http://projects.puremagic.com/greylisting/
1134 milter-greylist's web site:
1136 http://hcpnet.free.fr/milter-greylist/
1137 May 10, 2005 greylist.conf(5)