idnits 2.17.1 draft-irtf-nmrg-sming-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 7 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** The abstract seems to contain references ([RFCxxx2]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == There are 1 instance of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 942 has weird spacing: '...bccddee aa:b...' == Line 1234 has weird spacing: '... status curre...' == Line 1461 has weird spacing: '... status curre...' == Line 1467 has weird spacing: '... status curre...' == Line 1473 has weird spacing: '... parent snmpT...' == (2 more instances...) == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 16, 2003) is 7436 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC3411' is defined on line 2000, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) -- Obsolete informational reference (is this intentional?): RFC 2279 (Obsoleted by RFC 3629) Summary: 5 errors (**), 0 flaws (~~), 12 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group F. Strauss 3 Internet-Draft TU Braunschweig 4 Expires: June 15, 2004 J. Schoenwaelder 5 International University Bremen 6 December 16, 2003 8 SMIng - Next Generation Structure of Management Information 9 draft-irtf-nmrg-sming-07 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at http:// 27 www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on June 15, 2004. 34 Copyright Notice 36 Copyright (C) The Internet Society (2003). All Rights Reserved. 38 Abstract 40 This memo defines the base SMIng (Structure of Management 41 Information, Next Generation) language. SMIng is a data definition 42 language that provides a protocol-independent representation for 43 management information. Separate RFCs define mappings of SMIng to 44 specific management protocols, including SNMP [RFCxxx2]. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 49 1.1 The History of SMIng . . . . . . . . . . . . . . . . . . . . 5 50 1.2 Terms of Requirement Levels . . . . . . . . . . . . . . . . 5 51 2. SMIng Data Modelling . . . . . . . . . . . . . . . . . . . . 5 52 2.1 Identifiers . . . . . . . . . . . . . . . . . . . . . . . . 6 53 3. Base Types and Derived Types . . . . . . . . . . . . . . . . 8 54 3.1 OctetString . . . . . . . . . . . . . . . . . . . . . . . . 8 55 3.2 Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . 9 56 3.3 ObjectIdentifier . . . . . . . . . . . . . . . . . . . . . . 10 57 3.4 Integer32 . . . . . . . . . . . . . . . . . . . . . . . . . 11 58 3.5 Integer64 . . . . . . . . . . . . . . . . . . . . . . . . . 11 59 3.6 Unsigned32 . . . . . . . . . . . . . . . . . . . . . . . . . 12 60 3.7 Unsigned64 . . . . . . . . . . . . . . . . . . . . . . . . . 13 61 3.8 Float32 . . . . . . . . . . . . . . . . . . . . . . . . . . 14 62 3.9 Float64 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 63 3.10 Float128 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 64 3.11 Enumeration . . . . . . . . . . . . . . . . . . . . . . . . 17 65 3.12 Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 66 3.13 Display Formats . . . . . . . . . . . . . . . . . . . . . . 19 67 4. The SMIng File Structure . . . . . . . . . . . . . . . . . . 21 68 4.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . 21 69 4.2 Textual Data . . . . . . . . . . . . . . . . . . . . . . . . 21 70 4.3 Statements and Arguments . . . . . . . . . . . . . . . . . . 22 71 5. The module Statement . . . . . . . . . . . . . . . . . . . . 22 72 5.1 The module's import Statement . . . . . . . . . . . . . . . 23 73 5.2 The module's organization Statement . . . . . . . . . . . . 24 74 5.3 The module's contact Statement . . . . . . . . . . . . . . . 24 75 5.4 The module's description Statement . . . . . . . . . . . . . 24 76 5.5 The module's reference Statement . . . . . . . . . . . . . . 24 77 5.6 The module's revision Statement . . . . . . . . . . . . . . 24 78 5.6.1 The revision's date Statement . . . . . . . . . . . . . . . 24 79 5.6.2 The revision's description Statement . . . . . . . . . . . . 25 80 5.7 Usage Example . . . . . . . . . . . . . . . . . . . . . . . 25 81 6. The extension Statement . . . . . . . . . . . . . . . . . . 26 82 6.1 The extension's status Statement . . . . . . . . . . . . . . 27 83 6.2 The extension's description Statement . . . . . . . . . . . 27 84 6.3 The extension's reference Statement . . . . . . . . . . . . 27 85 6.4 The extension's abnf Statement . . . . . . . . . . . . . . . 27 86 6.5 Usage Example . . . . . . . . . . . . . . . . . . . . . . . 28 87 7. The typedef Statement . . . . . . . . . . . . . . . . . . . 28 88 7.1 The typedef's type Statement . . . . . . . . . . . . . . . . 28 89 7.2 The typedef's default Statement . . . . . . . . . . . . . . 28 90 7.3 The typedef's format Statement . . . . . . . . . . . . . . . 29 91 7.4 The typedef's units Statement . . . . . . . . . . . . . . . 29 92 7.5 The typedef's status Statement . . . . . . . . . . . . . . . 29 93 7.6 The typedef's description Statement . . . . . . . . . . . . 30 94 7.7 The typedef's reference Statement . . . . . . . . . . . . . 30 95 7.8 Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 30 96 8. The identity Statement . . . . . . . . . . . . . . . . . . . 31 97 8.1 The identity's parent Statement . . . . . . . . . . . . . . 31 98 8.2 The identity's status Statement . . . . . . . . . . . . . . 32 99 8.3 The identity' description Statement . . . . . . . . . . . . 32 100 8.4 The identity's reference Statement . . . . . . . . . . . . . 32 101 8.5 Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 33 102 9. The class Statement . . . . . . . . . . . . . . . . . . . . 33 103 9.1 The class' extends Statement . . . . . . . . . . . . . . . . 33 104 9.2 The class' attribute Statement . . . . . . . . . . . . . . . 33 105 9.2.1 The attribute's type Statement . . . . . . . . . . . . . . . 34 106 9.2.2 The attribute's access Statement . . . . . . . . . . . . . . 34 107 9.2.3 The attribute's default Statement . . . . . . . . . . . . . 34 108 9.2.4 The attribute's format Statement . . . . . . . . . . . . . . 34 109 9.2.5 The attribute's units Statement . . . . . . . . . . . . . . 35 110 9.2.6 The attribute's status Statement . . . . . . . . . . . . . . 35 111 9.2.7 The attribute's description Statement . . . . . . . . . . . 36 112 9.2.8 The attribute's reference Statement . . . . . . . . . . . . 36 113 9.3 The class' unique Statement . . . . . . . . . . . . . . . . 36 114 9.4 The class' event Statement . . . . . . . . . . . . . . . . . 36 115 9.4.1 The event's status Statement . . . . . . . . . . . . . . . . 37 116 9.4.2 The event's description Statement . . . . . . . . . . . . . 37 117 9.4.3 The event's reference Statement . . . . . . . . . . . . . . 37 118 9.5 The class' status Statement . . . . . . . . . . . . . . . . 37 119 9.6 The class' description Statement . . . . . . . . . . . . . . 38 120 9.7 The class's reference Statement . . . . . . . . . . . . . . 38 121 9.8 Usage Example . . . . . . . . . . . . . . . . . . . . . . . 38 122 10. Extending a Module . . . . . . . . . . . . . . . . . . . . . 39 123 11. SMIng Language Extensibility . . . . . . . . . . . . . . . . 41 124 12. Security Considerations . . . . . . . . . . . . . . . . . . 42 125 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 42 126 Normative References . . . . . . . . . . . . . . . . . . . . 43 127 Informative References . . . . . . . . . . . . . . . . . . . 43 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 44 129 A. NMRG-SMING Module . . . . . . . . . . . . . . . . . . . . . 45 130 B. SMIng ABNF Grammar . . . . . . . . . . . . . . . . . . . . . 54 131 Intellectual Property and Copyright Statements . . . . . . . 65 133 1. Introduction 135 In traditional management systems management information is viewed as 136 a collection of managed objects, residing in a virtual information 137 store, termed the Management Information Base (MIB). Collections of 138 related objects are defined in MIB modules. These modules are 139 written conforming to a specification language, the Structure of 140 Management Information (SMI). There are different versions of the 141 SMI. The SMI version 1 (SMIv1) is defined in [RFC1155], [RFC1212], 142 [RFC1215] and the SMI version 2 (SMIv2) in [RFC2578], [RFC2579], 143 [RFC2580]. Both are based on adapted subsets of OSI's Abstract 144 Syntax Notation One, ASN.1 [ASN1]. 146 In a similar fashion policy provisioning information is viewed as a 147 collection of Provisioning Classes (PRCs) and Provisioning Instances 148 (PRIs) residing in a virtual information store, termed the Policy 149 Information Base (PIB). Collections of related Provisioning Classes 150 are defined in PIB modules. PIB modules are written using the 151 Structure of Policy Provisioning Information (SPPI) [RFC3159] which 152 is an adapted subset of SMIv2. 154 The SMIv1 and the SMIv2 are bound to the Simple Network Management 155 Protocol (SNMP) while the the SPPI is bound to the Common Open Policy 156 Service Provisioning (COPS-PR) protocol. Even though the languages 157 have common rules, it is hard to use common data definitions with 158 both protocols. It is the purpose of this document to define a 159 common data definition language, named SMIng, that allows to formally 160 specify data models independent of specific protocols and 161 applications. The appendix of this document defines a core module 162 that supplies common SMIng definitions. 164 A companion document contains an SMIng language extension to define 165 SNMP specific mappings of SMIng definitions in a way compatible to 166 SMIv2 MIBs [RFCxxx2]. Additional language extensions may be added in 167 the future, e.g. to define COPS-PR specific mappings of SMIng 168 definition in a way compatible to SPPI PIBs. 170 Section 2 gives an overview of the basic concepts of data modelling 171 using SMIng while the subsequent sections present the concepts of the 172 SMIng language in detail: the base types, the SMIng file structure, 173 and all SMIng core statements. 175 The remainder of the document describes extensibility features of the 176 language and rules to follow when changes are applied to a module. 177 Appendix B contains the grammar of SMIng in ABNF [RFC2234] notation. 179 1.1 The History of SMIng 181 SMIng started in 1999 as a research project to address some drawbacks 182 of SMIv2, the current data modelling language for management 183 information bases, primarily its partial dependence on ASN.1 and a 184 number of exception rules that turned out to be problematic. In 185 2000, the work was handed over to the IRTF Network Management 186 Research Group where it was significantly detailed. Since the work 187 of the RAP Working Group on COPS-PR and SPPI emerged in 1999/2000, 188 SMIng was split into two parts: a core data definition language 189 (defined in this document) and protocol mappings to allow the 190 application of core defintions through (potentially) multiple 191 management protocols. The replacement of SMIv2 and SPPI by a single 192 merged data definition language was also a primary goal of the IETF 193 SMING Working Group that was chartered at the end of 2000. 195 The requirements for a new data definition language were discussed 196 several times within the IETF SMING Working Group and changed 197 significantly over time [RFC3216], so that another proposal (in 198 addition to SMIng), named SMI Data Structures (SMI-DS) was presented 199 to the Working Group. In the end neither of the two proposals found 200 enough consensus and support and the attempt to merge the existing 201 concepts did not succeed, so that the Working Group was closed down 202 in April 2003. 204 In order to record the work of the NMRG (Network Management Research 205 Group) on SMIng, this memo and the accompanying memo on the SNMP 206 protocol mapping [RFCxxx2] have been published for informational 207 purpose. 209 Note that throughout these documents the term "SMIng" refers to the 210 specific data modelling language that is specified in this document, 211 whereas the term "SMING" refers to the general effort within the IETF 212 Working Group to define a new management data definition language as 213 an SMIv2 successor and probably an SPPI merger, for which "SMIng" and 214 "SMI-DS" were two specific proposals. 216 1.2 Terms of Requirement Levels 218 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 219 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 220 document are to be interpreted as described in [RFC2119]. 222 2. SMIng Data Modelling 224 SMIng is a language designed to specify management information in a 225 structured way readable to computer programs, e.g. MIB compilers, as 226 well as to human readers. 228 Management information is modeled in classes. Classes can be defined 229 from scratch or by derivation from a parent class. Derivation from 230 multiple parent classes is not possible. The concept of classes is 231 described in Section 9. 233 Each class has a number of attributes. Each attribute represents an 234 atomic piece of information of a base type, a sub-type of a base 235 type, or another class. The concept of attributes is described in 236 Section 9.2. 238 The base types of SMIng include signed and unsigned integers, octet 239 strings, enumeration types, bitset types, and pointers. Pointers are 240 references to class instances, attributes of class instances, or 241 arbitrary identities. The SMIng type system is described in Section 242 3. 244 Related class and type definitions are defined in modules. A module 245 may refer to definitions from other modules by importing identifiers 246 from those modules. Each module may serve one or multiple purposes: 248 o the definition of management classes, 250 o the definition of events, 252 o the definition of derived types, 254 o the definition of arbitrary untyped identities serving as values 255 of pointers, 257 o the definition of SMIng extensions to allow the local module or 258 other modules to specify information beyond the scope of the base 259 SMIng in a machine readable notation. Some extensions for the 260 application of SMIng in the SNMP framework are defined in 261 [RFCxxx2], 263 o the definition of information beyond the scope of the base SMIng 264 statements, based on locally defined or imported SMIng extensions. 266 Each module is identified by an upper-case identifier. The names of 267 all standard modules must be unique (but different versions of the 268 same module should have the same name). Developers of enterprise 269 modules are encouraged to choose names for their modules that will 270 have a low probability of colliding with standard or other enterprise 271 modules, e.g. by using the enterprise or organization name as a 272 prefix. 274 2.1 Identifiers 275 Identifiers are used to identify different kinds of SMIng items by 276 name. Each identifier is valid in a namespace which depends on the 277 type of the SMIng item being defined: 279 o The global namespace contains all module identifiers. 281 o Each module defines a new namespace. A module's namespace may 282 contain definitions of extension identifiers, derived type 283 identifiers, identity identifiers, and class identifiers. 284 Furthermore, a module may import identifiers of these kinds from 285 other modules. All these identifiers are also visible within all 286 inner namespaces of the module. 288 o Each class within a module defines a new namespace. A class' 289 namespace may contain definitions of attribute identifiers and 290 event identifiers. 292 o Each enumeration type and bitset type defines a new namespace of 293 its named numbers. These named numbers are visible in each 294 expression of a corresponding value, e.g., default values and 295 sub-typing restrictions. 297 o Extensions may define additional namespaces and have additional 298 rules of other namespaces' visibilty. 300 Within every namespace each identifier MUST be unique. 302 Each identifier starts with an upper-case or lower-case character, 303 dependent on the kind of SMIng item, followed by zero or more 304 letters, digits and hyphens. 306 All identifiers defined in a namespace MUST be unique and SHOULD NOT 307 only differ in case. Identifiers MUST NOT exceed 64 characters in 308 length. Furthermore, the set of all identifiers defined in all 309 modules of a single standardization body or organization SHOULD be 310 unique and mnemonic. This promotes a common language for humans to 311 use when discussing a module. 313 To reference an item that is defined in the local module, its 314 definition MUST sequentially precede the reference. Thus, there MUST 315 NOT be any forward references. 317 To reference an item, that is defined in an external module it MUST 318 be imported (Section 5.1). Identifiers that are neither defined nor 319 imported MUST NOT be visible in the local module. 321 When identifiers from external modules are referenced, there is the 322 possibility of name collisions. As such, if different items with the 323 same identifier are imported or if imported identifiers collide with 324 identifiers of locally defined items, then this ambiguity is resolved 325 by prefixing those identifiers with the names of their modules and 326 the namespace operator `::', i.e. `Module::item'. Of course, this 327 notation can be used to refer to identifiers even when there is no 328 name collision. 330 Note that SMIng core language keywords MUST NOT be imported. See the 331 `...Keyword' rules of the SMIng ABNF grammar in Appendix B for a list 332 of those keywords. 334 3. Base Types and Derived Types 336 SMIng has a set of base types, similar to those of many programming 337 languages, but with some differences due to special requirements from 338 the management information model. 340 Additional types may be defined, derived from those base types or 341 from other derived types. Derived types may use subtyping to 342 formally restrict the set of possible values. An initial set of 343 commonly used derived types is defined in the SMIng standard module 344 NMRG-SMING [RFCxxx2]. 346 The different base types and their derived types allow different 347 kinds of subtyping, namely size restrictions of octet strings 348 (Section 3.1), range restrictions of numeric types (Section 3.4 349 through Section 3.10), restricted pointer types (Section 3.2), and 350 restrictions of the sets of named numbers for enumeration types 351 (Section 3.11) and bit sets (Section 3.12). 353 3.1 OctetString 355 The OctetString base type represents arbitrary binary or textual 356 data. Although SMIng has a theoretical size limitation of 2^16-1 357 (65535) octets for this base type, module designers should realize 358 that there may be implementation and interoperability limitations for 359 sizes in excess of 255 octets. 361 Values of octet strings may be denoted as textual data enclosed in 362 double quotes or as arbitrary binary data denoted as a `0x'-prefixed 363 hexadecimal value of an even number of at least two hexadecimal 364 digits, where each pair of hexadecimal digits represents a single 365 octet. Letters in hexadecimal values MAY be upper-case but 366 lower-case characters are RECOMMENDED. Textual data may contain any 367 number (possibly zero) of any 7-bit displayable ASCII characters, 368 including tab characters, spaces and line terminator characters (nl 369 or cr & nl). Some characters require a special encoding (see Section 370 4.2). Textual data may span multiple lines, where each subsequent 371 line prefix containing only white space up to the column where the 372 first line's data starts SHOULD be skipped by parsers for a better 373 text formatting. 375 When defining a type derived (directly or indirectly) from the 376 OctetString base type, the size in octets may be restricted by 377 appending a list of size ranges or explicit size values, separated by 378 pipe `|' characters and the whole list enclosed in parenthesis. A 379 size range consists of a lower bound, two consecutive dots `..' and 380 an upper bound. Each value can be given in decimal or `0x'-prefixed 381 hexadecimal notation. Hexadecimal numbers must have an even number 382 of at least two digits. Size restricting values MUST NOT be 383 negative. If multiple values or ranges are given, they all MUST be 384 disjoint and MUST be in ascending order. If a size restriction is 385 applied to an already size restricted octet string the new 386 restriction MUST be equal or more limiting, that is raising the lower 387 bounds, reducing the upper bounds, removing explicit size values or 388 ranges, or splitting ranges into multiple ranges with intermediate 389 gaps. 391 Value Examples: 393 "This is a multiline 394 textual data example." // legal 395 "This is "illegally" quoted." // illegal quotes 396 "This is \"legally\" quoted." // legally encoded quotes 397 "But this is 'ok', as well." // legal apostrophe quoting 398 "" // legal zero length 399 0x123 // illegal odd hex length 400 0x534d496e670a // legal octet string 402 Restriction Examples: 404 OctetString (0 | 4..255) // legal size spec 405 OctetString (4) // legal exact size 406 OctetString (-1 | 1) // illegal negative size 407 OctetString (5 | 0) // illegal ordering 408 OctetString (1 | 1..10) // illegal overlapping 410 3.2 Pointer 412 The Pointer base type represents values that reference class 413 instances, attributes of class instances, or arbitrary identities. 414 The only values of the Pointer type that can be present in a module 415 can refer to identities. They are denoted as identifiers of the 416 concerned identities. 418 When defining a type derived (directly or indirectly) from the 419 Pointer base type, the values may be restricted to a specific class, 420 attribute or identity and all (directly or indirectly) derived items 421 thereof by appending the identifier of the appropriate construct 422 enclosed in parenthesis. 424 Value Examples: 426 null // legal identity name 427 snmpUDPDomain // legal identity name 429 Restriction Examples: 431 Pointer (snmpTransportDomain) // legal restriction 433 3.3 ObjectIdentifier 435 The ObjectIdentifier base type represents administratively assigned 436 names for use with SNMP and COPS-PR. This type SHOULD NOT be used in 437 protocol independant SMIng modules. It is meant to be used in SNMP 438 and COPS-PR mappings of attributes of type Pointer (Section 3.2). 440 Values of this type may be denoted as a sequence of numerical 441 non-negative sub-identifier values which each MUST NOT exceed 2^32-1 442 (4294967295). Sub-identifiers may be denoted decimal or 443 `0x'-prefixed hexadecimal. They are separated by single dots and 444 without any intermediate white space. Alternatively (and preferred 445 in most cases), the first element may be a previously defined or 446 imported lower-case identifier, representing a static object 447 identifier prefix. 449 Although the number of sub-identifiers in SMIng object identifiers is 450 not limited, module designers should realize that there may be 451 implementations that stick with the SMIv1/v2 limit of 128 452 sub-identifiers. 454 Object identifier derived types cannot be restricted in any way. 456 Value Examples: 458 1.3.6.1 // legal numerical oid 459 mib-2.1 // legal oid with identifier prefix 460 internet.4.1.0x0627.0x01 // legal oid with hex subids 461 iso.-1 // illegal negative subid 462 iso.org.6 // illegal non-heading identifier 463 IF-MIB::ifNumber.0 // legel fully quallified instance oid 465 3.4 Integer32 467 The Integer32 base type represents integer values between -2^31 468 (-2147483648) and 2^31-1 (2147483647). 470 Values of type Integer32 may be denoted as decimal or hexadecimal 471 numbers, where only decimal numbers can be negative. Decimal numbers 472 other than zero MUST NOT have leading zero digits. Hexadecimal 473 numbers are prefixed by `0x' and MUST have an even number of at least 474 two hexadecimal digits, where letters MAY be upper-case but 475 lower-case characters are RECOMMENDED. 477 When defining a type derived (directly or indirectly) from the 478 Integer32 base type, the set of possible values may be restricted by 479 appending a list of ranges or explicit values, separated by pipe `|' 480 characters and the whole list enclosed in parenthesis. A range 481 consists of a lower bound, two consecutive dots `..' and an upper 482 bound. Each value can be given in decimal or `0x'-prefixed 483 hexadecimal notation. Hexadecimal numbers must have an even number 484 of at least two digits. If multiple values or ranges are given they 485 all MUST be disjoint and MUST be in ascending order. If a value 486 restriction is applied to an already restricted type the new 487 restriction MUST be equal or more limiting, that is raising the lower 488 bounds, reducing the upper bounds, removing explicit values or 489 ranges, or splitting ranges into multiple ranges with intermediate 490 gaps. 492 Value Examples: 494 015 // illegal leading zero 495 -123 // legal negative value 496 - 1 // illegal intermediate space 497 0xabc // illegal hexadecimal value length 498 -0xff // illegal sign on hex value 499 0x80000000 // illegal value, too large 500 0xf00f // legal hexadecimal value 502 Restriction Examples: 504 Integer32 (0 | 5..10) // legal range spec 505 Integer32 (5..10 | 2..3) // illegal ordering 506 Integer32 (4..8 | 5..10) // illegal overlapping 508 3.5 Integer64 510 The Integer64 base type represents integer values between -2^63 511 (-9223372036854775808) and 2^63-1 (9223372036854775807). 513 Values of type Integer64 may be denoted as decimal or hexadecimal 514 numbers, where only decimal numbers can be negative. Decimal numbers 515 other than zero MUST NOT have leading zero digits. Hexadecimal 516 numbers are prefixed by `0x' and MUST have an even number of 517 hexadecimal digits, where letters MAY be upper-case but lower-case 518 characters are RECOMMENDED. 520 When defining a type derived (directly or indirectly) from the 521 Integer64 base type, the set of possible values may be restricted by 522 appending a list of ranges or explicit values, separated by pipe `|' 523 characters and the whole list enclosed in parenthesis. A range 524 consists of a lower bound, two consecutive dots `..' and an upper 525 bound. Each value can be given in decimal or `0x'-prefixed 526 hexadecimal notation. Hexadecimal numbers must have an even number 527 of at least two digits. If multiple values or ranges are given they 528 all MUST be disjoint and MUST be in ascending order. If a value 529 restriction is applied to an already restricted type the new 530 restriction MUST be equal or more limiting, that is raising the lower 531 bounds, reducing the upper bounds, removing explicit values or 532 ranges, or splitting ranges into multiple ranges with intermediate 533 gaps. 535 Value Examples: 537 015 // illegal leading zero 538 -123 // legal negative value 539 - 1 // illegal intermediate space 540 0xabc // illegal hexadecimal value length 541 -0xff // illegal sign on hex value 542 0x80000000 // legal value 544 Restriction Examples: 546 Integer64 (0 | 5..10) // legal range spec 547 Integer64 (5..10 | 2..3) // illegal ordering 548 Integer64 (4..8 | 5..10) // illegal overlapping 550 3.6 Unsigned32 552 The Unsigned32 base type represents positive integer values between 0 553 and 2^32-1 (4294967295). 555 Values of type Unsigned32 may be denoted as decimal or hexadecimal 556 numbers. Decimal numbers other than zero MUST NOT have leading zero 557 digits. Hexadecimal numbers are prefixed by `0x' and MUST have an 558 even number of hexadecimal digits, where letters MAY be upper-case 559 but lower-case characters are RECOMMENDED. 561 When defining a type derived (directly or indirectly) from the 562 Unsigned32 base type, the set of possible values may be restricted by 563 appending a list of ranges or explicit values, separated by pipe `|' 564 characters and the whole list enclosed in parenthesis. A range 565 consists of a lower bound, two consecutive dots `..' and an upper 566 bound. Each value can be given in decimal or `0x'-prefixed 567 hexadecimal notation. Hexadecimal numbers must have an even number 568 of at least two digits. If multiple values or ranges are given they 569 all MUST be disjoint and MUST be in ascending order. If a value 570 restriction is applied to an already restricted type the new 571 restriction MUST be equal or more limiting, that is raising the lower 572 bounds, reducing the upper bounds, removing explicit values or 573 ranges, or splitting ranges into multiple ranges with intermediate 574 gaps. 576 Value Examples: 578 015 // illegal leading zero 579 -123 // illegal negative value 580 0xabc // illegal hexadecimal value length 581 0x80000000 // legal hexadecimal value 582 0x8080000000 // illegal value, too large 584 Restriction Examples: 586 Unsigned32 (0 | 5..10) // legal range spec 587 Unsigned32 (5..10 | 2..3) // illegal ordering 588 Unsigned32 (4..8 | 5..10) // illegal overlapping 590 3.7 Unsigned64 592 The Unsigned64 base type represents positive integer values between 0 593 and 2^64-1 (18446744073709551615). 595 Values of type Unsigned64 may be denoted as decimal or hexadecimal 596 numbers. Decimal numbers other than zero MUST NOT have leading zero 597 digits. Hexadecimal numbers are prefixed by `0x' and MUST have an 598 even number of hexadecimal digits, where letters MAY be upper-case 599 but lower-case characters are RECOMMENDED. 601 When defining a type derived (directly or indirectly) from the 602 Unsigned64 base type, the set of possible values may be restricted by 603 appending a list of ranges or explicit values, separated by pipe `|' 604 characters and the whole list enclosed in parenthesis. A range 605 consists of a lower bound, two consecutive dots `..' and an upper 606 bound. Each value can be given in decimal or `0x'-prefixed 607 hexadecimal notation. Hexadecimal numbers must have an even number 608 of at least two digits. If multiple values or ranges are given they 609 all MUST be disjoint and MUST be in ascending order. If a value 610 restriction is applied to an already restricted type the new 611 restriction MUST be equal or more limiting, that is raising the lower 612 bounds, reducing the upper bounds, removing explicit values or 613 ranges, or splitting ranges into multiple ranges with intermediate 614 gaps. 616 Value Examples: 618 015 // illegal leading zero 619 -123 // illegal negative value 620 0xabc // illegal hexadecimal value length 621 0x8080000000 // legal hexadecimal value 623 Restriction Examples: 625 Unsigned64 (1..10000000000) // legal range spec 626 Unsigned64 (5..10 | 2..3) // illegal ordering 628 3.8 Float32 630 The Float32 base type represents floating point values of single 631 precision as described by [IEEE754]. 633 Values of type Float32 may be denoted as a decimal fraction with an 634 optional exponent as known from many programming languages. See the 635 grammar rule `floatValue' of Appendix B for the detailed syntax. 636 Special values are `snan' (signaling Not-a-Number), `qnan' (quiet 637 Not-a-Number), `neginf' (negative infinity), and `posinf' (positive 638 infinity). Note that -0.0 and +0.0 are different floating point 639 values. 0.0 is equal to +0.0. 641 When defining a type derived (directly or indirectly) from the 642 Float32 base type, the set of possible values may be restricted by 643 appending a list of ranges or explicit values, separated by pipe `|' 644 characters and the whole list enclosed in parenthesis. A range 645 consists of a lower bound, two consecutive dots `..' and an upper 646 bound. If multiple values or ranges are given they all MUST be 647 disjoint and MUST be in ascending order. If a value restriction is 648 applied to an already restricted type the new restriction MUST be 649 equal or more limiting, that is raising the lower bounds, reducing 650 the upper bounds, removing explicit values or ranges, or splitting 651 ranges into multiple ranges with intermediate gaps. The special 652 values `snan', `qnan', `neginf', and `posinf' must be explicitly 653 listed in restrictions if they shall be included, where `snan' and 654 `qnan' cannot be used in ranges. 656 Note that encoding is not subject to this specification. It has to 657 be described by protocols that transport objects of type Float32. 658 Note also that most floating point encodings disallow the 659 representation of many values that can be written as decimal 660 fractions as used in SMIng for human readability. Therefore, 661 explicit values in floating point type restrictions should be handled 662 with care. 664 Value Examples: 666 00.1 // illegal leading zero 667 3.1415 // legal value 668 -2.5E+3 // legal negative exponential value 670 Restriction Examples: 672 Float32 (-1.0..1.0) // legal range spec 673 Float32 (1 | 3.3 | 5) // legal, probably unrepresentable 3.3 674 Float32 (neginf..-0.0) // legal range spec 675 Float32 (-10.0..10.0 | 0) // illegal overlapping 677 3.9 Float64 679 The Float64 base type represents floating point values of double 680 precision as described by [IEEE754]. 682 Values of type Float64 may be denoted as a decimal fraction with an 683 optional exponent as known from many programming languages. See the 684 grammar rule `floatValue' of Appendix B for the detailed syntax. 685 Special values are `snan' (signaling Not-a-Number), `qnan' (quiet 686 Not-a-Number), `neginf' (negative infinity), and `posinf' (positive 687 infinity). Note that -0.0 and +0.0 are different floating point 688 values. 0.0 is equal to +0.0. 690 When defining a type derived (directly or indirectly) from the 691 Float64 base type, the set of possible values may be restricted by 692 appending a list of ranges or explicit values, separated by pipe `|' 693 characters and the whole list enclosed in parenthesis. A range 694 consists of a lower bound, two consecutive dots `..' and an upper 695 bound. If multiple values or ranges are given they all MUST be 696 disjoint and MUST be in ascending order. If a value restriction is 697 applied to an already restricted type the new restriction MUST be 698 equal or more limiting, that is raising the lower bounds, reducing 699 the upper bounds, removing explicit values or ranges, or splitting 700 ranges into multiple ranges with intermediate gaps. The special 701 values `snan', `qnan', `neginf', and `posinf' must be explicitly 702 listed in restrictions if they shall be included, where `snan' and 703 `qnan' cannot be used in ranges. 705 Note that encoding is not subject to this specification. It has to 706 be described by protocols that transport objects of type Float64. 707 Note also that most floating point encodings disallow the 708 representation of many values that can be written as decimal 709 fractions as used in SMIng for human readability. Therefore, 710 explicit values in floating point type restrictions should be handled 711 with care. 713 Value Examples: 715 00.1 // illegal leading zero 716 3.1415 // legal value 717 -2.5E+3 // legal negative exponential value 719 Restriction Examples: 721 Float64 (-1.0..1.0) // legal range spec 722 Float64 (1 | 3.3 | 5) // legal, probably unrepresentable 3.3 723 Float64 (neginf..-0.0) // legal range spec 724 Float64 (-10.0..10.0 | 0) // illegal overlapping 726 3.10 Float128 728 The Float128 base type represents floating point values of quadruple 729 precision as described by [IEEE754]. 731 Values of type Float128 may be denoted as a decimal fraction with an 732 optional exponent as known from many programming languages. See the 733 grammar rule `floatValue' of Appendix B for the detailed syntax. 734 Special values are `snan' (signaling Not-a-Number), `qnan' (quiet 735 Not-a-Number), `neginf' (negative infinity), and `posinf' (positive 736 infinity). Note that -0.0 and +0.0 are different floating point 737 values. 0.0 is equal to +0.0. 739 When defining a type derived (directly or indirectly) from the 740 Float128 base type, the set of possible values may be restricted by 741 appending a list of ranges or explicit values, separated by pipe `|' 742 characters and the whole list enclosed in parenthesis. A range 743 consists of a lower bound, two consecutive dots `..' and an upper 744 bound. If multiple values or ranges are given they all MUST be 745 disjoint and MUST be in ascending order. If a value restriction is 746 applied to an already restricted type the new restriction MUST be 747 equal or more limiting, that is raising the lower bounds, reducing 748 the upper bounds, removing explicit values or ranges, or splitting 749 ranges into multiple ranges with intermediate gaps. The special 750 values `snan', `qnan', `neginf', and `posinf' must be explicitly 751 listed in restrictions if they shall be included, where `snan' and 752 `qnan' cannot be used in ranges. 754 Note that encoding is not subject to this specification. It has to 755 be described by protocols that transport objects of type Float128. 756 Note also that most floating point encodings disallow the 757 representation of many values that can be written as decimal 758 fractions as used in SMIng for human readability. Therefore, 759 explicit values in floating point type restrictions should be handled 760 with care. 762 Value Examples: 764 00.1 // illegal leading zero 765 3.1415 // legal value 766 -2.5E+3 // legal negative exponential value 768 Restriction Examples: 770 Float128 (-1.0..1.0) // legal range spec 771 Float128 (1 | 3.3 | 5) // legal, probably unrepresentable 3.3 772 Float128 (neginf..-0.0) // legal range spec 773 Float128 (-10.0..10.0 | 0) // illegal overlapping 775 3.11 Enumeration 777 The Enumeration base type represents values from a set of integers in 778 the range between -2^31 (-2147483648) and 2^31-1 (2147483647), where 779 each value has an assigned name. The list of those named numbers has 780 to be comma-separated, enclosed in parenthesis and appended to the 781 `Enumeration' keyword. Each named number is denoted by its 782 lower-case identifier followed by the assigned integer value, denoted 783 as a decimal or `0x'-prefixed hexadecimal number, enclosed in 784 parenthesis. Hexadecimal numbers must have an even number of at 785 least two digits. Every name and every number in an enumeration type 786 MUST be unique. It is RECOMMENDED that values are positive and start 787 at 1 and be numbered contiguously. All named numbers MUST be given 788 in ascending order. 790 Values of enumeration types may be denoted as decimal or 791 `0x'-prefixed hexadecimal numbers or preferably as their assigned 792 names. Hexadecimal numbers must have an even number of at least two 793 digits. 795 When types are derived (directly or indirectly) from an enumeration 796 type, the set of named numbers may be equal or restricted by removing 797 one or more named numbers. But no named numbers may be added or 798 changed regarding its name, value, or both. 800 Type and Value Examples: 802 Enumeration (up(1), down(2), testing(3)) 803 Enumeration (down(2), up(1)) // illegal order 805 0 // legal (though not recommended) value 806 up // legal value given by name 807 2 // legal value given by number 809 3.12 Bits 811 The Bits base type represents bit sets. That is, a Bits value is a 812 set of flags identified by small integer numbers starting at 0. Each 813 bit number has an assigned name. The list of those named numbers has 814 to be comma-separated, enclosed in parenthesis and appended to the 815 `Bits' keyword. Each named number is denoted by its lower-case 816 identifier followed by the assigned integer value, denoted as a 817 decimal or `0x'-prefixed hexadecimal number, enclosed in parenthesis. 818 Hexadecimal numbers must have an even number of at least two digits. 819 Every name and every number in a bits type MUST be unique. It is 820 RECOMMENDED that numbers start at 0 and be numbered contiguously. 821 Negative numbers are forbidden. All named numbers MUST be given in 822 ascending order. 824 Values of bits types may be denoted as a comma-separated list of 825 decimal or `0x'-prefixed hexadecimal numbers or preferably their 826 assigned names enclosed in parenthesis. Hexadecimal numbers must 827 have an even number of at least two digits. There MUST NOT be any 828 element (by name or number) listed more than once. Elements MUST be 829 listed in ascending order. 831 When defining a type derived (directly or indirectly) from a bits 832 type, the set of named numbers may be restricted by removing one or 833 more named numbers. But no named numbers may be added or changed 834 regarding its name, value, or both. 836 Type and Value Examples: 838 Bits (readable(0), writeable(1), executable(2)) 839 Bits (writeable(1), readable(0) // illegal order 841 () // legal empty value 842 (readable, writeable, 2) // legal value 843 (0, readable, executable) // illegal, readable(0) appears twice 844 (writeable, 4) // illegal, element 4 out of range 846 3.13 Display Formats 848 Attribute definitions and type definitions allow the specification of 849 a format to be used, when a value of that attribute or an attribute 850 of that type is displayed. Format specifications are represented as 851 textual data. 853 When the attribute or type has an underlying base type of Integer32, 854 Integer64, Unsigned32, or Unsigned64, the format consists of an 855 integer-format specification, containing two parts. The first part 856 is a single character suggesting a display format, either: `x' for 857 hexadecimal, or `d' for decimal, or `o' for octal, or `b' for binary. 858 For all types, when rendering the value, leading zeros are omitted, 859 and for negative values, a minus sign is rendered immediately before 860 the digits. The second part is always omitted for `x', `o' and `b', 861 and need not be present for `d'. If present, the second part starts 862 with a hyphen and is followed by a decimal number, which defines the 863 implied decimal point when rendering the value. For example `d-2' 864 suggests that a value of 1234 be rendered as `12.34'. 866 When the attribute or type has an underlying base type of 867 OctetString, the format consists of one or more octet-format 868 specifications. Each specification consists of five parts, with each 869 part using and removing zero or more of the next octets from the 870 value and producing the next zero or more characters to be displayed. 871 The octets within the value are processed in order of significance, 872 most significant first. 874 The five parts of a octet-format specification are: 876 1. the (optional) repeat indicator; if present, this part is a `*', 877 and indicates that the current octet of the value is to be used 878 as the repeat count. The repeat count is an unsigned integer 879 (which may be zero) which specifies how many times the remainder 880 of this octet-format specification should be successively 881 applied. If the repeat indicator is not present, the repeat 882 count is one. 884 2. the octet length: one or more decimal digits specifying the 885 number of octets of the value to be used and formatted by this 886 octet-specification. Note that the octet length can be zero. If 887 less than this number of octets remain in the value, then the 888 lesser number of octets are used. 890 3. the display format, either: `x' for hexadecimal, `d' for decimal, 891 `o' for octal, `a' for ASCII, or `t' for UTF-8 [RFC2279]. If the 892 octet length part is greater than one, and the display format 893 part refers to a numeric format, then network byte-ordering 894 (big-endian encoding) is used interpreting the octets in the 895 value. The octets processed by the `t' display format do not 896 necessarily form an integral number of UTF-8 characters. 897 Trailing octets which do not form a valid UTF-8 encoded character 898 are discarded. 900 4. the (optional) display separator character; if present, this part 901 is a single character which is produced for display after each 902 application of this octet-specification; however, this character 903 is not produced for display if it would be immediately followed 904 by the display of the repeat terminator character for this octet 905 specification. This character can be any character other than a 906 decimal digit and a `*'. 908 5. the (optional) repeat terminator character, which can be present 909 only if the display separator character is present and this octet 910 specification begins with a repeat indicator; if present, this 911 part is a single character which is produced after all the zero 912 or more repeated applications (as given by the repeat count) of 913 this octet specification. This character can be any character 914 other than a decimal digit and a `*'. 916 Output of a display separator character or a repeat terminator 917 character is suppressed if it would occur as the last character of 918 the display. 920 If the octets of the value are exhausted before all the octet format 921 specification have been used, then the excess specifications are 922 ignored. If additional octets remain in the value after interpreting 923 all the octet format specifications, then the last octet format 924 specification is re-interpreted to process the additional octets, 925 until no octets remain in the value. 927 Note that for some types no format specifications are defined. For 928 derived types and attributes that are based on such types, format 929 specifications SHOULD be omitted. Implementations MUST ignore format 930 specifications they cannot interpret. Also note that the SMIng 931 grammar (Appendix B) does not specify the syntax of format 932 specifications. 934 Display Format Examples: 936 Base Type Format Example Value Rendered Value 937 ----------- ------------------- ---------------- ----------------- 938 OctetString 255a "Hello World." Hello World. 939 OctetString 1x: "Hello!" 48:65:6c:6c:6f:21 940 OctetString 1d:1d:1d.1d,1a1d:1d 0x0d1e0f002d0400 13:30:15.0,-4:0 941 OctetString 1d.1d.1d.1d/2d 0x0a0000010400 10.0.0.1/1024 942 OctetString *1x:/1x: 0x02aabbccddee aa:bb/cc:dd:ee 943 Integer32 d-2 1234 12.34 945 4. The SMIng File Structure 947 The topmost container of SMIng information is a file. An SMIng file 948 may contain zero, one or more modules. It is RECOMMENDED to separate 949 modules into files named by their modules, where possible. However, 950 for dedicated purposes it may be reasonable to collect several 951 modules in a single file. 953 The top level SMIng construct is the `module' statement (Section 5) 954 that defines a single SMIng module. A module contains a sequence of 955 sections in an obligatory order with different kinds of definitions. 956 Whether these sections contain statements or remain empty mainly 957 depends on the purpose of the module. 959 4.1 Comments 961 Comments can be included at any position in an SMIng file, except 962 between the characters of a single token like those of a quoted 963 string. However, it is RECOMMENDED that all substantive descriptions 964 be placed within an appropriate description clause, so that the 965 information is available to SMIng parsers. 967 Comments commence with a pair of adjacent slashes `//' and end at the 968 end of the line. 970 4.2 Textual Data 972 Some statements, namely `organization', `contact', `description', 973 `reference', `abnf', `format', and `units', get a textual argument. 974 This text, as well as representations of OctetString values, have to 975 be enclosed in double quotes. They may contain arbitrary characters 976 with the following exceptional encoding rules: 978 A backslash character introduces a special character, which depends 979 on the character that immediately follows the backslash: 981 \n new line 982 \t a tab character 983 \" a double quote 984 \\ a single backslash 986 If the text contains a line break followed by whitespace which is 987 used to indent the text according to the layout in the SMIng file, 988 this prefixing whitespace is stripped from the text. 990 4.3 Statements and Arguments 992 SMIng has a very small set of basic grammar rules based on the 993 concept of statements. Each statement starts with a lower-case 994 keyword identifying the statement followed by a number (possibly 995 zero) of arguments. An argument may be quoted text, an identifier, a 996 value of any base type, a list of identifiers enclosed in parenthesis 997 `( )' or a statement block enclosed in curly braces `{ }'. Since 998 statement blocks are valid arguments, it is possible to nest 999 statement sequences. Each statement is terminated by a semicolon 1000 `;'. 1002 The core set of statements may be extended using the SMIng 1003 `extension' statement. See Section 6 and Section 11 for details. 1005 At places where a statement is expected, but an unknown lower-case 1006 word is read, those statements MUST be skipped up to the proper 1007 semicolon, including nested statement blocks. 1009 5. The module Statement 1011 The `module' statement is used as a container of all definitions of a 1012 single SMIng module. It gets two arguments: an upper-case module 1013 name and a statement block that contains mandatory and optional 1014 statements and sections of statements in an obligatory order: 1016 module { 1018 1019 1020 1021 1022 1023 1025 1027 1029 1031 1033 }; 1035 The optional `import' statements (Section 5.1) are followed by the 1036 mandatory `organization' (Section 5.2), `contact' (Section 5.3), and 1037 `description' (Section 5.4) statements and the optional `reference' 1038 statement (Section 5.5), which in turn are followed by at least one 1039 mandatory `revision' statement (Section 5.6). The part up to this 1040 point defines the module's meta information, i.e., information that 1041 describes the whole module but which does not define any items used 1042 by applications in the first instance. This part of a module is 1043 followed by its main definitions, namely SMIng extensions (Section 1044 6), derived types (Section 7), identities (Section 8), and classes 1045 (Section 9). 1047 See the `moduleStatement' rule of the SMIng grammar (Appendix B) for 1048 the formal syntax of the `module' statement. 1050 5.1 The module's import Statement 1052 The optional module's `import' statement is used to import 1053 identifiers from external modules into the local module's namespace. 1054 It gets two arguments: the name of the external module and a 1055 comma-separated list of one or more identifiers to be imported 1056 enclosed in parenthesis. 1058 Multiple `import' statements for the same module but with disjoint 1059 lists of identifiers are allowed, though NOT RECOMMENDED. Anyhow, 1060 the same identifier from the same module MUST NOT be imported 1061 multiple times. To import identifiers with the same name from 1062 different modules might be necessary and is allowed. To distinguish 1063 them in the local module, they have to be referred by qualified 1064 names. It is NOT RECOMMENDED to import identifiers not used in the 1065 local module. 1067 See the `importStatement' rule of the SMIng grammar (Appendix B) for 1068 the formal syntax of the `import' statement. 1070 5.2 The module's organization Statement 1072 The module's `organization' statement, which must be present, gets 1073 one argument which is used to specify a textual description of the 1074 organization(s) under whose auspices this module was developed. 1076 5.3 The module's contact Statement 1078 The module's `contact' statement, which must be present, gets one 1079 argument which is used to specify the name, postal address, telephone 1080 number, and electronic mail address of the person to whom technical 1081 queries concerning this module should be sent. 1083 5.4 The module's description Statement 1085 The module's `description' statement, which must be present, gets one 1086 argument which is used to specify a high-level textual description of 1087 the contents of this module. 1089 5.5 The module's reference Statement 1091 The module's `reference' statement, which need not be present, gets 1092 one argument which is used to specify a textual cross-reference to 1093 some other document, either another module which defines related 1094 management information, or some other document which provides 1095 additional information relevant to this module. 1097 5.6 The module's revision Statement 1099 The module's `revision' statement is repeatedly used to specify the 1100 editorial revisions of the module, including the initial revision. 1101 It gets one argument which is a statement block that holds detailed 1102 information in an obligatory order. A module MUST have at least one 1103 initial `revision' statement. For every editorial change, a new one 1104 MUST be added in front of the revisions sequence, so that all 1105 revisions are in reverse chronological order. 1107 See the `revisionStatement' rule of the SMIng grammar (Appendix B) 1108 for the formal syntax of the `revision' statement. 1110 5.6.1 The revision's date Statement 1111 The revision's `date' statement, which must be present, gets one 1112 argument which is used to specify the date and time of the revision 1113 in the format `YYYY-MM-DD HH:MM' or `YYYY-MM-DD' which implies the 1114 time `00:00'. The time is always given in UTC. 1116 See the `date' rule of the SMIng grammar (Appendix B) for the formal 1117 syntax of the revision's `date' statement. 1119 5.6.2 The revision's description Statement 1121 The revision's `description' statement, which must be present, gets 1122 one argument which is used to specify a high-level textual 1123 description of the revision. 1125 5.7 Usage Example 1127 Consider how a skeletal module might be constructed: 1129 module ACME-MIB { 1131 import NMRG-SMING (DisplayString); 1133 organization 1134 "IRTF Network Management Research Group (NMRG)"; 1136 contact "IRTF Network Management Research Group (NMRG) 1137 http://www.ibr.cs.tu-bs.de/projects/nmrg/ 1139 Joe L. User 1141 ACME, Inc. 1142 42 Anywhere Drive 1143 Nowhere, CA 95134 1144 USA 1146 Phone: +1 800 555 0815 1147 EMail: joe@acme.example.com"; 1149 description 1150 "The module for entities implementing the ACME protocol. 1152 Copyright (C) The Internet Society (2003). 1153 All Rights Reserved. 1154 This version of this MIB module is part of RFC xxx1, 1155 see the RFC itself for legal notices."; 1157 revision { 1158 date "2003-12-16"; 1159 description 1160 "Initial revision, published as RFC xxx1."; 1161 }; 1163 // ... further definitions ... 1165 }; // end of module ACME-MIB. 1167 6. The extension Statement 1169 The `extension' statement is used to define new statements to be used 1170 in the local module following this extension statement definition or 1171 in external modules that may import this extension statement 1172 definition. The `extension' statement gets two arguments: a 1173 lower-case extension statement identifier and a statement block that 1174 holds detailed extension information in an obligatory order. 1176 Extension statement identifiers SHOULD NOT contain any upper-case 1177 characters. 1179 Note that the SMIng extension feature does not allow to formally 1180 specify the context, argument syntax and semantics of an extension. 1181 Its only purpose is to declare the existence of an extension and to 1182 allow a unique reference to an extension. See Section 11 for 1183 detailed information on extensions and [RFCxxx2] for mappings of 1184 SMIng definitions to SNMP which is formally defined as an extension. 1186 See the `extensionStatement' rule of the SMIng grammar (Appendix B) 1187 for the formal syntax of the `extension' statement. 1189 6.1 The extension's status Statement 1191 The extension's `status' statement, which must be present, gets one 1192 argument which is used to specify whether this extension definition 1193 is current or historic. The value `current' means that the 1194 definition is current and valid. The value `obsolete' means the 1195 definition is obsolete and should not be implemented and/or can be 1196 removed if previously implemented. While the value `deprecated' also 1197 indicates an obsolete definition, it permits new/continued 1198 implementation in order to foster interoperability with older/ 1199 existing implementations. 1201 6.2 The extension's description Statement 1203 The extension's `description' statement, which must be present, gets 1204 one argument which is used to specify a high-level textual 1205 description of the extension statement. 1207 It is RECOMMENDED to include information on the extension's context, 1208 its semantics, and implementation conditions. See also Section 11. 1210 6.3 The extension's reference Statement 1212 The extension's `reference' statement, which need not be present, 1213 gets one argument which is used to specify a textual cross-reference 1214 to some other document, either another module which defines related 1215 extension definitions, or some other document which provides 1216 additional information relevant to this extension. 1218 6.4 The extension's abnf Statement 1220 The extension's `abnf' statement, which need not be present, gets one 1221 argument which is used to specify a formal ABNF [RFC2234] grammar 1222 definition of the extension. This grammar can reference rule names 1223 from the core SMIng grammar (Appendix B). 1225 Note that the `abnf' statement should contain only pure ABNF and no 1226 additional text, though comments prefixed by semicolon are allowed 1227 but should probably be moved to the description statement. Note that 1228 double quotes within the ABNF grammar have to be represented as `\"' 1229 according to Section 4.2. 1231 6.5 Usage Example 1233 extension severity { 1234 status current; 1235 description 1236 "The optional severity extension statement can only 1237 be applied to the statement block of an SMIng class' 1238 event definition. If it is present it denotes the 1239 severity level of the event in a range from 0 1240 (emergency) to 7 (debug)."; 1241 abnf 1242 "severityStatement = severityKeyword sep number optsep \";\" 1243 severityKeyword = \"severity\""; 1244 }; 1246 7. The typedef Statement 1248 The `typedef' statement is used to define new data types to be used 1249 in the local module or in external modules. It gets two arguments: 1250 an upper-case type identifier and a statement block that holds 1251 detailed type information in an obligatory order. 1253 Type identifiers SHOULD NOT consist of all upper-case characters and 1254 SHOULD NOT contain hyphens. 1256 See the `typedefStatement' rule of the SMIng grammar (Appendix B) for 1257 the formal syntax of the `typedef' statement. 1259 7.1 The typedef's type Statement 1261 The typedef's `type' statement, which must be present, gets one 1262 argument which is used to specify the type from which this type is 1263 derived. Optionally, type restrictions may be applied to the new 1264 type by appending subtyping information according to the rules of the 1265 base type. See Section 3 for SMIng base types and their type 1266 restrictions. 1268 7.2 The typedef's default Statement 1270 The typedef's `default' statement, which need not be present, gets 1271 one argument which is used to specify an acceptable default value for 1272 attributes of this type. A default value may be used when an 1273 attribute instance is created. That is, the value is a "hint" to 1274 implementors. 1276 The value of the `default' statement must, of course, correspond to 1277 the (probably restricted) type specified in the typedef's `type' 1278 statement. 1280 The default value of a type may be overwritten by a default value of 1281 an attribute of this type. 1283 Note that for some types, default values make no sense. 1285 7.3 The typedef's format Statement 1287 The typedef's `format' statement, which need not be present, gets one 1288 argument which is used to give a hint as to how the value of an 1289 instance of an attribute of this type might be displayed. See 1290 Section 3.13 for a description of format specifications. 1292 If no format is specified, it is inherited from the type given in the 1293 `type' statement. On the other hand, the format specification of a 1294 type may be semantically refined by a format specification of an 1295 attribute of this type. 1297 7.4 The typedef's units Statement 1299 The typedef's `units' statement, which need not be present, gets one 1300 argument which is used to specify a textual definition of the units 1301 associated with attributes of this type. 1303 If no units are specified, they are inherited from the type given in 1304 the `type' statement. On the other hand, the units specification of 1305 a type may be semantically refined by a units specification of an 1306 attribute of this type. 1308 The units specification has to be appropriate for values displayed 1309 according to the typedef's format specification, if present. E.g., 1310 if the type defines frequency values of type Unsigned64 measured in 1311 thousands of Hertz, the format specification should be `d-3' and the 1312 units specification should be `Hertz' or `Hz'. If the format 1313 specification would be omitted, the units specification should be 1314 `Milli-Hertz' or `mHz'. Authors of SMIng modules should pay 1315 attention to keep format and units specifications synced. 1316 Application implementors MUST NOT implement units specifications 1317 without implementing format specifications. 1319 7.5 The typedef's status Statement 1320 The typedef's `status' statement, which must be present, gets one 1321 argument which is used to specify whether this type definition is 1322 current or historic. The value `current' means that the definition 1323 is current and valid. The value `obsolete' means the definition is 1324 obsolete and should not be implemented and/or can be removed if 1325 previously implemented. While the value `deprecated' also indicates 1326 an obsolete definition, it permits new/continued implementation in 1327 order to foster interoperability with older/existing implementations. 1329 Derived types SHOULD NOT be defined as `current' if their underlying 1330 type is `deprecated' or `obsolete'. Similarly, they SHOULD NOT be 1331 defined as `deprecated' if their underlying type is `obsolete'. 1332 Nevertheless, subsequent revisions of the underlying type cannot be 1333 avoided, but SHOULD be taken into account in subsequent revisions of 1334 the local module. 1336 7.6 The typedef's description Statement 1338 The typedef's `description' statement, which must be present, gets 1339 one argument which is used to specify a high-level textual 1340 description of the newly defined type. 1342 It is RECOMMENDED to include all semantic definitions necessary for 1343 implementation, and to embody any information which would otherwise 1344 be communicated in any commentary annotations associated with this 1345 type definition. 1347 7.7 The typedef's reference Statement 1349 The typedef's `reference' statement, which need not be present, gets 1350 one argument which is used to specify a textual cross-reference to 1351 some other document, either another module which defines related type 1352 definitions, or some other document which provides additional 1353 information relevant to this type definition. 1355 7.8 Usage Examples 1357 typedef RptrOperStatus { 1358 type Enumeration (other(1), ok(2), rptrFailure(3), 1359 groupFailure(4), portFailure(5), 1360 generalFailure(6)); 1361 default other; // undefined by default. 1362 status deprecated; 1363 description 1364 "A type to indicate the operational state 1365 of a repeater."; 1366 reference 1367 "[IEEE 802.3 Mgt], 30.4.1.1.5, aRepeaterHealthState."; 1369 }; 1371 typedef SnmpTransportDomain { 1372 type Pointer (snmpTransportDomain); 1373 status current; 1374 description 1375 "A pointer to an SNMP transport domain identity."; 1376 }; 1378 typedef DateAndTime { 1379 type OctetString (8 | 11); 1380 format "2d-1d-1d,1d:1d:1d.1d,1a1d:1d"; 1381 status current; 1382 description 1383 "A date-time specification. 1384 ... 1385 Note that if only local time is known, then timezone 1386 information (fields 8-10) is not present."; 1387 reference 1388 "RFC 2579, SNMPv2-TC.DateAndTime."; 1389 }; 1391 typedef Frequency { 1392 type Unsigned64; 1393 format "d-3" 1394 units "Hertz"; 1395 status current; 1396 description 1397 "A wide-range frequency specification measured 1398 in thousands of Hertz."; 1399 }; 1401 8. The identity Statement 1403 The `identity' statement is used to define a new abstract and untyped 1404 identity. Its only purpose is to denote its name, semantics and 1405 existence. An identity can be defined either from scratch or derived 1406 from a parent identity. The `identity' statement gets the following 1407 two arguments: The first argument is a lower-case identity 1408 identifier. The second argument is a statement block that holds 1409 detailed identity information in an obligatory order. 1411 See the `identityStatement' rule of the SMIng grammar (Appendix B) 1412 for the formal syntax of the `identity' statement. 1414 8.1 The identity's parent Statement 1416 The identity's `parent' statement must be present for a derived 1417 identity and must be absent for an identity defined from scratch. It 1418 gets one argument which is used to specify the parent identity from 1419 which this identity shall be derived. 1421 8.2 The identity's status Statement 1423 The identity's `status' statement, which must be present, gets one 1424 argument which is used to specify whether this identity definition is 1425 current or historic. The value `current' means that the definition 1426 is current and valid. The value `obsolete' means the definition is 1427 obsolete and should not be implemented and/or can be removed if 1428 previously implemented. While the value `deprecated' also indicates 1429 an obsolete definition, it permits new/continued implementation in 1430 order to foster interoperability with older/existing implementations. 1432 Derived identities SHOULD NOT be defined as `current' if their parent 1433 identity is `deprecated' or `obsolete'. Similarly, they SHOULD NOT 1434 be defined as `deprecated' if their parent identity is `obsolete'. 1435 Nevertheless, subsequent revisions of the parent identity cannot be 1436 avoided, but SHOULD be taken into account in subsequent revisions of 1437 the local module. 1439 8.3 The identity' description Statement 1441 The identity's `description' statement, which must be present, gets 1442 one argument which is used to specify a high-level textual 1443 description of the newly defined identity. 1445 It is RECOMMENDED to include all semantic definitions necessary for 1446 implementation, and to embody any information which would otherwise 1447 be communicated in any commentary annotations associated with this 1448 identity definition. 1450 8.4 The identity's reference Statement 1452 The identity's `reference' statement, which need not be present, gets 1453 one argument which is used to specify a textual cross-reference to 1454 some other document, either another module which defines related 1455 identity definitions, or some other document which provides 1456 additional information relevant to this identity definition. 1458 8.5 Usage Examples 1460 identity null { 1461 status current; 1462 description 1463 "An identity used to represent null pointer values."; 1464 }; 1466 identity snmpTransportDomain { 1467 status current; 1468 description 1469 "A generic SNMP transport domain identity."; 1470 }; 1472 identity snmpUDPDomain { 1473 parent snmpTransportDomain; 1474 status current; 1475 description 1476 "The SNMP over UDP transport domain."; 1477 }; 1479 9. The class Statement 1481 The `class' statement is used to define a new class, that represents 1482 a container of related attributes and events (Section 9.2, Section 1483 9.4). A class can be defined either from scratch or derived from a 1484 parent class. A derived class inherits all attributes and events of 1485 the parent class and can be extended by additional attributes and 1486 events. 1488 The `class' statement gets the following two arguments: The first 1489 argument is an upper-case class identifier. The second argument is a 1490 statement block that holds detailed class information in an 1491 obligatory order. 1493 See the `classStatement' rule of the SMIng grammar (Appendix B) for 1494 the formal syntax of the `class' statement. 1496 9.1 The class' extends Statement 1498 The class' `extends' statement must be present for a class derived 1499 from a parent class and must be absent for a class defined from 1500 scratch. It gets one argument which is used to specify the parent 1501 class from which this class shall be derived. 1503 9.2 The class' attribute Statement 1505 The class' `attribute' statement, which can be present zero, one or 1506 multiple times, gets two arguments: the attribute name and a 1507 statement block that holds detailed attribute information in an 1508 obligatory order. 1510 9.2.1 The attribute's type Statement 1512 The attribute's `type' statement must be present. It gets at least 1513 one argument which is used to specify the type of the attribute: 1514 either a type name or a class name. In case of a type name, it may 1515 be restricted by a second argument according to the restriction rules 1516 described in Section 3. 1518 9.2.2 The attribute's access Statement 1520 The attribute's `access' statement must be present for attributes 1521 typed by a base type or derived type, and must be absent for 1522 attributes typed by a class. It gets one argument which is used to 1523 specify whether it makes sense to read and/or write an instance of 1524 the attribute, or to include its value in an event. This is the 1525 maximal level of access for the attribute. This maximal level of 1526 access is independent of any administrative authorization policy. 1528 The value `readwrite' indicates that read and write access makes 1529 sense. The value `readonly' indicates that read access makes sense, 1530 but write access is never possible. The value `eventonly' indicates 1531 an object which is accessible only via an event. 1533 These values are ordered, from least to greatest access level: 1534 `eventonly', `readonly', `readwrite'. 1536 9.2.3 The attribute's default Statement 1538 The attribute's `default' statement need not be present for 1539 attributes typed by a base type or derived type, and must be absent 1540 for attributes typed by a class. It gets one argument which is used 1541 to specify an acceptable default value for this attribute. A default 1542 value may be used when an attribute instance is created. That is, 1543 the value is a "hint" to implementors. 1545 The value of the `default' statement must, of course, correspond to 1546 the (probably restricted) type specified in the attribute's `type' 1547 statement. 1549 The attribute's default value overrides the default value of the 1550 underlying type definition if both are present. 1552 9.2.4 The attribute's format Statement 1553 The attribute's `format' statement need not be present for attributes 1554 typed by a base type or derived type, and must be absent for 1555 attributes typed by a class. It gets one argument which is used to 1556 give a hint as to how the value of an instance of this attribute 1557 might be displayed. See Section 3.13 for a description of format 1558 specifications. 1560 The attribute's format specification overrides the format 1561 specification of the underlying type definition if both are present. 1563 9.2.5 The attribute's units Statement 1565 The attribute's `units' statement need not be present for attributes 1566 typed by a base type or derived type, and must be absent for 1567 attributes typed by a class. It gets one argument which is used to 1568 specify a textual definition of the units associated with this 1569 attribute. 1571 The attribute's units specification overrides the units specification 1572 of the underlying type definition if both are present. 1574 The units specification has to be appropriate for values displayed 1575 according to the attribute's format specification if present. E.g., 1576 if the attribute represents a frequency value of type Unsigned64 1577 measured in thousands of Hertz, the format specification should be 1578 `d-3' and the units specification should be `Hertz' or `Hz'. If the 1579 format specification would be omitted the units specification should 1580 be `Milli-Hertz' or `mHz'. Authors of SMIng modules should pay 1581 attention to keep format and units specifications of type and 1582 attribute definitions synced. Application implementors MUST NOT 1583 implement units specifications without implementing format 1584 specifications. 1586 9.2.6 The attribute's status Statement 1588 The attribute's `status' statement must be present. It gets one 1589 argument which is used to specify whether this attribute definition 1590 is current or historic. The value `current' means that the 1591 definition is current and valid. The value `obsolete' means the 1592 definition is obsolete and should not be implemented and/or can be 1593 removed if previously implemented. While the value `deprecated' also 1594 indicates an obsolete definition, it permits new/continued 1595 implementation in order to foster interoperability with older/ 1596 existing implementations. 1598 Attributes SHOULD NOT be defined as `current' if their type or their 1599 containing class is `deprecated' or `obsolete'. Similarly, they 1600 SHOULD NOT be defined as `deprecated' if their type or their 1601 containting class is `obsolete'. Nevertheless, subsequent revisions 1602 of used type definition cannot be avoided, but SHOULD be taken into 1603 account in subsequent revisions of the local module. 1605 9.2.7 The attribute's description Statement 1607 The attribute's `description' statement, which must be present, gets 1608 one argument which is used to specify a high-level textual 1609 description of this attribute. 1611 It is RECOMMENDED to include all semantic definitions necessary for 1612 the implementation of this attribute. 1614 9.2.8 The attribute's reference Statement 1616 The attribute's `reference' statement, which need not be present, 1617 gets one argument which is used to specify a textual cross-reference 1618 to some other document, either another module which defines related 1619 attribute definitions, or some other document which provides 1620 additional information relevant to this attribute definition. 1622 9.3 The class' unique Statement 1624 The class' `unique' statement, which need not be present, gets one 1625 argument that specifies a comma-separated list of attributes of this 1626 class, enclosed in parenthesis. If present, this list of attributes 1627 makes up a unique identification of all possible instances of this 1628 class. It can be used as a unique key in underlying protocols. 1630 If the list is empty the class should be regarded as a scalar class 1631 with only a single instance. 1633 If the `unique' statement is not present the class is not meant to be 1634 instantiated directly, but just to be contained in other classes or 1635 to be the parent class of other refining classes. 1637 If present, the attribute list MUST NOT contain any attribute more 1638 than once and the attributes should be ordered where appropriate so 1639 that the attributes that are most significant in most situations 1640 appear first. 1642 9.4 The class' event Statement 1644 The class' `event' statement is used to define an event related to an 1645 instance of this class that can occur asynchronously. It gets two 1646 arguments: a lower-case event identifier and a statement block that 1647 holds detailed information in an obligatory order. 1649 See the `eventStatement' rule of the SMIng grammar (Appendix B) for 1650 the formal syntax of the `event' statement. 1652 9.4.1 The event's status Statement 1654 The event's `status' statement, which must be present, gets one 1655 argument which is used to specify whether this event definition is 1656 current or historic. The value `current' means that the definition 1657 is current and valid. The value `obsolete' means the definition is 1658 obsolete and should not be implemented and/or can be removed if 1659 previously implemented. While the value `deprecated' also indicates 1660 an obsolete definition, it permits new/continued implementation in 1661 order to foster interoperability with older/existing implementations. 1663 9.4.2 The event's description Statement 1665 The event's `description' statement, which must be present, gets one 1666 argument which is used to specify a high-level textual description of 1667 this event. 1669 It is RECOMMENDED to include all semantic definitions necessary for 1670 the implementation of this event. In particular, it SHOULD be 1671 documented which instance of the class is associated with an event of 1672 this type. 1674 9.4.3 The event's reference Statement 1676 The event's `reference' statement, which need not be present, gets 1677 one argument which is used to specify a textual cross-reference to 1678 some other document, either another module which defines related 1679 event definitions, or some other document which provides additional 1680 information relevant to this event definition. 1682 9.5 The class' status Statement 1684 The class' `status' statement, which must be present, gets one 1685 argument which is used to specify whether this class definition is 1686 current or historic. The value `current' means that the definition 1687 is current and valid. The value `obsolete' means the definition is 1688 obsolete and should not be implemented and/or can be removed if 1689 previously implemented. While the value `deprecated' also indicates 1690 an obsolete definition, it permits new/continued implementation in 1691 order to foster interoperability with older/existing implementations. 1693 Derived classes SHOULD NOT be defined as `current' if their parent 1694 class is `deprecated' or `obsolete'. Similarly, they SHOULD NOT be 1695 defined as `deprecated' if their parent class is `obsolete'. 1696 Nevertheless, subsequent revisions of the parent class cannot be 1697 avoided, but SHOULD be taken into account in subsequent revisions of 1698 the local module. 1700 9.6 The class' description Statement 1702 The class' `description' statement, which must be present, gets one 1703 argument which is used to specify a high-level textual description of 1704 the newly defined class. 1706 It is RECOMMENDED to include all semantic definitions necessary for 1707 implementation, and to embody any information which would otherwise 1708 be communicated in any commentary annotations associated with this 1709 class definition. 1711 9.7 The class's reference Statement 1713 The class's `reference' statement, which need not be present, gets 1714 one argument which is used to specify a textual cross-reference to 1715 some other document, either another module which defines related 1716 class definitions, or some other document which provides additional 1717 information relevant to this class definition. 1719 9.8 Usage Example 1721 Consider how an event might be described that signals a status change 1722 of an interface: 1724 class Interface { 1725 // ... 1726 attribute speed { 1727 type Gauge32; 1728 access readonly; 1729 units "bps"; 1730 status current; 1731 description 1732 "An estimate of the interface's current bandwidth 1733 in bits per second."; 1734 }; 1735 // ... 1736 attribute adminStatus { 1737 type AdminStatus; 1738 access readwrite; 1739 status current; 1740 description 1741 "The desired state of the interface."; 1742 }; 1743 attribute operStatus { 1744 type OperStatus; 1745 access readonly; 1746 status current; 1747 description 1748 "The current operational state of the interface."; 1749 }; 1751 event linkDown { 1752 status current; 1753 description 1754 "A linkDown event signifies that the ifOperStatus 1755 attribute for this interface instance is about to 1756 enter the down state from some other state (but not 1757 from the notPresent state). This other state is 1758 indicated by the included value of ifOperStatus."; 1759 }; 1761 status current; 1762 description 1763 "A physical or logical network interface."; 1765 }; 1767 10. Extending a Module 1769 As experience is gained with a module, it may be desirable to revise 1770 that module. However, changes are not allowed if they have any 1771 potential to cause interoperability problems between an 1772 implementation using an original specification and an implementation 1773 using an updated specification(s). 1775 For any change, some statements near the top of the module MUST be 1776 updated to include information about the revision: specifically, a 1777 new `revision' statement (Section 5.6) must be included in front of 1778 the `revision' statements. Furthermore, any necessary changes MUST 1779 be applied to other statements, including the `organization' and 1780 `contact' statements (Section 5.2, Section 5.3). 1782 Note that any definition contained in a module is available to be 1783 imported by any other module, and is referenced in an `import' 1784 statement via the module name. Thus, a module name MUST NOT be 1785 changed. Specifically, the module name (e.g., `ACME-MIB' in the 1786 example of Section 5.7) MUST NOT be changed when revising a module 1787 (except to correct typographical errors), and definitions MUST NOT be 1788 moved from one module to another. 1790 Also note, that obsolete definitions MUST NOT be removed from modules 1791 since their identifiers may still be referenced by other modules. 1793 A definition may be revised in any of the following ways: 1795 o In `typedef' statement blocks, a `type' statement containing an 1796 `Enumeration' or `Bits' type may have new named numbers added. 1798 o In `typedef' statement blocks, the value of a `type' statement may 1799 be replaced by another type if the new type is derived (directly 1800 or indirectly) from the same base type, has the same set of 1801 values, and has identical semantics. 1803 o In `attribute' statements where the `type' sub-statement specifies 1804 a class, the class may be replaced by another class if the new 1805 class is derived (directly or indirectly) from the base class and 1806 both classes have identical semantics. 1808 o In `attribute' statements where the `type' sub-statement specifies 1809 a base type, a defined type, or an implicitly derived type (i.e. 1810 not a class), that type may be replaced by another type if the new 1811 type is derived (directly or indirectly) from the same base type, 1812 has the same set of values, and has identical semantics. 1814 o In any statement block, a `status' statement value of `current' 1815 may be revised as `deprecated' or `obsolete'. Similarly, a 1816 `status' statement value of `deprecated' may be revised as 1817 `obsolete'. When making such a change, the `description' 1818 statement SHOULD be updated to explain the rationale. 1820 o In `typedef' and `attribute' statement blocks, a `default' 1821 statement may be added or updated. 1823 o In `typedef' and `attribute' statement blocks, a `units' statement 1824 may be added. 1826 o A class may be augmented by adding new attributes. 1828 o In any statement block, clarifications and additional information 1829 may be included in the `description' statement. 1831 o In any statement block, a `reference' statement may be added or 1832 updated. 1834 o Entirely new extensions, types, identities, and classes may be 1835 defined, using previously unassigned identifiers. 1837 Otherwise, if the semantics of any previous definition are changed 1838 (i.e., if a non-editorial change is made to any definition other than 1839 those specifically allowed above), then this MUST be achieved by a 1840 new definition with a new identifier. In case of a class where the 1841 semantics of any attributes are changed, the new class can be defined 1842 by derivation from the old class and refining the changed attributes. 1844 Note that changing the identifier associated with an existing 1845 definition is considered a semantic change, as these strings may be 1846 used in an `import' statement. 1848 11. SMIng Language Extensibility 1850 While the core SMIng language has a well defined set of statements 1851 (Section 5 through Section 9.4) that are used to specify those 1852 aspects of management information commonly regarded as necessary 1853 without management protocol specific information, there may be 1854 further information, people wish to express. To describe additional 1855 information informally in description statements has the disadvantage 1856 that this information cannot be parsed by any program. 1858 SMIng allows modules to include statements that are unknown to a 1859 parser but fulfill some core grammar rules (Section 4.3). 1860 Furthermore, additional statements may be defined by the `extension' 1861 statement (Section 6). Extensions can be used in the local module or 1862 in other modules, that import the extension. This has some 1863 advantages: 1865 o A parser can differentiate between statements known as extensions 1866 and unknown statements. This enables the parser to complain about 1867 unknown statements, e.g. due to typos. 1869 o If an extension's definition contains a formal ABNF grammar 1870 definition and a parser is able to interpret this ABNF definition, 1871 this enables the parser also to complain about wrong usage of an 1872 extension. 1874 o Since, there might be some common need for extensions, there is a 1875 relatively high probability of extension name collisions 1876 originated by different organizations, as long as there is no 1877 standardized extension for that purpose. The requirement to 1878 explicitly import extension statements allows to distinguish those 1879 extensions. 1881 o The supported extensions of an SMIng implementation, e.g. an 1882 SMIng module compiler, can be clearly expressed. 1884 The only formal effect of an extension statement definition is to 1885 declare its existence and its status, and optionally its ABNF 1886 grammar. All additional aspects SHOULD be described in the 1887 `description' statement: 1889 o The detailed semantics of the new statement SHOULD be described. 1891 o The contexts in which the new statement can be used, SHOULD be 1892 described, e.g., a new statement may be designed to be used only 1893 in the statement block of a module, but not in other nested 1894 statement blocks. Others may be applicable in multiple contexts. 1895 In addition, the point in the sequence of an obligatory order of 1896 other statements, where the new statement may be inserted, might 1897 be prescribed. 1899 o The circumstances that make the new statement mandatory or 1900 optional SHOULD be described. 1902 o The syntax of the new statement SHOULD at least be described 1903 informally, if not supplied formally in an `abnf' statement. 1905 o It might be reasonable to give some suggestions under which 1906 conditions the implementation of the new statement is adequate and 1907 how it could be integrated into existent implementations. 1909 Some possible extension applications are: 1911 o The formal mapping of SMIng definitions into the SNMP [RFCxxx2] 1912 framework is defined as an SMIng extension. Other mappings may 1913 follow in the future. 1915 o Inlined annotations to definitions. E.g., a vendor may wish to 1916 describe additional information to class and attribute definitions 1917 in private modules. An example are severity levels of events in 1918 the statement block of an `event' statement. 1920 o Arbitrary annotations to external definitions. E.g., a vendor may 1921 wish to describe additional information to definitions in a 1922 "standard" module. This allows a vendor to implement "standard" 1923 modules as well as additional private features, without redundant 1924 module definitions, but on top of "standard" module definitions. 1926 12. Security Considerations 1928 This document defines a language with which to write and read 1929 descriptions of management information. The language itself has no 1930 security impact on the Internet. 1932 13. Acknowledgements 1934 Since SMIng started as a close successor of SMIv2, some paragraphs 1935 and phrases are directly taken from the SMIv2 specifications 1937 [RFC2578], [RFC2579], [RFC2580] written by Jeff Case, Keith 1938 McCloghrie, David Perkins, Marshall T. Rose, Juergen Schoenwaelder, 1939 and Steven L. Waldbusser. 1941 The authors would like to thank all participants of the 7th NMRG 1942 meeting held in Schloss Kleinheubach from 6-8 September 2000, which 1943 was a major step towards the current status of this memo, namely 1944 Heiko Dassow, David Durham, Keith McCloghrie, and Bert Wijnen. 1946 Furthmore, several discussions within the SMING Working Group 1947 reflected experience with SMIv2 and influenced this specification at 1948 some points. 1950 Normative References 1952 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1953 Requirement Levels", RFC 2119, BCP 14, March 1997. 1955 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1956 Specifications: ABNF", RFC 2234, November 1997. 1958 Informative References 1960 [RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., 1961 Strauss, F. and W. Weiss, "SMIng Objectives", RFC 3216, 1962 December 2001. 1964 [RFCxxx2] Strauss, F. and J. Schoenwaelder, "SMIng Extension for 1965 SNMP Mappings", draft-irtf-nmrg-sming-snmp-05.txt, 1966 December 2003. 1968 [RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1969 Rose, M. and S. Waldbusser, "Structure of Management 1970 Information Version 2 (SMIv2)", RFC 2578, STD 58, April 1971 1999. 1973 [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1974 Rose, M. and S. Waldbusser, "Textual Conventions for 1975 SMIv2", RFC 2579, STD 59, April 1999. 1977 [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1978 Rose, M. and S. Waldbusser, "Conformance Statements for 1979 SMIv2", RFC 2580, STD 60, April 1999. 1981 [RFC3159] McCloghrie, K., Fine, M., Seligson, J., Chan, K., Hahn, 1982 S., Sahita, R., Smith, A. and F. Reichmeyer, "Structure of 1983 Policy Provisioning Information (SPPI)", RFC 3159, August 1984 2001. 1986 [RFC1155] Rose, M. and K. McCloghrie, "Structure and Identification 1987 of Management Information for TCP/IP-based Internets", RFC 1988 1155, STD 16, May 1990. 1990 [RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions", RFC 1991 1212, STD 16, March 1991. 1993 [RFC1215] Rose, M., "A Convention for Defining Traps for use with 1994 the SNMP", RFC 1215, March 1991. 1996 [ASN1] International Organization for Standardization, 1997 "Specification of Abstract Syntax Notation One (ASN.1)", 1998 International Standard 8824, December 1987. 2000 [RFC3411] Harrington, D., Presuhn, R. and B. Wijnen, "An 2001 Architecture for Describing Simple Network Management 2002 Protocol (SNMP) Management Frameworks", RFC 3411, STD 62, 2003 December 2002. 2005 [IEEE754] Institute of Electrical and Electronics Engineers, "IEEE 2006 Standard for Binary Floating-Point Arithmetic", ANSI/IEEE 2007 Standard 754-1985, August 1985. 2009 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 2010 10646", RFC 2279, January 1998. 2012 Authors' Addresses 2014 Frank Strauss 2015 TU Braunschweig 2016 Muehlenpfordtstrasse 23 2017 38106 Braunschweig 2018 Germany 2020 Phone: +49 531 391 3266 2021 EMail: strauss@ibr.cs.tu-bs.de 2022 URI: http://www.ibr.cs.tu-bs.de/ 2024 Juergen Schoenwaelder 2025 International University Bremen 2026 P.O. Box 750 561 2027 28725 Bremen 2028 Germany 2030 Phone: +49 421 200 3587 2031 EMail: j.schoenwaelder@iu-bremen.de 2032 URI: http://www.eecs.iu-bremen.de/ 2034 Appendix A. NMRG-SMING Module 2036 Most SMIng modules are built on top of the definitions of some 2037 commonly used derived types. The definitions of these derived types 2038 are contained in the NMRG-SMING module which is defined below. Its 2039 derived types are generally applicable for modelling all areas of 2040 management information. Among these derived types are counter types, 2041 string types and date and time related types. 2043 This module is derived from RFC 2578 [RFC2578] and RFC 2579 2044 [RFC2579]. 2046 module NMRG-SMING { 2048 organization "IRTF Network Management Research Group (NMRG)"; 2050 contact "IRTF Network Management Research Group (NMRG) 2051 http://www.ibr.cs.tu-bs.de/projects/nmrg/ 2053 Frank Strauss 2054 TU Braunschweig 2055 Muehlenpfordtstrasse 23 2056 38106 Braunschweig 2057 Germany 2058 Phone: +49 531 391 3266 2059 EMail: strauss@ibr.cs.tu-bs.de 2061 Juergen Schoenwaelder 2062 International University Bremen 2063 P.O. Box 750 561 2064 28725 Bremen 2065 Germany 2066 Phone: +49 421 200 3587 2067 EMail: j.schoenwaelder@iu-bremen.de"; 2069 description "Core type definitions for SMIng. Several 2070 type definitions are SMIng versions of 2071 similar SMIv2 or SPPI definitions. 2073 Copyright (C) The Internet Society (2003). 2074 All Rights Reserved. 2075 This version of this module is part of 2076 RFC xxx1, see the RFC itself for full 2077 legal notices."; 2079 revision { 2080 date "2003-12-16"; 2081 description "Initial revision, published as RFC XXXX."; 2082 }; 2084 typedef Gauge32 { 2085 type Unsigned32; 2086 description 2087 "The Gauge32 type represents a non-negative integer, 2088 which may increase or decrease, but shall never 2089 exceed a maximum value, nor fall below a minimum 2090 value. The maximum value can not be greater than 2091 2^32-1 (4294967295 decimal), and the minimum value 2092 can not be smaller than 0. The value of a Gauge32 2093 has its maximum value whenever the information 2094 being modeled is greater than or equal to its 2095 maximum value, and has its minimum value whenever 2096 the information being modeled is smaller than or 2097 equal to its minimum value. If the information 2098 being modeled subsequently decreases below 2099 (increases above) the maximum (minimum) value, the 2100 Gauge32 also decreases (increases)."; 2101 reference 2102 "RFC 2578, Sections 2. and 7.1.7."; 2103 }; 2105 typedef Counter32 { 2106 type Unsigned32; 2107 description 2108 "The Counter32 type represents a non-negative integer 2109 which monotonically increases until it reaches a 2110 maximum value of 2^32-1 (4294967295 decimal), when it 2111 wraps around and starts increasing again from zero. 2113 Counters have no defined `initial' value, and thus, a 2114 single value of a Counter has (in general) no information 2115 content. Discontinuities in the monotonically increasing 2116 value normally occur at re-initialization of the 2117 management system, and at other times as specified in the 2118 description of an attribute using this type. If such 2119 other times can occur, for example, the creation of a 2120 class instance that contains an attribute of type 2121 Counter32 at times other than re-initialization, then a 2122 corresponding attribute should be defined, with an 2123 appropriate type, to indicate the last discontinuity. 2124 Examples of appropriate types include: TimeStamp32, 2125 TimeStamp64, DateAndTime, TimeTicks32 or TimeTicks64 2126 (other types defined in this module). 2128 The value of the access statement for attributes with 2129 a type value of Counter32 should be either `readonly' 2130 or `eventonly'. 2132 A default statement should not be used for attributes 2133 with a type value of Counter32."; 2134 reference 2135 "RFC 2578, Sections 2. and 7.1.6."; 2136 }; 2138 typedef Gauge64 { 2139 type Unsigned64; 2140 description 2141 "The Gauge64 type represents a non-negative integer, 2142 which may increase or decrease, but shall never 2143 exceed a maximum value, nor fall below a minimum 2144 value. The maximum value can not be greater than 2145 2^64-1 (18446744073709551615), and the minimum value 2146 can not be smaller than 0. The value of a Gauge64 2147 has its maximum value whenever the information 2148 being modeled is greater than or equal to its 2149 maximum value, and has its minimum value whenever 2150 the information being modeled is smaller than or 2151 equal to its minimum value. If the information 2152 being modeled subsequently decreases below 2153 (increases above) the maximum (minimum) value, the 2154 Gauge64 also decreases (increases)."; 2155 }; 2157 typedef Counter64 { 2158 type Unsigned64; 2159 description 2160 "The Counter64 type represents a non-negative integer 2161 which monotonically increases until it reaches a 2162 maximum value of 2^64-1 (18446744073709551615), when 2163 it wraps around and starts increasing again from zero. 2165 Counters have no defined `initial' value, and thus, a 2166 single value of a Counter has (in general) no 2167 information content. Discontinuities in the 2168 monotonically increasing value normally occur at 2169 re-initialization of the management system, and at 2170 other times as specified in the description of an 2171 attribute using this type. If such other times can 2172 occur, for example, the creation of a class 2173 instance that contains an attribute of type Counter32 2174 at times other than re-initialization, then 2175 a corresponding attribute should be defined, with an 2176 appropriate type, to indicate the last discontinuity. 2177 Examples of appropriate types include: TimeStamp32, 2178 TimeStamp64, DateAndTime, TimeTicks32 or TimeTicks64 2179 (other types defined in this module). 2181 The value of the access statement for attributes with 2182 a type value of Counter64 should be either `readonly' 2183 or `eventonly'. 2185 A default statement should not be used for attributes 2186 with a type value of Counter64."; 2187 reference 2188 "RFC 2578, Sections 2. and 7.1.10."; 2189 }; 2191 typedef Opaque { 2192 type OctetString; 2193 status obsolete; 2194 description 2195 "******* THIS TYPE DEFINITION IS OBSOLETE ******* 2197 The Opaque type is provided solely for 2198 backward-compatibility, and shall not be used for 2199 newly-defined attributes and derived types. 2201 The Opaque type supports the capability to pass 2202 arbitrary ASN.1 syntax. A value is encoded using 2203 the ASN.1 Basic Encoding Rules into a string of 2204 octets. This, in turn, is encoded as an 2205 OctetString, in effect `double-wrapping' the 2206 original ASN.1 value. 2208 Note that a conforming implementation need only be 2209 able to accept and recognize opaquely-encoded data. 2210 It need not be able to unwrap the data and then 2211 interpret its contents. 2213 A requirement on `standard' modules is that no 2214 attribute may have a type value of Opaque and no 2215 type may be derived from the Opaque type."; 2216 reference 2217 "RFC 2578, Sections 2. and 7.1.9."; 2218 }; 2220 typedef IpAddress { 2221 type OctetString (4); 2222 status deprecated; 2223 description 2224 "******* THIS TYPE DEFINITION IS DEPRECATED ******* 2226 The IpAddress type represents a 32-bit Internet 2227 IPv4 address. It is represented as an OctetString 2228 of length 4, in network byte-order. 2230 Note that the IpAddress type is present for 2231 historical reasons."; 2232 reference 2233 "RFC 2578, Sections 2. and 7.1.5."; 2234 }; 2236 typedef TimeTicks32 { 2237 type Unsigned32; 2238 description 2239 "The TimeTicks32 type represents a non-negative integer 2240 which represents the time, modulo 2^32 (4294967296 2241 decimal), in hundredths of a second between two epochs. 2242 When attributes are defined which use this type, the 2243 description of the attribute identifies both of the 2244 reference epochs. 2246 For example, the TimeStamp32 type (defined in this 2247 module) is based on the TimeTicks32 type."; 2248 reference 2249 "RFC 2578, Sections 2. and 7.1.8."; 2250 }; 2252 typedef TimeTicks64 { 2253 type Unsigned64; 2254 description 2255 "The TimeTicks64 type represents a non-negative integer 2256 which represents the time, modulo 2^64 2257 (18446744073709551616 decimal), in hundredths of a second 2258 between two epochs. When attributes are defined which use 2259 this type, the description of the attribute identifies 2260 both of the reference epochs. 2262 For example, the TimeStamp64 type (defined in this 2263 module) is based on the TimeTicks64 type."; 2264 }; 2266 typedef TimeStamp32 { 2267 type TimeTicks32; 2268 description 2269 "The value of an associated TimeTicks32 attribute at 2270 which a specific occurrence happened. The specific 2271 occurrence must be defined in the description of any 2272 attribute defined using this type. When the specific 2273 occurrence occurred prior to the last time the 2274 associated TimeTicks32 attribute was zero, then the 2275 TimeStamp32 value is zero. Note that this requires all 2276 TimeStamp32 values to be reset to zero when the value of 2277 the associated TimeTicks32 attribute reaches 497+ days 2278 and wraps around to zero. 2280 The associated TimeTicks32 attribute should be specified 2281 in the description of any attribute using this type. 2282 If no TimeTicks32 attribute has been specified, the 2283 default scalar attribute sysUpTime is used."; 2284 reference 2285 "RFC 2579, Section 2."; 2286 }; 2288 typedef TimeStamp64 { 2289 type TimeTicks64; 2290 description 2291 "The value of an associated TimeTicks64 attribute at which 2292 a specific occurrence happened. The specific occurrence 2293 must be defined in the description of any attribute 2294 defined using this type. When the specific occurrence 2295 occurred prior to the last time the associated TimeTicks64 2296 attribute was zero, then the TimeStamp64 value is zero. 2297 The associated TimeTicks64 attribute must be specified in 2298 the description of any attribute using this 2299 type. TimeTicks32 attributes must not be used as 2300 associated attributes."; 2301 }; 2303 typedef TimeInterval32 { 2304 type Integer32 (0..2147483647); 2305 description 2306 "A period of time, measured in units of 0.01 seconds. 2308 The TimeInterval32 type uses Integer32 rather than 2309 Unsigned32 for compatibility with RFC 2579."; 2310 reference 2311 "RFC 2579, Section 2."; 2312 }; 2314 typedef TimeInterval64 { 2315 type Integer64; 2316 description 2317 "A period of time, measured in units of 0.01 seconds. 2318 Note that negative values are allowed."; 2319 }; 2320 typedef DateAndTime { 2321 type OctetString (8 | 11); 2322 default 0x0000000000000000000000; 2323 format "2d-1d-1d,1d:1d:1d.1d,1a1d:1d"; 2324 description 2325 "A date-time specification. 2327 field octets contents range 2328 ----- ------ -------- ----- 2329 1 1-2 year* 0..65535 2330 2 3 month 1..12 | 0 2331 3 4 day 1..31 | 0 2332 4 5 hour 0..23 2333 5 6 minutes 0..59 2334 6 7 seconds 0..60 2335 (use 60 for leap-second) 2336 7 8 deci-seconds 0..9 2337 8 9 direction from UTC '+' / '-' 2338 9 10 hours from UTC* 0..13 2339 10 11 minutes from UTC 0..59 2341 * Notes: 2342 - the value of year is in big-endian encoding 2343 - daylight saving time in New Zealand is +13 2345 For example, Tuesday May 26, 1992 at 1:30:15 PM EDT would 2346 be displayed as: 2348 1992-5-26,13:30:15.0,-4:0 2350 Note that if only local time is known, then timezone 2351 information (fields 8-10) is not present. 2353 The two special values of 8 or 11 zero bytes denote an 2354 unknown date-time specification."; 2355 reference 2356 "RFC 2579, Section 2."; 2357 }; 2359 typedef TruthValue { 2360 type Enumeration (true(1), false(2)); 2361 description 2362 "Represents a boolean value."; 2363 reference 2364 "RFC 2579, Section 2."; 2365 }; 2367 typedef PhysAddress { 2368 type OctetString; 2369 format "1x:"; 2370 description 2371 "Represents media- or physical-level addresses."; 2372 reference 2373 "RFC 2579, Section 2."; 2374 }; 2376 typedef MacAddress { 2377 type OctetString (6); 2378 format "1x:"; 2379 description 2380 "Represents an IEEE 802 MAC address represented in the 2381 `canonical' order defined by IEEE 802.1a, i.e., as if it 2382 were transmitted least significant bit first, even though 2383 802.5 (in contrast to other 802.x protocols) requires MAC 2384 addresses to be transmitted most significant bit first."; 2385 reference 2386 "RFC 2579, Section 2."; 2387 }; 2389 // The DisplayString definition below does not impose a size 2390 // restriction and is thus not the same as the DisplayString 2391 // definition in RFC 2579. The DisplayString255 definition is 2392 // provided for mapping purposes. 2394 typedef DisplayString { 2395 type OctetString; 2396 format "1a"; 2397 description 2398 "Represents textual information taken from the NVT ASCII 2399 character set, as defined in pages 4, 10-11 of RFC 854. 2401 To summarize RFC 854, the NVT ASCII repertoire specifies: 2403 - the use of character codes 0-127 (decimal) 2405 - the graphics characters (32-126) are interpreted as 2406 US ASCII 2408 - NUL, LF, CR, BEL, BS, HT, VT and FF have the special 2409 meanings specified in RFC 854 2411 - the other 25 codes have no standard interpretation 2413 - the sequence 'CR LF' means newline 2415 - the sequence 'CR NUL' means carriage-return 2416 - an 'LF' not preceded by a 'CR' means moving to the 2417 same column on the next line. 2419 - the sequence 'CR x' for any x other than LF or NUL is 2420 illegal. (Note that this also means that a string may 2421 end with either 'CR LF' or 'CR NUL', but not with CR.) 2422 "; 2423 }; 2425 typedef DisplayString255 { 2426 type DisplayString (0..255); 2427 description 2428 "A DisplayString with a maximum length of 255 characters. 2429 Any attribute defined using this syntax may not exceed 255 2430 characters in length. 2432 The DisplayString255 type has the same semantics as the 2433 DisplayString textual convention defined in RFC 2579."; 2434 reference 2435 "RFC 2579, Section 2."; 2436 }; 2438 // The Utf8String and Utf8String255 definitions below facilitate 2439 // internationalization. The definition is consistent with the 2440 // definition of SnmpAdminString in RFC 2571. 2442 typedef Utf8String { 2443 type OctetString; 2444 format "65535t"; // is there a better way ? 2445 description 2446 "A human readable string represented using the ISO/IEC IS 2447 10646-1 character set, encoded as an octet string using 2448 the UTF-8 transformation format described in RFC 2279. 2450 Since additional code points are added by amendments to 2451 the 10646 standard from time to time, implementations must 2452 be prepared to encounter any code point from 0x00000000 to 2453 0x7fffffff. Byte sequences that do not correspond to the 2454 valid UTF-8 encoding of a code point or are outside this 2455 range are prohibited. 2457 The use of control codes should be avoided. When it is 2458 necessary to represent a newline, the control code 2459 sequence CR LF should be used. 2461 The use of leading or trailing white space should be 2462 avoided. 2464 For code points not directly supported by user interface 2465 hardware or software, an alternative means of entry and 2466 display, such as hexadecimal, may be provided. 2468 For information encoded in 7-bit US-ASCII, the UTF-8 2469 encoding is identical to the US-ASCII encoding. 2471 UTF-8 may require multiple bytes to represent a single 2472 character / code point; thus the length of a Utf8String in 2473 octets may be different from the number of characters 2474 encoded. Similarly, size constraints refer to the number 2475 of encoded octets, not the number of characters 2476 represented by an encoding."; 2477 }; 2479 typedef Utf8String255 { 2480 type Utf8String (0..255); 2481 format "255t"; 2482 description 2483 "A Utf8String with a maximum length of 255 octets. Note 2484 that the size of an Utf8String is measured in octets, not 2485 characters."; 2486 }; 2488 identity null { 2489 description 2490 "An identity used to represent null pointer values."; 2491 }; 2493 }; 2495 Appendix B. SMIng ABNF Grammar 2497 The SMIng grammar conforms to the Augmented Backus-Naur Form (ABNF) 2498 [RFC2234]. 2500 ;; 2501 ;; sming.abnf -- SMIng grammar in ABNF notation (RFC 2234). 2502 ;; 2503 ;; @(#) $Id: sming.abnf,v 1.33 2003/10/23 19:31:55 strauss Exp $ 2504 ;; 2505 ;; Copyright (C) The Internet Society (2003). All Rights Reserved. 2506 ;; 2507 smingFile = optsep *(moduleStatement optsep) 2509 ;; 2510 ;; Statement rules. 2511 ;; 2513 moduleStatement = moduleKeyword sep ucIdentifier optsep 2514 "{" stmtsep 2515 *(importStatement stmtsep) 2516 organizationStatement stmtsep 2517 contactStatement stmtsep 2518 descriptionStatement stmtsep 2519 *1(referenceStatement stmtsep) 2520 1*(revisionStatement stmtsep) 2521 *(extensionStatement stmtsep) 2522 *(typedefStatement stmtsep) 2523 *(identityStatement stmtsep) 2524 *(classStatement stmtsep) 2525 "}" optsep ";" 2527 extensionStatement = extensionKeyword sep lcIdentifier optsep 2528 "{" stmtsep 2529 statusStatement stmtsep 2530 descriptionStatement stmtsep 2531 *1(referenceStatement stmtsep) 2532 *1(abnfStatement stmtsep) 2533 "}" optsep ";" 2535 typedefStatement = typedefKeyword sep ucIdentifier optsep 2536 "{" stmtsep 2537 typedefTypeStatement stmtsep 2538 *1(defaultStatement stmtsep) 2539 *1(formatStatement stmtsep) 2540 *1(unitsStatement stmtsep) 2541 statusStatement stmtsep 2542 descriptionStatement stmtsep 2543 *1(referenceStatement stmtsep) 2544 "}" optsep ";" 2546 identityStatement = identityStmtKeyword sep lcIdentifier optsep 2547 "{" stmtsep 2548 *1(parentStatement stmtsep) 2549 statusStatement stmtsep 2550 descriptionStatement stmtsep 2551 *1(referenceStatement stmtsep) 2552 "}" optsep ";" 2554 classStatement = classKeyword sep ucIdentifier optsep 2555 "{" stmtsep 2556 *1(extendsStatement stmtsep) 2557 *(attributeStatement stmtsep) 2558 *1(uniqueStatement stmtsep) 2559 *(eventStatement stmtsep) 2560 statusStatement stmtsep 2561 descriptionStatement stmtsep 2562 *1(referenceStatement stmtsep) 2563 "}" optsep ";" 2565 attributeStatement = attributeKeyword sep 2566 lcIdentifier optsep 2567 "{" stmtsep 2568 typeStatement stmtsep 2569 *1(accessStatement stmtsep) 2570 *1(defaultStatement stmtsep) 2571 *1(formatStatement stmtsep) 2572 *1(unitsStatement stmtsep) 2573 statusStatement stmtsep 2574 descriptionStatement stmtsep 2575 *1(referenceStatement stmtsep) 2576 "}" optsep ";" 2578 uniqueStatement = uniqueKeyword optsep 2579 "(" optsep qlcIdentifierList 2580 optsep ")" optsep ";" 2582 eventStatement = eventKeyword sep lcIdentifier 2583 optsep "{" stmtsep 2584 statusStatement stmtsep 2585 descriptionStatement stmtsep 2586 *1(referenceStatement stmtsep) 2587 "}" optsep ";" 2589 importStatement = importKeyword sep ucIdentifier optsep 2590 "(" optsep 2591 identifierList optsep 2592 ")" optsep ";" 2594 revisionStatement = revisionKeyword optsep "{" stmtsep 2595 dateStatement stmtsep 2596 descriptionStatement stmtsep 2597 "}" optsep ";" 2599 typedefTypeStatement = typeKeyword sep refinedBaseType optsep ";" 2601 typeStatement = typeKeyword sep 2602 (refinedBaseType / refinedType) optsep ";" 2604 parentStatement = parentKeyword sep qlcIdentifier optsep ";" 2606 extendsStatement = extendsKeyword sep qucIdentifier optsep ";" 2608 dateStatement = dateKeyword sep date optsep ";" 2610 organizationStatement = organizationKeyword sep text optsep ";" 2612 contactStatement = contactKeyword sep text optsep ";" 2614 formatStatement = formatKeyword sep format optsep ";" 2616 unitsStatement = unitsKeyword sep units optsep ";" 2618 statusStatement = statusKeyword sep status optsep ";" 2620 accessStatement = accessKeyword sep access optsep ";" 2622 defaultStatement = defaultKeyword sep anyValue optsep ";" 2624 descriptionStatement = descriptionKeyword sep text optsep ";" 2626 referenceStatement = referenceKeyword sep text optsep ";" 2628 abnfStatement = abnfKeyword sep text optsep ";" 2630 ;; 2631 ;; 2632 ;; 2634 refinedBaseType = ObjectIdentifierKeyword / 2635 OctetStringKeyword *1(optsep numberSpec) / 2636 PointerKeyword *1(optsep pointerSpec) / 2637 Integer32Keyword *1(optsep numberSpec) / 2638 Unsigned32Keyword *1(optsep numberSpec) / 2639 Integer64Keyword *1(optsep numberSpec) / 2640 Unsigned64Keyword *1(optsep numberSpec) / 2641 Float32Keyword *1(optsep floatSpec) / 2642 Float64Keyword *1(optsep floatSpec) / 2643 Float128Keyword *1(optsep floatSpec) / 2644 EnumerationKeyword 2645 optsep namedSignedNumberSpec / 2646 BitsKeyword optsep namedNumberSpec 2648 refinedType = qucIdentifier *1(optsep anySpec) 2650 anySpec = pointerSpec / numberSpec / floatSpec 2651 pointerSpec = "(" optsep qlcIdentifier optsep ")" 2653 numberSpec = "(" optsep numberElement 2654 *furtherNumberElement 2655 optsep ")" 2657 furtherNumberElement = optsep "|" optsep numberElement 2659 numberElement = signedNumber *1numberUpperLimit 2661 numberUpperLimit = optsep ".." optsep signedNumber 2663 floatSpec = "(" optsep floatElement 2664 *furtherFloatElement 2665 optsep ")" 2667 furtherFloatElement = optsep "|" optsep floatElement 2669 floatElement = floatValue *1floatUpperLimit 2671 floatUpperLimit = optsep ".." optsep floatValue 2673 namedNumberSpec = "(" optsep namedNumberList optsep ")" 2675 namedNumberList = namedNumberItem 2676 *(optsep "," optsep namedNumberItem) 2678 namedNumberItem = lcIdentifier optsep "(" optsep number 2679 optsep ")" 2681 namedSignedNumberSpec = "(" optsep namedSignedNumberList optsep ")" 2683 namedSignedNumberList = namedSignedNumberItem 2684 *(optsep "," optsep 2685 namedSignedNumberItem) 2687 namedSignedNumberItem = lcIdentifier optsep "(" optsep signedNumber 2688 optsep ")" 2690 identifierList = identifier 2691 *(optsep "," optsep identifier) 2693 qIdentifierList = qIdentifier 2694 *(optsep "," optsep qIdentifier) 2696 qlcIdentifierList = qlcIdentifier 2697 *(optsep "," optsep qlcIdentifier) 2699 bitsValue = "(" optsep bitsList optsep ")" 2701 bitsList = *1(lcIdentifier 2702 *(optsep "," optsep lcIdentifier)) 2704 ;; 2705 ;; Other basic rules. 2706 ;; 2708 identifier = ucIdentifier / lcIdentifier 2710 qIdentifier = qucIdentifier / qlcIdentifier 2712 ucIdentifier = ucAlpha *63(ALPHA / DIGIT / "-") 2714 qucIdentifier = *1(ucIdentifier "::") ucIdentifier 2716 lcIdentifier = lcAlpha *63(ALPHA / DIGIT / "-") 2718 qlcIdentifier = *1(ucIdentifier "::") lcIdentifier 2720 attrIdentifier = lcIdentifier *("." lcIdentifier) 2722 qattrIdentifier = *1(ucIdentifier ".") attrIdentifier 2724 cattrIdentifier = ucIdentifier "." 2725 lcIdentifier *("." lcIdentifier) 2727 qcattrIdentifier = qucIdentifier "." 2728 lcIdentifier *("." lcIdentifier) 2730 text = textSegment *(optsep textSegment) 2732 textSegment = DQUOTE *textAtom DQUOTE 2733 ; See Section 4.2. 2735 textAtom = textVChar / HTAB / SP / lineBreak 2737 date = DQUOTE 4DIGIT "-" 2DIGIT "-" 2DIGIT 2738 *1(" " 2DIGIT ":" 2DIGIT) 2739 DQUOTE 2740 ; always in UTC 2742 format = textSegment 2744 units = textSegment 2746 anyValue = bitsValue / 2747 signedNumber / 2748 hexadecimalNumber / 2749 floatValue / 2750 text / 2751 objectIdentifier 2752 ; Note: `objectIdentifier' includes the 2753 ; syntax of enumeration labels and 2754 ; identities. 2755 ; They are not named literally to 2756 ; avoid reduce/reduce conflicts when 2757 ; building LR parsers based on this 2758 ; grammar. 2760 status = currentKeyword / 2761 deprecatedKeyword / 2762 obsoleteKeyword 2764 access = eventonlyKeyword / 2765 readonlyKeyword / 2766 readwriteKeyword 2768 objectIdentifier = (qlcIdentifier / subid "." subid) 2769 *127("." subid) 2771 subid = decimalNumber 2773 number = hexadecimalNumber / decimalNumber 2775 negativeNumber = "-" decimalNumber 2777 signedNumber = number / negativeNumber 2779 decimalNumber = "0" / (nonZeroDigit *DIGIT) 2781 zeroDecimalNumber = 1*DIGIT 2783 hexadecimalNumber = %x30 %x78 ; "0x" with x only lower-case 2784 1*(HEXDIG HEXDIG) 2786 floatValue = neginfKeyword / 2787 posinfKeyword / 2788 snanKeyword / 2789 qnanKeyword / 2790 signedNumber "." zeroDecimalNumber 2791 *1("E" ("+"/"-") zeroDecimalNumber) 2793 ;; 2794 ;; Rules to skip unknown statements 2795 ;; with arbitrary arguments and blocks. 2796 ;; 2798 unknownStatement = unknownKeyword optsep *unknownArgument 2799 optsep ";" 2801 unknownArgument = ("(" optsep unknownList optsep ")") / 2802 ("{" optsep *unknownStatement optsep "}") / 2803 qucIdentifier / 2804 anyValue / 2805 anySpec 2807 unknownList = namedNumberList / 2808 qIdentifierList 2810 unknownKeyword = lcIdentifier 2812 ;; 2813 ;; Keyword rules. 2814 ;; 2815 ;; Typically, keywords are represented by tokens returned from the 2816 ;; lexical analyzer. Note, that the lexer has to be stateful to 2817 ;; distinguish keywords from identifiers depending on the context 2818 ;; position in the input stream. 2819 ;; 2821 moduleKeyword = %x6D %x6F %x64 %x75 %x6C %x65 2822 importKeyword = %x69 %x6D %x70 %x6F %x72 %x74 2823 revisionKeyword = %x72 %x65 %x76 %x69 %x73 %x69 %x6F %x6E 2824 dateKeyword = %x64 %x61 %x74 %x65 2825 organizationKeyword = %x6F %x72 %x67 %x61 %x6E %x69 %x7A %x61 %x74 2826 %x69 %x6F %x6E 2827 contactKeyword = %x63 %x6F %x6E %x74 %x61 %x63 %x74 2828 descriptionKeyword = %x64 %x65 %x73 %x63 %x72 %x69 %x70 %x74 %x69 2829 %x6F %x6E 2830 referenceKeyword = %x72 %x65 %x66 %x65 %x72 %x65 %x6E %x63 %x65 2831 extensionKeyword = %x65 %x78 %x74 %x65 %x6E %x73 %x69 %x6F %x6E 2832 typedefKeyword = %x74 %x79 %x70 %x65 %x64 %x65 %x66 2833 typeKeyword = %x74 %x79 %x70 %x65 2834 parentKeyword = %x70 %x61 %x72 %x65 %x6E %x74 2835 identityStmtKeyword = %x69 %x64 %x65 %x6E %x74 %x69 %x74 %x79 2836 classKeyword = %x63 %x6C %x61 %x73 %x73 2837 extendsKeyword = %x65 %x78 %x74 %x65 %x6E %x64 %x73 2838 attributeKeyword = %x61 %x74 %x74 %x72 %x69 %x62 %x75 %x74 %x65 2839 uniqueKeyword = %x75 %x6E %x69 %x71 %x75 %x65 2840 eventKeyword = %x65 %x76 %x65 %x6E %x74 2841 formatKeyword = %x66 %x6F %x72 %x6D %x61 %x74 2842 unitsKeyword = %x75 %x6E %x69 %x74 %x73 2843 statusKeyword = %x73 %x74 %x61 %x74 %x75 %x73 2844 accessKeyword = %x61 %x63 %x63 %x65 %x73 %x73 2845 defaultKeyword = %x64 %x65 %x66 %x61 %x75 %x6C %x74 2846 abnfKeyword = %x61 %x62 %x6E %x66 2848 ;; Base type keywords. 2850 OctetStringKeyword = %x4F %x63 %x74 %x65 %x74 %x53 %x74 %x72 %x69 2851 %x6E %x67 2852 PointerKeyword = %x50 %x6F %x69 %x6E %x74 %x65 %x72 2853 ObjectIdentifierKeyword = %x4F %x62 %x6A %x65 %x63 %x74 %x49 %x64 2854 %x65 %x6E %x74 %x69 %x66 %x69 %x65 %x72 2855 Integer32Keyword = %x49 %x6E %x74 %x65 %x67 %x65 %x72 %x33 %x32 2856 Unsigned32Keyword = %x55 %x6E %x73 %x69 %x67 %x6E %x65 %x64 %x33 2857 %x32 2858 Integer64Keyword = %x49 %x6E %x74 %x65 %x67 %x65 %x72 %x36 %x34 2859 Unsigned64Keyword = %x55 %x6E %x73 %x69 %x67 %x6E %x65 %x64 %x36 2860 %x34 2861 Float32Keyword = %x46 %x6C %x6F %x61 %x74 %x33 %x32 2862 Float64Keyword = %x46 %x6C %x6F %x61 %x74 %x36 %x34 2863 Float128Keyword = %x46 %x6C %x6F %x61 %x74 %x31 %x32 %x38 2864 BitsKeyword = %x42 %x69 %x74 %x73 2865 EnumerationKeyword = %x45 %x6E %x75 %x6D %x65 %x72 %x61 %x74 %x69 2866 %x6F %x6E 2868 ;; Status keywords. 2870 currentKeyword = %x63 %x75 %x72 %x72 %x65 %x6E %x74 2871 deprecatedKeyword = %x64 %x65 %x70 %x72 %x65 %x63 %x61 %x74 %x65 2872 %x64 2873 obsoleteKeyword = %x6F %x62 %x73 %x6F %x6C %x65 %x74 %x65 2875 ;; Access keywords. 2877 eventonlyKeyword = %x65 %x76 %x65 %x6E %x74 %x6F %x6E %x6C %x79 2878 readonlyKeyword = %x72 %x65 %x61 %x64 %x6F %x6E %x6C %x79 2879 readwriteKeyword = %x72 %x65 %x61 %x64 %x77 %x72 %x69 %x74 %x65 2881 ;; Special floating point values' keywords. 2883 neginfKeyword = %x6E %x65 %x67 %x69 %x6E %x66 2884 posinfKeyword = %x70 %x6F %x73 %x69 %x6E %x66 2885 snanKeyword = %x73 %x6E %x61 %x6E 2886 qnanKeyword = %x71 %x6E %x61 %x6E 2888 ;; 2889 ;; Some low level rules. 2890 ;; These tokens are typically skipped by the lexical analyzer. 2892 ;; 2894 sep = 1*(comment / lineBreak / WSP) 2895 ; unconditional separator 2897 optsep = *(comment / lineBreak / WSP) 2899 stmtsep = *(comment / 2900 lineBreak / 2901 WSP / 2902 unknownStatement) 2904 comment = "//" *(WSP / VCHAR) lineBreak 2906 lineBreak = CRLF / LF 2908 ;; 2909 ;; Encoding specific rules. 2910 ;; 2912 textVChar = %x21 / %x23-7E 2913 ; any VCHAR except DQUOTE 2915 ucAlpha = %x41-5A 2917 lcAlpha = %x61-7A 2919 nonZeroDigit = %x31-39 2921 ;; 2922 ;; RFC 2234 core rules. 2923 ;; 2925 ALPHA = %x41-5A / %x61-7A 2926 ; A-Z / a-z 2928 CR = %x0D 2929 ; carriage return 2931 CRLF = CR LF 2932 ; Internet standard newline 2934 DIGIT = %x30-39 2935 ; 0-9 2937 DQUOTE = %x22 2938 ; " (Double Quote) 2940 HEXDIG = DIGIT / 2941 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 2942 ; only lower-case a..f 2944 HTAB = %x09 2945 ; horizontal tab 2947 LF = %x0A 2948 ; linefeed 2950 SP = %x20 2951 ; space 2953 VCHAR = %x21-7E 2954 ; visible (printing) characters 2956 WSP = SP / HTAB 2957 ; white space 2959 ;; End of ABNF 2961 Intellectual Property Statement 2963 The IETF takes no position regarding the validity or scope of any 2964 intellectual property or other rights that might be claimed to 2965 pertain to the implementation or use of the technology described in 2966 this document or the extent to which any license under such rights 2967 might or might not be available; neither does it represent that it 2968 has made any effort to identify any such rights. Information on the 2969 IETF's procedures with respect to rights in standards-track and 2970 standards-related documentation can be found in BCP-11. Copies of 2971 claims of rights made available for publication and any assurances of 2972 licenses to be made available, or the result of an attempt made to 2973 obtain a general license or permission for the use of such 2974 proprietary rights by implementors or users of this specification can 2975 be obtained from the IETF Secretariat. 2977 The IETF invites any interested party to bring to its attention any 2978 copyrights, patents or patent applications, or other proprietary 2979 rights which may cover technology that may be required to practice 2980 this standard. Please address the information to the IETF Executive 2981 Director. 2983 Full Copyright Statement 2985 Copyright (C) The Internet Society (2003). All Rights Reserved. 2987 This document and translations of it may be copied and furnished to 2988 others, and derivative works that comment on or otherwise explain it 2989 or assist in its implementation may be prepared, copied, published 2990 and distributed, in whole or in part, without restriction of any 2991 kind, provided that the above copyright notice and this paragraph are 2992 included on all such copies and derivative works. However, this 2993 document itself may not be modified in any way, such as by removing 2994 the copyright notice or references to the Internet Society or other 2995 Internet organizations, except as needed for the purpose of 2996 developing Internet standards in which case the procedures for 2997 copyrights defined in the Internet Standards process must be 2998 followed, or as required to translate it into languages other than 2999 English. 3001 The limited permissions granted above are perpetual and will not be 3002 revoked by the Internet Society or its successors or assignees. 3004 This document and the information contained herein is provided on an 3005 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3006 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3007 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3008 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3009 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3011 Acknowledgement 3013 Funding for the RFC Editor function is currently provided by the 3014 Internet Society.