Add Shorewall Init Documentation

docs/Documentation_Index.xml

@@ -60,8 +60,8 @@
             <entry><ulink url="KVM.html">KVM (Kernel-mode Virtual
             Machine)</ulink></entry>
 
-            <entry><ulink url="Shorewall-perl.html">Shorewall
+            <entry><ulink url="Laptop.html">Shorewall on a
-            Perl</ulink></entry>
+            Laptop</ulink></entry>
           </row>
 
           <row>
@@ -70,8 +70,8 @@
             <entry><ulink url="ConnectionRate.html">Limiting Connection
             Rates</ulink></entry>
 
-            <entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
+            <entry><ulink url="Shorewall-perl.html">Shorewall
-            Guide</ulink></entry>
+            Perl</ulink></entry>
           </row>
 
           <row>
@@ -79,7 +79,8 @@
 
             <entry><ulink url="shorewall_logging.html">Logging</ulink></entry>
 
-            <entry><ulink url="samba.htm">SMB</ulink></entry>
+            <entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
+            Guide</ulink></entry>
           </row>
 
           <row>
@@ -87,9 +88,7 @@
 
             <entry><ulink url="Macros.html">Macros</ulink></entry>
 
-            <entry><ulink url="two-interface.htm#SNAT">SNAT</ulink>
+            <entry><ulink url="samba.htm">SMB</ulink></entry>
-            (<firstterm>Source Network Address
-            Translation</firstterm>)</entry>
           </row>
 
           <row>
@@ -99,8 +98,9 @@
             <entry><ulink url="MAC_Validation.html">MAC
             Verification</ulink></entry>
 
-            <entry><ulink url="SplitDNS.html">Split DNS the Easy
+            <entry><ulink url="two-interface.htm#SNAT">SNAT</ulink>
-            Way</ulink></entry>
+            (<firstterm>Source Network Address
+            Translation</firstterm>)</entry>
           </row>
 
           <row>
@@ -109,8 +109,8 @@
 
             <entry><ulink url="Manpages.html">Man Pages</ulink></entry>
 
-            <entry><ulink url="Shorewall_Squid_Usage.html">Squid with
+            <entry><ulink url="SplitDNS.html">Split DNS the Easy
-            Shorewall</ulink></entry>
+            Way</ulink></entry>
           </row>
 
           <row>
@@ -120,9 +120,8 @@
             <entry><ulink url="ManualChains.html">Manual
             Chains</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>
@@ -133,8 +132,9 @@
             <entry><ulink
             url="two-interface.htm#SNAT">Masquerading</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>
@@ -145,7 +145,8 @@
             from a Single Firewall</ulink> (<ulink
             url="MultiISP_ru.html">Russian</ulink>)</entry>
 
-            <entry><ulink url="support.htm">Support</ulink></entry>
+            <entry><ulink url="NAT.htm">Static (one-to-one)
+            NAT</ulink></entry>
           </row>
 
           <row>
@@ -155,8 +156,7 @@
             <entry><ulink url="Multiple_Zones.html">Multiple Zones Through One
             Interface</ulink></entry>
 
-            <entry><ulink url="configuration_file_basics.htm">Tips and
+            <entry><ulink url="support.htm">Support</ulink></entry>
-            Hints</ulink></entry>
           </row>
 
           <row>
@@ -166,8 +166,8 @@
             <entry><ulink url="MyNetwork.html">My Shorewall
             Configuration</ulink></entry>
 
-            <entry><ulink url="Accounting.html">Traffic
+            <entry><ulink url="configuration_file_basics.htm">Tips and
-            Accounting</ulink></entry>
+            Hints</ulink></entry>
           </row>
 
           <row>
@@ -177,8 +177,8 @@
             <entry><ulink url="NetfilterOverview.html">Netfilter
             Overview</ulink></entry>
 
-            <entry><ulink url="simple_traffic_shaping.html">Traffic
+            <entry><ulink url="Accounting.html">Traffic
-            Shaping/QOS - Simple</ulink></entry>
+            Accounting</ulink></entry>
           </row>
 
           <row>
@@ -187,9 +187,8 @@
 
             <entry><ulink url="netmap.html">Network Mapping</ulink></entry>
 
