What is sngrep?
sngrep is a terminal-based SIP (Session Initiation Protocol) message flow viewer and analyser. It’s designed to help VoIP engineers, telecom professionals, and network administrators to monitor, capture, and troubleshoot SIP traffic in real-time. Think of it as a specialized “wireshark for SIP” that runs in your terminal.
Key Features:
- Real-time SIP message capture and display
- Terminal-based interface with colour-coding
- Message flow visualization
- Powerful filtering capabilities
- Export functionality to PCAP files
- Support for various SIP scenarios (calls, registrations, etc.)
Installation
On Ubuntu/Debian:
sudo apt update
sudo apt install sngrep
On CentOS/RHEL/Fedora:
# For CentOS/RHEL 7/8
sudo yum install epel-release
sudo yum install sngrep
# For Fedora
sudo dnf install sngrep
On Arch Linux:
sudo pacman -S sngrep
From Source (if not available in repositories):
# Install dependencies
sudo apt install libncurses5-dev libpcap-dev git autoconf
# Clone and compile
git clone https://github.com/irontec/sngrep.git
cd sngrep
./configure
make
sudo make install
Basic Usage and Interface
Starting sngrep
Basic capture (requires root privileges):
sudo sngrep
Specify network interface:
sudo sngrep -d eth0
Read from PCAP file:
sngrep -I capture.pcap
Interface Navigation
Once sngrep is running, you’ll see a list of SIP calls. Here are the key controls:
- Enter: View detailed message flow for selected call
- Space: Select/deselect call for actions
- F1: Help menu
- F2: Save selected calls to PCAP
- F3: Search/Filter calls
- F4: Extended information panel
- F10/q: Quit
- Arrow Keys: Navigate through calls
- ESC: Go back to call list
Command-line Options
Basic Options:
# Capture on specific interface
sudo sngrep -d eth0
# Set custom capture port
sudo sngrep -p 5060
# Read from file
sngrep -I /path/to/file.pcap
# Save output to file
sudo sngrep -O /path/to/output.pcap
# Non-interactive mode (just capture)
sudo sngrep -N
# Rotate capture files
sudo sngrep -R 10 # Rotate every 10 calls
Filtering Options:
# Filter by IP address
sudo sngrep host 192.168.1.100
# Filter by specific call-id
sudo sngrep call-id 12345@192.168.1.1
# Filter by method (INVITE, REGISTER, etc.)
sudo sngrep "INVITE"
# Filter by source/destination
sudo sngrep src 192.168.1.100
sudo sngrep dst 192.168.1.200
Practical Examples
Example 1: Monitoring SIP Registration
# Monitor only REGISTER messages
sudo sngrep "REGISTER"
Use Case: When troubleshooting why SIP phones are not registering with your Asterisk/FreeSWITCH server.
Example 2: Debugging Call Setup Issues
# Monitor calls involving specific extension
sudo sngrep "9876543210"
Use Case: Customer complains that calls to mobile number 9876543210 are failing.
Example 3: Monitoring Specific SIP Trunk
# Monitor traffic from/to telecom provider's SIP gateway
sudo sngrep host 203.0.113.10
Use Case: Debugging connectivity issues with your telecom service provider (like Airtel, Jio, BSNL).
Example 4: Capturing for Later Analysis
# Capture SIP traffic and save for analysis
sudo sngrep -O sip_capture_$(date +%Y%m%d_%H%M%S).pcap
Use Case: Capturing evidence of call quality issues to share with your telecom provider.
Example 5: Monitoring Internal Extension Calls
# Monitor calls between internal extensions (100-199 range)
sudo sngrep "sip:1[0-9][0-9]@"
Use Case: Troubleshooting internal call routing in your office PBX system.
Real-world Use Cases in Indian Context
1. Telecom Service Provider Troubleshooting
Scenario: You’re working for a telecom operator and customers are complaining about call drops.
# Monitor specific customer's calls
sudo sngrep "sip:9876543210@" -O customer_calls.pcap
# Check for specific error codes
# Look for 486 (Busy Here), 408 (Request Timeout), etc.
2. Corporate PBX Debugging
Scenario: Employees in Mumbai office can’t make calls to Delhi office.
# Monitor inter-office trunk
sudo sngrep host delhi-pbx.company.com
# Check for authentication failures
sudo sngrep "401\|407"
3. Call Centre Quality Monitoring
Scenario: Call centre in Bangalore experiencing poor call quality.
# Monitor all calls and check RTP statistics
sudo sngrep -d eth0 -O callcentre_$(date +%H%M).pcap
# Filter by specific agent extensions
sudo sngrep "sip:agent[0-9]+@"
4. SIP Trunk Provider Issues
Scenario: Your Airtel SIP trunk is rejecting calls intermittently.
# Monitor trunk gateway traffic
sudo sngrep host airtel-sip-gateway.com
# Look for specific rejection codes
# Press F3 in sngrep and search for "403\|404\|503"
5. Hotel/Resort PBX Monitoring
Scenario: Guest complaints about international call billing issues.
# Monitor international calls (starting with 00)
sudo sngrep "sip:00[0-9]+"
# Capture for billing verification
sudo sngrep -O intl_calls_$(date +%Y%m%d).pcap
Advanced Filtering Techniques
1. Time-based Filtering
# Capture for specific duration (using timeout)
timeout 300 sudo sngrep -O 5min_capture.pcap
2. Multiple Condition Filtering
# Monitor calls from specific IP to specific destination
sudo sngrep "src 192.168.1.100 and dst 203.0.113.50"
3. Error Code Monitoring
# Monitor only failed calls
sudo sngrep "4[0-9][0-9]\|5[0-9][0-9]\|6[0-9][0-9]"
4. Protocol-specific Filtering
# Monitor only UDP SIP traffic
sudo sngrep udp
# Monitor only TCP SIP traffic
sudo sngrep tcp
Understanding SIP Call Flow
When you press Enter on a call in sngrep, you’ll see the message flow. Here’s how to interpret it:
Normal Call Flow:
Caller Callee
| |
|-------- INVITE -------->|
|<------- 100 Trying -----|
|<------- 180 Ringing ----|
|<------- 200 OK ---------|
|-------- ACK ----------->|
| |
|<====== RTP AUDIO ======>|
| |
|-------- BYE ----------->|
|<------- 200 OK ---------|
Common Error Scenarios:
1. Busy Signal:
|-------- INVITE -------->|
|<------- 486 Busy -------|
|-------- ACK ----------->|
2. Authentication Failure:
|-------- INVITE -------->|
|<------- 401 Unauthorized|
|-------- ACK ----------->|
3. Network Issues:
|-------- INVITE -------->|
|-------- INVITE -------->| (Retransmission)
|-------- INVITE -------->| (Retransmission)
| | (Request Timeout)
Troubleshooting Common Issues
1. No SIP Traffic Visible
Causes:
- Wrong network interface
- SIP traffic on non-standard port
- Encrypted SIP (TLS)
Solutions:
# List network interfaces
ip link show
# Try different interface
sudo sngrep -d enp0s3
# Try different port
sudo sngrep -p 5061
# Check if traffic exists
sudo tcpdump -i any port 5060
2. Permission Denied
Cause: sngrep needs root privileges for live capture
Solution:
# Run with sudo
sudo sngrep
# Or add user to wireshark group (Ubuntu/Debian)
sudo usermod -a -G wireshark $USER
# Logout and login again
3. High CPU Usage
Cause: Too much traffic or no filtering
Solutions:
# Apply filters to reduce load
sudo sngrep host 192.168.1.100
# Use non-interactive mode for long captures
sudo sngrep -N -O capture.pcap
Best Practices
1. Regular Monitoring Setup
Create a script for daily monitoring:
#!/bin/bash
# daily_sip_monitor.sh
DATE=$(date +%Y%m%d)
sudo sngrep -O /var/log/sip/sip_traffic_$DATE.pcap &
echo $! > /var/run/sngrep.pid
2. Log Rotation
# Add to crontab for automatic cleanup
0 0 * * * find /var/log/sip -name "*.pcap" -mtime +7 -delete
3. Performance Optimization
# For high-traffic environments
sudo sngrep -N -R 1000 -O /var/log/sip/capture.pcap
# This will:
# -N: Non-interactive mode
# -R 1000: Rotate every 1000 calls
# -O: Output to file
4. Integration with Monitoring Systems
# Export to syslog for integration with monitoring tools
sudo sngrep -N | logger -t sngrep
Useful Keyboard Shortcuts Summary
| Key | Action |
|---|---|
| Enter | View call details |
| Space | Select/deselect call |
| F1 | Help |
| F2 | Save selected calls |
| F3 | Search/Filter |
| F4 | Show extended info |
| F10/q | Quit |
| c | Clear call list |
| r | Refresh display |
Common SIP Response Codes to Watch For
Success Codes (2xx):
- 200 OK: Request successful
- 202 Accepted: Request accepted
Client Error Codes (4xx):
- 401 Unauthorized: Authentication required
- 403 Forbidden: Request forbidden
- 404 Not Found: User not found
- 408 Request Timeout: Request timeout
- 486 Busy Here: Callee is busy
Server Error Codes (5xx):
- 500 Server Internal Error: Server error
- 503 Service Unavailable: Service unavailable
- 504 Server Time-out: Server timeout
Global Failure Codes (6xx):
- 600 Busy Everywhere: All possible destinations busy
- 603 Decline: Call declined
Conclusion
sngrep is an invaluable tool for anyone working with SIP-based systems in India’s growing VoIP and telecom industry. Whether you’re troubleshooting call centre issues, debugging SIP trunks with providers like Airtel or Jio, or managing corporate PBX systems, sngrep provides the real-time visibility you need.
Remember to always run sngrep with appropriate permissions and apply filters to focus on relevant traffic. Regular monitoring and log analysis will help you maintain high-quality voice communications and quickly resolve issues as they arise.
For more advanced scenarios, consider combining sngrep with other tools like Wireshark for detailed packet analysis, or integrating its output with monitoring systems for automated alerting.
