home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_n_r / draft-perkins-bits-00.txt < prev    next >
Text File  |  1997-06-13  |  18KB  |  628 lines
  1.  
  2. INTERNET-DRAFT          Expires December 1997           INTERNET-DRAFT
  3.  
  4. Draft                      BITS Pseudotype                June 7, 1997
  5.  
  6.  
  7.                          The BITS Pseudotype
  8.                               for SMIv2
  9.  
  10.                      <draft-perkins-bits-00.txt>
  11.  
  12.                              June 7, 1997
  13.  
  14.                            David T. Perkins
  15.                         dperkins@snmpinfo.com
  16.  
  17.  
  18. 1.  Status of this Memo
  19.  
  20.    This document is an Internet Draft.  Internet Drafts are working
  21.    documents of the Internet Engineering Task Force (IETF), its Areas,
  22.    and its Working Groups. Note that other groups may also distribute
  23.    working documents as Internet Drafts.
  24.  
  25.    Internet Drafts are draft documents valid for a maximum of six
  26.    months.  Internet Drafts may be updated, replaced, or obsoleted by
  27.    other documents at any time.  It is not appropriate to use Internet
  28.    Drafts as reference material or to cite them other than as a
  29.    "working draft" or "work in progress."
  30.  
  31.    To learn the current status of any Internet-Draft, please check the
  32.    "1id-abstracts.txt" listing contained in the internet-drafts Shadow
  33.    Directories on:
  34.  
  35.          ftp.is.co.za (Africa)
  36.          nic.nordu.net (Europe)
  37.          ds.internic.net (US East Coast)
  38.          ftp.isi.edu (US West Coast)
  39.          munnari.oz.au (Pacific Rim)
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. Expires 12/07/97                                              [Page 1]
  59. Draft                      BITS Pseudotype                June 7, 1997
  60.  
  61.  
  62. 2.  Introduction
  63.  
  64. This memo is informational.  It specifies replacement text for version
  65. 2 of the SNMP SMI, which is defined by RFCs 1902[1], 1903[2], and
  66. 1904[3], to fix the incorrect usage of ASN.1 to specify a BITS
  67. pseudotype.  The BITS pseudotype must have the look and functions of
  68. an ASN.1 type in the following constructs allowed in SMIv2 format MIB
  69. modules: OBJECT-TYPE, SEQUENCE, MODULE-COMPLIANCE, AGENT-CAPABILITIES,
  70. TEXTUAL-CONVENTION, and type assignments.  The ASN.1 macros defined in
  71. RFCs 1902, 1903, and 1904 do not support the requirements.
  72.  
  73. This memo supplies a replacement definition of the BITS pseudotype,
  74. and updates for the OBJECT-TYPE macro and the TEXTUAL-CONVENTION macro
  75. to be used in the next update of the SNMP SMI.  A definition of the
  76. BITS pseudotype is given using the ASN.1 macro notation.  Also
  77. included in this memo is the extended BNF notation describing the
  78. syntax for this construct, and the guidelines for conversion between
  79. MIB modules in the SMIv1 format, which is defined by RFCs 1155[4],
  80. 1212[5], and 1215[6], and those using this pseudotype.
  81.  
  82. This memo specifies a clarification for version 2 of the SNMP SMI,
  83. which is a standard for the Internet community.
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115. Expires 12/07/97                                              [Page 2]
  116. Draft                      BITS Pseudotype                June 7, 1997
  117.  
  118.  
  119. 3.  The ASN.1 Macro for the BITS Pseudotype
  120.  
  121. BITS MACRO ::=
  122. BEGIN
  123.     -- Note: ASN.1 macro notation is too limiting to specify all the
  124.     -- rules for usage. Additional rules are specified as comments.
  125.  
  126.     TYPE NOTATION ::=
  127.         -- in SEQUENCES, cannot name any bits
  128.         -- (for example, SEQUENCE { o1 BITS, o2 Integer32 })
  129.         empty
  130.         -- in SYNTAX clause, must specify the named bits
  131.         | "{" NamedBits "}"
  132.  
  133.     -- The following is just to specify the syntax
  134.     -- for values, but does not "deliver" a useful value
  135.     VALUE NOTATION ::=
  136.         "{" NamedBitVal "}"
  137.         <VALUE OCTET STRING ::= ''H>
  138.  
  139.     -- the names of bits in a value
  140.     NamedBitVal ::=
  141.           identifier
  142.         | NamedBitVal "," identifier
  143.  
  144.     -- the names of bits in the type definition
  145.     NamedBits ::=
  146.           NamedBit
  147.         | NamedBits "," NamedBit
  148.  
  149.     -- The bits are named and identified by their position in the
  150.     -- octet string. Position zero is the high order (or left-most)
  151.     -- bit in the first octet of the string. Position 7 is the
  152.     -- low order (or right-most) bit of the first octet of the string.
  153.     -- Position 8 is the high order bit in the second octet of the
  154.     -- string, and so on.  For an instance of a BITS macro, all named
  155.     -- bits for that instance must be unique and the names must start
  156.     -- with a lowercase letter. Also, all the positions for that
  157.     -- instance must be unique and range from zero to the last one
  158.     -- specified. The bits do not need to be named in any order,
  159.     -- however, all positions for bits must be specified.
  160.     -- The identifier must consist of one or more letters or digits
  161.     -- (no hyphens), up to a maximum of 64 characters, and the
  162.     -- initial character must be a lower-case letter.
  163.     NamedBit ::= identifier "(" number ")"
  164.  
  165. END
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172. Expires 12/07/97                                              [Page 3]
  173. Draft                      BITS Pseudotype                June 7, 1997
  174.  
  175.  
  176. 4.  The extended BNF for the BITS Pseudotype
  177.  
  178. When used as a type, the BITS pseudotype is defined by production
  179. <bitsTypeRef>.  When used as a value, the BITS pseudotype is defined
  180. by production <bitsValueRef>.
  181.  
  182.     <bitsTypeRef> =
  183.           "BITS"   -- in a sequence
  184.         | "BITS" "{" <namedBit> [ "," <namedBit> ]... "}" -- elsewhere
  185.  
  186.     <namedBit> = identifier "(" number ")"
  187.  
  188.  
  189.     <bitsValueRef> = "{" [ identifier ["," identifier]... ] "}"
  190.  
  191.  
  192. Where:
  193.      identifier must consist of one or more letters or digits
  194.        (no hyphens), up to a maximum of 64 characters, and the
  195.        initial character must be a lower-case letter.
  196.  
  197.      Number is an unsigned integer less than 2^16 (65536).
  198.  
  199.  
  200.  
  201. 5.  Mapping of the BITS Pseudotype
  202.  
  203. The BITS pseudotype represents an enumeration of named bits. (The
  204. pseudotype looks like the ASN.1 type BIT STRING, but maps to type
  205. OCTET STRING.) Each collection of named bits is assigned non-negative,
  206. contiguous values, starting at zero.  However, the bits do not need to
  207. be named in any order in the definition of the collection as long as
  208. the resulting collection names all bits contiguously.
  209.  
  210. The maximum number of enumerations is 2^16 (65536).  MIB designers
  211. should realize that there may be implementation and interoperability
  212. limitations for sizes in excess of 128 bits.
  213.  
  214. Finally, the identifier (also called a label) for a named bit must
  215. consist of one or more letters or digits (no hyphens), up to a maximum
  216. of 64 characters, and the initial character must be a lower-case
  217. letter. (However, labels longer than 32 characters are not
  218. recommended.)
  219.  
  220. Values for the BITS pseudotype are encoded as values for the ASN.1
  221. OCTET STRING type, with the bits packed 8 per octet.  Bits are
  222. numbered by their position, starting at zero.  Position zero is the
  223. high order (or left-most) bit in the first octet of the string.
  224. Position 7 is the low order (or right-most) bit of the first octet of
  225. the string.  Position 8 is the high order bit in the second octet of
  226. the string, and so on.  When the number of bits is not a multiple of
  227.  
  228.  
  229. Expires 12/07/97                                              [Page 4]
  230. Draft                      BITS Pseudotype                June 7, 1997
  231.  
  232.  
  233. eight, then there will be remaining bits in the final octet.  When a
  234. value of the pseudotype BITS is encoded, the remaining bits, if any,
  235. of the final octet are set to zero.  On decoding a value of the
  236. pseudotype BITS, the remaining bits, if any, of the final octet are
  237. ignored.
  238.  
  239.  
  240. 6.  Example Usage
  241.  
  242. The BITS pseudotype can be used in the follow situations in MIB
  243. modules:
  244.  
  245.  
  246.  
  247.   In an OBJECT-TYPE construct, for example:
  248.  
  249.      o1 OBJECT-TYPE
  250.           SYNTAX         BITS { blue(0), red(1), green(2) }
  251.           MAX-ACCESS     read-create
  252.           STATUS         current
  253.           DESCRIPTION    "Example object"
  254.           DEFVAL         { { blue, green } }
  255.      ::= { a1Entry 4 }
  256.  
  257.  
  258.  
  259.   In a TEXTUAL-CONVENTION construct, for example:
  260.  
  261.      T1 TEXTUAL-CONVENTION
  262.           STATUS         current
  263.           DESCRIPTION    "Example textual convention"
  264.           SYNTAX         BITS { fire(0), wind(1), rain(2) }
  265.  
  266.  
  267.  
  268.   In a type assignment, for example:
  269.  
  270.      T1 ::= BITS { smooth(0), flexible(1), warm(2) }
  271.  
  272.  
  273.  
  274.   In a SEQUENCE definition, for example:
  275.  
  276.      S1Entry ::= SEQUENCE {
  277.           o1 BITS,
  278.           o2 Integer32 }
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286. Expires 12/07/97                                              [Page 5]
  287. Draft                      BITS Pseudotype                June 7, 1997
  288.  
  289.  
  290.   In a MODULE-COMPLIANCE construct, for example:
  291.  
  292.      mc1 MODULE-COMPLIANCE
  293.           STATUS         current
  294.           DESCRIPTION    "Example module compliance"
  295.           MODULE
  296.             MANDATORY-GROUPS { g1 }
  297.             OBJECT o1
  298.               SYNTAX          BITS { fire(0), wind(1) }
  299.               WRITE-SYNTAX    BITS { fire(0) }
  300.               DESCRIPTION     "Example variation"
  301.      ::= { mc 1 }
  302.  
  303.  
  304.   In an AGENT-CAPABILITIES construct, for example:
  305.  
  306.      ac1 AGENT-CAPABILITIES
  307.           PRODUCT-RELEASE     "Example product"
  308.           STATUS              current
  309.           DESCRIPTION         "Example agent capabilities"
  310.           SUPPORTS       M1
  311.             INCLUDES { g1 }
  312.             VARIATION o1
  313.               SYNTAX          BITS { fire(0), wind(1) }
  314.               WRITE-SYNTAX    BITS { fire(0) }
  315.               DEFVAL          { { wind } }
  316.      ::= { ac 1 }
  317.  
  318.  
  319. 7.  Conversion Between SMIv1 and SMIv2 MIB Module Formats
  320.  
  321. When a MIB module written in the SMIv2 format is converted to the
  322. SMIv1 format, the BITS pseudotype must be translated to an OCTET
  323. STRING type with a SIZE clause specified.  The SIZE must be fixed to
  324. the number of octets required to encode the bits.  This is the
  325. FLOOR((numberOfBits + 7)/8).  The following are examples of SYNTAX
  326. clauses
  327. in SMIv2 converted to SYNTAX clauses in SMIv1:
  328.  
  329.  
  330.     SMIv2 -- SYNTAX  BITS { fire(1), wind(0), rain(2) }
  331.     SMIv1 -- SYNTAX  OCTET STRING (SIZE(1))
  332.  
  333.     SMIv2 -- SYNTAX  BITS { sun(0), mon(1), tues(2), wed(3), thur(4),
  334.                             fri(5), sat(6), holiday(7), }
  335.     SMIv1 -- SYNTAX  OCTET STRING (SIZE(1))
  336.  
  337.     SMIv2 -- SYNTAX  BITS { a(0), b(1), c(2), d(3), e(4), f(5), g(6),
  338.                             h(7), i(8), j(9), k(10) }
  339.     SMIv1 -- SYNTAX  OCTET STRING (SIZE(2))
  340.  
  341.  
  342.  
  343. Expires 12/07/97                                              [Page 6]
  344. Draft                      BITS Pseudotype                June 7, 1997
  345.  
  346.  
  347.     SMIv2 -- Tc1 ::= BITS { red(0), blue(1), green(2) }
  348.           -- SYNTAX  Tc1
  349.     SMIv1 -- Tc1 ::= OCTET STRING (SIZE(1))
  350.           -- SYNTAX  Tc1
  351.  
  352.  
  353. The BITS pseudotype does not exist in SMIv1.  Thus, there is no
  354. programmatic method to convert types in SMIv1 MIB modules to the BITS
  355. pseudotype in SMIv2.  However, items with the OCTET STRING type that
  356. have identical semantics to the BITS pseudotype should be converted to
  357. the BITS pseudotype.  This can only be determined by examining the
  358. description text in each usage of a fixed length OCTET STRING type.
  359.  
  360.  
  361. To ease the conversion between SMIv1 and SMIv2 formats of MIB modules,
  362. the following textual convention should be used:
  363.  
  364.     -- The BITSv1 textual convention has the same semantics as the
  365.     -- BITS pseudotype in SMIv2.  Bits are packed 8 per octet, and
  366.     -- numbered starting at zero.  The first bit (the bit
  367.     -- numbered zero) is the most significant bit in the first octet.
  368.     -- The eighth bit (the bit numbered seven) is the least
  369.     -- significant bit in the first octet.  The ninth bit (the
  370.     -- bit numbered eight) is the most significant bit in the second
  371.     -- octet, and so on.  When the number of bits is not a multiple of
  372.     -- eight, then there will be remaining bits in the final octet.
  373.     -- When a value of the textual convention BITSv1 is encoded, the
  374.     -- remaining bits, if any, of the final octet are set to zero.
  375.     -- On decoding a value of the textual convention BITSv1, the
  376.     -- remaining bits, if any, of the final octet are ignored.
  377.     -- Note that a SIZE clause must be specified with each usage of
  378.     -- the BITSv1 textual convention.  Also, the named bits must be
  379.     -- specified in a description clause or in ASN.1 comments.
  380.     BITSv1  ::=  OCTET STRING (SIZE (0..8192))
  381.  
  382.  
  383. The previous specified examples are shown below using the BITSv1
  384. textual convention:
  385.  
  386.  
  387.     SMIv2 -- SYNTAX  BITS { fire(1), wind(0), rain(2) }
  388.     SMIv1 -- SYNTAX  BITSv1 (SIZE(1))  -- bits are fire(1), wind(0),
  389.                                        -- and rain(2)
  390.  
  391.     SMIv2 -- SYNTAX  BITS { sun(0), mon(1), tues(2), wed(3), thur(4),
  392.                             fri(5), sat(6), holiday(7) }
  393.     SMIv1 -- SYNTAX  BITSv1 (SIZE(1))  -- bits are sun(0), mon(1),
  394.                                        -- tues(2), wed(3), thur(4),
  395.                                        -- fri(5), sat(6), and
  396.                                        -- holiday(7) }
  397.  
  398.  
  399.  
  400. Expires 12/07/97                                              [Page 7]
  401. Draft                      BITS Pseudotype                June 7, 1997
  402.  
  403.  
  404.     SMIv2 -- SYNTAX  BITS { a(0), b(1), c(2), d(3), e(4), f(5), g(6),
  405.                             h(7), i(8), j(9), k(10) }
  406.     SMIv1 -- SYNTAX  BITSv1 (SIZE(2))  -- bits are a(0), b(1), c(2),
  407.                                        -- d(3), e(4), f(5), g(6),
  408.                                        -- h(7), i(8), j(9), and k(10)
  409.  
  410.     SMIv2 -- Tc1 ::= BITS { red(0), blue(1), green(2) }
  411.           -- SYNTAX  Tc1
  412.     SMIv1 -- Tc1 ::= BITSv1 (SIZE(1))  -- bits are red(0), blue(1),
  413.                                        -- and green(2)
  414.           -- SYNTAX  Tc1
  415.  
  416.  
  417. 9.  Update For the OBJECT-TYPE Macro
  418.  
  419.  
  420. -- definition for objects
  421.  
  422. OBJECT-TYPE MACRO ::=
  423. BEGIN
  424.     TYPE NOTATION ::=
  425.                   "SYNTAX" Syntax
  426.                   UnitsPart
  427.                   "MAX-ACCESS" Access
  428.                   "STATUS" Status
  429.                   "DESCRIPTION" Text
  430.                   ReferPart
  431.                   IndexPart
  432.                   DefValPart
  433.  
  434.     VALUE NOTATION ::=
  435.                   value(VALUE ObjectName)
  436.  
  437.     Syntax ::=
  438.            -- the ASN.1 type specified may be any base SNMP data type
  439.            -- (or pseudotype) or a textual convention, and may be
  440.            -- sub-typed if allowed.
  441.                   type(ObjectSyntax)
  442.  
  443.     UnitsPart ::=
  444.                   "UNITS" Text
  445.                 | empty
  446.  
  447.     Access ::=
  448.                   "not-accessible"
  449.                 | "accessible-for-notify"
  450.                 | "read-only"
  451.                 | "read-write"
  452.                 | "read-create"
  453.  
  454.  
  455.  
  456.  
  457. Expires 12/07/97                                              [Page 8]
  458. Draft                      BITS Pseudotype                June 7, 1997
  459.  
  460.  
  461.     Status ::=
  462.                   "current"
  463.                 | "deprecated"
  464.                 | "obsolete"
  465.  
  466.     ReferPart ::=
  467.                   "REFERENCE" Text
  468.                 | empty
  469.  
  470.     IndexPart ::=
  471.                   "INDEX"    "{" IndexTypes "}"
  472.                 | "AUGMENTS" "{" Entry      "}"
  473.                 | empty
  474.     IndexTypes ::=
  475.                   IndexType
  476.                 | IndexTypes "," IndexType
  477.     IndexType ::=
  478.                   "IMPLIED" Index
  479.                 | Index
  480.     Index ::=
  481.                     -- use the SYNTAX value of the
  482.                     -- correspondent OBJECT-TYPE invocation
  483.                   value(Indexobject ObjectName)
  484.     Entry ::=
  485.                     -- use the INDEX value of the
  486.                     -- correspondent OBJECT-TYPE invocation
  487.                   value(Entryobject ObjectName)
  488.  
  489.     DefValPart ::=
  490.                   "DEFVAL" "{" value(Defval Syntax) "}"
  491.                 | empty
  492.  
  493.     -- uses the NVT ASCII character set
  494.     Text ::= """" string """"
  495. END
  496.  
  497.  
  498. 10.  Update For the TEXTUAL-CONVENTION Macro
  499.  
  500.  
  501. -- definition of textual conventions
  502.  
  503. TEXTUAL-CONVENTION MACRO ::=
  504. BEGIN
  505.     TYPE NOTATION ::=
  506.                   DisplayPart
  507.                   "STATUS" Status
  508.                   "DESCRIPTION" Text
  509.                   ReferPart
  510.                   "SYNTAX" Syntax
  511.  
  512.  
  513.  
  514. Expires 12/07/97                                              [Page 9]
  515. Draft                      BITS Pseudotype                June 7, 1997
  516.  
  517.  
  518.     VALUE NOTATION ::=
  519.                   value(VALUE Syntax)
  520.  
  521.     DisplayPart ::=
  522.                   "DISPLAY-HINT" Text
  523.                 | empty
  524.  
  525.     Status ::=
  526.                   "current"
  527.                 | "deprecated"
  528.                 | "obsolete"
  529.  
  530.     ReferPart ::=
  531.                   "REFERENCE" Text
  532.                 | empty
  533.  
  534.     -- uses the NVT ASCII character set
  535.     Text ::= """" string """"
  536.  
  537.     Syntax ::=
  538.            -- the ASN.1 type specified may be any base SNMP data type
  539.            -- (or pseudotype) or a textual convention, and may be
  540.            -- sub-typed if allowed.
  541.                  type(ObjectSyntax)
  542.  
  543. END
  544.  
  545.  
  546. 11.  Acknowledgments
  547.  
  548. Thanks go to Bancroff Scott for his assistance on the BITS macro.
  549.  
  550.  
  551.  
  552. 12.  References
  553.  
  554.  
  555. [1]  J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Structure of
  556.      Management Information for Version 2 of the Simple Network
  557.      Management Protocol (SNMPv2)", RFC 1902, 01/22/1996.
  558.  
  559. [2]  J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Textual
  560.      Conventions for Version 2 of the Simple Network Management
  561.      Protocol (SNMPv2)", RFC 1903, 01/22/1996.
  562.  
  563. [3]  J. Case, K. McCloghrie, M. Rose, S. Waldbusser, "Conformance
  564.      Statements for Version 2 of the Simple Network Management
  565.      Protocol (SNMPv2)", RFC 1904, 01/22/1996.
  566.  
  567.  
  568.  
  569.  
  570.  
  571. Expires 12/07/97                                             [Page 10]
  572. Draft                      BITS Pseudotype                June 7, 1997
  573.  
  574.  
  575. [4]  K. McCloghrie, M. Rose, "Structure and Identification of
  576.      Management Information for TCP/IP-based Internets", RFC 1155,
  577.      05/10/1990.
  578.  
  579. [5]  K. McCloghrie, M. Rose, "Concise MIB Definitions", RFC 1212,
  580.      03/26/1991.
  581.  
  582. [6]  M. Rose, "A Convention for Defining Traps for use with the SNMP",
  583.      RFC 1215, 03/27/1991.
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628. Expires 12/07/97                                             [Page 11]