xdpcap

package module
Version: v0.0.0-...-17bf89d Latest Latest
Warning

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

Go to latest
Published: Dec 16, 2021 License: BSD-3-Clause Imports: 5 Imported by: 0

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

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

Source Files

Directories

Path Synopsis
cmd
bpfoff
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
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