Provided by: milter-greylist_4.6.4-3build2_amd64 bug

NAME

       greylist.conf - milter-greylist configuration file

DESCRIPTION

       greylist.conf  configures  milter-greylist(8)  operation.  The format is simple: each line
       contains a keyword and optional arguments. Any line starting with a # is considered  as  a
       comment  and is ignored. Blank lines are ignored as well. Comments at the end of lines are
       accepted in some situations, but do  not  take  them  as  granted.   A  statement  can  be
       continued  on  the  next  line  by using a backslash. Anything after the backslash will be
       ignored.

WHITELIST

       The primary use of greylist.conf is to setup milter-greylist(8) whitelist. It also  offers
       a  handy  blacklist  feature.   Access-lists  (ACL)  are  used  to do that. ACL enable the
       administrator to specify complex conditions on sender IP, sender DNS  address,  sender  e-
       mail address, and recipient e-mail address. If support for DNSRBL was built-in, it is even
       possible to use DNSRBL in ACL.

       An access-list entry starts with the racl  keyword  followed  by  an  optional  id  quoted
       string,  then  the  greylist, whitelist, blacklist, or continue keyword, and by any set of
       the following clauses: addr, domain, from, rawfrom, rcpt, rcptcount, helo, sm_macro, time,
       auth,  tls,  spf (if build with SPF support), geoip (if build with GeoIP support), p0f (if
       build with p0f support), ldapcheck (if build with  --with-openldap),  urlcheck  (if  built
       with  --with-libcurl),  dnsrbl (if built with --enable-dnsrbl), and nsupdate (if supported
       by the DNS resolver).  A message will match an ACL entry when it complies with all of  its
       clauses.

       The  greylist, whitelist, and blacklist keywords will cause the message to be respectively
       greylisted, accepted or  rejected  if  all  ACL  clauses  match,  and  ACL  evaluation  is
       terminated  there. If an ACL with continue keyword does match, nothing is decided and next
       ACL are evaluated.

       Clauses can be negated, by prefixing them by the not keyword. Here is the  detail  of  all
       possible clauses.

       addr   This  clause is used to specify a netblock of source IP addresses. The syntax is an
              IP address followed by a slash and a CIDR netmask. Here is an example:

                racl whitelist addr 127.0.0.0/8
                racl whitelist addr 192.168.3.0/24
                racl whitelist addr ::1

              If the netmask is omitted, /32 is assumed for an IPv4 address and /128  is  assumed
              for an IPv6 address.

              You  should  at  least whitelist localhost (127.0.0.1/8), and if you have some user
              clients connecting to the machine, you should whitelist the addresses they  connect
              from if you don't want them to get error messages when sending e-mail.

       domain This  clause  selects  source machines based on their DNS name, performing a suffix
              search.  For instance, this will whitelist any machine in the example.net domain:

                racl whitelist domain example.net

              Suffix search matching  means, for example, that gle.com will match google.com.  If
              you  want  domain  names to match on subdomain boundaries (e.g.  gle.com will match
              mail.gle.com and gle.com but not google.com) then enable domainexact

       The name resolution is made by Sendmail, which  hands  it  to  milter-greylist(8).   As  a
       result,  it  is impossible to use DNS aliases here. On the other hand, this will work even
       if your DNS resolver is not thread-safe.

       from   This is used to select sender e-mail addresses You should  not  use  that  feature,
              because sender e-mail addresses can be trivially forged.

              Please  note  that the sender e-mail is cleared from spaces and anything leading an
              equal (=) sign so that mailing-lists return-address with unique  return  paths  can
              still match.  If you need unedited sender address, use a rawfrom clause.

              Here is an example:

                racl whitelist from postmaster@example.com

       rawfrom
              Same  as from but the sender e-mail address is not modified to stip anything.  rcpt
              This is used to select recipient addresses. Example:

                racl greylist rcpt John.Doe@example.net

       rcptcount
              Followed by an operator and a recipient count, this is used to select the amount of
              recipients. Example:

                racl blacklist rcptcount >= 25 msg "No more than 25 recipients, please"

       helo   Followed  by a quoted string or a regular expression, this can be used to filter on
              the HELO string.

       sm_macro
              This is used to select a Sendmail macro value. See the section on  that  topic  for
              more information.

       time   This  is  used  to  specify a time set. It should be followed by a quoted string of
              crontab(5)-like time  specification.  Here  is  an  example  that  whitelists  mail
              addressed to a single recipient during office hours (from 8:00 to 16:59 from monday
              to friday):

                racl whitelist time "* 8-16 * * 1-5" rcpt info@example.net

       geoip  This is used to specify a country, as reported by GeoIP. The country code  must  be
              upper  case, and is only available if milter-greylist was built with GeoIP support.
              Special country code ZZ is used when the country cannot be determined (this happens
              for  private addresses, for instance). The geoipdb statement can be used to specify
              the location of GeoIP database.  geoipv6db statement can be  used  to  specify  the
              location  of  GeoIPv6  database.   geoip2db  statement  can  be used to specify the
              location of GeoIP2 (maxminddb) database.

       p0f    This is  used  to  match  against  the  remote  system  OS  fingerprint  genre  and
              detail,obtained  from  p0f.  It is only available if milter-greylist was built with
              p0f support.  p0f clauses can be used with a  quoted  string  for  case-insensitive
              substring  match, or against regular expressions. The p0fsock statement can be used
              to specify the location of the p0f socket.

       auth   This is used to select a user that succeeded SMTP AUTH. In order to select any user
              that succeeds SMTP AUTH, you can use a regular expression matching, like below;

                racl whitelist auth /.*/

              Using   such   a  clause  automatically  disable  global  STARTTLS  and  SMTP  AUTH
              whitelisting, like if the noauth keyword would have been used.

       tls    This is used to select the  distinguished  name  (DN)  of  a  user  that  succeeded
              STARTTLS.  Using  such a clause automatically disable global STARTTLS and SMTP AUTH
              whitelisting, like if the noauth keyword would have been used.

       spf    This is used to test SPF status. Possible values are pass, softfail, fail, neutral,
              unknown,  error,  none,  and self.  The first seven values are plain SPF validation
              status. The self value is a special test that checks the server's local IP  address
              against  the  sender's  SPF  record. If that test validates, odds are good that the
              sender SPF record is wide open, and this is hint that SPF should not be trusted.

              In order to use spf self, Postfix users must  specify  the  local  address  in  the
              configuration file, using the localaddr option.

              Absence  of  any  value  after  the spf keyword is a synonym for spf pass.  This is
              present for backward compatibility.

              The spf clause is only available if SPF support was  compiled  in.  Using  it  will
              disable global SPF whitelisting, like if the nospf keyword would have been used.

       ldapcheck
              This  is  used  to query an LDAP directory.  See the section on that topic for more
              information.

       urlcheck
              This is used to query an external configuration source through  an  URL.   See  the
              section on that topic for more information.

       dnsrbl This  is  used  to  select  a  DNSRBL.  See  the  section  on  that  topic for more
              information.

       nsupdate
              This always-matching clause performs a DNS update, see the section  on  that  topic
              for more information.

       The  domain,  from,  and  rcpt  clauses  may be used with regular expressions. The regular
       expressions must be enclosed by slashes (/). No escaping is available to provide  a  slash
       inside  a regular expression, so just do not use it. Regular expressions follow the format
       described in re_format(7).  Here is an example:

         racl greylist rcpt /@example\.net$/

       When regular expressions are not used, from, and rcpt perform a case insensitive substring
       match with leading and trailing brackets, spaces and tabs stripped out.  domain performs a
       case insensitive  suffix  match.   This  means,  for  example,  that  gle.com  will  match
       google.com.  If you want domain names to match on subdomain boundaries (e.g.  gle.com will
       match mail.gle.com and gle.com but not google.com) then enable domainexact

       An ACL entry can also hold various optional parameter used  on  match:  delay,  autowhite,
       flushaddr, nolog, code, ecode, report, maxpeek, addheader, addfooter, and msg

       delay  Specify  the  greylisting  delay  used  before  the  message can be accepted.  This
              overrides the greylist global setting, and it only  makes sense on an racl greylist
              entry.

       autowhite
              Specify  the  autowhitelisting  duration  for  messages  matching  this  ACL.  This
              overrides the autowhite global setting, and it only makes sense on an racl greylist
              entry. Example:

                racl greylist rcpt JDoe@example.net delay 15m autowhite 3d
                racl greylist rcpt root@example.net delay 1h autowhite 3d

       flushaddr
              If  a  message  matches  the rule, any entry in the greylist or autowhite databases
              matching the sender IP is removed. Used with a DNSRBL blacklist ACL, it  is  useful
              for  freeing  the  database from entries set up by a machine which is known to be a
              spammer. Example:

                racl blacklist dnsrbl "known-spammer" flushaddr

       nolog  Do not generate syslog message if this rule matches. Example:

                racl whitelist default nolog

       code

       ecode

       msg    These 3 values can be used to choose the SMTP code, extended code and reply message
              for temporary failures and rejects. Example:

                racl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
                racl greylist default code "451" ecode "4.7.1"

              The  msg  strings  accepts  format  string substitution as documented in the FORMAT
              STRINGS section. For instance, %A gets substituted by the ACL line number.

              None of the last 3 values makes sense for a whitelist entry.

       report This value overrides the text displayed in the X-Greylist header, for messages that
              milter-greylist(8)  lets  pass  through,  either  because  they are whitelisted, or
              because they passed greylisting (see REPORTING).  This string can be substituted as
              documented in the FORMAT STRINGS section.

       maxpeek
              This  parameter  only  makes  sense  in  a  RCPT-stage ACL. It overrides the global
              maxpeek setting for DATA-stage handling of the message. It has no effect if  global
              maxpeek is set to 0.

       addheader
              This  quoted  string  is  a  RFC822  header that gets added to the message.  Format
              string substitution is supported. No check  is  done  for  header  length  standard
              compliance,  so  make  sure the substituted string is shorter than 2048 characters.
              Headers are appended to the bottom, unless an  optionnal  comma-separated  positive
              index  is  specified  after  the  quoted  string;  in  this case the header will be
              inserted at this index point from the top. Here is an example:
              racl continue addheader "X-Personnal-Header: Hello world!",1

       addfooter
              Append a footer to the message. Usual escape sequences such as \n can  be  used  to
              get  special  characters.  The  string  is  subject  to  format string expantion as
              described in the FORMAT STRINGS section. The footer will not be append  if  milter-
              greylist  was  not able to capture the whole message, therefore maxpeek must be set
              approriately.

       Entries in the access-list are evaluated sequentially, so order  is  very  important.  The
       first  matching  entry is used to decide if a message will be whitelisted or greylisted. A
       special default clause can be used in the last ACL entry as a wildcard.  Here  are  a  few
       complete ACL examples:

       Example 1:

       racl whitelist from friend@toto.com rcpt grandma@example.com
       racl whitelist from other.friend@example.net rcpt grandma@example.com
       racl greylist rcpt grandma@example.com
       racl whitelist default

       Example 2:

       racl whitelist addr 193.54.0.0/16 domain friendly.com
       racl greylist rcpt user1@atmine.com
       racl greylist rcpt user2@atmine.com
       racl greylist rcpt user3@atmine.com
       racl whitelist default

       Example 3:

       racl whitelist rcpt /@.*otherdomain\.org$/
       racl whitelist addr 192.168.42.0/24 rcpt user1@mydomain.org
       racl whitelist from friend@example.net rcpt /@.*mydomain\.org$/
       racl whitelist rcpt user2@mydomain.org
       racl greylist rcpt /@.*mydomain\.org$/
       racl whitelist default

