A Lightweight Textual Format for IPFIX Information Models and Templates
draft-trammell-ipfix-text-iespec-00.txt

Abstract

This document describes a lightweight textual format for describing IPFIX Information Models, IPFIX Templates, and IPFIX Options Templates, designed for easy human readability and writability, and fast, easily implemented and deployed parsing and generation.

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). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

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

This Internet-Draft will expire on October 18, 2010.

Copyright Notice

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

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.

1.  Introduction

The IP Flow Information Export Protocol (IPFIX) [RFC5101] (Claise, B., “Specification of the IP Flow Information Export (IPFIX) Protocol for the Exchange of IP Traffic Flow Information,” January 2008.) affords new levels of flexibility in defining Data Record formats through its Template mechanism, and new Information Elements via an IANA registry (Internet Assigned Numbers Authority, “IP Flow Information Export Information Elements (http://www.iana.org/assignments/ipfix/ipfix.xml),” .) [iana‑ipfix‑assignments], enterprise-specific Information Elements, and inline information model export as defined in [RFC5610] (Boschi, E., Trammell, B., Mark, L., and T. Zseby, “Exporting Type Information for IP Flow Information Export (IPFIX) Information Elements,” July 2009.). However, XML representations of Information Elements as in the IANA registry (Internet Assigned Numbers Authority, “IP Flow Information Export Information Elements (http://www.iana.org/assignments/ipfix/ipfix.xml),” .) [iana‑ipfix‑assignments] require the inclusion of an XML parser in each IPFIX Exporting and Collecting Process for use at runtime, require transformation via XSLT (as used by IANA) in order to become human-readable, and are not particularly easily human-writiable. IPFIX Templates and Type Information Export as in [RFC5610] (Boschi, E., Trammell, B., Mark, L., and T. Zseby, “Exporting Type Information for IP Flow Information Export (IPFIX) Information Elements,” July 2009.) are excellent for runtime, but not particularly human-readable.

This document proposes a simple textual syntax for describing IPFIX Information Elements and IPFIX Templates, with human readability, human writability, compactness, and ease of parser/generator implementation without requiring external XML support as design goals. It is intended both for use in human communication (e.g., in new Internet-Drafts containing higher-level descriptions of IPFIX Templates, or describing sets of new IPFIX Information Elements for supporting new applications of the protocol) as well as at runtime by IPFIX implementations.

2.  Terminology

Terms used in this document that are defined in the Terminology section of the IPFIX Protocol (Claise, B., “Specification of the IP Flow Information Export (IPFIX) Protocol for the Exchange of IP Traffic Flow Information,” January 2008.) [RFC5101] document are to be interpreted as defined there. In addition, the following terms used in this document are defined as follows:

textual Information Element specifier (IESpec):

A string representing the four important aspects of an Information Element within the Information Model or within a Template: its name, its number (with Private Enterprise Number if applicable), its data type, and its length.

fully-qualified IESpec:

An IESpec as above, containing enough information to define an information element: at least a name, number, and type, and a length for types without a native length. IESpecs must be fully qualified to be of used in defining an Information Model or extensions thereto.

partial IESpec:

An IESpec that is not fully qualified.

Note that when the term Template is used in this document, it applies both to Templates and Options Templates as defined in [RFC5101] (Claise, B., “Specification of the IP Flow Information Export (IPFIX) Protocol for the Exchange of IP Traffic Flow Information,” January 2008.), unless otherwise noted.

3.  Information Element Specifier Syntax

The basis of this format is the textual Information Element Specifier, or IESpec. An IESpec contains each of the four important aspects of an Information Element: its name, its number, its type, and its size, separated by simple markup based on various types of brackets. Fully-qualified IESpecs may be used to specify existing or new Information Elements within an Information Model, while either fully-qualified or partial IESpecs may be used to define fields in a Template.

Each aspect of information associated with an Information Element is associated with a type of brackets. Bare words are used for Information Element names, () parentheses for Information Element numbers, <> angles for Information Element data types, and [] square brackets for Information Element sizes. {} Curly braces are reserved for optional and contextual use, described later in the document.

The basic form of a fully-qualified IESpec for an IANA-registered Information Element is as follows:

name(number)<type>[size]

where 'name' is the name of the Information Element in UTF-8, 'number' is the Information Element as a decimal integer, 'type' is the name of the data type as in the IANA informationElementDataTypes registry (Internet Assigned Numbers Authority, “IP Flow Information Export Information Elements (http://www.iana.org/assignments/ipfix/ipfix.xml),” .) [iana‑ipfix‑assignments], and 'size' is the length of the Information Element in octets as a decimal integer, where 65535 or the string 'v' signifies a variable-length Information Element. [size] may be omitted; in this case, the data type's native or default size is assumed (see section Section 3.1 (Native Sizes of Data Types).

The basic form of a fully-qualified IESpec for an enterprise-specific Information Element is as follows:

name(pen/number)<type>[size]

where 'pen' is the Private Enterprise Number as a decimal integer.

A fully-qualified IESpec is intended to give the implementation consuming it enough information about an Information Element to decode and display Data Records defined by Templates containing that Information Element. Range, unit, semantic, and description information, as in [RFC5610] (Boschi, E., Trammell, B., Mark, L., and T. Zseby, “Exporting Type Information for IP Flow Information Export (IPFIX) Information Elements,” July 2009.), is not supported by this syntax.

Example fully-qualified IESpecs follow:

• octetDeltaCount(1)<unsigned64>[8]
• octetDeltaCount(1)<unsigned64> (unsigned64 is natively 8 octets long)
• sourceIPv4Address(8)<ipv4Address>
• wlanSSID(146)<string>[v]
• sipRequestURI(35566/403)<string>[65535]

A partial IESpec is any IESpec that is not fully-qualified; these are useful when defining templates, or in other contexts in which the implementation already has an Information Model. A partial IESpec is assumed to take missing values from its Information Model (or, conceptually, from fully-qualified IESpecs which it matches). At minimum, a partial IESpec must contain a name, or a number. Any name, number, or type information given with a partial IESpec must match the values given in the Information Model; however, size information in a partial IESpec overrides size information in the Information Model; in this way, IESpecs can be used to express reduced-length encoding for Information Elements.

Example partial IESpecs follow:

• octetDeltaCount
• octetDeltaCount[4] (reduced-length encoding)
• (1)
• (1)[4] (reduced length encoding; note that this is exactly equivalent to an Information Element specifier in a Template)

3.1.  Native Sizes of Data Types

If absent in a fully-qualified IESpec, the size is assumed to be the native or default size for the type, as follows:

4.  Defining an Information Model from IESpecs

An Information Model, or an extension thereto (e.g., a set of enterprise-specific Information Elements supplied to a Collector to provide type information for information from a particular Exporter in the absence of support for [RFC5610] (Boschi, E., Trammell, B., Mark, L., and T. Zseby, “Exporting Type Information for IP Flow Information Export (IPFIX) Information Elements,” July 2009.); or a set of new Information Elements compactly presented in an Internet-Draft describing a new IPFIX application) can be expressed simply as a newline-separated list of fully-qualified IESpecs.

5.  Defining a Template or Options Template from IESpecs

A Template or Options Template can be expressed simply as an ordered newline-separated list of partial or fully-qualified IESpecs. IESpecs representing Scope Information Elements in an Options Template take the {scope} option as a suffix to the IESpec, e.g.:

sourceIPv4Address{scope}

A syntax for an encapsulation of templates (including e.g. template ID) is not yet defined.

6.  Security Considerations

Any IPFIX implementation using externally-provided strings to define Information Models and Templates must perform validation on those strings to ensure safe operation, and ensure that parsers for these strings are not vulnerable to common faults (e.g. buffer overflows); further guidance is implementation and platform specific.

7.  IANA Considerations

This document has no actions for IANA.

8. Normative References

Author's Address