1greylist.conf(5)                                              greylist.conf(5)
2
3
4

NAME

6       greylist.conf - milter-greylist configuration file
7

DESCRIPTION

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

WHITELIST

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
25       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
36       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
41       Clauses can be negated, by prefixing them by the not keyword.  Here  is
42       the detail of all possible clauses.
43
44       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
48                racl whitelist addr 127.0.0.0/8
49                racl whitelist addr 192.168.3.0/24
50                racl whitelist addr ::1
51
52              If  the  netmask  is omitted, /32 is assumed for an IPv4 address
53              and /128 is assumed for an IPv6 address.
54
55              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
60       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
64                racl whitelist domain example.net
65
66              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
71       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
76       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
80              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
85              Here is an example:
86
87                racl whitelist from postmaster@example.com
88
89       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
94                racl greylist rcpt John.Doe@example.net
95
96       rcptcount
97              Followed by an operator and a recipient count, this is  used  to
98              select the amount of recipients. Example:
99
100                racl  blacklist  rcptcount  >= 25 msg "No more than 25 recipi‐
101              ents, please"
102
103       helo   Followed by a quoted string or a regular expression, this can be
104              used to filter on the HELO string.
105
106       sm_macro
107              This  is  used to select a Sendmail macro value. See the section
108              on that topic for more information.
109
110       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
115                racl whitelist time "* 8-16 * * 1-5" rcpt info@example.net
116
117       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
126       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
133       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
137                racl whitelist auth /.*/
138
139              Using  such  a  clause automatically disable global STARTTLS and
140              SMTP AUTH whitelisting, like if the noauth  keyword  would  have
141              been used.
142
143       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
148       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
156              In order to use spf self, Postfix users must specify  the  local
157              address in the configuration file, using the localaddr option.
158
159              Absence  of any value after the spf keyword is a synonym for spf
160              pass.  This is present for backward compatibility.
161
162              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
166       ldapcheck
167              This is used to query an LDAP directory.   See  the  section  on
168              that topic for more information.
169
170       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
174       dnsrbl This is used to select a DNSRBL. See the section on  that  topic
175              for more information.
176
177       nsupdate
178              This  always-matching clause performs a DNS update, see the sec‐
179              tion on that topic for more information.
180
181       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
187         racl greylist rcpt /@example\.net$/
188
189       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
197       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
201       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
205       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
210                racl greylist rcpt JDoe@example.net delay 15m autowhite 3d
211                racl greylist rcpt root@example.net delay 1h autowhite 3d
212
213       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
220                racl blacklist dnsrbl "known-spammer" flushaddr
221
222       nolog  Do not generate syslog message if this rule matches. Example:
223
224                racl whitelist default nolog
225
226       code
227
228       ecode
229
230       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
234                racl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
235                racl greylist default code "451" ecode "4.7.1"
236
237              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
241              None of the last 3 values makes sense for a whitelist entry.
242
243       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
249       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
254       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
265       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
273       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
279       Example 1:
280
281       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
286       Example 2:
287
288       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
294       Example 3:
295
296       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

DATA-STAGE ACL

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
312       dkim   DKIM status (if build with DKIM support).  Possible  values  are
313              pass, fail, unknown, error, and none,
314
315       header String or regular expression searched in message headers
316
317       body   String or regular expression searched in message body
318
319       msgsize
320              Operator  followed  by a message size (k or M suffix allowed for
321              kilobytes or megabytes). Example:
322
323                dacl blacklist msgsize >= 4M msg "No more than 4 MB please"
324
325       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
330              Example 1:
331
332                spamdsock unix "/var/spamassassin/spamd.sock"
333                racl whitelist default
334                dacl greylist spamd
335
336              Example 2:
337
338                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
344       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

LISTS

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
355                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
358                racl whitelist list "local"
359                racl greylist list "my users"
360                racl whitelist default
361
362

BACKWARD COMPATIBILITY

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
372       test  mode  (using -T) is also deprecated. Access-list semantics do not
373       depend on this flag.
374
375       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

