From nobody@FreeBSD.org  Fri May 24 23:05:04 2013
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1])
	by hub.freebsd.org (Postfix) with ESMTP id 1ACA2299
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 24 May 2013 23:05:04 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from oldred.FreeBSD.org (oldred.freebsd.org [8.8.178.121])
	by mx1.freebsd.org (Postfix) with ESMTP id E7B49869
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 24 May 2013 23:05:03 +0000 (UTC)
Received: from oldred.FreeBSD.org ([127.0.1.6])
	by oldred.FreeBSD.org (8.14.5/8.14.5) with ESMTP id r4ON53uv096427
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 24 May 2013 23:05:03 GMT
	(envelope-from nobody@oldred.FreeBSD.org)
Received: (from nobody@localhost)
	by oldred.FreeBSD.org (8.14.5/8.14.5/Submit) id r4ON53Ib096419;
	Fri, 24 May 2013 23:05:03 GMT
	(envelope-from nobody)
Message-Id: <201305242305.r4ON53Ib096419@oldred.FreeBSD.org>
Date: Fri, 24 May 2013 23:05:03 GMT
From: Kevin Zheng <kevinz5000@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Incorrect column descriptions for `ipfw -a list` output in handbook
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         178959
>Category:       docs
>Synopsis:       Incorrect column descriptions for `ipfw -a list` output in handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri May 24 23:10:00 UTC 2013
>Closed-Date:    Sat Jun 08 13:23:30 UTC 2013
>Last-Modified:  Sat Jun  8 13:30:01 UTC 2013
>Originator:     Kevin Zheng
>Release:        9.1-RELEASE-p3
>Organization:
>Environment:
FreeBSD sigma.local 9.1-RELEASE-p3 FreeBSD 9.1-RELEASE-p3 #0: Mon Apr 29 18:11:52 UTC 2013     root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  i386
>Description:
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;
	}
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

>How-To-Repeat:
Read the IPFW section in the FreeBSD Handbook.
>Fix:
The IPFW page in the Handbook should be corrected to reflect the correct purposes of the columns in `ipfw show` output.

>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->closed 
State-Changed-By: pluknet 
State-Changed-When: Sat Jun 8 13:23:08 UTC 2013 
State-Changed-Why:  
Committed, thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=178959 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/178959: commit references a PR
Date: Sat,  8 Jun 2013 13:23:10 +0000 (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"
 
>Unformatted:
