366 lines
10 KiB
Groff
366 lines
10 KiB
Groff
.\" Copyright 2019-2021 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\fB\fR]
|
|
[\fB\-b\ \fIbufsize\fB\fR]
|
|
[\fB\-c\ \fIclients\fB\fR]
|
|
[\fB\-d\ \fIdatafile\fB\fR]
|
|
[\fB\-D\fR]
|
|
[\fB\-e\fR]
|
|
[\fB\-E\ \fIcode:secret\fB\fR]
|
|
[\fB\-f\ \fIfamily\fB\fR]
|
|
[\fB\-h\fR]
|
|
[\fB\-l\ \fIlimit\fB\fR]
|
|
[\fB\-m\ \fImode\fB\fR]
|
|
[\fB\-n\ \fIruns_through_file\fB\fR]
|
|
[\fB\-p\ \fIport\fB\fR]
|
|
[\fB\-q\ \fInum_queries\fB\fR]
|
|
[\fB\-Q\ \fImax_qps\fB\fR]
|
|
[\fB\-s\ \fIserver_addr\fB\fR]
|
|
[\fB\-S\ \fIstats_interval\fB\fR]
|
|
[\fB\-t\ \fItimeout\fB\fR]
|
|
[\fB\-T\ \fIthreads\fB\fR]
|
|
[\fB\-u\fR]
|
|
[\fB\-v\fR]
|
|
[\fB\-x\ \fIlocal_port\fB\fR]
|
|
[\fB\-y\ \fI[alg:]name:secret\fB\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.
|
|
.SH OPTIONS
|
|
|
|
\fB-a \fIlocal_addr\fB\fR
|
|
.br
|
|
.RS
|
|
Specifies the local address from which to send requests. The default is the
|
|
wildcard address.
|
|
.RE
|
|
|
|
\fB-b \fIbufsize\fB\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-c \fIclients\fB\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\fB\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.
|
|
.RE
|
|
|
|
\fB-e\fR
|
|
.br
|
|
.RS
|
|
Enables EDNS0 [RFC2671], by adding an OPT record to all packets sent.
|
|
.RE
|
|
|
|
\fB-E \fIcode:value\fB\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.
|
|
.RE
|
|
|
|
\fB-f \fIfamily\fB\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\fB\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\fB\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\fB\fR
|
|
.br
|
|
.RS
|
|
Sets the port on which the DNS packets are sent. If not specified, the
|
|
standard DNS port (udp/tcp 53, dot/tls 853) is used.
|
|
.RE
|
|
|
|
\fB-q \fInum_queries\fB\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\fB\fR
|
|
.br
|
|
.RS
|
|
Limits the number of requests per second. There is no default limit.
|
|
.RE
|
|
|
|
\fB-m \fImode\fB\fR
|
|
.br
|
|
.RS
|
|
Specifies the transport mode to use, "udp", "tcp" or "dot"/"tls".
|
|
Default is "udp".
|
|
.RE
|
|
|
|
\fB-s \fIserver_addr\fB\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\fB\fR
|
|
.br
|
|
.RS
|
|
If this parameter is specified, a count of the number of queries per second
|
|
during the interval will be printed out every stats_interval seconds.
|
|
.RE
|
|
|
|
\fB-t \fItimeout\fB\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\fB\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.
|
|
.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-x \fIlocal_port\fB\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\fB\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.
|
|
.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
|