Tech-invite3GPPspaceIETF RFCsSIP
9190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
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 3 of 3 – Pages 31 to 42
First   Prev   None

Top   ToC   RFC4181 - Page 31   prevText

5. Acknowledgments

Most of the material on usage of data types was based on input provided by Bert Wijnen with assistance from Keith McCloghrie, David T. Perkins, and Juergen Schoenwaelder. Much of the other material on SMIv2 usage was taken from an unpublished guide for MIB authors and reviewers by Juergen Schoenwaelder. Some of the recommendations in these guidelines are based on material drawn from the on-line SMIv2 errata list at http://www.ibr.cs.tu-bs.de/ietf/smi-errata/. Thanks to Frank Strauss and Juergen Schoenwaelder for maintaining that list and to the contributors who supplied the material for that list. Finally, thanks are due to the following individuals whose comments on earlier versions of this memo contained many valuable suggestions for additions, clarifications, and corrections: Andy Bierman, Bob Braden, Michelle Cotton, David Harrington, Harrie Hazewinkel, Dinakaran Joseph, Michael Kirkham, Keith McCloghrie, David T. Perkins, Randy Presuhn, Dan Romascanu, Juergen Schoenwaelder, Frank Strauss, Dave Thaler, and Bert Wijnen.
Top   ToC   RFC4181 - Page 32

6. Security Considerations

Implementation and deployment of a MIB module in a system may result in security risks that would not otherwise exist. It is important for authors and reviewers of documents that define MIB modules to ensure that those documents fully comply with the guidelines in http://www.ops.ietf.org/mib-security.html so that all such risks are adequately disclosed.

7. IANA Considerations

This document affects the IANA to the extent that it describes what is required to be present in the IANA Considerations section of a MIB document, but it does not require that the IANA update any existing registry or create any new registry.
Top   ToC   RFC4181 - Page 33

Appendix A: MIB Review Checklist

The purpose of a MIB review is to review the MIB module both for technical correctness and for adherence to IETF documentation requirements. The following checklist may be helpful when reviewing a draft document: 1.) I-D Boilerplate -- verify that the draft contains the required Internet-Draft boilerplate (see http://www.ietf.org/ietf/1id- guidelines.txt), including the appropriate statement to permit publication as an RFC, and that I-D boilerplate does not contain references or section numbers. 2.) Abstract -- verify that the abstract does not contain references, that it does not have a section number, and that its content follows the guidelines in http://www.ietf.org/ietf/1id-guidelines.txt. 3.) MIB Boilerplate -- verify that the draft contains the latest approved SNMP Network Management Framework boilerplate from the OPS area web site (http://www.ops.ietf.org/mib-boilerplate.html). 4.) Security Considerations Section -- verify that the draft uses the latest approved template from the OPS area web site (http://www.ops.ietf.org/mib-security.html) and that the guidelines therein have been followed. 5.) IANA Considerations Section -- this section must always be present. If the draft requires no action from the IANA, ensure that this is explicitly noted. If the draft requires OID values to be assigned, ensure that the IANA Considerations section contains the information specified in Section 3.5 of these guidelines. If the draft contains the initial version of an IANA-maintained module, verify that the MODULE-IDENTITY invocation contains maintenance instructions that comply with the requirements in RFC 2434. In the latter case, the IANA Considerations section that will appear in the RFC MUST contain a pointer to the actual IANA-maintained module. 6.) References -- verify that the references are properly divided between normative and informative references, that RFC 2119 is included as a normative reference if the terminology defined therein is used in the document, that all references required by the boilerplate are present, that all MIB modules containing imported items are cited as normative references, and that all citations point to the most current RFCs unless there is a valid reason to do otherwise (for example, it is OK to include an informative reference to a previous version of a specification to help explain a feature included for backward compatibility).
Top   ToC   RFC4181 - Page 34
   7.) Copyright Notices -- verify that the draft contains an
   abbreviated copyright notice in the DESCRIPTION clause of each
   MODULE-IDENTITY invocation and that it contains the full copyright
   notice and disclaimer specified in Sections 5.4 and 5.5 of RFC 3978
   at the end of the document.  Make sure that the correct year is used
   in all copyright dates.

   8.) IPR Notice -- if the draft does not contains a verbatim copy of
   the IPR notice specified in Section 5 of RFC 3979, recommend that the
   IPR notice be included.

   9.) Other Issues -- check for any issues mentioned in
   http://www.ietf.org/ID-Checklist.html that are not covered elsewhere.

   10.) Technical Content -- review the actual technical content for
   compliance with the guidelines in this document.  The use of a MIB
   compiler is recommended when checking for syntax errors; see
   http://www.ops.ietf.org/mib-review-tools.html for more information.
   Checking for correct syntax, however, is only part of the job.  It is
   just as important to actually read the MIB document from the point of
   view of a potential implementor.  It is particularly important to
   check that DESCRIPTION clauses are sufficiently clear and unambiguous
   to allow interoperable implementations to be created.