DATA-STAGE ACL

       ACL  using the racl keyword are evaluated at the RCPT stage of the SMTP transaction. It is
       also possible to have ACL evaluated at the DATA stage of the SMTP transaction,  using  the
       dacl  keyword, provided the message went through RCPT-stage ACL, and possibly greylisting.
       Note that you cannot use the greylist action at DATA-stage  if  the  RCPT-stage  ACL  that
       matched had a greylist action itself. The following clauses can be used to work on message
       content:

       dkim   DKIM status (if build with DKIM support). Possible values are pass, fail,  unknown,
              error, and none,

       header String or regular expression searched in message headers

       body   String or regular expression searched in message body

       msgsize
              Operator  followed  by  a  message  size  (k  or  M suffix allowed for kilobytes or
              megabytes). Example:

                dacl blacklist msgsize >= 4M msg "No more than 4 MB please"

       spamd  SpamAssassin score (if build with SpamAssassin support). If used without comparison
              operator  spamd  is true if the score is above threshold. The spamdsock keyword can
              be used to specify the location of the spamd socket.

              Example 1:

                spamdsock unix "/var/spamassassin/spamd.sock"
                racl whitelist default
                dacl greylist spamd

              Example 2:

                spamdsock inet "127.0.0.1:783"
                racl whitelist default
                dacl blacklist spamd > 15 msg "Your message is considered spam."
                dacl greylist  spamd > 10 delay 2h
                dacl greylist  spamd > 5  delay 1h

       Note that if there are multiple recipient, a rcpt clause at DATA stage evaluates  to  true
       if  it  matches any of them.  If you want to match an exact set of recipients, you can use
       multiple rcpt clauses along with a rcptcount clause.

