--- 1/draft-ietf-netmod-interfaces-cfg-07.txt 2012-11-15 14:14:24.277425323 +0100 +++ 2/draft-ietf-netmod-interfaces-cfg-08.txt 2012-11-15 14:14:24.341425727 +0100 @@ -1,18 +1,18 @@ Network Working Group M. Bjorklund Internet-Draft Tail-f Systems -Intended status: Standards Track October 22, 2012 -Expires: April 25, 2013 +Intended status: Standards Track November 15, 2012 +Expires: May 19, 2013 A YANG Data Model for Interface Management - draft-ietf-netmod-interfaces-cfg-07 + draft-ietf-netmod-interfaces-cfg-08 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. Status of this Memo This Internet-Draft is submitted in full conformance with the @@ -21,21 +21,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 April 25, 2013. + This Internet-Draft will expire on May 19, 2013. Copyright Notice Copyright (c) 2012 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 @@ -59,29 +59,36 @@ 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 9.1. Normative References . . . . . . . . . . . . . . . . . . . 26 9.2. Informative References . . . . . . . . . . . . . . . . . . 26 Appendix A. Example: Ethernet Interface Module . . . . . . . . . 27 Appendix B. Example: Ethernet Bonding Interface Module . . . . . 29 Appendix C. Example: VLAN Interface Module . . . . . . . . . . . 30 Appendix D. Example: NETCONF reply . . . . . . . . . . . . 31 - Appendix E. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 32 - E.1. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 32 - E.2. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 32 - E.3. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 32 - E.4. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 32 - E.5. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 32 - E.6. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 32 - E.7. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 33 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 34 + Appendix E. Examples: Interface Naming Schemes . . . . . . . . . 32 + E.1. Router with Restricted Interface Names . . . . . . . . . . 32 + E.2. Router with Arbitrary Interface Names . . . . . . . . . . 33 + E.3. Ethernet Switch with Restricted Interface Names . . . . . 33 + E.4. Generic Host with Restricted Interface Names . . . . . . . 34 + E.5. Generic Host with Arbitrary Interface Names . . . . . . . 35 + Appendix F. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 36 + F.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 36 + F.2. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 36 + F.3. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 36 + F.4. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 36 + F.5. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 36 + F.6. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 36 + F.7. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 37 + F.8. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 37 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 38 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 @@ -151,21 +158,20 @@ +--rw interfaces +--rw interface [name] +--rw name string +--rw description? string +--rw type ianaift:iana-if-type +--rw location? string +--rw enabled? boolean +--ro oper-status? enumeration +--ro last-change? yang:date-and-time +--ro if-index? int32 - +--rw mtu? uint32 +--rw link-up-down-trap-enable? enumeration +--ro phys-address? yang:phys-address +--ro higher-layer-if* interface-ref +--ro lower-layer-if* interface-ref +--ro speed? yang:gauge64 +--ro statistics +--ro discontinuity-time? yang:date-and-time +--ro in-octets? yang:counter64 +--ro in-unicast-pkts? yang:counter64 +--ro in-broadcast-pkts? yang:counter64 @@ -173,24 +179,20 @@ +--ro in-discards? yang:counter32 +--ro in-errors? yang:counter32 +--ro in-unknown-protos? yang:counter32 +--ro out-octets? yang:counter64 +--ro out-unicast-pkts? yang:counter64 +--ro out-broadcast-pkts? yang:counter64 +--ro out-multicast-pkts? yang:counter64 +--ro out-discards? yang:counter32 +--ro out-errors? yang:counter32 - This module defines one YANG feature: - - if-mib: Indicates that the server implements IF-MIB [RFC2863]. - 3.1. The interface List 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, and a "location" leaf. The combination of "type" and "location" is unique within the interface list. It is expected that interface type specific data models augment the interface list, and use the "type" leaf to make the augmentation @@ -237,20 +239,24 @@ There is no generic mechanism for how an interface is configured to be layered on top of some other interface. It is expected that 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"; + } + augment "/if:interfaces/if:interface" { when "if:type = 'ieee8023adLag'"; leaf-list slave-if { type if:interface-ref; must "/if:interfaces/if:interface[if:name = current()]" + "/if:type = 'ethernetCsmacd'" { description "The type of a slave interface must be ethernet"; } @@ -289,21 +295,20 @@ | YANG data node | IF-MIB object | +----------------------------------+------------------------+ | interface | ifEntry | | name | ifName | | description | ifAlias | | type | ifType | | enabled | ifAdminStatus | | oper-status | ifOperStatus | | last-change | ifLastChange | | if-index | ifIndex | - | mtu | ifMtu | | link-up-down-trap-enable | ifLinkUpDownTrapEnable | | phys-address | ifPhysAddress | | higher-layer-if / lower-layer-if | ifStackTable | | speed | ifSpeed | | in-octets | ifHCInOctets | | in-unicast-pkts | ifHCInUcastPkts | | in-broadcast-pkts | ifHCInBroadcastPkts | | in-multicast-pkts | ifHCInMulticastPkts | | in-discards | ifInDiscards | | in-errors | ifInErrors | @@ -319,21 +324,21 @@ Mapping of YANG data nodes to IF-MIB objects 5. Interfaces YANG Module This YANG module imports a typedef from [I-D.ietf-netmod-iana-if-type]. RFC Ed.: update the date below with the date of RFC publication and remove this note. - file "ietf-interfaces@2012-10-22.yang" + file "ietf-interfaces@2012-11-15.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 { @@ -371,40 +376,46 @@ (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; // RFC Ed.: replace XXXX with actual RFC number and remove this // note. // RFC Ed.: update the date below with the date of RFC publication // and remove this note. - revision 2012-10-22 { + revision 2012-11-15 { description "Initial revision."; reference "RFC XXXX: A YANG Data Model for Interface Management"; } /* 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 interfaces."; } /* Features */ + feature arbitrary-names { + description + "This feature indicates that the server allows interfaces to + be named arbitrarily."; + } + feature if-mib { description "This feature indicates that the server implements IF-MIB."; reference "RFC 2863: The Interfaces Group MIB"; } /* Data nodes */ container interfaces { @@ -407,34 +418,34 @@ /* Data nodes */ container interfaces { description "Interface parameters."; list interface { key "name"; unique "type location"; + description "The list of interfaces on the device."; leaf name { type string; description - "An arbitrary name for the interface. + "The name of the interface. A device MAY restrict the allowed values for this leaf, possibly depending on the type and location. - For example, if a device has a single array of 8 ethernet - ports, the name might be restricted to be on the form - 'ethN', where N is an integer between '1' and '8'. + If the device allows arbitrarily named interfaces, the + feature 'arbitrary-names' is advertised. This leaf MAY be mapped to ifName by an implementation. Such an implementation MAY restrict the allowed values for this leaf so that it matches the restrictions of ifName. If a NETCONF server that implements this restriction is sent a value that doesn't match the restriction, it MUST reply with an rpc-error with the error-tag 'invalid-value'."; reference "RFC 2863: The Interfaces Group MIB - ifName"; @@ -473,25 +483,20 @@ leaf location { type string; description "The device-specific location of the interface of a particular type. The format of the location string depends on the interface type and the device. If the interface's type represents a physical interface, this leaf MUST be set. - For example, if a device has a single array of 8 ethernet - ports, the location can be one of '1' to '8'. As another - example, if a device has N cards of M ports, the location - can be on the form 'n/m'. - When an interface entry is created, a server MAY initialize the location leaf with a valid value, e.g., if it is possible to derive the location from the name of the interface."; } leaf enabled { type boolean; default "true"; description @@ -508,46 +513,48 @@ leaf oper-status { type enumeration { enum up { value 1; description "Ready to pass packets."; } enum down { value 2; + description + "The interface does not pass any packets."; } enum testing { value 3; description "In some test mode. No operational packets can be passed."; } enum unknown { value 4; description - "Status can not be determined - for some reason."; + "Status cannot be determined for some reason."; } enum dormant { value 5; + description + "Waiting for some external event."; } enum not-present { value 6; description "Some component is missing."; } enum lower-layer-down { value 7; description - "Down due to state of lower-layer - interface(s)."; + "Down due to state of lower-layer interface(s)."; } } config false; description "The current operational state of the interface. If 'enabled' is 'false' then 'oper-status' should be 'down'. If 'enabled' is changed to 'true' then 'oper-status' should change to 'up' if the interface is ready to transmit and receive network traffic; it @@ -584,33 +590,20 @@ description "The ifIndex value for the ifEntry represented by this interface. Media-specific modules must specify how the type is mapped to entries in the ifTable."; reference "RFC 2863: The Interfaces Group MIB - ifIndex"; } - leaf mtu { - type uint32; - description - "The size, in octets, of the largest packet that the - interface can send and receive. This node might not be - valid for all interface types. - - Media-specific modules must specify any restrictions on - the mtu for their interface type."; - reference - "RFC 2863: The Interfaces Group MIB - ifMtu"; - } - leaf link-up-down-trap-enable { if-feature if-mib; type enumeration { enum enabled { value 1; } enum disabled { value 2; } } @@ -657,22 +650,22 @@ config false; description "A list of references to interfaces layered underneath this interface."; reference "RFC 2863: The Interfaces Group MIB - ifStackTable"; } leaf speed { type yang:gauge64; - config false; units "bits / second"; + config false; description "An estimate of the interface's current bandwidth in bits per second. For interfaces which do not vary in bandwidth or for those where no accurate estimation can be made, this node should contain the nominal bandwidth. For interfaces that has no concept of bandwidth, this node is not present."; reference "RFC 2863: The Interfaces Group MIB - ifSpeed, ifHighSpeed"; @@ -946,23 +936,20 @@ and their sensitivity/vulnerability: /interfaces/interface: This list specifies the configured interfaces on a device. Unauthorized access to this list could cause the device to ignore packets it should receive and process. /interfaces/interface/enabled: This leaf controls if an interface is enabled or not. Unauthorized access to this leaf could cause the device to ignore packets it should receive and process. - /interfaces/interface/mtu: Setting this leaf to a very small value - can be used to slow down interfaces. - 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] @@ -1155,66 +1142,258 @@ 1 true 7 true -Appendix E. ChangeLog +Appendix E. Examples: Interface Naming Schemes + + This section gives examples of some implementation strategies. + +E.1. Router with Restricted 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 + gigabit-ethernet ports. + + The implementation restricts the names of the interfaces to one of + "fastethernet-N/M" or "gigabitethernet-N/M". The "location" of an + interface is a string on the form "N/M". The implementation auto- + initializes the values for "type" and "location" based on the + interface name. + + An operator can configure a new interface by sending an + containing: + + + fastethernet-1/0 + + + When the server processes this request, it will set the leaf "type" + to "ethernetCsmacd" and "location" to "1/0". Thus, if the client + performs a right after the above, it will + get: + + + fastethernet-1/0 + ethernetCsmacd + 1/0 + + + If the client tries to change the location of this interface with an + containing: + + + fastethernet-1/0 + 1/1 + + + then the server will reply with an "invalid-value" error, since the + new location 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 + gigabit-ethernet ports. + + The implementation does not restrict the interface names. This + allows to more easily apply the interface configuration to a + different physical interface. However, the additional level of + indirection also makes it a bit more complex to map interface names + found in other protocols to configuration entries. The "location" of + an interface is a string on the form "N/M". + + An operator can configure a new interface by sending an + containing: + + + acme-interface + ethernetCsmacd + 1/0 + + + If necessary, the operator can move the configuration named + "acme-interface" over to a different physical interface with an + containing: + + + acme-interface + 2/4 + + +E.3. Ethernet Switch with Restricted Interface Names + + In this example, an ethernet switch has a number of ports, each port + identified by a simple port number. + + The implementation restricts the interface names to numbers that + match the physical port number. + + An operator can configure a new interface by sending an + containing: + + + 6 + + + When the server processes this request, it will set the leaf "type" + to "ethernetCsmacd" and "location" to "6". Thus, if the client + performs a right after the above, it will + get: + + + 6 + ethernetCsmacd + 6 + + + If the client tries to change the location of this interface with an + containing: + + + 6 + 5 + + + then the server will reply with an "invalid-value" error, since the + new location does not match the name. + +E.4. Generic Host with Restricted Interface Names + + In this example, a generic host has interfaces named by the kernel + and without easily usable location information. The system + identifies the physical interface by the name assigned by the + operating system to the interface. + + The implementation restricts the interface name to the operating + system level name of the physical interface. + + An operator can configure a new interface by sending an + containing: + + + eth8 + + + When the server processes this request, it will set the leaf "type" + to "ethernetCsmacd" and "location" to "eth8". Thus, if the client + performs a right after the above, it will + get: + + + eth8 + ethernetCsmacd + eth8 + + + If the client tries to change the location of this interface with an + containing: + + + eth8 + eth7 + + + then the server will reply with an "invalid-value" error, since the + new location does not match the name. + +E.5. Generic Host with Arbitrary Interface Names + + In this example, a generic host has interfaces named by the kernel + and without easily usable location information. The system + identifies the physical interface by the name assigned by the + operating system to the interface. + + The implementation does not restrict the interface name to the + operating system level name of the physical interface. This allows + to more easily apply the interface configuration to a different + physical interface. However, the additional level of indirection + also makes it a bit more complex to map interface names found in + other protocols to configuration entries. + + An operator can configure a new interface by sending an + containing: + + + acme-interface + ethernetCsmacd + eth4 + + + 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. -E.1. Version -07 +F.1. Version -08 + + o Removed the mtu leaf. + + o Added examples of different interface naming schemes. + +F.2. Version -07 o Made leaf speed config false. -E.2. Version -06 +F.3. 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. -E.3. Version -05 +F.4. 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. -E.4. Version -04 +F.5. 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. -E.5. Version -03 +F.6. 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. -E.6. Version -02 +F.7. Version -02 o Editorial fixes -E.7. Version -01 +F.8. Version -01 o Changed leaf "if-admin-status" to leaf "enabled". o Added Security Considerations Author's Address Martin Bjorklund Tail-f Systems