Internet DRAFT - draft-gray-sampled-streaming

draft-gray-sampled-streaming







OPSAWG                                                           A. Gray
Internet-Draft                                    Charter Communications
Intended status: Informational                               L.J. Wobker
Expires: 4 October 2020                                    Cisco Systems
                                                            2 April 2020


                       Sampled Traffic Streaming
                    draft-gray-sampled-streaming-03

Abstract

   This document standardizes both 1) a means of requesting a stream of
   packet samples from any device generating, routing, or forwarding
   traffic, and 2) receiving metadata information from the network
   element about these packet samples, and the structure of said stream
   metadata.  A main design requirement is to provide network elements
   with widely varying capabilities (e.g., ASICs, NPUs, NICs, vSwitches,
   CPUs) a mechanism to sample and export packets at high rates, by
   allowing communication of the specific bit formats of internal data
   headers applied to the packet flow, in a way that enhances
   interoperability between traffic sources and sinks.  Historically,
   Netflow and similar mechanisms have been used for these use cases;
   however, the increasing packet rates of very high-speed devices and
   increasing variance in the information available to data planes lends
   itself to both a less-prescriptive set of packet formats as well as a
   decoupling of the sampling action from the collection and analysis
   mechanisms.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 4 October 2020.






Gray & Wobker            Expires 4 October 2020                 [Page 1]

Internet-Draft          Sampled Traffic Streaming             April 2020


Copyright Notice

   Copyright (c) 2020 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Simplified BSD License text
   as described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   3
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
     1.3.  Motivation for Disaggregation of Telemetry  . . . . . . .   3
     1.4.  Comparisons with PSAMP  . . . . . . . . . . . . . . . . .   4
   2.  Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Use Case 1: Traffic Analytics . . . . . . . . . . . . . .   5
     2.2.  Use Case 2: Network Behavior Verification . . . . . . . .   6
     2.3.  Use Case 3: Standardization . . . . . . . . . . . . . . .   6
     2.4.  Use Case 4: Security Automation . . . . . . . . . . . . .   6
   3.  Stream Setup  . . . . . . . . . . . . . . . . . . . . . . . .   7
     3.1.  Client queries Replicator for Points  . . . . . . . . . .   7
     3.2.  Client submits a request to the Replicator  . . . . . . .   8
       3.2.1.  Filtering Details . . . . . . . . . . . . . . . . . .   9
     3.3.  Replicator offers Proposals . . . . . . . . . . . . . . .   9
     3.4.  Client selects a Proposal . . . . . . . . . . . . . . . .  10
     3.5.  Ending sampling and cleanup . . . . . . . . . . . . . . .  11
   4.  Data Stream Format  . . . . . . . . . . . . . . . . . . . . .  11
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  15
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  15
   7.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  16
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  16
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  16
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  16
   Appendix A.  Yang Model Tree Reference  . . . . . . . . . . . . .  17
   Appendix B.  Yang Model . . . . . . . . . . . . . . . . . . . . .  21
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  39

1.  Introduction






Gray & Wobker            Expires 4 October 2020                 [Page 2]

Internet-Draft          Sampled Traffic Streaming             April 2020


1.1.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

1.2.  Terminology

   The following terms are used within this document:

      Client: The device configuring the Replicator.

      Receiver: The device receiving the packet stream.

      Replicator: The device performing the actual packet replication,
      as requested by a Client, and sending the resulting replicated
      packet stream to a Receiver.

      Point: The location inside the Replicator (e.g., a forwarding
      ASIC) that performs the actual packet replication.  There may be
      multiple physical interfaces serviced by one Point, or one
      interface may be serviced by multiple Points, that may have
      different capabilities.

1.3.  Motivation for Disaggregation of Telemetry

   A key concept for this proposal is to enable very high rate sample
   generation for network elements, while at the same time separating
   the sampling mechanism itself from specific analysis or transport
   protocols.  If we separate the component functions of how these
   problems have been traditionally solved, these functions lend
   themselves to being viewed as a layered stack such as the one in the
   figure:

   Figure: Packet sampling and analysis viewed as a layered stack
















Gray & Wobker            Expires 4 October 2020                 [Page 3]

Internet-Draft          Sampled Traffic Streaming             April 2020


   +-+-+-+-+-+-+-+-+-+-+-+-+-+
   |        Analysis         |   Higher level applications perform
   +-+-+-+-+-+-+-+-+-+-+-+-+-+   further analysis on aggregated samples
               ^^
   +-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Collection / Decoding  |   Samples arrives at Receiver, decoded,
   +-+-+-+-+-+-+-+-+-+-+-+-+-+   optionally stored/aggregated
               ^^
   +-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   Export  / Transport   |  Encapsulate packet sample and metadata,
   +-+-+-+-+-+-+-+-+-+-+-+-+-+  send via configured transport protocol
               ^^
   +-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Sampling / Metadata    |  Samples filters packets at a fixed
   +-+-+-+-+-+-+-+-+-+-+-+-+-+  ratio from stream, appends metadata
               ^^
   +-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Data Plane Forwarding  |  Stream of data packets moving through
   +-+-+-+-+-+-+-+-+-+-+-+-+-+  element data plane


                                  Figure 1

   The primary advantage of the stack model is the ability to
   disaggregate functions from each other.  For example, providing a
   self-describing, flexible format for the metadata abstracts the data
   plane -- in other words the upper layers do not need to know how many
   bits wide a metadata field is, they only need to know that it is
   present and the semantics.  Separating the transport function allows
   for multiple use cases: a router wishing to sample packets for
   internal consumption within the same system might use a locally
   defined (perhaps even proprietary) transport header, while putting
   the sampled metadata and packet into a UDP packet allows for it to be
   transported to any IP-reachable collector, regardless of the
   geographic or topological distance from the Replicator itself.

   This document standardizes the "Sampling / Metadata" and "Export /
   Transport" components of the above stack.

1.4.  Comparisons with PSAMP

   Packet Sampling (PSAMP) from RFC 5476 [RFC5476] shares some of the
   characteristics of Sampled Streaming, and parts of its YANG model as
   documented in RFC 6728 [RFC6728] are in fact imported into this one
   to share concepts where possible (notably re-using the concepts of
   observation points and selectors).  However, Sampled Streaming
   differs primarily in the ability to include information that is
   normally internal to device that provides information about the



Gray & Wobker            Expires 4 October 2020                 [Page 4]

Internet-Draft          Sampled Traffic Streaming             April 2020


   packet's handling through the device, and to have the Replicator
   specify the outgoing packet format in a very dynamic fashion that
   suits itself as best as possible.  This is done to allow this
   replication to be done natively on relatively low feature set
   forwarding hardware and to ensure the only usage of high-capability
   CPU resources on the Replicator is in the initial setup and
   negotiation.  All other aspects have been made to allow the
   Replicator to do the least amount of work as possible, to extract as
   much information as possible, and get it sent to the Receiver who is
   presumed to have orders of magnitudes greater compute capability
   available.  Other changes to the setup and configuration are wrapped
   around this primary goal.

2.  Use Cases

   This document is designed around the following current and
   foreseeable use cases that operators have today.

2.1.  Use Case 1: Traffic Analytics

   Operators typically use a mix of NetFlow, IPFIX, and in-line traffic
   samplers spread throughout the network to gather data for analytics.
   With the next generation of hardware, 400Gb/s interfaces are becoming
   available, with higher data rates under development in their
   respective standards bodies.  This will require at least an
   augmentation of any in-line traffic samplers, which are quite
   expensive.  Additionally, the pace of growth in the data plane is
   outgrowing the pace of growth of the control plane.  This is
   especially visible with relatively control plane or CPU-heavy
   protocols such as NetFlow, where current sampling rates are simply
   not going to be sustainable long-term, primarily due to on-box
   control plane hardware limitations.  Being able to capture a
   filtered, sampled collection of actual packets throughout the network
   is very valuable for understanding how the network is being used, to
   provide hard data to justify network topology augments and/or
   technology changes.

   This proposal addresses this use case by: 1) making the data
   replication mechanism as simple as possible, reducing the need for
   high levels of complexity in the data plane; 2) decoupling the
   sampling/collection of packets from the analysis, which in turn
   allows for the analysis to be performed on distributed, horizontally-
   scalable platforms rather than being constrained to the compute and
   storage capabilities of a local network element.







