One document matched: draft-ietf-ipfix-ie-doctors-04.xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc ipr="trust200902" category="bcp" docName="draft-ietf-ipfix-ie-doctors-04.txt">
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<front>
<title abbrev="IPFIX IE-DOCTORS">
Guidelines for Authors and Reviewers of IPFIX Information Elements
</title>
<author initials="B." surname="Trammell" fullname="Brian Trammell">
<organization abbrev="ETH Zurich">
Swiss Federal Institute of Technology Zurich
</organization>
<address>
<postal>
<street>Gloriastrasse 35</street>
<city>8092 Zurich</city>
<country>Switzerland</country>
</postal>
<phone>+41 44 632 70 13</phone>
<email>trammell@tik.ee.ethz.ch</email>
</address>
</author>
<author initials="B." surname="Claise" fullname="Benoit Claise">
<organization abbrev="Cisco Systems, Inc.">
Cisco Systems, Inc.
</organization>
<address>
<postal>
<street>De Kleetlaan 6a b1</street>
<city>1831 Diagem</city>
<country>Belgium</country>
</postal>
<phone>+32 2 704 5622</phone>
<email>bclaise@cisco.com</email>
</address>
</author>
<date month="August" day="31" year="2012"/>
<area>Operations</area>
<workgroup>IPFIX Working Group</workgroup>
<abstract>
<t>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.</t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="sec-intro">
<t> 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 <xref target="RFC5472">"IPFIX Applicability
Statement"</xref>. These new applications are largely defined by
creating new Information Elements beyond those in the <xref
target="iana-ipfix-assignments">IANA IPFIX Information Element
Registry</xref>. New applications may be further specified through
additional RFCs defining and describing their usage.</t>
<t>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.</t>
<section title="Intended Audience and Usage" anchor="sec-audience">
<t>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 <xref
target="iana-ipfix-assignments">IANA IPFIX Information Element
Registry</xref>, it
defines a set of acceptance criteria against which these proposed
Information Elements should be evaluated.</t>
<t>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.</t>
<t>This document, together with <xref
target="I-D.ietf-ipfix-information-model-rfc5102bis"/>, defines
the procedures for management of the <xref
target="iana-ipfix-assignments">IANA IPFIX Information Element
Registry</xref>. 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 <xref target="RFC5226"/>.</t>
</section>
<section title="Overview of relevant IPFIX documents">
<t>[EDITOR'S NOTE: review this section to make sure "this document"
is always unambiguous.]</t>
<t><xref target="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.</t>
<t><xref target="I-D.ietf-ipfix-information-model-rfc5102bis"/>
defines the basis of the IPFIX Information Model, referring to
<xref target="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. </t>
<t><xref target="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.</t>
<t><xref target="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
<xref target="I-D.ietf-ipfix-protocol-rfc5101bis"/> and <xref
target="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 <xref
target="sec-ie-semantics"/>.</t>
</section>
</section>
<section title="Terminology" anchor="terminology-section">
<t>Capitalized terms used in this document that are defined in the
Terminology section of <xref
target="I-D.ietf-ipfix-protocol-rfc5101bis"/> are to be interpreted as
defined there.</t>
<t>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 <xref
target="RFC5472">IPFIX Applicability statement</xref>. By this
definition, <xref target="RFC5476">PSAMP</xref> was the first new
IPFIX application after the publication of the IPFIX protocol
itself.</t>
<t>"IANA IE registry", as used in this document, unless otherwise noted,
refers to the <xref target="iana-ipfix-assignments">IANA IPFIX
Information Element Registry</xref>.</t>
<t>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 <xref
target="RFC2119"/>.</t>
</section>
<section title="How to apply IPFIX" anchor="sec-howto">
<t>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
<xref target="RFC5476">PSAMP</xref>, any application with the
following characteristics is a good candidate for an IPFIX
application:</t>
<t><list style="symbols">
<t>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.</t>
<t>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.</t>
<t>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.</t>
<t>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).</t>
</list></t>
<t>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 <xref
target="sec-ie-reuse"/> for guidelines on maximizing Information
Element reuse). In this case, no work within the IETF is necessary:
simply define Templates and start exporting.</t>
<t>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 <xref target="sec-iedef"/> for best practices to be
followed in defining Information Elements.</t>
<t>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 <xref
target="sec-iedef"/>, as well as suggested Templates and examples of
the use of those Templates within the new application as in <xref
target="sec-templates"/>. <xref target="sec-iespec"/> defines a
compact textual Information Element notation to be used in describing
these suggested Templates and/or the use of <xref
target="RFC6313">IPFIX Structured Data</xref> within the new
application.</t>
</section>
<section title="Defining new Information Elements" anchor="sec-iedef">
<t>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:</t>
<t><list style="symbols">
<t>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.</t>
<t>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
<xref target="RFC6313">IPFIX Structured Data</xref>, as in <xref
target="sec-ie-structure"/>; 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.</t>
<t>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
section 3.2 [RFC-EDITOR NOTE: verify section number] of <xref
target="I-D.ietf-ipfix-protocol-rfc5101bis"/>.</t>
</list></t>
<t>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 (itself extensible via Standards
Action as per <xref target="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 <xref
target="I-D.ietf-ipfix-information-model-rfc5102bis"/> as
appropriate.</t>
<section title="Information Element naming" anchor="sec-ie-names">
<t>Information Element Names should be defined in accordance with
section 2.3 [RFC-EDITOR NOTE: verify section number] of <xref
target="I-D.ietf-ipfix-information-model-rfc5102bis"/>; the most
important naming conventions are repeated here for
convenience.</t>
<t><list style="symbols">
<t>Names of Information Elements SHOULD be descriptive.</t>
<t>Names of Information Elements MUST be unique within the
IANA IE registry.</t>
<t>Names of Information Elements MUST start with
non-capitalized letters.</t>
<t>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."</t>
</list></t>
<t>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.</t>
</section>
<section title="Information Element data types" anchor="sec-ie-types">
<t>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 <xref
target="iana-ipfix-assignments"/>. This subregistry may be
extended from time to time by a Standards Action as per <xref
target="RFC5226"/>.</t>
<t>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.</t>
<t>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 <xref
target="I-D.ietf-ipfix-protocol-rfc5101bis"/> in cases where fewer
than 2^64 values are necessary.</t>
<t>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.</t>
<t>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.</t>
<t>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.</t>
<t>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 <xref target="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.</t>
</section>
<section title="Information Element numbering" anchor="sec-ie-numbering">
<t>Each Information Element has a unique identifier in the IANA
registry.</t>
<t>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 <xref
target="iana-ipfix-assignments"/> in the range 128-32767, noting
that prior noncontiguous allocation may lead to unassigned
Information Elements with lower Information Element identifiers
than some presently assigned Information Elements.</t>
<t>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 <xref target="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.</t>
</section>
<section title="Ancillary Information Element properties"
anchor="sec-ie-semantics">
<t>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 <xref
target="I-D.ietf-ipfix-information-model-rfc5102bis"/>, subject to
the restrictions given in Section 3.10 of <xref
target="RFC5610"/>; in other words, the semantics and the type
MUST be consistent.</t>
<t>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 is maintained
on a First Come, First Served basis.</t>
<t>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.</t>
</section>
<section title="Internal structure in Information Elements" anchor="sec-ie-structure">
<t>The definition of Information Elements with
internal structure with the structure defined in the Description
field is NOT RECOMMENDED, except in the following cases:</t>
<t><list style="numbers">
<t>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)</t>
<t>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)</t>
<t>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)</t>
<t>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</t>
</list></t>
<t>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 <xref
target="RFC6313">IPFIX Structured
Data</xref> extension instead.</t>
<t>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 <xref
target="sec-ie-reuse"/>.</t>
<t>The decomposition of data with internal structure SHOULD avoid
the 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.</t>
</section>
<section title="Information Element multiplicity" anchor="sec-ie-multiplicity">
<t>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:</t>
<t><list style="numbers">
<t>As specified in section 8 [RFC-EDITOR NOTE: verify section
number] of <xref
target="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.</t>
<t>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 <xref target="RFC6313">IPFIX
Structured Data</xref> extension.</t>
<t>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.</t>
</list></t>
<t>Specifically, new Information Element SHOULD NOT encode any
multiplicity or ordinality information into the definition of the
Information Element itself.</t>
</section>
<section title="Enumerated Values and Subregistries" anchor="sec-ie-subreg">
<t>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
<xref target="RFC5226">Expert Review</xref>.</t>
</section>
<section title="Reversibility as per RFC 5103" anchor="ie-reversibility">
<t><xref target="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, <xref target="RFC5103"/>
enumerates those Information Elements which were defined at
the time of its publication which are NOT reversible.</t>
<t>New non-reversible Information Elements MUST contain a note
in the description stating that they are not reversible. </t>
</section>
<!-- <section title="Promotion of Enterprise-Specific Information Elements" anchor="ie-promotion">
<t>Some Information Elements may start their lifecycle outside the
IANA IE registry as enterprise-specific Information Elements scoped to a
Private Enterprise Number. One stated goal of enterprise-specific
Information Elements is pre-standards product delivery and
experimentation; should these experiments be successful and the
Information Elements generally useful, these SHOULD subsequently
registered with IANA.</t>
<t>In order to support transition from experimental registration to
IANA registration, the IANA IE registry provides an optional
"enterprise-specific IE reference" column for each Information
Element. In cases of promoted enterprise-specific Information
Elements, this column in the registry MAY contain the private
enterprise and Information Element numbers of the enterprise-specific
version(s) of the Information Element.</t>
</section> -->
<section title="Avoiding Bad Ideas in Information Element Design" anchor="ie-dont-do-this">
<t>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.</t>
<t>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 <xref
target="RFC5103"/>) and initiatorPackets and responderPackets (the
same, for packetDeltaCount). [EDITOR'S NOTE: verify whether these are
delta counts or total counts]</t>
<t>As mentioned in <xref target="sec-ie-types"/>, 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.</t>
<t>As mentioned in <xref target="sec-ie-multiplicity"/>, 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 <xref
target="RFC6313">IPFIX Structured Data</xref>
where supported, as a basicList of MPLS label entries, or as a raw
MPLS label stack using the variable-length mplsLabelStackSection
Information Element.</t>
</section>
</section>
<section title="The Information Element Lifecycle" anchor="sec-lifecycle">
<t>Once an Information Element or set of Information Elements has been
identified for a given application, Information Element specifications
in accordance with <xref target="sec-iedef"/> 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.</t>
<section title="The IE-DOCTORS process" anchor="sec-process">
<t>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 <xref target="RFC5226"/> policy
defined for the IANA IE registry. 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.</t>
<t>Authors are expected to review compliance with the specifications
in this document to check their submissions before sending them to
IANA.</t>
<t>IE-DOCTORS reviewers should endeavor to complete referred reviews
in a timely manner. If the request is acceptable, the IE-DOCTORS
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.</t>
<t>IE-DOCTORS decisions may be appealed as in section 7 of <xref
target="RFC5226"/>.</t>
</section>
<section title="Revising Information Elements" anchor="sec-revision">
<t>The Information Element status field in the IANA IE registry is
defined in <xref
target="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. <xref target="RFC5102"/>
additionally specified an 'obsolete' status; however, this has been
removed on revision as it served no operational purpose.</t>
<t>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.</t>
<t>Changes are initiated by sending a new Information Element
definition to IANA, as in <xref target="sec-process"/>, for an
already-existing Information Element.</t>
<t>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.</t>
<t>A change to an Information Element is held to be interoperable only
when:</t>
<t><list style="numbers">
<t>it involves the correction of an error which is obviously only
editorial; or</t>
<t>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</t>
<t>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</t>
<t>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</t>
<t>it defines a previously undefined or reserved enumerated value,
or one or more previously reserved bits in an Information Element
with flag semantics; or</t>
<t>it expands the set of permissible values in the Information
Element's range; or</t>
<t>it harmonizes with an external reference which was itself
corrected.</t>
</list></t>
<!--
<t>A non-interoperable Information Element change may also be made if
it can be reasonably assumed in the eyes of the appointed experts that
no unchanged implementation of the Information Element exists; this
can be held to happen if a non-interoperable change to an Information
Element defined shortly before is proposed to the IPFIX mailing list
by the original proposer of the Information Element, and no objection
is raised within a reasonable amount of time, to be defined by the
expert reviewers. [EDITOR'S NOTE: objection from Dan Romascanu, to
discuss on list]</t>
-->
<t>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.</t>
<t>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.</t>
<t>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.</t>
<t>Information Elements with identifiers in the range 1-127 are
compatible with the NetFlow V9 protocol as described in <xref
target="RFC3954"/>; to maintain this compatibility, all revisions to
such Information Elements are subject to additional review by the
appointed NetFlow V9 expert.</t>
</section>
<section title="Deprecating Information Elements" anchor="sec-deprecation">
<t>Changes that are not permissible by these criteria may only be
handled by deprecation. An Information Element MAY be deprecated and
replaced when:</t>
<t><list style="numbers">
<t>the Information Element definition has an error or shortcoming
which cannot be permissibly changed as in <xref
target="sec-revision"/>; or</t>
<t>the deprecation harmonizes with an external reference which was
itself deprecated through that reference's accepted deprecation
method; or</t>
<t>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.</t>
</list></t>
<t>A request for deprecation is sent to IANA, which passes it to the
IE-DOCTORS for review, as in <xref target="sec-process"/>. When
deprecating an Information Element, the Information Element
description MUST be updated to explain the deprecation, as well as to
refer to any new Information Elements created to replace the
deprecated Information Element.</t>
<t>The Revision number of an Information Element is incremented upon
deprecation, and the revision Date updated, as with any revision.</t>
<t>Information Elements with identifiers in the range 1-127 are
compatible with the NetFlow V9 protocol as described in <xref
target="RFC3954"/>; to maintain this compatibility, all deprecations
of such Information Elements are subject to additional review by the
appointed NetFlow V9 expert.</t>
<t>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.</t>
<!-- <t>After a period of time determined in the eyes of the
IE-DOCTORS experts to be reasonable in order to allow deployed
Exporting Processes to be updated to account for the deprecation, a
deprecated Information Element may be made obsolete. Obsolete
Information Elements MUST NOT be supported by either Exporting or
Collecting Processes. The receipt of obsolete Information Elements
SHOULD be logged by the Collecting Process.</t> -->
<t>Names and elementIDs of deprecated Information Elements
MUST NOT be reused.</t>
</section>
<!--
<section title="Versioning the entire IANA IE registry">
<t>Consider a typical Collector implementation, which regularly
downloads the entire registry in order to be compliant with the latest
of set of supported IEs. While a registry revision number might seems
advantageous for the Collector at first glance (avoiding the one by
one comparison of all IE revisions), it is not necessary, as the IPFIX
IANA IE registry specifies the date at which the registry was last
updated in the "Last Updated" field. For purposes of identifying the
latest set of Information Element versions specified in registry, the
last revision date of the Information Element registry (available in
the registry XML source, or from the Last-Modified: header of <xref
target="iana-ipfix-assignments"/>) SHOULD be used.</t>
</section>
-->
</section>
<section title="When not to define new Information Elements" anchor="sec-noie">
<t>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 <xref target="ie-enterprise"/> instead.
</t>
<t>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.</t>
<section title="Maximizing reuse of existing Information Elements" anchor="sec-ie-reuse">
<t>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.</t>
<t>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.</t>
<t>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.</t>
<t>Applications dealing with bidirectional interactions should use
<xref target="RFC5103">Bidirectional Flow Support for IPFIX</xref>
to represent these interactions.</t>
<t>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 timing information (e.g., an
IPFIX-exported record containing information about an event to be
scheduled in the future).</t>
<t>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.</t>
</section>
<section title="Applying enterprise-specific Information Elements" anchor="ie-enterprise">
<t>IPFIX provides a mechanism for defining enterprise-specific
Information Elements, as in Section 3.2 [RFC-EDITOR NOTE: verify
section number] of <xref
target="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.</t>
<t>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:</t>
<t><list style="symbols">
<t>export of implementation-specific information, or</t>
<t>export of information supporting research or experiments
within a single organization or closed community, or</t>
<t>export of information derived in a commercially-sensitive
or proprietary method, or</t>
<t>export of information or meta-information specific to a
commercially-sensitive or proprietary application.</t>
</list></t>
<t>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. Instead, these experimental Information Elements
SHOULD be represented as enterprise-specific until their
definitions are finalized.</t>
<!-- <t>then transitioned from enterprise-specific to
IANA-defined upon finalization. To support this transition, the
IANA IE registry provides an experimental IE reference as defined in
<xref target="ie-promotion"/>.</t> -->
</section>
</section>
<section title="Information Element Definition Checklist">
<t>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 <xref target="sec-revision"/>, and deprecation should follow the
process defined in <xref target="sec-deprecation"/>.</t>
<t>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.</t>
<t>Checklist 1 contains conditions which MUST be met by all proposed
Information Elements:</t>
<t><list style="numbers">
<t>The name MUST be unique within the IANA IE registry, and not
reuse the name of any current, deprecated, or obsolete Information
Element. (<xref target="sec-ie-names"/>) (tool support)</t>
<t>The description MUST be sufficiently semantically unique within
the IANA IE registry, representing a substantially different
meaning from any current, deprecated, or obsolete Information
Element. (<xref target="sec-iedef"/>)</t>
<t>The name MUST start with a non-capitalized letter. (<xref
target="sec-ie-names"/>) (tool support)</t>
<t>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
are made for acronyms containing non-capitalized letters, such as
'IPv4' and 'IPv6'. (<xref target="sec-ie-names"/>) (tool
support)</t>
<t>The data type MUST match the type of the data being represented.
(<xref target="sec-ie-types"/>)</t>
<t>Data type semantics MUST be appropriate for the data type.
(<xref target="sec-ie-semantics"/>) (tool support)</t>
<t>The Information Element identifier assigned by IANA MUST be
unique. (<xref target="sec-ie-numbering"/>) (tool support)</t>
<t>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 <xref target="RFC3954"/>.
(<xref target="sec-ie-numbering"/>)</t>
</list></t>
<t>Checklist 2 contains conditions which MUST be met by proposed
Information Elements with certain properties, as noted:</t>
<t><list style="numbers">
<t>Time values MUST be defined with appropriate precision. (<xref
target="sec-ie-types"/>)</t>
<t>Strings and octet arrays with length restrictions MUST note
those length restrictions in their descriptions. (<xref
target="sec-ie-types"/>)</t>
<t>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 <xref
target="RFC5226">Expert Review</xref>. (<xref
target="sec-ie-subreg"/>)</t>
</list></t>
<t>Checklist 3 contains conditions which SHOULD be met by proposed
Information Elements:</t>
<t><list style="numbers">
<t>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. (<xref target="sec-ie-names"/>)</t>
<t>Information Elements representing integral values SHOULD use a
data type for the appropriate width for the value. (<xref
target="sec-ie-types"/>)</t>
<t>Information Elements representing counters or identifiers SHOULD
be represented as signed64 or unsigned64, unless they are naturally
represented with narrower integral types, as appropriate. (<xref
target="sec-ie-types"/>)</t>
<t>An Information Element SHOULD NOT contain internal structure,
subject to the exceptions in <xref target="sec-ie-structure"/>;
candidate Information Elements with internal structure SHOULD be
decomposed into multiple Information Elements. (<xref
target="sec-ie-structure"/>)</t>
<t>An Information Element SHOULD NOT contain multiplicity or
ordinality information within the definition of the Information
Element itself. (<xref target="sec-ie-multiplicity"/>)</t>
<t>Data type semantics SHOULD be defined, if appropriate. (<xref
target="sec-ie-semantics"/>) (tool support)</t>
<t>Units SHOULD be defined, if appropriate, with new units added to
the Information Element Units subregistry if necessary. (<xref
target="sec-ie-semantics"/>) (tool support)</t>
<t>Ranges SHOULD be defined, if appropriate. (<xref
target="sec-ie-semantics"/>) (tool support)</t>
<t>Non-reversible Information Elements (see <xref
target="RFC5103"/>) SHOULD note non-reversibility in the
description. (<xref target="ie-reversibility"/>)</t>
<!-- <t>Information Elements created to replace enterprise-specific
Information Elements used for experimental or testing purposes
SHOULD contain a reference to the enterprise-specific Information
Element they replace. (<xref target="ie-promotion"/>)</t> -->
<t>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. (<xref
target="sec-ie-numbering"/>) (tool support)</t>
<t>Information Elements to be registered with IANA SHOULD BE
intended for implementation and deployment on production
networks.</t>
</list></t>
</section>
<section title="Applying IPFIX to non-Flow Applications" anchor="sec-nonflow">
<t>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.</t>
<t>Non-flow information defining associations or key-value pairs, on
the other hand, are defined by IPFIX Options Templates. Here, the
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.</t>
<t>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 <xref target="RFC5473"/> for an
example application of this.</t>
</section>
<section title="Writing Internet-Drafts for IPFIX Applications" anchor="sec-draft">
<t>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.</t>
<t>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 <xref
target="sec-iedef"/> 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 <xref target="sec-iespec"/>.</t>
<section title="Example Information Element Definition">
<t>This is an example of an Information Element definition which would appear in an Internet-Draft. The name appears in the section title.</t>
<t><list style="hanging">
<t hangText="Description: ">
Description goes here.; obligatory
</t>
<t hangText="Data Type: ">Data type goes here; obligatory</t>
<t hangText="Data Type Semantics: ">Data type semantics, if any, go here; optional</t>
<t hangText="Units: ">Units, if any, go here; optional</t>
<t hangText="Range: ">Range, if not implied by the data type, goes here; optional</t>
<t hangText="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</t>
<t hangText="ElementId: ">ElementId, if known, or TBD to be filled in by IANA at publication time.</t>
<!-- <t hangText="Replaces Enterprise-Specific Element:">If the Information Element replaces an existing enterprise-specific Information Element, the PEN and Information Element number go here, separated by a slash (e.g. 35566/123) as in <xref target="sec-iespec"/>.</t> -->
</list></t>
</section>
<section title="Defining Recommended Templates" anchor="sec-templates">
<t>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.</t>
<t>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:</t>
<t><list style="numbers">
<t>that the order of different Information Elements within a
Template is not significant;</t>
<t>that Templates on the wire for the application may also
contain additional Information Elements beyond those specified
in the recommended Template;</t>
<t>that a stream of IPFIX Messages supporting the application
may also contain Data Records not described by the recommended
Templates; and</t>
<t>that any reader of IPFIX Messages supporting the
application MUST accept these conditions.</t>
</list></t>
<t>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.</t>
<t>Recommended Templates are defined, for example, in <xref
target="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 <xref target="I-D.ietf-ipfix-protocol-rfc5101bis">the protocol document
itself</xref> for exporting export statistics; in the <xref
target="RFC5655">file format</xref> for exporting file metadata;
and in Mediator intermediate process definitions such as <xref
target="RFC6235"/> for intermediate process metadata.
The discussion in these examples is a good model for recommended
template definitions.</t>
</section>
</section>
<section title="A Textual Format for Specifying Information Elements and
Templates" anchor="sec-iespec">
<t>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.</t>
<t>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.</t>
<section title="Information Element Specifiers">
<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>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:</t>
<t><list style="symbols">
<t>() parentheses for Information Element numbers,</t>
<t><> angles for Information Element data types, and</t>
<t>[] square brackets for Information Element sizes.</t>
<t>{} curly braces contain an optional space-separated list of
context identifiers to be associated with an Information
Element, as described in more detail in <xref
target="sec-iespec-templates"/></t>
</list></t>
<t>The symbol + is reserved for Information Element nesting within
structured data elements; these are described in <xref
target="sec-iespec-structured"/>.</t>
<t>Whitespace in IESpecs is insignificant; spaces can be added
after each element in order, e.g., to align columns for better
readability.</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 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.</t>
<t>The basic form of a fully-qualified IESpec for an
enterprise-specific Information Element is as follows:</t>
<t>name(pen/number)<type>[size]</t>
<t>where 'pen' is the Private Enterprise Number as a decimal
integer.</t>
<t>A fully-qualified IESpec is intended to express enough
information about an Information Element to decode and display
Data Records defined by Templates containing that Information
Element. Range, unit, semantic, and description information, as in
<xref target="RFC5610"/>, is not supported by this syntax.</t>
<t>Example fully-qualified IESpecs follow:</t>
<t><list>
<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>
<t>A partial IESpec is any IESpec that is not fully-qualified;
these are useful when defining templates. A partial IESpec is
assumed to take missing values from its canonical definition 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.</t>
<t>Example partial IESpecs follow:</t>
<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></t>
</section>
<section title="Specifying Templates" anchor="sec-iespec-templates">
<t>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.</t>
<figure title="Fig. 1: Sample flow template in IESpec syntax">
<artwork><![CDATA[
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}
]]></artwork></figure>
<t>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 <xref target="I-D.ietf-ipfix-protocol-rfc5101bis"/> in IESpec syntax is shown
below:</t>
<figure title="Fig. 2: Flow Key Options Template in IESpec syntax">
<artwork><![CDATA[
templateId(145)<unsigned16>[2]{scope}
flowKeyIndicator(173)<unsigned64>[8]
]]></artwork></figure>
</section>
<section title="Specifying IPFIX Structured Data" anchor="sec-iespec-structured">
<t>IESpecs can also be used to illustrate the structure of the
information exported using the <xref
target="RFC6313">IPFIX Structured Data
extension</xref>. 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:</t>
<figure title="Fig. 3: Sample basicList in IESpec syntax">
<artwork><![CDATA[
basicList{oneOrMoreOf}
+sourceIPv4Address(8)[4]
]]></artwork></figure>
<t>And an example subTemplateList itself containing a basicList is
shown below:</t>
<figure title="Fig. 4: Sample subTemplateList in IESpec syntax">
<artwork><![CDATA[
subTemplateList{allOf}
+basicList{oneOrMoreOf}
++sourceIPv4Address(8)[4]
+destinationIPv4Address(12)[4]
]]></artwork></figure>
<t>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).</t>
<t>The contexts associable with structured data Information
Elements are the semantics, as defined in section 4.4 of <xref
target="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 <xref
target="RFC6313"/>.</t>
</section>
</section>
<section title="Security Considerations" anchor="security-section">
<t>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" <xref target="RFC5474"/>
concluded in section 12.3.2 that the hash functions private parameters
should not exported within IPFIX.</t>
<t>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.</t>
<t>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
octets from the IP payload, subject to <xref target="RFC2804"/>. See
the Security Considerations section." Another example can be seen in
the "Packet Sampling (PSAMP) Protocols Specification" <xref
target="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 <xref
target="RFC2804"/>. The PSAMP Device MUST respect local privacy laws."
</t>
</section>
<section title="IANA Considerations" anchor="iana-section">
<t>With respect to the management of the IANA IPFIX Information Elements
Registry and associated subregistries located at <xref
target="iana-ipfix-assignments"/>, this document defines a process for
IANA in <xref target="sec-process"/>, and includes a set of guidelines
for IANA for applying this process in <xref target="sec-iedef"/>, <xref
target="sec-lifecycle"/>, and <xref target="sec-noie"/>.</t>
<t>The IE-DOCTORS experts and the NetFlow V9 expert mentioned within
this document are to be appointed by the IESG.</t>
<t>In addition, in order to support more effective management of the
Information Element lifecycle as defined in <xref
target="sec-lifecycle"/>, this document specifies the addition of three
new columns for the registry:</t>
<t><list style="hanging">
<t hangText="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 <xref
target="sec-revision"/>, and need not be present in any Information
Element definition.</t>
<t hangText="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 <xref target="sec-revision"/>,
and need not be present in any Information Element definition.</t>
<!-- <t hangText="Enterprise-specific reference: ">for Information Elements
which where deployed as enterprise-specific Information Elements for
experimentation and testing, and subsequently registered in the IANA
registry, specifies the private enterprise number (PEN)/IE number
pair(s) of the equivalent experimental Information Element(s). Note
that this column may contain more than one entry per Information
Element. This column SHOULD be present in any Information Element
definition referencing an enterprise-specific Information Element, as
in <xref target="ie-promotion"/>.</t> -->
</list></t>
<t>[IANA NOTE: Note that the examples in <xref target="sec-examples"/> are NOT to be
added to the IPFIX Information Element registry upon the publication of
this document.]</t>
</section>
<section title="Acknowledgements">
<t>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).</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.I-D.ietf-ipfix-protocol-rfc5101bis" ?>
<?rfc include="reference.I-D.ietf-ipfix-information-model-rfc5102bis" ?>
<?rfc include="reference.RFC.5103" ?>
<?rfc include="reference.RFC.5610" ?>
<?rfc include="reference.RFC.2119" ?>
<?rfc include="reference.RFC.5226" ?>
<?rfc include="reference.RFC.6313" ?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.2804" ?>
<?rfc include="reference.RFC.3261" ?>
<?rfc include="reference.RFC.3954" ?>
<?rfc include="reference.RFC.5102" ?>
<?rfc include="reference.RFC.5472" ?>
<?rfc include="reference.RFC.5473" ?>
<?rfc include="reference.RFC.5474" ?>
<?rfc include="reference.RFC.5476" ?>
<?rfc include="reference.RFC.5477" ?>
<?rfc include="reference.RFC.5560" ?>
<?rfc include="reference.RFC.5655" ?>
<?rfc include="reference.RFC.6235" ?>
<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"/>
<date/>
</front>
</reference>
</references>
<section title="Example Information Element Definitions" anchor="sec-examples">
<t>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 <xref target="sec-iedef"/>.</t>
<t>The sipResponseStatus Information Element (<xref
target="ex-ie-sip"/>) 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 (<xref
target="ex-ie-ippm"/>) illustrates the addition
of a new metric, with a reference to the RFC defining the metric. The
ambientTemperature Information Element (<xref
target="ex-ie-temp"/>) illustrates the addition of a new
measured value outside the area of traditional networking
applications.</t>
<section title="sipResponseStatus" anchor="ex-ie-sip">
<t><list style="hanging">
<t hangText="Description: ">The SIP Response code as an
integer, as in the Response Codes registry at
http://www.iana.org/assignments/sip-parameters defined in
<xref target="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.</t>
<t hangText="Data Type: ">unsigned16</t>
<t hangText="Data Type Semantics: ">identifier</t>
<t hangText="References: "><xref target="RFC3261"/></t>
<t hangText="ElementId: ">TBD</t>
<t hangText="Replaces Enterprise-Specific Element:">35566 / 412</t>
</list></t>
</section>
<section title="duplicatePacketDeltaCount" anchor="ex-ie-ippm">
<t><list style="hanging">
<t hangText="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 <xref target="RFC5560"/>.</t>
<t hangText="Data Type: ">unsigned64</t>
<t hangText="Data Type Semantics: ">deltaCounter</t>
<t hangText="Units: ">packets</t>
<t hangText="References: "><xref target="RFC5560"/></t>
<t hangText="ElementId: ">TBD</t>
</list></t>
</section>
<section title="ambientTemperature" anchor="ex-ie-temp">
<t><list style="hanging">
<t hangText="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.</t>
<t hangText="Data Type: ">float</t>
<t hangText="Units: ">degrees Celsius</t>
<t hangText="Range: ">-273.15 - +inf</t>
<t hangText="ElementId: ">TBD</t>
</list></t>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 14:39:31 |