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 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 Alex Wang Abhay DS Hua Wu W "; 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."; } } } } 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, . [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6021, DOI 10.17487/RFC6021, October 2010, . [RFC6241] R. Enns, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . [RFC3176] P. Phaal, "A Method for Monitoring Traffic in Switched and Routed Networks", RFC 3176, DOI 10.17487/RFC3176, September 2001, . 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]