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, and sipnab --version prints the version when the install worked.
  • curl to download the two sample captures, and jq for 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.

  • -N skips the TUI.
  • --report prints the per-call table.
  • --no-cli-print leaves 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 200 answer,
  • 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 Trying after 6 ms,
  • 180 Ringing after 180 ms,
  • 200 OK after 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 Here under Signaling 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 timing object 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.