idnits 2.17.1
draft-ietf-sipclf-format-11.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 has examples using IPv4 documentation addresses according
to RFC6890, but does not use any IPv6 documentation addresses. Maybe
there should be IPv6 examples, too?
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but
does not include the phrase in its RFC 2119 key words list.
-- The document date (December 21, 2012) is 4141 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Outdated reference: A later version (-13) exists of
draft-ietf-sipclf-problem-statement-11
-- Obsolete informational reference (is this intentional?): RFC 2629
(Obsoleted by RFC 7749)
-- Obsolete informational reference (is this intentional?): RFC 5226
(Obsoleted by RFC 8126)
Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 SIPCLF G. Salgueiro
3 Internet-Draft Cisco Systems
4 Intended status: Standards Track V. Gurbani
5 Expires: June 24, 2013 Bell Labs, Alcatel-Lucent
6 A. B. Roach
7 Tekelec
8 December 21, 2012
10 Format for the Session Initiation Protocol (SIP) Common Log Format (CLF)
11 draft-ietf-sipclf-format-11
13 Abstract
15 The SIPCLF Workgroup has defined a common log format framework for
16 Session Initiation Protocol (SIP) servers. This common log format
17 mimics the successful event logging format found in well-known web
18 servers like Apache and web proxies like Squid. This document
19 proposes an indexed text encoding format for the SIP Common Log
20 Format (CLF) that retains the key advantages of a text-based format,
21 while significantly increasing processing performance over a purely
22 text-based implementation. This file format adheres to the SIP CLF
23 information model and provides an effective encoding scheme for all
24 mandatory and optional fields that appear in a SIP CLF record.
26 Status of this Memo
28 This Internet-Draft is submitted in full conformance with the
29 provisions of BCP 78 and BCP 79.
31 Internet-Drafts are working documents of the Internet Engineering
32 Task Force (IETF). Note that other groups may also distribute
33 working documents as Internet-Drafts. The list of current Internet-
34 Drafts is at http://datatracker.ietf.org/drafts/current/.
36 Internet-Drafts are draft documents valid for a maximum of six months
37 and may be updated, replaced, or obsoleted by other documents at any
38 time. It is inappropriate to use Internet-Drafts as reference
39 material or to cite them other than as "work in progress."
41 This Internet-Draft will expire on June 24, 2013.
43 Copyright Notice
45 Copyright (c) 2012 IETF Trust and the persons identified as the
46 document authors. All rights reserved.
48 This document is subject to BCP 78 and the IETF Trust's Legal
49 Provisions Relating to IETF Documents
50 (http://trustee.ietf.org/license-info) in effect on the date of
51 publication of this document. Please review these documents
52 carefully, as they describe your rights and restrictions with respect
53 to this document. Code Components extracted from this document must
54 include Simplified BSD License text as described in Section 4.e of
55 the Trust Legal Provisions and are provided without warranty as
56 described in the Simplified BSD License.
58 Table of Contents
60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
62 3. Document Conventions . . . . . . . . . . . . . . . . . . . . . 4
63 4. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
64 4.1. Index Pointers . . . . . . . . . . . . . . . . . . . . . . 8
65 4.2. Mandatory Fields . . . . . . . . . . . . . . . . . . . . . 10
66 4.3. SIP CLF Encoding and Character Escaping Requirements . . . 14
67 4.4. Optional Fields . . . . . . . . . . . . . . . . . . . . . 15
68 5. Example SIP CLF Record . . . . . . . . . . . . . . . . . . . . 24
69 6. Text Tool Considerations . . . . . . . . . . . . . . . . . . . 26
70 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26
71 8. Operational Guidance . . . . . . . . . . . . . . . . . . . . . 26
72 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
73 9.1. SIP CLF Version . . . . . . . . . . . . . . . . . . . . . 27
74 9.2. SIP CLF Transport Flag . . . . . . . . . . . . . . . . . . 27
75 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 28
76 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
77 11.1. Normative References . . . . . . . . . . . . . . . . . . . 28
78 11.2. Informative References . . . . . . . . . . . . . . . . . . 29
79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
81 1. Introduction
83 The extensive list of benefits and the widespread adoption of the
84 Apache Common Log Format (CLF) has prompted the development of an
85 analogous event logging mechanism for the Session Initiation Protocol
86 [RFC3261] (SIP). Implementing a logging scheme for SIP is a
87 considerable challenge. This is due in part to the fact that the
88 behavior of a SIP entity is more complex as compared to an HTTP
89 entity. Additionally, there are shortcomings to the purely text-
90 based HTTP Common Log Format that need to be addressed in order to
91 allow for real-time inspection of SIP log files
92 [I-D.ietf-sipclf-problem-statement]. Experience with Apache Common
93 Log Format has shown that dealing with large quantities of log data
94 can be very processor intensive, as doing so necessarily requires
95 reading and parsing every byte in the log file(s) of interest.
97 An implementation independent framework for the SIP CLF has been
98 defined in [I-D.ietf-sipclf-problem-statement]. This memo describes
99 an indexed text file format for logging SIP messages received and
100 sent by SIP clients, servers, and proxies that adheres to the
101 information model presented in Section 8 of
102 [I-D.ietf-sipclf-problem-statement]. This document defines a format
103 that is no more difficult to generate by logging entities than
104 standard (i.e., non-indexed) text log formats, while being radically
105 faster to process. In particular, the format is optimized for both
106 rapidly scanning through log records, as well as quickly locating
107 commonly accessed data fields.
109 Further, the format proposed by this document retains the key
110 advantage of being human readable and able to be processed using the
111 various Unix text processing tools, such as sed, awk, perl, cut, and
112 grep.
114 2. Terminology
116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
118 document are to be interpreted as described in [RFC2119].
120 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "NOT RECOMMENDED" are
121 appropriate when valid exceptions to a general requirement are known
122 to exist or appear to exist, and it is infeasible or impractical to
123 enumerate all of them. However, they should not be interpreted as
124 permitting implementors to fail to implement the general requirement
125 when such failure would result in interoperability failure.
127 [RFC3261] defines additional terms used in this document that are
128 specific to the SIP domain such as "proxy"; "registrar"; "redirect
129 server"; "user agent server" or "UAS"; "user agent client" or "UAC";
130 "back-to-back user agent" or "B2BUA"; "dialog"; "transaction";
131 "server transaction".
133 This document uses the term "SIP Server" that is defined to include
134 the following SIP entities: user agent server, registrar, redirect
135 server, a SIP proxy in the role of user agent server, and a B2BUA in
136 the role of a user agent server.
138 The reader is expected to be familiar with the terminology and
139 concepts defined in [I-D.ietf-sipclf-problem-statement].
141 3. Document Conventions
143 This document defines the logging syntax for the SIP CLF. This
144 syntax is demonstrated through the use of various examples. The
145 formatting described here does not permit these examples to be
146 unambiguously rendered due to the constraints imposed by the
147 formatting rules for RFCs. To avoid ambiguity and to meet the RFC
148 layout requirements this document uses the markup
149 convention established in [RFC4475].
151 For the sake of clarity and completeness, the entire text defining
152 this markup convention from Section 2.1 of [RFC4475] is quoted below:
154 Several of these examples contain unfolded lines longer than 72
155 characters. These are captured between tags. The
156 single unfolded line is reconstructed by directly concatenating
157 all lines appearing between the tags (discarding any line feeds or
158 carriage returns). There will be no whitespace at the end of
159 lines. Any whitespace appearing at a fold-point will appear at
160 the beginning of a line.
162 The following represent the same string of bits:
164 Header-name: first value, reallylongsecondvalue, third value
166
167 Header-name: first value,
168 reallylongsecondvalue
169 , third value
170
172
173 Header-name: first value,
174 reallylong
175 second
176 value,
177 third value
178
180 Note that this is NOT SIP header-line folding, where different
181 strings of bits have equivalent meaning.
183 The IP addresses used in the examples in this document correspond to
184 the documentation address block 192.0.2.0/24 (TEST-NET-1) as
185 described in [RFC5737].
187 4. Format
189 The Common Log Format for the Session Initiation Protocol
190 [I-D.ietf-sipclf-problem-statement] defines an information model to
191 which this logging format format adheres, and Section 8.1 of that
192 document defines all the mandatory information model elements.
194 This document defines the format of SIP CLF records as follows:
196 0 7 8 15 16 23 24 31
197 +-----------+-----------+-----------+-----------+
198 | Version | Record Length | 0 - 3
199 +-----------+-----------+-----------+-----------+
200 | Record Length (cont) | 0x2C | 4 - 7
201 +-----------+-----------+-----------+-----------+
202 | CSeq Pointer (Hex) | 8 - 11
203 +-----------+-----------+-----------+-----------+
204 | Response Status-Code Pointer (Hex) | 12 - 15
205 +-----------+-----------+-----------+-----------+
206 | R-URI Pointer (Hex) | 16 - 19
207 +-----------+-----------+-----------+-----------+
208 | Destination IP address:port Pointer (Hex) | 20 - 23
209 +-----------+-----------+-----------+-----------+
210 | Source IP address:port Pointer (Hex) | 24 - 27
211 +-----------+-----------+-----------+-----------+
212 | To URI Pointer (Hex) | 28 - 31
213 +-----------+-----------+-----------+-----------+
214 | To Tag Pointer (Hex) | 32 - 35
215 +-----------+-----------+-----------+-----------+
216 | From URI Pointer (Hex) | 36 - 39
217 +-----------+-----------+-----------+-----------+
218 | From Tag Pointer (Hex) | 40 - 43
219 +-----------+-----------+-----------+-----------+
220 | Call-Id Pointer (Hex) | 44 - 47
221 +-----------+-----------+-----------+-----------+
222 | Server-Txn Pointer (Hex) | 48 - 51
223 +-----------+-----------+-----------+-----------+
224 | Client-Txn Pointer (Hex) | 52 - 55
225 +-----------+-----------+-----------+-----------+
226 | Optional Fields Start Pointer (Hex) | 56 - 59
227 +-----------+-----------+-----------+-----------+
228 | 0x0A | | 60 - 63
229 +-----------+ +
230 | Timestamp | 64 - 67
231 + +-----------+
232 | | 0x2E | 68 - 71
233 +-----------+-----------+-----------+-----------+
234 | Fractional Seconds | 0x09 | 72 - 75
235 +-----------+-----------+-----------+-----------+
236 | Flags Field | 76 - 79
237 +-----------+-----------+-----------+-----------+
238 |Flag (cont)| 0x09 | | 80 - 83
239 |-----------+-----------+ |
240 | |
241 | |
242 | Mandatory Fields (variable length) |
243 | |
244 | |
245 +-----------+-----------+-----------+-----------+
246 | 0x09 | Tag | 0x40 |\
247 +-----------+-----------+-----------+-----------+ \
248 | Vendor-ID | \
249 +-----------+-----------+-----------+-----------+ \
250 | Vendor-ID (cont) | \ Repeated
251 +-----------+-----------+-----------+-----------+ \ as many
252 | 0x2C | Length (Hex) | > times as
253 +-----------+-----------+-----------+-----------+ / necessary
254 | Len (cont)| 0x2C | BEB | 0x2C | /
255 +-----------+-----------+-----------------------| /
256 | | /
257 | Value (variable length) | /
258 | |/
259 +-----------+-----------+-----------+-----------+
260 | 0x0A |
261 +-----------+
263 Figure 1: SIP Common Log Format
265 The format presented in Figure 1 is for a single SIP CLF log entry.
266 While there is no actual subdivision in practice, this format can be
267 logically subdivided into the following three distinct components:
269 1. Index Pointers - The first 60-bytes of this format. This
270 portion is metadata, primarily composed of a list of pointers that
271 indicate the beginning of both the variable length mandatory and
272 optional fields that are logged as part of this record. These
273 pointers are implemented as a mechanism to improve processing of
274 these records and to allow a reader to expeditiously skip directly
275 to the desired field without unnecessarily going through the
276 entire record. This logical subdivision within the SIP CLF format
277 will be referenced in this document with the tag.
278 A 0x0A (LF character) delimits from the next
279 logical grouping.
281 2. Mandatory Fields - The next logical grouping in this format is
282 a tab (0x09) delimited listing of the mandatory fields as
283 described in Section 8.1 of [I-D.ietf-sipclf-problem-statement]
284 and in the order listed in . This logical
285 subdivision within the SIP CLF format will be referenced in this
286 document with the tag.
288 3. Optional Fields - The last logical component MAY be present as
289 it is an OPTIONAL extension to the SIP CLF format. Its purpose is
290 to provide flexibility to the developer of this SIP CLF to log any
291 desired fields not included in . This includes
292 SIP bodies and any vendor-specific extensions. This logical
293 subdivision within the SIP CLF format will be referenced in this
294 document with the tag.
296 This logical structure of the SIP CLF record format can be
297 graphically represented as shown in Figure 2 below:
299
300
301
303 Figure 2: Logical Structure of the SIP CLF Record
305 Note that Figure 1 and Figure 2 plus the terminating line-feed (0x0A)
306 at the end of the SIP CLF record are different representations of the
307 same format but are functionally equivalent. The representation of
308 this format is a two line record where the metadata
309 is on one line and the actual data like and
310 (if present) is on another.
312 In the following sections note that indications of "hexadecimal
313 encoded" indicate values that are always unsigned and are to be
314 written out in human-readable base-16 numbers using the UTF-8
315 characters 0x30 through 0x39 ('0' through '9') and 0x41 through 0x46
316 ('A' through 'F'). Similarly, indications of "decimal encoded"
317 indicate that the value is to be written out in human readable
318 base-10 number using the UTF-8 characters 0x30 through 0x39 ('0'
319 through '9'). In both encodings, numbers always take up the number
320 of bytes indicated, and are padded on the left with UTF-8 '0' (zero)
321 characters to fill the entire space.
323 4.1. Index Pointers
324 The portion of the SIP CLF record (shown in Figure 3)
325 is a 60-byte header that indicates metadata about the record.
327 0 7 8 15 16 23 24 31
328 +-----------+-----------+-----------+-----------+
329 | Version | Record Length | 0 - 3
330 +-----------+-----------+-----------+-----------+
331 | Record Length (cont) | 0x2C | 4 - 7
332 +-----------+-----------+-----------+-----------+
333 | CSeq Pointer (Hex) | 8 - 11
334 +-----------+-----------+-----------+-----------+
335 | Response Status-Code Pointer (Hex) | 12 - 15
336 +-----------+-----------+-----------+-----------+
337 | R-URI Pointer (Hex) | 16 - 19
338 +-----------+-----------+-----------+-----------+
339 | Destination IP address:port Pointer (Hex) | 20 - 23
340 +-----------+-----------+-----------+-----------+
341 | Source IP address:port Pointer (Hex) | 24 - 27
342 +-----------+-----------+-----------+-----------+
343 | To URI Pointer (Hex) | 28 - 31
344 +-----------+-----------+-----------+-----------+
345 | To Tag Pointer (Hex) | 32 - 35
346 +-----------+-----------+-----------+-----------+
347 | From URI Pointer (Hex) | 36 - 39
348 +-----------+-----------+-----------+-----------+
349 | From Tag Pointer (Hex) | 40 - 43
350 +-----------+-----------+-----------+-----------+
351 | Call-Id Pointer (Hex) | 44 - 47
352 +-----------+-----------+-----------+-----------+
353 | Server-Txn Pointer (Hex) | 48 - 51
354 +-----------+-----------+-----------+-----------+
355 | Client-Txn Pointer (Hex) | 52 - 55
356 +-----------+-----------+-----------+-----------+
357 | Optional Fields Start Pointer (Hex) | 56 - 59
358 +-----------+-----------+-----------+-----------+
360 Figure 3: Index Pointers
362 The fields that make up are described below:
364 Version (1 byte): UTF-8 encoded version for the SIP CLF record.
365 Range of valid values for the Version is from 'A' (0x41) to 'Z'
366 (0x5A). This document uses a Version value of "0x41" ('A').
368 The value of the SIP CLF Version MUST be incremented for any new
369 SIP CLF specification that changes any part of the SIP CLF record
370 format. The SIP CLF Version values are IANA-assigned
371 (Section 9.1) via the Standards Action method as described in
372 [RFC5226].
374 Since the version is specified per record it is possible that a
375 SIP CLF log file could contain records with different versions.
376 Under normal operating conditions this is an unlikely occurrence
377 and SHOULD be avoided if possible.
379 Record Length (6 bytes): Hexadecimal encoded total length of this
380 log record, beginning with the "Version" octet and ending with the
381 terminating line-feed.
383 Bytes 8 through 55 contain hexadecimal encoded pointers that point to
384 the starting location of each of the variable-length mandatory
385 fields. Bytes 56 through 59 contain hexadecimal encoded pointer that
386 points to the starting location of the optional fields portion of the
387 SIP CLF record. Note that there are no delimiters between these
388 pointer values -- they are packed together as a single, 52-character
389 hexadecimal encoded string. The "Pointer" fields indicate absolute
390 byte values within the record, and are therefore >=82. They point to
391 the start of the corresponding value within the
392 portion. A description of each of the mandatory fields that these
393 pointer values point to can be found in Section 4.2.
395 Optional Fields Start Pointer: This final pointer indicates the
396 location within the SIP CLF record where the OPTIONAL group of
397 begin, if present. The "Optional Fields Start
398 Pointer" points to the UTF-8 Tab (0x09) character for the first
399 entry in the portion. If the OPTIONAL group of
400 are not implemented, then the "Optional Fields
401 Start Pointer" field MUST point to the terminating line-feed
402 (0x0A) at the end of the SIP CLF record.
404 4.2. Mandatory Fields
405 The portion of the SIP CLF record is shown below:
407 0 7 8 15 16 23 24 31
408 +-----------+-----------+-----------+-----------+
409 | 0x0A | | 60 - 63
410 +-----------+ +
411 | Timestamp | 64 - 67
412 + +-----------+
413 | | 0x2E | 68 - 71
414 +-----------+-----------+-----------+-----------+
415 | Fractional Seconds | 0x09 | 72 - 75
416 +-----------+-----------+-----------+-----------+
417 | Flags Field | 76 - 79
418 +-----------+-----------+-----------+-----------+
419 |Flag (cont)| 0x09 | | 80 - 83
420 |-----------+-----------+ |
421 | |
422 | |
423 | Mandatory Fields (variable length) |
424 | |
425 | |
426 +-----------+-----------+-----------+-----------+
428 Figure 4: Mandatory Fields
430 Following the pointers in , two fixed-length fields
431 are encoded to specify the exact time of the log entry. As before,
432 all fields are completely filled, pre-pending values with '0'
433 characters as necessary.
435 Timestamp (10 bytes): Decimal encoded date and time of the request
436 or response represented as the number of seconds since the Unix
437 epoch (i.e. seconds since midnight, January 1st, 1970, GMT).
439 Fractional Seconds (3 bytes): Decimal encoded fractional seconds
440 portion of the Timestamp field to millisecond accuracy.
442 The combined Timestamp and Fractional Seconds fields are
443 represented in the log file as a UTF-8 encoded string representing
444 the date and time of the request or response represented as the
445 number of seconds and milliseconds since the Unix epoch. The
446 number of milliseconds are separated by a "." (UTF-8 character
447 0x2E) from the number of seconds.
449 Flags Field (5 bytes):
451 byte 1 - Request/Response Flag
453 R = Request
454 r = Response
456 byte 2 - Retransmission Flag
458 O = Original transmission
459 D = Duplicate transmission
460 S = Server is stateless [i.e., retransmissions are not
461 detected]
463 byte 3 - Sent/Received Flag
465 S = Sent message
466 R = Received message
468 byte 4 - Transport Flag
470 The Transport Flag values are IANA-assigned (Section 9.2) via
471 the IETF Review method as described in [RFC5226]. Currently
472 registered values are:
474 U = UDP
475 T = TCP
476 S = SCTP
478 byte 5 - Encryption Flag
480 E = Encrytped message (TLS, DTLS, etc.)
481 U = Unencrypted message
483 After the "Timestamp", "Fractional Seconds" and the "Flags" fields
484 are the values for the mandatory fields specified in Section 8.1 of
485 [I-D.ietf-sipclf-problem-statement], which are described below:
487 CSeq: The Command Sequence header field, including the CSeq number
488 and method name.
490 Response Status-Code: Set to the value of the SIP response status
491 code for responses. Set to a single UTF-8 dash (0x2D) for
492 requests.
494 R-URI: The Request-URI in the start line (mandatory in request),
495 including any URI parameters.
497 Destination IP address:port The IP address of the downstream server
498 and the port number, separated by a single ':'. IPv4 addresses
499 are represented in "dotted decimal" notation as per [RFC1166].
500 IPv6 addresses are represented using the hexadecimal notation
501 detailed in Section 4 of [RFC5952] (or the special-case mixed
502 hexadecimal and decimal notation detailed in Section 5 of
503 [RFC5952]) and enclosed in square brackets ('[' and ']').
505 Source IP address:port Source IP address:port The IP address of the
506 upstream client and the port number over which the SIP message was
507 received, separated by a single ':'. IPv4 addresses are
508 represented in "dotted decimal" notation as per [RFC1166]. IPv6
509 addresses are represented using the hexadecimal notation detailed
510 in Section 4 of [RFC5952] (or the special-case mixed hexadecimal
511 and decimal notation detailed in Section 5 of [RFC5952]) and
512 enclosed in square brackets ('[' and ']').
514 To URI: Value of the URI in the To header field.
516 To Tag: Value of the tag parameter (if present) in the To header
517 field.
519 From URI: Value of the URI in the From header field.
521 From Tag: Value of the tag parameter (if present) in the From header
522 field.
524 Call-Id: The value of the Call-ID header field.
526 Server-Txn: Server transaction identification code - the transaction
527 identifier associated with the server transaction.
528 Implementations can reuse the server transaction identifier (the
529 topmost branch-id of the incoming request, with or without the
530 magic cookie), or they could generate a unique identification
531 string for a server transaction (this identifier needs to be
532 locally unique to the server only.) This identifier is used to
533 correlate ACKs and CANCELs to an INVITE transaction; it is also
534 used to aid in forking. (See Section 9 of
535 [I-D.ietf-sipclf-problem-statement] for usage.)
537 Client-Txn: Client transaction identification code - this field is
538 used to associate client transactions with a server transaction
539 for forking proxies or B2BUAs. Upon forking, implementations can
540 reuse the value they inserted into the topmost Via header's branch
541 parameter, or they can generate a unique identification string for
542 the client transaction. (See Section 9 of
543 [I-D.ietf-sipclf-problem-statement] for usage.)
545 Note: The definitions of the Server-Txn and Client-Txn are taken
546 directly from [I-D.ietf-sipclf-problem-statement] and are provided
547 here only as a convenience to the implementer. The definitions
548 specified in [I-D.ietf-sipclf-problem-statement] should be
549 considered authoritative in the event of a conflict.
551 This data MUST appear in the order listed in , and
552 each field MUST be present. Fields are subject the maximum SIP CLF
553 field size of 4096 bytes as detailed in Section 8 of
554 [I-D.ietf-sipclf-problem-statement].
556 4.3. SIP CLF Encoding and Character Escaping Requirements
558 The mandatory fields in a SIP CLF record are separated by a single
559 UTF-8 Tab character (0x09). Any Tab characters present in the data
560 to be written will be replaced by a UTF-8 space character (0x20)
561 prior to being logged.
563 The decision to replace tabs with spaces was based on there being no
564 standardized use of tabs in SIP headers to convey any other meaning
565 than whitespace. Tabs may appear in message bodies, and in the event
566 that the bodies are logged, the conversion to space may cause
567 problems when reconstructing the body from the corresponding log
568 entry. Two consequences of the decision to replace tab with a space
569 character are: (a) it will become impossible to reconstruct a
570 signature over the logged field that matches the signature over
571 fields in the original SIP message, and (b) any future SIP header
572 fields that include tabs with a different semantic meaning than
573 simply signifying whitespace will lose this meaning when logged. And
574 finally, the tabs to spaces substitution MUST occur when logging
575 mandatory fields and optional SIP Header Field or Reason-Phrase
576 (Tag=00); it MUST also occur when when optionally logging either the
577 entire message (Tag=02) or simply a SIP body (Tag=01) as described in
578 Section 4.4.
580 An element will not always have an appropriate value to provide for
581 one of these fields, even when the field is required to appear in the
582 SIP CLF record. In such circumstances, when a given mandatory field
583 from Section 4.2 and specified in Section 8.1 of
584 [I-D.ietf-sipclf-problem-statement]) is not present then that empty
585 field MUST be encoded as a single horizontal dash ("-"). In the
586 event that a field failed to parse it MUST be encoded as a single
587 question mark ("?"). If these characters are part of a sequence of
588 other characters, then there is no ambiguity. If the field being
589 logged contains only one character, and that character is the literal
590 "-", the implementation SHOULD insert an escaped %2D for that field
591 in the SIP CLF record. Similarly, if the field contains only one
592 character, and that character is the literal "?", the implementation
593 SHOULD insert an escaped %3F for that field in the SIP CLF record.
595 The terminating carriage return line feed (CRLF) after a given header
596 field value MUST NOT be logged. Since a bare CRLF sequence is not
597 permitted within a SIP header field value, mandatory fields MUST NOT
598 contain a CRLF when logged and consequently no escaping mechanism is
599 required for it.
601 Clearly a SIP parser could not possibly successfully parse a SIP CLF
602 record in its entirety given the SIP CLF format described in this
603 document. It is possible to parse individual fields in the SIP CLF
604 record if they are extracted and given to a SIP parser that would
605 normally parse those sequence of strings. It should be noted that
606 any field value that is modified by the escaping mechanisms defined
607 in this document before logging ('-','?', and CRLF) is likely no
608 longer well-formed SIP and will fail when given to such a parser.
610 The intent of logging using SIP CLF is not to faithfully recreate the
611 bit-exact SIP message being logged. In fact, the formatting rules,
612 encoding and character escaping requirements preclude this and may
613 introduce information loss relative to the original SIP message. A
614 log reader should never unescape anything in the SIP CLF record since
615 they are intended to be machine processed using text tools such as
616 grep and awk. The human user behind the log reader may be required
617 to infer more semantics about any differences between the original
618 SIP message and its SIP CLF representation.
620 4.4. Optional Fields
621 The portion of the SIP CLF record is shown below:
623 0 7 8 15 16 23 24 31
624 +-----------+-----------+-----------+-----------+
625 | 0x09 | Tag | 0x40 |\
626 +-----------+-----------+-----------+-----------+ \
627 | Vendor-ID | \
628 +-----------+-----------+-----------+-----------+ \
629 | Vendor-ID (cont) | \ Repeated
630 +-----------+-----------+-----------+-----------+ \ as many
631 | 0x2C | Length (Hex) | > times as
632 +-----------+-----------+-----------+-----------+ / necessary
633 | Len (cont)| 0x2C | BEB | 0x2C | /
634 +-----------+-----------+-----------------------| /
635 | | /
636 | Value (variable length) | /
637 | |/
638 +-----------+-----------+-----------+-----------+
640 Figure 5: Optional Fields
642 Optional fields are those SIP message elements that are not a part of
643 the mandatory fields list detailed in Section 8.1 of
644 [I-D.ietf-sipclf-problem-statement]. After the
645 section, there is an OPTIONAL group (shown in
646 Figure 5) that MAY appear zero or more times. This
647 group provides extensibility to the SIP CLF. It allows SIP CLF
648 implementers the flexibility to extend the logging capability of this
649 indexed text representation beyond just the mandatory log elements
650 described in Section 8.1 of [I-D.ietf-sipclf-problem-statement].
652 Logging any optional SIP elements MUST be done according to the
653 format shown in Figure 5. The location of the start of
654 within the SIP CLF record is indicated by the
655 "Optional Fields Start Pointer" field in . After the
656 initial Tab delimiter byte (0x09) shown in Figure 5, the optional
657 field being logged is generally represented by the notation:
659 Tag@Vendor-ID,Length,BEB,Value
661 The optional field identifier (Tag@Vendor-ID) is composed of a two
662 byte Tag and an eight byte Vendor-ID (both decimal encoded) separated
663 by an "@" character (0x40). This uniquely identifies the optional
664 field being logged. The format for this identifier is loosely
665 modeled after the private use option used by the Syslog protocol
666 [RFC5424] (Note: this is the second format detailed in Section 6.3.2
667 of [RFC5424]). It makes use of the Private Enterprise Number (PEN),
668 which provides an identifier through a globally unique name space
670 [PEN]. This syntax provides the necessary extensibility to SIP CLF
671 to allow logging of any SIP header, body, as well as any vendor-
672 specified SIP element.
674 The Base64 Encoded Byte (BEB) is a boolean that is used to indicate
675 whether the optional element being logged is Base64 encoded or not.
676 The Value field for the optional element being logged MUST be Base64
677 encoded if it has any characters that are 'unprintable'. For the
678 purposes of this document, we define 'unprintable' to mean a string
679 of octets that: (a) contains an octet with a value in the range of 0
680 to 31, inclusive; (b) contains an octet with a value of 127; or (c)
681 contains any series of octets greater than or equal to 128 which do
682 not form a valid UTF-8 sequence, as specified by [UNICODE]. If the
683 optional element being logged is Base64 encoded then BEB=0x01; if it
684 is not Base64 encoded then BEB=0x00.
686 Optional fields are logged according to the following two syntax
687 rules:
689 (1) Vendor-ID = 00000000
691 A Vendor-ID of zero is used to log the entire SIP message, message
692 body, Reason-Phrase or any SIP header fields that are not a part
693 of the mandatory fields list detailed in Section 8.1 of
694 [I-D.ietf-sipclf-problem-statement]. The following Tag values are
695 used to identify which of these optional elements are being
696 logged:
698 Tag = 00 - Log SIP Header Field or Reason-Phrase
700 When logging a SIP Header Field (Tag=00), the associated
701 "Value" field MUST be populated by the entire header field
702 being logged. That is, the field-name, the associated colon
703 (":") and the field-value. This mechanism provides the
704 capability to optionally log any SIP header field by
705 identifying the field being logged within the "Value" field.
707 Because the Reason-Phrase in a response is part of the Status-
708 Line and is not identified with a field-name, it is a special
709 case. In this instance, the the associated "Value" field MUST
710 be populated by the name "Reason-Phrase" followed by a colon
711 (":") and a single space (SP) between the colon and the logged
712 Reason-Phrase value.
714 The corresponding "Length" field includes the length of the
715 entire "Value" field. This includes the field-name, the colon,
716 and any LWS separator. For Tag=00 the BEB is set according to
717 whether the SIP Header Field value contains any 'unprintable'
718 characters. If it does not the BEB=00; if it does the BEB=01.
719 If BEB=01 then only the field-value MUST be Base64 encoded; the
720 field-name, the associated colon and any LWS separator MUST
721 retain their original encoding.
723 If an optional field occurs more than once in a SIP message
724 (e.g. Contact, Route, Record-Route, etc.) then each occurrence
725 MUST be logged with the same Tag value (i.e., Tag=00) as a
726 distinct optional field entry in the SIP CLF record. These
727 repeated optionally logged header fields MUST preserve the
728 ordinal position of the repeated header fields in the SIP
729 header. For example, a SIP header containing two Via header
730 fields with the following ordinal positions within the SIP
731 header: V1,V2. If optionally logging these header fields they
732 would occur as the following entries in the SIP CLF record.
733 (Note: For the sake of brevity this example only shows how
734 these optional header fields would be logged and omits the
735 remainder of the SIP CLF record):
737 00@00000000,len_V1,00,Via: V1 00@00000000,len_V2,00,Via: V2
739 The terminating carriage return line feed (CRLF) after a given
740 header field value MUST NOT be logged. Since a bare CRLF
741 sequence is not permitted within a SIP header field value,
742 optional SIP header fields logged with Tag=00 MUST NOT contain
743 a CRLF when logged and consequently no escaping mechanism is
744 required for it.
746 Tag = 01 - Log message body
748 SIP message bodies of all types can be optionally logged using
749 Tag=01. If the message body is logged it MUST adhere to the
750 maximum size limitation of 4096 bytes for a SIP CLF field, as
751 detailed in Section 8 of [I-D.ietf-sipclf-problem-statement].
752 Unlike with Tag=00, there can only be a single entry in the SIP
753 CLF record with Tag=01. When optionally logging the message
754 body if the maximum SIP CLF field size of 4096 bytes is
755 exceeded the message body being logged MUST be truncated to
756 meet these size limitations.
758 When logging a message body (Tag=01), the associated "Value"
759 field is populated with the Content-Type itself plus the SIP
760 message body separated with a space. In this manner,
761 everything about the SIP message body is self-described using a
762 single tag as compared to enumerating a separate tag for each
763 body type. Additionally, the corresponding "Length" field
764 includes the SIP message body, the length of the embedded
765 Content-Type, and the space separator between the MIME type and
766 the body content.
768 For an optionally logged message body (Tag=01) the BEB is set
769 according to whether the message body contains any
770 'unprintable' characters. If it does not the BEB=00; if it
771 does the BEB=01. If BEB=01 then the message body that follows
772 is entirely Base64 encoded except the prepended Content-Type as
773 described in the previous paragraph.
775 If an optionally logged SIP message body contains any CRLFs
776 they MUST be escaped by using the URI encoded equivalent value
777 of "%0D%0A". This escaping mechanism applies to all body
778 types. So we don't make any distinction in treatment between
779 the various possible body types. If a logged message body has
780 BEB=01 then it MUST be Base64 encoded prior to any character
781 escaping. Thus, if a binary body (like an image) is logged it
782 will be Base64 encoded first and that Base64 character stream
783 could never include the CRLF escape sequence of "%0D%0A"
784 because "%" is not a valid Base64 character.
786 Tag = 02 - Log entire SIP message
788 The entire SIP message (i.e., SIP header and message body) can
789 be optionally logged using a Tag=02. Logging the entire SIP
790 message MUST conform to the maximum size limitation of 4096
791 bytes for a SIP CLF field, as detailed in Section 8 of
792 [I-D.ietf-sipclf-problem-statement]. Unlike with Tag=00, there
793 can only be a single entry in the SIP CLF record with Tag=02.
794 When optionally logging the entire SIP message if the maximum
795 SIP CLF field size of 4096 bytes is exceeded the entire SIP
796 message being logged MUST be truncated to meet these size
797 limitations.
799 When optionally logging an entire SIP message (Tag=02) the BEB
800 is set according to whether the message body portion contains
801 any 'unprintable' characters. If it does not the BEB=00; if it
802 does the BEB=01. If BEB=01 then the entire SIP message is
803 Base64 encoded (not just the message body). Note that unlike
804 the case of Tag=01, when logging an entire SIP message (Tag=02)
805 with 'unprintable' characters (BEB=01) the Content-Type would
806 not be known prior to decode.
808 All instances of CRLFs, whether they appear in the SIP headers
809 or the SIP message body MUST be escaped by using the URI
810 encoded equivalent value of "%0D%0A". If a logged SIP message
811 has BEB=01 then it MUST be Base64 encoded prior to any
812 character escaping.
814 (2) Vendor-ID = PEN
816 A Vendor-ID set to a vendor's own private enterprise number from
817 the complete current list of private enterprise numbers maintained
818 by IANA [PEN] is used to log any other vendor-specified optional
819 element of a SIP header or body. The value of the Tag is set at
820 the discretion of the implementer:
822 Tag = Vendor-specified tag
824 The definition of the various values of the optional field identifier
825 (Tag@Vendor-ID) are the basis of how optional elements are logged in
826 the SIP CLF. For the sake of completeness the remaining fields in
827 the format shown in Figure 5 are also defined below:
829 Length Field (4 bytes): Indicates the length of only the "Value"
830 field of this optionally logged element (as shown in Figure 5),
831 hexadecimal encoded. This length corresponds to the length of the
832 "Value" field only and MUST NOT include any of the other elements
833 shown in Figure 5.
835 Base64 Encoded Byte (BEB) Field (1 byte): Indicates whether the
836 subsequent Value Field of the optionally logged element is Base64
837 encoded or not. The Value field for the optional element being
838 logged MUST be Base64 encoded if it contains any character that is
839 deemed 'unprintable' according to the definition given previously
840 in this section. If the optional element being logged is Base64
841 encoded then BEB=0x01; if it is not Base64 encoded then BEB=0x00.
843 Value Field (0 to 4096 bytes): Contains the actual value of this
844 optional field. As with the mandatory fields, UTF-8 Tab
845 characters (0x09) are replaced with UTF-8 space characters (0x20).
847 The following are examples of optionally logged SIP elements using
848 the syntax described in this section. All these examples only show
849 the portion of the SIP CLF record. The mandatory
850 and portions of the SIP CLF are
851 intentionally omitted for the sake of brevity. Note that all of
852 these examples of optionally logged fields begin with a leading Tab
853 delimiter byte (0x09) that is not apparent here.
855 (1) Contact header field logged as an optional field:
857 Consider the SIP response:
859 SIP/2.0 180 Ringing
860
861 Via: SIP/2.0/UDP host.example.com;
862 branch=z9hG4bKnashds8;received=192.0.2.1
863
864 To: Bob ;tag=a6c85cf
865 From: Alice ;tag=1928301774
866 Call-ID: a84b4c76e66710
867 Contact:
868 CSeq: 314159 INVITE
869 Content-Length: 0
871 The Contact header field would be logged as an optional field in
872 the following manner:
874 00@00000000,001C,00,Contact:
876 (2) Reason-Phrase logged as an optional field:
878 For the same SIP response the Reason-Phrase would be logged as
879 an optional field in the following manner:
881 00@00000000,0016,00,Reason-Phrase: Ringing
883 (3) SDP body to be logged as an optional field:
885 v=0
886 o=alice 2890844526 2890844526 IN IP4 host.example.com
887 s=-
888 c=IN IP4 host.example.com
889 t=0 0
890 m=audio 49170 RTP/AVP 0 8 97
892 This body has a Content-Type of application/sdp and is of length
893 of 123 bytes including all the line-feeds. When logging this
894 body the "Value" field is composed of the Content-Type and the
895 body separated by a space, which gives it a combined length of
896 139 (0x008B) bytes. This SIP body would be logged as an
897 optional field in the following manner:
899
900 01@00000000,008B,00,application/sdp v=0%0D%0Ao=alice 2890844526
901 2890844526 IN IP4 host.example.com%0D%0As=-%0D%0A
902 c=IN IP4 host.example.com%0D%0At=0 0%0D%0A
903 m=audio 49170 RTP/AVP 0 8 97%0D%0A
904
906 Note that the body is actually logged on a single line and is
907 thus captured between tags. The line-feeds are
908 escaped using %0D%0A to delimit the various lines in the message
909 body.
911 (4) binary body to be logged as an optional field:
913 The second body part of the multipart/mime SIP message shown in
914 Section 3.1.1.11 of RFC4475 is a binary encoded body
915 (represented in hex) and if logged would have BEB=01 and would
916 require Base64 encoding. That binary body would produce six
917 lines of output after being Base64 encoded. Subsequent escaping
918 of the CRLF characters would produce an optionally logged body
919 that would look like:
921
922 01@00000000,0216,01,multipart/mixed;boundary=7a9cbec02ceef655 MI
923 IBUgYJKoZIhvcNAQcCoIIBQzCCAT8CAQExCTAHBgUrDgMCGjALBgkqhkiG9w0BBw
924 ExggEgMIIB%0D%0AHAIBATB8MHAxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxp
925 Zm9ybmlhMREwDwYDVQQHEwhTYW4g%0D%0ASm9zZTEOMAwGA1UEChMFc2lwaXQxKT
926 AnBgNVBAsTIFNpcGl0IFRlc3QgQ2VydGlmaWNhdGUgQXV0%0D%0AaG9yaXR5AggB
927 lQBxAjMBEzAHBgUrDgMCGjANBgkqhkiG9w0BAQEFAASBgI70ZvlI8FIt0uWXjp2V
928 %0D%0Aquny/hWgZllxYpLo2iqo2DUKaM7/rjy9K/8Wdd3VZI5ZPdZHKPJiIPfpQX
929 SeMw2aFe2r25PRDEIQ%0D%0ALntyidKcwMmuLvvHwM/5Fy87An5PwCfhVG3ktqo6
930 uz5mzMtd1sZLg4MUnLjm/xgtlE/le2W8mdAF%0D%0A
931
933 Note that the body is actually logged on a single line and is
934 thus captured between tags. The line-feeds are
935 escaped using %0D%0A to delimit the various lines in the Base64
936 encoded binary body.
938 (5) Codec information from the SDP body logged as an optional field:
940 Consider the SIP message:
942 INVITE sip:bob@example.com SIP/2.0
943 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bKnashds8
944 To: Bob
945 From: Alice ;tag=1928301774
946 Call-ID: a84b4c76e66710
947 CSeq: 314159 INVITE
948 Max-Forwards: 70
949 Date: Thu, 21 Feb 2002 13:02:03 GMT
950 Contact:
951 Content-Type: application/sdp
952 Content-Length: 147
954 v=0
955 o=UserA 2890844526 2890844526 IN IP4 example.com
956 s=Session SDP
957 c=IN IP4 host.example.com
958 t=0 0
959 m=audio 49172 RTP/AVP 0
960 a=rtpmap:0 PCMU/8000
962 A vendor may choose to log a SIP message element such as the
963 codec information from the SDP body. This Vendor-specified SIP
964 element would be logged as an optional field in the following
965 manner:
967 03@00032473,0014,00,a=rtpmap:0 PCMU/8000
969 (6) N-th message received from a particular peer logged as an
970 optional field:
972 Perhaps a vendor wants to log that this message is the n-th
973 message received from a peering partner. To do so for the SIP
974 message shown above, the vendor would log this information as:
976 07@00032473,0016,00,1877 example.com
978 Which would signify that this is the 1,877th message from the
979 peering partner example.com. Note that the previous two
980 examples showing an optionally logged Vendor-specified SIP
981 element use a Vendor-ID with a Private Enterprise Number of
982 32473. This value has been reserved by IANA to be used as an
983 example PEN in documentation according to [RFC5612].
985 5. Example SIP CLF Record
987 The following SIP message is an INVITE request sent by a SIP client:
989 INVITE sip:192.0.2.10 SIP/2.0
990 To:
991 Call-ID: DL70dff590c1-1079051554@example.com
992
993 From: "Alice" ;
994 tag=DL88360fa5fc;epid=0x34619b0
995
996 CSeq: 1 INVITE
997 Max-Forwards: 70
998 Date: Thu, 21 Feb 2012 15:02:03 GMT
999
1000 Via: SIP/2.0/TCP 192.0.2.200:5060;
1001 branch=z9hG4bK-1f6be070c4-DL
1002
1003 Contact: "1001"
1004 Content-Type: application/sdp
1005 Content-Length: 418
1007 v=0
1008 o=1001 1456139204 0 IN IP4 192.0.2.200
1009 s=Session SDP
1010 c=IN IP4 192.0.2.200
1011 b=AS:2048
1012 t=0 0
1013 m=audio 13756 RTP/AVP 0 101
1014 a=rtpmap:0 PCMU/8000
1016 Shown below is approximately how this message would appear as a
1017 single record in a SIP CLF logging file if encoded according to the
1018 syntax described in this document. Due to RFC conventions, this log
1019 entry has been split into five lines, instead of the two lines that
1020 actually appear in a log file; and the tab characters have been
1021 padded out using spaces to simulate their appearance in a text
1022 terminal.
1024 A000100,0053005C005E006D007D008F009E00A000BA00C700EB00F70100
1025
1026 1328821153.010 RORUU 1 INVITE - sip:192.0.2.10
1027 192.0.2.10:5060 192.0.2.200:56485 sip:192.0.2.10 -
1028 sip:1001@example.com:5060 DL88360fa5fc
1029 DL70dff590c1-1079051554@example.com S1781761-88 C67651-11
1030
1032 A bit-exact version of the actual log entry is provided here, Base64
1033 encoded.
1035 begin-base64 644 clf_record
1036 QTAwMDEwMCwwMDUzMDA1QzAwNUUwMDZEMDA3RDAwOEYwMDlFMDBBMDAwQkEwMEM3MDBF
1037 QjAwRjcwMTAwCjEzMjg4MjExNTMuMDEwCVJPUlVVCTEgSU5WSVRFCS0Jc2lwOjE5Mi4w
1038 LjIuMTAJMTkyLjAuMi4xMDo1MDYwCTE5Mi4wLjIuMjAwOjU2NDg1CXNpcDoxOTIuMC4y
1039 LjEwCS0Jc2lwOjEwMDFAZXhhbXBsZS5jb206NTA2MAlETDg4MzYwZmE1ZmMJREw3MGRm
1040 ZjU5MGMxLTEwNzkwNTE1NTRAZXhhbXBsZS5jb20JUzE3ODE3NjEtODgJQzY3NjUxLTEx
1041 Cg==
1042 ====
1044 To recover the unencoded file, the Base64 text above may be passed as
1045 input to the following perl script (the output should be redirected
1046 to a file).
1048
1050 #!/usr/bin/perl
1051 use strict;
1052 my $bdata = "";
1053 use MIME::Base64;
1054 while(<>)
1055 {
1056 if (/begin-base64 644 clf_record/ .. /-- ==== --/)
1057 {
1058 if ( m/^\s*[^\s]+\s*$/)
1059 {
1060 $bdata = $bdata . $_;
1061 }
1062 }
1063 }
1064 print decode_base64($bdata);
1066
1068 6. Text Tool Considerations
1070 This format has been designed to allow text tools to easily process
1071 logs without needing to understand the indexing format. Index lines
1072 may be rapidly discarded by checking the first character of the line:
1073 index lines will always start with an alphabetical character, while
1074 field lines will start with a numerical character.
1076 Within a field line, script tools can quickly split fields at the tab
1077 characters. The first 12 fields are positional, and the meaning of
1078 any subsequent fields can be determined by checking the first four
1079 characters of the field. Alternately, these non-positional fields
1080 can be located using a regular expression. For example, the "Contact
1081 value" in a request can be found by searching for the perl regex
1082 /\t0000,....,([^\t]*)/.
1084 7. Security Considerations
1086 This document does not introduce any new security considerations
1087 beyond those discussed in [I-D.ietf-sipclf-problem-statement].
1089 In the interest of protecting the sensitive information contained in
1090 a SIP CLF file, [I-D.ietf-sipclf-problem-statement] notes that values
1091 might need to be obfuscated for privacy reasons when SIP CLF files
1092 are exchanged between domains. If a base64 encoded string contains
1093 the non-obfuscated value then that would also need to be obfuscated
1094 before base64 encoding.
1096 8. Operational Guidance
1098 SIP CLF log files will take up substantive amount of disk space
1099 depending on traffic volume at a processing entity and the amount of
1100 information being logged. As such, any enterprise using SIP CLF
1101 should establish operational procedures for file rollovers as
1102 appropriate to the needs of the organization.
1104 Listing such operational guidelines in this document is out of scope
1105 for this work.
1107 9. IANA Considerations
1109 This specification establishes a new Session Initiation Protocol
1110 (SIP) Common Log Format (CLF) Parameters registry, which contains two
1111 new sub-registries for SIP CLF Version and SIP CLF Transport Flag.
1112 Initial entries are defined by this specification for both sub-
1113 registries. Addition of any new sub-registry to the Session
1114 Initiation Protocol (SIP) Common Log Format (CLF) Parameters registry
1115 is to be done using the IETF Review registration policy detailed in
1116 [RFC5226].
1118 9.1. SIP CLF Version
1120 This document defines the SIP CLF "Version" field in Section 4.1.
1121 IANA has created a registry of Version values entitled "SIP CLF
1122 Version Values". Version numbers MUST be incremented for any new SIP
1123 CLF protocol specification that changes any part of the SIP CLF
1124 record format. Changes include addition or removal of fields or a
1125 change of syntax or semantics of existing fields.
1127 Version numbers must be registered via the Standards Action method as
1128 described in [RFC5226]. IANA has registered the Versions shown in
1129 Table 1 below.
1131 +---------+--------------------+-----------+
1132 | Version | FORMAT | Reference |
1133 +---------+--------------------+-----------+
1134 | 0x41 | Defined in RFCXXXX | RFCXXXX |
1135 +---------+--------------------+-----------+
1137 Table 1: IANA-Registered SIP CLF Versions
1139 [[NOTE TO RFC EDITOR: Please change XXXX to the number assigned to
1140 this specification, and remove this paragraph on publication.]]
1142 9.2. SIP CLF Transport Flag
1144 This document defines the SIP CLF "Transport Flag" as fourth byte in
1145 the Flags Field of the SIP CLF record. The format and values of the
1146 Transport Flag are described in Section 4.2. IANA has created a
1147 registry of SIP CLF Transport Flag values entitled "SIP CLF Transport
1148 Flag Values".
1150 SIP CLF Transport Flag values must be registered via the IETF Review
1151 method as described in [RFC5226]. IANA has registered the Transport
1152 Flag values shown in Table 2 below.
1154 +-------+--------------------+-----------+
1155 | Value | Transport Protocol | Reference |
1156 +-------+--------------------+-----------+
1157 | U | UDP | RFCXXXX |
1158 | T | TCP | RFCXXXX |
1159 | S | SCTP | RFCXXXX |
1160 +-------+--------------------+-----------+
1162 Table 2: IANA-Registered SIP CLF Transport Flag
1164 [[NOTE TO RFC EDITOR: Please change XXXX to the number assigned to
1165 this specification, and remove this paragraph on publication.]]
1167 10. Acknowledgements
1169 The authors of this document would like to acknowledge and thank
1170 Peter Musgrave (the chair of the SIPCLF working group) and Robert
1171 Sparks (the assigned area director) for their support, guidance, and
1172 continued invaluable feedback.
1174 This work benefited from the discussions and invaluable input by the
1175 various members of the SIPCLF working group. These include Brian
1176 Trammell, Eric Burger, Cullen Jennings, Benoit Claise, Saverio
1177 Niccolini, Dan Burnett. Special thanks to Hadriel Kaplan, Chris
1178 Lonvick, Paul E. Jones, John Elwell, Claudio Allocchio, and Joe
1179 Clarke for their constructive comments, suggestions, and reviews that
1180 were critical to the formulation and refinement of this document.
1182 Thanks to Anders Nygren for his early implementation, insight, and
1183 reviews of the SIP CLF format.
1185 This document was written with the xml2rfc tool described in
1186 [RFC2629].
1188 11. References
1190 11.1. Normative References
1192 [I-D.ietf-sipclf-problem-statement]
1193 Gurbani, V., Burger, E., Anjali, T., Abdelnur, H., and O.
1194 Festor, "The Common Log Format (CLF) for the Session
1195 Initiation Protocol (SIP): Framework and Data Model",
1196 draft-ietf-sipclf-problem-statement-11 (work in progress),
1197 March 2012.
1199 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1200 Requirement Levels", BCP 14, RFC 2119, March 1997.
1202 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
1203 A., Peterson, J., Sparks, R., Handley, M., and E.
1204 Schooler, "SIP: Session Initiation Protocol", RFC 3261,
1205 June 2002.
1207 11.2. Informative References
1209 [PEN] IANA, "Private Enterprise Numbers",
1210 http://www.iana.org/assignments/enterprise-numbers , 2009.
1212 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet
1213 numbers", RFC 1166, July 1990.
1215 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
1216 June 1999.
1218 [RFC4475] Sparks, R., Hawrylyshen, A., Johnston, A., Rosenberg, J.,
1219 and H. Schulzrinne, "Session Initiation Protocol (SIP)
1220 Torture Test Messages", RFC 4475, May 2006.
1222 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
1223 IANA Considerations Section in RFCs", BCP 26, RFC 5226,
1224 May 2008.
1226 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009.
1228 [RFC5612] Eronen, P. and D. Harrington, "Enterprise Number for
1229 Documentation Use", RFC 5612, August 2009.
1231 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks
1232 Reserved for Documentation", RFC 5737, January 2010.
1234 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
1235 Address Text Representation", RFC 5952, August 2010.
1237 [UNICODE] "The Unicode Consortium, The Unicode Standard, Version
1238 6.2.0, (Mountain View, CA: ISBN 978-1-936213-07-8)",
1239 http://www.unicode.org/versions/Unicode6.2.0/ , 2012.
1241 [W3C.REC-xml-20081126]
1242 Sperberg-McQueen, C., Yergeau, F., Maler, E., Paoli, J.,
1243 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
1244 Edition)", World Wide Web Consortium Recommendation REC-
1245 xml-20081126, November 2008,
1246 .
1248 Authors' Addresses
1250 Gonzalo Salgueiro
1251 Cisco Systems
1252 7200-12 Kit Creek Road
1253 Research Triangle Park, NC 27709
1254 US
1256 Email: gsalguei@cisco.com
1258 Vijay Gurbani
1259 Bell Labs, Alcatel-Lucent
1260 1960 Lucent Lane
1261 Rm 9C-533
1262 Naperville, IL 60563
1263 US
1265 Email: vkg@bell-labs.com
1267 Adam Roach
1268 Tekelec
1269 17210 Campbell Rd.
1270 Suite 250
1271 Dallas, TX 75252
1272 US
1274 Email: adam@nostrum.com