MX SYNC

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
386         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
391       You can list the local machine in  the  peer  statements,  it  will  be
392       ignored.
393
394       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
398       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
403         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
409       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
413       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
416         syncsrcaddr 123.456.78.9
417

TEXT DUMP

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
424       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
427       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
433       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

REPORTING

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
447       report none
448              Never add a X-Greylist header.
449
450       report delays
451              Only add a header if the message was delayed.
452
453       report nodelays
454              Add a header if the message was not delayed. The header explains
455              why the message was not delayed.
456
457       report all
458              Always add a header. This is the default.
459

SENDER CALLBACK SYSTEMS

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
467       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
475       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

SENDMAIL MACROS

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
485                sm_macro "maybe_forged" "{client_resolve}" "FORGED"
486
487                racl greylist sm_macro "maybe_forged" delay 1h
488                racl greylist default delay 15m
489
490       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
494                sm_macro "not_foo" "{foo}" unset
495
496       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

DNSRBL

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
507                dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10/32
508
509                racl greylist dnsrbl "SORBS DUN" delay 1h
510                racl greylist default delay 15m
511
512       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
516       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

DNS updates

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
525       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
529                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
533       The options for nsupdate are:
534
535       rname  Created record name, which uses format strings.
536
537       rvalue Created record value, which uses format strings.
538
539       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
544       ttl    TTL of created DNS record. Default is 0 seconds.
545
546       class  Created  record  class,  as  numeric value. Default is 1, for IN
547              class.
548
549       type   Created record type, as numeric value. Default is 1, for A type.
550
551       tsig   The name of a tsig configuration, which must have been  supplied
552              before.  If  unspecified,  unauthenticated  DNS updates are per‐
553              formed.
554
555       Once configured, DNS updates can be used in any ACL:
556
557                racl blacklist rcpt  spamtrap@example.net  nsupdate  "bl.exam‐
558              ple.net"
559

PROPERTIES

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
566       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
573       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
577       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
581       ldapcheck
582              These clause will cause properties to be  fetched  from  a  LDAP
583              directory See the LDAP CHECKS section below for details.
584
585       Properties can be used as left-hand side part of ACL clauses:
586
587                racl blacklist $name "badvalue"
588                racl blacklist $name /badregex/
589
590       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
595                racl blacklist *$domain "%f"
596
597       They are also available as right-hand side of many ACL clauses:
598
599                racl continue set $badword="spam"
600                racl blacklist body $badword
601
602       Values of properties can be obtained in any quoted string that is  sub‐
603       ject to format string expantion:
604
605                racl continue set $webmaster="webmaster@example.net"
606                racl  blacklist  domain evil.net msg "blacklisted, ask $P{web‐
607              master} why"
608
609       When the property value is a number, it can be increased  or  decreased
610       using this syntax:
611
612                racl continue set $score+=5
613                racl continue set $score-=5
614
615       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
621       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

URL checks

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
630                urlcheck "glusr" "http://www.example.net/mgl-config?rcpt=%r" 5
631
632                racl greylist urlcheck "glusr" delay 15m
633                racl whitelist default
634
635       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
641       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
644                milterGreylistStatus: Ok
645
646       TRUE can be used as an alias for Ok here.
647
648       The answer can be more complex, with keys that will  overload  the  ACL
649       settings:
650
651       milterGreylistDelay
652              The greylisting delay to use (time unit suffix allowed).
653
654       milterGreylistAutowhite
655              The autowhite delay to use (time unit suffix allowed).
656
657       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
662       milterGreylistCode
663              The SMTP code to return (e.g.: 551).
664
665       milterGreylistECode
666              The SMTP extended code to return (e.g.: 5.7.1)
667
668       milterGreylistMsg
669              The string to return with SMTP codes.
670
671       milterGreylistReport
672              The string to display in the X-Greylist header.
673
674       milterGreylistIgnore
675              This line will be ignored, without warnings in the logs.
676
677       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
683       The ACL will match if any of the above key is returned: milterGreylist‐
684       Status is not mandatory.
685
686       Optional keywords can be appended to a urlcheck definition:
687
688       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
692                urlcheck "extfilter" "http://www.example.net/f.cgi" 5 postmsg
693
694                dacl blacklist urlcheck "extfilter"
695                dacl whitelist default
696
697       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
702       clear  This causes gathered properties to be cleared on each new recip‐
703              ient.  This avoids properties for several recipients to mix.
704
705       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
709       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
717       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
720                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
726                racl  blacklist  urlcheck  "userconf"  $dnsrbl  "RBL2"  dnsrbl
727              "RBL2"
728                racl blacklist $dnsrbl "RBL3" dnsrbl "RBL3"
729                racl blacklist $dnsrbl "RBL4" dnsrbl "RBL4"
730
731       Note  that  when matching gathered properties, format strings and regex
732       can be used.
733

