From grg@ridley.unimelb.edu.au  Tue Aug 26 18:07:26 2003
Return-Path: <grg@ridley.unimelb.edu.au>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 883A816A4BF
	for <freebsd-gnats-submit@freebsd.org>; Tue, 26 Aug 2003 18:07:26 -0700 (PDT)
Received: from genesis.ridley.unimelb.edu.au (genesis.ridley.unimelb.edu.au [128.250.2.82])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 1562343FCB
	for <freebsd-gnats-submit@freebsd.org>; Tue, 26 Aug 2003 18:07:25 -0700 (PDT)
	(envelope-from grg@ridley.unimelb.edu.au)
Received: (from root@localhost)
	by genesis.ridley.unimelb.edu.au (8.12.3p2/8.11.6) id h7R17Ng4047527
	for freebsd-gnats-submit@freebsd.org; Wed, 27 Aug 2003 11:07:23 +1000 (EST)
	(envelope-from grg@genesis.ridley.unimelb.edu.au)
Received: from genesis.ridley.unimelb.edu.au (localhost [127.0.0.1])
	by genesis.ridley.unimelb.edu.au (8.12.3p2/8.12.5) with ESMTP id h7R17Ln3047515
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 27 Aug 2003 11:07:21 +1000 (EST)
	(envelope-from grg@genesis.ridley.unimelb.edu.au)
Received: (from root@localhost)
	by genesis.ridley.unimelb.edu.au (8.12.3p2/8.12.5/Submit) id h7R17L23047514;
	Wed, 27 Aug 2003 11:07:21 +1000 (EST)
	(envelope-from grg)
Message-Id: <200308270107.h7R17L23047514@genesis.ridley.unimelb.edu.au>
Date: Wed, 27 Aug 2003 11:07:21 +1000 (EST)
From: Glen Gibb <grg@ridley.unimelb.edu.au>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Documentation incorrect for mac in ipfw2
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         56021
>Category:       docs
>Synopsis:       Documentation incorrect for mac in ipfw2
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    roam
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Aug 26 18:10:02 PDT 2003
>Closed-Date:    Fri Jun 04 02:24:59 PDT 2004
>Last-Modified:  Fri Jun 04 02:24:59 PDT 2004
>Originator:     Glen Gibb
>Release:        FreeBSD 5.1-CURRENT i386
>Organization:
Ridley College
>Environment:
System: FreeBSD genesis.ridley.unimelb.edu.au 5.1-CURRENT FreeBSD 5.1-CURRENT #3: Wed Aug 27 00:08:46 EST 2003 grg@leviticus.ridley.unimelb.edu.au:/usr/obj/usr/src/sys/GENESIS i386

	
>Description:
The man page for ipfw (IPFW2) is incomplete/misleading in regards to the "mac" option in the RULE OPTIONS section. 

The man page states that the address can be "optionally followed by a mask indicating how many bits are significant, as in MAC 10:20:30:40:50:60/33 any". This IS correct but it does not mention the second method of specifying a bit mask, that is by following the address with an ampersand (&) followed by the bitmask whcich is specified using the same format as the address. For example, if we wanted to match any mac address that ended with 60, we could use the following mask:
MAC 00:00:00:00:50:60&00:00:00:00:00:ff

>How-To-Repeat:
man ipfw 
:)
	
>Fix:
Suggested change to the documentation:

"Match packets with a given dst-mac and src-mac addresses, speci-
fied as the any keyword (matching any MAC address), or six groups
of hex digits separated by colons, and optionally followed by a
mask indicating the significant bits.

The mask may be specified using either of the following methods:

i) append to the address a slash (/) followed by the number of bits that 
are significant. For example, an address in which the first 33 bits are
significant could be specified as:

MAC 10:20:30:40:50:60/33 any

ii) append to the address an ampersand (&) followed by a bitmask specified
as six groupsof hex digits separated by colons. For example, an address in 
which the last 16 bits are significant could be specified as:

MAC 10:20:30:40:50:60&00:00:00:00:00:ff any

