idnits 2.17.1 draft-ding-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 13 instances of too long lines in the document, the longest one being 13 characters in excess of 72. == There are 1 instance 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 156 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 (October 26, 2017) is 2373 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 70, but not defined == Missing Reference: 'RFC6536' is mentioned on line 655, but not defined ** Obsolete undefined reference: RFC 6536 (Obsoleted by RFC 8341) == Unused Reference: 'RFC0826' is defined on line 693, 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. -------------------------------------------------------------------------------- 2 NETMOD WG D. Ding 3 Internet-Draft F. Zheng 4 Intended status: Standards Track Huawei 5 Expires: April 29, 2018 October 26, 2017 7 YANG Data Model for ARP 8 draft-ding-arp-yang-model-00 10 Abstract 12 This document defines a YANG data model to describe Address 13 Resolution Protocol (ARP) configurations. It is intended this model 14 be used by service providers who manipulate devices from different 15 vendors in a standard way. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on April 29, 2018. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 55 3. Design of the Data Model . . . . . . . . . . . . . . . . . . 3 56 4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 5. Data Model Examples . . . . . . . . . . . . . . . . . . . . . 13 58 5.1. Static ARP entries . . . . . . . . . . . . . . . . . . . 13 59 5.2. ARP interfaces . . . . . . . . . . . . . . . . . . . . . 14 60 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 61 7. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 15 62 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 63 8.1. Normative References . . . . . . . . . . . . . . . . . . 15 64 8.2. Informative References . . . . . . . . . . . . . . . . . 15 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 67 1. Introduction 69 This document defines a YANG [RFC6020] data model for Address 70 Resolution Protocol [RFC826] implementation and identification of 71 some common properties within a device containing a Network 72 Configuration Protocol (NETCONF) server. Devices that are managed by 73 NETCONF and perhaps other mechanisms have common properties that need 74 to be configured and monitored in a standard way. 76 The data model convers configuration of system parameters of ARP, 77 such as static ARP entries, timeout for dynamic ARP entries, 78 interface ARP, proxy ARP, and so on. It also provides information 79 about running state of ARP implementations. 81 1.1. Terminology 83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 85 "OPTIONAL" in this document are to be interpreted as described in BCP 86 14, [RFC2119]. 88 The following terms are defined in [RFC6241] and are not redefined 89 here: 91 o client 93 o configuration data 95 o server 96 o state data 98 1.2. Tree Diagrams 100 A simplified graphical representation of the data model is presented 101 in Section 3. 103 o Brackets "[" and "]" enclose list keys. 105 o Abbreviations before data node names: "rw" means configuration 106 (read-write) and "ro" state data (read-only). 108 o Symbols after data node names: "?" means an optional node, "!" 109 means a presence container, and "*" denotes a list and leaf-list. 111 o Parentheses enclose choice and case nodes, and case nodes are also 112 marked with a colon (":"). 114 o Ellipsis ("...") stands for contents of subtrees that are not 115 shown. 117 2. Problem Statement 119 This document defines a YANG [RFC7950] configuration data model that 120 may be used to configure the ARP feature running on a system. YANG 121 models can be used with network management protocols such as NETCONF 122 [RFC6241] to install, manipulate, and delete the configuration of 123 network devices. 125 The data model makes use of the YANG "feature" construct which allows 126 implementations to support only those ARP features that lie within 127 their capabilities. It is intended this model be used by service 128 providers who manipulate devices from different vendors in a standard 129 way. 131 This module can be used to configure the ARP applications for 132 discovering the link layer address associated with a given Internet 133 layer address. 135 3. Design of the Data Model 137 This data model intends to describe the processing that a protocol 138 finds the hardware address, also known as Media Access Control (MAC) 139 address, of a host from its known IP address. These tasks include, 140 but are not limited to, adding a static entry in the ARP cache, 141 configuring ARP cache entry timeout, and clearing dynamic entries 142 from the ARP cache. 144 This data model has one top level container, ARP, which consists of 145 several second level containers. Each of these second level 146 containers describes a particular category of ARP handling, such as 147 defining static mapping between an IP address (32-bit address) and a 148 Media Access Control (MAC) address (48-bit address). 150 module: ietf-arp 151 +--rw arp 152 +--rw arp-static-tables 153 | +--rw arp-static-table* [vrf-name ip-address] 154 | +--rw vrf-name arp:routing-instance-ref 155 | +--rw ip-address inet:ipv4-address-no-zone 156 | +--rw mac-address yang:mac-address 157 | +--rw if-name? leafref 158 +--rw arp-interfaces 159 | +--rw arp-interface* [if-name] 160 | +--rw if-name leafref 161 | +--rw expire-time? uint32 162 | +--rw arp-learn-disable? boolean 163 | +--rw proxy-enable? boolean 164 | +--rw probe-interval? uint8 165 | +--rw probe-times? uint8 166 | +--rw probe-unicast? boolean 167 | +--rw arp-gratuitous? boolean 168 | +--rw arp-gratuitous-interval? uint32 169 | +--rw arp-gratuitous-drop? boolean 170 | +--rw arp-if-limits 171 | +--rw arp-if-limit* [vlan-id] 172 | +--rw vlan-id uint16 173 | +--rw limit-number uint32 174 | +--rw threshold-value? uint32 175 +--ro arp-tables 176 | +--ro arp-table* [vrf-name ip-address] 177 | +--ro vrf-name arp:routing-instance-ref 178 | +--ro ip-address inet:ipv4-address-no-zone 179 | +--ro mac-address? yang:mac-address 180 | +--ro expire-time? uint32 181 | +--ro if-name? leafref 182 +--ro arp-statistics 183 +--ro global-statistics* 184 | +--ro requests-received? uint32 185 | +--ro replies-received? uint32 186 | +--ro gratuitous-received? uint32 187 | +--ro requests-sent? uint32 188 | +--ro replies-sent? uint32 189 | +--ro gratuitous-sent? uint32 190 | +--ro drops-received? uint32 191 | +--ro total-received? uint32 192 | +--ro total-sent? uint32 193 | +--ro arp-dynamic-count? uint32 194 | +--ro arp-static-count? uint32 195 +--ro arp-if-statistics* [if-name] 196 +--ro if-name leafref 197 +--ro requests-received? uint32 198 +--ro replies-received? uint32 199 +--ro gratuitous-received? uint32 200 +--ro requests-sent? uint32 201 +--ro replies-sent? uint32 202 +--ro gratuitous-sent? uint32 204 4. YANG Module 206 This section presents the YANG module for the ARP data model defined 207 in this document. 209 file "ietf-arp@2017-10-18.yang" 210 module ietf-arp { 211 namespace "urn:ietf:params:xml:ns:yang:ietf-arp"; 212 prefix arp; 214 // import some basic types 216 import ietf-inet-types { 217 prefix inet; 218 } 220 import ietf-yang-types { 221 prefix yang; 222 } 224 import ietf-interfaces { 225 prefix if; 226 } 228 import ietf-network-instance { 229 prefix ni; 230 } 231 organization 232 "IETF Netmod (Network Modeling) Working Group"; 233 contact 234 "WG Web: 235 WG List: 236 Editor: Xiaojian Ding 237 dingxiaojian1@huawei.com 238 Editor: Feng Zheng 239 habby.zheng@huawei.com"; 240 description 241 "Address Resolution Protocol (ARP) management, which includes 242 static ARP configuration, dynamic ARP learning, ARP entry query, 243 and packet statistics collection."; 245 revision 2017-10-18 { 246 description 247 "Init revision"; 248 reference 249 "RFC XXX: ARP (Address Resolution Protocol) YANG data model."; 250 } 252 /*grouping*/ 254 grouping arp-prob-grouping { 255 description 256 "Common configuration for all ARP probe."; 257 leaf probe-interval { 258 type uint8 { 259 range "1..5"; 260 } 261 units "second"; 262 description 263 "Interval for detecting dynamic ARP entries."; 264 } 265 leaf probe-times { 266 type uint8 { 267 range "0..10"; 268 } 269 description 270 "Number of aging probe attempts for a dynamic ARP entry. If 271 a device does not receive an ARP reply message after the number 272 of aging probe attempts reaches a specified number, the 273 dynamic ARP entry is deleted."; 274 } 275 leaf probe-unicast { 276 type boolean; 277 default "false"; 278 description 279 "Send unicast ARP aging probe messages for a dynamic ARP 280 entry."; 281 } 282 } 283 grouping arp-gratuitous-grouping { 284 description 285 "Configure gratuitous ARP."; 286 leaf arp-gratuitous { 287 type boolean; 288 default "false"; 289 description 290 "Enable or disable sending gratuitous-arp packet on 291 interface."; 292 } 293 leaf arp-gratuitous-interval { 294 type uint32 { 295 range "1..86400"; 296 } 297 units "second"; 298 description 299 "The interval of sending gratuitous-arp packet on the 300 interface."; 301 } 302 leaf arp-gratuitous-drop { 303 type boolean; 304 default "false"; 305 description 306 "Drop the receipt of gratuitous ARP packets on the interface."; 307 } 308 } 310 grouping arp-statistics-grouping { 311 description "IP ARP statistics information"; 312 leaf requests-received { 313 type uint32; 314 description "Total ARP requests received"; 315 } 316 leaf replies-received { 317 type uint32; 318 description "Total ARP replies received"; 319 } 320 leaf gratuitous-received { 321 type uint32; 322 description "Total gratuitous ARP received"; 323 } 324 leaf requests-sent { 325 type uint32; 326 description "Total ARP requests sent"; 327 } 328 leaf replies-sent { 329 type uint32; 330 description "Total ARP replies sent"; 332 } 333 leaf gratuitous-sent { 334 type uint32; 335 description "Total gratuituous ARP sent"; 336 } 337 } 339 /* Typedefs */ 341 typedef routing-instance-ref { 342 type leafref { 343 path "/ni:network-instances/ni:network-instance/ni:name"; 344 } 345 description 346 "This type is used for leafs that reference a routing instance 347 configuration."; 348 } 350 /* Configuration data nodes */ 352 container arp { 353 description 354 "Address Resolution Protocol (ARP) management, which includes 355 static ARP configuration, dynamic ARP learning, ARP entry 356 query, and packet statistics collection."; 358 container arp-static-tables { 359 description 360 "List of static ARP configurations."; 361 list arp-static-table { 362 key "vrf-name ip-address"; 363 description 364 "Static ARP table. By default, the system ARP table is 365 empty, and address mappings are implemented by dynamic 366 ARP."; 367 leaf vrf-name { 368 type arp:routing-instance-ref; 369 description 370 "Name of a VPN instance. This parameter is used to 371 support the VPN feature. If this parameter is 372 set, it indicates that the ARP entry is in the 373 associated VLAN."; 374 } 375 leaf ip-address { 376 type inet:ipv4-address-no-zone; 377 description 378 "IP address, in dotted decimal notation."; 379 } 380 leaf mac-address { 381 type yang:mac-address; 382 mandatory true; 383 description 384 "MAC address in the format of H-H-H, in which H is 385 a hexadecimal number of 1 to 4 bits. "; 386 } 387 leaf if-name { 388 type leafref { 389 path "/if:interfaces/if:interface/if:name"; 390 } 391 description 392 "Name of the ARP outbound interface."; 393 } 394 } 395 }//End of arp-static-tables 397 container arp-interfaces { 398 description 399 "List of ARP Interface configurations."; 400 list arp-interface { 401 key "if-name"; 402 description 403 "ARP interface configuration, including the aging time, 404 probe interval, number of aging probe attempts, ARP 405 learning status, and ARP proxy."; 406 leaf if-name { 407 type leafref { 408 path "/if:interfaces/if:interface/if:name"; 409 } 410 description 411 "Name of the interface that has learned dynamic ARP 412 entries."; 413 } 414 leaf expire-time { 415 type uint32 { 416 range "60..86400"; 417 } 418 units "second"; 419 description 420 "Aging time of a dynamic ARP entry."; 421 } 422 leaf arp-learn-disable { 423 type boolean; 424 default "false"; 425 description 426 "Whether dynamic ARP learning is disabled. If the value 427 is True, dynamic ARP learning is disabled. If the value 428 is False, dynamic ARP learning is enabled."; 429 } 430 leaf proxy-enable { 431 type boolean; 432 default "false"; 433 description 434 "Enable proxy ARP."; 435 } 436 uses arp-prob-grouping; 437 uses arp-gratuitous-grouping; 439 container arp-if-limits { 440 description 441 "Maximum number of dynamic ARP entries that an interface 442 can learn."; 443 list arp-if-limit { 444 key "vlan-id"; 445 description 446 "Maximum number of dynamic ARP entries that an 447 interface can learn. If the number of ARP entries that 448 an interface can learn changes and the number of the 449 learned ARP entries exceeds the changed value, the 450 interface cannot learn additional ARP entries. The 451 system prompts you to delete the excess ARP entries."; 452 leaf vlan-id { 453 type uint16 { 454 range "0..4094"; 455 } 456 description 457 "ID of the VLAN where ARP learning is restricted. 458 This parameter can be set only on Layer 2 interfaces 459 and sub-interfaces. Ethernet, GE, VE, and Eth-Trunk 460 interfaces can be both Layer 3 and Layer 2 461 interfaces. When they work in Layer 3 mode, they 462 cannot have VLANs configured. When they work in Layer 463 2 mode, they must have VLANs configured. Ethernet, 464 GE, and Eth-Trunk sub-interfaces can be both common 465 and QinQ sub-interfaces. "; 466 } 467 leaf limit-number { 468 type uint32 { 469 range "1..65536"; 470 } 471 mandatory true; 472 description 473 "Maximum number of dynamic ARP entries that an 474 interface can learn."; 475 } 476 leaf threshold-value { 477 type uint32 { 478 range "60..100"; 479 } 480 must "not(not(../limit-number))"{ 481 description 482 "Upper boundary must be higher than lower boundary."; 483 } 484 description 485 "Alarm-Threshold for maximum number of ARP entries 486 that an interface can learn."; 487 } 488 } 489 }//End of arp-if-limits 490 } 491 }// End of arp-interfaces 493 container arp-tables { 494 config false; 495 description 496 "List of ARP entries that can be queried."; 497 list arp-table { 498 key "vrf-name ip-address"; 499 description 500 "Query ARP entries, including static, dynamic, and 501 interface-based ARP entries."; 502 leaf vrf-name { 503 type arp:routing-instance-ref; 504 description 505 "Name of the VPN instance to which an ARP entry 506 belongs."; 507 } 508 leaf ip-address { 509 type inet:ipv4-address-no-zone; 510 description 511 "IP address, in dotted decimal notation."; 512 } 513 leaf mac-address { 514 type yang:mac-address; 515 description 516 "MAC address in the format of H-H-H, in which H is a 517 hexadecimal number of 1 to 4 bits. "; 518 } 519 leaf expire-time { 520 type uint32 { 521 range "1..1440"; 522 } 523 description 524 "Aging time of a dynamic ARP entry. "; 525 } 526 leaf if-name { 527 type leafref { 528 path "/if:interfaces/if:interface/if:name"; 529 } 530 description 531 "Type and number of the interface that has learned ARP 532 entries."; 533 } 534 } 535 }//End of arp-tables 537 container arp-statistics { 538 config false; 539 description 540 "List of ARP packet statistics."; 541 list global-statistics { 542 description 543 "ARP packet statistics."; 544 uses arp-statistics-grouping; 545 leaf drops-received { 546 type uint32 { 547 range "0..4294967294"; 548 } 549 description 550 "Number of ARP packets discarded."; 551 } 552 leaf total-received { 553 type uint32 { 554 range "0..4294967294"; 555 } 556 description 557 "Total number of ARP received packets."; 558 } 559 leaf total-sent { 560 type uint32 { 561 range "0..4294967294"; 562 } 563 description 564 "Total number of ARP sent packets."; 565 } 566 leaf arp-dynamic-count { 567 type uint32 { 568 range "0..4294967294"; 569 } 570 description 571 "Number of dynamic ARP count."; 573 } 574 leaf arp-static-count { 575 type uint32 { 576 range "0..4294967294"; 577 } 578 description 579 "Number of static ARP count."; 580 } 581 } 582 list arp-if-statistics { 583 key "if-name"; 584 description 585 "ARP statistics on interfaces. ARP statistics on all 586 interfaces are displayed in sequence."; 587 leaf if-name { 588 type leafref { 589 path "/if:interfaces/if:interface/if:name"; 590 } 591 description 592 "Name of an interface where ARP statistics to be 593 displayed reside."; 594 } 595 uses arp-statistics-grouping; 596 } 597 }// End of arp-statistics 598 } 599 } 600 602 5. Data Model Examples 604 This section presents a simple but complete example of configuring 605 static ARP entries and interfaces, based on the YANG module specified 606 in Section 4. 608 5.1. Static ARP entries 609 Requirement: 610 Enable static ARP entry configuration. 611 612 613 614 __public__ 615 10.2.2.3 616 00e0-fc01-0000 617 GE1/0/1 618 619 621 5.2. ARP interfaces 623 Requirement: 624 Enable static ARP interface configuration. 626 627 628 629 GE1/0/1 630 1200 631 false 632 false 633 5 634 3 635 false 636 false 637 60 638 false 639 640 3 641 65535 642 80 643 644 645 647 6. Security Considerations 649 The YANG module defined in this document is designed to be accessed 650 via YANG based management protocols, such as NETCONF [RFC6241] and 651 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 652 implement secure transport layers (e.g., SSH, TLS) with mutual 653 authentication. 655 The NETCONF access control model (NACM) [RFC6536] provides the means 656 to restrict access for particular users to a pre-configured subset of 657 all available protocol operations and content. 659 These are the subtrees and data nodes and their sensitivity/ 660 vulnerability: 662 There are a number of data nodes defined in this YANG module that are 663 writable/creatable/deletable (i.e., config true, which is the 664 default). These data nodes may be considered sensitive or vulnerable 665 in some network environments. Write operations (e.g., edit-config) 666 to these data nodes without proper protection can have a negative 667 effect on network operations. 669 7. Conclusions 671 TBD. 673 8. References 675 8.1. Normative References 677 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 678 Requirement Levels", BCP 14, RFC 2119, 679 DOI 10.17487/RFC2119, March 1997, 680 . 682 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 683 the Network Configuration Protocol (NETCONF)", RFC 6020, 684 DOI 10.17487/RFC6020, October 2010, 685 . 687 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 688 RFC 7950, DOI 10.17487/RFC7950, August 2016, 689 . 691 8.2. Informative References 693 [RFC0826] Plummer, D., "Ethernet Address Resolution Protocol: Or 694 Converting Network Protocol Addresses to 48.bit Ethernet 695 Address for Transmission on Ethernet Hardware", STD 37, 696 RFC 826, DOI 10.17487/RFC0826, November 1982, 697 . 699 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 700 and A. Bierman, Ed., "Network Configuration Protocol 701 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 702 . 704 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 705 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 706 . 708 Authors' Addresses 710 Xiaojian Ding 711 Huawei 712 101 Software Avenue, Yuhua District 713 Nanjing, Jiangsu 210012 714 China 716 Email: dingxiaojian1@huawei.com 718 Feng Zheng 719 Huawei 720 101 Software Avenue, Yuhua District 721 Nanjing, Jiangsu 210012 722 China 724 Email: habby.zheng@huawei.com