greylist.conf(5) - Linux man page

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.