Note that the ampersand character has special meaning in most shells and
must generally be escaped.

Note that the order of MAC addresses (destination first, source
second) is the same as on the wire, but the opposite of the one
used for IP addresses."
>Release-Note:
>Audit-Trail:

From: Peter Pentchev <roam@ringlet.net>
To: Glen Gibb <grg@ridley.unimelb.edu.au>
Cc: bug-followup@FreeBSD.org, ipfw@FreeBSD.org
Subject: Re: docs/56021: Documentation incorrect for mac in ipfw2
Date: Fri, 5 Sep 2003 19:19:15 +0300

 On Wed, Aug 27, 2003 at 11:07:21AM +1000, Glen Gibb wrote:
 > 
 > >Number:         56021
 > >Category:       docs
 > >Synopsis:       Documentation incorrect for mac in ipfw2
 > >Originator:     Glen Gibb
 > >Release:        FreeBSD 5.1-CURRENT i386
 [snip]
 > >Description:
 > 
 > The man page for ipfw (IPFW2) is incomplete/misleading in regards to
 > the "mac" option in the RULE OPTIONS section. 
 > 
 > The man page states that the address can be "optionally followed by a
 > mask indicating how many bits are significant, as in MAC
 > 10:20:30:40:50:60/33 any". This IS correct but it does not mention the
 > second method of specifying a bit mask, that is by following the
 > address with an ampersand (&) followed by the bitmask whcich is
 > specified using the same format as the address. For example, if we
 > wanted to match any mac address that ended with 60, we could use the
 > following mask:
 > 
 > MAC 00:00:00:00:50:60&00:00:00:00:00:ff
 
 What do you think about the following patch?
 
 G'luck,
 Peter
 
 -- 
 Peter Pentchev	roam@ringlet.net    roam@sbnd.net    roam@FreeBSD.org
 PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
 Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
 This sentence was in the past tense.
 
 Index: src/sbin/ipfw/ipfw.8
 ===================================================================
 RCS file: /home/ncvs/src/sbin/ipfw/ipfw.8,v
 retrieving revision 1.131
 diff -u -r1.131 ipfw.8
 --- src/sbin/ipfw/ipfw.8	22 Jul 2003 07:41:24 -0000	1.131
 +++ src/sbin/ipfw/ipfw.8	5 Sep 2003 16:12:41 -0000
 @@ -1046,11 +1046,31 @@
  .Cm any
  keyword (matching any MAC address), or six groups of hex digits
  separated by colons,
 -and optionally followed by a mask indicating how many bits are
 -significant, as in
 +and optionally followed by a mask indicating the significant bits.
 +The mask may be specified using either of the following methods:
 +.Bl -enum -width indent
 +.It
 +A slash
 +.Pq /
 +followed by the number of significant bits.
 +For example, an address with 33 significant bits could be specified as:
  .Pp
  .Dl "MAC 10:20:30:40:50:60/33 any"
  .Pp
 +.It
 +An ampersand
 +.Pq &
 +followed by a bitmask specified as six groups of hex digits separated
 +by colons.
 +For example, an address in which the last 16 bits are significant could
 +be specified as:
 +.Pp
 +.Dl "MAC 10:20:30:40:50:60&00:00:00:00:00:ff any"
 +.Pp
 +Note that the ampersand character has a special meaning in many shells
 +and should generally be escaped.
 +.Pp
 +.El
  Note that the order of MAC addresses (destination first,
  source second) is
  the same as on the wire, but the opposite of the one used for

