Skip to main content

Guidelines for Authors and Reviewers of IPFIX Information Elements
draft-ietf-ipfix-ie-doctors-05

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 7013.
Authors Brian Trammell , Benoît Claise
Last updated 2012-09-20 (Latest revision 2012-09-19)
Replaces draft-trammell-ipfix-ie-doctors
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Document shepherd (None)
IESG IESG state Became RFC 7013 (Best Current Practice)
Consensus boilerplate Unknown
Telechat date (None)
Needs a YES. Needs 10 more YES or NO OBJECTION positions to pass.
Responsible AD Ron Bonica
IESG note
Send notices to ipfix-chairs@tools.ietf.org, draft-ietf-ipfix-ie-doctors@tools.ietf.org
draft-ietf-ipfix-ie-doctors-05
IPFIX Working Group                                          B. Trammell
Internet-Draft                                                ETH Zurich
Intended status: BCP                                           B. Claise
Expires: March 23, 2013                              Cisco Systems, Inc.
                                                      September 19, 2012

   Guidelines for Authors and Reviewers of IPFIX Information Elements
                   draft-ietf-ipfix-ie-doctors-05.txt

Abstract

   This document provides guidelines for the definition of IPFIX
   Information Elements for addition to the IANA IPFIX Information
   Element registry, in order to extend the applicability of the IPFIX
   protocol to new operations and management areas.

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 March 23, 2013.

Copyright Notice

   Copyright (c) 2012 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 & Claise        Expires March 23, 2013                 [Page 1]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Intended Audience and Usage  . . . . . . . . . . . . . . .  3
     1.2.  Overview of relevant IPFIX documents . . . . . . . . . . .  4
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  How to apply IPFIX . . . . . . . . . . . . . . . . . . . . . .  5
   4.  Defining new Information Elements  . . . . . . . . . . . . . .  6
     4.1.  Information Element naming . . . . . . . . . . . . . . . .  7
     4.2.  Information Element data types . . . . . . . . . . . . . .  7
     4.3.  Information Element numbering  . . . . . . . . . . . . . .  9
     4.4.  Ancillary Information Element properties . . . . . . . . .  9
     4.5.  Internal structure in Information Elements . . . . . . . . 10
     4.6.  Information Element multiplicity . . . . . . . . . . . . . 11
     4.7.  Enumerated Values and Subregistries  . . . . . . . . . . . 11
     4.8.  Reversibility as per RFC 5103  . . . . . . . . . . . . . . 12
     4.9.  Avoiding Bad Ideas in Information Element Design . . . . . 12
   5.  The Information Element Lifecycle  . . . . . . . . . . . . . . 13
     5.1.  The IE-DOCTORS process . . . . . . . . . . . . . . . . . . 13
     5.2.  Revising Information Elements  . . . . . . . . . . . . . . 14
     5.3.  Deprecating Information Elements . . . . . . . . . . . . . 15
   6.  When not to define new Information Elements  . . . . . . . . . 16
     6.1.  Maximizing reuse of existing Information Elements  . . . . 17
     6.2.  Applying enterprise-specific Information Elements  . . . . 18
   7.  Information Element Definition Checklist . . . . . . . . . . . 19
   8.  Applying IPFIX to non-Flow Applications  . . . . . . . . . . . 21
   9.  Writing Internet-Drafts for IPFIX Applications . . . . . . . . 22
     9.1.  Example Information Element Definition . . . . . . . . . . 22
     9.2.  Defining Recommended Templates . . . . . . . . . . . . . . 23
   10. A Textual Format for Specifying Information Elements and
       Templates  . . . . . . . . . . . . . . . . . . . . . . . . . . 24
     10.1. Information Element Specifiers . . . . . . . . . . . . . . 24
     10.2. Specifying Templates . . . . . . . . . . . . . . . . . . . 26
     10.3. Specifying IPFIX Structured Data . . . . . . . . . . . . . 27
   11. Security Considerations  . . . . . . . . . . . . . . . . . . . 28
   12. IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 29
   13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 30
   14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30
     14.1. Normative References . . . . . . . . . . . . . . . . . . . 30
     14.2. Informative References . . . . . . . . . . . . . . . . . . 30
   Appendix A.  Example Information Element Definitions . . . . . . . 32
     A.1.  sipResponseStatus  . . . . . . . . . . . . . . . . . . . . 32
     A.2.  duplicatePacketDeltaCount  . . . . . . . . . . . . . . . . 32
     A.3.  ambientTemperature . . . . . . . . . . . . . . . . . . . . 33
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33

Trammell & Claise        Expires March 23, 2013                 [Page 2]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

1.  Introduction

   This document provides guidelines for the extension of the
   applicability of the IP Flow Information Export (IPFIX) protocol to
   network operations and management purposes outside the initial scope
   defined in "IPFIX Applicability Statement" [RFC5472].  These new
   applications are largely defined by creating new Information Elements
   beyond those in the IANA IPFIX Information Element Registry
   [iana-ipfix-assignments].  New applications may be further specified
   through additional RFCs defining and describing their usage.

   We intend this document to enable the expansion of the applicability
   of IPFIX to new areas by experts in the working group or area
   directorate concerned with the technical details of the protocol or
   application to be measured or managed using IPFIX.  This expansion
   would occur with the consultation of IPFIX experts informally called
   IE-DOCTORS.  It provides guidelines both for those defining new
   Information Elements as well as the IE-DOCTORS reviewing them.

1.1.  Intended Audience and Usage

   This document is meant for two separate audiences.  For IETF
   contributors extending the applicability of IPFIX, it provides
   specifications and best practices to be used in deciding which
   Information Elements are necessary for a given existing or new
   application, defining these Information Elements, and deciding
   whether an RFC should be published to further describe the
   application.  For the IPFIX experts appointed as IE-DOCTORS, and for
   IANA personnel changing the IANA IPFIX Information Element Registry
   [iana-ipfix-assignments], it defines a set of acceptance criteria
   against which these proposed Information Elements should be
   evaluated.

   This document is not intended to guide the extension of the IPFIX
   protocol itself, e.g. through new export mechanisms, data types, or
   the like; these activities should be pursued through the publication
   of standards-track RFCs by the IPFIX Working Group.

   This document, together with
   [I-D.ietf-ipfix-information-model-rfc5102bis], defines the procedures
   for management of the IANA IPFIX Information Element Registry
   [iana-ipfix-assignments].  The practices outlined in this document
   are intended to guide experts when reviewing additions or changes to
   the Information Elements in the registry under Expert Review as
   defined in [RFC5226].

Trammell & Claise        Expires March 23, 2013                 [Page 3]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

1.2.  Overview of relevant IPFIX documents

   [EDITOR'S NOTE: review this section to make sure "this document" is
   always unambiguous.]

   [I-D.ietf-ipfix-protocol-rfc5101bis] defines the IPFIX Protocol, the
   IPFIX-specific terminology used by this document, and the data type
   encodings for each of the data types supported by IPFIX.

   [I-D.ietf-ipfix-information-model-rfc5102bis] defines the basis of
   the IPFIX Information Model, referring to [iana-ipfix-assignments]
   for the specific Information Element definitions.  It states that new
   Information Elements may be added to the Information Model on Expert
   Review basis, delegates the appointment of experts to an IESG Area
   Director, and refers to this document for details on the extension
   process.  This document is intended to further codify the best
   practices to be followed by these experts, in order to improve the
   efficiency of this process.

   [RFC5103] defines a method for exporting bidirectional flow
   information using IPFIX; this document should be followed when
   extending IPFIX to represent information about bidirectional network
   interactions in general.  Additionally, new Information Elements
   should be annotated for their reversibility or lack thereof as per
   this document.

   [RFC5610] defines a method for exporting information about
   Information Elements inline within IPFIX.  In doing so, it explicitly
   defines a set of restrictions, implied in
   [I-D.ietf-ipfix-protocol-rfc5101bis] and
   [I-D.ietf-ipfix-information-model-rfc5102bis], on the use of data
   types and semantic; these restrictions must be observed in the
   definition of new Information Elements, as in Section 4.4.

