INTERNET-DRAFT Expires January 1997 INTERNET-DRAFT Draft SMI Clarification July 30, 1996 A Clarification of SMIv2 July 30, 1996 David T. Perkins dperkins@scruznet.com 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 progress." To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the internet-drafts Shadow Directories on: ftp.is.co.za (Africa) nic.nordu.net (Europe) ds.internic.net (US East Coast) ftp.isi.edu (US West Coast) munnari.oz.au (Pacific Rim) Expires 1/30/1997 [Page 1] Draft SMI Clarification July 30, 1996 2. Introduction This memo is a clarification of the structure of management information (SMI) for version 2 of the Simple Network Management Protocol (SNMP). SMIv2 is defined in RFCs 1902[1], 1903[2] and 1904[4]. This version is a rough first draft as requested by the SNMPv2 WG at the SMI Documentation BOF during the June 1996 IETF. This memo assumes that the reader has already read RFCs 1902-4 and generally understands the concepts defined in these documents. SMIv2 includes the definitions for the following items: 1. The model of management information; 2. The data types for management information; 3. The language for writing MIB modules; 4. Administrative assignments of a few key elements; 5. Rules for modifying published MIB modules; 6. A preferred mechanism to create and delete instances of columnar information through SNMP operations; and 7. A core set of textual conventions. The purpose of this document is to identify those areas related to the definition of data types and the language of writing MIB modules that are incomplete, ambiguous, incomprehensible or inconsistent and provide clarifications. It is not the goal of this document to change or extend the data types or the MIB module language. The data types and language for writing MIB modules are defined using a combination of ASN.1 specifications and textual prose. This approach to define these items is fatally flawed for the following reasons: 1. The dialect of the ASN.1 language used for these definitions was an early version and is now obsolete. Thus, its specification is not generally available. 2. There is not a clean separation between the elements used to define the MIB module language and the base definitions specified in the MIB module language. 3. The ASN.1 specifications used to define the MIB module language are incorrect. 4. A few constructs from programming languages, not found in ASN.1, were added to MIB module language. 5. A few "misinterpretations" of the ASN.1 language were allowed as constructs of the MIB module language. 6. The MIB module language uses different terminology than ASN.1 for a few key common elements of the languages. 3. Data Types The term "data types" refers to the range and meaning of values of management information. The primary purpose of the MIB module language Expires 1/30/1997 [Page 2] Draft SMI Clarification July 30, 1996 is to specify definitions of management information. Each definition includes the data type of the management information. The data types allowed in the MIB module language are a subset of the ASN.1 UNIVERSAL types, several ASN.1 APPLICATION types defined in the SMI, size or range limited versions of these types (called sub-types), pseudo-types, and semantically restricted versions of previously defined types (called textual conventions). The SNMPv2 base data types consist of the ASN.1 UNIVERSAL types, the ASN.1 APPLICATION types, and the pseudo-types. 3.1 Pseudo-types An item that has the look and function of an ASN.1 type, but is not strictly an ASN.1 type is called a pseudo-type. The SMI doesn't include this terminology, and instead calls it a construct. However, the term pseudo-type closely describes these elements and term is used throughout this memo. The definitions of the OBJECT-TYPE and TEXTUAL-CONVENTION macros are incorrect in their attempt to add the BITS pseudo-type. Also, the MODULE-COMPLIANCE and AGENT-CAPABILITIES macros lack allowing the BITS pseudo-type; and the BITS pseudo-type as currently defined can not be specified in a SEQUENCE definition. One valid approach in ASN.1 to specify the BITS pseudo-type can be found in "The BITS Pseudo-type for SNMPv2 SMI"[5]. Note that the current approach to defining BITS makes it appear that the BITS pseudo-type is built into ASN.1 and thus does not need to be imported before it is used. The valid approach specified in [5] requires that the BITS pseudo-type be imported before it can be used. 3.2 SNMP Data Types The base data types for SNMP are not clearly identified and defined. The allowed data types are: 1. ASN.1 UNIVERSAL - INTEGER (Integer32), OCTET STRING, and OBJECT IDENTIFIER 2. ASN.1 APPLICATION - Unsigned32, Gauge32, Counter32, Counter64, TimeTicks, IpAddress, and Opaque 3. Pseudo-type - BITS The remainder of this section points out the problem definitions and provides clarifications. 3.2.1 Integer32 The first of these data types with problem are INTEGER and Integer32. The definition of Integer32 in the SMI is incorrect, since an ASN.1 UNIVERSAL type may be defined only in the ASN.1 specification. This problem can easily corrected by modifying the line: Integer32 ::= [UNIVERSAL 2] Expires 1/30/1997 [Page 3] Draft SMI Clarification July 30, 1996 IMPLICIT INTEGER (-2147483648..2147483647) to read: Integer32 ::= INTEGER (-2147483648..2147483647) for the definition to be valid. The Integer32 data type was created to specify a limits for the range of signed integers. SMIv2 allows data type INTEGER to be used if a range is specified, but requires data type Integer32 to be used if no range is specified. However, SMIv2 restricts the range that can be specified on data type INTEGER to be identical to that for Integer32. This duplicity for no apparent reason, is confusing to readers of MIB modules. For this reason, the SMI should be modified so that the type INTEGER is only used for enumerated integers. 3.2.2 Enumerated Integers The construct INTEGER { } is used to define a data type that represents a small list of labeled values. This data type is called an enumerated integer. Note that the data type starts with "INTEGER {" and not "Integer32 {". The labeled values must be within the range allowed for data type Integer32. The SMI specifies that only the values listed are valid for objects defined with data type of enumerated integer. The SMI allows a textual convention to be assigned an enumerated integer data type, for example: TcA TEXTUAL-CONVENTION STATUS current DESCRIPTION "Example TC" SYNTAX INTEGER { one(1), two(2), three(3) } The SMI allows an enumerated type to be "refined", but does not explicitly specify how this is done. For example, if a refined version of textual convention TcA were to be used in a SYNTAX clause in an OBJECT-TYPE, TEXTUAL-CONVENTION, AGENT-CAPABILITIES, or MODULE- COMPLIANCE construct, which of the following two examples are valid? 1) SYNTAX TcA { one(1), three(3) } 2) SYNTAX INTEGER { one(1), three(3) } The first example, while not explicitly allowed or disallowed by the SMI is not allowed by current leading MIB compilers. The second form, unfortunately does not clearly indicate that it is refining the value of a previously defined data type. Thus, use of a refinement of a textual convention must use the "INTEGER { . . . }" construct, and must specify in the description clause name of the textual convention being refined. Expires 1/30/1997 [Page 4] Draft SMI Clarification July 30, 1996 Consider the following specific example. A TC, called OperStatus, is created, and shown below: OperStatus ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "The current or desired operational state of a sub-system. The values are: up(1) - ready to perform its function down(2) - not able to perform its function testing(3) - in some test mode and not able to perform its function unknown(4) - state can not be determined for some reason. dormant(5) - ready to perform its function after an external event occurs." SYNTAX INTEGER { up(1), down(2), testing(3), unknown(4), dormant(5) } If refinement could be specified directly on a TC, then this TC could be used in the following constructs: ifAdminStatus OBJECT-TYPE SYNTAX OperStatus { up(1), down(2), testing(3) } . . . -- rest of construct ifOperStatus OBJECT-TYPE SYNTAX OperStatus . . . -- rest of construct ifCompliance MODULE-COMPLIANCE . . . -- clauses left out OBJECT ifAdminStatus SYNTAX OperStatus { up(1), down(2) } MIN-ACCESS read-only DESCRIPTION "Write access is not required, nor is support for the value testing(3)." ::= { ifCompliances 1 } Note that ASN.1 has the ENUMERATED type. It is not an allowed data type in SNMP MIB modules. Also note that the type construct "INTEGER { . . . }" in ASN.1 is used to specify distinguished values and does not limit the values. Only an ASN.1 sub-type specification limits the range of values in INTEGER type specifications. The following type specification is valid in ASN.1 and is not valid in SNMP: INTEGER { freezing(32), boiling(212) } (-5..450) This type specification limits values between -5 and 450 inclusive and gives names to values 32 and 212. This can not be expressed in SNMP. The closest is the following data type specification in SNMP: Integer32 (-5..450) Expires 1/30/1997 [Page 5] Draft SMI Clarification July 30, 1996 3.2.3 OCTET STRING The SMI limits the maximum size of data type OCTET STRING to 65535. No such limit exists in ASN.1. The approach used in the SMI to specify this limitation is not valid ASN.1. A valid approach is to create a new type, like was done with Integer32, that is a size limited version of the OCTET STRING type. For example, the following definition could be added to the SMI: Octets ::= OCTET STRING ((SIZE(0..65535)) With this data type defined, all uses of data type OCTET SRTING would be required to be modified to Octets (just like that which was done with INTEGER and Integer32). 3.2.4 OBJECT IDENTIFIER The SMI limits the maximum values of components of a OID valid to 4294967295 and limits the maximum number of components to 128. (The SMI calls components, sub-identifiers, a term not used in ASN.1.) ASN.1 has no limit on the maximum number of components in an OID value. Also, there is no maximum for component values. (Note that ASN.1 (and the SMI) require that OID values have at least two components. The first value of the first component may be 0, 1, or 2. The value of the second component is limited to 39 if the first component has value 0 or 1.) The approach used in the SMI to specify the limitations on OID values is incorrect. A valid approach is to create a new type, like was done with Integer32, that has its length and values of components limited, which is based on the OBJECT IDENTIFIER type. For example, the following definition could be added to the SMI: OID ::= -- the maximum number of components is limited to 128 and -- the maximum value of a component is limited to 4294967295 OBJECT IDENTIFIER With this data type defined, all uses of data type OBJECT IDENTIFIER would be required to be modified to OID (just like that which was done with INTEGER and Integer32). 3.2.5 Opaque The Opaque data type is not size limited. This appears to be an over site. This could be corrected by replacing: Opaque ::= [APPLICATION 4] IMPLICIT OCTET STRING with the following definition: Opaque ::= [APPLICATION 4] IMPLICIT OCTET STRING(SIZE(0..65535)) A full description of the Opaque data type, which has been generally misunderstood by the SNMP community, is not included in the SMI. A full Expires 1/30/1997 [Page 6] Draft SMI Clarification July 30, 1996 explanation is specified in "The Domestication of the Opaque Type for SNMPv1 and SNMPv2"[6]. 4. Syntax of the MIB Module Language The SMI assumes that its readers are versed in the ASN.1 language, and thus omits important details describing the MIB module language. This assumption has been shown to be problematic by the variations observed in programs, called MIB compilers, which parse MIB modules. This is also shown by the recurring questions about the syntax of MIB modules that come up on the SNMP and SNMPv2 mailing lists, and the SNMP news group. One of the reasons why this has been so difficult for compiler writers is that the terms that are used in the SMI for elements of the MIB module language are different than that used for the same elements in the ASN.1 language. Traditionally, the syntax of a language is specified by the definition of the elementary items, or tokens, of the language, a grammar for the syntax, and text specifying the rules for valid passages of the language. Usually, parsers of a language have three functional areas. The first area performs lexical analysis of its input, which is usually a sequence of characters in a specified character set. The output from this functional area is a sequence of tokens. The next functional area reads the sequence of tokens to determine if they conform to the grammar of the language. The final functional area of a parser evaluates the statements in the input to determine if the passage (or program) is valid. Consider the following assignment statement in the C programming language: a = b; The lexical definition of the C programming language specifies rules for tokens in the language. The lexical analyzer would input the sequence of characters in the line and output the following tokens: identifier - value "a" punctuation - value "=" identifier - value "b" punctuation - value ";" The syntax analyzer would input the sequence of tokens and determine that they represented an assignment statement of the language. The semantic analyzer would then determine if the assignment statement was valid using rules such as are variables "a" and "b" known in the scope of the assignment statement, and are the data types for the variables compatible for assignment. Expires 1/30/1997 [Page 7] Draft SMI Clarification July 30, 1996 4.1 Lexical Specification The lexical elements of the MIB module language are specified by section 8 of the ASN.1 specification[4], augmented by the ASN.1 macros defined for the MIB module language, and modified by textual descriptions in SMIv2[1][2][3]. Also, there are standard practices found in most of the leading MIB compilers that are accepted by the SNMP community as part of the MIB module language. There has been no one place that integrates these into one coherent definition. This is now specified in "A Lexical Specification for the SNMPv2 MIB Module Language"[7], which also includes a Lex specification for the tokens of the language. (Lex is a widely used program to generate lexical analyzers.) 4.2 Grammar Specification The grammar for the MIB module language is specified by the ASN.1 specification[4], augmented by the ASN.1 macros defined for the MIB module language, and modified by textual descriptions in SMIv2[1][2][3]. Also, there are standard practices found in most of the leading MIB compilers that are accepted by the SNMP community as part of the MIB module language. There has been no one place that integrates these into one coherent definition. This is now specified in "A Grammar Specification for the SNMPv2 MIB Module Language"[8]. A grammar is presented in the form of extended BNF and also in the form of input for Yacc. (Yacc is a widely used program to generate parsers.) 4.3 Semantic Specifications The rules to determine if a MIB module is valid and the meaning of a MIB module are written in textual descriptions in SMIv2[1][2][3], and supported by the ASN.1 language[4]. Only a few MIB compilers perform more than trivial checking, and none check all the rules. There is only one known compiler that attempts complete checking. Also, there is much disagreement in the SNMP community over many issues in this area. What follows is in the format of topic and clarifying information. 4.3.1 Prime Directive of MIB Module Design Once definitions have been published, they can not be semantically changed, or deleted. Definitions that were flawed or are no longer useful may be retired by changing the value of their status to "obsolete". New definitions can be added to MIB modules. This is the most important rule for MIB module design and maintenance. Breaking it (or making exceptions for short term gain) should be avoided. Expires 1/30/1997 [Page 8] Draft SMI Clarification July 30, 1996 4.3.2 Format of Tokens in a MIB Module The tokens in a MIB module have no requirement to be on the same or different lines. Any requirements or restrictions in this area are those imposed by a non-compliant MIB parser. 4.3.3 Location of MODULE-IDENTITY Construct All MIB modules must include exactly one MODULE-IDENTITY construct which is located after the IMPORTS statement, and before any other construct in the MIB module. (Note that comments function as "white space" and thus may be specified before the MODULE-IDENTITY construct.) 4.3.4 Ordering of Constructs in a MIB Module The constructs in a MIB module, other than IMPORTS and MODULE-IDENTITY, may be specified in any order. This may result in a construct using an item which is defined later in the MIB module. For example, the OID value specified for the MODULE-IDENTITY may reference an OID value which is defined later in a MIB module. 4.3.5 Registration and Assignment of OID Values The ASN.1 language has no direct mechanism to register an OID value to an item. Registration is accomplished in ASN.1 through processes outside of ASN.1 modules. Registration is the permanent assignment of an OID value to an item. After a valid registration, the OID value can not be registered to another item for all time; the assignment is remembered for all time; and the semantics of the item can not be changed for all time. Given the OID value, the item (after registration) can be positively identified, for all time. The MIB module language contains constructs which are used to perform registration. These constructs are OBJECT-TYPE, MODULE-IDENTITY, OBJECT-IDENTITY, NOTIFICATION-TYPE, OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE, and AGENT-CAPABILITIES. A item defined with one of these constructs is permanently assigned the OID value specified in that construct. That OID value can not be used for any other permanent assignment - a registration. However, the OID value assignment construct is not a permanent assignment. Below is an example of an OID value assignment: system OBJECT IDENTIFIER ::= { mib 1 } This value assignment in a MIB module is not a registration. It is a convenience for the MIB designer to write the value { mib 1 }. Without such a shorthand mechanism, an OID value would need to be completely specified from the root or from an item with a permanently assigned OID value. For example, the OID value used in the OBJECT-TYPE construct for Expires 1/30/1997 [Page 9] Draft SMI Clarification July 30, 1996 sysDescr would be specified as { iso 3 6 1 2 1 1 1 } instead of { system 1 }. Note that it is valid in ASN.1 to write a module that contains more than one OID value assignment with the same OID value. This is shown below: v1 OBJECT IDENTIFIER ::= { mib 1 } v2 OBJECT IDENTIFIER ::= { mib 1 } The SNMPv2 SMI is completely silent on this and related issues. For example, can a MIB module contain an OID value assignment and a registration with the same OID value? This shown below: s1 OBJECT IDENTIFIER ::= { system 1 } sysDescr OBJECT-TYPE -- clauses (omitted) ::= { system 1 } The proper behavior is not well defined. 4.3.6 OID Values to Identify Modules 4.3.7 Module Names and OID Values in IMPORTS Statement 4.3.8 Well Known Names in an OID Value The nodes at the top of the OID value tree were assigned "well known" names by ISO and CCITT. ASN.1 compilers are expected to know these names. However, the list of names has expanded, and was changed when the CCITT changed its name to ITU. This is disruptive to MIB designers, users, and compiler writers. Thus, in the MIB module language, the only well known names are ccitt, iso, and joint-iso-ccitt. These names will never be changed, or will new names added, since this is not installed base friendly. 4.3.9 Max Length of MIB Module Names The SMI doesn't specify a max length. It should. Expires 1/30/1997 [Page 10] Draft SMI Clarification July 30, 1996 4.3.10 Required Constructs in a MIB Module Every MIB module must include an IMPORTS and a MODULE-IDENTITY statement. 4.3.11 Meaning of the Values of the STATUS Clause The meaning of the values of the STATUS clause are not well defined in SMIv2. The memo "A Clarification of the STATUS Clause in SNMP MIB Modules"[9] contains what the values mean, and what actions agent and management applications developers should take based on the value, and change of value. 4.3.12 The Value of the CONTACT-INFO Clause The examples given in the SMI for the values of the CONTACT-INFO clause of MODULE-IDENTITY in SMIv2 should not be used. Other information such as the working group name and mailing list need to be specified. 4.3.13 Objects in the INDEX Clause (This needs to be determined) 4.3.14 Consistency of Status Values Several constructs are dependent of the definitions of other items. For example, the INDEX clause in the OBJECT-TYPE construct names other items. Another example is a table object and the columnar objects with in the table. The SMI is silent on the relationships between the status of these objects. Thus, could the status of a row object be "current" if one of the objects in its INDEX clause has the status of "obsolete"? If a table object has its status changed to "obsolete", do all of the columnar objects in the table have to also have to have their status changed to "obsolete"? This issue needs to be resolved. 4.3.15 Module Compliances and Agent Capabilities (Some major work needed here - probably separate documents) 5. Relationships Between Objects (There needs to be a section or maybe another document about relationships between objects. This section needs to specify whether or not the RMON2 approach to indexing was valid or invalid, and give rules for how it should be used.) Expires 1/30/1997 [Page 11] Draft SMI Clarification July 30, 1996 6. References [1] J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1902, 01/22/1996. [2] J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1903, 01/22/1996. [3] J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1904, 01/22/1996. Management Information for version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1442, 05/03/1993. [4] Information processing systems - Open Systems Interconnection - Specification of Abstract Syntax Notation One (ASN.1), International Organization for Standardization. International Standard 8824, (December, 1987). [5] D. Perkins, "The BITS Pseudo-type for SNMPv2 SMI", internet-draft draft-perkins-bits-00.txt, 05/27/1996. [6] D. Perkins, "The Domestication of the Opaque Type for SNMPv1 and SNMPv2", internet-draft draft-perkins-opaque-00.txt, 05/27/1996. [7] D. Perkins, "A Lexical Specification for the SNMPv2 MIB Module Language", (yet to be posted internet-draft). [8] D. Perkins, "A Grammar Specification for the SNMPv2 MIB Module Language", (yet to be posted internet-draft). [9] D. Perkins, "A Clarification of the STATUS Clause in SNMP MIB Modules", internet-draft draft-rfced-info-perkins-01.txt Expires 1/30/1997 [Page 12] ----------------- /dperkins@scruznet.com, David T. Perkins Date: 07/30/96, Time: 09:11:35