GLST(1) 0.27 GLST(1) NAME GLST - SMTP GreyListing module SYNOPSIS glst [--mfile MFIL] [--raddr RADDR] [--sender SNDR] [--rcpt RCPT] [--generr ERR] [--rejerr ERR] [--timeo NSEC] [--xnet NET] [--mnet MNET] [--exptimeo NSEC] [--lametimeo NSEC] [--cfg CFIL] [--rejfile RFIL] [--cleanup] [--help] DESCRIPTION Glst is an implementation of SMTP Grey Listing , that has been described in the following URL http://projects.puremagic.com/greylist- ing . You are invited to read the documentation contained inside the above listed URL for a detailed description of the SMTP greylisting solution. The glst module uses the gdbm(3) database interface to store its data. On Windows, binaries are provided for the gdbm(3) library and for the final executables. OPTIONS The following options are recognized by glst: --mfile MFIL Specify the input mail file name as MFIL. The glst module can be used by passing all the parameters it needs inside the com- mand line or, optionally, a mail file name can be passed to it, that glst will try to parse to extract missing information. At the moment, only the XMail spool files are recognized. --raddr RADDR Specify the remote SMTP client IP address. This can be an IP address, or a string in the [IP]:PORT form. In the latter case, the IP address part is extracted and used as remote SMTP client IP address. --sender SNDR Specify the email address of the sender of the currently pro- cessed message. --rcpt RCPT Specify the recipient of the message. This command line option can be passed multiple times to let the caller specify multiple recipients. --generr ERR Specify the error code that should be returned by glst in case of internal processing errors. --rejerr ERR Specify the error code that should be returned by glst in case the current message should be rejected by the calling SMTP layer. The message that should be returned to the remote SMTP client can be specified with the rejmsg configuration option. Such message will be printed on STDOUT, if no --mfile MFIL option is specified, while it will be stored in MFIL.rej in case the caller specified an input spool/mail file. --timeo NSEC Specify the time window (in seconds) that should be used to reject unknown triplets. A triplet, like the SMTP Grey Listing describes, is a set containing: o The remote IP of the SMTP client o The sender email address o The recipient of the message Triplets are stored as keys of the glst database. --xnet NET Specify a network that should be whitelisted by the glst module. The format for the NET parameter is IP,MASK , for example 127.0.0.1,255.255.255.255 . The --xnet parameter can be speci- fied multiple times inside the command line, and inside the con- figuration file. --mnet MNET The glst module stores the exact remote IP that is trying to send the message, inside the key (triplet) that is used to index its database. There are certain big ISPs though, that might try to send the same message from different IPs, by having the glst unable to recognize the previous key (triplet) in the database. The --mnet option gives the ability to apply a transformation on the incoming IP, so that entire subnets can be used as source IP in the stored triplet. the format of the MNET parameter is IP,MASK,NMASK , with the IP and MASK fields that are used to match the incoming IP, and the NMASK field that is applied to the incoming IP to retrieve the address that should be stored inside the database key. For example, supposing a /24 masking should be applied to all incoming IPs, the MNET field should be 0.0.0.0,0.0.0.0,255.255.255.0 . If the entire 10.0.0.0/8 subnet should be masked using a /27 address size, the MNET field should be 10.0.0.0,255.0.0.0,255.255.255.224 . --exptimeo NSEC Specify the expire timeout for triplets that have been success- fully accepted by the glst module. Every time a triplet is accepted (the remote mailer retried after the blackout window set with --timeo) the count of successfully accepted messages is increased, and the record timestamp is updated with the current time. During cleanup, if the timestamp is found older that the current time minus the timeout specified with --exptimeo, the record (triplet plus record metadata) is purged from the glst database. --lametimeo NSEC Specify the expire timeout for triplets that never attempted (lame) to resend during/after the blackout window set with --timeo. During the cleanup, if the record timestamp is found older than the current time minus the timeout specified with --lametimeo, and the number of successfully accepted messages for the current triplet is zero, the record (triplet plus record metadata) is purged from the glst database. --cfg CFIL Specify a glst configuration file to be loaded for default options. The glst module loads by default a file named glst.conf in the same directory where the glst binary resides. The --cfg option let the caller to specify an alternate configuration file to be loaded. --rejfile RFIL Specify the output reject message file name as RFIL. The reject message file name is the file where glst will store the reject message, in case the result of the processing will result in rejection. If the RFIL is not specified, the reject file name is composed by appending the '.rej' extension to the MFIL file path. If even MFIL is not specified, the reject message is printed on STDOUT. --cleanup Ask the glst module to perform database cleanup operations. --help Print an help message about the glst usage. EXAMPLES The glst module can either be run with all the parameters it needs sup- plied on the command line, or it has the ability to parse mail files to extract the required information for it to function. Currently the glst module has the ability to parse XMail's spool files and extract the required information from there. A typical usage of glst is inside an XMail's SMTP pre-data filter, with the filters.pre-data.tab file con- taining a line like (with real TABs between fields): "!aex" "/var/MailRoot/bin/glst" "--mfile" "@@FILE" In the same directory where the glst binary resides, a file named glst.conf can be created to allow the user to specify configuration options for the glst module (see FILES section for more information). Alternatively, when used with MTAs other than XMail, command line options can be specified to supply glst with the necessary information it needs to operate. At minimum, the caller should invoke glst with the following options: glst --raddr 10.107.17.1 --sender foo@boo.biz --rcpt whoops@darn.cc The return code of the glst binary can be used to detect if the current sender should be blocked or not. The [--generr ERR] and the [--rejerr ERR] command line options, or the generr=ERR and rejerr=ERR configura- tion file (glst.conf) options can be used to set the error code that the glst binary should return in case of generic error, and in case of rejection (current message should be blocked). In case the message should noe be blocked, and the glst binary completes successfully, zero will be returned. The error message can be set using the rejerr=ERRMSG configuration option, and such message will be printed on STDOUT if no --mfile MFIL option is specified, while it will be stored in MFIL.rej in case the caller specified an input spool/mail file. To enable the glst module to perform some cleanup of its database, it is better to invoke it with the --cleanup option periodically. I use a script like this in my /etc/cron.daily/glst.sh file: #!/bin/sh /var/MailRoot/bin/glst --cleanup This will perform the necessary cleanups and computations over the glst database. Users with very high load might want to issue such command with shorter periodicity than daily. FILES glst.conf The glst configuration file is a simple text file using the VARIABLE=VALUE format. Currently supported configuration vari- ables are: root Specifies the directory where the glst databases and con- figuration files are stored. rejmsg Specifies the rejection message that glst should report to the caller. The rejection message is either printed on STDOUT, or stored inside the .rej file associated with the file specified with the --mfile option. generr See --generr command line option. rejerr See --rejerr command line option. timeo See --timeo command line option. exptimeo See --exptimeo command line option. lametimeo See --lametimeo command line option. xnet See --xnet command line option. mnet See --mnet command line option. BUGS There are no known bugs. Bug reports and comments to: Davide Libenzi SOURCE The latest source code is available at: http://www.xmailserver.org/glst-mod.html LICENSE This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2.0 of the License, or (at your option) any later version. A copy of the license is available at: http://www.gnu.org/licenses/gpl.html AUTHORS The glst package has been developed by: Davide Libenzi Davide Libenzi 16 April 2008 GLST(1)