INTERNET-DRAFT Expires December 1997 INTERNET-DRAFT
Draft BITS Pseudotype June 7, 1997
The BITS Pseudotype
for SMIv2
<draft-perkins-bits-00.txt>
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 "}"
<VALUE OCTET STRING ::= ''H>
-- 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
<bitsTypeRef>. When used as a value, the BITS pseudotype is defined
by production <bitsValueRef>.
<bitsTypeRef> =
"BITS" -- in a sequence
| "BITS" "{" <namedBit> [ "," <namedBit> ]... "}" -- elsewhere
<namedBit> = identifier "(" number ")"
<bitsValueRef> = "{" [ 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]