xdpcap

README

xdpcap

xdpcap is a tcpdump like tool for eXpress Data Path (XDP). It can capture packets and actions / return codes from XDP programs, using standard tcpdump / libpcap filter expressions.

Instrumentation

XDP programs need to expose at least one hook point:

struct bpf_map_def xdpcap_hook = {
	.type = BPF_MAP_TYPE_PROG_ARRAY,
	.key_size = sizeof(int),
	.value_size = sizeof(int),
	.max_entries = 4, // The max value of XDP_* constants
};

This map must be pinned inside a bpffs.

hook.h provides a convenience macro for declaring such maps:

#include "hook.h"

struct bpf_map_def xdpcap_hook = XDPCAP_HOOK();

return XDP_* statements should be modified to "feed" a hook:

#include "hook.h"

struct bpf_map_def xdpcap_hook = XDPCAP_HOOK();

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

For a full example, see testdata/xdp_hook.c.

Depending on the granularity desired, a program can expose multiple hook points, or a hook can be reused across programs by using the same underlying map.

Package xdpcap provides a wrapper for creating and pinning the hook maps using the newtools/ebpf loader.

Installation

go get -u github.com/cloudflare/xdpcap/cmd/xdpcap

Usage

• Capture packets to a pcap: xdpcap /path/to/pinned/map dump.pcap "tcp and port 80"

• Display captured packets: sudo xdpcap /path/to/pinned/map - "tcp and port 80" | sudo tcpdump -r -

Limitations

• filters run after the instrumented XDP program. If the program modifies the packet, the filter should match the modified packet, not the original input packet.

Tests

• sudo -E $(which go) test

Documentation

Index

• Variables
• type Hook
  • func NewHook(fileName string) (*Hook, error)
  • func (h *Hook) Close() error
  • func (h *Hook) Patch(spec *ebpf.CollectionSpec, hookMapSymbol string) error
  • func (h *Hook) Pin() error
  • func (h *Hook) Rm() error

Variables

var HookMapABI = ebpf.MapABI{
	Type:      ebpf.ProgramArray,
	KeySize:   4,
	ValueSize: 4,
}

HookMapABI is the ABI of the underlying prog map created

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()