Internet DRAFT - draft-leon-ippm-sflow-yang-model

draft-leon-ippm-sflow-yang-model



Internet Engineering Task Force                               Leon Chen
Internet Draft                                                Alex Wang
Intended status: Standards Track                               Abhay DS
Expires: November 2017                                           Hua Wu
                                                               Ericsson
                                                           May 25, 2017



                         Yang Data Model for SFLOW
                  draft-leon-ippm-sflow-yang-model-00.txt




Abstract

   This document defines a YANG data model that can be used to
configure and manage SFLOW.

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), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   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."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html

   This Internet-Draft will expire on November 25, 2017.

Copyright Notice

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




Leon                  Expires November 25, 2017                [Page 1]

Internet-Draft          SFLOW Yang Data Model                  May 2017


   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://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. Terminology...............................................2
      1.2. Tree Diagrams.............................................3
   2. Design of Data Model...........................................3
      2.1. Tree Diagram..............................................3
   3. SFLOW YANG Module..............................................4
   4. Security Considerations.......................................16
   5. IANA Considerations...........................................17
   6. Normative References..........................................17

1. Introduction

   This document defines a YANG [RFC6020] data model for the management
   of SFLOW.

   This data model includes configuration data and state data (status
   information and counters for the collection of statistics).

1.1. Terminology

   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 [RFC2119].

   The following terms are used within this document:

   The following terms are defined in [RFC6241] and are not redefined
   here:

   o  client



Leon                  Expires November 25, 2017                [Page 2]

Internet-Draft          SFLOW Yang Data Model                  May 2017


   o  configuration data

   o  server

   o  state data

   The following terms are defined in [RFC6020] and are not redefined
   here:

   o  augment

   o  data model

   o  data node

   o  presence container

1.2. Tree Diagrams

   A simplified graphical representation of the data model is used in
   this document.  The meaning of the symbols in these diagrams is as
   follows:

   o  Brackets "[" and "]" enclose list keys.

   o  Abbreviations before data node names: "rw" means configuration
   (read-write), and "ro" means state data (read-only).

   o  Symbols after data node names: "?" means an optional node, "!"
   means a presence container, and "*" denotes a list and leaf-list.

   o  Parentheses enclose choice and case nodes, and case nodes are also
   marked with a colon (":").

   o  Ellipsis ("...") stands for contents of subtrees that are not
   shown.

2. Design of Data Model

   The goal of this document is to define a data model that provides a
   common user interface to the SFLOW. There is very information that is
   designated as "mandatory", providing freedom for vendors to adapt
   this data model to their respective product implementations.

2.1. Tree Diagram

   module: ietf-sflow


Leon                  Expires November 25, 2017                [Page 3]

Internet-Draft          SFLOW Yang Data Model                  May 2017


      +--rw sFlowAgent
         +--ro sFlowVersion?            string
         +--ro sFlowAgentAddressType?   inet-address:ip-version
         +--ro sFlowAgentAddress?       inet-address:ip-address
         +--ro sFlowCapExtData?         SFlowFsExtendedData
         +--rw sFlowRcvrEntry* [sFlowRcvrIndex]
         |  +--rw sFlowRcvrIndex                  int32
         |  +--rw sFlowRcvrOwner?                 string
         |  +--rw sFlowRcvrTimeout?               int32
         |  +--rw sFlowRcvrMaximumDatagramSize?   int32
         |  +--rw sFlowRcvrAddressType?           inet-address:ip-
   version
         |  +--rw sFlowRcvrAddress?               inet-address:ip-
   address
         |  +--rw sFlowRcvrPort?                  int32
         |  +--rw sFlowRcvrDatagramVersion?       int32
         +--rw sFlowFsEntry* [sFlowFsDataSource sFlowFsInstance]
         |  +--rw sFlowFsDataSource            sflow-
   yang:SFlowDataSource
         |  +--rw sFlowFsInstance              sflow-yang:SFlowInstance
         |  +--rw sFlowFsReceiver?             sflow-yang:SFlowReceiver
         |  +--rw sFlowFsPacketSamplingRate?   int32
         |  +--rw sFlowFsMaximumHeaderSize?    int32
         |  +--rw sFlowFsDirection?            sflow-yang:SFlowFsDirType
         +--rw sFlowCpEntry* [sFlowCpDataSource sFlowCpInstance]
            +--rw sFlowCpDataSource    sflow-yang:SFlowDataSource
            +--rw sFlowCpInstance      sflow-yang:SFlowInstance
            +--rw sFlowCpReceiver?     sflow-yang:SFlowReceiver
            +--rw sFlowCpInterval?     int32



