GREYLITE(8) System Manager's Manual GREYLITE(8)NAMEgreylite — transparent greylisting module for mailservers
SYNOPSISgreylite [smtpd-child]
DESCRIPTIONgreylite is an implementation of a modified greylisting technology for
fighting SPAM on mailservers. It combines natively with qmail and works
as a proxy for any SMTP server.
The prevalent reference for greylite is the web page at
http://mij.oltrelinux.com/net/greylite/; this man page is a shorter ref‐
erence.
This man page explains how to setup and use greylite, not how to install
it, nor its internals, nor its distinguishable features.
For setup instructions, see SETUP below. For a quick reference on control
variables, see CONTROLS below. For an outline of the algorithm with which
greylist modified the delivery attempts, see ALGORITHM below.
SETUP
Both when running as a reverse SMTP proxy or a UCSPI wrapper, greylite is
run under tcpserver (see http://cr.yp.to/ucspi-tcp/tcpserver.html).
The database file must be created first in either case, with the file
greydb.sql from the greylite's package (installing from package managers
could already provide this database):
mkdir -p /var/db/greylite
sqlite3 -init greydb.sql /var/db/greylite/greylite.db
Thereafter greylite can immediately be run from a tcpserver instance,
either as proxy or as wrapper.
When run as a reverse SMTP proxy, greylite stays in the middle of the
connection between the client and the upstream server, supervises the
envelope session transparently and decides how to act depending on its
modified greylisting algorithm. In this case, the ucspi2socket module is
used to communicate with the upstream server:
/usr/local/bin/tcpserver -v -R -l `uname -n` BINDADDR BINDPORT \
env GREYLIST="" /usr/local/bin/greylite \
/usr/local/bin/ucspi2socket SRVADDR [SRVPORT]
replace BINDADDR and BINDPORT with the IP address and port that greylite
must listen; replace SRVADDR (and SRVPORT if you need it) with the IP
address and port of the upstream "true" SMTP server to defend.
When run as a UCSPI (notably, qmail) wrapper, greylite is just plugged
into the top of the tcpserver chain preceding qmail-smtpd. A typical
chain (as taken from http://lifewithqmail.org/lwq.html#supervise-tree)
modified to enable greylite looks like:
/usr/local/bin/tcpserver -v -R -l "$LOCAL" \
-x /etc/tcp.smtp.cdb -c "$MAXSMTPD" \
-u "$QMAILDUID" -g "$NOFILESGID" 0 smtp \
/usr/local/bin/greylite /var/qmail/bin/qmail-smtpd 2>&1
where the greylite executable is evidently inserted without further com‐
plications.
Unless the GREYLIST environment variable in detected by greylite, it
passes transparently to the upstream server. This variable - as well as
other control variables, possibly - can be passed with the tcpserver's
control access feature (-x file option). Based on a rule file, it can
both allow/deny connections and specify environment variables per-source-
address. A rule file allowing everyone in and passing the GREYLIST vari‐
able looks like:
:allow,GREYLIST=""
See http://cr.yp.to/ucspi-tcp/tcpserver.html and
http://cr.yp.to/ucspi-tcp/tcprules.html for more information.
If greylite runs as unprivileged user (-u and/or -g arguments to
tcpserver), make sure that the directory holding the .db file is writable
by such user. Using custom paths or filenames for this database is also
possible (see CONTROLS below).
CONTROLSgreylite is controlled exclusively by environment variables. No command
line options are required nor allowed.
greylite recognizes the following environment variables:
GREYLIST if not set, greylisting is disabled and control is passed
immediately to the smtpd transparently. If set, greylisting
mediation is enabled. Besides existence, the value assigned
to this variable is completely ignored.
DBFILE if set, its value indicates the full path to the database
file to use. If not set, the default filename
/var/db/greylite/greylite.db is used.
LOGTHRESHOLD if set to an integer between 0 (LOG_EMERG) and 7
(LOG_DEBUG), log messages with priority strictly lower than
this value are not reported. Otherwise, the default thresh‐
old is 3 (LOG_ERR).
LOGPID if set, every log message will be prepended by the PID of
the process writing it.
SUSPICION if set, its value indicates the full path to the suspicion
file. See SUSPICION below.
GEOIPDB_FILE when using suspicion with GeoIP rules, the value of this
variable is the full path and filename of the GeoIP data‐
base. If not set, greylite will look for
/usr/local/share/GeoIP/GeoIP.dat.
GREETDELAY when set, greylite opens the connection immediately but
introduces a small delay (by default 6 seconds) before
actually responding data to the client. If its value is a
positive integer, it represents a custom delay to wait, in
millisecs.
SUSPICION
Greylisting has a tremendous effectiveness and efficiency but can be eas‐
ily worked around, for example issuing the delivery twice (or thrice) in
case of temporary error.
However, it can be frequently inferred with some accuracy that a client
is a spammer by a bunch of factors. For example, if the address' hostname
contains "ppp", or "dynamic" it is likely to be spammer; if it attempts
twice immediately, if it is located in countries like Russia or China or
Malaysia etc, if it connects and pushes data without waiting the server
responses et cetera, these are all distinguishable properties of spam‐
mers.
"Suspicion" is a technique used by greylite to avoid the workarounds that
spammers use against greylisting. It is a list of rules to determine if
the client has to be required multiple delivery attempts (instead of the
usual double attempt): the more suspicious is a client, the more times it
might be temporarily rejected. Also, clients resulting suspicious are not
whitelisted even if they pass the greylisting challenge.
A complete reference for greylite's suspicion is available in
http://mij.oltrelinux.com/net/greylite/suspicion.html.
This suspicion policy is contained in a suspicion file. In this text
file, each line has format "number letter rule" (or "number letter !
rule"), where:
number is a positive integer value defining the number of
delivery attempts to require for the message if the
rule matches
letter is a lowercase letter specifying the type of the rule
following (see below)
! if present, inverts (negates) the specification of
the rule -- that is, matches when the rule does not
and vice-versa
rule is the rule specification
Lines whose first character is '#' are ignored. The first line whose rule
matches decides the number of attempts to require.
The following kinds of rules are currently supported:
r Reverse lookup. The rule is an extended regular
expression (see re_format(7)) to check the PTR domain
of the client address. If the regex matches the PTR
domain, the rule is applied. This kind of rule
requires tcpserver to be run with the -r command line
option so that the remote host name is available to
greylite.
v environment Variable. The rule is a space-separated
list of one or more environment variables. If any of
these variables is present in the process' environ‐
ment, the rule is applied. If the value of the vari‐
able is a positive integer, that will be used as num‐
ber of attempts instead of the number in the rule.
e Envelope analysis. The rule is a list of one or more
patterns to match against parts of the envelope
information. Patterns are expressed as regular
expressions (see re_format(7)) prefixed by "r:", "s:"
or "h:" for matching respectively the envelope recip‐
ient, the envelope sender or the hostname sent in the
HELO/EHLO command.
g GeoIP. The rule is a space-separated list of one or
more country codes, see
http://www.maxmind.com/app/iso3166. If the client
appears to come from a zone in this list, the rule is
applied. This kind requires greylite to be compiled
with "-DWITH_GEOIP", and that the GeoIP library and
database are present in the system (see GEOIPDB_FILE
in CONTROLS above).
b client Behaviour. If the client features certain be‐
haviours, the rule is applied. Behaviours are speci‐
fied as list of one or more keywords: "greetdelay" (a
delay is inserted before passing data when the con‐
nection is open. Mass mailers may give up and discon‐
nect, or send data blindly before expecting the
server's greeting. In the second case the rule
matches.); "retryinterval" (the client may be retry‐
ing deliveries of the message with an excessive fre‐
quency that is not proper of legitimate servers.);
"commanderrors" (the client issued a command that the
server did not accept during the command session. Use
with caution)
Lines with an unknown kind are ignored. Lines with an incorrect format
are discarded.
This is an example:
# unprotecteddomain.com is not protected with greylisting, and GMX is
# trusted because of SPF's "-all"
0 e r:@unprotecteddomain.com$ s:@gmx.(de|net)$
# who fails the greetdelay trap or retries blindly is rejected to the infinite
100 b greetdelay retryinterval
# dnsblenv sets the BLACKLISTED variable when the client is on a RBL
6 v BLACKLISTED
# clients outside this zone are suspicious (this is very case-specific)
3 g ! AT BE CH DE ES EU FI FR GB IT MC NO SM VA
# clients whose PTR name contains "dynamic" stuff are suspicious
3 r (^|[^a-z])(a?dsl|dyn(amic)?(ip)?|dial(in|up)?|ppp|customer|user|host|home)([^a-z]|.?$)
2 r (([0-9]{1,3}[-.]){3})[0-9]{1,3}
MODULES
Greylite can be interfaced with more modules. Pre-modules are run before
greylite and can perform custom checks on the client and set environment
variables to which greylite can be made sensible for suspicion. Post-mod‐
ules are run after greylite and can make greylite communicate with back‐
end servers. Every module must conform to the UCSPI interface to be com‐
patible with the rest of the "service chain".
Two modules are included in the distribution: dnsblenv and ucspi2socket.
dnsblenv is a pre-module. It queries a list of RBL/DNSBL lists (space-
separated into the DNSBL environment variable) for the client's address.
If it is found in any of them, it sets the BLACKLISTED environment vari‐
able and runs its argument.
ucspi2socket is a post-module. It is run conforming to the UCSPI inter‐
face for interfacing with an upstream TCP server.
This is an example combining both modules: dnsblenv polling lists
zen.spamhaus.org and dnsbl.sorbs.net; ucspi2socket connecting to the
upstream server 1.2.3.4 on port 43210:
/usr/local/bin/tcpserver -v -R -l `uname -n` BINDADDR BINDPORT \\
env GREYLIST="" DNSBL="zen.spamhaus.org dnsbl.sorbs.net" \\
/usr/local/bin/dnsblenv /usr/local/bin/greylite \\
/usr/local/bin/ucspi2socket 1.2.3.4 43210
ALGORITHM
The original greylisting algorithm is described in
http://projects.puremagic.com/greylisting/ and the modified algorithm
used by greylite is outlined below and detailed in
http://mij.oltrelinux.com/net/greylite/.
SEE ALSOtcpserver(1), qmail-smtpd(8)
Nov 11, 2007
