kxdpgun(8)

1KXDPGUN(8)                         Knot DNS                         KXDPGUN(8)
2
3
4

NAME

6       kxdpgun - XDP-powered DNS benchmarking tool
7

SYNOPSIS

9       kxdpgun [options] -i filename targetIP
10

DESCRIPTION

12       Powerful  generator  of  DNS  traffic,  sending  and  receiving packets
13       through XDP.
14
15       Queries are generated according to a textual file which is read sequen‐
16       tially  in  a  loop  until  a configured duration elapses. The order of
17       queries is not guaranteed. Responses are received (unless disabled) and
18       counted, but not checked against queries.
19
20       The  number of parallel threads is autodetected according to the number
21       of queues configured for the network interface.
22
23   Options
24       -t, --duration seconds
25              Duration of traffic generation, specified as a decimal number in
26              seconds (default is 5.0).
27
28       -T, --tcp[=debug_mode]
29              Send  queries over TCP. See the list of optional debug modes be‐
30              low.
31
32       -U, --quic[=debug_mode]
33              Send queries over QUIC. See the list of optional debug modes be‐
34              low.
35
36       -Q, --qps queries
37              Number of queries-per-second (approximately) to be sent (default
38              is 1000).  The program is not optimized for low speeds at  which
39              it may lose communication packets. The recommended minimum speed
40              is 2 packets per thread (Rx/Tx queue).
41
42       -b, --batch size
43              Send more queries in a batch. Improves QPS but  may  affect  the
44              counterpart's  packet  loss  (default  is  10  for UDP and 1 for
45              TCP/QUIC).
46
47       -r, --drop
48              Drop incoming responses. Improves  QPS,  but  disables  response
49              statistics.
50
51       -p, --port number
52              Remote  destination  port  (default  is  53 for UDP/TCP, 853 for
53              QUIC).
54
55       -F, --affinity cpu_spec
56              CPU  affinity  for  all  threads   specified   in   the   format
57              [<cpu_start>][s<cpu_step>],  where <cpu_start> is the CPU ID for
58              the first thread and <cpu_step> is the CPU ID increment for next
59              thread (default is 0s1).
60
61       -i, --infile filename
62              Path to a file with query templates.
63
64       -I, --interface interface
65              Network interface for outgoing communication. This can be useful
66              in situations when the interfaces are in a bond for example.
67
68       -l, --local localIP[/prefix]
69              Override the auto-detected source  IP  address.  If  an  address
70              range  is  specified instead, various IPs from the range will be
71              used for different queries uniformly  (address  range  not  sup‐
72              ported in the QUIC mode).
73
74       targetIP
75              The IPv4 or IPv6 address of remote destination.
76
77       -L, --mac-local
78              Override auto-detected local MAC address.
79
80       -R, --mac-remote
81              Override auto-detected remote MAC address.
82
83       -v, --vlan id
84              Add VLAN 802.1Q header with the given id. VLAN offloading should
85              be disabled.
86
87       -h, --help
88              Print the program help.
89
90       -V, --version
91              Print the program version.
92
93   Queries file format
94       Each line describes a query in the form:
95
96       query_name query_type [flags]
97
98       Where query_name is a domain name to be queried, query_type is a record
99       type name, and flags is a single character:
100
101       E Send query with EDNS.
102
103       D Request DNSSEC (EDNS + DO flag).
104
105   TCP/QUIC debug modes
106       0      Perform full handshake for all connections (QUIC only).
107
108       1      Just send SYN (Initial) and receive SYN-ACK (Handshake).
109
110       2      Perform  TCP/QUIC handshake and don't send anything, allow close
111              initiated by counterpart.
112
113       3      Perform TCP/QUIC handshake and don't react further.
114
115       5      Send incomplete query (N-1 bytes) and don't react further.
116
117       7      Send query and don't ACK the response or anything further.
118
119       8      Don't close the connection and ignore close by counterpart  (TCP
120              only).
121
122       9      Operate  normally  except  for not ACKing the final FIN+ACK (TCP
123              only).
124
125   Signals
126       Sending USR1 signal to a running process  triggers  current  statistics
127       dump to the standard output.
128

NOTES

130       Linux kernel 4.18+ is required.
131
132       The  utility  has to be executed under root or with these capabilities:
133       CAP_NET_RAW,   CAP_NET_ADMIN,    CAP_SYS_ADMIN,    CAP_IPC_LOCK,    and
134       CAP_SYS_RESOURCE (Linux < 5.11).
135
136       The utility allocates source UDP/TCP ports from the range 2000-65535.
137

EXIT VALUES

139       Exit  status of 0 means successful operation. Any other exit status in‐
140       dicates an error.
141

EXAMPLES

143       Manually created queries file:
144
145          abc6.example.com. AAAA
146          nxdomain.example.com. A
147          notzone. A
148          a.example.com. NS E
149          ab.example.com. A D
150          abcd.example.com. DS D
151
152       Queries file generated from a zone file (Knot DNS format):
153
154          cat ZONE_FILE | awk "{print \$1,\$3}" | grep -E "(NS|DS|A|AAAA|PTR|MX|SOA)$" | sort -u -R > queries.txt
155
156       Basic usage:
157
158          # kxdpgun -i ~/queries.txt 2001:DB8::1
159
160       Using UDP with increased batch size:
161
162          # kxdpgun -t 20 -Q 1000000 -i ~/queries.txt -b 20 -p 8853 192.0.2.1
163
164       Using TCP:
165
166          # kxdpgun -t 20 -Q 100000 -i ~/queries.txt -T -p 8853 192.0.2.1
167

AUTHOR

172       CZ.NIC Labs <https://www.knot-dns.cz>
173

COPYRIGHT

175       Copyright 2010–2022, CZ.NIC, z.s.p.o.
176
177
178
179
1803.2.4                             2022-12-12                        KXDPGUN(8)