RFC 8346
A YANG Data Model for Layer 3 Topologies
RFC 8346: A YANG Data Model for Layer 3 Topologies 💖
Okay bestie, this one is from the IETF (Internet Engineering Task Force) 🌸 It's RFC 8346, and it came out in March 2018. The main author is A. Clemm from Huawei. The other authors are J. Medved (Cisco), R. Varga (Pantheon Technologies SRO), X. Liu (Jabil), H. Ananthakrishnan (Packet Design), and N. Bahadur (Bracket Computing). It's a Standards Track document, and its ISSN is 2070-1721. The title block doesn't list any Obsoletes or Updates lines, so this RFC isn't replacing or patching anything else 🦋
Abstract ✨
This doc defines a YANG data model for Layer 3 network topologies. That's the whole pitch, and it's a big deal 💅
Status of This Memo 📜
This is an Internet Standards Track document. It's a product of the IETF and represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 7841.
For the current status of this document, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc8346 🎀
Copyright Notice
Copyright (c) 2018 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 (https://trustee.ietf.org/license-info) as they were in effect on the publication date. Please read these carefully, because they spell out your rights and restrictions with respect to this document. Code Components pulled out of this document must include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License 🧚
Table of Contents 🗺️
1. Introduction ....................................................3
2. Key Words .......................................................3
3. Definitions and Acronyms ........................................4
4. Model Structure .................................................5
5. Layer 3 Unicast Topology Model Overview .........................6
6. Layer 3 Unicast Topology YANG Module ............................7
7. Interactions with Other YANG Modules ...........................15
8. IANA Considerations ............................................15
9. Security Considerations ........................................16
10. References ....................................................17
10.1. Normative References .....................................17
10.2. Informative References ...................................19
Appendix A. Companion YANG Data Model for Implementations Not
Compliant with NMDA ..................................20
Appendix B. Extending the Model ..................................24
B.1. Example OSPF Topology .....................................24
B.1.1. Model Overview ........................................24
B.1.2. OSPF Topology YANG Module .............................26
Appendix C. An Example ...........................................29
Acknowledgments ...................................................34
Contributors ......................................................34
Authors' Addresses ................................................351. Introduction ✨
So this document brings in a YANG [RFC7950] [RFC6991] data model for Layer 3 (L3) network topologies, specifically Layer 3 Unicast 🦋 The model lets an application see the whole topology of an L3 network at once, all sitting in one conceptual YANG datastore. It builds on top of the topology model from [RFC8345] and augments it.
The doc also shows how you can refine the model to cover different kinds of Layer 3 Unicast topology. For that, there's an example model covering OSPF [RFC2328]. This example is just for illustration, and the authors expect a real OSPF model to be way more thorough and polished than the one shown here 💅
There are lots of things you can do with a topology data model, and Section 6 of [USECASE-REQS] has a list of use cases. For example, nodes in the network can use the model to record what they think the overall topology looks like and share that with a network controller. The controller can then compare its own view with what the network elements it controls are reporting, and reconcile the differences. Nodes could also pass their understanding around to compare and reconcile among themselves, or with a controller's help. And a network controller could even use the model to show its view of the topology it controls to applications sitting above it 🌸
The Layer 3 Unicast model in this document is written in the YANG module ietf-l3-unicast-topology. That module augments the general network topology model from [RFC8345] with Layer 3 Unicast info, so the general model gets extended to handle Layer 3 Unicast topologies 💖
Anything stored in the Traffic Engineering Database (TED) gets its own separate model [YANG-TE]. That's outside the scope of this spec, so no spoilers here 🙈
2. Key Words 🔑
Here are the key words that carry special meaning in this document: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL". They get interpreted as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, exactly as shown here. Lowercase versions are just regular words, bestie 🎀
3. Definitions and Acronyms 📖
This document defines a YANG data model, so it uses a lot of terms that are already defined in YANG [RFC7950] and NETCONF [RFC6241]. A few of them, like "datastore" and "data tree", get repeated here so you don't have to hop around for context 🧚
- Datastore: A conceptual place to store and access information. A datastore could be built out of files, a database, flash memory locations, or some mix of those. A datastore maps to an instantiated YANG data tree (definition adopted from [RFC8342]).
- Data subtree: An instantiated data node together with all the data nodes hierarchically contained inside it.
- IS-IS: Intermediate System to Intermediate System protocol
- LSP: Label Switched Path
- NETCONF: Network Configuration Protocol
- NMDA: Network Management Datastore Architecture
- OSPF: Open Shortest Path First (a link-state routing protocol)
- URI: Uniform Resource Identifier
- TED: Traffic Engineering Database
- YANG: YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols [RFC7950].
4. Model Structure 🧩
The Layer 3 Unicast topology model is defined in the YANG module l3-unicast-topology. Here's a rough picture of how this module relates to the other YANG modules, in the figure below 🦋
+-----------------------------+
| +-----------------------+ |
| | ietf-network | |
| +----------^------------+ |
| | |
| +-----------------------+ |
| | ietf-network-topology | |
| +----------+------------+ |
+-------------^---------------+
|
|
+------------^-------------+
| ietf-l3-unicast-topology |
+------------^-------------+
|
|
+-----------^-----------+
| example-ospf-topology |
+-----------------------+
Figure 1: Overall Model StructureThe YANG modules ietf-network and ietf-network-topology work together to define the basic network topology model from [RFC8345]. The module ietf-l3-unicast-topology augments those with extra definitions needed to represent Layer 3 Unicast topologies. And it can itself get augmented by modules with more definitions for specific Layer 3 Unicast topology types, like OSPF and IS-IS 🌈
The ietf-network and ietf-network-topology modules are meant to be used with implementations that support the Network Management Datastore Architecture (NMDA) from [RFC8342]. The modules that augment them work the same way. So that implementations can still use the model when NMDA isn't supported, the document defines companion YANG modules in Appendix A. Those companion modules SHOULD NOT be supported by implementations that already support NMDA 💀
5. Layer 3 Unicast Topology Model Overview ✨
okay so the whole Layer 3 Unicast topology model lives in one YANG module called ietf-l3-unicast-topology 🦋 Here's the structure in a diagram. The notation follows [RFC8340], and to keep things short I left out the notifications from the picture 💅
module: ietf-l3-unicast-topology
augment /nw:networks/nw:network/nw:network-types:
+--rw l3-unicast-topology!
augment /nw:networks/nw:network:
+--rw l3-topology-attributes
+--rw name? string
+--rw flag* l3-flag-type
augment /nw:networks/nw:network/nw:node:
+--rw l3-node-attributes
+--rw name? inet:domain-name
+--rw flag* node-flag-type
+--rw router-id* rt-types:router-id
+--rw prefix* [prefix]
+--rw prefix inet:ip-prefix
+--rw metric? uint32
+--rw flag* prefix-flag-type
augment /nw:networks/nw:network/nt:link:
+--rw l3-link-attributes
+--rw name? string
+--rw flag* link-flag-type
+--rw metric1? uint64
+--rw metric2? uint64
augment /nw:networks/nw:network/nw:node/nt:termination-point:
+--rw l3-termination-point-attributes
+--rw (termination-point-type)?
+--:(ip)
| +--rw ip-address* inet:ip-address
+--:(unnumbered)
| +--rw unnumbered-id? uint32
+--:(interface-name)
+--rw interface-name? stringThe module augments the original ietf-network and ietf-network-topology modules, and here's how 🌸
- A brand new network topology type shows up,
l3-unicast-topology🎀 Its container augments thenetwork-typesin theietf-networkmodule. - Extra topology attributes get added too 💜 They sit in a grouping that augments the
networklist, and they include a name for the topology plus a set of flags (a leaf-list). Every flag type gets its own identity, which is lowkey genius because future modules can add new flags with new identities without anyone having to revise this module 🔥 - Nodes get new data objects by augmenting the
nodelist. That's a set of flags and a list of prefixes. Each prefix carries an IP prefix, a metric, and its own prefix-specific set of flags ✨ - Links (in
ietf-network-topology) get augmented with a link name, another set of flags, and a link metric 🦋 - Termination points (also in
ietf-network-topology) get a choice of IP address, identifier, or name 🧚
Last but not least, the module defines notifications to tell clients about events involving links, nodes, prefixes, and termination points 🔔 Every notification says what kind of event happened, which topology it came from, and which node, link, prefix, or termination point was affected. As a bonus for apps, the notification also includes extra data about the affected node, link, prefix, or termination point 💖 Yes, it makes notifications chunkier than they strictly need to be, but it means clients don't have to go fetching context that might have changed in the meantime. Iconic trade-off, honestly 😭✨
6. Layer 3 Unicast Topology YANG Module ✨
okay bestie, this is where the actual YANG lives 💖 it's giving spec, so read it like a menu. This YANG module makes reference to the following documents: [RFC2863] and [RFC8343]. 🎀
<CODE BEGINS> file "ietf-l3-unicast-topology@2018-02-26.yang"
module ietf-l3-unicast-topology {
yang-version 1.1;
namespace
"urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology";
prefix "l3t";
import ietf-network {
prefix "nw";
}
import ietf-network-topology {
prefix "nt";
}
import ietf-inet-types {
prefix "inet";
}
import ietf-routing-types {
prefix "rt-types";
}
organization
"IETF I2RS (Interface to the Routing System) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/i2rs/>
WG List: <mailto:i2rs@ietf.org>
Editor: Alexander Clemm
<mailto:ludwig@clemm.org>
Editor: Jan Medved
<mailto:jmedved@cisco.com>
Editor: Robert Varga
<mailto:robert.varga@pantheon.tech>
Editor: Xufeng Liu
<mailto:xufeng.liu.ietf@gmail.com>
Editor: Nitin Bahadur
<mailto:nitin_bahadur@yahoo.com>
Editor: Hariharan Ananthakrishnan
<mailto:hari@packetdesign.com>";
description
"This module defines a model for Layer 3 Unicast
topologies.
Copyright (c) 2018 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
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of
RFC 8346; see the RFC itself for full legal notices.";
revision "2018-02-26" {
description
"Initial revision.";
reference
"RFC 8346: A YANG Data Model for Layer 3 Topologies";
}
identity flag-identity {
description "Base type for flags";
}
typedef l3-event-type {
type enumeration {
enum "add" {
description
"A Layer 3 node, link, prefix, or termination point has
been added";
}
enum "remove" {
description
"A Layer 3 node, link, prefix, or termination point has
been removed";
}
enum "update" {
description
"A Layer 3 node, link, prefix, or termination point has
been updated";
}
}
description "Layer 3 event type for notifications";
}
typedef prefix-flag-type {
type identityref {
base "flag-identity";
}
description "Prefix flag attributes";
}
typedef node-flag-type {
type identityref {
base "flag-identity";
}
description "Node flag attributes";
}
typedef link-flag-type {
type identityref {
base "flag-identity";
}
description "Link flag attributes";
}
typedef l3-flag-type {
type identityref {
base "flag-identity";
}
description "L3 flag attributes";
}
grouping l3-prefix-attributes {
description
"L3 prefix attributes";
leaf prefix {
type inet:ip-prefix;
description
"IP prefix value";
}
leaf metric {
type uint32;
description
"Prefix metric";
}
leaf-list flag {
type prefix-flag-type;
description
"Prefix flags";
}
}
grouping l3-unicast-topology-type {
description "Identifies the topology type to be L3 Unicast.";
container l3-unicast-topology {
presence "indicates L3 Unicast topology";
description
"The presence of the container node indicates L3 Unicast
topology";
}
}
grouping l3-topology-attributes {
description "Topology scope attributes";
container l3-topology-attributes {
description "Contains topology attributes";
leaf name {
type string;
description
"Name of the topology";
}
leaf-list flag {
type l3-flag-type;
description
"Topology flags";
}
}
}
grouping l3-node-attributes {
description "L3 node scope attributes";
container l3-node-attributes {
description
"Contains node attributes";
leaf name {
type inet:domain-name;
description
"Node name";
}
leaf-list flag {
type node-flag-type;
description
"Node flags";
}
leaf-list router-id {
type rt-types:router-id;
description
"Router-id for the node";
}
list prefix {
key "prefix";
description
"A list of prefixes along with their attributes";
uses l3-prefix-attributes;
}
}
}
grouping l3-link-attributes {
description
"L3 link scope attributes";
container l3-link-attributes {
description
"Contains link attributes";
leaf name {
type string;
description
"Link Name";
}
leaf-list flag {
type link-flag-type;
description
"Link flags";
}
leaf metric1 {
type uint64;
description
"Link Metric 1";
}
leaf metric2 {
type uint64;
description
"Link Metric 2";
}
}
}
grouping l3-termination-point-attributes {
description "L3 termination point scope attributes";
container l3-termination-point-attributes {
description
"Contains termination point attributes";
choice termination-point-type {
description
"Indicates the termination point type";
case ip {
leaf-list ip-address {
type inet:ip-address;
description
"IPv4 or IPv6 address.";
}
}
case unnumbered {
leaf unnumbered-id {
type uint32;
description
"Unnumbered interface identifier.
The identifier will correspond to the ifIndex value
of the interface, i.e., the ifIndex value of the
ifEntry that represents the interface in
implementations where the Interfaces Group MIB
(RFC 2863) is supported.";
reference
"RFC 2863: The Interfaces Group MIB";
}
}
case interface-name {
leaf interface-name {
type string;
description
"Name of the interface. The name can (but does not
have to) correspond to an interface reference of a
containing node's interface, i.e., the path name of a
corresponding interface data node on the containing
node reminiscent of data type interface-ref defined
in RFC 8343. It should be noted that data type
interface-ref of RFC 8343 cannot be used directly,
as this data type is used to reference an interface
in a datastore of a single node in the network, not
to uniquely reference interfaces across a network.";
reference
"RFC 8343: A YANG Data Model for Interface Management";
}
}
}
}
}
augment "/nw:networks/nw:network/nw:network-types" {
description
"Introduces new network type for L3 Unicast topology";
uses l3-unicast-topology-type;
}
augment "/nw:networks/nw:network" {
when "nw:network-types/l3t:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description
"L3 Unicast for the network as a whole";
uses l3-topology-attributes;
}
augment "/nw:networks/nw:network/nw:node" {
when "../nw:network-types/l3t:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description
"L3 Unicast node-level attributes ";
uses l3-node-attributes;
}
augment "/nw:networks/nw:network/nt:link" {
when "../nw:network-types/l3t:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description
"Augments topology link attributes";
uses l3-link-attributes;
}
augment "/nw:networks/nw:network/nw:node/"
+"nt:termination-point" {
when "../../nw:network-types/l3t:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description "Augments topology termination point configuration";
uses l3-termination-point-attributes;
}
notification l3-node-event {
description
"Notification event for L3 node";
leaf l3-event-type {
type l3-event-type;
description
"Event type";
}
uses nw:node-ref;
uses l3-unicast-topology-type;
uses l3-node-attributes;
}
notification l3-link-event {
description
"Notification event for L3 link";
leaf l3-event-type {
type l3-event-type;
description
"Event type";
}
uses nt:link-ref;
uses l3-unicast-topology-type;
uses l3-link-attributes;
}
notification l3-prefix-event {
description
"Notification event for L3 prefix";
leaf l3-event-type {
type l3-event-type;
description
"Event type";
}
uses nw:node-ref;
uses l3-unicast-topology-type;
container prefix {
description
"Contains L3 prefix attributes";
uses l3-prefix-attributes;
}
}
notification termination-point-event {
description
"Notification event for L3 termination point";
leaf l3-event-type {
type l3-event-type;
description
"Event type";
}
uses nt:tp-ref;
uses l3-unicast-topology-type;
uses l3-termination-point-attributes;
}
}
<CODE ENDS>7. Interactions with Other YANG Modules ✨
okay bestie, remember Section 4? this model is built on top of the modules in [RFC8345] and it augments them 💅 specifically, "ietf-l3-unicast-topology" augments "ietf-network" and "ietf-network-topology". it also borrows some data types from [RFC6991]. main character reuse energy 🦋
the model is protocol-independent, which means it doesn't care which routing protocol you run 🌸 it's totally separate from and not linked with the stuff that configures routing protocols or routing info, like "ietf-routing" [RFC8022] and "ietf-rib-extension" [YANG-RIB]. it's giving "I'm my own thing" 💜 the only thing it imports from outside is one type definition from "ietf-routing-types" [RFC8294] 🎀
it also complies with the requirements for ephemeral state in [RFC8242] 🫶 for ephemeral topology data that the server provides, the process in charge of keeping topology info loads stuff from the routing process (like OSPF) straight into the data model, with no configuration datastore involved. so clean ✨
8. IANA Considerations 🧚
okay the registry part! this document registers two namespace URIs in the "IETF XML Registry" [RFC3688] 📝 the registrant contact is The IESG, and XML is N/A because these are XML namespaces.
URI: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.then it registers two YANG modules in the "YANG Module Names" registry [RFC6020] 💜 these are the exact entries:
Name: ietf-l3-unicast-topology
Namespace: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology
Prefix: l3t
Reference: RFC 8346
Name: ietf-l3-unicast-topology-state
Namespace: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state
Prefix: l3t-s
Reference: RFC 83469. Security Considerations 🔐
okay this part is SERIOUS, so listen up 🙈 the YANG modules in this document define a schema for data that's meant to be reached through network management protocols like NETCONF [RFC6241] or RESTCONF [RFC8040]. the lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. the lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC5246].
the NETCONF access control model [RFC8341] gives you the tools to restrict particular NETCONF or RESTCONF users to a preconfigured subset of all the available protocol operations and content. bouncer energy 🚪
in general, Layer 3 Unicast topologies are system-controlled and give you ephemeral topology info 🦋 in an NMDA-compliant server, they only live in <operational>, which is read-only for clients, so they're less vulnerable. that said, the YANG modules do in principle allow info to be configurable 👀
a bunch of data nodes in these modules are writable, creatable, and deletable (that's config true, which is the default). they could be sensitive or vulnerable in some network environments. writing to them without proper protection (think edit-config) can seriously mess with network operations 💀 these are the subtrees and data nodes, and how sensitive or vulnerable they are, in the "ietf-l3-unicast-topology" module:
l3-topology-attributes: a malicious client could try to sabotage the config of any of the contained attributes, i.e., the name or the flag data nodes.l3-node-attributes: a malicious client could try to sabotage the config of important node attributes, like the router-id or node prefix.l3-link-attributes: a malicious client could try to sabotage the config of important link attributes, like the name, flag, and metrics of the link.l3-termination-point-attributes: a malicious client could try to sabotage the config info of a termination point, like the termination point's IP address and interface name.
10. References 📚
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC2328] Moy, J., "OSPF Version 2", STD 54, RFC 2328, DOI 10.17487/RFC2328, April 1998, <https://www.rfc-editor.org/info/rfc2328>.
[RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB", RFC 2863, DOI 10.17487/RFC2863, June 2000, <https://www.rfc-editor.org/info/rfc2863>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <https://www.rfc-editor.org/info/rfc5246>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/info/rfc6991>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8294] Liu, X., Qu, Y., Lindem, A., Hopps, C., and L. Berger, "Common YANG Data Types for the Routing Area", RFC 8294, DOI 10.17487/RFC8294, December 2017, <https://www.rfc-editor.org/info/rfc8294>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.
[RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., Ananthakrishnan, H., and X. Liu, "A YANG Data Model for Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 2018, <https://www.rfc-editor.org/info/rfc8345>.
10.2. Informative References
[RFC8022] Lhotka, L. and A. Lindem, "A YANG Data Model for Routing Management", RFC 8022, DOI 10.17487/RFC8022, November 2016, <https://www.rfc-editor.org/info/rfc8022>.
[RFC8242] Haas, J. and S. Hares, "Interface to the Routing System (I2RS) Ephemeral State Requirements", RFC 8242, DOI 10.17487/RFC8242, September 2017, <https://www.rfc-editor.org/info/rfc8242>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>.
[RFC8343] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>.
[USECASE-REQS] Hares, S. and M. Chen, "Summary of I2RS Use Case Requirements", Work in Progress, draft-ietf-i2rs-usecase-reqs-summary-03, November 2016.
[YANG-RIB] Lindem, A. and Y. Qu, "RIB YANG Data Model", Work in Progress, draft-acee-rtgwg-yang-rib-extend-06, January 2018.
[YANG-TE] Liu, X., Bryskin, I., Beeram, V., Saad, T., Shah, H., and O. Gonzalez de Dios, "YANG Data Model for Traffic Engineering (TE) Topologies", Work in Progress, draft-ietf-teas-yang-te-topo-15, February 2018.
Appendix A. Companion YANG Data Model for Implementations Not Compliant with NMDA ✨
okay so this appendix is about the people who aren't on the NMDA train yet 🚂💨. The YANG module "ietf-l3-unicast-topology" in this document augments two modules from [RFC8345]: "ietf-network" and "ietf-network-topology". Those two were designed to be used with implementations that support the Network Management Datastore Architecture (NMDA) from [RFC8342] 💅. So that folks without NMDA can still use the model, [RFC8345] gives us two companion modules, "ietf-network-state" and "ietf-network-topology-state", which are state models of networks and network topologies.
So, to use the Layer 3 topology model from this document with non-NMDA implementations, we need a companion module too 🎀. That's "ietf-l3-unicast-topology-state". It mirrors "ietf-l3-unicast-topology", but it augments "ietf-network-state" and "ietf-network-topology-state" (instead of "ietf-network" and "ietf-network-topology"), and all of its data nodes are non-configurable 🔒.
Same energy applies to any module that augments "ietf-l3-unicast-topology", like the example module in Appendix B (example-ospf-topology) 🦋. Non-NMDA implementations will need their own non-configurable companion modules for state info, and those augment "ietf-l3-unicast-topology-state" instead. There are no companion modules for the Appendix B example, since it's just an example 🙈.
Like "ietf-network-state" and "ietf-network-topology-state", "ietf-l3-unicast-topology" SHOULD NOT be supported by implementations that support NMDA. That's why it lives in an appendix 💜.
Here's the module definition. The structure mirrors its underlying module, so the YANG tree isn't drawn separately 🧚.
<CODE BEGINS> file "ietf-l3-unicast-topology-state@2018-02-26.yang"
module ietf-l3-unicast-topology-state {
yang-version 1.1;
namespace
"urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state";
prefix "l3t-s";
import ietf-network-state {
prefix "nw-s";
}
import ietf-network-topology-state {
prefix "nt-s";
}
import ietf-l3-unicast-topology {
prefix "l3t";
}
organization
"IETF I2RS (Interface to the Routing System) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/i2rs/>
WG List: <mailto:i2rs@ietf.org>
Editor: Alexander Clemm
<mailto:ludwig@clemm.org>
Editor: Jan Medved
<mailto:jmedved@cisco.com>
Editor: Robert Varga
<mailto:robert.varga@pantheon.tech>
Editor: Xufeng Liu
<mailto:xufeng.liu.ietf@gmail.com>
Editor: Nitin Bahadur
<mailto:nitin_bahadur@yahoo.com>
Editor: Hariharan Ananthakrishnan
<mailto:hari@packetdesign.com>";
description
"This module defines a model for Layer 3 Unicast topology
state, representing topology that either is learned or
results from applying topology that has been configured per
the 'ietf-l3-unicast-topology' model, mirroring the
corresponding data nodes in this model.
This model mirrors 'ietf-l3-unicast-topology' but contains only
read-only state data. The model is not needed when the
underlying implementation infrastructure supports the Network
Management Datastore Architecture (NMDA).
Copyright (c) 2018 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
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8346;
see the RFC itself for full legal notices.";
revision "2018-02-26" {
description
"Initial revision.";
reference
"RFC 8346: A YANG Data Model for Layer 3 Topologies";
}
augment "/nw-s:networks/nw-s:network/nw-s:network-types" {
description
"Introduce new network type for L3 Unicast topology";
uses l3t:l3-unicast-topology-type;
}
augment "/nw-s:networks/nw-s:network" {
when "nw-s:network-types/l3t-s:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description
"L3 Unicast for the network as a whole";
uses l3t:l3-topology-attributes;
}
augment "/nw-s:networks/nw-s:network/nw-s:node" {
when "../nw-s:network-types/l3t-s:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description
"L3 Unicast node-level attributes ";
uses l3t:l3-node-attributes;
}
augment "/nw-s:networks/nw-s:network/nt-s:link" {
when "../nw-s:network-types/l3t-s:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description
"Augments topology link attributes";
uses l3t:l3-link-attributes;
}
augment "/nw-s:networks/nw-s:network/nw-s:node/"
+"nt-s:termination-point" {
when "../../nw-s:network-types/l3t-s:l3-unicast-topology" {
description
"Augmentation parameters apply only for networks with
L3 Unicast topology";
}
description "Augments topology termination point configuration";
uses l3t:l3-termination-point-attributes;
}
notification l3-node-event {
description
"Notification event for L3 node";
leaf l3-event-type {
type l3t:l3-event-type;
description
"Event type";
}
uses nw-s:node-ref;
uses l3t:l3-unicast-topology-type;
uses l3t:l3-node-attributes;
}
notification l3-link-event {
description
"Notification event for L3 link";
leaf l3-event-type {
type l3t:l3-event-type;
description
"Event type";
}
uses nt-s:link-ref;
uses l3t:l3-unicast-topology-type;
uses l3t:l3-link-attributes;
}
notification l3-prefix-event {
description
"Notification event for L3 prefix";
leaf l3-event-type {
type l3t:l3-event-type;
description
"Event type";
}
uses nw-s:node-ref;
uses l3t:l3-unicast-topology-type;
container prefix {
description
"Contains L3 prefix attributes";
uses l3t:l3-prefix-attributes;
}
}
notification termination-point-event {
description
"Notification event for L3 termination point";
leaf l3-event-type {
type l3t:l3-event-type;
description
"Event type";
}
uses nt-s:tp-ref;
uses l3t:l3-unicast-topology-type;
uses l3t:l3-termination-point-attributes;
}
}<CODE ENDS>
Appendix B. Extending the Model 🌈
okay bestie, the model can be extended for specific Layer 3 Unicast types 👑. Examples include OSPF and IS-IS topologies. This appendix introduces a YANG module that defines a simple topology model for OSPF. It's meant as an example of how the general topology model can be refined across multiple levels 💖. It is not a full-fledged OSPF topology model, and a real one may be more comprehensive and refined than the one described here 💅.
B.1. Example OSPF Topology 🦋
B.1.1. Model Overview 🌸
The following model shows how the Layer 3 Unicast topology model can be extended to cover OSPF topologies, lowkey iconic ✨. A set of augmentations lives in a separate YANG module, "example-ospf-topology", whose structure is in the diagram below. As before, the notation syntax follows [RFC8340]. One of the lines has been wrapped to stay within the 72-character line limitation of RFCs, so don't be confused by it 🙈.
module: example-ospf-topology
augment /nw:networks/nw:network/nw:network-types/
l3t:l3-unicast-topology:
+--rw ospf!
augment /nw:networks/nw:network/l3t:l3-topology-attributes:
+--rw ospf-topology-attributes
+--rw area-id? area-id-type
augment /nw:networks/nw:network/nw:node/l3t:l3-node-attributes:
+--rw ospf-node-attributes
+--rw (router-type)?
| +--:(abr)
| | +--rw abr? empty
| +--:(asbr)
| | +--rw asbr? empty
| +--:(internal)
| | +--rw internal? empty
| +--:(pseudonode)
| +--rw pseudonode? empty
+--rw dr-interface-id? uint32
augment /nw:networks/nw:network/nt:link/l3t:l3-link-attributes:
+--rw ospf-link-attributes
augment /l3t:l3-node-event:
+---- ospf!
+---- ospf-node-attributes
+---- (router-type)?
| +--:(abr)
| | +---- abr? empty
| +--:(asbr)
| | +---- asbr? empty
| +--:(internal)
| | +---- internal? empty
| +--:(pseudonode)
| +---- pseudonode? empty
+---- dr-interface-id? uint32
augment /l3t:l3-link-event:
+---- ospf!
+---- ospf-link-attributesThe module augments "ietf-l3-unicast-topology" like this 💜:
- A new topology type for an OSPF topology is introduced 🍓.
- Additional topology attributes are defined in a new grouping that augments l3-topology-attributes of the "ietf-l3-unicast-topology" module. The attributes include an OSPF area-id identifying the OSPF area 🧚.
- Additional data objects for nodes are introduced by augmenting the l3-node-attributes of the "ietf-l3-unicast-topology" module. New objects include router-type and dr-interface-id for pseudonodes ✨.
- Links are augmented with OSPF link attributes 🔥.
On top of that, the module extends notifications for events about Layer 3 nodes and links with OSPF attributes 📣.
Heads up: the model defined here represents topology and is intended as an example. It does not define how to configure OSPF routers or interfaces 🙅♀️.
B.1.2. OSPF Topology YANG Module ✨
okay so here's the actual OSPF Topology YANG module 🦋 heads up that it's just an example of how the Layer 3 Unicast topology model can be extended to cover OSPF topologies. it is not normative, so the module isn't wrapped in <CODE BEGINS> and <CODE ENDS> tags. no stress, just vibes 💅
file "example-ospf-topology@2017-12-16.yang"
module example-ospf-topology {
yang-version 1.1;
namespace "urn:example:example-ospf-topology";
prefix "ex-ospft";
import ietf-yang-types {
prefix "yang";
}
import ietf-network {
prefix "nw";
}
import ietf-network-topology {
prefix "nt";
}
import ietf-l3-unicast-topology {
prefix "l3t";
}
description
"This module is intended as an example for how the
Layer 3 Unicast topology model can be extended to cover
OSPF topologies.";
typedef area-id-type {
type yang:dotted-quad;
description
"Area ID type.";
}
grouping ospf-topology-type {
description
"Identifies the OSPF topology type.";
container ospf {
presence "indicates OSPF Topology";
description
"Its presence identifies the OSPF topology type.";
}
}
augment "/nw:networks/nw:network/nw:network-types/"
+ "l3t:l3-unicast-topology" {
description
"Defines the OSPF topology type.";
uses ospf-topology-type;
}
augment "/nw:networks/nw:network/l3t:l3-topology-attributes" {
when "../nw:network-types/l3t:l3-unicast-topology/" +
"ex-ospft:ospf" {
description
"Augments only for OSPF topology";
}
description
"Augments topology configuration";
container ospf-topology-attributes {
description
"Contains topology attributes";
leaf area-id {
type area-id-type;
description
"OSPF area ID";
}
}
}
augment "/nw:networks/nw:network/nw:node/l3t:l3-node-attributes" {
when "../../nw:network-types/l3t:l3-unicast-topology/" +
"ex-ospft:ospf" {
description
"Augments only for OSPF topology";
}
description
"Augments node configuration";
uses ospf-node-attributes;
}
augment "/nw:networks/nw:network/nt:link/l3t:l3-link-attributes" {
when "../../nw:network-types/l3t:l3-unicast-topology/" +
"ex-ospft:ospf" {
description
"Augments only for OSPF topology";
}
description
"Augments link configuration";
uses ospf-link-attributes;
}
grouping ospf-node-attributes {
description
"OSPF node scope attributes";
container ospf-node-attributes {
description
"Contains node attributes";
choice router-type {
description
"Indicates router type";
case abr {
leaf abr {
type empty;
description
"The node is ABR";
}
}
case asbr {
leaf asbr {
type empty;
description
"The node is ASBR";
}
}
case internal {
leaf internal {
type empty;
description
"The node is internal";
}
}
case pseudonode {
leaf pseudonode {
type empty;
description
"The node is pseudonode";
}
}
}
leaf dr-interface-id {
when "../pseudonode" {
description
"Valid only for pseudonode";
}
type uint32;
default "0";
description
"For pseudonodes, DR interface-id";
}
}
}
grouping ospf-link-attributes {
description
"OSPF link scope attributes";
container ospf-link-attributes {
description
"Contains OSPF link attributes";
}
} // ospf-link-attributes
augment "/l3t:l3-node-event" {
description
"OSPF node event";
uses ospf-topology-type;
uses ospf-node-attributes;
}
augment "/l3t:l3-link-event" {
description
"OSPF link event";
uses ospf-topology-type;
uses ospf-link-attributes;
}
}Appendix C. An Example 🎀
Okay bestie, this is the part where we see it all come together! 🧚 This section has an example of an instance data tree in JSON encoding [RFC7951] ✨. It instantiates ietf-l3-unicast-topology for the topology in the diagram below. There are three nodes: D1, D2, and D3 💖. D1 has three termination points: 1-0-1, 1-2-1, and 1-3-1. D2 has three too: 2-1-1, 2-0-1, and 2-3-1. D3 has two: 3-1-1 and 3-2-1 🌸. On top of that there are six links, two between each pair of nodes, with one going in each direction. It's giving full mesh energy 💅
+------------+ +------------+
| D1 | | D2 |
/-\ /-\ /-\ /-\
| | 1-0-1 | |---------------->| | 2-1-1 | |
| | 1-2-1 | |<----------------| | 2-0-1 | |
\-/ 1-3-1 \-/ \-/ 2-3-1 \-/
| /----\ | | /----\ |
+---| |---+ +---| |---+
\----/ \----/
A | A |
| | | |
| | | |
| | +------------+ | |
| | | D3 | | |
| | /-\ /-\ | |
| +----->| | 3-1-1 | |-------+ |
+---------| | 3-2-1 | |<---------+
\-/ \-/
| |
+------------+Figure 2: A Network Topology Example
The corresponding instance data tree is below 👑 Heads up, some lines got wrapped so they fit the 72-character line limit that RFCs have 🙈
{
"ietf-network:networks": {
"network": [
{
"network-types": {
"ietf-l3-unicast-topology:l3-unicast-topology": {}
},
"network-id": "l3-topo-example",
"node": [
{
"node-id": "D1",
"termination-point": [
{
"tp-id": "1-0-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 101
}
},
{
"tp-id": "1-2-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 121
}
},
{
"tp-id": "1-3-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 131
}
}
],
"ietf-l3-unicast-topology:l3-node-attributes": {
"router-id": ["203.0.113.1"]
}
},
{
"node-id": "D2",
"termination-point": [
{
"tp-id": "2-0-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 201
}
},
{
"tp-id": "2-1-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 211
}
},
{
"tp-id": "2-3-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 231
}
}
],
"ietf-l3-unicast-topology:l3-node-attributes": {
"router-id": ["203.0.113.2"]
}
},
{
"node-id": "D3",
"termination-point": [
{
"tp-id": "3-1-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 311
}
},
{
"tp-id": "3-2-1",
"ietf-l3-unicast-topology:
l3-termination-point-attributes": {
"unnumbered-id:": 321
}
}
],
"ietf-l3-unicast-topology:l3-node-attributes": {
"router-id": ["203.0.113.3"]
}
}
],
"ietf-network-topology:link": [
{
"link-id": "D1,1-2-1,D2,2-1-1",
"source": {
"source-node": "D1",
"source-tp": "1-2-1"
}
"destination": {
"dest-node": "D2",
"dest-tp": "2-1-1"
},
"ietf-l3-unicast-topology:l3-link-attributes": {
"metric1": "100"
}
},
{
"link-id": "D2,2-1-1,D1,1-2-1",
"source": {
"source-node": "D2",
"source-tp": "2-1-1"
}
"destination": {
"dest-node": "D1",
"dest-tp": "1-2-1"
},
"ietf-l3-unicast-topology:l3-link-attributes": {
"metric1": "100"
}
},
{
"link-id": "D1,1-3-1,D3,3-1-1",
"source": {
"source-node": "D1",
"source-tp": "1-3-1"
}
"destination": {
"dest-node": "D3",
"dest-tp": "3-1-1"
},
"ietf-l3-unicast-topology:l3-link-attributes": {
"metric1": "100"
}
},
{
"link-id": "D3,3-1-1,D1,1-3-1",
"source": {
"source-node": "D3",
"source-tp": "3-1-1"
}
"destination": {
"dest-node": "D1",
"dest-tp": "1-3-1"
},
"ietf-l3-unicast-topology:l3-link-attributes": {
"metric1": "100"
}
},
{
"link-id": "D2,2-3-1,D3,3-2-1",
"source": {
"source-node": "D2",
"source-tp": "2-3-1"
}
"destination": {
"dest-node": "D3",
"dest-tp": "3-2-1"
},
"ietf-l3-unicast-topology:l3-link-attributes": {
"metric1": "100"
}
},
{
"link-id": "D3,3-2-1,D2,2-3-1",
"source": {
"source-node": "D3",
"source-tp": "3-2-1"
}
"destination": {
"dest-node": "D2",
"dest-tp": "2-3-1"
},
"ietf-l3-unicast-topology:l3-link-attributes": {
"metric1": "100"
}
}
]
}
]
}
}Figure 3: Instance Data Tree
Acknowledgments 🫶
We wish to acknowledge the helpful contributions, comments, and suggestions that were received from Alia Atlas, Andy Bierman, Benoit Claise, Joel Halpern, Susan Hares, Ladislav Lhotka, Carl Moberg, Carlos Pignataro, Juergen Schoenwaelder, Michal Vasco, and Kent Watsen 💜
Contributors 💅
The model presented in this document was contributed to by more people than can be listed on the author list ✨ Additional contributors include:
- Vishnu Pavan Beeram, Juniper
- Igor Bryskin, Huawei
- Ken Gray, Cisco
- Aihua Guo, Huawei
- Tom Nadeau, Brocade
- Tony Tkacik
- Aleksandr Zhdankin, Cisco
Authors' Addresses 🦋
Alexander Clemm Huawei USA - Futurewei Technologies Inc. Santa Clara, CA United States of America
Email: ludwig@clemm.org, alexander.clemm@huawei.com
Jan Medved Cisco
Email: jmedved@cisco.com
Robert Varga Pantheon Technologies SRO
Email: robert.varga@pantheon.tech
Xufeng Liu Jabil
Email: xufeng.liu.ietf@gmail.com
Hariharan Ananthakrishnan Packet Design
Email: hari@packetdesign.com
Nitin Bahadur Bracket Computing
Email: nitin_bahadur@yahoo.com
📦 where this page comes from
- ietf: rfc8346 2018-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms