one argument which is used to specify a textual cross-reference to
some other document, either another module which defines related
identity definitions, or some other document which provides
additional information relevant to this identity definition.
8.5. Usage Examples
identity null {
status current;
description
"An identity used to represent null pointer values.";
};
identity snmpTransportDomain {
status current;
description
"A generic SNMP transport domain identity.";
};
identity snmpUDPDomain {
parent snmpTransportDomain;
status current;
description
"The SNMP over UDP transport domain.";
};
9. The class Statement
The `class’ statement is used to define a new class that represents a
container of related attributes and events (Section 9.2, Section
9.4). A class can be defined either from scratch or derived from a
parent class. A derived class inherits all attributes and events of
the parent class and can be extended by additional attributes and
events.
The `class’ statement gets the following two arguments: The first
argument is an upper-case class identifier. The second argument is a
statement block that holds detailed class information in an
obligatory order.
See the `classStatement’ rule of the SMIng grammar (Appendix B) for
the formal syntax of the `class’ statement.
9.1. The class’ extends Statement
The class’ `extends’ statement must be present for a class derived
from a parent class and must be absent for a class defined from
scratch. It gets one argument which is used to specify the parent
class from which this class shall be derived.
9.2. The class’ attribute Statement
The class’ `attribute’ statement, which can be present zero, one or
multiple times, gets two arguments: the attribute name and a
statement block that holds detailed attribute information in an
obligatory order.
9.2.1. The attribute’s type Statement
The attribute’s `type’ statement must be present. It gets at least
one argument which is used to specify the type of the attribute:
either a type name or a class name. In case of a type name, it may
be restricted by a second argument according to the restriction rules
described in Section 3.
9.2.2. The attribute’s access Statement
The attribute’s `access’ statement must be present for attributes
typed by a base type or derived type, and must be absent for
attributes typed by a class. It gets one argument which is used to
specify whether it makes sense to read and/or write an instance of
the attribute, or to include its value in an event. This is the
maximal level of access for the attribute. This maximal level of
access is independent of any administrative authorization policy.
The value `readwrite’ indicates that read and write access makes
sense. The value `readonly’ indicates that read access makes sense,
but write access is never possible. The value `eventonly’ indicates
an object which is accessible only via an event.
These values are ordered, from least to greatest access level:
`eventonly’, `readonly’, `readwrite’.
9.2.3. The attribute’s default Statement
The attribute’s `default’ statement need not be present for
attributes typed by a base type or derived type, and must be absent
for attributes typed by a class. It gets one argument which is used
to specify an acceptable default value for this attribute. A default
value may be used when an attribute instance is created. That is,
the value is a "hint" to implementors.
The value of the `default’ statement must, of course, correspond to
the (probably restricted) type specified in the attribute’s `type’
statement.
The attribute’s default value overrides the default value of the
underlying type definition if both are present.
9.2.4. The attribute’s format Statement
The attribute’s `format’ statement need not be present for attributes
typed by a base type or derived type, and must be absent for
attributes typed by a class. It gets one argument which is used to
give a hint as to how the value of an instance of this attribute
might be displayed. See Section 3.13 for a description of format
specifications.
The attribute’s format specification overrides the format
specification of the underlying type definition if both are present.
9.2.5. The attribute’s units Statement
The attribute’s `units’ statement need not be present for attributes
typed by a base type or derived type, and must be absent for
attributes typed by a class. It gets one argument which is used to
specify a textual definition of the units associated with this
attribute.
The attribute’s units specification overrides the units specification
of the underlying type definition if both are present.
The units specification has to be appropriate for values displayed
according to the attribute’s format specification if present. For
example, if the attribute represents a frequency value of type
Unsigned64 measured in thousands of Hertz, the format specification
should be `d-3’ and the units specification should be `Hertz’ or
`Hz’. If the format specification would be omitted, the units
specification should be `Milli-Hertz’ or `mHz’. Authors of SMIng
modules should pay attention to keep format and units specifications
of type and attribute definitions in sync. Application implementors
MUST NOT implement units specifications without implementing format
specifications.
9.2.6. The attribute’s status Statement
The attribute’s `status’ statement must be present. It gets one
argument which is used to specify whether this attribute definition
is current or historic. The value `current’ means that the
definition is current and valid. The value `obsolete’ means the
definition is obsolete and should not be implemented and/or can be
removed if previously implemented. While the value `deprecated’ also
indicates an obsolete definition, it permits new/continued
implementation in order to foster interoperability with older/
existing implementations.
Attributes SHOULD NOT be defined as `current’ if their type or their
containing class is `deprecated’ or `obsolete’. Similarly, they
SHOULD NOT be defined as `deprecated’ if their type or their
containing class is `obsolete’. Nevertheless, subsequent revisions
of used type definition cannot be avoided, but SHOULD be taken into
account in subsequent revisions of the local module.
9.2.7. The attribute’s description Statement
The attribute’s `description’ statement, which must be present, gets
one argument which is used to specify a high-level textual
description of this attribute.
It is RECOMMENDED that all semantic definitions necessary for the
implementation of this attribute be included.
9.2.8. The attribute’s reference Statement
The attribute’s `reference’ statement, which need not be present,
gets one argument which is used to specify a textual cross-reference
to some other document, either another module which defines related
attribute definitions, or some other document which provides
additional information relevant to this attribute definition.
9.3. The class’ unique Statement
The class’ `unique’ statement, which need not be present, gets one
argument that specifies a comma-separated list of attributes of this
class, enclosed in parenthesis. If present, this list of attributes
makes up a unique identification of all possible instances of this
class. It can be used as a unique key in underlying protocols.
If the list is empty, the class should be regarded as a scalar class
with only a single instance.
If the `unique’ statement is not present, the class is not meant to
be instantiated directly, but to be contained in other classes or the
parent class of other refining classes.
If present, the attribute list MUST NOT contain any attribute more
than once and the attributes should be ordered where appropriate so
that the attributes that are most significant in most situations
appear first.
9.4. The class’ event Statement
The class’ `event’ statement is used to define an event related to an
instance of this class that can occur asynchronously. It gets two
arguments: a lower-case event identifier and a statement block that
holds detailed information in an obligatory order.
See the `eventStatement’ rule of the SMIng grammar (Appendix B) for
the formal syntax of the `event’ statement.
9.4.1. The event’s status Statement
The event’s `status’ statement, which must be present, gets one
argument which is used to specify whether this event definition is
current or historic. The value `current’ means that the definition
is current and valid. The value `obsolete’ means the definition is
obsolete and should not be implemented and/or can be removed if
previously implemented. While the value `deprecated’ also indicates
an obsolete definition, it permits new/continued implementation in
order to foster interoperability with older/existing implementations.
9.4.2. The event’s description Statement
The event’s `description’ statement, which must be present, gets one
argument which is used to specify a high-level textual description of
this event.
It is RECOMMENDED that all semantic definitions necessary for the
implementation of this event be included. In particular, which
instance of the class is associated with an event of this type SHOULD
be documented.
9.4.3. The event’s reference Statement
The event’s `reference’ statement, which need not be present, gets
one argument which is used to specify a textual cross-reference to
some other document, either another module which defines related
event definitions, or some other document which provides additional
information relevant to this event definition.
9.5. The class’ status Statement
The class’ `status’ statement, which must be present, gets one
argument which is used to specify whether this class definition is
current or historic. The value `current’ means that the definition
is current and valid. The value `obsolete’ means the definition is
obsolete and should not be implemented and/or can be removed if
previously implemented. While the value `deprecated’ also indicates
an obsolete definition, it permits new/continued implementation in
order to foster interoperability with older/existing implementations.
Derived classes SHOULD NOT be defined as `current’ if their parent
class is `deprecated’ or `obsolete’. Similarly, they SHOULD NOT be
defined as `deprecated’ if their parent class is `obsolete’.
Nevertheless, subsequent revisions of the parent class cannot be
avoided, but SHOULD be taken into account in subsequent revisions of
the local module.
9.6. The class’ description Statement
The class’ `description’ statement, which must be present, gets one
argument which is used to specify a high-level textual description of
the newly defined class.
It is RECOMMENDED that all semantic definitions necessary for
implementation, and to embody any information which would otherwise
be communicated in any commentary annotations associated with this
class definition be included.
9.7. The class’ reference Statement
The class’ `reference’ statement, which need not be present, gets one
argument which is used to specify a textual cross-reference to some
other document, either another module which defines related class
definitions, or some other document which provides additional
information relevant to this class definition.
9.8. Usage Example
Consider how an event might be described that signals a status change
of an interface:
class Interface {
// ...
attribute speed {
type Gauge32;
access readonly;
units "bps";
status current;
description
"An estimate of the interface’s current bandwidth
in bits per second.";
};
// ...
attribute adminStatus {
type AdminStatus;
access readwrite;
status current;
description
"The desired state of the interface.";
};
attribute operStatus {
type OperStatus;
access readonly;
status current;
description
"The current operational state of the interface.";
};
event linkDown {
status current;
description
"A linkDown event signifies that the ifOperStatus
attribute for this interface instance is about to
enter the down state from some other state (but not
from the notPresent state). This other state is
indicated by the included value of ifOperStatus.";
};
status current;
description
"A physical or logical network interface.";
};
10. Extending a Module
As experience is gained with a module, it may be desirable to revise
that module. However, changes are not allowed if they have any
potential to cause interoperability problems between an
implementation using an original specification and an implementation
using an updated specification(s).
For any change, some statements near the top of the module MUST be
updated to include information about the revision: specifically, a
new `revision’ statement (Section 5.6) must be included in front of
the `revision’ statements. Furthermore, any necessary changes MUST
be applied to other statements, including the `organization’ and
`contact’ statements (Section 5.2, Section 5.3).
Note that any definition contained in a module is available to be
imported by any other module, and is referenced in an `import’
statement via the module name. Thus, a module name MUST NOT be
changed. Specifically, the module name (e.g., `ACME-MIB’ in the
example of Section 5.7) MUST NOT be changed when revising a module
(except to correct typographical errors), and definitions MUST NOT be
moved from one module to another.
Also note that obsolete definitions MUST NOT be removed from modules
since their identifiers may still be referenced by other modules.
A definition may be revised in any of the following ways:
o In `typedef’ statement blocks, a `type’ statement containing an
`Enumeration’ or `Bits’ type may have new named numbers added.
o In `typedef’ statement blocks, the value of a `type’ statement may
be replaced by another type if the new type is derived (directly
or indirectly) from the same base type, has the same set of
values, and has identical semantics.
o In `attribute’ statements where the `type’ sub-statement specifies
a class, the class may be replaced by another class if the new
class is derived (directly or indirectly) from the base class and
both classes have identical semantics.
o In `attribute’ statements where the `type’ sub-statement specifies
a base type, a defined type, or an implicitly derived type (i.e.,
not a class), that type may be replaced by another type if the new
type is derived (directly or indirectly) from the same base type,
has the same set of values, and has identical semantics.
o In any statement block, a `status’ statement value of `current’
may be revised as `deprecated’ or `obsolete’. Similarly, a
`status’ statement value of `deprecated’ may be revised as
`obsolete’. When making such a change, the `description’
statement SHOULD be updated to explain the rationale.
o In `typedef’ and `attribute’ statement blocks, a `default’
statement may be added or updated.
o In `typedef’ and `attribute’ statement blocks, a `units’ statement
may be added.
o A class may be augmented by adding new attributes.
o In any statement block, clarifications and additional information
may be included in the `description’ statement.
o In any statement block, a `reference’ statement may be added or
updated.
o Entirely new extensions, types, identities, and classes may be
defined, using previously unassigned identifiers.
Otherwise, if the semantics of any previous definition are changed
(i.e., if a non-editorial change is made to any definition other than
those specifically allowed above), then this MUST be achieved by a
new definition with a new identifier. In case of a class where the
semantics of any attributes are changed, the new class can be defined
by derivation from the old class and refining the changed attributes.
Note that changing the identifier associated with an existing
definition is considered a semantic change, as these strings may be
used in an `import’ statement.
11. SMIng Language Extensibility
While the core SMIng language has a well defined set of statements
(Section 5 through Section 9.4) that are used to specify those
aspects of management information commonly regarded as necessary
without management protocol specific information, there may be
further information people wish to express. Describing additional
information informally in description statements has a disadvantage
in that this information cannot be parsed by any program.
SMIng allows modules to include statements that are unknown to a
parser but fulfil some core grammar rules (Section 4.3).
Furthermore, additional statements may be defined by the `extension’
statement (Section 6). Extensions can be used in the local module or
in other modules that import the extension. This has some
advantages:
o A parser can differentiate between statements known as extensions
and unknown statements. This enables the parser to complain about
unknown statements, e.g., due to typos.
o If an extension’s definition contains a formal ABNF grammar
definition and a parser is able to interpret this ABNF definition,
this enables the parser to also complain about the wrong usage of
an extension.
o Since there might be some common need for extensions, there is a
relatively high probability of extension name collisions
originated by different organizations, as long as there is no
standardized extension for that purpose. The requirement to
explicitly import extension statements allows those extensions to
be distinguished.
o The supported extensions of an SMIng implementation, e.g., an
SMIng module compiler, can be clearly expressed.
The only formal effect of an extension statement definition is to
declare its existence and status, and optionally its ABNF grammar.
All additional aspects SHOULD be described in the `description’
statement:
o The detailed semantics of the new statement SHOULD be described.
o The contexts in which the new statement can be used SHOULD be
described, e.g., a new statement may be designed to be used only
in the statement block of a module, but not in other nested
statement blocks. Others may be applicable in multiple contexts.
In addition, the point in the sequence of an obligatory order of
other statements, where the new statement may be inserted, might
be prescribed.
o The circumstances that make the new statement mandatory or
optional SHOULD be described.
o The syntax of the new statement SHOULD at least be described
informally, if not supplied formally in an `abnf’ statement.
o It might be reasonable to give some suggestions under which
conditions the implementation of the new statement is adequate and
how it could be integrated into existent implementations.
Some possible extension applications are:
o The formal mapping of SMIng definitions into the SNMP [RFC3781]
framework is defined as an SMIng extension. Other mappings may
follow in the future.
o Inlined annotations to definitions. For example, a vendor may
wish to describe additional information to class and attribute
definitions in private modules. An example are severity levels of
events in the statement block of an `event’ statement.
o Arbitrary annotations to external definitions. For example, a
vendor may wish to describe additional information to definitions
in a "standard" module. This allows a vendor to implement
"standard" modules as well as additional private features, without
redundant module definitions, but on top of "standard" module
definitions.
12. Security Considerations
This document defines a language with which to write and read
descriptions of management information. The language itself has no
security impact on the Internet.
13. Acknowledgements
Since SMIng started as a close successor of SMIv2, some paragraphs
and phrases are directly taken from the SMIv2 specifications
[RFC2578], [RFC2579], [RFC2580] written by Jeff Case, Keith
McCloghrie, David Perkins, Marshall T. Rose, Juergen Schoenwaelder,
and Steven L. Waldbusser.
The authors would like to thank all participants of the 7th NMRG
meeting held in Schloss Kleinheubach from 6-8 September 2000, which
was a major step towards the current status of this memo, namely
Heiko Dassow, David Durham, Keith McCloghrie, and Bert Wijnen.
Furthermore, several discussions within the SMING Working Group
reflected experience with SMIv2 and influenced this specification at
some points.
14. References
14.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
14.2. Informative References
[RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J.,
Strauss, F. and W. Weiss, "SMIng Objectives", RFC 3216,
December 2001.
[RFC3781] Strauss, F. and J. Schoenwaelder, "Next Generation
Structure of Management Information (SMIng) Mappings to
the Simple Network Management Protocol (SNMP)", RFC 3781,
May 2004.
[RFC2578] McCloghrie, K., Perkins, D. and J. Schoenwaelder,
"Structure of Management Information Version 2 (SMIv2)",
STD 58, RFC 2578, April 1999.
[RFC2579] McCloghrie, K., Perkins, D. and J. Schoenwaelder, "Textual
Conventions for SMIv2", STD 59, RFC 2579, April 1999.
[RFC2580] McCloghrie, K., Perkins, D. and J. Schoenwaelder,
"Conformance Statements for SMIv2", STD 60, RFC 2580,
April 1999.
[RFC3159] McCloghrie, K., Fine, M., Seligson, J., Chan, K., Hahn,
S., Sahita, R., Smith, A. and F. Reichmeyer, "Structure of
Policy Provisioning Information (SPPI)", RFC 3159, August
2001.
[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.
[ASN1] International Organization for Standardization,
"Specification of Abstract Syntax Notation One (ASN.1)",
International Standard 8824, December 1987.
[RFC3411] Harrington, D., Presuhn, R. and B. Wijnen, "An
Architecture for Describing Simple Network Management