sngrep: a terminal viewer for SIP call flows

A call flow, not a packet list

sngrep is described as a tool for displaying SIP calls message flows from terminal, and the two things it says it supports are live capture to display realtime SIP packets, and use as a PCAP viewer.

The distinction between those two modes is the reason the tool exists, and it is also the difference between sngrep and a general purpose packet analyser. A general purpose analyser gives you every packet in a capture and leaves you to reconstruct the conversation. sngrep parses the SIP layer, groups the messages into calls, and draws the flow, so the dialog between two endpoints appears as a conversation with arrows between them, in a terminal.

The audience is therefore a person debugging a specific call. A SIP registration that fails, an INVITE that is answered but never acknowledged, a transaction that retransmits, a call that tears down in the middle. These are questions about a sequence of messages, and a flow view answers them directly where a hex dump makes you do the work.

The project is written in C, which is the obvious choice for a tool that sits in a terminal attached to a live interface, and the topic list names the ingredients: sip, pcap, ncurses, hep, flow, trace, debug and terminal. HEP is the protocol used to capture traffic from a remote host, so a capture does not have to happen on the machine you are sitting at.

The licence is GPL version 3 or later, with copyright from 2013 to 2026 held by Irontec S.L. The last push was on 2026-10-14, and the releases are v1.8.3 from 2025-10-16, v1.8.4 from 2026-07-24 and v1.9.0 from 2026-10-05, so the project ships regularly and the 1.9 line is current.

Two build systems, and the packages for seven distributions

The installation section is unusually complete, and that is a sign of a tool that people install in different ways.

There are prebuilt binary instructions in the wiki for Debian and Ubuntu, CentOS, RedHat and Fedora, Alpine Linux, Gentoo, Arch, OSX and OpenWRT or LEDE. The presence of an OpenWRT entry tells you something about the audience, because sngrep is the kind of tool you SSH into a small device to run.

For building from source, the prerequisites are listed with what each one is for. libncurses5 is for the UI, windows and panels, and libpcap is for capturing packets. Then five optional ones. libssl gives TLS transport decrypt using OpenSSL and libcrypt, and gnutls gives the same thing using GnuTLS and libgcrypt, so you can have one or the other. libncursesw5 adds wide character support. libpcre or libpcre2 adds Perl Compatible regular expressions in the regexp fields, which is the field where SIP filters usually live. And zlib supports gzip compressed pcap files, which matters if your capture pipeline compresses its output.

The standard autotools procedure is four commands:

./bootstrap.sh
./configure
make
make install (as root)

Or CMake, which the README notes as an alternative to autotools:

mkdir build && cd build
cmake [<options>] ..
make
make install (as root)

Two build systems for a C project of this size is unusual, and the practical effect is that a distribution packager can use whichever it already has a recipe for.

Every optional feature has a configure flag

The build flags are worth reading as a capability list, because each one turns a feature on that is otherwise absent.

With the autotools build, --with-openssl adds OpenSSL support to parse TLS captured messages and requires libssl, --with-gnutls does the same with GnuTLS and requires gnutls, --with-pcre and --with-pcre2 add Perl Compatible regular expressions support in the regexp fields, --with-zlib enables support for gzip compressed pcap files, --enable-unicode adds Ncurses UTF-8 and Unicode support and requires libncursesw5, --enable-ipv6 enables IPv6 packet capture support, and --enable-eep enables EEP packet send and receive support.

The CMake build has the same list under different names, WITH_OPENSSL, WITH_GNUTLS, WITH_PCRE, WITH_PCRE2, WITH_ZLIB, WITH_UNICODE, USE_IPV6 and USE_EEP, and it adds two packaging options, CPACK_GENERATOR=DEB so that make package builds a Debian package, and CPACK_GENERATOR=RPM for a RPM package.

Two of these have consequences beyond the build. The TLS options are what make encrypted traffic readable at all, and if your capture is TLS you need to enable one of them before the build, not after. And the IPv6 and EEP options determine whether the tool can even see the traffic you are chasing, since a capture on a v4 interface will not contain v6 traffic and a remote host's traffic needs HEP.

The design of the flags is consistent, which is a good sign. Most of them name the library they need, so a packager can resolve the dependency and the feature together.

Reading a pcap and capturing live are different commands