2.  Terminology

   Capitalized terms used in this document that are defined in the
   Terminology section of [I-D.ietf-ipfix-protocol-rfc5101bis] are to be
   interpreted as defined there.

   An "application", as used in this document, refers to a candidate
   protocol, task, or domain to which IPFIX export, collection, and/or
   storage is applied, beyond those within the IPFIX Applicability
   statement [RFC5472].  By this definition, PSAMP [RFC5476] was the
   first new IPFIX application after the publication of the IPFIX
   protocol itself.

Trammell & Claise        Expires March 23, 2013                 [Page 4]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   "IANA IE registry", as used in this document, unless otherwise noted,
   refers to the IANA IPFIX Information Element Registry
   [iana-ipfix-assignments].

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

3.  How to apply IPFIX

   Though originally specified for the export of IP flow information,
   the message format, template mechanism, and data model specified by
   IPFIX lead to it being applicable to a wide variety of network
   management situations.  In addition to flow information export, for
   which it was designed, and packet information export as specified by
   PSAMP [RFC5476], any application with the following characteristics
   is a good candidate for an IPFIX application:

   o  The application's data flow is fundamentally unidirectional.
      IPFIX is a "push" protocol, supporting only the export of
      information from a sender (an Exporting Process) to a receiver (a
      Collecting Process).  Request-response interactions are not
      supported by IPFIX.

   o  The application handles discrete event information, or information
      to be periodically reported.  IPFIX is particularly well suited to
      representing events, which can be scoped in time.

   o  The application handles information about network entities.
      IPFIX's information model is network-oriented, so network
      management applications have many opportunities for information
      model reuse.

   o  The application requires a small number of arrangements of data
      structures relative to the number of records it handles.  The
      template-driven self-description mechanism used by IPFIX excels at
      handling large volumes of identically structured data, compared to
      representations which define structure inline with data (such as
      XML).

   Most applications meeting these criteria can be supported over IPFIX.
   Once it has been determined that IPFIX is a good fit, the next step
   is determining which Information Elements are necessary to represent
   the information required by the application.  Especially for network-
   centric applications, the IANA IE registry may already contain all
   the necessary Information Elements (see Section 6.1 for guidelines on
   maximizing Information Element reuse).  In this case, no work within

Trammell & Claise        Expires March 23, 2013                 [Page 5]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   the IETF is necessary: simply define Templates and start exporting.

   It is expected, however, that most applications will be able to reuse
   some existing Information Elements, but may need to define some
   additional Information Elements to support all their requirements; in
   this case, see Section 4 for best practices to be followed in
   defining Information Elements.

   Optionally, a Working Group or individual contributor may choose to
   write an Internet-Draft for publication as an RFC, detailing the new
   IPFIX application.  Such an RFC should contain discussion of the new
   application, the Information Element definitions as in Section 4, as
   well as suggested Templates and examples of the use of those
   Templates within the new application as in Section 9.2.  Section 10
   defines a compact textual Information Element notation to be used in
   describing these suggested Templates and/or the use of IPFIX
   Structured Data [RFC6313] within the new application.

4.  Defining new Information Elements

   In many cases, a new application will require nothing more than a new
   Information Element or set of Information Elements to be exportable
   using IPFIX.  An Information Element meeting the following criteria,
   as evaluated by the IE-DOCTORS, is eligible for inclusion in the IANA
   IE registry:

   o  The Information Element MUST be sufficiently unique within the
      registry.  Its description MUST represent a substantially
      different meaning from that of any existing Information Element.
      A proposed Information Element which is a substantial duplicate of
      an existing Information Element is to be represented using the
      existing Information Element.

   o  The Information Element SHOULD contain minimal internal structure;
      complex information should be represented with multiple simple
      Information Elements to be exported in parallel or using IPFIX
      Structured Data [RFC6313], as in Section 4.5; the internal
      structure of a proposed IE may be evaluated by the IE-DOCTORS with
      an eye toward interoperability and/or backward compatibility with
      existing methods of exporting similar data on a case-by-case
      basis.

   o  The Information Element SHOULD be generally applicable to the
      application at hand, which SHOULD be of general interest to the
      community.  Information Elements representing information about
      proprietary or nonstandard applications SHOULD be represented
      using enterprise-specific Information Elements as detailed in

Trammell & Claise        Expires March 23, 2013                 [Page 6]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

      section 3.2 [RFC-EDITOR NOTE: verify section number] of
      [I-D.ietf-ipfix-protocol-rfc5101bis].

   The definition of new Information Elements requires a descriptive
   name, a specification of the data type from the IPFIX Data Type
   subregistry in the IANA IE registry (defined in
   [I-D.ietf-ipfix-information-model-rfc5102bis] as itself extensible
   via Standards Action as per [RFC5226]), and a human-readable
   description written in English.  This section provides guidelines on
   each of these components of an Information Element definition,
   referring to existing documentation such as
   [I-D.ietf-ipfix-information-model-rfc5102bis] as appropriate.

4.1.  Information Element naming

   Information Element Names should be defined in accordance with
   section 2.3 [RFC-EDITOR NOTE: verify section number] of
   [I-D.ietf-ipfix-information-model-rfc5102bis]; the most important
   naming conventions are repeated here for convenience.

   o  Names of Information Elements SHOULD be descriptive.

   o  Names of Information Elements MUST be unique within the IANA IE
      registry.

   o  Names of Information Elements MUST start with non-capitalized
      letters.

   o  Composed names MUST use capital letters for the first letter of
      each component except for the first one (aka "camel case").  All
      other letters are non-capitalized, even for acronyms.  Exceptions
      are made for acronyms containing non-capitalized letters, such as
      'IPv4' and 'IPv6'.  Examples are "sourceMacAddress" and
      "destinationIPv4Address."

   In addition, new Information Elements pertaining to a specific
   protocol SHOULD name the protocol in the first word in order to ease
   searching by name (e.g. "sipMethod" for a SIP method, as would be
   used in a logging format for SIP based on IPFIX).  Similarly, new
   Information Elements pertaining to a specific application SHOULD name
   the application in the first word.

4.2.  Information Element data types

   IPFIX provides a set of data types covering most primitives used in
   network measurement and management applications.  The most
   appropriate data type should be chosen for the Information Element
   type, IPFIX informationElementDataTypes subregistry at

