--- 1/draft-ietf-netmod-interfaces-cfg-12.txt 2013-11-07 16:14:59.886592744 -0800 +++ 2/draft-ietf-netmod-interfaces-cfg-13.txt 2013-11-07 16:14:59.954594381 -0800 @@ -1,18 +1,18 @@ Network Working Group M. Bjorklund Internet-Draft Tail-f Systems -Intended status: Standards Track July 4, 2013 -Expires: January 5, 2014 +Intended status: Standards Track November 7, 2013 +Expires: May 11, 2014 A YANG Data Model for Interface Management - draft-ietf-netmod-interfaces-cfg-12 + draft-ietf-netmod-interfaces-cfg-13 Abstract This document defines a YANG data model for the management of network interfaces. It is expected that interface type specific data models augment the generic interfaces data model defined in this document. The data model includes configuration data, state data and counters for the collection of statistics. Status of this Memo @@ -23,21 +23,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 5, 2014. + This Internet-Draft will expire on May 11, 2014. Copyright Notice Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -61,38 +61,39 @@ 5. Interfaces YANG Module . . . . . . . . . . . . . . . . . . . . 11 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 28 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 9.1. Normative References . . . . . . . . . . . . . . . . . . . 29 9.2. Informative References . . . . . . . . . . . . . . . . . . 29 Appendix A. Example: Ethernet Interface Module . . . . . . . . . 30 Appendix B. Example: Ethernet Bonding Interface Module . . . . . 32 Appendix C. Example: VLAN Interface Module . . . . . . . . . . . 33 - Appendix D. Example: NETCONF reply . . . . . . . . . . . . 34 - Appendix E. Examples: Interface Naming Schemes . . . . . . . . . 37 - E.1. Router with Restricted Interface Names . . . . . . . . . . 37 - E.2. Router with Arbitrary Interface Names . . . . . . . . . . 38 - E.3. Ethernet Switch with Restricted Interface Names . . . . . 39 - E.4. Generic Host with Restricted Interface Names . . . . . . . 39 - E.5. Generic Host with Arbitrary Interface Names . . . . . . . 40 - Appendix F. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 42 - F.1. Version -11 . . . . . . . . . . . . . . . . . . . . . . . 42 - F.2. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 42 - F.3. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 42 - F.4. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 42 - F.5. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 42 - F.6. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 43 - F.7. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 43 - F.8. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 43 - F.9. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 43 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 44 + Appendix D. Example: NETCONF reply . . . . . . . . . . . . 35 + Appendix E. Examples: Interface Naming Schemes . . . . . . . . . 38 + E.1. Router with Restricted Interface Names . . . . . . . . . . 38 + E.2. Router with Arbitrary Interface Names . . . . . . . . . . 39 + E.3. Ethernet Switch with Restricted Interface Names . . . . . 40 + E.4. Generic Host with Restricted Interface Names . . . . . . . 40 + E.5. Generic Host with Arbitrary Interface Names . . . . . . . 41 + Appendix F. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 43 + F.1. Version -13 . . . . . . . . . . . . . . . . . . . . . . . 43 + F.2. Version -11 . . . . . . . . . . . . . . . . . . . . . . . 43 + F.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 43 + F.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 43 + F.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 43 + F.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 44 + F.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 44 + F.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 44 + F.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 44 + F.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 44 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 45 1. Introduction This document defines a YANG [RFC6020] data model for the management of network interfaces. It is expected that interface type specific data models augment the generic interfaces data model defined in this document. Network interfaces are central to the management of many Internet protocols. Thus, it is important to establish a common data model @@ -150,22 +151,22 @@ A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration (read-write) and "ro" state data (read-only). - o Symbols after data node names: "?" means an optional node and "*" - denotes a "list" and "leaf-list". + o Symbols after data node names: "?" means an optional node, "!" + means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. 2. Objectives This section describes some of the design objectives for the model @@ -207,27 +208,27 @@ 3. Interfaces Data Model This document defines the YANG module "ietf-interfaces", which has the following structure: +--rw interfaces | +--rw interface* [name] | +--rw name string | +--rw description? string - | +--rw type ianaift:iana-if-type + | +--rw type identityref | +--rw enabled? boolean | +--rw link-up-down-trap-enable? enumeration +--ro interfaces-state +--ro interface* [name] +--ro name string - +--ro type ianaift:iana-if-type + +--ro type identityref +--ro admin-status enumeration +--ro oper-status enumeration +--ro last-change? yang:date-and-time +--ro if-index int32 +--ro phys-address? yang:phys-address +--ro higher-layer-if* interface-state-ref +--ro lower-layer-if* interface-state-ref +--ro speed? yang:gauge64 +--ro statistics +--ro discontinuity-time yang:date-and-time @@ -244,38 +245,45 @@ +--ro out-multicast-pkts? yang:counter64 +--ro out-discards? yang:counter32 +--ro out-errors? yang:counter32 3.1. The interface Lists The data model for interfaces presented in this document uses a flat list of interfaces. Each interface in the list is identified by its name. Furthermore, each interface has a mandatory "type" leaf. + The "iana-if-type" module [I-D.ietf-netmod-iana-if-type] defines YANG + identities for the interface types in the IANA-maintained "ifType + registry". + There is one list of configured interfaces ("/interfaces/interface"), and a separate list for the operational state of all interfaces ("/interfaces-state/interface"). It is expected that interface type specific data models augment the interface lists, and possibly use the "type" leaf to make the augmentation conditional. As an example of such an interface type specific augmentation, consider this YANG snippet. For a more complete example, see Appendix A. import interfaces { prefix "if"; } + import iana-if-type { + prefix ianaift; + } augment "/if:interfaces/if:interface" { - when "if:type = 'ethernetCsmacd'"; + when "if:type = 'ianaift:ethernetCsmacd'"; container ethernet { leaf duplex { ... } } } For system-controlled interfaces, the "name" is the device-specific name of the interface. The 'config false' list "/interfaces-state/ @@ -313,28 +321,31 @@ interface type specific models define their own data nodes for interface layering, by using "interface-ref" types to reference lower layers. Below is an example of a model with such nodes. For a more complete example, see Appendix B. import interfaces { prefix "if"; } + import iana-if-type { + prefix ianaift; + } augment "/if:interfaces/if:interface" { - when "if:type = 'ieee8023adLag'"; + when "if:type = 'ianaift:ieee8023adLag'"; leaf-list slave-if { type if:interface-ref; must "/if:interfaces/if:interface[if:name = current()]" - + "/if:type = 'ethernetCsmacd'" { + + "/if:type = 'ianaift:ethernetCsmacd'" { description "The type of a slave interface must be ethernet"; } } // other bonding config params, failover times etc. } Two state data leaf-lists, "higher-layer-if" and "lower-layer-if", represent a read-only view of the interface layering hierarchy. @@ -402,39 +413,35 @@ | out-broadcast-pkts | ifHCOutBroadcastPkts | | out-multicast-pkts | ifHCOutMulticastPkts | | out-discards | ifOutDiscards | | out-errors | ifOutErrors | +----------------------------------+------------------------+ YANG data nodes and related IF-MIB objects 5. Interfaces YANG Module - This YANG module imports typedefs from [I-D.ietf-netmod-rfc6021-bis] - and [I-D.ietf-netmod-iana-if-type]. + This YANG module imports typedefs from [RFC6991]. RFC Ed.: update the date below with the date of RFC publication and remove this note. - file "ietf-interfaces@2013-07-04.yang" + file "ietf-interfaces@2013-11-07.yang" module ietf-interfaces { namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces"; prefix if; import ietf-yang-types { prefix yang; } - import iana-if-type { - prefix ianaift; - } organization "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; contact "WG Web: WG List: WG Chair: David Kessens @@ -467,41 +473,55 @@ // RFC Ed.: update the date below with the date of RFC publication // and remove this note. revision 2013-07-04 { description "Initial revision."; reference "RFC XXXX: A YANG Data Model for Interface Management"; } - /* Typedefs */ + /* + * Typedefs + */ typedef interface-ref { type leafref { path "/if:interfaces/if:interface/if:name"; } description "This type is used by data models that need to reference configured interfaces."; } typedef interface-state-ref { type leafref { path "/if:interfaces-state/if:interface/if:name"; } description "This type is used by data models that need to reference the operationally present interfaces."; } - /* Features */ + /* + * Identities + */ + + identity interface-type { + description + "Base identity from which specific interface types are + derived."; + } + + /* + * Features + */ feature arbitrary-names { description "This feature indicates that the device allows user-controlled interfaces to be named arbitrarily."; } feature pre-provisioning { description "This feature indicates that the device supports @@ -510,21 +530,23 @@ hardware is not present on the device."; } feature if-mib { description "This feature indicates that the device implements IF-MIB."; reference "RFC 2863: The Interfaces Group MIB"; } - /* Data nodes */ + /* + * Configuration data nodes + */ container interfaces { description "Interface configuration parameters."; list interface { key "name"; description "The list of configured interfaces on the device. @@ -612,21 +635,23 @@ 'startup'. If the device does not support ':startup', ifAlias MUST be mapped to the 'description' leaf in the 'running' datastore."; reference "RFC 2863: The Interfaces Group MIB - ifAlias"; } leaf type { - type ianaift:iana-if-type; + type identityref { + base interface-type; + } mandatory true; description "The type of the interface. When an interface entry is created, a server MAY initialize the type leaf with a valid value, e.g., if it is possible to derive the type from the name of the interface. If a client tries to set the type of an interface to a @@ -675,20 +700,23 @@ If this node is not configured, the value 'enabled' is operationally used by the server for interfaces which do not operate on top of any other interface (i.e., there are no 'lower-layer-if' entries), and 'disabled' otherwise."; reference "RFC 2863: The Interfaces Group MIB - ifLinkUpDownTrapEnable"; } } } + /* + * Operational state data nodes + */ container interfaces-state { config false; description "Data nodes for the operational state of interfaces."; list interface { key "name"; description @@ -702,21 +730,23 @@ type string; description "The name of the interface. This leaf MAY be mapped to ifName by an implementation."; reference "RFC 2863: The Interfaces Group MIB - ifName"; } leaf type { - type ianaift:iana-if-type; + type identityref { + base interface-type; + } mandatory true; description "The type of the interface."; reference "RFC 2863: The Interfaces Group MIB - ifType"; } leaf admin-status { if-feature if-mib; type enumeration { @@ -1144,45 +1172,43 @@ 8. Acknowledgments The author wishes to thank Alexander Clemm, Per Hedeland, Ladislav Lhotka, and Juergen Schoenwaelder for their helpful comments. 9. References 9.1. Normative References - [I-D.ietf-netmod-iana-if-type] - Bjorklund, M., "IANA Interface Type YANG Module", - draft-ietf-netmod-iana-if-type-07 (work in progress), - July 2013. - - [I-D.ietf-netmod-rfc6021-bis] - Schoenwaelder, J., "Common YANG Data Types", - draft-ietf-netmod-rfc6021-bis-03 (work in progress), - June 2013. - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB", RFC 2863, June 2000. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010. + [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, + July 2013. + 9.2. Informative References + [I-D.ietf-netmod-iana-if-type] + Bjorklund, M., "IANA Interface Type YANG Module", + draft-ietf-netmod-iana-if-type-08 (work in progress), + November 2013. + [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. Bierman, "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, June 2011. @@ -1201,24 +1227,27 @@ interface list. The example is not intended as a complete module for ethernet configuration. module ex-ethernet { namespace "http://example.com/ethernet"; prefix "eth"; import ietf-interfaces { prefix if; } + import iana-if-type { + prefix ianaift; + } // configuration parameters for ethernet interfaces augment "/if:interfaces/if:interface" { - when "if:type = 'ethernetCsmacd'"; + when "if:type = 'ianaift:ethernet'"; container ethernet { choice transmission-params { case auto { leaf auto-negotiate { type empty; } } case manual { leaf duplex { @@ -1264,28 +1293,31 @@ defined. An ethernet bonding interface is defined, which bonds several ethernet interfaces into one logical interface. module ex-ethernet-bonding { namespace "http://example.com/ethernet-bonding"; prefix "bond"; import ietf-interfaces { prefix if; } + import iana-if-type { + prefix ianaift; + } augment "/if:interfaces/if:interface" { - when "if:type = 'ieee8023adLag'"; + when "if:type = 'ianaift:ieee8023adLag'"; leaf-list slave-if { type if:interface-ref; must "/if:interfaces/if:interface[if:name = current()]" - + "/if:type = 'ethernetCsmacd'" { + + "/if:type = 'ianaift:ethernetCsmacd'" { description "The type of a slave interface must be ethernet."; } } leaf bonding-mode { type enumeration { enum round-robin; enum active-backup; enum broadcast; } @@ -1299,32 +1331,38 @@ This section gives an example of how a vlan interface module can be defined. module ex-vlan { namespace "http://example.com/vlan"; prefix "vlan"; import ietf-interfaces { prefix if; } + import iana-if-type { + prefix ianaift; + } + import ex-ethernet { + prefix eth; + } augment "/if:interfaces/if:interface" { - when "if:type = 'ethernetCsmacd' or - if:type = 'ieee8023adLag'"; + when "if:type = 'ianaift:ethernetCsmacd' or + if:type = 'ianaift:ieee8023adLag'"; leaf vlan-tagging { type boolean; default false; } } augment "/if:interfaces/if:interface" { - when "if:type = 'l2vlan'"; + when "if:type = 'ianaift:l2vlan'"; leaf base-interface { type if:interface-ref; must "/if:interfaces/if:interface[if:name = current()]" + "/vlan:vlan-tagging = 'true'" { description "The base interface must have vlan tagging enabled."; } } leaf vlan-id { @@ -1345,119 +1383,121 @@ This section gives an example of a reply to the NETCONF request for a device that implements the example data models above. eth0 - ethernetCsmacd + ianaift:ethernetCsmacd false eth1 - ethernetCsmacd + ianaift:ethernetCsmacd true true eth1.10 - l2vlan + ianaift:l2vlan true eth1 10 lo1 - softwareLoopback + ianaift:softwareLoopback true + xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces" + xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type"> eth0 - ethernetCsmacd + ianaift:ethernetCsmacd down down 2 00:01:02:03:04:05 2013-04-01T03:00:00+00:00 eth1 - ethernetCsmacd + ianaift:ethernetCsmacd up up 7 00:01:02:03:04:06 eth1.10 2013-04-01T03:00:00+00:00 eth1.10 - l2vlan + ianaift:l2vlan up up 9 eth1 2013-04-01T03:00:00+00:00 eth2 - ethernetCsmacd + ianaift:ethernetCsmacd down down 8 00:01:02:03:04:07 2013-04-01T03:00:00+00:00 lo1 - softwareLoopback + ianaift:softwareLoopback up up 1 2013-04-01T03:00:00+00:00 @@ -1494,44 +1534,44 @@ in the message. An operator can configure a physical interface by sending an containing: fastethernet-1/0 When the server processes this request, it will set the leaf "type" - to "ethernetCsmacd". Thus, if the client performs a - right after the above, it will get: + to "ianaift:ethernetCsmacd". Thus, if the client performs a + right after the above, it will get: fastethernet-1/0 - ethernetCsmacd + ianaift:ethernetCsmacd The client can configure a vlan interface by sending an containing: fastethernet-1/0.10005 - l2-vlan + ianaift:l2vlan fastethernet-1/0 5 If the client tries to change the type of the physical interface with an containing: fastethernet-1/0 - tunnel + ianaift:tunnel then the server will reply with an "invalid-value" error, since the new type does not match the name. E.2. Router with Arbitrary Interface Names In this example, a router has support for 4 line cards, each with 8 ports. The slots for the cards are physically numbered from 0 to 3, and the ports on each card from 0 to 7. Each card has fast- or @@ -1549,21 +1589,21 @@ The NETCONF server advertises the 'arbitrary-names' feature in the message. Physical interfaces are configured as in Appendix E.1. An operator can configure a VLAN interface by sending an containing: acme-interface - l2-vlan + ianaift:l2vlan fastethernet-1/0 5 If necessary, the operator can move the configuration named "acme-interface" over to a different physical interface with an containing: acme-interface @@ -1579,26 +1619,26 @@ that match the physical port number. An operator can configure a physical interface by sending an containing: 6 When the server processes this request, it will set the leaf "type" - to "ethernetCsmacd". Thus, if the client performs a - right after the above, it will get: + to "ianaift:ethernetCsmacd". Thus, if the client performs a + right after the above, it will get: 6 - ethernetCsmacd + ianaift:ethernetCsmacd E.4. Generic Host with Restricted Interface Names In this example, a generic host has interfaces named by the kernel. The system identifies the physical interface by the name assigned by the operating system to the interface. The name of a vlan interface is restricted to the form ":". @@ -1607,34 +1647,34 @@ in the message. An operator can configure an interface by sending an containing: eth8 When the server processes this request, it will set the leaf "type" - to "ethernetCsmacd". Thus, if the client performs a - right after the above, it will get: + to "ianaift:ethernetCsmacd". Thus, if the client performs a + right after the above, it will get: eth8 - ethernetCsmacd + ianaift:ethernetCsmacd The client can configure a vlan interface by sending an containing: eth8:5 - l2-vlan + ianaift:l2vlan eth8 5 E.5. Generic Host with Arbitrary Interface Names In this example, a generic host has interfaces named by the kernel. The system identifies the physical interface by the name assigned by the operating system to the interface. @@ -1647,107 +1687,111 @@ The NETCONF server advertises the 'arbitrary-names' feature in the message. Physical interfaces are configured as in Appendix E.4. An operator can configure a VLAN interface by sending an containing: acme-interface - l2-vlan + ianaift:l2vlan eth8 5 If necessary, the operator can move the configuration named "acme-interface" over to a different physical interface with an containing: acme-interface eth3 Appendix F. ChangeLog RFC Editor: remove this section upon publication as an RFC. -F.1. Version -11 +F.1. Version -13 + + o Made the interface type an identity, instead of an enumseration. + +F.2. Version -11 o Separated the operational state from the configuration. o Removed 'location', and instead use the name to identify physical interfaces. o Added the feature 'pre-provisioning'. o Made 'oper-status' and 'if-index' mandatory in the data model. o Added 'admin-status'. o Clarified why description can be mapped to ifAlias. o Clarified that 64-bit counters only are used, where there exist 64-bit and 32-bit counters in IF-MIB. o Updated Security Considerations section with a reference to NACM. -F.2. Version -08 +F.3. Version -08 o Removed the mtu leaf. o Added examples of different interface naming schemes. -F.3. Version -07 +F.4. Version -07 o Made leaf speed config false. -F.4. Version -06 +F.5. Version -06 o Added oper-status leaf. o Added leaf-lists higher-layer-if and lower-layer-if, that show the interface layering. o Added container statistics with counters. -F.5. Version -05 +F.6. Version -05 o Added an Informative References section. o Updated the Security Considerations section. o Clarified the behavior of an NETCONF server when invalid values are received. -F.6. Version -04 +F.7. Version -04 o Clarified why ifPromiscuousMode is not part of this data model. o Added a table that shows the mapping between this YANG data model and IF-MIB. -F.7. Version -03 +F.8. Version -03 o Added the section Relationship to the IF-MIB. o Changed if-index to be a leaf instead of leaf-list. o Explained the notation used in the data model tree picture. -F.8. Version -02 +F.9. Version -02 o Editorial fixes -F.9. Version -01 +F.10. Version -01 o Changed leaf "if-admin-status" to leaf "enabled". o Added Security Considerations Author's Address Martin Bjorklund Tail-f Systems