One document matched: draft-trammell-ipfix-text-iespec-01.txt
Differences from draft-trammell-ipfix-text-iespec-00.txt
IPFIX Working Group B. Trammell
Internet-Draft ETH Zurich
Intended status: Informational August 5, 2010
Expires: February 6, 2011
A Lightweight Textual Format for IPFIX Information Models and Templates
draft-trammell-ipfix-text-iespec-01.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 February 6, 2011.
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.
Trammell Expires February 6, 2011 [Page 1]
Internet-Draft IPFIX IEspec August 2010
1. Introduction
The IP Flow Information Export Protocol (IPFIX) [RFC5101] affords new
levels of flexibility in defining Data Record formats through its
Template mechanism, and new Information Elements via an IANA registry
[iana-ipfix-assignments], enterprise-specific Information Elements,
and inline information model export as defined in [RFC5610].
However, XML representations of Information Elements as in the IANA
registry [iana-ipfix-assignments] require transformation via XSLT (as
used by IANA) in order to become human-readable, are not particularly
easily human-writiable, and would require the inclusion of an XML
parser in each IPFIX Exporting and Collecting Process for use at
runtime. IPFIX Templates and Type Information Export as in [RFC5610]
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 primarily 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.
PLEASE NOTE that this is intended ONLY as a proposed shorthand
format. It is under ACTIVE development. Authors are reminded that
it is inappropriate to cite an Internet-Draft as other than a work in
progress. This draft will likely be subsumed into a greater effort
to define how new Information Elements and recommended Templates are
developed within and outside the IPFIX Working Group. As such,
implementation or use of this representation within other Internet-
Drafts at this time is STRONGLY discouraged for implementors and
authors who are not prepared to track each change to this draft, for
it to be merged with other future work, or for it to expire entirely.
2. Terminology
Terms used in this document that are defined in the Terminology
section of the IPFIX Protocol [RFC5101] document are to be
interpreted as defined there. In addition, the following terms used
in this document are defined as follows:
Trammell Expires February 6, 2011 [Page 2]
Internet-Draft IPFIX IEspec August 2010
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],
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 [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.
Trammell Expires February 6, 2011 [Page 3]
Internet-Draft IPFIX IEspec August 2010
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 express 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], is not
supported by this syntax.
Example fully-qualified IESpecs follow:
o octetDeltaCount(1)<unsigned64>[8]
o octetDeltaCount(1)<unsigned64> (unsigned64 is natively 8 octets
long)
o sourceIPv4Address(8)<ipv4Address>
o wlanSSID(146)<string>[v]
o sipRequestURI(35566/403)<string>[65535]
A partial IESpec is any IESpec that is not fully-qualified; these are
useful when defining templates. A partial IESpec is assumed to take
missing values from its canonical definition, for example, the IANA
registry. 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:
o octetDeltaCount
o octetDeltaCount[4] (reduced-length encoding)
o (1)
o (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:
Trammell Expires February 6, 2011 [Page 4]
Internet-Draft IPFIX IEspec August 2010
+------------------------+-------------------------+
| Data Type | Native Size |
+------------------------+-------------------------+
| <octetArray> | [v], [65535] (variable) |
| <unsigned8> | [1] |
| <unsigned16> | [2] |
| <unsigned32> | [4] |
| <unsigned64> | [8] |
| <signed8> | [1] |
| <signed16> | [2] |
| <signed32> | [4] |
| <signed64> | [8] |
| <float32> | [4] |
| <float64> | [8] |
| <boolean> | [1] |
| <macAddress> | [6] |
| <string> | [v], [65535] (variable) |
| <dateTimeSeconds> | [4] |
| <dateTimeMilliseconds> | [8] |
| <dateTimeMicroseconds> | [8] |
| <dateTimeNanoseconds> | [8] |
| <ipv4Address> | [4] |
| <ipv6Address> | [16] |
+------------------------+-------------------------+
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]; 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.
Trammell Expires February 6, 2011 [Page 5]
Internet-Draft IPFIX IEspec August 2010
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
[RFC5101] Claise, B., "Specification of the IP Flow Information
Export (IPFIX) Protocol for the Exchange of IP Traffic
Flow Information", RFC 5101, January 2008.
[RFC5610] Boschi, E., Trammell, B., Mark, L., and T. Zseby,
"Exporting Type Information for IP Flow Information Export
(IPFIX) Information Elements", RFC 5610, July 2009.
[iana-ipfix-assignments]
Internet Assigned Numbers Authority, "IP Flow Information
Export Information Elements
(http://www.iana.org/assignments/ipfix/ipfix.xml)".
Author's Address
Brian Trammell
Swiss Federal Institute of Technology Zurich
Gloriastrasse 35
8092 Zurich
Switzerland
Phone: +41 44 632 70 13
Email: trammell@tik.ee.ethz.ch
Trammell Expires February 6, 2011 [Page 6]
| PAFTECH AB 2003-2026 | 2026-04-24 04:29:46 |