Quickstart

Get up and running with ptcpdump in a few minutes. This guide covers installation and a first capture that highlights process-aware metadata.

1. Check Requirements

• Linux kernel 5.2 or newer with BPF and BTF enabled.
• debugfs mounted at /sys/kernel/debug (mount with sudo mount -t debugfs none /sys/kernel/debug if needed).
• Root privileges or the CAP_BPF and CAP_NET_ADMIN capabilities to load eBPF programs (run commands with sudo).

For a complete list of kernel configuration options, see the Troubleshooting guide.

2. Install ptcpdump

Download a Release

Download static builds for x86_64 or arm64 from the GitHub releases page:

Build from Source (optional)

git clone https://github.com/mozillazg/ptcpdump.git
cd ptcpdump
make build
sudo cp ptcpdump /usr/local/bin/

The make build target compiles libpcap and produces a static binary inside ./.

3. Run Your First Capture

sudo ptcpdump -i any --pname curl -c 10

This command captures up to 10 packets from any interface and limits the context to the curl process. You should see output similar to:

eth0 curl.205562 Out IP 10.0.2.15.39984 > 139.178.84.217.80: Flags [P.], ... ParentProc [bash.180205]

To save a capture with embedded metadata for Wireshark, run:

sudo ptcpdump -i any -w demo.pcapng

What Next?

• Learn more filters and workflow tips in the Usage Guide.
• Troubleshoot kernel or permission issues via the Troubleshooting reference.
• Review the GitHub README for advanced build modes and feature comparisons.