diff options
Diffstat (limited to 'doc/man/kxdpgun.8in')
| -rw-r--r-- | doc/man/kxdpgun.8in | 241 |
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. +. |