How cilium/pwru works
Project type and purpose
• pwru is a command-line, eBPF-based network-packet tracing tool for Linux.
• Written in Go, it compiles and injects small BPF programs (under the bpf/ folder) into the kernel to probe networking functions (via kprobes) and collect per-packet events for debugging and filtering.
High-level file-structure analysis
• Top level:
• main.go, build.go: entrypoints and build orchestration.
• bpf/: eBPF C sources, headers, generated .o files.
• internal/: Go packages implementing assembler logic, byte-order, libpcap integration, BPF loader, kprobe attachment, event formatting.
• libpcap/: vendored upstream libpcap library for packet filter parsing and injection support.
• actions/, .github/: CI/CD pipelines, release and test workflows.
• Dockerfile, Vagrantfile, Makefile: packaging and multi-platform builds.
• test-app/: minimal example app with BPF program usage.
Insights from README
• pwru supports multiple backends (kprobe, kprobe-multi), advanced pcap-style filtering, JSON/plaintext output, and integration points (Docker, Kubernetes, Vagrant).
• Requires Linux kernel ≥5.3 with BTF, kprobes, perf events, debugfs.
Main components and their interactions
a. User-Space CLI (Go binary “pwru”)
• Parses flags, filter expression, backend choice.
• Packages: internal/config → determines which kernel functions to probe.
b. BPF Build & Loader
• bpf/kprobe_pwru.c + headers → clang/LLVM produces BPF object.
• internal/libpcap/compile.go & inject.go (optional for tunnel parsing).
• BPF syscall interface (internal/pwru/bpf_prog.go) loads the .o into kernel.
• BTF reader (internal/pwru/btf.go) – resolves kernel symbols and types.
c. Kernel Probing & Maps
• kprobes attached to network-related kernel functions (e.g., skb receive/transmit).
• BPF maps to store per-skb tracking state, ring buffer (perf events) to deliver events.
d. User-Space Event Reader
• internal/pwru/tracing.go reads perf ring buffer.
• internal/pwru/output.go formats events: JSON or text, prints to stdout or file.
e. External Integrations
• Docker container: pwru image mounts /sys/kernel/debug.
• Kubernetes Pod: privileged container, hostNetwork/hostPID.
• Vagrant VM: documented in docs/vagrant.md.
Architectural patterns and principles
• Layered separation: CLI → builder → kernel loader → event consumer → output.
• Modular internal packages: clear package boundaries for byte-order, assembler, BPF loading, tracing, output.
• Use of upstream libpcap modules for filter parsing in user space.
• CI/CD via GitHub Actions for multi-architecture build/test.
Detail level
• Don’t shy away from showing all internal modules if space allows (e.g., separate byteorder, btf, kprobe modules).
• Essential interactions: BTF lookup, kprobe attachment loop, skb metadata tracking.
• Configuration sources: debugfs, /proc/config.gz, environment flags.