idnits 2.17.1 draft-ietf-i2rs-yang-l3-topology-12.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 238 has weird spacing: '... prefix ine...' -- The document date (October 25, 2017) is 2374 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC1195' is defined on line 795, but no explicit reference was found in the text == Unused Reference: 'RFC2863' is defined on line 803, but no explicit reference was found in the text == Unused Reference: 'RFC7223' is defined on line 854, but no explicit reference was found in the text == Outdated reference: A later version (-20) exists of draft-ietf-i2rs-yang-network-topo-16 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-02 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-10) exists of draft-acee-rtgwg-yang-rib-extend-04 == Outdated reference: A later version (-22) exists of draft-ietf-teas-yang-te-topo-12 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) -- Obsolete informational reference (is this intentional?): RFC 8022 (Obsoleted by RFC 8349) Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Clemm 3 Internet-Draft Huawei 4 Intended status: Standards Track J. Medved 5 Expires: April 28, 2018 Cisco 6 R. Varga 7 Pantheon Technologies SRO 8 X. Liu 9 Ericsson 10 H. Ananthakrishnan 11 Packet Design 12 N. Bahadur 13 Bracket Computing 14 October 25, 2017 16 A YANG Data Model for Layer 3 Topologies 17 draft-ietf-i2rs-yang-l3-topology-12.txt 19 Abstract 21 This document defines a YANG data model for layer 3 network 22 topologies. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 28, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 3 61 4. Model Structure . . . . . . . . . . . . . . . . . . . . . . . 4 62 5. Layer 3 Unicast Topology Model Overview . . . . . . . . . . . 5 63 6. Layer 3 Unicast Topology YANG Module . . . . . . . . . . . . 7 64 7. Interactions with Other YANG Modules . . . . . . . . . . . . 15 65 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 66 9. Security Considerations . . . . . . . . . . . . . . . . . . . 16 67 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 17 68 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 69 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 70 12.1. Normative References . . . . . . . . . . . . . . . . . . 17 71 12.2. Informative References . . . . . . . . . . . . . . . . . 18 72 Appendix A. Companion YANG model for non-NMDA compliant 73 implementations . . . . . . . . . . . . . . . . . . 20 74 Appendix B. Extending the Model . . . . . . . . . . . . . . . . 24 75 B.1. Example OSPF Topology . . . . . . . . . . . . . . . . . . 24 76 B.1.1. Model Overview . . . . . . . . . . . . . . . . . . . 24 77 B.1.2. OSPF Topology YANG Module . . . . . . . . . . . . . . 26 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 80 1. Introduction 82 This document introduces a YANG [RFC7950] [RFC6991] data model for 83 Layer 3 network topologies, specifically Layer 3 Unicast. The model 84 allows an application to have a holistic view of the topology of a 85 Layer 3 network, all contained in a single conceptual YANG datastore. 86 The data model builds on top of, and augments, the data model for 87 network topologies defined in 88 [I-D.draft-ietf-i2rs-yang-network-topo]. 90 This document also shows how the model can be further refined to 91 cover different Layer 3 Unicast topology types. For this purpose, 92 example model is introduced that covers OSPF [RFC2328]. This example 93 is intended purely for illustrative purpose; we expect that full- 94 blown OSPF model will be more comprehensive and refined than the 95 example shown here. 97 There are multiple applications for a topology data model. A number 98 of use cases have been defined in section 6 of 99 [I-D.draft-ietf-i2rs-usecase-reqs-summary]. For example, nodes 100 within the network can use the data model to capture their 101 understanding of the overall network topology and expose it to a 102 network controller. A network controller can then use the 103 instantiated topology data to compare and reconcile its own view of 104 the network topology with that of the network elements that it 105 controls. Alternatively, nodes within the network could propagate 106 this understanding to compare and reconcile this understanding either 107 amongst themselves or with help of a controller. Beyond the network 108 element itself, a network controller might even use the data model to 109 represent its view of the topology that it controls and expose it to 110 applications north of itself. 112 The data model for Layer 3 Unicast topologies defined in this 113 document is specified in a YANG module "ietf-l3-unicast-topology". 114 To do so, it augments general network topology model defined in 115 [I-D.draft-ietf-i2rs-yang-network-topo] with information specific to 116 Layer 3 Unicast. This way, the general topology model is extended to 117 be able to meet the needs of Layer 3 Unicast topologies. 119 Information that is kept in the Traffic Engineering Database (TED) 120 will be specified in a separate model 121 [I-D.draft-ietf-teas-yang-te-topo] and outside the scope of this 122 specification. 124 2. Key Words 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 128 "OPTIONAL" in this document are to be interpreted as described in BCP 129 14 [RFC2119] [RFC8174] when, and only when, they appear in all 130 capitals, as shown here. 132 3. Definitions and Acronyms 134 As this document defines a YANG data model, in this document many 135 terms are used that have been defined in conjunction with YANG 136 [RFC7950] and NETCONF [RFC6241]. Some terms, such as datastore and 137 data tree, are repeated here for clarity and to put them in context. 139 Datastore: A conceptual store of instantiated management information, 140 with individual data items represented by data nodes which are 141 arranged in hierarchical manner. 143 Data subtree: An instantiated data node and the data nodes that are 144 hierarchically contained within it. 146 HTTP: Hyper-Text Transfer Protocol 148 IGP: Interior Gateway Protocol 150 IS-IS: Intermediate System to Intermediate System protocol 152 LSP: Label Switched Path 154 NETCONF: Network Configuration Protocol 156 NMDA: Network Management Datastore Architecture 158 OSPF: Open Shortest Path First, a link state routing protocol 160 URI: Uniform Resource Identifier 162 ReST: Representational State Transfer, a style of stateless interface 163 and protocol that is generally carried over HTTP 165 SRLG: Shared Risk Link Group 167 TED: Traffic Engineering Database 169 YANG: A data definition language for NETCONF 171 4. Model Structure 173 The Layer 3 Unicast topology model is defined by YANG module "l3- 174 unicast-topology". The relationship of this module with other YANG 175 modules is roughly depicted in the figure below. 177 +-----------------------------+ 178 | +-----------------------+ | 179 | | ietf-network | | 180 | +----------^------------+ | 181 | | | 182 | +-----------------------+ | 183 | | ietf-network-topology | | 184 | +----------+------------+ | 185 +-------------^---------------+ 186 | 187 | 188 +-----------^-------------+ 189 | L3-UNICAST-TOPOLOGY | 190 +----+------^--------+----+ 191 | 192 | 193 +-------^-------+ 194 | ospf-topology | 195 +---------------+ 197 Figure 1: Overall model structure 199 YANG modules "ietf-network" and "ietf-network-topology" collectively 200 define the basic network topology model. YANG module "ietf-l3- 201 unicast-topology" augments those models with additional definitions 202 needed to represent Layer 3 Unicast topologies. This module in turn 203 can be augmented by YANG modules with additional definitions for 204 specific types of Layer 3 Unicast topologies, such as OSPF and for 205 IS-IS topologies. 207 The YANG modules ietf-network and ietf-network are designed to be 208 used in conjunction with implementations that support the Network 209 Management Datastore Architecture (NMDA) defined in 210 [I-D.draft-ietf-netmod-revised-datastores]. Accordingly, the same is 211 true for the YANG modules that augment it. In order to allow 212 implementations to use the model even in cases when NMDA is not 213 supported, companion YANG modules (that SHOULD NOT be supported by 214 implementations that support NMDA) are defined in an Appendix, see 215 Appendix A. 217 5. Layer 3 Unicast Topology Model Overview 219 The Layer 3 Unicast topology model is defined by YANG module "ietf- 220 l3-unicast-topology". Its structure is depicted in the following 221 diagram. The notation syntax follows 222 [I-D.draft-ietf-netmod-yang-tree-diagrams]. For purposes of brevity, 223 notifications are not depicted. 225 module: ietf-l3-unicast-topology 226 augment /nw:networks/nw:network/nw:network-types: 227 +--rw l3-unicast-topology! 228 augment /nw:networks/nw:network: 229 +--rw l3-topology-attributes 230 +--rw name? string 231 +--rw flag* l3-flag-type 232 augment /nw:networks/nw:network/nw:node: 233 +--rw l3-node-attributes 234 +--rw name? inet:domain-name 235 +--rw flag* node-flag-type 236 +--rw router-id* inet:ip-address 237 +--rw prefix* [prefix] 238 +--rw prefix inet:ip-prefix 239 +--rw metric? uint32 240 +--rw flag* prefix-flag-type 241 augment /nw:networks/nw:network/nt:link: 242 +--rw l3-link-attributes 243 +--rw name? string 244 +--rw flag* link-flag-type 245 +--rw metric1? uint64 246 +--rw metric2? uint64 247 augment /nw:networks/nw:network/nw:node/nt:termination-point: 248 +--rw l3-termination-point-attributes 249 +--rw (termination-point-type)? 250 +--:(ip) 251 | +--rw ip-address* inet:ip-address 252 +--:(unnumbered) 253 | +--rw unnumbered-id? uint32 254 +--:(interface-name) 255 +--rw interface-name? string 257 The module augments the original ietf-network and ietf-network- 258 topology modules as follows: 260 o A new network topology type is introduced, l3-unicast-topology. 261 The corresponding container augments the network-types of the 262 ietf-network module. 264 o Additional topology attributes are introduced, defined in a 265 grouping, which augments the "network" list of the network module. 266 The attributes include a name for the topology, as well as a set 267 of flags (represented through a leaf-list). Each type of flag is 268 represented by a separate identity. This allows to introduce 269 additional flags in augmenting modules using additional identities 270 without needing to revise this module. 272 o Additional data objects for nodes are introduced by augmenting the 273 "node" list of the network module. New objects include again a 274 set of flags, as well as a list of prefixes. Each prefix in turn 275 includes an ip prefix, a metric, and a prefix-specific set of 276 flags. 278 o Links (in the ietf-network-topology module) are augmented with a 279 set of parameters as well, allowing to associate a link with a 280 link name, another set of flags, and a link metric. 282 o Termination points (in the ietf-network-topology module as well) 283 are augmented with a choice of IP address, identifier, or name. 285 In addition, the module defines a set of notifications to alert 286 clients of any events concerning links, nodes, prefixes, and 287 termination points. Each notification includes an indication of the 288 type of event, the topology from which it originated, and the 289 affected node, or link, or prefix, or termination point. In 290 addition, as a convenience to applications, additional data of the 291 affected node, or link, or termination point (respectively) is 292 included. While this makes notifications larger in volume than they 293 would need to be, it avoids the need for subsequent retrieval of 294 context information, which also might have changed in the meantime. 296 6. Layer 3 Unicast Topology YANG Module 298 file "ietf-l3-unicast-topology@2017-10-25.yang" 299 module ietf-l3-unicast-topology { 300 yang-version 1.1; 301 namespace 302 "urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology"; 303 prefix "l3t"; 304 import ietf-network { 305 prefix "nw"; 306 } 307 import ietf-network-topology { 308 prefix "nt"; 309 } 310 import ietf-inet-types { 311 prefix "inet"; 312 } 313 organization 314 "IETF I2RS (Interface to the Routing System) Working Group"; 315 contact 316 "WG Web: 317 WG List: 318 Editor: Alexander Clemm 319 321 Editor: Jan Medved 322 323 Editor: Robert Varga 324 325 Editor: Xufeng Liu 326 327 Editor: Nitin Bahadur 328 329 Editor: Hariharan Ananthakrishnan 330 "; 331 description 332 "This module defines a model for Layer 3 Unicast 333 topologies. 334 Copyright (c) 2017 IETF Trust and the persons identified as 335 authors of the code. All rights reserved. 336 Redistribution and use in source and binary forms, with or 337 without modification, is permitted pursuant to, and subject 338 to the license terms contained in, the Simplified BSD License 339 set forth in Section 4.c of the IETF Trust's Legal Provisions 340 Relating to IETF Documents 341 (http://trustee.ietf.org/license-info). 342 This version of this YANG module is part of 343 draft-ietf-i2rs-yang-l3-topology-12; 344 see the RFC itself for full legal notices. 345 NOTE TO RFC EDITOR: Please replace above reference to 346 draft-ietf-i2rs-yang-l3-topology-12 with RFC 347 number when published (i.e. RFC xxxx)."; 348 revision "2017-10-25" { 349 description 350 "Initial revision. 351 NOTE TO RFC EDITOR: Please replace the following reference 352 to draft-ietf-i2rs-yang-l3-topology-12 with 353 RFC number when published (i.e. RFC xxxx)."; 354 reference 355 "draft-ietf-i2rs-yang-l3-topology-12"; 356 } 358 identity flag-identity { 359 description "Base type for flags"; 360 } 362 typedef l3-event-type { 363 type enumeration { 364 enum "add" { 365 description 366 "An Layer 3 node or link or prefix or termination-point has 367 been added"; 368 } 369 enum "remove" { 370 description 371 "An Layer 3 node or link or prefix or termination-point has 372 been removed"; 373 } 374 enum "update" { 375 description 376 "An Layer 3 node or link or prefix or termination-point has 377 been updated"; 378 } 379 } 380 description "Layer 3 Event type for notifications"; 381 } 383 typedef prefix-flag-type { 384 type identityref { 385 base "flag-identity"; 386 } 387 description "Prefix flag attributes"; 388 } 390 typedef node-flag-type { 391 type identityref { 392 base "flag-identity"; 393 } 394 description "Node flag attributes"; 395 } 397 typedef link-flag-type { 398 type identityref { 399 base "flag-identity"; 400 } 401 description "Link flag attributes"; 402 } 404 typedef l3-flag-type { 405 type identityref { 406 base "flag-identity"; 407 } 408 description "L3 flag attributes"; 409 } 411 grouping l3-prefix-attributes { 412 description 413 "L3 prefix attributes"; 414 leaf prefix { 415 type inet:ip-prefix; 416 description 417 "IP prefix value"; 418 } 419 leaf metric { 420 type uint32; 421 description 422 "Prefix metric"; 423 } 424 leaf-list flag { 425 type prefix-flag-type; 426 description 427 "Prefix flags"; 428 } 429 } 430 grouping l3-unicast-topology-type { 431 description "Identify the topology type to be L3 unicast."; 432 container l3-unicast-topology { 433 presence "indicates L3 Unicast Topology"; 434 description 435 "The presence of the container node indicates L3 Unicast 436 Topology"; 437 } 438 } 439 grouping l3-topology-attributes { 440 description "Topology scope attributes"; 441 container l3-topology-attributes { 442 description "Containing topology attributes"; 443 leaf name { 444 type string; 445 description 446 "Name of the topology"; 447 } 448 leaf-list flag { 449 type l3-flag-type; 450 description 451 "Topology flags"; 452 } 453 } 454 } 455 grouping l3-node-attributes { 456 description "L3 node scope attributes"; 457 container l3-node-attributes { 458 description 459 "Containing node attributes"; 460 leaf name { 461 type inet:domain-name; 462 description 463 "Node name"; 464 } 465 leaf-list flag { 466 type node-flag-type; 467 description 468 "Node flags"; 469 } 470 leaf-list router-id { 471 type inet:ip-address; 472 description 473 "Router-id for the node"; 474 } 475 list prefix { 476 key "prefix"; 477 description 478 "A list of prefixes along with their attributes"; 479 uses l3-prefix-attributes; 480 } 481 } 482 } 483 grouping l3-link-attributes { 484 description 485 "L3 link scope attributes"; 486 container l3-link-attributes { 487 description 488 "Containing link attributes"; 489 leaf name { 490 type string; 491 description 492 "Link Name"; 493 } 494 leaf-list flag { 495 type link-flag-type; 496 description 497 "Link flags"; 498 } 499 leaf metric1 { 500 type uint64; 501 description 502 "Link Metric 1"; 503 } 504 leaf metric2 { 505 type uint64; 506 description 507 "Link Metric 2"; 508 } 509 } 510 } 511 grouping l3-termination-point-attributes { 512 description "L3 termination point scope attributes"; 513 container l3-termination-point-attributes { 514 description 515 "Containing termination point attributes"; 516 choice termination-point-type { 517 description 518 "Indicates the termination point type"; 519 case ip { 520 leaf-list ip-address { 521 type inet:ip-address; 522 description 523 "IPv4 or IPv6 address."; 524 } 525 } 526 case unnumbered { 527 leaf unnumbered-id { 528 type uint32; 529 description 530 "Unnumbered interface identifier. 531 The identifier will correspond to the ifIndex value 532 of the interface, i.e. the ifIndex value of the 533 ifEntry that represents the interface in 534 implementations where the Interfaces Group MIB 535 (RFC 2863) is supported."; 536 reference 537 "RFC 2863: The Interfaces Group MIB"; 538 } 539 } 540 case interface-name { 541 leaf interface-name { 542 type string; 543 description 544 "A name of the interface. The name can (but does not 545 have to) correspond to an interface reference of a 546 containing node's interface, i.e. the path name of a 547 corresponding interface data node on the containing 548 node reminiscent of data type if-ref defined in 549 RFC 7223. It should be noted that data type if-ref of 550 RFC 7223 cannot be used directly, as this data type 551 is used to reference an interface in a datastore of 552 a single node in the network, not to uniquely 553 reference interfaces across a network."; 554 } 555 } 556 } 557 } 558 } 559 augment "/nw:networks/nw:network/nw:network-types" { 560 description 561 "Introduce new network type for L3 unicast topology"; 562 uses l3-unicast-topology-type; 563 } 564 augment "/nw:networks/nw:network" { 565 when "nw:network-types/l3-unicast-topology" { 566 description 567 "Augmentation parameters apply only for networks with 568 L3 unicast topology"; 569 } 570 description 571 "L3 unicast for the network as a whole"; 572 uses l3-topology-attributes; 573 } 574 augment "/nw:networks/nw:network/nw:node" { 575 when "../nw:network-types/l3-unicast-topology" { 576 description 577 "Augmentation parameters apply only for networks with 578 L3 unicast topology"; 579 } 580 description 581 "L3 unicast node level attributes "; 582 uses l3-node-attributes; 583 } 584 augment "/nw:networks/nw:network/nt:link" { 585 when "../nw:network-types/l3-unicast-topology" { 586 description 587 "Augmentation parameters apply only for networks with 588 L3 unicast topology"; 589 } 590 description 591 "Augment topology link attributes"; 592 uses l3-link-attributes; 593 } 594 augment "/nw:networks/nw:network/nw:node/" 595 +"nt:termination-point" { 596 when "../../nw:network-types/l3-unicast-topology" { 597 description 598 "Augmentation parameters apply only for networks with 599 L3 unicast topology"; 600 } 601 description "Augment topology termination point configuration"; 602 uses l3-termination-point-attributes; 603 } 604 notification l3-node-event { 605 description 606 "Notification event for L3 node"; 607 leaf l3-event-type { 608 type l3-event-type; 609 description 610 "Event type"; 611 } 612 uses nw:node-ref; 613 uses l3-unicast-topology-type; 614 uses l3-node-attributes; 615 } 616 notification l3-link-event { 617 description 618 "Notification event for L3 link"; 619 leaf l3-event-type { 620 type l3-event-type; 621 description 622 "Event type"; 623 } 624 uses nt:link-ref; 625 uses l3-unicast-topology-type; 626 uses l3-link-attributes; 627 } 628 notification l3-prefix-event { 629 description 630 "Notification event for L3 prefix"; 631 leaf l3-event-type { 632 type l3-event-type; 633 description 634 "Event type"; 635 } 636 uses nw:node-ref; 637 uses l3-unicast-topology-type; 638 container prefix { 639 description 640 "Containing L3 prefix attributes"; 641 uses l3-prefix-attributes; 642 } 643 } 644 notification termination-point-event { 645 description 646 "Notification event for L3 termination point"; 647 leaf l3-event-type { 648 type l3-event-type; 649 description 650 "Event type"; 651 } 652 uses nt:tp-ref; 653 uses l3-unicast-topology-type; 654 uses l3-termination-point-attributes; 655 } 656 } 657 659 7. Interactions with Other YANG Modules 661 As described in section Section 4, the model builds on top of, and 662 augments, the YANG modules defined in 663 [I-D.draft-ietf-i2rs-yang-network-topo]. Specifically, module ietf- 664 l3-unicast-topology augments modules "ietf-network" and "ietf- 665 network-topology". In addition, the model makes use of data types 666 that have been defined in [RFC6991]. 668 The moodel defines a protocol independent YANG data model with layer 669 3 topology information. It is separate from and not linked with data 670 models that are used to configure routing protocols or routing 671 information. This includes e.g. model "ietf-routing" [RFC8022] and 672 model "ietf-fb-rib" [I-D.draft-acee-rtgwg-yang-rib-extend]. 674 The model obeys the requirements for the ephemeral state found in the 675 document [RFC8242]. For ephemeral topology data that is server 676 provided, the process tasked with maintaining topology information 677 will load information from the routing process (such as OSPF) into 678 the data model without relying on a configuration datastore. 680 8. IANA Considerations 682 This document registers the following namespace URIs in the "IETF XML 683 Registry" [RFC3688]: 685 URI: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology 686 Registrant Contact: The IESG. 687 XML: N/A; the requested URI is an XML namespace. 689 URI: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state 690 Registrant Contact: The IESG. 691 XML: N/A; the requested URI is an XML namespace. 693 This document registers the following YANG modules in the "YANG 694 Module Names" registry [RFC6020]: 696 Name: ietf-l3-unicast-topology 697 Namespace: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology 698 Prefix: l3t 699 Reference: draft-ietf-i2rs-yang-l3-topology-12.txt (RFC form) 701 Name: ietf-l3-unicast-topology-state 702 Namespace: urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state 703 Prefix: l3t-s 704 Reference: draft-ietf-i2rs-yang-l3-topology-12.txt (RFC form) 706 9. Security Considerations 708 The YANG module defined in this document is designed to be accessed 709 via network management protocols such as NETCONF [RFC6241] or 710 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport 711 layer, and the mandatory-to-implement secure transport is Secure 712 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the 713 mandatory-to-implement secure transport is TLS [RFC5246]. 715 The NETCONF access control model [RFC6536] provides the means to 716 restrict access for particular NETCONF or RESTCONF users to a 717 preconfigured subset of all available NETCONF or RESTCONF protocol 718 operations and content. 720 In general, Layer 3 Unicast topologies are system-controlled and 721 provide ephemeral topology information. In an NMDA-complient server, 722 they are only part of which provides read-only access 723 to clients, they are less vulnerable. That said, the YANG module 724 does in principle allow information to be configurable. 726 There are a number of data nodes defined in this YANG module that are 727 writable/creatable/deletable (i.e., config true, which is the 728 default). These data nodes may be considered sensitive or vulnerable 729 in some network environments. Write operations (e.g., edit-config) 730 to these data nodes without proper protection can have a negative 731 effect on network operations. These are the subtrees and data nodes 732 and their sensitivity/vulnerability in the ietf-network module: 734 l3-topology-attributes: A malicious client could attempt to 735 sabotage the configuration of any of the ctonained attributes, 736 i.e. the name or the flag data nodes. 738 l3-node-attributes: A malicious client could attempt to sabotage 739 the configuration of important node attributes, such as the 740 router-id or node prefix. 742 l3-link-attributes: A malicious client could attempt to sabotage 743 the configuration of important link attributes, such as name, 744 flag, and metrics of the link respectively corresponding data 745 nodes. 747 l3-termination-point-attributes: A malicious client could attempt 748 to sabotage the configuration information of a termination point, 749 such as its ip-address and interface name, respectively the 750 corresponding data nodes. 752 10. Contributors 754 The model presented in this document was contributed to by more 755 people than can be listed on the author list. Additional 756 contributors include: 758 o Vishnu Pavan Beeram, Juniper 760 o Igor Bryskin, Huawei 762 o Ken Gray, Cisco 764 o Aihua Guo, Huawei 766 o Tom Nadeau, Brocade 768 o Tony Tkacik 770 o Aleksandr Zhdankin, Cisco 772 11. Acknowledgements 774 We wish to acknowledge the helpful contributions, comments, and 775 suggestions that were received from Alia Atlas, Andy Bierman, Benoit 776 Claise, Joel Halpern, Susan Hares, Ladislav Lhotka, Carl Moberg, 777 Carlos Pignataro, Juergen Schoenwaelder, and Kent Watsen. 779 12. References 781 12.1. Normative References 783 [I-D.draft-ietf-i2rs-yang-network-topo] 784 Clemm, A., Medved, J., Varga, R., Bahadur, N., 785 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 786 Network Topologies", I-D draft-ietf-i2rs-yang-network- 787 topo-16, September 2017. 789 [I-D.draft-ietf-netmod-revised-datastores] 790 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 791 and R. Wilton, "A Revised Conceptual Model for YANG 792 Datastores", I-D draft-ietf-netmod-revised-datastores-02, 793 May 2017. 795 [RFC1195] Callon, R., "Use of OSI IS-IS for Routing in TCP/IP and 796 Dual Environments", RFC 1195, December 1990. 798 [RFC2119] Bradner, S., "Key words for use in RFCs to indicate 799 requirement levels", RFC 2119, March 1997. 801 [RFC2328] Moy, J., "OSPF Version 2", RFC 2328, April 1998. 803 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 804 MIB", RFC 2863, June 2000. 806 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 807 2004. 809 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 810 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 812 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 813 Network Configuration Protocol (NETCONF)", RFC 6020, 814 October 2010. 816 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 817 Bierman, "Network Configuration Protocol (NETCONF)", 818 RFC 6241, June 2011. 820 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 821 Shell (SSH)", RFC 6242, June 2011. 823 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 824 Protocol (NETCONF) Access Control Model", RFC 6536, March 825 2012. 827 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 828 July 2013. 830 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 831 RFC 7950, August 2016. 833 12.2. Informative References 835 [I-D.draft-acee-rtgwg-yang-rib-extend] 836 Lindem, A. and Y. Qu, "YANG Data Model for RIB 837 Extensions", I-D draft-acee-rtgwg-yang-rib-extend-04, 838 October 2017. 840 [I-D.draft-ietf-i2rs-usecase-reqs-summary] 841 Hares, S. and M. Chen, "Summary of I2RS Use Case 842 Requirements", I-D draft-ietf-i2rs-usecase-reqs-summary- 843 03, November 2016. 845 [I-D.draft-ietf-netmod-yang-tree-diagrams] 846 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", I-D 847 draft-ietf-netmod-yang-tree-diagrams, June 2017. 849 [I-D.draft-ietf-teas-yang-te-topo] 850 Liu, X., Bryskin, I., Beeram, V., Saad, T., Shah, H., and 851 O. Gonzalez De Dios, "YANG Data Model for TE Topologies", 852 I-D draft-ietf-teas-yang-te-topo-12, July 2017. 854 [RFC7223] Bjorklund, M., "A YANG Data Model for Routing Management", 855 RFC 7223, May 2014. 857 [RFC8022] Lhotka, L. and A. Lindem, "A YANG Data Model for Routing 858 Management", RFC 8022, November 2016. 860 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 861 Protocol", RFC 8040, January 2017. 863 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 864 2119 Key Words", RFC 8174, May 2017. 866 [RFC8242] Haas, J. and S. Hares, "I2RS Ephemeral State 867 Requirements", RFC 8242, September 2017. 869 Appendix A. Companion YANG model for non-NMDA compliant implementations 871 The YANG module ietf-l3-unicast-topology defined in this document 872 augments two modules, ietf-network and ietf-network-topology, that 873 are designed to be used in conjunction with implementations that 874 support the Network Management Datastore Architecture (NMDA) defined 875 in [I-D.draft-ietf-netmod-revised-datastores]. In order to allow 876 implementations to use the model even in cases when NMDA is not 877 supported, a set of companion modules have been defined that 878 represent a state model of networks and network topologies, ietf- 879 network-state and ietf-network-topology-state, respectively. 881 In order to be able to use the model for layer 3 topologies defined 882 in this in this document in conjunction with non-NMDA compliant 883 implementations, a corresponding companion module needs to be 884 introduced as well. This companion module, ietf-l3-unicast-topology- 885 state, mirrors ietf-l3-unicast-topology. However, the module 886 augments ietf-network-state and ietf-network-topology-state (instead 887 of ietf-network and ietf-network-state) and all of its data nodes are 888 non-configurable. 890 Similar considerations apply for any modules that augment ietf-l3- 891 unicast-topology, such as the example modules defined in see 892 Appendix B, example-ietf-ospf-topology. For non-NMDA compliant 893 implementations, companion modules will need to be introduced that 894 represent state information and are non-configurable, augmenting 895 ietf-l3-unicast-topology-state instead of ietf-l3-unicast-topology. 896 Because they served as examples only, companion modules for those 897 examples are not given. 899 Like ietf-network-state and ietf-network-topology-state, ietf-l3- 900 unicast-topology SHOULD NOT be supported by implementations that 901 support NMDA. It is for this reason that the module is defined in 902 the Appendix. 904 The definition of the module follows below. As the structure of the 905 module mirrors that of its underlying module, the YANG tree is not 906 depicted separately. 908 file "ietf-l3-unicast-topology-state@2017-10-25.yang" 909 module ietf-l3-unicast-topology-state { 910 yang-version 1.1; 911 namespace 912 "urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state"; 913 prefix "l3t-s"; 914 import ietf-network-state { 915 prefix "nw-s"; 916 } 917 import ietf-network-topology-state { 918 prefix "nt-s"; 919 } 920 import ietf-l3-unicast-topology { 921 prefix "l3t"; 922 } 923 organization 924 "IETF I2RS (Interface to the Routing System) Working Group"; 925 contact 926 "WG Web: 927 WG List: 928 Editor: Alexander Clemm 929 930 Editor: Jan Medved 931 932 Editor: Robert Varga 933 934 Editor: Xufeng Liu 935 936 Editor: Nitin Bahadur 937 938 Editor: Hariharan Ananthakrishnan 939 "; 940 description 941 "This module defines a model for Layer 3 Unicast topology 942 state, representing topology that is either learned, or topology 943 that results from applying topology that has been configured per 944 the ietf-l3-unicast-topology model, mirroring the corresponding 945 data nodes in this model. 947 The model mirrors ietf-l3-unicast-topology, but contains only 948 read-only state data. The model is not needed when the 949 underlying implementation infrastructure supports the Network 950 Management Datastore Architecture (NMDA). 952 Copyright (c) 2017 IETF Trust and the persons identified as 953 authors of the code. All rights reserved. 954 Redistribution and use in source and binary forms, with or 955 without modification, is permitted pursuant to, and subject 956 to the license terms contained in, the Simplified BSD License 957 set forth in Section 4.c of the IETF Trust's Legal Provisions 958 Relating to IETF Documents 959 (http://trustee.ietf.org/license-info). 960 This version of this YANG module is part of 961 draft-ietf-i2rs-yang-l3-topology-12; 962 see the RFC itself for full legal notices. 963 NOTE TO RFC EDITOR: Please replace above reference to 964 draft-ietf-i2rs-yang-l3-topology-12 with RFC 965 number when published (i.e. RFC xxxx)."; 966 revision "2017-10-25" { 967 description 968 "Initial revision. 969 NOTE TO RFC EDITOR: Please replace the following reference 970 to draft-ietf-i2rs-yang-l3-topology-12 with 971 RFC number when published (i.e. RFC xxxx)."; 972 reference 973 "draft-ietf-i2rs-yang-l3-topology-12"; 974 } 975 augment "/nw-s:networks/nw-s:network/nw-s:network-types" { 976 description 977 "Introduce new network type for L3 unicast topology"; 978 uses l3t:l3-unicast-topology-type; 979 } 980 augment "/nw-s:networks/nw-s:network" { 981 when "nw-s:network-types/l3-unicast-topology" { 982 description 983 "Augmentation parameters apply only for networks with 984 L3 unicast topology"; 985 } 986 description 987 "L3 unicast for the network as a whole"; 988 uses l3t:l3-topology-attributes; 989 } 990 augment "/nw-s:networks/nw-s:network/nw-s:node" { 991 when "../nw-s:network-types/l3-unicast-topology" { 992 description 993 "Augmentation parameters apply only for networks with 994 L3 unicast topology"; 995 } 996 description 997 "L3 unicast node level attributes "; 998 uses l3t:l3-node-attributes; 999 } 1000 augment "/nw-s:networks/nw-s:network/nt-s:link" { 1001 when "../nw-s:network-types/l3-unicast-topology" { 1002 description 1003 "Augmentation parameters apply only for networks with 1004 L3 unicast topology"; 1005 } 1006 description 1007 "Augment topology link attributes"; 1008 uses l3t:l3-link-attributes; 1009 } 1010 augment "/nw-s:networks/nw-s:network/nw-s:node/" 1011 +"nt-s:termination-point" { 1012 when "../../nw-s:network-types/l3-unicast-topology" { 1013 description 1014 "Augmentation parameters apply only for networks with 1015 L3 unicast topology"; 1016 } 1017 description "Augment topology termination point configuration"; 1018 uses l3t:l3-termination-point-attributes; 1019 } 1020 notification l3-node-event { 1021 description 1022 "Notification event for L3 node"; 1023 leaf l3-event-type { 1024 type l3t:l3-event-type; 1025 description 1026 "Event type"; 1027 } 1028 uses nw-s:node-ref; 1029 uses l3t:l3-unicast-topology-type; 1030 uses l3t:l3-node-attributes; 1031 } 1032 notification l3-link-event { 1033 description 1034 "Notification event for L3 link"; 1035 leaf l3-event-type { 1036 type l3t:l3-event-type; 1037 description 1038 "Event type"; 1039 } 1040 uses nt-s:link-ref; 1041 uses l3t:l3-unicast-topology-type; 1042 uses l3t:l3-link-attributes; 1043 } 1044 notification l3-prefix-event { 1045 description 1046 "Notification event for L3 prefix"; 1047 leaf l3-event-type { 1048 type l3t:l3-event-type; 1049 description 1050 "Event type"; 1051 } 1052 uses nw-s:node-ref; 1053 uses l3t:l3-unicast-topology-type; 1054 container prefix { 1055 description 1056 "Containing L3 prefix attributes"; 1057 uses l3t:l3-prefix-attributes; 1058 } 1059 } 1060 notification termination-point-event { 1061 description 1062 "Notification event for L3 termination point"; 1063 leaf l3-event-type { 1064 type l3t:l3-event-type; 1065 description 1066 "Event type"; 1067 } 1068 uses nt-s:tp-ref; 1069 uses l3t:l3-unicast-topology-type; 1070 uses l3t:l3-termination-point-attributes; 1071 } 1072 } 1074 1076 Appendix B. Extending the Model 1078 The model can be extended for specific Layer 3 Unicast types. 1079 Examples include OSPF and IS-IS topologies. In the following, one 1080 additional YANG module is introduced that define simple topology 1081 model for OSPF. This module is intended to serve as an example that 1082 illustrates how the general topology model can be refined across 1083 multiple levels. It does not constitute full-fledged OSPF topology 1084 model which may be more comprehensive and refined than the model that 1085 is described here. 1087 B.1. Example OSPF Topology 1089 B.1.1. Model Overview 1091 The following model shows how the Layer 3 Unicast topology model can 1092 be extended to cover OSFP topologies. For this purpose, a set of 1093 augmentations are introduced in a separate YANG module, "example- 1094 ietf-ospf-topology", whose structure is depicted in the following 1095 diagram. As before, the notation syntax follows 1096 [I-D.draft-ietf-netmod-yang-tree-diagrams]. 1098 module: example-ietf-ospf-topology 1099 augment /nw:networks/nw:network/nw:network-types/l3t:l3-unicast-topology: 1100 +--rw ospf! 1101 augment /nw:networks/nw:network/l3t:l3-topology-attributes: 1102 +--rw ospf-topology-attributes 1103 +--rw area-id? area-id-type 1104 augment /nw:networks/nw:network/nw:node/l3t:l3-node-attributes: 1105 +--rw ospf-node-attributes 1106 +--rw (router-type)? 1107 | +--:(abr) 1108 | | +--rw abr? empty 1109 | +--:(asbr) 1110 | | +--rw asbr? empty 1111 | +--:(internal) 1112 | | +--rw internal? empty 1113 | +--:(pseudonode) 1114 | +--rw pseudonode? empty 1115 +--rw dr-interface-id? uint32 1116 augment /nw:networks/nw:network/nt:link/l3t:l3-link-attributes: 1117 +--rw ospf-link-attributes 1118 augment /l3t:l3-node-event: 1119 +---- ospf! 1120 +---- ospf-node-attributes 1121 +---- (router-type)? 1122 | +--:(abr) 1123 | | +---- abr? empty 1124 | +--:(asbr) 1125 | | +---- asbr? empty 1126 | +--:(internal) 1127 | | +---- internal? empty 1128 | +--:(pseudonode) 1129 | +---- pseudonode? empty 1130 +---- dr-interface-id? uint32 1131 augment /l3t:l3-link-event: 1132 +---- ospf! 1133 +---- ospf-link-attributes 1135 The module augments "ietf-l3-unicast-topology" as follows: 1137 o A new topology type for an OSPF topology is introduced. 1139 o Additional topology attributes are defined in a new grouping which 1140 augments l3-topology-attributes of the ietf-l3-unicast-topology 1141 module. The attributes include an OSPF area-id identifying the 1142 OSPF area. 1144 o Additional data objects for nodes are introduced by augmenting the 1145 l3-node-attributes of the l3-unicast-topology module. New objects 1146 include router-type and dr-interface-id for pseudonodes. 1148 o Links are augmented with ospf link attributes. 1150 In addition, the module extends notifications for events concerning 1151 Layer 3 nodes and links with OSPF attributes. 1153 It should be noted that the model defined here represents topology 1154 and is intended as an example. It does not define how to configure 1155 OSPF routers or interfaces. 1157 B.1.2. OSPF Topology YANG Module 1159 The OSPF Topology YANG Module is specified below. As mentioned, the 1160 module is intended as an example for how the Layer 3 Unicast topology 1161 model can be extended to cover OSFP topologies, but it is not 1162 normative. Accordingly, the module is not delimited with CODE BEGINS 1163 and CODE ENDS tags. 1165 file "example-ietf-ospf-topology@2017-10-25.yang" 1166 module example-ietf-ospf-topology { 1167 yang-version 1.1; 1168 namespace "urn:ietf:params:xml:ns:yang:example-ietf-ospf-topology"; 1169 prefix "ospft"; 1170 import ietf-yang-types { 1171 prefix "yang"; 1172 } 1173 import ietf-network { 1174 prefix "nw"; 1175 } 1176 import ietf-network-topology { 1177 prefix "nt"; 1178 } 1179 import ietf-l3-unicast-topology { 1180 prefix "l3t"; 1181 } 1182 organization 1183 "IETF I2RS (Interface to the Routing System) Working Group"; 1184 contact 1185 "WG Web: 1186 WG List: 1187 Editor: Alexander Clemm 1188 1189 Editor: Jan Medved 1190 1191 Editor: Robert Varga 1192 1193 Editor: Xufeng Liu 1194 1195 Editor: Nitin Bahadur 1196 1197 Editor: Hariharan Ananthakrishnan 1198 "; 1199 description 1200 "This module defines a model for OSPF network topologies. 1201 Copyright (c) 2017 IETF Trust and the persons identified as 1202 authors of the code. All rights reserved. 1203 Redistribution and use in source and binary forms, with or 1204 without modification, is permitted pursuant to, and subject 1205 to the license terms contained in, the Simplified BSD License 1206 set forth in Section 4.c of the IETF Trust's Legal Provisions 1207 Relating to IETF Documents 1208 (http://trustee.ietf.org/license-info). 1209 This version of this YANG module is part of 1210 draft-ietf-i2rs-yang-l3-topology-12; 1211 see the RFC itself for full legal notices. 1212 NOTE TO RFC EDITOR: Please replace above reference to 1213 draft-ietf-i2rs-yang-l3-topology-12 with RFC 1214 number when published (i.e. RFC xxxx)."; 1215 revision "2017-10-25" { 1216 description 1217 "Initial revision. 1218 NOTE TO RFC EDITOR: Please replace the following reference 1219 to draft-ietf-i2rs-yang-l3-topology-12 with 1220 RFC number when published (i.e. RFC xxxx)."; 1221 reference 1222 "draft-ietf-i2rs-yang-l3-topology-12"; 1223 } 1224 typedef area-id-type { 1225 type yang:dotted-quad; 1226 description 1227 "Area ID type."; 1228 } 1229 grouping ospf-topology-type { 1230 description 1231 "Identifies the OSPF topology type."; 1232 container ospf { 1233 presence "indiates OSPF Topology"; 1234 description 1235 "Its presence identifies the OSPF topology type."; 1236 } 1237 } 1238 augment "/nw:networks/nw:network/nw:network-types/" 1239 + "l3t:l3-unicast-topology" { 1240 description 1241 "Defines the OSPF topology type."; 1242 uses ospf-topology-type; 1243 } 1244 augment "/nw:networks/nw:network/l3t:l3-topology-attributes" { 1245 when "../nw:network-types/l3t:l3-unicast-topology/ospf" { 1246 description 1247 "Augment only for OSPF topology"; 1248 } 1249 description 1250 "Augment topology configuration"; 1251 container ospf-topology-attributes { 1252 description 1253 "Containing topology attributes"; 1254 leaf area-id { 1255 type area-id-type; 1256 description 1257 "OSPF area ID"; 1258 } 1259 } 1260 } 1261 augment "/nw:networks/nw:network/nw:node/l3t:l3-node-attributes" { 1262 when "../../nw:network-types/l3t:l3-unicast-topology/ospf" { 1263 description 1264 "Augment only for OSPF topology"; 1265 } 1266 description 1267 "Augment node configuration"; 1268 uses ospf-node-attributes; 1269 } 1270 augment "/nw:networks/nw:network/nt:link/l3t:l3-link-attributes" { 1271 when "../../nw:network-types/l3t:l3-unicast-topology/ospf" { 1272 description 1273 "Augment only for OSPF topology"; 1274 } 1275 description 1276 "Augment link configuration"; 1277 uses ospf-link-attributes; 1278 } 1279 grouping ospf-node-attributes { 1280 description 1281 "OSPF node scope attributes"; 1282 container ospf-node-attributes { 1283 description 1284 "Containing node attributes"; 1285 choice router-type { 1286 description 1287 "Indicates router type"; 1289 case abr { 1290 leaf abr { 1291 type empty; 1292 description 1293 "The node is ABR"; 1294 } 1295 } 1296 case asbr { 1297 leaf asbr { 1298 type empty; 1299 description 1300 "The node is ASBR"; 1301 } 1302 } 1303 case internal { 1304 leaf internal { 1305 type empty; 1306 description 1307 "The node is internal"; 1308 } 1309 } 1310 case pseudonode { 1311 leaf pseudonode { 1312 type empty; 1313 description 1314 "The node is pseudonode"; 1315 } 1316 } 1317 } 1318 leaf dr-interface-id { 1319 when "../pseudonode" { 1320 description 1321 "Valid only for pseudonode"; 1322 } 1323 type uint32; 1324 default "0"; 1325 description 1326 "For pseudonodes, DR interface-id"; 1327 } 1328 } 1329 } 1330 grouping ospf-link-attributes { 1331 description 1332 "OSPF link scope attributes"; 1333 container ospf-link-attributes { 1334 description 1335 "Containing OSPF link attributes"; 1336 } 1338 } // ospf-link-attributes 1339 augment "/l3t:l3-node-event" { 1340 description 1341 "OSPF node event"; 1342 uses ospf-topology-type; 1343 uses ospft:ospf-node-attributes; 1344 } 1345 augment "/l3t:l3-link-event" { 1346 description 1347 "OSPF link event"; 1348 uses ospf-topology-type; 1349 uses ospft:ospf-link-attributes; 1350 } 1351 } 1353 Authors' Addresses 1355 Alexander Clemm 1356 Huawei 1358 EMail: ludwig@clemm.org 1360 Jan Medved 1361 Cisco 1363 EMail: jmedved@cisco.com 1365 Robert Varga 1366 Pantheon Technologies SRO 1368 EMail: robert.varga@pantheon.sk 1370 Xufeng Liu 1371 Ericsson 1373 EMail: xliu@kuatrotech.com 1375 Hariharan Ananthakrishnan 1376 Packet Design 1378 EMail: hari@packetdesign.com 1379 Nitin Bahadur 1380 Bracket Computing 1382 EMail: nitin_bahadur@yahoo.com