Provided by:
milter-greylist_3.0-3ubuntu1_i386 
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)