LDAP CHECKS

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
740       A  list  of LDAP URL to use can be specified with the ldapconf keyword.
741       The network timeout is optional.
742
743                ldapconf "ldap://localhost  ldaps://ldap.example.net"  timeout
744              2s
745
746       When  ldaps://  is  used, the system's ldap.conf file is used to locate
747       x509 certificates.
748
749       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

RATE LIMIT

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
760                ratelimit "internalclients" rcpt 10 / 1m
761
762                racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
763                   msg "you speak too much"
764
765       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
771                ratelimit "internalclients" rcpt 100 / 1h key "%r%i"
772
773                racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
774                   msg "you speak too much"
775

CUSTOM REPORTS

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
781                stat ">>/var/log/milter-greylist.log" "%T{%T},%i,%f,%r,%A\n"
782
783       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
787                stat "|logger -p local7.info" "%T{%T},%i,%f,%r,%A\n"
788
789       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
793       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
797              racl continue rcpt /@example\.com$/ log "I was here"
798

COMMAND-LINE FLAG EQUIVALENTS

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
804       If a command-line equivalent keyword is used more than once,  the  last
805       keyword will override the previous ones.
806
807       verbose
808              Enable debug output. This is equivalent to the -v flag.
809
810       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
813       nodetach
814              Do not fork and go into the background. This  is  equivalent  to
815              the -D flag.
816
817       noauth Greylist  clients  regardless  if  they  succeeded  SMTP AUTH or
818              STARTTLS.  Equivalent to the -A flag.
819
820       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
826       nospf  Greylist  clients  regardless if they are SPF-compliant. Equiva‐
827              lent to the -S flag.
828
829       testmode
830              Enable test mode. Equivalent to the -T flag. This option is dep‐
831              recated.
832
833       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
841                greylist 45m
842
843       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
848                autowhite 3d
849
850       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
856                pidfile "/var/run/greylist.pid"
857
858       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
864                dumpfile "/var/lib/milter-greylist/db/greylist.db" 640
865
866       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
871                subnetmatch /24
872
873       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
878                subnetmatch6 /64
879
880       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
886                socket "/run/milter-greylist/milter-greylist.sock" 660
887
888       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
893                user "smmsp"
894

MISCELLANEOUS

896       These options have no command line equivalent:
897
898       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
904       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
909       extendedregex
910              Use  extended  regular  expressions  instead  of  basic  regular
911              expressions.
912
913       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
918       maxpeek
919              Limit (in bytes) how much of messages are  examined  for  header
920              and body searches.
921
922       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
925       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
933       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
937                drac db "/usr/local/etc/drac.db"
938
939       nodrac Disable DRAC.
940
941       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
948       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
956       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
961       The dumpfreq option can be changed dynamically,  but  the  change  will
962       only take effect after the next dump.
963
964       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

