xdpcap

package module
v0.0.0-...-2c071ab Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2026 License: BSD-3-Clause Imports: 5 Imported by: 0

README

xdpcap

xdpcap is a tcpdump-like capture tool for eXpress Data Path (XDP). It captures packets and their XDP return codes from running XDP programs using standard tcpdump / libpcap filter expressions, writing output as a pcapng file.

Multiple concurrent captures on the same hook are supported — each subscriber gets its own filter and perf buffer, and a shared coordinator BPF program fans packets out to all of them.

Requirements

  • Linux kernel 4.15+ (for BPF_MAP_TYPE_PROG_ARRAY tail-call support)
  • Go 1.20+
  • libpcap and its headers (libpcap-dev / libpcap-devel) for filter compilation
  • Root privileges (or CAP_BPF + CAP_NET_ADMIN on kernels ≥ 5.8)

Installation

git clone https://github.com/ASCP11/xdpcap
cd xdpcap
go build -o xdpcap ./cmd/xdpcap
sudo install -m 755 xdpcap /usr/local/bin/xdpcap
With go install
go install github.com/ASCP11/xdpcap/cmd/xdpcap@latest

The binary lands in $(go env GOPATH)/bin/xdpcap. Make sure that directory is in your PATH, or copy the binary to /usr/local/bin.

Instrumenting your XDP program

Your XDP program needs to expose a hook map and call xdpcap_exit instead of returning directly.

1. Declare the hook map

Using the provided hook.h convenience macro:

#include "hook.h"

struct bpf_map_def xdpcap_hook = XDPCAP_HOOK();

Or declare it manually:

struct bpf_map_def xdpcap_hook = {
    .type        = BPF_MAP_TYPE_PROG_ARRAY,
    .key_size    = sizeof(int),
    .value_size  = sizeof(int),
    .max_entries = 5,   // one slot per XDP_* action
};
2. Replace return XDP_* with xdpcap_exit
#include "hook.h"

struct bpf_map_def xdpcap_hook = XDPCAP_HOOK();

int xdp_main(struct xdp_md *ctx) {
    // ... packet processing ...
    return xdpcap_exit(ctx, &xdpcap_hook, XDP_PASS);
}

xdpcap_exit tail-calls into the hook map and falls through to the original action if no capture is attached, so there is zero overhead when xdpcap is not running.

3. Pin the hook map to a bpffs path

The map must be pinned to a path inside a bpffs mount (typically /sys/fs/bpf) so that xdpcap can open it by path. Using the Go loader:

import "github.com/cloudflare/xdpcap"

hook, err := xdpcap.NewHook("/sys/fs/bpf/my_program_hook")
// ...
hook.Patch(collectionSpec, "xdpcap_hook")
// load and attach your collection, then:
hook.Pin()

For a complete example see testdata/xdp_hook.c.

Usage

xdpcap requires root (or the capabilities listed above).

xdpcap [options] <hook map path> <output> [<filter expr>]

<output> may be - to write pcapng to stdout (implies -q and -flush).

<filter expr> is an optional tcpdump / libpcap expression. Omit it to capture all packets. You can also pass a raw cBPF string in the form <count>,<op> <jt> <jf> <k>,....

Options
Flag Default Description
-actions <list> all Comma-separated XDP actions to capture (aborted, drop, pass, tx, redirect, or numeric values)
-buffer <bytes> 8192 Per-CPU perf ring-buffer size
-watermark <bytes> 1 Perf wakeup watermark
-c <count> unlimited Stop after capturing this many packets
-C <MB> unlimited Stop after capturing approximately this many megabytes
-flush off Flush output after every packet (implied when writing to stdout)
-linktype <type> ethernet Link type for filter compilation
-q off Quiet — suppress per-second statistics
Examples

Capture all traffic to a file:

sudo xdpcap /sys/fs/bpf/my_hook dump.pcapng

Capture TCP port 80 only, pipe to tcpdump for live display:

sudo xdpcap /sys/fs/bpf/my_hook - "tcp and port 80" | sudo tcpdump -r -

