.\" .\" glst by Davide Libenzi ( SMTP GreyListing module ) .\" Copyright (C) 2004 Davide Libenzi .\" .\" This program 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 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA .\" .\" Davide Libenzi .\" .\" .TH GLST 1 "16 April 2008" "Davide Libenzi" 0.27 .SH NAME .B GLST \- SMTP GreyListing module .SH SYNOPSIS .B glst .RB [ --mfile .IR MFIL ] .RB [ --raddr .IR RADDR ] .RB [ --sender .IR SNDR ] .RB [ --rcpt .IR RCPT ] .RB [ --generr .IR ERR ] .RB [ --rejerr .IR ERR ] .RB [ --timeo .IR NSEC ] .RB [ --xnet .IR NET ] .RB [ --mnet .IR MNET ] .RB [ --exptimeo .IR NSEC ] .RB [ --lametimeo .IR NSEC ] .RB [ --cfg .IR CFIL ] .RB [ --rejfile .IR RFIL ] .RB [ --cleanup ] .RB [ --help ] .SH DESCRIPTION .B Glst is an implementation of .B SMTP Grey Listing , that has been described in the following URL .BR http://projects.puremagic.com/greylisting " ." You are invited to read the documentation contained inside the above listed URL for a detailed description of the SMTP greylisting solution. The .B glst module uses the .BR gdbm (3) database interface to store its data. On Windows, binaries are provided for the .BR gdbm (3) library and for the final executables. .SH OPTIONS The following options are recognized by .BR glst : .TP .BI --mfile " MFIL" Specify the input mail file name as .IR MFIL . The .B glst module can be used by passing all the parameters it needs inside the command line or, optionally, a mail file name can be passed to it, that .B glst will try to parse to extract missing information. At the moment, only the XMail spool files are recognized. .TP .BI --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. .TP .BI --sender " SNDR" Specify the email address of the sender of the currently processed message. .TP .BI --rcpt " RCPT" Specify the recipient of the message. This command line option can be passed multiple times to let the caller specify multiple recipients. .TP .BI --generr " ERR" Specify the error code that should be returned by .B glst in case of internal processing errors. .TP .BI --rejerr " ERR" Specify the error code that should be returned by .B 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 .I rejmsg configuration option. Such message will be printed on .IR STDOUT , if no .BI --mfile " MFIL" option is specified, while it will be stored in .IR MFIL .rej in case the caller specified an input spool/mail file. .TP .BI --timeo " NSEC" Specify the time window (in seconds) that should be used to reject unknown triplets. A triplet, like the .B SMTP Grey Listing describes, is a set containing: .IP .B o The remote IP of the SMTP client .IP .B o The sender email address .IP .B o The recipient of the message .TP .B "" Triplets are stored as keys of the .B glst database. .TP .BI --xnet " NET" Specify a network that should be whitelisted by the .B glst module. The format for the .I NET parameter is .IR IP , MASK " ," for example .IR 127.0.0.1 , 255.255.255.255 " ." The .B --xnet parameter can be specified multiple times inside the command line, and inside the configuration file. .TP .BI --mnet " MNET" The .B 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 .B glst unable to recognize the previous key (triplet) in the database. The .B --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 .I MNET parameter is .IR IP , MASK , NMASK " ," with the .I IP and .I MASK fields that are used to match the incoming IP, and the .I 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 .I MNET field should be .IR "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 .I MNET field should be .IR "10.0.0.0" , "255.0.0.0" , "255.255.255.224" " ." .TP .BI --exptimeo " NSEC" Specify the expire timeout for triplets that have been successfully accepted by the .B glst module. Every time a triplet is accepted (the remote mailer retried after the blackout window set with .BR --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 .BR --exptimeo , the record (triplet plus record metadata) is purged from the .B glst database. .TP .BI --lametimeo " NSEC" Specify the expire timeout for triplets that never attempted (lame) to resend during/after the blackout window set with .BR --timeo . During the cleanup, if the record timestamp is found older than the current time minus the timeout specified with .BR --lametimeo , and the number of successfully accepted messages for the current triplet is zero, the record (triplet plus record metadata) is purged from the .B glst database. .TP .BI --cfg " CFIL" Specify a .B glst configuration file to be loaded for default options. The .B glst module loads by default a file named .I glst.conf in the same directory where the .B glst binary resides. The .B --cfg option let the caller to specify an alternate configuration file to be loaded. .TP .BI --rejfile " RFIL" Specify the output reject message file name as .IR RFIL . The reject message file name is the file where .B glst will store the reject message, in case the result of the processing will result in rejection. If the .I RFIL is not specified, the reject file name is composed by appending the '.rej' extension to the .I MFIL file path. If even .I MFIL is not specified, the reject message is printed on .BR STDOUT . .TP .BI --cleanup Ask the .B glst module to perform database cleanup operations. .TP .BI --help Print an help message about the .B glst usage. .PP .SH EXAMPLES The .B glst module can either be run with all the parameters it needs supplied on the command line, or it has the ability to parse mail files to extract the required information for it to function. Currently the .B glst module has the ability to parse XMail's spool files and extract the required information from there. A typical usage of .B glst is inside an XMail's SMTP .I pre-data filter, with the .I filters.pre-data.tab file containing a line like (with real TABs between fields): .nf "!aex" "/var/MailRoot/bin/glst" "--mfile" "@@FILE" .fi In the same directory where the .B glst binary resides, a file named .I glst.conf can be created to allow the user to specify configuration options for the .B glst module (see .B FILES section for more information). Alternatively, when used with MTAs other than XMail, command line options can be specified to supply .B glst with the necessary information it needs to operate. At minimum, the caller should invoke .B glst with the following options: .nf glst --raddr 10.107.17.1 --sender foo@boo.biz --rcpt whoops@darn.cc .fi The return code of the .B glst binary can be used to detect if the current sender should be blocked or not. The .RB [ --generr .IR ERR ] and the .RB [ --rejerr .IR ERR ] command line options, or the .IR generr = ERR and .IR rejerr = ERR configuration file (glst.conf) options can be used to set the error code that the .B 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 .B glst binary completes successfully, zero will be returned. The error message can be set using the .IR rejerr = ERRMSG configuration option, and such message will be printed on .I STDOUT if no .BI --mfile " MFIL" option is specified, while it will be stored in .IR MFIL .rej in case the caller specified an input spool/mail file. To enable the .B glst module to perform some cleanup of its database, it is better to invoke it with the .B --cleanup option periodically. I use a script like this in my .I /etc/cron.daily/glst.sh file: .nf #!/bin/sh /var/MailRoot/bin/glst --cleanup .fi This will perform the necessary cleanups and computations over the .B glst database. Users with very high load might want to issue such command with shorter periodicity than daily. .SH FILES .TP .B glst.conf The .B glst configuration file is a simple text file using the .IR VARIABLE = VALUE format. Currently supported configuration variables are: .IP .B root .in +6 Specifies the directory where the .B glst databases and configuration files are stored. .in -6 .IP .B rejmsg .in +6 Specifies the rejection message that .B glst should report to the caller. The rejection message is either printed on .IR STDOUT , or stored inside the .rej file associated with the file specified with the .B --mfile option. .in -6 .IP .B generr .in +6 See .B --generr command line option. .in -6 .IP .B rejerr .in +6 See .B --rejerr command line option. .in -6 .IP .B timeo .in +6 See .B --timeo command line option. .in -6 .IP .B exptimeo .in +6 See .B --exptimeo command line option. .in -6 .IP .B lametimeo .in +6 See .B --lametimeo command line option. .in -6 .IP .B xnet .in +6 See .B --xnet command line option. .IP .B mnet .in +6 See .B --mnet command line option. .in -6 .PP .SH BUGS There are no known bugs. Bug reports and comments to: Davide Libenzi .RB < davidel@xmailserver.org > .SH SOURCE The latest source code is available at: .BR http://www.xmailserver.org/glst-mod.html .SH 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: .BR http://www.gnu.org/licenses/gpl.html .SH AUTHORS The .B glst package has been developed by: Davide Libenzi .RB < davidel@xmailserver.org >