FORMAT STRINGS

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
975       %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
979       %f     the message sender e-mail address
980
981       %i     the sender machine IP address
982
983       %j     the reversed sender machine IP address. For instance, 192.0.2.12
984              becomes 12.2.0.192.
985
986       %I     the sender machine IP address masked by a CIDR. Example: %I{/24}
987
988       %d     the sender machine DNS address
989
990       %h     the SMTP transaction HELO string
991
992       %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
996       %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
1000       %mf    the mailbox part of %f (before the @ sign)
1001
1002       %sf    the site part of %f (after the @ sign)
1003
1004       %md    the machine part of %d (before the first . sign)
1005
1006       %sd    the site part of %d (after the first . sign)
1007
1008       %Xc    the SMTP code returned
1009
1010       %Xe    the SMTP extended code returned
1011
1012       %Xm    the SMTP message returned
1013
1014       %Xh    the message displayed in the X-Greylist header
1015
1016       %D     Comma-separated list of DNSRBL for which the sender host matched
1017
1018       %M     a sendmail macro value. Examples: %Mj or %M{if_addr}
1019
1020       %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
1024       %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
1027       %v     milter-greylist's version
1028
1029       %G     Offset to GMT (e.g.: -0100)
1030
1031       %C     Sender IP country code, as  reported  by  GeoIP.  This  is  only
1032              available if milter-greylist was built with GeoIP support
1033
1034       %Fx    p0f  OS  fingerprint genre and detail. This is only available if
1035              milter-greylist was built with p0f support.
1036
1037       %V     Shortcut to "milter-greylist-%v (%Mj [%M{if_addr}]);  %T{%a,  %d
1038              %b %Y %T} %G (%T{%Z})"
1039
1040       %S     the action performed: accept, tempfail, or reject.
1041
1042       %A     the line number of the ACL that caused the action.
1043
1044       %a     the  id  string  of the ACL that caused the action. If no id was
1045              given, the line number is used instead.
1046
1047       %cA    the line number of the ACL being evaluated, whether  it  matches
1048              or not.
1049
1050       %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
1053       %Et    total elapsed time in seconds before a  greylisted  message  has
1054              been accepted
1055
1056       %Eh    hours elapsed
1057
1058       %Em    minutes elapsed (modulo one hour)
1059
1060       %Es    seconds elapsed (modulo one minute)
1061
1062       %E     shortcut to %Eh:%Em:Es
1063
1064       %Rt    total remaining time in seconds before a greylisted message will
1065              be accepted
1066
1067       %Rh    hours remaining
1068
1069       %Rm    minutes remaining (modulo one hour)
1070
1071       %Rs    seconds remaining (modulo one minute)
1072
1073       %R     shortcut to %Rh:%Rm:Rs
1074
1075       %Hs    SpamAssassin score (if build with SpamAssassin support)
1076
1077       %pn    Name of last LDAP or CURL gathered property that matched an ACL.
1078
1079       %pv    Value of last LDAP or CURL gathered  property  that  matched  an
1080              ACL.
1081
1082       %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
1087       %Qd    DKIM query result (pass, fail, etc.), if built  with  DKIM  sup‐
1088              port.
1089
1090       %Qs    SPF  query  result  (pass,  (soft)fail, etc.), if built with SPF
1091              support.
1092
1093       %QA    Authentication results  summary,  suitable  for  Authentication-
1094              Results  header. Will included formatted query results from DKIM
1095              and SPF if checked.
1096
1097       %QS    SPF result, suitable for  Received-SPF  header.  Available  when
1098              compiled with libspf2.
1099
1100       %%     a single % character
1101

AUTHORS

1103       Emmanuel Dreyfus <manu@netbsd.org>
1104
1105       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
1126       Thanks to Helmut Messerer and Thomas Pfau for  their  feedback  on  the
1127       first releases of this software.
1128

SEE ALSO

1130       milter-greylist(8), sendmail(8), syslogd(8).
1131
1132       Evan Harris's paper:
1133              http://projects.puremagic.com/greylisting/
1134
1135       milter-greylist's web site:
1136              http://hcpnet.free.fr/milter-greylist/
1137
1138
1139
1140                                 May 10, 2005                 greylist.conf(5)
Impressum