299 lines
8.5 KiB
Groff
299 lines
8.5 KiB
Groff
.\" 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" "2025-04-10" "3.4.6" "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 formatted 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–2025, CZ.NIC, z.s.p.o.
|
||
.\" Generated by docutils manpage writer.
|
||
.
|