Network Working Group F. Strauss Internet-Draft J. Schoenwaelder Expires: May 11, 2001 TU Braunschweig K. McCloghrie Cisco Systems, Inc. November 10, 2000 SMIng - A new Structure of Management Information draft-irtf-nmrg-sming-03.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on May 11, 2001. Abstract This memo presents an object-oriented language for various kinds of management information specifications. It is independent of management protocols and applications. Protocol mappings are defined as extensions to this language in separate memos. However, the primarily targeted applications of this language are SNMP and COPS-PR in a way that this language can replace the SMIv2 and SPPI. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Strauss, et. al. Expires May 11, 2001 [Page 1] Internet-Draft SMIng November 2000 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 2. The Information Model . . . . . . . . . . . . . . . . . . . 6 2.1 Identifiers . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Base Types and Derived Types . . . . . . . . . . . . . . . . 9 3.1 OctetString . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2 Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.3 Integer32 . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.4 Integer64 . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.5 Unsigned32 . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.6 Unsigned64 . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.7 Float32 . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.8 Float64 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.9 Float128 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.10 Enumeration . . . . . . . . . . . . . . . . . . . . . . . . 17 3.11 Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.12 Display Formats . . . . . . . . . . . . . . . . . . . . . . 18 4. The SMIng File Structure . . . . . . . . . . . . . . . . . . 21 4.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.2 Statements and Arguments . . . . . . . . . . . . . . . . . . 21 5. The module Statement . . . . . . . . . . . . . . . . . . . . 22 5.1 The module's import Statement . . . . . . . . . . . . . . . 22 5.2 The module's organization Statement . . . . . . . . . . . . 23 5.3 The module's contact Statement . . . . . . . . . . . . . . . 23 5.4 The module's description Statement . . . . . . . . . . . . . 23 5.5 The module's revision Statement . . . . . . . . . . . . . . 23 5.5.1 The revision's date Statement . . . . . . . . . . . . . . . 23 5.5.2 The revision's description Statement . . . . . . . . . . . . 23 5.6 Usage Example . . . . . . . . . . . . . . . . . . . . . . . 24 6. The extension Statement . . . . . . . . . . . . . . . . . . 25 6.1 The extension's status Statement . . . . . . . . . . . . . . 25 6.2 The extension's description Statement . . . . . . . . . . . 25 6.3 The extension's abnf Statement . . . . . . . . . . . . . . . 25 7. The typedef Statement . . . . . . . . . . . . . . . . . . . 27 7.1 The typedef's type Statement . . . . . . . . . . . . . . . . 27 7.2 The typedef's default Statement . . . . . . . . . . . . . . 27 7.3 The typedef's format Statement . . . . . . . . . . . . . . . 27 7.4 The typedef's units Statement . . . . . . . . . . . . . . . 28 7.5 The typedef's status Statement . . . . . . . . . . . . . . . 28 7.6 The typedef's description Statement . . . . . . . . . . . . 29 7.7 Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 29 8. The identity Statement . . . . . . . . . . . . . . . . . . . 30 8.1 The identity's status Statement . . . . . . . . . . . . . . 30 8.2 The identity' description Statement . . . . . . . . . . . . 30 9. The class Statement . . . . . . . . . . . . . . . . . . . . 31 9.1 The class' attribute Statement . . . . . . . . . . . . . . . 31 9.1.1 The attribute's typemap Statement . . . . . . . . . . . . . 31 Strauss, et. al. Expires May 11, 2001 [Page 2] Internet-Draft SMIng November 2000 9.1.2 The attribute's access Statement . . . . . . . . . . . . . . 31 9.1.3 The attribute's default Statement . . . . . . . . . . . . . 31 9.1.4 The attribute's format Statement . . . . . . . . . . . . . . 32 9.1.5 The attribute's units Statement . . . . . . . . . . . . . . 32 9.1.6 The attribute's status Statement . . . . . . . . . . . . . . 32 9.1.7 The attribute's description Statement . . . . . . . . . . . 33 9.1.8 Usage Example . . . . . . . . . . . . . . . . . . . . . . . 33 9.2 The class' event Statement . . . . . . . . . . . . . . . . . 34 9.2.1 The event's status Statement . . . . . . . . . . . . . . . . 34 9.2.2 The event's description Statement . . . . . . . . . . . . . 34 9.2.3 Usage Example . . . . . . . . . . . . . . . . . . . . . . . 34 9.3 The class' status Statement . . . . . . . . . . . . . . . . 35 9.4 The class' description Statement . . . . . . . . . . . . . . 35 10. Extending a Module . . . . . . . . . . . . . . . . . . . . . 36 11. SMIng Language Extensibility . . . . . . . . . . . . . . . . 38 12. Security Considerations . . . . . . . . . . . . . . . . . . 40 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 References . . . . . . . . . . . . . . . . . . . . . . . . . 42 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 43 A. The SMIng ABNF grammar . . . . . . . . . . . . . . . . . . . 44 B. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Strauss, et. al. Expires May 11, 2001 [Page 3] Internet-Draft SMIng November 2000 1. Introduction In traditional management systems management information is viewed as a collection of managed objects, residing in a virtual information store, termed the Management Information Base (MIB). Collections of related objects are defined in MIB modules. These modules are written conforming to a specification language, the Structure of Management Information (SMI). There are different versions of the SMI. SMIv1 [8], [9], [10] and SMIv2 [4], [5], [6] are based on adapted subsets of OSI's Abstract Syntax Notation One, ASN.1 [12]. In a similar fashion policy provisioning information is viewed as a collection of Provisioning Classes (PRCs) and Provisioning Instances (PRIs) residing in a virtual information store, termed the Policy Information Base (PIB). Collections of related Provisioning Classes are defined in PIB modules. PIB modules are written using the Structure of Policy Provisioning Information (SPPI) [7] which is an adapted subset of SNMP's SMIv2. It is the purpose of this document to define a common object-oriented language, named SMIng, that allows to formally specify data models in a way independent of targeted protocols and applications. Companion documents contain o core modules that supply common SMIng definitions [1], o a SMIng language extension to define SNMP specific mappings of SMIng definition in way compatible to SMIv2 MIBs [2], and o a SMIng language extension to define COPS-PR specific mappings of SMIng definition in a way compatible to SPPI PIBs. Section 2 gives an overview of the basic concepts of the information model while the subsequent sections present the concepts of the SMIng language in detail: the base types, the SMIng file structure, and all SMIng core statements. The remainder of the document describes extensibility features of the language and rules to follow when changes are applied to a module. Appendix A contains the grammar of SMIng in ABNF [11] notation. 1.1 Terminology There are many specific terms in the areas of network and policy based management with some redundancy and ambiguity. Appendix B presents a glossary of terms used throughout this document and in related SMIng documents. Strauss, et. al. Expires May 11, 2001 [Page 4] Internet-Draft SMIng November 2000 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [3]. Strauss, et. al. Expires May 11, 2001 [Page 5] Internet-Draft SMIng November 2000 2. The Information Model SMIng is a language designed to specify management information in a structured way readable to computer programs, e.g. MIB compilers, as well as to human readers. Management information is modeled in classes in an object-oriented manner. Classes can be defined from scratch or by inheritance from a parent class. Multiple inheritence is not possible. The concept of classes is described in Section 9. Each class has a number of attributes. Each attribute represents an atomic piece of information of a base type or a sub-type of a base type. The concept of class attributes is described in Section 9.1. The base types of SMIng include signed and unsigned integers, octet strings, enumeration types, bitset types, and pointers. Pointers are references to classes or attributes or arbitrary identities. The SMIng type system is described in Section 3. Related class and type definitions are defined in modules. A module may refer to definitions from other modules by importing identifiers from those modules. Each module may serve one or multiple purposes: o the definition of management classes, o the definition of events, o the definition of derived types, o the definition of arbitrary untyped identities serving as values of pointers, o the definition of SMIng extensions to allow the local module or other modules to specify information beyond the scope of the base SMIng in a machine readable notation. Some extensions for the application of SMIng in the SNMP framework are defined in [2], o the definition of information beyond the scope of the base SMIng statements, based on locally defined or imported SMIng extensions. Each module is identified by an upper-case identifier. The names of all standard modules must be unique (but different versions of the same module should have the same name). Developers of enterprise modules are encouraged to choose names for their modules that will have a low probability of colliding with standard or other enterprise modules, e.g. by using the enterprise or organization name as a prefix. Strauss, et. al. Expires May 11, 2001 [Page 6] Internet-Draft SMIng November 2000 2.1 Identifiers Identifiers are used to identify different kinds of SMIng items by name. These names are valid in a namespace which is dependent on each SMIng item. Those items are o modules (Section 5), whose namespace is the global range of all SMIng definitions, o classes (Section 9), whose namespace is the local module where the class is defined, o class attributes (Section 9.1), whose namespace is the class where the attribute is defined and all inherited classes, o derived data types (Section 7), whose namespace is the local module where the type is defined, o elements of enumeration and bitset types (Section 3.10, Section 3.11), whose namespace is the related type definition construct and all constructs using that type, o extension statements (Section 6), whose namespace is the local module where the extension is defined. Each identifier starts with an upper-case or lower-case character, dependent on the kind of SMIng item, followed by zero or more letters, digits [XXX and hyphens]. For all identifiers of a single kind of item defined in a namespace, the identifier MUST be unique and SHOULD NOT only differ in case. Identifiers MUST NOT exceed 64 characters in length. Furthermore, the set of all identifiers defined in all modules of a single standardization body or organization SHOULD be unique and mnemonic. This promotes a common language for humans to use when discussing a module. To reference an item that is defined in the local module, its definition MUST sequentially precede the reference. Thus, there MUST NOT be any forward references. To reference an item, that is defined in an external module it MUST be imported into the local module's namespace (Section 5.1). Identifiers that are neither defined nor imported MUST NOT be visible in the local module. On the other hand, all items defined in a module are implicitly exported. [XXX Maybe, we will introduce an explicit export mechanism.] Note when identifiers from external modules are referenced, there is Strauss, et. al. Expires May 11, 2001 [Page 7] Internet-Draft SMIng November 2000 the possibility of name collisions. As such, if different items with the same identifier are imported or if imported identifiers collide with identifiers of locally defined items, then this ambiguity is resolved by prefixing those identifiers with the names of their modules and the namespace operator `::', i.e. `Module::item'. Of course, this notation can be used to refer to identifiers even when there is no name collision. Note that SMIng core language keywords MUST NOT be imported. All keywords of the SMIng language are statements or base types. See the `...Keyword' rules of the SMIng ABNF grammar in Appendix A for a list of those keywords. [XXX remove this paragraph: Finally, by convention, if the identifier refers to an attribute with a counter type (Counter32 or Counter64, derived from Unsigned32 and Unsigned64) then the identifier used for the attribute SHOULD denote plurality.] Strauss, et. al. Expires May 11, 2001 [Page 8] Internet-Draft SMIng November 2000 3. Base Types and Derived Types SMIng has a minimal but complete set of base types, similar to those of many programming languages, but with some differences due to special requirements from the management information model. Additional types may be defined, derived from those base types and even from other derived types. Derived types may use subtyping to formally restrict the possible values. A set of commonly used derived types is defined in the SMIng standard module IRTF-NMRG-SMING-TYPES[1]. Note that types can also be restricted "inline" in attribute definitions (Section 9.1). The different base types and their derived types allow different kinds of subtyping, namely size restrictions and range restrictions. See the following sections on base types (Section 3.1 through Section 3.11) for details. 3.1 OctetString The OctetString base type represents arbitrary binary or textual data. Although SMIng has a theoretical size limitation of 2^32-1 (4294967295) octets for this base type, module designers should realize that there may be implementation and interoperability limitations for sizes in excess of 255 octets. Values of octet strings may be denoted as textual data enclosed in double quotes or as arbitrary binary data denoted as a `0x'-prefixed hexadecimal value of arbitrary but even length, where each pair of hexadecimal digits represents a single octet. Letters in hexadecimal values MAY be upper-case but lower-case characters are RECOMMENDED. [XXX hex-digit letters MUST be upper-case. Apply this change in the whole document.] [XXX allow or forbid ``0x'' with zero hex digits? Apply this change in the whole document.] Textual data may contain any number (possibly zero) of any 7-bit displayable ASCII characters except double quote `"', including tab characters, spaces and line terminator characters (nl or cr & nl). [XXX allow double-quotes.] [XXX be more precise on line terminator characters.] Textual data may span multiple lines, where each subsequent line prefix containing only white space up to the column where the first line's data starts SHOULD be skipped by parsers for a better text formatting. When defining a type derived (directly or indirectly) from the OctetString base type, the size in octets may be restricted by appending a list of size ranges or explicit size values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A Strauss, et. al. Expires May 11, 2001 [Page 9] Internet-Draft SMIng November 2000 size range consists of a lower bound, two consecutive dots `..' and an upper bound. Each value can be given in decimal or `0x'-prefixed hexadecimal notation. Size restricting values MUST NOT be negative. If multiple values or ranges are given, they all MUST be disjunct and SHOULD [XXX MUST] be in ascending order. If a size restriction is applied to an already size restricted octet string the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit size values or ranges, or splitting ranges into multiple ranges with intermediate gaps. Value Examples: "This is a multiline textual data example." // legal "This is "illegally" quoted." // illegal quotes [XXX] "But this is 'ok'." // legal apostrophe quoting "" // legal zero length 0x123 // illegal odd hex length 0x534d496e670a // legal octet string Restriction Examples: OctetString (0 | 4..255) // legal size spec OctetString (4) // legal exact size OctetString (-1 | 1) // illegal negative size OctetString (1 | 1..10) // illegal overlapping 3.2 Pointer The Pointer base type represents an arbitrary reference to a class, an attribute, or a simple untyped identity. Values of pointers are denoted as identifiers of classes, attributes, and identities. Pointer derived types cannot syntactically be restricted in any way. Value Examples: null // legal identity name ifIndex // legal attribute name IF-MIB::ifIndex // legel fully quallified attribute name 3.3 Integer32 The Integer32 base type represents integer values between -2^31 (-2147483648) and 2^31-1 (2147483647). Strauss, et. al. Expires May 11, 2001 [Page 10] Internet-Draft SMIng November 2000 Values of type Integer32 may be denoted as decimal or hexadecimal numbers, where only decimal numbers can be negative. Other decimal numbers than zero MUST NOT have leading zero digits. Hexadecimal numbers are prefixed by `0x' and MUST have an even number of hexadecimal digits, where letters MAY be upper-case but lower-case characters are RECOMMENDED. When defining a type derived (directly or indirectly) from the Integer32 base type, the set of possible values may be restricted by appending a list of ranges or explicit values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A range consists of a lower bound, two consecutive dots `..' and an upper bound. Each value can be given in decimal or `0x'-prefixed hexadecimal notation. If multiple values or ranges are given they all MUST be disjunct and SHOULD be in ascending order. If a value restriction is applied to an already restricted type the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. Value Examples: 015 // illegal leading zero -123 // legal negative value - 1 // illegal intermediate space 0xabc // illegal hexadecimal value length -0xff // illegal sign on hex value 0x80000000 // illegal value, too large 0xf00f // legal hexadecimal value Restriction Examples: Integer32 (0 | 5..10) // legal range spec Integer32 (4..8 | 5..10) // illegal overlapping 3.4 Integer64 The Integer64 base type represents integer values between -2^63 (-9223372036854775808) and 2^63-1 (9223372036854775807). Values of type Integer64 may be denoted as decimal or hexadecimal numbers, where only decimal numbers can be negative. Other decimal numbers than zero MUST NOT have leading zero digits. Hexadecimal numbers are prefixed by `0x' and MUST have an even number of hexadecimal digits, where letters MAY be upper-case but lower-case characters are RECOMMENDED. When defining a type derived (directly or indirectly) from the Strauss, et. al. Expires May 11, 2001 [Page 11] Internet-Draft SMIng November 2000 Integer64 base type, the set of possible values may be restricted by appending a list of ranges or explicit values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A range consists of a lower bound, two consecutive dots `..' and an upper bound. Each value can be given in decimal or `0x'-prefixed hexadecimal notation. If multiple values or ranges are given they all MUST be disjunct and SHOULD be in ascending order. If a value restriction is applied to an already restricted type the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. Value Examples: 015 // illegal leading zero -123 // legal negative value - 1 // illegal intermediate space 0xabc // illegal hexadecimal value length -0xff // illegal sign on hex value 0x80000000 // legal value Restriction Examples: Integer64 (0 | 5..10) // legal range spec Integer64 (4..8 | 5..10) // illegal overlapping 3.5 Unsigned32 The Unsigned32 base type represents positive integer values between 0 and 2^32-1 (4294967295). Values of type Unsigned32 may be denoted as decimal or hexadecimal numbers. Other decimal numbers than zero MUST NOT have leading zero digits. Hexadecimal numbers are prefixed by `0x' and MUST have an even number of hexadecimal digits, where letters MAY be upper-case but lower-case characters are RECOMMENDED. When defining a type derived (directly or indirectly) from the Unsigned32 base type, the set of possible values may be restricted by appending a list of ranges or explicit values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A range consists of a lower bound, two consecutive dots `..' and an upper bound. Each value can be given in decimal or `0x'-prefixed hexadecimal notation. If multiple values or ranges are given they all MUST be disjunct and SHOULD be in ascending order. If a value restriction is applied to an already restricted type the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or Strauss, et. al. Expires May 11, 2001 [Page 12] Internet-Draft SMIng November 2000 ranges, or splitting ranges into multiple ranges with intermediate gaps. Value Examples: 015 // illegal leading zero -123 // illegal negative value 0xabc // illegal hexadecimal value length 0x80000000 // legal hexadecimal value 0x8080000000 // illegal value, too large]]> Restriction Examples: Unsigned32 (0 | 5..10) // legal range spec Unsigned32 (4..8 | 5..10) // illegal overlapping 3.6 Unsigned64 The Unsigned64 base type represents positive integer values between 0 and 2^64-1 (18446744073709551615). Values of type Unsigned64 may be denoted as decimal or hexadecimal numbers. Other decimal numbers than zero MUST NOT have leading zero digits. Hexadecimal numbers are prefixed by `0x' and MUST have an even number of hexadecimal digits, where letters MAY be upper-case but lower-case characters are RECOMMENDED. When defining a type derived (directly or indirectly) from the Unsigned64 base type, the set of possible values may be restricted by appending a list of ranges or explicit values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A range consists of a lower bound, two consecutive dots `..' and an upper bound. Each value can be given in decimal or `0x'-prefixed hexadecimal notation. If multiple values or ranges are given they all MUST be disjunct and SHOULD be in ascending order. If a value restriction is applied to an already restricted type the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. Value Examples: 015 // illegal leading zero -123 // illegal negative value 0xabc // illegal hexadecimal value length 0x8080000000 // legal hexadecimal value Restriction Examples: Strauss, et. al. Expires May 11, 2001 [Page 13] Internet-Draft SMIng November 2000 Unsigned64 (1..10000000000) // legal range spec 3.7 Float32 The Float32 base type represents floating point values of single precision as described by [14]. Values of type Float32 may be denoted as a decimal fraction with an optional exponent as known from many programming languages. See the grammar rule `floatValue' of Appendix A for the detailed syntax. Special values are `snan' (signaling Not-a-Number), `qnan' (quiet Not-a-Number), `neginf' (negative infinity), and `posinf' (positive infinity). Note that -0.0 and +0.0 are different floating point values. 0.0 is equal to +0.0. When defining a type derived (directly or indirectly) from the Float32 base type, the set of possible values may be restricted by appending a list of ranges or explicit values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A range consists of a lower bound, two consecutive dots `..' and an upper bound. If multiple values or ranges are given they all MUST be disjunct and SHOULD be in ascending order. If a value restriction is applied to an already restricted type the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. The special values `snan', `qnan', `neginf', and `posinf' must be explicitly listed in restrictions if they shall be included, where `snan' and `qnan' cannot be used in ranges. Note that encoding is not subject to this specification. It has to be described by protocols that transport objects of type Float32. Note also that most floating point encodings disallow the representation of many values that can be written as decimal fractions as used in SMIng for human readability. Therefore, explicit values in floating point type restrictions should be handled with care. Value Examples: 00.1 // illegal leading zero 3.1415 // legal value -2.5E+3 // legal negative exponential value Restriction Examples: Float32 (-1.0..1.0) // legal range spec Float32 (1 | 3.3 | 5) // legal, probably unrepresentable 3.3 Float32 (-10.0..10.0 | 0) // illegal overlapping Strauss, et. al. Expires May 11, 2001 [Page 14] Internet-Draft SMIng November 2000 3.8 Float64 The Float64 base type represents floating point values of single precision as described by [14]. Values of type Float64 may be denoted as a decimal fraction with an optional exponent as known from many programming languages. See the grammar rule `floatValue' of Appendix A for the detailed syntax. Special values are `snan' (signaling Not-a-Number), `qnan' (quiet Not-a-Number), `neginf' (negative infinity), and `posinf' (positive infinity). Note that -0.0 and +0.0 are different floating point values. 0.0 is equal to +0.0. When defining a type derived (directly or indirectly) from the Float64 base type, the set of possible values may be restricted by appending a list of ranges or explicit values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A range consists of a lower bound, two consecutive dots `..' and an upper bound. If multiple values or ranges are given they all MUST be disjunct and SHOULD be in ascending order. If a value restriction is applied to an already restricted type the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. The special values `snan', `qnan', `neginf', and `posinf' must be explicitly listed in restrictions if they shall be included, where `snan' and `qnan' cannot be used in ranges. Note that encoding is not subject to this specification. It has to be described by protocols that transport objects of type Float64. Note also that most floating point encodings disallow the representation of many values that can be written as decimal fractions as used in SMIng for human readability. Therefore, explicit values in floating point type restrictions should be handled with care. Value Examples: 00.1 // illegal leading zero 3.1415 // legal value -2.5E+3 // legal negative exponential value Restriction Examples: Float64 (-1.0..1.0) // legal range spec Float64 (1 | 3.3 | 5) // legal, probably unrepresentable 3.3 Float64 (-10.0..10.0 | 0) // illegal overlapping Strauss, et. al. Expires May 11, 2001 [Page 15] Internet-Draft SMIng November 2000 3.9 Float128 The Float128 base type represents floating point values of single precision as described by [14]. Values of type Float128 may be denoted as a decimal fraction with an optional exponent as known from many programming languages. See the grammar rule `floatValue' of Appendix A for the detailed syntax. Special values are `snan' (signaling Not-a-Number), `qnan' (quiet Not-a-Number), `neginf' (negative infinity), and `posinf' (positive infinity). Note that -0.0 and +0.0 are different floating point values. 0.0 is equal to +0.0. When defining a type derived (directly or indirectly) from the Float128 base type, the set of possible values may be restricted by appending a list of ranges or explicit values, separated by pipe `|' characters and the whole list enclosed in parenthesis. A range consists of a lower bound, two consecutive dots `..' and an upper bound. If multiple values or ranges are given they all MUST be disjunct and SHOULD be in ascending order. If a value restriction is applied to an already restricted type the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. The special values `snan', `qnan', `neginf', and `posinf' must be explicitly listed in restrictions if they shall be included, where `snan' and `qnan' cannot be used in ranges. Note that encoding is not subject to this specification. It has to be described by protocols that transport objects of type Float128. Note also that most floating point encodings disallow the representation of many values that can be written as decimal fractions as used in SMIng for human readability. Therefore, explicit values in floating point type restrictions should be handled with care. Value Examples: 00.1 // illegal leading zero 3.1415 // legal value -2.5E+3 // legal negative exponential value Restriction Examples: Float128 (-1.0..1.0) // legal range spec Float128 (1 | 3.3 | 5) // legal, probably unrepresentable 3.3 Float128 (-10.0..10.0 | 0) // illegal overlapping Strauss, et. al. Expires May 11, 2001 [Page 16] Internet-Draft SMIng November 2000 3.10 Enumeration The Enumeration base type represents values from a set of integers in the range between -2^31 (-2147483648) and 2^31-1 (2147483647), where each value has an assigned name. The list of those named numbers has to be comma-separated, enclosed in parenthesis and appended to the `Enumeration' keyword. Each named number is denoted by its lower-case identifier followed by the assigned integer value, denoted as a decimal or `0x'-prefixed hexadecimal number, enclosed in parenthesis. Every name and every number in an enumeration type MUST be unique. It is RECOMMENDED that values are positive and start at 1 and be numbered contiguously. Values of enumeration types may be denoted as decimal or `0x'-prefixed hexadecimal numbers or preferably as their assigned names. When defining a type derived (directly or indirectly) from an enumeration type, the set of named numbers may be equal or restricted by removing one or more named numbers. But no named numbers may be added or changed regarding its name, value, or both. Type and Value Examples: Enumeration (up(1), down(2), testing(3)) 0 // illegal, value 0 out of range up // legal value given by name 2 // legal value given by number 3.11 Bits The Bits base type represents bit sets. That is, a Bits value is a set of flags identified by small integer numbers starting at 0. Each bit number has an assigned name. The list of those named numbers has to be comma-separated, enclosed in parenthesis and appended to the `Bits' keyword. Each named number is denoted by its lower-case identifier followed by the assigned integer value, denoted as a decimal or `0x'-prefixed hexadecimal number, enclosed in parenthesis. Every name and every number in a bits type MUST be unique. It is RECOMMENDED that numbers start at 0 and be numbered contiguously. Negative numbers are forbidden. Values of bits types may be denoted as a comma-separated list of decimal or `0x'-prefixed hexadecimal numbers or preferably their assigned names enclosed in parenthesis. There MUST NOT be any element (by name or number) listed more than once. It is RECOMMENDED to list elements in ascending order, although the order is semantically irrelevant. Strauss, et. al. Expires May 11, 2001 [Page 17] Internet-Draft SMIng November 2000 When defining a type derived (directly or indirectly) from a bits type, the set of named numbers may be restricted by removing one or more named numbers. But no named numbers may be added or changed regarding its name, value, or both. Type and Value Examples: Bits (readable(0), writeable(1), executable(2)) () // legal empty value (readable, writeable, 2) // legal value (0, readable, executable) // illegal, readable(0) appears twice (writeable, 4) // illegal, element 4 out of range 3.12 Display Formats Attribute definitions and type definitions allow the specification of a format to be used, when a value of that attribute or an attribute of that type is displayed. Format specifications are represented as textual data. When the attribute or type has an underlying base type of Integer32, Integer64, Unsigned32, or Unsigned64, the format consists of an integer-format specification, containing two parts. The first part is a single character suggesting a display format, either: `x' for hexadecimal, or `d' for decimal, or `o' for octal, or `b' for binary. For all types, when rendering the value, leading zeros are omitted, and for negative values, a minus sign is rendered immediately before the digits. The second part is always omitted for `x', `o' and `b', and need not be present for `d'. If present, the second part starts with a hyphen and is followed by a decimal number, which defines the implied decimal point when rendering the value. For example `d-2' suggests that a value of 1234 be rendered as `12.34'. When the attribute or type has an underlying base type of OctetString, the format consists of one or more octet-format specifications. Each specification consists of five parts, with each part using and removing zero or more of the next octets from the value and producing the next zero or more characters to be displayed. The octets within the value are processed in order of significance, most significant first. The five parts of a octet-format specification are: 1. the (optional) repeat indicator; if present, this part is a `*', and indicates that the current octet of the value is to be used as the repeat count. The repeat count is an unsigned integer (which may be zero) which specifies how many times the remainder Strauss, et. al. Expires May 11, 2001 [Page 18] Internet-Draft SMIng November 2000 of this octet-format specification should be successively applied. If the repeat indicator is not present, the repeat count is one. 2. the octet length: one or more decimal digits specifying the number of octets of the value to be used and formatted by this octet-specification. Note that the octet length can be zero. If less than this number of octets remain in the value, then the lesser number of octets are used. 3. the display format, either: `x' for hexadecimal, `d' for decimal, `o' for octal, `a' for ASCII, or `t' for UTF-8 [15]. If the octet length part is greater than one, and the display format part refers to a numeric format, then network byte-ordering (big-endian encoding) is used interpreting the octets in the value. The octets processed by the `t' display format do not necessarily form an integral number of UTF-8 characters. Trailing octets which do not form a valid UTF-8 encoded character are discarded. 4. the (optional) display separator character; if present, this part is a single character which is produced for display after each application of this octet-specification; however, this character is not produced for display if it would be immediately followed by the display of the repeat terminator character for this octet specification. This character can be any character other than a decimal digit and a `*'. 5. the (optional) repeat terminator character, which can be present only if the display separator character is present and this octet specification begins with a repeat indicator; if present, this part is a single character which is produced after all the zero or more repeated applications (as given by the repeat count) of this octet specification. This character can be any character other than a decimal digit and a `*'. Output of a display separator character or a repeat terminator character is suppressed if it would occur as the last character of the display. If the octets of the value are exhausted before all the octet format specification have been used, then the excess specifications are ignored. If additional octets remain in the value after interpreting all the octet format specifications, then the last octet format specification is re-interpreted to process the additional octets, until no octets remain in the value. Note that for some types no format specifications are defined and SHOULD be omitted. Implementations MUST ignore format specifications Strauss, et. al. Expires May 11, 2001 [Page 19] Internet-Draft SMIng November 2000 they cannot interpret. Also note that the SMIng grammar (Appendix A) does not specify the syntax of format specifications. Display Format Examples: Base Type Format Example Value Rendered Value ----------- ------------------- ---------------- ----------------- OctetString 255a "Hello World." Hello World. OctetString 1x: "Hello!" 48:65:6c:6c:6f:21 OctetString 1d:1d:1d.1d,1a1d:1d 0x0d1e0f002d0400 13:30:15.0,-4:0 OctetString 1d.1d.1d.1d/2d 0x0a0000010400 10.0.0.1/1024 OctetString *1x:/1x: 0x02aabbccddee aa:bb/cc:dd:ee Integer32 d-2 1234 12.34 Strauss, et. al. Expires May 11, 2001 [Page 20] Internet-Draft SMIng November 2000 4. The SMIng File Structure The topmost container of SMIng information is a file. An SMIng file may contain zero, one or more modules. It is RECOMMENDED to separate modules into files named by their modules, where possible. Though, for dedicated purposes it may be reasonable to collect several modules in a single file. The top level SMIng construct is the `module' statement (Section 5) that defines a single SMIng module. A module contains a sequence of sections in an obligatory order with different kinds of definitions. Whether these sections contain statements or remain empty mainly depends on the purpose of the module. 4.1 Comments Comments can be included at any position in an SMIng file, except in between the characters of a single token like those of a quoted strings. However, it is RECOMMENDED that all substantive descriptions be placed within an appropriate description clause, so that the information is available to SMIng parsers. Comments commence with a pair of adjacent slashes `//' and end at the end of the line. 4.2 Statements and Arguments SMIng has a very small set of basic grammar rules based on the concept of statements. Each statement starts with a lower-case keyword identifying the statement followed by a number (possibly zero) of arguments. An argument may be quoted text, an identifier, a value of any base type, a list of identifiers enclosed in parenthesis `( )' or a statement block enclosed in curly braces `{ }'. Since statement blocks are valid arguments, it is possible to nest statement sequences. Each statement is terminated by a semicolon `;'. The core set of statements may be extended using the SMIng `extension' statement. See Section 6 and Section 11 for details. At places where a statement is expected, but an unknown lower-case word is read, those statements MUST be skipped up to the proper semicolon, including nested statement blocks. Strauss, et. al. Expires May 11, 2001 [Page 21] Internet-Draft SMIng November 2000 5. The module Statement The `module' statement is used as a container of all definitions of a single SMIng module. It gets two arguments: an upper-case module name and a statement block that contains mandatory and optional statements and sections of statements in an obligatory order: module { }; The optional `import' statements are followed by the mandatory `organization', `contact', and `description' statements, which in turn are followed by the mandatory `revision' statements. This part defines the module's meta information while the following sections contain its main definitions. See the `moduleStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `module' statement. 5.1 The module's import Statement The optional module's `import' statement is used to import identifiers from external modules into the local module's namespace. It gets two arguments: the name of the external module and a comma-separated list of one or more identifiers to be imported enclosed in parenthesis. Multiple `import' statements for the same module but with disjunct lists of identifiers are allowed, though NOT RECOMMENDED. Anyhow, the same identifier from the same module MUST NOT be imported multiple times. To import identifiers with the same name from different modules might be necessary and is allowed. To distinguish them in the local module, they have to be referred by qualified names. It is NOT RECOMMENDED to import identifiers not used in the local module. Strauss, et. al. Expires May 11, 2001 [Page 22] Internet-Draft SMIng November 2000 See the `importStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `import' statement. 5.2 The module's organization Statement The module's `organization' statement, which must be present, gets one argument which is used to specify a textual description of the organization(s) under whose auspices this module was developed. 5.3 The module's contact Statement The module's `contact' statement, which must be present, gets one argument which is used to specify the name, postal address, telephone number, and electronic mail address of the person to whom technical queries concerning this revision of this module should be sent. 5.4 The module's description Statement The module's `description' statement, which must be present, gets one argument which is used to specify a high-level textual description of the contents of this module. 5.5 The module's revision Statement The module's `revision' statement is repeatedly used to specify the editorial revisions of the module, including the initial revision. It gets one argument which is a statement block that holds detailed information in an obligatory order. A module MUST have at least one initial `revision' statement. For every editorial change, a new one MUST be added in front of the revisions sequence, so that all revisions are in reverse chronological order. See the `revisionStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `revision' statement. 5.5.1 The revision's date Statement The revision's `date' statement, which must be present, gets one argument which is used to specify the date and time of the revision in the format `YYYY-MM-DD HH:MM' or `YYYY-MM-DD' which implies the time `00:00'. The time is always given in UTC. See the `date' rule of the SMIng grammar (Appendix A) for the formal syntax of the revision's `date' statement. 5.5.2 The revision's description Statement The revision's `description' statement, which must be present, gets Strauss, et. al. Expires May 11, 2001 [Page 23] Internet-Draft SMIng November 2000 one argument which is used to specify a high-level textual description of the revision. 5.6 Usage Example Consider how a skeletal module might be constructed: e.g., module FIZBIN { import IRTF-NMRG-SMING-TYPES (DisplayString); organization "IRTF Network Management Research Group (NMRG)"; contact " Frank Strauss Postal: TU Braunschweig Bueltenweg 74/75 38106 Braunschweig DE Phone: +49 531 391-3266 EMail: strauss@ibr.cs.tu-bs.de"; description "The module for entities implementing the xxxx protocol."; revision { date "2000-11-02"; description "Initial revision."; }; // ... further definitions ... }; // end of module FIZBIN. Strauss, et. al. Expires May 11, 2001 [Page 24] Internet-Draft SMIng November 2000 6. The extension Statement The `extension' statement is used to define new statements to be used in the local module following this extension statement definition or in external modules that may import this extension statement definition. The `extension' statement gets two arguments: a lower-case extension statement identifier and a statement block that holds detailed extension information in an obligatory order. Extension statement identifiers SHOULD NOT contain any upper-case characters or hyphens. Note that the SMIng extension feature does not allow to formally specify the context, argument syntax and semantics of an extension. Its only purpose is to declare the existence of an extension and to allow a unique reference to an extension. See Section 11 for detailed information on extensions and [2] for mappings of SMIng definitions to SNMP which is formally defined as an extension. See the `extensionStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `extension' statement. 6.1 The extension's status Statement The extension's `status' statement, which need not be present, gets one argument which is used to specify whether this extension definition is current or historic. The value `current' means that the definition is current and valid. The value `obsolete' means the definition is obsolete and should not be implemented and/or can be removed if previously implemented. While the value `deprecated' also indicates an obsolete definition, it permits new/continued implementation in order to foster interoperability with older/existing implementations. If the `status' statement is omitted, the status value `current' is implied. 6.2 The extension's description Statement The extension's `description' statement, which must be present, gets one argument which is used to specify a high-level textual description of the extension statement. It is RECOMMENDED to include information on the extension's context, its semantics, and implementation conditions. See also Section 11. 6.3 The extension's abnf Statement The extension's `abnf' statement, which need not be present, gets Strauss, et. al. Expires May 11, 2001 [Page 25] Internet-Draft SMIng November 2000 one argument which is used to specify a formal ABNF [11] grammar definition of the extension. Note that the `abnf' statement should contain only pure ABNF and no additional text, though comments prefixed by semicolon are allowed but should probably be moved to the description statement. [XXX Note also that double quotes are not allowed inside textual descriptions which are itself enclosed in double quotes. So they have to be replaced by single quotes.] Strauss, et. al. Expires May 11, 2001 [Page 26] Internet-Draft SMIng November 2000 7. The typedef Statement The `typedef' statement is used to define new data types to be used in the local module or in external modules. It gets two arguments: an upper-case type identifier and a statement block that holds detailed type information in an obligatory order. Type identifiers SHOULD NOT consist of all upper-case characters and SHOULD NOT contain hyphens. See the `typedefStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `typedef' statement. 7.1 The typedef's type Statement The typedef's `type' statement, which must be present, gets one argument which is used to specify the type from which this type is derived. Optionally, type restrictions may be applied to the new type by appending subtyping information according to the rules of the base type. See Section 3 for SMIng base types and their type restrictions. 7.2 The typedef's default Statement The typedef's `default' statement, which need not be present, gets one argument which is used to specify an acceptable default value for attributes of this type. A default value may be used at the discretion of an agent when an attribute instance is created. That is, the value is a "hint" to implementors. The value of the `default' statement must, of course, correspond to the (probably restricted) type specified in the typedef's `type' statement. The default value of a type may be overwritten by a default value of an attribute of this type. Note that for some types, default values make no sense. 7.3 The typedef's format Statement The typedef's `format' statement, which need not be present, gets one argument which is used to give a hint as to how the value of an instance of an attribute of this type might be displayed. See Section 3.12 for a description of format specifications. If no format is specified, it is inherited from the type given in the `type' statement. On the other hand, the format specification of a type may be overwritten by a format specification of an Strauss, et. al. Expires May 11, 2001 [Page 27] Internet-Draft SMIng November 2000 attribute of this type. 7.4 The typedef's units Statement The typedef's `units' statement, which need not be present, gets one argument which is used to specify a textual definition of the units associated with attributes of this type. If no units are specified, they are inherited from the type given in the `type' statement. On the other hand, the units specification of a type may be overwritten by a units specification of an attribute of this type. The units specification has to be appropriate for values displayed according to the typedef's format specification, if present. E.g., if the type defines frequency values of type Unsigned64 measured in thousands of Hertz, the format specification should be `d-3' and the units specification should be `Hertz' or `Hz'. If the format specification would be omitted, the units specification should be `Milli-Hertz' or `mHz'. Authors of SMIng modules should pay attention to keep format and units specifications of type and attribute definitions synced. Application implementors MUST NOT implement units specifications without implementing format specifications. 7.5 The typedef's status Statement The typedef's `status' statement, which need not be present, gets one argument which is used to specify whether this type definition is current or historic. The value `current' means that the definition is current and valid. The value `obsolete' means the definition is obsolete and should not be implemented and/or can be removed if previously implemented. While the value `deprecated' also indicates an obsolete definition, it permits new/continued implementation in order to foster interoperability with older/existing implementations. Derived types SHOULD NOT be defined as `current' if their underlying type is `deprecated' or `obsolete'. Similarly, they SHOULD NOT be defined as `deprecated' if their underlying type is `obsolete'. Nevertheless, subsequent revisions of the underlying type cannot be avoided, but SHOULD be taken into account in subsequent revisions of the local module. If the `status' statement is omitted, the status value `current' is implied. Strauss, et. al. Expires May 11, 2001 [Page 28] Internet-Draft SMIng November 2000 7.6 The typedef's description Statement The typedef's `description' statement, which must be present, gets one argument which is used to specify a high-level textual description of the newly defined type. It is RECOMMENDED to include all semantic definitions necessary for implementation, and to embody any information which would otherwise be communicated in any commentary annotations associated with this type definition. 7.7 Usage Examples typedef RptrOperStatus { type Enumeration (other(1), ok(2), rptrFailure(3), groupFailure(4), portFailure(5), generalFailure(6)); default other; // undefined by default. status deprecated; description "A type to indicate the operational state of a repeater."; }; typedef DateAndTime { type OctetString (8 | 11); format "2d-1d-1d,1d:1d:1d.1d,1a1d:1d"; status current; // could be omitted description "A date-time specification. ... Note that if only local time is known, then timezone information (fields 8-10) is not present."; }; typedef Frequency { type Unsigned64; format "d-3" units "Hertz"; description "A wide-range frequency specification measured in thousands of Hertz."; }; Strauss, et. al. Expires May 11, 2001 [Page 29] Internet-Draft SMIng November 2000 8. The identity Statement The `identity' statement is used to define a new identity either from scratch or derived from a parent identity. The `identity' statement gets the following two or four arguments: The first argument is an upper-case identity identifier and the last argument is a statement block that holds detailed identity information in an obligatory order. In case of derived identities there are two tokens inbetween: a single colon `:' and the identifier of the parent identity. See the `identityStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `identity' statement. 8.1 The identity's status Statement The identity's `status' statement, which need not be present, gets one argument which is used to specify whether this identity definition is current or historic. The value `current' means that the definition is current and valid. The value `obsolete' means the definition is obsolete and should not be implemented and/or can be removed if previously implemented. While the value `deprecated' also indicates an obsolete definition, it permits new/continued implementation in order to foster interoperability with older/existing implementations. Derived identities SHOULD NOT be defined as `current' if their parent identity is `deprecated' or `obsolete'. Similarly, they SHOULD NOT be defined as `deprecated' if their parent identity is `obsolete'. Nevertheless, subsequent revisions of the parent identity cannot be avoided, but SHOULD be taken into account in subsequent revisions of the local module. If the `status' statement is omitted, the status value `current' is implied. 8.2 The identity' description Statement The identity's `description' statement, which must be present, gets one argument which is used to specify a high-level textual description of the newly defined identity. It is RECOMMENDED to include all semantic definitions necessary for implementation, and to embody any information which would otherwise be communicated in any commentary annotations associated with this identity definition. Strauss, et. al. Expires May 11, 2001 [Page 30] Internet-Draft SMIng November 2000 9. The class Statement The `class' statement is used to define a new class either from scratch or derived from a parent class. The `class' statement gets the following two or four arguments: The first argument is an upper-case class identifier and the last argument is a statement block that holds detailed class information in an obligatory order. In case of derived classes there are two tokens inbetween: a single colon `:' and the identifier of the parent class. See the `classStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `class' statement. 9.1 The class' attribute Statement The class' `attribute' statement, which can be present zero, one or multiple times, gets three arguments: a type or class name, the attribute name, and a statement block that holds detailed attribute information in an obligatory order. 9.1.1 The attribute's typemap Statement [XXX] 9.1.2 The attribute's access Statement The attribute's `access' statement, which must be present, gets one argument which is used to specify whether it makes sense to read and/or write an instance of the attribute, or to include its value in an event. This is the maximal level of access for the attribute. This maximal level of access is independent of any administrative authorization policy. The value `readwrite' indicates that read and write access makes sense. The value `readonly' indicates that read access makes sense, but write access is never possible. [XXX The value `noaccess' indicates an auxiliary object.] The value `eventonly' indicates an object which is accessible only via an event. These values are ordered, from least to greatest access level: [XXX `noaccess',] `notifyonly', `readonly', `readwrite'. 9.1.3 The attribute's default Statement The attribute's `default' statement, which need not be present, gets one argument which is used to specify an acceptable default value for this attribute. A default value may be used at the discretion of an agent when an attribute instance is created. That is, the value is a "hint" to implementors. Strauss, et. al. Expires May 11, 2001 [Page 31] Internet-Draft SMIng November 2000 The value of the `default' statement must, of course, correspond to the (probably restricted) type specified in the attribute's `type' statement. The attribute's default value overrides the default value of the underlying type definition if both are present. [XXX Note that for attributes of some types, default values make no sense, e.g. IRTF-NMRG-SMING-TYPES::Counter32.] 9.1.4 The attribute's format Statement The attribute's `format' statement, which need not be present, gets one argument which is used to give a hint as to how the value of an instance of this attribute might be displayed. See Section 3.12 for a description of format specifications. The attribute's format specification overrides the format specification of the underlying type definition if both are present. 9.1.5 The attribute's units Statement The attribute's `units' statement, which need not be present, gets one argument which is used to specify a textual definition of the units associated with this attribute. The attribute's units specification overrides the units specification of the underlying type definition if both are present. The units specification has to be appropriate for values displayed according to the attribute's format specification if present. E.g., if the attribute represents a frequency value of type Unsigned64 measured in thousands of Hertz, the format specification should be `d-3' and the units specification should be `Hertz' or `Hz'. If the format specification would be omitted the units specification should be `Milli-Hertz' or `mHz'. MIB Authors should pay attention to keep format and units specifications of type and attribute definitions synced. Application implementors MUST NOT implement units specifications without implementing format specifications. 9.1.6 The attribute's status Statement The attribute's `status' statement, which need not be present, gets one argument which is used to specify whether this attribute definition is current or historic. The value `current' means that the definition is current and valid. The value `obsolete' means the definition is obsolete and should not be implemented and/or can be removed if previously implemented. While the value `deprecated' also indicates an obsolete definition, it permits new/continued Strauss, et. al. Expires May 11, 2001 [Page 32] Internet-Draft SMIng November 2000 implementation in order to foster interoperability with older/existing implementations. Attributes SHOULD NOT be defined as `current' if their type or their containing class is `deprecated' or `obsolete'. Similarly, they SHOULD NOT be defined as `deprecated' if their type or their containting class is `obsolete'. Nevertheless, subsequent revisions of used type definition cannot be avoided, but SHOULD be taken into account in subsequent revisions of the local module. If the `status' statement is omitted the status value `current' is implied. 9.1.7 The attribute's description Statement The attribute's `description' statement, which must be present, gets one argument which is used to specify a high-level textual description of this attribute. It is RECOMMENDED to include all semantic definitions necessary for the implementation of this attribute. 9.1.8 Usage Example class Interface { // ... attribute Gauge32 speed { access readonly; units "bps"; description "An estimate of the interface's current bandwidth in bits per second."; }; // ... attribute AdminStatus adminStatus { access readwrite; description "The desired state of the interface."; }; attribute OperStatus operStatus { access readwrite; description "The current operational state of the interface."; }; // ... }; Strauss, et. al. Expires May 11, 2001 [Page 33] Internet-Draft SMIng November 2000 9.2 The class' event Statement The class' `event' statement is used to define an event related to an instance of this class that can occur asynchronously. It gets two arguments: a lower-case event identifier and a statement block that holds detailed information in an obligatory order. See the `eventStatement' rule of the SMIng grammar (Appendix A) for the formal syntax of the `event' statement. 9.2.1 The event's status Statement The event's `status' statement, which need not be present, gets one argument which is used to specify whether this event definition is current or historic. The value `current' means that the definition is current and valid. The value `obsolete' means the definition is obsolete and should not be implemented and/or can be removed if previously implemented. While the value `deprecated' also indicates an obsolete definition, it permits new/continued implementation in order to foster interoperability with older/existing implementations. If the `status' statement is omitted the status value `current' is implied. 9.2.2 The event's description Statement The event's `description' statement, which must be present, gets one argument which is used to specify a high-level textual description of this event. It is RECOMMENDED to include all semantic definitions necessary for the implementation of this event. In particular, it SHOULD be documented which instances of the classes and attributes mentioned in the `attributes' statement should be associated within events of this type. 9.2.3 Usage Example Consider how an event might be described that signals a status change of an interface: Strauss, et. al. Expires May 11, 2001 [Page 34] Internet-Draft SMIng November 2000 class Interface { // ... event linkDown { status current; description "A linkDown event signifies that it has been detected that the ifOperStatus attribute for this interface instance is about to enter the down state from some other state (but not from the notPresent state). This other state is indicated by the included value of ifOperStatus."; }; }; 9.3 The class' status Statement The class' `status' statement, which need not be present, gets one argument which is used to specify whether this class definition is current or historic. The value `current' means that the definition is current and valid. The value `obsolete' means the definition is obsolete and should not be implemented and/or can be removed if previously implemented. While the value `deprecated' also indicates an obsolete definition, it permits new/continued implementation in order to foster interoperability with older/existing implementations. Derived classes SHOULD NOT be defined as `current' if their parent class is `deprecated' or `obsolete'. Similarly, they SHOULD NOT be defined as `deprecated' if their parent class is `obsolete'. Nevertheless, subsequent revisions of the parent class cannot be avoided, but SHOULD be taken into account in subsequent revisions of the local module. If the `status' statement is omitted, the status value `current' is implied. 9.4 The class' description Statement The class' `description' statement, which must be present, gets one argument which is used to specify a high-level textual description of the newly defined class. It is RECOMMENDED to include all semantic definitions necessary for implementation, and to embody any information which would otherwise be communicated in any commentary annotations associated with this class definition. Strauss, et. al. Expires May 11, 2001 [Page 35] Internet-Draft SMIng November 2000 10. Extending a Module As experience is gained with a module, it may be desirable to revise that module. However, changes are not allowed if they have any potential to cause interoperability problems between an implementation using an original specification and an implementation using an updated specification(s). For any change, some statements near the top of the module MUST be updated to include information about the revision: specifically, a new `revision' statement (Section 5.5) must be included in front of the `revision' statements. Furthermore, any necessary changes MUST be applied to other statements, including the `organization' and `contact' statements (Section 5.2, Section 5.3). Note that any definition contained in a module is available to be imported by any other module, and is referenced in an `import' statement via the module name. Thus, a module name MUST NOT be changed. Specifically, the module name (e.g., `FIZBIN' in the example of Section 5.6) MUST NOT be changed when revising a module (except to correct typographical errors), and definitions MUST NOT be moved from one module to another. Also note, that obsolete definitions MUST NOT be removed from modules since their identifiers may still be referenced by other modules, and the object identifiers used to name them MUST never be re-assigned. A definition may be revised in any of the following ways: o In `typedef' and `attribute' statement blocks, a `type' statement containing an `Enumeration' or `Bits' type may have new named numbers added. o In `typedef' statement blocks, the value of a `type' statement may be replaced by another type if the new type is derived (directly or indirectly) from the same base type, has the same set of values, and has identical semantics. o In `attribute' statements where the first argument specifies a class, the class may be replaced by another class if the new class is inherited (directly or indirectly) from the base class. o In `attribute' statements where the first argument specifies a type, the type may be replaced by another type if the new type is derived (directly or indirectly) from the same base type, has the same set of values, and has identical semantics. o In any statement block, a `status' statement value of `current' Strauss, et. al. Expires May 11, 2001 [Page 36] Internet-Draft SMIng November 2000 (or a missing `status' statement) may be revised as `deprecated' or `obsolete'. Similarly, a `status' statement value of `deprecated' may be revised as `obsolete'. When making such a change, the `description' statement SHOULD be updated to explain the rationale. o In `typedef' and `attribute' statement blocks, a `default' statement may be added or updated. o In `typedef' and `attribute' statement blocks, a `units' statement may be added. o A class may be augmented by adding new attributes. o In any statement block, clarifications and additional information may be included in the `description' statement. o Entirely new extensions, types, identities, and classes may be defined, using previously unassigned identifiers. Otherwise, if the semantics of any previous definition are changed (i.e., if a non-editorial change is made to any definition other than those specifically allowed above), then this MUST be achieved by a new definition with a new identifier. In case of a class where the semantics of any attributes are changed, the new class can be defined by inheritence from the old class and overwriting the changed attributes. Note that changing the identifier associated with an existing definition is considered a semantic change, as these strings may be used in an `import' statement. Strauss, et. al. Expires May 11, 2001 [Page 37] Internet-Draft SMIng November 2000 11. SMIng Language Extensibility While the core SMIng language has a well defined set of statements (Section 5 through Section 9.2) that are used to specify those aspects of management information commonly regarded as necessary without management protocol specific information, there may be further information, people wish to express. To describe additional information informally in description statements has the disadvantage, that this information cannot be parsed by any program. SMIng allows modules to include statements that are unknown to a parser but fulfill some core grammar rules (Section 4.2). Furthermore, additional statements may be defined by the `extension' statement (Section 6). Extensions can be used in the local module or in other modules, that import the extension. This has some advantages: o A parser can differentiate between statements known as extensions and unknown statements. This enables the parser to complain about unknown statements, e.g. due to typos. o If an extension's definition contains a formal ABNF grammar definition and a parser is able to interpret this ABNF definition, this enables the parser also to complain about wrong usage of an extension. o Since, there might be some common need for extensions, there is a relatively high probability of extension name collisions originated by different organizations, as long as there is no standardized extension for that purpose. The requirement to explicitly import extension statements allows to distinguish those extensions. o The supported extensions of an SMIng implementation, e.g. a SMIng module compiler, can be clearly expressed. The only formal effect of an extension statement definition is to declare its existence and its status, and optionally its ABNF grammar. All additional aspects SHOULD be described in the `description' statement: o The detailed semantics of the new statement SHOULD be described. o The contexts in which the new statement can be used, SHOULD be described, e.g., a new statement may be designed to be used only in the statement block of a module, but not in other nested statement blocks. Others may be applicable in multiple contexts. In addition, the point in the sequence of an obligatory order of other statements, where the new statement may be inserted, might Strauss, et. al. Expires May 11, 2001 [Page 38] Internet-Draft SMIng November 2000 be prescribed. o The circumstances that make the new statement mandatory or optional SHOULD be described. o The syntax of the new statement SHOULD at least be described informally, if not supplied formally in an `abnf' statement. o It might be reasonable to give some suggestions under which conditions the implementation of the new statement is adequate and how it could be integrated into existent implementations. Some possible extension applications are: o The formal mappings of SMIng definitions into the SNMP ([2]) and COPS-PR frameworks are defined as SMIng extensions. o Inlined annotations to definitions. E.g., a vendor may wish to describe additional information to class and attribute definitions in private modules. An example are severity levels of events in the statement block of an `event' statement. o Arbitrary annotations to external definitions. E.g., a vendor may wish to describe additional information to definitions in a "standard" module. This allows a vendor to implement "standard" modules as well as additional private features, without redundant module definitions, but on top of "standard" module definitions. Strauss, et. al. Expires May 11, 2001 [Page 39] Internet-Draft SMIng November 2000 12. Security Considerations This document defines a language with which to write and read descriptions of management information. The language itself has no security impact on the Internet. Strauss, et. al. Expires May 11, 2001 [Page 40] Internet-Draft SMIng November 2000 13. Acknowledgements This document and the companion documents [1] and [2] started as a central part of a master's thesis at the Technical University of Braunschweig, under the guidance of Juergen Schoenwaelder in 1999. Since SMIng started as a close successor of SMIv2, some paragraphs and phrases are taken from the SMIv2 specifications [4], [5], [6] written by Jeff Case, Keith McCloghrie, David Perkins, Marshall T. Rose, Juergen Schoenwaelder, and Steven L. Waldbusser. Finally, Marshall T. Rose's work on an XML framework for RFC authors [18] made the writing of an Internet standards document much more feasible. Thanks to these people and the authors of these documents. Strauss, et. al. Expires May 11, 2001 [Page 41] Internet-Draft SMIng November 2000 References [1] Strauss, F., "SMIng Core Modules", November 2000. [2] Strauss, F., "SMIng Extension for SNMP Mappings", November 2000. [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, BCP 14, March 1997. [4] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., Waldbusser, S., "Structure of Management Information Version 2 (SMIv2)", RFC 2578, STD 58, April 1999. [5] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., Waldbusser, S., "Textual Conventions for SMIv2", RFC 2579, STD 59, April 1999. [6] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., Waldbusser, S., "Conformance Statements for SMIv2", RFC 2580, STD 60, April 1999. [7] McCloghrie, K., Fine, M., Seligson, J., Chan, K., Hahn, S., Sahita, R., Smith, A., Reichmeyer, F., "Structure of Policy Provisioning Information (SPPI)", draft-ietf-rap-sppi-02.txt, September 2000. [8] Rose, M., McCloghrie, K., "Structure and Identification of Management Information for TCP/IP-based Internets", RFC 1155, STD 16, May 1990. [9] Rose, M., McCloghrie, K., "Concise MIB Definitions", RFC 1212, STD 16, March 1991. [10] Rose, M., "A Convention for Defining Traps for use with the SNMP", RFC 1215, March 1991. [11] Crocker, D., Overell, P., "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [12] International Organization for Standardization, "Specification of Abstract Syntax Notation One (ASN.1)", International Standard 8824, December 1987. [13] Harrington, D., Presuhn, R., Wijnen, B., "An Architecture for Describing SNMP Management Frameworks", RFC 2271, January 1999. [14] Institute of Electrical and Electronics Engineers, "IEEE Standard for Binary Floating-Point Arithmetic", ANSI/IEEE Standard 754-1985, August 1985. Strauss, et. al. Expires May 11, 2001 [Page 42] Internet-Draft SMIng November 2000 [15] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998. [16] Case, J., McCloghrie, K., Rose, M., Waldbusser, S., "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1907, January 1996. [17] Wijnen, B., Levi, D., "V2ToV1 - Mapping SNMPv2 onto SNMPv1 within a bi-lingual SNMP agent", RFC 2089, January 1997. [18] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. Authors' Addresses Frank Strauss TU Braunschweig Bueltenweg 74/75 38106 Braunschweig Germany Phone: +49 531 391-3266 EMail: strauss@ibr.cs.tu-bs.de URI: http://www.ibr.cs.tu-bs.de/ Juergen Schoenwaelder TU Braunschweig Bueltenweg 74/75 38106 Braunschweig Germany Phone: +49 531 391-3266 EMail: schoenw@ibr.cs.tu-bs.de URI: http://www.ibr.cs.tu-bs.de/ Keith McCloghrie Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA Phone: +1 408 526 5260 EMail: kzm@cisco.com URI: http://www.cisco.com/ Strauss, et. al. Expires May 11, 2001 [Page 43] Internet-Draft SMIng November 2000 Appendix A. The SMIng ABNF grammar The SMIng grammar conforms to the Augmented Backus-Naur Form (ABNF)[11], with one exception: For readability, keywords are represented as quoted strings, although ABNF would declare these strings to be case-insensitive. Anyhow, SMIng keyword are meant to be case-sensitive. ;; ;; sming.abnf -- SMIng grammar in ABNF notation (RFC 2234). ;; ;; @(#) $Id: sming.abnf,v 1.13 2000/11/10 16:41:20 strauss Exp $ ;; ;; Copyright (C) The Internet Society (1999-2000). All Rights Reserved. ;; ;; ;; This file is WORK IN PROGRESS. ;; smingFile = optsep *(moduleStatement optsep) ;; ;; Statement rules. ;; moduleStatement = moduleKeyword sep ucIdentifier optsep "{" stmtsep *(importStatement stmtsep) organizationStatement stmtsep contactStatement stmtsep descriptionStatement stmtsep 1*(revisionStatement stmtsep) *(extensionStatement stmtsep) *(typedefStatement stmtsep) *(identityStatement stmtsep) *(classStatement stmtsep) "}" optsep ";" extensionStatement = extensionKeyword sep lcIdentifier optsep "{" stmtsep *1(statusStatement stmtsep) descriptionStatement stmtsep *1(abnfStatement stmtsep) "}" optsep ";" typedefStatement = typedefKeyword sep ucIdentifier optsep "{" stmtsep typedefTypeStatement stmtsep *1(defaultStatement stmtsep) Strauss, et. al. Expires May 11, 2001 [Page 44] Internet-Draft SMIng November 2000 *1(formatStatement stmtsep) *1(unitsStatement stmtsep) *1(statusStatement stmtsep) descriptionStatement stmtsep "}" optsep ";" identityStatement = identityKeyword sep ucIdentifier optsep *1(":" optsep qucIdentifier optsep) "{" stmtsep *1(statusStatement stmtsep) descriptionStatement stmtsep "}" optsep ";" classStatement = classKeyword sep ucIdentifier optsep *1(":" optsep qucIdentifier optsep) "{" stmtsep attributeStatement stmtsep *(eventStatement stmtsep) *1(statusStatement stmtsep) descriptionStatement stmtsep "}" optsep ";" attributeStatement = attributeKeyword sep qucIdentifier sep lcIdentifier optsep "{" stmtsep accessStatement stmtsep *1(defaultStatement stmtsep) *1(formatStatement stmtsep) *1(unitsStatement stmtsep) *1(statusStatement stmtsep) descriptionStatement stmtsep "}" optsep ";" eventStatement = eventKeyword sep lcIdentifier optsep "{" stmtsep *1(attributesStatement stmtsep) *1(statusStatement stmtsep) descriptionStatement stmtsep "}" optsep ";" importStatement = importKeyword sep ucIdentifier optsep "(" optsep identifierList optsep ")" optsep ";" revisionStatement = revisionKeyword optsep "{" stmtsep dateStatement stmtsep descriptionStatement stmtsep Strauss, et. al. Expires May 11, 2001 [Page 45] Internet-Draft SMIng November 2000 "}" optsep ";" typedefTypeStatement = typeKeyword sep refinedBaseType optsep ";" dateStatement = dateKeyword sep date optsep ";" organizationStatement = organizationKeyword sep text optsep ";" contactStatement = contactKeyword sep text optsep ";" formatStatement = formatKeyword sep format optsep ";" unitsStatement = unitsKeyword sep units optsep ";" statusStatement = statusKeyword sep status optsep ";" accessStatement = accessKeyword sep access optsep ";" defaultStatement = defaultKeyword sep anyValue optsep ";" descriptionStatement = descriptionKeyword sep text optsep ";" abnfStatement = abnfKeyword sep text optsep ";" attributesStatement = attributesKeyword optsep "(" optsep qlcIdentifierList optsep ")" optsep ";" ;; ;; ;; refinedBaseType = OctetStringKeyword *1(optsep numberSpec) / PointerKeyword *1(optsep pointerSpec) / Integer32Keyword *1(optsep numberSpec) / Unsigned32Keyword *1(optsep numberSpec) / Integer64Keyword *1(optsep numberSpec) / Unsigned64Keyword *1(optsep numberSpec) / Float32Keyword *1(optsep floatSpec) / Float64Keyword *1(optsep floatSpec) / Float128Keyword *1(optsep floatSpec) / EnumerationKeyword optsep namedSignedNumberSpec / BitsKeyword optsep namedNumberSpec refinedType = qucIdentifier *1(optsep anySpec) anySpec = pointerSpec / numberSpec / floatSpec pointerSpec = "(" optsep qlcIdentifier optsep ")" Strauss, et. al. Expires May 11, 2001 [Page 46] Internet-Draft SMIng November 2000 numberSpec = "(" optsep numberElement *furtherNumberElement optsep ")" furtherNumberElement = optsep "|" optsep numberElement numberElement = signedNumber *1numberUpperLimit numberUpperLimit = optsep ".." optsep signedNumber floatSpec = "(" optsep floatElement *furtherFloatElement optsep ")" furtherFloatElement = optsep "|" optsep floatElement floatElement = floatValue *1floatUpperLimit floatUpperLimit = optsep ".." optsep floatValue namedNumberSpec = "(" optsep namedNumberList optsep ")" namedNumberList = namedNumberItem *(optsep "," optsep namedNumberItem) *1(optsep ",") namedNumberItem = lcIdentifier optsep "(" optsep number optsep ")" namedSignedNumberSpec = "(" optsep namedSignedNumberList optsep ")" namedSignedNumberList = namedSignedNumberItem *(optsep "," optsep namedSignedNumberItem) *1(optsep ",") namedSignedNumberItem = lcIdentifier optsep "(" optsep signedNumber optsep ")" identifierList = identifier *(optsep "," optsep identifier) *1(optsep ",") qIdentifierList = qIdentifier *(optsep "," optsep qIdentifier) *1(optsep ",") qlcIdentifierList = qlcIdentifier *(optsep "," optsep qlcIdentifier) *1(optsep ",") Strauss, et. al. Expires May 11, 2001 [Page 47] Internet-Draft SMIng November 2000 bitsValue = "(" optsep bitsList optsep ")" bitsList = *1(lcIdentifier *(optsep "," optsep lcIdentifier)) *1(optsep ",") ;; ;; Other basic rules. ;; identifier = ucIdentifier / lcIdentifier qIdentifier = qucIdentifier / qlcIdentifier ucIdentifier = ucAlpha *63(ALPHA / DIGIT / "-") qucIdentifier = *1(ucIdentifier "::") ucIdentifier lcIdentifier = lcAlpha *63(ALPHA / DIGIT / "-") qlcIdentifier = *1(ucIdentifier "::") lcIdentifier attrIdentifier = lcIdentifier *("." lcIdentifier) qattrIdentifier = *1(ucIdentifier ".") attrIdentifier text = textSegment *(optsep textSegment) textSegment = DQUOTE *textAtom DQUOTE textAtom = textVChar / HTAB / SP / lineBreak date = DQUOTE 4DIGIT "-" 2DIGIT "-" 2DIGIT *1(" " 2DIGIT ":" 2DIGIT) DQUOTE ; always in UTC format = textSegment units = textSegment anyValue = bitsValue / signedNumber / hexadecimalNumber / floatValue / text / qlcIdentifier ; Note: `qlcIdentifier' includes the ; syntax of enumeration labels and Strauss, et. al. Expires May 11, 2001 [Page 48] Internet-Draft SMIng November 2000 ; identities. ; They are not named literally to ; avoid reduce/reduce conflicts when ; building LR parsers based on this ; grammar. status = currentKeyword / deprecatedKeyword / obsoleteKeyword access = noaccessKeyword / eventonlyKeyword / readonlyKeyword / readwriteKeyword number = hexadecimalNumber / decimalNumber negativeNumber = "-" decimalNumber signedNumber = number / negativeNumber decimalNumber = "0" / (nonZeroDigit *DIGIT) zeroDecimalNumber = 1*DIGIT hexadecimalNumber = "0x" 1*(HEXDIG HEXDIG) floatValue = neginfKeyword / posinfKeyword / snanKeyword / qnanKeyword / signedNumber "." zeroDecimalNumber *1("E" ("+"/"-") zeroDecimalNumber) ;; ;; Rules to skip unknown statements ;; with arbitrary arguments and blocks. ;; unknownStatement = unknownKeyword optsep *unknownArgument optsep ";" unknownArgument = ("(" optsep unknownList optsep ")") / ("{" optsep *unknownStatement optsep "}") / qucIdentifier / anyValue / anySpec unknownList = namedNumberList / Strauss, et. al. Expires May 11, 2001 [Page 49] Internet-Draft SMIng November 2000 qIdentifierList unknownKeyword = lcIdentifier ;; ;; Keyword rules. ;; ;; Typically, keywords are represented by tokens returned from the ;; lexical analyzer. Note, that the lexer has to be stateful to ;; distinguish keywords from identifiers depending on the context ;; position in the input stream. ;; ;; Also note, that these keyword definitions are represented in ;; cleartext for readability, while SMIng keywords are meant to be ;; case-sensitive, although ABNF makes quoted strings like these to ;; be case-insensitive. ;; ;; Statement keywords. moduleKeyword = "module" importKeyword = "import" revisionKeyword = "revision" dateKeyword = "date" organizationKeyword = "organization" contactKeyword = "contact" descriptionKeyword = "description" extensionKeyword = "extension" typedefKeyword = "typedef" typeKeyword = "type" identityKeyword = "identity" classKeyword = "class" attributeKeyword = "attribute" eventKeyword = "event" attributesKeyword = "attributes" formatKeyword = "format" unitsKeyword = "units" statusKeyword = "status" accessKeyword = "access" defaultKeyword = "default" abnfKeyword = "abnf" ;; Base type keywords. OctetStringKeyword = "OctetString" PointerKeyword = "Pointer" Integer32Keyword = "Integer32" Unsigned32Keyword = "Unsigned32" Integer64Keyword = "Integer64" Strauss, et. al. Expires May 11, 2001 [Page 50] Internet-Draft SMIng November 2000 Unsigned64Keyword = "Unsigned64" Float32Keyword = "Float32" Float64Keyword = "Float64" Float128Keyword = "Float128" BitsKeyword = "Bits" EnumerationKeyword = "Enumeration" ;; Status keyword. currentKeyword = "current" deprecatedKeyword = "deprecated" obsoleteKeyword = "obsolete" ;; Access keywords. noaccessKeyword = "noaccess" eventonlyKeyword = "eventonly" readonlyKeyword = "readonly" readwriteKeyword = "readwrite" ;; Special floating point values' keywords. neginfKeyword = "neginf" posinfKeyword = "posinf" snanKeyword = "snan" qnanKeyword = "qnan" ;; ;; Some low level rules. ;; These tokens are typically skipped by the lexical analyzer. ;; sep = 1*(comment / lineBreak / WSP) ; unconditional separator optsep = *(comment / lineBreak / WSP) stmtsep = *(comment / lineBreak / WSP / unknownStatement) comment = "//" *(WSP / VCHAR) lineBreak lineBreak = CRLF / LF ;; ;; Encoding specific rules. ;; Strauss, et. al. Expires May 11, 2001 [Page 51] Internet-Draft SMIng November 2000 textVChar = %x21 / %x23-7E ; any VCHAR except DQUOTE ucAlpha = %x41-5A lcAlpha = %x61-7A nonZeroDigit = %x31-39 ;; ;; RFC 2234 core rules. ;; ALPHA = %x41-5A / %x61-7A ; A-Z / a-z CR = %x0D ; carriage return CRLF = CR LF ; Internet standard newline DIGIT = %x30-39 ; 0-9 DQUOTE = %x22 ; " (Double Quote) HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" HTAB = %x09 ; horizontal tab LF = %x0A ; linefeed SP = %x20 ; space VCHAR = %x21-7E ; visible (printing) characters WSP = SP / HTAB ; white space ;; ;; EOF ;; Strauss, et. al. Expires May 11, 2001 [Page 52] Internet-Draft SMIng November 2000 Appendix B. Glossary columnar object: An object in a table row that may have zero, one or more object instances. Instances are identified by using the values of `indexing objects' as `instance identifier'. extension: The SMIng `extension' statement can be used to define new statements. Extensions can express annotations to existent management information, agent capabilities known from SMIv2, or arbitrary other information. See Section 11 for details. identifier: The name of any definition, either a module, type, node, scalar object, table, row, columnar object, notification, group, compliance, a named number of an enumeration or bits type or any construct defined by an SMIng extension. Every identifier starts with an upper-case or lower-case character, followed by letters, digits and hyphens, but without consecutive or trailing hyphens. The length of an identifier MUST NOT exceed 64 characters. Note that SMIng keywords may be used as identifiers, though it's NOT RECOMMENDED. See also Section 2.1. indexing objects: A Table may contain multiple instances of single columnar objects. That is, there may be multiple rows. The table's `indexing objects' are used to unambiguously distinguish the rows of a table. A special encoding of their values represents the columns' instance-identifier, and thus identifies the row. instance-identifier: That part of an object identifier value, that is used to unambiguously identify an instance of an object. For scalar objects, the instance-identifier is `0'. For columnar objects, the instance-identifier is built from the values of the `indexing objects'. module: A module is the container of inter-related management information, either managed objects or other definitions like type definitions or annotations. A module has to conform the SMIng grammar and semantics described by this document. A module represents a namespace in which local definitions are available and external definitions have to be imported. named number: Values of `Enumeration' types (Section 3.10) and single elements of `Bits' (Section 3.11) types are integer numbers, each associated with an identifers. Those number-identifier pairs are called `named numbers'. object: A leaf definition in the object identifier tree, that represents a class of object instances. Objects are exactly those definitions declared by the SMIng keywords `scalar' or `column'. Strauss, et. al. Expires May 11, 2001 [Page 53] Internet-Draft SMIng November 2000 object identifier: Management information is organized in a tree of nodes. Each node is unambiguously identified by an `object identifier', that consists of a sequence of integer numbers (`sub-identifiers') which represent the path of nodes from the root to the addressed node in the tree. See also Section 2. row: The kind of node used to group columnar objects of a table. Some significant information on table indexing and information used for row creation and deletion is associated with a table's row definition. scalar object: An object that has zero or one object instance. sub-identifier: A single component of an object identifier. There are at most 128 sub-identifiers in an object identifier value and each sub-identifier has a maximum value of 2^32-1 (4294967295). table: The kind of node used to group management information that is organized in a sequence of rows. Strauss, et. al. Expires May 11, 2001 [Page 54] Internet-Draft SMIng November 2000 Full Copyright Statement Copyright (C) The Internet Society (2000). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Strauss, et. al. Expires May 11, 2001 [Page 55]