.TH "xdp-trafficgen" "8" "FEBRUARY 19, 2026" "V1.6.3" "An XDP-based traffic generator" .SH "NAME" XDP-trafficgen \- an XDP-based traffic generator .SH "SYNOPSIS" .PP 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). .PP 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. .SS "Running xdp-traffigen" .PP The syntax for running xdp-trafficgen is: .RS .nf \fCUsage: xdp-trafficgen COMMAND [options] COMMAND can be one of: udp - run in UDP mode xsk-udp - run in UDP mode (using AF_XDP sockets) tcp - run in TCP mode probe - probe kernel support \fP .fi .RE .PP Each command, and its options are explained below. Or use \fIxdp\-trafficgen COMMAND \-\-help\fP to see the options for each command. .SH "The UDP command" .PP 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. .PP The syntax for the \fIudp\fP command is: .PP \fIxdp\-trafficgen udp [options] \fP .PP Where \fI\fP 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 \fIndo_xdp_xmit\fP driver operation). .PP The supported options are: .SS "-m, --dst-mac " .PP Set the destination MAC address of generated packets. The default is to generate packets with an all-zero destination MAC. .SS "-M, --src-mac " .PP Set the source MAC address of the generated packets. The default is to use the MAC address of the interface packets are transmitted on. .SS "-a, --dst-addr " .PP Destination IP address of generated packets. The default is the link-local \fIfe80::2\fP address. .SS "-A, --src-addr " .PP Source IP address of generated packets. The default is the link-local \fIfe80::1\fP address. .SS "-p, --dst-port " .PP Destination UDP port of generated packets, or the first port in the range if running with \fI\-\-dyn\-ports\fP set. Defaults to 1. .SS "-P, --src-port " .PP Source UDP port of generated packets. Defaults to 1. .SS "-d, --dyn-ports " .PP Enable dynamic port mode where the destination port is varied over a range of \fI\fP starting from the \fI\-\-dst\-port\fP. .SS "-n, --num-packets " .PP Number of packets to send before exiting. If not supplied, \fIxdp\-trafficgen\fP will keep sending packets until interrupted. .SS "-s, --pkt-size " .PP Size of each UDP packet being sent, including the Ethernet header and checksum. Since \fIxdp\-trafficgen\fP generates IPv6 traffic, the minimum size, which is also the default, is 66 bytes. .PP Older versions of \fIxdp\-trafficgen\fP failed to account for the four-byte ethernet checksum that is added at the end of packet, which meant that 64 was allowed (and the default) for size, even though this really generated 68-byte packets on the wire. To be able to fix this bug without breaking existing users, values of 64 or 65 will be clamped to the actual minimum value of 66 with a warning, instead of producing an error. .SS "-t, --threads " .PP Number of simultaneous threads to transmit from. Each thread will be pinned to a separate CPU core if possible. Defaults to 1. .SS "-I, --interval " .PP Output transmission statistics with this interval (in seconds). .SS "-v, --verbose" .PP Enable verbose logging (-vv: more verbose). .SS "--version" .PP Display version information and exit. .SS "-h, --help" .PP Display a summary of the available options .SH "The XSK-UDP command" .PP The \fIxsk\-udp\fP command also generates UDP traffic, but does so using an \fIAF_XDP\fP socket generates the traffic in userspace. This can be used to test and benchmark \fIAF_XDP\fP sockets for transmitting. .PP The code for this commands is derived from the \fIxdpsock\fP utility previously part of the kernel sources, and more recently the bpf-examples repository. This command corresponds to the \fI\-\-txonly\fP option of \fIxdpsock\fP. .PP The syntax for this command is: .PP \fIxdp\-trafficgen xsk\-udp [options] \fP .PP The supported options are: .SS "-m, --dst-mac " .PP Set the destination MAC address of generated packets. The default is to generate packets with an all-zero destination MAC. .SS "-M, --src-mac " .PP Set the source MAC address of the generated packets. The default is to use the MAC address of the interface packets are transmitted on. .SS "-y, --timestamp" .PP Add a timestamp to each packet, using the same header format used by the kernel \fIpktgen\fP utility. .SS "-V, --vlan-tag" .PP Add a vlan tag to packets, using the ID and PRI specified using the \fI\-\-vlan\-id\fP and \fI\-\-vlan\-pri\fP options. .SS "-J, --vlan-id" .PP Set the vlan ID used for packets. Only has an effect when the \fI\-\-vlan\-tag\fP option is set. Default: 1. .SS "-K, --vlan-pri" .PP Set the vlan PRI used for packets. Only has an effect when the \fI\-\-vlan\-tag\fP option is set. Default: 0. .SS "-P, --fill-pattern " .PP Use this pattern to fill the packet data. The data pattern is specified as a 32-bit hex value, and defaults to 0. .SS "-T, --tx-cycle-time " .PP Specify an interval between packet bursts, in microseconds. Each interval, a burst of \fI\-\-batch\-size\fP packets are sent. The default is 0 (send packets as fast as possible). .SS "-q, --queue " .PP Select the hardware receive queue to use for the test. The \fIAF_XDP\fP socket is bound to this queue, which means that \fIxdp\-trafficgen\fP will process all packets arriving on it. The default is to use queue 0. .SS "-i, --interval " .PP Set the polling interval for collecting all statistics and displaying them to the output. The default interval is 2 seconds. .SS "-O, --retries " .PP Set the maximum number retries when completing the last packets of a test run. When ending a test run, \fIxdp\-trafficgen\fP will try to release the last packet ring descriptors before exiting, retrying this many times with a 1-second interval in-between. This is only used when \fI\-\-pkt\-count\fP is set. .SS "-f, --frame-size " .PP Set the size of the memory frames used to transmit packets. Packets will always use a memory chunk of this size, regardless of the size of the packet on the wire. The size must be a power of two, unless the \fI\-\-unaligned\fP flag is used. The default is 4096 bytes (which corresponds to the page size on most systems). .SS "-s, --pkt-size " .PP Set the size of the packets being transmitted. This must be between 64 and 9728 bytes, and defaults to 64. .SS "-d, --duration " .PP Set the test duration, in seconds. The default is 0 (run forever, or until \fI\-\-pkt\-count\fP packets have been sent). .SS "-c, --pkt-count " .PP Set the total number of packets to transmit before exiting. The default is 0 (which means run forever, or until \fI\-\-duration\fP is reached). .SS "-b, --batch-size " .PP Set the batch size for the packet processing loop. This is the number of packets sent at once each time the loop runs. The default is 64 packets. See also \fI\-\-tx\-cycle\-time\fP. .SS "-I, --irq-string " .PP Enable printing of interrupt statistics for the interrupt number associated with \fIirq\-string\fP in /proc/interrupts. The string is used to find a matching IRQ number by simple substring matching. No default (which means no IRQ statistics are printed). .SS "-p, --poll" .PP Use the \fIpoll()\fP system call to get notifications for when a socket is ready to transmit new packets, instead of running in a loop constantly attempting to transmit. .SS "-m, --no-need-wakeup" .PP Don't set the \fIXDP_USE_NEED_WAKEUP\fP flag when binding the \fIAF_XDP\fP socket. The flag is set by default, and causes the kernel driver to occasionally go to sleep and yield the CPU to the userspace application when processing packets. .SS "-u, --unaligned" .PP Support sending unaligned packets, i.e., packets that are not aligned to the beginning of a data frame. When set, \fIxdp\-trafficgen\fP will enable huge pages for the userspace memory buffer used to hold the packet data being transmitted. Setting this option enables frame sizes that are not a power of two (see the \fI\-\-frame\-size\fP option). .SS "-M, --shared-umem" .PP Enable shared userspace memory across multiple \fIAF_XDP\fP sockets. When this option is set, \fIxdp\-trafficgen\fP will create four sockets that share the same userspace memory buffer, and packets will be sent on each socket in a round-robin fashion. .SS "-x, --extra-stats" .PP Print extra packet statistics at each output interval. .SS "-Q, --quiet" .PP Don't print any statistics at each output interval. .SS "-a, --app-stats" .PP Print additional application-level statistics at each output interval. .SS "-C, --copy-mode " .PP Select the copying mode for the packets. Set to one of \fIauto\fP, \fIcopy\fP, or \fIzero\-copy\fP. The default is \fIauto\fP, which lets the kernel pick. Using zero-copy requires kernel and driver support, and can only be used when attaching the XDP program in native mode (see \fI\-\-attach\-mode\fP). .SS "-w, --clock " .PP Choose the clock that will be used for all timer events in the application. The valid values are MONOTONIC, REALTIME, TAI and BOOTTIME, and the default is MONOTONIC. .SS "-W, --policy " .PP Set the scheduler policy for the application before running. Valid values are \fISCHED_OTHER\fP and \fISCHED_FIFO\fP, and the default is \fISCHED_OTHER\fP. .SS "-U, --schpri " .PP Set the scheduler priority when using \fISCHED_FIFO\fP. Defaults to 0. .SS "-A, --attach-mode " .PP Set the XDP program attach mode (native or skb) of the XDP program that \fIxdp\-trafficgen\fP attaches to the interface to enable XDP support. The default is native mode. Note that zero-copy can only be used in native mode. .SS "-v, --verbose" .PP Enable verbose logging. Supply twice to enable verbose logging from the underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. .SS "--version" .PP Show the application version and exit. .SS "-h, --help" .PP Display a summary of the available options .SH "The TCP command" .PP 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. .PP 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. .PP The syntax for the \fItcp\fP command is: .PP \fIxdp\-trafficgen tcp [options] \-i \fP .PP Where \fI\fP is the name of the destination interface that packets will be transmitted on and \fI\fP 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 \fIndo_xdp_xmit\fP driver operation). .PP The supported options are: .SS "-p, --dst-port " .PP Connect to destination . Default 10000. .SS "-m, --mode " .PP Load ingress XDP program in ; default native (valid values: native,skb,hw) .SS "-n, --num-packets " .PP Number of packets to send before exiting. If not supplied, \fIxdp\-trafficgen\fP will keep sending packets until interrupted. .SS "-I, --interval " .PP Output transmission statistics with this interval (in seconds). .SS "-v, --verbose" .PP Enable verbose logging (-vv: more verbose). .SS "--version" .PP Display version information and exit. .SS "-h, --help" .PP Display a summary of the available options .SH "The PROBE command" .PP 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. .PP The syntax for the \fIprobe\fP command is: .PP \fIxdp\-trafficgen probe [options]\fP .PP 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. .PP 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. .PP The supported options are: .SS "-i, --ifname " .PP Probe the supplied interface name, in addition to doing the general kernel probing. .SS "-v, --verbose" .PP Enable verbose logging (-vv: more verbose). .SS "--version" .PP Display version information and exit. .SS "-h, --help" .PP Display a summary of the available options .SH "BUGS" .PP Please report any bugs on Github: \fIhttps://github.com/xdp-project/xdp-tools/issues\fP .SH "AUTHOR" .PP xdp-trafficgen and this man page were written by Toke Høiland-Jørgensen.