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]
