Shorewall 3.4 documentation updates

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

docs/Actions.xml

@@ -113,6 +113,14 @@ ACCEPT   -              -               tcp     135,139,445
   </section>
 
   <section>
+    <title>Enabling the Use of Actions</title>
+
+    <para>In Shorewall version 3.4 and later, to make use of any of the three
+    types of actions you must set the USE_ACTIONS option to Yes in
+    <filename>/etc/shorewall/shorewall.conf</filename>.</para>
+  </section>
+
+  <section id="Default">
     <title>Default Actions (Formerly Common Actions)</title>
 
     <para>Shorewall allows the association of a <firstterm>default
@@ -140,17 +148,37 @@ ACCEPT   -              -               tcp     135,139,445
       </listitem>
     </orderedlist>
 
-    <para>Shorewall provides default actions for the REJECT and DROP policies.
+    <para>If you are running Shorewall 3.2 or earlier, then:</para>
-    The default action for REJECT is named <firstterm>Reject</firstterm> and
-    the default action for DROP is named <firstterm>Drop</firstterm>. These
-    associations are made through two entries in
-    /usr/share/shorewall/actions.std:</para>
 
-    <programlisting>Drop:DROP       #Default Action for DROP policy
+    <blockquote>
+      <para>Shorewall provides default actions for the REJECT and DROP
+      policies. The default action for REJECT is named
+      <firstterm>Reject</firstterm> and the default action for DROP is named
+      <firstterm>Drop</firstterm>. These associations are made through two
+      entries in /usr/share/shorewall/actions.std:</para>
+
+      <programlisting>Drop:DROP       #Default Action for DROP policy
 Reject:REJECT   #Default Action for REJECT policy</programlisting>
 
-    <para>These may be overridden by entries in your /etc/shorewall/actions
+      <para>These may be overridden by entries in your /etc/shorewall/actions
-    file.</para>
+      file.</para>
+    </blockquote>
+
+    <para>If you are running Shorewall 3.4 or later, then:</para>
+
+    <blockquote>
+      <para>Shorewall supports default actions for the ACCEPT, REJECT, DROP
+      and QUEUE policies. These default actions are specified in the
+      /etc/shorewall/shorewall.conf file using the ACCEPT_DEFAULT,
+      REJECT_DEFAULT, DROP_DEFAULT and QUEUE_DEFAULT options respectively.
+      Policies whose default is set to a value of "none" have no default
+      action.</para>
+
+      <para>In addition, the default specified in
+      /etc/shorewall/shorewall.conf may be overridden by specifying a
+      different default in the POLICY column of <ulink
+      url="Documentation.htm#Policy">/etc/shorewall/policy</ulink>.</para>
+    </blockquote>
 
     <warning>
       <para>Entries in the DROP and REJECT default actions <emphasis

docs/Documentation_Index.xml

@@ -196,8 +196,8 @@
             <entry><ulink url="PortKnocking.html#Limit">Limiting per-IPaddress
             Connection Rate</ulink></entry>
 
-            <entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
+            <entry><ulink url="Modularization.html">Shorewall
-            Guide</ulink></entry>
+            Modularization</ulink></entry>
           </row>
 
           <row>
@@ -206,7 +206,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>
@@ -215,8 +216,7 @@
 
             <entry><ulink url="Macros.html">Macros</ulink></entry>
 
-            <entry><ulink url="Shorewall_Squid_Usage.html">Squid with
+            <entry><ulink url="samba.htm">SMB</ulink></entry>
-            Shorewall</ulink></entry>
           </row>
 
           <row>
@@ -226,9 +226,8 @@
             <entry><ulink url="MAC_Validation.html">MAC
             Verification</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>
@@ -238,8 +237,9 @@
             <entry><ulink url="MultiISP.html">Multiple Internet Connections
             from a Single Firewall</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>
@@ -249,7 +249,8 @@
             <entry><ulink url="Multiple_Zones.html">Multiple Zones Through One
             Interface</ulink></entry>
 
-            <entry><ulink url="support.htm">Support</ulink></entry>
+            <entry><ulink url="NAT.htm">Static (one-to-one)
+            NAT</ulink></entry>
           </row>
 
           <row>
@@ -259,8 +260,7 @@
             <entry><ulink url="XenMyWay-Routed.html">My Shorewall
             Configuration</ulink></entry>
 
-            <entry><ulink url="Accounting.html">Traffic
+            <entry><ulink url="support.htm">Support</ulink></entry>
-            Accounting</ulink></entry>
           </row>
 
           <row>
@@ -270,8 +270,8 @@
             <entry><ulink url="NetfilterOverview.html">Netfilter
             Overview</ulink></entry>
 
-            <entry><ulink url="traffic_shaping.htm">Traffic
+            <entry><ulink url="Accounting.html">Traffic
-            Shaping/QOS</ulink></entry>
+            Accounting</ulink></entry>
           </row>
 
           <row>
