idnits 2.17.1 draft-ietf-i2rs-yang-network-topo-18.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 15, 2017) is 2353 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Z' is mentioned on line 225, but not defined == Missing Reference: 'Y5' is mentioned on line 251, but not defined == Missing Reference: 'Z5' is mentioned on line 251, but not defined == Missing Reference: 'Z3' is mentioned on line 251, but not defined == Missing Reference: 'Y4' is mentioned on line 255, but not defined == Missing Reference: 'Y1' is mentioned on line 255, but not defined == Missing Reference: 'Z2' is mentioned on line 255, but not defined == Missing Reference: 'X5' is mentioned on line 264, but not defined == Missing Reference: 'D1' is mentioned on line 732, but not defined == Missing Reference: 'D2' is mentioned on line 732, but not defined == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-02 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-16) exists of draft-ietf-i2rs-yang-l3-topology-11 == Outdated reference: A later version (-25) exists of draft-ietf-netconf-yang-push-10 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) -- Obsolete informational reference (is this intentional?): RFC 8022 (Obsoleted by RFC 8349) Summary: 2 errors (**), 0 flaws (~~), 14 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Clemm 3 Internet-Draft Huawei 4 Intended status: Standards Track J. Medved 5 Expires: May 19, 2018 Cisco 6 R. Varga 7 Pantheon Technologies SRO 8 N. Bahadur 9 Bracket Computing 10 H. Ananthakrishnan 11 Packet Design 12 X. Liu 13 Jabil 14 November 15, 2017 16 A Data Model for Network Topologies 17 draft-ietf-i2rs-yang-network-topo-18.txt 19 Abstract 21 This document defines an abstract (generic) YANG data model for 22 network/service topologies and inventories. The data model serves as 23 a base model which is augmented with technology-specific details in 24 other, more specific topology and inventory data models. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on May 19, 2018. 43 Copyright Notice 45 Copyright (c) 2017 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 3. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 7 63 4. Model Structure Details . . . . . . . . . . . . . . . . . . . 8 64 4.1. Base Network Model . . . . . . . . . . . . . . . . . . . 8 65 4.2. Base Network Topology Data Model . . . . . . . . . . . . 10 66 4.3. Extending the data model . . . . . . . . . . . . . . . . 12 67 4.4. Discussion and selected design decisions . . . . . . . . 12 68 4.4.1. Container structure . . . . . . . . . . . . . . . . . 12 69 4.4.2. Underlay hierarchies and mappings . . . . . . . . . . 13 70 4.4.3. Dealing with changes in underlay networks . . . . . . 13 71 4.4.4. Use of groupings . . . . . . . . . . . . . . . . . . 14 72 4.4.5. Cardinality and directionality of links . . . . . . . 14 73 4.4.6. Multihoming and link aggregation . . . . . . . . . . 15 74 4.4.7. Mapping redundancy . . . . . . . . . . . . . . . . . 15 75 4.4.8. Typing . . . . . . . . . . . . . . . . . . . . . . . 15 76 4.4.9. Representing the same device in multiple networks . . 15 77 4.4.10. Supporting client-configured and system-controlled 78 network topology . . . . . . . . . . . . . . . . . . 16 79 4.4.11. Identifiers of string or URI type . . . . . . . . . . 17 80 5. Interactions with Other YANG Modules . . . . . . . . . . . . 18 81 6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 18 82 6.1. Defining the Abstract Network: ietf-network.yang . . . . 18 83 6.2. Creating Abstract Network Topology: ietf-network- 84 topology.yang . . . . . . . . . . . . . . . . . . . . . . 23 85 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 86 8. Security Considerations . . . . . . . . . . . . . . . . . . . 30 87 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 32 88 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 32 89 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 90 11.1. Normative References . . . . . . . . . . . . . . . . . . 32 91 11.2. Informative References . . . . . . . . . . . . . . . . . 33 92 Appendix A. Model Use Cases . . . . . . . . . . . . . . . . . . 35 93 A.1. Fetching Topology from a Network Element . . . . . . . . 35 94 A.2. Modifying TE Topology Imported from an Optical Controller 35 95 A.3. Annotating Topology for Local Computation . . . . . . . . 36 96 A.4. SDN Controller-Based Configuration of Overlays on Top of 97 Underlays . . . . . . . . . . . . . . . . . . . . . . . . 36 98 Appendix B. Companion YANG models for non-NMDA compliant 99 implementations . . . . . . . . . . . . . . . . . . 36 100 B.1. YANG Model for Network State . . . . . . . . . . . . . . 37 101 B.2. YANG Data Model for Network Topology State . . . . . . . 41 102 Appendix C. An Example . . . . . . . . . . . . . . . . . . . . . 47 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 105 1. Introduction 107 This document introduces an abstract (base) YANG [RFC7950] data model 108 [RFC3444] to represent networks and topologies. The data model is 109 divided into two parts. The first part of the data model defines a 110 network data model that enables the definition of network hierarchies 111 (i.e. network stacks of networks that are layered on top of each 112 other) and to maintain an inventory of nodes contained in a network. 113 The second part of the data model augments the basic network data 114 model with information to describe topology information. 115 Specifically, it adds the concepts of links and termination points to 116 describe how nodes in a network are connected to each other. 117 Moreover the data model introduces vertical layering relationships 118 between networks that can be augmented to cover both network 119 inventories and network/service topologies. 121 While it would be possible to combine both parts into a single data 122 model, the separation facilitates integration of network topology and 123 network inventory data models, because it allows to augment network 124 inventory information separately and without concern for topology 125 into the network data model. 127 The data model can be augmented to describe the specifics of 128 particular types of networks and topologies. For example, an 129 augmenting data model can provide network node information with 130 attributes that are specific to a particular network type. Examples 131 of augmenting models include data models for Layer 2 network 132 topologies, Layer 3 network topologies, such as Unicast IGP, IS-IS 133 [RFC1195] and OSPF [RFC2328], traffic engineering (TE) data 134 [RFC3209], or any of the variety of transport and service topologies. 135 Information specific to particular network types will be captured in 136 separate, technology-specific data models. 138 The basic data models introduced in this document are generic in 139 nature and can be applied to many network and service topologies and 140 inventories. The data models allow applications to operate on an 141 inventory or topology of any network at a generic level, where the 142 specifics of particular inventory/topology types are not required. 143 At the same time, where data specific to a network type does comes 144 into play and the data model is augmented, the instantiated data 145 still adheres to the same structure and is represented in a 146 consistent fashion. This also facilitates the representation of 147 network hierarchies and dependencies between different network 148 components and network types. 150 The abstract (base) network YANG module introduced in this document, 151 entitled "ietf-network.yang", contains a list of abstract network 152 nodes and defines the concept of network hierarchy (network stack). 153 The abstract network node can be augmented in inventory and topology 154 data models with inventory and topology specific attributes. Network 155 hierarchy (stack) allows any given network to have one or more 156 "supporting networks". The relationship of the base network data 157 model, the inventory data models and the topology data models is 158 shown in the following figure (dotted lines in the figure denote 159 possible augmentations to models defined in this document). 161 +------------------------+ 162 | | 163 | Abstract Network Model | 164 | | 165 +------------------------+ 166 | 167 +-------+-------+ 168 | | 169 V V 170 +------------+ .............. 171 | Abstract | : Inventory : 172 | Topology | : Model(s) : 173 | Model | : : 174 +------------+ '''''''''''''' 175 | 176 +-------------+-------------+-------------+ 177 | | | | 178 V V V V 179 ............ ............ ............ ............ 180 : L1 : : L2 : : L3 : : Service : 181 : Topology : : Topology : : Topology : : Topology : 182 : Model : : Model : : Model : : Model : 183 '''''''''''' '''''''''''' '''''''''''' '''''''''''' 185 Figure 1: The network data model structure 187 The network-topology YANG module introduced in this document, 188 entitled "ietf-network-topology.yang", defines a generic topology 189 data model at its most general level of abstraction. The module 190 defines a topology graph and components from which it is composed: 191 nodes, edges and termination points. Nodes (from the ietf- 192 network.yang module) represent graph vertices and links represent 193 graph edges. Nodes also contain termination points that anchor the 194 links. A network can contain multiple topologies, for example 195 topologies at different layers and overlay topologies. The data 196 model therefore allows to capture relationships between topologies, 197 as well as dependencies between nodes and termination points across 198 topologies. An example of a topology stack is shown in the following 199 figure. 201 +---------------------------------------+ 202 / _[X1]_ "Service" / 203 / _/ : \_ / 204 / _/ : \_ / 205 / _/ : \_ / 206 / / : \ / 207 / [X2]__________________[X3] / 208 +---------:--------------:------:-------+ 209 : : : 210 +----:--------------:----:--------------+ 211 / : : : "L3" / 212 / : : : / 213 / : : : / 214 / [Y1]_____________[Y2] / 215 / * * * / 216 / * * * / 217 +--------------*-------------*--*-------+ 218 * * * 219 +--------*----------*----*--------------+ 220 / [Z1]_______________[Z1] "Optical" / 221 / \_ * _/ / 222 / \_ * _/ / 223 / \_ * _/ / 224 / \ * / / 225 / [Z] / 226 +---------------------------------------+ 228 Figure 2: Topology hierarchy (stack) example 230 The figure shows three topology levels. At top, the "Service" 231 topology shows relationships between service entities, such as 232 service functions in a service chain. The "L3" topology shows 233 network elements at Layer 3 (IP) and the "Optical" topology shows 234 network elements at Layer 1. Service functions in the "Service" 235 topology are mapped onto network elements in the "L3" topology, which 236 in turn are mapped onto network elements in the "Optical" topology. 237 The figure shows two Service Functions (X1 and X3) mapping onto a 238 single L3 network element (Y2); this could happen, for example, if 239 two service functions reside in the same VM (or server) and share the 240 same set of network interfaces. The figure shows a single "L3" 241 network element (Y2) mapped onto multiple "Optical" network elements 242 (Z and Z1). This could happen, for example, if a single IP router 243 attaches to multiple Reconfigurable Optical Add/Drop Multiplexers 244 (ROADMs) in the optical domain. 246 Another example of a service topology stack is shown in the following 247 figure. 249 VPN1 VPN2 250 +---------------------+ +---------------------+ 251 / [Y5]... / / [Z5]______[Z3] / 252 / / \ : / / : \_ / : / 253 / / \ : / / : \_ / : / 254 / / \ : / / : \ / : / 255 / [Y4]____[Y1] : / / : [Z2] : / 256 +------:-------:---:--+ +---:---------:-----:-+ 257 : : : : : : 258 : : : : : : 259 : +-------:---:-----:------------:-----:-----+ 260 : / [X1]__:___:___________[X2] : / 261 :/ / \_ : : _____/ / : / 262 : / \_ : _____/ / : / 263 /: / \: / / : / 264 / : / [X5] / : / 265 / : / __/ \__ / : / 266 / : / ___/ \__ / : / 267 / : / ___/ \ / : / 268 / [X4]__________________[X3]..: / 269 +------------------------------------------+ 270 L3 Topology 272 Figure 3: Topology hierarchy (stack) example 274 The figure shows two VPN service topologies (VPN1 and VPN2) 275 instantiated over a common L3 topology. Each VPN service topology is 276 mapped onto a subset of nodes from the common L3 topology. 278 There are multiple applications for such a data model. For example, 279 within the context of I2RS, nodes within the network can use the data 280 model to capture their understanding of the overall network topology 281 and expose it to a network controller. A network controller can then 282 use the instantiated topology data to compare and reconcile its own 283 view of the network topology with that of the network elements that 284 it controls. Alternatively, nodes within the network could propagate 285 this understanding to compare and reconcile this understanding either 286 among themselves or with help of a controller. Beyond the network 287 element and the immediate context of I2RS itself, a network 288 controller might even use the data model to represent its view of the 289 topology that it controls and expose it to applications north of 290 itself. Further use cases that the data model can be applied to are 291 described in [I-D.draft-ietf-i2rs-usecase-reqs-summary]. 293 In this data model, a network is categorized as either system 294 controlled or not. If a network is system controlled, then it is 295 automatically populated by the server and represents dynamically 296 learned information that can be read from the operational datastore. 297 The data model can also be used to create or modify network 298 topologies such as might be associated with an inventory or with an 299 overlay network. Such a network is not system controlled but 300 configured by a client. 302 The data model allows a network to refer to a supporting-network, 303 supporting-nodes, supporting-links, etc. The data model also allows 304 to layer a network that is configured on top of one that is system 305 controlled. This permits the configuration of overlay networks on 306 top of networks that are discovered. Specifically, this data model 307 is structured to support being implemented as part of the ephemeral 308 datastore [I-D.draft-ietf-netmod-revised-datastores], defined as 309 requirement Ephemeral-REQ-03 in 310 [I-D.draft-ietf-i2rs-ephemeral-state]. This allows network topology 311 data that is written, i.e. configured by a client and not system 312 controlled, to refer to a dynamically learned data that is controlled 313 by the system, not configured by a client. A simple use case might 314 involve creating an overlay network that is supported by the 315 dynamically discovered IP routed network topology. When an 316 implementation places written data for this data model in the 317 ephemeral data store, then such a network MAY refer to another 318 network that is system controlled. 320 2. Key Words 322 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 323 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 324 "OPTIONAL" in this document are to be interpreted as described in BCP 325 14 [RFC2119] [RFC8174] when, and only when, they appear in all 326 capitals, as shown here. 328 3. Definitions and Acronyms 330 Datastore: A conceptual place to store and access information. A 331 datastore might be implemented, for example, using files, a database, 332 flash memory locations, or combinations thereof. A datastore maps to 333 an instantiated YANG data tree. (Definition adopted from 334 [I-D.draft-ietf-netmod-revised-datastores]) 335 Data subtree: An instantiated data node and the data nodes that are 336 hierarchically contained within it. 338 IGP: Interior Gateway Protocol 340 IS-IS: Intermediate System to Intermediate System protocol 342 OSPF: Open Shortest Path First, a link state routing protocol 344 URI: Uniform Resource Identifier 346 4. Model Structure Details 348 4.1. Base Network Model 350 The abstract (base) network data model is defined in the ietf- 351 network.yang module. Its structure is shown in the following figure. 352 The notation syntax follows 353 [I-D.draft-ietf-netmod-yang-tree-diagrams]. 355 module: ietf-network 356 +--rw networks 357 +--rw network* [network-id] 358 +--rw network-id network-id 359 +--rw network-types 360 +--rw supporting-network* [network-ref] 361 | +--rw network-ref -> /networks/network/network-id 362 +--rw node* [node-id] 363 +--rw node-id node-id 364 +--rw supporting-node* [network-ref node-ref] 365 +--rw network-ref -> ../../../supporting-network/ + 366 | network-ref 367 +--rw node-ref -> /networks/network/node/node-id 369 Figure 4: The structure of the abstract (base) network data model 371 The data model contains a container with a list of networks. Each 372 network is captured in its own list entry, distinguished via a 373 network-id. 375 A network has a certain type, such as L2, L3, OSPF or IS-IS. A 376 network can even have multiple types simultaneously. The type, or 377 types, are captured underneath the container "network-types". In 378 this module it serves merely as an augmentation target; network- 379 specific modules will later introduce new data nodes to represent new 380 network types below this target, i.e. insert them below "network- 381 types" by ways of YANG augmentation. 383 When a network is of a certain type, it will contain a corresponding 384 data node. Network types SHOULD always be represented using presence 385 containers, not leafs of empty type. This allows the representation 386 of hierarchies of network subtypes within the instance information. 387 For example, an instance of an OSPF network (which, at the same time, 388 is a layer 3 unicast IGP network) would contain underneath "network- 389 types" another presence container "l3-unicast-igp-network", which in 390 turn would contain a presence container "ospf-network". Actual 391 examples of this pattern can be found in 392 [I-D.draft-ietf-i2rs-yang-l3-topology]. 394 A network can in turn be part of a hierarchy of networks, building on 395 top of other networks. Any such networks are captured in the list 396 "supporting-network". A supporting network is in effect an underlay 397 network. 399 Furthermore, a network contains an inventory of nodes that are part 400 of the network. The nodes of a network are captured in their own 401 list. Each node is identified relative to its containing network by 402 a node-id. 404 It should be noted that a node does not exist independently of a 405 network; instead it is a part of the network that it is contained in. 406 In cases where the same entity takes part in multiple networks, or at 407 multiple layers of a networking stack, the same entity will be 408 represented by multiple nodes, one for each network. In other words, 409 the node represents an abstraction of the device for the particular 410 network that it a is part of. To represent that the same entity or 411 same device is part of multiple topologies or networks, it is 412 possible to create one "physical" network with a list of nodes for 413 each of the devices or entities. This (physical) network, 414 respectively the (entities) nodes in that network, can then be 415 referred to as underlay network and nodes from the other (logical) 416 networks and nodes, respectively. Note that the data model allows 417 for the definition of more than one underlay network (and node), 418 allowing for simultaneous representation of layered network and 419 service topologies and their physical instantiation. 421 Similar to a network, a node can be supported by other nodes, and map 422 onto one or more other nodes in an underlay network. This is 423 captured in the list "supporting-node". The resulting hierarchy of 424 nodes allows also for the representation of device stacks, where a 425 node at one level is supported by a set of nodes at an underlying 426 level. For example, a "router" node might be supported by a node 427 representing a route processor and separate nodes for various line 428 cards and service modules, a virtual router might be supported or 429 hosted on a physical device represented by a separate node, and so 430 on. 432 Network data of a network at a particular layer can come into being 433 in one of two ways. In one way, network data is configured by client 434 applications, for example in case of overlay networks that are 435 configured by an SDN Controller application. In another way, it is 436 automatically controlled by the system, in case of networks that can 437 be discovered. It is possible for a configured (overlay) network to 438 refer to a (discovered) underlay network. 440 The revised datastore architecture 441 [I-D.draft-ietf-netmod-revised-datastores] is used to account for 442 those possibilities. Specifically, for each network, the origin of 443 its data is indicated per the "origin" metadata annotation - 444 "intended" for data that was configured by a client application, 445 "learned" for data that is discovered. Network data that is 446 discovered is automatically populated as part of the operational 447 datastore. Network data that is configured is part of the 448 configuration and intended datastores, respectively. Configured 449 network data that is actually in effect is in addition reflected in 450 the operational datastore. Data in the operational datastore will 451 always have complete referential integrity. Should a configured data 452 item (such as a node) have a dangling reference that refers to a non- 453 existing data item (such as a supporting node), the configured data 454 item will automatically be removed from the operational datastore and 455 thus only appear in the intended datastore. It will be up to the 456 client application to resolve the situation and ensure that the 457 reference to the supporting resources is configured properly. 459 4.2. Base Network Topology Data Model 461 The abstract (base) network topology data model is defined in the 462 "ietf-network-topology.yang" module. It builds on the network data 463 model defined in the "ietf-network.yang" module, augmenting it with 464 links (defining how nodes are connected) and termination-points 465 (which anchor the links and are contained in nodes). The structure 466 of the network topology module is shown in the following figure. The 467 notation syntax follows [I-D.draft-ietf-netmod-yang-tree-diagrams]. 469 module: ietf-network-topology 470 augment /nw:networks/nw:network: 471 +--rw link* [link-id] 472 +--rw link-id link-id 473 +--rw source 474 | +--rw source-node? -> ../../../nw:node/node-id 475 | +--rw source-tp? -> ../../../nw:node[nw:node-id=current()/+ 476 | ../source-node]/termination-point/tp-id 477 +--rw destination 478 | +--rw dest-node? -> ../../../nw:node/node-id 479 | +--rw dest-tp? -> ../../../nw:node[nw:node-id=current()/+ 480 | ../dest-node]/termination-point/tp-id 481 +--rw supporting-link* [network-ref link-ref] 482 +--rw network-ref -> ../../../nw:supporting-network/+ 483 | network-ref 484 +--rw link-ref -> /nw:networks/network+ 485 [nw:network-id=current()/../network-ref]/+ 486 link/link-id 487 augment /nw:networks/nw:network/nw:node: 488 +--rw termination-point* [tp-id] 489 +--rw tp-id tp-id 490 +--rw supporting-termination-point* [network-ref node-ref tp-ref] 491 +--rw network-ref -> ../../../nw:supporting-node/network-ref 492 +--rw node-ref -> ../../../nw:supporting-node/node-ref 493 +--rw tp-ref -> /nw:networks/network[nw:network-id=+ 494 current()/../network-ref]/node+ 495 [nw:node-id=current()/../node-ref]/+ 496 termination-point/tp-id 498 Figure 5: The structure of the abstract (base) network topology data 499 model 501 A node has a list of termination points that are used to terminate 502 links. An example of a termination point might be a physical or 503 logical port or, more generally, an interface. 505 Like a node, a termination point can in turn be supported by an 506 underlying termination point, contained in the supporting node of the 507 underlay network. 509 A link is identified by a link-id that uniquely identifies the link 510 within a given topology. Links are point-to-point and 511 unidirectional. Accordingly, a link contains a source and a 512 destination. Both source and destination reference a corresponding 513 node, as well as a termination point on that node. Similar to a 514 node, a link can map onto one or more links in an underlay topology 515 (which are terminated by the corresponding underlay termination 516 points). This is captured in the list "supporting-link". 518 4.3. Extending the data model 520 In order to derive a data model for a specific type of network, the 521 base data model can be extended. This can be done roughly as 522 follows: for the new network type, a new YANG module is introduced. 523 In this module, a number of augmentations are defined against the 524 network and network-topology YANG modules. 526 We start with augmentations against the ietf-network.yang module. 527 First, a new network type needs to be defined. For this, a presence 528 container that resembles the new network type is defined. It is 529 inserted by means of augmentation below the network-types container. 530 Subsequently, data nodes for any network-type specific node 531 parameters are defined and augmented into the node list. The new 532 data nodes can be defined as conditional ("when") on the presence of 533 the corresponding network type in the containing network. In cases 534 where there are any requirements or restrictions in terms of network 535 hierarchies, such as when a network of a new network-type requires a 536 specific type of underlay network, it is possible to define 537 corresponding constraints as well and augment the supporting-network 538 list accordingly. However, care should be taken to avoid excessive 539 definitions of constraints. 541 Subsequently, augmentations are defined against ietf-network- 542 topology.yang. Data nodes are defined both for link parameters, as 543 well as termination point parameters, that are specific to the new 544 network type. Those data nodes are inserted by way of augmentation 545 into the link and termination-point lists, respectively. Again, data 546 nodes can be defined as conditional on the presence of the 547 corresponding network-type in the containing network, by adding a 548 corresponding "when"-statement. 550 It is possible, but not required, to group data nodes for a given 551 network-type under a dedicated container. Doing so introduces 552 further structure, but lengthens data node path names. 554 In cases where a hierarchy of network types is defined, augmentations 555 can in turn be applied against augmenting modules, with the module of 556 a network "sub-type" augmenting the module of a network "super-type". 558 4.4. Discussion and selected design decisions 560 4.4.1. Container structure 562 Rather than maintaining lists in separate containers, the data model 563 is kept relatively flat in terms of its containment structure. Lists 564 of nodes, links, termination-points, and supporting-nodes, 565 supporting-links, and supporting-termination-points are not kept in 566 separate containers. Therefore, path specifiers used to refer to 567 specific nodes, be it in management operations or in specifications 568 of constraints, can remain relatively compact. Of course, this means 569 there is no separate structure in instance information that separates 570 elements of different lists from one another. Such structure is 571 semantically not required, although it might enhance human 572 readability in some cases. 574 4.4.2. Underlay hierarchies and mappings 576 To minimize assumptions of what a particular entity might actually 577 represent, mappings between networks, nodes, links, and termination 578 points are kept strictly generic. For example, no assumptions are 579 made whether a termination point actually refers to an interface, or 580 whether a node refers to a specific "system" or device; the data 581 model at this generic level makes no provisions for that. 583 Where additional specifics about mappings between upper and lower 584 layers are required, those can be captured in augmenting modules. 585 For example, to express that a termination point in a particular 586 network type maps to an interface, an augmenting module can introduce 587 an augmentation to the termination point which introduces a leaf of 588 type ifref that references the corresponding interface [RFC7223]. 589 Similarly, if a node maps to a particular device or network element, 590 an augmenting module can augment the node data with a leaf that 591 references the network element. 593 It is possible for links at one level of a hierarchy to map to 594 multiple links at another level of the hierarchy. For example, a VPN 595 topology might model VPN tunnels as links. Where a VPN tunnel maps 596 to a path that is composed of a chain of several links, the link will 597 contain a list of those supporting links. Likewise, it is possible 598 for a link at one level of a hierarchy to aggregate a bundle of links 599 at another level of the hierarchy. 601 4.4.3. Dealing with changes in underlay networks 603 It is possible for a network to undergo churn even as other networks 604 are layered on top of it. When a supporting node, link, or 605 termination point is deleted, the supporting leafrefs in the overlay 606 will be left dangling. To allow for this possibility, the data model 607 makes use of the "require-instance" construct of YANG 1.1 [RFC7950]. 609 A dangling leafref of a configured object leaves the corresponding 610 instance in a state in which it lacks referential integrity, 611 rendering it in effect inoperational. Any corresponding object 612 instance is therefore removed from the operational datastore until 613 the situation has been resolved, i.e. until either the supporting 614 object is added to the operational datastore, or until the instance 615 is reconfigured to refer to another object that is actually reflected 616 in the operational datastore. It does remain part of the intended 617 datastore. 619 It is the responsibility of the application maintaining the overlay 620 to deal with the possibility of churn in the underlay network. When 621 a server receives a request to configure an overlay network, it 622 SHOULD validate whether supporting nodes/links/tps refer to nodes in 623 the underlay are actually in existence, i.e. nodes which are 624 reflected in the operational datastore. Configuration requests in 625 which supporting nodes/links/tps refer to objects currently not in 626 existence SHOULD be rejected. It is the responsibility of the 627 application to update the overlay when a supporting node/link/tp is 628 deleted at a later point in time. For this purpose, an application 629 might subscribe to updates when changes to the underlay occur, for 630 example using mechanisms defined in 631 [I-D.draft-ietf-netconf-yang-push]. 633 4.4.4. Use of groupings 635 The data model makes use of groupings, instead of simply defining 636 data nodes "in-line". This makes it easier to include the 637 corresponding data nodes in notifications, which then do not need to 638 respecify each data node that is to be included. The tradeoff for 639 this is that it makes the specification of constraints more complex, 640 because constraints involving data nodes outside the grouping need to 641 be specified in conjunction with a "uses" statement where the 642 grouping is applied. This also means that constraints and XPath- 643 statements need to be specified in such a way that they navigate 644 "down" first and select entire sets of nodes, as opposed to being 645 able to simply specify them against individual data nodes. 647 4.4.5. Cardinality and directionality of links 649 The topology data model includes links that are point-to-point and 650 unidirectional. It does not directly support multipoint and 651 bidirectional links. While this may appear as a limitation, it does 652 keep the data model simple, generic, and allows it to very easily be 653 subjected to applications that make use of graph algorithms. Bi- 654 directional connections can be represented through pairs of 655 unidirectional links. Multipoint networks can be represented through 656 pseudo-nodes (similar to IS-IS, for example). By introducing 657 hierarchies of nodes, with nodes at one level mapping onto a set of 658 other nodes at another level, and introducing new links for nodes at 659 that level, topologies with connections representing non-point-to- 660 point communication patterns can be represented. 662 4.4.6. Multihoming and link aggregation 664 Links are terminated by a single termination point, not sets of 665 termination points. Connections involving multihoming or link 666 aggregation schemes need to be represented using multiple point-to- 667 point links, then defining a link at a higher layer that is supported 668 by those individual links. 670 4.4.7. Mapping redundancy 672 In a hierarchy of networks, there are nodes mapping to nodes, links 673 mapping to links, and termination points mapping to termination 674 points. Some of this information is redundant. Specifically, if the 675 link-to-links mapping is known, and the termination points of each 676 link are known, termination point mapping information can be derived 677 via transitive closure and does not have to be explicitly configured. 678 Nonetheless, in order to not constrain applications regarding which 679 mappings they want to configure and which should be derived, the data 680 model does provide for the option to configure this information 681 explicitly. The data model includes integrity constraints to allow 682 for validating for consistency. 684 4.4.8. Typing 686 A network's network types are represented using a container which 687 contains a data node for each of its network types. A network can 688 encompass several types of network simultaneously, hence a container 689 is used instead of a case construct, with each network type in turn 690 represented by a dedicated presence container itself. The reason for 691 not simply using an empty leaf, or even simpler, do away even with 692 the network container and just use a leaf-list of network-type 693 instead, is to be able to represent "class hierarchies" of network 694 types, with one network type refining the other. Network-type 695 specific containers are to be defined in the network-specific 696 modules, augmenting the network-types container. 698 4.4.9. Representing the same device in multiple networks 700 One common requirement concerns the ability to represent that the 701 same device can be part of multiple networks and topologies. 702 However, the data model defines a node as relative to the network 703 that it is contained in. The same node cannot be part of multiple 704 topologies. In many cases, a node will be the abstraction of a 705 particular device in a network. To reflect that the same device is 706 part of multiple topologies, the following approach might be chosen: 707 A new type of network to represent a "physical" (or "device") network 708 is introduced, with nodes representing devices. This network forms 709 an underlay network for logical networks above it, with nodes of the 710 logical network mapping onto nodes in the physical network. 712 This scenario is depicted in the following figure. It depicts three 713 networks with two nodes each. A physical network P consists of an 714 inventory of two nodes, D1 and D2, each representing a device. A 715 second network, X, has a third network, Y, as its underlay. Both X 716 and Y also have the physical network P as underlay. X1 has both Y1 717 and D1 as underlay nodes, while Y1 has D1 as underlay node. 718 Likewise, X2 has both Y2 and D2 as underlay nodes, while Y2 has D2 as 719 underlay node. The fact that X1 and Y1 are both instantiated on the 720 same physical node D1 can be easily derived. 722 +---------------------+ 723 / [X1]____[X2] / X(Service Overlay) 724 +----:--:----:--------+ 725 ..: :..: : 726 ........: ....: : :.... 727 +-----:-------------:--+ : :... 728 / [Y1]____[Y2]....: / :.. : 729 +------|-------|-------+ :.. :... 730 Y(L3) | +---------------------:-----+ : 731 | +----:----|-:----------+ 732 +------------------------/---[D1] [D2] / 733 +----------------------+ 734 P (Physical network) 736 Figure 6: Topology hierarchy example - multiple underlays 738 In the case of a physical network, nodes represent physical devices 739 and termination points physical ports. It should be noted that it is 740 also possible to augment the data model for a physical network-type, 741 defining augmentations that have nodes reference system information 742 and termination points reference physical interfaces, in order to 743 provide a bridge between network and device models. 745 4.4.10. Supporting client-configured and system-controlled network 746 topology 748 YANG requires data nodes to be designated as either configuration 749 ("config true") or operational data ("config false"), but not both, 750 yet it is important to have all network information, including 751 vertical cross-network dependencies, captured in one coherent data 752 model. In most cases, network topology information is discovered 753 about a network; the topology is considered a property of the network 754 that is reflected in the data model. That said, certain types of 755 topology need to also be configurable by an application, such as in 756 the case of overlay topologies. 758 The YANG data model for network topology designates all data as 759 "config true". The distinction between data that is actually 760 configured and data that is in effect, including data that is 761 discovered about the network, is provided through the datastores 762 introduced as part of the Network Management Datastore Architecture, 763 NMDA [I-D.draft-ietf-netmod-revised-datastores]. Network topology 764 data that is discovered is automatically populated as part of the 765 operational datastore, . It is "system controlled". 766 Network topology that is configured is instantiated as part of a 767 configuration datastore, e.g. . Only when it has actually 768 taken effect, it is also instantiated as part of the operational 769 datastore, i.e. . 771 Configured network topology will in general refer to an underlay 772 topology and include layering information, such as the supporting 773 node(s) underlying a node, supporting link(s) underlying a link, and 774 supporting termination point(s) underlying a termination point. The 775 supporting objects must be instantiated in the operational datastore 776 in order for the dependent overlay object to be reflected in the 777 operational datastore. Should a configured data item (such as a 778 node) have a dangling reference that refers to a non-existing data 779 item (such as a supporting node), the configured data item will 780 automatically be removed from and show up only in the 781 . It will be up to the client application to resolve the 782 situation and ensure that the reference to the supporting resources 783 is configured properly. 785 For each network, the origin of its data is indicated per the 786 "origin" metadata [RFC7952] annotation defined in 787 [I-D.draft-ietf-netmod-revised-datastores]. In general, the origin 788 of discovered network data is "learned"; the origin of configured 789 network data is "intended". 791 4.4.11. Identifiers of string or URI type 793 The current data model defines identifiers of nodes, networks, links, 794 and termination points as URIs. An alternative would define them as 795 strings. 797 The case for strings is that they will be easier to implement. The 798 reason for choosing URIs is that the topology/node/tp exists in a 799 larger context, hence it is useful to be able to correlate 800 identifiers across systems. While strings, being the universal data 801 type, are easier for human beings, they also muddle things. What 802 typically happens is that strings have some structure which is 803 magically assigned and the knowledge of this structure has to be 804 communicated to each system working with the data. A URI makes the 805 structure explicit and also attaches additional semantics: the URI, 806 unlike a free-form string, can be fed into a URI resolver, which can 807 point to additional resources associated with the URI. This property 808 is important when the topology data is integrated into a larger, more 809 complex system. 811 5. Interactions with Other YANG Modules 813 The data model makes use of data types that have been defined in 814 [RFC6991]. 816 This is a protocol independent YANG data model with topology 817 information. It is separate from and not linked with data models 818 that are used to configure routing protocols or routing information. 819 This includes e.g. data model "ietf-routing" [RFC8022]. 821 The data model obeys the requirements for the ephemeral state found 822 in the document [I-D.draft-ietf-i2rs-ephemeral-state]. For ephemeral 823 topology data that is system controlled, the process tasked with 824 maintaining topology information will load information from the 825 routing process (such as OSPF) into the without relying 826 on a configuration datastore. 828 6. YANG Modules 830 6.1. Defining the Abstract Network: ietf-network.yang 832 NOTE TO RFC EDITOR: Please change the date in the file name after the 833 CODE BEGINS statement to the date of publication when published. 835 file "ietf-network@2017-11-15.yang" 836 module ietf-network { 837 yang-version 1.1; 838 namespace "urn:ietf:params:xml:ns:yang:ietf-network"; 839 prefix nw; 841 import ietf-inet-types { 842 prefix inet; 843 reference "RFC 6991"; 844 } 846 organization 847 "IETF I2RS (Interface to the Routing System) Working Group"; 849 contact 850 "WG Web: 851 WG List: 853 Editor: Alexander Clemm 854 856 Editor: Jan Medved 857 859 Editor: Robert Varga 860 862 Editor: Nitin Bahadur 863 865 Editor: Hariharan Ananthakrishnan 866 868 Editor: Xufeng Liu 869 "; 871 description 872 "This module defines a common base data model for a collection 873 of nodes in a network. Node definitions are further used 874 in network topologies and inventories. 876 Copyright (c) 2017 IETF Trust and the persons identified as 877 authors of the code. All rights reserved. 879 Redistribution and use in source and binary forms, with or 880 without modification, is permitted pursuant to, and subject 881 to the license terms contained in, the Simplified BSD License 882 set forth in Section 4.c of the IETF Trust's Legal Provisions 883 Relating to IETF Documents 884 (http://trustee.ietf.org/license-info). 886 This version of this YANG module is part of 887 draft-ietf-i2rs-yang-network-topo-18; 888 see the RFC itself for full legal notices. 890 NOTE TO RFC EDITOR: Please replace above reference to 891 draft-ietf-i2rs-yang-network-topo-18 with RFC 892 number when published (i.e. RFC xxxx)."; 894 revision 2017-11-15 { 895 description 896 "Initial revision. 897 NOTE TO RFC EDITOR: 898 (1) Please replace the following reference 899 to draft-ietf-i2rs-yang-network-topo-18 with 900 RFC number when published (i.e. RFC xxxx). 901 (2) Please replace the date in the revision statement with the 902 date of publication when published. "; 903 reference 904 "draft-ietf-i2rs-yang-network-topo-18"; 905 } 907 typedef node-id { 908 type inet:uri; 909 description 910 "Identifier for a node. The precise structure of the node-id 911 will be up to the implementation. Some implementations MAY 912 for example, pick a uri that includes the network-id as 913 part of the path. The identifier SHOULD be chosen such that 914 the same node in a real network topology will always be 915 identified through the same identifier, even if the data model 916 is instantiated in separate datastores. An implementation MAY 917 choose to capture semantics in the identifier, for example to 918 indicate the type of node."; 919 } 921 typedef network-id { 922 type inet:uri; 923 description 924 "Identifier for a network. The precise structure of the 925 network-id will be up to an implementation. 926 The identifier SHOULD be chosen such that the same network 927 will always be identified through the same identifier, 928 even if the data model is instantiated in separate datastores. 929 An implementation MAY choose to capture semantics in the 930 identifier, for example to indicate the type of network."; 931 } 933 grouping network-ref { 934 description 935 "Contains the information necessary to reference a network, 936 for example an underlay network."; 937 leaf network-ref { 938 type leafref { 939 path "/nw:networks/nw:network/nw:network-id"; 940 require-instance false; 941 } 942 description 943 "Used to reference a network, for example an underlay 944 network."; 945 } 946 } 947 grouping node-ref { 948 description 949 "Contains the information necessary to reference a node."; 950 leaf node-ref { 951 type leafref { 952 path "/nw:networks/nw:network[nw:network-id=current()/../"+ 953 "network-ref]/nw:node/nw:node-id"; 954 require-instance false; 955 } 956 description 957 "Used to reference a node. 958 Nodes are identified relative to the network they are 959 contained in."; 960 } 961 uses network-ref; 962 } 964 container networks { 965 description 966 "Serves as top-level container for a list of networks."; 967 list network { 968 key "network-id"; 969 description 970 "Describes a network. 971 A network typically contains an inventory of nodes, 972 topological information (augmented through 973 network-topology data model), as well as layering 974 information."; 975 leaf network-id { 976 type network-id; 977 description 978 "Identifies a network."; 979 } 980 container network-types { 981 description 982 "Serves as an augmentation target. 983 The network type is indicated through corresponding 984 presence containers augmented into this container."; 985 } 986 list supporting-network { 987 key "network-ref"; 988 description 989 "An underlay network, used to represent layered network 990 topologies."; 991 leaf network-ref { 992 type leafref { 993 path "/nw:networks/nw:network/nw:network-id"; 994 require-instance false; 995 } 996 description 997 "References the underlay network."; 998 } 999 } 1000 list node { 1001 key "node-id"; 1002 description 1003 "The inventory of nodes of this network."; 1004 leaf node-id { 1005 type node-id; 1006 description 1007 "Identifies a node uniquely within the containing 1008 network."; 1009 } 1010 list supporting-node { 1011 key "network-ref node-ref"; 1012 description 1013 "Represents another node, in an underlay network, that 1014 this node is supported by. Used to represent layering 1015 structure."; 1016 leaf network-ref { 1017 type leafref { 1018 path "../../../nw:supporting-network/nw:network-ref"; 1019 require-instance false; 1020 } 1021 description 1022 "References the underlay network that the 1023 underlay node is part of."; 1024 } 1025 leaf node-ref { 1026 type leafref { 1027 path "/nw:networks/nw:network/nw:node/nw:node-id"; 1028 require-instance false; 1029 } 1030 description 1031 "References the underlay node itself."; 1032 } 1033 } 1034 } 1035 } 1036 } 1037 } 1039 1041 6.2. Creating Abstract Network Topology: ietf-network-topology.yang 1043 NOTE TO RFC EDITOR: Please change the date in the file name after the 1044 CODE BEGINS statement to the date of publication when published. 1046 file "ietf-network-topology@2017-11-15.yang" 1047 module ietf-network-topology { 1048 yang-version 1.1; 1049 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology"; 1050 prefix nt; 1052 import ietf-inet-types { 1053 prefix inet; 1054 reference 1055 "RFC 6991"; 1056 } 1057 import ietf-network { 1058 prefix nw; 1059 reference 1060 "draft-ietf-i2rs-yang-network-topo-18 1061 NOTE TO RFC EDITOR: 1062 (1) Please replace above reference to 1063 draft-ietf-i2rs-yang-network-topo-18 with RFC 1064 number when published (i.e. RFC xxxx). 1065 (2) Please replace the date in the revision statement with the 1066 date of publication when published."; 1067 } 1069 organization 1070 "IETF I2RS (Interface to the Routing System) Working Group"; 1072 contact 1073 "WG Web: 1074 WG List: 1076 Editor: Alexander Clemm 1077 1079 Editor: Jan Medved 1080 1082 Editor: Robert Varga 1083 1085 Editor: Nitin Bahadur 1086 1088 Editor: Hariharan Ananthakrishnan 1089 1091 Editor: Xufeng Liu 1092 "; 1094 description 1095 "This module defines a common base model for network topology, 1096 augmenting the base network data model with links to connect 1097 nodes, as well as termination points to terminate links on nodes. 1099 Copyright (c) 2017 IETF Trust and the persons identified as 1100 authors of the code. All rights reserved. 1102 Redistribution and use in source and binary forms, with or 1103 without modification, is permitted pursuant to, and subject 1104 to the license terms contained in, the Simplified BSD License 1105 set forth in Section 4.c of the IETF Trust's Legal Provisions 1106 Relating to IETF Documents 1107 (http://trustee.ietf.org/license-info). 1109 This version of this YANG module is part of 1110 draft-ietf-i2rs-yang-network-topo-18; 1111 see the RFC itself for full legal notices. 1113 NOTE TO RFC EDITOR: Please replace above reference to 1114 draft-ietf-i2rs-yang-network-topo-18 with RFC 1115 number when published (i.e. RFC xxxx)."; 1117 revision 2017-11-15 { 1118 description 1119 "Initial revision. 1120 NOTE TO RFC EDITOR: Please replace the following reference 1121 to draft-ietf-i2rs-yang-network-topo-18 with 1122 RFC number when published (i.e. RFC xxxx)."; 1123 reference 1124 "draft-ietf-i2rs-yang-network-topo-18"; 1125 } 1127 typedef link-id { 1128 type inet:uri; 1129 description 1130 "An identifier for a link in a topology. 1131 The precise structure of the link-id 1132 will be up to the implementation. 1133 The identifier SHOULD be chosen such that the same link in a 1134 real network topology will always be identified through the 1135 same identifier, even if the data model is instantiated in 1136 separate datastores. An implementation MAY choose to capture 1138 semantics in the identifier, for example to indicate the type 1139 of link and/or the type of topology that the link is a part 1140 of."; 1141 } 1143 typedef tp-id { 1144 type inet:uri; 1145 description 1146 "An identifier for termination points (TPs) on a node. 1147 The precise structure of the tp-id 1148 will be up to the implementation. 1149 The identifier SHOULD be chosen such that the same termination 1150 point in a real network topology will always be identified 1151 through the same identifier, even if the data model is 1152 instantiated in separate datastores. An implementation MAY 1153 choose to capture semantics in the identifier, for example to 1154 indicate the type of termination point and/or the type of node 1155 that contains the termination point."; 1156 } 1158 grouping link-ref { 1159 description 1160 "This grouping can be used to reference a link in a specific 1161 network. While it is not used in this module, it is defined 1162 here for the convenience of augmenting modules."; 1163 leaf link-ref { 1164 type leafref { 1165 path "/nw:networks/nw:network[nw:network-id=current()/../"+ 1166 "network-ref]/nt:link/nt:link-id"; 1167 require-instance false; 1168 } 1169 description 1170 "A type for an absolute reference a link instance. 1171 (This type should not be used for relative references. 1172 In such a case, a relative path should be used instead.)"; 1173 } 1174 uses nw:network-ref; 1175 } 1177 grouping tp-ref { 1178 description 1179 "This grouping can be used to references a termination point 1180 in a specific node. While it is not used in this module, it 1181 is defined here for the convenience of augmenting modules."; 1182 leaf tp-ref { 1183 type leafref { 1184 path "/nw:networks/nw:network[nw:network-id=current()/../"+ 1185 "network-ref]/nw:node[nw:node-id=current()/../"+ 1186 "node-ref]/nt:termination-point/nt:tp-id"; 1187 require-instance false; 1188 } 1189 description 1190 "A type for an absolute reference to a termination point. 1191 (This type should not be used for relative references. 1192 In such a case, a relative path should be used instead.)"; 1193 } 1194 uses nw:node-ref; 1195 } 1197 augment "/nw:networks/nw:network" { 1198 description 1199 "Add links to the network data model."; 1200 list link { 1201 key "link-id"; 1202 description 1203 "A network link connects a local (source) node and 1204 a remote (destination) node via a set of 1205 the respective node's termination points. 1206 It is possible to have several links between the same 1207 source and destination nodes. Likewise, a link could 1208 potentially be re-homed between termination points. 1209 Therefore, in order to ensure that we would always know 1210 to distinguish between links, every link is identified by 1211 a dedicated link identifier. Note that a link models a 1212 point-to-point link, not a multipoint link."; 1213 leaf link-id { 1214 type link-id; 1215 description 1216 "The identifier of a link in the topology. 1217 A link is specific to a topology to which it belongs."; 1218 } 1219 container source { 1220 description 1221 "This container holds the logical source of a particular 1222 link."; 1223 leaf source-node { 1224 type leafref { 1225 path "../../../nw:node/nw:node-id"; 1226 require-instance false; 1227 } 1228 description 1229 "Source node identifier, must be in same topology."; 1230 } 1231 leaf source-tp { 1232 type leafref { 1233 path "../../../nw:node[nw:node-id=current()/../"+ 1234 "source-node]/termination-point/tp-id"; 1235 require-instance false; 1236 } 1237 description 1238 "Termination point within source node that terminates 1239 the link."; 1240 } 1241 } 1242 container destination { 1243 description 1244 "This container holds the logical destination of a 1245 particular link."; 1246 leaf dest-node { 1247 type leafref { 1248 path "../../../nw:node/nw:node-id"; 1249 require-instance false; 1250 } 1251 description 1252 "Destination node identifier, must be in the same 1253 network."; 1254 } 1255 leaf dest-tp { 1256 type leafref { 1257 path "../../../nw:node[nw:node-id=current()/../"+ 1258 "dest-node]/termination-point/tp-id"; 1259 require-instance false; 1260 } 1261 description 1262 "Termination point within destination node that 1263 terminates the link."; 1264 } 1265 } 1266 list supporting-link { 1267 key "network-ref link-ref"; 1268 description 1269 "Identifies the link, or links, that this link 1270 is dependent on."; 1271 leaf network-ref { 1272 type leafref { 1273 path "../../../nw:supporting-network/nw:network-ref"; 1274 require-instance false; 1275 } 1276 description 1277 "This leaf identifies in which underlay topology 1278 the supporting link is present."; 1279 } 1280 leaf link-ref { 1281 type leafref { 1282 path "/nw:networks/nw:network[nw:network-id=current()/"+ 1283 "../network-ref]/link/link-id"; 1284 require-instance false; 1285 } 1286 description 1287 "This leaf identifies a link which is a part 1288 of this link's underlay. Reference loops in which 1289 a link identifies itself as its underlay, either 1290 directly or transitively, are not allowed."; 1291 } 1292 } 1293 } 1294 } 1295 augment "/nw:networks/nw:network/nw:node" { 1296 description 1297 "Augment termination points which terminate links. 1298 Termination points can ultimately be mapped to interfaces."; 1299 list termination-point { 1300 key "tp-id"; 1301 description 1302 "A termination point can terminate a link. 1303 Depending on the type of topology, a termination point 1304 could, for example, refer to a port or an interface."; 1305 leaf tp-id { 1306 type tp-id; 1307 description 1308 "Termination point identifier."; 1309 } 1310 list supporting-termination-point { 1311 key "network-ref node-ref tp-ref"; 1312 description 1313 "This list identifies any termination points that 1314 the termination point is dependent on, or maps onto. 1315 Those termination points will themselves be contained 1316 in a supporting node. 1317 This dependency information can be inferred from 1318 the dependencies between links. For this reason, 1319 this item is not separately configurable. Hence no 1320 corresponding constraint needs to be articulated. 1321 The corresponding information is simply provided by the 1322 implementing system."; 1323 leaf network-ref { 1324 type leafref { 1325 path "../../../nw:supporting-node/nw:network-ref"; 1326 require-instance false; 1327 } 1328 description 1329 "This leaf identifies in which topology the 1330 supporting termination point is present."; 1331 } 1332 leaf node-ref { 1333 type leafref { 1334 path "../../../nw:supporting-node/nw:node-ref"; 1335 require-instance false; 1336 } 1337 description 1338 "This leaf identifies in which node the supporting 1339 termination point is present."; 1340 } 1341 leaf tp-ref { 1342 type leafref { 1343 path "/nw:networks/nw:network[nw:network-id=current()/"+ 1344 "../network-ref]/nw:node[nw:node-id=current()/../"+ 1345 "node-ref]/termination-point/tp-id"; 1346 require-instance false; 1347 } 1348 description 1349 "Reference to the underlay node, must be in a 1350 different topology"; 1351 } 1352 } 1353 } 1354 } 1355 } 1357 1359 7. IANA Considerations 1361 This document registers the following namespace URIs in the "IETF XML 1362 Registry" [RFC3688]: 1364 URI: urn:ietf:params:xml:ns:yang:ietf-network 1365 Registrant Contact: The IESG. 1366 XML: N/A; the requested URI is an XML namespace. 1368 URI:urn:ietf:params:xml:ns:yang:ietf-network-topology 1369 Registrant Contact: The IESG. 1370 XML: N/A; the requested URI is an XML namespace. 1372 URI: urn:ietf:params:xml:ns:yang:ietf-network-state 1373 Registrant Contact: The IESG. 1374 XML: N/A; the requested URI is an XML namespace. 1376 URI:urn:ietf:params:xml:ns:yang:ietf-network-topology-state 1377 Registrant Contact: The IESG. 1379 XML: N/A; the requested URI is an XML namespace. 1381 This document registers the following YANG modules in the "YANG 1382 Module Names" registry [RFC6020]: 1384 NOTE TO THE RFC EDITOR: In the list below, please replace references 1385 to "draft-ietf-i2rs-yang-network-topo-18 (RFC form)" with RFC number 1386 when published (i.e. RFC xxxx). 1388 Name: ietf-network 1389 Namespace: urn:ietf:params:xml:ns:yang:ietf-network 1390 Prefix: nw 1391 Reference: draft-ietf-i2rs-yang-network-topo-18.txt (RFC form) 1393 Name: ietf-network-topology 1394 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology 1395 Prefix: nt 1396 Reference: draft-ietf-i2rs-yang-network-topo-18.txt (RFC form) 1398 Name: ietf-network-state 1399 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-state 1400 Prefix: nw-s 1401 Reference: draft-ietf-i2rs-yang-network-topo-18.txt (RFC form) 1403 Name: ietf-network-topology-state 1404 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology-state 1405 Prefix: nt-s 1406 Reference: draft-ietf-i2rs-yang-network-topo-18.txt (RFC form) 1408 8. Security Considerations 1410 The YANG modules defined in this document are designed to be accessed 1411 via network management protocols such as NETCONF [RFC6241] or 1412 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport 1413 layer, and the mandatory-to-implement secure transport is Secure 1414 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the 1415 mandatory-to-implement secure transport is TLS [RFC5246]. 1417 The NETCONF access control model [RFC6536] provides the means to 1418 restrict access for particular NETCONF or RESTCONF users to a 1419 preconfigured subset of all available NETCONF or RESTCONF protocol 1420 operations and content. 1422 The YANG modules define information that can be configurable in 1423 certain instances, for example in the case of overlay topologies that 1424 can be created by client applications. In such cases, a malicious 1425 client could introduce topologies that are undesired. Specifically, 1426 a malicious client could attempt to remove or add a node, a link, a 1427 termination point, by creating or deleting corresponding elements in 1428 the node, link, and termination point lists, respectively. In the 1429 case of a topology that is learned, the server will automatically 1430 prohibit such misconfiguration attempts. In the case of a topology 1431 that is configured, i.e. whose origin is "intended", the undesired 1432 configuration could become effective and be reflected in the 1433 operational datastore, leading to disruption of services provided via 1434 this topology might be disrupted. For example, the topology could be 1435 "cut" or be configured in a suboptimal way, leading to increased 1436 consumption of resources in the underlay network due to resulting 1437 routing and bandwidth utilization inefficiencies. Likewise, it could 1438 lead to degradation of service levels as well as possibly disruption 1439 of service. For those reasons, it is important that the NETCONF 1440 access control model is vigorously applied to prevent topology 1441 misconfiguration by unauthorized clients. 1443 Specifically, there are a number of data nodes defined in these YANG 1444 module that are writable/creatable/deletable (i.e., config true, 1445 which is the default). These data nodes may be considered sensitive 1446 or vulnerable in some network environments. Write operations (e.g., 1447 edit-config) to these data nodes without proper protection can have a 1448 negative effect on network operations. These are the subtrees and 1449 data nodes and their sensitivity/vulnerability in the ietf-network 1450 module: 1452 o network: A malicious client could attempt to remove or add a 1453 network in an attempt to remove an overlay topology, or create an 1454 unauthorized overlay. 1456 o supporting-network: A malicious client could attempt to disrupt 1457 the logical structure of the model, resulting in lack of overall 1458 data integrity and making it more difficult to, for example, 1459 troubleshoot problems rooted in the layering of network 1460 topologies. 1462 o node: A malicious client could attempt to remove or add a node 1463 from network, for example in order to sabotage the topology of a 1464 network overlay. 1466 o supporting-node: A malicious client could attempt to change the 1467 supporting-node in order to sabotage the layering of an overlay. 1469 These are the subtrees and data nodes and their sensitivity/ 1470 vulnerability in the ietf-network-topology module: 1472 o link: A malicious client could attempt to remove a link from a 1473 topology, or add a new link, or manipulate the way the link is 1474 layered over supporting links, or modify the source or destination 1475 of the link. Either way, the structure of the topology would be 1476 sabotaged, which could, for example, result in an overlay topology 1477 that is less than optimal. 1479 o termination-point: A malicious client could attempt to remove 1480 termination points from a node, or add "phantom" termination 1481 points to a node, or change the layering dependencies of 1482 termination points, again in an attempt to sabotage the integrity 1483 of a topology and potentially disrupt orderly operations of an 1484 overlay. 1486 9. Contributors 1488 The data model presented in this paper was contributed to by more 1489 people than can be listed on the author list. Additional 1490 contributors include: 1492 o Vishnu Pavan Beeram, Juniper 1494 o Ken Gray, Cisco 1496 o Tom Nadeau, Brocade 1498 o Tony Tkacik 1500 o Kent Watsen, Juniper 1502 o Aleksandr Zhdankin, Cisco 1504 10. Acknowledgements 1506 We wish to acknowledge the helpful contributions, comments, and 1507 suggestions that were received from Alia Atlas, Andy Bierman, Martin 1508 Bjorklund, Igor Bryskin, Benoit Claise, Susan Hares, Ladislav Lhotka, 1509 Carlos Pignataro, Juergen Schoenwaelder, Robert Wilton, and Xian 1510 Zhang. 1512 11. References 1514 11.1. Normative References 1516 [I-D.draft-ietf-netmod-revised-datastores] 1517 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1518 and R. Wilton, "A Revised Conceptual Model for YANG 1519 Datastores", I-D draft-ietf-netmod-revised-datastores-02, 1520 May 2017. 1522 [RFC2119] Bradner, S., "Key words for use in RFCs to indicate 1523 requirement levels", RFC 2119, March 1997. 1525 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1526 2004. 1528 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1529 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1531 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1532 Network Configuration Protocol (NETCONF)", RFC 6020, 1533 October 2010. 1535 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1536 Bierman, "Network Configuration Protocol (NETCONF)", 1537 RFC 6241, June 2011. 1539 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1540 Shell (SSH)", RFC 6242, June 2011. 1542 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1543 Protocol (NETCONF) Access Control Model", RFC 6536, March 1544 2012. 1546 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1547 July 2013. 1549 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1550 RFC 7950, August 2016. 1552 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1553 Protocol", RFC 8040, January 2017. 1555 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1556 2119 Key Words", RFC 8174, May 2017. 1558 11.2. Informative References 1560 [I-D.draft-ietf-i2rs-ephemeral-state] 1561 Haas, J. and S. Hares, "I2RS Ephemeral State 1562 Requirements", I-D draft-ietf-i2rs-ephemeral-state-23, 1563 November 2016. 1565 [I-D.draft-ietf-i2rs-usecase-reqs-summary] 1566 Hares, S. and M. Chen, "Summary of I2RS Use Case 1567 Requirements", I-D draft-ietf-i2rs-usecase-reqs-summary- 1568 03, November 2016. 1570 [I-D.draft-ietf-i2rs-yang-l3-topology] 1571 Clemm, A., Medved, J., Varga, R., Liu, X., 1572 Ananthakrishnan, H., and N. Bahadur, "A YANG Data Model 1573 for Layer 3 Topologies", I-D draft-ietf-i2rs-yang-l3- 1574 topology-11, September 2017. 1576 [I-D.draft-ietf-netconf-yang-push] 1577 Clemm, A., Voit, E., Gonzalez Prieto, A., Tripathy, A., 1578 Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 1579 "Subscribing to YANG datastore push updates", I-D draft- 1580 ietf-netconf-yang-push-10, October 2017. 1582 [I-D.draft-ietf-netmod-yang-tree-diagrams] 1583 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", I-D 1584 draft-ietf-netmod-yang-tree-diagrams, June 2017. 1586 [RFC1195] Callon, R., "Use of OSI IS-IS for Routing in TCP/IP and 1587 Dual Environments", RFC 1195, December 1990. 1589 [RFC2328] Moy, J., "OSPF Version 2", RFC 2328, April 1998. 1591 [RFC3209] Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V., 1592 and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP 1593 Tunnels", RFC 3209, December 2001. 1595 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1596 Information Models and Data Models", RFC 3444, January 1597 2003. 1599 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1600 Management", RFC 7223, May 2014. 1602 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1603 RFC 7951, August 2016. 1605 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1606 RFC 7952, August 2016. 1608 [RFC8022] Lhotka, L. and A. Lindem, "A YANG Data Model for Routing 1609 Management", RFC 8022, November 2016. 1611 Appendix A. Model Use Cases 1613 A.1. Fetching Topology from a Network Element 1615 In its simplest form, topology is learned by a network element (e.g., 1616 a router) through its participation in peering protocols (IS-IS, BGP, 1617 etc.). This learned topology can then be exported (e.g., to a 1618 Network Management System) for external utilization. Typically, any 1619 network element in a domain can be queried for its topology and 1620 expected to return the same result. 1622 In a slightly more complex form, the network element may be a 1623 controller, either by nature of it having satellite or subtended 1624 devices hanging off of it, or in the more classical sense, such as 1625 special device designated to orchestrate the activities of a number 1626 of other devices (e.g., an optical controller). In this case, the 1627 controller device is logically a singleton and must be queried 1628 distinctly. 1630 It is worth noting that controllers can be built on top of 1631 controllers to establish a topology incorporating of all the domains 1632 within an entire network. 1634 In all of the cases above, the topology learned by the network 1635 element is considered to be operational state data. That is, the 1636 data is accumulated purely by the network element's interactions with 1637 other systems and is subject to change dynamically without input or 1638 consent. 1640 A.2. Modifying TE Topology Imported from an Optical Controller 1642 Consider a scenario where an Optical Transport Controller presents 1643 its topology in abstract TE Terms to a Client Packet Controller. 1644 This Customized Topology (that gets merged into the Client's native 1645 topology) contains sufficient information for the path computing 1646 client to select paths across the optical domain according to its 1647 policies. If the Client determines (at any given point in time) that 1648 this imported topology does not exactly cater to its requirements, it 1649 may decide to request modifications to the topology. Such 1650 customization requests may include addition or deletion of 1651 topological elements or modification of attributes associated with 1652 existing topological elements. From the perspective of the Optical 1653 Controller, these requests translate into configuration changes to 1654 the exported abstract topology. 1656 A.3. Annotating Topology for Local Computation 1658 In certain scenarios, the topology learned by a controller needs to 1659 be augmented with additional attributes before running a computation 1660 algorithm on it. Consider the case where a path-computation 1661 application on the controller needs to take the geographic 1662 coordinates of the nodes into account while computing paths on the 1663 learned topology. If the learned topology does not contain these 1664 coordinates, then these additional attributes must be configured on 1665 the corresponding topological elements. 1667 A.4. SDN Controller-Based Configuration of Overlays on Top of Underlays 1669 In this scenario, an SDN controller (for example, Open Daylight) 1670 maintains a view of the topology of the network that it controls 1671 based on information that it discovers from the network. In 1672 addition, it provides an application in which it configures and 1673 maintains an overlay topology. 1675 The SDN Controller thus maintains two roles: 1677 o It is a client to the network. 1679 o It is a server to its own northbound applications and clients, 1680 e.g. an OSS. 1682 In other words, one system's client (or controller, in this case) may 1683 be another system's server (or managed system). 1685 In this scenario, the SDN controller maintains a consolidated data 1686 model of multiple layers of topology. This includes the lower layers 1687 of the network topology, built from information that is discovered 1688 from the network. It also includes upper layers of topology overlay, 1689 configurable by the controller's client, i.e. the OSS. To the OSS, 1690 the lower topology layers constitute "read-only" information. The 1691 upper topology layers need to be read-writable. 1693 Appendix B. Companion YANG models for non-NMDA compliant 1694 implementations 1696 The YANG modules defined in this document are designed to be used in 1697 conjunction with implementations that support the Network Management 1698 Datastore Architecture (NMDA) defined in 1699 [I-D.draft-ietf-netmod-revised-datastores]. In order to allow 1700 implementations to use the data model even in cases when NMDA is not 1701 supported, in the following two companion modules are defined that 1702 represent the operational state of networks and network topologies. 1703 The modules, ietf-network-state and ietf-network-topology-state, 1704 mirror modules ietf-network and ietf-network-topology defined earlier 1705 in this document. However, all data nodes are non-configurable. 1706 They represent state that comes into being by either learning 1707 topology information from the network, or by applying configuration 1708 from the mirrored modules. 1710 The companion modules, ietf-network-state and ietf-network-topology- 1711 state, are redundant and SHOULD NOT be supported by implementations 1712 that support NMDA. It is for this reason that the definitions are 1713 defined in an appendix. 1715 As the structure of both modules mirrors that of their underlying 1716 modules, the YANG tree is not depicted separately. 1718 B.1. YANG Model for Network State 1720 NOTE TO RFC EDITOR: Please change the date in the file name after the 1721 CODE BEGINS statement to the date of the publication when published. 1723 file "ietf-network-state@2017-11-15.yang" 1724 module ietf-network-state { 1725 yang-version 1.1; 1726 namespace "urn:ietf:params:xml:ns:yang:ietf-network-state"; 1727 prefix nw-s; 1729 import ietf-network { 1730 prefix nw; 1731 reference 1732 "draft-ietf-i2rs-yang-network-topo-18 1733 NOTE TO RFC EDITOR: Please replace above reference to 1734 draft-ietf-i2rs-yang-network-topo-18 with RFC 1735 number when published (i.e. RFC xxxx)."; 1736 } 1738 organization 1739 "IETF I2RS (Interface to the Routing System) Working Group"; 1741 contact 1742 "WG Web: 1743 WG List: 1745 Editor: Alexander Clemm 1746 1748 Editor: Jan Medved 1749 1751 Editor: Robert Varga 1752 1754 Editor: Nitin Bahadur 1755 1757 Editor: Hariharan Ananthakrishnan 1758 1760 Editor: Xufeng Liu 1761 "; 1763 description 1764 "This module defines a common base data model for a collection 1765 of nodes in a network. Node definitions are further used 1766 in network topologies and inventories. It represents 1767 information that is either learned and automatically populated, 1768 or information that results from applying configured netwok 1769 information configured per the ietf-network data model, 1770 mirroring the corresponding data nodes in this data model. 1772 The data model mirrors ietf-network, but contains only 1773 read-only state data. The data model is not needed when the 1774 underlying implementation infrastructure supports the Network 1775 Management Datastore Architecture (NMDA). 1777 Copyright (c) 2017 IETF Trust and the persons identified as 1778 authors of the code. All rights reserved. 1780 Redistribution and use in source and binary forms, with or 1781 without modification, is permitted pursuant to, and subject 1782 to the license terms contained in, the Simplified BSD License 1783 set forth in Section 4.c of the IETF Trust's Legal Provisions 1784 Relating to IETF Documents 1785 (http://trustee.ietf.org/license-info). 1787 This version of this YANG module is part of 1788 draft-ietf-i2rs-yang-network-topo-18; 1789 see the RFC itself for full legal notices. 1791 NOTE TO RFC EDITOR: Please replace above reference to 1792 draft-ietf-i2rs-yang-network-topo-18 with RFC 1793 number when published (i.e. RFC xxxx)."; 1795 revision 2017-11-15 { 1796 description 1797 "Initial revision. 1798 NOTE TO RFC EDITOR: 1799 (1) Please replace the following reference 1800 to draft-ietf-i2rs-yang-network-topo-18 with 1801 RFC number when published (i.e. RFC xxxx). 1802 (2) Please replace the date in the revision statement with the 1803 date of the publication when published."; 1804 reference 1805 "draft-ietf-i2rs-yang-network-topo-18"; 1806 } 1808 grouping network-ref { 1809 description 1810 "Contains the information necessary to reference a network, 1811 for example an underlay network."; 1812 leaf network-ref { 1813 type leafref { 1814 path "/nw-s:networks/nw-s:network/nw-s:network-id"; 1815 require-instance false; 1816 } 1817 description 1818 "Used to reference a network, for example an underlay 1819 network."; 1820 } 1821 } 1823 grouping node-ref { 1824 description 1825 "Contains the information necessary to reference a node."; 1826 leaf node-ref { 1827 type leafref { 1828 path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+ 1829 "/../network-ref]/nw-s:node/nw-s:node-id"; 1830 require-instance false; 1831 } 1832 description 1833 "Used to reference a node. 1834 Nodes are identified relative to the network they are 1835 contained in."; 1836 } 1837 uses network-ref; 1838 } 1840 container networks { 1841 config false; 1842 description 1843 "Serves as top-level container for a list of networks."; 1844 list network { 1845 key "network-id"; 1846 description 1847 "Describes a network. 1849 A network typically contains an inventory of nodes, 1850 topological information (augmented through 1851 network-topology data model), as well as layering 1852 information."; 1853 container network-types { 1854 description 1855 "Serves as an augmentation target. 1856 The network type is indicated through corresponding 1857 presence containers augmented into this container."; 1858 } 1859 leaf network-id { 1860 type nw:network-id; 1861 description 1862 "Identifies a network."; 1863 } 1864 list supporting-network { 1865 key "network-ref"; 1866 description 1867 "An underlay network, used to represent layered network 1868 topologies."; 1869 leaf network-ref { 1870 type leafref { 1871 path "/nw-s:networks/nw-s:network/nw-s:network-id"; 1872 require-instance false; 1873 } 1874 description 1875 "References the underlay network."; 1876 } 1877 } 1878 list node { 1879 key "node-id"; 1880 description 1881 "The inventory of nodes of this network."; 1882 leaf node-id { 1883 type nw:node-id; 1884 description 1885 "Identifies a node uniquely within the containing 1886 network."; 1887 } 1888 list supporting-node { 1889 key "network-ref node-ref"; 1890 description 1891 "Represents another node, in an underlay network, that 1892 this node is supported by. Used to represent layering 1893 structure."; 1894 leaf network-ref { 1895 type leafref { 1896 path "../../../nw-s:supporting-network/nw-s:network-ref"; 1898 require-instance false; 1899 } 1900 description 1901 "References the underlay network that the 1902 underlay node is part of."; 1903 } 1904 leaf node-ref { 1905 type leafref { 1906 path "/nw-s:networks/nw-s:network/nw-s:node/nw-s:node-id"; 1907 require-instance false; 1908 } 1909 description 1910 "References the underlay node itself."; 1911 } 1912 } 1913 } 1914 } 1915 } 1916 } 1917 1919 B.2. YANG Data Model for Network Topology State 1921 NOTE TO RFC EDITOR: Please change the date in the file name after the 1922 CODE BEGINS statement to the date of the publication when published. 1924 file "ietf-network-topology-state@2017-11-15.yang" 1925 module ietf-network-topology-state { 1926 yang-version 1.1; 1927 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology-state"; 1928 prefix nt-s; 1930 import ietf-network-state { 1931 prefix nw-s; 1932 reference 1933 "draft-ietf-i2rs-yang-network-topo-18 1934 NOTE TO RFC EDITOR: Please replace above reference to 1935 draft-ietf-i2rs-yang-network-topo-18 with RFC 1936 number when published (i.e. RFC xxxx)."; 1937 } 1938 import ietf-network-topology { 1939 prefix nt; 1940 reference 1941 "draft-ietf-i2rs-yang-network-topo-18 1942 NOTE TO RFC EDITOR: Please replace above reference to 1943 draft-ietf-i2rs-yang-network-topo-18 with RFC 1944 number when published (i.e. RFC xxxx)."; 1945 } 1946 organization 1947 "IETF I2RS (Interface to the Routing System) Working Group"; 1949 contact 1950 "WG Web: 1951 WG List: 1953 Editor: Alexander Clemm 1954 1956 Editor: Jan Medved 1957 1959 Editor: Robert Varga 1960 1962 Editor: Nitin Bahadur 1963 1965 Editor: Hariharan Ananthakrishnan 1966 1968 Editor: Xufeng Liu 1969 "; 1971 description 1972 "This module defines a common base data model for network 1973 topology state, representing topology that is either learned, 1974 or topology that results from applying topology that has been 1975 configured per the ietf-network-topology data model, mirroring 1976 the corresponding data nodes in this data model. It augments 1977 the base network state data model with links to connect nodes, 1978 as well as termination points to terminate links on nodes. 1980 The data model mirrors ietf-network-topology, but contains only 1981 read-only state data. The data model is not needed when the 1982 underlying implementation infrastructure supports the Network 1983 Management Datastore Architecture (NMDA). 1985 Copyright (c) 2017 IETF Trust and the persons identified as 1986 authors of the code. All rights reserved. 1988 Redistribution and use in source and binary forms, with or 1989 without modification, is permitted pursuant to, and subject 1990 to the license terms contained in, the Simplified BSD License 1991 set forth in Section 4.c of the IETF Trust's Legal Provisions 1992 Relating to IETF Documents 1993 (http://trustee.ietf.org/license-info). 1994 This version of this YANG module is part of 1995 draft-ietf-i2rs-yang-network-topo-18; 1996 see the RFC itself for full legal notices. 1998 NOTE TO RFC EDITOR: Please replace above reference to 1999 draft-ietf-i2rs-yang-network-topo-18 with RFC 2000 number when published (i.e. RFC xxxx)."; 2002 revision 2017-11-15 { 2003 description 2004 "Initial revision. 2005 NOTE TO RFC EDITOR: 2006 (1) Please replace the following reference 2007 to draft-ietf-i2rs-yang-network-topo-18 with 2008 RFC number when published (i.e. RFC xxxx). 2009 (2) Please replace the date in the revision statement with the 2010 date of publication when published."; 2011 reference 2012 "draft-ietf-i2rs-yang-network-topo-18"; 2013 } 2015 grouping link-ref { 2016 description 2017 "References a link in a specific network. While this grouping 2018 is not used in this module, it is defined here for the 2019 convenience of augmenting modules."; 2020 leaf link-ref { 2021 type leafref { 2022 path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+ 2023 "/../network-ref]/nt-s:link/nt-s:link-id"; 2024 require-instance false; 2025 } 2026 description 2027 "A type for an absolute reference a link instance. 2028 (This type should not be used for relative references. 2029 In such a case, a relative path should be used instead.)"; 2030 } 2031 uses nw-s:network-ref; 2032 } 2034 grouping tp-ref { 2035 description 2036 "References a termination point in a specific node. While 2037 this grouping is not used in this module, it is defined here 2038 for the convenience of augmenting modules."; 2039 leaf tp-ref { 2040 type leafref { 2041 path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+ 2042 "/../network-ref]/nw-s:node[nw-s:node-id=current()/../"+ 2043 "node-ref]/nt-s:termination-point/nt-s:tp-id"; 2044 require-instance false; 2045 } 2046 description 2047 "A type for an absolute reference to a termination point. 2048 (This type should not be used for relative references. 2049 In such a case, a relative path should be used instead.)"; 2050 } 2051 uses nw-s:node-ref; 2052 } 2054 augment "/nw-s:networks/nw-s:network" { 2055 description 2056 "Add links to the network data model."; 2057 list link { 2058 key "link-id"; 2059 description 2060 "A network link connects a local (source) node and 2061 a remote (destination) node via a set of 2062 the respective node's termination points. 2063 It is possible to have several links between the same 2064 source and destination nodes. Likewise, a link could 2065 potentially be re-homed between termination points. 2066 Therefore, in order to ensure that we would always know 2067 to distinguish between links, every link is identified by 2068 a dedicated link identifier. Note that a link models a 2069 point-to-point link, not a multipoint link."; 2070 container source { 2071 description 2072 "This container holds the logical source of a particular 2073 link."; 2074 leaf source-node { 2075 type leafref { 2076 path "../../../nw-s:node/nw-s:node-id"; 2077 require-instance false; 2078 } 2079 description 2080 "Source node identifier, must be in same topology."; 2081 } 2082 leaf source-tp { 2083 type leafref { 2084 path "../../../nw-s:node[nw-s:node-id=current()/../"+ 2085 "source-node]/termination-point/tp-id"; 2086 require-instance false; 2087 } 2088 description 2089 "Termination point within source node that terminates 2090 the link."; 2091 } 2092 } 2093 container destination { 2094 description 2095 "This container holds the logical destination of a 2096 particular link."; 2097 leaf dest-node { 2098 type leafref { 2099 path "../../../nw-s:node/nw-s:node-id"; 2100 require-instance false; 2101 } 2102 description 2103 "Destination node identifier, must be in the same 2104 network."; 2105 } 2106 leaf dest-tp { 2107 type leafref { 2108 path "../../../nw-s:node[nw-s:node-id=current()/../"+ 2109 "dest-node]/termination-point/tp-id"; 2110 require-instance false; 2111 } 2112 description 2113 "Termination point within destination node that 2114 terminates the link."; 2115 } 2116 } 2117 leaf link-id { 2118 type nt:link-id; 2119 description 2120 "The identifier of a link in the topology. 2121 A link is specific to a topology to which it belongs."; 2122 } 2123 list supporting-link { 2124 key "network-ref link-ref"; 2125 description 2126 "Identifies the link, or links, that this link 2127 is dependent on."; 2128 leaf network-ref { 2129 type leafref { 2130 path "../../../nw-s:supporting-network/nw-s:network-ref"; 2131 require-instance false; 2132 } 2133 description 2134 "This leaf identifies in which underlay topology 2135 the supporting link is present."; 2136 } 2137 leaf link-ref { 2138 type leafref { 2139 path "/nw-s:networks/nw-s:network[nw-s:network-id="+ 2140 "current()/../network-ref]/link/link-id"; 2141 require-instance false; 2142 } 2143 description 2144 "This leaf identifies a link which is a part 2145 of this link's underlay. Reference loops in which 2146 a link identifies itself as its underlay, either 2147 directly or transitively, are not allowed."; 2148 } 2149 } 2150 } 2151 } 2152 augment "/nw-s:networks/nw-s:network/nw-s:node" { 2153 description 2154 "Augment termination points which terminate links. 2155 Termination points can ultimately be mapped to interfaces."; 2156 list termination-point { 2157 key "tp-id"; 2158 description 2159 "A termination point can terminate a link. 2160 Depending on the type of topology, a termination point 2161 could, for example, refer to a port or an interface."; 2162 leaf tp-id { 2163 type nt:tp-id; 2164 description 2165 "Termination point identifier."; 2166 } 2167 list supporting-termination-point { 2168 key "network-ref node-ref tp-ref"; 2169 description 2170 "This list identifies any termination points that 2171 the termination point is dependent on, or maps onto. 2172 Those termination points will themselves be contained 2173 in a supporting node. 2174 This dependency information can be inferred from 2175 the dependencies between links. For this reason, 2176 this item is not separately configurable. Hence no 2177 corresponding constraint needs to be articulated. 2178 The corresponding information is simply provided by the 2179 implementing system."; 2180 leaf network-ref { 2181 type leafref { 2182 path "../../../nw-s:supporting-node/nw-s:network-ref"; 2183 require-instance false; 2184 } 2185 description 2186 "This leaf identifies in which topology the 2187 supporting termination point is present."; 2188 } 2189 leaf node-ref { 2190 type leafref { 2191 path "../../../nw-s:supporting-node/nw-s:node-ref"; 2192 require-instance false; 2193 } 2194 description 2195 "This leaf identifies in which node the supporting 2196 termination point is present."; 2197 } 2198 leaf tp-ref { 2199 type leafref { 2200 path "/nw-s:networks/nw-s:network[nw-s:network-id="+ 2201 "current()/../network-ref]/nw-s:node[nw-s:node-id="+ 2202 "current()/../node-ref]/termination-point/tp-id"; 2203 require-instance false; 2204 } 2205 description 2206 "Reference to the underlay node, must be in a 2207 different topology"; 2208 } 2209 } 2210 } 2211 } 2212 } 2214 2216 Appendix C. An Example 2218 This section contains an example of an instance data tree in JSON 2219 encoding [RFC7951]. The example instantiates ietf-network-topology 2220 (and ietf-network, which ietf-network-topology augments) for the 2221 topology that is depicted in the following diagram. There are three 2222 nodes, D1, D2, and D3. D1 has three termination points, 1-0-1, 2223 1-2-1, and 1-3-1. D2 has three termination points as well, 2-1-1, 2224 2-0-1, and 2-3-1. D3 has two termination points, 3-1-1 and 3-2-1. 2225 In addition there are six links, two between each pair of nodes with 2226 one going in each direction. 2228 +------------+ +------------+ 2229 | D1 | | D2 | 2230 /-\ /-\ /-\ /-\ 2231 | | 1-0-1 | |---------------->| | 2-1-1 | | 2232 | | 1-2-1 | |<----------------| | 2-0-1 | | 2233 \-/ 1-3-1 \-/ \-/ 2-3-1 \-/ 2234 | /----\ | | /----\ | 2235 +---| |---+ +---| |---+ 2236 \----/ \----/ 2237 A | A | 2238 | | | | 2239 | | | | 2240 | | +------------+ | | 2241 | | | D3 | | | 2242 | | /-\ /-\ | | 2243 | +----->| | 3-1-1 | |-------+ | 2244 +---------| | 3-2-1 | |<---------+ 2245 \-/ \-/ 2246 | | 2247 +------------+ 2249 Figure 7: A network topology example 2251 The corresponding instance data tree is depicted below: 2253 { 2254 "ietf-network:networks": { 2255 "network": [ 2256 { 2257 "network-types": { 2258 }, 2259 "network-id": "otn-hc", 2260 "node": [ 2261 { 2262 "node-id": "D1", 2263 "termination-point": [ 2264 { 2265 "tp-id": "1-0-1" 2266 }, 2267 { 2268 "tp-id": "1-2-1" 2269 }, 2270 { 2271 "tp-id": "1-3-1" 2272 } 2273 ] 2274 }, 2275 { 2276 "node-id": "D2", 2277 "termination-point": [ 2278 { 2279 "tp-id": "2-0-1" 2280 }, 2281 { 2282 "tp-id": "2-1-1" 2283 }, 2284 { 2285 "tp-id": "2-3-1" 2286 } 2287 ] 2288 }, 2289 { 2290 "node-id": "D3", 2291 "termination-point": [ 2292 { 2293 "tp-id": "3-1-1" 2294 }, 2295 { 2296 "tp-id": "3-2-1" 2297 } 2298 ] 2299 } 2300 ], 2301 "ietf-network-topology:link": [ 2302 { 2303 "link-id": "D1,1-2-1,D2,2-1-1", 2304 "destination": { 2305 "source-node": "D1", 2306 "source-tp": "1-2-1" 2307 } 2308 "destination": { 2309 "dest-node": "D2", 2310 "dest-tp": "2-1-1" 2311 } 2312 }, 2313 { 2314 "link-id": "D2,2-1-1,D1,1-2-1", 2315 "destination": { 2316 "source-node": "D2", 2317 "source-tp": "2-1-1" 2318 } 2319 "destination": { 2320 "dest-node": "D1", 2321 "dest-tp": "1-2-1" 2322 } 2324 }, 2325 { 2326 "link-id": "D1,1-3-1,D3,3-1-1", 2327 "destination": { 2328 "source-node": "D1", 2329 "source-tp": "1-3-1" 2330 } 2331 "destination": { 2332 "dest-node": "D3", 2333 "dest-tp": "3-1-1" 2334 } 2335 }, 2336 { 2337 "link-id": "D3,3-1-1,D1,1-3-1", 2338 "destination": { 2339 "source-node": "D3", 2340 "source-tp": "3-1-1" 2341 } 2342 "destination": { 2343 "dest-node": "D1", 2344 "dest-tp": "1-3-1" 2345 } 2346 }, 2347 { 2348 "link-id": "D2,2-3-1,D3,3-2-1", 2349 "destination": { 2350 "source-node": "D2", 2351 "source-tp": "2-3-1" 2352 } 2353 "destination": { 2354 "dest-node": "D3", 2355 "dest-tp": "3-2-1" 2356 } 2357 }, 2358 { 2359 "link-id": "D3,3-2-1,D2,2-3-1", 2360 "destination": { 2361 "source-node": "D3", 2362 "source-tp": "3-2-1" 2363 } 2364 "destination": { 2365 "dest-node": "D2", 2366 "dest-tp": "2-3-1" 2367 } 2368 } 2369 ] 2370 } 2371 ] 2373 } 2374 } 2376 Figure 8: Instance data tree 2378 Authors' Addresses 2380 Alexander Clemm 2381 Huawei 2383 EMail: ludwig@clemm.org 2385 Jan Medved 2386 Cisco 2388 EMail: jmedved@cisco.com 2390 Robert Varga 2391 Pantheon Technologies SRO 2393 EMail: robert.varga@pantheon.tech 2395 Nitin Bahadur 2396 Bracket Computing 2398 EMail: nitin_bahadur@yahoo.com 2400 Hariharan Ananthakrishnan 2401 Packet Design 2403 EMail: hari@packetdesign.com 2405 Xufeng Liu 2406 Jabil 2408 EMail: Xufeng_Liu@jabil.com