idnits 2.17.1 draft-dawes-sipping-debug-event-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1323. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1334. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1341. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1347. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 23 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 925 has weird spacing: '...nta.com r1....' == Line 1013 has weird spacing: '...nta.com r1....' == Line 1157 has weird spacing: '...nta.com r1....' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 29, 2008) is 5658 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '8' on line 1209 == Unused Reference: 'RFC2629' is defined on line 1279, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2141 (Obsoleted by RFC 8141) ** Obsolete normative reference: RFC 3265 (Obsoleted by RFC 6665) -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force P. Dawes 3 Internet-Draft Vodafone 4 Intended status: Informational K. Chew, Ed. 5 Expires: May 2, 2009 Vodafone Group 6 October 29, 2008 8 A Session Initiation Protocol (SIP) Event Package for Debugging 9 draft-dawes-sipping-debug-event-01 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on May 2, 2009. 36 Abstract 38 This document defines a Session Initiation Protocol (SIP) event 39 package for debugging. An entity that subscribes to this event 40 package for an address of record receives configuration data that 41 controls logging of SIP signalling for that address of record, for 42 example when to begin an end logging. 44 Table of Contents 46 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 47 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 48 2. Usage Scenarios . . . . . . . . . . . . . . . . . . . . . . . 3 49 3. Principle of Operation . . . . . . . . . . . . . . . . . . . . 4 50 3.1. Minimum debugging configuration . . . . . . . . . . . . . 5 51 4. Package Definition . . . . . . . . . . . . . . . . . . . . . . 5 52 4.1. Event Package Name . . . . . . . . . . . . . . . . . . . . 5 53 4.2. Event Package Parameters . . . . . . . . . . . . . . . . . 5 54 4.3. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 5 55 4.4. Subscription Duration . . . . . . . . . . . . . . . . . . 6 56 4.5. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 6 57 4.6. Notifier Processing of SUBSCRIBE Requests . . . . . . . . 7 58 4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 7 59 4.7.1. The Debug Configuration State Machine . . . . . . . . 8 60 4.7.2. Applying the State Machine . . . . . . . . . . . . . . 9 61 4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 9 62 4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 9 63 4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 9 64 4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 10 65 5. Debug Configuration Information . . . . . . . . . . . . . . . 10 66 5.1. Structure of Debug Configuration . . . . . . . . . . . . . 10 67 5.2. Computing Debug Configuration from the Document . . . . . 11 68 5.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 5.4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 13 70 6. Example Call Flows . . . . . . . . . . . . . . . . . . . . . . 16 71 6.1. Subscription to debug-event . . . . . . . . . . . . . . . 16 72 6.2. Incoming session . . . . . . . . . . . . . . . . . . . . . 20 73 6.3. Outgoing session . . . . . . . . . . . . . . . . . . . . . 22 74 6.4. Prompting a user agent to subscribe to debug-event . . . . 26 75 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 26 76 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 77 8.1. SIP Event Package Registration . . . . . . . . . . . . . . 27 78 8.2. application/debuinfo+xml MIME Registration . . . . . . . . 27 79 9. Security Considerations . . . . . . . . . . . . . . . . . . . 28 80 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 81 10.1. Normative References . . . . . . . . . . . . . . . . . . . 28 82 10.2. Informative References . . . . . . . . . . . . . . . . . . 29 83 Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 29 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 85 Intellectual Property and Copyright Statements . . . . . . . . . . 30 87 1. Introduction 89 The Session Initiation Protocol (SIP) RFC 3261 [RFC3261] provides all 90 of the functions needed for the establishment and maintenance of 91 communications sessions between users. Registration establishes an 92 address at which a user can be contacted to set up communication 93 sessions. 95 It is possible for that session setup might fail, for example due to 96 a network fault or mis-configuration, or that poor network 97 performance causes long setup delays. In such circumstances, it is 98 useful to be able to analyse SIP requests and responses end-to-end 99 from the UAC to the UAS, which entails logging of requests and 100 responses by entities along the signalling route. 102 Such logging will be occasional, specific to an address of record, 103 and specific to the SIP entities traversed on the route to and from 104 that address of record. Also, it must be possible to collect logs of 105 signalling taken from different SIP entities and identify that they 106 belong to the same SIP session. These requirements suggest two 107 properties of a solution; it must be possible to configure any SIP 108 entity on-the-fly to log requests and responses for a particular 109 address of record, and configuration data must include an identifier 110 that will allow logs from separate entities to be identified as 111 belonging to the same session. Also, for operational simplicity, it 112 is desirable to have a single logical point of control. An event 113 package allows entities to subscribe and unsubscribe as needed, is 114 organized by address of record, and can be hosted at a single point 115 of control. 117 This document describes an event package that enables SIP UAs, 118 proxies and B2BUAs to be dynamically configured to log SIP requests 119 and responses. 121 Logged signalling is identified across different entities with the 122 help of a private header field defined in 123 draft-dawes-sipping-debug-id [draft-dawes-sipping-debug-id] 125 1.1. Requirements Language 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 129 document are to be interpreted as described in RFC 2119 [RFC2119]. 131 2. Usage Scenarios 133 This event package supplies configuration for two broad applications, 134 debugging user reported faults and regression testing of a SIP 135 network, as described in draft-dawes-sipping-debug-id 136 [draft-dawes-sipping-debug-id]. 138 3. Principle of Operation 140 Debugging can be understood by the simple state machine below, which 141 applies to any SIP UA or Proxy. 143 +------------+ 144 | | 145 | Inactive | 146 | | 147 +------------+ 148 ^ | 149 | | Supply debugging 150 Delete debugging | | configuration 151 configuration | | 152 | | 153 | V 154 +------------+ 155 | | 156 | Active | 157 | | 158 +------------+ 159 ^ | 160 | | 161 | | Start trigger 162 Stop trigger | | event 163 event | | 164 | | 165 | V 166 +------------+ 167 | | 168 | Logging | 169 | | 170 +------------+ 172 Figure 1: Debugging State Machine 174 The debugging configuration is an XML document described by the 175 schema in this document. Supply of configuration causes debugging 176 state to change from Inactive to Active. Configuration defines one 177 or more start trigger events, which cause debugging state to change 178 from Active to Logging when they are detected. A start trigger event 179 is typically a user identity, in the SIP From: or To: header field, 180 plus a 6-digit hexadecimal reference number. Similarly, 181 configuration contains one or more stop triggering events, which 182 cause debugging state to change from Logging to Active when they are 183 detected. A stop trigger event is typically the expiry of a timer or 184 the end of a SIP session. 186 3.1. Minimum debugging configuration 188 In order to uniquely identify signalling logged at different entities 189 as belonging to the same session, the minimum set of debugging 190 configuration is a "aor" attribute and a element. 192 4. Package Definition 194 This section fills in the details needed to specify an event package 195 as defined in Section 4.4 of RFC 3265 [RFC3265]. 197 4.1. Event Package Name 199 The SIP Events specification requires package definitions to specify 200 the name of their package or template-package. 202 The name of this package is "debug". As specified in RFC 3265 203 [RFC3265], this value appears in the Event header present in 204 SUBSCRIBE and NOTIFY requests. 206 Example: 208 Event: debug 210 4.2. Event Package Parameters 212 The SIP Events specification requires package and template-package 213 definitions to specify any package specific parameters of the Event 214 header that are used by it. 216 No package specific Event header parameters are defined for this 217 event package. 219 4.3. SUBSCRIBE Bodies 221 The SIP Events specification requires package or template-package 222 definitions to define the usage, if any, of bodies in SUBSCRIBE 223 requests. 225 A SUBSCRIBE for debug events MAY contain a body. This body would 226 serve the purpose of filtering the subscription. The definition of 227 such a body is outside the scope of this specification. 229 A SUBSCRIBE for the debug package MAY be sent without a body. This 230 implies that the default registration filtering policy has been 231 requested. The default policy is: 233 o Notifications are generated every time there is any change in the 234 state of any part of the debug configuration for the resource 235 being subscribed to. Those notifications only contain information 236 on the configuration elements whose state has changed. 238 o Notifications triggered from a SUBSCRIBE contain full state (all 239 debug configuration bound to the address-of-record). Of course, 240 the server can apply any policy it likes to the subscription. 242 4.4. Subscription Duration 244 The SIP Events specification requires package definitions to define a 245 default value for subscription durations, and to discuss reasonable 246 choices for durations when they are explicitly specified. 248 Debug configuration state changes as the need for debugging arises, 249 either to investigate a user-reported fault or perform regression 250 testing. The debug configuration for a user or users is updated by 251 administrative means. 253 Since configuration of debugging will be followed quickly by the 254 debugging itself, the default duration of subscriptions to debug 255 configuration is 43200 seconds. Of course, clients MAY include an 256 Expires header in the SUBSCRIBE request asking for a different 257 duration. 259 4.5. NOTIFY Bodies 261 The SIP Events specification requires package definitions to describe 262 the allowed set of body types in NOTIFY requests, and to specify the 263 default value to be used when there is no Accept header in the 264 SUBSCRIBE request. 266 The body of a notification of a change in debug configuration state 267 contains a debug configuration information document. This document 268 describes some or all of the debugging configuration associated with 269 a particular address-of-record. All subscribers and notifiers MUST 270 support the "application/debuginfo+xml" format described in Section 271 5. The subscribe request MAY contain an Accept header field. If no 272 such header field is present, it has a default value of "application/ 273 debuginfo+xml". If the header field is present, it MUST include 274 "application/debuginfo+xml", and MAY include any other types capable 275 of representing debugging information. 277 Of course, the notifications generated by the server MUST be in one 278 of the formats specified in the Accept header field in the SUBSCRIBE 279 request. 281 4.6. Notifier Processing of SUBSCRIBE Requests 283 The SIP Events framework specifies that packages should define any 284 package-specific processing of SUBSCRIBE requests at a notifier, 285 specifically with regards to authentication and authorization. 287 Debug configuration can be sensitive information. Therefore, all 288 subscriptions to it SHOULD be authenticated and authorized before 289 approval. Authentication MAY be performed using any of the 290 techniques available through SIP, including digest, S/MIME, TLS or 291 other transport specific mechanisms RFC3261 [RFC3261]. Authorization 292 policy is at the discretion of the administrator, as always. 293 However, a few recommendations can be made. 295 It is RECOMMENDED that a user be allowed to subscribe to their own 296 debug configuration state. Debugging relies upon a user agent 297 including a network-provided debug-id, and this is most easily 298 provided by allowing the user to subscribe to debug-event. We also 299 anticipate that applications and automata will frequently be 300 subscribers to the debug configuration state. In those cases, 301 authorization policy will typically be provided ahead of time. 303 4.7. Notifier Generation of NOTIFY Requests 305 The SIP Event framework requests that packages specify the conditions 306 under which notifications are sent for that package, and how such 307 notifications are constructed. 309 To determine when a notifier should send notifications of changes in 310 debug configuration state, we define a finite state machine (FSM) 311 that represents the state of debug configuration for a particular 312 address-of-record. 314 Transitions in this state machine MAY result in the generation of 315 notifications. These notifications will carry information on the new 316 state and the event which triggered the state change. It is 317 important to note that this FSM is just a model of the debug 318 configuration state machinery maintained by a server. An 319 implementation would map its own state machines to this one in an 320 implementation-specific manner. 322 4.7.1. The Debug Configuration State Machine 324 The underlying state machine for debug configuration is shown in the 325 figure below. The machine is very simple. An instance of this 326 machine is associated with each address-of-record. When there is no 327 debugging configuration defined for an address-of-record, the state 328 machine is in the init state. It is important to note that this 329 state machine exists, and is well-defined, for each address-of-record 330 in the domain, even if there is no debug configuration defined for 331 it. This allows a user agent to subscribe to an address-of-record, 332 and learn that there is no debug configuration for it. When debug 333 configuration is added for that address-of-record, the state machine 334 moves from init to active. 336 +------------+ 337 | | 338 | Init | 339 | | 340 +------------+ 341 | 342 V 343 +------------+ 344 | | 345 | Active | 346 | | 347 +------------+ 348 | 349 V 350 +------------+ 351 | | 352 | Terminated | 353 | | 354 +------------+ 356 Figure 2: Debug Congfiguration State Machine 358 As long as there is debugging configuration for the address-of- 359 record, the state machine remains in the active state. When the last 360 debug configuration expires or is removed, the debug configuration 361 transitions to terminated. From there, it immediately transitions 362 back to the init state. This transition is invisible, in that it 363 MUST NOT ever be reported to a subscriber in a NOTIFY request. 365 This allows for an implementation optimization whereby the registrar 366 can destroy the objects associated with the debug configuration state 367 machine once it enters the terminated state and a NOTIFY has been 368 sent. Instead, the registrar can assume that, if the objects for 369 that state machine no longer exist, the state machine is in the init 370 state. 372 4.7.2. Applying the State Machine 374 The server MAY generate a notification to subscribers when any event 375 occurs in the debug configuration state machine, except for the 376 transition from terminated to init. As noted above, a notification 377 MUST NOT be sent in this case. For other transitions, whether the 378 server sends a notification or not is policy dependent. However, 379 several guidelines are defined. 381 4.8. Subscriber Processing of NOTIFY Requests 383 The SIP Events framework expects packages to specify how a subscriber 384 processes NOTIFY requests in any package specific ways, and in 385 particular, how it uses the NOTIFY requests to construct a coherent 386 view of the state of the subscribed resource. For debug 387 configuration, the NOTIFY will contain all information for the 388 address of record whose configuration has changed. 390 4.9. Handling of Forked Requests 392 The SIP Events framework mandates that packages indicate whether or 393 not forked SUBSCRIBE requests can install multiple subscriptions. 395 Debug configuration is normally stored in some repository (whether it 396 be co-located with a proxy/registrar or in a separate database). As 397 such, there is usually a single place where the debug configuration 398 information for a particular address-of-record is resident. This 399 implies that a subscription for this information is readily handled 400 by a single element with access to this repository. There is, 401 therefore, no compelling need for a subscription to debug 402 configuration information to fork. As a result, a subscriber MUST 403 NOT create multiple dialogs as a result of a single subscription 404 request. The required processing to guarantee that only a single 405 dialog is established is described in Section 4.4.9 of the SIP Events 406 framework RFC3265 [RFC3265]. 408 4.10. Rate of Notifications 410 The SIP Events framework mandates that packages define a maximum rate 411 of notifications for their package. 413 For reasons of congestion control, it is important that the rate of 414 notifications not become excessive. A change of debug configuration 415 is usually followed by a session to be debugged, which takes 416 significant time. Even during regression testing, in which a number 417 of consecutive sessions might be debugged, notifications are 418 punctuated by the sessions or standalone transactions to be debugged. 419 It is therefore RECOMMENDED that the server not generate 420 notifications for a single subscriber at a rate faster than once 421 every 60 seconds. 423 4.11. State Agents 425 The SIP Events framework asks packages to consider the role of state 426 agents in their design. 428 Debug configuration information is passed from a network management 429 server to the SIP registrar, which hosts the debug configuration 430 event package. The details of how debug configuration information is 431 passed to the SIP registrar is outside the scope of this document. 433 5. Debug Configuration Information 435 5.1. Structure of Debug Configuration 437 Debug configuration is an XML document Canonical XML Version 1.0 438 [W3C.xml-c14n] that MUST be well-formed and SHOULD be valid. Debug 439 configuration documents MUST be based on XML 1.0 and MUST be encoded 440 using UTF-8. This specification makes use of XML namespaces for 441 identifying debug configuration documents and document fragments. 442 The namespace URI for elements defined by this specification is a URN 443 RFC 2141 [RFC2141], using the namespace identifier 'ietf' defined by 444 RFC 2648 [RFC2648] and extended by RFC 3688 [RFC3688];. This URN is: 446 urn:ietf:params:xml:ns:debuginfo 448 A debug configuration document begins with the root element tag 449 "debuginfo". It consists of any number of "debugconfig" sub- 450 elements, each of which contains descriptions of sessions or 451 standalone transactions that are to be debugged for a particular 452 address-of-record. The debug configuration information for a 453 particular address-of-record MUST be contained within a single 454 "debuginfo" element; it cannot be spread across multiple "debuginfo" 455 elements within a document. Other elements from different namespaces 456 MAY be present for the purposes of extensibility; elements or 457 attributes from unknown namespaces MUST be ignored. There are two 458 attributes associated with the "debuginfo" element, both of which 459 MUST be present: 461 version: This attribute allows the recipient of debug 462 configuration documents to properly order them. Versions 463 start at 0, and increment by one for each new document sent 464 to a subscriber. Versions are scoped within a 465 subscription. Versions MUST be representable using a 32 466 bit integer. 468 state: This attribute indicates whether the document 469 contains the full registration state, or whether it 470 contains only information on those debug configurations 471 which have changed since the previous document (partial). 473 Note that the document format explicitly allows for conveying 474 information on multiple addresses-of-record. This enables 475 subscriptions to groups of debug configurations, where such a group 476 is identified by some kind of URI. For example, a domain might 477 define sip:allusers@example.com as a resource that can be subscribed 478 to and generates notifications when the state of any address-of- 479 record in the domain changes. 481 The "debugconfig" element has a list of any number of "session" sub- 482 elements, each of which contains information on a single session or 483 standalone transaction. Other elements from different namespaces MAY 484 be present for the purposes of extensibility; elements or attributes 485 from unknown namespaces MUST be ignored. There are three attributes 486 associated with the "debugconfig" element, all of which MUST be 487 present: 489 aor: The aor attribute contains a URI which is the address- 490 of-record this registration refers to. 492 state: The state attribute indicates the state of the debug 493 configuration. The valid values are "init", "active" and 494 "terminated". 496 The "session" element contains a "debug-id" element and a "start 497 trigger" element, "stop trigger" element, and "control" element. 498 Other elements from different namespaces MAY be present for the 499 purposes of extensibility; elements or attributes from unknown 500 namespaces MUST be ignored. There is one attribute associated with 501 the "session" element which MUST be present: 503 id: The "id" attribute identifies this session. It MUST be 504 unique amongst all other id attributes present in other 505 debug configuration elements conveyed to the subscriber 506 within the scope of their subscription. 508 5.2. Computing Debug Configuration from the Document 510 Typically, the NOTIFY for debug configuration information will only 511 contain information about those sessions whose state has changed. To 512 construct a coherent view of the total state of all registrations, a 513 subscriber will need to combine NOTIFYs received over time. The 514 subscriber maintains a table for each debug configuration it receives 515 information for. Each debug configuration is uniquely identified by 516 the "aor" attribute in the "debug configuration" element. Each table 517 contains a row for each session in that debug configuration. Each 518 row is indexed by the unique id for that session. It is conveyed in 519 the "id" attribute of the "session" element. The tables are also 520 associated with a version number. The version number MUST be 521 initialized with the value of the "version" attribute from the 522 "debuginfo" element in the first document received. Each time a new 523 document is received, the value of the local version number, and the 524 "version" attribute in the new document, are compared. If the value 525 in the new document is one higher than the local version number, the 526 local version number is increased by one, and the document is 527 processed. If the value in the document is more than one higher than 528 the local version number, the local version number is set to the 529 value in the new document, the document is processed, and the 530 subscriber SHOULD generate a refresh request to trigger a full state 531 notification. If the value in the document is less than the local 532 version, the document is discarded without processing. 534 The processing of the document depends on whether it contains full or 535 partial state. If it contains full state, indicated by the value of 536 the "state" attribute in the "debuginfo" element, the contents of all 537 tables associated with this subscription are flushed. They are re- 538 populated from the document. A new table is created for each 539 "debugconfig" element, and a new row in each table is created for 540 each "session" element. If the debuginfo contains partial state, as 541 indicated by the value of the "state" attribute in the "debuginfo" 542 element, the document is used to update the existing tables. For 543 each "debugconfig" element, the subscriber checks to see if a table 544 exists for that debug configuration. This check is done by comparing 545 the value in the "aor" attribute of the "debugconfig" element with 546 the aor associated with the table. If a table doesn't exist for that 547 registration, one is created. For each "session" element in the 548 debug configuration, the subscriber checks to see whether a row 549 exists for that session. This check is done by comparing the ID in 550 the "id" attribute of the "session" element with the ID associated 551 with the row. If the session doesn't exist in the table, a row is 552 added, and its state is set to the information from that "session" 553 element. If the session does exist, its state is updated to be the 554 information from that "session" element. If a row is updated or 555 created, such that its state is now terminated, that entry MAY be 556 removed from the table at any time. 558 5.3. Example 560 The following is an example debug configuration information document: 562 563 565 566 567 568 1A346D 569 alice@atlanta.com 570 571 572 dialog-established 573 574 575 minimum 576 577 578 579 581 5.4. XML Schema 583 584 588 589 591 596 597 598 599 600 601 602 603 604 605 607 608 609 610 611 612 613 614 615 617 618 619 620 621 622 623 624 626 627 628 630 632 633 634 635 636 637 638 639 640 642 643 644 645 646 648 650 651 652 653 654 655 656 657 658 659 660 661 662 664 665 666 667 668 669 670 671 672 673 675 676 677 678 679 680 681 682 683 684 685 686 687 689 690 691 692 693 694 695 696 697 699 700 701 702 703 704 705 706 707 709 711 6. Example Call Flows 713 6.1. Subscription to debug-event 715 User Proxy Registrar 717 |(1) REGISTER | | 718 |------------------>| | 719 | |(2) REGISTER | 720 | |------------------>| 721 | |(3) 200 OK | 722 | |<------------------| 723 |(4) 200 OK | | 724 |<------------------| | 725 |(5) SUBSCRIBE | | 726 | Event:debug | | 727 |-------------------------------------->| 728 | |(6) 200 OK | 729 |<--------------------------------------| 730 | |(7) NOTIFY | 731 |<--------------------------------------| 732 |(8) 200 OK | | 733 |-------------------------------------->| 734 | | | 735 | |(9) SUBSCRIBE | 736 | |Event:debug | 737 | |------------------>| 738 | |(10) 200 OK | 739 | |<------------------| 740 | |(11) NOTIFY | 741 | |<------------------| 742 | |(12) 200 OK | 743 | |------------------>| 745 Alice registers (1) and (2) 746 REGISTER sip:r1.atlanta.com SIP/2.0 747 Via: SIP/2.0/UDP u1.atlanta.com:5060;branch=z9hG4bKnashds7 748 Max-Forwards: 70 749 To: Alice 750 From: Alice ;tag=456248 751 Call-ID: 843817637684230@998sdasdh09 752 CSeq: 1826 REGISTER 753 Contact: 754 Expires: 7200 755 Content-Length: 0 757 Registration is successful (3) and (4) 758 SIP/2.0 200 OK 759 Via: SIP/2.0/UDP u1.atlanta.com:5060;branch=z9hG4bKnashds7 760 ;received=192.0.2.4 761 To: Alice ;tag=2493k59kd 762 From: Alice ;tag=456248 763 Call-ID: 843817637684230@998sdasdh09 764 CSeq: 1826 REGISTER 765 Contact: 766 Expires: 7200 767 Content-Length: 0 769 Since the Proxy is now aware of Alice's registration, it is possible for 770 the Proxy to subscribe to Alice's debug configuration now. Alice then 771 subscribes to her debug configuration (5) 773 SUBSCRIBE sip:alice@atlanta.com SIP/2.0 774 Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds7 775 From: sip:alice@atlanta.com;tag=123aa9 776 To: sip:s1.atlanta.com 777 Call-ID: 9987@u1.atlanta.com 778 CSeq: 9887 SUBSCRIBE 779 Contact: sip:u1.atlanta.com 780 Event: debug 781 Max-Forwards: 70 782 Accept: application/debuginfo+xml 784 The Registrar (which is acting as the notifier for the debug event 785 package) generates a 200 OK to the SUBSCRIBE (6): 787 200 OK Registrar -> Alice 788 SIP/2.0 200 OK 789 Via: SIP/2.0/UDP s1.atlanta.com;branch=z9hG4bKnashds7 790 ;received=192.0.2.1 791 From: sip:alice@atlanta.com;tag=123aa9 792 To: sip:s1.atlanta.com;tag=xyzygg 793 Call-ID: 9987@u1.atlanta.com 794 CSeq: 9987 SUBSCRIBE 795 Contact: sip:s1.atlanta.com 796 Expires: 3600 798 The registrar then generates a notification (7) with the current 799 debugging configuration information for the address of record 800 "alice@atlanta.com". 802 NOTIFY Registrar -> Alice 803 NOTIFY sip:u1.atlanta.com SIP/2.0 804 Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnasaii 805 From: sip:r1.atlanta.com;tag=xyzygg 806 To: sip:alice@atlanta.com;tag=123aa9 807 Call-ID: 9987@u1.atlanta.com 808 CSeq: 1288 NOTIFY 809 Contact: sip:r1.atlanta.com 810 Event: debug 811 Max-Forwards: 70 812 Content-Type: application/debuginfo+xml 813 Content-Length: ... 815 816 818 819 820 821 INVITE 822 alice@atlanta.com 823 824 825 P7M30S 826 827 828 minimum 829 1A346D 830 831 832 833 835 NOTE: If multiple sessions are to be debugged, then multiple 836 elements are included in the XML, each one with a 837 different debug-id attribute. 839 Alice's user agent responds to the NOTIFY request (8): 840 200 OK Alice -> Registrar 841 SIP/2.0 200 OK 842 Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnashds7 843 ;received=192.0.2.1 844 From: sip:r1.atlanta.com;tag=xyzygg 845 To: sip:alice@atlanta.com;tag=123aa9 846 Call-ID: 9987@s1.atlanta.com 847 CSeq: 1288 NOTIFY 848 Contact: sip:u1.atlanta.com 850 Typically, proxy p1.atlanta.com will already be subscribed to the debug 851 event package for sip:alice@atlanta.com. If not, proxy p1.atlanta.com 852 subscribes to the debug configuration for Alice (9): 854 SUBSCRIBE sip:alice@atlanta.com SIP/2.0 855 Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds7 856 From: sip:p1.atlanta.com;tag=123aa9 857 To: sip:alice@atlanta.com 858 Call-ID: 9987@p1.atlanta.com 859 CSeq: 9887 SUBSCRIBE 860 Contact: sip:p1.atlanta.com 861 Event: debug 862 Max-Forwards: 70 863 Accept: application/debuginfo+xml 865 The registrar (which is acting as the notifier for the debugging event 866 package) generates a 200 OK to the SUBSCRIBE (10): 868 SIP/2.0 200 OK 869 Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds7 870 ;received=192.0.2.1 871 From: sip:p1.atlanta.com;tag=123aa9 872 To: sip:alice@atlanta.com;tag=xyzygg 873 Call-ID: 9987@p1.example.com 874 CSeq: 9987 SUBSCRIBE 875 Contact: sip:r1.atlanta.com 876 Expires: 3600 878 The registrar then generates a notification to the proxy with debugging 879 configuration for the proxy (1): 881 NOTIFY sip:p1.atlanta.com SIP/2.0 882 Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnasaii 883 From: sip:p1.atlanta.com;tag=123aa9 884 To: sip:alice@atlanta.com;tag=xyzygg 885 Call-ID: 9987@p1.example.com 886 CSeq: 1288 NOTIFY 887 Contact: sip:r1.atlanta.com 888 Event: debug 889 Max-Forwards: 70 890 Content-Type: application/debuginfo+xml 891 Content-Length: 893 894 896 897 898 899 1A346D 900 alice@atlanta.com 901 902 903 P7M30S 904 905 906 minimum 907 908 909 910 912 The XML documents for the user agent and the proxy may be different. In 913 this example, the value in the <debug-d>.element is identical for 914 the user agent and the proxy, but for the proxy it is part of the start 915 trigger event, whereas for the user agent it is control information 917 6.2. Incoming session 919 In order to log signalling for the incoming session shown below, it 920 is necessary to configure debugging on the registrar, proxy, and user 921 agent. The P-Debug-ID private header shown in the figure below is 922 defined in draft-dawes-sipping-debug-id 923 [draft-dawes-sipping-debug-id] 924 User Proxy Registrar 925 u1.atlanta.com p1.atlanta.com r1.atlanta.com 927 | | |(1) INVITE 928 | | |<-------------- 929 | |(2) INVITE | 930 | | P-Debug-ID:BB947A | 931 | |<------------------| 932 |(3) INVITE | | 933 | P-Debug-ID:BB947A | | 934 |<------------------| | 935 | | | 936 |(4) 200 OK | | 937 | P-Debug-ID:BB947A | | 938 |------------------------------------------------------> 939 | | | 941 The registrar r1.atlanta.com is triggered to begin logging signalling 942 by a start trigger event of the INVITE method and the value 943 alice@atlanta.com in the To: header field. The debugging 944 configuration in the registrar is shown below. 946 947 949 950 951 952 INVITE 953 alice@atlanta.com 954 955 956 dialog-established 957 958 959 minimum 960 BB947A 961 962 963 964 966 The registrar detects an INVITE request with "alice@atlanta.com" in 967 the To: header field. The registrar therefore starts logging and 968 adds a P-Debug-ID header field containing the value in the 969 element in its debugging configuration.The registrar then 970 forwards the request. 972 The debugging configuration in the proxy is shown below. 974 975 977 978 979 980 BB947A 981 alice@atlanta.com 982 983 984 dialog-established 985 986 987 minimum 988 989 990 991 993 The request arriving at the proxy matches the values configured in 994 its element: a P-Debug-ID header containing the 995 configured value and "alice@atlanta.com" in the To: header field. 996 The proxy therefore starts logging and forwards the request. 998 The User Agent has the same element as the proxy and 999 therefore starts logging. The user agent copies the P-Debug-ID 1000 header field into the 200 OK response. 1002 The User Agent, proxy and registrar all have the same 1003 element, and logging will stop as the 200 OK passes each entity, 1004 thereby establishing the dialog. 1006 6.3. Outgoing session 1008 In order to log signalling for the outgoing session shown below, it 1009 is necessary to configure debugging on the registrar, proxy, and user 1010 agent. 1012 User Proxy Registrar 1013 u1.atlanta.com p1.atlanta.com r1.atlanta.com 1015 |(1) MESSAGE | | 1016 | P-Debug-ID:9E2836 | | 1017 |------------------>| | 1018 | |(2) MESSAGE | 1019 | | P-Debug-ID:9E2836 | 1020 | |------------------>| 1021 | | |(3) MESSAGE 1022 | | |P-Debug-ID:9E2836 1023 | | |-------------> 1024 | | | 1025 |(4) 200 OK | | 1026 | P-Debug-ID:9E2836 | | 1027 |<---------------------------------------------------- 1028 | | | 1030 Alice sends a MESSAGE request that is debugged: 1032 MESSAGE sip:bob@biloxi.com SIP/2.0 1033 Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8 1034 From: sip:alice@atlanta.com;tag=123aa10 1035 To: sip:bob@biloxi.com 1036 P-Preferred-Identity: alice@atlanta.com 1037 Call-ID: 9901@r1.atlanta.com 1038 CSeq: 82779 MESSAGE 1039 Max-Forwards: 70 1040 P-Debug-ID: 9E2836 1041 Content-Type: text/plain 1042 Content-Length: ... 1044 MESSAGE sip:bob@biloxi.com SIP/2.0 1045 Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds8 1046 Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8 1047 From: sip:alice@atlanta.com;tag=123aa10 1048 To: sip:bob@biloxi.com 1049 P-Asserted-Identity: alice@atlanta.com 1050 Call-ID: 9901@nms1.atlanta.com 1051 CSeq: 82779 MESSAGE 1052 Max-Forwards: 69 1053 P-Debug-ID: 9E2836 1054 Content-Type: text/plain 1055 Content-Length: ... 1057 MESSAGE sip:bob@biloxi.com SIP/2.0 1058 Via: SIP/2.0/UDP r1.atlanta.com;branch=z9hG4bKnashds8 1059 Via: SIP/2.0/UDP p1.atlanta.com;branch=z9hG4bKnashds8 1060 Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8 1061 From: sip:alice@atlanta.com;tag=123aa10 1062 To: sip:bob@biloxi.com 1063 P-Asserted-Identity: alice@atlanta.com 1064 Call-ID: 9901@nms1.atlanta.com 1065 CSeq: 82779 MESSAGE 1066 Max-Forwards: 68 1067 P-Debug-ID: 9E2836 1068 Content-Type: text/plain 1069 Content-Length: ... 1071 200 OK 1072 SIP/2.0 200 OK 1073 Via: SIP/2.0/UDP u1.atlanta.com;branch=z9hG4bKnashds8 1074 From: sip:alice@atlanta.com;tag=123aa10 1075 To: sip:bob@biloxi.com;tag=1928301774 1076 Call-ID: 9987@u1.atlanta.com 1077 CSeq: 9987 MESSAGE 1078 P-Debug-ID: 9E2836 1079 Content-Length:0 1081 The user agent u1.atlanta.com is triggered to begin logging 1082 signalling by a start trigger event of the MESSAGE method and the 1083 value alice@atlanta.com in the From: header field. The 1088 1090 1091 1092 1093 MESSAGE 1094 alice@atlanta.com 1095 1096 1097 P7M30S 1098 1099 1100 minimum 1101 9E2836 1102 1103 1104 1105 1107 The user agent detects the configured start trigger event when it 1108 originates a MESSAGE request with "alice@atlanta.com" in the From: 1109 header field. The user agent therefore starts logging and adds a 1110 P-Debug-ID header field containing the value in the 1111 element in its debugging configuration element. The user 1112 agent then forwards the request. 1114 The debugging configuration in the proxy is shown below. 1116 1117 1119 1120 1121 1122 P7M30S 1123 alice@atlanta.com 1124 1125 1126 P7M30S 1127 1128 1129 minimum 1130 1131 1132 1133 1135 The request arriving at the proxy matches the values configured in 1136 its element: a P-Debug-ID header containing the 1137 configured value and "alice@atlanta.com" in the From: header field. 1138 The proxy therefore starts logging and forwards the request. 1140 The registrar has the same element as the proxy and 1141 therefore starts logging and forwards the request. 1143 The User Agent, proxy and registrar all have the same 1144 element, and logging will stop after a time duration of 7 minutes 30 1145 seconds. 1147 6.4. Prompting a user agent to subscribe to debug-event 1149 Troubleshooting and regression testing will be quite rare events and 1150 only involve specific entities, therefore it is inefficient for all 1151 user agents to be subscribed to the debug event package all the time. 1152 A user agent can be prompted to subscribe to its own debug event 1153 package by an empty P-Debug-ID header field in a 200 OK response to a 1154 REGISTER request. The signalling is shown below. 1156 User Proxy Registrar 1157 u1.atlanta.com p1.atlanta.com r1.atlanta.com 1159 |(1) REGISTER | | 1160 |------------------>| | 1161 | |(2) REGISTER | 1162 | |------------------>| 1163 | | | 1164 |(3) 200 OK | | 1165 | P-Debug-ID: | | 1166 |<--------------------------------------| 1167 | | | 1168 | | | 1169 |(4)SUBSCRIBE | | 1170 | Event:debug | | 1171 |-------------------------------------->| 1173 7. Acknowledgements 1175 This template was derived from an initial version written by Pekka 1176 Savola and contributed by him to the xml2rfc project. 1178 8. IANA Considerations 1180 All drafts are required to have an IANA considerations section (see 1181 the update of RFC 2434 [I-D.narten-iana-considerations-rfc2434bis] 1182 for a guide). If the draft does not require IANA to do anything, the 1183 section contains an explicit statement that this is the case (as 1184 above). If there are no requirements for IANA, the section will be 1185 removed during conversion into an RFC by the RFC Editor. 1187 8.1. SIP Event Package Registration 1189 Package name: debug 1191 Type: package 1193 Contact: Peter Dawes, peter.dawes@vodafone.com> 1195 8.2. application/debuinfo+xml MIME Registration 1197 MIME media type name: application 1199 MIME subtype name: debuginfo+xml 1201 Mandatory parameters: none 1203 Optional parameters: Same as charset parameter application/xml as 1204 specified in RFC 3023 [8]. 1206 Encoding considerations: Same as encoding considerations of 1207 application/xml as specified in RFC 3023 [8]. 1209 Security considerations: See Section 10 of RFC 3023 [8] and Section 7 1210 of this specification. 1212 Interoperability considerations: none. 1214 Published specification: This document. 1216 Applications which use this media type: This document type is being 1217 used in notifications to provide SIP entities with configuration data 1218 for debugging SIP signaling. 1220 Additional Information: 1222 Magic Number: None 1224 File Extension: .rif or .xml 1225 Macintosh file type code: "TEXT" 1227 Personal and email address for further information: Peter Dawes, 1228 peter.dawes@vodafone.com 1230 Intended usage: COMMON 1232 Author/Change controller: The IETF. 1234 9. Security Considerations 1236 All drafts are required to have a security considerations section. 1237 See RFC 3552 [RFC3552] for a guide. 1239 10. References 1241 10.1. Normative References 1243 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1244 Requirement Levels", BCP 14, RFC 2119, March 1997. 1246 [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. 1248 [RFC2648] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, 1249 August 1999. 1251 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 1252 A., Peterson, J., Sparks, R., Handley, M., and E. 1253 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 1254 June 2002. 1256 [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific 1257 Event Notification", RFC 3265, June 2002. 1259 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1260 January 2004. 1262 [W3C.xml-c14n] 1263 Boyer, J., "Canonical XML Version 1.0", W3C 1264 Recommendation xpath, March 2001, 1265 . 1267 [draft-dawes-sipping-debug-id] 1268 Dawes, P., "Private Extension to the Session Initiation 1269 Protocol (SIP) for Debugging", 2008. 1271 10.2. Informative References 1273 [I-D.narten-iana-considerations-rfc2434bis] 1274 Narten, T. and H. Alvestrand, "Guidelines for Writing an 1275 IANA Considerations Section in RFCs", 1276 draft-narten-iana-considerations-rfc2434bis-09 (work in 1277 progress), March 2008. 1279 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 1280 June 1999. 1282 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 1283 Text on Security Considerations", BCP 72, RFC 3552, 1284 July 2003. 1286 Appendix A. Additional Stuff 1288 This becomes an Appendix. 1290 Authors' Addresses 1292 Peter Dawes 1293 Vodafone 1294 Newbury, Berkshire RG14 2FN 1295 UK 1297 Phone: +44 7717 275009 1298 Email: peter.dawes@vodafone.com 1300 Kar Ann Chew (editor) 1301 Vodafone Group 1302 The Connection 1303 Newbury, Berkshire RG14 2FN 1304 UK 1306 Phone: 1307 Email: karann.chew@vodafone.com 1309 Full Copyright Statement 1311 Copyright (C) The IETF Trust (2008). 1313 This document is subject to the rights, licenses and restrictions 1314 contained in BCP 78, and except as set forth therein, the authors 1315 retain all their rights. 1317 This document and the information contained herein are provided on an 1318 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1319 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1320 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1321 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1322 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1323 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1325 Intellectual Property 1327 The IETF takes no position regarding the validity or scope of any 1328 Intellectual Property Rights or other rights that might be claimed to 1329 pertain to the implementation or use of the technology described in 1330 this document or the extent to which any license under such rights 1331 might or might not be available; nor does it represent that it has 1332 made any independent effort to identify any such rights. Information 1333 on the procedures with respect to rights in RFC documents can be 1334 found in BCP 78 and BCP 79. 1336 Copies of IPR disclosures made to the IETF Secretariat and any 1337 assurances of licenses to be made available, or the result of an 1338 attempt made to obtain a general license or permission for the use of 1339 such proprietary rights by implementers or users of this 1340 specification can be obtained from the IETF on-line IPR repository at 1341 http://www.ietf.org/ipr. 1343 The IETF invites any interested party to bring to its attention any 1344 copyrights, patents or patent applications, or other proprietary 1345 rights that may cover technology that may be required to implement 1346 this standard. Please address the information to the IETF at 1347 ietf-ipr@ietf.org.