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.  geoip2db statement can be used to specify the location of
125              GeoIP2 (maxminddb) database.
126
127       p0f    This  is  used to match against the remote system OS fingerprint
128              genre and detail,obtained from p0f. It is only available if mil‐
129              ter-greylist  was  built  with  p0f support.  p0f clauses can be
130              used with a quoted string for case-insensitive substring  match,
131              or  against  regular  expressions.  The p0fsock statement can be
132              used to specify the location of the p0f socket.
133
134       auth   This is used to select a user that succeeded SMTP AUTH. In order
135              to  select any user that succeeds SMTP AUTH, you can use a regu‐
136              lar expression matching, like below;
137
138                racl whitelist auth /.*/
139
140              Using such a clause automatically disable  global  STARTTLS  and
141              SMTP  AUTH  whitelisting,  like if the noauth keyword would have
142              been used.
143
144       tls    This is used to select the distinguished name  (DN)  of  a  user
145              that  succeeded STARTTLS. Using such a clause automatically dis‐
146              able global STARTTLS and SMTP AUTH  whitelisting,  like  if  the
147              noauth keyword would have been used.
148
149       spf    This is used to test SPF status. Possible values are pass, soft‐
150              fail, fail, neutral, unknown, error, none, and self.  The  first
151              seven  values are plain SPF validation status. The self value is
152              a special test that checks the server's local IP address against
153              the  sender's  SPF record. If that test validates, odds are good
154              that the sender SPF record is wide open, and this is  hint  that
155              SPF should not be trusted.
156
157              In  order  to use spf self, Postfix users must specify the local
158              address in the configuration file, using the localaddr option.
159
160              Absence of any value after the spf keyword is a synonym for  spf
161              pass.  This is present for backward compatibility.
162
163              The spf clause is only available if SPF support was compiled in.
164              Using it will disable global SPF whitelisting, like if the nospf
165              keyword would have been used.
166
167       ldapcheck
168              This  is  used  to  query an LDAP directory.  See the section on
169              that topic for more information.
170
171       urlcheck
172              This is used to query an external configuration  source  through
173              an URL.  See the section on that topic for more information.
174
175       dnsrbl This  is  used to select a DNSRBL. See the section on that topic
176              for more information.
177
178       nsupdate
179              This always-matching clause performs a DNS update, see the  sec‐
180              tion on that topic for more information.
181
182       The  domain,  from,  and  rcpt clauses may be used with regular expres‐
183       sions. The regular expressions must be  enclosed  by  slashes  (/).  No
184       escaping  is  available to provide a slash inside a regular expression,
185       so just do not use it. Regular expressions follow the format  described
186       in re_format(7).  Here is an example:
187
188         racl greylist rcpt /@example\.net$/
189
190       When  regular  expressions  are not used, from, and rcpt perform a case
191       insensitive substring match with leading and trailing brackets,  spaces
192       and  tabs  stripped  out.   domain  performs  a case insensitive suffix
193       match.  This means, for example, that gle.com will match google.com. If
194       you  want  domain names to match on subdomain boundaries (e.g.  gle.com
195       will match mail.gle.com and gle.com but  not  google.com)  then  enable
196       domainexact
197
198       An  ACL  entry  can also hold various optional parameter used on match:
199       delay, autowhite,  flushaddr,  nolog,  code,  ecode,  report,  maxpeek,
200       addheader, addfooter, and msg
201
202       delay  Specify  the  greylisting  delay  used before the message can be
203              accepted.  This overrides the greylist global  setting,  and  it
204              only  makes sense on an racl greylist entry.
205
206       autowhite
207              Specify the autowhitelisting duration for messages matching this
208              ACL.  This overrides the autowhite global setting, and  it  only
209              makes sense on an racl greylist entry. Example:
210
211                racl greylist rcpt JDoe@example.net delay 15m autowhite 3d
212                racl greylist rcpt root@example.net delay 1h autowhite 3d
213
214       flushaddr
215              If  a  message  matches  the  rule, any entry in the greylist or
216              autowhite databases matching the sender IP is removed. Used with
217              a  DNSRBL  blacklist  ACL, it is useful for freeing the database
218              from entries set up by a machine which is known to be a spammer.
219              Example:
220
221                racl blacklist dnsrbl "known-spammer" flushaddr
222
223       nolog  Do not generate syslog message if this rule matches. Example:
224
225                racl whitelist default nolog
226
227       code
228
229       ecode
230
231       msg    These  3  values  can  be used to choose the SMTP code, extended
232              code and reply message for temporary failures and rejects. Exam‐
233              ple:
234
235                racl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
236                racl greylist default code "451" ecode "4.7.1"
237
238              The msg strings accepts format string substitution as documented
239              in the FORMAT STRINGS section. For instance, %A gets substituted
240              by the ACL line number.
241
242              None of the last 3 values makes sense for a whitelist entry.
243
244       report This  value  overrides  the  text  displayed  in  the X-Greylist
245              header, for messages that milter-greylist(8) lets pass  through,
246              either  because  they  are  whitelisted,  or because they passed
247              greylisting (see REPORTING).  This string can be substituted  as
248              documented in the FORMAT STRINGS section.
249
250       maxpeek
251              This  parameter  only  makes sense in a RCPT-stage ACL. It over‐
252              rides the global maxpeek setting for DATA-stage handling of  the
253              message. It has no effect if global maxpeek is set to 0.
254
255       addheader
256              This  quoted  string  is  a RFC822 header that gets added to the
257              message.  Format string substitution is supported. No  check  is
258              done  for  header  length  standard compliance, so make sure the
259              substituted string is shorter than 2048 characters. Headers  are
260              appended to the bottom, unless an optionnal comma-separated pos‐
261              itive index is specified after the quoted string; in  this  case
262              the  header  will  be inserted at this index point from the top.
263              Here is an example:
264              racl continue addheader "X-Personnal-Header: Hello world!",1
265
266       addfooter
267              Append a footer to the message. Usual escape sequences  such  as
268              \n  can be used to get special characters. The string is subject
269              to format string expantion as described in  the  FORMAT  STRINGS
270              section.  The  footer  will not be append if milter-greylist was
271              not able to capture the whole message, therefore maxpeek must be
272              set approriately.
273
274       Entries in the access-list are evaluated sequentially, so order is very
275       important. The first matching entry is used to decide if a message will
276       be  whitelisted  or greylisted. A special default clause can be used in
277       the last ACL entry as a wildcard.  Here are a few  complete  ACL  exam‐
278       ples:
279
280       Example 1:
281
282       racl whitelist from friend@toto.com rcpt grandma@example.com
283       racl whitelist from other.friend@example.net rcpt grandma@example.com
284       racl greylist rcpt grandma@example.com
285       racl whitelist default
286
287       Example 2:
288
289       racl whitelist addr 193.54.0.0/16 domain friendly.com
290       racl greylist rcpt user1@atmine.com
291       racl greylist rcpt user2@atmine.com
292       racl greylist rcpt user3@atmine.com
293       racl whitelist default
294
295       Example 3:
296
297       racl whitelist rcpt /@.*otherdomain\.org$/
298       racl whitelist addr 192.168.42.0/24 rcpt user1@mydomain.org
299       racl whitelist from friend@example.net rcpt /@.*mydomain\.org$/
300       racl whitelist rcpt user2@mydomain.org
301       racl greylist rcpt /@.*mydomain\.org$/
302       racl whitelist default
303

