idnits 2.17.1 draft-ietf-ops-mib-review-guidelines-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1899. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1912. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 1876), which is fine, but *also* found old RFC 2026, Section 10.4C, paragraph 1 text on line 39. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** The document seems to lack an RFC 3978 Section 5.5 (updated by RFC 4748) Disclaimer -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack an RFC 3979 Section 5, para. 2 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == 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 58 has weird spacing: '...cuments that ...' == 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 (February 2005) is 7007 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 2434 (Obsoleted by RFC 5226) ** Downref: Normative reference to an Not Issued RFC: RFC 3907 ** Downref: Normative reference to an Not Issued RFC: RFC 3908 ** Obsolete normative reference: RFC 2021 (Obsoleted by RFC 4502) -- Obsolete informational reference (is this intentional?): RFC 2223 (Obsoleted by RFC 7322) -- 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 1595 (Obsoleted by RFC 2558) -- Obsolete informational reference (is this intentional?): RFC 2558 (Obsoleted by RFC 3592) Summary: 10 errors (**), 0 flaws (~~), 5 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT C. M. Heard, Editor 3 February 2005 5 Guidelines for Authors and Reviewers of MIB Documents 7 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patents or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html 32 Comments on this memo should be submitted to the 33 mailing list. To subscribe to this mailing 34 list send an e-mail message to with 35 the word "subscribe" in the message body. 37 Copyright Notice 39 Copyright (C) The Internet Society (2005). All Rights Reserved. 41 Abstract 43 This memo provides guidelines for authors and reviewers of IETF 44 standards-track specifications containing MIB modules. Applicable 45 portions may used as a basis for reviews of other MIB documents. 47 Table of Contents 49 1 Introduction .............................................. 4 50 2 Terminology ............................................... 4 51 3 General Documentation Guidelines .......................... 5 52 3.1 MIB Boilerplate Section ................................. 5 53 3.2 Narrative Sections ...................................... 5 54 3.3 Definitions Section ..................................... 6 55 3.4 Security Considerations Section ......................... 6 56 3.5 IANA Considerations Section ............................. 7 57 3.5.1 Documents that Create a New Name Space ................ 7 58 3.5.2 Documents that Require Assignments in Existing 59 Namespace(s) ........................................... 8 60 3.5.3 Documents with no IANA Requests ....................... 9 61 3.6 References Sections ..................................... 9 62 3.7 Copyright Notices ....................................... 10 63 3.8 Intellectual Property Section ........................... 11 64 4 SMIv2 Usage Guidelines .................................... 11 65 4.1 Module Names ............................................ 11 66 4.2 Descriptors, TC Names, and Labels ....................... 11 67 4.3 Naming Hierarchy ........................................ 12 68 4.4 IMPORTS Statement ....................................... 12 69 4.5 MODULE-IDENTITY Invocation .............................. 13 70 4.6 Textual Conventions and Object Definitions .............. 15 71 4.6.1 Usage of Data Types ................................... 15 72 4.6.1.1 INTEGER, Integer32, Gauge32, and Unsigned32 ......... 15 73 4.6.1.2 Counter32 and Counter64 ............................. 17 74 4.6.1.3 CounterBasedGauge64 ................................. 18 75 4.6.1.4 OCTET STRING ........................................ 18 76 4.6.1.5 OBJECT IDENTIFIER ................................... 19 77 4.6.1.6 The BITS Construct .................................. 19 78 4.6.1.7 IpAddress ........................................... 20 79 4.6.1.8 TimeTicks ........................................... 20 80 4.6.1.9 TruthValue .......................................... 20 81 4.6.1.10 Other Data Types ................................... 20 82 4.6.2 DESCRIPTION and REFERENCE Clauses ..................... 21 83 4.6.3 DISPLAY-HINT Clause ................................... 21 84 4.6.4 Conceptual Table Definitions .......................... 22 85 4.6.5 OID Values Assigned to Objects ........................ 24 86 4.6.6 OID Length Limitations and Table Indexing ............. 24 87 4.7 Notification Definitions ................................ 25 88 4.8 Compliance Statements ................................... 26 89 4.9 Revisions to MIB Modules ................................ 28 90 5 Acknowledgments ........................................... 32 91 6 Security Considerations ................................... 32 92 7 IANA Considerations ....................................... 32 93 Appendix A: MIB Review Checklist .......................... 32 94 Appendix B: Commonly Used Textual Conventions ............. 34 95 Appendix C: Suggested Naming Conventions .................. 36 96 Appendix D: Suggested OID Layout .......................... 37 97 Normative References ....................................... 38 98 Informative References ..................................... 39 99 Editor's Address ........................................... 41 100 Full Copyright Statement ................................... 41 101 Intellectual Property ...................................... 41 103 1. Introduction 105 Some time ago the IESG instituted a policy of requiring expert review 106 of IETF standards-track specifications containing MIB modules. These 107 reviews were established to ensure that such specifications follow 108 established IETF documentation practices and that the MIB modules 109 they contain meet certain generally accepted standards of quality, 110 including (but not limited to) compliance with all syntactic and 111 semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579] [RFC2580] 112 that are applicable to "standard" MIB modules. The purpose of this 113 memo is to document the guidelines that are followed in such reviews. 115 Please note that the guidelines in this memo are not intended to 116 alter requirements or prohibitions (in the sense of "MUST", "MUST 117 NOT", "SHALL", or "SHALL NOT" as defined in RFC 2119 [RFC2119]) of 118 existing BCPs or Internet Standards except where those requirements 119 or prohibitions are ambiguous or contradictory. In the exceptional 120 cases where ambiguities or contradictions exist this memo documents 121 the current generally accepted interpretation. In certain instances 122 the guidelines in this memo do alter recommendations (in the sense of 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", or "NOT RECOMMENDED" as 124 defined in RFC 2119) of existing BCPs or Internet Standards. This 125 has been done where practical experience has shown that the published 126 recommendations are suboptimal. In addition, this memo provides 127 guidelines for the selection of certain SMIv2 options (in the sense 128 of "MAY" or "OPTIONAL" as defined in RFC 2119) in cases where there 129 is a consensus on a preferred approach. 131 Although some of the guidelines in this memo are not applicable to 132 non-standards track or non-IETF MIB documents, authors and reviewers 133 of those documents should consider using the ones that do apply. 135 Reviewers and authors need to be aware that some of the guidelines in 136 in this memo do not apply to MIB modules that have been translated to 137 SMIv2 from SMIv1 (STD 16) [RFC1155] [RFC1212] [RFC1215]. 139 2. Terminology 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 143 "OPTIONAL", when used in the guidelines in this memo, are to be 144 interpreted as described in RFC 2119 [RFC2119]. 146 The terms "MIB module" and "information module" are used 147 interchangeably in this memo. As used here, both terms refer to any 148 of the three types of information modules defined in Section 3 of RFC 149 2578 [RFC2578]. 151 The term "standard", when it appears in quotes, is used in the same 152 sense as in the SMIv2 documents [RFC2578] [RFC2579] [RFC2580]. In 153 particular, it is used to refer to the requirements that those 154 documents levy on "standard" modules or "standard" objects. 156 3. General Documentation Guidelines 158 In general, IETF standards-track specifications containing MIB 159 modules are subject to the same requirements as IETF standards-track 160 RFCs (see [RFC2223bis]), although there are some differences. In 161 particular, since the version under review will be an Internet-Draft, 162 the notices on the front page MUST comply with the requirements of 163 http://www.ietf.org/ietf/1id-guidelines.txt and not with those of 164 [RFC2223bis]. In addition, since the specification under review is 165 expected to be submitted to the IESG, it MUST comply with certain 166 requirements that do not necessarily apply to RFCs; see 167 http://www.ietf.org/ID-Checklist.html for details. 169 Section 4 of [RFC2223bis] lists the sections that may exist in an 170 RFC. Sections from the abstract onward may also be present in an 171 Internet-Draft; see http://www.ietf.org/ID-Checklist.html. The 172 "body of memo" is always required, and in a MIB document MUST contain 173 at least the following: 175 o MIB boilerplate section 177 o Narrative sections 179 o Definitions section 181 o Security Considerations section 183 o IANA Considerations section 185 o References section. 187 Section-by-section guidelines follow. 189 3.1. MIB Boilerplate Section 191 This section MUST contain a verbatim copy of the latest approved 192 Internet-Standard Management Framework boilerplate, which is 193 available on-line at http://www.ops.ietf.org/mib-boilerplate.html. 195 3.2. Narrative Sections 197 The narrative part MUST include an overview section that describes 198 the scope and field of application of the MIB modules defined by the 199 specification and that specifies the relationship (if any) of these 200 MIB modules to other standards, particularly to standards containing 201 other MIB modules. The narrative part SHOULD include one or more 202 sections to briefly describe the structure of the MIB modules defined 203 in the specification. 205 If the MIB modules defined by the specification import definitions 206 from other MIB modules (except for those defined in the SMIv2 207 documents [RFC2578] [RFC2579] [RFC2580]) or are always implemented in 208 conjunction with other MIB modules, then those facts MUST be noted in 209 the overview section, as MUST any special interpretations of objects 210 in other MIB modules. For instance, so-called media-specific MIB 211 modules are always implemented in conjunction with the IF-MIB 212 [RFC2863] and are REQUIRED to document how certain objects in the 213 IF-MIB are used. In addition, media-specific MIB modules that rely 214 on the ifStackTable [RFC2863] and the ifInvStackTable [RFC2864] to 215 maintain information regarding configuration and multiplexing of 216 interface sublayers MUST contain a description of the layering model. 218 3.3. Definitions Section 220 This section contains the MIB module(s) defined by the specification. 221 These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579] 222 [RFC2580]; SMIv1 [RFC1155] [RFC1212] [RFC1215] has "Not Recommended" 223 status [RFC3410] and is no longer acceptable in IETF MIB modules. 225 See Section 4 for guidelines on SMIv2 usage. 227 3.4. Security Considerations Section 229 Each specification that defines one or more MIB modules MUST contain 230 a section that discusses security considerations relevant to those 231 modules. This section MUST be patterned after the latest approved 232 template (available at http://www.ops.ietf.org/mib-security.html). 233 In particular, writeable MIB objects that could be especially 234 disruptive if abused MUST be explicitly listed by name and the 235 associated security risks MUST be spelled out; similarly, readable 236 MIB objects that contain especially sensitive information or that 237 raise significant privacy concerns MUST be explicitly listed by name 238 and the reasons for the sensitivity/privacy concerns MUST be 239 explained. If there are no risks/vulnerabilities for a specific 240 category of MIB objects, then that fact MUST be explicitly stated. 241 Failure to mention a particular category of MIB objects will not be 242 equated to a claim of no risks/vulnerabilities in that category; 243 rather, it will be treated as an act of omission and will result in 244 the document being returned to the author for correction. Remember 245 that the objective is not to blindly copy text from the template, but 246 rather to think and evaluate the risks/vulnerabilities and then 247 state/document the result of this evaluation. 249 3.5. IANA Considerations Section 251 In order to comply with IESG policy as set forth in 252 http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is 253 submitted to the IESG for publication MUST contain an IANA 254 Considerations section. The requirements for this section vary 255 depending what actions are required of the IANA. 257 3.5.1. Documents that Create a New Name Space 259 If an Internet-Draft defines a new name space that is to be 260 administered by the IANA, then the document MUST include an IANA 261 Considerations section conforming to the guidelines set forth in RFC 262 2434 [RFC2434] that specifies how the name space is to be 263 administered. 265 Name spaces defined by MIB documents generally consist of the range 266 of values for some type (usually an enumerated INTEGER) defined by a 267 TEXTUAL-CONVENTION (TC) or of a set of administratively-defined 268 OBJECT IDENTIFIER (OID) values. In each case the definitions are 269 housed in stand-alone MIB modules that are maintained by the IANA. 270 These IANA-maintained MIB modules are separate from the MIB modules 271 defined in standards-track specifications so that new assignments can 272 be made without having to republish a standards-track RFC. Examples 273 of IANA-maintained MIB modules include the IANAifType-MIB 274 (http://www.iana.org/assignments/ianaiftype-mib), which defines a 275 name space used by the IF-MIB [RFC2863], and the IANA-RTPROTO-MIB 276 (http://www.iana.org/assignments/ianaiprouteprotocol-mib), which 277 defines a name space used by the IPMROUTE-STD-MIB [RFC2932]. 279 The current practice for such cases is to include a detailed IANA 280 Considerations section complying with RFC 2434 in the DESCRIPTION 281 clause of the MODULE-IDENTITY invocation in each IANA-maintained MIB 282 module and for the IANA Considerations section of the MIB document 283 that defines the name spaces to refer to the URLs for the relevant 284 modules. See RFC 2932 [RFC2932] for an example. This creates a 285 chicken-and-egg problem for MIB documents that have not yet been 286 published as RFCs because the relevant IANA-maintained MIB modules 287 will not yet exist. The accepted way out of this dilemma is to 288 include the initial content of each IANA-maintained MIB module in a 289 non-normative section of the initial issue of the document that 290 defines the name space; for an example see [RFC1573], which 291 documents the initial version of the IANAifType-MIB. That material 292 is usually omitted from subsequent updates to the document since the 293 IANA-maintained modules are then available on-line (cf. [RFC2863]). 295 Reviewers of draft MIB documents to which these considerations apply 296 MUST check that the IANA Considerations section proposed for 297 publication in the RFC is present and contains pointers to the 298 appropriate IANA-maintained MIB modules. Reviewers of Internet 299 Drafts that contain the proposed initial content of IANA-maintained 300 MIB modules MUST also verify that the DESCRIPTION clauses of the 301 MODULE-IDENTITY invocations contain an IANA Considerations section 302 compliant with the guidelines in RFC 2434. 304 3.5.2. Documents that Require Assignments in Existing Namespace(s) 306 If an Internet-Draft requires the IANA to update an existing registry 307 prior to publication as an RFC, then the IANA Considerations section 308 in the draft MUST document that fact. MIB documents that contain the 309 initial version of a MIB module will generally require that the IANA 310 assign an OBJECT IDENTIFIER value for the MIB module's 311 MODULE-IDENTITY value and possibly to make other assignments as well. 312 Internet-Drafts containing such MIB modules MUST contain an IANA 313 Considerations section that specifies the registries that are to be 314 updated, the descriptors to which OBJECT IDENTIFIER values are being 315 assigned, and the subtrees under which the values are to be 316 allocated. The text SHOULD be crafted so that after publication it 317 will serve to document the OBJECT IDENTIFIER assignments. For 318 example, something along the following lines would be appropriate for 319 an Internet-Draft containing a single MIB module with MODULE-IDENTITY 320 descriptor powerEthernetMIB that is to be assigned a value under the 321 'mib-2' subtree: 323 The MIB module in this document uses the following IANA-assigned 324 OBJECT IDENTIFIER values recorded in the SMI Numbers registry: 326 Descriptor OBJECT IDENTIFIER value 327 ---------- ----------------------- 329 powerEthernetMIB { mib-2 XXX } 331 Editor's Note (to be removed prior to publication): the IANA is 332 requested to assign a value for "XXX" under the 'mib-2' 333 subtree and to record the assignment in the SMI Numbers registry. 334 When the assignment has been made, the RFC Editor is asked to 335 replace "XXX" (here and in the MIB module) with the assigned 336 value and to remove this note. 338 Note well: prior to official assignment by the IANA, a draft 339 document MUST use placeholders (such as "XXX" above) rather than 340 actual numbers. See Section 4.5 for an example of how this is done 341 in a draft MIB module. 343 3.5.3. Documents with no IANA Requests 345 If an Internet-Draft makes no requests of the IANA, then that fact 346 MUST be documented in the IANA Considerations section. When an 347 Internet-Draft contains an update of a previously published MIB 348 module, it typically will not require any action on the part of the 349 IANA, but it may inherit an IANA Considerations section documenting 350 existing assignments from the RFC that contains the previous version 351 of the MIB module. In such cases the draft MUST contain a note (to 352 be removed prior to publication) explicitly indicating that nothing 353 is required from the IANA. For example, a draft that contains an 354 updated version of the POWER-ETHERNET-MIB [RFC3621] might include an 355 IANA Considerations section like the following: 357 The MIB module in this document uses the following IANA-assigned 358 OBJECT IDENTIFIER values recorded in the SMI Numbers registry: 360 Descriptor OBJECT IDENTIFIER value 361 ---------- ----------------------- 363 powerEthernetMIB { mib-2 105 } 365 Editor's Note (to be removed prior to publication): this draft 366 makes no additional requests of the IANA. 368 If an Internet-Draft makes no requests of the IANA and there are no 369 existing assignments to be documented, then suitable text for the 370 draft would be something along the following lines: 372 No IANA actions are required by this document. 374 3.6. References Sections 376 Section 4.7f of [RFC2223bis] specifies the requirements for the 377 references sections in an RFC; http://www.ietf.org/ID-Checklist.html 378 imposes the same requirements on Internet-Drafts. In particular, 379 there MUST be separate lists of normative and informative references, 380 each in a separate section. The style SHOULD follow that of recently 381 published RFCs. 383 The standard MIB boilerplate available at 384 http://www.ops.ietf.org/mib-boilerplate.html includes lists of 385 normative and informative references that MUST appear in all IETF 386 specifications that contain MIB modules. If items from other MIB 387 modules appear in an IMPORTS statement in the Definitions section, 388 then the specifications containing those MIB modules MUST be included 389 in the list of normative references. When items are imported from an 390 IANA-maintained MIB module the corresponding normative reference 391 SHALL point to the on-line version of that MIB module. It is the 392 policy of the RFC Editor that all references must be cited in the 393 text; such citations MUST appear in the overview section where 394 documents containing imported definitions (other those already 395 mentioned in the MIB boilerplate) are required to be mentioned (cf. 396 Section 3.2). 398 In general, each normative reference SHOULD point to the most recent 399 version of the specification in question. 401 3.7. Copyright Notices 403 IETF MIB documents MUST contain the copyright notices and disclaimer 404 specified in Sections 5.4 and 5.5 of RFC 3907 [RFC3907]. Authors and 405 reviewers MUST check to make sure that the correct year is inserted 406 into these notices. In addition, the DESCRIPTION clause of the 407 MODULE-IDENTITY invocation of each MIB module that will appear in the 408 published RFC MUST contain a pointer to the copyright notices in the 409 RFC. A template suitable for inclusion in an Internet-Draft, 410 appropriate for MIB modules other than those that are to be 411 maintained by the IANA, is as follows: 413 DESCRIPTION 414 " [ ... ] 416 Copyright (C) The Internet Society (date). This version 417 of this MIB module is part of RFC yyyy; see the RFC 418 itself for full legal notices." 419 -- RFC Ed.: replace yyyy with actual RFC number & remove this note 421 A template suitable for MIB modules that are to be maintained by the 422 IANA is as follows: 424 DESCRIPTION 425 " [ ... ] 427 Copyright (C) The Internet Society (date). The initial 428 version of this MIB module was published in RFC yyyy; 429 for full legal notices see the RFC itself. Supplementary 430 information may be available at: 431 http://www.ietf.org/copyrights/ianamib.html." 432 -- RFC Ed.: replace yyyy with actual RFC number & remove this note 434 In each case the current year is to be inserted in place of the word 435 "date". 437 3.8. Intellectual Property Section 439 Section 5 of RFC 3908 [RFC3908] contains a notice regarding 440 intellectual property rights or other rights that must appear in all 441 IETF RFCs. A verbatim copy of that notice SHOULD appear in every 442 IETF MIB document. 444 4. SMIv2 Usage Guidelines 446 In general, MIB modules in IETF standards-track specifications MUST 447 comply with all syntactic and semantic requirements of SMIv2 448 [RFC2578] [RFC2579] [RFC2580] that apply to "standard" MIB modules 449 and except as noted below SHOULD comply with SMIv2 recommendations. 450 The guidelines in this section are intended to supplement the SMIv2 451 documents in the following ways: 453 o to document the current generally accepted interpretation when 454 those documents contain ambiguities or contradictions; 456 o to update recommendations in those documents that have been shown 457 by practical experience to be out-of-date or otherwise suboptimal; 459 o to provide guidance in selection of SMIv2 options in cases where 460 there is a consensus on a preferred approach. 462 4.1. Module Names 464 RFC 2578 Section 3 specifies the rules for module names. Note in 465 particular that names of "standard" modules MUST be unique, MUST 466 follow the syntax rules in RFC 2578 Section 3, and MUST NOT be 467 changed when a MIB module is revised (see also RFC 2578 Section 10). 469 It is RECOMMENDED that module names be mnemonic. See Appendix C for 470 suggested naming conventions. 472 4.2. Descriptors, TC Names, and Labels 474 RFC 2578 Sections 3.1, 7.1.1, and 7.1.4 and RFC 2579 Section 3 475 recommend that descriptors and names associated with macro 476 invocations and labels associated with enumerated INTEGER and BITS 477 values be no longer than 32 characters, but require that they be no 478 longer than 64 characters. 480 Restricting descriptors, TC names, and labels to 32 characters often 481 conflicts with the recommendation that they be mnemonic and (for 482 descriptors and TC names) with the requirement that they be unique 483 (see RFC 2578 Section 3.1 and RFC 2579 Section 3). The consensus of 484 the current pool of MIB reviewers is that the SMIv2 recommendation to 485 limit descriptors, TC names, and labels to 32 characters SHOULD be 486 set aside in favor of promoting clarity and uniqueness and that 487 automated tools such as MIB compilers SHOULD NOT by default generate 488 warnings for violating that recommendation. 490 Note that violations of the 64 character limit MUST NOT be ignored; 491 they MUST be treated as errors. 493 See Appendix C for suggested descriptor and TC naming conventions. 495 4.3. Naming Hierarchy 497 RFC 2578 Section 4 describes the object identifier subtrees that are 498 maintained by IANA and specifies the usages for those subtrees. In 499 particular, the mgmt subtree { iso 3 6 1 2 } is used to identify IETF 500 "standard" objects, while the experimental subtree { iso 3 6 1 3 } is 501 used to identify objects that are under development in the IETF. It 502 is REQUIRED that objects be moved from the experimental subtree to 503 the mgmt subtree when a MIB module enters the IETF standards track. 505 Experience has shown that it is impractical to move objects from one 506 subtree to another once those objects have seen large-scale use in an 507 operational environment. Hence any object that is targeted for 508 deployment in an operational environment MUST NOT be registered under 509 the experimental subtree, irrespective of the standardization status 510 of that object. The experimental subtree should be used only for 511 objects that are intended for limited experimental deployment. Such 512 objects typically are defined in Experimental RFCs. 514 Note: the term "object", as used here and in RFC 2578 Section 4, is 515 to be broadly interpreted as any construct that results in an OBJECT 516 IDENTIFIER registration. The list of such constructs is specified in 517 RFC 2578 Section 3.6. 519 4.4. IMPORTS Statement 521 RFC 2578 Section 3.2 specifies which symbols must be imported and 522 also lists certain pre-defined symbols that must not be imported. 524 The general requirement is that if an external symbol other than a 525 predefined ASN.1 type or the BITS construct is used, then it MUST be 526 mentioned in the module's IMPORTS statement. The words "external 527 object" in the first paragraph of that section may give the 528 impression that such symbols are limited to those that refer to 529 object definitions, but that is not the case, as subsequent 530 paragraphs should make clear. 532 Note that exemptions to this general requirement are granted by RFC 533 2580 Sections 5.4.3 and 6.5.2 for descriptors of objects appearing in 534 the OBJECT clause of a MODULE-COMPLIANCE statement or in the 535 VARIATION clause of an AGENT-CAPABILITIES statement. Some MIB 536 compilers also grant exemptions to descriptors of notifications 537 appearing in a VARIATION clause and to descriptors of object groups 538 and notification groups referenced by a MANDATORY-GROUPS clause, a 539 GROUP clause, or an INCLUDES clause, although RFC 2580 (through 540 apparent oversight) does not mention those cases. The exemptions are 541 sometimes seen as unhelpful because they make IMPORTS rules more 542 complicated and inter-module dependencies less obvious than they 543 otherwise would be. External symbols referenced by compliance 544 statements and capabilities statements MAY therefore be listed in the 545 IMPORTS statement; if this is done, it SHOULD be done consistently. 547 Finally, even though it is not forbidden by the SMI, it is considered 548 poor style to import symbols that are not used, and standards-track 549 MIB modules SHOULD NOT do so. 551 4.5. MODULE-IDENTITY Invocation 553 RFC 2578 Section 3 requires that all SMIv2 MIB modules start with 554 exactly one invocation of the MODULE-IDENTITY macro. This invocation 555 MUST appear immediately after the IMPORTS statement. 557 RFC 2578 Section 5 describes how the various clauses are used. The 558 following additional guidelines apply to all MIB modules over which 559 the IETF has change control: 561 - If the module was developed by an IETF working group, then the 562 ORGANIZATION clause MUST provide the full name of the working 563 group, and the CONTACT-INFO clause MUST include working group 564 mailing list information. The CONTACT-INFO clause SHOULD also 565 provide a pointer to the working group's web page. 567 - A REVISION clause MUST be present for each revision of the MIB 568 module, and the UTC time of the most recent REVISION clause MUST 569 match that of the LAST-UPDATED clause. The DESCRIPTION clause 570 associated with each revision MUST state in which RFC that revision 571 appeared and SHOULD provide a list of all significant changes. 572 When a MIB module is revised UTC times in all REVISION clauses 573 SHOULD be updated to use four-digit year notation. 575 - The value assigned to the MODULE-IDENTITY descriptor MUST be unique 576 and (for IETF standards-track MIB modules) SHOULD reside under the 577 mgmt subtree [RFC2578]. Most often it will be an IANA-assigned 578 value directly under mib-2 [RFC2578], although for media-specific 579 MIB modules that extend the IF-MIB [RFC2863] it is customary to use 580 an IANA-assigned value under transmission [RFC2578]. In the past 581 some IETF working groups have made their own assignments from 582 subtrees delegated to them by IANA, but that practice has proven 583 problematic and is NOT RECOMMENDED. 585 While a MIB module is under development, the RFC number in which it 586 will eventually be published is usually unknown and must be filled in 587 by the RFC Editor prior to publication. An appropriate form for the 588 REVISION clause applying to a version under development would be 589 something along the following lines: 591 REVISION "200212132358Z" -- December 13, 2002 592 DESCRIPTION "Initial version, published as RFC yyyy." 593 -- RFC Ed.: replace yyyy with actual RFC number & remove this note 595 Note that after RFC publication a REVISION clause is present only for 596 published versions of a MIB module and not for interim versions that 597 existed only as Internet-Drafts. Thus, a draft version of a MIB 598 module MUST contain just one new REVISION clause that covers all 599 changes since the last published version (if any). 601 When the initial version of a MIB module is under development, the 602 value assigned to the MODULE-IDENTITY descriptor will be unknown if 603 an IANA-assigned value is used, because the assignment is made just 604 prior to publication as an RFC. The accepted form for the 605 MODULE-IDENTITY statement in draft versions of such a module is 606 something along the following lines: 608 MODULE-IDENTITY 610 [ ... ] 612 ::= { XXX } 613 -- RFC Ed.: replace XXX with IANA-assigned number & remove this note 615 where is whatever descriptor has been selected for the 616 module and is the subtree under which the module is to be 617 registered (e.g., mib-2 or transmission). Note that XXX must be 618 temporarily replaced by a number in order for the module to compile. 620 Note well: prior to official assignment by the IANA, a draft 621 document MUST use a placeholder (such as "XXX" above) rather than an 622 actual number. If trial implementations are desired during the 623 development process, then an assignment under the 'experimental' 624 subtree may be obtained from the IANA (cf. Section 4.3). 626 4.6. Textual Conventions and Object Definitions 628 4.6.1. Usage of Data Types 630 4.6.1.1. INTEGER, Integer32, Gauge32, and Unsigned32 632 The 32-bit integer data types INTEGER, Integer32, Gauge32, and 633 Unsigned32 are described in RFC 2578 Section 2 and further elaborated 634 in RFC 2578 Sections 7.1.1, 7.1.7, and 7.1.11. The following 635 guidelines apply when selecting one of these data types for an object 636 definition or a textual convention: 638 - For integer-valued enumerations: 640 - INTEGER is REQUIRED; 641 - Integer32, Unsigned32, and Gauge32 MUST NOT be used. 643 Note that RFC 2578 recommends (but does not require) that 644 integer-valued enumerations start at 1 and be numbered contiguously. 645 This recommendation SHOULD be followed unless there is a valid reason 646 to do otherwise, e.g., to match values of external data or to 647 indicate special cases, and any such special-case usage SHOULD be 648 clearly documented. For an example see the InetAddressType TC 649 [RFC3291bis]. 651 Although the SMI allows DEFVAL clauses for integer-valued 652 enumerations to specify the default value either by label or by 653 numeric value, the label form is preferred since all the examples in 654 RFC 2578 are of that form and some tools do not accept the numeric 655 form. 657 - If the value range is between -2147483648..2147483647 (inclusive) 658 and negative values are possible, then: 660 - Integer32 is RECOMMENDED; 661 - INTEGER is acceptable; 662 - Unsigned32 and Gauge32 MUST NOT be used. 664 - If the value range is between 0..4294967295 (inclusive) and the 665 value of the information being modelled may increase above the 666 maximum value or decrease below the minimum value, then: 668 - Gauge32 is RECOMMENDED; 669 - Unsigned32 is acceptable; 670 - INTEGER and Integer32 MUST NOT be used if 671 values greater than 2147483647 are possible. 673 - If the value range is between 0..4294967295 (inclusive), and values 674 greater than 2147483647 are possible, and the value of the 675 information being modelled does not increase above the maximum 676 value nor decrease below the minimum value, then: 678 - Unsigned32 is RECOMMENDED; 679 - Gauge32 is acceptable; 680 - INTEGER and Integer32 MUST NOT be used. 682 - If the value range is between 0..2147483647 (inclusive), and the 683 value of the information being modelled does not increase above the 684 maximum value nor decrease below the minimum value, then: 686 - Unsigned32 is RECOMMENDED; 687 - INTEGER, Integer32, and Gauge32 are acceptable. 689 - For integer-valued objects that appear in an INDEX clause or for 690 integer-valued TCs that are to be used in an index column: 692 - Unsigned32 with a range that excludes zero is RECOMMENDED for 693 most index objects. It is acceptable to include zero in the 694 range when it is semantically significant or when it is used as 695 the index value for a unique row with special properties. Such 696 usage SHOULD be clearly documented in the DESCRIPTION clause. 698 - Integer32 or INTEGER with a non-negative range is acceptable. 699 Again, zero SHOULD be excluded from the range except when it is 700 semantically significant or when it is used as the index value 701 for a unique row with special properties, and in such cases the 702 usage SHOULD be clearly documented in the DESCRIPTION clause. 704 - Use of Gauge32 is acceptable for index objects that have gauge 705 semantics. 707 The guidelines above combine both the usage rules for integer data 708 types and the INDEX rules in RFC 2578 Section 7.7 up to and including 709 bullet (1) plus the next-to-last paragraph on page 28. 711 Sometimes it will be necessary for external variables to represent 712 values of an index object -- e.g., ifIndex [RFC2863]. In such cases 713 authors of the module containing that object SHOULD consider defining 714 TCs such as InterfaceIndex and/or InterfaceIndexOrZero [RFC2863]. 716 Note that INTEGER is a pre-defined ASN.1 type and MUST NOT be present 717 in a module's IMPORTS statement, whereas Integer32, Gauge32, and 718 Unsigned32 are defined by SNMPv2-SMI and MUST be imported from that 719 module if used. 721 4.6.1.2. Counter32 and Counter64 723 Counter32 and Counter64 have special semantics as described in RFC 724 2578 Sections 7.1.6 and 7.1.10 respectively. Object definitions MUST 725 (and textual conventions SHOULD) respect these semantics. That 726 means: 728 - It is OK to use Counter32/64 for counters that may/will be reset 729 when the management subsystem is re-initialized or when other 730 unusual/irregular events occur (e.g., counters maintained on a line 731 card may be reset when the line card is reset). However, if it is 732 possible for such other unusual/irregular events to occur, the 733 DESCRIPTION clause MUST state that this is so and MUST describe 734 those other unusual/irregular events in sufficient detail that it 735 is possible for a management application to determine whether a 736 reset has occurred since the last time the counter was polled. The 737 RECOMMENDED way to do this is to provide a discontinuity indicator 738 as described in RFC 2578 Sections 7.1.6 and 7.1.10. For an example 739 of such a discontinuity indicator see the 740 ifCounterDiscontinuityTime object in the IF-MIB [RFC2863]. 742 - It is NOT OK to put in the DESCRIPTION clause of a Counter32/64 743 that there is a requirement that on a discontinuity the counter 744 MUST reset to zero or to any other specific value. 746 - It is NOT OK to put in the DESCRIPTION clause of a Counter32/64 747 that there is a requirement that it MUST reset at any specific 748 time/event (e.g., midnight). 750 - It is NOT OK for one manager to request the agent to reset the 751 value(s) of counter(s) to zero, and Counter32/64 is the wrong 752 syntax for "counters" which regularly reset themselves to zero. 753 For the latter it is better to define or use textual conventions 754 such as those in RFC 3593 [RFC3593] or RFC 3705 [RFC3705]. 756 RFC 2578 Section 7.1.10 places a requirement on "standard" MIB 757 modules that the Counter64 type may be used only if the information 758 being modelled would wrap in less than one hour if the Counter32 type 759 was used instead. Now that SNMPv3 is an Internet Standard and SNMPv1 760 is Historic (see http://www.rfc-editor.org/rfcxx00.html for status 761 and [RFC3410] for rationale) there is no reason to continue enforcing 762 this restriction. Henceforth "standard" MIB modules MAY use the 763 Counter64 type when it makes sense to do so, and MUST use Counter64 764 if the information being modelled would wrap in less than one hour if 765 the Counter32 type was used instead. Note also that there is no 766 longer a requirement to define Counter32 counterparts for each 767 Counter64 object, although one is still allowed to do so. 769 There also exist closely-related textual conventions 770 ZeroBasedCounter32 and ZeroBasedCounter64 defined in RMON2-MIB 771 [RFC2021] and HCNUM-TC [RFC2856], respectively. 773 The only difference between ZeroBasedCounter32/64 TCs and 774 Counter32/64 is their starting value; at time=X, where X is their 775 minimum-wrap-time after they were created, the behavior of 776 ZeroBasedCounter32/64 becomes exactly the same as Counter32/64. 777 Thus, the preceding paragraphs/rules apply not only to Counter32/64, 778 but also to ZeroBasedCounter32/64 TCs. 780 4.6.1.3. CounterBasedGauge64 782 SMIv2 unfortunately does not provide 64-bit integer base types. In 783 order to make up for this omission, the CounterBasedGauge64 textual 784 convention is defined in HCNUM-TC [RFC2856]. This TC uses Counter64 785 as a base type, but discards the special counter semantics, which is 786 allowed under the generally accepted interpretation of RFC 2579 787 Section 3.3. It does inherit all the syntactic restrictions of that 788 type, which means that it MUST NOT be subtyped and that objects 789 defined with it MUST NOT appear in an INDEX clause, MUST NOT have a 790 DEFVAL clause, and MUST have a MAX-ACCESS of read-only or 791 accessible-for-notify. 793 This TC SHOULD be used for object definitions that require a 64-bit 794 unsigned data type with gauge semantics. If a 64-bit unsigned data 795 type with different semantics is needed, then a different TC based on 796 Counter64 MUST be used, since one TC cannot refine another (cf. RFC 797 2579 Section 3.5). 799 4.6.1.4. OCTET STRING 801 The OCTET STRING type is described in RFC 2578 Section 7.1.2. It 802 represents arbitrary binary or textual data whose length is between 0 803 and 65535 octets inclusive. Objects and TCs whose SYNTAX is of this 804 type SHOULD have a size constraint when the actual bounds are more 805 restrictive than the SMI-imposed limits. This is particularly true 806 for index objects. Note, however, that size constraints SHOULD NOT 807 be imposed arbitrarily, as the SMI does not permit them to be changed 808 afterward. 810 There exist a number of standard TCs that cater to some of the more 811 common requirements for specialized OCTET STRING types. In 812 particular, SNMPv2-TC [RFC2579] contains the DisplayString, 813 PhysAddress, MacAddress, and DateAndTime TCs, the SNMP-FRAMEWORK-MIB 814 [RFC3411] contains the SnmpAdminString TC, and the SYSAPPL-MIB 815 [RFC2287] contains the Utf8String and LongUtf8String TCs. When a 816 standard TC provides the desired semantics, it SHOULD be used in an 817 object's SYNTAX clause instead of OCTET STRING or an equivalent 818 locally-defined TC. 820 Note that OCTET STRING is a pre-defined ASN.1 type and MUST NOT be 821 present in a module's IMPORTS statement. 823 4.6.1.5. OBJECT IDENTIFIER 825 The OBJECT IDENTIFIER type is described in RFC 2578 Section 7.1.3. 826 Its instances represent administratively assigned names. Note that 827 both the SMI and the SNMP protocol limit instances of this type to 828 128 sub-identifiers and require that each sub-identifier be within 829 the range 0 to 4294967295 inclusive. Sub-typing is not allowed. 831 The purpose of OBJECT IDENTIFIER values is to provide authoritative 832 identification either for some type of item or for a specific 833 instance of some type of item. Among the items that can be 834 identified in this way are definitions in MIB modules created via the 835 MODULE-IDENTITY, OBJECT-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE, 836 OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE, and 837 AGENT-CAPABILITIES constructs, instances of objects defined in MIB 838 modules, protocols, languages, specifications, interface types, 839 hardware, and software. For some of these uses other possibilities 840 exist, e.g., OCTET STRING or enumerated INTEGER values. The OBJECT 841 IDENTIFIER type SHOULD be used instead of the alternatives when the 842 set of identification values needs to be independently extensible 843 without the need for a registry to provide centralized coordination. 845 There exist a number of standard TCs that cater to some of the more 846 common requirements for specialized OBJECT IDENTIFIER types. In 847 particular, SNMPv2-TC [RFC2579] contains the AutonomousType, 848 VariablePointer, and RowPointer TCs. When a standard TC provides the 849 desired semantics, it SHOULD be used in an object's SYNTAX clause 850 instead of OBJECT IDENTIFIER or an equivalent locally-defined TC. 852 Note that OBJECT IDENTIFIER is a pre-defined ASN.1 type and MUST NOT 853 be present in a module's IMPORTS statement. 855 4.6.1.6. The BITS Construct 857 The BITS construct is described in RFC 2578 Section 7.1.4. It 858 represents an enumeration of named bits. The bit positions in a TC 859 or object definition whose SYNTAX is of this type MUST start at 0 and 860 SHOULD be contiguous. 862 Note that the BITS construct is defined by the macros that use it and 863 therefore MUST NOT be present in a module's IMPORTS statement. 865 4.6.1.7. IpAddress 867 The IpAddress type described in RFC 2578 Section 7.1.5 SHOULD NOT be 868 used in new MIB modules. The InetAddress/InetAddressType textual 869 conventions [RFC3291bis] SHOULD be used instead. 871 4.6.1.8. TimeTicks 873 The TimeTicks type is described in RFC 2578 Section 7.1.8. It 874 represents the time in hundredths of a second between two epochs, 875 reduced modulo 2^32. It MUST NOT be sub-typed, and the DESCRIPTION 876 clause of any object or TC whose SYNTAX is of this type MUST identify 877 the reference epochs. 879 The TimeTicks type SHOULD NOT be used directly in definitions of 880 objects that are snapshots of sysUpTime [RFC3418]. The TimeStamp TC 881 [RFC2579] already conveys the desired semantics and SHOULD be used 882 instead. 884 4.6.1.9. TruthValue 886 The TruthValue TC is defined in SNMPv2-TC [RFC2579]. It is an 887 enumerated INTEGER type that assumes the values true(1) and false(2). 889 This TC SHOULD be used in the SYNTAX clause of object definitions 890 that require a Boolean type. MIB modules SHOULD NOT use enumerated 891 INTEGER types or define TCs that duplicate its semantics. 893 4.6.1.10. Other Data Types 895 There exist a number of standard TCs that cater to some of the more 896 common requirements for specialized data types. Some have been 897 mentioned above, and Appendix B contains a partial list that includes 898 those plus some others that are a bit more specialized. An on-line 899 version of that list, which is updated as new TCs are developed, can 900 be found at http://www.ops.ietf.org/mib-common-tcs.html. 902 Whenever a standard TC already conveys the desired semantics, it 903 SHOULD be used in an object definition instead of the corresponding 904 base type or a locally-defined TC. This is especially true of the 905 TCs defined in SNMPv2-TC [RFC2579] and SNMP-FRAMEWORK-MIB [RFC3411] 906 because they are Internet Standards, and so modules that refer to 907 them will not suffer delay in advancement on the standards track on 908 account of such references. 910 MIB module authors need to be aware that enumerated INTEGER or BITS 911 TCs may in some cases be extended with additional enumerated values 912 or additional bit positions. When an imported TC that may be 913 extended in this way is used to define an object that may be written 914 or that serves as an index in a read-create table, then the set of 915 values or bit positions that needs to be supported SHOULD be 916 specified either in the object's DESCRIPTION clause or in an OBJECT 917 clause in the MIB module's compliance statement(s). This may be done 918 by explicitly listing the required values or bit positions, or it may 919 be done by stating that an implementation may support a subset of 920 values or bit positions of its choosing. 922 4.6.2. DESCRIPTION and REFERENCE Clauses 924 It is hard to overemphasize the importance of an accurate and 925 unambiguous DESCRIPTION clause for all objects and TCs. The 926 DESCRIPTION clause contains the instructions that implementors will 927 use to implement an object, and if they are inadequate or ambiguous, 928 then implementation quality will suffer. Probably the single most 929 important job of a MIB reviewer is to ensure that DESCRIPTION clauses 930 are sufficiently clear and unambiguous to allow interoperable 931 implementations to be created. 933 A very common problem is to see an object definition for, say, 934 'stdMIBPoofpoofCounter' with a DESCRIPTION clause that just says 935 "Number of poofpoofs" with no indication what a 'poofpoof' is. In 936 such cases it is strongly RECOMMENDED that there either be at least a 937 minimal explanation or else a REFERENCE clause to point to the 938 definition of a 'poofpoof'. 940 For read-write objects (other than columns in read-create tables that 941 have well-defined persistence properties) it is RECOMMENDED that the 942 DESCRIPTION clause specify what happens to the value after an agent 943 reboot. Among the possibilities are that the value remains 944 unchanged, that it reverts to a well-defined default value, or that 945 the result is implementation-dependent. 947 4.6.3. DISPLAY-HINT Clause 949 The DISPLAY-HINT clause is used in a TC to provide a non-binding hint 950 to a management application as to how the value of an instance of an 951 object defined with the syntax in the TC might be displayed. Its 952 presence is optional. 954 Although management applications typically default to decimal format 955 ("d") for integer TCs which are not enumerations and to a hexadecimal 956 format ("1x:" or "1x " or "1x_") for octet string TCs when the 957 DISPLAY-HINT clause is absent, it should be noted that SMIv2 does not 958 actually specify any defaults. MIB authors should be aware that a 959 clear hint is provided to applications only when the DISPLAY-HINT 960 clause is present. 962 4.6.4. Conceptual Table Definitions 964 RFC 2578 Sections 7.1.12 and 7.1.12.1 specify the rules for defining 965 conceptual tables, and RFC 2578 Sections 7.7, 7.8, and 7.8.1 specify 966 conceptual table indexing rules. The following guidelines apply to 967 such definitions: 969 - For conceptual rows: 971 - If the row is an extension of a row in some other table, then an 972 AUGMENTS clause MUST be used if the relationship is one-to-one, 973 and an INDEX clause MUST be used if the relationship is sparse. 974 In the latter case the INDEX clause SHOULD be identical to that 975 of the original table. 977 - If the row is an element of an expansion table -- that is, if 978 multiple row instances correspond to a single row instance in 979 some other table -- then an INDEX clause MUST be used, and the 980 first-mentioned elements SHOULD be the indices of that other 981 table, listed in the same order. 983 - If objects external to the row are present in the INDEX clause, 984 then the conceptual row's DESCRIPTION clause MUST specify how 985 those objects are used in identifying instances of its columnar 986 objects, and in particular MUST specify for which values of those 987 index objects the conceptual row may exist. 989 - Use of the IMPLIED keyword is NOT RECOMMENDED for any index 990 object that may appear in the INDEX clause of an expansion table. 991 Since this keyword may be associated only with the last object in 992 an INDEX clause, it cannot be associated with the same index 993 object in a primary table and an expansion table. This will 994 cause the sort order to be different in the primary table and any 995 expansion tables. As a consequence, an implementation will be 996 unable to reuse indexing code from the primary table in expansion 997 tables, and data structures meant to be extended might actually 998 have to be replicated. Designers who are tempted to use IMPLIED 999 should consider that the resulting sort order rarely meets user 1000 expectations, particularly for strings that include both upper 1001 and lower-case letters, and it does not take the user language or 1002 locale into account. 1004 - If dynamic row creation and/or deletion by management applications 1005 is supported, then: 1007 - There SHOULD be one columnar object with a SYNTAX value of 1008 RowStatus [RFC2579] and a MAX-ACCESS value of read-create. This 1009 object is called the status column for the conceptual row. All 1010 other columnar objects MUST have a MAX-ACCESS value of 1011 read-create, read-only, accessible-for-notify, or not-accessible; 1012 a MAX-ACCESS value of read-write is not allowed. 1014 - There either MUST be one columnar object with a SYNTAX value of 1015 StorageType [RFC2579] and a MAX-ACCESS value of read-create, or 1016 else the row object (table entry) DESCRIPTION clause MUST specify 1017 what happens to dynamically-created rows after an agent restart. 1019 - If the agent itself may also create and/or delete rows, then the 1020 conditions under which this can occur MUST be clearly documented 1021 in the row object DESCRIPTION clause. 1023 - For conceptual rows that include a status column: 1025 - The DESCRIPTION clause of the status column MUST specify which 1026 columnar objects (if any) have to be set to valid values before 1027 the row can be activated. If any objects in cascading tables 1028 have to be populated with related data before the row can be 1029 activated, then this MUST also be specified. 1031 - The DESCRIPTION clause of the status column MUST specify whether 1032 or not it is possible to modify other columns in the same 1033 conceptual row when the status value is active(1). Note that in 1034 many cases it will be possible to modify some writeable columns 1035 when the row is active but not others. In such cases the 1036 DESCRIPTION clause for each writeable column SHOULD state whether 1037 or not that column can be modified when the row is active, and 1038 the DESCRIPTION clause for the status column SHOULD state that 1039 modifiability of other columns when the status value is active(1) 1040 is specified in the DESCRIPTION clauses for those columns (rather 1041 than listing the modifiable columns individually). 1043 - For conceptual rows that include a StorageType column: 1045 - The DESCRIPTION clause of the StorageType column MUST specify 1046 which read-write or read-create columnar objects in permanent(4) 1047 rows an agent must, at a minimum, allow to be writable. 1049 Note that RFC 2578 Section 7.8 requires that the lifetime of an 1050 instance of a conceptual row that AUGMENTS a base row must be the 1051 same as the corresponding instance of the base row. It follows that 1052 there is no need for a RowStatus or StorageType column in an 1053 augmenting row if one is already present in the base row. 1055 Complete requirements for the RowStatus and StorageType TCs can be 1056 found in RFC 2579, in the DESCRIPTION clauses for those TCs. 1058 4.6.5. OID Values Assigned to Objects 1060 RFC 2578 Section 7.10 specifies the rules for assigning OBJECT 1061 IDENFIFIER (OID) values to OBJECT-TYPE definitions. In particular: 1063 - A conceptual table MUST have exactly one subordinate object, which 1064 is a conceptual row. The OID assigned to the conceptual row MUST 1065 be derived by appending a sub-identifier of "1" to the OID assigned 1066 to the conceptual table. 1068 - A conceptual row has as many subordinate objects as there are 1069 columns in the row; there MUST be at least one. The OID assigned 1070 to each columnar object MUST be derived by appending a non-zero 1071 sub-identifier, unique within the row, to the OID assigned to the 1072 conceptual row. 1074 - A columnar or scalar object MUST NOT have any subordinate objects. 1076 - The last sub-identifier of an OID assigned to any object (be it 1077 table, row, column, or scalar) MUST NOT be equal to zero. Note 1078 that sub-identifiers of intermediate nodes MAY be equal to zero. 1080 - The OID assigned to an object definition MUST NOT also be assigned 1081 to another definition that results in OID registration. RFC 2578 1082 Section 3.6 lists the constructs that create OID registrations. 1084 Although it is not specifically required by the SMI, it is customary 1085 (and strongly RECOMMENDED) that object definitions not be registered 1086 beneath group definitions, compliance statements, capabilities 1087 statements, or notification definitions. It is also customary (and 1088 strongly RECOMMENDED) that group definitions, compliance statements, 1089 capabilities statements, and notification definitions not be 1090 registered beneath object definitions. See Appendix D for a 1091 RECOMMENDED OID assignment scheme. 1093 4.6.6. OID Length Limitations and Table Indexing 1095 As specified in RFC 2578 Section 3.5, all OIDs are limited to 128 1096 sub-identifiers. While this is not likely to cause problems with 1097 administrative assignments, it does place some limitations on table 1098 indexing. That is true because the length limitation also applies to 1099 OIDs for object instances, and these consist of the concatenation of 1100 the "base" OID assigned in the object definition plus the index 1101 components. When a table has multiple indices of types such as OCTET 1102 STRING or OBJECT IDENTIFIER that resolve to multiple sub-identifiers, 1103 then the 128 sub-identifier limit can be quickly reached. 1105 Despite its inconvenience, the 128 sub-identifier limit is not 1106 something that can be ignored. In addition to being imposed by the 1107 SMI, it is also imposed by the SNMP (see the last paragraph in 1108 Section 4.1 of RFC 3416 [RFC3416]). It follows that any table with 1109 enough indexing components to violate this limit cannot be read or 1110 written using the SNMP and so is unusable. Hence table design MUST 1111 take the 128 sub-identifier limit into account. It is RECOMMENDED 1112 that all MIB documents make explicit any limitations on index 1113 component lengths that management software must observe. This may be 1114 done either by including SIZE constraints on the index components or 1115 by specifying applicable constraints in the conceptual row 1116 DESCRIPTION clause or in the surrounding documentation. 1118 4.7. Notification Definitions 1120 RFC 2578 Section 8 specifies the rules for notification definitions. 1121 In particular: 1123 - Inaccessible objects MUST NOT appear in the OBJECTS clause. 1125 - For each object type mentioned in the OBJECTS clause, the 1126 DESCRIPTION clause MUST specify which object instance is to be 1127 present in the transmitted notification and MUST specify the 1128 information/meaning conveyed. 1130 - The OBJECT IDENTIFIER (OID) value assigned to each notification 1131 type MUST have a next-to-last sub-identifier of zero, so that it is 1132 possible to convert an SMIv2 notification definition into an SMIv1 1133 trap definition and back again without information loss (see 1134 [RFC3584] Section 2.1.2) and possible for a multilingual proxy 1135 chain to translate an SNMPv2 trap into an SNMPv1 trap and back 1136 again without information loss (see [RFC3584] Section 3). In 1137 addition, the OID assigned to a notification definition MUST NOT 1138 also be assigned to another definition that results in OID 1139 registration. RFC 2578 Section 3.6 lists the constructs that 1140 create OID registrations. 1142 Although it is not specifically required by the SMI, it is customary 1143 (and strongly RECOMMENDED) that notification definitions not be 1144 registered beneath group definitions, compliance statements, 1145 capabilities statements, or object definitions (this last is 1146 especially unwise, as it may result in an object instance and a 1147 notification definition sharing the same OID). It is also customary 1148 (and strongly RECOMMENDED) that the OIDs assigned to notification 1149 types be leaf OIDs (i.e., that there be no OID registrations 1150 subordinate to a notification definition). See Appendix D for a 1151 RECOMMENDED OID assignment scheme. 1153 In many cases notifications will be triggered by external events, and 1154 sometimes it will be possible for those external events to occur at a 1155 sufficiently rapid rate that sending a notification for each 1156 occurrence would overwhelm the network. In such cases a mechanism 1157 MUST be provided for limiting the rate at which the notification can 1158 be generated. A common technique is to require that the notification 1159 generator use throttling -- that is, to require that it generate no 1160 more than one notification for each event source in any given time 1161 interval of duration T. The throttling period T MAY be configurable, 1162 in which case it is specified in a MIB object, or it MAY be fixed, in 1163 which case it is specified in the notification definition. Examples 1164 of the fixed time interval technique can be found in the 1165 SNMP-REPEATER-MIB [RFC2108] and in the ENTITY-MIB [RFC2737bis]. 1167 4.8. Compliance Statements 1169 RFC 2580 Sections 3, 4, and 5 specify the rules for conformance 1170 groups and compliance statements. In particular: 1172 - Every object with a MAX-ACCESS value other than "not-accessible" 1173 MUST be contained in at least one object group. 1175 - Every notification MUST be contained in at least one notification 1176 group. 1178 - There MUST be at least one compliance statement defined for each 1179 "standard" MIB module. It may reside either within that MIB module 1180 or within a companion MIB module. 1182 In writing compliance statements there are several points that are 1183 easily overlooked: 1185 - An object group or notification group that is not mentioned either 1186 in the MANDATORY-GROUPS clause or in any GROUP clause of a 1187 MODULE-COMPLIANCE statement is unconditionally optional with 1188 respect to that compliance statement. An alternate way to indicate 1189 that an object group or notification group is optional is to 1190 mention it in a GROUP clause whose DESCRIPTION clause states that 1191 the group is optional. The latter method is RECOMMENDED (for 1192 optional groups that are relevant to the compliance statement) in 1193 order to make it clear that the optional status is intended rather 1194 than being the result of an act of omission. 1196 - If there are any objects with a MAX-ACCESS value of read-write or 1197 read-create for which there is no OBJECT clause that specifies a 1198 MIN-ACCESS of read-only, then implementations must support write 1199 access to those objects in order to be compliant with that 1200 MODULE-COMPLIANCE statement. This fact sometimes catches MIB 1201 module authors by surprise. When confronted with such cases, 1202 reviewers SHOULD verify that this is indeed what the authors 1203 intended, since it often is not. 1205 - On the other side of the coin, MIB module authors need to be aware 1206 that while a read-only compliance statement is sufficient to 1207 support interoperable monitoring applications, it is not sufficient 1208 to support interoperable configuration applications. A technique 1209 commonly used in MIB modules that are intended to support both 1210 monitoring and configuration is to provide both a read-only 1211 compliance statement and a full compliance statement. A good 1212 example is provided by the DIFFSERV-MIB [RFC3289]. Authors SHOULD 1213 consider using this technique when it is applicable. 1215 Sometimes MIB module authors will want to specify that a compliant 1216 implementation needs to support only a subset of the values allowed 1217 by an object's SYNTAX clause. For accessible objects this may be 1218 done either by specifying the required values in an object's 1219 DESCRIPTION clause or by providing an OBJECT clause with a refined 1220 SYNTAX in a compliance statement. The latter method is RECOMMENDED 1221 for most cases, and is REQUIRED if there are multiple compliance 1222 statements with different value subsets required. The DIFFSERV-MIB 1223 [RFC3289] illustrates this point. The diffServMIBFullCompliance 1224 statement contains the following OBJECT clause (*) 1226 OBJECT diffServDataPathStatus 1227 SYNTAX RowStatus { active(1) } 1228 WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) } 1229 DESCRIPTION 1230 "Support for createAndWait and notInService is not required." 1232 whereas the diffServMIBReadOnlyCompliance statement contains this: 1234 OBJECT diffServDataPathStatus 1235 SYNTAX RowStatus { active(1) } 1236 MIN-ACCESS read-only 1237 DESCRIPTION 1238 "Write access is not required, and active is the only status that 1239 needs to be supported." 1241 One cannot do this for inaccessible index objects because they cannot 1242 be present in object groups and cannot be mentioned in OBJECT 1243 clauses. There are situations, however, in which one might wish to 1244 indicate that an implementation is required to support only a subset 1245 of the possible values of some index in a read-create table. In such 1246 cases the requirements MUST be specified either in the index object's 1247 DESCRIPTION clause (RECOMMENDED if there is only one value subset) or 1248 in the DESCRIPTION clause of a MODULE-COMPLIANCE statement (REQUIRED 1249 if the value subset is unique to the compliance statement). 1251 In many cases a MIB module is always implemented in conjunction with 1252 one or more other MIB modules. That fact is REQUIRED to be noted in 1253 the surrounding documentation (see Section 3.2 above), and it SHOULD 1254 also be noted in the relevant compliance statements as well. In 1255 cases where a particular compliance statement in (say) MIB module A 1256 requires the complete implementation of some other MIB module B, then 1257 the RECOMMENDED approach is to include a statement to that effect in 1258 the DESCRIPTION clause of the compliance statement(s) in MIB module 1259 A. It is also possible, however, that MIB module A might have 1260 requirements that are different from those that are expressed by any 1261 any compliance statement of module B -- for example, module A might 1262 not require any of the unconditionally mandatory object groups from 1263 module B but might require mandatory implementation of an object 1264 group from module B that is only conditionally mandatory with respect 1265 to the compliance statement(s) in module B. In such cases the 1266 RECOMMENDED approach is for the compliance statement(s) in module A 1267 to formally specify requirements with respect to module B via 1268 appropriate MODULE, MANDATORY-GROUPS, GROUP, and OBJECT clauses. An 1269 example is provided by the compliance statements in the DIFFSERV-MIB 1270 [RFC3289], which list the ifCounterDiscontinuityGroup from IF-MIB 1271 [RFC2863] as a mandatory group. That group is not sufficient to 1272 satisfy any IF-MIB compliance statement, and it is conditionally 1273 mandatory in the IF-MIB's current compliance statement ifCompliance3. 1274 _______________________________ 1275 (*) There has been some dispute as to whether syntax refinements that 1276 restrict enumerations (RFC 2578, Section 9) are permitted with TCs, 1277 as shown in these examples, or are allowed only with the base types 1278 INTEGER and BITS, as suggested by a strict reading of RFC 2578. The 1279 rough consensus of the editors of the SMIv2 documents and the current 1280 pool of MIB reviewers is that they should be allowed with TCs. MIB 1281 module authors should be aware that some MIB compilers follow the 1282 strict reading of RFC 2578 and require that the TC be replaced by its 1283 base type (INTEGER or BITS) when enumerations are refined. That 1284 usage is legal, and it can be found in some older MIB modules such as 1285 the IF-MIB [RFC2863]. 1287 4.9. Revisions to MIB Modules 1289 RFC 2578 Section 10 specifies general rules that apply any time a MIB 1290 module is revised. Specifically: 1292 - The MODULE-IDENTITY invocation MUST be updated to include 1293 information about the revision. In particular, the LAST-UPDATED 1294 clause value MUST be set to the revision time, a REVISION clause 1295 with the same UTC time and an associated DESCRIPTION clause 1296 describing the changes MUST be added, and any obsolete information 1297 in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses 1298 MUST be replaced with up-to-date information. See Section 4.5 1299 above for additional requirements that apply to MIB modules that 1300 are under IETF change control. 1302 - On the other hand, the module name MUST NOT be changed (except to 1303 correct typographical errors), existing definitions (even obsolete 1304 ones) MUST NOT be removed from the MIB module, and descriptors and 1305 OBJECT IDENTIFIER values associated with existing definitions MUST 1306 NOT be changed or re-assigned. 1308 It is important to note that the purpose in forbidding certain kinds 1309 of changes is to ensure that a revised MIB module is compatible with 1310 fielded implementations based on previous versions of the module. 1311 There are two distinct aspects of this backward compatibility 1312 requirement. One is "over the wire" compatibility of agent and 1313 manager implementations that are based on different revisions of the 1314 MIB module. The other is "compilation" compatibility with MIB 1315 modules that import definitions from the revised MIB module. The 1316 rules forbidding changing or re-assigning OBJECT IDENTIFIER values 1317 are necessary to ensure "over the wire" compatibility; the rules 1318 against changing module names or descriptors or removing obsolete 1319 definitions are necessary to ensure compilation compatibility. 1321 RFC 2578 Section 10.2 specifies rules that apply to revisions of 1322 object definitions. The following guidelines correct some errors in 1323 these rules and provided some clarifications: 1325 - Bullet (1) allows the labels of named numbers and named bits in 1326 SYNTAX clauses of type enumerated INTEGER or BITS to be changed. 1327 This can break compilation compatibility, since those labels may be 1328 used by DEFVAL clauses in modules that import the definitions of 1329 the affected objects. Therefore, labels of named numbers and named 1330 bits MUST NOT be changed when revising IETF MIB modules (except to 1331 correct typographical errors), and they SHOULD NOT be changed when 1332 revising enterprise MIB modules. 1334 - Although not specifically permitted in bullets (1) through (8), it 1335 is generally considered acceptable to add range constraints to the 1336 SYNTAX clause of an integer-valued object, provided that the 1337 constraints simply make explicit some value restrictions that were 1338 implicit in the definition of the object. The most common example 1339 is an auxiliary object with a SYNTAX of INTEGER or Integer32 with 1340 no range constraint. Since an auxiliary object is not permitted to 1341 assume negative values, adding the range constraint (0..2147483647) 1342 cannot possibly result in any "over the wire" change, nor will it 1343 cause any compilation compatibility problems with a correctly 1344 written MIB module. Such a change SHOULD be treated by a reviewer 1345 as an editorial change, not as a semantic change. Similarly, 1346 removal of a range or size constraint from an object definition 1347 when that range or size constraint is enforced by the underlying 1348 data type SHOULD be treated by a reviewer as an editorial change. 1350 RFC 2578 Section 10.3 specifies rules that apply to revisions of 1351 notification definitions. No clarifications or corrections are 1352 required. 1354 RFC 2579 Section 5 specifies rules that apply to revisions of textual 1355 convention definitions. The following guideline corrects an error in 1356 these rules: 1358 - Bullet (1) allows the labels of named numbers and named bits in 1359 SYNTAX clauses of type enumerated INTEGER or BITS to be changed. 1360 This can break compilation compatibility, since those labels may be 1361 used by DEFVAL clauses in modules that import the definitions of 1362 the affected TCs. Therefore, labels of named numbers and named 1363 bits MUST NOT be changed when revising IETF MIB modules (except to 1364 correct typographical errors), and they SHOULD NOT be changed when 1365 revising enterprise MIB modules. 1367 RFC 2580 Section 7.1 specifies rules that apply to revisions of 1368 conformance groups. Two point are worth re-iterating: 1370 - Objects and notifications MUST NOT be added to or removed from an 1371 existing object group or notification group. Doing so could cause 1372 a compilation failure or (worse) a silent change in the meaning of 1373 a compliance statement or capabilities statement that refers to 1374 that group. 1376 - The status of a conformance group is independent of the status of 1377 its members. Thus, a current group MAY refer to deprecated objects 1378 or notifications. This may be desirable in certain cases, e.g., a 1379 set of widely-deployed objects or notifications may be deprecated 1380 when they are replaced by a more up-to-date set of definitions, but 1381 the conformance groups that contain them may remain current in 1382 order to encourage continued implementation of the deprecated 1383 objects and notifications. 1385 RFC 2580 Section 7.2 specifies rules that apply to revisions of 1386 compliance statements. The following guidelines correct an omission 1387 from these rules and emphasize one important point: 1389 - RFC 2580 should (but does not) recommend that an OBJECT clause 1390 specifying support for the original set of values be added to a 1391 compliance statement when an enumerated INTEGER object or a BITS 1392 object referenced by the compliance statement has enumerations or 1393 named bits added, assuming that no such clause is already present 1394 and that the effective MIN-ACCESS value is read-write or 1395 read-create. This is necessary in order to avoid a silent change 1396 to the meaning of the compliance statement. MIB module authors and 1397 reviewers SHOULD watch for this to ensure that such OBJECT clauses 1398 are added when needed. Note that this may not always be possible 1399 to do, since affected compliance statements may reside in modules 1400 other than the one that contains the revised definition(s). 1402 - The status of a compliance statement is independent of the status 1403 of its members. Thus, a current compliance statement MAY refer to 1404 deprecated object groups or notification groups. This may be 1405 desirable in certain cases, e.g., a set of widely-deployed object 1406 or notification groups may be deprecated when they are replaced by 1407 a more up-to-date set of definitions, but compliance statements 1408 that refer to them may remain current in order to encourage 1409 continued implementation of the deprecated groups. 1411 RFC 2580 Section 7.3 specifies rules that apply to revisions of 1412 capabilities statements. The following guideline corrects an 1413 omission from these rules: 1415 - RFC 2580 should (but does not) recommend that VARIATION clauses 1416 specifying support for the original set of values be added to a 1417 capabilities statement when enumerated INTEGER objects or BITS 1418 objects referenced by the capabilities statement have enumerations 1419 added, assuming that no such clauses are already present. This is 1420 necessary in order to avoid a silent change to the meaning of the 1421 capabilities statement. 1423 In certain exceptional situations the cost of strictly following the 1424 SMIv2 rules governing MIB modules revisions may exceed the benefit. 1425 In such cases the rules can be waived, but when that is done both the 1426 change and the justification for it MUST be thoroughly documented. 1427 One example is provided by Section 3.1.5 of RFC 2863, which documents 1428 the semantic change that was made to ifIndex in the transition from 1429 MIB-II [RFC1213] to the IF-MIB [RFC2863] and provides a detailed 1430 justification for that change. Another example is provided by the 1431 REVISION clause of the SONET-MIB [RFC2558] that documents raising the 1432 MAX-ACCESS of several objects to read-write while adding MIN-ACCESS 1433 of read-only for compatibility with the previous version [RFC1595]. 1435 Authors and reviewers may find it helpful to use tools that can list 1436 the differences between two revisions of a MIB module. Please see 1437 http://www.ops.ietf.org/mib-review-tools.html for more information. 1439 5. Acknowledgments 1441 Most of the material on usage of data types was based on input 1442 provided by Bert Wijnen with assistance from Keith McCloghrie, David 1443 T. Perkins, and Juergen Schoenwaelder. Much of the other material on 1444 SMIv2 usage was taken from an unpublished guide for MIB authors and 1445 reviewers by Juergen Schoenwaelder. Some of the recommendations in 1446 these guidelines are based on material drawn from the on-line SMIv2 1447 errata list at http://www.ibr.cs.tu-bs.de/ietf/smi-errata/. Thanks 1448 to Frank Strauss and Juergen Schoenwaelder for maintaining that list 1449 and to the contributors who supplied the material for that list. 1450 Finally, thanks are due to the following individuals whose comments 1451 on earlier versions of this memo contained many valuable suggestions 1452 for additions, clarifications, and corrections: Andy Bierman, Bob 1453 Braden, Michelle Cotton, David Harrington, Harrie Hazewinkel, 1454 Dinakaran Joseph, Michael Kirkham, Keith McCloghrie, David T. 1455 Perkins, Randy Presuhn, Dan Romascanu, Juergen Schoenwaelder, Frank 1456 Strauss, Dave Thaler, and Bert Wijnen. 1458 6. Security Considerations 1460 Implementation and deployment of a MIB module in a system may result 1461 in security risks that would not otherwise exist. It is important 1462 for authors and reviewers of documents that define MIB modules to 1463 ensure that those documents fully comply with the guidelines in 1464 http://www.ops.ietf.org/mib-security.html so that all such risks are 1465 adequately disclosed. 1467 7. IANA Considerations 1469 This document affects the IANA to the extent that it describes what 1470 is required to be present in the IANA Considerations Section of a MIB 1471 document, but it does not require that the IANA update any existing 1472 registry or create any new registry. 1474 Appendix A: MIB Review Checklist 1476 The purpose of a MIB review is to review the MIB module both for 1477 technical correctness and for adherence to IETF documentation 1478 requirements. The following checklist may be helpful when reviewing 1479 a draft document: 1481 1.) I-D Boilerplate -- verify that the draft contains the required 1482 Internet-Draft boilerplate (see 1483 http://www.ietf.org/ietf/1id-guidelines.txt), including the 1484 appropriate statement to permit publication as an RFC, and that I-D 1485 boilerplate does not contain references or section numbers. 1487 2.) Abstract -- verify that the abstract does not contain references, 1488 that it does not have a section number, and that its content follows 1489 the guidelines in http://www.ietf.org/ietf/1id-guidelines.txt. 1491 3.) MIB Boilerplate -- verify that the draft contains the latest 1492 approved SNMP Network Management Framework boilerplate from the OPS 1493 area web site (http://www.ops.ietf.org/mib-boilerplate.html). 1495 4.) Security Considerations Section -- verify that the draft uses the 1496 latest approved template from the OPS area web site 1497 (http://www.ops.ietf.org/mib-security.html) and that the guidelines 1498 therein have been followed. 1500 5.) IANA Considerations Section -- this section must always be 1501 present. If the draft requires no action from the IANA, ensure that 1502 this is explicitly noted. If the draft requires OID values to be 1503 assigned, ensure that the IANA Considerations section contains the 1504 information specified in Section 3.5 of these guidelines. If the 1505 draft contains the initial version of an IANA-maintained module, 1506 verify that the MODULE-IDENTITY invocation contains maintenance 1507 instructions that comply with the requirements in RFC 2434. In the 1508 latter case the IANA Considerations section that will appear in the 1509 RFC MUST contain a pointer to the actual IANA-maintained module. 1511 6.) References -- verify that the references are properly divided 1512 between normative and informative references, that RFC 2119 is 1513 included as a normative reference if the terminology defined therein 1514 is used in the document, that all references required by the 1515 boilerplate are present, that all MIB modules containing imported 1516 items are cited as normative references, and that all citations point 1517 to the most current RFCs unless there is a valid reason to do 1518 otherwise (for example, it is OK to include an informative reference 1519 to a previous version of a specification to help explain a feature 1520 included for backward compatibility). 1522 7.) Copyright Notices -- verify that the draft contains an 1523 abbreviated copyright notice in the DESCRIPTION clause of each 1524 MODULE-IDENTITY invocation and that it contains the full copyright 1525 notice and disclaimer specified in Sections 5.4 and 5.5 of RFC 3907 1526 at the end of the document. Make sure that the correct year is used 1527 in all copyright dates. 1529 8.) IPR Notice -- if the draft does not contains a verbatim copy of 1530 the IPR notice specified in Section 5 of RFC 3908, recommend that the 1531 IPR notice be included. 1533 9.) Other issues -- check for any issues mentioned in 1534 http://www.ietf.org/ID-Checklist.html that are not covered elsewhere. 1536 10.) Technical content -- review the actual technical content for 1537 compliance with the guidelines in this document. The use of a MIB 1538 compiler is recommended when checking for syntax errors; see 1539 http://www.ops.ietf.org/mib-review-tools.html for more information. 1540 Checking for correct syntax, however, is only part of the job. It is 1541 just as important to actually read the MIB document from the point of 1542 view of a potential implementor. It is particularly important to 1543 check that DESCRIPTION clauses are sufficiently clear and unambiguous 1544 to allow interoperable implementations to be created. 1546 Appendix B: Commonly Used Textual Conventions 1548 The following TCs are defined in SNMPv2-TC [RFC2579]: 1550 DisplayString OCTET STRING (SIZE (0..255)) 1551 PhysAddress OCTET STRING 1552 MacAddress OCTET STRING (SIZE (6)) 1553 TruthValue enumerated INTEGER 1554 TestAndIncr INTEGER (0..2147483647) 1555 AutonomousType OBJECT IDENTIFIER 1556 VariablePointer OBJECT IDENTIFIER 1557 RowPointer OBJECT IDENTIFIER 1558 RowStatus enumerated INTEGER 1559 TimeStamp TimeTicks 1560 TimeInterval INTEGER (0..2147483647) 1561 DateAndTime OCTET STRING (SIZE (8 | 11)) 1562 StorageType enumerated INTEGER 1563 TDomain OBJECT IDENTIFIER 1564 TAddress OCTET STRING (SIZE (1..255)) 1566 Note 1. InstancePointer is obsolete and MUST NOT be used. 1568 Note 2. DisplayString does not support internationalized text. 1569 It MUST NOT be used for objects that are required to 1570 hold internationalized text (which is always the case 1571 if the object is intended for use by humans [RFC2277]). 1572 Designers SHOULD consider using SnmpAdminString, 1573 Utf8String, or LongUtf8String for such objects. 1575 Note 3. TDomain and TAddress SHOULD NOT be used in new MIB 1576 modules. The TransportDomain, TransportAddressType, and 1577 TransportAddress TCs (defined in TRANSPORT-ADDRESS-MIB 1578 [RFC3419]) SHOULD be used instead. 1580 The following TC is defined in SNMP-FRAMEWORK-MIB [RFC3411]: 1582 SnmpAdminString OCTET STRING (SIZE (0..255)) 1583 The following TCs are defined in SYSAPPL-MIB [RFC2287]: 1585 Utf8String OCTET STRING (SIZE (0..255)) 1586 LongUtf8String OCTET STRING (SIZE (0..1024)) 1588 The following TCs are defined in INET-ADDRESS-MIB [RFC3291bis]: 1590 InetAddressType enumerated INTEGER 1591 InetAddress OCTET STRING (SIZE (0..255)) 1592 InetAddressPrefixLength Unsigned32 (0..2040) 1593 InetPortNumber Unsigned32 (0..65535)) 1594 InetAutonomousSystemNumber Unsigned32 1595 InetScopeType enumerated INTEGER 1596 InetZoneIndex Unsigned32 1597 InetVersion enumerated INTEGER 1599 The following TCs are defined in TRANSPORT-ADDRESS-MIB [RFC3419]: 1601 TransportDomain OBJECT IDENTIFIER 1602 TransportAddressType enumerated INTEGER 1603 TransportAddress OCTET STRING (SIZE (0..255)) 1605 The following TC is defined in RMON2-MIB [RFC2021]: 1607 ZeroBasedCounter32 Gauge32 1609 The following TCs are defined in HCNUM-TC [RFC2856]: 1611 ZeroBasedCounter64 Counter64 1612 CounterBasedGauge64 Counter64 1614 The following TCs are defined in IF-MIB [RFC2863]: 1616 InterfaceIndex Integer32 (1..2147483647) 1617 InterfaceIndexOrZero Integer32 (0..2147483647) 1619 The following TCs are defined in ENTITY-MIB [RFC2737bis]: 1621 PhysicalIndex Integer32 (1..2147483647) 1622 PhysicalIndexOrZero Integer32 (0..2147483647) 1623 The following TCs are defined in PerfHist-TC-MIB [RFC3593]: 1625 PerfCurrentCount Gauge32 1626 PerfIntervalCount Gauge32 1627 PerfTotalCount Gauge32 1629 The following TCs are defined in HC-PerfHist-TC-MIB [RFC3705]: 1631 HCPerfValidIntervals Integer32 (0..96) 1632 HCPerfInvalidIntervals Integer32 (0..96) 1633 HCPerfTimeElapsed Integer32 (0..86399) 1634 HCPerfIntervalThreshold Unsigned32 (0..900) 1635 HCPerfCurrentCount Counter64 1636 HCPerfIntervalCount Counter64 1637 HCPerfTotalCount Counter64 1639 Appendix C: Suggested Naming Conventions 1641 Authors and reviewers of IETF MIB modules have often found the 1642 following naming conventions to be helpful in the past, and authors 1643 of new IETF MIB modules are urged to consider following them. 1645 - The module name should be of the form XXX-MIB (or XXX-TC-MIB for a 1646 module with TCs only), where XXX is a unique prefix (usually all 1647 caps with hyphens for separators) that is not used by any existing 1648 module. For example, the module for managing optical interfaces 1649 [RFC3591] uses the prefix OPT-IF and has module name OPT-IF-MIB. 1651 - The descriptor associated with the MODULE-IDENTITY invocation 1652 should be of the form xxxMIB, xxxMib, or xxxMibModule, where xxx is 1653 a mixed-case version of XXX starting with a lower-case letter and 1654 without any hyphens. For example, the OPT-IF-MIB uses the prefix 1655 optIf, and the descriptor associated with its MODULE-IDENTITY 1656 invocation is optIfMibModule. 1658 - Other descriptors within the MIB module should start with the same 1659 prefix xxx. OPT-IF-MIB uses the prefix optIf for all descriptors. 1661 - Names of TCs that are specific to the MIB module and names of 1662 SEQUENCE types that are used in conceptual table definitions should 1663 start with a prefix Xxx that is the same as xxx but with the 1664 initial letter changed to upper case. OPT-IF-MIB uses the prefix 1665 OptIf on the names of TCs and SEQUENCE types. 1667 - The descriptor associated with a conceptual table should be of the 1668 form xxxZzzTable; the descriptor associated with the corresponding 1669 conceptual row should be of the form xxxZzzEntry; the name of the 1670 associated SEQUENCE type should be of the form XxxZzzEntry; and 1671 the descriptors associated with the subordinate columnar objects 1672 should be of the form xxxZzzSomeotherName. An example from the 1673 OPT-IF-MIB is the OTMn table. The descriptor of the table object 1674 is optIfOTMnTable, the descriptor of the row object is 1675 optIfOTMnEntry, the name of the associated SEQUENCE type is 1676 OptIfOTMnEntry, and the descriptors of the columnar objects are 1677 optIfOTMnOrder, optIfOTMnReduced, optIfOTMnBitRates, 1678 optIfOTMnInterfaceType, optIfOTMnTcmMax, and optIfOTMnOpticalReach. 1680 - When abbreviations are used, then they should be used consistently. 1681 Inconsistent usage such as 1683 xxxYyyDestAddr 1684 xxxZzzDstAddr 1686 should be avoided. 1688 Appendix D: Suggested OID Layout 1690 As noted in RFC 2578 Section 5.6, it is common practice to use the 1691 value of the MODULE-IDENTITY invocation as a subtree under which 1692 other OBJECT IDENTIFIER values assigned within the module are 1693 defined. That, of course, leaves open the question of how OIDs are 1694 assigned within that subtree. One assignment scheme that has gained 1695 favor -- and which is RECOMMENDED unless there is a specific reason 1696 not use it -- is to have three separate branches immediately below 1697 the MODULE-IDENTITY value dedicated (respectively) to notification 1698 definitions, object definitions, and conformance definitions, and to 1699 further subdivide the conformance branch into separate sub-branches 1700 for compliance statements and object/notification groups. This 1701 structure is illustrated below, with naming conventions following 1702 those outlined in Appendix C. The numbers in parentheses are the 1703 sub-identifiers assigned to the branches. 1705 xxxMIB 1706 | 1707 +-- xxxNotifications(0) 1708 +-- xxxObjects(1) 1709 +-- xxxConformance(2) 1710 | 1711 +-- xxxCompliances(1) 1712 +-- xxxGroups(2) 1714 When using this scheme notification definition values are assigned 1715 immediately below the xxxNotifications node. This ensures that each 1716 OID assigned to a notification definition has a next-to-last 1717 sub-identifier of zero, which is REQUIRED by Section 4.7 above. The 1718 other sub-branches may have additional sub-structure, but none beyond 1719 that specified in Section 4.6.5 above is actually required. 1721 One example of a MIB module whose OID assignments follow this scheme 1722 is the POWER-ETHERNET-MIB [RFC3621]. 1724 Normative References 1726 [RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1727 Rose, M. and S. Waldbusser, "Structure of Management 1728 Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1729 1999. 1731 [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1732 Rose, M. and S. Waldbusser, "Textual Conventions for 1733 SMIv2", STD 58, RFC 2579, April 1999. 1735 [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 1736 Rose, M. and S. Waldbusser, "Conformance Statements for 1737 SMIv2", STD 58, RFC 2580, April 1999. 1739 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1740 Requirements Levels", BCP 14, RFC 2119, March 1997. 1742 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 1743 MIB", RFC 2863, June 2000. 1745 [RFC2864] McCloghrie, K. and G. Hanson, "The Inverted Stack Table 1746 Extension to the Interfaces Group MIB", RFC 2864, June 2000. 1748 [RFC2434] Alvestrand, H., "Guidelines for Writing an IANA 1749 Considerations Section in RFCs", BCP 26, RFC 2434, October 1750 1998. 1752 [RFC3907] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC 1753 3907, to appear. 1755 [RFC3908] Bradner, S., "Intellectual Property Rights in IETF 1756 Technology", BCP 79, RFC 3908, to appear. 1758 [RFC3291bis] 1759 Daniele, M., Haberman, B., Routhier, S. and J. 1760 Schoenwaelder, "Textual Conventions for Internet Network 1761 Addresses", work in progress (currently draft-ietf-ops- 1762 rfc3291bis-06.txt). 1764 [RFC3593] Tesink, K., "Textual Conventions for MIB Modules Using 1765 Performance History Based on 15 Minute Intervals", RFC 3593, 1766 September 2003. 1768 [RFC3705] Ray, B. and R. Abbi, "High Capacity Textual Conventions for 1769 MIB Modules Using Performance History Based on 15 Minute 1770 Intervals", RFC 3705, February 2004. 1772 [RFC2021] Waldbusser, S., "Remote Network Monitoring Management 1773 Information Base Version 2 using SMIv2", RFC 2021, January 1774 1997. 1776 [RFC2856] Bierman, A., McCloghrie, K. and R. Presuhn, "Textual 1777 Conventions for Additional High Capacity Data Types", RFC 1778 2856, June 2000. 1780 [RFC3411] Harrington, D., Presuhn, R. and B. Wijnen, "An Architecture 1781 for Describing Simple Network Management Protocol (SNMP) 1782 Management Frameworks", STD 62, RFC 3411, December 2002. 1784 [RFC2287] Krupczak, C. and J. Saperia, "Definitions of System-Level 1785 Managed Objects for Applications", RFC 2287, February 1998. 1787 [RFC3418] Presuhn, R., Case, J., McCloghrie, K., Rose, M. and S. 1788 Waldbusser, "Management Information Base (MIB) for the 1789 Simple Network Management Protocol (SNMP)", STD 62, RFC 1790 3418, December 2002. 1792 [RFC3416] Presuhn, R., Case, J., McCloghrie, K., Rose, M. and S. 1793 Waldbusser, "Protocol Operations for the Simple Network 1794 Management Protocol (SNMP)", STD 62, RFC 3416, December 1795 2002. 1797 [RFC2737bis] 1798 McCloghrie, K. and A. Bierman, "Entity MIB (Version 3)", 1799 work in progress (currently draft-ietf-entmib-v3-07.txt). 1801 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 1802 Languages", BCP 18, RFC 2277, January 1998. 1804 [RFC3419] M. Daniele, M. and J. Schoenwaelder, "Textual Conventions 1805 for Transport Addresses", RFC 3419, December 2002. 1807 Informative References 1809 [RFC1155] Rose, M. and K. McCloghrie, "Structure and Identification of 1810 Management Information for TCP/IP-based Internets", STD 16, 1811 RFC 1155, May 1990. 1813 [RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 1814 16, RFC 1212, March 1991. 1816 [RFC1215] Rose, M., "A Convention for Defining Traps for use with the 1817 SNMP", RFC 1215, March 1991. 1819 [RFC2223bis] 1820 Reynolds, J., and R. Braden, "Instructions to Request for 1821 Comments (RFC) Authors", work in progress (currently ). 1824 [RFC3410] Case, J., Mundy, R., Partain, D. and B. Stewart, 1825 "Introduction and Applicability Statements for Internet- 1826 Standard Management Framework", RFC 3410, December 2002. 1828 [RFC2932] McCloghrie, K., Farinacci, D., and D. Thaler, "IPv4 1829 Multicast Routing MIB", RFC 2932, October 2000. 1831 [RFC1573] McCloghrie, K. and F. Kastenholz, "Evolution of the 1832 Interfaces Group of MIB-II", RFC 1573, January 1994. 1834 [RFC3621] Berger, A. and D. Romascanu, "Power Ethernet MIB", RFC 3621, 1835 December 2003. 1837 [RFC3584] Frye, R., Levi, D., Routhier, S. and B. Wijnen, "Coexistence 1838 between Version 1, Version 2, and Version 3 of the Internet- 1839 standard Network Management Framework", BCP 74, RFC 3584, 1840 August 2003. 1842 [RFC2108] de Graaf, K., Romascanu, D., McMaster, D. and K. McCloghrie, 1843 "Definitions of Managed Objects for IEEE 802.3 Repeater 1844 Devices using SMIv2", RFC 2108, February 1997. 1846 [RFC3289] Baker, F., Chan, K. and A. Smith, "Management Information 1847 Base for the Differentiated Services Architecture", RFC 1848 3289, May 2002. 1850 [RFC1213] McCloghrie, K. and M. Rose, "Management Information Base for 1851 Network Management of TCP/IP-based internets - MIB-II", STD 1852 17, RFC 1213, March 1991. 1854 [RFC1595] Brown, T. and K. Tesink, "Definitions of Managed Objects for 1855 the SONET/SDH Interface Type", RFC 1595, March 1994. 1857 [RFC2558] Tesink, K., "Definitions of Managed Objects for the 1858 SONET/SDH Interface Type", RFC 2558, March 1999. 1860 [RFC3591] Lam, H-K., Stewart, M. and A. Huynh, "Definitions of Managed 1861 Objects for the Optical Interface Type", RFC 3591, September 1862 2003. 1864 Editor's Address 1866 C. M. Heard 1867 158 South Madison Ave. #207 1868 Pasadena, CA 91101-2569 1869 USA 1871 Phone: +1 626 795 5311 1872 EMail: heard@pobox.com 1874 Full Copyright Statement 1876 Copyright (C) The Internet Society (2005). 1878 This document is subject to the rights, licenses and restrictions 1879 contained in BCP 78, and except as set forth therein, the authors 1880 retain all their rights. 1882 This document and the information contained herein are provided on an 1883 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1884 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, AND THE INTERNET 1885 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1886 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1887 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1888 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1890 Intellectual Property 1892 The IETF takes no position regarding the validity or scope of any 1893 Intellectual Property Rights or other rights that might be claimed to 1894 pertain to the implementation or use of the technology described in 1895 this document or the extent to which any license under such rights 1896 might or might not be available; nor does it represent that it has 1897 made any independent effort to identify any such rights. Information 1898 on the procedures with respect to rights in RFC documents can be 1899 found in BCP 78 and BCP 79. 1901 Copies of IPR disclosures made to the IETF Secretariat and any 1902 assurances of licenses to be made available, or the result of an 1903 attempt made to obtain a general license or permission for the use of 1904 such proprietary rights by implementors or users of this 1905 specification can be obtained from the IETF on-line IPR repository at 1906 http://www.ietf.org/ipr. 1908 The IETF invites any interested party to bring to its attention any 1909 copyrights, patents or patent applications, or other proprietary 1910 rights that may cover technology that may be required to implement 1911 this standard. Please address the information to the IETF at 1912 ietf-ipr@ietf.org. 1914 Acknowledgement 1916 Funding for the RFC Editor function is currently provided by the 1917 Internet Society. 1919 Revision History 1921 NOTE TO RFC Editor: this section is to be removed prior to 1922 publication as an RFC. 1924 The following changes were made to to produce : 1928 1.) The Abstract, Section 1, and Section 3 were revised to 1929 clarify that the guidelines are targeted specifically at IETF 1930 standards-track documents containing MIB modules but may be used 1931 as a basis for reviews of other documents containing MIB modules. 1933 2.) A note was added to Section 1 pointing out that some of the 1934 guidelines do not apply to MIB modules that have been converted to 1935 SMIv2 from SMIv1. 1937 3.) A note was added to Section 2 clarifying that the term 1938 "standard", when it appears in quotes, is being used in the same 1939 way as in RFCs 2578/2579/2580. 1941 4.) A typo (s/MIB modules/MIB module(s)/) was corrected in 1942 Section 3.3. 1944 5.) The second paragraph of Section 3.5 was revised to include a 1945 requirement for a normative reference to the on-line version of an 1946 IANA-maintained MIB module that appears in an IMPORTS statement. 1948 6.) Additional instructions to authors regarding the preparation 1949 of a Security Considerations section were incorporated into 1950 Section 3.6. 1952 7.) A typo (s/defined/defines/) was corrected in the second 1953 paragraph of Section 3.7. 1955 8.) In accordance with a recent IESG decision, the third 1956 paragraph of Section 3.7 was revised to state that the accepted 1957 procedure for the initial version of an IANA-maintained MIB module 1958 is to publish it in a non-normative section of the initial issue 1959 of the document that defines the corresponding name space, as was 1960 done in RFC 1573 for the IANAifType-MIB. 1962 9.) An Editor's Note was added to Section 3.8 to alert authors 1963 and reviewers that a copyright notice will be required in the 1964 MODULE-IDENTITY invocation of IANA-maintained MIB modules with the 1965 exact form still to be determined. 1967 10.) A pointer to the suggested naming conventions in Appendix E 1968 was added to Section 4.1. 1970 11.) In Section 4.2 the phrase "descriptors" was changed to 1971 "descriptors and TC names" to align with the usage in the SMIv2 1972 documents, and a pointer to the suggested naming conventions in 1973 Appendix E was added. 1975 12.) An editorial correction (s/"standard"/standards-track) was 1976 made to Section 4.4. 1978 13.) A typo (s/groups's/group's) was corrected in the first bullet 1979 in Section 4.5. 1981 14.) The third bullet in Section 4.5 was revised to clarify that 1982 IETF standards-track MIB modules are to be registered under the 1983 mgmt subtree and to say (based on experience reported by the RMON 1984 MIB working group chair) that IETF working groups SHOULD NOT 1985 assign top-level OIDs from subtrees delegated to them by IANA. 1987 15.) An editorial change (s/appropriate/acceptable/) was made to 1988 the paragraph of Section 4.6.1.1 that deals with Gauge32 index 1989 objects. 1991 16.) Section 4.6.1.2 was revised to state that (i) the DESCRIPTION 1992 clauses of Counter32/Counter64 objects MUST specify epochs of 1993 discontinuities (other than agent re-initialization) with enough 1994 precision to allow a manager to determine if data is valid and 1995 (ii) discontinuity indicators are the RECOMMENDED way to do this. 1997 17.) A note was added to Section 4.6.1.2 stating that the 1998 Counter64 type MUST be used for objects that would roll over in 1999 less than one hour if Counter32 was used instead and that the 2000 existing rule allowing Counter64 only under those circumstances is 2001 obsolete and should no longer be enforced. 2003 18.) The Utf8String and LongUtf8String TCs were added to the list 2004 of specialized OCTET STRING types mentioned in Section 4.6.1.4. 2006 19.) A typo (s/RowPointerTCs/RowPointer TCs/) was corrected in 2007 Section 4.6.1.5. 2009 20.) A wording change (s/MUST be contiguous/SHOULD be contiguous/) 2010 was made to Section 4.6.1.6 to make it agree with RFC 2578. 2012 21.) A note was added to Section 4.6.1.10 stating that when an 2013 object definition uses an imported TC that could later be extended 2014 (as is the case for some enumerated INTEGER and BITS TCs) then the 2015 value set that must be supported SHOULD be documented if the 2016 object is writeable or is an index of a read-create table. 2018 22.) A typo was corrected in the nroff source that caused the 2019 second line in the second paragraph of Section 4.6.2 to be omitted 2020 from the formatted text. 2022 23.) A note was added to Section 4.6.2 stating that the 2023 DESCRIPTION clause of a read-write object SHOULD document what 2024 happens to the value after a reboot unless the object is a column 2025 in a read-create table with well-defined persistence properties. 2027 24.) A bullet was added to the first list in Section 4.6.3 stating 2028 that IMPLIED SHOULD NOT be used on index objects that might appear 2029 in expansion tables and providing some reasons why using IMPLIED 2030 often does not have the expected benefits. 2032 25.) An editorial change (s/row object/row object (table entry)/) 2033 was made to the second bullet of the second list in Section 4.6.3. 2035 26.) A note was added to Section 4.6.4 explicitly stating that 2036 object definitions SHOULD NOT be registered beneath conformance 2037 group definitions, MODULE-COMPLIANCE definitions, or 2038 AGENT-CAPABILITIES definitions (or vice-versa). 2040 27.) A typo (s/128 OID limitation/128 sub-identifier) was 2041 corrected in the first paragraph of Section 4.6.5. 2043 28.) The second paragraph of Section 4.6.5 was revised to state 2044 that size limitations on index variables that need to be observed 2045 by management software SHOULD be spelled out. 2047 29.) The phrase "second technique" was changed to "fixed time 2048 interval technique" in the last sentence of the of the paragraph 2049 of Section 4.7 that discusses notification throttling. 2051 30.) The phrase "in situations where it is appropriate" was 2052 changed to "when it is applicable" at the end of the bullet in 2053 Section 4.8 that discusses when to write full compliance and 2054 read-only compliance statements. 2056 31.) A paragraph was added to Section 4.8 (just before the 2057 endnote) stating that prerequisite modules and in some cases 2058 specific groups from such modules SHOULD be mentioned in the 2059 compliance statements. 2061 32.) Two typos (s/implemantations/implementations/ and 2062 s/descriptions/descriptors/) were corrected in the fourth 2063 paragraph of Section 4.9. 2065 33.) A typo (s/boilerplace/boilerplate/) was fixed in checklist 2066 item #5 of Appendix A. 2068 34.) An item was added to the checklist in Appendix A requiring 2069 reviewers to check for things in http://www.ietf.org/ID-nits.html 2070 that are not covered elsewhere. This became item #10; the 2071 existing technical content review became item #11. 2073 35.) The default smilint switches in Appendix B were changed from 2074 "-m -s -l 9 -i namelength-32" to "-m -s -l 6 -i namelength-32" at 2075 the request of the authors of the program (currently there are no 2076 level 7, 8, or 9 diagnostics, and it is desired to reserve those 2077 levels for things that are of no concern in an IETF MIB review). 2079 36.) A note was added to Appendix D stating that the DisplayString 2080 TC is no longer permitted for objects that are intended for human 2081 consumption, and the Utf8String and LongUtf8String TCs from 2082 SYSAPPL-MIB were added to the list of standard TCs. 2084 37.) Suggested naming conventions were documented in Appendix E. 2086 38.) Normative references to RFCs 2277 and 2287 were added. 2088 39.) Informative references to RFC 1573 and OPT-IF-MIB were added. 2090 40.) The "Acknowledgements" section was updated. 2092 The following changes were made to to produce : 2096 1.) The following changes were made to avoid the implication that 2097 reviews are required only for OPS Area MIB documents: 2098 Section 1: s/OPS area review/expert review/ 2099 Section 4.2: s/OPS Area MIB reviewers/MIB reviewers/ 2100 Section 4.8: s/OPS Area MIB reviewers/MIB reviewers/ 2102 2.) Imperatives from RFC 2119 were capitalized in the following 2103 places: Section 3.2 (last paragraph), Section 3.8 (first 2104 paragraph), Section 4.9 (first bullet in first paragraph), and 2105 Appendix A (checklist item #7). 2107 3.) The EDITOR'S NOTE in Section 3.8 was replaced with text 2108 describing the actual form of the copyright notice that is now 2109 required for IANA-maintained MIB modules. 2111 4.) In Sections 4.1 & 4.2: s/Appendix E/Appendix C/ (appendices 2112 were renumbered owing to the elimination of -01 appendices B & C). 2114 5.) Two typographical errors (s/the the/the/, 2115 s/ifCounterDisconuityTime/ifCounterDiscontinuityTime/) were 2116 corrected in the first bullet of Section 4.6.1.2. 2118 6.) In Section 4.6.1.10 a pointer was added to the "Common TCs" 2119 page (http://www.ops.ietf.org/mib-common-tcs.html) on the OPS Area 2120 web site. 2122 7.) A "DISPLAY-HINT Clause" section was added; it is Section 2123 4.6.3 in the -02 draft. The following section numbers have 2124 changed as a result of this addition: 2126 -01 section number -02 section number 2127 4.6.3 4.6.4 2128 4.6.4 4.6.5 2129 4.6.5 4.6.6 2131 8.) A typographical error (s/are can be/can be/) was corrected in 2132 Section 4.6.4 (formerly Section 4.6.3). 2134 9.) In Sections 4.6.5 (formerly 4.6.4) and 4.7 a pointer to the 2135 new "Suggested OID Layout" appendix was added (it is Appendix D in 2136 the -02 draft, owing to the elimination of -01 appendices B & C). 2138 10.) In Section 4.7 the notification throttling text was 2139 wordsmithed. 2141 11.) A typographical error (s/following contains the/following/) 2142 was corrected in the third paragraph of Section 4.8. 2144 12.) The text of Section 4.9, third paragraph, first bullet and 2145 fifth paragraph, first bullet was revised to allow changes to BITS 2146 and enum labels in order to correct typographical errors. 2148 13.) The text of Section 4.9, third paragraph, second bullet was 2149 revised to allow redundant range or size constraints to be 2150 removed. 2152 14.) In the last paragraph of Section 4.9 the references to 2153 smidiff and -01 Appendix B were replaced by a pointer to the "MIB 2154 Review Tools" page (http://www.ops.ietf.org/mib-review-tools.html) 2155 on the OPS Area web site. 2157 15.) The text of Appendix A, checklist item #7 was corrected to 2158 reflect actual IESG policy on publication of initial versions of 2159 IANA-maintained MIB modules in RFCs. It is now consistent with 2160 Section 3.7. 2162 16.) In Appendix A draft -01 checklist items #9, #10, and #11 were 2163 consolidated into -02 checklist items #9 (which is equivalent to 2164 -01 checklist item #10) and #10 (which is equivalent to the union 2165 of -01 items #9 and #11). The new item #10 consolidates the MIB 2166 compilation step into the technical review, and replaces mention 2167 of specific MIB compilation tools with a pointer to the "MIB 2168 Review Tools" page (http://www.ops.ietf.org/mib-review-tools.html) 2169 on the OPS Area web site. 2171 17.) Draft -01 appendices B and C have been eliminated. They have 2172 been superseded by the "MIB Review Tools" page on the OPS Area web 2173 site (http://www.ops.ietf.org/mib-review-tools.html). The 2174 following appendix names have changed as a result: 2176 -01 appendix name -02 appendix name 2177 Appendix D Appendix B 2178 Appendix E Appendix C 2180 18.) A new "Suggested OID Layout" appendix was added. It is 2181 Appendix D in the -02 draft, owing to the elimination of -01 2182 appendices B & C. 2184 The following changes were made to to produce : 2188 1.) The title was changed to "Guidelines for Authors and 2189 Reviewers of MIB Documents". 2191 2.) The I-D boilerplate on the front page was updated to conform 2192 to the requirements set forth in RFCs 3667 and 3668. 2194 3.) Comments were redirected to . 2196 4.) All occurrences of http://www.ietf.org/ID-nits.html were 2197 changed to http://www.ietf.org/ID-Checklist.html. 2199 5.) Section 3.2 was revised to require mention in the overview 2200 section when definitions are imported from other modules apart 2201 from the modules defined in the SMIv2 documents. 2203 6.) The instructions for IPR notices in Section 3.4 (and also 2204 those in Appendix A) now refer to RFC 3668 instead of RFC 2026. 2206 7.) In Section 3.5 the [RFC2223bis] section number reference was 2207 updated to match , and text 2208 was added (a) to point out that RFC Editor policy prohibits 2209 uncited references and (b) to require citations in the narrative 2210 part of documents other than the SMIv2 RFCs that contain imported 2211 definitions. 2213 8.) In Section 3.5 the pointer to [RFC2223bis] was removed and 2214 text was added to remind authors to consider privacy implications. 2216 9.) The IANA Considerations instructions in Section 3.7 were 2217 changed to comply with the new IESG policy requiring an IANA 2218 Consideridations section in all Internet-Drafts. Subsection 2219 headings were added to cover the three different cases. The 2220 pointer to [RFC2223bis] was removed. 2222 10.) The instructions for copyright notices in Section 3.8 were 2223 changed to refer to RFC 3667 instead of RFC 2026, and the pointer 2224 to [RFC2223bis] was removed. 2226 11.) A minor wording change was made to Section 4.1. 2228 12.) In Section 4.5 text was added admonishing authors NOT to use 2229 SMI numbers that have not been properly allocated by the IANA. 2231 13.) Sections 4.6.1.1 and 4.6.1.6 now mention that DEFVALS for 2232 enumerated INTEGER and BITS objects may, according to the SMI, be 2233 specified either by label or by value, but since some tools do not 2234 accept the numeric form, the label form is preferred. 2236 14.) Section 4.9 was clarified to state that adding an OBJECT 2237 clause specifying support for the original set of values of an 2238 enumerated INTEGER or BITS object is needed only when write access 2239 is required by the compliance statement. 2241 15.) Several TCs have been added to Appendix B. These include the 2242 TCs that were recently added to the INET-ADDRESS-MIB, the 2243 PhysicalIndex and PhysicalIndexOrZero TCs from the recent update 2244 of the ENTITY-MIB, and all of the TCs from the HC-PerfHist-TC-MIB. 2246 16.) The reference to RFC 2026 was replaced by references to RFCs 2247 3667 and 3668, all references to I-Ds that have since been 2248 published have been changed to point to the RFCs, and the 2249 references to RFC 2737 and RFC 3291 were replaced by references to 2250 the I-Ds that update those documents. Note that RFC2737bis and 2251 RFC3291bis are both normative references since Appendix B lists 2252 some TCs from those drafts that are available nowhere else. 2254 17.) An IANA Considerations section (to be removed upon 2255 publication) was added, and the Open Issues section was removed. 2257 The following changes were made to to produce : 2261 1.) The I-D boilerplate on the front page was updated to comply 2262 with http://www.ietf.org/ietf/1id-guidelines.txt. 2264 2.) The introductory part of Section 3 has been wordsmithed to 2265 align it with http://www.ietf.org/ietf/1id-guidelines.txt, 2266 http://www.ietf.org/ID-Checklist.html, and RFC2223bis, and the 2267 sub-sections have been re-ordered to match the order recommended 2268 by RFC 2223bis for sections in an RFC. As a result, the following 2269 section numbers have changed: 2271 -03 Section Number -04 Section Number 2272 3.4 3.8 2273 3.5 3.6 2274 3.6 3.4 2275 3.7 3.5 2276 3.8 3.7 2278 3.) The instructions for copyright notices in Section 3.7 (and 2279 also those in Appendix A) refer to RFC 3907 instead of RFC 3667, 2280 and the wording for the abbreviated notice used in IANA-maintained 2281 was changed so that it agrees with RFC 3907. In addition, the 2282 requirement to check for the presence of a copyright notice on the 2283 front page of a document has been deleted from Appendix A, since 2284 Internet-Drafts no longer require such a notice. 2286 4.) The instructions for IPR notices in Section 3.8 (and also 2287 those in Appendix A) now refer to RFC 3908 instead of RFC 3668. 2288 In addition, these sections treat the notice as a SHOULD, since 2289 the IPR notice is no longer required in Internet-Drafts (although 2290 it is recommended) 2292 5.) Text has been added to Section 4.6.1.2 to clarify that there 2293 is no longer a requirement to define a Counter32 counterpart for 2294 each Counter64 object. 2296 6.) In Section 4.6.4 the presence of a RowStatus column in a 2297 read-create table was changed from a MUST to a SHOULD. 2299 7.) Text has been added to Section 4.6.4 to clarify that an 2300 augmenting row does not need a RowStatus or StorageType column 2301 when the base row has such a column. 2303 8.) The Acknowledgments, Security Considerations, and IANA 2304 Considerations sections have been relocated before the appendices, 2305 as recommended by RFC 2223bis, and the Intellectual Property 2306 Section has been relocated to the end of the document, as 2307 recommended by RFC 2223bis (and in accordance with the practice in 2308 recent RFCs). 2310 9.) Several previously unacknowledged individuals who have 2311 provided helpful comments have been named in the Acknowledgments 2312 section. 2314 10.) The IANA Considerations section is now non-null, and the 2315 editor's note requesting that it be removed prior to publication 2316 has been deleted. 2318 11.) The checklist items in Appendix A have been re-ordered to 2319 match the order of presentation in Section 3. 2321 12.) Appendix B now has a note to the effect that TDomain and 2322 TAddress SHOULD NOT be used in new MIB modules, and it now 2323 correctly lists the SYNTAX of InetAddressPrefixLength as 2324 Unsigned32 (0..2040). 2326 13.) The references to RFCs 3667 and 3668 were replaced by 2327 references to RFCs 3907 and 3908, the references to RFC 2223bis, 2328 RFC 2737bis and RFC 3291bis were updated to point to the most 2329 current drafts, RFC 2223bis was changed from a normative reference 2330 to an informative reference, and the reference list was 2331 re-organized. 2333 14.) Several typos and spelling errors were corrected. 2335 ************************************************************ 2336 * NOTES TO RFC Editor (to be removed prior to publication) * 2337 * * 2338 * 1.) Please remove the "Revision History" section. * 2339 * * 2340 * 2.) The normative reference [RFC3291bis] points to * 2341 * a work in progress that is intended to replace RFC * 2342 * 3291. Please update that reference to point to the * 2343 * forthcoming RFC that replaces RFC 3291, replace all * 2344 * occurrences of "3291bis" with the number of that RFC. * 2345 * * 2346 * 3.) The normative reference [RFC2737bis] points to * 2347 * a work in progress that is intended to replace RFC * 2348 * 2737. Please update that reference to point to the * 2349 * forthcoming RFC that replaces RFC 2737, replace all * 2350 * occurrences of "2737bis" with the number of that RFC. * 2351 * * 2352 * 4.) The informative reference [RFC2223bis] points to * 2353 * a work in progress that is intended to replace RFC * 2354 * 2223. If that document is published as an RFC prior to * 2355 * this document, please update that reference to point to * 2356 * forthcoming RFC that replaces RFC 2223, replace all * 2357 * occurrences of "2223bis" with the number of the new RFC, * 2358 * and update the RFC2223bis section number references in * 2359 * this document as necessary. * 2360 * * 2361 * 5.) The informative references [RFC1573], [RFC1595], and * 2362 * [RFC2558] refer to obsolete documents. This was done * 2363 * deliberately to provide historical examples of specific * 2364 * types of MIB module revisions. These references should * 2365 * NOT be updated to point to the most current RFC. * 2366 * * 2367 * 6.) The "Editor's Notes" and "Notes to RFC Editor" in * 2368 * Sections 3.5, 3.7, and 4.5 are examples to authors and * 2369 * are intended to appear in the final text. * 2370 ************************************************************