ietf-sampled-streaming@2019-08-06.yang

module ietf-sampled-streaming {
  namespace "urn:ietf:params:xml:ns:yang:ietf-sampled-streaming";
  prefix "ss";
  
  import ietf-yang-types {
    prefix yang;
  }
  import ietf-interfaces {
    prefix if;
  }
  import ietf-inet-types {
    prefix inet;
  }
  
  organization
    "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-08-06 {
    description 
      "Updates based on feedback for -01 draft.";
    reference
      "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.";
      }
      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.";
      }
    }
    description "The filtering abilities available.";
  }

  typedef field-type {
    type enumeration {
      enum padding {
        description "Padding bits that MUST be ignored.";
      }
      enum port {
        description "An indication of the port the traffic was sampled from.";
      }
      enum direction {
        description "Which direction the traffic went.";
      }
      enum ingress-port {
        description "What port the traffic was received from (may be different than 'port')";
      }
      enum egress-port {
        description "What port the traffic is leaving on (may be different than 'port')";
      }
      enum timestamp-msec {
        description "The timestamp the packet was received at, in integer milliseconds.";
      }
      enum timestamp-usec {
        description "The timestamp the packet was received at, in integer microseconds.";
      }      
      enum timestamp-nsec {
        description "The timestamp the packet was received at, in integer nanoseconds.";
      }
      enum frame-length {
        description "The received frame length.  Note that due to chipset capabilities, this MAY NOT be the same as the captured packet length.";
      }
      enum frame-payload {
        description "The payload of the frame.";
      }
      enum action {
        description "The action that was taken on this frame.  Values are mapped as according to action-type.";
      }
    }
    description "Types of data included in the data stream provided back to the receiver.  Note that all fields will not be provided.";
  }

  typedef action-type {
    type enumeration {
      enum forwarded {
        description "Forwarded normally through the system.";
      }
      enum dropped {
        description "Generically dropped.  A more specific action type code should be used, if possible.";
      }
      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 remarked {
        description "Frame was remarked and forwarded.";
      }
    }
    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 direction-type {
    type enumeration {
      enum ingress {
        description "Traffic flowing into the Replicator.";
      }
      enum egress {
        description "Traffic flowing out of the Replicator.";
      }
      enum both {
        description "Capture both ingress and egress traffic.";
      }
    }
    description "Different possible direction types.";
  }
    
  list points {
    description "A listing of the capture points available on this device, what ports they provide for, and what filtering is available at those points.";
    key name;
    leaf name {
      type string;
      description "The name of this capture point.";
    }
    list interface {
      description "List of interfaces that are available at this point.";
      config false;
	  	leaf if {
        mandatory true;
        type if:interface-ref;
        description "An interface tied to this capture point.";
		  }
	  }
    list filters {
      description "List of filtering options available at this point.";
      config false;
      leaf filter {
        description "One specific filter available at this point.";
        mandatory true;
        type filter-type;
      }
    }
    leaf min-ratio {
      type uint32 {
        range "1..max";
      }
      description "The minimum sampling ratio (1:N, with N being this value) this point can provide.";
    }
    leaf max-ratio {
      type uint32 {
        range "1..max";
      }
      description "The maximum sampling ratio (1:N, with N being this value) this point can provide.";
    }
    leaf max-samplers {
      type uint32;
      description "The maximum number of samplers that can be installed at this point.";
    }
    leaf max-filters {
      type uint32;
      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;
      description "The maximum size that the point can replicate and copy into the header.";
    }
    leaf max-frame-depth-inspect {
      type uint16;
      description "The offset of the last octet in a frame the ASIC can perform filtering against.";
    }

    list samplers {
      description "A list of all the samplers attached to this point.";

      config true;
      key "name";

      leaf name {
        mandatory true;
        type string;
        description "A unique name given to this sampler.";
      }

      container destination {
        description "The destination of where to send the UDP stream to.";
        leaf type {
          mandatory true;
          type destination-type;
          description "The type of encoding for the destination.";
        }
        container udp-parameters {
          description "Parameters for destination-type=udp.  Source port is always the port number assigned by IANA.";
          when "../type='udp'";
          leaf destination-ip {
            mandatory true;
            type inet:ip-address-no-zone;
            description "The destination IP to send the stream to.";
          }
          leaf destination-port {
            mandatory true;
            type inet:port-number;
            description "The destination UDP port number to send the stream to.";
          }
        }
      }

      leaf ratio {
        mandatory true;
        type uint32 {
          range "1..max";
        }
        description "The requested sampling ratio (1:N, with N being this value).";
      }

      list filters {
        description "A list of filters applied to this sampling.  Multiple filters are logically ANDed together.";

        key "name";
        leaf name {
          description "A name for this filter.";
          type string;
        }

        list interfaces {
          when "../type = 'interfaces'";
          description "Filter down to only this list of interfaces.";
          key "int";
          leaf int {
            description "A specific interface to filter against.";
            type if:interface-ref;
          }
        }

        list actions {
          when "../type = 'action'";
          description "Filter down to only this list of actions.";
          key "action";
          leaf action {
            description "One specific action code.";
            type action-type;
          }
        }

        list directions {
          when "../type = 'direction'";
          description "Which direction(s) to sample traffic in.";
          key "direction";
          leaf direction {
            description "Specific direction code.";
            type direction-type;
          }
        }

        leaf type {
          description "The type of filter associated.";
          type filter-type;
          mandatory true;
        }

        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 {
            description "Offset in octets from the start of the frame to begin the match on.";
            type uint16;
          }
          leaf match {
            description "The bytes to match on.";
            type binary;
          }
        }

        leaf frame-length {
          when "../type = 'frame-length'";
          type uint16;
          description "Frame length to match on.";
        }

      }
      container stream-format {
        config false; 
        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 {
          description "The listing of the fields that will be encapsulated and sent to the receiver.";

          key "name";
          leaf name {
            type string;
            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, which is only permitted as the last field in this definition.";
          }
          leaf type {
            type field-type;
            description "The type of this data.";
          }

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