-            <entry><ulink url="traffic_shaping.htm">Traffic Shaping/QOS -
+            <entry> <ulink url="simple_traffic_shaping.html">Traffic
-            Complex</ulink> (<ulink
+            Shaping/QOS - Simple</ulink></entry>
-            url="traffic_shaping_ru.html">Russian</ulink>)</entry>
           </row>
 
           <row>
@@ -199,8 +198,9 @@
             <entry><ulink url="NAT.htm">One-to-one NAT</ulink> (Static
             NAT)</entry>
 
-            <entry><ulink url="Shorewall_Squid_Usage.html">Transparent
+            <entry><ulink url="traffic_shaping.htm">Traffic Shaping/QOS -
-            Proxy</ulink></entry>
+            Complex</ulink> (<ulink
+            url="traffic_shaping_ru.html">Russian</ulink>)</entry>
           </row>
 
           <row>
@@ -209,7 +209,8 @@
             <entry><ulink url="Multiple_Zones.html"><ulink
             url="OPENVPN.html">OpenVPN</ulink></ulink></entry>
 
-            <entry><ulink url="UPnP.html">UPnP</ulink></entry>
+            <entry><ulink url="Shorewall_Squid_Usage.html">Transparent
+            Proxy</ulink></entry>
           </row>
 
           <row>
@@ -219,8 +220,7 @@
 
             <entry><ulink url="OpenVZ.html">OpenVZ</ulink></entry>
 
-            <entry><ulink url="upgrade_issues.htm">Upgrade
+            <entry><ulink url="UPnP.html">UPnP</ulink></entry>
-            Issues</ulink></entry>
           </row>
 
           <row>
@@ -229,8 +229,7 @@
             <entry><ulink url="starting_and_stopping_shorewall.htm">Operating
             Shorewall</ulink></entry>
 
-            <entry><ulink url="LennyToSqueeze.html">Upgrading to Shorewall 4.4
+            <entry><ulink url="OpenVZ.html">OpenVZ</ulink></entry>
-            (Upgrading Debian Lenny to Squeeze)</ulink></entry>
           </row>
 
           <row>
@@ -240,7 +239,8 @@
             <entry><ulink url="PacketMarking.html">Packet
             Marking</ulink></entry>
 
-            <entry><ulink url="VPNBasics.html">VPN</ulink></entry>
+            <entry><ulink url="LennyToSqueeze.html">Upgrading to Shorewall 4.4
+            (Upgrading Debian Lenny to Squeeze)</ulink></entry>
           </row>
 
           <row>
@@ -251,7 +251,7 @@
             <entry><ulink url="PacketHandling.html">Packet Processing in a
             Shorewall-based Firewall</ulink></entry>
 
-            <entry><ulink url="VPN.htm">VPN Passthrough</ulink></entry>
+            <entry><ulink url="VPNBasics.html">VPN</ulink></entry>
           </row>
 
           <row>
@@ -260,8 +260,7 @@
 
             <entry><ulink url="ping.html">'Ping' Management</ulink></entry>
 
-            <entry><ulink url="whitelisting_under_shorewall.htm">White List
+            <entry><ulink url="VPN.htm">VPN Passthrough</ulink></entry>
-            Creation</ulink></entry>
           </row>
 
           <row>
@@ -270,8 +269,8 @@
             <entry><ulink url="two-interface.htm#DNAT">Port
             Forwarding</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>
@@ -280,8 +279,8 @@
 
             <entry><ulink url="ports.htm">Port Information</ulink></entry>
 
-            <entry><ulink url="XenMyWay-Routed.html">Xen - Shorewall in Routed
+            <entry><ulink url="XenMyWay.html">Xen - Shorewall in a Bridged Xen
-            Xen Dom0</ulink></entry>
+            DomU</ulink></entry>
           </row>
 
           <row>
@@ -291,7 +290,8 @@
             <entry><ulink url="PortKnocking.html">Port Knocking and Other Uses
             of the 'Recent Match'</ulink></entry>
 
-            <entry></entry>
+            <entry><ulink url="XenMyWay-Routed.html">Xen - Shorewall in Routed
+            Xen Dom0</ulink></entry>
           </row>
 
           <row>
