Draft Textual Conventions for SNMPv2 Oct 92 Textual Conventions for version 2 of the Simple Network Management Protocol (SNMPv2) Thu Nov 12 08:51:15 1992 | Jeffrey D. Case SNMP Research, Inc. University of Tennessee, Knoxville case@cs.utk.edu Keith McCloghrie Hughes LAN Systems kzm@hls.com Marshall T. Rose Dover Beach Consulting, Inc. mrose@dbc.mtview.ca.us Steven L. Waldbusser Carnegie Mellon University waldbusser@andrew.cmu.edu 1. Status of this Memo This document is an Internet Draft. Internet Drafts are working documents of the Internet Engineering Task Force (IETF), its Areas, and its Working Groups. Note that other groups may also distribute working documents as Internet Drafts. Internet Drafts are valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet Drafts as reference material or to cite them other than as a "work in progress". Expires May 12, 1993 [Page 1] Draft Textual Conventions for SNMPv2 Oct 92 2. Introduction A network management system contains: several (potentially many) nodes, each with management instrumentation termed an agent; at least one management station; and, a management protocol, which is used to convey management information between the agents and management stations. Operations of the management protocol are carried out under an administrative framework which defines both authentication and authorization policies. Network management stations execute management applications which monitor and control network elements. Network elements are devices such as hosts, routers, terminal servers, etc., which are monitored and controlled through access to their management information. Management information is viewed as a collection of managed objects, residing in a virtual information store, termed the Management Information Base (MIB). Collections of related objects are defined in MIB modules. These modules are written using a subset of OSI's Abstract Syntax Notation One (ASN.1) [1], termed the Structure of Management Information (SMI) [2]. When designing a MIB module, it is often useful to define types, with a different name, but the same syntax, as one of the types defined in the SMI. These are termed textual conventions, and are used for the convenience of humans reading the MIB module. It is the purpose of this document to define the initial set of textual conventions available to all MIB modules. Objects defined using a textual convention are always encoded by means of the rules that define their primitive type. However, textual conventions often have special semantics associated with them. As such, an ASN.1 macro, TEXTUAL- CONVENTION, is used to concisely convey the syntax and semantics of a textual convention. For all textual conventions defined in an information module, the name shall be unique and mnemonic, and shall not exceed 64 characters in length. All names used for the textual conventions defined in all "standard" information modules shall be unique. Expires May 12, 1993 [Page 2] Draft Textual Conventions for SNMPv2 Oct 92 2.1. A Note on Terminology For the purpose of exposition, the original Internet-standard + Network Management Framework, as described in RFCs 1155, 1157, + and 1212, is termed the SNMP version 1 framework (SNMPv1). + The current framework is termed the SNMP version 2 framework + (SNMPv2). + Expires May 12, 1993 [Page 3] Draft Textual Conventions for SNMPv2 Oct 92 3. Definitions SNMPv2-TC DEFINITIONS ::= BEGIN IMPORTS ObjectSyntax, Integer32, TimeTicks FROM SNMPv2-SMI; -- definition of textual conventions TEXTUAL-CONVENTION MACRO ::= BEGIN TYPE NOTATION ::= DisplayPart "STATUS" Status "DESCRIPTION" value(description Text) ReferPart VALUE NOTATION ::= type(VALUE ObjectSyntax) DisplayPart ::= "DISPLAY-HINT" value(display Text) | empty Status ::= "current" | "deprecated" | "obsolete" ReferPart ::= "REFERENCE" value(reference Text) | empty -- uses the NVT ASCII character set Text ::= OCTET STRING END DisplayString TEXTUAL-CONVENTION DISPLAY-HINT "255a" STATUS current DESCRIPTION "Represents textual information taken from the NVT Expires May 12, 1993 [Page 4] Draft Textual Conventions for SNMPv2 Oct 92 ASCII character set, as defined in pages 4, 10-11 of RFC 854. Any object defined using this syntax may not exceed 255 characters in length." ::= OCTET STRING PhysAddress TEXTUAL-CONVENTION DISPLAY-HINT "1x:" STATUS current DESCRIPTION "Represents media- or physical-level addresses." ::= OCTET STRING MacAddress TEXTUAL-CONVENTION DISPLAY-HINT "1x:" STATUS current DESCRIPTION "Represents an 802 MAC address represented in the `canonical' order defined by IEEE 802.1a, i.e., as if it were transmitted least significant bit first, even though 802.5 (in contrast to other 802.x protocols) requires MAC addresses to be transmitted most significant bit first." ::= OCTET STRING (SIZE (6)) TruthValue TEXTUAL-CONVENTION STATUS current DESCRIPTION "Represents a boolean value." ::= INTEGER { true(1), false(2) } TestAndIncr TEXTUAL-CONVENTION STATUS current DESCRIPTION "Represents integer-valued information used for atomic operations. When the management protocol is used to specify that an object instance having this syntax is to be modified, the new value supplied via the management protocol must precisely match the value presently held by the instance. If not, the management protocol set operation fails with an error of Expires May 12, 1993 [Page 5] Draft Textual Conventions for SNMPv2 Oct 92 `inconsistentValue'. Otherwise, if the current value is the maximum value of 2^31-1 (2147483647 decimal), then the value held by the instance is wrapped to zero; otherwise, the value held by the instance is incremented by one. (Note that regardless of whether the management protocol set operation succeeds, the variable-binding in the request and response PDUs are identical.) The value of the ACCESS clause for objects having this syntax is either `read-write' or `read- create'. When an instance of a columnar object having this syntax is created, any value may be supplied via the management protocol." ::= INTEGER (0..2147483647) AutonomousType TEXTUAL-CONVENTION STATUS current DESCRIPTION "Represents an independently extensible type identification value. It may, for example, indicate a particular sub-tree with further MIB definitions, or define a particular type of protocol or hardware." ::= OBJECT IDENTIFIER InstancePointer TEXTUAL-CONVENTION STATUS current DESCRIPTION "A pointer to a specific instance of a conceptual row of a MIB table in the managed device. By convention, it is the name of the particular instance of the first columnar object in the conceptual row." ::= OBJECT IDENTIFIER RowStatus TEXTUAL-CONVENTION STATUS current DESCRIPTION "The syntax used for the status column for a conceptual row. If present, the value of the DEFVAL clause for an object having this syntax is Expires May 12, 1993 [Page 6] Draft Textual Conventions for SNMPv2 Oct 92 either `underModification(4)' or `active(1)'. To create new object instances for a conceptual row, a management protocol set operation is issued which sets the new instance of the status column to `underConstruction(2)'. If the instance already exists, then the management protocol set operation fails with an error of `inconsistentValue'. Otherwise, the instance is created. If the management protocol set operation created sufficient instances so that this conceptual row may be used by the correspondent SNMPv2 entity, and the value of the DEFVAL clause for the status column is `active(1)', then the SNMPv2 entity acting in an agent role immediately sets the value of this instance to `active(1)'. Otherwise, the SNMPv2 entity acting in an agent role immediately sets the value of this instance to `underModification(4)'. This suggests that the algorithm to create a new conceptual row is as follows: First, the management station ascertains the identity of an unused slot in the conceptual table of interest. Second, the management station issues a management protocol set operation to create the status column for the desired conceptual row. Third, the management station issues a management protocol get operation to examine all columns in that conceptual row. For each column, if the get operation returns a value for that column, then the management station may issue an additional management protocol set operation to change that value; if the `noSuchInstance' exception is returned, then the management station must issue an additional management protocol set operation to create that instance prior to changing the status column to `active'; and, if the `noSuchObject' exception is returned, then Expires May 12, 1993 [Page 7] Draft Textual Conventions for SNMPv2 Oct 92 the management station learns that it must not issue a management protocol set operation to create an instance of this column. When an instance of the status column has the value `underModification(4)' or `active(1)', then management operations may be issued to manipulate the columns in the conceptual row. However, only when the value of an instance of the status column is `active(1)', will the information in the conceptual row be available outside of the management subsystem, i.e., whilst the information is available to authorized SNMPv2 entities acting in a manager role, the information is independent of the operational state of the managed device. As such, note that while the status is `underModification(4)', it is possible for a managed device to create (or otherwise manipulate) its own instances which effectively supersede those held by the SNMPv2 entity acting in an agent role. If the management station doesn't finish this algorithm (due to a management station or network failure, for example) conceptual rows may be left in the `underModification(4)' state, consuming resources indefinitely. The SNMPv2 entity acting in an agent role may detect conceptual rows that have been in the `underModification(4) state for an abnormally long period of time and remove them from the table. This period of time should be long enough to allow for human response time (including `think time') between the creation of the conceptual row and the setting of the status to `active(1)'. It is suggested that this period be approximately 5 minutes in length. For deletion of conceptual rows, a management protocol set operation is issued which sets the instance of the status column to `underDestruction(3)'. If the operation succeeds, then the entire conceptual row is immediately removed from the table." ::= INTEGER { active(1) underConstruction(2), Expires May 12, 1993 [Page 8] Draft Textual Conventions for SNMPv2 Oct 92 underDestruction(3), underModification(4), } TimeStamp TEXTUAL-CONVENTION STATUS current DESCRIPTION "The value of MIB-II's sysUpTime object at which a specific occurrence happened. The specific occurrence must be defined in the description of any object defined using this type." ::= TimeTicks TimeInterval TEXTUAL-CONVENTION STATUS current DESCRIPTION "A period of time, measured in units of 0.01 seconds." ::= INTEGER (0..2147483647) DateAndTime TEXTUAL-CONVENTION DISPLAY-HINT "2d-1d-1d,1d:1d:1d.1d,1a1d:1d" STATUS current DESCRIPTION "A date-time specification. field octets contents range ----- ------ -------- ----- 1 1-2 year 0..65536 2 3 month 1..12 3 4 day 1..31 4 5 hour 0..23 5 6 minutes 0..59 6 7 seconds 0..60 (use 60 for leap-second) 7 8 deci-seconds 0..9 8 9 direction from UTC '+' / '-' | 9 10 hours from UTC 0..11 | 10 11 minutes from UTC 0..59 | For example, Tuesday May 26, 1992 at 1:30:15 PM EDT would be displayed as: 1992-5-26,13:30:15.0,-4:0 Expires May 12, 1993 [Page 9] Draft Textual Conventions for SNMPv2 Oct 92 Note that if only local time is known, then timezone information (fields 8-10) is not present. " ::= OCTET STRING (SIZE (8 | 11)) END Expires May 12, 1993 [Page 10] Draft Textual Conventions for SNMPv2 Oct 92 4. Mapping of the TEXTUAL-CONVENTION macro The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics associated with a textual convention. It should be noted that the expansion of the TEXTUAL-CONVENTION macro is something which conceptually happens during implementation and not during run-time. 4.1. Mapping of the DISPLAY-HINT clause The DISPLAY-HINT clause, which need not be present, gives a hint as to how the value of an instance of an object with the syntax defined using this textual convention might be displayed. The DISPLAY-HINT clause may only be present when the syntax has an underlying primitive type of INTEGER or OCTET STRING. When the syntax has an underlying primitive type of INTEGER, the hint consists of a single character suggesting a display format, either: `x' for hexadecimal, `d' for decimal, or `o' for octal, or `b' for binary. When the syntax has an underlying primitive type of OCTET STRING, the hint consists of one or more octet-format specifications. Each specification consists of five parts, with each part using and removing zero or more of the next octets from the value and producing the next zero or more characters to be displayed. The octets within the value are processed in order of significance, most significant first. The five parts of a octet-format specification are: (1) the (optional) repeat indicator; if present, this part is a `*', and indicates that the current octet of the value is to be used as the repeat count. The repeat count is an unsigned integer (which may be zero) which specifies how many times the remainder of this octet-format specification should be successively applied. If the repeat indicator is not present, the repeat count is one. (2) the octet length: one or more decimal digits specifying the number of octets of the value to be used and formatted by this octet-specification. Note that the octet length can be zero. If less than this number of Expires May 12, 1993 [Page 11] Draft Textual Conventions for SNMPv2 Oct 92 octets remain in the value, then the lesser number of octets are used. (3) the display format, either: `x' for hexadecimal, `d' for decimal, `o' for octal, or `a' for ascii. If the octet length part is greater than one, and the display format part refers to a numeric format, then network-byte ordering (big-endian encoding) is used interpreting the octets in the value. (4) the (optional) display separator character; if present, this part is a single character which is produced for display after each application of this octet- specification; however, this character is not produced for display if it would be immediately followed by the display of the repeat terminator character for this octet-specification. This character can be any character other than a decimal digit and a `*'. (5) the (optional) repeat terminator character, which can be present only if the display separator character is present and this octet-specification begins with a repeat indicator; if present, this part is a single character which is produced after all the zero or more repeated applications (as given by the repeat count) of this octet-specification. This character can be any character other than a decimal digit and a `*'. Output of a display separator character or a repeat terminator character is suppressed if it would occur as the last character of the display. If the octets of the value are exhausted before all the octet-format specification have been used, then the excess specifications are ignored. If additional octets remain in the value after interpreting all the octet-format specifications, then the last octet-format specification is re-interpreted to process the additional octets, until no octets remain in the value. 4.2. Mapping of the STATUS clause The STATUS clause, which must be present, indicates whether this definition is current or historic. Expires May 12, 1993 [Page 12] Draft Textual Conventions for SNMPv2 Oct 92 The values "current", and "obsolete" are self-explanatory. The "deprecated" value indicates that that object is obsolete, but that an implementor may wish to support that object to foster interoperability with older implementations. 4.3. Mapping of the DESCRIPTION clause The DESCRIPTION clause, which must be present, contains a textual definition of the textual convention, which provides all semantic definitions necessary for implementation, and should embody any information which would otherwise be communicated in any ASN.1 commentary annotations associated with the object. Note that, in order to conform to the ASN.1 syntax, the entire value of this clause must be enclosed in double quotation marks, and therefore cannot itself contain double quotation marks, although the value may be multi-line. 4.4. Mapping of the REFERENCE clause The REFERENCE clause, which need not be present, contains a textual cross-reference to a related item defined in some other published work. 4.5. Mapping of the TEXTUAL-CONVENTION value The value of an invocation of the TEXTUAL-CONVENTION macro defines the abstract data structure corresponding to the textual convention. The data structure must be one of the alternatives defined in the ObjectSyntax CHOICE from [2], a refinement of one of the alternatives, or the value of a previously defined TEXTUAL-CONVENTION. Consult Section 11 of [2] for more information on refined syntax. Expires May 12, 1993 [Page 13] Draft Textual Conventions for SNMPv2 Oct 92 5. Acknowledgements PhysAddress (and textual conventions) originated in RFC 1213. MacAddress originated in RFCs 1230 and 1231. TruthValue originated in RFC 1253. AutonomousType and InstancePointer originated in RFC 1316. RowStatus originated in RFC 1271. Finally, the comments of the SNMP Version 2 working group are gratefully acknowledged: Steve Alexander, Interactive Systems Uri Blumenthal, International Business Machines Jeffrey D. Case, SNMP Research, Inc. Tracy Cox, Bellcore James R. (Chuck) Davin, Bellcore Mike Davison, FiberCom Taso N. Devetzis, Bellcore Gary W. Haney, Martin Marietta Energy Systems Matt Hecht, SNMP Research, Inc. Susan E. Hicks, Martin Marietta Energy Systems Satish Joshi, SynOptics Mark Kepke, Hewlett-Packard Ken Key, SNMP Research, Inc. Michael Kornegay, Visisoft Deidre C. Kostick, Bellcore Cheryl Krupczak, Georgia Tech Robert C. Lushbaugh, Martin Marietta Energy Systems Keith McCloghrie, Hughes LAN Systems Dave Minnich, FiberCom Dave Perkins, SynOptics Marshall T. Rose, Dover Beach Consulting, Inc. Shawn A. Routhier, Epilogue Technology Jon Saperia, Digital Equipment Corporation Bob Stewart, Xyplex (chair) Robert Synder, Cisco Systems Maurice Turcotte, Racal Datacom Steven L. Waldbusser, Carnegie Mellon University Bert Wijnen, International Business Machines Peter Wilson, 3Com Steven Wong, Digital Equipment Corporation Expires May 12, 1993 [Page 14] Draft Textual Conventions for SNMPv2 Oct 92 Chris Young, Cabletron Kiho Yum, 3Com Expires May 12, 1993 [Page 15] Draft Textual Conventions for SNMPv2 Oct 92 6. References [1] Information processing systems - Open Systems Interconnection - Specification of Abstract Syntax Notation One (ASN.1), International Organization for Standardization. International Standard 8824, (December, 1987). [2] J.D. Case, K. McCloghrie, M.T. Rose, S.L. Waldbusser, Structure of Management Information for version 2 of the Simple Network Management Protocol, Internet-Draft, (October 7, 1992). Expires May 12, 1993 [Page 16] Draft Textual Conventions for SNMPv2 Oct 92 Table of Contents 1 Status of this Memo ................................... 1 2 Introduction .......................................... 2 2.1 A Note on Terminology ............................... 3 3 Definitions ........................................... 4 4 Mapping of the TEXTUAL-CONVENTION macro ............... 11 4.1 Mapping of the DISPLAY-HINT clause .................. 11 4.2 Mapping of the STATUS clause ........................ 12 4.3 Mapping of the DESCRIPTION clause ................... 13 4.4 Mapping of the REFERENCE clause ..................... 13 4.5 Mapping of the TEXTUAL-CONVENTION value ............. 13 5 Acknowledgements ...................................... 14 6 References ............................................ 16 Expires May 12, 1993 [Page 17]