# cilium/pwru architecture

> Architecture diagram of the GitHub repository cilium/pwru, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cilium/pwru
- Repository: https://github.com/cilium/pwru

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef uspace fill:#D6E9F8,stroke:#4A90E2,color:#000
    classDef kernel fill:#DFF0D8,stroke:#3C763D,color:#000
    classDef external fill:#F5F5F5,stroke:#CCCCCC,color:#000

    subgraph "User-Space" 
        pwruCLI["pwru CLI"]:::uspace
        config["Config Parser"]:::uspace
        asm["Byte-order & Assembler Logic"]:::uspace
        libpcap["libpcap Filter Integration"]:::uspace
    end

    subgraph "BPF Build & Loader"
        bpfSrc["BPF Program Sources"]:::uspace
        loader["BPF Object Loader"]:::uspace
        btf["BTF Reader & Kernel Symbols"]:::uspace
        kprobeAtt["kprobe Attachment & Probes"]:::uspace
        skbTrack["skb Metadata Tracking"]:::uspace
    end

    kernel["Linux Kernel (kprobes + BPF maps)"]:::kernel

    subgraph "User-Space Event Processing"
        perfReader["Perf-Event Tracing Reader"]:::uspace
        output["Event Output Formatter"]:::uspace
    end

    subgraph "External Integrations"
        docker["Docker Container"]:::external
        k8s["Kubernetes Pod"]:::external
        vagrant["Vagrant VM"]:::external
    end

    pwruCLI -->|parses flags/filter| config
    config -->|selects backend| bpfSrc
    pwruCLI -->|invokes build| bpfSrc
    libpcap -->|pcap-filter expression| bpfSrc
    bpfSrc -->|compile via clang/LLVM| loader
    btf -->|resolve symbols| loader
    loader -->|load & attach BPF| kernel
    kprobeAtt -->|attach kprobes| kernel
    skbTrack -->|update BPF maps| kernel
    kernel -->|perf event records| perfReader
    perfReader -->|events| output
    output -->|"stdout/file"| pwruCLI

    docker -.-> pwruCLI
    k8s -.-> pwruCLI
    vagrant -.-> pwruCLI

    click pwruCLI "https://github.com/cilium/pwru/blob/main/main.go"
    click pwruCLI "https://github.com/cilium/pwru/blob/main/build.go"
    click config "https://github.com/cilium/pwru/blob/main/internal/pwru/config.go"
    click asm "https://github.com/cilium/pwru/tree/main/internal/asm/"
    click asm "https://github.com/cilium/pwru/tree/main/internal/byteorder/"
    click libpcap "https://github.com/cilium/pwru/blob/main/internal/libpcap/compile.go"
    click libpcap "https://github.com/cilium/pwru/blob/main/internal/libpcap/inject.go"
    click libpcap "https://github.com/cilium/pwru/tree/main/libpcap/"
    click bpfSrc "https://github.com/cilium/pwru/blob/main/bpf/kprobe_pwru.c"
    click loader "https://github.com/cilium/pwru/blob/main/internal/pwru/bpf_prog.go"
    click btf "https://github.com/cilium/pwru/blob/main/internal/pwru/btf.go"
    click btf "https://github.com/cilium/pwru/blob/main/internal/pwru/ksym.go"
    click kprobeAtt "https://github.com/cilium/pwru/blob/main/internal/pwru/kprobe.go"
    click skbTrack "https://github.com/cilium/pwru/blob/main/internal/pwru/skb_metadata.go"
    click skbTrack "https://github.com/cilium/pwru/blob/main/internal/pwru/skb_tracker.go"
    click perfReader "https://github.com/cilium/pwru/blob/main/internal/pwru/tracing.go"
    click output "https://github.com/cilium/pwru/blob/main/internal/pwru/output.go"
    click docker "https://github.com/cilium/pwru/tree/main/Dockerfile"
    click vagrant "https://github.com/cilium/pwru/tree/main/Vagrantfile"
```
