INTERNET-DRAFT Expires December 1997 INTERNET-DRAFT Draft BITS Pseudotype June 7, 1997 The BITS Pseudotype for SMIv2 June 7, 1997 David T. Perkins dperkins@snmpinfo.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 12/07/97 [Page 1] Draft BITS Pseudotype June 7, 1997 2. Introduction This memo is informational. It specifies replacement text for version 2 of the SNMP SMI, which is defined by RFCs 1902[1], 1903[2], and 1904[3], to fix the incorrect usage of ASN.1 to specify a BITS pseudotype. The BITS pseudotype must have the look and functions of an ASN.1 type in the following constructs allowed in SMIv2 format MIB modules: OBJECT-TYPE, SEQUENCE, MODULE-COMPLIANCE, AGENT-CAPABILITIES, TEXTUAL-CONVENTION, and type assignments. The ASN.1 macros defined in RFCs 1902, 1903, and 1904 do not support the requirements. This memo supplies a replacement definition of the BITS pseudotype, and updates for the OBJECT-TYPE macro and the TEXTUAL-CONVENTION macro to be used in the next update of the SNMP SMI. A definition of the BITS pseudotype is given using the ASN.1 macro notation. Also included in this memo is the extended BNF notation describing the syntax for this construct, and the guidelines for conversion between MIB modules in the SMIv1 format, which is defined by RFCs 1155[4], 1212[5], and 1215[6], and those using this pseudotype. This memo specifies a clarification for version 2 of the SNMP SMI, which is a standard for the Internet community. Expires 12/07/97 [Page 2] Draft BITS Pseudotype June 7, 1997 3. The ASN.1 Macro for the BITS Pseudotype BITS MACRO ::= BEGIN -- Note: ASN.1 macro notation is too limiting to specify all the -- rules for usage. Additional rules are specified as comments. TYPE NOTATION ::= -- in SEQUENCES, cannot name any bits -- (for example, SEQUENCE { o1 BITS, o2 Integer32 }) empty -- in SYNTAX clause, must specify the named bits | "{" NamedBits "}" -- The following is just to specify the syntax -- for values, but does not "deliver" a useful value VALUE NOTATION ::= "{" NamedBitVal "}" -- the names of bits in a value NamedBitVal ::= identifier | NamedBitVal "," identifier -- the names of bits in the type definition NamedBits ::= NamedBit | NamedBits "," NamedBit -- The bits are named and identified by their position in the -- octet string. Position zero is the high order (or left-most) -- bit in the first octet of the string. Position 7 is the -- low order (or right-most) bit of the first octet of the string. -- Position 8 is the high order bit in the second octet of the -- string, and so on. For an instance of a BITS macro, all named -- bits for that instance must be unique and the names must start -- with a lowercase letter. Also, all the positions for that -- instance must be unique and range from zero to the last one -- specified. The bits do not need to be named in any order, -- however, all positions for bits must be specified. -- The identifier must consist of one or more letters or digits -- (no hyphens), up to a maximum of 64 characters, and the -- initial character must be a lower-case letter. NamedBit ::= identifier "(" number ")" END Expires 12/07/97 [Page 3] Draft BITS Pseudotype June 7, 1997 4. The extended BNF for the BITS Pseudotype When used as a type, the BITS pseudotype is defined by production . When used as a value, the BITS pseudotype is defined by production . = "BITS" -- in a sequence | "BITS" "{" [ "," ]... "}" -- elsewhere = identifier "(" number ")" = "{" [ identifier ["," identifier]... ] "}" Where: identifier must consist of one or more letters or digits (no hyphens), up to a maximum of 64 characters, and the initial character must be a lower-case letter. Number is an unsigned integer less than 2^16 (65536). 5. Mapping of the BITS Pseudotype The BITS pseudotype represents an enumeration of named bits. (The pseudotype looks like the ASN.1 type BIT STRING, but maps to type OCTET STRING.) Each collection of named bits is assigned non-negative, contiguous values, starting at zero. However, the bits do not need to be named in any order in the definition of the collection as long as the resulting collection names all bits contiguously. The maximum number of enumerations is 2^16 (65536). MIB designers should realize that there may be implementation and interoperability limitations for sizes in excess of 128 bits. Finally, the identifier (also called a label) for a named bit must consist of one or more letters or digits (no hyphens), up to a maximum of 64 characters, and the initial character must be a lower-case letter. (However, labels longer than 32 characters are not recommended.) Values for the BITS pseudotype are encoded as values for the ASN.1 OCTET STRING type, with the bits packed 8 per octet. Bits are numbered by their position, starting at zero. Position zero is the high order (or left-most) bit in the first octet of the string. Position 7 is the low order (or right-most) bit of the first octet of the string. Position 8 is the high order bit in the second octet of the string, and so on. When the number of bits is not a multiple of Expires 12/07/97 [Page 4] Draft BITS Pseudotype June 7, 1997 eight, then there will be remaining bits in the final octet. When a value of the pseudotype BITS is encoded, the remaining bits, if any, of the final octet are set to zero. On decoding a value of the pseudotype BITS, the remaining bits, if any, of the final octet are ignored. 6. Example Usage The BITS pseudotype can be used in the follow situations in MIB modules: In an OBJECT-TYPE construct, for example: o1 OBJECT-TYPE SYNTAX BITS { blue(0), red(1), green(2) } MAX-ACCESS read-create STATUS current DESCRIPTION "Example object" DEFVAL { { blue, green } } ::= { a1Entry 4 } In a TEXTUAL-CONVENTION construct, for example: T1 TEXTUAL-CONVENTION STATUS current DESCRIPTION "Example textual convention" SYNTAX BITS { fire(0), wind(1), rain(2) } In a type assignment, for example: T1 ::= BITS { smooth(0), flexible(1), warm(2) } In a SEQUENCE definition, for example: S1Entry ::= SEQUENCE { o1 BITS, o2 Integer32 } Expires 12/07/97 [Page 5] Draft BITS Pseudotype June 7, 1997 In a MODULE-COMPLIANCE construct, for example: mc1 MODULE-COMPLIANCE STATUS current DESCRIPTION "Example module compliance" MODULE MANDATORY-GROUPS { g1 } OBJECT o1 SYNTAX BITS { fire(0), wind(1) } WRITE-SYNTAX BITS { fire(0) } DESCRIPTION "Example variation" ::= { mc 1 } In an AGENT-CAPABILITIES construct, for example: ac1 AGENT-CAPABILITIES PRODUCT-RELEASE "Example product" STATUS current DESCRIPTION "Example agent capabilities" SUPPORTS M1 INCLUDES { g1 } VARIATION o1 SYNTAX BITS { fire(0), wind(1) } WRITE-SYNTAX BITS { fire(0) } DEFVAL { { wind } } ::= { ac 1 } 7. Conversion Between SMIv1 and SMIv2 MIB Module Formats When a MIB module written in the SMIv2 format is converted to the SMIv1 format, the BITS pseudotype must be translated to an OCTET STRING type with a SIZE clause specified. The SIZE must be fixed to the number of octets required to encode the bits. This is the FLOOR((numberOfBits + 7)/8). The following are examples of SYNTAX clauses in SMIv2 converted to SYNTAX clauses in SMIv1: SMIv2 -- SYNTAX BITS { fire(1), wind(0), rain(2) } SMIv1 -- SYNTAX OCTET STRING (SIZE(1)) SMIv2 -- SYNTAX BITS { sun(0), mon(1), tues(2), wed(3), thur(4), fri(5), sat(6), holiday(7), } SMIv1 -- SYNTAX OCTET STRING (SIZE(1)) SMIv2 -- SYNTAX BITS { a(0), b(1), c(2), d(3), e(4), f(5), g(6), h(7), i(8), j(9), k(10) } SMIv1 -- SYNTAX OCTET STRING (SIZE(2)) Expires 12/07/97 [Page 6] Draft BITS Pseudotype June 7, 1997 SMIv2 -- Tc1 ::= BITS { red(0), blue(1), green(2) } -- SYNTAX Tc1 SMIv1 -- Tc1 ::= OCTET STRING (SIZE(1)) -- SYNTAX Tc1 The BITS pseudotype does not exist in SMIv1. Thus, there is no programmatic method to convert types in SMIv1 MIB modules to the BITS pseudotype in SMIv2. However, items with the OCTET STRING type that have identical semantics to the BITS pseudotype should be converted to the BITS pseudotype. This can only be determined by examining the description text in each usage of a fixed length OCTET STRING type. To ease the conversion between SMIv1 and SMIv2 formats of MIB modules, the following textual convention should be used: -- The BITSv1 textual convention has the same semantics as the -- BITS pseudotype in SMIv2. Bits are packed 8 per octet, and -- numbered starting at zero. The first bit (the bit -- numbered zero) is the most significant bit in the first octet. -- The eighth bit (the bit numbered seven) is the least -- significant bit in the first octet. The ninth bit (the -- bit numbered eight) is the most significant bit in the second -- octet, and so on. When the number of bits is not a multiple of -- eight, then there will be remaining bits in the final octet. -- When a value of the textual convention BITSv1 is encoded, the -- remaining bits, if any, of the final octet are set to zero. -- On decoding a value of the textual convention BITSv1, the -- remaining bits, if any, of the final octet are ignored. -- Note that a SIZE clause must be specified with each usage of -- the BITSv1 textual convention. Also, the named bits must be -- specified in a description clause or in ASN.1 comments. BITSv1 ::= OCTET STRING (SIZE (0..8192)) The previous specified examples are shown below using the BITSv1 textual convention: SMIv2 -- SYNTAX BITS { fire(1), wind(0), rain(2) } SMIv1 -- SYNTAX BITSv1 (SIZE(1)) -- bits are fire(1), wind(0), -- and rain(2) SMIv2 -- SYNTAX BITS { sun(0), mon(1), tues(2), wed(3), thur(4), fri(5), sat(6), holiday(7) } SMIv1 -- SYNTAX BITSv1 (SIZE(1)) -- bits are sun(0), mon(1), -- tues(2), wed(3), thur(4), -- fri(5), sat(6), and -- holiday(7) } Expires 12/07/97 [Page 7] Draft BITS Pseudotype June 7, 1997 SMIv2 -- SYNTAX BITS { a(0), b(1), c(2), d(3), e(4), f(5), g(6), h(7), i(8), j(9), k(10) } SMIv1 -- SYNTAX BITSv1 (SIZE(2)) -- bits are a(0), b(1), c(2), -- d(3), e(4), f(5), g(6), -- h(7), i(8), j(9), and k(10) SMIv2 -- Tc1 ::= BITS { red(0), blue(1), green(2) } -- SYNTAX Tc1 SMIv1 -- Tc1 ::= BITSv1 (SIZE(1)) -- bits are red(0), blue(1), -- and green(2) -- SYNTAX Tc1 9. Update For the OBJECT-TYPE Macro -- definition for objects OBJECT-TYPE MACRO ::= BEGIN TYPE NOTATION ::= "SYNTAX" Syntax UnitsPart "MAX-ACCESS" Access "STATUS" Status "DESCRIPTION" Text ReferPart IndexPart DefValPart VALUE NOTATION ::= value(VALUE ObjectName) Syntax ::= -- the ASN.1 type specified may be any base SNMP data type -- (or pseudotype) or a textual convention, and may be -- sub-typed if allowed. type(ObjectSyntax) UnitsPart ::= "UNITS" Text | empty Access ::= "not-accessible" | "accessible-for-notify" | "read-only" | "read-write" | "read-create" Expires 12/07/97 [Page 8] Draft BITS Pseudotype June 7, 1997 Status ::= "current" | "deprecated" | "obsolete" ReferPart ::= "REFERENCE" Text | empty IndexPart ::= "INDEX" "{" IndexTypes "}" | "AUGMENTS" "{" Entry "}" | empty IndexTypes ::= IndexType | IndexTypes "," IndexType IndexType ::= "IMPLIED" Index | Index Index ::= -- use the SYNTAX value of the -- correspondent OBJECT-TYPE invocation value(Indexobject ObjectName) Entry ::= -- use the INDEX value of the -- correspondent OBJECT-TYPE invocation value(Entryobject ObjectName) DefValPart ::= "DEFVAL" "{" value(Defval Syntax) "}" | empty -- uses the NVT ASCII character set Text ::= """" string """" END 10. Update For the TEXTUAL-CONVENTION Macro -- definition of textual conventions TEXTUAL-CONVENTION MACRO ::= BEGIN TYPE NOTATION ::= DisplayPart "STATUS" Status "DESCRIPTION" Text ReferPart "SYNTAX" Syntax Expires 12/07/97 [Page 9] Draft BITS Pseudotype June 7, 1997 VALUE NOTATION ::= value(VALUE Syntax) DisplayPart ::= "DISPLAY-HINT" Text | empty Status ::= "current" | "deprecated" | "obsolete" ReferPart ::= "REFERENCE" Text | empty -- uses the NVT ASCII character set Text ::= """" string """" Syntax ::= -- the ASN.1 type specified may be any base SNMP data type -- (or pseudotype) or a textual convention, and may be -- sub-typed if allowed. type(ObjectSyntax) END 11. Acknowledgments Thanks go to Bancroff Scott for his assistance on the BITS macro. 12. 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. Expires 12/07/97 [Page 10] Draft BITS Pseudotype June 7, 1997 [4] K. McCloghrie, M. Rose, "Structure and Identification of Management Information for TCP/IP-based Internets", RFC 1155, 05/10/1990. [5] K. McCloghrie, M. Rose, "Concise MIB Definitions", RFC 1212, 03/26/1991. [6] M. Rose, "A Convention for Defining Traps for use with the SNMP", RFC 1215, 03/27/1991. Expires 12/07/97 [Page 11]