[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Draft MIB Review Guidelines
Colleagues,
Back in August, when I stirred up the controversy over whether
TCs should get to remove syntactic constraints of base types,
Bert Wijnen asked for a volunteer to write a CLR document.
That volunteer turned out to be me. The project ended up
morphing into a MIB review guidelines document, which turned
out to be quite a bit harder to organize that I thought it
would be. I've been struggling to get it written ever since.
I finally have a draft that is ready for people to poke sticks
at. It's far from finished, is probably inadequately
proofread, and most certainly reflects my own idiosyncratic
prejudices. Still, I'd still appreciate any comments that you
could make, especially if you have suggestions on what
additional stuff should go in it, what should get cut out, and
what needs to be reorganized. [I can already see one thing I
missed: something needs to be said about specifying persistency
of dynamically created rows across reboots.] The hope-for is
that with your help I can cobble together something that would
be suitable for publication as a BCP. Since it's way past the
I-D deadline, I'm attaching the draft (such as it is) to
this e-mail.
Thanks in advance for your help. Any comments, especially
negative ones, will be welcome.
I will be away on travel until after Thanksgiving and
consequently in only sporadic e-mail contact, so a slow
response does not mean that I'm ignoring you.
Mike
INTERNET DRAFT C. M. Heard, Editor
Consultant
November 2002
Guidelines for MIB Authors and Reviewers
<draft-ops-mib-review-guidelines-00pre0.txt>
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract
This memo provides guidelines for authors and reviewers of IETF
specifications containing MIB modules.
OPS Area Expires May 2003 [Page 1]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
1. Introduction
Some time ago the IESG instituted a policy of requiring OPS area
review of all IETF 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 or exceed certain generally accepted standards of
quality, including (but not limited to) compliance with all syntactic
and semantic requirements of SMIv2 [RFC2578] [RFC2579] [RFC2580]
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.
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].
OPS Area Expires May 2003 [Page 2]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
3. General Documentation Guidelines
In general, IETF specifications containing MIB modules MUST conform
to the requirements for IETF RFCs documented in [RFC2223bis].
Because the version under review will be an Internet Draft, the
notices on the front page will comply with the requirements of
http://www.ietf.org/ietf/1id-guidelines.txt and not with those of
[RFC2223bis]. The rest of the requirements in [RFC2223bis] will,
however, apply.
Section 4 of [RFC2223bis] lists the sections that may exist in an
RFC. The "body of memo" part of an RFC in general contains multiple
sections, and in a MIB document MUST contain at least the following:
o MIB boilerplate section
o Narrative sections
o Definitions section
o Intellectual Property 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 MAY include section that
briefly describes the structure of the MIB modules defined in the
specification.
If the MIB modules defined by the specification are always
implemented in conjunction with other MIB modules, then that fact
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
OPS Area Expires May 2003 [Page 3]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
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 modules defined by the specification.
These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579]
[RFC2580]; SMIv1 [RFC1155] [RFC1212] [RFC1215] has "Not Recommended"
status [RFC2570bis] and is no longer acceptable in IETF MIB modules.
See Section 4 for guidelines on SMIv2 usage.
3.4. Intellectual Property Section
Bullets (A) and (B) in Section 10.4 of RFC 2026 [RFC2026] specify
that certain notices regarding intellectual or other property rights
appear in all standards-track RFCs. Verbatim copies of these so-
called IPR notices MUST appear in each MIB document that is destined
for the standards track.
3.5. References Sections
Section 4.8 of [RFC2223bis] specifies the requirements for the
references sections. In particular, there MUST be separate lists of
normative and informative references, each in its own numbered
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
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 other MIB module MUST be
included in the list of normative references.
In general, each normative reference SHOULD point to the most recent
version of the specification in question.
3.6. Security Considerations Section
In order to comply with Section 4.9 of [RFC2223bis], each
specification that defines one or more MIB modules MUST contain a
section that discusses security considerations relevant to those MIB
modules. This section MUST be patterned after the latest approved
template available at http://www.ops.ietf.org/security.html, and all
MIB objects that contain sensitive information MUST be explicitly
listed by name. Writeable MIB objects that could be especially
OPS Area Expires May 2003 [Page 4]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
disruptive if abused MUST also be explicitly listed by name.
3.7. IANA Considerations Section
In order to comply with Section 4.10 of [RFC2223bis], each
specification that defines a name space of assigned numbers MUST
include an IANA Considerations section conforming to the guidelines
set forth in [RFC2434] specifying how that 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 IANA. These
IANA-maintained MIB modules are kept 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
defined 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 [RFC2434] in the DESCRIPTION
clause of the MODULE-IDENTITY statement in each IANA-maintained MIB
module and for the IANA Considerations section of the MIB document
that defines the name space 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 the proposed IANA-maintained MIB
modules in appendices of the Internet Draft with a note to the RFC
Editor that those appendices are to be removed upon publication, when
the IANA-maintained modules go on-line.
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 [RFC2434].
OPS Area Expires May 2003 [Page 5]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
3.8. Copyright Notices
IETF MIB documents MUST contain the copyright notices specified in
Sections 4.3 and 4.12 of RFC 2223bis [RFC2223bis] and Section 10.4
Bullet (C) of RFC 2026 [RFC2026]. Authors and reviewers MUST check
make sure that the correct year is inserted into these notices.
OPS Area Expires May 2003 [Page 6]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
4. SMIv2 Usage Guidelines
In general, MIB modules in IETF standards-track specifications MUST
comply with all syntactic and semantic requirements of SMIv2
[RFC2578] [RFC2579] [RFC2580] that apply to "standard" MIB modules
and except as noted below SHOULD comply with SMIv2 recommendations.
The guidelines in this section are intended to supplement the SMIv2
documents in the following ways:
o to document the current generally accepted interpretation when
those documents contain ambiguities or contradictions;
o to update recommendations in those documents that have been shown
by practical experience to be out-of-date or otherwise suboptimal;
o to provide guidance in selection of SMIv2 options in cases where
there is a consensus on a preferred approach.
4.1. Module Names
RFC 2578 Section 3 specifies the rules for module names. Note in
particular that names of "standard" modules MUST be unique, MUST
follow the syntax rules in RFC 2578 Section 3, and MUST NOT be
changed when a MIB module is revised (see also RFC 2578 Section 10).
4.2. Descriptors and Labels
RFC 2578, Sections 3.1, 7.1.1, and 7.1.4, and RFC 2579, Section 3
recommend that descriptors associated with macro invocations and
labels associated with enumerated INTEGER and BITS values be no
longer than 32 characters, but require that they be no longer than 64
characters.
Restricting descriptors and labels to 32 characters often conflicts
with the recommendation that they be mnemonic and (for descriptors)
the requirement that they be unique (see RFC 2578, Section 3.1). The
SMIv2 recommendation to limit names to 32 characters SHOULD be set
aside when it comes in conflict with these considerations.
Note that violations of the 64-character limit MUST NOT be ignored;
they MUST be treated as errors.
4.3. Naming Hierarchy
RFC 2578 Section 4 describes the object identifier subtrees that are
maintained by IANA and specifies the usages for those subtrees. In
particular, the mgmt subtree { iso 3 6 1 2 } is used to identify
"standard" objects, while the experimental subtree { iso 3 6 1 3 } is
OPS Area Expires May 2003 [Page 7]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
used to identify objects that are under development in the IETF. It
is REQUIRED that objects be moved from the experimental subtree to
the mgmt subtree when a MIB module enters the standards track.
Experience has shown that is impractical objects from one subtree to
another once those objects have seen large-scale use in an
operational environment. Hence any object that is targeted for
deployment in an operational environment MUST NOT be registered under
the experimental subtree, irrespective of the standardization status
of that object. The experimental subtree should be used only for
objects that are intended for limited experimental deployment (such
objects are typically defined in Experimental RFCs).
Note: the term "object", as used here and in RFC 2578 Section 4, is
to be broadly interpreted as any construct that results in an OBJECT
IDENTIFIER registration. The list of such constructs is specified in
RFC 2578 Section 3.6.
4.4. IMPORTS Statement
RFC 2578 Section 3.2 specifies which symbols must be imported and
also lists certain pre-defined symbols that must not be imported.
The general requirement is that if an external symbol other than a
predefined ASN.1 type or the BITS construct is used, then it MUST be
mentioned in the module's IMPORTS statement. The words "external
object" in the first paragraph of this section may give the
impression that such symbols are limited to those that refer to
object definitions, but that is not the case, as subsequent
paragraphs should make clear.
Although exemptions to this general requirement are granted by RFC
2580 Sections 5.4.3 and 6.5.2 for names of objects appearing in the
OBJECT clause of a MODULE-COMPLIANCE macro invocation or in the
VARIATION clause of an AGENT-CAPABILITIES macro invocation, it is
nonetheless RECOMMENDED by these guidelines that such symbols be
included in the module's IMPORTS statement. There are two reasons
for this. One is that these special rules are somewhat obscure and
may not be implemented by all MIB compilers, especially since RFC
2580 has no analogous rules for names of notifications referenced by
a VARIATION clause nor for names of object groups or notification
groups referenced by a MANDATORY-GROUPS clause, a GROUP clause, or a
SUPPORTS clause. The other reason is that including these items
helps to make dependencies on other modules obvious from looking at
the IMPORTS statement.
Finally, even though it is not forbidden by the SMI, it is considered
poor style to import symbols that are not used, and "standard" MIB
OPS Area Expires May 2003 [Page 8]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
modules SHOULD NOT do so.
4.5. MODULE-IDENTITY Invocation
RFC 2578 Section 3 requires that all SMIv2 MIB modules start with
exactly one invocation of the MODULE-IDENTITY macro. This invocation
MUST appear immediately after the IMPORTs statement.
RFC 2578 Section 5 describes how the various clauses are used. The
following additional guidelines apply to all MIB modules over which
the IETF has change control:
- If the module was developed by an IETF working group, then the
ORGANIZATION clause MUST provide the full name of the working
group, and the CONTACT-INFO clause SHOULD provide a pointer to the
working groups's web page at www.ietf.org.
- A REVISION clause MUST be present for each revision of the MIB
module, and the UTC time of the most recent REVISION clause MUST
match that of the LAST-UPDATED clause. The DESCRIPTION clause
associated with each revision MUST state in which RFC that revision
appeared and SHOULD provide a list of all significant changes.
- The value assigned to the MODULE-IDENTITY descriptor MUST be unique
and SHOULD reside under the mgmt subtree. Most often it will be an
IANA-assigned value directly under mib-2, although for media-
specific MIB modules that extend the IF-MIB [RFC2864] it is
customary to use an IANA-assigned value under transmission. It is
also acceptable for a working group to make its own assignments
from a subtree delegated to it by IANA, provided that adequate
controls are in place to ensure that such assignments are unique.
While a MIB module is under development, the RFC number in which it
will eventually be published is usually unknown and must be filled in
by the RFC Editor prior to publication. An appropriate form for the
REVISION clause applying to a version under under development would
be something along the following lines:
REVISION "200205022034Z" -- May 2, 2002
DESCRIPTION "Initial version, published as RFC yyyy."
-- RFC Ed.: replace yyyy with actual RFC number & remove this notice
Note that after RFC publication a REVISION clause is present only for
published versions of a MIB module and not for interim versions that
existed only as Internet Drafts. Thus, a draft version of a MIB
module MUST contain just one REVISION clause that covers all changes
since the last published version (if any).
OPS Area Expires May 2003 [Page 9]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
When the initial version of a MIB module is under development, the
value assigned to the MODULE-IDENTITY descriptor will be unknown if
an IANA-assigned value is used, because the assignment is made just
prior to publication as an RFC. The accepted form for the MODULE-
IDENTITY statement in draft versions of such a module is something
along the following lines:
<descriptor> MODULE-IDENTITY
[ ... ]
::= { <subtree> XXX }
-- RFC Ed.: replace XXX with IANA-assigned number & remove this notice
where <descriptor> is whatever descriptor has been selected for the
module and <subtree> is the subtree under which the module is to be
registered (e.g., mib-2 or transmission). Note that XXX must be
(temporarily) replaced by a number in order for the module to
compile.
4.6. Textual Conventions and Object Definitions
4.6.1. Usage of Data Types
4.6.1.1. INTEGER, Integer32, Gauge32, and Unsigned32
The following guidelines apply when selecting a 32-bit integer data
type for an object definition or a textual convention:
- For integer-valued enumerations:
- INTEGER is REQUIRED;
- Integer32, Unsigned32, and Gauge32 MUST NOT be used.
- 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..2147483647 (inclusive), then:
- Unsigned32 or Gauge32 is RECOMMENDED;
- INTEGER or Integer32 is acceptable.
- If the value range is between 0..4294967295 (inclusive) and the
underlying value of the information being modelled may increase
OPS Area Expires May 2003 [Page 10]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
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 the value range is between 0..4294967295 (inclusive) and the
underlying value of the information being modelled does not
increase above the maximum value or decrease below the minimum
value, then:
- Unsigned32 is RECOMMENDED;
- Gauge32 is acceptable;
- INTEGER and Integer32 MUST NOT be used.
All of the above is a direct translation the definitions in RFC 2578
Section 2 and the elaboration in RFC 2578 Sections 7.1.1, 7.1.7, and
7.1.11.
- For integer-valued objects that are to be used as an index column:
- Use of Unsigned32 or Gauge32 with a range that excludes 0 is
RECOMMENDED. If 0 is included in the range, then a good reason
MUST be specified.
- Integer32 or INTEGER with a non-negative range is acceptable.
Again, if 0 is included in the range, then a good reason MUST be
specified.
The above is a direct translation of the INDEX rules in RFC 2578
Section 7.7 up to and including bullet (1).
Note that INTEGER is a pre-defined ASN.1 type and MUST NOT be present
in the module's IMPORTS statement, whereas Integer32, Gauge32, and
Unsigned32 are defined by SNMPv2-SMI and MUST be imported from that
module if used.
4.6.1.2. Counter32 and Counter64
Counter32 and Counter64 have special semantics as defined in RFC 2578
Sections 7.1.6 and 7.1.10 respectively. Object definitions MUST (and
textual conventions SHOULD) respect these semantics. That means:
- It is OK to use Counter32/64 for counters that can reset themselves
on unusual/irregular events (e.g., counters maintained on a line
card are reset when the line card is reset), and it is not illegal
if their value after the reset happens to be zero (i.e., it does
not have to be non-zero). So, "counters that can reset to zero" is
OPS Area Expires May 2003 [Page 11]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
not automatically wrong for Counter32/64. However, if it is
possible for such resets to occur, then a discontinuity indicator
object SHOULD be provided to indicate when the last such reset
occurred.
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that on a discontinuity, the counter
MUST reset to zero.
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement MUST reset at any specific time/event
(e.g. midnight).
- It is NOT OK for one manager to request the agent to reset the
value of counter(s) to zero, and Counter32/64 is the wrong syntax
for "counters" which regularly reset themselves to zero. (For the
latter it is better to define or use textual conventions such as
those in RFC 2493 [RFC2493]).
There also exist closely-related textual conventions
ZeroBasedCounter32 and ZeroBasedCounter64 defined in RMON2-MIB
[RFC2021] and HCNUM-TC [RFC2856], respectively.
The only difference between ZeroBasedCounter32/64 TCs and
Counter32/64 is their starting value; at time=X, where X is their
minimum-wrap-time after they were created, the behaviour of
ZeroBasedCounter32/64 becomes exactly the same as Counter32/64.
Thus, the preceeding paragraphs/rules apply not only to Counter32/64,
but also to ZeroBasedCounter32/64 TCs.
4.6.1.3. CounterBasedGauge64
SMIv2 unfortunately does not provide 64-bit integer base types. In
order to make up for this omission, the CounterBasedGauge64 textual
convention is defined in HCNUM-TC [RFC2856]. This TC uses Counter64
as a base type, but discards the special counter semantics, which is
allowed under the generally accepted interpretation of RFC 2579
Section 3.3. It does inherit all the syntactic restrictions of that
type, which means that it MUST NOT be subtyped and that that objects
defined with it MUST NOT appear in an INDEX clause, MUST NOT have a
DEFVAL clause, and MUST have a MAX-ACCESS of read-only or
accessible-for-notify.
This TC SHOULD be used for object definitions that require a 64-bit
unsigned data type with no special semantics. If a 64-bit unsigned
data type with additional semantic refinements is needed, then an
additional TC based on Counter64 MUST be defined, since one TC cannot
refine another (c.f. RFC 2579 Section 3.5).
OPS Area Expires May 2003 [Page 12]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
4.6.1.4. IpAddress
The IpAddress type described in RFC 2578 Section 7.1.5 SHOULD NOT be
used in new MIB modules. The InetAddress/InetAddressType textual
conventions [RFC3291] should be used instead.
4.6.1.5. Other Types
[ add sections here on TimeTicks, OCTET STRING, OBJECT IDENTIFIER,
and the BITS construct, if needed ... opinions are solicited ]
4.6.2. OBJECT IDENTIFIER Values Assigned to Objects
[ reminder that last sub-OID must not be zero (RFC 2578 Section 7.10) ]
4.7. Notification Definitions
4.8. Compliance Statements
OPS Area Expires May 2003 [Page 13]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
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.) 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).
2.) IPR Notices -- verify that the draft contains verbatim copies of
the IPR notices specified by bullets (A) and (B) in Section 10.4 of
RFC 2026.
3.) References -- verify that the references are properly divided
between normative and informative references, that all references
required by the boilerplace are present, that all MIB modules
containing imported items are cited, and that all citations point to
the most current RFCs.
4.) Security Considerations Section -- verify that the draft used the
latest approved template from the OPS area web site
(http://www.ops.ietf.org/security.html) and that the guidelines
therein were followed.
5.) IANA Considerations Section -- if the draft contains the initial
version of an IANA-maintained module, verify that the MODULE-IDENTITY
contains maintanance instructions that comply with RFC 2434. Note
that module itself must be in an appendix that will disappear after
publication and that the IANA Considerations section that will appear
in the RFC must contain a pointer to that module.
6.) Copyrights -- verify that the draft contains a copyright notice
on the front page and there is a full copyright notice section with
text matching that in recently published RFCs. Make sure that the
year is up-to-date in both places.
6.) MIB compilation -- verify that smicng and smilint set to maximum
complaint levels issue no errors or warnings (exception: warnings
for names longer than 32 characters may be ignored).
7.) Technical content -- review the actual technical for compliance
with the guidelines in this document.
OPS Area Expires May 2003 [Page 14]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
Appendix B: Using smilint to compile MIB modules
smilint is part of the open-source libsmi package maintained by Frank
Strauss of the Technical University of Braunschweig; see
http://www.ibr.cs.tu-bs.de/projects/libsmi/ for more information and
downloading instructions.
By default, the smilint program does only minimal checking, and in a
MIB review one generally wishes to run the program at maximum
complaint level. The following command line, valid under the Unix
Bourne shell, does that, and then discards all warnings about names
longer than 32 characters:
smilint -l 9 -s <module> 2>1 | \
grep -v 'name .* longer than 32 characters$'
An equivalent command line under the Unix C shell is:
smilint -l 9 -s <module> |& \
grep -v 'name .* longer than 32 characters$'
In both lines above, <module> is replaced with the file name of the
module being compiled. A full pathname is required unless it resides
in one of the standard MIB directories (see the program documentation
for more information).
There is a related utility called smidiff that is very useful when
checking whether updates to a previously-published MIB module conform
to the SMIv2 rules on revisions. Similar command line options are
recommended.
OPS Area Expires May 2003 [Page 15]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
Appendix C: Using SMICng to compile MIB modules
SMICng is a commercial program available from SNMPinfo; see
http://www.snmpinfo.com/ for more information.
As a rule, MIB modules are not compiled directly with SMICng but
rather are referenced by a SMICng include file, which mentions the
modules from which symbols are imported and contains any module-
specific compilation options. For the purposes of doing MIB reviews,
selecting maximally picky compilation switches is usually the right
thing to do. A sample include file (for the SONET-MIB [RFC2558]) is
shown below.
-- File: rfc2558.inc -- SONET-MIB
-- IMPORTS
#condInclude "rfc1902.inc" -- SNMPv2-SMI
#condInclude "rfc1903.inc" -- SNMPv2-TC
#condInclude "rfc1904.inc" -- SNMPv2-CONF
#condInclude "rfc2863.inc" -- IF-MIB
#condInclude "rfc2493.inc" -- PerfHist-TC-MIB
-- MIB module
#pushOpt
-- Add extra strict checking beyond that mandated by SMI
-- C - check size/range present
-- W - don't allow size/range for items in a sequence
-- H - strict ASN.1 for comments
-- 7 - restrict INTEGER values below 2G-1
-- R - check (in V1) that INDEX objs are read-only
-- S - require (in V2) that IMPORTS be specified for items in compliances
-- B - strong checking for size/range of items in index clause
-- 0B - act as BITS is builtin
#addOpt "C W H 7 R S B 0B"
-- Remove strict checking for benign practices permitted by SMI
-- 9 - no dup OID values with OVAs
-- 0M - check if index items used in VARIABLES or OBJECTS clause
#removeOpt "9 0M"
-- Remove relaxed checking beyond that forbidden by SMI
-- 4 - allow non-standard access for objects
-- 5 - allow 'optional' status
-- 6 - no check table, row, seq names
-- J - allow DEFVAL on Counters
-- K - allow (in v1) zero valued enums
-- U - allow underbars in names
-- L - allow (in v1) neg enum values
OPS Area Expires May 2003 [Page 16]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
-- 2 - allow (in v2) use of RFC 1442 types
-- 3 - allow (in v1) INDEX clause on objects
-- O - allow (in v2) hyphens in labels for enumerated values
-- P - allow (in v2) hyphens in descriptors(identifiers)
-- T - no check (in v2) of proper access for items in groups
-- M - no check (in v2) that all NTs and accessible OTs are in a group
-- F - allow integer/integer32 index items without a range
-- A - allow (in v2) MIB modules missing a MODULE-IDENTITY
-- G - allow unused IMPORTS and textual conventions
-- N - no check (in v2) of access of objects in notifications
-- I - use (in v1) the v2 rules for checking ACCESS of index items
-- Z - allow bad table modelling practices
-- 0I - allow use of SMI items and macros without being imported
-- 0N - no check (in v1) of access of leaf items in traps
-- 0S - allow non-matching syntax of sequence items
#removeOpt "4 5 6 J K U L 2 3 O P T M F A G N I Z 0I 0N 0S"
-- Relax strict checking for practices permitted (or required) by SMI
-- V - allow (in v2) a V1 OID or OT as V2 group
-- E - allow seq item syntax to match TC
-- 0V - allow use dup items in VARIABLES or OBJECTS clause
#addOpt "V E 0V"
#condinclude "rfc2558.mi2"
#condExcludeModule SONET-MIB 0
#popOpt
In some cases the switches selected above will cause SMICng to
complain about something that is not an error. For instance,
#removeOpt "G" causes complaints about unused TCs in a module such as
PerfHist-TC-MIB [RFC2493] that contains nothing but TCs, while
#removeOpt "Z" will cause complaints about the ifInvStackTable in the
IF-INVERTED-STACK-MIB [RFC2864] because the indices appear in the
opposite order than in the IF-MIB's [RFC2863] ifStackTable (which is
by design). In such cases the sense of the switches in question
should be reversed.
OPS Area Expires May 2003 [Page 17]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
Intellectual Property
The IETF takes no position regarding the validity or scope of any
intellectual property 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; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication 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 implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
OPS Area Expires May 2003 [Page 18]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
Normative References
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3",
BCP 9, RFC 2026, October 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirements Levels", BCP 14, RFC 2119, March 1997.
[RFC2223bis]
Reynolds, J., and R. Braden, "Instructions to Request for
Comments (RFC) Authors ", work in progress (currently
<draft-rfc-editor-rfc2223bis-03.txt>).
[RFC2434] Alvestrand, H., "Guidelines for Writing an IANA
Considerations Section in RFCs", BCP 26, RFC 2434, October
1998.
[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.
[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.
[RFC3291] Daniele, M., Haberman, B., Routhier, S., and J.
Schoenwaelder, "Textual Conventions for Internet Network
Addresses", RFC 3291, May 2002.
OPS Area Expires May 2003 [Page 19]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
Informative References
[RFC2570bis]
Case, J., Mundy, R., Partain, D., and B. Stewart,
"Introduction and Applicability Statements for Internet-
Standard Management Framework", work in progress (currently
<draft-ietf-snmpv3-rfc2570bis-03.txt>).
[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.
[RFC2493] Tesink, K., "Textual Conventions for MIB Modules Using
Performance History Based on 15 Minute Intervals", RFC 2493,
January 1999.
[RFC2558] Tesink, K., "Definitions of Managed Objects for the
SONET/SDH Interface Type", RFC 2558, March 1999.
[RFC2863] McCloghrie, K., and F. Kastenholz, "The Interfaces Group
MIB*(rq, RFC 2863, June 2000.
[RFC2864] McCloghrie, K., and G. Hanson, "The Inverted Stack Table
Extension to the Interfaces Group MIB", RFC 2864, June 2000.
[RFC2932] McCloghrie, K., Farinacci, D., and D. Thaler, "IPv4
Multicast Routing MIB", RFC 2932, October 2000.
OPS Area Expires May 2003 [Page 20]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
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/security.html so that all such risks are
adequately disclosed.
Acknowledgments
Most of the material on usage of data types was provided by Bert
Wijnen, with assistance from Keith McCloghrie, David Perkins, and
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,
much of the material in this document was taken from an unpublished
XML guide for MIB authors and reviewers by Juergen Schoenwaelder.
Editor's Address
C. M. Heard
600 Rainbow Dr. #141
Mountain View, CA 94041-2542
USA
Phone: +1 650 964 8391
EMail: heard@pobox.com
OPS Area Expires May 2003 [Page 21]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS 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.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
OPS Area Expires May 2003 [Page 22]
Internet Draft Guidelines for MIB Authors and Reviewers November 2002
Table of Contents
1 Introduction ................................................. 2
2 Terminology .................................................. 2
3 General Documentation Guidelines ............................. 3
3.1 MIB Boilerplate Section .................................... 3
3.2 Narrative Sections ......................................... 3
3.3 Definitions Section ........................................ 4
3.4 Intellectual Property Section .............................. 4
3.5 References Sections ........................................ 4
3.6 Security Considerations Section ............................ 4
3.7 IANA Considerations Section ................................ 5
3.8 Copyright Notices .......................................... 6
4 SMIv2 Usage Guidelines ....................................... 7
4.1 Module Names ............................................... 7
4.2 Descriptors and Labels ..................................... 7
4.3 Naming Hierarchy ........................................... 7
4.4 IMPORTS Statement .......................................... 8
4.5 MODULE-IDENTITY Invocation ................................. 9
4.6 Textual Conventions and Object Definitions ................. 10
4.6.1 Usage of Data Types ...................................... 10
4.6.1.1 INTEGER, Integer32, Gauge32, and Unsigned32 ............ 10
4.6.1.2 Counter32 and Counter64 ................................ 11
4.6.1.3 CounterBasedGauge64 .................................... 12
4.6.1.4 IpAddress .............................................. 13
4.6.1.5 Other Types ............................................ 13
4.6.2 OBJECT IDENTIFIER Values Assigned to Objects ............. 13
4.7 Notification Definitions ................................... 13
4.8 Compliance Statements ...................................... 13
Appendix A: MIB Review Checklist ............................. 14
Appendix B: Using smilint to compile MIB modules ............. 15
Appendix C: Using SMICng to compile MIB modules .............. 16
Intellectual Property ......................................... 18
Normative References .......................................... 19
Informative References ........................................ 20
Security Considerations ....................................... 21
Acknowledgments ............................................... 21
Editor's Address .............................................. 21
Full Copyright Statement ...................................... 22
Acknowledgement ............................................... 22
OPS Area Expires May 2003 [Page 23]