DATA-STAGE ACL

305       ACL  using the racl keyword are evaluated at the RCPT stage of the SMTP
306       transaction. It is also possible to have  ACL  evaluated  at  the  DATA
307       stage  of  the  SMTP  transaction, using the dacl keyword, provided the
308       message went through RCPT-stage ACL,  and  possibly  greylisting.  Note
309       that you cannot use the greylist action at DATA-stage if the RCPT-stage
310       ACL that matched had a greylist action itself.  The  following  clauses
311       can be used to work on message content:
312
313       dkim   DKIM  status  (if  build with DKIM support). Possible values are
314              pass, fail, unknown, error, and none,
315
316       header String or regular expression searched in message headers
317
318       body   String or regular expression searched in message body
319
320       msgsize
321              Operator followed by a message size (k or M suffix  allowed  for
322              kilobytes or megabytes). Example:
323
324                dacl blacklist msgsize >= 4M msg "No more than 4 MB please"
325
326       spamd  SpamAssassin score (if build with SpamAssassin support). If used
327              without comparison operator spamd is true if the score is  above
328              threshold.  The  spamdsock  keyword  can  be used to specify the
329              location of the spamd socket.
330
331              Example 1:
332
333                spamdsock unix "/var/spamassassin/spamd.sock"
334                racl whitelist default
335                dacl greylist spamd
336
337              Example 2:
338
339                spamdsock inet "127.0.0.1:783"
340                racl whitelist default
341                dacl blacklist spamd > 15 msg "Your message is considered spam."
342                dacl greylist  spamd > 10 delay 2h
343                dacl greylist  spamd > 5  delay 1h
344
345       Note that if there are multiple recipient, a rcpt clause at DATA  stage
346       evaluates  to  true if it matches any of them.  If you want to match an
347       exact set of recipients, you can use multiple rcpt clauses along with a
348       rcptcount clause.
349

LISTS

351       It  is  often useful to group several users or sender IP addresses in a
352       single ACL. This can be done with lists. Lists must  be  first  defined
353       and  given  a  name  before they can be used in ACL entries. Here is an
354       example:
355
356                list "my users" rcpt { user1@example.com user2@example.com }
357                list "local" addr { 192.0.2.0/24 10.0.0.0/8 }
358
359                racl whitelist list "local"
360                racl greylist list "my users"
361                racl whitelist default
362
363

BACKWARD COMPATIBILITY

365       Previous versions of milter-greylist(8) used addr,  domain,  from,  and
366       rcpt  lines,  without  the  racl  keyword.   Access-list  management is
367       intended to replace them.  These lines are still  accepted  by  milter-
368       greylist(8),  but they are deprecated.  milter-greylist(8) handles them
369       as access-list entries with a single clause. They are added at the head
370       of  the  access-list  so the use of these keywords and access-lists may
371       lead to unspecified behaviour. Do not mix them.
372
373       test mode (using -T) is also deprecated. Access-list semantics  do  not
374       depend on this flag.
375
376       milter-greylist(8)  also  used to only have a RCPT-stage ACL, which was
377       configured through acl statements. These have  been  replaced  by  racl
378       statements  (as  opposed  to  dacl statements for DATA-stage ACL).  acl
379       statements are still accepted for backward compatibility and are a syn‐
380       onym for racl statements.
381