Appendix B: Commonly Used Textual Conventions

The following TCs are defined in SNMPv2-TC [RFC2579]: DisplayString OCTET STRING (SIZE (0..255)) PhysAddress OCTET STRING MacAddress OCTET STRING (SIZE (6)) TruthValue enumerated INTEGER TestAndIncr INTEGER (0..2147483647) AutonomousType OBJECT IDENTIFIER VariablePointer OBJECT IDENTIFIER RowPointer OBJECT IDENTIFIER RowStatus enumerated INTEGER TimeStamp TimeTicks TimeInterval INTEGER (0..2147483647) DateAndTime OCTET STRING (SIZE (8 | 11)) StorageType enumerated INTEGER TDomain OBJECT IDENTIFIER TAddress OCTET STRING (SIZE (1..255)) Note 1. InstancePointer is obsolete and MUST NOT be used. Note 2. DisplayString does not support internationalized text. It MUST NOT be used for objects that are required to hold
Top   ToC   RFC4181 - Page 35
            internationalized text (which is always the case if the
            object is intended for use by humans [RFC2277]).  Designers
            SHOULD consider using SnmpAdminString, Utf8String, or
            LongUtf8String for such objects.

   Note 3.  TDomain and TAddress SHOULD NOT be used in new MIB modules.
            The TransportDomain, TransportAddressType, and
            TransportAddress TCs (defined in TRANSPORT-ADDRESS-MIB
            [RFC3419]) SHOULD be used instead.

   The following TC is defined in SNMP-FRAMEWORK-MIB [RFC3411]:

   SnmpAdminString             OCTET STRING (SIZE (0..255))

   The following TCs are defined in SYSAPPL-MIB [RFC2287]:

   Utf8String                  OCTET STRING (SIZE (0..255))
   LongUtf8String              OCTET STRING (SIZE (0..1024))

   The following TCs are defined in INET-ADDRESS-MIB [RFC4001]:

   InetAddressType             enumerated INTEGER
   InetAddress                 OCTET STRING (SIZE (0..255))
   InetAddressPrefixLength     Unsigned32 (0..2040)
   InetPortNumber              Unsigned32 (0..65535))
   InetAutonomousSystemNumber  Unsigned32
   InetScopeType               enumerated INTEGER
   InetZoneIndex               Unsigned32
   InetVersion                 enumerated INTEGER

   The following TCs are defined in TRANSPORT-ADDRESS-MIB [RFC3419]:

   TransportDomain             OBJECT IDENTIFIER
   TransportAddressType        enumerated INTEGER
   TransportAddress            OCTET STRING (SIZE (0..255))

   The following TC is defined in RMON2-MIB [RFC2021]:

   ZeroBasedCounter32          Gauge32

   The following TCs are defined in HCNUM-TC [RFC2856]:

   ZeroBasedCounter64          Counter64
   CounterBasedGauge64         Counter64

   The following TCs are defined in IF-MIB [RFC2863]:

   InterfaceIndex              Integer32 (1..2147483647)
Top   ToC   RFC4181 - Page 36
   InterfaceIndexOrZero        Integer32 (0..2147483647)

   The following TCs are defined in ENTITY-MIB [RFC4133]:

   PhysicalIndex               Integer32 (1..2147483647)
   PhysicalIndexOrZero         Integer32 (0..2147483647)

   The following TCs are defined in PerfHist-TC-MIB [RFC3593]:

   PerfCurrentCount            Gauge32
   PerfIntervalCount           Gauge32
   PerfTotalCount              Gauge32

   The following TCs are defined in HC-PerfHist-TC-MIB [RFC3705]:

   HCPerfValidIntervals        Integer32 (0..96)
   HCPerfInvalidIntervals      Integer32 (0..96)
   HCPerfTimeElapsed           Integer32 (0..86399)
   HCPerfIntervalThreshold     Unsigned32 (0..900)
   HCPerfCurrentCount          Counter64
   HCPerfIntervalCount         Counter64
   HCPerfTotalCount            Counter64

