packeteer

Terminal packet capture and analysis for Linux. Captures live traffic or replays a saved file, decodes it from Ethernet up to the application layer, and shows the result in a plain-text log, an interactive TUI, or a graphical window.

Capture files are pcapng, so Wireshark reads them and interface metadata survives the round trip.

Build

Requires a C++20 compiler, CMake 3.20 or later, and libpcap. FTXUI, doctest, SDL3 and Dear ImGui are fetched during configuration, so no system packages are needed for them.

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

The binaries are build/packeteer (command line and TUI), build/packeteer_gui (graphical), and build/packeteer_tests.

Use

packeteer [options] [interface]

With no interface, the first available device is used.

Option	Effect
`-t`, `--tui`	Interactive TUI instead of plain-text output
`-x`	Hex dump under each summary, plain-text mode only
`-c`	Show IPv4/TCP/UDP checksum validity
`-a`	Reassemble TCP streams and re-run HTTP parsing on the joined bytes
`-w <file>`	Write the capture to a pcapng file
`-r <file>`	Replay a pcapng file instead of a live device
`-f <expr>`	Capture filter in tcpdump/BPF syntax
`-g <term>`	Display filter: show only summaries containing `term`
`-h`, `--help`	Show usage

In the TUI, press / to search interactively.

Filters

-f is a kernel-level BPF filter. The kernel discards what does not match, so those packets never reach the process, and -w writes only what passed. Use it to cut volume at the source.

-g is a display filter applied after decoding. It changes what you see, not what is captured, and does not affect -w.

-f cannot be combined with -r, because a saved file has already been filtered at capture time.

Checksums

Checksum validation is off by default. Most network cards compute the real checksum in hardware, after the point where capture taps the packet. Outbound and loopback packets therefore read as invalid even when nothing is wrong. Turn it on with -c when you are looking at received traffic and the distinction matters.

TCP reassembly

-a joins TCP segments and parses the result, which catches an HTTP request or response split across several packets that single-packet dissection misses. In-order segments only. Out-of-order and retransmitted segments are dropped rather than buffered.

Protocol support

Link and network layers: Ethernet, ARP, IPv4, IPv6, ICMP, IGMP, LLDP.

Transport: TCP with stream reassembly, UDP, RTP, RTCP.

Application: DHCP, DNS, mDNS, HTTP, FTP, SMTP, SSH, TLS, QUIC, NTP, SNMP, TFTP.

Fragmented IPv4 and IPv6 packets are reported as fragments. A non-first fragment carries no transport header, so its payload is not decoded as one.

Capture backends

libpcap is the default and works on any interface it supports.

A second path uses a raw AF_PACKET socket with an mmap'd ring buffer, which avoids libpcap's copies. It is Linux-only and built as packeteer_afpacket_demo.

Privileges

Packet capture needs CAP_NET_RAW. Grant it to the binary rather than running as root:

sudo setcap cap_net_raw,cap_net_admin=eip build/packeteer

The capture handle is opened first and privileges are dropped immediately afterwards, so the decoders never run with them.

Tests

cmake --build build -j && ./build/packeteer_tests

Unit tests cover the decoders, the byte reader, the capture queue and the filters. Twelve libFuzzer targets under fuzz/ exercise the parsers against malformed input; build them with -DPACKETEER_ENABLE_FUZZING=ON and a Clang toolchain.