xdpcap

A high-performance packet capture tool using XDP/eBPF that captures only packet headers, not payload data.

Features

• XDP-based capture: Captures packets at the earliest point in the network stack for maximum performance
• Header capture: Captures L2-L7 headers (up to 512 bytes), including HTTP, TLS, DNS headers while reducing storage requirements
• IPv4 and IPv6 support: Full support for both IP versions
• Flow-based filtering: Exclude specific traffic flows from capture (e.g., backup traffic, known file transfers)
• Time-based rotation: Automatically rotates pcap files at configurable intervals
• Zero-copy ring buffer: Efficient packet transfer from kernel to userspace
• Non-intrusive: Always passes packets through (XDP_PASS), never drops traffic

Requirements

• Linux kernel 5.8+ (for ring buffer and BTF support)
• Go 1.21+
• Clang/LLVM (for compiling eBPF program)
• libbpf development headers
• bpftool (for generating vmlinux.h)
• Root privileges (for attaching XDP programs)

Building

Install Build Dependencies (Ubuntu/Debian)

# Install all required build dependencies
sudo add-apt-repository ppa:longsleep/golang-backports
sudo apt-get update
sudo apt-get install -y \
clang \
llvm \
libbpf-dev \
linux-tools-common \
linux-tools-$(uname -r) \
golang-go
# Or use the Makefile target
sudo make deps-system

Build

# Download Go module dependencies
make deps
# Compile eBPF program and generate Go bindings# (automatically generates vmlinux.h from kernel BTF)
make generate
# Build the binary
make build
# Or do everything at once
make all

Installation

# Install binary to /usr/local/bin and config to /etc/xdpcap
sudo make install

Usage

# Run with default config file (/etc/xdpcap/xdpcap.yaml)
sudo xdpcap
# Specify a custom config file
sudo xdpcap -c /path/to/config.yaml
# Override interface and output directory
sudo xdpcap -i eth0 -o /var/log/captures
# Enable verbose mode (periodic stats output)
sudo xdpcap -i eth0 -v

Command Line Options

Flag	Description	Default
-c, --config	Path to configuration file	/etc/xdpcap/xdpcap.yaml
-i, --interface	Network interface to capture from	(from config)
-o, --output-dir	Directory for pcap files	/var/log/xdpcap
-v, --verbose	Enable verbose output with periodic stats	false

Configuration

Configuration is done via a YAML file. See configs/xdpcap.yaml.example for a complete example.

# Network interface to capture frominterface: eth0# Directory to store pcap filesoutput_dir: /var/log/xdpcap# Pcap file rotation intervalrotation_interval: 5m# Flows to exclude from captureexclude_flows:
# Exclude SSH traffic from backup server
- name: "backup-ssh"src_ip: "10.0.0.100"dst_port: 22protocol: tcp# Exclude all DNS responses
- name: "dns-responses"src_port: 53protocol: udp

Filter Rule Fields

Field	Description	Example
name	Descriptive name for the rule	"backup-traffic"
src_ip	Source IP address (v4 or v6)	"10.0.0.1", "2001:db8::1"
dst_ip	Destination IP address	"192.168.1.50"
src_port	Source port number	53
dst_port	Destination port number	22
protocol	Protocol (tcp, udp, icmp, icmpv6)	"tcp"

All fields except name are optional. Omitted fields match any value.

Output

Captured packets are written to pcap files in the output directory:

/var/log/xdpcap/
├── xdpcap_eth0_20240115-143022.pcap
├── xdpcap_eth0_20240115-143522.pcap
└── xdpcap_eth0_20240115-144022.pcap

Files are rotated based on the configured interval. Each file contains standard pcap format data that can be analyzed with tools like Wireshark, tcpdump, or tshark.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│ xdpcap CLI (Go) │
├─────────────────────────────────────────────────────────────────┤
│ Config Loader │ PCAP Writer │ Stats Reporter │ Signals │
├─────────────────────────────────────────────────────────────────┤
│ eBPF Map Interface │
│ (filter rules, packet ring buffer, stats) │
├─────────────────────────────────────────────────────────────────┤
│ XDP Program (C/eBPF) │
│ - Parse L2-L4 headers (Ethernet, IPv4/IPv6, TCP/UDP/ICMP) │
│ - Check against filter map (exclude matching flows) │
│ - Copy headers to ring buffer │
│ - Always return XDP_PASS (non-intrusive) │
└─────────────────────────────────────────────────────────────────┘
│
▼
Network Interface

Development

# Run tests
make test# Run linter
make lint
# Clean build artifacts
make clean

Project Structure

xdpcap/
├── cmd/xdpcap/ # CLI entry point
├── internal/
│ ├── config/ # YAML configuration parsing
│ ├── capture/ # eBPF program loading and packet capture
│ └── writer/ # Time-rotated pcap file writer
├── bpf/ # XDP/eBPF program (C)
├── configs/ # Example configuration files
├── Makefile
└── README.md

License

MIT License