[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: XML2RFC template for MIB modules
On Tue, 27 Sep 2005, David B Harrington wrote:
> I have enclosed a text document that is the output of my xml2rfc MIB
> module template, so you can see roughly what will get generated, and
> can comment on the layout, etc.
Thanks for kicking this off. It's a good start, but I have some
criticisms of the proposed section organization. Looking at the
template's table of contents I see:
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 The Internet-Standard Management Framework . . . . . . . . 4
2.2 Key Words . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 Textual Conventions . . . . . . . . . . . . . . . . . . . 4
3. Narrative Sections . . . . . . . . . . . . . . . . . . . . . . 4
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2 Design Principles . . . . . . . . . . . . . . . . . . . . 5
3.3 Structure of the MIB Module . . . . . . . . . . . . . . . 6
3.3.1 The sample Group . . . . . . . . . . . . . . . . . . . 6
3.3.2 The sample999 Group . . . . . . . . . . . . . . . . . 6
3.3.3 The Notifications Group . . . . . . . . . . . . . . . 6
3.4 Relationship to Other MIB Modules . . . . . . . . . . . . 6
3.4.1 Relationship to the SNMPv2-MIB . . . . . . . . . . . . 7
3.4.2 Relationship to the IF-MIB . . . . . . . . . . . . . . 7
3.4.3 MIB modules required for Imports . . . . . . . . . . . 7
4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 7
5. Security Considerations . . . . . . . . . . . . . . . . . . . 13
5.1 Sensitive Modifiable Objects . . . . . . . . . . . . . . . 13
5.2 Sensitive Readable Objects . . . . . . . . . . . . . . . . 13
5.3 Protocol Security . . . . . . . . . . . . . . . . . . . . 13
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
8.1 Normative References . . . . . . . . . . . . . . . . . . . 15
8.2 Informative References . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 16
A. Appendice A . . . . . . . . . . . . . . . . . . . . . . . . . 16
B. Changes from RFC BBBB (the previous RFC for this
specification) . . . . . . . . . . . . . . . . . . . . . . . . 16
C. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 16
Intellectual Property and Copyright Statements . . . . . . . . 18
I think this is too elaborate. It's not the way most MIB documents are
done today and I can't see a good reason for that. To see what I mean,
here is the TOC from ftp://ftp.isi.edu/in-notes/authors/rfc4188.txt,
which is the current BRIDGE-MIB galley proof:
1. The Internet-Standard Management Framework ......................2
2. Conventions .....................................................2
3. Overview ........................................................3
3.1. Structure of the MIB Module ................................3
3.1.1. The dot1dBase Subtree ...............................6
3.1.2. The dot1dStp Subtree ................................6
3.1.3. The dot1dSr Subtree .................................6
3.1.4. The dot1dTp Subtree .................................6
3.1.5. The dot1dStatic Subtree .............................6
3.2. Relationship to Other MIB Modules ..........................6
3.2.1. Relationship to the SNMPv2-MIB ......................7
3.2.2. Relationship to the IF-MIB ..........................7
4. Definitions .....................................................8
5. IANA Considerations ............................................39
6. Security Considerations ........................................39
7. Acknowledgements ...............................................40
8. Contact Information ............................................41
9. Changes from RFC 1493 ..........................................42
10. References ....................................................42
10.1. Normative References .....................................42
10.2. Informative References ...................................43
Authors' Addresses ................................................43
Full Copyright Statement ..........................................44
Intellectual Property .............................................44
Note: the last two sections aren't actually listed in the TOC of the
RFC-to-be, but are included here for the sake of our discussion.
I would call this near to ideal as a template. The things I would change
would be:
- put "Security Considerations" before "IANA Considerations" (this is
arbitrary but is what is in 2223bis and rfc 4181)
- either leave out "Contact Information" or change it to "Contributors"
(the latter being more common, especially for new work)
- add some appendices just before the "References" section, and give
them appendix labels rather than section numbers;
- make the References section (and its subsections) unnumbered.
Note that the MIB boilerplate comes first and has the title and section
number EXACTLY as in http://www.ops.ietf.org/mib-boilerplate.html. That
is a feature I would like to see in any MIB document template. I would
also like to see a stand-alone "Conventions" section follow, since that
seems to be the most common practice. If that gives heartburn, a good
alternate choice would be "Terminology". It seems to me that any
discussion of TEXTUAL-CONVENTIONS should go in the "Structure of the
MIB Module" part.
I am sorry to be so picky, but one thing I don't think this template
should be is inventive! It should simply copy the most common set of
best current practices that MIB documents actually use.
Thanks for listening.
Mike