{"id":13575936,"url":"https://github.com/cilium/pwru","last_synced_at":"2025-05-12T20:48:35.759Z","repository":{"id":36952474,"uuid":"416278604","full_name":"cilium/pwru","owner":"cilium","description":"Packet, where are you? -- eBPF-based Linux kernel networking debugger","archived":false,"fork":false,"pushed_at":"2025-05-09T03:09:11.000Z","size":8822,"stargazers_count":3299,"open_issues_count":36,"forks_count":192,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-05-09T19:59:36.801Z","etag":null,"topics":["bpf","ebpf","kernel","linux","network","tracing"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cilium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-12T09:55:50.000Z","updated_at":"2025-05-09T17:59:45.000Z","dependencies_parsed_at":"2023-12-23T20:34:15.604Z","dependency_job_id":"6e26f0a5-37ff-40a9-a8b6-cdddcd679766","html_url":"https://github.com/cilium/pwru","commit_stats":{"total_commits":404,"total_committers":36,"mean_commits":"11.222222222222221","dds":0.7029702970297029,"last_synced_commit":"05fe67e627458d2730cc37802e98eb837f578ca2"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cilium%2Fpwru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cilium%2Fpwru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cilium%2Fpwru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cilium%2Fpwru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cilium","download_url":"https://codeload.github.com/cilium/pwru/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253819939,"owners_count":21969443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bpf","ebpf","kernel","linux","network","tracing"],"created_at":"2024-08-01T15:01:05.585Z","updated_at":"2025-05-12T20:48:35.747Z","avatar_url":"https://github.com/cilium.png","language":"C","readme":"# pwru (packet, where are you?)\n\n[![Build and Test](https://github.com/cilium/pwru/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/cilium/pwru/actions/workflows/test.yml)\n[![GitHub Release](https://img.shields.io/github/release/cilium/pwru.svg?style=flat)](https://github.com/cilium/pwru/releases/latest)\n\n![logo](logo.png \"Detective Gopher is looking for packet traces left by eBPF bee\")\n\n`pwru` is an [eBPF](https://ebpf.io)-based tool for tracing network packets in\nthe Linux kernel with advanced filtering capabilities. It allows fine-grained\nintrospection of kernel state to facilitate debugging network connectivity issues.\n\nThe following example shows where the packets of a `curl` request are dropped\nafter installing an IP tables rule:\n\n![demo](demo.gif)\n\n## Running\n\n### Requirements\n\n`pwru` requires \u003e= 5.3 kernel to run. For `--output-skb` \u003e= 5.9 kernel is required. For `--backend=kprobe-multi` \u003e= 5.18 kernel is required.\n\n`pwru` optionally requires `debugfs`. It has to be mounted in `/sys/kernel/debug`. In case the folder is empty, it can be mounted with:\n\n```\nmount -t debugfs none /sys/kernel/debug\n```\n\nThe following kernel configuration is required.\n\n|           Option         | Backend      |                   Note                               |\n| ------------------------ | -------------|----------------------------------------------------- |\n| CONFIG_DEBUG_INFO_BTF=y  | both         | available since \u003e= 5.3                               |\n| CONFIG_KPROBES=y         | both         |                                                      |\n| CONFIG_PERF_EVENTS=y     | both         |                                                      |\n| CONFIG_BPF=y             | both         |                                                      |\n| CONFIG_BPF_SYSCALL=y     | both         |                                                      |\n| CONFIG_FUNCTION_TRACER=y | kprobe-multi | /sys/kernel/debug/tracing/available_filter_functions |\n| CONFIG_FPROBE=y          | kprobe-multi | available since \u003e= 5.18                              |\n\nYou can use `zgrep $OPTION /proc/config.gz` to validate whether option is enabled.\n\n### Downloading\n\nYou can download the statically linked executable for x86\\_64 and arm64 from the\n[release page](https://github.com/cilium/pwru/releases).\n\n### Usage\n\n```\n$ ./pwru --help\n\nUsage: ./pwru [options] [pcap-filter]\n    Available pcap-filter: see \"man 7 pcap-filter\"\n    Available options:\n      --all-kmods                      attach to all available kernel modules\n      --backend string                 Tracing backend('kprobe', 'kprobe-multi'). Will auto-detect if not specified.\n      --filter-func string             filter kernel functions to be probed by name (exact match, supports RE2 regular expression)\n      --filter-ifname string           filter skb ifname in --filter-netns (if not specified, use current netns)\n      --filter-kprobe-batch uint       batch size for kprobe attaching/detaching (default 10)\n      --filter-mark mark[/mask]        filter skb mark (format: mark[/mask], e.g., 0xa00/0xf00) (default 0x0)\n      --filter-netns string            filter netns (\"/proc/\u003cpid\u003e/ns/net\", \"inode:\u003cinode\u003e\")\n      --filter-non-skb-funcs strings   filter non-skb kernel functions to be probed (--filter-track-skb-by-stackid will be enabled)\n      --filter-trace-tc                trace TC bpf progs\n      --filter-trace-xdp               trace XDP bpf progs\n      --filter-track-bpf-helpers       trace BPF helper functions\n      --filter-track-skb               trace a packet even if it does not match given filters (e.g., after NAT or tunnel decapsulation)\n      --filter-track-skb-by-stackid    trace a packet even after it is kfreed (e.g., traffic going through bridge)\n      --filter-tunnel-pcap-l2 string   pcap expression for vxlan/geneve tunnel (l2)\n      --filter-tunnel-pcap-l3 string   pcap expression for vxlan/geneve tunnel (l3)\n  -h, --help                           display this message and exit\n      --kernel-btf string              specify kernel BTF file\n      --kmods strings                  list of kernel modules names to attach to\n      --output-caller                  print caller function name\n      --output-file string             write traces to file\n      --output-json                    output traces in JSON format\n      --output-limit-lines uint        exit the program after the number of events has been received/printed\n      --output-meta                    print skb metadata (default true)\n      --output-skb                     print skb\n      --output-skb-cb                  print skb-\u003ecb\n      --output-skb-metadata strings    print skb metadata (e.g., \"skb-\u003emark\", \"skb-\u003ehash\"), 4 at most\n      --output-skb-shared-info         print skb shared info\n      --output-stack                   print stack\n      --output-tcp-flags               print TCP flags\n      --output-tunnel                  print encapsulated tunnel header data\n      --output-tuple                   print L4 tuple (default true)\n      --output-xdp-metadata strings    print xdp metadata (e.g., \"xdp-\u003erxq-\u003equeue_index\"), 4 at most\n      --timestamp string               print timestamp per skb (\"current\", \"relative\", \"absolute\", \"none\") (default \"none\")\n      --version                        show pwru version and exit\n```\n\nThe `--filter-func` switch does an exact match on function names i.e.\n`--filter-func=foo` only matches `foo()`; for a wildcarded match, try\n`--filter-func=\".*foo.*\"` instead.\n\n### Running with Docker\n\nDocker images for `pwru` are published at https://hub.docker.com/r/cilium/pwru.\n\nAn example how to run `pwru` with Docker:\n\n```\ndocker run --privileged --rm -t --pid=host -v /sys/kernel/debug/:/sys/kernel/debug/ cilium/pwru pwru --output-tuple 'host 1.1.1.1'\n```\n\n### Running on Kubernetes\n\nThe following example shows how to run `pwru` on a given node:\n```\n#!/usr/bin/env bash\nNODE=kind-control-plane\nPWRU_ARGS=\"--output-tuple 'host 1.1.1.1'\"\n\ntrap \" kubectl delete --wait=false pod pwru \" EXIT\n\nkubectl apply -f - \u003c\u003cEOF\napiVersion: v1\nkind: Pod\nmetadata:\n  name: pwru\nspec:\n  nodeSelector:\n    kubernetes.io/hostname: ${NODE}\n  containers:\n  - image: docker.io/cilium/pwru:latest\n    name: pwru\n    volumeMounts:\n    - mountPath: /sys/kernel/debug\n      name: sys-kernel-debug\n    securityContext:\n      privileged: true\n    command: [\"/bin/sh\"]\n    args: [\"-c\", \"pwru ${PWRU_ARGS}\"]\n  volumes:\n  - name: sys-kernel-debug\n    hostPath:\n      path: /sys/kernel/debug\n      type: DirectoryOrCreate\n  hostNetwork: true\n  hostPID: true\nEOF\n\nkubectl wait pod pwru --for condition=Ready --timeout=90s\nkubectl logs -f pwru\n```\n\n### Running on Vagrant\n\nSee [docs/vagrant.md](docs/vagrant.md)\n\n## Developing\n\n### Dependencies\n\n* Go \u003e= 1.16\n* LLVM/clang \u003e= 12\n* Bison\n* Lex/Flex \u003e= 2.5.31\n\n### Building\n\n```\nmake\n```\n\nAlternatively, you can build in the Docker container:\n\n```\nmake release\n```\n\n### Sign-off\n\nEnsure that all commits have [Developer Certificate of Origin](https://developercertificate.org/) by adding a [Signed-off-by line to your commit messages](https://docs.cilium.io/en/stable/contributing/development/contributing_guide/#developer-s-certificate-of-origin).\n\n## Community\n\nJoin the `#pwru` [Slack channel](https://slack.cilium.io) to chat with\ndevelopers, maintainers, and other users. This is a good first stop to ask\nquestions and share your experiences.\n\n## Logo Credits\n\nThe detective gopher is based on the Go gopher designed by Renee French.\n","funding_links":[],"categories":["C","linux","Software and Tools","Cilium related projects"],"sub_categories":["Packet capture and analysis"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcilium%2Fpwru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcilium%2Fpwru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcilium%2Fpwru/lists"}