Add short article about scalability and performance

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

docs/Documentation_Index.xml

@@ -174,8 +174,8 @@
             <entry><ulink url="Shorewall_and_Kazaa.html">Kazaa
             Filtering</ulink></entry>
 
-            <entry><ulink url="CompiledPrograms.html#Lite">Shorewall
+            <entry><ulink url="ScalabilityAndPerformance.html">Scalability and
-            Lite</ulink></entry>
+            Performance</ulink></entry>
           </row>
 
           <row>
@@ -185,8 +185,8 @@
             <entry><ulink url="kernel.htm">Kernel
             Configuration</ulink></entry>
 
-            <entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
+            <entry><ulink url="CompiledPrograms.html#Lite">Shorewall
-            Guide</ulink></entry>
+            Lite</ulink></entry>
           </row>
 
           <row>
@@ -196,7 +196,8 @@
             <entry><ulink url="PortKnocking.html#Limit">Limiting per-IPaddress
             Connection Rate</ulink></entry>
 
-            <entry><ulink url="samba.htm">SMB</ulink></entry>
+            <entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
+            Guide</ulink></entry>
           </row>
 
           <row>
@@ -205,8 +206,7 @@
 
             <entry><ulink url="shorewall_logging.html">Logging</ulink></entry>
 
-            <entry><ulink url="Shorewall_Squid_Usage.html">Squid with
+            <entry><ulink url="samba.htm">SMB</ulink></entry>
-            Shorewall</ulink></entry>
           </row>
 
           <row>
@@ -215,9 +215,8 @@
 
             <entry><ulink url="Macros.html">Macros</ulink></entry>
 
-            <entry><ulink
+            <entry><ulink url="Shorewall_Squid_Usage.html">Squid with
-            url="starting_and_stopping_shorewall.htm">Starting/stopping the
+            Shorewall</ulink></entry>
-            Firewall</ulink></entry>
           </row>
 
           <row>
@@ -227,8 +226,9 @@
             <entry><ulink url="MAC_Validation.html">MAC
             Verification</ulink></entry>
 
-            <entry><ulink url="NAT.htm">Static (one-to-one)
+            <entry><ulink
-            NAT</ulink></entry>
+            url="starting_and_stopping_shorewall.htm">Starting/stopping the
+            Firewall</ulink></entry>
           </row>
 
           <row>
@@ -238,7 +238,8 @@
             <entry><ulink url="MultiISP.html">Multiple Internet Connections
             from a Single Firewall</ulink></entry>
 
-            <entry><ulink url="support.htm">Support</ulink></entry>
+            <entry><ulink url="NAT.htm">Static (one-to-one)
+            NAT</ulink></entry>
           </row>
 
           <row>
@@ -248,8 +249,7 @@
             <entry><ulink url="Multiple_Zones.html">Multiple Zones Through One
             Interface</ulink></entry>
 
-            <entry><ulink url="Accounting.html">Traffic
+            <entry><ulink url="support.htm">Support</ulink></entry>
-            Accounting</ulink></entry>
           </row>
 
           <row>
@@ -259,8 +259,8 @@
             <entry><ulink url="XenMyWay-Routed.html">My Shorewall
             Configuration</ulink></entry>
 
-            <entry><ulink url="traffic_shaping.htm">Traffic
+            <entry><ulink url="Accounting.html">Traffic
-            Shaping/QOS</ulink></entry>
+            Accounting</ulink></entry>
           </row>
 
           <row>
@@ -270,8 +270,8 @@
             <entry><ulink url="NetfilterOverview.html">Netfilter
             Overview</ulink></entry>
 
-            <entry><ulink
+            <entry><ulink url="traffic_shaping.htm">Traffic
-            url="troubleshoot.htm">Troubleshooting</ulink></entry>
+            Shaping/QOS</ulink></entry>
           </row>
 
           <row>
@@ -280,7 +280,8 @@
 
             <entry><ulink url="netmap.html">Network Mapping</ulink></entry>
 
-            <entry><ulink url="UPnP.html">UPnP</ulink></entry>
+            <entry><ulink
+            url="troubleshoot.htm">Troubleshooting</ulink></entry>
           </row>
 
           <row>
@@ -289,8 +290,7 @@
             <entry><ulink url="NAT.htm">One-to-one NAT</ulink> (Static
             NAT)</entry>
 
-            <entry><ulink url="upgrade_issues.htm">Upgrade
+            <entry><ulink url="UPnP.html">UPnP</ulink></entry>
-            Issues</ulink></entry>
           </row>
 
           <row>