@@ -280,8 +280,8 @@
 
             <entry><ulink url="netmap.html">Network Mapping</ulink></entry>
 
-            <entry><ulink
+            <entry><ulink url="traffic_shaping.htm">Traffic
-            url="troubleshoot.htm">Troubleshooting</ulink></entry>
+            Shaping/QOS</ulink></entry>
           </row>
 
           <row>
@@ -290,7 +290,8 @@
             <entry><ulink url="NAT.htm">One-to-one NAT</ulink> (Static
             NAT)</entry>
 
-            <entry><ulink url="UPnP.html">UPnP</ulink></entry>
+            <entry><ulink
+            url="troubleshoot.htm">Troubleshooting</ulink></entry>
           </row>
 
           <row>
@@ -299,8 +300,7 @@
 
             <entry><ulink url="OPENVPN.html">OpenVPN</ulink></entry>
 
-            <entry><ulink url="upgrade_issues.htm">Upgrade
+            <entry><ulink url="UPnP.html">UPnP</ulink></entry>
-            Issues</ulink></entry>
           </row>
 
           <row>
@@ -310,7 +310,8 @@
             <entry><ulink url="starting_and_stopping_shorewall.htm">Operating
             Shorewall</ulink></entry>
 
-            <entry><ulink url="VPNBasics.html">VPN</ulink></entry>
+            <entry><ulink url="upgrade_issues.htm">Upgrade
+            Issues</ulink></entry>
           </row>
 
           <row>
@@ -320,8 +321,7 @@
             <entry><ulink url="PacketMarking.html">Packet
             Marking</ulink></entry>
 
-            <entry><ulink url="whitelisting_under_shorewall.htm">White List
+            <entry><ulink url="VPNBasics.html">VPN</ulink></entry>
-            Creation</ulink></entry>
           </row>
 
           <row>
@@ -331,8 +331,8 @@
             <entry><ulink url="PacketHandling.html">Packet Processing in a
             Shorewall-based Firewall</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>
@@ -340,8 +340,8 @@
 
             <entry><ulink url="ping.html">'Ping' Management</ulink></entry>
 
-            <entry><ulink url="Xen.html">Xen - Shorewall in Bridged Xen
+            <entry><ulink url="XenMyWay.html">Xen - Shorewall in a Bridged Xen
-            Dom0</ulink></entry>
+            DomU</ulink></entry>
           </row>
 
           <row>
@@ -350,8 +350,8 @@
 
             <entry><ulink url="ports.htm">Port Information</ulink></entry>
 
-            <entry><ulink url="XenMyWay-Routed.html">Xen - Shorewall in Routed
+            <entry><ulink url="Xen.html">Xen - Shorewall in Bridged Xen
-            Xen Dom0</ulink></entry>
+            Dom0</ulink></entry>
           </row>
 
           <row>
@@ -361,7 +361,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>

docs/Macros.xml

@@ -245,6 +245,29 @@ ACCEPT           fw       loc             tcp      135,139,445</programlisting>
     from actions cannot themselves invoke other actions.</para>
   </section>
 
+  <section id="Default">
+    <title>Default Macros</title>
+
+    <para>Beginning with Shorewall release 3.4, Shorewall supports
+    <firstterm>default macros</firstterm>; default macros perform the same
+    function as <ulink url="???">default actions</ulink>. The DEFAULT_ACCEPT,
+    DEFAULT_REJECT, DEFAULT_DROP and DEFAULT_QUEUE options in
+    <filename>/etc/shorewall/shorewall.conf</filename> may specify the name of
+    a macro. In that case, the rules in the macro will be traversed before the
+    associated policy is applied.</para>
+
+    <para>The value of the DEFAULT_... settings is interpreted as follows. If
+    USE_ACTIONS=Yes in shorewall.conf, then the value is treated like the name
+    of an action -- if that action is not found, then the value is treated
+    like the name of a macro. If USE_ACTIONS=No, then the value is treated
+    like the name of a macro. The special value "none" is always interpreted
+    as "no default rules should be applied".</para>
+
+    <para>Shorewall versions 3.4 and later include standard 'Reject' and
+    'Drop' macros that are equivalent to the 'Reject' and 'Drop'
+    actions.</para>
+  </section>
+
   <section>
     <title>Defining your own Macros</title>
 

docs/Modularization.xml

