idnits 2.17.1 draft-ietf-netmod-smi-yang-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 20, 2012) is 4388 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 6021 (Obsoleted by RFC 6991) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schoenwaelder 3 Internet-Draft Jacobs University 4 Intended status: Standards Track April 20, 2012 5 Expires: October 22, 2012 7 Translation of SMIv2 MIB Modules to YANG Modules 8 draft-ietf-netmod-smi-yang-05 10 Abstract 12 YANG is a data modeling language used to model configuration and 13 state data manipulated by the NETCONF protocol, NETCONF remote 14 procedure calls, and NETCONF notifications. The Structure of 15 Management Information (SMIv2) defines fundamental data types, an 16 object model, and the rules for writing and revising MIB modules for 17 use with the SNMP protocol. This document defines a translation of 18 SMIv2 MIB modules into YANG modules, enabling read-only (config 19 false) access to data objects defined in SMIv2 MIB modules via 20 NETCONF. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on October 22, 2012. 39 Copyright Notice 41 Copyright (c) 2012 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 This document may contain material from IETF Documents or IETF 55 Contributions published or made publicly available before November 56 10, 2008. The person(s) controlling the copyright in some of this 57 material may not have granted the IETF Trust the right to allow 58 modifications of such material outside the IETF Standards Process. 59 Without obtaining an adequate license from the person(s) controlling 60 the copyright in such materials, this document may not be modified 61 outside the IETF Standards Process, and derivative works of it may 62 not be created outside the IETF Standards Process, except to format 63 it for publication as an RFC or to translate it into languages other 64 than English. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. Mapping of Well Known Types . . . . . . . . . . . . . . . . . 5 70 3. Translation of SMIv2 Modules and SMIv2 IMPORT Clauses . . . . 6 71 3.1. Example: IMPORTS of IF-MIB . . . . . . . . . . . . . . . . 7 72 4. Translation of the MODULE-IDENTITY Macro . . . . . . . . . . . 8 73 4.1. MODULE-IDENTITY Translation Rules . . . . . . . . . . . . 8 74 4.2. Example: MODULE-IDENTITY of IF-MIB . . . . . . . . . . . . 9 75 5. Translation of the TEXTUAL-CONVENTION Macro . . . . . . . . . 10 76 5.1. TEXTUAL-CONVENTION Translation Rules . . . . . . . . . . . 10 77 5.2. Example: OwnerString and InterfaceIndex of IF-MIB . . . . 11 78 5.3. Example: IfDirection of the DIFFSERV-MIB . . . . . . . . . 11 79 6. Translation of OBJECT IDENTIFIER Assignments . . . . . . . . . 13 80 7. Translation of the OBJECT-TYPE Macro . . . . . . . . . . . . . 14 81 7.1. Scalar and Columnar Object Translation Rules . . . . . . . 14 82 7.2. Example: ifNumber and ifIndex of the IF-MIB . . . . . . . 15 83 7.3. Non-Augmenting Conceptual Table Translation Rules . . . . 16 84 7.4. Example: ifTable of the IF-MIB . . . . . . . . . . . . . . 18 85 7.5. Example: ifRcvAddressTable of the IF-MIB . . . . . . . . . 18 86 7.6. Example: alHostTable of the RMON2-MIB . . . . . . . . . . 20 87 7.7. Augmenting Conceptual Tables Translation Rules . . . . . . 21 88 7.8. Example: ifXTable of the IF-MIB . . . . . . . . . . . . . 22 89 8. Translation of the OBJECT-IDENTITY Macro . . . . . . . . . . . 24 90 8.1. OBJECT-IDENTITY Translation Rules . . . . . . . . . . . . 24 91 8.2. Example: diffServTBParamSimpleTokenBucket of the 92 DIFFSERV-MIB . . . . . . . . . . . . . . . . . . . . . . . 24 93 9. Translation of the NOTIFICATION-TYPE Macro . . . . . . . . . . 25 94 9.1. NOTIFICATION-TYPE Translation Rules . . . . . . . . . . . 25 95 9.2. Example: linkDown NOTIFICATION-TYPE of IF-MIB . . . . . . 25 96 10. YANG Language Extension Definition . . . . . . . . . . . . . . 28 97 11. Implementing Configuration Data Nodes . . . . . . . . . . . . 32 98 11.1. Example: addressMapControlTable of RMON2-MIB . . . . . . . 32 99 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 100 13. Security Considerations . . . . . . . . . . . . . . . . . . . 36 101 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 37 102 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 38 103 15.1. Normative References . . . . . . . . . . . . . . . . . . . 38 104 15.2. Informative References . . . . . . . . . . . . . . . . . . 38 105 Appendix A. Mapping of Well Known Types (normative) . . . . . . . 40 106 Appendix B. Module Prefix Generation (informative) . . . . . . . 43 107 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 44 109 1. Introduction 111 This document describes a translation of SMIv2 [RFC2578], [RFC2579], 112 [RFC2580] MIB modules into YANG [RFC6020] modules, enabling read-only 113 (config false) access to SMIv2 objects defined in SMIv2 MIB modules 114 via NETCONF [RFC6241]. For a discussion why SMIv2 read-write or 115 read-create objects are translated to read-only (config false) YANG 116 objects, see Section 11. 118 YANG modules generated from SMIv2 modules should not be modified. 119 Any necessary changes should be made by modifying the original SMIv2 120 modules (with proper updates of the SMIv2 LAST-UPDATED and REVISION 121 clauses) and then running the translation defined in this memo again. 122 Note that this does not affect the usage of YANG augments and or YANG 123 deviations: YANG modules generated from SMIv2 modules can be 124 augmented and like any other YANG module and YANG deviations can be 125 used to document how an implementation deviates from the generated 126 YANG module. 128 SMIv1 modules can be converted to YANG by first following the rules 129 in [RFC3584] to convert the SMIv1 module to SMIv2 and then following 130 the rules in this document to convert the obtained SMIv2 module to 131 YANG. 133 The SMIv2 to YANG mapping is illustrated by examples showing the 134 translation of parts of the IF-MIB [RFC2863], the DIFFSERV-MIB 135 [RFC3289], and the RMON2-MIB [RFC4502] SMIv2 module. 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 139 "OPTIONAL" in this document are to be interpreted as described in BCP 140 14, [RFC2119]. 142 2. Mapping of Well Known Types 144 The SMIv2 base types and some well known derived textual conventions 145 are mapped to YANG types according to Appendix A. The mapping of the 146 OCTET STRING depends on the context. If an OCTET STRING type has an 147 associated DISPLAY-HINT, then the corresponding YANG base type is the 148 string type. Otherwise, the binary type is used. Similarly, the 149 mapping of the INTEGER type depends on its usage as an enumeration or 150 a 32-bit integral type. Implementations should provide 151 implementation specific options to handle situations where DISPLAY- 152 HINTs are added during a revision of a module and backwards 153 compatibility must be preserved, i.e., an added DISPLAY-HINT needs to 154 be ignored. 156 The mappings shown in Appendix A may require to import the ietf-yang- 157 types, ietf-inet-types, or ietf-yang-smiv2 YANG modules since some 158 SMIv2 types and textual conventions map to YANG types defined in the 159 ietf-yang-types and ietf-inet-types YANG modules defined in [RFC6021] 160 and the ietf-yang-smiv2 YANG module defined in this document. 161 Implementations MUST add any additional imports required by the type 162 mapping. 164 3. Translation of SMIv2 Modules and SMIv2 IMPORT Clauses 166 SMIv2 modules are mapped to corresponding YANG modules. The 167 generated YANG module name MUST be the same as the SMIv2 module name. 169 The YANG namespace MUST be constructed out of the IANA registered 170 prefix urn:ietf:params:xml:ns:yang:smiv2: (see Section 12) followed 171 by the SMIv2 module name. Since SMIv2 module names can be assumed to 172 be unique (see Section 3 in [RFC2578]), the resulting YANG namespace 173 is unique. 175 The YANG prefix MAY be derived from the SMIv2 module name using the 176 module prefix generation algorithm described in Appendix B. The YANG 177 prefix is supposed to be short and it must be unique within the set 178 of all prefixes used by a YANG module. The algorithm described in 179 Appendix B generates such prefixes. 181 SMIv2 IMPORT clauses are translated to YANG import statements. One 182 major difference between the SMIv2 import mechanism and the YANG 183 import mechanism is that SMIv2 IMPORT clauses import specific symbols 184 from an SMIv2 module while the YANG import statement imports all 185 symbols of the referenced YANG module. 187 In order to produce correct and complete YANG import statements, the 188 following rules MUST be used: 190 o Process each item in each SMIv2 IMPORT clause as follows: 192 1. If an import statement for this SMIv2 module has already been 193 generated, then ignore this item. 195 2. Otherwise, if the SMIv2 module name is SNMPv2-SMI or SNMPv2- 196 CONF, then ignore this item. Note that these two modules can 197 be completely ignored since all definitions in these modules 198 are translated by translation rules. 200 3. Otherwise, if this item is a textual convention matching one 201 of the textual conventions in the SMIv2 types column of 202 Appendix A (e.g., MacAddress, PhysAddress, or TimeStamp) then 203 ignore this item. 205 4. Otherwise, if the item is used in a SYNTAX clause of an 206 OBJECT-TYPE whose MAX-ACCESS is not accessible-for-notify, 207 then generate an import statement as described below. 209 5. Otherwise, if the item is used in an OBJECTS clause of a 210 NOTIFICATION-TYPE, then generate an import statement as 211 described below. 213 6. Otherwise, if the item is used in an INDEX or AUGMENTS clause, 214 then generate an import statement as described below. 216 7. Otherwise, ignore this item. Some examples of this case are 217 OBJECT IDENTIFIER assignments and objects that are only 218 referenced in MODULE-COMPLIANCE, OBJECT-GROUP, or 219 NOTIFICATION-GROUP clauses. 221 o Generate any additional import statements as required by the type 222 translations according to the type mapping table Appendix A. This 223 requires the translator to consider all the types used in the 224 SMIv2 module in order to produce the imports. 226 o Generate an import statement for the YANG module ietf-yang-smiv2 227 with the prefix smiv2. 229 The generated import statements use the untranslated SMIv2 module 230 names or the names of well-known YANG modules as their argument. The 231 import statement must contain a prefix statement. The prefixes MAY 232 be generated by applying the module prefix generation algorithm 233 described in Appendix B. 235 3.1. Example: IMPORTS of IF-MIB 237 The translation of the IF-MIB [RFC2863] leads to the YANG module and 238 namespace/prefix statement and the import statements shown below. 239 The prefix is the translation of the SMIv2 module name IF-MIB to 240 lowercase (consisting of two tokens and thus no further 241 abbreviation). 243 module IF-MIB { 245 namespace "urn:ietf:params:xml:ns:yang:smiv2:IF-MIB"; 246 prefix "if-mib"; 248 import IANAifType-MIB { prefix "ianaiftype-mib"; } 249 import SNMPv2-TC { prefix "snmpv2-tc"; } 250 import ietf-yang-types { prefix "yang"; } 251 import ietf-yang-smiv2 { prefix "smiv2"; } 252 } 254 4. Translation of the MODULE-IDENTITY Macro 256 The SMIv2 requires an invocation of the MODULE-IDENTITY macro to 257 provide contact and revision history for a MIB module. The clauses 258 of the SMIv2 MODULE-IDENTITY macro MUST be translated into YANG 259 statements as detailed below. 261 4.1. MODULE-IDENTITY Translation Rules 263 o The SMIv2 ORGANIZATION clause is mapped to the YANG organization 264 statement. 266 o The SMIv2 CONTACT-INFO clause is mapped to the YANG contact 267 statement. 269 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 270 statement. 272 o Each SMIv2 REVISION clause is mapped to a YANG revision statement. 273 The revision is identified by the date argument of the SMIv2 274 REVISION clause. DESCRIPTION sub-clauses of REVISION clauses are 275 mapped to corresponding description statement nested in revision 276 clauses. 278 o The SMIv2 LAST-UPDATED clause is ignored if the associated date 279 matches a REVISION clause. Otherwise, an additional revision 280 statement is generated. 282 o A top-level YANG container is generated. The container's name is 283 the SMIv2 module name and the container MUST be config false. The 284 generation of the top-level container MAY be skipped if the SMIv2 285 module does not define any objects that go into the top-level 286 container (e.g., an SMIv2 module only defining textual 287 conventions). 289 o The object identifier value of the invocation of the SMIv2 MODULE- 290 IDENTITY is translated into an smiv2:oid statement contained in an 291 smiv2:alias statement representing the MODULE-IDENTITY macro 292 invocation. Refer to the YANG extension defined in Section 10. 294 While all proper SMIv2 modules must have exactly one MODULE-IDENTITY 295 macro invocation, there are a few notable exceptions. The modules 296 defining the SMIv2 language (i.e., the SNMPv2-SMI, SNMPv2-TC, and 297 SNMPv2-CONF modules) do not invoke the MODULE-IDENTITY macro. 298 Furthermore, SMIv2 modules generated from SMIv1 modules may miss an 299 invocation of the MODULE-IDENTITY macro as well. In such cases, it 300 is preferable to not generate organization, contact, description, and 301 revision statements. 303 4.2. Example: MODULE-IDENTITY of IF-MIB 305 The translation of the MODULE-IDENTITY of the IF-MIB [RFC2863] leads 306 to the following YANG statements: 308 organization 309 "IETF Interfaces MIB Working Group"; 311 contact 312 "Keith McCloghrie 313 Cisco Systems, Inc. 314 170 West Tasman Drive 315 San Jose, CA 95134-1706 316 US 318 408-526-5260 319 kzm@cisco.com"; 321 description 322 "The MIB module to describe generic objects for network 323 interface sub-layers. This MIB is an updated version of 324 MIB-II's ifTable, and incorporates the extensions defined in 325 RFC 1229."; 327 revision "2000-06-14" { 328 description 329 "Clarifications agreed upon by the Interfaces MIB WG, and 330 published as RFC 2863."; 331 } 332 revision "1996-02-28" { 333 description 334 "Revisions made by the Interfaces MIB WG, and published in 335 RFC 2233."; 336 } 337 revision "1993-11-08" { 338 description 339 "Initial revision, published as part of RFC 1573."; 340 } 342 container IF-MIB { 343 config false; 344 } 346 5. Translation of the TEXTUAL-CONVENTION Macro 348 The SMIv2 uses invocations of the TEXTUAL-CONVENTION macro to define 349 new types derived from the SMIv2 base types. Invocations of the 350 TEXTUAL-CONVENTION macro MUST be translated into YANG typedef 351 statements as detailed below. 353 5.1. TEXTUAL-CONVENTION Translation Rules 355 The name of the TEXTUAL-CONVENTION macro invocation is used as the 356 name of the generated typedef statement. The clauses of the SMIv2 357 TEXTUAL-CONVENTION macro are mapped to YANG statements embedded in 358 the typedef statement as follows: 360 o The SMIv2 DISPLAY-HINT clause is used to determine the type 361 mapping of types derived form the OCTET STRING type as explained 362 in Section 2. Furthermore, the DISPLAY-HINT value MAY be used to 363 generate a regular expression for the YANG pattern statement 364 within the type statement. 366 o The SMIv2 DISPLAY-HINT is translated into an smiv2:display-hint 367 statement. Refer to the YANG extension defined in Section 10. 369 o The SMIv2 STATUS clause is mapped to the YANG status statement. 370 The generation of the YANG status statement is skipped if the 371 value of the STATUS clause is current. 373 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 374 statement. 376 o The SMIv2 REFERENCE clause is mapped to the YANG reference 377 statement. 379 o The SMIv2 SYNTAX clause is mapped to the YANG type statement. 380 SMIv2 range restrictions are mapped to YANG range statements while 381 SMIv2 length restrictions are mapped to YANG length statements. 382 SMIv2 INTEGER enumerations are mapped to YANG enum/value 383 statements. SMIv2 BITS are mapped to YANG bit/position 384 statements. For OCTET STRING types that are mapped to a YANG 385 string base type (see Section 2), the length specified in the YANG 386 length statement must be consistent with the stringified 387 representation of values. If an implementation is unable to 388 derive a proper length restrictions, then the YANG length 389 statement MUST be omitted. 391 This translation assumes that labels of named numbers and named bits 392 do not change when an SMIv2 module is revised. This is consistent 393 with the clarification of the SMIv2 module revision rules in Section 394 4.9 of [RFC4181]. 396 5.2. Example: OwnerString and InterfaceIndex of IF-MIB 398 The translations of the OwnerString and InterfaceIndex textual 399 conventions of the IF-MIB [RFC2863] are shown below. 401 typedef OwnerString { 402 type string { 403 length "0..255"; 404 pattern '\p{IsBasicLatin}{0,255}'; 405 } 406 status deprecated; 407 description 408 "This data type is used to model an administratively 409 assigned name of the owner of a resource. This information 410 is taken from the NVT ASCII character set. It is suggested 411 that this name contain one or more of the following: ASCII 412 form of the manager station's transport address, management 413 station name (e.g., domain name), network management 414 personnel's name, location, or phone number. In some cases 415 the agent itself will be the owner of an entry. In these 416 cases, this string shall be set to a string starting with 417 'agent'."; 418 smiv2:display-hint "255a"; 419 } 421 typedef InterfaceIndex { 422 type int32 { 423 range "1..2147483647"; 424 } 425 description 426 "A unique value, greater than zero, for each interface or 427 interface sub-layer in the managed system. It is 428 recommended that values are assigned contiguously starting 429 from 1. The value for each interface sub-layer must remain 430 constant at least from one re-initialization of the entity's 431 network management system to the next re-initialization."; 432 smiv2:display-hint "d"; 433 } 435 5.3. Example: IfDirection of the DIFFSERV-MIB 437 The translation of the IfDirection textual convention of the 438 DIFFSERV-MIB [RFC3289] is shown below. 440 typedef IfDirection { 441 type enumeration { 442 enum inbound { value 1; } 443 enum outbound { value 2; } 444 } 445 description 446 "IfDirection specifies a direction of data travel on an 447 interface. 'inbound' traffic is operated on during reception from 448 the interface, while 'outbound' traffic is operated on prior to 449 transmission on the interface."; 450 } 452 6. Translation of OBJECT IDENTIFIER Assignments 454 The SMIv2 uses OBJECT IDENTIFIER assignments to introduce names for 455 intermediate nodes in the OBJECT IDENTIFIER tree. OBJECT IDENTIFIER 456 assignments are translated into smiv2:alias statements. Refer to the 457 YANG extension defined in Section 10. 459 7. Translation of the OBJECT-TYPE Macro 461 The SMIv2 uses the OBJECT-TYPE macro to define objects and the 462 structure of conceptual tables. Objects exist either as scalars 463 (exactly one instance within an SNMP context) or columnar objects 464 within conceptual tables (zero or multiple instances within an SNMP 465 context). A number of auxiliary objects define the index (key) of a 466 conceptual table. Furthermore, conceptual tables can be augmented by 467 other conceptual tables. All these differences must be taken into 468 account when translating SMIv2 OBJECT-TYPE macro invocations to YANG. 469 Invocations of the OBJECT-TYPE macro MUST be translated into YANG 470 statements as detailed below. 472 7.1. Scalar and Columnar Object Translation Rules 474 SMIv2 OBJECT-TYPE macro invocations defining scalars or columnar 475 objects with a MAX-ACCESS of "not-accessible", "read-only", 476 "read-write" and "read-create" are translated to YANG leaf 477 statements. Additionally, columnar objects with a MAX-ACCESS of 478 accessible-for-notify are translated to YANG leaf statements if that 479 columnar object is part of the INDEX clause of the table containing 480 that columnar object. The name of the leaf is the name associated 481 with the SMIv2 OBJECT-TYPE macro invocation. SMIv2 OBJECT-TYPE macro 482 invocations with a MAX-ACCESS of "accessible-for-notify" are not 483 translated to YANG data tree leafs but instead into YANG notification 484 leafs. 486 Leaf statements for scalar objects are created in a container 487 representing the scalar's parent node in the OID tree. This 488 container is named after the scalar's parent node in the OID tree and 489 placed in the top-level container representing the SMIv2 module, see 490 Section 4.1. In the rare case that the scalar's parent node has 491 multiple names, the automatic translation MUST fail with an error and 492 the name clash needs to be investigated and fixed manually. In case 493 a previous revision of the SMIv2 module did not have an ambiguity, 494 then the name used by the previous revision MUST be used. The leaf 495 statements representing columnar objects are created in the list 496 representing a conceptual row, see Section 7.3. 498 o The SMIv2 SYNTAX clause is mapped to the YANG type statement. 499 SMIv2 range restrictions are mapped to YANG range statements while 500 SMIv2 length restrictions are mapped to YANG length statements. 501 SMIv2 INTEGER enumerations are mapped to YANG enum/value 502 statements. SMIv2 BITS are mapped to YANG bit/position 503 statements. For OCTET STRING types that are mapped to a YANG 504 string base type (see Section 2), the length specified in the YANG 505 length statement must be consistent with the stringified 506 representation of values. If an implementation is unable to 507 derive a proper length restrictions, then the YANG length 508 statement MUST be omitted. 510 o The SMIv2 UNITS clause is mapped to the YANG units statement. 512 o The SMIv2 MAX-ACCESS is translated into an smiv2:max-access 513 statement. Refer to the YANG extension defined in Section 10. 515 o The SMIv2 STATUS clause is mapped to the YANG status statement. 516 The generation of the YANG status statement is skipped if the 517 value of the STATUS clause is current. 519 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 520 statement. 522 o The SMIv2 REFERENCE clause is mapped to the YANG reference 523 statement. 525 o The SMIv2 DEFVAL clause is mapped to an smiv2:defval statement. 526 Refer to the YANG extension defined in Section 10. 528 o The value of the SMIv2 OBJECT-TYPE macro invocation is translated 529 into an smiv2:oid statement. Refer to the YANG extension defined 530 in Section 10. 532 This translation assumes that labels of named numbers and named bits 533 do not change when an SMIv2 module is revised. This is consistent 534 with the clarification of the SMIv2 module revision rules in Section 535 4.9 of [RFC4181]. 537 7.2. Example: ifNumber and ifIndex of the IF-MIB 539 The translations of the ifNumber scalar object and the ifIndex 540 columnar object of the IF-MIB [RFC2863] are shown below. Since 541 ifNumber is a scalar object in the interfaces branch of the IF-MIB, 542 the YANG leaf ifNumber will be placed in a YANG container called 543 interfaces, which is registered in the top-level container IF-MIB. 545 leaf ifNumber { 546 type int32; 547 description 548 "The number of network interfaces (regardless of their 549 current state) present on this system."; 550 smiv2:max-access "read-only"; 551 smiv2:oid "1.3.6.1.2.1.2.1"; 552 } 554 leaf ifIndex { 555 type if-mib:InterfaceIndex; 556 description 557 "A unique value, greater than zero, for each interface. It 558 is recommended that values are assigned contiguously 559 starting from 1. The value for each interface sub-layer 560 must remain constant at least from one re-initialization of 561 the entity's network management system to the next re- 562 initialization."; 563 smiv2:max-access "read-only"; 564 smiv2:oid "1.3.6.1.2.1.2.2.1.1"; 565 } 567 7.3. Non-Augmenting Conceptual Table Translation Rules 569 An OBJECT-TYPE macro invocation defining a non-augmenting conceptual 570 table is translated to a YANG container statement using the name of 571 the OBJECT-TYPE macro invocation. This container is created in the 572 top-level container representing the SMIv2 module. The clauses of 573 the macro are translated as follows: 575 o The SMIv2 SYNTAX clause is ignored 577 o The SMIv2 UNITS clause is ignored. 579 o The SMIv2 MAX-ACCESS clause is ignored. 581 o The SMIv2 STATUS clause is mapped to the YANG status statement. 582 The generation of the YANG status statement is skipped if the 583 value of the STATUS clause is current. 585 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 586 statement. 588 o The SMIv2 REFERENCE clause is mapped to the YANG reference 589 statement. 591 o The value of the SMIv2 OBJECT-TYPE macro invocation is translated 592 into an smiv2:oid statement. Refer to the YANG extension defined 593 in Section 10. 595 An OBJECT-TYPE macro invocation defining a conceptual row is 596 translated to a YANG list statement. It is contained in the YANG 597 container representing the conceptual table. The generated list uses 598 the name of the row OBJECT-TYPE macro invocation. The clauses of the 599 OBJECT-TYPE macro are translated as follows: 601 o The SMIv2 SYNTAX clause is ignored. 603 o The SMIv2 UNITS clause is ignored. 605 o The SMIv2 MAX-ACCESS clause is ignored. 607 o The SMIv2 STATUS clause is mapped to the YANG status statement. 608 The generation of the YANG status statement is skipped if the 609 value of the STATUS clause is current. 611 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 612 statement. 614 o The SMIv2 REFERENCE clause is mapped to the YANG reference 615 statement. 617 o The SMIv2 INDEX clause is mapped to the YANG key clause listing 618 the columnar objects forming the key of the YANG list. If the 619 same object appears more than once in the INDEX clause, append 620 '_' to the duplicate object name(s) where '' counts the 621 occurances of the object in the INDEX clause, starting from 2. 622 Additional leaf statements must be created to define the leafs 623 introduced. 625 o If the SMIv2 INDEX clause contains the IMPLIED keyword, then an 626 smiv2:implied statement is generated to record the name of the 627 object preceded by the IMPLIED keyword. Refer to the YANG 628 extension defined in Section 10. 630 o The value of the SMIv2 OBJECT-TYPE macro invocation is translated 631 into an smiv2:oid statement. Refer to the YANG extension defined 632 in Section 10. 634 Within the list statement, YANG leaf statements are created for 635 columnar objects as described in Section 7.1. For objects listed in 636 the SMIv2 INDEX clause that are not part of the conceptual table 637 itself, YANG leaf statements of type leafref pointing to the 638 referenced definition are created. 640 7.4. Example: ifTable of the IF-MIB 642 The translation of the definition of the ifTable of the IF-MIB 643 [RFC2863] is shown below. 645 container ifTable { 646 description 647 "A list of interface entries. The number of entries is 648 given by the value of ifNumber."; 649 smiv2:oid "1.3.6.1.2.1.2.2"; 651 list ifEntry { 652 key "ifIndex"; 653 description 654 "An entry containing management information applicable to a 655 particular interface."; 656 smiv2:oid "1.3.6.1.2.1.2.2.1"; 658 leaf ifIndex { 659 type if-mib:InterfaceIndex; 660 description 661 "A unique value, greater than zero, for each interface. It 662 is recommended that values are assigned contiguously 663 starting from 1. The value for each interface sub-layer 664 must remain constant at least from one re-initialization of 665 the entity's network management system to the next re- 666 initialization."; 667 smiv2:max-access "read-only"; 668 smiv2:oid "1.3.6.1.2.1.2.2.1.1"; 669 } 671 // ... 672 } 673 } 675 7.5. Example: ifRcvAddressTable of the IF-MIB 677 The translation of the definition of the ifRcvAddressTable of the IF- 678 MIB [RFC2863] is shown below. 680 container ifRcvAddressTable { 681 description 682 "This table contains an entry for each address (broadcast, 683 multicast, or uni-cast) for which the system will receive 684 packets/frames on a particular interface, except as follows: 686 - for an interface operating in promiscuous mode, entries 687 are only required for those addresses for which the system 688 would receive frames were it not operating in promiscuous 689 mode. 691 - for 802.5 functional addresses, only one entry is 692 required, for the address which has the functional address 693 bit ANDed with the bit mask of all functional addresses for 694 which the interface will accept frames. 696 A system is normally able to use any unicast address which 697 corresponds to an entry in this table as a source address."; 698 smiv2:oid "1.3.6.1.2.1.31.1.4"; 700 list ifRcvAddressEntry { 701 key "ifIndex ifRcvAddressAddress"; 702 description 703 "A list of objects identifying an address for which the 704 system will accept packets/frames on the particular 705 interface identified by the index value ifIndex."; 706 smiv2:oid "1.3.6.1.2.1.31.1.4.1"; 708 leaf ifIndex { 709 type leafref { 710 path "/if-mib:IF-MIB/if-mib:ifTable" + 711 "/if-mib:ifEntry/if-mib:ifIndex"; 712 } 713 } 715 leaf ifRcvAddressAddress { 716 type yang:phys-address; 717 description 718 "An address for which the system will accept packets/frames 719 on this entry's interface."; 720 smiv2:max-access "not-accessible"; 721 smiv2:oid "1.3.6.1.2.1.31.1.4.1.1"; 722 } 724 // ... 725 } 726 } 728 7.6. Example: alHostTable of the RMON2-MIB 730 The translation of the definition of the alHostTable of the RMON2-MIB 731 [RFC4502] is shown below. 733 container alHostTable { 734 description 735 "A collection of statistics for a particular protocol from a 736 particular network address that has been discovered on an 737 interface of this device. 739 The probe will populate this table for all protocols in the 740 protocol directory table whose value of 741 protocolDirHostConfig is equal to supportedOn(3), and 742 will delete any entries whose protocolDirEntry is deleted or 743 has a protocolDirHostConfig value of supportedOff(2). 745 The probe will add to this table all addresses 746 seen as the source or destination address in all packets with 747 no MAC errors and will increment octet and packet counts in 748 the table for all packets with no MAC errors. Further, 749 entries will only be added to this table if their address 750 exists in the nlHostTable and will be deleted from this table 751 if their address is deleted from the nlHostTable."; 752 smiv2:oid "1.3.6.1.2.1.16.16.1"; 754 list alHostEntry { 755 key "hlHostControlIndex alHostTimeMark protocolDirLocalIndex " 756 + "nlHostAddress protocolDirLocalIndex_2"; 757 description 758 "A conceptual row in the alHostTable. 760 The hlHostControlIndex value in the index identifies the 761 hlHostControlEntry on whose behalf this entry was created. 762 The first protocolDirLocalIndex value in the index identifies 763 the network-layer protocol of the address. 764 The nlHostAddress value in the index identifies the network- 765 layer address of this entry. 766 The second protocolDirLocalIndex value in the index identifies 767 the protocol that is counted by this entry. 769 An example of the indexing in this entry is 770 alHostOutPkts.1.783495.18.4.128.2.6.6.34. 772 Note that some combinations of index values may result in an 773 index that exceeds 128 sub-identifiers in length, which exceeds 774 the maximum for the SNMP protocol. Implementations should take 775 care to avoid such combinations."; 777 smiv2:oid "1.3.6.1.2.1.16.16.1.1"; 779 // ... 781 leaf protocolDirLocalIndex { 782 type leafref { 783 path "/rmon2-mib:RMON2-MIB/" 784 + "rmon2-mib:protocolDirTable/" 785 + "rmon2-mib:protocolDirEntry/" 786 + "rmon2-mib:protocolDirLocalIndex"; 787 } 788 } 790 // ... 792 leaf protocolDirLocalIndex_2 { 793 type leafref { 794 path "/rmon2-mib:RMON2-MIB/" 795 + "rmon2-mib:protocolDirTable/" 796 + "rmon2-mib:protocolDirEntry/" 797 + "rmon2-mib:protocolDirLocalIndex"; 798 } 799 } 801 // ... 802 } 803 } 805 7.7. Augmenting Conceptual Tables Translation Rules 807 An OBJECT-TYPE macro invocation defining an augmenting conceptual 808 table is translated to a YANG smiv2:alias statement. Refer to the 809 YANG extension defined in Section 10. The clauses of the macro are 810 translated as follows: 812 o The SMIv2 SYNTAX clause is ignored. 814 o The SMIv2 UNITS clause is ignored. 816 o The SMIv2 MAX-ACCESS clause is ignored. 818 o The SMIv2 STATUS clause is mapped to the YANG status statement. 819 The generation of the YANG status statement is skipped if the 820 value of the STATUS clause is current. 822 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 823 statement. 825 o The SMIv2 REFERENCE clause is mapped to the YANG reference 826 statement. 828 o The value of the SMIv2 OBJECT-TYPE macro invocation is translated 829 into an smiv2:oid statement. Refer to the YANG extension defined 830 in Section 10. 832 An OBJECT-TYPE macro invocation defining a conceptual row 833 augmentation is translated to a YANG smiv2:alias statement and a YANG 834 augment statement using the path to the augmented table as its 835 argument. The clauses of the OBJECT-TYPE macro are translated as 836 follows: 838 o The SMIv2 SYNTAX clause is ignored. 840 o The SMIv2 UNITS clause is ignored. 842 o The SMIv2 MAX-ACCESS clause is ignored. 844 o The SMIv2 STATUS clause is mapped to the YANG status statement. 845 The generation of the YANG status statement is skipped if the 846 value of the STATUS clause is current. 848 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 849 statement. 851 o The SMIv2 REFERENCE clause is mapped to the YANG reference 852 statement. 854 o The value of the SMIv2 OBJECT-TYPE macro invocation is translated 855 into an smiv2:oid statement. Refer to the YANG extension defined 856 in Section 10. 858 Within the augment statement, YANG leaf statements are created as 859 described in Section 7.1. 861 7.8. Example: ifXTable of the IF-MIB 863 The translation of the definition of the ifXTable of the IF-MIB 864 [RFC2863] is shown below. 866 smiv2:alias "ifXTable" { 867 description 868 "A list of interface entries. The number of entries is 869 given by the value of ifNumber. This table contains 870 additional objects for the interface table."; 871 smiv2:oid "1.3.6.1.2.1.31.1.1"; 872 } 874 smiv2:alias "ifXEntry" { 875 description 876 "An entry containing additional management information 877 applicable to a particular interface."; 878 smiv2:oid "1.3.6.1.2.1.31.1.1.1"; 879 } 881 augment "/if-mib:IF-MIB/if-mib:ifTable/if-mib:ifEntry" { 882 description 883 "An entry containing additional management information 884 applicable to a particular interface."; 885 smiv2:oid "1.3.6.1.2.1.31.1.1.1"; 887 leaf ifName { 888 type snmpv2-tc:DisplayString; 889 description 890 "The textual name of the interface. The value of this 891 object should be the name of the interface as assigned by 892 the local device and should be suitable for use in commands 893 entered at the device's `console'. This might be a text 894 name, such as `le0' or a simple port number, such as `1', 895 depending on the interface naming syntax of the device. If 896 several entries in the ifTable together represent a single 897 interface as named by the device, then each will have the 898 same value of ifName. Note that for an agent which responds 899 to SNMP queries concerning an interface on some other 900 (proxied) device, then the value of ifName for such an 901 interface is the proxied device's local name for it. 903 If there is no local name, or this object is otherwise not 904 applicable, then this object contains a zero-length string."; 905 smiv2:max-access "read-only"; 906 smiv2:oid "1.3.6.1.2.1.31.1.1.1.1"; 907 } 909 // ... 910 } 912 8. Translation of the OBJECT-IDENTITY Macro 914 The SMIv2 uses invocations of the OBJECT-IDENTITY macro to define 915 information about an OBJECT IDENTIFIER assignment. Invocations of 916 the OBJECT-IDENTITY macro MUST be translated into YANG identity 917 statements as detailed below. 919 8.1. OBJECT-IDENTITY Translation Rules 921 The name of the OBJECT-IDENTITY macro invocation is used as the name 922 of the generated identity statement. The generated identity 923 statement uses the smiv2:object-identity defined in Section 10 as its 924 base. The clauses of the SMIv2 OBJECT-IDENTITY macro are mapped to 925 YANG statements as follows: 927 o The SMIv2 STATUS clause is mapped to the YANG status statement. 928 The generation of the YANG status statement is skipped if the 929 value of the STATUS clause is current. 931 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 932 statement. 934 o The SMIv2 REFERENCE clause is mapped to the YANG reference 935 statement. 937 o The value of the SMIv2 OBJECT-IDENTITY macro invocation is 938 translated into an smiv2:oid statement. Refer to the YANG 939 extension defined in Section 10. 941 8.2. Example: diffServTBParamSimpleTokenBucket of the DIFFSERV-MIB 943 The translation of the diffServTBParamSimpleTokenBucket of the 944 DIFFSERV-MIB [RFC3289] is shown below. 946 identity diffServTBParamSimpleTokenBucket { 947 base "smiv2:object-identity"; 948 description 949 "Two Parameter Token Bucket Meter as described in the Informal 950 Differentiated Services Model section 5.2.3."; 951 smiv2:oid "1.3.6.1.2.1.97.3.1.1"; 952 } 954 9. Translation of the NOTIFICATION-TYPE Macro 956 The SMIv2 provides the NOTIFICATION-TYPE macro to define event 957 notifications. YANG provides the notification statement for the same 958 purpose. Invocations of the NOTIFICATION-TYPE macro MUST be 959 translated into YANG notification statements as detailed below. 961 9.1. NOTIFICATION-TYPE Translation Rules 963 The name of the NOTIFICATION-TYPE macro invocation is used as the 964 name of the generated notification statement. The clauses of the 965 NOTIFICATION-TYPE macro are mapped to YANG statements embedded in the 966 notification statement as follows. 968 o The SMIv2 OBJECTS clause is mapped to a sequence of YANG 969 containers. For each object listed in the OBJECTS clause value, a 970 YANG container statement is generated. The name of this container 971 is the string "object-", where is the position of the 972 object in the value of the OBJECTS clause (first element has 973 position 1). If the current object belongs to a conceptual table, 974 then a sequence of leaf statements is generated for each INDEX 975 object of the conceptual table. These leafs are named after the 976 INDEX objects and of type leafref. Finally, a leaf statement is 977 generated named after the current object. If the current object 978 has a MAX-ACCESS of "read-only", "read-write" or "read-create", 979 then the generated leaf is of type leafref. Otherwise, if the 980 current object has a MAX-ACCESS of "accessible-for-notify", then a 981 leaf is generated, following the itemized steps in Section 7.1. 983 o The SMIv2 STATUS clause is mapped to the YANG status statement. 984 The generation of the YANG status statement is skipped if the 985 value of the STATUS clause is current. 987 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 988 statement. 990 o The SMIv2 REFERENCE clause is mapped to the YANG reference 991 statement. 993 o The value of the SMIv2 NOTIFICATION-TYPE macro invocation is 994 translated into an smiv2:oid statement. Refer to the YANG 995 extension defined in Section 10. 997 9.2. Example: linkDown NOTIFICATION-TYPE of IF-MIB 999 The translation of the linkDown notification of the IF-MIB [RFC2863] 1000 is shown below. 1002 notification linkDown { 1003 description 1004 "A linkDown trap signifies that the SNMP entity, acting in 1005 an agent role, has detected that the ifOperStatus object for 1006 one of its communication links is about to enter the down 1007 state from some other state (but not from the notPresent 1008 state). This other state is indicated by the included value 1009 of ifOperStatus."; 1010 smiv2:oid "1.3.6.1.6.3.1.1.5.3"; 1012 container object-1 { 1013 leaf ifIndex { 1014 type leafref { 1015 path "/if-mib:IF-MIB/if-mib:ifTable" + 1016 "/if-mib:ifEntry/if-mib:ifIndex"; 1017 } 1018 } 1019 } 1021 container object-2 { 1022 leaf ifIndex { 1023 type leafref { 1024 path "/if-mib:IF-MIB/if-mib:ifTable" + 1025 "/if-mib:ifEntry/if-mib:ifIndex"; 1026 } 1027 } 1028 leaf ifAdminStatus { 1029 type leafref { 1030 path "/if-mib:IF-MIB/if-mib:ifTable" + 1031 "/if-mib:ifEntry/if-mib:ifAdminStatus"; 1032 } 1033 } 1034 } 1036 container object-3 { 1037 leaf ifIndex { 1038 type leafref { 1039 path "/if-mib:IF-MIB/if-mib:ifTable" + 1040 "/if-mib:ifEntry/if-mib:ifIndex"; 1041 } 1042 } 1043 leaf ifOperStatus { 1044 type leafref { 1045 path "/if-mib:IF-MIB/if-mib:ifTable" + 1046 "/if-mib:ifEntry/if-mib:ifOperStatus"; 1047 } 1048 } 1049 } 1051 } 1053 10. YANG Language Extension Definition 1055 This section defines some YANG extension statements that can be used 1056 to capture some information present in SMIv2 modules that is not 1057 translated into core YANG statements. The YANG module references 1058 [RFC2578] and [RFC2579]. 1060 RFC Ed.: update the date below with the revision date of the YANG 1061 module and remove this note. 1063 file "ietf-yang-smiv2@2012-04-20.yang" 1065 module ietf-yang-smiv2 { 1067 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-smiv2"; 1068 prefix "smiv2"; 1070 organization 1071 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 1073 contact 1074 "WG Web: 1075 WG List: 1077 WG Chair: David Kessens 1078 1080 WG Chair: Juergen Schoenwaelder 1081 1083 Editor: Juergen Schoenwaelder 1084 "; 1086 description 1087 "This module defines YANG extensions that are used to translate 1088 SMIv2 concepts into YANG. 1090 Copyright (c) 2012 IETF Trust and the persons identified as 1091 authors of the code. All rights reserved. 1093 Redistribution and use in source and binary forms, with or 1094 without modification, is permitted pursuant to, and subject 1095 to the license terms contained in, the Simplified BSD License 1096 set forth in Section 4.c of the IETF Trust's Legal Provisions 1097 Relating to IETF Documents 1098 (http://trustee.ietf.org/license-info). 1100 This version of this YANG module is part of RFC XXXX; see 1101 the RFC itself for full legal notices."; 1102 // RFC Ed.: replace XXXX with actual RFC number and remove this note 1104 // RFC Ed.: please update the date to the date of publication 1105 revision 2012-04-20 { 1106 description 1107 "Initial revision."; 1108 reference 1109 "RFC XXXX: Translation of SMIv2 MIB Modules to YANG Modules"; 1110 // RFC Ed.: replace XXXX with actual RFC number and remove this note 1111 } 1113 identity object-identity { 1114 description 1115 "Base identity for all SMIv2 OBJECT-IDENTITYs."; 1116 } 1118 typedef opaque { 1119 type binary; 1120 description 1121 "The Opaque type supports the capability to pass arbitrary ASN.1 1122 syntax. A value is encoded using the ASN.1 Basic Encoding Rules 1123 into a string of octets. This, in turn, is encoded as an OCTET 1124 STRING, in effect 'double-wrapping' the original ASN.1 value. 1126 In the value set and its semantics, this type is equivalent to 1127 the Opaque type of the SMIv2. This type exists in the SMIv2 1128 solely for backward-compatibility reasons and this is also 1129 true for this YANG data type."; 1130 reference 1131 "RFC 2578: Structure of Management Information Version 2 (SMIv2)"; 1132 } 1134 extension display-hint { 1135 argument "format"; 1136 description 1137 "The display-hint statement takes as an argument the DISPLAY-HINT 1138 assigned to an SMIv2 textual convention."; 1139 reference 1140 "RFC2579: Textual Conventions for SMIv2"; 1141 } 1143 extension max-access { 1144 argument "access"; 1145 description 1146 "The max-access statement takes as an argument the MAX-ACCESS 1147 assigned to an SMIv2 object definition. 1149 The MAX-ACCESS value is SMIv2 specific and has no impact on 1150 the access provided to YANG objects through protocols such 1151 as NETCONF."; 1152 reference 1153 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1154 } 1156 extension defval { 1157 argument "value"; 1158 description 1159 "The defval statement takes as an argument a default value 1160 defined by an SMIv2 DEFVAL clause. Note that the value is in 1161 the SMIv2 value space defined by the SMIv2 syntax of the 1162 corresponding object and not in the YANG value space 1163 defined by the corresponding YANG data type."; 1164 reference 1165 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1166 } 1168 extension implied { 1169 argument "index"; 1170 description 1171 "If an SMIv2 INDEX object is preceded by the IMPLIED keyword, then 1172 the implied statement is present in the yang module and takes as 1173 an argument the name of the IMPLIED index object."; 1174 reference 1175 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1176 } 1178 extension alias { 1179 argument "descriptor"; 1180 description 1181 "The alias statement introduces an SMIv2 descriptor. The body of 1182 the alias statement is expected to contain an oid statement that 1183 provides the numeric OID associated with the descriptor."; 1184 reference 1185 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1186 } 1188 extension oid { 1189 argument "value"; 1190 description 1191 "The oid statement takes as an argument the object identifier 1192 assigned to an SMIv2 definition. The object identifier value 1193 is written in decimal dotted notation."; 1194 reference 1195 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1196 } 1197 extension subid { 1198 argument "value"; 1199 description 1200 "The subid statement takes as an argument the last sub-identifier 1201 of the object identifier assigned to an SMIv2 definition. The 1202 sub-identifier value is a single positive decimal natural number. 1203 The subid statement may not be used as a substatement to any 1204 top-level node in a YANG document. The subid substatement may 1205 be used only as a substatement to a node having a parent node 1206 defined with either a smiv2:oid or smiv2:subid substatement."; 1207 reference 1208 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1209 } 1211 } 1213 1215 11. Implementing Configuration Data Nodes 1217 The result of the translation of SMIv2 MIB modules into YANG modules, 1218 even if SMIv2 objects are read-write or read-create, consists of 1219 read-only (config false) YANG objects. One reason is that the 1220 persistency models of the underlying protocols, SNMP and NETCONF, are 1221 quite different. With SNMP, the persistency of a writable object 1222 depends either on the object definition itself (i.e., the text in the 1223 DESCRIPTION clause) or the persistency properties of the conceptual 1224 row it is part of, sometimes controlled via a columnar object using 1225 the StorageType textual convention. With NETCONF, the persistency of 1226 configuration objects is determined by the properties of the 1227 underlying datastore. Furthermore, NETCONF as defined in [RFC6241] 1228 does not provide a standard operation to modify operational state. 1229 The and operations only manipulate 1230 configuration data. As a consequence of these considerations, it is 1231 not possible to generate YANG configuration data nodes from SMIv2 1232 definitions in an automated way. 1234 However, for selected SMIv2 objects where the SNMP and NETCONF 1235 persistency semantics are consistent, implementations may choose to 1236 implement some YANG data nodes generated from SMIv2 definitions as 1237 configuration data nodes. Such a deviation from the generated read- 1238 only YANG module should be formally documented in the form of a 1239 separate YANG module that uses YANG deviation statements to change 1240 the config property of the data nodes implemented as configuration 1241 data nodes from false to true. Deviations that change the config 1242 false property to true without any other changes to the semantics of 1243 the data node do not affect the compliance with the YANG module 1244 generated from an SMIv2 module. 1246 11.1. Example: addressMapControlTable of RMON2-MIB 1248 The following example demonstrates how certain columnar objects of 1249 the addressMapControlTable of the RMON2-MIB [RFC4502] can be turned 1250 into YANG configuration data nodes. Note that YANG deviations affect 1251 the property of the target node only and are not inherited downwards. 1253 module acme-RMON2-MIB-deviations { 1255 namespace "http://acme.example.com/RMON2-MIB-deviations"; 1256 prefix "acme-rmon2-devs"; 1258 import RMON2-MIB { 1259 prefix "rmon2-mib"; 1260 revision-date 2006-05-02; 1261 } 1262 revision 2012-01-11 { 1263 description 1264 "First version."; 1265 } 1267 deviation "/rmon2-mib:RMON2-MIB" { 1268 deviate replace { 1269 config true; 1270 } 1271 } 1273 deviation "/rmon2-mib:RMON2-MIB/" 1274 + "rmon2-mib:addressMapControlTable" { 1275 deviate replace { 1276 config true; 1277 } 1278 } 1280 deviation "/rmon2-mib:RMON2-MIB/" 1281 + "rmon2-mib:addressMapControlTable/" 1282 + "rmon2-mib:addressMapControlEntry" { 1283 deviate replace { 1284 config true; 1285 } 1286 } 1288 deviation "/rmon2-mib:RMON2-MIB/" 1289 + "rmon2-mib:addressMapControlTable/" 1290 + "rmon2-mib:addressMapControlEntry/" 1291 + "rmon2-mib:addressMapControlIndex" { 1292 deviate replace { 1293 config true; 1294 } 1295 } 1297 deviation "/rmon2-mib:RMON2-MIB/" 1298 + "rmon2-mib:addressMapControlTable/" 1299 + "rmon2-mib:addressMapControlEntry/" 1300 + "rmon2-mib:addressMapControlDataSource" { 1301 deviate replace { 1302 config true; 1303 } 1304 } 1306 deviation "/rmon2-mib:RMON2-MIB/" 1307 + "rmon2-mib:addressMapControlTable/" 1308 + "rmon2-mib:addressMapControlEntry/" 1309 + "rmon2-mib:addressMapControlOwner" { 1311 deviate replace { 1312 config true; 1313 } 1314 } 1315 } 1317 A NETCONF server that implements the RMON2-MIB module with these 1318 deviations would advertise the following capabilities in its 1319 message (where whitespace has been added for readability): 1321 1322 urn:ietf:params:xml:ns:yang:smiv2:RMON2-MIB? 1323 module=RMON2-MIB& 1324 revision=2006-05-02& 1325 deviations=acme-RMON2-MIB-deviations 1326 1327 1328 http://acme.example.com/RMON2-MIB-deviations? 1329 module=acme-RMON2-MIB-deviations& 1330 revision=2012-01-11 1331 1333 12. IANA Considerations 1335 This document registers two URIs in the IETF XML registry [RFC3688]. 1336 Following the format in RFC 3688, the following registrations have 1337 been made. 1339 URI: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 1341 Registrant Contact: The NETMOD WG of the IETF. 1343 XML: N/A, the requested URI is an XML namespace. 1345 URI: urn:ietf:params:xml:ns:yang:smiv2 1347 Registrant Contact: The NETMOD WG of the IETF. 1349 XML: N/A, the requested URI is an XML namespace. 1351 This document registers a YANG module in the YANG Module Names 1352 registry [RFC6020]. 1354 name: ietf-yang-smiv2 1355 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 1356 prefix: smiv2 1357 reference: RFC XXXX 1359 13. Security Considerations 1361 This document defines a translation of SMIv2 MIB modules into YANG 1362 modules, enabling read-only (config false) access to data objects 1363 defined in SMIv2 MIB modules via NETCONF. The translation itself has 1364 no security impact on the Internet. 1366 Users of YANG data models generated from SMIv2 data models that have 1367 been published in the RFC series are advised to consult the security 1368 considerations of the respective RFCs. The security considerations 1369 of RFCs containing SMIv2 data models explain which objects are 1370 sensitive and important to protect. NETCONF users are encouraged to 1371 make use of the NETCONF access control model [RFC6536], which allows 1372 to specify access control rules to protect potentially sensitive 1373 information. 1375 14. Acknowledgements 1377 The editor wishes to thank the following individuals for providing 1378 helpful comments on various versions of this document: Andy Bierman, 1379 Benoit Claise, Martin Bjorklund, Leif Johansson, David Reid, Dan 1380 Romascanu, and David Spakes. 1382 15. References 1384 15.1. Normative References 1386 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1387 Requirement Levels", BCP 14, RFC 2119, March 1997. 1389 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1390 Schoenwaelder, Ed., "Structure of Management Information 1391 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1393 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1394 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 1395 STD 58, RFC 2579, April 1999. 1397 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 1398 "Conformance Statements for SMIv2", STD 58, RFC 2580, 1399 April 1999. 1401 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1402 the Network Configuration Protocol (NETCONF)", RFC 6020, 1403 October 2010. 1405 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1406 October 2010. 1408 15.2. Informative References 1410 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 1411 MIB", RFC 2863, June 2000. 1413 [RFC3289] Baker, F., Chan, K., and A. Smith, "Management Information 1414 Base for the Differentiated Services Architecture", 1415 RFC 3289, May 2002. 1417 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 1418 "Coexistence between Version 1, Version 2, and Version 3 1419 of the Internet-standard Network Management Framework", 1420 RFC 3584, August 2003. 1422 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1423 January 2004. 1425 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 1426 Documents", BCP 111, RFC 4181, September 2005. 1428 [RFC4502] Waldbusser, S., "Remote Network Monitoring Management 1429 Information Base Version 2", RFC 4502, May 2006. 1431 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1432 and A. Bierman, Ed., "Network Configuration Protocol 1433 (NETCONF)", RFC 6241, June 2011. 1435 [RFC6536] Bierman, A., Ed. and M. Bjorklund, Ed., "Network 1436 Configuration Protocol (NETCONF) Access Control Model", 1437 RFC 6536, March 2012. 1439 Appendix A. Mapping of Well Known Types (normative) 1441 This normative appendix describes the mapping of SMIv2 types to YANG 1442 types. The mapping is fully consistent with Table 1 and Table 2 of 1443 [RFC6021]. 1445 SMIv2 Module: SNMPv2-SMI 1446 SMIv2 Type: INTEGER (used as an enumeration) 1447 YANG Type: enumeration 1449 SMIv2 Module: SNMPv2-SMI 1450 SMIv2 Type: INTEGER (used as a numeric type) 1451 YANG Type: int32 1453 SMIv2 Module: SNMPv2-SMI 1454 SMIv2 Type: Integer32 1455 YANG Type: int32 1457 SMIv2 Module: SNMPv2-SMI 1458 SMIv2 Type: OCTET STRING (used as a binary string) 1459 YANG Type: binary 1461 SMIv2 Module: SNMPv2-SMI 1462 SMIv2 Type: OCTET STRING (used to hold UTF8/ASCII characters) 1463 YANG Type: string 1465 SMIv2 Module: SNMPv2-SMI 1466 SMIv2 Type: OBJECT IDENTIFIER 1467 YANG Module: ietf-yang-types 1468 YANG Type: object-identifier-128 1470 SMIv2 Module: SNMPv2-SMI 1471 SMIv2 Type: BITS 1472 YANG Type: bits 1474 SMIv2 Module: SNMPv2-SMI 1475 SMIv2 Type: IpAddress 1476 YANG Module: ietf-inet-types 1477 YANG Type: ipv4-address 1479 SMIv2 Module: SNMPv2-SMI 1480 SMIv2 Type: Counter32 1481 YANG Module: ietf-yang-types 1482 YANG Type: counter32 1484 SMIv2 Module: SNMPv2-SMI 1485 SMIv2 Type: Gauge32 1486 YANG Module: ietf-yang-types 1487 YANG Type: gauge32 1489 SMIv2 Module: SNMPv2-SMI 1490 SMIv2 Type: TimeTicks 1491 YANG Module: ietf-yang-types 1492 YANG Type: timeticks 1494 SMIv2 Module: SNMPv2-SMI 1495 SMIv2 Type: Counter64 1496 YANG Module: ietf-yang-types 1497 YANG Type: counter64 1499 SMIv2 Module: SNMPv2-SMI 1500 SMIv2 Type: Unsigned32 1501 YANG Type: uint32 1503 SMIv2 Module: SNMPv2-SMI 1504 SMIv2 Type: Opaque 1505 YANG Module: ietf-yang-smiv2 1506 YANG Type: opaque 1508 SMIv2 Module: SNMPv2-TC 1509 SMIv2 Type: PhysAddress 1510 YANG Module: ietf-yang-types 1511 YANG Type: phys-address 1513 SMIv2 Module: SNMPv2-TC 1514 SMIv2 Type: MacAddress 1515 YANG Module: ietf-yang-types 1516 YANG Type: mac-address 1518 SMIv2 Module: SNMPv2-TC 1519 SMIv2 Type: TruthValue 1520 YANG Type: boolean 1522 SMIv2 Module: SNMPv2-TC 1523 SMIv2 Type: TimeStamp 1524 YANG Module: ietf-yang-types 1525 YANG Type: timestamp 1527 SMIv2 Module: RMON2-MIB 1528 SMIv2 Type: ZeroBasedCounter32 1529 YANG Module: ietf-yang-types 1530 YANG Type: zero-based-counter32 1532 SMIv2 Module: HCNUM-TC 1533 SMIv2 Type: ZeroBasedCounter64 1534 YANG Module: ietf-yang-types 1535 YANG Type: zero-based-counter64 1537 SMIv2 Module: HCNUM-TC 1538 SMIv2 Type: CounterBasedGauge64 1539 YANG Module: ietf-yang-types 1540 YANG Type: gauge64 1542 SMIv2 Module: INET-ADDRESS-MIB 1543 SMIv2 Type: InetAutonomousSystemNumber 1544 YANG Module: ietf-inet-types 1545 YANG Type: as-number 1547 SMIv2 Module: INET-ADDRESS-MIB 1548 SMIv2 Type: InetVersion 1549 YANG Module: ietf-inet-types 1550 YANG Type: ip-version 1552 SMIv2 Module: INET-ADDRESS-MIB 1553 SMIv2 Type: InetPortNumber 1554 YANG Module: ietf-inet-types 1555 YANG Type: port-number 1557 SMIv2 Module: DIFFSERV-DSCP-TC 1558 SMIv2 Type: Dscp 1559 YANG Module: ietf-inet-types 1560 YANG Type: dscp 1562 SMIv2 Module: IPV6-FLOW-LABEL-MIB 1563 SMIv2 Type: IPv6FlowLabel 1564 YANG Module: ietf-inet-types 1565 YANG Type: ipv6-flow-label 1567 SMIv2 Module: URI-TC-MIB 1568 SMIv2 Type: Uri 1569 YANG Module: ietf-inet-types 1570 YANG Type: uri 1572 Appendix B. Module Prefix Generation (informative) 1574 This section describes an algorithm to generate module prefixes, to 1575 be used in the import statements. The input of the prefix generation 1576 algorithm is a set of prefixes (usually derived from imported module 1577 names) and a specific module name to be converted into a prefix. The 1578 algorithm described below produces a prefix for the given module name 1579 that is unique within the set of prefixes. 1581 +-----------------+--------+ 1582 | YANG Module | Prefix | 1583 +-----------------+--------+ 1584 | ietf-yang-types | yang | 1585 | ietf-inet-types | inet | 1586 | ietf-yang-smiv2 | smiv2 | 1587 +-----------------+--------+ 1589 Table 1: Special prefixes for well known YANG modules 1591 o First, some predefined translations mapping well known YANG 1592 modules to short prefixes are tried (see Table 1). If a fixed 1593 translation rule exists and leads to a conflict free prefix, then 1594 the fixed translation is used. 1596 o Otherwise, prefixes are generated by tokenizing a YANG module 1597 name, using hyphens as token separators. The tokens derived from 1598 the module name are converted to lowercase characters. The prefix 1599 then becomes the shortest sequence of tokens concatenated using 1600 hyphens as separators, which includes at least two tokens and 1601 which is unique among all prefixes used in the YANG module. 1603 In the worst case, the prefix derived from an SMIv2 module name 1604 becomes the SMIv2 module name translated to lower-case. But on 1605 average, much shorter prefixes are generated. 1607 Author's Address 1609 Juergen Schoenwaelder 1610 Jacobs University 1612 Email: j.schoenwaelder@jacobs-university.de