RFC 8497
Marking SIP Messages to Be Logged
Pages: 46
Proposed Standard
Proposed Standard
Part 1 of 3 – Pages 1 to 13
Internet Engineering Task Force (IETF) P. Dawes Request for Comments: 8497 Vodafone Group Category: Standards Track C. Arunachalam ISSN: 2070-1721 Cisco Systems November 2018 Marking SIP Messages to Be LoggedAbstract
SIP networks use signaling monitoring tools to diagnose user-reported problems and to perform regression testing if network or user agent (UA) software is upgraded. As networks grow and become interconnected, including connection via transit networks, it becomes impractical to predict the path that SIP signaling will take between user agents and therefore impractical to monitor SIP signaling end to end. This document describes an indicator for the SIP protocol that can be used to mark signaling as being of interest to logging. Such marking will typically be applied as part of network testing controlled by the network operator and is not used in normal user agent signaling. Operators of all networks on the signaling path can agree to carry such marking end to end, including the originating and terminating SIP user agents, even if a session originates and terminates in different networks. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8497.
Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4 3. "Log Me" Marking Protocol Aspects . . . . . . . . . . . . . . 4 3.1. Session-ID "logme" Parameter . . . . . . . . . . . . . . 4 3.2. Starting and Stopping Logging . . . . . . . . . . . . . . 5 3.3. Identifying Test Cases . . . . . . . . . . . . . . . . . 6 3.4. Passing the Marker . . . . . . . . . . . . . . . . . . . 6 3.4.1. To/From a User Device . . . . . . . . . . . . . . . . 6 3.4.2. To/From an External Network . . . . . . . . . . . . . 6 3.4.3. Across a Non-supporting SIP Intermediary . . . . . . 6 3.5. Logging Multiple Simultaneous Dialogs . . . . . . . . . . 6 3.6. Format of Logged Signaling . . . . . . . . . . . . . . . 7 3.7. Marking-Related Dialogs . . . . . . . . . . . . . . . . . 7 3.8. Forked Requests . . . . . . . . . . . . . . . . . . . . . 13 4. SIP Entity Behavior . . . . . . . . . . . . . . . . . . . . . 13 4.1. Scope of Marking . . . . . . . . . . . . . . . . . . . . 13 4.2. Endpoints . . . . . . . . . . . . . . . . . . . . . . . . 13 4.3. SIP Intermediaries Acting on Behalf of Endpoints . . . . 15 4.4. B2BUAs . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.5. "Log Me" Marker Processing by SIP Intermediaries . . . . 17 4.5.1. Stateless Processing . . . . . . . . . . . . . . . . 17 4.5.2. Stateful Processing . . . . . . . . . . . . . . . . . 17 4.5.2.1. "Log Me" Marking Not Supported by Originating UA 18 4.5.2.2. "Log Me" Marking Not Supported by Terminating UA 21 4.5.2.3. "Log Me" Marking Removed by Originating Network . 23 4.5.2.4. "Log Me" Marking Removed by Supporting Terminating Network . . . . . . . . . . . . . . . 26 4.5.2.5. "Log Me" Marking Passed by Non-supporting Terminating Network . . . . . . . . . . . . . . . 28
5. Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.1. Error Cases . . . . . . . . . . . . . . . . . . . . . . . 31 5.1.1. Missing "Log Me" Marker Error Case . . . . . . . . . 31 5.1.2. "Log Me" Marker Appears Mid-dialog Error Case . . . . 35 5.2. Non-error Cases . . . . . . . . . . . . . . . . . . . . . 36 5.2.1. Missing "Log Me" Marker Non-error Case . . . . . . . 36 5.2.2. "Log Me" Marker Appears Mid-dialog Non-error Case . . 37 5.2.3. Combining Dialogs Non-error Case . . . . . . . . . . 37 5.3. Error Handling . . . . . . . . . . . . . . . . . . . . . 38 6. Augmented BNF for the "logme" Parameter . . . . . . . . . . . 38 7. Security Considerations . . . . . . . . . . . . . . . . . . . 39 7.1. "Log Me" Authorization . . . . . . . . . . . . . . . . . 39 7.2. "Log Me" Marker Removal . . . . . . . . . . . . . . . . . 39 7.3. Denial-of-Service Attacks . . . . . . . . . . . . . . . . 39 7.4. Data Protection . . . . . . . . . . . . . . . . . . . . . 40 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 40 8.1. Personal Identifiers . . . . . . . . . . . . . . . . . . 40 8.2. Data Stored at SIP Intermediaries . . . . . . . . . . . . 41 8.3. Data Visible at Network Elements . . . . . . . . . . . . 41 8.4. Preventing Fingerprinting . . . . . . . . . . . . . . . . 41 8.5. Retaining Logs . . . . . . . . . . . . . . . . . . . . . 42 8.6. User Control of Logging . . . . . . . . . . . . . . . . . 42 8.7. Recommended Defaults . . . . . . . . . . . . . . . . . . 42 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 9.1. Registration of the "logme" Parameter . . . . . . . . . . 43 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 10.1. Normative References . . . . . . . . . . . . . . . . . . 43 10.2. Informative References . . . . . . . . . . . . . . . . . 45 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 46 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 461. Introduction
When users experience problems with setting up sessions using SIP, enterprise or service provider network operators often have to identify the root cause by examining the SIP signaling. Also, when network or user agent (UA) software or hardware is upgraded, regression testing is needed. Such diagnostics apply to a small proportion of network traffic and can apply end to end, even if signaling crosses several networks possibly belonging to several different network operators. It may not be possible to predict the path through those networks in advance, therefore, a mechanism is needed to mark a session as being of interest so that SIP entities along the signaling path can provide diagnostic logging. [RFC8123] illustrates this motivating scenario. This document describes a solution that meets the requirements for such "log me" marking of SIP signaling also defined in [RFC8123].
This document also defines a new header field parameter, "logme", for the Session-ID header field [RFC7989]. Implementations of this document MUST implement [RFC7989].2. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.3. "Log Me" Marking Protocol Aspects
3.1. Session-ID "logme" Parameter
Logging for diagnostic purposes is most effective when it is applied end to end in a communication session. This ability requires a "log me" marker to be passed through SIP intermediaries. The Session-ID header field defined in [RFC7989] was chosen to carry the "log me" marker as a "logme" parameter since the session identifier is typically passed through SIP Back-to-Back User Agents (B2BUAs) (described in [RFC7092]) or other intermediaries, as per the Session- ID requirement REQ3 in [RFC7206]. The "logme" parameter shown in Figure 1 does not introduce any device-specific or user-specific information and MUST be passed unchanged with the Session-ID header field. There is an exception, however, for the cases specified in Section 3.4.2 where the "log me" marker may be removed at a network boundary. Alice Proxy Registrar u1.example.com p1.example.com r1.example.com | | | |(1) INVITE | | | Session-ID: ab30317f1a784dc48ff824d0d3715d86; | remote=47755a9de7794ba387653f2099600ef2;logme |----------------->| | | | | Figure 1: "Log Me" Marking Using the "logme" Session-ID Header Field Parameter
3.2. Starting and Stopping Logging
If a dialog is to be "log me" marked, then marking MUST start with the SIP request that initiates that dialog (dialog-initiating requests are described in Section 12.1 of [RFC3261]). For the most effective testing and troubleshooting, marking continues for the lifetime of the dialog, applies to each request and response in the dialog, and applies uninterrupted end to end (including user devices). The "log me" marking mechanism described in this document allows for parts of the signaling path to not be marked, e.g, because an endpoint does not support the "log me" marking mechanism (see Section 4.5.2) or because an endpoint or intermediary deliberately removes the "log me" marker (see Section 4.5.2.4). Also, marking errors can terminate marking before the dialog ends (see Section 5.3). A UA or intermediary adds a "log me" marker in an unmarked request or response in two cases: first, because it is configured to add the marking to a dialog-creating request, or second, because it has received a dialog-creating request that is being "log me" marked causing it to maintain state to ensure that all requests and responses in the dialog are similarly "log me" marked. Once the "log me" marking is started for a dialog, all subsequent requests and responses in this dialog are "log me" marked. Marking is stopped when this dialog and its related dialogs end. It is considered an error (see Section 5.1.2) if "log me" marking is started in a mid- dialog request or response. For the first case, "log me" marking trigger condition configurations that define whether a UA or intermediary can initiate "log me" marking for a given dialog are out of scope of this document. As an example of trigger condition configurations, the UA or intermediary could be configured to add a "log me" marker for all dialogs initiated during a specific time period (e.g., 9:00 am - 10:00 am every day) or for specific dialogs that have a particular "User- Agent" header field value. They could also be configured to add a "log me" marker for a specific set of called party numbers for which users are experiencing call setup failures. For the second case of a UA or intermediary detecting that a dialog- initiating request is being "log me" marked, the scope of such marking extends to the lifetime of the dialog. In addition, as discussed in Section 3.7, "log me" marked dialogs that create related dialogs (e.g., REFER) may transfer the marking to the related dialogs. In such cases, the entire "session", identified by the Session-ID header field, is "log me" marked.
3.3. Identifying Test Cases
The local Universally Unique Identifier (UUID) portion of the Session-ID header field value [RFC7989] in the initial SIP request of a dialog is used as a random test case identifier (described in REQ 5 in [RFC8123]). This provides the ability to collate all logged SIP requests and responses to the initial SIP request in a dialog or standalone transaction.3.4. Passing the Marker
3.4.1. To/From a User Device
When a user device inserts the "log me" marker, the marker MUST be passed unchanged in the Session-ID header field across an edge proxy or a B2BUA adjacent to the user device.3.4.2. To/From an External Network
An external network is a peer network connected at a network boundary as defined in [RFC8123]. External networks may be connected directly or via a peering network, and such networks often have specific connection agreements. Whether "log me" marking is removed depends on the policy applied at the network-to-network interface. Troubleshooting and testing will be easier if peer networks endeavor to make agreements to pass "log me" marking unchanged. However, since a "log me" marker may cause a SIP entity to log the SIP header and body of a request or response, the "log me" marker MUST be removed at a network boundary if no agreement exists between peer networks.3.4.3. Across a Non-supporting SIP Intermediary
"Log me" marking is most effective if passed end to end. However, intermediaries that do not comply with this document might pass the "log me" marker unchanged or even drop it entirely.3.5. Logging Multiple Simultaneous Dialogs
Multiple SIP dialogs can be simultaneously logged by an originating UA, terminating UA, and SIP entities on the signaling path. These dialogs are differentiated by their test case identifier (the local UUID portion of the Session-ID header field value at the originating device).
3.6. Format of Logged Signaling
The entire SIP message (SIP request line, response line, header fields, and message body) SHOULD be logged since troubleshooting might be difficult if information is missing. Logging SHOULD use common standard formats such as SIP Common Log Format (CLF) defined in [RFC6873] and Libpcap as defined in "vnd.tcpdump.pcap" in the Media Types registry [MEDIA-TYPES]. If SIP CLF is used, the entire message is logged using Vendor-ID = 00000000 and Tag = 02 in the <OptionalFields> portion of the SIP CLF record (see Section 4.4 of [RFC6873]). Header fields SHOULD be logged in the form in which they appear in the message; they SHOULD NOT be converted between long and compact forms described in Section 7.3.3 of [RFC3261].3.7. Marking Related Dialogs
"Log me" marking is done per dialog; typically, it begins at dialog creation and ends when the dialog ends. However, dialogs related to a "log me" marked dialog MAY also be "log me" marked for call control features such as call forward, transfer, park, and join. As described in Section 6 of [RFC7989], related dialogs can occur when an endpoint receives a 3xx message, a REFER that directs the endpoint to a different peer, an INVITE request with Replaces that also potentially results in communicating with a new peer, or an INVITE with a Join header field as described in [RFC3911]. An example is the call transfer feature described in Section 6.1 of [RFC5589]. The logged signaling for related dialogs can be correlated using Session- ID header field values as described in Section 10.9 of [RFC7989]. In the example shown in Figure 2, Alice has reported problems making call transfers. Her terminal is placed in debug mode in preparation for "log me" marked signaling from the network administrator, Bob. Bob's terminal is configured to "log me" mark and log signaling for calls originated during the troubleshooting session (e.g., for a duration of 15 minutes). Bob, who is troubleshooting the problem, arranges to make a call that Alice can attempt to transfer. Bob calls Alice, which creates initial dialog1, and then Alice transfers the call to connect Bob to Carol. Logged signaling is correlated using the test case identifier, which is the local UUID ab30317f1a784dc48ff824d0d3715d86 in the Session-ID header field of INVITE request F1. Logging by Alice's terminal begins when it receives and echoes the "log me" marker in INVITE F1 and ends when the last request or response in the dialog is sent or received (200 OK F7 of dialog1). Also during dialog1, Alice's terminal logs related REFER dialog2, which it initiates and terminates as part of the call transfer. Alice's terminal inserts a "log me" marker in the REFER request and 200 OK responses to NOTIFY requests in dialog2. Both dialog1 and dialog2 have the same test case identifier.
Logging by Bob's terminal begins when it sends INVITE F1, which includes the "log me" marker, and ends when dialog3, initiated by Bob, ends. Logging by Carol's terminal begins when it receives the INVITE F5 with the "log me" marker and ends when dialog3 ends. dialog3 is not logged by Alice's terminal; however, the test case identifier ab30317f1a784dc48ff824d0d3715d86 is also the test case identifier (local-uuid) in INVITE F5. Also, the test case identifier of dialog2, which is logged by Alice's terminal, can be linked to dialog1 and dialog3 because the remote-uuid component of dialog2 is the test case identifier ab30317f1a784dc48ff824d0d3715d86.
Alice Bob Carol Transferor Transferee Transfer | | Target | INVITE F1 | | dialog1 |<-------------------| | | 200 OK F2 | | dialog1 |------------------->| | | ACK | | dialog1 |<-------------------| | | INVITE (hold) | | dialog1 |------------------->| | | 200 OK | | dialog1 |<-------------------| | | ACK | | dialog1 |------------------->| | | REFER F3 (Target-Dialog:1) | dialog2 |------------------->| | | 200 OK | | dialog2 |<-------------------| | | NOTIFY (100 Trying) F4 | dialog2 |<-------------------| | | 200 OK | | dialog2 |------------------->| | | | INVITE F5 | dialog3 | |------------------->| | | 200 OK | dialog3 | |<-------------------| | | ACK | dialog3 | |------------------->| | NOTIFY (200 OK) F6| | dialog2 |<-------------------| | | 200 OK | | dialog2 |------------------->| | | BYE | | dialog1 |------------------->| | | 200 OK F7 | | dialog1 |<-------------------| | | | BYE | dialog3 | |<-------------------| | | 200 OK | dialog3 | |------------------->| Figure 2: "Log Me" Marking Related Dialogs in Call Transfer
F1: Bob's UA inserts the "logme" parameter in the Session-ID header
field of the INVITE request that creates dialog1.
F3: Alice's UA inserts the "logme" parameter in the Session-ID
header field of the REFER request that creates dialog2, which
is related to dialog1.
F5: Bob's UA inserts the "logme" parameter in the Session-ID header
field of the INVITE request that creates dialog3, which is
related to dialog1.
F1 INVITE Transferee -> Transferor
INVITE sips:transferor@atlanta.example.com SIP/2.0
Via: SIP/2.0/TLS [2001:db8::1];branch=z9hG4bKnas432
Max-Forwards: 70
To: <sips:transferor@atlanta.example.com>
From: <sips:transferee@biloxi.example.com>;tag=7553452
Call-ID: 090459243588173445
Session-ID: ab30317f1a784dc48ff824d0d3715d86
;remote=00000000000000000000000000000000;logme
CSeq: 29887 INVITE
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
Supported: replaces, gruu, tdialog
Contact: <sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha>
Content-Type: application/sdp
Content-Length: ...
F2 200 OK Transferor -> Transferee
SIP/2.0 200 OK
Via: SIP/2.0/TLS [2001:db8::1];branch=z9hG4bKnas432
To: <sips:transferor@atlanta.example.com>;tag=31kdl4i3k
From: <sips:transferee@biloxi.example.com>;tag=7553452
Call-ID: 090459243588173445
Session-ID: 47755a9de7794ba387653f2099600ef2
;remote=ab30317f1a784dc48ff824d0d3715d86;logme
CSeq: 29887 INVITE
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
Supported: replaces, gruu, tdialog
Contact: <sips:4889445d8kjtk3@atlanta.example.com;gr=723jd2d>
Content-Type: application/sdp
Content-Length: ...
F3 REFER Transferor -> Transferee
REFER sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha SIP/2.0
Via: SIP/2.0/TLS pc33.atlanta.example.com;branch=z9hG4bKna9
Max-Forwards: 70
To: <sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha>
From: <sips:transferor@atlanta.example.com>;tag=1928301774
Call-ID: a84b4c76e66710
Session-ID: 47755a9de7794ba387653f2099600ef2
;remote=ab30317f1a784dc48ff824d0d3715d86;logme
CSeq: 314159 REFER
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
Supported: gruu, replaces, tdialog
Require: tdialog
Refer-To: <sips:transfertarget@chicago.example.com>
Target-Dialog: 090459243588173445;local-tag=7553452
;remote-tag=31kdl4i3k
Contact: <sips:4889445d8kjtk3@atlanta.example.com;gr=723jd2d>
Content-Length: 0
F4 NOTIFY Transferee -> Transferor
NOTIFY sips:4889445d8kjtk3@atlanta.example.com
;gr=723jd2d SIP/2.0
Via: SIP/2.0/TLS [2001:db8::1];branch=z9hG4bKnas432
Max-Forwards: 70
To: <sips:transferor@atlanta.example.com>;tag=1928301774
From: <sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha>
;tag=a6c85cf
Call-ID: a84b4c76e66710
Session-ID: ab30317f1a784dc48ff824d0d3715d86
;remote=47755a9de7794ba387653f2099600ef2;logme
CSeq: 73 NOTIFY
Contact: <sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha>
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
Supported: replaces, tdialog
Event: refer
Subscription-State: active;expires=60
Content-Type: message/sipfrag
Content-Length: ...
F5 INVITE Transferee -> Transfer Target
INVITE sips:transfertarget@chicago.example.com SIP/2.0
Via: SIP/2.0/TLS [2001:db8::1];branch=z9hG4bKnas41234
Max-Forwards: 70
To: <sips:transfertarget@chicago.example.com>
From: <sips:transferee@biloxi.example.com>;tag=j3kso3iqhq
Call-ID: 90422f3sd23m4g56832034
Session-ID: ab30317f1a784dc48ff824d0d3715d86
;remote=00000000000000000000000000000000;logme
CSeq: 521 REFER
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
Supported: replaces, gruu, tdialog
Contact: <sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha>
Content-Type: application/sdp
Content-Length: ...
F6 NOTIFY Transferee -> Transferor
NOTIFY sips:4889445d8kjtk3@atlanta.example.com
;gr=723jd2d SIP/2.0
Via: SIP/2.0/TLS [2001:db8::1];branch=z9hG4bKnas432
Max-Forwards: 70
To: <sips:transferor@atlanta.example.com>;tag=1928301774
From: <sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha>
;tag=a6c85cf
Call-ID: a84b4c76e66710
Session-ID: ab30317f1a784dc48ff824d0d3715d86
;remote=47755a9de7794ba387653f2099600ef2;logme
CSeq: 74 NOTIFY
Contact: <sips:3ld812adkjw@biloxi.example.com;gr=3413kj2ha>
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
Supported: replaces, tdialog
Event: refer
Subscription-State: terminated;reason=noresource
Content-Type: message/sipfrag
Content-Length: ...
3.8. Forked Requests
A SIP intermediary is required to copy the "log me" marker into forked requests. SIP request forking is discussed in Sections 4 and 16.6 of [RFC3261].
(page 13 continued on part 2)