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

           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

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].

   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.

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;

   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

   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.

   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

   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

   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.