idnits 2.17.1 draft-ietf-ops-mib-review-guidelines-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 643 has weird spacing: '...est the agent...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 2003) is 7559 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 2493 (Obsoleted by RFC 3593) ** Obsolete normative reference: RFC 2021 (Obsoleted by RFC 4502) ** Obsolete normative reference: RFC 3291 (Obsoleted by RFC 4001) -- Obsolete informational reference (is this intentional?): RFC 2932 (Obsoleted by RFC 5132) -- Obsolete informational reference (is this intentional?): RFC 1573 (Obsoleted by RFC 2233) -- Obsolete informational reference (is this intentional?): RFC 2576 (Obsoleted by RFC 3584) -- Obsolete informational reference (is this intentional?): RFC 2737 (Obsoleted by RFC 4133) -- Obsolete informational reference (is this intentional?): RFC 1595 (Obsoleted by RFC 2558) -- Obsolete informational reference (is this intentional?): RFC 2558 (Obsoleted by RFC 3592) Summary: 7 errors (**), 0 flaws (~~), 5 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET DRAFT C. M. Heard, Editor 3 Consultant 4 August 2003 6 Guidelines for MIB Authors and Reviewers 8 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its areas, 15 and its working groups. Note that other groups may also distribute 16 working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html 29 Comments on this memo should be submitted to the 30 mailing list. To subscribe to this mailing list send an e-mail 31 message to with the word "subscribe" in 32 the message body. 34 Copyright Notice 36 Copyright (C) The Internet Society (2003). All Rights Reserved. 38 Abstract 40 This memo provides guidelines for authors and reviewers of IETF 41 standards-track specifications containing MIB modules. Applicable 42 portions may used as a basis for reviews of other MIB documents. 44 Table of Contents 46 1 Introduction .............................................. 4 47 2 Terminology ............................................... 4 48 3 General Documentation Guidelines .......................... 5 49 3.1 MIB Boilerplate Section ................................. 5 50 3.2 Narrative Sections ...................................... 5 51 3.3 Definitions Section ..................................... 6 52 3.4 Intellectual Property Section ........................... 6 53 3.5 References Sections ..................................... 6 54 3.6 Security Considerations Section ......................... 7 55 3.7 IANA Considerations Section ............................. 7 56 3.8 Copyright Notices ....................................... 8 57 4 SMIv2 Usage Guidelines .................................... 9 58 4.1 Module Names ............................................ 9 59 4.2 Descriptors, TC Names, and Labels ....................... 9 60 4.3 Naming Hierarchy ........................................ 10 61 4.4 IMPORTS Statement ....................................... 10 62 4.5 MODULE-IDENTITY Invocation .............................. 11 63 4.6 Textual Conventions and Object Definitions .............. 13 64 4.6.1 Usage of Data Types ................................... 13 65 4.6.1.1 INTEGER, Integer32, Gauge32, and Unsigned32 ......... 13 66 4.6.1.2 Counter32 and Counter64 ............................. 14 67 4.6.1.3 CounterBasedGauge64 ................................. 16 68 4.6.1.4 OCTET STRING ........................................ 16 69 4.6.1.5 OBJECT IDENTIFIER ................................... 16 70 4.6.1.6 The BITS Construct .................................. 17 71 4.6.1.7 IpAddress ........................................... 17 72 4.6.1.8 TimeTicks ........................................... 17 73 4.6.1.9 TruthValue .......................................... 18 74 4.6.1.10 Other Data Types ................................... 18 75 4.6.2 DESCRIPTION and REFERENCE Clauses ..................... 19 76 4.6.3 DISPLAY-HINT Clause ................................... 19 77 4.6.4 Conceptual Table Definitions .......................... 19 78 4.6.5 OID Values Assigned to Objects ........................ 21 79 4.6.6 OID Length Limitations and Table Indexing ............. 22 80 4.7 Notification Definitions ................................ 23 81 4.8 Compliance Statements ................................... 24 82 4.9 Revisions to MIB Modules ................................ 26 83 Appendix A: MIB Review Checklist .......................... 30 84 Appendix B: Commonly Used Textual Conventions ............. 32 85 Appendix C: Suggested Naming Conventions .................. 34 86 Appendix D: Suggested OID Layout .......................... 35 87 Intellectual Property ...................................... 36 88 Normative References ....................................... 37 89 Informative References ..................................... 38 90 Security Considerations .................................... 40 91 Acknowledgments ............................................ 40 92 Editor's Address ........................................... 40 93 Full Copyright Statement ................................... 41 95 1. Introduction 97 Some time ago the IESG instituted a policy of requiring expert review 98 of IETF standards-track specifications containing MIB modules. These 99 reviews were established to ensure that such specifications follow 100 established IETF documentation practices and that the MIB modules 101 they contain meet certain generally accepted standards of quality, 102 including (but not limited to) compliance with all syntactic and 103 semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579] [RFC2580] 104 that are applicable to "standard" MIB modules. The purpose of this 105 memo is to document the guidelines that are followed in such reviews. 107 Please note that the guidelines in this memo are not intended to 108 alter requirements or prohibitions (in the sense of "MUST", "MUST 109 NOT", "SHALL", or "SHALL NOT" as defined in RFC 2119 [RFC2119]) of 110 existing BCPs or Internet Standards except where those requirements 111 or prohibitions are ambiguous or contradictory. In the exceptional 112 cases where ambiguities or contradictions exist this memo documents 113 the current generally accepted interpretation. In certain instances 114 the guidelines in this memo do alter recommendations (in the sense of 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", or "NOT RECOMMENDED" as 116 defined in RFC 2119) of existing BCPs or Internet Standards. This 117 has been done where practical experience has shown that the published 118 recommendations are suboptimal. In addition, this memo provides 119 guidelines for the selection of certain SMIv2 options (in the sense 120 of "MAY" or "OPTIONAL" as defined in RFC 2119) in cases where there 121 is a consensus on a preferred approach. 123 Although some of the guidelines in this memo are not applicable to 124 non-standards track or non-IETF MIB documents, authors and reviewers 125 of those documents should consider using the ones that do apply. 127 Reviewers and authors need to be aware that some of the guidelines in 128 in this memo do not apply to MIB modules that have been translated to 129 SMIv2 from SMIv1 (STD 16) [RFC1155] [RFC1212] [RFC1215]. 131 2. Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL", when used in the guidelines in this memo, are to be 136 interpreted as described in RFC 2119 [RFC2119]. 138 The terms "MIB module" and "information module" are used 139 interchangeably in this memo. As used here, both terms refer to any 140 of the three types of information modules defined in Section 3 of RFC 141 2578 [RFC2578]. 143 The term "standard", when it appears in quotes, is used in the same 144 sense as in the SMIv2 documents [RFC2578] [RFC2579] [RFC2580]. In 145 particular, it is used to refer to the requirements that those 146 documents levy on "standard" modules or "standard" objects. 148 3. General Documentation Guidelines 150 In general, IETF standards-track specifications containing MIB 151 modules MUST conform to the requirements for IETF standards-track 152 RFCs documented in [RFC2223bis]. Because the version under review 153 will be an Internet Draft, the notices on the front page will comply 154 with the requirements of http://www.ietf.org/ietf/1id-guidelines.txt 155 and not with those of [RFC2223bis]. The rest of the requirements in 156 [RFC2223bis], however, do apply (see http://www.ietf.org/ID-nits.html 157 for additional details). 159 Section 4 of [RFC2223bis] lists the sections that may exist in an 160 RFC. The "body of memo" part of an RFC in general contains multiple 161 sections, and in a MIB document MUST contain at least the following: 163 o MIB boilerplate section 165 o Narrative sections 167 o Definitions section 169 o Intellectual Property section 171 Section-by-section guidelines follow. 173 3.1. MIB Boilerplate Section 175 This section MUST contain a verbatim copy of the latest approved 176 Internet-Standard Management Framework boilerplate, which is 177 available on-line at http://www.ops.ietf.org/mib-boilerplate.html 179 3.2. Narrative Sections 181 The narrative part MUST include an overview section that describes 182 the scope and field of application of the MIB modules defined by the 183 specification and that specifies the relationship (if any) of these 184 MIB modules to other standards, particularly to standards containing 185 other MIB modules. The narrative part SHOULD include one or more 186 sections that briefly describes the structure of the MIB modules 187 defined in the specification. 189 If the MIB modules defined by the specification are always 190 implemented in conjunction with other MIB modules, then that fact 191 MUST be noted in the overview section, as MUST any special 192 interpretations of objects in other MIB modules. For instance, so- 193 called media-specific MIB modules are always implemented in 194 conjunction with the IF-MIB [RFC2863] and are REQUIRED to document 195 how certain objects in the IF-MIB are used. In addition, media- 196 specific MIB modules that rely on the ifStackTable [RFC2863] and the 197 ifInvStackTable [RFC2864] to maintain information regarding 198 configuration and multiplexing of interface sublayers MUST contain a 199 description of the layering model. 201 3.3. Definitions Section 203 This section contains the MIB module(s) defined by the specification. 204 These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579] 205 [RFC2580]; SMIv1 [RFC1155] [RFC1212] [RFC1215] has "Not Recommended" 206 status [RFC3410] and is no longer acceptable in IETF MIB modules. 208 See Section 4 for guidelines on SMIv2 usage. 210 3.4. Intellectual Property Section 212 Bullets (A) and (B) in Section 10.4 of RFC 2026 [RFC2026] specify 213 that certain notices regarding intellectual or other property rights 214 appear in all standards-track RFCs. Verbatim copies of these so- 215 called IPR notices MUST appear in each MIB document that is destined 216 for the standards track. If proprietary rights are known to be 217 claimed with respect to the technology described in the document, 218 then the notice in bullet (D) MUST also appear in the document. 220 3.5. References Sections 222 Section 4.8 of [RFC2223bis] specifies the requirements for the 223 references sections. In particular, there MUST be separate lists of 224 normative and informative references, each in a separate section. 225 The style SHOULD follow that of recently published RFCs. 227 The standard MIB boilerplate available at 228 http://www.ops.ietf.org/mib-boilerplate.html includes lists of 229 normative and informative references that MUST appear in all IETF 230 specifications that contain MIB modules. If items from other MIB 231 modules appear in an IMPORTS statement in the Definitions section, 232 then the specifications containing those MIB modules MUST be included 233 in the list of normative references. When items are imported from an 234 IANA-mainained MIB module the corresponding normative reference SHALL 235 point to the on-line version of that MIB module. 237 In general, each normative reference SHOULD point to the most recent 238 version of the specification in question. 240 3.6. Security Considerations Section 242 In order to comply with Section 4.9 of [RFC2223bis], each 243 specification that defines one or more MIB modules MUST contain a 244 section that discusses security considerations relevant to those MIB 245 modules. This section MUST be patterned after the latest approved 246 template (available at http://www.ops.ietf.org/mib-security.html). 247 In particular, writeable MIB objects that could be especially 248 disruptive if abused MUST be explicitly listed by name and the 249 associated security risks MUST be spelled out; similarly, readable 250 MIB objects that contain especially sensitive information MUST be 251 explicitly listed by name and the reasons for the special sensitivity 252 MUST be explained. If there are no risks/vulnerabilities for a 253 specific category of MIB objects, then that fact MUST be explicitly 254 stated. Failure to mention a particular category of MIB objects will 255 not be equated to a claim of no risks/vulnerabilities in that 256 category; rather, it will be treated as an act of omission and will 257 result in the document being returned to the author for correction. 258 Remember that the objective is not to blindly copy text from the 259 template, but rather to think and evaluate the risks/vulnerabilies 260 and then state/document the result of this evaluation. 262 3.7. IANA Considerations Section 264 In order to comply with Section 4.10 of [RFC2223bis], each 265 specification that defines a name space of assigned numbers MUST 266 include an IANA Considerations section conforming to the guidelines 267 set forth in [RFC2434] specifying how that name space is to be 268 administered. 270 Name spaces defined by MIB documents generally consist of the range 271 of values for some type (usually an enumerated INTEGER) defined by a 272 TEXTUAL-CONVENTION (TC) or of a set of administratively-defined 273 OBJECT IDENTIFIER (OID) values. In each case the definitions are 274 housed in stand-alone MIB modules that are maintained by IANA. These 275 IANA-maintained MIB modules are kept separate from the MIB modules 276 defined in standards-track specifications so that new assignments can 277 be made without having to republish a standards-track RFC. Examples 278 of IANA-maintained MIB modules include the IANAifType-MIB 279 (http://www.iana.org/assignments/ianaiftype-mib), which defines a 280 name space used by the IF-MIB [RFC2863], and the IANA-RTPROTO-MIB 281 (http://www.iana.org/assignments/ianaiprouteprotocol-mib), which 282 defines a name space used by the IPMROUTE-STD-MIB [RFC2932]. 284 The current practice for such cases is to include a detailed IANA 285 Considerations section complying with [RFC2434] in the DESCRIPTION 286 clause of the MODULE-IDENTITY invocation in each IANA-maintained MIB 287 module and for the IANA Considerations section of the MIB document 288 that defines the name spaces to refer to the URLs for the relevant 289 modules. See RFC 2932 [RFC2932] for an example. This creates a 290 chicken-and-egg problem for MIB documents that have not yet been 291 published as RFCs because the relevant IANA-maintained MIB modules 292 will not yet exist. The accepted way out of this dilemma is to 293 include the initial content of each IANA-maintained MIB module in a 294 non-normative section of the initial issue of the document that 295 defines the name space; for an example see [RFC1573], which 296 documents the initial version of the IANAifType-MIB. That material 297 is usually omitted from subsequent updates to the document since the 298 IANA-maintained modules are then available on-line (cf. [RFC2863]). 300 Reviewers of draft MIB documents to which these considerations apply 301 MUST check that the IANA Considerations section proposed for 302 publication in the RFC is present and contains pointers to the 303 appropriate IANA-maintained MIB modules. Reviewers of Internet 304 Drafts that contain the proposed initial content of IANA-maintained 305 MIB modules MUST also verify that the DESCRIPTION clauses of the 306 MODULE-IDENTITY invocations contain an IANA Considerations section 307 compliant with the guidelines in [RFC2434]. 309 Note that an IANA Considerations section is NOT required if the only 310 IANA action needed is the assignment of the object identifier for the 311 MIB module's MODULE-IDENTITY value. A note in the form of an ASN.1 312 comment requesting such an assignment is sufficient for this; see 313 Section 4.5 for an example. 315 3.8. Copyright Notices 317 IETF MIB documents MUST contain the copyright notices specified in 318 Section 4.3 of RFC 2223bis [RFC2223bis] and Section 10.4 Bullet (C) 319 of RFC 2026 [RFC2026]. Authors and reviewers MUST check make sure 320 that the correct year is inserted into these notices. In addition, 321 the DESCRIPTION clause of the MODULE-IDENTITY invocation of each MIB 322 module that will appear in the published RFC MUST contain a pointer 323 to the copyright notices in the RFC. A template suitable for 324 inclusion in an Internet Draft, appropriate for MIB modules other 325 those that are to be maintained by the IANA, is as follows: 327 DESCRIPTION 328 " [ ... ] 330 Copyright (C) The Internet Society (date). This version 331 of this MIB module is part of RFC yyyy; see the RFC 332 itself for full legal notices." 333 -- RFC Ed.: replace yyyy with actual RFC number & remove this note 334 A template suitable for MIB modules that are to be maintained by the 335 IANA is as follows: 337 DESCRIPTION 338 " [ ... ] 340 Copyright (C) The Internet Society (date). The initial 341 version of this MIB module was published in RFC yyyy; 342 for full legal notices see the RFC itself or see: 343 http://www.ietf.org/copyrights/ianamib.html." 344 -- RFC Ed.: replace yyyy with actual RFC number & remove this note 346 In each case the current year is to be inserted in place of the word 347 "date". 349 4. SMIv2 Usage Guidelines 351 In general, MIB modules in IETF standards-track specifications MUST 352 comply with all syntactic and semantic requirements of SMIv2 353 [RFC2578] [RFC2579] [RFC2580] that apply to "standard" MIB modules 354 and except as noted below SHOULD comply with SMIv2 recommendations. 355 The guidelines in this section are intended to supplement the SMIv2 356 documents in the following ways: 358 o to document the current generally accepted interpretation when 359 those documents contain ambiguities or contradictions; 361 o to update recommendations in those documents that have been shown 362 by practical experience to be out-of-date or otherwise suboptimal; 364 o to provide guidance in selection of SMIv2 options in cases where 365 there is a consensus on a preferred approach. 367 4.1. Module Names 369 RFC 2578 Section 3 specifies the rules for module names. Note in 370 particular that names of "standard" modules MUST be unique, MUST 371 follow the syntax rules in RFC 2578 Section 3, and MUST NOT be 372 changed when a MIB module is revised (see also RFC 2578 Section 10). 374 It is RECOMMENDED that module names be mnemonic. See Appendix C for 375 additional suggestions. 377 4.2. Descriptors, TC Names, and Labels 379 RFC 2578 Sections 3.1, 7.1.1, and 7.1.4 and RFC 2579 Section 3 380 recommend that descriptors and names associated with macro 381 invocations and labels associated with enumerated INTEGER and BITS 382 values be no longer than 32 characters, but require that they be no 383 longer than 64 characters. 385 Restricting descriptors, TC names, and labels to 32 characters often 386 conflicts with the recommendation that they be mnemonic and (for 387 descriptors and TC names) with the requirement that they be unique 388 (see RFC 2578 Section 3.1 and RFC 2579 Section 3). The consensus of 389 the current pool of MIB reviewers is that the SMIv2 recommendation to 390 limit descriptors, TC names, and labels to 32 characters SHOULD be 391 set aside in favor of promoting clarity and uniqueness and that 392 automated tools such as MIB compilers SHOULD NOT by default generate 393 warnings for violating that recommendation. 395 Note that violations of the 64 character limit MUST NOT be ignored; 396 they MUST be treated as errors. 398 See Appendix C for suggested descriptor and TC naming conventions. 400 4.3. Naming Hierarchy 402 RFC 2578 Section 4 describes the object identifier subtrees that are 403 maintained by IANA and specifies the usages for those subtrees. In 404 particular, the mgmt subtree { iso 3 6 1 2 } is used to identify IETF 405 "standard" objects, while the experimental subtree { iso 3 6 1 3 } is 406 used to identify objects that are under development in the IETF. It 407 is REQUIRED that objects be moved from the experimental subtree to 408 the mgmt subtree when a MIB module enters the IETF standards track. 410 Experience has shown that it is impractical to move objects from one 411 subtree to another once those objects have seen large-scale use in an 412 operational environment. Hence any object that is targeted for 413 deployment in an operational environment MUST NOT be registered under 414 the experimental subtree, irrespective of the standardization status 415 of that object. The experimental subtree should be used only for 416 objects that are intended for limited experimental deployment. Such 417 objects typically are defined in Experimental RFCs. 419 Note: the term "object", as used here and in RFC 2578 Section 4, is 420 to be broadly interpreted as any construct that results in an OBJECT 421 IDENTIFIER registration. The list of such constructs is specified in 422 RFC 2578 Section 3.6. 424 4.4. IMPORTS Statement 426 RFC 2578 Section 3.2 specifies which symbols must be imported and 427 also lists certain pre-defined symbols that must not be imported. 429 The general requirement is that if an external symbol other than a 430 predefined ASN.1 type or the BITS construct is used, then it MUST be 431 mentioned in the module's IMPORTS statement. The words "external 432 object" in the first paragraph of that section may give the 433 impression that such symbols are limited to those that refer to 434 object definitions, but that is not the case, as subsequent 435 paragraphs should make clear. 437 Note that exemptions to this general requirement are granted by RFC 438 2580 Sections 5.4.3 and 6.5.2 for descriptors of objects appearing in 439 the OBJECT clause of a MODULE-COMPLIANCE statement or in the 440 VARIATION clause of an AGENT-CAPABILITIES statement. Some MIB 441 compilers also grant exemptions to descriptors of notifications 442 appearing in a VARIATION clause and to descriptors of object groups 443 and notification groups referenced by a MANDATORY-GROUPS clause, a 444 GROUP clause, or an INCLUDES clause, although RFC 2580 (through 445 apparent oversight) does not mention those cases. The exemptions are 446 sometimes seen as unhelpful because they make IMPORTS rules more 447 complicated and inter-module dependencies less obvious than they 448 otherwise would be. External symbols referenced by compliance 449 statements and capabilities statements MAY therefore be listed in the 450 IMPORTS statement; if this is done, it SHOULD be done consistently. 452 Finally, even though it is not forbidden by the SMI, it is considered 453 poor style to import symbols that are not used, and standards-track 454 MIB modules SHOULD NOT do so. 456 4.5. MODULE-IDENTITY Invocation 458 RFC 2578 Section 3 requires that all SMIv2 MIB modules start with 459 exactly one invocation of the MODULE-IDENTITY macro. This invocation 460 MUST appear immediately after the IMPORTS statement. 462 RFC 2578 Section 5 describes how the various clauses are used. The 463 following additional guidelines apply to all MIB modules over which 464 the IETF has change control: 466 - If the module was developed by an IETF working group, then the 467 ORGANIZATION clause MUST provide the full name of the working 468 group, and the CONTACT-INFO clause MUST include working group 469 mailing list information. The CONTACT-INFO clause SHOULD also 470 provide a pointer to the working group's web page. 472 - A REVISION clause MUST be present for each revision of the MIB 473 module, and the UTC time of the most recent REVISION clause MUST 474 match that of the LAST-UPDATED clause. The DESCRIPTION clause 475 associated with each revision MUST state in which RFC that revision 476 appeared and SHOULD provide a list of all significant changes. 478 When a MIB module is revised UTC times in all REVISION clauses 479 SHOULD be updated to use four-digit year notation. 481 - The value assigned to the MODULE-IDENTITY descriptor MUST be unique 482 and (for IETF standards-track MIB modules) SHOULD reside under the 483 mgmt subtree [RFC2578]. Most often it will be an IANA-assigned 484 value directly under mib-2 [RFC2578], although for media-specific 485 MIB modules that extend the IF-MIB [RFC2863] it is customary to use 486 an IANA-assigned value under transmission [RFC2578]. In the past 487 some IETF working groups have made their own assignments from 488 subtrees delegated to them by IANA, but that practice has proven 489 problematic and is NOT RECOMMENDED. 491 While a MIB module is under development, the RFC number in which it 492 will eventually be published is usually unknown and must be filled in 493 by the RFC Editor prior to publication. An appropriate form for the 494 REVISION clause applying to a version under development would be 495 something along the following lines: 497 REVISION "200212132358Z" -- December 13, 2002 498 DESCRIPTION "Initial version, published as RFC yyyy." 499 -- RFC Ed.: replace yyyy with actual RFC number & remove this note 501 Note that after RFC publication a REVISION clause is present only for 502 published versions of a MIB module and not for interim versions that 503 existed only as Internet Drafts. Thus, a draft version of a MIB 504 module MUST contain just one new REVISION clause that covers all 505 changes since the last published version (if any). 507 When the initial version of a MIB module is under development, the 508 value assigned to the MODULE-IDENTITY descriptor will be unknown if 509 an IANA-assigned value is used, because the assignment is made just 510 prior to publication as an RFC. The accepted form for the MODULE- 511 IDENTITY statement in draft versions of such a module is something 512 along the following lines: 514 MODULE-IDENTITY 516 [ ... ] 518 ::= { XXX } 519 -- RFC Ed.: replace XXX with IANA-assigned number & remove this note 521 where is whatever descriptor has been selected for the 522 module and is the subtree under which the module is to be 523 registered (e.g., mib-2 or transmission). Note that XXX must be 524 temporarily replaced by a number in order for the module to compile. 526 4.6. Textual Conventions and Object Definitions 528 4.6.1. Usage of Data Types 530 4.6.1.1. INTEGER, Integer32, Gauge32, and Unsigned32 532 The 32-bit integer data types INTEGER, Integer32, Gauge32, and 533 Unsigned32 are described in RFC 2578 Section 2 and further elaborated 534 in RFC 2578 Sections 7.1.1, 7.1.7, and 7.1.11. The following 535 guidelines apply when selecting one of these data types for an object 536 definition or a textual convention: 538 - For integer-valued enumerations: 540 - INTEGER is REQUIRED; 541 - Integer32, Unsigned32, and Gauge32 MUST NOT be used. 543 Note that RFC 2578 recommends (but does not require) that integer- 544 valued enumerations start at 1 and be numbered contiguously. This 545 recommendation SHOULD be followed unless there is a valid reason to 546 do otherwise, e.g., to match values of external data or to indicate 547 special cases, and any such special-case usage SHOULD be clearly 548 documented. For an example see the InetAddressType TC [RFC3291]. 550 - If the value range is between -2147483648..2147483647 (inclusive) 551 and negative values are possible, then: 553 - Integer32 is RECOMMENDED; 554 - INTEGER is acceptable; 555 - Unsigned32 and Gauge32 MUST NOT be used. 557 - If the value range is between 0..4294967295 (inclusive) and the 558 value of the information being modelled may increase above the 559 maximum value or decrease below the minimum value, then: 561 - Gauge32 is RECOMMENDED; 562 - Unsigned32 is acceptable; 563 - INTEGER and Integer32 MUST NOT be used if 564 values greater than 2147483647 are possible. 566 - If the value range is between 0..4294967295 (inclusive), and values 567 greater than 2147483647 are possible, and the value of the 568 information being modelled does not increase above the maximum 569 value nor decrease below the minimum value, then: 571 - Unsigned32 is RECOMMENDED; 572 - Gauge32 is acceptable; 573 - INTEGER and Integer32 MUST NOT be used. 575 - If the value range is between 0..2147483647 (inclusive), and the 576 value of the information being modelled does not increase above the 577 maximum value nor decrease below the minimum value, then: 579 - Unsigned32 is RECOMMENDED; 580 - INTEGER, Integer32, and Gauge32 are acceptable. 582 - For integer-valued objects that appear in an INDEX clause or for 583 integer-valued TCs that are to be used in an index column: 585 - Unsigned32 with a range that excludes zero is RECOMMENDED for 586 most index objects. It is acceptable to include zero in the 587 range when it is semantically significant or when it is used as 588 the index value for a unique row with special properties. Such 589 usage SHOULD be clearly documented in the DESCRIPTION clause. 591 - Integer32 or INTEGER with a non-negative range is acceptable. 592 Again, zero SHOULD be excluded from the range except when it is 593 semantically significant or when it is used as the index value 594 for a unique row with special properties, and in such cases the 595 usage SHOULD be clearly documented in the DESCRIPTION clause. 597 - Use of Gauge32 is acceptable for index objects that have gauge 598 semantics. 600 The guidelines above combine both the usage rules for integer data 601 types and the INDEX rules in RFC 2578 Section 7.7 up to and including 602 bullet (1) plus the next-to-last paragraph on page 28. 604 Sometimes it will be necessary for external variables to represent 605 values of an index object -- e.g., ifIndex [RFC2863]. In such cases 606 authors of the module containing that object SHOULD consider defining 607 TCs such as InterfaceIndex and/or InterfaceIndexOrZero [RFC2863]. 609 Note that INTEGER is a pre-defined ASN.1 type and MUST NOT be present 610 in a module's IMPORTS statement, whereas Integer32, Gauge32, and 611 Unsigned32 are defined by SNMPv2-SMI and MUST be imported from that 612 module if used. 614 4.6.1.2. Counter32 and Counter64 616 Counter32 and Counter64 have special semantics as described in RFC 617 2578 Sections 7.1.6 and 7.1.10 respectively. Object definitions MUST 618 (and textual conventions SHOULD) respect these semantics. That 619 means: 621 - It is OK to use Counter32/64 for counters that may/will be reset 622 when the management subsystem is re-initialized or when other 623 unusual/irregular events occur (e.g., counters maintained on a line 624 card may be reset when the line card is reset). However, if it is 625 possible for such other unusual/irregular events to occur, the 626 DESCRIPTION clause MUST state that this is so and MUST describe 627 those other unusual/irregular events in sufficient detail that it 628 is possible for a management application to determine whether a 629 reset has occurred since the last time the counter was polled. The 630 RECOMMENDED way to do this is to provide a discontinuity indicator 631 as described in RFC 2578 Sections 7.1.6 and 7.1.10. For an example 632 of such a discontinuity indicator see the 633 ifCounterDiscontinuityTime object in the IF-MIB [RFC2863]. 635 - It is NOT OK to put in the DESCRIPTION clause of a Counter32/64 636 that there is a requirement that on a discontinuity the counter 637 MUST reset to zero or to any other specific value. 639 - It is NOT OK to put in the DESCRIPTION clause of a Counter32/64 640 that there is a requirement that it MUST reset at any specific 641 time/event (e.g., midnight). 643 - It is NOT OK for one manager to request the agent to reset the 644 value of counter(s) to zero, and Counter32/64 is the wrong syntax 645 for "counters" which regularly reset themselves to zero. For the 646 latter it is better to define or use textual conventions such as 647 those in RFC 2493 [RFC2493]. 649 RFC 2578 Section 7.1.10 places a requirement on "standard" MIB 650 modules that the Counter64 type may be used only if the information 651 being modelled would wrap in less than one hour if the Counter32 type 652 was used instead. Now that SNMPv3 is an Internet Standard and SNMPv1 653 is Historic (see http://www.rfc-editor.org/rfcxx00.html for status 654 and [RFC3410] for rationale) there is no reason to continue enforcing 655 this restriction. Henceforth "standard" MIB modules MAY use the 656 Counter64 type when it makes sense to do so, and MUST use Counter64 657 if the information being modelled would wrap in less than one hour if 658 the Counter32 type was used instead. 660 There also exist closely-related textual conventions 661 ZeroBasedCounter32 and ZeroBasedCounter64 defined in RMON2-MIB 662 [RFC2021] and HCNUM-TC [RFC2856], respectively. 664 The only difference between ZeroBasedCounter32/64 TCs and 665 Counter32/64 is their starting value; at time=X, where X is their 666 minimum-wrap-time after they were created, the behaviour of 667 ZeroBasedCounter32/64 becomes exactly the same as Counter32/64. 668 Thus, the preceeding paragraphs/rules apply not only to Counter32/64, 669 but also to ZeroBasedCounter32/64 TCs. 671 4.6.1.3. CounterBasedGauge64 673 SMIv2 unfortunately does not provide 64-bit integer base types. In 674 order to make up for this omission, the CounterBasedGauge64 textual 675 convention is defined in HCNUM-TC [RFC2856]. This TC uses Counter64 676 as a base type, but discards the special counter semantics, which is 677 allowed under the generally accepted interpretation of RFC 2579 678 Section 3.3. It does inherit all the syntactic restrictions of that 679 type, which means that it MUST NOT be subtyped and that objects 680 defined with it MUST NOT appear in an INDEX clause, MUST NOT have a 681 DEFVAL clause, and MUST have a MAX-ACCESS of read-only or 682 accessible-for-notify. 684 This TC SHOULD be used for object definitions that require a 64-bit 685 unsigned data type with gauge semantics. If a 64-bit unsigned data 686 type with different semantics is needed, then a different TC based on 687 Counter64 MUST be used, since one TC cannot refine another (cf. RFC 688 2579 Section 3.5). 690 4.6.1.4. OCTET STRING 692 The OCTET STRING type is described in RFC 2578 Section 7.1.2. It 693 represents arbitrary binary or textual data whose length is between 0 694 and 65535 octets inclusive. Objects and TCs whose SYNTAX is of this 695 type SHOULD have a size constraint when the actual bounds are more 696 restrictive than the SMI-imposed limits. This is particularly true 697 for index objects. Note, however, that size constraints SHOULD NOT 698 be imposed arbitrarily, as the SMI does not permit them to be changed 699 afterward. 701 There exist a number of standard TCs that cater to some of the more 702 common requirements for specialized OCTET STRING types. In 703 particular, SNMPv2-TC [RFC2579] contains the DisplayString, 704 PhysAddress, MacAddress, and DateAndTime TCs, the SNMP-FRAMEWORK-MIB 705 [RFC3411] contains the SnmpAdminString TC, and the SYSAPPL-MIB 706 [RFC2287] contains the Utf8String and LongUtf8String TCs. When a 707 standard TC provides the desired semantics, it SHOULD be used in an 708 object's SYNTAX clause instead of OCTET STRING or an equivalent 709 locally-defined TC. 711 Note that OCTET STRING is a pre-defined ASN.1 type and MUST NOT be 712 present in a module's IMPORTS statement. 714 4.6.1.5. OBJECT IDENTIFIER 716 The OBJECT IDENTIFIER type is described in RFC 2578 Section 7.1.3. 717 Its instances represent administratively assigned names. Note that 718 both the SMI and the SNMP protocol limit instances of this type to 719 128 sub-identifiers and require that each sub-identifier be within 720 the range 0 to 4294967295 inclusive. Sub-typing is not allowed. 722 The purpose of OBJECT IDENTIFIER values is to provide authoritative 723 identification either for some type of item or for a specific 724 instance of some type of item. Among the items that can be 725 identified in this way are definitions in MIB modules created via the 726 MODULE-IDENTITY, OBJECT-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE, 727 OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE, and AGENT- 728 CAPABILITIES constructs, instances of objects defined in MIB modules, 729 protocols, languages, specifications, interface types, hardware, and 730 software. For some of these uses other possibilities exist, e.g., 731 OCTET STRING or enumerated INTEGER values. The OBJECT IDENTIFIER 732 type SHOULD be used instead of the alternatives when the set of 733 identification values needs to be independently extensible without 734 the need for a registry to provide centralized coordination. 736 There exist a number of standard TCs that cater to some of the more 737 common requirements for specialized OBJECT IDENTIFIER types. In 738 particular, SNMPv2-TC [RFC2579] contains the AutonomousType, 739 VariablePointer, and RowPointer TCs. When a standard TC provides the 740 desired semantics, it SHOULD be used in an object's SYNTAX clause 741 instead of OBJECT IDENTIFIER or an equivalent locally-defined TC. 743 Note that OBJECT IDENTIFIER is a pre-defined ASN.1 type and MUST NOT 744 be present in a module's IMPORTS statement. 746 4.6.1.6. The BITS Construct 748 The BITS construct is described in RFC 2578 Section 7.1.4. It 749 represents an enumeration of named bits. The bit positions in a TC 750 or object definition whose SYNTAX is of this type MUST start at 0 and 751 SHOULD be contiguous. 753 Note that the BITS construct is defined by the macros that use it and 754 therefore MUST NOT be present in a module's IMPORTS statement. 756 4.6.1.7. IpAddress 758 The IpAddress type described in RFC 2578 Section 7.1.5 SHOULD NOT be 759 used in new MIB modules. The InetAddress/InetAddressType textual 760 conventions [RFC3291] SHOULD be used instead. 762 4.6.1.8. TimeTicks 764 The TimeTicks type is described in RFC 2578 Section 7.1.8. It 765 represents the time in hundredths of a second between two epochs, 766 reduced modulo 2^32. It MUST NOT be sub-typed, and the DESCRIPTION 767 clause of any object or TC whose SYNTAX is of this type MUST identify 768 the reference epochs. 770 The TimeTicks type SHOULD NOT be used directly in definitions of 771 objects that are snapshots of sysUpTime [RFC3418]. The TimeStamp TC 772 [RFC2579] already conveys the desired semantics and SHOULD be used 773 instead. 775 4.6.1.9. TruthValue 777 The TruthValue TC is defined in SNMPv2-TC [RFC2579]. It is an 778 enumerated INTEGER type that assumes the values true(1) and false(2). 780 This TC SHOULD be used in the SYNTAX clause of object definitions 781 that require a Boolean type. MIB modules SHOULD NOT use enumerated 782 INTEGER types or define TCs that duplicate its semantics. 784 4.6.1.10. Other Data Types 786 There exist a number of standard TCs that cater to some of the more 787 common requirements for specialized data types. Some have been 788 mentioned above, and Appendix B contains a partial list that includes 789 those plus some others that are a bit more specialized. An on-line 790 version of that list, which is updated as new TCs are developed, can 791 be found at http://www.ops.ietf.org/mib-common-tcs.html 793 Whenever a standard TC already conveys the desired semantics, it 794 SHOULD be used in an object definition instead of the corresponding 795 base type or a locally-defined TC. This is especially true of the 796 TCs defined in SNMPv2-TC [RFC2579] and SNMP-FRAMEWORK-MIB [RFC3411] 797 because they are Internet Standards, and so modules that refer to 798 them will not suffer delay in advancement on the standards track on 799 account of such references. 801 MIB module authors need to be aware that enumerated INTEGER or BITS 802 TCs may in some cases be extended with additional enumerated values 803 or additional bit positions. When an imported TC that may be 804 extended in this way is used to define an object that may be written 805 or that serves as an index in a read-create table, then the set of 806 values or bit positions that needs to be supported SHOULD be 807 specified either in the object's DESCRIPTION clause or in an OBJECT 808 clause in the MIB module's compliance statement(s). This may be done 809 by explicitly listing the required values or bit positions, or it may 810 be done by stating that an implementation may support a subset of 811 values or bit positions of its choosing. 813 4.6.2. DESCRIPTION and REFERENCE Clauses 815 It is hard to overemphasize the importance of an accurate and 816 unambiguous DESCRIPTION clause for all objects and TCs. The 817 DESCRIPTION clause contains the instructions that implementors will 818 use to implement an object, and if they are inadequate or ambiguous, 819 then implementation quality will suffer. Probably the single most 820 important job of a MIB reviewer is to ensure that DESCRIPTION clauses 821 are sufficiently clear and unambiguous to allow interoperable 822 implementations to be created. 824 A very common problem is to see an object definition for, say, 825 'stdMIBPoofpoofCounter' with a DESCRIPTION clause that just says 826 "Number of poofpoofs" with no indication what a 'poofpoof' is. In 827 such cases it is strongly RECOMMENDED that there either be at least a 828 minimal explanation or else a REFERENCE clause to point to the 829 definition of a 'poofpoof'. 831 For read-write objects (other than columns in read-create tables that 832 have well-defined persistence properties) it is RECOMMENDED that the 833 DESCRIPTION clause specify what happens to the value after an agent 834 reboot. Among the possibilities are that the value remains 835 unchanged, that it reverts to a well-defined default value, or that 836 the result is implementation-dependent. 838 4.6.3. DISPLAY-HINT Clause 840 The DISPLAY-HINT clause is used in a TC to provide a non-binding hint 841 to a management application as to how the value of an instance of an 842 object defined with the syntax in the TC might be displayed. Its 843 presence is optional. 845 Although management applications typically default to decimal format 846 ("d") for integer TCs which are not enumerations and to a hexadecimal 847 format ("1x:" or "1x " or "1x_") for octet string TCs when the 848 DISPLAY-HINT clause is absent, it should be noted that SMIv2 does not 849 actually specify any defaults. MIB authors should be aware that a 850 clear hint is provided to applications only when the DISPLAY-HINT 851 clause is present. 853 4.6.4. Conceptual Table Definitions 855 RFC 2578 Sections 7.1.12 and 7.1.12.1 specify the rules for defining 856 conceptual tables, and RFC 2578 Sections 7.7, 7.8, and 7.8.1 specify 857 conceptual table indexing rules. The following guidelines apply to 858 such definitions: 860 - For conceptual rows: 862 - If the row is an extension of a row in some other table, then an 863 AUGMENTS clause MUST be used if the relationship is one-to-one, 864 and an INDEX clause MUST be used if the relationship is sparse. 865 In the latter case the INDEX clause SHOULD be identical to that 866 of the original table. 868 - If the row is an element of an expansion table -- that is, if 869 multiple row instances correspond to a single row instance in 870 some other table -- then an INDEX clause MUST be used, and the 871 first-mentioned elements SHOULD be the indices of that other 872 table, listed in the same order. 874 - If objects external to the row are present in the INDEX clause, 875 then the conceptual row's DESCRIPTION clause MUST specify how 876 those objects are used in identifying instances of its columnar 877 objects, and in particular MUST specify for which values of those 878 index objects the conceptual row may exist. 880 - Use of the IMPLIED keyword is NOT RECOMMENDED for any index 881 object that may appear in the INDEX clause of an expansion table. 882 Since this keyword may be associated only with the last object in 883 an INDEX clause, it cannot be associated with the same index 884 object in a primary table and an expansion table. This will 885 cause the sort order to be different in the primary table and any 886 expansion tables. As a consequence, an implementation will be 887 unable to reuse indexing code from the primary table in expansion 888 tables, and data structures meant to be extended might actually 889 have to be replicated. Designers who are tempted to use IMPLIED 890 should consider that the resulting sort order rarely meets user 891 expectations, particularly for strings that include both upper 892 and lower-case letters, and it does not take the user language or 893 locale into account. 895 - If dynamic row creation and/or deletion by management applications 896 is supported, then: 898 - There MUST be one columnar object with a SYNTAX value of 899 RowStatus [RFC2579] and a MAX-ACCESS value of read-create. This 900 object is called the status column for the conceptual row. All 901 other columnar objects MUST have a MAX-ACCESS value of read- 902 create, read-only, accessible-for-notify, or not-accessible; a 903 MAX-ACCESS value of read-write is not allowed. 905 - There either MUST be one columnar object with a SYNTAX value of 906 StorageType [RFC2579] and a MAX-ACCESS value of read-create, or 907 else the row object (table entry) DESCRIPTION clause MUST specify 908 what happens to dynamically-created rows after an agent restart. 910 - If the agent itself may also create and/or delete rows, then the 911 conditions under which this can occur MUST be clearly documented 912 in the row object DESCRIPTION clause. 914 - For conceptual rows that include a status column: 916 - The DESCRIPTION clause of the status column MUST specify which 917 columnar objects (if any) have to be set to valid values before 918 the row can be activated. If any objects in cascading tables 919 have to be populated with related data before the row can be 920 activated, then this MUST also be specified. 922 - The DESCRIPTION clause of the status column MUST specify whether 923 or not it is possible to modify other columns in the same 924 conceptual row when the status value is active(1). Note that in 925 many cases it will be possible to modify some writeable columns 926 when the row is active but not others. In such cases the 927 DESCRIPTION clause for each writeable column SHOULD state whether 928 or not that column can be modified when the row is active, and 929 the DESCRIPTION clause for the status column SHOULD state that 930 modifiability of other columns when the status value is active(1) 931 is specified in the DESCRIPTION clauses for those columns (rather 932 than listing the modifiable columns individually). 934 - For conceptual rows that include a StorageType column: 936 - The DESCRIPTION clause of the StorageType column MUST specify 937 which read-write or read-create columnar objects in permanent(4) 938 rows an agent must, at a minimum, allow to be writable. 940 Complete requirements for the RowStatus and StorageType TCs can be 941 found in RFC 2579, in the DESCRIPTION clauses for those TCs. 943 4.6.5. OID Values Assigned to Objects 945 RFC 2578 Section 7.10 specifies the rules for assigning OBJECT 946 IDENFIFIER (OID) values to OBJECT-TYPE definitions. In particular: 948 - A conceptual table MUST have exactly one subordinate object, which 949 is a conceptual row. The OID assigned to the conceptual row MUST 950 be derived by appending a sub-identifier of "1" to the OID assigned 951 to the conceptual table. 953 - A conceptual row has as many subordinate objects as there are 954 columns in the row; there MUST be at least one. The OID assigned 955 to each columnar object MUST be derived by appending a non-zero 956 sub-identifier, unique within the row, to the OID assigned to the 957 conceptual row. 959 - A columnar or scalar object MUST NOT have any subordinate objects. 961 - The last sub-identifier of an OID assigned to any object (be it 962 table, row, column, or scalar) MUST NOT be equal to zero. Note 963 that sub-identifiers of intermediate nodes MAY be equal to zero. 965 - The OID assigned to an object definition MUST NOT also be assigned 966 to another definition that results in OID registration. RFC 2578 967 Section 3.6 lists the constructs that create OID registrations. 969 Although it is not specifically required by the SMI, it is customary 970 (and strongly RECOMMENDED) that object definitions not be registered 971 beneath group definitions, compliance statements, capabilities 972 statements, or notification definitions. It is also customary (and 973 strongly RECOMMENDED) that group definitions, compliance statements, 974 capabilities statements, and notification definitions not be 975 registered beneath object definitions. See Appendix D for a 976 RECOMMENDED OID assignment scheme. 978 4.6.6. OID Length Limitations and Table Indexing 980 As specified in RFC 2578 Section 3.5, all OIDs are limited to 128 981 sub-identifiers. While this is not likely to cause problems with 982 administrative assignments, it does place some limitations on table 983 indexing. That is true because the length limitation also applies to 984 OIDs for object instances, and these consist of the concatenation of 985 the "base" OID assigned in the object definition plus the index 986 components. When a table has multiple indices of types such as OCTET 987 STRING or OBJECT IDENTIFIER that resolve to multiple sub-identifiers, 988 then the 128 sub-identifier limit can be quickly reached. 990 Despite its inconvenience, the 128 sub-identifier limit is not 991 something that can be ignored. In addition to being imposed by the 992 SMI, it is also imposed by the SNMP (see the last paragraph in 993 Section 4.1 of RFC 3416 [RFC3416]). It follows that any table with 994 enough indexing components to violate this limit cannot be read or 995 written using the SNMP and so is unusable. Hence table design MUST 996 take the 128 sub-identifier limit into account. It is RECOMMENDED 997 that all MIB documents make explicit any limitations on index 998 component lengths that management software must observe. This may be 999 done either by including SIZE constraints on the index components or 1000 by specifying applicable constraints in the conceptual row 1001 DESCRIPTION clause or in the surrounding documentation. 1003 4.7. Notification Definitions 1005 RFC 2578 Section 8 specifies the rules for notification definitions. 1006 In particular: 1008 - Inaccessible objects MUST NOT appear in the OBJECTS clause. 1010 - For each object type mentioned in the OBJECTS clause, the 1011 DESCRIPTION clause MUST specify which object instance is to be 1012 present in the transmitted notification and MUST specify the 1013 information/meaning conveyed. 1015 - The OBJECT IDENTIFIER (OID) value assigned to each notification 1016 type MUST have a next-to-last sub-identifier of zero, so that it is 1017 possible to convert an SMIv2 notification definition into an SMIv1 1018 trap definition and back again without information loss (see 1019 [RFC2576] Section 2.1.2) and possible for a multilingual proxy 1020 chain to translate an SNMPv2 trap into an SNMPv1 trap and back 1021 again without information loss (see [RFC2576] Section 3). In 1022 addition, the OID assigned to a notification definition MUST NOT 1023 also be assigned to another definition that results in OID 1024 registration. RFC 2578 Section 3.6 lists the constructs that 1025 create OID registrations. 1027 Although it is not specifically required by the SMI, it is customary 1028 (and strongly RECOMMENDED) that notification definitions not be 1029 registered beneath group definitions, compliance statements, 1030 capabilities statements, or object definitions (this last is 1031 especially unwise, as it may result in an object instance and a 1032 notification definition sharing the same OID). It is also customary 1033 (and strongly RECOMMENDED) that the OIDs assigned to notification 1034 types be leaf OIDs (i.e., that there be no OID registrations 1035 subordinate to a notification definition). See Appendix D for a 1036 RECOMMENDED OID assignment scheme. 1038 In many cases notifications will be triggered by external events, and 1039 sometimes it will be possible for those external events to occur at a 1040 sufficiently rapid rate that sending a notification for each 1041 occurrence would overwhelm the network. In such cases a mechanism 1042 MUST be provided for limiting the rate at which the notification can 1043 be generated. A common technique is to require that the notification 1044 generator use throttling -- that is, to require that it generate no 1045 more than one notification for each event source in any given time 1046 interval of duration T. The throttling period T MAY be configurable, 1047 in which case it is specified in a MIB object, or it MAY be fixed, in 1048 which case it is specified in the notification definition. Examples 1049 of the fixed time interval technique can be found in the SNMP- 1050 REPEATER-MIB [RFC2108] and in the ENTITY-MIB [RFC2737]. 1052 4.8. Compliance Statements 1054 RFC 2580 Sections 3, 4, and 5 specify the rules for conformance 1055 groups and compliance statements. In particular: 1057 - Every object with a MAX-ACCESS value other than "not-accessible" 1058 MUST be contained in at least one object group. 1060 - Every notification MUST be contained in at least one notification 1061 group. 1063 - There MUST be at least one compliance statement defined for each 1064 "standard" MIB module. It may reside either within that MIB module 1065 or within a companion MIB module. 1067 In writing compliance statements there are several points that are 1068 easily overlooked: 1070 - An object group or notification group that is not mentioned either 1071 in the MANDATORY-GROUPS clause or in any GROUP clause of a MODULE- 1072 COMPLIANCE statement is unconditionally optional with respect to 1073 that compliance statement. An alternate way to indicate that an 1074 object group or notification group is optional is to mention it in 1075 a GROUP clause whose DESCRIPTION clause states that the group is 1076 optional. The latter method is RECOMMENDED (for optional groups 1077 that are relevant to the compliance statement) in order to make it 1078 clear that the optional status is intended rather than being the 1079 result of an act of omission. 1081 - If there are any objects with a MAX-ACCESS value of read-write or 1082 read-create for which there is no OBJECT clause that specifies a 1083 MIN-ACCESS of read-only, then implementations must support write 1084 access to those objects in order to be compliant with that MODULE- 1085 COMPLIANCE statement. This fact sometimes catches MIB module 1086 authors by surprise. When confronted with such cases, reviewers 1087 SHOULD verify that this is indeed what the authors intended, since 1088 it often is not. 1090 - On the other side of the coin, MIB module authors need to be aware 1091 that while a read-only compliance statement is sufficient to 1092 support interoperable monitoring applications, it is not sufficient 1093 to support interoperable configuration applications. A technique 1094 commonly used in MIB modules that are intended to support both 1095 monitoring and configuration is to provide both a read-only 1096 compliance statement and a full compliance statement. A good 1097 example is provided by the DIFFSERV-MIB [RFC3289]. Authors SHOULD 1098 consider using this technique when it is applicable. 1100 Sometimes MIB module authors will want to specify that a compliant 1101 implementation needs to support only a subset of the values allowed 1102 by an object's SYNTAX clause. For accessible objects this may be 1103 done either by specifying the required values in an object's 1104 DESCRIPTION clause or by providing an OBJECT clause with a refined 1105 SYNTAX in a compliance statement. The latter method is RECOMMENDED 1106 for most cases, and is REQUIRED if there are multiple compliance 1107 statements with different value subsets required. The DIFFSERV-MIB 1108 [RFC3289] illustrates this point. The diffServMIBFullCompliance 1109 statement contains the following OBJECT clause (*) 1111 OBJECT diffServDataPathStatus 1112 SYNTAX RowStatus { active(1) } 1113 WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) } 1114 DESCRIPTION 1115 "Support for createAndWait and notInService is not required." 1117 whereas the diffServMIBReadOnlyCompliance statement contains this: 1119 OBJECT diffServDataPathStatus 1120 SYNTAX RowStatus { active(1) } 1121 MIN-ACCESS read-only 1122 DESCRIPTION 1123 "Write access is not required, and active is the only status that 1124 needs to be supported." 1126 One cannot do this for inaccessible index objects because they cannot 1127 be present in object groups and cannot be mentioned in OBJECT 1128 clauses. There are situations, however, in which one might wish to 1129 indicate that an implementation is required to support only a subset 1130 of the possible values of some index in a read-create table. In such 1131 cases the requirements MUST be specified either in the index object's 1132 DESCRIPTION clause (RECOMMENDED if there is only one value subset) or 1133 in the DESCRIPTION clause of a MODULE-COMPLIANCE statement (REQUIRED 1134 if the value subset is unique to the compliance statement). 1136 In many cases a MIB module is always implemented in conjunction with 1137 one or more other MIB modules. That fact is REQUIRED to be noted in 1138 the surrounding documentation (see Section 3.2 above), and it SHOULD 1139 also be noted in the relevant compliance statements as well. In 1140 cases where a particular compliance statement in (say) MIB module A 1141 requires the complete implementation of some other MIB module B, then 1142 the RECOMMENDED approach is to include a statement to that effect in 1143 the DESCRIPTION clause of the compliance statement(s) in MIB module 1144 A. It is also possible, however, that MIB module A might have 1145 requirements that are different from those that are expressed by any 1146 any compliance statement of module B -- for example, module A might 1147 not require any of the unconditionally mandatory object groups from 1148 module B but might require mandatory implementation of an object 1149 group from module B that is only conditionally mandatory with respect 1150 to the compliance statement(s) in module B. In such cases the 1151 RECOMMENDED approach is for the compliance statement(s) in module A 1152 to formally specify requirements with respect to module B via 1153 appropriate MODULE, MANDATORY-GROUPS, GROUP, and OBJECT clauses. An 1154 example is provided by the compliance statements in the DIFFSERV-MIB 1155 [RFC3289], which list the ifCounterDiscontinuityGroup from IF-MIB 1156 [RFC2863] as a mandatory group. That group is not sufficient to 1157 satisfy any IF-MIB compliance statement, and it is conditionally 1158 mandatory in the IF-MIB's current compliance statement ifCompliance3. 1160 _______________________________ 1161 (*) There has been some dispute as to whether syntax refinements that 1162 restrict enumerations (RFC 2578, Section 9) are permitted with TCs, 1163 as shown in these examples, or are allowed only with the base types 1164 INTEGER and BITS, as suggested by a strict reading of RFC 2578. The 1165 rough consensus of the editors of the SMIv2 documents and the current 1166 pool of MIB reviewers is that they should be allowed with TCs. MIB 1167 module authors should be aware that some MIB compilers follow the 1168 strict reading of RFC 2578 and require that the TC be replaced by its 1169 base type (INTEGER or BITS) when enumerations are refined. That 1170 usage is legal, and it can be found in some older MIB modules such as 1171 the IF-MIB [RFC2863]. 1173 4.9. Revisions to MIB Modules 1175 RFC 2578 Section 10 specifies general rules that apply any time a MIB 1176 module is revised. Specifically: 1178 - The MODULE-IDENTITY invocation MUST be updated to include 1179 information about the revision. In particular, the LAST-UPDATED 1180 clause value MUST be set to the revision time, a REVISION clause 1181 with the same UTC time and an associated DESCRIPTION clause 1182 describing the changes MUST be added, and any obsolete information 1183 in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses 1184 MUST be replaced with up-to-date information. See Section 4.5 1185 above for additional requirements that apply to MIB modules that 1186 are under IETF change control. 1188 - On the other hand, the module name MUST NOT be changed (except to 1189 correct typographical errors), existing definitions (even obsolete 1190 ones) MUST NOT be removed from the MIB module, and descriptors and 1191 OBJECT IDENTIFIER values associated with existing definitions MUST 1192 NOT be changed or re-assigned. 1194 It is important to note that the purpose in forbidding certain kinds 1195 of changes is to ensure that a revised MIB module is compatible with 1196 fielded implementations based on previous versions of the module. 1197 There are two distinct aspects of this backward compatibility 1198 requirement. One is "over the wire" compatibility of agent and 1199 manager implementations that are based on different revisions of the 1200 MIB module. The other is "compilation" compatibility with MIB 1201 modules that import definitions from the revised MIB module. The 1202 rules forbidding changing or re-assigning OBJECT IDENTIFIER values 1203 are necessary to ensure "over the wire" compatibility; the rules 1204 against changing module names or descriptors or removing obsolete 1205 definitions are necessary to ensure compilation compatibility. 1207 RFC 2578 Section 10.2 specifies rules that apply to revisions of 1208 object definitions. The following guidelines correct some errors in 1209 these rules and provided some clarifications: 1211 - Bullet (1) allows the labels of named numbers and named bits in 1212 SYNTAX clauses of type enumerated INTEGER or BITS to be changed. 1213 This can break compilation compatibility, since those labels may be 1214 used by DEFVAL clauses in modules that import the definitions of 1215 the affected objects. Therefore, labels of named numbers and named 1216 bits MUST NOT be changed when revising IETF MIB modules (except to 1217 correct typographical errors), and they SHOULD NOT be changed when 1218 revising enterprise MIB modules. 1220 - Although not specifically permitted in bullets (1) through (8), it 1221 is generally considered acceptable to add range constraints to the 1222 SYNTAX clause of an integer-valued object, provided that the 1223 constraints simply make explicit some value restrictions that were 1224 implicit in the definition of the object. The most common example 1225 is an auxiliary object with a SYNTAX of INTEGER or Integer32 with 1226 no range constraint. Since an auxiliary object is not permitted to 1227 assume negative values, adding the range constraint (0..2147483647) 1228 cannot possibly result in any "over the wire" change, nor will it 1229 cause any compilation compatibility problems with a correctly 1230 written MIB module. Such a change SHOULD be treated by a reviewer 1231 as an editorial change, not as a semantic change. Similarly, 1232 removal of a range or size constraint from an object definition 1233 when that range or size constraint is enforced by the underlying 1234 data type SHOULD be treated by a reviewer as an editorial change. 1236 RFC 2578 Section 10.3 specifies rules that apply to revisions of 1237 notification definitions. No clarifications or corrections are 1238 required. 1240 RFC 2579 Section 5 specifies rules that apply to revisions of textual 1241 convention definitions. The following guideline corrects an error in 1242 these rules: 1244 - Bullet (1) allows the labels of named numbers and named bits in 1245 SYNTAX clauses of type enumerated INTEGER or BITS to be changed. 1246 This can break compilation compatibility, since those labels may be 1247 used by DEFVAL clauses in modules that import the definitions of 1248 the affected TCs. Therefore, labels of named numbers and named 1249 bits MUST NOT be changed when revising IETF MIB modules (except to 1250 correct typographical errors), and they SHOULD NOT be changed when 1251 revising enterprise MIB modules. 1253 RFC 2580 Section 7.1 specifies rules that apply to revisions of 1254 conformance groups. Two point are worth re-iterating: 1256 - Objects and notifications MUST NOT be added to or removed from an 1257 existing object group or notification group. Doing so could cause 1258 a compilation failure or (worse) a silent change in the meaning of 1259 a compliance statement or capabilities statement that refers to 1260 that group. 1262 - The status of a conformance group is independent of the status of 1263 its members. Thus, a current group MAY refer to deprecated objects 1264 or notifications. This may be desirable in certain cases, e.g., a 1265 set of widely-deployed objects or notifications may be deprecated 1266 when they are replaced by a more up-to-date set of definitions, but 1267 the conformance groups that contain them may remain current in 1268 order to encourage continued implementation of the deprecated 1269 objects and notifications. 1271 RFC 2580 Section 7.2 specifies rules that apply to revisions of 1272 compliance statements. The following guidelines correct an omission 1273 from these rules and emphasize one important point: 1275 - RFC 2580 should (but does not) recommend that OBJECT clauses 1276 specifying support for the original set of values be added to a 1277 compliance statement when enumerated INTEGER objects or BITS 1278 objects referenced by the compliance statement have enumerations 1279 added, assuming that no such clauses are already present. This is 1280 necessary in order to avoid a silent change to the meaning of the 1281 compliance statement. MIB module authors and reviewers SHOULD 1282 watch for this to ensure that such OBJECT clauses are added when 1283 needed. Note that this may not always be possible to do, since 1284 affected compliance statements may reside in modules other than the 1285 one that contains the revised definition(s). 1287 - The status of a compliance statement is independent of the status 1288 of its members. Thus, a current compliance statement MAY refer to 1289 deprecated object groups or notification groups. This may be 1290 desirable in certain cases, e.g., a set of widely-deployed object 1291 or notification groups may be deprecated when they are replaced by 1292 a more up-to-date set of definitions, but compliance statements 1293 that refer to them may remain current in order to encourage 1294 continued implementation of the deprecated groups. 1296 RFC 2580 Section 7.3 specifies rules that apply to revisions of 1297 capabilities statements. The following guideline corrects an 1298 omission from these rules: 1300 - RFC 2580 should (but does not) recommend that VARIATION clauses 1301 specifying support for the original set of values be added to a 1302 capabilities statement when enumerated INTEGER objects or BITS 1303 objects referenced by the capabilities statement have enumerations 1304 added, assuming that no such clauses are already present. This is 1305 necessary in order to avoid a silent change to the meaning of the 1306 capabilities statement. 1308 In certain exceptional situations the cost of strictly following the 1309 SMIv2 rules governing MIB modules revisions may exceed the benefit. 1310 In such cases the rules can be waived, but when that is done both the 1311 change and the justification for it MUST be thoroughly documented. 1312 One example is provided by Section 3.1.5 of RFC 2863, which documents 1313 the semantic change that was made to ifIndex in the transition from 1314 MIB-II [RFC1213] to the IF-MIB [RFC2863] and provides a detailed 1315 justification for that change. Another example is provided by the 1316 REVISION clause of the SONET-MIB [RFC2558] that documents raising the 1317 MAX-ACCESS of several objects to read-write while adding MIN-ACCESS 1318 of read-only for compatibility with the previous version [RFC1595]. 1320 Authors and reviewers may find it helpful to use tools that can list 1321 the differences between two revisions of a MIB module. Please see 1322 http://www.ops.ietf.org/mib-review-tools.html for more information. 1324 Appendix A: MIB Review Checklist 1326 The purpose of a MIB review is to review the MIB module both for 1327 technical correctness and for adherence to IETF documentation 1328 requirements. The following checklist may be helpful when reviewing 1329 a draft document: 1331 1.) I-D Boilerplate -- verify that the draft contains the required 1332 Internet Draft boilerplate (see http://www.ietf.org/ietf/1id- 1333 guidelines.txt), including the appropriate statement to permit 1334 publication as an RFC, and that I-D boilerplate does not contain 1335 references or section numbers. 1337 2.) Abstract -- verify that the abstract does not contain references, 1338 that it does not have a section number, and that its content follows 1339 the guidelines in [RFC2223bis]. 1341 3.) MIB Boilerplate -- verify that the draft contains the latest 1342 approved SNMP Network Management Framework boilerplate from the OPS 1343 area web site (http://www.ops.ietf.org/mib-boilerplate.html). 1345 4.) IPR Notices -- verify that the draft contains verbatim copies of 1346 the IPR notices specified in bullets (A) and (B) and if needed bullet 1347 (D) of Section 10.4 of RFC 2026. 1349 5.) References -- verify that the references are properly divided 1350 between normative and informative references, that RFC 2119 is 1351 included as a normative reference if the terminology defined therein 1352 is used in the document, that all references required by the 1353 boilerplate are present, that all MIB modules containing imported 1354 items are cited as normative references, and that all citations point 1355 to the most current RFCs unless there is a valid reason to do 1356 otherwise (for example, it is OK to include an informative reference 1357 to a previous version of a specification to help explain a feature 1358 included for backward compatibility). 1360 6.) Security Considerations Section -- verify that the draft uses the 1361 latest approved template from the OPS area web site 1362 (http://www.ops.ietf.org/mib-security.html) and that the guidelines 1363 therein have been followed. 1365 7.) IANA Considerations Section -- if the draft contains the initial 1366 version of an IANA-maintained module, verify that the MODULE-IDENTITY 1367 invocation contains maintenance instructions that comply with RFC 1368 2434. Note that the IANA Considerations section that will appear in 1369 the RFC MUST contain a pointer to the actual IANA-maintained module. 1371 8.) Copyrights -- verify that the draft contains a copyright notice 1372 on the front page and in the DESCRIPTION clause of the MODULE- 1373 IDENTITY invocation and there is a full copyright notice section with 1374 text matching that in recently published RFCs. Make sure that the 1375 year is up-to-date in all three places. 1377 9.) Other issues -- check for any issues mentioned in 1378 http://www.ietf.org/ID-nits.html (other than MIB compilation) that 1379 are not covered above. 1381 10.) Technical content -- review the actual technical content for 1382 compliance with the guidelines in this document. The use of a MIB 1383 compiler is recommended when checking for syntax errors; see 1384 http://www.ops.ietf.org/mib-review-tools.html for more information. 1385 Checking for correct syntax, however, is only part of the job. It is 1386 just as important to actually read the MIB document from the point of 1387 view of a potential implementor. It is particularly important to 1388 check that DESCRIPTION clauses are sufficiently clear and unambiguous 1389 to allow interoperable implementations to be created. 1391 Appendix B: Commonly Used Textual Conventions 1393 The following TCs are defined in SNMPv2-TC [RFC2579]: 1395 DisplayString OCTET STRING (SIZE (0..255)) 1396 PhysAddress OCTET STRING 1397 MacAddress OCTET STRING (SIZE (6)) 1398 TruthValue enumerated INTEGER 1399 TestAndIncr INTEGER (0..2147483647) 1400 AutonomousType OBJECT IDENTIFIER 1401 VariablePointer OBJECT IDENTIFIER 1402 RowPointer OBJECT IDENTIFIER 1403 RowStatus enumerated INTEGER 1404 TimeStamp TimeTicks 1405 TimeInterval INTEGER (0..2147483647) 1406 DateAndTime OCTET STRING (SIZE (8 | 11)) 1407 StorageType enumerated INTEGER 1408 TDomain OBJECT IDENTIFIER 1409 TAddress OCTET STRING (SIZE (1..255)) 1411 Note 1. InstancePointer is obsolete and MUST NOT be used. 1413 Note 2. DisplayString does not support internationalized text. 1414 It MUST NOT be used for objects that are required to 1415 hold internationalized text (which is always the case 1416 if the object is intended for use by humans [RFC2277]). 1417 Designers SHOULD consider using SnmpAdminString, 1418 Utf8String, or LongUtf8String for such objects. 1420 The following TC is defined in SNMP-FRAMEWORK-MIB [RFC3411]: 1422 SnmpAdminString OCTET STRING (SIZE (0..255)) 1424 The following TCs are defined in SYSAPPL-MIB [RFC2287]: 1426 Utf8String OCTET STRING (SIZE (0..255)) 1427 LongUtf8String OCTET STRING (SIZE (0..1024)) 1429 The following TCs are defined in INET-ADDRESS-MIB [RFC3291]: 1431 InetAddressType enumerated INTEGER 1432 InetAddress OCTET STRING (SIZE (0..255)) 1433 InetAddressPrefixLength Unsigned32 1434 InetPortNumber Unsigned32 (0..65535)) 1435 InetAutonomousSystemNumber Unsigned32 1436 The following TCs are defined in TRANSPORT-ADDRESS-MIB [RFC3419]: 1438 TransportDomain OBJECT IDENTIFIER 1439 TransportAddressType enumerated INTEGER 1440 TransportAddress OCTET STRING (SIZE (0..255)) 1442 The following TC is defined in RMON2-MIB [RFC2021]: 1444 ZeroBasedCounter32 Gauge32 1446 The following TCs are defined in HCNUM-TC [RFC2856]: 1448 ZeroBasedCounter64 Counter64 1449 CounterBasedGauge64 Counter64 1451 The following TCs are defined in IF-MIB [RFC2863]: 1453 InterfaceIndex Integer32 (1..2147483647) 1454 InterfaceIndexOrZero Integer32 (0..2147483647) 1456 The following TCs are defined in PerfHist-TC-MIB [RFC2493]: 1458 PerfCurrentCount Gauge32 1459 PerfIntervalCount Gauge32 1460 PerfTotalCount Gauge32 1462 Appendix C: Suggested Naming Conventions 1464 Authors and reviewers of IETF MIB modules have often found the 1465 following naming conventions to be helpful in the past, and authors 1466 of new IETF MIB modules are urged to consider following them. 1468 - The module name should be of the form XXX-MIB, where XXX is a 1469 unique prefix (usually all caps with hyphens for separators) that 1470 is not used by any existing IETF MIB module. For example, the MIB 1471 module for managing optical interfaces [OPTIF] uses the prefix 1472 OPT-IF and has module name OPT-IF-MIB. 1474 - The descriptor associated with the MODULE-IDENTITY invocation 1475 should be of the form xxxMIB, xxxMib, or xxxMibModule, where xxx is 1476 a mixed-case version of XXX starting with a lower-case letter and 1477 without any hyphens. For example, the OPT-IF-MIB uses the prefix 1478 optIf, and the descriptor associated with its MODULE-IDENTITY 1479 invocation is optIfMibModule. 1481 - Other descriptors within the MIB module should start with the same 1482 prefix xxx. OPT-IF-MIB uses the prefix optIf for all descriptors. 1484 - Names of TCs that are specific to the MIB module and names of 1485 SEQUENCE types that are used in conceptual table definitions should 1486 start with a prefix Xxx that is the same as xxx but with the 1487 initial letter changed to upper case. OPT-IF-MIB uses the prefix 1488 OptIf on the names of TCs and SEQUENCE types. 1490 - The descriptor associated with a conceptual table should be of the 1491 form xxxZzzTable; the descriptor associated with the corresponding 1492 conceptual row should be of the form xxxZzzEntry; the name of the 1493 associated SEQUENCE type should be of the form XxxZzzEntry; and 1494 the descriptors associated with the subordinate columnar objects 1495 should be of the form xxxZzzSomeotherName. An example from the 1496 OPT-IF-MIB is the OTMn table. The descriptor of the table object 1497 is optIfOTMnTable, the descriptor of the row object is 1498 optIfOTMnEntry, the name of the associated SEQUENCE type is 1499 OptIfOTMnEntry, and the descriptors of the columnar objects are 1500 optIfOTMnOrder, optIfOTMnReduced, optIfOTMnBitRates, 1501 optIfOTMnInterfaceType, optIfOTMnTcmMax, and optIfOTMnOpticalReach. 1503 - When abbreviations are used, then they should be used consistently. 1504 Inconsistent usage such as 1506 xxxYyyDestAddr 1507 xxxZzzDstAddr 1509 should be avoided. 1511 Appendix D: Suggested OID Layout 1513 As noted in RFC 2578 Section 5.6, it is common practice to use the 1514 value of the MODULE-IDENTITY invocation as a subtree under which 1515 other OBJECT IDENTIFIER values assigned within the module are 1516 defined. That, of course, leaves open the question of how OIDs are 1517 assigned within that subtree. One assignment scheme that has gained 1518 favor -- and which is RECOMMENDED unless there is a specific reason 1519 not use it -- is to have three separate branches immediately below 1520 the MODULE-IDENTITY value dedicated (respectively) to notification 1521 definitions, object definitions, and conformance definitions, and to 1522 further subdivide the conformance branch into separate sub-branches 1523 for compliance statements and object/notification groups. This 1524 structure is illustrated below, with naming conventions following 1525 those outlined in Appendix C. The numbers in parentheses are the 1526 sub-identifiers assigned to the branches. 1528 xxxMIB 1529 | 1530 +-- xxxNotifications(0) 1531 +-- xxxObjects(1) 1532 +-- xxxConformance(2) 1533 | 1534 +-- xxxCompliances(1) 1535 +-- xxxGroups(2) 1537 When using this scheme notification definition values are assigned 1538 immediately below the xxxNotifications node. This ensures that each 1539 OID assigned to a notification definition has a next-to-last sub- 1540 identifier of zero, which is REQUIRED by Section 4.7 above. The 1541 other sub-branches may have additional sub-structure, but none beyond 1542 that specified in Section 4.6.5 above is actually required. 1544 One example of a MIB module whose OID assignments follow this scheme 1545 is the POWER-ETHERNET-MIB [PETH-MIB]. 1547 Intellectual Property 1549 The IETF takes no position regarding the validity or scope of any 1550 intellectual property or other rights that might be claimed to 1551 pertain to the implementation or use of the technology described in 1552 this document or the extent to which any license under such rights 1553 might or might not be available; neither does it represent that it 1554 has made any effort to identify any such rights. Information on the 1555 IETF's procedures with respect to rights in standards-track and 1556 standards-related documentation can be found in BCP-11. Copies of 1557 claims of rights made available for publication and any assurances of 1558 licenses to be made available, or the result of an attempt made to 1559 obtain a general license or permission for the use of such 1560 proprietary rights by implementors or users of this specification can 1561 be obtained from the IETF Secretariat. 1563 The IETF invites any interested party to bring to its attention any 1564 copyrights, patents or patent applications, or other proprietary 1565 rights which may cover technology that may be required to practice 1566 this standard. Please address the information to the IETF Executive 1567 Director. 1569 Normative References 1571 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", 1572 BCP 9, RFC 2026, October 1996. 1574 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1575 Requirements Levels", BCP 14, RFC 2119, March 1997. 1577 [RFC2223bis] 1578 Reynolds, J., and R. Braden, "Instructions to Request for 1579 Comments (RFC) Authors", work in progress (currently 1580 ). 1582 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 1583 Languages", BCP 18, RFC 2277, January 1998. 1585 [RFC2434] Alvestrand, H., "Guidelines for Writing an IANA 1586 Considerations Section in RFCs", BCP 26, RFC 2434, October 1587 1998. 1589 [RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1590 Rose, M. and S. Waldbusser, "Structure of Management 1591 Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1592 1999. 1594 [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1595 Rose, M. and S. Waldbusser, "Textual Conventions for 1596 SMIv2", STD 58, RFC 2579, April 1999. 1598 [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1599 Rose, M. and S. Waldbusser, "Conformance Statements for 1600 SMIv2", STD 58, RFC 2580, April 1999. 1602 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 1603 MIB", RFC 2863, June 2000. 1605 [RFC2864] McCloghrie, K. and G. Hanson, "The Inverted Stack Table 1606 Extension to the Interfaces Group MIB", RFC 2864, June 2000. 1608 [RFC2493] Tesink, K., "Textual Conventions for MIB Modules Using 1609 Performance History Based on 15 Minute Intervals", RFC 2493, 1610 January 1999. 1612 [RFC2021] Waldbusser, S., "Remote Network Monitoring Management 1613 Information Base Version 2 using SMIv2", RFC 2021, January 1614 1997. 1616 [RFC2856] Bierman, A., McCloghrie, K. and R. Presuhn, "Textual 1617 Conventions for Additional High Capacity Data Types", RFC 1618 2856, June 2000. 1620 [RFC3291] Daniele, M., Haberman, B., Routhier, S. and J. 1621 Schoenwaelder, "Textual Conventions for Internet Network 1622 Addresses", RFC 3291, May 2002. 1624 [RFC2287] Krupczak, C. and J. Saperia, "Definitions of System-Level 1625 Managed Objects for Applications", RFC 2287, February 1998. 1627 [RFC3411] Harrington, D., Presuhn, R. and B. Wijnen, "An Architecture 1628 for Describing Simple Network Management Protocol (SNMP) 1629 Management Frameworks", STD 62, RFC 3411, December 2002. 1631 [RFC3416] Presuhn, R., Case, J., McCloghrie, K., Rose, M. and S. 1632 Waldbusser, "Protocol Operations for the Simple Network 1633 Management Protocol (SNMP)", STD 62, RFC 3416, December 1634 2002. 1636 [RFC3418] Presuhn, R., Case, J., McCloghrie, K., Rose, M. and S. 1637 Waldbusser, "Management Information Base (MIB) for the 1638 Simple Network Management Protocol (SNMP)", STD 62, RFC 1639 3418, December 2002. 1641 [RFC3419] M. Daniele, M. and J. Schoenwaelder, "Textual Conventions 1642 for Transport Addresses", RFC 3419, December 2002. 1644 Informative References 1646 [RFC3410] Case, J., Mundy, R., Partain, D. and B. Stewart, 1647 "Introduction and Applicability Statements for Internet- 1648 Standard Management Framework", RFC 3410, December 2002. 1650 [RFC1155] Rose, M. and K. McCloghrie, "Structure and Identification of 1651 Management Information for TCP/IP-based Internets", STD 16, 1652 RFC 1155, May 1990. 1654 [RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 1655 16, RFC 1212, March 1991. 1657 [RFC1215] Rose, M., "A Convention for Defining Traps for use with the 1658 SNMP", RFC 1215, March 1991. 1660 [RFC2932] McCloghrie, K., Farinacci, D., and D. Thaler, "IPv4 1661 Multicast Routing MIB", RFC 2932, October 2000. 1663 [RFC1573] McCloghrie, K. and F. Kastenholz, "Evolution of the 1664 Interfaces Group of MIB-II", RFC 1573, January 1994. 1666 [RFC2576] Frye, R., Levi, D., Routhier, S. and B. Wijnen, "Coexistence 1667 between Version 1, Version 2, and Version 3 of the 1668 Internet-standard Network Management Framework", RFC 2576, 1669 March 2000. 1671 [RFC2108] de Graaf, K., Romascanu, D., McMaster, D. and K. McCloghrie, 1672 "Definitions of Managed Objects for IEEE 802.3 Repeater 1673 Devices using SMIv2", RFC 2108, February 1997. 1675 [RFC2737] McCloghrie, K. and A. Bierman, "Entity MIB (Version 2)", RFC 1676 2737, December 1999. 1678 [RFC3289] Baker, F., Chan, K. and A. Smith, "Management Information 1679 Base for the Differentiated Services Architecture", RFC 1680 3289, May 2002. 1682 [RFC1213] McCloghrie, K. and M. Rose, "Management Information Base for 1683 Network Management of TCP/IP-based internets - MIB-II", STD 1684 17, RFC 1213, March 1991. 1686 [RFC1595] Brown, T. and K. Tesink, "Definitions of Managed Objects for 1687 the SONET/SDH Interface Type", RFC 1595, March 1994. 1689 [RFC2558] Tesink, K., "Definitions of Managed Objects for the 1690 SONET/SDH Interface Type", RFC 2558, March 1999. 1692 [OPTIF] Lam, H., Stewart, M. and A. Huynh, "Definitions of Managed 1693 Objects for the Optical Interface Type", work in progress 1694 (currently ). 1696 [PETH-MIB] Berger, Avi and D. Romascanu, "Power Ethernet MIB", work in 1697 progress (currently ). 1700 Security Considerations 1702 Implementation and deployment of a MIB module in a system may result 1703 in security risks that would not otherwise exist. It is important 1704 for authors and reviewers of documents that define MIB modules to 1705 ensure that those documents fully comply with the guidelines in 1706 http://www.ops.ietf.org/mib-security.html so that all such risks are 1707 adequately disclosed. 1709 Acknowledgments 1711 Most of the material on usage of data types was based on input 1712 provided by Bert Wijnen with assistance from Keith McCloghrie, David 1713 T. Perkins, and Juergen Schoenwaelder. Much of the other material on 1714 SMIv2 usage was taken from an unpublished guide for MIB authors and 1715 reviewers by Juergen Schoenwaelder. Some of the recommendations in 1716 these guidelines are based on material drawn from the on-line SMIv2 1717 errata list at http://www.ibr.cs.tu-bs.de/ietf/smi-errata/. Thanks 1718 to Frank Strauss and Juergen Schoenwaelder for maintaining that list 1719 and to the contributors who supplied the material for that list. 1720 Finally, thanks are due to the following individuals whose comments 1721 on earlier versions of this memo contained many valuable suggestions 1722 for additions, clarifications, and corrections: Andy Bierman, David 1723 Harrington, Harrie Hazewinkel, Michael Kirkham, Keith McCloghrie, 1724 David T. Perkins, Randy Presuhn, Dan Romascanu, Juergen 1725 Schoenwaelder, Frank Strauss, Dave Thaler, and Bert Wijnen. 1727 Editor's Address 1729 C. M. Heard 1730 600 Rainbow Dr. #141 1731 Mountain View, CA 94041-2542 1732 USA 1734 Phone: +1 650 964 8391 1735 EMail: heard@pobox.com 1737 Full Copyright Statement 1739 Copyright (C) The Internet Society (2003). All Rights Reserved. 1741 This document and translations of it may be copied and furnished to 1742 others, and derivative works that comment on or otherwise explain it 1743 or assist in its implementation may be prepared, copied, published 1744 and distributed, in whole or in part, without restriction of any 1745 kind, provided that the above copyright notice and this paragraph are 1746 included on all such copies and derivative works. However, this 1747 document itself may not be modified in any way, such as by removing 1748 the copyright notice or references to the Internet Society or other 1749 Internet organizations, except as needed for the purpose of 1750 developing Internet standards in which case the procedures for 1751 copyrights defined in the Internet Standards process must be 1752 followed, or as required to translate it into languages other than 1753 English. 1755 The limited permissions granted above are perpetual and will not be 1756 revoked by the Internet Society or its successors or assigns. 1758 This document and the information contained herein is provided on an 1759 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1760 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1761 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1762 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1763 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1765 Acknowledgement 1767 Funding for the RFC Editor function is currently provided by the 1768 Internet Society. 1770 Revision History 1772 NOTE TO RFC Editor: this section is to be removed prior to 1773 publication as an RFC. 1775 The following changes were made to to produce : 1779 1.) The Abstract, Section 1, and Section 3 were revised to 1780 clarify that the guidelines are targeted specifically at IETF 1781 standards-track documents containing MIB modules but may be used 1782 as a basis for reviews of other documents containing MIB modules. 1784 2.) A note was added to Section 1 pointing out that some of the 1785 guidelines do not apply to MIB modules that have been converted to 1786 SMIv2 from SMIv1. 1788 3.) A note was added to Section 2 clarifying that the term 1789 "standard", when it appears in quotes, is being used in the same 1790 way as in RFCs 2578/2579/2580. 1792 4.) A typo (s/MIB modules/MIB module(s)/) was corrected in 1793 Section 3.3. 1795 5.) The second paragraph of Section 3.5 was revised to include a 1796 requirement for a normative reference to the on-line version of an 1797 IANA-maintained MIB module that appears in an IMPORTS statement. 1799 6.) Additional instructions to authors regarding the preparation 1800 of a Security Considerations section were incorporated into 1801 Section 3.6. 1803 7.) A typo (s/defined/defines/) was corrected in the second 1804 paragraph of Section 3.7. 1806 8.) In accordance with a recent IESG decision, the third 1807 paragraph of Section 3.7 was revised to state that the accepted 1808 procedure for the initial version of an IANA-maintained MIB module 1809 is to publish it in a non-normative section of the initial issue 1810 of the document that defines the corresponding name space, as was 1811 done in RFC 1573 for the IANAifType-MIB. 1813 9.) An Editor's Note was added to Section 3.8 to alert authors 1814 and reviewers that a copyright notice will be required in the 1815 MODULE-IDENTITY invocation of IANA-maintained MIB modules with the 1816 exact form still to be determined. 1818 10.) A pointer to the suggested naming conventions in Appendix E 1819 was added to Section 4.1. 1821 11.) In Section 4.2 the phrase "descriptors" was changed to 1822 "descriptors and TC names" to align with the usage in the SMIv2 1823 documents, and a pointer to the suggested naming conventions in 1824 Appendix E was added. 1826 12.) An editorial correction (s/"standard"/standards-track) was 1827 made to Section 4.4. 1829 13.) A typo (s/groups's/group's) was corrected in the first bullet 1830 in Section 4.5. 1832 14.) The third bullet in Section 4.5 was revised to clarify that 1833 IETF standards-track MIB modules are to be registered under the 1834 mgmt subtree and to say (based on experience reported by the RMON 1835 MIB working group chair) that IETF working groups SHOULD NOT 1836 assign top-level OIDs from subtrees delegated to them by IANA. 1838 15.) An editorial change (s/appropriate/acceptable/) was made to 1839 the paragraph of Section 4.6.1.1 that deals with Gauge32 index 1840 objects. 1842 16.) Section 4.6.1.2 was revised to state that (i) the DESCRIPTION 1843 clauses of Counter32/Counter64 objects MUST specify epochs of 1844 discontinuities (other than agent re-initialization) with enough 1845 precision to allow a manager to determine if data is valid and 1846 (ii) discontinuity indicators are the RECOMMENDED way to do this. 1848 17.) A note was added to Section 4.6.1.2 stating that the 1849 Counter64 type MUST be used for objects that would roll over in 1850 less than one hour if Counter32 was used instead and that the 1851 existing rule allowing Counter64 only under those circumstances is 1852 obsolete and should no longer be enforced. 1854 18.) The Utf8String and LongUtf8String TCs were added to the list 1855 of specialized OCTET STRING types mentioned in Section 4.6.1.4. 1857 19.) A typo (s/RowPointerTCs/RowPointer TCs/) was corrected in 1858 Section 4.6.1.5. 1860 20.) A wording change (s/MUST be contiguous/SHOULD be contiguous/) 1861 was made to Section 4.6.1.6 to make it agree with RFC 2578. 1863 21.) A note was added to Section 4.6.1.10 stating that when an 1864 object definition uses an imported TC that could later be extended 1865 (as is the case for some enumerated INTEGER and BITS TCs) then the 1866 value set that must be supported SHOULD be documented if the 1867 object is writeable or is an index of a read-create table. 1869 22.) A typo was corrected in the nroff source that caused the 1870 second line in the second paragraph of Section 4.6.2 to be omitted 1871 from the formatted text. 1873 23.) A note was added to Section 4.6.2 stating that the 1874 DESCRIPTION clause of a read-write object SHOULD document what 1875 happens to the value after a reboot unless the object is a column 1876 in a read-create table with well-defined persistence properties. 1878 24.) A bullet was added to the first list in Section 4.6.3 stating 1879 that IMPLIED SHOULD NOT be used on index objects that might appear 1880 in expansion tables and providing some reasons why using IMPLIED 1881 often does not have the expected benefits. 1883 25.) An editorial change (s/row object/row object (table entry)/) 1884 was made to the second bullet of the second list in Section 4.6.3. 1886 26.) A note was added to Secton 4.6.4 explicitly stating that 1887 object definitions SHOULD NOT be registered beneath conformance 1888 group definitions, MODULE-COMPLIANCE definitions, or AGENT- 1889 CAPABILITIES definitions (or vice-versa). 1891 27.) A typo (s/128 OID limitation/128 sub-identifier) was 1892 corrected in the first paragraph of Section 4.6.5. 1894 28.) The second paragraph of Section 4.6.5 was revised to state 1895 that size limitations on index variables that need to be observed 1896 by management software SHOULD be spelled out. 1898 29.) The phrase "second technique" was changed to "fixed time 1899 interval technique" in the last sentence of the of the paragraph 1900 of Section 4.7 that discusses notification throttling. 1902 30.) The phrase "in situations where it is appropriate" was 1903 changed to "when it is applicable" at the end of the bullet in 1904 Section 4.8 that discusses when to write full compliance and 1905 read-only compliance statements. 1907 31.) A paragraph was added to Section 4.8 (just before the 1908 endnote) stating that prerequisite modules and in some some cases 1909 specific groups from such modules SHOULD be mentioned in the 1910 compliance statements. 1912 32.) Two typos (s/implemantations/implementations/ and 1913 s/descriptions/descriptors/) were corrected in the fourth 1914 paragraph of Section 4.9. 1916 33.) A typo (s/boilerplace/boilerplate/) was fixed in checklist 1917 item #5 of Appendix A. 1919 34.) An item was added to the checklist in Appendix A requiring 1920 reviewers to check for things in http://www.ietf.org/ID-nits.html 1921 that are not covered elsewhere. This became item #10; the 1922 existing technical content review became item #11. 1924 35.) The default smilint switches in Appendix B were changed from 1925 "-m -s -l 9 -i namelength-32" to "-m -s -l 6 -i namelength-32" at 1926 the request of the authors of the program (currently there are no 1927 level 7, 8, or 9 diagnostics, and it is desired to reserve those 1928 levels for things that are of no concern in an IETF MIB review). 1930 36.) A note was added to Appendix D stating that the DisplayString 1931 TC is no longer permitted for objects that are intended for human 1932 consumption, and the Utf8String and LongUtf8String TCs from 1933 SYSAPPL-MIB were added to the list of standard TCs. 1935 37.) Suggested naming conventions were documented in Appendix E. 1937 38.) Normative references to RFCs 2277 and 2287 were added. 1939 39.) Informative references to RFC 1573 and OPT-IF-MIB were added. 1941 40.) The "Acknowledgements" section was updated. 1943 The following changes were made to to produce : 1947 1.) These following changes were made to avoid the implication 1948 that reviews are required only for OPS Area MIB documents: 1949 Section 1: s/OPS area review/expert review/ 1950 Section 4.2: s/OPS Area MIB reviewers/MIB reviewers/ 1951 Section 4.8: s/OPS Area MIB reviewers/MIB reviewers/ 1953 2.) Imperatives from RFC 2119 were capitalized in the following 1954 places: Section 3.2 (last paragraph), Section 3.8 (first 1955 paragraph), Section 4.9 (first bullet in first paragraph), and 1956 Appendix A (checklist item #7). 1958 3.) The EDITOR'S NOTE in Section 3.8 was replaced with text 1959 describing the actual form of the copyright notice that is now 1960 required for IANA-maintained MIB modules. 1962 4.) In Sections 4.1 & 4.2: s/Appendix E/Appendix C/ (appendices 1963 were renumbered owing to the elimination of -01 appendices B & C). 1965 5.) Two typographical errors (s/the the/the/, 1966 s/ifCounterDisconuityTime/ifCounterDiscontinuityTime/) were 1967 corrected in the first bullet of Section 4.6.1.2. 1969 6.) In Section 4.6.1.10 a pointer was added to the "Common TCs" 1970 page (http://www.ops.ietf.org/mib-common-tcs.html) on the OPS Area 1971 web site. 1973 7.) A "DISPLAY-HINT Clause" section was added; it is Section 1974 4.6.3 in the -02 draft. The following section numbers have 1975 changed as a result of this addition: 1977 -01 section number -02 section number 1978 4.6.3 4.6.4 1979 4.6.4 4.6.5 1980 4.6.5 4.6.6 1982 8.) A typographical error (s/are can be/can be/) was corrected in 1983 Section 4.6.4 (formerly Section 4.6.3). 1985 9.) In Sections 4.6.5 (formerly 4.6.4) and 4.7 a pointer to the 1986 new "Suggested OID Layout" appendix was added (it is Appendix D in 1987 the -02 draft, owing to the elimination of -01 appendices B & C). 1989 10.) In Section 4.7 the notification throttling text was 1990 wordsmithed. 1992 11.) A typographical error (s/following contains the/following/) 1993 was corrected in the third paragraph of Section 4.8. 1995 12.) The text of Section 4.9, third paragraph, first bullet and 1996 fifth paragraph, first bullet was revised to allow changes to BITS 1997 and enum labels in order to correct typographical errors. 1999 13.) The text of Section 4.9, third paragraph, second bullet was 2000 revised to allow redundant range or size constraints to be 2001 removed. 2003 14.) In the last paragraph of Section 4.9 the references to 2004 smidiff and -01 Appendix B were replaced by a pointer to the "MIB 2005 Review Tools" page (http://www.ops.ietf.org/mib-review-tools.html) 2006 on the OPS Area web site. 2008 15.) The text of Appendix A, checklist item #7 was corrected to 2009 reflect actual IESG policy on publication of initial versions of 2010 IANA-maintained MIB modules in RFCs. It is now consistent with 2011 Section 3.7. 2013 16.) In Appendix A draft -01 checklist items #9, #10, and #11 were 2014 consolidated into -02 checklist items #9 (which is equivalent to 2015 -01 checklist item #10) and #10 (which is equivalent to the union 2016 of -01 items #9 and #11). The new item #10 consolidates the MIB 2017 compilation step into the technical review, and replaces mention 2018 of specific MIB compilation tools with a a pointer to the "MIB 2019 Review Tools" page (http://www.ops.ietf.org/mib-review-tools.html) 2020 on the OPS Area web site. 2022 17.) Draft -01 appendices B and C have been eliminated. They have 2023 been superseded by the "MIB Review Tools" page on the OPS Area web 2024 site (http://www.ops.ietf.org/mib-review-tools.html). The 2025 following appendix names have changed as a result: 2027 -01 appendix name -02 appendix name 2028 Appendix D Appendix B 2029 Appendix E Appendix C 2031 18.) A new "Suggested OID Layout" appendix was added. It is 2032 Appendix D in the -02 draft, owing to the elimination of -01 2033 appendices B & C. 2035 Open Issues 2037 NOTE TO RFC Editor: this section is to be removed prior to 2038 publication as an RFC. 2040 1.) There is work in progress by IPR working group to update RFC 2041 2026 Section 10 that will probably require updates to this memo. 2043 ************************************************************ 2044 * NOTES TO RFC Editor (to be removed prior to publication) * 2045 * * 2046 * 1.) The normative reference [RFC2223bis] currently * 2047 * points to a work in progress that is intended to replace * 2048 * RFC 2223. Please update that reference to point to the * 2049 * forthcoming RFC that replaces RFC 2223, and replace all * 2050 * occurrences of "2223bis" with the number of that RFC. * 2051 * * 2052 * 2.) The I-D is * 2053 * currently in the publication queue and will eventually * 2054 * replace RFC 2493. If that draft is published as an RFC * 2055 * prior to or concurrently with this document, then the * 2056 * normative reference [RFC2493] should be updated to * 2057 * point to the replacement RFC, and the reference tag * 2058 * [RFC2493] should be updated to match. * 2059 * * 2060 * 3.) The I-D (or a * 2061 * successor) is expected to eventually replace RFC 3291. * 2062 * If that draft (or a successor) is published as an RFC * 2063 * prior to or concurrently with this document, then the * 2064 * normative reference [RFC3291] should be updated to * 2065 * point to the replacement RFC, and the reference tag * 2066 * [RFC3291] should be updated to match. * 2067 * * 2068 * 4.) The I-D is * 2069 * currently in the publication queue and will eventually * 2070 * replace RFC 2576. If that draft is published as an RFC * 2071 * prior to or concurrently with this document, then the * 2072 * informative reference [RFC2576] should be updated to * 2073 * point to the replacement RFC, and the reference tag * 2074 * [RFC2576] should be updated to match. * 2075 * * 2076 * 5.) The I-D (or a * 2077 * successor) is expected to eventually replace RFC 2737. * 2078 * If that draft (or a successor) is published as an RFC * 2079 * prior to or concurrently with this document, then the * 2080 * informative reference [RFC2737] should be updated to * 2081 * point to the replacement RFC, and the reference tag * 2082 * [RFC2737] should be updated to match. * 2083 * * 2084 ************************************************************ 2085 ************************************************************ 2086 * NOTES TO RFC Editor (continued) * 2087 * * 2088 * 6.) The informative reference [OPTIF] points to a work * 2089 * in progress that * 2090 * is currently in the publication queue. If that draft is * 2091 * published as an RFC prior to or concurrently with this * 2092 * document, please update the reference to point to the * 2093 * published RFC and update the reference tag to match. * 2094 * * 2095 * 7.) The informative reference [PETH-MIB] points to a work* 2096 * in progress * 2097 * that is currently in IETF Last Call. If that draft * 2098 * or a successor) is published as an RFC prior to or * 2099 * concurrently with this document, please update the * 2100 * reference to point to the published RFC and update the * 2101 * reference tag to match. * 2102 * * 2103 ************************************************************