A YANG Data Model for Interface Management
draft-ietf-netmod-interfaces-cfg-07
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 7223.
|
|
|---|---|---|---|
| Author | Martin Björklund | ||
| Last updated | 2012-10-22 | ||
| Replaces | draft-bjorklund-netmod-interfaces-cfg | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Document shepherd | Jürgen Schönwälder | ||
| IESG | IESG state | Became RFC 7223 (Proposed Standard) | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-netmod-interfaces-cfg-07
Internet-Draft YANG Interface Management October 2012 description "Ready to pass packets."; } enum down { value 2; } 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."; } enum dormant { value 5; } 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)."; } } 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 should change to 'dormant' if the interface is waiting for external actions (such as a serial line waiting for an incoming connection); it should remain in the 'down' state if and only if there is a fault that prevents it from going to the 'up' state; it should remain in the 'not-present' state if the interface has missing (typically, hardware) components."; Bjorklund Expires April 25, 2013 [Page 14] Internet-Draft YANG Interface Management October 2012 reference "RFC 2863: The Interfaces Group MIB - ifOperStatus"; } leaf last-change { type yang:date-and-time; config false; description "The time the interface entered its current operational state. If the current state was entered prior to the last re-initialization of the local network management subsystem, then this node is not present."; reference "RFC 2863: The Interfaces Group MIB - ifLastChange"; } leaf if-index { if-feature if-mib; type int32 { range "1..2147483647"; } config false; 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 { Bjorklund Expires April 25, 2013 [Page 15] Internet-Draft YANG Interface Management October 2012 enum enabled { value 1; } enum disabled { value 2; } } description "Indicates whether linkUp/linkDown SNMP notifications should be generated for this interface. 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"; } leaf phys-address { type yang:phys-address; config false; description "The interface's address at its protocol sub-layer. For example, for an 802.x interface, this object normally contains a MAC address. The interface's media-specific modules must define the bit and byte ordering and the format of the value of this object. For interfaces that do not have such an address (e.g., a serial line), this node is not present."; reference "RFC 2863: The Interfaces Group MIB - ifPhysAddress"; } leaf-list higher-layer-if { type interface-ref; config false; description "A list of references to interfaces layered on top of this interface."; reference "RFC 2863: The Interfaces Group MIB - ifStackTable"; } leaf-list lower-layer-if { type interface-ref; config false; Bjorklund Expires April 25, 2013 [Page 16] Internet-Draft YANG Interface Management October 2012 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"; 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"; } container statistics { config false; description "A collection of interface-related statistics objects."; leaf discontinuity-time { type yang:date-and-time; description "The time on the most recent occasion at which any one or more of this interface's counters suffered a discontinuity. If no such discontinuities have occurred since the last re-initialization of the local management subsystem, then this node contains the time the local management subsystem re-initialized itself."; } leaf in-octets { type yang:counter64; description "The total number of octets received on the interface, including framing characters. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of Bjorklund Expires April 25, 2013 [Page 17] Internet-Draft YANG Interface Management October 2012 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifHCInOctets"; } leaf in-unicast-pkts { type yang:counter64; description "The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were not addressed to a multicast or broadcast address at this sub-layer. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifHCInUcastPkts"; } leaf in-broadcast-pkts { type yang:counter64; description "The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were addressed to a broadcast address at this sub-layer. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifHCInBroadcastPkts"; } leaf in-multicast-pkts { type yang:counter64; description "The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were addressed to a multicast address at this sub-layer. For a MAC layer protocol, this includes both Group and Functional addresses. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifHCInMulticastPkts"; Bjorklund Expires April 25, 2013 [Page 18] Internet-Draft YANG Interface Management October 2012 } leaf in-discards { type yang:counter32; description "The number of inbound packets which were chosen to be discarded even though no errors had been detected to prevent their being deliverable to a higher-layer protocol. One possible reason for discarding such a packet could be to free up buffer space. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifInDiscards"; } leaf in-errors { type yang:counter32; description "For packet-oriented interfaces, the number of inbound packets that contained errors preventing them from being deliverable to a higher-layer protocol. For character- oriented or fixed-length interfaces, the number of inbound transmission units that contained errors preventing them from being deliverable to a higher-layer protocol. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifInErrors"; } leaf in-unknown-protos { type yang:counter32; description "For packet-oriented interfaces, the number of packets received via the interface which were discarded because of an unknown or unsupported protocol. For character-oriented or fixed-length interfaces that support protocol multiplexing the number of transmission units received via the interface which were discarded because of an unknown or unsupported protocol. For any interface that does not support protocol multiplexing, this counter is not present. Bjorklund Expires April 25, 2013 [Page 19] Internet-Draft YANG Interface Management October 2012 Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifInUnknownProtos"; } leaf out-octets { type yang:counter64; description "The total number of octets transmitted out of the interface, including framing characters. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifHCOutOctets"; } leaf out-unicast-pkts { type yang:counter64; description "The total number of packets that higher-level protocols requested be transmitted, and which were not addressed to a multicast or broadcast address at this sub-layer, including those that were discarded or not sent. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifHCOutUcastPkts"; } leaf out-broadcast-pkts { type yang:counter64; description "The total number of packets that higher-level protocols requested be transmitted, and which were addressed to a broadcast address at this sub-layer, including those that were discarded or not sent. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; Bjorklund Expires April 25, 2013 [Page 20] Internet-Draft YANG Interface Management October 2012 reference "RFC 2863: The Interfaces Group MIB - ifHCOutBroadcastPkts"; } leaf out-multicast-pkts { type yang:counter64; description "The total number of packets that higher-level protocols requested be transmitted, and which were addressed to a multicast address at this sub-layer, including those that were discarded or not sent. For a MAC layer protocol, this includes both Group and Functional addresses. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifHCOutMulticastPkts"; } leaf out-discards { type yang:counter32; description "The number of outbound packets which were chosen to be discarded even though no errors had been detected to prevent their being transmitted. One possible reason for discarding such a packet could be to free up buffer space. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifOutDiscards"; } leaf out-errors { type yang:counter32; description "For packet-oriented interfaces, the number of outbound packets that could not be transmitted because of errors. For character-oriented or fixed-length interfaces, the number of outbound transmission units that could not be transmitted because of errors. Discontinuities in the value of this counter can occur Bjorklund Expires April 25, 2013 [Page 21] Internet-Draft YANG Interface Management October 2012 at re-initialization of the management system, and at other times as indicated by the value of 'discontinuity-time'."; reference "RFC 2863: The Interfaces Group MIB - ifOutErrors"; } } } } } <CODE ENDS> Bjorklund Expires April 25, 2013 [Page 22] Internet-Draft YANG Interface Management October 2012 6. IANA Considerations This document registers a URI in the IETF XML registry [RFC3688]. Following the format in RFC 3688, the following registration is requested to be made. URI: urn:ietf:params:xml:ns:yang:ietf-interfaces Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. This document registers a YANG module in the YANG Module Names registry [RFC6020]. name: ietf-interfaces namespace: urn:ietf:params:xml:ns:yang:ietf-interfaces prefix: if reference: RFC XXXX Bjorklund Expires April 25, 2013 [Page 23] Internet-Draft YANG Interface Management October 2012 7. Security Considerations The YANG module defined in this memo is designed to be accessed via the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the secure transport layer and the mandatory-to-implement secure transport is SSH [RFC6242]. There are a number of data nodes defined in the YANG module which are writable/creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., <edit-config>) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes 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. Bjorklund Expires April 25, 2013 [Page 24] Internet-Draft YANG Interface Management October 2012 8. Acknowledgments The author wishes to thank Alexander Clemm, Per Hedeland, Ladislav Lhotka, and Juergen Schoenwaelder for their helpful comments. Bjorklund Expires April 25, 2013 [Page 25] Internet-Draft YANG Interface Management October 2012 9. References 9.1. Normative References [I-D.ietf-netmod-iana-if-type] Bjorklund, M., "IANA Interface Type and Address Family YANG Modules", draft-ietf-netmod-iana-if-type-02 (work in progress), April 2012. [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. 9.2. Informative References [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. Bjorklund Expires April 25, 2013 [Page 26] Internet-Draft YANG Interface Management October 2012 Appendix A. Example: Ethernet Interface Module This section gives a simple example of how an Ethernet interface module could be defined. It demonstrates how media-specific configuration parameters can be conditionally augmented to the generic interface list. It is not intended as a complete module for ethernet configuration. Bjorklund Expires April 25, 2013 [Page 27] Internet-Draft YANG Interface Management October 2012 module ex-ethernet { namespace "http://example.com/ethernet"; prefix "eth"; import ietf-interfaces { prefix if; } augment "/if:interfaces/if:interface" { when "if:type = 'ethernetCsmacd'"; container ethernet { must "../if:location" { description "An ethernet interface must specify the physical location of the ethernet hardware."; } choice transmission-params { case auto { leaf auto-negotiate { type empty; } } case manual { leaf duplex { type enumeration { enum "half"; enum "full"; } } leaf speed { type enumeration { enum "10Mb"; enum "100Mb"; enum "1Gb"; enum "10Gb"; } } } } // other ethernet specific params... } } } Bjorklund Expires April 25, 2013 [Page 28] Internet-Draft YANG Interface Management October 2012 Appendix B. Example: Ethernet Bonding Interface Module This section gives an example of how interface layering can be 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; } 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."; } } leaf bonding-mode { type enumeration { enum round-robin; enum active-backup; enum broadcast; } } // other bonding config params, failover times etc. } } Bjorklund Expires April 25, 2013 [Page 29] Internet-Draft YANG Interface Management October 2012 Appendix C. Example: VLAN Interface Module 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; } augment "/if:interfaces/if:interface" { when "if:type = 'ethernetCsmacd' or if:type = 'ieee8023adLag'"; leaf vlan-tagging { type boolean; default false; } } augment "/if:interfaces/if:interface" { when "if:type = '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 { type uint16 { range "1..4094"; } must "../base-interface" { description "If a vlan-id is defined, a base-interface must be specified."; } } } } Bjorklund Expires April 25, 2013 [Page 30] Internet-Draft YANG Interface Management October 2012 Appendix D. Example: NETCONF <get> reply This section gives an example of a reply to the NETCONF <get> request for a device that implements the example data models above. <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101"> <data> <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"> <interface> <name>eth0</name> <type>ethernetCsmacd</type> <location>0</location> <enabled>true</enabled> <if-index>2</if-index> </interface> <interface> <name>eth1</name> <type>ethernetCsmacd</type> <location>1</location> <enabled>true</enabled> <if-index>7</if-index> <vlan-tagging xmlns="http://example.com/vlan">true</vlan-tagging> </interface> </interfaces> </data> </rpc-reply> Bjorklund Expires April 25, 2013 [Page 31] Internet-Draft YANG Interface Management October 2012 Appendix E. ChangeLog RFC Editor: remove this section upon publication as an RFC. E.1. Version -07 o Made leaf speed config false. E.2. 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 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 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 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 o Editorial fixes Bjorklund Expires April 25, 2013 [Page 32] Internet-Draft YANG Interface Management October 2012 E.7. Version -01 o Changed leaf "if-admin-status" to leaf "enabled". o Added Security Considerations Bjorklund Expires April 25, 2013 [Page 33] Internet-Draft YANG Interface Management October 2012 Author's Address Martin Bjorklund Tail-f Systems Email: mbj@tail-f.com Bjorklund Expires April 25, 2013 [Page 34]