Adding upstream version 1.3.1.upstream/1.3.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 188 insertions, 0 deletions

diff --git a/xdp-trafficgen/xdp-trafficgen.8 b/xdp-trafficgen/xdp-trafficgen.8
new file mode 100644
index 0000000..3bef2b6
--- /dev/null
+++ b/xdp-trafficgen/xdp-trafficgen.8
@@ -0,0 +1,188 @@
+.TH "xdp-trafficgen" "8" "FEBRUARY  4, 2023" "V1.3.1" "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-bench is:
+
+.RS
+.nf
+\fCUsage: xdp-trafficgen COMMAND [options]
+
+COMMAND can be one of:
+       udp         - run in UDP mode
+       tcp         - run in TCP mode
+\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] <ifname>\fP
+
+.PP
+Where \fI<ifname>\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 <mac addr>"
+.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 <mac addr>"
+.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 <addr>"
+.PP
+Destination IP address of generated packets. The default is the link-local
+\fIfe80::2\fP address.
+
+.SS "-A, --src-addr <addr>"
+.PP
+Source IP address of generated packets. The default is the link-local \fIfe80::1\fP
+address.
+
+.SS "-p, --dst-port <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 <port>"
+.PP
+Source UDP port of generated packets. Defaults to 1.
+
+.SS "-d, --dyn-ports <num ports>"
+.PP
+Enable dynamic port mode where the destination port is varied over a range of
+\fI<num ports>\fP starting from the \fI\-\-dst\-port\fP.
+
+.SS "-n, --num-packets <port>"
+.PP
+Number of packets to send before exiting. If not supplied, \fIxdp\-trafficgen\fP will
+keep sending packets until interrupted.
+
+.SS "-t, --threads <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 <s>"
+.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 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 <ifname> <hostname>\fP
+
+.PP
+Where \fI<ifname>\fP is the name of the destination interface that packets will be
+transmitted on and \fI<hostname>\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 <port>"
+.PP
+Connect to destination <port>. Default 10000.
+
+.SS "-m, --mode <mode>"
+.PP
+Load ingress XDP program in <mode>; default native (valid values: native,skb,hw)
+
+.SS "-n, --num-packets <port>"
+.PP
+Number of packets to send before exiting. If not supplied, \fIxdp\-trafficgen\fP will
+keep sending packets until interrupted.
+
+.SS "-I, --interval <s>"
+.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 "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.