Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GREYLITE(8)		    System Manager's Manual		   GREYLITE(8)

     greylite -- transparent greylisting module	for mailservers

     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 ref-

     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, ei-
     ther 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 en-
     velope session transparently and decides how to act depending on its mod-
     ified 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 ad-
     dress 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 com-

     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:

     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:
	     if	not set, greylisting is	disabled and control is	passed immedi-
	     ately to the smtpd	transparently. If set, greylisting mediation
	     is	enabled. Besides existence, the	value assigned to this vari-
	     able 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.
	     if	set to an integer between 0 (LOG_EMERG)	and 7 (LOG_DEBUG), log
	     messages with priority strictly lower than	this value are not re-
	     ported. 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.
	     if	set, its value indicates the full path to the suspicion	file.
	     See SUSPICION below.
	     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.
	     when set, greylite	opens the connection immediately but intro-
	     duces a small delay (by default 6 seconds)	before actually	re-
	     sponding 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 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-

     "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 fol-
		   lowing (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 vari-
		   ables is present in the process' environment, the rule is
		   applied. If the value of the	variable is a positive inte-
		   ger,	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	pat-
		   terns to match against parts	of the envelope	information.
		   Patterns are	expressed as regular expressions (see re_for-
		   mat(7)) prefixed by "r:", "s:" or "h:" for matching respec-
		   tively 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 com-
		   piled 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 behav-
		   iours, the rule is applied. Behaviours are specified	as
		   list	of one or more keywords: "greetdelay" (a delay is in-
		   serted 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 sec-
		   ond 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.); "com-
		   manderrors" (the client issued a command that the server
		   did not accept during the command session. Use with cau-
     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-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 and; ucspi2socket	connecting to the up-
     stream 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)

				 Nov 11, 2007


Want to link to this manual page? Use this URL:

home | help