Documentation Updates

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

Shorewall-docs2/FAQ.xml

@@ -17,7 +17,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2004-08-10</pubdate>
+    <pubdate>2004-08-19</pubdate>
 
     <copyright>
       <year>2001-2004</year>
@@ -1776,9 +1776,9 @@ Creating input Chains...
       with your new kernel.</para>
 
       <section id="faq27a">
-        <title>(FAQ 27a) I just built and installed a new kernel and now
+        <title>(FAQ 27a) I just built (or downloaded or otherwise acquired)
-        Shorewall won't start. I know that my kernel options are
+        and installed a new kernel and now Shorewall won't start. I know that
-        correct.</title>
+        my kernel options are correct.</title>
 
         <para>The last few lines of <ulink url="troubleshoot.htm">a startup
         trace</ulink> are these:</para>
@@ -1816,6 +1816,16 @@ iptables: Invalid argument
     <title>Revision History</title>
 
     <para><revhistory>
+        <revision>
+          <revnumber>1.29</revnumber>
+
+          <date>2004-08-19</date>
+
+          <authorinitials>TE</authorinitials>
+
+          <revremark>Reword FAQ 27a to include downloaded kernels.</revremark>
+        </revision>
+
         <revision>
           <revnumber>1.28</revnumber>
 

Shorewall-docs2/IPSEC-2.6.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2004-08-15</pubdate>
+    <pubdate>2004-08-18</pubdate>
 
     <copyright>
       <year>2004</year>
@@ -46,6 +46,60 @@
     the responsible Netfilter developer who has confirmed the problem.</para>
   </warning>
 
+  <section>
+    <title>Shorewall 2.1 and Kernel 2.6 IPSEC</title>
+
+    <para>The 2.6 Linux Kernel introduces new facilities for defining
+    encrypted communication between hosts in a network. The network
+    administrator defines a set of Security Policies which are stored in the
+    kernel as a Security Policy Database (SPD). Outgoing traffic is encrypted
+    according to the contents of the SPD and incoming traffic is verified
+    against the SPD to ensure that no unencrypted traffic is accepted in
+    violation of the administrator's policies.</para>
+
+    <para>There are three ways in which IPSEC traffic can interact with
+    Shorewall policies and rules:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Traffic that is encrypted on the firewall system. The traffic
+        passes through Netfilter twice -- first as unencrypted then
+        encrypted.</para>
+      </listitem>
+
+      <listitem>
+        <para>Traffic that is decrypted on the firewall system. The traffic
+        passes through Netfilter twice -- first as encrypted then as
+        unencrypted.</para>
+      </listitem>
+
+      <listitem>
+        <para>Encrypted traffic that is passed through the firewall system.
+        The traffic passes through Netfilter once.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>In cases 1 and 2, the encrypted traffic is handled by entries in
+    <filename>/etc/shorewall/tunnels</filename> (don't be mislead by the name
+    of the file -- <emphasis>transport mode</emphasis> encrypted traffic is
+    also handled by entries in that file). The unencrypted traffic is handled
+    by normal rules and policies.</para>
+
+    <para>Under the 2.4 Linux Kernel, the association of unencrypted traffic
+    and zones was made easy by the presense of IPSEC pseudo-interfaces with
+    names of the form <filename class="devicefile">ipsecn</filename> (e.g.
+    <filename class="devicefile">ipsec0</filename>). Outgoing unencrypted
+    traffic (case 1.) was send through an <filename
+    class="devicefile">ipsecn</filename> device while incoming unencrypted
+    traffic (case 2) arrived from an <filename
+    class="devicefile">ipsecn</filename> device. The 2.6 kernel-based
+    implementation does away with these pseudo-interfaces. Outgoing traffic
+    that is going to be encrypted and incoming traffic that has been decrypted
+    must be matched against policies in the SPD.</para>
+
+    <para></para>
+  </section>
+
   <section>
     <title>IPSec Gateway on the Firewall System</title>
 