Trammell & Claise        Expires March 23, 2013                 [Page 7]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   [iana-ipfix-assignments].  This subregistry may be extended from time
   to time by a Standards Action [RFC5226], as defined in [RFC5610].

   Information Elements representing an integral value with a natural
   width SHOULD be defined with the appropriate integral data type.
   This applies especially to values taken directly from fixed-width
   fields in a measured protocol.  For example, tcpControlBits, the TCP
   flags byte, is an unsigned8, and tcpSequenceNumber is an unsigned32.

   Information Elements representing counters or identifiers SHOULD be
   defined as signed64 or unsigned64, as appropriate, to maximize the
   range of values available; applications can use reduced-size encoding
   as defined in Section 6.2 [RFC-EDITOR NOTE: verify section number] of
   [I-D.ietf-ipfix-protocol-rfc5101bis] in cases where fewer than 2^64
   values are necessary.

   Information Elements representing time values MUST be defined with
   appropriate precision.  For example, a Information Element for a time
   measured at second-level precision should be defined as having a
   dateTimeSeconds data type, instead of dateTimeMilliseconds.

   Information Elements of type string or octetArray which have length
   constraints (fixed length, minimum and/or maximum length) MUST note
   these constraints in their description.

   The type of an Information Element MUST match the type of the data it
   represents.  More specifically, information that could be represented
   as a string, but which better matches one of the other data types
   (e.g. an integral type for a number or enumerated type, an address
   type for an address) MUST be represented by the best-matching type,
   even if the data was represented using a different type in the
   source.  In other words, an IPFIX application that exports Options
   Template Records mapping IP addresses to additional information about
   each host from an external database MUST use Information Elements of
   an address type to represent the addresses, even if the source
   database represented these as strings.

   This document does not cover the addition of new Data Types or Data
   Type Semantics to the IPFIX Protocol.  As such changes have important
   interoperability considerations and require implementation on both
   Collecting and Exporting Processes, they require a Standards Action
   as per [RFC5610].  However, note that the set of primitive types
   provided by IPFIX are applicable to almost any appropriate
   application, so extending the type system is generally not necessary.

Trammell & Claise        Expires March 23, 2013                 [Page 8]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

4.3.  Information Element numbering

   Each Information Element has a unique identifier in the IANA
   registry.

   In general, when adding newly registered Information Elements to the
   IANA IE registry, IANA SHOULD assign the lowest available Information
   Element identifier (the value column in [iana-ipfix-assignments]) in
   the range 128-32767.

   Information Element identifiers in the range 1-127 MUST NOT be
   assigned unless the Information Element is compatible with the
   NetFlow V9 protocol as described in [RFC3954].  Such Information
   Elements may ONLY be requested by a NetFlow v9 expert, to be
   designated by the IESG to consult with IANA on NetFlow v9
   compatibility with IPFIX.  These information elements are exempt from
   IE-DOCTORS review; it is the responsibility of the NetFlow v9 expert
   to ensure that the requested IEs substantially conform to the
   guidelines in this document, with consideration given for already-
   implemented and already-deployed features.

4.4.  Ancillary Information Element properties

   Information Elements to which special semantics apply SHOULD refer to
   one of the values in the Information Element Semantics subregistry of
   the IANA IE registry, as described in Section 3.2 [RFC-EDITOR NOTE:
   verify section number] of
   [I-D.ietf-ipfix-information-model-rfc5102bis], subject to the
   restrictions given in Section 3.10 of [RFC5610]; in other words, the
   semantics and the type MUST be consistent.

   When defining Information Elements representing a dimensioned
   quantity or entity count, the units of that quantity SHOULD be
   defined in the units field.  This field takes its values from the
   IANA Information Element Units subregistry of the IANA IE registry.
   If an Information Element expresses a quantity in units not yet in
   this subregistry, then the unit MUST be added to the Units
   subregistry at the same time the Information Element is added to the
   IANA IE registry.  Note that the Units subregistry as defined in
   [RFC5610] is maintained on an Expert Review basis.

   Additionally, when the range of values an Information Element can
   take is smaller than the range implied by its data type, the range
   SHOULD be defined within the Information Element's entry the IANA IE
   registry.

Trammell & Claise        Expires March 23, 2013                 [Page 9]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

4.5.  Internal structure in Information Elements

   The definition of Information Elements with internal structure with
   the structure defined in the Description field is NOT RECOMMENDED,
   except in the following cases:

   1.  The Information Element is a direct copy of a structured entity
       in a measured protocol (e.g. the tcpControlBits Information
       Element for the flags byte from the TCP header)

   2.  The Information Element represents a section of a packet of
       protocol entity, in raw form as captured from the wire (e.g. the
       mplsLabelStackSection Information Element for the MPLS label
       stack)

   3.  The Information Element represents a set of flags which are
       tightly semantically related, where representing the flags as
       separate one-byte booleans would be inefficient, and which should
       always appear together in a data record (e.g., the
       anonymizationFlags Information Element for specifying optional
       features of anonymization techniques)

   4.  The Information Element contains internal structure by reference
       to an external datatype or specification containing internal
       structure (e.g., a MIME type or URL), for interoperability and
       backward compatibility purposes

   In other cases, candidate Information Elements with internal
   structure SHOULD be decomposed into multiple primitive Information
   Elements to be used in parallel.  For more complicated semantics,
   where the structure is not identical from Data Record to Data Record,
   or where there is semantic dependency between multiple decomposed
   primitive Information Elements, use the IPFIX Structured Data
   [RFC6313] extension instead.

   As an example of information element decomposition, consider an
   application-level identifier called an "endpoint", which represents a
   {host, port, protocol} tuple.  Instead of allocating an opaque,
   structured "source endpoint" Information Element, the source endpoint
   should be represented by three separate Information Elements: "source
   address", "source port", "transport protocol".  In this example, the
   required information elements already exist in the IANA IE registry:
   sourceIPv4Address or sourceIPv6Address, sourceTransportPort,
   protocolIdentifier.  Indeed, as well as being good practice, this
   normalization down to non-structured Information Elements also
   increases opportunities for reuse as in Section 6.1.

   The decomposition of data with internal structure SHOULD avoid the

Trammell & Claise        Expires March 23, 2013                [Page 10]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   definition of Information Elements with a meaning too specific to be
   generally useful, or that would result in a multitude of templates to
   handle different multiplicities.  More information on multiplicities
   is given in the following section.

4.6.  Information Element multiplicity

   Some Information Elements may represent information with a
   multiplicity other than one; i.e., items that may occur multiple
   times within the data to be represented in a single IPFIX record.  In
   this case, there are several options, depending on the circumstances:

   1.  As specified in section 8 [RFC-EDITOR NOTE: verify section
       number] of [I-D.ietf-ipfix-protocol-rfc5101bis]: "if an
       Information Element is required more than once in a Template, the
       different occurrences of this Information Element SHOULD follow
       the logical order of their treatments by the Metering Process."
       In other words, in cases where the items have a natural order
       (e.g., the order in which they occur in the packet), and the
       multiplicity is the same for each record, the information can be
       modeled by containing multiple instances of the Information
       Element representing a single item within the Template Record
       describing the Data Records.

   2.  In cases where the items have a variable multiplicity, a
       basicList of the Information Element representing a single item
       can be used as in the IPFIX Structured Data [RFC6313] extension.

   3.  If the multiple-item structure is taken directly from bytes
       observed on the wire by the Metering Process or otherwise taken
       from the application being measured (e.g., a TCP options stack),
       the multiple-item structure can be exported as a variable-length
       octetArray Information Element holding the raw content.

   Specifically, new Information Element SHOULD NOT encode any
   multiplicity or ordinality information into the definition of the
   Information Element itself.

4.7.  Enumerated Values and Subregistries

   When defining an Information Element that takes an enumerated value
   from a set of values which may change in the future, this enumeration
   MUST be defined by an IANA IE registry or subregistry.  For
   situations where an existing registry defines the enumeration (e.g.,
   the IANA Protocol Numbers registry for the protocolIdentifier
   Information Element), that registry MUST be used.  Otherwise, a new
   subregistry of the IANA IPFIX registry MUST be defined for the
   enumerated value, to be modified subject to Expert Review [RFC5226].

Trammell & Claise        Expires March 23, 2013                [Page 11]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

