SNGREP(8)

👑 SNGREP(8) — the sip messages flow viewer, bestie edition

okay so welcome to sngrep, section 8 of your system manager's manual, and no I will not be normal about it 💅

---

✨ NAME ✨

sngrep — SIP Messages flow viewer. that's it. that's the whole name. short, iconic, does exactly what it says 🫶

---

🎀 SYNOPSIS 🎀

sngrep [-hVcivNqrD] [-IO pcap_dump ] [-d dev ] [-l limit ] [-B buffer ]
[-k keyfile ] [-f config_file ] [-F] [-T text_file ] [-t] [-P] [-R]
[-LHE capture_url ] [ <match expression> ] [ <bpf filter> ]

like yes the flags look like a keyboard smash but each one is doing something I promise 😭

---

🌸 DESCRIPTION 🌸

so sngrep is a terminal tool that groups SIP (Session Initiation Protocol) Messages by Call-Id, and then displays them as arrow flows — literally the exact same way the SIP RFCs draw them. it's giving diagram-core. it's giving "why is my call not connecting" but make it pretty ✨

the whole point of this tool is to make the process of learning or debugging SIP easier. no cap. it recognizes UDP, TCP, and partially TLS SIP packets, and it understands bpf filter logic in exactly the same way ngrep (8) and tcpdump (1) do. so if you already know those, you already know this. iykyk 🔥

---

💖 OPTIONS 💖

• -h — show help and usage info. the "wait what do I do" button 🙈
• -V — show version info. so you can flex which build you're on.
• -c — only display dialogs that start with an INVITE request. filtering out the noise, main character energy only 👑
• -r — capture RTP packets payload.
• -i — make the match expression case insensitive. lowercase rights fr fr.
• -v — invert the match expression. everything EXCEPT the match. the hater filter 💀
• -I pcap_dump — read packets from a pcap file instead of network devices. this option can be used with bpf filters.
• -O pcap_dump — save all captured packets to a pcap file. this option can be used with bpf filters. and here's the cute part: when sngrep receives a SIGUSR1 signal it will reopen the pcap file so you can do pcap file rotation. so organized. so responsible. periodt 🌈
• -B buffer — set the pcap buffer size in MB (default: 2).
• -d dev — use this capture device instead of the default (any). special keyword any, a device name like eth0, or a comma separated list like eth1,eth3. this overrides the settings in the configuration file. it said "your config file could never" 💅
• -k keyfile — RSA private keyfile to decrypt captured packets. unlock the lore 🔓
• -l limit — set the capture limit to N dialogs. the limit must be a numeric value above 1 and can not be disabled. why so strict? because it's both a security measure to avoid unlimited memory usage AND it's used internally in sngrep to manage hash table sizes. so it's not just being mean, it's being protective 🫶
• -R — rotate calls when the capture limit has been reached. although not recommended, this can be used to keep sngrep running during long times with some control over consumed memory. it's giving "I know this is a bad idea but I'm doing it anyway" 😭
• -N — don't display the sngrep interface, just capture. stealth mode. ghost mode. 👻
• -q — don't print captured dialogs in no interface mode.
• -H — Homer sipcapture url (udp:X.X.X.X:XXXX).
• -L — listen for encapsulated packets (udp:X.X.X.X:XXXX).
• -E — enable parsing of captured HEP3 packets.
• -D — print the active configuration settings and exit. a little look inside its brain 🧠
• -f config_file — read configuration from file.
• -F — do not read configuration from the default config file. freeing yourself from the defaults, as you should ✨
• -T text_file — save pcap to a text file.
• -t — capture and parse RTP telephone-event packets.
• -P — decode SIP inside IPsec ESP packets with NULL encryption (transport mode).
• match expression — match the given expression in Messages' payload. and here's the tea: if one request message matches the given expression, the following messages within the same dialog will also be captured. it brings its friends 🫂
• bpf filter — selects a filter that specifies what packets will be parsed. if no bpf filter is given, all SIP packets seen on the selected interface or pcap file will be displayed. otherwise, only packets for which the bpf filter is `true' will be displayed.

---

🦋 INTERFACE 🦋

there are multiple windows to provide different information. and most of the program windows have a help dialog with a brief description and useful keybindings. so if you're lost, press the help key, bestie, it's right there 🥰

🌸 Call List Window 🌸

the first window that sngrep shows is the Call List window, and it displays the different SIP Call-Ids found in messages. the displayed columns depend on your terminal width and your custom configuration. you can move between dialogs with the arrow keys and select them using the Spacebar. selecting multiple dialogs will display all of them in the Call flow window and Call Raw window, and will allow you to save only the selected message dialogs to a PCAP file. multi-select is the moment 💅

🎀 Call Flow Window 🎀

this window will [show] a flow diagram of the selected dialogs' messages. the selected message payload will be displayed on the right side of the window. you can move between messages using the arrow keys and select them using the Spacebar. selecting multiple messages will display the Message Diff Window. arrows!! going places!! 📈

💜 Call Raw Window 💜

this window will display the selected dialog messages in plain text. it was designed to allow copying the messages payload easily. you can also save the displayed information to a text file from this screen. copy-paste girlies, this one's for you 🙈

🌈 Column selection Window 🌈

the columns displayed in Call List can be updated in this window. you can add or remove columns or change their order in the list. additionally, you can save column state to be used in the next sngrep execution. your setup, your rules, and it remembers. iconic ✨

⭐ Message Diff Window ⭐

this window will compare two messages. right now the comparison is done by searching each line in the other message, highlighting those not found exactly. you can reach this window by selecting two messages using the Spacebar in the Call Flow window. spot the difference, but for SIP 💀

---

🍓 FILES 🍓

full paths below may vary between installations. so like, don't come for me if yours lives somewhere else 🫶

• /etc/sngreprc — System-wide configuration file. some sngrep options can be overridden using this file.
• ~/.sngreprc — User's configuration file. if this file is present, options will override system-wide configurations. user settings stay winning 👑

---

💀 BUGS 💀

please report bugs to the sngrep github project at

http://github.com/irontec/sngrep

Non-bug, non-feature-request general feedback should be sent to the author directly by email. so like, bugs go to github, vibes go to the inbox, got it? 📬

---

🌟 AUTHOR 🌟

Written by Ivan Alonso [a.k.a. Kaian] <kaian@irontec.com>. thank you for your service, king 🫡

---

and that's the whole manual, bestie!! this is sngrep 1.9.0, dated Oct 2026, and it lives at SNGREP(8) in your friendly neighborhood System Manager's Manual. go capture some dialogs, you've got this 💖✨🎀