idnits 2.17.1 draft-ietf-i2rs-yang-network-topo-00.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 337: '.... Network types SHOULD always be repr...' RFC 2119 keyword, line 855: '... The identifier SHOULD be chosen such...' RFC 2119 keyword, line 858: '...n implementation MAY choose to capture...' RFC 2119 keyword, line 869: '... The identifier SHOULD be chosen such...' RFC 2119 keyword, line 872: '...n implementation MAY choose to capture...' (2 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 315 has weird spacing: '...ork-ref lea...' == Line 319 has weird spacing: '...ork-ref lea...' == Line 398 has weird spacing: '...ce-node lea...' == Line 401 has weird spacing: '...st-node lea...' == Line 405 has weird spacing: '...ork-ref lea...' == (1 more instance...) == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 15, 2015) is 3299 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'Z' is mentioned on line 207, but not defined == Missing Reference: 'Y5' is mentioned on line 232, but not defined == Missing Reference: 'Z5' is mentioned on line 232, but not defined == Missing Reference: 'Z3' is mentioned on line 232, but not defined == Missing Reference: 'Y4' is mentioned on line 236, but not defined == Missing Reference: 'Y1' is mentioned on line 236, but not defined == Missing Reference: 'Z2' is mentioned on line 236, but not defined == Missing Reference: 'X5' is mentioned on line 245, but not defined == Missing Reference: 'D1' is mentioned on line 616, but not defined == Missing Reference: 'D2' is mentioned on line 616, but not defined == Unused Reference: 'RFC6241' is defined on line 1118, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) Summary: 4 errors (**), 0 flaws (~~), 19 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Clemm 3 Internet-Draft J. Medved 4 Intended status: Experimental R. Varga 5 Expires: October 17, 2015 T. Tkacik 6 Cisco 7 N. Bahadur 8 Bracket Computing 9 H. Ananthakrishnan 10 Packet Design 11 April 15, 2015 13 A Data Model for Network Topologies 14 draft-ietf-i2rs-yang-network-topo-00.txt 16 Abstract 18 This document defines an abstract (generic) YANG data model for 19 network/service topologies and inventories. The model serves as a 20 base model which is augmented with technology-specific details in 21 other, more specific topology and inventory models. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on October 17, 2015. 40 Copyright Notice 42 Copyright (c) 2015 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 This document may contain material from IETF Documents or IETF 56 Contributions published or made publicly available before November 57 10, 2008. The person(s) controlling the copyright in some of this 58 material may not have granted the IETF Trust the right to allow 59 modifications of such material outside the IETF Standards Process. 60 Without obtaining an adequate license from the person(s) controlling 61 the copyright in such materials, this document may not be modified 62 outside the IETF Standards Process, and derivative works of it may 63 not be created outside the IETF Standards Process, except to format 64 it for publication as an RFC or to translate it into languages other 65 than English. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 70 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 7 71 3. Model Structure Details . . . . . . . . . . . . . . . . . . . 7 72 3.1. Base Network Model . . . . . . . . . . . . . . . . . . . 7 73 3.2. Base Network Topology Model . . . . . . . . . . . . . . . 9 74 3.3. Extending the model . . . . . . . . . . . . . . . . . . . 10 75 3.4. Discussion and selected design decisions . . . . . . . . 11 76 3.4.1. Container structure . . . . . . . . . . . . . . . . . 11 77 3.4.2. Underlay hierarchies and mappings . . . . . . . . . . 12 78 3.4.3. Use of groupings . . . . . . . . . . . . . . . . . . 12 79 3.4.4. Cardinality and directionality of links . . . . . . . 12 80 3.4.5. Multihoming and link aggregation . . . . . . . . . . 13 81 3.4.6. Mapping redundancy . . . . . . . . . . . . . . . . . 13 82 3.4.7. Typing . . . . . . . . . . . . . . . . . . . . . . . 13 83 3.4.8. Representing the same device in multiple networks . . 14 84 3.5. Items for further discussion . . . . . . . . . . . . . . 15 85 4. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 15 86 4.1. Defining the Abstract Network: network.yang . . . . . . . 15 87 4.2. Creating Abstract Network Topology: network-topology.yang 19 88 5. Security Considerations . . . . . . . . . . . . . . . . . . . 24 89 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 24 90 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 24 91 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 8.1. Normative References . . . . . . . . . . . . . . . . . . 24 93 8.2. Informative References . . . . . . . . . . . . . . . . . 25 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 96 1. Introduction 98 This document introduces an abstract (base) YANG [RFC6020] [RFC6021] 99 data model to represent networks and topologies. The data model is 100 divided into two parts. The first part of the model defines a 101 network model that allows to define network hierarchies (i.e. network 102 stacks) and to maintain an inventory of nodes contained in a network. 103 The second part of the model augments the basic network model with 104 information to describe topology information. Specifically, it adds 105 the concepts of links and termination points to describe how nodes in 106 a network are connected to each other. Moreover the model introduces 107 vertical layering relationships between networks that can be 108 augmented to cover both network inventories and network/service 109 topologies. 111 The model can be augmented to describe specifics of particular types 112 of networks and topologies. For example, an augmenting model can 113 provide network node information with attributes that are specific to 114 a particular network type. Examples of augmenting models include 115 models for Layer 2 network topologies, Layer 3 network topologies, 116 such as Unicast IGP, IS-IS [RFC1195] and OSPF [RFC2328], traffic 117 engineering (TE) data [RFC3209], or any of the variety of transport 118 and service topologies. Information specific to particular network 119 types will be captured in separate, technology-specific models. 121 The basic data models introduced in this document are generic in 122 nature and can be applied to many network and service topologies and 123 inventories. The models allow applications to operate on an 124 inventory or topology of any network at a generic level, where 125 specifics of particular inventory/topology types are not required. 126 At the same time, where data specific to a network type does comes 127 into play and the model is augmented, the instantiated data still 128 adheres to the same structure and is represented in consistent 129 fashion. This also facilitates the representation of network 130 hierarchies and dependencies between different network components and 131 network types. 133 The abstract (base) network YANG module introduced in this document, 134 entitled "network.yang", contains a list of abstract network nodes 135 and defines the concept of network hierarchy (network stack). The 136 abstract network node can be augmented in inventory and topology 137 models with inventory and topology specific attributes. Network 138 hierarchy (stack) allows any given network to have one or more 139 "supporting networks". The relationship of the base network model, 140 the inventory models and the topology models is shown in the 141 following figure (dotted lines in the figure denote possible 142 augmentations to models defined in this document). 144 +------------------------+ 145 | | 146 | Abstract Network Model | 147 | | 148 +------------------------+ 149 | 150 +-------+-------+ 151 | | 152 V V 153 +------------+ .............. 154 | Abstract | : Inventory : 155 | Topology | : Model(s) : 156 | Model | : : 157 +------------+ '''''''''''''' 158 | 159 +-------------+-------------+-------------+ 160 | | | | 161 V V V V 162 ............ ............ ............ ............ 163 : L1 : : L2 : : L3 : : Service : 164 : Topology : : Topology : : Topology : : Topology : 165 : Model : : Model : : Model : : Model : 166 '''''''''''' '''''''''''' '''''''''''' '''''''''''' 168 Figure 1: The network model structure 170 The network-topology YANG module introduced in this document, 171 entitled "network-topology.yang", defines a generic topology model at 172 its most general level of abstraction. The module defines a topology 173 graph and components from which it is composed: nodes, edges and 174 termination points. Nodes (from the network.yang module) represent 175 graph vertices and links represent graph edges. Nodes also contain 176 termination points that anchor the links. A network can contain 177 multiple topologies, for example topologies at different layers and 178 overlay topologies. The model therefore allows to capture 179 relationships between topologies, as well as dependencies between 180 nodes and termination points across topologies. An example of a 181 topology stack is shown in the following figure. 183 +---------------------------------------+ 184 / _[X1]_ "Service" / 185 / _/ : \_ / 186 / _/ : \_ / 187 / _/ : \_ / 188 / / : \ / 189 / [X2]__________________[X3] / 190 +---------:--------------:------:-------+ 191 : : : 192 +----:--------------:----:--------------+ 193 / : : : "L3" / 194 / : : : / 195 / : : : / 196 / [Y1]_____________[Y2] / 197 / * * * / 198 / * * * / 199 +--------------*-------------*--*-------+ 200 * * * 201 +--------*----------*----*--------------+ 202 / [Z1]_______________[Z1] "Optical" / 203 / \_ * _/ / 204 / \_ * _/ / 205 / \_ * _/ / 206 / \ * / / 207 / [Z] / 208 +---------------------------------------+ 210 Figure 2: Topology hierarchy (stack) example 212 The figure shows three topology levels. At top, the "Service" 213 topology shows relationships between service entities, such as 214 service functions in a service chain. The "L3" topology shows 215 network elements at Layer 3 (IP) and the "Optical" topology shows 216 network elements at Layer 1. Service functions in the "Service" 217 topology are mapped onto network elements in the "L3" topology, which 218 in turn are mapped onto network elements in the "Optical" topology. 219 The figure shows two Service Functions - X1 and X2 - mapping onto a 220 single L3 network element; this could happen, for example, if two 221 service functions reside in the same VM (or server) and share the 222 same set of network interfaces. The figure shows a single "L3" 223 network element mapped onto multiple "Optical" network elements. 224 This could happen, for example, if a single IP router attaches to 225 multiple ROADMs in the optical domain. 227 Another example of a service topology stack is shown in the following 228 figure. 230 VPN1 VPN2 231 +---------------------+ +---------------------+ 232 / [Y5]... / / [Z5]______[Z3] / 233 / / \ : / / : \_ / : / 234 / / \ : / / : \_ / : / 235 / / \ : / / : \ / : / 236 / [Y4]____[Y1] : / / : [Z2] : / 237 +------:-------:---:--+ +---:---------:-----:-+ 238 : : : : : : 239 : : : : : : 240 : +-------:---:-----:------------:-----:-----+ 241 : / [X1]__:___:___________[X2] : / 242 :/ / \_ : : _____/ / : / 243 : / \_ : _____/ / : / 244 /: / \: / / : / 245 / : / [X5] / : / 246 / : / __/ \__ / : / 247 / : / ___/ \__ / : / 248 / : / ___/ \ / : / 249 / [X4]__________________[X3]..: / 250 +------------------------------------------+ 251 L3 Topology 253 Figure 3: Topology hierarchy (stack) example 255 The figure shows two VPN service topologies (VPN1 and VPN2) 256 instantiated over a common L3 topology. Each VPN service topology is 257 mapped onto a subset of nodes from the common L3 topology. 259 There are multiple applications for such a data model. For example, 260 within the context of I2RS, nodes within the network can use the data 261 model to capture their understanding of the overall network topology 262 and expose it to a network controller. A network controller can then 263 use the instantiated topology data to compare and reconcile its own 264 view of the network topology with that of the network elements that 265 it controls. Alternatively, nodes within the network could propagate 266 this understanding to compare and reconcile this understanding either 267 among themselves or with help of a controller. Beyond the network 268 element and the immediate context of I2RS itself, a network 269 controller might even use the data model to represent its view of the 270 topology that it controls and expose it to applications north of 271 itself. Further use cases that the data model can be applied to are 272 described in [topology-use-cases]. 274 2. Definitions and Acronyms 276 Datastore: A conceptual store of instantiated management information, 277 with individual data items represented by data nodes which are 278 arranged in hierarchical manner. 280 Data subtree: An instantiated data node and the data nodes that are 281 hierarchically contained within it. 283 HTTP: Hyper-Text Transfer Protocol 285 IGP: Interior Gateway Protocol 287 IS-IS: Intermediate System to Intermediate System protocol 289 NETCONF: Network Configuration Protocol 291 OSPF: Open Shortest Path First, a link state routing protocol 293 URI: Uniform Resource Identifier 295 ReST: Representational State Transfer, a style of stateless interface 296 and protocol that is generally carried over HTTP 298 YANG: A data definition language for NETCONF 300 3. Model Structure Details 302 3.1. Base Network Model 304 The abstract (base) network model is defined in the network.yang 305 module. Its structure is shown in the following figure. Brackets 306 enclose list keys, "rw" means configuration data, "ro" means 307 operational state data, and "?" designates optional nodes. 309 module: ietf-network 310 +--rw network* [network-id] 311 +--rw network-types 312 +--rw network-id network-id 313 +--ro server-provided? boolean 314 +--rw supporting-network* [network-ref] 315 | +--rw network-ref leafref 316 +--rw node* [node-id] 317 +--rw node-id node-id 318 +--rw supporting-node* [network-ref node-ref] 319 +--rw network-ref leafref 320 +--rw node-ref leafref 322 Figure 4: The structure of the abstract (base) network model 324 The model contains a list of networks, contained underneath a root 325 container for this module, "network". Each network is captured in 326 its own list entry, distinguished via a network-id. 328 A network has a certain type, such as L2, L3, OSPF or IS-IS. A 329 network can even have multiple types simultaneously. The type, or 330 types, are captured underneath the container "network-types". In 331 this module it serves merely as an augmentation target; network- 332 specific modules will later introduce new data nodes to represent new 333 network types below this target, i.e. insert them below "network- 334 types" by ways of yang augmentation. 336 When a network is of a certain type, it will contain a corresponding 337 data node. Network types SHOULD always be represented using presence 338 containers, not leafs of empty type. This allows to represent 339 hierarchies of network subtypes within the instance information. For 340 example, an instance of an OSPF network (which, at the same time, is 341 a layer 3 unicast IGP network) would contain underneath "network- 342 types" another container "l3-unicast-igp-network", which in turn 343 would contain a container "ospf-network". 345 A network can in turn be part of a hierarchy of networks, building on 346 top of other networks. Any such networks are captured in the list 347 "supporting-network". A supporting network is in effect an underlay 348 network. 350 Furthermore, a network contains an inventory of nodes that are part 351 of the network. The nodes of a network are captured in their own 352 list. Each node is identified relative to its containing network by 353 a node-id. 355 It should be noted that a node does not exist independently of a 356 network; instead it is a part of the network that it is contained in. 358 In cases where the same entity takes part in multiple networks, or at 359 multiple layers of a networking stack, the same entity will be 360 represented by multiple nodes, one for each network. In other words, 361 the node represents an abstraction of the device for the particular 362 network that it a is part of. To represent that the same entity or 363 same device is part of multiple topologies or networks, it is 364 possible to create one "physical" network with a list of nodes for 365 each of the devices or entities. This (physical) network, 366 respectively the (entities) nodes in that network, can then be 367 referred to as underlay network and nodes from the other (logical) 368 networks and nodes, respectively. Note that the model allows to 369 define more than one underlay network (and node), allowing for 370 simultaneous representation of layered network- and service 371 topologies and physical instantiation. 373 Similar to a network, a node can be supported by other nodes, and map 374 onto one or more other nodes in an underlay network. This is 375 captured in the list "supporting-node". The resulting hierarchy of 376 nodes allows also to represent device stacks, where a node at one 377 level is supported by a set of nodes at an underlying level. For 378 example, a "router" node might be supported by a node representing a 379 route processor and separate nodes for various line cards and service 380 modules, a virtual router might be supported or hosted on a physical 381 device represented by a separate node, and so on. 383 3.2. Base Network Topology Model 385 The abstract (base) network topology model is defined in the 386 "network-topology.yang" module. It builds on the network model 387 defined in the "network.yang" module, augmenting it with links 388 (defining how nodes are connected) and termination-points (which 389 anchor the links and are contained in nodes). The structure of the 390 network topology module is shown in the following figure. Brackets 391 enclose list keys, "rw" means configuration data, "ro" means 392 operational state data, and "?" designates optional nodes. 394 module: ietf-network-topology 395 augment /nd:network: 396 +--rw link* [link-id] 397 +--rw source 398 | +--rw source-node leafref 399 | +--rw source-tp? leafref 400 +--rw destination 401 | +--rw dest-node leafref 402 | +--rw dest-tp? leafref 403 +--rw link-id link-id 404 +--rw supporting-link* [network-ref link-ref] 405 +--rw network-ref leafref 406 +--rw link-ref leafref 407 augment /nd:network/nd:node: 408 +--rw termination-point* [tp-id] 409 +--rw tp-id tp-id 410 +--rw supporting-termination-point* [network-ref node-ref tp-ref] 411 +--rw network-ref leafref 412 +--rw node-ref leafref 413 +--rw tp-ref leafref 415 Figure 5: The structure of the abstract (base) network topology model 417 A node has a list of termination points that are used to terminate 418 links. An example of a termination point might be a physical or 419 logical port or, more generally, an interface. 421 Like a node, a termination point can in turn be supported by an 422 underlying termination point, contained in the supporting node of the 423 underlay network. 425 A link is identified by a link-id that uniquely identifies the link 426 within a given topology. Links are point-to-point and 427 unidirectional. Accordingly, a link contains a source and a 428 destination. Both source and destination reference a corresponding 429 node, as well as a termination point on that node. Similar to a 430 node, a link can map onto one or more links in an underlay topology 431 (which are terminated by the corresponding underlay termination 432 points). This is captured in the list "supporting-link". 434 3.3. Extending the model 436 In order to derive a model for a specific type of network, the base 437 model can be extended. This can be done roughly as follows: for the 438 new network type, a new YANG module is introduced. In this module a 439 number of augmentations are defined against the network and network- 440 topology YANG modules. 442 We start with augmentations against the network.yang module. First, 443 a new network type needs to be defined. For this, a presence 444 container that resembles the new network type is defined. It is 445 inserted by means of augmentation below the network-types container. 446 Subsequently, data nodes for any network-type specific node 447 parameters are defined and augmented into the node list. The new 448 data nodes can be defined as conditional ("when") on the presence of 449 the corresponding network type in the containing network. In cases 450 where there are any requirements or restrictions in terms of network 451 hierarchies, such as when a network of a new network-type requires a 452 specific type of underlay network, it is possible to define 453 corresponding constraints as well and augment the supporting-network 454 list accordingly. However, care should be taken to avoid excessive 455 definitions of constraints. 457 Subsequently, augmentations are defined against network- 458 topology.yang. Data nodes are defined both for link parameters, as 459 well as termination point parameters, that are specific to the new 460 network type. Those data nodes are inserted by way of augmentation 461 into the link and termination-point lists, respectively. Again, data 462 nodes can be defined as conditional on the presence of the 463 corresponding network-type in the containing network, by adding a 464 corresponding "when"-statement. 466 It is possible, but not required, to group data nodes for a given 467 network-type under a dedicated container. Doing so introduces 468 further structure, but lengthens data node path names. 470 In cases where a hierarchy of network types is defined, augmentations 471 can in turn against augmenting modules, with the module of a network 472 "sub-type" augmenting the module of a network "super-type". 474 3.4. Discussion and selected design decisions 476 3.4.1. Container structure 478 Rather than maintaining lists in separate containers, the model is 479 kept relatively flat in terms of its containment structure. Lists of 480 nodes, links, termination-points, and supporting-nodes, supporting- 481 links, and supporting-termination-points are not kept in separate 482 containers. Therefore, path specifiers used to refer to specific 483 nodes, be it in management operations or in specifications of 484 constraints, can remain relatively compact. Of course, this means 485 there is no separate structure in instance information that separates 486 elements of different lists from one another. Such structure is 487 semantically not required, although it might enhance human 488 readability in some cases. 490 3.4.2. Underlay hierarchies and mappings 492 To minimize assumptions of what a particular entity might actually 493 represent, mappings between networks, nodes, links, and termination 494 points are kept strictly generic. For example, no assumptions are 495 made whether a termination point actually refers to an interface, or 496 whether a node refers to a specific "system" or device; the model at 497 this generic level makes no provisions for that. 499 Where additional specifics about mappings between upper and lower 500 layers are required, those can be captured in augmenting modules. 501 For example, to express that a termination point in a particular 502 network type maps to an interface, an augmenting module can introduce 503 an augmentation to the termination point which introduces a leaf of 504 type ifref that references the corresponding interface [RFC7223]. 505 Similarly, if a node maps to a particular device or network element, 506 an augmenting module can augment the node data with a leaf that 507 references the network element. 509 It is possible for links at one level of a hierarchy to map to 510 multiple links at another level of the hierarchy. For example, a VPN 511 topology might model VPN tunnels as links. Where a VPN tunnel maps 512 to a path that is composed of a chain of several links, the link will 513 contain a list of those supporting links. Likewise, it is possible 514 for a link at one level of a hierarchy to aggregate a bundle of links 515 at another level of the hierarchy. 517 3.4.3. Use of groupings 519 The model makes use of groupings, instead of simply defining data 520 nodes "in-line". This allows to more easily include the 521 corresponding data nodes in notifications, which then do not need to 522 respecify each data node that is to be included. The tradeoff for 523 this is that it makes the specification of constraints more complex, 524 because constraints involving data nodes outside the grouping need to 525 be specified in conjunction with a "uses" statement where the 526 grouping is applied. This also means that constraints and XPath- 527 statements need to specified in such a way that they navigate "down" 528 first and select entire sets of nodes, as opposed to being able to 529 simply specify them against individual data nodes. 531 3.4.4. Cardinality and directionality of links 533 The topology model includes links that are point-to-point and 534 unidirectional. It does not directly support multipoint and 535 bidirectional links. While this may appear as a limitation, it does 536 keep the model simple, generic, and allows it to very easily be 537 subjected to applications that make use of graph algorithms. Bi- 538 directional connections can be represented through pairs of 539 unidirectional links. Multipoint networks can be represented through 540 pseudo-nodes (similar to IS-IS, for example). By introducing 541 hierarchies of nodes, with nodes at one level mapping onto a set of 542 other nodes at another level, and introducing new links for nodes at 543 that level, topologies with connections representing non-point-to- 544 point communication patterns can be represented. 546 3.4.5. Multihoming and link aggregation 548 Links are terminated by a single termination point, not sets of 549 termination points. Connections involving multihoming or link 550 aggregation schemes need to be represented using multiple point-to- 551 point links, then defining a link at a higher layer that is supported 552 by those individual links. 554 3.4.6. Mapping redundancy 556 In a hierarchy of networks, there are nodes mapping to nodes, links 557 mapping to links, and termination points mapping to termination 558 points. Some of this information is redundant. Specifically, if the 559 link-to-links mapping known, and the termination points of each link 560 known, termination point mapping information can be derived via 561 transitive closure and does not have to be explicitly configured. 562 Nonetheless, in order to not constrain applications regarding which 563 mappings they want to configure and which should be derived, the 564 model does provide for the option to configure this information 565 explicitly. The model includes integrity constraints to allow for 566 validating for consistency. 568 3.4.7. Typing 570 A network's network types are represented using a container which 571 contains a data node for each of its network types. A network can 572 encompass several types of network simultaneously, hence a container 573 is used instead of a case construct, with each network type in turn 574 represented by a dedicated presence container itself. The reason for 575 not simply using an empty leaf, or even simpler, do away even with 576 the network container and just use a leaf-list of network-type 577 instead, is to be able to represent "class hierarchies" of network 578 types, with one network type refining the other. Network-type 579 specific containers are to be defined in the network-specific 580 modules, augmenting the network-types container. 582 3.4.8. Representing the same device in multiple networks 584 One common requirement concerns the ability to represent that the 585 same device can be part of multiple networks and topologies. 586 However, the model defines a node as relative to the network that it 587 is contained in. The same node cannot be part of multiple 588 topologies. In many cases, a node will be the abstraction of a 589 particular device in a network. To reflect that the same device is 590 part of multiple topologies, the following approach might be chosen: 591 A new type of network to represent a "physical" (or "device") network 592 is introduced, with nodes representing devices. This network forms 593 an underlay network for logical networks above it, with nodes of the 594 logical network mapping onto nodes in the physical network. 596 This scenario is depicted in the following figure. It depicts three 597 networks with two nodes each. A physical network P consists of an 598 inventory of two nodes, D1 and D2, each representing a device. A 599 second network, X, has a third network, Y, as its underlay. Both X 600 and Y also have the physical network P as underlay. X1 has both Y1 601 and D1 as underlay nodes, while Y1 has D1 as underlay node. 602 Likewise, X2 has both Y2 and D2 as underlay nodes, while Y2 has D2 as 603 underlay node. The fact that X1 and Y1 are both instantiated on the 604 same physical node D1 can be easily derived. 606 +---------------------+ 607 / [X1]____[X2] / X(Service Overlay) 608 +----:--:----:--------+ 609 ..: :..: : 610 ........: ....: : :.... 611 +-----:-------------:--+ : :... 612 / [Y1]____[Y2]....: / :.. : 613 +------|-------|-------+ :.. :... 614 Y(L3) | +---------------------:-----+ : 615 | +----:----|-:----------+ 616 +------------------------/---[D1] [D2] / 617 +----------------------+ 618 P (Physical network) 620 Figure 6: Topology hierarchy example - multiple underlays 622 In the case of a physical network, nodes represent physical devices 623 and termination points physical ports. It should be noted that it is 624 also conceivable to augment the model for a physical network-type, 625 defining augmentations that have nodes reference system information 626 and termination points reference physical interfaces, in order to 627 provide a bridge between network and device models. 629 3.5. Items for further discussion 631 YANG requires data needs to be designated as either configuration or 632 operational data, but not both, yet it is important to have all 633 network information, including vertical cross-network dependencies, 634 captured in one coherent model. In most cases network topology 635 information is discovered about a network; the topology is considered 636 a property of the network that is reflected in the model. That said, 637 it is conceivable that certain types of topology need to also be 638 configurable by an application. 640 There are several alternatives in which this can be addressed. The 641 alternative chosen in this draft does not restrict network topology 642 information as read-only, but includes a flag that indicates for each 643 network whether it should be considered as read-only or configurable 644 by applications. 646 An alternative would be to designate network list elements as read 647 only. The read-only network list includes each network; it is the 648 complete reference. In parallel a second network list is introduced. 649 This list serves the purpose of being able to configure networks 650 which are then mirrored in the read-only list. The configurable 651 network list adheres to the same structure and uses the same 652 groupings as its read-only counterpart. As most data is defined in 653 those groupings, the amount of additional definitions required will 654 be limited. A configurable network will thus be represented twice: 655 once in the read-only list of all networks, a second time in a 656 configuration sandbox. 658 Similar considerations apply to scenarios in which data is subject to 659 configuration, but implementations want to be smart enough require 660 only some mapping information, such as which link is supported by 661 which other links, while automatically deriving other mapping 662 information where possible, such as which termination points are 663 supported by which underlay termination points. To accommodate such 664 cases, separate provision may again be made by including another 665 "server-provided" option. 667 4. YANG Modules 669 4.1. Defining the Abstract Network: network.yang 671 672 file "ietf-network@2015-04-15.yang" 673 module ietf-network { 674 yang-version 1; 675 namespace "urn:ietf:params:xml:ns:yang:ietf-network"; 676 prefix nd; 677 import ietf-inet-types { 678 prefix inet; 679 } 681 organization "TBD"; 682 contact 683 "WILL-BE-DEFINED-LATER"; 684 description 685 "This module defines a common base model for a collection 686 of nodes in a network. Node definitions s are further used 687 in network topologies and inventories."; 689 revision 2015-04-15 { 690 description 691 "Initial revision."; 692 reference "draft-ietf-i2rs-yang-network-topo-00"; 693 } 695 typedef node-id { 696 type inet:uri; 697 description 698 "Identifier for a node."; 699 } 701 typedef network-id { 702 type inet:uri; 703 description 704 "Identifier for a network."; 705 } 707 grouping network-ref { 708 description 709 "Contains the information necessary to reference a network, 710 for example an underlay network."; 711 leaf network-ref { 712 type leafref { 713 path "/network/network-id"; 714 } 715 description 716 "Used to reference a network, for example an underlay 717 network."; 718 } 719 } 721 grouping node-ref { 722 description 723 "Contains the information necessary to reference a node."; 724 leaf node-ref { 725 type leafref { 726 path "/network[network-id=current()/../network-ref]"+ 727 "/node/node-id"; 728 } 729 description 730 "Used to reference a node. 731 Nodes are identified relative to the network they are 732 contained in."; 733 } 734 uses network-ref; 735 } 737 list network { 738 key "network-id"; 739 description 740 "Describes a network. 741 A network typically contains an inventory of nodes, 742 topological information (augmented through 743 network-topology model), as well as layering 744 information."; 745 container network-types { 746 description 747 "Serves as an augmentation target. 748 The network type is indicated through corresponding 749 presence containers augmented into this container."; 750 } 751 leaf network-id { 752 type network-id; 753 description 754 "Identifies a network."; 755 } 756 leaf server-provided { 757 type boolean; 758 config false; 759 description 760 "Indicates whether the information concerning this 761 particular network is populated by the server 762 (server-provided true, the general case for network 763 information discovered from the server), 764 or whether it is configured by a client 765 (server-provided true, possible e.g. for 766 service overlays managed through a controller)."; 767 } 768 list supporting-network { 769 key "network-ref"; 770 description 771 "An underlay network, used to represent layered network 772 topologies."; 774 leaf network-ref { 775 type leafref { 776 path "/network/network-id"; 777 } 778 description 779 "References the underlay network."; 780 } 781 } 782 list node { 783 key "node-id"; 784 description 785 "The inventory of nodes of this network."; 786 leaf node-id { 787 type node-id; 788 description 789 "Identifies a node uniquely within the containing 790 network."; 791 } 792 list supporting-node { 793 key "network-ref node-ref"; 794 description 795 "Represents another node, in an underlay network, that 796 this node is supported by. Used to represent layering 797 structure."; 798 leaf network-ref { 799 type leafref { 800 path "../../../supporting-network/network-ref"; 801 } 802 description 803 "References the underlay network that the 804 underlay node is part of."; 805 } 806 leaf node-ref { 807 type leafref { 808 path "/network/node/node-id"; 809 } 810 description 811 "References the underlay node itself."; 812 } 813 } 814 } 815 } 816 } 818 820 4.2. Creating Abstract Network Topology: network-topology.yang 822 823 file "ietf-network-topology@2015-04-15.yang" 824 module ietf-network-topology { 825 yang-version 1; 826 namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology"; 827 prefix lnk; 829 import ietf-inet-types { 830 prefix inet; 831 } 832 import ietf-network { 833 prefix nd; 834 } 836 organization "TBD"; 837 contact 838 "WILL-BE-DEFINED-LATER"; 839 description 840 "This module defines a common base model for network topology, 841 augmenting the base network model with links to connect nodes, 842 as well as termination points to terminate links on nodes."; 844 revision 2015-04-15 { 845 description 846 "Initial revision."; 847 reference "draft-ietf-i2rs-yang-network-topo-00"; 848 } 850 typedef link-id { 851 type inet:uri; 852 description 853 "An identifier for a link in a topology. 854 The identifier may be opaque. 855 The identifier SHOULD be chosen such that the same link in a 856 real network topology will always be identified through the 857 same identifier, even if the model is instantiated in separate 858 datastores. An implementation MAY choose to capture semantics 859 in the identifier, for example to indicate the type of link 860 and/or the type of topology that the link is a part of."; 861 } 863 typedef tp-id { 864 type inet:uri; 865 description 866 "An identifier for termination points on a node. 867 The identifier may be opaque. 869 The identifier SHOULD be chosen such that the same TP in a 870 real network topology will always be identified through the 871 same identifier, even if the model is instantiated in separate 872 datastores. An implementation MAY choose to capture semantics 873 in the identifier, for example to indicate the type of TP 874 and/or the type of node and topology that the TP is a part 875 of."; 876 } 878 grouping link-ref { 879 description 880 "References a link in a specific network."; 881 leaf link-ref { 882 type leafref { 883 path "/nd:network[nd:network-id=current()/../"+ 884 "nd:network-ref]/link/link-id"; 885 } 886 description 887 "A type for an absolute reference a link instance. 888 (This type should not be used for relative references. 889 In such a case, a relative path should be used instead.)"; 890 } 891 uses nd:network-ref; 892 } 894 grouping tp-ref { 895 description 896 "References a termination point in a specific node."; 897 leaf tp-ref { 898 type leafref { 899 path "/nd:network[nd:network-id=current()/../"+ 900 "nd:network-ref]/nd:node[nd:node-id=current()/../"+ 901 "nd:node-ref]/termination-point/tp-id"; 902 } 903 description 904 "A type for an absolute reference to a termination point. 905 (This type should not be used for relative references. 906 In such a case, a relative path should be used instead.)"; 907 } 908 uses nd:node-ref; 909 } 911 augment "/nd:network" { 912 description 913 "Add links to the network model."; 914 list link { 915 key "link-id"; 916 description 917 "A Network Link connects a by Local (Source) node and 918 a Remote (Destination) Network Nodes via a set of the 919 nodes' termination points. 920 As it is possible to have several links between the same 921 source and destination nodes, and as a link could 922 potentially be re-homed between termination points, to 923 ensure that we would always know to distinguish between 924 links, every link is identified by a dedicated link 925 identifier. 926 Note that a link models a point-to-point link, not a 927 multipoint link. 928 Layering dependencies on links in underlay topologies are 929 not represented as the layering information of nodes and of 930 termination points is sufficient."; 931 container source { 932 description 933 "This container holds the logical source of a particular 934 link."; 935 leaf source-node { 936 type leafref { 937 path "../../../nd:node/nd:node-id"; 938 } 939 mandatory true; 940 description 941 "Source node identifier, must be in same topology."; 942 } 943 leaf source-tp { 944 type leafref { 945 path "../../../nd:node[nd:node-id=current()/../"+ 946 "source-node]/termination-point/tp-id"; 947 } 948 description 949 "Termination point within source node that terminates 950 the link."; 951 } 952 } 953 container destination { 954 description 955 "This container holds the logical destination of a 956 particular link."; 957 leaf dest-node { 958 type leafref { 959 path "../../../nd:node/nd:node-id"; 960 } 961 mandatory true; 962 description 963 "Destination node identifier, must be in the same 964 network."; 966 } 967 leaf dest-tp { 968 type leafref { 969 path "../../../nd:node[nd:node-id=current()/../"+ 970 "dest-node]/termination-point/tp-id"; 971 } 972 description 973 "Termination point within destination node that 974 terminates the link."; 975 } 976 } 977 leaf link-id { 978 type link-id; 979 description 980 "The identifier of a link in the topology. 981 A link is specific to a topology to which it belongs."; 982 } 983 list supporting-link { 984 key "network-ref link-ref"; 985 description 986 "Identifies the link, or links, that this link 987 is dependent on."; 988 leaf network-ref { 989 type leafref { 990 path "../../../nd:supporting-network/nd:network-ref"; 991 } 992 description 993 "This leaf identifies in which underlay topology 994 supporting link is present."; 995 } 996 leaf link-ref { 997 type leafref { 998 path "/nd:network[nd:network-id=current()/.."+ 999 "/network-ref]/link/link-id"; 1000 } 1001 description 1002 "This leaf identifies a link which is a part 1003 of this link's underlay. Reference loops, in which 1004 a link identifies itself as its underlay, either 1005 directly or transitively, are not allowed."; 1006 } 1007 } 1008 } 1009 } 1010 augment "/nd:network/nd:node" { 1011 description 1012 "Augment termination points which terminate links. 1013 Termination points can ultimately be mapped to interfaces."; 1015 list termination-point { 1016 key "tp-id"; 1017 description 1018 "A termination point can terminate a link. 1019 Depending on the type of topology, a termination point 1020 could, for example, refer to a port or an interface."; 1021 leaf tp-id { 1022 type tp-id; 1023 description 1024 "Termination point identifier."; 1025 } 1026 list supporting-termination-point { 1027 key "network-ref node-ref tp-ref"; 1028 description 1029 "The leaf list identifies any termination points that 1030 the termination point is dependent on, or maps onto. 1031 Those termination points will themselves be contained 1032 in a supporting node. 1033 This dependency information can be inferred from 1034 the dependencies between links. For this reason, 1035 this item is not separately configurable. Hence no 1036 corresponding constraint needs to be articulated. 1037 The corresponding information is simply provided by the 1038 implementing system."; 1039 leaf network-ref { 1040 type leafref { 1041 path "../../../nd:supporting-node/nd:network-ref"; 1042 } 1043 description 1044 "This leaf identifies in which topology the 1045 supporting termination point is present."; 1046 } 1047 leaf node-ref { 1048 type leafref { 1049 path "../../../nd:supporting-node/nd:node-ref"; 1050 } 1051 description 1052 "This leaf identifies in which node the supporting 1053 termination point is present."; 1054 } 1055 leaf tp-ref { 1056 type leafref { 1057 path "/nd:network[nd:network-id=current()/../"+ 1058 "network-ref]/nd:node[nd:node-id=current()/../"+ 1059 "node-ref]/termination-point/tp-id"; 1060 } 1061 description 1062 "Reference to the underlay node, must be in a 1063 different topology"; 1064 } 1065 } 1066 } 1067 } 1068 } 1070 1072 5. Security Considerations 1074 The transport protocol used for sending the topology data MUST 1075 support authentication and SHOULD support encryption. The data-model 1076 by itself does not create any security implications. 1078 6. Contributors 1080 The model presented in this paper was contributed to by more people 1081 than can be listed on the author list. Additional contributors 1082 include: 1084 o Ken Gray, Cisco Systems 1086 o Tom Nadeau, Brocade 1088 o Aleksandr Zhdankin, Cisco 1090 7. Acknowledgements 1092 We wish to acknowledge the helpful contributions, comments, and 1093 suggestions that were received from Alia Atlas, Vishna Pavan Beeram, 1094 Andy Bierman, Martin Bjorklund, Igor Bryskin, Benoit Claise, Susan 1095 Hares, Xufeng Liu, Ladislav Lhotka, Carlos Pignataro, Juergen 1096 Schoenwaelder, and Xian Zhang. 1098 8. References 1100 8.1. Normative References 1102 [RFC1195] Callon, R., "Use of OSI IS-IS for Routing in TCP/IP and 1103 Dual Environments", RFC 1195, December 1990. 1105 [RFC2328] Moy, J., "OSPF Version 2", RFC 2328, April 1998. 1107 [RFC3209] Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V., 1108 and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP 1109 Tunnels", RFC 3209, December 2001. 1111 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1112 Network Configuration Protocol (NETCONF)", RFC 6020, 1113 October 2010. 1115 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1116 October 2010. 1118 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1119 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1120 6241, June 2011. 1122 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1123 Management", RFC 7223, May 2014. 1125 8.2. Informative References 1127 [restconf] 1128 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1129 Protocol", I-D draft-ietf-netconf-restconf-04, January 1130 2015. 1132 [topology-use-cases] 1133 Medved, J., Previdi, S., Lopez, V., and S. Amante, 1134 "Topology API Use Cases", I-D draft-amante-i2rs-topology- 1135 use-cases-01, October 2013. 1137 [yang-json] 1138 Lhotka, L., "JSON Encoding of Data Modeled with YANG", I-D 1139 draft-ietf-netmod-yang-json-03, February 2015. 1141 Authors' Addresses 1143 Alexander Clemm 1144 Cisco 1146 EMail: alex@cisco.com 1148 Jan Medved 1149 Cisco 1151 EMail: jmedved@cisco.com 1153 Robert Varga 1154 Cisco 1156 EMail: rovarga@cisco.com 1157 Tony Tkacik 1158 Cisco 1160 EMail: ttkacik@cisco.com 1162 Nitin Bahadur 1163 Bracket Computing 1165 EMail: nitin_bahadur@yahoo.com 1167 Hariharan Ananthakrishnan 1168 Packet Design 1170 EMail: hari@packetdesign.com