A YANG Data Model for Network Topologies
Extracted elements (28)
All data nodes are designated `config true` even though much topology information is discovered rather than configured. The distinction between configured and discovered data is handled by NMDA datastores (`<intended>` vs `<operational>`) rather than by separate `config true`/`config false` trees, preserving a single coherent model.
Identifiers are typed as `inet:uri` rather than plain strings because URIs make structure explicit, can be fed into a URI resolver for additional resources, and facilitate correlation of identifiers across systems. Free-form strings tend to embed implicit structure that must be communicated out-of-band.
Links are point-to-point and unidirectional by design, which keeps the model simple and directly amenable to graph algorithms. Bidirectional connections are represented as pairs of unidirectional links; multipoint topologies use pseudonodes and node hierarchies.
Multihoming and link aggregation are represented by multiple point-to-point links at a lower layer, with a single aggregated link at a higher layer carrying a `supporting-link` list pointing to the constituent links. No special aggregation construct is introduced.
Termination point–to–termination point mapping information is technically derivable from link mappings via transitive closure, making it redundant. The data model nonetheless allows it to be configured explicitly to avoid constraining applications, and includes integrity constraints for consistency validation.
The data model is kept flat rather than nesting nodes, links, and termination points in separate containers. This keeps path identifiers compact for use in management operations and constraints, at the cost of reduced visual separation between list types in instance data.
The data model uses groupings instead of inline data node definitions to simplify inclusion of topology data in YANG notifications, which otherwise would need to re-specify each included data node. The trade-off is increased complexity in XPath constraints, which must navigate into the grouping.
The model is split into `ietf-network` (nodes and network hierarchy) and `ietf-network-topology` (links and termination points) so that inventory data models can augment the base network module independently of topology concerns, avoiding forced coupling between inventory and topology.
The `ietf-network-topology` module uses `require-instance false` on all leafrefs within `supporting-link`, `supporting-termination-point`, and related constructs to accommodate the possibility that underlay objects may transiently not exist (network churn), rather than mandating strict referential integrity at the YANG layer.
Two companion modules — `ietf-network-state` and `ietf-network-topology-state` — are defined in Appendix B for implementations that do not support NMDA. They mirror the main modules but with all data nodes set `config false`. Implementations supporting NMDA SHOULD NOT implement these companion modules.
Network types SHOULD always be represented using presence containers, not leafs of type `empty`. This enables representation of hierarchies of network subtypes (e.g., an OSPF network is also an L3-unicast-IGP network) within instance information.
The companion state modules (`ietf-network-state` and `ietf-network-topology-state`) SHOULD NOT be supported by implementations that support NMDA, as they are redundant when NMDA datastores are available.
When a server receives a request to configure an overlay network, it SHOULD validate that supporting nodes/links/termination points exist in the operational state datastore. Configuration requests referencing non-existent supporting objects SHOULD be rejected.
When an implementation places written (client-configured) data for this data model in the ephemeral datastore, such a network MAY refer to another network that is system controlled, permitting overlay networks to be layered atop dynamically discovered underlays.
Although no personally identifiable information is explicitly defined in the modules, node identifiers (URIs) may be associated with specific devices, which may in turn be associated with specific users. Operators should consider this when exposing topology data.
Each `node` in a network is identified by a `node-id` (type `inet:uri`) unique within its containing network. A node may have a `supporting-node` list that references nodes in underlay networks, capturing hierarchical device representations (e.g., a router node supported by line-card nodes).
Identifiers for networks (`network-id`), nodes (`node-id`), links (`link-id`), and termination points (`tp-id`) are all defined as `inet:uri`. The SHOULD requirement is that the same real-world entity always maps to the same identifier across separate datastore instantiations.
The `ietf-network` module defines a top-level `networks` container holding a list of `network` entries, each keyed by `network-id` (of type `inet:uri`). Each network contains a `network-types` augmentation target, a `supporting-network` list for underlay references, and a `node` list representing the network inventory.
The `ietf-network-topology` module augments `ietf-network` with a `link` list keyed by `link-id` (type `inet:uri`). A link has `source` (source-node, source-tp) and `destination` (dest-node, dest-tp) containers, plus a `supporting-link` list for underlay link mappings. Links are strictly point-to-point and unidirectional.
The `network-types` container serves purely as an augmentation target; technology-specific modules insert presence containers beneath it to indicate the network type(s). A network may simultaneously represent multiple types, which is why a container (not a case construct or leaf-list) is used.
The `supporting-network` list within a `network` entry captures underlay networks. Each entry contains a `network-ref` leafref (with `require-instance false`) pointing to another network-id, enabling expression of multi-layer network stacks.
The `termination-point` list (keyed by `tp-id` of type `inet:uri`) is augmented into each `node` by `ietf-network-topology`. A termination point anchors links and may represent a port or interface. It may have a `supporting-termination-point` list referencing termination points in underlay nodes.
Four XML namespace URIs are registered in the IETF XML Registry: `urn:ietf:params:xml:ns:yang:ietf-network`, `urn:ietf:params:xml:ns:yang:ietf-network-topology`, `urn:ietf:params:xml:ns:yang:ietf-network-state`, and `urn:ietf:params:xml:ns:yang:ietf-network-topology-state`.
Four YANG modules are registered in the YANG Module Names registry: `ietf-network` (prefix `nw`), `ietf-network-topology` (prefix `nt`), `ietf-network-state` (prefix `nw-s`), and `ietf-network-topology-state` (prefix `nt-s`), all referencing RFC 8345.
A malicious client with write access to configured (overlay) topologies can add or remove networks, nodes, links, and termination points. This can result in service disruption, suboptimal routing, or increased resource consumption in the underlay. System-controlled topologies are automatically protected from such misconfiguration by the server.
Network topology and inventory data exposed by these modules reveals the structure of networks, which is highly useful to an attacker. Implementations MUST apply the NETCONF access control model (RFC 8341) to restrict which users can read or modify topology data.
The lowest NETCONF layer must use SSH (RFC 6242) and the lowest RESTCONF layer must use HTTPS with TLS (RFC 5246) as mandatory-to-implement secure transports when accessing these YANG modules.
A configured overlay object (node, link, or termination point) transitions out of `<operational>` when its `supporting-*` leafref becomes dangling (i.e., the referenced underlay object is deleted). The object remains in `<intended>`. It re-enters `<operational>` when either the supporting object reappears in `<operational>` or the reference is reconfigured to an existing object.