Add a connection rate limiting doc

Signed-off-by: Tom Eastep <teastep@shorewall.net>

docs/ConnectionRate.xml

@@ -0,0 +1,99 @@
+<?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>

docs/Documentation_Index.xml

@@ -55,11 +55,20 @@
       <tgroup align="left" cols="3">
         <tbody>
           <row>
-            <entry><ulink url="6to4.htm">6to4 Tunnels</ulink></entry>
+            <entry></entry>
 
             <entry><ulink url="KVM.html">KVM (Kernel-mode Virtual
             Machine)</ulink></entry>
 
+            <entry></entry>
+          </row>
+
+          <row>
+            <entry><ulink url="6to4.htm">6to4 Tunnels</ulink></entry>
+
+            <entry><ulink url="ConnectionRate.html">Limiting Connection
+            Rates</ulink></entry>
+
             <entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
             Guide</ulink></entry>
           </row>