NAME

SYNOPSIS

DESCRIPTION

The prevalent reference for greylite is the web page at http://mij.oltrelinux.com/net/greylite/; this man page is a shorter reference.

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

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]

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

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 variable looks like:

:allow,GREYLIST=""

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

CONTROLS

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 threshold 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 database. 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

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

"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:

The following kinds of rules are currently supported:

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

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 variable and runs its argument.

ucspi2socket is a post-module. It is run conforming to the UCSPI interface 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

SEE ALSO