1dnsperf(1) General Commands Manual dnsperf(1)
2
6 dnsperf - test the performance of a DNS server
7
9 dnsperf [-a local_addr] [-b bufsize] [-B] [-c clients] [-d datafile]
10 [-D] [-e] [-E code:secret] [-f family] [-h] [-l limit] [-m mode]
11 [-n runs_through_file] [-p port] [-q num_queries] [-Q max_qps]
12 [-s server_addr] [-S stats_interval] [-t timeout] [-T threads] [-u]
13 [-v] [-W] [-x local_port] [-y [alg:]name:secret] [-O option=value]
14
16 dnsperf is a DNS server performance testing tool. It is primarily in‐
17 tended for measuring the performance of authoritative DNS servers, but
18 it can also be used for measuring caching server performance in a
19 closed laboratory environment. For testing caching servers resolving
20 against the live Internet, the resperf program is preferred.
21 It is recommended that dnsperf and the name server under test be run on
23 separate machines, so that the CPU usage of dnsperf itself does not
24 slow down the name server. The two machines should be connected with a
25 fast network, preferably a dedicated Gigabit Ethernet segment. Testing
26 through a router or firewall is not advisable.
27 Configuring the name server
29 If using dnsperf to test an authoritative server, the name server under
30 test should be set up to serve one or more zones similar in size and
31 number to what the server is expected to serve in production.
32 Also, be sure to turn off recursion in the server's configuration (in
34 BIND 8/9, specify "recursion no;" in the options block). In BIND 8,
35 you should also specify "fetch-glue no;"; otherwise the server may at‐
36 tempt to retrieve glue information from the Internet during the test,
37 slowing it down by an unpredictable factor.
38 Constructing a query input file
40 A dnsperf input file should contain a large and realistic set of
41 queries, on the order of ten thousand to a million. The input file
42 contains one line per query, consisting of a domain name and an RR type
43 name separated by a space. The class of the query is implicitly IN.
44 When measuring the performance serving non-terminal zones such as the
46 root zone or TLDs, note that such servers spend most of their time pro‐
47 viding referral responses, not authoritative answers. Therefore, a re‐
48 alistic input file might consist mostly of queries for type A for names
49 *below*, not at, the delegations present in the zone. For example,
50 when testing the performance of a server configured to be authoritative
51 for the top-level domain "fi.", which contains delegations for domains
52 like "helsinki.fi" and "turku.fi", the input file could contain lines
53 like
54 www.turku.fi A
56 www.helsinki.fi A
57 where the "www" prefix ensures that the server will respond with a re‐
59 ferral. Ideally, a realistic proportion of queries for nonexistent do‐
60 mains should be mixed in with those for existing ones, and the lines of
61 the input file should be in a random order.
62 Constructing a dynamic update input file
64 To test dynamic update performance, dnsperf is run with the -u option,
65 and the input file is constructed of blocks of lines describing dynamic
66 update messages. The first line in a block contains the zone name:
67 example.com
69 Subsequent lines contain prerequisites, if there are any. Prerequi‐
71 sites can specify that a name may or may not exist, an rrset may or may
72 not exist, or an rrset exists and its rdata matches all specified rdata
73 for that name and type. The keywords "require" and "prohibit" are fol‐
74 lowed by the appropriate information. All relative names are consid‐
75 ered to be relative to the zone name. The following lines show the 5
76 types of prerequisites.
77 require a
79 require a A
80 require a A 1.2.3.4
81 prohibit x
82 prohibit x A
83 Subsequent lines contain records to be added, records to be deleted,
85 rrsets to be deleted, or names to be deleted. The keywords "add" or
86 "delete" are followed by the appropriate information. All relative
87 names are considered to be relative to the zone name. The following
88 lines show the 4 types of updates.
89 add x 3600 A 10.1.2.3
91 delete y A 10.1.2.3
92 delete z A
93 delete w
94 Each update message is terminated by a line containing the command:
96 send
98 Running the tests
100 When running dnsperf, a data file (the -d option) and server (the -s
101 option) will normally be specified. The output of dnsperf is mostly
102 self-explanatory. Pay attention to the number of dropped packets re‐
103 ported - when running the test over a local Ethernet connection, it
104 should be zero. If one or more packets has been dropped, there may be
105 a problem with the network connection. In that case, the results
106 should be considered suspect and the test repeated.
107 Using DNS-over-HTTPS
109 When using DNS-over-HTTPS you must set the -O doh-uri=... to something
110 that works with the server you're sending to. Also note that the value
111 for maximum outstanding queries will be used to control the maximum
112 concurrent streams within the HTTP/2 connection.
113
115 -a local_addr
116 Specifies the local address from which to send requests. The
117 default is the wildcard address.
118 -b bufsize
120 Sets the size of the socket's send and receive buffers, in kilo‐
121 bytes. If not specified, the operating system's default is
122 used.
123 -B
125 Instructs dnsperf to read datafile in TCP-stream binary format
126 as specified by RFC 1035 section "4.2.2. TCP usage". Each pack‐
127 et is preceded by 2-byte preambule which specifies length of the
128 following DNS packet in network byte order, immediatelly fol‐
129 lowed by raw bytes of the packet. First two bytes of any packet
130 should contain message ID and are overwritten by dnsperf on the
131 fly. All other bytes are left intact. Packets shorter than two
132 bytes are sent intact. Packets in datafile can contain arbi‐
133 trary bytes and are not checked for validity. Malformed packets
134 probably will not be responded to by servers and will cause
135 timeouts. This option is mutually exclusive with -D, -e, -E, -u
136 and -y.
137 These binary datafiles can be generated using arbitrary TCP lis‐
139 teners such as netcat (nc) and sockat. TCP must be used so that
140 the length is prepended. Following example shows how to gener‐
141 ate a datafile with two query and then using it, you need two
142 terminals.
143 (terminal 1) $ nc -l 127.0.0.1 5300 > dns.blob
145 (terminal 2) $ echo "example.com A" | dnsperf -s 127.0.0.1 -p 5300 -m tcp
146 (terminal 1) $ nc -l 127.0.0.1 5300 >> dns.blob
147 (terminal 2) $ echo "example.com AAAA" | dnsperf -s 127.0.0.1 -p 5300 -m tcp
148 (terminal 1) $ dnsperf -B -d dns.blob -s $IP
149 -c clients
151 Act as multiple clients. Requests are sent from multiple sock‐
152 ets. The default is to act as 1 client.
153 -d datafile
155 Specifies the input data file. If not specified, dnsperf will
156 read from standard input.
157 -D
159 Sets the DO (DNSSEC OK) bit [RFC3225] in all packets sent. This
160 also enables EDNS0, which is required for DNSSEC. This option
161 is mutually exclusive with -B.
162 -e
164 Enables EDNS0 [RFC2671], by adding an OPT record to all packets
165 sent. This option is mutually exclusive with -B.
166 -E code:value
168 Add an EDNS [RFC2671] option to all packets sent, using the
169 specified numeric option code and value expressed as a a hex-en‐
170 coded string. This also enables EDNS0. This option is mutually
171 exclusive with -B.
172 -f family
174 Specifies the address family used for sending DNS packets. The
175 possible values are "inet", "inet6", or "any". If "any" (the
176 default value) is specified, dnsperf will use whichever address
177 family is appropriate for the server it is sending packets to.
178 -h
180 Print a usage statement and exit.
181 -l limit
183 Specifies a time limit for the run, in seconds. This may cause
184 the input to be read multiple times, or only some of the input
185 to be read. The default behavior is to read the input once, and
186 have no specific time limit.
187 -n runs_through_file
189 Run through the input file at most this many times. If no time
190 limit is set, the file will be read exactly this number of
191 times; if a time limit is set, the file may be read fewer times.
192 -p port
194 Sets the port on which the DNS packets are sent. If not speci‐
195 fied, the standard DNS port (udp/tcp 53, DoT 853, DoH 443) is
196 used.
197 -q num_queries
199 Sets the maximum number of outstanding requests. When this
200 value is reached, dnsperf will not send any more requests until
201 either responses are received or requests time out. The default
202 value is 100.
203 -Q max_qps
205 Limits the number of requests per second. There is no default
206 limit.
207 -m mode
209 Specifies the transport mode to use, "udp", "tcp", "dot" or
210 "doh". Default is "udp".
211 -s server_addr
213 Specifies the name or address of the server to which requests
214 will be sent. The default is the loopback address, 127.0.0.1.
215 -S stats_interval
217 If this parameter is specified, a count of the number of answers
218 received per second during the interval will be printed out ev‐
219 ery stats_interval seconds.
220 -t timeout
222 Specifies the request timeout value, in seconds. dnsperf will
223 no longer wait for a response to a particular request after this
224 many seconds have elapsed. The default is 5 seconds.
225 -T threads
227 Run multiple client threads. By default, dnsperf uses one
228 thread for sending requests and one thread for receiving re‐
229 sponses. If this option is specified, dnsperf will instead use
230 N pairs of send/receive threads.
231 -u
233 Instructs dnsperf to send DNS dynamic update messages, rather
234 than queries. The format of the input file is different in this
235 case; see the "Constructing a dynamic update input file" section
236 for more details. This option is mutually exclusive with -B.
237 -v
239 Enables verbose mode. The DNS RCODE of each response will be
240 reported to standard output when the response is received, as
241 will the latency. If a query times out, it will be reported
242 with the special string "T" instead of a normal DNS RCODE. If a
243 query is interrupted, it will be reported with the special
244 string "I". Additional information regarding network readiness
245 and congestion will also be reported.
246 -W
248 Log warnings and errors to standard output instead of standard
249 error making it easier for script, test and automation to cap‐
250 ture all output.
251 -x local_port
253 Specifies the local port from which to send requests. The de‐
254 fault is the wildcard port (0).
255 If acting as multiple clients and the wildcard port is used,
257 each client will use a different random port. If a port is
258 specified, the clients will use a range of ports starting with
259 the specified one.
260 -y [alg:]name:secret
262 Add a TSIG record [RFC2845] to all packets sent, using the spec‐
263 ified TSIG key algorithm, name and secret, where the algorithm
264 defaults to hmac-md5 and the secret is expressed as a base-64
265 encoded string. Available algorithms are: hmac-md5, hmac-sha1,
266 hmac-sha224, hmac-sha256, hmac-sha384 and hmac-sha512. This op‐
267 tion is mutually exclusive with -B.
268 -O option=value
270 Set an extended long option for various things to control dif‐
271 ferent aspects of testing or protocol modules, see EXTENDED OP‐
272 TIONS for list of available options.
273
275 doh-uri=URI
276 The URI to use for DNS-over-HTTPS, default value is "https://lo‐
277 calhost/dns-query".
278 doh-method=HTTP_METHOD
280 The HTTP method to use when querying with DNS-over-HTTPS, de‐
281 fault is GET. Available methods are: GET, POST.
282 suppress=MESSAGE[,MESSAGE,...]
284 Suppress various messages and warnings that may be shown exces‐
285 sively in some situations, such as socket readiness when con‐
286 necting to a slow service. Can suppress multiple types by list‐
287 ing them as a comma separated list. Following type are avail‐
288 able.
289 timeouts: Suppress messages about queries being timed out
291 congestion: Suppress messages about network congestion
292 sendfailed: Suppress messages about failure to send packets or
293 if only parts of the packet were sent
294 sockready: Suppress messages about socket readiness
295 unexpected: Suppress messages about answers with an unexpected
296 message ID
297 num-queries-per-conn=NUMBER
298 This will limit the number of queries sent over a connection be‐
299 fore triggering a re-connection. Once re-connected it will reset
300 the counter and continue sending queries until the limit is
301 reached again, triggering another re-connection and so on. Us‐
302 ing this option will also enable counting number of responses
303 received for each connection and once the limit is reached for
304 sending queries it will wait until the same amount of responses
305 has been received before re-connecting. Waiting for responses
306 may timeout and the timeout used for this is the same as speci‐
307 fied by -t. Note that this option is only useful for connection
308 oriented protocols.
309 verbose-interval-stats
311 Change the statistics format of -S to that shown at end of run.
312 Please note: Min/max values for latency and connections are not
314 available in interval statistics. Number of answers received
315 within stats_interval can legitimately exceed number of queries
316 sent, depending on answer latency, configured timeout, and
317 stats_interval.
318 Only available in dnsperf.
320 latency-histogram
322 Print detailed latency histograms for DNS answers and connec‐
323 tions. Latency is quantized into bins with roughly 3 % resolu‐
324 tion, and latency range for individual bins increases logarith‐
325 mically. This is done to to limit amount of memory required for
326 histograms and also allows to visualize latency using logarith‐
327 mic percentile histograms with minimal postprocessing.
328 Only available in dnsperf and if compile time support was de‐
330 tected.
331 qps-threshold-wait=<microseconds>
333 When using -Q to rate limit queries sent, this option control
334 the minimum time (in microseconds) there should be between
335 queries to use nanosleep() to wait until sending the next query.
336 Setting to zero (0) will disable any call to nanosleep() between
337 sending queries.
338 If the time between queries is lower then this, then no wait is
340 performed in order to have more precision on when to send the
341 next query. This is because during high QPS rate limiting it
342 can take more time just calling the functions to wait for when
343 to send the next query then the actually time between queries.
344 If not set, the average call-time to nanosleep() will be mea‐
346 sured during startup.
347 Only available in dnsperf.
349
351 resperf(1)
352
354 Nominum, Inc.
355 Maintained by DNS-OARC
357 https://www.dns-oarc.net/
359
361 For issues and feature requests please use:
362 https://github.com/DNS-OARC/dnsperf/issues
364 For question and help please use:
366 admin@dns-oarc.net
368dnsperf 2.12.0 dnsperf(1)