@@ -299,7 +299,8 @@
 
             <entry><ulink url="OPENVPN.html">OpenVPN</ulink></entry>
 
-            <entry><ulink url="VPNBasics.html">VPN</ulink></entry>
+            <entry><ulink url="upgrade_issues.htm">Upgrade
+            Issues</ulink></entry>
           </row>
 
           <row>
@@ -309,8 +310,7 @@
             <entry><ulink url="starting_and_stopping_shorewall.htm">Operating
             Shorewall</ulink></entry>
 
-            <entry><ulink url="whitelisting_under_shorewall.htm">White List
+            <entry><ulink url="VPNBasics.html">VPN</ulink></entry>
-            Creation</ulink></entry>
           </row>
 
           <row>
@@ -320,8 +320,8 @@
             <entry><ulink url="PacketMarking.html">Packet
             Marking</ulink></entry>
 
-            <entry><ulink url="XenMyWay.html">Xen - Shorewall in a Bridged Xen
+            <entry><ulink url="whitelisting_under_shorewall.htm">White List
-            DomU</ulink></entry>
+            Creation</ulink></entry>
           </row>
 
           <row>
@@ -331,8 +331,8 @@
             <entry><ulink url="PacketHandling.html">Packet Processing in a
             Shorewall-based Firewall</ulink></entry>
 
-            <entry><ulink url="Xen.html">Xen - Shorewall in Bridged Xen
+            <entry><ulink url="XenMyWay.html">Xen - Shorewall in a Bridged Xen
-            Dom0</ulink></entry>
+            DomU</ulink></entry>
           </row>
 
           <row>
@@ -340,8 +340,8 @@
 
             <entry><ulink url="ping.html">'Ping' Management</ulink></entry>
 
-            <entry><ulink url="XenMyWay-Routed.html">Xen - Shorewall in Routed
+            <entry><ulink url="Xen.html">Xen - Shorewall in Bridged Xen
-            Xen Dom0</ulink></entry>
+            Dom0</ulink></entry>
           </row>
 
           <row>
@@ -350,7 +350,8 @@
 
             <entry><ulink url="ports.htm">Port Information</ulink></entry>
 
-            <entry></entry>
+            <entry><ulink url="XenMyWay-Routed.html">Xen - Shorewall in Routed
+            Xen Dom0</ulink></entry>
           </row>
 
           <row>

docs/FAQ.xml

@@ -1613,6 +1613,10 @@ Creating input Chains...
           [re]start your firewall.</para>
         </listitem>
       </orderedlist>
+
+      <para>For additional information about Shorewall Scalability and
+      Performance, see <ulink url="ScalabilityAndPerformance.html">this
+      article</ulink>.</para>
     </section>
 
     <section id="faq43">

docs/ScalabilityAndPerformance.xml

