FreeBSD Manual Pages
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 reference. This man page explains how to setup and use greylite, not how to in- stall it, nor its internals, nor its distinguishable features. For setup instructions, see SETUP below. For a quick reference on con- trol variables, see CONTROLS below. For an outline of the algorithm with which greylist modified the delivery attempts, see ALGORITHM be- low. 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 man- agers 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 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: :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 data- base 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 imme- diately to the smtpd transparently. If set, greylisting media- tion 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 vari- able 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 intro- duces a small delay (by default 6 seconds) before actually re- sponding data to the client. If its value is a positive inte- ger, it represents 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' host- name contains "ppp", or "dynamic" it is likely to be spammer; if it at- tempts 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 proper- ties 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 deter- mine if the client has to be required multiple delivery attempts (in- stead of the usual double attempt): the more suspicious is a client, the more times it might be temporarily rejected. Also, clients result- ing 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 deliv- ery 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 expres- sion (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 posi- tive integer, that will be used as number of attempts in- stead 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_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 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 behav- iours, 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 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 be- fore greylite and can perform custom checks on the client and set envi- ronment 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 uc- spi2socket. dnsblenv is a pre-module. It queries a list of RBL/DNSBL lists (space- separated into the DNSBL environment variable) for the client's ad- dress. If it is found in any of them, it sets the BLACKLISTED environ- ment variable 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 ALSO tcpserver(1), qmail-smtpd(8) Nov 11, 2007 GREYLITE(8)
NAME | SYNOPSIS | DESCRIPTION | SETUP | CONTROLS | SUSPICION | MODULES | ALGORITHM | SEE ALSO
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.0>