xdp-trafficgen(8)

NAME
XDP-trafficgen - an XDP-based traffic generator

SYNOPSIS

XDP-trafficgen is a packet generator utilising the XDP kernel subsystem to generate packets transmit them through a network interface. Packets are dynamically generated and transmitted in the kernel, allowing for high performance (millions of packets per second per core).

XDP-trafficgen supports generating UDP traffic with fixed or dynamic destination ports, and also has basic support for generating dummy TCP traffic on a single flow.

  Running xdp-traffigen

The syntax for running xdp-trafficgen is:
    Usage: xdp-trafficgen COMMAND [options]
    COMMAND can be one of:
           udp         - run in UDP mode
           tcp         - run in TCP mode
           probe       - probe kernel support

Each command, and its options are explained below. Or use xdp-trafficgen COMMAND --help to see the options for each command.

The UDP command

The UDP command generates UDP traffic to a given destination IP and either a fixed destination port, or a range of port numbers. Only IPv6 traffic is supported, and the generated packets will have their IP hop limit set to 1, so they can't be routed.

The syntax for the udp command is:

xdp-trafficgen udp [options] <ifname>

Where <ifname> is the name of the destination interface that packets will be transmitted on. Note that the network driver of this network interface must support being the target of XDP redirects (it must implement the ndo_xdp_xmit driver operation).

The supported options are:

  -m, --dst-mac <mac addr>

Set the destination MAC address of generated packets. The default is to generate packets with an all-zero destination MAC.

  -M, --src-mac <mac addr>

Set the source MAC address of the generated packets. The default is to use the MAC address of the interface packets are transmitted on.

  -a, --dst-addr <addr>

Destination IP address of generated packets. The default is the link-local fe80::2 address.

  -A, --src-addr <addr>

Source IP address of generated packets. The default is the link-local fe80::1 address.

  -p, --dst-port <port>

Destination UDP port of generated packets, or the first port in the range if running with --dyn-ports set. Defaults to 1.

  -P, --src-port <port>

Source UDP port of generated packets. Defaults to 1.

  -d, --dyn-ports <num ports>

Enable dynamic port mode where the destination port is varied over a range of <num ports> starting from the --dst-port.

  -n, --num-packets <num packets>

Number of packets to send before exiting. If not supplied, xdp-trafficgen will keep sending packets until interrupted.

  -s, --pkt-size <bytes>

Size of each UDP packet being sent, including the Ethernet header. The minimum size, which is also the default, is 64 bytes.

  -t, --threads <threads>

Number of simultaneous threads to transmit from. Each thread will be pinned to a separate CPU core if possible. Defaults to 1.

  -I, --interval <s>

Output transmission statistics with this interval (in seconds).

  -v, --verbose

Enable verbose logging (-vv: more verbose).

  --version

Display version information and exit.

  -h, --help

Display a summary of the available options

The TCP command

The TCP command generates dummy TCP traffic in a single TCP flow. This relies on first installing an ingress XDP program on the interface used to transmit on. Then, a regular TCP socket connection is established from userspace, and once the handshake is completed, the XDP program will take over and start generating traffic on that flow tuple. The ingress XDP program will intercept ACK packets from the receiver, and keep track of the receive window.

The traffic generator has no congestion control, and only very basic retransmit tracking: in essence, any duplicate ACKs from the receiver will cause the sender to reset its send sequence number to the last ACKed value and restart from there. The same thing happens if no progress on the window is made within two seconds. This means that the traffic generator can generate a large amount of dummy traffic, but if there's packet loss a lot of this can be retransmissions.

The syntax for the tcp command is:

xdp-trafficgen tcp [options] -i <ifname> <hostname>

Where <ifname> is the name of the destination interface that packets will be transmitted on and <hostname> is the peer hostname or IP address to connect to (only IPv6 is supported). Note that the network driver of this network interface must support being the target of XDP redirects (it must implement the ndo_xdp_xmit driver operation).

The supported options are:

  -p, --dst-port <port>

Connect to destination <port>. Default 10000.

  -m, --mode <mode>

Load ingress XDP program in <mode>; default native (valid values: native,skb,hw)

  -n, --num-packets <port>

Number of packets to send before exiting. If not supplied, xdp-trafficgen will keep sending packets until interrupted.

  -I, --interval <s>

Output transmission statistics with this interval (in seconds).

  -v, --verbose

Enable verbose logging (-vv: more verbose).

  --version

Display version information and exit.

  -h, --help

Display a summary of the available options

The PROBE command

The PROBE command probes the kernel to discover whether it supports the features needed to run xdp-trafficgen. This can be used to discover whether the running kernel is compatible with xdp-trafficgen, as well as to discover whether a particular interface supports sending packets generated by xdp-trafficgen.

The syntax for the probe command is:

xdp-trafficgen probe [options]

After probing, xdp-trafficgen will print the results of the probing of the kernel, and (if an interface name is supplied), whether the interface supports sending packets generated by xdp-trafficgen. The exit code will be 0 if all probes succeed, and 1 otherwise.

Note that the probing relies on the kernel XDP feature reporting, which was added after the XDP support itself. This means that with some older kernel versions, the probing may fail even though xdp-trafficgen would in fact be able to transmit packets.

The supported options are:

  -i, --ifname <ifname>

Probe the supplied interface name, in addition to doing the general kernel probing.

  -v, --verbose

Enable verbose logging (-vv: more verbose).

  --version

Display version information and exit.

  -h, --help

Display a summary of the available options

BUGS

Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues

AUTHOR

xdp-trafficgen and this man page were written by Toke Høiland-Jørgensen.