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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY draftIpfixPerstream PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-ipfix-export-per-sctp-stream.xml'>
<!ENTITY draftIpfixMedps PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-ipfix-mediators-problem-statement.xml'>
<!ENTITY draftIpfixMedframe PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-ipfix-mediators-framework.xml'>
<!ENTITY rfc5101 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5101.xml">
<!ENTITY rfc5102 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5102.xml">
<!ENTITY rfc5103 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5103.xml">
<!ENTITY rfc5153 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5153.xml">
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc5470 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5470.xml">
<!ENTITY rfc5472 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5472.xml">
<!ENTITY rfc5610 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5610.xml">
<!ENTITY rfc5655 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5655.xml">
] >
<rfc ipr="trust200902" category="info" docName="draft-trammell-ipfix-text-iespec-00.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="Hitachi Europe">
      Hitachi Europe 
    </organization>
    <address>
      <postal>
        <street>c/o ETH Zurich</street>
        <street>Gloriastrasse 35</street>
        <city>8092 Zurich</city>
        <country>Switzerland</country>
      </postal>
      <phone>+41 44 632 70 13</phone>
      <email>brian.trammell@hitachi-eu.com</email>
    </address>
  </author>
  <date month="April" day="16" 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"/>. However,
    XML representations of Information Elements as in the <xref
    target="iana-ipfix-assignments">IANA registry</xref> 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 <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
    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.</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 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 <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, 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.</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">
    &rfc5101;
    &rfc5610;
    <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>