RFC 8497
Marking SIP Messages to Be Logged
Pages: 46
Proposed Standard
Proposed Standard
Part 2 of 3 – Pages 13 to 30
4. SIP Entity Behavior
4.1. Scope of Marking
"Log me" marking is intended to be limited, in time period and number of dialogs marked, to the minimum needed to troubleshoot a particular problem or perform a particular test. o SIP entities MUST be configured to "log me" mark only dialogs needed for the current testing purpose, e.g., troubleshooting or regression testing. The mechanisms in this section ensure that "log me" marking begins at dialog creation and, other than cases of marking related dialogs or premature ending, ends when the dialog being "log me" marked ends. o If a dialog is to be marked, the only way to initiate "log me" marking is at the dialog-creating request (e.g., SIP INVITE) sent by an originating endpoint or an intermediary that marks on behalf of the originating endpoint. Marking that appears mid-dialog is an error as described in Section 5.1.2. The final terminating endpoint, or intermediary that marks on behalf of the terminating endpoint, cannot initiate marking, but it takes action as defined in Sections 4.2 and 4.3 if it receives an incoming "log me" marker. Note that the error cases described in Section 5.1 cause SIP entities to stop "log me" marking, and the requirements in Section 7 also place requirements on SIP entities, including allowing SIP entities to not log signaling based on local policies (see Section 8.6).4.2. Endpoints
A common scenario is to have both originating and terminating endpoints support "log me" marking with the originating endpoint configured to initiate "log me" marking. In this simplest use case, the originating UA inserts a "log me" marker in the dialog-creating SIP request and all subsequent SIP requests within that dialog. The "log me" marker is passed through the SIP intermediaries and arrives at the terminating UA, which echoes the "log me" marker in the corresponding responses. If the terminating UA sends an in-dialog request on a dialog that is being "log me" marked, it inserts a "log me" marker and the originating UA echoes the "log me" marker in
responses. The terminating UA logs the "log me" marked SIP requests
and responses if it is allowed as per policy defined in the
terminating network. This basic use case suggests the following
rules for originating and terminating UAs.
For originating UAs:
o The originating UA configured for "log me" marking MUST insert a
"log me" marker into the dialog-creating SIP request and
subsequent in-dialog SIP requests.
o The originating UA itself logs marked requests and responses.
o The originating UA echoes, in responses, the "log me" marker
received in in-dialog requests from the terminating side.
o The originating UA logs the SIP responses that it sends in
response to received "log me" marked in-dialog requests.
o The originating UA MAY also apply these rules to any subsequent
related SIP dialogs as described in Section 3.7.
For terminating UAs:
o The terminating UA detects that a dialog is of interest to logging
by the existence of a "log me" marker in an incoming dialog-
creating SIP request.
o The terminating UA itself logs marked requests and corresponding
marked responses if allowed as per policy.
o The terminating UA MUST echo a "log me" marker in responses to a
SIP request that included a "log me" marker.
o If the terminating UA has detected that a dialog is being "log me"
marked, it MUST insert a "log me" marker in any in-dialog SIP
requests that it sends.
o The terminating UA itself logs any in-dialog SIP requests that it
sends if allowed as per policy.
o The terminating UA MAY also apply these rules to any subsequent
related SIP dialogs as described in Section 3.7.
4.3. SIP Intermediaries Acting on Behalf of Endpoints
A network operator may know that some of the UAs connected to the network do not support "log me" marking. Subject to the authorizations in Section 7.1, a SIP intermediary close to the UA (e.g., edge proxy, B2BUA) on the originating and/or terminating sides inserts the "log me" marker instead in order to test sessions involving such UAs. The originating and terminating SIP intermediaries are not identified by protocol means but are designated and explicitly configured by the network administrator to "log me" mark on behalf of endpoints. The intermediaries that are known to be closest to the terminals can be configured to "log me" mark on behalf of terminals that do not support "log me" marking. The originating SIP intermediary is the first one to be traversed by a SIP request sent by the originating endpoint. Similarly, the terminating SIP intermediary is the last intermediary traversed before the terminating endpoint is reached. The SIP intermediary at the originating side is configured to insert the "log me" marker on behalf of the originating endpoint. If the terminating UA does not echo the "log me" marker in responses to a marked request, then the SIP intermediary closest to the terminating UA, if configured to mark on behalf of the terminating UA, inserts a "log me" marker in responses to the request. Likewise, if the terminating UA sends an in-dialog request, the SIP intermediary at the terminating side inserts a "log me" marker and the SIP intermediary at the originating side echoes the "log me" marker in responses to that request. Originating and terminating intermediaries that are configured for "log me" marking on behalf of the endpoint must also mark dialog-creating requests that contain Target-Dialog [RFC4538], Join [RFC3911], and Replaces [RFC3891] header fields and corresponding responses. The SIP intermediaries at the originating and terminating sides log the "log me" marked SIP requests and responses if it is allowed as per policy defined in the originating and terminating networks. This scenario suggests the following rules when a SIP intermediary is configured to initiate or handle "log me" marking on behalf of a UA. For the originating SIP intermediary: o The originating SIP intermediary configured for "log me" marking MUST insert a "log me" marker into the dialog-creating SIP request and subsequent in-dialog SIP requests. o The originating SIP intermediary itself logs marked requests and responses.
o The originating SIP intermediary detects the "log me" marker
received in in-dialog requests and echoes the "log me" marker in
the corresponding SIP responses.
o The originating SIP intermediary logs the SIP responses that it
sends in response to "log me" marked in-dialog requests.
o The originating SIP intermediary MAY also apply these rules to any
subsequent related SIP dialogs as described in Section 3.7.
For the terminating SIP intermediary:
o The terminating SIP intermediary detects that a dialog is of
interest to logging by the existence of a "log me" marker in an
incoming dialog-creating SIP request.
o The terminating SIP intermediary itself logs marked requests and
corresponding responses if allowed as per policy.
o The terminating SIP intermediary MUST echo a "log me" marker in
responses to a SIP request that included a "log me" marker.
o If the terminating SIP intermediary has detected that a dialog is
being "log me" marked, it MUST insert a "log me" marker in any
in-dialog SIP requests from the terminating UA.
o The terminating SIP intermediary itself logs any in-dialog SIP
requests that it sends if allowed as per policy.
o The terminating SIP intermediary MAY also apply these rules to any
subsequent related SIP dialogs as described in Section 3.7.
4.4. B2BUAs
B2BUA "log me" behavior is specified based on its different signaling
plane roles described in [RFC7092].
A Proxy-B2BUA SHOULD copy "log me" marking in requests and responses
from its terminating side to the originating side without needing
explicit configuration to do so.
A dialog on one "side" of the B2BUA may or may not be coupled to a
related dialog on the other "side" for "log me" purposes. To allow
end-to-end troubleshooting of user problems and regression testing, a
signaling-only and SDP-modifying signaling-only B2BUA [RFC7092]
SHOULD couple related dialogs for "log me" marking purposes and pass
on the received "log me" parameter from the originating side to the
terminating side and vice versa. For example, a SIP B2BUA handling
an end-to-end session between an external caller and an agent in a contact center environment can couple the dialog between itself and an agent with the dialog between itself and the external caller. It can pass on the "log me" marking from the originating side to the terminating side to enable end-to-end logging of specific sessions of interest. For dialogs that are being "log me" marked, all B2BUAs MUST "log me" mark in-dialog SIP requests that they generate on their own, without needing explicit configuration to do so. This rule applies to both the originating and terminating sides of a B2BUA.4.5. "Log Me" Marker Processing by SIP Intermediaries
4.5.1. Stateless Processing
Typically, "log me" marking will be done by an originating UA and echoed by a terminating UA. SIP intermediaries on the signaling path between these UAs that do not perform the tasks described in Sections 4.3 or 4.4 MUST simply log any request or response that contains a "log me" marker in a stateless manner, if it is allowed per local policy.4.5.2. Stateful Processing
The originating and terminating SIP intermediaries that "log me" mark on behalf of endpoints and SIP intermediaries that remove "log me" marking at the network boundary must maintain state to enable "log me" marking. Applicable scenarios are as follows: o The originating UA does not support "log me" marking. This scenario was described in Section 4.3 and requires support by the originating SIP intermediary. "Log me" marker processing is illustrated in Section 4.5.2.1. o The terminating UA does not support "log me" marking. This scenario was described in Section 4.3 and requires support by the terminating SIP intermediary. "Log me" marker processing is illustrated in Section 4.5.2.2. o The originating network ensures that it does not pass marking outside its boundaries in order to not impact any external networks. The originating network removes "log me" marking from SIP requests and responses before forwarding them from its network boundary to external networks, but it adds marking back to any incoming SIP requests and responses belonging to any "log me"
marked dialog. This scenario requires support by the SIP
intermediary at the originating network boundary. "Log me" marker
processing is illustrated in Section 4.5.2.3.
o The terminating network ensures that it does not allow "log me"
marking from external networks to pass through its boundary to its
internal entities. The terminating network removes "log me"
marking from SIP requests and responses before forwarding them
internally, but it adds marking back to any outgoing SIP requests
and responses belonging to any "log me" marked dialog. This
scenario requires support by the SIP intermediary at the
terminating network boundary. "Log me" marker processing is
illustrated in Section 4.5.2.4.
o The terminating network does not support "log me" marking and does
not echo marking that it receives. The originating network adds
marking back to any incoming SIP requests and responses belonging
to the "log me" marked dialog. This scenario requires support by
the SIP intermediary at the originating network boundary and "log
me" marker processing is illustrated in Section 4.5.2.5.
SIP intermediary behavior in these scenarios is illustrated using
[RFC3665] example call flow "Session Establishment Through Two
Proxies".
4.5.2.1. "Log Me" Marking Not Supported by Originating UA
Alice's UA does not support "log me" marking; hence, Proxy 1, which
is the SIP intermediary closest to Alice, is configured to act on
behalf of Alice's UA to "log me" mark specific dialogs of interest
that are created by Alice for troubleshooting purposes.
In Figure 3, Proxy 1 in the originating network maintains state of
which dialogs are being logged in order to "log me" mark all SIP
requests and responses that it receives from Alice's UA before
forwarding them to Proxy 2.
[ NETWORK A ] [ NETWORK B ]
Alice Proxy 1 Proxy 2 Bob
| | | |
| INVITE F1 | | |
| (no logme) | | |
|--------------->| | |
| | INVITE F2 | |
| | (logme) | |
| |--------------->| |
| | | |
| | | |
| 100 F3 | | INVITE F4 |
| (logme) | | (logme) |
|<---------------| 100 F5 |--------------->|
| | (logme) | |
| |<---------------| |
| | | 180 F6 |
| | | (logme) |
| | 180 F7 |<---------------|
| | (logme) | |
| 180 F8 |<---------------| |
| (logme) | | |
|<---------------| | 200 F9 |
| | | (logme) |
| | 200 F10 |<---------------|
| | (logme) | |
| 200 F11 |<---------------| |
| (logme) | | |
|<---------------| | |
| ACK F12 | | |
| (no logme) | | |
|--------------->| | |
| | | |
| | ACK F13 | |
| | (logme) | |
| |--------------->| |
| | | |
| | | ACK F14 |
| | | (logme) |
| | |--------------->|
| Both Way RTP Media |
|<================================================>|
| | | BYE F15 | | | | (logme) | | | BYE F16 |<---------------| | | (logme) | | | BYE F17 |<---------------| | | (logme) | | | |<---------------| | | | 200 F18 | | | | (no logme) | | | |--------------->| | | | | 200 F19 | | | | (logme) | | | |--------------->| | | | | | | | | 200 F20 | | | | (logme) | | | |--------------->| | | | | Figure 3: The Originating UA Does Not Support "Log Me" Marking F1: Alice's UA does not insert a "log me" marker in the dialog- creating INVITE request F1. Nevertheless, Proxy 1 is configured to initiate logging on behalf of Alice. Proxy 1 logs INVITE request F1 and maintains state that this dialog is being logged. F2: Proxy 1 inserts a "log me" marker in INVITE request F2 before forwarding it to Proxy 2. Proxy 1 logs this request. F3: Proxy 1 inserts a "log me" marker in 100 response F3 before forwarding it to Alice's UA since this is a response sent on a dialog that is being "log me" marked. Proxy 1 logs this response. F4: "Bob's UA detects the "log me" marker and logs the INVITE request F4 if allowed as per policy. F6: Bob's UA echoes the "log me" marker in INVITE request F4 into 180 response F6. It logs this response if allowed as per policy. F7 and F8: Proxy 1 logs the received "180" response F7 and passes the "log me" marker to Alice's UA in F8. F12: Proxy 1 receives ACK with no "log me" marker. It doesn't consider this an error since it is configured to "log me" mark on behalf of Alice's UA.
F13: Proxy 1 inserts a "log me" marker in ACK request F13 before
forwarding it to Proxy 2. Proxy 1 logs this request.
F15: Bob's UA inserts a "log me" marker in the in-dialog BYE request
and this "log me" marker is carried back to Alice's UA in F16
and F17. Bob's UA logs this request if allowed as per policy.
F18: Alice's UA does not echo the "log me" marker from BYE request
F17 into 200 response F18.
F19: Proxy 1 inserts a "log me" marker in 200 response F19 before
forwarding it to Proxy 2. Proxy 1 logs this response.
4.5.2.2. "Log Me" Marking Not Supported by Terminating UA
In Figure 4, Bob's UA does not support "log me" marking, so Proxy 2
in the terminating network maintains state to ensure "log me" marking
of SIP requests and responses from Bob's UA.
[ NETWORK A ] [ NETWORK B ]
Alice Proxy 1 Proxy 2 Bob
| | | |
| INVITE F1 | | |
| (log me) | | |
|--------------->| | |
| | INVITE F2 | |
| | (log me) | |
| |--------------->| |
| | | |
| | | |
| 100 F3 | | |
| (log me) | | |
|<---------------| | |
| | | INVITE F4 |
| | | (log me) |
| | 100 F5 |--------------->|
| | (log me) | |
| |<---------------| |
| | | 180 F6 |
| | | (no log me) |
| | |<---------------|
| | | |
| | | |
| | 180 F7 | |
| | (log me) | |
| |<---------------| |
| | | |
| | | |
| 180 F8 | | |
| (log me) | | |
|<---------------| | 200 F9 |
| | | (no log me) |
| | 200 F10 |<---------------|
| | (log me) | |
| 200 F11 |<---------------| |
| (log me) | | |
|<---------------| | |
| ACK F12 | | |
| (log me) | | |
|--------------->| | |
| | ACK F13 | |
| | (log me) | |
| |--------------->| ACK F14 |
| | | (log me) |
| | |--------------->|
| Both Way RTP Media |
|<================================================>|
| | | BYE F15 | | | | (no log me) | | | BYE F16 |<---------------| | | (log me) | | | BYE F17 |<---------------| | | (log me) | | | |<---------------| | | | 200 F18 | | | | (log me) | | | |--------------->| | | | | 200 F19 | | | | (log me) | | | |--------------->| 200 F20 | | | | (log me) | | | |--------------->| | | | | Figure 4: The Terminating UA Does Not Support "Log Me" Marking. F1: Alice's UA inserts a "log me" marker in the dialog-creating INVITE request F1. F2: INVITE F2 is "log me" marked; therefore, Proxy 2 maintains state that this dialog is to be logged. Proxy 2 logs the request and responses of this dialog if allowed per policy. F5: Proxy 2 inserts a "log me" marker in the 100 response it sends to Proxy 1. F6: Bob's UA does not support "log me" marking; therefore, the 180 response to the INVITE request doesn't have a "log me" marker. F7: Proxy 2 inserts a "log me" marker in the 180 response on behalf of Bob's UA before forwarding it. The same applies to response F10 and the BYE request in F16.4.5.2.3. "Log Me" Marking Removed by Originating Network
If network A in Figure 5 is performing testing independently of network B, then network A removes "log me" marking from SIP requests and responses forwarded to network B to prevent triggering unintended logging in network B. Proxy 1 removes "log me" marking from requests and responses that it forwards to Proxy 2 and maintains state of which dialogs are being "log me" marked in order to "log me" mark requests and responses that it forwards from Proxy 2 to Alice's UA. For troubleshooting purposes, Proxy 1 MAY also log the requests and responses sent to or received from Proxy 2 even though it removed "log me" marker prior to forwarding the messages to Proxy 2.
[ NETWORK A ] [ NETWORK B ]
Alice Proxy 1 Proxy 2 Bob
| | | |
| INVITE F1 | | |
| (logme) | | |
|--------------->| | |
| | INVITE F2 | |
| | (no logme) | |
| |--------------->| |
| | | |
| | | |
| 100 F3 | | |
| (logme) | | INVITE F4 |
| | | (no logme) |
|<---------------| 100 F5 |--------------->|
| | (no logme) | |
| |<---------------| |
| | | 180 F6 |
| | | (no logme) |
| | 180 F7 |<---------------|
| | (no logme) | |
| 180 F8 |<---------------| |
| (logme) | | |
|<---------------| | 200 F9 |
| | | (no logme) |
| | 200 F10 |<---------------|
| | (no logme) | |
| 200 F11 |<---------------| |
| (logme) | | |
|<---------------| | |
| ACK F12 | | |
| (logme) | | |
|--------------->| | |
| | | |
| | ACK F13 | |
| | (no logme) | |
| |--------------->| |
| | | |
| | | ACK F14 |
| | | (no logme) |
| | |--------------->|
| Both Way RTP Media |
|<================================================>|
| | | BYE F15 | | | | (no logme) | | | BYE F16 |<---------------| | | (no logme) | | | BYE F17 |<---------------| | | (logme) | | | |<---------------| | | | 200 F18 | | | | (logme) | | | |--------------->| | | | | 200 F19 | | | | (no logme) | | | |--------------->| | | | | | | | | 200 F20 | | | | (no logme) | | | |--------------->| | | | | Figure 5: The Originating Network Removes "Log Me" Marking from Outgoing SIP Messages at its Network Edge. F1: Alice's UA inserts a "log me" marker in the dialog-creating INVITE request, and Proxy 1 therefore maintains state that this dialog is to be logged. F2: Proxy 1 removes "log me" marking from INVITE request before forwarding it to Proxy 2. Proxy 1 logs INVITE request F2. F3: Proxy 1 inserts a "log me" marker in the 100 response sent to Alice's UA. Proxy 1 logs this response. F8: Proxy 1 inserts a "log me" marker in the 180 response before forwarding it to Alice's UA. Proxy 1 logs this response. The same applies to responses F11 and F17. F13: Proxy 1 removes "log me" marking from the ACK request. Proxy 1 logs this request before forwarding it to Proxy 2. F19: Proxy 1 removes "log me" marking from the 200 response of the BYE request. Proxy 1 logs this response before forwarding it to Proxy 2.
4.5.2.4. "Log Me" Marking Removed by Supporting Terminating Network
In Figure 6, Proxy 2 removes "log me" marking from all SIP requests and responses entering network B. However, Proxy 2 supports maintaining the marking state of the dialog and "log me" marks requests and responses that it sends towards Proxy 1. For troubleshooting purposes, Proxy 2 MAY also log the requests and responses received from or sent to Bob even though it removed the "log me" marker prior to forwarding the messages to Bob. This scenario might be used for troubleshooting a signaling path between two enterprise or carrier networks, or across a transit network, with minimal logging (i.e., only at the network boundaries).
[ NETWORK A ] [ NETWORK B ]
Alice Proxy 1 Proxy 2 Bob
| | | |
| INVITE F1 | | |
| (log me) | | |
|--------------->| | |
| | INVITE F2 | |
| | (log me) | |
| |--------------->| |
| | | |
| | | |
| 100 F3 | | |
| (log me) | | |
|<---------------| | |
| | | INVITE F4 |
| | | (no log me) |
| | 100 F5 |--------------->|
| | (log me) | |
| |<---------------| |
| | | 180 F6 |
| | | (no log me) |
| | |<---------------|
| | 180 F7 | |
| | (log me) | |
| |<---------------| |
| | | |
| | | |
| 180 F8 | | |
| (log me) | | |
|<---------------| | 200 F9 |
| | | (no log me) |
| | 200 F10 |<---------------|
| | (log me) | |
| 200 F11 |<---------------| |
| (log me) | | |
|<---------------| | |
| ACK F12 | | |
| (log me) | | |
|--------------->| | |
| | ACK F13 | |
| | (log me) | |
| |--------------->| ACK F14 |
| | | (no log me) |
| | |--------------->|
| Both Way RTP Media |
|<================================================>|
| | | BYE F15 | | | | (no log me) | | | BYE F16 |<---------------| | | (log me) | | | BYE F17 |<---------------| | | (log me) | | | |<---------------| | | | 200 F18 | | | | (log me) | | | |--------------->| | | | | 200 F19 | | | | (log me) | | | |--------------->| 200 F20 | | | | (no log me) | | | |--------------->| | | | | Figure 6: The terminating network removes "log me" marking from incoming SIP messages at its network edge. F1: Alice's UA inserts a "log me" marker in the dialog-creating INVITE request F1. Proxy 1 detects the "log me" marker, logs the request, and maintains state that this dialog is to be logged. F2: Proxy 2 removes the "log me" marker in the INVITE request F2 before forwarding it as F4. The same applies to responses F13 and F19. F6: Proxy 2 inserts a "log me" marker in the 180 response to the INVITE request and logs the request before forwarding it as F7. The same applies to response F9 and the BYE request in F15.4.5.2.5. "Log Me" Marking Passed by Non-supporting Terminating Network
In Figure 6, Proxy 2 is not "log me" aware and therefore passes marking in all SIP requests and responses entering network B according to the rules in Sections 16.6 and 16.7 of [RFC3261]. Proxy 2 does not log requests and responses in the dialog. Proxy 1 supports maintaining the marking state of the dialog. When Proxy 1 observes that requests and responses received from Proxy 2 are not marked, it adds the marking. For troubleshooting purposes, Proxy 1 MAY also log the requests and responses received from or sent to Proxy 2 even though Proxy 2 didn't add "log me" to messages sent to Proxy 1.
[ NETWORK A ] [ NETWORK B ]
Alice Proxy 1 Proxy 2 Bob
| | | |
| INVITE F1 | | |
| (log me) | | |
|--------------->| | |
| | INVITE F2 | |
| | (log me) | |
| |--------------->| |
| | | |
| | | |
| 100 F3 | | |
| (log me) | | |
|<---------------| | |
| | | INVITE F4 |
| | | (log me) |
| | 100 F5 |--------------->|
| | (no log me) | |
| |<---------------| |
| | | 180 F6 |
| | | (no log me) |
| | |<---------------|
| | 180 F7 | |
| | (no log me) | |
| |<---------------| |
| | | |
| | | |
| 180 F8 | | |
| (log me) | | |
|<---------------| | 200 F9 |
| | | (no log me) |
| | 200 F10 |<---------------|
| | (no log me) | |
| 200 F11 |<---------------| |
| (log me) | | |
|<---------------| | |
| ACK F12 | | |
| (log me) | | |
|--------------->| | |
| | ACK F13 | |
| | (log me) | |
| |--------------->| ACK F14 |
| | | (log me) |
| | |--------------->|
| Both Way RTP Media |
|<================================================>|
| | | BYE F15 | | | | (no log me) | | | BYE F16 |<---------------| | | (no log me) | | | BYE F17 |<---------------| | | (log me) | | | |<---------------| | | | 200 F18 | | | | (log me) | | | |--------------->| | | | | 200 F19 | | | | (log me) | | | |--------------->| 200 F20 | | | | (log me) | | | |--------------->| | | | | Figure 7: The Terminating Network Removes "Log Me" Marking from Incoming SIP Messages at its Network Edge. F1: Alice's UA inserts a "log me" marker in the dialog-creating INVITE request F1. Proxy 1 detects the "log me" marker, logs the request, and maintains state that this dialog is to be logged. F2: Proxy 2 passes the "log me" marker in the INVITE request F2 before forwarding it as F4. The same applies to request F13 and response F19. F6: Bob's UA does not support "log me" marking and does not echo the "log me" marker in response F6. The same applies to response F9 and the BYE request F15. F7: Proxy 1 inserts a "log me" marker in the 180 response of the INVITE request before forwarding it as F8. The same applies to response F10 and the BYE request F16.
(next page on part 3)