idnits 2.17.1 draft-ietf-netmod-interfaces-cfg-07.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 22, 2012) is 4204 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) == Outdated reference: A later version (-10) exists of draft-ietf-netmod-iana-if-type-02 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track October 22, 2012 5 Expires: April 25, 2013 7 A YANG Data Model for Interface Management 8 draft-ietf-netmod-interfaces-cfg-07 10 Abstract 12 This document defines a YANG data model for the management of network 13 interfaces. It is expected that interface type specific data models 14 augment the generic interfaces data model defined in this document. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on April 25, 2013. 33 Copyright Notice 35 Copyright (c) 2012 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 3. Interfaces Data Model . . . . . . . . . . . . . . . . . . . . 5 54 3.1. The interface List . . . . . . . . . . . . . . . . . . . . 5 55 3.2. Interface References . . . . . . . . . . . . . . . . . . . 6 56 3.3. Interface Layering . . . . . . . . . . . . . . . . . . . . 6 57 4. Relationship to the IF-MIB . . . . . . . . . . . . . . . . . . 8 58 5. Interfaces YANG Module . . . . . . . . . . . . . . . . . . . . 10 59 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 60 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 61 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 62 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 63 9.1. Normative References . . . . . . . . . . . . . . . . . . . 26 64 9.2. Informative References . . . . . . . . . . . . . . . . . . 26 65 Appendix A. Example: Ethernet Interface Module . . . . . . . . . 27 66 Appendix B. Example: Ethernet Bonding Interface Module . . . . . 29 67 Appendix C. Example: VLAN Interface Module . . . . . . . . . . . 30 68 Appendix D. Example: NETCONF reply . . . . . . . . . . . . 31 69 Appendix E. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 32 70 E.1. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 32 71 E.2. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 32 72 E.3. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 32 73 E.4. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 32 74 E.5. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 32 75 E.6. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 32 76 E.7. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 33 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 34 79 1. Introduction 81 This document defines a YANG [RFC6020] data model for the management 82 of network interfaces. It is expected that interface type specific 83 data models augment the generic interfaces data model defined in this 84 document. 86 Network interfaces are central to the management of many Internet 87 protocols. Thus, it is important to establish a common data model 88 for how interfaces are identified and configured. 90 1.1. Terminology 92 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 94 "OPTIONAL" in this document are to be interpreted as described in BCP 95 14, [RFC2119]. 97 The following terms are defined in [RFC6241] and are not redefined 98 here: 100 o client 102 o server 104 The following terms are defined in [RFC6020] and are not redefined 105 here: 107 o augment 109 o data model 111 o data node 113 2. Objectives 115 This section describes some of the design objectives for the model 116 presented in Section 5. 118 o It is recognized that existing implementations will have to map 119 the interface data model defined in this memo to their proprietary 120 native data model. The new data model should be simple to 121 facilitate such mappings. 123 o The data model should be suitable for new implementations to use 124 as-is, without requiring a mapping to a different native model. 126 o References to interfaces should be as simple as possible, 127 preferably by using a single leafref. 129 o The mapping to ifIndex [RFC2863] used by SNMP to identify 130 interfaces must be clear. 132 o The model must support interface layering, both simple layering 133 where one interface is layered on top of exactly one other 134 interface, and more complex scenarios where one interface is 135 aggregated over N other interfaces, or when N interfaces are 136 multiplexed over one other interface. 138 o The data model should support the pre-provisioning of interface 139 configuration, i.e., it should be possible to configure an 140 interface whose physical interface hardware is not present on the 141 device. It is recommended that devices that support dynamic 142 addition and removal of physical interfaces also support pre- 143 provisioning. 145 3. Interfaces Data Model 147 The data model in the module "ietf-interfaces" has the following 148 structure, where square brackets are used to enclose a list's keys, 149 "?" means that the leaf is optional, and "*" denotes a leaf-list: 151 +--rw interfaces 152 +--rw interface [name] 153 +--rw name string 154 +--rw description? string 155 +--rw type ianaift:iana-if-type 156 +--rw location? string 157 +--rw enabled? boolean 158 +--ro oper-status? enumeration 159 +--ro last-change? yang:date-and-time 160 +--ro if-index? int32 161 +--rw mtu? uint32 162 +--rw link-up-down-trap-enable? enumeration 163 +--ro phys-address? yang:phys-address 164 +--ro higher-layer-if* interface-ref 165 +--ro lower-layer-if* interface-ref 166 +--ro speed? yang:gauge64 167 +--ro statistics 168 +--ro discontinuity-time? yang:date-and-time 169 +--ro in-octets? yang:counter64 170 +--ro in-unicast-pkts? yang:counter64 171 +--ro in-broadcast-pkts? yang:counter64 172 +--ro in-multicast-pkts? yang:counter64 173 +--ro in-discards? yang:counter32 174 +--ro in-errors? yang:counter32 175 +--ro in-unknown-protos? yang:counter32 176 +--ro out-octets? yang:counter64 177 +--ro out-unicast-pkts? yang:counter64 178 +--ro out-broadcast-pkts? yang:counter64 179 +--ro out-multicast-pkts? yang:counter64 180 +--ro out-discards? yang:counter32 181 +--ro out-errors? yang:counter32 183 This module defines one YANG feature: 185 if-mib: Indicates that the server implements IF-MIB [RFC2863]. 187 3.1. The interface List 189 The data model for interfaces presented in this document uses a flat 190 list of interfaces. Each interface in the list is identified by its 191 name. Furthermore, each interface has a mandatory "type" leaf, and a 192 "location" leaf. The combination of "type" and "location" is unique 193 within the interface list. 195 It is expected that interface type specific data models augment the 196 interface list, and use the "type" leaf to make the augmentation 197 conditional. 199 As an example of such an interface type specific augmentation, 200 consider this YANG snippet. For a more complete example, see 201 Appendix A. 203 import interfaces { 204 prefix "if"; 205 } 207 augment "/if:interfaces/if:interface" { 208 when "if:type = 'ethernetCsmacd'"; 210 container ethernet { 211 leaf duplex { 212 ... 213 } 214 } 215 } 217 The "location" leaf is a string. It is optional in the data model, 218 but if the type represents a physical interface, it is mandatory. 219 The format of this string is device- and type-dependent. The device 220 uses the location string to identify the physical or logical entity 221 that the configuration applies to. For example, if a device has a 222 single array of 8 ethernet ports, the location can be one of the 223 strings "1" to "8". As another example, if a device has N cards of M 224 ports, the location can be on the form "n/m", such as "1/0". 226 How a client can learn which types and locations are present on a 227 certain device is outside the scope of this document. 229 3.2. Interface References 231 An interface is identified by its name, which is unique within the 232 server. This property is captured in the "interface-ref" typedef, 233 which other YANG modules SHOULD use when they need to reference an 234 existing interface. 236 3.3. Interface Layering 238 There is no generic mechanism for how an interface is configured to 239 be layered on top of some other interface. It is expected that 240 interface type specific models define their own data nodes for 241 interface layering, by using "interface-ref" types to reference lower 242 layers. 244 Below is an example of a model with such nodes. For a more complete 245 example, see Appendix B. 247 augment "/if:interfaces/if:interface" { 248 when "if:type = 'ieee8023adLag'"; 250 leaf-list slave-if { 251 type if:interface-ref; 252 must "/if:interfaces/if:interface[if:name = current()]" 253 + "/if:type = 'ethernetCsmacd'" { 254 description 255 "The type of a slave interface must be ethernet"; 256 } 257 } 258 // other bonding config params, failover times etc. 259 } 261 There are two state data leaf-list nodes "higher-layer-if" and 262 "lower-layer-if" defined, that contains a read-only view of the 263 interface layering hierarchy. 265 4. Relationship to the IF-MIB 267 If the device implements IF-MIB [RFC2863], each entry in the 268 "interface" list is typically mapped to one ifEntry. The "if-index" 269 leaf contains the value of the corresponding ifEntry's ifIndex. 271 In most cases, the "name" of an "interface" entry is mapped to 272 ifName. ifName is defined as an DisplayString [RFC2579] which uses a 273 7-bit ASCII character set. An implementation MAY restrict the 274 allowed values for "name" to match the restrictions of ifName. 276 The IF-MIB allows two different ifEntries to have the same ifName. 277 Devices that support this feature, and also support the configuration 278 of these interfaces using the "interface" list, cannot have a 1-1 279 mapping between the "name" leaf and ifName. 281 The IF-MIB also defines the writable object ifPromiscuousMode. Since 282 this object typically is not a configuration object, it is not mapped 283 to the "ietf-interfaces" module. 285 The following table lists the YANG data nodes with corresponding 286 objects in the IF-MIB. 288 +----------------------------------+------------------------+ 289 | YANG data node | IF-MIB object | 290 +----------------------------------+------------------------+ 291 | interface | ifEntry | 292 | name | ifName | 293 | description | ifAlias | 294 | type | ifType | 295 | enabled | ifAdminStatus | 296 | oper-status | ifOperStatus | 297 | last-change | ifLastChange | 298 | if-index | ifIndex | 299 | mtu | ifMtu | 300 | link-up-down-trap-enable | ifLinkUpDownTrapEnable | 301 | phys-address | ifPhysAddress | 302 | higher-layer-if / lower-layer-if | ifStackTable | 303 | speed | ifSpeed | 304 | in-octets | ifHCInOctets | 305 | in-unicast-pkts | ifHCInUcastPkts | 306 | in-broadcast-pkts | ifHCInBroadcastPkts | 307 | in-multicast-pkts | ifHCInMulticastPkts | 308 | in-discards | ifInDiscards | 309 | in-errors | ifInErrors | 310 | in-unknown-protos | ifInUnknownProtos | 311 | out-octets | ifHCOutOctets | 312 | out-unicast-pkts | ifHCOutUcastPkts | 313 | out-broadcast-pkts | ifHCOutBroadcastPkts | 314 | out-multicast-pkts | ifHCOutMulticastPkts | 315 | out-discards | ifOutDiscards | 316 | out-errors | ifOutErrors | 317 +----------------------------------+------------------------+ 319 Mapping of YANG data nodes to IF-MIB objects 321 5. Interfaces YANG Module 323 This YANG module imports a typedef from 324 [I-D.ietf-netmod-iana-if-type]. 326 RFC Ed.: update the date below with the date of RFC publication and 327 remove this note. 329 file "ietf-interfaces@2012-10-22.yang" 331 module ietf-interfaces { 333 namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces"; 334 prefix if; 336 import ietf-yang-types { 337 prefix yang; 338 } 339 import iana-if-type { 340 prefix ianaift; 341 } 343 organization 344 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 346 contact 347 "WG Web: 348 WG List: 350 WG Chair: David Kessens 351 353 WG Chair: Juergen Schoenwaelder 354 356 Editor: Martin Bjorklund 357 "; 359 description 360 "This module contains a collection of YANG definitions for 361 managing network interfaces. 363 Copyright (c) 2012 IETF Trust and the persons identified as 364 authors of the code. All rights reserved. 366 Redistribution and use in source and binary forms, with or 367 without modification, is permitted pursuant to, and subject 368 to the license terms contained in, the Simplified BSD License 369 set forth in Section 4.c of the IETF Trust's Legal Provisions 370 Relating to IETF Documents 371 (http://trustee.ietf.org/license-info). 373 This version of this YANG module is part of RFC XXXX; see 374 the RFC itself for full legal notices."; 376 // RFC Ed.: replace XXXX with actual RFC number and remove this 377 // note. 379 // RFC Ed.: update the date below with the date of RFC publication 380 // and remove this note. 381 revision 2012-10-22 { 382 description 383 "Initial revision."; 384 reference 385 "RFC XXXX: A YANG Data Model for Interface Management"; 386 } 388 /* Typedefs */ 390 typedef interface-ref { 391 type leafref { 392 path "/if:interfaces/if:interface/if:name"; 393 } 394 description 395 "This type is used by data models that need to reference 396 interfaces."; 397 } 399 /* Features */ 401 feature if-mib { 402 description 403 "This feature indicates that the server implements IF-MIB."; 404 reference 405 "RFC 2863: The Interfaces Group MIB"; 406 } 408 /* Data nodes */ 410 container interfaces { 411 description 412 "Interface parameters."; 414 list interface { 415 key "name"; 416 unique "type location"; 417 description 418 "The list of interfaces on the device."; 420 leaf name { 421 type string; 422 description 423 "An arbitrary name for the interface. 425 A device MAY restrict the allowed values for this leaf, 426 possibly depending on the type and location. 428 For example, if a device has a single array of 8 ethernet 429 ports, the name might be restricted to be on the form 430 'ethN', where N is an integer between '1' and '8'. 432 This leaf MAY be mapped to ifName by an implementation. 433 Such an implementation MAY restrict the allowed values for 434 this leaf so that it matches the restrictions of ifName. 435 If a NETCONF server that implements this restriction is 436 sent a value that doesn't match the restriction, it MUST 437 reply with an rpc-error with the error-tag 438 'invalid-value'."; 439 reference 440 "RFC 2863: The Interfaces Group MIB - ifName"; 441 } 443 leaf description { 444 type string; 445 description 446 "A textual description of the interface. 448 This leaf MAY be mapped to ifAlias by an implementation. 449 Such an implementation MAY restrict the allowed values for 450 this leaf so that it matches the restrictions of ifAlias. 451 If a NETCONF server that implements this restriction is 452 sent a value that doesn't match the restriction, it MUST 453 reply with an rpc-error with the error-tag 454 'invalid-value'."; 455 reference 456 "RFC 2863: The Interfaces Group MIB - ifAlias"; 457 } 459 leaf type { 460 type ianaift:iana-if-type; 461 mandatory true; 462 description 463 "The type of the interface. 465 When an interface entry is created, a server MAY 466 initialize the type leaf with a valid value, e.g., if it 467 is possible to derive the type from the name of the 468 interface."; 469 reference 470 "RFC 2863: The Interfaces Group MIB - ifType"; 471 } 473 leaf location { 474 type string; 475 description 476 "The device-specific location of the interface of a 477 particular type. The format of the location string 478 depends on the interface type and the device. 480 If the interface's type represents a physical interface, 481 this leaf MUST be set. 483 For example, if a device has a single array of 8 ethernet 484 ports, the location can be one of '1' to '8'. As another 485 example, if a device has N cards of M ports, the location 486 can be on the form 'n/m'. 488 When an interface entry is created, a server MAY 489 initialize the location leaf with a valid value, e.g., if 490 it is possible to derive the location from the name of 491 the interface."; 492 } 494 leaf enabled { 495 type boolean; 496 default "true"; 497 description 498 "The desired state of the interface. 500 This leaf contains the configured, desired state of the 501 interface. Systems that implement the IF-MIB use the 502 value of this leaf to set IF-MIB.ifAdminStatus to 'up' or 503 'down' after an ifEntry has been initialized, as described 504 in RFC 2863."; 505 reference 506 "RFC 2863: The Interfaces Group MIB - ifAdminStatus"; 507 } 509 leaf oper-status { 510 type enumeration { 511 enum up { 512 value 1; 513 description 514 "Ready to pass packets."; 515 } 516 enum down { 517 value 2; 518 } 519 enum testing { 520 value 3; 521 description 522 "In some test mode. No operational packets can 523 be passed."; 524 } 525 enum unknown { 526 value 4; 527 description 528 "Status can not be determined 529 for some reason."; 530 } 531 enum dormant { 532 value 5; 533 } 534 enum not-present { 535 value 6; 536 description 537 "Some component is missing."; 538 } 539 enum lower-layer-down { 540 value 7; 541 description 542 "Down due to state of lower-layer 543 interface(s)."; 544 } 545 } 546 config false; 547 description 548 "The current operational state of the interface. 550 If 'enabled' is 'false' then 'oper-status' 551 should be 'down'. If 'enabled' is changed to 'true' 552 then 'oper-status' should change to 'up' if the interface 553 is ready to transmit and receive network traffic; it 554 should change to 'dormant' if the interface is waiting for 555 external actions (such as a serial line waiting for an 556 incoming connection); it should remain in the 'down' state 557 if and only if there is a fault that prevents it from 558 going to the 'up' state; it should remain in the 559 'not-present' state if the interface has missing 560 (typically, hardware) components."; 562 reference 563 "RFC 2863: The Interfaces Group MIB - ifOperStatus"; 564 } 566 leaf last-change { 567 type yang:date-and-time; 568 config false; 569 description 570 "The time the interface entered its current operational 571 state. If the current state was entered prior to the 572 last re-initialization of the local network management 573 subsystem, then this node is not present."; 574 reference 575 "RFC 2863: The Interfaces Group MIB - ifLastChange"; 576 } 578 leaf if-index { 579 if-feature if-mib; 580 type int32 { 581 range "1..2147483647"; 582 } 583 config false; 584 description 585 "The ifIndex value for the ifEntry represented by this 586 interface. 588 Media-specific modules must specify how the type is 589 mapped to entries in the ifTable."; 590 reference 591 "RFC 2863: The Interfaces Group MIB - ifIndex"; 592 } 594 leaf mtu { 595 type uint32; 596 description 597 "The size, in octets, of the largest packet that the 598 interface can send and receive. This node might not be 599 valid for all interface types. 601 Media-specific modules must specify any restrictions on 602 the mtu for their interface type."; 603 reference 604 "RFC 2863: The Interfaces Group MIB - ifMtu"; 605 } 607 leaf link-up-down-trap-enable { 608 if-feature if-mib; 609 type enumeration { 610 enum enabled { 611 value 1; 612 } 613 enum disabled { 614 value 2; 615 } 616 } 617 description 618 "Indicates whether linkUp/linkDown SNMP notifications 619 should be generated for this interface. 621 If this node is not configured, the value 'enabled' is 622 operationally used by the server for interfaces which do 623 not operate on top of any other interface (i.e., there are 624 no 'lower-layer-if' entries), and 'disabled' otherwise."; 625 reference 626 "RFC 2863: The Interfaces Group MIB - 627 ifLinkUpDownTrapEnable"; 628 } 630 leaf phys-address { 631 type yang:phys-address; 632 config false; 633 description 634 "The interface's address at its protocol sub-layer. For 635 example, for an 802.x interface, this object normally 636 contains a MAC address. The interface's media-specific 637 modules must define the bit and byte ordering and the 638 format of the value of this object. For interfaces that do 639 not have such an address (e.g., a serial line), this node 640 is not present."; 641 reference 642 "RFC 2863: The Interfaces Group MIB - ifPhysAddress"; 643 } 645 leaf-list higher-layer-if { 646 type interface-ref; 647 config false; 648 description 649 "A list of references to interfaces layered on top of this 650 interface."; 651 reference 652 "RFC 2863: The Interfaces Group MIB - ifStackTable"; 653 } 655 leaf-list lower-layer-if { 656 type interface-ref; 657 config false; 658 description 659 "A list of references to interfaces layered underneath this 660 interface."; 661 reference 662 "RFC 2863: The Interfaces Group MIB - ifStackTable"; 663 } 665 leaf speed { 666 type yang:gauge64; 667 config false; 668 units "bits / second"; 669 description 670 "An estimate of the interface's current bandwidth in bits 671 per second. For interfaces which do not vary in 672 bandwidth or for those where no accurate estimation can 673 be made, this node should contain the nominal bandwidth. 674 For interfaces that has no concept of bandwidth, this 675 node is not present."; 676 reference 677 "RFC 2863: The Interfaces Group MIB - 678 ifSpeed, ifHighSpeed"; 679 } 681 container statistics { 682 config false; 683 description 684 "A collection of interface-related statistics objects."; 686 leaf discontinuity-time { 687 type yang:date-and-time; 688 description 689 "The time on the most recent occasion at which any one or 690 more of this interface's counters suffered a 691 discontinuity. If no such discontinuities have occurred 692 since the last re-initialization of the local management 693 subsystem, then this node contains the time the local 694 management subsystem re-initialized itself."; 695 } 697 leaf in-octets { 698 type yang:counter64; 699 description 700 "The total number of octets received on the interface, 701 including framing characters. 703 Discontinuities in the value of this counter can occur 704 at re-initialization of the management system, and at 705 other times as indicated by the value of 706 'discontinuity-time'."; 707 reference 708 "RFC 2863: The Interfaces Group MIB - ifHCInOctets"; 709 } 710 leaf in-unicast-pkts { 711 type yang:counter64; 712 description 713 "The number of packets, delivered by this sub-layer to a 714 higher (sub-)layer, which were not addressed to a 715 multicast or broadcast address at this sub-layer. 717 Discontinuities in the value of this counter can occur 718 at re-initialization of the management system, and at 719 other times as indicated by the value of 720 'discontinuity-time'."; 721 reference 722 "RFC 2863: The Interfaces Group MIB - ifHCInUcastPkts"; 723 } 724 leaf in-broadcast-pkts { 725 type yang:counter64; 726 description 727 "The number of packets, delivered by this sub-layer to a 728 higher (sub-)layer, which were addressed to a broadcast 729 address at this sub-layer. 731 Discontinuities in the value of this counter can occur 732 at re-initialization of the management system, and at 733 other times as indicated by the value of 734 'discontinuity-time'."; 735 reference 736 "RFC 2863: The Interfaces Group MIB - 737 ifHCInBroadcastPkts"; 738 } 739 leaf in-multicast-pkts { 740 type yang:counter64; 741 description 742 "The number of packets, delivered by this sub-layer to a 743 higher (sub-)layer, which were addressed to a multicast 744 address at this sub-layer. For a MAC layer protocol, 745 this includes both Group and Functional addresses. 747 Discontinuities in the value of this counter can occur 748 at re-initialization of the management system, and at 749 other times as indicated by the value of 750 'discontinuity-time'."; 751 reference 752 "RFC 2863: The Interfaces Group MIB - 753 ifHCInMulticastPkts"; 755 } 756 leaf in-discards { 757 type yang:counter32; 758 description 759 "The number of inbound packets which were chosen to be 760 discarded even though no errors had been detected to 761 prevent their being deliverable to a higher-layer 762 protocol. One possible reason for discarding such a 763 packet could be to free up buffer space. 765 Discontinuities in the value of this counter can occur 766 at re-initialization of the management system, and at 767 other times as indicated by the value of 768 'discontinuity-time'."; 769 reference 770 "RFC 2863: The Interfaces Group MIB - ifInDiscards"; 771 } 772 leaf in-errors { 773 type yang:counter32; 774 description 775 "For packet-oriented interfaces, the number of inbound 776 packets that contained errors preventing them from being 777 deliverable to a higher-layer protocol. For character- 778 oriented or fixed-length interfaces, the number of 779 inbound transmission units that contained errors 780 preventing them from being deliverable to a higher-layer 781 protocol. 783 Discontinuities in the value of this counter can occur 784 at re-initialization of the management system, and at 785 other times as indicated by the value of 786 'discontinuity-time'."; 787 reference 788 "RFC 2863: The Interfaces Group MIB - ifInErrors"; 789 } 790 leaf in-unknown-protos { 791 type yang:counter32; 792 description 793 "For packet-oriented interfaces, the number of packets 794 received via the interface which were discarded because 795 of an unknown or unsupported protocol. For 796 character-oriented or fixed-length interfaces that 797 support protocol multiplexing the number of transmission 798 units received via the interface which were discarded 799 because of an unknown or unsupported protocol. For any 800 interface that does not support protocol multiplexing, 801 this counter is not present. 803 Discontinuities in the value of this counter can occur 804 at re-initialization of the management system, and at 805 other times as indicated by the value of 806 'discontinuity-time'."; 807 reference 808 "RFC 2863: The Interfaces Group MIB - ifInUnknownProtos"; 809 } 811 leaf out-octets { 812 type yang:counter64; 813 description 814 "The total number of octets transmitted out of the 815 interface, including framing characters. 817 Discontinuities in the value of this counter can occur 818 at re-initialization of the management system, and at 819 other times as indicated by the value of 820 'discontinuity-time'."; 821 reference 822 "RFC 2863: The Interfaces Group MIB - ifHCOutOctets"; 823 } 824 leaf out-unicast-pkts { 825 type yang:counter64; 826 description 827 "The total number of packets that higher-level protocols 828 requested be transmitted, and which were not addressed 829 to a multicast or broadcast address at this sub-layer, 830 including those that were discarded or not sent. 832 Discontinuities in the value of this counter can occur 833 at re-initialization of the management system, and at 834 other times as indicated by the value of 835 'discontinuity-time'."; 836 reference 837 "RFC 2863: The Interfaces Group MIB - ifHCOutUcastPkts"; 838 } 839 leaf out-broadcast-pkts { 840 type yang:counter64; 841 description 842 "The total number of packets that higher-level protocols 843 requested be transmitted, and which were addressed to a 844 broadcast address at this sub-layer, including those 845 that were discarded or not sent. 847 Discontinuities in the value of this counter can occur 848 at re-initialization of the management system, and at 849 other times as indicated by the value of 850 'discontinuity-time'."; 852 reference 853 "RFC 2863: The Interfaces Group MIB - 854 ifHCOutBroadcastPkts"; 855 } 856 leaf out-multicast-pkts { 857 type yang:counter64; 858 description 859 "The total number of packets that higher-level protocols 860 requested be transmitted, and which were addressed to a 861 multicast address at this sub-layer, including those 862 that were discarded or not sent. For a MAC layer 863 protocol, this includes both Group and Functional 864 addresses. 866 Discontinuities in the value of this counter can occur 867 at re-initialization of the management system, and at 868 other times as indicated by the value of 869 'discontinuity-time'."; 870 reference 871 "RFC 2863: The Interfaces Group MIB - 872 ifHCOutMulticastPkts"; 873 } 874 leaf out-discards { 875 type yang:counter32; 876 description 877 "The number of outbound packets which were chosen to be 878 discarded even though no errors had been detected to 879 prevent their being transmitted. One possible reason 880 for discarding such a packet could be to free up buffer 881 space. 883 Discontinuities in the value of this counter can occur 884 at re-initialization of the management system, and at 885 other times as indicated by the value of 886 'discontinuity-time'."; 887 reference 888 "RFC 2863: The Interfaces Group MIB - ifOutDiscards"; 889 } 890 leaf out-errors { 891 type yang:counter32; 892 description 893 "For packet-oriented interfaces, the number of outbound 894 packets that could not be transmitted because of errors. 895 For character-oriented or fixed-length interfaces, the 896 number of outbound transmission units that could not be 897 transmitted because of errors. 899 Discontinuities in the value of this counter can occur 900 at re-initialization of the management system, and at 901 other times as indicated by the value of 902 'discontinuity-time'."; 903 reference 904 "RFC 2863: The Interfaces Group MIB - ifOutErrors"; 905 } 906 } 907 } 908 } 909 } 911 913 6. IANA Considerations 915 This document registers a URI in the IETF XML registry [RFC3688]. 916 Following the format in RFC 3688, the following registration is 917 requested to be made. 919 URI: urn:ietf:params:xml:ns:yang:ietf-interfaces 921 Registrant Contact: The IESG. 923 XML: N/A, the requested URI is an XML namespace. 925 This document registers a YANG module in the YANG Module Names 926 registry [RFC6020]. 928 name: ietf-interfaces 929 namespace: urn:ietf:params:xml:ns:yang:ietf-interfaces 930 prefix: if 931 reference: RFC XXXX 933 7. Security Considerations 935 The YANG module defined in this memo is designed to be accessed via 936 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 937 secure transport layer and the mandatory-to-implement secure 938 transport is SSH [RFC6242]. 940 There are a number of data nodes defined in the YANG module which are 941 writable/creatable/deletable (i.e., config true, which is the 942 default). These data nodes may be considered sensitive or vulnerable 943 in some network environments. Write operations (e.g., ) 944 to these data nodes without proper protection can have a negative 945 effect on network operations. These are the subtrees and data nodes 946 and their sensitivity/vulnerability: 948 /interfaces/interface: This list specifies the configured interfaces 949 on a device. Unauthorized access to this list could cause the 950 device to ignore packets it should receive and process. 952 /interfaces/interface/enabled: This leaf controls if an interface is 953 enabled or not. Unauthorized access to this leaf could cause the 954 device to ignore packets it should receive and process. 956 /interfaces/interface/mtu: Setting this leaf to a very small value 957 can be used to slow down interfaces. 959 8. Acknowledgments 961 The author wishes to thank Alexander Clemm, Per Hedeland, Ladislav 962 Lhotka, and Juergen Schoenwaelder for their helpful comments. 964 9. References 966 9.1. Normative References 968 [I-D.ietf-netmod-iana-if-type] 969 Bjorklund, M., "IANA Interface Type and Address Family 970 YANG Modules", draft-ietf-netmod-iana-if-type-02 (work in 971 progress), April 2012. 973 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 974 Requirement Levels", BCP 14, RFC 2119, March 1997. 976 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 977 MIB", RFC 2863, June 2000. 979 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 980 January 2004. 982 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 983 Network Configuration Protocol (NETCONF)", RFC 6020, 984 October 2010. 986 9.2. Informative References 988 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 989 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 990 STD 58, RFC 2579, April 1999. 992 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 993 Bierman, "Network Configuration Protocol (NETCONF)", 994 RFC 6241, June 2011. 996 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 997 Shell (SSH)", RFC 6242, June 2011. 999 Appendix A. Example: Ethernet Interface Module 1001 This section gives a simple example of how an Ethernet interface 1002 module could be defined. It demonstrates how media-specific 1003 configuration parameters can be conditionally augmented to the 1004 generic interface list. It is not intended as a complete module for 1005 ethernet configuration. 1007 module ex-ethernet { 1008 namespace "http://example.com/ethernet"; 1009 prefix "eth"; 1011 import ietf-interfaces { 1012 prefix if; 1013 } 1015 augment "/if:interfaces/if:interface" { 1016 when "if:type = 'ethernetCsmacd'"; 1018 container ethernet { 1019 must "../if:location" { 1020 description 1021 "An ethernet interface must specify the physical location 1022 of the ethernet hardware."; 1023 } 1024 choice transmission-params { 1025 case auto { 1026 leaf auto-negotiate { 1027 type empty; 1028 } 1029 } 1030 case manual { 1031 leaf duplex { 1032 type enumeration { 1033 enum "half"; 1034 enum "full"; 1035 } 1036 } 1037 leaf speed { 1038 type enumeration { 1039 enum "10Mb"; 1040 enum "100Mb"; 1041 enum "1Gb"; 1042 enum "10Gb"; 1043 } 1044 } 1045 } 1046 } 1047 // other ethernet specific params... 1048 } 1049 } 1050 } 1052 Appendix B. Example: Ethernet Bonding Interface Module 1054 This section gives an example of how interface layering can be 1055 defined. An ethernet bonding interface is defined, which bonds 1056 several ethernet interfaces into one logical interface. 1058 module ex-ethernet-bonding { 1059 namespace "http://example.com/ethernet-bonding"; 1060 prefix "bond"; 1062 import ietf-interfaces { 1063 prefix if; 1064 } 1066 augment "/if:interfaces/if:interface" { 1067 when "if:type = 'ieee8023adLag'"; 1069 leaf-list slave-if { 1070 type if:interface-ref; 1071 must "/if:interfaces/if:interface[if:name = current()]" 1072 + "/if:type = 'ethernetCsmacd'" { 1073 description 1074 "The type of a slave interface must be ethernet."; 1075 } 1076 } 1077 leaf bonding-mode { 1078 type enumeration { 1079 enum round-robin; 1080 enum active-backup; 1081 enum broadcast; 1082 } 1083 } 1084 // other bonding config params, failover times etc. 1085 } 1086 } 1088 Appendix C. Example: VLAN Interface Module 1090 This section gives an example of how a vlan interface module can be 1091 defined. 1093 module ex-vlan { 1094 namespace "http://example.com/vlan"; 1095 prefix "vlan"; 1097 import ietf-interfaces { 1098 prefix if; 1099 } 1101 augment "/if:interfaces/if:interface" { 1102 when "if:type = 'ethernetCsmacd' or 1103 if:type = 'ieee8023adLag'"; 1104 leaf vlan-tagging { 1105 type boolean; 1106 default false; 1107 } 1108 } 1110 augment "/if:interfaces/if:interface" { 1111 when "if:type = 'l2vlan'"; 1113 leaf base-interface { 1114 type if:interface-ref; 1115 must "/if:interfaces/if:interface[if:name = current()]" 1116 + "/vlan:vlan-tagging = true" { 1117 description 1118 "The base interface must have vlan tagging enabled."; 1119 } 1120 } 1121 leaf vlan-id { 1122 type uint16 { 1123 range "1..4094"; 1124 } 1125 must "../base-interface" { 1126 description 1127 "If a vlan-id is defined, a base-interface must 1128 be specified."; 1129 } 1130 } 1131 } 1132 } 1134 Appendix D. Example: NETCONF reply 1136 This section gives an example of a reply to the NETCONF request 1137 for a device that implements the example data models above. 1139 1142 1143 1145 1146 eth0 1147 ethernetCsmacd 1148 0 1149 true 1150 2 1151 1152 1153 eth1 1154 ethernetCsmacd 1155 1 1156 true 1157 7 1158 true 1160 1161 1162 1163 1165 Appendix E. ChangeLog 1167 RFC Editor: remove this section upon publication as an RFC. 1169 E.1. Version -07 1171 o Made leaf speed config false. 1173 E.2. Version -06 1175 o Added oper-status leaf. 1177 o Added leaf-lists higher-layer-if and lower-layer-if, that show the 1178 interface layering. 1180 o Added container statistics with counters. 1182 E.3. Version -05 1184 o Added an Informative References section. 1186 o Updated the Security Considerations section. 1188 o Clarified the behavior of an NETCONF server when invalid values 1189 are received. 1191 E.4. Version -04 1193 o Clarified why ifPromiscuousMode is not part of this data model. 1195 o Added a table that shows the mapping between this YANG data model 1196 and IF-MIB. 1198 E.5. Version -03 1200 o Added the section Relationship to the IF-MIB. 1202 o Changed if-index to be a leaf instead of leaf-list. 1204 o Explained the notation used in the data model tree picture. 1206 E.6. Version -02 1208 o Editorial fixes 1210 E.7. Version -01 1212 o Changed leaf "if-admin-status" to leaf "enabled". 1214 o Added Security Considerations 1216 Author's Address 1218 Martin Bjorklund 1219 Tail-f Systems 1221 Email: mbj@tail-f.com