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] [-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

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       -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
138              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
144              (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
150       -c clients
151              Act as multiple clients.  Requests are sent from multiple  sock‐
152              ets.  The default is to act as 1 client.
153
154       -d datafile
155              Specifies  the  input data file.  If not specified, dnsperf will
156              read from standard input.
157
158       -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
163       -e
164              Enables EDNS0 [RFC2671], by adding an OPT record to all  packets
165              sent.  This option is mutually exclusive with -B.
166
167       -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
173       -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
179       -h
180              Print a usage statement and exit.
181
182       -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
188       -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
193       -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
198       -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
204       -Q max_qps
205              Limits  the  number of requests per second.  There is no default
206              limit.
207
208       -m mode
209              Specifies the transport mode to  use,  "udp",  "tcp",  "dot"  or
210              "doh".  Default is "udp".
211
212       -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
216       -S stats_interval
217              If this parameter is specified, a count of the number of queries
218              per  second  during  the  interval  will  be  printed  out every
219              stats_interval seconds.
220
221       -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
226       -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
232       -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
238       -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
247       -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
252       -x local_port
253              Specifies the local port from which to send requests.   The  de‐
254              fault is the wildcard port (0).
255
256              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
261       -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
269       -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

EXTENDED OPTIONS

275       doh-uri=URI
276              The URI to use for DNS-over-HTTPS, default value is "https://lo
277              calhost/dns-query".
278
279       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
283       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
290              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
298       num-queries-per-conn=NUMBER
299              This will limit the number of queries sent over a connection be‐
300              fore triggering a re-connection. Once re-connected it will reset
301              the  counter  and  continue  sending  queries until the limit is
302              reached again, triggering another re-connection and so on.   Us‐
303              ing  this  option  will also enable counting number of responses
304              received for each connection and once the limit is  reached  for
305              sending  queries it will wait until the same amount of responses
306              has been received before re-connecting.  Waiting  for  responses
307              may  timeout and the timeout used for this is the same as speci‐
308              fied by -t.  Note that this option is only useful for connection
309              oriented protocols.
310

SEE ALSO

312       resperf(1)
313

AUTHOR

315       Nominum, Inc.
316
317       Maintained by DNS-OARC
318
319              https://www.dns-oarc.net/
320

BUGS

322       For issues and feature requests please use:
323
324              https://github.com/DNS-OARC/dnsperf/issues
325
326       For question and help please use:
327
328              admin@dns-oarc.net
329
330dnsperf                             2.10.0                          dnsperf(1)
Impressum