Add a manpage describing nested zones

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

manpages/shorewall-nesting.xml

@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+  <refmeta>
+    <refentrytitle>shorewall-nesting</refentrytitle>
+
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Nesting</refname>
+
+    <refpurpose>Shorewall Nested Zones</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <arg choice="plain"
+      rep="norepeat"><replaceable>child-zone</replaceable>[:<replaceable>parent-zone</replaceable>[,<replaceable>parent-zone</replaceable>]...]</arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>In <ulink url="shorewall-zones.html">shorewall-zones</ulink>(5), a
+    zone may be declared to be a sub-zone of one or more other zones using the
+    above syntax. </para>
+
+    <para>Where zones are nested, the CONTINUE policy in <ulink
+    url="shorewall-policy.html">shorewall-policy</ulink>(5) allows hosts that
+    are within multiple zones to be managed under the rules of all of these
+    zones.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
+
+    <para><filename>/etc/shorewall/zones</filename>:</para>
+
+    <programlisting>        #ZONE    TYPE        OPTION
+        fw       firewall
+        net      ipv4
+        sam:net  ipv4
+        loc      ipv4</programlisting>
+
+    <para><filename>/etc/shorewall/interfaces</filename>:</para>
+
+    <programlisting>        #ZONE     INTERFACE     BROADCAST     OPTIONS
+        -         eth0          detect        dhcp,norfc1918
+        loc       eth1          detect</programlisting>
+
+    <para><filename>/etc/shorewall/hosts</filename>:</para>
+
+    <programlisting>        #ZONE     HOST(S)                     OPTIONS
+        net       eth0:0.0.0.0/0
+        sam       eth0:206.191.149.197</programlisting>
+
+    <para><filename>/etc/shorewall/policy</filename>:</para>
+
+    <programlisting>        #SOURCE      DEST        POLICY       LOG LEVEL
+        loc          net         ACCEPT
+        sam          all         CONTINUE
+        net          all         DROP         info
+        all          all         REJECT       info</programlisting>
+
+    <para>The second entry above says that when Sam is the client, connection
+    requests should first be processed under rules where the source zone is
+    sam and if there is no match then the connection request should be treated
+    under rules where the source zone is net. It is important that this policy
+    be listed BEFORE the next policy (net to all).</para>
+
+    <para>Partial <filename>/etc/shorewall/rules</filename>:</para>
+
+    <programlisting>        #ACTION   SOURCE    DEST            PROTO    DEST PORT(S)
+        ...
+        DNAT      sam       loc:192.168.1.3 tcp      ssh
+        DNAT      net       loc:192.168.1.5 tcp      www
+        ...</programlisting>
+
+    <para>Given these two rules, Sam can connect to the firewall's internet
+    interface with ssh and the connection request will be forwarded to
+    192.168.1.3. Like all hosts in the net zone, Sam can connect to the
+    firewall's internet interface on TCP port 80 and the connection request
+    will be forwarded to 192.168.1.5. The order of the rules is not
+    significant. Sometimes it is necessary to suppress port forwarding for a
+    sub-zone. For example, suppose that all hosts can SSH to the firewall and
+    be forwarded to 192.168.1.5 EXCEPT Sam. When Sam connects to the
+    firewall's external IP, he should be connected to the firewall itself.
+    Because of the way that Netfilter is constructed, this requires two rules
+    as follows:</para>
+
+    <programlisting>        #ACTION   SOURCE    DEST            PROTO    DEST PORT(S)
+        ...
+        ACCEPT+   sam       $FW             tcp      ssh
+        DNAT      net       loc:192.168.1.3 tcp      ssh
+        ...</programlisting>
+
+    <para>The first rule allows Sam SSH access to the firewall. The second
+    rule says that any clients from the net zone with the exception of those
+    in the “sam” zone should have their connection port forwarded to
+    192.168.1.3. If you need to exclude more than one zone, simply use
+    multiple ACCEPT+ rules. This technique also may be used when the ACTION is
+    REDIRECT.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>FILES</title>
+
+    <para>/etc/shorewall/zones</para>
+
+    <para>/etc/shorewall/interfaces</para>
+
+    <para>/etc/shorewall/hosts</para>
+
+    <para>/etc/shorewall/policy</para>
+
+    <para>/etc/shorewall/rules</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See ALSO</title>
+
+    <para>shorewall(8), shorewall-accounting(5), shorewall-actions(5),
+    shorewall-blacklist(5), shorewall-hosts(5), shorewall-interfaces(5),
+    shorewall-ipsec(5), shorewall-maclist(5), shorewall-masq(5),
+    shorewall-nat(5), shorewall-netmap(5), shorewall-params(5),
+    shorewall-policy(5), shorewall-providers(5), shorewall-proxyarp(5),
+    shorewall-route_rules(5), shorewall-routestopped(5), shorewall-rules(5),
+    shorewall.conf(5), shorewall-tcclasses(5), shorewall-tcdevices(5),
+    shorewall-tcrules(5), shorewall-tos(5), shorewall-tunnels(5),
+    shorewall-zones(5)</para>
+  </refsect1>
+</refentry>

manpages/shorewall-policy.xml

@@ -143,7 +143,9 @@
                 <para>Pass the connection request past any other rules that it
                 might also match (where the source or destination zone in
                 those rules is a superset of the SOURCE or DEST in this
-                policy).</para>
+                policy). See <ulink
+                url="shorewall-nesting.html">shorewall-nesting</ulink>(5) for
+                additional information.</para>
               </listitem>
             </varlistentry>
 

manpages/shorewall-zones.xml

@@ -58,7 +58,9 @@
           <para>Where a zone is nested in one or more other zones, you may
           follow the (sub)zone name by ":" and a comma-separated list of the
           parent zones. The parent zones must have been declared in earlier
-          records in this file.</para>
+          records in this file. See <ulink
+          url="shorewall-nesting.html">shorewall-nesting</ulink>(5) for
+          additional information.</para>
 
           <para>Example:</para>
 
@@ -70,7 +72,7 @@ c:a,b     ipv4</programlisting>
           <para>Currently, Shorewall uses this information to reorder the zone
           list so that parent zones appear after their subzones in the list.
           The IMPLICIT_CONTINUE option in shorewall.conf can also create
-          implicit CONTINUE policies to/from the subzone.</para>
+          implicit CONTINUE policies to/from the subzone. </para>
 
           <para>In the future, Shorewall may make additional use of nesting
           information.</para>