Some documentation updates

Shorewall/Contrib/swping

@@ -39,26 +39,33 @@ if [ $FAMILY -eq 4 ]; then
 	. /usr/share/shorewall-lite/lib.base
 	[ -f /etc/shorewall-lite/params ] && . /etc/shorewall-lite/params
 	[ -n "${COMMAND:="/sbin/shorewall-lite restart; /sbin/ip -4 route ls"}" ]
-	STATEDIR=/etc/shorewall-lite
+	CONFDIR=/etc/shorewall-lite
+	VARDIR=/var/lib/shorewall-lite
     elif [ -f /usr/share/shorewall/lib.base ]; then
 	. /usr/share/shorewall/lib.base
 	[ -f /etc/shorewall/params ] && . /etc/shorewall/params
 	[ -n "${COMMAND:="/sbin/shorewall restart -f; /sbin/ip -4 route ls"}" ]
-	STATEDIR=/etc/shorewall
+	CONFDIR=/etc/shorewall
+	VARDIR=/var/lib/shorewall
     fi
 else
     if [ -f /usr/share/shorewall6-lite/lib.base ]; then
 	. /usr/share/shorewall6-lite/lib.base
 	[ -f /etc/shorewall6-lite/params ] && . /etc/shorewall6-lite/params
 	[ -n "${COMMAND:="/sbin/shorewall6-lite restart; /sbin/ip -4 route ls"}" ]
-	STATEDIR=/etc/shorewall6-lite
+	CONFDIR=/etc/shorewall6-lite
+	VARDIR=/var/lib/shorewall6-lite
     elif [ -f /usr/share/shorewall6/lib.base ]; then
 	. /usr/share/shorewal6l/lib.base
 	[ -f /etc/shorewall6/params ] && . /etc/shorewall6/params
 	[ -n "${COMMAND:="/sbin/shorewall6 restart -f; /sbin/ip -4 route ls"}" ]
-	STATEDIR=/etc/shorewall6
+	CONFDIR=/etc/shorewall6
+	VARDIR=/var/lib/shorewall6
     fi
 fi
+
+[ -f ${CONFDIR}/vardir ] && . ${CONFDIR}/vardir
+
 #
 # Interfaces to monitor -- you may use shell variables from your params file
 #
@@ -124,8 +131,8 @@ get_target() {
 #
 # Script starts here
 #
-rm -f $STATEDIR/${IF1}.status
+rm -f $VARDIR/${IF1}.status
-rm -f $STATEDIR/${IF2}.status
+rm -f $VARDIR/${IF2}.status
 
 while : ; do
     target=$TARGET1
@@ -216,8 +223,8 @@ while : ; do
 	#
 	# One of the interfaces changed state -- restart Shorewall
 	#
-	echo $if1_state > $STATEDIR/${IF1}.status
+	echo $if1_state > $VARDIR/${IF1}.status
-	echo $if2_state > $STATEDIR/${IF2}.status 
+	echo $if2_state > $VARDIR/${IF2}.status 
 	eval $COMMAND
 	state_changed=
     fi

Shorewall/configfiles/isusable

@@ -16,7 +16,7 @@
 ###############################################################################
 local status=0
 
-[ -f /etc/shorewall/${1}.status ] && status=$(cat /etc/shorewall/${1}.status)
+[ -f ${VARDIR}/${1}.status ] && status=$(cat ${VARDIR}/${1}.status)
 
 return $status
 

docs/MultiISP.xml

@@ -1089,7 +1089,7 @@ shorewall     2    2    -        eth0    192.168.1.254 track,balance=2,optional<
         <filename>swping</filename>. The <filename>swping</filename> file is
         available in the main directory contained in the Shorewall-common
         tarball and is included in the Shorewall-common documentation
-        directory on the Shorewall-common RPM. The script is inspired by
+        directory in the Shorewall-common RPM. The script is inspired by
         Angsuman Chakraborty's <ulink
         url="http://blog.taragana.com/index.php/archive/how-to-load-balancing-failover-with-dual-multi-wan-adsl-cable-connections-on-linux/">gwping</ulink>
         script.</para>
@@ -1167,9 +1167,9 @@ DOWN_COUNT=2</programlisting>
 
         <itemizedlist>
           <listitem>
-            <para>For each interface, a file is placed in /etc/shorewall to
+            <para>For each interface, a file is placed in ${VARDIR} (normally
-            record the status of the interface: either 0 (UP) or 1 (DOWN). The
+            /var/lib/shorewall) to record the status of the interface: either
-            name of the file is
+            0 (UP) or 1 (DOWN). The name of the file is
             <filename><replaceable>interface</replaceable>.status</filename>
             where <replaceable>interface</replaceable> is the interface (e.g.,
             <filename>eth0.status</filename>).</para>
@@ -1189,16 +1189,13 @@ DOWN_COUNT=2</programlisting>
         <para>The .status files are intended to be used with the following
         <filename>/etc/shorewall/isusable</filename> script.<programlisting>local status=0
 
-case $1 in
+[ -f ${VARDIR}/${1}.status ] &amp;&amp; status=$(cat ${VARDIR}/${1}.status)
-    <emphasis role="bold">eth0|eth1</emphasis>)
-        [ -f /etc/shorewall/${1}.status ] &amp;&amp; status=$(cat /etc/shorewall/${1}.status)
-        ;;
-esac
 
 return $status</programlisting></para>
 
