idnits 2.17.1 draft-ietf-i2rs-yang-network-topo-17.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 (October 22, 2017) is 2378 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 223, but not defined == Missing Reference: 'Y5' is mentioned on line 249, but not defined == Missing Reference: 'Z5' is mentioned on line 249, but not defined == Missing Reference: 'Z3' is mentioned on line 249, but not defined == Missing Reference: 'Y4' is mentioned on line 253, but not defined == Missing Reference: 'Y1' is mentioned on line 253, but not defined == Missing Reference: 'Z2' is mentioned on line 253, but not defined == Missing Reference: 'X5' is mentioned on line 262, but not defined == Missing Reference: 'D1' is mentioned on line 734, but not defined == Missing Reference: 'D2' is mentioned on line 734, 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: April 25, 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 October 22, 2017 16 A Data Model for Network Topologies 17 draft-ietf-i2rs-yang-network-topo-17.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 April 25, 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. Appendix: 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. Appendix: Companion YANG models for non-NMDA 99 compliant implementations . . . . . . . . . . . . . 36 100 B.1. YANG Model for Network State . . . . . . . . . . . . . . 37 101 B.2. YANG Data Model for Network Topology State . . . . . . . 41 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 104 1. Introduction 106 This document introduces an abstract (base) YANG [RFC7950] data model 107 to represent networks and topologies. The data model is divided into 108 two parts. The first part of the data model defines a network data 109 model that enables the definition of network hierarchies (i.e. 110 network stacks) and to maintain an inventory of nodes contained in a 111 network. The second part of the data model augments the basic 112 network data model with information to describe topology information. 113 Specifically, it adds the concepts of links and termination points to 114 describe how nodes in a network are connected to each other. 115 Moreover the data model introduces vertical layering relationships 116 between networks that can be augmented to cover both network 117 inventories and network/service topologies. 119 While it would be possible to combine both parts into a single data 120 model, the separation facilitates integration of network topology and 121 network inventory data models, by allowing to augment network 122 inventory information separately and without concern for topology 123 into the network data model. 125 The data model can be augmented to describe specifics of particular 126 types of networks and topologies. For example, an augmenting data 127 model can provide network node information with attributes that are 128 specific to a particular network type. Examples of augmenting models 129 include data models for Layer 2 network topologies, Layer 3 network 130 topologies, such as Unicast IGP, IS-IS [RFC1195] and OSPF [RFC2328], 131 traffic engineering (TE) data [RFC3209], or any of the variety of 132 transport and service topologies. Information specific to particular 133 network types will be captured in separate, technology-specific data 134 models. 136 The basic data models introduced in this document are generic in 137 nature and can be applied to many network and service topologies and 138 inventories. The data models allow applications to operate on an 139 inventory or topology of any network at a generic level, where 140 specifics of particular inventory/topology types are not required. 141 At the same time, where data specific to a network type does comes 142 into play and the data model is augmented, the instantiated data 143 still adheres to the same structure and is represented in consistent 144 fashion. This also facilitates the representation of network 145 hierarchies and dependencies between different network components and 146 network types. 148 The abstract (base) network YANG module introduced in this document, 149 entitled "ietf-network.yang", contains a list of abstract network 150 nodes and defines the concept of network hierarchy (network stack). 151 The abstract network node can be augmented in inventory and topology 152 data models with inventory and topology specific attributes. Network 153 hierarchy (stack) allows any given network to have one or more 154 "supporting networks". The relationship of the base network data 155 model, the inventory data models and the topology data models is 156 shown in the following figure (dotted lines in the figure denote 157 possible augmentations to models defined in this document). 159 +------------------------+ 160 | | 161 | Abstract Network Model | 162 | | 163 +------------------------+ 164 | 165 +-------+-------+ 166 | | 167 V V 168 +------------+ .............. 169 | Abstract | : Inventory : 170 | Topology | : Model(s) : 171 | Model | : : 172 +------------+ '''''''''''''' 173 | 174 +-------------+-------------+-------------+ 175 | | | | 176 V V V V 177 ............ ............ ............ ............ 178 : L1 : : L2 : : L3 : : Service : 179 : Topology : : Topology : : Topology : : Topology : 180 : Model : : Model : : Model : : Model : 181 '''''''''''' '''''''''''' '''''''''''' '''''''''''' 183 Figure 1: The network data model structure 185 The network-topology YANG module introduced in this document, 186 entitled "ietf-network-topology.yang", defines a generic topology 187 data model at its most general level of abstraction. The module 188 defines a topology graph and components from which it is composed: 189 nodes, edges and termination points. Nodes (from the ietf- 190 network.yang module) represent graph vertices and links represent 191 graph edges. Nodes also contain termination points that anchor the 192 links. A network can contain multiple topologies, for example 193 topologies at different layers and overlay topologies. The data 194 model therefore allows to capture relationships between topologies, 195 as well as dependencies between nodes and termination points across 196 topologies. An example of a topology stack is shown in the following 197 figure. 199 +---------------------------------------+ 200 / _[X1]_ "Service" / 201 / _/ : \_ / 202 / _/ : \_ / 203 / _/ : \_ / 204 / / : \ / 205 / [X2]__________________[X3] / 206 +---------:--------------:------:-------+ 207 : : : 208 +----:--------------:----:--------------+ 209 / : : : "L3" / 210 / : : : / 211 / : : : / 212 / [Y1]_____________[Y2] / 213 / * * * / 214 / * * * / 215 +--------------*-------------*--*-------+ 216 * * * 217 +--------*----------*----*--------------+ 218 / [Z1]_______________[Z1] "Optical" / 219 / \_ * _/ / 220 / \_ * _/ / 221 / \_ * _/ / 222 / \ * / / 223 / [Z] / 224 +---------------------------------------+ 226 Figure 2: Topology hierarchy (stack) example 228 The figure shows three topology levels. At top, the "Service" 229 topology shows relationships between service entities, such as 230 service functions in a service chain. The "L3" topology shows 231 network elements at Layer 3 (IP) and the "Optical" topology shows 232 network elements at Layer 1. Service functions in the "Service" 233 topology are mapped onto network elements in the "L3" topology, which 234 in turn are mapped onto network elements in the "Optical" topology. 235 The figure shows two Service Functions (X1 and X2) mapping onto a 236 single L3 network element (Y2); this could happen, for example, if 237 two service functions reside in the same VM (or server) and share the 238 same set of network interfaces. The figure shows a single "L3" 239 network element mapped onto multiple "Optical" network elements. 241 This could happen, for example, if a single IP router attaches to 242 multiple ROADMs in the optical domain. 244 Another example of a service topology stack is shown in the following 245 figure. 247 VPN1 VPN2 248 +---------------------+ +---------------------+ 249 / [Y5]... / / [Z5]______[Z3] / 250 / / \ : / / : \_ / : / 251 / / \ : / / : \_ / : / 252 / / \ : / / : \ / : / 253 / [Y4]____[Y1] : / / : [Z2] : / 254 +------:-------:---:--+ +---:---------:-----:-+ 255 : : : : : : 256 : : : : : : 257 : +-------:---:-----:------------:-----:-----+ 258 : / [X1]__:___:___________[X2] : / 259 :/ / \_ : : _____/ / : / 260 : / \_ : _____/ / : / 261 /: / \: / / : / 262 / : / [X5] / : / 263 / : / __/ \__ / : / 264 / : / ___/ \__ / : / 265 / : / ___/ \ / : / 266 / [X4]__________________[X3]..: / 267 +------------------------------------------+ 268 L3 Topology 270 Figure 3: Topology hierarchy (stack) example 272 The figure shows two VPN service topologies (VPN1 and VPN2) 273 instantiated over a common L3 topology. Each VPN service topology is 274 mapped onto a subset of nodes from the common L3 topology. 276 There are multiple applications for such a data model. For example, 277 within the context of I2RS, nodes within the network can use the data 278 model to capture their understanding of the overall network topology 279 and expose it to a network controller. A network controller can then 280 use the instantiated topology data to compare and reconcile its own 281 view of the network topology with that of the network elements that 282 it controls. Alternatively, nodes within the network could propagate 283 this understanding to compare and reconcile this understanding either 284 among themselves or with help of a controller. Beyond the network 285 element and the immediate context of I2RS itself, a network 286 controller might even use the data model to represent its view of the 287 topology that it controls and expose it to applications north of 288 itself. Further use cases that the data model can be applied to are 289 described in [I-D.draft-ietf-i2rs-usecase-reqs-summary]. 291 In this data model, a network is categorized as either system 292 controlled or not. If a network is system controlled, then it is 293 automatically populated by the server and represents dynamically 294 learned information that can be read from the operational datastore. 295 The data model can also be used to create or modify network 296 topologies such as might be associated with an inventory or with an 297 overlay network. Such a network is not system controlled but 298 configured by a client. 300 The data model allows a network to refer to a supporting-network, 301 supporting-nodes, supporting-links, etc. The data model also allows 302 to layer a network that is configured on top of one that is system 303 controlled. This permits the configuration of overlay networks on 304 top of networks that are discovered. Specifically, this data model 305 is structured to support being implemented as part of the ephemeral 306 datastore [I-D.draft-ietf-netmod-revised-datastores], defined as 307 requirement Ephemeral-REQ-03 in 308 [I-D.draft-ietf-i2rs-ephemeral-state]. This allows network topology 309 data that is written, i.e. configured by a client and not system 310 controlled, to refer to a dynamically learned data that is controlled 311 by the system, not configured by a client. A simple use case might 312 involve creating an overlay network that is supported by the 313 dynamically discovered IP routed network topology. When an 314 implementation places written data for this data model in the 315 ephemeral data store, then such a network MAY refer to another 316 network that is system controlled. 318 2. Key Words 320 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 321 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 322 "OPTIONAL" in this document are to be interpreted as described in BCP 323 14 [RFC2119] [RFC8174] when, and only when, they appear in all 324 capitals, as shown here. 326 3. Definitions and Acronyms 328 Datastore: A conceptual place to store and access information. A 329 datastore might be implemented, for example, using files, a database, 330 flash memory locations, or combinations thereof. A datastore maps to 331 an instantiated YANG data tree. 333 Data subtree: An instantiated data node and the data nodes that are 334 hierarchically contained within it. 336 HTTP: Hyper-Text Transfer Protocol 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 ReST: Representational State Transfer, a style of stateless interface 347 and protocol that is generally carried over HTTP 349 4. Model Structure Details 351 4.1. Base Network Model 353 The abstract (base) network data model is defined in the ietf- 354 network.yang module. Its structure is shown in the following figure. 355 The notation syntax follows 356 [I-D.draft-ietf-netmod-yang-tree-diagrams]. 358 module: ietf-network 359 +--rw networks 360 +--rw network* [network-id] 361 +--rw network-id network-id 362 +--rw network-types 363 +--rw supporting-network* [network-ref] 364 | +--rw network-ref -> /networks/network/network-id 365 +--rw node* [node-id] 366 +--rw node-id node-id 367 +--rw supporting-node* [network-ref node-ref] 368 +--rw network-ref -> ../../../supporting-network/ + 369 | network-ref 370 +--rw node-ref -> /networks/network/node/node-id 372 Figure 4: The structure of the abstract (base) network data model 374 The data model contains a container with a list of networks. Each 375 network is captured in its own list entry, distinguished via a 376 network-id. 378 A network has a certain type, such as L2, L3, OSPF or IS-IS. A 379 network can even have multiple types simultaneously. The type, or 380 types, are captured underneath the container "network-types". In 381 this module it serves merely as an augmentation target; network- 382 specific modules will later introduce new data nodes to represent new 383 network types below this target, i.e. insert them below "network- 384 types" by ways of YANG augmentation. 386 When a network is of a certain type, it will contain a corresponding 387 data node. Network types SHOULD always be represented using presence 388 containers, not leafs of empty type. This allows representation of 389 hierarchies of network subtypes within the instance information. For 390 example, an instance of an OSPF network (which, at the same time, is 391 a layer 3 unicast IGP network) would contain underneath "network- 392 types" another presence container "l3-unicast-igp-network", which in 393 turn would contain a presence container "ospf-network". Actual 394 examples of this pattern can be found in 395 [I-D.draft-ietf-i2rs-yang-l3-topology]. 397 A network can in turn be part of a hierarchy of networks, building on 398 top of other networks. Any such networks are captured in the list 399 "supporting-network". A supporting network is in effect an underlay 400 network. 402 Furthermore, a network contains an inventory of nodes that are part 403 of the network. The nodes of a network are captured in their own 404 list. Each node is identified relative to its containing network by 405 a node-id. 407 It should be noted that a node does not exist independently of a 408 network; instead it is a part of the network that it is contained in. 409 In cases where the same entity takes part in multiple networks, or at 410 multiple layers of a networking stack, the same entity will be 411 represented by multiple nodes, one for each network. In other words, 412 the node represents an abstraction of the device for the particular 413 network that it a is part of. To represent that the same entity or 414 same device is part of multiple topologies or networks, it is 415 possible to create one "physical" network with a list of nodes for 416 each of the devices or entities. This (physical) network, 417 respectively the (entities) nodes in that network, can then be 418 referred to as underlay network and nodes from the other (logical) 419 networks and nodes, respectively. Note that the data model allows 420 definition of more than one underlay network (and node), allowing for 421 simultaneous representation of layered network- and service 422 topologies and physical instantiation. 424 Similar to a network, a node can be supported by other nodes, and map 425 onto one or more other nodes in an underlay network. This is 426 captured in the list "supporting-node". The resulting hierarchy of 427 nodes allows also representation of device stacks, where a node at 428 one level is supported by a set of nodes at an underlying level. For 429 example, a "router" node might be supported by a node representing a 430 route processor and separate nodes for various line cards and service 431 modules, a virtual router might be supported or hosted on a physical 432 device represented by a separate node, and so on. 434 Network data of a network at a particular layer can come into being 435 in one of two ways. In one way, network data is configured by client 436 applications, for example in case of overlay networks that are 437 configured by an SDN Controller application. In another way, it is 438 automatically populated by the server, in case of networks that can 439 be discovered. It is possible for a configured (overlay) network to 440 refer to a (discovered) underlay network. 442 The revised datastore architecture 443 [I-D.draft-ietf-netmod-revised-datastores] is used to account for 444 those possibilities. Specifically, for each network, the origin of 445 its data is indicated per the "origin" metadata annotation - 446 "intended" for data that was configured by a client application, 447 "learned" for data that is discovered. Network data that is 448 discovered is automatically populated as part of the operational 449 datastore. Network data that is configured is part of the 450 configuration and intended datastores, respectively. Configured 451 network data that is actually in effect is in addition reflected in 452 the operational datastore. Data in the operational datastore will 453 always have complete referential integrity. Should a configured data 454 item (such as a node) have a dangling reference that refers to a non- 455 existing data item (such as a supporting node), the configured data 456 item will automatically be removed from the operational datastore and 457 thus only appear in the intended datastore. It will be up to the 458 client application to resolve the situation and ensure that the 459 reference to the supporting resources is configured properly. 461 4.2. Base Network Topology Data Model 463 The abstract (base) network topology data model is defined in the 464 "ietf-network-topology.yang" module. It builds on the network data 465 model defined in the "ietf-network.yang" module, augmenting it with 466 links (defining how nodes are connected) and termination-points 467 (which anchor the links and are contained in nodes). The structure 468 of the network topology module is shown in the following figure. The 469 notation syntax follows [I-D.draft-ietf-netmod-yang-tree-diagrams]. 471 module: ietf-network-topology 472 augment /nw:networks/nw:network: 473 +--rw link* [link-id] 474 +--rw link-id link-id 475 +--rw source 476 | +--rw source-node? -> ../../../nw:node/node-id 477 | +--rw source-tp? -> ../../../nw:node[nw:node-id=current()/+ 478 | ../source-node]/termination-point/tp-id 479 +--rw destination 480 | +--rw dest-node? -> ../../../nw:node/node-id 481 | +--rw dest-tp? -> ../../../nw:node[nw:node-id=current()/+ 482 | ../dest-node]/termination-point/tp-id 483 +--rw supporting-link* [network-ref link-ref] 484 +--rw network-ref -> ../../../nw:supporting-network/+ 485 | network-ref 486 +--rw link-ref -> /nw:networks/network+ 487 [nw:network-id=current()/../network-ref]/+ 488 link/link-id 489 augment /nw:networks/nw:network/nw:node: 490 +--rw termination-point* [tp-id] 491 +--rw tp-id tp-id 492 +--rw supporting-termination-point* [network-ref node-ref tp-ref] 493 +--rw network-ref -> ../../../nw:supporting-node/network-ref 494 +--rw node-ref -> ../../../nw:supporting-node/node-ref 495 +--rw tp-ref -> /nw:networks/network[nw:network-id=+ 496 current()/../network-ref]/node+ 497 [nw:node-id=current()/../node-ref]/+ 498 termination-point/tp-id 500 Figure 5: The structure of the abstract (base) network topology data 501 model 503 A node has a list of termination points that are used to terminate 504 links. An example of a termination point might be a physical or 505 logical port or, more generally, an interface. 507 Like a node, a termination point can in turn be supported by an 508 underlying termination point, contained in the supporting node of the 509 underlay network. 511 A link is identified by a link-id that uniquely identifies the link 512 within a given topology. Links are point-to-point and 513 unidirectional. Accordingly, a link contains a source and a 514 destination. Both source and destination reference a corresponding 515 node, as well as a termination point on that node. Similar to a 516 node, a link can map onto one or more links in an underlay topology 517 (which are terminated by the corresponding underlay termination 518 points). This is captured in the list "supporting-link". 520 4.3. Extending the data model 522 In order to derive a data model for a specific type of network, the 523 base data model can be extended. This can be done roughly as 524 follows: for the new network type, a new YANG module is introduced. 525 In this module, a number of augmentations are defined against the 526 network and network-topology YANG modules. 528 We start with augmentations against the ietf-network.yang module. 529 First, a new network type needs to be defined. For this, a presence 530 container that resembles the new network type is defined. It is 531 inserted by means of augmentation below the network-types container. 532 Subsequently, data nodes for any network-type specific node 533 parameters are defined and augmented into the node list. The new 534 data nodes can be defined as conditional ("when") on the presence of 535 the corresponding network type in the containing network. In cases 536 where there are any requirements or restrictions in terms of network 537 hierarchies, such as when a network of a new network-type requires a 538 specific type of underlay network, it is possible to define 539 corresponding constraints as well and augment the supporting-network 540 list accordingly. However, care should be taken to avoid excessive 541 definitions of constraints. 543 Subsequently, augmentations are defined against ietf-network- 544 topology.yang. Data nodes are defined both for link parameters, as 545 well as termination point parameters, that are specific to the new 546 network type. Those data nodes are inserted by way of augmentation 547 into the link and termination-point lists, respectively. Again, data 548 nodes can be defined as conditional on the presence of the 549 corresponding network-type in the containing network, by adding a 550 corresponding "when"-statement. 552 It is possible, but not required, to group data nodes for a given 553 network-type under a dedicated container. Doing so introduces 554 further structure, but lengthens data node path names. 556 In cases where a hierarchy of network types is defined, augmentations 557 can in turn be applied against augmenting modules, with the module of 558 a network "sub-type" augmenting the module of a network "super-type". 560 4.4. Discussion and selected design decisions 562 4.4.1. Container structure 564 Rather than maintaining lists in separate containers, the data model 565 is kept relatively flat in terms of its containment structure. Lists 566 of nodes, links, termination-points, and supporting-nodes, 567 supporting-links, and supporting-termination-points are not kept in 568 separate containers. Therefore, path specifiers used to refer to 569 specific nodes, be it in management operations or in specifications 570 of constraints, can remain relatively compact. Of course, this means 571 there is no separate structure in instance information that separates 572 elements of different lists from one another. Such structure is 573 semantically not required, although it might enhance human 574 readability in some cases. 576 4.4.2. Underlay hierarchies and mappings 578 To minimize assumptions of what a particular entity might actually 579 represent, mappings between networks, nodes, links, and termination 580 points are kept strictly generic. For example, no assumptions are 581 made whether a termination point actually refers to an interface, or 582 whether a node refers to a specific "system" or device; the data 583 model at this generic level makes no provisions for that. 585 Where additional specifics about mappings between upper and lower 586 layers are required, those can be captured in augmenting modules. 587 For example, to express that a termination point in a particular 588 network type maps to an interface, an augmenting module can introduce 589 an augmentation to the termination point which introduces a leaf of 590 type ifref that references the corresponding interface [RFC7223]. 591 Similarly, if a node maps to a particular device or network element, 592 an augmenting module can augment the node data with a leaf that 593 references the network element. 595 It is possible for links at one level of a hierarchy to map to 596 multiple links at another level of the hierarchy. For example, a VPN 597 topology might model VPN tunnels as links. Where a VPN tunnel maps 598 to a path that is composed of a chain of several links, the link will 599 contain a list of those supporting links. Likewise, it is possible 600 for a link at one level of a hierarchy to aggregate a bundle of links 601 at another level of the hierarchy. 603 4.4.3. Dealing with changes in underlay networks 605 It is possible for a network to undergo churn even as other networks 606 are layered on top of it. When a supporting node, link, or 607 termination point is deleted, the supporting leafrefs in the overlay 608 will be left dangling. To allow for this possibility, the data model 609 makes use of the "require-instance" construct of YANG 1.1 [RFC7950]. 611 A dangling leafref of a configured object leaves the corresponding 612 instance in a state in which it lacks referential integrity, 613 rendering it in effect inoperational. Any corresponding object 614 instance is therefore removed from the operational datastore until 615 the situation has been resolved, i.e. until either the supporting 616 object is added to the operational datastore, or until the instance 617 is reconfigured to refer to another object that is actually reflected 618 in the operational datastore. It does remain part of the intended 619 datastore. 621 It is the responsibility of the application maintaining the overlay 622 to deal with the possibility of churn in the underlay network. When 623 a server receives a request to configure an overlay network, it 624 SHOULD validate whether supporting nodes/links/tps refer to nodes in 625 the underlay are actually in existence, i.e. nodes which are 626 reflected in the operational datastore. Configuration requests in 627 which supporting nodes/links/tps refer to objects currently not in 628 existence SHOULD be rejected. It is the responsibility of the 629 application to update the overlay when a supporting node/link/tp is 630 deleted at a later point in time. For this purpose, an application 631 might subscribe to updates when changes to the underlay occur, for 632 example using mechanisms defined in 633 [I-D.draft-ietf-netconf-yang-push]. 635 4.4.4. Use of groupings 637 The data model makes use of groupings, instead of simply defining 638 data nodes "in-line". This allows to more easily include the 639 corresponding data nodes in notifications, which then do not need to 640 respecify each data node that is to be included. The tradeoff for 641 this is that it makes the specification of constraints more complex, 642 because constraints involving data nodes outside the grouping need to 643 be specified in conjunction with a "uses" statement where the 644 grouping is applied. This also means that constraints and XPath- 645 statements need to be specified in such a way that they navigate 646 "down" first and select entire sets of nodes, as opposed to being 647 able to simply specify them against individual data nodes. 649 4.4.5. Cardinality and directionality of links 651 The topology data model includes links that are point-to-point and 652 unidirectional. It does not directly support multipoint and 653 bidirectional links. While this may appear as a limitation, it does 654 keep the data model simple, generic, and allows it to very easily be 655 subjected to applications that make use of graph algorithms. Bi- 656 directional connections can be represented through pairs of 657 unidirectional links. Multipoint networks can be represented through 658 pseudo-nodes (similar to IS-IS, for example). By introducing 659 hierarchies of nodes, with nodes at one level mapping onto a set of 660 other nodes at another level, and introducing new links for nodes at 661 that level, topologies with connections representing non-point-to- 662 point communication patterns can be represented. 664 4.4.6. Multihoming and link aggregation 666 Links are terminated by a single termination point, not sets of 667 termination points. Connections involving multihoming or link 668 aggregation schemes need to be represented using multiple point-to- 669 point links, then defining a link at a higher layer that is supported 670 by those individual links. 672 4.4.7. Mapping redundancy 674 In a hierarchy of networks, there are nodes mapping to nodes, links 675 mapping to links, and termination points mapping to termination 676 points. Some of this information is redundant. Specifically, if the 677 link-to-links mapping is known, and the termination points of each 678 link are known, termination point mapping information can be derived 679 via transitive closure and does not have to be explicitly configured. 680 Nonetheless, in order to not constrain applications regarding which 681 mappings they want to configure and which should be derived, the data 682 model does provide for the option to configure this information 683 explicitly. The data model includes integrity constraints to allow 684 for validating for consistency. 686 4.4.8. Typing 688 A network's network types are represented using a container which 689 contains a data node for each of its network types. A network can 690 encompass several types of network simultaneously, hence a container 691 is used instead of a case construct, with each network type in turn 692 represented by a dedicated presence container itself. The reason for 693 not simply using an empty leaf, or even simpler, do away even with 694 the network container and just use a leaf-list of network-type 695 instead, is to be able to represent "class hierarchies" of network 696 types, with one network type refining the other. Network-type 697 specific containers are to be defined in the network-specific 698 modules, augmenting the network-types container. 700 4.4.9. Representing the same device in multiple networks 702 One common requirement concerns the ability to represent that the 703 same device can be part of multiple networks and topologies. 704 However, the data model defines a node as relative to the network 705 that it is contained in. The same node cannot be part of multiple 706 topologies. In many cases, a node will be the abstraction of a 707 particular device in a network. To reflect that the same device is 708 part of multiple topologies, the following approach might be chosen: 709 A new type of network to represent a "physical" (or "device") network 710 is introduced, with nodes representing devices. This network forms 711 an underlay network for logical networks above it, with nodes of the 712 logical network mapping onto nodes in the physical network. 714 This scenario is depicted in the following figure. It depicts three 715 networks with two nodes each. A physical network P consists of an 716 inventory of two nodes, D1 and D2, each representing a device. A 717 second network, X, has a third network, Y, as its underlay. Both X 718 and Y also have the physical network P as underlay. X1 has both Y1 719 and D1 as underlay nodes, while Y1 has D1 as underlay node. 720 Likewise, X2 has both Y2 and D2 as underlay nodes, while Y2 has D2 as 721 underlay node. The fact that X1 and Y1 are both instantiated on the 722 same physical node D1 can be easily derived. 724 +---------------------+ 725 / [X1]____[X2] / X(Service Overlay) 726 +----:--:----:--------+ 727 ..: :..: : 728 ........: ....: : :.... 729 +-----:-------------:--+ : :... 730 / [Y1]____[Y2]....: / :.. : 731 +------|-------|-------+ :.. :... 732 Y(L3) | +---------------------:-----+ : 733 | +----:----|-:----------+ 734 +------------------------/---[D1] [D2] / 735 +----------------------+ 736 P (Physical network) 738 Figure 6: Topology hierarchy example - multiple underlays 740 In the case of a physical network, nodes represent physical devices 741 and termination points physical ports. It should be noted that it is 742 also conceivable to augment the data model for a physical network- 743 type, defining augmentations that have nodes reference system 744 information and termination points reference physical interfaces, in 745 order to provide a bridge between network and device models. 747 4.4.10. Supporting client-configured and system-controlled network 748 topology 750 YANG requires data nodes to be designated as either configuration 751 ("config true") or operational data ("config false"), but not both, 752 yet it is important to have all network information, including 753 vertical cross-network dependencies, captured in one coherent data 754 model. In most cases, network topology information is discovered 755 about a network; the topology is considered a property of the network 756 that is reflected in the data model. That said, certain types of 757 topology need to also be configurable by an application, such as in 758 the case of overlay topologies. 760 The YANG data model for network topology designates all data as 761 "config true". The distinction between data that is actually 762 configured and data that is in effect, including data that is 763 discovered about the network, is provided through the datastores 764 introduced as part of the Network Management Datastore Architecture, 765 NMDA [I-D.draft-ietf-netmod-revised-datastores]. Network topology 766 data that is discovered is automatically populated as part of the 767 operational datastore, . It is "system controlled". 768 Network topology that is configured is instantiated as part of a 769 configuration datastore, e.g. . Only when it has actually 770 taken effect, it is also instantiated as part of the operational 771 datastore, i.e. . 773 Configured network topology will in general refer to an underlay 774 topology and include layering information, such as the supporting 775 node(s) underlying a node, supporting link(s) underlying a link, and 776 supporting termination point(s) underlying a termination point. The 777 supporting objects must be instantiated in the operational datastore 778 in order for the dependent overlay object to be reflected in the 779 operational datastore. Should a configured data item (such as a 780 node) have a dangling reference that refers to a non-existing data 781 item (such as a supporting node), the configured data item will 782 automatically be removed from and show up only in the 783 . It will be up to the client application to resolve the 784 situation and ensure that the reference to the supporting resources 785 is configured properly. 787 For each network, the origin of its data is indicated per the 788 "origin" metadata [RFC7952] annotation defined in 789 [I-D.draft-ietf-netmod-revised-datastores]. In general, the origin 790 of discovered network data is "learned"; the origin of configured 791 network data is "intended". 793 4.4.11. Identifiers of string or URI type 795 The current data model defines identifiers of nodes, networks, links, 796 and termination points as URIs. An alternative would define them as 797 string. 799 The case for strings is that they will be easier to implement. The 800 reason for choosing URIs is that the topology/node/tp exists in a 801 larger context, hence it is useful to be able to correlate 802 identifiers across systems. While strings, being the universal data 803 type, are easier for human beings (a string is a string is a string), 804 they also muddle things. What typically happens is that strings have 805 some structure which is magically assigned and the knowledge of this 806 structure has to be communicated to each system working with the 807 data. A URI makes the structure explicit and also attaches 808 additional semantics: the URI, unlike a free-form string, can be fed 809 into a URI resolver, which can point to additional resources 810 associated with the URI. This property is important when the 811 topology data is integrated into a larger, more complex system. 813 5. Interactions with Other YANG Modules 815 The data model makes use of data types that have been defined in 816 [RFC6991]. 818 This is a protocol independent YANG data model with topology 819 information. It is separate from and not linked with data models 820 that are used to configure routing protocols or routing information. 821 This includes e.g. data model "ietf-routing" [RFC8022]. 823 The data model obeys the requirements for the ephemeral state found 824 in the document [I-D.draft-ietf-i2rs-ephemeral-state]. For ephemeral 825 topology data that is system controlled, the process tasked with 826 maintaining topology information will load information from the 827 routing process (such as OSPF) into the without relying 828 on a configuration datastore. 830 6. YANG Modules 832 6.1. Defining the Abstract Network: ietf-network.yang 834 NOTE TO RFC EDITOR: Please change the date in the file name after the 835 CODE BEGINS statement to the date of publication when published. 837 file "ietf-network@2017-10-22.yang" 838 module ietf-network { 839 yang-version 1.1; 840 namespace "urn:ietf:params:xml:ns:yang:ietf-network"; 841 prefix nw; 843 import ietf-inet-types { 844 prefix inet; 845 reference "RFC 6991"; 846 } 848 organization 849 "IETF I2RS (Interface to the Routing System) Working Group"; 851 contact 852 "WG Web: 853 WG List: 855 Editor: Alexander Clemm 856 858 Editor: Jan Medved 859 861 Editor: Robert Varga 862 864 Editor: Nitin Bahadur 865 867 Editor: Hariharan Ananthakrishnan 868 870 Editor: Xufeng Liu 871 "; 873 description 874 "This module defines a common base data model for a collection 875 of nodes in a network. Node definitions are further used 876 in network topologies and inventories. 878 Copyright (c) 2017 IETF Trust and the persons identified as 879 authors of the code. All rights reserved. 881 Redistribution and use in source and binary forms, with or 882 without modification, is permitted pursuant to, and subject 883 to the license terms contained in, the Simplified BSD License 884 set forth in Section 4.c of the IETF Trust's Legal Provisions 885 Relating to IETF Documents 886 (http://trustee.ietf.org/license-info). 888 This version of this YANG module is part of 889 draft-ietf-i2rs-yang-network-topo-17; 890 see the RFC itself for full legal notices. 892 NOTE TO RFC EDITOR: Please replace above reference to 893 draft-ietf-i2rs-yang-network-topo-17 with RFC 894 number when published (i.e. RFC xxxx)."; 896 revision 2017-10-22 { 897 description 898 "Initial revision. 899 NOTE TO RFC EDITOR: 900 (1) Please replace the following reference 901 to draft-ietf-i2rs-yang-network-topo-17 with 902 RFC number when published (i.e. RFC xxxx). 903 (2) Please replace the date in the revision statement with the 904 date of publication when published. "; 905 reference 906 "draft-ietf-i2rs-yang-network-topo-17"; 907 } 909 typedef node-id { 910 type inet:uri; 911 description 912 "Identifier for a node. The precise structure of the node-id 913 will be up to the implementation. Some implementations MAY 914 for example, pick a uri that includes the network-id as 915 part of the path. The identifier SHOULD be chosen such that 916 the same node in a real network topology will always be 917 identified through the same identifier, even if the data model 918 is instantiated in separate datastores. An implementation MAY 919 choose to capture semantics in the identifier, for example to 920 indicate the type of node."; 921 } 923 typedef network-id { 924 type inet:uri; 925 description 926 "Identifier for a network. The precise structure of the 927 network-id will be up to an implementation. 928 The identifier SHOULD be chosen such that the same network 929 will always be identified through the same identifier, 930 even if the data model is instantiated in separate datastores. 931 An implementation MAY choose to capture semantics in the 932 identifier, for example to indicate the type of network."; 933 } 935 grouping network-ref { 936 description 937 "Contains the information necessary to reference a network, 938 for example an underlay network."; 939 leaf network-ref { 940 type leafref { 941 path "/nw:networks/nw:network/nw:network-id"; 942 require-instance false; 943 } 944 description 945 "Used to reference a network, for example an underlay 946 network."; 947 } 948 } 949 grouping node-ref { 950 description 951 "Contains the information necessary to reference a node."; 952 leaf node-ref { 953 type leafref { 954 path "/nw:networks/nw:network[nw:network-id=current()/../"+ 955 "network-ref]/nw:node/nw:node-id"; 956 require-instance false; 957 } 958 description 959 "Used to reference a node. 960 Nodes are identified relative to the network they are 961 contained in."; 962 } 963 uses network-ref; 964 } 966 container networks { 967 description 968 "Serves as top-level container for a list of networks."; 969 list network { 970 key "network-id"; 971 description 972 "Describes a network. 973 A network typically contains an inventory of nodes, 974 topological information (augmented through 975 network-topology data model), as well as layering 976 information."; 977 leaf network-id { 978 type network-id; 979 description 980 "Identifies a network."; 981 } 982 container network-types { 983 description 984 "Serves as an augmentation target. 985 The network type is indicated through corresponding 986 presence containers augmented into this container."; 987 } 988 list supporting-network { 989 key "network-ref"; 990 description 991 "An underlay network, used to represent layered network 992 topologies."; 993 leaf network-ref { 994 type leafref { 995 path "/nw:networks/nw:network/nw:network-id"; 996 require-instance false; 997 } 998 description 999 "References the underlay network."; 1000 } 1001 } 1002 list node { 1003 key "node-id"; 1004 description 1005 "The inventory of nodes of this network."; 1006 leaf node-id { 1007 type node-id; 1008 description 1009 "Identifies a node uniquely within the containing 1010 network."; 1011 } 1012 list supporting-node { 1013 key "network-ref node-ref"; 1014 description 1015 "Represents another node, in an underlay network, that 1016 this node is supported by. Used to represent layering 1017 structure."; 1018 leaf network-ref { 1019 type leafref { 1020 path "../../../nw:supporting-network/nw:network-ref"; 1021 require-instance false; 1022 } 1023 description 1024 "References the underlay network that the 1025 underlay node is part of."; 1026 } 1027 leaf node-ref { 1028 type leafref { 1029 path "/nw:networks/nw:network/nw:node/nw:node-id"; 1030 require-instance false; 1031 } 1032 description 1033 "References the underlay node itself."; 1034 } 1035 } 1036 } 1037 } 1038 } 1039 } 1041 1043 6.2. Creating Abstract Network Topology: ietf-network-topology.yang 1045 NOTE TO RFC EDITOR: Please change the date in the file name after the 1046 CODE BEGINS statement to the date of publication when published. 1048 file "ietf-network-topology@2017-10-22.yang" 1049 module ietf-network-topology { 1050 yang-version 1.1; 1051 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology"; 1052 prefix nt; 1054 import ietf-inet-types { 1055 prefix inet; 1056 reference 1057 "RFC 6991"; 1058 } 1059 import ietf-network { 1060 prefix nw; 1061 reference 1062 "draft-ietf-i2rs-yang-network-topo-17 1063 NOTE TO RFC EDITOR: 1064 (1) Please replace above reference to 1065 draft-ietf-i2rs-yang-network-topo-17 with RFC 1066 number when published (i.e. RFC xxxx). 1067 (2) Please replace the date in the revision statement with the 1068 date of publication when published."; 1069 } 1071 organization 1072 "IETF I2RS (Interface to the Routing System) Working Group"; 1074 contact 1075 "WG Web: 1076 WG List: 1078 Editor: Alexander Clemm 1079 1081 Editor: Jan Medved 1082 1084 Editor: Robert Varga 1085 1087 Editor: Nitin Bahadur 1088 1090 Editor: Hariharan Ananthakrishnan 1091 1093 Editor: Xufeng Liu 1094 "; 1096 description 1097 "This module defines a common base model for network topology, 1098 augmenting the base network data model with links to connect 1099 nodes, as well as termination points to terminate links on nodes. 1101 Copyright (c) 2017 IETF Trust and the persons identified as 1102 authors of the code. All rights reserved. 1104 Redistribution and use in source and binary forms, with or 1105 without modification, is permitted pursuant to, and subject 1106 to the license terms contained in, the Simplified BSD License 1107 set forth in Section 4.c of the IETF Trust's Legal Provisions 1108 Relating to IETF Documents 1109 (http://trustee.ietf.org/license-info). 1111 This version of this YANG module is part of 1112 draft-ietf-i2rs-yang-network-topo-17; 1113 see the RFC itself for full legal notices. 1115 NOTE TO RFC EDITOR: Please replace above reference to 1116 draft-ietf-i2rs-yang-network-topo-17 with RFC 1117 number when published (i.e. RFC xxxx)."; 1119 revision 2017-10-22 { 1120 description 1121 "Initial revision. 1122 NOTE TO RFC EDITOR: Please replace the following reference 1123 to draft-ietf-i2rs-yang-network-topo-17 with 1124 RFC number when published (i.e. RFC xxxx)."; 1125 reference 1126 "draft-ietf-i2rs-yang-network-topo-17"; 1127 } 1129 typedef link-id { 1130 type inet:uri; 1131 description 1132 "An identifier for a link in a topology. 1133 The precise structure of the link-id 1134 will be up to the implementation. 1135 The identifier SHOULD be chosen such that the same link in a 1136 real network topology will always be identified through the 1137 same identifier, even if the data model is instantiated in 1138 separate datastores. An implementation MAY choose to capture 1140 semantics in the identifier, for example to indicate the type 1141 of link and/or the type of topology that the link is a part 1142 of."; 1143 } 1145 typedef tp-id { 1146 type inet:uri; 1147 description 1148 "An identifier for termination points (TPs) on a node. 1149 The precise structure of the tp-id 1150 will be up to the implementation. 1151 The identifier SHOULD be chosen such that the same termination 1152 point in a real network topology will always be identified 1153 through the same identifier, even if the data model is 1154 instantiated in separate datastores. An implementation MAY 1155 choose to capture semantics in the identifier, for example to 1156 indicate the type of termination point and/or the type of node 1157 that contains the termination point."; 1158 } 1160 grouping link-ref { 1161 description 1162 "This grouping can be used to reference a link in a specific 1163 network. While it is not used in this module, it is defined 1164 here for the convenience of augmenting modules."; 1165 leaf link-ref { 1166 type leafref { 1167 path "/nw:networks/nw:network[nw:network-id=current()/../"+ 1168 "network-ref]/nt:link/nt:link-id"; 1169 require-instance false; 1170 } 1171 description 1172 "A type for an absolute reference a link instance. 1173 (This type should not be used for relative references. 1174 In such a case, a relative path should be used instead.)"; 1175 } 1176 uses nw:network-ref; 1177 } 1179 grouping tp-ref { 1180 description 1181 "This grouping can be used to references a termination point 1182 in a specific node. While it is not used in this module, it 1183 is defined here for the convenience of augmenting modules."; 1184 leaf tp-ref { 1185 type leafref { 1186 path "/nw:networks/nw:network[nw:network-id=current()/../"+ 1187 "network-ref]/nw:node[nw:node-id=current()/../"+ 1188 "node-ref]/nt:termination-point/nt:tp-id"; 1189 require-instance false; 1190 } 1191 description 1192 "A type for an absolute reference to a termination point. 1193 (This type should not be used for relative references. 1194 In such a case, a relative path should be used instead.)"; 1195 } 1196 uses nw:node-ref; 1197 } 1199 augment "/nw:networks/nw:network" { 1200 description 1201 "Add links to the network data model."; 1202 list link { 1203 key "link-id"; 1204 description 1205 "A network link connects a local (source) node and 1206 a remote (destination) node via a set of 1207 the respective node's termination points. 1208 It is possible to have several links between the same 1209 source and destination nodes. Likewise, a link could 1210 potentially be re-homed between termination points. 1211 Therefore, in order to ensure that we would always know 1212 to distinguish between links, every link is identified by 1213 a dedicated link identifier. Note that a link models a 1214 point-to-point link, not a multipoint link."; 1215 leaf link-id { 1216 type link-id; 1217 description 1218 "The identifier of a link in the topology. 1219 A link is specific to a topology to which it belongs."; 1220 } 1221 container source { 1222 description 1223 "This container holds the logical source of a particular 1224 link."; 1225 leaf source-node { 1226 type leafref { 1227 path "../../../nw:node/nw:node-id"; 1228 require-instance false; 1229 } 1230 description 1231 "Source node identifier, must be in same topology."; 1232 } 1233 leaf source-tp { 1234 type leafref { 1235 path "../../../nw:node[nw:node-id=current()/../"+ 1236 "source-node]/termination-point/tp-id"; 1237 require-instance false; 1238 } 1239 description 1240 "Termination point within source node that terminates 1241 the link."; 1242 } 1243 } 1244 container destination { 1245 description 1246 "This container holds the logical destination of a 1247 particular link."; 1248 leaf dest-node { 1249 type leafref { 1250 path "../../../nw:node/nw:node-id"; 1251 require-instance false; 1252 } 1253 description 1254 "Destination node identifier, must be in the same 1255 network."; 1256 } 1257 leaf dest-tp { 1258 type leafref { 1259 path "../../../nw:node[nw:node-id=current()/../"+ 1260 "dest-node]/termination-point/tp-id"; 1261 require-instance false; 1262 } 1263 description 1264 "Termination point within destination node that 1265 terminates the link."; 1266 } 1267 } 1268 list supporting-link { 1269 key "network-ref link-ref"; 1270 description 1271 "Identifies the link, or links, that this link 1272 is dependent on."; 1273 leaf network-ref { 1274 type leafref { 1275 path "../../../nw:supporting-network/nw:network-ref"; 1276 require-instance false; 1277 } 1278 description 1279 "This leaf identifies in which underlay topology 1280 the supporting link is present."; 1281 } 1282 leaf link-ref { 1283 type leafref { 1284 path "/nw:networks/nw:network[nw:network-id=current()/"+ 1285 "../network-ref]/link/link-id"; 1286 require-instance false; 1287 } 1288 description 1289 "This leaf identifies a link which is a part 1290 of this link's underlay. Reference loops in which 1291 a link identifies itself as its underlay, either 1292 directly or transitively, are not allowed."; 1293 } 1294 } 1295 } 1296 } 1297 augment "/nw:networks/nw:network/nw:node" { 1298 description 1299 "Augment termination points which terminate links. 1300 Termination points can ultimately be mapped to interfaces."; 1301 list termination-point { 1302 key "tp-id"; 1303 description 1304 "A termination point can terminate a link. 1305 Depending on the type of topology, a termination point 1306 could, for example, refer to a port or an interface."; 1307 leaf tp-id { 1308 type tp-id; 1309 description 1310 "Termination point identifier."; 1311 } 1312 list supporting-termination-point { 1313 key "network-ref node-ref tp-ref"; 1314 description 1315 "This list identifies any termination points that 1316 the termination point is dependent on, or maps onto. 1317 Those termination points will themselves be contained 1318 in a supporting node. 1319 This dependency information can be inferred from 1320 the dependencies between links. For this reason, 1321 this item is not separately configurable. Hence no 1322 corresponding constraint needs to be articulated. 1323 The corresponding information is simply provided by the 1324 implementing system."; 1325 leaf network-ref { 1326 type leafref { 1327 path "../../../nw:supporting-node/nw:network-ref"; 1328 require-instance false; 1329 } 1330 description 1331 "This leaf identifies in which topology the 1332 supporting termination point is present."; 1333 } 1334 leaf node-ref { 1335 type leafref { 1336 path "../../../nw:supporting-node/nw:node-ref"; 1337 require-instance false; 1338 } 1339 description 1340 "This leaf identifies in which node the supporting 1341 termination point is present."; 1342 } 1343 leaf tp-ref { 1344 type leafref { 1345 path "/nw:networks/nw:network[nw:network-id=current()/"+ 1346 "../network-ref]/nw:node[nw:node-id=current()/../"+ 1347 "node-ref]/termination-point/tp-id"; 1348 require-instance false; 1349 } 1350 description 1351 "Reference to the underlay node, must be in a 1352 different topology"; 1353 } 1354 } 1355 } 1356 } 1357 } 1359 1361 7. IANA Considerations 1363 This document registers the following namespace URIs in the "IETF XML 1364 Registry" [RFC3688]: 1366 URI: urn:ietf:params:xml:ns:yang:ietf-network 1367 Registrant Contact: The IESG. 1368 XML: N/A; the requested URI is an XML namespace. 1370 URI:urn:ietf:params:xml:ns:yang:ietf-network-topology 1371 Registrant Contact: The IESG. 1372 XML: N/A; the requested URI is an XML namespace. 1374 URI: urn:ietf:params:xml:ns:yang:ietf-network-state 1375 Registrant Contact: The IESG. 1376 XML: N/A; the requested URI is an XML namespace. 1378 URI:urn:ietf:params:xml:ns:yang:ietf-network-topology-state 1379 Registrant Contact: The IESG. 1381 XML: N/A; the requested URI is an XML namespace. 1383 This document registers the following YANG modules in the "YANG 1384 Module Names" registry [RFC6020]: 1386 NOTE TO THE RFC EDITOR: In the list below, please replace references 1387 to "draft-ietf-i2rs-yang-network-topo-17 (RFC form)" with RFC number 1388 when published (i.e. RFC xxxx). 1390 Name: ietf-network 1391 Namespace: urn:ietf:params:xml:ns:yang:ietf-network 1392 Prefix: nw 1393 Reference: draft-ietf-i2rs-yang-network-topo-17.txt (RFC form) 1395 Name: ietf-network-topology 1396 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology 1397 Prefix: nt 1398 Reference: draft-ietf-i2rs-yang-network-topo-17.txt (RFC form) 1400 Name: ietf-network-state 1401 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-state 1402 Prefix: nw-s 1403 Reference: draft-ietf-i2rs-yang-network-topo-17.txt (RFC form) 1405 Name: ietf-network-topology-state 1406 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology-state 1407 Prefix: nt-s 1408 Reference: draft-ietf-i2rs-yang-network-topo-17.txt (RFC form) 1410 8. Security Considerations 1412 The YANG modules defined in this document are designed to be accessed 1413 via network management protocols such as NETCONF [RFC6241] or 1414 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport 1415 layer, and the mandatory-to-implement secure transport is Secure 1416 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the 1417 mandatory-to-implement secure transport is TLS [RFC5246]. 1419 The NETCONF access control model [RFC6536] provides the means to 1420 restrict access for particular NETCONF or RESTCONF users to a 1421 preconfigured subset of all available NETCONF or RESTCONF protocol 1422 operations and content. 1424 The YANG modules define information that can be configurable in 1425 certain instances, for example in the case of overlay topologies that 1426 can be created by client applications. In such cases, a malicious 1427 client could introduce topologies that are undesired. Specifically, 1428 a malicious client could attempt to remove or add a node, a link, a 1429 termination point, by creating or deleting corresponding elements in 1430 the node, link, and termination point lists, respectively. In the 1431 case of a topology that is learned, the server will automatically 1432 prohibit such misconfiguration attempts. In the case of a topology 1433 that is configured, i.e. whose origin is "intended", the undesired 1434 configuration could become effective and be reflected in the 1435 operational datastore, leading to disruption of services provided via 1436 this topology might be disrupted. For example, the topology could be 1437 "cut" or be configured in a suboptimal way, leading to increased 1438 consumption of resources in the underlay network due to resulting 1439 routing and bandwidth utilization inefficiencies. Likewise, it could 1440 lead to degradation of service levels as well as possibly disruption 1441 of service. For those reasons, it is important that the NETCONF 1442 access control model is vigorously applied to prevent topology 1443 misconfiguration by unauthorized clients. 1445 Specifically, there are a number of data nodes defined in these YANG 1446 module that are writable/creatable/deletable (i.e., config true, 1447 which is the default). These data nodes may be considered sensitive 1448 or vulnerable in some network environments. Write operations (e.g., 1449 edit-config) to these data nodes without proper protection can have a 1450 negative effect on network operations. These are the subtrees and 1451 data nodes and their sensitivity/vulnerability in the ietf-network 1452 module: 1454 o network: A malicious client could attempt to remove or add a 1455 network in an attempt to remove an overlay topology, or create an 1456 unauthorized overlay. 1458 o supporting-network: A malicious client could attempt to disrupt 1459 the logical structure of the model, resulting in lack of overall 1460 data integrity and making it more difficult to, for example, 1461 troubleshoot problems rooted in the layering of network 1462 topologies. 1464 o node: A malicious client could attempt to remove or add a node 1465 from network, for example in order to sabotage the topology of a 1466 network overlay. 1468 o supporting-node: A malicious client could attempt to change the 1469 supporting-node in order to sabotage the layering of an overlay. 1471 These are the subtrees and data nodes and their sensitivity/ 1472 vulnerability in the ietf-network-topology module: 1474 o link: A malicious client could attempt to remove a link from a 1475 topology, or add a new link, or manipulate the way the link is 1476 layered over supporting links, or modify the source or destination 1477 of the link. Either way, the structure of the topology would be 1478 sabotaged, which could, for example, result in an overlay topology 1479 that is less than optimal. 1481 o termination-point: A malicious client could attempt to remove 1482 termination points from a node, or add "phantom" termination 1483 points to a node, or change the layering dependencies of 1484 termination points, again in an attempt to sabotage the integrity 1485 of a topology and potentially disrupt orderly operations of an 1486 overlay. 1488 9. Contributors 1490 The data model presented in this paper was contributed to by more 1491 people than can be listed on the author list. Additional 1492 contributors include: 1494 o Vishnu Pavan Beeram, Juniper 1496 o Ken Gray, Cisco 1498 o Tom Nadeau, Brocade 1500 o Tony Tkacik 1502 o Kent Watsen, Juniper 1504 o Aleksandr Zhdankin, Cisco 1506 10. Acknowledgements 1508 We wish to acknowledge the helpful contributions, comments, and 1509 suggestions that were received from Alia Atlas, Andy Bierman, Martin 1510 Bjorklund, Igor Bryskin, Benoit Claise, Susan Hares, Ladislav Lhotka, 1511 Carlos Pignataro, Juergen Schoenwaelder, Robert Wilton, and Xian 1512 Zhang. 1514 11. References 1516 11.1. Normative References 1518 [I-D.draft-ietf-netmod-revised-datastores] 1519 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1520 and R. Wilton, "A Revised Conceptual Model for YANG 1521 Datastores", I-D draft-ietf-netmod-revised-datastores-02, 1522 May 2017. 1524 [RFC2119] Bradner, S., "Key words for use in RFCs to indicate 1525 requirement levels", RFC 2119, March 1997. 1527 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1528 2004. 1530 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1531 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1533 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1534 Network Configuration Protocol (NETCONF)", RFC 6020, 1535 October 2010. 1537 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1538 Bierman, "Network Configuration Protocol (NETCONF)", 1539 RFC 6241, June 2011. 1541 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1542 Shell (SSH)", RFC 6242, June 2011. 1544 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1545 Protocol (NETCONF) Access Control Model", RFC 6536, March 1546 2012. 1548 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1549 July 2013. 1551 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1552 RFC 7950, August 2016. 1554 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1555 Protocol", RFC 8040, January 2017. 1557 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1558 2119 Key Words", RFC 8174, May 2017. 1560 11.2. Informative References 1562 [I-D.draft-ietf-i2rs-ephemeral-state] 1563 Haas, J. and S. Hares, "I2RS Ephemeral State 1564 Requirements", I-D draft-ietf-i2rs-ephemeral-state-23, 1565 November 2016. 1567 [I-D.draft-ietf-i2rs-usecase-reqs-summary] 1568 Hares, S. and M. Chen, "Summary of I2RS Use Case 1569 Requirements", I-D draft-ietf-i2rs-usecase-reqs-summary- 1570 03, November 2016. 1572 [I-D.draft-ietf-i2rs-yang-l3-topology] 1573 Clemm, A., Medved, J., Varga, R., Liu, X., 1574 Ananthakrishnan, H., and N. Bahadur, "A YANG Data Model 1575 for Layer 3 Topologies", I-D draft-ietf-i2rs-yang-l3- 1576 topology-11, September 2017. 1578 [I-D.draft-ietf-netconf-yang-push] 1579 Clemm, A., Voit, E., Gonzalez Prieto, A., Tripathy, A., 1580 Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 1581 "Subscribing to YANG datastore push updates", I-D draft- 1582 ietf-netconf-yang-push-10, October 2017. 1584 [I-D.draft-ietf-netmod-yang-tree-diagrams] 1585 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", I-D 1586 draft-ietf-netmod-yang-tree-diagrams, June 2017. 1588 [RFC1195] Callon, R., "Use of OSI IS-IS for Routing in TCP/IP and 1589 Dual Environments", RFC 1195, December 1990. 1591 [RFC2328] Moy, J., "OSPF Version 2", RFC 2328, April 1998. 1593 [RFC3209] Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V., 1594 and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP 1595 Tunnels", RFC 3209, December 2001. 1597 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1598 Management", RFC 7223, May 2014. 1600 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1601 RFC 7952, August 2016. 1603 [RFC8022] Lhotka, L. and A. Lindem, "A YANG Data Model for Routing 1604 Management", RFC 8022, November 2016. 1606 Appendix A. Appendix: Model Use Cases 1608 A.1. Fetching Topology from a Network Element 1610 In its simplest form, topology is learned by a network element (e.g., 1611 a router) through its participation in peering protocols (IS-IS, BGP, 1612 etc.). This learned topology can then be exported (e.g., to an NMS) 1613 for external utilization. Typically, any network element in a domain 1614 can be queried for its topology and expected to return the same 1615 result. 1617 In a slightly more complex form, the network element may be a 1618 controller, either by nature of it having satellite or subtended 1619 devices hanging off of it, or in the more classical sense, such as 1620 special device designated to orchestrate the activities of a number 1621 of other devices (e.g., an optical controller). In this case, the 1622 controller device is logically a singleton and must be queried 1623 distinctly. 1625 It is worth noting that controllers can be built on top of 1626 controllers to establish a topology incorporating of all the domains 1627 within an entire network. 1629 In all of the cases above, the topology learned by the network 1630 element is considered to be operational state data. That is, the 1631 data is accumulated purely by the network element's interactions with 1632 other systems and is subject to change dynamically without input or 1633 consent. 1635 A.2. Modifying TE Topology Imported from an Optical Controller 1637 Consider a scenario where an Optical Transport Controller presents 1638 its topology in abstract TE Terms to a Client Packet Controller. 1639 This Customized Topology (that gets merged into the Client's native 1640 topology) contains sufficient information for the path computing 1641 client to select paths across the optical domain according to its 1642 policies. If the Client determines (at any given point in time) that 1643 this imported topology does not exactly cater to its requirements, it 1644 may decide to request modifications to the topology. Such 1645 customization requests may include addition or deletion of topoogical 1646 elements or modification of attributes associated with existing 1647 topological elements. From the perspective of the Optical 1648 Controller, these requests translate into configuration changes to 1649 the exported abstract topology. 1651 A.3. Annotating Topology for Local Computation 1653 In certain scenarios, the topology learned by a controller needs to 1654 be augmented with additional attributes before running a computation 1655 algorithm on it. Consider the case where a path-computation 1656 application on the controller needs to take the geographic 1657 coordinates of the nodes into account while computing paths on the 1658 learned topology. If the learned topology does not contain these 1659 coordinates, then these additional attributes must be configured on 1660 the corresponding topological elements. 1662 A.4. SDN Controller-Based Configuration of Overlays on Top of Underlays 1664 In this scenario, an SDN controller (for example, Open Daylight) 1665 maintains a view of the topology of the network that it controls 1666 based on information that it discovers from the network. In 1667 addition, it provides an application in which it configures and 1668 maintains an overlay topology. 1670 The SDN Controller thus maintains two roles: 1672 o It is a client to the network. 1674 o It is a server to its own northbound applications and clients, 1675 e.g. an OSS. 1677 In other words, one system's client (or controller, in this case) may 1678 be another system's server (or "uber-network device"). 1680 In this scenario, the SDN controller maintains a consolidated data 1681 model of multiple layers of topology. This includes the lower layers 1682 of the network topology, built from information that is discovered 1683 from the network. It also includes upper layers of topology overlay, 1684 configurable by the controller's client, i.e. the OSS. To the OSS, 1685 the lower topology layers constitute "read-only" information. The 1686 upper topology layers need to be read-writable. 1688 Appendix B. Appendix: Companion YANG models for non-NMDA compliant 1689 implementations 1691 The YANG modules defined in this document are designed to be used in 1692 conjunction with implementations that support the Network Management 1693 Datastore Architecture (NMDA) defined in 1694 [I-D.draft-ietf-netmod-revised-datastores]. In order to allow 1695 implementations to use the data model even in cases when NMDA is not 1696 supported, in the following two companion modules are defined that 1697 represent the operational state of networks and network topologies. 1698 The modules, ietf-network-state and ietf-network-topology-state, 1699 mirror modules ietf-network and ietf-network-topology defined earlier 1700 in this document. However, all data nodes are non-configurable. 1701 They represent state that comes into being by either learning 1702 topology information from the network, or by applying configuration 1703 from the mirrored modules. 1705 The companion modules, ietf-network-state and ietf-network-topology- 1706 state, are redundant and SHOULD NOT be supported by implementations 1707 that support NMDA. It is for this reason that the definitions are 1708 defined in an appendix. 1710 As the structure of both modules mirrors that of their underlying 1711 modules, the YANG tree is not depicted separately. 1713 B.1. YANG Model for Network State 1715 NOTE TO RFC EDITOR: Please change the date in the file name after the 1716 CODE BEGINS statement to the date of the publication when published. 1718 file "ietf-network-state@2017-10-22.yang" 1719 module ietf-network-state { 1720 yang-version 1.1; 1721 namespace "urn:ietf:params:xml:ns:yang:ietf-network-state"; 1722 prefix nw-s; 1724 import ietf-network { 1725 prefix nw; 1726 reference 1727 "draft-ietf-i2rs-yang-network-topo-17 1728 NOTE TO RFC EDITOR: Please replace above reference to 1729 draft-ietf-i2rs-yang-network-topo-17 with RFC 1730 number when published (i.e. RFC xxxx)."; 1731 } 1733 organization 1734 "IETF I2RS (Interface to the Routing System) Working Group"; 1736 contact 1737 "WG Web: 1738 WG List: 1740 Editor: Alexander Clemm 1741 1743 Editor: Jan Medved 1744 1746 Editor: Robert Varga 1747 1749 Editor: Nitin Bahadur 1750 1752 Editor: Hariharan Ananthakrishnan 1753 1755 Editor: Xufeng Liu 1756 "; 1758 description 1759 "This module defines a common base data model for a collection 1760 of nodes in a network. Node definitions are further used 1761 in network topologies and inventories. It represents 1762 information that is either learned and automatically populated, 1763 or information that results from applying configured netwok 1764 information configured per the ietf-network data model, 1765 mirroring the corresponding data nodes in this data model. 1767 The data model mirrors ietf-network, but contains only 1768 read-only state data. The data model is not needed when the 1769 underlying implementation infrastructure supports the Network 1770 Management Datastore Architecture (NMDA). 1772 Copyright (c) 2017 IETF Trust and the persons identified as 1773 authors of the code. All rights reserved. 1775 Redistribution and use in source and binary forms, with or 1776 without modification, is permitted pursuant to, and subject 1777 to the license terms contained in, the Simplified BSD License 1778 set forth in Section 4.c of the IETF Trust's Legal Provisions 1779 Relating to IETF Documents 1780 (http://trustee.ietf.org/license-info). 1782 This version of this YANG module is part of 1783 draft-ietf-i2rs-yang-network-topo-17; 1784 see the RFC itself for full legal notices. 1786 NOTE TO RFC EDITOR: Please replace above reference to 1787 draft-ietf-i2rs-yang-network-topo-17 with RFC 1788 number when published (i.e. RFC xxxx)."; 1790 revision 2017-10-22 { 1791 description 1792 "Initial revision. 1793 NOTE TO RFC EDITOR: 1794 (1) Please replace the following reference 1795 to draft-ietf-i2rs-yang-network-topo-17 with 1796 RFC number when published (i.e. RFC xxxx). 1797 (2) Please replace the date in the revision statement with the 1798 date of the publication when published."; 1799 reference 1800 "draft-ietf-i2rs-yang-network-topo-17"; 1801 } 1803 grouping network-ref { 1804 description 1805 "Contains the information necessary to reference a network, 1806 for example an underlay network."; 1807 leaf network-ref { 1808 type leafref { 1809 path "/nw-s:networks/nw-s:network/nw-s:network-id"; 1810 require-instance false; 1811 } 1812 description 1813 "Used to reference a network, for example an underlay 1814 network."; 1815 } 1816 } 1818 grouping node-ref { 1819 description 1820 "Contains the information necessary to reference a node."; 1821 leaf node-ref { 1822 type leafref { 1823 path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+ 1824 "/../network-ref]/nw-s:node/nw-s:node-id"; 1825 require-instance false; 1826 } 1827 description 1828 "Used to reference a node. 1829 Nodes are identified relative to the network they are 1830 contained in."; 1831 } 1832 uses network-ref; 1833 } 1835 container networks { 1836 config false; 1837 description 1838 "Serves as top-level container for a list of networks."; 1839 list network { 1840 key "network-id"; 1841 description 1842 "Describes a network. 1844 A network typically contains an inventory of nodes, 1845 topological information (augmented through 1846 network-topology data model), as well as layering 1847 information."; 1848 container network-types { 1849 description 1850 "Serves as an augmentation target. 1851 The network type is indicated through corresponding 1852 presence containers augmented into this container."; 1853 } 1854 leaf network-id { 1855 type nw:network-id; 1856 description 1857 "Identifies a network."; 1858 } 1859 list supporting-network { 1860 key "network-ref"; 1861 description 1862 "An underlay network, used to represent layered network 1863 topologies."; 1864 leaf network-ref { 1865 type leafref { 1866 path "/nw-s:networks/nw-s:network/nw-s:network-id"; 1867 require-instance false; 1868 } 1869 description 1870 "References the underlay network."; 1871 } 1872 } 1873 list node { 1874 key "node-id"; 1875 description 1876 "The inventory of nodes of this network."; 1877 leaf node-id { 1878 type nw:node-id; 1879 description 1880 "Identifies a node uniquely within the containing 1881 network."; 1882 } 1883 list supporting-node { 1884 key "network-ref node-ref"; 1885 description 1886 "Represents another node, in an underlay network, that 1887 this node is supported by. Used to represent layering 1888 structure."; 1889 leaf network-ref { 1890 type leafref { 1891 path "../../../nw-s:supporting-network/nw-s:network-ref"; 1893 require-instance false; 1894 } 1895 description 1896 "References the underlay network that the 1897 underlay node is part of."; 1898 } 1899 leaf node-ref { 1900 type leafref { 1901 path "/nw-s:networks/nw-s:network/nw-s:node/nw-s:node-id"; 1902 require-instance false; 1903 } 1904 description 1905 "References the underlay node itself."; 1906 } 1907 } 1908 } 1909 } 1910 } 1911 } 1912 1914 B.2. YANG Data Model for Network Topology State 1916 NOTE TO RFC EDITOR: Please change the date in the file name after the 1917 CODE BEGINS statement to the date of the publication when published. 1919 file "ietf-network-topology-state@2017-10-22.yang" 1920 module ietf-network-topology-state { 1921 yang-version 1.1; 1922 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology-state"; 1923 prefix nt-s; 1925 import ietf-network-state { 1926 prefix nw-s; 1927 reference 1928 "draft-ietf-i2rs-yang-network-topo-17 1929 NOTE TO RFC EDITOR: Please replace above reference to 1930 draft-ietf-i2rs-yang-network-topo-17 with RFC 1931 number when published (i.e. RFC xxxx)."; 1932 } 1933 import ietf-network-topology { 1934 prefix nt; 1935 reference 1936 "draft-ietf-i2rs-yang-network-topo-17 1937 NOTE TO RFC EDITOR: Please replace above reference to 1938 draft-ietf-i2rs-yang-network-topo-17 with RFC 1939 number when published (i.e. RFC xxxx)."; 1940 } 1941 organization 1942 "IETF I2RS (Interface to the Routing System) Working Group"; 1944 contact 1945 "WG Web: 1946 WG List: 1948 Editor: Alexander Clemm 1949 1951 Editor: Jan Medved 1952 1954 Editor: Robert Varga 1955 1957 Editor: Nitin Bahadur 1958 1960 Editor: Hariharan Ananthakrishnan 1961 1963 Editor: Xufeng Liu 1964 "; 1966 description 1967 "This module defines a common base data model for network 1968 topology state, representing topology that is either learned, 1969 or topology that results from applying topology that has been 1970 configured per the ietf-network-topology data model, mirroring 1971 the corresponding data nodes in this data model. It augments 1972 the base network state data model with links to connect nodes, 1973 as well as termination points to terminate links on nodes. 1975 The data model mirrors ietf-network-topology, but contains only 1976 read-only state data. The data model is not needed when the 1977 underlying implementation infrastructure supports the Network 1978 Management Datastore Architecture (NMDA). 1980 Copyright (c) 2017 IETF Trust and the persons identified as 1981 authors of the code. All rights reserved. 1983 Redistribution and use in source and binary forms, with or 1984 without modification, is permitted pursuant to, and subject 1985 to the license terms contained in, the Simplified BSD License 1986 set forth in Section 4.c of the IETF Trust's Legal Provisions 1987 Relating to IETF Documents 1988 (http://trustee.ietf.org/license-info). 1989 This version of this YANG module is part of 1990 draft-ietf-i2rs-yang-network-topo-17; 1991 see the RFC itself for full legal notices. 1993 NOTE TO RFC EDITOR: Please replace above reference to 1994 draft-ietf-i2rs-yang-network-topo-17 with RFC 1995 number when published (i.e. RFC xxxx)."; 1997 revision 2017-10-22 { 1998 description 1999 "Initial revision. 2000 NOTE TO RFC EDITOR: 2001 (1) Please replace the following reference 2002 to draft-ietf-i2rs-yang-network-topo-17 with 2003 RFC number when published (i.e. RFC xxxx). 2004 (2) Please replace the date in the revision statement with the 2005 date of publication when published."; 2006 reference 2007 "draft-ietf-i2rs-yang-network-topo-17"; 2008 } 2010 grouping link-ref { 2011 description 2012 "References a link in a specific network. While this grouping 2013 is not used in this module, it is defined here for the 2014 convenience of augmenting modules."; 2015 leaf link-ref { 2016 type leafref { 2017 path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+ 2018 "/../network-ref]/nt-s:link/nt-s:link-id"; 2019 require-instance false; 2020 } 2021 description 2022 "A type for an absolute reference a link instance. 2023 (This type should not be used for relative references. 2024 In such a case, a relative path should be used instead.)"; 2025 } 2026 uses nw-s:network-ref; 2027 } 2029 grouping tp-ref { 2030 description 2031 "References a termination point in a specific node. While 2032 this grouping is not used in this module, it is defined here 2033 for the convenience of augmenting modules."; 2034 leaf tp-ref { 2035 type leafref { 2036 path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+ 2037 "/../network-ref]/nw-s:node[nw-s:node-id=current()/../"+ 2038 "node-ref]/nt-s:termination-point/nt-s:tp-id"; 2039 require-instance false; 2040 } 2041 description 2042 "A type for an absolute reference to a termination point. 2043 (This type should not be used for relative references. 2044 In such a case, a relative path should be used instead.)"; 2045 } 2046 uses nw-s:node-ref; 2047 } 2049 augment "/nw-s:networks/nw-s:network" { 2050 description 2051 "Add links to the network data model."; 2052 list link { 2053 key "link-id"; 2054 description 2055 "A network link connects a local (source) node and 2056 a remote (destination) node via a set of 2057 the respective node's termination points. 2058 It is possible to have several links between the same 2059 source and destination nodes. Likewise, a link could 2060 potentially be re-homed between termination points. 2061 Therefore, in order to ensure that we would always know 2062 to distinguish between links, every link is identified by 2063 a dedicated link identifier. Note that a link models a 2064 point-to-point link, not a multipoint link."; 2065 container source { 2066 description 2067 "This container holds the logical source of a particular 2068 link."; 2069 leaf source-node { 2070 type leafref { 2071 path "../../../nw-s:node/nw-s:node-id"; 2072 require-instance false; 2073 } 2074 description 2075 "Source node identifier, must be in same topology."; 2076 } 2077 leaf source-tp { 2078 type leafref { 2079 path "../../../nw-s:node[nw-s:node-id=current()/../"+ 2080 "source-node]/termination-point/tp-id"; 2081 require-instance false; 2082 } 2083 description 2084 "Termination point within source node that terminates 2085 the link."; 2086 } 2087 } 2088 container destination { 2089 description 2090 "This container holds the logical destination of a 2091 particular link."; 2092 leaf dest-node { 2093 type leafref { 2094 path "../../../nw-s:node/nw-s:node-id"; 2095 require-instance false; 2096 } 2097 description 2098 "Destination node identifier, must be in the same 2099 network."; 2100 } 2101 leaf dest-tp { 2102 type leafref { 2103 path "../../../nw-s:node[nw-s:node-id=current()/../"+ 2104 "dest-node]/termination-point/tp-id"; 2105 require-instance false; 2106 } 2107 description 2108 "Termination point within destination node that 2109 terminates the link."; 2110 } 2111 } 2112 leaf link-id { 2113 type nt:link-id; 2114 description 2115 "The identifier of a link in the topology. 2116 A link is specific to a topology to which it belongs."; 2117 } 2118 list supporting-link { 2119 key "network-ref link-ref"; 2120 description 2121 "Identifies the link, or links, that this link 2122 is dependent on."; 2123 leaf network-ref { 2124 type leafref { 2125 path "../../../nw-s:supporting-network/nw-s:network-ref"; 2126 require-instance false; 2127 } 2128 description 2129 "This leaf identifies in which underlay topology 2130 the supporting link is present."; 2131 } 2132 leaf link-ref { 2133 type leafref { 2134 path "/nw-s:networks/nw-s:network[nw-s:network-id="+ 2135 "current()/../network-ref]/link/link-id"; 2136 require-instance false; 2137 } 2138 description 2139 "This leaf identifies a link which is a part 2140 of this link's underlay. Reference loops in which 2141 a link identifies itself as its underlay, either 2142 directly or transitively, are not allowed."; 2143 } 2144 } 2145 } 2146 } 2147 augment "/nw-s:networks/nw-s:network/nw-s:node" { 2148 description 2149 "Augment termination points which terminate links. 2150 Termination points can ultimately be mapped to interfaces."; 2151 list termination-point { 2152 key "tp-id"; 2153 description 2154 "A termination point can terminate a link. 2155 Depending on the type of topology, a termination point 2156 could, for example, refer to a port or an interface."; 2157 leaf tp-id { 2158 type nt:tp-id; 2159 description 2160 "Termination point identifier."; 2161 } 2162 list supporting-termination-point { 2163 key "network-ref node-ref tp-ref"; 2164 description 2165 "This list identifies any termination points that 2166 the termination point is dependent on, or maps onto. 2167 Those termination points will themselves be contained 2168 in a supporting node. 2169 This dependency information can be inferred from 2170 the dependencies between links. For this reason, 2171 this item is not separately configurable. Hence no 2172 corresponding constraint needs to be articulated. 2173 The corresponding information is simply provided by the 2174 implementing system."; 2175 leaf network-ref { 2176 type leafref { 2177 path "../../../nw-s:supporting-node/nw-s:network-ref"; 2178 require-instance false; 2179 } 2180 description 2181 "This leaf identifies in which topology the 2182 supporting termination point is present."; 2183 } 2184 leaf node-ref { 2185 type leafref { 2186 path "../../../nw-s:supporting-node/nw-s:node-ref"; 2187 require-instance false; 2188 } 2189 description 2190 "This leaf identifies in which node the supporting 2191 termination point is present."; 2192 } 2193 leaf tp-ref { 2194 type leafref { 2195 path "/nw-s:networks/nw-s:network[nw-s:network-id="+ 2196 "current()/../network-ref]/nw-s:node[nw-s:node-id="+ 2197 "current()/../node-ref]/termination-point/tp-id"; 2198 require-instance false; 2199 } 2200 description 2201 "Reference to the underlay node, must be in a 2202 different topology"; 2203 } 2204 } 2205 } 2206 } 2207 } 2209 2211 Authors' Addresses 2213 Alexander Clemm 2214 Huawei 2216 EMail: ludwig@clemm.org 2218 Jan Medved 2219 Cisco 2221 EMail: jmedved@cisco.com 2223 Robert Varga 2224 Pantheon Technologies SRO 2226 EMail: robert.varga@pantheon.tech 2227 Nitin Bahadur 2228 Bracket Computing 2230 EMail: nitin_bahadur@yahoo.com 2232 Hariharan Ananthakrishnan 2233 Packet Design 2235 EMail: hari@packetdesign.com 2237 Xufeng Liu 2238 Jabil 2240 EMail: Xufeng_Liu@jabil.com