Provided by: milter-greylist_3.0-3.1ubuntu2_i386 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  acl  keyword  followed  by  the
       greylist,  whitelist,  or  blacklist  keyword,  and by any set of the 6
       clauses: addr,  domain,  from,  rcpt,  sm_macro,  and  (if  built  with
       --enable-dnsrbl)  dnsrbl.   A  message  will match an ACL entry when it
       complies with all of its 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:

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

              If the netmask is ommitted, /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:

                acl whitelist domain example.net

              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:

                acl whitelist from postmaster@example.com

       rcpt   This is used to select recipient addresses. Example:

                acl greylist rcpt John.Doe@example.net

       sm_macro
              This  is  used to select a Sendmail macro value. 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.

       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:

         acl 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.

       An ACL entry can also hold various optional parameter  used  on  match:
       delay, autowhite, flushaddr, code, ecode, 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 acl 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 acl greylist entry. Example:

                acl greylist rcpt JDoe@example.net delay 15m autowhite 3d
                acl 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  spamer.
              Example:

                acl blacklist dnsrbl "known-spamers" flushaddr

       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:

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

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

       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:

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

       Example 2:

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

       Example 3:

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

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 }

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

BACKWARD COMPATIBILITY

       Previous versions of milter-greylist(8) used addr,  domain,  from,  and
       rcpt  lines,  without  the  acl  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.

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

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

       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
       adresses.  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 specifficaly  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 others.  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"

                acl greylist sm_macro "maybe_forged" delay 1h
                acl greylist default 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

                acl greylist dnsrbl "SORBS DUN" delay 1h
                acl 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.

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.
              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.  Example:

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

       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:

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

       user   This keyword should be followed by a quoted user login. 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:

       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.

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

       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,  expirations  are  only  logged if the debug option is
              set, but that generates a lot of extra messages.

       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.

AUTHORS

       Emmanuel Dreyfus <manu@netbsd.org>

       milter-greylist  received  many  contributions  from  (in  alphabetical
       order):  Aida  Shinra,  Gary Aitken, Joel Bertrand, Moritz Both, Attila
       Bruncsak, Pavel Cahyna, Remy Card, Alexandre  Cherif,  Eugene  Crosser,
       Elrond, Cyril Guibourg, Klas Heggemann, Matthieu Herrb, Dan Hollis, Per
       Holm,  Romain  Kang,  Guido  Kerkewitz,  Matt  Kettler,  Petr  Kristof,
       Stephane  Lentz,  Alexander Lobodzinski, Ivan F. Martinez, Martin Paul,
       Christian Pelissier, Fredrik Pettai, Alexey Popov, Jeff Rife,  Matthias
       Scheler,  Jobst  Schmalenbach,  Thomas  Scheunemann, Wolfgang Solfrank,
       Fabien Tassin, Hajimu Umemoto, Lev Walkin, and Ranko Zivojnovic

       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)