idnits 2.17.1 draft-clemm-i2rs-yang-network-topo-04.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 808: '... The identifier SHOULD be chosen such...' RFC 2119 keyword, line 811: '...n implementation MAY choose to capture...' RFC 2119 keyword, line 821: '... The identifier SHOULD be chosen such...' RFC 2119 keyword, line 824: '...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 400 has weird spacing: '...ork-ref lea...' == Line 404 has weird spacing: '...ork-ref lea...' == Line 410 has weird spacing: '...ork-ref lea...' == (3 more instances...) == 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 (March 9, 2015) is 3308 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 625, but not defined == Missing Reference: 'D2' is mentioned on line 625, but not defined == Unused Reference: 'RFC6241' is defined on line 1064, 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: September 10, 2015 T. Tkacik 6 Cisco 7 N. Bahadur 8 Bracket Computing 9 H. Ananthakrishnan 10 Packet Design 11 March 9, 2015 13 A Data Model for Network Topologies 14 draft-clemm-i2rs-yang-network-topo-04.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 September 10, 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 . . . . . . . . . . . . . . . . . . . 11 75 3.4. Discussion and selected design decisions . . . . . . . . 11 76 3.4.1. Container structure . . . . . . . . . . . . . . . . . 12 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 . . . . . . . 13 80 3.4.5. Multihoming and link aggregation . . . . . . . . . . 13 81 3.4.6. Mapping redundancy . . . . . . . . . . . . . . . . . 13 82 3.4.7. Typing . . . . . . . . . . . . . . . . . . . . . . . 14 83 3.4.8. Representing the same device in multiple networks . . 14 84 3.5. Items for further discussion . . . . . . . . . . . . . . 15 85 4. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 16 86 4.1. Defining the Abstract Network: network.yang . . . . . . . 16 87 4.2. Creating Abstract Network Topology: network-topology.yang 18 88 5. Security Considerations . . . . . . . . . . . . . . . . . . . 23 89 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 23 90 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 91 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 92 8.1. Normative References . . . . . . . . . . . . . . . . . . 23 93 8.2. Informative References . . . . . . . . . . . . . . . . . 24 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 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: network 310 +--rw network* [network-id] 311 +--rw network-id network-id 312 +--ro server-provided? boolean 313 +--rw network-types 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: network 395 +--rw network* [network-id] 396 +--rw network-id network-id 397 +--ro server-provided? boolean 398 +--rw network-types 399 +--rw supporting-network* [network-ref] 400 | +--rw network-ref leafref 401 +--rw node* [node-id] 402 | +--rw node-id node-id 403 | +--rw supporting-node* [network-ref node-ref] 404 | | +--rw network-ref leafref 405 | | +--rw node-ref leafref 406 | +--rw lnk:termination-point* [tp-id] 407 | +--rw lnk:tp-id tp-id 408 | +--rw lnk:supporting-termination-point* 409 [network-ref node-ref tp-ref] 410 | +--rw lnk:network-ref leafref 411 | +--rw lnk:node-ref leafref 412 | +--rw lnk:tp-ref leafref 413 +--rw lnk:link* [link-id] 414 +--rw lnk:link-id link-id 415 +--rw lnk:source 416 | +--rw lnk:source-node leafref 417 | +--rw lnk:source-tp? leafref 418 +--rw lnk:destination 419 | +--rw lnk:dest-node leafref 420 | +--rw lnk:dest-tp? leafref 421 +--rw lnk:supporting-link* [network-ref link-ref] 422 +--rw lnk:network-ref leafref 423 +--rw lnk:link-ref leafref 425 Figure 5: The structure of the abstract (base) network topology model 427 A node has a list of termination points that are used to terminate 428 links. An example of a termination point might be a physical or 429 logical port or, more generally, an interface. 431 Like a node, a termination point can in turn be supported by an 432 underlying termination point, contained in the supporting node of the 433 underlay network. 435 A link is identified by a link-id that uniquely identifies the link 436 within a given topology. Links are point-to-point and 437 unidirectional. Accordingly, a link contains a source and a 438 destination. Both source and destination reference a corresponding 439 node, as well as a termination point on that node. Similar to a 440 node, a link can map onto one or more links in an underlay topology 441 (which are terminated by the corresponding underlay termination 442 points). This is captured in the list "supporting-link". 444 3.3. Extending the model 446 In order to derive a model for a specific type of network, the base 447 model can be extended. This can be done roughly as follows: for the 448 new network type, a new YANG module is introduced. In this module a 449 number of augmentations are defined against the network and network- 450 topology YANG modules. 452 We start with augmentations against the network.yang module. First, 453 a new network type needs to be defined. For this, a presence 454 container that resembles the new network type is defined. It is 455 inserted by means of augmentation below the network-types container. 456 Subsequently, data nodes for any network-type specific node 457 parameters are defined and augmented into the node list. The new 458 data nodes can be defined as conditional ("when") on the presence of 459 the corresponding network type in the containing network. In cases 460 where there are any requirements or restrictions in terms of network 461 hierarchies, such as when a network of a new network-type requires a 462 specific type of underlay network, it is possible to define 463 corresponding constraints as well and augment the supporting-network 464 list accordingly. However, care should be taken to avoid excessive 465 definitions of constraints. 467 Subsequently, augmentations are defined against network- 468 topology.yang. Data nodes are defined both for link parameters, as 469 well as termination point parameters, that are specific to the new 470 network type. Those data nodes are inserted by way of augmentation 471 into the link and termination-point lists, respectively. Again, data 472 nodes can be defined as conditional on the presence of the 473 corresponding network-type in the containing network, by adding a 474 corresponding "when"-statement. 476 It is possible, but not required, to group data nodes for a given 477 network-type under a dedicated container. Doing so introduces 478 further structure, but lengthens data node path names. 480 In cases where a hierarchy of network types is defined, augmentations 481 can in turn against augmenting modules, with the module of a network 482 "sub-type" augmenting the module of a network "super-type". 484 3.4. Discussion and selected design decisions 485 3.4.1. Container structure 487 Rather than maintaining lists in separate containers, the model is 488 kept relatively flat in terms of its containment structure. Lists of 489 nodes, links, termination-points, and supporting-nodes, supporting- 490 links, and supporting-termination-points are not kept in separate 491 containers. Therefore, path specifiers used to refer to specific 492 nodes, be it in management operations or in specifications of 493 constraints, can remain relatively compact. Of course, this means 494 there is no separate structure in instance information that separates 495 elements of different lists from one another. Such structure is 496 semantically not required, although it might enhance human 497 readability in some cases. 499 3.4.2. Underlay hierarchies and mappings 501 To minimize assumptions of what a particular entity might actually 502 represent, mappings between networks, nodes, links, and termination 503 points are kept strictly generic. For example, no assumptions are 504 made whether a termination point actually refers to an interface, or 505 whether a node refers to a specific "system" or device; the model at 506 this generic level makes no provisions for that. 508 Where additional specifics about mappings between upper and lower 509 layers are required, those can be captured in augmenting modules. 510 For example, to express that a termination point in a particular 511 network type maps to an interface, an augmenting module can introduce 512 an augmentation to the termination point which introduces a leaf of 513 type ifref that references the corresponding interface [RFC7223]. 514 Similarly, if a node maps to a particular device or network element, 515 an augmenting module can augment the node data with a leaf that 516 references the network element. 518 It is possible for links at one level of a hierarchy to map to 519 multiple links at another level of the hierarchy. For example, a VPN 520 topology might model VPN tunnels as links. Where a VPN tunnel maps 521 to a path that is composed of a chain of several links, the link will 522 contain a list of those supporting links. Likewise, it is possible 523 for a link at one level of a hierarchy to aggregate a bundle of links 524 at another level of the hierarchy. 526 3.4.3. Use of groupings 528 The model makes use of groupings, instead of simply defining data 529 nodes "in-line". This allows to more easily include the 530 corresponding data nodes in notifications, which then do not need to 531 respecify each data node that is to be included. The tradeoff for 532 this is that it makes the specification of constraints more complex, 533 because constraints involving data nodes outside the grouping need to 534 be specified in conjunction with a "uses" statement where the 535 grouping is applied. This also means that constraints and XPath- 536 statements need to specified in such a way that they navigate "down" 537 first and select entire sets of nodes, as opposed to being able to 538 simply specify them against individual data nodes. 540 3.4.4. Cardinality and directionality of links 542 The topology model includes links that are point-to-point and 543 unidirectional. It does not directly support multipoint and 544 bidirectional links. While this may appear as a limitation, it does 545 keep the model simple, generic, and allows it to very easily be 546 subjected to applications that make use of graph algorithms. Bi- 547 directional connections can be represented through pairs of 548 unidirectional links. Multipoint networks can be represented through 549 pseudo-nodes (similar to IS-IS, for example). By introducing 550 hierarchies of nodes, with nodes at one level mapping onto a set of 551 other nodes at another level, and introducing new links for nodes at 552 that level, topologies with connections representing non-point-to- 553 point communication patterns can be represented. 555 3.4.5. Multihoming and link aggregation 557 Links are terminated by a single termination point, not sets of 558 termination points. Connections involving multihoming or link 559 aggregation schemes need to be represented using multiple point-to- 560 point links, then defining a link at a higher layer that is supported 561 by those individual links. 563 3.4.6. Mapping redundancy 565 In a hierarchy of networks, there are nodes mapping to nodes, links 566 mapping to links, and termination points mapping to termination 567 points. Some of this information is redundant. Specifically, if the 568 link-to-links mapping known, and the termination points of each link 569 known, termination point mapping information can be derived via 570 transitive closure and does not have to be explicitly configured. 571 Nonetheless, in order to not constrain applications regarding which 572 mappings they want to configure and which should be derived, the 573 model does provide for the option to configure this information 574 explicitly. The model includes integrity constraints to allow for 575 validating for consistency. 577 3.4.7. Typing 579 A network's network types are represented using a container which 580 contains a data node for each of its network types. A network can 581 encompass several types of network simultaneously, hence a container 582 is used instead of a case construct, with each network type in turn 583 represented by a dedicated presence container itself. The reason for 584 not simply using an empty leaf, or even simpler, do away even with 585 the network container and just use a leaf-list of network-type 586 instead, is to be able to represent "class hierarchies" of network 587 types, with one network type refining the other. Network-type 588 specific containers are to be defined in the network-specific 589 modules, augmenting the network-types container. 591 3.4.8. Representing the same device in multiple networks 593 One common requirement concerns the ability to represent that the 594 same device can be part of multiple networks and topologies. 595 However, the model defines a node as relative to the network that it 596 is contained in. The same node cannot be part of multiple 597 topologies. In many cases, a node will be the abstraction of a 598 particular device in a network. To reflect that the same device is 599 part of multiple topologies, the following approach might be chosen: 600 A new type of network to represent a "physical" (or "device") network 601 is introduced, with nodes representing devices. This network forms 602 an underlay network for logical networks above it, with nodes of the 603 logical network mapping onto nodes in the physical network. 605 This scenario is depicted in the following figure. It depicts three 606 networks with two nodes each. A physical network P consists of an 607 inventory of two nodes, D1 and D2, each representing a device. A 608 second network, X, has a third network, Y, as its underlay. Both X 609 and Y also have the physical network P as underlay. X1 has both Y1 610 and D1 as underlay nodes, while Y1 has D1 as underlay node. 611 Likewise, X2 has both Y2 and D2 as underlay nodes, while Y2 has D2 as 612 underlay node. The fact that X1 and Y1 are both instantiated on the 613 same physical node D1 can be easily derived. 615 +---------------------+ 616 / [X1]____[X2] / X(Service Overlay) 617 +----:--:----:--------+ 618 ..: :..: : 619 ........: ....: : :.... 620 +-----:-------------:--+ : :... 621 / [Y1]____[Y2]....: / :.. : 622 +------|-------|-------+ :.. :... 623 Y(L3) | +---------------------:-----+ : 624 | +----:----|-:----------+ 625 +------------------------/---[D1] [D2] / 626 +----------------------+ 627 P (Physical network) 629 Figure 6: Topology hierarchy example - multiple underlays 631 In the case of a physical network, nodes represent physical devices 632 and termination points physical ports. It should be noted that it is 633 also conceivable to augment the model for a physical network-type, 634 defining augmentations that have nodes reference system information 635 and termination points reference physical interfaces, in order to 636 provide a bridge between network and device models. 638 3.5. Items for further discussion 640 YANG requires data needs to be designated as either configuration or 641 operational data, but not both, yet it is important to have all 642 network information, including vertical cross-network dependencies, 643 captured in one coherent model. In most cases network topology 644 information is discovered about a network; the topology is considered 645 a property of the network that is reflected in the model. That said, 646 it is conceivable that certain types of topology need to also be 647 configurable by an application. 649 There are several alternatives in which this can be addressed. The 650 alternative chosen in this draft does not restrict network topology 651 information as read-only, but includes a flag that indicates for each 652 network whether it should be considered as read-only or configurable 653 by applications. 655 An alternative would be to designate network list elements as read 656 only. The read-only network list includes each network; it is the 657 complete reference. In parallel a second network list is introduced. 658 This list serves the purpose of being able to configure networks 659 which are then mirrored in the read-only list. The configurable 660 network list adheres to the same structure and uses the same 661 groupings as its read-only counterpart. As most data is defined in 662 those groupings, the amount of additional definitions required will 663 be limited. A configurable network will thus be represented twice: 664 once in the read-only list of all networks, a second time in a 665 configuration sandbox. 667 Similar considerations apply to scenarios in which data is subject to 668 configuration, but implementations want to be smart enough require 669 only some mapping information, such as which link is supported by 670 which other links, while automatically deriving other mapping 671 information where possible, such as which termination points are 672 supported by which underlay termination points. To accommodate such 673 cases, separate provision may again be made by including another 674 "server-provided" option. 676 4. YANG Modules 678 4.1. Defining the Abstract Network: network.yang 680 file "network.yang" 681 module network { 682 yang-version 1; 683 namespace "urn:TBD:params:xml:ns:yang:nodes"; 684 prefix nd; 686 import ietf-inet-types { prefix inet; } 688 organization "TBD"; 689 contact 690 "WILL-BE-DEFINED-LATER"; 691 description 692 "This module defines a common base model for a collection 693 of nodes in a network. Node definitions s are further used 694 in network topologies and inventories."; 696 revision 2014-3-9 { 697 description 698 "Initial revision."; 699 reference "draft-clemm-i2rs-yang-network-topo-04"; 700 } 702 typedef node-id { 703 type inet:uri; 704 } 706 typedef network-id { 707 type inet:uri; 708 } 710 grouping network-ref { 711 leaf network-ref { 712 type leafref { 713 path "/network/topology-id"; 714 } 715 } 716 } 718 grouping node-ref { 719 uses network-ref; 720 leaf node-ref { 721 type leafref { 722 path "/network[network-id=current()" + 723 "/../network-ref]/node/node-id"; 724 } 725 } 726 } 728 list network { 729 key "network-id"; 731 leaf network-id { 732 type network-id; 733 } 735 leaf server-provided { 736 type boolean; 737 config false; 738 } 740 container network-types { 741 } 743 list supporting-network { 744 key "network-ref"; 745 leaf network-ref { 746 type leafref { 747 path "/network/network-id"; 748 } 749 } 750 } 752 list node { 753 key "node-id"; 754 leaf node-id { 755 type node-id; 756 } 757 list supporting-node { 758 key "network-ref node-ref"; 759 leaf network-ref { 760 type leafref { 761 path "../../../supporting-network/network-ref"; 762 } 763 } 764 leaf node-ref { 765 type leafref { 766 // path "/network[network-id=current()" + 767 // "/../network-ref]/node/node-id"; 768 path "/network/node/node-id"; 769 } 770 } 771 } 772 } 773 } 775 } 776 778 4.2. Creating Abstract Network Topology: network-topology.yang 780 file "network-topology.yang" 781 module network-topology { 782 yang-version 1; 783 namespace "urn:TBD:params:xml:ns:yang:links"; 784 prefix lnk; 786 import ietf-inet-types { prefix inet; } 787 import nodes { prefix nd; } 789 organization "TBD"; 790 contact 791 "WILL-BE-DEFINED-LATER"; 792 description 793 "This module defines a common base model for a collection of links 794 connecting nodes."; 796 revision 2014-3-9 { 797 description 798 "Initial revision."; 799 reference "draft-clemm-i2rs-yang-network-topo-04"; 800 } 802 typedef link-id { 803 type inet:uri; 804 description 805 "An identifier for a link in a topology. 806 The identifier may be opaque. 808 The identifier SHOULD be chosen such that the same link in a 809 real network topology will always be identified through the 810 same identifier, even if the model is instantiated in separate 811 datastores. An implementation MAY choose to capture semantics 812 in the identifier, for example to indicate the type of link 813 and/or the type of topology that the link is a part of."; 814 } 816 typedef tp-id { 817 type inet:uri; 818 description 819 "An identifier for termination points on a node. 820 The identifier may be opaque. 821 The identifier SHOULD be chosen such that the same TP in a 822 real network topology will always be identified through the 823 same identifier, even if the model is instantiated in separate 824 datastores. An implementation MAY choose to capture semantics 825 in the identifier, for example to indicate the type of TP 826 and/or the type of node and topology that the TP is a part 827 of."; 828 } 830 grouping link-ref { 831 description 832 "A type for an absolute reference a link instance. 833 (This type should not be used for relative references. 834 In such a case, a relative path should be used instead.)"; 835 uses nd:network-ref; 836 leaf link-ref { 837 type leafref { 838 path "/nd:network[nd:network-id=current()" + 839 "/../nd:network-ref]/link/link-id"; 840 } 841 } 842 } 844 grouping tp-ref { 845 description 846 "A type for an absolute reference to a termination point. 847 (This type should not be used for relative references. 848 In such a case, a relative path should be used instead.)"; 849 uses nd:node-ref; 850 leaf tp-ref { 851 type leafref { 852 path "/nd:network[nd:network-id=current()" + 853 "/../nd:network-ref]/nd:node[nd:node-id=current()" + 854 "/../nd:node-ref]/termination-point/tp-id"; 855 } 857 } 858 } 860 augment "/nd:network" { 861 list link { 862 key "link-id"; 863 leaf link-id { 864 type link-id; 865 description 866 "The identifier of a link in the topology. 867 A link is specific to a topology to which it belongs."; 868 } 869 description 870 "A Network Link connects a by Local (Source) node and 871 a Remote (Destination) Network Nodes via a set of the 872 nodes' termination points. 873 As it is possible to have several links between the same 874 source and destination nodes, and as a link could 875 potentially be re-homed between termination points, to 876 ensure that we would always know to distinguish between 877 links, every link is identified by a dedicated link 878 identifier. 879 Note that a link models a point-to-point link, not a 880 multipoint link. 881 Layering dependencies on links in underlay topologies are 882 not represented as the layering information of nodes and of 883 termination points is sufficient."; 884 container source { 885 description 886 "This container holds the logical source of a particular 887 link."; 888 leaf source-node { 889 type leafref { 890 path "../../../nd:node/nd:node-id"; 891 } 892 mandatory true; 893 description 894 "Source node identifier, must be in same topology."; 895 } 896 leaf source-tp { 897 type leafref { 898 path "../../../nd:node[nd:node-id=current()/.." + 899 "/source-node]/termination-point/tp-id"; 900 } 901 description 902 "Termination point within source node that terminates 903 the link."; 904 } 906 } 907 container destination { 908 description 909 "This container holds the logical destination of a 910 particular link."; 911 leaf dest-node { 912 type leafref { 913 path "../../../nd:node/nd:node-id"; 914 } 915 mandatory true; 916 description 917 "Destination node identifier, must be in the same 918 network."; 919 } 920 leaf dest-tp { 921 type leafref { 922 path "../../../nd:node[nd:node-id=current()/.." + 923 "/dest-node]/termination-point/tp-id"; 924 } 925 description 926 "Termination point within destination node that 927 terminates the link."; 928 } 929 } 930 list supporting-link { 931 key "network-ref link-ref"; 932 description 933 "Identifies the link, or links, that this link 934 is dependent on."; 935 leaf network-ref { 936 type leafref { 937 path "../../../nd:supporting-network/nd:network-ref"; 938 } 939 description 940 "This leaf identifies in which underlay topology 941 supporting link is present."; 942 } 943 leaf link-ref { 944 type leafref { 945 path "/nd:network[nd:network-id=" + 946 "current()/../network-ref]/link/link-id"; 947 } 948 description 949 "This leaf identifies a link which is forms a part 950 of this link's underlay. Reference loops, where 951 a link identifies itself as its underlay, either 952 directly or transitively, are not allowed."; 953 } 955 } 956 } 957 } 959 augment "/nd:network/nd:node" { 960 list termination-point { 961 key "tp-id"; 962 description 963 "A termination point can terminate a link. 964 Depending on the type of topology, a termination point 965 could, for example, refer to a port or an interface."; 966 leaf tp-id { 967 type tp-id; 968 description 969 "Termination point identifier."; 970 } 971 list supporting-termination-point { 972 key "network-ref node-ref tp-ref"; 973 description 974 "The leaf list identifies any termination points that 975 the termination point is dependent on, or maps onto. 976 Those termination points will themselves be contained 977 in a supporting node. 978 This dependency information can be inferred from 979 the dependencies between links. For this reason, 980 this item is not separately configurable. Hence no 981 corresponding constraint needs to be articulated. 982 The corresponding information is simply provided by the 983 implementing system."; 984 leaf network-ref { 985 type leafref { 986 path "../../../nd:supporting-node/nd:network-ref"; 987 } 988 description 989 "This leaf identifies in which topology the 990 supporting termination point is present."; 991 } 992 leaf node-ref { 993 type leafref { 994 path "../../../nd:supporting-node/nd:node-ref"; 995 } 996 description 997 "This leaf identifies in which node the supporting 998 termination point is present."; 999 } 1000 leaf tp-ref { 1001 type leafref { 1002 path "/nd:network[nd:network-id=" + 1003 "current()/../network-ref]/nd:node[nd:node-id=" + 1004 "current()/../node-ref]/termination-point" + 1005 "/tp-id"; 1006 } 1007 description 1008 "Reference to the underlay node, must be in a 1009 different topology"; 1010 } 1011 } 1012 } 1013 } 1014 } 1016 1018 5. Security Considerations 1020 The transport protocol used for sending the topology data MUST 1021 support authentication and SHOULD support encryption. The data-model 1022 by itself does not create any security implications. 1024 6. Contributors 1026 The model presented in this paper was contributed to by more people 1027 than can be listed on the author list. Additional contributors 1028 include: 1030 o Ken Gray, Cisco Systems 1032 o Tom Nadeau, Brocade 1034 o Aleksandr Zhdankin, Cisco 1036 7. Acknowledgements 1038 We wish to acknowledge the helpful contributions, comments, and 1039 suggestions that were received from Alia Atlas, Vishna Pavan Beeram, 1040 Andy Bierman, Martin Bjorklund, Igor Bryskin, Benoit Claise, Susan 1041 Hares, Xufeng Liu, Ladislav Lhotka, Carlos Pignataro, Juergen 1042 Schoenwaelder, and Xian Zhang. 1044 8. References 1046 8.1. Normative References 1048 [RFC1195] Callon, R., "Use of OSI IS-IS for routing in TCP/IP and 1049 dual environments", RFC 1195, December 1990. 1051 [RFC2328] Moy, J., "OSPF Version 2", STD 54, RFC 2328, April 1998. 1053 [RFC3209] Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V., 1054 and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP 1055 Tunnels", RFC 3209, December 2001. 1057 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1058 Network Configuration Protocol (NETCONF)", RFC 6020, 1059 October 2010. 1061 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1062 October 2010. 1064 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1065 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1066 6241, June 2011. 1068 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1069 Management", RFC 7223, May 2014. 1071 8.2. Informative References 1073 [restconf] 1074 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1075 Protocol", I-D draft-ietf-netconf-restconf-04, January 1076 2015. 1078 [topology-use-cases] 1079 Medved, J., Previdi, S., Lopez, V., and S. Amante, 1080 "Topology API Use Cases", I-D draft-amante-i2rs-topology- 1081 use-cases-01, October 2013. 1083 [yang-json] 1084 Lhotka, L., "JSON Encoding of Data Modeled with YANG", I-D 1085 draft-ietf-netmod-yang-json-03, February 2015. 1087 Authors' Addresses 1089 Alexander Clemm 1090 Cisco 1092 EMail: alex@cisco.com 1094 Jan Medved 1095 Cisco 1097 EMail: jmedved@cisco.com 1098 Robert Varga 1099 Cisco 1101 EMail: rovarga@cisco.com 1103 Tony Tkacik 1104 Cisco 1106 EMail: ttkacik@cisco.com 1108 Nitin Bahadur 1109 Bracket Computing 1111 EMail: nitin_bahadur@yahoo.com 1113 Hariharan Ananthakrishnan 1114 Packet Design 1116 EMail: hari@packetdesign.com