One document matched: draft-trammell-ipfix-text-iespec-01.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc ipr="trust200902" category="info" docName="draft-trammell-ipfix-text-iespec-01.txt">
<?rfc compact="yes"?>
<?rfc subcompact="yes"?>
<?rfc toc="no"?>
<?rfc symrefs="yes"?>

<front>
  <title abbrev="IPFIX IEspec">
    A Lightweight Textual Format for IPFIX Information Models and Templates 
  </title>
  <author initials="B." surname="Trammell" fullname="Brian Trammell">
    <organization abbrev="ETH Zurich">
        Swiss Federal Institute of Technology Zurich
    </organization>
    <address>
      <postal>
        <street>Gloriastrasse 35</street>
        <city>8092 Zurich</city>
        <country>Switzerland</country>
      </postal>
      <phone>+41 44 632 70 13</phone>
      <email>trammell@tik.ee.ethz.ch</email>
    </address>
  </author>
  <date month="August" day="5" year="2010"></date>
  <area>Operations</area>
  <workgroup>IPFIX Working Group</workgroup>
  <abstract> 

    <t>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.</t>

  </abstract>
</front>

<middle>

  <section title="Introduction">

    <t>The IP Flow Information Export Protocol (IPFIX) <xref
    target="RFC5101"/> affords new levels of flexibility in defining Data
    Record formats through its Template mechanism, and new Information
    Elements via an <xref target="iana-ipfix-assignments">IANA
    registry</xref>, enterprise-specific Information Elements, and inline
    information model export as defined in <xref target="RFC5610"/>.</t>
    
    <t>However, XML representations of Information Elements as in the <xref
    target="iana-ipfix-assignments">IANA registry</xref> 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 <xref target="RFC5610"/> are excellent for
    runtime, but not particularly human-readable.</t>

    <t>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.</t>
    
     <t>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.</t>

  </section>

  <section title="Terminology">

    <t>Terms used in this document that are defined in the Terminology section
    of the <xref target="RFC5101">IPFIX Protocol</xref> document are to be
    interpreted as defined there. In addition, the following terms used in
    this document are defined as follows:</t>

    <list style="hanging"> 

      <t hangText="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.</t>

      <t hangText="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.</t>

      <t hangText="partial IESpec: ">An IESpec that is not fully
      qualified.</t>
    </list>

    <t>Note that when the term Template is used in this document,
    it applies both to Templates and Options Templates as
    defined in <xref target="RFC5101"/>, unless otherwise noted.</t>

  </section>
  
  <section title="Information Element Specifier Syntax">

    <t>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.</t>

    <t>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.</t>

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

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

    <t>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 <xref target="iana-ipfix-assignments">IANA
    informationElementDataTypes registry</xref>, 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 <xref target='sec-native-size'/>.</t>

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

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

    <t>where 'pen' is the Private Enterprise Number as a decimal integer.</t>

    <t>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 <xref target="RFC5610"/>, is not supported
    by this syntax.</t>

    <t>Example fully-qualified IESpecs follow:</t>
    
    <list style="symbols">
      <t>octetDeltaCount(1)<unsigned64>[8]</t>
      <t>octetDeltaCount(1)<unsigned64> (unsigned64 is natively 8 octets long)</t>
      <t>sourceIPv4Address(8)<ipv4Address></t>
      <t>wlanSSID(146)<string>[v]</t>
      <t>sipRequestURI(35566/403)<string>[65535]</t>
    </list>

    <t>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.</t>
    
     <t>Example partial IESpecs follow:</t>

    <list style="symbols">
      <t>octetDeltaCount</t>
      <t>octetDeltaCount[4] (reduced-length encoding)</t>
      <t>(1)</t>
      <t>(1)[4] (reduced length encoding; note that this is exactly equivalent to an Information Element specifier in a Template)</t>
    </list>

    <section title="Native Sizes of Data Types" anchor="sec-native-size">

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

      <texttable> 
        <ttcol align="left">Data Type</ttcol> 
        <ttcol align="left">Native Size</ttcol> 
        <c><octetArray></c><c>[v], [65535] (variable)</c>
        <c><unsigned8></c><c>[1]</c>
        <c><unsigned16></c><c>[2]</c>
        <c><unsigned32></c><c>[4]</c>
        <c><unsigned64></c><c>[8]</c>
        <c><signed8></c><c>[1]</c>
        <c><signed16></c><c>[2]</c>
        <c><signed32></c><c>[4]</c>
        <c><signed64></c><c>[8]</c>
        <c><float32></c><c>[4]</c>
        <c><float64></c><c>[8]</c>
        <c><boolean></c><c>[1]</c>
        <c><macAddress></c><c>[6]</c>
        <c><string></c><c>[v], [65535] (variable)</c>
        <c><dateTimeSeconds></c><c>[4]</c>
        <c><dateTimeMilliseconds></c><c>[8]</c>
        <c><dateTimeMicroseconds></c><c>[8]</c>
        <c><dateTimeNanoseconds></c><c>[8]</c>
        <c><ipv4Address></c><c>[4]</c>
        <c><ipv6Address></c><c>[16]</c>
      </texttable>
    </section>

  </section>

  <section title="Defining an Information Model from IESpecs">

    <t>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 <xref target="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.</t>

  </section>    
  
  <section title="Defining a Template or Options Template from IESpecs">

    <t>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.:</t>

    <t>sourceIPv4Address{scope}</t>

    <t>A syntax for an encapsulation of templates (including e.g. template ID)
    is not yet defined.</t>
    
  </section>

  <section title="Security Considerations">

    <t>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.</t>

  </section>

  <section title="IANA Considerations">

    <t>This document has no actions for IANA.</t>

  </section>

</middle>   

<back>

  <references title="Normative References">
      <?rfc include="reference.RFC.5101" ?>
      <?rfc include="reference.RFC.5610" ?>
    <reference anchor='iana-ipfix-assignments'>
      <front>
        <title>IP Flow Information Export Information Elements (http://www.iana.org/assignments/ipfix/ipfix.xml)</title>
        <author surname="Internet Assigned Numbers Authority"/>
      </front>
    </reference>
  </references>

</back>
</rfc>