Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 4181

Guidelines for Authors and Reviewers of MIB Documents

Pages: 42
Best Current Practice: 111
Errata
BCP 111 is also:  4841
Updated by:  4841
Part 1 of 3 – Pages 1 to 10
None   None   Next

Top   ToC   RFC4181 - Page 1
Network Working Group                                      C. Heard, Ed.
Request for Comments: 4181                                September 2005
BCP: 111
Category: Best Current Practice


         Guidelines for Authors and Reviewers of MIB Documents

Status of This Memo

   This document specifies an Internet Best Current Practices for the
   Internet Community, and requests discussion and suggestions for
   improvements.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2005).

Abstract

This memo provides guidelines for authors and reviewers of IETF standards-track specifications containing MIB modules. Applicable portions may be used as a basis for reviews of other MIB documents.

Table of Contents

1. Introduction ....................................................3 2. Terminology .....................................................3 3. General Documentation Guidelines ................................4 3.1. MIB Boilerplate Section ....................................4 3.2. Narrative Sections .........................................5 3.3. Definitions Section ........................................5 3.4. Security Considerations Section ............................5 3.5. IANA Considerations Section ................................6 3.5.1. Documents that Create a New Name Space ..............6 3.5.2. Documents that Require Assignments in Existing Namespace(s) ...............................7 3.5.3. Documents with No IANA Requests .....................8 3.6. References Sections ........................................8 3.7. Copyright Notices ..........................................9 3.8. Intellectual Property Section .............................10 4. SMIv2 Usage Guidelines .........................................10 4.1. Module Names ..............................................10 4.2. Descriptors, TC Names, and Labels .........................10 4.3. Naming Hierarchy ..........................................11 4.4. IMPORTS Statement .........................................11 4.5. MODULE-IDENTITY Invocation ................................12 4.6. Textual Conventions and Object Definitions ................14
Top   ToC   RFC4181 - Page 2
           4.6.1. Usage of Data Types ................................14
                  4.6.1.1. INTEGER, Integer32, Gauge32, and
                           Unsigned32 ................................14
                  4.6.1.2. Counter32 and Counter64 ...................16
                  4.6.1.3. CounterBasedGauge64 .......................17
                  4.6.1.4. OCTET STRING ..............................17
                  4.6.1.5. OBJECT IDENTIFIER .........................18
                  4.6.1.6. The BITS Construct ........................19
                  4.6.1.7. IpAddress .................................19
                  4.6.1.8. TimeTicks .................................19
                  4.6.1.9. TruthValue ................................19
                  4.6.1.10. Other Data Types .........................19
           4.6.2. DESCRIPTION and REFERENCE Clauses ..................20
           4.6.3. DISPLAY-HINT Clause ................................21
           4.6.4. Conceptual Table Definitions .......................21
           4.6.5. OID Values Assigned to Objects .....................23
           4.6.6. OID Length Limitations and Table Indexing ..........24
      4.7. Notification Definitions ..................................24
      4.8. Compliance Statements .....................................25
           4.8.1. Note Regarding These Examples and RFC 2578 .........27
      4.9. Revisions to MIB Modules ..................................28
   5. Acknowledgments ................................................31
   6. Security Considerations ........................................32
   7. IANA Considerations ............................................32
   Appendix A:  MIB Review Checklist .................................33
   Appendix B:  Commonly Used Textual Conventions ....................34
   Appendix C:  Suggested Naming Conventions .........................36
   Appendix D:  Suggested OID Layout .................................37
   Normative References ..............................................38
   Informative References ............................................40
Top   ToC   RFC4181 - Page 3

1. Introduction

