- Notifications
You must be signed in to change notification settings - Fork186
Packet, where are you? -- eBPF-based Linux kernel networking debugger
License
cilium/pwru
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
pwru is aneBPF-based tool for tracing network packets inthe Linux kernel with advanced filtering capabilities. It allows fine-grainedintrospection of kernel state to facilitate debugging network connectivity issues.
The following example shows where the packets of acurl request are droppedafter installing an IP tables rule:
pwru requires >= 5.3 kernel to run. For--output-skb >= 5.9 kernel is required. For--backend=kprobe-multi >= 5.18 kernel is required.
pwru optionally requiresdebugfs. It has to be mounted in/sys/kernel/debug. In case the folder is empty, it can be mounted with:
mount -t debugfs none /sys/kernel/debugThe following kernel configuration is required.
| Option | Backend | Note |
|---|---|---|
| CONFIG_DEBUG_INFO_BTF=y | both | available since >= 5.3 |
| CONFIG_KPROBES=y | both | |
| CONFIG_PERF_EVENTS=y | both | |
| CONFIG_BPF=y | both | |
| CONFIG_BPF_SYSCALL=y | both | |
| CONFIG_FUNCTION_TRACER=y | kprobe-multi | /sys/kernel/debug/tracing/available_filter_functions |
| CONFIG_FPROBE=y | kprobe-multi | available since >= 5.18 |
You can usezgrep $OPTION /proc/config.gz to validate whether option is enabled.
You can download the statically linked executable for x86_64 and arm64 from therelease page.
$ ./pwru --helpUsage: ./pwru [options] [pcap-filter] Available pcap-filter: see "man 7 pcap-filter" Available options: --all-kmods attach to all available kernel modules --backend string Tracing backend('kprobe', 'kprobe-multi'). Will auto-detect if not specified. --filter-func string filter kernel functions to be probed by name (exact match, supports RE2 regular expression) --filter-ifname string filter skb ifname in --filter-netns (if not specified, use current netns) --filter-kprobe-batch uint batch size for kprobe attaching/detaching (default 10) --filter-mark uint32 filter skb mark --filter-netns string filter netns ("/proc/<pid>/ns/net", "inode:<inode>") --filter-non-skb-funcs strings filter non-skb kernel functions to be probed (--filter-track-skb-by-stackid will be enabled) --filter-trace-tc trace TC bpf progs --filter-trace-xdp trace XDP bpf progs --filter-track-skb trace a packet even if it does not match given filters (e.g., after NAT or tunnel decapsulation) --filter-track-skb-by-stackid trace a packet even after it is kfreed (e.g., traffic going through bridge) -h, --help display this message and exit --kernel-btf string specify kernel BTF file --kmods strings list of kernel modules names to attach to --output-caller print caller function name --output-file string write traces to file --output-json output traces in JSON format --output-limit-lines uint exit the program after the number of events has been received/printed --output-meta print skb metadata --output-skb print skb --output-skb-shared-info print skb shared info --output-stack print stack --output-tuple print L4 tuple --timestamp string print timestamp per skb ("current", "relative", "absolute", "none") (default "none") --version show pwru version and exitThe--filter-func switch does an exact match on function names i.e.--filter-func=foo only matchesfoo(); for a wildcarded match, try--filter-func=".*foo.*" instead.
Docker images forpwru are published athttps://hub.docker.com/r/cilium/pwru.
An example how to runpwru with Docker:
docker run --privileged --rm -t --pid=host -v /sys/kernel/debug/:/sys/kernel/debug/ cilium/pwru pwru --output-tuple 'host 1.1.1.1'The following example shows how to runpwru on a given node:
#!/usr/bin/env bashNODE=kind-control-planePWRU_ARGS="--output-tuple 'host 1.1.1.1'"trap " kubectl delete --wait=false pod pwru " EXITkubectl apply -f - <<EOFapiVersion: v1kind: Podmetadata: name: pwruspec: nodeSelector: kubernetes.io/hostname: ${NODE} containers: - image: docker.io/cilium/pwru:latest name: pwru volumeMounts: - mountPath: /sys/kernel/debug name: sys-kernel-debug securityContext: privileged: true command: ["/bin/sh"] args: ["-c", "pwru ${PWRU_ARGS}"] volumes: - name: sys-kernel-debug hostPath: path: /sys/kernel/debug type: DirectoryOrCreate hostNetwork: true hostPID: trueEOFkubectl wait pod pwru --for condition=Ready --timeout=90skubectl logs -f pwru- Go >= 1.16
- LLVM/clang >= 12
- Bison
- Lex/Flex >= 2.5.31
makeAlternatively, you can build in the Docker container:
make releasepwru is an open source project. The userspace code is licensed underApache-2.0, while the BPF underBSD 2-ClauseandGPL-2.0. Everybody is welcome to contribute.Contributors are required to follow theContributor Covenant Code ofConduct andmust adhere to theDeveloper Certificate ofOrigin by adding a Signed-off-by line totheir commit messages.
Join the#pwruSlack channel to chat withdevelopers, maintainers, and other users. This is a good first stop to askquestions and share your experiences.
The detective gopher is based on the Go gopher designed by Renee French.
About
Packet, where are you? -- eBPF-based Linux kernel networking debugger