GLST
Section: 0.27 (1)
Updated: 16 April 2008
Index
Return to Main Contents
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/greylisting .
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 command
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 processed 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 specified multiple times inside the command line, and
inside the configuration 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 successfully 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 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
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 containing 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
configuration 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 variables are:
-
root
Specifies the directory where the
glst
databases and configuration 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
<davidel@xmailserver.org>
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
<davidel@xmailserver.org>
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- EXAMPLES
-
- FILES
-
- BUGS
-
- SOURCE
-
- LICENSE
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 18:33:38 GMT, April 15, 2008