{"id":13646855,"url":"https://github.com/cloudflare/xdpcap","last_synced_at":"2025-04-07T04:19:10.375Z","repository":{"id":37820095,"uuid":"175179794","full_name":"cloudflare/xdpcap","owner":"cloudflare","description":"tcpdump like XDP packet capture","archived":false,"fork":false,"pushed_at":"2024-09-25T22:46:54.000Z","size":84,"stargazers_count":720,"open_issues_count":18,"forks_count":76,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-31T03:22:47.108Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-12T09:41:37.000Z","updated_at":"2025-03-27T05:00:43.000Z","dependencies_parsed_at":"2024-06-18T20:08:01.278Z","dependency_job_id":"7f22b01d-6434-4083-bd38-2c06583d68b2","html_url":"https://github.com/cloudflare/xdpcap","commit_stats":{"total_commits":49,"total_committers":7,"mean_commits":7.0,"dds":0.326530612244898,"last_synced_commit":"de14bd17e0f343448371c8c34b13a6957fa1c131"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fxdpcap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fxdpcap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fxdpcap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fxdpcap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/xdpcap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247589826,"owners_count":20963025,"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":[],"created_at":"2024-08-02T01:03:10.457Z","updated_at":"2025-04-07T04:19:10.337Z","avatar_url":"https://github.com/cloudflare.png","language":"Go","funding_links":[],"categories":["Go","\u003ca id=\"b293f791ec9366957733415323755aa6\"\u003e\u003c/a\u003eTcpdump"],"sub_categories":[],"readme":"# xdpcap\n\nxdpcap is a tcpdump like tool for eXpress Data Path (XDP).\nIt can capture packets and actions / return codes from XDP programs,\nusing standard tcpdump / libpcap filter expressions.\n\n\n## Instrumentation\n\nXDP programs need to expose at least one hook point:\n\n```C\nstruct bpf_map_def xdpcap_hook = {\n\t.type = BPF_MAP_TYPE_PROG_ARRAY,\n\t.key_size = sizeof(int),\n\t.value_size = sizeof(int),\n\t.max_entries = 4, // The max value of XDP_* constants\n};\n```\n\nThis map must be [pinned inside a bpffs](https://facebookmicrosites.github.io/bpf/blog/2018/08/31/object-lifetime.html#bpffs).\n\n`hook.h` provides a convenience macro for declaring such maps:\n\n```\n#include \"hook.h\"\n\nstruct bpf_map_def xdpcap_hook = XDPCAP_HOOK();\n```\n\n`return XDP_*` statements should be modified to \"feed\" a hook:\n\n```C\n#include \"hook.h\"\n\nstruct bpf_map_def xdpcap_hook = XDPCAP_HOOK();\n\nint xdp_main(struct xdp_md *ctx) {\n\treturn xdpcap_exit(ctx, \u0026xdpcap_hook, XDP_PASS);\n}\n```\n\nFor a full example, see [testdata/xdp_hook.c](testdata/xdp_hook.c).\n\nDepending on the granularity desired,\na program can expose multiple hook points,\nor a hook can be reused across programs by using the same underlying map.\n\nPackage [xdpcap](https://godoc.org/github.com/cloudflare/xdpcap) provides a wrapper for\ncreating and pinning the hook maps using the [newtools/ebpf](https://godoc.org/github.com/cilium/ebpf) loader.\n\n`xdpcap` supports attaching to XDP programs loaded with the\n`BPF_F_XDP_HAS_FRAGS` flag (annotated with `xdp.frags`). It will attempt to\nattach itself as usual to the XDP program and if that fails, it will retry\nwith the `BPF_F_XDP_HAS_FRAGS` flag.\n\n\n## Installation\n\n`go get -u github.com/cloudflare/xdpcap/cmd/xdpcap`\n\n\n## Usage\n\n* Capture packets to a pcap:\n`xdpcap /path/to/pinned/map dump.pcap \"tcp and port 80\"`\n\n* Display captured packets:\n`sudo xdpcap /path/to/pinned/map - \"tcp and port 80\" | sudo tcpdump -r -`\n\n\n## Limitations\n\n* filters run after the instrumented XDP program.\nIf the program modifies the packet,\nthe filter should match the modified packet,\nnot the original input packet.\n\n* capturing multi-buffer packets\n`xdpcap` is currently unable to capture more than the first page of a packet.\nIf the instrumented XDP program is loaded with `BPF_F_XDP_HAS_FRAGS`, then\npackets that span multiple physical pages won't be entirely captured.\n\n## Tests\n\n* `sudo -E $(which go) test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fxdpcap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fxdpcap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fxdpcap/lists"}