idnits 2.17.1 draft-trammell-ipfix-text-iespec-01.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 5, 2010) is 5012 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '4' on line 205 -- Looks like a reference, but probably isn't: '65535' on line 200 -- Looks like a reference, but probably isn't: '1' on line 198 -- Looks like a reference, but probably isn't: '2' on line 193 -- Looks like a reference, but probably isn't: '8' on line 204 -- Looks like a reference, but probably isn't: '6' on line 199 -- Looks like a reference, but probably isn't: '16' on line 206 ** Obsolete normative reference: RFC 5101 (Obsoleted by RFC 7011) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 8 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: Informational August 5, 2010 5 Expires: February 6, 2011 7 A Lightweight Textual Format for IPFIX Information Models and Templates 8 draft-trammell-ipfix-text-iespec-01.txt 10 Abstract 12 This document describes a lightweight textual format for describing 13 IPFIX Information Models, IPFIX Templates, and IPFIX Options 14 Templates, designed for easy human readability and writability, and 15 fast, easily implemented and deployed parsing and generation. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on February 6, 2011. 34 Copyright Notice 36 Copyright (c) 2010 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 1. Introduction 51 The IP Flow Information Export Protocol (IPFIX) [RFC5101] affords new 52 levels of flexibility in defining Data Record formats through its 53 Template mechanism, and new Information Elements via an IANA registry 54 [iana-ipfix-assignments], enterprise-specific Information Elements, 55 and inline information model export as defined in [RFC5610]. 57 However, XML representations of Information Elements as in the IANA 58 registry [iana-ipfix-assignments] require transformation via XSLT (as 59 used by IANA) in order to become human-readable, are not particularly 60 easily human-writiable, and would require the inclusion of an XML 61 parser in each IPFIX Exporting and Collecting Process for use at 62 runtime. IPFIX Templates and Type Information Export as in [RFC5610] 63 are excellent for runtime, but not particularly human-readable. 65 This document proposes a simple textual syntax for describing IPFIX 66 Information Elements and IPFIX Templates, with human readability, 67 human writability, compactness, and ease of parser/generator 68 implementation without requiring external XML support as design 69 goals. It is intended primarily for use in human communication 70 (e.g., in new Internet-Drafts containing higher-level descriptions of 71 IPFIX Templates, or describing sets of new IPFIX Information Elements 72 for supporting new applications of the protocol), as well as at 73 runtime by IPFIX implementations. 75 PLEASE NOTE that this is intended ONLY as a proposed shorthand 76 format. It is under ACTIVE development. Authors are reminded that 77 it is inappropriate to cite an Internet-Draft as other than a work in 78 progress. This draft will likely be subsumed into a greater effort 79 to define how new Information Elements and recommended Templates are 80 developed within and outside the IPFIX Working Group. As such, 81 implementation or use of this representation within other Internet- 82 Drafts at this time is STRONGLY discouraged for implementors and 83 authors who are not prepared to track each change to this draft, for 84 it to be merged with other future work, or for it to expire entirely. 86 2. Terminology 88 Terms used in this document that are defined in the Terminology 89 section of the IPFIX Protocol [RFC5101] document are to be 90 interpreted as defined there. In addition, the following terms used 91 in this document are defined as follows: 93 textual Information Element specifier (IESpec): A string 94 representing the four important aspects of an Information Element 95 within the Information Model or within a Template: its name, its 96 number (with Private Enterprise Number if applicable), its data 97 type, and its length. 98 fully-qualified IESpec: An IESpec as above, containing enough 99 information to define an information element: at least a name, 100 number, and type, and a length for types without a native length. 101 IESpecs must be fully qualified to be of used in defining an 102 Information Model or extensions thereto. 103 partial IESpec: An IESpec that is not fully qualified. 105 Note that when the term Template is used in this document, it applies 106 both to Templates and Options Templates as defined in [RFC5101], 107 unless otherwise noted. 109 3. Information Element Specifier Syntax 111 The basis of this format is the textual Information Element 112 Specifier, or IESpec. An IESpec contains each of the four important 113 aspects of an Information Element: its name, its number, its type, 114 and its size, separated by simple markup based on various types of 115 brackets. Fully-qualified IESpecs may be used to specify existing or 116 new Information Elements within an Information Model, while either 117 fully-qualified or partial IESpecs may be used to define fields in a 118 Template. 120 Each aspect of information associated with an Information Element is 121 associated with a type of brackets. Bare words are used for 122 Information Element names, () parentheses for Information Element 123 numbers, <> angles for Information Element data types, and [] square 124 brackets for Information Element sizes. {} Curly braces are reserved 125 for optional and contextual use, described later in the document. 127 The basic form of a fully-qualified IESpec for an IANA-registered 128 Information Element is as follows: 130 name(number)[size] 132 where 'name' is the name of the Information Element in UTF-8, 133 'number' is the Information Element as a decimal integer, 'type' is 134 the name of the data type as in the IANA informationElementDataTypes 135 registry [iana-ipfix-assignments], and 'size' is the length of the 136 Information Element in octets as a decimal integer, where 65535 or 137 the string 'v' signifies a variable-length Information Element. 138 [size] may be omitted; in this case, the data type's native or 139 default size is assumed (see section Section 3.1. 141 The basic form of a fully-qualified IESpec for an enterprise-specific 142 Information Element is as follows: 144 name(pen/number)[size] 146 where 'pen' is the Private Enterprise Number as a decimal integer. 148 A fully-qualified IESpec is intended to express enough information 149 about an Information Element to decode and display Data Records 150 defined by Templates containing that Information Element. Range, 151 unit, semantic, and description information, as in [RFC5610], is not 152 supported by this syntax. 154 Example fully-qualified IESpecs follow: 155 o octetDeltaCount(1)[8] 156 o octetDeltaCount(1) (unsigned64 is natively 8 octets 157 long) 158 o sourceIPv4Address(8) 159 o wlanSSID(146)[v] 160 o sipRequestURI(35566/403)[65535] 162 A partial IESpec is any IESpec that is not fully-qualified; these are 163 useful when defining templates. A partial IESpec is assumed to take 164 missing values from its canonical definition, for example, the IANA 165 registry. At minimum, a partial IESpec must contain a name, or a 166 number. Any name, number, or type information given with a partial 167 IESpec must match the values given in the Information Model; however, 168 size information in a partial IESpec overrides size information in 169 the Information Model; in this way, IESpecs can be used to express 170 reduced-length encoding for Information Elements. 172 Example partial IESpecs follow: 173 o octetDeltaCount 174 o octetDeltaCount[4] (reduced-length encoding) 175 o (1) 176 o (1)[4] (reduced length encoding; note that this is exactly 177 equivalent to an Information Element specifier in a Template) 179 3.1. Native Sizes of Data Types 181 If absent in a fully-qualified IESpec, the size is assumed to be the 182 native or default size for the type, as follows: 184 +------------------------+-------------------------+ 185 | Data Type | Native Size | 186 +------------------------+-------------------------+ 187 | | [v], [65535] (variable) | 188 | | [1] | 189 | | [2] | 190 | | [4] | 191 | | [8] | 192 | | [1] | 193 | | [2] | 194 | | [4] | 195 | | [8] | 196 | | [4] | 197 | | [8] | 198 | | [1] | 199 | | [6] | 200 | | [v], [65535] (variable) | 201 | | [4] | 202 | | [8] | 203 | | [8] | 204 | | [8] | 205 | | [4] | 206 | | [16] | 207 +------------------------+-------------------------+ 209 4. Defining an Information Model from IESpecs 211 An Information Model, or an extension thereto (e.g., a set of 212 enterprise-specific Information Elements supplied to a Collector to 213 provide type information for information from a particular Exporter 214 in the absence of support for [RFC5610]; or a set of new Information 215 Elements compactly presented in an Internet-Draft describing a new 216 IPFIX application) can be expressed simply as a newline-separated 217 list of fully-qualified IESpecs. 219 5. Defining a Template or Options Template from IESpecs 221 A Template or Options Template can be expressed simply as an ordered 222 newline-separated list of partial or fully-qualified IESpecs. 223 IESpecs representing Scope Information Elements in an Options 224 Template take the {scope} option as a suffix to the IESpec, e.g.: 226 sourceIPv4Address{scope} 228 A syntax for an encapsulation of templates (including e.g. template 229 ID) is not yet defined. 231 6. Security Considerations 233 Any IPFIX implementation using externally-provided strings to define 234 Information Models and Templates must perform validation on those 235 strings to ensure safe operation, and ensure that parsers for these 236 strings are not vulnerable to common faults (e.g. buffer overflows); 237 further guidance is implementation and platform specific. 239 7. IANA Considerations 241 This document has no actions for IANA. 243 8. Normative References 245 [RFC5101] Claise, B., "Specification of the IP Flow Information 246 Export (IPFIX) Protocol for the Exchange of IP Traffic 247 Flow Information", RFC 5101, January 2008. 249 [RFC5610] Boschi, E., Trammell, B., Mark, L., and T. Zseby, 250 "Exporting Type Information for IP Flow Information Export 251 (IPFIX) Information Elements", RFC 5610, July 2009. 253 [iana-ipfix-assignments] 254 Internet Assigned Numbers Authority, "IP Flow Information 255 Export Information Elements 256 (http://www.iana.org/assignments/ipfix/ipfix.xml)". 258 Author's Address 260 Brian Trammell 261 Swiss Federal Institute of Technology Zurich 262 Gloriastrasse 35 263 8092 Zurich 264 Switzerland 266 Phone: +41 44 632 70 13 267 Email: trammell@tik.ee.ethz.ch