summaryrefslogtreecommitdiffstats
path: root/doc/man/kxdpgun.8in
blob: 243f4f4ac8fcd54a20a5fefb7fe18269c946b765 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
.\" 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 \fItarget_IP\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
\fIfilename\fP
Path to the queries file. See the description below regarding the file format.
.TP
\fItarget_IP\fP
The IPv4 or IPv6 address of remote destination.
.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\-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\-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.
.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.
.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 \(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–2024, CZ.NIC, z.s.p.o.
.\" Generated by docutils manpage writer.
.