Gray & Wobker            Expires 4 October 2020                 [Page 5]

Internet-Draft          Sampled Traffic Streaming             April 2020


2.2.  Use Case 2: Network Behavior Verification

   This use case focuses on the potential ability to have the ASICs
   stream discarded packets, along with an indication as to the reason
   for the drop.  With fields denoting the reason for dropped packets
   such as QoS policies, buffer contention, ACLs, etc., such discarded
   traffic could be streamed (potentially at a sampling rate of 1:1,
   i.e. every packet) off-box for analysis to determine if the observed
   behavior was expected, or trigger alerts that QoS policies may be
   having adverse effects on the network.  The ability to include the
   packet payload provides additional context, allowing examination of
   the platform behavior and affected policies.

   This proposal addresses this use case by allowing samplers which have
   such capabilities to communicate to the receiver: 1) drop
   codes(reasons) that are known, 2) the semantics of those codes, and
   3) the specific bit formats for the receiver to use when decoding.

2.3.  Use Case 3: Standardization

   Standardizing the way these data streams are formed and communicated
   between the Replicators, Clients, and Receivers in a fashion that
   allows vendors flexibility in what work the ASIC has to do to support
   sampled streaming (by allowing communicating of an extremely dynamic
   header in a manner than control planes can manage) allows systems to
   be used between all platforms in an interoperable fashion.  The
   alternative is to build independent systems for each packet
   replication solution that may end up being developed, resulting in
   much higher costs for an overall solution.

   This proposal addresses this use case by allowing the sampled packet
   header to provide varying metadata fields, without mandating specific
   positions or widths.  This arrangement of fields and their format is
   a function of the Replicator, and information about how to handle
   this data is exchanged between the Replicator, Client, and Receiver
   at the initialization of the session.  The motivation for such
   latitude in encoding and sizing is quite intentional, as it permits
   widely varying capabilities within the Replicators.

2.4.  Use Case 4: Security Automation

   An automated security platform can utilize this proposal to set up a
   "normal security analysis" stream at a very low sampling rate (for
   example, 1 in 20,000) for constant monitoring at various points
   throughout the network.  Upon seeing something it deems
   'interesting', or by manual input, it can add in an additional,
   targeted, stream, at a very high sampling rate (potentially 1:1) for
   detailed analysis and mitigation efforts.



Gray & Wobker            Expires 4 October 2020                 [Page 6]

Internet-Draft          Sampled Traffic Streaming             April 2020


   Examples of past incidents where this may have been useful are the
   NTP MONLIST attacks, DNS attacks, or DDoS attacks (although 1:1 would
   most likely not be used in a DDoS case, unless performing the initial
   data collection).

   The security platform could potentially then use the collected
   packets to generate an auto-mitigation plan based on heuristics
   (i.e., 99% of this sudden burst of traffic has something in common,
   deploy mitigation targeting that.)

3.  Stream Setup

   The configuration and setup between the Client and the Replicator
   utilizes the YANG model as listed in Appendix B and any supported
   configuration method (NETCONF, RESTCONF, gRPC, etc.).  The tree
   output of this model, as provided in Appendix A is provided as an aid
   to understanding the interactions and tree structure as described in
   this document.

3.1.  Client queries Replicator for Points

   A Client MUST first request from the Replicator the available
   configurations via the 'points' branch, which provides the following
   information:

   *  'name' - The name of the Point.  This serves as a key, and SHOULD
      NOT be interpreted by software as anything other than a possibly-
      human-readable uniquely identifying value.  A Replicator MAY
      choose to use an internal path, an encoded address, or any other
      value of its choosing.

   *  'interfaces' - The physical interfaces this Point is servicing.  A
      Replicator MAY offer the same interfaces under different Points,
      with a different set of options.  A Replicator MAY not offer a
      Point for every interface available on the system.

   *  'filters' - What filters can be applied (for example, against
      certain IP fields, against parts of the frame, etc.).  A
      Replicator MAY not be able to honor every combination of filters
      submitted in a request, or MAY not offer any filtering capability
      at all.  A Replicator MAY only be able to support a limited number
      of filters, which MAY be returned in in the 'max-filters' branch.

   *  'min-ratio' and 'max-ratio' - Minimum and maximum sampling rates
      possible at this point.  These are provided as a number N,
      denoting one sample will be returned for every N.  A Replicator
      MAY not be able to offer a 'min-ratio' of 1 (i.e. every packet).




Gray & Wobker            Expires 4 October 2020                 [Page 7]

Internet-Draft          Sampled Traffic Streaming             April 2020


   *  'samplers' - A list of any current samplers already active on this
      Point as requested by this Client, and the branch manipulated in
      the next section.  A Replicator SHOULD NOT inform a Client about
      the sampling sessions from other Clients.

   *  Optionally, the maximum frame length the Point can replicate into
      the sample in 'max-frame-length-copy'.

   *  Optionally, the maximum offset into a frame the Point can inspect
      in 'max-frame-depth-inspect'.

   *  Optionally, the maximum number of samplers that this Point can
      accommodate in 'max-samplers'.  A Client MUST still check for
      success, as highly complex filters may reduce the amount of
      replication the Point can do from this stated maximum.

3.2.  Client submits a request to the Replicator

   The Client then can request one or more streams to be set up on the
   Replicator, taking into consideration the provided information.  This
   is performed by sending a request via adding an entry to the
   'samplers' list in the 'points' branch and filling in the parameters
   listed below:

   *  'name' MUST be unique in the list, and MAY be any valid string
      value up to 255 characters.  The Replicator MUST isolate
      namespaces between Clients (as one Client SHOULD NOT be able to
      see other Clients' entries).

   *  'destination' sets the transport mechanism and Receiver address.
      It should be noted that the Client and Receiver MAY be separate
      devices.  The mechanism of exchanging information between the
      Client and Receiver about this setup process is outside the scope
      of this document.  At present, the only supported transport
      mechanism is a UDP tunnel, as detailed below in Section 4.

   *  'client-heartbeat' MUST be set to 0.

   *  The desired sampling rate ('ratio'), along with what degree of
      variance the Client can accept ('min-ratio' and 'max-ratio').  For
      example, the client may request a 1 in 2000 rate, but specify a
      range in the variance of 1900-2100.  A proposal may come back with
      the sampling rate offered of 1 in 2048, due to restrictions on the
      Replicator.

   *  Optionally, one, or more filters in the 'filters' container, as
      seen in the 'filter-type' typedef in the Yang model.  Generally, a




Gray & Wobker            Expires 4 October 2020                 [Page 8]

Internet-Draft          Sampled Traffic Streaming             April 2020


      Client would filter at least on a specific interface and
      direction, but many other filter options are possible.

   When the client is done with its configuration, it MUST set 'status'
   to the 'client-request-complete' value, and the 'request' branch MUST
   be read-only from this point forward.

3.2.1.  Filtering Details

   The filtering discussed above is designed to be as flexible as the
   Replicator can realistically support.  There are a few cases worth
   discussing in detail, which are covered here.

3.2.1.1.  Interfaces

   All of the use cases focus on filtering to specific interface(s) to
   filter on.  A Replicator MAY, at its discretion, offer some or all of
   its possible physical interfaces, offer logical interfaces (i.e.
   routed interfaces on a port or VLAN, or subscriber interfaces), or
   LAG interfaces.  LAGs may be especially tricky, as the member ports
   of the LAG may span line cards of different capturing capabilities.
   Replicators SHOULD make an attempt to offer LAGs if all ports are of
   identical capability, and MAY offer them in the case where they are
   not, with a lowest-common capability set.  Clients SHOULD NOT expect
   LAG functionality to be present, and SHOULD be prepared to set up
   separate sessions on each of the individual member ports if the
   Replicator does not offer the LAG, or offers it with an insufficient
   set.

3.3.  Replicator offers Proposals

   Upon receiving the 'status' change to 'client-request-complete', the
   Replicator updates the 'proposals' branch.  This branch details zero,
   one, or more ways the Replicator can fulfill the sampling request.
   While generally there will only be zero or one proposals, a
   Replicator MAY offer more.  For example, matching a sampling rate
   exactly would result in performance loss but a 'close enough' option
   can be offered that does not, or offers of what headers can be
   captured in the resulting stream.  Each proposal includes a unique ID
   number, allowing the Client to select one, as detailed below.

   If the Replicator is unable to provide any Proposals, the 'proposals'
   list MUST be empty, a human-readable error message MAY be returned in
   the 'proposal-error' field, then the 'status' field MUST be set to
   'replicator-proposal-error'.

   If the Replicator was able to provide Proposals, it MUST set the
   'status' field to 'replicator-proposals-available' when it is



Gray & Wobker            Expires 4 October 2020                 [Page 9]

Internet-Draft          Sampled Traffic Streaming             April 2020


   finished, and the 'proposals' branch MUST be read-only until the
   Client finishes the Proposal selection step below.

   Part of each Proposal is a 'stream-format' branch, which informs the
   Client of the packet format the Receiver will be receiving.  This
   format completely defines the entirety of the resulting data flow
   format besides the outer UDP wrapper - there is no normative format.
   A couple non-normative examples of what may result are provided in
   Section 4.

   To adequately addresses the use cases stated above, a Replicator
   SHOULD support as a minimum set of capabilities:

   *  An action field that denotes a pass or drop (ideally with drop
      reason)

   *  Capturing at least 128 octets of payload

   *  The original frame length

   *  Sampling rates up to 1:1 (i.e. every packet is replicated), and
      down to 1:20000 or smaller.

   *  Having different sampling sessions having different sampling rates
      (to allow a "general" session to be watching a broad selection of
      traffic, and more specific sessions targeting exact flows or
      situations)

   *  At least two sessions per physical interface

   *  Filtering on ingress port

   *  Filtering on action

   *  Filtering on direction of traffic

3.4.  Client selects a Proposal

   Upon either a notification or detection that the 'status' field has
   been updated, the Client then may then set the 'proposal-selected'
   entry to the value of the desired ID offered in 'proposals', and then
   set 'status' to 'client-proposal selected'.  At this point, the
   Replicator:

   *  MAY remove unnecessary branches in the 'proposals' list, but MUST
      retain the selected one.





Gray & Wobker            Expires 4 October 2020                [Page 10]

Internet-Draft          Sampled Traffic Streaming             April 2020


   *  MUST either install the requested sampling stream if possible,
      then MUST set 'status' to 'replicator-install-success'.  If it
      cannot, it MAY set 'install-error' to a human-readable error
      message and MUST set 'status' to 'replicator-install-error'.

   *  If the Proposal selected includes any of the 'dropped-' action-
      types as a filter, or does not specify an action-type filter at
      all, a Replicator MUST install the requested sampling before any
      filtering actions occur to the stream, as the sampling session is
      explicitly interested in pre-drop traffic.

   *  If the Proposal selected does not include any of the 'dropped-'
      action-types as a filter, a Replicator MUST install the requested
      sampling after any filtering actions occur to the stream, to
      ensure the sampling ratio remains correct.

3.5.  Ending sampling and cleanup

   When a Client is finished with a sampling session, it deletes its
   entry in the 'samplers' tree to terminate a sampling session.
   Otherwise, a Client MUST refresh its entry by setting 'client-
   heartbeat' to 0 at least every 3600 seconds.  The 'client-heartbeat'
   is then incremented by the Replicator.  If 'client-heartbeat' exceeds
   3600, the Replicator SHOULD consider the sampling configuration and
   any associated sampling session no longer necessary, terminate the
   sampling, and delete the entry.  A Replicator MAY allow configuration
   to increase this timeout.

4.  Data Stream Format

   After the stream setup has been completed, the Receiver MUST use the
   stream-format data that the Replicator has calculated in its
   proposal.  The Client and Receiver MUST NOT assume that the stream-
   format data is consistent between one stream setup and any other
   (there may be different versions of ASICs, different capabilities,
   different versions of operating systems, or different filters may
   yield a different format), or that the payload is always at the end
   (it could appear at the beginning or in the middle, and sufficient
   data is provided by the other fields to extract the data correctly).
   The stream-format data provides the Client with what information is
   provided at what location in the resulting packet.  The Replicator
   MUST follow the expectation that is provided in these fields.

   There is one captured packet per encapsulated packet, and thus the
   outer encapsulation length can be used to deduce the length of one
   variable-length field (designated by a field length of 0) contained
   within.  If there is more than one variable-length field, a matching
   "-size"; field type MUST be provided for all but one of the variable-



Gray & Wobker            Expires 4 October 2020                [Page 11]

Internet-Draft          Sampled Traffic Streaming             April 2020


   length fields (as a single variable length can be deduced from the
   wrapper length).

   This means there is no normative packet format or data layout - a
   large point of this specification is to allow that packet format to
   be negotiated and decided between the Client and Replicator, with the
   information passed back via the stream-format data.

   One example of what the resulting packet may look like (but not a
   normative listing of what it is - the actual format can be any
   combination of fields, of any size, in any order), the data inside
   the resulting data stream after the UDP tunnel header may look like
   the following:

   Example 1: Packet layout


    0                   1                   2                   3
    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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Incoming Port | Timestamp                                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Act|          Frame Length           |       Internal Data 1   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Payload                             |
   |                             ...                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


                                  Figure 2

   This non-normative example may be associated with a stream-format as
   per the following table:

   +-----------+-------+------------------------+----------------------+
   | Field     | Field | Field Type             | Field Type-Data      |
   | Name      | Size  |                        |                      |
   +===========+=======+========================+======================+
   | Incoming  | 8     | port-ingress           | A listing of         |
   | port      |       |                        | values that may be   |
   |           |       |                        | seen in this         |
   |           |       |                        | field, mapped to     |
   |           |       |                        | interface-refs       |
   |           |       |                        | from [RFC8343].      |
   +-----------+-------+------------------------+----------------------+
   | Timestamp | 24    | timestamp-nsec-ingress | Two 32-bit numbers   |
   |           |       |                        | giving when the      |
   |           |       |                        | "0" of this field    |



Gray & Wobker            Expires 4 October 2020                [Page 12]

Internet-Draft          Sampled Traffic Streaming             April 2020


   |           |       |                        | is based off of,     |
   |           |       |                        | using the PTP        |
   |           |       |                        | Truncated            |
   |           |       |                        | Timestamp format.    |
   +-----------+-------+------------------------+----------------------+
   | Act       | 2     | action                 | A listing of         |
   |           |       |                        | values that may be   |
   |           |       |                        | seen in this         |
   |           |       |                        | field, mapped to     |
   |           |       |                        | action types         |
   |           |       |                        | (accepted,           |
   |           |       |                        | dropped, etc.)       |
   +-----------+-------+------------------------+----------------------+
   | Frame     | 17    | frame-length-ingress   | Note that this       |
   | Length    |       |                        | denotes the          |
   |           |       |                        | original frame       |
   |           |       |                        | length - the         |
   |           |       |                        | payload field MAY    |
   |           |       |                        | not include the      |
   |           |       |                        | entire payload.      |
   +-----------+-------+------------------------+----------------------+
   | Internal  | 13    | padding                | Note that this may   |
   | Data 1    |       |                        | be ASIC-internal-    |
   |           |       |                        | only data, or some   |
   |           |       |                        | other information    |
   |           |       |                        | that would be        |
   |           |       |                        | expensive to prune   |
   |           |       |                        | out.  'padding'      |
   |           |       |                        | fields MUST have     |
   |           |       |                        | all content          |
   |           |       |                        | ignored.             |
   +-----------+-------+------------------------+----------------------+
   | Payload   | 0     | frame-payload-ingress  |                      |
   +-----------+-------+------------------------+----------------------+

                   Table 1: Example 1: Stream-format data

   Another non-normative example, which is similar to the
   [I-D.tuexen-opsawg-pcapng] enhanced packet block (EPB) format (and
   thus, this Replicator may in fact be a server offering a tcpdump-
   based backend using this frontend):










Gray & Wobker            Expires 4 October 2020                [Page 13]

Internet-Draft          Sampled Traffic Streaming             April 2020


     +-----------+-------+--------------------+---------------------+
     | Field     | Field | Field Type         | Field Type-Data     |
     | Name      | Size  |                    |                     |
     +===========+=======+====================+=====================+
     | Interface | 32    | port               | A listing of values |
     | ID        |       |                    | that may be seen in |
     |           |       |                    | this field, mapped  |
     |           |       |                    | to interface-refs   |
     |           |       |                    | from [RFC8343].     |
     +-----------+-------+--------------------+---------------------+
     | Timestamp | 64    | timestamp-msec     | Two 32-bit numbers  |
     |           |       |                    | giving when the "0" |
     |           |       |                    | of this field is    |
     |           |       |                    | based off of, using |
     |           |       |                    | the PTP Truncated   |
     |           |       |                    | Timestamp format.   |
     +-----------+-------+--------------------+---------------------+
     | Captured  | 32    | frame-payload-size | Note: This allows   |
     | Packet    |       |                    | us to have the      |
     | Length    |       |                    | Options field as    |
     |           |       |                    | our real variable   |
     |           |       |                    | length field.       |
     +-----------+-------+--------------------+---------------------+
     | Original  | 32    | frame-length       |                     |
     | Packet    |       |                    |                     |
     | Length    |       |                    |                     |
     +-----------+-------+--------------------+---------------------+
     | Packet    | 0     | frame-payload      |                     |
     | Data      |       |                    |                     |
     +-----------+-------+--------------------+---------------------+
     | Options   | 0     | padding            |                     |
     +-----------+-------+--------------------+---------------------+

                Table 2: Packet-format response example 2

   To restate the prior note, the above is purely an example of what the
   format could be - the actual format used is negotiated between the
   Client and Replicator, and can have practically any layout, with any
   additional fields.

   A Client SHOULD take efforts to be notified when a change has
   occurred on the Replicator (e.g., port or line card changes, device
   reboot, etc.), and re-verify and re-apply as needed its sampled
   streaming configurations when such a change is detected.







Gray & Wobker            Expires 4 October 2020                [Page 14]

Internet-Draft          Sampled Traffic Streaming             April 2020


5.  IANA Considerations

   This document defines a new UDP port number, entitled "Sampled
   Streaming", and assigns a value of TBD1 from the Service Name and
   Transport Protocol Port Number Registry
   https://www.iana.org/assignments/service-names-port-numbers/service-
   names-port-numbers.xhtml:

                       +------+-------------------+
                       | Tag  | Description       |
                       +======+===================+
                       | TBD1 | Sampled Streaming |
                       +------+-------------------+

                                 Table 3

   This document requests registration of a URI in the "IETF XML
   Registry" RFC 3688 [RFC3688].  Following the format in RFC 3688, the
   following registration is suggested:


   URI: urn:ietf:params:xml:ns:yang:ietf-sampled-streaming
   Registrant Contact: The IESG.
   XML: N/A, the requested URI is an XML namespace.

   This document registers a YANG module in the "YANG Module Names"
   registry RFC 6020 [RFC6020]:


   name: ietf-sampled-streaming
   namespace: urn:ietf:params:xml:ns:yang:ietf-sampled-streaming
   prefix: ss
   reference: This document

6.  Security Considerations

   Vendors and deployments must take into consideration that this
   functionality allows a mirroring of traffic, with configurable
   destinations and filters.  Similar functionality already exists in
   various remote packet mirroring systems, and similar considerations
   should be taken.  Filters utilizing the source port of TBD1 SHOULD be
   applied at the edges of a provider's network to provide an additional
   layer of security.

   A Replicator SHOULD ensure that Clients can only see their own
   entries in the 'samplers', and MUST ensure that once a Client has
   created an entry in the samplers list, only that same Client may re-
   query or make changes to it.



Gray & Wobker            Expires 4 October 2020                [Page 15]

Internet-Draft          Sampled Traffic Streaming             April 2020


7.  Acknowledgments

   The authors would like to thank Joe Clarke, Marek Hajduczenia, Brian
   Harber, Paolo Lucente, Jim Rampley, and Dmytro Shytyi for their
   reviews and providing helpful suggestions and feedback of this draft.

8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC5476]  Claise, B., Ed., Johnson, A., and J. Quittek, "Packet
              Sampling (PSAMP) Protocol Specifications", RFC 5476,
              DOI 10.17487/RFC5476, March 2009,
              <https://www.rfc-editor.org/info/rfc5476>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [RFC6728]  Muenz, G., Claise, B., and P. Aitken, "Configuration Data
              Model for the IP Flow Information Export (IPFIX) and
              Packet Sampling (PSAMP) Protocols", RFC 6728,
              DOI 10.17487/RFC6728, October 2012,
              <https://www.rfc-editor.org/info/rfc6728>.

   [RFC8343]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
              <https://www.rfc-editor.org/info/rfc8343>.

8.2.  Informative References

   [I-D.tuexen-opsawg-pcapng]
              Tuexen, M., Risso, F., Bongertz, J., Combs, G., Harris,
              G., and M. Richardson, "PCAP Next Generation (pcapng)
              Capture File Format", Work in Progress, Internet-Draft,
              draft-tuexen-opsawg-pcapng-01, 27 March 2020,
              <http://www.ietf.org/internet-drafts/draft-tuexen-opsawg-
              pcapng-01.txt>.



Gray & Wobker            Expires 4 October 2020                [Page 16]

Internet-Draft          Sampled Traffic Streaming             April 2020


Appendix A.  Yang Model Tree Reference

   module: ietf-sampled-streaming
     +--rw points* [name]
        +--rw name                       psamp:nameType
        +--rw observationPoints* [name]
        |  +--rw name                   psamp:nameType
        |  +--ro observationPointId?    uint32
        |  +--rw observationDomainId    uint32
        |  +--rw ifName*                ifNameType
        |  +--rw ifIndex*               uint32
        |  +--rw entPhysicalName*       string
        |  +--rw entPhysicalIndex*      uint32
        |  +--rw direction?             direction
        +--rw selectors* [name]
        |  +--rw name                         psamp:nameType
        |  +--rw (Method)
        |  |  +--:(selectAll)
        |  |  |  +--rw selectAll?             empty
        |  |  +--:(sampCountBased)
        |  |  |  +--rw sampCountBased {psampSampCountBased}?
        |  |  |     +--rw packetInterval    uint32
        |  |  |     +--rw packetSpace       uint32
        |  |  +--:(sampTimeBased)
        |  |  |  +--rw sampTimeBased {psampSampTimeBased}?
        |  |  |     +--rw timeInterval    uint32
        |  |  |     +--rw timeSpace       uint32
        |  |  +--:(sampRandOutOfN)
        |  |  |  +--rw sampRandOutOfN {psampSampRandOutOfN}?
        |  |  |     +--rw size          uint32
        |  |  |     +--rw population    uint32
        |  |  +--:(sampUniProb)
        |  |  |  +--rw sampUniProb {psampSampUniProb}?
        |  |  |     +--rw probability    decimal64
        |  |  +--:(filterMatch)
        |  |  |  +--rw filterMatch {psampFilterMatch}?
        |  |  |     +--rw (nameOrId)
        |  |  |     |  +--:(ieName)
        |  |  |     |  |  +--rw ieName?         ieNameType
        |  |  |     |  +--:(ieId)
        |  |  |     |     +--rw ieId?           ieIdType
        |  |  |     +--rw ieEnterpriseNumber?   uint32
        |  |  |     +--rw value                 string
        |  |  +--:(filterHash)
        |  |     +--rw filterHash {psampFilterHash}?
        |  |        +--rw hashFunction?       identityref
        |  |        +--rw initializerValue?   uint64
        |  |        +--rw ipPayloadOffset?    uint64



