idnits 2.17.1 draft-ietf-netmod-smi-yang-01.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 (July 1, 2011) is 4677 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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) 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 July 1, 2011 5 Expires: January 2, 2012 7 Translation of SMIv2 MIB Modules to YANG Modules 8 draft-ietf-netmod-smi-yang-01 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 January 2, 2012. 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 . . . . . . . . . . . . 10 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 . . . . . . . . . 14 80 8. Translation of the OBJECT-TYPE Macro . . . . . . . . . . . . . 15 81 8.1. Scalar and Columnar Object Translation Rules . . . . . . . 15 82 8.2. Example: ifNumber and ifIndex of the IF-MIB . . . . . . . 16 83 8.3. Non-Augmenting Conceptual Table Translation Rules . . . . 16 84 8.4. Example: ifTable of the IF-MIB . . . . . . . . . . . . . . 18 85 8.5. Example: ifRcvAddressTable of the IF-MIB . . . . . . . . . 18 86 8.6. Augmenting Conceptual Tables Translation Rules . . . . . . 20 87 8.7. Example: ifXTable of the IF-MIB . . . . . . . . . . . . . 21 88 9. Translation of the OBJECT-IDENTITY Macro . . . . . . . . . . . 22 89 9.1. OBJECT-IDENTITY Translation Rules . . . . . . . . . . . . 22 90 9.2. Example: diffServTBParamSimpleTokenBucket of the 91 DIFFSERV-MIB . . . . . . . . . . . . . . . . . . . . . . . 22 92 10. Translation of the NOTIFICATION-TYPE Macro . . . . . . . . . . 23 93 10.1. NOTIFICATION-TYPE Translation Rules . . . . . . . . . . . 23 94 10.2. Example: linkDown NOTIFICATION-TYPE of IF-MIB . . . . . . 23 95 11. YANG Language Extension Definition . . . . . . . . . . . . . . 26 96 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 97 13. Security Considerations . . . . . . . . . . . . . . . . . . . 30 98 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 99 14.1. Normative References . . . . . . . . . . . . . . . . . . . 31 100 14.2. Informative References . . . . . . . . . . . . . . . . . . 31 101 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 32 103 1. Introduction 105 This document describes an translation of SMIv2 [RFC2578], [RFC2579], 106 [RFC2580] MIB modules into YANG [RFC6020] modules, enabling read-only 107 access to data objects defined in SMIv2 MIB modules via NETCONF. The 108 mapping is illustrated by examples showing the translation of part of 109 the IF-MIB [RFC2863] SMIv2 module and the DIFFSERV-MIB [RFC3289] 110 SMIv2 module. 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14, [RFC2119]. 117 2. Mapping of Special Types 119 The SMIv2 base types and some well known derived textual-conventions 120 are mapped to YANG types according to Table 1. The mapping of the 121 OCTET STRING depends on the context. If an OCTET STRING type has an 122 associated DISPLAY-HINT, then the corresponding YANG base type is the 123 string type. Otherwise, the binary type is used. Similarly, the 124 mapping of the INTEGER type depends on its usage as an enumeration or 125 a 32-bit integral type. Implementations are encouraged to provide 126 options to handle situations where DISPLAY-HINTs are added during a 127 revision of a module and backwards compatibility must be preserved. 129 Mapping of SMIv2 types to YANG types 131 +------------+----------------+-----------------+-------------------+ 132 | SMIv2 | SMIv2 Type | YANG Module | YANG Type | 133 | Module | | | | 134 +------------+----------------+-----------------+-------------------+ 135 | SNMPv2-SMI | INTEGER | | enumeration | 136 | SNMPv2-SMI | INTEGER | | int32 | 137 | SNMPv2-SMI | Integer32 | | int32 | 138 | SNMPv2-SMI | OCTET STRING | | binary | 139 | SNMPv2-SMI | OCTET STRING | | string | 140 | SNMPv2-SMI | OBJECT | ietf-yang-types | object-identifier | 141 | | IDENTIFIER | | | 142 | SNMPv2-SMI | BITS | | bits | 143 | SNMPv2-SMI | IpAddress | ietf-inet-types | ipv4-address | 144 | SNMPv2-SMI | Counter32 | ietf-yang-types | counter32 | 145 | SNMPv2-SMI | Gauge32 | ietf-yang-types | gauge32 | 146 | SNMPv2-SMI | TimeTicks | ietf-yang-types | timeticks | 147 | SNMPv2-SMI | Opaque | | binary | 148 | SNMPv2-SMI | Counter64 | ietf-yang-types | counter64 | 149 | SNMPv2-SMI | Unsigned32 | | uint32 | 150 | SNMPv2-TC | PhysAddress | ietf-yang-types | phys-address | 151 | SNMPv2-TC | MacAddress | ietf-yang-types | mac-address | 152 | SNMPv2-TC | TimeStamp | ietf-yang-types | timestamp | 153 +------------+----------------+-----------------+-------------------+ 155 Table 1 157 The mappings shown in Table 1 may impact the imports of the generated 158 YANG module since some SMIv2 types and textual-conventions map to 159 YANG types defined in the ietf-yang-types and ietf-inet-types YANG 160 modules [RFC6021]. Implementations MUST add any additional imports 161 required by the type mapping. 163 3. Module Prefix Generation 165 The input of the prefix generation algorithm is a set of prefixes 166 (usually derived from imported module names) and a specific module 167 name to be converted into a prefix. The algorithm described below 168 produces a prefix for the given module name that is unique within the 169 set of prefixes. 171 Special prefixes for well known SMIv2 and YANG modules 173 +---------------------+--------+ 174 | YANG / SMIv2 Module | Prefix | 175 +---------------------+--------+ 176 | ietf-yang-types | yang | 177 | ietf-inet-types | inet | 178 | ietf-yang-smiv2 | smiv2 | 179 +---------------------+--------+ 181 Table 2 183 o First, some predefined translations mapping well known SMIv2 and 184 YANG modules to short prefixes are tried (see Table 2). If a 185 fixed translation rule exists and leads to a conflict free prefix, 186 then the fixed translation is used. 188 o Otherwise, prefixes are generated by tokenizing an SMIv2 module 189 name, using hyphens as token separators. The tokens derived from 190 a module name are converted to lowercase characters. The prefix 191 then becomes the shortest sequence of token concatenated using 192 hyphens as separators, which includes at least two token and which 193 is unique among all prefixes used in the YANG module. 195 In the worst case, the prefix derived from an SMIv2 module name 196 becomes the SMIv2 module name translated to lower-case. But on 197 average, much shorter prefixes are generated. 199 4. Translation of SMIv2 Modules and SMIv2 IMPORT Clauses 201 SMIv2 modules are mapped to corresponding YANG modules. The YANG 202 module name MUST be the same as the SMIv2 module name. 204 The YANG namespace MUST be constructed out of a constant prefix, 205 which followed by the SMIv2 module name. Since SMIv2 module names 206 can be assumed to be unique (see Section 3 in [RFC2578]), the 207 resulting YANG namespace is unique. The registered prefix is 208 urn:ietf:params:xml:ns:yang:smiv2:, see the IANA considerations in 209 Section 12. 211 The YANG prefix MAY be derived from the SMIv2 module name using the 212 module prefix generation algorithm described in Section 3. The YANG 213 prefix is supposed to be short and it must be unique within the set 214 of all prefixes used by a YANG module. The algorithm described in 215 Section 3 generates such prefixes. 217 SMIv2 IMPORT clauses are translated to YANG import statements. One 218 major difference between the SMIv2 import mechanism and the YANG 219 import mechanism is that SMIv2 IMPORT clauses import specific symbols 220 from an SMIv2 module while the YANG import statement imports all 221 symbols of the referenced YANG module. 223 SMIv2 imports that are ignored in YANG 225 +--------------+--------------------+ 226 | SMIv2 Module | SMIv2 Symbol | 227 +--------------+--------------------+ 228 | SNMPv2-SMI | MODULE-IDENTITY | 229 | SNMPv2-SMI | OBJECT-IDENTITY | 230 | SNMPv2-SMI | OBJECT-TYPE | 231 | SNMPv2-SMI | NOTIFICATION-TYPE | 232 | SNMPv2-SMI | mib-2 | 233 | SNMPv2-TC | TEXTUAL-CONVENTION | 234 | SNMPv2-MIB | snmpTraps | 235 | SNMPv2-SMI | * all symbols * | 236 | SNMPv2-CONF | * all symbols * | 237 +--------------+--------------------+ 239 Table 3 241 In order to produce correct and complete YANG import statements, the 242 following rules MUST be used: 244 o Ignore all imports listed in Table 3. Note that the modules 245 SNMPv2-SMI and SNMPv2-CONF are completely ignored since all 246 definitions in these modules are translated by translation rules 247 defined in this document. 249 o Add any imports required by the type translations according to the 250 type mapping table. This requires to consider all the types used 251 in the translation unit in order to produce the imports. 253 The generated import statements use the untranslated SMIv2 module 254 names or the names of well-known YANG modules as their argument. The 255 import statement must contain a prefix statement. The prefixes MAY 256 be generated by applying the module prefix generation algorithm 257 described in Section 3. 259 4.1. Example: IMPORTS of IF-MIB 261 The translation of the IF-MIB [RFC2863] leads to the YANG module 262 frame and the import statements shown below. The prefix is the 263 translation of the SMIv2 module name IF-MIB to lowercase (consisting 264 of two tokens and thus no further abbreviation). 266 module IF-MIB { 268 namespace "urn:ietf:params:xml:ns:yang:smiv2:IF-MIB"; 269 prefix "if-mib"; 271 import IANAifType-MIB { prefix "ianaiftype-mib"; } 272 import SNMPv2-TC { prefix "smiv2-tc"; } 273 import ietf-yang-types { prefix "yang"; } 274 import ietf-yang-smiv2 { prefix "smiv2"; } 275 } 277 5. Translation of the MODULE-IDENTITY Macro 279 The SMIv2 requires an invocation of the MODULE-IDENTITY macro to 280 provide contact and revision history for a MIB module. The clauses 281 of the SMIv2 MODULE-IDENTITY macro MUST be translated into YANG 282 statements as detailed below. 284 5.1. MODULE-IDENTITY Translation Rules 286 o The SMIv2 ORGANIZATION clause is mapped to the YANG organization 287 statement. 289 o The SMIv2 CONTACT-INFO clause is mapped to the YANG contact 290 statement. 292 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 293 statement. 295 o Each SMIv2 REVISION clause is mapped to a YANG revision statement. 296 The revision is identified by the date argument of the SMIv2 297 REVISION clause. DESCRIPTION sub-clauses of REVISION clauses are 298 mapped to corresponding description statement nested in revision 299 clauses. 301 o The SMIv2 LAST-UPDATED clause is ignored if the associated date 302 matches a REVISION clause. Otherwise, an additional revision 303 statement is generated. 305 o The name of the MODULE-IDENTITY macro invocation is used to 306 generate a top-level container statement. This container MUST be 307 config false. 309 o The object identifier value of the invocation of the SMIv2 MODULE- 310 IDENTITY MAY be translated into an smiv2:oid statement contained 311 in the container representing the MODULE-IDENTITY macro 312 invocation, see the YANG extension defined in Section 11. 314 While all proper SMIv2 modules must have exactly one MODULE-IDENTITY 315 macro invocation, there are a few notable exceptions. The modules 316 defining the SMIv2 language (i.e., the SNMPv2-SMI, SNMPv2-TC, and 317 SNMPv2-CONF modules) do not invoke the MODULE-IDENTITY macro. 318 Furthermore, SMIv2 modules generated from SMIv1 modules may miss an 319 invocation of the MODULE-IDENTITY macro as well. In such cases, it 320 is preferable to not generate organization, contact, description, and 321 revision statements. 323 5.2. Example: MODULE-IDENTITY of IF-MIB 325 The translation of the MODULE-IDENTITY of the IF-MIB [RFC2863] leads 326 to the following YANG statements: 328 organization 329 "IETF Interfaces MIB Working Group"; 331 contact 332 "Keith McCloghrie 333 Cisco Systems, Inc. 334 170 West Tasman Drive 335 San Jose, CA 95134-1706 336 US 338 408-526-5260 339 kzm@cisco.com"; 341 description 342 "The MIB module to describe generic objects for network 343 interface sub-layers. This MIB is an updated version of 344 MIB-II's ifTable, and incorporates the extensions defined in 345 RFC 1229."; 347 revision "2000-06-14" { 348 description 349 "Clarifications agreed upon by the Interfaces MIB WG, and 350 published as RFC 2863."; 351 } 352 revision "1996-02-28" { 353 description 354 "Revisions made by the Interfaces MIB WG, and published in 355 RFC 2233."; 356 } 357 revision "1993-11-08" { 358 description 359 "Initial revision, published as part of RFC 1573."; 360 } 362 container ifMIB { 363 config false; 364 description 365 "[Automatically generated top-level container.]"; 366 smiv2:oid "1.3.6.1.2.1.31"; 367 } 369 6. Translation of the TEXTUAL-CONVENTION Macro 371 The SMIv2 uses invocations of the TEXTUAL-CONVENTION macro to define 372 new types derived from the SMIv2 base types. Invocations of the 373 TEXTUAL-CONVENTION macro MUST be translated into YANG typedef 374 statements as detailed below. 376 6.1. TEXTUAL-CONVENTION Translation Rules 378 The name of the TEXTUAL-CONVENTION macro invocation is used as the 379 name of the generated typedef statement. The clauses of the SMIv2 380 TEXTUAL-CONVENTION macro are mapped to YANG statements embedded in 381 the typedef statement as follows: 383 o The SMIv2 DISPLAY-HINT clause is used to determine the type 384 mapping of types derived form the OCTET STRING type as explained 385 in Section 2. Furthermore, the DISPLAY-HINT value MAY be used to 386 generate a regular expression for the YANG pattern statement 387 within the type statement. 389 o The SMIv2 DISPLAY-HINT MAY be translated into an smiv2:display- 390 hint statement, see the YANG extension defined in Section 11. 392 o The SMIv2 STATUS clause is mapped to the YANG status statement. 393 The generation of the YANG status statement is skipped if the 394 value of the STATUS clause is current. 396 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 397 statement. 399 o The SMIv2 REFERENCE clause is mapped to the YANG reference 400 statement. 402 o The SMIv2 SYNTAX clause is mapped to the YANG type statement. 403 SMIv2 range restrictions are mapped to YANG range statements while 404 SMIv2 length restrictions are mapped to YANG length statements. 405 SMIv2 INTEGER enumerations and SMIv2 BITS are mapped to YANG enum 406 / value and bit / position statements. 408 This translation assumes that labels of named numbers and named bits 409 do not change when an SMIv2 module is revised. This is consistent 410 with the clarification of the SMIv2 module revision rules in Section 411 4.9 of [RFC4181]. 413 6.2. Example: OwnerString and InterfaceIndex of IF-MIB 415 The translation of the OwnerString and InterfaceIndex textual- 416 conventions of the IF-MIB [RFC2863] are shown below. 418 typedef OwnerString { 419 type string { 420 length "0..255"; 421 pattern '\p{IsBasicLatin}{0,255}'; 422 } 423 status deprecated; 424 description 425 "This data type is used to model an administratively 426 assigned name of the owner of a resource. This information 427 is taken from the NVT ASCII character set. It is suggested 428 that this name contain one or more of the following: ASCII 429 form of the manager station's transport address, management 430 station name (e.g., domain name), network management 431 personnel's name, location, or phone number. In some cases 432 the agent itself will be the owner of an entry. In these 433 cases, this string shall be set to a string starting with 434 'agent'."; 435 smiv2:display-hint "255a"; 436 } 438 typedef InterfaceIndex { 439 type int32 { 440 range "1..2147483647"; 441 } 442 description 443 "A unique value, greater than zero, for each interface or 444 interface sub-layer in the managed system. It is 445 recommended that values are assigned contiguously starting 446 from 1. The value for each interface sub-layer must remain 447 constant at least from one re-initialization of the entity's 448 network management system to the next re-initialization."; 449 smiv2:display-hint "d"; 450 } 452 6.3. Example: IfDirection of the DIFFSERV-MIB 454 The translation of the IfDirection textual-convention of the 455 DIFFSERV-MIB [RFC3289] is shown below. 457 typedef IfDirection { 458 type enumeration { 459 enum inbound { value 1; } 460 enum outbound { value 2; } 461 } 462 description 463 "IfDirection specifies a direction of data travel on an 464 interface. 'inbound' traffic is operated on during reception from 465 the interface, while 'outbound' traffic is operated on prior to 466 transmission on the interface."; 467 } 469 7. Translation of OBJECT IDENTIFIER Assignments 471 The SMIv2 uses OBJECT IDENTIFIER assignments to introduce names for 472 intermediate nodes in the OBJECT IDENTIFIER tree. OBJECT IDENTIFIER 473 assignments are not translated into YANG statements. 475 8. Translation of the OBJECT-TYPE Macro 477 The SMIv2 uses the OBJECT-TYPE macro to define objects and the 478 structure of conceptual tables. Objects exist either as scalars 479 (exactly one instance within an SNMP context) or columnar objects 480 within conceptual tables (zero or multiple instances within an SNMP 481 context). A number of auxiliary objects define the index (key) of a 482 conceptual table. Furthermore, conceptual tables can be augmented by 483 other conceptual tables. All these differences must be taken into 484 account when translating SMIv2 OBJECT-TYPE macro invocations to YANG. 485 Invocations of the OBJECT-TYPE macro MUST be translated into YANG 486 statements as detailed below. 488 8.1. Scalar and Columnar Object Translation Rules 490 SMIv2 OBJECT-TYPE macro invocations defining scalars or columnar 491 objects with a MAX-ACCESS of "not-accessible", "read-only", 492 "read-write" and ""read-create" are translated to YANG leaf 493 statements. The name of the leaf is the name associated with the 494 SMIv2 OBJECT-TYPE macro invocation. SMIv2 OBJECT-TYPE macro 495 invocations with a MAX-ACCESS of "accessible-for-notify" are not 496 translated to YANG data tree leafs but instead into YANG notification 497 leafs. 499 All leaf statements for scalar objects are created in the top-level 500 container representing the SMIv2 module, see Section 5.1. The leaf 501 statements representing columnar objects are created in the list 502 representing a conceptual row, see Section 8.3. 504 o The SMIv2 SYNTAX clause is mapped to the YANG type statement. 505 SMIv2 range restrictions are mapped to YANG range statements while 506 SMIv2 length restrictions are mapped to YANG length statements. 507 SMIv2 INTEGER enumerations and SMIv2 BITS are mapped to YANG enum 508 / value and bit / position statements. 510 o The SMIv2 UNITS clause is mapped to the YANG units statement. 512 o The SMIv2 MAX-ACCESS MAY be translated into an smiv2:max-access 513 statement, see the YANG extension defined in Section 11. 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 value of the SMIv2 OBJECT-TYPE macro invocation MAY be 526 translated into an smiv2:oid statement, see the YANG extension 527 defined in Section 11. 529 This translation assumes that labels of named numbers and named bits 530 do not change when an SMIv2 module is revised. This is consistent 531 with the clarification of the SMIv2 module revision rules in Section 532 4.9 of [RFC4181]. 534 8.2. Example: ifNumber and ifIndex of the IF-MIB 536 The translations of the ifNumber scalar object and the ifIndex 537 columnar object of the IF-MIB [RFC2863] are shown below. 539 leaf ifNumber { 540 type int32; 541 description 542 "The number of network interfaces (regardless of their 543 current state) present on this system."; 544 smiv2:max-access "read-only"; 545 smiv2:oid "1.3.6.1.2.1.2.1"; 546 } 548 leaf ifIndex { 549 type if-mib:InterfaceIndex; 550 description 551 "A unique value, greater than zero, for each interface. It 552 is recommended that values are assigned contiguously 553 starting from 1. The value for each interface sub-layer 554 must remain constant at least from one re-initialization of 555 the entity's network management system to the next re- 556 initialization."; 557 smiv2:max-access "read-only"; 558 smiv2:oid "1.3.6.1.2.1.2.2.1.1"; 559 } 561 8.3. Non-Augmenting Conceptual Table Translation Rules 563 An OBJECT-TYPE macro invocation defining a non-augmenting conceptual 564 table is translated to a YANG container statement using the name of 565 the OBJECT-TYPE macro invocation. This container is created in the 566 top-level container representing the SMIv2 module. The clauses of 567 the macro are translated as follows: 569 o The SMIv2 SYNTAX clause is ignored 571 o The SMIv2 UNITS clause is ignored. 573 o The SMIv2 MAX-ACCESS clause is ignored. 575 o The SMIv2 STATUS clause is mapped to the YANG status statement. 576 The generation of the YANG status statement is skipped if the 577 value of the STATUS clause is current. 579 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 580 statement. 582 o The SMIv2 REFERENCE clause is mapped to the YANG reference 583 statement. 585 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 586 translated into an smiv2:oid statement, see the YANG extension 587 defined in Section 11. 589 An OBJECT-TYPE macro invocation defining a conceptual row is 590 translated to a YANG list statement. It is contained in the YANG 591 container representing the conceptual table. The generated list uses 592 the name of the row OBJECT-TYPE macro invocation. The clauses of the 593 OBJECT-TYPE macro are translated as follows: 595 o The SMIv2 SYNTAX clause is ignored. 597 o The SMIv2 UNITS clause is ignored. 599 o The SMIv2 MAX-ACCESS clause is ignored. 601 o The SMIv2 STATUS clause is mapped to the YANG status statement. 602 The generation of the YANG status statement is skipped if the 603 value of the STATUS clause is current. 605 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 606 statement. 608 o The SMIv2 REFERENCE clause is mapped to the YANG reference 609 statement. 611 o The SMIv2 INDEX clause is mapped to the YANG key clause listing 612 the columnar objects forming the key of the YANG list. 614 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 615 translated into an smiv2:oid statement, see the YANG extension 616 defined in Section 11. 618 Within the list statement, YANG leaf statements are created for 619 columnar objects as described in Section 8.1. For objects listed in 620 the SMIv2 INDEX clause that are not part of the conceptual table 621 itself, YANG leaf statements of type leafref pointing to the 622 referenced definition are created. 624 8.4. Example: ifTable of the IF-MIB 626 The translation of the definition of the ifTable of the IF-MIB 627 [RFC2863] is shown below. 629 container ifTable { 630 config false; 631 description 632 "A list of interface entries. The number of entries is 633 given by the value of ifNumber."; 634 smiv2:oid "1.3.6.1.2.1.2.2"; 636 list ifEntry { 637 key "ifIndex"; 638 description 639 "An entry containing management information applicable to a 640 particular interface."; 641 smiv2:oid "1.3.6.1.2.1.2.2.1"; 643 leaf ifIndex { 644 type if-mib:InterfaceIndex; 645 description 646 "A unique value, greater than zero, for each interface. It 647 is recommended that values are assigned contiguously 648 starting from 1. The value for each interface sub-layer 649 must remain constant at least from one re-initialization of 650 the entity's network management system to the next re- 651 initialization."; 652 smiv2:max-access "read-only"; 653 smiv2:oid "1.3.6.1.2.1.2.2.1.1"; 654 } 656 // ... 657 } 658 } 660 8.5. Example: ifRcvAddressTable of the IF-MIB 662 The translation of the definition of the ifRcvAddressTable of the IF- 663 MIB [RFC2863] is shown below. 665 container ifRcvAddressTable { 666 description 667 "This table contains an entry for each address (broadcast, 668 multicast, or uni-cast) for which the system will receive 669 packets/frames on a particular interface, except as follows: 671 - for an interface operating in promiscuous mode, entries 672 are only required for those addresses for which the system 673 would receive frames were it not operating in promiscuous 674 mode. 676 - for 802.5 functional addresses, only one entry is 677 required, for the address which has the functional address 678 bit ANDed with the bit mask of all functional addresses for 679 which the interface will accept frames. 681 A system is normally able to use any unicast address which 682 corresponds to an entry in this table as a source address."; 683 smiv2:oid "1.3.6.1.2.1.31.1.4"; 685 list ifRcvAddressEntry { 686 key "ifIndex ifRcvAddressAddress"; 687 description 688 "A list of objects identifying an address for which the 689 system will accept packets/frames on the particular 690 interface identified by the index value ifIndex."; 691 smiv2:oid "1.3.6.1.2.1.31.1.4.1"; 693 leaf ifIndex { 694 type leafref { 695 path "/if-mib:ifMIB/if-mib:ifTable" + 696 "/if-mib:ifEntry/if-mib:ifIndex"; 697 } 698 description 699 "[Automatically generated leaf for a foreign index.]"; 700 } 702 leaf ifRcvAddressAddress { 703 type yang:phys-address; 704 description 705 "An address for which the system will accept packets/frames 706 on this entry's interface."; 707 smiv2:max-access "not-accessible"; 708 smiv2:oid "1.3.6.1.2.1.31.1.4.1.1"; 709 } 711 // ... 712 } 713 } 715 8.6. Augmenting Conceptual Tables Translation Rules 717 An OBJECT-TYPE macro invocation defining an augmenting conceptual 718 table is not translated to a YANG statement. The name assigned by 719 the OBJECT-TYPE macro invocation to the augmenting conceptual table 720 MAY be captured in a comment. The clauses of the macro are 721 translated as follows: 723 o The SMIv2 SYNTAX clause is ignored. 725 o The SMIv2 UNITS clause is ignored. 727 o The SMIv2 MAX-ACCESS clause is ignored. 729 o The SMIv2 STATUS clause is ignored. 731 o The SMIv2 DESCRIPTION clause MAY be captured in a comment. 733 o The SMIv2 REFERENCE clause MAY be captured in a comment. 735 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 736 captured in a comment. 738 An OBJECT-TYPE macro invocation defining a conceptual row 739 augmentation is translated to a YANG augment statement using the path 740 to the augmented table as its argument. The clauses of the OBJECT- 741 TYPE macro are translated as follows: 743 o The SMIv2 SYNTAX clause is ignored. 745 o The SMIv2 UNITS clause is ignored. 747 o The SMIv2 MAX-ACCESS clause is ignored. 749 o The SMIv2 STATUS clause is mapped to the YANG status statement. 750 The generation of the YANG status statement is skipped if the 751 value of the STATUS clause is current. 753 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 754 statement. 756 o The SMIv2 REFERENCE clause is mapped to the YANG reference 757 statement. 759 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 760 translated into an smiv2:oid statement, see the YANG extension 761 defined in Section 11. 763 Within the augment statement, YANG leaf statements are created as 764 described in Section 8.1. 766 8.7. Example: ifXTable of the IF-MIB 768 The translation of the definition of the ifXTable of the IF-MIB 769 [RFC2863] is shown below. 771 /* 772 * ifXTable (1.3.6.1.2.1.31.1.1) 773 * 774 * A list of interface entries. The number of entries is 775 * given by the value of ifNumber. This table contains 776 * additional objects for the interface table. 777 */ 779 augment "/if-mib:ifMIB/if-mib:ifTable/if-mib:ifEntry" { 780 description 781 "An entry containing additional management information 782 applicable to a particular interface."; 783 smiv2:oid "1.3.6.1.2.1.31.1.1.1"; 785 leaf ifName { 786 type snmpv2-tc:DisplayString; 787 description 788 "The textual name of the interface. The value of this 789 object should be the name of the interface as assigned by 790 the local device and should be suitable for use in commands 791 entered at the device's `console'. This might be a text 792 name, such as `le0' or a simple port number, such as `1', 793 depending on the interface naming syntax of the device. If 794 several entries in the ifTable together represent a single 795 interface as named by the device, then each will have the 796 same value of ifName. Note that for an agent which responds 797 to SNMP queries concerning an interface on some other 798 (proxied) device, then the value of ifName for such an 799 interface is the proxied device's local name for it. 801 If there is no local name, or this object is otherwise not 802 applicable, then this object contains a zero-length string."; 803 smiv2:max-access "read-only"; 804 smiv2:oid "1.3.6.1.2.1.31.1.1.1.1"; 805 } 807 // ... 808 } 810 9. Translation of the OBJECT-IDENTITY Macro 812 The SMIv2 uses invocations of the OBJECT-IDENTITY macro to define 813 information about an OBJECT IDENTIFIER assignment. Invocations of 814 the OBJECT-IDENTITY macro MUST be translated into YANG identity 815 statements as detailed below. 817 9.1. OBJECT-IDENTITY Translation Rules 819 The name of the OBJECT-IDENTITY macro invocation is used as the name 820 of the generated identity statement. The generated identity 821 statement uses the smiv2:object-identity defined in Section 11 as its 822 base. The clauses of the SMIv2 OBJECT-IDENTITY macro are mapped to 823 YANG statements as follows: 825 o The SMIv2 STATUS clause is mapped to the YANG status statement. 826 The generation of the YANG status statement is skipped if the 827 value of the STATUS clause is current. 829 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 830 statement. 832 o The SMIv2 REFERENCE clause is mapped to the YANG reference 833 statement. 835 o The value of the SMIv2 OBJECT-IDENTITY macro invocation MAY be 836 translated into an smiv2:oid statement, see the YANG extension 837 defined in Section 11. 839 9.2. Example: diffServTBParamSimpleTokenBucket of the DIFFSERV-MIB 841 The translation of the diffServTBParamSimpleTokenBucket of the 842 DIFFSERV-MIB [RFC3289] is shown below. 844 identity diffServTBParamSimpleTokenBucket { 845 base "smiv2:object-identity"; 846 description 847 "Two Parameter Token Bucket Meter as described in the Informal 848 Differentiated Services Model section 5.2.3."; 849 smiv2:oid "1.3.6.1.2.1.97.3.1.1"; 850 } 852 10. Translation of the NOTIFICATION-TYPE Macro 854 The SMIv2 provides the NOTIFICATION-TYPE macro to define event 855 notifications. YANG provides the notification statement for the same 856 purpose. Invocations of the NOTIFICATION-TYPE macro MUST be 857 translated into YANG notification statements as detailed below. 859 10.1. NOTIFICATION-TYPE Translation Rules 861 The name of the NOTIFICATION-TYPE macro invocation is used as the 862 name of the generated notification statement. The clauses of the 863 NOTIFICATION-TYPE macro are mapped to YANG statements embedded in the 864 notification statement as follows. 866 o The SMIv2 OBJECTS clause is mapped to a sequence of YANG 867 containers. For each object listed in the OBJECTS clause value, a 868 YANG container statement is generated. The name of this container 869 is the string "object-", where is the position of the 870 object in the value of the OBJECTS clause (first element has 871 position 1). If the current object belongs to a conceptual table, 872 then a sequence of leaf statements is generated for each INDEX 873 object of the conceptual table. These leafs are named after the 874 INDEX objects and of type leafref. Finally, a leaf statement is 875 generated named after the current object. If the current object 876 has a MAX-ACCESS of "read-only", "read-write" or ""read-create", 877 then the generated leaf is of type leafref. Otherwise, if the 878 current object has a MAX-ACCESS of "accessible-for-notify", then a 879 leaf is generated, following the itemized steps in Section 8.1. 881 o The SMIv2 STATUS clause is mapped to the YANG status statement. 882 The generation of the YANG status statement is skipped if the 883 value of the STATUS clause is current. 885 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 886 statement. 888 o The SMIv2 REFERENCE clause is mapped to the YANG reference 889 statement. 891 o The value of the SMIv2 NOTIFICATION-TYPE macro invocation MAY be 892 translated into an smiv2:oid statement, see the YANG extension 893 defined in Section 11. 895 10.2. Example: linkDown NOTIFICATION-TYPE of IF-MIB 897 The translation of the linkDown notification of the IF-MIB [RFC2863] 898 is shown below. 900 notification linkDown { 901 description 902 "A linkDown trap signifies that the SNMP entity, acting in 903 an agent role, has detected that the ifOperStatus object for 904 one of its communication links is about to enter the down 905 state from some other state (but not from the notPresent 906 state). This other state is indicated by the included value 907 of ifOperStatus."; 908 smiv2:oid "1.3.6.1.6.3.1.1.5.3"; 910 container object-1 { 911 description 912 "[Automatically generated container for a notification object."; 914 leaf ifIndex { 915 type leafref { 916 path "/if-mib:ifMIB/if-mib:ifTable" + 917 "/if-mib:ifEntry/if-mib:ifIndex"; 918 } 919 description 920 "[Automatically generated leaf for a notification object.]"; 921 } 922 } 924 container object-2 { 925 description 926 "[Automatically generated container for a notification object."; 928 leaf ifIndex { 929 type leafref { 930 path "/if-mib:ifMIB/if-mib:ifTable" + 931 "/if-mib:ifEntry/if-mib:ifIndex"; 932 } 933 description 934 "[Automatically generated leaf for a notification object 935 index.]"; 936 } 937 leaf ifAdminStatus { 938 type leafref { 939 path "/if-mib:ifMIB/if-mib:ifTable" + 940 "/if-mib:ifEntry/if-mib:ifAdminStatus"; 941 } 942 description 943 "[Automatically generated leaf for a notification object.]"; 944 } 945 } 947 container object-3 { 948 description 949 "[Automatically generated container for a notification object."; 951 leaf ifIndex { 952 type leafref { 953 path "/if-mib:ifMIB/if-mib:ifTable" + 954 "/if-mib:ifEntry/if-mib:ifIndex"; 955 } 956 description 957 "[Automatically generated leaf for a notification object 958 index.]"; 959 } 960 leaf ifOperStatus { 961 type leafref { 962 path "/if-mib:ifMIB/if-mib:ifTable" + 963 "/if-mib:ifEntry/if-mib:ifOperStatus"; 964 } 965 description 966 "[Automatically generated leaf for a notification object.]"; 967 } 968 } 969 } 971 11. YANG Language Extension Definition 973 This section defines some YANG extension statements that can be used 974 to capture some information present in SMIv2 modules that is not 975 translated into core YANG statements. The YANG module references 976 [RFC2578] and [RFC2579]. 978 file "ietf-yang-smiv2@2011-07-01.yang" 980 module ietf-yang-smiv2 { 982 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-smiv2"; 983 prefix "smiv2"; 985 organization 986 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 988 contact 989 "WG Web: 990 WG List: 992 WG Chair: David Kessens 993 995 WG Chair: Juergen Schoenwaelder 996 998 Editor: Juergen Schoenwaelder 999 "; 1001 description 1002 "This module defines YANG extensions that are used to translate 1003 SMIv2 concepts into YANG. 1005 Copyright (c) 2011 IETF Trust and the persons identified as 1006 authors of the code. All rights reserved. 1008 Redistribution and use in source and binary forms, with or 1009 without modification, is permitted pursuant to, and subject 1010 to the license terms contained in, the Simplified BSD License 1011 set forth in Section 4.c of the IETF Trust's Legal Provisions 1012 Relating to IETF Documents 1013 (http://trustee.ietf.org/license-info). 1015 This version of this YANG module is part of RFC XXXX; see 1016 the RFC itself for full legal notices."; 1017 // RFC Ed.: replace XXXX with actual RFC number and remove this note 1019 // RFC Ed.: please update the date to the date of publication 1020 revision 2011-07-01 { 1021 description 1022 "Initial revision."; 1023 reference 1024 "RFC XXXX: Translation of SMIv2 MIB Modules to YANG Modules"; 1025 // RFC Ed.: replace XXXX with actual RFC number and remove this note 1026 } 1028 identity object-identity { 1029 description 1030 "Base identity for all SMIv2 OBJECT-IDENTITYs."; 1031 } 1033 extension oid { 1034 argument "value"; 1035 description 1036 "The oid statement takes as an argument the object identifier 1037 assigned to an SMIv2 definition. The object identifier value 1038 is written in decimal dotted notation."; 1039 reference 1040 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1041 } 1043 extension display-hint { 1044 argument "format"; 1045 description 1046 "The display-hint statement takes as an argument the DISPLAY-HINT 1047 assigned to an SMIv2 textual convention."; 1048 reference 1049 "RFC2579: Textual Conventions for SMIv2"; 1050 } 1052 extension max-access { 1053 argument "access"; 1054 description 1055 "The max-access statement takes as an argument the MAX-ACCESS 1056 assigned to an SMIv2 object definition"; 1057 reference 1058 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1059 } 1061 extension defval { 1062 argument "value"; 1063 description 1064 "The defval statement takes as an argument a default value defined 1065 by an SMIv2 DEFVAL clause."; 1066 reference 1067 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1068 } 1070 extension alias { 1071 argument "descriptor" 1072 description 1073 "The alias statement introduces an SMIv2 descriptor. The body of 1074 the alias statement is expected to contain an oid statement that 1075 provides the numeric OID associated with the descriptor."; 1076 reference 1077 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1078 } 1080 } 1082 1084 12. IANA Considerations 1086 This document registers two URIs in the IETF XML registry [RFC3688]. 1087 Following the format in RFC 3688, the following registrations have 1088 been made. 1090 URI: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 1092 Registrant Contact: The NETMOD WG of the IETF. 1094 XML: N/A, the requested URI is an XML namespace. 1096 URI: urn:ietf:params:xml:ns:yang:smiv2 1098 Registrant Contact: The NETMOD WG of the IETF. 1100 XML: N/A, the requested URI is an XML namespace. 1102 This document registers a YANG module in the YANG Module Names 1103 registry [RFC6020]. 1105 name: ietf-yang-smiv2 1106 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 1107 prefix: smiv2 1108 reference: RFC XXXX 1110 13. Security Considerations 1112 This document defines a translation of SMIv2 MIB modules into YANG 1113 modules, enabling read-only access to data objects defined in SMIv2 1114 MIB modules via NETCONF. The translation itself has no security 1115 impact on the Internet. 1117 Users of translated SMIv2 models that have been published as RFCs 1118 should consult the security considerations of the respective RFCs. 1119 In addition, the security considerations for the NETCONF protocol 1120 [RFC6241] should be consulted to understand how NETCONF protects 1121 potentially sensitive information. 1123 14. References 1125 14.1. Normative References 1127 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1128 Requirement Levels", BCP 14, RFC 2119, March 1997. 1130 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1131 Schoenwaelder, Ed., "Structure of Management Information 1132 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1134 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1135 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 1136 STD 58, RFC 2579, April 1999. 1138 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 1139 "Conformance Statements for SMIv2", STD 58, RFC 2580, 1140 April 1999. 1142 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1143 the Network Configuration Protocol (NETCONF)", RFC 6020, 1144 October 2010. 1146 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1147 October 2010. 1149 14.2. Informative References 1151 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 1152 MIB", RFC 2863, June 2000. 1154 [RFC3289] Baker, F., Chan, K., and A. Smith, "Management Information 1155 Base for the Differentiated Services Architecture", 1156 RFC 3289, May 2002. 1158 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1159 January 2004. 1161 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 1162 Documents", BCP 111, RFC 4181, September 2005. 1164 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1165 and A. Bierman, Ed., "Network Configuration Protocol 1166 (NETCONF)", RFC 6241, June 2011. 1168 Author's Address 1170 Juergen Schoenwaelder 1171 Jacobs University 1173 Email: j.schoenwaelder@jacobs-university.de