IP Flow Information Export WG G. Muenz Internet-Draft TU Muenchen Intended status: Standards Track B. Claise Expires: May 7, 2009 Cisco Systems, Inc. November 3, 2008 Configuration Data Model for IPFIX and PSAMP Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of 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 May 7, 2009. Abstract This document specifies a data model for the configuration of caches, selection processes, exporting processes, and collecting processes of IPFIX and PSAMP compliant monitoring devices. The configuration data model is encoded in Extensible Markup Language (XML). The structure of the data model is specified in a YANG module to ensure compatibility with the NETCONF protocol. A YANG-to-XSD converter is available which allows generating an XML Schema Definition (XSD) of the data model. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 1] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Table of Contents 1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. IPFIX Documents Overview . . . . . . . . . . . . . . . . . 5 2.2. PSAMP Documents Overview . . . . . . . . . . . . . . . . . 5 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Structure of the Configuration Data Model . . . . . . . . . . 6 4.1. UML Representation . . . . . . . . . . . . . . . . . . . . 8 4.2. Exporter Configuration . . . . . . . . . . . . . . . . . . 10 4.3. Collector Configuration . . . . . . . . . . . . . . . . . 12 5. Configuration Parameters . . . . . . . . . . . . . . . . . . . 12 5.1. ObservationPoint Class . . . . . . . . . . . . . . . . . . 13 5.2. Selector Class . . . . . . . . . . . . . . . . . . . . . . 14 5.2.1. Sampler Classes . . . . . . . . . . . . . . . . . . . 15 5.2.2. Filter Classes . . . . . . . . . . . . . . . . . . . . 15 5.3. SelectionProcess Class . . . . . . . . . . . . . . . . . . 16 5.4. Cache Class . . . . . . . . . . . . . . . . . . . . . . . 17 5.4.1. CacheLayout Class . . . . . . . . . . . . . . . . . . 18 5.5. ExportingProcess Class . . . . . . . . . . . . . . . . . . 19 5.5.1. Destination Class . . . . . . . . . . . . . . . . . . 19 5.5.2. Export Parameters Classes . . . . . . . . . . . . . . 20 5.5.3. Option Class . . . . . . . . . . . . . . . . . . . . . 21 5.5.4. OptionTemplate Class . . . . . . . . . . . . . . . . . 22 5.6. CollectingProcess Class and Receiver Class . . . . . . . . 23 5.6.1. Receiver Parameters Classes . . . . . . . . . . . . . 24 6. YANG Module of the IPFIX/PSAMP Configuration Data Model . . . 25 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 7.1. PSAMP Device . . . . . . . . . . . . . . . . . . . . . . . 39 7.2. IPFIX Device . . . . . . . . . . . . . . . . . . . . . . . 41 7.3. Export of Flow Records and Packet Reports . . . . . . . . 44 7.4. Collector and File Writer . . . . . . . . . . . . . . . . 48 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 49 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.1. Normative References . . . . . . . . . . . . . . . . . . . 49 9.2. Informative References . . . . . . . . . . . . . . . . . . 50 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 2] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Intellectual Property and Copyright Statements . . . . . . . . . . 53 Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 3] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 1. Open Issues TLS/DTLS parameters: IPFIX WG lacks experience with IPFIX implementations supporting TLS/DTLS. Is TLS/DTLS configuration out of scope of IPFIX anyway? Relationship to IPFIX and PSAMP MIB: Check if operational data (read-only, non-configurable parameters) is included as far as possible. Parameters: Review specification of configuration data model w/r to mandatory/optional parameters and default values. Replace timeticks by other data type (e.g., milliseconds) as soon as yang- types supports it. Keep up with NETMOD WG: Make use of new language features to come, e.g. support of features, default values provided by device. 2. Introduction IPFIX and PSAMP compliant monitoring devices (routers, switches, monitoring probes, Collectors etc.) offer various configuration possibilities that allow adapting network monitoring to the goals and purposes of the application, e.g. accounting and charging, traffic analysis, performance monitoring, security monitoring. The use of a common device-independent configuration data model for IPFIX and PSAMP compliant monitoring devices facilitates network management and configuration, especially if monitoring devices of different implementers and/or manufacturers are deployed simultaneously. On the one hand, a device-independent configuration data model helps storing and managing the configuration data of monitoring devices in a consistent format. On the other hand, it can be used for local and remote configuration of monitoring devices. However, this requires that monitoring devices natively support the configuration data model, or that a mapping between the configuration data model and the device-specific representation of configuration data is provided. An appropriate transport protocol is needed in the case of remote configuration. The purpose of this document is the specification of a device- independent configuration data model that covers the commonly available configuration parameters of Caches and Selection Processes, Exporting Processes, and Collecting Processes. The data model is encoded in Extensible Markup Language (XML) [W3C.REC-xml-20040204]. An XML document conforming to the configuration data model contains the configuration data of one monitoring device. In order to ensure compatibility with the NETCONF protocol [RFC4741], YANG [I-D.ietf-netmod-yang] is used as modeling language. If required, the YANG specification of the configuration data model can be converted into XML Schema language [W3C.REC-xmlschema-0-20041028] using the pyang tool [YANG-WEB]. YANG provides mechanisms to augment Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 4] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 the configuration data model with additional device-specific or vendor-specific parameters. For the configuration of remote monitoring devices, an appropriate protocol is needed to transfer the XML encoded configuration data. The configuration data model is compatible with the NETCONF protocol [RFC4741]. However, alternative protocols, such as the Simple Object Access Protocol (SOAP) [W3C.REC-soap12-part1-20070427], are also suitable for transferring XML data from a network management system to a monitoring device. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2.1. IPFIX Documents Overview The IPFIX protocol [RFC5101] provides network administrators with access to IP flow information. The architecture for the export of measured IP flow information out of an IPFIX Exporting Process to a Collecting Process is defined in [I-D.ietf-ipfix-architecture], per the requirements defined in [RFC3917]. The IPFIX protocol [RFC5101] specifies how IPFIX Data Records and Templates are carried via a number of transport protocols from IPFIX Exporting Processes to IPFIX Collecting Process. IPFIX has a formal description of IPFIX Information Elements, their name, type and additional semantic information, as specified in [RFC5102]. [I-D.ietf-ipfix-mib] specifies the IPFIX Management Information Base. Finally, [I-D.ietf-ipfix-as] describes what type of applications can use the IPFIX protocol and how they can use the information provided. It furthermore shows how the IPFIX framework relates to other architectures and frameworks. The storage of IPFIX Messages in a file is specified in [I-D.ietf-ipfix-file]. 2.2. PSAMP Documents Overview The framework for packet selection and reporting [I-D.ietf-psamp-framework] enables network elements to select subsets of packets by statistical and other methods, and to export a stream of reports on the selected packets to a Collector. The set of packet selection techniques (sampling, filtering, and hashing) standardized by PSAMP are described in [I-D.ietf-psamp-sample-tech]. The PSAMP protocol [I-D.ietf-psamp-protocol] specifies the export of packet information from a PSAMP Exporting Process to a Collector. Like IPFIX, PSAMP has a formal description of its Information Elements, their name, type and additional semantic information. The PSAMP information model is defined in [I-D.ietf-psamp-info]. [I-D.ietf-psamp-mib] describes the PSAMP Management Information Base. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 5] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 3. Terminology This document adopts the terminologies used in [RFC5101], [I-D.ietf-ipfix-file], and [I-D.ietf-psamp-protocol]. As in [RFC5101], these specific terms have the first letter of a word capitalized when used in this document. The following additional terms are defined: Cache: The Cache is a functional block in a Metering Process which maintains IPFIX Flow Records or PSAMP Packet Reports. According to [RFC5101], the maintenance of Flow Records may include creating new records, updating existing ones, computing Flow statistics, deriving further Flow properties, detecting Flow expiration, passing Flow Records to the Exporting Process, and deleting Flow Records. The maintainence of Packet Reports covers the same set of functions. Cache Layout: The Cache Layout defines the superset of fields that are included in the Packet Reports or Flow Records maintained by the Cache. The fields are specified by the corresponding Information Elements. In general, the largest possible subset of the specified fields is derived for every Packet Report or Flow Record. More specific rules about which fields must be included are given in Section 5.4.1. Cache Type: The Cache Type specifies whether Packet Reports or Flow Records are generated by the Cache. In the case of Flow Records, it also specifies the Flow expiration policy. 4. Structure of the Configuration Data Model The IPFIX reference model in [I-D.ietf-ipfix-architecture] describes Metering Processes, Exporting Processes, and Collecting Processes as functional blocks of IPFIX Devices. The PSAMP framework [I-D.ietf-psamp-framework] provides the corresponding information for PSAMP Devices and introduces Selection Processes as functional blocks within Metering Processes. Normative definitions of these terms are given in [RFC5101] and [I-D.ietf-psamp-protocol]. In Section 3, the Cache is defined as another functional block within Metering Processes. Further explanations about the relationship between Selection Processes and Caches are given in the next paragraph. IPFIX File Reader and File Writer are defined as specific kinds of Exporting and Collecting Processes in [I-D.ietf-ipfix-file]. IPFIX and PSAMP compliant monitoring device implementations usually maintain the separation of functional blocks although they do not necessarily implement all of them. Furthermore, they provide various configuration possibilities; some of them are specified as mandatory by the IPFIX protocol [RFC5101]. The configuration data model Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 6] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 enables the setting of commonly available configuration parameters for Caches, Selection Processes, Exporting Processes, and Collecting Processes. In addition, it allows specifying the composition of functional blocks within a monitoring device configuration and their linkage with Observation Points. In an IPFIX and PSAMP compliant monitoring device implementation, the functionality of the Metering Process is commonly split into packet filtering and sampling functions performed by Selection Processes, and the maintainence of Flow Records and Packet Reports performed by Caches. Figure 1 illustrates this separation with the example of a simple Metering Process consisting of one Selection Process and one Cache. +-----------------------------------+ | Metering Process | | +-----------+ Stream of | Stream of | | Selection | selected +-------+ | Stream of observed -->| Process |---------->| Cache |--> Flow Records or packets | +-----------+ packets +-------+ | Packet Reports +-----------------------------------+ Figure 1: Selection Process and Cache forming a Metering Process The configuration data model adopts this separation in order to support the flexible configuration and combination of Selection Processes and Caches. As defined in in [I-D.ietf-psamp-protocol], the Selection Process takes the observed packet stream as its input and selects a subset of that stream as its output. The action of a Selection Process on a single packet of its input is defined by a single Selector or an ordered composition of multiple Selectors. The stream of selected packets may enter a Cache. In the case of a PSAMP Device, the Cache generates Packet Reports. In the case of an IPFIX Device, the Cache generates Flow Records. If Packet Reports or Flow Records are generated, is depends on the Cache Type. The selection of parameters in the configuration data model is based on configuration issues discussed in the IPFIX and PSAMP documents [RFC3917], [RFC5101], [I-D.ietf-ipfix-architecture], [I-D.ietf-psamp-protocol], [I-D.ietf-psamp-framework], and [I-D.ietf-psamp-sample-tech]. Furthermore, the structure and content of the IPFIX MIB module [I-D.ietf-ipfix-mib] and the PSAMP MIB module [I-D.ietf-psamp-mib] were taken into consideration. Consistency between the configuration data model and the IPFIX and PSAMP MIB modules is an intended goal. Therefore, parameters in the configuration data model are named according to corresponding managed objects. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 7] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 The next section explains how UML class diagrams are deployed to illustrate the structure of the configuration data model. Thereafter, Section 4.2 and Section 4.3 explain the class diagrams for the configuration of Exporters and Collectors, respectively. Each of the presented classes contains specific configuration parameters which are specified in Section 5. The formal definition of the configuration data model in YANG is given in Section 6. Section 7 illustrates the usage of the model with example configurations in XML. 4.1. UML Representation We use Unified Modeling Language (UML) class diagrams [UML] to explain the structure of the configuration data model. Each class contains a set of related parameters. For example, the Selector class contains the configuration parameters of a Selector. If some parameters within a class belong together, it can make sense to group these parameters in a subclass. This is especially useful if different subclasses represent choices of different parameter sets, or if the parameters of a subclass may appear multiple times. For example, the Selector class contains the parameters of one of the subclasses SelectAll, SampCountBased, SampTimeBased,sampRandOutOfN, SampUniProb, SampNonUniProb, SampFlowState, FilterMatch, FilterHash, and FilterRState. As another example, the OptionTemplate class may contain multiple times the parameters of the OptionField subclass. Classes serve as templates for the objects of a specific configuration. In the corresponding XML document, every object is encoded as an XML element. So, one object of the Selector class corresponds to one occurrence of ... in the XML document. There are various possibilities how objects of classes can be related to each other. In the scope of this document, we use two different types of relationship between objects: aggregation and unidirectional association. In UML class diagrams, two different arrow types are used as shown in Figure 2. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 8] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 +---+ 0..* +---+ +---+ 0..* 1 +---+ | A |<>------| B | | A |-------->| B | +---+ +---+ +---+ +---+ (a) Aggregation (b) Unidirectional association Figure 2: Class relationships in UML class diagrams Aggregation means that one object is part of the other object. In example (a), an object of class B is part of an object of class A. In the XML document, this corresponds to nested XML elements: ... ... Note that we write class names starting with a capital letter throughout this document. The corresponding XML elements use identical names starting with an uncapitalized letter because they represent objects, not classes. An unidiractional association is a reference to an object. In example (b), an object of class A contains a reference to an object of class B. In the XML document, this corresponds to separate XML elements that are not nested. The indicated numbers define the multiplicity: "1": one only "0..*": zero or more "1..*": one or more In the case of aggregation, the multiplicity indicates how many objects of one class may be included in one object of the other class. In example (a), an object of class A may contain an arbitrary number of objects of class B. In the case of unidirectional association, the multiplicity at the arrowhead specifies the number of objects of a given class that may be referred to. The multiplicity at the arrowtail specifies how many different objects of one class may refer to a single object of the other class. In example (b), an object of class A refers to single object of class B. One object of class B can be referred to from an arbitrary number of objects of class A. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 9] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 In UML class diagrams, all classes that occur with multiplicity greater than one in an aggregation relationship, and all classes that are referenced in associations MUST have a key which allows distinguishing different objects of the class. This key MUST be unique within the given scope. Regarding example (a), all objects of class B belonging to the same object of class A must have a key; the scope is local to the given object of class A. In example (b), all objects of class B must have a unique key as they can be referenced by multiple objects of class A (i.e., the scope is global). In YANG, there exists a corresponding rule which mandates the existence of a key for all elements which appear in lists [I-D.ietf-netmod-yang]. In the configuration data model, the key is a string parameter called "name" in all concerned classes, corresponding to XML elements in the XML document. 4.2. Exporter Configuration Figure 3 below shows the main classes of the configuration data model which are involved in the configuration of an IPFIX or PSAMP Exporter. The role of the classes can be briefly summarized as follows: o The ObservationPoint class specifies an Observation Point (i.e., an interface or linecard) of the monitoring device at which packets are captured for traffic measurements. An object of the ObservationPoint class may be associated with one or more objects of the SelectionProcess class configuring Selection Processes that process the observed packets in parallel. As long as an ObservationPoint object is specified without any references to SelectionProcess objects, the Observation Point is not deployed for traffic measurements. o The Selector class contains the configuration parameters of a Selector. An object of the Selector class may be referred to from multiple objects of the SelectionProcess class. o The SelectionProcess class contains the configuration parameters of a Selection Process, including an ordered sequence of references to objects of the Selector class. The referred Selector objects specify the type and parameters of the Selectors implemented by the Selection Process. The output of a Selection Process MAY be processed by further Selection Processes. Therefore, the SelectionProcess class enables references to other objects of the Selection Process class. A Selection Process MAY pass the stream of selected packets to one or multiple Caches. Therefore, the SelectionProcess class enables references to objects of the Cache class. A Selection Process MAY be configured without any reference to Selection Processes or Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 10] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Caches that receive the selected packets, which is useful for the configuration of standby processes. In this case, the selected packets are not accounted in any Packet Report or Flow Record. An SelectionProcess object MAY be referred to from multiple ObservationPoint and SelectionProcess objects. o The Cache class contains configuration parameters of a Cache. A Cache may receive the output of one or more Selection Processes and maintains the corresponding Packet Reports or Flow Records. Therefore, an object of the Cache class MAY be referred to from multiple SelectionProcess objects. Configuration parameters of the Cache class specify the size of the Cache, the Cache Type and Layout, and expiration parameters. The Cache Type determines if Packet Reports or Flow Records are generated. A Cache MAY pass its output to one or multiple Exporting Process. Therefore, the Cache class enables references to one or multiple objects of the ExportingProcess class. A Cache object without any reference to an ExportingProcess object represents a standby Cache. In this case, the Cache output is dropped. o The ExportingProcess class contains configuration parameters of an Exporting Process. It includes various transport protocol specific parameters and the export destinations. An object of the ExportingProcess class MAY be referred to from multiple objects of the Cache class. An Exporting Process MAY be configured as a File Writer according to [I-D.ietf-ipfix-file]. +------------------+ | ObservationPoint | +------------------+ 1 | | 0..* V +------------------+ 0..* 1..* +----------+ | SelectionProcess |----------->| Selector | +------------------+<-+ +----------+ 0..* | 0..* | | 0..* | +---+ 0..* V +------------------+ | Cache | +------------------+ 0..* | | 0..* V +------------------+ | ExportingProcess | +------------------+ Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 11] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Figure 3: Class diagram of Exporter configuration 4.3. Collector Configuration Figure 4 below shows the main classes of the configuration data model which are involved in the configuration of an IPFIX or PSAMP Collector. An object of the CollectingProcess class configures interfaces, transport protocols and port numbers of a Collecting Process using the Receiver class. Alternatively, the Collecting Process MAY be configured as a File Reader according to [I-D.ietf-ipfix-file]. In this case, the Receiver class MUST specify the corresponding file names. An object of the CollectingProcess class may refer to one or multiple ExportingProcess objects configuring Exporting Processes that reexport the received Data Records. As an example, an Exporting Process can be configured as a File Writer in order to save the received Data Records in a file. +-------------------+ 1..* +------------------+ | |<>----------| Receiver | | CollectingProcess | +------------------+ | | | | 0..* 0..* +------------------+ | |----------->| ExportingProcess | +-------------------+ +------------------+ Figure 4: Class diagram of Collector configuration 5. Configuration Parameters This section specifies the configuration parameters of the configuration data model separately for each class. Parameters serving as keys are depicted in brackets. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 12] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 5.1. ObservationPoint Class +---------------------+ | ObservationPoint | +---------------------+ 1 +--------------------+ | [name] |<>----------| Interface/Linecard | | observationPointId | +--------------------+ | observationDomainId | | | 0..* 0..* +--------------------+ | |----------->| SelectionProcess | +---------------------+ +--------------------+ +------------------+ +----------------------------------+ | Interface | | Linecard | +------------------+ +----------------------------------+ | ifIndex/ifName | | entPhysicalIndex/entPhysicalName | | direction | | direction | +------------------+ +----------------------------------+ Figure 5: ObservationPoint class The ObservationPoint class identifies an Observation Point of the monitoring device, which is either an interface or a linecard. An object of the ObservationPoint class MAY specify the Observation Domain ID as well as the Observation Point ID (i.e., the value of the Information Element observationPointId [RFC5102]). The configuration parameters to identify an interface or a linecard are as follows: ifIndex/ifName (interface only): Either the index or name of the interface MUST be specified according to corresponding objects in the IF-MIB [RFC2863]. entPhysicalIndex/entPhysicalName (linecard only): Either the index or name of the linecard MUST be specified according to corresponding objects in the ENTITY-MIB [RFC4133]. direction: This OPTIONAL parameter specifies if ingress traffic, egress traffic, or both ingress and egress traffic is captured. If not present, ingress and egress traffic is captured. If not applicable (e.g., in the case of a sniffing interface in promiscuous mode), the value of this parameter MUST be ignored. An ObservationPoint object MAY refer to one or multiple SelectionProcess objects configuring Selection Processes that process the observed packets in parallel. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 13] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 5.2. Selector Class +------------+ | Selector | +------------+ 1 +-----------------+ | [name] |<>------+ SelectAll/ | | selectorId | | SampCountBased/ | | | | SampTimeBased/ | | | | SampRandOutOfN/ | | | | SampUniProb/ | | | | SampNonUniProb/ | | | | SampFlowState/ | | | | FilterMatch/ | | | | FilterHash/ | | | | FilterRState | +------------+ +-----------------+ Figure 6: Selector class The Selector class contains the configuration parameters of a Selector. Standardized PSAMP sampling and filtering methods are described in [I-D.ietf-psamp-sample-tech]; their configuration parameters are specified in corresponding sampler (SampCountBased, SampTimeBased, SampRandOutOfN, SampUniProb, SampNonUniProb, SampFlowState) or filter (FilterMatch, FilterHash, FilterRState) classes. In addition, the SelectAll class, which has no parameters, is used for a Selector that selects all packets. The Selector class includes exactly one of these sampler and filter classes, depending on the applied method. An object of the Selector class MAY set the Selector ID (i.e., the value of the Information Element selectorId [I-D.ietf-psamp-info]). In this case, the configured Selector ID MUST be unique within the Observation Domains where the Selector is deployed. If not configured, the Selector ID is assigned by the monitoring device. An object of the Selector class MAY be referred to from multiple SelectionProcess objects. A Selection Process MAY refer multiple times to the same Selector object. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 14] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 5.2.1. Sampler Classes +----------------+ +----------------+ +----------------+ | SampCountBased | | SampTimeBased | | SampRandOutOfN | +----------------+ +----------------+ +----------------+ | interval | | interval | | population | | spacing | | spacing | | sample | +----------------+ +----------------+ +----------------+ +----------------+ +----------------+ +----------------+ | SampUniProb | | SampNonUniProb | | SampFlowState | +----------------+ +----------------+ +----------------+ | probability | | function | | func | | | | funcParam | | funcParam | +----------------+ +----------------+ +----------------+ Figure 7: Sampler classes The names and semantics of the configuration parameters correspond to the managed objects in the PSAMP MIB module [I-D.ietf-psamp-mib]. 5.2.2. Filter Classes +------------------+ +----------------+ +----------------+ | FilterMatch | | FilterHash | | FilterRState | +------------------+ +----------------+ +----------------+ | ieId/ieName | | addrType | | function | | enterpriseNumber | | headerBits | | negate | | startValue | | payloadBytes | | ifIndex | | stopValue | | payloadBits | | startAS | | mask | | function | | stopAS | | | | inputBits | | vendorFunc | | | | outputBits | | | | | | outputMask | | | | | | selection | | | +------------------+ +----------------+ +----------------+ Figure 8: Filter classes The names and semantics of the configuration parameters correspond to the managed objects in the PSAMP MIB module [I-D.ietf-psamp-mib]. In the case of the FilterMatch class, we deviate from the PSAMP MIB module and allow the specification of a field by either the ID or name of the Information Element. An enterprise number MAY be specified to define an enterprise-specific Information Element. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 15] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 5.3. SelectionProcess Class +---------------------+ | SelectionProcess | +---------------------+ 0..* 1..* +----------+ | [name] |----------->| Selector | | selectionSequenceId | +----------+ | | 0..* | |<---+ | | | | |----+ | | 0..* | | | | 0..* 0..* +----------+ | |----------->| Cache | +---------------------+ +----------+ Figure 9: SelectionProcess class The SelectionProcess class contains the configuration parameters of a Selection Process which selects packets from the input stream and outputs the selected packets to another Selection Process or a Cache. The Selectors implemented by the Selection Proess are defined in objects of the Selector class. The SelectionProcess class enables the specification of an ordered list of references to Selector objects. The actions defined by the Selector objects are applied to the stream of incoming packet in the specified order. A SelectionProcess object MUST refer to at least one Selector object. A SelectionProcess object MAY set the Selection Sequence ID (i.e., the value of the Information Element selectionSequenceId [I-D.ietf-psamp-info]). In this case, the configured Selection Sequence ID MUST be unique within the Observation Domain. If not configured, the Selection Sequence ID is assigned by the monitoring device. The output of one Selection Process MAY be processed by other Selection Processes. Therefore, the SelectionProcess class includes references to itself, meaning that one SelectionProcess object MAY refer to other SelectionProcess objects. A SelectionProcess object MAY include references to one or more objects of the Cache class configuring Caches that receive the selected packets and maintain the corresponding Packet Reports or Flow Records. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 16] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 5.4. Cache Class +---------------+ | Cache | +---------------+ 1 +-------------+ | [name] |<>----------| CacheLayout | | cacheType | +-------------+ | maxRecords | | activeTimeout | 0..* 0..* +------------------+ | idleTimeout |----------->| ExportingProcess | +---------------+ +------------------+ Figure 10: Cache class The Cache class contains the configuration parameters of a Cache. The configuration parameters of the Cache class are as follows: cacheType: Configures the Cache Type. The value of this parameter MUST be one of the following: * immediate: Records expire after the first packet * timeout: Records expire after active or idle timeout * permanent: Records never expire, but are periodically exported with interval set by the active timeout In the case of "immediate", PSAMP Packet Reports are generated. Otherwise, IPFIX Flow Records are generated. maxRecords: maximum number of records in the Cache. activeTimeout: timeout in timeticks (i.e., hundredths of a second) after which an active Flow is timed out anyway even if there is still a continuous flow of packets. idleTimeout: A Flow is considered to be timed out if no packets belonging to the Flow have been observed for the amount of time specified by this parameter. The unit is timeticks (i.e., hundredths of a second). The parameters activeTimeout and idleTimeout MUST be ignored if the Cache Type is "immediate". the parameter idleTimeout MUST be ignored if the Cache Type is "permanent". An object of the Cache class also specifies the Cache Layout that defines which fields are included in the Packet Reports or Flow Records. A Cache object MAY refer to one or multiple ExportingProcess objects configuring different Exporting Processes. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 17] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 5.4.1. CacheLayout Class +--------------+ | CacheLayout | +--------------+ 1..* +------------------+ | |<>------| Field | | | +------------------+ | | | [name] | | | | ieId/ieName | | | | ieLength | | | | enterpriseNumber | | | | isFlowKey | +--------------+ +------------------+ Figure 11: CacheLayout class A Cache maintains Packet Reports or Flow Records containing information that has been extracted from the incoming stream of packets. Using the Field class, the CacheLayout class specifies the superset of fields which are included in the Packet Reports or Flow Records maintained by the Cache. If Packet Reports are generated (i.e., Cache Type is "immediate"), all fields specified by the Cache Layout MUST be included in the resulting Packet Report unless the corresponding Information Element is not applicable or cannot be derived from the content or treatment of the incoming packet. If Flow Records are generated (i.e., Cache Type is "timeout" or "permanent"), all Flow Key fields specified by the Cache Layout MUST be included as Flow Key in the resulting Flow Record unless the corresponding Information Element is not applicable or cannot be derived from the content or treatment of the incoming packet. Two packets MUST NOT be accounted by the same Flow Record if different subsets of the Flow Key fields are applicable or derivable. All non- key fields specified by the Cache Layout MUST be included in the resulting Flow Record unless the corresponding Information Element is not applicable or cannot be derived for the given Flow. For example, if a Cache Layout field specifies an Information Element whose value is determined by the first packet observed within a Flow (which is the default rule according to [RFC5102]), this field MUST be included in the resulting Flow Record if it can be determined from the first packet of the Flow. The CacheLayout class does not have any parameters. The configuration parameters of the Field class are as follows: Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 18] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 ieId, ieName, ieLength, enterpriseNumber: These parameters specify a field by identifier, name, length, and enterprise number of an Information Element. Either ieId or ieName MUST be specified. ieLength MAY be omitted if a default length exists of the specified Information Element. If ieLength is set to 65535, the field is exported as variable-length Information Element. enterpriseNumber is only inserted for enterprise-specific Information Elements. isFlowKey: If present, this field is a Flow Key. 5.5. ExportingProcess Class +--------------------+ | ExportingProcess | +--------------------+ 0..* +-------------+ | [name] |<>------| Destination | | exportingProcessId | +-------------+ +--------------------+ Figure 12: ExportingProcess class The ExportingProcess class specifies a list of destinations to which the measurement data are exported. An object of the ExportingProcess class MAY set the Exporting Process ID (i.e., the value of the Information Element exportingProcessId [RFC5102]). 5.5.1. Destination Class +-----------------+ | Destination | +-----------------+ 1 +-----------------------+ | [name] |<>------| SctpExport/UdpExport/ | | type | | TcpExport/FileWriter | | | +-----------------------+ | | | | 0..* +-----------------------+ | |<>------| Option | +-----------------+ +-----------------------+ Figure 13: Destination class The Destination class contains the parameters of one export destination of an Exporting Process. The type parameter determines the Transport Session type ("primary", "secondary", "duplicate", "load balancing", or "unused") and corresponds to the ipfixTransportSessionGroupMemberType object in [I-D.ietf-ipfix-mib]. The Destination class contains further configuration parameters that are specific to the transport protocol used (SCTP, UDP, or TCP). Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 19] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Alternatively, the measurement data can be exported to a file as proposed in [I-D.ietf-ipfix-file]. An object of the Destination class MAY specify the report of additional information with Option Templates, using the Option class. 5.5.2. Export Parameters Classes +--------------------------+ +--------------------------+ | SctpExport | | TcpExport | +--------------------------+ +--------------------------+ | destinationIpAddress | | destinationIpAddress | | destinationTransportPort | | destinationTransportPort | | sourceIpAddress* | | sendBufferSize | | sendBufferSize | | rateLimit | | rateLimit | +--------------------------+ | timedReliability | | numberOfStreams | | orderedDelivery | +--------------------------+ +------------------------------+ +-------------+ | UdpExport | | FileWriter | +------------------------------+ +-------------+ | destinationIpAddress | | uri | | destinationTransportPort | +-------------+ | sourceIpAddress | | sendBufferSize | | rateLimit | | templateRefreshTimeout | | templateRefreshPacket | | optionTemplateRefreshTimeout | | optionTemplateRefreshPacket | +------------------------------+ Figure 14: Export parameters classes The export parameter classes SctpExport, TcpExport, UdpExport, and FileWriter specify configuration parameters that are specific to an export destination. The configuration parameters of the SctpExport, TcpExport, and UdpExport classes are: destinationIpAddress, destinationTransportPort: destination IP address and destination transport to be used for export with SCTP, UDP, or TCP. destinationIpAddress is a mandatory parameter. If destinationTransportPort is omitted, 4739 is used as port number. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 20] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 sendBufferSize: size of the socket send buffer in octets. rateLimit: maximum number of bytes per second the Exporting Process may export to the given destination (i.e., Collector). The number of bytes is calculated from the lengths of the IPFIX Messages exported. timedReliability (SctpExport only): lifetime in timeticks (i.e., hundredths of a second) until an IPFIX Message containing Data Sets only is "abandoned" due to the timed reliability mechanism of PR-SCTP [RFC3758]. If this parameter is omitted or set to zero, reliable SCTP transport is used. numberOfStreams (SctpExport only): number of outbound streams requested for SCTP associations [RFC4960]. orderedDelivery (SctpExport only): boolean parameter controlling the ordered delivery of IPFIX Messages containing Data Sets [RFC4960]. If this parameter is omitted, ordered delivery is enabled. sourceIpAddress (not in TcpExport): In the case of UdpExport, this optional parameter MAY appear once to set the source IP address. If this parameter is omitted, the address assigned to the outgoing interface is used. In the case of SctpExport, this optional parameter MAY appear multiple times to specify the list of eligible local IP addresses of the SCTP association [RFC4960]. If omitted, all locally assigned IP addresses are used by the SCTP endpoint. templateRefreshTimeout, templateRefreshPacket, optionTemplateRefreshTimeout, optionTemplateRefreshPacket (UdpExport only): Template refresh parameters when using UDP as transport protocol. templateRefreshTimeout and optionTemplateRefreshTimeout are specified in timeticks (i.e., hundredths of a second), templateRefreshPacket and optionTemplateRefreshPacket in number of IPFIX Messages between resendings of Templates. If the Exporting Process is configured as a File Writer, the FileWriter class MUST be used with the following parameter: uri: file name and location encoded as URI. 5.5.3. Option Class +-----------+ | Option | +-----------+ 0..1 +----------------+ | [name] |<>------| OptionTemplate | | type | +----------------+ | timeout | +-----------+ Figure 15: Option class Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 21] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 The Option class defines the type of additional information to be reported, such as statistics, flow keys, sampling and filtering parameters etc. [RFC5101] and [I-D.ietf-psamp-protocol] specify several types of reporting information which may be exported. The type MUST be one of the following: meteringStatistics: export of Metering Process statistics using the Metering Process Statistics Option Template [RFC5101]. meteringReliability: export of Metering Process reliability statistics using the Metering Process Reliability Statistics Option Template [RFC5101]. exportingReliability: export of Exporting Process reliability statistics using the Exporting Process Reliability Statistics Option Template [RFC5101]. flowKeys: export of the Flow Key specification using the Flow Keys Option Template [RFC5101]. selectionSequence: export of Selection Sequence and Selector Report Interpretation [I-D.ietf-psamp-protocol]. selectionStatistics: export of Selection Sequence Statistics Report Interpretation [I-D.ietf-psamp-protocol]. accuracy: export of Accuracy Report Interpretation [I-D.ietf-psamp-protocol]. reducingRedundancy: export of common properties according to [I-D.ietf-ipfix-reducing-redundancy]. The option type is a mandatory parameter. The Option Template MAY be configured, using the OptionTemplate class. If no Option Template is specified, the Exporter MUST choose a template definition automatically according to the option type and available option data. The timeout parameter specifies the reporting interval. If the timeout parameter is omitted or set to zero, the corresponding reporting information will be exported only once. Otherwise, the information is exported periodically. 5.5.4. OptionTemplate Class Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 22] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 +----------------+ | OptionTemplate | +----------------+ 0..* +------------------+ | |<>------| OptionField | | | +------------------+ | | | [name] | | | | ieId/ieName | | | | ieLength | | | | enterpriseNumber | | | | isScope | +----------------+ +------------------+ Figure 16: OptionTemplate class The Option Template class specifies the fields of an Option Template using the OptionField class. The configuration parameters of the OptionField class are the same as for the Field class (see Section 5.4.1). If the additional parameter isScope is present, the field is a scope field. 5.6. CollectingProcess Class and Receiver Class +-------------------+ | CollectingProcess | +-------------------+ | [name] | 1..* +-------------+ | |<>------| Receiver | +---------------+ | | +-------------+ 1 | SctpReceiver/ | | | | [name] |<>----| UdpReceiver/ | | | +-------------+ | TcpReceiver/ | | | | FileReader | | | +---------------+ | | | | 0..* 0..* +------------------+ | |----------->| ExportingProcess | +-------------------+ +------------------+ Figure 17: CollectingProcess class and Receiver class The CollectingProcess class contains one or multiple receivers specified with the Receiver class. The Receiver class contains further configuration parameters that are specific to the transport protocol used (SCTP, UDP, or TCP). These parameters are provided by the receiver parameter classes SctpReceiver, UdpReceiver, and TcpReceiver classes. The Collecting Process can also be configured as a File Reader using the FileReader class. An CollectingProcess object MAY refer to one or multiple Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 23] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 ExportingProcess objects configuring Exporting Processes that export the received Data Records without modifications to a file or to another Collector. 5.6.1. Receiver Parameters Classes +-------------------+ +----------------+ | SctpReceiver | | TcpReceiver | +-------------------+ +----------------+ | ipAddress* | | ipAddress | | transportPort | | transportPort | | maxAllowedStreams | +----------------+ +-------------------+ +-------------------------+ +------------+ | UdpReceiver | | FileReader | +-------------------------+ +------------+ | ipAddress | | uri | | transportPort | +------------+ | defaultTemplateLifetime | +-------------------------+ Figure 18: Receiver parameters classes The receiver parameter classes SctpReceiver, UdpReceiver, and TcpReceiver specify configuration parameters that are specific to the transport protocol SCTP, UDP, and TCP: ipAddress, transportPort: IP address and port number of the receiving port. If ipAddress is omitted, the Collecting Process receives data sent to any local IP address. In the case of SctpReceiver, multiple IP addresses MAY be specified as a list of eligible local IP addresses to be used for the local SCTP endpoint [RFC4960]. defaultTemplateLifetime (UdpReceiver only): default template lifetime if UDP is used as transport protocol. maxAllowedStreams (SctpReceiver only): maximum number of allowed inbound streams per SCTP association. Instead of receiving records from the network, it is possible to import them from a file in which they have been saved as proposed in [I-D.ietf-ipfix-file]. In this case, the FileReader class MUST be used with the following parameter: Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 24] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 uri: file name and location encoded as URI. 6. YANG Module of the IPFIX/PSAMP Configuration Data Model The YANG module specification of the configuration data model is specified as follows: module ipfix-psamp { namespace "urn:ietf:params:xml:ns:ipfix-psamp-config"; prefix ipfix; import yang-types { prefix yang; } import inet-types { prefix inet; } import IF-MIB { prefix if; } import ENTITY-MIB { prefix ent; } organization "IPFIX WG"; contact "muenz@net.in.tum.de"; description "IPFIX/PSAMP Configuration Data Model"; revision 2008-11-03 { description "Version of draft-ietf-ipfix-configuration-model-01 Changes in draft-ietf-ipfix-configuration-model-01: - separation of Selectors and Selection Processes as in PSAMP documents - parameter modifications in filterMatch - new rateLimit parameter in destinations of Exporting Process - Cache Type 'normal' now called 'timeout' Changes in draft-ietf-ipfix-configuration-model-00: - Metering Process container replaced by direct reference to Selection Process - concatenation of Selection Processes realize Selection Sequence - removal of premature support of IPFIX Mediators/Concentrators. - more SCTP parameters in SctpReceiver and SctpExport classes - sendBufferSize parameter for all *Export classes - templateId no longer configuration parameter Changes in draft-muenz-ipfix-configuration-04: - first version in yang - Collecting Process can be configured for file import - Collecting Process can be configured to export received records without modifications (e.g., to file or other collectors) - SCTP export parameter timedReliability - parameter for eligible local IP addresses for SCTP endpoint - all tags names uncapitalized, types names etc. capitalized Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 25] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 - CacheParameters renamed as Cache - description attribute removed Changes in -03: - Linecard and Interface classes now have direction element - sec => s (SI unit) - optional description attribute for annotations - simplifications in ExportingProcess class - new parameters: observationPointId, meteringProcessId, selectorId, exportingProcessId (note that devices do not have to support the configuration of these parameters) - new FileExport class for exporting into a file - Reporting class renamed Option Class Changes in -02: - new structure without next pointers - packet reporting and flow metering replaced by record cache - added reporting with options"; } grouping InformationElement { description "Parameters of an Information Element."; choice NameOrId { mandatory true; leaf ieName { type string; } leaf ieId { type uint16; } } leaf ieLength { description "Length can be omitted if a default length exists for the specified Information Element. A value of 65535 specifies a variable-length Information Element."; type uint16; } leaf ieEnterpriseNumber { description "Omitted in the case of an IETF specified Information Element."; type uint32; } } typedef Direction { description "Direction of packets going through an interface or Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 26] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 linecard."; type enumeration { enum ingress; enum egress; enum both; } } grouping Interface { description "Interface as input to Observation Point."; choice IndexOrName { description "Index or name of the interface as stored in the ifTable of IF-MIB."; reference "RFC 1229."; mandatory true; leaf ifIndex { type uint32; } leaf ifName { type string; } } leaf direction { description "Direction of packets. If not applicable (e.g., in the case of a sniffing interface in promiscuous mode), this parameter is omitted"; type Direction; default both; } } grouping Linecard { description "Linecard as input to Observation Point."; choice IndexOrName { description "Index or name of the linecard as stored in the entPhysicalTable of ENTITY-MIB."; reference "RFC 4133."; mandatory true; leaf entPhysicalIndex { type uint32; } leaf entPhysicalName { type string; } } leaf direction { description "Direction of packets. If not applicable (e.g., in the case of a sniffing interface in promiscuous mode), this parameter is omitted"; type Direction; default both; Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 27] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 } } container ipfix { list collectingProcess { description "Parameters of a Collecting Process."; key name; leaf name { description "Arbitrary but unique name of the Collecting Process."; type string; } list receiver { description "Receiver parameters."; key name; leaf name { type string; } choice TransportProtocol { mandatory true; container sctpReceiver { description "SCTP receiver parameters."; reference "RFC 4960."; leaf-list ipAddress { description "List of eligible local IP addresses to be used by the SCTP endpoint. If omitted, all locally assigned IP addresses are used by the SCTP endpoint."; type inet:ip-address; } leaf transportPort { mandatory true; type inet:port-number; } leaf maxAllowedStreams { description "Maximum number of allowed inbound streams per SCTP association."; type uint16; } } container udpReceiver { description "UDP receiver parameters."; leaf ipAddress { description "If omitted, all locally assigned IP addresses are used by the UDP endpoint."; type inet:ip-address; Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 28] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 } leaf transportPort { mandatory true; type inet:port-number; } leaf defaultTemplateLifetime { type uint32; } } container tcpReceiver { description "TCP receiver parameters."; leaf ipAddress { description "If omitted, all locally assigned IP addresses are used by the TCP endpoint."; type inet:ip-address; } leaf transportPort { mandatory true; type inet:port-number; } } container fileReader { description "File Reader parameters."; leaf uri { mandatory true; type yang:uri; } } } } leaf-list exportingProcess { description "Export of received records without any modifications. Records are processed by all Exporting Processes in the list."; type keyref { path "/ipfix/exportingProcess/name"; } } } list observationPoint { description "Parameters of an Observation Point."; key name; leaf name { description "Arbitrary but unique name of the Observation Point."; type string; } leaf observationPointId { Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 29] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 description "If omitted, the Observation Point ID is assigned by the monitoring device."; type uint32; } leaf observationDomainId { description "If omitted, the Observation Domain ID is assigned by the monitoring device."; type uint32; } choice OPType { mandatory true; container interface { uses Interface; } container linecard { uses Linecard; } } leaf-list selectionProcess { description "Selection Processes in this list process packets in parallel."; type keyref { path "/ipfix/selectionProcess/name"; } } } list selector { description "Parameters of a Selector."; key name; leaf name { description "Arbitrary but unique name of the Selector."; type string; } leaf selectorId { description "If omitted, the Selector ID is assigned by the monitoring device."; type uint16; } choice Method { description "See PSAMP-MIB for details about the selection methods and their parameters."; reference "draft-ietf-psamp-mib-06."; mandatory true; leaf selectAll { type empty; } container sampCountBased { leaf interval { type uint32; } Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 30] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 leaf spacing { type uint32; } } container sampTimeBased { leaf interval { type uint32; } leaf spacing { type uint32; } } container sampRandOutOfN { leaf population { type uint32; } leaf sample { type uint32; } } container sampUniProb { leaf probability { description "The given value must be divided by 4294967295."; type uint32; } } container sampNonUniProb { description "In PSAMP-MIB, these are OIDs."; leaf function { type string; } leaf funcParam { type string; } } container sampFlowState { description "In PSAMP-MIB, these are OIDs."; leaf function { type string; } leaf funcParam { type string; } } container filterMatch { choice NameOrId { description "Deviating from the PSAMP MIB, the field is specified by either the name or the ID of the Information Element."; mandatory true; leaf ieName { type string; } leaf ieId { type uint16; } } leaf ieEnterpriseNumber { description "Deviating from the PSAMP MIB, an enterprise number may be specified to refer to an enterprise-specific Information Element."; type uint32; } leaf startValue { type string; } leaf stopValue { type string; } leaf mask { type string; } Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 31] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 } container filterHash { description "In PSAMP-MIB, function and funcParam are OIDs."; leaf addrType { type inet:ip-version; } leaf headerBits { type string; } leaf payloadBytes { type uint32; } leaf payloadBits { type string; } leaf function { type string; } leaf funcParam { type string; } leaf inputBits { type uint32; } leaf outputBits { type uint32; } leaf outputMask { type string; } leaf selection { type string; } } container filterRState { description "In PSAMP-MIB, vendorFunc is OID."; leaf function { type int32; } leaf negate { type boolean; } leaf ifIndex { description "Index of the interface as stored in the ifTable of IF-MIB."; reference "RFC 2863."; type uint32; } leaf startAS { type inet:asn; } leaf stopAS { type inet:asn; } leaf vendorFunc { type string; } } } } list selectionProcess { description "Parameters of a Selection Process."; key name; leaf name { description "Arbitrary but unique name of the Selection Process."; type string; } leaf selectionSequenceId { description "If omitted, the Selection Sequence ID is assigned by the monitoring device."; type uint64; } leaf-list selector { Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 32] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 description "List of Selectors that define the action of the Selection Process on a single packet. The Selectors are serially invoked in the same order as they appear in this list."; min-elements 1; ordered-by user; type keyref { path "/ipfix/selector/name"; } } leaf-list selectionProcess { description "A Selection Process may pass selected packets to further Selection Processes."; type keyref { path "/ipfix/selectionProcess/name"; } } leaf-list cache { description "Caches in this list receive the selected packets in parallel."; type keyref { path "/ipfix/cache/name"; } } } list cache { description "Parameters of a Cache."; key name; leaf name { description "Arbitrary but unique name of the Cache."; type string; } leaf cacheType { mandatory true; type enumeration { enum immediate { description "Flow expiration after the first packet, generation of Packet Records."; } enum timeout { description "Flow expiration after active and idle timeout, generation of Flow Records."; } enum permanent { description "No flow expiration, periodical export after active timeout, generation of Flow Records."; } } } Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 33] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 leaf maxRecords { type uint32; } leaf activeTimeout { type yang:timeticks; } leaf idleTimeout { type yang:timeticks; } container cacheLayout { list field { min-elements 1; key name; leaf name { type string; } uses InformationElement; leaf isFlowKey { type empty; } } } leaf-list exportingProcess { description "Records are exported by all Exporting Processes in the list."; type keyref { path "/ipfix/exportingProcess/name"; } } } list exportingProcess { description "Parameters of an Exporting Process."; key name; leaf name { description "Arbitrary but unique name of the Exporting Process."; type string; } leaf exportingProcessId { description "If omitted, the Exporting Process ID is assigned by the monitoring device."; type uint32; } list destination { key name; leaf name { type string; } leaf type { description "Transport Session type according to IPFIX-MIB"; reference "draft-ietf-ipfix-mib-02."; type enumeration { Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 34] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 enum primary; enum secondary; enum duplicate; enum loadBalancing; enum unused; } } choice TransportProtocol { mandatory true; container sctpExport { description "SCTP export parameters."; reference "RFC 3758, RFC 4960."; leaf destinationIpAddress { mandatory true; type inet:ip-address; } leaf destinationTransportPort { type inet:port-number; default 4739; } leaf-list sourceIpAddress { description "List of eligible local IP addresses to be used by the SCTP endpoint. If omitted, all locally assigned IP addresses are used by the local endpoint."; type inet:ip-address; } leaf sendBufferSize { type uint32; } leaf rateLimit { description "Maximum number of bytes per second the Exporting Process may export to the given destination. The number of bytes is calculated from the lengths of the IPFIX Messages exported."; reference "draft-ietf-psamp-protocol-09, section 6.3."; type uint32; } leaf timedReliability { description "PR-SCTP lifetime for IPFIX Messages containing Data Sets only."; type yang:timeticks; default 0; } leaf numberOfStreams { description "Number of outbound streams requested for the SCTP association."; type uint16; } leaf orderedDelivery { Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 35] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 description "Ordered delivery of IPFIX Messages containing Data Sets."; type boolean; default "true"; } } container udpExport { description "UDP export parameters."; leaf destinationIpAddress { mandatory true; type inet:ip-address; } leaf destinationTransportPort { type inet:port-number; default 4739; } leaf sourceIpAddress { description "Source IP address. If omitted, the address assigned to the outgoing interface is used."; type inet:ip-address; } leaf sendBufferSize { type uint32; } leaf rateLimit { description "Maximum number of bytes per second the Exporting Process may export to the given destination. The number of bytes is calculated from the lengths of the IPFIX Messages exported."; reference "draft-ietf-psamp-protocol-09, section 6.3."; type uint32; } leaf templateRefreshTimeout { type yang:timeticks; } leaf templateRefreshPacket { type uint32; } leaf optionTemplateRefreshTimeout { type yang:timeticks; } leaf optionTemplateRefreshPacket { type uint32; } } container tcpExport { description "TCP export parameters."; leaf destinationIpAddress { mandatory true; type inet:ip-address; } leaf destinationTransportPort { type inet:port-number; default 4739; } leaf sendBufferSize { type uint32; } leaf rateLimit { description "Maximum number of bytes per second the Exporting Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 36] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Process may export to the given destination. The number of bytes is calculated from the lengths of the IPFIX Messages exported."; reference "draft-ietf-psamp-protocol-09, section 6.3."; type uint32; } } container fileWriter { description "File Writer parameters."; leaf uri { mandatory true; type yang:uri; } } } list option { key name; leaf name { type string; } leaf type { mandatory true; type enumeration { enum "meteringStatistics" { description "Metering Process Statistics."; reference "RFC 5101, section 4.1."; } enum "meteringReliability" { description "Metering Process Reliability Statistics."; reference "RFC 5101, section 4.2."; } enum "exportingReliability" { description "Exporting Process Reliability Statistics."; reference "RFC 5101, section 4.3."; } enum "flowKeys" { description "Flow Keys."; reference "RFC 5101, section 4.4."; } enum "selectionSequence" { description "Selection Sequence and Selector Reports."; reference "draft-ietf-psamp-protocol-09, section 6.5.1 and 6.5.2."; } enum "selectionStatistics" { description "Selection Sequence Statistics Report."; reference "draft-ietf-psamp-protocol-09, section 6.5.3."; Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 37] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 } enum "accuracy" { description "Accuracy Report."; reference "draft-ietf-psamp-protocol-09, section 6.5.4."; } enum "reducingRedundancy" { description "Application of ipfix-reducing-redundancy."; reference "draft-ietf-ipfix-reducing-redundancy-04"; } } } leaf timeout { description "Time interval for exporting option data."; type yang:timeticks; default 0; } container optionTemplate { description "If no Option Template is specified, the Exporter defines a template according to option type and available option data."; presence "If present, the Exporter is to use this Option Template to export the option data."; list optionField { key name; ordered-by user; leaf name { type string; } uses InformationElement; leaf isScope { type empty; } } } } } } } } 7. Examples This section shows example configurations conforming to the YANG module specified in Section 6. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 38] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 7.1. PSAMP Device This example shows two Selection Processes configured for the same Observation Point. The first Selection Process implements two Selectors: a filter for UDP packets and a random sampler. The second Selection Process implements an ICMP filter. The outputs of both Selection Processes enter the same Cache. The Cache Type is "immediate" resulting in the creation of a PSAMP Packet Report for every single packet. The associated Exporting Process exports to one Collector using PR-SCTP. As the destination transport port is omitted, the standard IPFIX port 4739 is used. Exporting Process reliability statistics are reported using a configured Option Template. OP at linecard 3 1 12345 3 Sampled UDP packets ICMP packets UDP filter 1 4 17 17 ICMP filter 2 4 1 1 Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 39] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 10-out-of-100 sampler 3 100 10 Sampled UDP packets 1 UDP filter 10-out-of-100 sampler PSAMP cache ICMP packets 2 ICMP filter PSAMP cache PSAMP cache immediate 512 Field 1 313 64 Field 2 154 The only exporter The only exporter 1 PR-SCTP collector primary Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 40] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 192.0.2.1 1000000 500 1 7.2. IPFIX Device This example demonstrates the shared usage of a Cache for maintaining Flow Records from two different Observation Points. Packets are selected using different sampling techniques. The Exporting Process sends the Flow Records to a primary destination using SCTP. A UDP Collector is specified as secondary, i.e. backup destination. Exporting Process reliability statistics are reported to the SCTP Collector, Selection Sequence and Selector Report Interpretation to both SCTP and UDP Collector. OP at eth0 (ingress) 12345 eth0 ingress Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 41] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Count-based packet selection OP at eth1 12346 eth1 All packet selection Count-based sampler 1 99 Select all Count-based packet selection Count-based sampler Flow cache All packet selection Select all Flow cache Flow cache timeout 4096 500 1000 Field 1 sourceIPv4Address Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 42] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Field 2 destinationIPv4Address Field 3 transportProtocol Field 4 sourceTransportPort Field 5 destinationTransportPort Field 6 flowStartMilliSeconds Field 7 flowEndSeconds Field 8 octetDeltaCount Field 9 packetDeltaCount SCTP export with UDP backup SCTP export with UDP backup SCTP destination primary Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 43] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 192.0.2.1 4739 true UDP destination secondary 192.0.2.2 4739 127.0.0.1 6000 6000 7.3. Export of Flow Records and Packet Reports This example demonstrates the combined export of Flow Records and Packet Reports for a single Observation Point. A Selection Process applies random sampling to the stream of packets. The output is passed to a Cache maintaining Flow Records. In addition, the output is passed to a second Selection Process which discards all non-ICMP packets. A second Cache generates Packet Reports of the retained ICMP packets. The output of both caches is exported to a single Collector using SCTP. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 44] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 OP at linecard 3 3 Sampling ICMP filter 4 1 1 Random sampler 4294967 Sampling Random sampler ICMP IPFIX cache ICMP ICMP filter Packet cache Flow cache timeout 4096 500 1000 Field 1 Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 45] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 sourceIPv4Address Field 2 destinationIPv4Address Field 6 flowStartMilliSeconds Field 7 flowEndSeconds Field 8 octetDeltaCount Field 9 packetDeltaCount Export Packet cache immediate 512 Field 1 313 64 Field 2 154 Export Export Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 46] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 SCTP collector 192.0.2.1 0 2 The following modifications lead to a similar but not identical configuration: ... OP at linecard 3 3 Sampling Sampled ICMP packets ... Sampling Random sampler IPFIX cache Sampled ICMP packets Random sampler ICMP filter Packet cache ... In this case, the random sampler is implemented in two different Selection Processes, leading to different sets of selected packets. As a consequence, the set of packets accounted in the Flow Cache is not identical to the set of packets from which the ICMP Packet Reports are generated. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 47] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 7.4. Collector and File Writer This example configures a Collector which writes the received Flow Records to a file. SCTP collector Listening port 4739 192.0.2.1 4739 64 File writer File writer File destination primary file://tmp/collected-records.ipfix 8. Security Considerations The IPFIX/PSAMP configuration data model does not introduce security issues. Configuration data encoded according to the configuration data model may contain sensitive information. Therefore, if configuration data is transmitted, the underlying protocol must apply appropriate procedures to guarantee the integrity and confidentiality of the data. Particularly, if the NETCONF protocol is used to configure IPFIX and PSAMP compliant monitoring devices, the security considerations of the NETCONF protocol apply [RFC4741]. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 48] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Appendix A. Acknowledgements The authors thank Martin Bjorklund for helping specifying the configuration data model in YANG. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC5101] Claise, B., "Specification of the IP Flow Information Export (IPFIX) Protocol for the Exchange of IP Traffic Flow Information", RFC 5101, January 2008. [RFC5102] Quittek, J., Bryant, S., Claise, B., Aitken, P., and J. Meyer, "Information Model for IP Flow Information Export", RFC 5102, January 2008. [I-D.ietf-psamp-protocol] Claise, B., "Packet Sampling (PSAMP) Protocol Specifications", draft-ietf-psamp-protocol-09 (work in progress), December 2007. [I-D.ietf-psamp-info] Dietz, T., Claise, B., Aitken, P., Dressler, F., and G. Carle, "Information Model for Packet Sampling Exports", draft-ietf-psamp-info-11 (work in progress), October 2008. [W3C.REC-xml-20040204] Paoli, J., Maler, E., Sperberg-McQueen, C., Yergeau, F., and T. Bray, "Extensible Markup Language (XML) 1.0 (Third Edition)", World Wide Web Consortium FirstEdition REC-xml- 20040204, February 2004, . [I-D.ietf-netmod-yang] Bjorklund, M., "YANG - A data modeling language for NETCONF", draft-ietf-netmod-yang-01 (work in progress), August 2008. [I-D.ietf-netmod-yang-types] Schoenwaelder, J., "Common YANG Data Types", draft-ietf-netmod-yang-types-00 (work in progress), September 2008. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 49] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 [UML] "OMG Unified Modeling Language (OMG UML), Superstructure, V2.1.2", OMG formal/2007-11-02, November 2007. 9.2. Informative References [W3C.REC-xmlschema-0-20041028] Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-0-20041028, October 2004, . [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [W3C.REC-soap12-part1-20070427] Karmarkar, A., Mendelsohn, N., Lafon, Y., Nielsen, H., Hadley, M., Gudgin, M., and J. Moreau, "SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)", World Wide Web Consortium Recommendation REC-soap12-part1-20070427, April 2007, . [I-D.ietf-ipfix-as] Zseby, T., "IPFIX Applicability", draft-ietf-ipfix-as-12 (work in progress), July 2007. [I-D.ietf-ipfix-architecture] Sadasivan, G., "Architecture for IP Flow Information Export", draft-ietf-ipfix-architecture-12 (work in progress), September 2006. [I-D.ietf-ipfix-mib] Dietz, T., Kobayashi, A., and B. Claise, "Definitions of Managed Objects for IP Flow Information Export", draft-ietf-ipfix-mib-04 (work in progress), July 2008. [I-D.ietf-ipfix-file] Trammell, B., Boschi, E., Mark, L., Zseby, T., and A. Wagner, "Specification of the IPFIX File Format", draft-ietf-ipfix-file-03 (work in progress), October 2008. [I-D.ietf-ipfix-reducing-redundancy] Boschi, E., "Reducing Redundancy in IP Flow Information Export (IPFIX) and Packet Sampling (PSAMP) Reports", draft-ietf-ipfix-reducing-redundancy-04 (work in progress), May 2007. [RFC3917] Quittek, J., Zseby, T., Claise, B., and S. Zander, Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 50] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 "Requirements for IP Flow Information Export (IPFIX)", RFC 3917, October 2004. [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. Conrad, "Stream Control Transmission Protocol (SCTP) Partial Reliability Extension", RFC 3758, May 2004. [RFC4960] Stewart, R., "Stream Control Transmission Protocol", RFC 4960, September 2007. [I-D.ietf-psamp-framework] Chiou, D., Claise, B., Duffield, N., Greenberg, A., Grossglauser, M., Rexford, J., and S. Goldberg, "A Framework for Packet Selection and Reporting", draft-ietf-psamp-framework-13 (work in progress), June 2008. [I-D.ietf-psamp-mib] Dietz, T. and B. Claise, "Definitions of Managed Objects for Packet Sampling", draft-ietf-psamp-mib-06 (work in progress), June 2006. [I-D.ietf-psamp-sample-tech] Zseby, T., "Sampling and Filtering Techniques for IP Packet Selection", draft-ietf-psamp-sample-tech-11 (work in progress), July 2008. [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB", RFC 2863, June 2000. [RFC4133] Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)", RFC 4133, August 2005. [YANG-WEB] Bjoerklund, M., "YANG WebHome", Homepage http://www.yang-central.org, November 2008. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 51] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Authors' Addresses Gerhard Muenz Technische Universitaet Muenchen Department of Informatics Chair for Network Architectures and Services (I8) Boltzmannstr. 3 Garching D-85748 DE Phone: +49 89 289-18008 Email: muenz@net.in.tum.de URI: http://www.net.in.tum.de/~muenz Benoit Claise Cisco Systems, Inc. De Kleetlaan 6a b1 Diegem 1831 BE Phone: +32 2 704 5622 Email: bclaise@cisco.com Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 52] Internet-Draft IPFIX/PSAMP Configuration Data Model November 2008 Full Copyright Statement Copyright (C) The IETF Trust (2008). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Muenz & Claise draft-ietf-ipfix-configuration-model-01.txt [Page 53]