Gray & Wobker            Expires 4 October 2020                [Page 17]

Internet-Draft          Sampled Traffic Streaming             April 2020


        |  |        +--rw ipPayloadSize?      uint64
        |  |        +--rw digestOutput?       boolean
        |  |        +--ro outputRangeMin?     uint64
        |  |        +--ro outputRangeMax?     uint64
        |  |        +--rw selectedRange* [name]
        |  |           +--rw name    nameType
        |  |           +--rw min?    uint64
        |  |           +--rw max?    uint64
        |  +--ro packetsObserved?             yang:counter64
        |  +--ro packetsDropped?              yang:counter64
        |  +--ro selectorDiscontinuityTime?   yang:date-and-time
        +--ro filters* []
        |  +--ro filter    filter-type
        +--ro max-samplers?              uint32
        +--ro max-filters?               uint32
        +--ro max-frame-length-copy?     uint16
        +--ro max-frame-depth-inspect?   uint16
        +--rw samplers* [name]
           +--rw name                 string
           +--rw status               status-type
           +--rw client-heartbeat     uint32
           +--rw destination
           |  +--rw type              destination-type
           |  +--rw udp-parameters
           |     +--rw destination-ip      inet:ip-address-no-zone
           |     +--rw destination-port    inet:port-number
           +--rw request
           |  +--rw filters
           |  |  +--rw name?            string
           |  |  +--rw interfaces* [int]
           |  |  |  +--rw int    if:interface-ref
           |  |  +--rw actions* [action]
           |  |  |  +--rw action    action-type
           |  |  +--rw direction?       psamp:direction
           |  |  +--rw type             filter-type
           |  |  +--rw ipv4-address?    inet:ipv4-address-no-zone
           |  |  +--rw ipv6-address?    inet:ipv6-address-no-zone
           |  |  +--rw version?         inet:ip-version
           |  |  +--rw frame-payload
           |  |  |  +--rw offset?   uint16
           |  |  |  +--rw match?    binary
           |  |  +--rw frame-length?    uint16
           |  +--rw selector
           |  |  +--rw (Method)
           |  |  |  +--:(selectAll)
           |  |  |  |  +--rw selectAll?             empty
           |  |  |  +--:(sampCountBased)
           |  |  |  |  +--rw sampCountBased {psampSampCountBased}?



Gray & Wobker            Expires 4 October 2020                [Page 18]

Internet-Draft          Sampled Traffic Streaming             April 2020


           |  |  |  |     +--rw packetInterval    uint32
           |  |  |  |     +--rw packetSpace       uint32
           |  |  |  +--:(sampTimeBased)
           |  |  |  |  +--rw sampTimeBased {psampSampTimeBased}?
           |  |  |  |     +--rw timeInterval    uint32
           |  |  |  |     +--rw timeSpace       uint32
           |  |  |  +--:(sampRandOutOfN)
           |  |  |  |  +--rw sampRandOutOfN {psampSampRandOutOfN}?
           |  |  |  |     +--rw size          uint32
           |  |  |  |     +--rw population    uint32
           |  |  |  +--:(sampUniProb)
           |  |  |  |  +--rw sampUniProb {psampSampUniProb}?
           |  |  |  |     +--rw probability    decimal64
           |  |  |  +--:(filterMatch)
           |  |  |  |  +--rw filterMatch {psampFilterMatch}?
           |  |  |  |     +--rw (nameOrId)
           |  |  |  |     |  +--:(ieName)
           |  |  |  |     |  |  +--rw ieName?         ieNameType
           |  |  |  |     |  +--:(ieId)
           |  |  |  |     |     +--rw ieId?           ieIdType
           |  |  |  |     +--rw ieEnterpriseNumber?   uint32
           |  |  |  |     +--rw value                 string
           |  |  |  +--:(filterHash)
           |  |  |     +--rw filterHash {psampFilterHash}?
           |  |  |        +--rw hashFunction?       identityref
           |  |  |        +--rw initializerValue?   uint64
           |  |  |        +--rw ipPayloadOffset?    uint64
           |  |  |        +--rw ipPayloadSize?      uint64
           |  |  |        +--rw digestOutput?       boolean
           |  |  |        +--ro outputRangeMin?     uint64
           |  |  |        +--ro outputRangeMax?     uint64
           |  |  |        +--rw selectedRange* [name]
           |  |  |           +--rw name    nameType
           |  |  |           +--rw min?    uint64
           |  |  |           +--rw max?    uint64
           |  |  +--ro packetsObserved?             yang:counter64
           |  |  +--ro packetsDropped?              yang:counter64
           |  |  +--ro selectorDiscontinuityTime?   yang:date-and-time
           |  +--rw ratio        uint32
           |  +--rw min-ratio?   uint32
           |  +--rw max-ratio?   uint32
           +--ro proposals* [id]
           |  +--ro id                            uint32
           |  +--ro selector
           |  |  +--ro (Method)
           |  |  |  +--:(selectAll)
           |  |  |  |  +--ro selectAll?             empty
           |  |  |  +--:(sampCountBased)



Gray & Wobker            Expires 4 October 2020                [Page 19]

Internet-Draft          Sampled Traffic Streaming             April 2020


           |  |  |  |  +--ro sampCountBased {psampSampCountBased}?
           |  |  |  |     +--ro packetInterval    uint32
           |  |  |  |     +--ro packetSpace       uint32
           |  |  |  +--:(sampTimeBased)
           |  |  |  |  +--ro sampTimeBased {psampSampTimeBased}?
           |  |  |  |     +--ro timeInterval    uint32
           |  |  |  |     +--ro timeSpace       uint32
           |  |  |  +--:(sampRandOutOfN)
           |  |  |  |  +--ro sampRandOutOfN {psampSampRandOutOfN}?
           |  |  |  |     +--ro size          uint32
           |  |  |  |     +--ro population    uint32
           |  |  |  +--:(sampUniProb)
           |  |  |  |  +--ro sampUniProb {psampSampUniProb}?
           |  |  |  |     +--ro probability    decimal64
           |  |  |  +--:(filterMatch)
           |  |  |  |  +--ro filterMatch {psampFilterMatch}?
           |  |  |  |     +--ro (nameOrId)
           |  |  |  |     |  +--:(ieName)
           |  |  |  |     |  |  +--ro ieName?         ieNameType
           |  |  |  |     |  +--:(ieId)
           |  |  |  |     |     +--ro ieId?           ieIdType
           |  |  |  |     +--ro ieEnterpriseNumber?   uint32
           |  |  |  |     +--ro value                 string
           |  |  |  +--:(filterHash)
           |  |  |     +--ro filterHash {psampFilterHash}?
           |  |  |        +--ro hashFunction?       identityref
           |  |  |        +--ro initializerValue?   uint64
           |  |  |        +--ro ipPayloadOffset?    uint64
           |  |  |        +--ro ipPayloadSize?      uint64
           |  |  |        +--ro digestOutput?       boolean
           |  |  |        +--ro outputRangeMin?     uint64
           |  |  |        +--ro outputRangeMax?     uint64
           |  |  |        +--ro selectedRange* [name]
           |  |  |           +--ro name    nameType
           |  |  |           +--ro min?    uint64
           |  |  |           +--ro max?    uint64
           |  |  +--ro packetsObserved?             yang:counter64
           |  |  +--ro packetsDropped?              yang:counter64
           |  |  +--ro selectorDiscontinuityTime?   yang:date-and-time
           |  +--ro performance-penalty?          boolean
           |  +--ro performance-penalty-amount?   uint16
           |  +--ro stream-format
           |  |  +--ro fields* [name]
           |  |     +--ro name                  string
           |  |     +--ro size?                 uint32
           |  |     +--ro type?                 field-type
           |  |     +--ro action-mappings* [value]
           |  |     |  +--ro value      binary



