idnits 2.17.1 draft-vassilev-bmwg-network-interconnect-tester-06.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 == Line 225 has weird spacing: '...-stream uin...' == Line 257 has weird spacing: '...-stream uin...' == Line 312 has weird spacing: '...rw type ide...' == Line 519 has weird spacing: '...The raw frame...' -- The document date (July 11, 2021) is 1018 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC6991' is defined on line 1179, but no explicit reference was found in the text == Unused Reference: 'RFC7224' is defined on line 1183, but no explicit reference was found in the text == Unused Reference: 'RFC7950' is defined on line 1187, but no explicit reference was found in the text == Unused Reference: 'IEEE1588' is defined on line 1197, but no explicit reference was found in the text == Unused Reference: 'IEEE802.3-2014' is defined on line 1200, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 10 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group V. Vassilev 3 Internet-Draft Lightside Instruments AS 4 Intended status: Standards Track July 11, 2021 5 Expires: January 12, 2022 7 A YANG Data Model for Network Interconnect Tester Management 8 draft-vassilev-bmwg-network-interconnect-tester-06 10 Abstract 12 This document introduces new YANG model for use in network 13 interconnect testing containing modules of traffic generator and 14 traffic analyzer. 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 January 12, 2022. 33 Copyright Notice 35 Copyright (c) 2021 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.1.1. Definitions and Acronyms . . . . . . . . . . . . . . 2 53 1.1.2. Tree Diagram . . . . . . . . . . . . . . . . . . . . 3 54 1.2. Problem Statement . . . . . . . . . . . . . . . . . . . . 3 55 1.3. Objectives . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.4. Solution . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Using the network interconnect tester model . . . . . . . . . 5 58 3. Traffic Generator Module Tree Diagram . . . . . . . . . . . . 5 59 4. Traffic Analyzer Module Tree Diagram . . . . . . . . . . . . 6 60 5. Traffic Generator Module YANG . . . . . . . . . . . . . . . . 8 61 6. Traffic Analyzer Module YANG . . . . . . . . . . . . . . . . 15 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 63 7.1. URI Registration . . . . . . . . . . . . . . . . . . . . 23 64 7.2. YANG Module Name Registration . . . . . . . . . . . . . . 24 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 24 66 8.1. ietf-traffic-generator.yang . . . . . . . . . . . . . . . 24 67 8.2. ietf-traffic-analyzer.yang . . . . . . . . . . . . . . . 25 68 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 69 9.1. Normative References . . . . . . . . . . . . . . . . . . 25 70 9.2. Informative References . . . . . . . . . . . . . . . . . 26 71 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 26 72 A.1. Basic Test Program . . . . . . . . . . . . . . . . . . . 26 73 A.2. Generating RFC2544 Testframes . . . . . . . . . . . . . . 28 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 28 76 1. Introduction 78 There is a need for standard mechanism to allow the specification and 79 implementation of the transactions part of network tests. The 80 mechanism should allow the control and monitoring of the data plane 81 traffic in a transactional way. This document defines two YANG 82 modules for test traffic generator and analyzer. 84 The YANG modules in this document conform to the Network Management 85 Datastore Architecture (NMDA) defined in RFC 8342. 87 1.1. Terminology 89 1.1.1. Definitions and Acronyms 91 DUT: Device Under Test 93 TA: Traffic Analyzer 95 TG: Traffic Generator 97 1.1.2. Tree Diagram 99 For a reference to the annotations used in tree diagrams included in 100 this document, please see YANG Tree Diagrams [RFC8340]. 102 1.2. Problem Statement 104 Network interconnect tests require active network elements part of 105 the tested network that generate test traffic and network elements 106 that analyze the test traffic at one or more points of its path. A 107 network interconnect tester is a device that can either generate test 108 traffic, analyze test traffic or both. Here is a figure borrowed 109 from [RFC2544] representing the horseshoe test setup topology 110 consisting of a single tester and a single DUT connected in a network 111 interconnect loop. 113 +------------+ 114 | | 115 +------------| tester |<-------------+ 116 | | | | 117 | +------------+ | 118 | | 119 | +------------+ | 120 | | | | 121 +----------->| DUT |--------------+ 122 | | 123 +------------+ 125 This document attempts to address the problem of defining YANG model 126 of a network interconnect tester that can be used for development of 127 vendor independent network interconnect tests and utilize the 128 advantages of transactional management using standard protocols like 129 NETCONF. 131 1.3. Objectives 133 This section describes some of the design objectives for the model. 134 It should: 136 o provide means to specify the generated traffic as streams of 137 cyclic sequence of bursts with configurable frame size, frame 138 data, interframe gap and interburst gap. 140 o have a mandatory single stream mode and optional multi stream 141 mode. 143 o provide means for configuration of traffic streams with static 144 frame data where frames with identical frame data are sent during 145 the lifetime of the stream. 147 o provide means for configuration of traffic streams with dynamic 148 frame data where frames contain fields with dynamic data like 149 generation time and sequence number. 151 o allow third parties to augment the base module with alternative 152 dynamic fields of frame data extensions. 154 o provide means for realtime synchronization and orchestration of 155 the generated streams. 157 o provide counters for received test traffic frames and octets. 159 o provide latency statistic in the case of test traffic with dynamic 160 frame data that includes timestamp. 162 o provide sequence number errors in the case of test traffic with 163 dynamic frame data that includes sequence number. 165 1.4. Solution 167 The proposed model splits the design into 2 modules - 1) Traffic 168 Generator module (TG), 2) Traffic Analyzer module (TA). The modules 169 are implemented as augmentations of the ietf-interfaces [RFC8343] 170 module adding configuration and state data that models the 171 functionality of a network interconnect tester. The TA and TG 172 modules concept is illustrated with the following diagram of a tester 173 with two interfaces (named e0 and e1) connected in a loop with single 174 DUT: 176 +----------------+ 177 e0.egress | | e1.ingress 178 +------------| TG tester TA |<-------------+ 179 | | | | 180 | +----------------+ | 181 | | 182 | +------------+ | 183 | | | | 184 +------------->| DUT |----------------+ 185 | | 186 +------------+ 188 2. Using the network interconnect tester model 190 Basic example of how the model can be used in transactional network 191 test program to control the testers part of a network and report 192 counter statistics and timing measurement data is presented in 193 Appendix A. All example cases present the configuration and state 194 data from a single test trial. The search algorithm logic that 195 operates to control the trial configuration is outside the scope of 196 this document. One of the examples demonstrates the use of the 197 [RFC2544] defined testframe packet. 199 3. Traffic Generator Module Tree Diagram 201 module: ietf-traffic-generator 202 augment /if:interfaces/if:interface: 203 +--rw traffic-generator {egress-direction}? 204 | +--rw (type)? 205 | | +--:(single-stream) 206 | | | +--rw testframe-type? identityref 207 | | | +--rw frame-size uint32 208 | | | +--rw frame-data? string 209 | | | +--rw interframe-gap uint32 210 | | | +--rw interburst-gap? uint32 211 | | | +--rw frames-per-burst? uint32 212 | | | +--rw src-mac-address? yang:mac-address {ethernet}? 213 | | | +--rw dst-mac-address? yang:mac-address {ethernet}? 214 | | | +--rw ether-type? uint16 {ethernet}? 215 | | +--:(multi-stream) 216 | | +--rw streams 217 | | +--rw stream* [id] 218 | | +--rw id uint32 219 | | +--rw testframe-type? identityref 220 | | +--rw frame-size uint32 221 | | +--rw frame-data? string 222 | | +--rw interframe-gap uint32 223 | | +--rw interburst-gap? uint32 224 | | +--rw frames-per-burst? uint32 225 | | +--rw frames-per-stream uint32 226 | | +--rw interstream-gap uint32 227 | | +--rw src-mac-address? 228 | | | yang:mac-address {ethernet}? 229 | | +--rw dst-mac-address? 230 | | | yang:mac-address {ethernet}? 231 | | +--rw ether-type? uint16 {ethernet}? 232 | +--rw realtime-epoch? 233 | | yang:date-and-time {realtime-epoch}? 234 | +--rw total-frames? uint64 235 +--rw traffic-generator-ingress {ingress-direction}? 236 +--rw (type)? 237 | +--:(single-stream) 238 | | +--rw testframe-type? identityref 239 | | +--rw frame-size uint32 240 | | +--rw frame-data? string 241 | | +--rw interframe-gap uint32 242 | | +--rw interburst-gap? uint32 243 | | +--rw frames-per-burst? uint32 244 | | +--rw src-mac-address? yang:mac-address {ethernet}? 245 | | +--rw dst-mac-address? yang:mac-address {ethernet}? 246 | | +--rw ether-type? uint16 {ethernet}? 247 | +--:(multi-stream) 248 | +--rw streams 249 | +--rw stream* [id] 250 | +--rw id uint32 251 | +--rw testframe-type? identityref 252 | +--rw frame-size uint32 253 | +--rw frame-data? string 254 | +--rw interframe-gap uint32 255 | +--rw interburst-gap? uint32 256 | +--rw frames-per-burst? uint32 257 | +--rw frames-per-stream uint32 258 | +--rw interstream-gap uint32 259 | +--rw src-mac-address? 260 | | yang:mac-address {ethernet}? 261 | +--rw dst-mac-address? 262 | | yang:mac-address {ethernet}? 263 | +--rw ether-type? 264 | uint16 {ethernet}? 265 +--rw realtime-epoch? 266 | yang:date-and-time {realtime-epoch}? 267 +--rw total-frames? uint64 269 4. Traffic Analyzer Module Tree Diagram 271 module: ietf-traffic-analyzer 272 augment /if:interfaces/if:interface: 273 +--rw traffic-analyzer! {ingress-direction}? 274 | +--rw filter! {filter}? 275 | | +--rw type identityref 276 | | +--rw ether-type? uint16 277 | +--rw capture {capture}? 278 | | +--rw start-trigger 279 | | | +--rw (start-trigger)? 280 | | | +--:(frame-index) 281 | | | | +--rw frame-index? uint64 282 | | | +--:(testframe-index) 283 | | | +--rw testframe-index? uint64 284 | | +--rw stop-trigger 285 | | +--rw (stop-trigger)? 286 | | +--:(when-full) 287 | | +--rw when-full? empty 288 | +--ro state 289 | +--ro pkts? yang:counter64 290 | +--ro octets? yang:counter64 291 | +--ro idle-octets? yang:counter64 {idle-octets-counter}? 292 | +--ro errors? yang:counter64 293 | +--ro testframe-stats 294 | | +--ro testframe-pkts? yang:counter64 295 | | +--ro sequence-errors? yang:counter64 296 | | +--ro payload-errors? yang:counter64 297 | | +--ro latency 298 | | +--ro samples? uint64 299 | | +--ro min? uint64 300 | | +--ro max? uint64 301 | | +--ro average? uint64 302 | | +--ro latest? uint64 303 | +--ro capture {capture}? 304 | +--ro frame* [sequence-number] 305 | +--ro sequence-number uint64 306 | +--ro timestamp? yang:date-and-time 307 | +--ro length? uint32 308 | +--ro preceding-interframe-gap? uint32 309 | +--ro data? string 310 +--rw traffic-analyzer-egress! {egress-direction}? 311 +--rw filter! {filter}? 312 | +--rw type identityref 313 +--rw capture {capture}? 314 | +--rw start-trigger 315 | | +--rw (start-trigger)? 316 | | +--:(frame-index) 317 | | | +--rw frame-index? uint64 318 | | +--:(testframe-index) 319 | | +--rw testframe-index? uint64 320 | +--rw stop-trigger 321 | +--rw (stop-trigger)? 322 | +--:(when-full) 323 | +--rw when-full? empty 324 +--ro state 325 +--ro pkts? yang:counter64 326 +--ro octets? yang:counter64 327 +--ro idle-octets? yang:counter64 {idle-octets-counter}? 328 +--ro errors? yang:counter64 329 +--ro testframe-stats 330 | +--ro testframe-pkts? yang:counter64 331 | +--ro sequence-errors? yang:counter64 332 | +--ro payload-errors? yang:counter64 333 | +--ro latency 334 | +--ro samples? uint64 335 | +--ro min? uint64 336 | +--ro max? uint64 337 | +--ro average? uint64 338 | +--ro latest? uint64 339 +--ro capture {capture}? 340 +--ro frame* [sequence-number] 341 +--ro sequence-number uint64 342 +--ro timestamp? yang:date-and-time 343 +--ro length? uint32 344 +--ro preceding-interframe-gap? uint32 345 +--ro data? string 347 5. Traffic Generator Module YANG 349 file "ietf-traffic-generator@2021-07-11.yang" 351 module ietf-traffic-generator { 352 yang-version 1.1; 353 namespace "urn:ietf:params:xml:ns:yang:ietf-traffic-generator"; 354 prefix tg; 356 import ietf-interfaces { 357 prefix if; 358 reference 359 "RFC 8343: A YANG Data Model For Interface Management"; 360 } 361 import ietf-yang-types { 362 prefix yang; 363 reference 364 "RFC 6991: Common YANG Data Types"; 365 } 366 import iana-if-type { 367 prefix ianaift; 368 reference 369 "RFC 7224: IANA Interface Type YANG Module"; 370 } 372 organization 373 "IETF Benchmarking Methodology Working Group"; 374 contact 375 "WG Web: 376 WG List: 378 Editor: Vladimir Vassilev 379 "; 381 description 382 "This module contains a collection of YANG definitions for 383 description and management of network interconnect testers. 385 Copyright (c) 2021 IETF Trust and the persons identified as 386 authors of the code. All rights reserved. 388 Redistribution and use in source and binary forms, with or 389 without modification, is permitted pursuant to, and subject 390 to the license terms contained in, the Simplified BSD License 391 set forth in Section 4.c of the IETF Trust's Legal Provisions 392 Relating to IETF Documents 393 (http://trustee.ietf.org/license-info). 394 This version of this YANG module is part of RFC XXXX; see 395 the RFC itself for full legal notices."; 397 revision 2021-07-11 { 398 description 399 "Initial revision."; 400 reference 401 "RFC XXXX: A YANG Data Model for 402 Network Interconnect Tester Management"; 403 } 405 feature egress-direction { 406 description 407 "The device can generate traffic in the egress direction."; 408 } 410 feature ingress-direction { 411 description 412 "The device can generate traffic in the ingress direction."; 413 } 415 feature multi-stream { 416 description 417 "The device can generate multi-stream traffic."; 418 } 420 feature ethernet { 421 description 422 "The device can generate ethernet traffic."; 423 } 425 feature realtime-epoch { 426 description 427 "The device can generate traffic precisely 428 at configured realtime epoch."; 430 } 432 identity testframe-type { 433 description 434 "Base identity for all testframe types."; 435 } 437 identity static { 438 base testframe-type; 439 description 440 "Identity for static testframe. 441 The frame data and size are constant."; 442 } 444 identity dynamic { 445 base testframe-type; 446 description 447 "Identity to be used as base for dynamic 448 testframe type identities defined 449 in external modules. 451 When used itself it identifies dynamic testframe 452 where the last 18 octets of the payload contain 453 incrementing sequence number field (8 octets) 454 followed by timestamp field in the 455 IEEE 1588-2008 format (10 octets). If frame data is defined 456 for the last 18 octets of the payload it will be ignored 457 and overwritten with dynamic data according to this 458 specification."; 459 } 461 grouping common-data { 462 description 463 "Common configuration data."; 464 leaf realtime-epoch { 465 if-feature "realtime-epoch"; 466 type yang:date-and-time; 467 description 468 "If this leaf is present the stream generation will start 469 at the specified realtime epoch."; 470 } 471 leaf total-frames { 472 type uint64; 473 description 474 "If this leaf is present the traffic generation will stop 475 after the specified number of frames are generated."; 476 } 477 } 478 grouping burst-data { 479 description 480 "Generated traffic burst parameters."; 481 leaf testframe-type { 482 type identityref { 483 base tg:testframe-type; 484 } 485 default "tg:static"; 486 description 487 "In case of dynamic testframes this leaf specifies 488 the dynamic testframe identity."; 489 } 490 leaf frame-size { 491 type uint32; 492 mandatory true; 493 description 494 "Size of the frames generated. For example for 495 ethernet interfaces the following definition 496 applies: 498 Ethernet frame-size in octets includes: 499 * Destination Address (6 octets), 500 * Source Address (6 octets), 501 * Frame Type (2 octets), 502 * Data (min 46 octets or 42 octets + 4 octets 802.1Q tag), 503 * CRC Checksum (4 octets). 505 Ethernet frame-size does not include: 506 * Preamble (dependent on MAC configuration 507 by default 7 octets), 508 * Start of frame delimiter (1 octet) 510 Minimum standard ethernet frame-size is 64 bytes but 511 generators might support smaller sizes for validation."; 512 } 513 leaf frame-data { 514 type string { 515 pattern '([0-9A-F]{2})*'; 516 } 517 must 'string-length(.)<=(../frame-size*2)'; 518 description 519 "The raw frame data specified as hexadecimal string. 520 The specified data can be shorter then the ../frame-size 521 value specifying only the header or the header and the 522 payload with or without the 4 byte CRC Checksum 523 in the case of a Ethernet frame."; 524 } 525 leaf interframe-gap { 526 type uint32; 527 mandatory true; 528 description 529 "Length of the idle period between generated frames. 530 For example for ethernet interfaces the following 531 definition applies: 533 Ethernet interframe-gap between transmission of frames 534 known as the interframe gap (IFG). A brief recovery time 535 between frames allows devices to prepare for 536 reception of the next frame. The minimum 537 interframe gap is 96 bit times (12 octet times) (the time it 538 takes to transmit 96 bits (12 octets) of raw data on the 539 medium). However the preamble (7 octets) and start of 540 frame delimiter (1 octet) are considered a constant gap that 541 should be included in the interframe-gap. Thus the minimum 542 value for standard ethernet transmission should be considered 543 20 octets."; 544 } 545 leaf interburst-gap { 546 type uint32; 547 description 548 "Similar to the interframe-gap but takes place between 549 any two bursts of the stream."; 550 } 551 leaf frames-per-burst { 552 type uint32; 553 description 554 "Number of frames contained in a burst"; 555 } 556 } 558 grouping multi-stream-data { 559 description 560 "Multi stream traffic generation parameters."; 561 container streams { 562 description 563 "Non-presence container holding the configured stream list."; 564 list stream { 565 key "id"; 566 description 567 "Each stream repeats a burst until frames-per-stream 568 count is reached followed by interstream-gap delay."; 569 leaf id { 570 type uint32; 571 description 572 "Number specifying the order of the stream."; 573 } 574 uses burst-data; 575 leaf frames-per-stream { 576 type uint32; 577 mandatory true; 578 description 579 "The count of frames to be generated before 580 generation of the next stream is started."; 581 } 582 leaf interstream-gap { 583 type uint32; 584 mandatory true; 585 description 586 "Idle period after the last frame of the last burst."; 587 } 588 } 589 } 590 } 592 grouping ethernet-data { 593 description 594 "Ethernet frame data specific parameters."; 595 reference 596 "IEEE 802-2014 Clause 9.2"; 597 leaf src-mac-address { 598 type yang:mac-address; 599 description 600 "Source Address field of the generated Ethernet packet."; 601 } 602 leaf dst-mac-address { 603 type yang:mac-address; 604 description 605 "Destination Address field of the generated Ethernet packet."; 606 } 607 leaf ether-type { 608 type uint16; 609 description 610 "Length/Type field of the generated Ethernet packet."; 611 } 612 } 614 augment "/if:interfaces/if:interface" { 615 description 616 "Traffic generator augmentations of ietf-interfaces."; 617 container traffic-generator { 618 if-feature "egress-direction"; 619 description 620 "Traffic generator for egress direction."; 621 choice type { 622 description 623 "Choice of the type of the data model of the generator. 624 Single or multi stream."; 625 case single-stream { 626 uses burst-data; 627 } 628 case multi-stream { 629 uses multi-stream-data; 630 } 631 } 632 uses common-data; 633 } 634 container traffic-generator-ingress { 635 if-feature "ingress-direction"; 636 description 637 "Traffic generator for ingress direction."; 638 choice type { 639 description 640 "Choice of the type of the data model of the generator. 641 Single or multi stream."; 642 case single-stream { 643 uses burst-data; 644 } 645 case multi-stream { 646 uses multi-stream-data; 647 } 648 } 649 uses common-data; 650 } 651 } 653 augment "/if:interfaces/if:interface/tg:traffic-generator/tg:type/" 654 + "tg:single-stream" { 655 when "derived-from-or-self(../if:type, 'ianaift:ethernetCsmacd')" { 656 description 657 "Ethernet interface type."; 658 } 659 if-feature "ethernet"; 660 description 661 "Ethernet specific augmentation for egress 662 single stream generator type."; 663 uses ethernet-data; 664 } 666 augment "/if:interfaces/if:interface/tg:traffic-generator/" 667 + "tg:type/tg:multi-stream/tg:streams/tg:stream" { 668 when "derived-from-or-self(../../../if:type," 669 + "'ianaift:ethernetCsmacd')" { 671 description 672 "Ethernet interface type."; 673 } 674 if-feature "ethernet"; 675 description 676 "Ethernet specific augmentation for egress 677 multi stream generator type."; 678 uses ethernet-data; 679 } 681 augment "/if:interfaces/if:interface/tg:traffic-generator-ingress/" 682 + "tg:type/tg:single-stream" { 683 when "derived-from-or-self(../if:type, 'ianaift:ethernetCsmacd')" { 684 description 685 "Ethernet interface type."; 686 } 687 if-feature "ethernet"; 688 description 689 "Ethernet specific augmentation for ingress 690 single stream generator type."; 691 uses ethernet-data; 692 } 694 augment "/if:interfaces/if:interface/tg:traffic-generator-ingress/" 695 + "tg:type/tg:multi-stream/tg:streams/tg:stream" { 696 when "derived-from-or-self(../../../if:type," 697 + "'ianaift:ethernetCsmacd')" { 698 description 699 "Ethernet interface type."; 700 } 701 if-feature "ethernet"; 702 description 703 "Ethernet specific augmentation for ingress 704 multi stream generator type."; 705 uses ethernet-data; 706 } 707 } 709 711 6. Traffic Analyzer Module YANG 713 file "ietf-traffic-analyzer@2021-07-11.yang" 715 module ietf-traffic-analyzer { 716 yang-version 1.1; 717 namespace "urn:ietf:params:xml:ns:yang:ietf-traffic-analyzer"; 718 prefix ta; 719 import ietf-interfaces { 720 prefix if; 721 reference 722 "RFC 8343: A YANG Data Model For Interface Management"; 723 } 724 import ietf-yang-types { 725 prefix yang; 726 reference 727 "RFC 6991: Common YANG Data Types"; 728 } 730 organization 731 "IETF Benchmarking Methodology Working Group"; 732 contact 733 "WG Web: 734 WG List: 736 Editor: Vladimir Vassilev 737 "; 738 description 739 "This module contains a collection of YANG definitions for 740 description and management of network interconnect testers. 742 Copyright (c) 2021 IETF Trust and the persons identified as 743 authors of the code. All rights reserved. 745 Redistribution and use in source and binary forms, with or 746 without modification, is permitted pursuant to, and subject 747 to the license terms contained in, the Simplified BSD License 748 set forth in Section 4.c of the IETF Trust's Legal Provisions 749 Relating to IETF Documents 750 (http://trustee.ietf.org/license-info). 752 This version of this YANG module is part of RFC XXXX; see 753 the RFC itself for full legal notices."; 755 revision 2021-07-11 { 756 description 757 "Initial revision."; 758 reference 759 "RFC XXXX: A YANG Data Model for 760 Network Interconnect Tester Management"; 761 } 763 feature egress-direction { 764 description 765 "The device can analyze traffic from the egress direction."; 766 } 767 feature ingress-direction { 768 description 769 "The device can generate traffic from the ingress direction."; 770 } 772 feature filter { 773 description 774 "This feature indicates that the device implements 775 filter that can specify a subset of packets to be 776 analyzed when filtering is enabled."; 777 } 779 feature idle-octets-counter { 780 description 781 "This feature indicates that the device implements 782 idle-octets counter that accumulates the time 783 the link is not utilized. The minimum required 784 idle gaps are not counted as idle octets."; 785 } 786 feature capture { 787 description 788 "This feature indicates that the device implements 789 packet capture functionality."; 790 } 792 identity filter { 793 description 794 "Base filter identity."; 795 } 797 identity ethernet { 798 base ta:filter; 799 description 800 "Ethernet packet fields filter."; 801 } 803 grouping statistics-data { 804 description 805 "Analyzer statistics."; 806 leaf pkts { 807 type yang:counter64; 808 description 809 "Total number of packets analyzed."; 810 } 811 leaf octets { 812 type yang:counter64; 813 description 814 "This counter is identical with the in-octets/out-octets 815 counters defined in RFC8343 except that it counts the 816 octets since the analyzer was created."; 817 } 818 leaf idle-octets { 819 if-feature "idle-octets-counter"; 820 type yang:counter64; 821 description 822 "Total accumulated period with no frame transmission 823 taking place measured in octets at the current link 824 speed. Octets not counted in ../octets but not idle are 825 for example layer 1 framing octets - for Ethernet links 826 7+1 preamble octets per packet."; 827 } 828 leaf errors { 829 type yang:counter64; 830 description 831 "Count of packets with errors. 832 Not counted in the pkts or captured. 833 For example packets with CRC error."; 834 } 835 container testframe-stats { 836 description 837 "Statistics for testframe packets containing 838 either sequence number, payload checksum, 839 timestamp or any combination of these features."; 840 leaf testframe-pkts { 841 type yang:counter64; 842 description 843 "Total count of detected testframe packets."; 844 } 845 leaf sequence-errors { 846 type yang:counter64; 847 description 848 "Total count of testframe packets with 849 unexpected sequence number. After each sequence 850 error the expected next sequence number is 851 updated."; 852 } 853 leaf payload-errors { 854 type yang:counter64; 855 description 856 "Total count of testframe packets with 857 payload errors."; 858 } 859 container latency { 860 description 861 "Latency statistics."; 862 leaf samples { 863 type uint64; 864 description 865 "Total count of packets used for estimating 866 the latency statistics. Ideally 867 samples=../testframe-stats."; 868 } 869 leaf min { 870 type uint64; 871 units "nanoseconds"; 872 description 873 "Minimum measured latency."; 874 } 875 leaf max { 876 type uint64; 877 units "nanoseconds"; 878 description 879 "Maximum measured latency."; 880 } 881 leaf average { 882 type uint64; 883 units "nanoseconds"; 884 description 885 "The sum of all sampled latencies divided 886 by the number of samples."; 887 } 888 leaf latest { 889 type uint64; 890 units "nanoseconds"; 891 description 892 "Latency of the latest sample."; 893 } 894 } 895 } 896 } 898 grouping capture-config-data { 899 description 900 "Grouping with a capture configuration container."; 901 container capture { 902 if-feature "capture"; 904 description 905 "Contains capture parameters."; 907 container start-trigger { 908 description 909 "Configures when the capture start is triggered."; 910 choice start-trigger { 911 description 912 "If none of the cases in this choice are configured the 913 capture process starts from the first frame received."; 914 case frame-index { 915 description 916 "Start capturing frames at the specified frame index."; 917 leaf frame-index { 918 type uint64; 919 description 920 "First captured frame index."; 921 } 922 } 923 case testframe-index { 924 description 925 "Start capturing frames at the specified 926 testframe index."; 927 leaf testframe-index { 928 type uint64; 929 description 930 "Starts capture as specified testframe index."; 931 } 932 } 933 } 934 } 935 container stop-trigger { 936 description 937 "Configures when the capture is stopped."; 938 choice stop-trigger { 939 description 940 "If none of the cases in this choice are configured the 941 captured frames are always the last frames received for 942 as many frames the implementation can buffer."; 943 case when-full { 944 description 945 "Stops capturing when the implementation can not store 946 more frames."; 947 leaf when-full { 948 type empty; 949 description 950 "When present in configuration capture stops when 951 the capture buffer is full."; 952 } 953 } 954 } 955 } 956 } 957 } 958 grouping capture-data { 959 description 960 "Grouping with statistics and data 961 of one or more captured frame."; 962 container capture { 963 if-feature "capture"; 964 description 965 "Statistics and data of 966 one or more captured frames."; 967 list frame { 968 key "sequence-number"; 969 description 970 "Statistics and data of a captured frame."; 971 leaf sequence-number { 972 type uint64; 973 description 974 "Incremental counter of frames captured."; 975 } 976 leaf timestamp { 977 type yang:date-and-time; 978 description 979 "Timestamp of the moment the frame was captured."; 980 } 981 leaf length { 982 type uint32; 983 description 984 "Frame length. Ideally the data captured will be 985 of the same length but can be shorter 986 depending on implementation limitations."; 987 } 988 leaf preceding-interframe-gap { 989 type uint32; 990 units "nanoseconds"; 991 description 992 "Measured delay between the reception of the previous 993 frame was completed and the reception of the current 994 frame was started."; 995 } 996 leaf data { 997 type string { 998 pattern '([0-9A-F]{2})*'; 999 } 1000 description 1001 "Raw data of the captured frame."; 1002 } 1003 } 1004 } 1005 } 1006 grouping filter-data { 1007 description 1008 "Grouping with a filter container specifying the filtering 1009 rules for processing only a specific subset of the 1010 frames."; 1011 container filter { 1012 if-feature "filter"; 1013 presence "When present packets are 1014 filtered before analyzed according 1015 to the filter type"; 1016 description 1017 "Contains the filtering rules for processing only 1018 a specific subset of the frames."; 1019 leaf type { 1020 type identityref { 1021 base ta:filter; 1022 } 1023 mandatory true; 1024 description 1025 "Type of the applied filter. External modules can 1026 define alternative filter type identities."; 1027 } 1028 } 1029 } 1031 augment "/if:interfaces/if:interface" { 1032 description 1033 "Traffic analyzer augmentations of ietf-interfaces."; 1034 container traffic-analyzer { 1035 if-feature "ingress-direction"; 1036 presence "Enables the traffic analyzer for ingress traffic."; 1037 description 1038 "Traffic analyzer for ingress direction."; 1039 uses filter-data; 1040 uses capture-config-data; 1041 container state { 1042 config false; 1043 description 1044 "State data."; 1045 uses statistics-data; 1046 uses capture-data; 1047 } 1048 } 1049 container traffic-analyzer-egress { 1050 if-feature "egress-direction"; 1051 presence "Enables the traffic analyzer for egress traffic."; 1052 description 1053 "Traffic analyzer for egress direction."; 1055 uses filter-data; 1056 uses capture-config-data; 1057 container state { 1058 config false; 1059 description 1060 "State data."; 1061 uses statistics-data; 1062 uses capture-data; 1063 } 1064 } 1065 } 1067 augment "/if:interfaces/if:interface/ta:traffic-analyzer/ta:filter" { 1068 when "derived-from-or-self(ta:type, 'ta:ethernet')"; 1069 description 1070 "Ethernet frame specific filter type."; 1071 leaf ether-type { 1072 type uint16; 1073 description 1074 "The Ethernet Type (or Length) value 1075 defined by IEEE 802."; 1076 reference 1077 "IEEE 802-2014 Clause 9.2"; 1078 } 1079 } 1080 } 1082 1084 7. IANA Considerations 1086 This document registers two URIs and two YANG modules. 1088 7.1. URI Registration 1090 This document registers two URIs in the IETF XML registry [RFC3688]. 1091 Following the format in RFC 3688, the following registration is 1092 requested to be made: 1094 URI: urn:ietf:params:xml:ns:yang:ietf-traffic-generator 1095 URI: urn:ietf:params:xml:ns:yang:ietf-traffic-analyzer 1097 Registrant Contact: The IESG. 1099 XML: N/A, the requested URI is an XML namespace. 1101 7.2. YANG Module Name Registration 1103 This document registers two YANG module in the YANG Module Names 1104 registry YANG [RFC6020]. 1106 name: ietf-traffic-generator 1107 namespace: urn:ietf:params:xml:ns:yang:ietf-traffic-generator 1108 prefix: tg 1109 reference: RFC XXXX 1111 name: ietf-traffic-analyzer 1112 namespace: urn:ietf:params:xml:ns:yang:ietf-traffic-analyzer 1113 prefix: ta 1114 reference: RFC XXXX 1116 8. Security Considerations 1118 The YANG modules defined in this document are designed to be accessed 1119 via the NETCONF protocol RFC 6241 [RFC6241]. The lowest NETCONF 1120 layer is the secure transport layer and the mandatory to implement 1121 secure transport is SSH RFC 6242 [RFC6242]. The NETCONF access 1122 control model RFC 6536 [RFC6536] provides the means to restrict 1123 access for particular NETCONF users to a pre-configured subset of all 1124 available NETCONF protocol operations and content. 1126 There are a number of data nodes defined in this YANG module which 1127 are writable/creatable/deletable (i.e. config true, which is the 1128 default). These data nodes may be considered sensitive or vulnerable 1129 in some network environments. Write operations (e.g. edit-config) to 1130 these data nodes without proper protection can have a negative effect 1131 on network operations. These are the subtrees and data nodes and 1132 their sensitivity/vulnerability: 1134 8.1. ietf-traffic-generator.yang 1136 The ietf-traffic-generator YANG module controls a stateless traffic 1137 generator which is intended to be used for testing and verification 1138 purposes but can be used for malicious purposes like generating 1139 network traffic part of a Denial-of-Service (DoS) attack. This 1140 should be taken into consideration when granting write access to the 1141 following container and descendant data nodes: 1143 o /if:interfaces/if:interface/tg:traffic-generator 1145 8.2. ietf-traffic-analyzer.yang 1147 The ietf-traffic-analyzer YANG module controls a traffic analyzer 1148 which is designed for use in testing and verification but can be used 1149 for reading information contained in packets sent and received on any 1150 of the interfaces on systems that implement the capture feature. 1151 This should be taken into consideration when granting read access to 1152 the following container and descendant data nodes: 1154 o /if:interfaces/if:interface/ta:traffic-analyzer/ta:capture 1156 9. References 1158 9.1. Normative References 1160 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1161 the Network Configuration Protocol (NETCONF)", RFC 6020, 1162 DOI 10.17487/RFC6020, October 2010, 1163 . 1165 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1166 and A. Bierman, Ed., "Network Configuration Protocol 1167 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1168 . 1170 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1171 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1172 . 1174 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1175 Protocol (NETCONF) Access Control Model", RFC 6536, 1176 DOI 10.17487/RFC6536, March 2012, 1177 . 1179 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1180 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1181 . 1183 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 1184 RFC 7224, DOI 10.17487/RFC7224, May 2014, 1185 . 1187 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1188 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1189 . 1191 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1192 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1193 . 1195 9.2. Informative References 1197 [IEEE1588] 1198 IEEE, "IEEE 1588-2008", 2008. 1200 [IEEE802.3-2014] 1201 IEEE WG802.3 - Ethernet Working Group, "IEEE 802.3-2014", 1202 2014. 1204 [RFC2544] Bradner, S. and J. McQuaid, "Benchmarking Methodology for 1205 Network Interconnect Devices", RFC 2544, 1206 DOI 10.17487/RFC2544, March 1999, 1207 . 1209 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1210 DOI 10.17487/RFC3688, January 2004, 1211 . 1213 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1214 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1215 . 1217 Appendix A. Examples 1219 The following topology will be used for the examples in this section: 1221 +-------------+ +------------+ +------------+ 1222 | | e0 e0 | | e1 e0 | | 1223 | tester0 TG|>-------->| dut0 |>------->|TA tester1 | 1224 | | | | | | 1225 +-------------+ +------------+ +------------+ 1227 A.1. Basic Test Program 1229 This pseudo code program orchestrates a network test and shows how 1230 the model can be used: 1232 #Connect to network 1233 net=connect("topology.xml") 1235 # Configure DUTs and enable traffic-analyzers 1236 net.node("dut0").edit( \ 1237 "create /interfaces/interface[name='e0'] -- type=ethernetCsmacd") 1239 net.node("dut0").edit( 1240 "create /interfaces/interface[name='e1'] -- type=ethernetCsmacd") 1241 net.node("dut0").edit( 1242 "create /flows/flow[id='t0'] -- match/in-port=e0 " 1243 "actions/action[order='0']/output-action/out-port=e1") 1245 net.node("tester1").edit( 1246 "create /interfaces/interface[name='e0']/traffic-analyzer") 1247 net.commit() 1249 #Get network state - before 1250 before=net.get() 1252 # Start traffic 1253 net.node("tester0).edit( 1254 "create /interfaces/interface[name='e0']/traffic-generator -- " 1255 "frame-size=64 interframe-gap=20") 1257 net.commit() 1259 time.sleep(60) 1261 # Stop traffic 1262 net.node("tester1").edit("delete /interfaces/interface[name='e0']/" 1263 "traffic-generator") 1264 net.commit() 1266 #Get network state - after 1267 after=net.get() 1269 #Report 1270 sent_pkts=delta("tester0",before,after, 1271 "/interfaces/interface[name='e0']/statistics/out-unicast-pkts") 1273 received_pkts=delta("tester1",before,after, 1274 "/interfaces/interface[name='e0']/statistics/in-unicast-pkts") 1276 latency_max=absolute(after, 1277 "/interfaces/interface[name='e0']/traffic-analyzer/state/" 1278 "testframe-stats/latency/max") 1280 #Cleanup 1281 net.node("tester1").edit( 1282 "delete /interfaces/interface/traffic-analyzer") 1283 net.node("dut0").edit("delete /flows") 1284 net.node("dut0").edit("delete /interfaces") 1285 net.commit() 1287 A.2. Generating RFC2544 Testframes 1289 In sec. C.2.6.4 Test Frames a detailed format is specified. The 1290 frame-data leaf allows full control over the generated frames 1291 payload. 1293 ... 1294 net.node("tester1").edit( 1295 "merge /interfaces/interface[name='e0']/" 1296 "traffic-generator -- frame-data=" 1297 "6CA96F0000026CA96F00000108004500" 1298 "002ED4A500000A115816C0000201C000" 1299 "0202C0200007001A0000010203040506" 1300 "0708090A0B0C0D0E0F101112") 1301 ... 1303 Author's Address 1305 Vladimir Vassilev 1306 Lightside Instruments AS 1308 Email: vladimir@lightside-instruments.com