summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc7223.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc7223.txt')
-rw-r--r--doc/rfc/rfc7223.txt2187
1 files changed, 2187 insertions, 0 deletions
diff --git a/doc/rfc/rfc7223.txt b/doc/rfc/rfc7223.txt
new file mode 100644
index 0000000..0056987
--- /dev/null
+++ b/doc/rfc/rfc7223.txt
@@ -0,0 +1,2187 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) M. Bjorklund
+Request for Comments: 7223 Tail-f Systems
+Category: Standards Track May 2014
+ISSN: 2070-1721
+
+
+ A YANG Data Model for Interface Management
+
+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 and state data (status
+ information and counters for the collection of statistics).
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7223.
+
+Copyright Notice
+
+ Copyright (c) 2014 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
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 1]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+Table of Contents
+
+ 1. Introduction ....................................................2
+ 1.1. Terminology ................................................3
+ 1.2. Tree Diagrams ..............................................4
+ 2. Objectives ......................................................4
+ 3. Interfaces Data Model ...........................................5
+ 3.1. The Interface Lists ........................................6
+ 3.2. Interface References .......................................7
+ 3.3. Interface Layering .........................................7
+ 4. Relationship to the IF-MIB ......................................8
+ 5. Interfaces YANG Module .........................................11
+ 6. IANA Considerations ............................................26
+ 7. Security Considerations ........................................26
+ 8. Acknowledgments ................................................27
+ 9. References .....................................................27
+ 9.1. Normative References ......................................27
+ 9.2. Informative References ....................................28
+ Appendix A. Example: Ethernet Interface Module ....................29
+ Appendix B. Example: Ethernet Bonding Interface Module ............30
+ Appendix C. Example: VLAN Interface Module ........................31
+ Appendix D. Example: NETCONF <get> Reply ..........................32
+ Appendix E. Examples: Interface Naming Schemes ....................35
+ E.1. Router with Restricted Interface Names .....................35
+ E.2. Router with Arbitrary Interface Names ......................36
+ E.3. Ethernet Switch with Restricted Interface Names ............37
+ E.4. Generic Host with Restricted Interface Names ...............38
+ E.5. Generic Host with Arbitrary Interface Names ................39
+
+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
+ for how interfaces are identified, configured, and monitored.
+
+ The data model includes configuration data and state data (status
+ information and counters for the collection of statistics).
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 2]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+1.1. Terminology
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ BCP 14 [RFC2119].
+
+ The following terms are used within this document:
+
+ o system-controlled interface: An interface is said to be system-
+ controlled if the system creates and deletes the interface
+ independently of what has been explicitly configured. Examples
+ are interfaces representing physical hardware that appear and
+ disappear when hardware (e.g., a line card or hot-pluggable
+ wireless interface) is added or removed. System-controlled
+ interfaces may also appear if a certain functionality is enabled
+ (e.g., a loopback interface might appear if the IP protocol stack
+ is enabled).
+
+ o user-controlled interface: An interface is said to be user-
+ controlled if the creation of the interface is controlled by
+ adding explicit interface configuration to the running
+ configuration datastore and the removal of the interface is
+ controlled by removing explicit interface configuration from the
+ running configuration datastore. Examples are VLAN interfaces
+ configured on a system-controlled Ethernet interface.
+
+ The following terms are defined in [RFC6241] and are not redefined
+ here:
+
+ o client
+
+ o configuration data
+
+ o server
+
+ o state data
+
+ The following terms are defined in [RFC6020] and are not redefined
+ here:
+
+ o augment
+
+ o data model
+
+ o data node
+
+ o presence container
+
+
+
+Bjorklund Standards Track [Page 3]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+1.2. Tree Diagrams
+
+ 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" means state data (read-only).
+
+ 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
+ presented in Section 5.
+
+ o It is recognized that existing implementations will have to map
+ the interface data model defined in this memo to their proprietary
+ native data model. To facilitate such mappings, the data model
+ should be simple.
+
+ o The data model should be suitable for new implementations to use
+ as is, without requiring a mapping to a different native model.
+
+ o References to interfaces should be as simple as possible,
+ preferably by using a single leafref.
+
+ o The mapping to ifIndex [RFC2863] used by the Simple Network
+ Management Protocol (SNMP) to identify interfaces must be clear.
+
+ o The model must support interface layering: both (1) simple
+ layering, where one interface is layered on top of exactly one
+ other interface, and (2) more complex scenarios, where one
+ interface results from the aggregation of N other interfaces or
+ when N interfaces are multiplexed over one other interface.
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 4]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ o The data model should support the pre-provisioning of interface
+ configuration, i.e., it should be possible to configure an
+ interface whose physical interface hardware is not present on the
+ device. It is recommended that devices that support dynamic
+ addition and removal of physical interfaces also support
+ pre-provisioning.
+
+ o The data model should support physical interfaces as well as
+ logical interfaces.
+
+ o The data model should include read-only counters in order to
+ gather statistics for sent and received octets and packets,
+ received packets with errors, and packets that could not be sent
+ due to errors.
+
+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 identityref
+ | +--rw enabled? boolean
+ | +--rw link-up-down-trap-enable? enumeration
+ +--ro interfaces-state
+ +--ro interface* [name]
+ +--ro name string
+ +--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
+ +--ro in-octets? yang:counter64
+ +--ro in-unicast-pkts? yang:counter64
+ +--ro in-broadcast-pkts? yang:counter64
+ +--ro in-multicast-pkts? yang:counter64
+ +--ro in-discards? yang:counter32
+ +--ro in-errors? yang:counter32
+ +--ro in-unknown-protos? yang:counter32
+
+
+
+Bjorklund Standards Track [Page 5]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ +--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
+
+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 [RFC7224] defines YANG identities for the
+ interface types in the IANA-maintained "ifType definitions" 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 = 'ianaift:ethernetCsmacd'";
+
+ container ethernet {
+ leaf duplex {
+ ...
+ }
+ }
+ }
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 6]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ For system-controlled interfaces, the "name" is the device-specific
+ name of the interface. The 'config false' list
+ "/interfaces-state/interface" contains all existing interfaces on the
+ device.
+
+ If the device supports arbitrarily named user-controlled interfaces,
+ the Network Configuration Protocol (NETCONF) server advertises the
+ "arbitrary-names" feature. If the device does not advertise this
+ feature, the names of user-controlled interfaces MUST match the
+ device's naming scheme. How a client can learn the naming scheme of
+ such devices is outside the scope of this document. See Appendices
+ E.1 and E.2 for examples.
+
+ When a system-controlled interface is created by the system, the
+ system tries to apply the interface configuration in "/interfaces/
+ interface" with the same name as the new interface. If no such
+ interface configuration is found, or if the configured type does not
+ match the real interface type, the system creates the interface
+ without applying explicit configuration.
+
+ When a user-controlled interface is created, the configuration
+ determines the name of the interface.
+
+ Depending on the operating system and the physical attachment point
+ to which a network interface may be attached or removed, it may be
+ impossible for an implementation to provide predictable and
+ consistent names for system-controlled interfaces across insertion/
+ removal cycles as well as in anticipation of initial insertion. The
+ ability to provide configurations for such interfaces is therefore
+ dependent on the implementation and cannot be assumed in all cases.
+
+3.2. Interface References
+
+ An interface is identified by its name, which is unique within the
+ server. This property is captured in the "interface-ref" and
+ "interface-state-ref" typedefs, which other YANG modules SHOULD use
+ when they need to reference a configured interface or operationally
+ used interface, respectively.
+
+3.3. Interface Layering
+
+ 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.
+
+
+
+
+
+Bjorklund Standards Track [Page 7]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ 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 = 'ianaift:ieee8023adLag'";
+
+ leaf-list slave-if {
+ type if:interface-ref;
+ must "/if:interfaces/if:interface[if:name = current()]"
+ + "/if:type = 'ianaift:ethernetCsmacd'" {
+ description
+ "The type of a slave interface must be
+ 'ethernetCsmacd'.";
+ }
+ }
+ // other bonding config params, failover times, etc.
+ }
+
+ While the interface layering is configured in interface-type-specific
+ models, two generic state data leaf-lists, "higher-layer-if" and
+ "lower-layer-if", represent a read-only view of the interface
+ layering hierarchy.
+
+4. Relationship to the IF-MIB
+
+ If the device implements the IF-MIB [RFC2863], each entry in the "/
+ interfaces-state/interface" list is typically mapped to one ifEntry.
+ The "if-index" leaf MUST contain the value of the corresponding
+ ifEntry's ifIndex.
+
+ In most cases, the "name" of an "/interfaces-state/interface" entry
+ is mapped to ifName. The IF-MIB allows two different ifEntries to
+ have the same ifName. Devices that support this feature and also
+ support the data model defined in this document cannot have a 1-1
+ mapping between the "name" leaf and ifName.
+
+ The configured "description" of an "interface" has traditionally been
+ mapped to ifAlias in some implementations. This document allows this
+ mapping, but implementers should be aware of the differences in the
+ value space and persistence for these objects. See the YANG module
+ definition of the leaf "description" in Section 5 for details.
+
+
+
+Bjorklund Standards Track [Page 8]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ The IF-MIB also defines the writable object ifPromiscuousMode. Since
+ this object typically is not implemented as a configuration object by
+ SNMP agents, it is not mapped to the "ietf-interfaces" module.
+
+ The ifMtu object from the IF-MIB is not mapped to the
+ "ietf-interfaces" module. It is expected that interface-type-
+ specific YANG modules provide interface-type-specific MTU leafs by
+ augmenting the "ietf-interfaces" model.
+
+ There are a number of counters in the IF-MIB that exist in two
+ versions: one with 32 bits and one with 64 bits. The 64-bit versions
+ were added to support high-speed interfaces with a data rate greater
+ than 20,000,000 bits/second. Today's implementations generally
+ support such high-speed interfaces, and hence only 64-bit counters
+ are provided in this data model. Note that NETCONF and SNMP may
+ differ in the time granularity in which they provide access to the
+ counters. For example, it is common that SNMP implementations cache
+ counter values for some time.
+
+ The objects ifDescr and ifConnectorPresent from the IF-MIB are not
+ mapped to the "ietf-interfaces" module.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 9]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ The following tables list the YANG data nodes with corresponding
+ objects in the IF-MIB.
+
+ +--------------------------------------+----------------------------+
+ | YANG data node in /interfaces- | IF-MIB object |
+ | state/interface | |
+ +--------------------------------------+----------------------------+
+ | name | ifName |
+ | type | ifType |
+ | admin-status | ifAdminStatus |
+ | oper-status | ifOperStatus |
+ | last-change | ifLastChange |
+ | if-index | ifIndex |
+ | link-up-down-trap-enable | ifLinkUpDownTrapEnable |
+ | phys-address | ifPhysAddress |
+ | higher-layer-if and lower-layer-if | ifStackTable |
+ | speed | ifSpeed and ifHighSpeed |
+ | discontinuity-time | ifCounterDiscontinuityTime |
+ | in-octets | ifHCInOctets |
+ | in-unicast-pkts | ifHCInUcastPkts |
+ | in-broadcast-pkts | ifHCInBroadcastPkts |
+ | in-multicast-pkts | ifHCInMulticastPkts |
+ | in-discards | ifInDiscards |
+ | in-errors | ifInErrors |
+ | in-unknown-protos | ifInUnknownProtos |
+ | out-octets | ifHCOutOctets |
+ | out-unicast-pkts | ifHCOutUcastPkts |
+ | out-broadcast-pkts | ifHCOutBroadcastPkts |
+ | out-multicast-pkts | ifHCOutMulticastPkts |
+ | out-discards | ifOutDiscards |
+ | out-errors | ifOutErrors |
+ +--------------------------------------+----------------------------+
+
+ YANG State Data Nodes and Related IF-MIB Objects
+
+ +-----------------------------------------+---------------+
+ | YANG data node in /interfaces/interface | IF-MIB object |
+ +-----------------------------------------+---------------+
+ | description | ifAlias |
+ +-----------------------------------------+---------------+
+
+ YANG Config Data Nodes and Related IF-MIB Objects
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 10]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+5. Interfaces YANG Module
+
+ This YANG module imports typedefs from [RFC6991].
+
+ <CODE BEGINS> file "ietf-interfaces@2014-05-08.yang"
+
+ module ietf-interfaces {
+
+ namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces";
+ prefix if;
+
+ import ietf-yang-types {
+ prefix yang;
+ }
+
+ organization
+ "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
+
+ contact
+ "WG Web: <http://tools.ietf.org/wg/netmod/>
+ WG List: <mailto:netmod@ietf.org>
+
+ WG Chair: Thomas Nadeau
+ <mailto:tnadeau@lucidvision.com>
+
+ WG Chair: Juergen Schoenwaelder
+ <mailto:j.schoenwaelder@jacobs-university.de>
+
+ Editor: Martin Bjorklund
+ <mailto:mbj@tail-f.com>";
+
+ description
+ "This module contains a collection of YANG definitions for
+ managing network interfaces.
+
+ Copyright (c) 2014 IETF Trust and the persons identified as
+ authors of the code. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or
+ without modification, is permitted pursuant to, and subject
+ to the license terms contained in, the Simplified BSD License
+ set forth in Section 4.c of the IETF Trust's Legal Provisions
+ Relating to IETF Documents
+ (http://trustee.ietf.org/license-info).
+
+ This version of this YANG module is part of RFC 7223; see
+ the RFC itself for full legal notices.";
+
+
+
+
+Bjorklund Standards Track [Page 11]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ revision 2014-05-08 {
+ description
+ "Initial revision.";
+ reference
+ "RFC 7223: 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
+ 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.";
+ }
+
+ /*
+ * 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.";
+ }
+
+
+
+Bjorklund Standards Track [Page 12]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ feature pre-provisioning {
+ description
+ "This feature indicates that the device supports
+ pre-provisioning of interface configuration, i.e., it is
+ possible to configure an interface whose physical interface
+ hardware is not present on the device.";
+ }
+
+ feature if-mib {
+ description
+ "This feature indicates that the device implements
+ the IF-MIB.";
+ reference
+ "RFC 2863: The Interfaces Group MIB";
+ }
+
+ /*
+ * Configuration data nodes
+ */
+
+ container interfaces {
+ description
+ "Interface configuration parameters.";
+
+ list interface {
+ key "name";
+
+ description
+ "The list of configured interfaces on the device.
+
+ The operational state of an interface is available in the
+ /interfaces-state/interface list. If the configuration of a
+ system-controlled interface cannot be used by the system
+ (e.g., the interface hardware present does not match the
+ interface type), then the configuration is not applied to
+ the system-controlled interface shown in the
+ /interfaces-state/interface list. If the configuration
+ of a user-controlled interface cannot be used by the system,
+ the configured interface is not instantiated in the
+ /interfaces-state/interface list.";
+
+ leaf name {
+ type string;
+ description
+ "The name of the interface.
+
+ A device MAY restrict the allowed values for this leaf,
+ possibly depending on the type of the interface.
+
+
+
+Bjorklund Standards Track [Page 13]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ For system-controlled interfaces, this leaf is the
+ device-specific name of the interface. The 'config false'
+ list /interfaces-state/interface contains the currently
+ existing interfaces on the device.
+
+ If a client tries to create configuration for a
+ system-controlled interface that is not present in the
+ /interfaces-state/interface list, the server MAY reject
+ the request if the implementation does not support
+ pre-provisioning of interfaces or if the name refers to
+ an interface that can never exist in the system. A
+ NETCONF server MUST reply with an rpc-error with the
+ error-tag 'invalid-value' in this case.
+
+ If the device supports pre-provisioning of interface
+ configuration, the 'pre-provisioning' feature is
+ advertised.
+
+ If the device allows arbitrarily named user-controlled
+ interfaces, the 'arbitrary-names' feature is advertised.
+
+ When a configured user-controlled interface is created by
+ the system, it is instantiated with the same name in the
+ /interface-state/interface list.";
+ }
+
+ leaf description {
+ type string;
+ description
+ "A textual description of the interface.
+
+ A server implementation MAY map this leaf to the ifAlias
+ MIB object. Such an implementation needs to use some
+ mechanism to handle the differences in size and characters
+ allowed between this leaf and ifAlias. The definition of
+ such a mechanism is outside the scope of this document.
+
+ Since ifAlias is defined to be stored in non-volatile
+ storage, the MIB implementation MUST map ifAlias to the
+ value of 'description' in the persistently stored
+ datastore.
+
+ Specifically, if the device supports ':startup', when
+ ifAlias is read the device MUST return the value of
+ 'description' in the 'startup' datastore, and when it is
+ written, it MUST be written to the 'running' and 'startup'
+ datastores. Note that it is up to the implementation to
+
+
+
+
+Bjorklund Standards Track [Page 14]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ decide whether to modify this single leaf in 'startup' or
+ perform an implicit copy-config from 'running' to
+ '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 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
+ value that can never be used by the system, e.g., if the
+ type is not supported or if the type does not match the
+ name of the interface, the server MUST reject the request.
+ A NETCONF server MUST reply with an rpc-error with the
+ error-tag 'invalid-value' in this case.";
+ reference
+ "RFC 2863: The Interfaces Group MIB - ifType";
+ }
+
+ leaf enabled {
+ type boolean;
+ default "true";
+ description
+ "This leaf contains the configured, desired state of the
+ interface.
+
+ Systems that implement the IF-MIB use the value of this
+ leaf in the 'running' datastore to set
+ IF-MIB.ifAdminStatus to 'up' or 'down' after an ifEntry
+ has been initialized, as described in RFC 2863.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 15]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ Changes in this leaf in the 'running' datastore are
+ reflected in ifAdminStatus, but if ifAdminStatus is
+ changed over SNMP, this leaf is not affected.";
+ reference
+ "RFC 2863: The Interfaces Group MIB - ifAdminStatus";
+ }
+
+ leaf link-up-down-trap-enable {
+ if-feature if-mib;
+ type enumeration {
+ enum enabled {
+ value 1;
+ }
+ enum disabled {
+ value 2;
+ }
+ }
+ description
+ "Controls 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 that 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";
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 16]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ description
+ "The list of interfaces on the device.
+
+ System-controlled interfaces created by the system are
+ always present in this list, whether they are configured or
+ not.";
+
+ leaf name {
+ type string;
+ description
+ "The name of the interface.
+
+ A server implementation MAY map this leaf to the ifName
+ MIB object. Such an implementation needs to use some
+ mechanism to handle the differences in size and characters
+ allowed between this leaf and ifName. The definition of
+ such a mechanism is outside the scope of this document.";
+ reference
+ "RFC 2863: The Interfaces Group MIB - ifName";
+ }
+
+ leaf 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 {
+ enum up {
+ value 1;
+ description
+ "Ready to pass packets.";
+ }
+ enum down {
+ value 2;
+ description
+ "Not ready to pass packets and not in some test mode.";
+ }
+
+
+
+
+
+
+Bjorklund Standards Track [Page 17]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ enum testing {
+ value 3;
+ description
+ "In some test mode.";
+ }
+ }
+ mandatory true;
+ description
+ "The desired state of the interface.
+
+ This leaf has the same read semantics as ifAdminStatus.";
+ reference
+ "RFC 2863: The Interfaces Group MIB - ifAdminStatus";
+ }
+
+ 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 cannot be determined for some reason.";
+ }
+ enum dormant {
+ value 5;
+ description
+ "Waiting for some external event.";
+ }
+ enum not-present {
+ value 6;
+ description
+ "Some component (typically hardware) is missing.";
+ }
+
+
+
+Bjorklund Standards Track [Page 18]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ enum lower-layer-down {
+ value 7;
+ description
+ "Down due to state of lower-layer interface(s).";
+ }
+ }
+ mandatory true;
+ description
+ "The current operational state of the interface.
+
+ This leaf has the same semantics as ifOperStatus.";
+ reference
+ "RFC 2863: The Interfaces Group MIB - ifOperStatus";
+ }
+
+ leaf last-change {
+ type yang:date-and-time;
+ 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";
+ }
+ mandatory true;
+ description
+ "The ifIndex value for the ifEntry represented by this
+ interface.";
+ reference
+ "RFC 2863: The Interfaces Group MIB - ifIndex";
+ }
+
+ leaf phys-address {
+ type yang:phys-address;
+ description
+ "The interface's address at its protocol sub-layer. For
+ example, for an 802.x interface, this object normally
+ contains a Media Access Control (MAC) address. The
+ interface's media-specific modules must define the bit
+
+
+
+
+
+Bjorklund Standards Track [Page 19]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ 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-state-ref;
+ 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-state-ref;
+ description
+ "A list of references to interfaces layered underneath this
+ interface.";
+ reference
+ "RFC 2863: The Interfaces Group MIB - ifStackTable";
+ }
+
+ leaf speed {
+ type yang:gauge64;
+ units "bits/second";
+ description
+ "An estimate of the interface's current bandwidth in bits
+ per second. For interfaces that 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 have no concept of bandwidth, this
+ node is not present.";
+ reference
+ "RFC 2863: The Interfaces Group MIB -
+ ifSpeed, ifHighSpeed";
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 20]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ container statistics {
+ description
+ "A collection of interface-related statistics objects.";
+
+ leaf discontinuity-time {
+ type yang:date-and-time;
+ mandatory true;
+ 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
+ '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, that 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";
+ }
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 21]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ leaf in-broadcast-pkts {
+ type yang:counter64;
+ description
+ "The number of packets, delivered by this sub-layer to a
+ higher (sub-)layer, that 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, that 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";
+ }
+
+ leaf in-discards {
+ type yang:counter32;
+ description
+ "The number of inbound packets that 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'.";
+
+
+
+
+
+Bjorklund Standards Track [Page 22]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ 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 that 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 that were
+ discarded because of an unknown or unsupported protocol.
+ For any interface that does not support protocol
+ multiplexing, this counter is not present.
+
+ 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";
+ }
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 23]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ 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 that 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 that 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'.";
+ reference
+ "RFC 2863: The Interfaces Group MIB -
+ ifHCOutBroadcastPkts";
+ }
+
+
+
+
+
+Bjorklund Standards Track [Page 24]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ leaf out-multicast-pkts {
+ type yang:counter64;
+ description
+ "The total number of packets that higher-level protocols
+ requested be transmitted, and that 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 that 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.
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 25]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ 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 - ifOutErrors";
+ }
+ }
+ }
+ }
+ }
+
+ <CODE ENDS>
+
+6. IANA Considerations
+
+ This document registers a URI in the "IETF XML Registry" [RFC3688].
+ Following the format in RFC 3688, the following registration has been
+ 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 7223
+
+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]. The NETCONF access control model
+ [RFC6536] provides the means to restrict access for particular
+ NETCONF users to a pre-configured subset of all available NETCONF
+ protocol operations and content.
+
+ 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>)
+
+
+
+Bjorklund Standards Track [Page 26]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ 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 whether an
+ interface is enabled or not. Unauthorized access to this leaf
+ could cause the device to ignore packets it should receive and
+ process.
+
+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
+
+ [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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 27]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+9.2. Informative References
+
+ [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.
+
+ [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
+ Protocol (NETCONF) Access Control Model", RFC 6536,
+ March 2012.
+
+ [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module",
+ RFC 7224, May 2014.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 28]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+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 also shows how operational state
+ parameters can be conditionally augmented to the operational
+ 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 = 'ianaift:ethernetCsmacd'";
+
+ container ethernet {
+ choice transmission-params {
+ case auto {
+ leaf auto-negotiate {
+ type empty;
+ }
+ }
+ case manual {
+ leaf duplex {
+ type enumeration {
+ enum "half";
+ enum "full";
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 29]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ leaf speed {
+ type enumeration {
+ enum "10Mb";
+ enum "100Mb";
+ enum "1Gb";
+ enum "10Gb";
+ }
+ }
+ }
+ }
+ // other Ethernet-specific params...
+ }
+ }
+
+ // operational state parameters for Ethernet interfaces
+ augment "/if:interfaces-state/if:interface" {
+ when "if:type = 'ianaift:ethernetCsmacd'";
+
+ container ethernet {
+ leaf duplex {
+ type enumeration {
+ enum "half";
+ enum "full";
+ }
+ }
+ // other Ethernet-specific params...
+ }
+ }
+ }
+
+Appendix B. Example: Ethernet Bonding Interface Module
+
+ This section gives an example of how interface layering can be
+ defined. An Ethernet bonding interface that bonds several Ethernet
+ interfaces into one logical interface is defined.
+
+ module ex-ethernet-bonding {
+ namespace "http://example.com/ethernet-bonding";
+ prefix "bond";
+
+ import ietf-interfaces {
+ prefix if;
+ }
+ import iana-if-type {
+ prefix ianaift;
+ }
+
+
+
+
+
+Bjorklund Standards Track [Page 30]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ augment "/if:interfaces/if:interface" {
+ when "if:type = 'ianaift:ieee8023adLag'";
+
+ leaf-list slave-if {
+ type if:interface-ref;
+ must "/if:interfaces/if:interface[if:name = current()]"
+ + "/if:type = 'ianaift:ethernetCsmacd'" {
+ description
+ "The type of a slave interface must be 'ethernetCsmacd'.";
+ }
+ }
+ leaf bonding-mode {
+ type enumeration {
+ enum round-robin;
+ enum active-backup;
+ enum broadcast;
+ }
+ }
+ // other bonding config params, failover times, etc.
+ }
+ }
+
+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;
+ }
+ import iana-if-type {
+ prefix ianaift;
+ }
+
+ augment "/if:interfaces/if:interface" {
+ when "if:type = 'ianaift:ethernetCsmacd' or
+ if:type = 'ianaift:ieee8023adLag'";
+ leaf vlan-tagging {
+ type boolean;
+ default false;
+ }
+ }
+
+
+
+
+
+Bjorklund Standards Track [Page 31]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ augment "/if:interfaces/if:interface" {
+ 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 {
+ type uint16 {
+ range "1..4094";
+ }
+ must "../base-interface" {
+ description
+ "If a vlan-id is defined, a base-interface must
+ be specified.";
+ }
+ }
+ }
+ }
+
+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"
+ xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type"
+ xmlns:vlan="http://example.com/vlan">
+
+ <interface>
+ <name>eth0</name>
+ <type>ianaift:ethernetCsmacd</type>
+ <enabled>false</enabled>
+ </interface>
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 32]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ <interface>
+ <name>eth1</name>
+ <type>ianaift:ethernetCsmacd</type>
+ <enabled>true</enabled>
+ <vlan:vlan-tagging>true</vlan:vlan-tagging>
+ </interface>
+
+ <interface>
+ <name>eth1.10</name>
+ <type>ianaift:l2vlan</type>
+ <enabled>true</enabled>
+ <vlan:base-interface>eth1</vlan:base-interface>
+ <vlan:vlan-id>10</vlan:vlan-id>
+ </interface>
+
+ <interface>
+ <name>lo1</name>
+ <type>ianaift:softwareLoopback</type>
+ <enabled>true</enabled>
+ </interface>
+
+ </interfaces>
+
+ <interfaces-state
+ xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
+ xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">
+
+ <interface>
+ <name>eth0</name>
+ <type>ianaift:ethernetCsmacd</type>
+ <admin-status>down</admin-status>
+ <oper-status>down</oper-status>
+ <if-index>2</if-index>
+ <phys-address>00:01:02:03:04:05</phys-address>
+ <statistics>
+ <discontinuity-time>
+ 2013-04-01T03:00:00+00:00
+ </discontinuity-time>
+ <!-- counters now shown here -->
+ </statistics>
+ </interface>
+
+ <interface>
+ <name>eth1</name>
+ <type>ianaift:ethernetCsmacd</type>
+ <admin-status>up</admin-status>
+ <oper-status>up</oper-status>
+ <if-index>7</if-index>
+
+
+
+Bjorklund Standards Track [Page 33]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ <phys-address>00:01:02:03:04:06</phys-address>
+ <higher-layer-if>eth1.10</higher-layer-if>
+ <statistics>
+ <discontinuity-time>
+ 2013-04-01T03:00:00+00:00
+ </discontinuity-time>
+ <!-- counters now shown here -->
+ </statistics>
+ </interface>
+
+ <interface>
+ <name>eth1.10</name>
+ <type>ianaift:l2vlan</type>
+ <admin-status>up</admin-status>
+ <oper-status>up</oper-status>
+ <if-index>9</if-index>
+ <lower-layer-if>eth1</lower-layer-if>
+ <statistics>
+ <discontinuity-time>
+ 2013-04-01T03:00:00+00:00
+ </discontinuity-time>
+ <!-- counters now shown here -->
+ </statistics>
+ </interface>
+
+ <!-- This interface is not configured -->
+ <interface>
+ <name>eth2</name>
+ <type>ianaift:ethernetCsmacd</type>
+ <admin-status>down</admin-status>
+ <oper-status>down</oper-status>
+ <if-index>8</if-index>
+ <phys-address>00:01:02:03:04:07</phys-address>
+ <statistics>
+ <discontinuity-time>
+ 2013-04-01T03:00:00+00:00
+ </discontinuity-time>
+ <!-- counters now shown here -->
+ </statistics>
+ </interface>
+
+ <interface>
+ <name>lo1</name>
+ <type>ianaift:softwareLoopback</type>
+ <admin-status>up</admin-status>
+ <oper-status>up</oper-status>
+ <if-index>1</if-index>
+ <statistics>
+
+
+
+Bjorklund Standards Track [Page 34]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ <discontinuity-time>
+ 2013-04-01T03:00:00+00:00
+ </discontinuity-time>
+ <!-- counters now shown here -->
+ </statistics>
+ </interface>
+
+ </interfaces-state>
+ </data>
+ </rpc-reply>
+
+Appendix E. Examples: Interface Naming Schemes
+
+ This section gives examples of some implementation strategies.
+
+ The examples make use of the example data model "ex-vlan" (see
+ Appendix C) to show how user-controlled interfaces can be configured.
+
+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 Ethernet
+ or Gigabit Ethernet ports.
+
+ The device-specific names for these physical interfaces are
+ "fastethernet-N/M" or "gigabitethernet-N/M".
+
+ The name of a VLAN interface is restricted to the form
+ "<physical-interface-name>.<subinterface-number>".
+
+ It is assumed that the operator is aware of this naming scheme. The
+ implementation auto-initializes the value for "type" based on the
+ interface name.
+
+ The NETCONF server does not advertise the "arbitrary-names" feature
+ in the <hello> message.
+
+ An operator can configure a physical interface by sending an
+ <edit-config> containing:
+
+ <interface nc:operation="create">
+ <name>fastethernet-1/0</name>
+ </interface>
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 35]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ When the server processes this request, it will set the leaf "type"
+ to "ianaift:ethernetCsmacd". Thus, if the client performs a
+ <get-config> right after the <edit-config> above, it will get:
+
+ <interface>
+ <name>fastethernet-1/0</name>
+ <type>ianaift:ethernetCsmacd</type>
+ </interface>
+
+ The client can configure a VLAN interface by sending an <edit-config>
+ containing:
+
+ <interface nc:operation="create">
+ <name>fastethernet-1/0.10005</name>
+ <type>ianaift:l2vlan</type>
+ <vlan:base-interface>fastethernet-1/0</vlan:base-interface>
+ <vlan:vlan-id>5</vlan:vlan-id>
+ </interface>
+
+ If the client tries to change the type of the physical interface with
+ an <edit-config> containing:
+
+ <interface nc:operation="merge">
+ <name>fastethernet-1/0</name>
+ <type>ianaift:tunnel</type>
+ </interface>
+
+ 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 Ethernet
+ or Gigabit Ethernet ports.
+
+ The device-specific names for these physical interfaces are
+ "fastethernet-N/M" or "gigabitethernet-N/M".
+
+ The implementation does not restrict the user-controlled interface
+ names. This allows an operator to more easily apply the interface
+ configuration to a different 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 NETCONF server advertises the "arbitrary-names" feature in the
+ <hello> message.
+
+
+
+Bjorklund Standards Track [Page 36]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+ Physical interfaces are configured as in Appendix E.1.
+
+ An operator can configure a VLAN interface by sending an
+ <edit-config> containing:
+
+ <interface nc:operation="create">
+ <name>acme-interface</name>
+ <type>ianaift:l2vlan</type>
+ <vlan:base-interface>fastethernet-1/0</vlan:base-interface>
+ <vlan:vlan-id>5</vlan:vlan-id>
+ </interface>
+
+ If necessary, the operator can move the configuration named
+ "acme-interface" over to a different physical interface with an
+ <edit-config> containing:
+
+ <interface nc:operation="merge">
+ <name>acme-interface</name>
+ <vlan:base-interface>fastethernet-1/1</vlan:base-interface>
+ </interface>
+
+E.3. Ethernet Switch with Restricted Interface Names
+
+ In this example, an Ethernet switch has a number of ports, each
+ identified by a simple port number.
+
+ The device-specific names for the physical interfaces are numbers
+ that match the physical port number.
+
+ An operator can configure a physical interface by sending an
+ <edit-config> containing:
+
+ <interface nc:operation="create">
+ <name>6</name>
+ </interface>
+
+ When the server processes this request, it will set the leaf "type"
+ to "ianaift:ethernetCsmacd". Thus, if the client performs a
+ <get-config> right after the <edit-config> above, it will get:
+
+ <interface>
+ <name>6</name>
+ <type>ianaift:ethernetCsmacd</type>
+ </interface>
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 37]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+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
+ "<physical-interface-name>:<vlan-number>".
+
+ The NETCONF server does not advertise the "arbitrary-names" feature
+ in the <hello> message.
+
+ An operator can configure an interface by sending an <edit-config>
+ containing:
+
+ <interface nc:operation="create">
+ <name>eth8</name>
+ </interface>
+
+ When the server processes this request, it will set the leaf "type"
+ to "ianaift:ethernetCsmacd". Thus, if the client performs a
+ <get-config> right after the <edit-config> above, it will get:
+
+ <interface>
+ <name>eth8</name>
+ <type>ianaift:ethernetCsmacd</type>
+ </interface>
+
+ The client can configure a VLAN interface by sending an <edit-config>
+ containing:
+
+ <interface nc:operation="create">
+ <name>eth8:5</name>
+ <type>ianaift:l2vlan</type>
+ <vlan:base-interface>eth8</vlan:base-interface>
+ <vlan:vlan-id>5</vlan:vlan-id>
+ </interface>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 38]
+
+RFC 7223 YANG Interface Management May 2014
+
+
+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.
+
+ The implementation does not restrict the user-controlled interface
+ names. This allows an operator to more easily apply the interface
+ configuration to a different 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 NETCONF server advertises the "arbitrary-names" feature in the
+ <hello> message.
+
+ Physical interfaces are configured as in Appendix E.4.
+
+ An operator can configure a VLAN interface by sending an
+ <edit-config> containing:
+
+ <interface nc:operation="create">
+ <name>acme-interface</name>
+ <type>ianaift:l2vlan</type>
+ <vlan:base-interface>eth8</vlan:base-interface>
+ <vlan:vlan-id>5</vlan:vlan-id>
+ </interface>
+
+ If necessary, the operator can move the configuration named
+ "acme-interface" over to a different physical interface with an
+ <edit-config> containing:
+
+ <interface nc:operation="merge">
+ <name>acme-interface</name>
+ <vlan:base-interface>eth3</vlan:base-interface>
+ </interface>
+
+Author's Address
+
+ Martin Bjorklund
+ Tail-f Systems
+
+ EMail: mbj@tail-f.com
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 39]
+