bionic (5) greylist.conf.5.gz

Provided by: milter-greylist_4.5.11-1.1build2_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, 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.  Example:

                racl whitelist from postmaster@example.com

       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.

       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.

       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/

       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.

       %%     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, Christian Pelissier, Cyril Guibourg,
       Dan Hollis, 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,
       Klas Heggemann, Kouhei Sutou, Laurence Moindrot, Lev Walkin, Manuel Badzong, Martin Paul,  Matt  Kettler,
       Mattheu  Herrb,  Matthias  Scheler,  Matthieu  Herrb,  Michael Fromme, Moritz Both, Nerijus Baliunas, Ole
       Hansen, Pavel Cahyna, Pascal Lalonde, Per  Holm,  Petr  Kristof,  Piotr  Wadas,  R  P  Herrold,  Ralf  S.
       Engelschall, Ranko Zivojnovic, Remy Card, Rick Adams, Rogier Maas, Romain Kang, Rudy Eschauzier, Stephane
       Lentz, Thomas Scheunemann, Tim Mooney, 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)