First round of 3.0 documentation changes

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

Shorewall-docs2/Accounting.xml

@@ -15,10 +15,10 @@
       </author>
     </authorgroup>
 
-    <pubdate>2004-04-19</pubdate>
+    <pubdate>2005-08-28</pubdate>
 
     <copyright>
-      <year>2003-2004</year>
+      <year>2003-2005</year>
 
       <holder>Thomas M. Eastep</holder>
     </copyright>
@@ -34,9 +34,6 @@
     </legalnotice>
   </articleinfo>
 
-  <para>Shorewall Traffic Accounting support was added in Shorewall release
-  1.4.7.</para>
-
   <para>Shorewall accounting rules are described in the file
   /etc/shorewall/accounting. By default, the accounting rules are placed in a
   chain called <quote>accounting</quote> and can thus be displayed using
@@ -122,9 +119,8 @@
     </listitem>
 
     <listitem>
-      <para><emphasis role="bold">USER/GROUP</emphasis> (Added in Shorewall
+      <para><emphasis role="bold">USER/GROUP</emphasis> - This column may only
-      2.2.0) - This column may only be non-empty if the CHAIN is OUTPUT. The
+      be non-empty if the CHAIN is OUTPUT. The column may contain:</para>
-      column may contain:</para>
 
       <programlisting> [!][&lt;user name or number&gt;][:&lt;group name or number&gt;]</programlisting>
 

Shorewall-docs2/Actions.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2005-05-13</pubdate>
+    <pubdate>2005-08-28</pubdate>
 
     <copyright>
       <year>2005</year>
@@ -34,6 +34,12 @@
     </legalnotice>
   </articleinfo>
 
+  <caution>
+    <para>This article applies to Shorewall 3.0 and later. If you are running
+    a version of Shorewall earlier than Shorewall 3.0.0 then please see the
+    documentation for that release.</para>
+  </caution>
+
   <section>
     <title>What are Shorewall Actions?</title>
 
@@ -167,16 +173,16 @@ Reject:REJECT   #Common Action for REJECT policy</programlisting>
         action begins with a capital letter; that way, the name won't conflict
         with a Shorewall-defined chain name.</para>
 
-        <para>Beginning with Shorewall-2.0.0-Beta1, the name of the action may
+        <para>The name of the action may be optionally followed by a colon
-        be optionally followed by a colon (<quote>:</quote>) and ACCEPT, DROP
+        (<quote>:</quote>) and ACCEPT, DROP or REJECT. When this is done, the
-        or REJECT. When this is done, the named action will become the
+        named action will become the <emphasis>common action </emphasis>for
-        <emphasis>common action </emphasis>for policies of type ACCEPT, DROP
+        policies of type ACCEPT, DROP or REJECT respectively. The common
-        or REJECT respectively. The common action is applied immediately
+        action is applied immediately before the policy is enforced (before
-        before the policy is enforced (before any logging is done under that
+        any logging is done under that policy) and is used mainly to suppress
-        policy) and is used mainly to suppress logging of uninteresting
+        logging of uninteresting traffic which would otherwise clog your logs.
-        traffic which would otherwise clog your logs. The same policy name can
+        The same policy name can appear in multiple actions; the last such
-        appear in multiple actions; the last such action for each policy name
+        action for each policy name is the one which Shorewall will
-        is the one which Shorewall will use.</para>
+        use.</para>
 
         <para>Shorewall includes pre-defined actions for DROP and REJECT --
         see above.</para>
@@ -369,12 +375,9 @@ LogAndAccept loc         fw          tcp      22</programlisting>
   <section>
     <title>Actions and Logging</title>
 
-    <para>Prior to Shorewall 2.1.2, specifying a log level (and optionally a
+    <para>Specifying a log level in a rule that specifies a user- or
-    log tag) on a rule that specified a user-defined (or Shorewall-defined)
+    Shorewall-defined action will cause each rule in the action to be logged
-    action would log all traffic passed to the action. Beginning with
+    with the specified level (and tag).</para>
-    Shorewall 2.1.2, specifying a log level in a rule that specifies a user-
-    or Shorewall-defined action will cause each rule in the action to be
-    logged with the specified level (and tag).</para>
 
     <para>The extent to which logging of action rules occur is governed by the
     following:</para>

Shorewall-docs2/blacklisting_support.xml

@@ -15,10 +15,10 @@
       </author>
     </authorgroup>
 
-    <pubdate>2004-10-25</pubdate>
+    <pubdate>2005-08-28</pubdate>
 
     <copyright>
-      <year>2002-2004</year>
+      <year>2002-2005</year>
 
       <holder>Thomas M. Eastep</holder>
     </copyright>
@@ -38,16 +38,14 @@
     <title>Introduction</title>
 
     <para>Shorewall supports two different forms of blacklisting; static and