4.8.  Reversibility as per RFC 5103

   [RFC5103] defines a method for exporting bidirectional flows using a
   special Private Enterprise Number to define reverse-direction
   variants of IANA Information Elements, and a set of criteria for
   determining whether an Information Element may be reversed using this
   method.  Since almost all Information Elements are reversible,
   [RFC5103] enumerates those Information Elements which were defined at
   the time of its publication which are NOT reversible.

   New non-reversible Information Elements MUST contain a note in the
   description stating that they are not reversible.

4.9.  Avoiding Bad Ideas in Information Element Design

   In general, the existence of a similarly-defined Information Element
   in the IANA IE registry sets a precedent which may be followed to
   determine whether a given proposed Information Element "fits" within
   the registry.  Indeed, the rules specified by this document could be
   interpreted to mean "make new Information Elements that look like
   existing Information Elements".  However, for reasons of history,
   there are several Information Elements within the IANA IE registry
   which do not follow best practices in Information Element design.
   These Information Elements are not necessarily so flawed so as to
   require deprecation, but they should be explicitly ignored when
   looking for guidance as to whether a new Information Element should
   be added.

   Before registering a new Information Element, it must be determined
   that it would be sufficiently unique within the IANA IE registry.
   This evaluation has not always been done in the past, and the
   existence of the Information Elements defined without this evaluation
   should not be taken as an example that such Information Element
   definition practices should be followed in the future.  Specific
   examples of such Information Elements include initiatorOctets and
   responderOctets (which duplicate octetDeltaCount and its reverse per
   [RFC5103]) and initiatorPackets and responderPackets (the same, for
   packetDeltaCount).  [EDITOR'S NOTE: verify whether these are delta
   counts or total counts]

   As mentioned in Section 4.2, the type of an Information Element
   SHOULD match the type of data the Information Element represents.  An
   example of how not to do this is presented by the p2pTechnology,
   tunnelTechnology, and encryptedTechnology Information Elements: these
   represent a three-state enumeration using a String.  The example set
   by these Information Elements SHOULD NOT be followed in the
   definition of new Information Elements.

Trammell & Claise        Expires March 23, 2013                [Page 12]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   As mentioned in Section 4.6, an Information Element definition SHOULD
   NOT include any ordinality or multiplicity information.  The only
   example of this within the IANA registry the following list of
   assigned IPFIX Information Elements: mplsTopLabelStackSection,
   mplsLabelStackSection2, mplsLabelStackSection3,
   mplsLabelStackSection4, mplsLabelStackSection5,
   mplsLabelStackSection6 mplsLabelStackSection7,
   mplsLabelStackSection8, mplsLabelStackSection9, and
   mplsLabelStackSection10.  The only distinction between those almost-
   identical Information Elements is the position within the MPLS stack.
   This Information Element design pattern met an early requirement of
   the definition of IPFIX which was not carried forward into the final
   specification -- namely, that no semantic dependency was allowed
   between Information Elements in the same Record -- and as such SHOULD
   NOT be followed in the definition of new Information Elements.  In
   this case, since the size of the MPLS stack will vary from flow to
   flow, it should be exported using IPFIX Structured Data [RFC6313]
   where supported, as a basicList of MPLS label entries, or as a raw
   MPLS label stack using the variable-length mplsLabelStackSection
   Information Element.

5.  The Information Element Lifecycle

   Once an Information Element or set of Information Elements has been
   identified for a given application, Information Element
   specifications in accordance with Section 4 are submitted to IANA to
   follow the IE-DOCTORS process, as defined below.  This process is
   also used for other changes to the IANA IE registry, such as
   deprecation or revision, as described later in this section.

5.1.  The IE-DOCTORS process

   Requests to change the IANA IE registry or a linked subregistry are
   submitted to IANA, which forwards the request to a designated group
   of experts (IE-DOCTORS) appointed by the IESG; these are the
   reviewers called for by the Expert Review [RFC5226] policy defined
   for the IANA IE registry by
   [I-D.ietf-ipfix-information-model-rfc5102bis].  The IE-DOCTORS review
   the request for such things as compliance with this document,
   compliance with other applicable IPFIX-related RFCs, and consistency
   with the currently defined set of Information Elements.

   Authors are expected to review compliance with the specifications in
   this document to check their submissions before sending them to IANA.

   IE-DOCTORS reviewers should endeavor to complete referred reviews in
   a timely manner.  If the request is acceptable, the IE-DOCTORS

Trammell & Claise        Expires March 23, 2013                [Page 13]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   signify their approval to IANA, which changes the IANA IE registry.
   If the request is not acceptable, the IE-DOCTORS can coordinate with
   the requestor to change the request to be compliant.  The IE-DOCTORS
   may also choose in exceptional circumstances to reject clearly
   frivolous or inappropriate change requests outright.

   IE-DOCTORS decisions may be appealed as in section 7 of [RFC5226].

5.2.  Revising Information Elements

   The Information Element status field in the IANA IE registry is
   defined in [I-D.ietf-ipfix-information-model-rfc5102bis] to allow
   Information Elements to be 'current' or 'deprecated'.  No Information
   Elements are as of this writing deprecated.  [RFC5102] additionally
   specified an 'obsolete' status; however, this has been removed on
   revision as it served no operational purpose.

   In addition, no policy is defined for revising IANA IE registry
   entries or addressing errors therein.  To be certain, changes and
   deprecations within the IANA IE registry are not encouraged, and
   should be avoided to the extent possible.  However, in recognition
   that change is inevitable, this section is intended to remedy this
   situation.

   Changes are initiated by sending a new Information Element definition
   to IANA, as in Section 5.1, for an already-existing Information
   Element.

   The primary requirement in the definition of a policy for managing
   changes to existing Information Elements is avoidance of
   interoperability problems; IE-DOCTORS MUST work to maintain
   interoperability above all else.  Changes to Information Elements
   already in use may only be done in an interoperable way; necessary
   changes which cannot be done in a way to allow interoperability with
   unchanged implementations MUST result in deprecation.

   A change to an Information Element is held to be interoperable only
   when:

   1.  it involves the correction of an error which is obviously only
       editorial; or

   2.  it corrects an ambiguity in the Information Element's definition,
       which itself leads to non-interoperability severe enough to
       prevent the Information Element's usage as originally defined
       (e.g., a prior change to ipv6ExtensionHeaders); or

Trammell & Claise        Expires March 23, 2013                [Page 14]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   3.  it expands the Information Element's data type without changing
       how it is represented (e.g., changing unsigned32 to unsigned64,
       as with a prior change to selectorId); or

   4.  it corrects missing information in the Information Element's
       definition without changing its meaning (e.g., the explicit
       definition of 'quantity' semantics for numeric Information
       Elements without a Data Type Semantics value); or

   5.  it defines a previously undefined or reserved enumerated value,
       or one or more previously reserved bits in an Information Element
       with flag semantics; or

   6.  it expands the set of permissible values in the Information
       Element's range; or

   7.  it harmonizes with an external reference which was itself
       corrected.

   If a change is deemed permissible by the IE-DOCTORS, IANA makes the
   change in the IANA IE registry.  The requestor of the change is
   appended to the Requestor in the registry.

   Each Information Element in the IANA IE registry has a Revision
   number, starting at zero.  Each change to an Information Element
   following this process increments the Revision number by one.  Since
   any revision must be interoperable according to the criteria above,
   there is no need for the IANA IE registry to store information about
   old revisions.

   When a revised Information Element is accepted into the registry, the
   date of acceptance of the most recent revision is placed into the
   revision Date column of the registry for that Information Element.

   Information Elements with identifiers in the range 1-127 are
   compatible with the NetFlow V9 protocol as described in [RFC3954]; to
   maintain this compatibility, all revisions to such Information
   Elements are subject to additional review by the appointed NetFlow V9
   expert.

