greylist (5) - Linux Manuals
greylist: milter-greylist configuration file
NAME
greylist.conf - milter-greylist configuration fileDESCRIPTION
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, or blacklist 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), and dnsrbl (if built with --enable-dnsrbl). A message will match an ACL entry when it complies with all of its clauses.
Clauses can be negated, by prefixing them by the not keyword.
- 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 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:
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 [at] example.com - rcpt
- This is used to select recipient addresses. Example:
racl greylist rcpt John.Doe [at] 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 [at] 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. 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 speficy 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, unknown, error, none, and self. The first six 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.
- 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.
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:
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,
addheader,
and
msg
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:
Example 2:
Example 3:
Note that if there are multiple recipient, a
rcpt
clause at DATA stage evalutes 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.
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.
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:
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:
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!
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.
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:
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.
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.
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 querried, with % format
tags being subtituted. 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:
TRUE
can be used as an alias for
Ok
here.
The answer can be more complex, with keys that will overload the ACL
settings:
The ACL will match if any of the above key is returned:
milterGreylistStatus
is not mandatory.
If you use an URL check in a DATA stage ACL, you can post the message header
and body to the URL. This is done by appending the
postmsg
keyword to the
urlcheck
statement, like in the example above:
It is also possible to gather the properties returned by the URL and reuse
them in the ACL. This behavior is enabled by the
getprop
keyword at the end of
urlcheck
definition. If this option is enabled, the gathered properties can be
accessed in the current and following ACL by prefixing them by a dollar ($).
If the
clear
keyword is added, then properties will be cleaned up before handling a new
recipient. This avoids properties for several recipients to mix.
Finally, the
fork
keyword instructs
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.
Here is an example that will use various DNSRBL depending on a per-recipient
setting stored in the
dnsrbl
attribute of a LDAP directory.
Note that when matching gathered properties, format strings and regex can
be used.
A list of LDAP URL to use can be specified with the
ldapconf
keyword. The network timeout is optional.
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.
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:
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.
If a command-line equivalent keyword is used more than once, the last
keyword will override the previous ones.
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.
milter-greylist
received many contributions from (in alphabetical order):
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,
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,
Jeff Rife,
Jobst Schmalenbach,
Joe Pruett,
Joel Bertrand,
Johann E. Klasek,
Johann Klasek,
John Thiltges,
Klas Heggemann,
Laurence Moindrot,
Lev Walkin,
Manuel Badzong,
Martin Paul,
Matt Kettler,
Mattheu Herrb,
Matthias Scheler,
Matthieu Herrb,
Michael Fromme,
Moritz Both,
Nerijus Baliunas,
Pavel Cahyna,
Per Holm,
Petr Kristof,
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.
racl whitelist from friend [at] toto.com rcpt grandma [at] example.com
racl whitelist from other.friend [at] example.net rcpt grandma [at] example.com
racl greylist rcpt grandma [at] example.com
racl whitelist default
racl whitelist addr 193.54.0.0/16 domain friendly.com
racl greylist rcpt user1 [at] atmine.com
racl greylist rcpt user2 [at] atmine.com
racl greylist rcpt user3 [at] atmine.com
racl whitelist default
racl whitelist rcpt /.*@.*otherdomain\.org/
racl whitelist addr 192.168.42.0/24 rcpt user1 [at] mydomain.org
racl whitelist from friend [at] example.net rcpt /.*@.*mydomain\.org/
racl whitelist rcpt user2 [at] 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 canot 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:
spamdsock unix "/var/spamassassin/spamd.sock"
racl whitelist default
dacl greylist spamd
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
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:
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.
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:
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.
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:
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.
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:
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):
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:
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 only available option is
clear.
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:
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.
MISCELLANEOUS
These options have no command line equivalent:
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).
AUTHORS
Emmanuel Dreyfus <manu [at] netbsd.org>
SEE ALSO
milter-greylist(8),
sendmail(8),
syslogd(8).