idnits 2.17.1 draft-ding-rtgwg-arp-yang-model-02.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 22 instances of too long lines in the document, the longest one being 18 characters in excess of 72. ** There are 2 instances of lines with control characters in the document. == 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 203 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 (June 28, 2018) is 2128 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 77, but not defined == Missing Reference: 'RFC6536' is mentioned on line 583, but not defined ** Obsolete undefined reference: RFC 6536 (Obsoleted by RFC 8341) == Unused Reference: 'I-D.ietf-netmod-rfc7223bis' is defined on line 606, but no explicit reference was found in the text == Unused Reference: 'RFC0826' is defined on line 636, but no explicit reference was found in the text ** Downref: Normative reference to an Unknown state RFC: RFC 1027 Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 RTGWG X. Ding 3 Internet-Draft F. Zheng 4 Intended status: Standards Track Huawei 5 Expires: December 30, 2018 R. Wilton 6 Cisco Systems 7 June 28, 2018 9 YANG Data Model for ARP 10 draft-ding-rtgwg-arp-yang-model-02 12 Abstract 14 This document defines a YANG data model to describe Address 15 Resolution Protocol (ARP) configurations. The data model performs as 16 a guideline for configuring ARP capabilities on a system. It is 17 intended this model be used by service providers who manipulate 18 devices from different vendors in a standard way. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on December 30, 2018. 37 Copyright Notice 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Design of the Data Model . . . . . . . . . . . . . . . . . . 4 59 3.1. ARP Caching . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.2. proxy ARP . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.3. gratuitous ARP . . . . . . . . . . . . . . . . . . . . . 4 62 3.4. ietf-arp Module . . . . . . . . . . . . . . . . . . . . . 5 63 4. ARP YANG Module . . . . . . . . . . . . . . . . . . . . . . . 5 64 5. Data Model Examples . . . . . . . . . . . . . . . . . . . . . 12 65 5.1. Static ARP Entries . . . . . . . . . . . . . . . . . . . 12 66 5.2. ARP Dynamic Learning . . . . . . . . . . . . . . . . . . 12 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 68 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 69 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 70 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 71 8.2. Informative References . . . . . . . . . . . . . . . . . 14 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 74 1. Introduction 76 This document defines a YANG [RFC7950] data model for Address 77 Resolution Protocol [RFC826] implementation and identification of 78 some common properties within a device. Devices have common 79 properties that need to be configured and monitored in a standard 80 way. This document is intended to present universal ARP protocol 81 configuration and many vendors can implement it. 83 The data model convers configuration of system parameters of ARP, 84 such as static ARP entries, timeout for dynamic ARP entries, 85 interface ARP, proxy ARP, and so on. It also provides information 86 about running state of ARP implementations. 88 1.1. Terminology 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 92 "OPTIONAL" in this document are to be interpreted as described in BCP 93 14, [RFC2119]. 95 The following terms are defined in [RFC6241] and are not redefined 96 here: 98 o client 100 o configuration data 102 o server 104 o state data 106 1.2. Tree Diagrams 108 A simplified graphical representation of the data model is presented 109 in Section 3. 111 o Brackets "[" and "]" enclose list keys. 113 o Abbreviations before data node names: "rw" means configuration 114 (read-write) and "ro" state data (read-only). 116 o Symbols after data node names: "?" means an optional node, "!" 117 means a presence container, and "*" denotes a list and leaf-list. 119 o Parentheses enclose choice and case nodes, and case nodes are also 120 marked with a colon (":"). 122 o Ellipsis ("...") stands for contents of subtrees that are not 123 shown. 125 Tree diagrams used in this document use the notation defined in 126 [RFC8340]. 128 2. Problem Statement 130 This document defines a YANG [RFC7950] configuration data model that 131 may be used to configure the ARP feature running on a system. Data 132 model "ietf-ip" [I-D.ietf-netmod-rfc7277bis] covers the address 133 mapping functionality. However, this functionality is strictly 134 dependent on IPv4 networks, and many ARP related functionalities are 135 missing, e.g. device global ARP entries and control, configuration 136 related to dynamic ARP learning, proxy ARP, gratuitous ARP, etc. 138 The data model makes use of the YANG "feature" construct which allows 139 implementations to support only those ARP features that lie within 140 their capabilities. It is intended this model be used by service 141 providers who manipulate devices from different vendors in a standard 142 way. 144 This model can be used to configure the ARP applications for 145 discovering the link layer address associated with a given Internet 146 layer address. 148 3. Design of the Data Model 150 This data model intends to describe the processing that a protocol 151 finds the hardware address, also known as Media Access Control (MAC) 152 address, of a host from its known IP address. These tasks include, 153 but are not limited to, adding a static entry in the ARP cache, 154 configuring dynamic ARP learning, proxy ARP, gratuitous ARP. There 155 are two kind of ARP configurations: global ARP configuration, which 156 is across all interfaces on the device, and per interface ARP 157 configuration. 159 3.1. ARP Caching 161 ARP caching is the method of storing network addresses and the 162 associated data-link addresses in memory for a period of time as the 163 addresses are learned. This minimizes the use of valuable network 164 resources to broadcast for the same address each time a datagram is 165 sent. 167 There are static ARP cache entries and dynamic ARP cache entries. 168 Static entries are manually configured and kept in the cache table on 169 a permanent basis. Dynamic entries are added by vendor software, 170 kept for a period of time, and then removed. We can specify how long 171 an entry remains in the ARP cache. If we specify a timeout of 0 172 seconds, entries are never cleared from the ARP cache. 174 3.2. proxy ARP 176 Proxy ARP [RFC1027] can be configured to enable the switch to respond 177 to ARP queries for network addresses by offering its own Ethernet 178 media access control (MAC) address. With proxy ARP enabled, the 179 switch captures and routes traffic to the intended destination. 181 3.3. gratuitous ARP 183 Gratuitous ARP requests help detect duplicate IP addresses. A 184 gratuitous ARP is a broadcast request for a router's own IP address. 185 If a router or switch sends an ARP request for its own IP address and 186 no ARP replies are received, the router- or switch-assigned IP 187 address is not being used by other nodes. However, if a router or 188 switch sends an ARP request for its own IP address and an ARP reply 189 is received, the router- or switch-assigned IP address is already 190 being used by another node. 192 3.4. ietf-arp Module 194 This module has one top level container, ARP, which consists of two 195 second level containers, which are used for static entries 196 configuration and global parameters control. 198 module: ietf-arp 199 +--rw arp 200 +--rw global-static-entries {global-static-entries}? 201 | +--rw static-entry* [ip-address] 202 | +--rw ip-address inet:ipv4-address-no-zone 203 | +--rw mac-address yang:mac-address 204 +--rw global-control 205 +--rw enable-learning? boolean 206 +--rw enable-proxy? boolean 207 augment /if:interfaces/if:interface: 208 +--rw arp-dynamic-learning 209 +--rw expire-time? yang:timeticks 210 +--rw learn-disable? boolean 211 +--rw proxy 212 | +--rw mode? enumeration 213 +--rw probe 214 | +--rw interval? uint8 215 | +--rw times? uint8 216 | +--rw unicast? boolean 217 +--rw gratuitous 218 | +--rw enable? boolean 219 | +--rw interval? uint32 220 | +--rw drop? boolean 221 +--ro statistics 222 +--ro in-requests-pkts? uint16 223 +--ro in-replies-pkts? uint16 224 +--ro in-gratuitous-pkts? uint16 225 +--ro out-requests-pkts? uint16 226 +--ro out-replies-pkts? uint16 227 +--ro out-gratuitous-pkts? uint16 228 augment /if:interfaces/if:interface/ip:ipv4/ip:neighbor: 229 +--ro remaining-expire-time? uint32 231 4. ARP YANG Module 233 This section presents the ARP YANG module defined in this document. 234 This YANG module imports typedefs from [RFC6991]. 236 file "ietf-arp@2018-01-27.yang" 237 module ietf-arp { 238 yang-version 1.1; 239 namespace "urn:ietf:params:xml:ns:yang:ietf-arp"; 240 prefix arp; 242 import ietf-inet-types { 243 prefix inet; 244 reference "RFC 6991: INET Types Model"; 245 } 247 import ietf-yang-types { 248 prefix yang; 249 reference "RFC 6991: yang Types Model"; 250 } 252 import ietf-interfaces { 253 prefix if; 254 description 255 "A Network Management Datastore Architecture (NMDA) 256 compatible version of the ietf-interfaces module 257 is required."; 258 } 259 import ietf-ip { 260 prefix ip; 261 description 262 "A Network Management Datastore Architecture (NMDA) 263 compatible version of the ietf-ip module is 264 required."; 265 } 267 organization 268 "IETF Routing Area Working Group (rtgwg)"; 269 contact 270 "WG Web: 271 WG List: 272 Editor: Xiaojian Ding 273 dingxiaojian1@huawei.com 274 Editor: Feng Zheng 275 habby.zheng@huawei.com 276 Editor: Robert Wilton 277 rwilton@cisco.com"; 278 description 279 "Address Resolution Protocol (ARP) management, which includes 280 static ARP configuration, dynamic ARP learning, ARP entry query, 281 and packet statistics collection."; 283 revision 2018-01-27 { 284 description 285 "Init revision"; 286 // NOTE TO RFC EDITOR: 287 // Please replace the following reference 288 // to draft-ding-rtgwg-arp-yang-model-02 with 289 // RFC number when published (i.e. RFC xxxx). 290 reference 291 "draft-ding-rtgwg-arp-yang-model-02"; 292 } 294 /* 295 * Features 296 */ 298 feature global-static-entries { 299 description 300 "This feature indicates that the device allows static entries 301 to be configured globally."; 302 } 304 container arp { 305 description 306 "Address Resolution Protocol (ARP) management, which includes 307 static ARP configuration, dynamic ARP learning, ARP entry 308 query, and packet statistics collection."; 310 container global-static-entries { 311 if-feature "global-static-entries"; 312 description 313 "Set a global static ARP entry, which is independent of the interface."; 314 list static-entry { 315 key "ip-address"; 316 description 317 "List of ARP static entries that can be configured globally."; 318 leaf ip-address { 319 type inet:ipv4-address-no-zone; 320 description 321 "IP address, in dotted decimal notation."; 322 } 323 leaf mac-address { 324 type yang:mac-address; 325 mandatory true; 326 description 327 "MAC address in the format of H-H-H, in which H is 328 a hexadecimal number of 1 to 4 bits."; 329 } 330 } 331 } 332 container global-control { 333 description 334 "Set global control parameters, which are independent of interface."; 335 leaf enable-learning { 336 type boolean; 337 default "true"; 338 description 339 "Enables or disables global dynamic ARP learning. 340 If 'true', then enforcement is enabled. 341 If 'false', then enforcement is disabled."; 342 } 343 leaf enable-proxy { 344 type boolean; 345 default "true"; 346 description 347 "Proxy ARP is enabled by default; perform this 348 task to globally disable proxy ARP on all interfaces."; 349 } 350 } 351 } 352 augment "/if:interfaces/if:interface" { 353 description 354 "Augment interface configuration with parameters of ARP."; 355 container arp-dynamic-learning { 356 description 357 "Support for ARP configuration on interfaces."; 358 leaf expire-time { 359 type yang:timeticks { 360 range "60..86400"; 361 } 362 units "second"; 363 description 364 "Aging time of a dynamic ARP entry."; 365 } 366 leaf learn-disable { 367 type boolean; 368 default "false"; 369 description 370 "Whether dynamic ARP learning is disabled on an interface. 371 If the value is True, dynamic ARP learning is disabled. 372 If the value is False, dynamic ARP learning is enabled."; 373 } 375 container proxy { 376 description 377 "Configuration parameters for proxy ARP"; 378 leaf mode { 379 type enumeration { 380 enum DISABLE { 381 description 382 "The system should not respond to ARP requests that 383 do not specify an IP address configured on the local 384 subinterface as the target address."; 385 } 386 enum REMOTE_ONLY { 387 description 388 "The system responds to ARP requests only when the 389 sender and target IP addresses are in different 390 subnets."; 391 } 392 enum ALL { 393 description 394 "The system responds to ARP requests where the sender 395 and target IP addresses are in different subnets, as well 396 as those where they are in the same subnet."; 397 } 398 } 399 default "DISABLE"; 400 description 401 "When set to a value other than DISABLE, the local system should 402 respond to ARP requests that are for target addresses other than 403 those that are configured on the local subinterface using its own 404 MAC address as the target hardware address. If the REMOTE_ONLY 405 value is specified, replies are only sent when the target address 406 falls outside the locally configured subnets on the interface, 407 whereas with the ALL value, all requests, regardless of their 408 target address are replied to."; 409 reference "RFC1027: Using ARP to Implement Transparent Subnet Gateways"; 410 } 411 } 413 container probe { 414 description 415 "Common configuration parameters for all ARP probe."; 416 leaf interval { 417 type uint8 { 418 range "1..5"; 419 } 420 units "second"; 421 description 422 "Interval for detecting dynamic ARP entries."; 423 } 424 leaf times { 425 type uint8 { 426 range "0..10"; 427 } 428 description 429 "Number of aging probe attempts for a dynamic ARP entry. 430 If a device does not receive an ARP reply message after 431 the number of aging probe attempts reaches a specified 432 number,thedynamic ARP entry is deleted."; 433 } 434 leaf unicast { 435 type boolean; 436 default "false"; 437 description 438 "Send unicast ARP aging probe messages for a dynamic ARP 439 entry."; 440 } 441 } 443 container gratuitous { 444 description 445 "Configure gratuitous ARP."; 446 leaf enable { 447 type boolean; 448 default "false"; 449 description 450 "Enable or disable sending gratuitous-arp packet on 451 interface."; 452 } 453 leaf interval { 454 type uint32 { 455 range "1..86400"; 456 } 457 units "second"; 458 description 459 "The interval of sending gratuitous-arp packet on the 460 interface."; 461 } 462 leaf drop { 463 type boolean; 464 default "false"; 465 description 466 "Drop the receipt of gratuitous ARP packets on the interface."; 467 } 468 } 470 container statistics { 471 config false; 472 description 473 "IP ARP Statistics information on interfaces"; 474 leaf in-requests-pkts { 475 type uint16; 476 description 477 "Total ARP requests received"; 478 } 479 leaf in-replies-pkts { 480 type uint16; 481 description 482 "Total ARP replies received"; 483 } 484 leaf in-gratuitous-pkts { 485 type uint16; 486 description 487 "Total gratuitous ARP received"; 488 } 489 leaf out-requests-pkts { 490 type uint16; 491 description 492 "Total ARP requests sent"; 493 } 494 leaf out-replies-pkts { 495 type uint16; 496 description 497 "Total ARP replies sent"; 498 } 499 leaf out-gratuitous-pkts { 500 type uint16; 501 description 502 "Total gratuitous ARP sent"; 503 } 504 } 505 } 506 } 508 augment "/if:interfaces/if:interface/ip:ipv4/ip:neighbor" { 509 description 510 "Augment neighbor list with parameters of ARP, 511 eg., support for remaining expire time query on interfaces."; 512 leaf remaining-expire-time { 513 type uint32; 514 config false; 515 description 516 "Remaining expire time of a dynamic ARP entry. "; 517 } 518 } 520 } 521 5. Data Model Examples 523 This section presents a simple but complete example of configuring 524 static ARP entries and dynamic learning, based on the YANG modules 525 specified in Section 4. 527 5.1. Static ARP Entries 529 Requirement: 530 Enable static ARP entry global configuration (not rely on interface). 531 532 533 534 10.2.2.3 535 00e0-fc01-0000 536 537 539 Requirement: 540 Enable static ARP entry configuration on interface (defined in 541 draft [I-D.ietf-netmod-rfc7277bis]). 542 543 544 545 10.2.2.3 546 00e0-fc01-0000 547 GE1/0/1 548 549 551 5.2. ARP Dynamic Learning 552 Requirement: 553 Enable ARP dynamic learning configuration. 555 556 557 GE1/0/1 558 1200 559 false 560 561 DISABLE 562 563 564 5 565 3 566 false 567 568 569 false 570 60 571 false 572 573 575 6. Security Considerations 577 The YANG module defined in this document is designed to be accessed 578 via YANG based management protocols, such as NETCONF [RFC6241] and 579 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 580 implement secure transport layers (e.g., SSH, TLS) with mutual 581 authentication. 583 The NETCONF access control model (NACM) [RFC6536] provides the means 584 to restrict access for particular users to a pre-configured subset of 585 all available protocol operations and content. 587 These are the subtrees and data nodes and their sensitivity/ 588 vulnerability: 590 There are a number of data nodes defined in this YANG module that are 591 writable/creatable/deletable (i.e., config true, which is the 592 default). These data nodes may be considered sensitive or vulnerable 593 in some network environments. Write operations (e.g., edit-config) 594 to these data nodes without proper protection can have a negative 595 effect on network operations. 597 7. Acknowledgments 599 The authors wish to thank Alex Campbell and Reshad Rahman, Qin Wu, 600 many others for their helpful comments. 602 8. References 604 8.1. Normative References 606 [I-D.ietf-netmod-rfc7223bis] 607 Bjorklund, M., "A YANG Data Model for Interface 608 Management", draft-ietf-netmod-rfc7223bis-03 (work in 609 progress), January 2018. 611 [I-D.ietf-netmod-rfc7277bis] 612 Bjorklund, M., "A YANG Data Model for IP Management", 613 draft-ietf-netmod-rfc7277bis-03 (work in progress), 614 January 2018. 616 [RFC1027] Carl-Mitchell, S. and J. Quarterman, "Using ARP to 617 implement transparent subnet gateways", RFC 1027, 618 DOI 10.17487/RFC1027, October 1987, 619 . 621 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 622 Requirement Levels", BCP 14, RFC 2119, 623 DOI 10.17487/RFC2119, March 1997, 624 . 626 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 627 RFC 6991, DOI 10.17487/RFC6991, July 2013, 628 . 630 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 631 RFC 7950, DOI 10.17487/RFC7950, August 2016, 632 . 634 8.2. Informative References 636 [RFC0826] Plummer, D., "An Ethernet Address Resolution Protocol: Or 637 Converting Network Protocol Addresses to 48.bit Ethernet 638 Address for Transmission on Ethernet Hardware", STD 37, 639 RFC 826, DOI 10.17487/RFC0826, November 1982, 640 . 642 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 643 and A. Bierman, Ed., "Network Configuration Protocol 644 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 645 . 647 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 648 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 649 . 651 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 652 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 653 . 655 Authors' Addresses 657 Xiaojian Ding 658 Huawei 659 101 Software Avenue, Yuhua District 660 Nanjing, Jiangsu 210012 661 China 663 Email: dingxiaojian1@huawei.com 665 Feng Zheng 666 Huawei 667 101 Software Avenue, Yuhua District 668 Nanjing, Jiangsu 210012 669 China 671 Email: habby.zheng@huawei.com 673 Robert Wilton 674 Cisco Systems 676 Email: rwilton@cisco.com