Finish initial editorial review of IPF chapter.

Sponsored by: iXsystems

1 files changed, 57 insertions, 90 deletions

diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
index 67789ca919..595edbb229 100644
--- a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
@@ -2508,7 +2508,7 @@ sh /etc/ipf.rules.script</programlisting>
     </sect2>
     -->
     <sect2>
-      <title>IPFSTAT</title>
+      <title>Viewing <application>IPF</application> Statistics</title>
 
       <indexterm><primary><command>ipfstat</command></primary></indexterm>
 
@@ -2518,16 +2518,16 @@ sh /etc/ipf.rules.script</programlisting>
 	<secondary>statistics</secondary>
       </indexterm>
 
-      <para>The default behavior of &man.ipfstat.8; is to retrieve
-	and display the totals of the accumulated statistics gathered
-	by applying the rules against packets going in and out of the
-	firewall since it was last started, or since the last time the
-	accumulators were reset to zero using <command>ipf
+      <para><application>IPF</application> includes &man.ipfstat.8;
+	which can be used to retrieve
+	and display statistics which are gathered
+	as packets match rules as they go through the
+	firewall.  Statistics are accumulated since the firewall was
+	last started or since the last time they
+	were reset to zero using <command>ipf
 	  -Z</command>.</para>
 
-      <para>Refer to &man.ipfstat.8; for details.</para>
-
-      <para>The default &man.ipfstat.8; output will look something
+      <para>The default <command>ipfstat</command> output looks
 	like this:</para>
 
       <screen>input packets: blocked 99286 passed 1255609 nomatch 14686 counted 0
@@ -2540,58 +2540,47 @@ sh /etc/ipf.rules.script</programlisting>
  fragment state(out): kept 0 lost 0
  packet state(in): kept 169364 lost 0
  packet state(out): kept 431395 lost 0
- ICMP replies: 0 <acronym>TCP</acronym> RSTs sent: 0
+ ICMP replies: 0 TCP RSTs sent: 0
  Result cache hits(in): 1215208 (out): 1098963
  IN Pullups succeeded: 2 failed: 0
  OUT Pullups succeeded: 0 failed: 0
  Fastroute successes: 0 failures: 0
- <acronym>TCP</acronym> cksum fails(in): 0 (out): 0
+ TCP cksum fails(in): 0 (out): 0
  Packet log flags set: (0)</screen>
 
-      <para>When supplied with either <option>-i</option> for inbound
+      <para>Several options are available.  When supplied with either <option>-i</option> for inbound
 	or <option>-o</option> for outbound, the command will retrieve
 	and display the appropriate list of filter rules currently
-	installed and in use by the kernel.</para>
-
-      <para><command>ipfstat -in</command> displays the inbound
-	internal rules table with rule numbers.</para>
-
-      <para><command>ipfstat -on</command> displays the outbound
-	internal rules table with rule numbers.</para>
-
-      <para>The output will look something like this:</para>
+	installed and in use by the kernel.  To also see the rule
+	numbers, include <option>-n</option>.  For example,
+	<command>ipfstat -on</command> displays the outbound
+	rules table with rule numbers:</para>
 
       <screen>@1 pass out on xl0 from any to any
 @2 block out on dc0 from any to any
 @3 pass out quick on dc0 proto tcp/udp from any to any keep state</screen>
 
-      <para><command>ipfstat -ih</command> displays the inbound
-	internal rules table, prefixing each rule with a count of how
-	many times the rule was matched.</para>
-
-      <para><command>ipfstat -oh</command> displays the outbound
-	internal rules table, prefixing each rule with a count of how
-	many times the rule was matched.</para>
-
-      <para>The output will look something like this:</para>
+      <para>Include <option>-h</option> to
+	prefix each rule with a count of how
+	many times the rule was matched. For example,
+	<command>ipfstat -oh</command> displays the outbound
+	internal rules table, prefixing each rule with its usage count:</para>
 
       <screen>2451423 pass out on xl0 from any to any
 354727 block out on dc0 from any to any
 430918 pass out quick on dc0 proto tcp/udp from any to any keep state</screen>
 
