Bug 178959

Summary: Incorrect column descriptions for `ipfw -a list` output in handbook
Product: Documentation Reporter: Kevin Zheng <kevinz5000>
Component: Books & ArticlesAssignee: freebsd-doc (Nobody) <doc>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Kevin Zheng 2013-05-25 00:10:00 UTC
The FreeBSD Handbook incorrectly documents the columns that appear as output to the `ipfw show` command (also `ipfw -a list`).

http://www.freebsd.org/doc/handbook/firewalls-ipfw.html

From the Handbook: ~~~~~~~~~~~~~~~~~~~~
The next example lists accounting information and the packet count for matched rules along with the rules themselves. The first column is the rule number, followed by the number of outgoing matched packets, followed by the number of incoming matched packets, followed by the rule itself.

# ipfw -a list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The first column is indeed the rule number. The second column, however, is simply the amount of packets matched (in and out). Furthermore, the third column is a byte counter, not a packet counter. The fourth column is indeed the rule itself.

You can verify this in "/usr/src/sbin/ipfw/ipfw2.c" when you search for the function "ipfw_list". This is what you'll find:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* if showing stats, figure out column widths ahead of time */
bcwidth = pcwidth = 0;
if (show_counters) {
	for (n = 0, r = data; n < nstat; n++, r = NEXT(r)) {
		/* skip rules from another set */
		if (co.use_set && r->set != co.use_set - 1)
			continue;

		/* packet counter */
		width = pr_u64(&r->pcnt, 0);
		if (width > pcwidth)
			pcwidth = width;

		/* byte counter */
		width = pr_u64(&r->bcnt, 0);
		if (width > bcwidth)
			bcwidth = width;
	}
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fix: 

The IPFW page in the Handbook should be corrected to reflect the correct purposes of the columns in `ipfw show` output.
How-To-Repeat: Read the IPFW section in the FreeBSD Handbook.
Comment 1 Sergey Kandaurov freebsd_committer freebsd_triage 2013-06-08 14:23:08 UTC
State Changed
From-To: open->closed

Committed, thanks!
Comment 2 dfilter service freebsd_committer freebsd_triage 2013-06-08 14:23:10 UTC
Author: pluknet
Date: Sat Jun  8 13:22:53 2013
New Revision: 41868
URL: http://svnweb.freebsd.org/changeset/doc/41868

Log:
  Fix column description for "ipfw -a list" output.
  
  PR:		docs/178959

Modified:
  head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml	Sat Jun  8 12:34:02 2013	(r41867)
+++ head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml	Sat Jun  8 13:22:53 2013	(r41868)
@@ -3690,8 +3690,7 @@ ipfw add deny out</programlisting>
       <para>The next example lists accounting information and the
 	packet count for matched rules along with the rules
 	themselves.  The first column is the rule number, followed by
-	the number of outgoing matched packets, followed by the number
-	of incoming matched packets, followed by the rule
+	the number of matched packets and bytes, followed by the rule
 	itself.</para>
 
       <screen>&prompt.root; <userinput>ipfw -a list</userinput></screen>
_______________________________________________
svn-doc-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"