Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  GREYLITE (8)


greylite - transparent greylisting module for mailservers


See Also


greylite [smtpd-child]


greylite 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; 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.


Both when running as a reverse SMTP proxy or a UCSPI wrapper, greylite is run under tcpserver (see

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

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:


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


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


Greylisting has a tremendous effectiveness and efficiency but can be easily 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 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

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’ environment, the rule is applied. If the value of the variable is a positive integer, that will be used as number 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 recipient, 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 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 behaviours, the rule is applied. Behaviours are specified as list of one or more keywords: "greetdelay" (a delay is inserted before passing data when the connection is open. Mass mailers may give up and disconnect, or send data blindly before expecting the server’s greeting. In the second case the rule matches.); "retryinterval" (the client may be retrying deliveries of the message with an excessive frequency 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:

# is not protected with greylisting, and GMX is
# trusted because of SPF’s "-all"
0 e$ 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
# clients outside this zone are suspicious (this is very case-specific)
# 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}


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-modules are run after greylite and can make greylite communicate with backend servers. Every module must conform to the UCSPI interface to be compatible 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 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 and; ucspi2socket connecting to the upstream server on port 43210:

/usr/local/bin/tcpserver -v -R -l ‘uname -n‘ BINDADDR BINDPORT \\
    env GREYLIST="" DNSBL="" \\
    /usr/local/bin/dnsblenv /usr/local/bin/greylite \\
    /usr/local/bin/ucspi2socket 43210


The original greylisting algorithm is described in and the modified algorithm used by greylite is outlined below and detailed in


tcpserver(1), qmail-smtpd(8)
Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.