-    dynamic. Beginning with Shorewall version 1.4.8, the BLACKLISTNEWONLY
+    dynamic. The BLACKLISTNEWONLY option in /etc/shorewall/shorewall.conf
-    option in /etc/shorewall/shorewall.conf controls the degree of blacklist
+    controls the degree of blacklist filtering:</para>
-    filtering:</para>
 
     <orderedlist>
       <listitem>
         <para>BLACKLISTNEWONLY=No --&nbsp; All incoming packets are checked
         against the blacklist. New blacklist entries can be used to terminate
-        existing connections. Versions of Shorewall prior to 1.4.8 behave in
+        existing connections.</para>
-        this manner.</para>
       </listitem>
 
       <listitem>
@@ -66,10 +64,12 @@
     </important>
 
     <important>
-      <para><emphasis role="bold">Neither form of Shorewall blacklisting is
+      <para><emphasis role="bold">Dynamic Shorewall blacklisting is not
-      appropriate for blacklisting 1,000s of different addresses</emphasis>.
+      appropriate for blacklisting 1,000s of different addresses. Static
-      The blacklists will take forever to load and will have a very negative
+      Blacklisting can handle large blacklists but only if you use
-      effect on firewall performance.</para>
+      ipsets</emphasis>. Without ipsets, the blacklists will take forever to
+      load and will have a very negative effect on firewall
+      performance.</para>
     </important>
   </section>
 
@@ -97,8 +97,8 @@
         <para>You list the IP addresses/subnets that you wish to blacklist in
         <ulink
         url="Documentation.htm#Blacklist"><filename>/etc/shorewall/blacklist</filename></ulink>.
-        Beginning with Shorewall version 1.3.8, you may also specify PROTOCOL
+        You may also specify PROTOCOL and Port numbers/Service names in the
-        and Port numbers/Service names in the blacklist file.</para>
+        blacklist file.</para>
       </listitem>
 
       <listitem>
@@ -123,14 +123,41 @@
     blacklisted hosts to slip by during construction of the blacklist, it can
     substantially reduce the time that all new connections are disabled during
     "shorewall [re]start".</para>
+
+    <para>Beginning with Shorewall 2.4.0, you can use <ulink
+    url="ipsets.html">ipsets</ulink> to define your static blacklist. Here's
+    an example:</para>
+
+    <programlisting>#ADDRESS/SUBNET         PROTOCOL        PORT
++Blacklistports[dst]
++Blacklistnets[src,dst]
++Blacklist[src,dst]
+#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>
+
+    <para>In this example, there is a portmap ipset
+    <emphasis>Blacklistports</emphasis> that blacklists all traffic with
+    destination ports included in the ipsec. There are also
+    <emphasis>Blacklistnets</emphasis> (type <emphasis>nethash</emphasis>) and
+    <emphasis>Blacklist</emphasis> (type <emphasis>iphash</emphasis>) ipsets
+    that allow blacklisting networks and individual IP addresses. Note that
+    [src,dst] is specified so that individual entries in the sets can be bound
+    to other portmap ipsets to allow blacklisting (<emphasis>source
+    address</emphasis>, <emphasis>destination port</emphasis>) combinations.
+    For example:</para>
+
+    <programlisting>ipset -N SMTP portmap --from 1 --to 31
+ipset -A SMTP 25
+ipset -A Blacklist 206.124.146.177
+ipset -B Blacklist 206.124.146.177 -b SMTP</programlisting>
+
+    <para>This will blacklist SMTP traffic from host 206.124.146.177.</para>
   </section>
 
   <section>
     <title>Dynamic Blacklisting</title>
 
-    <para>Dynamic blacklisting support was added in version 1.3.2. Dynamic
+    <para>Dynamic blacklisting doesn't use any configuration parameters but is
-    blacklisting doesn't use any configuration parameters but is rather
+    rather controlled using /sbin/shorewall commands:</para>
-    controlled using /sbin/shorewall commands:</para>
 
     <itemizedlist>
       <listitem>

Shorewall-docs2/configuration_file_basics.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2005-06-02</pubdate>
+    <pubdate>2005-08-28</pubdate>
 
     <copyright>
       <year>2001-2005</year>
@@ -201,15 +201,6 @@
           <filename>/etc/shorewall</filename> and modify the
           copy</emphasis>.</para>
         </listitem>
-
-        <listitem>
-          <para><filename>/usr/share/bogons</filename> — Defines the behavior
-          of the 'nobogons' interface option in
-          <filename>/etc/shorewall/interfaces</filename>. <emphasis
-          role="bold">If you need to change this file, copy it to
-          <filename>/etc/shorewall</filename> and modify the
-          copy</emphasis>.</para>
-        </listitem>
       </itemizedlist></para>
   </section>