@@ -371,8 +371,8 @@
             <entry><ulink url="Shorewall_and_Kazaa.html">Kazaa
             Filtering</ulink></entry>
 
-            <entry><ulink url="Laptop.html">Shorewall on a
+            <entry><ulink url="Shorewall-init.html">Shorewall
-            Laptop</ulink></entry>
+            Init</ulink></entry>
 
             <entry></entry>
           </row>

docs/Shorewall-init.xml

@@ -0,0 +1,284 @@
+<?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>Shorewall Init</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Tom</firstname>
+
+        <surname>Eastep</surname>
+      </author>
+    </authorgroup>
+
+    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
+
+    <copyright>
+      <year>2010</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 Shorewall init scripts released from shorewall.net and by most
+    distributions start Shorewall after networking. This allows Shorewall to
+    detect the network configuration and taylor itself accordingly. It is
+    possible to start Shorewall prior to networking but doing so limits the
+    set of Shorewall features that can be used.</para>
+
+    <para>When Shorewall starts after networking, there is the possibility of
+    unwanted connections being accepted between the time that an interface
+    comes up and the time that Shorewall has finished starting up. Also,
+    Shorewall has had no means of reacting when interfaces are brought up and
+    down.</para>
+
+    <para>Beginning with Shorewall 4.4.10, a new package, <firstterm>Shorewall
+    Init</firstterm>, is available. Shorewall Init serves two purposes:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>It can 'close' the firewall before the network interfaces are
+        brought up during boot.</para>
+      </listitem>
+
+      <listitem>
+        <para>It can change the firewall state as the result of interfaces
+        being brought up or taken down.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>These two features can be controlled independently. Shorewall Init
+    can be used together with any combination of the other Shorewall packages.
+    Shorewall-init works on RedHat-based, SuSE-based and Debian-based
+    distributions.</para>
+  </section>
+
+  <section id="Close">
+    <title>Closing the Firewall before the Network Interfaces are brought
+    up</title>
+
+    <para> When Shorewall-init is first installed, it does nothing until you
+    configure it.</para>
+
+    <para>The configuration file is <filename>/etc/default/shorewall-init
+    </filename>on Debian-based systems and
+    <filename>/etc/sysconfig/shorewall-init</filename> otherwise. There are
+    two settings in the file: </para>
+
+    <variablelist>
+      <varlistentry>
+        <term>PRODUCTS</term>
+
+        <listitem>
+          <para>Lists the Shorewall packages that you want to integrate with
+          Shorewall-init.</para>
+
+          <para>Example: PRODUCTS="shorewall shorewall6"</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>IFUPDOWN</term>
+
+        <listitem>
+          <para>When set to 1, enables integration with NetworkManager and the
+          ifup/ifdown scripts.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>To close your firewall before networking starts:</para>
+
+    <orderedlist numeration="loweralpha">
+      <listitem>
+        <para>In the Shorewall-init configuration file, set PRODUCTS to the
+        firewall products installed on your system.</para>
+      </listitem>
+
+      <listitem>
+        <para>Be sure that your current firewall script(s) (normally in
+        <filename>/var/lib/&lt;product&gt;/firewall</filename>) is(are)
+        compiled with the 4.4.10 compiler. </para>
+
+        <para>Shorewall and Shorewall6 users can execute these
+        commands:</para>
+
+        <simplelist>
+          <member>shorewall compile</member>
+
+          <member><command>shorewall6 compile</command></member>
+        </simplelist>
+
+        <para>Shorewall-lite and Shorewall6-lite users can execute these
+        commands on the administrative system:</para>
+
+        <simplelist>
+          <member><command>shorewall export
+          <replaceable>firewall-name-or-ip-address</replaceable></command></member>
+
+          <member><command>shorewall6 export
+          <replaceable>firewall-name-or-ip-address</replaceable></command></member>
+        </simplelist>
+      </listitem>
+    </orderedlist>
+
+    <para>That's all that is required. </para>
+  </section>
+
+  <section id="NM">
+    <title>Integration with NetworkManager and ifup/ifdown Scripts</title>
+
+    <para>To integrate with NetworkManager and ifup/ifdown, additional steps
+    are required. You probably don't want to enable this feature if you run a
+    link status monitor like swping or LSM. </para>
+
+    <orderedlist numeration="loweralpha">
+      <listitem>
+        <para>In the Shorewall-init configuration file, set IFUPDOWN=1.</para>
+      </listitem>
+
+      <listitem>
+        <para>In your Shorewall interfaces file(s), set the
+        <option>required</option> option on any interfaces that must be up in
+        order for the firewall to start. At least one interface must have the
+        <option>required</option> or <option>optional</option> option if you
+        perform the next optional step.</para>
+      </listitem>
+
+      <listitem>
+        <para>Optional) -- If you have specified at least one
+        <option>required</option> or <option>optional</option> interface, you
+        can then disable automatic firewall startup at boot time. On
+        Debian-based systems, set startup=0 in
+        <filename>/etc/default/<replaceable>product</replaceable></filename>.
+        On other systems, use your service startup configuration tool
+        (chkconfig, insserv, ...) to disable startup. </para>
+      </listitem>
+    </orderedlist>
+
+    <para>The following actions occur when an interface comes up: </para>
+
+    <informaltable>
+      <tgroup cols="3">
+        <tbody>
+          <row>
+            <entry><emphasis role="bold">FIREWALL STATE</emphasis></entry>
+
+            <entry><emphasis role="bold">INTERFACE</emphasis></entry>
+
+            <entry><emphasis role="bold">ACTION</emphasis></entry>
+          </row>
+
+          <row>
+            <entry>Any</entry>
+
+            <entry>Required</entry>
+
+            <entry>start</entry>
+          </row>
+
+          <row>
+            <entry>stopped</entry>
+
+            <entry>Optional</entry>
+
+            <entry>start</entry>
+          </row>
+
+          <row>
+            <entry>started</entry>
+
+            <entry>Any</entry>
+
+            <entry>restart</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+
+    <para>The following actions occur when an interface goes down:</para>
+
+    <informaltable>
+      <tgroup cols="3">
+        <tbody>
+          <row>
+            <entry><emphasis role="bold">FIREWALL STATE</emphasis></entry>
+
+            <entry><emphasis role="bold">INTERFACE</emphasis></entry>
+
+            <entry><emphasis role="bold">ACTION</emphasis></entry>
+          </row>
+
+          <row>
+            <entry>Any</entry>
+
+            <entry>Required</entry>
+
+            <entry>stop</entry>
+          </row>
+
+          <row>
+            <entry>stopped</entry>
+
+            <entry>Optional</entry>
+
+            <entry>start</entry>
+          </row>
+
+          <row>
+            <entry>started</entry>
+
+            <entry>Any</entry>
+
+            <entry>restart</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+
+    <para> For optional interfaces, the
+    <filename>/var/lib/<replaceable>product</replaceable>/<replaceable>interface</replaceable>.state</filename>
+    files are maintained to reflect the state of the interface so that they
+    may be used by the standard <firstterm>isusable</firstterm> script. Please
+    note that the action is carried out using the current compiled script; the
+    configuration is not recompiled.</para>
+
+    <para>A new option has been added to <filename>shorewall.conf</filename>
+    and <filename>shorewall6.conf</filename>. The REQUIRE_INTERFACE option
+    determines the outcome when an attempt to start/restart/restore/refresh
+    the firewall is made and none of the optional interfaces are available.
+    With REQUIRE_INTERFACE=No (the default), the operation is performed. If
+    REQUIRE_INTERFACE=Yes, then the operation fails and the firewall is placed
+    in the stopped state. This option is suitable for a laptop with both
+    ethernet and wireless interfaces. If either come up, the firewall starts.
+    If neither comes up, the firewall remains in the stopped state.</para>
+
+    <para>Similarly, if an optional interface goes down and there are no
+    optional interfaces remaining in the up state, then the firewall is
+    stopped. </para>
+
+    <para>On Debian-based systems, during system shutdown the firewall is
+    opened prior to network shutdown (<command>/etc/init.d/shorewall
+    stop</command> performs a 'clear' operation rather than a 'stop'). This is
+    required by Debian standards. You can change this default behavior by
+    setting SAFESTOP=1 in <filename>/etc/default/shorewall</filename>
+    (<filename>/etc/default/shorewall6</filename>, ...). </para>
+  </section>
+</article>