MX SYNC

383       Synchronization  of  the greylist among multiple MX is configured using
384       the peer keyword. List each other MX IP addresses using the  peer  key‐
385       word. Here is an example:
386
387         peer 192.0.2.18
388         peer 192.0.2.17
389         peer 192.0.2.22 timeout 7
390         peer 192.0.2.38 timeout 5m
391
392       You  can  list  the  local  machine  in the peer statements, it will be
393       ignored.
394
395       The timeout clause sets a peer communication  timeout  to  have  proper
396       retrial  in  case  of slow MX peer. The default value is 3 seconds. The
397       special value of 0 disables the connection retrials.
398
399       By default, milter-greylist will listen on  all  interfaces  using  TCP
400       port 5252 or the port number given by service named mxglsync if defined
401       in /etc/services or other directory  service.  This  behaviour  can  be
402       changed by using the syncaddr keyword. Here are a few examples:
403
404         syncaddr *
405         syncaddr * port 7689
406         syncaddr 192.0.2.2 port 9785
407         syncaddr 2001:db8::1:c3b5:123
408         syncaddr 2001:db8::1:c3b5:123 port 1234
409
410       Using  '*'  as  the  address  means  to  bind  to all local interfaces'
411       addresses.  Note that if you are not using the default  port,  all  MXs
412       must use the same port number.
413
414       For  outbound  connections  the system is selecting one of the possible
415       addresses.  If you want to use a specific IP you can use:
416
417         syncsrcaddr 123.456.78.9
418

TEXT DUMP

420       milter-greylist(8) uses a text dump of its database to resume operation
421       after  a  crash. The dump is performed at regular time interval, but as
422       it is a heavy operation, you might want to configure a particular  time
423       interval, using the dumpfreq option.
424
425       If  the dumpfreq value is too small, it will kill performance. If it is
426       too high, you will loose a bigger part of the database on a crash.
427
428       Set dumpfreq to 0 to get a dump on each change (kills performance), Set
429       it to -1 to never dump to a file (unsafe as you lose the whole greylist
430       on each crash), or give a time value for the delay between dumps.   The
431       time  is  given in seconds, except if a unit is given: m for minutes, h
432       for hours, and d for days.
433
434       You may further improve the performance of the dump  operation  at  the
435       expense  of  humanly  readable  timestamp which by default appears as a
436       comment at the end of each line in the dumpfile. You may disable gener‐
437       ation  of this comment by specifying dump_no_time_translation option in
438       the configuration file. This is specifically recommended if your  dump‐
439       file  grows  to  100's of megabytes - it can reduce the time needed for
440       the dump operation by the order of magnitude!
441

REPORTING

443       By default, milter-greylist(8) will add a X-Greylist header to any mes‐
444       sage it handles. The header shows what happened to the message: delayed
445       or not  delayed,  and  why.  The  following  options  can  be  used  in
446       greylist.conf to alter this behavior:
447
448       report none
449              Never add a X-Greylist header.
450
451       report delays
452              Only add a header if the message was delayed.
453
454       report nodelays
455              Add a header if the message was not delayed. The header explains
456              why the message was not delayed.
457
458       report all
459              Always add a header. This is the default.
460

SENDER CALLBACK SYSTEMS

462       Sender callback systems are another anti-spam measure that attempts  to
463       send  a  DSN  to the sender address before accepting a message. If that
464       fails, then the sender address is wrong and the  message  is  rejected.
465       Such systems usually stop their callback check at the RCPT stage of the
466       SMTP transaction.
467
468       Greylisting temporarily rejects at the RCPT stage, so  sender  callback
469       and  greylisting love to fight each other.  milter-greylist(8) proposes
470       a workaround to that problem with the delayedreject  option.  For  mes‐
471       sages  coming  from  <> (that is, for DSN), it will cause the temporary
472       reject to happen at the DATA stage of the SMTP transaction  instead  of
473       the RCPT stage. That way, milter-greylist(8) will cope much better with
474       sender callback systems.
475
476       This has a minor drawback (and  this  is  why  it  is  not  enabled  by
477       default):  for a multi recipient DSN, whitelisted recipient will not be
478       honoured: the message will be delayed for everyone.
479

SENDMAIL MACROS

481       Any sendmail macro can be used as a clause in the access list. You need
482       to define a (macro, value) pair using the sm_macro keyword before using
483       it.  Here is an example that uses the {client_resolve} macro to apply a
484       larger greylisting delay to hosts that have a bogus reverse DNS:
485
486                sm_macro "maybe_forged" "{client_resolve}" "FORGED"
487
488                racl greylist sm_macro "maybe_forged" delay 1h
489                racl greylist default delay 15m
490
491       A  regular  expression can be used as the macro value.  It must be sur‐
492       rounded with slashes and not by quotes.  The special  value  unset  can
493       also be used to match an unset macro:
494
495                sm_macro "not_foo" "{foo}" unset
496
497       Note  that  any  Sendmail  macro  that  is  not exported using the Mil‐
498       ter.macros.envrcpt setting of sendmail.cf will be seen  as  unset  from
499       milter-greylist.
500

