some other organization.
8.5. Mapping of the NOTIFICATION-TYPE value
The value of an invocation of the NOTIFICATION-TYPE macro is the name
of the notification, which is an OBJECT IDENTIFIER, an
administratively assigned name. In order to achieve compatibility
with the procedures employed by proxy agents (see Section 3.1.2 of
[7]), the next to last sub-identifier in the name of any newly-
defined notification must have the value zero.
Sections 4.2.6 and 4.2.7 of [6] describe how the NOTIFICATION-TYPE
macro is used to generate a SNMPv2-Trap-PDU or InformRequest-PDU,
respectively.
8.6. Usage Example
Consider how a linkUp trap might be described:
linkUp NOTIFICATION-TYPE
OBJECTS { ifIndex }
STATUS current
DESCRIPTION
"A linkUp trap signifies that the SNMPv2 entity, acting in
an agent role, recognizes that one of the communication
links represented in its configuration has come up."
::= { snmpTraps 4 }
According to this invocation, the trap authoritatively identified as
{ snmpTraps 4 }
is used to report a link coming up.
9. Refined Syntax
Some macros have clauses which allows syntax to be refined,
specifically: the SYNTAX clause of the OBJECT-TYPE macro, and the
SYNTAX/WRITE-SYNTAX clauses of the MODULE-COMPLIANCE and AGENT-
CAPABILITIES macros [2]. However, not all refinements of syntax are
appropriate. In particular, the object's primitive or application
type must not be changed.
Further, the following restrictions apply:
Restrictions to Refinement on
object syntax range enumeration size repertoire
----------------- ----- ----------- ---- ----------
INTEGER (1) (2) - -
Integer32 (1) - - -
Unsigned32 (1) - - -
OCTET STRING - - (3) (4)
OBJECT IDENTIFIER - - - -
BITS - (2) - -
IpAddress - - - -
Counter32 - - - -
Counter64 - - - -
Gauge32 (1) - - -
TimeTicks - - - -
where:
(1) the range of permitted values may be refined by raising the lower-
bounds, by reducing the upper-bounds, and/or by reducing the
alternative value/range choices;
(2) the enumeration of named-values may be refined by removing one or
more named-values (note that for BITS, a refinement may cause the
enumerations to no longer be contiguous);
(3) the size in characters of the value may be refined by raising the
lower-bounds, by reducing the upper-bounds, and/or by reducing the
alternative size choices; or,
(4) the repertoire of characters in the value may be reduced by further
sub-typing.
Otherwise no refinements are possible. Further details on sub-typing
are provided in Appendix C.
10. Extending an Information Module
As experience is gained with a published information module, it may
be desirable to revise that information module.
To begin, the invocation of the MODULE-IDENTITY macro should be
updated to include information about the revision. Usually, this
consists of updating the LAST-UPDATED clause and adding a pair of
REVISION and DESCRIPTION clauses. However, other existing clauses in
the invocation may be updated.
Note that the module's label (e.g., "FIZBIN-MIB" from the example in
Section 5.8), is not changed when the information module is revised.
10.1. Object Assignments
If any non-editorial change is made to any clause of a object
assignment, then the OBJECT IDENTIFIER value associated with that
object assignment must also be changed, along with its associated
descriptor.
10.2. Object Definitions
An object definition may be revised in any of the following ways:
(1) A SYNTAX clause containing an enumerated INTEGER may have new
enumerations added or existing labels changed.
(2) A STATUS clause value of "current" may be revised as "deprecated"
or "obsolete". Similarly, a STATUS clause value of "deprecated"
may be revised as "obsolete".
(3) A DEFVAL clause may be added or updated.
(4) A REFERENCE clause may be added or updated.
(5) A UNITS clause may be added.
(6) A conceptual row may be augmented by adding new columnar objects at
the end of the row.
(7) Entirely new objects may be defined, named with previously
unassigned OBJECT IDENTIFIER values.
Otherwise, if the semantics of any previously defined object are
changed (i.e., if a non-editorial change is made to any clause other
those specifically allowed above), then the OBJECT IDENTIFIER value
associated with that object must also be changed.
Note that changing the descriptor associated with an existing object
is considered a semantic change, as these strings may be used in an
IMPORTS statement.
Finally, note that if an object has the value of its STATUS clause
changed, then the value of its DESCRIPTION clause should be updated
accordingly.
10.3. Notification Definitions
A notification definition may be revised in any of the following
ways:
(1) A REFERENCE clause may be added or updated.
Otherwise, if the semantics of any previously defined notification
are changed (i.e., if a non-editorial change is made to any clause
other those specifically allowed above), then the OBJECT IDENTIFIER
value associated with that notification must also be changed.
Note that changing the descriptor associated with an existing
notification is considered a semantic change, as these strings may be
used in an IMPORTS statement.
Finally, note that if an object has the value of its STATUS clause
changed, then the value of its DESCRIPTION clause should be updated
accordingly.
11. Appendix A: de-OSIfying a MIB module
There has been an increasing amount of work recently on taking MIBs
defined by other organizations (e.g., the IEEE) and de-osifying them
for use with the Internet-standard network management framework. The
steps to achieve this are straight-forward, though tedious. Of
course, it is helpful to already be experienced in writing MIB
modules for use with the Internet-standard network management
framework.
The first step is to construct a skeletal MIB module, as shown
earlier in Section 5.8. The next step is to categorize the objects
into groups. Optional objects are not permitted. Thus, when a MIB
module is created, optional objects must be placed in a additional
groups, which, if implemented, all objects in the group must be
implemented. For the first pass, it is wisest to simply ignore any
optional objects in the original MIB: experience shows it is better
to define a core MIB module first, containing only essential objects;
later, if experience demands, other objects can be added.
11.1. Managed Object Mapping
Next for each managed object class, determine whether there can exist
multiple instances of that managed object class. If not, then for
each of its attributes, use the OBJECT-TYPE macro to make an
equivalent definition.
Otherwise, if multiple instances of the managed object class can
exist, then define a conceptual table having conceptual rows each
containing a columnar object for each of the managed object class's
attributes. If the managed object class is contained within the
containment tree of another managed object class, then the assignment
of an object is normally required for each of the "distinguished
attributes" of the containing managed object class. If they do not
already exist within the MIB module, then they can be added via the
definition of additional columnar objects in the conceptual row
corresponding to the contained managed object class.
In defining a conceptual row, it is useful to consider the
optimization of network management operations which will act upon its
columnar objects. In particular, it is wisest to avoid defining more
columnar objects within a conceptual row, than can fit in a single
PDU. As a rule of thumb, a conceptual row should contain no more
than approximately 20 objects. Similarly, or as a way to abide by
the "20 object guideline", columnar objects should be grouped into
tables according to the expected grouping of network management
operations upon them. As such, the content of conceptual rows should
reflect typical access scenarios, e.g., they should be organized
along functional lines such as one row for statistics and another row
for parameters, or along usage lines such as commonly-needed objects
versus rarely-needed objects.
On the other hand, the definition of conceptual rows where the number
of columnar objects used as indexes outnumbers the number used to
hold information, should also be avoided. In particular, the
splitting of a managed object class's attributes into many conceptual
tables should not be used as a way to obtain the same degree of
flexibility/complexity as is often found in MIBs with a myriad of
optionals.
11.1.1. Mapping to the SYNTAX clause
When mapping to the SYNTAX clause of the OBJECT-TYPE macro:
(1) An object with BOOLEAN syntax becomes a TruthValue [3].
(2) An object with INTEGER syntax becomes an Integer32.
(3) An object with ENUMERATED syntax becomes an INTEGER with
enumerations, taking any of the values given which can be
represented with an Integer32.
(4) An object with BIT STRING syntax having enumerations becomes a BITS
construct.
(5) An object with BIT STRING syntax but no enumerations becomes an
OCTET STRING.
(6) An object with a character string syntax becomes either an OCTET
STRING, or a DisplayString [3], depending on the repertoire of the
character string.
(7) A non-tabular object with a complex syntax, such as REAL or
EXTERNAL, must be decomposed, usually into an OCTET STRING (if
sensible). As a rule, any object with a complicated syntax should
be avoided.
(8) Tabular objects must be decomposed into rows of columnar objects.
11.1.2. Mapping to the UNITS clause
If the description of this managed object defines a unit-basis, then
mapping to this clause is straight-forward.
11.1.3. Mapping to the MAX-ACCESS clause
This is straight-forward.
11.1.4. Mapping to the STATUS clause
This is straight-forward.
11.1.5. Mapping to the DESCRIPTION clause
This is straight-forward: simply copy the text, making sure that any
embedded double quotation marks are sanitized (i.e., replaced with
single-quotes or removed).
11.1.6. Mapping to the REFERENCE clause
This is straight-forward: simply include a textual reference to the
object being mapped, the document which defines the object, and
perhaps a page number in the document.
11.1.7. Mapping to the INDEX clause
If necessary, decide how instance-identifiers for columnar objects
are to be formed and define this clause accordingly.
11.1.8. Mapping to the DEFVAL clause
Decide if a meaningful default value can be assigned to the object
being mapped, and if so, define the DEFVAL clause accordingly.
11.2. Action Mapping
Actions are modeled as read-write objects, in which writing a
particular value results in a state change. (Usually, as a part of
this state change, some action might take place.)
11.2.1. Mapping to the SYNTAX clause
Usually the Integer32 syntax is used with a distinguished value
provided for each action that the object provides access to. In
addition, there is usually one other distinguished value, which is
the one returned when the object is read.
11.2.2. Mapping to the MAX-ACCESS clause
Always use read-write or read-create.
11.2.3. Mapping to the STATUS clause
This is straight-forward.
11.2.4. Mapping to the DESCRIPTION clause
This is straight-forward: simply copy the text, making sure that any
embedded double quotation marks are sanitized (i.e., replaced with
single-quotes or removed).
11.2.5. Mapping to the REFERENCE clause
This is straight-forward: simply include a textual reference to the
action being mapped, the document which defines the action, and
perhaps a page number in the document.
11.3. Event Mapping
Events are modeled as SNMPv2 notifications using NOTIFICATION-TYPE
macro. However, recall that SNMPv2 emphasizes trap-directed polling.
As such, few, and usually no, notifications, need be defined for any
MIB module.
11.3.1. Mapping to the STATUS clause
This is straight-forward.
11.3.2. Mapping to the DESCRIPTION clause
This is straight-forward: simply copy the text, making sure that any
embedded double quotation marks are sanitized (i.e., replaced with
single-quotes or removed).
11.3.3. Mapping to the REFERENCE clause
This is straight-forward: simply include a textual reference to the
notification being mapped, the document which defines the
notification, and perhaps a page number in the document.
12. Appendix B: UTC Time Format
Several clauses defined in this document use the UTC Time format:
YYMMDDHHMMZ
where: YY - last two digits of year
MM - month (01 through 12)
DD - day of month (01 through 31)
HH - hours (00 through 23)
MM - minutes (00 through 59)
Z - the character "Z" denotes Greenwich Mean Time (GMT).
For example, "9502192015Z" represents 8:15pm GMT on 19 February 1995.
13. Appendix C: Detailed Sub-typing Rules
13.1. Syntax Rules
The syntax rules for sub-typing are given below. Note that while
this syntax is based on ASN.1, it includes some extensions beyond
what is allowed in ASN.1, and a number of ASN.1 constructs are not
allowed by this syntax.
<integerSubType>
::= <empty>
| "(" <range> ["|" <range>]... ")"
<octetStringSubType>
::= <empty>
| "(" "SIZE" "(" <range> ["|" <range>]... ")" ")"
<range>
::= <value>
| <value> ".." <value>
<value>
::= "-" <number>
| <number>
| <hexString>
| <binString>
where:
<empty> is the empty string
<number> is a non-negative integer
<hexString> is a hexadecimal string (i.e. 'xxxx'H)
<binString> is a binary string (i.e. 'xxxx'B)
<range> is further restricted as follows:
- any <value> used in a SIZE clause must be non-negative.
- when a pair of values is specified, the first value
must be less than the second value.
- when multiple ranges are specified, the ranges may
not overlap but may touch. For example, (1..4 | 4..9)
is invalid, and (1..4 | 5..9) is valid.
- the ranges must be a subset of the maximum range of the
base type.
13.2. Examples
Some examples of legal sub-typing:
Integer32 (-20..100)
Integer32 (0..100 | 300..500)
Integer32 (300..500 | 0..100)
Integer32 (0 | 2 | 4 | 6 | 8 | 10)
OCTET STRING (SIZE(0..100))
OCTET STRING (SIZE(0..100 | 300..500))
OCTET STRING (SIZE(0 | 2 | 4 | 6 | 8 | 10))
Some examples of illegal sub-typing:
Integer32 (150..100) -- first greater than second
Integer32 (0..100 | 50..500) -- ranges overlap
Integer32 (0 | 2 | 0 ) -- value duplicated
Integer32 (MIN..-1 | 1..MAX) -- MIN and MAX not allowed
Integer32 ((SIZE (0..34)) -- must not use SIZE
OCTET STRING (0..100) -- must use SIZE
OCTET STRING (SIZE(-10..100)) -- negative SIZE
13.3. Rules for Textual Conventions
Sub-typing of Textual Conventions (see [3]) is allowed but must be
valid. In particular, each range specified for the textual
convention must be a subset of a range specified for the base type.
For example,
Tc1 ::= INTEGER (1..10 | 11..20)
Tc2 ::= Tc1 (2..10 | 12..15) -- is valid
Tc3 ::= Tc1 (4..8) -- is valid
Tc4 ::= Tc1 (8..12) -- is invalid
14. Security Considerations
Security issues are not discussed in this memo.
15. Editor's Address
Keith McCloghrie
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
US
Phone: +1 408 526 5260
EMail: kzm@cisco.com
16. Acknowledgements
This document is the result of significant work by the four major
contributors:
Jeffrey D. Case (SNMP Research, case@snmp.com)
Keith McCloghrie (Cisco Systems, kzm@cisco.com)
Marshall T. Rose (Dover Beach Consulting, mrose@dbc.mtview.ca.us)
Steven Waldbusser (International Network Services, stevew@uni.ins.com)
In addition, the contributions of the SNMPv2 Working Group are
acknowledged. In particular, a special thanks is extended for the
contributions of:
Alexander I. Alten (Novell)
Dave Arneson (Cabletron)
Uri Blumenthal (IBM)
Doug Book (Chipcom)
Kim Curran (Bell-Northern Research)
Jim Galvin (Trusted Information Systems)
Maria Greene (Ascom Timeplex)
Iain Hanson (Digital)
Dave Harrington (Cabletron)
Nguyen Hien (IBM)
Jeff Johnson (Cisco Systems)
Michael Kornegay (Object Quest)
Deirdre Kostick (AT&T Bell Labs)
David Levi (SNMP Research)
Daniel Mahoney (Cabletron)
Bob Natale (ACE*COMM)
Brian O'Keefe (Hewlett Packard)
Andrew Pearson (SNMP Research)
Dave Perkins (Peer Networks)
Randy Presuhn (Peer Networks)
Aleksey Romanov (Quality Quorum)
Shawn Routhier (Epilogue)
Jon Saperia (BGS Systems)
Bob Stewart (Cisco Systems, bstewart@cisco.com), chair
Kaj Tesink (Bellcore)
Glenn Waters (Bell-Northern Research)
Bert Wijnen (IBM)
17. References
[1] Information processing systems - Open Systems Interconnection -
Specification of Abstract Syntax Notation One (ASN.1),
International Organization for Standardization. International
Standard 8824, (December, 1987).
[2] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
S. Waldbusser, "Conformance Statements for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC1904, January 1996.
[3] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
S. Waldbusser, "Textual Conventions for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC1903, January 1996.
[4] Information processing systems - Open Systems Interconnection -
Specification of Basic Encoding Rules for Abstract Syntax Notation
One (ASN.1), International Organization for Standardization.
International Standard 8825, (December, 1987).
[5] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
S. Waldbusser, "Management Information Base for Version 2 of the
Simple Network Management Protocol (SNMPv2)", RFC1907,
January 1996.
[6] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
S. Waldbusser, "Protocol Operations for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC1905, January 1996.
[7] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
S. Waldbusser, "Coexistence between Version 1 and Version 2 of the
Internet-standard Network Management Framework", RFC1908,
January 1996.