Prep work for edits on IPF rulesets.

Move paragraphs that apply to all firewalls to Firewall Concepts section.
That section will be reviewed last, to make sure it includes the concepts covered in all the firewalls.
Move how to load ruleset to previous section to match layout of PF firewall section.
Next up, review ruleset syntax.

Sponsored by: iXsystems

1 files changed, 43 insertions, 61 deletions

diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
index 4ba5890322..c2096b6597 100644
--- a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
@@ -156,6 +156,20 @@
       <secondary>rulesets</secondary>
     </indexterm>
 
+    <para>A ruleset contains a group of rules which pass or
+	block packets based on the values contained in the packet.
+	The bi-directional exchange of packets between hosts comprises
+	a session conversation.  The firewall ruleset processes both
+	the packets arriving from the public Internet, as well as the
+	packets produced by the system as a response to them.  Each
+	<acronym>TCP/IP</acronym> service is predefined by its
+	protocol and listening port.  Packets destined for a specific
+	service originate from the source address using an
+	unprivileged port and target the specific service port on the
+	destination address.  All the above parameters can be used as
+	selection criteria to create rules which will pass or block
+	services.</para>
+
     <para>A firewall ruleset can be either
       <quote>exclusive</quote> or <quote>inclusive</quote>.  An
       exclusive firewall allows all traffic through except for the
@@ -187,6 +201,15 @@
       to Denial of Service (<acronym>DoS</acronym>) attacks if a lot
       of new connections are opened very fast.  Most firewalls use a
       combination of stateful and non-stateful behavior.</para>
+
+      <warning>
+	<para>When working with the firewall rules, be <emphasis>very
+	    careful</emphasis>.  Some configurations <emphasis>can
+	  lock the administrator out</emphasis> of the server.  To be
+	  on the safe side, consider performing the initial firewall
+	  configuration from the local console rather than doing it
+	  remotely over <application>ssh</application>.</para>
+      </warning>
   </sect1>
 
   <sect1 xml:id="firewalls-pf">
@@ -1635,55 +1658,20 @@ ipnat_rules="/etc/ipnat.rules"    # rules definition file for ipnat</programlist
       <para>Then, to start <application>IPF</application> now:</para>
 
       <programlisting>&prompt.root; <userinput>service ipfilter start</userinput></programlisting>
-    </sect2>
-
-    <sect2>
-      <title>IPF Rulesets</title>
-
-      <para>A ruleset contains a group of IPF rules which pass or
-	block packets based on the values contained in the packet.
-	The bi-directional exchange of packets between hosts comprises
-	a session conversation.  The firewall ruleset processes both
-	the packets arriving from the public Internet, as well as the
-	packets produced by the system as a response to them.  Each
-	<acronym>TCP/IP</acronym> service is predefined by its
-	protocol and listening port.  Packets destined for a specific
-	service originate from the source address using an
-	unprivileged port and target the specific service port on the
-	destination address.  All the above parameters can be used as
-	selection criteria to create rules which will pass or block
-	services.</para>
-
-      <indexterm>
-	<primary><application>IPFILTER</application></primary>
-
-	<secondary>rule processing order</secondary>
-      </indexterm>
 
-      <warning>
-	<para>When working with the firewall rules, be <emphasis>very
-	    careful</emphasis>.  Some configurations <emphasis>can
-	  lock the administrator out</emphasis> of the server.  To be
-	  on the safe side, consider performing the initial firewall
-	  configuration from the local console rather than doing it
-	  remotely over <application>ssh</application>.</para>
-      </warning>
-
-      <para>To load the ruleset file, use &man.ipf.8;.  Custom rules
-	are normally placed in a file, and the following command can
+      <para>To load the ruleset file, specify the name of the file using <command>ipf</command>.
+	The following command can
 	be used to replace the currently running firewall
 	rules:</para>
 
       <screen>&prompt.root; <userinput>ipf -Fa -f /etc/ipf.rules</userinput></screen>
 
-      <para><option>-Fa</option> flushes all the internal rules
-	tables.</para>
-
-      <para><option>-f</option> specifies the file containing the
+      <para>where <option>-Fa</option> flushes all the internal rules
+	tables and <option>-f</option> specifies the file containing the
 	rules to load.</para>
 
       <para>This provides the ability to make changes to a custom
-	rules file, run the above IPF command, and thus update the
+	ruleset and update the
 	running firewall with a fresh copy of the rules without having
 	to reboot the system.  This method is convenient for testing
 	new rules as the procedure can be executed as many times as
@@ -1691,14 +1679,10 @@ ipnat_rules="/etc/ipnat.rules"    # rules definition file for ipnat</programlist
 
       <para>Refer to &man.ipf.8; for details on the other flags
 	available with this command.</para>
+    </sect2>
 
-      <para>&man.ipf.8; expects the rules file to be a standard text
-	file.  It will not accept a rules file written as a script
-	with symbolic substitution.</para>
-
-      <para>There is a way to build IPF rules that utilize the power
-	of script symbolic substitution.  For more information, see
-	<xref linkend="firewalls-ipf-rules-script"/>.</para>
+    <sect2>
+      <title>IPF Rulesets</title>
 
       <indexterm>
 	<primary><application>IPFILTER</application></primary>
@@ -1706,21 +1690,19 @@ ipnat_rules="/etc/ipnat.rules"    # rules definition file for ipnat</programlist
 	<secondary>rule syntax</secondary>
       </indexterm>
 
-      <para>The rule syntax presented here has been simplified to
-	only address the modern stateful rule context and <quote>first
-	matching rule wins</quote> logic.  For the complete legacy
-	rule syntax, refer to &man.ipf.8;.</para>
+      <para>This section describes the <application>IPF</application> rule syntax
+	used to create stateful rules where the <quote>first
+	matching rule wins</quote>.  Refer to &man.ipf.8; for more details, including the legacy
+	rule syntax.</para>
 
-      <para>A <literal>#</literal> character is used to mark the
-	start of a comment and may appear at the end of a rule line
-	or on its own line.  Blank lines are ignored.</para>
+      <para>When creating rules, a <literal>#</literal> character is used to mark the
+	start of a comment and may appear at the end of a rule, to explain its function,
+	or on its own line.  Any blank lines are ignored.</para>
 
-      <para>Rules contain keywords which must be written in a specific
-	order from left to right on the line.  Keywords are identified
-	in bold type.  Some keywords have sub-options which may be
-	keywords themselves and also include more sub-options.  Each
-	of the headings in the below syntax has a bold section header
-	which expands on the content.</para>
+      <para>The keywords which are used in rules must be written in a specific
+	order, from left to right.  Some keywords have sub-options which may be
+	keywords themselves and also include more sub-options.  The
+	keyword order is as follows:</para>
 
       <!-- This section is probably wrong. See the OpenBSD flag -->
       <!-- What is the "OpenBSD flag"?  Reference please -->
@@ -1729,7 +1711,7 @@ ipnat_rules="/etc/ipnat.rules"    # rules definition file for ipnat</programlist
 	  PROTO SRC_ADDR,DST_ADDR OBJECT PORT_NUM TCP_FLAG
 	  STATEFUL</replaceable></para>
 
-      <para>Each keyword and its options are described below.</para>
+      <para>This section describes each keyword and its options.</para>
 
       <variablelist>
 	<varlistentry>