idnits 2.17.1 draft-ietf-ipfix-ie-doctors-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 705: '...ormation Element MAY be deprecated and...' RFC 2119 keyword, line 807: '...eltaMicroseconds) MAY be used if high-...' RFC 2119 keyword, line 813: '...wStartSysUpTime) MAY be used only in t...' RFC 2119 keyword, line 1319: '... Device MUST respect local privacy l...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 3, 2012) is 4221 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '4' on line 1267 == Unused Reference: 'RFC5477' is defined on line 1406, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-ipfix-protocol-rfc5101bis-02 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-ipfix-protocol-rfc5101bis' == Outdated reference: A later version (-10) exists of draft-ietf-ipfix-information-model-rfc5102bis-05 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5102 (Obsoleted by RFC 7012) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IPFIX Working Group B. Trammell 3 Internet-Draft ETH Zurich 4 Intended status: BCP B. Claise 5 Expires: April 6, 2013 Cisco Systems, Inc. 6 October 3, 2012 8 Guidelines for Authors and Reviewers of IPFIX Information Elements 9 draft-ietf-ipfix-ie-doctors-07.txt 11 Abstract 13 This document provides guidelines for how to write definitions of new 14 Information Elements for the IP Flow Information Export (IPFIX) 15 protocol. It provides instructions on using the proper conventions 16 for Information Elements to be registered in the IANA IPFIX 17 Information Element registry, and provides guidelines for expert 18 reviewers to evaluate new registrations. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on April 6, 2013. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 1.1. Intended Audience and Usage . . . . . . . . . . . . . . . 4 56 1.2. Overview of relevant IPFIX documents . . . . . . . . . . . 5 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3. How to apply IPFIX . . . . . . . . . . . . . . . . . . . . . . 6 59 4. Defining new Information Elements . . . . . . . . . . . . . . 7 60 4.1. Information Element naming . . . . . . . . . . . . . . . . 8 61 4.2. Information Element data types . . . . . . . . . . . . . . 8 62 4.3. Information Element numbering . . . . . . . . . . . . . . 9 63 4.4. Ancillary Information Element properties . . . . . . . . . 10 64 4.5. Internal structure in Information Elements . . . . . . . . 10 65 4.6. Information Element multiplicity . . . . . . . . . . . . . 11 66 4.7. Enumerated Values and Subregistries . . . . . . . . . . . 12 67 4.8. Reversibility as per RFC 5103 . . . . . . . . . . . . . . 12 68 4.9. Avoiding Bad Ideas in Information Element Design . . . . . 13 69 5. The Information Element Lifecycle . . . . . . . . . . . . . . 14 70 5.1. The IE-DOCTORS process . . . . . . . . . . . . . . . . . . 14 71 5.2. Revising Information Elements . . . . . . . . . . . . . . 15 72 5.3. Deprecating Information Elements . . . . . . . . . . . . . 16 73 6. When not to define new Information Elements . . . . . . . . . 17 74 6.1. Maximizing reuse of existing Information Elements . . . . 17 75 6.2. Applying enterprise-specific Information Elements . . . . 19 76 7. Information Element Definition Checklist . . . . . . . . . . . 19 77 8. Applying IPFIX to non-Flow Applications . . . . . . . . . . . 22 78 9. Writing Internet-Drafts for IPFIX Applications . . . . . . . . 22 79 9.1. Example Information Element Definition . . . . . . . . . . 23 80 9.2. Defining Recommended Templates . . . . . . . . . . . . . . 23 81 10. A Textual Format for Specifying Information Elements and 82 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . 24 83 10.1. Information Element Specifiers . . . . . . . . . . . . . . 25 84 10.2. Specifying Templates . . . . . . . . . . . . . . . . . . . 27 85 10.3. Specifying IPFIX Structured Data . . . . . . . . . . . . . 28 86 11. Security Considerations . . . . . . . . . . . . . . . . . . . 28 87 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 88 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 29 89 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 90 14.1. Normative References . . . . . . . . . . . . . . . . . . . 30 91 14.2. Informative References . . . . . . . . . . . . . . . . . . 30 92 Appendix A. Example Information Element Definitions . . . . . . . 31 93 A.1. sipResponseStatus . . . . . . . . . . . . . . . . . . . . 32 94 A.2. duplicatePacketDeltaCount . . . . . . . . . . . . . . . . 32 95 A.3. ambientTemperature . . . . . . . . . . . . . . . . . . . . 33 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 99 1. Introduction 101 This document provides guidelines for the definition of new IPFIX 102 Information Elements beyond those currently in the IANA IPFIX 103 Information Element Registry [iana-ipfix-assignments]. Given the 104 self-describing nature of the data export format used by IPFIX, the 105 definition of new Information Elements is often sufficient to allow 106 the application of IPFIX to new network measurement and management 107 use cases. 109 We intend this document to enable the application of IPFIX to new 110 areas by experts in the IETF Working Group or Area Directorate, or 111 the community or organization external to the IETF, concerned with 112 the technical details of the protocol or application to be measured 113 or managed using IPFIX. This expansion occurs with the consultation 114 of IPFIX experts informally called IE-DOCTORS. It provides 115 guidelines both for those defining new Information Elements as well 116 as the IE-DOCTORS reviewing them. 118 This document essentially codifies two meta-guidelines: (1) "define 119 new Information Elements that look like existing Information 120 Elements", and (2) "don't define Information Elements unless you need 121 to". 123 1.1. Intended Audience and Usage 125 This document is meant for two separate audiences. For those 126 defining new Information Elements, it provides specifications and 127 best practices to be used in deciding which Information Elements are 128 necessary for a given existing or new application, instructions for 129 writing the definitions for these Information Elements, and 130 information on the supporting documentation required for the new 131 application (up to and including the publication of one or more RFCs 132 describing it). For the IPFIX experts appointed as IE-DOCTORS, and 133 for IANA personnel changing the IANA IPFIX Information Element 134 Registry [iana-ipfix-assignments], it defines a set of acceptance 135 criteria against which these proposed Information Elements should be 136 evaluated. 138 This document is not intended to guide the extension of the IPFIX 139 protocol itself, e.g. through new export mechanisms, data types, or 140 the like; these activities should be pursued through the publication 141 of standards-track RFCs within the IPFIX Working Group. 143 This document, together with 144 [I-D.ietf-ipfix-information-model-rfc5102bis], defines the procedures 145 for management of the IANA IPFIX Information Element Registry 146 [iana-ipfix-assignments]. The practices outlined in this document 147 are intended to guide experts when reviewing additions or changes to 148 the Information Elements in the registry under Expert Review as 149 defined in [RFC5226]. 151 1.2. Overview of relevant IPFIX documents 153 [I-D.ietf-ipfix-protocol-rfc5101bis] defines the IPFIX Protocol, the 154 IPFIX-specific terminology used by this document, and the data type 155 encodings for each of the data types supported by IPFIX. 157 [I-D.ietf-ipfix-information-model-rfc5102bis] defines the basis of 158 the IPFIX Information Model, referring to [iana-ipfix-assignments] 159 for the specific Information Element definitions. It states that new 160 Information Elements may be added to the Information Model on Expert 161 Review basis, delegates the appointment of experts to an IESG Area 162 Director, and refers to this document for details on the extension 163 process. This document is intended to further codify the best 164 practices to be followed by these experts, in order to improve the 165 efficiency of this process. 167 [RFC5103] defines a method for exporting bidirectional flow 168 information using IPFIX; this document should be followed when 169 extending IPFIX to represent information about bidirectional network 170 interactions in general. Additionally, new Information Elements 171 should be annotated for their reversibility or lack thereof as per 172 this document. 174 [RFC5610] defines a method for exporting information about 175 Information Elements inline within IPFIX. In doing so, it explicitly 176 defines a set of restrictions, implied in 177 [I-D.ietf-ipfix-protocol-rfc5101bis] and 178 [I-D.ietf-ipfix-information-model-rfc5102bis], on the use of data 179 types and semantic; these restrictions must be observed in the 180 definition of new Information Elements, as in Section 4.4. 182 2. Terminology 184 Capitalized terms used in this document that are defined in the 185 Terminology section of [I-D.ietf-ipfix-protocol-rfc5101bis] are to be 186 interpreted as defined there. 188 An "application", as used in this document, refers to a candidate 189 protocol, task, or domain to which IPFIX export, collection, and/or 190 storage is applied. By this definition, the IPFIX Applicability 191 statement [RFC5472] definied the initial applications of IPFIX, and 192 PSAMP [RFC5476] was the first new IPFIX application after the 193 publication of the IPFIX protocol itself. 195 "IANA IE registry", as used in this document, unless otherwise noted, 196 refers to the IANA IPFIX Information Element Registry 197 [iana-ipfix-assignments]. 199 3. How to apply IPFIX 201 Though originally specified for the export of IP flow information, 202 the message format, template mechanism, and data model specified by 203 IPFIX lead to it being applicable to a wide variety of network 204 management situations. In addition to flow information export, for 205 which it was designed, and packet information export as specified by 206 PSAMP [RFC5476], any application with the following characteristics 207 is a good candidate for an IPFIX application: 209 o The application's data flow is fundamentally unidirectional. 210 IPFIX is a "push" protocol, supporting only the export of 211 information from a sender (an Exporting Process) to a receiver (a 212 Collecting Process). Request-response interactions are not 213 supported by IPFIX. 215 o The application handles discrete event information, or information 216 to be periodically reported. IPFIX is particularly well suited to 217 representing events, which can be scoped in time. 219 o The application handles information about network entities. 220 IPFIX's information model is network-oriented, so network 221 management applications have many opportunities for information 222 model reuse. 224 o The application requires a small number of arrangements of data 225 structures relative to the number of records it handles. The 226 template-driven self-description mechanism used by IPFIX excels at 227 handling large volumes of identically structured data, compared to 228 representations which define structure inline with data (such as 229 XML). 231 Most applications meeting these criteria can be supported over IPFIX. 232 Once it has been determined that IPFIX is a good fit, the next step 233 is determining which Information Elements are necessary to represent 234 the information required by the application. Especially for network- 235 centric applications, the IANA IE registry may already contain all 236 the necessary Information Elements (see Section 6.1 for guidelines on 237 maximizing Information Element reuse). In this case, no work within 238 the IETF is necessary: simply define Templates and start exporting. 240 It is expected, however, that most applications will be able to reuse 241 some existing Information Elements, but may need to define some 242 additional Information Elements to support all their requirements; in 243 this case, see Section 4 for best practices to be followed in 244 defining Information Elements. 246 Optionally, a Working Group or individual contributor may choose to 247 write an Internet-Draft for publication as an RFC, detailing the new 248 IPFIX application. Such an RFC should contain discussion of the new 249 application, the Information Element definitions as in Section 4, as 250 well as suggested Templates and examples of the use of those 251 Templates within the new application as in Section 9.2. Section 10 252 defines a compact textual Information Element notation to be used in 253 describing these suggested Templates and/or the use of IPFIX 254 Structured Data [RFC6313] within the new application. 256 4. Defining new Information Elements 258 In many cases, a new application will require nothing more than a new 259 Information Element or set of Information Elements to be exportable 260 using IPFIX. An Information Element meeting the following criteria, 261 as evaluated by the IE-DOCTORS, is eligible for inclusion in the IANA 262 IE registry: 264 o The Information Element must be unique within the registry, and 265 its description must represent a substantially different meaning 266 from that of any existing Information Element. An existing 267 Information Element that can be reused for a given purpose should 268 be. 270 o The Information Element should contain as little internal 271 structure as possible. Instead of representing complex 272 information by overlaying internal structure on a simple data type 273 such as octetArray, such information should be represented with 274 multiple simple Information Elements to be exported in parallel or 275 using IPFIX Structured Data [RFC6313], as in Section 4.5. The 276 internal structure of a proposed IE may be evaluated by the IE- 277 DOCTORS with an eye toward interoperability and/or backward 278 compatibility with existing methods of exporting similar data on a 279 case-by-case basis. 281 o Information Elements representing information about proprietary or 282 nonstandard applications should not be registered in the IANA IE 283 registry; these be represented using enterprise-specific 284 Information Elements as detailed in section 3.2 [RFC-EDITOR NOTE: 285 verify section number] of [I-D.ietf-ipfix-protocol-rfc5101bis], 286 instead. 288 The definition of new Information Elements requires a descriptive 289 name, a specification of the data type from the IPFIX Data Type 290 subregistry in the IANA IE registry (defined in 291 [I-D.ietf-ipfix-information-model-rfc5102bis] as itself extensible 292 via Standards Action as per [RFC5226]), and a human-readable 293 description written in English. This section provides guidelines on 294 each of these components of an Information Element definition, 295 referring to existing documentation such as 296 [I-D.ietf-ipfix-information-model-rfc5102bis] as appropriate. 298 4.1. Information Element naming 300 As the name of an Information Element is the first thing a potential 301 implementor will use when determining whether it is suitable for a 302 given application, it is important to be as precise and descriptive 303 as possible. Names of Information Elements: 305 o must be chosen carefully to describe the use of the Information 306 Element within the context in which it will be used. 308 o must be unique within the IANA IE registry. 310 o start with non-capitalized letters. 312 o use capital letters for the first letter of each component except 313 for the first one (aka "camel case"). All other letters are non- 314 capitalized, even for acronyms. Exceptions are made for acronyms 315 containing non-capitalized letters, such as 'IPv4' and 'IPv6'. 316 Examples are "sourceMacAddress" and "destinationIPv4Address." 318 In addition, new Information Elements pertaining to a specific 319 protocol should name the protocol in the first word in order to ease 320 searching by name (e.g. "sipMethod" for a SIP method, as would be 321 used in a logging format for SIP based on IPFIX). Similarly, new 322 Information Elements pertaining to a specific application should name 323 the application in the first word. 325 4.2. Information Element data types 327 IPFIX provides a set of data types covering most primitives used in 328 network measurement and management applications. The most 329 appropriate data type should be chosen for the Information Element 330 type, IPFIX informationElementDataTypes subregistry at 331 [iana-ipfix-assignments]. This subregistry may be extended from time 332 to time by a Standards Action [RFC5226], as defined in [RFC5610]. 334 Information Elements representing an integral value with a natural 335 width should be defined with the appropriate integral data type. 336 This applies especially to values taken directly from fixed-width 337 fields in a measured protocol. For example, tcpControlBits, the TCP 338 flags byte, is an unsigned8, and tcpSequenceNumber is an unsigned32. 340 Information Elements representing counters or identifiers should be 341 defined as signed64 or unsigned64, as appropriate, to maximize the 342 range of values available; applications can use reduced-size encoding 343 as defined in Section 6.2 [RFC-EDITOR NOTE: verify section number] of 344 [I-D.ietf-ipfix-protocol-rfc5101bis] in cases where fewer than 2^64 345 values are necessary. 347 Information Elements representing time values must be defined with 348 appropriate precision. For example, a Information Element for a time 349 measured at second-level precision should be defined as having a 350 dateTimeSeconds data type, instead of dateTimeMilliseconds. 352 Information Elements of type string or octetArray which have length 353 constraints (fixed length, minimum and/or maximum length) must note 354 these constraints in their description. 356 The type of an Information Element must match the type of the data it 357 represents. More specifically, information that could be represented 358 as a string, but which better matches one of the other data types 359 (e.g. an integral type for a number or enumerated type, an address 360 type for an address) must be represented by the best-matching type, 361 even if the data was represented using a different type in the 362 source. For example, an IPFIX application that exports Options 363 Template Records mapping IP addresses to additional information about 364 each host from an external database must use Information Elements of 365 an address type to represent the addresses, even if the source 366 database represented these as strings. 368 Strings and octetArrays must not be used to encode data that would be 369 more properly represented using multiple Information Elements and/or 370 IPFIX Structured Data [RFC6313]; see Section 4.5 for more. 372 This document does not cover the addition of new Data Types or Data 373 Type Semantics to the IPFIX Protocol. As such changes have important 374 interoperability considerations and require implementation on both 375 Collecting and Exporting Processes, they require a Standards Action 376 as per [RFC5610]. However, note that the set of primitive types 377 provided by IPFIX are applicable to almost any appropriate 378 application, so extending the type system is generally not necessary. 380 4.3. Information Element numbering 382 Each Information Element has a unique identifier in the IANA 383 registry. 385 When adding newly registered Information Elements to the IANA IE 386 registry, IANA should assign the lowest available Information Element 387 identifier (the value column in [iana-ipfix-assignments]) in the 388 range 128-32767. 390 Information Elements with identifiers from 1-127 are reserved for 391 compatibility with corresponding fields in NetFlow version 9, as 392 described in [RFC3954]. 394 4.4. Ancillary Information Element properties 396 Information Elements to which special semantics apply should refer to 397 one of the values in the Information Element Semantics subregistry of 398 the IANA IE registry, as described in Section 3.2 [RFC-EDITOR NOTE: 399 verify section number] of 400 [I-D.ietf-ipfix-information-model-rfc5102bis], subject to the 401 restrictions given in Section 3.10 of [RFC5610]; in other words, the 402 semantics and the type must be consistent. 404 When defining Information Elements representing a dimensioned 405 quantity or entity count, the units of that quantity should be 406 defined in the units field. This field takes its values from the 407 IANA Information Element Units subregistry of the IANA IE registry. 408 If an Information Element expresses a quantity in units not yet in 409 this subregistry, then the unit must be added to the Units 410 subregistry at the same time the Information Element is added to the 411 IANA IE registry. Note that the Units subregistry as defined in 412 [RFC5610] is maintained on an Expert Review basis. 414 Additionally, when the range of values an Information Element can 415 take is smaller than the range implied by its data type, the range 416 should be defined within the Information Element's entry the IANA IE 417 registry. 419 4.5. Internal structure in Information Elements 421 The definition of Information Elements with internal structure with 422 the structure defined in the Description field is not recommended, 423 except in the following cases: 425 1. The Information Element is a direct copy of a structured entity 426 in a measured protocol (e.g. the tcpControlBits Information 427 Element for the flags byte from the TCP header) 429 2. The Information Element represents a section of a packet of 430 protocol entity, in raw form as captured from the wire (e.g. the 431 mplsLabelStackSection Information Element for the MPLS label 432 stack) 434 3. The Information Element represents a set of flags which are 435 tightly semantically related, where representing the flags as 436 separate one-byte booleans would be inefficient, and which should 437 always appear together in a data record (e.g., the 438 anonymizationFlags Information Element for specifying optional 439 features of anonymization techniques) 441 4. The Information Element contains internal structure by reference 442 to an external datatype or specification containing internal 443 structure (e.g., a MIME type or URL), for interoperability and 444 backward compatibility purposes 446 Additional exceptions to the above list should be made through a 447 publication of an RFC. 449 In other cases, candidate Information Elements with internal 450 structure should be decomposed into multiple primitive Information 451 Elements to be used in parallel. For more complicated semantics, 452 where the structure is not identical from Data Record to Data Record, 453 or where there is semantic dependency between multiple decomposed 454 primitive Information Elements, use the IPFIX Structured Data 455 [RFC6313] extension instead. 457 As an example of information element decomposition, consider an 458 application-level identifier called an "endpoint", which represents a 459 {host, port, protocol} tuple. Instead of allocating an opaque, 460 structured "source endpoint" Information Element, the source endpoint 461 should be represented by three separate Information Elements: "source 462 address", "source port", "transport protocol". In this example, the 463 required information elements already exist in the IANA IE registry: 464 sourceIPv4Address or sourceIPv6Address, sourceTransportPort, 465 protocolIdentifier. Indeed, as well as being good practice, this 466 normalization down to non-structured Information Elements also 467 increases opportunities for reuse as in Section 6.1. 469 The decomposition of data with internal structure should avoid the 470 definition of Information Elements with a meaning too specific to be 471 generally useful, or that would result in a multitude of templates to 472 handle different multiplicities. More information on multiplicities 473 is given in the following section. 475 4.6. Information Element multiplicity 477 Some Information Elements may represent information with a 478 multiplicity other than one; i.e., items that may occur multiple 479 times within the data to be represented in a single IPFIX record. In 480 this case, there are several options, depending on the circumstances: 482 1. As specified in section 8 [RFC-EDITOR NOTE: verify section 483 number] of [I-D.ietf-ipfix-protocol-rfc5101bis]: "if an 484 Information Element is required more than once in a Template, the 485 different occurrences of this Information Element should follow 486 the logical order of their treatments by the Metering Process." 487 In other words, in cases where the items have a natural order 488 (e.g., the order in which they occur in the packet), and the 489 multiplicity is the same for each record, the information can be 490 modeled by containing multiple instances of the Information 491 Element representing a single item within the Template Record 492 describing the Data Records. 494 2. In cases where the items have a variable multiplicity, a 495 basicList of the Information Element representing a single item 496 can be used as in the IPFIX Structured Data [RFC6313] extension. 498 3. If the multiple-item structure is taken directly from bytes 499 observed on the wire by the Metering Process or otherwise taken 500 from the application being measured (e.g., a TCP options stack), 501 the multiple-item structure can be exported as a variable-length 502 octetArray Information Element holding the raw content. 504 Specifically, new Information Element should not encode any 505 multiplicity or ordinality information into the definition of the 506 Information Element itself. 508 4.7. Enumerated Values and Subregistries 510 When defining an Information Element that takes an enumerated value 511 from a set of values which may change in the future, this enumeration 512 must be defined by an IANA IE registry or subregistry. For 513 situations where an existing registry defines the enumeration (e.g., 514 the IANA Protocol Numbers registry for the protocolIdentifier 515 Information Element), that registry must be used. Otherwise, a new 516 subregistry of the IANA IPFIX registry must be defined for the 517 enumerated value, to be modified subject to Expert Review [RFC5226]. 519 4.8. Reversibility as per RFC 5103 521 [RFC5103] defines a method for exporting bidirectional flows using a 522 special Private Enterprise Number to define reverse-direction 523 variants of IANA Information Elements, and a set of criteria for 524 determining whether an Information Element may be reversed using this 525 method. Since almost all Information Elements are reversible, 526 [RFC5103] enumerates those Information Elements which were defined at 527 the time of its publication which are NOT reversible. 529 New non-reversible Information Elements must contain a note in the 530 description stating that they are not reversible. 532 4.9. Avoiding Bad Ideas in Information Element Design 534 In general, the existence of a similarly-defined Information Element 535 in the IANA IE registry sets a precedent which may be followed to 536 determine whether a given proposed Information Element "fits" within 537 the registry. Indeed, the rules specified by this document could be 538 interpreted to mean "make new Information Elements that look like 539 existing Information Elements". However, for reasons of history, 540 there are several Information Elements within the IANA IE registry 541 which do not follow best practices in Information Element design. 542 These Information Elements are not necessarily so flawed so as to 543 require deprecation, but they should be explicitly ignored when 544 looking for guidance as to whether a new Information Element should 545 be added. Here we provide a set of representative examples taken 546 from the IANA IE registry; in general, entries in the IANA IE 547 registry which do not follow the guidelines in this document should 548 not be used as examples for new Information Element definitions. 550 Before registering a new Information Element, it must be determined 551 that it would be sufficiently unique within the IANA IE registry. 552 This evaluation has not always been done in the past, and the 553 existence of the Information Elements defined without this evaluation 554 should not be taken as an example that such Information Element 555 definition practices should be followed in the future. Specific 556 examples of such Information Elements include initiatorOctets and 557 responderOctets (which duplicate octetDeltaCount and its reverse per 558 [RFC5103]) and initiatorPackets and responderPackets (the same, for 559 packetDeltaCount). 561 As mentioned in Section 4.2, the type of an Information Element 562 should match the type of data the Information Element represents. An 563 example of how not to do this is presented by the p2pTechnology, 564 tunnelTechnology, and encryptedTechnology Information Elements: these 565 represent a three-state enumeration using a String. The example set 566 by these Information Elements should not be followed in the 567 definition of new Information Elements. 569 As mentioned in Section 4.6, an Information Element definition should 570 not include any ordinality or multiplicity information. The only 571 example of this within the IANA IE registry the following list of 572 assigned IPFIX Information Elements: mplsTopLabelStackSection, 573 mplsLabelStackSection2, mplsLabelStackSection3, 574 mplsLabelStackSection4, mplsLabelStackSection5, 575 mplsLabelStackSection6 mplsLabelStackSection7, 576 mplsLabelStackSection8, mplsLabelStackSection9, and 577 mplsLabelStackSection10. The only distinction between those almost- 578 identical Information Elements is the position within the MPLS stack. 579 This Information Element design pattern met an early requirement of 580 the definition of IPFIX which was not carried forward into the final 581 specification -- namely, that no semantic dependency was allowed 582 between Information Elements in the same Record -- and as such should 583 not be followed in the definition of new Information Elements. In 584 this case, since the size of the MPLS stack will vary from flow to 585 flow, it should be exported using IPFIX Structured Data [RFC6313] 586 where supported, as a basicList of MPLS label entries, or as a raw 587 MPLS label stack using the variable-length mplsLabelStackSection 588 Information Element. 590 5. The Information Element Lifecycle 592 Once an Information Element or set of Information Elements has been 593 identified for a given application, Information Element 594 specifications in accordance with Section 4 are submitted to IANA to 595 follow the IE-DOCTORS process, as defined below. This process is 596 also used for other changes to the IANA IE registry, such as 597 deprecation or revision, as described later in this section. 599 5.1. The IE-DOCTORS process 601 Requests to change the IANA IE registry or a linked subregistry are 602 submitted to IANA, which forwards the request to a designated group 603 of experts (IE-DOCTORS) appointed by the IESG; these are the 604 reviewers called for by the Expert Review [RFC5226] policy defined 605 for the IANA IE registry by 606 [I-D.ietf-ipfix-information-model-rfc5102bis]. The IE-DOCTORS review 607 the request for such things as compliance with this document, 608 compliance with other applicable IPFIX-related RFCs, and consistency 609 with the currently defined set of Information Elements. 611 Authors are expected to review compliance with the specifications in 612 this document to check their submissions before sending them to IANA. 614 IE-DOCTORS reviewers should endeavor to complete referred reviews in 615 a timely manner. If the request is acceptable, the IE-DOCTORS 616 signify their approval to IANA, which changes the IANA IE registry. 617 If the request is not acceptable, the IE-DOCTORS can coordinate with 618 the requestor to change the request to be compliant. The IE-DOCTORS 619 may also choose in exceptional circumstances to reject clearly 620 frivolous or inappropriate change requests outright. 622 This process should not in any way be construed as allowing the IE- 623 DOCTORS to overrule IETF consensus. Specifically, Information 624 Elements in the IANA IE registry which were added with IETF consensus 625 require IETF consensus for revision or deprecation. 627 IE-DOCTORS decisions may be appealed as in section 7 of [RFC5226]. 629 5.2. Revising Information Elements 631 The Information Element status field in the IANA IE registry is 632 defined in [I-D.ietf-ipfix-information-model-rfc5102bis] to allow 633 Information Elements to be 'current' or 'deprecated'. No Information 634 Elements are as of this writing deprecated. [RFC5102] additionally 635 specified an 'obsolete' status; however, this has been removed on 636 revision as it served no operational purpose. 638 In addition, no policy is defined for revising IANA IE registry 639 entries or addressing errors therein. To be certain, changes and 640 deprecations within the IANA IE registry are not encouraged, and 641 should be avoided to the extent possible. However, in recognition 642 that change is inevitable, this section is intended to remedy this 643 situation. 645 Changes are initiated by sending a new Information Element definition 646 to IANA, as in Section 5.1, for an already-existing Information 647 Element. 649 The primary requirement in the definition of a policy for managing 650 changes to existing Information Elements is avoidance of 651 interoperability problems; IE-DOCTORS must work to maintain 652 interoperability above all else. Changes to Information Elements 653 already in use may only be done in an interoperable way; necessary 654 changes which cannot be done in a way to allow interoperability with 655 unchanged implementations must result in deprecation. 657 A change to an Information Element is held to be interoperable only 658 when: 660 1. it involves the correction of an error which is obviously only 661 editorial; or 663 2. it corrects an ambiguity in the Information Element's definition, 664 which itself leads to non-interoperability severe enough to 665 prevent the Information Element's usage as originally defined 666 (e.g., a prior change to ipv6ExtensionHeaders); or 668 3. it expands the Information Element's data type without changing 669 how it is represented (e.g., changing unsigned32 to unsigned64, 670 as with a prior change to selectorId); or 672 4. it corrects missing information in the Information Element's 673 definition without changing its meaning (e.g., the explicit 674 definition of 'quantity' semantics for numeric Information 675 Elements without a Data Type Semantics value); or 677 5. it defines a previously undefined or reserved enumerated value, 678 or one or more previously reserved bits in an Information Element 679 with flag semantics; or 681 6. it expands the set of permissible values in the Information 682 Element's range; or 684 7. it harmonizes with an external reference which was itself 685 corrected. 687 If a change is deemed permissible by the IE-DOCTORS, IANA makes the 688 change in the IANA IE registry. The requestor of the change is 689 appended to the Requestor in the registry. 691 Each Information Element in the IANA IE registry has a Revision 692 number, starting at zero. Each change to an Information Element 693 following this process increments the Revision number by one. Since 694 any revision must be interoperable according to the criteria above, 695 there is no need for the IANA IE registry to store information about 696 old revisions. 698 When a revised Information Element is accepted into the registry, the 699 date of acceptance of the most recent revision is placed into the 700 revision Date column of the registry for that Information Element. 702 5.3. Deprecating Information Elements 704 Changes that are not permissible by these criteria may only be 705 handled by deprecation. An Information Element MAY be deprecated and 706 replaced when: 708 1. the Information Element definition has an error or shortcoming 709 which cannot be permissibly changed as in Section 5.2; or 711 2. the deprecation harmonizes with an external reference which was 712 itself deprecated through that reference's accepted deprecation 713 method; or 715 3. changes in the IPFIX Protocol or its extensions, or in community 716 understanding thereof, allow the information represented by the 717 Information Element to be represented in a more efficient or 718 convenient way. Deprecation in this circumstance requires a 719 Standards Action. 721 A request for deprecation is sent to IANA, which passes it to the IE- 722 DOCTORS for review, as in Section 5.1. When deprecating an 723 Information Element, the Information Element description in the IANA 724 IE registry must be updated to explain the deprecation, as well as to 725 refer to any new Information Elements created to replace the 726 deprecated Information Element. 728 The Revision number of an Information Element is incremented upon 729 deprecation, and the revision Date updated, as with any revision. 731 Deprecated Information Elements should continue to be supported by 732 Collecting Processes, but should not be exported by Exporting 733 Processes. The use of deprecated Information Elements should result 734 in a log entry or human-readable warning at the Exporting and 735 Collecting Processes. 737 Names and elementIDs of deprecated Information Elements must not be 738 reused. 740 6. When not to define new Information Elements 742 Due to the relatively limited number space of Information Elements in 743 the IANA IE registry, and the fact that the difficulty of managing 744 and understanding the registry increases with its size, avoiding 745 redundancy and clutter in the registry is important in defining new 746 applications. New Information Elements should not be added to the 747 IANA IE registry unless there is an intent to implement and deploy 748 applications using them; research or experimental applications should 749 use enterprise-specific Information Elements as in Section 6.2 750 instead. 752 The subsections below provide guidelines for reuse of existing 753 Information Elements, as well as guidelines on using enterprise- 754 specific Information Elements instead of adding Information Elements 755 in the IANA IE registry. 757 6.1. Maximizing reuse of existing Information Elements 759 Whenever possible, new applications should prefer usage of existing 760 IPFIX Information Elements to the creation of new Information 761 Elements. IPFIX already provides Information Elements for every 762 common Layer 4 and Layer 3 packet header field in the IETF protocol 763 suite, basic Layer 2 information, basic counters, timestamps and time 764 ranges, and so on. When defining a new Information Element similar 765 to an existing one, reviewers should ensure that the existing one is 766 not applicable. 768 Note that this guideline to maximize reuse does not imply that an 769 Information Element that represents the same information from a 770 packet as a existing Information Element should not be added to the 771 IANA IE registry. For example, consider the ipClassOfService 772 (Element ID 5), ipDiffServCodePoint (Element ID 98), and ipPrecedence 773 (Element ID 196) Information Elements. These all represent subsets 774 of the same field in an IP version 4 packet header, but different 775 uses of these bits. The representation in one or another of these 776 Information Elements contains information in itself as to how the 777 bits were interpreted by the Metering Process. 779 On the other hand, simply changing the context in which an 780 Information Element will be used is insufficient reason for the 781 definition of a new Information Element. For example, an extension 782 of IPFIX to log detailed information about HTTP transactions 783 alongside network-level information should not define 784 httpClientAddress and httpServerAddress Information Elements, 785 preferring instead the use of sourceIPv[46]Address and 786 destinationIPv[46]Address. 788 Applications dealing with bidirectional interactions should use 789 Bidirectional Flow Support for IPFIX [RFC5103] to represent these 790 interactions. 792 Existing timestamp and time range Information Elements should be 793 reused for any situation requiring simple time stamping of an event: 794 for single observations, the observationTime* Information Elements 795 from PSAMP are provided, and for events with a duration, the 796 flowStart* and flowEnd* Information Elements suffice. This 797 arrangement allows minimal generic time handling by existing 798 Collecting Processes and analysis workflows. New timestamp 799 Information Elements should ONLY be defined for semantically distinct 800 timing information (e.g., an IPFIX-exported record containing 801 information about an event to be scheduled in the future). 803 In all cases the use of absolute timestamp Information Elements (e.g. 804 flowStartMilliseconds) is recommended, as these Information Elements 805 allow for maximum flexibility in processing with minimal overhead. 806 Timestamps based on the export time header in the enclosing IPFIX 807 Message (e.g. flowStartTimeDeltaMicroseconds) MAY be used if high- 808 precision timing is important, export bandwidth or storage space is 809 limited, timestamps comprise a relatively large fraction of record 810 size, and the application naturally groups records into IPFIX 811 Messages. Timestamps based on information which must be exported in 812 a separate Data Record defined by an Options Template (e.g. 813 flowStartSysUpTime) MAY be used only in the context of an existing 814 practice of using runtime-defined epochs for the given application. 815 New applications should avoid these structures when possible. 817 6.2. Applying enterprise-specific Information Elements 819 IPFIX provides a mechanism for defining enterprise-specific 820 Information Elements, as in Section 3.2 [RFC-EDITOR NOTE: verify 821 section number] of [I-D.ietf-ipfix-protocol-rfc5101bis]. These are 822 scoped to a vendor's or organization's Structure of Management 823 Information (SMI) Private Enterprise Number, and are under complete 824 control of the organization assigning them. 826 For situations in which interoperability is unimportant, new 827 information should be exported using enterprise-specific Information 828 Elements instead of adding new Information Elements to the IANA IE 829 registry. These situations include: 831 o export of implementation-specific information, or 833 o export of information supporting research or experiments within a 834 single organization or closed community, or 836 o export of information derived in a commercially-sensitive or 837 proprietary method, or 839 o export of information or meta-information specific to a 840 commercially-sensitive or proprietary application. 842 While work within the IETF generally does not fall into these 843 categories, enterprise-specific Information Elements are also useful 844 for pre-standardization testing of a new IPFIX application. While 845 performing initial development and interoperability testing of a new 846 application, the Information Elements used by the application should 847 not be submitted to IANA for inclusion in the IANA IE registry. 848 Instead, these experimental Information Elements should be 849 represented as enterprise-specific until their definitions are 850 finalized. 852 As this document contains best practices for defining new Information 853 Elements, organizations using enterprise-specific Information 854 Elements are advised to follow the guidelines set forth here even if 855 not submitting Information Elements for inclusion in the IANA IE 856 registry. 858 7. Information Element Definition Checklist 860 The following three checklists, condensed from the rest of this 861 document, can be used when defining and reviewing Information 862 Elements; they refer back to the section of this document from which 863 they are taken. These checklists are intended for the definition of 864 new Information Elements; revision should follow the process defined 865 in Section 5.2, and deprecation should follow the process defined in 866 Section 5.3. 868 Though many of the considerations in this document require the 869 subjective judgement of Information Element authors, reviewers, and 870 IANA, certain parts of the process may be made simpler through tool 871 support. Items on these checklists which could be easily automated 872 or assisted by tools are annotated with "(tool support)". Other 873 items on these checklists require some level of subjective judgement; 874 checks for semantic uniqueness may additionally be supported by 875 textual analysis of descriptions in the future. 877 Checklist 1 contains conditions which must be met by all proposed 878 Information Elements: 880 1. The name must be unique within the IANA IE registry, and not 881 reuse the name of any current or deprecated Information Element. 882 (Section 4.1) (tool support) 884 2. The description must be sufficiently semantically unique within 885 the IANA IE registry, representing a substantially different 886 meaning from any current or deprecated Information Element. 887 (Section 4) 889 3. The name must start with a non-capitalized letter. (Section 4.1) 890 (tool support) 892 4. Names composed of more than on word must use capital letters for 893 the first letter of each component except for the first one; all 894 other letters are non-capitalized, even for acronyms. Exceptions 895 are made for acronyms containing non-capitalized letters, such as 896 'IPv4' and 'IPv6'. (Section 4.1) (tool support) 898 5. The data type must match the type of the data being represented. 899 (Section 4.2) 901 6. Data type semantics must be appropriate for the data type. 902 (Section 4.4) (tool support) 904 7. The Information Element identifier assigned by IANA must be 905 unique. (Section 4.3) (tool support) 907 8. The Information Element must be reviewed for the potential of 908 information leakage or other misuse that could reduce the 909 security of the measured system; security considerations specific 910 to the Information Element must be discussed in the description 911 or in a supporting RFC. (Section 11) 913 Checklist 2 contains conditions which must be met by proposed 914 Information Elements with certain properties, as noted: 916 1. Time values must be defined with appropriate precision. 917 (Section 4.2) 919 2. Strings and octet arrays with length restrictions must note those 920 length restrictions in their descriptions. (Section 4.2) 922 3. Enumerations must refer to an IANA IE registry or subregistry, or 923 a registry maintained by an external standards organization. If 924 no suitable registry or subregistry exists, a new subregistry of 925 the IPFIX Information Element registry must be created for the 926 enumeration, to be modified subject to Expert Review [RFC5226]. 927 (Section 4.7) 929 Checklist 3 contains conditions which should be met by proposed 930 Information Elements: 932 1. The name of an Information Element pertaining to a specific 933 protocol or application should contain the name of the protocol 934 or application as the first word. (Section 4.1) 936 2. Information Elements representing integral values should use a 937 data type for the appropriate width for the value. 938 (Section 4.2) 940 3. Information Elements representing counters or identifiers should 941 be represented as signed64 or unsigned64, unless they are 942 naturally represented with narrower integral types, as 943 appropriate. (Section 4.2) 945 4. An Information Element should not contain internal structure, 946 subject to the exceptions in Section 4.5; candidate Information 947 Elements with internal structure should be decomposed into 948 multiple Information Elements. (Section 4.5) 950 5. An Information Element should not contain multiplicity or 951 ordinality information within the definition of the Information 952 Element itself. (Section 4.6) 954 6. Data type semantics should be defined, if appropriate. 955 (Section 4.4) (tool support) 957 7. Units should be defined, if appropriate, with new units added to 958 the Information Element Units subregistry if necessary. 959 (Section 4.4) (tool support) 961 8. Ranges should be defined, if appropriate. (Section 4.4) (tool 962 support) 964 9. Non-reversible Information Elements (see [RFC5103]) should note 965 non-reversibility in the description. (Section 4.8) 967 10. Information Elements to be registered with IANA should be 968 intended for implementation and deployment on production 969 networks. 971 8. Applying IPFIX to non-Flow Applications 973 At the core of IPFIX is its definition of a Flow, a set of packets 974 sharing some common properties crossing an Observation Point within a 975 certain time window. However, the reliance on this definition does 976 not preclude the application of IPFIX to domains which are not 977 obviously handling flow data according to this definition. Most 978 network management data collection tasks, those to which IPFIX is 979 most applicable, have at their core the movement of packets from one 980 place to another; by a liberal interpretation of the common 981 properties defining the flow, then, almost any event handled by these 982 can be held to concern data records conforming to the IPFIX 983 definition of a Flow. 985 Non-flow information defining associations or key-value pairs, on the 986 other hand, are defined by IPFIX Options Templates. Here, the 987 Information Elements within an Options Template Record are divided 988 into Scope Information Elements which define the key, and non-scope 989 Information Elements which define the values associated with that 990 key. Unlike Flows, Data Records defined by Options Template are not 991 necessarily scoped in time; these Data Records are generally held to 992 be in effect until a new set of values for a specific set of keys is 993 exported. While this mechanism is often used by IPFIX to export 994 metadata about the collection infrastructure, it is applicable to any 995 association information. 997 An IPFIX application can mix Data Records described either type of 998 template in an IPFIX Message or Message stream, and exploit 999 relationships among the Flow Keys, values, and Scopes to create 1000 interrelated data structures. See [RFC5473] for an example 1001 application of this. 1003 9. Writing Internet-Drafts for IPFIX Applications 1005 When a new application is complex enough to require additional 1006 clarification or specification as to the use of the defined 1007 Information Elements, or has particularly this may be given in an 1008 Internet-Draft. Internet-Drafts for new IPFIX applications are best 1009 submitted to a Working Group with expertise in the area of the new 1010 application, or as independent submissions. 1012 When defining new Information Elements in an Internet-Draft, the 1013 Internet-Draft should contain a section (or subsection) for each 1014 Information Element, which contains the attributes in Section 4 in 1015 human-readable form. An example subsection is given below. These 1016 Information Element descriptions should not assign Information 1017 Element numbers, instead using placeholder identifiers for these 1018 numbers (e.g. "TBD1", "TBD2", "TBD3") and a note to IANA in the IANA 1019 Considerations section to replace those placeholders in the document 1020 with Information Element numbers when the numbers are assigned. The 1021 use of these placeholder definitions allows references to the numbers 1022 in e.g. box-and-line diagrams or template definitions as in 1023 Section 10. 1025 9.1. Example Information Element Definition 1027 This is an example of an Information Element definition which would 1028 appear in an Internet-Draft. The name appears in the section title. 1030 Description: Description goes here.; obligatory 1032 Data Type: Data type goes here; obligatory 1034 Data Type Semantics: Data type semantics, if any, go here; optional 1036 Units: Units, if any, go here; optional 1038 Range: Range, if not implied by the data type, goes here; optional 1040 References: References to other RFCs or documents outside the IETF, 1041 in which additional information is given, or which are referenced 1042 by the description, go here; optional 1044 ElementId: ElementId, if known, or TBD to be filled in by IANA at 1045 publication time. 1047 9.2. Defining Recommended Templates 1049 New IPFIX applications should not, in the general case, define fixed 1050 templates for export, as this throws away much of the flexibility 1051 afforded by IPFIX. However, fixed template export is permissible in 1052 the case that the export implementation must operate in a resource 1053 constrained environment, and/or that the application is replacing an 1054 existing fixed-format binary export format in a maximally compatible 1055 way. In any case, Collecting Processes for such applications should 1056 support the collection Templates with Information Elements in any 1057 order, or Templates with additional Information Elements. 1059 An Internet-Draft clarifying the use of new Information Elements 1060 should include any recommended Template or Options Template Records 1061 necessary for supporting the application, as well as examples of 1062 records exported using these Template Records. In defining these 1063 Template Records, such Internet-Drafts should mention, subject to 1064 rare exceptions: 1066 1. that the order of different Information Elements within a 1067 Template is not significant; 1069 2. that Templates on the wire for the application may also contain 1070 additional Information Elements beyond those specified in the 1071 recommended Template; 1073 3. that a stream of IPFIX Messages supporting the application may 1074 also contain Data Records not described by the recommended 1075 Templates; and 1077 4. that any reader of IPFIX Messages supporting the application must 1078 accept these conditions. 1080 Definitions of recommended Template Records for flow-like 1081 information, where the Flow Key is well-defined, should indicate 1082 which of the Information Elements in the recommended Template are 1083 Flow Keys. 1085 Recommended Templates are defined, for example, in [RFC5476] for 1086 PSAMP packet reports (section 6.4) and extended packet reports 1087 (section 6.5). Recommended Options Templates are defined extensively 1088 throughout the IPFIX documents, including in the protocol document 1089 itself [I-D.ietf-ipfix-protocol-rfc5101bis] for exporting export 1090 statistics; in the file format [RFC5655] for exporting file metadata; 1091 and in Mediator intermediate process definitions such as [RFC6235] 1092 for intermediate process metadata. The discussion in these examples 1093 is a good model for recommended template definitions. 1095 10. A Textual Format for Specifying Information Elements and Templates 1097 Example Templates given in existing IPFIX documents are generally 1098 expressed using bitmap diagrams of the respective Templates. These 1099 are illustrative of the wire representation of simple Templates, but 1100 not particularly readable for more complicated recommended Templates, 1101 provide no support for rapid implementation of new Templates, and do 1102 not adequately convey the optional nature of ordering and additional 1103 Information Elements. Therefore, we define a recommended textual 1104 format for specifying Information Elements and Templates in Internet- 1105 Drafts in this section. 1107 Here we define a simple textual syntax for describing IPFIX 1108 Information Elements and IPFIX Templates, with human readability, 1109 human writability, compactness, and ease of parser/generator 1110 implementation without requiring external XML support as design 1111 goals. It is intended both for use in human communication (e.g., in 1112 new Internet-Drafts containing higher-level descriptions of IPFIX 1113 Templates, or describing sets of new IPFIX Information Elements for 1114 supporting new applications of the protocol) as well as at runtime by 1115 IPFIX implementations. 1117 10.1. Information Element Specifiers 1119 The basis of this format is the textual Information Element 1120 Specifier, or IESpec. An IESpec contains each of the four important 1121 aspects of an Information Element: its name, its number, its type, 1122 and its size, separated by simple markup based on various types of 1123 brackets. Fully-qualified IESpecs may be used to specify existing or 1124 new Information Elements within an Information Model, while either 1125 fully-qualified or partial IESpecs may be used to define fields in a 1126 Template. 1128 Bare words are used for Information Element names, and each aspect of 1129 information associated with an Information Element is associated with 1130 a type of brackets: 1132 o () parentheses for Information Element numbers, 1134 o <> angles for Information Element data types, and 1136 o [] square brackets for Information Element sizes. 1138 o {} curly braces contain an optional space-separated list of 1139 context identifiers to be associated with an Information Element, 1140 as described in more detail in Section 10.2 1142 The symbol + is reserved for Information Element nesting within 1143 structured data elements; these are described in Section 10.3. 1145 Whitespace in IESpecs is insignificant; spaces can be added after 1146 each element in order, e.g., to align columns for better readability. 1148 The basic form of a fully-qualified IESpec for an IANA-registered 1149 Information Element is as follows: 1151 name(number)[size] 1153 where 'name' is the name of the Information Element in UTF-8, 1154 'number' is the Information Element as a decimal integer, 'type' is 1155 the name of the data type as in the IANA informationElementDataTypes 1156 registry, and 'size' is the length of the Information Element in 1157 octets as a decimal integer, where 65535 or the string 'v' signifies 1158 a variable-length Information Element. [size] may be omitted; in this 1159 case, the data type's native or default size is assumed. 1161 The basic form of a fully-qualified IESpec for an enterprise-specific 1162 Information Element is as follows: 1164 name(pen/number)[size] 1166 where 'pen' is the Private Enterprise Number as a decimal integer. 1168 A fully-qualified IESpec is intended to express enough information 1169 about an Information Element to decode and display Data Records 1170 defined by Templates containing that Information Element. Range, 1171 unit, semantic, and description information, as in [RFC5610], is not 1172 supported by this syntax. 1174 Example fully-qualified IESpecs follow: 1176 octetDeltaCount(1)[8] 1178 octetDeltaCount(1) (unsigned64 is natively 8 octets 1179 long) 1181 sourceIPv4Address(8) 1183 wlanSSID(146)[v] 1185 sipRequestURI(35566/403)[65535] 1187 A partial IESpec is any IESpec that is not fully-qualified; these are 1188 useful when defining templates. A partial IESpec is assumed to take 1189 missing values from its canonical definition in the IANA IE registry. 1190 At minimum, a partial IESpec must contain a name, or a number. Any 1191 name, number, or type information given with a partial IESpec must 1192 match the values given in the Information Model; however, size 1193 information in a partial IESpec overrides size information in the 1194 Information Model; in this way, IESpecs can be used to express 1195 reduced-length encoding for Information Elements. 1197 Example partial IESpecs follow: 1199 o octetDeltaCount 1201 o octetDeltaCount[4] (reduced-length encoding) 1203 o (1) 1205 o (1)[4] (reduced length encoding; note that this is exactly 1206 equivalent to an Information Element specifier in a Template) 1208 10.2. Specifying Templates 1210 A Template can then be defined simply as an ordered, newline- 1211 separated sequence of IESpecs. IESpecs in example Templates 1212 illustrating a new application of IPFIX should be fully-qualified. 1213 Flow Keys may be optionally annotated by appending the {key} context 1214 to the end of each Flow Key specifier. A template counting packets 1215 and octets per five-tuple with millisecond precision in IESpec syntax 1216 is shown below. 1218 flowStartMilliseconds(152)[8] 1219 flowEndMilliseconds(153)[8] 1220 octetDeltaCount(1)[8] 1221 packetDeltaCount(2)[8] 1222 sourceIPv4Address(8)[4]{key} 1223 destinationIPv4Address(12)[4]{key} 1224 sourceTransportPort(7)[2]{key} 1225 destinationTransportPort(11)[2]{key} 1226 protocolIdentifier(4)[1]{key} 1228 Fig. 1: Sample flow template in IESpec syntax 1230 An Options Template is specified similarly. Scope is specified 1231 appending the {scope} context to the end of each IESpec for a Scope 1232 IE. Due to the way Information Elements are represented in Options 1233 Templates, all {scope} IESpecs must appear before any non-scope 1234 IESpec. The Flow Key Options Template defined in section 4.4 [RFC- 1235 EDITOR NOTE: verify section number] of 1236 [I-D.ietf-ipfix-protocol-rfc5101bis] in IESpec syntax is shown below: 1238 templateId(145)[2]{scope} 1239 flowKeyIndicator(173)[8] 1241 Fig. 2: Flow Key Options Template in IESpec syntax 1243 10.3. Specifying IPFIX Structured Data 1245 IESpecs can also be used to illustrate the structure of the 1246 information exported using the IPFIX Structured Data extension 1247 [RFC6313]. Here, the semantics of the structured data elements are 1248 specified using contexts, and the information elements within each 1249 structured data element follow the structured data element, prefixed 1250 with + to show they are contained therein. Arbitrary nesting of 1251 structured data elements is possible by using multiple + signs in the 1252 prefix. For example, a basic list of IP addresses with "one or more" 1253 semantics would be expressed using partially qualified IESpecs as 1254 follows: 1256 basicList{oneOrMoreOf} 1257 +sourceIPv4Address(8)[4] 1259 Fig. 3: Sample basicList in IESpec syntax 1261 And an example subTemplateList itself containing a basicList is shown 1262 below: 1264 subTemplateList{allOf} 1265 +basicList{oneOrMoreOf} 1266 ++sourceIPv4Address(8)[4] 1267 +destinationIPv4Address(12)[4] 1269 Fig. 4: Sample subTemplateList in IESpec syntax 1271 This describes a subTemplateMultilist containing all of the expressed 1272 set of source-destination pairs, where the source address itself 1273 could be one of any number in a basicList (e.g., in the case of SCTP 1274 multihoming). 1276 The contexts associable with structured data Information Elements are 1277 the semantics, as defined in section 4.4 of [RFC6313]; a structured 1278 data Information Element without any context is taken to have 1279 undefined semantics. More information on the application of 1280 structured data is available in [RFC6313]. 1282 11. Security Considerations 1284 The IE-DOCTORS must evaluate the security aspects of new Information 1285 Elements in light of the information they could provide to support 1286 potential attacks against the measured network or entities about 1287 which information is exported. Specific security aspects to evaluate 1288 include whether the exported information contains personally 1289 identifiable information, or information which should be kept 1290 confidential about the described entities (e.g. partial payload, or 1291 configuration information which could be exploited). This is not to 1292 say that such Information Elements should not be defined, but there 1293 must be an evaluation of the security risk versus the utility of the 1294 exported information for the intended application. For example, "A 1295 Framework for Packet Selection and Reporting" [RFC5474] concluded in 1296 section 12.3.2 that the hash functions private parameters should not 1297 exported within IPFIX. 1299 Security considerations specific to an Information Element must be 1300 addressed in the Security Considerations section of the Internet- 1301 Draft describing the Information Element, or in the Information 1302 Element description itself in case the Information Element is not 1303 defined in an Internet-Draft. Information Elements with specific 1304 security considerations should be described in an Internet-Draft. 1306 For example, the ipHeaderPacketSection in the IPFIX IE registry 1307 mentions: "This Information Element, which may have a variable 1308 length, carries a series of octets from the start of the IP header of 1309 a sampled packet. With sufficient length, this element also reports 1310 octets from the IP payload, subject to [RFC2804]. See the Security 1311 Considerations section." Another example can be seen in the "Packet 1312 Sampling (PSAMP) Protocols Specification" [RFC5476] specifies: "In 1313 the basic Packet Report, a PSAMP Device exports some number of 1314 contiguous bytes from the start of the packet, including the packet 1315 header (which includes link layer, network layer and other 1316 encapsulation headers) and some subsequent bytes of the packet 1317 payload. The PSAMP Device should not export the full payload of 1318 conversations, as this would mean wiretapping [RFC2804]. The PSAMP 1319 Device MUST respect local privacy laws." 1321 12. IANA Considerations 1323 This document has no considerations for IANA. 1325 [IANA NOTE: IANA considerations for the process outlined in this 1326 document are given in [I-D.ietf-ipfix-information-model-rfc5102bis]] 1328 [IANA NOTE: Note that the examples in Appendix A are NOT to be added 1329 to the IPFIX Information Element registry upon the publication of 1330 this document.] 1332 13. Acknowledgements 1334 Thanks to Paul Aitken, Andrew Feren, Dan Romascanu, and David 1335 Harrington for their reviews and feedback. Thanks as well to Roni 1336 Even and Yoav Nir for their area reviews; and to Pete Resnick, Adrian 1337 Farrel, Stephen Farrell, Stewart Bryant, and Barry Leiba for their 1338 contributions during IESG discussions. This work is materially 1339 supported by the European Union Seventh Framework Programme under 1340 grant agreement 257315 (DEMONS). 1342 14. References 1344 14.1. Normative References 1346 [I-D.ietf-ipfix-protocol-rfc5101bis] 1347 Claise, B. and B. Trammell, "Specification of the IP Flow 1348 Information eXport (IPFIX) Protocol for the Exchange of 1349 Flow Information", draft-ietf-ipfix-protocol-rfc5101bis-02 1350 (work in progress), June 2012. 1352 [I-D.ietf-ipfix-information-model-rfc5102bis] 1353 Claise, B. and B. Trammell, "Information Model for IP Flow 1354 Information eXport (IPFIX)", 1355 draft-ietf-ipfix-information-model-rfc5102bis-05 (work in 1356 progress), September 2012. 1358 [RFC5103] Trammell, B. and E. Boschi, "Bidirectional Flow Export 1359 Using IP Flow Information Export (IPFIX)", RFC 5103, 1360 January 2008. 1362 [RFC5610] Boschi, E., Trammell, B., Mark, L., and T. Zseby, 1363 "Exporting Type Information for IP Flow Information Export 1364 (IPFIX) Information Elements", RFC 5610, July 2009. 1366 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1367 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1368 May 2008. 1370 [RFC6313] Claise, B., Dhandapani, G., Aitken, P., and S. Yates, 1371 "Export of Structured Data in IP Flow Information Export 1372 (IPFIX)", RFC 6313, July 2011. 1374 14.2. Informative References 1376 [RFC2804] IAB and IESG, "IETF Policy on Wiretapping", RFC 2804, 1377 May 2000. 1379 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 1380 A., Peterson, J., Sparks, R., Handley, M., and E. 1381 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 1382 June 2002. 1384 [RFC3954] Claise, B., "Cisco Systems NetFlow Services Export Version 1385 9", RFC 3954, October 2004. 1387 [RFC5102] Quittek, J., Bryant, S., Claise, B., Aitken, P., and J. 1388 Meyer, "Information Model for IP Flow Information Export", 1389 RFC 5102, January 2008. 1391 [RFC5472] Zseby, T., Boschi, E., Brownlee, N., and B. Claise, "IP 1392 Flow Information Export (IPFIX) Applicability", RFC 5472, 1393 March 2009. 1395 [RFC5473] Boschi, E., Mark, L., and B. Claise, "Reducing Redundancy 1396 in IP Flow Information Export (IPFIX) and Packet Sampling 1397 (PSAMP) Reports", RFC 5473, March 2009. 1399 [RFC5474] Duffield, N., Chiou, D., Claise, B., Greenberg, A., 1400 Grossglauser, M., and J. Rexford, "A Framework for Packet 1401 Selection and Reporting", RFC 5474, March 2009. 1403 [RFC5476] Claise, B., Johnson, A., and J. Quittek, "Packet Sampling 1404 (PSAMP) Protocol Specifications", RFC 5476, March 2009. 1406 [RFC5477] Dietz, T., Claise, B., Aitken, P., Dressler, F., and G. 1407 Carle, "Information Model for Packet Sampling Exports", 1408 RFC 5477, March 2009. 1410 [RFC5560] Uijterwaal, H., "A One-Way Packet Duplication Metric", 1411 RFC 5560, May 2009. 1413 [RFC5655] Trammell, B., Boschi, E., Mark, L., Zseby, T., and A. 1414 Wagner, "Specification of the IP Flow Information Export 1415 (IPFIX) File Format", RFC 5655, October 2009. 1417 [RFC6235] Boschi, E. and B. Trammell, "IP Flow Anonymization 1418 Support", RFC 6235, May 2011. 1420 [iana-ipfix-assignments] 1421 Internet Assigned Numbers Authority, "IP Flow Information 1422 Export Information Elements 1423 (http://www.iana.org/assignments/ipfix/ipfix.xml)". 1425 Appendix A. Example Information Element Definitions 1427 This section contains a few example Information Element definitions 1428 as they would appear in an Internet-Draft. Note the conformance of 1429 these examples to the guidelines in Section 4. 1431 The sipResponseStatus Information Element (Appendix A.1) illustrates 1432 the addition of an Information Element representing Layer 7 1433 application information, with a reference to the registry containing 1434 the allowable values. The duplicatePacketDeltaCount Information 1435 Element (Appendix A.2) illustrates the addition of a new metric, with 1436 a reference to the RFC defining the metric. The ambientTemperature 1437 Information Element (Appendix A.3) illustrates the addition of a new 1438 measured value outside the area of traditional networking 1439 applications. 1441 A.1. sipResponseStatus 1443 Description: The SIP Response code as an integer, as in the 1444 Response Codes registry at 1445 http://www.iana.org/assignments/sip-parameters defined in 1446 [RFC3261] and amended in subsequent RFCs. The presence of this 1447 Information Element in a SIP Message record marks it as describing 1448 a SIP response; if absent, the record describes a SIP request. 1450 Data Type: unsigned16 1452 Data Type Semantics: identifier 1454 References: [RFC3261] 1456 ElementId: TBD 1458 Replaces Enterprise-Specific Element: 35566 / 412 1460 A.2. duplicatePacketDeltaCount 1462 Description: The number of uncorrupted and identical additional 1463 copies of each individual packet in the Flow arriving at the 1464 destination since the previous Data Record for this Flow (if any), 1465 as measured at the Observation Point. This is measured as the 1466 Type-P-one-way-packet-duplication metric defined in section 3 of 1467 [RFC5560]. 1469 Data Type: unsigned64 1471 Data Type Semantics: deltaCounter 1473 Units: packets 1475 References: [RFC5560] 1476 ElementId: TBD 1478 A.3. ambientTemperature 1480 Description: An ambient temperature observed by measurement 1481 equipment at an Observation Point, positioned such that it 1482 measures the temperature of the surroundings (i.e., not including 1483 any heat generated by the measuring or measured equipment), 1484 expressed in degrees Celsius. 1486 Data Type: float 1488 Units: degrees Celsius 1490 Range: -273.15 - +inf 1492 ElementId: TBD 1494 Authors' Addresses 1496 Brian Trammell 1497 Swiss Federal Institute of Technology Zurich 1498 Gloriastrasse 35 1499 8092 Zurich 1500 Switzerland 1502 Phone: +41 44 632 70 13 1503 Email: trammell@tik.ee.ethz.ch 1505 Benoit Claise 1506 Cisco Systems, Inc. 1507 De Kleetlaan 6a b1 1508 1831 Diegem 1509 Belgium 1511 Phone: +32 2 704 5622 1512 Email: bclaise@cisco.com