idnits 2.17.1 draft-ietf-netmod-interfaces-cfg-03.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 (February 8, 2012) is 4461 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 February 8, 2012 5 Expires: August 11, 2012 7 A YANG Data Model for Interface Configuration 8 draft-ietf-netmod-interfaces-cfg-03 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 August 11, 2012. 34 Copyright Notice 36 Copyright (c) 2012 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. Relationship to the IF-MIB . . . . . . . . . . . . . . . . . . 8 58 5. Interfaces YANG Module . . . . . . . . . . . . . . . . . . . . 9 59 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 60 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 61 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 62 9. Normative References . . . . . . . . . . . . . . . . . . . . . 17 63 Appendix A. Example: Ethernet Interface Module . . . . . . . . . 18 64 Appendix B. Example: Ethernet Bonding Interface Module . . . . . 20 65 Appendix C. Example: VLAN Interface Module . . . . . . . . . . . 21 66 Appendix D. Example: NETCONF reply . . . . . . . . . . . . 22 67 Appendix E. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 23 68 E.1. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 23 69 E.2. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 23 70 E.3. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 23 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 24 73 1. Introduction 75 This document defines a YANG [RFC6020] data model for the 76 configuration of network interfaces. It is expected that interface 77 type specific configuration data models augment the generic 78 interfaces data model defined in this document. 80 Network interfaces are central to the configuration of many Internet 81 protocols. Thus, it is important to establish a common data model 82 for how interfaces are identified and configured. 84 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 86 "OPTIONAL" in this document are to be interpreted as described in BCP 87 14, [RFC2119]. 89 2. Objectives 91 This section describes some of the design objectives for the model 92 presented in Section 5. 94 o It is recognized that existing implementations will have to map 95 the interface data model defined in this memo to their proprietary 96 native data model. The new data model should be simple to 97 facilitate such mappings. 99 o The data model should be suitable for new implementations to use 100 as-is, without requiring a mapping to a different native model. 102 o References to interfaces should be as simple as possible, 103 preferably by using a single leafref. 105 o The mapping to ifIndex [RFC2863] used by SNMP to identify 106 interfaces must be clear. 108 o The model must support interface layering, both simple layering 109 where one interface is layered on top of exactly one other 110 interface, and more complex scenarios where one interface is 111 aggregated over N other interfaces, or when N interfaces are 112 multiplexed over one other interface. 114 o The data model should support the pre-provisioning of interface 115 configuration, i.e., it should be possible to configure an 116 interface whose physical interface hardware is not present on the 117 device. It is recommended that devices that support dynamic 118 addition and removal of physical interfaces also support pre- 119 provisioning. 121 3. Interfaces Data Model 123 The data model in the module "ietf-interfaces" has the following 124 structure, where square brackets are used to enclose a list's keys, 125 and "?" means that the leaf is optional: 127 +--rw interfaces 128 +--rw interface [name] 129 +--rw name string 130 +--rw description? string 131 +--rw type ianaift:iana-if-type 132 +--rw location? string 133 +--rw enabled? boolean 134 +--ro if-index int32 135 +--rw mtu? uint32 136 +--rw link-up-down-trap-enable? enumeration 138 This module defines one YANG feature: 140 snmp-if-mib: Indicates that the server implements IF-MIB [RFC2863]. 142 3.1. The interface List 144 The data model for interface configuration presented in this document 145 uses a flat list of interfaces. Each interface in the list is 146 identified by its name. Furthermore, each interface has a mandatory 147 "type" leaf, and a "location" leaf. The combination of "type" and 148 "location" is unique within the interface list. 150 It is expected that interface type specific data models augment the 151 interface list, and use the "type" leaf to make the augmentation 152 conditional. 154 As an example of such an interface type specific augmentation, 155 consider this YANG snippet. For a more complete example, see 156 Appendix A. 158 import interfaces { 159 prefix "if"; 160 } 162 augment "/if:interfaces/if:interface" { 163 when "if:type = 'ethernetCsmacd'"; 165 container ethernet { 166 leaf duplex { 167 ... 168 } 169 } 170 } 172 The "location" leaf is a string. It is optional in the data model, 173 but if the type represents a physical interface, it is mandatory. 174 The format of this string is device- and type-dependent. The device 175 uses the location string to identify the physical or logical entity 176 that the configuration applies to. For example, if a device has a 177 single array of 8 ethernet ports, the location can be one of the 178 strings "1" to "8". As another example, if a device has N cards of M 179 ports, the location can be on the form "n/m", such as "1/0". 181 How a client can learn which types and locations are present on a 182 certain device is outside the scope of this document. 184 3.2. Interface References 186 An interface is uniquely identified by its name. This property is 187 captured in the "interface-ref" typedef, which other YANG modules 188 SHOULD use when they need to reference an existing interface. 190 3.3. Interface Layering 192 There is no generic mechanism for how an interface is configured to 193 be layered on top of some other interface. It is expected that 194 interface type specific models define their own nodes for interface 195 layering, by using "interface-ref" types to reference lower layers. 197 Below is an example of a model with such nodes. For a more complete 198 example, see Appendix B. 200 augment "/if:interfaces/if:interface" { 201 when "if:type = 'ieee8023adLag'"; 203 leaf-list slave-if { 204 type if:interface-ref; 205 must "/if:interfaces/if:interface[if:name = current()]" 206 + "/if:type = 'ethernetCsmacd'" { 207 description 208 "The type of a slave interface must be ethernet"; 209 } 210 } 211 // other bonding config params, failover times etc. 212 } 214 4. Relationship to the IF-MIB 216 If the device implements IF-MIB [RFC2863], each entry in the 217 "interface" list is typically mapped to one ifEntry. The "if-index" 218 leaf contains the value of the corresponding ifEntry's ifIndex. 220 In most cases, the "name" of an "interface" entry is mapped to 221 ifName. ifName is defined as an DisplayString [RFC2579] which uses a 222 7-bit ASCII character set. An implementation MAY restrict the 223 allowed values for "name" to match the restrictions of ifName. 225 The IF-MIB allows two different ifEntries to have the same ifName. 226 Devices that support this feature, and also support the configuration 227 of these interfaces using the "interface" list, cannot have a 1-1 228 mapping between the "name" leaf and ifName. 230 5. Interfaces YANG Module 232 This YANG module imports a typedef from 233 [I-D.ietf-netmod-iana-if-type]. 235 RFC Ed.: update the date below with the date of RFC publication and 236 remove this note. 238 file "ietf-interfaces@2012-02-08.yang" 240 module ietf-interfaces { 242 namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces"; 243 prefix if; 245 import iana-if-type { 246 prefix ianaift; 247 } 249 organization 250 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 252 contact 253 "WG Web: 254 WG List: 256 WG Chair: David Kessens 257 259 WG Chair: Juergen Schoenwaelder 260 262 Editor: Martin Bjorklund 263 "; 265 description 266 "This module contains a collection of YANG definitions for 267 configuring network interfaces. 269 Copyright (c) 2011 IETF Trust and the persons identified as 270 authors of the code. All rights reserved. 272 Redistribution and use in source and binary forms, with or 273 without modification, is permitted pursuant to, and subject 274 to the license terms contained in, the Simplified BSD License 275 set forth in Section 4.c of the IETF Trust's Legal Provisions 276 Relating to IETF Documents 277 (http://trustee.ietf.org/license-info). 278 This version of this YANG module is part of RFC XXXX; see 279 the RFC itself for full legal notices."; 281 // RFC Ed.: replace XXXX with actual RFC number and remove this 282 // note. 284 // RFC Ed.: update the date below with the date of RFC publication 285 // and remove this note. 286 revision 2012-02-08 { 287 description 288 "Initial revision."; 289 reference 290 "RFC XXXX: A YANG Data Model for Interface Configuration"; 291 } 293 /* Typedefs */ 295 typedef interface-ref { 296 type leafref { 297 path "/if:interfaces/if:interface/if:name"; 298 } 299 description 300 "This type is used by data models that need to reference 301 interfaces."; 302 } 304 /* Features */ 306 feature snmp-if-mib { 307 description 308 "This feature indicates that the server implements IF-MIB."; 309 reference 310 "RFC 2863: The Interfaces Group MIB"; 311 } 313 /* Data nodes */ 315 container interfaces { 316 description 317 "Interface parameters."; 319 list interface { 320 key "name"; 321 unique "type location"; 323 description 324 "The list of configured interfaces on the device."; 326 leaf name { 327 type string; 328 description 329 "An arbitrary name for the interface. 331 A device MAY restrict the allowed values for this leaf, 332 possibly depending on the type and location. 334 For example, if a device has a single array of 8 ethernet 335 ports, the name might be restricted to be on the form 336 'ethN', where N is an integer between '1' and '8'. 338 This leaf MAY be mapped to ifName by an implementation. 339 Such an implementation MAY restrict the allowed values 340 for this leaf so that it matches the restrictions of 341 ifName."; 342 reference 343 "RFC 2863: The Interfaces Group MIB - ifName"; 344 } 346 leaf description { 347 type string; 348 description 349 "A textual description of the interface. 351 This leaf MAY be mapped to ifAlias by an implementation. 352 Such an implementation MAY restrict the allowed values 353 for this leaf so that it matches the restrictions of 354 ifAlias."; 355 reference 356 "RFC 2863: The Interfaces Group MIB - ifAlias"; 357 } 359 leaf type { 360 type ianaift:iana-if-type; 361 mandatory true; 362 description 363 "The type of the interface. 365 When an interface entry is created, a server MAY 366 initialize the type leaf with a valid value, e.g., if it 367 is possible to derive the type from the name of the 368 interface."; 369 } 371 leaf location { 372 type string; 373 description 374 "The device-specific location of the interface of a 375 particular type. The format of the location string 376 depends on the interface type and the device. 378 Media-specific modules must specify if the location 379 is needed for the given type. 381 For example, if a device has a single array of 8 ethernet 382 ports, the location can be one of '1' to '8'. As another 383 example, if a device has N cards of M ports, the location 384 can be on the form 'n/m'. 386 When an interface entry is created, a server MAY 387 initialize the location leaf with a valid value, e.g., if 388 it is possible to derive the location from the name of 389 the interface."; 390 } 392 leaf enabled { 393 type boolean; 394 default "true"; 395 description 396 "The desired state of the interface. 398 This leaf contains the configured, desired state of the 399 interface. Systems that implement the IF-MIB use the 400 value of this leaf to set IF-MIB.ifAdminStatus to 'up' or 401 'down' after an ifEntry has been initialized, as described 402 in RFC 2863."; 403 reference 404 "RFC 2863: The Interfaces Group MIB - ifAdminStatus"; 405 } 407 leaf if-index { 408 if-feature snmp-if-mib; 409 type int32 { 410 range "1..2147483647"; 411 } 412 config false; 413 description 414 "The ifIndex value for the ifEntry represented by this 415 interface. 417 Media-specific modules must specify how the type is 418 mapped to entries in the ifTable."; 419 reference 420 "RFC 2863: The Interfaces Group MIB - ifIndex"; 421 } 422 leaf mtu { 423 type uint32; 424 description 425 "The size, in octets, of the largest packet that the 426 interface can send and receive. This node might not be 427 valid for all interface types. 429 Media-specific modules must specify any restrictions on 430 the mtu for their interface type."; 431 } 433 leaf link-up-down-trap-enable { 434 if-feature snmp-if-mib; 435 type enumeration { 436 enum enabled { 437 value 1; 438 } 439 enum disabled { 440 value 2; 441 } 442 } 443 description 444 "Indicates whether linkUp/linkDown SNMP notifications 445 should be generated for this interface. 447 If this node is not configured, the value 'enabled' is 448 operationally used by the server for interfaces which do 449 not operate on top of any other interface (as defined in 450 the ifStackTable), and 'disabled' otherwise."; 451 reference 452 "RFC 2863: The Interfaces Group MIB - 453 ifLinkUpDownTrapEnable"; 454 } 455 } 456 } 457 } 459 461 6. IANA Considerations 463 This document registers a URI in the IETF XML registry [RFC3688]. 464 Following the format in RFC 3688, the following registration is 465 requested to be made. 467 URI: urn:ietf:params:xml:ns:yang:ietf-interfaces 469 Registrant Contact: The IESG. 471 XML: N/A, the requested URI is an XML namespace. 473 This document registers a YANG module in the YANG Module Names 474 registry [RFC6020]. 476 name: ietf-interfaces 477 namespace: urn:ietf:params:xml:ns:yang:ietf-interfaces 478 prefix: if 479 reference: RFC XXXX 481 7. Security Considerations 483 The YANG module defined in this memo is designed to be accessed via 484 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 485 secure transport layer and the mandatory-to-implement secure 486 transport is SSH [RFC6242]. 488 There are a number of data nodes defined in the YANG module which are 489 writable/creatable/deletable (i.e., config true, which is the 490 default). These data nodes may be considered sensitive or vulnerable 491 in some network environments. Write operations (e.g., edit-config) 492 to these data nodes without proper protection can have a negative 493 effect on network operations. These are the subtrees and data nodes 494 and their sensitivity/vulnerability: 496 /interfaces/interface: This list specify the configured interfaces 497 on a device. Unauthorized access to this list could cause the 498 device to ignore packets destined to it. 500 /interfaces/interface/enabled: This leaf controls if an interface is 501 enabled or not. Unauthorized access to this leaf could cause the 502 device to ignore packets destined to it. 504 8. Acknowledgments 506 The author wishes to thank Per Hedeland, Ladislav Lhotka, and Juergen 507 Schoenwaelder for their helpful comments. 509 9. Normative References 511 [I-D.ietf-netmod-iana-if-type] 512 Bjorklund, M., "IANA Interface Type YANG Module", 513 draft-ietf-netmod-iana-if-type-00 (work in progress), 514 April 2011. 516 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 517 Requirement Levels", BCP 14, RFC 2119, March 1997. 519 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 520 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 521 STD 58, RFC 2579, April 1999. 523 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 524 MIB", RFC 2863, June 2000. 526 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 527 January 2004. 529 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 530 Network Configuration Protocol (NETCONF)", RFC 6020, 531 October 2010. 533 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 534 Bierman, "Network Configuration Protocol (NETCONF)", 535 RFC 6241, June 2011. 537 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 538 Shell (SSH)", RFC 6242, June 2011. 540 Appendix A. Example: Ethernet Interface Module 542 This section gives a simple example of how an Ethernet interface 543 module could be defined. It demonstrates how media-specific 544 configuration parameters can be conditionally augmented to the 545 generic interface list. It is not intended as a complete module for 546 ethernet configuration. 548 module ex-ethernet { 549 namespace "http://example.com/ethernet"; 550 prefix "eth"; 552 import ietf-interfaces { 553 prefix if; 554 } 556 augment "/if:interfaces/if:interface" { 557 when "if:type = 'ethernetCsmacd'"; 559 container ethernet { 560 must "../if:location" { 561 description 562 "An ethernet interface must specify the physical location 563 of the ethernet hardware."; 564 } 565 choice transmission-params { 566 case auto { 567 leaf auto-negotiate { 568 type empty; 569 } 570 } 571 case manual { 572 leaf duplex { 573 type enumeration { 574 enum "half"; 575 enum "full"; 576 } 577 } 578 leaf speed { 579 type enumeration { 580 enum "10Mb"; 581 enum "100Mb"; 582 enum "1Gb"; 583 enum "10Gb"; 584 } 585 } 586 } 587 } 588 // other ethernet specific params... 589 } 590 } 591 } 593 Appendix B. Example: Ethernet Bonding Interface Module 595 This section gives an example of how interface layering can be 596 defined. An ethernet bonding interface is defined, which bonds 597 several ethernet interfaces into one logical interface. 599 module ex-ethernet-bonding { 600 namespace "http://example.com/ethernet-bonding"; 601 prefix "bond"; 603 import ietf-interfaces { 604 prefix if; 605 } 607 augment "/if:interfaces/if:interface" { 608 when "if:type = 'ieee8023adLag'"; 610 leaf-list slave-if { 611 type if:interface-ref; 612 must "/if:interfaces/if:interface[if:name = current()]" 613 + "/if:type = 'ethernetCsmacd'" { 614 description 615 "The type of a slave interface must be ethernet."; 616 } 617 } 618 leaf bonding-mode { 619 type enumeration { 620 enum round-robin; 621 enum active-backup; 622 enum broadcast; 623 } 624 } 625 // other bonding config params, failover times etc. 626 } 627 } 629 Appendix C. Example: VLAN Interface Module 631 This section gives an example of how a vlan interface module can be 632 defined. 634 module ex-vlan { 635 namespace "http://example.com/vlan"; 636 prefix "vlan"; 638 import ietf-interfaces { 639 prefix if; 640 } 642 augment "/if:interfaces/if:interface" { 643 when "if:type = 'ethernetCsmacd' or 644 if:type = 'ieee8023adLag'"; 645 leaf vlan-tagging { 646 type boolean; 647 default false; 648 } 649 } 651 augment "/if:interfaces/if:interface" { 652 when "if:type = 'l2vlan'"; 654 leaf base-interface { 655 type if:interface-ref; 656 must "/if:interfaces/if:interface[if:name = current()]" 657 + "/vlan:vlan-tagging = true" { 658 description 659 "The base interface must have vlan tagging enabled."; 660 } 661 } 662 leaf vlan-id { 663 type uint16 { 664 range "1..4094"; 665 } 666 must "../base-interface"; 667 } 668 } 669 } 671 Appendix D. Example: NETCONF reply 673 This section gives an example of a reply to the NETCONF request 674 for a device that implements the example data models above. 676 679 680 682 683 eth0 684 ethernetCsmacd 685 0 686 true 687 2 688 689 690 eth1 691 ethernetCsmacd 692 1 693 true 694 7 695 true 697 698 699 700 702 Appendix E. ChangeLog 704 RFC Editor: remove this section upon publication as an RFC. 706 E.1. Version -03 708 o Added the section Relationship to the IF-MIB. 710 o Changed if-index to be a leaf instead of leaf-list. 712 o Explained the notation used in the data model tree picture. 714 E.2. Version -02 716 o Editorial fixes 718 E.3. Version -01 720 o Changed leaf "if-admin-status" to leaf "enabled". 722 o Added Security Considerations 724 Author's Address 726 Martin Bjorklund 727 Tail-f Systems 729 Email: mbj@tail-f.com