-        <para>Be sure that you modify the interface names to match your
+        <para>The above script is installed in <filename
-        configuration.</para>
+        class="directory">/etc/shorewall</filename>, beginning with Shorewall
+        4.3.11.</para>
 
         <para>Also included is a sample init script
         (<filename>swping.init</filename>) to start the monitoring daemon.
@@ -1266,20 +1263,26 @@ fi</programlisting></para>
         more sophisticated monitoring than the simple swping script described
         in the preceding section.</para>
 
+        <para>Like many Open Source products, LSM is poorly documented. It's
+        main configuration file is normally kept in /etc/lsm/lsm.conf, but the
+        file's name is passed as an argument to the lsm program so you can
+        name it anything you want.</para>
+
+        <para>The sample <filename>lsm.conf</filename> included with the
+        product shows some of the possibilities for configuration. One feature
+        that is not mentioned in the sample is that an "include" directive is
+        supported. This allows additional files to be sourced in from the main
+        configuration file.</para>
+
         <para>I personally use LSM here at shorewall.net (configuration is
         described <link linkend="Complete">below</link>). Here are my relevant
         configuration files:</para>
 
         <para><filename>/etc/shorewall/isusable</filename>:</para>
 
-        <programlisting>local status
+        <programlisting>local status=0
-status=0
 
-case $1 in
+[ -f ${VARDIR}/${1}.status ] &amp;&amp; status=$(cat ${VARDIR}/${1}.status)
-    eth0|eth3)
-        [ -f /etc/shorewall/${1}.status ] &amp;&amp; status=$(cat /etc/shorewall/${1}.status)
-        ;;
-esac
 
 return $status</programlisting>
 
@@ -1289,7 +1292,7 @@ return $status</programlisting>
 # My 'restored' script calls this one if there is no lsm process running
 ###############################################################################
 if [ "$COMMAND" = start -o "$COMMAND" = restore ]; then
