Adding upstream version 3.2.6.upstream/3.2.6upstream

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

1 files changed, 241 insertions, 0 deletions

diff --git a/doc/man/kxdpgun.8in b/doc/man/kxdpgun.8in
new file mode 100644
index 0000000..3304838
--- /dev/null
+++ b/doc/man/kxdpgun.8in
@@ -0,0 +1,241 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "KXDPGUN" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS"
+.SH NAME
+kxdpgun \- XDP-powered DNS benchmarking tool
+.SH SYNOPSIS
+.sp
+\fBkxdpgun\fP [\fIoptions\fP] \fB\-i\fP \fIfilename\fP \fItargetIP\fP
+.SH DESCRIPTION
+.sp
+Powerful generator of DNS traffic, sending and receiving packets through XDP.
+.sp
+Queries are generated according to a textual file which is read sequentially
+in a loop until a configured duration elapses. The order of queries is not
+guaranteed. Responses are received (unless disabled) and counted, but not
+checked against queries.
+.sp
+The number of parallel threads is autodetected according to the number of queues
+configured for the network interface.
+.SS Options
+.INDENT 0.0
+.TP
+\fB\-t\fP, \fB\-\-duration\fP \fIseconds\fP
+Duration of traffic generation, specified as a decimal number in seconds
+(default is 5.0).
+.TP
+\fB\-T\fP, \fB\-\-tcp\fP[\fB=\fP\fIdebug_mode\fP]
+Send queries over TCP. See the list of optional debug modes below.
+.TP
+\fB\-U\fP, \fB\-\-quic\fP[\fB=\fP\fIdebug_mode\fP]
+Send queries over QUIC. See the list of optional debug modes below.
+.TP
+\fB\-Q\fP, \fB\-\-qps\fP \fIqueries\fP
+Number of queries\-per\-second (approximately) to be sent (default is 1000).
+The program is not optimized for low speeds at which it may lose
+communication packets. The recommended minimum speed is 2 packets per thread
+(Rx/Tx queue).
+.TP
+\fB\-b\fP, \fB\-\-batch\fP \fIsize\fP
+Send more queries in a batch. Improves QPS but may affect the counterpart\(aqs
+packet loss (default is 10 for UDP and 1 for TCP/QUIC).
+.TP
+\fB\-r\fP, \fB\-\-drop\fP
+Drop incoming responses. Improves QPS, but disables response statistics.
+.TP
+\fB\-p\fP, \fB\-\-port\fP \fInumber\fP
+Remote destination port (default is 53 for UDP/TCP, 853 for QUIC).
+.TP
+\fB\-F\fP, \fB\-\-affinity\fP \fIcpu_spec\fP
+CPU affinity for all threads specified in the format [<cpu_start>][s<cpu_step>],
+where <cpu_start> is the CPU ID for the first thread and <cpu_step> is the
+CPU ID increment for next thread (default is 0s1).
+.TP
+\fB\-i\fP, \fB\-\-infile\fP \fIfilename\fP
+Path to a file with query templates.
+.TP
+\fB\-I\fP, \fB\-\-interface\fP \fIinterface\fP
+Network interface for outgoing communication. This can be useful in situations
+when the interfaces are in a bond for example.
+.TP
+\fB\-l\fP, \fB\-\-local\fP \fIlocalIP\fP[\fB/\fP\fIprefix\fP]
+Override the auto\-detected source IP address. If an address range is specified
+instead, various IPs from the range will be used for different queries uniformly
+(address range not supported in the QUIC mode).
+.TP
+\fItargetIP\fP
+The IPv4 or IPv6 address of remote destination.
+.TP
+\fB\-L\fP, \fB\-\-mac\-local\fP
+Override auto\-detected local MAC address.
+.TP
+\fB\-R\fP, \fB\-\-mac\-remote\fP
+Override auto\-detected remote MAC address.
+.TP
+\fB\-v\fP, \fB\-\-vlan\fP \fIid\fP
+Add VLAN 802.1Q header with the given id. VLAN offloading should be disabled.
+.TP
+\fB\-h\fP, \fB\-\-help\fP
+Print the program help.
+.TP
+\fB\-V\fP, \fB\-\-version\fP
+Print the program version.
+.UNINDENT
+.SS Queries file format
+.sp
+Each line describes a query in the form:
+.sp
+\fIquery_name\fP \fIquery_type\fP [\fIflags\fP]
+.sp
+Where \fIquery_name\fP is a domain name to be queried, \fIquery_type\fP is a record type
+name, and \fIflags\fP is a single character:
+.sp
+\fBE\fP Send query with EDNS.
+.sp
+\fBD\fP Request DNSSEC (EDNS + DO flag).
+.SS TCP/QUIC debug modes
+.INDENT 0.0
+.TP
+\fB0\fP
+Perform full handshake for all connections (QUIC only).
+.TP
+\fB1\fP
+Just send SYN (Initial) and receive SYN\-ACK (Handshake).
+.TP
+\fB2\fP
+Perform TCP/QUIC handshake and don\(aqt send anything, allow close initiated by counterpart.
+.TP
+\fB3\fP
+Perform TCP/QUIC handshake and don\(aqt react further.
+.TP
+\fB5\fP
+Send incomplete query (N\-1 bytes) and don\(aqt react further.
+.TP
+\fB7\fP
+Send query and don\(aqt ACK the response or anything further.
+.TP
+\fB8\fP
+Don\(aqt close the connection and ignore close by counterpart (TCP only).
+.TP
+\fB9\fP
+Operate normally except for not ACKing the final FIN+ACK (TCP only).
+.UNINDENT
+.SS Signals
+.sp
+Sending USR1 signal to a running process triggers current statistics dump
+to the standard output.
+.SH NOTES
+.sp
+Linux kernel 4.18+ is required.
+.sp
+The utility has to be executed under root or with these capabilities:
+CAP_NET_RAW, CAP_NET_ADMIN, CAP_SYS_ADMIN, CAP_IPC_LOCK, and CAP_SYS_RESOURCE
+(Linux < 5.11).
+.sp
+The utility allocates source UDP/TCP ports from the range 2000\-65535.
+.SH EXIT VALUES
+.sp
+Exit status of 0 means successful operation. Any other exit status indicates
+an error.
+.SH EXAMPLES
+.sp
+Manually created queries file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+abc6.example.com. AAAA
+nxdomain.example.com. A
+notzone. A
+a.example.com. NS E
+ab.example.com. A D
+abcd.example.com. DS D
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Queries file generated from a zone file (Knot DNS format):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cat ZONE_FILE | awk "{print \e$1,\e$3}" | grep \-E "(NS|DS|A|AAAA|PTR|MX|SOA)$" | sort \-u \-R > queries.txt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Basic usage:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# kxdpgun \-i ~/queries.txt 2001:DB8::1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fIUsing UDP with increased batch size\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# kxdpgun \-t 20 \-Q 1000000 \-i ~/queries.txt \-b 20 \-p 8853 192.0.2.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fIUsing TCP\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# kxdpgun \-t 20 \-Q 100000 \-i ~/queries.txt \-T \-p 8853 192.0.2.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBkdig(1)\fP\&.
+.SH AUTHOR
+CZ.NIC Labs <https://www.knot-dns.cz>
+.SH COPYRIGHT
+Copyright 2010–2023, CZ.NIC, z.s.p.o.
+.\" Generated by docutils manpage writer.
+.