A YANG Data Model for Interface Management
obsoleted by
- rfc-8343 — A YANG Data Model for Interface Management
Extracted elements (24)
A flat list of interfaces (rather than a hierarchical structure) was chosen to keep the data model simple, facilitate mapping to proprietary native data models, and to allow references by a single leafref. The model supports both physical and logical interfaces in the same flat list.
Configuration data and operational state data are kept in separate lists ('/interfaces/interface' and '/interfaces-state/interface') rather than merged, enabling clear separation between desired configuration and actual runtime state. System-controlled interfaces always appear in the state list whether configured or not.
Only 64-bit counters (yang:counter64) are provided in this data model, unlike the IF-MIB which provides both 32-bit and 64-bit versions. This is because today's implementations generally support high-speed interfaces (>20 Mbps) for which 32-bit counters were insufficient.
There is no generic mechanism for configuring interface layering; each interface-type-specific model defines its own layering data nodes using 'interface-ref' types. Two generic read-only leaf-lists ('higher-layer-if' and 'lower-layer-if') provide a unified view of the layering hierarchy regardless of the type-specific configuration method.
ifMtu and ifDescr/ifConnectorPresent from the IF-MIB are intentionally not mapped to the 'ietf-interfaces' module. MTU is expected to be provided by interface-type-specific augmenting modules.
The 'description' leaf may be mapped to ifAlias in implementations. Implementers must handle differences in value space and persistence between this leaf and ifAlias; the IF-MIB defines ifAlias to be stored in non-volatile storage.
The IF-MIB allows two different ifEntries to have the same ifName. Devices that support this feature and also support the ietf-interfaces data model cannot have a 1-1 mapping between the 'name' leaf and ifName, creating a compatibility constraint.
If a client tries to create configuration for a system-controlled interface not present in '/interfaces-state/interface', the server MAY reject the request if it does not support pre-provisioning or if the name can never exist; in that case, a NETCONF server MUST reply with an rpc-error with error-tag 'invalid-value'.
If a client tries to set the interface type to a value that can never be used by the system, the server MUST reject the request and a NETCONF server MUST reply with an rpc-error with the error-tag 'invalid-value'.
If the 'arbitrary-names' feature is not advertised, the names of user-controlled interfaces MUST match the device's naming scheme. A client cannot assume arbitrary naming is supported.
If the device implements the IF-MIB, the 'if-index' leaf MUST contain the value of the corresponding ifEntry's ifIndex.
Other YANG modules SHOULD use the 'interface-ref' and 'interface-state-ref' typedefs when referencing a configured or operationally used interface, respectively.
When a server maps 'description' to ifAlias and the device supports ':startup', reading ifAlias MUST return the value of 'description' in the 'startup' datastore, and writing ifAlias MUST write to both 'running' and 'startup' datastores. If ':startup' is not supported, ifAlias MUST be mapped to the 'description' leaf in the 'running' datastore.
Each configured interface entry under '/interfaces/interface' has leaves: 'name' (string, key), 'description' (optional string), 'type' (mandatory identityref based on interface-type identity), 'enabled' (boolean, default true), and 'link-up-down-trap-enable' (enumeration, if-mib feature only).
Each operational interface entry under '/interfaces-state/interface' has leaves: 'name', 'type', 'admin-status' (up/down/testing), 'oper-status' (up/down/testing/unknown/dormant/not-present/lower-layer-down), 'last-change', 'if-index', 'phys-address', 'higher-layer-if', 'lower-layer-if', 'speed', and a 'statistics' container.
The 'ietf-interfaces' YANG module defines two top-level containers: '/interfaces' (config true) holding the list of configured interfaces keyed by name, and '/interfaces-state' (config false) holding the operational state of all interfaces including counters. Interface-type-specific models are expected to augment these lists.
The 'statistics' container under '/interfaces-state/interface' provides read-only 64-bit counters (yang:counter64) 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 (yang:counter32) for in-discards, in-errors, in-unknown-protos, out-discards, out-errors. A mandatory 'discontinuity-time' leaf marks when counters last reset.
Three YANG features are defined: 'arbitrary-names' (device allows arbitrarily named user-controlled interfaces), 'pre-provisioning' (device supports configuring interfaces whose hardware is not yet present), and 'if-mib' (device implements the IF-MIB, RFC 2863). Feature advertisement occurs in the NETCONF <hello> message.
Two typedefs are defined: 'interface-ref' (leafref to /interfaces/interface/name) for referencing configured interfaces, and 'interface-state-ref' (leafref to /interfaces-state/interface/name) for referencing operationally present interfaces. Other YANG modules should use these when referencing interfaces.
This document registers the URI 'urn:ietf:params:xml:ns:yang:ietf-interfaces' in the IETF XML Registry (RFC 3688) as an XML namespace.
This document registers the YANG module 'ietf-interfaces' in the YANG Module Names registry (RFC 6020) with namespace 'urn:ietf:params:xml:ns:yang:ietf-interfaces' and prefix 'if'.
The YANG module is designed to be accessed via NETCONF; the mandatory-to-implement secure transport is SSH (RFC 6242). The NETCONF access control model (RFC 6536) provides means to restrict access to NETCONF operations and content.
Unauthorized write access to '/interfaces/interface' or '/interfaces/interface/enabled' could cause the device to ignore packets it should receive and process, negatively impacting network operations. These writable nodes must be protected appropriately.
The 'oper-status' leaf defines seven states: 'up' (ready to pass packets), 'down' (not passing packets), 'testing' (in test mode), 'unknown' (status cannot be determined), 'dormant' (waiting for external event), 'not-present' (hardware missing), and 'lower-layer-down' (down due to lower-layer interface state). These mirror ifOperStatus from IF-MIB.