idnits 2.17.1 draft-ietf-i2rs-yang-network-topo-16.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 19, 2017) is 2382 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-11 == 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 23, 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 19, 2017 16 A Data Model for Network Topologies 17 draft-ietf-i2rs-yang-network-topo-16.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 23, 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 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-19.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-16; 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-16 with RFC 892 number when published (i.e. RFC xxxx)."; 894 revision 2017-09-19 { 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-16 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-16"; 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-19.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-16 1061 NOTE TO RFC EDITOR: 1062 (1) Please replace above reference to 1063 draft-ietf-i2rs-yang-network-topo-16 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-16; 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-16 with RFC 1115 number when published (i.e. RFC xxxx)."; 1117 revision 2017-09-19 { 1118 description 1119 "Initial revision. 1120 NOTE TO RFC EDITOR: Please replace the following reference 1121 to draft-ietf-i2rs-yang-network-topo-16 with 1122 RFC number when published (i.e. RFC xxxx)."; 1123 reference 1124 "draft-ietf-i2rs-yang-network-topo-16"; 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-16 (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-16.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-16.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-16.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-16.txt (RFC form) 1403 8. Security Considerations 1405 The YANG modules defined in this document are 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 The YANG modules define information that can be configurable in 1418 certain instances, for example in the case of overlay topologies that 1419 can be created by client applications. In such cases, a malicious 1420 client could introduce topologies that are undesired. Specifically, 1421 a malicious client could attempt to remove or add a node, a link, a 1422 termination point, by creating or deleting corresponding elements in 1423 the node, link, and termination point lists, respectively. In the 1424 case of a topology that is learned, the server will automatically 1425 prohibit such misconfiguration attempts. In the case of a topology 1426 that is configured, i.e. whose origin is "intended", the undesired 1427 configuration could become effective and be reflected in the 1428 operational datastore, leading to disruption of services provided via 1429 this topology might be disrupted. For example, the topology could be 1430 "cut" or be configured in a suboptimal way, leading to increased 1431 consumption of resources in the underlay network due to resulting 1432 routing and bandwidth utilization inefficiencies. Likewise, it could 1433 lead to degradation of service levels as well as possibly disruption 1434 of service. For those reasons, it is important that the NETCONF 1435 access control model is vigorously applied to prevent topology 1436 misconfiguration by unauthorized clients. 1438 Specifically, there are a number of data nodes defined in these YANG 1439 module that are writable/creatable/deletable (i.e., config true, 1440 which is the default). These data nodes may be considered sensitive 1441 or vulnerable in some network environments. Write operations (e.g., 1442 edit-config) to these data nodes without proper protection can have a 1443 negative effect on network operations. These are the subtrees and 1444 data nodes and their sensitivity/vulnerability in the ietf-network 1445 module: 1447 o network: A malicious client could attempt to remove or add a 1448 network in an attempt to remove an overlay topology, or create an 1449 unauthorized overlay. 1451 o supporting-network: A malicious client could attempt to disrupt 1452 the logical structure of the model, resulting in lack of overall 1453 data integrity and making it more difficult to, for example, 1454 troubleshoot problems rooted in the layering of network 1455 topologies. 1457 o node: A malicious client could attempt to remove or add a node 1458 from network, for example in order to sabotage the topology of a 1459 network overlay. 1461 o supporting-node: A malicious client could attempt to change the 1462 supporting-node in order to sabotage the layering of an overlay. 1464 These are the subtrees and data nodes and their sensitivity/ 1465 vulnerability in the ietf-network-topology module: 1467 o link: A malicious client could attempt to remove a link from a 1468 topology, or add a new link, or manipulate the way the link is 1469 layered over supporting links, or modify the source or destination 1470 of the link. Either way, the structure of the topology would be 1471 sabotaged, which could, for example, result in an overlay topology 1472 that is less than optimal. 1474 o termination-point: A malicious client could attempt to remove 1475 termination points from a node, or add "phantom" termination 1476 points to a node, or change the layering dependencies of 1477 termination points, again in an attempt to sabotage the integrity 1478 of a topology and potentially disrupt orderly operations of an 1479 overlay. 1481 9. Contributors 1483 The data model presented in this paper was contributed to by more 1484 people than can be listed on the author list. Additional 1485 contributors include: 1487 o Vishnu Pavan Beeram, Juniper 1489 o Ken Gray, Cisco 1491 o Tom Nadeau, Brocade 1493 o Tony Tkacik 1495 o Kent Watsen, Juniper 1497 o Aleksandr Zhdankin, Cisco 1499 10. Acknowledgements 1501 We wish to acknowledge the helpful contributions, comments, and 1502 suggestions that were received from Alia Atlas, Andy Bierman, Martin 1503 Bjorklund, Igor Bryskin, Benoit Claise, Susan Hares, Ladislav Lhotka, 1504 Carlos Pignataro, Juergen Schoenwaelder, Robert Wilton, and Xian 1505 Zhang. 1507 11. References 1509 11.1. Normative References 1511 [I-D.draft-ietf-netmod-revised-datastores] 1512 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1513 and R. Wilton, "A Revised Conceptual Model for YANG 1514 Datastores", I-D draft-ietf-netmod-revised-datastores-02, 1515 May 2017. 1517 [RFC2119] Bradner, S., "Key words for use in RFCs to indicate 1518 requirement levels", RFC 2119, March 1997. 1520 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1521 2004. 1523 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1524 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1526 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1527 Network Configuration Protocol (NETCONF)", RFC 6020, 1528 October 2010. 1530 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1531 Bierman, "Network Configuration Protocol (NETCONF)", 1532 RFC 6241, June 2011. 1534 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1535 Shell (SSH)", RFC 6242, June 2011. 1537 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1538 Protocol (NETCONF) Access Control Model", RFC 6536, March 1539 2012. 1541 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1542 July 2013. 1544 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1545 RFC 7950, August 2016. 1547 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1548 Protocol", RFC 8040, January 2017. 1550 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1551 2119 Key Words", RFC 8174, May 2017. 1553 11.2. Informative References 1555 [I-D.draft-ietf-i2rs-ephemeral-state] 1556 Haas, J. and S. Hares, "I2RS Ephemeral State 1557 Requirements", I-D draft-ietf-i2rs-ephemeral-state-23, 1558 November 2016. 1560 [I-D.draft-ietf-i2rs-usecase-reqs-summary] 1561 Hares, S. and M. Chen, "Summary of I2RS Use Case 1562 Requirements", I-D draft-ietf-i2rs-usecase-reqs-summary- 1563 03, November 2016. 1565 [I-D.draft-ietf-i2rs-yang-l3-topology] 1566 Clemm, A., Medved, J., Varga, R., Liu, X., 1567 Ananthakrishnan, H., and N. Bahadur, "A YANG Data Model 1568 for Layer 3 Topologies", I-D draft-ietf-i2rs-yang-l3- 1569 topology-11, September 2017. 1571 [I-D.draft-ietf-netconf-yang-push] 1572 Clemm, A., Voit, E., Gonzalez Prieto, A., Tripathy, A., 1573 Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 1574 "Subscribing to YANG datastore push updates", I-D draft- 1575 ietf-netconf-yang-push-08, August 2017. 1577 [I-D.draft-ietf-netmod-yang-tree-diagrams] 1578 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", I-D 1579 draft-ietf-netmod-yang-tree-diagrams, June 2017. 1581 [RFC1195] Callon, R., "Use of OSI IS-IS for Routing in TCP/IP and 1582 Dual Environments", RFC 1195, December 1990. 1584 [RFC2328] Moy, J., "OSPF Version 2", RFC 2328, April 1998. 1586 [RFC3209] Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V., 1587 and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP 1588 Tunnels", RFC 3209, December 2001. 1590 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1591 Management", RFC 7223, May 2014. 1593 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1594 RFC 7952, August 2016. 1596 [RFC8022] Lhotka, L. and A. Lindem, "A YANG Data Model for Routing 1597 Management", RFC 8022, November 2016. 1599 Appendix A. Appendix: Model Use Cases 1601 A.1. Fetching Topology from a Network Element 1603 In its simplest form, topology is learned by a network element (e.g., 1604 a router) through its participation in peering protocols (IS-IS, BGP, 1605 etc.). This learned topology can then be exported (e.g., to an NMS) 1606 for external utilization. Typically, any network element in a domain 1607 can be queried for its topology and expected to return the same 1608 result. 1610 In a slightly more complex form, the network element may be a 1611 controller, either by nature of it having satellite or subtended 1612 devices hanging off of it, or in the more classical sense, such as 1613 special device designated to orchestrate the activities of a number 1614 of other devices (e.g., an optical controller). In this case, the 1615 controller device is logically a singleton and must be queried 1616 distinctly. 1618 It is worth noting that controllers can be built on top of 1619 controllers to establish a topology incorporating of all the domains 1620 within an entire network. 1622 In all of the cases above, the topology learned by the network 1623 element is considered to be operational state data. That is, the 1624 data is accumulated purely by the network element's interactions with 1625 other systems and is subject to change dynamically without input or 1626 consent. 1628 A.2. Modifying TE Topology Imported from an Optical Controller 1630 Consider a scenario where an Optical Transport Controller presents 1631 its topology in abstract TE Terms to a Client Packet Controller. 1632 This Customized Topology (that gets merged into the Client's native 1633 topology) contains sufficient information for the path computing 1634 client to select paths across the optical domain according to its 1635 policies. If the Client determines (at any given point in time) that 1636 this imported topology does not exactly cater to its requirements, it 1637 may decide to request modifications to the topology. Such 1638 customization requests may include addition or deletion of topoogical 1639 elements or modification of attributes associated with existing 1640 topological elements. From the perspective of the Optical 1641 Controller, these requests translate into configuration changes to 1642 the exported abstract topology. 1644 A.3. Annotating Topology for Local Computation 1646 In certain scenarios, the topology learned by a controller needs to 1647 be augmented with additional attributes before running a computation 1648 algorithm on it. Consider the case where a path-computation 1649 application on the controller needs to take the geographic 1650 coordinates of the nodes into account while computing paths on the 1651 learned topology. If the learned topology does not contain these 1652 coordinates, then these additional attributes must be configured on 1653 the corresponding topological elements. 1655 A.4. SDN Controller-Based Configuration of Overlays on Top of Underlays 1657 In this scenario, an SDN controller (for example, Open Daylight) 1658 maintains a view of the topology of the network that it controls 1659 based on information that it discovers from the network. In 1660 addition, it provides an application in which it configures and 1661 maintains an overlay topology. 1663 The SDN Controller thus maintains two roles: 1665 o It is a client to the network. 1667 o It is a server to its own northbound applications and clients, 1668 e.g. an OSS. 1670 In other words, one system's client (or controller, in this case) may 1671 be another system's server (or "uber-network device"). 1673 In this scenario, the SDN controller maintains a consolidated data 1674 model of multiple layers of topology. This includes the lower layers 1675 of the network topology, built from information that is discovered 1676 from the network. It also includes upper layers of topology overlay, 1677 configurable by the controller's client, i.e. the OSS. To the OSS, 1678 the lower topology layers constitute "read-only" information. The 1679 upper topology layers need to be read-writable. 1681 Appendix B. Appendix: Companion YANG models for non-NMDA compliant 1682 implementations 1684 The YANG modules defined in this document are designed to be used in 1685 conjunction with implementations that support the Network Management 1686 Datastore Architecture (NMDA) defined in 1687 [I-D.draft-ietf-netmod-revised-datastores]. In order to allow 1688 implementations to use the data model even in cases when NMDA is not 1689 supported, in the following two companion modules are defined that 1690 represent the operational state of networks and network topologies. 1691 The modules, ietf-network-state and ietf-network-topology-state, 1692 mirror modules ietf-network and ietf-network-topology defined earlier 1693 in this document. However, all data nodes are non-configurable. 1694 They represent state that comes into being by either learning 1695 topology information from the network, or by applying configuration 1696 from the mirrored modules. 1698 The companion modules, ietf-network-state and ietf-network-topology- 1699 state, are redundant and SHOULD NOT be supported by implementations 1700 that support NMDA. It is for this reason that the definitions are 1701 defined in an appendix. 1703 As the structure of both modules mirrors that of their underlying 1704 modules, the YANG tree is not depicted separately. 1706 B.1. YANG Model for Network State 1708 NOTE TO RFC EDITOR: Please change the date in the file name after the 1709 CODE BEGINS statement to the date of the publication when published. 1711 file "ietf-network-state@2017-09-19.yang" 1712 module ietf-network-state { 1713 yang-version 1.1; 1714 namespace "urn:ietf:params:xml:ns:yang:ietf-network-state"; 1715 prefix nd-s; 1717 import ietf-network { 1718 prefix nd; 1719 reference 1720 "draft-ietf-i2rs-yang-network-topo-16 1721 NOTE TO RFC EDITOR: Please replace above reference to 1722 draft-ietf-i2rs-yang-network-topo-16 with RFC 1723 number when published (i.e. RFC xxxx)."; 1724 } 1726 organization 1727 "IETF I2RS (Interface to the Routing System) Working Group"; 1729 contact 1730 "WG Web: 1731 WG List: 1733 Editor: Alexander Clemm 1734 1736 Editor: Jan Medved 1737 1739 Editor: Robert Varga 1740 1742 Editor: Nitin Bahadur 1743 1745 Editor: Hariharan Ananthakrishnan 1746 1748 Editor: Xufeng Liu 1749 "; 1751 description 1752 "This module defines a common base data model for a collection 1753 of nodes in a network. Node definitions are further used 1754 in network topologies and inventories. It represents 1755 information that is either learned and automatically populated, 1756 or information that results from applying configured netwok 1757 information configured per the ietf-network data model, 1758 mirroring the corresponding data nodes in this data model. 1760 The data model mirrors ietf-network, but contains only 1761 read-only state data. The data model is not needed when the 1762 underlying implementation infrastructure supports the Network 1763 Management Datastore Architecture (NMDA). 1765 Copyright (c) 2017 IETF Trust and the persons identified as 1766 authors of the code. All rights reserved. 1768 Redistribution and use in source and binary forms, with or 1769 without modification, is permitted pursuant to, and subject 1770 to the license terms contained in, the Simplified BSD License 1771 set forth in Section 4.c of the IETF Trust's Legal Provisions 1772 Relating to IETF Documents 1773 (http://trustee.ietf.org/license-info). 1775 This version of this YANG module is part of 1776 draft-ietf-i2rs-yang-network-topo-16; 1777 see the RFC itself for full legal notices. 1779 NOTE TO RFC EDITOR: Please replace above reference to 1780 draft-ietf-i2rs-yang-network-topo-16 with RFC 1781 number when published (i.e. RFC xxxx)."; 1783 revision 2017-09-19 { 1784 description 1785 "Initial revision. 1786 NOTE TO RFC EDITOR: 1787 (1) Please replace the following reference 1788 to draft-ietf-i2rs-yang-network-topo-16 with 1789 RFC number when published (i.e. RFC xxxx). 1790 (2) Please replace the date in the revision statement with the 1791 date of the publication when published."; 1792 reference 1793 "draft-ietf-i2rs-yang-network-topo-16"; 1794 } 1796 grouping network-ref { 1797 description 1798 "Contains the information necessary to reference a network, 1799 for example an underlay network."; 1800 leaf network-ref { 1801 type leafref { 1802 path "/nd-s:networks/nd-s:network/nd-s:network-id"; 1803 require-instance false; 1804 } 1805 description 1806 "Used to reference a network, for example an underlay 1807 network."; 1808 } 1809 } 1811 grouping node-ref { 1812 description 1813 "Contains the information necessary to reference a node."; 1814 leaf node-ref { 1815 type leafref { 1816 path "/nd-s:networks/nd-s:network[nd-s:network-id=current()"+ 1817 "/../network-ref]/nd-s:node/nd-s:node-id"; 1818 require-instance false; 1819 } 1820 description 1821 "Used to reference a node. 1822 Nodes are identified relative to the network they are 1823 contained in."; 1824 } 1825 uses network-ref; 1826 } 1828 container networks { 1829 config false; 1830 description 1831 "Serves as top-level container for a list of networks."; 1832 list network { 1833 key "network-id"; 1834 description 1835 "Describes a network. 1837 A network typically contains an inventory of nodes, 1838 topological information (augmented through 1839 network-topology data model), as well as layering 1840 information."; 1841 container network-types { 1842 description 1843 "Serves as an augmentation target. 1844 The network type is indicated through corresponding 1845 presence containers augmented into this container."; 1846 } 1847 leaf network-id { 1848 type nd:network-id; 1849 description 1850 "Identifies a network."; 1851 } 1852 list supporting-network { 1853 key "network-ref"; 1854 description 1855 "An underlay network, used to represent layered network 1856 topologies."; 1857 leaf network-ref { 1858 type leafref { 1859 path "/nd-s:networks/nd-s:network/nd-s:network-id"; 1860 require-instance false; 1861 } 1862 description 1863 "References the underlay network."; 1864 } 1865 } 1866 list node { 1867 key "node-id"; 1868 description 1869 "The inventory of nodes of this network."; 1870 leaf node-id { 1871 type nd:node-id; 1872 description 1873 "Identifies a node uniquely within the containing 1874 network."; 1875 } 1876 list supporting-node { 1877 key "network-ref node-ref"; 1878 description 1879 "Represents another node, in an underlay network, that 1880 this node is supported by. Used to represent layering 1881 structure."; 1882 leaf network-ref { 1883 type leafref { 1884 path "../../../nd-s:supporting-network/nd-s:network-ref"; 1886 require-instance false; 1887 } 1888 description 1889 "References the underlay network that the 1890 underlay node is part of."; 1891 } 1892 leaf node-ref { 1893 type leafref { 1894 path "/nd-s:networks/nd-s:network/nd-s:node/nd-s:node-id"; 1895 require-instance false; 1896 } 1897 description 1898 "References the underlay node itself."; 1899 } 1900 } 1901 } 1902 } 1903 } 1904 } 1905 1907 B.2. YANG Data Model for Network Topology State 1909 NOTE TO RFC EDITOR: Please change the date in the file name after the 1910 CODE BEGINS statement to the date of the publication when published. 1912 file "ietf-network-topology-state@2017-09-19.yang" 1913 module ietf-network-topology-state { 1914 yang-version 1.1; 1915 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology-state"; 1916 prefix lnk-s; 1918 import ietf-network-state { 1919 prefix nd-s; 1920 reference 1921 "draft-ietf-i2rs-yang-network-topo-16 1922 NOTE TO RFC EDITOR: Please replace above reference to 1923 draft-ietf-i2rs-yang-network-topo-16 with RFC 1924 number when published (i.e. RFC xxxx)."; 1925 } 1926 import ietf-network-topology { 1927 prefix lnk; 1928 reference 1929 "draft-ietf-i2rs-yang-network-topo-16 1930 NOTE TO RFC EDITOR: Please replace above reference to 1931 draft-ietf-i2rs-yang-network-topo-16 with RFC 1932 number when published (i.e. RFC xxxx)."; 1933 } 1934 organization 1935 "IETF I2RS (Interface to the Routing System) Working Group"; 1937 contact 1938 "WG Web: 1939 WG List: 1941 Editor: Alexander Clemm 1942 1944 Editor: Jan Medved 1945 1947 Editor: Robert Varga 1948 1950 Editor: Nitin Bahadur 1951 1953 Editor: Hariharan Ananthakrishnan 1954 1956 Editor: Xufeng Liu 1957 "; 1959 description 1960 "This module defines a common base data model for network 1961 topology state, representing topology that is either learned, 1962 or topology that results from applying topology that has been 1963 configured per the ietf-network-topology data model, mirroring 1964 the corresponding data nodes in this data model. It augments 1965 the base network state data model with links to connect nodes, 1966 as well as termination points to terminate links on nodes. 1968 The data model mirrors ietf-network-topology, but contains only 1969 read-only state data. The data model is not needed when the 1970 underlying implementation infrastructure supports the Network 1971 Management Datastore Architecture (NMDA). 1973 Copyright (c) 2017 IETF Trust and the persons identified as 1974 authors of the code. All rights reserved. 1976 Redistribution and use in source and binary forms, with or 1977 without modification, is permitted pursuant to, and subject 1978 to the license terms contained in, the Simplified BSD License 1979 set forth in Section 4.c of the IETF Trust's Legal Provisions 1980 Relating to IETF Documents 1981 (http://trustee.ietf.org/license-info). 1982 This version of this YANG module is part of 1983 draft-ietf-i2rs-yang-network-topo-16; 1984 see the RFC itself for full legal notices. 1986 NOTE TO RFC EDITOR: Please replace above reference to 1987 draft-ietf-i2rs-yang-network-topo-16 with RFC 1988 number when published (i.e. RFC xxxx)."; 1990 revision 2017-09-19 { 1991 description 1992 "Initial revision. 1993 NOTE TO RFC EDITOR: 1994 (1) Please replace the following reference 1995 to draft-ietf-i2rs-yang-network-topo-16 with 1996 RFC number when published (i.e. RFC xxxx). 1997 (2) Please replace the date in the revision statement with the 1998 date of publication when published."; 1999 reference 2000 "draft-ietf-i2rs-yang-network-topo-16"; 2001 } 2003 grouping link-ref { 2004 description 2005 "References a link in a specific network."; 2006 leaf link-ref { 2007 type leafref { 2008 path "/nd-s:networks/nd-s:network[nd-s:network-id=current()"+ 2009 "/../network-ref]/lnk-s:link/lnk-s:link-id"; 2010 require-instance false; 2011 } 2012 description 2013 "A type for an absolute reference a link instance. 2014 (This type should not be used for relative references. 2015 In such a case, a relative path should be used instead.)"; 2016 } 2017 uses nd-s:network-ref; 2018 } 2020 grouping tp-ref { 2021 description 2022 "References a termination point in a specific node."; 2023 leaf tp-ref { 2024 type leafref { 2025 path "/nd-s:networks/nd-s:network[nd-s:network-id=current()"+ 2026 "/../network-ref]/nd-s:node[nd-s:node-id=current()/../"+ 2027 "node-ref]/lnk-s:termination-point/lnk-s:tp-id"; 2028 require-instance false; 2029 } 2030 description 2031 "A type for an absolute reference to a termination point. 2032 (This type should not be used for relative references. 2033 In such a case, a relative path should be used instead.)"; 2034 } 2035 uses nd-s:node-ref; 2036 } 2038 augment "/nd-s:networks/nd-s:network" { 2039 description 2040 "Add links to the network data model."; 2041 list link { 2042 key "link-id"; 2043 description 2044 "A network link connects a local (source) node and 2045 a remote (destination) node via a set of 2046 the respective node's termination points. 2047 It is possible to have several links between the same 2048 source and destination nodes. Likewise, a link could 2049 potentially be re-homed between termination points. 2050 Therefore, in order to ensure that we would always know 2051 to distinguish between links, every link is identified by 2052 a dedicated link identifier. Note that a link models a 2053 point-to-point link, not a multipoint link."; 2054 container source { 2055 description 2056 "This container holds the logical source of a particular 2057 link."; 2058 leaf source-node { 2059 type leafref { 2060 path "../../../nd-s:node/nd-s:node-id"; 2061 require-instance false; 2062 } 2063 description 2064 "Source node identifier, must be in same topology."; 2065 } 2066 leaf source-tp { 2067 type leafref { 2068 path "../../../nd-s:node[nd-s:node-id=current()/../"+ 2069 "source-node]/termination-point/tp-id"; 2070 require-instance false; 2071 } 2072 description 2073 "Termination point within source node that terminates 2074 the link."; 2075 } 2076 } 2077 container destination { 2078 description 2079 "This container holds the logical destination of a 2080 particular link."; 2081 leaf dest-node { 2082 type leafref { 2083 path "../../../nd-s:node/nd-s:node-id"; 2084 require-instance false; 2085 } 2086 description 2087 "Destination node identifier, must be in the same 2088 network."; 2089 } 2090 leaf dest-tp { 2091 type leafref { 2092 path "../../../nd-s:node[nd-s:node-id=current()/../"+ 2093 "dest-node]/termination-point/tp-id"; 2094 require-instance false; 2095 } 2096 description 2097 "Termination point within destination node that 2098 terminates the link."; 2099 } 2100 } 2101 leaf link-id { 2102 type lnk:link-id; 2103 description 2104 "The identifier of a link in the topology. 2105 A link is specific to a topology to which it belongs."; 2106 } 2107 list supporting-link { 2108 key "network-ref link-ref"; 2109 description 2110 "Identifies the link, or links, that this link 2111 is dependent on."; 2112 leaf network-ref { 2113 type leafref { 2114 path "../../../nd-s:supporting-network/nd-s:network-ref"; 2115 require-instance false; 2116 } 2117 description 2118 "This leaf identifies in which underlay topology 2119 the supporting link is present."; 2120 } 2121 leaf link-ref { 2122 type leafref { 2123 path "/nd-s:networks/nd-s:network[nd-s:network-id="+ 2124 "current()/../network-ref]/link/link-id"; 2125 require-instance false; 2127 } 2128 description 2129 "This leaf identifies a link which is a part 2130 of this link's underlay. Reference loops in which 2131 a link identifies itself as its underlay, either 2132 directly or transitively, are not allowed."; 2133 } 2134 } 2135 } 2136 } 2137 augment "/nd-s:networks/nd-s:network/nd-s:node" { 2138 description 2139 "Augment termination points which terminate links. 2140 Termination points can ultimately be mapped to interfaces."; 2141 list termination-point { 2142 key "tp-id"; 2143 description 2144 "A termination point can terminate a link. 2145 Depending on the type of topology, a termination point 2146 could, for example, refer to a port or an interface."; 2147 leaf tp-id { 2148 type lnk:tp-id; 2149 description 2150 "Termination point identifier."; 2151 } 2152 list supporting-termination-point { 2153 key "network-ref node-ref tp-ref"; 2154 description 2155 "This list identifies any termination points that 2156 the termination point is dependent on, or maps onto. 2157 Those termination points will themselves be contained 2158 in a supporting node. 2159 This dependency information can be inferred from 2160 the dependencies between links. For this reason, 2161 this item is not separately configurable. Hence no 2162 corresponding constraint needs to be articulated. 2163 The corresponding information is simply provided by the 2164 implementing system."; 2165 leaf network-ref { 2166 type leafref { 2167 path "../../../nd-s:supporting-node/nd-s:network-ref"; 2168 require-instance false; 2169 } 2170 description 2171 "This leaf identifies in which topology the 2172 supporting termination point is present."; 2173 } 2174 leaf node-ref { 2175 type leafref { 2176 path "../../../nd-s:supporting-node/nd-s:node-ref"; 2177 require-instance false; 2178 } 2179 description 2180 "This leaf identifies in which node the supporting 2181 termination point is present."; 2182 } 2183 leaf tp-ref { 2184 type leafref { 2185 path "/nd-s:networks/nd-s:network[nd-s:network-id="+ 2186 "current()/../network-ref]/nd-s:node[nd-s:node-id="+ 2187 "current()/../node-ref]/termination-point/tp-id"; 2188 require-instance false; 2189 } 2190 description 2191 "Reference to the underlay node, must be in a 2192 different topology"; 2193 } 2194 } 2195 } 2196 } 2197 } 2198 2200 Authors' Addresses 2202 Alexander Clemm 2203 Huawei 2205 EMail: ludwig@clemm.org 2207 Jan Medved 2208 Cisco 2210 EMail: jmedved@cisco.com 2212 Robert Varga 2213 Pantheon Technologies SRO 2215 EMail: robert.varga@pantheon.sk 2216 Nitin Bahadur 2217 Bracket Computing 2219 EMail: nitin_bahadur@yahoo.com 2221 Hariharan Ananthakrishnan 2222 Packet Design 2224 EMail: hari@packetdesign.com 2226 Xufeng Liu 2227 Jabil 2229 EMail: Xufeng_Liu@jabil.com