5.3.  Deprecating Information Elements

   Changes that are not permissible by these criteria may only be
   handled by deprecation.  An Information Element MAY be deprecated and
   replaced when:

Trammell & Claise        Expires March 23, 2013                [Page 15]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   1.  the Information Element definition has an error or shortcoming
       which cannot be permissibly changed as in Section 5.2; or

   2.  the deprecation harmonizes with an external reference which was
       itself deprecated through that reference's accepted deprecation
       method; or

   3.  changes in the IPFIX Protocol or its extensions, or in community
       understanding thereof, allow the information represented by the
       Information Element to be represented in a more efficient or
       convenient way.  Deprecation in this circumstance requires a
       Standards Action.

   A request for deprecation is sent to IANA, which passes it to the IE-
   DOCTORS for review, as in Section 5.1.  When deprecating an
   Information Element, the Information Element description in the IANA
   IE registry MUST be updated to explain the deprecation, as well as to
   refer to any new Information Elements created to replace the
   deprecated Information Element.

   The Revision number of an Information Element is incremented upon
   deprecation, and the revision Date updated, as with any revision.

   Information Elements with identifiers in the range 1-127 are
   compatible with the NetFlow V9 protocol as described in [RFC3954]; to
   maintain this compatibility, all deprecations of such Information
   Elements are subject to additional review by the appointed NetFlow V9
   expert.

   Deprecated Information Elements SHOULD continue to be supported by
   Collecting Processes, but SHOULD NOT be exported by Exporting
   Processes.  The use of deprecated Information Elements SHOULD result
   in a log entry or human-readable warning at the Exporting and
   Collecting Processes.

   Names and elementIDs of deprecated Information Elements MUST NOT be
   reused.

6.  When not to define new Information Elements

   Due to the limited number space of Information Elements in the IANA
   IE registry, avoiding redundancy and clutter in the registry is
   important in defining new applications.  New Information Elements
   SHOULD NOT be added to the IANA IE registry unless there is an intent
   to implement and deploy applications using them; research or
   experimental applications SHOULD use enterprise-specific Information
   Elements as in Section 6.2 instead.

Trammell & Claise        Expires March 23, 2013                [Page 16]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   The subsections below provide guidelines for reuse of existing
   Information Elements, as well as guidelines on using enterprise-
   specific Information Elements instead of adding Information Elements
   in the IANA IE registry.

6.1.  Maximizing reuse of existing Information Elements

   Whenever possible, new applications should prefer usage of existing
   IPFIX Information Elements to the creation of new Information
   Elements.  IPFIX already provides Information Elements for every
   common Layer 4 and Layer 3 packet header field in the IETF protocol
   suite, basic Layer 2 information, basic counters, timestamps and time
   ranges, and so on.  When defining a new Information Element similar
   to an existing one, reviewers SHOULD ensure that the existing one is
   not applicable.

   Note that this guideline to maximize reuse does not imply that an
   Information Element that represents the same information from a
   packet as a existing Information Element should not be added to the
   IANA IE registry.  For example, consider the ipClassOfService
   (Element ID 5), ipDiffServCodePoint (Element ID 98), and ipPrecedence
   (Element ID 196) Information Elements.  These all represent subsets
   of the same field in an IP version 4 packet header, but different
   uses of these bits.  The representation in one or another of these
   Information Elements contains information in itself as to how the
   bits were interpreted by the Metering Process.

   On the other hand, simply changing the context in which an
   Information Element will be used is insufficient reason for the
   definition of a new Information Element.  For example, an extension
   of IPFIX to log detailed information about HTTP transactions
   alongside network-level information should not define
   httpClientAddress and httpServerAddress Information Elements,
   preferring instead the use of sourceIPv[46]Address and
   destinationIPv[46]Address.

   Applications dealing with bidirectional interactions should use
   Bidirectional Flow Support for IPFIX [RFC5103] to represent these
   interactions.

   Existing timestamp and time range Information Elements should be
   reused for any situation requiring simple time stamping of an event:
   for single observations, the observationTime* Information Elements
   from PSAMP are provided, and for events with a duration, the
   flowStart* and flowEnd* Information Elements suffice.  This
   arrangement allows minimal generic time handling by existing
   Collecting Processes and analysis workflows.  New timestamp
   Information Elements should ONLY be defined for semantically distinct

Trammell & Claise        Expires March 23, 2013                [Page 17]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   timing information (e.g., an IPFIX-exported record containing
   information about an event to be scheduled in the future).

   In all cases the use of absolute timestamp Information Elements (e.g.
   flowStartMilliseconds) is RECOMMENDED, as these Information Elements
   allow for maximum flexibility in processing with minimal overhead.
   Timestamps based on the export time header in the enclosing IPFIX
   Message (e.g. flowStartTimeDeltaMicroseconds) MAY be used if high-
   precision timing is important, export bandwidth or storage space is
   limited, timestamps comprise a relatively large fraction of record
   size, and the application naturally groups records into IPFIX
   Messages.  Timestamps based on information which must be exported in
   a separate Data Record defined by an Options Template (e.g.
   flowStartSysUpTime) MAY be used only in the context of an existing
   practice of using runtime-defined epochs for the given application.
   New applications SHOULD avoid these structures when possible.

6.2.  Applying enterprise-specific Information Elements

   IPFIX provides a mechanism for defining enterprise-specific
   Information Elements, as in Section 3.2 [RFC-EDITOR NOTE: verify
   section number] of [I-D.ietf-ipfix-protocol-rfc5101bis].  These are
   scoped to a vendor's or organization's Structure of Management
   Information (SMI) Private Enterprise Number, and are under complete
   control of the organization assigning them.

   For situations in which interoperability is unimportant, new
   information SHOULD be exported using enterprise-specific Information
   Elements instead of adding new Information Elements to the IANA IE
   registry.  These situations include:

   o  export of implementation-specific information, or

   o  export of information supporting research or experiments within a
      single organization or closed community, or

   o  export of information derived in a commercially-sensitive or
      proprietary method, or

   o  export of information or meta-information specific to a
      commercially-sensitive or proprietary application.

   While work within the IETF generally does not fall into these
   categories, enterprise-specific Information Elements are also useful
   for pre-standardization testing of a new IPFIX application.  While
   performing initial development and interoperability testing of a new
   application, the Information Elements used by the application SHOULD
   NOT be submitted to IANA for inclusion in the IANA IE registry.

Trammell & Claise        Expires March 23, 2013                [Page 18]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   Instead, these experimental Information Elements SHOULD be
   represented as enterprise-specific until their definitions are
   finalized.

   As this document contains best practices for defining new Information
   Elements, organizations using enterprise-specific Information
   Elements are advised to follow the guidelines set forth here even if
   not submitting Information Elements for inclusion in the IANA IE
   registry.

7.  Information Element Definition Checklist

   The following three checklists, condensed from the rest of this
   document, can be used when defining and reviewing Information
   Elements; they refer back to the section of this document from which
   they are taken.  These checklists are intended for the definition of
   new Information Elements; revision should follow the process defined
   in Section 5.2, and deprecation should follow the process defined in
   Section 5.3.

   Though many of the considerations in this document require the
   subjective judgement of Information Element authors, reviewers, and
   IANA, certain parts of the process may be made simpler through tool
   support.  Items on these checklists which could be easily automated
   or assisted by tools are annotated with "(tool support)".  Other
   items on these checklists require some level of subjective judgement;
   checks for semantic uniqueness may additionally be supported by
   textual analysis of descriptions in the future.

   Checklist 1 contains conditions which MUST be met by all proposed
   Information Elements:

   1.  The name MUST be unique within the IANA IE registry, and not
       reuse the name of any current or deprecated Information Element.
       (Section 4.1) (tool support)

   2.  The description MUST be sufficiently semantically unique within
       the IANA IE registry, representing a substantially different
       meaning from any current or deprecated Information Element.
       (Section 4)

   3.  The name MUST start with a non-capitalized letter.  (Section 4.1)
       (tool support)

   4.  Names composed of more than on word MUST use capital letters for
       the first letter of each component except for the first one; all
       other letters are non-capitalized, even for acronyms.  Exceptions

