Docs Run sipnab beside OpenSIPS
Run sipnab beside OpenSIPS
Install sipnab on the OpenSIPS machine and watch a call through the proxy as one call, from both its legs, with or without Kamailio beside it.
On this page
sipnab reads the SIP that passes through OpenSIPS off the wire. So it needs nothing from OpenSIPS: no module, no configuration change. The one exception is optional: for calls through topology hiding, the OpenSIPS script can send sipnab each call’s two Call-IDs, a change to the script only (Have OpenSIPS send the mapping).
On the OpenSIPS machine, sipnab sees both legs of every call:
- the caller’s side into OpenSIPS,
- OpenSIPS’s side out to the callee.
It puts them together into one call.
This guide adds sipnab to the OpenSIPS proxy from Use OpenSIPS as your voice stack’s SIP server, installed from the packages or built from source.
Before you start
- The OpenSIPS proxy from
Use OpenSIPS as your voice stack’s SIP server, with its
test call working. The steps here reuse its SIPp files in
~/sipp. - root on that machine. sipnab captures there, and the steps use
sudo. - On the other system, OpenSIPS, nothing changes for every step up to Calls through topology hiding. Two of that section’s three methods change the OpenSIPS script, and its table says what each changes.
- On the phones and carriers, nothing changes.
Tested on
Every block on this page above Calls through topology hiding ran as written, in order, on 2026-10-01, with sipnab 0.5.198 from its release package. That section names the checks that cover it.
- It ran on the Debian 13 (kernel 6.12.63) and Ubuntu 24.04 (kernel 6.8.0)
machines that the OpenSIPS guide had set up:
- the Watch a call through OpenSIPS step with OpenSIPS from source,
- With Kamailio on the same machine with the OpenSIPS packages.
- The test calls carried audio.
- The terminal interface showed each call on one row.
- On both machines, causing the fault under When something does not work produced the message it quotes.
The examples use 192.0.2.10 as the machine’s address.
Install sipnab
# Run all of these, in order.
V=$(curl -fsSL https://api.github.com/repos/NormB/sipnab/releases/latest \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"].lstrip("v"))')
A=$(dpkg --print-architecture)
curl -fsSLO https://github.com/NormB/sipnab/releases/download/v$V/sipnab_${V}_${A}.deb
curl -fsSL https://github.com/NormB/sipnab/releases/download/v$V/SHA256SUMS.txt \
| grep " sipnab_${V}_${A}.deb$" | sha256sum -c -
sudo apt-get install -y ./sipnab_${V}_${A}.deb
sipnab --version
Watch a call through OpenSIPS
Start sipnab on every interface for 30 seconds. It prints each SIP message as it passes, and a report of the calls at the end:
sudo sipnab -N -d any --duration 30 --report
While it runs, place a test call from a second terminal. Do it as in the Place a test call step of the OpenSIPS guide:
# Run all of these, in order.
cd ~/sipp
sipp -sn uas -i 127.0.0.1 -p 5070 -rtp_echo -m 1 -bg
sudo sipp -sf uac_rr.xml 192.0.2.10:5060 -i 192.0.2.10 -p 5080 -s echo -m 1 -timeout 90s
sipnab prints every message OpenSIPS relays twice, once on each leg:
- the caller’s
INVITEto OpenSIPS at192.0.2.10:5060, - then OpenSIPS’s copy of it to the callee at
127.0.0.1:5070, - and the same for the replies and the
BYE.
OpenSIPS’s own 100 Giving it a try goes to the caller alone.
When the 30 seconds are up, the report lists the call once:
- It shows the call as
Completed, with 13 messages from both legs. - Below it, an
RTP Streams:table holds the call’s audio.- The audio goes straight between the caller and the callee. It never goes through OpenSIPS.
- The table shows the caller’s 236
PCMApackets and 10telephone-event(DTMF) packets. - It shows the same again coming back from the callee’s echo.
- That is four streams in all.
You can get the same view in a terminal interface, which updates as calls
happen. Run sudo sipnab -d any without -N and without --duration. It
lists the call on one row, Completed, with the same 13 messages.
With Kamailio on the same machine
OpenSIPS and Kamailio on one machine sets up OpenSIPS on 5060 and Kamailio on 5062. With that setup, give sipnab both ports:
sudo sipnab -N -d any --duration 30 --report --portrange 5060-5062
A call through each proxy then appears in the report, one row per call.
- The two test calls send their audio from the same ports with the same RTP SSRC.
- sipnab starts a new stream when the second call’s SDP renegotiates those ports.
- So the
RTP Streams:table lists each call’s streams on rows of their own:- 236
PCMApackets each way for each call, - not one stream of 472 across both.
- 236
Calls through topology hiding
topology_hiding("C") gives the callee’s leg a different Call-ID from the
caller’s leg. OpenSIPS builds it from the caller’s Call-ID:
- XOR each byte with
th_callid_passwd. - Encode the result in a base64 variant.
- Put
th_callid_prefix(DLGCH_by default) in front.
OpenSIPS also strips Via, Record-Route and Route, and replaces Contact. Without help, sipnab can tie the two legs only by timing, which is a guess.
The C flag changes the Call-ID only when the call has a dialog
(create_dialog()). Without a dialog, OpenSIPS leaves the Call-ID alone.
There are three ways to tie the legs exactly. None of them needs an OpenSIPS module built or patched for sipnab: each uses modules that ship with OpenSIPS.
| Method | What changes in OpenSIPS | What sipnab needs | On a capture file (-I) | Discloses anything to the callee’s side | Modules OpenSIPS loads |
|---|---|---|---|---|---|
| Have OpenSIPS send the mapping | The script only: load a module, subscribe at startup, raise one event per call | --hep-listen on the address the script names, --hep-allow with OpenSIPS’s address, and a capture filter that keeps SIP | No, live only: sipnab takes the event from its listener, never from a capture | No | tm, dialog and topology_hiding, which C needs anyway, and event_datagram |
| Decode the hidden Call-ID | Nothing | [sip] th_callid_secret_file with the OpenSIPS th_callid_passwd, [sip] th_callid_prefix when OpenSIPS changes it, and a build with the tls feature (every release package) | Yes | No | tm, dialog and topology_hiding, which C needs anyway |
| Copy the Call-ID into a header | The script only: one append_hf line | [sip] xcid_headers naming the header | Yes | Yes: the caller’s Call-ID, in the header | tm, dialog and topology_hiding, which C needs anyway, and sipmsgops for append_hf |
sipnab reports which method joined a leg in method: mapping, decoded or
header.
Have OpenSIPS send the mapping
OpenSIPS knows both Call-IDs: $ci is the caller’s, and
$TH_callee_callid is the one it writes on the callee’s leg. The script
sends sipnab one small UDP datagram per call that names both. This needs no
secret, and the SIP is still what sipnab captures.
1. What this changes
This is a change to the OpenSIPS script only, with no module to build or
patch: it uses the stock event_datagram module, the core script functions
subscribe_event and raise_event, and the $TH_callee_callid variable of
the stock topology_hiding module.
E_SIPNAB_TH_MAP is a name the script chooses. OpenSIPS needs no declaration
for it: the first subscribe_event or raise_event that names an unknown
event publishes it (fixup_event_name in core_cmds.c calls
evi_publish_event, in every release from 3.1.0 to 4.0.2). The harness
confirms it: OpenSIPS 4.0.2 logs Registered event <E_SIPNAB_TH_MAP(9)> at startup.
2. Prerequisites
- OpenSIPS 4.0.2, 4.0.1 or 3.6.9. These are the versions
harness/th-mapping/e2e.shruns. For other versions, the OpenSIPS source says:- 3.1.0 to 3.6.8 and 4.0.0 have everything this uses:
$TH_callee_callid,event_datagram,subscribe_event, andraise_eventwith lists of names and values. Theirevent_datagramsends the same JSON-RPC 2.0 notification (evi_build_payload). sipnab has not run against them. - 3.0 and 2.4 have
$TH_callee_callidandevent_datagram, but theirevent_datagramsends the event as text, onename::valueper line, not as JSON. sipnab takes that datagram for a HEP packet and refuses it:/v1/hep/senderscounts it underrefused_by_reason.malformed. Use the decode there.
- 3.1.0 to 3.6.8 and 4.0.0 have everything this uses:
- These modules loaded:
tm,dialogandtopology_hiding, which a script withtopology_hiding("C")already loads, andevent_datagram. Thetopology_hidingREADME liststmas required, anddialogwhen the script creates a dialog, asCneeds. - An IPv4 address for sipnab’s listener. OpenSIPS’s
event_datagramsends UDP to an IPv4 address only: its source passessizeof(struct sockaddr_in)tosendto.
3. The OpenSIPS script change
Three additions, each in its own place.
Load the module, with the other loadmodule lines:
loadmodule "event_datagram.so"
Subscribe sipnab’s listener to the event once, at startup. Put the
startup_route at the top level of the script, next to route:
startup_route {
subscribe_event("E_SIPNAB_TH_MAP", "udp:127.0.0.1:9060");
}
Raise the event right after topology_hiding("C"), in the branch that
handles a new INVITE. That branch comes after the check for in-dialog
requests (has_totag()), so a re-INVITE or a BYE never reaches it. Raise it
before OpenSIPS relays the request (t_relay()):
if (!create_dialog() || !topology_hiding("C")) {
send_reply(500, "Internal Server Error");
exit;
}
$avp(th_keys) = "caller_call_id";
$avp(th_vals) = $ci;
$avp(th_keys) = "callee_call_id";
$avp(th_vals) = $TH_callee_callid;
raise_event("E_SIPNAB_TH_MAP", $avp(th_keys), $avp(th_vals));
$TH_callee_callid has a value only after topology_hiding("C") on a
request with a dialog. The topology_hiding README says it is NULL
otherwise, so raised anywhere else, the event cannot name the callee’s
Call-ID.
A retransmitted INVITE runs the same branch again and raises the event again.
That is harmless: the caller’s Call-ID is the same, so the callee’s Call-ID
OpenSIPS builds from it is the same, and sipnab counts the repeat as
duplicate and changes nothing.
OpenSIPS sends a JSON-RPC 2.0 notification:
{"jsonrpc":"2.0","method":"E_SIPNAB_TH_MAP","params":{"callee_call_id":"DLGCH_fl0RBn4kMSMPFR0PPjk8NmETCgM-","caller_call_id":"1-th-map@example.com"}}
A complete minimal opensips.cfg with these lines follows. It is the
script the harness runs. OpenSIPS listens on 192.0.2.10, sipnab on the
same machine, and the example sends every call to one callee at
192.0.2.1:5070. Set mpath to the directory your OpenSIPS build or
package installs its modules in. mi_fifo is there for the opensips-cli
check in step 5, and the event does not need it.
log_level=3
stderror_enabled=yes
udp_workers=2
socket=udp:192.0.2.10:5060
# The directory your OpenSIPS build or package installs its modules in.
mpath="/usr/local/lib64/opensips/modules/"
loadmodule "signaling.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "sipmsgops.so"
loadmodule "dialog.so"
loadmodule "topology_hiding.so"
loadmodule "maxfwd.so"
loadmodule "rr.so"
loadmodule "proto_udp.so"
loadmodule "event_datagram.so"
# For opensips-cli: the MI FIFO, at /tmp/opensips_fifo by default.
loadmodule "mi_fifo.so"
startup_route {
subscribe_event("E_SIPNAB_TH_MAP", "udp:127.0.0.1:9060");
}
route {
if (!mf_process_maxfwd_header(10)) {
send_reply(483, "Too Many Hops");
exit;
}
if (has_totag()) {
if (is_method("ACK") && t_check_trans()) {
t_relay();
exit;
}
if (!loose_route() && !topology_hiding_match()) {
send_reply(404, "Not here");
exit;
}
t_relay();
exit;
}
if (is_method("CANCEL")) {
if (t_check_trans())
t_relay();
exit;
}
if (!is_method("INVITE")) {
send_reply(503, "Service Unavailable");
exit;
}
if (!create_dialog() || !topology_hiding("C")) {
send_reply(500, "Internal Server Error");
exit;
}
$avp(th_keys) = "caller_call_id";
$avp(th_vals) = $ci;
$avp(th_keys) = "callee_call_id";
$avp(th_vals) = $TH_callee_callid;
raise_event("E_SIPNAB_TH_MAP", $avp(th_keys), $avp(th_vals));
# Your routing goes here. This example sends every call to one callee.
$du = "sip:192.0.2.1:5070";
if (!t_relay())
send_reply(500, "Internal Error");
exit;
}
4. The sipnab side
Run sipnab with:
--hep-listenon the address and port the subscription names,--hep-allowwith the address OpenSIPS sends the event from. With both on one machine and the subscription on127.0.0.1, as here, that is127.0.0.1. With sipnab on another machine, it is OpenSIPS’s address,- a capture filter that keeps the SIP.
sudo sipnab -N -d any --hep-listen 127.0.0.1:9060 --hep-allow 127.0.0.1/32 --duration 30 --report 'udp port 5060 or udp[8] & 0xc0 = 0x80'
The filter matters. With --hep-listen as well as -d and no filter of
your own, the interface takes media only, because sipnab expects a HEP
mirror to deliver the signaling, and taking it off the wire too would count
every message twice. Here the SIP is on the wire, so the filter keeps UDP
port 5060 and RTP. sipnab prints a notice at startup when it sees
--hep-allow with that default filter.
--hep-listen and --hep-allow are command-line flags only, with no
configuration-file key. The interface and the filter can go in the
configuration file instead:
[capture]
device = "any"
bpf_filter = "udp port 5060 or udp[8] & 0xc0 = 0x80"
sudo sipnab -N --hep-listen 127.0.0.1:9060 --hep-allow 127.0.0.1/32 --duration 30 --report
[sip] th_mapping_max and [sip] th_mapping_ttl_secs set how many
mappings sipnab holds and for how long (see Limits).
5. Verify it works
On OpenSIPS, list the event’s subscribers through the MI. OpenSIPS 4.0
names the command evi:subscribers, and 3.6 names it subscribers_list:
sudo opensips-cli -o fifo_file=/tmp/opensips_fifo -x mi evi:subscribers
sudo opensips-cli -o fifo_file=/tmp/opensips_fifo -x mi subscribers_list
opensips-clitalks to themi_fifomodule. With no-o, it opens/var/run/opensips/opensips_fifo, andmi_fifocreates/tmp/opensips_fifounless the script sets itsfifo_name. Aopensips-cli.cfgthat names the FIFO makes the-ounnecessary.- OpenSIPS 4.0 also accepts
subscribers_listas an old name, butopensips-clirefuses it before asking, withno command 'subscribers_list' in module 'mi'.
The answer names the event, sipnab’s address and "expire": "never". This
one comes from the harness, where sipnab listens on 192.0.2.1:9617:
{
"Events": [
{
"name": "E_SIPNAB_TH_MAP",
"id": 9,
"Subscribers": [
{
"socket": "udp:192.0.2.1:9617",
"expire": "never"
}
]
}
]
}
An empty "Events": [] means the subscription failed: see
Troubleshooting.
On sipnab, run it as a server with the REST API, place a call, and ask:
sudo sipnab -N -d any --hep-listen 127.0.0.1:9060 --hep-allow 127.0.0.1/32 --api 127.0.0.1:8080 'udp port 5060 or udp[8] & 0xc0 = 0x80'
The counts under th_mappings rise by one per call:
curl -s http://127.0.0.1:8080/v1/stats | jq -c .th_mappings
{"accepted":3,"conflict":0,"duplicate":0,"expired":0,"held":3,"malformed":0,"pending":0,"refused_full":0}
The caller’s leg names the callee’s leg, joined by mapping:
curl -s http://127.0.0.1:8080/v1/dialogs/1-th-docs@example.com/correlated | jq '[.legs[] | select(.method == "mapping") | {call_id, strategy, method, score}]'
[
{
"call_id": "DLGCH_fl0RBn4tPzA8MAAWMiQgPypeBgE+",
"strategy": "th_callid_mapping",
"method": "mapping",
"score": 100
}
]
The callee’s leg reports th_callid mapped:
curl -s 'http://127.0.0.1:8080/v1/dialogs/DLGCH_fl0RBn4tPzA8MAAWMiQgPypeBgE+/correlated' | jq '{th_callid, legs: [.legs[] | select(.method == "mapping") | {call_id, strategy, method, score}]}'
{
"th_callid": "mapped",
"legs": [
{
"call_id": "1-th-docs@example.com",
"strategy": "th_callid_mapping",
"method": "mapping",
"score": 100
}
]
}
At the end of a run, sipnab logs what the events did:
INFO sipnab::app::batch: Topology hiding: 3 E_SIPNAB_TH_MAP event(s): 3 accepted, 0 duplicate, 0 conflicting, 0 malformed, 0 refused (table full); 0 expired; 3 held now, 0 waiting for their SIP.
The other legs in a /correlated answer are timing guesses about the
other calls, and the filter above drops them.
6. Troubleshooting
The harness caused each row below on purpose with OpenSIPS 4.0.2, except
where the row says otherwise. GET /v1/hep/senders gives the
listener’s counts, and GET /v1/stats gives th_mappings.
| Symptom | Cause | Fix |
|---|---|---|
accepted stays 0, and /v1/hep/senders counts the events under refused_by_reason.event_sender_not_listed | The listener has no --hep-allow. It still starts on a loopback address, or with --hep-auth | Add --hep-allow with the address OpenSIPS sends from |
accepted stays 0, and the events count under refused_by_reason.allowlist | --hep-allow lists other addresses, but not the one OpenSIPS sends from | Add that address. With both on one machine and the subscription on 127.0.0.1, it is 127.0.0.1 |
accepted rises, pending stays above 0, and the legs do not join | The capture drops the SIP: with --hep-listen, -d and no filter of your own, the interface takes media only. sipnab says so at startup (no BPF filter was given, so the interface takes media only) and at the end of the run (3 waiting for their SIP) | Give a filter that keeps the SIP, as in The sipnab side |
Nothing arrives: packets_received stays 0 on /v1/hep/senders, and the end of the run says dialog(s) carry an OpenSIPS hidden Call-ID and no secret is configured | The subscription names an IPv6 address. OpenSIPS takes the first : for the port separator, refuses udp:[2001:db8::1]:9060 with no message at log_level=3, and evi:subscribers shows "Events": [] | Give the subscription an IPv4 address |
| The same | The subscription names a port other than the one --hep-listen binds | Make the two the same |
| The same | A firewall drops UDP from OpenSIPS to the listener. Not caused in the harness | Allow UDP from OpenSIPS’s address to the listener’s port |
conflict rises, sipnab logs conflicts with a mapping already held for one of them; neither joins, and the callee’s leg reports th_callid conflict | Two events named one Call-ID with different partners. The harness caused it with OpenSIPS 4.0.2 and th_callid_loop_protection, when a second INVITE reused a Call-ID with a new From tag: the hidden Call-ID then differs. A second program sending events from an address --hep-allow lists causes it too | sipnab joins neither leg on purpose, because it cannot tell which event is right. Check that only OpenSIPS sends from the listed addresses, and that the script raises the event only in the new-INVITE branch. For callers that reuse a Call-ID, decode the hidden Call-ID instead: the decode also checks the From tag |
refused_full rises, and sipnab logs the mapping table is full ([sip] th_mapping_max) | More calls started within [sip] th_mapping_ttl_secs than [sip] th_mapping_max allows. The harness set th_mapping_max = 1 and placed three calls: 1 accepted, 2 refused | Raise [sip] th_mapping_max, or lower [sip] th_mapping_ttl_secs |
/v1/hep/senders counts the events under refused_by_reason.malformed, and th_mappings stays at 0 | OpenSIPS 3.0 or older, whose event_datagram sends the event as text rather than JSON. Checked by sending a datagram in that format to sipnab, not with OpenSIPS 3.0 | Decode the hidden Call-ID instead |
malformed rises | The datagram is not an E_SIPNAB_TH_MAP event naming both Call-IDs. The harness renamed caller_call_id in the script. Run sipnab with SIPNAB_LOG=debug to see why: here E_SIPNAB_TH_MAP datagram refused (missing_call_id). | Use the key names caller_call_id and callee_call_id, exactly as in The OpenSIPS script change |
What sipnab does with the event
- It reads the event on the HEP listener: a datagram that starts with
{is an event, and one that starts withHEP3is HEP. Events come over UDP only. - It accepts an event only from a sender
--hep-allowlists. An event carries no HEP authentication, so--hep-authcannot vouch for it. A listener with no--hep-allowrefuses every event, and counts each under the refusal reasonevent_sender_not_listed. - The two legs join with
methodmappingandstrategyth_callid_mapping, whichever arrives first: the event or the SIP. The callee’s leg reportsth_callidmapped. - A repeated event, as a retransmitted INVITE raises, changes nothing.
- sipnab refuses an event that maps either Call-ID to a different partner. The
mapping already held for it stops joining too, and the callee’s leg
reports
th_callidconflict. sipnab cannot tell which of the two is right, so it joins neither.
Counts
The counts are on REST GET /v1/stats and the MCP tool capture_status
under th_mappings, with the fields accepted, duplicate, conflict,
malformed, refused_full, expired, held and pending. Prometheus has
sipnab_th_mapping_events_total{outcome}, sipnab_th_mappings_expired_total,
sipnab_th_mappings_held and sipnab_th_mappings_pending. The terminal
interface’s statistics view lists them, and a run ends with a line that
says what the events did.
Limits
- sipnab holds at most
[sip] th_mapping_maxmappings (100000), and drops one when neither of its legs has been in the store for[sip] th_mapping_ttl_secs(300). It refuses an event larger thanMAX_EVENT_BYTES(4096) bytes. - Mappings arrive live, on the listener. sipnab never takes an event from a
capture, even one that recorded the datagrams, so for a file read with
-Iuse the decode. - OpenSIPS sends the event to an IPv4 address only (see Prerequisites).
Decode the hidden Call-ID
OpenSIPS side: no change. sipnab side: a file with the OpenSIPS secret. This method also works on a capture file.
Put the OpenSIPS th_callid_passwd in a file, on one line. Only the account
that runs sipnab may read it: mode 600, or 640 with that account’s group.
Then name the file:
[sip]
th_callid_secret_file = "/etc/sipnab/th_callid.secret"
# th_callid_prefix = "DLGCH_" # set this when OpenSIPS sets th_callid_prefix
- sipnab reads the file once at startup and never prints or logs the secret.
- It refuses to start when the file is world-readable, is empty or holds a NUL byte.
- Only a file can hold the secret. There is no command-line flag or environment variable for it.
- Decoding needs a sipnab built with the
tlsfeature. Every release package has it.
When OpenSIPS keeps its default secret, set
th_callid_secret = "opensips-default" instead. The OpenSIPS source
publishes that secret, so it hides nothing. sipnab logs a warning at startup
that says so.
The legs join only when both of these hold:
- the decoded value equals the other leg’s Call-ID,
- the two legs have the same From tag.
OpenSIPS does not change tags, so a wrong secret cannot join two legs.
A decoded leg reports strategy th_callid_decoded and method decoded
on all of these:
--correlateand--call-tree,GET /v1/dialogs/{call_id}/correlatedandGET /v1/dialogs/{call_id}/tree,- the MCP tools
find_correlatedandget_call_tree, - the
sipnab-related-legsattachment of a vCon export.
In the terminal interface, the call flow’s status line says
Legs: 1 decoded, and on the hidden leg also Topology hiding: decoded.
The extended view (F4) draws both legs in one ladder.
For a hidden leg, --correlate, REST and MCP also return th_callid, which
says what happened:
decoded: the legs joined.no_secret: sipnab has no secret configured.undecodable: the secret or the prefix does not decode this Call-ID.unmatched: the value decoded, but no captured leg has that Call-ID and From tag. Either the caller’s side was not captured or the secret is wrong. A wrong secret that shares bytes with the right one can decode part of a Call-ID, so it can show here.
At the end of a run over a capture file, sipnab warns when hidden legs did not join, with the count and the settings to check. For example, with the wrong secret:
Topology hiding: 3 hidden Call-ID(s) did not decode to the captured caller leg that has their From tag, so those legs are not joined. Check [sip] th_callid_secret_file and th_callid_prefix against OpenSIPS's th_callid_passwd and th_callid_prefix.
The OpenSIPS source uses the same XOR and alphabet in every release from
2.4.11 to 4.0.2. OpenSIPS 4.0 adds th_callid_loop_protection, which
appends the caller’s From tag before encoding. sipnab decodes both forms,
and checks the appended tag against the From tag.
Or copy the Call-ID into a header
OpenSIPS side: a one-line script change. sipnab side: the header’s name. The header discloses the caller’s Call-ID to the callee’s side.
Without the secret, OpenSIPS can carry the caller’s Call-ID to the callee in a
header. Inside the script, $ci is the caller’s Call-ID even with the C flag:
if (!create_dialog() || !topology_hiding("C")) {
send_reply(500, "Internal Server Error");
exit;
}
append_hf("X-CID: $ci\r\n");
Then tell sipnab the header’s name:
[sip]
xcid_headers = ["X-CID"]
The legs then join with method header.
This header discloses the caller’s Call-ID to the callee’s side, which is part of what topology hiding exists to hide. Use it only when the callee is inside your own network, or remove the header where the call leaves it. When the configuration names both the secret and the header, sipnab reports the decoded match.
What checks this section
harness/th-mapping/e2e.sh
runs OpenSIPS with
harness/th-mapping/opensips.cfg.tmpl,
the complete opensips.cfg above, and a live sipnab that captures the
network with the filter above and receives the events on --hep-listen. It
places three calls with SIPp, and fails unless REST reports each callee leg
joined to its own caller leg by mapping. On 2026-11-03 it passed with
OpenSIPS 4.0.2, 4.0.1 and 3.6.9. It runs the sudo sipnab command above with
the test network’s interface and addresses, and with --api in place of
--duration 30 --report, so it can ask REST how each leg joined.
tests/th_mapping_test.rs
checks that the complete opensips.cfg on this page is that template with
127.0.0.1:9060 for sipnab’s address, line for line, and that the three
blocks of step 3 are in it. It also replays
tests/fixtures/th-mapping/opensips-4.0-events.pcap
into a live listener: events after the SIP and before it, repeats, a
conflict, a listener with no --hep-allow, and the end-of-run line.
harness/th-mapping/capture.sh
recorded that capture from OpenSIPS 4.0.2, with the template as it was
before it loaded mi_fifo, and the JSON datagram above is its first event.
On 2026-11-03 these were also run by hand, against the harness’s network:
- the
opensips-clicommands of step 5, withopensips-clifrom its source repository:evi:subscriberson OpenSIPS 4.0.2 and 4.0.1,subscribers_liston 3.6.9. In the harness the FIFO sits in a directory shared with the container, so-o fifo_filenamed that path and-o fifo_reply_dirthe same directory. - the
curlcommands and the end-of-run line of step 5, on OpenSIPS 4.0.2, 4.0.1 and 3.6.9. - OpenSIPS and sipnab on one machine, with the subscription and
--hep-allowon127.0.0.1, on OpenSIPS 4.0.2 and 3.6.9./v1/hep/sendersnamed the sender127.0.0.1. Ports 5060 and 9060 were in use on that machine, so the run used others. - the configuration-file form of step 4, on OpenSIPS 4.0.2.
- a retransmitted INVITE on OpenSIPS 4.0.2: two events,
1 accepted, 1 duplicate, and the legs joined. - every row of the troubleshooting table, on OpenSIPS 4.0.2, except where the row says otherwise.
On 2026-11-02, test calls went through OpenSIPS 4.0.2 and 3.6.9 with
harness/th-callid/capture.sh. Its
OpenSIPS script contains the append_hf lines above as shown. The captures
are in tests/fixtures/th-callid/, and the tests in
tests/th_callid_test.rs run sipnab against
them on the command line, REST and MCP, including the warning quoted above.
Check that it worked
Place a test call while this runs:
sudo sipnab -N -d any --duration 30 --report
- The report lists the call on one row, though sipnab saw it on both sides of OpenSIPS.
- The row shows
Completed, code200and 13 messages. - An
RTP Streams:table follows it.
When something does not work
- sipnab reports a line such as
No SIP signaling found, but 839 RTP packets across 2 stream(s) were parsed.The counts are your run’s own.- It saw the call’s audio, which uses other ports, but none of its SIP.
- OpenSIPS listens on a port outside 5060-5061, the range sipnab watches by default.
- Give sipnab OpenSIPS’s ports with
--portrange.