idnits 2.17.1 draft-gray-sampled-streaming-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 : ---------------------------------------------------------------------------- ** There are 39 instances of too long lines in the document, the longest one being 173 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: +-----------+------+----------------+-----------------------------+ | Name | Size | Type | Type-Data | +===========+======+================+=============================+ | Incoming | 8 | ingress-port | A listing of values that | | port | | | may be seen in this field, | | | | | mapped to interface-refs | | | | | from [RFC8343]. | +-----------+------+----------------+-----------------------------+ | Timestamp | 24 | timestamp-nsec | Two 32 bit numbers giving | | | | | when the "0" of this field | | | | | is based off of. | +-----------+------+----------------+-----------------------------+ | Action | 2 | action | A listing of values that | | | | | may be seen in this field, | | | | | mapped to action types | | | | | (accepted, dropped, etc.) | +-----------+------+----------------+-----------------------------+ | Frame | 17 | frame-length | Note that this denotes the | | Length | | | original frame length - the | | | | | payload field MAY NOT | | | | | include the entire payload. | +-----------+------+----------------+-----------------------------+ | Internal | 13 | padding | | | Data 1 | | | | +-----------+------+----------------+-----------------------------+ | Payload | 0 | frame-payload | | +-----------+------+----------------+-----------------------------+ == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: typedef field-type { type enumeration { enum padding { description "Padding bits that MUST be ignored."; } enum ingress-port { description "An indication of the incoming port the frame was received on."; } enum egress-port { description "An indication of the incoming port the frame was transmitted on."; } enum timestamp-msec { description "The timestamp the packet was received at, in integer milliseconds."; } enum timestamp-usec { description "The timestamp the packet was received at, in integer microseconds."; } enum timestamp-nsec { description "The timestamp the packet was received at, in integer nanoseconds."; } enum frame-length { description "The received frame length. Note that due to chipset capabilities, this MAY NOT be the same as the captured packet length."; } enum frame-payload { description "The payload of the frame."; } enum action { description "The action that was taken on this frame. Values are mapped as according to action-type."; } } -- The document date (5 August 2019) is 1725 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Gray, Ed. 3 Internet-Draft Charter Communications 4 Intended status: Informational 5 August 2019 5 Expires: 6 February 2020 7 Sampled Traffic Streaming 8 draft-gray-sampled-streaming-00 10 Abstract 12 This document standardizes the means of requesting a sampled capture 13 stream from a router, receiving details about the resulting data 14 flow, and the structure of the data flow itself. This is 15 specifically tailored to having various hardware ASICs be able to 16 perform this operation as quickly as possible, by allowing 17 communication of the specific bit formats of headers applied to the 18 packet flow, in a way that enhances interoperability between sources 19 and sinks. Historically, NetFlow and its ilk have been used for 20 these use cases, however the growth in hardware forward speeds is far 21 outpacing the growth in CPU speeds, and the CPU-heavy parts of 22 NetFlow is resulting in a reduction of sampling rates that include 23 all of the fields provided by NetFlow that require CPU lookups. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 6 February 2020. 42 Copyright Notice 44 Copyright (c) 2019 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Simplified BSD License text 53 as described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Problem Statement / Operator Use Cases . . . . . . . . . . . 3 62 2.1. Use Case 1 : Traffic Analytics . . . . . . . . . . . . . 3 63 2.2. Use Case 2 : Network Behavior Verification . . . . . . . 3 64 2.3. Use Case 3 : Standardization . . . . . . . . . . . . . . 4 65 3. Stream Setup . . . . . . . . . . . . . . . . . . . . . . . . 4 66 4. Data Stream Format . . . . . . . . . . . . . . . . . . . . . 5 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 71 7.2. Informative References . . . . . . . . . . . . . . . . . 8 72 Appendix A. Yang Model . . . . . . . . . . . . . . . . . . . . . 9 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 75 1. Introduction 77 1.1. Requirements Language 79 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 81 document are to be interpreted as described in RFC 2119 [RFC2119]. 83 1.2. Terminology 85 The following terms are used within this document: 87 Client: The device configuring the Replicator. 89 Receiver: The device that will be receiving the packet stream. 91 Replicator: The device doing the actual packet replication, as 92 requested by a Client, and sending it to a Receiver. 94 Point: The location inside the Replicator (generally a forwarding 95 ASIC) that performs the actual packet replication. There may be 96 multiple physical interfaces serviced by one Point, or one 97 interface may be serviced by multiple Points, that may have 98 different capabilities. 100 2. Problem Statement / Operator Use Cases 102 This document is designed around the following use cases that 103 operators have today, or can foresee coming on the near horizion. 105 2.1. Use Case 1 : Traffic Analytics 107 At present, operators may use a mix of NetFlow, IPFIX, and inline 108 traffic samplers spread throughout the network to gather data for 109 analytics. With the next generation of hardware on the horizon, we 110 have 400Gb/s interfaces starting to become available, with faster 111 speeds already being talked about. This will require at least an 112 augmentation of any inline traffic samplers, which are quite 113 expensive. Additionally, the pace of growth in the data plane is 114 outgrowing the pace of growth in the control plane. This is 115 especially seen with relatively control plane or CPU heavy protocols 116 like NetFlow, where present sampling rates are simply not going to be 117 sustainable long-term, due to on-box control plane hardware 118 limitations. Being able to capture a filtered, sampled collection of 119 actual packets throughout the network is very valuable for 120 understanding how the network is being used, to provide hard data to 121 justify network topology augments or changes. 123 This proposal addresses this use case by making the data replication 124 as simple as possible for hardware fowarding ASICs to implement and 125 send off the device. This allows offloading the heavy calculations 126 to distributed infrastructure than can be scaled as needed using 127 commodity hardware. 129 2.2. Use Case 2 : Network Behavior Verification 131 This use case focuses on the potential abilioty to have the ASICs 132 also include packets that would normally be dropped, along with a 133 reason why. With bits denoting dropped due to QoS policies, buffer 134 contention, ACLs, etc., this traffic could be captured (potentially 135 at a sampling rate of 1:1, i.e. every packet) and sent off for off- 136 box analysis to determine if this was expected, or to provide alerts 137 that QoS policies may be having adverse effects on the network. 138 Here, including the packet payload provides a lot of additional data 139 for these platforms to effectively "second guess" these policies. 141 This proposal addresses this use case by explicitly including a field 142 for marking what an ASIC is going to do with a packet, and including 143 the payload of the resulting sample. 145 2.3. Use Case 3 : Standardization 147 These problems are foreseen by various vendors, who are talking about 148 different variants of these sorts of traffic flows. Standardizing 149 the way these streams are formed and communicated between the 150 Replicators, Clients, and Receivers in a fashion that allows vendors 151 flexibility in what the ASIC has to do (by allowing communicating of 152 an extremely dynamic header in a manner than control planes can 153 manage) allows systems to be used between all compliant platforms. 154 The alternative is having to build independent systems for each form 155 of this sort of packet replication that may end up being developed, 156 resulting in much higher costs. 158 This proposal addresses this use case by allowing the packet header 159 to contain any combination of information, in any position and of any 160 length, to be dynamically determined and information about how to 161 handle this data to be exchanged between the Replicator, Client, and 162 Receiver. This allows ASICs to put on what information they can, in 163 the most efficient format for them. 165 3. Stream Setup 167 To begin, a Client utilizes NETCONF and the model listed in Appedix 168 A. A Client must first request from the Replicator the available 169 configurations via the 'points' branch, which provides the following 170 information: 172 * A name of the Point. 174 * What interfaces this Point is servicing. 176 * If filtering is available, and if so, what filters can be applied 177 (against certain IP fields, against parts of the frame, etc.) 179 * Minimum and maximum sampling rates. 181 * Any current samplers already active off this Point. 183 * Optionally, the maximum frame length the Point can replicate into 184 the sample. 186 * Optionally, the maximum offset into a frame the Point can inspect. 188 * Optionally, the maximum number of samplers that this Point can 189 accomodate. A Client MUST still check for success, as highly 190 complex filters may reduce the amount of replication the Point can 191 do from this maximum. 193 The Client then can request one or more streams to be set up on the 194 Replicator, using that information. 196 These individual streams may be configured with filters and a 197 sampling rate, with the replicated packets sent to the Receiver, 198 wrapped in an outer UDP header. The available filters are provided 199 by the Replicator in the response above - a common option will be for 200 what interface specifically to filter traffic against. The source 201 port of this UDP stream MUST be set to TBD1 by default - Replicators 202 MAY offer an ability to change this default. This is to allow 203 security filters to have a fixed value to key off of as an additional 204 defense to prevent these streams from being inadvertantly sent to 205 undesirable locations. 207 The Client and Receiver MAY be separate devices. The mechanism of 208 exchanging information between Client and Receiver about the setup 209 process is outside the scope of this document. 211 4. Data Stream Format 213 After the stream setup, the Client MUST re-query the stream 214 configuration to get the stream-format data that the remote device 215 has calculated. The Client MUST NOT assume that the stream-format 216 data is consistent between one instance and any other performed 217 (there may be different versions of ASICs, different capabilities, 218 different versions of operating systems, or different filters may 219 yield a different format), or that the Payload is always at the end 220 (as it is the only variable-width field, it could appear at the 221 beginning or in the middle, and sufficient data is provided by the 222 other fields to extract the data correctly). This provides the 223 Client with what information is provided at what location in the 224 resulting packet. The Replicator MUST follow the expectation that is 225 provided in these fields. As an example (but not a nominative 226 listing of what this may be - the actual format can be any 227 combination of fields, of any size, in any order), the data inside 228 the resulting data stream after the UDP tunnel header may look like 229 the following: 231 Example layout: 233 0 1 2 3 234 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 235 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 236 | Incoming Port | Timestamp | 237 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 238 |Act| Frame Length | Internal Data 1 | 239 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 240 | Payload | 241 | ... | 242 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 244 Figure 1 246 This non-normative example would be listed in the modeled data for 247 packet-format as per the following table: 249 +-----------+------+----------------+-----------------------------+ 250 | Name | Size | Type | Type-Data | 251 +===========+======+================+=============================+ 252 | Incoming | 8 | ingress-port | A listing of values that | 253 | port | | | may be seen in this field, | 254 | | | | mapped to interface-refs | 255 | | | | from [RFC8343]. | 256 +-----------+------+----------------+-----------------------------+ 257 | Timestamp | 24 | timestamp-nsec | Two 32 bit numbers giving | 258 | | | | when the "0" of this field | 259 | | | | is based off of. | 260 +-----------+------+----------------+-----------------------------+ 261 | Action | 2 | action | A listing of values that | 262 | | | | may be seen in this field, | 263 | | | | mapped to action types | 264 | | | | (accepted, dropped, etc.) | 265 +-----------+------+----------------+-----------------------------+ 266 | Frame | 17 | frame-length | Note that this denotes the | 267 | Length | | | original frame length - the | 268 | | | | payload field MAY NOT | 269 | | | | include the entire payload. | 270 +-----------+------+----------------+-----------------------------+ 271 | Internal | 13 | padding | | 272 | Data 1 | | | | 273 +-----------+------+----------------+-----------------------------+ 274 | Payload | 0 | frame-payload | | 275 +-----------+------+----------------+-----------------------------+ 277 Table 1: Example packet-format response 279 To restate the prior note, the above is purely an example of what the 280 format could be - the actual format used is negotiated between the 281 Client and Replicator, and can have practically any layout, with any 282 additional fields. 284 To adequately addresses the use cases stated above, a Replicator 285 SHOULD support as a minimum set of capabilities: 287 * An action field that denotes a pass or drop (ideally with drop 288 reason) 290 * The payload of at least 128 octets 292 * The original frame length 294 * Sampling rates down to 1:1 (i.e. every packet is replicated) 296 * Having different sampling sessions having different sampling rates 297 (to allow a "general" session to be watching a broad selection of 298 traffic, and more specific sessions targeting exact flows or 299 situations) 301 * At least two sessions per physical interface 303 * Filtering on ingress port 305 * Filtering on action 307 A Client SHOULD take efforts to be notified when a change has 308 occurred on the Replicator, and re-verify its replication 309 configurations when such a change is detected. 311 5. IANA Considerations 313 This document defines a new UDP port number, entitled "Sampled 314 Streaming", and assigns a value of TBD1 from the Service Name and 315 Transport Protocol Port Number Registry 316 https://www.iana.org/assignments/service-names-port-numbers/service- 317 names-port-numbers.xhtml: 319 +------+-------------------+ 320 | Tag | Description | 321 +======+===================+ 322 | TBD1 | Sampled Streaming | 323 +------+-------------------+ 325 Table 2 327 This document requests registration of a URI in the "IETF XML 328 Registry" RFC 3688 [RFC3688]. Following the format in RFC 3688, the 329 following registration is suggested: 331 URI: urn:ietf:params:xml:ns:yang:ietf-sampled-streaming 332 Registrant Contact: The IESG. 333 XML: N/A, the requested URI is an XML namespace. 335 This document registers a YANG module in the "YANG Module Names" 336 registry RFC 6020 [RFC6020]: 338 name: ietf-sampled-streaming 339 namespace: urn:ietf:params:xml:ns:yang:ietf-sampled-streaming 340 prefix: ss 341 reference: This document 343 6. Security Considerations 345 Vendors and deployments must take into consideration that this 346 functionality allows a mirroring of traffic, with configurable 347 destinations and filters. Similar functionality already exists in 348 various remote packet mirroring systems, and similiar considerations 349 should be taken. Filters utilizing the source port of TBD1 SHOULD be 350 applied at the edges of a provider's network to provide an additional 351 layer of security. 353 7. References 355 7.1. Normative References 357 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 358 Requirement Levels", BCP 14, RFC 2119, 359 DOI 10.17487/RFC2119, March 1997, 360 . 362 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 363 DOI 10.17487/RFC3688, January 2004, 364 . 366 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 367 the Network Configuration Protocol (NETCONF)", RFC 6020, 368 DOI 10.17487/RFC6020, October 2010, 369 . 371 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 372 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 373 . 375 7.2. Informative References 376 Appendix A. Yang Model 378 module ietf-sampled-streaming { 379 namespace "urn:ietf:params:xml:ns:yang:ietf-sampled-streaming"; 380 prefix "ss"; 382 import ietf-yang-types { 383 prefix yang; 384 } 385 import ietf-interfaces { 386 prefix if; 387 } 388 import ietf-inet-types { 389 prefix inet; 390 } 392 organization 393 "IETF Working Group"; 395 contact 396 "Editor: Andrew Gray 397 "; 399 description 400 "This module contains a collection of YANG definitions for 401 managing sampled streaming subscriptions. 403 Copyright (c) 2019 IETF Trust and the persons identified as 404 authors of the code. All rights reserved. 406 Redistribution and use in source and binary forms, with or 407 without modification, is permitted pursuant to, and subject to 408 the license terms contained in, the Simplified BSD License set 409 forth in Section 4.c of the IETF Trust's Legal Provisions 410 Relating to IETF Documents 411 (https://trustee.ietf.org/license-info). 413 This version of this YANG module is part of RFC XXXX 414 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 415 for full legal notices. 417 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 418 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 419 'MAY', and 'OPTIONAL' in this document are to be interpreted as 420 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 421 they appear in all capitals, as shown here."; 423 revision 2019-06-25 { 424 description 425 "Initial version."; 426 reference 427 "draft-gray-sampled-streaming-00"; 428 } 430 typedef filter-type { 431 type enumeration { 432 enum interfaces { 433 description "List of interfaces to filter against."; 434 } 435 enum action { 436 description "Filter against a list of actions that the Point took (i.e., only consider packets that were actually forwarded)."; 437 } 438 enum ip-version { 439 description "The version number in the IP header."; 440 } 441 enum ip-v4-srcip { 442 description "The IPv4 header's source IPv4 address."; 443 } 444 enum ip-v4-dstip { 445 description "The IPv4 header's destination IPv4 address."; 446 } 447 enum ip-v4-ttl { 448 description "The IPv4 header's Time to Live."; 449 } 450 enum ip-v4-prot { 451 description "The IPv4 header's protocol number."; 452 } 453 enum ip-v6-srcip { 454 description "The IPv6 header's source IPv4 address."; 455 } 456 enum ip-v6-dstip { 457 description "The IPv6 header's destination IPv4 address."; 458 } 459 enum frame-size { 460 description "The total size of the the frame."; 461 } 462 enum frame-payload { 463 description "Specific payload octets."; 464 } 465 } 467 description "The filtering abilities available."; 468 } 470 typedef field-type { 471 type enumeration { 472 enum padding { 473 description "Padding bits that MUST be ignored."; 474 } 475 enum ingress-port { 476 description "An indication of the incoming port the frame was received on."; 477 } 478 enum egress-port { 479 description "An indication of the incoming port the frame was transmitted on."; 480 } 481 enum timestamp-msec { 482 description "The timestamp the packet was received at, in integer milliseconds."; 483 } 484 enum timestamp-usec { 485 description "The timestamp the packet was received at, in integer microseconds."; 486 } 487 enum timestamp-nsec { 488 description "The timestamp the packet was received at, in integer nanoseconds."; 489 } 490 enum frame-length { 491 description "The received frame length. Note that due to chipset capabilities, this MAY NOT be the same as the captured packet length."; 492 } 493 enum frame-payload { 494 description "The payload of the frame."; 495 } 496 enum action { 497 description "The action that was taken on this frame. Values are mapped as according to action-type."; 498 } 499 } 501 description "Types of data included in the data stream provided back to the receiver. Note that all fields will not be provided."; 502 } 504 typedef action-type { 505 type enumeration { 506 enum forwarded { 507 description "Forwarded normally through the system."; 508 } 509 enum dropped { 510 description "Generically dropped. A more specific action type code should be used, if possible."; 511 } 512 enum dropped-rate-limit { 513 description "Dropped due to a rate limiter applied."; 514 } 515 enum dropped-buffer { 516 description "Dropped due to no buffer space."; 517 } 518 enum dropped-security { 519 description "Dropped due to a security policy."; 521 } 522 enum dropped-error { 523 description "Dropped due to the frame being in error."; 524 } 525 enum remarked { 526 description "Frame was remarked and forwarded."; 527 } 528 } 530 description "Possible actions taken on a packet."; 531 } 533 typedef destination-type { 534 type enumeration { 535 enum udp { 536 description "Sent with a UDP header."; 537 } 538 } 540 description "Different possible destination types."; 541 } 543 list points { 544 description "A listing of the capture points available on this device, what ports they provide for, and what filtering is available at those points."; 545 key name; 546 leaf name { 547 type string; 548 description "The name of this capture point."; 549 } 550 list interface { 551 description "List of interfaces that are available at this point."; 552 config false; 553 leaf if { 554 mandatory true; 555 type if:interface-ref; 556 description "An interface tied to this capture point."; 557 } 558 } 559 list filters { 560 description "List of filtering options available at this point."; 561 config false; 562 leaf filter { 563 description "One specific filter available at this point."; 564 mandatory true; 565 type filter-type; 566 } 567 } 568 leaf min-ratio { 569 type uint32 { 570 range "1..max"; 571 } 572 description "The minimum sampling ratio (1:N, with N being this value) this point can provide."; 573 } 574 leaf max-ratio { 575 type uint32 { 576 range "1..max"; 577 } 578 description "The maximum sampling ratio (1:N, with N being this value) this point can provide."; 579 } 580 leaf max-samplers { 581 type uint32; 582 description "The maximum number of samplers that can be installed at this point."; 583 } 584 leaf max-filters { 585 type uint32; 586 description "The maximum number of filtering rules permitted at this location. Note this is an absolute maximum, and fewer rules that are complex may still be rejected by the device."; 587 } 588 leaf max-frame-length-copy { 589 type uint16; 590 description "The maximum size that the point can replicate and copy into the header."; 591 } 592 leaf max-frame-depth-inspect { 593 type uint16; 594 description "The offset of the last octet in a frame the ASIC can perform filtering against."; 595 } 597 list samplers { 598 description "A list of all the samplers attached to this point."; 600 config true; 601 key "name"; 603 leaf name { 604 mandatory true; 605 type string; 606 description "A unique name given to this sampler."; 607 } 609 container destination { 610 description "The destination of where to send the UDP stream to."; 611 leaf type { 612 mandatory true; 613 type destination-type; 614 description "The type of encoding for the destination."; 615 } 616 container udp-parameters { 617 description "Parameters for destination-type=udp. Source port is always the port number assigned by IANA."; 618 when "../type='udp'"; 619 leaf destination-ip { 620 mandatory true; 621 type inet:ip-address-no-zone; 622 description "The destination IP to send the stream to."; 623 } 624 leaf destination-port { 625 mandatory true; 626 type inet:port-number; 627 description "The destination UDP port number to send the stream to."; 628 } 629 } 630 } 632 leaf ratio { 633 mandatory true; 634 type uint32 { 635 range "1..max"; 636 } 637 description "The requested sampling ratio (1:N, with N being this value)."; 638 } 640 list filters { 641 description "A list of filters applied to this sampling. Multiple filters are logically ANDed together."; 643 key "name"; 644 leaf name { 645 description "A name for this filter."; 646 type string; 647 } 649 list interfaces { 650 when "../type = 'interfaces'"; 651 description "Filter down to only this list of interfaces."; 652 key "int"; 653 leaf int { 654 description "A specific interface to filter against."; 655 type if:interface-ref; 656 } 657 } 659 list actions { 660 when "../type = 'action'"; 661 description "Filter down to only this list of actions."; 662 key "action"; 663 leaf action { 664 description "One specific action code."; 665 type action-type; 666 } 667 } 669 leaf type { 670 description "The type of filter associated."; 671 type filter-type; 672 mandatory true; 673 } 675 leaf ipv4-address { 676 when "../type = 'ip-v4-srcip' | ../type = 'ip-v4-dstip'"; 677 type inet:ipv4-address-no-zone; 678 description "The IPv4 address to filter on."; 679 } 681 leaf ipv6-address { 682 when "../type = 'ip-v6-srcip' | ../type = 'ip-v6-dstip'"; 683 type inet:ipv6-address-no-zone; 684 description "The IPv6 address to filter on."; 685 } 687 leaf version { 688 when "../type = 'ip-version'"; 689 type inet:ip-version; 690 description "The value of the IP version number to match on."; 691 } 693 container frame-payload { 694 when "../type = 'frame-payload'"; 695 description "Frame payload fragment to match on."; 697 leaf offset { 698 description "Offset in octets from the start of the frame to begin the match on."; 699 type uint16; 700 } 701 leaf match { 702 description "The bytes to match on."; 703 type binary; 704 } 705 } 707 leaf frame-length { 708 when "../type = 'frame-length'"; 709 type uint16; 710 description "Frame length to match on."; 711 } 713 } 714 container stream-format { 715 config false; 716 description "This contains the packet format data that this sampling stream is sending. This is only valid after configuration. The length fields are given in bits, and are consecutive. Needed gaps should use a 'padding' element."; 718 list fields { 719 description "The listing of the fields that will be encapsulated and sent to the receiver."; 721 key "name"; 722 leaf name { 723 type string; 724 description "Human readable name of what this field contains."; 725 } 726 leaf size { 727 type uint32 { 728 range "0..524280"; 729 } 730 description "The size of this field, in bits. The value of '0' denotes a variable-sized field, which is only permitted as the last field in this definition."; 731 } 732 leaf type { 733 type field-type; 734 description "The type of this data."; 735 } 737 list action-mappings { 738 description "The mapping of values to action-type codes, valid for type=action."; 739 key "value"; 740 when "../type='action'"; 741 leaf value { 742 type binary; 743 description "The value that will appear in the header."; 744 } 745 leaf meaning { 746 type action-type; 747 description "What this value indicates."; 748 } 749 } 751 list port-mappings { 752 description "The mapping of values to interfaces, valid for type=ingress-port or type=egress-port"; 753 key "value"; 754 when "../type='ingress-port' | ../type='egress-port'"; 755 leaf value { 756 type binary; 757 description "The value that will appear in the header."; 758 } 759 leaf port { 760 type if:interface-ref; 761 description "The port the value maps to."; 762 } 763 } 765 container timestamp { 766 description "Supplemental data for type=timestamp*, in PTP Truncated Timestamp Format. Provides the time used as the epoch for the number in the data stream."; 767 when "../type='timestamp-nsec' | ../type='timestamp-usec' | ../type='timestamp-msec'"; 769 leaf seconds { 770 type uint32; 771 description "Specifies the integer portion of the number of seconds since the epoch."; 772 } 773 leaf nanoseconds { 774 type uint32; 775 description "Specifies the fractional portion of the number of seconds since the epoch, in integer number of nanoseconds."; 776 } 777 } 778 } 779 } 780 } 781 } 782 } 784 Author's Address 786 Andrew Gray (editor) 787 Charter Communications 788 8560 Upland Drive, Suite B 789 Englewood, CO 80112 790 United States 792 Phone: +1 720 699 5125 793 Email: Andrew.Gray@charter.com