Trammell & Claise        Expires March 23, 2013                [Page 19]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

       are made for acronyms containing non-capitalized letters, such as
       'IPv4' and 'IPv6'.  (Section 4.1) (tool support)

   5.  The data type MUST match the type of the data being represented.
       (Section 4.2)

   6.  Data type semantics MUST be appropriate for the data type.
       (Section 4.4) (tool support)

   7.  The Information Element identifier assigned by IANA MUST be
       unique.  (Section 4.3) (tool support)

   8.  The Information Element identifier assigned by IANA MUST NOT be
       in the range 1-127 unless it is compatible with the counterpart
       Information Element used in NetFlow V9 [RFC3954].  (Section 4.3)

   Checklist 2 contains conditions which MUST be met by proposed
   Information Elements with certain properties, as noted:

   1.  Time values MUST be defined with appropriate precision.
       (Section 4.2)

   2.  Strings and octet arrays with length restrictions MUST note those
       length restrictions in their descriptions.  (Section 4.2)

   3.  Enumerations MUST refer to an IANA IE registry or subregistry, or
       a registry maintained by an external standards organization.  If
       no suitable registry or subregistry exists, a new subregistry of
       the IPFIX Information Element registry MUST be created for the
       enumeration, to be modified subject to Expert Review [RFC5226].
       (Section 4.7)

   Checklist 3 contains conditions which SHOULD be met by proposed
   Information Elements:

   1.   The name of an Information Element pertaining to a specific
        protocol or application SHOULD contain the name of the protocol
        or application as the first word.  (Section 4.1)

   2.   Information Elements representing integral values SHOULD use a
        data type for the appropriate width for the value.
        (Section 4.2)

   3.   Information Elements representing counters or identifiers SHOULD
        be represented as signed64 or unsigned64, unless they are
        naturally represented with narrower integral types, as
        appropriate.  (Section 4.2)

Trammell & Claise        Expires March 23, 2013                [Page 20]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   4.   An Information Element SHOULD NOT contain internal structure,
        subject to the exceptions in Section 4.5; candidate Information
        Elements with internal structure SHOULD be decomposed into
        multiple Information Elements.  (Section 4.5)

   5.   An Information Element SHOULD NOT contain multiplicity or
        ordinality information within the definition of the Information
        Element itself.  (Section 4.6)

   6.   Data type semantics SHOULD be defined, if appropriate.
        (Section 4.4) (tool support)

   7.   Units SHOULD be defined, if appropriate, with new units added to
        the Information Element Units subregistry if necessary.
        (Section 4.4) (tool support)

   8.   Ranges SHOULD be defined, if appropriate.  (Section 4.4) (tool
        support)

   9.   Non-reversible Information Elements (see [RFC5103]) SHOULD note
        non-reversibility in the description.  (Section 4.8)

   10.  The Information Element Identifier assigned by IANA for IEs not
        compatible with their counterparts in NetFlow V9 SHOULD be the
        lowest available identifier above 128.  (Section 4.3) (tool
        support)

   11.  Information Elements to be registered with IANA SHOULD be
        intended for implementation and deployment on production
        networks.

8.  Applying IPFIX to non-Flow Applications

   At the core of IPFIX is its definition of a Flow, a set of packets
   sharing some common properties crossing an Observation Point within a
   certain time window.  However, the reliance on this definition does
   not preclude the application of IPFIX to domains which are not
   obviously handling flow data according to this definition.  Most
   network management data collection tasks, those to which IPFIX is
   most applicable, have at their core the movement of packets from one
   place to another; by a liberal interpretation of the common
   properties defining the flow, then, almost any event handled by these
   can be held to concern data records conforming to the IPFIX
   definition of a Flow.

   Non-flow information defining associations or key-value pairs, on the
   other hand, are defined by IPFIX Options Templates.  Here, the

Trammell & Claise        Expires March 23, 2013                [Page 21]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   Information Elements within an Options Template Record are divided
   into Scope Information Elements which define the key, and non-scope
   Information Elements which define the values associated with that
   key.  Unlike Flows, Data Records defined by Options Template are not
   necessarily scoped in time; these Data Records are generally held to
   be in effect until a new set of values for a specific set of keys is
   exported.  While this mechanism is often used by IPFIX to export
   metadata about the collection infrastructure, it is applicable to any
   association information.

   An IPFIX application can mix Data Records described either type of
   template in an IPFIX Message or Message stream, and exploit
   relationships among the Flow Keys, values, and Scopes to create
   interrelated data structures.  See [RFC5473] for an example
   application of this.

9.  Writing Internet-Drafts for IPFIX Applications

   When a new application is complex enough to require additional
   clarification or specification as to the use of the defined
   Information Elements, or has particularly this may be given in an
   Internet-Draft.  Internet-Drafts for new IPFIX applications are best
   submitted to a Working Group with expertise in the area of the new
   application, or as independent submissions.

   When defining new Information Elements in an Internet-Draft, the
   Internet-Draft SHOULD contain a section (or subsection) for each
   Information Element, which contains the attributes in Section 4 in
   human-readable form.  An example subsection is given below.  These
   Information Element descriptions SHOULD NOT assign Information
   Element numbers, instead using placeholder identifiers for these
   numbers (e.g.  "TBD1", "TBD2", "TBD3") and a note to IANA in the IANA
   Considerations section to replace those placeholders in the document
   with Information Element numbers when the numbers are assigned.  The
   use of these placeholder definitions allows references to the numbers
   in e.g. box-and-line diagrams or template definitions as in
   Section 10.

9.1.  Example Information Element Definition

   This is an example of an Information Element definition which would
   appear in an Internet-Draft.  The name appears in the section title.

Trammell & Claise        Expires March 23, 2013                [Page 22]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   Description:   Description goes here.; obligatory

   Data Type:   Data type goes here; obligatory

   Data Type Semantics:   Data type semantics, if any, go here; optional

   Units:   Units, if any, go here; optional

   Range:   Range, if not implied by the data type, goes here; optional

   References:   References to other RFCs or documents outside the IETF,
      in which additional information is given, or which are referenced
      by the description, go here; optional

   ElementId:   ElementId, if known, or TBD to be filled in by IANA at
      publication time.

9.2.  Defining Recommended Templates

   New IPFIX applications SHOULD NOT, in the general case, define fixed
   templates for export, as this throws away much of the flexibility
   afforded by IPFIX.  However, fixed template export is permissible in
   the case that the export implementation must operate in a resource
   constrained environment, and/or that the application is replacing an
   existing fixed-format binary export format in a maximally compatible
   way.  In any case, Collecting Processes for such applications SHOULD
   support the collection Templates with Information Elements in any
   order, or Templates with additional Information Elements.

   An Internet-Draft clarifying the use of new Information Elements
   SHOULD include any recommended Template or Options Template Records
   necessary for supporting the application, as well as examples of
   records exported using these Template Records.  In defining these
   Template Records, such Internet-Drafts SHOULD mention, subject to
   rare exceptions:

   1.  that the order of different Information Elements within a
       Template is not significant;

   2.  that Templates on the wire for the application may also contain
       additional Information Elements beyond those specified in the
       recommended Template;

   3.  that a stream of IPFIX Messages supporting the application may
       also contain Data Records not described by the recommended
       Templates; and

