NAME greylite -- transparent greylisting module for mailservers SYNOPSIS greylite [smtpd-child] DESCRIPTION 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 http://mij.oltrelinux.com/net/greylite/; this man page is a shorter refer- ence. 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, ei- ther as proxy or as wrapper. When run as a reverse SMTP proxy, greylite stays in the middle of the con- nection 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 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 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 compli- cations. Unless the GREYLIST environment variable in detected by greylite, it passes transparently to the upstream server. This variable - as well as other con- trol variables, possibly - can be passed with the tcpserver's control ac- cess feature (-x file option). Based on a rule file, it can both al- low/deny connections and specify environment variables per-source-address. A rule file allowing everyone in and passing the GREYLIST variable 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). CONTROLS 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 immedi- ately 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 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. 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 repre- sents a custom delay to wait, in millisecs. SUSPICION 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 con- tains "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: 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 follow- ing (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 ad- dress. If the regex matches the PTR domain, the rule is ap- plied. 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)) pre- fixed by "r:", "s:" or "h:" for matching respectively the en- velope 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 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 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 le- gitimate servers.); "commanderrors" (the client issued a com- mand that the server did not accept during the command ses- sion. 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 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-sepa- rated 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 up- stream 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 ALSO tcpserver(1), qmail-smtpd(8) Nov 11, 2007 GREYLITE(8)
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=greylite&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>