idnits 2.17.1 draft-ietf-i2rs-yang-l2-network-topology-09.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 are 2 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 18, 2019) is 1707 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: 'RFC5246' is defined on line 979, but no explicit reference was found in the text == Unused Reference: 'RFC6536' is defined on line 993, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE802.1Q' ** Obsolete normative reference: RFC 6326 (Obsoleted by RFC 7176) ** Downref: Normative reference to an Informational RFC: RFC 7348 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Dong 3 Internet-Draft X. Wei 4 Intended status: Standards Track Q. Wu 5 Expires: February 19, 2020 Huawei 6 M. Boucadair 7 Orange 8 A. Liu 9 Tecent 10 August 18, 2019 12 A YANG Data Model for Layer-2 Network Topologies 13 draft-ietf-i2rs-yang-l2-network-topology-09 15 Abstract 17 This document defines a YANG data model for Layer 2 network 18 topologies. 20 Editorial Note (To be removed by RFC Editor) 22 Please update these statements within the document with the RFC 23 number to be assigned to this document: 25 o "This version of this YANG module is part of RFC XXXX;" 27 o "RFC XXXX: A YANG Data Model for Layer-2 Network Topologies"; 29 o reference: RFC XXXX 31 Please update the "revision" date of the YANG module. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at https://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on February 19, 2020. 50 Copyright Notice 52 Copyright (c) 2019 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 3. Layer 2 Topology Model . . . . . . . . . . . . . . . . . . . 3 70 4. Layer 2 Topology YANG Module . . . . . . . . . . . . . . . . 6 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 18 73 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 75 8.1. Normative References . . . . . . . . . . . . . . . . . . 19 76 8.2. Informative References . . . . . . . . . . . . . . . . . 21 77 Appendix A. Companion YANG Module for Non-NMDA Compliant 78 Implementations . . . . . . . . . . . . . . . . . . 22 79 Appendix B. An Example . . . . . . . . . . . . . . . . . . . . . 26 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 82 1. Introduction 84 [RFC8345] defines the YANG [RFC6020] [RFC7950] data models of the 85 abstract (generic) network and network topology. Such models can be 86 augmented with technology-specific details to build more specific 87 topology models. 89 This document defines the YANG data model for Layer 2 network 90 topologies by augmenting the generic network and network topology 91 data models with L2 specific topology attributes. A sample example 92 is provided in Appendix B. 94 This document uses the common YANG types defined in [RFC6991] and 95 adopts the Network Management Datastore Architecture (NMDA 96 [RFC8342]). 98 The terminology for describing YANG modules is defined in [RFC7950]. 99 The meanings of the symbols used in the tree diagram are defined in 100 [RFC8340]. 102 2. Terminology 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 106 "OPTIONAL" in this document are to be interpreted as described in BCP 107 14 [RFC2119] [RFC8174] when, and only when, they appear in all 108 capitals, as shown here. 110 3. Layer 2 Topology Model 112 The Layer 2 network topology YANG module is designed to be generic 113 and applicable to Layer 2 networks built with different L2 114 technologies. It can be used to describe both the physical and the 115 logical (virtual) L2 network topologies. 117 The relationship between the Layer 2 topology module and the generic 118 network and network topology module is shown in Figure 1. In order 119 to represent a Layer 2 network topology, the generic network and 120 topology models are augmented with Layer-2 specific information, such 121 as the identifiers, descriptions, attributes and states of the 122 Layer-2 networks, nodes, links and termination points. Some of the 123 information may be collected via Link Layer Discovery Protocol (LLDP) 124 or other Layer-2 protocols, and some of them may be locally 125 configured. 127 +---------------------+ 128 | ietf-network | 129 +----------^----------+ 130 | 131 | 132 +---------------------+ 133 |ietf-network-topology| 134 +----------^----------+ 135 | 136 | 137 +----------^----------+ 138 | ietf-l2-topology | 139 +---------------------+ 141 Figure 1: L2-topology YANG Module Structure 143 The structure of "ietf-l2-topology" YANG module is depicted in the 144 following tree diagram: 146 module: ietf-l2-topology 147 augment /nw:networks/nw:network/nw:network-types: 148 +--rw l2-network! 149 augment /nw:networks/nw:network: 150 +--rw l2-network-attributes 151 +--rw name? string 152 +--rw flag* l2-flag-type 153 augment /nw:networks/nw:network/nw:node: 154 +--rw l2-node-attributes 155 +--rw name? string 156 +--rw description? string 157 +--rw management-address* inet:ip-address 158 +--rw sys-mac-address? yang:mac-address 159 +--rw management-vid? vlan {VLAN}? 160 +--rw flag* node-flag-type 161 augment /nw:networks/nw:network/nt:link: 162 +--rw l2-link-attributes 163 +--rw name? string 164 +--rw flag* link-flag-type 165 +--rw rate? decimal64 166 +--rw delay? uint32 167 +--rw srlg* uint32 168 augment /nw:networks/nw:network/nw:node/nt:termination-point: 169 +--rw l2-termination-point-attributes 170 +--rw description? string 171 +--rw maximum-frame-size? uint32 172 +--rw (l2-termination-point-type)? 173 | +--:(ethernet) 174 | | +--rw mac-address? yang:mac-address 175 | | +--rw eth-encapsulation? identityref 176 | | +--rw port-vlan-id? vlan {VLAN}? 177 | | +--rw vlan-id-name* [vlan-id] {VLAN}? 178 | | +--rw vlan-id vlan 179 | | +--rw vlan-name? string 180 | +--:(legacy) 181 | +--rw layer-2-address? yang:phys-address 182 | +--rw encapsulation? identityref 183 +--ro tp-state? enumeration 184 notifications: 185 +---n l2-node-event 186 | +--ro event-type? 187 | +--ro node-ref? 188 | +--ro network-ref? 189 | +--ro l2-network! 190 | +--ro l2-node-attributes 191 +---n l2-link-event 192 | +--ro event-type? 193 | +--ro link-ref? 194 | +--ro network-ref? 195 | +--ro l2-network! 196 | +--ro l2-link-attributes 197 +---n l2-termination-point-event 198 +--ro event-type? 199 +--ro tp-ref? 200 +--ro node-ref? 201 +--ro network-ref? 202 +--ro l2-network! 203 +--ro l2-termination-point-attributes 205 The L2-topology module augments the generic 'ietf-network' and 'ietf- 206 network-topology' modules as follows: 208 o A new network type "l2-network-type" is introduced. This is 209 represented by a container object, and is inserted under the 210 "network-types" container of the generic 'ietf-network' module 211 defned in [RFC8345]. 213 o Additional network attributes are introduced in a grouping "l2- 214 network-attributes", which augments the "network" list of the 215 'ietf-network' module. The attributes include Layer-2 network 216 name and a set of flags. Each type of flag is represented by a 217 separate identity. 219 o Additional data objects for Layer-2 nodes are introduced by 220 augmenting the "node" list of the generic 'ietf-network' module. 221 New objects include Layer-2 node identifier, description, 222 management address, and a set of flags. 224 o Additional data objects for Layer-2 termination points are 225 introduced by augmenting the "termination-point" list of the 226 'ietf-network-topology' module defined in [RFC8345]. New objects 227 include Layer-2 termination point descriptions, Layer-2 228 termination point type specific attributes and Layer-2 termination 229 point states. 231 o Links in the 'ietf-network-topology' module are augmented as well 232 with a set of Layer-2 parameters, allowing to associate a link 233 with a name, a set of Layer-2 link attributes and flags. 235 o The optional L2 technology specific attributes are introduced in 236 this module as Layer-2 features. 238 4. Layer 2 Topology YANG Module 240 This module uses the common YANG types defined in 241 [RFC6991][RFC7224][IEEE802.1Q] and types defined in [RFC8345], and it 242 references [RFC4761][RFC4762][RFC6325][RFC6326][RFC7348][RFC4202]. 244 file "ietf-l2-topology@2019-06-04.yang" 245 module ietf-l2-topology { 246 yang-version 1.1; 247 namespace "urn:ietf:params:xml:ns:yang:ietf-l2-topology"; 248 prefix "l2t"; 250 import ietf-network { 251 prefix "nw"; 252 reference 253 "RFC 8345: A YANG Data Model for Network Topologies"; 254 } 255 import ietf-network-topology { 256 prefix "nt"; 257 reference 258 "RFC 8345: A YANG Data Model for Network Topologies"; 259 } 260 import ietf-inet-types { 261 prefix "inet"; 262 reference "Section 4 of RFC 6991"; 263 } 264 import ietf-yang-types { 265 prefix "yang"; 266 reference "Section 3 of RFC 6991"; 267 } 268 import iana-if-type { 269 prefix ift; 270 reference 271 "RFC 7224: IANA Interface Type YANG Module"; 272 } 273 import ieee802-dot1q-types { 274 prefix dot1q-type; 275 reference 276 "IEEE Std 802.1Q-2017: Virtual Bridged Local Area Networks."; 277 } 278 organization 279 "IETF I2RS (Interface to the Routing System) Working Group"; 280 contact 281 "WG Web: 282 WG List: 283 Editor: Jie Dong 284 286 Editor: Xiugang Wei 287 289 Editor: Qin Wu 290 292 Editor: Mohamed Boucadair 293 295 Editor: Anders Liu 296 "; 298 description 299 "This module defines a basic model for 300 the layer-2 topology of a network. 302 Copyright (c) 2019 IETF Trust and the persons identified as 303 authors of the code. All rights reserved. 305 Redistribution and use in source and binary forms, with or 306 without modification, is permitted pursuant to, and subject 307 to the license terms contained in, the Simplified BSD License 308 set forth in Section 4.c of the IETF Trust's Legal Provisions 309 Relating to IETF Documents 310 (http://trustee.ietf.org/license-info). 312 This version of this YANG module is part of 313 RFC XXXX: A YANG Data Model for Layer-2 Network Topologies 314 see the RFC itself for full legal notices."; 316 revision "2019-06-04" { 317 description "Initial revision"; 318 reference 319 "RFC XXXX: A YANG Data Model for Layer-2 Network Topologies"; 320 } 322 /* 323 * Typedefs 324 */ 326 typedef trill-nickname { 327 type uint16; 328 description "TRILL Nickname"; 329 reference 330 "RFC 6326: Transparent Interconnection of Lots 331 of Links (TRILL) Use of IS-IS"; 332 } 333 typedef vni { 334 type uint32 { 335 range "1..16777215"; 336 } 337 description "VxLAN Network Identifier"; 338 reference 339 "RFC 7348: Virtual eXtensible Local Area 340 Network (VXLAN): A Framework for Overlaying 341 Virtualized Layer 2 Networks over Layer 3 342 Networks"; 343 } 345 typedef l2-flag-type { 346 type identityref { 347 base "flag-identity"; 348 } 349 description "Base type for l2 flags"; 350 } 351 typedef node-flag-type { 352 type identityref { 353 base "flag-identity"; 354 } 355 description "Node flag attributes"; 356 } 357 typedef link-flag-type { 358 type identityref { 359 base "flag-identity"; 360 } 361 description "Link flag attributes"; 362 } 364 typedef l2-network-event-type { 365 type enumeration { 366 enum "add" { 367 value 0; 368 description "An L2 node or link or termination-point 369 has been added"; 370 } 371 enum "remove" { 372 value 1; 373 description "An L2 node or link or termination-point 374 has been removed"; 375 } 376 enum "update" { 377 value 2; 378 description "An L2 node or link or termination-point 379 has been updated"; 380 } 382 } 383 description "l2 network event type for notifications"; 384 } // l2-topology-event-type 386 /* 388 * Features 389 */ 391 feature VLAN { 392 description 393 "Indicates that the system supports the 394 vlan functions (also known as an IEEE 802.1Q tag)."; 395 } 397 feature QinQ { 398 description 399 "Indicates that the system supports the 400 qinq functions (also known as IEEE 802.1ad double tag)"; 401 } 403 feature PBB { 404 description 405 "Indicates that the device supports the 406 provider-backbone-bridging functions developed 407 in IEEE 802.1ah."; 408 } 410 feature VPLS { 411 description 412 "Indicates that the device supports the 413 VPLS functions."; 414 reference 415 "RFC 4761: Virtual Private LAN Service (VPLS) Using 416 BGP for Auto-Discovery and Signaling 417 RFC 4762: Virtual Private LAN Service (VPLS) Using 418 Label Distribution Protocol (LDP) Signaling"; 419 } 421 feature TRILL { 422 description 423 "Indicates that the device supports the 424 TRILL functions."; 425 reference 426 "RFC 6325: Routing Bridges (RBridges): Base Protocol 427 Specification"; 428 } 429 feature VXLAN { 430 description 431 "Indicates that the device supports the 432 VXLAN functions."; 433 reference 434 "RFC 7348: Virtual eXtensible Local Area Network (VXLAN): 435 A Framework for Overlaying Virtualized Layer 2 Networks 436 over Layer 3 Networks"; 437 } 439 /* 440 * Identities 441 */ 443 identity flag-identity { 444 description "Base type for flags."; 445 } 447 identity eth-encapsulation-type { 448 base ift:iana-interface-type; 449 description 450 "Base identity from which specific Ethernet 451 encapsulation types are derived."; 452 reference 453 "RFC 7224: IANA Interface Type YANG Module"; 454 } 456 identity ethernet { 457 base eth-encapsulation-type; 458 description 459 "Native Ethernet encapsulation."; 460 } 462 identity vlan { 463 base eth-encapsulation-type; 464 description 465 "VLAN encapsulation."; 466 } 468 identity qinq { 469 base eth-encapsulation-type; 470 description 471 "QinQ encapsulation."; 472 } 474 identity pbb { 475 base eth-encapsulation-type; 476 description 477 "PBB encapsulation."; 478 } 480 identity trill { 481 base eth-encapsulation-type; 482 description 483 "TRILL encapsulation."; 484 } 486 identity vpls { 487 base eth-encapsulation-type; 488 description 489 "Ethernet VPLS interface encapsulation."; 490 } 492 identity vxlan { 493 base eth-encapsulation-type; 494 description 495 "VXLAN MAC in UDP encapsulation."; 496 } 498 /* 499 * Groupings 500 */ 502 grouping l2-network-type { 503 description "Identify the topology type to be L2."; 504 container l2-network { 505 presence "indicates L2 Network"; 506 description 507 "The presence of the container node indicates 508 L2 Topology."; 509 } 510 } 512 grouping l2-network-attributes { 513 description "L2 Topology scope attributes"; 514 container l2-network-attributes { 515 description "Containing L2 network attributes"; 516 leaf name { 517 type string; 518 description "Name of the L2 network."; 519 } 521 leaf-list flag { 522 type l2-flag-type; 523 description "L2 network flags"; 525 } 526 } 527 } 529 grouping l2-node-attributes { 530 description "L2 node attributes"; 531 container l2-node-attributes { 532 description "Containing L2 node attributes"; 533 leaf name { 534 type string; 535 description "Node name."; 536 } 537 leaf description { 538 type string; 539 description "Node description."; 540 } 541 leaf-list management-address { 542 type inet:ip-address; 543 description "System management address."; 544 } 545 leaf sys-mac-address { 546 type yang:mac-address; 547 description "System MAC-address."; 548 } 549 leaf management-vid { 550 if-feature VLAN; 551 type dot1q-type:vlanid; 552 description "System management VID."; 553 } 554 leaf-list flag { 555 type node-flag-type; 556 description "Node operational flags."; 557 } 558 } 559 } // grouping l2-node-attributes 561 grouping l2-link-attributes { 562 description "L2 link attributes"; 563 container l2-link-attributes { 564 description "Containing L2 link attributes."; 565 leaf name { 566 type string; 567 description "Link name."; 568 } 569 leaf-list flag { 570 type link-flag-type; 571 description "Link flags."; 572 } 573 leaf rate { 574 type decimal64 { 575 fraction-digits 2; 576 } 577 description "Link rate."; 579 } 580 leaf delay { 581 type uint32; 582 description "Link delay in microseconds."; 583 } 584 leaf-list srlg { 585 type uint32; 586 description 587 "List of Shared Risk Link Groups 588 this link belongs to."; 589 reference 590 "RFC 4202: Routing Extensions in Support of 591 Generalized Multi-Protocol Label Switching 592 (GMPLS)"; 593 } 594 } 595 } // grouping l2-link-attributes 597 grouping l2-termination-point-attributes { 598 description "L2 termination point attributes"; 599 container l2-termination-point-attributes { 600 description "Containing L2 TP attributes"; 601 leaf description { 602 type string; 603 description "Port description."; 604 } 606 leaf maximum-frame-size { 607 type uint32; 608 description "Maximum frame size."; 609 } 611 choice l2-termination-point-type { 612 description 613 "Indicates termination-point type 614 specific attributes."; 615 case ethernet { 616 leaf mac-address { 617 type yang:mac-address; 618 description "Interface MAC address."; 619 } 620 leaf eth-encapsulation { 621 type identityref { 622 base eth-encapsulation-type; 623 } 624 description 625 "Encapsulation type of this 626 ternimation point."; 627 } 629 leaf port-vlan-id { 630 if-feature VLAN; 631 type dot1q-type:vlanid; 632 description "Port VLAN ID is the VLAN id that 633 will be assigned to any untagged frames entering 634 the switch on the specific port."; 635 } 637 list vlan-id-name { 638 if-feature VLAN; 639 key "vlan-id"; 640 description "Interface configured VLANs."; 641 leaf vlan-id { 642 type dot1q-type:vlanid; 643 description "VLAN ID."; 644 } 645 leaf vlan-name { 646 type string; 647 description "VLAN name."; 648 } 649 } 650 } //case ethernet 652 case legacy { 653 leaf layer-2-address { 654 type yang:phys-address; 655 description "Interface Layer 2 address."; 656 } 658 leaf encapsulation { 659 type identityref { 660 base ift:iana-interface-type; 661 } 662 description 663 "Other legacy encapsulation type of this termination point."; 664 } 665 } //case legacy such as atm, ppp, hdlc,etc. 667 } //choice termination-point-type 668 leaf tp-state { 669 type enumeration { 670 enum in-use { 671 value 0; 672 description 673 "the termination point is in forwarding state."; 674 } 675 enum blocking { 676 value 1; 677 description 678 "the termination point is in blocking state."; 679 } 680 enum down { 681 value 2; 682 description 683 "the termination point is in down state."; 684 } 685 enum others { 686 value 3; 687 description 688 "the termination point is in other state."; 689 } 690 } 691 config false; 692 description "State of the termination point"; 693 } 694 } 695 } // grouping l2-termination-point-attributes 697 /* 698 * Data nodes 699 */ 701 augment "/nw:networks/nw:network/nw:network-types" { 702 description 703 "Introduce new network type for L2 topology."; 704 uses l2-network-type; 705 } 707 augment "/nw:networks/nw:network" { 708 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 709 description 710 "Augmentation parameters apply only for networks 711 with L2 topology."; 712 } 713 description 714 "Configuration parameters for the L2 network 715 as a whole"; 717 uses l2-network-attributes; 718 } 720 augment "/nw:networks/nw:network/nw:node" { 721 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 722 description 723 "Augmentation parameters apply only for networks 724 with L2 topology."; 725 } 726 description 727 "Configuration parameters for L2 at the node 728 level."; 729 uses l2-node-attributes; 730 } 732 augment "/nw:networks/nw:network/nt:link" { 733 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 734 description 735 "Augmentation parameters apply only for networks 736 with L2 topology."; 737 } 738 description "Augment L2 topology link information"; 739 uses l2-link-attributes; 740 } 742 augment "/nw:networks/nw:network/nw:node/nt:termination-point" { 743 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 744 description 745 "Augmentation parameters apply only for networks 746 with L2 topology."; 747 } 748 description 749 "Augment L2 topology termination point information."; 750 uses l2-termination-point-attributes; 751 } 753 /* 754 * Notifications 755 */ 757 notification l2-node-event { 758 description "Notification event for L2 node"; 759 leaf event-type { 760 type l2-network-event-type; 761 description "Event type."; 762 } 763 uses nw:node-ref; 764 uses l2-network-type; 765 uses l2-node-attributes; 766 } 768 notification l2-link-event { 769 description "Notification event for L2 link."; 770 leaf event-type { 771 type l2-network-event-type; 772 description "Event type"; 773 } 774 uses nt:link-ref; 775 uses l2-network-type; 776 uses l2-link-attributes; 777 } 779 notification l2-termination-point-event { 780 description "Notification event for L2 termination point."; 781 leaf event-type { 782 type l2-network-event-type; 783 description "Event type"; 784 } 785 uses nt:tp-ref; 786 uses l2-network-type; 787 uses l2-termination-point-attributes; 788 } 789 } // module l2-topology 790 792 5. IANA Considerations 794 This document requests IANA to register the following URIs in the 795 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 797 URI: urn:ietf:params:xml:ns:yang:ietf-l2-topology 798 Registrant Contact: The IESG. 799 XML: N/A; the requested URI is an XML namespace. 801 URI: urn:ietf:params:xml:ns:yang:ietf-l2-topology-state 802 Registrant Contact: The IESG. 803 XML: N/A; the requested URI is an XML namespace. 805 This document requests IANA to register the following YANG modules in 806 the "YANG Module Names" subregistry [RFC6020] within the "YANG 807 Parameters" registry. 809 name: ietf-l2-topology 810 namespace: urn:ietf:params:xml:ns:yang:ietf-l2-topology 811 prefix: l2t 812 reference: RFC XXXX 814 name: ietf-l2-topology-state 815 namespace: urn:ietf:params:xml:ns:yang:ietf-l2-topology-state 816 prefix: l2t-s 817 reference: RFC XXXX 819 These modules are not maintained by IANA. 821 6. Security Considerations 823 The YANG module specified in this document defines a schema for data 824 that is designed to be accessed via network management protocols such 825 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 826 is the secure transport layer, and the mandatory-to-implement secure 827 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 828 is HTTPS, and the mandatory-to-implement secure transport is TLS 829 [RFC8446]. 831 The Network Configuration Access Control Model (NACM) [RFC8341] 832 provides the means to restrict access for particular NETCONF or 833 RESTCONF users to a preconfigured subset of all available NETCONF or 834 RESTCONF protocol operations and content. 836 In general, Layer 2 network topologies are system-controlled and 837 provide ephemeral topology information. In an NMDA-complient server, 838 they are only part of which provides read-only access 839 to clients, they are less vulnerable. That said, the YANG module 840 does in principle allow information to be configurable. 842 The Layer 2 topology module define information that can be 843 configurable in certain instances, for example in the case of virtual 844 topologies that can be created by client applications. In such 845 cases, a malicious client could introduce topologies that are 846 undesired. Specifically, a malicious client could attempt to remove 847 or add a node, a link, a termination point, by creating or deleting 848 corresponding elements in the node, link, and termination point 849 lists, respectively. In the case of a topology that is learned, the 850 server will automatically prohibit such misconfiguration attempts. 851 In the case of a topology that is configured, i.e. whose origin is 852 "intended", the undesired configuration could become effective and be 853 reflected in the operational state datastore, leading to disruption 854 of services provided via this topology might be disrupted. For those 855 reasons, it is important that the NETCONF access control model is 856 vigorously applied to prevent topology misconfiguration by 857 unauthorized clients. 859 There are a number of data nodes defined in this YANG module that are 860 writable/creatable/deletable (i.e., config true, which is the 861 default). These data nodes may be considered sensitive or vulnerable 862 in some network environments. Write operations (e.g., edit-config) 863 to these data nodes without proper protection can have a negative 864 effect on network operations. These are the subtrees and data nodes 865 and their sensitivity/vulnerability in the ietf-network module: 867 o l2-network-attributes: A malicious client could attempt to 868 sabotage the configuration of any of the contained attributes, 869 such as the name or the flag data nodes. 871 o l2-node-attributes: A malicious client could attempt to sabotage 872 the configuration of important node attributes, such as the name 873 or the management-address. 875 o l2-link-attributes: A malicious client could attempt to sabotage 876 the configuration of important link attributes, such as the rate 877 or the delay data nodes. 879 o l2-termination-point-attributes: A malicious client could attempt 880 to sabotage the configuration of important termination point 881 attributes, such as the maximum-frame-size. 883 7. Acknowledgements 885 The authors would like to acknowledge the comments and suggestions 886 received from Susan Hares, Alia Atlas, Juergen Schoenwaelder, Mach 887 Chen, Alexander Clemm and Sriganesh Kini. 889 8. References 891 8.1. Normative References 893 [IEEE802.1Q] 894 "Media Access Control (MAC) Bridges and Virtual Bridged 895 Local Area Networks", IEEE Std 802.1Q-2018, July 2018. 897 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 898 Requirement Levels", BCP 14, RFC 2119, 899 DOI 10.17487/RFC2119, March 1997, 900 . 902 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 903 DOI 10.17487/RFC3688, January 2004, 904 . 906 [RFC4202] Kompella, K., Ed. and Y. Rekhter, Ed., "Routing Extensions 907 in Support of Generalized Multi-Protocol Label Switching 908 (GMPLS)", RFC 4202, DOI 10.17487/RFC4202, October 2005, 909 . 911 [RFC4761] Kompella, K., Ed. and Y. Rekhter, Ed., "Virtual Private 912 LAN Service (VPLS) Using BGP for Auto-Discovery and 913 Signaling", RFC 4761, DOI 10.17487/RFC4761, January 2007, 914 . 916 [RFC4762] Lasserre, M., Ed. and V. Kompella, Ed., "Virtual Private 917 LAN Service (VPLS) Using Label Distribution Protocol (LDP) 918 Signaling", RFC 4762, DOI 10.17487/RFC4762, January 2007, 919 . 921 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 922 the Network Configuration Protocol (NETCONF)", RFC 6020, 923 DOI 10.17487/RFC6020, October 2010, 924 . 926 [RFC6325] Perlman, R., Eastlake 3rd, D., Dutt, D., Gai, S., and A. 927 Ghanwani, "Routing Bridges (RBridges): Base Protocol 928 Specification", RFC 6325, DOI 10.17487/RFC6325, July 2011, 929 . 931 [RFC6326] Eastlake, D., Banerjee, A., Dutt, D., Perlman, R., and A. 932 Ghanwani, "Transparent Interconnection of Lots of Links 933 (TRILL) Use of IS-IS", RFC 6326, DOI 10.17487/RFC6326, 934 July 2011, . 936 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 937 RFC 6991, DOI 10.17487/RFC6991, July 2013, 938 . 940 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 941 RFC 7224, DOI 10.17487/RFC7224, May 2014, 942 . 944 [RFC7348] Mahalingam, M., Dutt, D., Duda, K., Agarwal, P., Kreeger, 945 L., Sridhar, T., Bursell, M., and C. Wright, "Virtual 946 eXtensible Local Area Network (VXLAN): A Framework for 947 Overlaying Virtualized Layer 2 Networks over Layer 3 948 Networks", RFC 7348, DOI 10.17487/RFC7348, August 2014, 949 . 951 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 952 RFC 7950, DOI 10.17487/RFC7950, August 2016, 953 . 955 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 956 RFC 7951, DOI 10.17487/RFC7951, August 2016, 957 . 959 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 960 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 961 May 2017, . 963 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 964 Access Control Model", STD 91, RFC 8341, 965 DOI 10.17487/RFC8341, March 2018, 966 . 968 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 969 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 970 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 971 2018, . 973 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 974 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 975 . 977 8.2. Informative References 979 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 980 (TLS) Protocol Version 1.2", RFC 5246, 981 DOI 10.17487/RFC5246, August 2008, 982 . 984 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 985 and A. Bierman, Ed., "Network Configuration Protocol 986 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 987 . 989 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 990 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 991 . 993 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 994 Protocol (NETCONF) Access Control Model", RFC 6536, 995 DOI 10.17487/RFC6536, March 2012, 996 . 998 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 999 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1000 . 1002 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1003 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1004 . 1006 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1007 and R. Wilton, "Network Management Datastore Architecture 1008 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1009 . 1011 Appendix A. Companion YANG Module for Non-NMDA Compliant 1012 Implementations 1014 The YANG module ietf-l2-topology defined in this document augments 1015 two modules, ietf-network and ietf-network-topology, that are 1016 designed to be used in conjunction with implementations that support 1017 the Network Management Datastore Architecture (NMDA) defined in 1018 [RFC8342]. In order to allow implementations to use the model even 1019 in cases when NMDA is not supported, a set of companion modules have 1020 been defined that represent a state model of networks and network 1021 topologies, ietf- network-state and ietf-network-topology-state, 1022 respectively. 1024 In order to be able to use the model for layer 2 topologies defined 1025 in this document in conjunction with non-NMDA compliant 1026 implementations, a corresponding companion module is defined that 1027 represent the operational state of layer 2 network topologies. The 1028 module ietf-l2-topology-state mirrors the module ietf-l2-topology 1029 defined earlier in this document. However, it augments ietf-network- 1030 state and ietf-network-topology-state (instead of ietf-network and 1031 ietf-network-topology) and all its data nodes are non-configurable. 1033 The companion module ietf-l2-topology SHOULD NOT be supported by 1034 implementations that support NMDA. It is for this reason that this 1035 module is defined in the informative Appendix. 1037 As the structure of this modules mirrors that of its underlying 1038 modules, the YANG tree is not depicted separately. 1040 file "ietf-l2-topology-state@2019-06-04.yang" 1041 module ietf-l2-topology-state { 1042 yang-version 1.1; 1043 namespace "urn:ietf:params:xml:ns:yang:ietf-l2-topology-state"; 1044 prefix "l2t-s"; 1045 import ietf-network-state { 1046 prefix "nw-s"; 1047 reference 1048 "RFC 8345: A YANG Data Model for Network Topologies"; 1049 } 1051 import ietf-network-topology-state { 1052 prefix "nt-s"; 1053 reference 1054 "RFC 8345: A YANG Data Model for Network Topologies"; 1055 } 1057 import ietf-l2-topology { 1058 prefix "l2t"; 1059 reference 1060 "RFC XXXX: A YANG Data Model for Layer-2 Network Topologies"; 1061 } 1063 organization 1064 "IETF I2RS (Interface to the Routing System) Working Group"; 1065 contact 1066 "WG Web: 1067 WG List: 1068 Editor: Jie Dong 1069 1070 Editor: Xiugang Wei 1071 1072 Editor: Qin Wu 1073 1074 Editor: Mohamed Boucadair 1075 1076 Editor: Anders Liu 1077 "; 1079 description 1080 " This module defines a model for Layer 2 Network Topology 1081 state, representing topology that either is learned or 1082 results from applying topology that has been configured per 1083 the 'ietf-l2-topology' model, mirroring the 1084 corresponding data nodes in this model. 1086 This model mirrors 'ietf-l2-topology' but contains only 1087 read-only state data. The model is not needed when the 1088 underlying implementation infrastructure supports the Network 1089 Management Datastore Architecture (NMDA). 1091 Copyright (c) 2018 IETF Trust and the persons identified as 1092 authors of the code. All rights reserved. 1094 Redistribution and use in source and binary forms, with or 1095 without modification, is permitted pursuant to, and subject 1096 to the license terms contained in, the Simplified BSD License 1097 set forth in Section 4.c of the IETF Trust's Legal Provisions 1098 Relating to IETF Documents 1099 (http://trustee.ietf.org/license-info). 1101 This version of this YANG module is part of 1102 RFC XXXX: A YANG Data Model for Layer-2 Network Topologies 1103 see the RFC itself for full legal notices."; 1105 revision "2019-06-04" { 1106 description "Initial revision"; 1107 reference "RFC XXXX: A YANG Data Model for Layer-2 Network Topologies"; 1108 } 1110 /* 1111 * Data nodes 1112 */ 1113 augment "/nw-s:networks/nw-s:network/nw-s:network-types" { 1114 description 1115 "Introduce new network type for L2 topology"; 1116 uses l2t:l2-network-type; 1117 } 1119 augment "/nw-s:networks/nw-s:network" { 1120 when "/nw-s:networks/nw-s:network/nw-s:network-types/"+ 1121 "l2t-s:l2-network" { 1122 description 1123 "Augmentation parameters apply only for networks 1124 with L2 topology"; 1125 } 1126 description 1127 "Configuration parameters for the L2 network 1128 as a whole"; 1129 uses l2t:l2-network-attributes; 1130 } 1132 augment "/nw-s:networks/nw-s:network/nw-s:node" { 1133 when "../nw-s:network-types/l2t-s:l2-network" { 1134 description 1135 "Augmentation parameters apply only for networks 1136 with L2 topology"; 1137 } 1138 description 1139 "Configuration parameters for L2 at the node 1140 level"; 1141 uses l2t:l2-node-attributes; 1143 } 1145 augment "/nw-s:networks/nw-s:network/nt-s:link" { 1146 when "../nw-s:network-types/l2t-s:l2-network" { 1147 description 1148 "Augmentation parameters apply only for networks 1149 with L2 topology"; 1150 } 1151 description "Augment L2 topology link information"; 1152 uses l2t:l2-link-attributes; 1153 } 1155 augment "/nw-s:networks/nw-s:network/nw-s:node/"+ 1156 "nt-s:termination-point" { 1157 when "../../nw-s:network-types/l2t-s:l2-network" { 1158 description 1159 "Augmentation parameters apply only for networks 1160 with L2 topology"; 1161 } 1162 description 1163 "Augment L2 topology termination point information"; 1164 uses l2t:l2-termination-point-attributes; 1165 } 1167 /* 1168 * Notifications 1169 */ 1171 notification l2-node-event { 1172 description "Notification event for L2 node"; 1173 leaf event-type { 1174 type l2t:l2-network-event-type; 1175 description "Event type"; 1176 } 1177 uses nw-s:node-ref; 1178 uses l2t:l2-network-type; 1179 uses l2t:l2-node-attributes; 1180 } 1182 notification l2-link-event { 1183 description "Notification event for L2 link"; 1184 leaf event-type { 1185 type l2t:l2-network-event-type; 1186 description "Event type"; 1187 } 1188 uses nt-s:link-ref; 1189 uses l2t:l2-network-type; 1190 uses l2t:l2-link-attributes; 1192 } 1194 notification l2-termination-point-event { 1195 description "Notification event for L2 termination point"; 1196 leaf event-type { 1197 type l2t:l2-network-event-type; 1198 description "Event type"; 1199 } 1200 uses nt-s:tp-ref; 1201 uses l2t:l2-network-type; 1202 uses l2t:l2-termination-point-attributes; 1203 } 1204 } // module l2-topology-state 1205 1207 Appendix B. An Example 1209 This section contains an example of an instance data tree in JSON 1210 encoding [RFC7951]. The example instantiates "ietf-l2- topology" for 1211 the topology that is depicted in the following diagram. There are 1212 three nodes: D1, D2, and D3. D1 has three termination points: 1-0-1, 1213 1-2-1, and 1-3-1. D2 has three termination points as well: 2-1-1, 1214 2-0-1, and 2-3-1. D3 has two termination points: 3-1-1 and 3-2-1. 1215 In addition, there are six links, two between each pair of nodes, 1216 with one going in each direction. 1218 +------------+ +------------+ 1219 | D1 | | D2 | 1220 /-\ /-\ /-\ /-\ 1221 | | 1-0-1 | |---------------->| | 2-1-1 | | 1222 | | 1-2-1 | |<----------------| | 2-0-1 | | 1223 \-/ 1-3-1 \-/ \-/ 2-3-1 \-/ 1224 | /----\ | | /----\ | 1225 +---| |---+ +---| |---+ 1226 \----/ \----/ 1227 A | A | 1228 | | | | 1229 | | | | 1230 | | +------------+ | | 1231 | | | D3 | | | 1232 | | /-\ /-\ | | 1233 | +----->| | 3-1-1 | |-------+ | 1234 +---------| | 3-2-1 | |<---------+ 1235 \-/ \-/ 1236 | | 1237 +------------+ 1239 Figure 2. A Network Topology Example 1241 The corresponding instance data tree is depicted as below. Note that 1242 some lines have been wrapped to adhere to the 72-character line 1243 limitation of RFCs. 1245 { 1246 "ietf-network:networks": { 1247 "network": [ 1248 { 1249 "network-types": { 1250 "ietf-l2-topology:l2-network": {} 1251 }, 1252 "network-id": "l2-topo-example", 1253 "node": [ 1254 { 1255 "node-id": "D1", 1256 "termination-point": [ 1257 { 1258 "tp-id": "1-0-1", 1259 "ietf-l2-topology: 1260 l2-termination-point-attributes": { 1261 "mac-address": "00-00-5E-00-53-D0" 1262 } 1263 }, 1264 { 1265 "tp-id": "1-2-1", 1266 "ietf-l2-topology: 1267 l2-termination-point-attributes": { 1268 "mac-address": "00-00-5E-00-53-D1" 1269 } 1270 }, 1271 { 1272 "tp-id": "1-3-1", 1273 "ietf-l2-topology: 1274 l2-termination-point-attributes": { 1275 "mac-address": "00-00-5E-00-53-D2" 1276 } 1277 } 1278 ], 1279 "ietf-l2-topology:l2-node-attributes": { 1280 "management-address": ["10.1.1.1"] 1281 } 1282 }, 1283 { 1284 "node-id": "D2", 1285 "termination-point": [ 1286 { 1287 "tp-id": "2-0-1", 1288 "ietf-l2-topology: 1290 l2-termination-point-attributes": { 1291 "mac-address": "00-00-5E-00-53-E0" 1292 } 1293 }, 1294 { 1295 "tp-id": "2-1-1", 1296 "ietf-l2-topology: 1297 l2-termination-point-attributes": { 1298 "mac-address": "00-00-5E-00-53-E1" 1299 } 1300 }, 1301 { 1302 "tp-id": "2-3-1", 1303 "ietf-l2-topology: 1304 l2-termination-point-attributes": { 1305 "mac-address": "00-00-5E-00-53-E2" 1306 } 1307 } 1308 ], 1309 "ietf-l2-topology:l2-node-attributes": { 1310 "management-address": ["10.1.1.2"] 1311 } 1312 }, 1313 { 1314 "node-id": "D3", 1315 "termination-point": [ 1316 { 1317 "tp-id": "3-1-1", 1318 "ietf-l2-topology: 1319 l2-termination-point-attributes": { 1320 "mac-address": "00-00-5E-00-53-F0" 1321 } 1322 }, 1323 { 1324 "tp-id": "3-2-1", 1325 "ietf-l2-topology: 1326 l2-termination-point-attributes": { 1327 "mac-address": "00-00-5E-00-53-F1" 1328 } 1329 } 1330 ], 1331 "ietf-l2-topology:l2-node-attributes": { 1332 "management-address": ["10.1.1.3"] 1333 } 1334 } 1335 ], 1336 "ietf-network-topology:link": [ 1337 { 1338 "link-id": "D1,1-2-1,D2,2-1-1", 1339 "source": { 1340 "source-node": "D1", 1341 "source-tp": "1-2-1" 1342 } 1343 "destination": { 1344 "dest-node": "D2", 1345 "dest-tp": "2-1-1" 1346 }, 1347 "ietf-l2-topology:l2-link-attributes": { 1348 "rate": "1000" 1349 } 1350 }, 1351 { 1352 "link-id": "D2,2-1-1,D1,1-2-1", 1353 "source": { 1354 "source-node": "D2", 1355 "source-tp": "2-1-1" 1356 } 1357 "destination": { 1358 "dest-node": "D1", 1359 "dest-tp": "1-2-1" 1360 }, 1361 "ietf-l2-topology:l2-link-attributes": { 1362 "rate": "1000" 1363 } 1364 }, 1365 { 1366 "link-id": "D1,1-3-1,D3,3-1-1", 1367 "source": { 1368 "source-node": "D1", 1369 "source-tp": "1-3-1" 1370 } 1371 "destination": { 1372 "dest-node": "D3", 1373 "dest-tp": "3-1-1" 1374 }, 1375 "ietf-l2-topology:l2-link-attributes": { 1376 "rate": "1000" 1377 } 1378 }, 1379 { 1380 "link-id": "D3,3-1-1,D1,1-3-1", 1381 "source": { 1382 "source-node": "D3", 1383 "source-tp": "3-1-1" 1384 } 1385 "destination": { 1386 "dest-node": "D1", 1387 "dest-tp": "1-3-1" 1388 }, 1389 "ietf-l2-topology:l2-link-attributes": { 1390 "rate": "1000" 1391 } 1392 }, 1393 { 1394 "link-id": "D2,2-3-1,D3,3-2-1", 1395 "source": { 1396 "source-node": "D2", 1397 "source-tp": "2-3-1" 1398 } 1399 "destination": { 1400 "dest-node": "D3", 1401 "dest-tp": "3-2-1" 1402 }, 1403 "ietf-l2-topology:l2-link-attributes": { 1404 "rate": "1000" 1405 } 1406 }, 1407 { 1408 "link-id": "D3,3-2-1,D2,2-3-1", 1409 "source": { 1410 "source-node": "D3", 1411 "source-tp": "3-2-1" 1412 } 1413 "destination": { 1414 "dest-node": "D2", 1415 "dest-tp": "2-3-1" 1416 }, 1417 "ietf-l2-topology:l2-link-attributes": { 1418 "rate": "1000" 1419 } 1420 } 1421 ] 1422 } 1423 ] 1424 } 1425 } 1427 Authors' Addresses 1428 Jie Dong 1429 Huawei 1430 Huawei Campus, No. 156 Beiqing Rd. 1431 Beijing 100095 1432 China 1434 Email: jie.dong@huawei.com 1436 Xiugang Wei 1437 Huawei 1438 Huawei Campus, No. 156 Beiqing Rd. 1439 Beijing 100095 1440 China 1442 Email: weixiugang@huawei.com 1444 Qin Wu 1445 Huawei 1446 101 Software Avenue, Yuhua District 1447 Nanjing 210012 1448 China 1450 Email: bill.wu@huawei.com 1452 Mohamed Boucadair 1453 Orange 1454 Rennes 35000 1455 France 1457 Email: mohamed.boucadair@orange.com 1459 Anders Liu 1460 Tecent 1461 Yinke Building 38 Haidian St, Haidian District 1462 Beijing 100080 1463 China 1465 Email: andersliu@tencent.com