Trammell & Claise        Expires March 23, 2013                [Page 23]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   4.  that any reader of IPFIX Messages supporting the application MUST
       accept these conditions.

   Definitions of recommended Template Records for flow-like
   information, where the Flow Key is well-defined, SHOULD indicate
   which of the Information Elements in the recommended Template are
   Flow Keys.

   Recommended Templates are defined, for example, in [RFC5476] for
   PSAMP packet reports (section 6.4) and extended packet reports
   (section 6.5).  Recommended Options Templates are defined extensively
   throughout the IPFIX documents, including in the protocol document
   itself [I-D.ietf-ipfix-protocol-rfc5101bis] for exporting export
   statistics; in the file format [RFC5655] for exporting file metadata;
   and in Mediator intermediate process definitions such as [RFC6235]
   for intermediate process metadata.  The discussion in these examples
   is a good model for recommended template definitions.

10.  A Textual Format for Specifying Information Elements and Templates

   Example Templates given in existing IPFIX documents are generally
   expressed using bitmap diagrams of the respective Templates.  These
   are illustrative of the wire representation of simple Templates, but
   not particularly readable for more complicated recommended Templates,
   provide no support for rapid implementation of new Templates, and do
   not adequately convey the optional nature of ordering and additional
   Information Elements.  Therefore, we define a RECOMMENDED textual
   format for specifying Information Elements and Templates in Internet-
   Drafts in this section.

   Here we define 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.

10.1.  Information Element Specifiers

   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

Trammell & Claise        Expires March 23, 2013                [Page 24]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   new Information Elements within an Information Model, while either
   fully-qualified or partial IESpecs may be used to define fields in a
   Template.

   Bare words are used for Information Element names, and each aspect of
   information associated with an Information Element is associated with
   a type of brackets:

   o  () parentheses for Information Element numbers,

   o  <> angles for Information Element data types, and

   o  [] square brackets for Information Element sizes.

   o  {} curly braces contain an optional space-separated list of
      context identifiers to be associated with an Information Element,
      as described in more detail in Section 10.2

   The symbol + is reserved for Information Element nesting within
   structured data elements; these are described in Section 10.3.

   Whitespace in IESpecs is insignificant; spaces can be added after
   each element in order, e.g., to align columns for better readability.

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

   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

Trammell & Claise        Expires March 23, 2013                [Page 25]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   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.  A partial IESpec is assumed to take
   missing values from its canonical definition in the IANA IE 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)

10.2.  Specifying Templates

   A Template can then be defined simply as an ordered, newline-
   separated sequence of IESpecs.  IESpecs in example Templates
   illustrating a new application of IPFIX SHOULD be fully-qualified.
   Flow Keys may be optionally annotated by appending the {key} context
   to the end of each Flow Key specifier.  A template counting packets
   and octets per five-tuple with millisecond precision in IESpec syntax
   is shown below.

Trammell & Claise        Expires March 23, 2013                [Page 26]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   flowStartMilliseconds(152)<dateTimeMilliseconds>[8]
   flowEndMilliseconds(153)<dateTimeMilliseconds>[8]
   octetDeltaCount(1)<unsigned64>[8]
   packetDeltaCount(2)<unsigned64>[8]
   sourceIPv4Address(8)<ipv4Address>[4]{key}
   destinationIPv4Address(12)<ipv4Address>[4]{key}
   sourceTransportPort(7)<unsigned16>[2]{key}
   destinationTransportPort(11)<unsigned16>[2]{key}
   protocolIdentifier(4)<unsigned8>[1]{key}

               Fig. 1: Sample flow template in IESpec syntax

   An Options Template is specified similarly.  Scope is specified
   appending the {scope} context to the end of each IESpec for a Scope
   IE.  Due to the way Information Elements are represented in Options
   Templates, all {scope} IESpecs must appear before any non-scope
   IESpec.  The Flow Key Options Template defined in section 4.4 [RFC-
   EDITOR NOTE: verify section number] of
   [I-D.ietf-ipfix-protocol-rfc5101bis] in IESpec syntax is shown below:

   templateId(145)<unsigned16>[2]{scope}
   flowKeyIndicator(173)<unsigned64>[8]

            Fig. 2: Flow Key Options Template in IESpec syntax

10.3.  Specifying IPFIX Structured Data

   IESpecs can also be used to illustrate the structure of the
   information exported using the IPFIX Structured Data extension
   [RFC6313].  Here, the semantics of the structured data elements are
   specified using contexts, and the information elements within each
   structured data element follow the structured data element, prefixed
   with + to show they are contained therein.  Arbitrary nesting of
   structured data elements is possible by using multiple + signs in the
   prefix.  For example, a basic list of IP addresses with "one or more"
   semantics would be expressed using partially qualified IESpecs as
   follows:

   basicList{oneOrMoreOf}
   +sourceIPv4Address(8)[4]

                 Fig. 3: Sample basicList in IESpec syntax

   And an example subTemplateList itself containing a basicList is shown
   below:

Trammell & Claise        Expires March 23, 2013                [Page 27]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   subTemplateList{allOf}
   +basicList{oneOrMoreOf}
   ++sourceIPv4Address(8)[4]
   +destinationIPv4Address(12)[4]

              Fig. 4: Sample subTemplateList in IESpec syntax

   This describes a subTemplateMultilist containing all of the expressed
   set of source-destination pairs, where the source address itself
   could be one of any number in a basicList (e.g., in the case of SCTP
   multihoming).

   The contexts associable with structured data Information Elements are
   the semantics, as defined in section 4.4 of [RFC6313]; a structured
   data Information Element without any context is taken to have
   undefined semantics.  More information on the application of
   structured data is available in [RFC6313].

11.  Security Considerations

   The IE-DOCTORS MUST evaluate the security aspects of new Information
   Elements in light of the information they could provide to support
   potential attacks against the measured network or entities about
   which information is exported.  Specific security aspects to evaluate
   include whether the exported information contains personally
   identifiable information, or information which should be kept
   confidential about the described entities (e.g. partial payload, or
   configuration information which could be exploited).  This is not to
   say that such Information Elements should not be defined, but there
   must be an evaluation of the security risk versus the utility of the
   exported information for the intended application.  For example, "A
   Framework for Packet Selection and Reporting" [RFC5474] concluded in
   section 12.3.2 that the hash functions private parameters should not
   exported within IPFIX.

   Security considerations specific to an Information Element MUST be
   addressed in the Security Considerations section of the Internet-
   Draft describing the Information Element, or in the Information
   Element description itself in case the Information Element is not
   defined in an Internet-Draft.  It is RECOMMENDED that Information
   Elements with specific security considerations be described in an
   Internet-Draft.

   For example, the ipHeaderPacketSection in the IPFIX IE registry
   mentions: "This Information Element, which may have a variable
   length, carries a series of octets from the start of the IP header of
   a sampled packet.  With sufficient length, this element also reports

Trammell & Claise        Expires March 23, 2013                [Page 28]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   octets from the IP payload, subject to [RFC2804].  See the Security
   Considerations section."  Another example can be seen in the "Packet
   Sampling (PSAMP) Protocols Specification" [RFC5476] specifies: "In
   the basic Packet Report, a PSAMP Device exports some number of
   contiguous bytes from the start of the packet, including the packet
   header (which includes link layer, network layer and other
   encapsulation headers) and some subsequent bytes of the packet
   payload.  The PSAMP Device SHOULD NOT export the full payload of
   conversations, as this would mean wiretapping [RFC2804].  The PSAMP
   Device MUST respect local privacy laws."

