idnits 2.17.1 draft-ietf-netmod-smi-yang-00.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 13, 2011) is 4755 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) -- Obsolete informational reference (is this intentional?): RFC 4741 (Obsoleted by RFC 6241) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 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 13, 2011 5 Expires: October 15, 2011 7 Translation of SMIv2 MIB Modules to YANG Modules 8 draft-ietf-netmod-smi-yang-00 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 October 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 . . . . . . . . . . . . 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. 127 Mapping of SMIv2 types to YANG types 129 +------------+----------------+-----------------+-------------------+ 130 | SMIv2 | SMIv2 Type | YANG Module | YANG Type | 131 | Module | | | | 132 +------------+----------------+-----------------+-------------------+ 133 | SNMPv2-SMI | INTEGER | | enumeration | 134 | SNMPv2-SMI | INTEGER | | int32 | 135 | SNMPv2-SMI | Integer32 | | int32 | 136 | SNMPv2-SMI | OCTET STRING | | binary | 137 | SNMPv2-SMI | OCTET STRING | | string | 138 | SNMPv2-SMI | OBJECT | ietf-yang-types | object-identifier | 139 | | IDENTIFIER | | | 140 | SNMPv2-SMI | BITS | | bits | 141 | SNMPv2-SMI | IpAddress | ietf-inet-types | ipv4-address | 142 | SNMPv2-SMI | Counter32 | ietf-yang-types | counter32 | 143 | SNMPv2-SMI | Gauge32 | ietf-yang-types | gauge32 | 144 | SNMPv2-SMI | TimeTicks | ietf-yang-types | timeticks | 145 | SNMPv2-SMI | Opaque | | binary | 146 | SNMPv2-SMI | Counter64 | ietf-yang-types | counter64 | 147 | SNMPv2-SMI | Unsigned32 | | uint32 | 148 | SNMPv2-TC | PhysAddress | ietf-yang-types | phys-address | 149 | SNMPv2-TC | MacAddress | ietf-yang-types | mac-address | 150 | SNMPv2-TC | TimeStamp | ietf-yang-types | timestamp | 151 +------------+----------------+-----------------+-------------------+ 153 Table 1 155 The mappings shown in Table 1 may impact the imports of the generated 156 YANG module since some SMIv2 types and textual-conventions map to 157 YANG types defined in the ietf-yang-types and ietf-inet-types YANG 158 modules [RFC6021]. Implementations MUST add any additional imports 159 required by the type mapping. 161 3. Module Prefix Generation 163 The input of the prefix generation algorithm is a set of prefixes 164 (usually derived from imported module names) and a specific module 165 name to be converted into a prefix. The algorithm described below 166 produces a prefix for the given module name that is unique within the 167 set of prefixes. 169 Special prefixes for well known SMIv2 and YANG modules 171 +---------------------+--------+ 172 | YANG / SMIv2 Module | Prefix | 173 +---------------------+--------+ 174 | ietf-yang-types | yang | 175 | ietf-inet-types | inet | 176 | ietf-yang-smiv2 | smiv2 | 177 +---------------------+--------+ 179 Table 2 181 o First, some predefined translations mapping well known SMIv2 and 182 YANG modules to short prefixes are tried (see Table 2). If a 183 fixed translation rule exists and leads to a conflict free prefix, 184 then the fixed translation is used. 186 o Otherwise, prefixes are generated by tokenizing an SMIv2 module 187 name, using hyphens as token separators. The tokens derived from 188 a module name are converted to lowercase characters. The prefix 189 then becomes the shortest sequence of token concatenated using 190 hyphens as separators, which includes at least two token and which 191 is unique among all prefixes used in the YANG module. 193 In the worst case, the prefix derived from an SMIv2 module name 194 becomes the SMIv2 module name translated to lower-case. But on 195 average, much shorter prefixes are generated. 197 4. Translation of SMIv2 Modules and SMIv2 IMPORT Clauses 199 SMIv2 modules are mapped to corresponding YANG modules. The YANG 200 module name MUST be the same as the SMIv2 module name. 202 The YANG namespace MUST be constructed out of a constant prefix, 203 which followed by the SMIv2 module name. Since SMIv2 module names 204 can be assumed to be unique (see Section 3 in [RFC2578]), the 205 resulting YANG namespace is unique. The registered prefix is 206 urn:ietf:params:xml:ns:yang:smiv2:, see the IANA considerations in 207 Section 12. 209 The YANG prefix MAY be derived from the SMIv2 module name using the 210 module prefix generation algorithm described in Section 3. The YANG 211 prefix is supposed to be short and it must be unique within the set 212 of all prefixes used by a YANG module. The algorithm described in 213 Section 3 generates such prefixes. 215 SMIv2 IMPORT clauses are translated to YANG import statements. One 216 major difference between the SMIv2 import mechanism and the YANG 217 import mechanism is that SMIv2 IMPORT clauses import specific symbols 218 from an SMIv2 module while the YANG import statement imports all 219 symbols of the referenced YANG module. 221 SMIv2 imports that are ignored in YANG 223 +--------------+--------------------+ 224 | SMIv2 Module | SMIv2 Symbol | 225 +--------------+--------------------+ 226 | SNMPv2-SMI | MODULE-IDENTITY | 227 | SNMPv2-SMI | OBJECT-IDENTITY | 228 | SNMPv2-SMI | OBJECT-TYPE | 229 | SNMPv2-SMI | NOTIFICATION-TYPE | 230 | SNMPv2-SMI | mib-2 | 231 | SNMPv2-TC | TEXTUAL-CONVENTION | 232 | SNMPv2-MIB | snmpTraps | 233 | SNMPv2-SMI | * all symbols * | 234 | SNMPv2-CONF | * all symbols * | 235 +--------------+--------------------+ 237 Table 3 239 In order to produce correct and complete YANG import statements, the 240 following rules MUST be used: 242 o Ignore all imports listed in Table 3. Note that the modules 243 SNMPv2-SMI and SNMPv2-CONF are completely ignored since all 244 definitions in these modules are translated by translation rules 245 defined in this document. 247 o Add any imports required by the type translations according to the 248 type mapping table. This requires to consider all the types used 249 in the translation unit in order to produce the imports. 251 The generated import statements use the untranslated SMIv2 module 252 names or the names of well-known YANG modules as their argument. The 253 import statement must contain a prefix statement. The prefixes MAY 254 be generated by applying the module prefix generation algorithm 255 described in Section 3. 257 4.1. Example: IMPORTS of IF-MIB 259 The translation of the IF-MIB [RFC2863] leads to the YANG module 260 frame and the import statements shown below. The prefix is the 261 translation of the SMIv2 module name IF-MIB to lowercase (consisting 262 of two tokens and thus no further abbreviation). 264 module IF-MIB { 266 namespace "urn:ietf:params:xml:ns:yang:smiv2:IF-MIB"; 267 prefix "if-mib"; 269 import IANAifType-MIB { prefix "ianaiftype-mib"; } 270 import SNMPv2-TC { prefix "smiv2-tc"; } 271 import ietf-yang-types { prefix "yang"; } 272 import ietf-yang-smiv2 { prefix "smiv2"; } 273 } 275 5. Translation of the MODULE-IDENTITY Macro 277 The SMIv2 requires an invocation of the MODULE-IDENTITY macro to 278 provide contact and revision history for a MIB module. The clauses 279 of the SMIv2 MODULE-IDENTITY macro MUST be translated into YANG 280 statements as detailed below. 282 5.1. MODULE-IDENTITY Translation Rules 284 o The SMIv2 ORGANIZATION clause is mapped to the YANG organization 285 statement. 287 o The SMIv2 CONTACT-INFO clause is mapped to the YANG contact 288 statement. 290 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 291 statement. 293 o Each SMIv2 REVISION clause is mapped to a YANG revision statement. 294 The revision is identified by the date argument of the SMIv2 295 REVISION clause. DESCRIPTION sub-clauses of REVISION clauses are 296 mapped to corresponding description statement nested in revision 297 clauses. 299 o The SMIv2 LAST-UPDATED clause is ignored if the associated date 300 matches a REVISION clause. Otherwise, an additional revision 301 statement is generated. 303 o The name of the MODULE-IDENTITY macro invocation is used to 304 generate a top-level container statement. This container MUST be 305 config false. 307 o The object identifier value of the invocation of the SMIv2 MODULE- 308 IDENTITY MAY be translated into an smiv2:oid statement contained 309 in the container representing the MODULE-IDENTITY macro 310 invocation, see the YANG extension defined in Section 11. 312 While all proper SMIv2 modules must have exactly one MODULE-IDENTITY 313 macro invocation, there are a few notable exceptions. The modules 314 defining the SMIv2 language (i.e., the SNMPv2-SMI, SNMPv2-TC, and 315 SNMPv2-CONF modules) do not invoke the MODULE-IDENTITY macro. 316 Furthermore, SMIv2 modules generated from SMIv1 modules may miss an 317 invocation of the MODULE-IDENTITY macro as well. In such cases, it 318 is preferable to not generate organization, contact, description, and 319 revision statements. 321 5.2. Example: MODULE-IDENTITY of IF-MIB 323 The translation of the MODULE-IDENTITY of the IF-MIB [RFC2863] leads 324 to the following YANG statements: 326 organization 327 "IETF Interfaces MIB Working Group"; 329 contact 330 "Keith McCloghrie 331 Cisco Systems, Inc. 332 170 West Tasman Drive 333 San Jose, CA 95134-1706 334 US 336 408-526-5260 337 kzm@cisco.com"; 339 description 340 "The MIB module to describe generic objects for network 341 interface sub-layers. This MIB is an updated version of 342 MIB-II's ifTable, and incorporates the extensions defined in 343 RFC 1229."; 345 revision "2000-06-14" { 346 description 347 "Clarifications agreed upon by the Interfaces MIB WG, and 348 published as RFC 2863."; 349 } 350 revision "1996-02-28" { 351 description 352 "Revisions made by the Interfaces MIB WG, and published in 353 RFC 2233."; 354 } 355 revision "1993-11-08" { 356 description 357 "Initial revision, published as part of RFC 1573."; 358 } 360 container ifMIB { 361 config false; 362 smiv2:oid "1.3.6.1.2.1.31"; 363 } 365 6. Translation of the TEXTUAL-CONVENTION Macro 367 The SMIv2 uses invocations of the TEXTUAL-CONVENTION macro to define 368 new types derived from the SMIv2 base types. Invocations of the 369 TEXTUAL-CONVENTION macro MUST be translated into YANG typedef 370 statements as detailed below. 372 6.1. TEXTUAL-CONVENTION Translation Rules 374 The name of the TEXTUAL-CONVENTION macro invocation is used as the 375 name of the generated typedef statement. The clauses of the SMIv2 376 TEXTUAL-CONVENTION macro are mapped to YANG statements embedded in 377 the typedef statement as follows: 379 o The SMIv2 DISPLAY-HINT clause is used to determine the type 380 mapping of types derived form the OCTET STRING type as explained 381 in Section 2. Furthermore, the DISPLAY-HINT value MAY be used to 382 generate a regular expression for the YANG pattern statement 383 within the type statement. 385 o The SMIv2 DISPLAY-HINT MAY be translated into an smiv2:display- 386 hint statement, see the YANG extension defined in Section 11. 388 o The SMIv2 STATUS clause is mapped to the YANG status statement. 389 The generation of the YANG status statement is skipped if the 390 value of the STATUS clause is current. 392 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 393 statement. 395 o The SMIv2 REFERENCE clause is mapped to the YANG reference 396 statement. 398 o The SMIv2 SYNTAX clause is mapped to the YANG type statement. 399 SMIv2 range restrictions are mapped to YANG range statements while 400 SMIv2 length restrictions are mapped to YANG length statements. 401 SMIv2 INTEGER enumerations and SMIv2 BITS are mapped to YANG enum 402 / value and bit / position statements. 404 This translation assumes that labels of named numbers and named bits 405 do not change when an SMIv2 module is revised. This is consistent 406 with the clarification of the SMIv2 module revision rules in Section 407 4.9 of [RFC4181]. 409 6.2. Example: OwnerString and InterfaceIndex of IF-MIB 411 The translation of the OwnerString and InterfaceIndex textual- 412 conventions of the IF-MIB [RFC2863] are shown below. 414 typedef OwnerString { 415 type string { 416 length "0..255"; 417 pattern '\p{IsBasicLatin}{0,255}'; 418 } 419 status deprecated; 420 description 421 "This data type is used to model an administratively 422 assigned name of the owner of a resource. This information 423 is taken from the NVT ASCII character set. It is suggested 424 that this name contain one or more of the following: ASCII 425 form of the manager station's transport address, management 426 station name (e.g., domain name), network management 427 personnel's name, location, or phone number. In some cases 428 the agent itself will be the owner of an entry. In these 429 cases, this string shall be set to a string starting with 430 'agent'."; 431 smiv2:display-hint "255a"; 432 } 434 typedef InterfaceIndex { 435 type int32 { 436 range "1..2147483647"; 437 } 438 description 439 "A unique value, greater than zero, for each interface or 440 interface sub-layer in the managed system. It is 441 recommended that values are assigned contiguously starting 442 from 1. The value for each interface sub-layer must remain 443 constant at least from one re-initialization of the entity's 444 network management system to the next re-initialization."; 445 smiv2:display-hint "d"; 446 } 448 6.3. Example: IfDirection of the DIFFSERV-MIB 450 The translation of the IfDirection textual-convention of the 451 DIFFSERV-MIB [RFC3289] is shown below. 453 typedef IfDirection { 454 type enumeration { 455 enum inbound { value 1; } 456 enum outbound { value 2; } 457 } 458 description 459 "IfDirection specifies a direction of data travel on an 460 interface. 'inbound' traffic is operated on during reception from 461 the interface, while 'outbound' traffic is operated on prior to 462 transmission on the interface."; 463 } 465 7. Translation of OBJECT IDENTIFIER Assignments 467 The SMIv2 uses OBJECT IDENTIFIER assignments to introduce names for 468 intermediate nodes in the OBJECT IDENTIFIER tree. OBJECT IDENTIFIER 469 assignments are not translated into YANG statements. 471 8. Translation of the OBJECT-TYPE Macro 473 The SMIv2 uses the OBJECT-TYPE macro to define objects and the 474 structure of conceptual tables. Objects exist either as scalars 475 (exactly one instance within an SNMP context) or columnar objects 476 within conceptual tables (zero or multiple instances within an SNMP 477 context). A number of auxiliary objects define the index (key) of a 478 conceptual table. Furthermore, conceptual tables can be augmented by 479 other conceptual tables. All these differences must be taken into 480 account when translating SMIv2 OBJECT-TYPE macro invocations to YANG. 481 Invocations of the OBJECT-TYPE macro MUST be translated into YANG 482 statements as detailed below. 484 8.1. Scalar and Columnar Object Translation Rules 486 SMIv2 OBJECT-TYPE macro invocations defining scalars or columnar 487 objects with a MAX-ACCESS of "not-accessible", "read-only", 488 "read-write" and ""read-create" are translated to YANG leaf 489 statements. The name of the leaf is the name associated with the 490 SMIv2 OBJECT-TYPE macro invocation. SMIv2 OBJECT-TYPE macro 491 invocations with a MAX-ACCESS of "accessible-for-notify" are not 492 translated to YANG data tree leafs but instead into YANG notification 493 leafs. 495 All leaf statements for scalar objects are created in the container 496 representing the SMIv2 module, see Section 5.1. The leaf statements 497 representing columnar objects are created in the list representing a 498 conceptual row, see Section 8.3. 500 o The SMIv2 SYNTAX clause is mapped to the YANG type statement. 501 SMIv2 range restrictions are mapped to YANG range statements while 502 SMIv2 length restrictions are mapped to YANG length statements. 503 SMIv2 INTEGER enumerations and SMIv2 BITS are mapped to YANG enum 504 / value and bit / position statements. 506 o The SMIv2 UNITS clause is mapped to the YANG units statement. 508 o The SMIv2 MAX-ACCESS MAY be translated into an smiv2:max-access 509 statement, see the YANG extension defined in Section 11. 511 o The SMIv2 STATUS clause is mapped to the YANG status statement. 512 The generation of the YANG status statement is skipped if the 513 value of the STATUS clause is current. 515 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 516 statement. 518 o The SMIv2 REFERENCE clause is mapped to the YANG reference 519 statement. 521 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 522 translated into an smiv2:oid statement, see the YANG extension 523 defined in Section 11. 525 This translation assumes that labels of named numbers and named bits 526 do not change when an SMIv2 module is revised. This is consistent 527 with the clarification of the SMIv2 module revision rules in Section 528 4.9 of [RFC4181]. 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 smiv2:max-access "read-only"; 541 smiv2:oid "1.3.6.1.2.1.2.1"; 542 } 544 leaf ifIndex { 545 type if-mib:InterfaceIndex; 546 description 547 "A unique value, greater than zero, for each interface. It 548 is recommended that values are assigned contiguously 549 starting from 1. The value for each interface sub-layer 550 must remain constant at least from one re-initialization of 551 the entity's network management system to the next re- 552 initialization."; 553 smiv2:max-access "read-only"; 554 smiv2:oid "1.3.6.1.2.1.2.2.1.1"; 555 } 557 8.3. Non-Augmenting Conceptual Table Translation Rules 559 An OBJECT-TYPE macro invocation defining a non-augmenting conceptual 560 table is translated to a YANG container statement using the name of 561 the OBJECT-TYPE macro invocation. This container MUST be config 562 false. The clauses of the macro are translated as follows: 564 o The SMIv2 SYNTAX clause is ignored 566 o The SMIv2 UNITS clause is ignored. 568 o The SMIv2 MAX-ACCESS clause is ignored. 570 o The SMIv2 STATUS clause is mapped to the YANG status statement. 571 The generation of the YANG status statement is skipped if the 572 value of the STATUS clause is current. 574 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 575 statement. 577 o The SMIv2 REFERENCE clause is mapped to the YANG reference 578 statement. 580 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 581 translated into an smiv2:oid statement, see the YANG extension 582 defined in Section 11. 584 An OBJECT-TYPE macro invocation defining a conceptual row is 585 translated to a YANG list statement. It is contained in the YANG 586 container representing the conceptual table. The generated list uses 587 the name of the row OBJECT-TYPE macro invocation. The clauses of the 588 OBJECT-TYPE macro are translated as follows: 590 o The SMIv2 SYNTAX clause is ignored. 592 o The SMIv2 UNITS clause is ignored. 594 o The SMIv2 MAX-ACCESS clause is ignored. 596 o The SMIv2 STATUS clause is mapped to the YANG status statement. 597 The generation of the YANG status statement is skipped if the 598 value of the STATUS clause is current. 600 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 601 statement. 603 o The SMIv2 REFERENCE clause is mapped to the YANG reference 604 statement. 606 o The SMIv2 INDEX clause is mapped to the YANG key clause listing 607 the columnar objects forming the key of the YANG list. 609 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 610 translated into an smiv2:oid statement, see the YANG extension 611 defined in Section 11. 613 Within the list statement, YANG leaf statements are created for 614 columnar objects as described in Section 8.1. For objects listed in 615 the SMIv2 INDEX clause that are not part of the conceptual table 616 itself, YANG leaf statements of type leafref pointing to the 617 referenced definition are created. 619 8.4. Example: ifTable of the IF-MIB 621 The translation of the definition of the ifTable of the IF-MIB 622 [RFC2863] is shown below. 624 container ifTable { 625 config false; 626 description 627 "A list of interface entries. The number of entries is 628 given by the value of ifNumber."; 629 smiv2:oid "1.3.6.1.2.1.2.2"; 631 list ifEntry { 632 key "ifIndex"; 633 description 634 "An entry containing management information applicable to a 635 particular interface."; 636 smiv2:oid "1.3.6.1.2.1.2.2.1"; 638 leaf ifIndex { 639 type if-mib:InterfaceIndex; 640 description 641 "A unique value, greater than zero, for each interface. It 642 is recommended that values are assigned contiguously 643 starting from 1. The value for each interface sub-layer 644 must remain constant at least from one re-initialization of 645 the entity's network management system to the next re- 646 initialization."; 647 smiv2:max-access "read-only"; 648 smiv2:oid "1.3.6.1.2.1.2.2.1.1"; 649 } 651 // ... 652 } 653 } 655 8.5. Example: ifRcvAddressTable of the IF-MIB 657 The translation of the definition of the ifRcvAddressTable of the IF- 658 MIB [RFC2863] is shown below. 660 container ifRcvAddressTable { 661 description 662 "This table contains an entry for each address (broadcast, 663 multicast, or uni-cast) for which the system will receive 664 packets/frames on a particular interface, except as follows: 666 - for an interface operating in promiscuous mode, entries 667 are only required for those addresses for which the system 668 would receive frames were it not operating in promiscuous 669 mode. 671 - for 802.5 functional addresses, only one entry is 672 required, for the address which has the functional address 673 bit ANDed with the bit mask of all functional addresses for 674 which the interface will accept frames. 676 A system is normally able to use any unicast address which 677 corresponds to an entry in this table as a source address."; 678 smiv2:oid "1.3.6.1.2.1.31.1.4"; 680 list ifRcvAddressEntry { 681 key "ifIndex ifRcvAddressAddress"; 682 description 683 "A list of objects identifying an address for which the 684 system will accept packets/frames on the particular 685 interface identified by the index value ifIndex."; 686 smiv2:oid "1.3.6.1.2.1.31.1.4.1"; 688 leaf ifIndex { 689 type leafref { 690 path "/if-mib:ifTable/if-mib:ifEntry/if-mib:ifIndex"; 691 } 692 description 693 "[Automatically generated leaf for a foreign index.]"; 694 } 696 leaf ifRcvAddressAddress { 697 type yang:phys-address; 698 description 699 "An address for which the system will accept packets/frames 700 on this entry's interface."; 701 smiv2:max-access "not-accessible"; 702 smiv2:oid "1.3.6.1.2.1.31.1.4.1.1"; 703 } 705 // ... 706 } 707 } 709 8.6. Augmenting Conceptual Tables Translation Rules 711 An OBJECT-TYPE macro invocation defining an augmenting conceptual 712 table is not translated to a YANG statement. The name assigned by 713 the OBJECT-TYPE macro invocation to the augmenting conceptual table 714 MAY be captured in a comment. The clauses of the macro are 715 translated as follows: 717 o The SMIv2 SYNTAX clause is ignored. 719 o The SMIv2 UNITS clause is ignored. 721 o The SMIv2 MAX-ACCESS clause is ignored. 723 o The SMIv2 STATUS clause is ignored. 725 o The SMIv2 DESCRIPTION clause MAY be captured in a comment. 726 statement. 728 o The SMIv2 REFERENCE clause MAY be captured in a comment. 730 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 731 captured in a comment. 733 An OBJECT-TYPE macro invocation defining a conceptual row 734 augmentation is translated to a YANG augment statement using the path 735 to the augmented table as its argument. The clauses of the OBJECT- 736 TYPE macro are translated as follows: 738 o The SMIv2 SYNTAX clause is ignored. 740 o The SMIv2 UNITS clause is ignored. 742 o The SMIv2 MAX-ACCESS clause is ignored. 744 o The SMIv2 STATUS clause is mapped to the YANG status statement. 745 The generation of the YANG status statement is skipped if the 746 value of the STATUS clause is current. 748 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 749 statement. 751 o The SMIv2 REFERENCE clause is mapped to the YANG reference 752 statement. 754 o The value of the SMIv2 OBJECT-TYPE macro invocation MAY be 755 translated into an smiv2:oid statement, see the YANG extension 756 defined in Section 11. 758 Within the augment statement, YANG leaf statements are created as 759 described in Section 8.1. 761 8.7. Example: ifXTable of the IF-MIB 763 The translation of the definition of the ifXTable of the IF-MIB 764 [RFC2863] is shown below. 766 /* 767 * ifXTable (1.3.6.1.2.1.31.1.1) 768 * 769 * A list of interface entries. The number of entries is 770 * given by the value of ifNumber. This table contains 771 * additional objects for the interface table. 772 */ 774 augment "/if-mib:ifTable/if-mib:ifEntry" { 775 description 776 "An entry containing additional management information 777 applicable to a particular interface."; 778 smiv2:oid "1.3.6.1.2.1.31.1.1.1"; 780 leaf ifName { 781 type snmpv2-tc:DisplayString; 782 description 783 "The textual name of the interface. The value of this 784 object should be the name of the interface as assigned by 785 the local device and should be suitable for use in commands 786 entered at the device's `console'. This might be a text 787 name, such as `le0' or a simple port number, such as `1', 788 depending on the interface naming syntax of the device. If 789 several entries in the ifTable together represent a single 790 interface as named by the device, then each will have the 791 same value of ifName. Note that for an agent which responds 792 to SNMP queries concerning an interface on some other 793 (proxied) device, then the value of ifName for such an 794 interface is the proxied device's local name for it. 796 If there is no local name, or this object is otherwise not 797 applicable, then this object contains a zero-length string."; 798 smiv2:max-access "read-only"; 799 smiv2:oid "1.3.6.1.2.1.31.1.1.1.1"; 800 } 802 // ... 803 } 805 9. Translation of the OBJECT-IDENTITY Macro 807 The SMIv2 uses invocations of the OBJECT-IDENTITY macro to define 808 information about an OBJECT IDENTIFIER assignment. Invocations of 809 the OBJECT-IDENTITY macro MUST be translated into YANG identity 810 statements as detailed below. 812 9.1. OBJECT-IDENTITY Translation Rules 814 The name of the OBJECT-IDENTITY macro invocation is used as the name 815 of the generated identity statement. The generated identity 816 statement uses the smiv2:object-identity defined in Section 11 as its 817 base. The clauses of the SMIv2 OBJECT-IDENTITY macro are mapped to 818 YANG statements as follows: 820 o The SMIv2 STATUS clause is mapped to the YANG status statement. 821 The generation of the YANG status statement is skipped if the 822 value of the STATUS clause is current. 824 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 825 statement. 827 o The SMIv2 REFERENCE clause is mapped to the YANG reference 828 statement. 830 o The value of the SMIv2 OBJECT-IDENTITY macro invocation MAY be 831 translated into an smiv2:oid statement, see the YANG extension 832 defined in Section 11. 834 9.2. Example: diffServTBParamSimpleTokenBucket of the DIFFSERV-MIB 836 The translation of the diffServTBParamSimpleTokenBucket of the 837 DIFFSERV-MIB [RFC3289] is shown below. 839 identity diffServTBParamSimpleTokenBucket { 840 base "smiv2:object-identity"; 841 description 842 "Two Parameter Token Bucket Meter as described in the Informal 843 Differentiated Services Model section 5.2.3."; 844 smiv2:oid "1.3.6.1.2.1.97.3.1.1"; 845 } 847 10. Translation of the NOTIFICATION-TYPE Macro 849 The SMIv2 provides the NOTIFICATION-TYPE macro to define event 850 notifications. YANG provides the notification statement for the same 851 purpose. Invocations of the NOTIFICATION-TYPE macro MUST be 852 translated into YANG notification statements as detailed below. 854 10.1. NOTIFICATION-TYPE Translation Rules 856 The name of the NOTIFICATION-TYPE macro invocation is used as the 857 name of the generated notification statement. The clauses of the 858 NOTIFICATION-TYPE macro are mapped to YANG statements embedded in the 859 notification statement as follows. 861 o The SMIv2 OBJECTS clause is mapped to a sequence of YANG 862 containers. For each object listed in the OBJECTS clause value, a 863 YANG container statement is generated. The name of this container 864 is the string "object-", where is the position of the 865 object in the value of the OBJECTS clause (first element has 866 position 1). If the current object belongs to a conceptual table, 867 then a sequence of leaf statements is generated for each INDEX 868 object of the conceptual table. These leafs are named after the 869 INDEX objects and of type leafref. Finally, a leaf statement is 870 generated named after the current object. If the current object 871 has a MAX-ACCESS of "read-only", "read-write" or ""read-create", 872 then the generated leaf is of type leafref. Otherwise, if the 873 current object has a MAX-ACCESS of "accessible-for-notify", then a 874 leaf is generated, following the itemized steps in Section 8.1. 876 o The SMIv2 STATUS clause is mapped to the YANG status statement. 877 The generation of the YANG status statement is skipped if the 878 value of the STATUS clause is current. 880 o The SMIv2 DESCRIPTION clause is mapped to the YANG description 881 statement. 883 o The SMIv2 REFERENCE clause is mapped to the YANG reference 884 statement. 886 o The value of the SMIv2 NOTIFICATION-TYPE macro invocation MAY be 887 translated into an smiv2:oid statement, see the YANG extension 888 defined in Section 11. 890 10.2. Example: linkDown NOTIFICATION-TYPE of IF-MIB 892 The translation of the linkDown notification of the IF-MIB [RFC2863] 893 is shown below. 895 notification linkDown { 896 description 897 "A linkDown trap signifies that the SNMP entity, acting in 898 an agent role, has detected that the ifOperStatus object for 899 one of its communication links is about to enter the down 900 state from some other state (but not from the notPresent 901 state). This other state is indicated by the included value 902 of ifOperStatus."; 903 smiv2:oid "1.3.6.1.6.3.1.1.5.3"; 905 container object-1 { 906 leaf ifIndex { 907 type leafref { 908 path "/if-mib:ifTable/if-mib:ifEntry/if-mib:ifIndex"; 909 } 910 description 911 "[Automatically generated leaf for a notification object.]"; 912 } 913 } 915 container object-2 { 916 leaf ifIndex { 917 type leafref { 918 path "/if-mib:ifTable/if-mib:ifEntry/if-mib:ifIndex"; 919 } 920 description 921 "[Automatically generated leaf for a notification object 922 index.]"; 923 } 924 leaf ifAdminStatus { 925 type leafref { 926 path "/if-mib:ifTable/if-mib:ifEntry/if-mib:ifAdminStatus"; 927 } 928 description 929 "[Automatically generated leaf for a notification object.]"; 930 } 931 } 933 container object-3 { 934 leaf ifIndex { 935 type leafref { 936 path "/if-mib:ifTable/if-mib:ifEntry/if-mib:ifIndex"; 937 } 938 description 939 "[Automatically generated leaf for a notification object 940 index.]"; 941 } 942 leaf ifOperStatus { 943 type leafref { 944 path "/if-mib:ifTable/if-mib:ifEntry/if-mib:ifOperStatus"; 945 } 946 description 947 "[Automatically generated leaf for a notification object.]"; 948 } 949 } 950 } 952 11. YANG Language Extension Definition 954 This section defines some YANG extension statements that can be used 955 to capture some information present in SMIv2 modules that is not 956 translated into core YANG statements. The YANG module references 957 [RFC2578] and [RFC2579]. 959 file "ietf-yang-smiv2@2011-04-13.yang" 961 module ietf-yang-smiv2 { 963 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-smiv2"; 964 prefix "smiv2"; 966 organization 967 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 969 contact 970 "WG Web: 971 WG List: 973 WG Chair: David Kessens 974 976 WG Chair: Juergen Schoenwaelder 977 979 Editor: Juergen Schoenwaelder 980 "; 982 description 983 "This module defines YANG extensions that are used to translate 984 SMIv2 concepts into YANG. 986 Copyright (c) 2011 IETF Trust and the persons identified as 987 authors of the code. All rights reserved. 989 Redistribution and use in source and binary forms, with or 990 without modification, is permitted pursuant to, and subject 991 to the license terms contained in, the Simplified BSD License 992 set forth in Section 4.c of the IETF Trust's Legal Provisions 993 Relating to IETF Documents 994 (http://trustee.ietf.org/license-info). 996 This version of this YANG module is part of RFC XXXX; see 997 the RFC itself for full legal notices."; 998 // RFC Ed.: replace XXXX with actual RFC number and remove this note 1000 // RFC Ed.: please update the date to the date of publication 1001 revision 2011-04-13 { 1002 description 1003 "Initial revision."; 1004 reference 1005 "RFC XXXX: Translation of SMIv2 MIB Modules to YANG Modules"; 1006 // RFC Ed.: replace XXXX with actual RFC number and remove this note 1007 } 1009 identity object-identity { 1010 description 1011 "Base identity for all SMIv2 OBJECT-IDENTITYs."; 1012 } 1014 extension oid { 1015 argument "value"; 1016 description 1017 "The oid statement takes as an argument the object identifier 1018 assigned to an SMIv2 definition. The object identifier value 1019 is written in decimal dotted notation."; 1020 reference 1021 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1022 } 1024 extension display-hint { 1025 argument "format"; 1026 description 1027 "The display-hint statement takes as an argument the DISPLAY-HINT 1028 assigned to an SMIv2 textual convention."; 1029 reference 1030 "RFC2579: Textual Conventions for SMIv2"; 1031 } 1033 extension max-access { 1034 argument "access"; 1035 description 1036 "The max-access statement takes as an argument the MAX-ACCESS 1037 assigned to an SMIv2 object definition"; 1038 reference 1039 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1040 } 1042 extension defval { 1043 argument "value"; 1044 description 1045 "The defval statement takes as an argument a default value defined 1046 by an SMIv2 DEFVAL clause."; 1047 reference 1048 "RFC2578: Structure of Management Information Version 2 (SMIv2)"; 1049 } 1051 } 1053 1055 12. IANA Considerations 1057 This document registers two URIs in the IETF XML registry [RFC3688]. 1058 Following the format in RFC 3688, the following registrations have 1059 been made. 1061 URI: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 1063 Registrant Contact: The NETMOD WG of the IETF. 1065 XML: N/A, the requested URI is an XML namespace. 1067 URI: urn:ietf:params:xml:ns:yang:smiv2 1069 Registrant Contact: The NETMOD WG of the IETF. 1071 XML: N/A, the requested URI is an XML namespace. 1073 This document registers a YANG module in the YANG Module Names 1074 registry [RFC6020]. 1076 name: ietf-yang-smiv2 1077 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-smiv2 1078 prefix: smiv2 1079 reference: RFC XXXX 1081 13. Security Considerations 1083 This document defines a translation of SMIv2 MIB modules into YANG 1084 modules, enabling read-only access to data objects defined in SMIv2 1085 MIB modules via NETCONF. The translation itself has no security 1086 impact on the Internet. 1088 Users of translated SMIv2 models that have been published as RFCs 1089 should consult the security considerations of the respective RFCs. 1090 In addition, the security considerations for the NETCONF protocol 1091 [RFC4741] should be consulted to understand how NETCONF protects 1092 potentially sensitive information. 1094 14. References 1096 14.1. Normative References 1098 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1099 Requirement Levels", BCP 14, RFC 2119, March 1997. 1101 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1102 Schoenwaelder, Ed., "Structure of Management Information 1103 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1105 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1106 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 1107 STD 58, RFC 2579, April 1999. 1109 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 1110 "Conformance Statements for SMIv2", STD 58, RFC 2580, 1111 April 1999. 1113 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1114 the Network Configuration Protocol (NETCONF)", RFC 6020, 1115 October 2010. 1117 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1118 October 2010. 1120 14.2. Informative References 1122 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 1123 MIB", RFC 2863, June 2000. 1125 [RFC3289] Baker, F., Chan, K., and A. Smith, "Management Information 1126 Base for the Differentiated Services Architecture", 1127 RFC 3289, May 2002. 1129 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1130 January 2004. 1132 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 1133 Documents", BCP 111, RFC 4181, September 2005. 1135 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1136 December 2006. 1138 Author's Address 1140 Juergen Schoenwaelder 1141 Jacobs University 1143 Email: j.schoenwaelder@jacobs-university.de