KXDPGUN(8)

📦
version 3.5.10 · 15 versions
, in fedora 44, nixos 26.05

💖 KXDPGUN 💖 — the XDP-powered DNS benchmarking tool (it's in section 8, system admin stuff, iykyk)

okay bestie, so kxdpgun is from Knot DNS and it is literally the XDP-powered DNS benchmarking tool. she does not play around. 🦋

✨ SYNOPSIS ✨

kxdpgun [options] -i filename target

🎀 DESCRIPTION 🎀

Bestie. She is a powerful generator of DNS traffic, sending and receiving packets through XDP. Like, packets go brrr through the kernel and she is thriving. 🔥

Queries get generated according to a textual file, and that file is read sequentially in a loop until a configured duration elapses. Important though: the order of queries is not guaranteed. And responses are received (unless you disable that, diva behavior) and counted, but they're not checked against queries. So she counts, she does not verify. Not her job. 💅

The number of parallel threads gets autodetected according to the number of queues configured for the network interface. she's self-aware like that.

🌸 Parameters 🌸

  • filename — the path to the queries file. There's a whole description below about the file format, keep scrolling babe.
  • target — either the domain name, IPv4 or IPv6 address of a remote target.

💜 Options 💜

  • -t, --duration seconds — how long the traffic generation lasts, given as a decimal number in seconds (default is 5.0).
  • -T, --tcp[=debug_mode] — send queries over TCP. the optional debug modes are listed below, go look. 👀
  • -U, --quic[=debug_mode] — send queries over QUIC. again, debug modes are listed below.
  • -Q, --qps queries — number of queries-per-second (approximately, no cap) to be sent (default is 1000). Heads up though: 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). So don't come at her with tiny numbers and expect perfection. 😭
  • -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. trade-off queen. ✨
  • -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.
  • -B, --binary — specify that input file is in binary format. This format is similar to the TCP DNS message format. The file contains records formatted as 2-octet length (network order) followed by a message in DNS wire format.
  • -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, sorry babes).
  • -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.
  • -e, --edns-size size — EDNS UDP payload size, range 512-4096 (default is 1232). Note that over XDP the maximum supported MTU is 1790.
  • -m, --mode mode — set the XDP mode. Supported values are:
    • auto (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.
    • copy – 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.
    • generic – the generic XDP implementation is forced even if native implementation is available. This mode doesn't require support from the driver nor hardware, but offers the worst performance.
  • -G, --qlog path — generate qlog files in the directory specified by path. The directory has to exist. This option is ignored if not in the QUIC mode. The recommended usage is with --quic=R or with low QPS. Otherwise, too many files are generated. like, an unhinged amount of files.
  • -j, --json — print statistics formatted as json.
  • -S, --stats-period period — report statistics automatically every period milliseconds. These reports contain only metrics collected in the given period.
  • -h, --help — print the program help.
  • -V, --version — print the program version. And the option -VV makes the program print the compile time configuration summary. double V double the info, iconic. 👑

🦋 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.
  • 9 — operate normally except for not ACKing the final FIN+ACK (TCP only).
  • R — instead of opening a connection for each query, reuse connections.

⭐ Signals ⭐

Sending USR1 signal to a running process triggers current statistics dump to the standard output. In combination with -S may cause erratic printout timing. so, like, be aware. 😭

🌸 NOTES 🌸

  • Linux kernel 4.18+ is required. no old kernels allowed bestie.
  • 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.
  • For proper operation of QUIC mode on a multi-queue Mellanox/NVIDIA network card, it may be necessary to set ethtool -X <dev> xfrm none.
  • 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. she's honest about her flaws, we love that. 🫶

🔥 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 💜

kdig(1). that's the one girl. go read her too.

🎀 AUTHOR 🎀

CZ.NIC, z.s.p.o. and contributors <https://www.knot-dns.cz/>

Copyright (C) CZ.NIC, z.s.p.o. and contributors

k that's the whole thing bestie, version 3.5.10, dated 2026-10-21, and it's a KXDPGUN(8) page — go forth and benchmark, you absolute main character. 💖✨🦋

📦 where this page comes from