Some time ago, the IESG instituted a policy of requiring expert review of IETF standards-track specifications containing MIB modules. These reviews were established to ensure that such specifications follow established IETF documentation practices and that the MIB modules they contain meet certain generally accepted standards of quality, including (but not limited to) compliance with all syntactic and semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579] [RFC2580] that are applicable to "standard" MIB modules. The purpose of this memo is to document the guidelines that are followed in such reviews. Please note that the guidelines in this memo are not intended to alter requirements or prohibitions (in the sense of "MUST", "MUST NOT", "SHALL", or "SHALL NOT" as defined in RFC 2119 [RFC2119]) of existing BCPs or Internet Standards except where those requirements or prohibitions are ambiguous or contradictory. In the exceptional cases where ambiguities or contradictions exist, this memo documents the current generally accepted interpretation. In certain instances, the guidelines in this memo do alter recommendations (in the sense of "SHOULD", "SHOULD NOT", "RECOMMENDED", or "NOT RECOMMENDED" as defined in RFC 2119) of existing BCPs or Internet Standards. This has been done where practical experience has shown that the published recommendations are suboptimal. In addition, this memo provides guidelines for the selection of certain SMIv2 options (in the sense of "MAY" or "OPTIONAL" as defined in RFC 2119) in cases where there is a consensus on a preferred approach. Although some of the guidelines in this memo are not applicable to non-standards track or non-IETF MIB documents, authors and reviewers of those documents should consider using the ones that do apply. Reviewers and authors need to be aware that some of the guidelines in this memo do not apply to MIB modules that have been translated to SMIv2 from SMIv1 (STD 16) [RFC1155] [RFC1212] [RFC1215].

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL", when used in the guidelines in this memo, are to be interpreted as described in RFC 2119 [RFC2119]. The terms "MIB module" and "information module" are used interchangeably in this memo. As used here, both terms refer to any of the three types of information modules defined in Section 3 of RFC 2578 [RFC2578].
Top   ToC   RFC4181 - Page 4
   The term "standard", when it appears in quotes, is used in the same
   sense as in the SMIv2 documents [RFC2578] [RFC2579] [RFC2580].  In
   particular, it is used to refer to the requirements that those
   documents levy on "standard" modules or "standard" objects.

3. General Documentation Guidelines

In general, IETF standards-track specifications containing MIB modules are subject to the same requirements as IETF standards-track RFCs (see [RFC2223bis]), although there are some differences. In particular, since the version under review will be an Internet-Draft, the notices on the front page MUST comply with the requirements of http://www.ietf.org/ietf/1id-guidelines.txt and not with those of [RFC2223bis]. In addition, since the specification under review is expected to be submitted to the IESG, it MUST comply with certain requirements that do not necessarily apply to RFCs; see http://www.ietf.org/ID-Checklist.html for details. Section 4 of [RFC2223bis] lists the sections that may exist in an RFC. Sections from the abstract onward may also be present in an Internet-Draft; see http://www.ietf.org/ID-Checklist.html. The "body of memo" is always required, and in a MIB document MUST contain at least the following: o MIB boilerplate section o Narrative sections o Definitions section o Security Considerations section o IANA Considerations section o References section Section-by-section guidelines follow.

3.1. MIB Boilerplate Section

This section MUST contain a verbatim copy of the latest approved Internet-Standard Management Framework boilerplate, which is available on-line at http://www.ops.ietf.org/mib-boilerplate.html.
Top   ToC   RFC4181 - Page 5

3.2. Narrative Sections

The narrative part MUST include an overview section that describes the scope and field of application of the MIB modules defined by the specification and that specifies the relationship (if any) of these MIB modules to other standards, particularly to standards containing other MIB modules. The narrative part SHOULD include one or more sections to briefly describe the structure of the MIB modules defined in the specification. If the MIB modules defined by the specification import definitions from other MIB modules (except for those defined in the SMIv2 documents [RFC2578] [RFC2579] [RFC2580]) or are always implemented in conjunction with other MIB modules, then those facts MUST be noted in the overview section, as MUST any special interpretations of objects in other MIB modules. For instance, so-called media-specific MIB modules are always implemented in conjunction with the IF-MIB [RFC2863] and are REQUIRED to document how certain objects in the IF-MIB are used. In addition, media-specific MIB modules that rely on the ifStackTable [RFC2863] and the ifInvStackTable [RFC2864] to maintain information regarding configuration and multiplexing of interface sublayers MUST contain a description of the layering model.

