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