A YANG Data Model for Interface Management
obsoletes
- rfc-7223 — A YANG Data Model for Interface Management
Extracted elements (24)
Only 64-bit counters are provided in the statistics container, unlike the IF-MIB which defines both 32-bit and 64-bit versions. The rationale is that today's implementations generally support high-speed interfaces (>20 Mbps) where 64-bit counters are needed, making the 32-bit variants redundant.
The data model uses a simple flat list of interfaces rather than a hierarchical structure, to facilitate mapping to existing proprietary native data models and to make interface references as simple as possible (a single leafref). Interface layering is expressed through read-only 'higher-layer-if' and 'lower-layer-if' leaf-lists rather than a generic configurable hierarchy.
The model supports pre-provisioning of interface configuration (configuring an interface before its hardware is present) as an optional capability advertised via the 'pre-provisioning' feature. This is recommended for devices supporting dynamic addition/removal of physical interfaces, but cannot be assumed in all cases due to OS and hardware constraints.
There is intentionally no generic mechanism in 'ietf-interfaces' for configuring interface layering. Interface-type-specific models are expected to define their own layering data nodes using 'interface-ref' types, allowing type-appropriate constraints (e.g., a bonding slave must be of type 'ethernetCsmacd').
The IF-MIB allows two ifEntries to share the same ifName; devices supporting this feature cannot maintain a 1-1 mapping between the 'name' leaf and ifName. Additionally, ifMtu, ifDescr, ifConnectorPresent, and ifPromiscuousMode are not mapped to 'ietf-interfaces' and are expected to be provided by interface-type-specific augmenting modules.
The '/interfaces-state' subtree with 'config false' data nodes from RFC 7223 is deprecated in this revision; all 'config false' data nodes are now present in the '/interfaces' subtree in conformance with the NMDA architecture (RFC 8342).
This document maps YANG data nodes to IF-MIB objects: 'name'→ifName, 'type'→ifType, 'description'→ifAlias, 'admin-status'→ifAdminStatus, 'oper-status'→ifOperStatus, 'if-index'→ifIndex, 'phys-address'→ifPhysAddress, 'higher-layer-if'/'lower-layer-if'→ifStackTable, 'speed'→ifSpeed/ifHighSpeed, and all statistics counters to their HC (64-bit) IF-MIB counterparts.
If a client tries to create configuration for a system-controlled interface not present in the operational state and the implementation does not support pre-provisioning, a NETCONF server MUST reply with an rpc-error with the error-tag 'invalid-value'.
If a client tries to set the interface 'type' to a value that can never be used by the system (unsupported type or type mismatch with name), the server MUST reject the request; a NETCONF server MUST reply with an rpc-error with the error-tag 'invalid-value'.
If the device implements the IF-MIB, the 'if-index' leaf MUST contain the value of the corresponding ifEntry's ifIndex.
If the server does not advertise the 'arbitrary-names' feature, the names of user-controlled interfaces MUST match the device's naming scheme.
Other YANG modules SHOULD use the 'interface-ref' typedef when they need to reference an interface, ensuring consistent referencing across data models.
Servers that do not implement NMDA, or that wish to support clients that do not implement NMDA, MAY implement the deprecated '/interfaces-state' tree.
The 'discontinuity-time' mandatory leaf (yang:date-and-time) in the statistics container records the most recent time any counter on the interface suffered a discontinuity; if no discontinuity since last management subsystem re-initialization, it contains the re-initialization time. Consumers must check this value before computing counter deltas.
The 'enabled' leaf (boolean, default true) represents the configured desired state of the interface. Systems implementing IF-MIB map this to ifAdminStatus ('up' when true, 'down' when false). The 'admin-status' leaf (if-mib feature) is a read-only reflection of the same value from the operational state.
The 'ietf-interfaces' YANG module defines a flat list '/interfaces/interface' keyed by 'name', with a mandatory 'type' leaf (identityref based on 'interface-type' identity). Each entry carries configuration leaves (enabled, description, link-up-down-trap-enable) and read-only state leaves (admin-status, oper-status, last-change, if-index, phys-address, higher-layer-if, lower-layer-if, speed, statistics).
The 'interface-ref' typedef is a leafref to '/if:interfaces/if:interface/if:name' and is the standard type other YANG modules should use when referencing an interface by name.
The 'link-up-down-trap-enable' leaf (if-mib feature, enumeration: enabled=1/disabled=2) controls whether linkUp/linkDown SNMP notifications are generated. If unconfigured, 'enabled' is operationally used for interfaces with no lower-layer-if entries, and 'disabled' otherwise.
The 'statistics' container under each interface entry is read-only (config false) and contains a mandatory 'discontinuity-time' leaf (yang:date-and-time), 64-bit counters for in-octets, in-unicast-pkts, in-broadcast-pkts, in-multicast-pkts, out-octets, out-unicast-pkts, out-broadcast-pkts, out-multicast-pkts, and 32-bit counters for in-discards, in-errors, in-unknown-protos, out-discards, out-errors.
Three YANG features gate optional behavior: 'arbitrary-names' (device allows freely named user-controlled interfaces), 'pre-provisioning' (interface config may be added before hardware is present), and 'if-mib' (device implements the IF-MIB, enabling admin-status, if-index, and link-up-down-trap-enable nodes).
This document registers URI 'urn:ietf:params:xml:ns:yang:ietf-interfaces' in the IETF XML Registry (RFC 3688) as an XML namespace, and registers the YANG module named 'ietf-interfaces' (prefix 'if') in the YANG Module Names registry (RFC 6020).
The '/interfaces/interface' list and '/interfaces/interface/enabled' leaf are writable and considered sensitive: unauthorized write access could cause the device to ignore packets it should receive and process, disrupting network operations.
The YANG module is accessed via NETCONF or RESTCONF; the mandatory-to-implement secure transport for NETCONF is SSH (RFC 6242) and for RESTCONF is TLS (RFC 5246). The NETCONF Access Control Model (RFC 8341) must be used to restrict access to authorized users.
The 'oper-status' leaf defines seven operational states: up (passing packets), down (not passing packets), testing (test mode, no operational traffic), unknown (status indeterminate), dormant (waiting for external event), not-present (hardware component missing), and lower-layer-down (down due to lower-layer interface state).