diff options
Diffstat (limited to 'doc/man/kxdpgun.8')
| -rw-r--r-- | doc/man/kxdpgun.8 | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/doc/man/kxdpgun.8 b/doc/man/kxdpgun.8 new file mode 100644 index 0000000..d7892eb --- /dev/null +++ b/doc/man/kxdpgun.8 @@ -0,0 +1,299 @@ +.\" 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" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +kxdpgun \- XDP-powered DNS benchmarking tool +.SH SYNOPSIS +.sp +\fBkxdpgun\fP [\fIoptions\fP] \fB\-i\fP \fIfilename\fP \fItarget\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 Parameters +.INDENT 0.0 +.TP +.B \fIfilename\fP +Path to the queries file. See the description below regarding the file format. +.TP +.B \fItarget\fP +Either the domain name, IPv4 or IPv6 address of a remote target. +.UNINDENT +.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\-B\fP, \fB\-\-binary\fP +Specify that input file is in binary format. This format is similar to the +TCP DNS message format. The file contains records formated as 2\-octet length +(network order) followed by a message in DNS wire format. +.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 +\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\-e\fP, \fB\-\-edns\-size\fP \fIsize\fP +EDNS UDP payload size, range 512\-4096 (default is 1232). Note that over XDP +the maximum supported MTU is 1790. +.TP +\fB\-m\fP, \fB\-\-mode\fP \fImode\fP +Set the XDP mode. Supported values are: +.INDENT 7.0 +.IP \(bu 2 +\fBauto\fP (default) – the XDP mode is selected automatically to achieve +the best performance, which means that native driver support is preferred +over the generic one, and zero\-copy is used if available. +.IP \(bu 2 +\fBcopy\fP – the XDP socket copy mode is forced even if zero\-copy +is available. This can resolve various driver issues, but at the cost +of lower performance. +.IP \(bu 2 +\fBgeneric\fP – the generic XDP implementation is forced even if native +implementation is available. This mode doesn\(aqt require support from the +driver nor hardware, but offers the worst performance. +.UNINDENT +.TP +\fB\-G\fP, \fB\-\-qlog\fP \fIpath\fP +Generate qlog files in the directory specified by \fIpath\fP\&. The directory +has to exist. +.sp +This option is ignored if not in the QUIC mode. The recommended usage is +with \fB\-\-quic=R\fP or with low QPS. Otherwise, too many files are generated. +.TP +\fB\-j\fP, \fB\-\-json\fP +Print statistics formatted as json. +.TP +\fB\-S\fP, \fB\-\-stats\-period\fP \fIperiod\fP +Report statistics automatically every \fIperiod\fP milliseconds. +.sp +These reports contain only metrics collected in the given period. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.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. +.TP +\fB9\fP +Operate normally except for not ACKing the final FIN+ACK (TCP only). +.TP +\fBR\fP +Instead of opening a connection for each query, reuse connections. +.UNINDENT +.SS Signals +.sp +Sending USR1 signal to a running process triggers current statistics dump +to the standard output. In combination with \fB\-S\fP may cause erratic printout +timing. +.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. +.sp +Due to the multi\-threaded program structure there are slight discrepancies in +the timespan during which metrics are collected for any given thread. The +statistics printouts ignore this and are thus ever\-so\-slightly inaccurate. The +error margin decreases proportionally to the volume of data & timespan over +which they are collected. +.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 \(dq{print \e$1,\e$3}\(dq | grep \-E \(dq(NS|DS|A|AAAA|PTR|MX|SOA)$\(dq | 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–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. |