xdperf

README

xdperf

⚠️ This repository is archived. ⚠️

This project was created as an example for a presentation at eBPF Japan Meetup #4. The presentation slides are available at Docswell.

Please use takehaya/xdperf instead, which is a more feature-rich and actively maintained tool with a WASM-based plugin system.

Overview

xdperf is a high-performance network traffic generation and analysis tool that utilizes XDP (eXpress Data Path). It can operate in both client and server modes to test network throughput and packet rates.

Features

• Client/Server Mode: Can act as a traffic generator (client) or a packet counter (server).
• XDP-based Packet Processing: Leverages XDP for fast packet redirection and counting directly in the kernel.
• Configurable Parameters:
  • Source/Destination IP Addresses
  • Source/Destination MAC Addresses
  • Source/Destination UDP Ports
  • Packet Size
  • Number of Goroutines for Traffic Generation

Requirements

• Linux Kernel with XDP and BPF_F_TEST_XDP_LIVE_FRAMES support (5.18 or newer)
• Go 1.24.2 or later (as specified in go.mod)
• clang
• libbpf-dev
• libxdp-dev

Installation

To install xdperf, you need to have Go installed on your system. You can install it using the following command:

go install github.com/higebu/xdperf@latest

Usage

Server Mode

The server mode listens on a specified network interface and UDP port, counting incoming packets that match the port.

Command:

sudo xdperf --server --port <port> <device>

Example:

sudo xdperf --server --port 12345 eth0

This starts the server on interface eth0, listening for UDP packets on port 12345.

Client Mode

The client mode generates and sends UDP packets to a specified destination.

Command:

sudo xdperf [flags] <device>

Flags:

• --src-ip <ip>: Source IP address (default: 127.0.0.1)
• --dst-ip <ip>: Destination IP address (default: 127.0.0.1)
• --src-port <port>: Source UDP port (default: 12345)
• --dst-port <port>: Destination UDP port (default: 12345)
• --src-mac <mac>: Source MAC address (default: MAC of the redirect device)
• --dst-mac <mac>: Destination MAC address (default: 00:00:00:00:00:00)
• -s, --size <bytes>: Packet size in bytes (default: 64)
• -p, --parallel <num>: Number of goroutines for sending packets (default: 1)
• --pps <num>: Packets per second (default: 0, no rate limit)
• --batch-size <num>: Number of packets to send in a batch (default: 1 or 1048576 if no rate limit)

Example:

Sending traffic from eth0 to 192.168.1.100:8080:

sudo xdperf --dst-ip 192.168.1.100 --dst-mac 00:00:00:00:00:00 --dst-port 8080 eth0

Sending traffic with 100-byte packets using 4 goroutines:

sudo xdperf --dst-ip 192.168.1.100 --dst-mac 00:00:00:00:00:00 --dst-port 8080 -s 100 -p 4 eth0

License

MIT License

Documentation

Index

• type Client
  • func NewClient(dev *net.Interface, opts ...ClientOption) (*Client, error)
  • func (c *Client) Run() error
• type ClientOption
  • func WithBatchSize(batchSize uint32) ClientOption
  • func WithDstIP(ip net.IP) ClientOption
  • func WithDstMac(mac net.HardwareAddr) ClientOption
  • func WithDstPort(port int) ClientOption
  • func WithPPS(pps uint64) ClientOption
  • func WithPacketSize(size int) ClientOption
  • func WithParallel(parallel int) ClientOption
  • func WithSrcIP(ip net.IP) ClientOption
  • func WithSrcMac(mac net.HardwareAddr) ClientOption
  • func WithSrcPort(port int) ClientOption
  • func WithTx(tx bool) ClientOption
• type ClientParams
• type Server
  • func NewServer(dev *net.Interface, port int) *Server
  • func (s *Server) Run() error

Types

type Client

type Client struct {
	Params ClientParams
	// contains filtered or unexported fields
}

Client represents the Client.

func NewClient

func NewClient(dev *net.Interface, opts ...ClientOption) (*Client, error)

NewClient creates a new Client instance with default parameters.

func (*Client) Run

func (c *Client) Run() error

Run starts the xdperf application with the provided parameters.

type ClientOption

type ClientOption func(*Client)

ClientOption defines a function that modifies the Xdperf parameters.

func WithBatchSize

func WithBatchSize(batchSize uint32) ClientOption

WithBatchSize sets the batch size for sending packets.

func WithDstIP

func WithDstIP(ip net.IP) ClientOption

WithDstIP sets the destination IP address.

func WithDstMac

func WithDstMac(mac net.HardwareAddr) ClientOption

WithDstMac sets the destination MAC address.

func WithDstPort

func WithDstPort(port int) ClientOption

WithDstPort sets the destination UDP port.

func WithPPS

func WithPPS(pps uint64) ClientOption

WithPPS sets the packets per second rate.

func WithPacketSize

func WithPacketSize(size int) ClientOption

WithPacketSize sets the size of the packets to send.

func WithParallel

func WithParallel(parallel int) ClientOption

WithParallel sets the number of parallel threads to use.

func WithSrcIP

func WithSrcIP(ip net.IP) ClientOption

WithSrcIP sets the source IP address.

func WithSrcMac

func WithSrcMac(mac net.HardwareAddr) ClientOption

WithSrcMac sets the source MAC address.

func WithSrcPort

func WithSrcPort(port int) ClientOption

WithSrcPort sets the source UDP port.

func WithTx

func WithTx(tx bool) ClientOption

WithTx sets the client to use XDP_TX mode instead of XDP_REDIRECT.

type ClientParams

type ClientParams struct {
	SrcIP      net.IP
	DstIP      net.IP
	SrcPort    int
	DstPort    int
	SrcMac     net.HardwareAddr
	DstMac     net.HardwareAddr
	PacketSize int
	Parallel   int
	PPS        uint64
	BatchSize  uint32
	Tx         bool
	Device     *net.Interface
}

ClientParams holds the parameters for the xdperf application.

type Server

type Server struct {
	Port   int
	Device *net.Interface
	// contains filtered or unexported fields
}

Server represents the server configuration for xdperf.

func NewServer

func NewServer(dev *net.Interface, port int) *Server

NewServer creates a new Server instance with the specified attach device and port.

func (*Server) Run

func (s *Server) Run() error

Run starts the xdperf server, attaching the XDP program to count packets.