From: Glen Gibb <grg@ridley.unimelb.edu.au>
To: Peter Pentchev <roam@ringlet.net>
Cc: bug-followup@freebsd.org, <ipfw@freebsd.org>
Subject: Re: docs/56021: Documentation incorrect for mac in ipfw2
Date: Mon, 8 Sep 2003 20:34:44 +1000 (EST)

 The patch looks ok to me. Don't be surprised if I'm slow to reply for the
 next week or two - I'm currently travalling.
 
 Glen
 
 On Fri, 5 Sep 2003, Peter Pentchev wrote:
 
 > On Wed, Aug 27, 2003 at 11:07:21AM +1000, Glen Gibb wrote:
 > >
 > > >Number:         56021
 > > >Category:       docs
 > > >Synopsis:       Documentation incorrect for mac in ipfw2
 > > >Originator:     Glen Gibb
 > > >Release:        FreeBSD 5.1-CURRENT i386
 > [snip]
 > > >Description:
 > >
 > > The man page for ipfw (IPFW2) is incomplete/misleading in regards to
 > > the "mac" option in the RULE OPTIONS section.
 > >
 > > The man page states that the address can be "optionally followed by a
 > > mask indicating how many bits are significant, as in MAC
 > > 10:20:30:40:50:60/33 any". This IS correct but it does not mention the
 > > second method of specifying a bit mask, that is by following the
 > > address with an ampersand (&) followed by the bitmask whcich is
 > > specified using the same format as the address. For example, if we
 > > wanted to match any mac address that ended with 60, we could use the
 > > following mask:
 > >
 > > MAC 00:00:00:00:50:60&00:00:00:00:00:ff
 >
 > What do you think about the following patch?
 >
 > G'luck,
 > Peter
 >
 > --
 > Peter Pentchev	roam@ringlet.net    roam@sbnd.net    roam@FreeBSD.org
 > PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
 > Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
 > This sentence was in the past tense.
 >
 > Index: src/sbin/ipfw/ipfw.8
 > ===================================================================
 > RCS file: /home/ncvs/src/sbin/ipfw/ipfw.8,v
 > retrieving revision 1.131
 > diff -u -r1.131 ipfw.8
 > --- src/sbin/ipfw/ipfw.8	22 Jul 2003 07:41:24 -0000	1.131
 > +++ src/sbin/ipfw/ipfw.8	5 Sep 2003 16:12:41 -0000
 > @@ -1046,11 +1046,31 @@
 >  .Cm any
 >  keyword (matching any MAC address), or six groups of hex digits
 >  separated by colons,
 > -and optionally followed by a mask indicating how many bits are
 > -significant, as in
 > +and optionally followed by a mask indicating the significant bits.
 > +The mask may be specified using either of the following methods:
 > +.Bl -enum -width indent
 > +.It
 > +A slash
 > +.Pq /
 > +followed by the number of significant bits.
 > +For example, an address with 33 significant bits could be specified as:
 >  .Pp
 >  .Dl "MAC 10:20:30:40:50:60/33 any"
 >  .Pp
 > +.It
 > +An ampersand
 > +.Pq &
 > +followed by a bitmask specified as six groups of hex digits separated
 > +by colons.
 > +For example, an address in which the last 16 bits are significant could
 > +be specified as:
 > +.Pp
 > +.Dl "MAC 10:20:30:40:50:60&00:00:00:00:00:ff any"
 > +.Pp
 > +Note that the ampersand character has a special meaning in many shells
 > +and should generally be escaped.
 > +.Pp
 > +.El
 >  Note that the order of MAC addresses (destination first,
 >  source second) is
 >  the same as on the wire, but the opposite of the one used for
 >
 
State-Changed-From-To: open->patched 
State-Changed-By: roam 
State-Changed-When: Tue Sep 9 23:41:28 PDT 2003 
State-Changed-Why:  
Committed to -CURRENT, I will merge it into -STABLE in a month, 
after the code freeze for 4.9-RELEASE is over. 
Thanks for reporting this! 


Responsible-Changed-From-To: freebsd-doc->roam 
Responsible-Changed-By: roam 
Responsible-Changed-When: Tue Sep 9 23:41:28 PDT 2003 
Responsible-Changed-Why:  
I will handle the MFC. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=56021 
State-Changed-From-To: patched->closed 
State-Changed-By: roam 
State-Changed-When: Fri Jun 4 02:24:37 PDT 2004 
State-Changed-Why:  
A couple of months late, I merged the clarification into -STABLE. 
Thanks for the problem report! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=56021 
>Unformatted:
