https://github.com/takehaya/xdperf
xdperf is a high-performance network traffic generation tool that leverages XDP (eXpress Data Path).
https://github.com/takehaya/xdperf
ebpf golang wasm xdp
Last synced: 2 months ago
JSON representation
xdperf is a high-performance network traffic generation tool that leverages XDP (eXpress Data Path).
- Host: GitHub
- URL: https://github.com/takehaya/xdperf
- Owner: takehaya
- License: mit
- Created: 2025-10-11T08:42:20.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T21:34:41.000Z (3 months ago)
- Last Synced: 2026-04-03T23:27:00.852Z (3 months ago)
- Topics: ebpf, golang, wasm, xdp
- Language: Go
- Homepage:
- Size: 7.97 MB
- Stars: 71
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# XDPerf
XDPerf is a high-performance network traffic generation tool that leverages XDP (eXpress Data Path). It can operate in both client and server modes, enabling measurement of network throughput and packet rate.
In addition, XDPerf provides a flexible mechanism for transmitting arbitrary packets. This functionality is implemented through a plugin system based on WASM, which eliminates the dependency issues often encountered with Python-based tools like Trex. Another major advantage is that it does not rely on DPDK.
Furthermore, since XDPerf is implemented in Go, it runs as a single binary, making deployment simple and convenient.
You can find the project explanation slides at [./docs/xdperf.pdf](https://github.com/takehaya/xdperf/tree/main/docs/xdperf.pdf).
## Install
Note: You need to install `jq` beforehand.
```shell
# latest install
curl -fsSL https://raw.githubusercontent.com/takehaya/xdperf/main/scripts/install_xdperf.sh | sudo bash
# extra: select version mode
curl -fsSL https://raw.githubusercontent.com/takehaya/xdperf/main/scripts/install_xdperf.sh | sudo bash -s -- --version v0.5.3
```
## Usage
### Commands
xdperf has two main commands
| Command | Description |
|---------|-------------|
| `run` | Run the traffic generator (send or receive mode) |
| `probe` | Probe XDP capabilities of a network device |
### Basic Syntax
```shell
# Traffic generation
sudo xdperf run --device [options]
# Probe XDP support
sudo xdperf probe --device [--json]
```
By default, `simpleudp.tinygo` plugin is used (installed at `/usr/local/share/xdperf/plugins`).
For custom plugin development, see [Plugin Development Guide](./plugins/README.md).
### Basic Examples
```shell
# Send 10,000 packets with default settings
sudo xdperf run --device eth0 --count 10k
# Send packets for 30 seconds at 100k pps
sudo xdperf run --device eth0 --duration 30s --pps 100k
```
### High-Performance Traffic Generation
```shell
# High-throughput: 1M packets with 8 parallel threads at max speed
sudo xdperf run --device eth0 --count 1m --parallelism 8
# Rate-limited: 10 seconds at 500k pps with 4 threads
sudo xdperf run --device eth0 --duration 10s --pps 500k --parallelism 4
```
### Custom Packet Configuration
```shell
# Small packets for PPS testing
sudo xdperf run --device eth0 --count 1m --parallelism 4 \
--cfg '{"dst_port": 10001, "src_ip": "192.168.1.1", "dst_ip": "192.168.1.2", "payload_size": 64}'
# Large packets for throughput testing
sudo xdperf run --device eth0 --count 100k \
--cfg '{"payload_size": 1400}'
sudo xdperf run --device ens4 --count 100k --parallelism 10 \
--cfg '{"dst_port": 10001, "src_ip": "192.168.1.1", "dst_ip": "192.168.1.2", "payload_size": 64}'
```
### Server Mode (Receive Only)
```shell
# Receive only (server mode)
sudo xdperf run --device eth0 --send=false --recv
# Echo server with swap
sudo xdperf run --device eth0 --send=false --recv --swap-resp
```
### Development and Debugging
```shell
# Local build with verbose debugging
sudo ./out/bin/xdperf run \
--plugin simpleudp.go \
--plugin-path ./out/bin \
--device eth0 \
--count 100 \
--debugmode 1
# With NIC statistics
sudo xdperf run --device eth0 --count 1m --show-nic-stats
```
### Probe Command
Check if your device supports XDP and live frame mode:
```shell
# Check XDP capabilities
sudo xdperf probe --device eth0
# Output in JSON format
sudo xdperf probe --device eth0 --json
```
Example output:
```
INFO Probing XDP capabilities {"device": "eth0"}
INFO Device {"name": "eth0"}
INFO XDP Support {"supported": true, "driver_mode": true, "generic_mode": true, "offload_mode": false}
INFO BPF_PROG_RUN Support {"live_frame_mode": true}
INFO Summary: This device is fully compatible with xdperf
```
## For Developers
The following information describes what is required to build the project.
### Prepare
On a Debian-based Linux environment, make sure the following tools are installed:
* make
* [mise](https://github.com/jdx/mise)
* docker
### Development Setup
```shell
make install-dev-pkg
make install-dev-tools
make install-build-tools
# Used by lefthook (explained later)
make install-lint-tools
# Equivalent to pre-commit
lefthook install
```
### Go Binary Build
```shell
# Development build (includes xdperf binary and plugins)
make build
# Build plugins only
make build-plugins
# Build a specific plugin
make simpleudp.tinygo # TinyGo version
make simpleudp.go # Go version
# Build release snapshot with goreleaser
make goreleaser
# Run build test (check for panics)
make test-runnable
```
### BPF Binary Build
```shell
make bpf-gen
# debug pattern
# CEXTRA_FLAGS="-DXDPERF_DEBUG" make bpf-gen
```
### Multi kernel version test
```shell
# Prerequisite: install vimto with static linking (once)
CGO_ENABLED=0 go install lmb.io/vimto@v0.4.0
# Enable KVM access (once, resets on reboot)
sudo chmod 0666 /dev/kvm
# Run tests on a specific kernel version
vimto -kernel :6.1 -- go test -v -count 1 -timeout 5m ./pkg/coreelf/ -run TestBpf
vimto -kernel :6.6 -- go test -v -count 1 -timeout 5m ./pkg/coreelf/ -run TestBpf
vimto -kernel :6.12 -- go test -v -count 1 -timeout 5m ./pkg/coreelf/ -run TestBpf
vimto -kernel :6.18 -- go test -v -count 1 -timeout 5m ./pkg/coreelf/ -run TestBpf
```
## Inspired by
- We implemented the packet transmission mechanism with reference to [xdp-trafficgen](https://github.com/xdp-project/xdp-tools/tree/main/xdp-trafficgen). I think elements such as its probe implementation are excellent.
- We adopted the name xdperf simply because we thought it was a good name. See also [https://github.com/higebu/xdperf](https://github.com/higebu/xdperf)