Document ROUTE_BALANCE

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

Shorewall-common/releasenotes.txt

@@ -121,7 +121,7 @@ Other Changes in Shoreall 4.2.0 Beta 3.
        GATEWAY column. 'detect' may not be specified.
 
     f) You should disable all default route management outside of 
-       Shorewall. If a default route is added to the mail table while
+       Shorewall. If a default route is added to the main table while
        Shorewall is started, then all policy routing will stop working
        (except for those routing rules in the priority range 1-998).
 

docs/MultiISP.xml

@@ -960,12 +960,12 @@ gateway:~ #</programlisting>Note that because we used a priority of 1000, the
         test for <filename class="devicefile">eth1</filename> is inserted
         before the fwmark tests.</para>
 
-        <para><emphasis role="bold">Example 2:</emphasis> You use OpenVPN
+        <para id="Openvpn"><emphasis role="bold">Example 2:</emphasis> You use
-        (routed setup w/tunX) in combination with multiple providers. In this
+        OpenVPN (routed setup w/tunX) in combination with multiple providers.
-        case you have to set up a rule to ensure that the OpenVPN traffic is
+        In this case you have to set up a rule to ensure that the OpenVPN
-        routed back through the tunX interface(s) rather than through any of
+        traffic is routed back through the tunX interface(s) rather than
-        the providers. 10.8.0.0/24 is the subnet choosen in your OpenVPN
+        through any of the providers. 10.8.0.0/24 is the subnet choosen in
-        configuration (server 10.8.0.0 255.255.255.0).</para>
+        your OpenVPN configuration (server 10.8.0.0 255.255.255.0).</para>
 
         <programlisting>#SOURCE                 DEST            PROVIDER        PRIORITY
 -                       10.8.0.0/24     main            1000</programlisting>
@@ -1050,4 +1050,82 @@ eth0(Avvanta) eth1            130.252.144.8 </programlisting>
 2:P               eth0:130.252.144.8/24 0.0.0.0/0</programlisting></para>
     </section>
   </section>
+
+  <section>
+    <title>ROUTE_BALANCE (Experimental)</title>
+
+    <para>Beginning with Shorewall 4.2.0 Beta3, Shorewall-perl has supported a
+    ROUTE_BALANCE option in <ulink
+    url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
+
+    <para>ROUTE_BALANCE=Yes is marked as Experimental currently. This means
+    that it is a 'use at your own risk' feature; if you encounter problems,
+    the Shorewall support staff may not be able to provide you with a quick
+    solution.</para>
+
+    <para>One of the drawbacks of the Mulit-ISP support as described in the
+    preceding section is that changes to the main table made by applications
+    are not added to the individual provider tables. This makes route rules
+    such as described in <link linkend="Openvpn">one of the examples
+    above</link> necessary.</para>
+
+    <para>ROUTE_BALANCE=Yes works around that problem by passing packets
+    through the main table first rather than last. This has a number of
+    implications:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Both the DUPLICATE and the COPY columns in the providers file
+        must remain empty or contain "-". The individual provider routing
+        tables generated when ROUTE_BALANCE=Yes contain only a host route to
+        the gateway and a default route via the gateway.</para>
+      </listitem>
+
+      <listitem>
+        <para>The balance option is assumed for all interfaces that do not
+        have the <emphasis role="bold">loose</emphasis> option.</para>
+      </listitem>
+
+      <listitem>
+        <para>The default route generated by Shorewall is added to the
+        <emphasis>default</emphasis> routing table (253) rather than to the
+        main routing table (254).</para>
+      </listitem>
+
+      <listitem>
+        <para>Packets are sent through the main routing table by a routing
+        rule with priority 999. In ), the priority range 1-998 may be used for
+        inserting rules that bypass the main table.</para>
+      </listitem>
+
+      <listitem>
+        <para>All provider gateways must be specified explicitly in the
+        GATEWAY column. 'detect' may not be specified. Note that for ppp
+        interfaces, the GATEWAY may remain unspecified ("-").</para>
+      </listitem>
+
+      <listitem>
+        <para>You should disable all default route management outside of
+        Shorewall. If a default should be added to the main table while
+        Shorewall is started, then all policy routing will stop working except
+        for those routing rules in the priority range 1-998.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>Although 'balance' is automatically assumed when ROUTE_BALANCE=Yes,
+    you can easily cause all traffic to use one provider except when you
+    explicitly direct it to use the other provider via <ulink
+    url="manpages/shorewall-route_rules.html">shorewall-route_rules</ulink>
+    (5) or <ulink
+    url="manpages/shorewall-tcrules.html">shorewall-tcrules</ulink>
+    (5).</para>
+
+    <para>Example (send all traffic through the 'shorewall' provider unless
+    otherwise directed).</para>
+
+    <para>/etc/shorewall/providers:<programlisting>#NAME    NUMBER MARK DUPLICATE INTERFACE GATEWAY       OPTIONS
+linksys       1    1    -        wlan0   172.20.1.1    track,balance=1,optional
+shorewall     2    2    -        eth0    192.168.1.254 track,balance=2,optional</programlisting>/etc/shorewall/rules:<programlisting>#SOURCE     DEST      PROVIDER        PRIORITY
+-           -         shorewall       11999</programlisting></para>
+  </section>
 </article>

manpages/shorewall.conf.xml

@@ -1353,6 +1353,30 @@ net     all  DROP   info</programlisting>then the chain name is 'net2all'
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><emphasis role="bold">ROUTE_FILTER=</emphasis>[<emphasis
+        role="bold">Yes</emphasis>|<emphasis
+        role="bold">No</emphasis>|Keep]</term>
+
+        <listitem>
+          <para>If this parameter is given the value <emphasis
+          role="bold">Yes</emphasis> or <emphasis role="bold">yes</emphasis>
+          then route filtering (anti-spoofing) is enabled on all network
+          interfaces which are brought up while Shorewall is in the started
+          state. The default value is <emphasis
+          role="bold">no</emphasis>.</para>
+
+          <para>The value <emphasis role="bold">Keep</emphasis> is only
+          allowed under Shorewall-perl. It causes Shorewall to ignore the
+          option. If the option is set to <emphasis
+          role="bold">Yes</emphasis>, then route filtering occurs on all
+          interfaces. If the option is set to <emphasis
+          role="bold">No</emphasis>, then route filtering is disabled on all
+          interfaces except those specified in <ulink
+          url="shorewall-interfaces.html">shorewall-interfaces</ulink>(5).</para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><emphasis role="bold">SAVE_IPSETS=</emphasis>{<emphasis
         role="bold">Yes</emphasis>|<emphasis role="bold">No</emphasis>}</term>