Draft Textual Conventions for SMP Jul 92 Textual Conventions for the Simple Management Protocol (SMP) Framework Sat Jul 4 17:76:03 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 draft documents valid for a maximum of six months. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as a "working draft" or "work in Expires January 4, 1993 [Page 1] Draft Textual Conventions for SMP Jul 92 progress". Please check the 1id-abstracts.txt listing contained in the internet-drafts Shadow Directories on nic.ddn.mil, nnsc.nsf.net, nic.nordu.net, ftp.nisc.sri.com, or munnari.oz.au to learn the current status of any Internet Draft. Please send comments to the SNMP discussion group, . Expires January 4, 1993 [Page 2] Draft Textual Conventions for SMP Jul 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). 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. Expires January 4, 1993 [Page 3] Draft Textual Conventions for SMP Jul 92 3. Definitions SMP-TC DEFINITIONS ::= BEGIN IMPORTS ObjectSyntax, Integer32, TimeTicks FROM SMP-SMI; -- definition of textual conventions TEXTUAL-CONVENTION MACRO ::= BEGIN TYPE NOTATION ::= DisplayPart "DESCRIPTION" value(description Text) ReferPart VALUE NOTATION ::= type(VALUE ObjectSyntax) DisplayPart ::= "DISPLAY-HINT" value(display Text) | empty ReferPart ::= "REFERENCE" value(reference Text) | empty -- uses the NVT ASCII character set Text ::= OCTET STRING END DisplayString TEXTUAL-CONVENTION DISPLAY-HINT "255a" DESCRIPTION "Represents textual information taken from the NVT 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 Expires January 4, 1993 [Page 4] Draft Textual Conventions for SMP Jul 92 DISPLAY-HINT "1x:" DESCRIPTION "Represents media- or physical-level addresses." ::= OCTET STRING MacAddress TEXTUAL-CONVENTION DISPLAY-HINT "1x:" 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 DESCRIPTION "Represents a boolean value." ::= INTEGER { true(1), false(2) } TestAndIncr TEXTUAL-CONVENTION 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 `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 previous value held by the instance is returned.) The value of the ACCESS clause for objects having this syntax is either `read-write' or `read- Expires January 4, 1993 [Page 5] Draft Textual Conventions for SMP Jul 92 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 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 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 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 either `underModification(3)' or `active(4)'. 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 `underCreation(1)'. 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 SMP entity, and the value of the DEFVAL clause for the status column is `active(4)', then the SMP entity acting Expires January 4, 1993 [Page 6] Draft Textual Conventions for SMP Jul 92 in an agent role immediately sets the value of this instance to `active(4)'. Otherwise, the SMP entity acting in an agent role immediately sets the value of this instance to `underModification(3)'. 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 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(3)' or `active(4)', 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(4)', will the information in the conceptual row be available outside of the management subsystem, i.e., whilst the information is available to authorized SMP entities acting in a manager role, the information is independent of Expires January 4, 1993 [Page 7] Draft Textual Conventions for SMP Jul 92 the operational state of the managed device. As such, note that while the status is `underModification(3)', it is possible for a managed device to create (or otherwise manipulate) its own instances which effectively supersede those held by the SMP 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(3)' state, consuming resources indefinitely. The SMP entity acting in an agent role may detect conceptual rows that have been in the `underModification(3) 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(4)'. 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(2)'. If the operation succeeds, then the entire conceptual row is immediately removed from the table." ::= INTEGER { underCreation(1), underDestruction(2), underModification(3), active(4) } TimeStamp TEXTUAL-CONVENTION 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 DESCRIPTION "A period of time, measured in units of 0.01 Expires January 4, 1993 [Page 8] Draft Textual Conventions for SMP Jul 92 seconds." ::= Integer32 END Expires January 4, 1993 [Page 9] Draft Textual Conventions for SMP Jul 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 January 4, 1993 [Page 10] Draft Textual Conventions for SMP Jul 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. (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 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 Expires January 4, 1993 [Page 11] Draft Textual Conventions for SMP Jul 92 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.3. 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.4. 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]. Expires January 4, 1993 [Page 12] Draft Textual Conventions for SMP Jul 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. Expires January 4, 1993 [Page 13] Draft Textual Conventions for SMP Jul 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 the Simple Management Protocol (SMP) Framework, (July, 1992). Expires January 4, 1993 [Page 14] Draft Textual Conventions for SMP Jul 92 Table of Contents 1 Status of this Memo ................................... 1 2 Introduction .......................................... 3 3 Definitions ........................................... 4 4 Mapping of the TEXTUAL-CONVENTION macro ............... 10 4.1 Mapping of the DISPLAY-HINT clause .................. 10 4.2 Mapping of the DESCRIPTION clause ................... 11 4.3 Mapping of the REFERENCE clause ..................... 12 4.4 Mapping of the TEXTUAL-CONVENTION value ............. 12 5 Acknowledgements ...................................... 13 6 References ............................................ 14 Expires January 4, 1993 [Page 15]