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