- There either MUST be one columnar object with a SYNTAX value of
StorageType [RFC2579] and a MAX-ACCESS value of read-create, or
else the row object (table entry) DESCRIPTION clause MUST specify
what happens to dynamically-created rows after an agent restart.
- If the agent itself may also create and/or delete rows, then the
conditions under which this can occur MUST be clearly documented
in the row object DESCRIPTION clause.
- For conceptual rows that include a status column:
- The DESCRIPTION clause of the status column MUST specify which
columnar objects (if any) have to be set to valid values before
the row can be activated. If any objects in cascading tables
have to be populated with related data before the row can be
activated, then this MUST also be specified.
- The DESCRIPTION clause of the status column MUST specify whether
or not it is possible to modify other columns in the same
conceptual row when the status value is active(1). Note that in
many cases it will be possible to modify some writable columns
when the row is active but not others. In such cases, the
DESCRIPTION clause for each writable column SHOULD state whether
or not that column can be modified when the row is active, and
the DESCRIPTION clause for the status column SHOULD state that
modifiability of other columns when the status value is active(1)
is specified in the DESCRIPTION clauses for those columns (rather
than listing the modifiable columns individually).
- For conceptual rows that include a StorageType column:
- The DESCRIPTION clause of the StorageType column MUST specify
which read-write or read-create columnar objects in permanent(4)
rows an agent must, at a minimum, allow to be writable.
Note that RFC 2578 Section 7.8 requires that the lifetime of an
instance of a conceptual row that AUGMENTS a base row must be the
same as the corresponding instance of the base row. It follows that
there is no need for a RowStatus or StorageType column in an
augmenting row if one is already present in the base row.
Complete requirements for the RowStatus and StorageType TCs can be
found in RFC 2579, in the DESCRIPTION clauses for those TCs.
4.6.5. OID Values Assigned to Objects
RFC 2578 Section 7.10 specifies the rules for assigning OBJECT
IDENTIFIER (OID) values to OBJECT-TYPE definitions. In particular:
- A conceptual table MUST have exactly one subordinate object, which
is a conceptual row. The OID assigned to the conceptual row MUST
be derived by appending a sub-identifier of "1" to the OID assigned
to the conceptual table.
- A conceptual row has as many subordinate objects as there are
columns in the row; there MUST be at least one. The OID assigned
to each columnar object MUST be derived by appending a non-zero
sub-identifier, unique within the row, to the OID assigned to the
conceptual row.
- A columnar or scalar object MUST NOT have any subordinate objects.
- The last sub-identifier of an OID assigned to any object (be it
table, row, column, or scalar) MUST NOT be equal to zero. Note
that sub-identifiers of intermediate nodes MAY be equal to zero.
- The OID assigned to an object definition MUST NOT also be assigned
to another definition that results in OID registration. RFC 2578
Section 3.6 lists the constructs that create OID registrations.
Although it is not specifically required by the SMI, it is customary
(and strongly RECOMMENDED) that object definitions not be registered
beneath group definitions, compliance statements, capabilities
statements, or notification definitions. It is also customary (and
strongly RECOMMENDED) that group definitions, compliance statements,
capabilities statements, and notification definitions not be
registered beneath object definitions. See Appendix D for a
RECOMMENDED OID assignment scheme.
4.6.6. OID Length Limitations and Table Indexing
As specified in RFC 2578 Section 3.5, all OIDs are limited to 128
sub-identifiers. While this is not likely to cause problems with
administrative assignments, it does place some limitations on table
indexing. That is true because the length limitation also applies to
OIDs for object instances, and these consist of the concatenation of
the "base" OID assigned in the object definition plus the index
components. When a table has multiple indices of types such as OCTET
STRING or OBJECT IDENTIFIER that resolve to multiple sub-identifiers,
then the 128-sub-identifier limit can be quickly reached.
Despite its inconvenience, the 128-sub-identifier limit is not
something that can be ignored. In addition to being imposed by the
SMI, it is also imposed by the SNMP (see the last paragraph in
Section 4.1 of RFC 3416 [RFC3416]). It follows that any table with
enough indexing components to violate this limit cannot be read or
written using the SNMP and so is unusable. Hence table design MUST
take the 128-sub-identifier limit into account. It is RECOMMENDED
that all MIB documents make explicit any limitations on index
component lengths that management software must observe. This may be
done either by including SIZE constraints on the index components or
by specifying applicable constraints in the conceptual row
DESCRIPTION clause or in the surrounding documentation.
4.7. Notification Definitions
RFC 2578 Section 8 specifies the rules for notification definitions.
In particular:
- Inaccessible objects MUST NOT appear in the OBJECTS clause.
- For each object type mentioned in the OBJECTS clause, the
DESCRIPTION clause MUST specify which object instance is to be
present in the transmitted notification and MUST specify the
information/meaning conveyed.
- The OBJECT IDENTIFIER (OID) value assigned to each notification
type MUST have a next-to-last sub-identifier of zero, so that it is
possible to convert an SMIv2 notification definition into an SMIv1
trap definition and back again without information loss (see
[RFC3584] Section 2.1.2) and possible for a multilingual proxy
chain to translate an SNMPv2 trap into an SNMPv1 trap and back
again without information loss (see [RFC3584] Section 3). In
addition, the OID assigned to a notification definition MUST NOT
also be assigned to another definition that results in OID
registration. RFC 2578 Section 3.6 lists the constructs that
create OID registrations.
Although it is not specifically required by the SMI, it is customary
(and strongly RECOMMENDED) that notification definitions not be
registered beneath group definitions, compliance statements,
capabilities statements, or object definitions (this last is
especially unwise, as it may result in an object instance and a
notification definition sharing the same OID). It is also customary
(and strongly RECOMMENDED) that the OIDs assigned to notification
types be leaf OIDs (i.e., that there be no OID registrations
subordinate to a notification definition). See Appendix D for a
RECOMMENDED OID assignment scheme.
In many cases, notifications will be triggered by external events,
and sometimes it will be possible for those external events to occur
at a sufficiently rapid rate that sending a notification for each
occurrence would overwhelm the network. In such cases, a mechanism
MUST be provided for limiting the rate at which the notification can
be generated. A common technique is to require that the notification
generator use throttling -- that is, to require that it generate no
more than one notification for each event source in any given time
interval of duration T. The throttling period T MAY be configurable,
in which case it is specified in a MIB object, or it MAY be fixed, in
which case it is specified in the notification definition. Examples
of the fixed time interval technique can be found in the SNMP-
REPEATER-MIB [RFC2108] and in the ENTITY-MIB [RFC4133].
4.8. Compliance Statements
RFC 2580 Sections 3, 4, and 5 specify the rules for conformance
groups and compliance statements. In particular:
- Every object with a MAX-ACCESS value other than "not-accessible"
MUST be contained in at least one object group.
- Every notification MUST be contained in at least one notification
group.
- There MUST be at least one compliance statement defined for each
"standard" MIB module. It may reside either within that MIB module
or within a companion MIB module.
In writing compliance statements, there are several points that are
easily overlooked:
- An object group or notification group that is not mentioned either
in the MANDATORY-GROUPS clause or in any GROUP clause of a MODULE-
COMPLIANCE statement is unconditionally optional with respect to
that compliance statement. An alternate way to indicate that an
object group or notification group is optional is to mention it in
a GROUP clause whose DESCRIPTION clause states that the group is
optional. The latter method is RECOMMENDED (for optional groups
that are relevant to the compliance statement) in order to make it
clear that the optional status is intended rather than being the
result of an act of omission.
- If there are any objects with a MAX-ACCESS value of read-write or
read-create for which there is no OBJECT clause that specifies a
MIN-ACCESS of read-only, then implementations must support write
access to those objects in order to be compliant with that MODULE-
COMPLIANCE statement. This fact sometimes catches MIB module
authors by surprise. When confronted with such cases, reviewers
SHOULD verify that this is indeed what the authors intended, since
it often is not.
- On the other side of the coin, MIB module authors need to be aware
that while a read-only compliance statement is sufficient to
support interoperable monitoring applications, it is not sufficient
to support interoperable configuration applications. A technique
commonly used in MIB modules that are intended to support both
monitoring and configuration is to provide both a read-only
compliance statement and a full compliance statement. A good
example is provided by the DIFFSERV-MIB [RFC3289]. Authors SHOULD
consider using this technique when it is applicable.
Sometimes MIB module authors will want to specify that a compliant
implementation needs to support only a subset of the values allowed
by an object’s SYNTAX clause. For accessible objects, this may be
done either by specifying the required values in an object’s
DESCRIPTION clause or by providing an OBJECT clause with a refined
SYNTAX in a compliance statement. The latter method is RECOMMENDED
for most cases, and is REQUIRED if there are multiple compliance
statements with different value subsets required. The DIFFSERV-MIB
[RFC3289] illustrates this point. The diffServMIBFullCompliance
statement contains the following OBJECT clause. (See Section 4.8.1,
"Note Regarding These Examples and RFC 2578".)
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) }
DESCRIPTION
"Support for createAndWait and notInService is not required."
whereas the diffServMIBReadOnlyCompliance statement contains this:
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
MIN-ACCESS read-only
DESCRIPTION
"Write access is not required, and active is the only status that
needs to be supported."
One cannot do this for inaccessible index objects because they cannot
be present in object groups and cannot be mentioned in OBJECT
clauses. There are situations, however, in which one might wish to
indicate that an implementation is required to support only a subset
of the possible values of some index in a read-create table. In such
cases, the requirements MUST be specified either in the index
object’s DESCRIPTION clause (RECOMMENDED if there is only one value
subset) or in the DESCRIPTION clause of a MODULE-COMPLIANCE statement
(REQUIRED if the value subset is unique to the compliance statement).
In many cases, a MIB module is always implemented in conjunction with
one or more other MIB modules. That fact is REQUIRED to be noted in
the surrounding documentation (see Section 3.2 above), and it SHOULD
also be noted in the relevant compliance statements. In cases where
a particular compliance statement in (say) MIB module A requires the
complete implementation of some other MIB module B, then the
RECOMMENDED approach is to include a statement to that effect in the
DESCRIPTION clause of the compliance statement(s) in MIB module A.
It is also possible, however, that MIB module A might have
requirements that are different from those that are expressed by any
compliance statement of module B -- for example, module A might not
require any of the unconditionally mandatory object groups from
module B but might require mandatory implementation of an object
group from module B that is only conditionally mandatory with respect
to the compliance statement(s) in module B. In such cases, the
RECOMMENDED approach is for the compliance statement(s) in module A
to formally specify requirements with respect to module B via
appropriate MODULE, MANDATORY-GROUPS, GROUP, and OBJECT clauses. An
example is provided by the compliance statements in the DIFFSERV-MIB
[RFC3289], which list the ifCounterDiscontinuityGroup from IF-MIB
[RFC2863] as a mandatory group. That group is not sufficient to
satisfy any IF-MIB compliance statement, and it is conditionally
mandatory in the IF-MIB’s current compliance statement ifCompliance3.
4.8.1. Note Regarding These Examples and RFC 2578
There has been some dispute as to whether syntax refinements that
restrict enumerations (RFC 2578 Section 9) are permitted with TCs, as
shown in the examples above, or are allowed only with the base types
INTEGER and BITS, as suggested by a strict reading of RFC 2578. The
rough consensus of the editors of the SMIv2 documents and the current
pool of MIB reviewers is that they should be allowed with TCs. MIB
module authors should be aware that some MIB compilers follow the
strict reading of RFC 2578 and require that the TC be replaced by its
base type (INTEGER or BITS) when enumerations are refined. That
usage is legal, and it can be found in some older MIB modules such as
the IF-MIB [RFC2863].
4.9. Revisions to MIB Modules
RFC 2578 Section 10 specifies general rules that apply any time a MIB
module is revised. Specifically:
- The MODULE-IDENTITY invocation MUST be updated to include
information about the revision. In particular, the LAST-UPDATED
clause value MUST be set to the revision time, a REVISION clause
with the same UTC time and an associated DESCRIPTION clause
describing the changes MUST be added, and any obsolete information
in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses
MUST be replaced with up-to-date information. See Section 4.5
above for additional requirements that apply to MIB modules that
are under IETF change control.
- On the other hand, the module name MUST NOT be changed (except to
correct typographical errors), existing definitions (even obsolete
ones) MUST NOT be removed from the MIB module, and descriptors and
OBJECT IDENTIFIER values associated with existing definitions MUST
NOT be changed or re-assigned.
It is important to note that the purpose in forbidding certain kinds
of changes is to ensure that a revised MIB module is compatible with
fielded implementations based on previous versions of the module.
There are two distinct aspects of this backward-compatibility
requirement. One is "over the wire" compatibility of agent and
manager implementations that are based on different revisions of the
MIB module. The other is "compilation" compatibility with MIB
modules that import definitions from the revised MIB module. The
rules forbidding changing or re-assigning OBJECT IDENTIFIER values
are necessary to ensure "over the wire" compatibility; the rules
against changing module names or descriptors or removing obsolete
definitions are necessary to ensure compilation compatibility.
RFC 2578 Section 10.2 specifies rules that apply to revisions of
object definitions. The following guidelines correct some errors in
these rules and provide some clarifications:
- Bullet (1) allows the labels of named numbers and named bits in
SYNTAX clauses of type enumerated INTEGER or BITS to be changed.
This can break compilation compatibility, since those labels may be
used by DEFVAL clauses in modules that import the definitions of
the affected objects. Therefore, labels of named numbers and named
bits MUST NOT be changed when revising IETF MIB modules (except to
correct typographical errors), and they SHOULD NOT be changed when
revising enterprise MIB modules.
- Although not specifically permitted in bullets (1) through (8), it
is generally considered acceptable to add range constraints to the
SYNTAX clause of an integer-valued object, provided that the
constraints simply make explicit some value restrictions that were
implicit in the definition of the object. The most common example
is an auxiliary object with a SYNTAX of INTEGER or Integer32 with
no range constraint. Since an auxiliary object is not permitted to
assume negative values, adding the range constraint (0..2147483647)
cannot possibly result in any "over the wire" change, nor will it
cause any compilation compatibility problems with a correctly
written MIB module. Such a change SHOULD be treated by a reviewer
as an editorial change, not as a semantic change. Similarly,
removal of a range or size constraint from an object definition
when that range or size constraint is enforced by the underlying
data type SHOULD be treated by a reviewer as an editorial change.
RFC 2578 Section 10.3 specifies rules that apply to revisions of
notification definitions. No clarifications or corrections are
required.
RFC 2579 Section 5 specifies rules that apply to revisions of textual
convention definitions. The following guideline corrects an error in
these rules:
- Bullet (1) allows the labels of named numbers and named bits in
SYNTAX clauses of type enumerated INTEGER or BITS to be changed.
This can break compilation compatibility, since those labels may be
used by DEFVAL clauses in modules that import the definitions of
the affected TCs. Therefore, labels of named numbers and named
bits MUST NOT be changed when revising IETF MIB modules (except to
correct typographical errors), and they SHOULD NOT be changed when
revising enterprise MIB modules.
RFC 2580 Section 7.1 specifies rules that apply to revisions of
conformance groups. Two point are worth reiterating:
- Objects and notifications MUST NOT be added to or removed from an
existing object group or notification group. Doing so could cause
a compilation failure or (worse) a silent change in the meaning of
a compliance statement or capabilities statement that refers to
that group.
- The status of a conformance group is independent of the status of
its members. Thus, a current group MAY refer to deprecated objects
or notifications. This may be desirable in certain cases, e.g., a
set of widely-deployed objects or notifications may be deprecated
when they are replaced by a more up-to-date set of definitions, but
the conformance groups that contain them may remain current in
order to encourage continued implementation of the deprecated
objects and notifications.
RFC 2580 Section 7.2 specifies rules that apply to revisions of
compliance statements. The following guidelines correct an omission
from these rules and emphasize one important point:
- RFC 2580 should (but does not) recommend that an OBJECT clause
specifying support for the original set of values be added to a
compliance statement when an enumerated INTEGER object or a BITS
object referenced by the compliance statement has enumerations or
named bits added, assuming that no such clause is already present
and that the effective MIN-ACCESS value is read-write or read-
create. This is necessary in order to avoid a silent change to the
meaning of the compliance statement. MIB module authors and
reviewers SHOULD watch for this to ensure that such OBJECT clauses
are added when needed. Note that this may not always be possible
to do, since affected compliance statements may reside in modules
other than the one that contains the revised definition(s).
- The status of a compliance statement is independent of the status
of its members. Thus, a current compliance statement MAY refer to
deprecated object groups or notification groups. This may be
desirable in certain cases, e.g., a set of widely-deployed object
or notification groups may be deprecated when they are replaced by
a more up-to-date set of definitions, but compliance statements
that refer to them may remain current in order to encourage
continued implementation of the deprecated groups.
RFC 2580 Section 7.3 specifies rules that apply to revisions of
capabilities statements. The following guideline corrects an
omission from these rules:
- RFC 2580 should (but does not) recommend that VARIATION clauses
specifying support for the original set of values be added to a
capabilities statement when enumerated INTEGER objects or BITS
objects referenced by the capabilities statement have enumerations
added, assuming that no such clauses are already present. This is
necessary in order to avoid a silent change to the meaning of the
capabilities statement.
In certain exceptional situations, the cost of strictly following the
SMIv2 rules governing MIB module revisions may exceed the benefit.
In such cases, the rules can be waived, but when that is done both
the change and the justification for it MUST be thoroughly
documented. One example is provided by Section 3.1.5 of RFC 2863,
which documents the semantic change that was made to ifIndex in the
transition from MIB-II [RFC1213] to the IF-MIB [RFC2863] and provides
a detailed justification for that change. Another example is
provided by the REVISION clause of the SONET-MIB [RFC2558] that
documents raising the MAX-ACCESS of several objects to read-write
while adding MIN-ACCESS of read-only for compatibility with the
previous version [RFC1595].
Authors and reviewers may find it helpful to use tools that can list
the differences between two revisions of a MIB module. Please see
http://www.ops.ietf.org/mib-review-tools.html for more information.
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.
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