-   killproc lsm 2&gt; /dev/null
+   killall lsm 2&gt; /dev/null
    cat &lt;&lt;EOF &gt; /etc/lsm/shorewall.conf
 connection {
     name=Avvanta
@@ -1305,7 +1308,7 @@ connection {
     ttl=1
 }
 EOF
-   rm -f /etc/shorewall/*.status
+   rm -f ${VARDIR}/*.status
    /usr/sbin/lsm /etc/lsm/lsm.conf &gt;&gt; /var/log/lsm
 fi</programlisting>
 
@@ -1363,6 +1366,16 @@ CONS_WAIT=${11}
 CONS_MISS=${12}
 AVG_RTT=${13}
 
+if [ -f /usr/share/shorewall-lite/lib.base ]; then
+    VARDIR=/var/lib/shorewall-lite
+    STATEDIR=/etc/shorewall-lite
+else
+    VARDIR=/var/lib/shorewall
+    STATEDIR=/etc/shorewall
+fi
+
+[ -f ${STATEDIR}/vardir ] &amp;&amp; . ${STATEDIR}/vardir
+
 cat &lt;&lt;EOM | mail -s "${NAME} ${STATE}, DEV ${DEVICE}" ${WARN_EMAIL}
 
 Hi,
@@ -1392,7 +1405,7 @@ EOM
 
 [ ${STATE} = up ] &amp;&amp; state=0 || state=1
 
-echo $state &gt; /etc/shorewall/${DEVICE}.status
+echo $state &gt; ${VARDIR}/${DEVICE}.status
 
 /sbin/shorewall -f restart &gt;&gt; /var/log/lsm 2&gt;&amp;1
 
@@ -1407,7 +1420,7 @@ exit 0;
     <section id="Shared">
       <title>Two Providers Sharing an Interface</title>
 
-      <para>Shared interface support has the following characteristics"</para>
+      <para>Shared interface support has the following characteristics:</para>
 
       <orderedlist numeration="loweralpha">
         <listitem>

docs/traffic_shaping.xml

@@ -24,7 +24,7 @@
     <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
 
     <copyright>
-      <year>2001-2008</year>
+      <year>2001-2009</year>
 
       <holder>Thomas M. Eastep</holder>
     </copyright>
@@ -429,7 +429,15 @@ ppp0           6000kbit         500kbit</programlisting>
           option in <filename>/etc/shorewall/tcdevices</filename>, then the
           interface name or number must be followed by a colon and a
           <firstterm>class number</firstterm>. Examples: eth0:1, 4:9. Class
-          numbers must be unique for a given interface.</para>
+          numbers must be unique for a given interface. Normally, all classes
+          defined here are sub-classes of a root class that is implicitly
+          defined from the entry in <ulink
+          url="shorewall-tcdevices.html">shorewall-tcdevices</ulink>(5). You
+          can establish a class hierarchy by specifying a
+          <emphasis>parent</emphasis> class (e.g.,
+          <emphasis>interface</emphasis>:<emphasis>parent-class</emphasis>:<emphasis>class</emphasis>)
+          -- the number of a class that you have previously defined. The
+          sub-class may borrow unused bandwidth from its parent.</para>
         </listitem>
 
         <listitem>
@@ -559,6 +567,48 @@ ppp0           6000kbit         500kbit</programlisting>
               <ulink url="manpages/shorewall-tcrules.html">tcrules</ulink>
               (5).</para>
             </listitem>
+
+            <listitem>
+              <para>flow=<emphasis>keys</emphasis> - Shorewall attaches an SFQ
+              queuing discipline to each leaf HTB class. SFQ ensures that each
+              <firstterm>flow</firstterm> gets equal access to the interface.
+              The default definition of a flow corresponds roughly to a
+              Netfilter connection. So if one internal system is running
+              BitTorrent, for example, it can have lots of 'flows' and can
+              thus take up a larger share of the bandwidth than a system
+              having only a single active connection. The
+              <option>flow</option> classifier (module cls_flow) works around
+              this by letting you define what a 'flow' is. The clasifier must
+              be used carefully or it can block off all traffic on an
+              interface! The flow option can be specified for an HTB leaf
+              class (one that has no sub-classes). We recommend that you use
+              the following:</para>
+
+              <simplelist>
+                <member>Shaping internet-bound traffic: flow=nfct-src</member>
+
+                <member>Shaping traffic bound for your local net:
+                flow=dst</member>
+              </simplelist>
+
+              <para>These will cause a 'flow' to consists of the traffic
+              to/from each internal system.</para>
+
+              <para>When more than one key is give, they must be enclosed in
+              parenthesis and separated by commas.</para>
+
+              <para>To see a list of the possible flow keys, run this
+              command:</para>
+
+              <blockquote>
+                <para><command>tc filter add flow help</command></para>
+              </blockquote>
+
+              <para>Those that begin with "nfct-" are Netfilter connection
+              tracking fields. As shown above, we recommend flow=nfct-src;
+              that means that we want to use the source IP address
+              <emphasis>before NAT</emphasis> as the key.</para>
+            </listitem>
           </itemizedlist>
         </listitem>
       </itemizedlist>

manpages/shorewall-tcclasses.xml

@@ -344,6 +344,53 @@
                 (5).</para>
               </listitem>
             </varlistentry>
+
+            <varlistentry>
+              <term>flow=<emphasis>keys</emphasis></term>
+
+              <listitem>
+                <para>Shorewall attaches an SFQ queuing discipline to each
+                leaf HTB class. SFQ ensures that each
+                <firstterm>flow</firstterm> gets equal access to the
+                interface. The default definition of a flow corresponds
+                roughly to a Netfilter connection. So if one internal system
+                is running BitTorrent, for example, it can have lots of
+                'flows' and can thus take up a larger share of the bandwidth
+                than a system having only a single active connection. The
+                <option>flow</option> classifier (module cls_flow) works
+                around this by letting you define what a 'flow' is. The
+                clasifier must be used carefully or it can block off all
+                traffic on an interface! The flow option can be specified for
+                an HTB leaf class (one that has no sub-classes). We recommend
+                that you use the following:</para>
+
+                <simplelist>
+                  <member>Shaping internet-bound traffic:
+                  flow=nfct-src</member>
+
+                  <member>Shaping traffic bound for your local net:
+                  flow=dst</member>
+                </simplelist>
+
+                <para>These will cause a 'flow' to consists of the traffic
+                to/from each internal system.</para>
+
+                <para>When more than one key is give, they must be enclosed in
+                parenthesis and separated by commas.</para>
+
+                <para>To see a list of the possible flow keys, run this
+                command:</para>
+
+                <blockquote>
+                  <para><command>tc filter add flow help</command></para>
+                </blockquote>
+
+                <para>Those that begin with "nfct-" are Netfilter connection
+                tracking fields. As shown above, we recommend flow=nfct-src;
+                that means that we want to use the source IP address
+                <emphasis>before NAT</emphasis> as the key. </para>
+              </listitem>
+            </varlistentry>
           </variablelist>
         </listitem>
       </varlistentry>

manpages6/shorewall6-tcclasses.xml

@@ -134,7 +134,15 @@
           <para>Please note that you can only use interface names in here that
           have a bandwidth defined in the <ulink
           url="shorewall6-tcdevices.html">shorewall6-tcdevices</ulink>(5)
-          file</para>
+          file.</para>
+
+          <para>Normally, all classes defined here are sub-classes of a root
+          class that is implicitly defined from the entry in <ulink
+          url="shorewall6-tcdevices.html">shorewall6-tcdevices</ulink>(5). You
+          can establish a class hierarchy by specifying a
+          <emphasis>parent</emphasis> class -- the number of a class that you
+          have previously defined. The sub-class may borrow unused bandwidth
+          from its parent.</para>
         </listitem>
       </varlistentry>
 
@@ -287,6 +295,53 @@
                 </note>
               </listitem>
             </varlistentry>
+
+            <varlistentry>
+              <term>flow=<emphasis>keys</emphasis></term>
+
+              <listitem>
+                <para>Shorewall attaches an SFQ queuing discipline to each
+                leaf HTB class. SFQ ensures that each
+                <firstterm>flow</firstterm> gets equal access to the
+                interface. The default definition of a flow corresponds
+                roughly to a Netfilter connection. So if one internal system
+                is running BitTorrent, for example, it can have lots of
+                'flows' and can thus take up a larger share of the bandwidth
+                than a system having only a single active connection. The
+                <option>flow</option> classifier (module cls_flow) works
+                around this by letting you define what a 'flow' is. The
+                clasifier must be used carefully or it can block off all
+                traffic on an interface! The flow option can be specified for
+                an HTB leaf class (one that has no sub-classes). We recommend
+                that you use the following:</para>
+
+                <simplelist>
+                  <member>Shaping internet-bound traffic:
+                  flow=nfct-src</member>
+
+                  <member>Shaping traffic bound for your local net:
+                  flow=dst</member>
+                </simplelist>
+
+                <para>These will cause a 'flow' to consists of the traffic
+                to/from each internal system.</para>
+
+                <para>When more than one key is give, they must be enclosed in
+                parenthesis and separated by commas.</para>
+
+                <para>To see a list of the possible flow keys, run this
+                command:</para>
+
+                <blockquote>
+                  <para><command>tc filter add flow help</command></para>
+                </blockquote>
+
+                <para>Those that begin with "nfct-" are Netfilter connection
+                tracking fields. As shown above, we recommend flow=nfct-src;
+                that means that we want to use the source IP address
+                <emphasis>before NAT</emphasis> as the key.</para>
+              </listitem>
+            </varlistentry>
           </variablelist>
         </listitem>
       </varlistentry>