dnsperf/src/dnsperf.1.in

.\" Copyright 2019-2023 OARC, Inc.
.\" Copyright 2017-2018 Akamai Technologies
.\" Copyright 2006-2016 Nominum, Inc.
.\" All rights reserved.
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License");
.\" you may not use this file except in compliance with the License.
.\" You may obtain a copy of the License at
.\"
.\"     http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.TH dnsperf 1 "@PACKAGE_VERSION@" "dnsperf"
.SH NAME
dnsperf \- test the performance of a DNS server
.SH SYNOPSIS
.hy 0
.ad l
\fBdnsperf\fR\ [\fB\-a\ \fIlocal_addr\fR]
[\fB\-b\ \fIbufsize\fR]
[\fB\-B\fR]
[\fB\-c\ \fIclients\fR]
[\fB\-d\ \fIdatafile\fR]
[\fB\-D\fR]
[\fB\-e\fR]
[\fB\-E\ \fIcode:secret\fR]
[\fB\-f\ \fIfamily\fR]
[\fB\-h\fR]
[\fB\-l\ \fIlimit\fR]
[\fB\-m\ \fImode\fR]
[\fB\-n\ \fIruns_through_file\fR]
[\fB\-p\ \fIport\fR]
[\fB\-q\ \fInum_queries\fR]
[\fB\-Q\ \fImax_qps\fR]
[\fB\-s\ \fIserver_addr\fR]
[\fB\-S\ \fIstats_interval\fR]
[\fB\-t\ \fItimeout\fR]
[\fB\-T\ \fIthreads\fR]
[\fB\-u\fR]
[\fB\-v\fR]
[\fB\-W\fR]
[\fB\-x\ \fIlocal_port\fR]
[\fB\-y\ \fI[alg:]name:secret\fR]
[\fB\-O\ \fIoption=value\fR]
.ad
.hy
.SH DESCRIPTION
\fBdnsperf\fR is a DNS server performance testing tool.
It is primarily intended for measuring the performance of authoritative DNS
servers, but it can also be used for measuring caching server performance in
a closed laboratory environment.
For testing caching servers resolving against the live Internet, the
\fBresperf\fR program is preferred.

It is recommended that \fBdnsperf\fR and the name server under test be run
on separate machines, so that the CPU usage of \fBdnsperf\fR itself does not
slow down the name server.
The two machines should be connected with a fast network, preferably a
dedicated Gigabit Ethernet segment.
Testing through a router or firewall is not advisable.
.SS "Configuring the name server"
If using \fBdnsperf\fR to test an authoritative server, the name server
under test should be set up to serve one or more zones similar in size and
number to what the server is expected to serve in production.

Also, be sure to turn off recursion in the server's configuration (in BIND
8/9, specify "recursion no;" in the options block).
In BIND 8, you should also specify "fetch-glue no;"; otherwise the server
may attempt to retrieve glue information from the Internet during the test,
slowing it down by an unpredictable factor.
.SS "Constructing a query input file"
A \fBdnsperf\fR input file should contain a large and realistic set of
queries, on the order of ten thousand to a million.
The input file contains one line per query, consisting of a domain name and
an RR type name separated by a space.
The class of the query is implicitly IN.

When measuring the performance serving non-terminal zones such as the root
zone or TLDs, note that such servers spend most of their time providing
referral responses, not authoritative answers.
Therefore, a realistic input file might consist mostly of queries for type
A for names *below*, not at, the delegations present in the zone.
For example, when testing the performance of a server configured to be
authoritative for the top-level domain "fi.", which contains delegations
for domains like "helsinki.fi" and "turku.fi", the input file could contain
lines like
.RS
.hy 0

.nf
www.turku.fi A
www.helsinki.fi A
.fi
.hy
.RE

where the "www" prefix ensures that the server will respond with a referral.
Ideally, a realistic proportion of queries for nonexistent domains should be
mixed in with those for existing ones, and the lines of the input file
should be in a random order.
.SS "Constructing a dynamic update input file"
To test dynamic update performance, \fBdnsperf\fR is run with the \fB\-u\fR
option, and the input file is constructed of blocks of lines describing
dynamic update messages.
The first line in a block contains the zone name:
.RS
.hy 0

