Learn how to debug SIP calls using Asterisk CLI, tcpdump, and Wireshark. Get step-by-step commands, file-size tricks, and best practices for VoIP engineers.
SIP debug in Action: Asterisk CLI to Wireshark & tcpdump
Published by Brav
Table of Contents
TL;DR
- I can spin up an Asterisk CLI SIP debug session and capture traffic with tcpdump, all without leaving my server.
- Writing the debug output to a file and opening it in Wireshark lets me spot every SIP message and the RTP payload that caused the drop.
- By using -s 0 and -C 100, I keep my pcap under 100 MB and rotate ten files, so disk space never becomes a blocker.
- I avoid missing audio glitches by capturing the full packet payload, not just headers.
- If I need long-term monitoring, I simply drop the -C 100 switch and let tcpdump roll me the logs I need.
Why This Matters
In a production VoIP farm, hundreds of calls can erupt in a heartbeat. When an engineer hits SIP set debug on all peers, the terminal floods with a million lines in seconds. The log scrolls away, the screen is full, and I can’t pick out the real problem. I used to copy huge text dumps to a spare laptop, hoping the sheer volume would show me the error, only to spend hours scrolling through noise.
- Debug output becomes too large to read when many peers are active.
- Wireshark can’t capture traffic on a remote server locally—so I had to SSH, pull a file, and open it.
- Filtering tcpdump to only SIP or specific ports may miss traffic that’s crucial for audio, like RTP packets or retransmissions.
- Full packet payloads triple the file size but are the only way to see the audio payload and validate that the RTP stream is intact.
- Long-term monitoring can exhaust disk space if I don’t limit the capture file size.
These pain points kept me from troubleshooting fast. When I switched to a method that captures the traffic, writes it to a file, and then analyzes it offline, I went from hours to minutes.
Core Concepts
| Parameter | Use Case | Limitation |
|---|---|---|
| SIP set debug | Turns on per-peer or global SIP logging in Asterisk. | Produces a flood of text; hard to read live. |
| Wireshark | GUI tool to dissect pcap files; shows SIP dialogs and RTP streams. | Only captures local traffic; needs file transfer for remote servers. |
| tcpdump | CLI tool that writes raw traffic to a pcap file. | Without options, only headers are captured; -s 0 needed for payload. |
SIP (Session Initiation Protocol) is the language that tells two endpoints how to open, modify, and close a call. Every INVITE, 200 OK, ACK, BYE is a SIP message that can be read in plain text. But the real voice lives in RTP (Real-Time Protocol) packets that travel on UDP ports. To debug an audio drop, you need to see that payload.
Asterisk is the most common open-source PBX. It has a powerful CLI that lets you enable debug for individual peers or for the whole system:
SIP set debug all 1 # Enable debug for every peer
SIP set debug 1234 1 # Enable debug for peer 1234 only
Wireshark can read any .pcap file, highlight SIP headers, and even reassemble RTP streams so you can play the audio directly. But if you want to debug a server in the data center, you need to capture the packets on that machine first.
tcpdump is the classic network sniffer that writes the raw bytes to a file. By giving it the right options you can capture everything, keep file sizes manageable, and rotate logs automatically.
Why Capture Full Packets?
When I debug a dropped call, I need to see the exact bytes that went out. A simple header might tell me that a packet went to port 5060, but I can’t tell if the payload was a valid DTMF tone or if the packet was garbled. Capturing the whole packet (-s 0) gives me a complete view, and Wireshark can reconstruct the audio so I can hear what the user actually heard.
Managing File Size
A 100 MB cap is a good rule of thumb. With -C 100 tcpdump will start a new file when it reaches that limit, and with -W 10 it will keep only ten files on disk. If I need 7 days of traffic, I set -W 10 and rely on a cron job to archive the old files.
How to Apply It
I use the same workflow every time I need to troubleshoot a VoIP issue. It works for small testbeds and large production farms.
1. Enable SIP Debug in Asterisk
$ asterisk -rvv
CLI> SIP set debug all 1 # or ***SIP set debug 1234 1***
This prints every SIP request and response to the console. If you have 500 peers, the output will be huge, so you’ll want to redirect it to a file right away.
2. Redirect the Debug Output to a File
$ asterisk -rvv > /tmp/asterisk_debug.log &
The & runs it in the background so you can keep using the terminal. Now you have a full text dump of every SIP message.
3. Capture All Traffic on the Server with tcpdump
$ sudo tcpdump -i eth0 -s 0 -C 100 -W 10 -w sip_capture.pcap
- -i eth0 – interface that your VoIP traffic passes through.
- -s 0 – snap length of 0 captures the entire packet, not just headers.
- -C 100 – rotate when the file reaches 100 MB.
- -W 10 – keep only 10 rotated files.
- -w sip_capture.pcap – write to disk.
I often add -n to avoid DNS lookups and -vv for more verbose output, but the basics are the four switches above. With -C 100 I know my disk will never be full even if the network is busy.
4. Let the Capture Run While You Work
If you’re debugging a long-running call, let tcpdump keep capturing until the issue resolves. If you’re only interested in a short burst, you can stop it with Ctrl+C or by killing the process.
5. Transfer the pcap to Your Local Machine
$ scp user@server:/tmp/sip_capture.pcap* ~/Desktop/
The ******* pulls all rotated files. On my laptop, I now have sip_capture.pcap, sip_capture.pcap.1, … sip_capture.pcap.9.
6. Open the pcap in Wireshark
Launch Wireshark, drag and drop the files. Wireshark will automatically merge rotated files into a single stream.
7. Filter SIP and RTP Traffic
In the display filter box type:
sip || rtp
This will show only SIP messages and RTP packets, letting me see call flows and any missing or garbled audio.
8. Reassemble and Play the Audio
Click on a SIP dialog, right-click “Follow” → “UDP Stream” → “Save as audio file”. I can then play the resulting .wav file and verify that the user heard a clear tone.
9. Correlate with the Asterisk Log
I open /tmp/asterisk_debug.log and match timestamps with the Wireshark timeline. If a 408 Request Timeout appears in the log, I look at the packets around that time to see if the RTP stream stopped.
10. Repeat or Archive
Once I’ve found the root cause, I stop the capture, archive the pcap, and reset debug levels:
CLI> SIP set debug all 0
This keeps my system clean and ensures I don’t keep dumping millions of lines.
Pitfalls & Edge Cases
| Issue | What Happens | Mitigation |
|---|---|---|
| Huge debug logs | The console floods and I lose context. | Redirect to a file or limit debug to specific peers. |
| File rotation stops | tcpdump stops capturing when disk is full. | Use -C 100 -W 10 or set up disk quotas. |
| Missing RTP | I see SIP but no audio. | Verify that -s 0 was used; check -w path. |
| Encrypted audio | Wireshark shows payload as Encrypted RTP. | Can’t be decoded unless keys are available. |
| Remote capture limitations | Wireshark can’t see traffic on the server. | Capture on the server with tcpdump; pull file. |
| Out-of-order packets | Call seems broken but packets are fine. | Use Wireshark’s “Reassemble” feature. |
Sometimes I forget to exit the Asterisk CLI after enabling debug. When I do, the console scrolls away, and I lose the first few hundred lines. I’ve built a habit of piping the output to a file right away. Also, I never use -C 0 because that tells tcpdump to write to a single file forever, which quickly fills my /var/log partition.
Quick FAQ
Q: How does Wireshark capture traffic on a remote server if run locally?
A: Wireshark itself can’t sniff traffic on a different machine; you need to run tcpdump on the remote server and then transfer the pcap file to your local machine to analyze it.
Q: What is the best way to filter tcpdump if I want to capture all relevant traffic without missing issues?
A: Capture everything with -s 0 and let Wireshark filter later. A common filter is port 5060 || port 5061 || udp. This captures SIP and any RTP that lands on typical UDP ports.
Q: How do I handle encrypted audio streams for debugging?
A: If the traffic is SRTP or TLS-wrapped, Wireshark can’t decrypt it without keys. You’ll need to capture the TLS handshake and provide the keys, or work with the vendor to get the SRTP keying material.
Q: What are the best practices for long-term tcpdump monitoring beyond file size limits?
A: Use -C with a reasonable size (e.g., 100 MB) and -W to keep a set number of rotated files. Combine this with a cron job that archives old files to another storage tier.
Q: What is the difference between -s 0 and -C 100 options in tcpdump?
A: -s 0 sets the snapshot length to 0, meaning capture the entire packet payload. -C 100 tells tcpdump to rotate the file when it reaches 100 MB. They serve different purposes: one ensures completeness, the other controls disk usage.
Q: Will rotating 10 files of 100 MB each be sufficient for high traffic environments?
A: For many deployments, 1 GB of capture is enough for a day’s worth of traffic. If you need more, increase -W or reduce -C. Monitor disk usage; if you see high churn, consider a dedicated capture server.
Conclusion
I’ve spent countless hours chasing a “silent call” or a “missing DTMF” and finally got the answers by combining Asterisk’s debug output, tcpdump’s raw capture, and Wireshark’s analysis power. The key takeaways:
- Capture first, then analyze. A single pcap file is your single source of truth.
- Keep logs under control. Use -C 100 -W 10 so disk space never becomes a blocker.
- Capture full packets. You can’t debug audio without payloads.
- Use Wireshark filters. Don’t let the file size overwhelm you; filter for SIP and RTP first.
- Archive and rotate. Store older captures on a separate volume or cloud bucket.
If you’re a VoIP engineer or a DevOps professional managing a SIP infrastructure, start implementing this workflow today. You’ll spend less time hunting in endless logs and more time delivering clear, high-quality voice for your users.