3. SFLOW YANG Module

   <CODE BEGINS> file "ietf-sflow@2017-05-10.yang"
   module ietf-sflow {

     /*** NAMESPACE / PREFIX DEFINITION ***/

     namespace "urn:ietf:params:xml:ns:yang:ietf-sflow";
     prefix "sflow-yang";

     /*** LINKAGE (IMPORTS / INCLUDES) ***/

     import ietf-inet-types    { prefix "inet-address"; }
     import ietf-yang-types    { prefix "yang"; }



Leon                  Expires November 25, 2017                [Page 4]

Internet-Draft          SFLOW Yang Data Model                  May 2017


     /*** META INFORMATION ***/

     organization
      "sFlow working group";

     contact
      "Leon Chen
       <leon.chen@ericsson.com>

       Alex Wang
       <alex.g.wang@ericsson.com>

       Abhay DS
       <abhay.ds@ericsson.com>

       Hua Wu W
       <hua.w.wu@ericsson.com>";

     description
      "The sflow yang module for managing the generation and
       transportation of sFlow data records.";

     revision "2017-05-10" {
       description
        "Version 1, initial draft.";
       reference "RFC 3176";
     }

     /*** TYPE DEFINITIONS ***/

     typedef SFlowDataSource {
       type yang:object-identifier;
       description
        "Identifies a source of sFlow data.

         The following data source types are currently defined:

         - ifIndex.
         SFlowDataSources of this traditional form are called
         'port-based'. Ideally the sampling entity will perform
         sampling on all flows originating from or destined to the
         specified interface. However, if the switch architecture only
         allows input or output sampling then the sampling agent is
         permitted to only sample input flows input or output flows.
         Each packet must only be considered once for sampling,
         irrespective of the number of ports it will be forwarded to.
         Note: Port 0 is used to indicate that all ports on the device


Leon                  Expires November 25, 2017                [Page 5]

Internet-Draft          SFLOW Yang Data Model                  May 2017


               are represented by a single data source.
               - sFlowFsPacketSamplingRate applies to all ports on the
                 device capable of packet sampling.

         - smonVlanDataSource.
         An SFlowDataSource of this form refers to a 'Packet-based
         VLAN' and is called a 'VLAN-based' dataSource. is the VLAN
         ID as defined by the IEEE 802.1Q standard. The
         value is between 1 and 4094 inclusive, and it represents
         an 802.1Q VLAN-ID with global scope within a given
         bridged domain.
         Sampling is performed on all packets received that are part
         of the specified VLAN (no matter which port they arrived on).
         Each packet will only be considered once for sampling,
         irrespective of the number of ports it will be forwarded to.

         - entPhysicalEntry.
         An SFlowDataSource of this form refers to a physical entity
         within the agent (e.g. entPhysicalClass = backplane(4)) and
         is called an 'entity-based' dataSource. Sampling is performed
         on all packets entering the resource (e.g. If the backplane
         is being sampled, all packets transmitted onto the backplane
         will be considered as single candidates for sampling
         irrespective of the number of ports they ultimately reach).

         Note: Since each SFlowDataSource operates independently a
               packet that crosses multiple DataSources may generate
               multiple flow records.";
     }

     typedef SFlowInstance {
       type int32 {
         range "1..65535";
       }
       description
        "If more than one sFlow sampler is available for this
         SFlowDataSource then individual samplers are distinguished
         using the SFlowInstance variable. The value of
         SFlowInstance ranges from 1..n where n is the number of
         samplers associated with this SFlowDataSource.

         Note: Each sFlow sampler instance must operate
               independently of all other instances. Setting
               an attribute of one sampler must not alter the
               the behavior and settings of other sampler
               instances.";
     }


Leon                  Expires November 25, 2017                [Page 6]

Internet-Draft          SFLOW Yang Data Model                  May 2017



     typedef SFlowReceiver {
       type int32;
       description
        "Identify the sFlow receiver associated with this resource.

         A value of zero indicates that this resource is available.
         If non-zero the value must correspond to a valid, active
         sFlowRcvrIndex.

         If the value is currently zero it may be set to any
         active entry in the sFlowRcvrTable. If the value is
         not zero then a set to anything other than zero or
         its current value will result in an error (bad value).

         Setting to zero frees the resource and returns all the
         values in this entry to their default values.

         If an entry in the sFlowRcvrTable expires, either
         because the sFlowRcvrOwner is set to the empty
         string or because the sFlowRcvrTimeout reaches zero, then
         the agent must mark all associated resources as available
         (by setting the associated SFlowReceiver entry to zero)
         and all values in these records must be restored to their
         default values.

         This mechanism provides no enforcement and relies on the
         cooperation of management entities in order to ensure that
         competition for a resource is fairly resolved. A management
         entity should not make any changes to a resource
         without first acquiring it by successfully writing its
         sFlowRcvrIndex value as the SFlowReceiver for the resource.";
     }

     typedef SFlowFsExtendedData {
       type bits {
         bit ext_switch  {
            position 0;
           description
             "extended switch data
              Note: For untagged ingress ports, use the assigned vlan
              and priority of the port for the src_vlan and src_priority
              values.  For untagged egress ports, use the values for
              dst_vlan and dst_priority that would have been placed in
              the 802.Q tag had the egress port been a tagged member of
              the VLAN instead of an untagged member.";
         }


Leon                  Expires November 25, 2017                [Page 7]

Internet-Draft          SFLOW Yang Data Model                  May 2017


         bit ext_router  {
            position 1;
           description
             "extended router data";
         }
         bit ext_gateway  {
            position 2;
           description
             "extended gateway data";
         }
         bit ext_user  {
            position 3;
           description
             "extended user data";
         }
         bit ext_url  {
            position 4;
           description
             "extended URL data";
         }
         bit ext_mpls  {
            position 5;
           description
             "extended MPLS data
              Empty stack may be returned if values unknown
              If only innermost label is known then stack may contain
              single entry See RFC 3032 for label encoding
              Labels in network order
              ";
         }
         bit ext_nat  {
            position 6;
           description
             "extended NAT data
              Packet header records report addresses as seen at the
              sFlowDataSource. The extended_nat structure reports on
              translated source and/or destination addesses for this
              packet. If an address was not translated it should be
              equal to that reported for the header.
             ";
         }
         bit ext_mpls_tunnel  {
            position 7;
           description
             "extended MPLS tunnel data";
         }
         bit ext_mpls_vc  {


Leon                  Expires November 25, 2017                [Page 8]

Internet-Draft          SFLOW Yang Data Model                  May 2017


            position 8;
           description
             "extended MPLS VC data";
         }
         bit ext_mpls_fec  {
            position 9;
           description
             "extended MPLS FEC data";
         }
         bit ext_mpls_lvp_fec  {
            position 10;
           description
             "extended MPLS LVP FEC data";
         }
         bit ext_vlan_tunnel  {
            position 11;
           description
             "extended VLAN tunnel information
              Record outer VLAN encapsulations that have been stripped.
              extended_vlantunnel information should only be reported
              if all the following conditions are satisfied:
             1. The packet has nested vlan tags, AND
             2. The reporting device is VLAN aware, AND
             3. One or more VLAN tags have been stripped, either
               because they represent proprietary encapsulations, or
               because switch hardware automatically strips the outer
               VLAN encapsulation.
               Reporting extended_vlantunnel information is not a
              substitute for reporting extended_switch information.
              extended_switch data must always be reported to describe
              the ingress/egress VLAN information for the packet.
              The extended_vlantunnel information only applies to nested
              VLAN tags, and then only when one or more tags has been
              stripped.";
         }
       }
       description
       "This describes the capabilites of the Node for
        supporting extend flow data.";
     }

     typedef SFlowFsDirType {
       type enumeration {
         enum in  {
            value 1;
           description
             "Ingress direction, sampling incoming packets";


Leon                  Expires November 25, 2017                [Page 9]

Internet-Draft          SFLOW Yang Data Model                  May 2017


         }
         enum out  {
           value 2;
           description
             "Egress direction, sampling outgoing packets";
         }
         enum both  {
           value 3;
           description
             "Both ingress and egress, sampling bi-directional packets";
         }
       }
       description
       "This describes the packets forwarding direction
        that need to be sampled.";
     }

     container sFlowAgent {
       description
        "Top level container for sflow configuration";

       leaf sFlowVersion {
         type string {
           length "1..16";
         }
         config false;
         description
          "Uniquely identifies the version and implementation of this
           module.

           Management entities must check the Version and not attempt
           to manage agents with Versions greater than that for which
           they were designed.

           Note: The sFlow Datagram Format has an independent version
                 number which may change independently from it.
                 It applies to the structure and semantics of
                 the SFLOW yang model only.";
       }

       leaf sFlowAgentAddressType {
         type inet-address:ip-version;
         config false;
         description
          "The address type of the address associated with this agent.
           Only ipv4 and ipv6 types are supported.";
       }


Leon                  Expires November 25, 2017               [Page 10]

Internet-Draft          SFLOW Yang Data Model                  May 2017



       leaf sFlowAgentAddress {
         type inet-address:ip-address;
         config false;
         description
          "The IP address associated with this agent. In the case of a
           multi-homed agent, this should be the loopback address of
           the agent. The sFlowAgent address must provide IP
           connectivity to the agent. The address should be an
           invariant that does not change as interfaces are
           reconfigured, enabled, disabled, added or removed.
           A manager should be able to use the sFlowAgentAddress
           as a unique key that will identify this agent over
           extended periods of time so that a history can
           be maintained.";
       }

       leaf sFlowCapExtData {
         type SFlowFsExtendedData;
         config false;
         description
          "This element provide supplimentary information about the
             sampled packet. All applicable extended flow records
           should be included with each flow sample.";
       }


       /* XXX table comments here XXX */

       list sFlowRcvrEntry {

         key "sFlowRcvrIndex";
         description
          "Attributes of an sFlow Receiver.";


         leaf sFlowRcvrIndex {
           type int32 {
             range "1..65535";
           }
           description
            "Index into sFlowReceiverTable.";
         }

         leaf sFlowRcvrOwner {
           type string {
             length "0..127";


Leon                  Expires November 25, 2017               [Page 11]

Internet-Draft          SFLOW Yang Data Model                  May 2017


           }
           description
            "The entity making use of this sFlowRcvrTable entry. The
             empty string indicates that the entry is currently
             unclaimed. An entity wishing to claim an sFlowRcvrTable
             entry must ensure that the entry is unclaimed before
             trying to claim it. The entry is claimed by setting
             the owner string. The entry must be claimed before any
             changes can be made to other sampler objects.

             In order to avoid a race condition, the entity taking
             control of the sampler must set both the owner and a value
             for sFlowRcvrTimeout in the same configuration request.

             When a management entity is finished using the sampler, it
             should set the value of sFlowRcvrOwner back to unclaimed.
             The agent must restore all other entities this row to
             their default values when the owner is set to unclaimed.
             It must also free all other resources associated with this
             sFlowRcvrTable entry.

             This mechanism provides no enforcement and relies on the
             cooperation of management entities in order to ensure that
             competition for a receiver entry is fairly resolved.";
         }

         leaf sFlowRcvrTimeout {
           type int32;
           description
            "The time (in seconds) remaining before the sampler is
             released and stops sampling. When set, the owner
             establishes control for the specified period. When read,
             the remaining time in the interval is returned.

             A management entity wanting to maintain control of the
             sampler is responsible for setting a new value before
             the old one expires.

             When the interval expires, the agent is responsible for
             restoring all other entities in this row to their default
             values. It must also free all other resources associated
             with this sFlowRcvrTable entry.";
         }

         leaf sFlowRcvrMaximumDatagramSize {
           type int32;
           description


Leon                  Expires November 25, 2017               [Page 12]

Internet-Draft          SFLOW Yang Data Model                  May 2017


            "The maximum number of data bytes that can be sent in a
             single sample datagram. The manager should set this value
             to avoid fragmentation of the sFlow datagrams.";
         }

         leaf sFlowRcvrAddressType {
           type inet-address:ip-version;
           description
            "The type of sFlowRcvrCollectorAddress.";
         }

         leaf sFlowRcvrAddress {
           type inet-address:ip-address;
           description
            "The IP address of the sFlow collector.
             If set to 0.0.0.0 not sFlow datagrams will be sent.";
         }

         leaf sFlowRcvrPort {
           type int32;
           description
            "The destination port for sFlow datagrams.";
         }

         leaf sFlowRcvrDatagramVersion {
           type int32;
           description
            "The version of sFlow datagrams that should be sent.

             When set to a value not support by the agent, the agent
             should adjust the value to the highest supported value
             less than the requested value, or return an bad
             value error if no such value exists.";
         }
       }


       /* XXX table comments here XXX */

       list sFlowFsEntry {

         key "sFlowFsDataSource sFlowFsInstance";
         description
          "Attributes of a flow sampler.";


         leaf sFlowFsDataSource {


Leon                  Expires November 25, 2017               [Page 13]

Internet-Draft          SFLOW Yang Data Model                  May 2017


           type sflow-yang:SFlowDataSource;
           description
            "sFlowDataSource for this flow sampler.";
         }

         leaf sFlowFsInstance {
           type sflow-yang:SFlowInstance;
           description
            "The sFlow instance for this flow sampler.";
         }

         leaf sFlowFsReceiver {
           type sflow-yang:SFlowReceiver;
           description
            "The SFlowReceiver for this flow sampler.";
         }

         leaf sFlowFsPacketSamplingRate {
           type int32;
           description
            "The statistical sampling rate for packet sampling from
             this source.

             Set to N to sample 1/Nth of the packets in the monitored
             flows.  An agent should choose its own algorithm to
             introduce variance into the sampling so that exactly
             every Nth packet is not counted. A sampling rate of 1
             counts all packets. A sampling rate of 0 disables
             sampling.

             The agent is permitted to have minimum and maximum
             allowable values for the sampling rate. A minimum rate
             lets the agent designer set an upper bound on the overhead
             associated with sampling, and a maximum rate may be the
             result of hardware restrictions (such as counter size).
             In addition not all values between the maximum and
             minimum may be realizable as the sampling rate
             (again because of implementation considerations).

             When the sampling rate is set the agent is free to adjust
             the value so that it lies between the maximum and minimum
             values and has the closest achievable value.

             When read, the agent must return the actual sampling rate
             it will be using (after the adjustments previously
             described).
             The sampling algorithm must converge so that over time


Leon                  Expires November 25, 2017               [Page 14]

Internet-Draft          SFLOW Yang Data Model                  May 2017


             the number of packets sampled approaches 1/Nth of the
             total number of packets in the monitored flows.";
         }

         leaf sFlowFsMaximumHeaderSize {
           type int32;
           description
            "The maximum number of bytes that should be copied from a
             sampled packet. The agent may have an internal maximum and
             minimum permissible sizes. If an attempt is made to set
             this value outside the permissible range then the agent
             should adjust the value to the closest permissible
             value.";
         }

         leaf sFlowFsDirection {
           type sflow-yang:SFlowFsDirType;
           description
            "This object specifies the packet forwarding direction
             that need to be sampled.";
         }
       }


       /* XXX table comments here XXX */

       list sFlowCpEntry {

         key "sFlowCpDataSource sFlowCpInstance";
         description
          "Attributes of a counter poller.";


         leaf sFlowCpDataSource {
           type sflow-yang:SFlowDataSource;
           description
            "Identifies the source of the data for the counter
             poller.";
         }

         leaf sFlowCpInstance {
           type sflow-yang:SFlowInstance;
           description
            "The sFlowInstance for this counter poller.";
         }

         leaf sFlowCpReceiver {


Leon                  Expires November 25, 2017               [Page 15]

Internet-Draft          SFLOW Yang Data Model                  May 2017


           type sflow-yang:SFlowReceiver;
           description
            "The SFlowReciever associated with this counter poller.";
         }

         leaf sFlowCpInterval {
           type int32;
           description
            "The maximum number of seconds between successive samples
             of the counters associated with this data source.
             A sampling interval of 0 disables counter sampling.

             The agent is permitted to have minimum and maximum
             allowable values for the counter polling interval.
             A minimum interval lets the agent designer set an upper
             bound on the overhead associated with polling, and a
             maximum interval may be the result of implementation
             restrictions (such as counter size). In addition not
             all values between the maximum and minimum may be
             realizable as the sampling interval (again because of
             implementation considerations).

             When the sampling rate is set the agent is free to adjust
             the value so that it lies between the maximum and minimum
             values and has the closest achievable value.

             When read, the agent must return the actual sampling
             interval it will be using
             (after the adjustments previously described).
             The sampling algorithm must converge so that over time the
             number of packets sampled approaches 1/Nth of the total
             number of packets in the monitored flows.";
         }
       }
     }

   }
   <CODE ENDS>


