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