home | help
dnsperf(1)		     General Commands Manual		      dnsperf(1)

NAME
     dnsperf - test the performance of a DNS server

SYNOPSIS
     dnsperf [-a local_addr] [-b bufsize] [-B] [-c clients] [-d datafile] [-D]
     [-e] [-E code:secret] [-f family] [-h] [-l limit] [-m mode]
     [-n runs_through_file] [-p port] [-q num_queries] [-Q max_qps]
     [-s server_addr] [-S stats_interval] [-t timeout] [-T threads] [-u] [-v]
     [-W] [-x local_port] [-y [alg:]name:secret] [-O option=value]

DESCRIPTION
     dnsperf 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 en-
     vironment.   For  testing caching servers resolving against the live Inter-
     net, the resperf program is preferred.

     It is recommended that dnsperf and the name server under  test  be  run  on
     separate  machines,  so  that the CPU usage of dnsperf 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.

   Configuring the name server
     If using dnsperf 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.

   Constructing a query input file
     A dnsperf 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 re-
     ferral 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 perfor-
     mance 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

	    www.turku.fi A
	    www.helsinki.fi A

     where the "www" prefix ensures that the server will respond with  a  refer-
     ral.   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.

   Constructing a dynamic update input file
     To test dynamic update performance, dnsperf is run with the -u 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:

	    example.com

     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 ex-
     ist, 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.

	    require a
	    require a A
	    require a A 1.2.3.4
	    prohibit x
	    prohibit x A

     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.

	    add x 3600 A 10.1.2.3
	    delete y A 10.1.2.3
	    delete z A
	    delete w

     Each update message is terminated by a line containing the command:

	    send

   Running the tests
     When  running  dnsperf,  a data file (the -d option) and server (the -s op-
     tion) will normally be specified.	The output of dnsperf is mostly self-ex-
     planatory.  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  net-
     work  connection.	 In  that case, the results should be considered suspect
     and the test repeated.

   Using DNS-over-HTTPS
     When using DNS-over-HTTPS you must set the -O doh-uri=... to something that
     works with the server you're sending to.  Also note that the value for max-
     imum outstanding queries will be used to  control	the  maximum  concurrent
     streams within the HTTP/2 connection.