Appendix C: Suggested Naming Conventions

Authors and reviewers of IETF MIB modules have often found the following naming conventions to be helpful in the past, and authors of new IETF MIB modules are urged to consider following them. - 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. - The descriptor associated with the MODULE-IDENTITY invocation should be of the form xxxMIB, xxxMib, or xxxMibModule, where xxx is a mixed-case version of XXX starting with a lowercase letter and without any hyphens. For example, the OPT-IF-MIB uses the prefix optIf, and the descriptor associated with its MODULE-IDENTITY invocation is optIfMibModule. - Other descriptors within the MIB module should start with the same prefix xxx. OPT-IF-MIB uses the prefix optIf for all descriptors.
Top   ToC   RFC4181 - Page 37
   - Names of TCs that are specific to the MIB module and names of
     SEQUENCE types that are used in conceptual table definitions should
     start with a prefix Xxx that is the same as xxx but with the
     initial letter changed to uppercase.  OPT-IF-MIB uses the prefix
     OptIf on the names of TCs and SEQUENCE types.

   - The descriptor associated with a conceptual table should be of the
     form xxxZzzTable; the descriptor associated with the corresponding
     conceptual row should be of the form xxxZzzEntry; the name of the
     associated SEQUENCE type should be of the form XxxZzzEntry; and the
     descriptors associated with the subordinate columnar objects should
     be of the form xxxZzzSomeotherName.  An example from the OPT-IF-MIB
     is the OTMn table.  The descriptor of the table object is
     optIfOTMnTable, the descriptor of the row object is optIfOTMnEntry,
     the name of the associated SEQUENCE type is OptIfOTMnEntry, and the
     descriptors of the columnar objects are optIfOTMnOrder,
     optIfOTMnReduced, optIfOTMnBitRates, optIfOTMnInterfaceType,
     optIfOTMnTcmMax, and optIfOTMnOpticalReach.

   - When abbreviations are used, then they should be used consistently.
     Inconsistent usage such as

       xxxYyyDestAddr
       xxxZzzDstAddr

     should be avoided.

Appendix D: Suggested OID Layout

As noted in RFC 2578 Section 5.6, it is common practice to use the value of the MODULE-IDENTITY invocation as a subtree under which other OBJECT IDENTIFIER values assigned within the module are defined. That, of course, leaves open the question of how OIDs are assigned within that subtree. One assignment scheme that has gained favor -- and that is RECOMMENDED unless there is a specific reason not use it -- is to have three separate branches immediately below the MODULE-IDENTITY value dedicated (respectively) to notification definitions, object definitions, and conformance definitions, and to further subdivide the conformance branch into separate sub-branches for compliance statements and object/notification groups. This structure is illustrated below, with naming conventions following those outlined in Appendix C. The numbers in parentheses are the sub-identifiers assigned to the branches.
Top   ToC   RFC4181 - Page 38
         xxxMIB
         |
         +-- xxxNotifications(0)
         +-- xxxObjects(1)
         +-- xxxConformance(2)
             |
             +-- xxxCompliances(1)
             +-- xxxGroups(2)

   When using this scheme, notification definition values are assigned
   immediately below the xxxNotifications node.  This ensures that each
   OID assigned to a notification definition has a next-to-last sub-
   identifier of zero, which is REQUIRED by Section 4.7 above.  The
   other sub-branches may have additional sub-structure, but none beyond
   that specified in Section 4.6.5 above is actually required.

   One example of a MIB module whose OID assignments follow this scheme
   is the POWER-ETHERNET-MIB [RFC3621].

Normative References

[RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Conformance Statements for SMIv2", STD 58, RFC 2580, April 1999. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirements Levels", BCP 14, RFC 2119, March 1997. [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB", RFC 2863, June 2000. [RFC2864] McCloghrie, K. and G. Hanson, "The Inverted Stack Table Extension to the Interfaces Group MIB", RFC 2864, June 2000. [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.
Top   ToC   RFC4181 - Page 39
   [RFC3978]    Bradner, S., "IETF Rights in Contributions", BCP 78, RFC
                3978, March 2005.

   [RFC3979]    Bradner, S., "Intellectual Property Rights in IETF
                Technology", BCP 79, RFC 3979, March 2005.

   [RFC4001]    Daniele, M., Haberman, B., Routhier, S., and J.
                Schoenwaelder, "Textual Conventions for Internet Network
                Addresses", RFC 4001, February 2005.

   [RFC3593]    Tesink, K., "Textual Conventions for MIB Modules Using
                Performance History Based on 15 Minute Intervals", RFC
                3593, September 2003.

   [RFC3705]    Ray, B. and R. Abbi, "High Capacity Textual Conventions
                for MIB Modules Using Performance History Based on 15
                Minute Intervals", RFC 3705, February 2004.

   [RFC2021]    Waldbusser, S., "Remote Network Monitoring Management
                Information Base Version 2 using SMIv2", RFC 2021,
                January 1997.

   [RFC2856]    Bierman, A., McCloghrie, K., and R. Presuhn, "Textual
                Conventions for Additional High Capacity Data Types",
                RFC 2856, June 2000.

   [RFC3411]    Harrington, D., Presuhn, R., and B. Wijnen, "An
                Architecture for Describing Simple Network Management
                Protocol (SNMP) Management Frameworks", STD 62, RFC
                3411, December 2002.

   [RFC2287]    Krupczak, C. and J. Saperia, "Definitions of
                System-Level Managed Objects for Applications", RFC
                2287, February 1998.

   [RFC3418]    Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S.
                Waldbusser, "Management Information Base (MIB) for the
                Simple Network Management Protocol (SNMP)", STD 62, RFC
                3418, December 2002.

   [RFC3416]    Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S.
                Waldbusser, "Protocol Operations for the Simple Network
                Management Protocol (SNMP)", STD 62, RFC 3416, December
                2002.

   [RFC4133]    Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)",
                RFC 4133, August 2005.
Top   ToC   RFC4181 - Page 40
   [RFC2277]    Alvestrand, H., "IETF Policy on Character Sets and
                Languages", BCP 18, RFC 2277, January 1998.

   [RFC3419]    Daniele, M. and J. Schoenwaelder, "Textual Conventions
                for Transport Addresses", RFC 3419, December 2002.

Informative References

[RFC1155] Rose, M. and K. McCloghrie, "Structure and Identification of Management Information for TCP/IP-based Internets", STD 16, RFC 1155, May 1990. [RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 16, RFC 1212, March 1991. [RFC1215] Rose, M., "A Convention for Defining Traps for use with the SNMP", RFC 1215, March 1991. [RFC2223bis] Reynolds, J. and R. Braden, "Instructions to Request for Comments (RFC) Authors", Work in Progress, August 2004. [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, "Introduction and Applicability Statements for Internet-Standard Management Framework", RFC 3410, December 2002. [RFC2932] McCloghrie, K., Farinacci, D., and D. Thaler, "IPv4 Multicast Routing MIB", RFC 2932, October 2000. [RFC1573] McCloghrie, K. and F. Kastenholz, "Evolution of the Interfaces Group of MIB-II", RFC 1573, January 1994. [RFC3621] Berger, A. and D. Romascanu, "Power Ethernet MIB", RFC 3621, December 2003. [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, "Coexistence between Version 1, Version 2, and Version 3 of the Internet-standard Network Management Framework", BCP 74, RFC 3584, August 2003. [RFC2108] de Graaf, K., Romascanu, D., McMaster, D., and K. McCloghrie, "Definitions of Managed Objects for IEEE 802.3 Repeater Devices using SMIv2", RFC 2108, February 1997. [RFC3289] Baker, F., Chan, K., and A. Smith, "Management Information Base for the Differentiated Services Architecture", RFC 3289, May 2002.
Top   ToC   RFC4181 - Page 41
   [RFC1213]    McCloghrie, K. and M. Rose, "Management Information Base
                for Network Management of TCP/IP-based internets - MIB-
                II", STD 17, RFC 1213, March 1991.

   [RFC1595]    Brown, T. and K. Tesink, "Definitions of Managed Objects
                for the SONET/SDH Interface Type", RFC 1595, March 1994.

   [RFC2558]    Tesink, K., "Definitions of Managed Objects for the
                SONET/SDH Interface Type", RFC 2558, March 1999.

   [RFC3591]    Lam, H-K., Stewart, M., and A. Huynh, "Definitions of
                Managed Objects for the Optical Interface Type", RFC
                3591, September 2003.

Editor's Address

C. M. Heard 158 South Madison Ave. #207 Pasadena, CA 91101-2569 USA Phone: +1 626 795 5311 EMail: heard@pobox.com
Top   ToC   RFC4181 - Page 42
Full Copyright Statement

   Copyright (C) The Internet Society (2005).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at ietf-
   ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.