Document the hashlimit feature

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

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9827 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb

Shorewall/changelog.txt

@@ -20,6 +20,8 @@ Changes in Shorewall 4.3.8
 
 10) Fix LOG_MARTIANS=Yes.
 
+11) Adapt I. Buijs's hashlimit patch.
+
 Changes in Shorewall 4.3.7
 
 1)  Fix forward treatment of interface options.

Shorewall/releasenotes.txt

@@ -30,6 +30,11 @@ released late in 2009.
     the compilation phase during start/restart if no configuration
     changes have occurred since the last start/restart.
 
+7)  The LIMIT:BURST column in /etc/shorewall/policy
+    (/etc/shorewall6/policy) and the RATE LIMIT column in
+    /etc/shorewall/rules (/etc/shorewall6/rules) may now be used to
+    limit on a per source IP or per destination IP basis.
+
 ----------------------------------------------------------------------------
                     M I G R A T I O N   I S S U E S
 ----------------------------------------------------------------------------
@@ -140,6 +145,35 @@ None.
     In other words, you can compile the current configuration then
     install it at a later time.
 
+7)  Thanks to I. Buijs, it is now possible to rate-limit connections by
+    source IP or destination IP. The LIMIT:BURST column in
+    /etc/shorewall/policy (/etc/shorewall6/policy) and the RATE LIMIT
+    column /etc/shorewall/rules (/etc/shorewall6/rules) have been
+    extended as follows:
+
+    	[{s|d}:[[<name>]:]]<rate>/{sec|min}[:<burst>]
+
+    When s: is specified, the rate is per source IP address.
+    When d: is specified, the rate is per destination IP address.
+    The <name> specifies the name of a hash table -- you get to choose
+    the name. If you don't specify a name, the name 'shorewall' is
+    assumed. Rules with the same name have their connection counts
+    aggregated and the individual rates are applied to the aggregate.
+
+    Example:
+
+	ACCEPT	net   fw    tcp    22  - - s:ssh:3/min
+
+    This will limit SSH connections from net->fw to 3 per minute.
+
+    	ACCEPT	net   fw    tcp    25   - - s:mail:3/min
+    	ACCEPT	net   fw    tcp    587  - - s:mail:3/min
+
+    Since the same hash table name is used in both rules, the above is
+    equivalent to this single rule:
+
+    	ACCEPT	net   fw    tcp    25,587  - - s:mail:3/min
+
 ----------------------------------------------------------------------------
                  N E W   F E A T U R E S   IN   4 . 3
 ----------------------------------------------------------------------------

manpages/shorewall-policy.xml

@@ -226,7 +226,9 @@
 
       <varlistentry>
         <term><emphasis role="bold">BURST:LIMIT</emphasis> -
-        <emphasis>rate</emphasis><emphasis role="bold">/</emphasis>{<emphasis
+        [{<emphasis>s</emphasis>|<emphasis
+        role="bold">d</emphasis>}:[[<replaceable>name</replaceable>]:]]]<emphasis>rate</emphasis><emphasis
+        role="bold">/</emphasis>{<emphasis
         role="bold">second</emphasis>|<emphasis
         role="bold">minute</emphasis>}:<emphasis>burst</emphasis></term>
 
@@ -235,6 +237,16 @@
           <emphasis>rate</emphasis> and the size of an acceptable
           <emphasis>burst</emphasis>. If not specified, TCP connections are
           not limited.</para>
+
+          <para>When <option>s:</option> or <option>d:</option> is specified,
+          the rate applies per source IP address or per destination IP address
+          respectively. The <replaceable>name</replaceable> may be chosen by
+          the user and specifies a hash table to be used to count matching
+          connections. If not give, the name <emphasis
+          role="bold">shorewall</emphasis> is assumed. Where more than one
+          POLICY specifies the same name, the connections counts for the
+          policies are aggregated and the individual rates apply to the
+          aggregated count.</para>
         </listitem>
       </varlistentry>
 

manpages/shorewall-rules.xml

@@ -922,7 +922,8 @@
 
       <varlistentry>
         <term><emphasis role="bold">RATE LIMIT</emphasis> (Optional) -
