idnits 2.17.1 draft-gray-sampled-streaming-03.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 4 instances of too long lines in the document, the longest one being 4 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 743 has weird spacing: '...omainId uin...' == Line 756 has weird spacing: '...nterval uin...' == Line 760 has weird spacing: '...nterval uin...' == Line 765 has weird spacing: '...ulation uin...' == Line 768 has weird spacing: '...ability dec...' == (18 more instances...) == 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 document date (2 April 2020) is 1484 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-05) exists of draft-tuexen-opsawg-pcapng-01 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OPSAWG A. Gray 3 Internet-Draft Charter Communications 4 Intended status: Informational L.J. Wobker 5 Expires: 4 October 2020 Cisco Systems 6 2 April 2020 8 Sampled Traffic Streaming 9 draft-gray-sampled-streaming-03 11 Abstract 13 This document standardizes both 1) a means of requesting a stream of 14 packet samples from any device generating, routing, or forwarding 15 traffic, and 2) receiving metadata information from the network 16 element about these packet samples, and the structure of said stream 17 metadata. A main design requirement is to provide network elements 18 with widely varying capabilities (e.g., ASICs, NPUs, NICs, vSwitches, 19 CPUs) a mechanism to sample and export packets at high rates, by 20 allowing communication of the specific bit formats of internal data 21 headers applied to the packet flow, in a way that enhances 22 interoperability between traffic sources and sinks. Historically, 23 Netflow and similar mechanisms have been used for these use cases; 24 however, the increasing packet rates of very high-speed devices and 25 increasing variance in the information available to data planes lends 26 itself to both a less-prescriptive set of packet formats as well as a 27 decoupling of the sampling action from the collection and analysis 28 mechanisms. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on 4 October 2020. 47 Copyright Notice 49 Copyright (c) 2020 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 54 license-info) in effect on the date of publication of this document. 55 Please review these documents carefully, as they describe your rights 56 and restrictions with respect to this document. Code Components 57 extracted from this document must include Simplified BSD License text 58 as described in Section 4.e of the Trust Legal Provisions and are 59 provided without warranty as described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.3. Motivation for Disaggregation of Telemetry . . . . . . . 3 67 1.4. Comparisons with PSAMP . . . . . . . . . . . . . . . . . 4 68 2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 2.1. Use Case 1: Traffic Analytics . . . . . . . . . . . . . . 5 70 2.2. Use Case 2: Network Behavior Verification . . . . . . . . 6 71 2.3. Use Case 3: Standardization . . . . . . . . . . . . . . . 6 72 2.4. Use Case 4: Security Automation . . . . . . . . . . . . . 6 73 3. Stream Setup . . . . . . . . . . . . . . . . . . . . . . . . 7 74 3.1. Client queries Replicator for Points . . . . . . . . . . 7 75 3.2. Client submits a request to the Replicator . . . . . . . 8 76 3.2.1. Filtering Details . . . . . . . . . . . . . . . . . . 9 77 3.3. Replicator offers Proposals . . . . . . . . . . . . . . . 9 78 3.4. Client selects a Proposal . . . . . . . . . . . . . . . . 10 79 3.5. Ending sampling and cleanup . . . . . . . . . . . . . . . 11 80 4. Data Stream Format . . . . . . . . . . . . . . . . . . . . . 11 81 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 82 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 83 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 84 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 85 8.1. Normative References . . . . . . . . . . . . . . . . . . 16 86 8.2. Informative References . . . . . . . . . . . . . . . . . 16 87 Appendix A. Yang Model Tree Reference . . . . . . . . . . . . . 17 88 Appendix B. Yang Model . . . . . . . . . . . . . . . . . . . . . 21 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 91 1. Introduction 92 1.1. Requirements Language 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 96 document are to be interpreted as described in RFC 2119 [RFC2119]. 98 1.2. Terminology 100 The following terms are used within this document: 102 Client: The device configuring the Replicator. 104 Receiver: The device receiving the packet stream. 106 Replicator: The device performing the actual packet replication, 107 as requested by a Client, and sending the resulting replicated 108 packet stream to a Receiver. 110 Point: The location inside the Replicator (e.g., a forwarding 111 ASIC) that performs the actual packet replication. There may be 112 multiple physical interfaces serviced by one Point, or one 113 interface may be serviced by multiple Points, that may have 114 different capabilities. 116 1.3. Motivation for Disaggregation of Telemetry 118 A key concept for this proposal is to enable very high rate sample 119 generation for network elements, while at the same time separating 120 the sampling mechanism itself from specific analysis or transport 121 protocols. If we separate the component functions of how these 122 problems have been traditionally solved, these functions lend 123 themselves to being viewed as a layered stack such as the one in the 124 figure: 126 Figure: Packet sampling and analysis viewed as a layered stack 127 +-+-+-+-+-+-+-+-+-+-+-+-+-+ 128 | Analysis | Higher level applications perform 129 +-+-+-+-+-+-+-+-+-+-+-+-+-+ further analysis on aggregated samples 130 ^^ 131 +-+-+-+-+-+-+-+-+-+-+-+-+-+ 132 | Collection / Decoding | Samples arrives at Receiver, decoded, 133 +-+-+-+-+-+-+-+-+-+-+-+-+-+ optionally stored/aggregated 134 ^^ 135 +-+-+-+-+-+-+-+-+-+-+-+-+-+ 136 | Export / Transport | Encapsulate packet sample and metadata, 137 +-+-+-+-+-+-+-+-+-+-+-+-+-+ send via configured transport protocol 138 ^^ 139 +-+-+-+-+-+-+-+-+-+-+-+-+-+ 140 | Sampling / Metadata | Samples filters packets at a fixed 141 +-+-+-+-+-+-+-+-+-+-+-+-+-+ ratio from stream, appends metadata 142 ^^ 143 +-+-+-+-+-+-+-+-+-+-+-+-+-+ 144 | Data Plane Forwarding | Stream of data packets moving through 145 +-+-+-+-+-+-+-+-+-+-+-+-+-+ element data plane 147 Figure 1 149 The primary advantage of the stack model is the ability to 150 disaggregate functions from each other. For example, providing a 151 self-describing, flexible format for the metadata abstracts the data 152 plane -- in other words the upper layers do not need to know how many 153 bits wide a metadata field is, they only need to know that it is 154 present and the semantics. Separating the transport function allows 155 for multiple use cases: a router wishing to sample packets for 156 internal consumption within the same system might use a locally 157 defined (perhaps even proprietary) transport header, while putting 158 the sampled metadata and packet into a UDP packet allows for it to be 159 transported to any IP-reachable collector, regardless of the 160 geographic or topological distance from the Replicator itself. 162 This document standardizes the "Sampling / Metadata" and "Export / 163 Transport" components of the above stack. 165 1.4. Comparisons with PSAMP 167 Packet Sampling (PSAMP) from RFC 5476 [RFC5476] shares some of the 168 characteristics of Sampled Streaming, and parts of its YANG model as 169 documented in RFC 6728 [RFC6728] are in fact imported into this one 170 to share concepts where possible (notably re-using the concepts of 171 observation points and selectors). However, Sampled Streaming 172 differs primarily in the ability to include information that is 173 normally internal to device that provides information about the 174 packet's handling through the device, and to have the Replicator 175 specify the outgoing packet format in a very dynamic fashion that 176 suits itself as best as possible. This is done to allow this 177 replication to be done natively on relatively low feature set 178 forwarding hardware and to ensure the only usage of high-capability 179 CPU resources on the Replicator is in the initial setup and 180 negotiation. All other aspects have been made to allow the 181 Replicator to do the least amount of work as possible, to extract as 182 much information as possible, and get it sent to the Receiver who is 183 presumed to have orders of magnitudes greater compute capability 184 available. Other changes to the setup and configuration are wrapped 185 around this primary goal. 187 2. Use Cases 189 This document is designed around the following current and 190 foreseeable use cases that operators have today. 192 2.1. Use Case 1: Traffic Analytics 194 Operators typically use a mix of NetFlow, IPFIX, and in-line traffic 195 samplers spread throughout the network to gather data for analytics. 196 With the next generation of hardware, 400Gb/s interfaces are becoming 197 available, with higher data rates under development in their 198 respective standards bodies. This will require at least an 199 augmentation of any in-line traffic samplers, which are quite 200 expensive. Additionally, the pace of growth in the data plane is 201 outgrowing the pace of growth of the control plane. This is 202 especially visible with relatively control plane or CPU-heavy 203 protocols such as NetFlow, where current sampling rates are simply 204 not going to be sustainable long-term, primarily due to on-box 205 control plane hardware limitations. Being able to capture a 206 filtered, sampled collection of actual packets throughout the network 207 is very valuable for understanding how the network is being used, to 208 provide hard data to justify network topology augments and/or 209 technology changes. 211 This proposal addresses this use case by: 1) making the data 212 replication mechanism as simple as possible, reducing the need for 213 high levels of complexity in the data plane; 2) decoupling the 214 sampling/collection of packets from the analysis, which in turn 215 allows for the analysis to be performed on distributed, horizontally- 216 scalable platforms rather than being constrained to the compute and 217 storage capabilities of a local network element. 219 2.2. Use Case 2: Network Behavior Verification 221 This use case focuses on the potential ability to have the ASICs 222 stream discarded packets, along with an indication as to the reason 223 for the drop. With fields denoting the reason for dropped packets 224 such as QoS policies, buffer contention, ACLs, etc., such discarded 225 traffic could be streamed (potentially at a sampling rate of 1:1, 226 i.e. every packet) off-box for analysis to determine if the observed 227 behavior was expected, or trigger alerts that QoS policies may be 228 having adverse effects on the network. The ability to include the 229 packet payload provides additional context, allowing examination of 230 the platform behavior and affected policies. 232 This proposal addresses this use case by allowing samplers which have 233 such capabilities to communicate to the receiver: 1) drop 234 codes(reasons) that are known, 2) the semantics of those codes, and 235 3) the specific bit formats for the receiver to use when decoding. 237 2.3. Use Case 3: Standardization 239 Standardizing the way these data streams are formed and communicated 240 between the Replicators, Clients, and Receivers in a fashion that 241 allows vendors flexibility in what work the ASIC has to do to support 242 sampled streaming (by allowing communicating of an extremely dynamic 243 header in a manner than control planes can manage) allows systems to 244 be used between all platforms in an interoperable fashion. The 245 alternative is to build independent systems for each packet 246 replication solution that may end up being developed, resulting in 247 much higher costs for an overall solution. 249 This proposal addresses this use case by allowing the sampled packet 250 header to provide varying metadata fields, without mandating specific 251 positions or widths. This arrangement of fields and their format is 252 a function of the Replicator, and information about how to handle 253 this data is exchanged between the Replicator, Client, and Receiver 254 at the initialization of the session. The motivation for such 255 latitude in encoding and sizing is quite intentional, as it permits 256 widely varying capabilities within the Replicators. 258 2.4. Use Case 4: Security Automation 260 An automated security platform can utilize this proposal to set up a 261 "normal security analysis" stream at a very low sampling rate (for 262 example, 1 in 20,000) for constant monitoring at various points 263 throughout the network. Upon seeing something it deems 264 'interesting', or by manual input, it can add in an additional, 265 targeted, stream, at a very high sampling rate (potentially 1:1) for 266 detailed analysis and mitigation efforts. 268 Examples of past incidents where this may have been useful are the 269 NTP MONLIST attacks, DNS attacks, or DDoS attacks (although 1:1 would 270 most likely not be used in a DDoS case, unless performing the initial 271 data collection). 273 The security platform could potentially then use the collected 274 packets to generate an auto-mitigation plan based on heuristics 275 (i.e., 99% of this sudden burst of traffic has something in common, 276 deploy mitigation targeting that.) 278 3. Stream Setup 280 The configuration and setup between the Client and the Replicator 281 utilizes the YANG model as listed in Appendix B and any supported 282 configuration method (NETCONF, RESTCONF, gRPC, etc.). The tree 283 output of this model, as provided in Appendix A is provided as an aid 284 to understanding the interactions and tree structure as described in 285 this document. 287 3.1. Client queries Replicator for Points 289 A Client MUST first request from the Replicator the available 290 configurations via the 'points' branch, which provides the following 291 information: 293 * 'name' - The name of the Point. This serves as a key, and SHOULD 294 NOT be interpreted by software as anything other than a possibly- 295 human-readable uniquely identifying value. A Replicator MAY 296 choose to use an internal path, an encoded address, or any other 297 value of its choosing. 299 * 'interfaces' - The physical interfaces this Point is servicing. A 300 Replicator MAY offer the same interfaces under different Points, 301 with a different set of options. A Replicator MAY not offer a 302 Point for every interface available on the system. 304 * 'filters' - What filters can be applied (for example, against 305 certain IP fields, against parts of the frame, etc.). A 306 Replicator MAY not be able to honor every combination of filters 307 submitted in a request, or MAY not offer any filtering capability 308 at all. A Replicator MAY only be able to support a limited number 309 of filters, which MAY be returned in in the 'max-filters' branch. 311 * 'min-ratio' and 'max-ratio' - Minimum and maximum sampling rates 312 possible at this point. These are provided as a number N, 313 denoting one sample will be returned for every N. A Replicator 314 MAY not be able to offer a 'min-ratio' of 1 (i.e. every packet). 316 * 'samplers' - A list of any current samplers already active on this 317 Point as requested by this Client, and the branch manipulated in 318 the next section. A Replicator SHOULD NOT inform a Client about 319 the sampling sessions from other Clients. 321 * Optionally, the maximum frame length the Point can replicate into 322 the sample in 'max-frame-length-copy'. 324 * Optionally, the maximum offset into a frame the Point can inspect 325 in 'max-frame-depth-inspect'. 327 * Optionally, the maximum number of samplers that this Point can 328 accommodate in 'max-samplers'. A Client MUST still check for 329 success, as highly complex filters may reduce the amount of 330 replication the Point can do from this stated maximum. 332 3.2. Client submits a request to the Replicator 334 The Client then can request one or more streams to be set up on the 335 Replicator, taking into consideration the provided information. This 336 is performed by sending a request via adding an entry to the 337 'samplers' list in the 'points' branch and filling in the parameters 338 listed below: 340 * 'name' MUST be unique in the list, and MAY be any valid string 341 value up to 255 characters. The Replicator MUST isolate 342 namespaces between Clients (as one Client SHOULD NOT be able to 343 see other Clients' entries). 345 * 'destination' sets the transport mechanism and Receiver address. 346 It should be noted that the Client and Receiver MAY be separate 347 devices. The mechanism of exchanging information between the 348 Client and Receiver about this setup process is outside the scope 349 of this document. At present, the only supported transport 350 mechanism is a UDP tunnel, as detailed below in Section 4. 352 * 'client-heartbeat' MUST be set to 0. 354 * The desired sampling rate ('ratio'), along with what degree of 355 variance the Client can accept ('min-ratio' and 'max-ratio'). For 356 example, the client may request a 1 in 2000 rate, but specify a 357 range in the variance of 1900-2100. A proposal may come back with 358 the sampling rate offered of 1 in 2048, due to restrictions on the 359 Replicator. 361 * Optionally, one, or more filters in the 'filters' container, as 362 seen in the 'filter-type' typedef in the Yang model. Generally, a 363 Client would filter at least on a specific interface and 364 direction, but many other filter options are possible. 366 When the client is done with its configuration, it MUST set 'status' 367 to the 'client-request-complete' value, and the 'request' branch MUST 368 be read-only from this point forward. 370 3.2.1. Filtering Details 372 The filtering discussed above is designed to be as flexible as the 373 Replicator can realistically support. There are a few cases worth 374 discussing in detail, which are covered here. 376 3.2.1.1. Interfaces 378 All of the use cases focus on filtering to specific interface(s) to 379 filter on. A Replicator MAY, at its discretion, offer some or all of 380 its possible physical interfaces, offer logical interfaces (i.e. 381 routed interfaces on a port or VLAN, or subscriber interfaces), or 382 LAG interfaces. LAGs may be especially tricky, as the member ports 383 of the LAG may span line cards of different capturing capabilities. 384 Replicators SHOULD make an attempt to offer LAGs if all ports are of 385 identical capability, and MAY offer them in the case where they are 386 not, with a lowest-common capability set. Clients SHOULD NOT expect 387 LAG functionality to be present, and SHOULD be prepared to set up 388 separate sessions on each of the individual member ports if the 389 Replicator does not offer the LAG, or offers it with an insufficient 390 set. 392 3.3. Replicator offers Proposals 394 Upon receiving the 'status' change to 'client-request-complete', the 395 Replicator updates the 'proposals' branch. This branch details zero, 396 one, or more ways the Replicator can fulfill the sampling request. 397 While generally there will only be zero or one proposals, a 398 Replicator MAY offer more. For example, matching a sampling rate 399 exactly would result in performance loss but a 'close enough' option 400 can be offered that does not, or offers of what headers can be 401 captured in the resulting stream. Each proposal includes a unique ID 402 number, allowing the Client to select one, as detailed below. 404 If the Replicator is unable to provide any Proposals, the 'proposals' 405 list MUST be empty, a human-readable error message MAY be returned in 406 the 'proposal-error' field, then the 'status' field MUST be set to 407 'replicator-proposal-error'. 409 If the Replicator was able to provide Proposals, it MUST set the 410 'status' field to 'replicator-proposals-available' when it is 411 finished, and the 'proposals' branch MUST be read-only until the 412 Client finishes the Proposal selection step below. 414 Part of each Proposal is a 'stream-format' branch, which informs the 415 Client of the packet format the Receiver will be receiving. This 416 format completely defines the entirety of the resulting data flow 417 format besides the outer UDP wrapper - there is no normative format. 418 A couple non-normative examples of what may result are provided in 419 Section 4. 421 To adequately addresses the use cases stated above, a Replicator 422 SHOULD support as a minimum set of capabilities: 424 * An action field that denotes a pass or drop (ideally with drop 425 reason) 427 * Capturing at least 128 octets of payload 429 * The original frame length 431 * Sampling rates up to 1:1 (i.e. every packet is replicated), and 432 down to 1:20000 or smaller. 434 * Having different sampling sessions having different sampling rates 435 (to allow a "general" session to be watching a broad selection of 436 traffic, and more specific sessions targeting exact flows or 437 situations) 439 * At least two sessions per physical interface 441 * Filtering on ingress port 443 * Filtering on action 445 * Filtering on direction of traffic 447 3.4. Client selects a Proposal 449 Upon either a notification or detection that the 'status' field has 450 been updated, the Client then may then set the 'proposal-selected' 451 entry to the value of the desired ID offered in 'proposals', and then 452 set 'status' to 'client-proposal selected'. At this point, the 453 Replicator: 455 * MAY remove unnecessary branches in the 'proposals' list, but MUST 456 retain the selected one. 458 * MUST either install the requested sampling stream if possible, 459 then MUST set 'status' to 'replicator-install-success'. If it 460 cannot, it MAY set 'install-error' to a human-readable error 461 message and MUST set 'status' to 'replicator-install-error'. 463 * If the Proposal selected includes any of the 'dropped-' action- 464 types as a filter, or does not specify an action-type filter at 465 all, a Replicator MUST install the requested sampling before any 466 filtering actions occur to the stream, as the sampling session is 467 explicitly interested in pre-drop traffic. 469 * If the Proposal selected does not include any of the 'dropped-' 470 action-types as a filter, a Replicator MUST install the requested 471 sampling after any filtering actions occur to the stream, to 472 ensure the sampling ratio remains correct. 474 3.5. Ending sampling and cleanup 476 When a Client is finished with a sampling session, it deletes its 477 entry in the 'samplers' tree to terminate a sampling session. 478 Otherwise, a Client MUST refresh its entry by setting 'client- 479 heartbeat' to 0 at least every 3600 seconds. The 'client-heartbeat' 480 is then incremented by the Replicator. If 'client-heartbeat' exceeds 481 3600, the Replicator SHOULD consider the sampling configuration and 482 any associated sampling session no longer necessary, terminate the 483 sampling, and delete the entry. A Replicator MAY allow configuration 484 to increase this timeout. 486 4. Data Stream Format 488 After the stream setup has been completed, the Receiver MUST use the 489 stream-format data that the Replicator has calculated in its 490 proposal. The Client and Receiver MUST NOT assume that the stream- 491 format data is consistent between one stream setup and any other 492 (there may be different versions of ASICs, different capabilities, 493 different versions of operating systems, or different filters may 494 yield a different format), or that the payload is always at the end 495 (it could appear at the beginning or in the middle, and sufficient 496 data is provided by the other fields to extract the data correctly). 497 The stream-format data provides the Client with what information is 498 provided at what location in the resulting packet. The Replicator 499 MUST follow the expectation that is provided in these fields. 501 There is one captured packet per encapsulated packet, and thus the 502 outer encapsulation length can be used to deduce the length of one 503 variable-length field (designated by a field length of 0) contained 504 within. If there is more than one variable-length field, a matching 505 "-size"; field type MUST be provided for all but one of the variable- 506 length fields (as a single variable length can be deduced from the 507 wrapper length). 509 This means there is no normative packet format or data layout - a 510 large point of this specification is to allow that packet format to 511 be negotiated and decided between the Client and Replicator, with the 512 information passed back via the stream-format data. 514 One example of what the resulting packet may look like (but not a 515 normative listing of what it is - the actual format can be any 516 combination of fields, of any size, in any order), the data inside 517 the resulting data stream after the UDP tunnel header may look like 518 the following: 520 Example 1: Packet layout 522 0 1 2 3 523 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 524 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 525 | Incoming Port | Timestamp | 526 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 527 |Act| Frame Length | Internal Data 1 | 528 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 529 | Payload | 530 | ... | 531 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 533 Figure 2 535 This non-normative example may be associated with a stream-format as 536 per the following table: 538 +-----------+-------+------------------------+----------------------+ 539 | Field | Field | Field Type | Field Type-Data | 540 | Name | Size | | | 541 +===========+=======+========================+======================+ 542 | Incoming | 8 | port-ingress | A listing of | 543 | port | | | values that may be | 544 | | | | seen in this | 545 | | | | field, mapped to | 546 | | | | interface-refs | 547 | | | | from [RFC8343]. | 548 +-----------+-------+------------------------+----------------------+ 549 | Timestamp | 24 | timestamp-nsec-ingress | Two 32-bit numbers | 550 | | | | giving when the | 551 | | | | "0" of this field | 552 | | | | is based off of, | 553 | | | | using the PTP | 554 | | | | Truncated | 555 | | | | Timestamp format. | 556 +-----------+-------+------------------------+----------------------+ 557 | Act | 2 | action | A listing of | 558 | | | | values that may be | 559 | | | | seen in this | 560 | | | | field, mapped to | 561 | | | | action types | 562 | | | | (accepted, | 563 | | | | dropped, etc.) | 564 +-----------+-------+------------------------+----------------------+ 565 | Frame | 17 | frame-length-ingress | Note that this | 566 | Length | | | denotes the | 567 | | | | original frame | 568 | | | | length - the | 569 | | | | payload field MAY | 570 | | | | not include the | 571 | | | | entire payload. | 572 +-----------+-------+------------------------+----------------------+ 573 | Internal | 13 | padding | Note that this may | 574 | Data 1 | | | be ASIC-internal- | 575 | | | | only data, or some | 576 | | | | other information | 577 | | | | that would be | 578 | | | | expensive to prune | 579 | | | | out. 'padding' | 580 | | | | fields MUST have | 581 | | | | all content | 582 | | | | ignored. | 583 +-----------+-------+------------------------+----------------------+ 584 | Payload | 0 | frame-payload-ingress | | 585 +-----------+-------+------------------------+----------------------+ 587 Table 1: Example 1: Stream-format data 589 Another non-normative example, which is similar to the 590 [I-D.tuexen-opsawg-pcapng] enhanced packet block (EPB) format (and 591 thus, this Replicator may in fact be a server offering a tcpdump- 592 based backend using this frontend): 594 +-----------+-------+--------------------+---------------------+ 595 | Field | Field | Field Type | Field Type-Data | 596 | Name | Size | | | 597 +===========+=======+====================+=====================+ 598 | Interface | 32 | port | A listing of values | 599 | ID | | | that may be seen in | 600 | | | | this field, mapped | 601 | | | | to interface-refs | 602 | | | | from [RFC8343]. | 603 +-----------+-------+--------------------+---------------------+ 604 | Timestamp | 64 | timestamp-msec | Two 32-bit numbers | 605 | | | | giving when the "0" | 606 | | | | of this field is | 607 | | | | based off of, using | 608 | | | | the PTP Truncated | 609 | | | | Timestamp format. | 610 +-----------+-------+--------------------+---------------------+ 611 | Captured | 32 | frame-payload-size | Note: This allows | 612 | Packet | | | us to have the | 613 | Length | | | Options field as | 614 | | | | our real variable | 615 | | | | length field. | 616 +-----------+-------+--------------------+---------------------+ 617 | Original | 32 | frame-length | | 618 | Packet | | | | 619 | Length | | | | 620 +-----------+-------+--------------------+---------------------+ 621 | Packet | 0 | frame-payload | | 622 | Data | | | | 623 +-----------+-------+--------------------+---------------------+ 624 | Options | 0 | padding | | 625 +-----------+-------+--------------------+---------------------+ 627 Table 2: Packet-format response example 2 629 To restate the prior note, the above is purely an example of what the 630 format could be - the actual format used is negotiated between the 631 Client and Replicator, and can have practically any layout, with any 632 additional fields. 634 A Client SHOULD take efforts to be notified when a change has 635 occurred on the Replicator (e.g., port or line card changes, device 636 reboot, etc.), and re-verify and re-apply as needed its sampled 637 streaming configurations when such a change is detected. 639 5. IANA Considerations 641 This document defines a new UDP port number, entitled "Sampled 642 Streaming", and assigns a value of TBD1 from the Service Name and 643 Transport Protocol Port Number Registry 644 https://www.iana.org/assignments/service-names-port-numbers/service- 645 names-port-numbers.xhtml: 647 +------+-------------------+ 648 | Tag | Description | 649 +======+===================+ 650 | TBD1 | Sampled Streaming | 651 +------+-------------------+ 653 Table 3 655 This document requests registration of a URI in the "IETF XML 656 Registry" RFC 3688 [RFC3688]. Following the format in RFC 3688, the 657 following registration is suggested: 659 URI: urn:ietf:params:xml:ns:yang:ietf-sampled-streaming 660 Registrant Contact: The IESG. 661 XML: N/A, the requested URI is an XML namespace. 663 This document registers a YANG module in the "YANG Module Names" 664 registry RFC 6020 [RFC6020]: 666 name: ietf-sampled-streaming 667 namespace: urn:ietf:params:xml:ns:yang:ietf-sampled-streaming 668 prefix: ss 669 reference: This document 671 6. Security Considerations 673 Vendors and deployments must take into consideration that this 674 functionality allows a mirroring of traffic, with configurable 675 destinations and filters. Similar functionality already exists in 676 various remote packet mirroring systems, and similar considerations 677 should be taken. Filters utilizing the source port of TBD1 SHOULD be 678 applied at the edges of a provider's network to provide an additional 679 layer of security. 681 A Replicator SHOULD ensure that Clients can only see their own 682 entries in the 'samplers', and MUST ensure that once a Client has 683 created an entry in the samplers list, only that same Client may re- 684 query or make changes to it. 686 7. Acknowledgments 688 The authors would like to thank Joe Clarke, Marek Hajduczenia, Brian 689 Harber, Paolo Lucente, Jim Rampley, and Dmytro Shytyi for their 690 reviews and providing helpful suggestions and feedback of this draft. 692 8. References 694 8.1. Normative References 696 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 697 Requirement Levels", BCP 14, RFC 2119, 698 DOI 10.17487/RFC2119, March 1997, 699 . 701 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 702 DOI 10.17487/RFC3688, January 2004, 703 . 705 [RFC5476] Claise, B., Ed., Johnson, A., and J. Quittek, "Packet 706 Sampling (PSAMP) Protocol Specifications", RFC 5476, 707 DOI 10.17487/RFC5476, March 2009, 708 . 710 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 711 the Network Configuration Protocol (NETCONF)", RFC 6020, 712 DOI 10.17487/RFC6020, October 2010, 713 . 715 [RFC6728] Muenz, G., Claise, B., and P. Aitken, "Configuration Data 716 Model for the IP Flow Information Export (IPFIX) and 717 Packet Sampling (PSAMP) Protocols", RFC 6728, 718 DOI 10.17487/RFC6728, October 2012, 719 . 721 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 722 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 723 . 725 8.2. Informative References 727 [I-D.tuexen-opsawg-pcapng] 728 Tuexen, M., Risso, F., Bongertz, J., Combs, G., Harris, 729 G., and M. Richardson, "PCAP Next Generation (pcapng) 730 Capture File Format", Work in Progress, Internet-Draft, 731 draft-tuexen-opsawg-pcapng-01, 27 March 2020, 732 . 735 Appendix A. Yang Model Tree Reference 737 module: ietf-sampled-streaming 738 +--rw points* [name] 739 +--rw name psamp:nameType 740 +--rw observationPoints* [name] 741 | +--rw name psamp:nameType 742 | +--ro observationPointId? uint32 743 | +--rw observationDomainId uint32 744 | +--rw ifName* ifNameType 745 | +--rw ifIndex* uint32 746 | +--rw entPhysicalName* string 747 | +--rw entPhysicalIndex* uint32 748 | +--rw direction? direction 749 +--rw selectors* [name] 750 | +--rw name psamp:nameType 751 | +--rw (Method) 752 | | +--:(selectAll) 753 | | | +--rw selectAll? empty 754 | | +--:(sampCountBased) 755 | | | +--rw sampCountBased {psampSampCountBased}? 756 | | | +--rw packetInterval uint32 757 | | | +--rw packetSpace uint32 758 | | +--:(sampTimeBased) 759 | | | +--rw sampTimeBased {psampSampTimeBased}? 760 | | | +--rw timeInterval uint32 761 | | | +--rw timeSpace uint32 762 | | +--:(sampRandOutOfN) 763 | | | +--rw sampRandOutOfN {psampSampRandOutOfN}? 764 | | | +--rw size uint32 765 | | | +--rw population uint32 766 | | +--:(sampUniProb) 767 | | | +--rw sampUniProb {psampSampUniProb}? 768 | | | +--rw probability decimal64 769 | | +--:(filterMatch) 770 | | | +--rw filterMatch {psampFilterMatch}? 771 | | | +--rw (nameOrId) 772 | | | | +--:(ieName) 773 | | | | | +--rw ieName? ieNameType 774 | | | | +--:(ieId) 775 | | | | +--rw ieId? ieIdType 776 | | | +--rw ieEnterpriseNumber? uint32 777 | | | +--rw value string 778 | | +--:(filterHash) 779 | | +--rw filterHash {psampFilterHash}? 780 | | +--rw hashFunction? identityref 781 | | +--rw initializerValue? uint64 782 | | +--rw ipPayloadOffset? uint64 783 | | +--rw ipPayloadSize? uint64 784 | | +--rw digestOutput? boolean 785 | | +--ro outputRangeMin? uint64 786 | | +--ro outputRangeMax? uint64 787 | | +--rw selectedRange* [name] 788 | | +--rw name nameType 789 | | +--rw min? uint64 790 | | +--rw max? uint64 791 | +--ro packetsObserved? yang:counter64 792 | +--ro packetsDropped? yang:counter64 793 | +--ro selectorDiscontinuityTime? yang:date-and-time 794 +--ro filters* [] 795 | +--ro filter filter-type 796 +--ro max-samplers? uint32 797 +--ro max-filters? uint32 798 +--ro max-frame-length-copy? uint16 799 +--ro max-frame-depth-inspect? uint16 800 +--rw samplers* [name] 801 +--rw name string 802 +--rw status status-type 803 +--rw client-heartbeat uint32 804 +--rw destination 805 | +--rw type destination-type 806 | +--rw udp-parameters 807 | +--rw destination-ip inet:ip-address-no-zone 808 | +--rw destination-port inet:port-number 809 +--rw request 810 | +--rw filters 811 | | +--rw name? string 812 | | +--rw interfaces* [int] 813 | | | +--rw int if:interface-ref 814 | | +--rw actions* [action] 815 | | | +--rw action action-type 816 | | +--rw direction? psamp:direction 817 | | +--rw type filter-type 818 | | +--rw ipv4-address? inet:ipv4-address-no-zone 819 | | +--rw ipv6-address? inet:ipv6-address-no-zone 820 | | +--rw version? inet:ip-version 821 | | +--rw frame-payload 822 | | | +--rw offset? uint16 823 | | | +--rw match? binary 824 | | +--rw frame-length? uint16 825 | +--rw selector 826 | | +--rw (Method) 827 | | | +--:(selectAll) 828 | | | | +--rw selectAll? empty 829 | | | +--:(sampCountBased) 830 | | | | +--rw sampCountBased {psampSampCountBased}? 831 | | | | +--rw packetInterval uint32 832 | | | | +--rw packetSpace uint32 833 | | | +--:(sampTimeBased) 834 | | | | +--rw sampTimeBased {psampSampTimeBased}? 835 | | | | +--rw timeInterval uint32 836 | | | | +--rw timeSpace uint32 837 | | | +--:(sampRandOutOfN) 838 | | | | +--rw sampRandOutOfN {psampSampRandOutOfN}? 839 | | | | +--rw size uint32 840 | | | | +--rw population uint32 841 | | | +--:(sampUniProb) 842 | | | | +--rw sampUniProb {psampSampUniProb}? 843 | | | | +--rw probability decimal64 844 | | | +--:(filterMatch) 845 | | | | +--rw filterMatch {psampFilterMatch}? 846 | | | | +--rw (nameOrId) 847 | | | | | +--:(ieName) 848 | | | | | | +--rw ieName? ieNameType 849 | | | | | +--:(ieId) 850 | | | | | +--rw ieId? ieIdType 851 | | | | +--rw ieEnterpriseNumber? uint32 852 | | | | +--rw value string 853 | | | +--:(filterHash) 854 | | | +--rw filterHash {psampFilterHash}? 855 | | | +--rw hashFunction? identityref 856 | | | +--rw initializerValue? uint64 857 | | | +--rw ipPayloadOffset? uint64 858 | | | +--rw ipPayloadSize? uint64 859 | | | +--rw digestOutput? boolean 860 | | | +--ro outputRangeMin? uint64 861 | | | +--ro outputRangeMax? uint64 862 | | | +--rw selectedRange* [name] 863 | | | +--rw name nameType 864 | | | +--rw min? uint64 865 | | | +--rw max? uint64 866 | | +--ro packetsObserved? yang:counter64 867 | | +--ro packetsDropped? yang:counter64 868 | | +--ro selectorDiscontinuityTime? yang:date-and-time 869 | +--rw ratio uint32 870 | +--rw min-ratio? uint32 871 | +--rw max-ratio? uint32 872 +--ro proposals* [id] 873 | +--ro id uint32 874 | +--ro selector 875 | | +--ro (Method) 876 | | | +--:(selectAll) 877 | | | | +--ro selectAll? empty 878 | | | +--:(sampCountBased) 879 | | | | +--ro sampCountBased {psampSampCountBased}? 880 | | | | +--ro packetInterval uint32 881 | | | | +--ro packetSpace uint32 882 | | | +--:(sampTimeBased) 883 | | | | +--ro sampTimeBased {psampSampTimeBased}? 884 | | | | +--ro timeInterval uint32 885 | | | | +--ro timeSpace uint32 886 | | | +--:(sampRandOutOfN) 887 | | | | +--ro sampRandOutOfN {psampSampRandOutOfN}? 888 | | | | +--ro size uint32 889 | | | | +--ro population uint32 890 | | | +--:(sampUniProb) 891 | | | | +--ro sampUniProb {psampSampUniProb}? 892 | | | | +--ro probability decimal64 893 | | | +--:(filterMatch) 894 | | | | +--ro filterMatch {psampFilterMatch}? 895 | | | | +--ro (nameOrId) 896 | | | | | +--:(ieName) 897 | | | | | | +--ro ieName? ieNameType 898 | | | | | +--:(ieId) 899 | | | | | +--ro ieId? ieIdType 900 | | | | +--ro ieEnterpriseNumber? uint32 901 | | | | +--ro value string 902 | | | +--:(filterHash) 903 | | | +--ro filterHash {psampFilterHash}? 904 | | | +--ro hashFunction? identityref 905 | | | +--ro initializerValue? uint64 906 | | | +--ro ipPayloadOffset? uint64 907 | | | +--ro ipPayloadSize? uint64 908 | | | +--ro digestOutput? boolean 909 | | | +--ro outputRangeMin? uint64 910 | | | +--ro outputRangeMax? uint64 911 | | | +--ro selectedRange* [name] 912 | | | +--ro name nameType 913 | | | +--ro min? uint64 914 | | | +--ro max? uint64 915 | | +--ro packetsObserved? yang:counter64 916 | | +--ro packetsDropped? yang:counter64 917 | | +--ro selectorDiscontinuityTime? yang:date-and-time 918 | +--ro performance-penalty? boolean 919 | +--ro performance-penalty-amount? uint16 920 | +--ro stream-format 921 | | +--ro fields* [name] 922 | | +--ro name string 923 | | +--ro size? uint32 924 | | +--ro type? field-type 925 | | +--ro action-mappings* [value] 926 | | | +--ro value binary 927 | | | +--ro meaning? action-type 928 | | +--ro port-mappings* [value] 929 | | | +--ro value binary 930 | | | +--ro port? if:interface-ref 931 | | +--ro direction-mappings* [value] 932 | | | +--ro value binary 933 | | | +--ro direction? psamp:direction 934 | | +--ro timestamp 935 | | | +--ro seconds? uint32 936 | | | +--ro nanoseconds? uint32 937 | | +--ro payload-contents? frame-headers 938 | +--ro filters* [name] 939 | +--ro name string 940 | +--ro interfaces* [int] 941 | | +--ro int if:interface-ref 942 | +--ro actions* [action] 943 | | +--ro action action-type 944 | +--ro direction? psamp:direction 945 | +--ro type filter-type 946 | +--ro ipv4-address? inet:ipv4-address-no-zone 947 | +--ro ipv6-address? inet:ipv6-address-no-zone 948 | +--ro version? inet:ip-version 949 | +--ro frame-payload 950 | | +--ro offset? uint16 951 | | +--ro match? binary 952 | +--ro frame-length? uint16 953 +--rw proposal-error? string 954 +--rw proposal-selected? uint32 955 +--rw install-error? string 957 Appendix B. Yang Model 959 module ietf-sampled-streaming { 960 namespace "urn:ietf:params:xml:ns:yang:ietf-sampled-streaming"; 961 prefix ss; 963 import ietf-interfaces { 964 prefix if; 965 } 966 import ietf-inet-types { 967 prefix inet; 968 } 969 import ietf-ipfix-psamp { 970 prefix psamp; 971 revision-date 2012-09-05; 972 } 974 organization 975 "IETF Working Group"; 976 contact 977 "Editor: Andrew Gray 978 "; 979 description 980 "This module contains a collection of YANG definitions for 981 managing sampled streaming subscriptions. 983 Copyright (c) 2019 IETF Trust and the persons identified as 984 authors of the code. All rights reserved. 986 Redistribution and use in source and binary forms, with or 987 without modification, is permitted pursuant to, and subject to 988 the license terms contained in, the Simplified BSD License set 989 forth in Section 4.c of the IETF Trust's Legal Provisions 990 Relating to IETF Documents 991 (https://trustee.ietf.org/license-info). 993 This version of this YANG module is part of RFC XXXX 994 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 995 for full legal notices. 997 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 998 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 999 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1000 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1001 they appear in all capitals, as shown here."; 1003 revision 2019-12-27 { 1004 description 1005 "Clarifications based on feedback for -03 draft. Utilize parts 1006 of RFC 6728 to avoid redundancy, where possible."; 1007 reference 1008 "draft-gray-sampled-streaming-03"; 1009 } 1010 revision 2019-10-22 { 1011 description 1012 "Updates based on feedback for -02 draft: Adding more forwarded 1013 action-types. frame-payload changed to be explicit about 1014 direction. Added -size types explicitly for frame-payload and 1015 padding to allow using more than one zero-length field."; 1016 reference 1017 "draft-gray-sampled-streaming-02"; 1018 } 1019 revision 2019-08-06 { 1020 description 1021 "Updates based on feedback for -01 draft."; 1022 reference 1023 "draft-gray-sampled-streaming-01"; 1024 } 1025 revision 2019-06-25 { 1026 description 1027 "Initial version."; 1028 reference 1029 "draft-gray-sampled-streaming-00"; 1030 } 1032 typedef filter-type { 1033 type enumeration { 1034 enum interfaces { 1035 description 1036 "List of interfaces to filter against."; 1037 } 1038 enum action { 1039 description 1040 "Filter against a list of actions that the Point took (i.e. 1041 only consider packets that were actually forwarded)."; 1042 } 1043 enum direction { 1044 description 1045 "Direction to sample traffic in."; 1046 } 1047 enum ip-version { 1048 description 1049 "The version number in the IP header."; 1050 } 1051 enum ip-v4-srcip { 1052 description 1053 "The IPv4 header's source IPv4 address."; 1054 } 1055 enum ip-v4-dstip { 1056 description 1057 "The IPv4 header's destination IPv4 address."; 1058 } 1059 enum ip-v4-ttl { 1060 description 1061 "The IPv4 header's Time to Live."; 1062 } 1063 enum ip-v4-prot { 1064 description 1065 "The IPv4 header's protocol number."; 1066 } 1067 enum ip-v6-srcip { 1068 description 1069 "The IPv6 header's source IPv4 address."; 1070 } 1071 enum ip-v6-dstip { 1072 description 1073 "The IPv6 header's destination IPv4 address."; 1074 } 1075 enum frame-size { 1076 description 1077 "The total size of the frame."; 1078 } 1079 enum frame-payload { 1080 description 1081 "Specific payload octets."; 1082 } 1083 enum frame-length { 1084 description 1085 "Specific frame length."; 1086 } 1087 } 1088 description 1089 "The filtering abilities available."; 1090 } 1092 typedef field-type { 1093 type enumeration { 1094 enum padding { 1095 description 1096 "Padding bits that MUST be ignored."; 1097 } 1098 enum padding-size { 1099 description 1100 "This packet's length of a variable-length padding field."; 1101 } 1102 enum port { 1103 description 1104 "An indication of the port the traffic was sampled from."; 1105 } 1106 enum direction { 1107 description 1108 "Which direction the traffic went."; 1109 } 1110 enum port-ingress { 1111 description 1112 "What port the traffic was received from (may be different 1113 than 'port')"; 1114 } 1115 enum port-egress { 1116 description 1117 "What port the traffic is leaving on (may be different than 1118 'port')"; 1120 } 1121 enum timestamp-msec-ingress { 1122 description 1123 "The timestamp the packet was received at, in integer 1124 milliseconds. The epoch of this number is provided in the 1125 timestamp container of the returned field information."; 1126 } 1127 enum timestamp-usec-ingress { 1128 description 1129 "The timestamp the packet was received at, in integer 1130 microseconds. The epoch of this number is provided in the 1131 timestamp container of the returned field information."; 1132 } 1133 enum timestamp-nsec-ingress { 1134 description 1135 "The timestamp the packet was received at, in integer 1136 nanoseconds. The epoch of this number is provided in the 1137 timestamp container of the returned field information."; 1138 } 1139 enum timestamp-msec-egress { 1140 description 1141 "The timestamp the packet left the point at, in integer 1142 milliseconds. The epoch of this number is provided in the 1143 timestamp container of the returned field information."; 1144 } 1145 enum timestamp-usec-egress { 1146 description 1147 "The timestamp the packet left the point at, in integer 1148 microseconds. The epoch of this number is provided in the 1149 timestamp container of the returned field information."; 1150 } 1151 enum timestamp-nsec-egress { 1152 description 1153 "The timestamp the packet left the point at, in integer 1154 nanoseconds. The epoch of this number is provided in the 1155 timestamp container of the returned field information."; 1156 } 1157 enum frame-length { 1158 description 1159 "The generic frame length. Note that due to chipset 1160 capabilities, this MAY not be the same as the captured 1161 packet length."; 1162 } 1163 enum frame-length-ingress { 1164 description 1165 "The frame length as received by the point. Note that due 1166 to chipset capabilities, this MAY not be the same as the 1167 captured packet length."; 1169 } 1170 enum frame-length-egress { 1171 description 1172 "The frame length after local processing, as it leaves the 1173 point. Note that due to chipset capabilities, this MAY 1174 not be the same as the captured packet length."; 1175 } 1176 enum frame-payload-size { 1177 description 1178 "The length of the payload that has actually been copied 1179 into this stream."; 1180 } 1181 enum frame-payload-ingress { 1182 description 1183 "The payload of the frame, as received the point."; 1184 } 1185 enum frame-payload-egress { 1186 description 1187 "The payload of the frame, as it leaves the point."; 1188 } 1189 enum action { 1190 description 1191 "The action that was taken on this frame. Values are 1192 mapped as according to action-type."; 1193 } 1194 } 1195 description 1196 "Types of data included in the data stream provided back to 1197 the receiver. Note that all fields MAY not be provided."; 1198 } 1200 typedef action-type { 1201 type enumeration { 1202 enum forwarded { 1203 description 1204 "Generically forwarded normally through the system. A more 1205 specific action type code SHOULD be used."; 1206 } 1207 enum forwarded-label-change { 1208 description 1209 "Forwarded, with a generic MPLS label change having 1210 occurred."; 1211 } 1212 enum forwarded-label-swap { 1213 description 1214 "Forwarded, with a MPLS label swap."; 1215 } 1216 enum forwarded-label-pop { 1217 description 1218 "Forwarded, with a MPLS label pop."; 1219 } 1220 enum forwarded-label-push { 1221 description 1222 "Forwarded, with a MPLS label push."; 1223 } 1224 enum forwarded-cpu-punt { 1225 description 1226 "Forwarded after a CPU punt."; 1227 } 1228 enum forwarded-tunnel { 1229 description 1230 "Forwarded with additional outer wrapper for tunneling."; 1231 } 1232 enum forwarded-tunnel-frr { 1233 description 1234 "Forwarded with additional outer wrapper due to fast 1235 reroute."; 1236 } 1237 enum dropped { 1238 description 1239 "Generically dropped. A more specific action type code 1240 SHOULD be used."; 1241 } 1242 enum dropped-rate-limit { 1243 description 1244 "Dropped due to a rate limiter applied."; 1245 } 1246 enum dropped-buffer { 1247 description 1248 "Dropped due to no buffer space."; 1249 } 1250 enum dropped-security { 1251 description 1252 "Dropped due to a security policy."; 1253 } 1254 enum dropped-error { 1255 description 1256 "Dropped due to the frame being in error."; 1257 } 1258 enum dropped-cpu-punt { 1259 description 1260 "Dropped after a CPU punt."; 1261 } 1262 enum passed-to-cpu { 1263 description 1264 "Passed on to the CPU, but what the CPU did with it is 1265 unknown."; 1266 } 1267 } 1268 description 1269 "Possible actions taken on a packet."; 1270 } 1272 typedef destination-type { 1273 type enumeration { 1274 enum udp { 1275 description 1276 "Sent with a UDP header."; 1277 } 1278 } 1279 description 1280 "Different possible destination types."; 1281 } 1283 typedef status-type { 1284 type enumeration { 1285 enum client-request-complete { 1286 description 1287 "The Client has completed its request setup."; 1288 } 1289 enum replicator-proposals-available { 1290 description 1291 "The Replicator has finished processing the request, and 1292 has proposals available in the 'proposals' branch."; 1293 } 1294 enum replicator-proposal-error { 1295 description 1296 "The Replicator encountered an error attempting to come up 1297 with a proposal. 'proposal-error' MAY contain an 1298 explanation."; 1299 } 1300 enum client-proposal-selected { 1301 description 1302 "The Client has updated 'proposal-selected' and is ready 1303 for the Replicator to install the requested sampling."; 1304 } 1305 enum replicator-install-success { 1306 description 1307 "The Replicator has successfully activated the sampling, 1308 and it is operating."; 1309 } 1310 enum replicator-install-error { 1311 description 1312 "The Replicator encountered an error installing the 1313 sampling. 'install-error' MAY contain an explanation."; 1314 } 1315 } 1316 description 1317 "The status of a sampler entry."; 1318 } 1320 typedef frame-headers { 1321 type bits { 1322 bit eth-l1-preamble { 1323 position 0; 1324 description 1325 "Will include the Ethernet preamble."; 1326 } 1327 bit eth-l1-sof { 1328 position 1; 1329 description 1330 "Will include the Ethernet start of frame 1331 delimiter"; 1332 } 1333 bit eth-l2-dmac { 1334 position 2; 1335 description 1336 "Will include the outer Ethernet destination MAC."; 1337 } 1338 bit eth-l2-smac { 1339 position 3; 1340 description 1341 "Will include the outer Ethernet source MAC."; 1342 } 1343 bit eth-l2-vlan { 1344 position 4; 1345 description 1346 "Will include any 802.1Q-2018 VLAN tags."; 1347 } 1348 bit eth-l2-type { 1349 position 5; 1350 description 1351 "Will include the Ethertype or size."; 1352 } 1353 bit eth-l2-fcs { 1354 position 6; 1355 description 1356 "Will include the Frame Check Sequence after the 1357 payload."; 1358 } 1359 bit eth-l1-ipg { 1360 position 7; 1361 description 1362 "Will include the inter-packet gap. Be aware that 1363 different Ethernet speeds may have different lengths."; 1364 } 1365 bit mpls-tags { 1366 position 8; 1367 description 1368 "Will include MPLS tags."; 1369 } 1370 } 1371 description 1372 "Listing of fields to be provided in a frame capture."; 1373 } 1375 grouping filters { 1376 description 1377 "Filter definition. Multiple filters are ANDed."; 1378 leaf name { 1379 type string { 1380 length "1..255"; 1381 } 1382 description 1383 "A name for this filter."; 1384 } 1385 list interfaces { 1386 when "../type = 'interfaces'"; 1387 key "int"; 1388 description 1389 "Filter down to only this list of interfaces."; 1390 leaf int { 1391 type if:interface-ref; 1392 description 1393 "A specific interface to filter against."; 1394 } 1395 } 1396 list actions { 1397 when "../type = 'action'"; 1398 key "action"; 1399 description 1400 "Filter down to only this list of actions."; 1401 leaf action { 1402 type action-type; 1403 description 1404 "One specific action code."; 1405 } 1406 } 1407 leaf direction { 1408 when "../type = 'direction'"; 1409 type psamp:direction; 1410 description 1411 "Which direction(s) to sample traffic in."; 1412 } 1413 leaf type { 1414 type filter-type; 1415 mandatory true; 1416 description 1417 "The type of filter associated."; 1418 } 1419 leaf ipv4-address { 1420 when "../type = 'ip-v4-srcip' | ../type = 'ip-v4-dstip'"; 1421 type inet:ipv4-address-no-zone; 1422 description 1423 "The IPv4 address to filter on."; 1424 } 1425 leaf ipv6-address { 1426 when "../type = 'ip-v6-srcip' | ../type = 'ip-v6-dstip'"; 1427 type inet:ipv6-address-no-zone; 1428 description 1429 "The IPv6 address to filter on."; 1430 } 1431 leaf version { 1432 when "../type = 'ip-version'"; 1433 type inet:ip-version; 1434 description 1435 "The value of the IP version number to match on."; 1436 } 1437 container frame-payload { 1438 when "../type = 'frame-payload'"; 1439 description 1440 "Frame payload fragment to match on."; 1441 leaf offset { 1442 type uint16; 1443 description 1444 "Offset in octets from the start of the frame to begin the 1445 match on."; 1446 } 1447 leaf match { 1448 type binary; 1449 description 1450 "The bytes to match on."; 1451 } 1452 } 1453 leaf frame-length { 1454 when "../type = 'frame-length'"; 1455 type uint16; 1456 description 1457 "Frame length to match on."; 1458 } 1459 } 1461 grouping stream-format { 1462 description 1463 "This contains the packet format data that this sampling stream 1464 is sending. This is only valid after configuration. The 1465 length fields are given in bits, and are consecutive. Needed 1466 gaps should use a 'padding' element."; 1467 list fields { 1468 key "name"; 1469 description 1470 "The listing of the fields that will be encapsulated and sent 1471 to the receiver."; 1472 leaf name { 1473 type string { 1474 length "1..255"; 1475 } 1476 description 1477 "Human readable name of what this field contains."; 1478 } 1479 leaf size { 1480 type uint32 { 1481 range "0..524280"; 1482 } 1483 description 1484 "The size of this field, in bits. The value of '0' denotes 1485 a variable-sized field."; 1486 } 1487 leaf type { 1488 type field-type; 1489 description 1490 "The type of this data."; 1491 } 1492 list action-mappings { 1493 when "../type='action'"; 1494 key "value"; 1495 description 1496 "The mapping of values to action-type codes, valid for 1497 type=action."; 1498 leaf value { 1499 type binary; 1500 description 1501 "The value that will appear in the header."; 1502 } 1503 leaf meaning { 1504 type action-type; 1505 description 1506 "What this value indicates."; 1507 } 1508 } 1509 list port-mappings { 1510 when "../type='ingress-port' | ../type='egress-port'"; 1511 key "value"; 1512 description 1513 "The mapping of values to interfaces, valid for 1514 type=ingress-port or type=egress-port"; 1515 leaf value { 1516 type binary; 1517 description 1518 "The value that will appear in the header."; 1519 } 1520 leaf port { 1521 type if:interface-ref; 1522 description 1523 "The port the value maps to."; 1524 } 1525 } 1526 list direction-mappings { 1527 when "../type='direction'"; 1528 key "value"; 1529 description 1530 "The mapping of values to direction codes, valid for 1531 type=direction."; 1532 leaf value { 1533 type binary; 1534 description 1535 "The value that will appear in the header."; 1536 } 1537 leaf direction { 1538 type psamp:direction; 1539 description 1540 "The direction the traffic in respect to the port. The 1541 value 'both' MUST NOT be used here."; 1542 } 1543 } 1544 container timestamp { 1545 when "../type='timestamp-nsec' | ../type='timestamp-usec' | 1546 ../type='timestamp-msec'"; 1547 description 1548 "Supplemental data for type=timestamp*, in PTP Truncated 1549 Timestamp Format. Provides the time used as the epoch for 1550 the number in the data stream."; 1551 leaf seconds { 1552 type uint32; 1553 description 1554 "Specifies the integer portion of the number of seconds 1555 since the epoch."; 1556 } 1557 leaf nanoseconds { 1558 type uint32; 1559 description 1560 "Specifies the fractional portion of the number of 1561 seconds since the epoch, in integer number of 1562 nanoseconds."; 1563 } 1564 } 1565 leaf payload-contents { 1566 when "../type='frame-payload-ingress' | 1567 ../type='frame-payload-egress'"; 1568 type frame-headers; 1569 description 1570 "Details about what parts of the frame this payload field 1571 SHOULD contain. Note carefully the 'SHOULD' - for a 1572 variety of reasons (different forwarding paths, exception 1573 handling, etc.), the actual headers of any one frame MAY 1574 be different than this."; 1575 } 1576 } 1577 } 1579 list points { 1580 key "name"; 1581 description 1582 "A listing of the observation points available on this device, what 1583 ports they provide for, and what filtering is available at 1584 those points."; 1585 leaf name { 1586 type psamp:nameType; 1587 description 1588 "A unique name for this point."; 1589 } 1590 list observationPoints { 1591 key "name"; 1592 description 1593 "A list of the observation points (i.e. interfaces) able to be 1594 monitored at this point."; 1595 leaf name { 1596 type psamp:nameType; 1597 description 1598 "Name of this observationPoint"; 1599 } 1600 uses psamp:observationPointParameters; 1602 } 1603 list selectors { 1604 key "name"; 1605 description 1606 "List of packet selector options available at this point."; 1607 leaf name { 1608 type psamp:nameType; 1609 description 1610 "A unique name for this selector option."; 1611 } 1612 uses psamp:selectorParameters; 1613 } 1614 list filters { 1615 config false; 1616 description 1617 "List of filtering options available at this point."; 1618 leaf filter { 1619 type filter-type; 1620 mandatory true; 1621 description 1622 "One specific filter available at this point."; 1623 } 1624 } 1625 leaf max-samplers { 1626 type uint32; 1627 config false; 1628 description 1629 "The maximum number of additional samplers that can be 1630 installed at this point."; 1631 } 1632 leaf max-filters { 1633 type uint32; 1634 config false; 1635 description 1636 "The maximum number of filtering rules permitted at this 1637 location. Note this is an absolute maximum, and fewer rules 1638 that are complex may still be rejected by the device."; 1639 } 1640 leaf max-frame-length-copy { 1641 type uint16; 1642 config false; 1643 description 1644 "The maximum size that the point can replicate and copy into 1645 the header."; 1646 } 1647 leaf max-frame-depth-inspect { 1648 type uint16; 1649 config false; 1650 description 1651 "The offset of the last octet in a frame the point can 1652 perform filtering against."; 1653 } 1654 list samplers { 1655 key "name"; 1656 description 1657 "A list of all the samplers attached to this point."; 1658 leaf name { 1659 type string; 1660 mandatory true; 1661 description 1662 "A unique name given to this sampler."; 1663 } 1664 leaf status { 1665 type status-type; 1666 mandatory true; 1667 description 1668 "The current status of this sampler."; 1669 } 1670 leaf client-heartbeat { 1671 type uint32; 1672 mandatory true; 1673 description 1674 "The number of seconds since the Client has refreshed this 1675 request. The Client MUST only be able to set this value 1676 to 0, the Replicator MUST keep track of it, and SHOULD 1677 delete this entry when it reaches 3600."; 1678 } 1679 container destination { 1680 description 1681 "The destination of where to send the UDP stream to."; 1682 leaf type { 1683 type destination-type; 1684 mandatory true; 1685 description 1686 "The type of encoding for the destination."; 1687 } 1688 container udp-parameters { 1689 when "../type='udp'"; 1690 description 1691 "Parameters for destination-type=udp. Source port is 1692 always the port number assigned by IANA."; 1693 leaf destination-ip { 1694 type inet:ip-address-no-zone; 1695 mandatory true; 1696 description 1697 "The destination IP to send the stream to."; 1699 } 1700 leaf destination-port { 1701 type inet:port-number; 1702 mandatory true; 1703 description 1704 "The destination UDP port number to send the stream 1705 to."; 1706 } 1707 } 1708 } 1709 container request { 1710 description 1711 "The request as sent in by a Client."; 1712 container filters { 1713 description 1714 "Requested filters to apply to the stream."; 1715 uses filters; 1716 } 1717 container selector { 1718 description 1719 "Requested packet Selector."; 1720 uses psamp:selectorParameters; 1721 } 1722 leaf ratio { 1723 type uint32 { 1724 range "1..max"; 1725 } 1726 mandatory true; 1727 description 1728 "The requested sampling ratio (1:N, with N being this 1729 value)."; 1730 } 1731 leaf min-ratio { 1732 type uint32 { 1733 range "1..max"; 1734 } 1735 description 1736 "The minimum value of N the client will accept."; 1737 } 1738 leaf max-ratio { 1739 type uint32 { 1740 range "1..max"; 1741 } 1742 description 1743 "The maximum value of N the client will accept."; 1744 } 1745 } 1746 list proposals { 1747 key "id"; 1748 config false; 1749 description 1750 "The proposals as offered by the Replicator."; 1751 leaf id { 1752 type uint32 { 1753 range "1..max"; 1754 } 1755 description 1756 "An id-number representing this proposal for selection."; 1757 } 1758 container selector { 1759 description 1760 "Provided packet Selector, plus stores statistics when 1761 this proposal is active."; 1762 uses psamp:selectorParameters; 1763 } 1764 leaf performance-penalty { 1765 type boolean; 1766 description 1767 "Selecting this offer will result in a forwarding perfomance 1768 penalty on the device (usually due to ASIC recirculation)"; 1769 } 1770 leaf performance-penalty-amount { 1771 type uint16 { 1772 range "0..10000"; 1773 } 1774 description 1775 "The forwarding performance penalty amount, in hundredths 1776 of a percent. This value is not required even if 1777 performance-penalty is true. If present, it MUST be 1778 treated as an estimate."; 1779 } 1780 container stream-format { 1781 description 1782 "The stream format that would be generated if this 1783 proposal is selected."; 1784 uses stream-format; 1785 } 1786 list filters { 1787 key "name"; 1788 description 1789 "The filters the Replicator can actually apply in this 1790 proposal. These MAY not match the request."; 1791 uses filters; 1792 } 1793 } 1794 leaf proposal-error { 1795 type string { 1796 length "1..1023"; 1797 } 1798 description 1799 "The Replicator was unable to generate any Proposals."; 1800 } 1801 leaf proposal-selected { 1802 type uint32 { 1803 range "1..max"; 1804 } 1805 description 1806 "The ID of the proposal above the Client wants 1807 to use."; 1808 } 1809 leaf install-error { 1810 type string { 1811 length "1..1023"; 1812 } 1813 description 1814 "The Replicator was unable to install the requested 1815 Proposal for this reason."; 1816 } 1817 } 1818 } 1819 } 1821 Authors' Addresses 1823 Andrew Gray 1824 Charter Communications 1825 8560 Upland Drive, Suite B 1826 Englewood, CO 80112 1827 United States of America 1829 Phone: +1 720 699 5125 1830 Email: Andrew.Gray@charter.com 1832 Lawrence J Wobker 1833 Cisco Systems 1834 170 W Tasman Drive 1835 San Jose, CA 95134 1836 United States of America 1838 Phone: +1 984 216 1860 1839 Email: lwobker@cisco.com