GLST(1)                              0.22                              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] [--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.

       --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.

       --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 <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>




Davide Libenzi                 23 December 2004                        GLST(1)