4. Security Considerations

   The data model defined does not create any security implications.






Leon                  Expires November 25, 2017               [Page 16]

Internet-Draft          SFLOW Yang Data Model                  May 2017


5. IANA Considerations

   This draft does not request any IANA action.



6. Normative References

   [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
             Requirement Levels", BCP 14, RFC 2119, March 1997.

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

   [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6021,
             DOI 10.17487/RFC6021, October 2010, <http://www.rfc-
             editor.org/info/rfc6021>.

   [RFC6241] R. Enns, Ed., "Network Configuration Protocol (NETCONF)",
             RFC 6241, DOI 10.17487/RFC6241, June 2011, <http://www.rfc-
             editor.org/info/rfc6241>.

   [RFC3176] P. Phaal, "A Method for Monitoring Traffic in Switched and
             Routed Networks", RFC 3176, DOI 10.17487/RFC3176, September
             2001, <http://www.rfc-editor.org/info/rfc3176>.





   Authors' Addresses
















Leon                  Expires November 25, 2017               [Page 17]

Internet-Draft          SFLOW Yang Data Model                  May 2017


   Leon Chen
   Email: leon.chen@ericsson.com

   Alex Wang
   Email: alex.g.wang@ericsson.com

   Abhay DS
   Email: abhay.ds@ericsson.com

   Hua Wu W
   Email: hua.w.wu@ericsson.com

   Ericsson (China) Communications Company Ltd.
   Ericsson Tower, No. 5 Lize East Street,
   Chaoyang District Beijing 100102, P.R. China


































Leon                  Expires November 25, 2017               [Page 18]