Document policy action changes

Signed-off-by: Tom Eastep <teastep@shorewall.net>

Shorewall/manpages/shorewall-policy.xml

@@ -153,7 +153,8 @@
 
           <para>Beginning with Shorewall 5.1.2, multiple
           <replaceable>action</replaceable>[:<replaceable>level</replaceable>]
-          pairs may be specified, separated by commas.</para>
+          specification may be listeded, separated by commas. The actions are
+          invoked in the order listed.</para>
 
           <para>Possible actions are:</para>
 

Shorewall/manpages/shorewall.conf.xml

@@ -109,7 +109,7 @@
     <variablelist>
       <varlistentry>
         <term><emphasis
-        role="bold">ACCEPT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">ACCEPT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -119,7 +119,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">BLACKLIST_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">BLACKLIST_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -129,7 +129,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">DROP_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">DROP_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -139,7 +139,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">NFQUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">NFQUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -149,7 +149,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">QUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">QUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -159,13 +159,13 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">REJECT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">REJECT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
-          <para>In earlier Shorewall versions, a "default action" for DROP and
+          <para>In earlier Shorewall versions, a "<firstterm>default
-          REJECT policies was specified in the file
+          action</firstterm>" for DROP and REJECT policies was specified in
-          /usr/share/shorewall/actions.std.</para>
+          the file /usr/share/shorewall/actions.std.</para>
 
           <para>In Shorewall 4.4.0, the DROP_DEFAULT, REJECT_DEFAULT,
           ACCEPT_DEFAULT, QUEUE_DEFAULT and NFQUEUE_DEFAULT options were
@@ -189,7 +189,7 @@
             role="bold">none</emphasis></member>
           </simplelist>
 
-          <para>The default values are:</para>
+          <para>Prior to Shorewall 5.1.2, the default values are:</para>
 
           <simplelist>
             <member>DROP_DEFAULT="Drop"</member>
@@ -203,9 +203,14 @@
 
             <member>QUEUE_DEFAULT="none"</member>
 
-            <member>NFQUEUE_DEFAULT="None"</member>
+            <member>NFQUEUE_DEFAULT="none"</member>
           </simplelist>
 
+          <para>Beginning with Shorewall 5.1.2, the default value is 'none'
+          for all of these. Note that the sample configuration files do,
+          however, provide settings for DROP_DEFAULT, BLACKLIST_DEFAULT and
+          REJECT_DEFAULT.</para>
+
           <para>If you set the value of either option to "None" then no
           default action will be used and the default action or macro must be
           specified in <ulink
@@ -220,6 +225,10 @@
           <replaceable>level</replaceable>. The level will be applied to each
           rule in the action or body that does not already have a log
           level.</para>
+
+          <para>Beginning with Shorewall 5.1.2, multiple
+          <replaceable>action</replaceable>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]
+          specifications may be listed, separated by commas.</para>
         </listitem>
       </varlistentry>
 

Shorewall6/manpages/shorewall6-policy.xml

@@ -151,7 +151,8 @@
 
           <para>Beginning with Shorewall 5.1.2, multiple
           <replaceable>action</replaceable>[:<replaceable>level</replaceable>]
-          pairs may be specified, separated by commas.</para>
+          pairs may be specified, separated by commas. The actions are invoked
+          in the order listed.</para>
 
           <para>Possible actions are:</para>
 

Shorewall6/manpages/shorewall6.conf.xml

@@ -95,7 +95,7 @@
     <variablelist>
       <varlistentry>
         <term><emphasis
-        role="bold">ACCEPT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">ACCEPT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -105,7 +105,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">BLACKLIST_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">BLACKLIST_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -115,7 +115,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">DROP_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">DROP_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -125,7 +125,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">NFQUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">NFQUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -135,7 +135,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">QUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">QUEUE_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -145,7 +145,7 @@
 
       <varlistentry>
         <term><emphasis
-        role="bold">REJECT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]|<emphasis
+        role="bold">REJECT_DEFAULT=</emphasis>{<emphasis>action</emphasis>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>][,...]|<emphasis
         role="bold">none</emphasis>}</term>
 
         <listitem>
@@ -167,7 +167,7 @@
             role="bold">none</emphasis></member>
           </simplelist>
 
-          <para>The default values are:</para>
+          <para>Prior to Shorewall 5.1.2, the default values are:</para>
 
           <simplelist>
             <member>DROP_DEFAULT="Drop"</member>
@@ -181,9 +181,14 @@
 
             <member>QUEUE_DEFAULT="none"</member>
 
-            <member>NFQUEUE_DEFAULT="None"</member>
+            <member>NFQUEUE_DEFAULT="none"</member>
           </simplelist>
 
+          <para>Beginning with Shorewall 5.1.2, the default value is 'none'
+          for all of these. Note that the sample configuration files do,
+          however, provide settings for DROP_DEFAULT, BLACKLIST_DEFAULT and
+          REJECT_DEFAULT.</para>
+
           <para>If you set the value of either option to "None" then no
           default action will be used and the default action or macro must be
           specified in <ulink