DNSRBL

502       DNS  Reverse  Black  List  can  be  used to toggle an ACL. They must be
503       defined and named before they can be used. Here  is  an  example  which
504       uses  a  bigger greylisting delay for hosts caught in the SORBS dynamic
505       pool DNRSBL (this will include DSL and cable customers pools, which are
506       well known to be massively infected by spamwares):
507
508                dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10/32
509
510                racl greylist dnsrbl "SORBS DUN" delay 1h
511                racl greylist default delay 15m
512
513       The  definition  of  a DNSRBL starts by the dnsrbl keyword, followed by
514       the quoted name of the DNSRBL, the DNS domain on which addresses should
515       be looked up, and the answer we should consider as a positive hit.
516
517       DNSRBL support is only available if enabled through the --enable-dnsrbl
518       config flag. Please make sure milter-greylist(8) is  linked  against  a
519       thread-safe DNS resolver, otherwise it shall crash.
520

DNS updates

522       ACL  are  able  to  trigger  a  DNS update, which can be used to feed a
523       DNSRBL.  That functionnality is  enabled  at  build  time  if  the  DNS
524       resolver has DNS update support.
525
526       Configuration  is  done  with the nsupdate statement, which may be used
527       several times, and the optionnal tsig statement, if  you  want  ot  use
528       authenticated DNS update. Here is an example syntax:
529
530                tsig "dns-update" "hmac-md5" "1B2M2Y8AsgTpgAmY7PhCfg=="
531                nsupdate  "bl.example.net"  { rname "%j.bl.example.net" rvalue
532              "127.0.0.2" tsig "dns-update" }
533
534       The options for nsupdate are:
535
536       rname  Created record name, which uses format strings.
537
538       rvalue Created record value, which uses format strings.
539
540       servers
541              Quoted comma-separated list of DNS server the update  should  be
542              sent  to.   Default  is to use the system confifugration, usualy
543              from /etc/resolv.conf
544
545       ttl    TTL of created DNS record. Default is 0 seconds.
546
547       class  Created record class, as numeric value. Default  is  1,  for  IN
548              class.
549
550       type   Created record type, as numeric value. Default is 1, for A type.
551
552       tsig   The  name of a tsig configuration, which must have been supplied
553              before. If unspecified, unauthenticated  DNS  updates  are  per‐
554              formed.
555
556       Once configured, DNS updates can be used in any ACL:
557
558                racl  blacklist  rcpt  spamtrap@example.net nsupdate "bl.exam‐
559              ple.net"
560

PROPERTIES

562       Properties are variables that can be set, evaluated and printed in ACL.
563       A  property  may be dropped once the current recipient is processed, or
564       it can be retained until the message is processed. They can be  created
565       through the following always-matching ACL clauses:
566
567       set $name="value"
568              This  sets a property that will be retained for all next recipi‐
569              ents. Right hand side of the  clause  may  be  a  quoted  string
570              (which will be substituted using format strings, as described in
571              the FORMAT STRINGS section), a number, or another property  name
572              (which will be substituted by the property value).
573
574       rset $name="value"
575              Same as set clause, except that the property will be droped once
576              the current user will have been processed.
577
578       urlcheck
579              These clause will cause properties to be fetched from an  exter‐
580              nal web service.  See the URL checks section below for details.
581
582       ldapcheck
583              These  clause  will  cause  properties to be fetched from a LDAP
584              directory See the LDAP CHECKS section below for details.
585
586       Properties can be used as left-hand side part of ACL clauses:
587
588                racl blacklist $name "badvalue"
589                racl blacklist $name /badregex/
590
591       If used left-hand side and prefixed by a star,  the  property  will  be
592       evaluated  as  a  glob(7)  pattern, In the example below, if sender DNS
593       domain is test.example.net and  $domain  is  *.example.net,  we  get  a
594       match.
595
596                racl blacklist *$domain "%f"
597
598       They are also available as right-hand side of many ACL clauses:
599
600                racl continue set $badword="spam"
601                racl blacklist body $badword
602
603       Values  of properties can be obtained in any quoted string that is sub‐
604       ject to format string expantion:
605
606                racl continue set $webmaster="webmaster@example.net"
607                racl blacklist domain evil.net msg "blacklisted,  ask  $P{web‐
608              master} why"
609
610       When  the  property value is a number, it can be increased or decreased
611       using this syntax:
612
613                racl continue set $score+=5
614                racl continue set $score-=5
615
616       Here again, right hand side may be a quoted string, a number or another
617       property.  For  the  quoted  string and property cases, a conversion is
618       first made to an integer, using 0 as a value on failure. Note  that  no
619       arithmetic  evaluation  occurs. For instance, the quoted string "1 + 1"
620       will be evaluated as 0.
621
622       The log ACL clause can be helpful when one need to figure what  happens
623       to  property  values during the ACL flow. See the CUSTOM REPORT section
624       for more details.
625

URL checks

