idnits 2.17.1 draft-ietf-netmod-interfaces-cfg-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 lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (April 11, 2011) is 4762 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track April 11, 2011 5 Expires: October 13, 2011 7 A YANG Data Model for Interface Configuration 8 draft-ietf-netmod-interfaces-cfg-00 10 Abstract 12 This document defines a YANG data model for the configuration of 13 network interfaces. It is expected that interface type specific 14 configuration data models augment the generic interfaces data model 15 defined in this document. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on October 13, 2011. 34 Copyright Notice 36 Copyright (c) 2011 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 3. Interfaces Data Model . . . . . . . . . . . . . . . . . . . . 5 54 3.1. The interface List . . . . . . . . . . . . . . . . . . . . 5 55 3.2. Interface References . . . . . . . . . . . . . . . . . . . 5 56 3.3. Interface Layering . . . . . . . . . . . . . . . . . . . . 6 57 4. Interfaces YANG Module . . . . . . . . . . . . . . . . . . . . 7 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 59 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 60 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 61 8. Normative References . . . . . . . . . . . . . . . . . . . . . 15 62 Appendix A. Example: Ethernet Interface Module . . . . . . . . . 16 63 Appendix B. Example: Ethernet Bonding Interface Module . . . . . 18 64 Appendix C. Example: VLAN Interface Module . . . . . . . . . . . 19 65 Appendix D. Example: IP Module . . . . . . . . . . . . . . . . . 20 66 Appendix E. Example: NETCONF reply . . . . . . . . . . . . 21 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 69 1. Introduction 71 This document defines a YANG [RFC6020] data model for the 72 configuration of network interfaces. It is expected that interface 73 type specific configuration data models augment the generic 74 interfaces data model defined in this document. 76 Network interfaces are central to the configuration of many Internet 77 protocols. Thus, it is important to establish a common data model 78 for how interfaces are identified and configured. 80 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 81 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 82 "OPTIONAL" in this document are to be interpreted as described in BCP 83 14, [RFC2119]. 85 2. Objectives 87 This section describes some of the design objectives for the model 88 presented in Section 4. 90 o It is recognized that existing implementations will have to map 91 the interface data model defined in this memo to their proprietary 92 native data model. The new data model should be simple to 93 facilitate such mappings. 95 o The data model should be suitable for new implementations to use 96 as-is, without requiring a mapping to a different native model. 98 o The data model must be extensible for different specific interface 99 types, including vendor-specific types. 101 o References to interfaces should be as simple as possible, 102 preferably by using a single leafref. 104 o The mapping to ifIndex [RFC2863] used by SNMP to identify 105 interfaces must be clear. 107 o The model must support interface layering, both simple layering 108 where one interface is layered on top of exactly one other 109 interface, and more complex scenarios where one interface is 110 aggregated over N other interfaces, or when N interfaces are 111 multiplexed over one other interface. 113 o The data model should support the pre-provisioning of interface 114 configuration, i.e., it should be possible to configure an 115 interface whose physical interface hardware is not present on the 116 device. It is recommended that devices that support dynamic 117 addition and removal of physical interfaces also support pre- 118 provisioning. 120 3. Interfaces Data Model 122 3.1. The interface List 124 The data model for interface configuration presented in this document 125 uses a flat list of interfaces. Each interface in the list is 126 identified by its name. Furthermore, each interface has a mandatory 127 "type" leaf, and a "location" leaf. The combination of "type" and 128 "location" is unique within the interface list. 130 It is expected that interface type specific data models augment the 131 interface list, and use the "type" leaf to make the augmentation 132 conditional. 134 As an example of such an interface type specific augmentation, 135 consider this YANG snippet. For a more complete example, see 136 Appendix A. 138 import interfaces { 139 prefix "if"; 140 } 142 augment "/if:interfaces/if:interface" { 143 when "if:type = 'ethernetCsmacd'"; 145 container ethernet { 146 leaf duplex { 147 ... 148 } 149 } 150 } 152 The "location" leaf is a string. It is optional in the data model, 153 but if the type represents a physical interface, it is mandatory. 154 The format of this string is device- and type-dependent. The device 155 uses the location string to identify the physical or logical entity 156 that the configuration applies to. For example, if a device has a 157 single array of 8 ethernet ports, the location can be one of the 158 strings "1" to "8". As another example, if a device has N cards of M 159 ports, the location can be on the form "n/m", such as "1/0". 161 How a client can learn which types and locations are present on a 162 certain device is outside the scope of this document. 164 3.2. Interface References 166 An interface is uniquely identified by its name. This property is 167 captured in the "interface-ref" typedef, which other YANG modules 168 SHOULD use when they need to reference an existing interface. 170 3.3. Interface Layering 172 There is no generic mechanism for how an interface is configured to 173 be layered on top of some other interface. It is expected that 174 interface type specific models define their own objects for interface 175 layering, by using "interface-ref" types to reference lower layers. 177 Below is an example of a model with such objects. For a more 178 complete example, see Appendix B. 180 augment "/if:interfaces/if:interface" { 181 when "if:type = 'ieee8023adLag'"; 183 leaf-list slave-if { 184 type if:interface-ref; 185 must "/if:interfaces/if:interface[if:name = current()]" 186 + "/if:type = 'eth:ethernet'" { 187 description 188 "The type of a slave interface must be ethernet"; 189 } 190 } 191 // other bonding config params, failover times etc. 192 } 194 4. Interfaces YANG Module 196 RFC Ed.: update the date below with the date of RFC publication and 197 remove this note. 199 This YANG module references [RFC2863]. 201 file "ietf-interfaces@2011-03-30.yang" 203 module ietf-interfaces { 205 namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces"; 206 prefix "if"; 208 import iana-if-type { 209 prefix ift; 210 } 212 organization 213 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 215 contact 216 "WG Web: 217 WG List: 219 WG Chair: David Kessens 220 222 WG Chair: Juergen Schoenwaelder 223 225 Editor: Martin Bjorklund 226 "; 228 description 229 "This module contains a collection of YANG definitions for 230 configuring network interfaces. 232 Copyright (c) 2011 IETF Trust and the persons identified as 233 authors of the code. All rights reserved. 235 Redistribution and use in source and binary forms, with or 236 without modification, is permitted pursuant to, and subject 237 to the license terms contained in, the Simplified BSD License 238 set forth in Section 4.c of the IETF Trust's Legal Provisions 239 Relating to IETF Documents 240 (http://trustee.ietf.org/license-info). 241 This version of this YANG module is part of RFC XXXX; see 242 the RFC itself for full legal notices."; 244 // RFC Ed.: replace XXXX with actual RFC number and remove this 245 // note. 247 // RFC Ed.: update the date below with the date of RFC publication 248 // and remove this note. 249 revision 2011-03-29 { 250 description 251 "Initial revision."; 252 reference 253 "RFC XXXX: A YANG Data Model for Interface Configuration"; 254 } 256 /* Typedefs */ 258 typedef interface-ref { 259 type leafref { 260 path "/if:interfaces/if:interface/if:name"; 261 } 262 description 263 "This type is used by data models that need to reference 264 interfaces."; 265 } 267 /* Features */ 269 feature snmp-if-mib { 270 description 271 "This feature indicates that the server implements IF-MIB, 272 accessible over SNMP."; 273 reference 274 "RFC 2863: The Interfaces Group MIB"; 275 } 277 /* Data nodes */ 279 container interfaces { 280 description 281 "Interface parameters."; 283 list interface { 284 key "name"; 285 unique "type location"; 287 description 288 "The list of configured interfaces on the device."; 290 leaf name { 291 type string { 292 length "1..255"; 293 } 294 description 295 "An arbitrary name for the interface. 297 A device MAY restrict the allowed values for this leaf, 298 possibly depending on the type and location. 300 For example, if a device has a single array of 8 ethernet 301 ports, the name might be restricted to be on the form 302 'ethN', where N is an integer between '1' and '8'."; 303 } 305 leaf description { 306 type string; 307 description 308 "A textual description of the interface. 310 This leaf MAY be mapped to ifAlias by an implementation. 311 Such an implementation MAY restrict the length of the 312 value of this leaf so that it matches the restrictions 313 of ifAlias."; 314 reference 315 "RFC 2863: The Interfaces Group MIB - ifAlias"; 316 } 318 leaf type { 319 type ift:iana-if-type; 320 mandatory true; 321 description 322 "The type of the interface. 324 When an interface entry is created, a server MAY 325 initialize the type leaf with a valid value, e.g., if it 326 is possible to derive the type from the name of the 327 interface."; 328 } 330 leaf location { 331 type string; 332 description 333 "The device-specific location of the interface of a 334 particular type. The format of the location string 335 depends on the interface type and the device. 337 Media-specific modules must specify if the location 338 is needed for the given type. 340 For example, if a device has a single array of 8 ethernet 341 ports, the location can be one of '1' to '8'. As another 342 example, if a device has N cards of M ports, the location 343 can be on the form 'n/m'. 345 When an interface entry is created, a server MAY 346 initialize the location leaf with a valid value, e.g., if 347 it is possible to derive the location from the name of 348 the interface."; 349 } 351 leaf admin-status { 352 type enumeration { 353 enum "up" { 354 value 1; 355 } 356 enum "down" { 357 value 2; 358 } 359 } 360 default "up"; 361 description 362 "The desired state of the interface. 364 This leaf contains the configured, desired state of the 365 interface. Systems that implement the IF-MIB use the 366 value of this leaf to set IF-MIB.ifAdminStatus after an 367 ifEntry has been initialized, as described in RFC 2863."; 368 // FIXME: Can we say that changing ifAdminStatus does NOT 369 // change this object? If not, is the opposite 370 // always true, i.e. that changing ifAdminStatus 371 // results in a change of this object (in running)? 372 // Or should we be silent? 373 reference 374 "RFC 2863: The Interfaces Group MIB - ifAdminStatus"; 375 } 377 leaf-list if-index { 378 if-feature snmp-if-mib; 379 type int32 { 380 range "1..2147483647"; 381 } 382 config false; 383 description 384 "The list of ifIndex values for all ifEntries that are 385 represented by this interface. If there is a one-to-one 386 mapping between the interface and entries in the ifTable, 387 this leaf-list will have a single value. 389 Media-specific modules must specify how the type is 390 mapped to entries in the ifTable."; 391 reference 392 "RFC 2863: The Interfaces Group MIB - ifIndex"; 393 } 395 leaf mtu { 396 type uint32; 397 description 398 "The size, in octets, of the largest packet that the 399 interface can send and receive. This node might not be 400 valid for all interface types. 402 Media-specific modules must specify any restrictions on 403 the mtu for their interface type."; 404 } 406 leaf link-up-down-trap-enable { 407 if-feature snmp-if-mib; 408 type enumeration { 409 enum enabled { 410 value 1; 411 } 412 enum disabled { 413 value 2; 414 } 415 } 416 description 417 "Indicates whether linkUp/linkDown SNMP traps should be 418 generated for this interface. 420 If this node is not configured, the value 'enabled' is 421 operationally used by the server for interfaces which do 422 not operate on top of any other intertface (as defined in 423 the ifStackTable), and 'disabled' otherwise."; 424 reference 425 "RFC 2863: The Interfaces Group MIB - 426 ifLinkUpDownTrapEnable"; 427 } 428 } 429 } 430 } 432 434 5. IANA Considerations 436 This document registers a URI in the IETF XML registry [RFC3688]. 437 Following the format in RFC 3688, the following registration is 438 requested to be made. 440 URI: urn:ietf:params:xml:ns:yang:ietf-interfaces 442 Registrant Contact: The NETMOD WG of the IETF. 444 XML: N/A, the requested URI is an XML namespace. 446 This document registers a YANG module in the YANG Module Names 447 registry [RFC6020]. 449 name: ietf-interfaces 450 namespace: urn:ietf:params:xml:ns:yang:ietf-interfaces 451 prefix: if 452 reference: RFC XXXX 454 6. Security Considerations 456 TBD. 458 7. Acknowledgments 460 The author wishes to thank Per Hedeland, Ladislav Lhotka, and Juergen 461 Schoenwaelder for their helpful comments. 463 8. Normative References 465 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 466 Requirement Levels", BCP 14, RFC 2119, March 1997. 468 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 469 MIB", RFC 2863, June 2000. 471 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 472 January 2004. 474 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 475 Network Configuration Protocol (NETCONF)", RFC 6020, 476 October 2010. 478 Appendix A. Example: Ethernet Interface Module 480 This section gives a simple example of how an Ethernet interface 481 module could be defined. It demonstrates how media-specific 482 configuration parameters can be conditionally augmented to the 483 generic interface list. It is not intended as a complete module for 484 ethernet configuration. 486 module ex-ethernet { 487 namespace "http://example.com/ethernet"; 488 prefix "eth"; 490 import ietf-interfaces { 491 prefix if; 492 } 494 augment "/if:interfaces/if:interface" { 495 when "if:type = 'ethernetCsmacd'"; 496 container ethernet { 497 must "../if:location" { 498 description 499 "An ethernet interface must specify the physical location 500 of the ethernet hardware."; 501 } 502 choice transmission-params { 503 case auto { 504 leaf auto-negotiate { 505 type empty; 506 } 507 } 508 case manual { 509 leaf duplex { 510 type enumeration { 511 enum "half"; 512 enum "full"; 513 } 514 } 515 leaf speed { 516 type enumeration { 517 enum "10Mb"; 518 enum "100Mb"; 519 enum "1Gb"; 520 enum "10Gb"; 521 } 522 } 523 } 524 } 525 // other ethernet specific params... 526 } 527 } 528 } 530 Appendix B. Example: Ethernet Bonding Interface Module 532 This section gives an example of how interface layering can be 533 defined. An ethernet bonding interface is defined, which bonds 534 several ethernet interfaces into one logical interface. 536 module ex-ethernet-bonding { 537 namespace "http://example.com/ethernet-bonding"; 538 prefix "bond"; 540 import ietf-interfaces { 541 prefix if; 542 } 544 augment "/if:interfaces/if:interface" { 545 when "if:type = 'ieee8023adLag'"; 546 leaf-list slave-if { 547 type if:interface-ref; 548 must "/if:interfaces/if:interface[if:name = current()]" 549 + "/if:type = 'ethernetCsmacd'" { 550 description 551 "The type of a slave interface must be ethernet."; 552 } 553 } 554 leaf bonding-mode { 555 type enumeration { 556 enum round-robin; 557 enum active-backup; 558 enum broadcast; 559 } 560 } 561 // other bonding config params, failover times etc. 562 } 563 } 565 Appendix C. Example: VLAN Interface Module 567 This section gives an example of how a vlan interface module can be 568 defined. 570 module ex-vlan { 571 namespace "http://example.com/vlan"; 572 prefix "vlan"; 574 import ietf-interfaces { 575 prefix if; 576 } 578 augment "/if:interfaces/if:interface" { 579 when "if:type = 'ethernetCsmacd' or 580 if:type = 'ieee8023adLag'"; 581 leaf vlan-tagging { 582 type boolean; 583 default false; 584 } 585 } 587 augment "/if:interfaces/if:interface" { 588 when "if:type = 'l2vlan'"; 589 leaf base-interface { 590 type if:interface-ref; 591 must "/if:interfaces/if:interface[if:name = current()]" 592 + "/vlan:vlan-tagging = true" { 593 description 594 "The base interface must have vlan tagging enabled."; 595 } 596 } 597 leaf vlan-id { 598 type uint16 { 599 range "1..4094"; 600 } 601 must "../base-interface"; 602 } 603 } 604 } 606 Appendix D. Example: IP Module 608 This section gives an example how an IP module can be defined. 610 module ex-ip { 612 namespace "http://example.com/ip"; 613 prefix "ip"; 615 import ietf-interfaces { 616 prefix if; 617 } 619 import ietf-inet-types { 620 prefix inet; 621 } 623 augment "/if:interfaces/if:interface" { 624 container ip { 625 list address { 626 key "ip"; 627 leaf ip { 628 type inet:ip-address; 629 } 630 leaf prefix-length { 631 type uint16; 632 // range depends on type of address 633 } 634 } 635 } 636 } 637 } 639 Appendix E. Example: NETCONF reply 641 This section gives an example of a reply to the NETCOMF request 642 for a device that implements the example data models above. 644 647 648 650 651 eth0 652 ethernetCsmacd 653 0 654 up 655 2 656 657
658 192.0.2.1 659 24 660
661 662 663 664 eth1 665 ethernetCsmacd 666 1 667 up 668 7 669 670
671 192.168.1.1 672 24 673
674 675 676 677 678 680 Author's Address 682 Martin Bjorklund 683 Tail-f Systems 685 Email: mbj@tail-f.com