idnits 2.17.1 draft-bjorklund-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 (December 8, 2010) is 4882 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 December 8, 2010 5 Expires: June 11, 2011 7 A YANG Data Model for Interface Configuration 8 draft-bjorklund-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 June 11, 2011. 34 Copyright Notice 36 Copyright (c) 2010 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 . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . 21 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 68 1. Introduction 70 This document defines a YANG [RFC6020] data model for the 71 configuration of network interfaces. It is expected that interface 72 type specific configuration data models augment the generic 73 interfaces data model defined in this document. 75 Network interfaces are central to the configuration of many Internet 76 protocols. Thus, it is important to establish a common data model 77 for how interfaces are identified and configured. 79 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 81 "OPTIONAL" in this document are to be interpreted as described in BCP 82 14, [RFC2119]. 84 2. Objectives 86 This section describes some of the design objectives for the model 87 presented in Section 4. 89 o It is recognized that existing implementations will have to map 90 the interface data model defined in this memo to their proprietary 91 native data model. The new data model should be simple to 92 facilitate such mappings. 94 o The data model should be suitable for new implementations to use 95 as-is, without requiring a mapping to a different native model. 97 o The data model must be extensible for different specific interface 98 types, including vendor-specific types. 100 o References to interfaces should be as simple as possible, 101 preferably by using a single leafref. 103 o The mapping to ifIndex [RFC2863] used by SNMP to identify 104 interfaces must be clear. 106 o The model must support interface layering, both simple layering 107 where one interface is layered on top of exactly one other 108 interface, and more complex scenarios where one interface is 109 aggregated over N other interfaces, or when N interfaces are 110 multiplexed over one other interface. 112 o The data model should support the pre-provisioning of interface 113 configuration, i.e, it should be possible to configure an 114 interface whose physical interface hardware is not present on the 115 device. It is recommended that devices that supports dynamic 116 addition and removal of physical interfaces also support pre- 117 provisioning. 119 3. Interfaces Data Model 121 3.1. The interface List 123 The data model for interface configuration presented in this document 124 uses a flat list of interfaces. Each interface in the list is 125 identified by its name. Furthermore, each interface has a mandatory 126 "type" leaf, and a "location" leaf. The combination of "type" and 127 "location" is unique within the interface list. 129 The "type" is a YANG identity which must be derived from the base 130 identity "interface-type". By using an identity instead of an 131 enumeration, the definition of interface types is decentralized. 132 Other standard or vendor-specific data models can define their own 133 interface types without having to update a central data model. 135 It is expected that interface type specific data models augment the 136 interface list, and use the "type" leaf to make the augmentation 137 conditional. 139 As an example of such a interface type specific augmentation, 140 consider this YANG snippet. For a more complete example, see 141 Appendix A. 143 import interfaces { 144 prefix "if"; 145 } 147 augment "/if:interfaces/if:interface" { 148 when "if:type = 'ethernet'"; 149 container ethernet { 150 leaf duplex { 151 ... 152 } 153 } 154 } 156 The "location" leaf is a string. It is optional in the data model, 157 but if the type represents a physical interface, it is mandatory. 158 The format of this string is device- and type-dependent. The device 159 uses the location string to identify the physical or logical entity 160 that the configuration applies to. For example, if a device has a 161 single array of 8 ethernet ports, the location can be one of the 162 strings "1" to "8". As another example, if a device has N cards of M 163 ports, the location can be on the form "n/m", such as "1/0". 165 How a client can learn which types and locations are present on a 166 certain device is outside the scope of this document. 168 3.2. Interface References 170 An interface is uniquely identified by its name. This property is 171 captured in the "interface-ref" typedef, which other YANG modules 172 SHOULD use when they need to reference an existing interface. 174 3.3. Interface Layering 176 There is no generic mechanism for how an interface is configured to 177 be layered on top some other interface. It is expected that 178 interface type specific models define their own objects for interface 179 layering, by using "interface-ref" types to reference lower layers. 181 Below is an example of a model with such objects. For a more 182 complete example, see Appendix B. 184 identity eth-bonding { 185 base if:interface-type; 186 } 188 augment "/if:interfaces/if:interface" { 189 when "if:type = eth-bonding"; 191 leaf-list slave-if { 192 type if:interface-ref; 193 must "/if:interfaces/if:interface[if:name = current()]" 194 + "/if:type = 'eth:ethernet'" { 195 description 196 "The type of a slave interface must be ethernet"; 197 } 198 } 199 // other bonding config params, failover times etc. 200 } 202 4. Interfaces YANG module 204 RFC Ed.: update the date below with the date of RFC publication and 205 remove this note. 207 file "ietf-interfaces@2010-12-08.yang" 209 module ietf-interfaces { 211 namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces"; 212 prefix "if"; 214 organization 215 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 217 contact 218 "WG Web: 219 WG List: 221 WG Chair: David Kessens 222 224 WG Chair: Juergen Schoenwaelder 225 227 Editor: Martin Bjorklund 228 "; 230 description 231 "This module contains a collection of YANG definitions for 232 configuring network interfaces. 234 Copyright (c) 2010 IETF Trust and the persons identified as 235 authors of the code. All rights reserved. 237 Redistribution and use in source and binary forms, with or 238 without modification, is permitted pursuant to, and subject 239 to the license terms contained in, the Simplified BSD License 240 set forth in Section 4.c of the IETF Trust's Legal Provisions 241 Relating to IETF Documents 242 (http://trustee.ietf.org/license-info). 244 This version of this YANG module is part of RFC XXXX; see 245 the RFC itself for full legal notices."; 247 // RFC Ed.: replace XXXX with actual RFC number and remove this 248 // note. 250 // RFC Ed.: update the date below with the date of RFC publication 251 // and remove this note. 252 revision 2010-12-08 { 253 description 254 "Initial revision."; 255 reference 256 "RFC XXXX: A YANG Data Model for Interface Configuration"; 257 } 259 /* Typedefs */ 261 typedef interface-ref { 262 type leafref { 263 path "/if:interfaces/if:interface/if:name"; 264 } 265 description 266 "This type is used by data models that need to reference 267 interfaces."; 268 } 270 /* Features */ 272 feature snmp-if-mib { 273 description 274 "This feature indicates that the server implements IF-MIB, 275 accessible over SNMP."; 276 } 278 /* Identities */ 280 identity interface-type { 281 description 282 "The base identity from which media-specific interface 283 identities are derived."; 284 } 286 /* Data nodes */ 288 container interfaces { 289 description 290 "Interface parameters."; 292 list interface { 293 key "name"; 294 unique "type location"; 296 description 297 "The list of configurable interfaces on the device."; 299 leaf name { 300 type string { 301 length "1..255"; 302 } 303 description 304 "An arbitrary name for the interface. 306 A device MAY restrict the allowed values for this leaf, 307 possibly depending on the type and location."; 308 } 310 leaf type { 311 type identityref { 312 base interface-type; 313 } 314 mandatory true; 315 description 316 "The type of the interface. 318 When an interface entry is created, a server MAY 319 initialize the type leaf with a valid value, e.g. if it 320 is possible to derive the type from the name of the 321 interface."; 322 } 324 leaf location { 325 type string; 326 description 327 "The device-specific location of the interface of a 328 particular type. The format of the location string 329 depends on the interface type and the device. 331 Media-specific modules must specify if the location 332 is needed for the given type. 334 For example, if a device has a single array of 8 ethernet 335 ports, the location can be one of '1' to '8'. As another 336 example, if a device has N cards of M ports, the location 337 can be on the form 'n/m'. 339 When an interface entry is created, a server MAY 340 initialize the location leaf with a valid value, e.g. if 341 it is possible to derive the location from the name of 342 the interface."; 343 } 345 leaf admin-status { 346 type enumeration { 347 enum "up"; 348 enum "down"; 349 } 350 default "up"; 351 description 352 "The desired state of the interface. 354 This leaf contains the configured, desired state of the 355 interface. Systems that implement the IF-MIB use the 356 value of this leaf to set IF-MIB.ifAdminStatus after an 357 ifEntry has been initialized, as described in RFC 2863."; 358 // FIXME: Can we say that changing ifAdminStatus does NOT 359 // change this object? If not, is the opposite 360 // always true, i.e. that changing ifAdminStatus 361 // results in a change of this object (in running)? 362 // Or should we be silent? 363 reference 364 "RFC 2863: The Interfaces Group MIB - ifAdminStatus"; 365 } 367 leaf-list if-index { 368 if-feature snmp-if-mib; 369 type int32 { 370 range "1..2147483647"; 371 } 372 config false; 373 description 374 "The list of ifIndex values for all ifEntries that are 375 represented by this interface. If there is a one-to-one 376 mapping between the interface and entries in the ifTable, 377 this leaf-list will have a single value. 379 Media-specific modules must specify how the type is 380 mapped to entries in the ifTable."; 381 reference 382 "RFC 2863: The Interfaces Group MIB - ifIndex"; 383 } 385 leaf mtu { 386 type uint32; 387 description 388 "The size, in octets, of the largest packet that the 389 interface can send and receive. This node might not be 390 valid for all interface types. 392 Media-specific modules must specify any restrictions on 393 the mtu for their interface type."; 394 } 396 } 397 } 398 } 400 402 5. IANA Considerations 404 This document registers a URI in the IETF XML registry [RFC3688]. 405 Following the format in RFC 3688, the following registration is 406 requested to be made. 408 URI: urn:ietf:params:xml:ns:yang:ietf-interfaces 410 Registrant Contact: The NETMOD WG of the IETF. 412 XML: N/A, the requested URI is an XML namespace. 414 This document registers a YANG module in the YANG Module Names 415 registry [RFC6020]. 417 name: ietf-interfaces 418 namespace: urn:ietf:params:xml:ns:yang:ietf-interfaces 419 prefix: if 420 reference: RFC XXXX 422 6. Security Considerations 424 TBD. 426 7. Acknowledgments 428 The author wishes to thank Per Hedeland, Ladislav Lhotka, and Juergen 429 Schoenwaelder for their helpful comments. 431 8. Normative References 433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 434 Requirement Levels", BCP 14, RFC 2119, March 1997. 436 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 437 MIB", RFC 2863, June 2000. 439 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 440 January 2004. 442 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 443 Network Configuration Protocol (NETCONF)", RFC 6020, 444 October 2010. 446 Appendix A. Example: Ethernet Interface Module 448 This section gives a simple example of how an Ethernet interface 449 module could be defined. It demonstrates how a media-specific type 450 can be derived from the base identity "interface-type", and how 451 media-specific configuration parameters can be conditionally 452 augmented to the generic interface list. It is not intended as a 453 complete module for ethernet configuration. 455 module ex-ethernet { 456 namespace "http://example.com/ethernet"; 457 prefix "eth"; 459 import ietf-interfaces { 460 prefix if; 461 } 463 identity ethernet { 464 base if:interface-type; 465 } 467 augment "/if:interfaces/if:interface" { 468 when "if:type = 'eth:ethernet'"; 469 container ethernet { 470 must "../if:location" { 471 description 472 "An ethernet interface must specify the physical location 473 of the ethernet hardware."; 474 } 475 choice transmission-params { 476 case auto { 477 leaf auto-negotiate { 478 type empty; 479 } 480 } 481 case manual { 482 leaf duplex { 483 type enumeration { 484 enum "half"; 485 enum "full"; 486 } 487 } 488 leaf speed { 489 type enumeration { 490 enum "10Mb"; 491 enum "100Mb"; 492 enum "1Gb"; 493 enum "10Gb"; 494 } 495 } 496 } 497 } 498 // other ethernet specific params... 499 } 500 } 501 } 503 Appendix B. Example: Ethernet Bonding Interface Module 505 This section gives an example of how interface layering can be 506 defined. An ethernet bonding type is defined, which bonds several 507 ethernet interfaces into one logical interface. 509 module ex-ethernet-bonding { 510 namespace "http://example.com/ethernet-bonding"; 511 prefix "bond"; 513 import ietf-interfaces { 514 prefix if; 515 } 516 import ex-ethernet { 517 prefix eth; 518 } 520 identity eth-bonding { 521 base if:interface-type; 522 } 524 augment "/if:interfaces/if:interface" { 525 when "if:type = 'bond:eth-bonding'"; 526 leaf-list slave-if { 527 type if:interface-ref; 528 must "/if:interfaces/if:interface[if:name = current()]" 529 + "/if:type = 'eth:ethernet'" { 530 description 531 "The type of a slave interface must be ethernet."; 532 } 533 } 534 leaf bonding-mode { 535 type enumeration { 536 enum round-robin; 537 enum active-backup; 538 enum broadcast; 539 } 540 } 541 // other bonding config params, failover times etc. 542 } 543 } 545 Appendix C. Example: VLAN Interface Module 547 This section gives an example of how vlan interface module can be 548 defined. 550 module ex-vlan { 551 namespace "http://example.com/vlan"; 552 prefix "vlan"; 554 import ietf-interfaces { 555 prefix if; 556 } 557 import ex-ethernet { 558 prefix eth; 559 } 560 import ex-ethernet-bonding { 561 prefix bond; 562 } 564 identity vlan { 565 base if:interface-type; 566 } 568 augment "/if:interfaces/if:interface" { 569 when "if:type = 'eth:ethernet' or 570 if:type = 'bond:eth-bonding'"; 571 // Should we list all types that support vlan tagging here, or 572 // should we just remove the when, and state in text that not 573 // all interfaces support this? 574 leaf vlan-tagging { 575 type boolean; 576 default false; 577 } 578 } 580 augment "/if:interfaces/if:interface" { 581 when "if:type = 'vlan:vlan'"; 582 leaf base-interface { 583 type if:interface-ref; 584 must "/if:interfaces/if:interface[if:name = current()]" 585 + "/vlan:vlan-tagging = true" { 586 description 587 "The base interface must have vlan tagging enabled."; 588 } 589 } 590 leaf vlan-id { 591 type uint16 { 592 range "1..4094"; 593 } 594 must "../base-interface"; 595 } 596 } 597 } 599 Appendix D. Example: IP Module 601 This section gives an example how an IP module can be defined. 603 module ex-ip { 605 namespace "http://example.com/ip"; 606 prefix "ip"; 608 import ietf-interfaces { 609 prefix if; 610 } 612 import ietf-inet-types { 613 prefix inet; 614 } 616 augment "/if:interfaces/if:interface" { 617 container ip { 618 list address { 619 key "ip"; 620 leaf ip { 621 type inet:ip-address; 622 } 623 leaf prefix-length { 624 type uint16; 625 // range depends on type of address 626 } 627 } 628 } 629 } 630 } 632 Author's Address 634 Martin Bjorklund 635 Tail-f Systems 637 Email: mbj@tail-f.com