LISTS

       It is often useful to group several users or sender IP addresses in a single ACL. This can
       be  done  with lists. Lists must be first defined and given a name before they can be used
       in ACL entries. Here is an example:

                list "my users" rcpt { user1@example.com user2@example.com }
                list "local" addr { 192.0.2.0/24 10.0.0.0/8 }

                racl whitelist list "local"
                racl greylist list "my users"
                racl whitelist default

BACKWARD COMPATIBILITY

       Previous versions of milter-greylist(8) used addr, domain, from, and rcpt  lines,  without
       the  racl  keyword.   Access-list management is intended to replace them.  These lines are
       still accepted by milter-greylist(8), but they are deprecated.  milter-greylist(8) handles
       them  as  access-list  entries  with  a  single  clause. They are added at the head of the
       access-list so the use  of  these  keywords  and  access-lists  may  lead  to  unspecified
       behaviour. Do not mix them.

       test mode (using -T) is also deprecated. Access-list semantics do not depend on this flag.

       milter-greylist(8)  also  used to only have a RCPT-stage ACL, which was configured through
       acl statements. These have been replaced by racl statements (as opposed to dacl statements
       for DATA-stage ACL).  acl statements are still accepted for backward compatibility and are
       a synonym for racl statements.

MX SYNC

       Synchronization of the greylist among multiple MX is configured using  the  peer  keyword.
       List each other MX IP addresses using the peer keyword. Here is an example:

         peer 192.0.2.18
         peer 192.0.2.17
         peer 192.0.2.22 timeout 7
         peer 192.0.2.38 timeout 5m

       You can list the local machine in the peer statements, it will be ignored.

       The  timeout  clause  sets  a peer communication timeout to have proper retrial in case of
       slow MX peer. The default value is  3  seconds.  The  special  value  of  0  disables  the
       connection retrials.

       By  default, milter-greylist will listen on all interfaces using TCP port 5252 or the port
       number given by service named mxglsync if defined  in  /etc/services  or  other  directory
       service.  This  behaviour  can  be  changed  by using the syncaddr keyword. Here are a few
       examples:

         syncaddr *
         syncaddr * port 7689
         syncaddr 192.0.2.2 port 9785
         syncaddr 2001:db8::1:c3b5:123
         syncaddr 2001:db8::1:c3b5:123 port 1234

       Using '*' as the address means to bind to all local interfaces' addresses.  Note  that  if
       you are not using the default port, all MXs must use the same port number.

       For  outbound  connections  the system is selecting one of the possible addresses.  If you
       want to use a specific IP you can use:

         syncsrcaddr 123.456.78.9

