idnits 2.17.1 draft-ietf-netmod-interfaces-cfg-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to 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 (September 7, 2011) is 4613 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) == Outdated reference: A later version (-10) exists of draft-ietf-netmod-iana-if-type-00 Summary: 0 errors (**), 0 flaws (~~), 3 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 September 7, 2011 5 Expires: March 10, 2012 7 A YANG Data Model for Interface Configuration 8 draft-ietf-netmod-interfaces-cfg-02 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 March 10, 2012. 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 . . . . . . . . . . . . . . . . . . . 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: NETCONF reply . . . . . . . . . . . . 20 66 Appendix E. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 21 67 E.1. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 21 68 E.2. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 21 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 71 1. Introduction 73 This document defines a YANG [RFC6020] data model for the 74 configuration of network interfaces. It is expected that interface 75 type specific configuration data models augment the generic 76 interfaces data model defined in this document. 78 Network interfaces are central to the configuration of many Internet 79 protocols. Thus, it is important to establish a common data model 80 for how interfaces are identified and configured. 82 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 83 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 84 "OPTIONAL" in this document are to be interpreted as described in BCP 85 14, [RFC2119]. 87 2. Objectives 89 This section describes some of the design objectives for the model 90 presented in Section 4. 92 o It is recognized that existing implementations will have to map 93 the interface data model defined in this memo to their proprietary 94 native data model. The new data model should be simple to 95 facilitate such mappings. 97 o The data model should be suitable for new implementations to use 98 as-is, without requiring a mapping to a different native model. 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 support dynamic 116 addition and removal of physical interfaces also support pre- 117 provisioning. 119 3. Interfaces Data Model 121 The module "ietf-interfaces" has the following structure: 123 +--rw interfaces 124 +--rw interface [name] 125 +--rw name string 126 +--rw description? string 127 +--rw type ianaift:iana-if-type 128 +--rw location? string 129 +--rw enabled? boolean 130 +--ro if-index* int32 131 +--rw mtu? uint32 132 +--rw link-up-down-trap-enable? enumeration 134 This module defines one YANG feature: 136 snmp-if-mib: Indicates that the server implements IF-MIB [RFC2863]. 138 3.1. The interface List 140 The data model for interface configuration presented in this document 141 uses a flat list of interfaces. Each interface in the list is 142 identified by its name. Furthermore, each interface has a mandatory 143 "type" leaf, and a "location" leaf. The combination of "type" and 144 "location" is unique within the interface list. 146 It is expected that interface type specific data models augment the 147 interface list, and use the "type" leaf to make the augmentation 148 conditional. 150 As an example of such an interface type specific augmentation, 151 consider this YANG snippet. For a more complete example, see 152 Appendix A. 154 import interfaces { 155 prefix "if"; 156 } 158 augment "/if:interfaces/if:interface" { 159 when "if:type = 'ethernetCsmacd'"; 161 container ethernet { 162 leaf duplex { 163 ... 164 } 165 } 166 } 168 The "location" leaf is a string. It is optional in the data model, 169 but if the type represents a physical interface, it is mandatory. 170 The format of this string is device- and type-dependent. The device 171 uses the location string to identify the physical or logical entity 172 that the configuration applies to. For example, if a device has a 173 single array of 8 ethernet ports, the location can be one of the 174 strings "1" to "8". As another example, if a device has N cards of M 175 ports, the location can be on the form "n/m", such as "1/0". 177 How a client can learn which types and locations are present on a 178 certain device is outside the scope of this document. 180 3.2. Interface References 182 An interface is uniquely identified by its name. This property is 183 captured in the "interface-ref" typedef, which other YANG modules 184 SHOULD use when they need to reference an existing interface. 186 3.3. Interface Layering 188 There is no generic mechanism for how an interface is configured to 189 be layered on top of some other interface. It is expected that 190 interface type specific models define their own nodes for interface 191 layering, by using "interface-ref" types to reference lower layers. 193 Below is an example of a model with such nodes. For a more complete 194 example, see Appendix B. 196 augment "/if:interfaces/if:interface" { 197 when "if:type = 'ieee8023adLag'"; 199 leaf-list slave-if { 200 type if:interface-ref; 201 must "/if:interfaces/if:interface[if:name = current()]" 202 + "/if:type = 'ethernetCsmacd'" { 203 description 204 "The type of a slave interface must be ethernet"; 205 } 206 } 207 // other bonding config params, failover times etc. 208 } 210 4. Interfaces YANG Module 212 This YANG module imports a typedef from 213 [I-D.ietf-netmod-iana-if-type]. 215 RFC Ed.: update the date below with the date of RFC publication and 216 remove this note. 218 file "ietf-interfaces@2011-09-07.yang" 220 module ietf-interfaces { 222 namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces"; 223 prefix if; 225 import iana-if-type { 226 prefix ianaift; 227 } 229 organization 230 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 232 contact 233 "WG Web: 234 WG List: 236 WG Chair: David Kessens 237 239 WG Chair: Juergen Schoenwaelder 240 242 Editor: Martin Bjorklund 243 "; 245 description 246 "This module contains a collection of YANG definitions for 247 configuring network interfaces. 249 Copyright (c) 2011 IETF Trust and the persons identified as 250 authors of the code. All rights reserved. 252 Redistribution and use in source and binary forms, with or 253 without modification, is permitted pursuant to, and subject 254 to the license terms contained in, the Simplified BSD License 255 set forth in Section 4.c of the IETF Trust's Legal Provisions 256 Relating to IETF Documents 257 (http://trustee.ietf.org/license-info). 258 This version of this YANG module is part of RFC XXXX; see 259 the RFC itself for full legal notices."; 261 // RFC Ed.: replace XXXX with actual RFC number and remove this 262 // note. 264 // RFC Ed.: update the date below with the date of RFC publication 265 // and remove this note. 266 revision 2011-09-07 { 267 description 268 "Initial revision."; 269 reference 270 "RFC XXXX: A YANG Data Model for Interface Configuration"; 271 } 273 /* Typedefs */ 275 typedef interface-ref { 276 type leafref { 277 path "/if:interfaces/if:interface/if:name"; 278 } 279 description 280 "This type is used by data models that need to reference 281 interfaces."; 282 } 284 /* Features */ 286 feature snmp-if-mib { 287 description 288 "This feature indicates that the server implements IF-MIB."; 289 reference 290 "RFC 2863: The Interfaces Group MIB"; 291 } 293 /* Data nodes */ 295 container interfaces { 296 description 297 "Interface parameters."; 299 list interface { 300 key "name"; 301 unique "type location"; 303 description 304 "The list of configured interfaces on the device."; 306 leaf name { 307 type string { 308 length "1..255"; 309 } 310 description 311 "An arbitrary name for the interface. 313 A device MAY restrict the allowed values for this leaf, 314 possibly depending on the type and location. 316 For example, if a device has a single array of 8 ethernet 317 ports, the name might be restricted to be on the form 318 'ethN', where N is an integer between '1' and '8'."; 319 } 321 leaf description { 322 type string; 323 description 324 "A textual description of the interface. 326 This leaf MAY be mapped to ifAlias by an implementation. 327 Such an implementation MAY restrict the length of the 328 value of this leaf so that it matches the restrictions 329 of ifAlias."; 330 reference 331 "RFC 2863: The Interfaces Group MIB - ifAlias"; 332 } 334 leaf type { 335 type ianaift:iana-if-type; 336 mandatory true; 337 description 338 "The type of the interface. 340 When an interface entry is created, a server MAY 341 initialize the type leaf with a valid value, e.g., if it 342 is possible to derive the type from the name of the 343 interface."; 344 } 346 leaf location { 347 type string; 348 description 349 "The device-specific location of the interface of a 350 particular type. The format of the location string 351 depends on the interface type and the device. 353 Media-specific modules must specify if the location 354 is needed for the given type. 356 For example, if a device has a single array of 8 ethernet 357 ports, the location can be one of '1' to '8'. As another 358 example, if a device has N cards of M ports, the location 359 can be on the form 'n/m'. 361 When an interface entry is created, a server MAY 362 initialize the location leaf with a valid value, e.g., if 363 it is possible to derive the location from the name of 364 the interface."; 365 } 367 leaf enabled { 368 type boolean; 369 default "true"; 370 description 371 "The desired state of the interface. 373 This leaf contains the configured, desired state of the 374 interface. Systems that implement the IF-MIB use the 375 value of this leaf to set IF-MIB.ifAdminStatus after an 376 ifEntry has been initialized, as described in RFC 2863."; 377 reference 378 "RFC 2863: The Interfaces Group MIB - ifAdminStatus"; 379 } 381 leaf-list if-index { 382 if-feature snmp-if-mib; 383 type int32 { 384 range "1..2147483647"; 385 } 386 config false; 387 description 388 "The list of ifIndex values for all ifEntries that are 389 represented by this interface. If there is a one-to-one 390 mapping between the interface and entries in the ifTable, 391 this leaf-list will have a single value. 393 Media-specific modules must specify how the type is 394 mapped to entries in the ifTable."; 395 reference 396 "RFC 2863: The Interfaces Group MIB - ifIndex"; 397 } 399 leaf mtu { 400 type uint32; 401 description 402 "The size, in octets, of the largest packet that the 403 interface can send and receive. This node might not be 404 valid for all interface types. 406 Media-specific modules must specify any restrictions on 407 the mtu for their interface type."; 408 } 410 leaf link-up-down-trap-enable { 411 if-feature snmp-if-mib; 412 type enumeration { 413 enum enabled { 414 value 1; 415 } 416 enum disabled { 417 value 2; 418 } 419 } 420 description 421 "Indicates whether linkUp/linkDown SNMP traps should be 422 generated for this interface. 424 If this node is not configured, the value 'enabled' is 425 operationally used by the server for interfaces which do 426 not operate on top of any other intertface (as defined in 427 the ifStackTable), and 'disabled' otherwise."; 428 reference 429 "RFC 2863: The Interfaces Group MIB - 430 ifLinkUpDownTrapEnable"; 431 } 432 } 433 } 434 } 436 438 5. IANA Considerations 440 This document registers a URI in the IETF XML registry [RFC3688]. 441 Following the format in RFC 3688, the following registration is 442 requested to be made. 444 URI: urn:ietf:params:xml:ns:yang:ietf-interfaces 446 Registrant Contact: The NETMOD WG of the IETF. 448 XML: N/A, the requested URI is an XML namespace. 450 This document registers a YANG module in the YANG Module Names 451 registry [RFC6020]. 453 name: ietf-interfaces 454 namespace: urn:ietf:params:xml:ns:yang:ietf-interfaces 455 prefix: if 456 reference: RFC XXXX 458 6. Security Considerations 460 The YANG module defined in this memo is designed to be accessed via 461 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 462 secure transport layer and the mandatory-to-implement secure 463 transport is SSH [RFC6242]. 465 There are a number of data nodes defined in the YANG module which are 466 writable/creatable/deletable (i.e., config true, which is the 467 default). These data nodes may be considered sensitive or vulnerable 468 in some network environments. Write operations (e.g., edit-config) 469 to these data nodes without proper protection can have a negative 470 effect on network operations. These are the subtrees and data nodes 471 and their sensitivity/vulnerability: 473 /interfaces/interface: This list specify the configured interfaces 474 on a device. Unauthorized access to this list could cause the 475 device to ignore packets destined to it. 477 /interfaces/interface/enabled: This leaf controls if an interface is 478 enabled or not. Unauthorized access to this leaf could cause the 479 device to ignore packets destined to it. 481 7. Acknowledgments 483 The author wishes to thank Per Hedeland, Ladislav Lhotka, and Juergen 484 Schoenwaelder for their helpful comments. 486 8. Normative References 488 [I-D.ietf-netmod-iana-if-type] 489 Bjorklund, M., "IANA Interface Type YANG Module", 490 draft-ietf-netmod-iana-if-type-00 (work in progress), 491 April 2011. 493 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 494 Requirement Levels", BCP 14, RFC 2119, March 1997. 496 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 497 MIB", RFC 2863, June 2000. 499 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 500 January 2004. 502 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 503 Network Configuration Protocol (NETCONF)", RFC 6020, 504 October 2010. 506 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 507 Bierman, "Network Configuration Protocol (NETCONF)", 508 RFC 6241, June 2011. 510 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 511 Shell (SSH)", RFC 6242, June 2011. 513 Appendix A. Example: Ethernet Interface Module 515 This section gives a simple example of how an Ethernet interface 516 module could be defined. It demonstrates how media-specific 517 configuration parameters can be conditionally augmented to the 518 generic interface list. It is not intended as a complete module for 519 ethernet configuration. 521 module ex-ethernet { 522 namespace "http://example.com/ethernet"; 523 prefix "eth"; 525 import ietf-interfaces { 526 prefix if; 527 } 529 augment "/if:interfaces/if:interface" { 530 when "if:type = 'ethernetCsmacd'"; 532 container ethernet { 533 must "../if:location" { 534 description 535 "An ethernet interface must specify the physical location 536 of the ethernet hardware."; 537 } 538 choice transmission-params { 539 case auto { 540 leaf auto-negotiate { 541 type empty; 542 } 543 } 544 case manual { 545 leaf duplex { 546 type enumeration { 547 enum "half"; 548 enum "full"; 549 } 550 } 551 leaf speed { 552 type enumeration { 553 enum "10Mb"; 554 enum "100Mb"; 555 enum "1Gb"; 556 enum "10Gb"; 557 } 558 } 559 } 560 } 561 // other ethernet specific params... 562 } 563 } 564 } 566 Appendix B. Example: Ethernet Bonding Interface Module 568 This section gives an example of how interface layering can be 569 defined. An ethernet bonding interface is defined, which bonds 570 several ethernet interfaces into one logical interface. 572 module ex-ethernet-bonding { 573 namespace "http://example.com/ethernet-bonding"; 574 prefix "bond"; 576 import ietf-interfaces { 577 prefix if; 578 } 580 augment "/if:interfaces/if:interface" { 581 when "if:type = 'ieee8023adLag'"; 583 leaf-list slave-if { 584 type if:interface-ref; 585 must "/if:interfaces/if:interface[if:name = current()]" 586 + "/if:type = 'ethernetCsmacd'" { 587 description 588 "The type of a slave interface must be ethernet."; 589 } 590 } 591 leaf bonding-mode { 592 type enumeration { 593 enum round-robin; 594 enum active-backup; 595 enum broadcast; 596 } 597 } 598 // other bonding config params, failover times etc. 599 } 600 } 602 Appendix C. Example: VLAN Interface Module 604 This section gives an example of how a vlan interface module can be 605 defined. 607 module ex-vlan { 608 namespace "http://example.com/vlan"; 609 prefix "vlan"; 611 import ietf-interfaces { 612 prefix if; 613 } 615 augment "/if:interfaces/if:interface" { 616 when "if:type = 'ethernetCsmacd' or 617 if:type = 'ieee8023adLag'"; 618 leaf vlan-tagging { 619 type boolean; 620 default false; 621 } 622 } 624 augment "/if:interfaces/if:interface" { 625 when "if:type = 'l2vlan'"; 627 leaf base-interface { 628 type if:interface-ref; 629 must "/if:interfaces/if:interface[if:name = current()]" 630 + "/vlan:vlan-tagging = true" { 631 description 632 "The base interface must have vlan tagging enabled."; 633 } 634 } 635 leaf vlan-id { 636 type uint16 { 637 range "1..4094"; 638 } 639 must "../base-interface"; 640 } 641 } 642 } 644 Appendix D. Example: NETCONF reply 646 This section gives an example of a reply to the NETCOMF request 647 for a device that implements the example data models above. 649 652 653 655 656 eth0 657 ethernetCsmacd 658 0 659 true 660 2 661 662
663 192.0.2.1 664 24 665
666 667 668 669 eth1 670 ethernetCsmacd 671 1 672 true 673 7 674 675
676 192.168.1.1 677 24 678
679 680 681 682 683 685 Appendix E. ChangeLog 687 RFC Editor: remove this section upon publication as an RFC. 689 E.1. Version -02 691 o Editorial fixes 693 E.2. Version -01 695 o Changed leaf "if-admin-status" to leaf "enabled". 697 o Added Security Considerations 699 Author's Address 701 Martin Bjorklund 702 Tail-f Systems 704 Email: mbj@tail-f.com