.nf
example.com
.fi
.hy
.RE

Subsequent lines contain prerequisites, if there are any.
Prerequisites can specify that a name may or may not exist, an rrset may or
may not exist, or an rrset exists and its rdata matches all specified rdata
for that name and type.
The keywords "require" and "prohibit" are followed by the appropriate
information.
All relative names are considered to be relative to the zone name.
The following lines show the 5 types of prerequisites.
.RS
.hy 0

.nf
require a
require a A
require a A 1.2.3.4
prohibit x
prohibit x A
.fi
.hy
.RE

Subsequent lines contain records to be added, records to be deleted, rrsets
to be deleted, or names to be deleted.
The keywords "add" or "delete" are followed by the appropriate information.
All relative names are considered to be relative to the zone name.
The following lines show the 4 types of updates.
.RS
.hy 0

.nf
add x 3600 A 10.1.2.3
delete y A 10.1.2.3
delete z A
delete w
.fi
.hy
.RE

Each update message is terminated by a line containing the command:
.RS
.hy 0

.nf
send
.fi
.hy
.RE
.SS "Running the tests"
When running \fBdnsperf\fR, a data file (the \fB\-d\fR option) and server
(the \fB\-s\fR option) will normally be specified.
The output of dnsperf is mostly self-explanatory.
Pay attention to the number of dropped packets reported - when running the
test over a local Ethernet connection, it should be zero.
If one or more packets has been dropped, there may be a problem with the
network connection.
In that case, the results should be considered suspect and the test repeated.
.SS "Using DNS-over-HTTPS"
When using DNS-over-HTTPS you must set the \fB-O doh\-uri=...\fR to something
that works with the server you're sending to.
Also note that the value for maximum outstanding queries will be used to
control the maximum concurrent streams within the HTTP/2 connection.
.SH OPTIONS

\fB-a \fIlocal_addr\fR
.br
.RS
Specifies the local address from which to send requests.
The default is the wildcard address.
.RE

\fB-b \fIbufsize\fR
.br
.RS
Sets the size of the socket's send and receive buffers, in kilobytes.
If not specified, the operating system's default is used.
.RE

\fB-B\fR
.br
.RS
Instructs \fBdnsperf\fR to read datafile in TCP-stream binary format
as specified by RFC 1035 section "4.2.2. TCP usage".
Each packet is preceded by 2-byte preambule which specifies length of
the following DNS packet in network byte order, immediatelly followed
by raw bytes of the packet.
First two bytes of any packet should contain message ID and are
overwritten by \fBdnsperf\fR on the fly. All other bytes are left
intact.
Packets shorter than two bytes are sent intact.
Packets in datafile can contain arbitrary bytes and are not checked for
validity.
Malformed packets probably will not be responded to by servers and will
cause timeouts.
This option is mutually exclusive with \fB-D\fR, \fB-e\fR, \fB-E\fR,
\fB-u\fR and \fB-y\fR.

These binary datafiles can be generated using arbitrary TCP listeners such
as \fBnetcat\fR (nc) and \fBsockat\fR.
TCP must be used so that the length is prepended.
Following example shows how to generate a datafile with two query and
then using it, you need two terminals.

.EX
(terminal 1) $ nc -l 127.0.0.1 5300 > dns.blob
(terminal 2) $ echo "example.com A" | dnsperf -s 127.0.0.1 -p 5300 -m tcp
...wait for dnsperf to finish...
(terminal 1) $ nc -l 127.0.0.1 5300 >> dns.blob
(terminal 2) $ echo "example.com AAAA" | dnsperf -s 127.0.0.1 -p 5300 -m tcp
...wait for dnsperf to finish...
(terminal 1) $ dnsperf -B -d dns.blob -s $IP
.EE
.RE

\fB-c \fIclients\fR
.br
.RS
Act as multiple clients.
Requests are sent from multiple sockets.
The default is to act as 1 client.
.RE

\fB-d \fIdatafile\fR
.br
.RS
Specifies the input data file.
If not specified, \fBdnsperf\fR will read from standard input.
.RE

\fB-D\fR
.br
.RS
Sets the DO (DNSSEC OK) bit [RFC3225] in all packets sent.
This also enables EDNS0, which is required for DNSSEC.
This option is mutually exclusive with \fB-B\fR.
.RE