Capture only dropped packets:

sudo xdpcap -actions drop /sys/fs/bpf/my_hook drops.pcapng

Run two concurrent captures on the same hook (different filters):

sudo xdpcap /sys/fs/bpf/my_hook all.pcapng &
sudo xdpcap /sys/fs/bpf/my_hook icmp-only.pcapng "icmp"

Stop after 1000 packets or 10 MB, whichever comes first:

sudo xdpcap -c 1000 -C 10 /sys/fs/bpf/my_hook capture.pcapng

Multi-capture

Up to 16 concurrent xdpcap processes can attach to the same hook map. Each subscriber registers independently — they can use different filters and action sets. A shared coordinator BPF program (rebuilt whenever a subscriber joins or leaves) fans packets to every active subscriber whose filter matches.

The coordinator is installed automatically on first attach and removed when the last subscriber exits. A capture that is killed (e.g. SIGKILL) can't unregister, so its filter keeps running on every packet until the next xdpcap attaches to or detaches from the same hook and cleans it up. To clean up right away, run:

xdpcap -cleanup /path/to/pinned/map

Subscriber state is pinned on bpffs next to the hook map, in <debug map>_subs/, so it is only accessible to privileged users and shared by every process that can see the hook map.

Limitations

  • Filters run on modified packets. Filters are evaluated after the XDP program runs. If your program rewrites packets, write your filter to match the modified form.

  • Multi-buffer packets are truncated. xdpcap captures only the first page of a packet. Programs loaded with BPF_F_XDP_HAS_FRAGS that process multi-page packets will produce truncated captures for those frames.

Tests

Unit and integration tests require root:

sudo -E $(which go) test ./...

Live tests attach a real XDP hook to a named interface and exercise multi-subscriber coordination end-to-end. They run as part of the normal test suite when root is available and the interface exists, and are skipped otherwise:

go build -o /tmp/xdpcap ./cmd/xdpcap/
sudo -E XDPCAP_LIVE_IFACE=eth0 $(which go) test ./cmd/xdpcap/ -v -run TestLive -timeout 180s
Variable Default Description
XDPCAP_LIVE_IFACE enp5s0f0 Interface the XDP hook is attached to
XDPCAP_LIVE_MACVLAN macvlan0 macvlan created on it to generate traffic
XDPCAP_LIVE_MACVLAN_IP 10.25.0.100 Address of the macvlan (/24)
XDPCAP_LIVE_TARGET_IP 10.25.0.5 Address pinged through the interface
XDPCAP_BIN /tmp/xdpcap xdpcap binary used by the binary tests

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Hook

type Hook struct {
	// contains filtered or unexported fields
}

Hook represents an xdpcap hook point. This hook can be reused with several programs.

func NewHook

func NewHook(fileName string) (*Hook, error)

NewHook creates a new Hook, that can be Pin()'d to fileName. fileName must be inside a bpffs

func (*Hook) Close

func (h *Hook) Close() error

Close releases any resources held It does not Rm()

func (*Hook) Patch

func (h *Hook) Patch(spec *ebpf.CollectionSpec, hookMapSymbol string) error

Patch edits all programs in the spec that refer to hookMapSymbol to use this hook.

This function is a no-op if called on a nil Hook.

func (*Hook) Pin

func (h *Hook) Pin() error

Pin persists the underlying map to a file, overwriting it if it already exists

func (*Hook) Rm

func (h *Hook) Rm() error

Rm deletes files created by Pin()

Directories

Path Synopsis
cmd
bpfoff command
Program bpfoff converts a tcpdump / libpcap filter expression to a BPF filter matching packets with a fixed set of byte offsets.
Program bpfoff converts a tcpdump / libpcap filter expression to a BPF filter matching packets with a fixed set of byte offsets.
xdpcap command
Program xdpcap produces tcpdump compatible PCAPs from a BPF map.
Program xdpcap produces tcpdump compatible PCAPs from a BPF map.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL