Internet Engineering Task Force P. Dawes Internet-Draft Vodafone Group Intended status: Standards Track July 13, 2009 Expires: January 14, 2010 Private Extension to the Session Initiation Protocol (SIP) for Debugging draft-dawes-sipping-debug-01 Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 14, 2010. Copyright Notice Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Abstract Networks that use SIP to start and stop sessions between their users will frequently be upgraded with software and hardware changes. Users will similarly frequently change their client software and the Dawes Expires January 14, 2010 [Page 1] Internet-Draft P-Debug-ID July 2009 way they use the network. In order to allow troubleshooting and regression testing, it is useful to provide debugging as part of the network fabric. This draft describes an event package that provides debugging configuration to SIP entities and a SIP private header that triggers logging of SIP signalling and identifies logs at mulitiple SIP entities as belonging to a single end-to-end session. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 3. Motivating Scenario . . . . . . . . . . . . . . . . . . . . . 3 4. Signalling for Example Scenario . . . . . . . . . . . . . . . 4 4.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 4 4.2. Originating Session . . . . . . . . . . . . . . . . . . . 4 4.3. Terminating Sessions . . . . . . . . . . . . . . . . . . . 8 5. Avoiding Configuring all Entities on the Signalling Path . . . 9 5.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.2. Originating Sessions . . . . . . . . . . . . . . . . . . . 10 5.3. Terminating Sessions . . . . . . . . . . . . . . . . . . . 10 6. Multiple Simultaneous Events . . . . . . . . . . . . . . . . . 10 7. P-Debug-ID in SIP Requests . . . . . . . . . . . . . . . . . . 12 7.1. Forked Requests . . . . . . . . . . . . . . . . . . . . . 12 7.2. Back-to-Back User Agents . . . . . . . . . . . . . . . . . 12 8. P-Debug-ID in SIP Responses . . . . . . . . . . . . . . . . . 12 9. Multiple Service Providers . . . . . . . . . . . . . . . . . . 12 9.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 12 10. Configuration for Multiple AORs . . . . . . . . . . . . . . . 12 11. Retrieving Debugging Logs . . . . . . . . . . . . . . . . . . 13 12. Security Considerations . . . . . . . . . . . . . . . . . . . 13 12.1. Trust Domain . . . . . . . . . . . . . . . . . . . . . . . 13 12.2. Security Threats . . . . . . . . . . . . . . . . . . . . . 13 12.3. Security Mechanisms . . . . . . . . . . . . . . . . . . . 14 13. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14 13.1. P-Debug-ID header syntax . . . . . . . . . . . . . . . . . 14 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 14.1. Normative References . . . . . . . . . . . . . . . . . . . 14 14.2. Informative References . . . . . . . . . . . . . . . . . . 14 Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 Dawes Expires January 14, 2010 [Page 2] Internet-Draft P-Debug-ID July 2009 1. Introduction If users experience problems with setting up sessions using SIP, their service provider needs to find out why by examining the SIP signalling. This draft defines an event package to configure SIP entities with conditions for starting and stopping logging of SIP signalling a SIP header field that allows a service provider to link signalling logged at various SIP entities in order to troubleshoot session setup. The skeleton of the debugging procedure is as follows: o The user's terminal is prompted to enrol to debug configuration, supplied from a debug event package o The first proxy the terminal connects to, at the edge of the network, either is already primed to log any signalling that is identified for debug, because it is permanenently enrolled to receive debug configuration for all users, or is prompted to enrol in the same way as the terminal. o The user's terminal receives configuration that indicates to the terminal when it should start and stop logging signalling o When user's terminal sends a SIP request that matches the pre- configured criteria for logging, logging starts at the user's terminal, the first proxy the terminal connects to, and any other SIP entity within the trust domain that receives the request. o Subsequent responses and requests in the same dialog are logged. o Logging stops, either because the dialog has ended or because a 'stop' event, defined in the debug configuration, occurred o The user's terminal, the proxy, and any other SIP entity that has logged signalling sends its logs to the debug server 2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 3. Motivating Scenario Alice has a SIP client on her laptop, which she has been using for Dawes Expires January 14, 2010 [Page 3] Internet-Draft P-Debug-ID July 2009 some time to make video calls to work colleagues inside her company, FooCorp, including making video calls and sending pager-mode messages. Last week, her company became able to contact staff working for its principal customer BarCorp, which recently installed a SIP-based network. Today, she tried to set up a call to Bob at BarCorp who uses an audio-only SIP phone, but the call failed and Alice does not know why. Also, she tried sending an instant message to her friend Carol, also working at BarCorp, and her terminal displayed 'message failed'. She contacts those who manage the SIP network within FooCorp to ask them to investigate the problem. This draft discusses the properties of a solution for debugging such a scenario, and outlines one possible solution. 4. Signalling for Example Scenario 4.1. General The network administrators at FooCorp are first interested in whether the problem is within FooCorp or BarCorp. They would like to log the SIP signalling from Alice's client to the edge of the FooCorp network. In order to do this, Alice's client, the SIP entity at the border between FooCorp and BarCorp, and all of the SIP entities in between must log signalling for both the audio call and the instant message. The network administrators can then examine the logs to determine the cause of the problem. 4.2. Originating Session The first step is to provide Alice's SIP client with configuration information that instructs the SIP client when to log SIP signalling. All debug configuration information at FooCorp is hosted on a single logical debug server, debug.foocorp.com, which hosts an event package that provides configuration using SUBSCRIBE and NOTIFY methods. Usually, SIP clients are not subscribed to this event package, since debugging is rarely used. Because debugging is rare, the debug event package should only be subscribed to when required, which is achieved by triggering subscription when Alice refreshes her registration. The administrators cause Alice to re-register by notifying her UA that its subscription has expired. When Alice's UA re-registers, an empty P-Debug-ID header field is included in the 200 OK response to the REGISTER request. This empty P-Debug-ID header field causes Alice's UA to subscribe to Alice's debug event package at the debug server, which returns an XML document containing her debugging configuration. Dawes Expires January 14, 2010 [Page 4] Internet-Draft P-Debug-ID July 2009 Alice Proxy Registrar Debug Server u1.foocorp.com p1.foocorp.com r1.foocorp.com d1.foocorp.com | | | | | | | | |(1) NOTIFY (Alice's registration terminated) | | Event: reg | | | |<-------------------------------------------------------| | | | | |(2) REGISTER (Alice re-registers) | | |----------------->| | | | |(3) REGISTER | | | |----------------->| | | | | | | |(4) 200 OK | | | | P-Debug-ID: | | | |<-----------------| | |(5) 200 OK | | | | P-Debug-ID: | | | |<-----------------| | | | | | | |(6) ACK | | | |------------------------------------>| | | | | | |(7) SUBSCRIBE | | | | Event: debug | | | |------------------------------------------------------->| |(8) 200 OK | | | |<-------------------------------------------------------| | | | | |(9) NOTIFY (debug configuration in body) | |<-------------------------------------------------------| |(10)200 OK | | | |------------------------------------------------------->| | | | | Figure 1: Prompting Client to Retrieve Debugging Configuration The XML document returned to Alice's terminal contains the debugging configuration shown below. This configuration instructs the terminal when to start logging, when to stop, and a value to put in the inserted P-Debug-ID header field. Dawes Expires January 14, 2010 [Page 5] Internet-Draft P-Debug-ID July 2009 bob@barcorp.com T0H2M0S 1A346D Figure 2: Minimal Debugging Configuration for UA The start-trigger element instructs Alice's terminal to begin to log signalling for any SIP request that contains bob@barcorp.com in the To: header field. The stop-trigger element instructs Alice's terminal end logging signalling after a time period of two minutes. Alice's terminal inserts a P-Debug-ID header field in all logged SIP requests, and the debug-control element contains the value that Alice's terminal will include in the P-Debug-ID header field. Proxy p1.foocorp.com is supplied with similar configuration, shown below, with one important difference, that the value in the P-Debug-ID header field is part of the start trigger, thereby ensuring that the session from Alice is logged, not simply any request sent to Bob. bob@barcorp.com 1A346D T0H2M0S Figure 3: Minimal Debugging Configuration for Proxy For all entities, debug configuration is used for a single dialog and then discarded, which means that once Alice's UA has started the dialog with Bob, the debug configuration shown above is not re-used for any subsequent dialogs. The scope of logging is the dialog for which logging started, logging is not done of any other dialog that was in progress or is started while logging the dialog with Bob. The FooCorp network is organized such that all SIP clients route requests through the first SIP proxy they connect to, and their Dawes Expires January 14, 2010 [Page 6] Internet-Draft P-Debug-ID July 2009 registrar, by using the path: and Service-Route: header fields. Other SIP proxies may also be on the signalling path. The debugging configuration causes Alice's UA and the first SIP proxy connected to Alice's terminal to log SIP signalling the next time she sends an INVITE request to bob@barcorp.com. Alice retries calling Bob and signalling is logged for two minutes. Later examination of these logs shows that although requests and responses are correctly exchanged with Bob, Alice's SIP client is not accepting audio-only sessions and is sending BYE immediately. This problem had not come to light previously as all calls within Alice's company are video calls. The outline call flow below illustrates how debugging works. Signalling logged at Alice's UA and the Proxy shows that requests and responses are successfully exchanged, but Alice's UA will not set up an audio-only session and sends BYE immediately. Dawes Expires January 14, 2010 [Page 7] Internet-Draft P-Debug-ID July 2009 Alice Proxy Bob |(1) INVITE | | | m = audio | | | m = video | | | From:alice at atlanta.com | | P-Debug-ID:A076D1 | | | Alice's UA starts logging | |--------------------->| | | | (2) INVITE | | | P-Debug-ID: and From: | | | match debugging config| | | so proxy starts | | | logging | | |---------------------->| | | | | | (3) 200 OK | | | m = audio | | |<----------------------| |(4) 200 OK | | |<---------------------| | | | | |(5) ACK | | |--------------------->| | | | (6) ACK | | |---------------------->| | | | |(7) BYE | | |--------------------->| | | | (8) BYE | | |---------------------->| | | | | | (9) 200 OK | | |<----------------------| | | Dialog has ended so | | | Proxy stops logging | | (10) 200 OK | | |<---------------------| | | Dialog has ended, so | | | Alice's UA stops | | | logging | | Figure 4: Example of Debugging 4.3. Terminating Sessions Logging of a terminating session should start at the SIP proxy at the incoming edge of a network. For example, Bob has been told by Alice that her calls are not getting through and therefore asks the BarCorp Dawes Expires January 14, 2010 [Page 8] Internet-Draft P-Debug-ID July 2009 network administrators to check any incoming calls from Alice. The proxy at the edge of the BarCorp network is provided with the configuration below to log any incoming calls from Alice. The element contains the value for the P-Debug-ID header field that the proxy will insert. bob@barcorp.com alice@foocorp.com T0H2M0S 2B346D Figure 5: Minimal Debugging Configuration for Proxy When Alice calls Bob, the proxy at the edge of the BarCorp network begins logging and inserts a P-Debug-ID: header field with the value 2B346D taken from the configuration data. 5. Avoiding Configuring all Entities on the Signalling Path 5.1. General It is desirable to minimize the need for SIP entities to enrol for debug configuration for two reasons. Firstly, each enrollment results in state maintained in the entity that enrols and in the debug server. Secondly, the path through proxies of a SIP request cannot always be predicted, therefore an indication in the signalling itself that this signalling should be logged is needed. The requirements above can be met by one proxy policing the P-Debug-ID: header field on behalf of all other proxies downstream. Two cases are possible, a sesssion originated at a terminal, and a session that enters a network which will be terminated at a terminal attached to that network. Dawes Expires January 14, 2010 [Page 9] Internet-Draft P-Debug-ID July 2009 5.2. Originating Sessions Both the terminal and the proxy that it connects to at the edge of the FooCorp network are configured with debug data. Since the terminal is outside the trust domain, the edge proxy checks the P-Debug-ID: header field inserted by the terminal, if any, against the debug configuration data it has been supplied for that terminal. If P-Debug-ID should not have been inserted by the terminal, or contains an incorrect value, the proxy removes the header field. If the SIP request has no P-Debug-ID header field but matches the debug configuration data in the proxy, the proxy inserts a P-Debug-ID: header field with the configured value. 5.3. Terminating Sessions The SIP registrar for the address of record being debugged and the terminating user's UA are provided with debug configuration. The SIP request passes through this registrar on its way to the terminating UA and the registrar inserts a P-Debug-ID: header field. SIP entities in the same trust domain and downstream of the registrar can trust that the presence of the P-Debug-ID header field indicates that they should log that SIP request or response. The terminating user's UA is outside the trust domain and therefore requires its own configuration data. 6. Multiple Simultaneous Events At the same time as looking into the problem with calling Bob, the administrators at FooCorp also want to find out why the message sent to Carol caused an error display on Alice's terminal. In order to do this, they add the configuration below to the debug event package hosted on the debug server. The configuration is a new session that has a different id attribute to the previous session. This configuration is supplied to the terminal, and the terminal adds it to the session with id="u01" for debugging the problem with calling Bob. Dawes Expires January 14, 2010 [Page 10] Internet-Draft P-Debug-ID July 2009 carol@barcorp.com T0H2M0S 1A346E Figure 6: Debugging Configuration for Instant Message Alice then re-sends a message request to Carol and the call flow below is recorded. Alice Proxy Carol |(1) MESSAGE | | | From:alice@foocorp.com | | | P-Debug-ID:1A346E | | | Alice's UA starts logging | |----------------------->| | | | (2) MESSAGE | | | P-Debug-ID: and To: | | | match debugging config | | | so proxy starts | | | logging | | |------------------------>| | | | | | (3) 501 Not Implemented | | | P-Debug-ID:1A346E | | |<------------------------| |(4) 501 Not Implemented | Dialog has ended, so | | P-Debug-ID:1A346E | proxy stops | |<-----------------------| logging | | Dialog has ended, so | | | Alice's UA stops | | | logging | | Figure 7: Example of Debugging a MESSAGE Request The signalling flow shows that Carol's SIP UA is not able to process MESSAGE requests. In fact, Carol has an audio-only black phone. Logging for the MESSAGE request sent to Carol and the INVITE request sent to Bob happens simultaneously. Dawes Expires January 14, 2010 [Page 11] Internet-Draft P-Debug-ID July 2009 7. P-Debug-ID in SIP Requests 7.1. Forked Requests Since forked requests are part of the same intention of the user to communicate, the P-Debug-ID header field is copied unchanged from a single SIP request into all SIP requests that result from the forking. 7.2. Back-to-Back User Agents Since requests generated by a B2BUA as a result of an incoming request that is being debugged are part of the same intention of the user to communicate, the P-Debug-ID header field is copied unchanged from a SIP request into all new outgoing SIP requests that a B2BUA generates as a result of the incoming SIP request that contained the P-Debug-ID header. 8. P-Debug-ID in SIP Responses The P-Debug-ID header field is copied unchanged from a single SIP request into all responses, provisional and final, to that SIP request. 9. Multiple Service Providers 9.1. General Foocorp is able to check signalling in its own network, but not in the network of Barcorp. Two solutions are possible, either entities in Barcorp are allowed to retrieve debugging configuration by sending a SUBSCRIBE request to the debug server in Foocorp, or Foocorp asks Barcorp to setup similar debugging in its own network to investigate why the MESSAGE request to Carol is failing. The debugging configuration in Barcorp would consist of logging signalling for requests that are incoming to Carol (i.e., with carol@barcorp.com in the From: header field). 10. Configuration for Multiple AORs Any entity may subscribe to a URI that identifies a group of AORs. If multiple NOTIFY requests carry configuration information about the same AOR then the most recent configuration document is used. It might be that a new NOTIFY request adds a session to existing configuration for an AOR and otherwise leaves its existing Dawes Expires January 14, 2010 [Page 12] Internet-Draft P-Debug-ID July 2009 configuration untouched. 11. Retrieving Debugging Logs When logging finishes, either because the stop trigger event occurred, or because the dialog being logged has ended, the SIP entity sends logged signalling in the body of a PUBLISH request sent to the debug event server. If this PUBLISH request will cross a trust domain boundary, it MUST use authentication, integrity protection, and privacy protection. The debug event server reconstructs the flow of signalling using the dialog identity (Call-ID: header field and the tags in the To: and From: header fields) and the CSeq: and Max-Forwards: header fields. 12. Security Considerations All drafts are required to have a security considerations section. See RFC 3552 [RFC3552] for a guide. 12.1. Trust Domain Since a non-empty P-Debug-ID: header field may cause a SIP entity to log the SIP header and body of a request or response, P-Debug-ID must be removed at a trust domain boundary. If BarCorp is outside the trust domain of FooCorp, then BarCorp will not receive the P-Debug-ID header. However, the SIP entity at the edge of the BarCorp network can attempt to subscribe to the debug configuration for alice@foocorp.com and use this configuration to cause logging in the BarCorp network. 12.2. Security Threats The identity carried by the P-Debug-ID header is not sensitive information, although it will sometimes indicate that a particular device is experiencing problems. If the value in the header is maliciously changed, this will disrupt troubleshooting. The presence of a P-Debug-ID header field will cause some SIP entities to log signalling. Therefore, this header field must be removed at the earliest opportunity if it has been incorrectly inserted. Debug configuration affects the operation of a terminal, therefore it must be supplied by an authorized server to an authorized terminal, it must not be altered in transit, and it must not be readable by an Dawes Expires January 14, 2010 [Page 13] Internet-Draft P-Debug-ID July 2009 unauthorized third party. Logged signalling is privacy-sensitive data, therefore it must be passed to an authorized server, it must not be altered in transit, and it must not be readable by an unauthorized third party. 12.3. Security Mechanisms Security considerations are very similar to those in draft-ietf-sipping-config-framework [I-D.ietf-sipping-config-framework], so the same mechanisms can be used to secure debugging configuration and logged signalling. 13. Formal Syntax All of the mechanisms specified in this document are described in both prose and an augmented Backus-Naur Form (BNF) defined in RFC 2234 [RFC2234]. Further, several BNF definitions are inherited from SIP and are not repeated here. Implementors need to be familiar with the notation and contents of SIP RFC 3261 [RFC3261] and RFC 2234 [RFC2234] to understand this document. 13.1. P-Debug-ID header syntax The syntax for the P-Debug-ID header is described as follows: P-Debug-ID = "P-Debug-ID" HCOLON [gen-value] 14. References 14.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [draft-dawes-sipping-debug-event] Dawes, P., "A Session Initiation Protocol (SIP) Event Package for Debugging", 2008. 14.2. Informative References [I-D.ietf-sipping-config-framework] Channabasappa, S., "A Framework for Session Initiation Protocol User Agent Profile Delivery", draft-ietf-sipping-config-framework-15 (work in progress), February 2008. Dawes Expires January 14, 2010 [Page 14] Internet-Draft P-Debug-ID July 2009 [I-D.narten-iana-considerations-rfc2434bis] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", draft-narten-iana-considerations-rfc2434bis-09 (work in progress), March 2008. [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. [RFC2976] Donovan, S., "The SIP INFO Method", RFC 2976, October 2000. [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002. [RFC3262] Rosenberg, J. and H. Schulzrinne, "Reliability of Provisional Responses in Session Initiation Protocol (SIP)", RFC 3262, June 2002. [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002. [RFC3311] Rosenberg, J., "The Session Initiation Protocol (SIP) UPDATE Method", RFC 3311, October 2002. [RFC3428] Campbell, B., Rosenberg, J., Schulzrinne, H., Huitema, C., and D. Gurle, "Session Initiation Protocol (SIP) Extension for Instant Messaging", RFC 3428, December 2002. [RFC3515] Sparks, R., "The Session Initiation Protocol (SIP) Refer Method", RFC 3515, April 2003. [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003. Appendix A. Additional Stuff This becomes an Appendix. Dawes Expires January 14, 2010 [Page 15] Internet-Draft P-Debug-ID July 2009 Author's Address Peter Dawes Vodafone Group The Connection Newbury, Berkshire RG14 2FN UK Phone: +44 7717 275009 Email: peter.dawes@vodafone.com Dawes Expires January 14, 2010 [Page 16]