idnits 2.17.1 draft-ietf-snmpv2-smi-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** Expected the document's filename to be given on the first page, but didn't find any == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' 2. Introduction' ) ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** There are 79 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1100: '...(the DEFAULT and OPTIONAL clauses are ...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1424 has weird spacing: '...luation table...' == Line 1486 has weird spacing: '...a group defin...' == Line 2129 has weird spacing: '... range enum...' == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 2493 looks like a reference -- Missing reference section? 'UNIVERSAL 2' on line 276 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 307 looks like a reference -- Missing reference section? 'APPLICATION 1' on line 312 looks like a reference -- Missing reference section? 'APPLICATION 2' on line 319 looks like a reference -- Missing reference section? 'APPLICATION 3' on line 324 looks like a reference -- Missing reference section? 'APPLICATION 4' on line 329 looks like a reference -- Missing reference section? 'APPLICATION 5' on line 334 looks like a reference -- Missing reference section? 'APPLICATION 6' on line 339 looks like a reference -- Missing reference section? '2' on line 2499 looks like a reference -- Missing reference section? '3' on line 2503 looks like a reference -- Missing reference section? '4' on line 2508 looks like a reference -- Missing reference section? '5' on line 2514 looks like a reference -- Missing reference section? '6' on line 2520 looks like a reference -- Missing reference section? '9' on line 2532 looks like a reference -- Missing reference section? '7' on line 2525 looks like a reference -- Missing reference section? '8' on line 2529 looks like a reference Summary: 15 errors (**), 0 flaws (~~), 5 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Draft Structure of Management Information for SNMPv2 Oct 92 4 Structure of Management Information 5 for version 2 of the 6 Simple Network Management Protocol (SNMPv2) 8 Thu Nov 12 08:51:15 1992 | 10 Jeffrey D. Case 11 SNMP Research, Inc. 12 University of Tennessee, Knoxville 13 case@cs.utk.edu 15 Keith McCloghrie 16 Hughes LAN Systems 17 kzm@hls.com 19 Marshall T. Rose 20 Dover Beach Consulting, Inc. 21 mrose@dbc.mtview.ca.us 23 Steven L. Waldbusser 24 Carnegie Mellon University 25 waldbusser@andrew.cmu.edu 27 1. Status of this Memo 29 This document is an Internet Draft. Internet Drafts are 30 working documents of the Internet Engineering Task Force 31 (IETF), its Areas, and its Working Groups. Note that other 32 groups may also distribute working documents as Internet 33 Drafts. 35 Internet Drafts are valid for a maximum of six months and may 36 be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet Drafts as reference 38 material or to cite them other than as a "work in progress". 40 Draft Structure of Management Information for SNMPv2 Oct 92 42 2. Introduction 44 A network management system contains: several (potentially 45 many) nodes, each with a processing entity, termed an agent, 46 which has access to management instrumentation; at least one 47 management station; and, a management protocol, used to convey 48 management information between the agents and management 49 stations. Operations of the management protocol are carried 50 out under an administrative framework which defines both 51 authentication and authorization policies. 53 Network management stations execute management applications 54 which monitor and control network elements. Network elements 55 are devices such as hosts, routers, terminal servers, etc., 56 which are monitored and controlled through access to their 57 management information. 59 Management information is viewed as a collection of managed 60 objects, residing in a virtual information store, termed the 61 Management Information Base (MIB). Collections of related 62 objects are defined in MIB modules. These modules are written 63 using a subset of OSI's Abstract Syntax Notation One (ASN.1) 64 [1]. It is the purpose of this document, the Structure of 65 Management Information (SMI), to define that subset. 67 The SMI is divided into four parts: object definitions, trap 68 definitions, compliance definitions, and capabilities 69 definitions. 71 (1) Object definitions are used when describing managed 72 objects. An ASN.1 macro, OBJECT-TYPE, is used to 73 concisely convey the syntax and semantics of a managed 74 object. Collections of related objects are grouped 75 together to form a unit of conformance. An ASN.1 macro, 76 OBJECT-GROUP, is used to concisely convey the syntax and 77 semantics of such a group. 79 (2) Notification definitions are used when describing an | 80 unsolicited transmission of management information. | 81 An ASN.1 macro, NOTIFICATION-TYPE, is used to concisely | 82 convey the syntax and semantics of a notification. | 84 (3) Compliance definitions are used when describing 85 requirements for agents with respect to object 86 definitions. An ASN.1 macro, MODULE-COMPLIANCE, is used 88 Draft Structure of Management Information for SNMPv2 Oct 92 90 to concisely convey such requirements. 92 (4) Capability definitions are used when describing the 93 capabilities of agents with respect to object 94 definitions. An ASN.1 macro, AGENT-CAPABILITIES, is used 95 to concisely convey such capabilities. 97 2.1. A Note on Terminology 99 For the purpose of exposition, the original Internet-standard + 100 Network Management Framework, as described in RFCs 1155, 1157, + 101 and 1212, is termed the SNMP version 1 framework (SNMPv1). + 102 The current framework is termed the SNMP version 2 framework + 103 (SNMPv2). + 104 Draft Structure of Management Information for SNMPv2 Oct 92 106 3. Definitions 108 SNMPv2-SMI DEFINITIONS ::= BEGIN 110 -- the path to the root 112 internet OBJECT IDENTIFIER ::= { iso org(3) dod(6) 1 } 114 directory OBJECT IDENTIFIER ::= { internet 1 } 116 mgmt OBJECT IDENTIFIER ::= { internet 2 } 118 experimental OBJECT IDENTIFIER ::= { internet 3 } 120 private OBJECT IDENTIFIER ::= { internet 4 } 121 enterprises OBJECT IDENTIFIER ::= { private 1 } 123 snmpV2 OBJECT IDENTIFIER ::= 124 { joint-iso-ccitt mhs(6) group(6) mtr(200) 4 } 125 snmpMappings OBJECT IDENTIFIER ::= { snmpV2 1 } 126 -- { snmpV2 2 } is obsolete 128 -- these two values will go away 129 -- when the SNMP Security working group reconvenes 130 smpProtocols OBJECT IDENTIFIER ::= { snmpV2 3 } 131 smpMD5AuthProtocol OBJECT IDENTIFIER ::= { smpProtocols 1 } 133 snmpModules OBJECT IDENTIFIER ::= { snmpV2 4 } 134 Draft Structure of Management Information for SNMPv2 Oct 92 136 -- information about a module 138 MODULE-IDENTITY MACRO ::= 139 BEGIN 140 TYPE NOTATION ::= 141 "LAST-UPDATED" value(update UTCTime) 142 "ORGANIZATION" value(organization Text) 143 "CONTACT-INFO" value(contact Text) 144 "DESCRIPTION" value(description Text) 145 RevisionPart 147 VALUE NOTATION ::= 148 value(VALUE OBJECT IDENTIFIER) 150 RevisionPart ::= 151 Revisions 152 | empty 153 Revisions ::= 154 Revision 155 | Revisions Revision 156 Revision ::= 157 "REVISION" value(update UTCTime) 158 "DESCRIPTION" value(description Text) 160 -- uses the NVT ASCII character set 161 Text ::= OCTET STRING 162 END 163 Draft Structure of Management Information for SNMPv2 Oct 92 165 -- definition for objects 167 OBJECT-TYPE MACRO ::= 168 BEGIN 169 TYPE NOTATION ::= 170 "SYNTAX" type(ObjectSyntax) 171 UnitsPart 172 "MAX-ACCESS" Access 173 "STATUS" Status 174 "DESCRIPTION" value(description Text) 175 ReferPart 176 IndexPart 177 DefValPart 179 VALUE NOTATION ::= 180 value(VALUE ObjectName) 182 UnitsPart ::= 183 "UNITS" value(units Text) 184 | empty 186 Access ::= 187 "not-accessible" 188 | "read-only" 189 | "read-write" 190 | "read-create" 192 Status ::= 193 "current" 194 | "deprecated" 195 | "obsolete" 197 ReferPart ::= 198 "REFERENCE" value(reference Text) 199 | empty 201 IndexPart ::= 202 "INDEX" "{" IndexTypes "}" 203 | "AUGMENTS" "{" Entry "}" 204 | empty 205 IndexTypes ::= 206 IndexType 207 | IndexTypes "," IndexType 209 Draft Structure of Management Information for SNMPv2 Oct 92 211 IndexType ::= 212 "IMPLIED" Index 213 | Index 214 Index ::= 215 -- use the SYNTAX value of the 216 -- correspondent OBJECT-TYPE invocation 217 value(indexobject ObjectName) 218 Entry ::= 219 -- use the INDEX value of the 220 -- correspondent OBJECT-TYPE invocation 221 value(entryobject ObjectName) 223 DefValPart ::= 224 "DEFVAL" "{" value(defval ObjectSyntax) "}" 225 | empty 227 -- uses the NVT ASCII character set 228 Text ::= OCTET STRING 229 END 230 Draft Structure of Management Information for SNMPv2 Oct 92 232 -- names of objects 234 ObjectName ::= 235 OBJECT IDENTIFIER 237 -- syntax of objects 239 ObjectSyntax ::= 240 CHOICE { 241 simple 242 SimpleSyntax, 244 -- note that SEQUENCEs for conceptual tables and 245 -- rows are not mentioned here... 247 application-wide 248 ApplicationSyntax 249 } 251 -- built-in ASN.1 types 253 SimpleSyntax ::= 254 CHOICE { 255 -- INTEGERs with a more restrictive range 256 -- may also be used 257 integer-value 258 INTEGER (-2147483648..2147483647), 260 string-value 261 OCTET STRING, 263 objectID-value 264 OBJECT IDENTIFIER, 266 -- only the enumerated form is allowed 267 bit-value 268 BIT STRING 269 } 271 Draft Structure of Management Information for SNMPv2 Oct 92 273 -- indistinguishable from INTEGER, but never needs more than 274 -- 32-bits for a two's complement representation 275 Integer32 ::= 276 [UNIVERSAL 2] 277 IMPLICIT INTEGER (-2147483648..2147483647) 279 -- application-wide types 281 ApplicationSyntax ::= 282 CHOICE { 283 ipAddress-value 284 IpAddress, 286 counter-value 287 Counter32, 289 gauge-value 290 Gauge32, 292 timeticks-value 293 TimeTicks, 295 arbitrary-value 296 Opaque, 298 nsapAddress-value 299 NsapAddress, 301 big-counter-value 302 Counter64 303 } 305 -- in network-byte order 306 IpAddress ::= 307 [APPLICATION 0] 308 IMPLICIT OCTET STRING (SIZE (4)) 310 -- this wraps 311 Counter32 ::= 312 [APPLICATION 1] 313 IMPLICIT INTEGER (0..4294967295) 315 Draft Structure of Management Information for SNMPv2 Oct 92 317 -- this doesn't wrap 318 Gauge32 ::= 319 [APPLICATION 2] 320 IMPLICIT INTEGER (0..4294967295) 322 -- hundredths of seconds since an epoch 323 TimeTicks ::= 324 [APPLICATION 3] 325 IMPLICIT INTEGER (0..4294967295) 327 -- for backward-compatibility only 328 Opaque ::= 329 [APPLICATION 4] 330 IMPLICIT OCTET STRING 332 -- for OSI NSAP addresses 333 NsapAddress ::= 334 [APPLICATION 5] 335 IMPLICIT OCTET STRING (SIZE (1 | 4..21)) 337 -- for counters that wrap in less than one hour with only 32 bits 338 Counter64 ::= 339 [APPLICATION 6] 340 IMPLICIT INTEGER (0..18446744073709551615) 342 Draft Structure of Management Information for SNMPv2 Oct 92 344 -- definitions for object groups (a unit of conformance) 346 OBJECT-GROUP MACRO ::= 347 BEGIN 348 TYPE NOTATION ::= 349 ObjectsPart 350 "STATUS" Status 351 "DESCRIPTION" value(description Text) 352 ReferPart 354 VALUE NOTATION ::= 355 value(VALUE OBJECT IDENTIFIER) 357 ObjectsPart ::= 358 "OBJECTS" "{" Objects "}" 359 Objects ::= 360 Object 361 | Objects "," Object 362 Object ::= 363 value(object ObjectName) 365 Status ::= 366 "current" 367 | "deprecated" 368 | "obsolete" 370 ReferPart ::= 371 "REFERENCE" value(reference Text) 372 | empty 374 -- uses the NVT ASCII character set 375 Text ::= OCTET STRING 376 END 377 Draft Structure of Management Information for SNMPv2 Oct 92 379 -- definitions for notifications | 381 NOTIFICATION-TYPE MACRO ::= | 382 BEGIN 383 TYPE NOTATION ::= 384 ObjectsPart 385 "STATUS" Status 386 "DESCRIPTION" value(description Text) 387 ReferPart 389 VALUE NOTATION ::= 390 value (VALUE OBJECT IDENTIFIER) 392 ObjectPart ::= 393 "OBJECTS" "{" Objects "}" 394 | empty 395 Objects ::= 396 Object 397 | Objects "," Object 398 Object ::= 399 value(object ObjectName) 401 Status ::= 402 "current" 403 | "deprecated" 404 | "obsolete" 406 ReferPart ::= 407 "REFERENCE" value (reference Text) 408 | empty 410 -- uses the NVT ASCII character set 411 Text ::= OCTET STRING 412 END 413 Draft Structure of Management Information for SNMPv2 Oct 92 415 -- definitions for compliance 417 MODULE-COMPLIANCE MACRO ::= 418 BEGIN 419 TYPE NOTATION ::= 420 "STATUS" Status 421 "DESCRIPTION" value(description Text) 422 ReferPart 423 ModulePart 425 VALUE NOTATION ::= 426 value(VALUE OBJECT IDENTIFIER) 428 Status ::= 429 "current" 430 | "deprecated" 431 | "obsolete" 433 ReferPart ::= 434 "REFERENCE" value (reference Text) 435 | empty 437 ModulePart ::= 438 Modules 439 | empty 440 Modules ::= 441 Module 442 | Modules Module 443 Module ::= 444 -- name of module -- 445 "MODULE" ModuleName 446 MandatoryPart 447 CompliancePart 449 ModuleName ::= 450 identifier ModuleIdentifier 451 -- must not be empty unless contained 452 -- in MIB Module 453 | empty 454 ModuleIdentifier ::= 455 value (moduleID OBJECT IDENTIFIER) 456 | empty 458 MandatoryPart ::= 459 "MANDATORY-GROUPS" "{" Groups "}" 461 Draft Structure of Management Information for SNMPv2 Oct 92 463 | empty 465 Groups ::= 466 Group 467 | Groups "," Group 468 Group ::= 469 value(group OBJECT IDENTIFIER) 471 CompliancePart ::= 472 Compliances 473 | empty 474 Compliances ::= 475 Compliance 476 | Compliances Compliance 477 Compliance ::= 478 Group 479 | Object 481 Group ::= 482 "GROUP" value(object OBJECT IDENTIFIER) 483 "DESCRIPTION" value(description Text) 485 Object ::= 486 "OBJECT" value(object ObjectName) 487 SyntaxPart 488 WriteSyntaxPart 489 AccessPart 490 "DESCRIPTION" value(description Text) 492 -- must be a refinement for object's SYNTAX clause 493 SyntaxPart ::= 494 "SYNTAX" type(SYNTAX) 495 | empty 497 -- must be a refinement for object's SYNTAX clause 498 WriteSyntaxPart ::= 499 "WRITE-SYNTAX" type(WriteSYNTAX) 500 | empty 502 AccessPart ::= 503 "MIN-ACCESS" Access 504 | empty 505 Access ::= 506 "not-accessible" 507 | "read-only" 509 Draft Structure of Management Information for SNMPv2 Oct 92 511 | "read-write" 512 | "read-create" 514 -- uses the NVT ASCII character set 515 Text ::= OCTET STRING 516 END 517 Draft Structure of Management Information for SNMPv2 Oct 92 519 -- definitions for agent capabilities 521 AGENT-CAPABILITIES MACRO ::= 522 BEGIN 523 TYPE NOTATION ::= 524 "PRODUCT-RELEASE" value(release Text) 525 "STATUS" Status 526 "DESCRIPTION" value(description Text) 527 ReferPart 528 ModulePart 530 VALUE NOTATION ::= 531 -- agent's sysObjectID [2] or snmpORID [3] 532 value(VALUE OBJECT IDENTIFIER) 534 Status ::= 535 "current" 536 | "deprecated" 537 | "obsolete" 539 ReferPart ::= 540 "REFERENCE" value (reference Text) 541 | empty 543 ModulePart ::= 544 Modules 545 | empty 546 Modules ::= 547 Module 548 | Modules Module 549 Module ::= 550 -- name of module -- 551 "SUPPORTS" ModuleName 552 "INCLUDES" "{" Groups "}" 553 VariationPart 555 ModuleName ::= 556 identifier ModuleIdentifier 557 ModuleIdentifier ::= 558 value (moduleID OBJECT IDENTIFIER) 559 | empty 561 Groups ::= 562 Group 563 | Groups "," Group 565 Draft Structure of Management Information for SNMPv2 Oct 92 567 Group ::= 568 value(group OBJECT IDENTIFIER) 570 VariationPart ::= 571 Variations 572 | empty 573 Variations ::= 574 Variation 575 | Variations Variation 577 Variation ::= 578 "VARIATION" value(object ObjectName) 579 SyntaxPart 580 WriteSyntaxPart 581 AccessPart 582 CreationPart 583 DefValPart 584 "DESCRIPTION" value(description Text) 586 -- must be a refinement for object's SYNTAX clause 587 SyntaxPart ::= 588 "SYNTAX" type(SYNTAX) 589 | empty 591 -- must be a refinement for object's SYNTAX clause 592 WriteSyntaxPart ::= 593 "WRITE-SYNTAX" type(WriteSYNTAX) 594 | empty 596 AccessPart ::= 597 "ACCESS" Access 598 | empty 600 Access ::= 601 "not-implemented" 602 | "read-only" 603 | "read-write" 604 | "read-create" 605 -- following is for backward-compatibility only 606 | "write-only" 608 CreationPart ::= 609 "CREATION-REQUIRES" "{" Cells "}" 610 | empty 612 Draft Structure of Management Information for SNMPv2 Oct 92 614 Cells ::= 615 Cell 616 | Cells "," Cell 618 Cell ::= 619 value(cell ObjectName) 621 DefValPart ::= 622 "DEFVAL" "{" value (defval ObjectSyntax) "}" 623 | empty 625 -- uses the NVT ASCII character set 626 Text ::= OCTET STRING 627 END 629 END 630 Draft Structure of Management Information for SNMPv2 Oct 92 632 4. Information Modules 634 An "information module" is an ASN.1 module defining 635 information relating to network management. 637 The SMI describes how to use a subset of ASN.1 to define an 638 information module. Further, additional restrictions are 639 placed on "standard" information modules. It is strongly 640 recommended that "enterprise-specific" information modules 641 also adhere to these restrictions. 643 Typically, there are three kinds of information modules: 645 (1) MIB modules, which contain definitions of inter-related 646 managed objects, make use of the OBJECT-TYPE and OBJECT- 647 GROUP macros (if notification definitions are included, | 648 then the NOTIFICATION-TYPE macro is also used); | 650 (2) compliance statements for MIB modules, which make use of 651 the MODULE-COMPLIANCE macros; and, 653 (3) capability statements for agent implementations which 654 make use of the AGENT-CAPABILITIES macros. 656 This classification scheme does not imply a rigid taxonomy. 657 For example, a "standard" information module might include 658 definitions of managed objects and a compliance statement. 659 Similarly, an "enterprise-specific" information module might 660 include definitions of managed objects and a capability 661 statement. Of course, a "standard" information module may not 662 contain capability statements. 664 All information modules start with exactly one invocation of 665 the MODULE-IDENTITY macro, which provides contact and revision 666 history. This invocation must appear immediately after any 667 IMPORTs or EXPORTs statements. 669 4.1. Macro Invocation 671 Within an information module, each macro invocation appears 672 as: 674 ::= 676 Draft Structure of Management Information for SNMPv2 Oct 92 678 where corresponds to an ASN.1 identifier, 679 names the macro being invoked, and and 680 depend on the definition of the macro. 682 An ASN.1 identifier consists of one or more letters, digits, 683 or hyphens. The initial character must be a lower-case 684 letter, and the final character may not be a hyphen. Further, 685 a hyphen may not be immediatedly followed by another hyphen. 687 For all descriptors appearing in an information module, the 688 descriptor shall be unique and mnemonic, and shall not exceed 689 64 characters in length. This promotes a common language for 690 humans to use when discussing the information module and also 691 facilitates simple table mappings for user-interfaces. 693 The set of descriptors defined in all "standard" information 694 modules shall be unique. Further, within each "standard" 695 information module, the hyphen is not allowed as a character 696 in any descriptor. 698 Finally, by convention, if the descriptor refers to an object 699 with a SYNTAX clause value of either Counter32 or Counter64, 700 then the descriptor used for the object should denote 701 plurality. 703 4.1.1. Textual Clauses 705 Some clauses in a macro invocation may take a textual value 706 (e.g., the DESCRIPTION clause). 708 4.2. IMPORTing Symbols 710 When symbols from "enterprise-specific" information modules 711 are referenced (e.g., a descriptor), there is the possibility 712 of collision. 714 To reference an external object, the IMPORTS statement must be | 715 used to identify both the descriptor and the module defining | 716 the descriptor. If two different information modules define | 717 the same descriptor for different objects, then this ambiguity | 718 is resolved by prefixing the descriptor with the name of the | 719 information module and a dot | 720 ("."), i.e., 721 Draft Structure of Management Information for SNMPv2 Oct 92 723 "module.descriptor" | 725 Draft Structure of Management Information for SNMPv2 Oct 92 727 5. Mapping of the MODULE-IDENTITY macro 729 The MODULE-IDENTITY macro is used to provide contact and 730 revision history for each information module. It must appear 731 exactly once in every information module. It should be noted 732 that the expansion of the MODULE-IDENTITY macro is something 733 which conceptually happens during implementation and not 734 during run-time. 736 5.1. Mapping of the LAST-UPDATED clause 738 The LAST-UPDATED clause, which must be present, contains the 739 date and time that this information module was last edited. 741 5.2. Mapping of the ORGANIZATION clause 743 The ORGANIZATION clause, which must be present, contains a 744 textual description of the organization under whose auspices 745 this information module was developed. 747 5.3. Mapping of the CONTACT-INFO clause 749 The CONTACT-INFO clause, which must be present, contains the 750 name, postal address, telephone number, and electronic mail 751 address of the person to whom technical queries concerning 752 this information module should be sent. 754 5.4. Mapping of the DESCRIPTION clause 756 The DESCRIPTION clause, which must be present, contains a 757 high-level textual description of the contents of this 758 information module. 760 5.5. Mapping of the REVISION clause 762 The REVISION clause, which need not be present, is repeatedly 763 used to describe the revisions made to this information 764 module, in reverse chronological order. Each instance of this 765 clause contains the date and time of the revision. 767 Draft Structure of Management Information for SNMPv2 Oct 92 769 Note that the variation concept is meant for generic 770 implementation restrictions, e.g., if the variation for an 771 object depends on the values of other objects, then this 772 should be noted in the appropriate DESCRIPTION clause. 774 5.6. Mapping of the DESCRIPTION clause 776 The DESCRIPTION clause, which must be present for each 777 REVISION clause, contains a high-level textual description of 778 the revision identified in that REVISION clause. 780 5.7. Mapping of the MODULE-IDENTITY value 782 The value of an invocation of the MODULE-IDENTITY macro is an 783 OBJECT IDENTIFIER. As such, this value may be authoritatively 784 used when referring to the information module containing the 785 invocation. 787 Draft Structure of Management Information for SNMPv2 Oct 92 789 5.8. Usage Example 791 Consider how a skeletal MIB module might be constructed: e.g., 793 RFCxxxx-MIB DEFINITIONS ::= BEGIN 795 IMPORTS 796 MODULE-IDENTITY, OBJECT-TYPE, OBJECT-GROUP, experimental 797 FROM SNMPv2-SMI; 799 xxxx MODULE-IDENTITY 800 LAST-UPDATED "9210070433Z" 801 ORGANIZATION "IETF SNMPv2 Working Group" 802 CONTACT-INFO 803 " Marshall T. Rose 805 Postal: Dover Beach Consulting, Inc. 806 420 Whisman Court 807 Mountain View, CA 94043-2186 808 US 810 Tel: +1 415 968 1052 811 Fax: +1 415 968 2510 813 E-mail: mrose@dbc.mtview.ca.us" 814 DESCRIPTION 815 "The MIB module for entities implementing the 816 xxxx protocol." 817 REVISION "9210070433Z" 818 DESCRIPTION 819 "Initial version of this MIB module." 820 -- contact IANA for actual number 821 ::= { experimental xx } 823 END 825 Draft Structure of Management Information for SNMPv2 Oct 92 827 6. Mapping of the OBJECT-TYPE macro 829 The OBJECT-TYPE macro is used to define a managed object. It 830 should be noted that the expansion of the OBJECT-TYPE macro is 831 something which conceptually happens during implementation and 832 not during run-time. 834 6.1. Mapping of the SYNTAX clause 836 The SYNTAX clause, which must be present, defines the abstract 837 data structure corresponding to that object. The data 838 structure must be one of the alternatives defined in the 839 ObjectSyntax CHOICE. Any restriction on size, range, 840 enumerations or repertoire specified in this clause represents 841 the maximal level of support which makes "protocol sense". 843 The semantics of ObjectSyntax are now described. 845 6.1.1. Integer32 and INTEGER 847 The Integer32 type represents integer-valued information 848 between -2^31 and 2^31-1 inclusive (-2147483648 to 2147483647 849 decimal). This type is indistinguishable from the INTEGER 850 type. 852 The INTEGER type may also be used to represent integer-valued 853 information, if it contains named-number enumerations, or if 854 it is subtyped to be more constrained than the Integer32 type. 855 In the former case, only those named-numbers so enumerated may 856 be present as a value. Further, the enumerated values must 857 all be positive. 859 A requirement on "standard" information modules is that the 860 hyphen character is not allowed as a part of the label name 861 for any named-number enumeration. 863 6.1.2. OCTET STRING 865 The OCTET STRING type represents arbitrary binary or textual 866 data. Although there is no SMI-specified size limitation for 867 this type, MIB designers should realize that there may be 868 implementation and interoperability limitations for sizes in 869 Draft Structure of Management Information for SNMPv2 Oct 92 871 excess of 255 octets. 873 6.1.3. OBJECT IDENTIFIER 875 The OBJECT IDENTIFIER type represents administratively 876 assigned names. Any instance of this type may have at most 877 128 sub-identifiers. Further, each sub-identifier must not 878 exceed the value 2^32-1 (4294967295 decimal). 880 6.1.4. BIT STRING 882 The BIT STRING type represents an enumeration of named bits. 883 This collection is assigned non-negative, contiguous values, 884 starting at zero. Only those named-bits so enumerated may be 885 present in a value. 887 A requirement on "standard" MIB modules is that the hyphen 888 character is not allowed as a part of the label name for any 889 named-bit enumeration. 891 6.1.5. IpAddress 893 The IpAddress type represents a 32-bit internet address. It 894 is represented as an OCTET STRING of length 4, in network 895 byte-order. 897 6.1.6. Counter32 899 The Counter32 type represents a non-negative integer which 900 monotonically increases until it reaches a maximum value of 901 2^32-1 (4294967295 decimal), when it wraps around and starts 902 increasing again from zero. 904 Counters have no defined "initial" value, and thus, a single 905 value of a Counter has (in general) no information content. 906 Discontinuities in the monotonically increasing value normally 907 occur at re-initialization of the management system, and at 908 other times as specified in the description of an object-type 909 using this ASN.1 type. If such other times can occur, for 910 example, the creation of an object instance at times other 911 than re-initialization, then a corresponding object should be 912 Draft Structure of Management Information for SNMPv2 Oct 92 914 defined with a SYNTAX clause value of TimeStamp (a textual | 915 convention defined in [4]) | 916 indicating the time of the last discontinuity. 918 The value of the MAX-ACCESS clause for objects with a SYNTAX 919 clause value of Counter32 is always "read-only". 921 6.1.7. Gauge32 923 The Gauge32 type represents a non-negative integer, which may 924 increase or decrease, but shall never exceed a maximum value. 925 The maximum value can not be greater than 2^32-1 (4294967295 926 decimal). The value of a Gauge has its maximum value whenever 927 the information being modeled is greater or equal to that 928 maximum value; if the information being modeled subsequently 929 decreases below the maximum value, the Gauge also decreases. 931 6.1.8. TimeTicks 933 The TimeTicks type represents a non-negative integer which 934 represents the time, modulo 2^32 (4294967296 decimal), in 935 hundredths of a second between two epochs. When objects are 936 defined which use this ASN.1 type, the description of the 937 object identifies both of the reference epochs. 939 6.1.9. Opaque 941 The Opaque type is provided solely for backward-compatibility, 942 and shall not be used for newly-defined object types. 944 The Opaque type supports the capability to pass arbitrary 945 ASN.1 syntax. A value is encoded using the ASN.1 Basic | 946 Encoding Rules [5] into a string | 947 of octets. This, in turn, is encoded as an OCTET STRING, in 948 effect "double-wrapping" the original ASN.1 value. 950 Note that a conforming implementation need only be able to 951 accept and recognize opaquely-encoded data. It need not be 952 able to unwrap the data and then interpret its contents. 954 Further note that by use of the ASN.1 EXTERNAL type, non-ASN.1 955 types may be used in opaquely-encoded data. 957 Draft Structure of Management Information for SNMPv2 Oct 92 959 A requirement on "standard" MIB modules is that no object may 960 have a SYNTAX clause value of Opaque. 962 6.1.10. Counter64 964 The Counter64 type represents a non-negative integer which 965 monotonically increases until it reaches a maximum value of 966 2^64-1 (18446744073709551615 decimal), when it wraps around 967 and starts increasing again from zero. 969 Counters have no defined "initial" value, and thus, a single 970 value of a Counter has (in general) no information content. 971 Discontinuities in the monotonically increasing value normally 972 occur at re-initialization of the management system, and at 973 other times as specified in the description of an object-type 974 using this ASN.1 type. If such other times can occur, for 975 example, the creation of an object instance at times other 976 than re-initialization, then a corresponding object should be 977 defined with a SYNTAX clause value of TimeStamp (a textual | 978 convention defined in [4]) | 979 indicating the time of the last discontinuity. 981 The value of the MAX-ACCESS clause for objects with a SYNTAX 982 clause value of Counter64 is always "read-only". 984 A requirement on "standard" MIB modules is that the Counter64 985 type may be used only if the information being modeled would 986 wrap in less than one hour if the Counter32 type was used 987 instead. 989 6.1.11. NsapAddress 991 The NsapAddress type represents an OSI address as a variable- 992 length OCTET STRING. The first octet of the string contains a 993 binary value in the range of 0..20, and indicates the length 994 in octets of the NSAP. Following the first octet, is the 995 NSAP, expressed in concrete binary notation, starting with the 996 most significant octet. A zero-length NSAP is used as a 997 "special" address meaning "the default NSAP" (analogous to the 998 IP address of 0.0.0.0). Such an NSAP is encoded as a single 999 octet, containing the value 0. All other NSAPs are encoded in 1000 at least 4 octets. 1002 Draft Structure of Management Information for SNMPv2 Oct 92 1004 6.2. Mapping of the UNITS clause 1006 This UNITS clause, which need not be present, contains a 1007 textual definition of the units associated with that object. 1009 6.3. Mapping of the MAX-ACCESS clause 1011 The MAX-ACCESS clause, which must be present, defines whether 1012 it makes "protocol sense" to read, write and/or create an 1013 instance of the object. This is the maximal level of access 1014 for the object. (This maximal level of access is independent 1015 of any administrative authorization policy.) 1017 The value "read-write" indicates that read and write access 1018 make "protocol sense", but create does not. The value "read- 1019 create" indicates that read, write and create access make 1020 "protocol sense". 1022 These values are ordered, from least to greatest: "not- 1023 accessible", "read-only", "read-write", "read-create". 1025 If any columnar object in a conceptual row has "read-create" 1026 as its maximal level of access, then no other columnar object 1027 of the same conceptual row may have a maximal access of 1028 "read-write". (Note that "read-create" is a superset of 1029 "read-write".) 1031 6.4. Mapping of the STATUS clause 1033 The STATUS clause, which must be present, indicates whether 1034 this definition is current or historic. 1036 The values "current", and "obsolete" are self-explanatory. 1037 The "deprecated" value indicates that that object is obsolete, 1038 but that an implementor may wish to support that object to 1039 foster interoperability with older implementations. 1041 6.5. Mapping of the DESCRIPTION clause 1043 The DESCRIPTION clause, which must be present, contains a 1044 textual definition of that object which provides all semantic 1045 definitions necessary for implementation, and should embody 1046 Draft Structure of Management Information for SNMPv2 Oct 92 1048 any information which would otherwise be communicated in any 1049 ASN.1 commentary annotations associated with the object. 1051 6.6. Mapping of the REFERENCE clause 1053 The REFERENCE clause, which need not be present, contains a 1054 textual cross-reference to an object defined in some other 1055 information module. This is useful when de-osifying a MIB 1056 module produced by some other organization. 1058 6.7. Mapping of the INDEX clause 1060 The INDEX clause, which must be present if that object 1061 corresponds to a conceptual row (unless an AUGMENTS clause is 1062 present instead), and must be absent otherwise, defines 1063 instance identification information for the columnar objects 1064 subordinate to that object. 1066 Management operations apply exclusively to scalar objects. 1067 However, it is convenient for developers of management 1068 applications to impose imaginary, tabular structures on the 1069 ordered collection of objects that constitute the MIB. Each 1070 such conceptual table contains zero or more rows, and each row 1071 may contain one or more scalar objects, termed columnar 1072 objects. This conceptualization is formalized by using the 1073 OBJECT-TYPE macro to define both an object which corresponds 1074 to a table and an object which corresponds to a row in that 1075 table. A conceptual table has SYNTAX of the form: 1077 SEQUENCE OF | 1079 where refers to the SEQUENCE type of its | 1080 subordinate conceptual row. | 1081 A conceptual row has SYNTAX of the form: 1083 | 1085 where is a SEQUENCE type defined as follows: + 1087 ::= SEQUENCE { , ... , } + 1089 where there is one for each subordinate object, and 1090 each is of the form: 1092 Draft Structure of Management Information for SNMPv2 Oct 92 1094 1096 where is the descriptor naming a subordinate 1097 object, and has the value of that subordinate 1098 object's SYNTAX clause, optionally omitting the sub-typing 1099 information. Further, these ASN.1 types are always present 1100 (the DEFAULT and OPTIONAL clauses are disallowed in the 1101 SEQUENCE definition). The MAX-ACCESS clause for conceptual 1102 tables and rows is "not-accessible". 1104 For leaf objects which are not columnar objects, instances of 1105 the object are identified by appending a sub-identifier of 1106 zero to the name of that object. Otherwise, the INDEX clause 1107 of the conceptual row object superior to a columnar object 1108 defines instance identification information. 1110 The instance identification information in an INDEX clause 1111 must specify object(s) such that value(s) of those object(s) 1112 will unambiguously distinguish a conceptual row. The syntax 1113 of those objects indicate how to form the instance-identifier: 1115 (1) integer-valued: a single sub-identifier taking the 1116 integer value (this works only for non-negative 1117 integers); 1119 (2) string-valued, fixed-length strings (or variable-length 1120 preceded by the IMPLIED keyword): `n' sub-identifiers, 1121 where `n' is the length of the string (each octet of the 1122 string is encoded in a separate sub-identifier); 1124 (3) string-valued, variable-length strings (not preceded by 1125 the IMPLIED keyword): `n+1' sub-identifiers, where `n' is 1126 the length of the string (the first sub-identifier is `n' 1127 itself, following this, each octet of the string is 1128 encoded in a separate sub-identifier); 1130 (4) object identifier-valued: `n+1' sub-identifiers, where 1131 `n' is the number of sub-identifiers in the value (the 1132 first sub-identifier is `n' itself, following this, each 1133 sub-identifier in the value is copied); 1135 (5) IpAddress-valued: 4 sub-identifiers, in the familiar 1136 a.b.c.d notation. 1138 Draft Structure of Management Information for SNMPv2 Oct 92 1140 (6) NsapAddress-valued: `n' sub-identifiers, where `n' is the 1141 length of the value (each octet of the value is encoded 1142 in a separate sub-identifier); 1144 Note that the IMPLIED keyword can only be present for string- 1145 valued objects, excluding IpAddress- and NsapAddress-valued 1146 objects. 1148 Instances identified by use of integer-valued objects should 1149 be numbered starting from one (i.e., not from zero). The use 1150 of zero as a value for an integer-valued index object should 1151 be avoided, except in special cases. 1153 Objects which are both specified in the INDEX clause of a 1154 conceptual row and also columnar objects of the same 1155 conceptual row are termed auxiliary objects. The MAX-ACCESS 1156 clause for newly-defined auxiliary objects is "not- 1157 accessible". However, a conceptual row must contain at least 1158 one columnar object which is not an auxiliary object (i.e., 1159 the value of the MAX-ACCESS clause for such an object is 1160 either "read-only" or "read-create"). 1162 Note that objects specified in a conceptual row's INDEX clause 1163 need not be columnar objects of that conceptual row. In this 1164 situation, the DESCRIPTION clause of the conceptual row must 1165 include a textual explanation of how the objects which are 1166 included in the INDEX clause but not columnar objects of that 1167 conceptual row, are used in uniquely identifying instances of 1168 the conceptual row's columnar objects. 1170 6.7.1. Creation and Deletion of Conceptual Rows 1172 For newly-defined conceptual rows which allow the creation of 1173 new object instances and the deletion of existing object 1174 instances, there should be one columnar object with a SYNTAX 1175 clause value of RowStatus (a textual convention defined in | 1176 [4]) | 1177 and a MAX-ACCESS clause value of read-create. By convention, 1178 this is termed the status column for the conceptual row. 1180 Draft Structure of Management Information for SNMPv2 Oct 92 1182 6.8. Mapping of the AUGMENTS clause 1184 The AUGMENTS clause, which must not be present unless the 1185 object corresponds to a conceptual row, is an alternative to 1186 the INDEX clause. Every object corresponding to a conceptual 1187 row has either an INDEX clause or an AUGMENTS clause. 1189 If an object corresponding to a conceptual row has an INDEX 1190 clause, that row is termed a base conceptual row; 1191 alternatively, if the object has an AUGMENTS clause, the row 1192 is said to be a conceptual row augmentation, where the 1193 AUGMENTS clause names the object corresponding to the base 1194 conceptual row which is augmented by this conceptual row 1195 extension. Instances of subordinate columnar objects of a 1196 conceptual row extension are identified according to the INDEX 1197 clause of the base conceptual row corresponding to the object 1198 named in the AUGMENTS clause. Further, instances of 1199 subordinate columnar objects of a conceptual row extension 1200 exist according to the same semantics as instances of 1201 subordinate columnar objects of the base conceptual row being 1202 augmented. 1204 For example, a MIB designer might wish to define additional 1205 columns in an "enterprise-specific" MIB which logically extend 1206 a conceptual row in a "standard" MIB. The "standard" MIB 1207 definition of the conceptual row would include the INDEX 1208 clause and the "enterprise-specific" MIB would contain the 1209 definition of a conceptual row using the AUGMENTS clause. 1211 Note that a base conceptual row may be augmented by multiple 1212 conceptual row extensions. 1214 6.9. Mapping of the DEFVAL clause 1216 The DEFVAL clause, which need not be present, defines an 1217 acceptable default value which may be used at the discretion 1218 of an SNMPv2 entity acting in an agent role when an object 1219 instance is created. 1221 During conceptual row creation, if an instance of a columnar 1222 object is not present as one of the operands in the 1223 correspondent management protocol set operation, then the 1224 value of the DEFVAL clause, if present, indicates an 1225 acceptable default value that a SNMPv2 entity acting in an 1226 Draft Structure of Management Information for SNMPv2 Oct 92 1228 agent role might use. 1230 The value of the DEFVAL clause must, of course, correspond to 1231 the SYNTAX clause for the object. If the value is an OBJECT 1232 IDENTIFIER, then it must be expressed as a single ASN.1 1233 identifier, and not as a collection of sub-identifiers. 1235 Note that if an operand to the management protocol set 1236 operation is an instance of a read-only object, then the error 1237 `notWritable' [6] will be returned. As such, the DEFVAL 1238 clause can be used to provide an acceptable default value that 1239 a SNMPv2 entity acting in an agent role might use. 1241 By way of example, consider the following possible DEFVAL 1242 clauses: 1244 ObjectSyntax DEFVAL clause 1245 ----------------- ------------ 1246 Integer32 1 1247 -- same for Gauge32, TimeTicks 1248 INTEGER valid -- enumerated value 1249 OCTET STRING 'ffffffffffff'h 1250 OBJECT IDENTIFIER sysDescr 1251 BIT STRING { primary, secondary } -- enumerated values 1252 IpAddress 'c0210415'h -- 192.33.4.21 1254 Object types with SYNTAX of Counter32 and Counter64 may not 1255 have DEFVAL clauses, since they do not have defined initial 1256 values. However, it is recommended that they be initialized 1257 to zero. 1259 6.10. Mapping of the OBJECT-TYPE value 1261 The value of an invocation of the OBJECT-TYPE macro is the 1262 name of the object, which is an OBJECT IDENTIFIER, an 1263 administratively assigned name. 1265 When an OBJECT IDENTIFIER is assigned to an object: 1267 (1) If the object corresponds to a conceptual table, then 1268 only a single assignment, that for a conceptual row, is 1269 present immediately beneath that object. The 1270 administratively assigned name for the conceptual row 1271 object is derived by appending a sub-identifier of "1" to 1273 Draft Structure of Management Information for SNMPv2 Oct 92 1275 the administratively assigned name for the conceptual 1276 table. 1278 (2) If the object corresponds to a conceptual row, then at 1279 least one assignment, one for each column in the 1280 conceptual row, is present beneath that object. The 1281 administratively assigned name for each column is derived 1282 by appending a unique, positive sub-identifier to the 1283 administratively assigned name for the conceptual row. 1285 (3) Otherwise, no other OBJECT IDENTIFIERs which are 1286 subordinate to the object may be assigned. 1288 Note that the final sub-identifier of any administratively 1289 assigned name for an object shall be positive. A zero-valued 1290 final sub-identifier is reserved for future use. 1292 Further note that although conceptual tables and rows are 1293 given administratively assigned names, these conceptual 1294 objects may not be manipulated in aggregate form by the 1295 management protocol. 1297 6.10.1. Naming Hierarchy 1299 The root of the subtree administered by the Internet Assigned 1300 Numbers Authority (IANA) for the Internet is: 1302 internet OBJECT IDENTIFIER ::= { iso org(3) dod(6) 1 } 1304 That is, the Internet subtree of OBJECT IDENTIFIERs starts 1305 with the prefix: 1307 1.3.6.1. 1309 Several branches underneath this subtree are used for network 1310 management: 1312 mgmt OBJECT IDENTIFIER ::= { internet 2 } 1313 experimental OBJECT IDENTIFIER ::= { internet 3 } 1314 private OBJECT IDENTIFIER ::= { internet 4 } 1315 enterprises OBJECT IDENTIFIER ::= { private 1 } 1317 However, the SMI does not prohibit the definition of objects 1318 in other portions of the object tree. 1320 Draft Structure of Management Information for SNMPv2 Oct 92 1322 The mgmt(2) subtree is used to identify "standard" objects. 1324 The experimental(3) subtree is used to identify objects used 1325 in Internet experiments. As a part of the assignment process, 1326 the IANA may make requirements as to how that subtree is used. 1328 The private(4) subtree is used to identify objects defined 1329 unilaterally. The enterprises(1) subtree beneath private is 1330 used, among other things, to permit providers of networking 1331 subsystems to register models of their products. 1333 Draft Structure of Management Information for SNMPv2 Oct 92 1335 6.11. Usage Example 1337 Consider how one might define a conceptual table and its 1338 subordinates. 1340 evalSlot OBJECT-TYPE 1341 SYNTAX INTEGER 1342 MAX-ACCESS read-only 1343 STATUS current 1344 DESCRIPTION 1345 "The index number of the first unassigned entry in 1346 the evaluation table. 1348 A management station should create new entries in 1349 the evaluation table using this algorithm: first, 1350 issue a management protocol retrieval operation to 1351 determine the value of evalSlot; and, second, 1352 issue a management protocol set operation to 1353 create an instance of the evalStatus object 1354 setting its value to underCreation(1). If this 1355 latter operation succeeds, then the management 1356 station may continue modifying the instances 1357 corresponding to the newly created conceptual row, 1358 without fear of collision with other management 1359 stations." 1360 ::= { eval 1 } 1362 evalTable OBJECT-TYPE 1363 SYNTAX SEQUENCE OF EvalEntry 1364 MAX-ACCESS not-accessible 1365 STATUS current 1366 DESCRIPTION 1367 "The (conceptual) evaluation table." 1368 ::= { eval 2 } 1370 evalEntry OBJECT-TYPE 1371 SYNTAX EvalEntry 1372 MAX-ACCESS not-accessible 1373 STATUS current 1374 DESCRIPTION 1375 "An entry (conceptual row) in the evaluation 1376 table." 1377 INDEX { evalIndex } 1378 ::= { evalTable 1 } 1380 Draft Structure of Management Information for SNMPv2 Oct 92 1382 EvalEntry ::= 1383 SEQUENCE { 1384 evalIndex Integer32, 1385 evalString OCTET STRING, 1386 evalValue Integer32, 1387 evalStatus RowStatus 1388 } 1390 evalIndex OBJECT-TYPE 1391 SYNTAX Integer32 1392 MAX-ACCESS not-accessible 1393 STATUS current 1394 DESCRIPTION 1395 "The auxiliary variable used for identifying 1396 instances of the columnar objects in the 1397 evaluation table." 1398 ::= { evalEntry 1 } 1400 evalString OBJECT-TYPE 1401 SYNTAX OCTET STRING 1402 MAX-ACCESS read-create 1403 STATUS current 1404 DESCRIPTION 1405 "The string to evaluate." 1406 ::= { evalEntry 2 } 1408 evalValue OBJECT-TYPE 1409 SYNTAX Integer32 1410 MAX-ACCESS read-only 1411 STATUS current 1412 DESCRIPTION 1413 "The value when evalString was last executed." 1414 DEFVAL { 0 } 1415 ::= { evalEntry 3 } 1417 evalStatus OBJECT-TYPE 1418 SYNTAX RowStatus 1419 MAX-ACCESS read-create 1420 STATUS current 1421 DESCRIPTION 1422 "The status column used for creating, modifying, 1423 and deleting instances of the columnar objects in 1424 the evaluation table." 1425 DEFVAL { active } 1426 ::= { evalEntry 4 } 1428 Draft Structure of Management Information for SNMPv2 Oct 92 1430 7. Mapping of the OBJECT-GROUP macro 1432 When a MIB module is written, each collection of related 1433 managed objects defined within the MIB module is combined into 1434 a unit of conformance termed a MIB group. The OBJECT-GROUP 1435 macro is used to define each such collection of related 1436 objects. It should be noted that the expansion of the 1437 OBJECT-GROUP macro is something which conceptually happens 1438 during implementation and not during run-time. 1440 To "implement" an object, a SNMPv2 entity acting in an agent 1441 role must return an reasonably accurate value for management 1442 protocol retrieval operations; similarly, if the object is 1443 writable, then in response to a management protocol set 1444 operation, a SNMPv2 entity must accordingly be able to 1445 reasonably influence the underlying managed entity. If a 1446 SNMPv2 entity acting in an agent role can not implement an 1447 object, the management protocol provides for the SNMPv2 entity 1448 to return an exception or error, e.g, noSuchObject [6]. Under 1449 no circumstances shall a SNMPv2 entity return a value for 1450 objects which it does not implement -- it must always return 1451 the appropriate exception or error, as described in the 1452 protocol specification [6]. 1454 7.1. Mapping of the OBJECTS clause 1456 The OBJECTS clause which must be present, is used to name each 1457 object contained in the group. Each of the named objects must 1458 be defined in the same information module as the OBJECT-GROUP 1459 macro appears, and must have a MAX-ACCESS clause value of 1460 "read-only", "read-write", or "read-create". 1462 7.2. Mapping of the STATUS clause 1464 The STATUS clause, which must be present, indicates whether 1465 this definition is current or historic. 1467 The values "current", and "obsolete" are self-explanatory. 1468 The "deprecated" value indicates that that object is obsolete, 1469 but that an implementor may wish to support that object to 1470 foster interoperability with older implementations. 1472 Draft Structure of Management Information for SNMPv2 Oct 92 1474 7.3. Mapping of the DESCRIPTION clause 1476 The DESCRIPTION clause, which must be present, contains a 1477 textual definition of that group, along with a description of 1478 any relations to other groups. Note that generic compliance 1479 requirements should not be stated in this clause. However, 1480 implementation relationships between this group and other 1481 groups may be defined in this clause. 1483 7.4. Mapping of the REFERENCE clause 1485 The REFERENCE clause, which need not be present, contains a 1486 textual cross-reference to a group defined in some other 1487 information module. This is useful when de-osifying a MIB 1488 module produced by some other organization. 1490 7.5. Mapping of the OBJECT-GROUP value 1492 The value of an invocation of the OBJECT-GROUP macro is the 1493 name of the group, which is an OBJECT IDENTIFIER, an 1494 administratively assigned name. 1496 Draft Structure of Management Information for SNMPv2 Oct 92 1498 7.6. Usage Example 1500 Consider how the system group from MIB-II [2] might be 1501 described: 1503 system OBJECT-GROUP 1504 OBJECTS { sysDescr, sysObjectID, sysUpTime, 1505 sysContact, sysName, sysLocation, 1506 sysServices } 1507 STATUS current 1508 DESCRIPTION 1509 "The system group defines objects which are common 1510 to all managed systems." 1511 ::= { mib-2 1 } 1513 Draft Structure of Management Information for SNMPv2 Oct 92 1515 8. Mapping of the NOTIFICATION-TYPE macro 1517 The NOTIFICATION-TYPE macro is used to define the information | 1518 contained within an unsolicited transmission of management | 1519 information (i.e., within either an SNMPv2-Trap-PDU or | 1520 InformRequest-PDU). It should be noted that the expansion of | 1521 the NOTIFICATION-TYPE macro is | 1522 something which conceptually happens during implementation and 1523 not during run-time. - 1525 8.1. Mapping of the OBJECTS clause 1527 The OBJECTS clause, which need not be present, defines the 1528 ordered sequence of MIB objects which are contained within 1529 every instance of the notification. | 1531 8.2. Mapping of the STATUS clause 1533 The STATUS clause, which must be present, indicates whether 1534 this definition is current or historic. 1536 The values "current", and "obsolete" are self-explanatory. 1537 The "deprecated" value indicates that that object is obsolete, 1538 but that an implementor may wish to support that object to 1539 foster interoperability with older implementations. 1541 8.3. Mapping of the DESCRIPTION clause 1543 The DESCRIPTION clause, which must be present, contains a | 1544 textual definition of the notification | 1545 which provides all semantic definitions necessary for 1546 implementation, and should embody any information which would 1547 otherwise be communicated in any ASN.1 commentary annotations 1548 associated with the object. In particular, the DESCRIPTION 1549 clause should document which instances of the objects | 1550 mentioned in the OBJECTS clause should be contained within | 1551 notifications of this type. | 1552 Draft Structure of Management Information for SNMPv2 Oct 92 1554 8.4. Mapping of the REFERENCE clause 1556 The REFERENCE clause, which need not be present, contains a | 1557 textual cross-reference to a notification defined in some | 1558 other | 1559 information module. This is useful when de-osifying a MIB 1560 module produced by some other organization. 1562 8.5. Mapping of the NOTIFICATION-TYPE value 1564 The value of an invocation of the NOTIFICATION-TYPE macro is | 1565 the name of the notification, | 1566 which is an OBJECT IDENTIFIER, an administratively assigned 1567 name. - 1568 Draft Structure of Management Information for SNMPv2 Oct 92 1570 8.6. Usage Example 1572 Consider how a linkUp trap might be described: 1574 linkUp NOTIFICATION-TYPE | 1575 OBJECTS { ifIndex } 1576 STATUS current 1577 DESCRIPTION 1578 "A linkUp trap signifies that the SNMPv2 entity, 1579 acting in an agent role, recognizes that one of 1580 the communication links represented in its 1581 configuration has come up." 1582 ::= { snmpTraps 4 } 1584 According to this invocation, the trap authoritatively 1585 identified as 1587 { snmpTraps 4 } 1589 is used to report a link coming up. | 1590 The instance of ifIndex corresponding to this link will be 1591 present as the third variable in the variable-bindings field. 1593 Note that a SNMPv2 entity acting in an agent role can be 1594 configured to send this trap to zero or more SNMPv2 entities 1595 acting in a manager role, depending on the contents of the 1596 aclTable and viewTable [9] tables. For example, by judicious 1597 use of the viewTable, a SNMPv2 entity acting in an agent role 1598 might be configured to send all linkUp traps to one particular 1599 SNMPv2 entity, and linkUp traps for only certain interfaces to 1600 other SNMPv2 entities. 1602 Draft Structure of Management Information for SNMPv2 Oct 92 1604 9. Mapping of the MODULE-COMPLIANCE macro 1606 The MODULE-COMPLIANCE macro is used to convey a minimum set of 1607 requirements with respect to implementation of one or more MIB 1608 modules. It should be noted that the expansion of the 1609 MODULE-COMPLIANCE macro is something which conceptually 1610 happens during implementation and not during run-time. 1612 A requirement on all "standard" MIB modules is that a 1613 corresponding MODULE-COMPLIANCE specification is also defined, 1614 either in the same information module or in a companion 1615 information module. 1617 9.1. Mapping of the STATUS clause 1619 The STATUS clause, which must be present, indicates whether 1620 this definition is current or historic. 1622 The values "current", and "obsolete" are self-explanatory. 1623 The "deprecated" value indicates that that object is obsolete, 1624 but that an implementor may wish to support that object to 1625 foster interoperability with older implementations. 1627 9.2. Mapping of the DESCRIPTION clause 1629 The DESCRIPTION clause, which must be present, contains a 1630 textual definition of this compliance statement and should 1631 embody any information which would otherwise be communicated 1632 in any ASN.1 commentary annotations associated with the 1633 statement. 1635 9.3. Mapping of the REFERENCE clause 1637 The REFERENCE clause, which need not be present, contains a 1638 textual cross-reference to a compliance statement defined in 1639 some other information module. 1641 9.4. Mapping of the MODULE clause 1643 The MODULE clause, which must be present, is repeatedly used 1644 to name each MIB module for which compliance requirements are 1645 Draft Structure of Management Information for SNMPv2 Oct 92 1647 being specified. Each MIB module is named by its module name, 1648 and optionally, by its associated OBJECT IDENTIFIER as well. 1649 The module name can be omitted when the MODULE-COMPLIANCE 1650 invocation occurs inside a MIB module, to refer to the 1651 encompassing MIB module. 1653 9.4.1. Mapping of the MANDATORY-GROUPS clause 1655 The MANDATORY-GROUPS clause, which need not be present, names 1656 the one or more groups within the correspondent MIB module 1657 which are unconditionally mandatory for implementation. If a 1658 SNMPv2 entity acting in an agent role claims compliance to the 1659 MIB module, then it must implement each and every object 1660 within each group listed. That is, if a SNMPv2 entity returns 1661 a noSuchObject exception in response to a management protocol 1662 get operation [6] for any object within any mandatory group 1663 for every MIB view, then that SNMPv2 entity is not a 1664 conformant implementation of the MIB module. 1666 9.4.2. Mapping of the GROUP clause 1668 The GROUP clause which need not be present, is repeatedly used 1669 to name each MIB group which is conditionally mandatory or 1670 unconditionally optional for compliance to the MIB module. A 1671 MIB group named in a GROUP clause must be absent from the 1672 correspondent MANDATORY-GROUPS clause. 1674 Conditionally mandatory groups include those which are 1675 mandatory only if a particular protocol is implemented, or 1676 only if another group is implemented. A GROUP clause's 1677 DESCRIPTION specifies the conditions under which the group is 1678 conditionally mandatory. 1680 A MIB group which is named in neither a MANDATORY-GROUPS 1681 clause nor a GROUP clause, is unconditionally optional for 1682 compliance to the MIB module. 1684 9.4.3. Mapping of the OBJECT clause 1686 The OBJECT clause which need not be present, is repeatedly 1687 used to name each MIB object for which compliance has a 1688 refined requirement with respect to the MIB module definition. 1690 Draft Structure of Management Information for SNMPv2 Oct 92 1692 The MIB object must be present in one of the groups named in 1693 the correspondent MANDATORY-GROUPS clause or GROUP clauses. 1695 9.4.3.1. Mapping of the SYNTAX clause 1697 The SYNTAX clause, which need not be present, is used to 1698 provide a refined SYNTAX for the object named in the 1699 correspondent OBJECT clause. Note that if this clause and a 1700 WRITE-SYNTAX clause are both present, then this clause only 1701 applies when instances of the object named in the 1702 correspondent OBJECT clause are read. 1704 Consult Section 11 for more information on refined syntax. 1706 9.4.3.2. Mapping of the WRITE-SYNTAX clause 1708 The WRITE-SYNTAX clause, which need not be present, is used to 1709 provide a refined SYNTAX for the object named in the 1710 correspondent OBJECT clause when instances of that object are 1711 written. 1713 Consult Section 11 for more information on refined syntax. 1715 9.4.3.3. Mapping of the MIN-ACCESS clause 1717 The MIN-ACCESS clause, which need not be present, is used to 1718 define the minimal level of access for the object named in the 1719 correspondent OBJECT clause. If this clause is absent, the 1720 minimal level of access is the same as the maximal level 1721 specified in the correspondent invocation of the OBJECT-TYPE 1722 macro. If present, this clause must not specify a greater 1723 level of access than is specified in the correspondent 1724 invocation of the OBJECT-TYPE macro. 1726 The level of access for certain types of objects is fixed 1727 according to their syntax definition. These types are: 1728 conceptual tables and rows, auxiliary objects, and objects 1729 with the syntax of Counter32, Counter64, or certain types of | 1730 textual conventions (e.g., RowStatus [4]). | 1731 A MIN-ACCESS clause should not be present for such objects. 1733 Draft Structure of Management Information for SNMPv2 Oct 92 1735 An implementation is compliant if the level of access it 1736 provides is greater or equal to the minimal level in the 1737 MODULE-COMPLIANCE macro and less or equal to the maximal level 1738 in the OBJECT-TYPE macro. 1740 9.4.3.4. Mapping of the DESCRIPTION clause 1742 The DESCRIPTION clause must be present for each use of the 1743 GROUP or OBJECT clause. For an OBJECT clause, it contains a 1744 textual description of the refined compliance requirement. 1745 For a GROUP clause, it contains a textual description of the 1746 conditions under which the group is conditionally mandatory or 1747 unconditionally optional. 1749 9.5. Mapping of the MODULE-COMPLIANCE value 1751 The value of an invocation of the MODULE-COMPLIANCE macro is 1752 an OBJECT IDENTIFIER. As such, this value may be 1753 authoritatively used when referring to the compliance 1754 requirements embodied by that invocation of the macro. 1756 Draft Structure of Management Information for SNMPv2 Oct 92 1758 9.6. Usage Example 1760 Consider how a compliance statement might be included at the 1761 end of the MIB-II document [2], assuming that objects groups 1762 were defined therein: 1764 rfc1213Compliance MODULE-COMPLIANCE 1765 STATUS current 1766 DESCRIPTION 1767 "The compliance statement for SNMPv2 entities 1768 residing on systems which implement the Internet 1769 suite of protocols." 1770 MODULE -- compliance to the containing MIB module 1771 MANDATORY-GROUPS { system, snmp } 1773 GROUP interfaces 1774 DESCRIPTION 1775 "The interfaces group is mandatory for systems 1776 with network interfaces." 1778 GROUP ip 1779 DESCRIPTION 1780 "The ip group is mandatory for systems which 1781 implement IP." 1783 GROUP icmp 1784 DESCRIPTION 1785 "The icmp group is mandatory for systems which 1786 implement ICMP." 1788 GROUP tcp 1789 DESCRIPTION 1790 "The tcp group is mandatory for systems which 1791 implement TCP." 1792 OBJECT tcpConnState 1793 MIN-ACCESS read-only 1794 DESCRIPTION 1795 "A compliant system need not allow 1796 write-access to this object." 1798 GROUP udp 1799 DESCRIPTION 1800 "The udp group is mandatory for systems which 1801 implement UDP." 1803 Draft Structure of Management Information for SNMPv2 Oct 92 1805 GROUP egp 1806 DESCRIPTION 1807 "The egp group is mandatory for systems which 1808 implement EGP." 1810 ::= { mib2Compliance 1 } 1812 According to this invocation, to claim compliance with the 1813 specification named 1815 { mib2Compliance 1 } 1817 a system must implement RFC1213's system and snmp groups. If 1818 the system implements any network interfaces, then RFC1213's 1819 interfaces group must be implemented. Further, if the system 1820 implements any of the IP, ICMP, TCP, UDP, or EGP protocols, 1821 then the correspondent group in RFC1213 must be implemented, 1822 if compliance is to be claimed. Finally, although RFC1213 1823 specifies that it makes "protocol sense" for the tcpConnState 1824 object to be writable, this specification allows the system to 1825 permit only read-only access and still claim compliance. 1827 Draft Structure of Management Information for SNMPv2 Oct 92 1829 10. Mapping of the AGENT-CAPABILITIES macro 1831 The AGENT-CAPABILITIES macro is used to convey the 1832 capabilities present in a SNMPv2 1833 entity acting in an agent role. It should be noted that the 1834 expansion of the AGENT-CAPABILITIES macro is something which 1835 conceptually happens during implementation and not during 1836 run-time. 1838 When a MIB module is written, it is divided into units of 1839 conformance termed groups. If a SNMPv2 entity acting in an 1840 agent role claims to implement a group, then it must implement 1841 each and every object within that group. Of course, for 1842 whatever reason, a SNMPv2 entity might implement only a subset 1843 of the groups within a MIB module. In addition, the 1844 definition of some MIB objects leave some aspects of the 1845 definition to the discretion of an implementor. 1847 Practical experience has demonstrated a need for concisely 1848 describing the capabilities of an agent with regards to the 1849 MIB groups that it implements. The AGENT-CAPABILITIES macro 1850 allows an agent implementor to describe the precise level of 1851 support which an agent claims in regards to a MIB group, and 1852 to bind that description to the value of sysObjectID [2] 1853 associated with the agent, or to the value of an instance of 1854 the snmpORID object in the snmpORTable [3]. In particular, 1855 some objects may have restricted or augmented syntax or 1856 access-levels. 1858 If the AGENT-CAPABILITIES invocation is given to a 1859 management-station implementor, then that implementor can 1860 build management applications which optimize themselves when 1861 communicating with a particular agent. For example, the 1862 management-station can maintain a database of these 1863 invocations. When a management-station interacts with an 1864 agent, it retrieves the agent's sysObjectID [2]. Based on 1865 this, it consults the database. If an entry is found, then 1866 the management application can optimize its behavior 1867 accordingly. 1869 Note that this binding to sysObjectID may not always suffice 1870 to define all MIB objects to which an agent can provide 1871 access. In particular, this situation occurs where the agent 1872 dynamically learns of the objects it supports. In these 1873 cases, the snmpORID column of snmpORTable [3] contains 1874 Draft Structure of Management Information for SNMPv2 Oct 92 1876 information which should be used in addition to sysObjectID. 1878 Note that the AGENT-CAPABILITIES macro specifies refinements 1879 or variations with respect to OBJECT-TYPE macros in MIB 1880 modules, NOT with respect to MODULE-COMPLIANCE macros in 1881 compliance statements. 1883 10.1. Mapping of the PRODUCT-RELEASE clause 1885 The PRODUCT-RELEASE clause, which must be present, contains a 1886 textual description of the product release which includes this 1887 agent. 1889 10.2. Mapping of the STATUS clause 1891 The STATUS clause, which must be present, indicates whether 1892 this definition is current or historic. 1894 The values "current", and "obsolete" are self-explanatory. 1895 The "deprecated" value indicates that that object is obsolete, 1896 but that an implementor may wish to support that object to 1897 foster interoperability with older implementations. 1899 10.3. Mapping of the DESCRIPTION clause 1901 The DESCRIPTION clause, which must be present, contains a 1902 textual description of this agent. 1904 10.4. Mapping of the REFERENCE clause 1906 The REFERENCE clause, which need not be present, contains a 1907 textual cross-reference to a capability statement defined in 1908 some other information module. 1910 10.5. Mapping of the SUPPORTS clause 1912 The SUPPORTS clause, which need not be present, is repeatedly 1913 used to name each MIB module for which the agent claims a 1914 complete or partial implementation. Each MIB module is named 1915 by its module name, and optionally, by its associated OBJECT 1916 Draft Structure of Management Information for SNMPv2 Oct 92 1918 IDENTIFIER as well. 1920 10.5.1. Mapping of the INCLUDES clause 1922 The INCLUDES clause, which must be present for each use of the 1923 SUPPORTS clause, is used to name each MIB group associated 1924 with the SUPPORT clause, which the agent claims to implement. 1926 10.5.2. Mapping of the VARIATION clause 1928 The VARIATION clause, which need not be present, is repeatedly 1929 used to name each MIB object which the agent implements in 1930 some variant or refined fashion with respect to the 1931 correspondent invocation of the OBJECT-TYPE macro. 1933 Note that the variation concept is meant for generic 1934 implementation restrictions, e.g., if the variation for an 1935 object depends on the values of other objects, then this 1936 should be noted in the appropriate DESCRIPTION clause. 1938 10.5.2.1. Mapping of the SYNTAX clause 1940 The SYNTAX clause, which need not be present, is used to 1941 provide a refined SYNTAX for the object named in the 1942 correspondent VARIATION clause. Note that if this clause and 1943 a WRITE-SYNTAX clause are both present, then this clause only 1944 applies when instances of the object named in the 1945 correspondent VARIATION clause are read. 1947 Consult Section 11 for more information on refined syntax. 1949 10.5.2.2. Mapping of the WRITE-SYNTAX clause 1951 The WRITE-SYNTAX clause, which need not be present, is used to 1952 provide a refined SYNTAX for the object named in the 1953 correspondent VARIATION clause when instances of that object 1954 are written. 1956 Consult Section 11 for more information on refined syntax. 1958 Draft Structure of Management Information for SNMPv2 Oct 92 1960 10.5.2.3. Mapping of the ACCESS clause 1962 The ACCESS clause, which need not be present, is used to 1963 indicate the agent provides less than the maximal level of 1964 access to the object named in the correspondent VARIATION 1965 clause. 1967 The value "not-implemented" indicates the agent does not 1968 implement the object, and in the ordering of possible values 1969 is equivalent to "not-accessible". 1971 The value "write-only" is provided solely for backward 1972 compatibility, and shall not be used for newly-defined object 1973 types. In the ordering of possible values, "write-only" is 1974 less than "not-accessible". 1976 10.5.2.4. Mapping of the CREATION-REQUIRES clause 1978 The CREATION-REQUIRES clause, which need not be present, is 1979 used to name the columnar objects of a conceptual row to which 1980 values must be explicitly assigned, by a management protocol 1981 set operation, before the agent will allow the instance of the 1982 status column of that row to be set to `active(4)'. (Consult | 1983 the definition of RowStatus [4].) | 1985 If the conceptual row does not have a status column (i.e., the 1986 objects corresponding to the conceptual table were defined 1987 using the mechanisms in [7,8]), then the CREATION-REQUIRES 1988 clause, which need not be present, is used to name the 1989 columnar objects of a conceptual row to which values must be 1990 explicitly assigned, by a management protocol set operation, 1991 before the agent will create new instances of objects in that 1992 row. 1994 This clause must not present unless the object named in the 1995 correspondent VARIATION clause is a conceptual row, i.e., has 1996 a syntax which resolves to a SEQUENCE containing columnar 1997 objects. The objects named in the value of this clause 1998 usually will refer to columnar objects in that row. However, 1999 objects unrelated to the conceptual row may also be specified. 2001 All objects which are named in the CREATION-REQUIRES clause 2002 for a conceptual row, and which are columnar objects of that 2003 row, must have an access level of "read-create". 2005 Draft Structure of Management Information for SNMPv2 Oct 92 2007 10.5.2.5. Mapping of the DEFVAL clause 2009 The DEFVAL clause, which need not be present, is used to 2010 provide a refined DEFVAL value for the object named in the 2011 correspondent VARIATION clause. The semantics of this value 2012 are identical to those of the OBJECT-TYPE macro's DEFVAL 2013 clause. 2015 10.5.2.6. Mapping of the DESCRIPTION clause 2017 The DESCRIPTION clause, which must be present for each use of 2018 the VARIATION clause, contains a textual description of the 2019 variant or refined implementation. 2021 10.6. Mapping of the AGENT-CAPABILITIES value 2023 The value of an invocation of the AGENT-CAPABILITIES macro is 2024 an OBJECT IDENTIFIER, which names the value of sysObjectID [2] 2025 or snmpORID [3] for which this capabilities statement is 2026 valid. 2028 Draft Structure of Management Information for SNMPv2 Oct 92 2030 10.7. Usage Example 2032 Consider how a capabilities statement for an agent might be 2033 described: 2035 exampleAgent AGENT-CAPABILITIES 2036 PRODUCT-RELEASE "ACME Agent release 1.1 for 4BSD" 2037 STATUS current 2038 DESCRIPTION "ACME agent for 4BSD" 2040 SUPPORTS RFC1213-MIB 2041 INCLUDES { system, interfaces, at, ip, icmp, 2042 tcp, udp, snmp } 2044 VARIATION ifAdminStatus 2045 SYNTAX INTEGER { up(1), down(2) } 2046 DESCRIPTION "Unable to set test mode on 4BSD" 2048 VARIATION ifOperStatus 2049 SYNTAX INTEGER { up(1), down(2) } 2050 DESCRIPTION "Information limited on 4BSD" 2052 VARIATION atEntry 2053 CREATION-REQUIRES { atPhysAddress } 2054 DESCRIPTION "Address mappings on 4BSD require 2055 both protocol and media addresses" 2057 VARIATION ipDefaultTTL 2058 SYNTAX INTEGER (255..255) 2059 DESCRIPTION "Hard-wired on 4BSD" 2061 VARIATION ipInAddrErrors 2062 ACCESS not-implemented 2063 DESCRIPTION "Information not available on 4BSD" 2065 VARIATION ipRouteType 2066 SYNTAX INTEGER { direct(3), indirect(4) } 2067 WRITE-SYNTAX INTEGER { invalid(2), direct(3), 2068 indirect(4) } 2069 DESCRIPTION "Information limited on 4BSD" 2071 VARIATION tcpConnState 2072 ACCESS read-only 2073 DESCRIPTION "Unable to set this on 4BSD" 2075 Draft Structure of Management Information for SNMPv2 Oct 92 2077 SUPPORTS EVAL-MIB 2078 INCLUDES { functions, expressions } 2079 VARIATION exprEntry 2080 CREATION-REQUIRES { evalString } 2081 DESCRIPTION "Conceptual row creation supported" 2083 ::= { acmeAgents 1 } 2085 According to this invocation, an agent with a sysObjectID (or 2086 snmpORID) value of 2088 { acmeAgents 1 } 2090 supports two MIB modules. 2092 From MIB-II, all groups except the egp group are supported. 2093 However, the object ipInAddrErrors is not implemented, whilst 2094 the objects 2096 ifAdminStatus 2097 ifOperStatus 2098 ipDefaultTTL 2099 ipRouteType 2101 have a restricted syntax, and the object 2103 tcpConnState 2105 is available only for reading. Note that in the case of the 2106 object ipRouteType the set of values which may be read is 2107 different than the set of values which may be written. 2108 Finally, when creating a new instance in the atTable, the 2109 set-request must create an instance of atPhysAddress. 2111 From the EVAL-MIB, all the objects contained in the functions 2112 and expressions groups are supported, without variation. In 2113 addition, creation of new instances in the expr table is 2114 supported. 2116 Draft Structure of Management Information for SNMPv2 Oct 92 2118 11. Refined Syntax 2120 The SYNTAX and WRITE-SYNTAX clauses in the MODULE-COMPLIANCE 2121 and AGENT-CAPABILITIES macros allow an object's syntax to be 2122 refined. However, not all refinements of syntax are 2123 appropriate. In particular, the object's primitive or 2124 application type must not be changed. 2126 Further, the following restrictions apply: 2128 Restrictions to Refinement on 2129 object syntax range enumeration size repertoire 2130 ----------------- ----- ----------- ---- ---------- 2131 INTEGER (1) (2) - - 2132 OCTET STRING - - (3) (4) 2133 OBJECT IDENTIFIER - - - - 2134 BIT STRING - (2) - - 2135 IpAddress - - - - 2136 Counter32 - - - - 2137 Gauge32 (1) - - - 2138 TimeTicks - - - - 2139 Counter64 - - - - 2140 NsapAddress - - - - 2142 where: 2144 (1) the range of permitted values may be refined by raising 2145 the lower-bounds, by reducing the upper-bounds, and/or by 2146 reducing the alternative value/range choices; 2148 (2) the enumeration of named-values may be refined by 2149 removing one or more named-values; 2151 (3) the size in characters of the value may be refined by 2152 raising the lower-bounds, by reducing the upper-bounds, 2153 and/or by reducing the alternative size choices; or, 2155 (4) the repertoire of characters in the value may be reduced 2156 by further sub-typing. 2158 Otherwise no refinements are possible. 2160 Note that when refining an object with a SYNTAX clause value 2161 of Integer32, then the refined SYNTAX is expressed as an 2162 INTEGER and the restrictions of the table above are used. 2164 Draft Structure of Management Information for SNMPv2 Oct 92 2166 12. Extending an Information Module 2168 As experience is gained with a published information module, 2169 it may be desirable to revise that information module. 2171 12.1. Object Definitions 2173 An object definition may be revised in any of the following 2174 ways: 2176 (1) Existing objects with a status of "current" may be 2177 revised as "deprecated" or "obsolete". Similarly, 2178 objects with a status of "deprecated" may be revised as 2179 "obsolete". 2181 (2) A DEFVAL clause may be added or updated. 2183 (3) A REFERENCE clause may be added or updated. 2185 (4) A UNITS clause may be added. 2187 (5) A conceptual row may be augmented by adding new columnar 2188 objects at the end of the row. 2190 (6) Entirely new objects may be defined, named with 2191 previously unassigned OBJECT IDENTIFIER values. 2193 However, if the semantics of any previously defined object are 2194 changed (i.e., if a non-editorial change is made to any clause 2195 other those specifically allowed above), then the OBJECT 2196 IDENTIFIER value associated with that object must also be 2197 changed. 2199 Finally, note that changing the descriptor associated with an 2200 existing object, is not considered a semantic change, as these 2201 strings are used solely for local use, and are not passed via 2202 the management protocol. 2204 12.2. Trap Definitions 2206 A trap definition may be revised in any of the following ways: 2208 Draft Structure of Management Information for SNMPv2 Oct 92 2210 (1) A REFERENCE clause may be added or updated. 2212 However, if the semantics of any previously defined trap are 2213 changed (i.e., if a non-editorial change is made to any clause 2214 other those specifically allowed above), then the OBJECT 2215 IDENTIFIER value associated with that trap must also be 2216 changed. 2218 Finally, note that changing the descriptor associated with an 2219 existing trap, is not considered a semantic change, as these 2220 strings are used solely for local use, and are not passed via 2221 the management protocol. 2223 12.3. Compliance Definitions 2225 If any non-editorial change is made to any clause of a 2226 compliance definition, then the OBJECT IDENTIFIER value 2227 associated with that compliance definition must also be 2228 changed, along with its associated descriptor. 2230 12.4. Capabilities Definitions 2232 If any non-editorial change is made to any clause of a 2233 capabilities definition, then the OBJECT IDENTIFIER value 2234 associated with that capabilities definition must also be 2235 changed, along with its associated descriptor. 2237 Draft Structure of Management Information for SNMPv2 Oct 92 2239 13. Appendix: de-OSIfying a MIB module 2241 There has been an increasing amount of work recently on taking 2242 MIBs defined by other organizations (e.g., the IEEE) and de- 2243 osifying them for use with the Internet-standard network 2244 management framework. The steps to achieve this are 2245 straight-forward, though tedious. Of course, it is helpful to 2246 already be experienced in writing MIB modules for use with the 2247 Internet-standard network management framework. 2249 The first step is to construct a skeletal MIB module, as shown 2250 earlier in Section 5.8. The next step is to categorize the 2251 objects into groups. Optional objects are not permitted. 2252 Thus, when a MIB module is created, optional objects must be 2253 placed in a optional group, which, if implemented, all objects 2254 in the group must be implemented. For the first pass, it is 2255 wisest to simply ignore any optional objects in the original 2256 MIB: experience shows it is better to define a core MIB module 2257 first, containing only essential objects; later, if experience 2258 demands, other objects can be added. 2260 13.1. Managed Object Mapping 2262 Next for each managed object class, determine whether there 2263 can exist multiple instances of that managed object class. If 2264 not, then for each of its attributes, use the OBJECT-TYPE 2265 macro to make an equivalent definition. 2267 Otherwise, if multiple instances of the managed object class 2268 can exist, then define a conceptual table having conceptual 2269 rows each containing a columnar object for each of the managed 2270 object class's attributes. If the managed object class is 2271 contained within the containment tree of another managed 2272 object class, then the assignment of an object is normally 2273 required for each of the "distinguished attributes" of the 2274 containing managed object class. If they do not already exist 2275 within the MIB module, then they can be added via the 2276 definition of additional columnar objects in the conceptual 2277 row corresponding to the contained managed object class. 2279 In defining a conceptual row, it is useful to consider the 2280 optimization of network management operations which will act 2281 upon its columnar objects. In particular, it is wisest to 2282 avoid defining more columnar objects within a conceptual row, 2283 Draft Structure of Management Information for SNMPv2 Oct 92 2285 than can fit in a single PDU. As a rule of thumb, a 2286 conceptual row should contain no more than approximately 20 2287 objects. Similarly, or as a way to abide by the "20 object 2288 guideline", columnar objects should be grouped into tables 2289 according to the expected grouping of network management 2290 operations upon them. As such, the content of conceptual rows 2291 should reflect typical access scenarios, e.g., they should be 2292 organized along functional lines such as one row for 2293 statistics and another row for parameters, or along usage 2294 lines such as commonly-needed objects versus rarely-needed 2295 objects. 2297 On the other hand, the definition of conceptual rows where the 2298 number of columnar objects used as indexes outnumbers the 2299 number used to hold information, should also be avoided. In 2300 particular, the splitting of a managed object class's 2301 attributes into many conceptual tables should not be used as a 2302 way to obtain the same degree of flexibility/complexity as is 2303 often found in MIBs with a myriad of optionals. 2305 13.1.1. Mapping to the SYNTAX clause 2307 When mapping to the SYNTAX clause of the OBJECT-type macro: 2309 (1) An object with BOOLEAN syntax becomes a TruthValue [4]. | 2311 (2) An object with INTEGER syntax becomes an Integer32. 2313 (3) An object with ENUMERATED syntax becomes an INTEGER with 2314 enumerations, taking any of the values given which can be 2315 represented with an Integer32. 2317 (4) An object with BIT STRING syntax but no enumerations 2318 becomes an OCTET STRING. 2320 (5) An object with a character string syntax becomes either 2321 an OCTET STRING, or a DisplayString [4], | 2322 depending on the repertoire of the character string. 2324 (6) A non-tabular object with a complex syntax, such as REAL 2325 or EXTERNAL, must be decomposed, usually into an OCTET 2326 STRING (if sensible). As a rule, any object with a 2327 complicated syntax should be avoided. 2329 Draft Structure of Management Information for SNMPv2 Oct 92 2331 (7) Tabular objects must be decomposed into rows of columnar 2332 objects. 2334 13.1.2. Mapping to the UNITS clause 2336 If the description of this managed object defines a unit- 2337 basis, then mapping to this clause is straight-forward. 2339 13.1.3. Mapping to the MAX-ACCESS clause 2341 This is straight-forward. 2343 13.1.4. Mapping to the STATUS clause 2345 This is straight-forward. 2347 13.1.5. Mapping to the DESCRIPTION clause 2349 This is straight-forward: simply copy the text, making sure 2350 that any embedded double quotation marks are sanitized (i.e., 2351 replaced with single-quotes or removed). 2353 13.1.6. Mapping to the REFERENCE clause 2355 This is straight-forward: simply include a textual reference 2356 to the object being mapped, the document which defines the 2357 object, and perhaps a page number in the document. 2359 13.1.7. Mapping to the INDEX clause 2361 If necessary, decide how instance-identifiers for columnar 2362 objects are to be formed and define this clause accordingly. 2364 13.1.8. Mapping to the DEFVAL clause 2366 Decide if a meaningful default value can be assigned to the 2367 object being mapped, and if so, define the DEFVAL clause 2368 accordingly. 2370 Draft Structure of Management Information for SNMPv2 Oct 92 2372 13.2. Action Mapping 2374 Actions are modeled as read-write objects, in which writing a 2375 particular value results in a state change. (Usually, as a 2376 part of this state change, some action might take place.) 2378 13.2.1. Mapping to the SYNTAX clause 2380 Usually the Integer32 syntax is used with a distinguished 2381 value provided for each action that the object provides access 2382 to. In addition, there is usually one other distinguished 2383 value, which is the one returned when the object is read. 2385 13.2.2. Mapping to the MAX-ACCESS clause 2387 Always use read-write or read-create. 2389 13.2.3. Mapping to the STATUS clause 2391 This is straight-forward. 2393 13.2.4. Mapping to the DESCRIPTION clause 2395 This is straight-forward: simply copy the text, making sure 2396 that any embedded double quotation marks are sanitized (i.e., 2397 replaced with single-quotes or removed). 2399 13.2.5. Mapping to the REFERENCE clause 2401 This is straight-forward: simply include a textual reference 2402 to the action being mapped, the document which defines the 2403 action, and perhaps a page number in the document. 2405 13.3. Event Mapping 2407 Events are modeled as SNMPv2 traps using NOTIFICATION-TYPE | 2408 macro. | 2409 However, recall that SNMPv2 emphasizes trap-directed polling. 2410 As such, few, and usually no, traps, need be defined for any 2411 Draft Structure of Management Information for SNMPv2 Oct 92 2413 MIB module. 2415 13.3.1. Mapping to the STATUS clause 2417 This is straight-forward. 2419 13.3.2. Mapping to the DESCRIPTION clause 2421 This is straight-forward: simply copy the text, making sure 2422 that any embedded double quotation marks are sanitized (i.e., 2423 replaced with single-quotes or removed). 2425 13.3.3. Mapping to the REFERENCE clause 2427 This is straight-forward: simply include a textual reference | 2428 to the notification being mapped, the document which defines | 2429 the notification, | 2430 and perhaps a page number in the document. 2432 Draft Structure of Management Information for SNMPv2 Oct 92 2434 14. Acknowledgements 2436 The section on object definitions (and MIB de-osification) is 2437 based, in part, on RFCs 1155 and 1212. The IMPLIED keyword is 2438 based on a conversation with David T. Perkins in December, 2439 1991. 2441 The section on trap definitions is based, in part, on RFC 2442 1215. 2444 The section on compliance definitions is based, in part, on a 2445 conversation with James R. Davin in December, 1990. 2447 The section on capabilities definitions is based, in part, on 2448 RFC 1303. 2450 Finally, the comments of the SNMP Version 2 working group are 2451 gratefully acknowledged: 2453 Steve Alexander, Interactive Systems 2454 Uri Blumenthal, International Business Machines 2455 Jeffrey D. Case, SNMP Research, Inc. 2456 Tracy Cox, Bellcore 2457 James R. (Chuck) Davin, Bellcore 2458 Mike Davison, FiberCom 2459 Taso N. Devetzis, Bellcore 2460 Gary W. Haney, Martin Marietta Energy Systems 2461 Matt Hecht, SNMP Research, Inc. 2462 Susan E. Hicks, Martin Marietta Energy Systems 2463 Satish Joshi, SynOptics 2464 Mark Kepke, Hewlett-Packard 2465 Ken Key, SNMP Research, Inc. 2466 Michael Kornegay, Visisoft 2467 Deidre C. Kostick, Bellcore 2468 Cheryl Krupczak, Georgia Tech 2469 Robert C. Lushbaugh, Martin Marietta Energy Systems 2470 Keith McCloghrie, Hughes LAN Systems 2471 Dave Minnich, FiberCom 2472 Dave Perkins, SynOptics 2473 Marshall T. Rose, Dover Beach Consulting, Inc. 2474 Shawn A. Routhier, Epilogue Technology 2475 Jon Saperia, Digital Equipment Corporation 2476 Bob Stewart, Xyplex (chair) 2477 Robert Synder, Cisco Systems 2478 Maurice Turcotte, Racal Datacom 2480 Draft Structure of Management Information for SNMPv2 Oct 92 2482 Steven L. Waldbusser, Carnegie Mellon University 2483 Bert Wijnen, International Business Machines 2484 Peter Wilson, 3Com 2485 Steven Wong, Digital Equipment Corporation 2486 Chris Young, Cabletron 2487 Kiho Yum, 3Com 2489 Draft Structure of Management Information for SNMPv2 Oct 92 2491 15. References 2493 [1] Information processing systems - Open Systems 2494 Interconnection - Specification of Abstract Syntax 2495 Notation One (ASN.1), International Organization for 2496 Standardization. International Standard 8824, (December, 2497 1987). 2499 [2] K. McCloghrie and M.T. Rose, Management Information Base 2500 for Network Management of TCP/IP-based internets: MIB-II. 2501 Request for Comments 1213, (March, 1991). 2503 [3] J.D. Case, K. McCloghrie, M.T. Rose, S.L. Waldbusser, 2504 Management Information Base for version 2 of the Simple 2505 Network Management Protocol, Internet-Draft, (October 7, 2506 1992). 2508 [4] - 2509 J.D. Case, K. McCloghrie, M.T. Rose, S.L. Waldbusser, 2510 Textual Conventions for version 2 of the the Simple 2511 Network Management Protocol (SNMPv2), Internet-Draft, 2512 (October 7, 1992). 2514 [5] Information processing systems - Open Systems + 2515 Interconnection - Specification of Basic Encoding Rules + 2516 for Abstract Syntax Notation One (ASN.1), International + 2517 Organization for Standardization. International Standard + 2518 8825, (December, 1987). + 2520 [6] J.D. Case, K. McCloghrie, M.T. Rose, S.L. Waldbusser, 2521 Protocol Operations for version 2 of the Simple Network 2522 Management Protocol (SNMPv2), Internet-Draft, (October 7, 2523 1992). 2525 [7] M.T. Rose and K. McCloghrie, Structure and Identification 2526 of Management Information for TCP/IP-based internets. 2527 Request for Comments 1155, (May, 1990). 2529 [8] M.T. Rose and K. McCloghrie, Concise MIB Definitions. 2530 Request for Comments 1212, (March, 1991). 2532 [9] K. McCloghrie, J.R. Davin, J.M. Galvin, Definitions of 2533 Managed Objects for Administration of SNMP Parties. 2534 Request for Comments 1353, (July, 1992). 2536 Draft Structure of Management Information for SNMPv2 Oct 92 2538 Table of Contents 2540 1 Status of this Memo ................................... 1 2541 2 Introduction .......................................... 2 2542 2.1 A Note on Terminology ............................... 3 2543 3 Definitions ........................................... 4 2544 3.1 The MODULE-IDENTITY macro ........................... 5 2545 3.2 The OBJECT-TYPE macro ............................... 6 2546 3.3 Object Names and Syntaxes ........................... 8 2547 3.4 The OBJECT-GROUP macro .............................. 11 2548 3.5 The NOTIFICATION-TYPE macro ......................... 12 2549 3.6 The MODULE-COMPLIANCE macro ......................... 13 2550 3.7 The AGENT-CAPABILITIES macro ........................ 16 2551 4 Information Modules ................................... 19 2552 4.1 Macro Invocation .................................... 19 2553 4.1.1 Textual Clauses ................................... 20 2554 4.2 IMPORTing Symbols ................................... 20 2555 5 Mapping of the MODULE-IDENTITY macro .................. 22 2556 5.1 Mapping of the LAST-UPDATED clause .................. 22 2557 5.2 Mapping of the ORGANIZATION clause .................. 22 2558 5.3 Mapping of the CONTACT-INFO clause .................. 22 2559 5.4 Mapping of the DESCRIPTION clause ................... 22 2560 5.5 Mapping of the REVISION clause ...................... 22 2561 5.6 Mapping of the DESCRIPTION clause ................... 23 2562 5.7 Mapping of the MODULE-IDENTITY value ................ 23 2563 5.8 Usage Example ....................................... 24 2564 6 Mapping of the OBJECT-TYPE macro ...................... 25 2565 6.1 Mapping of the SYNTAX clause ........................ 25 2566 6.1.1 Integer32 and INTEGER ............................. 25 2567 6.1.2 OCTET STRING ...................................... 25 2568 6.1.3 OBJECT IDENTIFIER ................................. 26 2569 6.1.4 BIT STRING ........................................ 26 2570 6.1.5 IpAddress ......................................... 26 2571 6.1.6 Counter32 ......................................... 26 2572 6.1.7 Gauge32 ........................................... 27 2573 6.1.8 TimeTicks ......................................... 27 2574 6.1.9 Opaque ............................................ 27 2575 6.1.10 Counter64 ........................................ 28 2576 6.1.11 NsapAddress ...................................... 28 2577 6.2 Mapping of the UNITS clause ......................... 29 2578 6.3 Mapping of the MAX-ACCESS clause .................... 29 2579 6.4 Mapping of the STATUS clause ........................ 29 2580 6.5 Mapping of the DESCRIPTION clause ................... 29 2581 6.6 Mapping of the REFERENCE clause ..................... 30 2582 Draft Structure of Management Information for SNMPv2 Oct 92 2584 6.7 Mapping of the INDEX clause ......................... 30 2585 6.7.1 Creation and Deletion of Conceptual Rows .......... 32 2586 6.8 Mapping of the AUGMENTS clause ...................... 33 2587 6.9 Mapping of the DEFVAL clause ........................ 33 2588 6.10 Mapping of the OBJECT-TYPE value ................... 34 2589 6.10.1 Naming Hierarchy ................................. 35 2590 6.11 Usage Example ...................................... 37 2591 7 Mapping of the OBJECT-GROUP macro ..................... 39 2592 7.1 Mapping of the OBJECTS clause ....................... 39 2593 7.2 Mapping of the STATUS clause ........................ 39 2594 7.3 Mapping of the DESCRIPTION clause ................... 40 2595 7.4 Mapping of the REFERENCE clause ..................... 40 2596 7.5 Mapping of the OBJECT-GROUP value ................... 40 2597 7.6 Usage Example ....................................... 41 2598 8 Mapping of the NOTIFICATION-TYPE macro ................ 42 2599 8.1 Mapping of the OBJECTS clause ....................... 42 2600 8.2 Mapping of the STATUS clause ........................ 42 2601 8.3 Mapping of the DESCRIPTION clause ................... 42 2602 8.4 Mapping of the REFERENCE clause ..................... 43 2603 8.5 Mapping of the NOTIFICATION-TYPE value .............. 43 2604 8.6 Usage Example ....................................... 44 2605 9 Mapping of the MODULE-COMPLIANCE macro ................ 45 2606 9.1 Mapping of the STATUS clause ........................ 45 2607 9.2 Mapping of the DESCRIPTION clause ................... 45 2608 9.3 Mapping of the REFERENCE clause ..................... 45 2609 9.4 Mapping of the MODULE clause ........................ 45 2610 9.4.1 Mapping of the MANDATORY-GROUPS clause ............ 46 2611 9.4.2 Mapping of the GROUP clause ....................... 46 2612 9.4.3 Mapping of the OBJECT clause ...................... 46 2613 9.4.3.1 Mapping of the SYNTAX clause .................... 47 2614 9.4.3.2 Mapping of the WRITE-SYNTAX clause .............. 47 2615 9.4.3.3 Mapping of the MIN-ACCESS clause ................ 47 2616 9.4.3.4 Mapping of the DESCRIPTION clause ............... 48 2617 9.5 Mapping of the MODULE-COMPLIANCE value .............. 48 2618 9.6 Usage Example ....................................... 49 2619 10 Mapping of the AGENT-CAPABILITIES macro .............. 51 2620 10.1 Mapping of the PRODUCT-RELEASE clause .............. 52 2621 10.2 Mapping of the STATUS clause ....................... 52 2622 10.3 Mapping of the DESCRIPTION clause .................. 52 2623 10.4 Mapping of the REFERENCE clause .................... 52 2624 10.5 Mapping of the SUPPORTS clause ..................... 52 2625 10.5.1 Mapping of the INCLUDES clause ................... 53 2626 10.5.2 Mapping of the VARIATION clause .................. 53 2627 10.5.2.1 Mapping of the SYNTAX clause ................... 53 2628 10.5.2.2 Mapping of the WRITE-SYNTAX clause ............. 53 2629 Draft Structure of Management Information for SNMPv2 Oct 92 2631 10.5.2.3 Mapping of the ACCESS clause ................... 54 2632 10.5.2.4 Mapping of the CREATION-REQUIRES clause ........ 54 2633 10.5.2.5 Mapping of the DEFVAL clause ................... 55 2634 10.5.2.6 Mapping of the DESCRIPTION clause .............. 55 2635 10.6 Mapping of the AGENT-CAPABILITIES value ............ 55 2636 10.7 Usage Example ...................................... 56 2637 11 Refined Syntax ....................................... 58 2638 12 Extending an Information Module ...................... 59 2639 12.1 Object Definitions ................................. 59 2640 12.2 Trap Definitions ................................... 59 2641 12.3 Compliance Definitions ............................. 60 2642 12.4 Capabilities Definitions ........................... 60 2643 13 Appendix: de-OSIfying a MIB module ................... 61 2644 13.1 Managed Object Mapping ............................. 61 2645 13.1.1 Mapping to the SYNTAX clause ..................... 62 2646 13.1.2 Mapping to the UNITS clause ...................... 63 2647 13.1.3 Mapping to the MAX-ACCESS clause ................. 63 2648 13.1.4 Mapping to the STATUS clause ..................... 63 2649 13.1.5 Mapping to the DESCRIPTION clause ................ 63 2650 13.1.6 Mapping to the REFERENCE clause .................. 63 2651 13.1.7 Mapping to the INDEX clause ...................... 63 2652 13.1.8 Mapping to the DEFVAL clause ..................... 63 2653 13.2 Action Mapping ..................................... 64 2654 13.2.1 Mapping to the SYNTAX clause ..................... 64 2655 13.2.2 Mapping to the MAX-ACCESS clause ................. 64 2656 13.2.3 Mapping to the STATUS clause ..................... 64 2657 13.2.4 Mapping to the DESCRIPTION clause ................ 64 2658 13.2.5 Mapping to the REFERENCE clause .................. 64 2659 13.3 Event Mapping ...................................... 64 2660 13.3.1 Mapping to the STATUS clause ..................... 65 2661 13.3.2 Mapping to the DESCRIPTION clause ................ 65 2662 13.3.3 Mapping to the REFERENCE clause .................. 65 2663 14 Acknowledgements ..................................... 66 2664 15 References ........................................... 68