[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
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.
> > > 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.
> > > 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.
> > > 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:
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".
> > 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.
> > > 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.
> > > 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.
> > > 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.
Thanks,
Mike