Internet Engineering Task Force P. Dawes Internet-Draft Vodafone Group Intended status: Standards Track May 3, 2008 Expires: November 4, 2008 Private Extension to the Session Initiation Protocol (SIP) for Debugging draft-dawes-sipping-debug-id-00 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 November 4, 2008. 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 user the network. In order to provide 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 Expires November 4, 2008 [Page 1] Internet-Draft P-Debug-ID May 2008 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 2. The P-Debug-ID Header . . . . . . . . . . . . . . . . . . . . 3 2.1. Debugging principle of operation . . . . . . . . . . . . . 3 2.2. Role of P-Debug-ID . . . . . . . . . . . . . . . . . . . . 4 2.3. Detecting when to insert P-Debug-ID . . . . . . . . . . . 5 2.4. Identifying logged signalling across entities . . . . . . 5 2.5. Validity of debugging configuration . . . . . . . . . . . 5 2.6. Usage of the P-Debug-ID header . . . . . . . . . . . . . . 5 2.6.1. Procedures at the UA . . . . . . . . . . . . . . . . . 6 2.6.2. Procedures at the Registrar . . . . . . . . . . . . . 6 2.6.3. Procedures at a Proxy . . . . . . . . . . . . . . . . 7 2.7. Example Call Flow . . . . . . . . . . . . . . . . . . . . 7 2.7.1. Example configuration at the user agent . . . . . . . 7 2.7.2. Example configuration at a proxy . . . . . . . . . . . 7 2.7.3. Triggering logging start and stop . . . . . . . . . . 8 3. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. P-Debug-ID header syntax . . . . . . . . . . . . . . . . . 10 4. Table of new headers . . . . . . . . . . . . . . . . . . . . . 10 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 Intellectual Property and Copyright Statements . . . . . . . . . . 13 Dawes Expires November 4, 2008 [Page 2] Internet-Draft P-Debug-ID May 2008 1. Introduction The original specification of xml2rfc format is in RFC 2629 [RFC2629]. 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]. 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. Dawes Expires November 4, 2008 [Page 3] Internet-Draft P-Debug-ID May 2008 +------------+ | | | Inactive | | | +------------+ ^ | | | Supply debugging Delete debugging | | configuration configuration | | | | | V +------------+ | | | Active | | | +------------+ ^ | | | | | Start trigger Stop trigger | | event event | | | | | V +------------+ | | | Logging | | | +------------+ Figure 1: 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. 2.2. Role of P-Debug-ID P-Debug-ID has two roles, to provide the start trigger event in the figure above, or to cause a UA to subscribe to the debug event package defined in draft-dawes-sipping-debug-event. P-Debug-ID provides the start trigger event 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 Dawes Expires November 4, 2008 [Page 4] Internet-Draft P-Debug-ID May 2008 event". 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 P-Preferred-Identity header, for UA originating requests, or the request URI, 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 user identity defined in the sub-element 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 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. 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 two roles: to provide the start trigger event in the figure above, or to cause a UA to subscribe to the debug event package defined in draft-dawes-sipping-debug-event. Dawes Expires November 4, 2008 [Page 5] Internet-Draft P-Debug-ID May 2008 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 SHOULD 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 SHALL 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, using the address of record that it registered. 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 UA MUST copy the P-Debug-ID header from a request into all responses to that request, including 1xx responses. Dawes Expires November 4, 2008 [Page 6] Internet-Draft P-Debug-ID May 2008 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 defined in draft-dawes-sipping-debug-event 2.6.3. Procedures at a Proxy The procedures for a proxy are the same as for the registrar. 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