From 513a07abc0a06eea6bea417e20b3d4bc3a0d546f Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 4 Mar 2021 19:39:15 +0100 Subject: Adding upstream version 2.4.2+debian. Signed-off-by: Daniel Baumann --- src/dnsperf.1.in | 366 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 src/dnsperf.1.in (limited to 'src/dnsperf.1.in') diff --git a/src/dnsperf.1.in b/src/dnsperf.1.in new file mode 100644 index 0000000..f6def3b --- /dev/null +++ b/src/dnsperf.1.in @@ -0,0 +1,366 @@ +.\" 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 -- cgit v1.2.3