627       milter-greylist(8) is able to query  external  sources  of  information
628       through  various  URL,  if it was built with --with-libcurl. Here is an
629       example:
630
631                urlcheck "glusr" "http://www.example.net/mgl-config?rcpt=%r" 5
632
633                racl greylist urlcheck "glusr" delay 15m
634                racl whitelist default
635
636       The trailing 5 at the end of the urlcheck  definition  is  the  maximum
637       number  of  simultaneous connections we want to launch on this URL. For
638       each message, the URL will be queried, with  % format tags  being  sub‐
639       stituted.  For  instance,  %r  is substituted by the recipient. See the
640       FORMAT STRINGS section for the complete list of substitutions.
641
642       milter-greylist(8) expects an answer containing a list of \n terminated
643       lines, with key: value pairs. The most basic answer to get a match is:
644
645                milterGreylistStatus: Ok
646
647       TRUE can be used as an alias for Ok here.
648
649       The  answer  can  be more complex, with keys that will overload the ACL
650       settings:
651
652       milterGreylistDelay
653              The greylisting delay to use (time unit suffix allowed).
654
655       milterGreylistAutowhite
656              The autowhite delay to use (time unit suffix allowed).
657
658       milterGreylistFlushAddr
659              The value is ignored. If  this  key  is  present,  then  the  IP
660              address for the sender machine will be flushed from greylist and
661              autowhite databases.
662
663       milterGreylistCode
664              The SMTP code to return (e.g.: 551).
665
666       milterGreylistECode
667              The SMTP extended code to return (e.g.: 5.7.1)
668
669       milterGreylistMsg
670              The string to return with SMTP codes.
671
672       milterGreylistReport
673              The string to display in the X-Greylist header.
674
675       milterGreylistIgnore
676              This line will be ignored, without warnings in the logs.
677
678       milterGreylistAction
679              This feature is nifty but use it with caution, as it  makes  the
680              access  list  a  bit  difficult to understand. By specifying the
681              values greylist, whitelist, or  blacklist,  it  is  possible  to
682              overload the ACL action itself.
683
684       The ACL will match if any of the above key is returned: milterGreylist‐
685       Status is not mandatory.
686
687       Optional keywords can be appended to a urlcheck definition:
688
689       postmsg
690              On DATA-stage ACL, This causes the message to  be  sent  (up  to
691              maxpeek bytes) in a POST request. Here is an example:
692
693                urlcheck "extfilter" "http://www.example.net/f.cgi" 5 postmsg
694
695                dacl blacklist urlcheck "extfilter"
696                dacl whitelist default
697
698       getprop
699              Gather  the properties returned by the URL and reuse them in the
700              ACL.  The gathered properties can be accessed in the current and
701              following ACL by prefixing them by a dollar ($).
702
703       clear  This causes gathered properties to be cleared on each new recip‐
704              ient.  This avoids properties for several recipients to mix.
705
706       fork   Tells milter-greylist(8) to fork a separate instance  of  itself
707              for  performing  the  queries.  Use  it if you encounter thread-
708              safety problems.  fork is not compatible with postmsg.
709
710       domatch
711              Cause the ldapcheck clause  to  be  evaluated  in  ACL.  Default
712              behavior  is  to  ignore  the  result and just fecth properties,
713              except if the LDAP directory is unreachecable, in which  case  a
714              temporary failure occurs.  The fixldapcheck gloabal settings may
715              also be used to globaly cause all ldapcheck and urlcheck clauses
716              to match.
717
718       Here  is  an  example  that will use various DNSRBL depending on a per-
719       recipient setting stored in the dnsrbl attribute of a LDAP directory.
720
721                dnsrbl "RBL2" "rbl.example.net" "127.0.0.2"
722                dnsrbl "RBL3" "rbl.example.net" "127.0.0.3"
723                dnsrbl "RBL4" "rbl.example.net" "127.0.0.4"
724                urlcheck  "userconf"  "ldap://localhost/dc=example,dc=net?mil‐
725              terGreylistStatus,dnsrbl?one?mail=%r" 5 getprop clear
726
727                racl  blacklist  urlcheck  "userconf"  $dnsrbl  "RBL2"  dnsrbl
728              "RBL2"
729                racl blacklist $dnsrbl "RBL3" dnsrbl "RBL3"
730                racl blacklist $dnsrbl "RBL4" dnsrbl "RBL4"
731
732       Note that when matching gathered properties, format strings  and  regex
733       can be used.
734

LDAP CHECKS

736       If  milter-greylist  was  built with --with-openldap, then you can also
737       use ldapcheck for pulling information  from  an  LDAP  directory.  This
738       works  exactly  like  urlcheck,  except that properties are always col‐
739       lected: The getprop option is implicit.
740
741       A list of LDAP URL to use can be specified with the  ldapconf  keyword.
742       The network timeout is optional.
743
744                ldapconf  "ldap://localhost  ldaps://ldap.example.net" timeout
745              2s
746
747       When ldaps:// is used, the system's ldap.conf file is  used  to  locate
748       x509 certificates.
749
750       When  defining LDAP queries with the ldapcheck statement, note that the
751       scheme and host part of the URL are ignored.  Servers listed  in  ldap‐
752       conf are used instead.
753

RATE LIMIT