-      <para>One of the most important options of
-	<command>ipfstat</command> is <option>-t</option> which
-	displays the state table in a way similar to how &man.top.1;
-	shows the &os; running process table.  When a firewall is
-	under attack, this function provides the ability to identify
+      <para>To display the state table in a format similar to &man.top.1;, use
+	<command>ipfstat -t</command>.  When the firewall is
+	under attack, this option provides the ability to identify
 	and see the attacking packets.  The optional sub-flags give
-	the ability to select the destination or source IP, port, or
+	the ability to select the destination or source <acronym>IP</acronym>, port, or
 	protocol to be monitored in real time.  Refer to
 	&man.ipfstat.8; for details.</para>
     </sect2>
 
     <sect2>
-      <title>IPMON</title>
+      <title><application>IPF</application> Logging</title>
 
       <indexterm><primary><command>ipmon</command></primary></indexterm>
 
@@ -2601,17 +2590,16 @@ sh /etc/ipf.rules.script</programlisting>
 	<secondary>logging</secondary>
       </indexterm>
 
-      <para>In order for <command>ipmon</command> to work properly,
-	the kernel option <literal>IPFILTER_LOG</literal> must be
-	turned on.  This command has two different modes.  Native mode
-	is the default mode when the command is used without
-	<option>-D</option>.</para>
-
-      <para>Daemon mode provides a continuous system log file so that
-	logging of past events may be reviewed.  &os; has a built in
-	facility to automatically rotate system logs.  This is why
-	outputting the log information to &man.syslogd.8; is better
-	than the default of outputting to a regular file.  The default
+      <para><application>IPF</application> provides
+	<command>ipmon</command>, which can be used to write the firewall's logging
+	information in a human readable format.  It requires that
+	<literal>options IPFILTER_LOG</literal> be first added
+	to a custom kernel using the instructions in <xref linkend="kernelconfig"/>.</para>
+
+      <para>This command is typically run in
+	daemon mode in order to provide a continuous system log file so that
+	logging of past events may be reviewed.  Since &os; has a built in
+	&man.syslogd.8; facility to automatically rotate system logs, the default
 	<filename>rc.conf</filename>
 	<literal>ipmon_flags</literal> statement uses
 	<option>-Ds</option>:</para>
@@ -2623,48 +2611,38 @@ sh /etc/ipf.rules.script</programlisting>
 
       <para>Logging provides the ability to review, after the fact,
 	information such as which packets were dropped, what addresses
-	they came from and where they were going.  These can all
-	provide a significant edge in tracking down attackers.</para>
+	they came from, and where they were going.  This information
+	is useful in tracking down attackers.</para>
 
-      <para>Even with the logging facility enabled, IPF will not
-	generate any rule logging by default.  The firewall
+      <para>Once the logging facility is enabled in
+	<filename>rc.conf</filename> and started with <command>service
+	  ipmon start</command>, <application>IPF</application> will only
+	log the rules which contain the <literal>log</literal> keyword.  The firewall
 	administrator decides which rules in the ruleset should be
-	logged and adds the log keyword to those rules.  Normally,
-	only deny rules are logged.</para>
-
-      <para>It is customary to include a <quote>default deny
-	  everything</quote> rule with the log keyword included as the
+	logged and normally
+	only deny rules are logged.  It is customary to include the
+	<literal>log</literal> keyword in the
 	last rule in the ruleset.  This makes it possible to see all
 	the packets that did not match any of the rules in the
 	ruleset.</para>
 