OPTIONS
     -a local_addr
	    Specifies  the  local  address from which to send requests.  The de-
	    fault is the wildcard address.

     -b bufsize
	    Sets the size of the socket's send and  receive  buffers,  in  kilo-
	    bytes.  If not specified, the operating system's default is used.

     -B
	    Instructs  dnsperf	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 dnsperf on the fly. All other bytes are
	    left intact.  Packets shorter than two bytes are sent intact.  Pack-
	    ets 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 -D, -e, -E, -u and -y.

	    These  binary datafiles can be generated using arbitrary TCP listen-
	    ers such as netcat (nc) and sockat.  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.

	    (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
	    (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
	    (terminal 1) $ dnsperf -B -d dns.blob -s $IP

     -c clients
	    Act as multiple clients.  Requests are sent from  multiple	sockets.
	    The default is to act as 1 client.

     -d datafile
	    Specifies  the input data file.  If not specified, dnsperf will read
	    from standard input.

     -D
	    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 -B.

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

     -E code:value
	    Add  an  EDNS [RFC2671] option to all packets sent, using the speci-
	    fied numeric option code and value	expressed  as  a  a  hex-encoded
	    string.  This also enables EDNS0.  This option is mutually exclusive
	    with -B.

     -f family
	    Specifies the address family used for sending DNS packets.	The pos-
	    sible  values  are "inet", "inet6", or "any".  If "any" (the default
	    value) is specified, dnsperf will use whichever  address  family  is
	    appropriate for the server it is sending packets to.

     -h
	    Print a usage statement and exit.

     -l limit
	    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.

     -n runs_through_file
	    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.

     -p port
	    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.

     -q num_queries
	    Sets the maximum number of outstanding requests.  When this value is
	    reached, dnsperf will not send any more requests  until  either  re-
	    sponses  are  received  or	requests time out.  The default value is
	    100.

     -Q max_qps
	    Limits the number of requests  per	second.   There  is  no  default
	    limit.

     -m mode
	    Specifies  the  transport mode to use, "udp", "tcp", "dot" or "doh".
	    Default is "udp".

     -s server_addr
	    Specifies the name or address of the server to which  requests  will
	    be sent.  The default is the loopback address, 127.0.0.1.

     -S stats_interval
	    If this parameter is specified, a count of the number of answers re-
	    ceived  per  second  during  the  interval will be printed out every
	    stats_interval seconds.

     -t timeout
	    Specifies the request timeout value, in seconds.   dnsperf	will  no
	    longer  wait  for a response to a particular request after this many
	    seconds have elapsed.  The default is 5 seconds.

     -T threads
	    Run multiple client threads.  By default, dnsperf  uses  one  thread
	    for  sending  requests  and  one thread for receiving responses.  If
	    this option is specified,  dnsperf	will  instead  use  N  pairs  of
	    send/receive threads.

     -u
	    Instructs  dnsperf	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 -B.

     -v
	    Enables verbose mode.  The DNS RCODE of each response  will  be  re-
	    ported 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 inter-
	    rupted, it will be reported with the special string "I".  Additional
	    information regarding network readiness and congestion will also  be
	    reported.

     -W
	    Log warnings and errors to standard output instead of standard error
	    making it easier for script, test and automation to capture all out-
	    put.

     -x local_port
	    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.

     -y [alg:]name:secret
	    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 exclu-
	    sive with -B.

     -O option=value
	    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.

EXTENDED OPTIONS
     doh-uri=URI
	    The  URI to use for DNS-over-HTTPS, default value is "https://local-
	    host/dns-query".

     doh-method=HTTP_METHOD
	    The HTTP method to use when querying with DNS-over-HTTPS, default is
	    GET.  Available methods are: GET, POST.

     tls-sni=SERVER_NAME
	    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 ex-
	    tension in the client hello.

     suppress=MESSAGE[,MESSAGE,...]
	    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.

	    timeouts: Suppress messages about queries being timed out
	    congestion: Suppress messages about network congestion
	    sendfailed: Suppress messages about failure to send  packets  or  if
	    only parts of the packet were sent
	    sockready: Suppress messages about socket readiness
	    unexpected:  Suppress messages about answers with an unexpected mes-
	    sage ID
     num-queries-per-conn=NUMBER
	    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 op-
	    tion 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 -t.	Note that this option is
	    only useful for connection oriented protocols.

     verbose-interval-stats
	    Change the statistics format of -S to that shown at end of run.

	    Please note: Min/max values for  latency  and  connections	are  not
	    available in interval statistics.  Number of answers received within
	    stats_interval  can  legitimately exceed number of queries sent, de-
	    pending on answer latency, configured timeout, and stats_interval.

	    Only available in dnsperf.

     latency-histogram
	    Print detailed latency histograms for DNS answers  and  connections.
	    Latency  is quantized into bins with roughly 3 % resolution, and la-
	    tency 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 percentileA histograms
	    with minimal postprocessing.

	    Only available in dnsperf and if compile time support was detected.

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

	    If the time between queries is lower then this, then no wait is per-
	    formed 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 nanosleep() will be measured
	    during startup.

	    Only available in dnsperf.

SEE ALSO
     resperf(1)

AUTHOR
     Nominum, Inc.

     Maintained by DNS-OARC

	    https://www.dns-oarc.net/

BUGS
     For issues and feature requests please use:

	    https://github.com/DNS-OARC/dnsperf/issues

     For question and help please use:

	    admin@dns-oarc.net

dnsperf 			     2.14.0			      dnsperf(1)

home | help