diff options
Diffstat (limited to 'doc/man_kxdpgun.rst')
| -rw-r--r-- | doc/man_kxdpgun.rst | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/doc/man_kxdpgun.rst b/doc/man_kxdpgun.rst new file mode 100644 index 0000000..bb6c917 --- /dev/null +++ b/doc/man_kxdpgun.rst @@ -0,0 +1,183 @@ +.. highlight:: console + +``kxdpgun`` – DNS benchmarking tool +=================================== + +Synopsis +-------- + +:program:`kxdpgun` [*options*] **-i** *filename* *targetIP* + +Description +----------- + +Powerful generator of DNS traffic, sending and receiving packets through XDP. + +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. + +The number of parallel threads is autodetected according to the number of queues +configured for the network interface. + +Options +....... + +**-t**, **--duration** *seconds* + Duration of traffic generation, specified as a decimal number in seconds + (default is 5.0). + +**-T**, **--tcp**\[\ **=**\ *debug_mode*\] + Send queries over TCP. See the list of optional debug modes below. + +**-U**, **--quic**\[\ **=**\ *debug_mode*\] + Send queries over QUIC. See the list of optional debug modes below. + +**-Q**, **--qps** *queries* + 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). + +**-b**, **--batch** *size* + Send more queries in a batch. Improves QPS but may affect the counterpart's + packet loss (default is 10 for UDP and 1 for TCP/QUIC). + +**-r**, **--drop** + Drop incoming responses. Improves QPS, but disables response statistics. + +**-p**, **--port** *number* + Remote destination port (default is 53 for UDP/TCP, 853 for QUIC). + +**-F**, **--affinity** *cpu_spec* + 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). + +**-i**, **--infile** *filename* + Path to a file with query templates. + +**-I**, **--interface** *interface* + Network interface for outgoing communication. This can be useful in situations + when the interfaces are in a bond for example. + +**-l**, **--local** *localIP*\ [**/**\ *prefix*] + 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). + +*targetIP* + The IPv4 or IPv6 address of remote destination. + +**-L**, **--mac-local** + Override auto-detected local MAC address. + +**-R**, **--mac-remote** + Override auto-detected remote MAC address. + +**-v**, **--vlan** *id* + Add VLAN 802.1Q header with the given id. VLAN offloading should be disabled. + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. + +Queries file format +................... + +Each line describes a query in the form: + +*query_name* *query_type* [*flags*] + +Where *query_name* is a domain name to be queried, *query_type* is a record type +name, and *flags* is a single character: + +**E** Send query with EDNS. + +**D** Request DNSSEC (EDNS + DO flag). + +TCP/QUIC debug modes +.................... + +**0** + Perform full handshake for all connections (QUIC only). + +**1** + Just send SYN (Initial) and receive SYN-ACK (Handshake). + +**2** + Perform TCP/QUIC handshake and don't send anything, allow close initiated by counterpart. + +**3** + Perform TCP/QUIC handshake and don't react further. + +**5** + Send incomplete query (N-1 bytes) and don't react further. + +**7** + Send query and don't ACK the response or anything further. + +**8** + Don't close the connection and ignore close by counterpart (TCP only). + +**9** + Operate normally except for not ACKing the final FIN+ACK (TCP only). + +Signals +....... + +Sending USR1 signal to a running process triggers current statistics dump +to the standard output. + +Notes +----- + +Linux kernel 4.18+ is required. + +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). + +The utility allocates source UDP/TCP ports from the range 2000-65535. + +Exit values +----------- + +Exit status of 0 means successful operation. Any other exit status indicates +an error. + +Examples +-------- + +Manually created queries file:: + + 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 + +Queries file generated from a zone file (Knot DNS format):: + + cat ZONE_FILE | awk "{print \$1,\$3}" | grep -E "(NS|DS|A|AAAA|PTR|MX|SOA)$" | sort -u -R > queries.txt + +Basic usage:: + + # kxdpgun -i ~/queries.txt 2001:DB8::1 + +*Using UDP with increased batch size*:: + + # kxdpgun -t 20 -Q 1000000 -i ~/queries.txt -b 20 -p 8853 192.0.2.1 + +*Using TCP*:: + + # kxdpgun -t 20 -Q 100000 -i ~/queries.txt -T -p 8853 192.0.2.1 + +See Also +-------- + +:manpage:`kdig(1)`. |