qmail-spamthrottle(5) - the qmail spam throttle mechanism


       The  idea  of  spam  throttling  came about after would-be
       spammers were easily circumventing  (classic)  tarpitting.
       A  reasonable  recipient  limit  in  tarpitting  must  not
       adversely affect acceptable mail usage,  so  spam  clients
       typically  create  multiple SMTP connections, all of which
       fall under this threshold.   Other  sources  have  similar
       concepts,  using  rate  limiting, stuttering, et cetera to
       describe them.

       It was originally intended for  use  at  ISPs  to  control
       their internal clients (users) SMTP usage, although it can
       applied equally in other environments.  An ISP may wish to
       enable  this  mechanism  for its customers to prevent them
       from using the mail servers as a convenient location  from
       which  to  send spam.  However, in some or all other cases
       (other originating IP addresses) this mechanism  might  be
       disabled  to allow for legitimate high-volume mail traffic
       such as mailing lists.

       Spam throttling acts in a similar  manner  to  tarpitting,
       except that it is highly parameterized, more flexible, and
       (hopefully)  more  effective.   A  wait  is  imposed  (via
       sleep(3))  following  the  DATA command depending on these
       SMTP parameters: remote IP address; previous SMTP  connec­
       tion timestamp; and previous wait time.

       With  the  addition  of  teergrubing, spammers should keep
       their connections open and deliver less mail.


       Two files, wait and time, store the previous wait time and
       SMTP  connection  timestamp, respectively.  Both files are
       found in  /var/qmail/spam/dir.   Where  dir  is  based  on
       parameters  set  in  /var/qmail/control/spamt.   If dir is
       empty as a result, then it will be  automatically  set  to
       a/b/0/0, where a and b are the two octets (in decimal) for
       the remote IP address, a.b.c.d.

       Similarly, if dir starts with a  slash  (/),  then  it  be
       automatically  set  to the n-bit masked IP address (format
       [/n]), based on the remote IP address.

       See qmail-spamt(5) for details.

       Note: In case it is not yet evident, when dir is empty (or
       starts  with  a slash), as indicated above, then every dot
       (.) is interpreted as a slash (/) in the  construction  of
       the  directory  where  the  spam  throttle state files are

       Message throughput is controlled via the value of st.  The
       delays imposed (by calling sleep(3)) depend on:  the value
       of st); number of recipients for the current SMTP  session
       (R);  the  number  of reasonable recipients per connection
       (rcpt); how much time has passed (T) since the  last  SMTP
       request  (as  determined by /var/qmail/spam/dir/time); and
       the   last   imposed   delay   (W)   (as   determined   by
       /var/qmail/spam/dir/wait).  The new delay is approximately

           (R - R / 2^(R/rcpt)) * ((W * st * R) / T)

       when rcpt is greater than 0, and

            (W * st * R) / T

       otherwise.  The unit of time is milliseconds.

       If stmax is defined (and is non-zero), then it is used  as
       a  maximum  (in  milliseconds)  for  the  delay calculated

       In short, st is roughly the minimum time between  messages
       and/or  connections.   If  you  already know that you only
       want a throughput of N messages per second, then  you  can
       use 1000/N as a good starting point for st.


       For  the  following  discussion,  we assuming the matching
       entry in /var/qmail/control/spamt is


       Despite efforts to impose a  waiting  period  on  would-be
       spammers,  it  is still possible for the client to circum­
       vent the call to sleep(3).  That is, they may not wait for
       the  response  from  the DATA command, continuing to write
       their message, assuming success, then closing the  socket,
       again  without waiting for a response from the server; the
       message will be delivered  at  no  (time)  cost  to  them.
       Adherence  to  standards  (such as ignoring the absence of
       PIPELINING) should not be assumed for  clients  acting  as
       agents  for  unsolicited  bulk  email.  As such, the flush
       variable can be set (non-zero) to indicate that all  input
       will  be flushed after calling sleep(3) and prior to send­
       ing a response to the DATA command.   RFC  2920  (STD  60)
       prohibits  flushing  of  the input buffer if PIPELINING is
       supported.  As such, EHLO  responses  will  not  advertise
       PIPELINING while flush is set.

            354-please wait
            354-please wait
            354 go ahead


       The   environment   variable,   TCPREMOTEIP,  is  strictly
       required  by  spam  throttle.   If  you  are   not   using
       tcpserver,  then  you  will  have to use tcp-env to ensure
       TCPREMOTEIP is set.


       The implicit translation of  an  empty  directory  to  one
       based  on the remote IP address will most certainly result
       in an unwieldy spam  directory  structure  and  should  be
       reserved  for small networks, such as the internal network
       side of an office or ISP (including  ISP  users).   It  is
       recommended  that  the  /n  format  be used in the default
       /var/qmail/control/spamt  entry  (empty  network   block).
       Then, for specific networks, a directory per IP address is
       still possible: for example, the entries


       define the default spam throttle directory  (assuming  the
       remote  IP  address is a.b.c.d) as a/b/0/0.  However, when
       the remote IP address is  in  the  network
       block,  the spam throttle directory will be a/b/c/d, since
       the dir parameter is /32.


       These examples assume that /var/qmail/control/spamthrottle
       contains a non-zero value.

       Here  is a sample /var/qmail/control/spamt file for a home

           # network:dir:st:stmax:flush:rcpt:tg:tg_resp:
           # default entry (make it all share the  public  direc­
           #   private   (trusted)   network   does  not  enforce
           #   network

       Here is a sample file for a high-volume  mail  server  (or
       servers)  for  some  arbitrary  ISP (with customer network and internal/ employee network

           # network:dir:st:stmax:flush:rcpt:tg:tg_resp:
           # by default, turn throttling off
           # customer network uses default behaviour
           # (IP-based throttle files)
           # employee network doesn't adhere to throttling
           # external trusted network which legitimately
           # provides high volume mail traffic
           # a collection of addresses/networks which we
           # might have gathered from past abuse experience
           # - we allow the mail, but we're aggressive
           #   about throttling it


       tcp-env(1), tcp-environ(5), qmail-spamt(5), qmail-smtpd(8)


       Dale Woolridge, James Law, and Moto Kawasaki.  Contact the
       authors via email: <spamthrottle at qmail dot ca>.


Man(1) output converted with man2html