-        [<emphasis role="bold">-</emphasis>|<emphasis>rate</emphasis><emphasis
+        [<emphasis role="bold">-</emphasis>|[{<emphasis>s</emphasis>|<emphasis
+        role="bold">d</emphasis>}:[[<replaceable>name</replaceable>]:]]]<emphasis>rate</emphasis><emphasis
         role="bold">/</emphasis>{<emphasis
         role="bold">sec</emphasis>|<emphasis
         role="bold">min</emphasis>}[:<emphasis>burst</emphasis>]</term>
@@ -939,6 +940,18 @@
           the specification.</para>
 
           <para>Example: <emphasis role="bold">10/sec:20</emphasis></para>
+
+          <para>When <option>s:</option> or <option>d:</option> is specified,
+          the rate applies per source IP address or per destination IP address
+          respectively. The <replaceable>name</replaceable> may be chosen by
+          the user and specifies a hash table to be used to count matching
+          connections. If not give, the name <emphasis
+          role="bold">shorewall</emphasis> is assumed. Where more than one
+          rule specifies the same name, the connections counts for the
+          policies are aggregated and the individual rates apply to the
+          aggregated count.</para>
+
+          <para>Example: <emphasis role="bold">s:ssh:3/min:5</emphasis></para>
         </listitem>
       </varlistentry>
 

manpages6/shorewall6-policy.xml

@@ -226,7 +226,9 @@
 
       <varlistentry>
         <term><emphasis role="bold">BURST:LIMIT</emphasis> -
-        <emphasis>rate</emphasis><emphasis role="bold">/</emphasis>{<emphasis
+        [{<emphasis>s</emphasis>|<emphasis
+        role="bold">d</emphasis>}:[[<replaceable>name</replaceable>]:]]]<emphasis>rate</emphasis><emphasis
+        role="bold">/</emphasis>{<emphasis
         role="bold">second</emphasis>|<emphasis
         role="bold">minute</emphasis>}:<emphasis>burst</emphasis></term>
 
@@ -235,6 +237,16 @@
           <emphasis>rate</emphasis> and the size of an acceptable
           <emphasis>burst</emphasis>. If not specified, TCP connections are
           not limited.</para>
+
+          <para>When <option>s:</option> or <option>d:</option> is specified,
+          the rate applies per source IP address or per destination IP address
+          respectively. The <replaceable>name</replaceable> may be chosen by
+          the user and specifies a hash table to be used to count matching
+          connections. If not give, the name <emphasis
+          role="bold">shorewall</emphasis> is assumed. Where more than one
+          POLICY specifies the same name, the connections counts for the
+          policies are aggregated and the individual rates apply to the
+          aggregated count.</para>
         </listitem>
       </varlistentry>
 

manpages6/shorewall6-rules.xml

@@ -665,7 +665,8 @@
 
       <varlistentry>
         <term><emphasis role="bold">RATE LIMIT</emphasis> (Optional) -
-        [<emphasis role="bold">-</emphasis>|<emphasis>rate</emphasis><emphasis
+        [<emphasis role="bold">-</emphasis>|[{<emphasis>s</emphasis>|<emphasis
+        role="bold">d</emphasis>}:[[<replaceable>name</replaceable>]:]]]<emphasis>rate</emphasis><emphasis
         role="bold">/</emphasis>{<emphasis
         role="bold">sec</emphasis>|<emphasis
         role="bold">min</emphasis>}[:<emphasis>burst</emphasis>]</term>
@@ -682,6 +683,16 @@
           the specification.</para>
 
           <para>Example: <emphasis role="bold">10/sec:20</emphasis></para>
+
+          <para>When <option>s:</option> or <option>d:</option> is specified,
+          the rate applies per source IP address or per destination IP address
+          respectively. The <replaceable>name</replaceable> may be chosen by
+          the user and specifies a hash table to be used to count matching
+          connections. If not give, the name <emphasis
+          role="bold">shorewall</emphasis> is assumed. Where more than one
+          POLICY specifies the same name, the connections counts for the
+          policies are aggregated and the individual rates apply to the
+          aggregated count.</para>
         </listitem>
       </varlistentry>