12.  IANA Considerations

   With respect to the management of the IANA IPFIX Information Elements
   Registry and associated subregistries located at
   [iana-ipfix-assignments], this document defines a process for IANA in
   Section 5.1, and includes a set of guidelines for IANA for applying
   this process in Section 4, Section 5, and Section 6.

   The IE-DOCTORS experts and the NetFlow V9 expert mentioned within
   this document are to be appointed by the IESG.

   In addition, in order to support more effective management of the
   Information Element lifecycle as defined in Section 5, this document
   specifies the addition of two new columns for the registry:

   Revision:   a serial revision number for each Information Element,
      beginning at 0 for all presently existing and newly created
      Information Elements.  This column is to be managed by IANA in
      order to support the process defined in Section 5.2, and need not
      be present in any Information Element definition.

   Date:   the date at which the Information Element was created or last
      modified.  This column is to be managed by IANA in order to
      support the process defined in Section 5.2, and need not be
      present in any Information Element definition.

   Any additions to the registry which themselves require subregistries
   of enumerated values MUST define those subregistries to be subject to
   Expert Review [RFC5226].

   [IANA NOTE: Note that the examples in Appendix A are NOT to be added
   to the IPFIX Information Element registry upon the publication of
   this document.]

Trammell & Claise        Expires March 23, 2013                [Page 29]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

13.  Acknowledgements

   Thanks to Paul Aitken, Andrew Feren, and Dan Romascanu for their
   reviews and feedback.  Thanks as well to Roni Even and Yoav Nir for
   their area reviews.  This work is materially supported by the
   European Union Seventh Framework Programme under grant agreement
   257315 (DEMONS).

14.  References

14.1.  Normative References

   [I-D.ietf-ipfix-protocol-rfc5101bis]
              Claise, B. and B. Trammell, "Specification of the IP Flow
              Information eXport (IPFIX) Protocol for the Exchange of
              Flow Information", draft-ietf-ipfix-protocol-rfc5101bis-02
              (work in progress), June 2012.

   [I-D.ietf-ipfix-information-model-rfc5102bis]
              Claise, B. and B. Trammell, "Information Model for IP Flow
              Information eXport (IPFIX)",
              draft-ietf-ipfix-information-model-rfc5102bis-04 (work in
              progress), August 2012.

   [RFC5103]  Trammell, B. and E. Boschi, "Bidirectional Flow Export
              Using IP Flow Information Export (IPFIX)", RFC 5103,
              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.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              May 2008.

   [RFC6313]  Claise, B., Dhandapani, G., Aitken, P., and S. Yates,
              "Export of Structured Data in IP Flow Information Export
              (IPFIX)", RFC 6313, July 2011.

14.2.  Informative References

   [RFC2804]  IAB and IESG, "IETF Policy on Wiretapping", RFC 2804,
              May 2000.

Trammell & Claise        Expires March 23, 2013                [Page 30]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   [RFC3261]  Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
              A., Peterson, J., Sparks, R., Handley, M., and E.
              Schooler, "SIP: Session Initiation Protocol", RFC 3261,
              June 2002.

   [RFC3954]  Claise, B., "Cisco Systems NetFlow Services Export Version
              9", RFC 3954, October 2004.

   [RFC5102]  Quittek, J., Bryant, S., Claise, B., Aitken, P., and J.
              Meyer, "Information Model for IP Flow Information Export",
              RFC 5102, January 2008.

   [RFC5472]  Zseby, T., Boschi, E., Brownlee, N., and B. Claise, "IP
              Flow Information Export (IPFIX) Applicability", RFC 5472,
              March 2009.

   [RFC5473]  Boschi, E., Mark, L., and B. Claise, "Reducing Redundancy
              in IP Flow Information Export (IPFIX) and Packet Sampling
              (PSAMP) Reports", RFC 5473, March 2009.

   [RFC5474]  Duffield, N., Chiou, D., Claise, B., Greenberg, A.,
              Grossglauser, M., and J. Rexford, "A Framework for Packet
              Selection and Reporting", RFC 5474, March 2009.

   [RFC5476]  Claise, B., Johnson, A., and J. Quittek, "Packet Sampling
              (PSAMP) Protocol Specifications", RFC 5476, March 2009.

   [RFC5477]  Dietz, T., Claise, B., Aitken, P., Dressler, F., and G.
              Carle, "Information Model for Packet Sampling Exports",
              RFC 5477, March 2009.

   [RFC5560]  Uijterwaal, H., "A One-Way Packet Duplication Metric",
              RFC 5560, May 2009.

   [RFC5655]  Trammell, B., Boschi, E., Mark, L., Zseby, T., and A.
              Wagner, "Specification of the IP Flow Information Export
              (IPFIX) File Format", RFC 5655, October 2009.

   [RFC6235]  Boschi, E. and B. Trammell, "IP Flow Anonymization
              Support", RFC 6235, May 2011.

   [iana-ipfix-assignments]
              Internet Assigned Numbers Authority, "IP Flow Information
              Export Information Elements
              (http://www.iana.org/assignments/ipfix/ipfix.xml)".

Trammell & Claise        Expires March 23, 2013                [Page 31]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

Appendix A.  Example Information Element Definitions

   This section contains a few example Information Element definitions
   as they would appear in an Internet-Draft.  Note the conformance of
   these examples to the guidelines in Section 4.

   The sipResponseStatus Information Element (Appendix A.1) illustrates
   the addition of an Information Element representing Layer 7
   application information, with a reference to the registry containing
   the allowable values.  The duplicatePacketDeltaCount Information
   Element (Appendix A.2) illustrates the addition of a new metric, with
   a reference to the RFC defining the metric.  The ambientTemperature
   Information Element (Appendix A.3) illustrates the addition of a new
   measured value outside the area of traditional networking
   applications.

A.1.  sipResponseStatus

   Description:   The SIP Response code as an integer, as in the
      Response Codes registry at
      http://www.iana.org/assignments/sip-parameters defined in
      [RFC3261] and amended in subsequent RFCs.  The presence of this
      Information Element in a SIP Message record marks it as describing
      a SIP response; if absent, the record describes a SIP request.

   Data Type:   unsigned16

   Data Type Semantics:   identifier

   References:   [RFC3261]

   ElementId:   TBD

   Replaces Enterprise-Specific Element:  35566 / 412

A.2.  duplicatePacketDeltaCount

   Description:   The number of uncorrupted and identical additional
      copies of each individual packet in the Flow arriving at the
      destination since the previous Data Record for this Flow (if any),
      as measured at the Observation Point.  This is measured as the
      Type-P-one-way-packet-duplication metric defined in section 3 of
      [RFC5560].

   Data Type:   unsigned64

Trammell & Claise        Expires March 23, 2013                [Page 32]
Internet-Draft              IPFIX IE-DOCTORS              September 2012

   Data Type Semantics:   deltaCounter

   Units:   packets

   References:   [RFC5560]

   ElementId:   TBD

A.3.  ambientTemperature

   Description:   An ambient temperature observed by measurement
      equipment at an Observation Point, positioned such that it
      measures the temperature of the surroundings (i.e., not including
      any heat generated by the measuring or measured equipment),
      expressed in degrees Celsius.

   Data Type:   float

   Units:   degrees Celsius

   Range:   -273.15 - +inf

   ElementId:   TBD

Authors' Addresses

   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

   Benoit Claise
   Cisco Systems, Inc.
   De Kleetlaan 6a b1
   1831 Diegem
   Belgium

   Phone: +32 2 704 5622
   Email: bclaise@cisco.com

Trammell & Claise        Expires March 23, 2013                [Page 33]