755       The ratelimit keyword specifies a ratelimit configuration to be used in
756       access lists. It must be followed by the rate limit configuration name,
757       what  is  being  accounted  (i.e.:  session for SMTP sessions, rcpt for
758       recipients, data for bytes in body and headers), the actual limit,  and
759       the sampling period. Example:
760
761                ratelimit "internalclients" rcpt 10 / 1m
762
763                racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
764                   msg "you speak too much"
765
766       The ratelimit keyword can also have  an  option  key  statement,  which
767       determine  the set of key for message accounting. The default is %i for
768       per IP address accounting (see the FORMAT STRINGS sections for the pos‐
769       sible  syntax of this field). Here is an example that configures a rate
770       limit of 100 messages per hour for each individual recipient-IP set.
771
772                ratelimit "internalclients" rcpt 100 / 1h key "%r%i"
773
774                racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
775                   msg "you speak too much"
776

CUSTOM REPORTS

778       The  stat  keyword  can  be used to specify a custom report for milter-
779       greylist activity.  It should be supplied with an output  (either  file
780       or external command) and a format string. Here is an example:
781
782                stat ">>/var/log/milter-greylist.log" "%T{%T},%i,%f,%r,%A\n"
783
784       If  the output starts by >> or > then it is a file. Use >> to append to
785       an existing file, and use > to overwrite it. If the output starts by  a
786       | then the output is a shell command, like in the example below:
787
788                stat "|logger -p local7.info" "%T{%T},%i,%f,%r,%A\n"
789
790       The format string gets substituted as URL checks format string: %r gets
791       substituted by the recipient, %f by the sender, and so on. See the FOR‐
792       MAT STRINGS section for a complete list of available substitutions.
793
794       There  is  also  an  always-matching log ACL clause that can be used to
795       send a formated string to syslog with LOG_INFO level.  Here is an exam‐
796       ple:
797
798              racl continue rcpt /@example\.com$/ log "I was here"
799

COMMAND-LINE FLAG EQUIVALENTS

801       Most  milter-greylist(8)  command-line  options have equivalent options
802       that can be set in the configuration file. Note that if a command  line
803       option is supplied, it will always override the configuration file.
804
805       If  a  command-line equivalent keyword is used more than once, the last
806       keyword will override the previous ones.
807
808       verbose
809              Enable debug output. This is equivalent to the -v flag.
810
811       quiet  Do not tell clients how much time remains  before  their  e-mail
812              will be accepted. This is equivalent to the -q flag.
813
814       nodetach
815              Do  not  fork  and go into the background. This is equivalent to
816              the -D flag.
817
818       noauth Greylist clients regardless  if  they  succeeded  SMTP  AUTH  or
819              STARTTLS.  Equivalent to the -A flag.
820
821       noaccessdb
822              Normally  milter-greylist(8)  will  whitelist a message if send‐
823              mail(8) defines a ${greylist} macro set to WHITE.  This  enables
824              complex whitelisting rules based on the Sendmail access DB. This
825              option inhibits this behavior.
826
827       nospf  Greylist clients regardless if they are  SPF-compliant.  Equiva‐
828              lent to the -S flag.
829
830       testmode
831              Enable test mode. Equivalent to the -T flag. This option is dep‐
832              recated.
833
834       greylist
835              The argument sets how much time milter-greylist(8) will want the
836              client  to  wait between the first attempt and the time the mes‐
837              sage is accepted. The time is given in seconds, except if a unit
838              is  given:  m  for  minutes,  h  for hours, and d for days.  The
839              greylist keyword is equivalent to the  -w  option.  Here  is  an
840              example that sets the delay to 45 minutes:
841
842                greylist 45m
843
844       autowhite
845              This  sets  the auto-whitelisting duration, equivalent to the -a
846              command-line option. As for the greylist keyword, units  can  be
847              supplied. Here is an example for a 3 day long auto-whitelisting:
848
849                autowhite 3d
850
851       pidfile
852              This  causes  milter-greylist(8)  to write its PID into the file
853              given as argument, like the -P command line argument  does.  The
854              path  to  the  file  must be absolute and it must be enclosed in
855              quotes. Here is an example:
856
857                pidfile "/var/run/greylist.pid"
858
859       dumpfile
860              This chooses the location of the greylist dump file, like the -d
861              command line option does. The path must be absolute and enclosed
862              in quotes.  It can optionally be followed by an octal permission
863              mode.  Example:
864
865                dumpfile "/var/lib/milter-greylist/db/greylist.db" 640
866
867       subnetmatch
868              This  is  equivalent  to  the -L command line option. It takes a
869              slash followed by a CIDR mask as argument, and it  commands  the
870              subnet matching feature. Example, for a class C wide matching:
871
872                subnetmatch /24
873
874       subnetmatch6
875              This  is  equivalent  to  the -M command line option. It takes a
876              slash followed by a prefixlen as argument, and it  commands  the
877              subnet matching feature. Example, for a subnet wide matching:
878
879                subnetmatch6 /64
880
881       socket Like the -p command line option, this keyword is used to specify
882              the socket used to communicate with  sendmail(8).   It  must  be
883              enclosed  in  quotes  and can optionally be followed by an octal
884              permission mode (valid values are 666, 660 or 600, other  values
885              cause an error):
886
887                socket "/run/milter-greylist/milter-greylist.sock" 660
888
889       user   This  keyword  should  be  followed  by  a quoted user login and
890              optionally a colon followed by a groupname.  Like the -u option,
891              this is used to run milter-greylist(8) as a non root user.  Here
892              is an example:
893
894                user "smmsp"
895

MISCELLANEOUS

897       These options have no command line equivalent:
898
899       logfac Sets the syslog facility for messages.  Can be set to any of the
900              standard  facilities:  kern,  user,  mail, daemon, auth, syslog,
901              lpr, news, uucp, cron, authpriv, ftp,  local0,  local1,  local2,
902              local3, local4, local5, local6, local7.  Can also be set to none
903              to disable syslog output completely.
904
905       timeout
906              is used to control how long greylist tuples are retained in  the
907              database.   Value  is in seconds, except if a suffix is given (m
908              for minutes, h for hours, d for days). Default is 5 days.
909
910       extendedregex
911              Use  extended  regular  expressions  instead  of  basic  regular
912              expressions.
913
914       unbracket
915              Attempt  to  resolve  sender  address  when the MTA handed it as
916              bracketed IP address (e.g.: [192.0.2.18] ). Default is to  leave
917              it as is.
918
919       maxpeek
920              Limit  (in  bytes)  how much of messages are examined for header
921              and body searches.
922
923       lazyaw Make auto-whitelist look at just the IP instead of  the  (sender
924              IP, sender e-mail address, recipient e-mail address) tuple.
925
926       domainexact
927              match  on  subdomain  boundaries  instead  of the default suffix
928              matching.  E.g. if domainexact is not enabled (the default) then
929              gle.com  will  match  google.com  in  addition  to  gle.com.  If
930              domainexact is enabled then, domain names will match  on  subdo‐
931              main  boundaries  (e.g.   gle.com  will  match  mail.gle.com and
932              gle.com but not google.com)
933
934       drac db
935              Tell where the DRAC DB file is. This is only available  if  DRAC
936              support was compiled in. Here is an example:
937
938                drac db "/usr/local/etc/drac.db"
939
940       nodrac Disable DRAC.
941
942       logexpired
943              This option causes greylist entries that expire to be logged via
944              syslog.  This allows you to easily collect the IP addresses  and
945              sender  names  and use them for blacklisting, SPAM scoring, etc.
946              Normally, expiration's are only logged if the  debug  option  is
947              set, but that generates a lot of extra messages.
948
949       localaddr
950              This  keyword  can be used to manually define the local MTA's IP
951              address for such uses as spf self and p0f in absence of the mil‐
952              ter-API {if_addr} macro support in your MTA (Postfix, Sun/Oracle
953              CommSuite Messaging Server).  This is not so useful  when  using
954              Sendmail, since it serves the macro and the local address can be
955              detected automatically.
956
957       The configuration file is reloaded automatically once  it  is  modified
958       when  new  e-mail arrives. Most configuration keywords will take effect
959       immediately, except the following, which will only take effect after  a
960       restart of milter-greylist(8): nodetach, pidfile, socket, and user.
961
962       The  dumpfreq  option  can  be changed dynamically, but the change will
963       only take effect after the next dump.
964
965       multiracl
966              By default, once a RCPT-stage ACL whitelists a  recipient,  next
967              recipient gets automatically whitelisted. This historical behav‐
968              ior can be considered a bug, and this option disables it.
969

FORMAT STRINGS

971       Various statements in the configuration  file  accept  format  strings,
972       where the following % prefixed tokens are substituted. Here is the com‐
973       plete list of available substitutions (Note that some substitutions are
974       not relevant in any context).
975
976       %r     the  message  recipient  e-mail address. This is not substituted
977              for DATA stage ACL since there can be  multiple  recipients  for
978              the message.
979
980       %f     the message sender e-mail address
981
982       %i     the sender machine IP address
983
984       %j     the reversed sender machine IP address. For instance, 192.0.2.12
985              becomes 12.2.0.192.
986
987       %I     the sender machine IP address masked by a CIDR. Example: %I{/24}
988
989       %d     the sender machine DNS address
990
991       %h     the SMTP transaction HELO string
992
993       %mr    the mailbox part of %r (before the @ sign). This is not  substi‐
994              tuted  for DATA stage ACL since there can be multiple recipients
995              for the message.
996
997       %sr    the site part of %r (after the @ sign). This is not  substituted
998              for  DATA  stage  ACL since there can be multiple recipients for
999              the message.
1000
1001       %mf    the mailbox part of %f (before the @ sign)
1002
1003       %sf    the site part of %f (after the @ sign)
1004
1005       %md    the machine part of %d (before the first . sign)
1006
1007       %sd    the site part of %d (after the first . sign)
1008
1009       %Xc    the SMTP code returned
1010
1011       %Xe    the SMTP extended code returned
1012
1013       %Xm    the SMTP message returned
1014
1015       %Xh    the message displayed in the X-Greylist header
1016
1017       %D     Comma-separated list of DNSRBL for which the sender host matched
1018
1019       %M     a sendmail macro value. Examples: %Mj or %M{if_addr}
1020
1021       %g     a regex back reference. For instance, %g{\2} is  substituted  by
1022              the  string  matching  the  second  parenthesis group in all ACL
1023              regex clauses
1024
1025       %T     a brace-enclosed strftime(3) format string that will be  substi‐
1026              tuted by the system time. Example: %T{%Y%m%d:%H%M%S}
1027
1028       %v     milter-greylist's version
1029
1030       %G     Offset to GMT (e.g.: -0100)
1031
1032       %C     Sender  IP  country  code,  as  reported  by GeoIP. This is only
1033              available if milter-greylist was built with GeoIP support
1034
1035       %Fx    p0f OS fingerprint genre and detail. This is only  available  if
1036              milter-greylist was built with p0f support.
1037
1038       %V     Shortcut  to  "milter-greylist-%v (%Mj [%M{if_addr}]); %T{%a, %d
1039              %b %Y %T} %G (%T{%Z})"
1040
1041       %S     the action performed: accept, tempfail, or reject.
1042
1043       %A     the line number of the ACL that caused the action.
1044
1045       %a     the id string of the ACL that caused the action. If  no  id  was
1046              given, the line number is used instead.
1047
1048       %cA    the  line  number of the ACL being evaluated, whether it matches
1049              or not.
1050
1051       %ca    the id string of the ACL being avaluated, whether it matches  or
1052              not.  If no id was given, the line number is used instead.
1053
1054       %Et    total  elapsed  time  in seconds before a greylisted message has
1055              been accepted
1056
1057       %Eh    hours elapsed
1058
1059       %Em    minutes elapsed (modulo one hour)
1060
1061       %Es    seconds elapsed (modulo one minute)
1062
1063       %E     shortcut to %Eh:%Em:Es
1064
1065       %Rt    total remaining time in seconds before a greylisted message will
1066              be accepted
1067
1068       %Rh    hours remaining
1069
1070       %Rm    minutes remaining (modulo one hour)
1071
1072       %Rs    seconds remaining (modulo one minute)
1073
1074       %R     shortcut to %Rh:%Rm:Rs
1075
1076       %Hs    SpamAssassin score (if build with SpamAssassin support)
1077
1078       %pn    Name of last LDAP or CURL gathered property that matched an ACL.
1079
1080       %pv    Value  of  last  LDAP  or CURL gathered property that matched an
1081              ACL.
1082
1083       %pr    Recipient that caused storage of the last matching LDAP or  CURL
1084              gathered property.  %P a LDAP or CURL gathered propery. Example:
1085              %P{mail} Note that this copes very badly with multivalued  prop‐
1086              erties.
1087
1088       %Qd    DKIM  query  result  (pass, fail, etc.), if built with DKIM sup‐
1089              port.
1090
1091       %Qs    SPF query result (pass, (soft)fail, etc.),  if  built  with  SPF
1092              support.
1093
1094       %QA    Authentication  results  summary,  suitable  for Authentication-
1095              Results header. Will included formatted query results from  DKIM
1096              and SPF if checked.
1097
1098       %QS    SPF  result,  suitable  for  Received-SPF header. Available when
1099              compiled with libspf2.
1100
1101       %%     a single % character
1102

AUTHORS

1104       Emmanuel Dreyfus <manu@netbsd.org>
1105
1106       milter-greylist  received  many  contributions  from  (in  alphabetical
1107       order):  Adrian  Dabrowski, Aida Shinra, Adam Katz, Alexander Lobodzin‐
1108       ski, Alexandre Cherif, Alexey Popov, Andrew  McGill,  Attila  Bruncsak,
1109       Benoit   Branciard,  Bernhard  Schneider,  Bob  Smith,  Constantine  A.
1110       Murenin, Chris Bennett, Christian Pelissier, Cyril Guibourg,  Dan  Hol‐
1111       lis,  David  Binderman,  Denis  Solovyov, Elrond, Enrico Scholz, Eugene
1112       Crosser, Fabien Tassin, Fredrik Pettai, Gary Aitken, Georg  Horn,  Gert
1113       Doering, Greg Troxel, Guido Kerkewitz, Hajimu Umemoto, Hideki ONO, Ivan
1114       F. Martinez, Jacques Beigbeder, Jean Benoit,  Jean-Jacques  Puig,  Jeff
1115       Rife, Jim Klimov, Jobst Schmalenbach, Joe Pruett, Joel Bertrand, Johann
1116       E. Klasek, Johann Klasek, John Thiltges,  John  Wood,  Jorgen  Lundman,
1117       Kazuyuki  Yoshida, Klas Heggemann, Kouhei Sutou, Laurence Moindrot, Lev
1118       Walkin, Manuel Badzong, Markus Wennrich, Mart Pirita, Martin Paul, Matt
1119       Kettler,  Mattheu  Herrb,  Matthias  Scheler,  Matthieu  Herrb, Michael
1120       Fromme, Moritz Both, Nerijus Baliunas, Ole Hansen, Pavel Cahyna, Pascal
1121       Lalonde,  Per  Holm,  Petar  Bogdanovic, Petr Kristof, Piotr Wadas, R P
1122       Herrold, Ralf S. Engelschall, Ranko Zivojnovic, Remy Card, Rick  Adams,
1123       Rogier  Maas, Romain Kang, Rudy Eschauzier, Stephane Lentz, Steven His‐
1124       cocks, Thomas Scheunemann, Tim Mooney, Vincent Dufresne, Wolfgang  Sol‐
1125       frank, and Yaroslav Boychuk.
1126
1127       Thanks  to  Helmut  Messerer  and Thomas Pfau for their feedback on the
1128       first releases of this software.
1129

SEE ALSO

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