docs/56021: Documentation incorrect for mac in ipfw2

[Peter Pentchev]

The following reply was made to PR docs/56021; it has been noted by GNATS.

From: Peter Pentchev <roam at ringlet.net>
To: Glen Gibb <grg at ridley.unimelb.edu.au>
Cc: bug-followup at FreeBSD.org, ipfw at 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 at ringlet.net    roam at sbnd.net    roam at 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