TEXT DUMP

       milter-greylist(8) uses a text dump of its database to resume operation after a crash. The
       dump is performed at regular time interval, but as it is a heavy operation, you might want
       to configure a particular time interval, using the dumpfreq option.

       If the dumpfreq value is too small, it will kill performance. If it is too high, you  will
       loose a bigger part of the database on a crash.

       Set  dumpfreq to 0 to get a dump on each change (kills performance), Set it to -1 to never
       dump to a file (unsafe as you lose the whole greylist on each crash), or give a time value
       for  the  delay between dumps.  The time is given in seconds, except if a unit is given: m
       for minutes, h for hours, and d for days.

       You may further improve the performance of the dump operation at the  expense  of  humanly
       readable  timestamp  which  by default appears as a comment at the end of each line in the
       dumpfile.   You   may   disable    generation    of    this    comment    by    specifying
       dump_no_time_translation   option   in   the  configuration  file.  This  is  specifically
       recommended if your dumpfile grows to 100's of megabytes - it can reduce the  time  needed
       for the dump operation by the order of magnitude!

REPORTING

       By default, milter-greylist(8) will add a X-Greylist header to any message it handles. The
       header shows what happened to the message: delayed or not delayed, and why. The  following
       options can be used in greylist.conf to alter this behavior:

       report none
              Never add a X-Greylist header.

       report delays
              Only add a header if the message was delayed.

       report nodelays
              Add  a  header  if the message was not delayed. The header explains why the message
              was not delayed.

       report all
              Always add a header. This is the default.

SENDER CALLBACK SYSTEMS

       Sender callback systems are another anti-spam measure that attempts to send a DSN  to  the
       sender address before accepting a message. If that fails, then the sender address is wrong
       and the message is rejected.  Such systems usually stop their callback check at  the  RCPT
       stage of the SMTP transaction.

       Greylisting temporarily rejects at the RCPT stage, so sender callback and greylisting love
       to fight each other.  milter-greylist(8) proposes a workaround to that  problem  with  the
       delayedreject  option.  For  messages coming from <> (that is, for DSN), it will cause the
       temporary reject to happen at the DATA stage of the SMTP transaction instead of  the  RCPT
       stage. That way, milter-greylist(8) will cope much better with sender callback systems.

       This  has  a  minor  drawback  (and this is why it is not enabled by default): for a multi
       recipient DSN, whitelisted recipient will not be honoured: the message will be delayed for
       everyone.

SENDMAIL MACROS

       Any  sendmail  macro  can  be  used  as  a clause in the access list. You need to define a
       (macro, value) pair using the sm_macro keyword before using it.  Here is an  example  that
       uses  the  {client_resolve} macro to apply a larger greylisting delay to hosts that have a
       bogus reverse DNS:

                sm_macro "maybe_forged" "{client_resolve}" "FORGED"

                racl greylist sm_macro "maybe_forged" delay 1h
                racl greylist default delay 15m

       A regular expression can be used as the macro value.  It must be surrounded  with  slashes
       and not by quotes.  The special value unset can also be used to match an unset macro:

                sm_macro "not_foo" "{foo}" unset

       Note  that any Sendmail macro that is not exported using the Milter.macros.envrcpt setting
       of sendmail.cf will be seen as unset from milter-greylist.

DNSRBL

       DNS Reverse Black List can be used to toggle an ACL. They must be defined and named before
       they  can  be  used.  Here  is  an example which uses a bigger greylisting delay for hosts
       caught in the SORBS dynamic pool DNRSBL (this will include DSL and cable customers  pools,
       which are well known to be massively infected by spamwares):

                dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10/32

                racl greylist dnsrbl "SORBS DUN" delay 1h
                racl greylist default delay 15m

       The  definition  of  a DNSRBL starts by the dnsrbl keyword, followed by the quoted name of
       the DNSRBL, the DNS domain on which addresses should be  looked  up,  and  the  answer  we
       should consider as a positive hit.

       DNSRBL  support  is  only  available  if  enabled through the --enable-dnsrbl config flag.
       Please make  sure  milter-greylist(8)  is  linked  against  a  thread-safe  DNS  resolver,
       otherwise it shall crash.

DNS updates

       ACL  are  able  to  trigger  a  DNS  update,  which  can  be  used to feed a DNSRBL.  That
       functionnality is enabled at build time if the DNS resolver has DNS update support.

       Configuration is done with the nsupdate statement, which may be used  several  times,  and
       the  optionnal  tsig  statement,  if  you want ot use authenticated DNS update. Here is an
       example syntax:

                tsig "dns-update" "hmac-md5" "1B2M2Y8AsgTpgAmY7PhCfg=="
                nsupdate "bl.example.net" { rname  "%j.bl.example.net"  rvalue  "127.0.0.2"  tsig
              "dns-update" }

       The options for nsupdate are:

       rname  Created record name, which uses format strings.

       rvalue Created record value, which uses format strings.

       servers
              Quoted comma-separated list of DNS server the update should be sent to.  Default is
              to use the system confifugration, usualy from /etc/resolv.conf

       ttl    TTL of created DNS record. Default is 0 seconds.

       class  Created record class, as numeric value. Default is 1, for IN class.

       type   Created record type, as numeric value. Default is 1, for A type.

       tsig   The name of a  tsig  configuration,  which  must  have  been  supplied  before.  If
              unspecified, unauthenticated DNS updates are performed.

       Once configured, DNS updates can be used in any ACL:

                racl blacklist rcpt spamtrap@example.net nsupdate "bl.example.net"