-      <para>&man.syslogd.8; uses its own method for segregation of log
-	data.  It uses groupings called <quote>facility</quote> and
-	<quote>level</quote>.  By default, IPMON in
-	<option>-Ds</option> mode uses <literal>local0</literal> as
-	the <quote>facility</quote> name.  The following levels can be
+      <para>By default, <command>ipmon -Ds</command> mode uses
+	<literal>local0</literal> as
+	the logging facility.  The following logging levels can be
 	used to further segregate the logged data:</para>
 
       <screen>LOG_INFO - packets logged using the "log" keyword as the action rather than pass or block.
 LOG_NOTICE - packets logged which are also passed
 LOG_WARNING - packets logged which are also blocked
-LOG_ERR - packets which have been logged and which can be considered short</screen>
-
-      <!-- XXX: "can be considered short" == "with incomplete header" -->
+LOG_ERR - packets which have been logged and which can be considered short due to an incomplete header</screen>
 
-      <para>In order to setup <application>IPFILTER</application> to
+      <para>In order to setup <application>IPF</application> to
 	log all data to <filename>/var/log/ipfilter.log</filename>,
 	first create the empty file:</para>
 
        <screen>&prompt.root; <userinput>touch /var/log/ipfilter.log</userinput></screen>
 
-      <para>&man.syslogd.8; is controlled by definition statements in
-	<filename>/etc/syslog.conf</filename>.  This file offers
-	considerable flexibility in how
-	<application>syslog</application> will deal with system
-	messages issued by software applications like IPF.</para>
-
-      <para>To write all logged messages to the specified file,
+      <para>Then, to write all logged messages to the specified file,
 	add the following statement to
 	<filename>/etc/syslog.conf</filename>:</para>
 
@@ -2674,7 +2652,7 @@ LOG_ERR - packets which have been logged and which can be considered short</scre
 	to read the modified <filename>/etc/syslog.conf</filename>,
 	run <command>service syslogd reload</command>.</para>
 
-      <para>Do not forget to change
+      <para>Do not forget to edit
 	<filename>/etc/newsyslog.conf</filename> to rotate the new
 	log file.</para>
 
@@ -2702,23 +2680,12 @@ LOG_ERR - packets which have been logged and which can be considered short</scre
 	  <para>The group and rule number of the rule in the format
 	    <literal>@0:17</literal>.</para>
 	</listitem>
-      </orderedlist>
-
-      <para>These can be viewed with
-	<command>ipfstat -in</command>.</para>
 
-      <orderedlist>
 	<listitem>
 	  <para>The action: <literal>p</literal> for passed,
 	    <literal>b</literal> for blocked, <literal>S</literal> for
 	    a short packet, <literal>n</literal> did not match any
-	    rules, and <literal>L</literal> for a log rule.  The order
-	    of precedence in showing flags is: <literal>S</literal>,
-	    <literal>p</literal>, <literal>b</literal>,
-	    <literal>n</literal>, <literal>L</literal>.  A capital
-	    <literal>P</literal> or <literal>B</literal> means that
-	    the packet has been logged due to a global logging
-	    setting, not a particular rule.</para>
+	    rules, and <literal>L</literal> for a log rule.</para>
 	</listitem>
 
 	<listitem>
@@ -2746,10 +2713,10 @@ LOG_ERR - packets which have been logged and which can be considered short</scre
 	letters corresponding to any flags that were set.  Refer to
 	&man.ipf.5; for a list of letters and their flags.</para>
 
-      <para>If the packet is an ICMP packet, there will be two fields
-	at the end:  the first always being <quote>ICMP</quote> and
-	the next being the ICMP message and sub-message type,
-	separated by a slash.  For example:  ICMP 3/3 for a port
+      <para>If the packet is an <acronym>ICMP</acronym> packet, there will be two fields
+	at the end:  the first always being <quote>icmp</quote> and
+	the next being the <acronym>ICMP</acronym> message and sub-message type,
+	separated by a slash.  For example:  <literal>icmp 3/3</literal> for a port
 	unreachable message.</para>
     </sect2>
   </sect1>