@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article>
+  <!--$Id$-->
+
+  <articleinfo>
+    <title>Scalability and Performance</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Tom</firstname>
+
+        <surname>Eastep</surname>
+      </author>
+    </authorgroup>
+
+    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
+
+    <copyright>
+      <year>2006</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>The performance of the <emphasis role="bold">shorewall
+    start</emphasis> and <emphasis role="bold">shorewall restart</emphasis>
+    commands is a frequent topic of questions. This article attempts to
+    explain the scalability issues involved and to offer some tips for
+    reducing the time required to compile a Shorewall configuration and to
+    execute the compiled script.</para>
+  </section>
+
+  <section>
+    <title>Host Groups</title>
+
+    <para>In this article, we will use the term <firstterm>host
+    group</firstterm> to refer to a set of IP addresses accessed through a
+    particular interface. In a Shorewall configuration, there is one host
+    group for:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Each entry in <filename>/etc/shorewall/interfaces</filename>
+        that contains the name of a zone in the first column.</para>
+      </listitem>
+
+      <listitem>
+        <para>Each entry in <filename>/etc/shorewall/hosts</filename>.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>As you can see, each host group is associated with a single
+    <firstterm>zone</firstterm>.</para>
+  </section>
+
+  <section>
+    <title>Scaling by Host Groups</title>
+
+    <para>For each host group, it is possible to attempt connections to every
+    other host group; and if the host group has the <emphasis
+    role="bold">routeback</emphasis> option, then it is possible for
+    connections to be attempted from the host group to itself. So if there are
+    <emphasis role="bold">H</emphasis> host groups defined in a Shorewall
+    configuration, then the number of unique pairs of (<emphasis>source host
+    group</emphasis>, <emphasis>destination host group</emphasis>) is
+    <emphasis role="bold">H</emphasis>*<emphasis role="bold">H</emphasis> or
+    <emphasis role="bold">H</emphasis><superscript>2</superscript>. In other
+    words, the number of combinations is the square of the number of host
+    groups and increasing the number of groups from <emphasis
+    role="bold">H</emphasis> to <emphasis role="bold">H</emphasis>+1 adds
+    <emphasis role="bold">H</emphasis> + <emphasis role="bold">H</emphasis> +
+    1 = 2<emphasis role="bold">H</emphasis> + 1 additional
+    combinations.</para>
+  </section>
+
+  <section>
+    <title>Scaling by Zones</title>
+
+    <para>A similar scaling issue applies to Shorewall zones. If there are
+    <emphasis role="bold">Z</emphasis> zones, then connections may be
+    attempted from a given zone <emphasis
+    role="bold">Z</emphasis><subscript>n</subscript> to all of the other zones
+    (including to <emphasis role="bold">Z</emphasis><subscript>n</subscript>
+    itself). Hence, the number of combinations is the square of the number of
+    zones or <emphasis
+    role="bold">Z</emphasis><superscript>2</superscript>.</para>
+  </section>
+
+  <section>
+    <title>Scaling within the Shorewall Code</title>
+
+    <para>Shorewall is written entirely in Bourne Shell. While this allows
+    Shorewall to run on a wide range of distributions (included embedded
+    ones), the shell programming environment is not ideal for writing the
+    compiler portion of Shorewall. As a consequency, the code must repeatedly
+    perform sequential searches of lists. If a list has <emphasis
+    role="bold">N</emphasis> elements (<emphasis role="bold">N</emphasis> &gt;
+    1) and a sequential search is made for each of those elements, then the
+    number of comparisons is 1 + 2 + 3 + .... + <emphasis
+    role="bold">N</emphasis> = <emphasis role="bold">N</emphasis> * (<emphasis
+    role="bold">N</emphasis> - 1 ). So again, we see order <emphasis
+    role="bold">N</emphasis><superscript>2</superscript> scaling.</para>
+  </section>
+
+  <section>
+    <title>Improving Performance</title>
+
+    <para>Achieving good performance boils down to two things:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Use a light-weight shell and fast hardware. Especially in the
+        compiler, a light-weight shell such as <command>ash</command> or
+        <command>dash</command> can provide considerable improvement over
+        bash.</para>
+      </listitem>
+
+      <listitem>
+        <para>With all of the order <emphasis
+        role="bold">N</emphasis><superscript>2</superscript> scaling that is
+        implicit in the problem being solved, it is vital to keep <emphasis
+        role="bold">N</emphasis> small.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>So while it is tempting to create lots of zones through entries in
+    <filename>/etc/shorewall/hosts</filename>, such configurations
+    <emphasis>always</emphasis> perform badly. In these cases, it is much
+    better to have more rules than more zones because the performance scales
+    linearly with the number of rules whereas it scales geometrically with the
+    number of zones.</para>
+
+    <para>Another tip worth noting has to do with the use of shell variables.
+    </para>
+
+    <para>Suppose that the following appears in
+    <filename>/etc/shorewall/params</filename>: </para>
+
+    <programlisting>HOSTS=&lt;ip1&gt;,&lt;ip2&gt;,&lt;ip3&gt;,...&lt;ipN&gt;</programlisting>
+
+    <para>and suppose that $HOSTS appears in the SOURCE column of <emphasis
+    role="bold">M</emphasis> ACCEPT rules. That would generate a total of
+    <emphasis role="bold">N</emphasis> * <emphasis role="bold">M</emphasis>
+    iptables ACCEPT rules.</para>
+
+    <para>On the other hand, consider the following:</para>
+
+    <blockquote>
+      <para><filename>/etc/shorewall/actions</filename>:</para>
+
+      <programlisting>AcceptHosts</programlisting>
+
+      <para><filename>/etc/shorewall/action.AcceptHosts</filename>:</para>
+
+      <programlisting>#TARGET SOURCE          DEST            PROTO   DEST    SOURCE     ORIGINAL     RATE
+#                                               PORT    PORT(S)    DEST         LIMIT
+ACCEPT  $HOSTS </programlisting>
+    </blockquote>
+
+    <para>If the <emphasis role="bold">M</emphasis> ACCEPT rules are now
+    replaced with <emphasis role="bold">M</emphasis> AcceptHosts rules, the
+    total number of rules will be <emphasis role="bold">N</emphasis> +
+    <emphasis role="bold">M</emphasis>.</para>
+  </section>
+</article>