@@ -0,0 +1,235 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article>
+  <!--$Id$-->
+
+  <articleinfo>
+    <title>Shorewall Modularization</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Tom</firstname>
+
+        <surname>Eastep</surname>
+      </author>
+    </authorgroup>
+
+    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
+
+    <copyright>
+      <year>2006</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>One of the major changes in Shorewall version 3.4 involved breaking
+    much of the code into <firstterm>libraries</firstterm>. This
+    modularization is expected to be used primarily by embedded distributions
+    that wish to minimize the Shorewall disk and RAM footprint.</para>
+
+    <para>Shorewall libraries are Bourne shell source files that contain
+    nothing but function declarations. Shorewall libraries may be loaded into
+    a running shell program using the shell's "." operator. The library files
+    have names which begin with "lib." and are installed in <filename
+    class="directory">/usr/share/shorewall/</filename>. </para>
+
+    <para> Individual libraries are of one of two classes. The first class of
+    libraries are <firstterm>required libraries</firstterm> which, as their
+    name implies, must be included in any Shorewall installation. The other
+    libraries are <firstterm>optional libraries</firstterm> that implement a
+    particular function. Each optional library may be included or omitted
+    based on the requirements of the individual installation.</para>
+  </section>
+
+  <section>
+    <title>Required Libraries</title>
+
+    <para>Shorewall 3.4 includes the following required libraries.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>lib.base — includes functions needed by all Shorewall
+        programs.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.cli — includes functions common to both
+        <filename>/sbin/shorewall</filename> and
+        <filename>/sbin/shorewall-lite</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.config — contains functions common to both
+        <filename>/sbin/shorewall</filename> and
+        <filename>/usr/share/shorewall/firewall</filename>.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>lib.base and lib.cli are installed in /usr/share/shorewall-lite/ on
+    Shorewall Lite systems.</para>
+  </section>
+
+  <section>
+    <title>Optional Libraries</title>
+
+    <para>Optional libraries are loaded upon demand based on the user's
+    configuration.</para>
+
+    <para>In Shorewall 3.4, the optional librares are as follows.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>lib.accounting — required if the
+        <filename>/etc/shorewall/accounting</filename> file is
+        non-empty.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.actions — required if USE_ACTIONS=Yes in
+        <filename>/etc/shorewall/shorewall.conf</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.dynamiczones — required if DYNAMIC_ZONES=Yes in
+        <filename>/etc/shorewall/shorewall.conf</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.maclist — required if the maclist option is specified in any
+        entry in <filename>/etc/shorewall/interfaces</filename> or
+        <filename>/etc/shorewall/hosts</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.nat — required if the
+        <filename>/etc/shorewall/masq</filename>,
+        <filename>/etc/shorewall/nat</filename> or
+        <filename>/etc/shorewall/netmap</filename> files are non-empty or if
+        DNAT[-] rules are present in
+        <filename>/etc/shorewall/rules</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.providers — required if the
+        <filename>/etc/shorewall/providers</filename> file is
+        non-empty.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.proxyarp — required if the
+        <filename>/etc/shorewall/proxyarp</filename> file is non-empty or if
+        the <emphasis role="bold">proxyarp</emphasis> option is specified in
+        an entry in <filename>/etc/shorewall/interfaces</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.tc — required if the
+        <filename>/etc/shorewall/tcdevices</filename> or
+        <filename>/etc/shorewall/tcclasses</filename> file is
+        non-empty.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.tcrules — required if the
+        <filename>/etc/shorewall/tcrules</filename> file is non-empty.</para>
+      </listitem>
+
+      <listitem>
+        <para>lib.tunnels — required if the
+        <firstterm>/etc/shorewall/tunnels</firstterm> file is
+        non-empty.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>As described, many of the libraries are required when one or more
+    configuration files are non-empty and embedded distribution providers are
+    encouraged to package each optional library together with its associated
+    configuration files.</para>
+
+    <informaltable>
+      <tgroup cols="2">
+        <colspec align="left" />
+
+        <tbody>
+          <row>
+            <entry><emphasis role="bold">Library</emphasis></entry>
+
+            <entry><emphasis role="bold">Files</emphasis></entry>
+          </row>
+
+          <row>
+            <entry>lib.accounting</entry>
+
+            <entry><filename>/etc/shorewall/accounting</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.actions</entry>
+
+            <entry><filename>/etc/shorewall/actions</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.maclist</entry>
+
+            <entry><filename>/etc/shorewall/maclist</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.nat</entry>
+
+            <entry><filename>/etc/shorewall/masq, /etc/shorewall/nat,
+            /etc/shorewall/netmap</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.providers</entry>
+
+            <entry><filename>/etc/shorewall/route_rules,
+            /etc/shorewall/providers</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.proxyarp</entry>
+
+            <entry><filename>/etc/shorewall/proxyarp</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.tc</entry>
+
+            <entry><filename>/etc/shorewall/tcclasses,
+            /etc/shorewall/tcdevices</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.tcrules</entry>
+
+            <entry><filename>/etc/shorewall/tcrules</filename></entry>
+          </row>
+
+          <row>
+            <entry>lib.tunnels</entry>
+
+            <entry><filename>/etc/shorewall/tunnels</filename></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </section>
+</article>