@@ -198,6 +203,10 @@
           <replaceable>level</replaceable>. The level will be applied to each
           rule in the action or macro body that does not already have a log
           level.</para>
+
+          <para>Beginning with Shorewall 5.1.2, multiple
+          <replaceable>action</replaceable>[(<replaceable>parameters</replaceable>)][:<replaceable>level</replaceable>]
+          specifications may be listed, separated by commas.</para>
         </listitem>
       </varlistentry>
 

docs/Actions.xml

@@ -132,13 +132,13 @@ ACCEPT   -              -               tcp     135,139,445</programlisting>
   </section>
 
   <section id="Default">
-    <title>Default Actions (Formerly Common Actions)</title>
+    <title>Policy Actions (Formerly Default Actions)</title>
 
-    <para>Shorewall allows the association of a <firstterm>default
+    <para>Shorewall allows the association of a <firstterm>policy
-    action</firstterm> with policies. A separate default action may be
+    action</firstterm> with policies. A separate policy action may be
-    associated with ACCEPT, DROP, REJECT, QUEUE and NFQUEUE policies. Default
+    associated with ACCEPT, DROP, REJECT, QUEUE and NFQUEUE policies. Policy
     actions provide a way to invoke a set of common rules just before the
-    policy is enforced. Default actions accomplish two goals:</para>
+    policy is enforced. Policy actions accomplish two goals:</para>
 
     <orderedlist>
       <listitem>
@@ -152,7 +152,7 @@ ACCEPT   -              -               tcp     135,139,445</programlisting>
       </listitem>
     </orderedlist>
 
-    <para>Shorewall supports default actions for the ACCEPT, REJECT, DROP,
+    <para>Shorewall supports policy actions for the ACCEPT, REJECT, DROP,
     QUEUE and NFQUEUE policies. These default actions are specified in the
     <filename>/etc/shorewall/shorewall.conf</filename> file using the
     ACCEPT_DEFAULT, REJECT_DEFAULT, DROP_DEFAULT, QUEUE_DEFAULT and
@@ -165,14 +165,15 @@ ACCEPT   -              -               tcp     135,139,445</programlisting>
     url="manpages/shorewall-policy.html">/etc/shorewall/policy</ulink></filename>.</para>
 
     <important>
-      <para>Entries in the DROP and REJECT default actions <emphasis
+      <para>Entries in the DROP, REJECT and BLACKLIST policy actions <emphasis
       role="bold">ARE NOT THE CAUSE OF CONNECTION PROBLEMS</emphasis>.
-      Remember — default actions are only invoked immediately before the
+      Remember — policy actions are only invoked immediately before the packet
-      packet is going to be dropped or rejected anyway!!!</para>
+      is going to be dropped or rejected anyway!!!</para>
     </important>
 
-    <para>Beginning with Shorewall 4.4.21, the standard Drop and Reject
+    <para>Prior to Shorewall 5.1.2, the Drop and Reject actions were the
-    options are parameterized. Each has five parameters as follows:</para>
+    default policy actions for DROP and REJECT policies respectively. Those
+    actions are parameterized; each has five parameters as follows:</para>
 
     <informaltable>
       <tgroup cols="4">
@@ -283,6 +284,61 @@ ACCEPT   -              -               tcp     135,139,445</programlisting>
     POLICY column of <ulink
     url="manpages/shorewall-policy.html">shorewall-policy</ulink>(5) (e.g.,
     DROP:<emphasis role="bold">Drop(audit)</emphasis>:audit).</para>
+
+    <para>Beginning with Shorewall 5.1.2, Drop and Reject are deprecated. In
+    5.1.2, a list of policy actions is accepted in both shorewall.conf and the
+    policy file. This allows logging to be specified on some actions and not
+    on others and eliminates the need for a large number of policy-action
+    parameters.</para>
+
+    <para>Actions commonly included in policy-action lists are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>Broadcasts[(<replaceable>disposition</replaceable>)]</term>
+
+        <listitem>
+          <para>Handles broadcasts and multicasts based on the
+          <replaceable>disposition</replaceable>. The default
+          <replaceable>disposition</replaceable> is DROP.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>dropNotSyn[:<replaceable>level</replaceable>]</term>
+
+        <listitem>
+          <para>Drops TCP packets that are not part of an existing connection
+          but that don't have the SYN flag set or that have additional flags
+          set. We recommend that these be logged by specifying an approproate
+          <replaceable>level</replaceable>. This action is particularly
+          appropriate packets received from the Internet. Recommended when the
+          policy is BLACKLIST to avoid late-arriving FIN packets from
+          blacklisting the remote system.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>DropDNSrep[:<replaceable>level</replaceable>]</term>
+
+        <listitem>
+          <para>Drops UDP packets with source port 53. We recommend that these
+          be logged by specifying an approproate
+          <replaceable>level</replaceable>. This action is recommended when
+          the policy is BLACKLIST to avoid blacklisting uplevel DNS
+          servers.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>AllowICMPs (IPv6 only)</term>
+
+        <listitem>
+          <para>Allows ICMP packets mandated by RFC 4890. In particular, this
+          ensures that Neighbor Discovery won't be broken </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
   </section>
 
   <section id="Defining">