FreeBSD Manual Pages

home | help

KXDPGUN(8) Knot DNS KXDPGUN(8)

NAME
kxdpgun - XDP-powered DNS benchmarking tool

SYNOPSIS
kxdpgun [options] -i filename target

DESCRIPTION
Powerful generator of DNS traffic, sending and receiving packets
through XDP.

Queries are generated according to a textual file which is read sequen-
tially 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.

Parameters
filename
Path to the queries file. See the description below regarding
the file format.

target Either the domain name, IPv4 or IPv6 address of a remote target.

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 be-
low.

-U, --quic[=debug_mode]
Send queries over QUIC. See the list of optional debug modes be-
low.

-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.

-B, --binary
Specify that input file is in binary format. This format is sim-
ilar to the TCP DNS message format. The file contains records
formatted as 2-octet length (network order) followed by a mes-
sage 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 sup-
ported in the QUIC mode).

-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 na-
tive 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 di-
rectory 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.

-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 pe-
riod.

-h, --help
Print the program help.

-V, --version
Print the program version. The option -VV makes the program
print the compile time configuration summary.

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 connec-
tions.

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.

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.

Due to the multi-threaded program structure there are slight discrepan-
cies 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.

EXIT VALUES
Exit status of 0 means successful operation. Any other exit status in-
dicates 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

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages