idnits 2.17.1 draft-dawes-insipid-logme-marking-00.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 : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 5 characters in excess of 72. == There are 3 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 326 has weird spacing: '...orp.com p1.fo...' == Line 357 has weird spacing: '...orp.com r1.ba...' == Line 454 has weird spacing: '...orp.com p1.fo...' -- The document date (July 21, 2014) is 3564 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) == Missing Reference: 'RFCXXXX' is mentioned on line 524, but not defined == Outdated reference: A later version (-27) exists of draft-ietf-insipid-session-id-06 Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force P. Dawes 3 Internet-Draft Vodafone Group 4 Intended status: Standards Track July 21, 2014 5 Expires: January 22, 2015 7 Marking SIP Messages to be Logged 8 draft-dawes-insipid-logme-marking-00 10 Abstract 12 SIP networks use signalling monitoring tools to diagnose user 13 reported problems and for regression testing if network or user agent 14 software is upgraded. As networks grow and become interconnected, 15 including connection via transit networks, it becomes impractical to 16 predict the path that SIP signalling will take between user agents, 17 and therefore impractical to monitor SIP signalling end-to-end. 19 This document describes an indicator for the SIP protocol which can 20 be used to mark signalling as of interest to logging. Such marking 21 will typically be applied as part of network testing controlled by 22 the network operator and not used in regular user agent signalling. 23 However, such marking can be carried end-to-end including the SIP 24 user agents, even if a session originates and terminates in different 25 networks. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on January 22, 2015. 44 Copyright Notice 46 Copyright (c) 2014 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 63 3. Motivating Scenario . . . . . . . . . . . . . . . . . . . . . 3 64 4. Skeleton Diagnostic Procedure . . . . . . . . . . . . . . . . 4 65 5. Protocol for Log-Me Marking . . . . . . . . . . . . . . . . . 5 66 5.1. Configuration for Log-Me Marking . . . . . . . . . . . . 5 67 5.2. Starting and Stopping Log-Me Marking . . . . . . . . . . 5 68 5.3. End Points of Log-Me Marking . . . . . . . . . . . . . . 6 69 5.3.1. Originating and Terminating User Agent . . . . . . . 6 70 5.3.2. Originating Edge Proxy and Terminating Edge Proxy . . 7 71 5.4. Maintaining State . . . . . . . . . . . . . . . . . . . . 7 72 5.5. Missing Log-me Marker in Dialog Being Logged . . . . . . 9 73 5.6. Logging Multiple Simultaneous Dialogs . . . . . . . . . . 10 74 5.7. Forked Requests and Back to Back User Agents . . . . . . 10 75 5.7.1. Propagating the Log-me Marker in Forked Requests . . 10 76 5.7.2. B2BUA Processing of Log-Me Marker . . . . . . . . . . 10 77 5.8. 'Log-Me' Marker . . . . . . . . . . . . . . . . . . . . . 10 78 5.8.1. Header Field Parameter for Session-ID . . . . . . . . 10 79 5.8.2. Identifying Test Cases . . . . . . . . . . . . . . . 11 80 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 81 6.1. Trust Domain . . . . . . . . . . . . . . . . . . . . . . 11 82 6.2. Security Threats . . . . . . . . . . . . . . . . . . . . 11 83 6.2.1. The Log-Me Marker . . . . . . . . . . . . . . . . . . 11 84 6.2.2. Activating Debug . . . . . . . . . . . . . . . . . . 11 85 6.3. Protecting Logs . . . . . . . . . . . . . . . . . . . . . 12 86 7. Augmented BNF for the "debug" Parameter . . . . . . . . . . . 12 87 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 88 8.1. Registration of the "debug" Parameter . . . . . . . . . . 12 89 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 90 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 91 9.2. Informative References . . . . . . . . . . . . . . . . . 13 92 Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 13 93 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 95 1. Introduction 97 If users experience problems with setting up sessions using SIP, 98 their service provider needs to find out why by examining the SIP 99 signalling. Also, if network or user agent software or hardware is 100 upgraded regression testing is needed. Such diagnostics apply to a 101 small proportion of network traffic and can apply end-to-end, even if 102 signalling crosses several networks possibly belonging to several 103 different network operators. It may not be possible to predict the 104 path through those networks in advance, therefore a mechanism is 105 needed to mark a session as being of interest so that SIP entities 106 along the signalling path can provide diagnostic logging. This 107 document describes a solution that meets the requirements for such a 108 'log me' marker for SIP signalling as defined in draft-insipid-logme- 109 reqs [I-D.dawes-insipid-logme-reqs]. 111 2. Requirements Language 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in RFC 2119 [RFC2119]. 117 3. Motivating Scenario 119 Signalling for SIP session setup can cross several networks, and 120 these networks may not have common ownership and also may be in 121 differrent countries. If a single operator wishes to perform 122 regression testing or fault diagnosis end-to-end, the separate 123 ownership of networks that carry the signalling and the explosion in 124 the number of possible signalling paths through SIP entities from the 125 originating to the terminating user make it impractical to pre- 126 configure logging of an end-to-end SIP signalling of a session of 127 interest. 129 The figure below shows an example of a signalling path through 130 multiple networks. 132 +------------------+ +------------------+ 133 | COUNTRY A | | COUNTRY B | 134 | Operator A | | Operator A | 135 | | | | 136 | SIP Phones | | SIP Phones | 137 | | //| | 138 +------------------+ // +------------------+ 139 | // 140 | // 141 ,'```', // +------------------+ 142 .`',.' `..'``',<==// | COUNTRY B | 143 ,' Operator A `', | Operator A | 144 ; Backbone Network ..'-------| | 145 ', ,., .'` | PSTN phones | 146 '.,.`'.,,,.` `''` | | 147 || +------------------+ 148 || 149 \/ 150 +------------------+ 151 | | 152 | Transit Network | 153 | | 154 | |\\ 155 +------------------+ \\ 156 | \\ 157 | \\ 158 +------------------+ \\ +------------------+ 159 | COUNTRY D | \\ | COUNTRY C | 160 | Operator C | \\=>| Operator B | 161 | | | | 162 | SIP Phones | | SIP Phones | 163 | | | | 164 +------------------+ +------------------+ 166 Figure 1: Example signalling path through multiple networks 168 4. Skeleton Diagnostic Procedure 170 The skeleton diagnostic procedure is as follows: 172 o The user's user agent is placed in debug mode. The user agent 173 logs its own signalling and inserts a log me marker into SIP 174 requests for session setup 176 o All SIP entities that the signalling traverses, from the first 177 proxy the user agent connects to at the edge of the network to the 178 destination user agent, can detect that the log me marker is 179 present and can log SIP requests and responses that contain the 180 marker if configured to do so. 182 o Subsequent responses and requests in the same dialog are logged. 184 o Logging stops, either because the dialog has ended or because a 185 'stop event', typically expiry of a certain amount of time, 186 occurred 188 o The user's user agent and any other SIP entity that has logged 189 signalling sends logs to a server that is co-ordinating 190 diagnostics. 192 5. Protocol for Log-Me Marking 194 This clause describes the protocol solution to the log-me 195 requirements described in draft-dawes-insipid-logme-reqs 196 [I-D.dawes-insipid-logme-reqs]. 198 5.1. Configuration for Log-Me Marking 200 Configuration of a user agent or proxy to perform log-me marking can 201 be done in any way that is convenient to the configured entity. For 202 example, an XML file might be used to list conditions for starting 203 and stopping based on time. 205 09:00:00 206 09:10:00 208 Figure 2: Simple example log-me configuration 210 Logging is on a per-dialog basis and individual logs are 211 differentiated by their test identifier, which is defined in 212 Section 5.8.2 of this document. Therefore, an individual log for an 213 individual dialog is closed when that dialog ends. Logging is 214 typically done separately from regualar operation, which means that 215 tests can be designed to be short enough to troubleshoot quickly and 216 to limit the size of individual logs. If logging is configured so 217 that everything is logged for a specified number of minutes then 218 several separate dialogs might start and finish meaning that several 219 logs may be generated, each one distinguished by its test identifier. 221 5.2. Starting and Stopping Log-Me Marking 223 A proxy or user agent needs to determine when it needs to log-me mark 224 a SIP request or response. A user agent or proxy log-me marks a 225 request or response for two reasons: either it is configured to do so 226 or it has detected that a dialog is being log-me marked and maintains 227 state to ensure that all requests and responses in the dialog are 228 log-me marked. A regression test might be configured to log-me mark 229 all SIP dialogs created during a given time period whereas a 230 troubleshooting test might be configured to mark a dialog based on 231 criteria specific to a reported fault. When configuration has caused 232 a user agent or proxy to start log-me marking requests and responses, 233 marking continues until the dialog ends. 235 5.3. End Points of Log-Me Marking 237 Log-me marking is initiated on a dialog creating side controlled by 238 configuration. The dialog terminating side detects an incoming log- 239 me marker and reacts accordingly. 241 5.3.1. Originating and Terminating User Agent 243 In the simplest case, an originating user agent will insert a log-me 244 marker in the dialog-creating SIP request and all subsequent SIP 245 requests within that dialog. The log-me marker is carried to the 246 terminating user agent and the terminating user agent echoes the log- 247 me marker in responses. If the terminating user agent sends an in- 248 dialog request on a dialog that is being log-me marked, it inserts a 249 log-me marker and the originating user agent echoes the log-me marker 250 in responses. This basic case suggests the following principles: 252 o The originating user agent is configured for debug 254 o The terminating user agent is not configured for debug and cannot 255 initiate log-me marking. 257 o The originating user agent logs its own signalling and inserts a 258 log me marker into the dialog-creating SIP request and subsequent 259 in-dialog SIP requests. 261 o The terminating user agent can detect that a dialog is of interest 262 to logging by the existence of a log-me marker in an incoming 263 dialog-creating SIP request. 265 o The terminating user agent MUST echo a log-me marker in responses 266 to a SIP request that included a log-me marker. 268 o If the terminating user agent has detected that a dialog is being 269 log-me marked, it inserts a log-me marker in any in-dialog SIP 270 requests that it sends. 272 5.3.2. Originating Edge Proxy and Terminating Edge Proxy 274 Some user agents might not support log-me marking. In order to test 275 sessions involving such user agents, the log-me marker is inserted by 276 edge proxies on the originating and terminating sides. The log-me 277 marker is carried to the terminating user agent but the terminating 278 user agent is not able to echo the log-me marker in responses to that 279 request. Therefore the terminating edge proxy inserts a log-me 280 marker in reponses to the request. Likewise, if the terminating user 281 agent sends an in-dialog request, the terminating edge proxy inserts 282 a log-me marker and the originating edge proxy echoes the log-me 283 marker in responses to that request. This case suggests the 284 following principles: 286 o The originating edge proxy is configured for debug. 288 o The terminating edge proxy is not configured for debug and cannot 289 initiate log-me marking. 291 o The originating edge proxy logs its own signalling and inserts a 292 log me marker into SIP requests for session setup. 294 o The terminating edge proxy can detect that a dialog is of interest 295 to logging by the existence of a log-me marker in an incoming SIP 296 request. 298 o The terminating edge proxy MUST echo a log-me marker in responses 299 to a SIP request that included a log-me marker. 301 o If the terminating edge proxy has detected that a dialog is being 302 log-me marked, it inserts a log-me marker in in-dialog SIP 303 requests from the terminating user agent. 305 o The originating edge proxy echoes the log-me marker in responses 306 to in-dialog requests received from the terminating side. 308 5.4. Maintaining State 310 If a proxy inserts a log-me marker in a SIP request (because a user 311 agent did not) then it must ensure that a log-me marker is also 312 inserted in responses to that request. A proxy on the terminating 313 side that receives a SIP reqeust with a log-me marker may also ensure 314 that responses to that requset contain a log-me marker by inserting 315 one if the terminating user agent did not. Entities that perform 316 this log-me marking or checking must maintain a record of which 317 dialogs are being log-me marked. 319 In the figure below, the edge proxy in the originating network 320 maintains state to ensure log-me marking of SIP requests and in the 321 terminating network the registrar maintains state to ensure log-me 322 marking of SIP responses. Such behaviour is useful for logging if 323 end devices do not insert or echo a log-me marker. 325 Alice Proxy Registrar 326 u1.foocorp.com p1.foocorp.com r1.foocorp.com 327 | | | 328 |(1) INVITE | | 329 | (u1 does not insert log-me marker in SIP request) 330 |----------------->| | 331 | |(2) INVITE | 332 | | 'log-me' marker 333 | | (p1 inserts log-me marker. p1 maintains 334 | | state and inserts log-me marker in all 335 | | requests on this dialog) 336 | |----------------->| 337 | | |(3) INVITE 338 | | | 'log-me' marker 339 | | |--------> (to barcorp) 340 | | | 341 | | | 342 | | | 343 | | |(8) 200 OK 344 | | | 'log-me' marker 345 | |(9) 200 OK |<-------- (from barcorp) 346 | | 'log-me' marker 347 | |<-----------------| 348 |(10) 200 OK | | 349 | 'log-me' marker | 350 |<-----------------| | 351 | | | 352 |(11) ACK | | 353 |---------------------------------------------------------> 354 | | | 356 Proxy Registrar Bob 357 p1.barcorp.com r1.barcorp.com u1.barcorp.com 358 | | | 359 (3) INVITE | | 360 'log-me' marker | | 361 ----->|(from foocorp) | | 362 | | | 363 |(4) INVITE | | 364 | 'log-me' marker | 365 |----------------->| | 366 | |(r1 detects that this dialog is 367 | | being log-me marked) 368 | | | 369 | | | 370 | |(5) INVITE | 371 | 'log-me' marker 372 | |----------------->| 373 | | | 374 | |(6) 200 OK | 375 | | (u1 does not echo LogMe: 376 | | to SIP response)| 377 | |<-----------------| 378 |(7) 200 OK | | 379 |'log-me' marker | | 380 | (r1 inserts log-me marker. r1 maintains 381 | state and inserts log-me marker in all 382 | responses on this dialog) 383 |<-----------------| | 384 | | | 385 (8) 200 OK | | 386 'log-me' marker | | 387 <----| | | 388 | | | 389 (11) ACK | | 390 from foocorp) -------------------------->| 391 | | | 392 | | | 393 | |(12) re-INVITE | 394 | |<-----------------| 395 | |(in-dialog request) 396 | | | 397 |(13) re-INVITE | | 398 |'log-me' marker | | 399 |<-----------------| | 400 |(r1 inserts log-me marker into in-dialog 401 | requests sent from the terminating user agent) 402 | | | 404 Figure 3: Maintaining state for log-me marking 406 5.5. Missing Log-me Marker in Dialog Being Logged 408 A terminating user agent or terminating edge proxy that has been 409 echoing markers in responses for a given dialog might receive a SIP 410 request that has not been log-me marked. Since log-me marking is 411 done per dialog, this is an error. In such cases, the proxy SHOULD 412 consider log-me marking to have ended and MUST NOT mark a response to 413 the unmarked request, responses to subsequent requests in the dialog, 414 or in-dialog requests sent from the terminating side. Similarly, 415 log-me marking that begins mid-dialog is an error case and the 416 terminating user agent or edge proxy MUST NOT log-me mark responses 417 to the marked request, responses to subsequent requests in the 418 dialog, or in-dialog requests from the terminating side. 420 5.6. Logging Multiple Simultaneous Dialogs 422 An originating or terminating user agent and SIP entities on the 423 signaling path can log multiple SIP dialogs simultaneously, these 424 dialogs are differentiated by their test identifier. 426 5.7. Forked Requests and Back to Back User Agents 428 5.7.1. Propagating the Log-me Marker in Forked Requests 430 Log-me marking is copied into forked requests. 432 5.7.2. B2BUA Processing of Log-Me Marker 434 A B2BUA SHOULD act on the terminating side as described for a 435 terminating user agent and therefore log marked incoming requests, 436 echo log-me marking in responses to log-me marked requests, and log- 437 me mark in-dialog SIP requests that it sends if the dialog is being 438 log-me marked. 440 A B2BUA SHOULD act on the originating side as described for an 441 originating user agent and therefore mark SIP requests if and only if 442 configured to do so, and echo log-me marking in responses to in- 443 dialog requests received from the terminating side. 445 5.8. 'Log-Me' Marker 447 5.8.1. Header Field Parameter for Session-ID 449 A new header field parameter called debug is defined to be used with 450 the Session-ID header field (described in draft-ietf-insipid-session- 451 id [I-D.ietf-insipid-session-id]). 453 Alice Proxy Registrar Debug Server 454 u1.foocorp.com p1.foocorp.com r1.foocorp.com d1.foocorp.com 455 | | | | 456 |(1) INVITE | | | 457 | Session-ID: ab30317f1a784dc48ff824d0d3715d86; | 458 | remote=47755a9de7794ba387653f2099600ef2; debug 459 |----------------->| | | 460 | | | | 462 Figure 4: Log-me marking using the "debug" Session-ID: header field 463 parameter 465 5.8.2. Identifying Test Cases 467 The test case identifier is the Session-ID in the Session-ID header 468 field (described in draft-ietf-insipid-session-id 469 [I-D.ietf-insipid-session-id]). A log relates to exactly one dialog 470 and logs are distinguished by their test case identifier. 472 6. Security Considerations 474 6.1. Trust Domain 476 Since a log me marker may cause a SIP entity to log the SIP header 477 and body of a request or response, the log me marker SHOULD be 478 removed at a trust domain boundary. If a prior agreement to log 479 sessions exists with the net hop network then the log me marker might 480 not be removed. 482 6.2. Security Threats 484 6.2.1. The Log-Me Marker 486 The log me marker is not sensitive information, although it will 487 sometimes be inserted because a particular device is experiencing 488 problems. 490 The presence of a log me marker will cause some SIP entities to log 491 signalling. Therefore, this marker MUST be removed at the earliest 492 opportunity if it has been incorrectly inserted. 494 6.2.2. Activating Debug 496 Activating a debug mode affects the operation of a user agent, 497 therefore it MUST be supplied by an authorized server to an 498 authorized user agent, it MUST NOT be altered in transit, and it MUST 499 NOT be readable by an unauthorized third party. 501 6.3. Protecting Logs 503 A SIP entity that has logged information SHOULD encrypt it, such that 504 it can be decrypted only by a person authorized to examine the logged 505 information. 507 7. Augmented BNF for the "debug" Parameter 509 ABNF is described in RFC 5234 [RFC5234] 511 debug-param = "debug" 513 8. IANA Considerations 515 8.1. Registration of the "debug" Parameter 517 The following parameter is to be added to the "Header Field 518 Parameters and Parameter Values" section of the SIP parameter 519 registry: 521 +--------------+----------------+-------------------+-----------+ 522 | Header Field | Parameter Name | Predefined Values | Reference | 523 +--------------+----------------+-------------------+-----------+ 524 | Session-ID | debug | No | [RFCXXXX] | 525 +--------------+----------------+-------------------+-----------+ 527 Table 1 529 9. References 531 9.1. Normative References 533 [I-D.dawes-insipid-logme-reqs] 534 Dawes, P., "Requirements for Marking SIP Messages to be 535 Logged", draft-dawes-insipid-logme-reqs-00 (work in 536 progress), January 2014. 538 [I-D.ietf-insipid-session-id] 539 Jones, P., Pearce, C., Polk, J., and G. Salgueiro, "End- 540 to-End Session Identification in IP-Based Multimedia 541 Communication Networks", draft-ietf-insipid-session-id-06 542 (work in progress), April 2014. 544 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 545 Requirement Levels", BCP 14, RFC 2119, March 1997. 547 9.2. Informative References 549 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 550 Specifications: ABNF", STD 68, RFC 5234, January 2008. 552 Appendix A. Additional Stuff 554 This becomes an Appendix. 556 Author's Address 558 Peter Dawes 559 Vodafone Group 560 The Connection 561 Newbury, Berkshire RG14 2FN 562 UK 564 Email: peter.dawes@vodafone.com