Connect sipnab to Homer - NormB/sipnab GitHub Wiki
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.
Tested on
Every block on this page ran as written, in order, on 2026-09-28, with sipnab 0.5.194 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.5 (kernel 6.8.0).
- It ran with OpenSIPS, from source and from the packages.
- It ran with Kamailio.
- It ran as a source on a second machine.
On Debian 13, 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"))')
curl -fsSLO https://github.com/NormB/sipnab/releases/download/v$V/sipnab_${V}_amd64.deb
curl -fsSL https://github.com/NormB/sipnab/releases/download/v$V/SHA256SUMS.txt \
| grep " sipnab_${V}_amd64.deb$" | sha256sum -c -
sudo apt-get install -y ./sipnab_${V}_amd64.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 -m 1 -bg
sipp -sf uac_rr.xml 192.0.2.10:5060 -i 192.0.2.10 -p 5080 -m 1 -d 1000 -timeout 20s
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
------------------------------------------------------------------------------------------------------
[email protected] sipp service Completed 200 1s 13
SOURCE PACKETS LAST SEEN IDLE STATE
hep:[email protected] 13 2026-09-26T21:25:09.115Z 6s sending
hep:101 is the hep_capture_id OpenSIPS stamps on everything it sends.
Homer received the same 13 messages.
- 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, Kamailio's
hep_capture_id.
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 so that Homer can report media quality. It never forwards RTP, the audio itself.
While it runs, place a call from the second machine through your SIP server. The callee still runs on the SIP server's machine:
# Run all of these, in order.
# On 192.0.2.10:
cd ~/sipp
sipp -sn uas -i 127.0.0.1 -p 5070 -m 1 -bg
# Run all of these, in order.
# On 192.0.2.20:
sudo apt-get install -y sip-tester
mkdir -p ~/sipp && cd ~/sipp
sipp -sd uac > uac_rr.xml
sed -i 's|<recv response="200" rtd="true">|<recv response="200" rtd="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
sipp -sf uac_rr.xml 192.0.2.10:5060 -i 192.0.2.20 -p 5080 -m 1 -d 1000 -timeout 20s \
-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:
[email protected]
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.
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.
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.