PROPERTIES

       Properties are variables that can be set, evaluated and printed in ACL.  A property may be
       dropped once the current recipient is processed, or it can be retained until  the  message
       is processed. They can be created through the following always-matching ACL clauses:

       set $name="value"
              This sets a property that will be retained for all next recipients. Right hand side
              of the clause may be a quoted  string  (which  will  be  substituted  using  format
              strings, as described in the FORMAT STRINGS section), a number, or another property
              name (which will be substituted by the property value).

       rset $name="value"
              Same as set clause, except that the property will be droped once the  current  user
              will have been processed.

       urlcheck
              These clause will cause properties to be fetched from an external web service.  See
              the URL checks section below for details.

       ldapcheck
              These clause will cause properties to be fetched from a LDAP directory See the LDAP
              CHECKS section below for details.

       Properties can be used as left-hand side part of ACL clauses:

                racl blacklist $name "badvalue"
                racl blacklist $name /badregex/

       If used left-hand side and prefixed by a star, the property will be evaluated as a glob(7)
       pattern, In the example below, if sender DNS domain is  test.example.net  and  $domain  is
       *.example.net, we get a match.

                racl blacklist *$domain "%f"

       They are also available as right-hand side of many ACL clauses:

                racl continue set $badword="spam"
                racl blacklist body $badword

       Values of properties can be obtained in any quoted string that is subject to format string
       expantion:

                racl continue set $webmaster="webmaster@example.net"
                racl blacklist domain evil.net msg "blacklisted, ask $P{webmaster} why"

       When the property value is a number, it can be increased or decreased using this syntax:

                racl continue set $score+=5
                racl continue set $score-=5

       Here again, right hand side may be a quoted string, a number or another property. For  the
       quoted  string  and property cases, a conversion is first made to an integer, using 0 as a
       value on failure. Note that no arithmetic evaluation  occurs.  For  instance,  the  quoted
       string "1 + 1" will be evaluated as 0.

       The  log ACL clause can be helpful when one need to figure what happens to property values
       during the ACL flow. See the CUSTOM REPORT section for more details.

URL checks

       milter-greylist(8) is able to query external sources of information through  various  URL,
       if it was built with --with-libcurl. Here is an example:

                urlcheck "glusr" "http://www.example.net/mgl-config?rcpt=%r" 5

                racl greylist urlcheck "glusr" delay 15m
                racl whitelist default

       The trailing 5 at the end of the urlcheck definition is the maximum number of simultaneous
       connections we want to launch on this URL. For each message, the URL will be queried, with
       % format tags being substituted. For instance, %r is substituted by the recipient. See the
       FORMAT STRINGS section for the complete list of substitutions.

       milter-greylist(8) expects an answer containing a list of \n terminated lines,  with  key:
       value pairs. The most basic answer to get a match is:

                milterGreylistStatus: Ok

       TRUE can be used as an alias for Ok here.

       The answer can be more complex, with keys that will overload the ACL settings:

       milterGreylistDelay
              The greylisting delay to use (time unit suffix allowed).

       milterGreylistAutowhite
              The autowhite delay to use (time unit suffix allowed).

       milterGreylistFlushAddr
              The  value  is  ignored. If this key is present, then the IP address for the sender
              machine will be flushed from greylist and autowhite databases.

       milterGreylistCode
              The SMTP code to return (e.g.: 551).

       milterGreylistECode
              The SMTP extended code to return (e.g.: 5.7.1)

       milterGreylistMsg
              The string to return with SMTP codes.

       milterGreylistReport
              The string to display in the X-Greylist header.

       milterGreylistIgnore
              This line will be ignored, without warnings in the logs.

       milterGreylistAction
              This feature is nifty but use it with caution, as it makes the access  list  a  bit
              difficult   to  understand.  By  specifying  the  values  greylist,  whitelist,  or
              blacklist, it is possible to overload the ACL action itself.

       The ACL will match if any of the  above  key  is  returned:  milterGreylistStatus  is  not
       mandatory.

       Optional keywords can be appended to a urlcheck definition:

       postmsg
              On  DATA-stage  ACL,  This causes the message to be sent (up to maxpeek bytes) in a
              POST request. Here is an example:

                urlcheck "extfilter" "http://www.example.net/f.cgi" 5 postmsg

                dacl blacklist urlcheck "extfilter"
                dacl whitelist default

       getprop
              Gather the properties returned by the URL and reuse them in the ACL.  The  gathered
              properties  can be accessed in the current and following ACL by prefixing them by a
              dollar ($).

       clear  This causes gathered properties to be cleared on each new recipient.   This  avoids
              properties for several recipients to mix.

       fork   Tells  milter-greylist(8)  to fork a separate instance of itself for performing the
              queries. Use it if you encounter thread-safety problems.  fork  is  not  compatible
              with postmsg.

       domatch
              Cause  the  ldapcheck  clause to be evaluated in ACL. Default behavior is to ignore
              the  result  and  just  fecth  properties,  except  if  the   LDAP   directory   is
              unreachecable,  in which case a temporary failure occurs.  The fixldapcheck gloabal
              settings may also be used to globaly cause all ldapcheck and  urlcheck  clauses  to
              match.

       Here  is  an  example  that  will  use various DNSRBL depending on a per-recipient setting
       stored in the dnsrbl attribute of a LDAP directory.

                dnsrbl "RBL2" "rbl.example.net" "127.0.0.2"
                dnsrbl "RBL3" "rbl.example.net" "127.0.0.3"
                dnsrbl "RBL4" "rbl.example.net" "127.0.0.4"
                urlcheck                                                               "userconf"
              "ldap://localhost/dc=example,dc=net?milterGreylistStatus,dnsrbl?one?mail=%r"      5
              getprop clear

                racl blacklist urlcheck "userconf" $dnsrbl "RBL2" dnsrbl "RBL2"
                racl blacklist $dnsrbl "RBL3" dnsrbl "RBL3"
                racl blacklist $dnsrbl "RBL4" dnsrbl "RBL4"

       Note that when matching gathered properties, format strings and regex can be used.

