Internet Engineering Task Force P. Dawes Internet-Draft K. Chew, Ed. Intended status: Standards Track Vodafone Group Expires: May 2, 2009 October 29, 2008 Private Extension to the Session Initiation Protocol (SIP) for Debugging draft-dawes-sipping-debug-id-01 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of 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 May 2, 2009. 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 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 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. Dawes & Chew Expires May 2, 2009 [Page 1] Internet-Draft P-Debug-ID October 2008 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 2. The P-Debug-ID Header . . . . . . . . . . . . . . . . . . . . 6 2.1. Debugging principle of operation . . . . . . . . . . . . . 6 2.2. Role of P-Debug-ID . . . . . . . . . . . . . . . . . . . . 7 2.3. Detecting when to insert P-Debug-ID . . . . . . . . . . . 7 2.4. Identifying logged signalling across entities . . . . . . 7 2.5. Validity of debugging configuration . . . . . . . . . . . 8 2.6. Usage of the P-Debug-ID header . . . . . . . . . . . . . . 8 2.6.1. Procedures at the UA . . . . . . . . . . . . . . . . . 8 2.6.2. Procedures at the Registrar . . . . . . . . . . . . . 9 2.6.3. Procedures at a Proxy . . . . . . . . . . . . . . . . 9 2.6.3.1. Proxy with Debug Configuration . . . . . . . . . . 9 2.6.3.2. Proxy without Debug Configuration . . . . . . . . 10 2.7. Example Call Flow . . . . . . . . . . . . . . . . . . . . 10 2.7.1. Example configuration at the user agent . . . . . . . 10 2.7.2. Example configuration at a proxy . . . . . . . . . . . 11 2.7.3. Triggering logging start and stop . . . . . . . . . . 11 3. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 13 3.1. P-Debug-ID header syntax . . . . . . . . . . . . . . . . . 13 4. Table of new headers . . . . . . . . . . . . . . . . . . . . . 13 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 8.1. Normative References . . . . . . . . . . . . . . . . . . . 14 8.2. Informative References . . . . . . . . . . . . . . . . . . 14 Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 Intellectual Property and Copyright Statements . . . . . . . . . . 17 Dawes & Chew Expires May 2, 2009 [Page 2] Internet-Draft P-Debug-ID October 2008 1. Introduction Alice has a SIP client on her laptop, which she has been using for some time to make video calls to work colleagues inside her company. Today, she tried to set up a call to Bob, who recently installed an audio-only SIP phone at home, but the call failed and Alice does not know why. She contacts those who manage the SIP network within her company to ask them to fix the problem. Alice's UA and the SIP proxy that Alice uses must be configured to log SIP signalling the next time she sends an INVITE request. The UA and the proxy obtain their configuration by subscribing to the debug event package, which supplies XML configuration documents carried in NOTIFY requests. Because debugging is rarely needed, 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 both Alice's UA and the SIP proxy that Alice uses to subscribe to Alice's debug event package at the registrar, which returns them an XML document containing her debugging configuration. The debugging configuration causes Alice's UA and the SIP proxy that Alice uses to log SIP signalling the next time she sends an INVITE request. Alice retries calling Bob and signalling is logged until the dialog with Bob ends. 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 debugging configuration (supplied by subscription to the debug event package) used to investigate the problem is shown below. Alice's UA inserts the configured identifier (P-Debug-ID:A076D1) to trigger logging of signalling at the proxy, and the same identifier is used to correlate signalling logged at Alice's UA and at the Proxy after logging has finished. Dawes & Chew Expires May 2, 2009 [Page 3] Internet-Draft P-Debug-ID October 2008 Alice Proxy Bob alice@atlanta.com p1.example.com bob at biloxi.com A076D1 alice@atlanta.com INVITE A076D1 Figure 1: Debugging Configuration 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 & Chew Expires May 2, 2009 [Page 4] Internet-Draft P-Debug-ID October 2008 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 2: Example of Debugging 1.1. 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]. Dawes & Chew Expires May 2, 2009 [Page 5] Internet-Draft P-Debug-ID October 2008 2. The P-Debug-ID Header The P-Debug-ID header field carries a 3-digit hexadecimal number used as an end-to-end identifier for logging of SIP signalling. The header is added by a SIP UA or a SIP proxy in order to trigger logging of SIP signalling in downstream entities. Configuration of debugging is provided by the debug event package described in draft-dawes-sipping-debug-event [draft-dawes-sipping-debug-event] 2.1. Debugging principle of operation Debugging can be understood by the simple state machine below, which applies to any SIP UA or Proxy. +------------+ | | | Inactive | | | +------------+ ^ | | | Supply debugging Delete debugging | | configuration configuration | | | | | V +------------+ | | | Active | | | +------------+ ^ | | | | | Start trigger Stop trigger | | event event | | | | | V +------------+ | | | Logging | | | +------------+ Figure 3: Debugging State Machine This document is mainly concerned with the "Start trigger event"; debugging configuration and the stop trigger event are described to illustrate the purpose of the P-Debug-ID header. Dawes & Chew Expires May 2, 2009 [Page 6] Internet-Draft P-Debug-ID October 2008 2.2. Role of P-Debug-ID P-Debug-ID has three roles, to provide the start trigger event in the figure above, to cause (by its presence) a SIP entity to log SIP signalling, or to cause a UA to subscribe to the debug event package described in draft-dawes-sipping-debug-event [draft-dawes-sipping-debug-event]. P-Debug-ID provides the start trigger event in the example in the figure above for all SIP entities other than the SIP entity that inserted the P-Debug-ID header. Start of logging of SIP signalling by a SIP entity is triggered if the P-Debug-ID header contains a value that matches the value contained in the debugging configuration of that SIP entity. Logging continues until a "stop trigger event" is detected, as defined within the configuration element "stop trigger event". Once a non-empty P-Debug-ID header field has been inserted, SIP entities that do not have any debugging configuration can use its presence as an indication that signalling MUST be logged. Debugging will be an infrequent activity, therefore it is not efficient for a UA to be permanently subscribed to the debug event package. A registrar can prompt a UA to subscribe to the debug event package by including an empty P-Debug-ID header field in a 200 OK response to a REGISTER request. 2.3. Detecting when to insert P-Debug-ID A UA, proxy, or registrar can insert a P-Debug-ID header. Debugging configuration MAY specify conditions that must be met for to insert a P-Debug-ID header in the configuration element. Typically, the conditions will be a particular SIP method and a particular SIP URI in the From: header field, for UA originating requests, or the To: header field, for UA terminating requests. For example, a UA that originates an INVITE request and identifies itself as alice@u1.atlanta.com will trigger that UA to insert a P-Debug-ID header containing a 3-digit hexadecimal value taken from the configuration element. 2.4. Identifying logged signalling across entities The P-Debug-ID header field contains a 6-digit hexadecimal number, taken from the configuration element, which is combined with the address of record attribute of the "aor" attribute in configuration data to provide a unique identifier to tie together SIP signalling logged at all UAs and proxys. Logging of SIP signalling must include the value in the P-Debug-ID header field and the user Dawes & Chew Expires May 2, 2009 [Page 7] Internet-Draft P-Debug-ID October 2008 identity from the configuration element. 2.5. Validity of debugging configuration Debugging configuration is used once and then discarded. Debugging configuration is valid until the following sequence has completed: a start trigger event defined in the configuration element is detected, logging of signalling starts, the stop trigger event defined in the configuration element is detected, and logging of signalling stops. The configuration is then discarded. If no debugging configuration remains, the entity moves into the Inactive state in the debugging state machine. 2.6. Usage of the P-Debug-ID header A UA, proxy, or registrar can insert a P-Debug-ID header. P-Debug-ID has three roles: to provide the start trigger event in the figure above, to cause an entity with no debugging configuration to log a message, or to cause a UA to subscribe to the debug event package described in draft-dawes-sipping-debug-event [draft-dawes-sipping-debug-event]. 2.6.1. Procedures at the UA If the UA is originating a SIP session and detects a start trigger event, as defined in its debugging configuration information, and is not logging SIP signalling, the UA MUST insert a P-Debug-ID header field containing the 3-digit hexadecimal value defined in the sub-element of its debugging configuration. If the UA is terminating a SIP session and detects a start trigger event, as defined in its debugging configuration information, the UA MUST begin to log SIP signalling. If the UA is logging SIP signalling and detects a stop trigger event, as defined in its debugging configuration information, the UA MUST stop logging SIP signalling. A UA MUST copy the P-Debug-ID header from a terminating request into all responses to that request, including 1xx responses. If a UA receives an empty P-Debug-ID header field in a 200 OK response to a REGISTER request, the UA SHOULD subscribe its own debug event package, defined in draft-dawes-sipping-debug-event [draft-dawes-sipping-debug-event], using the address of record that it registered. Dawes & Chew Expires May 2, 2009 [Page 8] Internet-Draft P-Debug-ID October 2008 2.6.2. Procedures at the Registrar If a registrar detects a start trigger event, as defined in its debugging configuration information, and is not logging SIP signalling, the registrar SHOULD begin to log SIP signalling. If the SIP session is terminating at a UA served by the registrar and the registrar detects a start trigger event, as defined in its debugging configuration information and the SIP request does not contain a P-Debug-ID header and a 3-digit hexadecimal value is defined in the sub-element of its debugging configuration the registrar MUST insert a P-Debug-ID header field containing the 3-digit hexadecimal value defined in the sub-element of its debugging configuration. If the registrar detects a stop trigger event, as defined in its debugging configuration information, the registrar SHOULD stop logging SIP signalling. If the registrar forks a SIP request, the registrar MUST copy the P-Debug-ID header field into each request that results from forking. A registrar MUST copy the P-Debug-ID header from a request into all responses to that request, including 1xx responses. The registrar MAY include an empty P-Debug-ID header in a 200 OK response to a REGISTER request to prompt a UA to subscribe to the debug event package described in draft-dawes-sipping-debug-event [draft-dawes-sipping-debug-event]. 2.6.3. Procedures at a Proxy 2.6.3.1. Proxy with Debug Configuration If a proxy detects a start trigger event, as defined in its debugging configuration information, and is not logging SIP signalling, the registrar MUST begin to log SIP signalling. If the SIP session is originating at a UA served by the proxy and the proxy detects a start trigger event, as defined in its debugging configuration, and the SIP request does not contain a P-Debug-ID header and a 3-digit hexadecimal value is defined in the sub-element of its debugging configuration then the proxy MUST insert a P-Debug-ID header field containing the 6-digit hexadecimal value defined in the sub-element of its debugging configuration. If the proxy received the message from an element that it does not trust and there is a P-Debug-ID header present containing a 3-digit hexadecimal value, the proxy MUST replace that value with the value Dawes & Chew Expires May 2, 2009 [Page 9] Internet-Draft P-Debug-ID October 2008 defined in the sub-element of its debugging configuration or remove this header field. If the proxy detects a stop trigger event, as defined in its debugging configuration, the registrar SHOULD stop logging SIP signalling. A proxy MUST copy the P-Debug-ID header from a request into all responses to that request, including 1xx responses. 2.6.3.2. Proxy without Debug Configuration A proxy in a Trust Domain can receive a request from a node that it trusts, or a node that it does not trust. If the proxy receives a message (request or response) from a node that it trusts, it can use the presence of the P-Debug-ID header field, if any, as an indication that the message MUST be logged. 2.7. Example Call Flow In order to trigger logging, each entity must be pre-configured to allow it to detect start and stop trigger events. 2.7.1. Example configuration at the user agent In this example, the UA is configured to start logging at 9am by the