.\" Copyright (C) 2002-2006 Nominum, Inc.
.\"
.\" All rights reserved.
.TH "DNSPERF" "1" "September 7, 2006" "dnsperf" ""
.SH NAME
dnsperf \- test the performance of a DNS server
.SH SYNOPSIS
.sp
\fBdnsperf\fR [ \fB-1\fR ]  [ \fB-A\fR ]  [ \fB-b \fIbufsize\fB\fR ]  [ \fB-c\fR ]  [ \fB-d \fIdatafile\fB\fR ]  [ \fB-D\fR ]  [ \fB-e\fR ]  [ \fB-f \fIfamily\fB\fR ]  [ \fB-h\fR ]  [ \fB-H \fIhistogram_buckets\fB\fR ]  [ \fB-l \fIlimit\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-t \fItimeout\fB\fR ]  [ \fB-T \fIhistogram_seconds\fB\fR ]  [ \fB-u\fR ]  [ \fB-v\fR ]  [ \fB-y \fIname:secret\fB\fR ] 
.SH "DESCRIPTION"
.PP
\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.
.PP
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"
.PP
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.
.PP
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"
.PP
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.
.PP
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
.sp
.nf
                www.turku.fi A
                www.helsinki.fi A
            
.sp
.fi
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"
.PP
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:
.sp
.nf
                example.com
            
.sp
.fi
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.
.sp
.nf
                require a
                require a A
                require a A 1.2.3.4
                prohibit x
                prohibit x A
            
.sp
.fi
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.
.sp
.nf
                add x 3600 A 10.1.2.3
                delete y A 10.1.2.3
                delete z A
                delete w
            
.sp
.fi
Each update message is terminated by a line containing the command:
.sp
.nf
                send
            
.sp
.fi
.SS "RUNNING THE TESTS"
.PP
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 "MEASURING LATENCY"
.PP
When the \fB-H\fR option is specified, the statistics
output will include a histogram (a.k.a. bar chart) showing the
distribution of response latencies. This is intended mainly for
testing caching servers, as the latencies of authoritative servers
typically are negligible compared to network and queueing delays.
.PP
A typical histogram might contain 50 buckets representing latencies
from 0 to 1 second in 20 millisecond increments. To print such a
histogram, pass dnsperf the options
.sp
.nf
                -H 50 -T 1
            
.sp
.fi
If you are interested in responses that arrive several seconds
late, you can get a 10-second histogram using
.sp
.nf
                -H 50 -T 10
            
.sp
.fi
The lengths of the bars in the bar chart are normalized such that
the widest bar is 60 characters wide, to allow the chart to be
displayed in an 80-column window or printed on an 80-column
printer. Responses are classified into successes and failures;
successes are represented by "#" characters and failures by "-" in
the bars. The number of success/failure responses is also printed
next to each bar.
.PP
The average latency is also printed; it takes into account both
successes and failures. Note that requests that got no response at
all will not be included in the latency graph; this may unfairly
skew the average latency in favor of servers that drop requests (or
respond with an error later than the dnsperf timeout) over those
from which an error response is received.
.SH "OPTIONS"
.TP
\fB-1\fR
Run through the input file exactly once. This is the
default if no time limit is set.
.TP
\fB-A\fR
Reports the command line arguments passed
to \fBdnsperf\fR to standard output as
part of the final statistics.
.TP
\fB-b \fIbufsize\fB\fR
Sets the size of the socket's send and receive buffers,
in kilobytes. If not specified, the default value is 32k.
.TP
\fB-c\fR
Prints a count of the number of responses with each
DNS RCODE as part of the final statistics.
.TP
\fB-d \fIdatafile\fB\fR
Specifies the input data file. If not specified,
\fBdnsperf\fR will read from standard input.
.TP
\fB-D\fR
Sets the DNSSEC OK bit in all packets sent. This also
enables EDNS 0, which is required for DNSSEC.
.TP
\fB-e\fR
Enables EDNS 0, by adding an OPT record to all packets
sent.
.TP
\fB-f \fIfamily\fB\fR
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.
.TP
\fB-h\fR
Print a usage statement and exit.
.TP
\fB-H \fIhistogram_buckets\fB\fR
When specified, \fBdnsperf\fR will print a
histogram showing response latency after completing the
run; the histogram will contain this many buckets.
.TP
\fB-l \fIlimit\fB\fR
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.
.TP
\fB-p \fIport\fB\fR
Sets the port on which the DNS packets are sent. If not
specified, the standard DNS port (53) is used.
.TP
\fB-q \fInum_queries\fB\fR
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 20.
.TP
\fB-Q \fImax_qps\fB\fR
Limits the number of requests per second. There is no
default limit.
.TP
\fB-s \fIserver_addr\fB\fR
Specifies the name or address of the server to which
requests will be sent. The default is the loopback
address, 127.0.0.1.
.TP
\fB-t \fItimeout\fB\fR
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.
.TP
\fB-T \fIhistogram_seconds\fB\fR
When specified, \fBdnsperf\fR will print a
histogram showing response latency after completing the
run; the histogram will include latencies up to this
number of seconds. This should be used with the
\fB-H\fR option.
.TP
\fB-u\fR
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.
.TP
\fB-v\fR
Enables verbose mode. The DNS RCODE of each response will
be reported to standard output when the response is
received.
.TP
\fB-y \fIname:secret\fB\fR
Add a TSIG record to all packets sent, using the specified
TSIG key name and secret, where the secret is expressed as
a base-64 encoded string.
.SH "AUTHOR"
.PP
Nominum, Inc.
.SH "SEE ALSO"
.PP
\fBresperf\fR(1)