Repository navigation
Follow A Call
A call through a proxy keeps its Call-ID, so sipnab sees one call. A call through a back-to-back user agent (B2BUA) does not. A PBX such as Asterisk or FreeSWITCH, an SBC, and OpenSIPS with topology hiding end the call on one side and start a new one on the other, each with its own Call-ID. sipnab then holds two calls, or more across several hops, and ties them together.
This page shows how to list a call's other legs, how to read how sipnab tied each one, and what to change on your SIP servers so the tie is an exact match rather than a guess.
- A sipnab build with the default features, for everything except decoding
OpenSIPS topology-hiding Call-IDs, which needs the
tlsfeature. Every release package has it. - Reading a capture file needs no privileges. A live capture needs root or
CAP_NET_RAW. - A capture that holds every leg. Capture where the legs meet, on the B2BUA itself or on a link that carries both sides. sipnab cannot join a leg the capture does not hold.
- No change on any other system to list legs by the identifiers the capture already holds. You change your SIP servers only if you want an exact match where there is none today. Make the match exact says what to change for each server.
Name one leg with --correlate. This capture holds one call through an
Asterisk PBX: the caller's leg, and the leg Asterisk placed to the callee.
sipnab -I tests/pcap-samples/b2bua-asterisk.pcapng --correlate b2bua-caller-synth@203.0.113.1 --no-cli-print --quietLegs correlated with b2bua-caller-synth@203.0.113.1: 1 leg
Leg Strategy Method Score Match Gap ms
----------------------------------------------------------------------------------
b2bua-leg-synth@203.0.113.101:5060 timing_heuristic timing 50 guess 3
Every leg here is a timing guess: no identifier ties it to this call.
-
Strategynames the rule that tied the leg.Methodsays what sipnab compared the two legs on. -
Matchisidentifierwhen both legs carry the same identifier, andguesswhen only their timing and addresses tie them. -
Gap msis how far apart the two legs started, for a guess.
Here Asterisk wrote nothing into the callee's leg that names the caller's, so the tie is a guess. A guess can join unrelated calls on a busy server. Make the match exact changes it to an identifier match.
--report lists the Call-IDs a capture holds. The Call-ID must match exactly.
A call through an SBC and then a PBX has three legs or more. --call-tree
follows the ties leg by leg and prints the whole call. This capture's calls
cross one hop, so each tree has two legs:
sipnab -I tests/fixtures/session-id/opensips-4.0-th-session-id.pcap --call-tree 1-sid-call@example.com --no-cli-print --quietCall tree from 1-sid-call@example.com: 2 legs, depth 1, 13 messages, 0 timing guesses
Leg Strategy Method Score Match Followed
-----------------------------------------------------------------------------------------
1-sid-call@example.com root - - - yes
DLGCH_fl0WBzdkMzIjHCULKyg9IyMVSw08JA-- session_id header 100 identifier yes
- Each hop indents the leg two more spaces.
-
Followedisnoon a guess: sipnab lists the leg but does not look for that leg's own matches, so one wrong guess cannot pull in unrelated calls.
sipnab tries each strategy, and reports a leg under the highest-scoring one that matched.
| Strategy | Method | Score | What both legs carry | What it needs |
|---|---|---|---|---|
session_id |
header |
100 | The same RFC 7989 Session-ID
|
Endpoints or a server that send it. Nothing in sipnab |
th_callid_decoded |
decoded |
100 | A Call-ID that OpenSIPS topology_hiding("C") encoded, which decodes to the other leg's |
The OpenSIPS secret in [sip] th_callid_secret_file
|
th_callid_mapping |
mapping |
100 | Nothing: OpenSIPS sends sipnab the pair | An OpenSIPS event to sipnab's HEP listener |
x_call_id |
header |
100 | A header, named in [sip] xcid_headers, holding the other leg's Call-ID |
A header your server adds, and its name in sipnab's configuration |
charging_vector_related_icid |
header |
95 | An RFC 7315 P-Charging-Vector whose related-icid names the other leg's icid-value
|
An IMS or carrier B2BUA that sends it |
sdp_origin |
sdp |
90 | The same SDP origin line, while both legs were open, and an origin no two calls in the capture used on one hop at once | A server that passes SDP through unchanged, and endpoints that write a new origin for each call |
charging_vector_icid |
header |
85 | The same P-Charging-Vector icid-value
|
An intermediary that copied it onto the second leg |
via_branch |
header |
80 | A shared Via branch | A proxy hop, not a B2BUA |
timing_heuristic |
timing |
50 | Nothing: the legs started close together and share an address | Nothing. A guess |
Run MCP across an estate explains what each identifier proves and where it stops working.
Read the three fields of a leg in this order:
-
strategynames the rule that tied the leg. It is the decisive field: two strategies with one score are not the same claim. -
identifier_matchistruewhen the two legs carry one identifier, andfalsefortiming_heuristic, which is a guess. - The score orders the strategies. It is a rank, not a probability.
RFC 8866 section 5.2
says the origin line's username, session ID, network type, address type and
address are globally unique for a session. Not every endpoint follows that.
SIPp's built-in uac scenario writes
o=user1 53655765 2353687637 IN IP4 <ip> into every call, and some phones
and gateways write the same session ID into every call. So sipnab reports
sdp_origin only when both of these hold:
- The two legs were open at one time. A B2BUA sends the second leg before the first one's call setup ends, and both stay up for the call. Calls placed one after the other are not open at one time. The time runs from a leg's oldest message to its newest, whatever order sipnab read them in, and a leg that starts at the instant the other ended still counts.
- No two calls in the capture used the origin on one hop at once. A hop is the sending address and the receiving address and port of a leg's first message. Each leg of a B2BUA call is a different hop. A load test that places overlapping calls with one origin sends them all on one hop, and then the origin ties no leg to any other.
An origin line that does not have the six fields of RFC 8866, or whose session ID or version is not a number, ties nothing.
When the rule refuses a pair, a weaker strategy such as timing_heuristic can
still tie it, and sipnab reports it at that strategy's strength.
The rule says less than the truth in three cases:
- A B2BUA that forks one call to two contacts through one next hop.
- A spiral that sends one offer over one hop twice.
- Two capture points whose clocks differ by more than the call lasted.
In each case, give the legs an identifier from Make the match exact.
A SIPp scenario that writes a constant origin, as the built-in uac scenario
does, no longer ties its calls together by the origin:
- Calls placed one after the other each keep their own B2BUA legs.
- Calls that overlap on one hop tie nothing by the origin, not even a call's own B2BUA leg. The timing heuristic may still list legs as guesses.
To keep an identifier match in a load test, make the origin unique per call:
write o=caller [call_number] 1 IN IP[local_ip_type] [local_ip] in the
scenario, as harness/th-callid/uac.xml does,
or send Session-ID or a correlation header.
To check a capture, list the legs of one call:
sipnab -I tests/fixtures/th-callid/opensips-4.0-default.pcap --correlate 1-th-call@example.com --no-cli-print --quietLegs correlated with 1-th-call@example.com: 5 legs
Leg Strategy Method Score Match Gap ms TH
--------------------------------------------------------------------------------------------------
DLGCH_fl0RBn4qMT8jMAAWMiQgPypeBgE+ sdp_origin sdp 90 identifier - no_secret
2-th-call@example.com timing_heuristic timing 50 guess 999 -
DLGCH_fV0RBn4qMT8jMAAWMiQgPypeBgE+ timing_heuristic timing 50 guess 1000 no_secret
3-th-call@example.com timing_heuristic timing 50 guess 1999 -
DLGCH_fF0RBn4qMT8jMAAWMiQgPypeBgE+ timing_heuristic timing 50 guess 2000 no_secret
The call's own callee leg is the sdp_origin identifier match. The two later
calls, one and two seconds after, are timing guesses.
Pick one of these, in this order of preference.
Session-ID is a pair of identifiers that the two endpoints of a session
exchange, made to survive a B2BUA. sipnab reads it with no configuration, and
matches the two halves in either order.
This capture holds three calls through OpenSIPS with
topology_hiding("C"), which gives the callee's leg a new Call-ID. The
endpoints send Session-ID, and OpenSIPS passes it through unchanged:
sipnab -I tests/fixtures/session-id/opensips-4.0-th-session-id.pcap --correlate 1-sid-call@example.com --no-cli-print --quietLegs correlated with 1-sid-call@example.com: 1 leg
Leg Strategy Method Score Match Gap ms
-------------------------------------------------------------------------------------
DLGCH_fl0WBzdkMzIjHCULKyg9IyMVSw08JA-- session_id header 100 identifier -
Which servers send it:
-
Endpoints and SBCs. Check whether yours send it:
sipnab -N -I capture.pcap --filter "header.Session-ID =~ '.'" --reportlists the calls that carry it. -
FreeSWITCH writes it when a Sofia profile sets the
rfc-7989parameter totrue. FreeSWITCH reads the parameter insrc/mod/endpoints/mod_sofia/sofia.cof FreeSWITCH 1.11.3 (read on 2026-11-03). Not tested with sipnab. - OpenSIPS passes the header through unchanged, as the capture above shows for OpenSIPS 4.0.2 through topology hiding. A proxy forwards the header fields it does not act on (RFC 3261 section 16.6), so Kamailio as a proxy passes it too. Not tested here with Kamailio.
- A search of the OpenSIPS, Kamailio and Asterisk source code on GitHub on 2026-11-03 found no code that writes the header.
Have the B2BUA add a header to the callee's INVITE that holds the caller's Call-ID, then tell sipnab its name. This header names nothing standard, so sipnab looks for none until you name one.
This header discloses the caller's Call-ID to the callee's side. Add it only on legs inside your own network, or remove it where the call leaves.
Asterisk 22. A pre-dial handler sets the header on the outbound channel, from
the inbound channel's Call-ID. In extensions.conf:
[from-caller]
exten => 100,1,Dial(PJSIP/callee,30,b(add-xcid^s^1(${CHANNEL(pjsip,call-id)})))
same => n,Hangup()
[add-xcid]
exten => s,1,Set(PJSIP_HEADER(add,X-CID)=${ARG1})
same => n,Return()
Tested on 2026-11-03 with Asterisk 22.11.0: the callee's INVITE carried
X-CID: 1-xcid-call@example.com. The capture below is that test.
OpenSIPS with topology hiding. Add append_hf("X-CID: $ci\r\n"); after
topology_hiding("C"). Run sipnab beside OpenSIPS
shows the script and the tests that run it. OpenSIPS can also tell sipnab the
pair with no header at all. That section describes both.
Kamailio with the topology-hiding module and mask_callid = 1, which encodes
the Call-ID (module documentation,
read on 2026-11-03). Add the header in the request route before the request
leaves, with
append_hf:
append_hf("X-CID: $ci\r\n");
Not tested: the Kamailio build on this project's test host lacks that module. Check on the wire that the callee's INVITE carries the caller's Call-ID before you rely on it.
FreeSWITCH. Set a sip_h_ channel variable before the bridge. FreeSWITCH
adds a header named after the prefix to the outbound INVITE, and
sip_call_id holds the inbound leg's Call-ID
(channel variables,
read on 2026-11-03):
<action application="set" data="sip_h_X-CID=${sip_call_id}"/>
<action application="bridge" data="user/1000"/>Not tested with sipnab.
Name the header in the [sip] section of the configuration file:
[sip]
xcid_headers = ["X-CID"]Without it, the Asterisk capture's legs tie only by timing:
sipnab -I tests/fixtures/xcid/asterisk-22-xcid.pcap --correlate 1-xcid-call@example.com --no-cli-print --quietLegs correlated with 1-xcid-call@example.com: 1 leg
Leg Strategy Method Score Match Gap ms
------------------------------------------------------------------------------------
207e9af6-c60c-4f7f-99ae-328d569004c6 timing_heuristic timing 50 guess 5
Every leg here is a timing guess: no identifier ties it to this call.
With it, they tie on the header:
sipnab -I tests/fixtures/xcid/asterisk-22-xcid.pcap --config sipnab.toml --correlate 1-xcid-call@example.com --no-cli-print --quietLegs correlated with 1-xcid-call@example.com: 1 leg
Leg Strategy Method Score Match Gap ms
----------------------------------------------------------------------------------
207e9af6-c60c-4f7f-99ae-328d569004c6 x_call_id header 100 identifier -
xcid_headers takes a list, so one sipnab can read the headers of several
servers.
OpenSIPS with topology_hiding("C") can tie its legs for sipnab in two more
ways: sipnab decodes the hidden Call-ID with OpenSIPS's secret, or OpenSIPS
sends sipnab each pair as an event.
Calls through topology hiding
gives the steps for both.
When no identifier crosses a hop, the timing guess is what remains. It ties two legs that started within two seconds of each other and share an address. A PBX that looks a number up before it places the second leg (an LNP or ENUM query, a routing list) can start it later than that, and the guess then misses. Widen the window, in milliseconds:
sipnab -I tests/pcap-samples/b2bua-asterisk.pcapng --leg-correlation-window 8000 --correlate b2bua-caller-synth@203.0.113.1 --no-cli-print --quietThe configuration key is [sip] leg_correlation_window_ms. A wider window
also ties more unrelated calls on a busy server, which Gap ms shows.
| Where | How |
|---|---|
| Command line |
--correlate <CALL-ID>, --call-tree <CALL-ID>, each with --json
|
| REST |
GET /v1/dialogs/{call_id}/correlated, GET /v1/dialogs/{call_id}/tree
|
| MCP |
find_correlated, get_call_tree
|
| Terminal interface | In the call flow, x or F4 draws the related legs in one ladder |
| vCon | The sipnab-related-legs attachment of an exported call |
Every surface reports the same strategy and method for each leg. Under
--json, --correlate prints the answer the REST route returns:
sipnab -I tests/fixtures/session-id/opensips-4.0-th-session-id.pcap --correlate 1-sid-call@example.com --json --no-cli-print --quiet | jq -c '.legs[] | {call_id, strategy, method, identifier_match}'{"call_id":"DLGCH_fl0WBzdkMzIjHCULKyg9IyMVSw08JA--","strategy":"session_id","method":"header","identifier_match":true}The first line of the answer counts the legs sipnab tied to the call, and each row names one leg with the strategy that tied it:
sipnab -I tests/fixtures/session-id/opensips-4.0-th-session-id.pcap --correlate 1-sid-call@example.com --no-cli-print --quietLegs correlated with 1-sid-call@example.com: 1 leg
Leg Strategy Method Score Match Gap ms TH
------------------------------------------------------------------------------------------------
DLGCH_fl0WBzdkMzIjHCULKyg9IyMVSw08JA-- session_id header 100 identifier - no_secret
The match is exact when the Match column reads identifier: both legs carry
the same identifier, here a Session-ID header. The run exits with status 0
when it found the Call-ID you named.
A build without the tls feature prints - in the TH column.
| What you see | Why | What to do |
|---|---|---|
--correlate prints no legs |
The capture does not hold the other leg, or nothing ties it | Capture where both legs pass. Check with --report that both are there |
The legs tie with timing_heuristic although the server adds a header |
[sip] xcid_headers does not name the header, or sipnab did not read the configuration file |
Name the header. Pass --config with the file, and check that sipnab does not print that it ignores a configuration file |
The legs tie with timing_heuristic and a large Gap ms, or not at all |
The B2BUA placed the second leg later than the window | Widen --leg-correlation-window, or add an identifier |
| Unrelated calls appear as legs | Timing guesses on a busy server | Read Match. Add an identifier, so the guess is not needed |
Two legs that share an SDP origin are not tied by sdp_origin
|
The legs were not open at one time, or other calls in the capture used the origin on one hop at once | See When an SDP origin counts. Make the origin unique per call, or add an identifier |
Exit 1 and no dialog with Call-ID
|
The Call-ID is not in the capture, or is not exact | Copy it from --report
|
A topology-hiding leg reports th_callid undecodable or unmatched
|
The secret or prefix is wrong, or the caller's leg is missing | See Calls through topology hiding |
Website · Repository · Issues · Generated from docs/ — edit there, not here.
Getting started
- Installation
- First CLI Triage
- Glossary
- Cookbook
- Runnable Examples
- Real World Captures
- Troubleshooting
- Measure Call Quality
- Run as a Service
- Tuning Capture
- Encapsulations
- Capture With Least Privilege
- Collect and Forward HEP
- Read Captures From Archives
- Rtpengine Relays
- Ask a Media Relay About Itself
- Ask Each Calls rtpengine Engine
- Backers
Using the TUI
CLI & automation
- CLI Reference
- Error Messages
- Capture Queries
- Expectations
- Filter DSL
- Follow A Call
- Output Formats
- Stability
- SIP Response Codes
- SIP Methods
- SIP Header Fields
- SIP Parameters
- SIP Lint Rules
- MOS and Codecs
Configuration
Integrations (API & MCP)
- REST API
- Prometheus Metrics
- Authentication
- Require Client Certificates
- MCP
- MCP Deployment
- MCP Across an Estate
- Manage Many Instances
- MCP Tools
- MCP Tools Core
- MCP Tools Signaling
- MCP Tools Captures
- MCP Tools Security
- MCP Tools Media
- MCP Tools Relay
- MCP Tools TFPS
- MCP Tools Server
- MCP Tools vCon
- MCP Tools TLS
- MCP Protocol
- Uprobe Walkthrough
- Capture SIP over TLS
- WASM Plugins
- Run Commands and Send Alerts
- vCon Export
- vCon Capture Stack
- G729 Decoding
Your SIP server
- Use OpenSIPS as the SIP Server
- Run sipnab beside OpenSIPS
- Use Kamailio as the SIP Server
- Run sipnab beside Kamailio
- Use Asterisk as the PBX
- Run sipnab beside Asterisk
- Use FreeSWITCH in the Voice Stack
- Run sipnab beside FreeSWITCH
Add to your voice stack
- Add a vCon Server
- Send vCons to a vCon Server
- Send vCons to vcon store
- Add TFPS
- Control TFPS from sipnab
- Ban SIP Scanners with fail2ban
- Feed fail2ban from sipnab
- Add rtpengine
- Name rtpengine Media with sipnab
- Add rtpproxy
- Name rtpproxy Media with sipnab
- Add Homer
- Connect sipnab to Homer
- Add Prometheus and Grafana
- Add sipnab Metrics to Prometheus
Development & internals
- Internals Index
- Internals Subsystem Guide
- Internals Invariants
- Internals Testing
- Internals Walkthroughs
- Internals Build CI Release
- Internals Profiling
- Internals Domain Primer
- Library API
- Benchmarks
- Fault Model
- Threat Model
- Assurance Case
- Architecture
- Internals Threading
- Internals TUI Testing
- Internals Zero Copy Payloads
- Internals Uprobe Capture
- Internals Rtpengine Control Plane
- Internals Relay Control Decoding
- Internals vCon Exporter
- Internals Operator Guide Notes
- Internals Postmortems
- Internals Code Map
- Internals Lint Rules
- Internals Encapsulation Decoding
- Internals MCP Design Notes
- Internals Metrics And Output Notes