docs/56021: Documentation incorrect for mac in ipfw2

[Glen Gibb]

>Number:         56021
>Category:       docs
>Synopsis:       Documentation incorrect for mac in ipfw2
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Aug 26 18:10:02 PDT 2003
>Closed-Date:
>Last-Modified:
>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 at 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:
>Unformatted: