idnits 2.17.1 draft-ding-rtgwg-arp-yang-model-00.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 9 instances of too long lines in the document, the longest one being 6 characters in excess of 72. == There are 2 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 154 has weird spacing: '...address yan...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (January 11, 2018) is 2290 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) == Missing Reference: 'RFC826' is mentioned on line 69, but not defined == Missing Reference: 'RFC6536' is mentioned on line 645, but not defined ** Obsolete undefined reference: RFC 6536 (Obsoleted by RFC 8341) == Unused Reference: 'RFC0826' is defined on line 683, but no explicit reference was found in the text Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 RTGWG X. Ding 2 Internet-Draft F. Zheng 3 Intended status: Standards Track Huawei 4 Expires: July 15, 2018 January 11, 2018 6 YANG Data Model for ARP 7 draft-ding-rtgwg-arp-yang-model-00 9 Abstract 11 This document defines a YANG data model to describe Address 12 Resolution Protocol (ARP) configurations. It is intended this model 13 be used by service providers who manipulate devices from different 14 vendors in a standard way. 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 https://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 July 15, 2018. 33 Copyright Notice 35 Copyright (c) 2018 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 (https://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 . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 54 3. Design of the Data Model . . . . . . . . . . . . . . . . . . 3 55 4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 5. Data Model Examples . . . . . . . . . . . . . . . . . . . . . 13 57 5.1. Static ARP entries . . . . . . . . . . . . . . . . . . . 13 58 5.2. ARP interfaces . . . . . . . . . . . . . . . . . . . . . 14 59 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 60 7. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 15 61 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 62 8.1. Normative References . . . . . . . . . . . . . . . . . . 15 63 8.2. Informative References . . . . . . . . . . . . . . . . . 15 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 66 1. Introduction 68 This document defines a YANG [RFC6020] data model for Address 69 Resolution Protocol [RFC826] implementation and identification of 70 some common properties within a device containing a Network 71 Configuration Protocol (NETCONF) server. Devices that are managed by 72 NETCONF and perhaps other mechanisms have common properties that need 73 to be configured and monitored in a standard way. 75 The data model convers configuration of system parameters of ARP, 76 such as static ARP entries, timeout for dynamic ARP entries, 77 interface ARP, proxy ARP, and so on. It also provides information 78 about running state of ARP implementations. 80 1.1. Terminology 82 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 83 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 84 "OPTIONAL" in this document are to be interpreted as described in BCP 85 14, [RFC2119]. 87 The following terms are defined in [RFC6241] and are not redefined 88 here: 90 o client 92 o configuration data 94 o server 95 o state data 97 1.2. Tree Diagrams 99 A simplified graphical representation of the data model is presented 100 in Section 3. 102 o Brackets "[" and "]" enclose list keys. 104 o Abbreviations before data node names: "rw" means configuration 105 (read-write) and "ro" state data (read-only). 107 o Symbols after data node names: "?" means an optional node, "!" 108 means a presence container, and "*" denotes a list and leaf-list. 110 o Parentheses enclose choice and case nodes, and case nodes are also 111 marked with a colon (":"). 113 o Ellipsis ("...") stands for contents of subtrees that are not 114 shown. 116 2. Problem Statement 118 This document defines a YANG [RFC7950] configuration data model that 119 may be used to configure the ARP feature running on a system. YANG 120 models can be used with network management protocols such as NETCONF 121 [RFC6241] to install, manipulate, and delete the configuration of 122 network devices. 124 The data model makes use of the YANG "feature" construct which allows 125 implementations to support only those ARP features that lie within 126 their capabilities. It is intended this model be used by service 127 providers who manipulate devices from different vendors in a standard 128 way. 130 This module can be used to configure the ARP applications for 131 discovering the link layer address associated with a given Internet 132 layer address. 134 3. Design of the Data Model 136 This data model intends to describe the processing that a protocol 137 finds the hardware address, also known as Media Access Control (MAC) 138 address, of a host from its known IP address. These tasks include, 139 but are not limited to, adding a static entry in the ARP cache, 140 configuring ARP cache entry timeout, and clearing dynamic entries 141 from the ARP cache. 143 This data model has one top level container, ARP, which consists of 144 several second level containers. Each of these second level 145 containers describes a particular category of ARP handling, such as 146 defining static mapping between an IP address (32-bit address) and a 147 Media Access Control (MAC) address (48-bit address). 149 module: ietf-arp 150 +--rw arp 151 +--rw arp-static-tables 152 | +--rw arp-static-table* [ip-address] 153 | +--rw ip-address inet:ipv4-address-no-zone 154 | +--rw mac-address yang:mac-address 155 +--ro arp-statistics 156 +--ro global-statistics 157 | +--ro requests-received? uint32 158 | +--ro replies-received? uint32 159 | +--ro gratuitous-received? uint32 160 | +--ro requests-sent? uint32 161 | +--ro replies-sent? uint32 162 | +--ro gratuitous-sent? uint32 163 | +--ro drops-received? uint32 164 | +--ro total-received? uint32 165 | +--ro total-sent? uint32 166 | +--ro arp-dynamic-count? uint32 167 | +--ro arp-static-count? uint32 168 +--ro local-statistics 169 +--ro arp-if-statistics* [if-name] 170 +--ro if-name -> /if:interfaces/interface/name 171 +--ro requests-received? uint32 172 +--ro replies-received? uint32 173 +--ro gratuitous-received? uint32 174 +--ro requests-sent? uint32 175 +--ro replies-sent? uint32 176 +--ro gratuitous-sent? uint32 177 augment /if:interfaces/if:interface/ip:ipv4/ip:neighbor: 178 augment /if:interfaces-state/if:interface/ip:ipv4/ip:neighbor: 179 +--ro vrf-name? arp:routing-instance-ref 180 +--ro expire-time? uint32 181 augment /if:interfaces/if:interface: 182 +--rw expire-time? uint32 183 +--rw arp-learn-disable? boolean 184 +--rw proxy-enable? boolean 185 +--rw probe-interval? uint8 186 +--rw probe-times? uint8 187 +--rw probe-unicast? boolean 188 +--rw arp-gratuitous? boolean 189 +--rw arp-gratuitous-interval? uint32 190 +--rw arp-gratuitous-drop? boolean 191 +--rw arp-if-limit* [vlan-id] 192 +--rw vlan-id uint16 193 +--rw limit-number uint32 194 +--rw threshold-value? uint32 195 augment /if:interfaces-state/if:interface: 196 +--ro requests-received? uint32 197 +--ro replies-received? uint32 198 +--ro gratuitous-received? uint32 199 +--ro requests-sent? uint32 200 +--ro replies-sent? uint32 201 +--ro gratuitous-sent? uint32 203 4. YANG Module 205 This section presents the YANG module for the ARP data model defined 206 in this document. 208 file "ietf-arp@2018-1-11.yang" 209 module ietf-arp { 210 namespace "urn:ietf:params:xml:ns:yang:ietf-arp"; 211 prefix arp; 213 // import some basic types 215 import ietf-inet-types { 216 prefix inet; 217 } 219 import ietf-yang-types { 220 prefix yang; 221 } 223 import ietf-interfaces { 224 prefix if; 225 } 227 import ietf-ip { 228 prefix ip; 229 } 231 import ietf-network-instance { 232 prefix ni; 233 } 234 organization 235 "IETF Routing Area Working Group (rtgwg)"; 236 contact 237 "WG Web: 238 WG List: 239 Editor: Xiaojian Ding 240 dingxiaojian1@huawei.com 241 Editor: Feng Zheng 242 habby.zheng@huawei.com"; 243 description 244 "Address Resolution Protocol (ARP) management, which includes 245 static ARP configuration, dynamic ARP learning, ARP entry query, 246 and packet statistics collection."; 248 revision 2017-10-18 { 249 description 250 "Init revision"; 251 reference 252 "RFC XXX: ARP (Address Resolution Protocol) YANG data model."; 253 } 255 /*grouping*/ 257 grouping arp-prob-grouping { 258 description 259 "Common configuration for all ARP probe."; 260 leaf probe-interval { 261 type uint8 { 262 range "1..5"; 263 } 264 units "second"; 265 description 266 "Interval for detecting dynamic ARP entries."; 267 } 268 leaf probe-times { 269 type uint8 { 270 range "0..10"; 271 } 272 description 273 "Number of aging probe attempts for a dynamic ARP entry. 274 If a device does not receive an ARP reply message after 275 the number of aging probe attempts reaches a specified 276 number, the dynamic ARP entry is deleted."; 277 } 278 leaf probe-unicast { 279 type boolean; 280 default "false"; 281 description 282 "Send unicast ARP aging probe messages for a dynamic ARP 283 entry."; 284 } 285 } 287 grouping arp-gratuitous-grouping { 288 description 289 "Configure gratuitous ARP."; 290 leaf arp-gratuitous { 291 type boolean; 292 default "false"; 293 description 294 "Enable or disable sending gratuitous-arp packet on 295 interface."; 296 } 297 leaf arp-gratuitous-interval { 298 type uint32 { 299 range "1..86400"; 300 } 301 units "second"; 302 description 303 "The interval of sending gratuitous-arp packet on the 304 interface."; 305 } 306 leaf arp-gratuitous-drop { 307 type boolean; 308 default "false"; 309 description 310 "Drop the receipt of gratuitous ARP packets on the interface."; 311 } 312 } 314 grouping arp-statistics-grouping { 315 description "IP ARP Statistics information"; 316 leaf requests-received { 317 type uint32; 318 description "Total ARP requests received"; 319 } 320 leaf replies-received { 321 type uint32; 322 description "Total ARP replies received"; 323 } 324 leaf gratuitous-received { 325 type uint32; 326 description "Total gratuitous ARP received"; 327 } 328 leaf requests-sent { 329 type uint32; 330 description "Total ARP requests sent"; 331 } 332 leaf replies-sent { 333 type uint32; 334 description "Total ARP replies sent"; 335 } 336 leaf gratuitous-sent { 337 type uint32; 338 description "Total gratuitous ARP sent"; 339 } 340 } 342 /* Typedefs */ 344 typedef routing-instance-ref { 345 type leafref { 346 path "/ni:network-instances/ni:network-instance/ni:name"; 347 } 348 description 349 "This type is used for leafs that reference a routing instance 350 configuration."; 351 } 353 /* Configuration data nodes */ 355 container arp { 356 description 357 "Address Resolution Protocol (ARP) management, which includes 358 static ARP configuration, dynamic ARP learning, ARP entry 359 query, and packet statistics collection."; 361 container arp-static-tables { 362 //config false; 363 description 364 "List of ARP entries that can be configured."; 365 list arp-static-table { 366 key "ip-address"; 367 description 368 "Short static ARP table. By default, the system ARP table is 369 empty, and address mappings are implemented by dynamic 370 ARP."; 372 leaf ip-address { 373 type inet:ipv4-address-no-zone; 374 description 375 "IP address, in dotted decimal notation."; 376 } 377 leaf mac-address { 378 type yang:mac-address; 379 mandatory true; 380 description 381 "MAC address in the format of H-H-H, in which H is 382 a hexadecimal number of 1 to 4 bits."; 383 } 385 } 386 }//End of arp-tables 388 container arp-statistics { 389 config false; 390 description 391 "List of ARP packet statistics."; 392 container global-statistics { 393 description 394 "ARP packet statistics."; 395 uses arp-statistics-grouping; 396 leaf drops-received { 397 type uint32 { 398 range "0..4294967294"; 399 } 400 description 401 "Number of ARP packets discarded."; 402 } 403 leaf total-received { 404 type uint32 { 405 range "0..4294967294"; 406 } 407 description 408 "Total number of ARP received packets."; 409 } 410 leaf total-sent { 411 type uint32 { 412 range "0..4294967294"; 413 } 414 description 415 "Total number of ARP sent packets."; 416 } 417 leaf arp-dynamic-count { 418 type uint32 { 419 range "0..4294967294"; 420 } 421 description 422 "Number of dynamic ARP count."; 423 } 424 leaf arp-static-count { 425 type uint32 { 426 range "0..4294967294"; 427 } 428 description 429 "Number of static ARP count."; 430 } 431 } 432 container local-statistics { 433 list arp-if-statistics { 434 key "if-name"; 435 description 436 "ARP statistics on interfaces. ARP statistics on all 437 interfaces are displayed in sequence."; 438 leaf if-name { 439 type leafref { 440 path "/if:interfaces/if:interface/if:name"; 441 } 442 description 443 "Name of an interface where ARP statistics to be 444 displayed reside."; 445 } 446 uses arp-statistics-grouping; 447 } 449 description 450 "foo"; 451 } 452 } 453 } 455 //End of arp-static-tables 457 augment "/if:interfaces/if:interface/ip:ipv4/ip:neighbor" 458 { 459 description 460 "Long static ARP table has been defined in 461 /if:interfaces/if:interface/ip:ipv4/ip:neighbor"; 462 } 463 augment "/if:interfaces-state/if:interface/ip:ipv4/ip:neighbor" { 464 description 465 "List of ARP entries that can be queried."; 467 leaf vrf-name { 468 type arp:routing-instance-ref; 469 config false; 470 description 471 "Name of the VPN instance to which an ARP entry 472 belongs."; 474 } 476 leaf expire-time { 478 type uint32 { 479 range "1..1440"; 480 } 481 config false; 482 description 483 "Aging time of a dynamic ARP entry. "; 484 } 486 } 488 augment "/if:interfaces/if:interface" { 489 description 490 "List of ARP Interface configurations.including the aging time, 491 probe interval, number of aging probe attempts, ARP 492 learning status, and ARP proxy."; 494 leaf expire-time { 495 type uint32 { 496 range "60..86400"; 497 } 498 units "second"; 499 description 500 "Aging time of a dynamic ARP entry."; 501 } 502 leaf arp-learn-disable { 503 type boolean; 504 default "false"; 505 description 506 "Whether dynamic ARP learning is disabled. 507 If the value is True, dynamic ARP learning 508 is disabled. If the value is False, dynamic 509 ARP learning is enabled."; 510 } 511 leaf proxy-enable { 512 type boolean; 513 default "false"; 514 description 515 "Enable proxy ARP."; 516 } 517 uses arp-prob-grouping; 518 uses arp-gratuitous-grouping; 520 list arp-if-limit { 521 key "vlan-id"; 522 description 523 "Maximum number of dynamic ARP entries that an 524 interface can learn. If the number of ARP 525 entries that an interface can learn changes 526 and the number of the learned ARP entries 527 exceeds the changed value, the interface cannot 528 learn additional ARP entries. The system prompts 529 you to delete the excess ARP entries."; 531 leaf vlan-id { 532 type uint16 { 533 range "0..4094"; 534 } 535 description 536 "ID of the VLAN where ARP learning is restricted. 537 This parameter can be set only on Layer 2 538 interfaces and sub-interfaces. Ethernet, GE, VE, 539 and Eth-Trunk interfaces can be both Layer 3 and 540 Layer 2 interfaces. When they work in Layer 3 mode, 541 they cannot have VLANs configured. When they work 542 in Layer 2 mode, they must have VLANs configured. 543 Ethernet, GE, and Eth-Trunk sub-interfaces can be 544 both common and QinQ sub-interfaces."; 545 } 546 leaf limit-number { 547 type uint32 { 548 range "1..65536"; 549 } 550 mandatory true; 551 description 552 "Maximum number of dynamic ARP entries that an 553 interface can learn."; 554 } 555 leaf threshold-value { 556 type uint32 { 557 range "60..100"; 558 } 559 must "not(not(../limit-number))"{ 560 description 561 "Upper boundary must be higher than lower boundary."; 562 } 563 description 564 "Alarm-Threshold for Maximum number of ARP entries 565 that an interface can learn."; 566 } 567 } 568 } 569 augment "/if:interfaces-state/if:interface" { 570 description 571 "ARP statistics on interfaces. ARP statistics on all 572 interfaces are displayed in sequence."; 573 uses arp-statistics-grouping; 574 } 575 // End of arp-statistics 577 } 579 581 5. Data Model Examples 583 This section presents a simple but complete example of configuring 584 static ARP entries and interfaces, based on the YANG module specified 585 in Section 4. 587 5.1. Static ARP entries 589 Requirement: 590 Enable common static ARP entry configuration. 591 592 593 594 10.2.2.3 595 00e0-fc01-0000 596 597 599 Requirement: 600 Enable long static ARP entry configuration. 601 602 603 604 __public__ 605 10.2.2.3 606 00e0-fc01-0000 607 GE1/0/1 608 609 611 5.2. ARP interfaces 613 Requirement: 614 Enable static ARP interface configuration. 616 617 618 619 GE1/0/1 620 1200 621 false 622 false 623 5 624 3 625 false 626 false 627 60 628 false 629 630 3 631 65535 632 80 633 634 635 637 6. Security Considerations 639 The YANG module defined in this document is designed to be accessed 640 via YANG based management protocols, such as NETCONF [RFC6241] and 641 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 642 implement secure transport layers (e.g., SSH, TLS) with mutual 643 authentication. 645 The NETCONF access control model (NACM) [RFC6536] provides the means 646 to restrict access for particular users to a pre-configured subset of 647 all available protocol operations and content. 649 These are the subtrees and data nodes and their sensitivity/ 650 vulnerability: 652 There are a number of data nodes defined in this YANG module that are 653 writable/creatable/deletable (i.e., config true, which is the 654 default). These data nodes may be considered sensitive or vulnerable 655 in some network environments. Write operations (e.g., edit-config) 656 to these data nodes without proper protection can have a negative 657 effect on network operations. 659 7. Conclusions 661 TBD. 663 8. References 665 8.1. Normative References 667 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 668 Requirement Levels", BCP 14, RFC 2119, 669 DOI 10.17487/RFC2119, March 1997, 670 . 672 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 673 the Network Configuration Protocol (NETCONF)", RFC 6020, 674 DOI 10.17487/RFC6020, October 2010, 675 . 677 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 678 RFC 7950, DOI 10.17487/RFC7950, August 2016, 679 . 681 8.2. Informative References 683 [RFC0826] Plummer, D., "Ethernet Address Resolution Protocol: Or 684 Converting Network Protocol Addresses to 48.bit Ethernet 685 Address for Transmission on Ethernet Hardware", STD 37, 686 RFC 826, DOI 10.17487/RFC0826, November 1982, 687 . 689 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 690 and A. Bierman, Ed., "Network Configuration Protocol 691 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 692 . 694 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 695 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 696 . 698 Authors' Addresses 700 Xiaojian Ding 701 Huawei 702 101 Software Avenue, Yuhua District 703 Nanjing, Jiangsu 210012 704 China 706 Email: dingxiaojian1@huawei.com 707 Feng Zheng 708 Huawei 709 101 Software Avenue, Yuhua District 710 Nanjing, Jiangsu 210012 711 China 713 Email: habby.zheng@huawei.com