Marking SIP Messages to Be Logged
Extracted elements (30)
Logging trigger conditions (e.g., time periods, User-Agent values, called party numbers) are explicitly left out of scope, allowing operators to configure marking for specific troubleshooting needs without constraining the protocol to a particular policy model.
The Session-ID header field (RFC 7989) was chosen to carry the 'logme' marker because it is typically passed through B2BUAs and intermediaries per Session-ID requirement REQ3 in RFC 7206, making it well-suited for end-to-end propagation without introducing device- or user-specific information.
A SIP proxy as defined in RFC 3261 cannot detect or handle 'log me' marking errors and will simply forward any 'log me' marker it receives. Only supporting UAs or B2BUAs can detect and handle marking errors.
Intermediaries that do not comply with RFC 8497 might pass the 'log me' marker unchanged or drop it entirely. This means marking may be absent or inconsistently present on parts of the path, and stateful entities on either side must handle these gaps gracefully.
A SIP intermediary is required to copy the 'log me' marker into forked requests. SIP request forking is discussed in RFC 3261.
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, on both originating and terminating sides.
If a dialog is to be 'log me' marked, marking MUST start with the SIP request that initiates that dialog (dialog-creating request). It is an error if 'log me' marking begins in a mid-dialog request or response.
If a 'log me' marking that begins mid-dialog error is detected, the entity MUST NOT forward the 'log me' marker, MUST NOT log the message, MUST NOT mark subsequent requests and responses, and MUST NOT log subsequent messages in the same dialog.
If a missing marker error is detected, the entity MUST NOT mark subsequent requests and responses and MUST stop logging messages in the same dialog. Previously logged messages SHOULD be retained.
If an endpoint/intermediary already 'log me' marking a dialog receives a SIP INVITE with a Join header field and without a 'log me' marker, it MUST NOT 'log me' mark the new dialog. Conversely, if not marking and receives an INVITE with Join and with 'log me', it MUST mark the new dialog.
Implementations of RFC 8497 MUST implement RFC 7989 (Session-ID header field), which defines the header field that carries the 'logme' parameter.
SIP entities MUST be configured to 'log me' mark only the dialogs needed for the current testing purpose, limiting scope to the minimum needed to troubleshoot a particular problem or perform a particular test.
SIP intermediaries that do not perform originating/terminating marking or B2BUA functions MUST simply log any request or response containing a 'log me' marker in a stateless manner, if allowed per local policy.
The 'log me' marker MUST be removed at a network boundary if no agreement exists between peer networks, because the marker may cause a SIP entity to log the SIP header and body of requests or responses.
The 'logme' parameter MUST be passed unchanged with the Session-ID header field through intermediaries, except where it is explicitly removed at a network boundary per Section 3.4.2.
The originating UA configured for 'log me' marking MUST insert a 'log me' marker into the dialog-creating SIP request and all subsequent in-dialog SIP requests.
The terminating UA MUST echo a 'log me' marker in responses to a SIP request that included a 'log me' marker. Additionally, 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.
Data stored at SIP intermediaries as a result of 'log me' marking should be retained only for the minimum period necessary for the troubleshooting purpose and then deleted. The recommended default is to not enable 'log me' logging unless explicitly configured by a user or administrator.
Logged SIP messages may contain personal identifiers such as SIP URIs, phone numbers, IP addresses, and communication patterns. Operators must apply appropriate data-protection measures to any stored logs and limit access to authorized personnel.
The 'logme' parameter itself carries no device-specific or user-specific information and does not fingerprint users; however, its presence in signaling visible at network elements reveals that the session is under diagnostic observation, which may itself be sensitive.
'Log me' marked dialogs MAY propagate marking to related dialogs for call control features such as call forward, transfer, park, and join (e.g., REFER, 3xx, INVITE with Replaces). Correlated logging uses Session-ID header field values across related dialogs.
The entire SIP message (request line, response line, header fields, and message body) SHOULD be logged. Logging SHOULD use SIP Common Log Format (CLF) per RFC 6873 or Libpcap. Header fields SHOULD NOT be converted between long and compact forms.
The local UUID portion of the Session-ID header field value in the initial SIP request of a dialog serves as a random test case identifier, enabling collation of all logged SIP requests and responses belonging to that dialog or standalone transaction.
The 'logme' parameter is added to the Session-ID header field (RFC 7989) to mark SIP signaling as being of interest to logging. The parameter carries no device-specific or user-specific information and is designed to pass through B2BUAs and other intermediaries end to end.
IANA registered the 'logme' parameter for the Session-ID header field in the 'Header Field Parameters and Parameter Values' registry under RFC 8497. The parameter has no predefined values and is defined by this document.
A 'log me' marker may cause SIP entities to log the full SIP header and body of requests and responses, creating a risk that logged data is exposed to unauthorized parties. Administrators MUST remove the marker at network boundaries where no inter-operator agreement exists.
An attacker could insert 'log me' markers into SIP traffic to trigger excessive logging and cause a denial-of-service condition. Implementations must apply authorization controls and rate-limiting to mitigate this risk.
'Log me' marking MUST be disabled by default at both endpoints and intermediaries and MUST be enabled only by authorized users. An end user or network administrator must give explicit permission for a terminal or intermediary to initiate marking.
Stateful intermediaries maintain per-dialog logging state: UNMARKED → LOGGING (triggered by detecting 'log me' in dialog-creating request), LOGGING → ERROR (triggered by unexpected missing marker or mid-dialog appearance), ERROR terminates all further marking and logging for that dialog.
The ABNF for the 'logme' parameter extends sess-id-param from RFC 7989: 'sess-id-param =/ logme-param' and 'logme-param = "logme"'. The parameter is a simple token with no value.