home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / rfc / rfc1902 < prev    next >
Text File  |  1996-01-22  |  77KB  |  2,244 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                               SNMPv2 Working Group
  8. Request for Comments: 1902                                       J. Case
  9. Obsoletes: 1442                                      SNMP Research, Inc.
  10. Category: Standards Track                                  K. McCloghrie
  11.                                                      Cisco Systems, Inc.
  12.                                                                  M. Rose
  13.                                             Dover Beach Consulting, Inc.
  14.                                                            S. Waldbusser
  15.                                           International Network Services
  16.                                                             January 1996
  17.  
  18.  
  19.                   Structure of Management Information
  20.                           for Version 2 of the
  21.               Simple Network Management Protocol (SNMPv2)
  22.  
  23. Status of this Memo
  24.  
  25.    This document specifies an Internet standards track protocol for the
  26.    Internet community, and requests discussion and suggestions for
  27.    improvements.  Please refer to the current edition of the "Internet
  28.    Official Protocol Standards" (STD 1) for the standardization state
  29.    and status of this protocol.  Distribution of this memo is unlimited.
  30.  
  31. 1.  Introduction
  32.  
  33.    A management system contains:  several (potentially many) nodes, each
  34.    with a processing entity, termed an agent, which has access to
  35.    management instrumentation; at least one management station; and, a
  36.    management protocol, used to convey management information between
  37.    the agents and management stations.  Operations of the protocol are
  38.    carried out under an administrative framework which defines
  39.    authentication, authorization, access control, and privacy policies.
  40.  
  41.    Management stations execute management applications which monitor and
  42.    control managed elements.  Managed elements are devices such as
  43.    hosts, routers, terminal servers, etc., which are monitored and
  44.    controlled via access to their management information.
  45.  
  46.    Management information is viewed as a collection of managed objects,
  47.    residing in a virtual information store, termed the Management
  48.    Information Base (MIB).  Collections of related objects are defined
  49.    in MIB modules.  These modules are written using an adapted subset of
  50.    OSI's Abstract Syntax Notation One (ASN.1) [1].  It is the purpose of
  51.    this document, the Structure of Management Information (SMI), to
  52.    define that adapted subset, and to assign a set of associated
  53.    administrative values.
  54.  
  55.  
  56.  
  57.  
  58. SNMPv2 Working Group        Standards Track                     [Page 1]
  59.  
  60. RFC 1902                     SMI for SNMPv2                 January 1996
  61.  
  62.  
  63.    The SMI is divided into three parts:  module definitions, object
  64.    definitions, and, notification definitions.
  65.  
  66. (1)  Module definitions are used when describing information modules.
  67.      An ASN.1 macro, MODULE-IDENTITY, is used to concisely convey the
  68.      semantics of an information module.
  69.  
  70. (2)  Object definitions are used when describing managed objects.  An
  71.      ASN.1 macro, OBJECT-TYPE, is used to concisely convey the syntax
  72.      and semantics of a managed object.
  73.  
  74. (3)  Notification definitions are used when describing unsolicited
  75.      transmissions of management information.  An ASN.1 macro,
  76.      NOTIFICATION-TYPE, is used to concisely convey the syntax and
  77.      semantics of a notification.
  78.  
  79. 1.1.  A Note on Terminology
  80.  
  81.    For the purpose of exposition, the original Internet-standard Network
  82.    Management Framework, as described in RFCs 1155 (STD 16), 1157 (STD
  83.    15), and 1212 (STD 16), is termed the SNMP version 1 framework
  84.    (SNMPv1).  The current framework is termed the SNMP version 2
  85.    framework (SNMPv2).
  86.  
  87. 2.  Definitions
  88.  
  89. SNMPv2-SMI DEFINITIONS ::= BEGIN
  90.  
  91.  
  92. -- the path to the root
  93.  
  94. org            OBJECT IDENTIFIER ::= { iso 3 }
  95. dod            OBJECT IDENTIFIER ::= { org 6 }
  96. internet       OBJECT IDENTIFIER ::= { dod 1 }
  97.  
  98. directory      OBJECT IDENTIFIER ::= { internet 1 }
  99.  
  100. mgmt           OBJECT IDENTIFIER ::= { internet 2 }
  101. mib-2          OBJECT IDENTIFIER ::= { mgmt 1 }
  102. transmission   OBJECT IDENTIFIER ::= { mib-2 10 }
  103.  
  104. experimental   OBJECT IDENTIFIER ::= { internet 3 }
  105.  
  106. private        OBJECT IDENTIFIER ::= { internet 4 }
  107. enterprises    OBJECT IDENTIFIER ::= { private 1 }
  108.  
  109. security       OBJECT IDENTIFIER ::= { internet 5 }
  110.  
  111.  
  112.  
  113.  
  114. SNMPv2 Working Group        Standards Track                     [Page 2]
  115.  
  116. RFC 1902                     SMI for SNMPv2                 January 1996
  117.  
  118.  
  119. snmpV2         OBJECT IDENTIFIER ::= { internet 6 }
  120.  
  121. -- transport domains
  122. snmpDomains    OBJECT IDENTIFIER ::= { snmpV2 1 }
  123.  
  124. -- transport proxies
  125. snmpProxys     OBJECT IDENTIFIER ::= { snmpV2 2 }
  126.  
  127. -- module identities
  128. snmpModules    OBJECT IDENTIFIER ::= { snmpV2 3 }
  129.  
  130.  
  131. -- definitions for information modules
  132.  
  133. MODULE-IDENTITY MACRO ::=
  134. BEGIN
  135.     TYPE NOTATION ::=
  136.                   "LAST-UPDATED" value(Update UTCTime)
  137.                   "ORGANIZATION" Text
  138.                   "CONTACT-INFO" Text
  139.                   "DESCRIPTION" Text
  140.                   RevisionPart
  141.  
  142.     VALUE NOTATION ::=
  143.                   value(VALUE OBJECT IDENTIFIER)
  144.  
  145.     RevisionPart ::=
  146.                   Revisions
  147.                 | empty
  148.     Revisions ::=
  149.                   Revision
  150.                 | Revisions Revision
  151.     Revision ::=
  152.                   "REVISION" value(Update UTCTime)
  153.                   "DESCRIPTION" Text
  154.  
  155.     -- uses the NVT ASCII character set
  156.     Text ::= """" string """"
  157. END
  158.  
  159.  
  160. OBJECT-IDENTITY MACRO ::=
  161. BEGIN
  162.     TYPE NOTATION ::=
  163.                   "STATUS" Status
  164.                   "DESCRIPTION" Text
  165.                   ReferPart
  166.  
  167.  
  168.  
  169.  
  170. SNMPv2 Working Group        Standards Track                     [Page 3]
  171.  
  172. RFC 1902                     SMI for SNMPv2                 January 1996
  173.  
  174.  
  175.     VALUE NOTATION ::=
  176.                   value(VALUE OBJECT IDENTIFIER)
  177.  
  178.     Status ::=
  179.                   "current"
  180.                 | "deprecated"
  181.                 | "obsolete"
  182.  
  183.     ReferPart ::=
  184.                 "REFERENCE" Text
  185.               | empty
  186.  
  187.     Text ::= """" string """"
  188. END
  189.  
  190.  
  191. -- names of objects
  192.  
  193. ObjectName ::=
  194.     OBJECT IDENTIFIER
  195.  
  196. NotificationName ::=
  197.     OBJECT IDENTIFIER
  198.  
  199. -- syntax of objects
  200.  
  201. ObjectSyntax ::=
  202.     CHOICE {
  203.         simple
  204.             SimpleSyntax,
  205.  
  206.           -- note that SEQUENCEs for conceptual tables and
  207.           -- rows are not mentioned here...
  208.  
  209.         application-wide
  210.             ApplicationSyntax
  211.     }
  212.  
  213.  
  214. -- built-in ASN.1 types
  215.  
  216. SimpleSyntax ::=
  217.     CHOICE {
  218.         -- INTEGERs with a more restrictive range
  219.         -- may also be used
  220.         integer-value               -- includes Integer32
  221.             INTEGER (-2147483648..2147483647),
  222.  
  223.  
  224.  
  225.  
  226. SNMPv2 Working Group        Standards Track                     [Page 4]
  227.  
  228. RFC 1902                     SMI for SNMPv2                 January 1996
  229.  
  230.  
  231.         -- OCTET STRINGs with a more restrictive size
  232.         -- may also be used
  233.         string-value
  234.             OCTET STRING (SIZE (0..65535)),
  235.  
  236.         objectID-value
  237.             OBJECT IDENTIFIER
  238.     }
  239.  
  240.  
  241. -- indistinguishable from INTEGER, but never needs more than
  242. -- 32-bits for a two's complement representation
  243. Integer32 ::=
  244.     [UNIVERSAL 2]
  245.         IMPLICIT INTEGER (-2147483648..2147483647)
  246.  
  247.  
  248. -- application-wide types
  249.  
  250. ApplicationSyntax ::=
  251.     CHOICE {
  252.         ipAddress-value
  253.             IpAddress,
  254.  
  255.         counter-value
  256.             Counter32,
  257.  
  258.         timeticks-value
  259.             TimeTicks,
  260.  
  261.         arbitrary-value
  262.             Opaque,
  263.  
  264.         big-counter-value
  265.             Counter64,
  266.  
  267.         unsigned-integer-value  -- includes Gauge32
  268.             Unsigned32
  269.     }
  270.  
  271. -- in network-byte order
  272. -- (this is a tagged type for historical reasons)
  273. IpAddress ::=
  274.     [APPLICATION 0]
  275.         IMPLICIT OCTET STRING (SIZE (4))
  276.  
  277. -- this wraps
  278. Counter32 ::=
  279.  
  280.  
  281.  
  282. SNMPv2 Working Group        Standards Track                     [Page 5]
  283.  
  284. RFC 1902                     SMI for SNMPv2                 January 1996
  285.  
  286.  
  287.     [APPLICATION 1]
  288.         IMPLICIT INTEGER (0..4294967295)
  289.  
  290. -- this doesn't wrap
  291. Gauge32 ::=
  292.     [APPLICATION 2]
  293.         IMPLICIT INTEGER (0..4294967295)
  294.  
  295. -- an unsigned 32-bit quantity
  296. -- indistinguishable from Gauge32
  297. Unsigned32 ::=
  298.     [APPLICATION 2]
  299.         IMPLICIT INTEGER (0..4294967295)
  300.  
  301. -- hundredths of seconds since an epoch
  302. TimeTicks ::=
  303.     [APPLICATION 3]
  304.         IMPLICIT INTEGER (0..4294967295)
  305.  
  306. -- for backward-compatibility only
  307. Opaque ::=
  308.     [APPLICATION 4]
  309.         IMPLICIT OCTET STRING
  310.  
  311. -- for counters that wrap in less than one hour with only 32 bits
  312. Counter64 ::=
  313.     [APPLICATION 6]
  314.         IMPLICIT INTEGER (0..18446744073709551615)
  315.  
  316.  
  317. -- definition for objects
  318.  
  319. OBJECT-TYPE MACRO ::=
  320. BEGIN
  321.     TYPE NOTATION ::=
  322.                   "SYNTAX" Syntax
  323.                   UnitsPart
  324.                   "MAX-ACCESS" Access
  325.                   "STATUS" Status
  326.                   "DESCRIPTION" Text
  327.                   ReferPart
  328.                   IndexPart
  329.                   DefValPart
  330.  
  331.     VALUE NOTATION ::=
  332.                   value(VALUE ObjectName)
  333.  
  334.     Syntax ::=
  335.  
  336.  
  337.  
  338. SNMPv2 Working Group        Standards Track                     [Page 6]
  339.  
  340. RFC 1902                     SMI for SNMPv2                 January 1996
  341.  
  342.  
  343.                   type(ObjectSyntax)
  344.                 | "BITS" "{" Kibbles "}"
  345.     Kibbles ::=
  346.                   Kibble
  347.                 | Kibbles "," Kibble
  348.     Kibble ::=
  349.                  identifier "(" nonNegativeNumber ")"
  350.  
  351.     UnitsPart ::=
  352.                   "UNITS" Text
  353.                 | empty
  354.  
  355.     Access ::=
  356.                   "not-accessible"
  357.                 | "accessible-for-notify"
  358.                 | "read-only"
  359.                 | "read-write"
  360.                 | "read-create"
  361.  
  362.     Status ::=
  363.                   "current"
  364.                 | "deprecated"
  365.                 | "obsolete"
  366.  
  367.     ReferPart ::=
  368.                   "REFERENCE" Text
  369.                 | empty
  370.  
  371.     IndexPart ::=
  372.                   "INDEX"    "{" IndexTypes "}"
  373.                 | "AUGMENTS" "{" Entry      "}"
  374.                 | empty
  375.     IndexTypes ::=
  376.                   IndexType
  377.                 | IndexTypes "," IndexType
  378.     IndexType ::=
  379.                   "IMPLIED" Index
  380.                 | Index
  381.     Index ::=
  382.                     -- use the SYNTAX value of the
  383.                     -- correspondent OBJECT-TYPE invocation
  384.                   value(Indexobject ObjectName)
  385.     Entry ::=
  386.                     -- use the INDEX value of the
  387.                     -- correspondent OBJECT-TYPE invocation
  388.                   value(Entryobject ObjectName)
  389.  
  390.     DefValPart ::=
  391.  
  392.  
  393.  
  394. SNMPv2 Working Group        Standards Track                     [Page 7]
  395.  
  396. RFC 1902                     SMI for SNMPv2                 January 1996
  397.  
  398.  
  399.                   "DEFVAL" "{" value(Defval Syntax) "}"
  400.                 | empty
  401.  
  402.     -- uses the NVT ASCII character set
  403.     Text ::= """" string """"
  404. END
  405.  
  406.  
  407. -- definitions for notifications
  408.  
  409. NOTIFICATION-TYPE MACRO ::=
  410. BEGIN
  411.     TYPE NOTATION ::=
  412.                   ObjectsPart
  413.                   "STATUS" Status
  414.                   "DESCRIPTION" Text
  415.                   ReferPart
  416.  
  417.     VALUE NOTATION ::=
  418.                   value(VALUE NotificationName)
  419.  
  420.     ObjectsPart ::=
  421.                   "OBJECTS" "{" Objects "}"
  422.                 | empty
  423.     Objects ::=
  424.                   Object
  425.                 | Objects "," Object
  426.     Object ::=
  427.                   value(Name ObjectName)
  428.  
  429.     Status ::=
  430.                   "current"
  431.                 | "deprecated"
  432.                 | "obsolete"
  433.  
  434.     ReferPart ::=
  435.                 "REFERENCE" Text
  436.               | empty
  437.  
  438.     -- uses the NVT ASCII character set
  439.     Text ::= """" string """"
  440. END
  441.  
  442. -- definitions of administrative identifiers
  443.  
  444. zeroDotZero    OBJECT-IDENTITY
  445.     STATUS     current
  446.     DESCRIPTION
  447.  
  448.  
  449.  
  450. SNMPv2 Working Group        Standards Track                     [Page 8]
  451.  
  452. RFC 1902                     SMI for SNMPv2                 January 1996
  453.  
  454.  
  455.             "A value used for null identifiers."
  456.     ::= { 0 0 }
  457.  
  458. END
  459.  
  460. 3.  Information Modules
  461.  
  462.    An "information module" is an ASN.1 module defining information
  463.    relating to network management.
  464.  
  465.    The SMI describes how to use a subset of ASN.1 to define an
  466.    information module.  Further, additional restrictions are placed on
  467.    "standard" information modules.  It is strongly recommended that
  468.    "enterprise-specific" information modules also adhere to these
  469.    restrictions.
  470.  
  471.    Typically, there are three kinds of information modules:
  472.  
  473. (1)  MIB modules, which contain definitions of inter-related managed
  474.      objects, make use of the OBJECT-TYPE and NOTIFICATION-TYPE macros;
  475.  
  476. (2)  compliance statements for MIB modules, which make use of the
  477.      MODULE-COMPLIANCE and OBJECT-GROUP macros [2]; and,
  478.  
  479. (3)  capability statements for agent implementations which make use of
  480.      the AGENT-CAPABILITIES macros [2].
  481.  
  482.    This classification scheme does not imply a rigid taxonomy.  For
  483.    example, a "standard" information module will normally include
  484.    definitions of managed objects and a compliance statement.
  485.    Similarly, an "enterprise-specific" information module might include
  486.    definitions of managed objects and a capability statement.  Of
  487.    course, a "standard" information module may not contain capability
  488.    statements.
  489.  
  490.    The constructs of ASN.1 allowed in SNMPv2 information modules
  491.    include: the IMPORTS clause, value definitions for OBJECT
  492.    IDENTIFIERs, type definitions for SEQUENCEs (with restrictions),
  493.    ASN.1 type assignments of the restricted ASN.1 types allowed in
  494.    SNMPv2, and instances of ASN.1 macros defined in this document and in
  495.    other documents [2, 3] of the SNMPv2 framework.  Additional ASN.1
  496.    macros may not be defined in SNMPv2 information modules.
  497.  
  498.    The names of all standard information modules must be unique (but
  499.    different versions of the same information module should have the
  500.    same name).  Developers of enterprise information modules are
  501.    encouraged to choose names for their information modules that will
  502.    have a low probability of colliding with standard or other enterprise
  503.  
  504.  
  505.  
  506. SNMPv2 Working Group        Standards Track                     [Page 9]
  507.  
  508. RFC 1902                     SMI for SNMPv2                 January 1996
  509.  
  510.  
  511.    information modules. An information module may not use the ASN.1
  512.    construct of placing an object identifier value between the module
  513.    name and the "DEFINITIONS" keyword.
  514.  
  515.    All information modules start with exactly one invocation of the
  516.    MODULE-IDENTITY macro, which provides contact information as well as
  517.    revision history to distinguish between versions of the same
  518.    information module.  This invocation must appear immediately after
  519.    any IMPORTs statements.
  520.  
  521. 3.1.  Macro Invocation
  522.  
  523.    Within an information module, each macro invocation appears as:
  524.  
  525.      <descriptor> <macro> <clauses> ::= <value>
  526.  
  527.    where <descriptor> corresponds to an ASN.1 identifier, <macro> names
  528.    the macro being invoked, and <clauses> and <value> depend on the
  529.    definition of the macro.  (Note that this definition of a descriptor
  530.    applies to all macros defined in this memo and in [2].)
  531.  
  532.    For the purposes of this specification, an ASN.1 identifier consists
  533.    of one or more letters or digits, and its initial character must be a
  534.    lower-case letter.  (Note that hyphens are not allowed by this
  535.    specification, even though hyphen is allowed by [1].  This
  536.    restriction enables arithmetic expressions in languages which use the
  537.    minus sign to reference these descriptors without ambiguity.)
  538.  
  539.    For all descriptors appearing in an information module, the
  540.    descriptor shall be unique and mnemonic, and shall not exceed 64
  541.    characters in length.  (However, descriptors longer than 32
  542.    characters are not recommended.)  This promotes a common language for
  543.    humans to use when discussing the information module and also
  544.    facilitates simple table mappings for user-interfaces.
  545.  
  546.    The set of descriptors defined in all "standard" information modules
  547.    shall be unique.
  548.  
  549.    Finally, by convention, if the descriptor refers to an object with a
  550.    SYNTAX clause value of either Counter32 or Counter64, then the
  551.    descriptor used for the object should denote plurality.
  552.  
  553. 3.1.1.  Textual Clauses
  554.  
  555.    Some clauses in a macro invocation may take a textual value (e.g.,
  556.    the DESCRIPTION clause).  Note that, in order to conform to the ASN.1
  557.    syntax, the entire value of these clauses must be enclosed in double
  558.    quotation marks, and therefore cannot itself contain double quotation
  559.  
  560.  
  561.  
  562. SNMPv2 Working Group        Standards Track                    [Page 10]
  563.  
  564. RFC 1902                     SMI for SNMPv2                 January 1996
  565.  
  566.  
  567.    marks, although the value may be multi-line.
  568.  
  569. 3.2.  IMPORTing Symbols
  570.  
  571.    To reference an external object, the IMPORTS statement must be used
  572.    to identify both the descriptor and the module in which the
  573.    descriptor is defined, where the module is identified by its ASN.1
  574.    module name.
  575.  
  576.    Note that when symbols from "enterprise-specific" information modules
  577.    are referenced  (e.g., a descriptor), there is the possibility of
  578.    collision.  As such, if different objects with the same descriptor
  579.    are IMPORTed, then this ambiguity is resolved by prefixing the
  580.    descriptor with the name of the information module and a dot ("."),
  581.    i.e.,
  582.  
  583.      "module.descriptor"
  584.  
  585.    (All descriptors must be unique within any information module.)
  586.  
  587.    Of course, this notation can be used even when there is no collision
  588.    when IMPORTing symbols.
  589.  
  590.    Finally, the IMPORTS statement may not be used to import an ASN.1
  591.    named type which corresponds to either the SEQUENCE or SEQUENCE OF
  592.    type.
  593.  
  594. 3.3.  Exporting Symbols
  595.  
  596.    The ASN.1 EXPORTS statement is not allowed in SNMPv2 information
  597.    modules.  All items defined in an information module are
  598.    automatically exported.
  599.  
  600. 3.4.  ASN.1 Comments
  601.  
  602.    Comments in ASN.1 commence with a pair of adjacent hyphens and end
  603.    with the next pair of adjacent hyphens or at the end of the line,
  604.    whichever occurs first.
  605.  
  606. 3.5.  OBJECT IDENTIFIER values
  607.  
  608.    An OBJECT IDENTIFIER value is an ordered list of non-negative
  609.    numbers.  For the SNMPv2 framework, each number in the list is
  610.    referred to as a sub-identifier, there are at most 128 sub-
  611.    identifiers in a value, and each sub-identifier has a maximum value
  612.    of 2^32-1 (4294967295 decimal).  All OBJECT IDENTIFIER values have at
  613.    least two sub-identifiers, where the value of the first sub-
  614.    identifier is one of the following well-known names:
  615.  
  616.  
  617.  
  618. SNMPv2 Working Group        Standards Track                    [Page 11]
  619.  
  620. RFC 1902                     SMI for SNMPv2                 January 1996
  621.  
  622.  
  623.      Value   Name
  624.        0     ccitt
  625.        1     iso
  626.        2     joint-iso-ccitt
  627.  
  628. 4.  Naming Hierarchy
  629.  
  630.    The root of the subtree administered by the Internet Assigned Numbers
  631.    Authority (IANA) for the Internet is:
  632.  
  633.      internet       OBJECT IDENTIFIER ::= { iso 3 6 1 }
  634.  
  635.    That is, the Internet subtree of OBJECT IDENTIFIERs starts with the
  636.    prefix:
  637.  
  638.      1.3.6.1.
  639.  
  640.    Several branches underneath this subtree are used for network
  641.    management:
  642.  
  643.      mgmt           OBJECT IDENTIFIER ::= { internet 2 }
  644.      experimental   OBJECT IDENTIFIER ::= { internet 3 }
  645.      private        OBJECT IDENTIFIER ::= { internet 4 }
  646.      enterprises    OBJECT IDENTIFIER ::= { private 1 }
  647.  
  648.    However, the SMI does not prohibit the definition of objects in other
  649.    portions of the object tree.
  650.  
  651.    The mgmt(2) subtree is used to identify "standard" objects.
  652.  
  653.    The experimental(3) subtree is used to identify objects being
  654.    designed by working groups of the IETF.  If an information module
  655.    produced by a working group becomes a "standard" information module,
  656.    then at the very beginning of its entry onto the Internet standards
  657.    track, the objects are moved under the mgmt(2) subtree.
  658.  
  659.    The private(4) subtree is used to identify objects defined
  660.    unilaterally.  The enterprises(1) subtree beneath private is used,
  661.    among other things, to permit providers of networking subsystems to
  662.    register models of their products.
  663.  
  664. 5.  Mapping of the MODULE-IDENTITY macro
  665.  
  666.    The MODULE-IDENTITY macro is used to provide contact and revision
  667.    history for each information module.  It must appear exactly once in
  668.    every information module.  It should be noted that the expansion of
  669.    the MODULE-IDENTITY macro is something which conceptually happens
  670.    during implementation and not during run-time.
  671.  
  672.  
  673.  
  674. SNMPv2 Working Group        Standards Track                    [Page 12]
  675.  
  676. RFC 1902                     SMI for SNMPv2                 January 1996
  677.  
  678.  
  679.    Note that reference in an IMPORTS clause or in clauses of SNMPv2
  680.    macros to an information module is NOT through the use of the
  681.    'descriptor' of a MODULE-IDENTITY macro; rather, an information
  682.    module is referenced through specifying its module name.
  683.  
  684. 5.1.  Mapping of the LAST-UPDATED clause
  685.  
  686.    The LAST-UPDATED clause, which must be present, contains the date and
  687.    time that this information module was last edited.  The date and time
  688.    are represented in UTC Time format (see Appendix B).
  689.  
  690. 5.2.  Mapping of the ORGANIZATION clause
  691.  
  692.    The ORGANIZATION clause, which must be present, contains a textual
  693.    description of the organization under whose auspices this information
  694.    module was developed.
  695.  
  696. 5.3.  Mapping of the CONTACT-INFO clause
  697.  
  698.    The CONTACT-INFO clause, which must be present, contains the name,
  699.    postal address, telephone number, and electronic mail address of the
  700.    person to whom technical queries concerning this information module
  701.    should be sent.
  702.  
  703. 5.4.  Mapping of the DESCRIPTION clause
  704.  
  705.    The DESCRIPTION clause, which must be present, contains a high-level
  706.    textual description of the contents of this information module.
  707.  
  708. 5.5.  Mapping of the REVISION clause
  709.  
  710.    The REVISION clause, which need not be present, is repeatedly used to
  711.    describe the revisions (including the initial version) made to this
  712.    information module, in reverse chronological order (i.e., most recent
  713.    first).  Each instance of this clause contains the date and time of
  714.    the revision.  The date and time are represented in UTC Time format
  715.    (see Appendix B).
  716.  
  717. 5.5.1.  Mapping of the DESCRIPTION sub-clause
  718.  
  719.    The DESCRIPTION clause, which must be present for each REVISION
  720.    clause, contains a high-level textual description of the revision
  721.    identified in that REVISION clause.
  722.  
  723. 5.6.  Mapping of the MODULE-IDENTITY value
  724.  
  725.    The value of an invocation of the MODULE-IDENTITY macro is an OBJECT
  726.    IDENTIFIER.  As such, this value may be authoritatively used when
  727.  
  728.  
  729.  
  730. SNMPv2 Working Group        Standards Track                    [Page 13]
  731.  
  732. RFC 1902                     SMI for SNMPv2                 January 1996
  733.  
  734.  
  735.    specifying an OBJECT IDENTIFIER value to refer to the information
  736.    module containing the invocation.
  737.  
  738. 5.7.  Usage Example
  739.  
  740.    Consider how a skeletal MIB module might be constructed:  e.g.,
  741.  
  742. FIZBIN-MIB DEFINITIONS ::= BEGIN
  743.  
  744. IMPORTS
  745.     MODULE-IDENTITY, OBJECT-TYPE, experimental
  746.         FROM SNMPv2-SMI;
  747.  
  748.  
  749. fizbin MODULE-IDENTITY
  750.     LAST-UPDATED "9505241811Z"
  751.     ORGANIZATION "IETF SNMPv2 Working Group"
  752.     CONTACT-INFO
  753.             "        Marshall T. Rose
  754.  
  755.              Postal: Dover Beach Consulting, Inc.
  756.                      420 Whisman Court
  757.                      Mountain View, CA  94043-2186
  758.                      US
  759.  
  760.                 Tel: +1 415 968 1052
  761.                 Fax: +1 415 968 2510
  762.  
  763.              E-mail: mrose@dbc.mtview.ca.us"
  764.     DESCRIPTION
  765.             "The MIB module for entities implementing the xxxx
  766.             protocol."
  767.     REVISION      "9505241811Z"
  768.     DESCRIPTION
  769.             "The latest version of this MIB module."
  770.     REVISION      "9210070433Z"
  771.     DESCRIPTION
  772.             "The initial version of this MIB module."
  773. -- contact IANA for actual number
  774.     ::= { experimental xx }
  775.  
  776.  
  777. END
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786. SNMPv2 Working Group        Standards Track                    [Page 14]
  787.  
  788. RFC 1902                     SMI for SNMPv2                 January 1996
  789.  
  790.  
  791. 6.  Mapping of the OBJECT-IDENTITY macro
  792.  
  793.    The OBJECT-IDENTITY macro is used to define information about an
  794.    OBJECT IDENTIFIER assignment.  All administrative OBJECT IDENTIFIER
  795.    assignments which define a type identification value (see
  796.    AutonomousType, a textual convention defined in [3]) should be
  797.    defined via the OBJECT-IDENTITY macro.  It should be noted that the
  798.    expansion of the OBJECT-IDENTITY macro is something which
  799.    conceptually happens during implementation and not during run-time.
  800.  
  801. 6.1.  Mapping of the STATUS clause
  802.  
  803.    The STATUS clause, which must be present, indicates whether this
  804.    definition is current or historic.
  805.  
  806.    The values "current", and "obsolete" are self-explanatory.  The
  807.    "deprecated" value indicates that the definition is obsolete, but
  808.    that an implementor may wish to support it to foster interoperability
  809.    with older implementations.
  810.  
  811. 6.2.  Mapping of the DESCRIPTION clause
  812.  
  813.    The DESCRIPTION clause, which must be present, contains a textual
  814.    description of the object assignment.
  815.  
  816. 6.3.  Mapping of the REFERENCE clause
  817.  
  818.    The REFERENCE clause, which need not be present, contains a textual
  819.    cross-reference to an object assignment defined in some other
  820.    information module.
  821.  
  822. 6.4.  Mapping of the OBJECT-IDENTITY value
  823.  
  824.    The value of an invocation of the OBJECT-IDENTITY macro is an OBJECT
  825.    IDENTIFIER.
  826.  
  827. 6.5.  Usage Example
  828.  
  829.    Consider how an OBJECT IDENTIFIER assignment might be made:  e.g.,
  830.  
  831. fizbin69 OBJECT-IDENTITY
  832.     STATUS  current
  833.     DESCRIPTION
  834.             "The authoritative identity of the Fizbin 69 chipset."
  835.     ::= { fizbinChipSets 1 }
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842. SNMPv2 Working Group        Standards Track                    [Page 15]
  843.  
  844. RFC 1902                     SMI for SNMPv2                 January 1996
  845.  
  846.  
  847. 7.  Mapping of the OBJECT-TYPE macro
  848.  
  849.    The OBJECT-TYPE macro is used to define a type of managed object.  It
  850.    should be noted that the expansion of the OBJECT-TYPE macro is
  851.    something which conceptually happens during implementation and not
  852.    during run-time.
  853.  
  854.    For leaf objects which are not columnar objects (i.e., not contained
  855.    within a conceptual table), instances of the object are identified by
  856.    appending a sub-identifier of zero to the name of that object.
  857.    Otherwise, the INDEX clause of the conceptual row object superior to
  858.    a columnar object defines instance identification information.
  859.  
  860. 7.1.  Mapping of the SYNTAX clause
  861.  
  862.    The SYNTAX clause, which must be present, defines the abstract data
  863.    structure corresponding to that object.  The data structure must be
  864.    one of the following: a base type, the BITS construct, or a textual
  865.    convention.  (SEQUENCE OF and SEQUENCE are also possible for
  866.    conceptual tables, see section 7.1.12).  The base types are those
  867.    defined in the ObjectSyntax CHOICE.  A textual convention is a
  868.    newly-defined type defined as a sub-type of a base type [3].
  869.  
  870.    A extended subset of the full capabilities of ASN.1 sub-typing is
  871.    allowed, as appropriate to the underingly ASN.1 type.  Any such
  872.    restriction on size, range, enumerations or repertoire specified in
  873.    this clause represents the maximal level of support which makes
  874.    "protocol sense".  Restrictions on sub-typing are specified in detail
  875.    in Section 9 and Appendix C of this memo.
  876.  
  877.    The semantics of ObjectSyntax are now described.
  878.  
  879. 7.1.1.  Integer32 and INTEGER
  880.  
  881.    The Integer32 type represents integer-valued information between
  882.    -2^31 and 2^31-1 inclusive (-2147483648 to 2147483647 decimal).  This
  883.    type is indistinguishable from the INTEGER type.  Both the INTEGER
  884.    and Integer32 types may be sub-typed to be more constrained than the
  885.    Integer32 type.
  886.  
  887.    The INTEGER type may also be used to represent integer-valued
  888.    information as named-number enumerations.  In this case, only those
  889.    named-numbers so enumerated may be present as a value.  Note that
  890.    although it is recommended that enumerated values start at 1 and be
  891.    numbered contiguously, any valid value for Integer32 is allowed for
  892.    an enumerated value and, further, enumerated values needn't be
  893.    contiguously assigned.
  894.  
  895.  
  896.  
  897.  
  898. SNMPv2 Working Group        Standards Track                    [Page 16]
  899.  
  900. RFC 1902                     SMI for SNMPv2                 January 1996
  901.  
  902.  
  903.    Finally, a label for a named-number enumeration must consist of one
  904.    or more letters or digits (no hyphens), up to a maximum of 64
  905.    characters, and the initial character must be a lower-case letter.
  906.    (However, labels longer than 32 characters are not recommended.)
  907.  
  908. 7.1.2.  OCTET STRING
  909.  
  910.    The OCTET STRING type represents arbitrary binary or textual data.
  911.    Although there is no SMI-specified size limitation for this type, MIB
  912.    designers should realize that there may be implementation and
  913.    interoperability limitations for sizes in excess of 255 octets.
  914.  
  915. 7.1.3.  OBJECT IDENTIFIER
  916.  
  917.    The OBJECT IDENTIFIER type represents administratively assigned
  918.    names.  Any instance of this type may have at most 128 sub-
  919.    identifiers.  Further, each sub-identifier must not exceed the value
  920.    2^32-1 (4294967295 decimal).
  921.  
  922. 7.1.4.  The BITS construct
  923.  
  924.    The BITS construct represents an enumeration of named bits.  This
  925.    collection is assigned non-negative, contiguous values, starting at
  926.    zero.  Only those named-bits so enumerated may be present in a value.
  927.    (Thus, enumerations must be assigned to consecutive bits; however,
  928.    see Section 9 for refinements of an object with this syntax.)
  929.  
  930.    Although there is no SMI-specified limitation on the number of
  931.    enumerations (and therefore on the length of a value), MIB designers
  932.    should realize that there may be implementation and interoperability
  933.    limitations for sizes in excess of 128 bits.
  934.  
  935.    Finally, a label for a named-number enumeration must consist of one
  936.    or more letters or digits (no hyphens), up to a maximum of 64
  937.    characters, and the initial character must be a lower-case letter.
  938.    (However, labels longer than 32 characters are not recommended.)
  939.  
  940. 7.1.5.  IpAddress
  941.  
  942.    The IpAddress type represents a 32-bit internet address.  It is
  943.    represented as an OCTET STRING of length 4, in network byte-order.
  944.  
  945.    Note that the IpAddress type is a tagged type for historical reasons.
  946.    Network addresses should be represented using an invocation of the
  947.    TEXTUAL-CONVENTION macro [3].
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954. SNMPv2 Working Group        Standards Track                    [Page 17]
  955.  
  956. RFC 1902                     SMI for SNMPv2                 January 1996
  957.  
  958.  
  959. 7.1.6.  Counter32
  960.  
  961.    The Counter32 type represents a non-negative integer which
  962.    monotonically increases until it reaches a maximum value of 2^32-1
  963.    (4294967295 decimal), when it wraps around and starts increasing
  964.    again from zero.
  965.  
  966.    Counters have no defined "initial" value, and thus, a single value of
  967.    a Counter has (in general) no information content.  Discontinuities
  968.    in the monotonically increasing value normally occur at re-
  969.    initialization of the management system, and at other times as
  970.    specified in the description of an object-type using this ASN.1 type.
  971.    If such other times can occur, for example, the creation of an object
  972.    instance at times other than re-initialization, then a corresponding
  973.    object should be defined with a SYNTAX clause value of TimeStamp (a
  974.    textual convention defined in [3]) indicating the time of the last
  975.    discontinuity.
  976.  
  977.    The value of the MAX-ACCESS clause for objects with a SYNTAX clause
  978.    value of Counter32 is either "read-only" or "accessible-for-notify".
  979.  
  980.    A DEFVAL clause is not allowed for objects with a SYNTAX clause value
  981.    of Counter32.
  982.  
  983. 7.1.7.  Gauge32
  984.  
  985.    The Gauge32 type represents a non-negative integer, which may
  986.    increase or decrease, but shall never exceed a maximum value.  The
  987.    maximum value can not be greater than 2^32-1 (4294967295 decimal).
  988.    The value of a Gauge has its maximum value whenever the information
  989.    being modeled is greater or equal to that maximum value; if the
  990.    information being modeled subsequently decreases below the maximum
  991.    value, the Gauge also decreases.
  992.  
  993. 7.1.8.  TimeTicks
  994.  
  995.    The TimeTicks type represents a non-negative integer which represents
  996.    the time, modulo 2^32 (4294967296 decimal), in hundredths of a second
  997.    between two epochs.  When objects are defined which use this ASN.1
  998.    type, the description of the object identifies both of the reference
  999.    epochs.
  1000.  
  1001.    For example, [3] defines the TimeStamp textual convention which is
  1002.    based on the TimeTicks type.  With a TimeStamp, the first reference
  1003.    epoch is defined as the time when sysUpTime [5] was zero, and the
  1004.    second reference epoch is defined as the current value of sysUpTime.
  1005.  
  1006.    The TimeTicks type may not be sub-typed.
  1007.  
  1008.  
  1009.  
  1010. SNMPv2 Working Group        Standards Track                    [Page 18]
  1011.  
  1012. RFC 1902                     SMI for SNMPv2                 January 1996
  1013.  
  1014.  
  1015. 7.1.9.  Opaque
  1016.  
  1017.    The Opaque type is provided solely for backward-compatibility, and
  1018.    shall not be used for newly-defined object types.
  1019.  
  1020.    The Opaque type supports the capability to pass arbitrary ASN.1
  1021.    syntax.  A value is encoded using the ASN.1 Basic Encoding Rules [4]
  1022.    into a string of octets.  This, in turn, is encoded as an OCTET
  1023.    STRING, in effect "double-wrapping" the original ASN.1 value.
  1024.  
  1025.    Note that a conforming implementation need only be able to accept and
  1026.    recognize opaquely-encoded data.  It need not be able to unwrap the
  1027.    data and then interpret its contents.
  1028.  
  1029.    A requirement on "standard" MIB modules is that no object may have a
  1030.    SYNTAX clause value of Opaque.
  1031.  
  1032. 7.1.10.  Counter64
  1033.  
  1034.    The Counter64 type represents a non-negative integer which
  1035.    monotonically increases until it reaches a maximum value of 2^64-1
  1036.    (18446744073709551615 decimal), when it wraps around and starts
  1037.    increasing again from zero.
  1038.  
  1039.    Counters have no defined "initial" value, and thus, a single value of
  1040.    a Counter has (in general) no information content.  Discontinuities
  1041.    in the monotonically increasing value normally occur at re-
  1042.    initialization of the management system, and at other times as
  1043.    specified in the description of an object-type using this ASN.1 type.
  1044.    If such other times can occur, for example, the creation of an object
  1045.    instance at times other than re-initialization, then a corresponding
  1046.    object should be defined with a SYNTAX clause value of TimeStamp (a
  1047.    textual convention defined in [3]) indicating the time of the last
  1048.    discontinuity.
  1049.  
  1050.    The value of the MAX-ACCESS clause for objects with a SYNTAX clause
  1051.    value of Counter64 is either "read-only" or "accessible-for-notify".
  1052.  
  1053.    A requirement on "standard" MIB modules is that the Counter64 type
  1054.    may be used only if the information being modeled would wrap in less
  1055.    than one hour if the Counter32 type was used instead.
  1056.  
  1057.    A DEFVAL clause is not allowed for objects with a SYNTAX clause value
  1058.    of Counter64.
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066. SNMPv2 Working Group        Standards Track                    [Page 19]
  1067.  
  1068. RFC 1902                     SMI for SNMPv2                 January 1996
  1069.  
  1070.  
  1071. 7.1.11.  Unsigned32
  1072.  
  1073.    The Unsigned32 type represents integer-valued information between 0
  1074.    and 2^32-1 inclusive (0 to 4294967295 decimal).
  1075.  
  1076. 7.1.12.  Conceptual Tables
  1077.  
  1078.    Management operations apply exclusively to scalar objects.  However,
  1079.    it is sometimes convenient for developers of management applications
  1080.    to impose an imaginary, tabular structure on an ordered collection of
  1081.    objects within the MIB.  Each such conceptual table contains zero or
  1082.    more rows, and each row may contain one or more scalar objects,
  1083.    termed columnar objects.  This conceptualization is formalized by
  1084.    using the OBJECT-TYPE macro to define both an object which
  1085.    corresponds to a table and an object which corresponds to a row in
  1086.    that table.  A conceptual table has SYNTAX of the form:
  1087.  
  1088.      SEQUENCE OF <EntryType>
  1089.  
  1090.    where <EntryType> refers to the SEQUENCE type of its subordinate
  1091.    conceptual row.  A conceptual row has SYNTAX of the form:
  1092.  
  1093.      <EntryType>
  1094.  
  1095.    where <EntryType> is a SEQUENCE type defined as follows:
  1096.  
  1097.      <EntryType> ::= SEQUENCE { <type1>, ... , <typeN> }
  1098.  
  1099.    where there is one <type> for each subordinate object, and each
  1100.    <type> is of the form:
  1101.  
  1102.      <descriptor> <syntax>
  1103.  
  1104.    where <descriptor> is the descriptor naming a subordinate object, and
  1105.    <syntax> has the value of that subordinate object's SYNTAX clause,
  1106.    normally omitting the sub-typing information.  Further, these ASN.1
  1107.    types are always present (the DEFAULT and OPTIONAL clauses are
  1108.    disallowed in the SEQUENCE definition).  The MAX-ACCESS clause for
  1109.    conceptual tables and rows is "not-accessible".
  1110.  
  1111. 7.1.12.1.  Creation and Deletion of Conceptual Rows
  1112.  
  1113.    For newly-defined conceptual rows which allow the creation of new
  1114.    object instances and/or the deletion of existing object instances,
  1115.    there should be one columnar object with a SYNTAX clause value of
  1116.    RowStatus (a textual convention defined in [3]) and a MAX-ACCESS
  1117.    clause value of read-create.  By convention, this is termed the
  1118.    status column for the conceptual row.
  1119.  
  1120.  
  1121.  
  1122. SNMPv2 Working Group        Standards Track                    [Page 20]
  1123.  
  1124. RFC 1902                     SMI for SNMPv2                 January 1996
  1125.  
  1126.  
  1127. 7.2.  Mapping of the UNITS clause
  1128.  
  1129.    This UNITS clause, which need not be present, contains a textual
  1130.    definition of the units associated with that object.
  1131.  
  1132. 7.3.  Mapping of the MAX-ACCESS clause
  1133.  
  1134.    The MAX-ACCESS clause, which must be present, defines whether it
  1135.    makes "protocol sense" to read, write and/or create an instance of
  1136.    the object, or to include its value in a notification.  This is the
  1137.    maximal level of access for the object.  (This maximal level of
  1138.    access is independent of any administrative authorization policy.)
  1139.  
  1140.    The value "read-write" indicates that read and write access make
  1141.    "protocol sense", but create does not.  The value "read-create"
  1142.    indicates that read, write and create access make "protocol sense".
  1143.    The value "not-accessible" indicates an auxiliary object (see Section
  1144.    7.7).  The value "accessible-for-notify" indicates an object which is
  1145.    accessible only via a notification (e.g., snmpTrapOID [5]).
  1146.  
  1147.    These values are ordered, from least to greatest:  "not-accessible",
  1148.    "accessible-for-notify", "read-only", "read-write", "read-create".
  1149.  
  1150.    If any columnar object in a conceptual row has "read-create" as its
  1151.    maximal level of access, then no other columnar object of the same
  1152.    conceptual row may have a maximal access of "read-write".  (Note that
  1153.    "read-create" is a superset of "read-write".)
  1154.  
  1155. 7.4.  Mapping of the STATUS clause
  1156.  
  1157.    The STATUS clause, which must be present, indicates whether this
  1158.    definition is current or historic.
  1159.  
  1160.    The values "current", and "obsolete" are self-explanatory.  The
  1161.    "deprecated" value indicates that the definition is obsolete, but
  1162.    that an implementor may wish to support that object to foster
  1163.    interoperability with older implementations.
  1164.  
  1165. 7.5.  Mapping of the DESCRIPTION clause
  1166.  
  1167.    The DESCRIPTION clause, which must be present, contains a textual
  1168.    definition of that object which provides all semantic definitions
  1169.    necessary for implementation, and should embody any information which
  1170.    would otherwise be communicated in any ASN.1 commentary annotations
  1171.    associated with the object.
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178. SNMPv2 Working Group        Standards Track                    [Page 21]
  1179.  
  1180. RFC 1902                     SMI for SNMPv2                 January 1996
  1181.  
  1182.  
  1183. 7.6.  Mapping of the REFERENCE clause
  1184.  
  1185.    The REFERENCE clause, which need not be present, contains a textual
  1186.    cross-reference to an object defined in some other information
  1187.    module.  This is useful when de-osifying a MIB module produced by
  1188.    some other organization.
  1189.  
  1190. 7.7.  Mapping of the INDEX clause
  1191.  
  1192.    The INDEX clause, which must be present if that object corresponds to
  1193.    a conceptual row (unless an AUGMENTS clause is present instead), and
  1194.    must be absent otherwise, defines instance identification information
  1195.    for the columnar objects subordinate to that object.
  1196.  
  1197.    The instance identification information in an INDEX clause must
  1198.    specify object(s) such that value(s) of those object(s) will
  1199.    unambiguously distinguish a conceptual row.  The syntax of those
  1200.    objects indicate how to form the instance-identifier:
  1201.  
  1202. (1)  integer-valued:  a single sub-identifier taking the integer value
  1203.      (this works only for non-negative integers);
  1204.  
  1205. (2)  string-valued, fixed-length strings (or variable-length preceded by
  1206.      the IMPLIED keyword):  `n' sub-identifiers, where `n' is the length
  1207.      of the string (each octet of the string is encoded in a separate
  1208.      sub-identifier);
  1209.  
  1210. (3)  string-valued, variable-length strings (not preceded by the IMPLIED
  1211.      keyword):  `n+1' sub-identifiers, where `n' is the length of the
  1212.      string (the first sub-identifier is `n' itself, following this,
  1213.      each octet of the string is encoded in a separate sub-identifier);
  1214.  
  1215. (4)  object identifier-valued (when preceded by the IMPLIED keyword):
  1216.      `n' sub-identifiers, where `n' is the number of sub-identifiers in
  1217.      the value (each sub-identifier of the value is copied into a
  1218.      separate sub-identifier);
  1219.  
  1220. (5)  object identifier-valued (when not preceded by the IMPLIED
  1221.      keyword):  `n+1' sub-identifiers, where `n' is the number of sub-
  1222.      identifiers in the value (the first sub-identifier is `n' itself,
  1223.      following this, each sub-identifier in the value is copied);
  1224.  
  1225. (6)  IpAddress-valued:  4 sub-identifiers, in the familiar a.b.c.d
  1226.      notation.
  1227.  
  1228.    Note that the IMPLIED keyword can only be present for an object
  1229.    having a variable-length syntax (e.g., variable-length strings or
  1230.    object identifier-valued objects), Further, the IMPLIED keyword can
  1231.  
  1232.  
  1233.  
  1234. SNMPv2 Working Group        Standards Track                    [Page 22]
  1235.  
  1236. RFC 1902                     SMI for SNMPv2                 January 1996
  1237.  
  1238.  
  1239.    only be associated with the last object in the INDEX clause.
  1240.    Finally, the IMPLIED keyword may not be used on a variable-length
  1241.    string object if that string might have a value of zero-length.
  1242.  
  1243.    Instances identified by use of integer-valued objects should be
  1244.    numbered starting from one (i.e., not from zero).  The use of zero as
  1245.    a value for an integer-valued index object should be avoided, except
  1246.    in special cases.
  1247.  
  1248.    Objects which are both specified in the INDEX clause of a conceptual
  1249.    row and also columnar objects of the same conceptual row are termed
  1250.    auxiliary objects.  The MAX-ACCESS clause for auxiliary objects is
  1251.    "not-accessible", except in the following circumstances:
  1252.  
  1253. (1)  within a MIB module originally written to conform to the SNMPv1
  1254.      framework, and later converted to conform to the SNMPv2 framework;
  1255.      or
  1256.  
  1257. (2)  a conceptual row must contain at least one columnar object which is
  1258.      not an auxiliary object.  In the event that all of a conceptual
  1259.      row's columnar objects are also specified in its INDEX clause, then
  1260.      one of them must be accessible, i.e., have a MAX-ACCESS clause of
  1261.      "read-only". (Note that this situation does not arise for a
  1262.      conceptual row allowing create access, since such a row will have a
  1263.      status column which will not be an auxiliary object.)
  1264.  
  1265.    Note that objects specified in a conceptual row's INDEX clause need
  1266.    not be columnar objects of that conceptual row.  In this situation,
  1267.    the DESCRIPTION clause of the conceptual row must include a textual
  1268.    explanation of how the objects which are included in the INDEX clause
  1269.    but not columnar objects of that conceptual row, are used in uniquely
  1270.    identifying instances of the conceptual row's columnar objects.
  1271.  
  1272. 7.8.  Mapping of the AUGMENTS clause
  1273.  
  1274.    The AUGMENTS clause, which must not be present unless the object
  1275.    corresponds to a conceptual row, is an alternative to the INDEX
  1276.    clause.  Every object corresponding to a conceptual row has either an
  1277.    INDEX clause or an AUGMENTS clause.
  1278.  
  1279.    If an object corresponding to a conceptual row has an INDEX clause,
  1280.    that row is termed a base conceptual row; alternatively, if the
  1281.    object has an AUGMENTS clause, the row is said to be a conceptual row
  1282.    augmentation, where the AUGMENTS clause names the object
  1283.    corresponding to the base conceptual row which is augmented by this
  1284.    conceptual row augmentation.  (Thus, a conceptual row augmentation
  1285.    cannot itself be augmented.) Instances of subordinate columnar
  1286.    objects of a conceptual row augmentation are identified according to
  1287.  
  1288.  
  1289.  
  1290. SNMPv2 Working Group        Standards Track                    [Page 23]
  1291.  
  1292. RFC 1902                     SMI for SNMPv2                 January 1996
  1293.  
  1294.  
  1295.    the INDEX clause of the base conceptual row corresponding to the
  1296.    object named in the AUGMENTS clause.  Further, instances of
  1297.    subordinate columnar objects of a conceptual row augmentation exist
  1298.    according to the same semantics as instances of subordinate columnar
  1299.    objects of the base conceptual row being augmented.  As such, note
  1300.    that creation of a base conceptual row implies the correspondent
  1301.    creation of any conceptual row augmentations.
  1302.  
  1303.    For example, a MIB designer might wish to define additional columns
  1304.    in an "enterprise-specific" MIB which logically extend a conceptual
  1305.    row in a "standard" MIB.  The "standard" MIB definition of the
  1306.    conceptual row would include the INDEX clause and the "enterprise-
  1307.    specific" MIB would contain the definition of a conceptual row using
  1308.    the AUGMENTS clause.  On the other hand, it would be incorrect to use
  1309.    the AUGMENTS clause for the relationship between RFC 1573's ifTable
  1310.    and the many media-specific MIBs which extend it for specific media
  1311.    (e.g., the dot3Table in RFC 1650), since not all interfaces are of
  1312.    the same media.
  1313.  
  1314.    Note that a base conceptual row may be augmented by multiple
  1315.    conceptual row augmentations.
  1316.  
  1317. 7.8.1.  Relation between INDEX and AUGMENTS clauses
  1318.  
  1319.    When defining instance identification information for a conceptual
  1320.    table:
  1321.  
  1322. (1)  If there is a one-to-one correspondence between the conceptual rows
  1323.      of this table and an existing table, then the AUGMENTS clause
  1324.      should be used.
  1325.  
  1326. (2)  Otherwise, if there is a sparse relationship between the conceptual
  1327.      rows of this table and an existing table, then an INDEX clause
  1328.      should be used which is identical to that in the existing table.
  1329.      For example, the relationship between RFC 1573's ifTable and a
  1330.      media-specific MIB which extends the ifTable for a specific media
  1331.      (e.g., the dot3Table in RFC 1650), is a sparse relationship.
  1332.  
  1333. (3)  Otherwise, if no existing objects have the required syntax and
  1334.      semantics, then auxiliary objects should be defined within the
  1335.      conceptual row for the new table, and those objects should be used
  1336.      within the INDEX clause for the conceptual row.
  1337.  
  1338. 7.9.  Mapping of the DEFVAL clause
  1339.  
  1340.    The DEFVAL clause, which need not be present, defines an acceptable
  1341.    default value which may be used at the discretion of a SNMPv2 entity
  1342.    acting in an agent role when an object instance is created.
  1343.  
  1344.  
  1345.  
  1346. SNMPv2 Working Group        Standards Track                    [Page 24]
  1347.  
  1348. RFC 1902                     SMI for SNMPv2                 January 1996
  1349.  
  1350.  
  1351.    During conceptual row creation, if an instance of a columnar object
  1352.    is not present as one of the operands in the correspondent management
  1353.    protocol set operation, then the value of the DEFVAL clause, if
  1354.    present, indicates an acceptable default value that a SNMPv2 entity
  1355.    acting in an agent role might use.
  1356.  
  1357.    The value of the DEFVAL clause must, of course, correspond to the
  1358.    SYNTAX clause for the object.  If the value is an OBJECT IDENTIFIER,
  1359.    then it must be expressed as a single ASN.1 identifier, and not as a
  1360.    collection of sub-identifiers.
  1361.  
  1362.    Note that if an operand to the management protocol set operation is
  1363.    an instance of a read-only object, then the error `notWritable' [6]
  1364.    will be returned.  As such, the DEFVAL clause can be used to provide
  1365.    an acceptable default value that a SNMPv2 entity acting in an agent
  1366.    role might use.
  1367.  
  1368.    By way of example, consider the following possible DEFVAL clauses:
  1369.  
  1370.      ObjectSyntax       DEFVAL clause
  1371.      ----------------   ------------
  1372.      Integer32          DEFVAL { 1 }
  1373.                         -- same for Gauge32, TimeTicks, Unsigned32
  1374.      INTEGER            DEFVAL { valid } -- enumerated value
  1375.      OCTET STRING       DEFVAL { 'ffffffffffff'H }
  1376.      OBJECT IDENTIFIER  DEFVAL { sysDescr }
  1377.      BITS               DEFVAL { { primary, secondary } }
  1378.                         -- enumerated values that are set
  1379.      IpAddress          DEFVAL { 'c0210415'H } -- 192.33.4.21
  1380.  
  1381.    Object types with SYNTAX of Counter32 and Counter64 may not have
  1382.    DEFVAL clauses, since they do not have defined initial values.
  1383.    However, it is recommended that they be initialized to zero.
  1384.  
  1385. 7.10.  Mapping of the OBJECT-TYPE value
  1386.  
  1387.    The value of an invocation of the OBJECT-TYPE macro is the name of
  1388.    the object, which is an OBJECT IDENTIFIER, an administratively
  1389.    assigned name.
  1390.  
  1391.    When an OBJECT IDENTIFIER is assigned to an object:
  1392.  
  1393. (1)  If the object corresponds to a conceptual table, then only a single
  1394.      assignment, that for a conceptual row, is present immediately
  1395.      beneath that object.  The administratively assigned name for the
  1396.      conceptual row object is derived by appending a sub-identifier of
  1397.      "1" to the administratively assigned name for the conceptual table.
  1398.  
  1399.  
  1400.  
  1401.  
  1402. SNMPv2 Working Group        Standards Track                    [Page 25]
  1403.  
  1404. RFC 1902                     SMI for SNMPv2                 January 1996
  1405.  
  1406.  
  1407. (2)  If the object corresponds to a conceptual row, then at least one
  1408.      assignment, one for each column in the conceptual row, is present
  1409.      beneath that object.  The administratively assigned name for each
  1410.      column is derived by appending a unique, positive sub-identifier to
  1411.      the administratively assigned name for the conceptual row.
  1412.  
  1413. (3)  Otherwise, no other OBJECT IDENTIFIERs which are subordinate to the
  1414.      object may be assigned.
  1415.  
  1416.    Note that the final sub-identifier of any administratively assigned
  1417.    name for an object shall be positive.  A zero-valued  final sub-
  1418.    identifier is reserved for future use.
  1419.  
  1420.    Further note that although conceptual tables and rows are given
  1421.    administratively assigned names, these conceptual objects may not be
  1422.    manipulated in aggregate form by the management protocol.
  1423.  
  1424. 7.11.  Usage Example
  1425.  
  1426.    Consider how one might define a conceptual table and its
  1427.    subordinates.  (This example uses the RowStatus textual convention
  1428.    defined in [3].)
  1429.  
  1430. evalSlot OBJECT-TYPE
  1431.     SYNTAX      INTEGER
  1432.     MAX-ACCESS  read-only
  1433.     STATUS      current
  1434.     DESCRIPTION
  1435.             "The index number of the first unassigned entry in the
  1436.             evaluation table.
  1437.  
  1438.             A management station should create new entries in the
  1439.             evaluation table using this algorithm:  first, issue a
  1440.             management protocol retrieval operation to determine the
  1441.             value of evalSlot; and, second, issue a management protocol
  1442.             set operation to create an instance of the evalStatus object
  1443.             setting its value to createAndGo(4) or createAndWait(5).  If
  1444.             this latter operation succeeds, then the management station
  1445.             may continue modifying the instances corresponding to the
  1446.             newly created conceptual row, without fear of collision with
  1447.             other management stations."
  1448.     ::= { eval 1 }
  1449.  
  1450. evalTable OBJECT-TYPE
  1451.     SYNTAX      SEQUENCE OF EvalEntry
  1452.     MAX-ACCESS  not-accessible
  1453.     STATUS      current
  1454.     DESCRIPTION
  1455.  
  1456.  
  1457.  
  1458. SNMPv2 Working Group        Standards Track                    [Page 26]
  1459.  
  1460. RFC 1902                     SMI for SNMPv2                 January 1996
  1461.  
  1462.  
  1463.             "The (conceptual) evaluation table."
  1464.     ::= { eval 2 }
  1465.  
  1466. evalEntry OBJECT-TYPE
  1467.     SYNTAX      EvalEntry
  1468.     MAX-ACCESS  not-accessible
  1469.     STATUS      current
  1470.     DESCRIPTION
  1471.             "An entry (conceptual row) in the evaluation table."
  1472.     INDEX   { evalIndex }
  1473.     ::= { evalTable 1 }
  1474.  
  1475. EvalEntry ::=
  1476.     SEQUENCE {
  1477.         evalIndex       Integer32,
  1478.         evalString      DisplayString,
  1479.         evalValue       Integer32,
  1480.         evalStatus      RowStatus
  1481.     }
  1482.  
  1483. evalIndex OBJECT-TYPE
  1484.     SYNTAX      Integer32
  1485.     MAX-ACCESS  not-accessible
  1486.     STATUS      current
  1487.     DESCRIPTION
  1488.             "The auxiliary variable used for identifying instances of
  1489.             the columnar objects in the evaluation table."
  1490.         ::= { evalEntry 1 }
  1491.  
  1492. evalString OBJECT-TYPE
  1493.     SYNTAX      DisplayString
  1494.     MAX-ACCESS  read-create
  1495.     STATUS      current
  1496.     DESCRIPTION
  1497.             "The string to evaluate."
  1498.         ::= { evalEntry 2 }
  1499.  
  1500. evalValue OBJECT-TYPE
  1501.     SYNTAX      Integer32
  1502.     MAX-ACCESS  read-only
  1503.     STATUS      current
  1504.     DESCRIPTION
  1505.             "The value when evalString was last executed."
  1506.     DEFVAL  { 0 }
  1507.         ::= { evalEntry 3 }
  1508.  
  1509. evalStatus OBJECT-TYPE
  1510.     SYNTAX      RowStatus
  1511.  
  1512.  
  1513.  
  1514. SNMPv2 Working Group        Standards Track                    [Page 27]
  1515.  
  1516. RFC 1902                     SMI for SNMPv2                 January 1996
  1517.  
  1518.  
  1519.     MAX-ACCESS  read-create
  1520.     STATUS      current
  1521.     DESCRIPTION
  1522.             "The status column used for creating, modifying, and
  1523.             deleting instances of the columnar objects in the evaluation
  1524.             table."
  1525.     DEFVAL  { active }
  1526.         ::= { evalEntry 4 }
  1527.  
  1528. 8.  Mapping of the NOTIFICATION-TYPE macro
  1529.  
  1530.    The NOTIFICATION-TYPE macro is used to define the information
  1531.    contained within an unsolicited transmission of management
  1532.    information (i.e., within either a SNMPv2-Trap-PDU or InformRequest-
  1533.    PDU).  It should be noted that the expansion of the NOTIFICATION-TYPE
  1534.    macro is something which conceptually happens during implementation
  1535.    and not during run-time.
  1536.  
  1537. 8.1.  Mapping of the OBJECTS clause
  1538.  
  1539.    The OBJECTS clause, which need not be present, defines the ordered
  1540.    sequence of MIB object types which are contained within every
  1541.    instance of the notification.  An object type specified in this
  1542.    clause may not have an MAX-ACCESS clause of "not-accessible".
  1543.  
  1544. 8.2.  Mapping of the STATUS clause
  1545.  
  1546.    The STATUS clause, which must be present, indicates whether this
  1547.    definition is current or historic.
  1548.  
  1549.    The values "current", and "obsolete" are self-explanatory.  The
  1550.    "deprecated" value indicates that the definition is obsolete, but
  1551.    that an implementor may wish to support the notification to foster
  1552.    interoperability with older implementations.
  1553.  
  1554. 8.3.  Mapping of the DESCRIPTION clause
  1555.  
  1556.    The DESCRIPTION clause, which must be present, contains a textual
  1557.    definition of the notification which provides all semantic
  1558.    definitions necessary for implementation, and should embody any
  1559.    information which would otherwise be communicated in any ASN.1
  1560.    commentary annotations associated with the notification.  In
  1561.    particular, the DESCRIPTION clause should document which instances of
  1562.    the objects mentioned in the OBJECTS clause should be contained
  1563.    within notifications of this type.
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570. SNMPv2 Working Group        Standards Track                    [Page 28]
  1571.  
  1572. RFC 1902                     SMI for SNMPv2                 January 1996
  1573.  
  1574.  
  1575. 8.4.  Mapping of the REFERENCE clause
  1576.  
  1577.    The REFERENCE clause, which need not be present, contains a textual
  1578.    cross-reference to a notification defined in some other information
  1579.    module.  This is useful when de-osifying a MIB module produced by
  1580.    some other organization.
  1581.  
  1582. 8.5.  Mapping of the NOTIFICATION-TYPE value
  1583.  
  1584.    The value of an invocation of the NOTIFICATION-TYPE macro is the name
  1585.    of the notification, which is an OBJECT IDENTIFIER, an
  1586.    administratively assigned name.  In order to achieve compatibility
  1587.    with the procedures employed by proxy agents (see Section 3.1.2 of
  1588.    [7]), the next to last sub-identifier in the name of any newly-
  1589.    defined notification must have the value zero.
  1590.  
  1591.    Sections 4.2.6 and 4.2.7 of [6] describe how the NOTIFICATION-TYPE
  1592.    macro is used to generate a SNMPv2-Trap-PDU or InformRequest-PDU,
  1593.    respectively.
  1594.  
  1595. 8.6.  Usage Example
  1596.  
  1597.    Consider how a linkUp trap might be described:
  1598.  
  1599. linkUp NOTIFICATION-TYPE
  1600.     OBJECTS { ifIndex }
  1601.     STATUS  current
  1602.     DESCRIPTION
  1603.             "A linkUp trap signifies that the SNMPv2 entity, acting in
  1604.             an agent role, recognizes that one of the communication
  1605.             links represented in its configuration has come up."
  1606.     ::= { snmpTraps 4 }
  1607.  
  1608. According to this invocation, the trap authoritatively identified as
  1609.  
  1610.      { snmpTraps 4 }
  1611.  
  1612. is used to report a link coming up.
  1613.  
  1614. 9.  Refined Syntax
  1615.  
  1616.    Some macros have clauses which allows syntax to be refined,
  1617.    specifically: the SYNTAX clause of the OBJECT-TYPE macro, and the
  1618.    SYNTAX/WRITE-SYNTAX clauses of the MODULE-COMPLIANCE and AGENT-
  1619.    CAPABILITIES macros [2].  However, not all refinements of syntax are
  1620.    appropriate.  In particular, the object's primitive or application
  1621.    type must not be changed.
  1622.  
  1623.  
  1624.  
  1625.  
  1626. SNMPv2 Working Group        Standards Track                    [Page 29]
  1627.  
  1628. RFC 1902                     SMI for SNMPv2                 January 1996
  1629.  
  1630.  
  1631.    Further, the following restrictions apply:
  1632.  
  1633.                             Restrictions to Refinement on
  1634.   object syntax         range   enumeration     size    repertoire
  1635.   -----------------     -----   -----------     ----    ----------
  1636.             INTEGER      (1)        (2)           -         -
  1637.           Integer32      (1)         -            -         -
  1638.          Unsigned32      (1)         -            -         -
  1639.        OCTET STRING       -          -           (3)       (4)
  1640.   OBJECT IDENTIFIER       -          -            -         -
  1641.                BITS       -         (2)           -         -
  1642.           IpAddress       -          -            -         -
  1643.           Counter32       -          -            -         -
  1644.           Counter64       -          -            -         -
  1645.             Gauge32      (1)         -            -         -
  1646.           TimeTicks       -          -            -         -
  1647.  
  1648. where:
  1649.  
  1650. (1)  the range of permitted values may be refined by raising the lower-
  1651.      bounds, by reducing the upper-bounds, and/or by reducing the
  1652.      alternative value/range choices;
  1653.  
  1654. (2)  the enumeration of named-values may be refined by removing one or
  1655.      more named-values (note that for BITS, a refinement may cause the
  1656.      enumerations to no longer be contiguous);
  1657.  
  1658. (3)  the size in characters of the value may be refined by raising the
  1659.      lower-bounds, by reducing the upper-bounds, and/or by reducing the
  1660.      alternative size choices; or,
  1661.  
  1662. (4)  the repertoire of characters in the value may be reduced by further
  1663.      sub-typing.
  1664.  
  1665.    Otherwise no refinements are possible.  Further details on sub-typing
  1666.    are provided in Appendix C.
  1667.  
  1668. 10.  Extending an Information Module
  1669.  
  1670.    As experience is gained with a published information module, it may
  1671.    be desirable to revise that information module.
  1672.  
  1673.    To begin, the invocation of the MODULE-IDENTITY macro should be
  1674.    updated to include information about the revision.  Usually, this
  1675.    consists of updating the LAST-UPDATED clause and adding a pair of
  1676.    REVISION and DESCRIPTION clauses.  However, other existing clauses in
  1677.    the invocation may be updated.
  1678.  
  1679.  
  1680.  
  1681.  
  1682. SNMPv2 Working Group        Standards Track                    [Page 30]
  1683.  
  1684. RFC 1902                     SMI for SNMPv2                 January 1996
  1685.  
  1686.  
  1687.    Note that the module's label (e.g., "FIZBIN-MIB" from the example in
  1688.    Section 5.8), is not changed when the information module is revised.
  1689.  
  1690. 10.1.  Object Assignments
  1691.  
  1692.    If any non-editorial change is made to any clause of a object
  1693.    assignment, then the OBJECT IDENTIFIER value associated with that
  1694.    object assignment must also be changed, along with its associated
  1695.    descriptor.
  1696.  
  1697. 10.2.  Object Definitions
  1698.  
  1699.    An object definition may be revised in any of the following ways:
  1700.  
  1701. (1)  A SYNTAX clause containing an enumerated INTEGER may have new
  1702.      enumerations added or existing labels changed.
  1703.  
  1704. (2)  A STATUS clause value of "current" may be revised as "deprecated"
  1705.      or "obsolete".  Similarly, a STATUS clause value of "deprecated"
  1706.      may be revised as "obsolete".
  1707.  
  1708. (3)  A DEFVAL clause may be added or updated.
  1709.  
  1710. (4)  A REFERENCE clause may be added or updated.
  1711.  
  1712. (5)  A UNITS clause may be added.
  1713.  
  1714. (6)  A conceptual row may be augmented by adding new columnar objects at
  1715.      the end of the row.
  1716.  
  1717. (7)  Entirely new objects may be defined, named with previously
  1718.      unassigned OBJECT IDENTIFIER values.
  1719.  
  1720.    Otherwise, if the semantics of any previously defined object are
  1721.    changed (i.e., if a non-editorial change is made to any clause other
  1722.    those specifically allowed above), then the OBJECT IDENTIFIER value
  1723.    associated with that object must also be changed.
  1724.  
  1725.    Note that changing the descriptor associated with an existing object
  1726.    is considered a semantic change, as these strings may be used in an
  1727.    IMPORTS statement.
  1728.  
  1729.    Finally, note that if an object has the value of its STATUS clause
  1730.    changed, then the value of its DESCRIPTION clause should be updated
  1731.    accordingly.
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738. SNMPv2 Working Group        Standards Track                    [Page 31]
  1739.  
  1740. RFC 1902                     SMI for SNMPv2                 January 1996
  1741.  
  1742.  
  1743. 10.3.  Notification Definitions
  1744.  
  1745.    A notification definition may be revised in any of the following
  1746.    ways:
  1747.  
  1748.    (1)  A REFERENCE clause may be added or updated.
  1749.  
  1750.    Otherwise, if the semantics of any previously defined notification
  1751.    are changed (i.e., if a non-editorial change is made to any clause
  1752.    other those specifically allowed above), then the OBJECT IDENTIFIER
  1753.    value associated with that notification must also be changed.
  1754.  
  1755.    Note that changing the descriptor associated with an existing
  1756.    notification is considered a semantic change, as these strings may be
  1757.    used in an IMPORTS statement.
  1758.  
  1759.    Finally, note that if an object has the value of its STATUS clause
  1760.    changed, then the value of its DESCRIPTION clause should be updated
  1761.    accordingly.
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794. SNMPv2 Working Group        Standards Track                    [Page 32]
  1795.  
  1796. RFC 1902                     SMI for SNMPv2                 January 1996
  1797.  
  1798.  
  1799. 11.  Appendix A: de-OSIfying a MIB module
  1800.  
  1801.    There has been an increasing amount of work recently on taking MIBs
  1802.    defined by other organizations (e.g., the IEEE) and de-osifying them
  1803.    for use with the Internet-standard network management framework.  The
  1804.    steps to achieve this are straight-forward, though tedious.  Of
  1805.    course, it is helpful to already be experienced in writing MIB
  1806.    modules for use with the Internet-standard network management
  1807.    framework.
  1808.  
  1809.    The first step is to construct a skeletal MIB module, as shown
  1810.    earlier in Section 5.8.  The next step is to categorize the objects
  1811.    into groups.  Optional objects are not permitted.  Thus, when a MIB
  1812.    module is created, optional objects must be placed in a additional
  1813.    groups, which, if implemented, all objects in the group must be
  1814.    implemented.  For the first pass, it is wisest to simply ignore any
  1815.    optional objects in the original MIB:  experience shows it is better
  1816.    to define a core MIB module first, containing only essential objects;
  1817.    later, if experience demands, other objects can be added.
  1818.  
  1819. 11.1.  Managed Object Mapping
  1820.  
  1821.    Next for each managed object class, determine whether there can exist
  1822.    multiple instances of that managed object class.  If not, then for
  1823.    each of its attributes, use the OBJECT-TYPE macro to make an
  1824.    equivalent definition.
  1825.  
  1826.    Otherwise, if multiple instances of the managed object class can
  1827.    exist, then define a conceptual table having conceptual rows each
  1828.    containing a columnar object for each of the managed object class's
  1829.    attributes.  If the managed object class is contained within the
  1830.    containment tree of another managed object class, then the assignment
  1831.    of an object is normally required for each of the "distinguished
  1832.    attributes" of the containing managed object class.  If they do not
  1833.    already exist within the MIB module, then they can be added via the
  1834.    definition of additional columnar objects in the conceptual row
  1835.    corresponding to the contained managed object class.
  1836.  
  1837.    In defining a conceptual row, it is useful to consider the
  1838.    optimization of network management operations which will act upon its
  1839.    columnar objects.  In particular, it is wisest to avoid defining more
  1840.    columnar objects within a conceptual row, than can fit in a single
  1841.    PDU.  As a rule of thumb, a conceptual row should contain no more
  1842.    than approximately 20 objects.  Similarly, or as a way to abide by
  1843.    the "20 object guideline", columnar objects should be grouped into
  1844.    tables according to the expected grouping of network management
  1845.    operations upon them.  As such, the content of conceptual rows should
  1846.    reflect typical access scenarios, e.g., they should be organized
  1847.  
  1848.  
  1849.  
  1850. SNMPv2 Working Group        Standards Track                    [Page 33]
  1851.  
  1852. RFC 1902                     SMI for SNMPv2                 January 1996
  1853.  
  1854.  
  1855.    along functional lines such as one row for statistics and another row
  1856.    for parameters, or along usage lines such as commonly-needed objects
  1857.    versus rarely-needed objects.
  1858.  
  1859.    On the other hand, the definition of conceptual rows where the number
  1860.    of columnar objects used as indexes outnumbers the number used to
  1861.    hold information, should also be avoided.  In particular, the
  1862.    splitting of a managed object class's attributes into many conceptual
  1863.    tables should not be used as a way to obtain the same degree of
  1864.    flexibility/complexity as is often found in MIBs with a myriad of
  1865.    optionals.
  1866.  
  1867. 11.1.1.  Mapping to the SYNTAX clause
  1868.  
  1869.    When mapping to the SYNTAX clause of the OBJECT-TYPE macro:
  1870.  
  1871. (1)  An object with BOOLEAN syntax becomes a TruthValue [3].
  1872.  
  1873. (2)  An object with INTEGER syntax becomes an Integer32.
  1874.  
  1875. (3)  An object with ENUMERATED syntax becomes an INTEGER with
  1876.      enumerations, taking any of the values given which can be
  1877.      represented with an Integer32.
  1878.  
  1879. (4)  An object with BIT STRING syntax having enumerations becomes a BITS
  1880.      construct.
  1881.  
  1882. (5)  An object with BIT STRING syntax but no enumerations becomes an
  1883.      OCTET STRING.
  1884.  
  1885. (6)  An object with a character string syntax becomes either an OCTET
  1886.      STRING, or a DisplayString [3], depending on the repertoire of the
  1887.      character string.
  1888.  
  1889. (7)  A non-tabular object with a complex syntax, such as REAL or
  1890.      EXTERNAL, must be decomposed, usually into an OCTET STRING (if
  1891.      sensible).  As a rule, any object with a complicated syntax should
  1892.      be avoided.
  1893.  
  1894. (8)  Tabular objects must be decomposed into rows of columnar objects.
  1895.  
  1896. 11.1.2.  Mapping to the UNITS clause
  1897.  
  1898.    If the description of this managed object defines a unit-basis, then
  1899.    mapping to this clause is straight-forward.
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906. SNMPv2 Working Group        Standards Track                    [Page 34]
  1907.  
  1908. RFC 1902                     SMI for SNMPv2                 January 1996
  1909.  
  1910.  
  1911. 11.1.3.  Mapping to the MAX-ACCESS clause
  1912.  
  1913.    This is straight-forward.
  1914.  
  1915. 11.1.4.  Mapping to the STATUS clause
  1916.  
  1917.    This is straight-forward.
  1918.  
  1919. 11.1.5.  Mapping to the DESCRIPTION clause
  1920.  
  1921.    This is straight-forward:  simply copy the text, making sure that any
  1922.    embedded double quotation marks are sanitized (i.e., replaced with
  1923.    single-quotes or removed).
  1924.  
  1925. 11.1.6.  Mapping to the REFERENCE clause
  1926.  
  1927.    This is straight-forward:  simply include a textual reference to the
  1928.    object being mapped, the document which defines the object, and
  1929.    perhaps a page number in the document.
  1930.  
  1931. 11.1.7.  Mapping to the INDEX clause
  1932.  
  1933.    If necessary, decide how instance-identifiers for columnar objects
  1934.    are to be formed and define this clause accordingly.
  1935.  
  1936. 11.1.8.  Mapping to the DEFVAL clause
  1937.  
  1938.    Decide if a meaningful default value can be assigned to the object
  1939.    being mapped, and if so, define the DEFVAL clause accordingly.
  1940.  
  1941. 11.2.  Action Mapping
  1942.  
  1943.    Actions are modeled as read-write objects, in which writing a
  1944.    particular value results in a state change.  (Usually, as a part of
  1945.    this state change, some action might take place.)
  1946.  
  1947. 11.2.1.  Mapping to the SYNTAX clause
  1948.  
  1949.    Usually the Integer32 syntax is used with a distinguished value
  1950.    provided for each action that the object provides access to.  In
  1951.    addition, there is usually one other distinguished value, which is
  1952.    the one returned when the object is read.
  1953.  
  1954. 11.2.2.  Mapping to the MAX-ACCESS clause
  1955.  
  1956.    Always use read-write or read-create.
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962. SNMPv2 Working Group        Standards Track                    [Page 35]
  1963.  
  1964. RFC 1902                     SMI for SNMPv2                 January 1996
  1965.  
  1966.  
  1967. 11.2.3.  Mapping to the STATUS clause
  1968.  
  1969.    This is straight-forward.
  1970.  
  1971. 11.2.4.  Mapping to the DESCRIPTION clause
  1972.  
  1973.    This is straight-forward:  simply copy the text, making sure that any
  1974.    embedded double quotation marks are sanitized (i.e., replaced with
  1975.    single-quotes or removed).
  1976.  
  1977. 11.2.5.  Mapping to the REFERENCE clause
  1978.  
  1979.    This is straight-forward:  simply include a textual reference to the
  1980.    action being mapped, the document which defines the action, and
  1981.    perhaps a page number in the document.
  1982.  
  1983. 11.3.  Event Mapping
  1984.  
  1985.    Events are modeled as SNMPv2 notifications using NOTIFICATION-TYPE
  1986.    macro.  However, recall that SNMPv2 emphasizes trap-directed polling.
  1987.    As such, few, and usually no, notifications, need be defined for any
  1988.    MIB module.
  1989.  
  1990. 11.3.1.  Mapping to the STATUS clause
  1991.  
  1992.    This is straight-forward.
  1993.  
  1994. 11.3.2.  Mapping to the DESCRIPTION clause
  1995.  
  1996.    This is straight-forward:  simply copy the text, making sure that any
  1997.    embedded double quotation marks are sanitized (i.e., replaced with
  1998.    single-quotes or removed).
  1999.  
  2000. 11.3.3.  Mapping to the REFERENCE clause
  2001.  
  2002.    This is straight-forward:  simply include a textual reference to the
  2003.    notification being mapped, the document which defines the
  2004.    notification, and perhaps a page number in the document.
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018. SNMPv2 Working Group        Standards Track                    [Page 36]
  2019.  
  2020. RFC 1902                     SMI for SNMPv2                 January 1996
  2021.  
  2022.  
  2023. 12.  Appendix B: UTC Time Format
  2024.  
  2025.    Several clauses defined in this document use the UTC Time format:
  2026.  
  2027.      YYMMDDHHMMZ
  2028.  
  2029.      where: YY - last two digits of year
  2030.             MM - month (01 through 12)
  2031.             DD - day of month (01 through 31)
  2032.             HH - hours (00 through 23)
  2033.             MM - minutes (00 through 59)
  2034.              Z - the character "Z" denotes Greenwich Mean Time (GMT).
  2035.  
  2036.    For example, "9502192015Z" represents 8:15pm GMT on 19 February 1995.
  2037.  
  2038. 13.  Appendix C: Detailed Sub-typing Rules
  2039.  
  2040. 13.1.  Syntax Rules
  2041.  
  2042.    The syntax rules for sub-typing are given below.  Note that while
  2043.    this syntax is based on ASN.1, it includes some extensions beyond
  2044.    what is allowed in ASN.1, and a number of ASN.1 constructs are not
  2045.    allowed by this syntax.
  2046.  
  2047.      <integerSubType>
  2048.          ::= <empty>
  2049.            | "(" <range> ["|" <range>]... ")"
  2050.  
  2051.      <octetStringSubType>
  2052.          ::= <empty>
  2053.            | "(" "SIZE" "(" <range> ["|" <range>]... ")" ")"
  2054.  
  2055.      <range>
  2056.          ::= <value>
  2057.            | <value> ".." <value>
  2058.  
  2059.      <value>
  2060.          ::= "-" <number>
  2061.            | <number>
  2062.            | <hexString>
  2063.            | <binString>
  2064.  
  2065.      where:
  2066.          <empty>     is the empty string
  2067.          <number>    is a non-negative integer
  2068.          <hexString> is a hexadecimal string (i.e. 'xxxx'H)
  2069.          <binString> is a binary string (i.e. 'xxxx'B)
  2070.  
  2071.  
  2072.  
  2073.  
  2074. SNMPv2 Working Group        Standards Track                    [Page 37]
  2075.  
  2076. RFC 1902                     SMI for SNMPv2                 January 1996
  2077.  
  2078.  
  2079.          <range> is further restricted as follows:
  2080.              - any <value> used in a SIZE clause must be non-negative.
  2081.              - when a pair of values is specified, the first value
  2082.                must be less than the second value.
  2083.              - when multiple ranges are specified, the ranges may
  2084.                not overlap but may touch. For example, (1..4 | 4..9)
  2085.                is invalid, and (1..4 | 5..9) is valid.
  2086.              - the ranges must be a subset of the maximum range of the
  2087.                base type.
  2088.  
  2089. 13.2.  Examples
  2090.  
  2091. Some examples of legal sub-typing:
  2092.  
  2093.          Integer32 (-20..100)
  2094.          Integer32 (0..100 | 300..500)
  2095.          Integer32 (300..500 | 0..100)
  2096.          Integer32 (0 | 2 | 4 | 6 | 8 | 10)
  2097.          OCTET STRING (SIZE(0..100))
  2098.          OCTET STRING (SIZE(0..100 | 300..500))
  2099.          OCTET STRING (SIZE(0 | 2 | 4 | 6 | 8 | 10))
  2100.  
  2101. Some examples of illegal sub-typing:
  2102.  
  2103.      Integer32 (150..100)         -- first greater than second
  2104.      Integer32 (0..100 | 50..500) -- ranges overlap
  2105.      Integer32 (0 | 2 | 0 )       -- value duplicated
  2106.      Integer32 (MIN..-1 | 1..MAX) -- MIN and MAX not allowed
  2107.      Integer32 ((SIZE (0..34))    -- must not use SIZE
  2108.      OCTET STRING (0..100)        -- must use SIZE
  2109.      OCTET STRING (SIZE(-10..100)) -- negative SIZE
  2110.  
  2111. 13.3.  Rules for Textual Conventions
  2112.  
  2113.    Sub-typing of Textual Conventions (see [3]) is allowed but must be
  2114.    valid.  In particular, each range specified for the textual
  2115.    convention must be a subset of a range specified for the base type.
  2116.    For example,
  2117.  
  2118.      Tc1 ::= INTEGER (1..10 | 11..20)
  2119.      Tc2 ::= Tc1 (2..10 | 12..15)       -- is valid
  2120.      Tc3 ::= Tc1 (4..8)                 -- is valid
  2121.      Tc4 ::= Tc1 (8..12)                -- is invalid
  2122.  
  2123. 14.  Security Considerations
  2124.  
  2125.    Security issues are not discussed in this memo.
  2126.  
  2127.  
  2128.  
  2129.  
  2130. SNMPv2 Working Group        Standards Track                    [Page 38]
  2131.  
  2132. RFC 1902                     SMI for SNMPv2                 January 1996
  2133.  
  2134.  
  2135. 15.  Editor's Address
  2136.  
  2137.    Keith McCloghrie
  2138.    Cisco Systems, Inc.
  2139.    170 West Tasman Drive
  2140.    San Jose, CA  95134-1706
  2141.    US
  2142.  
  2143.    Phone: +1 408 526 5260
  2144.    EMail: kzm@cisco.com
  2145.  
  2146. 16.  Acknowledgements
  2147.  
  2148.    This document is the result of significant work by the four major
  2149.    contributors:
  2150.  
  2151.    Jeffrey D. Case (SNMP Research, case@snmp.com)
  2152.    Keith McCloghrie (Cisco Systems, kzm@cisco.com)
  2153.    Marshall T. Rose (Dover Beach Consulting, mrose@dbc.mtview.ca.us)
  2154.    Steven Waldbusser (International Network Services, stevew@uni.ins.com)
  2155.  
  2156.    In addition, the contributions of the SNMPv2 Working Group are
  2157.    acknowledged.  In particular, a special thanks is extended for the
  2158.    contributions of:
  2159.  
  2160.      Alexander I. Alten (Novell)
  2161.      Dave Arneson (Cabletron)
  2162.      Uri Blumenthal (IBM)
  2163.      Doug Book (Chipcom)
  2164.      Kim Curran (Bell-Northern Research)
  2165.      Jim Galvin (Trusted Information Systems)
  2166.      Maria Greene (Ascom Timeplex)
  2167.      Iain Hanson (Digital)
  2168.      Dave Harrington (Cabletron)
  2169.      Nguyen Hien (IBM)
  2170.      Jeff Johnson (Cisco Systems)
  2171.      Michael Kornegay (Object Quest)
  2172.      Deirdre Kostick (AT&T Bell Labs)
  2173.      David Levi (SNMP Research)
  2174.      Daniel Mahoney (Cabletron)
  2175.      Bob Natale (ACE*COMM)
  2176.      Brian O'Keefe (Hewlett Packard)
  2177.      Andrew Pearson (SNMP Research)
  2178.      Dave Perkins (Peer Networks)
  2179.      Randy Presuhn (Peer Networks)
  2180.      Aleksey Romanov (Quality Quorum)
  2181.      Shawn Routhier (Epilogue)
  2182.      Jon Saperia (BGS Systems)
  2183.  
  2184.  
  2185.  
  2186. SNMPv2 Working Group        Standards Track                    [Page 39]
  2187.  
  2188. RFC 1902                     SMI for SNMPv2                 January 1996
  2189.  
  2190.  
  2191.      Bob Stewart (Cisco Systems, bstewart@cisco.com), chair
  2192.      Kaj Tesink (Bellcore)
  2193.      Glenn Waters (Bell-Northern Research)
  2194.      Bert Wijnen (IBM)
  2195.  
  2196. 17.  References
  2197.  
  2198. [1]  Information processing systems - Open Systems Interconnection -
  2199.      Specification of Abstract Syntax Notation One (ASN.1),
  2200.      International Organization for Standardization.  International
  2201.      Standard 8824, (December, 1987).
  2202.  
  2203. [2]  SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
  2204.      S. Waldbusser, "Conformance Statements for Version 2 of the Simple
  2205.      Network Management Protocol (SNMPv2)", RFC 1904, January 1996.
  2206.  
  2207. [3]  SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
  2208.      S. Waldbusser, "Textual Conventions for Version 2 of the Simple
  2209.      Network Management Protocol (SNMPv2)", RFC 1903, January 1996.
  2210.  
  2211. [4]  Information processing systems - Open Systems Interconnection -
  2212.      Specification of Basic Encoding Rules for Abstract Syntax Notation
  2213.      One (ASN.1), International Organization for Standardization.
  2214.      International Standard 8825, (December, 1987).
  2215.  
  2216. [5]  SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
  2217.      S. Waldbusser, "Management Information Base for Version 2 of the
  2218.      Simple Network Management Protocol (SNMPv2)", RFC 1907,
  2219.      January 1996.
  2220.  
  2221. [6]  SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
  2222.      S. Waldbusser, "Protocol Operations for Version 2 of the Simple
  2223.      Network Management Protocol (SNMPv2)", RFC 1905, January 1996.
  2224.  
  2225. [7]  SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
  2226.      S. Waldbusser, "Coexistence between Version 1 and Version 2 of the
  2227.      Internet-standard Network Management Framework", RFC 1908,
  2228.      January 1996.
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242. SNMPv2 Working Group        Standards Track                    [Page 40]
  2243.  
  2244.