Docs Connect sipnab to Homer
Connect sipnab to Homer
Have sipnab receive the SIP proxy's HEP beside Homer, and have sipnab on another machine forward what it captures to Homer.
On this page
Homer and sipnab both speak HEP. HEP is the protocol SIP servers use to send Homer a copy of their traffic. So they connect in either direction:
- sipnab as a second receiver.
- Your SIP server sends the same HEP copies to sipnab as to Homer.
- Homer keeps the history.
- sipnab analyzes the calls as they happen, with no capture on the wire at all.
- sipnab as a source.
- This is for a machine that runs no SIP server of its own, or one whose SIP server cannot send HEP.
- sipnab captures the traffic and forwards it to Homer, under a capture id of its own.
This guide sets up both against the stack from Add Homer to your voice stack. That stack can use:
- OpenSIPS from its packages or built from source,
- Kamailio, as that guide’s With Kamailio section sets it up.
The sipnab as a second receiver step differs for Kamailio, and says how. The sipnab as a source for Homer step is the same for both.
Before you start
- The stack from Add Homer to your voice stack, with its test
call stored in Homer. The steps here reuse its SIPp files in
~/sipp. - root on each machine that runs sipnab. The steps use
sudo. - On the other system that sends HEP, your SIP server:
- OpenSIPS gains a second HEP destination, and the step restarts it.
- Kamailio either does not change, or its
duplicate_urimoves from Homer to sipnab. The step says which.
- On the Homer machine:
- Nothing changes when sipnab is a second receiver.
- When sipnab is a source on a second machine, the Homer machine’s firewall must let that machine reach UDP port 9060.
- On the phones and carriers, nothing changes.
Tested on
Every block on this page ran as written, in order, on 2026-10-01, with sipnab 0.5.199 from its release package.
- The machines were clean x86_64 virtual machines with 2 cores and 3 GB of
memory:
- Debian 13 (kernel 6.12.63),
- Ubuntu 24.04 (kernel 6.8.0).
- The test calls carried real audio both ways.
- It ran with OpenSIPS, from source and from the packages.
- It ran with Kamailio.
- The second machine in the sipnab as a source for Homer step was a network namespace on the same virtual machine. It had its own address, its own link and its own capture, and shared the first machine’s files.
That run predates the RTCP form described in the sipnab as a source for Homer step: sipnab 0.5.199 sent RTCP without the call’s Call-ID, and Homer stored none of it.
On 2026-11-03 the sipnab as a source for Homer step ran again, with sipnab 0.5.232 built from source, on Ubuntu 24.04.5 (aarch64, kernel 6.8.12) with Docker 29.9.2:
- Homer was the stack from Start Homer, unchanged: heplify-server 1.60.9, homer-app 1.5.21 and PostgreSQL 17.11.
- No SIP server or SIPp ran. sipnab captured the loopback interface while
tcpreplayreplayedtests/pcap-samples/Asterisk_ZFONE_XLITE.pcap, a call with SDP and RTCP, and sent HEP to heplify-server on the Docker bridge address. - Homer stored the call’s 13 SIP messages under capture id 2002, and 7 RTCP
reports in
hep_proto_5_defaultwith the call’s Call-ID as theirsid. - The sipnab as a second receiver step did not run again: it needs a SIP server sending HEP to two places.
On both systems, causing the first fault under When something does not work produced what it describes. The second needs a firewall between two machines, and did not run.
The examples use two addresses. Replace them with yours.
192.0.2.10is the machine that runs the SIP proxy and Homer.192.0.2.20is the second machine.
Install sipnab
On each machine that runs 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
sipnab as a second receiver
Send OpenSIPS’s HEP to sipnab as well. OpenSIPS’s tracer sends to every
destination defined under the same trace name.
- Add a second HEP destination,
sipnab, on UDP port 9062. - Put it under the name
tidthattrace()already uses. - The first line finds your configuration file, the packages’ or a source build’s:
# Run all of these, in order.
for f in /etc/opensips/opensips.cfg /usr/local/etc/opensips/opensips.cfg; do sudo test -f "$f" && C=$f && break; done
sudo sed -i '/^modparam("tracer", "trace_id", "\[tid\]uri=hep:homer")$/a modparam("proto_hep", "hep_id", "[sipnab] 127.0.0.1:9062; transport=udp; version=3")\nmodparam("tracer", "trace_id", "[tid]uri=hep:sipnab")' "$C"
sudo grep -nE 'hep_id|trace_id' "$C"
sudo opensips -C -f "$C"
sudo systemctl restart opensips
The grep shows:
- the two destinations,
homerandsipnab, - the two
trace_idlines that name them.
Listen, and place a call. Start sipnab’s HEP listener for 30 seconds:
sudo sipnab -N -L 127.0.0.1:9062 --duration 30 --report --hep-senders
While it runs, place a test call from a second terminal. Do it as in the Place a test call step of the Homer 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 each message as it arrives, marked origin=hep. When the 30
seconds are up, it prints the call and who sent it:
Call-ID From To State Code Duration Msgs PDD Tags
-------------------------------------------------------------------------------------------------------------------------
1-19569@192.0.2.10 sipp echo Completed 200 9s 13 0.0s -
HEP senders (trust unauthenticated, silent after 30s)
received 13 admitted 13 refused 0 from untracked senders 0
SOURCE PACKETS LAST SEEN IDLE STATE
hep:101@127.0.0.1 13 2026-10-01T13:58:35.376Z 15s sending
hep:101 is the hep_capture_id OpenSIPS stamps on everything it sends.
Homer received the same 13 messages.
The call carried audio, but sipnab here sees only what OpenSIPS sends it: the
SIP messages. Its end-of-run line reports 0 RTP packets across 0 streams.
- The capture id is what the sender claims. Nothing proves it.
- What keeps other senders out here is the address. sipnab listens on
127.0.0.1, which only this machine can reach.
To keep the listener running, give the packaged service the same arguments in a drop-in. Send sipnab’s vCons to a vCon server does the same for its own flags.
With Kamailio. Kamailio’s siptrace sends its copies of every message to
one destination, its duplicate_uri.
-
A second
duplicate_uriline does not add a destination. It replaces the first, and Homer receives nothing. -
So with Kamailio, choose one of two ways:
-
Keep Homer as the destination, and let sipnab watch the wire.
- sipnab on the Kamailio machine sees every message as it passes, both legs.
- This needs no change to Kamailio at all.
- Run sipnab beside Kamailio sets it up.
-
Send Kamailio’s copies to sipnab instead of Homer.
- Point
duplicate_uriat sipnab’s listener. - Homer then receives nothing from Kamailio until you point it back:
- Point
# Run all of these, in order.
sudo sed -i 's|"duplicate_uri", "sip:127.0.0.1:9060"|"duplicate_uri", "sip:127.0.0.1:9062"|' /etc/kamailio/kamailio.cfg
sudo grep -n duplicate_uri /etc/kamailio/kamailio.cfg
sudo kamailio -c -f /etc/kamailio/kamailio.cfg
sudo systemctl restart kamailio
Then start sipnab’s listener and place the test call as above. The report shows
the call Completed with 13 messages. They come from hep:101@192.0.2.10:
Kamailio’s hep_capture_id, sent from the machine’s own address. Homer stores
none of that call.
sipnab as a source for Homer
On the second machine, sipnab captures SIP off the wire and forwards it to heplify-server. Give it a capture id of its own. Then Homer can tell its copies from your SIP server’s:
sudo sipnab -N -d any -H 192.0.2.10:9060 --hep-id 2002 --duration 30
sipnab forwards SIP, and RTCP as HEP type 5. It never forwards RTP, the audio itself.
sipnab sends each RTCP report in the form Homer stores:
- The report is JSON, as heplify sends it.
- It carries the Call-ID of the call it belongs to, as its correlation ID. heplify-server stores an RTCP report only under that ID, and Homer shows it in the call’s media quality (QoS) view.
- sipnab finds the call from the SDP that set up the media. RTCP for a call whose SDP sipnab did not capture is not sent, because Homer would store none of it.
SIPp sends no RTCP of its own, so the SIPp test call below gives sipnab no RTCP to forward, and the call’s QoS view stays empty. A call between phones that send RTCP fills it.
While sipnab runs, place a call from the second machine through your SIP
server. The callee still runs on the SIP server’s machine. -mi gives it the
machine’s own address for its audio, so that the caller on the second machine
can reach it:
# Run all of these, in order.
# On 192.0.2.10:
cd ~/sipp
sipp -sn uas -i 127.0.0.1 -mi 192.0.2.10 -p 5070 -rtp_echo -m 1 -bg
# Run all of these, in order.
# On 192.0.2.20:
sudo apt-get install -y sip-tester
mkdir -p ~/sipp/pcap && cd ~/sipp
ln -sf /usr/share/sip-tester/*.pcap pcap/
sipp -sd uac_pcap > uac_rr.xml
sed -i 's|<recv response="200" rtd="true" crlf="true">|<recv response="200" rtd="true" crlf="true" rrs="true">|' uac_rr.xml
sed -i -E 's#^( *)(ACK|BYE) sip:\[service\]@\[remote_ip\]:\[remote_port\] SIP/2.0#\1\2 [next_url] SIP/2.0\n\1[routes]#' uac_rr.xml
sudo sipp -sf uac_rr.xml 192.0.2.10:5060 -i 192.0.2.20 -p 5080 -s echo -m 1 -timeout 90s \
-trace_msg -message_file uac.msg
grep -m1 -i '^Call-ID:' uac.msg
Find sipnab’s copies in Homer. Homer now holds the call twice:
- once from the SIP server, capture id 101,
- once from sipnab, capture id 2002.
On the Homer machine, use the Call-ID the last command printed:
# Run all of these, in order.
# On 192.0.2.10:
CALL=1-1234@192.0.2.20
cd /opt/homer
docker compose exec -T db psql -U root -d homer_data -c \
"select protocol_header->>'captureId' as capture_id, count(*)
from hep_proto_1_call where data_header->>'callid' = '$CALL' group by 1"
The test call gave 13 messages under capture id 101 and 7 under 2002.
- The SIP server sees both legs of the call.
- sipnab, on the second machine, sees the messages on that machine’s own link. That is the caller’s leg.
- sipnab saw the call’s audio there too, 246 RTP packets each way, and forwarded none of it.
Find the call’s RTCP. heplify-server stores RTCP in its own table, under the call’s Call-ID:
# Run all of these, in order.
# On 192.0.2.10:
cd /opt/homer
docker compose exec -T db psql -U root -d homer_data -c \
"select protocol_header->>'captureId' as capture_id, count(*)
from hep_proto_5_default where sid = '$CALL' group by 1"
The SIPp call above sends no RTCP, so this finds no row for it. For a call between phones that send RTCP it counts the reports sipnab forwarded. The 2026-11-03 run under Tested on, a replayed call with RTCP, counted 7 under capture id 2002.
HEP over UDP carries no authentication of its own. heplify-server accepts it from anyone who can reach port 9060. So open that port only to:
- your SIP servers,
- the machines where sipnab forwards.
Check that it worked
As a second receiver. Run the listener again, and place a test call while it runs:
sudo sipnab -N -L 127.0.0.1:9062 --duration 30 --report --hep-senders
- The report lists the call as
Completed. - The line under
HEP sendersends withrefused 0. - The table has a row for your SIP server’s capture id,
hep:101@127.0.0.1with OpenSIPS on the same machine.
As a source. The count query of
sipnab as a source for Homer has a row for
capture id 2002.
- A row for 101 and none for 2002 means that Homer did not receive sipnab’s copies.
- A HEP listener names what sipnab forwards in the same way. It lists the
sender as
hep:2002@and the address the copies came from.
When something does not work
- sipnab shows no messages. Check that the SIP server sends to it.
- For OpenSIPS,
sudo grep hep_idon its configuration file lists both destinations. - For Kamailio,
sudo grep duplicate_uri /etc/kamailio/kamailio.cfgnames sipnab’s port. - Then check that sipnab listens on that port.
- For OpenSIPS,
- sipnab’s copies are missing from Homer. Check two things:
- The second machine can reach UDP port 9060 on the Homer machine.
- sipnab’s capture saw the call. Run it with
--reportand look for the Call-ID.
Collect and forward HEP adds a shared secret, HEP over TCP and TLS,
and what a collector outage costs a --hep-send agent.