The usage section is short, and it points at --help for the full list of flags and their syntax, which is the right thing to do for a tool with this many options.

The two examples given cover the two modes. To view SIP packets from a pcap file, applying a filter:

sngrep -I file.pcap host 192.168.1.1 and port 5060

And to capture live, saving the packets to a new file:

sngrep -d eth0 -O save.pcap port 5060 and udp

The filter syntax is the interesting part. Both expressions are written in the style of a packet filter language, with a host term, a port term and a protocol term combined with and. That is the same shape as a tcpdump style expression, and it means the muscle memory transfers, but the README does not document the grammar, so the wiki and --help are where the full syntax lives. The examples also show the two natural forms of the filter, a host and a port for a specific peer, and a protocol constraint for capturing everything SIP over UDP.

The -O option is the one that changes the workflow. Capturing live and writing the packets out to a pcap as it goes means the flow view is not the only artefact, so a session you were watching can be handed to somebody else afterwards or re-examined later, and the capture survives the terminal session.

There is also a configuration file, sngreprc, and the README links a wiki page for it. Some options can be configured that way rather than on the command line, which matters for the settings you want to be in place every time rather than typed on every invocation.

The OpenSSL exception is the licensing detail to read

The licence section is where this project departs from a plain GPL notice, and it is worth reading in full because it changes what you may do with a binary you build.

The base terms are the GNU General Public License version 3, or at your option any later version, and the copyright is held by Irontec S.L. from 2013 to 2026. The program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY, and without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Then the exception. As a special exception, the copyright holders give permission to link the code of portions of this program with the OpenSSL library under certain conditions as described in each individual source file, and to distribute linked combinations including the two. You must obey the GPL in all respects for all the code used other than OpenSSL. If you modify files with this exception, you may extend the exception to your version, though you are not obligated to, and if you do not want to do so you must delete the exception statement from your version, and if you delete it from all source files in the program you must delete it here too.

This is the standard arrangement for a GPL program that wants to permit linking with the OpenSSL library, and the repository carries a separate LICENSE.OpenSSL file to hold it. The reason it matters practically is the distribution case. If you build sngrep with --with-openssl and ship that binary, you are relying on the exception as written, and the source files it refers to are where the per file conditions are recorded. A packager who enables the OpenSSL option has to keep that file and the conditions in place, and anyone building without OpenSSL avoids the question entirely.

This is a note about where the terms are, not a reading of them.

Where a terminal SIP viewer is the wrong tool

The limits are specific and mostly follow from the design.

The first is that this is a SIP tool. It parses the SIP layer and draws SIP calls, so a capture you want to understand at the transport level, or one containing a protocol it does not model, is not going to be served well by the flow view. The pcap mode is still useful for that, because you can write the capture out and open it elsewhere, but the analysis you came for is not there.

The second is encrypted traffic. The TLS decrypt options are optional, they need a key, and a capture that is encrypted and not decryptable is an unreadable capture. The --with-openssl and --with-gnutls flags tell you the capability exists, and the wiki and the help output are where the key handling is described.

The third is that a terminal tool cannot do what a graphical analyser does in one respect, which is multi protocol inspection at once. If your incident spans SIP and the RTP media or the RTP signalling that goes with it, sngrep shows you the SIP conversation and nothing else.

The fourth is the operational one. The tool is a ncurses program attached to a terminal, which means it is for a person, at a console, on a machine with a terminal. A capture that has to be collected from somewhere else needs HEP, and the EEP option covers the send and receive side of that, but the topology has to be arranged.

For the case it is built for, a single person watching a live or recorded SIP call in a server room, the alternative is a general purpose packet analyser and the manual work of reconstructing the flow by hand, and the difference in approach is exactly the difference between reading packets and reading a call.

Editorial conclusion

Adopt sngrep if you debug SIP on a server where you have a terminal and no GUI, if you want the call flow rather than a list of packets, and if you are prepared to build it with the optional libraries your capture needs. Do not adopt it as a full protocol analyser or for encrypted traffic you cannot decrypt, since the TLS support is optional and needs a key. Verify first that the libpcap and ncurses development packages are present, that the configure or CMake options you need for your capture are enabled before the build rather than after, and that you understand the OpenSSL linking exception before you redistribute a binary built with --with-openssl.

Frequently asked questions

Official sources

1. irontec/sngrep on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases