Docs Triage a capture from the command line
Triage a capture from the command line
On this page
Your first analysis without the TUI, one command at a time. You list the calls in a capture and find the ones that went wrong. You explain one of them and hand the answer to another tool as JSON.
Every command reads a file, so none of them needs root.
- Each step shows the output it prints.
- sipnab also writes progress lines, such as
Reading from 'sample-call.pcap', to stderr. The outputs below leave those out. - The Glossary defines any term you do not recognize.
Before you start
- sipnab on your
PATH. Any release binary or package works: these steps use no optional feature. Installing sipnab has every route, andsipnab --versionprints the version when the install worked. curlto download the two sample captures, andjqfor the last step, Hand the answer to another tool.- No privileges. Every command reads a file.
- No change on any other system. The steps read two downloaded files and contact no SIP server, relay or collector.
What ran: every command and output on this page ran on 2026-11-10 with sipnab 0.5.244 on Linux, against the two sample captures as the repository holds them.
Download a capture
Download the sample call the website uses. It holds:
- one phone call between Alice and Bob,
- the registrations, subscriptions and keepalives around it.
curl -LO https://sipnab.com/demos/sample-call.pcap
List the calls
Ask for one line per dialog. A dialog is every SIP message that shares a Call-ID.
-Nskips the TUI.--reportprints the per-call table.--no-cli-printleaves out the per-message lines. Without it, they would come first.
sipnab -N -I sample-call.pcap --report --no-cli-print
The table comes first, then the RTP streams:
Call-ID From To State Code Duration Msgs PDD Tags
-------------------------------------------------------------------------------------------------------------------------
reg-alice-4f2a19@192.0.2.10 alice alice Registered 200 0s 4 - -
reg-bob-7c3d02@192.0.2.30 bob bob Expired 200 14s 8 - -
sub-alice-mwi-2b81@192.0.2.10 alice alice Active 200 0s 3 - -
sub-bob-blf-9e42@192.0.2.30 bob bob Pending 202 0s 3 - -
sub-alice-pres-5c07@192.0.2.10 alice alice Terminated 200 14s 6 - -
opt-8b7c02@192.0.2.20 pbx alice Completed 200 0s 2 - -
call-2c9d47@192.0.2.10 alice bob Completed 200 8s 7 0.2s -
RTP Streams:
SSRC PT Codec Clock Source Destination Pkts Lost Loss% Jitter Dur Kbps
--------------------------------------------------------------------------------------------------------------------------
0x1a2b3c4d 0 PCMU 8000 192.0.2.10:10000 192.0.2.20:10002 300 0 0.0% 0ms 6s 64
0x5e6f7a8b 0 PCMU 8000 192.0.2.20:10002 192.0.2.10:10000 300 0 0.0% 0ms 6s 64
Read it left to right. The last row is the phone call. It is an INVITE that:
- got a
200answer, - lasted 8 seconds,
- waited 0.2 seconds for the first ringing response. That wait is the PDD (post-dial delay).
The two streams below it are the call’s audio. There is one per direction, with no loss.
The rows above it are not calls. sipnab tracks these as dialogs too:
- registrations (
reg-), - subscriptions (
sub-), - an OPTIONS keepalive (
opt-).
The Code column is the final response to the request that opened each
dialog. For these rows that is the REGISTER, SUBSCRIBE or OPTIONS answer:
200, or 202 for the subscription Bob’s phone opened.
Find the calls that went wrong
--problems keeps only the dialogs that failed, or that show:
- one-way audio,
- high loss or jitter,
- a NAT mismatch,
- retransmits,
- slow setup,
- a media asymmetry.
Combined with --report, it prints the same table, filtered to those calls:
sipnab -N -I sample-call.pcap --problems --report --no-cli-print
On the sample, the table is empty apart from its header. Nothing in it went wrong. An empty answer is a result: sipnab looked at every call and found no problem.
To see what a problem looks like, download a second sample from the repository. It holds five calls. Four of them failed:
curl -LO https://github.com/NormB/sipnab/raw/main/tests/pcap-samples/sip-problem-call.pcap
sipnab -N -I sip-problem-call.pcap --problems --report --no-cli-print
Call-ID From To State Code Duration Msgs PDD Tags
-------------------------------------------------------------------------------------------------------------------------
busy-3a2b1c@192.0.2.30 carol dave Failed 486 1s 4 - -
decline-7c6d5e@198.51.100.30 erin frank Failed 603 1s 4 - -
notfound-1b2c3d@203.0.113.30 grace heidi Failed 404 1s 4 - -
unavail-4e5f60@192.0.2.50 ivan judy Failed 503 1s 4 - -
The completed call drops out. The four failures remain, each with the response code that ended it:
- busy,
- declined,
- not found,
- unavailable.
Explain one call
Pick a Call-ID from the table and ask for its report. Set it in a shell variable first:
- Most Call-IDs contain an
@. - Some contain characters the shell would otherwise interpret.
CALL_ID='call-2c9d47@192.0.2.10'
sipnab -N -I sample-call.pcap --call-report "$CALL_ID" --no-cli-print
Call Report: call-2c9d47@192.0.2.10
════════════════════════════════════════
Time: 2023-11-14 22:13:25 -> 22:13:33 (8s)
From: "Alice" <sip:alice@...>
To: <sip:bob@...>
Result: Completed (BYE)
Frame: sample-call.pcap#19@db3d2ea0ae5df067
Timing:
PDD: 0.18s
Setup: 2.42s
Ring: 2.24s
Teardown: 0.01s
Retransmits: 0
SIP Transactions:
INVITE (SDP) -> 100 (6ms) -> 180 (180ms) -> 200 (SDP) (2420ms)
ACK
BYE -> 200 (8468ms)
Media Streams:
RTP 192.0.2.10->192.0.2.20 PCMU SSRC=0x1a2b3c4d pkts=300 jitter=0ms loss=0.0% mos=4.36 R=90.8
RTP 192.0.2.20->192.0.2.10 PCMU SSRC=0x5e6f7a8b pkts=300 jitter=0ms loss=0.0% mos=4.36 R=90.8
Issues Detected: None
The SIP Transactions line is the call in one row. The INVITE got:
100 Tryingafter 6 ms,180 Ringingafter 180 ms,200 OKafter 2.4 seconds, when Bob answered.
Frame names the packet the report starts from. You can find the same bytes
in Wireshark. Issues Detected: None is the verdict.
Try the same command on sip-problem-call.pcap with
CALL_ID='busy-3a2b1c@192.0.2.30'.
- Its report ends with
Final failure: 486 Busy HereunderSignaling Issues. - It names the message that says so.
Hand the answer to another tool
--json prints one JSON object per SIP message. jq can slice it. This
lists the call’s messages in order, with the time of each:
sipnab -N -I sample-call.pcap --json | jq -r --arg id "$CALL_ID" 'select(.call_id == $id) | [.timestamp, .method // (.status_code | tostring)] | @tsv'
2023-11-14T22:13:25+00:00 INVITE
2023-11-14T22:13:25.006+00:00 100
2023-11-14T22:13:25.180+00:00 180
2023-11-14T22:13:27.420+00:00 200
2023-11-14T22:13:27.430+00:00 ACK
2023-11-14T22:13:33.460+00:00 BYE
2023-11-14T22:13:33.468+00:00 200
--json-dialogs prints one JSON object per call instead.
- It leaves out the per-message lines by itself, so its output is JSON only.
- Its
timingobject carries the numbers from the report, in milliseconds:
sipnab -N -I sample-call.pcap --json-dialogs --no-cli-print | jq --arg id "$CALL_ID" 'select(.call_id == $id) | .timing'
{
"pdd_ms": 180,
"retransmits": 0,
"ring_ms": 2240,
"setup_ms": 2420,
"teardown_ms": 8,
"trying_delay_ms": 6
}
Check that it worked
Count the dialogs sipnab found in the sample. jq -s length counts the JSON
objects on its input:
sipnab -N -I sample-call.pcap --json-dialogs --no-cli-print | jq -s length
7
Seven is the number of rows in the table of List the calls. The last progress line on stderr gives the totals for the same file:
sipnab: 633 packets captured, 33 SIP messages, 600 RTP packets across 2 streams
Each command on this page exits with status 0 when it read the capture, even when the answer is empty.
When something does not work
Each of these ends with exit status 1.
-I/--input: 'sample-call.pcap' does not exist. The file is not in the
current directory. Run the curl command of
Download a capture again, or give -I the path of the
file.
-I/--input: cannot read capture 'sample-call.pcap' named with -I: Failed to open pcap file 'sample-call.pcap': libpcap error: unknown file format.
The file is not a capture. A download that failed can leave an HTML error page
under the capture’s name. Download it again.
Call-ID 'nosuch@example.com' not found in tracked dialogs.
--call-report got a Call-ID the capture does not hold, here
nosuch@example.com. Copy the Call-ID from the first column of the
--report table, and keep the single quotes around it: without them the shell
reads characters such as ; or & in a Call-ID as its own.
The --problems table has a header and no rows. That is the answer for a
capture with no failed or impaired call, as
Find the calls that went wrong shows.
For a message that is not listed here, look it up in the error reference.
Where to go next
- Troubleshooting starts from a complaint. Examples are one-way audio or a call that drops after 30 seconds. It says which command answers it.
- Examples & recipes has a recipe for each task, from live capture to scanner blocking.
- Output formats lists every JSON field these commands print.
- TUI walkthrough reads the same capture interactively.