idnits 2.17.1 draft-perkins-bits-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 7, 1997) is 9819 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 1902 (ref. '1') (Obsoleted by RFC 2578) ** Obsolete normative reference: RFC 1903 (ref. '2') (Obsoleted by RFC 2579) ** Obsolete normative reference: RFC 1904 (ref. '3') (Obsoleted by RFC 2580) ** Downref: Normative reference to an Informational RFC: RFC 1215 (ref. '6') Summary: 15 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Expires December 1997 INTERNET-DRAFT 3 Draft BITS Pseudotype June 7, 1997 5 The BITS Pseudotype 6 for SMIv2 8 10 June 7, 1997 12 David T. Perkins 13 dperkins@snmpinfo.com 15 1. Status of this Memo 17 This document is an Internet Draft. Internet Drafts are working 18 documents of the Internet Engineering Task Force (IETF), its Areas, 19 and its Working Groups. Note that other groups may also distribute 20 working documents as Internet Drafts. 22 Internet Drafts are draft documents valid for a maximum of six 23 months. Internet Drafts may be updated, replaced, or obsoleted by 24 other documents at any time. It is not appropriate to use Internet 25 Drafts as reference material or to cite them other than as a 26 "working draft" or "work in progress." 28 To learn the current status of any Internet-Draft, please check the 29 "1id-abstracts.txt" listing contained in the internet-drafts Shadow 30 Directories on: 32 ftp.is.co.za (Africa) 33 nic.nordu.net (Europe) 34 ds.internic.net (US East Coast) 35 ftp.isi.edu (US West Coast) 36 munnari.oz.au (Pacific Rim) 37 Draft BITS Pseudotype June 7, 1997 39 2. Introduction 41 This memo is informational. It specifies replacement text for version 42 2 of the SNMP SMI, which is defined by RFCs 1902[1], 1903[2], and 43 1904[3], to fix the incorrect usage of ASN.1 to specify a BITS 44 pseudotype. The BITS pseudotype must have the look and functions of 45 an ASN.1 type in the following constructs allowed in SMIv2 format MIB 46 modules: OBJECT-TYPE, SEQUENCE, MODULE-COMPLIANCE, AGENT-CAPABILITIES, 47 TEXTUAL-CONVENTION, and type assignments. The ASN.1 macros defined in 48 RFCs 1902, 1903, and 1904 do not support the requirements. 50 This memo supplies a replacement definition of the BITS pseudotype, 51 and updates for the OBJECT-TYPE macro and the TEXTUAL-CONVENTION macro 52 to be used in the next update of the SNMP SMI. A definition of the 53 BITS pseudotype is given using the ASN.1 macro notation. Also 54 included in this memo is the extended BNF notation describing the 55 syntax for this construct, and the guidelines for conversion between 56 MIB modules in the SMIv1 format, which is defined by RFCs 1155[4], 57 1212[5], and 1215[6], and those using this pseudotype. 59 This memo specifies a clarification for version 2 of the SNMP SMI, 60 which is a standard for the Internet community. 62 Draft BITS Pseudotype June 7, 1997 64 3. The ASN.1 Macro for the BITS Pseudotype 66 BITS MACRO ::= 67 BEGIN 68 -- Note: ASN.1 macro notation is too limiting to specify all the 69 -- rules for usage. Additional rules are specified as comments. 71 TYPE NOTATION ::= 72 -- in SEQUENCES, cannot name any bits 73 -- (for example, SEQUENCE { o1 BITS, o2 Integer32 }) 74 empty 75 -- in SYNTAX clause, must specify the named bits 76 | "{" NamedBits "}" 78 -- The following is just to specify the syntax 79 -- for values, but does not "deliver" a useful value 80 VALUE NOTATION ::= 81 "{" NamedBitVal "}" 82 84 -- the names of bits in a value 85 NamedBitVal ::= 86 identifier 87 | NamedBitVal "," identifier 89 -- the names of bits in the type definition 90 NamedBits ::= 91 NamedBit 92 | NamedBits "," NamedBit 94 -- The bits are named and identified by their position in the 95 -- octet string. Position zero is the high order (or left-most) 96 -- bit in the first octet of the string. Position 7 is the 97 -- low order (or right-most) bit of the first octet of the string. 98 -- Position 8 is the high order bit in the second octet of the 99 -- string, and so on. For an instance of a BITS macro, all named 100 -- bits for that instance must be unique and the names must start 101 -- with a lowercase letter. Also, all the positions for that 102 -- instance must be unique and range from zero to the last one 103 -- specified. The bits do not need to be named in any order, 104 -- however, all positions for bits must be specified. 105 -- The identifier must consist of one or more letters or digits 106 -- (no hyphens), up to a maximum of 64 characters, and the 107 -- initial character must be a lower-case letter. 108 NamedBit ::= identifier "(" number ")" 110 END 111 Draft BITS Pseudotype June 7, 1997 113 4. The extended BNF for the BITS Pseudotype 115 When used as a type, the BITS pseudotype is defined by production 116 . When used as a value, the BITS pseudotype is defined 117 by production . 119 = 120 "BITS" -- in a sequence 121 | "BITS" "{" [ "," ]... "}" -- elsewhere 123 = identifier "(" number ")" 125 = "{" [ identifier ["," identifier]... ] "}" 127 Where: 128 identifier must consist of one or more letters or digits 129 (no hyphens), up to a maximum of 64 characters, and the 130 initial character must be a lower-case letter. 132 Number is an unsigned integer less than 2^16 (65536). 134 5. Mapping of the BITS Pseudotype 136 The BITS pseudotype represents an enumeration of named bits. (The 137 pseudotype looks like the ASN.1 type BIT STRING, but maps to type 138 OCTET STRING.) Each collection of named bits is assigned non-negative, 139 contiguous values, starting at zero. However, the bits do not need to 140 be named in any order in the definition of the collection as long as 141 the resulting collection names all bits contiguously. 143 The maximum number of enumerations is 2^16 (65536). MIB designers 144 should realize that there may be implementation and interoperability 145 limitations for sizes in excess of 128 bits. 147 Finally, the identifier (also called a label) for a named bit must 148 consist of one or more letters or digits (no hyphens), up to a maximum 149 of 64 characters, and the initial character must be a lower-case 150 letter. (However, labels longer than 32 characters are not 151 recommended.) 153 Values for the BITS pseudotype are encoded as values for the ASN.1 154 OCTET STRING type, with the bits packed 8 per octet. Bits are 155 numbered by their position, starting at zero. Position zero is the 156 high order (or left-most) bit in the first octet of the string. 157 Position 7 is the low order (or right-most) bit of the first octet of 158 the string. Position 8 is the high order bit in the second octet of 159 the string, and so on. When the number of bits is not a multiple of 160 Draft BITS Pseudotype June 7, 1997 162 eight, then there will be remaining bits in the final octet. When a 163 value of the pseudotype BITS is encoded, the remaining bits, if any, 164 of the final octet are set to zero. On decoding a value of the 165 pseudotype BITS, the remaining bits, if any, of the final octet are 166 ignored. 168 6. Example Usage 170 The BITS pseudotype can be used in the follow situations in MIB 171 modules: 173 In an OBJECT-TYPE construct, for example: 175 o1 OBJECT-TYPE 176 SYNTAX BITS { blue(0), red(1), green(2) } 177 MAX-ACCESS read-create 178 STATUS current 179 DESCRIPTION "Example object" 180 DEFVAL { { blue, green } } 181 ::= { a1Entry 4 } 183 In a TEXTUAL-CONVENTION construct, for example: 185 T1 TEXTUAL-CONVENTION 186 STATUS current 187 DESCRIPTION "Example textual convention" 188 SYNTAX BITS { fire(0), wind(1), rain(2) } 190 In a type assignment, for example: 192 T1 ::= BITS { smooth(0), flexible(1), warm(2) } 194 In a SEQUENCE definition, for example: 196 S1Entry ::= SEQUENCE { 197 o1 BITS, 198 o2 Integer32 } 199 Draft BITS Pseudotype June 7, 1997 201 In a MODULE-COMPLIANCE construct, for example: 203 mc1 MODULE-COMPLIANCE 204 STATUS current 205 DESCRIPTION "Example module compliance" 206 MODULE 207 MANDATORY-GROUPS { g1 } 208 OBJECT o1 209 SYNTAX BITS { fire(0), wind(1) } 210 WRITE-SYNTAX BITS { fire(0) } 211 DESCRIPTION "Example variation" 212 ::= { mc 1 } 214 In an AGENT-CAPABILITIES construct, for example: 216 ac1 AGENT-CAPABILITIES 217 PRODUCT-RELEASE "Example product" 218 STATUS current 219 DESCRIPTION "Example agent capabilities" 220 SUPPORTS M1 221 INCLUDES { g1 } 222 VARIATION o1 223 SYNTAX BITS { fire(0), wind(1) } 224 WRITE-SYNTAX BITS { fire(0) } 225 DEFVAL { { wind } } 226 ::= { ac 1 } 228 7. Conversion Between SMIv1 and SMIv2 MIB Module Formats 230 When a MIB module written in the SMIv2 format is converted to the 231 SMIv1 format, the BITS pseudotype must be translated to an OCTET 232 STRING type with a SIZE clause specified. The SIZE must be fixed to 233 the number of octets required to encode the bits. This is the 234 FLOOR((numberOfBits + 7)/8). The following are examples of SYNTAX 235 clauses 236 in SMIv2 converted to SYNTAX clauses in SMIv1: 238 SMIv2 -- SYNTAX BITS { fire(1), wind(0), rain(2) } 239 SMIv1 -- SYNTAX OCTET STRING (SIZE(1)) 241 SMIv2 -- SYNTAX BITS { sun(0), mon(1), tues(2), wed(3), thur(4), 242 fri(5), sat(6), holiday(7), } 243 SMIv1 -- SYNTAX OCTET STRING (SIZE(1)) 245 SMIv2 -- SYNTAX BITS { a(0), b(1), c(2), d(3), e(4), f(5), g(6), 246 h(7), i(8), j(9), k(10) } 247 SMIv1 -- SYNTAX OCTET STRING (SIZE(2)) 248 Draft BITS Pseudotype June 7, 1997 250 SMIv2 -- Tc1 ::= BITS { red(0), blue(1), green(2) } 251 -- SYNTAX Tc1 252 SMIv1 -- Tc1 ::= OCTET STRING (SIZE(1)) 253 -- SYNTAX Tc1 255 The BITS pseudotype does not exist in SMIv1. Thus, there is no 256 programmatic method to convert types in SMIv1 MIB modules to the BITS 257 pseudotype in SMIv2. However, items with the OCTET STRING type that 258 have identical semantics to the BITS pseudotype should be converted to 259 the BITS pseudotype. This can only be determined by examining the 260 description text in each usage of a fixed length OCTET STRING type. 262 To ease the conversion between SMIv1 and SMIv2 formats of MIB modules, 263 the following textual convention should be used: 265 -- The BITSv1 textual convention has the same semantics as the 266 -- BITS pseudotype in SMIv2. Bits are packed 8 per octet, and 267 -- numbered starting at zero. The first bit (the bit 268 -- numbered zero) is the most significant bit in the first octet. 269 -- The eighth bit (the bit numbered seven) is the least 270 -- significant bit in the first octet. The ninth bit (the 271 -- bit numbered eight) is the most significant bit in the second 272 -- octet, and so on. When the number of bits is not a multiple of 273 -- eight, then there will be remaining bits in the final octet. 274 -- When a value of the textual convention BITSv1 is encoded, the 275 -- remaining bits, if any, of the final octet are set to zero. 276 -- On decoding a value of the textual convention BITSv1, the 277 -- remaining bits, if any, of the final octet are ignored. 278 -- Note that a SIZE clause must be specified with each usage of 279 -- the BITSv1 textual convention. Also, the named bits must be 280 -- specified in a description clause or in ASN.1 comments. 281 BITSv1 ::= OCTET STRING (SIZE (0..8192)) 283 The previous specified examples are shown below using the BITSv1 284 textual convention: 286 SMIv2 -- SYNTAX BITS { fire(1), wind(0), rain(2) } 287 SMIv1 -- SYNTAX BITSv1 (SIZE(1)) -- bits are fire(1), wind(0), 288 -- and rain(2) 290 SMIv2 -- SYNTAX BITS { sun(0), mon(1), tues(2), wed(3), thur(4), 291 fri(5), sat(6), holiday(7) } 292 SMIv1 -- SYNTAX BITSv1 (SIZE(1)) -- bits are sun(0), mon(1), 293 -- tues(2), wed(3), thur(4), 294 -- fri(5), sat(6), and 295 -- holiday(7) } 296 Draft BITS Pseudotype June 7, 1997 298 SMIv2 -- SYNTAX BITS { a(0), b(1), c(2), d(3), e(4), f(5), g(6), 299 h(7), i(8), j(9), k(10) } 300 SMIv1 -- SYNTAX BITSv1 (SIZE(2)) -- bits are a(0), b(1), c(2), 301 -- d(3), e(4), f(5), g(6), 302 -- h(7), i(8), j(9), and k(10) 304 SMIv2 -- Tc1 ::= BITS { red(0), blue(1), green(2) } 305 -- SYNTAX Tc1 306 SMIv1 -- Tc1 ::= BITSv1 (SIZE(1)) -- bits are red(0), blue(1), 307 -- and green(2) 308 -- SYNTAX Tc1 310 9. Update For the OBJECT-TYPE Macro 312 -- definition for objects 314 OBJECT-TYPE MACRO ::= 315 BEGIN 316 TYPE NOTATION ::= 317 "SYNTAX" Syntax 318 UnitsPart 319 "MAX-ACCESS" Access 320 "STATUS" Status 321 "DESCRIPTION" Text 322 ReferPart 323 IndexPart 324 DefValPart 326 VALUE NOTATION ::= 327 value(VALUE ObjectName) 329 Syntax ::= 330 -- the ASN.1 type specified may be any base SNMP data type 331 -- (or pseudotype) or a textual convention, and may be 332 -- sub-typed if allowed. 333 type(ObjectSyntax) 335 UnitsPart ::= 336 "UNITS" Text 337 | empty 339 Access ::= 340 "not-accessible" 341 | "accessible-for-notify" 342 | "read-only" 343 | "read-write" 344 | "read-create" 345 Draft BITS Pseudotype June 7, 1997 347 Status ::= 348 "current" 349 | "deprecated" 350 | "obsolete" 352 ReferPart ::= 353 "REFERENCE" Text 354 | empty 356 IndexPart ::= 357 "INDEX" "{" IndexTypes "}" 358 | "AUGMENTS" "{" Entry "}" 359 | empty 360 IndexTypes ::= 361 IndexType 362 | IndexTypes "," IndexType 363 IndexType ::= 364 "IMPLIED" Index 365 | Index 366 Index ::= 367 -- use the SYNTAX value of the 368 -- correspondent OBJECT-TYPE invocation 369 value(Indexobject ObjectName) 370 Entry ::= 371 -- use the INDEX value of the 372 -- correspondent OBJECT-TYPE invocation 373 value(Entryobject ObjectName) 375 DefValPart ::= 376 "DEFVAL" "{" value(Defval Syntax) "}" 377 | empty 379 -- uses the NVT ASCII character set 380 Text ::= """" string """" 381 END 383 10. Update For the TEXTUAL-CONVENTION Macro 385 -- definition of textual conventions 387 TEXTUAL-CONVENTION MACRO ::= 388 BEGIN 389 TYPE NOTATION ::= 390 DisplayPart 391 "STATUS" Status 392 "DESCRIPTION" Text 393 ReferPart 394 "SYNTAX" Syntax 395 Draft BITS Pseudotype June 7, 1997 397 VALUE NOTATION ::= 398 value(VALUE Syntax) 400 DisplayPart ::= 401 "DISPLAY-HINT" Text 402 | empty 404 Status ::= 405 "current" 406 | "deprecated" 407 | "obsolete" 409 ReferPart ::= 410 "REFERENCE" Text 411 | empty 413 -- uses the NVT ASCII character set 414 Text ::= """" string """" 416 Syntax ::= 417 -- the ASN.1 type specified may be any base SNMP data type 418 -- (or pseudotype) or a textual convention, and may be 419 -- sub-typed if allowed. 420 type(ObjectSyntax) 422 END 424 11. Acknowledgments 426 Thanks go to Bancroff Scott for his assistance on the BITS macro. 428 12. References 430 [1] J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Structure of 431 Management Information for Version 2 of the Simple Network 432 Management Protocol (SNMPv2)", RFC 1902, 01/22/1996. 434 [2] J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Textual 435 Conventions for Version 2 of the Simple Network Management 436 Protocol (SNMPv2)", RFC 1903, 01/22/1996. 438 [3] J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Conformance 439 Statements for Version 2 of the Simple Network Management 440 Protocol (SNMPv2)", RFC 1904, 01/22/1996. 442 Draft BITS Pseudotype June 7, 1997 444 [4] K. McCloghrie, M. Rose, "Structure and Identification of 445 Management Information for TCP/IP-based Internets", RFC 1155, 446 05/10/1990. 448 [5] K. McCloghrie, M. Rose, "Concise MIB Definitions", RFC 1212, 449 03/26/1991. 451 [6] M. Rose, "A Convention for Defining Traps for use with the SNMP", 452 RFC 1215, 03/27/1991.