3.3. Definitions Section

This section contains the MIB module(s) defined by the specification. These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579] [RFC2580]; SMIv1 [RFC1155] [RFC1212] [RFC1215] has "Not Recommended" status [RFC3410] and is no longer acceptable in IETF MIB modules. See Section 4 for guidelines on SMIv2 usage.

3.4. 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, writable 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 concerns 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;
Top   ToC   RFC4181 - Page 6
   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/vulnerabilities and then
   state/document the result of this evaluation.

3.5. IANA Considerations Section

In order to comply with IESG policy as set forth in http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is submitted to the IESG for publication MUST contain an IANA Considerations section. The requirements for this section vary depending what actions are required of the IANA.

3.5.1. Documents that Create a New Name Space

If an Internet-Draft defines a new name space that is to be administered by the IANA, then the document MUST include an IANA Considerations section conforming to the guidelines set forth in RFC 2434 [RFC2434] that specifies how the name space is to be administered. Name spaces defined by MIB documents generally consist of the range of values for some type (usually an enumerated INTEGER) defined by a TEXTUAL-CONVENTION (TC) or of a set of administratively-defined OBJECT IDENTIFIER (OID) values. In each case, the definitions are housed in stand-alone MIB modules that are maintained by the IANA. These IANA-maintained MIB modules are separate from the MIB modules defined in standards-track specifications so that new assignments can be made without having to republish a standards-track RFC. Examples of IANA-maintained MIB modules include the IANAifType-MIB (http://www.iana.org/assignments/ianaiftype-mib), which defines a name space used by the IF-MIB [RFC2863], and the IANA-RTPROTO-MIB (http://www.iana.org/assignments/ianaiprouteprotocol-mib), which defines a name space used by the IPMROUTE-STD-MIB [RFC2932]. The current practice for such cases is to include a detailed IANA Considerations section complying with RFC 2434 in the DESCRIPTION clause of the MODULE-IDENTITY invocation in each IANA-maintained MIB module and for the IANA Considerations section of the MIB document that defines the name spaces to refer to the URLs for the relevant modules. See RFC 2932 [RFC2932] for an example. This creates a chicken-and-egg problem for MIB documents that have not yet been published as RFCs because the relevant IANA-maintained MIB modules will not yet exist. The accepted way out of this dilemma is to include the initial content of each IANA-maintained MIB module in a non-normative section of the initial issue of the document that defines the name space; for an example, see [RFC1573], which
Top   ToC   RFC4181 - Page 7
   documents the initial version of the IANAifType-MIB.  That material
   is usually omitted from subsequent updates to the document since the
   IANA-maintained modules are then available on-line (cf. [RFC2863]).

   Reviewers of draft MIB documents to which these considerations apply
   MUST check that the IANA Considerations section proposed for
   publication in the RFC is present and contains pointers to the
   appropriate IANA-maintained MIB modules.  Reviewers of Internet
   Drafts that contain the proposed initial content of IANA-maintained
   MIB modules MUST also verify that the DESCRIPTION clauses of the
   MODULE-IDENTITY invocations contain an IANA Considerations section
   compliant with the guidelines in RFC 2434.

3.5.2. Documents that Require Assignments in Existing Namespace(s)

If an Internet-Draft requires the IANA to update an existing registry prior to publication as an RFC, then the IANA Considerations section in the draft MUST document that fact. MIB documents that contain the initial version of a MIB module will generally require that the IANA assign an OBJECT IDENTIFIER value for the MIB module's MODULE- IDENTITY value and possibly to make other assignments as well. Internet-Drafts containing such MIB modules MUST contain an IANA Considerations section that specifies the registries that are to be updated, the descriptors to which OBJECT IDENTIFIER values are being assigned, and the subtrees under which the values are to be allocated. The text SHOULD be crafted so that after publication it will serve to document the OBJECT IDENTIFIER assignments. For example, something along the following lines would be appropriate for an Internet-Draft containing a single MIB module with MODULE-IDENTITY descriptor powerEthernetMIB that is to be assigned a value under the 'mib-2' subtree: The MIB module in this document uses the following IANA-assigned OBJECT IDENTIFIER values recorded in the SMI Numbers registry: Descriptor OBJECT IDENTIFIER value ---------- ----------------------- powerEthernetMIB { mib-2 XXX } Editor's Note (to be removed prior to publication): the IANA is requested to assign a value for "XXX" under the 'mib-2' subtree and to record the assignment in the SMI Numbers registry. When the assignment has been made, the RFC Editor is asked to replace "XXX" (here and in the MIB module) with the assigned value and to remove this note.
Top   ToC   RFC4181 - Page 8
   Note well:  prior to official assignment by the IANA, a draft
   document MUST use placeholders (such as "XXX" above) rather than
   actual numbers.  See Section 4.5 for an example of how this is done
   in a draft MIB module.

3.5.3. Documents with No IANA Requests

If an Internet-Draft makes no requests of the IANA, then that fact MUST be documented in the IANA Considerations section. When an Internet-Draft contains an update of a previously published MIB module, it typically will not require any action on the part of the IANA, but it may inherit an IANA Considerations section documenting existing assignments from the RFC that contains the previous version of the MIB module. In such cases, the draft MUST contain a note (to be removed prior to publication) explicitly indicating that nothing is required from the IANA. For example, a draft that contains an updated version of the POWER-ETHERNET-MIB [RFC3621] might include an IANA Considerations section such as the following: The MIB module in this document uses the following IANA-assigned OBJECT IDENTIFIER values recorded in the SMI Numbers registry: Descriptor OBJECT IDENTIFIER value ---------- ----------------------- powerEthernetMIB { mib-2 105 } Editor's Note (to be removed prior to publication): this draft makes no additional requests of the IANA. If an Internet-Draft makes no requests of the IANA and there are no existing assignments to be documented, then suitable text for the draft would be something along the following lines: No IANA actions are required by this document.

3.6. References Sections

Section 4.7f of [RFC2223bis] specifies the requirements for the references sections in an RFC; http://www.ietf.org/ID-Checklist.html imposes the same requirements on Internet-Drafts. In particular, there MUST be separate lists of normative and informative references, each in a separate section. The style SHOULD follow that of recently published RFCs. The standard MIB boilerplate available at http://www.ops.ietf.org/mib-boilerplate.html includes lists of normative and informative references that MUST appear in all IETF
Top   ToC   RFC4181 - Page 9
   specifications that contain MIB modules.  If items from other MIB
   modules appear in an IMPORTS statement in the Definitions section,
   then the specifications containing those MIB modules MUST be included
   in the list of normative references.  When items are imported from an
   IANA-maintained MIB module, the corresponding normative reference
   SHALL point to the on-line version of that MIB module.  It is the
   policy of the RFC Editor that all references must be cited in the
   text; such citations MUST appear in the overview section where
   documents containing imported definitions (other than those already
   mentioned in the MIB boilerplate) are required to be mentioned (cf.
   Section 3.2).

   In general, each normative reference SHOULD point to the most recent
   version of the specification in question.

3.7. Copyright Notices

IETF MIB documents MUST contain the copyright notices and disclaimer specified in Sections 5.4 and 5.5 of RFC 3978 [RFC3978]. 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 at: http://www.ietf.org/copyrights/ianamib.html." -- RFC Ed.: replace yyyy with actual RFC number & remove this note
Top   ToC   RFC4181 - Page 10
   In each case, the current year is to be inserted in place of the word
   "date".

3.8. Intellectual Property Section

Section 5 of RFC 3979 [RFC3979] contains a notice regarding intellectual property rights or other rights that must appear in all IETF RFCs. A verbatim copy of that notice SHOULD appear in every IETF MIB document.


(page 10 continued on part 2)

Next Section