1dnsperf(1)                  General Commands Manual                 dnsperf(1)
2
3
4

NAME

6       dnsperf - test the performance of a DNS server
7

SYNOPSIS

9       dnsperf [-a local_addr] [-b bufsize] [-c clients] [-d datafile] [-D]
10       [-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

DESCRIPTION

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
22       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
28   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
33       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
39   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
45       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
55              www.turku.fi A
56              www.helsinki.fi A
57
58       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
63   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
68              example.com
69
70       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
78              require a
79              require a A
80              require a A 1.2.3.4
81              prohibit x
82              prohibit x A
83
84       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
90              add x 3600 A 10.1.2.3
91              delete y A 10.1.2.3
92              delete z A
93              delete w
94
95       Each update message is terminated by a line containing the command:
96
97              send
98
99   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
108   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

OPTIONS

115       -a local_addr
116              Specifies the local address from which to  send  requests.   The
117              default is the wildcard address.
118
119       -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
124       -c clients
125              Act  as multiple clients.  Requests are sent from multiple sock‐
126              ets.  The default is to act as 1 client.
127
128       -d datafile
129              Specifies the input data file.  If not specified,  dnsperf  will
130              read from standard input.
131
132       -D
133              Sets the DO (DNSSEC OK) bit [RFC3225] in all packets sent.  This
134              also enables EDNS0, which is required for DNSSEC.
135
136       -e
137              Enables EDNS0 [RFC2671], by adding an OPT record to all  packets
138              sent.
139
140       -E code:value
141              Add  an  EDNS  [RFC2671]  option  to all packets sent, using the
142              specified numeric option code and value expressed as a a hex-en‐
143              coded string.  This also enables EDNS0.
144
145       -f family
146              Specifies  the address family used for sending DNS packets.  The
147              possible values are "inet", "inet6", or "any".   If  "any"  (the
148              default  value) is specified, dnsperf will use whichever address
149              family is appropriate for the server it is sending packets to.
150
151       -h
152              Print a usage statement and exit.
153
154       -l limit
155              Specifies a time limit for the run, in seconds.  This may  cause
156              the  input  to be read multiple times, or only some of the input
157              to be read.  The default behavior is to read the input once, and
158              have no specific time limit.
159
160       -n runs_through_file
161              Run  through the input file at most this many times.  If no time
162              limit is set, the file will  be  read  exactly  this  number  of
163              times; if a time limit is set, the file may be read fewer times.
164
165       -p port
166              Sets  the port on which the DNS packets are sent.  If not speci‐
167              fied, the standard DNS port (udp/tcp 53, DoT 853,  DoH  443)  is
168              used.
169
170       -q num_queries
171              Sets the maximum number of outstanding requests.  When this val‐
172              ue is reached, dnsperf will not send any more requests until ei‐
173              ther  responses  are received or requests time out.  The default
174              value is 100.
175
176       -Q max_qps
177              Limits the number of requests per second.  There is  no  default
178              limit.
179
180       -m mode
181              Specifies  the  transport  mode  to  use, "udp", "tcp", "dot" or
182              "doh".  Default is "udp".
183
184       -s server_addr
185              Specifies the name or address of the server  to  which  requests
186              will be sent.  The default is the loopback address, 127.0.0.1.
187
188       -S stats_interval
189              If this parameter is specified, a count of the number of queries
190              per second  during  the  interval  will  be  printed  out  every
191              stats_interval seconds.
192
193       -t timeout
194              Specifies  the  request timeout value, in seconds.  dnsperf will
195              no longer wait for a response to a particular request after this
196              many seconds have elapsed.  The default is 5 seconds.
197
198       -T threads
199              Run  multiple  client  threads.   By  default,  dnsperf uses one
200              thread for sending requests and one  thread  for  receiving  re‐
201              sponses.   If this option is specified, dnsperf will instead use
202              N pairs of send/receive threads.
203
204       -u
205              Instructs dnsperf to send DNS dynamic  update  messages,  rather
206              than queries.  The format of the input file is different in this
207              case; see the "Constructing a dynamic update input file" section
208              for more details.
209
210       -v
211              Enables  verbose  mode.   The DNS RCODE of each response will be
212              reported to standard output when the response  is  received,  as
213              will  the  latency.   If  a query times out, it will be reported
214              with the special string "T" instead of a normal DNS RCODE.  If a
215              query  is  interrupted,  it  will  be  reported with the special
216              string "I".  Additional information regarding network  readiness
217              and congestion will also be reported.
218
219       -W
220              Log  warnings  and errors to standard output instead of standard
221              error making it easier for script, test and automation  to  cap‐
222              ture all output.
223
224       -x local_port
225              Specifies  the  local port from which to send requests.  The de‐
226              fault is the wildcard port (0).
227
228              If acting as multiple clients and the  wildcard  port  is  used,
229              each  client  will  use  a  different random port.  If a port is
230              specified, the clients will use a range of ports  starting  with
231              the specified one.
232
233       -y [alg:]name:secret
234              Add a TSIG record [RFC2845] to all packets sent, using the spec‐
235              ified TSIG key algorithm, name and secret, where  the  algorithm
236              defaults  to  hmac-md5  and the secret is expressed as a base-64
237              encoded string.  Available algorithms are: hmac-md5,  hmac-sha1,
238              hmac-sha224, hmac-sha256, hmac-sha384 and hmac-sha512.
239
240       -O option=value
241              Set  an  extended long option for various things to control dif‐
242              ferent aspects of testing or protocol modules, see EXTENDED  OP‐
243              TIONS for list of available options.
244

EXTENDED OPTIONS

246       doh-uri=URI
247              The URI to use for DNS-over-HTTPS, default value is "https://lo
248              calhost/dns-query".
249
250       doh-method=HTTP_METHOD
251              The HTTP method to use when querying  with  DNS-over-HTTPS,  de‐
252              fault is GET.  Available methods are: GET, POST.
253
254       suppress=MESSAGE[,MESSAGE,...]
255              Suppress  various messages and warnings that may be shown exces‐
256              sively in some situations, such as socket  readiness  when  con‐
257              necting to a slow service.  Can suppress multiple types by list‐
258              ing them as a comma separated list.  Following type  are  avail‐
259              able.
260
261              timeouts: Suppress messages about queries being timed out
262              congestion: Suppress messages about network congestion
263              sendfailed:  Suppress  messages about failure to send packets or
264              if only parts of the packet were sent
265              sockready: Suppress messages about socket readiness
266              unexpected: Suppress messages about answers with  an  unexpected
267              message ID
268
269       num-queries-per-conn=NUMBER
270              This will limit the number of queries sent over a connection be‐
271              fore triggering a re-connection. Once re-connected it will reset
272              the  counter  and  continue  sending  queries until the limit is
273              reached again, triggering another re-connection and so on.   Us‐
274              ing  this  option  will also enable counting number of responses
275              received for each connection and once the limit is  reached  for
276              sending  queries it will wait until the same amount of responses
277              has been received before re-connecting.  Waiting  for  responses
278              may  timeout and the timeout used for this is the same as speci‐
279              fied by -t.  Note that this option is only useful for connection
280              oriented protocols.
281

SEE ALSO

283       resperf(1)
284

AUTHOR

286       Nominum, Inc.
287
288       Maintained by DNS-OARC
289
290              https://www.dns-oarc.net/
291

BUGS

293       For issues and feature requests please use:
294
295              https://github.com/DNS-OARC/dnsperf/issues
296
297       For question and help please use:
298
299              admin@dns-oarc.net
300
301dnsperf                              2.9.0                          dnsperf(1)
Impressum