idnits 2.17.1 draft-ietf-i2rs-yang-l2-network-topology-11.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 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 29, 2019) is 1700 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: 'IEEE802.1ad' is defined on line 987, but no explicit reference was found in the text == Unused Reference: 'IEEE802.1ah' is defined on line 991, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 999, but no explicit reference was found in the text == Unused Reference: 'RFC6536' is defined on line 1013, but no explicit reference was found in the text ** 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 (~~), 5 warnings (==), 3 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: March 1, 2020 Huawei 6 M. Boucadair 7 Orange 8 A. Liu 9 Tecent 10 August 29, 2019 12 A YANG Data Model for Layer-2 Network Topologies 13 draft-ietf-i2rs-yang-l2-network-topology-11 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 March 1, 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 . . . . . . . . . . . . . . . . . . . . . . . 31 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 [IEEE802.1AB] or other Layer-2 protocols, and some of them may be 125 locally 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 defined 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.1Qcp] and types defined in [RFC8345], and 242 it 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.1Qcp-2018: Bridges and Bridged 277 Networks - Amendment: YANG Data Model."; 278 } 279 organization 280 "IETF I2RS (Interface to the Routing System) Working Group"; 281 contact 282 "WG Web: 283 WG List: 284 Editor: Jie Dong 285 287 Editor: Xiugang Wei 288 290 Editor: Qin Wu 291 293 Editor: Mohamed Boucadair 294 296 Editor: Anders Liu 297 "; 299 description 300 "This module defines a basic model for 301 the layer-2 topology of a network. 303 Copyright (c) 2019 IETF Trust and the persons identified as 304 authors of the code. All rights reserved. 306 Redistribution and use in source and binary forms, with or 307 without modification, is permitted pursuant to, and subject 308 to the license terms contained in, the Simplified BSD License 309 set forth in Section 4.c of the IETF Trust's Legal Provisions 310 Relating to IETF Documents 311 (http://trustee.ietf.org/license-info). 313 This version of this YANG module is part of 314 RFC XXXX: A YANG Data Model for Layer-2 Network Topologies 315 see the RFC itself for full legal notices."; 317 revision "2019-06-04" { 318 description "Initial revision"; 319 reference 320 "RFC XXXX: A YANG Data Model for Layer-2 Network Topologies"; 321 } 323 /* 324 * Typedefs 325 */ 327 typedef trill-nickname { 328 type uint16; 329 description "TRILL Nickname"; 330 reference 331 "RFC 6326: Transparent Interconnection of Lots 332 of Links (TRILL) Use of IS-IS"; 333 } 334 typedef vni { 335 type uint32 { 336 range "1..16777215"; 337 } 338 description "VxLAN Network Identifier"; 339 reference 340 "RFC 7348: Virtual eXtensible Local Area 341 Network (VXLAN): A Framework for Overlaying 342 Virtualized Layer 2 Networks over Layer 3 343 Networks"; 344 } 346 typedef l2-flag-type { 347 type identityref { 348 base "flag-identity"; 349 } 350 description "Base type for l2 flags"; 351 } 352 typedef node-flag-type { 353 type identityref { 354 base "flag-identity"; 355 } 356 description "Node flag attributes"; 357 } 358 typedef link-flag-type { 359 type identityref { 360 base "flag-identity"; 361 } 362 description "Link flag attributes"; 363 } 365 typedef l2-network-event-type { 366 type enumeration { 367 enum "add" { 368 value 0; 369 description "An L2 node or link or termination-point 370 has been added"; 371 } 372 enum "remove" { 373 value 1; 374 description "An L2 node or link or termination-point 375 has been removed"; 376 } 377 enum "update" { 378 value 2; 379 description "An L2 node or link or termination-point 380 has been updated"; 381 } 383 } 384 description "l2 network event type for notifications"; 385 } // l2-topology-event-type 387 /* 389 * Features 390 */ 392 feature VLAN { 393 description 394 "Indicates that the system supports the 395 vlan functions (also known as an IEEE 802.1Q tag)."; 396 } 398 feature QinQ { 399 description 400 "Indicates that the system supports the 401 qinq functions (also known as IEEE 802.1ad double tag)"; 402 } 404 feature PBB { 405 description 406 "Indicates that the device supports the 407 provider-backbone-bridging functions developed 408 in IEEE 802.1ah."; 409 } 411 feature VPLS { 412 description 413 "Indicates that the device supports the 414 VPLS functions."; 415 reference 416 "RFC 4761: Virtual Private LAN Service (VPLS) Using 417 BGP for Auto-Discovery and Signaling 418 RFC 4762: Virtual Private LAN Service (VPLS) Using 419 Label Distribution Protocol (LDP) Signaling"; 420 } 422 feature TRILL { 423 description 424 "Indicates that the device supports the 425 TRILL functions."; 426 reference 427 "RFC 6325: Routing Bridges (RBridges): Base Protocol 428 Specification"; 429 } 430 feature VXLAN { 431 description 432 "Indicates that the device supports the 433 VXLAN functions."; 434 reference 435 "RFC 7348: Virtual eXtensible Local Area Network (VXLAN): 436 A Framework for Overlaying Virtualized Layer 2 Networks 437 over Layer 3 Networks"; 438 } 440 /* 441 * Identities 442 */ 444 identity flag-identity { 445 description "Base type for flags."; 446 } 448 identity eth-encapsulation-type { 449 base ift:iana-interface-type; 450 description 451 "Base identity from which specific Ethernet 452 encapsulation types are derived."; 453 reference 454 "RFC 7224: IANA Interface Type YANG Module"; 455 } 457 identity ethernet { 458 base eth-encapsulation-type; 459 description 460 "Native Ethernet encapsulation."; 461 } 463 identity vlan { 464 base eth-encapsulation-type; 465 description 466 "VLAN encapsulation."; 467 } 469 identity qinq { 470 base eth-encapsulation-type; 471 description 472 "QinQ encapsulation."; 473 } 475 identity pbb { 476 base eth-encapsulation-type; 477 description 478 "PBB encapsulation."; 479 } 481 identity trill { 482 base eth-encapsulation-type; 483 description 484 "TRILL encapsulation."; 485 } 487 identity vpls { 488 base eth-encapsulation-type; 489 description 490 "Ethernet VPLS interface encapsulation."; 491 } 493 identity vxlan { 494 base eth-encapsulation-type; 495 description 496 "VXLAN MAC in UDP encapsulation."; 497 } 499 /* 500 * Groupings 501 */ 503 grouping l2-network-type { 504 description "Identify the topology type to be L2."; 505 container l2-network { 506 presence "indicates L2 Network"; 507 description 508 "The presence of the container node indicates 509 L2 Topology."; 510 } 511 } 513 grouping l2-network-attributes { 514 description "L2 Topology scope attributes"; 515 container l2-network-attributes { 516 description "Containing L2 network attributes"; 517 leaf name { 518 type string; 519 description "Name of the L2 network."; 520 } 522 leaf-list flag { 523 type l2-flag-type; 524 description "L2 network flags"; 526 } 527 } 528 } 530 grouping l2-node-attributes { 531 description "L2 node attributes"; 532 container l2-node-attributes { 533 description "Containing L2 node attributes"; 534 leaf name { 535 type string; 536 description "Node name."; 537 } 538 leaf description { 539 type string; 540 description "Node description."; 541 } 542 leaf-list management-address { 543 type inet:ip-address; 544 description "System management address."; 545 } 546 leaf sys-mac-address { 547 type yang:mac-address; 548 description "System MAC-address."; 549 } 550 leaf management-vid { 551 if-feature VLAN; 552 type dot1q-type:vlanid; 553 description "System management VID."; 554 } 555 leaf-list flag { 556 type node-flag-type; 557 description "Node operational flags."; 558 } 559 } 560 } // grouping l2-node-attributes 562 grouping l2-link-attributes { 563 description "L2 link attributes"; 564 container l2-link-attributes { 565 description "Containing L2 link attributes."; 566 leaf name { 567 type string; 568 description "Link name."; 569 } 570 leaf-list flag { 571 type link-flag-type; 572 description "Link flags."; 573 } 574 leaf rate { 575 type decimal64 { 576 fraction-digits 2; 577 } 578 units "Mbps"; 579 description "Link rate."; 580 } 581 leaf delay { 582 type uint32; 583 description "Link delay in microseconds."; 584 } 585 leaf-list srlg { 586 type uint32; 587 description 588 "List of Shared Risk Link Groups 589 this link belongs to."; 590 reference 591 "RFC 4202: Routing Extensions in Support of 592 Generalized Multi-Protocol Label Switching 593 (GMPLS)"; 594 } 595 } 596 } // grouping l2-link-attributes 598 grouping l2-termination-point-attributes { 599 description "L2 termination point attributes"; 600 container l2-termination-point-attributes { 601 description "Containing L2 TP attributes"; 602 leaf description { 603 type string; 604 description "Port description."; 605 } 607 leaf maximum-frame-size { 608 type uint32; 609 description "Maximum L2 frame size. If L2 frame is an ethernet 610 frame, the ethernet header should be included; if L2 frame is 611 other type (e.g.,PPP), the L2 header should be 612 included."; 613 } 615 choice l2-termination-point-type { 616 description 617 "Indicates termination-point type 618 specific attributes."; 619 case ethernet { 620 leaf mac-address { 621 type yang:mac-address; 622 description "Interface MAC address."; 623 } 625 leaf eth-encapsulation { 626 type identityref { 627 base eth-encapsulation-type; 628 } 629 description 630 "Encapsulation type of this 631 termination point."; 632 } 634 leaf port-vlan-id { 635 if-feature VLAN; 636 type dot1q-type:vlanid; 637 description "Port VLAN ID is the VLAN id that 638 will be assigned to any untagged frames entering 639 the switch on the specific port."; 640 } 642 list vlan-id-name { 643 if-feature VLAN; 644 key "vlan-id"; 645 description "Interface configured VLANs."; 646 leaf vlan-id { 647 type dot1q-type:vlanid; 648 description "VLAN ID."; 649 } 650 leaf vlan-name { 651 type string { 652 length "1..31"; 653 } 654 description "VLAN name."; 655 } 656 } 657 } //case ethernet 659 case legacy { 660 leaf layer-2-address { 661 type yang:phys-address; 662 description "Interface Layer 2 address."; 663 } 665 leaf encapsulation { 666 type identityref { 667 base ift:iana-interface-type; 668 } 669 description 670 "Other legacy encapsulation type of this 671 termination point."; 672 } 673 } //case legacy such as atm, ppp, hdlc,etc. 675 } //choice termination-point-type 677 leaf tp-state { 678 type enumeration { 679 enum in-use { 680 value 1; 681 description 682 "the termination point is in forwarding state."; 683 } 684 enum blocking { 685 value 2; 686 description 687 "the termination point is in blocking state."; 688 } 689 enum down { 690 value 3; 691 description 692 "the termination point is in down state."; 693 } 694 enum others { 695 value 4; 696 description 697 "the termination point is in other state."; 698 } 699 } 700 config false; 701 description "State of the termination point."; 702 } 703 } 704 } // grouping l2-termination-point-attributes 706 /* 707 * Data nodes 708 */ 710 augment "/nw:networks/nw:network/nw:network-types" { 711 description 712 "Introduce new network type for L2 topology."; 713 uses l2-network-type; 714 } 716 augment "/nw:networks/nw:network" { 717 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 718 description 719 "Augmentation parameters apply only for networks 720 with L2 topology."; 721 } 722 description 723 "Configuration parameters for the L2 network 724 as a whole"; 725 uses l2-network-attributes; 726 } 728 augment "/nw:networks/nw:network/nw:node" { 729 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 730 description 731 "Augmentation parameters apply only for networks 732 with L2 topology."; 733 } 734 description 735 "Configuration parameters for L2 at the node 736 level."; 737 uses l2-node-attributes; 738 } 740 augment "/nw:networks/nw:network/nt:link" { 741 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 742 description 743 "Augmentation parameters apply only for networks 744 with L2 topology."; 745 } 746 description "Augment L2 topology link information"; 747 uses l2-link-attributes; 748 } 750 augment "/nw:networks/nw:network/nw:node/nt:termination-point" { 751 when "/nw:networks/nw:network/nw:network-types/l2t:l2-network" { 752 description 753 "Augmentation parameters apply only for networks 754 with L2 topology."; 755 } 756 description 757 "Augment L2 topology termination point information."; 758 uses l2-termination-point-attributes; 759 } 761 /* 762 * Notifications 763 */ 765 notification l2-node-event { 766 description "Notification event for L2 node"; 767 leaf event-type { 768 type l2-network-event-type; 769 description "Event type."; 770 } 771 uses nw:node-ref; 772 uses l2-network-type; 773 uses l2-node-attributes; 774 } 776 notification l2-link-event { 777 description "Notification event for L2 link."; 778 leaf event-type { 779 type l2-network-event-type; 780 description "Event type"; 781 } 782 uses nt:link-ref; 783 uses l2-network-type; 784 uses l2-link-attributes; 785 } 787 notification l2-termination-point-event { 788 description "Notification event for L2 termination point."; 789 leaf event-type { 790 type l2-network-event-type; 791 description "Event type"; 792 } 793 uses nt:tp-ref; 794 uses l2-network-type; 795 uses l2-termination-point-attributes; 796 } 797 } // module l2-topology 798 800 5. IANA Considerations 802 This document requests IANA to register the following URIs in the 803 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 805 URI: urn:ietf:params:xml:ns:yang:ietf-l2-topology 806 Registrant Contact: The IESG. 807 XML: N/A; the requested URI is an XML namespace. 809 URI: urn:ietf:params:xml:ns:yang:ietf-l2-topology-state 810 Registrant Contact: The IESG. 811 XML: N/A; the requested URI is an XML namespace. 813 This document requests IANA to register the following YANG modules in 814 the "YANG Module Names" subregistry [RFC6020] within the "YANG 815 Parameters" registry. 817 name: ietf-l2-topology 818 namespace: urn:ietf:params:xml:ns:yang:ietf-l2-topology 819 prefix: l2t 820 reference: RFC XXXX 822 name: ietf-l2-topology-state 823 namespace: urn:ietf:params:xml:ns:yang:ietf-l2-topology-state 824 prefix: l2t-s 825 reference: RFC XXXX 827 These modules are not maintained by IANA. 829 6. Security Considerations 831 The YANG module specified in this document defines a schema for data 832 that is designed to be accessed via network management protocols such 833 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 834 is the secure transport layer, and the mandatory-to-implement secure 835 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 836 is HTTPS, and the mandatory-to-implement secure transport is TLS 837 [RFC8446]. 839 The Network Configuration Access Control Model (NACM) [RFC8341] 840 provides the means to restrict access for particular NETCONF or 841 RESTCONF users to a preconfigured subset of all available NETCONF or 842 RESTCONF protocol operations and content. 844 In general, Layer 2 network topologies are system-controlled and 845 provide ephemeral topology information. In an NMDA-complient server, 846 they are only part of which provides read-only access 847 to clients, they are less vulnerable. That said, the YANG module 848 does in principle allow information to be configurable. 850 The Layer 2 topology module define information that can be 851 configurable in certain instances, for example in the case of virtual 852 topologies that can be created by client applications. In such 853 cases, a malicious client could introduce topologies that are 854 undesired. Specifically, a malicious client could attempt to remove 855 or add a node, a link, a termination point, by creating or deleting 856 corresponding elements in the node, link, and termination point 857 lists, respectively. In the case of a topology that is learned, the 858 server will automatically prohibit such misconfiguration attempts. 859 In the case of a topology that is configured, i.e. whose origin is 860 "intended", the undesired configuration could become effective and be 861 reflected in the operational state datastore, leading to disruption 862 of services provided via this topology might be disrupted. For those 863 reasons, it is important that the NETCONF access control model is 864 vigorously applied to prevent topology misconfiguration by 865 unauthorized clients. 867 There are a number of data nodes defined in this YANG module that are 868 writable/creatable/deletable (i.e., config true, which is the 869 default). These data nodes may be considered sensitive or vulnerable 870 in some network environments. Write operations (e.g., edit-config) 871 to these data nodes without proper protection can have a negative 872 effect on network operations. These are the subtrees and data nodes 873 and their sensitivity/vulnerability in the ietf-network module: 875 o l2-network-attributes: A malicious client could attempt to 876 sabotage the configuration of any of the contained attributes, 877 such as the name or the flag data nodes. 879 o l2-node-attributes: A malicious client could attempt to sabotage 880 the configuration of important node attributes, such as the name 881 or the management-address. 883 o l2-link-attributes: A malicious client could attempt to sabotage 884 the configuration of important link attributes, such as the rate 885 or the delay data nodes. 887 o l2-termination-point-attributes: A malicious client could attempt 888 to sabotage the configuration of important termination point 889 attributes, such as the maximum-frame-size. 891 7. Acknowledgements 893 The authors would like to acknowledge the comments and suggestions 894 received from Susan Hares, Alia Atlas, Juergen Schoenwaelder, Mach 895 Chen, Alexander Clemm and Sriganesh Kini. 897 8. References 899 8.1. Normative References 901 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 902 Requirement Levels", BCP 14, RFC 2119, 903 DOI 10.17487/RFC2119, March 1997, 904 . 906 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 907 DOI 10.17487/RFC3688, January 2004, 908 . 910 [RFC4202] Kompella, K., Ed. and Y. Rekhter, Ed., "Routing Extensions 911 in Support of Generalized Multi-Protocol Label Switching 912 (GMPLS)", RFC 4202, DOI 10.17487/RFC4202, October 2005, 913 . 915 [RFC4761] Kompella, K., Ed. and Y. Rekhter, Ed., "Virtual Private 916 LAN Service (VPLS) Using BGP for Auto-Discovery and 917 Signaling", RFC 4761, DOI 10.17487/RFC4761, January 2007, 918 . 920 [RFC4762] Lasserre, M., Ed. and V. Kompella, Ed., "Virtual Private 921 LAN Service (VPLS) Using Label Distribution Protocol (LDP) 922 Signaling", RFC 4762, DOI 10.17487/RFC4762, January 2007, 923 . 925 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 926 the Network Configuration Protocol (NETCONF)", RFC 6020, 927 DOI 10.17487/RFC6020, October 2010, 928 . 930 [RFC6325] Perlman, R., Eastlake 3rd, D., Dutt, D., Gai, S., and A. 931 Ghanwani, "Routing Bridges (RBridges): Base Protocol 932 Specification", RFC 6325, DOI 10.17487/RFC6325, July 2011, 933 . 935 [RFC6326] Eastlake, D., Banerjee, A., Dutt, D., Perlman, R., and A. 936 Ghanwani, "Transparent Interconnection of Lots of Links 937 (TRILL) Use of IS-IS", RFC 6326, DOI 10.17487/RFC6326, 938 July 2011, . 940 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 941 RFC 6991, DOI 10.17487/RFC6991, July 2013, 942 . 944 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 945 RFC 7224, DOI 10.17487/RFC7224, May 2014, 946 . 948 [RFC7348] Mahalingam, M., Dutt, D., Duda, K., Agarwal, P., Kreeger, 949 L., Sridhar, T., Bursell, M., and C. Wright, "Virtual 950 eXtensible Local Area Network (VXLAN): A Framework for 951 Overlaying Virtualized Layer 2 Networks over Layer 3 952 Networks", RFC 7348, DOI 10.17487/RFC7348, August 2014, 953 . 955 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 956 RFC 7950, DOI 10.17487/RFC7950, August 2016, 957 . 959 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 960 RFC 7951, DOI 10.17487/RFC7951, August 2016, 961 . 963 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 964 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 965 May 2017, . 967 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 968 Access Control Model", STD 91, RFC 8341, 969 DOI 10.17487/RFC8341, March 2018, 970 . 972 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 973 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 974 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 975 2018, . 977 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 978 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 979 . 981 8.2. Informative References 983 [IEEE802.1AB] 984 "Station and Media Access Control Connectivity Discovery", 985 IEEE Std 802.1AB-2016, March 2016. 987 [IEEE802.1ad] 988 "Virtual Bridged Local Area Networks Amendment 4: Provider 989 Bridges", IEEE Std 802.1ad-2005, May 2006. 991 [IEEE802.1ah] 992 "Virtual Bridged Local Area Networks Amendment 4: Provider 993 Bridges", IEEE Std 802.1ah-2008, August 2008. 995 [IEEE802.1Qcp] 996 "Bridges and Bridged Networks - Amendment: YANG Data 997 Model", IEEE Std 802.1Qcp-2018, September 2018. 999 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1000 (TLS) Protocol Version 1.2", RFC 5246, 1001 DOI 10.17487/RFC5246, August 2008, 1002 . 1004 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1005 and A. Bierman, Ed., "Network Configuration Protocol 1006 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1007 . 1009 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1010 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1011 . 1013 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1014 Protocol (NETCONF) Access Control Model", RFC 6536, 1015 DOI 10.17487/RFC6536, March 2012, 1016 . 1018 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1019 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1020 . 1022 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1023 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1024 . 1026 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1027 and R. Wilton, "Network Management Datastore Architecture 1028 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1029 . 1031 Appendix A. Companion YANG Module for Non-NMDA Compliant 1032 Implementations 1034 The YANG module ietf-l2-topology defined in this document augments 1035 two modules, ietf-network and ietf-network-topology, that are 1036 designed to be used in conjunction with implementations that support 1037 the Network Management Datastore Architecture (NMDA) defined in 1038 [RFC8342]. In order to allow implementations to use the model even 1039 in cases when NMDA is not supported, a set of companion modules have 1040 been defined that represent a state model of networks and network 1041 topologies, ietf- network-state and ietf-network-topology-state, 1042 respectively. 1044 In order to be able to use the model for layer 2 topologies defined 1045 in this document in conjunction with non-NMDA compliant 1046 implementations, a corresponding companion module is defined that 1047 represent the operational state of layer 2 network topologies. The 1048 module ietf-l2-topology-state mirrors the module ietf-l2-topology 1049 defined earlier in this document. However, it augments ietf-network- 1050 state and ietf-network-topology-state (instead of ietf-network and 1051 ietf-network-topology) and all its data nodes are non-configurable. 1053 The companion module ietf-l2-topology SHOULD NOT be supported by 1054 implementations that support NMDA. It is for this reason that this 1055 module is defined in the informative Appendix. 1057 As the structure of this modules mirrors that of its underlying 1058 modules, the YANG tree is not depicted separately. 1060 file "ietf-l2-topology-state@2019-06-04.yang" 1061 module ietf-l2-topology-state { 1062 yang-version 1.1; 1063 namespace "urn:ietf:params:xml:ns:yang:ietf-l2-topology-state"; 1064 prefix "l2t-s"; 1066 import ietf-network-state { 1067 prefix "nw-s"; 1068 reference 1069 "RFC 8345: A YANG Data Model for Network Topologies"; 1070 } 1072 import ietf-network-topology-state { 1073 prefix "nt-s"; 1074 reference 1075 "RFC 8345: A YANG Data Model for Network Topologies"; 1076 } 1078 import ietf-l2-topology { 1079 prefix "l2t"; 1080 reference 1081 "RFC XXXX: A YANG Data Model for Layer-2 Network Topologies"; 1082 } 1084 organization 1085 "IETF I2RS (Interface to the Routing System) Working Group"; 1086 contact 1087 "WG Web: 1088 WG List: 1089 Editor: Jie Dong 1090 1091 Editor: Xiugang Wei 1092 1093 Editor: Qin Wu 1094 1095 Editor: Mohamed Boucadair 1096 1097 Editor: Anders Liu 1098 "; 1100 description 1101 " This module defines a model for Layer 2 Network Topology 1102 state, representing topology that either is learned or 1103 results from applying topology that has been configured per 1104 the 'ietf-l2-topology' model, mirroring the 1105 corresponding data nodes in this model. 1107 This model mirrors 'ietf-l2-topology' but contains only 1108 read-only state data. The model is not needed when the 1109 underlying implementation infrastructure supports the Network 1110 Management Datastore Architecture (NMDA). 1112 Copyright (c) 2018 IETF Trust and the persons identified as 1113 authors of the code. All rights reserved. 1115 Redistribution and use in source and binary forms, with or 1116 without modification, is permitted pursuant to, and subject 1117 to the license terms contained in, the Simplified BSD License 1118 set forth in Section 4.c of the IETF Trust's Legal Provisions 1119 Relating to IETF Documents 1120 (http://trustee.ietf.org/license-info). 1122 This version of this YANG module is part of 1123 RFC XXXX: A YANG Data Model for Layer-2 Network Topologies 1124 see the RFC itself for full legal notices."; 1126 revision "2019-06-04" { 1127 description "Initial revision"; 1128 reference "RFC XXXX: A YANG Data Model for Layer-2 Network Topologies"; 1129 } 1131 /* 1132 * Data nodes 1133 */ 1134 augment "/nw-s:networks/nw-s:network/nw-s:network-types" { 1135 description 1136 "Introduce new network type for L2 topology"; 1137 uses l2t:l2-network-type; 1138 } 1140 augment "/nw-s:networks/nw-s:network" { 1141 when "/nw-s:networks/nw-s:network/nw-s:network-types/"+ 1142 "l2t-s:l2-network" { 1143 description 1144 "Augmentation parameters apply only for networks 1145 with L2 topology"; 1146 } 1147 description 1148 "Configuration parameters for the L2 network 1149 as a whole"; 1150 uses l2t:l2-network-attributes; 1151 } 1153 augment "/nw-s:networks/nw-s:network/nw-s:node" { 1154 when "../nw-s:network-types/l2t-s:l2-network" { 1155 description 1156 "Augmentation parameters apply only for networks 1157 with L2 topology"; 1158 } 1159 description 1160 "Configuration parameters for L2 at the node 1161 level"; 1162 uses l2t:l2-node-attributes; 1163 } 1165 augment "/nw-s:networks/nw-s:network/nt-s:link" { 1166 when "../nw-s:network-types/l2t-s:l2-network" { 1167 description 1168 "Augmentation parameters apply only for networks 1169 with L2 topology"; 1170 } 1171 description "Augment L2 topology link information"; 1172 uses l2t:l2-link-attributes; 1173 } 1175 augment "/nw-s:networks/nw-s:network/nw-s:node/"+ 1176 "nt-s:termination-point" { 1177 when "../../nw-s:network-types/l2t-s:l2-network" { 1178 description 1179 "Augmentation parameters apply only for networks 1180 with L2 topology"; 1181 } 1182 description 1183 "Augment L2 topology termination point information"; 1184 uses l2t:l2-termination-point-attributes; 1185 } 1187 /* 1188 * Notifications 1189 */ 1191 notification l2-node-event { 1192 description "Notification event for L2 node"; 1193 leaf event-type { 1194 type l2t:l2-network-event-type; 1195 description "Event type"; 1196 } 1197 uses nw-s:node-ref; 1198 uses l2t:l2-network-type; 1199 uses l2t:l2-node-attributes; 1200 } 1202 notification l2-link-event { 1203 description "Notification event for L2 link"; 1204 leaf event-type { 1205 type l2t:l2-network-event-type; 1206 description "Event type"; 1207 } 1208 uses nt-s:link-ref; 1209 uses l2t:l2-network-type; 1210 uses l2t:l2-link-attributes; 1211 } 1213 notification l2-termination-point-event { 1214 description "Notification event for L2 termination point"; 1215 leaf event-type { 1216 type l2t:l2-network-event-type; 1217 description "Event type"; 1218 } 1219 uses nt-s:tp-ref; 1220 uses l2t:l2-network-type; 1221 uses l2t:l2-termination-point-attributes; 1222 } 1223 } // module l2-topology-state 1224 1226 Appendix B. An Example 1228 This section contains an example of an instance data tree in JSON 1229 encoding [RFC7951]. The example instantiates "ietf-l2- topology" for 1230 the topology that is depicted in the following diagram. There are 1231 three nodes: D1, D2, and D3. D1 has three termination points: 1-0-1, 1232 1-2-1, and 1-3-1. D2 has three termination points as well: 2-1-1, 1233 2-0-1, and 2-3-1. D3 has two termination points: 3-1-1 and 3-2-1. 1234 In addition, there are six links, two between each pair of nodes, 1235 with one going in each direction. 1237 +------------+ +------------+ 1238 | D1 | | D2 | 1239 /-\ /-\ /-\ /-\ 1240 | | 1-0-1 | |---------------->| | 2-1-1 | | 1241 | | 1-2-1 | |<----------------| | 2-0-1 | | 1242 \-/ 1-3-1 \-/ \-/ 2-3-1 \-/ 1243 | /----\ | | /----\ | 1244 +---| |---+ +---| |---+ 1245 \----/ \----/ 1246 A | A | 1247 | | | | 1248 | | | | 1249 | | +------------+ | | 1250 | | | D3 | | | 1251 | | /-\ /-\ | | 1252 | +----->| | 3-1-1 | |-------+ | 1253 +---------| | 3-2-1 | |<---------+ 1254 \-/ \-/ 1255 | | 1256 +------------+ 1258 Figure 2. A Network Topology Example 1260 The corresponding instance data tree is depicted as below. Note that 1261 some lines have been wrapped to adhere to the 72-character line 1262 limitation of RFCs. 1264 { 1265 "ietf-network:networks": { 1266 "network": [ 1267 { 1268 "network-types": { 1269 "ietf-l2-topology:l2-network": {} 1270 }, 1271 "network-id": "l2-topo-example", 1272 "node": [ 1273 { 1274 "node-id": "D1", 1275 "termination-point": [ 1276 { 1277 "tp-id": "1-0-1", 1278 "ietf-l2-topology: 1279 l2-termination-point-attributes": { 1280 "mac-address": "00-00-5E-00-53-D0" 1281 } 1282 }, 1283 { 1284 "tp-id": "1-2-1", 1285 "ietf-l2-topology: 1286 l2-termination-point-attributes": { 1287 "mac-address": "00-00-5E-00-53-D1" 1288 } 1289 }, 1290 { 1291 "tp-id": "1-3-1", 1292 "ietf-l2-topology: 1293 l2-termination-point-attributes": { 1294 "mac-address": "00-00-5E-00-53-D2" 1295 } 1296 } 1297 ], 1298 "ietf-l2-topology:l2-node-attributes": { 1299 "management-address": ["192.0.2.1"] 1300 } 1301 }, 1302 { 1303 "node-id": "D2", 1304 "termination-point": [ 1305 { 1306 "tp-id": "2-0-1", 1307 "ietf-l2-topology: 1308 l2-termination-point-attributes": { 1309 "mac-address": "00-00-5E-00-53-E0" 1310 } 1311 }, 1312 { 1313 "tp-id": "2-1-1", 1314 "ietf-l2-topology: 1315 l2-termination-point-attributes": { 1316 "mac-address": "00-00-5E-00-53-E1" 1317 } 1318 }, 1319 { 1320 "tp-id": "2-3-1", 1321 "ietf-l2-topology: 1322 l2-termination-point-attributes": { 1323 "mac-address": "00-00-5E-00-53-E2" 1324 } 1325 } 1326 ], 1327 "ietf-l2-topology:l2-node-attributes": { 1328 "management-address": ["192.0.2.2"] 1329 } 1330 }, 1331 { 1332 "node-id": "D3", 1333 "termination-point": [ 1334 { 1335 "tp-id": "3-1-1", 1336 "ietf-l2-topology: 1337 l2-termination-point-attributes": { 1338 "mac-address": "00-00-5E-00-53-F0" 1339 } 1340 }, 1341 { 1342 "tp-id": "3-2-1", 1343 "ietf-l2-topology: 1344 l2-termination-point-attributes": { 1345 "mac-address": "00-00-5E-00-53-F1" 1346 } 1347 } 1348 ], 1349 "ietf-l2-topology:l2-node-attributes": { 1350 "management-address": ["192.0.2.3"] 1351 } 1352 } 1353 ], 1354 "ietf-network-topology:link": [ 1355 { 1356 "link-id": "D1,1-2-1,D2,2-1-1", 1357 "source": { 1358 "source-node": "D1", 1359 "source-tp": "1-2-1" 1360 } 1361 "destination": { 1362 "dest-node": "D2", 1363 "dest-tp": "2-1-1" 1364 }, 1365 "ietf-l2-topology:l2-link-attributes": { 1366 "rate": "1000" 1367 } 1368 }, 1369 { 1370 "link-id": "D2,2-1-1,D1,1-2-1", 1371 "source": { 1372 "source-node": "D2", 1373 "source-tp": "2-1-1" 1374 } 1375 "destination": { 1376 "dest-node": "D1", 1377 "dest-tp": "1-2-1" 1378 }, 1379 "ietf-l2-topology:l2-link-attributes": { 1380 "rate": "1000" 1382 } 1383 }, 1384 { 1385 "link-id": "D1,1-3-1,D3,3-1-1", 1386 "source": { 1387 "source-node": "D1", 1388 "source-tp": "1-3-1" 1389 } 1390 "destination": { 1391 "dest-node": "D3", 1392 "dest-tp": "3-1-1" 1393 }, 1394 "ietf-l2-topology:l2-link-attributes": { 1395 "rate": "1000" 1396 } 1397 }, 1398 { 1399 "link-id": "D3,3-1-1,D1,1-3-1", 1400 "source": { 1401 "source-node": "D3", 1402 "source-tp": "3-1-1" 1403 } 1404 "destination": { 1405 "dest-node": "D1", 1406 "dest-tp": "1-3-1" 1407 }, 1408 "ietf-l2-topology:l2-link-attributes": { 1409 "rate": "1000" 1410 } 1411 }, 1412 { 1413 "link-id": "D2,2-3-1,D3,3-2-1", 1414 "source": { 1415 "source-node": "D2", 1416 "source-tp": "2-3-1" 1417 } 1418 "destination": { 1419 "dest-node": "D3", 1420 "dest-tp": "3-2-1" 1421 }, 1422 "ietf-l2-topology:l2-link-attributes": { 1423 "rate": "1000" 1424 } 1425 }, 1426 { 1427 "link-id": "D3,3-2-1,D2,2-3-1", 1428 "source": { 1429 "source-node": "D3", 1430 "source-tp": "3-2-1" 1431 } 1432 "destination": { 1433 "dest-node": "D2", 1434 "dest-tp": "2-3-1" 1435 }, 1436 "ietf-l2-topology:l2-link-attributes": { 1437 "rate": "1000" 1438 } 1439 } 1440 ] 1441 } 1442 ] 1443 } 1444 } 1446 Authors' Addresses 1448 Jie Dong 1449 Huawei 1450 Huawei Campus, No. 156 Beiqing Rd. 1451 Beijing 100095 1452 China 1454 Email: jie.dong@huawei.com 1456 Xiugang Wei 1457 Huawei 1458 Huawei Campus, No. 156 Beiqing Rd. 1459 Beijing 100095 1460 China 1462 Email: weixiugang@huawei.com 1464 Qin Wu 1465 Huawei 1466 101 Software Avenue, Yuhua District 1467 Nanjing 210012 1468 China 1470 Email: bill.wu@huawei.com 1471 Mohamed Boucadair 1472 Orange 1473 Rennes 35000 1474 France 1476 Email: mohamed.boucadair@orange.com 1478 Anders Liu 1479 Tecent 1480 Yinke Building 38 Haidian St, Haidian District 1481 Beijing 100080 1482 China 1484 Email: andersliu@tencent.com