idnits 2.17.1 draft-wilton-netmod-intf-ext-yang-01.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (October 19, 2015) is 3106 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: 'RFC7224' is defined on line 1110, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force R. Wilton, Ed. 3 Internet-Draft D. Ball 4 Intended status: Standards Track Cisco Systems 5 Expires: April 21, 2016 T. Singh 6 S. Sivaraj 7 Juniper Networks 8 October 19, 2015 10 Common Interface Extension YANG Data Models 11 draft-wilton-netmod-intf-ext-yang-01 13 Abstract 15 This document defines two YANG modules that augment the Interfaces 16 data model defined in the "YANG Data Model for Interface Management" 17 with additional configuration and operational data nodes to support 18 common lower layer interface properties, such as interface MTU. 19 These properties are common to many types of interfaces on network 20 routers and switches and are implemented by multiple network 21 equipment vendors with similar semantics, even though some of the 22 features are not formally defined in any published standard. 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 http://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 21, 2016. 41 Copyright Notice 43 Copyright (c) 2015 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 (http://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 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3. Interfaces Extensions Module . . . . . . . . . . . . . . . . 4 63 3.1. Bandwidth . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.2. Carrier Delay . . . . . . . . . . . . . . . . . . . . . . 6 65 3.3. Dampening . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.3.1. Suppress Threshold . . . . . . . . . . . . . . . . . 7 67 3.3.2. Half-Life Period . . . . . . . . . . . . . . . . . . 8 68 3.3.3. Reuse Threshold . . . . . . . . . . . . . . . . . . . 8 69 3.3.4. Maximum Suppress Time . . . . . . . . . . . . . . . . 8 70 3.4. Encapsulation . . . . . . . . . . . . . . . . . . . . . . 8 71 3.5. Loopback . . . . . . . . . . . . . . . . . . . . . . . . 8 72 3.6. MTU . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 3.7. Sub-interface . . . . . . . . . . . . . . . . . . . . . . 9 74 3.8. Transport Layer . . . . . . . . . . . . . . . . . . . . . 10 75 4. Interfaces Ethernet-Like Module . . . . . . . . . . . . . . . 10 76 5. Interfaces Common YANG Module . . . . . . . . . . . . . . . . 10 77 6. Interfaces Ethernet-Like YANG Module . . . . . . . . . . . . 19 78 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 80 9. Security Considerations . . . . . . . . . . . . . . . . . . . 22 81 9.1. interfaces-common.yang . . . . . . . . . . . . . . . . . 22 82 9.2. interfaces-ethernet-like.yang . . . . . . . . . . . . . . 23 83 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 84 10.1. Normative References . . . . . . . . . . . . . . . . . . 24 85 10.2. Informative References . . . . . . . . . . . . . . . . . 24 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 88 1. Introduction 90 This document defines two YANG RFC 6020 [RFC6020] modules for the 91 management of network interfaces. It defines various augmentations 92 to the generic interfaces data model defined in RFC 7223 [RFC7223] to 93 support configuration of lower layer interface properties that are 94 common across many types of network interface. 96 One of the aims of this draft is to provide a standard namespace and 97 path for these configuration items regardless of the underlying 98 interface type. For example a standard namespace and path for 99 configuring or reading the MAC address associated with an interface 100 is provided that can be used for any interface type that uses 101 Ethernet framing. 103 Several of the augmentations defined here are not backed by any 104 formal standard specification. Instead, they are for features that 105 are commonly implemented in equivalent ways by multiple independent 106 network equipment vendors. The aim of this draft is to define common 107 paths and leaves for the configuration of these equivalent features 108 in a uniform way, making it easier for users of the YANG model to 109 access these features in a vendor independent way. Where necessary, 110 a description of the expected behavior is also provided with the aim 111 of ensuring vendors implementations are consistent with the specified 112 behaviour. 114 Given that the modules contain a collection of discrete features with 115 the common theme that they generically apply to interfaces, it is 116 plausible that not all implementors of the YANG module will decide to 117 support all features. Hence separate feature keywords are defined 118 for each logically discrete feature to allow implementors the 119 flexibility to choose which specific parts of the model they support. 121 The augmentations are split into two separate YANG modules that each 122 focus on a particular area of functionality. The two YANG modules 123 defined in this internet draft are: 125 interface-extensions.yang - Defines extensions to the IETF 126 interface data model to support common configuration data nodes. 128 etherlike-interfaces.yang - Defines a module for any configuration 129 and operational data nodes that are common across interfaces that 130 use Ethernet framing. 132 1.1. Terminology 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in RFC 2119 [RFC2119]. 138 1.2. Tree Diagrams 140 A simplified graphical representation of the data model is used in 141 this document. The meaning of the symbols in these diagrams is as 142 follows: 144 o Brackets "[" and "]" enclose list keys. 146 o Abbreviations before data node names: "rw" means configuration 147 (read-write), and "ro" means state data (read-only). 149 o Symbols after data node names: "?" means an optional node, "!" 150 means a presence container, and "*" denotes a list or leaf-list. 152 o Parentheses enclose choice and case nodes, and case nodes are also 153 marked with a colon (":"). 155 o Ellipsis ("...") stands for contents of subtrees that are not 156 shown. 158 2. Objectives 160 The aim of of the YANG modules contained in this draft is to provide 161 standard definitions for common interface based configuration on 162 network devices. 164 The expectation is that the YANG leaves that are being defined are 165 fairly widely implemented by network vendors. However, the features 166 described here are mostly not backed by formal standards because they 167 are fairly basic in their behavior and do not need to interoperate 168 with other devices. Where required a concise explanation of the 169 expected behavior is also provided to ensure consistency between 170 vendors. 172 3. Interfaces Extensions Module 174 The Interfaces Common module provides some basic extensions to the 175 IETF interfaces YANG module. 177 The module provides: 179 o A bandwidth configuration leaf to specify the bandwidth available 180 on an interface to control routing metrics. 182 o A carrier delay feature used to provide control over short lived 183 link state flaps. 185 o An interface link state dampening feature that is used to provide 186 control over longer lived link state flaps. 188 o An encapsulation container and extensible choice statement for use 189 by any interface types that allow for configurable L2 190 encapsulations. 192 o A loopback configuration leaf that is primarily aimed at loopback 193 at the physical layer. 195 o MTU configuration leaves applicable to all packet/frame based 196 interfaces. 198 o A transport layer leaf to indicate whether the interface handles 199 traffic at L1, L2 or L3. 201 o A parent interface leaf useable for all types of sub-interface 202 that are children of parent interfaces. 204 The "interface-extensions" YANG module has the following structure: 206 module: interfaces-common 207 augment /if:interfaces/if:interface: 208 +--rw bandwidth? uint64 209 augment /if:interfaces/if:interface: 210 +--rw carrier-delay 211 +--rw down? uint32 212 +--rw up? uint32 213 augment /if:interfaces/if:interface: 214 +--rw dampening! 215 +--rw half-life? uint32 216 +--rw reuse? uint32 217 +--rw suppress? uint32 218 +--rw max-suppress-time? uint32 219 augment /if:interfaces/if:interface: 220 +--rw encapsulation 221 +--rw (encaps-type)? 222 augment /if:interfaces/if:interface: 223 +--rw loopback? identityref 224 augment /if:interfaces/if:interface: 225 +--rw l2-mtu? uint16 {configurable-l2-mtu}? 226 augment /if:interfaces/if:interface: 227 +--rw parent-interface? if:interface-ref 228 augment /if:interfaces/if:interface: 229 +--rw transport-layer? enumeration 231 3.1. Bandwidth 233 The bandwidth configuration leaf allows the specified bandwidth of an 234 interface to be reduced from the inherent interface bandwidth. The 235 bandwidth leaf affects the routing metric cost associated with the 236 interface. 238 Note that the bandwidth leaf does not actually limit the amount of 239 traffic that can be sent/received over the interface. If required, 240 interface traffic can be limited to the required bandwidth by 241 configuring an explicit QoS policy. 243 Note for reviewers: Given that the bandwidth only controls routing 244 metrics, it may be more appropriate for this leaf, or an equivalent, 245 to be defined as part of one of the routing YANG modules. Although 246 conversely, it is also worth considering that the corresponding 247 existing CLI configuration command is an interface level bandwidth 248 command in many implementations. 250 3.2. Carrier Delay 252 The carrier delay feature augments the IETF interfaces data model 253 with configuration for a simple algorithm that is used, generally on 254 physical interfaces, to suppress short transient changes in the 255 interface link state. It can be used in conjunction with the 256 dampening feature described in Section 3.3 to provide effective 257 control of unstable links and unwanted state transitions. 259 The principal of the carrier delay feature is to use a short per 260 interface timer to ensure that any interface link state transition 261 that occurs and reverts back within the specified time interval is 262 entirely suppressed without providing any signalling to any upper 263 layer protocols that the state transition has occurred. E.g. in the 264 case that the link state transition is suppressed then there is no 265 change of the /if:interfaces-state/if:interface/oper-status or 266 /if:interfaces-state/if:interfaces/last-change leaves for the 267 interface that the feature is operating on. One obvious side effect 268 of using this feature that is worth noting is that any state 269 transition will always be delayed by the specified time interval. 271 The configuration allows for separate timer values to be used in the 272 suppression of down->up->down link transitions vs up->down->up link 273 transitions. 275 The carrier delay down timer leaf specifies the amount of time that 276 an interface that is currently in link up state must be continuously 277 down before the down state change is reported to higher level 278 protocols. Use of this timer can cause traffic to be black holed for 279 the configured value and delay reconvergence after link failures, 280 therefore its use is normally restricted to cases where it is 281 necessary to allow enough time for another protection mechanism (such 282 as an optical layer automatic protection system) to take effect. 284 The carrier delay up timer leaf specifies the amount of time that an 285 interface that is currently in link down state must be continuously 286 up before the down->up link state transition is reported to higher 287 level protocols. This timer is generally useful as a debounce 288 mechanism to ensure that a link is relatively stable before being 289 brought into service. It can also be used effectively to limit the 290 frequency at which link state transition events can occur. The 291 default value for this leaf is determined by the underlying network 292 device. 294 3.3. Dampening 296 The dampening feature introduces a configurable exponential decay 297 mechanism to suppress the effects of excessive interface link state 298 flapping. This feature allows the network operator to configure a 299 device to automatically identify and selectively dampen a local 300 interface which is flapping. Dampening an interface keeps the 301 interface operationally down until the interface stops flapping and 302 becomes stable. Configuring the dampening feature can improve 303 convergence times and stability throughout the network by isolating 304 failures so that disturbances are not propagated, which reduces the 305 utilization of system processing resources by other devices in the 306 network and improves overall network stability. 308 The basic algorithm uses a counter that is nominally increased by 309 1000 units every time the underlying interface link state changes 310 from up to down. If the counter increases above the suppress 311 threshold then the interface is kept down (and out of service) until 312 either the maximum suppression time is reached, or the counter has 313 reduced below the reuse threshold. The half-life period determines 314 that rate at which the counter is periodically reduced. 315 Implementations are not required to use a penalty of 1000 units in 316 their dampening algorithm, but should ensure that the Suppress 317 Threshold and Reuse Threshold values are scaled relative to the 318 nominal 1000 unit penalty to ensure that the same configuration 319 values provide consistent behaviour. The configurable values are 320 described in more detail below. 322 3.3.1. Suppress Threshold 324 The suppress threshold is the value of the accumulated penalty that 325 triggers the device to dampen a flapping interface. The flapping 326 interface is identified by the device and assigned a penalty for each 327 up to down link state change, but the interface is not automatically 328 dampened. The device tracks the penalties that a flapping interface 329 accumulates. When the accumulated penalty reaches the default or 330 configured suppress threshold, the interface is placed in a dampened 331 state. 333 3.3.2. Half-Life Period 335 The half-life period determines how fast the accumulated penalties 336 can decay exponentially. Any penalties that have been accumulated on 337 a flapping interface are reduced by half after each half-life period. 339 3.3.3. Reuse Threshold 341 If, after one or more half-life periods, the accumulated penalty 342 decreases below the reuse threshold and the underlying interface link 343 state is up then the interface is taken out of dampened state and 344 allowed to go up. 346 3.3.4. Maximum Suppress Time 348 The maximum suppress time represents the maximum amount of time an 349 interface can remain dampened when a penalty is assigned to an 350 interface. The default of the maximum suppress timer is four times 351 the half-life period. The maximum value of the accumulated penalty 352 is calculated using the maximum suppress time, reuse threshold and 353 half-life period. 355 3.4. Encapsulation 357 The encapsulation container holds a choice node that is to be 358 augmented with datalink layer specific encapsulations, such as HDLC, 359 PPP, or sub-interface 802.1Q tag match encapsulations. It ensures 360 that an interface can only have a single datalink layer protocol 361 configured. 363 3.5. Loopback 365 The loopback configuration leaf allows any physical interface to be 366 configured to be in one of the possible following physical loopback 367 modes, i.e. internal loopback, line loopback, or use of an external 368 loopback connector. The use of YANG identities allows for the model 369 to be extended with other modes of loopback if required. 371 3.6. MTU 373 Two MTU configuration leaves are provided to program the layer 2 374 interface in two different ways. Different mechanisms are provided 375 to reflect the fact that devices handle their MTU configuration in 376 different ways. A given device would only normally be expected to 377 support MTU configuration using one of these mechanisms. 379 The preferable way to configure MTU is using the l2-mtu leaf that 380 specifies the maximum size of a layer 2 frame including header and 381 payload, but excluding any frame checksum (FCS) bytes. The payload 382 MTU available to higher layer protocols is calculated from the l2-mtu 383 after taking the layer 2 header size into account. 385 For Ethernet interfaces carrying 802.1Q VLAN tagged frames, the 386 l2-mtu excludes the 4-8 byte overhead of any known (e.g. explicitly 387 matched by a child sub-interface) 801.1Q VLAN tags. 389 The alternative way to configure MTU is using the l3-mtu leaf that 390 specifies the maximum size of payload carried by a layer 2 frame. 391 The maximum size of the layer 2 frame can then be derived by adding 392 on the size of the layer 2 header overheads. 394 Note for reviewers: Is it correct/beneficial to support l3-mtu? It 395 would be easier for clients if they only had a single MTU that they 396 could configure. Can all devices sensibly handle an l2-mtu 397 configuration leaf? 399 3.7. Sub-interface 401 The sub-interface feature specifies the minimal leaves required to 402 define a child interface that is parented to another interface. 404 A sub-interface is a logical interface that handles a subset of the 405 traffic on the parent interface. Separate configuration leaves are 406 used to classify the subset of ingress traffic received on the parent 407 interface to be processed in the context of a given sub-interface. 408 All egress traffic processed on a sub-interface is given to the 409 parent interface for transmission. Otherwise, a sub-interface is 410 like any other interface in /if:interfaces and supports the standard 411 interface features and configuration. 413 For some vendor specific interface naming conventions the name of the 414 child interface is sufficient to determine the parent interface, 415 which implies that the child interface can never be reparented to a 416 different parent interface after it has been created without deleting 417 the existing the sub-interface and recreating a new sub-interface. 418 Even in this case it is useful to have a well defined leaf to cleanly 419 identify the parent interface. 421 The model also allows for arbitrarily named sub-interfaces by having 422 an explicit parent-interface leaf define the child -> parent 423 relationship. In this naming scenario it is also possible for 424 implementations to allow for logical interfaces to be reparented to 425 new parent interfaces without needing the sub-interface to be 426 destroyed and recreated. 428 3.8. Transport Layer 430 The transport layer leaf provides additional information as to which 431 layer an interface is logically operating and forwarding traffic at. 432 The implication of this leaf is that for traffic forwarded at a given 433 layer that any headers for lower layers are stripped off before the 434 packet is forwarded at the given layer. Conversely, on egress any 435 lower layer headers must be added to the packet before it is 436 transmitted out of the interface. 438 This leaf can also be used as a simple mechanism to determine whether 439 particular types of configuration are valid. E.g. a layer 2 QoS 440 policy could ensure that it is only applied to a interface running at 441 transport layer 2. 443 4. Interfaces Ethernet-Like Module 445 The Interfaces Ethernet-Like Module is a small module that contains 446 all configuration and operational data that is common across 447 interface types that use Ethernet framing as their datalink layer 448 encapsulation. 450 This module currently contains leaves for the configuration and 451 reporting of the operational MAC address and the burnt-in MAC address 452 (BIA) associated with any interface using Ethernet framing. 454 The "interfaces-ethernet-like" YANG module has the following 455 structure: 457 module: interfaces-ethernet-like 458 augment /if:interfaces/if:interface: 459 +--rw ethernet-like 460 +--rw mac-address? yang:mac-address 461 augment /if:interfaces-state/if:interface: 462 +--ro ethernet-like 463 +--ro mac-address? yang:mac-address 464 +--ro bia-mac-address? yang:mac-address 466 5. Interfaces Common YANG Module 468 This YANG module augments the interface container defined in RFC 7223 469 [RFC7223]. 471 file "interfaces-common@2015-10-19.yang" 472 module interfaces-common { 473 yang-version 1.1; 474 namespace "urn:ietf:params:xml:ns:yang:interfaces-common"; 475 prefix if-cmn; 476 import ietf-interfaces { 477 prefix if; 478 } 480 import iana-if-type { 481 prefix ianaift; 482 } 484 organization 485 "Cisco Systems, Inc. 486 Customer Service 488 Postal: 170 W Tasman Drive 489 San Jose, CA 95134 491 Tel: +1 1800 553-NETS 493 E-mail: cs-yang@cisco.com"; 495 contact 496 "Robert Wilton - rwilton@cisco.com"; 498 description 499 "This module contains common definitions for extending the IETF 500 interface YANG model (RFC 7223) with common configurable layer 2 501 properties."; 503 revision 2015-10-19 { 504 description 505 "Add support for various common interface configuration 506 parameters that are likely to be widely implemented by various 507 network device vendors."; 509 reference "Internet draft: draft-wilton-netmod-intf-ext-yang-01"; 510 } 512 feature bandwidth { 513 description 514 "This feature indicates that the device supports configurable 515 interface bandwidth."; 516 reference "Section 3.1 Bandwidth"; 517 } 519 feature carrier-delay { 520 description 521 "This feature indicates that configurable interface 522 carrier delay is supported, which is a feature is used to 523 limit the propagation of very short interface link state 524 flaps."; 525 reference "Section 3.2 Carrier Delay"; 526 } 528 feature dampening { 529 description 530 "This feature indicates that the device supports interface 531 dampening, which is a feature that is used to limit the 532 propagation of interface link state flaps over longer 533 periods"; 534 reference "Section 3.3 Dampening"; 535 } 537 feature loopback { 538 description 539 "This feature indicates that configurable interface loopback 540 is supported."; 541 reference "Section 3.5 Loopback"; 542 } 544 feature configurable-l2-mtu { 545 description 546 "This feature indicates that the device supports configuring 547 layer 2 MTUs on interfaces. Such MTU configurations include 548 the layer 2 header overheads (but exclude any FCS overhead). 549 The payload MTU available to higher layer protocols is either 550 derived from the layer 2 MTU, taking into account the size of 551 the layer 2 header, or is further restricted by explicit layer 552 3 or protocol specific MTU configuration."; 553 reference "Section 3.6 MTU"; 554 } 556 feature sub-interfaces { 557 description 558 "This feature indicates that the device supports the 559 instantiation of sub-interfaces. Sub-interfaces are defined 560 as logical child interfaces that allow features and forwarding 561 decisions to be applied to a subset of the traffic processed 562 on the specified parent interface."; 563 reference "Section 3.7 Sub-interface"; 564 } 566 feature transport-layer { 567 description 568 "This feature indicates that the device supports configurable 569 transport layer."; 570 reference "Section 3.8 Transport Layer"; 571 } 572 /* 573 * Define common identities to help allow interface types to be 574 * assigned properties. 575 */ 576 identity sub-interface { 577 description "Base type for generic sub-interfaces. New or custom 578 interface types can derive from this type to 579 inherit generic sub-interface configuration"; 580 } 582 identity ethSubInterface{ 583 base ianaift:l2vlan; 584 base sub-interface; 586 description "Sub-interface of any interface types that uses 587 Ethernet framing (with or without 802.1Q tagging)"; 588 } 590 identity loopback { 591 description "Base type for interface loopback options"; 592 } 593 identity loopback-internal { 594 base loopback; 595 description "All egress traffic on the interface is internally 596 looped back within the interface to be received on 597 the ingress path."; 598 } 599 identity loopback-line { 600 base loopback; 601 description "All ingress traffic received on the interface is 602 internally looped back within the interface to the 603 egress path."; 604 } 605 identity loopback-connector { 606 base loopback; 607 description "The interface has a physical loopback connector 608 attached to that loops all egress traffic back into 609 the interface's ingress path, with equivalent 610 semantics to loopback-internal"; 611 } 613 /* 614 * Augments the IETF interfaces model with a leaf to explicitly 615 * specify the bandwidth available on an interface. 616 */ 617 augment "/if:interfaces/if:interface" { 618 if-feature "bandwidth"; 619 description "Add a top level node for interface bandwidth."; 620 leaf bandwidth { 621 type uint64; 622 units kbps; 623 description 624 "The bandwidth available on the interface in Kb/s. This 625 configuration is used by routing protocols to adjust the 626 metrics associated with the interface, but does not limit 627 the amount of traffic that can be sent or received on the 628 interface. A separate QoS policy would need to be configured 629 to limit the ingress or egress traffic. If not configured, 630 the default bandwidth is the maximum available bandwidth of 631 the underlying interface."; 632 } 633 } 635 /* 636 * Defines standard YANG for the Carrier Delay feature. 637 */ 638 augment "/if:interfaces/if:interface" { 639 if-feature "carrier-delay"; 640 description "Augments the IETF interface model with 641 carrier delay configuration for interfaces that 642 support it."; 644 container carrier-delay { 645 description "Holds carrier delay related feature 646 configuration"; 647 leaf down { 648 type uint32; 649 units milliseconds; 650 description 651 "Delays the propagation of a 'loss of carrier signal' event 652 that would cause the interface state to go down, i.e. the 653 command allows short link flaps to be suppressed. The 654 configured value indicates the minimum time interval (in 655 milliseconds) that the carrier signal must be continuously 656 down before the interface state is brought down. If not 657 configured, the behaviour on loss of carrier signal is 658 vendor/interface specific, but with the general 659 expectation that there should be little or no delay."; 660 } 661 leaf up { 662 type uint32; 663 units milliseconds; 664 description 665 "Defines the minimum time interval (in milliseconds) that 666 the carrier signal must be continuously present and 667 error free before the interface state is allowed to 668 transition from down to up. If not configured, the 669 behaviour is vendor/interface specific, but with the 670 general expectation that sufficient default delay 671 should be used to ensure that the interface is stable 672 when enabled before being reported as being up. 673 Configured values that are too low for the hardware 674 capabilties may be rejected."; 675 } 676 } 677 } 679 /* 680 * Augments the IETF interfaces model with a container to hold 681 * generic interface dampening 682 */ 683 augment "/if:interfaces/if:interface" { 684 if-feature "dampening"; 685 description 686 "Add a container for interface dampening configuration"; 688 container dampening { 689 presence "Enable interface link flap dampening with default 690 settings (that are vendor/device specific)"; 691 description "Interface dampening limits the propagation of 692 interface link state flaps over longer periods"; 693 leaf half-life { 694 type uint32; 695 units seconds; 696 description 697 "The Time (in seconds) after which a penalty reaches half 698 its original value. Once the interface has been assigned 699 a penalty, the penalty is decreased by half after the 700 half-life period. For some devices, the allowed values may 701 be restricted to particular multiples of seconds. The 702 default value is vendor/device specific."; 703 } 705 leaf reuse { 706 type uint32; 707 description 708 "Penalty value below which a stable interface is 709 unsuppressed (i.e. brought up) (no units). The default 710 value is vendor/device specific. The penalty value for a 711 link up->down state change is nominally 1000 units."; 712 } 714 leaf suppress { 715 type uint32; 716 description 717 "Limit at which an interface is suppressed (i.e. held down) 718 when its penalty exceeds that limit (no units). The value 719 must be greater than the reuse threshold. The default 720 value is vendor/device specific. The penalty value for a 721 link up->down state change is nominally 1000 units."; 722 } 724 leaf max-suppress-time { 725 type uint32; 726 units seconds; 727 description 728 "Maximum time (in seconds) that an interface can be 729 suppressed. This value effectively acts as a ceiling that 730 the penalty value cannot exceed. The default value is 731 vendor/device specific."; 732 } 733 } 734 } 736 /* 737 * Various types of interfaces support a configurable layer 2 738 * encapsulation, any that are supported by YANG should be 739 * listed here. 740 * 741 * Different encapsulations can hook into the common encaps-type 742 * choice statement. 743 */ 744 augment "/if:interfaces/if:interface" { 745 when "if:type = 'ianaift:ethernetCsmacd' or 746 if:type = 'ianaift:ieee8023adLag' or 747 if:type = 'ethSubInterface' or 748 if:type = 'ianaift:pos' or 749 if:type = 'ianaift:atmSubInterface'" { 750 description "All interface types that can have a configurable 751 L2 encapsulation"; 752 /* 753 * TODO - Should we introduce an abstract type to make this 754 * extensible to new interface types, or vendor specific 755 * interface types? 756 */ 757 } 759 description "Add encapsulation top level node to interface types 760 that support a configurable L2 encapsulation"; 762 container encapsulation { 763 description 764 "Holds the L2 encapsulation associated with an interface"; 765 choice encaps-type { 766 description "Extensible choice of L2 encapsulations"; 767 } 768 } 769 } 771 /* 772 * Various types of interfaces support loopback configuration, any 773 * that are supported by YANG should be listed here. 774 */ 775 augment "/if:interfaces/if:interface" { 776 when "if:type = 'ianaift:ethernetCsmacd' or 777 if:type = 'ianaift:sonet' or 778 if:type = 'ianaift:atm' or 779 if:type = 'ianaift:otnOtu'" { 780 description 781 "All interface types that support loopback configuration."; 782 } 783 if-feature "loopback"; 784 description "Augments the IETF interface model with loopback 785 configuration for interfaces that support it."; 787 leaf loopback { 788 type identityref { 789 base loopback; 790 } 791 description "Enables traffic loopback."; 792 } 793 } 795 /* 796 * Many types of interfaces support a configurable layer 2 MTU. 797 */ 798 augment "/if:interfaces/if:interface" { 799 description "Add configurable layer 2 MTU to all appropriate 800 interface types."; 802 leaf l2-mtu { 803 if-feature "configurable-l2-mtu"; 804 type uint16 { 805 range "64 .. 65535"; 806 } 807 description 808 "The maximum size of layer 2 frames that may be transmitted 809 or received on the interface (excluding any FCS overhead). 810 In the case of Ethernet interfaces it also excludes the 811 4-8 byte overhead of any known (i.e. explicitly matched by 812 a child sub-interface) 801.1Q VLAN tags."; 813 } 814 } 816 /* 817 * Add generic support for sub-interfaces. 818 * 819 * This should be extended to cover all interface types that are 820 * child interfaces of other interfaces. 821 */ 822 augment "/if:interfaces/if:interface" { 823 when "derived-from(if:type, 824 'ietf-if-cmn', 825 'sub-interface') or 826 if:type = 'ianaift:atmSubInterface' or 827 if:type = 'ianaift:frameRelay'" { 828 description 829 "Any ianaift:types that explicitly represent sub-interfaces 830 or any types that derive from the sub-interface identity"; 831 } 832 if-feature "sub-interfaces"; 833 description "Add a parent interface field to interfaces that 834 model sub-interfaces"; 835 leaf parent-interface { 836 type if:interface-ref; 838 mandatory true; 839 description 840 "This is the reference to the parent interface of this 841 sub-interface."; 842 } 843 } 845 /* 846 * Augments the IETF interfaces model with a leaf that indicates 847 * which layer traffic is to be transported at. 848 */ 849 augment "/if:interfaces/if:interface" { 850 if-feature "transport-layer"; 851 description "Add a top level node to appropriate interfaces to 852 indicate which tranport layer an interface is 853 operating at"; 855 leaf transport-layer { 856 type enumeration { 857 enum layer-1 { 858 value 1; 859 description "Layer 1 transport."; 860 } 861 enum layer-2 { 862 value 2; 863 description "Layer 2 transport"; 864 } 865 enum layer-3 { 866 value 3; 867 description "Layer 3 transport"; 868 } 869 } 870 default layer-3; 871 description 872 "The transport layer at which the interface is operating at"; 873 } 874 } 875 } 876 878 6. Interfaces Ethernet-Like YANG Module 880 This YANG module augments the interface container defined in RFC 7223 881 [RFC7223] for Etherlike interfaces. This includes Ethernet 882 interfaces, 802.3 LAG (802.1AX) interfaces, VLAN sub-interfaces, 883 Switch Virtual interfaces, and Pseudo-Wire Head-End interfaces. 885 file "interfaces-ethernet-like@2015-06-26.yang" 886 module interfaces-ethernet-like { 887 namespace "urn:ietf:params:xml:ns:yang:interfaces-ethernet-like"; 888 prefix ethlike; 890 import ietf-interfaces { 891 prefix if; 892 } 894 import ietf-yang-types { 895 prefix yang; 896 } 898 import iana-if-type { 899 prefix ianaift; 900 } 902 organization 903 "Cisco Systems, Inc. 904 Customer Service 906 Postal: 170 W Tasman Drive 907 San Jose, CA 95134 909 Tel: +1 1800 553-NETS 911 E-mail: cs-yang@cisco.com"; 913 contact 914 "Robert Wilton - rwilton@cisco.com"; 916 description 917 "This module contains YANG definitions for configuration for 918 'Ethernet-like' interfaces. It is applicable to all interface 919 types that use Ethernet framing and expose an Ethernet MAC 920 layer, and includes such interfaces as physical Ethernet 921 interfaces, Ethernet LAG interfaces and VLAN sub-interfaces."; 923 revision 2015-06-26 { 924 description "Updated reference to new internet draft name."; 926 reference 927 "Internet draft: draft-wilton-netmod-intf-ext-yang-00"; 928 } 930 /* 931 * Configuration parameters for Etherlike interfaces. 932 */ 933 augment "/if:interfaces/if:interface" { 934 when "if:type = 'ianaift:ethernetCsmacd' or 935 if:type = 'ianaift:ieee8023adLag' or 936 if:type = 'ianaift:l2vlan' or 937 if:type = 'ianaift:ifPwType'" { 938 description "Applies to all Ethernet-like interfaces"; 939 } 940 description 941 "Augment the interface model with configuration parameters for 942 all Ethernet-like interfaces"; 944 container ethernet-like { 945 description "Contains configuration parameters for interfaces 946 that use Ethernet framing and expose an Ethernet 947 MAC layer."; 948 leaf mac-address { 949 type yang:mac-address; 950 description 951 "The configured MAC address of the interface."; 952 } 953 } 954 } 955 /* 956 * Operational state for Etherlike interfaces. 957 */ 958 augment "/if:interfaces-state/if:interface" { 959 when "if:type = 'ianaift:ethernetCsmacd' or 960 if:type = 'ianaift:ieee8023adLag' or 961 if:type = 'ianaift:l2vlan' or 962 if:type = 'ianaift:ifPwType'" { 963 description "Applies to all Ethernet-like interfaces"; 964 } 965 description 966 "Augments the interface model with operational state parameters 967 for all Ethernet-like interfaces."; 968 container ethernet-like { 969 description "Contains operational state parameters for 970 interfaces that use Ethernet framing and expose an 971 Ethernet MAC layer."; 972 leaf mac-address { 973 type yang:mac-address; 974 description 975 "The operational MAC address of the interface, if 976 applicable"; 977 } 979 leaf bia-mac-address { 980 type yang:mac-address; 981 description 982 "The 'burnt-in' MAC address. I.e the default MAC address 983 assigned to the interface if none is explicitly 984 configured."; 985 } 986 } 987 } 988 } 989 991 7. Acknowledgements 993 The authors wish to thank Juergen Schoenwaelder, Mahesh Jethanandani, 994 Michael Zitao, Neil Ketley and Qin Wu for their helpful comments 995 contributing to this draft. 997 8. IANA Considerations 999 This document defines several new YANG module and the authors 1000 politely request that IANA assigns unique names to the YANG module 1001 files contained within this draft, and also appropriate URIs in the 1002 "IETF XML Registry". 1004 9. Security Considerations 1006 The YANG module defined in this memo is designed to be accessed via 1007 the NETCONF protocol RFC 6241 [RFC6241]. The lowest NETCONF layer is 1008 the secure transport layer and the mandatory to implement secure 1009 transport is SSH RFC 6242 [RFC6242]. The NETCONF access control 1010 model RFC 6536 [RFC6536] provides the means to restrict access for 1011 particular NETCONF users to a pre-configured subset of all available 1012 NETCONF protocol operations and content. 1014 There are a number of data nodes defined in this YANG module which 1015 are writable/creatable/deletable (i.e. config true, which is the 1016 default). These data nodes may be considered sensitive or vulnerable 1017 in some network environments. Write operations (e.g. edit-config) to 1018 these data nodes without proper protection can have a negative effect 1019 on network operations. These are the subtrees and data nodes and 1020 their sensitivity/vulnerability: 1022 9.1. interfaces-common.yang 1024 The interfaces-common YANG module contains various configuration 1025 leaves that affect the behavior of interfaces. Modifying these 1026 leaves can cause an interface to go down, or become unreliable, or to 1027 drop traffic forwarded over it. More specific details of the 1028 possible failure modes are given below. 1030 The following leaf could cause the interface to go down, and stop 1031 processing any ingress or egress traffic on the interface: 1033 o /if:interfaces/if:interface/loopback 1035 The following leaf could cause changes to the routing metrics. Any 1036 change in routing metrics could cause too much traffic to be routed 1037 through the interface, or through other interfaces in the network, 1038 potentially causing traffic loss due to excesssive traffic on a 1039 particular interface or network device: 1041 o /if:interfaces/if:interface/bandwidth 1043 The following leaves could cause instabilities at the interface link 1044 layer, and cause unwanted higher layer routing path changes if the 1045 leaves are modified, although they would generally only affect a 1046 device that had some underlying link stability issues: 1048 o /if:interfaces/if:interface/carrier-delay/down 1050 o /if:interfaces/if:interface/carrier-delay/up 1051 o /if:interfaces/if:interface/dampening/half-life 1053 o /if:interfaces/if:interface/dampening/reuse 1055 o /if:interfaces/if:interface/dampening/suppress 1057 o /if:interfaces/if:interface/dampening/max-suppress-time 1059 The following leaves could cause traffic loss on the interface 1060 because the received or transmitted frames do not comply with the 1061 frame matching criteria on the interface and hence would be dropped: 1063 o /if:interfaces/if:interface/encapsulation 1065 o /if:interfaces/if:interface/l2-mtu 1067 o /if:interfaces/if:interface/l3-mtu 1069 o /if:interfaces/if:interface/transport-layer 1071 Normally devices will not allow the parent-interface leaf to be 1072 changed after the interfce has been created. If an implementation 1073 did allow the parent-interface leaf to be changed then it could cause 1074 all traffic on the affected interface to be dropped. The affected 1075 leaf is: 1077 o /if:interfaces/if:interface/parent-interface 1079 9.2. interfaces-ethernet-like.yang 1081 Generally, the configuration nodes in the interfaces-ethernet-like 1082 YANG module are concerned with configuration that is common across 1083 all types of Ethernet-like interfaces. Currently, the module only 1084 contains a node for configuring the operational MAC address to use on 1085 an interface. Adding/modifying/deleting this leaf has the potential 1086 risk of causing protocol instability, excessive protocol traffic, and 1087 general traffic loss, particularly if the configuration change caused 1088 a duplicate MAC address to be present on the local network . The 1089 following leaf is affected: 1091 o interfaces/interface/ethernet-like/mac-address 1093 10. References 1094 10.1. Normative References 1096 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1097 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1098 RFC2119, March 1997, 1099 . 1101 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1102 the Network Configuration Protocol (NETCONF)", RFC 6020, 1103 DOI 10.17487/RFC6020, October 2010, 1104 . 1106 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1107 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1108 . 1110 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", RFC 1111 7224, DOI 10.17487/RFC7224, May 2014, 1112 . 1114 10.2. Informative References 1116 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1117 and A. Bierman, Ed., "Network Configuration Protocol 1118 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1119 . 1121 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1122 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1123 . 1125 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1126 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 1127 10.17487/RFC6536, March 2012, 1128 . 1130 Authors' Addresses 1132 Robert Wilton (editor) 1133 Cisco Systems 1135 Email: rwilton@cisco.com 1137 David Ball 1138 Cisco Systems 1140 Email: daviball@cisco.com 1141 Tapraj Singh 1142 Juniper Networks 1144 Email: tsingh@juniper.net 1146 Selvakumar Sivaraj 1147 Juniper Networks 1149 Email: ssivaraj@juniper.net