[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Updating the MIB Review guidelines - my comments part 1
Inline.
> -----Original Message-----
> From: C. M. Heard [mailto:heard@pobox.com]
> Sent: dinsdag 8 juni 2004 18:49
> To: Mreview (E-mail)
> Subject: RE: Updating the MIB Review guidelines - my comments part 1
>
>
> Hello again,
>
> I have had a few hours to work on the guidelines this morning and I
> will try to close out as many of Bert's part 1 open issues as I can.
>
> On Tue, 8 Jun 2004, Wijnen, Bert (Bert) wrote:
> ...
> > > -----Original Message-----
> > > From: C. M. Heard [mailto:heard@pobox.com]
> ...
> > > On Mon, 7 Jun 2004, Wijnen, Bert (Bert) wrote:
> ...
> > > > 1. This document should probably set a GOOD example and
> > > > have its own IANA COnsiderations section!?
> > >
> > > It does! It's right after the full copyright statement.
> > > It's bundled with the other removable sections.
> > >
> > Guess I missed it because it is not listed in ToC.
> > Normally I think IANA considerations is a ToC entry.
>
> OK, It will be listed in the TOC in the next rev. I will also list
> the "Revision History" section in the TOC.
>
thanks
> > > > 6. Sect 3.6 should maybe also list that "privacy
> > > > aspects/risks" must be documented in the security
> > > > considerations section.
> > >
> > > That's already covered in "Guidelines for a MIB security
> > > section" at http://www.ops.ietf.org/mib-security.html and I
> > > would rather not duplicate it here.
> > >
> > Mmm... it seems to be a point though that does not stick well
> > enough with people. And then there comes the saying:
> > "repetition is the key to learning". Oh well...
>
> OK, then here is a proposal for a reworked version of Section 3.6.
> Not sure whether it is exactly what you want, but it does at least
> to mention privacy concerns in addition to the other risks. Note
> that I removed the mention of 2223bis since the authoritative
> source is the security template.
>
> 3.6. Security Considerations Section
>
> Each specification that defines one or more MIB modules
> MUST contain
> a section that discusses security considerations relevant to those
> modules. This section MUST be patterned after the latest approved
> template (available at http://www.ops.ietf.org/mib-security.html).
> In particular, writeable MIB objects that could be especially
> disruptive if abused MUST be explicitly listed by name and the
> associated security risks MUST be spelled out; similarly, readable
> MIB objects that contain especially sensitive information or that
> raise significant privacy concerns MUST be explicitly
> listed by name
> and the reasons for the sensitivity/privacy conserns MUST be
> explained. If there are no risks/vulnerabilities for a specific
> category of MIB objects, then that fact MUST be explicitly stated.
> Failure to mention a particular category of MIB objects will not be
> equated to a claim of no risks/vulnerabilities in that category;
> rather, it will be treated as an act of omission and will result in
> the document being returned to the author for correction. Remember
> that the objective is not to blindly copy text from the
> template, but
> rather to think and evaluate the risks/vulnerabilies and then
> state/document the result of this evaluation.
>
> This text is now incorporated into my nroff source.
>
Looks good to me
> > > > 9. Sect 3.7 last para.
> > > > Although it is probably such that RFC-Editor will remove an
> > > > empty IANA Considerations section, I wonder if we should
> > > > recommend that authors/editors instruct RFC-Editor to do so
> > > > or not. Since this still has ongoing discussion in various
> > > > places, why do we not just leave it out and then whenever
> > > > the policy settles, RFC-Editor will know what to do.
> > >
> > > Current RFC Editor policy is to remove null IANA considerations
> > > sections. It's true that if the RFC Editor policy changes we'll
> > > have to change the text here. But if the policy stays as is, I
> > > would prefer to have the instructions exactly as I have written
> > > them, so that authors will know what to expect (and hopefully
> > > will not then to do things such as putting in citations to RFC
> > > 2434).
> >
> > There is actually debate in IESG if RFC-Editor can just remove
> > such IANA considerations section. And anyway... we will never
> > know how policy changes over time. So if possible I like to be
> > silent on it. But it is just a personal opinion.
>
> Presumably, the debate that is going on is about whether the
> RFC Editor can unilaterally remove a null IANA Considerations
> section without the author's consent. In that case the policy
> change (if one comes about) would be that such could be left
> in or taken out at the author's discretion. I think the
> proposed text as it now stands would be compatible with
> such a policy.
>
> Maybe I am abusing my position as document editor to lobby to hard
> for my own position on this matter. If people think so, then I
> will back off. But I do have a very strong opinion (as, apparently,
> does the RFC Editor) that a null IANA considerations section has no
> place in an archival document, and I would like to see the review
> guidelines suggest (not require) that people to proceed in that
> way. That is exactly what the proposed text does.
>
My point was that I believe I am seeing consensus forming in IESG to keep
it in RFCs. But that is still debated, and once we get there we may have
to go through a debate with Bob/RFC-ed.
So what will happen in the end is not clear.
Now RFC-Ed has claimed they will remove empty statements, so as long
as there is no IESG/IETF mandated policy to keep them they will get
removed and the things you prefer will happen.
By leaving the text "may be removed" or "should be removed" out of the
guideline (and text in I-Ds), you get what you want, and this doc
will still be valid if IESG/IETF change policy.
I do have some sympathy for your "if author agrees/disagrees" argument
also.
> > > > 10. Sect 3.8 states:
> > > > IETF MIB documents MUST contain the copyright notices
> > > > and disclaimer specified in Section 4.3 of RFC 2223bis
> > > > [RFC2223bis] and Sections 5.4 and 5.5 of RFC 3667
> > > > [RFC3667].
> > > > I believe that RFC3667 is the authoritative place. And so I
> > > > would rather see it phrased as follows:
> > > > IETF MIB documents MUST contain the copyright notices
> > > > and disclaimer specified in Sections 5.4 and 5.5 of RFC
> > > > 3667 [RFC3667]. Note that Section 4.3 of RFC 2223bis
> > > > [RFC2223bis] also states this requirement.
> > > > Or maybe not even talk about 2223bis here at all.
> > >
> > > I was about to agree with you, and then I realized that what you
> > > said is not quite true. RFC2223bis Section 4.3 requires a
> > > copyright notice on the front page of each RFC; as of this
> > > writing, that is still the policy of the RFC Editor.
> >
> > Right, and they will add it. And they can do so based on the
> > text that is in RFC3667 and 3668. So we should not make
> > ourselves dependent on 2223bis. Or so is my personal (actaully
> > pretty strong) opinion.
>
> OK, since the notice on the front page is no longer required I can
> accept your proposed text. I also see that I failed to get the
> updated text for IANA MIB module copyrights into the draft. So here
> is what is now in my nroff source:
>
next text looks good to me
> 3.8. Copyright Notices
>
> IETF MIB documents MUST contain the copyright notices and
> disclaimer
> specified in Sections 5.4 and 5.5 of RFC 3667 [RFC3667].
> Authors and
> reviewers MUST check to make sure that the correct year is inserted
> into these notices. In addition, the DESCRIPTION clause of the
> MODULE-IDENTITY invocation of each MIB module that will
> appear in the
> published RFC MUST contain a pointer to the copyright
> notices in the
> RFC. A template suitable for inclusion in an Internet-Draft,
> appropriate for MIB modules other than those that are to be
> maintained by the IANA, is as follows:
>
> DESCRIPTION
> " [ ... ]
>
> Copyright (C) The Internet Society (date). This version
> of this MIB module is part of RFC yyyy; see the RFC
> itself for full legal notices."
> -- RFC Ed.: replace yyyy with actual RFC number & remove this note
>
> A template suitable for MIB modules that are to be
> maintained by the
> IANA is as follows:
>
> DESCRIPTION
> " [ ... ]
>
> Copyright (C) The Internet Society (date). The initial
> version of this MIB module was published in RFC yyyy;
> for full legal notices see the RFC itself. Supplementary
> information may be available on
> http://www.ietf.org/copyrights/ianamib.html.";
> -- RFC Ed.: replace yyyy with actual RFC number & remove this note
>
> In each case the current year is to be inserted in place
> of the word "date".
>
Looks good. I had missed the new text fragments indeed, but thought you had
done so on purpose since it is now clear in 3667.
> > > RFC 3667 does not mention a copyright notice for the front page.
> > > It talks only about the notice and disclosure that appear at the
> > > end and the abbreviated one that goes in a MIB module.
> > >
> > > Again, it's possible that RFC Editor policy will change and we
> > > will have to catch up, but we'll have a change to do that before
> > > publication because RFC2223bis is a normative reference and has
> > > to be published first.
>
> > > > 12. Sect 4.1. Might be good to emphasize that app C also has
> > > > suggestions on naming conventions.
> > >
> > > It already does this.
> > >
> > Mmmm
> > sect 4.1 says:
> > It is RECOMMENDED that module names be mnemonic. See
> Appendix C for
> > additional suggestions.
> >
> > sect 4.2 is better in my view with:
> >
> > See Appendix C for suggested descriptor and TC naming
> conventions.
>
> OK, my nroff source now has the following text for the last paragraph
> of Section 4.1:
>
> It is RECOMMENDED that module names be mnemonic. See Appendix C for
> suggested naming conventions.
>
thanks (it was a nit though)
> > > > Did we ever agree on wanting to have TC modules be of the form
> > > > XXXX-TC-MIB ??
> > > > If so we should add it.
> > >
> > > Proposal:
> > >
> > > OLD:
> > > - The module name should be of the form XXX-MIB, where XXX is a
> > > unique prefix (usually all caps with hyphens for
> separators) that
> > > is not used by any existing IETF MIB module. For
> example, the MIB
> > > module for managing optical interfaces [RFC3591]
> uses the prefix
> > > OPT-IF and has module name OPT-IF-MIB.
> > > NEW:
> > > - The module name should be of the form XXX-MIB (or
> XXX-TC-MIB for a
> > > module with TCs only), where XXX is a unique prefix
> (usually all
> > > caps with hyphens for separators) that is not used
> by any existing
> > > module. For example, the module for managing
> optical interfaces
> > > [RFC3591] uses the prefix OPT-IF and has module name
> OPT-IF-MIB.
> > >
> > > (I have elided a few words because I would like for this
> appendix to
> > > fit on a single page).
> > >
> > NEW text looks fine to me.
>
> OK, it is now incorporated into my nroff source.
>
thanks
> > > > 14. First bullet in sect 4.5
> > > > Recently there was discussion (and new ID-Checklist
> has a statement
> > > > about it) that WG names, mailing list info and
> charter pages" should
> > > > not be listed in RFCs. The reason being that after
> x years that
> > > > mailing list will no longer exist, neither will the WG.
> > > > So... although I personally like it if the WG name
> and mlist is
> > > > mentioned, is it still fair to require/recommend that?
> > >
> > > I'll do whatever you say. What's in there now is
> existing practice.
> > > If we keep it, then ID-Checklist should acknowledge this practice.
> > >
> > I understand it is existing practice,
> > I am bringing it up because it is now discouraged in ID-Checklist.
> > I told IESG that we do it for MIB modules and that we thought it was
> > goodness. So they will accept that as an exception (I think).
> > If we want to keep it, we can and we'll see if IESG barks.
>
> That is what I would like to do.
>
OK, pls keep it then
> > > > 16. Sect 4.6.1.1
> > > > - I think you want to indent the first 2 paragraphs on page 15
> > > > (2 positions to the right.
> > >
> > > It looks right to me.
> > >
> > It looks as follows:
> > - For integer-valued enumerations:
> >
> > - INTEGER is REQUIRED;
> > - Integer32, Unsigned32, and Gauge32 MUST NOT be used.
> >
> > Note that RFC 2578 recommends (but does not require)
> that integer-
> > valued enumerations start at 1 and be numbered
> contiguously. This
> > recommendation SHOULD be followed unless there is a
> valid reason to
> > do otherwise, e.g., to match values of external data or
> to indicate
> > special cases, and any such special-case usage SHOULD be clearly
> > documented. For an example see the InetAddressType TC [RFC3291].
> >
> > Although the SMI allows DEFVAL clauses for integer-valued
> > enumerations to specify the default value either by label or by
> > numeric value, the label form is preferred since all the
> examples in
> > RFC 2578 are of that form and some tools do not accept
> the numeric
> > form.
> >
> > - If the value range is between -2147483648..2147483647
> (inclusive)
> > and negative values are possible, then:
> >
> > So to me it seems that the 2 paragraphs belong to the
> discussion about
> > inter-valued enumerations. So I (but this is probably just
> a matter of
> > style) would indent them 2 to the right.
> >
> > > > - I think you want to indent the 3rd and 2nd to
> last paragraphs
> > > > of sect 4.6.1.1 also 2 positions to the right
> > >
> > > That also looks right to me. I just ran off a copy without
> > > any headers or footers to verify that.
> > >
> > Same reasoning on my side.
>
> Here is what it looks like with your proposed change:
>
> 4.6.1.1. INTEGER, Integer32, Gauge32, and Unsigned32
>
> The 32-bit integer data types INTEGER, Integer32, Gauge32, and
> Unsigned32 are described in RFC 2578 Section 2 and further
> elaborated
> in RFC 2578 Sections 7.1.1, 7.1.7, and 7.1.11. The following
> guidelines apply when selecting one of these data types
> for an object
> definition or a textual convention:
>
> - For integer-valued enumerations:
>
> - INTEGER is REQUIRED;
> - Integer32, Unsigned32, and Gauge32 MUST NOT be used.
>
> Note that RFC 2578 recommends (but does not require)
> that integer-
> valued enumerations start at 1 and be numbered
> contiguously. This
> recommendation SHOULD be followed unless there is a
> valid reason to
> do otherwise, e.g., to match values of external data or
> to indicate
> special cases, and any such special-case usage SHOULD be clearly
> documented. For an example see the InetAddressType TC [RFC3291].
>
> Although the SMI allows DEFVAL clauses for integer-valued
> enumerations to specify the default value either by label or by
> numeric value, the label form is preferred since all the examples
> in RFC 2578 are of that form and some tools do not accept the
> numeric form.
>
> - If the value range is between -2147483648..2147483647 (inclusive)
> and negative values are possible, then:
>
> - Integer32 is RECOMMENDED;
> - INTEGER is acceptable;
> - Unsigned32 and Gauge32 MUST NOT be used.
>
> - If the value range is between 0..4294967295 (inclusive) and the
> value of the information being modelled may increase above the
> maximum value or decrease below the minimum value, then:
>
> - Gauge32 is RECOMMENDED;
> - Unsigned32 is acceptable;
> - INTEGER and Integer32 MUST NOT be used if
> values greater than 2147483647 are possible.
>
> - If the value range is between 0..4294967295 (inclusive),
> and values
> greater than 2147483647 are possible, and the value of the
> information being modelled does not increase above the maximum
> value nor decrease below the minimum value, then:
>
> - Unsigned32 is RECOMMENDED;
> - Gauge32 is acceptable;
> - INTEGER and Integer32 MUST NOT be used.
>
> - If the value range is between 0..2147483647 (inclusive), and the
> value of the information being modelled does not
> increase above the
> maximum value nor decrease below the minimum value, then:
>
> - Unsigned32 is RECOMMENDED;
> - INTEGER, Integer32, and Gauge32 are acceptable.
>
> - For integer-valued objects that appear in an INDEX clause or for
> integer-valued TCs that are to be used in an index column:
>
> - Unsigned32 with a range that excludes zero is RECOMMENDED for
> most index objects. It is acceptable to include zero in the
> range when it is semantically significant or when it is used as
> the index value for a unique row with special
> properties. Such
> usage SHOULD be clearly documented in the DESCRIPTION clause.
>
> - Integer32 or INTEGER with a non-negative range is acceptable.
> Again, zero SHOULD be excluded from the range except when it is
> semantically significant or when it is used as the index value
> for a unique row with special properties, and in such cases the
> usage SHOULD be clearly documented in the DESCRIPTION clause.
>
> - Use of Gauge32 is acceptable for index objects that have gauge
> semantics.
>
> The guidelines above combine both the usage rules for
> integer data
> types and the INDEX rules in RFC 2578 Section 7.7 up to and
> including bullet (1) plus the next-to-last paragraph on page 28.
>
> Sometimes it will be necessary for external variables to represent
> values of an index object -- e.g., ifIndex [RFC2863]. In
> such cases
> authors of the module containing that object SHOULD
> consider defining
> TCs such as InterfaceIndex and/or InterfaceIndexOrZero [RFC2863].
>
> Note that INTEGER is a pre-defined ASN.1 type and MUST NOT
> be present
> in a module's IMPORTS statement, whereas Integer32, Gauge32, and
> Unsigned32 are defined by SNMPv2-SMI and MUST be imported from that
> module if used.
>
> Frankly, it does not look very good to my eye, since the bullets don't
> stand out as much. But I will do it if you insist.
>
OK, so it is clearly a matter of taste/style. I personally like the
latter style better... but.
It was a nit, and not something I feel that strong about.
I'll give you your way for being the editor.
Bert
> Thanks,
>
> Mike
>
>