LDAP CHECKS

       If milter-greylist was built with --with-openldap, then you can  also  use  ldapcheck  for
       pulling  information from an LDAP directory. This works exactly like urlcheck, except that
       properties are always collected: The getprop option is implicit.

       A list of LDAP URL to use can be specified with the ldapconf keyword. The network  timeout
       is optional.

                ldapconf "ldap://localhost ldaps://ldap.example.net" timeout 2s

       When ldaps:// is used, the system's ldap.conf file is used to locate x509 certificates.

       When  defining  LDAP  queries  with the ldapcheck statement, note that the scheme and host
       part of the URL are ignored.  Servers listed in ldapconf are used instead.

RATE LIMIT

       The ratelimit keyword specifies a ratelimit configuration to be used in access  lists.  It
       must  be  followed  by  the  rate limit configuration name, what is being accounted (i.e.:
       session for SMTP sessions, rcpt for recipients, data for bytes in body and  headers),  the
       actual limit, and the sampling period. Example:

                ratelimit "internalclients" rcpt 10 / 1m

                racl  blacklist  addr  192.0.2.0/24  ratelimit  "internalclients" \      msg "you
              speak too much"

       The ratelimit keyword can also have an option key statement, which determine  the  set  of
       key  for  message  accounting.  The  default  is %i for per IP address accounting (see the
       FORMAT STRINGS sections for the possible syntax of this field). Here is  an  example  that
       configures a rate limit of 100 messages per hour for each individual recipient-IP set.

                ratelimit "internalclients" rcpt 100 / 1h key "%r%i"

                racl  blacklist  addr  192.0.2.0/24  ratelimit  "internalclients" \      msg "you
              speak too much"

CUSTOM REPORTS

       The stat keyword can be used to specify a custom report for milter-greylist activity.   It
       should  be  supplied with an output (either file or external command) and a format string.
       Here is an example:

                stat ">>/var/log/milter-greylist.log" "%T{%T},%i,%f,%r,%A\n"

       If the output starts by >> or > then it is a file. Use >> to append to an  existing  file,
       and use > to overwrite it. If the output starts by a | then the output is a shell command,
       like in the example below:

                stat "|logger -p local7.info" "%T{%T},%i,%f,%r,%A\n"

       The format string gets substituted as URL checks format string: %r gets substituted by the
       recipient, %f by the sender, and so on. See the FORMAT STRINGS section for a complete list
       of available substitutions.

       There is also an always-matching log ACL clause that can be used to send a formated string
       to syslog with LOG_INFO level.  Here is an example:

              racl continue rcpt /@example\.com$/ log "I was here"

COMMAND-LINE FLAG EQUIVALENTS

       Most  milter-greylist(8)  command-line  options have equivalent options that can be set in
       the configuration file. Note that if a command line option is  supplied,  it  will  always
       override the configuration file.

       If  a  command-line  equivalent  keyword  is  used  more  than once, the last keyword will
       override the previous ones.

       verbose
              Enable debug output. This is equivalent to the -v flag.

       quiet  Do not tell clients how much time remains before their  e-mail  will  be  accepted.
              This is equivalent to the -q flag.

       nodetach
              Do not fork and go into the background. This is equivalent to the -D flag.

       noauth Greylist clients regardless if they succeeded SMTP AUTH or STARTTLS.  Equivalent to
              the -A flag.

       noaccessdb
              Normally milter-greylist(8) will whitelist  a  message  if  sendmail(8)  defines  a
              ${greylist}  macro  set  to WHITE. This enables complex whitelisting rules based on
              the Sendmail access DB. This option inhibits this behavior.

       nospf  Greylist clients regardless if they are SPF-compliant. Equivalent to the -S flag.

       testmode
              Enable test mode. Equivalent to the -T flag. This option is deprecated.

       greylist
              The argument sets how much time milter-greylist(8) will want  the  client  to  wait
              between  the  first attempt and the time the message is accepted. The time is given
              in seconds, except if a unit is given: m for minutes, h for hours, and d for  days.
              The  greylist  keyword is equivalent to the -w option. Here is an example that sets
              the delay to 45 minutes:

                greylist 45m

       autowhite
              This sets the auto-whitelisting duration, equivalent to the -a command-line option.
              As  for the greylist keyword, units can be supplied. Here is an example for a 3 day
              long auto-whitelisting:

                autowhite 3d

       pidfile
              This causes milter-greylist(8) to write its PID into the file  given  as  argument,
              like  the  -P command line argument does. The path to the file must be absolute and
              it must be enclosed in quotes. Here is an example:

                pidfile "/var/run/greylist.pid"

       dumpfile
              This chooses the location of the greylist dump  file,  like  the  -d  command  line
              option  does.  The path must be absolute and enclosed in quotes.  It can optionally
              be followed by an octal permission mode.  Example:

                dumpfile "/var/milter-greylist/greylist.db" 640

       subnetmatch
              This is equivalent to the -L command line option. It takes a slash  followed  by  a
              CIDR  mask as argument, and it commands the subnet matching feature. Example, for a
              class C wide matching:

                subnetmatch /24

       subnetmatch6
              This is equivalent to the -M command line option. It takes a slash  followed  by  a
              prefixlen  as argument, and it commands the subnet matching feature. Example, for a
              subnet wide matching:

                subnetmatch6 /64

       socket Like the -p command line option, this keyword is used to specify the socket used to
              communicate  with sendmail(8).  It must be enclosed in quotes and can optionally be
              followed by an octal permission mode (valid values  are  666,  660  or  600,  other
              values cause an error):

                socket "/var/milter-greylist/milter-greylist.sock" 660

       user   This  keyword  should  be  followed  by  a quoted user login and optionally a colon
              followed by a groupname.   Like  the  -u  option,  this  is  used  to  run  milter-
              greylist(8) as a non root user.  Here is an example:

                user "smmsp"

