idnits 2.17.1 draft-schoenw-netmod-smi-yang-02.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 (March 14, 2011) is 4789 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 4741 (Obsoleted by RFC 6241) 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 March 14, 2011 5 Expires: September 15, 2011 7 Translation of SMIv2 MIB Modules to YANG Modules 8 draft-schoenw-netmod-smi-yang-02 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 access to 19 data objects defined in SMIv2 MIB modules via NETCONF. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on September 15, 2011. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 This document may contain material from IETF Documents or IETF 54 Contributions published or made publicly available before November 55 10, 2008. The person(s) controlling the copyright in some of this 56 material may not have granted the IETF Trust the right to allow 57 modifications of such material outside the IETF Standards Process. 58 Without obtaining an adequate license from the person(s) controlling 59 the copyright in such materials, this document may not be modified 60 outside the IETF Standards Process, and derivative works of it may 61 not be created outside the IETF Standards Process, except to format 62 it for publication as an RFC or to translate it into languages other 63 than English. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Mapping of Special Types . . . . . . . . . . . . . . . . . . . 5 69 3. Module Prefix Generation . . . . . . . . . . . . . . . . . . . 6 70 4. Translation of SMIv2 Modules and SMIv2 IMPORT Clauses . . . . 7 71 4.1. Example: IMPORTS of IF-MIB . . . . . . . . . . . . . . . . 8 72 5. Translation of the MODULE-IDENTITY Macro . . . . . . . . . . . 9 73 5.1. MODULE-IDENTITY Translation Rules . . . . . . . . . . . . 9 74 5.2. Example: MODULE-IDENTITY of IF-MIB . . . . . . . . . . . . 9 75 6. Translation of the TEXTUAL-CONVENTION Macro . . . . . . . . . 11 76 6.1. TEXTUAL-CONVENTION Translation Rules . . . . . . . . . . . 11 77 6.2. Example: OwnerString and InterfaceIndex of IF-MIB . . . . 11 78 6.3. Example: IfDirection of the DIFFSERV-MIB . . . . . . . . . 12 79 7. Translation of OBJECT IDENTIFIER Assignments . . . . . . . . . 13 80 7.1. Object Identifier Assignment Translation Rules . . . . . . 13 81 7.2. Example: OBJECT IDENTIFIER Assignments of the IF-MIB . . . 13 82 8. Translation of the OBJECT-TYPE Macro . . . . . . . . . . . . . 14 83 8.1. Scalar and Columnar Object Translation Rules . . . . . . . 14 84 8.2. Example: ifNumber and ifIndex of the IF-MIB . . . . . . . 14 85 8.3. Non-Augmenting Conceptual Table Translation Rules . . . . 15 86 8.4. Example: ifTable of the IF-MIB . . . . . . . . . . . . . . 16 87 8.5. Example: ifRcvAddressTable of the IF-MIB . . . . . . . . . 16 88 8.6. Augmenting Conceptual Tables Translation Rules . . . . . . 18 89 8.7. Example: ifXTable of the IF-MIB . . . . . . . . . . . . . 18 90 9. Translation of the OBJECT-IDENTITY Macro . . . . . . . . . . . 20 91 9.1. OBJECT-IDENTITY Translation Rules . . . . . . . . . . . . 20 92 9.2. Example: diffServTBParamSimpleTokenBucket of the 93 DIFFSERV-MIB . . . . . . . . . . . . . . . . . . . . . . . 20 94 10. Translation of the NOTIFICATION-TYPE Macro . . . . . . . . . . 21 95 10.1. NOTIFICATION-TYPE Translation Rules . . . . . . . . . . . 21 96 10.2. Example: linkDown NOTIFICATION-TYPE of IF-MIB . . . . . . 21 97 11. YANG Language Extension Definition . . . . . . . . . . . . . . 24 98 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 99 13. Security Considerations . . . . . . . . . . . . . . . . . . . 27 100 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 101 14.1. Normative References . . . . . . . . . . . . . . . . . . . 28 102 14.2. Informative References . . . . . . . . . . . . . . . . . . 28 103 Appendix A. Changes from 01 to 02 . . . . . . . . . . . . . . . . 29 104 Appendix B. Changes from 00 to 01 . . . . . . . . . . . . . . . . 30 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 31 107 1. Introduction 109 This document describes an translation of SMIv2 [RFC2578], [RFC2579], 110 [RFC2580] MIB modules into YANG [RFC6020] modules, enabling read-only 111 access to data objects defined in SMIv2 MIB modules via NETCONF. The 112 mapping is illustrated by examples showing the translation of part of 113 the IF-MIB [RFC2863] SMIv2 module and the DIFFSERV-MIB [RFC3289] 114 SMIv2 module. 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 118 "OPTIONAL" in this document are to be interpreted as described in BCP 119 14, [RFC2119]. 121 2. Mapping of Special Types 123 The SMIv2 base types and some well known derived textual-conventions 124 are mapped to YANG types according to Table 1. The mapping of the 125 OCTET STRING depends on the context. If an OCTET STRING type has an 126 associated DISPLAY-HINT, then the corresponding YANG base type is the 127 string type. Otherwise, the binary type is used. Similarly, the 128 mapping of the INTEGER type depends on its usage as an enumeration or 129 a 32-bit integral type. 131 Mapping of SMIv2 types to YANG types 133 +------------+----------------+-----------------+-------------------+ 134 | SMIv2 | SMIv2 Type | YANG Module | YANG Type | 135 | Module | | | | 136 +------------+----------------+-----------------+-------------------+ 137 | SNMPv2-SMI | INTEGER | | enumeration | 138 | SNMPv2-SMI | INTEGER | | int32 | 139 | SNMPv2-SMI | Integer32 | | int32 | 140 | SNMPv2-SMI | OCTET STRING | | binary | 141 | SNMPv2-SMI | OCTET STRING | | string | 142 | SNMPv2-SMI | OBJECT | ietf-yang-types | object-identifier | 143 | | IDENTIFIER | | | 144 | SNMPv2-SMI | BITS | | bits | 145 | SNMPv2-SMI | IpAddress | ietf-inet-types | ipv4-address | 146 | SNMPv2-SMI | Counter32 | ietf-yang-types | counter32 | 147 | SNMPv2-SMI | Gauge32 | ietf-yang-types | gauge32 | 148 | SNMPv2-SMI | TimeTicks | ietf-yang-types | timeticks | 149 | SNMPv2-SMI | Opaque | | binary | 150 | SNMPv2-SMI | Counter64 | ietf-yang-types | counter64 | 151 | SNMPv2-SMI | Unsigned32 | | uint32 | 152 | SNMPv2-TC | PhysAddress | ietf-yang-types | phys-address | 153 | SNMPv2-TC | MacAddress | ietf-yang-types | mac-address | 154 | SNMPv2-TC | TimeStamp | ietf-yang-types | timestamp | 155 +------------+----------------+-----------------+-------------------+ 157 Table 1 159 The mappings shown in Table 1 may impact the imports of the generated 160 YANG module since some SMIv2 types and textual-conventions map to 161 YANG types defined in the ietf-yang-types and ietf-inet-types YANG 162 modules [RFC6021]. Implementations must add any additional imports 163 required by the type mapping. 165 3. Module Prefix Generation 167 The input of the prefix generation algorithm is a set of prefixes 168 (usually derived from imported module names) and a specific module 169 name to be converted into a prefix. The algorithm described below 170 produces a prefix for the given module name that is unique within the 171 set of prefixes. 173 Special prefixes for well known SMIv2 and YANG modules 175 +---------------------+--------+ 176 | YANG / SMIv2 Module | Prefix | 177 +---------------------+--------+ 178 | ietf-yang-types | yang | 179 | ietf-inet-types | inet | 180 | ietf-yang-smiv2 | smiv2 | 181 +---------------------+--------+ 183 Table 2 185 o First, some fixed translations mapping well known SMIv2 and YANG 186 modules to short prefixes are tried (see Table 2). If a fixed 187 translation rule exists and leads to a conflict free prefix, then 188 the fixed translation is used. 190 o Otherwise, prefixes are generated by tokenizing an SMIv2 module 191 name where hyphens are considered as token separators. The tokens 192 derived with a module name are converted to lowercase characters. 193 The prefix then becomes the shortest sequence of token 194 concatenated using hyphens as separators, which includes at least 195 two token and which is unique among all prefixes used in the YANG 196 module. 198 In the worst case, the prefix derived from an SMIv2 module name 199 becomes the SMIv2 module name translated to lower-case. But on 200 average, much shorter prefixes are generated. 202 4. Translation of SMIv2 Modules and SMIv2 IMPORT Clauses 204 SMIv2 modules are mapped to corresponding YANG modules. The YANG 205 module name is the same as the SMIv2 module name. 207 The YANG namespace is constructed out of a constant prefix followed 208 by the SMIv2 module name. Since SMIv2 module names are unique, the 209 resulting YANG namespace is unique. The registered prefix is 210 urn:ietf:params:xml:ns:yang:smiv2:, see the IANA considerations 211 section. 213 The YANG prefix is derived from the SMIv2 module name using the 214 module prefix generation algorithm described in Section 3. The YANG 215 prefix is supposed to be short and it must be unique within the set 216 of all prefixes used by a YANG module. The algorithm described in 217 Section 3 generates such prefixes. 219 SMIv2 IMPORT clauses are translated to YANG import statements. One 220 major difference between the SMIv2 import mechanism and the YANG 221 import mechanism is that SMIv2 IMPORT clauses import specific symbols 222 from an SMIv2 module while the YANG import statement imports all 223 symbols of the referenced YANG module. 225 SMIv2 imports that are ignored in YANG 227 +--------------+--------------------+ 228 | SMIv2 Module | SMIv2 Symbol | 229 +--------------+--------------------+ 230 | SNMPv2-SMI | MODULE-IDENTITY | 231 | SNMPv2-SMI | OBJECT-IDENTITY | 232 | SNMPv2-SMI | OBJECT-TYPE | 233 | SNMPv2-SMI | NOTIFICATION-TYPE | 234 | SNMPv2-SMI | mib-2 | 235 | SNMPv2-TC | TEXTUAL-CONVENTION | 236 | SNMPv2-CONF | OBJECT-GROUP | 237 | SNMPv2-CONF | NOTIFICATION-GROUP | 238 | SNMPv2-CONF | MODULE-COMPLIANCE | 239 | SNMPv2-CONF | AGENT-CAPABILITIES | 240 | SNMPv2-MIB | snmpTraps | 241 | SNMPv2-SMI | all symbols | 242 | SNMPv2-CONF | all symbols | 243 +--------------+--------------------+ 245 Table 3 247 In order to produce correct and complete YANG import statements, it 248 is necessary to apply the following rules: 250 o Ignore all imports listed in Table 3. Note that the modules 251 SNMPv2-SMI and SNMPv2-CONF are completely ignored since all 252 definitions in these modules are translated by translation rules. 254 o Add any imports required by the type translations according to the 255 type mapping table. This requires to consider all the types used 256 in the translation unit. 258 The argument of the generated import statements are the untranslated 259 SMIv2 module name. The import statement must contain a prefix 260 statement. The prefixes are generated by applying the module prefix 261 generation algorithm described in Section 3. 263 4.1. Example: IMPORTS of IF-MIB 265 The translation of the IF-MIB [RFC2863] leads to the YANG module 266 frame and the import statements shown below. The prefix is the 267 translation of the SMIv2 module name IF-MIB to lowercase (consisting 268 of two token and thus no further abbreviation). 270 module IF-MIB { 272 namespace "urn:ietf:params:xml:ns:yang:smiv2:IF-MIB"; 273 prefix "if-mib"; 275 import IANAifType-MIB { prefix "ianaiftype-mib"; } 276 import SNMPv2-TC { prefix "smiv2-tc"; } 277 import ietf-yang-types { prefix "yang"; } 278 import ietf-yang-smiv2 { prefix "smiv2"; } 279 } 281 5. Translation of the MODULE-IDENTITY Macro 283 The clauses of the SMIv2 MODULE-IDENTITY macro are mapped to 284 equivalent YANG statements. 286 5.1. MODULE-IDENTITY Translation Rules 288 o The SMIv2 ORGANIZATION clause is mapped to the YANG organization 289 statement. 291 o The SMIv2 CONTACT-INFO clause is mapped to the YANG contact 292 statement. 294 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 295 statement. 297 o Each SMIv2 REVISION clause is mapped to a YANG revision statement. 298 The revision is identified by the date of contained in the SMIv2 299 REVISION. DESCRIPTION sub-clauses of REVISION clauses are mapped 300 to corresponding description statement nested in revision clauses. 302 o The SMIv2 LAST-UPDATED is ignored if the associated date matches a 303 REVISION clause. Otherwise, an additional revision statement is 304 generated. 306 o The value of the invocation of an SMIv2 MODULE-IDENTITY macro is 307 ignored. 309 While all proper SMIv2 modules must have a MODULE-IDENTITY macro 310 invocation, there are a few notable exceptions. The modules defining 311 the SMIv2 language (i.e., the SNMPv2-SMI, SNMPv2-TC, and SNMPv2-CONF 312 modules) do not invoke the MODULE-IDENTITY macro. Furthermore, SMIv2 313 modules generated out of SMIv1 modules may miss an invocation of the 314 MODULE-IDENTITY macro as well. In such cases, it is preferable to 315 not generate organization, contact, description, and revision 316 statements. 318 5.2. Example: MODULE-IDENTITY of IF-MIB 320 The translation of the MODULE-IDENTITY of the IF-MIB [RFC2863] leads 321 to the following YANG statements: 323 organization 324 "IETF Interfaces MIB Working Group"; 326 contact 327 "Keith McCloghrie 328 Cisco Systems, Inc. 329 170 West Tasman Drive 330 San Jose, CA 95134-1706 331 US 333 408-526-5260 334 kzm@cisco.com"; 336 description 337 "The MIB module to describe generic objects for network 338 interface sub-layers. This MIB is an updated version of 339 MIB-II's ifTable, and incorporates the extensions defined in 340 RFC 1229."; 342 revision "2000-06-14" { 343 description 344 "Clarifications agreed upon by the Interfaces MIB WG, and 345 published as RFC 2863."; 346 } 347 revision "1996-02-28" { 348 description 349 "Revisions made by the Interfaces MIB WG, and published in 350 RFC 2233."; 351 } 352 revision "1993-11-08" { 353 description 354 "Initial revision, published as part of RFC 1573."; 355 } 357 6. Translation of the TEXTUAL-CONVENTION Macro 359 The SMIv2 uses invocations of the TEXTUAL-CONVENTION macro to define 360 new types derived from the SMIv2 base types. Invocations of the 361 TEXTUAL-CONVENTION macro are translated into YANG typedef statements. 363 6.1. TEXTUAL-CONVENTION Translation Rules 365 The name of the TEXTUAL-CONVENTION macro invocation is used as the 366 name of the generated typedef statement. The clauses of the SMIv2 367 TEXTUAL-CONVENTION macro are mapped to YANG statements embedded in 368 the typedef statement as follows: 370 o The SMIv2 DISPLAY-HINT clause is used to determine the type 371 mapping of types derived form the OCTET STRING type as explained 372 in Section 2. Furthermore, the DISPLAY-HINT value MAY be used to 373 generate a regular expression for the YANG pattern statement 374 within the type statement. [[TODO: Define a translation algorithm 375 that is simple and produces correct and usable results for the 376 majority of simple DISPLAY-HINTS?]] 378 o The SMIv2 STATUS clause is mapped to the YANG status statement. 379 The generation of the YANG status statement is skipped if the 380 value of the STATUS clause is current. 382 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 383 statement. 385 o The SMIv2 REFERENCE clause is mapped to the YANG reference 386 statement. 388 o The SMIv2 SYNTAX clause is mapped to the YANG type statement. 389 SMIv2 range restrictions are mapped to YANG range statements while 390 SMIv2 length restrictions are mapped to YANG length statements. 391 SMIv2 INTEGER enumerations and SMIv2 BITS are mapped to YANG enum 392 / value and bit / position statements. 394 6.2. Example: OwnerString and InterfaceIndex of IF-MIB 396 The translation of the OwnerString and InterfaceIndex textual- 397 conventions of the IF-MIB [RFC2863] are shown below. 399 typedef OwnerString { 400 type string { 401 length "0..255"; 402 pattern "\p{IsBasicLatin}{0,255}"; 403 } 404 status deprecated; 405 description 406 "This data type is used to model an administratively 407 assigned name of the owner of a resource. This information 408 is taken from the NVT ASCII character set. It is suggested 409 that this name contain one or more of the following: ASCII 410 form of the manager station's transport address, management 411 station name (e.g., domain name), network management 412 personnel's name, location, or phone number. In some cases 413 the agent itself will be the owner of an entry. In these 414 cases, this string shall be set to a string starting with 415 'agent'."; 416 } 418 typedef InterfaceIndex { 419 type int32 { 420 range "1..2147483647"; 421 } 422 description 423 "A unique value, greater than zero, for each interface or 424 interface sub-layer in the managed system. It is 425 recommended that values are assigned contiguously starting 426 from 1. The value for each interface sub-layer must remain 427 constant at least from one re-initialization of the entity's 428 network management system to the next re-initialization."; 429 } 431 6.3. Example: IfDirection of the DIFFSERV-MIB 433 The translation of the IfDirection textual-convention of the 434 DIFFSERV-MIB [RFC3289] is shown below. 436 typedef IfDirection { 437 type enumeration { 438 enum inbound { value 1; } 439 enum outbound { value 2; } 440 } 441 description 442 "IfDirection specifies a direction of data travel on an 443 interface. 'inbound' traffic is operated on during reception from 444 the interface, while 'outbound' traffic is operated on prior to 445 transmission on the interface."; 446 } 448 7. Translation of OBJECT IDENTIFIER Assignments 450 The mapping suppresses many structural OBJECT IDENTIFIER assignments 451 that are typically used to organize the OBJECT IDENTIFIER tree. 453 7.1. Object Identifier Assignment Translation Rules 455 o Object identifier assignments through ASN.1 value assignments or 456 through the invocation of a MODULE-IDENTITY clause are translated 457 to YANG container statements. 459 o Top-level container must be marked as config false. 461 o Implementations MAY suppress the generation of YANG containers for 462 object identifiers that only contain SMIv2 conformance 463 definitions. 465 [[TODO: What do we do if multiple assignments exist for the same OID 466 value?]] 468 7.2. Example: OBJECT IDENTIFIER Assignments of the IF-MIB 470 The translation of the OBJECT IDENTIFIER assignments and the value of 471 the MODULE-IDENTITY clause of the IF-MIB [RFC2863] is shown below. 473 container interfaces { 474 config false; 475 // ... 476 } 478 container ifMIB { 479 config false; 480 container ifMIBObjects { 481 // ... 482 } 484 container ifConformance { 485 container ifGroups { 486 // ... 487 } 488 container ifCompliances { 489 // ... 490 } 491 } 492 } 494 8. Translation of the OBJECT-TYPE Macro 496 The SMIv2 uses the OBJECT-TYPE macro to define objects and the 497 structure of conceptual tables. Objects exist either as scalars 498 (exactly one instance within an SNMP context) or columnar objects 499 (zero or multiple instances within an SNMP context) within conceptual 500 tables. A number of auxiliary objects define the index (key) of the 501 table. Furthermore, conceptual tables can be augmented by other 502 conceptual tables. All these differences must be taken into account 503 when mapping SMIv2 OBJECT-TYPE macro invocations to YANG. 505 8.1. Scalar and Columnar Object Translation Rules 507 The SMIv2 OBJECT-TYPE macro invocations defining scalars or columnar 508 objects are translated to YANG leaf statements. The name of the leaf 509 is the name associated with the SMIv2 OBJECT-TYPE macro invocation. 511 o The SMIv2 SYNTAX clause is mapped to the YANG type clause. 512 Embedded clauses are generates as described in Section 2. 514 o The SMIv2 UNITS clause is mapped to the YANG units statement. 516 o The SMIv2 MAX-ACCESS clause is ignored. 518 o The SMIv2 STATUS clause is mapped to the YANG status statement. 519 The generation of the YANG status statement is skipped if the 520 value of the STATUS clause is current. 522 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 523 statement. 525 o The SMIv2 REFERENCE clause is mapped to the YANG reference 526 statement. 528 o The value of the SMIv2 OBJECT-TYPE macro invocation is ignored. 530 8.2. Example: ifNumber and ifIndex of the IF-MIB 532 The translations of the ifNumber scalar object and the ifIndex 533 columnar object of the IF-MIB [RFC2863] are shown below. 535 leaf ifNumber { 536 type int32; 537 description 538 "The number of network interfaces (regardless of their 539 current state) present on this system."; 540 } 542 leaf ifIndex { 543 type if-mib:InterfaceIndex; 544 description 545 "A unique value, greater than zero, for each interface. It 546 is recommended that values are assigned contiguously 547 starting from 1. The value for each interface sub-layer 548 must remain constant at least from one re-initialization of 549 the entity's network management system to the next re- 550 initialization."; 551 } 553 8.3. Non-Augmenting Conceptual Table Translation Rules 555 An OBJECT-TYPE clause defining a non-augmenting conceptual table is 556 translated to a YANG container statement using the name of the table 557 OBJECT-TYPE clause. The OBJECT-TYPE clause representing a table row 558 is translated to a YANG list statement using the name of the row 559 OBJECT-TYPE clause. The rest of the clauses are translated as 560 follows: 562 o The SMIv2 SYNTAX clause is ignored. 564 o The SMIv2 UNITS clause is ignored. 566 o The SMIv2 MAX-ACCESS clause is ignored. 568 o The SMIv2 STATUS clause is mapped to the YANG status statement. 569 The generation of the YANG status statement is skipped if the 570 value of the STATUS clause is current. 572 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 573 statement. 575 o The SMIv2 REFERENCE clause is mapped to the YANG reference 576 statement. 578 o The SMIv2 INDEX clause is mapped to the YANG key clause listing 579 the columnar objects forming the key of the YANG list. 581 o The value of the SMIv2 OBJECT-TYPE macro invocation is ignored. 583 Within the list statement, YANG leaf statements are created for 584 columnar objects as described above. For objects listed in the SMIv2 585 INDEX clause that are not part of the conceptual table itself, YANG 586 leaf statements of type leafref pointing to the referenced definition 587 are created. 589 8.4. Example: ifTable of the IF-MIB 591 The translation of the definition of the ifTable of the IF-MIB 592 [RFC2863] is shown below. 594 container ifTable { 595 description 596 "A list of interface entries. The number of entries is 597 given by the value of ifNumber."; 599 list ifEntry { 600 key "ifIndex"; 601 description 602 "An entry containing management information applicable to a 603 particular interface."; 605 // ... 606 } 607 } 609 8.5. Example: ifRcvAddressTable of the IF-MIB 611 The translation of the definition of the ifRcvAddressTable of the IF- 612 MIB [RFC2863] is shown below. 614 container ifRcvAddressTable { 615 description 616 "This table contains an entry for each address (broadcast, 617 multicast, or uni-cast) for which the system will receive 618 packets/frames on a particular interface, except as follows: 620 - for an interface operating in promiscuous mode, entries 621 are only required for those addresses for which the system 622 would receive frames were it not operating in promiscuous 623 mode. 625 - for 802.5 functional addresses, only one entry is 626 required, for the address which has the functional address 627 bit ANDed with the bit mask of all functional addresses for 628 which the interface will accept frames. 630 A system is normally able to use any unicast address which 631 corresponds to an entry in this table as a source address."; 633 list ifRcvAddressEntry { 634 key "ifIndex ifRcvAddressAddress"; 635 description 636 "A list of objects identifying an address for which the 637 system will accept packets/frames on the particular 638 interface identified by the index value ifIndex."; 640 leaf ifIndex { 641 type leafref { 642 path "/if-mib:interfaces/if-mib:ifTable" + 643 "/if-mib:ifEntry/if-mib:ifIndex"; 644 } 645 description 646 "[Automatically generated leaf for a foreign index.]"; 647 } 649 leaf ifRcvAddressAddress { 650 type yang:phys-address; 651 description 652 "An address for which the system will accept packets/frames 653 on this entry's interface."; 654 } 656 // ... 657 } 658 } 660 8.6. Augmenting Conceptual Tables Translation Rules 662 An OBJECT-TYPE clause defining an augmenting conceptual table is 663 translated to a YANG container statement using the name of the table 664 OBJECT-TYPE clause. The OBJECT-TYPE clause representing a table row 665 is translated to a YANG augment statement using the path to the 666 augmented table. The rest of the clauses are translated as follows: 668 o The SMIv2 SYNTAX clause is ignored. 670 o The SMIv2 UNITS clause is ignored. 672 o The SMIv2 MAX-ACCESS clause is ignored. 674 o The SMIv2 STATUS clause is mapped to the YANG status statement. 675 The generation of the YANG status statement is skipped if the 676 value of the STATUS clause is current. 678 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 679 statement. 681 o The SMIv2 REFERENCE clause is mapped to the YANG reference 682 statement. 684 o The value of the SMIv2 OBJECT-TYPE macro invocation is ignored. 686 Within the augment statement, YANG leaf nodes are created as 687 described above. 689 8.7. Example: ifXTable of the IF-MIB 691 The translation of the definition of the ifXTable of the IF-MIB 692 [RFC2863] is shown below. 694 container ifXTable { 695 description 696 "A list of interface entries. The number of entries is 697 given by the value of ifNumber. This table contains 698 additional objects for the interface table." 700 augment "/if-mib:interfaces/if-mib:ifTable" + 701 "/if-mib:ifEntry" { 702 description 703 "An entry containing additional management information 704 applicable to a particular interface."; 706 // ... 707 } 709 } 711 9. Translation of the OBJECT-IDENTITY Macro 713 Invocations of the OBJECT-IDENTITY macro are translated into YANG 714 container statements. 716 9.1. OBJECT-IDENTITY Translation Rules 718 The name of the OBJECT-IDENTITY macro invocation is used as the name 719 of the generated container statement. Any generated top-level 720 container must be marked as config false. The clauses of the SMIv2 721 OBJECT-IDENTITY macro are mapped to YANG statements as follows: 723 o The SMIv2 STATUS clause is mapped to the YANG status statement. 724 The generation of the YANG status statement is skipped if the 725 value of the STATUS clause is current. 727 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 728 statement. 730 o The SMIv2 REFERENCE clause is mapped to the YANG reference 731 statement. 733 9.2. Example: diffServTBParamSimpleTokenBucket of the DIFFSERV-MIB 735 The translation of the diffServTBParamSimpleTokenBucket of the 736 DIFFSERV-MIB [RFC3289] is shown below. 738 container diffServTBParamSimpleTokenBucket { 739 description 740 "Two Parameter Token Bucket Meter as described in the Informal 741 Differentiated Services Model section 5.2.3."; 742 } 744 [[TODO: Should we in addition generate toplevel YANG identities so 745 that definitions can be referenced from new YANG modules? See the 746 example below (which assumes we provide an smiv2:object-identity 747 base).]] 749 identity diffServTBParamSimpleTokenBucket { 750 base "smiv2:object-identity"; 751 description 752 "Two Parameter Token Bucket Meter as described in the Informal 753 Differentiated Services Model section 5.2.3."; 754 } 756 10. Translation of the NOTIFICATION-TYPE Macro 758 The SMIv2 provides the NOTIFICATION-TYPE macro to define 759 notifications. YANG provides the notification statement for the same 760 purpose. 762 10.1. NOTIFICATION-TYPE Translation Rules 764 The name of the NOTIFICATION-TYPE macro invocation is used as the 765 name of the generated notification statement. The clauses of the 766 NOTIFICATION-TYPE macro are mapped to YANG statements embedded in the 767 notification statement as follows. 769 o The SMIv2 OBJECTS clause is mapped to a sequence of YANG 770 containers. For each object listed in the OBJECTS clause value, a 771 YANG container statement is generated. The name of this container 772 is the name of the notification and the name of the current 773 concatenated by a hyphen. If the current object belongs a 774 conceptual table, then a sequence of leaf statements is generated 775 for each INDEX of the SMIv2 conceptual table. Next, a leaf 776 statement is generated for the current object. All container 777 leafs are marked as config false. 779 o The SMIv2 STATUS clause is mapped to the YANG status statement. 780 The generation of the YANG status statement is skipped if the 781 value of the STATUS clause is current. 783 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 784 statement. 786 o The SMIv2 REFERENCE clause is mapped to the YANG reference 787 statement. 789 o The value of the SMIv2 NOTIFICATION-TYPE macro invocation is 790 ignored. 792 10.2. Example: linkDown NOTIFICATION-TYPE of IF-MIB 794 The translation of the linkDown notification of the IF-MIB [RFC2863] 795 is shown below. 797 notification linkDown { 798 description 799 "A linkDown trap signifies that the SNMP entity, acting in 800 an agent role, has detected that the ifOperStatus object for 801 one of its communication links is about to enter the down 802 state from some other state (but not from the notPresent 803 state). This other state is indicated by the included value 804 of ifOperStatus."; 806 container linkDown-ifIndex { 807 config false; 808 leaf ifIndex { 809 type leafref { 810 path "/if-mib:interfaces/if-mib:ifTable" + 811 "/if-mib:ifEntry/if-mib:ifIndex"; 812 } 813 description 814 "[Automatically generated leaf for a notification.]"; 815 } 816 } 818 container linkDown-ifAdminStatus { 819 config false; 820 leaf ifIndex { 821 type leafref { 822 path "/if-mib:interfaces/if-mib:ifTable" + 823 "/if-mib:ifEntry/if-mib:ifIndex"; 824 } 825 description 826 "[Automatically generated leaf for a notification.]"; 827 } 828 leaf ifAdminStatus { 829 type enumeration { 830 enum up { value 1; } 831 enum down { value 2; } 832 enum testing { value 3; } 833 } 834 description 835 "The desired state of the interface. The testing(3) state 836 indicates that no operational packets can be passed. When a 837 managed system initializes, all interfaces start with 838 ifAdminStatus in the down(2) state. As a result of either 839 explicit management action or per configuration information 840 retained by the managed system, ifAdminStatus is then 841 changed to either the up(1) or testing(3) states (or remains 842 in the down(2) state)."; 843 } 844 } 846 container linkDown-ifOperStatus { 847 config false; 848 leaf ifIndex { 849 type leafref { 850 path "/if-mib:interfaces/if-mib:ifTable" + 851 "/if-mib:ifEntry/if-mib:ifIndex"; 853 } 854 description 855 "[Automatically generated leaf for a notification.]"; 856 } 857 leaf ifOperStatus { 858 type enumeration { 859 enum up { value 1; } 860 enum down { value 2; } 861 enum testing { value 3; } 862 enum unknown { value 4; } 863 enum dormant { value 5; } 864 enum notPresent { value 6; } 865 enum lowerLayerDown { value 7; } 866 } 867 description 868 "The current operational state of the interface. The 869 testing(3) state indicates that no operational packets can 870 be passed. If ifAdminStatus is down(2) then ifOperStatus 871 should be down(2). If ifAdminStatus is changed to up(1) 872 then ifOperStatus should change to up(1) if the interface is 873 ready to transmit and receive network traffic; it should 874 change to dormant(5) if the interface is waiting for 875 external actions (such as a serial line waiting for an 876 incoming connection); it should remain in the down(2) state 877 if and only if there is a fault that prevents it from going 878 to the up(1) state; it should remain in the notPresent(6) 879 state if the interface has missing (typically, hardware) 880 components."; 881 } 882 } 883 } 885 11. YANG Language Extension Definition 887 This section defines some YANG extension statements that can be used 888 to carry additional information from the original SMIv2 module into 889 the YANG module. The YANG module references [RFC2578] and [RFC2579]. 891 file "ietf-yang-smiv2@2011-03-14.yang" 893 module ietf-yang-smiv2 { 895 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-smiv2"; 896 prefix "smiv2"; 898 organization 899 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 901 contact 902 "WG Web: 903 WG List: 905 WG Chair: David Kessens 906 908 WG Chair: Juergen Schoenwaelder 909 911 Editor: Juergen Schoenwaelder 912 "; 914 description 915 "This module defines YANG extensions that are used to translate 916 SMIv2 concepts into YANG. 918 Copyright (c) 2011 IETF Trust and the persons identified as 919 authors of the code. All rights reserved. 921 Redistribution and use in source and binary forms, with or 922 without modification, is permitted pursuant to, and subject 923 to the license terms contained in, the Simplified BSD License 924 set forth in Section 4.c of the IETF Trust's Legal Provisions 925 Relating to IETF Documents 926 (http://trustee.ietf.org/license-info). 928 This version of this YANG module is part of RFC XXXX; see 929 the RFC itself for full legal notices."; 930 // RFC Ed.: replace XXXX with actual RFC number and remove this note 932 // RFC Ed.: please update the date to the date of publication 933 revision 2011-03-14 { 934 description 935 "Initial revision."; 936 reference 937 "RFC XXXX: Translation of SMIv2 MIB Modules to YANG Modules"; 938 // RFC Ed.: replace XXXX with actual RFC number and remove this note 939 } 941 extension oid { 942 argument "value"; 943 description 944 "The oid statement takes as an argument the object identifier 945 assigned to an SMIv2 definition. The object identifier value 946 is written in decimal dotted notation."; 947 reference 948 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 949 } 951 extension display-hint { 952 argument "format"; 953 description 954 "The display-hint statement takes as an argument the DISPLAY-HINT 955 assigned to an SMIv2 textual convention."; 956 reference 957 "RFC2579: Textual Conventions for SMIv2"; 958 } 960 extension max-access { 961 argument "access"; 962 description 963 "The max-access statement takes as an argument the MAX-ACCESS 964 assigned to an SMIv2 object definition"; 965 reference 966 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 967 } 969 extension defval { 970 argument "value"; 971 description 972 "The defval statement takes as an argument a default value defined 973 by an SMIv2 DEFVAL clause."; 974 reference 975 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 976 } 978 } 980 982 12. IANA Considerations 984 This document registers two URIs in the IETF XML registry [RFC3688]. 985 Following the format in RFC 3688, the following registrations have 986 been made. 988 URI: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 990 Registrant Contact: The NETMOD WG of the IETF. 992 XML: N/A, the requested URI is an XML namespace. 994 URI: urn:ietf:params:xml:ns:yang:smiv2 996 Registrant Contact: The NETMOD WG of the IETF. 998 XML: N/A, the requested URI is an XML namespace. 1000 This document registers a YANG module in the YANG Module Names 1001 registry [RFC6020]. 1003 name: ietf-yang-smiv2 1004 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 1005 prefix: smiv2 1006 reference: RFC XXXX 1008 13. Security Considerations 1010 This document defines a translation of the SMIv2 data modeling 1011 language to the YANG data modeling language. The translation itself 1012 has no security impact on the Internet. 1014 Users of translated SMIv2 data models that have been published as 1015 RFCs should consult the security considerations of the respective 1016 RFCs. In addition, the security considerations for the NETCONF 1017 protocol [RFC4741] should be consulted to understand how NETCONF 1018 protects potentially sensitive information. 1020 14. References 1022 14.1. Normative References 1024 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1025 Requirement Levels", BCP 14, RFC 2119, March 1997. 1027 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1028 Schoenwaelder, Ed., "Structure of Management Information 1029 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1031 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1032 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 1033 STD 58, RFC 2579, April 1999. 1035 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 1036 "Conformance Statements for SMIv2", STD 58, RFC 2580, 1037 April 1999. 1039 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1040 the Network Configuration Protocol (NETCONF)", RFC 6020, 1041 October 2010. 1043 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1044 October 2010. 1046 14.2. Informative References 1048 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 1049 MIB", RFC 2863, June 2000. 1051 [RFC3289] Baker, F., Chan, K., and A. Smith, "Management Information 1052 Base for the Differentiated Services Architecture", 1053 RFC 3289, May 2002. 1055 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1056 January 2004. 1058 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1059 December 2006. 1061 Appendix A. Changes from 01 to 02 1063 o Preserving the SMIv2 nesting instead of a flat translation. 1065 o Inlined the examples to avoid page flipping exercises. 1067 o Clarifications and several editorial improvements. 1069 Appendix B. Changes from 00 to 01 1071 o Translation is config false; top-level container are marked as 1072 config false. 1074 o Revised the overall document structure, added a YANG module for 1075 the definition of YANG extensions (smiv2:oid, smiv2:display-hint, 1076 smiv2:max-access, smiv2:defval), moved the IF-MIB example into an 1077 appendix. 1079 o Alignment with RFC 6020 and RFC 6021. 1081 o Started to use [[TODO]] markers inside the text instead of 1082 maintaining a TODO list as an appendix. 1084 Author's Address 1086 Juergen Schoenwaelder 1087 Jacobs University 1089 Email: j.schoenwaelder@jacobs-university.de