How mozillazg/ptcpdump works
1. What this repo is
ptcpdump is a Linux-only, Go-based tcpdump-compatible CLI. Its core architecture is a packet-capture pipeline built on eBPF, with optional enrichment from host, process, container, and Kubernetes metadata. The repo is split between Go control-plane code and C eBPF data-plane code.
2. Top-level control plane
main.go and the cmd/ package form the CLI surface. This is where flags like -i, -r, -w, --backend, --pid, --container-id, --pod-name, --netns, and the -- command [args] mode are interpreted. The command layer dispatches into live capture, reading saved files, listing interfaces, version/prog info, and related subcommands.
3. Capture pipeline
The live-capture path is centered in internal/capturer/ and the bpf/ package. At startup, the CLI selects a backend and attaches the corresponding eBPF program(s) to interfaces, cgroups, sockets, or tracing hooks. Captured packets and related events are then pushed back into Go through the BPF event bridge and processed asynchronously.
4. eBPF data plane
The bpf/ directory contains the C sources, headers, and generated Go bindings/bytecode blobs for multiple architectures (amd64, arm64, arm) and backend variants. The repository embeds prebuilt .o artifacts and uses kernel BTF/CO-RE support where available. This is the low-level layer that actually observes packets and emits metadata needed by the Go side.
5. Backend boundary
The repo supports four capture backends: tc, cgroup-skb, socket-filter, and tp-btf. They share the same downstream Go pipeline, but differ in where packets are observed and what metadata is available. This boundary matters architecturally because backend choice changes namespace visibility, L2 access, and kernel requirements, but not the CLI/output model.
6. Event and consumer model
internal/event/, bpf/event.go, and internal/consumer/ define the event flow between kernel and user space. Packet events are distinct from process-exec/exit/keylog/net events, and consumers update state caches or side effects as those events arrive. This is the mechanism that lets ptcpdump correlate a packet with the process, thread, parent process, container, or pod that produced it.
7. Metadata enrichment
internal/metadata/ is the main enrichment subsystem. It resolves process identity, network namespace, device identity, container membership, and Kubernetes pod context by combining kernel-visible IDs with host-side lookups. Container support is split across Docker, containerd, and generic CRI paths, with a multiple.go layer to try multiple runtimes. This is the major boundary between packet capture and human-readable context.
8. Process and namespace correlation
internal/metadata/process.go, internal/metadata/netns.go, internal/metadata/net.go, and the internal/utils/ helpers support mapping kernel observations back to host processes and namespaces. The README’s --pid, --pname, --uid, --follow-forks, and --netns flags are implemented through this correlation layer rather than by packet parsing alone.
9. Packet parsing and read mode
internal/parser/ handles decoding of saved captures, including pcap and pcapng. This powers -r/--read-file and also supports replaying previously captured traffic with the same formatting and filtering behavior. In other words, reading files and live capture converge into the same presentation pipeline after the parsing stage.
10. Output and persistence
internal/writer/ contains the sinks: stdout formatting, raw pcap, pcapng, keylog output, and rotation support. The output subsystem is separate from capture so the same packet stream can be printed, saved, rotated, or piped to downstream tools. PcapNG is the richer format because it can carry embedded metadata and is Wireshark-ready.
11. Filter model
Filtering is not only tcpdump-style pcap-filter(7) expressions. ptcpdump also adds higher-level filters for process/container/pod identity, and some of those are enforced through runtime metadata matching rather than kernel packet matching. The README’s emphasis on kernel-space BPF filtering shows that the system intentionally splits filters between data-plane reduction and user-space correlation.
12. Build and packaging boundaries
The repository is designed to ship as a mostly static binary. It bundles libpcap from lib/libpcap, precompiles eBPF objects, and supports Docker-based builds for both the Go binary and the BPF bytecode. Release and CI automation live in .github/workflows/, .circleci/, and .goreleaser.yml, which are important for reproducible native builds but not part of the runtime path.
13. Test/integration coverage
testdata/ contains sample captures and many shell-based end-to-end scenarios for Docker, containerd, Kubernetes, netns, NAT, TLS keylog, and output formatting. This reflects the repo’s main integration risks: backend-specific capture correctness, runtime metadata correctness, and stable output formatting across capture/read modes.
14. Diagram-friendly mental model
A useful architecture diagram is: CLI and flags at the top; backend selection and BPF attachment in the middle; event ingestion plus metadata enrichment on the Go side; then parser/writer/output at the bottom. The main external dependencies that materially shape the design are the Linux kernel eBPF/BTF subsystem, container runtimes (Docker/containerd/CRI), and the bundled libpcap library.
Main entry points: root.go Root cmd · container.go Metadata · capturer.go Capturer · writer.go Writer
Components 26
CLI
Command parsing, subcommands, and user-facing entry points
- main · Program entry and CLI bootstrap
main.go - Root cmd · Top-level command wiring and mode dispatch
cmd/root.go - Options · Flag parsing and command configuration
cmd/options.go - Capture cmd · Live capture execution and backend selection
cmd/capture.go - Read cmd · Reads saved captures and routes them through formatting
cmd/read.go - Tool cmds · Interface listing, version, BPF info, logging, and container helpers
cmd/list.go
Capture
Live packet capture and backend attachment
- Capturer · Orchestrates backend attachment and packet collection
internal/capturer/capturer.go - Backend · Selects and configures tc, cgroup-skb, socket-filter, or tp-btf capture path
internal/types/backend.go - Event bus · User-space event dispatch for packet, exec, exit, and net events
internal/event/process.go
eBPF
Kernel-space program variants and generated artifacts
- BPF bridge · Go-side bridge to BPF programs and generated bindings
bpf/bpf.go - Kernel events · Packet and auxiliary event definitions shared with user space
bpf/event.go - BPF prog · Core packet-observation programs and helper code
bpf/ptcpdump.c - Variants · Prebuilt program blobs and per-architecture/generated wrappers
bpf/bpf_x86_bpfel.go
Enrichment
Process, container, netns, and Kubernetes correlation
- Consumers · Consumes exec/exit/keylog/net events and updates local state
internal/consumer/exec.go - Metadata · Resolves human-readable packet context from kernel-visible identifiers
internal/metadata/container.go - Process map · Maps packets to processes, users, forks, and parents
internal/metadata/process.go - Netns map · Maps traffic to network namespaces and device context
internal/metadata/netns.go - Container map · Container and runtime identity resolution across Docker, containerd, and CRI
internal/metadata/container/multiple.go - K8s lookup · Kubernetes pod and CRI metadata resolution
internal/metadata/k8s/cri.go
I/O
Parsing, formatting, and output sinks
- Parser · Decodes saved captures in pcap and pcapng formats
internal/parser/parser.go - Writer · Routes packet streams to stdout, files, rotation, and keylog sinks
internal/writer/writer.go - PcapNG · Rich capture format with metadata-friendly output
internal/writer/pcapng.go - Stdout · Tcpdump-style terminal formatting
internal/writer/stdout.go
Support
Shared helpers and runtime support
- libpcap · Bundled packet capture library and filter support
lib/libpcap - BTF utils · BTF/CO-RE detection and helpers
internal/btf/btf.go - Host utils · Host and namespace helper functions
internal/host/host.go
Connections 27
- main → Root cmd: starts · Bootstraps the CLI and hands off to root command handling
- Root cmd → Options: parses · Loads flags and run configuration
- Root cmd → Capture cmd: live mode · Dispatches to live capture execution
- Root cmd → Read cmd: read mode · Dispatches to saved-capture replay
- Root cmd → Tool cmds: aux commands · Handles listing, versioning, and other utility commands
- Capture cmd → Backend: selects · Chooses the observation backend and attach target
- Capture cmd → Capturer: runs · Starts the live capture pipeline
- Capturer → BPF bridge: loads · Loads and attaches generated BPF artifacts
- BPF bridge → BPF prog: executes · Runs the kernel-space packet observation logic
- BPF bridge → Variants: binds · Uses architecture and backend-specific program variants
- BPF prog → Kernel events: emits · Produces packet and auxiliary events for user space
- Kernel events → Event bus: delivers · Events are consumed asynchronously in Go
- Event bus → Consumers: fan-out · Dispatches exec, exit, keylog, and net event consumers
- Consumers → Metadata: updates · Maintains state used for later enrichment
- Metadata → Process map: resolves · Correlates packets to process identity
- Metadata → Netns map: resolves · Correlates packets to namespaces and devices
- Metadata → Container map: resolves · Adds container/runtime identity
- Container map → K8s lookup: extends · Derives pod context through CRI and Kubernetes metadata
- Read cmd → Parser: decodes · Reads pcap/pcapng files into the shared pipeline
- Capturer → Writer: streams · Sends captured packets to output sinks
- Parser → Writer: formats · Feeds replayed packets into the same presentation/output layer
- Writer → Stdout: prints · Human-readable tcpdump-style output
- Writer → PcapNG: writes · Produces richer capture files and metadata-aware output
- Writer → libpcap: filters · Uses bundled libpcap support for capture/filter semantics
- Capturer → BTF utils: checks · Detects BTF/CO-RE capability for supported backends
- Metadata → Host utils: queries · Uses host-side lookups and namespace helpers
- Backend → Capturer: configures · Backend choice shapes attachment and kernel visibility