MISCELLANEOUS

       These options have no command line equivalent:

       logfac Sets  the  syslog  facility  for  messages.   Can  be  set  to  any of the standard
              facilities: kern,  user,  mail,  daemon,  auth,  syslog,  lpr,  news,  uucp,  cron,
              authpriv, ftp, local0, local1, local2, local3, local4, local5, local6, local7.  Can
              also be set to none to disable syslog output completely.

       timeout
              is used to control how long greylist tuples are retained in the database.  Value is
              in  seconds,  except if a suffix is given (m for minutes, h for hours, d for days).
              Default is 5 days.

       extendedregex
              Use extended regular expressions instead of basic regular expressions.

       unbracket
              Attempt to resolve sender address when the MTA handed it as  bracketed  IP  address
              (e.g.: [192.0.2.18] ). Default is to leave it as is.

       maxpeek
              Limit (in bytes) how much of messages are examined for header and body searches.

       lazyaw Make  auto-whitelist  look  at just the IP instead of the (sender IP, sender e-mail
              address, recipient e-mail address) tuple.

       domainexact
              match on subdomain boundaries instead of the  default  suffix  matching.   E.g.  if
              domainexact  is  not  enabled  (the  default) then gle.com will match google.com in
              addition to gle.com. If domainexact is enabled then, domain  names  will  match  on
              subdomain  boundaries  (e.g.   gle.com  will match mail.gle.com and gle.com but not
              google.com)

       drac db
              Tell where the DRAC DB file is. This is only available if DRAC support was compiled
              in. Here is an example:

                drac db "/usr/local/etc/drac.db"

       nodrac Disable DRAC.

       logexpired
              This  option  causes  greylist  entries  that expire to be logged via syslog.  This
              allows you to easily collect the IP addresses and sender names  and  use  them  for
              blacklisting,  SPAM  scoring,  etc.   Normally, expiration's are only logged if the
              debug option is set, but that generates a lot of extra messages.

       localaddr
              This keyword can be used to manually define the local MTA's  IP  address  for  such
              uses  as  spf  self and p0f in absence of the milter-API {if_addr} macro support in
              your MTA (Postfix, Sun/Oracle CommSuite Messaging Server).  This is not  so  useful
              when  using  Sendmail,  since  it  serves  the  macro  and the local address can be
              detected automatically.

       The configuration file is reloaded automatically once  it  is  modified  when  new  e-mail
       arrives.  Most  configuration keywords will take effect immediately, except the following,
       which will only take effect after a  restart  of  milter-greylist(8):  nodetach,  pidfile,
       socket, and user.

       The dumpfreq option can be changed dynamically, but the change will only take effect after
       the next dump.

       multiracl
              By default, once a RCPT-stage ACL  whitelists  a  recipient,  next  recipient  gets
              automatically  whitelisted.  This  historical behavior can be considered a bug, and
              this option disables it.

