From grg@ridley.unimelb.edu.au Tue Aug 26 18:07:26 2003 Return-Path: Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 883A816A4BF for ; 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 ; 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 ; 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 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 To: Glen Gibb 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 To: Peter Pentchev Cc: bug-followup@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: