shorewall_code/docs/ConnectionRate.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Connection Rate Limiting</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2008</year>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <section>
    <title>Introduction</title>

    <para>Shorewall supports several mechanisms for limiting connection rates.
    These are described in the following sections.</para>

    <para>Rates are expressed in terms of a <firstterm>connections per unit
    time</firstterm> and a <filename>burst</filename>. An
    <firstterm>interval</firstterm> is calculated by dividing the unit of time
    by the number of connections allowed in that unit of time
    (<replaceable>connections</replaceable>/{<option>sec</option>|<option>min</option>|<option>hour</option>|<option>day</option>|week|month}[:<replaceable>burst</replaceable>]</para>

    <para>Example: 4/min:5</para>

    <simplelist>
      <member>Connections = 4</member>

      <member>Unit of time = 1 minute</member>

      <member>Interval = 1 minute/4 = 15 seconds.</member>

      <member>Burst = 5</member>
    </simplelist>

    <para>As each connection arrives,if the burst count is &gt; 0 the
    <firstterm>burst</firstterm> count is reduced by one and the connection is
    accepted. After each interval (15 seconds) that passes without a
    connection arriving, the <firstterm>burst</firstterm> count is incremented
    by 1 but is not allowed to exceed its initial setting (5).</para>

    <para>By default, the aggregate connection rate is limited. If the
    specification is preceeded by "<option>s:</option>" or
    "<option>d:</option>", then the rate is limited per SOURCE or per
    DESTINATION IP address respectively.</para>

    <section>
      <title>Policy Rate Limiting</title>

      <para>The LIMIT:BURST column in the
      <filename>/etc/shorewall/policy</filename> file applies to TCP
      connections that are subject to the policy. The limiting is applied
      BEFORE the connection request is passed through the rules generated by
      entries in <filename>/etc/shorewall/rules</filename>. Those connections
      in excess of the limit are logged and dropped.</para>
    </section>

    <section>
      <title>Rules Rate Limiting</title>

      <para>The RATE LIMIT column in the
      <filename>/etc/shorewall/rules</filename> file allows limiting of
      ACCEPT, DNAT and Action rules.</para>
    </section>

    <section>
      <title>Limit Action</title>

      <para>The <ulink url="Actions.html#Limit">Limit Action</ulink> is a
      legacy mechanism that limits connections per source IP. It does not
      support the notion of a burst size.</para>
    </section>
  </section>
</article>