\fB-e\fR
.br
.RS
Enables EDNS0 [RFC2671], by adding an OPT record to all packets sent.
This option is mutually exclusive with \fB-B\fR.
.RE

\fB-E \fIcode:value\fR
.br
.RS
Add an EDNS [RFC2671] option to all packets sent, using the specified
numeric option code and value expressed as a a hex-encoded string.
This also enables EDNS0.
This option is mutually exclusive with \fB-B\fR.
.RE

\fB-f \fIfamily\fR
.br
.RS
Specifies the address family used for sending DNS packets.
The possible values are "inet", "inet6", or "any".
If "any" (the default value) is specified, \fBdnsperf\fR will use whichever
address family is appropriate for the server it is sending packets to.
.RE

\fB-h\fR
.br
.RS
Print a usage statement and exit.
.RE

\fB-l \fIlimit\fR
.br
.RS
Specifies a time limit for the run, in seconds.
This may cause the input to be read multiple times, or only some of the
input to be read.
The default behavior is to read the input once, and have no specific time
limit.
.RE

\fB-n \fIruns_through_file\fR
.br
.RS
Run through the input file at most this many times.
If no time limit is set, the file will be read exactly this number of
times; if a time limit is set, the file may be read fewer times.
.RE

\fB-p \fIport\fR
.br
.RS
Sets the port on which the DNS packets are sent.
If not specified, the standard DNS port (udp/tcp 53, DoT 853, DoH 443) is used.
.RE

\fB-q \fInum_queries\fR
.br
.RS
Sets the maximum number of outstanding requests.
When this value is reached, \fBdnsperf\fR will not send any more requests
until either responses are received or requests time out.
The default value is 100.
.RE

\fB-Q \fImax_qps\fR
.br
.RS
Limits the number of requests per second.
There is no default limit.
.RE

\fB-m \fImode\fR
.br
.RS
Specifies the transport mode to use, "udp", "tcp", "dot" or "doh".
Default is "udp".
.RE

\fB-s \fIserver_addr\fR
.br
.RS
Specifies the name or address of the server to which requests will be sent.
The default is the loopback address, 127.0.0.1.
.RE

\fB-S \fIstats_interval\fR
.br
.RS
If this parameter is specified, a count of the number of answers received
per second during the interval will be printed out every \fIstats_interval\fR
seconds.
.RE

\fB-t \fItimeout\fR
.br
.RS
Specifies the request timeout value, in seconds.
\fBdnsperf\fR will no longer wait for a response to a particular request
after this many seconds have elapsed.
The default is 5 seconds.
.RE

\fB-T \fIthreads\fR
.br
.RS
Run multiple client threads.
By default, \fBdnsperf\fR uses one thread for sending requests and one
thread for receiving responses.
If this option is specified, \fBdnsperf\fR will instead use N pairs of
send/receive threads.
.RE

\fB-u\fR
.br
.RS
Instructs \fBdnsperf\fR to send DNS dynamic update messages, rather than
queries.
The format of the input file is different in this case; see the
"Constructing a dynamic update input file" section for more details.
This option is mutually exclusive with \fB-B\fR.
.RE

\fB-v\fR
.br
.RS
Enables verbose mode.
The DNS RCODE of each response will be reported to standard output when
the response is received, as will the latency.
If a query times out, it will be reported with the special string "T"
instead of a normal DNS RCODE.
If a query is interrupted, it will be reported with the special string "I".
Additional information regarding network readiness and congestion will
also be reported.
.RE

\fB-W\fR
.br
.RS
Log warnings and errors to standard output instead of standard error making
it easier for script, test and automation to capture all output.
.RE

\fB-x \fIlocal_port\fR
.br
.RS
Specifies the local port from which to send requests.
The default is the wildcard port (0).

If acting as multiple clients and the wildcard port is used, each client
will use a different random port.
If a port is specified, the clients will use a range of ports starting with
the specified one.
.RE

\fB-y \fI[alg:]name:secret\fR
.br
.RS
Add a TSIG record [RFC2845] to all packets sent, using the specified TSIG
key algorithm, name and secret, where the algorithm defaults to hmac-md5 and
the secret is expressed as a base-64 encoded string.
Available algorithms are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256,
hmac-sha384 and hmac-sha512.
This option is mutually exclusive with \fB-B\fR.
.RE

