idnits 2.17.1 draft-ietf-i2rs-yang-network-topo-15.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 (September 5, 2017) is 2423 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 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-10 == Outdated reference: A later version (-25) exists of draft-ietf-netconf-yang-push-08 -- 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: March 9, 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 September 5, 2017 16 A Data Model for Network Topologies 17 draft-ietf-i2rs-yang-network-topo-15.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 March 9, 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 . . . . . . . . . . . . . . . . . . . . . . . . 31 88 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 89 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 90 11.1. Normative References . . . . . . . . . . . . . . . . . . 32 91 11.2. Informative References . . . . . . . . . . . . . . . . . 33 92 Appendix A. Appendix: Model Use Cases . . . . . . . . . . . . . 34 93 A.1. Fetching Topology from a Network Element . . . . . . . . 34 94 A.2. Modifying TE Topology Imported from an Optical Controller 34 95 A.3. Annotating Topology for Local Computation . . . . . . . . 35 96 A.4. SDN Controller-Based Configuration of Overlays on Top of 97 Underlays . . . . . . . . . . . . . . . . . . . . . . . . 35 98 Appendix B. Appendix: Companion YANG models for non-NMDA 99 compliant implementations . . . . . . . . . . . . . 35 100 B.1. YANG Model for Network State . . . . . . . . . . . . . . 36 101 B.2. YANG Data Model for Network Topology State . . . . . . . 40 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 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 store of instantiated management information, 329 with individual data items represented by data nodes which are 330 arranged in hierarchical manner. 332 Data subtree: An instantiated data node and the data nodes that are 333 hierarchically contained within it. 335 HTTP: Hyper-Text Transfer Protocol 336 IGP: Interior Gateway Protocol 338 IS-IS: Intermediate System to Intermediate System protocol 340 OSPF: Open Shortest Path First, a link state routing protocol 342 URI: Uniform Resource Identifier 344 ReST: Representational State Transfer, a style of stateless interface 345 and protocol that is generally carried over HTTP 347 4. Model Structure Details 349 4.1. Base Network Model 351 The abstract (base) network data model is defined in the ietf- 352 network.yang module. Its structure is shown in the following figure. 353 The notation syntax follows 354 [I-D.draft-ietf-netmod-yang-tree-diagrams]. 356 module: ietf-network 357 +--rw networks 358 +--rw network* [network-id] 359 +--rw network-types 360 +--rw network-id network-id 361 +--rw supporting-network* [network-ref] 362 | +--rw network-ref -> /networks/network/network-id 363 +--rw node* [node-id] 364 +--rw node-id node-id 365 +--rw supporting-node* [network-ref node-ref] 366 +--rw network-ref -> ../../../supporting-network/ + 367 | network-ref 368 +--rw node-ref -> /networks/network/node/node-id 370 Figure 4: The structure of the abstract (base) network data model 372 The data model contains a container with a list of networks. Each 373 network is captured in its own list entry, distinguished via a 374 network-id. 376 A network has a certain type, such as L2, L3, OSPF or IS-IS. A 377 network can even have multiple types simultaneously. The type, or 378 types, are captured underneath the container "network-types". In 379 this module it serves merely as an augmentation target; network- 380 specific modules will later introduce new data nodes to represent new 381 network types below this target, i.e. insert them below "network- 382 types" by ways of YANG augmentation. 384 When a network is of a certain type, it will contain a corresponding 385 data node. Network types SHOULD always be represented using presence 386 containers, not leafs of empty type. This allows representation of 387 hierarchies of network subtypes within the instance information. For 388 example, an instance of an OSPF network (which, at the same time, is 389 a layer 3 unicast IGP network) would contain underneath "network- 390 types" another presence container "l3-unicast-igp-network", which in 391 turn would contain a presence container "ospf-network". Actual 392 examples of this pattern can be found in 393 [I-D.draft-ietf-i2rs-yang-l3-topology]. 395 A network can in turn be part of a hierarchy of networks, building on 396 top of other networks. Any such networks are captured in the list 397 "supporting-network". A supporting network is in effect an underlay 398 network. 400 Furthermore, a network contains an inventory of nodes that are part 401 of the network. The nodes of a network are captured in their own 402 list. Each node is identified relative to its containing network by 403 a node-id. 405 It should be noted that a node does not exist independently of a 406 network; instead it is a part of the network that it is contained in. 407 In cases where the same entity takes part in multiple networks, or at 408 multiple layers of a networking stack, the same entity will be 409 represented by multiple nodes, one for each network. In other words, 410 the node represents an abstraction of the device for the particular 411 network that it a is part of. To represent that the same entity or 412 same device is part of multiple topologies or networks, it is 413 possible to create one "physical" network with a list of nodes for 414 each of the devices or entities. This (physical) network, 415 respectively the (entities) nodes in that network, can then be 416 referred to as underlay network and nodes from the other (logical) 417 networks and nodes, respectively. Note that the data model allows 418 definition of more than one underlay network (and node), allowing for 419 simultaneous representation of layered network- and service 420 topologies and physical instantiation. 422 Similar to a network, a node can be supported by other nodes, and map 423 onto one or more other nodes in an underlay network. This is 424 captured in the list "supporting-node". The resulting hierarchy of 425 nodes allows also representation of device stacks, where a node at 426 one level is supported by a set of nodes at an underlying level. For 427 example, a "router" node might be supported by a node representing a 428 route processor and separate nodes for various line cards and service 429 modules, a virtual router might be supported or hosted on a physical 430 device represented by a separate node, and so 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 populated by the server, 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 /nd:networks/nd:network: 471 +--rw link* [link-id] 472 +--rw source 473 | +--rw source-node? -> ../../../nd:node/node-id 474 | +--rw source-tp? -> ../../../nd:node[nd:node-id=current()/+ 475 | ../source-node]/termination-point/tp-id 476 +--rw destination 477 | +--rw dest-node? -> ../../../nd:node/node-id 478 | +--rw dest-tp? -> ../../../nd:node[nd:node-id=current()/+ 479 | ../dest-node]/termination-point/tp-id 480 +--rw link-id link-id 481 +--rw supporting-link* [network-ref link-ref] 482 +--rw network-ref -> ../../../nd:supporting-network/+ 483 | network-ref 484 +--rw link-ref -> /nd:networks/network+ 485 [nd:network-id=current()/../network-ref]/+ 486 link/link-id 487 augment /nd:networks/nd:network/nd: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 -> ../../../nd:supporting-node/network-ref 492 +--rw node-ref -> ../../../nd:supporting-node/node-ref 493 +--rw tp-ref -> /nd:networks/network[nd:network-id=+ 494 current()/../network-ref]/node+ 495 [nd: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 allows to more easily 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 conceivable to augment the data model for a physical network- 741 type, defining augmentations that have nodes reference system 742 information and termination points reference physical interfaces, in 743 order to 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 string. 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 (a string is a string is a string), 802 they also muddle things. What typically happens is that strings have 803 some structure which is magically assigned and the knowledge of this 804 structure has to be communicated to each system working with the 805 data. A URI makes the structure explicit and also attaches 806 additional semantics: the URI, unlike a free-form string, can be fed 807 into a URI resolver, which can point to additional resources 808 associated with the URI. This property is important when the 809 topology data is integrated into a larger, more 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-09-05.yang" 836 module ietf-network { 837 yang-version 1.1; 838 namespace "urn:ietf:params:xml:ns:yang:ietf-network"; 839 prefix nd; 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-15; 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-15 with RFC 892 number when published (i.e. RFC xxxx)."; 894 revision 2017-09-05 { 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-15 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-15"; 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 "/nd:networks/nd:network/nd: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 "/nd:networks/nd:network[nd:network-id=current()/../"+ 953 "network-ref]/nd:node/nd: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 container network-types { 976 description 977 "Serves as an augmentation target. 978 The network type is indicated through corresponding 979 presence containers augmented into this container."; 980 } 981 leaf network-id { 982 type network-id; 983 description 984 "Identifies a network."; 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 "/nd:networks/nd:network/nd: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 "../../../nd:supporting-network/nd: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 "/nd:networks/nd:network/nd:node/nd: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-09-05.yang" 1047 module ietf-network-topology { 1048 yang-version 1.1; 1049 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology"; 1050 prefix lnk; 1052 import ietf-inet-types { 1053 prefix inet; 1054 reference 1055 "RFC 6991"; 1056 } 1057 import ietf-network { 1058 prefix nd; 1059 reference 1060 "draft-ietf-i2rs-yang-network-topo-15 1061 NOTE TO RFC EDITOR: 1062 (1) Please replace above reference to 1063 draft-ietf-i2rs-yang-network-topo-15 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-15; 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-15 with RFC 1115 number when published (i.e. RFC xxxx)."; 1117 revision 2017-09-05 { 1118 description 1119 "Initial revision. 1120 NOTE TO RFC EDITOR: Please replace the following reference 1121 to draft-ietf-i2rs-yang-network-topo-15 with 1122 RFC number when published (i.e. RFC xxxx)."; 1123 reference 1124 "draft-ietf-i2rs-yang-network-topo-15"; 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 "References a link in a specific network."; 1161 leaf link-ref { 1162 type leafref { 1163 path "/nd:networks/nd:network[nd:network-id=current()/../"+ 1164 "network-ref]/lnk:link/lnk:link-id"; 1165 require-instance false; 1166 } 1167 description 1168 "A type for an absolute reference a link instance. 1169 (This type should not be used for relative references. 1170 In such a case, a relative path should be used instead.)"; 1171 } 1172 uses nd:network-ref; 1173 } 1175 grouping tp-ref { 1176 description 1177 "References a termination point in a specific node."; 1178 leaf tp-ref { 1179 type leafref { 1180 path "/nd:networks/nd:network[nd:network-id=current()/../"+ 1181 "network-ref]/nd:node[nd:node-id=current()/../"+ 1182 "node-ref]/lnk:termination-point/lnk:tp-id"; 1183 require-instance false; 1184 } 1185 description 1186 "A type for an absolute reference to a termination point. 1187 (This type should not be used for relative references. 1188 In such a case, a relative path should be used instead.)"; 1189 } 1190 uses nd:node-ref; 1191 } 1193 augment "/nd:networks/nd:network" { 1194 description 1195 "Add links to the network data model."; 1196 list link { 1197 key "link-id"; 1198 description 1199 "A network link connects a local (source) node and 1200 a remote (destination) node via a set of 1201 the respective node's termination points. 1202 It is possible to have several links between the same 1203 source and destination nodes. Likewise, a link could 1204 potentially be re-homed between termination points. 1205 Therefore, in order to ensure that we would always know 1206 to distinguish between links, every link is identified by 1207 a dedicated link identifier. Note that a link models a 1208 point-to-point link, not a multipoint link."; 1209 container source { 1210 description 1211 "This container holds the logical source of a particular 1212 link."; 1213 leaf source-node { 1214 type leafref { 1215 path "../../../nd:node/nd:node-id"; 1216 require-instance false; 1217 } 1218 description 1219 "Source node identifier, must be in same topology."; 1220 } 1221 leaf source-tp { 1222 type leafref { 1223 path "../../../nd:node[nd:node-id=current()/../"+ 1224 "source-node]/termination-point/tp-id"; 1225 require-instance false; 1226 } 1227 description 1228 "Termination point within source node that terminates 1229 the link."; 1230 } 1231 } 1232 container destination { 1233 description 1234 "This container holds the logical destination of a 1235 particular link."; 1236 leaf dest-node { 1237 type leafref { 1238 path "../../../nd:node/nd:node-id"; 1239 require-instance false; 1240 } 1241 description 1242 "Destination node identifier, must be in the same 1243 network."; 1244 } 1245 leaf dest-tp { 1246 type leafref { 1247 path "../../../nd:node[nd:node-id=current()/../"+ 1248 "dest-node]/termination-point/tp-id"; 1249 require-instance false; 1250 } 1251 description 1252 "Termination point within destination node that 1253 terminates the link."; 1254 } 1255 } 1256 leaf link-id { 1257 type link-id; 1258 description 1259 "The identifier of a link in the topology. 1260 A link is specific to a topology to which it belongs."; 1261 } 1262 list supporting-link { 1263 key "network-ref link-ref"; 1264 description 1265 "Identifies the link, or links, that this link 1266 is dependent on."; 1267 leaf network-ref { 1268 type leafref { 1269 path "../../../nd:supporting-network/nd:network-ref"; 1270 require-instance false; 1271 } 1272 description 1273 "This leaf identifies in which underlay topology 1274 the supporting link is present."; 1275 } 1276 leaf link-ref { 1277 type leafref { 1278 path "/nd:networks/nd:network[nd:network-id=current()/"+ 1279 "../network-ref]/link/link-id"; 1280 require-instance false; 1281 } 1282 description 1283 "This leaf identifies a link which is a part 1284 of this link's underlay. Reference loops in which 1285 a link identifies itself as its underlay, either 1286 directly or transitively, are not allowed."; 1287 } 1288 } 1289 } 1290 } 1291 augment "/nd:networks/nd:network/nd:node" { 1292 description 1293 "Augment termination points which terminate links. 1294 Termination points can ultimately be mapped to interfaces."; 1295 list termination-point { 1296 key "tp-id"; 1297 description 1298 "A termination point can terminate a link. 1299 Depending on the type of topology, a termination point 1300 could, for example, refer to a port or an interface."; 1301 leaf tp-id { 1302 type tp-id; 1303 description 1304 "Termination point identifier."; 1305 } 1306 list supporting-termination-point { 1307 key "network-ref node-ref tp-ref"; 1308 description 1309 "This list identifies any termination points that 1310 the termination point is dependent on, or maps onto. 1311 Those termination points will themselves be contained 1312 in a supporting node. 1313 This dependency information can be inferred from 1314 the dependencies between links. For this reason, 1315 this item is not separately configurable. Hence no 1316 corresponding constraint needs to be articulated. 1317 The corresponding information is simply provided by the 1318 implementing system."; 1319 leaf network-ref { 1320 type leafref { 1321 path "../../../nd:supporting-node/nd:network-ref"; 1322 require-instance false; 1323 } 1324 description 1325 "This leaf identifies in which topology the 1326 supporting termination point is present."; 1327 } 1328 leaf node-ref { 1329 type leafref { 1330 path "../../../nd:supporting-node/nd:node-ref"; 1331 require-instance false; 1332 } 1333 description 1334 "This leaf identifies in which node the supporting 1335 termination point is present."; 1336 } 1337 leaf tp-ref { 1338 type leafref { 1339 path "/nd:networks/nd:network[nd:network-id=current()/"+ 1340 "../network-ref]/nd:node[nd:node-id=current()/../"+ 1341 "node-ref]/termination-point/tp-id"; 1342 require-instance false; 1343 } 1344 description 1345 "Reference to the underlay node, must be in a 1346 different topology"; 1347 } 1348 } 1349 } 1350 } 1351 } 1353 1355 7. IANA Considerations 1357 This document registers the following namespace URIs in the "IETF XML 1358 Registry" [RFC3688]: 1360 URI: urn:ietf:params:xml:ns:yang:ietf-network 1361 Registrant Contact: The IESG. 1362 XML: N/A; the requested URI is an XML namespace. 1364 URI:urn:ietf:params:xml:ns:yang:ietf-network-topology 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-state 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-topology-state 1373 Registrant Contact: The IESG. 1374 XML: N/A; the requested URI is an XML namespace. 1376 This document registers the following YANG modules in the "YANG 1377 Module Names" registry [RFC6020]: 1379 NOTE TO THE RFC EDITOR: In the list below, please replace references 1380 to "draft-ietf-i2rs-yang-network-topo-15 (RFC form)" with RFC number 1381 when published (i.e. RFC xxxx). 1383 Name: ietf-network 1384 Namespace: urn:ietf:params:xml:ns:yang:ietf-network 1385 Prefix: nd 1386 Reference: draft-ietf-i2rs-yang-network-topo-15.txt (RFC form) 1388 Name: ietf-network-topology 1389 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology 1390 Prefix: lnk 1391 Reference: draft-ietf-i2rs-yang-network-topo-15.txt (RFC form) 1393 Name: ietf-network-state 1394 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-state 1395 Prefix: nd-s 1396 Reference: draft-ietf-i2rs-yang-network-topo-15.txt (RFC form) 1398 Name: ietf-network-topology-state 1399 Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology-state 1400 Prefix: lnk-s 1401 Reference: draft-ietf-i2rs-yang-network-topo-15.txt (RFC form) 1403 8. Security Considerations 1405 The YANG module defined in this document is designed to be accessed 1406 via network management protocols such as NETCONF [RFC6241] or 1407 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport 1408 layer, and the mandatory-to-implement secure transport is Secure 1409 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the 1410 mandatory-to-implement secure transport is TLS [RFC5246]. 1412 The NETCONF access control model [RFC6536] provides the means to 1413 restrict access for particular NETCONF or RESTCONF users to a 1414 preconfigured subset of all available NETCONF or RESTCONF protocol 1415 operations and content. 1417 Rules expressed in NACM can be applied analogously also to other 1418 protocols that attempt access to YANG-defined data. In fact, it 1419 needs to be applied in the same way and should, like YANG, thus be 1420 considered independent of any particular protocol that is used to 1421 access YANG-defined data. Otherwise, access control rules defined by 1422 NACM could be very easily circumvented simply by using another access 1423 mechanism which does not enforce NACM. The alternative of mandating 1424 the introduction of mechanisms parallel to NACM that specify the same 1425 access control rules for other transports is clearly undesirable, as 1426 this would not only inhibit ease-of-use of systems that implement 1427 multiple protocols to access YANG data, but also open the specter of 1428 security holes due to inconsistencies in articulation and enforcement 1429 of rules across mechanisms that are essentially redundant. 1431 The YANG module defines information that can be configurable in 1432 certain instances, for example in the case of overlay topologies that 1433 can be created by client applications. In such cases, a malicious 1434 client could introduce topologies that are undesired. Specifically, 1435 a malicious client could attempt to remove or add a node, a link, a 1436 termination point, by creating or deleting corresponding elements in 1437 the node, link, and termination point lists, respectively. In the 1438 case of a topology that is learned, the server will automatically 1439 prohibit such misconfiguration attempts. In the case of a topology 1440 that is configured, i.e. whose origin is "intended", the undesired 1441 configuration could become effective and be reflected in the 1442 operational datastore, leading to disruption of services provided via 1443 this topology might be disrupted. For example, the topology could be 1444 "cut" or be configured in a suboptimal way, leading to increased 1445 consumption of resources in the underlay network due to resulting 1446 routing and bandwidth utilization inefficiencies. Likewise, it could 1447 lead to degradation of service levels as well as possibly disruption 1448 of service. For those reasons, it is important that the NETCONF 1449 access control model is vigorously applied to prevent topology 1450 misconfiguration by unauthorized clients. 1452 9. Contributors 1454 The data model presented in this paper was contributed to by more 1455 people than can be listed on the author list. Additional 1456 contributors include: 1458 o Vishnu Pavan Beeram, Juniper 1460 o Ken Gray, Cisco 1462 o Tom Nadeau, Brocade 1464 o Tony Tkacik 1466 o Kent Watsen, Juniper 1468 o Aleksandr Zhdankin, Cisco 1470 10. Acknowledgements 1472 We wish to acknowledge the helpful contributions, comments, and 1473 suggestions that were received from Alia Atlas, Andy Bierman, Martin 1474 Bjorklund, Igor Bryskin, Benoit Claise, Susan Hares, Ladislav Lhotka, 1475 Carlos Pignataro, Juergen Schoenwaelder, Robert Wilton, and Xian 1476 Zhang. 1478 11. References 1480 11.1. Normative References 1482 [I-D.draft-ietf-netmod-revised-datastores] 1483 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1484 and R. Wilton, "A Revised Conceptual Model for YANG 1485 Datastores", I-D draft-ietf-netmod-revised-datastores-02, 1486 May 2017. 1488 [RFC2119] Bradner, S., "Key words for use in RFCs to indicate 1489 requirement levels", RFC 2119, March 1997. 1491 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1492 2004. 1494 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1495 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1497 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1498 Network Configuration Protocol (NETCONF)", RFC 6020, 1499 October 2010. 1501 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1502 Bierman, "Network Configuration Protocol (NETCONF)", 1503 RFC 6241, June 2011. 1505 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1506 Shell (SSH)", RFC 6242, June 2011. 1508 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1509 Protocol (NETCONF) Access Control Model", RFC 6536, March 1510 2012. 1512 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1513 July 2013. 1515 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1516 RFC 7950, August 2016. 1518 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1519 Protocol", RFC 8040, January 2017. 1521 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1522 2119 Key Words", RFC 8174, May 2017. 1524 11.2. Informative References 1526 [I-D.draft-ietf-i2rs-ephemeral-state] 1527 Haas, J. and S. Hares, "I2RS Ephemeral State 1528 Requirements", I-D draft-ietf-i2rs-ephemeral-state-23, 1529 November 2016. 1531 [I-D.draft-ietf-i2rs-usecase-reqs-summary] 1532 Hares, S. and M. Chen, "Summary of I2RS Use Case 1533 Requirements", I-D draft-ietf-i2rs-usecase-reqs-summary- 1534 03, November 2016. 1536 [I-D.draft-ietf-i2rs-yang-l3-topology] 1537 Clemm, A., Medved, J., Varga, R., Liu, X., 1538 Ananthakrishnan, H., and N. Bahadur, "A YANG Data Model 1539 for Layer 3 Topologies", I-D draft-ietf-i2rs-yang-l3- 1540 topology-10, July 2017. 1542 [I-D.draft-ietf-netconf-yang-push] 1543 Clemm, A., Voit, E., Gonzalez Prieto, A., Tripathy, A., 1544 Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 1545 "Subscribing to YANG datastore push updates", I-D draft- 1546 ietf-netconf-yang-push-08, August 2017. 1548 [I-D.draft-ietf-netmod-yang-tree-diagrams] 1549 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", I-D 1550 draft-ietf-netmod-yang-tree-diagrams, June 2017. 1552 [RFC1195] Callon, R., "Use of OSI IS-IS for Routing in TCP/IP and 1553 Dual Environments", RFC 1195, December 1990. 1555 [RFC2328] Moy, J., "OSPF Version 2", RFC 2328, April 1998. 1557 [RFC3209] Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V., 1558 and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP 1559 Tunnels", RFC 3209, December 2001. 1561 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1562 Management", RFC 7223, May 2014. 1564 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1565 RFC 7952, August 2016. 1567 [RFC8022] Lhotka, L. and A. Lindem, "A YANG Data Model for Routing 1568 Management", RFC 8022, November 2016. 1570 Appendix A. Appendix: Model Use Cases 1572 A.1. Fetching Topology from a Network Element 1574 In its simplest form, topology is learned by a network element (e.g., 1575 a router) through its participation in peering protocols (IS-IS, BGP, 1576 etc.). This learned topology can then be exported (e.g., to an NMS) 1577 for external utilization. Typically, any network element in a domain 1578 can be queried for its topology and expected to return the same 1579 result. 1581 In a slightly more complex form, the network element may be a 1582 controller, either by nature of it having satellite or subtended 1583 devices hanging off of it, or in the more classical sense, such as 1584 special device designated to orchestrate the activities of a number 1585 of other devices (e.g., an optical controller). In this case, the 1586 controller device is logically a singleton and must be queried 1587 distinctly. 1589 It is worth noting that controllers can be built on top of 1590 controllers to establish a topology incorporating of all the domains 1591 within an entire network. 1593 In all of the cases above, the topology learned by the network 1594 element is considered to be operational state data. That is, the 1595 data is accumulated purely by the network element's interactions with 1596 other systems and is subject to change dynamically without input or 1597 consent. 1599 A.2. Modifying TE Topology Imported from an Optical Controller 1601 Consider a scenario where an Optical Transport Controller presents 1602 its topology in abstract TE Terms to a Client Packet Controller. 1603 This Customized Topology (that gets merged into the Client's native 1604 topology) contains sufficient information for the path computing 1605 client to select paths across the optical domain according to its 1606 policies. If the Client determines (at any given point in time) that 1607 this imported topology does not exactly cater to its requirements, it 1608 may decide to request modifications to the topology. Such 1609 customization requests may include addition or deletion of topoogical 1610 elements or modification of attributes associated with existing 1611 topological elements. From the perspective of the Optical 1612 Controller, these requests translate into configuration changes to 1613 the exported abstract topology. 1615 A.3. Annotating Topology for Local Computation 1617 In certain scenarios, the topology learned by a controller needs to 1618 be augmented with additional attributes before running a computation 1619 algorithm on it. Consider the case where a path-computation 1620 application on the controller needs to take the geographic 1621 coordinates of the nodes into account while computing paths on the 1622 learned topology. If the learned topology does not contain these 1623 coordinates, then these additional attributes must be configured on 1624 the corresponding topological elements. 1626 A.4. SDN Controller-Based Configuration of Overlays on Top of Underlays 1628 In this scenario, an SDN controller (for example, Open Daylight) 1629 maintains a view of the topology of the network that it controls 1630 based on information that it discovers from the network. In 1631 addition, it provides an application in which it configures and 1632 maintains an overlay topology. 1634 The SDN Controller thus maintains two roles: 1636 o It is a client to the network. 1638 o It is a server to its own northbound applications and clients, 1639 e.g. an OSS. 1641 In other words, one system's client (or controller, in this case) may 1642 be another system's server (or "uber-network device"). 1644 In this scenario, the SDN controller maintains a consolidated data 1645 model of multiple layers of topology. This includes the lower layers 1646 of the network topology, built from information that is discovered 1647 from the network. It also includes upper layers of topology overlay, 1648 configurable by the controller's client, i.e. the OSS. To the OSS, 1649 the lower topology layers constitute "read-only" information. The 1650 upper topology layers need to be read-writable. 1652 Appendix B. Appendix: Companion YANG models for non-NMDA compliant 1653 implementations 1655 The YANG modules defined in this document are designed to be used in 1656 conjunction with implementations that support the Network Management 1657 Datastore Architecture (NMDA) defined in 1658 [I-D.draft-ietf-netmod-revised-datastores]. In order to allow 1659 implementations to use the data model even in cases when NMDA is not 1660 supported, in the following two companion modules are defined that 1661 represent the operational state of networks and network topologies. 1662 The modules, ietf-network-state and ietf-network-topology-state, 1663 mirror modules ietf-network and ietf-network-topology defined earlier 1664 in this document. However, all data nodes are non-configurable. 1665 They represent state that comes into being by either learning 1666 topology information from the network, or by applying configuration 1667 from the mirrored modules. 1669 The companion modules, ietf-network-state and ietf-network-topology- 1670 state, are redundant and SHOULD NOT be supported by implementations 1671 that support NMDA. It is for this reason that the definitions are 1672 defined in an appendix. 1674 As the structure of both modules mirrors that of their underlying 1675 modules, the YANG tree is not depicted separately. 1677 B.1. YANG Model for Network State 1679 NOTE TO RFC EDITOR: Please change the date in the file name after the 1680 CODE BEGINS statement to the date of the publication when published. 1682 file "ietf-network-state@2017-09-05.yang" 1683 module ietf-network-state { 1684 yang-version 1.1; 1685 namespace "urn:ietf:params:xml:ns:yang:ietf-network-state"; 1686 prefix nd-s; 1688 import ietf-network { 1689 prefix nd; 1690 reference 1691 "draft-ietf-i2rs-yang-network-topo-15 1692 NOTE TO RFC EDITOR: Please replace above reference to 1693 draft-ietf-i2rs-yang-network-topo-15 with RFC 1694 number when published (i.e. RFC xxxx)."; 1695 } 1697 organization 1698 "IETF I2RS (Interface to the Routing System) Working Group"; 1700 contact 1701 "WG Web: 1702 WG List: 1704 Editor: Alexander Clemm 1705 1707 Editor: Jan Medved 1708 1710 Editor: Robert Varga 1711 1713 Editor: Nitin Bahadur 1714 1716 Editor: Hariharan Ananthakrishnan 1717 1719 Editor: Xufeng Liu 1720 "; 1722 description 1723 "This module defines a common base data model for a collection 1724 of nodes in a network. Node definitions are further used 1725 in network topologies and inventories. It represents 1726 information that is either learned and automatically populated, 1727 or information that results from applying configured netwok 1728 information configured per the ietf-network data model, 1729 mirroring the corresponding data nodes in this data model. 1731 The data model mirrors ietf-network, but contains only 1732 read-only state data. The data model is not needed when the 1733 underlying implementation infrastructure supports the Network 1734 Management Datastore Architecture (NMDA). 1736 Copyright (c) 2017 IETF Trust and the persons identified as 1737 authors of the code. All rights reserved. 1739 Redistribution and use in source and binary forms, with or 1740 without modification, is permitted pursuant to, and subject 1741 to the license terms contained in, the Simplified BSD License 1742 set forth in Section 4.c of the IETF Trust's Legal Provisions 1743 Relating to IETF Documents 1744 (http://trustee.ietf.org/license-info). 1746 This version of this YANG module is part of 1747 draft-ietf-i2rs-yang-network-topo-15; 1748 see the RFC itself for full legal notices. 1750 NOTE TO RFC EDITOR: Please replace above reference to 1751 draft-ietf-i2rs-yang-network-topo-15 with RFC 1752 number when published (i.e. RFC xxxx)."; 1754 revision 2017-09-05 { 1755 description 1756 "Initial revision. 1757 NOTE TO RFC EDITOR: 1758 (1) Please replace the following reference 1759 to draft-ietf-i2rs-yang-network-topo-15 with 1760 RFC number when published (i.e. RFC xxxx). 1761 (2) Please replace the date in the revision statement with the 1762 date of the publication when published."; 1763 reference 1764 "draft-ietf-i2rs-yang-network-topo-15"; 1765 } 1767 grouping network-ref { 1768 description 1769 "Contains the information necessary to reference a network, 1770 for example an underlay network."; 1771 leaf network-ref { 1772 type leafref { 1773 path "/nd-s:networks/nd-s:network/nd-s:network-id"; 1774 require-instance false; 1775 } 1776 description 1777 "Used to reference a network, for example an underlay 1778 network."; 1779 } 1780 } 1782 grouping node-ref { 1783 description 1784 "Contains the information necessary to reference a node."; 1785 leaf node-ref { 1786 type leafref { 1787 path "/nd-s:networks/nd-s:network[nd-s:network-id=current()"+ 1788 "/../network-ref]/nd-s:node/nd-s:node-id"; 1789 require-instance false; 1790 } 1791 description 1792 "Used to reference a node. 1793 Nodes are identified relative to the network they are 1794 contained in."; 1795 } 1796 uses network-ref; 1797 } 1799 container networks { 1800 config false; 1801 description 1802 "Serves as top-level container for a list of networks."; 1803 list network { 1804 key "network-id"; 1805 description 1806 "Describes a network. 1808 A network typically contains an inventory of nodes, 1809 topological information (augmented through 1810 network-topology data model), as well as layering 1811 information."; 1812 container network-types { 1813 description 1814 "Serves as an augmentation target. 1815 The network type is indicated through corresponding 1816 presence containers augmented into this container."; 1817 } 1818 leaf network-id { 1819 type nd:network-id; 1820 description 1821 "Identifies a network."; 1822 } 1823 list supporting-network { 1824 key "network-ref"; 1825 description 1826 "An underlay network, used to represent layered network 1827 topologies."; 1828 leaf network-ref { 1829 type leafref { 1830 path "/nd-s:networks/nd-s:network/nd-s:network-id"; 1831 require-instance false; 1832 } 1833 description 1834 "References the underlay network."; 1835 } 1836 } 1837 list node { 1838 key "node-id"; 1839 description 1840 "The inventory of nodes of this network."; 1841 leaf node-id { 1842 type nd:node-id; 1843 description 1844 "Identifies a node uniquely within the containing 1845 network."; 1846 } 1847 list supporting-node { 1848 key "network-ref node-ref"; 1849 description 1850 "Represents another node, in an underlay network, that 1851 this node is supported by. Used to represent layering 1852 structure."; 1853 leaf network-ref { 1854 type leafref { 1855 path "../../../nd-s:supporting-network/nd-s:network-ref"; 1857 require-instance false; 1858 } 1859 description 1860 "References the underlay network that the 1861 underlay node is part of."; 1862 } 1863 leaf node-ref { 1864 type leafref { 1865 path "/nd-s:networks/nd-s:network/nd-s:node/nd-s:node-id"; 1866 require-instance false; 1867 } 1868 description 1869 "References the underlay node itself."; 1870 } 1871 } 1872 } 1873 } 1874 } 1875 } 1876 1878 B.2. YANG Data Model for Network Topology State 1880 NOTE TO RFC EDITOR: Please change the date in the file name after the 1881 CODE BEGINS statement to the date of the publication when published. 1883 file "ietf-network-topology-state@2017-09-05.yang" 1884 module ietf-network-topology-state { 1885 yang-version 1.1; 1886 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology-state"; 1887 prefix lnk-s; 1889 import ietf-network-state { 1890 prefix nd-s; 1891 reference 1892 "draft-ietf-i2rs-yang-network-topo-15 1893 NOTE TO RFC EDITOR: Please replace above reference to 1894 draft-ietf-i2rs-yang-network-topo-15 with RFC 1895 number when published (i.e. RFC xxxx)."; 1896 } 1897 import ietf-network-topology { 1898 prefix lnk; 1899 reference 1900 "draft-ietf-i2rs-yang-network-topo-15 1901 NOTE TO RFC EDITOR: Please replace above reference to 1902 draft-ietf-i2rs-yang-network-topo-15 with RFC 1903 number when published (i.e. RFC xxxx)."; 1904 } 1905 organization 1906 "IETF I2RS (Interface to the Routing System) Working Group"; 1908 contact 1909 "WG Web: 1910 WG List: 1912 Editor: Alexander Clemm 1913 1915 Editor: Jan Medved 1916 1918 Editor: Robert Varga 1919 1921 Editor: Nitin Bahadur 1922 1924 Editor: Hariharan Ananthakrishnan 1925 1927 Editor: Xufeng Liu 1928 "; 1930 description 1931 "This module defines a common base data model for network 1932 topology state, representing topology that is either learned, 1933 or topology that results from applying topology that has been 1934 configured per the ietf-network-topology data model, mirroring 1935 the corresponding data nodes in this data model. It augments 1936 the base network state data model with links to connect nodes, 1937 as well as termination points to terminate links on nodes. 1939 The data model mirrors ietf-network-topology, but contains only 1940 read-only state data. The data model is not needed when the 1941 underlying implementation infrastructure supports the Network 1942 Management Datastore Architecture (NMDA). 1944 Copyright (c) 2017 IETF Trust and the persons identified as 1945 authors of the code. All rights reserved. 1947 Redistribution and use in source and binary forms, with or 1948 without modification, is permitted pursuant to, and subject 1949 to the license terms contained in, the Simplified BSD License 1950 set forth in Section 4.c of the IETF Trust's Legal Provisions 1951 Relating to IETF Documents 1952 (http://trustee.ietf.org/license-info). 1953 This version of this YANG module is part of 1954 draft-ietf-i2rs-yang-network-topo-15; 1955 see the RFC itself for full legal notices. 1957 NOTE TO RFC EDITOR: Please replace above reference to 1958 draft-ietf-i2rs-yang-network-topo-15 with RFC 1959 number when published (i.e. RFC xxxx)."; 1961 revision 2017-09-05 { 1962 description 1963 "Initial revision. 1964 NOTE TO RFC EDITOR: 1965 (1) Please replace the following reference 1966 to draft-ietf-i2rs-yang-network-topo-15 with 1967 RFC number when published (i.e. RFC xxxx). 1968 (2) Please replace the date in the revision statement with the 1969 date of publication when published."; 1970 reference 1971 "draft-ietf-i2rs-yang-network-topo-15"; 1972 } 1974 grouping link-ref { 1975 description 1976 "References a link in a specific network."; 1977 leaf link-ref { 1978 type leafref { 1979 path "/nd-s:networks/nd-s:network[nd-s:network-id=current()"+ 1980 "/../network-ref]/lnk-s:link/lnk-s:link-id"; 1981 require-instance false; 1982 } 1983 description 1984 "A type for an absolute reference a link instance. 1985 (This type should not be used for relative references. 1986 In such a case, a relative path should be used instead.)"; 1987 } 1988 uses nd-s:network-ref; 1989 } 1991 grouping tp-ref { 1992 description 1993 "References a termination point in a specific node."; 1994 leaf tp-ref { 1995 type leafref { 1996 path "/nd-s:networks/nd-s:network[nd-s:network-id=current()"+ 1997 "/../network-ref]/nd-s:node[nd-s:node-id=current()/../"+ 1998 "node-ref]/lnk-s:termination-point/lnk-s:tp-id"; 1999 require-instance false; 2000 } 2001 description 2002 "A type for an absolute reference to a termination point. 2003 (This type should not be used for relative references. 2004 In such a case, a relative path should be used instead.)"; 2005 } 2006 uses nd-s:node-ref; 2007 } 2009 augment "/nd-s:networks/nd-s:network" { 2010 description 2011 "Add links to the network data model."; 2012 list link { 2013 key "link-id"; 2014 description 2015 "A network link connects a local (source) node and 2016 a remote (destination) node via a set of 2017 the respective node's termination points. 2018 It is possible to have several links between the same 2019 source and destination nodes. Likewise, a link could 2020 potentially be re-homed between termination points. 2021 Therefore, in order to ensure that we would always know 2022 to distinguish between links, every link is identified by 2023 a dedicated link identifier. Note that a link models a 2024 point-to-point link, not a multipoint link."; 2025 container source { 2026 description 2027 "This container holds the logical source of a particular 2028 link."; 2029 leaf source-node { 2030 type leafref { 2031 path "../../../nd-s:node/nd-s:node-id"; 2032 require-instance false; 2033 } 2034 description 2035 "Source node identifier, must be in same topology."; 2036 } 2037 leaf source-tp { 2038 type leafref { 2039 path "../../../nd-s:node[nd-s:node-id=current()/../"+ 2040 "source-node]/termination-point/tp-id"; 2041 require-instance false; 2042 } 2043 description 2044 "Termination point within source node that terminates 2045 the link."; 2046 } 2047 } 2048 container destination { 2049 description 2050 "This container holds the logical destination of a 2051 particular link."; 2052 leaf dest-node { 2053 type leafref { 2054 path "../../../nd-s:node/nd-s:node-id"; 2055 require-instance false; 2056 } 2057 description 2058 "Destination node identifier, must be in the same 2059 network."; 2060 } 2061 leaf dest-tp { 2062 type leafref { 2063 path "../../../nd-s:node[nd-s:node-id=current()/../"+ 2064 "dest-node]/termination-point/tp-id"; 2065 require-instance false; 2066 } 2067 description 2068 "Termination point within destination node that 2069 terminates the link."; 2070 } 2071 } 2072 leaf link-id { 2073 type lnk:link-id; 2074 description 2075 "The identifier of a link in the topology. 2076 A link is specific to a topology to which it belongs."; 2077 } 2078 list supporting-link { 2079 key "network-ref link-ref"; 2080 description 2081 "Identifies the link, or links, that this link 2082 is dependent on."; 2083 leaf network-ref { 2084 type leafref { 2085 path "../../../nd-s:supporting-network/nd-s:network-ref"; 2086 require-instance false; 2087 } 2088 description 2089 "This leaf identifies in which underlay topology 2090 the supporting link is present."; 2091 } 2092 leaf link-ref { 2093 type leafref { 2094 path "/nd-s:networks/nd-s:network[nd-s:network-id="+ 2095 "current()/../network-ref]/link/link-id"; 2096 require-instance false; 2098 } 2099 description 2100 "This leaf identifies a link which is a part 2101 of this link's underlay. Reference loops in which 2102 a link identifies itself as its underlay, either 2103 directly or transitively, are not allowed."; 2104 } 2105 } 2106 } 2107 } 2108 augment "/nd-s:networks/nd-s:network/nd-s:node" { 2109 description 2110 "Augment termination points which terminate links. 2111 Termination points can ultimately be mapped to interfaces."; 2112 list termination-point { 2113 key "tp-id"; 2114 description 2115 "A termination point can terminate a link. 2116 Depending on the type of topology, a termination point 2117 could, for example, refer to a port or an interface."; 2118 leaf tp-id { 2119 type lnk:tp-id; 2120 description 2121 "Termination point identifier."; 2122 } 2123 list supporting-termination-point { 2124 key "network-ref node-ref tp-ref"; 2125 description 2126 "This list identifies any termination points that 2127 the termination point is dependent on, or maps onto. 2128 Those termination points will themselves be contained 2129 in a supporting node. 2130 This dependency information can be inferred from 2131 the dependencies between links. For this reason, 2132 this item is not separately configurable. Hence no 2133 corresponding constraint needs to be articulated. 2134 The corresponding information is simply provided by the 2135 implementing system."; 2136 leaf network-ref { 2137 type leafref { 2138 path "../../../nd-s:supporting-node/nd-s:network-ref"; 2139 require-instance false; 2140 } 2141 description 2142 "This leaf identifies in which topology the 2143 supporting termination point is present."; 2144 } 2145 leaf node-ref { 2146 type leafref { 2147 path "../../../nd-s:supporting-node/nd-s:node-ref"; 2148 require-instance false; 2149 } 2150 description 2151 "This leaf identifies in which node the supporting 2152 termination point is present."; 2153 } 2154 leaf tp-ref { 2155 type leafref { 2156 path "/nd-s:networks/nd-s:network[nd-s:network-id="+ 2157 "current()/../network-ref]/nd-s:node[nd-s:node-id="+ 2158 "current()/../node-ref]/termination-point/tp-id"; 2159 require-instance false; 2160 } 2161 description 2162 "Reference to the underlay node, must be in a 2163 different topology"; 2164 } 2165 } 2166 } 2167 } 2168 } 2169 2171 Authors' Addresses 2173 Alexander Clemm 2174 Huawei 2176 EMail: ludwig@clemm.org 2178 Jan Medved 2179 Cisco 2181 EMail: jmedved@cisco.com 2183 Robert Varga 2184 Pantheon Technologies SRO 2186 EMail: robert.varga@pantheon.sk 2187 Nitin Bahadur 2188 Bracket Computing 2190 EMail: nitin_bahadur@yahoo.com 2192 Hariharan Ananthakrishnan 2193 Packet Design 2195 EMail: hari@packetdesign.com 2197 Xufeng Liu 2198 Jabil 2200 EMail: Xufeng_Liu@jabil.com