FORMAT STRINGS

       Various statements in the configuration file accept format strings, where the following  %
       prefixed  tokens  are  substituted.  Here  is the complete list of available substitutions
       (Note that some substitutions are not relevant in any context).

       %r     the message recipient e-mail address. This is not substituted for  DATA  stage  ACL
              since there can be multiple recipients for the message.

       %f     the message sender e-mail address

       %i     the sender machine IP address

       %j     the   reversed   sender  machine  IP  address.  For  instance,  192.0.2.12  becomes
              12.2.0.192.

       %I     the sender machine IP address masked by a CIDR. Example: %I{/24}

       %d     the sender machine DNS address

       %h     the SMTP transaction HELO string

       %mr    the mailbox part of %r (before the @ sign). This is not substituted for DATA  stage
              ACL since there can be multiple recipients for the message.

       %sr    the  site part of %r (after the @ sign). This is not substituted for DATA stage ACL
              since there can be multiple recipients for the message.

       %mf    the mailbox part of %f (before the @ sign)

       %sf    the site part of %f (after the @ sign)

       %md    the machine part of %d (before the first . sign)

       %sd    the site part of %d (after the first . sign)

       %Xc    the SMTP code returned

       %Xe    the SMTP extended code returned

       %Xm    the SMTP message returned

       %Xh    the message displayed in the X-Greylist header

       %D     Comma-separated list of DNSRBL for which the sender host matched

       %M     a sendmail macro value. Examples: %Mj or %M{if_addr}

       %g     a regex back reference. For instance, %g{\2} is substituted by the string  matching
              the second parenthesis group in all ACL regex clauses

       %T     a  brace-enclosed  strftime(3) format string that will be substituted by the system
              time. Example: %T{%Y%m%d:%H%M%S}

       %v     milter-greylist's version

       %G     Offset to GMT (e.g.: -0100)

       %C     Sender IP country code, as reported by GeoIP. This is  only  available  if  milter-
              greylist was built with GeoIP support

       %Fx    p0f  OS fingerprint genre and detail. This is only available if milter-greylist was
              built with p0f support.

       %V     Shortcut to "milter-greylist-%v  (%Mj  [%M{if_addr}]);  %T{%a,  %d  %b  %Y  %T}  %G
              (%T{%Z})"

       %S     the action performed: accept, tempfail, or reject.

       %A     the line number of the ACL that caused the action.

       %a     the  id  string  of  the  ACL  that caused the action. If no id was given, the line
              number is used instead.

       %cA    the line number of the ACL being evaluated, whether it matches or not.

       %ca    the id string of the ACL being avaluated, whether it matches or not.  If no id  was
              given, the line number is used instead.

       %Et    total elapsed time in seconds before a greylisted message has been accepted

       %Eh    hours elapsed

       %Em    minutes elapsed (modulo one hour)

       %Es    seconds elapsed (modulo one minute)

       %E     shortcut to %Eh:%Em:Es

       %Rt    total remaining time in seconds before a greylisted message will be accepted

       %Rh    hours remaining

       %Rm    minutes remaining (modulo one hour)

       %Rs    seconds remaining (modulo one minute)

       %R     shortcut to %Rh:%Rm:Rs

       %Hs    SpamAssassin score (if build with SpamAssassin support)

       %pn    Name of last LDAP or CURL gathered property that matched an ACL.

       %pv    Value of last LDAP or CURL gathered property that matched an ACL.

       %pr    Recipient  that caused storage of the last matching LDAP or CURL gathered property.
              %P a LDAP or CURL gathered propery. Example: %P{mail} Note  that  this  copes  very
              badly with multivalued properties.

       %Qd    DKIM query result (pass, fail, etc.), if built with DKIM support.

       %Qs    SPF query result (pass, (soft)fail, etc.), if built with SPF support.

       %QA    Authentication  results  summary,  suitable for Authentication-Results header. Will
              included formatted query results from DKIM and SPF if checked.

       %QS    SPF result, suitable for Received-SPF header. Available when compiled with libspf2.

       %%     a single % character

AUTHORS

       Emmanuel Dreyfus <manu@netbsd.org>

       milter-greylist  received  many  contributions  from  (in  alphabetical   order):   Adrian
       Dabrowski,  Aida Shinra, Adam Katz, Alexander Lobodzinski, Alexandre Cherif, Alexey Popov,
       Andrew  McGill,  Attila  Bruncsak,  Benoit  Branciard,  Bernhard  Schneider,  Bob   Smith,
       Constantine  A.  Murenin,  Chris Bennett, Christian Pelissier, Cyril Guibourg, Dan Hollis,
       David Binderman, Denis Solovyov, Elrond, Enrico Scholz,  Eugene  Crosser,  Fabien  Tassin,
       Fredrik  Pettai,  Gary  Aitken,  Georg  Horn,  Gert Doering, Greg Troxel, Guido Kerkewitz,
       Hajimu Umemoto, Hideki ONO, Ivan F. Martinez, Jacques Beigbeder, Jean Benoit, Jean-Jacques
       Puig,  Jeff  Rife,  Jim  Klimov,  Jobst Schmalenbach, Joe Pruett, Joel Bertrand, Johann E.
       Klasek, Johann Klasek, John Thiltges, John Wood, Jorgen Lundman,  Kazuyuki  Yoshida,  Klas
       Heggemann,  Kouhei  Sutou, Laurence Moindrot, Lev Walkin, Manuel Badzong, Markus Wennrich,
       Mart Pirita, Martin Paul, Matt Kettler, Mattheu Herrb, Matthias Scheler,  Matthieu  Herrb,
       Michael  Fromme,  Moritz Both, Nerijus Baliunas, Ole Hansen, Pavel Cahyna, Pascal Lalonde,
       Per Holm, Petar Bogdanovic, Petr Kristof, Piotr Wadas, R P Herrold, Ralf  S.  Engelschall,
       Ranko  Zivojnovic,  Remy  Card,  Rick  Adams,  Rogier  Maas, Romain Kang, Rudy Eschauzier,
       Stephane Lentz,  Steven  Hiscocks,  Thomas  Scheunemann,  Tim  Mooney,  Vincent  Dufresne,
       Wolfgang Solfrank, and Yaroslav Boychuk.

       Thanks to Helmut Messerer and Thomas Pfau for their feedback on the first releases of this
       software.

SEE ALSO

       milter-greylist(8), sendmail(8), syslogd(8).

       Evan Harris's paper:
              http://projects.puremagic.com/greylisting/

       milter-greylist's web site:
              http://hcpnet.free.fr/milter-greylist/

                                           May 10, 2005                          greylist.conf(5)