\fB-O \fIoption=value\fR
.br
.RS
Set an extended long option for various things to control different aspects
of testing or protocol modules, see EXTENDED OPTIONS for list of available
options.
.RE
.SH "EXTENDED OPTIONS"

\fBdoh-uri=\fIURI\fR
.br
.RS
The URI to use for DNS-over-HTTPS, default value is
"https://localhost/dns-query".
.RE

\fBdoh-method=\fIHTTP_METHOD\fR
.br
.RS
The HTTP method to use when querying with DNS-over-HTTPS, default is GET.
Available methods are: GET, POST.
.RE

\fBtls-sni=\fISERVER_NAME\fR
.br
.RS
The Server Name Indication (SNI) to use for TLS connections (such as DNS-over-TLS or DNS-over-HTTPS),
defaults to leaving out the SNI extension in the client hello.
.RE

\fBsuppress=\fIMESSAGE[,MESSAGE,...]\fR
.br
.RS
Suppress various messages and warnings that may be shown excessively in some
situations, such as socket readiness when connecting to a slow service.
Can suppress multiple types by listing them as a comma separated list.
Following type are available.

\fBtimeouts\fR: Suppress messages about queries being timed out
.br
\fBcongestion\fR: Suppress messages about network congestion
.br
\fBsendfailed\fR: Suppress messages about failure to send packets or if only parts of the packet were sent
.br
\fBsockready\fR: Suppress messages about socket readiness
.br
\fBunexpected\fR: Suppress messages about answers with an unexpected message ID
.RE
\fBnum-queries-per-conn=\fINUMBER\fR
.br
.RS
This will limit the number of queries sent over a connection before
triggering a re-connection. Once re-connected it will reset the counter and
continue sending queries until the limit is reached again, triggering
another re-connection and so on.
Using this option will also enable counting number of responses received
for each connection and once the limit is reached for sending queries it
will wait until the same amount of responses has been received before
re-connecting.
Waiting for responses may timeout and the timeout used for this is the
same as specified by \fB-t\fR.
Note that this option is only useful for connection oriented protocols.
.RE

\fBverbose-interval-stats\fR
.br
.RS
Change the statistics format of \fB-S\fR to that shown at end of run.

\fIPlease note\fR: Min/max values for latency and connections are not
available in interval statistics.
Number of answers received within \fIstats_interval\fR can legitimately
exceed number of queries sent, depending on answer latency, configured
\fItimeout\fR, and \fIstats_interval\fR.

Only available in \fBdnsperf\fR.
.RE

\fBlatency-histogram\fR
.br
.RS
Print detailed latency histograms for DNS answers and connections.
Latency is quantized into bins with roughly 3 % resolution, and latency
range for individual bins increases logarithmically.
This is done to to limit amount of memory required for histograms
and also allows to visualize latency using logarithmic percentile histograms
with minimal postprocessing.

Only available in \fBdnsperf\fR and if compile time support was detected.
.RE

\fBqps-threshold-wait=<microseconds>\fR
.br
.RS
When using \fB-Q\fR to rate limit queries sent, this option control the
minimum time (in microseconds) there should be between queries to use
\fInanosleep()\fR to wait until sending the next query.
Setting to zero (0) will disable any call to \fInanosleep()\fR between
sending queries.

If the time between queries is lower then this, then no wait is performed
in order to have more precision on when to send the next query.
This is because during high QPS rate limiting it can take more time just
calling the functions to wait for when to send the next query then the
actually time between queries.

If not set, the average call-time to \fInanosleep()\fR will be measured
during startup.

Only available in \fBdnsperf\fR.
.RE
.SH "SEE ALSO"
\fBresperf\fR(1)
.SH AUTHOR
Nominum, Inc.
.LP
Maintained by DNS-OARC
.LP
.RS
.I https://www.dns-oarc.net/
.RE
.LP
.SH BUGS
For issues and feature requests please use:
.LP
.RS
\fI@PACKAGE_URL@\fP
.RE
.LP
For question and help please use:
.LP
.RS
\fI@PACKAGE_BUGREPORT@\fP
.RE
.LP