Gray & Wobker            Expires 4 October 2020                [Page 20]

Internet-Draft          Sampled Traffic Streaming             April 2020


           |  |     |  +--ro meaning?   action-type
           |  |     +--ro port-mappings* [value]
           |  |     |  +--ro value    binary
           |  |     |  +--ro port?    if:interface-ref
           |  |     +--ro direction-mappings* [value]
           |  |     |  +--ro value        binary
           |  |     |  +--ro direction?   psamp:direction
           |  |     +--ro timestamp
           |  |     |  +--ro seconds?       uint32
           |  |     |  +--ro nanoseconds?   uint32
           |  |     +--ro payload-contents?     frame-headers
           |  +--ro filters* [name]
           |     +--ro name             string
           |     +--ro interfaces* [int]
           |     |  +--ro int    if:interface-ref
           |     +--ro actions* [action]
           |     |  +--ro action    action-type
           |     +--ro direction?       psamp:direction
           |     +--ro type             filter-type
           |     +--ro ipv4-address?    inet:ipv4-address-no-zone
           |     +--ro ipv6-address?    inet:ipv6-address-no-zone
           |     +--ro version?         inet:ip-version
           |     +--ro frame-payload
           |     |  +--ro offset?   uint16
           |     |  +--ro match?    binary
           |     +--ro frame-length?    uint16
           +--rw proposal-error?      string
           +--rw proposal-selected?   uint32
           +--rw install-error?       string