Shorewall-docs2/bridge.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2004-07-31</pubdate>
+    <pubdate>2004-08-19</pubdate>
 
     <copyright>
       <year>2004</year>
@@ -29,7 +29,8 @@
       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>
+      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
+      License</ulink></quote>.</para>
     </legalnotice>
   </articleinfo>
 
@@ -60,7 +61,8 @@
       </listitem>
 
       <listitem>
-        <para>A router cannot forward broadcast packets while a bridge can.</para>
+        <para>A router cannot forward broadcast packets while a bridge
+        can.</para>
       </listitem>
     </orderedlist>
   </section>
@@ -80,7 +82,8 @@
         <para>Your kernel must contain Netfilter physdev match support
         (CONFIG_IP_NF_MATCH_PHYSDEV=m or CONFIG_IP_NF_MATCH_PHYSDEV=y).
         Physdev match is standard in the 2.6 kernel series but must be patched
-        into the 2.4 kernels (see <ulink url="http://bridge.sf.net">http://bridge.sf.net</ulink>).</para>
+        into the 2.4 kernels (see <ulink
+        url="http://bridge.sf.net">http://bridge.sf.net</ulink>).</para>
       </listitem>
 
       <listitem>
@@ -108,7 +111,7 @@
     between the router and the systems in the local network. In the example
     shown, the network uses RFC 1918 addresses but that is not a requirement;
     the bridge would work exactly the same if public IP addresses were used
-    (remember that the bridge doesn&#39;t deal with IP addresses).</para>
+    (remember that the bridge doesn't deal with IP addresses).</para>
 
     <graphic fileref="images/bridge.png" />
 
@@ -125,13 +128,13 @@
 
       <listitem>
         <para>The systems connected to the LAN are configured with the
-        router&#39;s IP address (192.168.1.254 in the above diagram) as their
+        router's IP address (192.168.1.254 in the above diagram) as their
         default gateway.</para>
       </listitem>
 
       <listitem>
-        <para><command>traceroute</command> doesn&#39;t detect the
+        <para><command>traceroute</command> doesn't detect the Bridge/Firewall
-        Bridge/Firewall as an intermediate router.</para>
+        as an intermediate router.</para>
       </listitem>
 
       <listitem>
@@ -157,9 +160,9 @@
     configuration information may be found at <ulink
     url="http://bridge.sf.net">http://bridge.sf.net</ulink>.</para>
 
-    <para>Unfortunately, Linux distributions don&#39;t have good bridge
+    <para>Unfortunately, Linux distributions don't have good bridge
-    configuration tools and the network configuration GUIs don&#39;t detect
+    configuration tools and the network configuration GUIs don't detect the
-    the presence of bridge devices. You may refer to <ulink url="myfiles.htm">my
+    presence of bridge devices. You may refer to <ulink url="myfiles.htm">my
     configuration files</ulink> for an example of configuring a three-port
     bridge at system boot under <trademark>SuSE</trademark>. Here is an
     excerpt from a Debian <filename>/etc/network/interfaces</filename> file
@@ -183,22 +186,24 @@ iface br0 inet static
     doing so allows the bridge/firewall to access other systems and allows the
     bridge/firewall to be managed remotely. The bridge must also have an IP
     address for REJECT rules and policies to work correctly — otherwise REJECT
-    behaves the same as DROP.</para>
+    behaves the same as DROP. It is also a requirement for bridges to have an
+    IP address if they are part of a <link
+    linkend="bridge-router">bridge/router</link>.</para>
 
-    <para>The bridge may have its IP address assigned via DHCP. Here&#39;s an
+    <para>The bridge may have its IP address assigned via DHCP. Here's an
     example of an /etc/sysconfig/network/ifcfg-br0 file from a
     <trademark>SuSE</trademark> system:</para>
 
     <blockquote>
-      <programlisting>BOOTPROTO=&#39;dhcp&#39;
+      <programlisting>BOOTPROTO='dhcp'
-REMOTE_IPADDR=&#39;&#39;
+REMOTE_IPADDR=''
-STARTMODE=&#39;onboot&#39;
+STARTMODE='onboot'
-UNIQUE=&#39;3hqH.MjuOqWfSZ+C&#39;
+UNIQUE='3hqH.MjuOqWfSZ+C'
-WIRELESS=&#39;no&#39;
+WIRELESS='no'
-MTU=&#39;&#39;</programlisting>
+MTU=''</programlisting>
     </blockquote>
 
-    <para>Here&#39;s an /etc/sysconfig/network-scripts/ifcfg-br0 file for a
+    <para>Here's an /etc/sysconfig/network-scripts/ifcfg-br0 file for a
     <trademark>Mandrake</trademark> system:</para>
 
     <blockquote>
@@ -209,7 +214,8 @@ ONBOOT=yes</programlisting>
 
     <para>On both the SuSE and Mandrake systems, a separate script is required
     to configure the bridge itself (again see <ulink url="myfiles.htm">my
-    configuration files</ulink> for an example - <filename>/etc/init.d/bridge</filename>).</para>
+    configuration files</ulink> for an example -
+    <filename>/etc/init.d/bridge</filename>).</para>
 
     <para>Axel Westerhold has contributed this example of configuring a bridge
     with a static IP address on a Fedora System (Core 1 and Core 2 Test 1).
@@ -243,12 +249,12 @@ ONBOOT=yes</programlisting></para>
 # description: Layer 2 Bridge
 #
 
-[ -f /etc/sysconfig/bridge ] &#38;&#38; . /etc/sysconfig/bridge
+[ -f /etc/sysconfig/bridge ] &amp;&amp; . /etc/sysconfig/bridge
 
 PATH=$PATH:/sbin:/usr/sbin:/usr/local/sbin
 
 do_stop() {
-    echo &#34;Stopping Bridge&#34;
+    echo "Stopping Bridge"
     for i in $INTERFACES $BRIDGE_INTERFACE ; do
     	ip link set $i down
     done
@@ -257,7 +263,7 @@ do_stop() {
 
 do_start() {
 
-   echo &#34;Starting Bridge&#34;
+   echo "Starting Bridge"
    for i in $INTERFACES ; do
         ip link set $i up
    done
@@ -269,7 +275,7 @@ do_start() {
    ifup $BRIDGE_INTERFACE 
 }
 
-case &#34;$1&#34; in
+case "$1" in
   start)
       do_start
     ;;
@@ -282,7 +288,7 @@ case &#34;$1&#34; in
       do_start
     ;;
   *)
-    echo &#34;Usage: $0 {start|stop|restart}&#34;
+    echo "Usage: $0 {start|stop|restart}"
     exit 1
 esac
 exit 0</programlisting>
@@ -290,7 +296,7 @@ exit 0</programlisting>
       <para>The <filename>/etc/sysconfig/bridge file</filename>:</para>
 
       <programlisting>BRIDGE_INTERFACE=br0          #The name of your Bridge
-INTERFACES=&#34;eth0 eth1&#34;        #The physical interfaces to be bridged</programlisting>
+INTERFACES="eth0 eth1"        #The physical interfaces to be bridged</programlisting>
     </blockquote>
 
     <para>Andrzej Szelachowski contributed the following.</para>
@@ -298,15 +304,15 @@ INTERFACES=&#34;eth0 eth1&#34;        #The physical interfaces to be bridged</pr
     <blockquote>
       <programlisting>Here is how I configured bridge in Slackware:
 
-1) I had to compile bridge-utils (It&#39;s not in the standard distribution)
+1) I had to compile bridge-utils (It's not in the standard distribution)
-2) I&#39;ve created rc.bridge in /etc/rc.d:
+2) I've created rc.bridge in /etc/rc.d:
 
 #########################
 #! /bin/sh
 
 ifconfig eth0 0.0.0.0
 ifconfig eth1 0.0.0.0
-#ifconfig lo 127.0.0.1 #this line should be uncommented if you don&#39;t use rc.inet1
+#ifconfig lo 127.0.0.1 #this line should be uncommented if you don't use rc.inet1
 
 brctl addbr most
 
@@ -315,7 +321,7 @@ brctl addif most eth1
 
 ifconfig most 192.168.1.31 netmask 255.255.255.0 up 
 #route add default gw 192.168.1.1 metric 1 #this line should be uncommented if
-                                           #you don&#39;t use rc.inet1
+                                           #you don't use rc.inet1
 #########################
 
 3) I made rc.brige executable and added the following line to /etc/rc.d/rc.local
@@ -356,16 +362,17 @@ all         all         REJECT        info
 #LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE</programlisting>
 
     <para>Only the bridge device itself is configured with an IP address so
-    only that device is defined to Shorewall in <filename>/etc/shorewall/interfaces</filename>:</para>
+    only that device is defined to Shorewall in
+    <filename>/etc/shorewall/interfaces</filename>:</para>
 
     <programlisting>#ZONE    INTERFACE      BROADCAST       OPTIONS
 -       br0             192.168.1.255
 #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>
 
-    <para>The zones are defined using the <filename>/etc/shorewall/hosts</filename>
+    <para>The zones are defined using the
-    file. Assuming that the router is connected to <filename
+    <filename>/etc/shorewall/hosts</filename> file. Assuming that the router
-    class="devicefile">eth0</filename> and the switch to <filename
+    is connected to <filename class="devicefile">eth0</filename> and the
-    class="devicefile">eth1</filename>:</para>
+    switch to <filename class="devicefile">eth1</filename>:</para>
 
     <programlisting>#ZONE           HOST(S)                         OPTIONS
 net             br0:eth0
@@ -373,7 +380,8 @@ loc             br0:eth1
 #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS LINE -- DO NOT REMOVE</programlisting>
 
     <para>When Shorewall is stopped, you want to allow only local traffic
-    through the bridge — <filename><filename>/etc/shorewall/routestopped</filename></filename>:</para>
+    through the bridge —
+    <filename><filename>/etc/shorewall/routestopped</filename></filename>:</para>
 
     <programlisting>#INTERFACE      HOST(S)         OPTIONS
 br0             192.168.1.0/24  routeback
@@ -384,11 +392,11 @@ br0             192.168.1.0/24  routeback
     firewall rules.</para>
   </section>
 
-  <section>
+  <section id="bridge-router">
     <title>Combination Router/Bridge</title>
 
-    <para>A system running Shorewall doesn&#39;t have to be exclusively a
+    <para>A system running Shorewall doesn't have to be exclusively a bridge
-    bridge or a router -- it can act as both. Here&#39;s an example:<graphic
+    or a router -- it can act as both. Here's an example:<graphic
     fileref="images/bridge2.png" /></para>
 
     <para>This is basically the same setup as shown in the <ulink
@@ -410,7 +418,8 @@ loc      eth1           detect</programlisting></para>
       </listitem>
 
       <listitem>
-        <para>The <filename>/etc/shorewall/hosts</filename> file would have:</para>
+        <para>The <filename>/etc/shorewall/hosts</filename> file would
+        have:</para>
 
         <programlisting>#ZONE    HOSTS                        OPTIONS
 net      br0:eth0
@@ -422,7 +431,7 @@ dmz      br0:eth2</programlisting>
   <section>
     <title>Limitations</title>
 
-    <para>Bridging doesn&#39; t work with some wireless cards — see <ulink
+    <para>Bridging doesn' t work with some wireless cards — see <ulink
     url="http://bridge.sf.net">http://bridge.sf.net</ulink>.</para>
   </section>
 </article>