Internet Engineering Task Force P. Dawes
Internet-Draft Vodafone
Intended status: Informational K. Chew, Ed.
Expires: May 2, 2009 Vodafone Group
October 29, 2008
A Session Initiation Protocol (SIP) Event Package for Debugging
draft-dawes-sipping-debug-event-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
This document defines a Session Initiation Protocol (SIP) event
package for debugging. An entity that subscribes to this event
package for an address of record receives configuration data that
controls logging of SIP signalling for that address of record, for
example when to begin an end logging.
Dawes & Chew Expires May 2, 2009 [Page 1]
Internet-Draft SIP Debugging Event October 2008
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. Usage Scenarios . . . . . . . . . . . . . . . . . . . . . . . 3
3. Principle of Operation . . . . . . . . . . . . . . . . . . . . 4
3.1. Minimum debugging configuration . . . . . . . . . . . . . 5
4. Package Definition . . . . . . . . . . . . . . . . . . . . . . 5
4.1. Event Package Name . . . . . . . . . . . . . . . . . . . . 5
4.2. Event Package Parameters . . . . . . . . . . . . . . . . . 5
4.3. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 5
4.4. Subscription Duration . . . . . . . . . . . . . . . . . . 6
4.5. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 6
4.6. Notifier Processing of SUBSCRIBE Requests . . . . . . . . 7
4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 7
4.7.1. The Debug Configuration State Machine . . . . . . . . 8
4.7.2. Applying the State Machine . . . . . . . . . . . . . . 9
4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 9
4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 9
4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 9
4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 10
5. Debug Configuration Information . . . . . . . . . . . . . . . 10
5.1. Structure of Debug Configuration . . . . . . . . . . . . . 10
5.2. Computing Debug Configuration from the Document . . . . . 11
5.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 13
6. Example Call Flows . . . . . . . . . . . . . . . . . . . . . . 16
6.1. Subscription to debug-event . . . . . . . . . . . . . . . 16
6.2. Incoming session . . . . . . . . . . . . . . . . . . . . . 20
6.3. Outgoing session . . . . . . . . . . . . . . . . . . . . . 22
6.4. Prompting a user agent to subscribe to debug-event . . . . 26
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 26
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
8.1. SIP Event Package Registration . . . . . . . . . . . . . . 27
8.2. application/debuinfo+xml MIME Registration . . . . . . . . 27
9. Security Considerations . . . . . . . . . . . . . . . . . . . 28
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
10.1. Normative References . . . . . . . . . . . . . . . . . . . 28
10.2. Informative References . . . . . . . . . . . . . . . . . . 29
Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29
Intellectual Property and Copyright Statements . . . . . . . . . . 30
Dawes & Chew Expires May 2, 2009 [Page 2]
Internet-Draft SIP Debugging Event October 2008
1. Introduction
The Session Initiation Protocol (SIP) RFC 3261 [RFC3261] provides all
of the functions needed for the establishment and maintenance of
communications sessions between users. Registration establishes an
address at which a user can be contacted to set up communication
sessions.
It is possible for that session setup might fail, for example due to
a network fault or mis-configuration, or that poor network
performance causes long setup delays. In such circumstances, it is
useful to be able to analyse SIP requests and responses end-to-end
from the UAC to the UAS, which entails logging of requests and
responses by entities along the signalling route.
Such logging will be occasional, specific to an address of record,
and specific to the SIP entities traversed on the route to and from
that address of record. Also, it must be possible to collect logs of
signalling taken from different SIP entities and identify that they
belong to the same SIP session. These requirements suggest two
properties of a solution; it must be possible to configure any SIP
entity on-the-fly to log requests and responses for a particular
address of record, and configuration data must include an identifier
that will allow logs from separate entities to be identified as
belonging to the same session. Also, for operational simplicity, it
is desirable to have a single logical point of control. An event
package allows entities to subscribe and unsubscribe as needed, is
organized by address of record, and can be hosted at a single point
of control.
This document describes an event package that enables SIP UAs,
proxies and B2BUAs to be dynamically configured to log SIP requests
and responses.
Logged signalling is identified across different entities with the
help of a private header field defined in
draft-dawes-sipping-debug-id [draft-dawes-sipping-debug-id]
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. Usage Scenarios
This event package supplies configuration for two broad applications,
Dawes & Chew Expires May 2, 2009 [Page 3]
Internet-Draft SIP Debugging Event October 2008
debugging user reported faults and regression testing of a SIP
network, as described in draft-dawes-sipping-debug-id
[draft-dawes-sipping-debug-id].
3. 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 1: Debugging State Machine
The debugging configuration is an XML document described by the
schema in this document. Supply of configuration causes debugging
state to change from Inactive to Active. Configuration defines one
or more start trigger events, which cause debugging state to change
from Active to Logging when they are detected. A start trigger event
is typically a user identity, in the SIP From: or To: header field,
plus a 6-digit hexadecimal reference number. Similarly,
Dawes & Chew Expires May 2, 2009 [Page 4]
Internet-Draft SIP Debugging Event October 2008
configuration contains one or more stop triggering events, which
cause debugging state to change from Logging to Active when they are
detected. A stop trigger event is typically the expiry of a timer or
the end of a SIP session.
3.1. Minimum debugging configuration
In order to uniquely identify signalling logged at different entities
as belonging to the same session, the minimum set of debugging
configuration is a "aor" attribute and a <debug-id> element.
4. Package Definition
This section fills in the details needed to specify an event package
as defined in Section 4.4 of RFC 3265 [RFC3265].
4.1. Event Package Name
The SIP Events specification requires package definitions to specify
the name of their package or template-package.
The name of this package is "debug". As specified in RFC 3265
[RFC3265], this value appears in the Event header present in
SUBSCRIBE and NOTIFY requests.
Example:
Event: debug
4.2. Event Package Parameters
The SIP Events specification requires package and template-package
definitions to specify any package specific parameters of the Event
header that are used by it.
No package specific Event header parameters are defined for this
event package.
4.3. SUBSCRIBE Bodies
The SIP Events specification requires package or template-package
definitions to define the usage, if any, of bodies in SUBSCRIBE
requests.
A SUBSCRIBE for debug events MAY contain a body. This body would
serve the purpose of filtering the subscription. The definition of
such a body is outside the scope of this specification.
Dawes & Chew Expires May 2, 2009 [Page 5]
Internet-Draft SIP Debugging Event October 2008
A SUBSCRIBE for the debug package MAY be sent without a body. This
implies that the default registration filtering policy has been
requested. The default policy is:
o Notifications are generated every time there is any change in the
state of any part of the debug configuration for the resource
being subscribed to. Those notifications only contain information
on the configuration elements whose state has changed.
o Notifications triggered from a SUBSCRIBE contain full state (all
debug configuration bound to the address-of-record). Of course,
the server can apply any policy it likes to the subscription.
4.4. Subscription Duration
The SIP Events specification requires package definitions to define a
default value for subscription durations, and to discuss reasonable
choices for durations when they are explicitly specified.
Debug configuration state changes as the need for debugging arises,
either to investigate a user-reported fault or perform regression
testing. The debug configuration for a user or users is updated by
administrative means.
Since configuration of debugging will be followed quickly by the
debugging itself, the default duration of subscriptions to debug
configuration is 43200 seconds. Of course, clients MAY include an
Expires header in the SUBSCRIBE request asking for a different
duration.
4.5. NOTIFY Bodies
The SIP Events specification requires package definitions to describe
the allowed set of body types in NOTIFY requests, and to specify the
default value to be used when there is no Accept header in the
SUBSCRIBE request.
The body of a notification of a change in debug configuration state
contains a debug configuration information document. This document
describes some or all of the debugging configuration associated with
a particular address-of-record. All subscribers and notifiers MUST
support the "application/debuginfo+xml" format described in Section
5. The subscribe request MAY contain an Accept header field. If no
such header field is present, it has a default value of "application/
debuginfo+xml". If the header field is present, it MUST include
"application/debuginfo+xml", and MAY include any other types capable
of representing debugging information.
Dawes & Chew Expires May 2, 2009 [Page 6]
Internet-Draft SIP Debugging Event October 2008
Of course, the notifications generated by the server MUST be in one
of the formats specified in the Accept header field in the SUBSCRIBE
request.
4.6. Notifier Processing of SUBSCRIBE Requests
The SIP Events framework specifies that packages should define any
package-specific processing of SUBSCRIBE requests at a notifier,
specifically with regards to authentication and authorization.
Debug configuration can be sensitive information. Therefore, all
subscriptions to it SHOULD be authenticated and authorized before
approval. Authentication MAY be performed using any of the
techniques available through SIP, including digest, S/MIME, TLS or
other transport specific mechanisms RFC3261 [RFC3261]. Authorization
policy is at the discretion of the administrator, as always.
However, a few recommendations can be made.
It is RECOMMENDED that a user be allowed to subscribe to their own
debug configuration state. Debugging relies upon a user agent
including a network-provided debug-id, and this is most easily
provided by allowing the user to subscribe to debug-event. We also
anticipate that applications and automata will frequently be
subscribers to the debug configuration state. In those cases,
authorization policy will typically be provided ahead of time.
4.7. Notifier Generation of NOTIFY Requests
The SIP Event framework requests that packages specify the conditions
under which notifications are sent for that package, and how such
notifications are constructed.
To determine when a notifier should send notifications of changes in
debug configuration state, we define a finite state machine (FSM)
that represents the state of debug configuration for a particular
address-of-record.
Transitions in this state machine MAY result in the generation of
notifications. These notifications will carry information on the new
state and the event which triggered the state change. It is
important to note that this FSM is just a model of the debug
configuration state machinery maintained by a server. An
implementation would map its own state machines to this one in an
implementation-specific manner.
Dawes & Chew Expires May 2, 2009 [Page 7]
Internet-Draft SIP Debugging Event October 2008
4.7.1. The Debug Configuration State Machine
The underlying state machine for debug configuration is shown in the
figure below. The machine is very simple. An instance of this
machine is associated with each address-of-record. When there is no
debugging configuration defined for an address-of-record, the state
machine is in the init state. It is important to note that this
state machine exists, and is well-defined, for each address-of-record
in the domain, even if there is no debug configuration defined for
it. This allows a user agent to subscribe to an address-of-record,
and learn that there is no debug configuration for it. When debug
configuration is added for that address-of-record, the state machine
moves from init to active.
+------------+
| |
| Init |
| |
+------------+
|
V
+------------+
| |
| Active |
| |
+------------+
|
V
+------------+
| |
| Terminated |
| |
+------------+
Figure 2: Debug Congfiguration State Machine
As long as there is debugging configuration for the address-of-
record, the state machine remains in the active state. When the last
debug configuration expires or is removed, the debug configuration
transitions to terminated. From there, it immediately transitions
back to the init state. This transition is invisible, in that it
MUST NOT ever be reported to a subscriber in a NOTIFY request.
This allows for an implementation optimization whereby the registrar
can destroy the objects associated with the debug configuration state
machine once it enters the terminated state and a NOTIFY has been
sent. Instead, the registrar can assume that, if the objects for
that state machine no longer exist, the state machine is in the init
Dawes & Chew Expires May 2, 2009 [Page 8]
Internet-Draft SIP Debugging Event October 2008
state.
4.7.2. Applying the State Machine
The server MAY generate a notification to subscribers when any event
occurs in the debug configuration state machine, except for the
transition from terminated to init. As noted above, a notification
MUST NOT be sent in this case. For other transitions, whether the
server sends a notification or not is policy dependent. However,
several guidelines are defined.
4.8. Subscriber Processing of NOTIFY Requests
The SIP Events framework expects packages to specify how a subscriber
processes NOTIFY requests in any package specific ways, and in
particular, how it uses the NOTIFY requests to construct a coherent
view of the state of the subscribed resource. For debug
configuration, the NOTIFY will contain all information for the
address of record whose configuration has changed.
4.9. Handling of Forked Requests
The SIP Events framework mandates that packages indicate whether or
not forked SUBSCRIBE requests can install multiple subscriptions.
Debug configuration is normally stored in some repository (whether it
be co-located with a proxy/registrar or in a separate database). As
such, there is usually a single place where the debug configuration
information for a particular address-of-record is resident. This
implies that a subscription for this information is readily handled
by a single element with access to this repository. There is,
therefore, no compelling need for a subscription to debug
configuration information to fork. As a result, a subscriber MUST
NOT create multiple dialogs as a result of a single subscription
request. The required processing to guarantee that only a single
dialog is established is described in Section 4.4.9 of the SIP Events
framework RFC3265 [RFC3265].
4.10. Rate of Notifications
The SIP Events framework mandates that packages define a maximum rate
of notifications for their package.
For reasons of congestion control, it is important that the rate of
notifications not become excessive. A change of debug configuration
is usually followed by a session to be debugged, which takes
significant time. Even during regression testing, in which a number
of consecutive sessions might be debugged, notifications are
Dawes & Chew Expires May 2, 2009 [Page 9]
Internet-Draft SIP Debugging Event October 2008
punctuated by the sessions or standalone transactions to be debugged.
It is therefore RECOMMENDED that the server not generate
notifications for a single subscriber at a rate faster than once
every 60 seconds.
4.11. State Agents
The SIP Events framework asks packages to consider the role of state
agents in their design.
Debug configuration information is passed from a network management
server to the SIP registrar, which hosts the debug configuration
event package. The details of how debug configuration information is
passed to the SIP registrar is outside the scope of this document.
5. Debug Configuration Information
5.1. Structure of Debug Configuration
Debug configuration is an XML document Canonical XML Version 1.0
[W3C.xml-c14n] that MUST be well-formed and SHOULD be valid. Debug
configuration documents MUST be based on XML 1.0 and MUST be encoded
using UTF-8. This specification makes use of XML namespaces for
identifying debug configuration documents and document fragments.
The namespace URI for elements defined by this specification is a URN
RFC 2141 [RFC2141], using the namespace identifier 'ietf' defined by
RFC 2648 [RFC2648] and extended by RFC 3688 [RFC3688];. This URN is:
urn:ietf:params:xml:ns:debuginfo
A debug configuration document begins with the root element tag
"debuginfo". It consists of any number of "debugconfig" sub-
elements, each of which contains descriptions of sessions or
standalone transactions that are to be debugged for a particular
address-of-record. The debug configuration information for a
particular address-of-record MUST be contained within a single
"debuginfo" element; it cannot be spread across multiple "debuginfo"
elements within a document. Other elements from different namespaces
MAY be present for the purposes of extensibility; elements or
attributes from unknown namespaces MUST be ignored. There are two
attributes associated with the "debuginfo" element, both of which
MUST be present:
version: This attribute allows the recipient of debug
configuration documents to properly order them. Versions
start at 0, and increment by one for each new document sent
to a subscriber. Versions are scoped within a
Dawes & Chew Expires May 2, 2009 [Page 10]
Internet-Draft SIP Debugging Event October 2008
subscription. Versions MUST be representable using a 32
bit integer.
state: This attribute indicates whether the document
contains the full registration state, or whether it
contains only information on those debug configurations
which have changed since the previous document (partial).
Note that the document format explicitly allows for conveying
information on multiple addresses-of-record. This enables
subscriptions to groups of debug configurations, where such a group
is identified by some kind of URI. For example, a domain might
define sip:allusers@example.com as a resource that can be subscribed
to and generates notifications when the state of any address-of-
record in the domain changes.
The "debugconfig" element has a list of any number of "session" sub-
elements, each of which contains information on a single session or
standalone transaction. Other elements from different namespaces MAY
be present for the purposes of extensibility; elements or attributes
from unknown namespaces MUST be ignored. There are three attributes
associated with the "debugconfig" element, all of which MUST be
present:
aor: The aor attribute contains a URI which is the address-
of-record this registration refers to.
state: The state attribute indicates the state of the debug
configuration. The valid values are "init", "active" and
"terminated".
The "session" element contains a "debug-id" element and a "start
trigger" element, "stop trigger" element, and "control" element.
Other elements from different namespaces MAY be present for the
purposes of extensibility; elements or attributes from unknown
namespaces MUST be ignored. There is one attribute associated with
the "session" element which MUST be present:
id: The "id" attribute identifies this session. It MUST be
unique amongst all other id attributes present in other
debug configuration elements conveyed to the subscriber
within the scope of their subscription.
5.2. Computing Debug Configuration from the Document
Typically, the NOTIFY for debug configuration information will only
contain information about those sessions whose state has changed. To
construct a coherent view of the total state of all registrations, a
Dawes & Chew Expires May 2, 2009 [Page 11]
Internet-Draft SIP Debugging Event October 2008
subscriber will need to combine NOTIFYs received over time. The
subscriber maintains a table for each debug configuration it receives
information for. Each debug configuration is uniquely identified by
the "aor" attribute in the "debug configuration" element. Each table
contains a row for each session in that debug configuration. Each
row is indexed by the unique id for that session. It is conveyed in
the "id" attribute of the "session" element. The tables are also
associated with a version number. The version number MUST be
initialized with the value of the "version" attribute from the
"debuginfo" element in the first document received. Each time a new
document is received, the value of the local version number, and the
"version" attribute in the new document, are compared. If the value
in the new document is one higher than the local version number, the
local version number is increased by one, and the document is
processed. If the value in the document is more than one higher than
the local version number, the local version number is set to the
value in the new document, the document is processed, and the
subscriber SHOULD generate a refresh request to trigger a full state
notification. If the value in the document is less than the local
version, the document is discarded without processing.
The processing of the document depends on whether it contains full or
partial state. If it contains full state, indicated by the value of
the "state" attribute in the "debuginfo" element, the contents of all
tables associated with this subscription are flushed. They are re-
populated from the document. A new table is created for each
"debugconfig" element, and a new row in each table is created for
each "session" element. If the debuginfo contains partial state, as
indicated by the value of the "state" attribute in the "debuginfo"
element, the document is used to update the existing tables. For
each "debugconfig" element, the subscriber checks to see if a table
exists for that debug configuration. This check is done by comparing
the value in the "aor" attribute of the "debugconfig" element with
the aor associated with the table. If a table doesn't exist for that
registration, one is created. For each "session" element in the
debug configuration, the subscriber checks to see whether a row
exists for that session. This check is done by comparing the ID in
the "id" attribute of the "session" element with the ID associated
with the row. If the session doesn't exist in the table, a row is
added, and its state is set to the information from that "session"
element. If the session does exist, its state is updated to be the
information from that "session" element. If a row is updated or
created, such that its state is now terminated, that entry MAY be
removed from the table at any time.
Dawes & Chew Expires May 2, 2009 [Page 12]
Internet-Draft SIP Debugging Event October 2008
5.3. Example
The following is an example debug configuration information document:
<?xml version="1.0"?>
<debuginfo xmlns="urn:ietf:params:xml:ns:debuginfo"
version="0" state="full">
<debugconfig aor="alice@atlanta.com">
<session id="r03">
<start-trigger>
<debug-id>1A346D</debug-id>
<to>alice@atlanta.com</to>
</start-trigger>
<stop-trigger>
<reason>dialog-established</reason>
</stop-trigger>
<control>
<trace-depth>minimum</trace-depth>
</control>
</session>
</debugconfig>
</debuginfo>
5.4. XML Schema
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:debuginfo"
xmlns:tns="urn:ietf:params:xml:ns:debuginfo"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<!-- This import brings in the XML language attribute xml:lang-->
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/03/xml.xsd"/>
<!-- debuginfo is the root element in debug configuration
debuginfo contains one or more debugconfig elements, where one
debugconfig element exists per address of record.
-->
<!-- definition of simple elements -->
<xs:element name="time" type="xs:time"/>
<xs:element name="from" type="xs:string"/>
<xs:element name="to" type="xs:string"/>
<xs:element name="method" type="xs:string"/>
<xs:element name="icsi" type="xs:string"/>
<xs:element name="iari" type="xs:string"/>
<xs:element name="time-period" type="xs:duration"/>
<xs:element name="interface" type="xs:string"/>
<xs:element name="debug-id" type="hexBinary"/>
Dawes & Chew Expires May 2, 2009 [Page 13]
Internet-Draft SIP Debugging Event October 2008
<!-- definition of simple elements with restrictions -->
<xs:element name="reason">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="dialog_established"/>
<xs:enumeration value="session_end"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="depth">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="maximum"/>
<xs:enumeration value="minimum"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- definition of attributes -->
<xs:attribute name="version" type="xs:nonNegativeInteger"/>
<xs:attribute name="aor" type="xs:string" minOccurs="1"
maxOccurs="1"/>
<xs:attribute name="id" type="xs:string" use="required"/>
<!-- definition of attributes with restrictions -->
<xs:attribute name="state">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="full"/>
<xs:enumeration value="partial"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!-- definition of complex elements -->
<xs:element name="debuginfo">
<xs:complexType>
<xs:sequence>
<xs:element ref="debugconfig" minOccurs="0"
maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute ref="version" use="required"/>
<xs:attribute ref="state" use="required"/>
</xs:complexType>
</xs:element>
Dawes & Chew Expires May 2, 2009 [Page 14]
Internet-Draft SIP Debugging Event October 2008
<xs:element name="debugconfig">
<xs:complexType>
<xs:sequence>
<xs:element ref="session" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute ref="aor" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="session">
<xs:complexType>
<xs:sequence>
<xs:element ref="start-trigger"/>
<xs:element ref="stop-trigger"/>
<xs:element ref="control"/>
</xs:sequence>
<xs:attribute ref="id" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="start-trigger">
<xs:complexType>
<xs:sequence>
<xs:element ref="from" minOccurs="0" maxOccurs="1"/>
<xs:element ref="to" minOccurs="0" maxOccurs="1"/>
<xs:element ref="icsi" minOccurs="0" maxOccurs="1"/>
<xs:element ref="iari" minOccurs="0" maxOccurs="1"/>
<xs:element ref="method" minOccurs="0" maxOccurs="1"/>
<xs:element ref="time" minOccurs="0" maxOccurs="1"/>
<xs:element ref="debug-id" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="stop-trigger">
<xs:complexType>
<xs:sequence>
<xs:element ref="time" minOccurs="0" maxOccurs="1"/>
<xs:element ref="time-period" minOccurs="0" maxOccurs="1"/>
<xs:element ref="reason" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="control">
<xs:complexType>
<xs:sequence>
<xs:element ref="interface"/>
Dawes & Chew Expires May 2, 2009 [Page 15]
Internet-Draft SIP Debugging Event October 2008
<xs:element ref="depth" minOccurs="0" maxOccurs="1"/>
<xs:element ref="debug-id" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
6. Example Call Flows
6.1. Subscription to debug-event
User Proxy Registrar
|(1) REGISTER | |
|------------------>| |
| |(2) REGISTER |
| |------------------>|
| |(3) 200 OK |
| |<------------------|
|(4) 200 OK | |
|<------------------| |
|(5) SUBSCRIBE | |
| Event:debug | |
|-------------------------------------->|
| |(6) 200 OK |
|<--------------------------------------|
| |(7) NOTIFY |
|<--------------------------------------|
|(8) 200 OK | |
|-------------------------------------->|
| | |
| |(9) SUBSCRIBE |
| |Event:debug |
| |------------------>|
| |(10) 200 OK |
| |<------------------|
| |(11) NOTIFY |
| |<------------------|
| |(12) 200 OK |
| |------------------>|
Dawes & Chew Expires May 2, 2009 [Page 16]
Internet-Draft SIP Debugging Event October 2008
Alice registers (1) and (2)
REGISTER sip:r1.atlanta.com SIP/2.0
Via: SIP/2.0/UDP u1.atlanta.com:5060;branch=z9hG4bKnashds7
Max-Forwards: 70
To: Alice <sip:alice@atlanta.com>
From: Alice <sip:alice@atlanta.com>;tag=456248
Call-ID: 843817637684230@998sdasdh09
CSeq: 1826 REGISTER
Contact: <sip:alice@192.0.2.4>
Expires: 7200
Content-Length: 0
Registration is successful (3) and (4)
SIP/2.0 200 OK
Via: SIP/2.0/UDP u1.atlanta.com:5060;branch=z9hG4bKnashds7
;received=192.0.2.4
To: Alice <sip:alice@atlanta.com>;tag=2493k59kd
From: Alice <sip:alice@atlanta.com>;tag=456248
Call-ID: 843817637684230@998sdasdh09
CSeq: 1826 REGISTER
Contact: <sip:alice@192.0.2.4>
Expires: 7200
Content-Length: 0
Since the Proxy is now aware of Alice's registration, it is possible for
the Proxy to subscribe to Alice's debug configuration now. Alice then
subscribes to her debug configuration (5)
SUBSCRIBE sip:alice@atlanta.com SIP/2.0
Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds7
From: sip:alice@atlanta.com;tag=123aa9
To: sip:s1.atlanta.com
Call-ID: 9987@u1.atlanta.com
CSeq: 9887 SUBSCRIBE
Contact: sip:u1.atlanta.com
Event: debug
Max-Forwards: 70
Accept: application/debuginfo+xml
The Registrar (which is acting as the notifier for the debug event
package) generates a 200 OK to the SUBSCRIBE (6):
200 OK Registrar -> Alice
SIP/2.0 200 OK
Via: SIP/2.0/UDP s1.atlanta.com;branch=z9hG4bKnashds7
;received=192.0.2.1
From: sip:alice@atlanta.com;tag=123aa9
To: sip:s1.atlanta.com;tag=xyzygg
Dawes & Chew Expires May 2, 2009 [Page 17]
Internet-Draft SIP Debugging Event October 2008
Call-ID: 9987@u1.atlanta.com
CSeq: 9987 SUBSCRIBE
Contact: sip:s1.atlanta.com
Expires: 3600
The registrar then generates a notification (7) with the current
debugging configuration information for the address of record
"alice@atlanta.com".
NOTIFY Registrar -> Alice
NOTIFY sip:u1.atlanta.com SIP/2.0
Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnasaii
From: sip:r1.atlanta.com;tag=xyzygg
To: sip:alice@atlanta.com;tag=123aa9
Call-ID: 9987@u1.atlanta.com
CSeq: 1288 NOTIFY
Contact: sip:r1.atlanta.com
Event: debug
Max-Forwards: 70
Content-Type: application/debuginfo+xml
Content-Length: ...
<?xml version="1.0"?>
<debuginfo xmlns="urn:ietf:params:xml:ns:debuginfo"
version="0" state="full">
<debugconfig aor="alice@atlanta.com">
<session id="r03">
<start-trigger>
<method>INVITE</method>
<from>alice@atlanta.com</from>
</start-trigger>
<stop-trigger>
<time-period>P7M30S</time-period>
</stop-trigger>
<control>
<trace-depth>minimum</trace-depth>
<debug-id>1A346D</debug-id>
</control>
</session>
</debugconfig>
</debuginfo>
NOTE: If multiple sessions are to be debugged, then multiple
<session></session> elements are included in the XML, each one with a
different debug-id attribute.
Alice's user agent responds to the NOTIFY request (8):
200 OK Alice -> Registrar
Dawes & Chew Expires May 2, 2009 [Page 18]
Internet-Draft SIP Debugging Event October 2008
SIP/2.0 200 OK
Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnashds7
;received=192.0.2.1
From: sip:r1.atlanta.com;tag=xyzygg
To: sip:alice@atlanta.com;tag=123aa9
Call-ID: 9987@s1.atlanta.com
CSeq: 1288 NOTIFY
Contact: sip:u1.atlanta.com
Typically, proxy p1.atlanta.com will already be subscribed to the debug
event package for sip:alice@atlanta.com. If not, proxy p1.atlanta.com
subscribes to the debug configuration for Alice (9):
SUBSCRIBE sip:alice@atlanta.com SIP/2.0
Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds7
From: sip:p1.atlanta.com;tag=123aa9
To: sip:alice@atlanta.com
Call-ID: 9987@p1.atlanta.com
CSeq: 9887 SUBSCRIBE
Contact: sip:p1.atlanta.com
Event: debug
Max-Forwards: 70
Accept: application/debuginfo+xml
The registrar (which is acting as the notifier for the debugging event
package) generates a 200 OK to the SUBSCRIBE (10):
SIP/2.0 200 OK
Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds7
;received=192.0.2.1
From: sip:p1.atlanta.com;tag=123aa9
To: sip:alice@atlanta.com;tag=xyzygg
Call-ID: 9987@p1.example.com
CSeq: 9987 SUBSCRIBE
Contact: sip:r1.atlanta.com
Expires: 3600
The registrar then generates a notification to the proxy with debugging
configuration for the proxy (1):
NOTIFY sip:p1.atlanta.com SIP/2.0
Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnasaii
From: sip:p1.atlanta.com;tag=123aa9
To: sip:alice@atlanta.com;tag=xyzygg
Call-ID: 9987@p1.example.com
CSeq: 1288 NOTIFY
Contact: sip:r1.atlanta.com
Dawes & Chew Expires May 2, 2009 [Page 19]
Internet-Draft SIP Debugging Event October 2008
Event: debug
Max-Forwards: 70
Content-Type: application/debuginfo+xml
Content-Length:
<?xml version="1.0"?>
<debuginfo xmlns="urn:ietf:params:xml:ns:debuginfo"
version="0" state="full">
<debugconfig aor="alice@atlanta.com">
<session id="r03">
<start-trigger>
<debug-id>1A346D</debug-id>
<from>alice@atlanta.com</from>
</start-trigger>
<stop-trigger>
<time-period>P7M30S</time-period>
</stop-trigger>
<control>
<trace-depth>minimum</trace-depth>
</control>
</session>
</debugconfig>
</debuginfo>
The XML documents for the user agent and the proxy may be different. In
this example, the value in the <debug-d>.element is identical for
the user agent and the proxy, but for the proxy it is part of the start
trigger event, whereas for the user agent it is control information
6.2. Incoming session
In order to log signalling for the incoming session shown below, it
is necessary to configure debugging on the registrar, proxy, and user
agent. The P-Debug-ID private header shown in the figure below is
defined in draft-dawes-sipping-debug-id
[draft-dawes-sipping-debug-id]
Dawes & Chew Expires May 2, 2009 [Page 20]
Internet-Draft SIP Debugging Event October 2008
User Proxy Registrar
u1.atlanta.com p1.atlanta.com r1.atlanta.com
| | |(1) INVITE
| | |<--------------
| |(2) INVITE |
| | P-Debug-ID:BB947A |
| |<------------------|
|(3) INVITE | |
| P-Debug-ID:BB947A | |
|<------------------| |
| | |
|(4) 200 OK | |
| P-Debug-ID:BB947A | |
|------------------------------------------------------>
| | |
The registrar r1.atlanta.com is triggered to begin logging signalling
by a start trigger event of the INVITE method and the value
alice@atlanta.com in the To: header field. The debugging
configuration in the registrar is shown below.
<?xml version="1.0"?>
<debuginfo xmlns="urn:ietf:params:xml:ns:debuginfo"
version="0" state="full">
<debugconfig aor="alice@atlanta.com">
<session id="r03">
<start-trigger>
<method>INVITE</method>
<to>alice@atlanta.com</to>
</start-trigger>
<stop-trigger>
<reason>dialog-established</reason>
</stop-trigger>
<control>
<trace-depth>minimum</trace-depth>
<debug-id>BB947A</debug-id>
</control>
</session>
</debugconfig>
</debuginfo>
The registrar detects an INVITE request with "alice@atlanta.com" in
the To: header field. The registrar therefore starts logging and
adds a P-Debug-ID header field containing the value in the
Dawes & Chew Expires May 2, 2009 [Page 21]
Internet-Draft SIP Debugging Event October 2008
<debug-id/> element in its debugging configuration.The registrar then
forwards the request.
The debugging configuration in the proxy is shown below.
<?xml version="1.0"?>
<debuginfo xmlns="urn:ietf:params:xml:ns:debuginfo"
version="0" state="full">
<debugconfig aor="alice@atlanta.com">
<session id="r03">
<start-trigger>
<debug-id>BB947A</debug-id>
<to>alice@atlanta.com</to>
</start-trigger>
<stop-trigger>
<reason>dialog-established</reason>
</stop-trigger>
<control>
<trace-depth>minimum</trace-depth>
</control>
</session>
</debugconfig>
</debuginfo>
The request arriving at the proxy matches the values configured in
its <start-trigger> element: a P-Debug-ID header containing the
configured value and "alice@atlanta.com" in the To: header field.
The proxy therefore starts logging and forwards the request.
The User Agent has the same <start-trigger> element as the proxy and
therefore starts logging. The user agent copies the P-Debug-ID
header field into the 200 OK response.
The User Agent, proxy and registrar all have the same <stop-trigger>
element, and logging will stop as the 200 OK passes each entity,
thereby establishing the dialog.
6.3. Outgoing session
In order to log signalling for the outgoing session shown below, it
is necessary to configure debugging on the registrar, proxy, and user
agent.
Dawes & Chew Expires May 2, 2009 [Page 22]
Internet-Draft SIP Debugging Event October 2008
User Proxy Registrar
u1.atlanta.com p1.atlanta.com r1.atlanta.com
|(1) MESSAGE | |
| P-Debug-ID:9E2836 | |
|------------------>| |
| |(2) MESSAGE |
| | P-Debug-ID:9E2836 |
| |------------------>|
| | |(3) MESSAGE
| | |P-Debug-ID:9E2836
| | |------------->
| | |
|(4) 200 OK | |
| P-Debug-ID:9E2836 | |
|<----------------------------------------------------
| | |
Alice sends a MESSAGE request that is debugged:
MESSAGE sip:bob@biloxi.com SIP/2.0
Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8
From: sip:alice@atlanta.com;tag=123aa10
To: sip:bob@biloxi.com
P-Preferred-Identity: alice@atlanta.com
Call-ID: 9901@r1.atlanta.com
CSeq: 82779 MESSAGE
Max-Forwards: 70
P-Debug-ID: 9E2836
Content-Type: text/plain
Content-Length: ...
MESSAGE sip:bob@biloxi.com SIP/2.0
Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds8
Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8
From: sip:alice@atlanta.com;tag=123aa10
To: sip:bob@biloxi.com
P-Asserted-Identity: alice@atlanta.com
Call-ID: 9901@nms1.atlanta.com
CSeq: 82779 MESSAGE
Max-Forwards: 69
P-Debug-ID: 9E2836
Content-Type: text/plain
Content-Length: ...
Dawes & Chew Expires May 2, 2009 [Page 23]
Internet-Draft SIP Debugging Event October 2008
MESSAGE sip:bob@biloxi.com SIP/2.0
Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnashds8
Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds8
Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8
From: sip:alice@atlanta.com;tag=123aa10
To: sip:bob@biloxi.com
P-Asserted-Identity: alice@atlanta.com
Call-ID: 9901@nms1.atlanta.com
CSeq: 82779 MESSAGE
Max-Forwards: 68
P-Debug-ID: 9E2836
Content-Type: text/plain
Content-Length: ...
200 OK
SIP/2.0 200 OK
Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8
From: sip:alice@atlanta.com;tag=123aa10
To: sip:bob@biloxi.com;tag=1928301774
Call-ID: 9987@u1.atlanta.com
CSeq: 9987 MESSAGE
P-Debug-ID: 9E2836
Content-Length:0
The user agent u1.atlanta.com is triggered to begin logging
signalling by a start trigger event of the MESSAGE method and the
value alice@atlanta.com in the From: header field. The <start-
trigger> element in the user agent debugging configuration is shown
below.
Dawes & Chew Expires May 2, 2009 [Page 24]
Internet-Draft SIP Debugging Event October 2008
<?xml version="1.0"?>
<debuginfo xmlns="urn:ietf:params:xml:ns:debuginfo"
version="0" state="full">
<debugconfig aor="alice@atlanta.com">
<session id="r03">
<start-trigger>
<method>MESSAGE</method>
<from>alice@atlanta.com</from>
</start-trigger>
<stop-trigger>
<time-period>P7M30S</time-period>
</stop-trigger>
<control>
<trace-depth>minimum</trace-depth>
<debug-id>9E2836</debug-id>
</control>
</session>
</debugconfig>
</debuginfo>
The user agent detects the configured start trigger event when it
originates a MESSAGE request with "alice@atlanta.com" in the From:
header field. The user agent therefore starts logging and adds a
P-Debug-ID header field containing the value in the <debug-id/>
element in its debugging configuration <control/> element. The user
agent then forwards the request.
The debugging configuration in the proxy is shown below.
<?xml version="1.0"?>
<debuginfo xmlns="urn:ietf:params:xml:ns:debuginfo"
version="0" state="full">
<debugconfig aor="alice@atlanta.com">
<session id="r03">
<start-trigger>
<debug-id>P7M30S</debug-id>
<from>alice@atlanta.com</from>
</start-trigger>
<stop-trigger>
<time-period>P7M30S</time-period>
</stop-trigger>
<control>
<trace-depth>minimum</trace-depth>
</control>
</session>
</debugconfig>
</debuginfo>
Dawes & Chew Expires May 2, 2009 [Page 25]
Internet-Draft SIP Debugging Event October 2008
The request arriving at the proxy matches the values configured in
its <start-trigger> element: a P-Debug-ID header containing the
configured value and "alice@atlanta.com" in the From: header field.
The proxy therefore starts logging and forwards the request.
The registrar has the same <start-trigger> element as the proxy and
therefore starts logging and forwards the request.
The User Agent, proxy and registrar all have the same <stop-trigger>
element, and logging will stop after a time duration of 7 minutes 30
seconds.
6.4. Prompting a user agent to subscribe to debug-event
Troubleshooting and regression testing will be quite rare events and
only involve specific entities, therefore it is inefficient for all
user agents to be subscribed to the debug event package all the time.
A user agent can be prompted to subscribe to its own debug event
package by an empty P-Debug-ID header field in a 200 OK response to a
REGISTER request. The signalling is shown below.
User Proxy Registrar
u1.atlanta.com p1.atlanta.com r1.atlanta.com
|(1) REGISTER | |
|------------------>| |
| |(2) REGISTER |
| |------------------>|
| | |
|(3) 200 OK | |
| P-Debug-ID: | |
|<--------------------------------------|
| | |
| | |
|(4)SUBSCRIBE | |
| Event:debug | |
|-------------------------------------->|
7. Acknowledgements
This template was derived from an initial version written by Pekka
Savola and contributed by him to the xml2rfc project.
Dawes & Chew Expires May 2, 2009 [Page 26]
Internet-Draft SIP Debugging Event October 2008
8. IANA Considerations
All drafts are required to have an IANA considerations section (see
the update of RFC 2434 [I-D.narten-iana-considerations-rfc2434bis]
for a guide). If the draft does not require IANA to do anything, the
section contains an explicit statement that this is the case (as
above). If there are no requirements for IANA, the section will be
removed during conversion into an RFC by the RFC Editor.
8.1. SIP Event Package Registration
Package name: debug
Type: package
Contact: Peter Dawes, peter.dawes@vodafone.com>
8.2. application/debuinfo+xml MIME Registration
MIME media type name: application
MIME subtype name: debuginfo+xml
Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml as
specified in RFC 3023 [8].
Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023 [8].
Security considerations: See Section 10 of RFC 3023 [8] and Section 7
of this specification.
Interoperability considerations: none.
Published specification: This document.
Applications which use this media type: This document type is being
used in notifications to provide SIP entities with configuration data
for debugging SIP signaling.
Additional Information:
Magic Number: None
File Extension: .rif or .xml
Dawes & Chew Expires May 2, 2009 [Page 27]
Internet-Draft SIP Debugging Event October 2008
Macintosh file type code: "TEXT"
Personal and email address for further information: Peter Dawes,
peter.dawes@vodafone.com
Intended usage: COMMON
Author/Change controller: The IETF.
9. Security Considerations
All drafts are required to have a security considerations section.
See RFC 3552 [RFC3552] for a guide.
10. References
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997.
[RFC2648] Moats, R., "A URN Namespace for IETF Documents", RFC 2648,
August 1999.
[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.
[RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific
Event Notification", RFC 3265, June 2002.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[W3C.xml-c14n]
Boyer, J., "Canonical XML Version 1.0", W3C
Recommendation xpath, March 2001,
<http://www.w3.org/TR/xml-c14n>.
[draft-dawes-sipping-debug-id]
Dawes, P., "Private Extension to the Session Initiation
Protocol (SIP) for Debugging", 2008.
Dawes & Chew Expires May 2, 2009 [Page 28]
Internet-Draft SIP Debugging Event October 2008
10.2. Informative References
[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.
[RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
June 1999.
[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.
Authors' Addresses
Peter Dawes
Vodafone
Newbury, Berkshire RG14 2FN
UK
Phone: +44 7717 275009
Email: peter.dawes@vodafone.com
Kar Ann Chew (editor)
Vodafone Group
The Connection
Newbury, Berkshire RG14 2FN
UK
Phone:
Email: karann.chew@vodafone.com
Dawes & Chew Expires May 2, 2009 [Page 29]
Internet-Draft SIP Debugging Event October 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Dawes & Chew Expires May 2, 2009 [Page 30]