Appendix B.  Yang Model

   module ietf-sampled-streaming {
     namespace "urn:ietf:params:xml:ns:yang:ietf-sampled-streaming";
     prefix ss;

     import ietf-interfaces {
       prefix if;
     }
     import ietf-inet-types {
       prefix inet;
     }
     import ietf-ipfix-psamp {
       prefix psamp;
       revision-date 2012-09-05;
     }

     organization



Gray & Wobker            Expires 4 October 2020                [Page 21]

Internet-Draft          Sampled Traffic Streaming             April 2020


       "IETF Working Group";
     contact
       "Editor:    Andrew Gray
        <mailto:Andrew.Gray@charter.com>";
     description
       "This module contains a collection of YANG definitions for
        managing sampled streaming subscriptions.

        Copyright (c) 2019 IETF Trust and the persons identified as
        authors of the code.  All rights reserved.

        Redistribution and use in source and binary forms, with or
        without modification, is permitted pursuant to, and subject to
        the license terms contained in, the Simplified BSD License set
        forth in Section 4.c of the IETF Trust's Legal Provisions
        Relating to IETF Documents
        (https://trustee.ietf.org/license-info).

        This version of this YANG module is part of RFC XXXX
        (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
        for full legal notices.

        The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
        NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
        'MAY', and 'OPTIONAL' in this document are to be interpreted as
        described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
        they appear in all capitals, as shown here.";

     revision 2019-12-27 {
       description
         "Clarifications based on feedback for -03 draft.  Utilize parts
          of RFC 6728 to avoid redundancy, where possible.";
       reference
         "draft-gray-sampled-streaming-03";
     }
     revision 2019-10-22 {
       description
         "Updates based on feedback for -02 draft: Adding more forwarded
          action-types.  frame-payload changed to be explicit about
          direction.  Added -size types explicitly for frame-payload and
          padding to allow using more than one zero-length field.";
       reference
         "draft-gray-sampled-streaming-02";
     }
     revision 2019-08-06 {
       description
         "Updates based on feedback for -01 draft.";
       reference



Gray & Wobker            Expires 4 October 2020                [Page 22]

Internet-Draft          Sampled Traffic Streaming             April 2020


         "draft-gray-sampled-streaming-01";
     }
     revision 2019-06-25 {
       description
         "Initial version.";
       reference
         "draft-gray-sampled-streaming-00";
     }

     typedef filter-type {
       type enumeration {
         enum interfaces {
           description
             "List of interfaces to filter against.";
         }
         enum action {
           description
             "Filter against a list of actions that the Point took (i.e.
              only consider packets that were actually forwarded).";
         }
         enum direction {
           description
             "Direction to sample traffic in.";
         }
         enum ip-version {
           description
             "The version number in the IP header.";
         }
         enum ip-v4-srcip {
           description
             "The IPv4 header's source IPv4 address.";
         }
         enum ip-v4-dstip {
           description
             "The IPv4 header's destination IPv4 address.";
         }
         enum ip-v4-ttl {
           description
             "The IPv4 header's Time to Live.";
         }
         enum ip-v4-prot {
           description
             "The IPv4 header's protocol number.";
         }
         enum ip-v6-srcip {
           description
             "The IPv6 header's source IPv4 address.";
         }



Gray & Wobker            Expires 4 October 2020                [Page 23]

Internet-Draft          Sampled Traffic Streaming             April 2020


         enum ip-v6-dstip {
           description
             "The IPv6 header's destination IPv4 address.";
         }
         enum frame-size {
           description
             "The total size of the frame.";
         }
         enum frame-payload {
           description
             "Specific payload octets.";
         }
         enum frame-length {
           description
             "Specific frame length.";
         }
       }
       description
         "The filtering abilities available.";
     }

     typedef field-type {
       type enumeration {
         enum padding {
           description
             "Padding bits that MUST be ignored.";
         }
         enum padding-size {
           description
             "This packet's length of a variable-length padding field.";
         }
         enum port {
           description
             "An indication of the port the traffic was sampled from.";
         }
         enum direction {
           description
             "Which direction the traffic went.";
         }
         enum port-ingress {
           description
             "What port the traffic was received from (may be different
              than 'port')";
         }
         enum port-egress {
           description
             "What port the traffic is leaving on (may be different than
              'port')";



Gray & Wobker            Expires 4 October 2020                [Page 24]

Internet-Draft          Sampled Traffic Streaming             April 2020


         }
         enum timestamp-msec-ingress {
           description
             "The timestamp the packet was received at, in integer
              milliseconds.  The epoch of this number is provided in the
              timestamp container of the returned field information.";
         }
         enum timestamp-usec-ingress {
           description
             "The timestamp the packet was received at, in integer
              microseconds.  The epoch of this number is provided in the
              timestamp container of the returned field information.";
         }
         enum timestamp-nsec-ingress {
           description
             "The timestamp the packet was received at, in integer
              nanoseconds.  The epoch of this number is provided in the
              timestamp container of the returned field information.";
         }
         enum timestamp-msec-egress {
           description
             "The timestamp the packet left the point at, in integer
              milliseconds.  The epoch of this number is provided in the
              timestamp container of the returned field information.";
         }
         enum timestamp-usec-egress {
           description
             "The timestamp the packet left the point at, in integer
              microseconds.  The epoch of this number is provided in the
              timestamp container of the returned field information.";
         }
         enum timestamp-nsec-egress {
           description
             "The timestamp the packet left the point at, in integer
              nanoseconds.  The epoch of this number is provided in the
              timestamp container of the returned field information.";
         }
         enum frame-length {
           description
             "The generic frame length.  Note that due to chipset
              capabilities, this MAY not be the same as the captured
              packet length.";
         }
         enum frame-length-ingress {
           description
             "The frame length as received by the point.  Note that due
              to chipset capabilities, this MAY not be the same as the
              captured packet length.";



Gray & Wobker            Expires 4 October 2020                [Page 25]

Internet-Draft          Sampled Traffic Streaming             April 2020


         }
         enum frame-length-egress {
           description
             "The frame length after local processing, as it leaves the
              point.  Note that due to chipset capabilities, this MAY
              not be the same as the captured packet length.";
         }
         enum frame-payload-size {
           description
             "The length of the payload that has actually been copied
              into this stream.";
         }
         enum frame-payload-ingress {
           description
             "The payload of the frame, as received the point.";
         }
         enum frame-payload-egress {
           description
             "The payload of the frame, as it leaves the point.";
         }
         enum action {
           description
             "The action that was taken on this frame.  Values are
              mapped as according to action-type.";
         }
       }
       description
         "Types of data included in the data stream provided back to
          the receiver.  Note that all fields MAY not be provided.";
     }

     typedef action-type {
       type enumeration {
         enum forwarded {
           description
             "Generically forwarded normally through the system.  A more
              specific action type code SHOULD be used.";
         }
         enum forwarded-label-change {
           description
             "Forwarded, with a generic MPLS label change having
              occurred.";
         }
         enum forwarded-label-swap {
           description
             "Forwarded, with a MPLS label swap.";
         }
         enum forwarded-label-pop {



Gray & Wobker            Expires 4 October 2020                [Page 26]

Internet-Draft          Sampled Traffic Streaming             April 2020


           description
             "Forwarded, with a MPLS label pop.";
         }
         enum forwarded-label-push {
           description
             "Forwarded, with a MPLS label push.";
         }
         enum forwarded-cpu-punt {
           description
             "Forwarded after a CPU punt.";
         }
         enum forwarded-tunnel {
           description
             "Forwarded with additional outer wrapper for tunneling.";
         }
         enum forwarded-tunnel-frr {
           description
             "Forwarded with additional outer wrapper due to fast
              reroute.";
         }
         enum dropped {
           description
             "Generically dropped.  A more specific action type code
              SHOULD be used.";
         }
         enum dropped-rate-limit {
           description
             "Dropped due to a rate limiter applied.";
         }
         enum dropped-buffer {
           description
             "Dropped due to no buffer space.";
         }
         enum dropped-security {
           description
             "Dropped due to a security policy.";
         }
         enum dropped-error {
           description
             "Dropped due to the frame being in error.";
         }
         enum dropped-cpu-punt {
           description
             "Dropped after a CPU punt.";
         }
         enum passed-to-cpu {
           description
             "Passed on to the CPU, but what the CPU did with it is



Gray & Wobker            Expires 4 October 2020                [Page 27]

Internet-Draft          Sampled Traffic Streaming             April 2020


              unknown.";
         }
       }
       description
         "Possible actions taken on a packet.";
     }

     typedef destination-type {
       type enumeration {
         enum udp {
           description
             "Sent with a UDP header.";
         }
       }
       description
         "Different possible destination types.";
     }

     typedef status-type {
       type enumeration {
         enum client-request-complete {
           description
             "The Client has completed its request setup.";
         }
         enum replicator-proposals-available {
           description
             "The Replicator has finished processing the request, and
              has proposals available in the 'proposals' branch.";
         }
         enum replicator-proposal-error {
           description
             "The Replicator encountered an error attempting to come up
              with a proposal.  'proposal-error' MAY contain an
              explanation.";
         }
         enum client-proposal-selected {
           description
             "The Client has updated 'proposal-selected' and is ready
              for the Replicator to install the requested sampling.";
         }
         enum replicator-install-success {
           description
             "The Replicator has successfully activated the sampling,
              and it is operating.";
         }
         enum replicator-install-error {
           description
             "The Replicator encountered an error installing the



Gray & Wobker            Expires 4 October 2020                [Page 28]

Internet-Draft          Sampled Traffic Streaming             April 2020


              sampling. 'install-error' MAY contain an explanation.";
         }
       }
       description
         "The status of a sampler entry.";
     }

     typedef frame-headers {
       type bits {
         bit eth-l1-preamble {
           position 0;
           description
             "Will include the Ethernet preamble.";
         }
         bit eth-l1-sof {
           position 1;
           description
             "Will include the Ethernet start of frame
              delimiter";
         }
         bit eth-l2-dmac {
           position 2;
           description
             "Will include the outer Ethernet destination MAC.";
         }
         bit eth-l2-smac {
           position 3;
           description
             "Will include the outer Ethernet source MAC.";
         }
         bit eth-l2-vlan {
           position 4;
           description
             "Will include any 802.1Q-2018 VLAN tags.";
         }
         bit eth-l2-type {
           position 5;
           description
             "Will include the Ethertype or size.";
         }
         bit eth-l2-fcs {
           position 6;
           description
             "Will include the Frame Check Sequence after the
              payload.";
         }
         bit eth-l1-ipg {
           position 7;



Gray & Wobker            Expires 4 October 2020                [Page 29]

Internet-Draft          Sampled Traffic Streaming             April 2020


           description
             "Will include the inter-packet gap.  Be aware that
              different Ethernet speeds may have different lengths.";
         }
         bit mpls-tags {
           position 8;
           description
             "Will include MPLS tags.";
         }
       }
       description
         "Listing of fields to be provided in a frame capture.";
     }

     grouping filters {
       description
         "Filter definition.  Multiple filters are ANDed.";
       leaf name {
         type string {
           length "1..255";
         }
         description
           "A name for this filter.";
       }
       list interfaces {
         when "../type = 'interfaces'";
         key "int";
         description
           "Filter down to only this list of interfaces.";
         leaf int {
           type if:interface-ref;
           description
             "A specific interface to filter against.";
         }
       }
       list actions {
         when "../type = 'action'";
         key "action";
         description
           "Filter down to only this list of actions.";
         leaf action {
           type action-type;
           description
             "One specific action code.";
         }
       }
       leaf direction {
         when "../type = 'direction'";



Gray & Wobker            Expires 4 October 2020                [Page 30]

Internet-Draft          Sampled Traffic Streaming             April 2020


         type psamp:direction;
         description
           "Which direction(s) to sample traffic in.";
       }
       leaf type {
         type filter-type;
         mandatory true;
         description
           "The type of filter associated.";
       }
       leaf ipv4-address {
         when "../type = 'ip-v4-srcip' | ../type = 'ip-v4-dstip'";
         type inet:ipv4-address-no-zone;
         description
           "The IPv4 address to filter on.";
       }
       leaf ipv6-address {
         when "../type = 'ip-v6-srcip' | ../type = 'ip-v6-dstip'";
         type inet:ipv6-address-no-zone;
         description
           "The IPv6 address to filter on.";
       }
       leaf version {
         when "../type = 'ip-version'";
         type inet:ip-version;
         description
           "The value of the IP version number to match on.";
       }
       container frame-payload {
         when "../type = 'frame-payload'";
         description
           "Frame payload fragment to match on.";
         leaf offset {
           type uint16;
           description
             "Offset in octets from the start of the frame to begin the
              match on.";
         }
         leaf match {
           type binary;
           description
             "The bytes to match on.";
         }
       }
       leaf frame-length {
         when "../type = 'frame-length'";
         type uint16;
         description



Gray & Wobker            Expires 4 October 2020                [Page 31]

Internet-Draft          Sampled Traffic Streaming             April 2020


           "Frame length to match on.";
       }
     }

     grouping stream-format {
       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.";
       list fields {
         key "name";
         description
           "The listing of the fields that will be encapsulated and sent
            to the receiver.";
         leaf name {
           type string {
             length "1..255";
           }
           description
             "Human readable name of what this field contains.";
         }
         leaf size {
           type uint32 {
             range "0..524280";
           }
           description
             "The size of this field, in bits.  The value of '0' denotes
              a variable-sized field.";
         }
         leaf type {
           type field-type;
           description
             "The type of this data.";
         }
         list action-mappings {
           when "../type='action'";
           key "value";
           description
             "The mapping of values to action-type codes, valid for
              type=action.";
           leaf value {
             type binary;
             description
               "The value that will appear in the header.";
           }
           leaf meaning {
             type action-type;



Gray & Wobker            Expires 4 October 2020                [Page 32]

Internet-Draft          Sampled Traffic Streaming             April 2020


             description
               "What this value indicates.";
           }
         }
         list port-mappings {
           when "../type='ingress-port' | ../type='egress-port'";
           key "value";
           description
             "The mapping of values to interfaces, valid for
              type=ingress-port or type=egress-port";
           leaf value {
             type binary;
             description
               "The value that will appear in the header.";
           }
           leaf port {
             type if:interface-ref;
             description
               "The port the value maps to.";
           }
         }
         list direction-mappings {
           when "../type='direction'";
           key "value";
           description
             "The mapping of values to direction codes, valid for
              type=direction.";
           leaf value {
             type binary;
             description
               "The value that will appear in the header.";
           }
           leaf direction {
             type psamp:direction;
             description
               "The direction the traffic in respect to the port.  The
                value 'both' MUST NOT be used here.";
           }
         }
         container timestamp {
           when "../type='timestamp-nsec' | ../type='timestamp-usec' |
                 ../type='timestamp-msec'";
           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.";
           leaf seconds {
             type uint32;



Gray & Wobker            Expires 4 October 2020                [Page 33]

Internet-Draft          Sampled Traffic Streaming             April 2020


             description
               "Specifies the integer portion of the number of seconds
                since the epoch.";
           }
           leaf nanoseconds {
             type uint32;
             description
               "Specifies the fractional portion of the number of
                seconds since the epoch, in integer number of
                nanoseconds.";
           }
         }
         leaf payload-contents {
           when "../type='frame-payload-ingress' |
                 ../type='frame-payload-egress'";
           type frame-headers;
           description
             "Details about what parts of the frame this payload field
              SHOULD contain.  Note carefully the 'SHOULD' - for a
              variety of reasons (different forwarding paths, exception
              handling, etc.), the actual headers of any one frame MAY
              be different than this.";
         }
       }
     }

     list points {
       key "name";
       description
         "A listing of the observation points available on this device, what
          ports they provide for, and what filtering is available at
          those points.";
       leaf name {
         type psamp:nameType;
         description
           "A unique name for this point.";
       }
       list observationPoints {
         key "name";
         description
           "A list of the observation points (i.e. interfaces) able to be
            monitored at this point.";
         leaf name {
           type psamp:nameType;
           description
             "Name of this observationPoint";
         }
         uses psamp:observationPointParameters;



Gray & Wobker            Expires 4 October 2020                [Page 34]

Internet-Draft          Sampled Traffic Streaming             April 2020


       }
       list selectors {
         key "name";
         description
           "List of packet selector options available at this point.";
         leaf name {
           type psamp:nameType;
           description
             "A unique name for this selector option.";
         }
         uses psamp:selectorParameters;
       }
       list filters {
         config false;
         description
           "List of filtering options available at this point.";
         leaf filter {
           type filter-type;
           mandatory true;
           description
             "One specific filter available at this point.";
         }
       }
       leaf max-samplers {
         type uint32;
         config false;
         description
           "The maximum number of additional samplers that can be
            installed at this point.";
       }
       leaf max-filters {
         type uint32;
         config false;
         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.";
       }
       leaf max-frame-length-copy {
         type uint16;
         config false;
         description
           "The maximum size that the point can replicate and copy into
            the header.";
       }
       leaf max-frame-depth-inspect {
         type uint16;
         config false;



Gray & Wobker            Expires 4 October 2020                [Page 35]

Internet-Draft          Sampled Traffic Streaming             April 2020


         description
           "The offset of the last octet in a frame the point can
            perform filtering against.";
       }
       list samplers {
         key "name";
         description
           "A list of all the samplers attached to this point.";
         leaf name {
           type string;
           mandatory true;
           description
             "A unique name given to this sampler.";
         }
         leaf status {
           type status-type;
           mandatory true;
           description
             "The current status of this sampler.";
         }
         leaf client-heartbeat {
           type uint32;
           mandatory true;
           description
             "The number of seconds since the Client has refreshed this
              request.  The Client MUST only be able to set this value
              to 0, the Replicator MUST keep track of it, and SHOULD
              delete this entry when it reaches 3600.";
         }
         container destination {
           description
             "The destination of where to send the UDP stream to.";
           leaf type {
             type destination-type;
             mandatory true;
             description
               "The type of encoding for the destination.";
           }
           container udp-parameters {
             when "../type='udp'";
             description
               "Parameters for destination-type=udp.  Source port is
                always the port number assigned by IANA.";
             leaf destination-ip {
               type inet:ip-address-no-zone;
               mandatory true;
               description
                 "The destination IP to send the stream to.";



Gray & Wobker            Expires 4 October 2020                [Page 36]

Internet-Draft          Sampled Traffic Streaming             April 2020


             }
             leaf destination-port {
               type inet:port-number;
               mandatory true;
               description
                 "The destination UDP port number to send the stream
                  to.";
             }
           }
         }
         container request {
           description
             "The request as sent in by a Client.";
           container filters {
             description
               "Requested filters to apply to the stream.";
             uses filters;
           }
           container selector {
             description
               "Requested packet Selector.";
             uses psamp:selectorParameters;
           }
           leaf ratio {
             type uint32 {
               range "1..max";
             }
             mandatory true;
             description
               "The requested sampling ratio (1:N, with N being this
                value).";
           }
           leaf min-ratio {
             type uint32 {
               range "1..max";
             }
             description
               "The minimum value of N the client will accept.";
           }
           leaf max-ratio {
             type uint32 {
               range "1..max";
             }
             description
               "The maximum value of N the client will accept.";
           }
         }
         list proposals {



Gray & Wobker            Expires 4 October 2020                [Page 37]

Internet-Draft          Sampled Traffic Streaming             April 2020


           key "id";
           config false;
           description
             "The proposals as offered by the Replicator.";
           leaf id {
             type uint32 {
               range "1..max";
             }
             description
               "An id-number representing this proposal for selection.";
           }
           container selector {
             description
               "Provided packet Selector, plus stores statistics when
                this proposal is active.";
             uses psamp:selectorParameters;
           }
           leaf performance-penalty {
             type boolean;
             description
               "Selecting this offer will result in a forwarding perfomance
                penalty on the device (usually due to ASIC recirculation)";
           }
           leaf performance-penalty-amount {
             type uint16 {
               range "0..10000";
             }
             description
               "The forwarding performance penalty amount, in hundredths
                of a percent.  This value is not required even if
                performance-penalty is true.  If present, it MUST be
                treated as an estimate.";
           }
           container stream-format {
             description
               "The stream format that would be generated if this
                proposal is selected.";
             uses stream-format;
           }
           list filters {
             key "name";
             description
               "The filters the Replicator can actually apply in this
                proposal.  These MAY not match the request.";
             uses filters;
           }
         }
         leaf proposal-error {



Gray & Wobker            Expires 4 October 2020                [Page 38]

Internet-Draft          Sampled Traffic Streaming             April 2020


           type string {
             length "1..1023";
           }
           description
             "The Replicator was unable to generate any Proposals.";
         }
         leaf proposal-selected {
           type uint32 {
             range "1..max";
           }
           description
             "The ID of the proposal above the Client wants
              to use.";
         }
         leaf install-error {
           type string {
             length "1..1023";
           }
           description
             "The Replicator was unable to install the requested
              Proposal for this reason.";
         }
       }
     }
   }

Authors' Addresses

   Andrew Gray
   Charter Communications
   8560 Upland Drive, Suite B
   Englewood, CO 80112
   United States of America

   Phone: +1 720 699 5125
   Email: Andrew.Gray@charter.com


   Lawrence J Wobker
   Cisco Systems
   170 W Tasman Drive
   San Jose, CA 95134
   United States of America

   Phone: +1 984 216 1860
   Email: lwobker@cisco.com





Gray & Wobker            Expires 4 October 2020                [Page 39]