Provided by: kea-admin_2.2.0-1_amd64 bug


       perfdhcp - DHCP benchmarking tool


       perfdhcp  [-1]  [-4  | -6] [-A encapsulation-level] [-b base] [-B] [-c] [-C separator] [-d
       drop-time]  [-D  max-drop]  [-e  lease-type]  [-E   time-offset]   [-f   renew-rate]   [-F
       release-rate]  [-g thread-mode] [-h] [-i] [-I ip-offset] [-J remote-address-list-file] [-l
       local-address|interface]  [-L  local-port]  [-M  mac-list-file]   [-n   num-request]   [-N
       remote-port]  [-O  random-offset]  [-o  code,hexstring]  [-p test-period] [-P preload] [-r
       rate] [-R num-clients] [-s seed] [-S  srvid-offset]  [--scenario  name]  [-t  report]  [-T
       template-file] [-u] [-v] [-W exit-wait-time] [-w script_name] [-x diagnostic-selector] [-X
       xid-offset] [server]


       perfdhcp is a DHCP benchmarking tool. It provides a way to measure the performance of DHCP
       servers by generating large amounts of traffic from multiple simulated clients. It is able
       to test both IPv4 and IPv6 servers, and provides statistics concerning response times  and
       the number of requests that are dropped.

       The tool supports two different scenarios, which offer certain behaviors to be tested.  By
       default (the basic scenario), tests are run using the full four-packet  exchange  sequence
       (DORA  for  DHCPv4, SARR for DHCPv6). An option is provided to run tests using the initial
       two-packet exchange (DO and SA) instead. It is also possible to configure perfdhcp to send
       DHCPv6  RENEW  and  RELEASE  messages  at  a  specified  rate, in parallel with the DHCPv6
       four-way exchanges. By default, if there is  no  response  received  with  one  second,  a
       response is considered lost and perfdhcp continues with other transactions.

       A second scenario, called avalanche, is selected via --scenario avalanche.  It first sends
       the number  of  Discovery  or  Solicit  messages  specified  by  the  -R  option;  then  a
       retransmission (with an exponential back-off mechanism) is used for each simulated client,
       until all requests are answered. It generates a report  when  all  clients  receive  their
       addresses,  or  when  it  is  manually stopped. This scenario attempts to replicate a case
       where the server is not able to handle the  traffic  swiftly  enough.  Real  clients  will
       assume  the  packet  or  response  was  lost  and will retransmit, further increasing DHCP
       traffic. This is sometimes called an avalanche effect, thus the scenario name.  Option  -p
       is ignored in the avalanche scenario.

       When  running a performance test, perfdhcp exchanges packets with the server under test as
       quickly as possible, unless the -r parameter is used to limit the request rate. The length
       of  the test can be limited by setting a threshold on any or all of the number of requests
       made by perfdhcp, the elapsed time, or the number of requests dropped by the server.


       To allow the contents of packets sent to the server to be customized, perfdhcp allows  the
       specification  of  template files that determine the contents of the packets. For example,
       the customized packet may contain a DHCPv6 ORO to request a set of options to be  returned
       by the server, or it may contain the Client FQDN option to request that the server perform
       DNS updates. This may be used to discover performance  bottlenecks  for  different  server
       configurations (e.g. DDNS enabled or disabled).

       Up to two template files can be specified on the command line, with each file representing
       the contents of a particular type of packet, and the type being  determined  by  the  test
       being carried out. For example, if testing DHCPv6:

       • With  no  template  files specified on the command line, perfdhcp generates both Solicit
         and Request packets.

       • With one template file specified, that file is used as the pattern for Solicit  packets:
         perfdhcp generates the Request packets.

       • With  two template files given on the command line, the first is used as the pattern for
         Solicit packets, and the second as the pattern for Request packets.

       (A similar determination applies to DHCPv4's DHCPDISCOVER and DHCPREQUEST packets.)

       The template file holds the DHCP packet, represented as  a  stream  of  ASCII  hexadecimal
       digits;  it  excludes  any  IP/UDP  stack  headers. The template file must not contain any
       characters other than hexadecimal  digits  and  spaces.  Spaces  are  discarded  when  the
       template  file is parsed; in the file, 12B4 is the same as 12 B4, which is the same as 1 2
       B 4.

       The template files should be used in conjunction with the  command-line  parameters  which
       specify offsets of the data fields being modified in outbound packets. For example, the -E
       time-offset switch specifies the offset of the DHCPv6 Elapsed Time option  in  the  packet
       template.   If  the  offset  is specified, perfdhcp injects the current elapsed-time value
       into this field before sending the packet to the server.

       In many scenarios, perfdhcp needs to simulate  multiple  clients,  each  having  a  unique
       client  identifier.  Since  packets  for  each client are generated from the same template
       file, it is necessary to randomize the client identifier (or HW address in DHCPv4) in  the
       packet  created from it. The -O random-offset option allows specification of the offset in
       the template where randomization should be performed. It is important to  note  that  this
       offset  points  to  the  end  (not  the beginning) of the client identifier (or HW address
       field). The number of bytes being randomized depends on the number of  simulated  clients.
       If  the  number  of  simulated  clients  is between 1 and 255, only one byte (to which the
       randomization offset points) is randomized. If the number of simulated clients is  between
       256  and  65535,  two  bytes  are  randomized.  Note that the last two bytes of the client
       identifier are randomized in this case: the byte which the randomization offset  parameter
       points  to,  and the one which precedes it (random-offset - 1). If the number of simulated
       clients exceeds 65535, three bytes are randomized, and so on.

       perfdhcp can simulate traffic from multiple subnets by enabling option -J  and  passing  a
       path  to  a  file  that  contains  v4  or  v6  addresses to be used as relays in generated
       messages. That enables testing of vast numbers  of  Kea  shared  networks.  While  testing
       DHCPv4,  Kea  should  be  started  with  the KEA_TEST_SEND_RESPONSES_TO_SOURCE environment
       variable, to force Kea to send generated messages to the source address  of  the  incoming

       Templates  may  currently  be  used  to generate packets being sent to the server in 4-way
       exchanges, i.e. Solicit, Request (DHCPv6) and  DHCPDISCOVER,  DHCPREQUEST  (DHCPv4).  They
       cannot be used when Renew or DHCPRELEASE packets are being sent.


       -1     Takes the server-id option from the first received message.

       -4     Establishes  DHCPv4  operation; this is the default. It is incompatible with the -6

       -6     Establishes DHCPv6 operation. It is incompatible with the -4 option.

       -b basetype=value
              Indicates the base MAC or DUID used to simulate different clients. The basetype may
              be  "mac"  or  "duid". (The keyword "ether" may alternatively used for MAC.) The -b
              option can be specified multiple times. The MAC address must consist of six  octets
              separated  by single (:) or double (::) colons; for example: mac=00:0c:01:02:03:04.
              The DUID value is a hexadecimal string; it must be at least six octets long and not
              longer  than 64 bytes, and the length must be less than 128 hexadecimal digits. For
              example: duid=0101010101010101010110111F14.

       -d drop-time
              Specifies the time after which a request is treated as having been lost. The  value
              is given in seconds and may contain a fractional component. The default is 1.

       -e lease-type
              Specifies  the  type of lease being requested from the server. It may be one of the

                     Only regular addresses (v4 or v6) are requested.

                     Only IPv6 prefixes are requested.

                     Both IPv6 addresses and prefixes are requested.

              The -e prefix-only and -e address-and-prefix forms may not  be  used  with  the  -4

       -F release-rate
              Specifies  the rate at which DHCPv4 DHCPRELEASE or DHCPv6 Release requests are sent
              to a server. This value is only valid when used in conjunction  with  the  exchange
              rate  (given  by  -r  rate).  Furthermore, the sum of this value and the renew-rate
              (given by -f rate) must be equal to or less than the exchange rate value.

       -f renew-rate
              Specifies the rate at which DHCPv4 DHCPREQUEST or DHCPv6 Renew requests are sent to
              a server.  This value is only valid when used in conjunction with the exchange rate
              (given by -r rate). Furthermore, the sum of this value and the release-rate  (given
              by -F rate) must be equal to or less than the exchange rate.

       -g thread-mode
              Allows  selection  of  thread-mode,  which  can  be  either  single  or  multi.  In
              multi-thread mode, packets are received in a separate thread, which  allows  better
              utilisation  of  CPUs. In a single-CPU system it is better to run in one thread, to
              avoid threads blocking each other. If more than one CPU is present in  the  system,
              multi-thread mode is the default; otherwise single-thread is the default.

       -h     Prints help and exits.

       -i     Performs  only  the initial part of the exchange: DISCOVER-OFFER if -4 is selected,
              Solicit-Advertise if -6 is chosen.

              -i is incompatible with the following options: -1, -d, -D, -E, -S, -I  and  -F.  In
              addition, it cannot be used with multiple instances of -O, -T, and -X.

       -J remote-address-list-file
              Specifies  a  text  file  that includes multiple addresses, and is designed to test
              shared networks. If provided, perfdhcp randomly chooses one of  the  addresses  for
              each  exchange,  to generate traffic from multiple subnets. When testing DHCPv4, it
              should be started  with  the  KEA_TEST_SEND_RESPONSES_TO_SOURCE=ENABLE  environment
              variable; otherwise, perfdhcp will not be able to receive responses.

       -l local-addr|interface
              For   DHCPv4   operation,   specifies   the  local  hostname/address  to  use  when
              communicating with the server. By default,  the  interface  address  through  which
              traffic  would  normally  be  routed  to the server is used.  For DHCPv6 operation,
              specifies the name of the network interface through which exchanges are initiated.

       -L local-port
              Specifies the local port to use. This must be zero or  a  positive  integer  up  to
              65535. A value of 0 (the default) allows perfdhcp to choose its own port.

       -M mac-list-file
              Specifies  a  text  file  containing  a  list  of  MAC  addresses, one per line. If
              provided, a MAC address is chosen randomly from this list for every  new  exchange.
              In  DHCPv6, MAC addresses are used to generate DUID-LLs. This parameter must not be
              used in conjunction with the -b parameter.

       -N remote-port
              Specifies the remote port to use. This must be zero or a  positive  integer  up  to
              65535.  A  value  of 0 (the default) allows perfdhcp to choose the standard service

       -o code,hexstring
              Forces perfdhcp to insert the specified extra option (or options  if  used  several
              times)  into  packets being transmitted. The code specifies the option code and the
              hexstring is a hexadecimal string that defines the  content  of  the  option.  Care
              should  be taken as perfdhcp does not offer any kind of logic behind those options;
              they are simply inserted into packets and sent as is. Be careful not  to  duplicate
              options  that  are already inserted. For example, to insert client class identifier
              (option code 60) with a string "docsis", use "-o 60,646f63736973". The  -o  may  be
              used  multiple  times. It is necessary to specify the protocol family (either -4 or
              -6) before using -o.

       -P preload
              Initiates preload exchanges back-to-back at startup. Must be 0 (the default)  or  a
              positive integer.

       -r rate
              Initiates  the rate of DORA/SARR (or if -i is given, DO/SA) exchanges per second. A
              periodic report is generated  showing  the  number  of  exchanges  which  were  not
              completed,  as  well  as  the average response latency. The program continues until
              interrupted, at which point a final report is generated.

       -R num-clients
              Specifies how many different clients are used. With a value of 1 (the default), all
              requests appear to come from the same client.  Must be a positive number.

       -s seed
              Specifies the seed for randomization, making runs of perfdhcp repeatable. This must
              be 0 or a positive integer. The value 0 means that a seed is not used; this is  the

       --scenario name
              Specifies the type of scenario, and can be basic (the default) or avalanche.

       -T template-file
              Specifies  a file containing the template to use as a stream of hexadecimal digits.
              This may be specified up to two times and controls the contents of the packets sent
              (see the "Templates" section above).

       -u     Enables  checks  for  address  uniqueness.  The  lease valid-lifetime should not be
              shorter than the test duration, and clients should not request an address more than
              once without releasing it.

       -v     Prints the version of this program.

       -W exit-wait-time
              Specifies the exit-wait-time parameter, which causes perfdhcp to wait for a certain
              amount of time after an exit condition has been met, to receive all packets without
              sending  any  new  packets. Expressed in microseconds.  If not specified, 0 is used
              (i.e. exit immediately after exit conditions are met).

       -w script_name
              Specifies the name of the script to be run before/after perfdhcp.  When called, the
              script  is  passed a single parameter, either "start" or "stop", indicating whether
              it is being called before or after perfdhcp.

       -x diagnostic-selector
              Includes extended diagnostics in the output. This is a string  of  single  keywords
              specifying  the  operations  for  which verbose output is desired. The selector key
              letters are:

              a      Prints the decoded command-line arguments.

              e      Prints the exit reason.

              i      Prints the rate-processing details.

              l      Prints the received leases.

              s      Prints the first server ID.

              t      When finished, prints timers of all successful exchanges.

              T      When finished, prints templates.

       -y seconds
              Time in seconds after which perfdhcp starts simulating the  client  waiting  longer
              for  server  responses. This increases the secs field in DHCPv4 and sends increased
              values in the Elapsed Time option in DHCPv6. Must be used with -Y.

       -Y seconds
              Time in seconds during which perfdhcp  simulates  the  client  waiting  longer  for
              server  responses.  This  increases  the  secs  field in DHCPv4 and sends increased
              values in the Elapsed Time option in DHCPv6. Must be used with -y.


       The following options only apply for DHCPv4 (i.e. when -4 is given).

       -B     Forces broadcast handling.


       The following options only apply for DHCPv6 (i.e. when -6 is given).

       -c     Adds a rapid-commit option (exchanges are Solicit-Advertise).

       -A encapsulation-level
              Specifies that relayed traffic must be generated. The argument specifies the  level
              of  encapsulation,  i.e.  how  many  relay agents are simulated. Currently the only
              supported encapsulation-level value is 1, which means that the generated traffic is
              equivalent to the amount of traffic passing through a single relay agent.


       The  following  options  may  only be used in conjunction with -T and control how perfdhcp
       modifies the template. The options may be specified multiple times on  the  command  line;
       each occurrence affects the corresponding template file (see "Templates" above).

       -E time-offset
              Specifies  the offset of the secs field (DHCPv4) or Elapsed Time option (DHCPv6) in
              the second (i.e. Request) template; must be 0 or a positive integer. A value  of  0
              disables this.

       -I ip-offset
              Specifies the offset of the IP address (DHCPv4) in the requested-ip option or IA_NA
              option (DHCPv6) in the second (Request) template.

       -O random-offset
              Specifies the offset of the last octet to randomize in the template. This  must  be
              an integer greater than 3. The -T switch must be given to use this option.

       -S srvid-offset
              Specifies  the  offset  of  the  server-id option in the second (Request) template.
              This must be a positive integer, and the switch can only be used when the  template
              option (-T) is also given.

       -X xid-offset
              Specifies  the  offset  of the transaction ID (xid) in the template. This must be a
              positive integer, and the switch can only be used when the template option (-T)  is
              also given.


       -D max-drop
              Aborts  the test immediately if "max-drop" requests have been dropped.  Use -D 0 to
              abort if even a single request has been dropped.  "max-drop"  must  be  a  positive
              integer.  If  "max-drop" includes the suffix %, it specifies the maximum percentage
              of requests that may be dropped before aborting.  In  this  case,  testing  of  the
              threshold begins after 10 requests are expected to have been received.

       -n num-requests
              Initiates "num-request" transactions. No report is generated until all transactions
              have been initiated/waited-for, after which a report is generated and  the  program

       -p test-period
              Sends requests for "test-period", which is specified in the same manner as -d. This
              can be used as an alternative to -n, or both options can be given,  in  which  case
              the testing is completed when either limit is reached.

       -t interval
              Sets the delay (in seconds) between two successive reports.

       -C separator
              Suppresses  the  preliminary output and causes the interim data to only contain the
              values delimited by separator. Used  in  conjunction  with  -t  to  produce  easily
              parsable reports at -t intervals.


       server Indicates  the  server to test, specified as an IP address. In the DHCPv6 case, the
              special name all can be used to  refer  to  All_DHCP_Relay_Agents_and_Servers  (the
              multicast   address   FF02::1:2),   or   the  special  name  servers  to  refer  to
              All_DHCP_Servers (the multicast address FF05::1:3). The server is mandatory  except
              where  the -l option is given to specify an interface, in which case it defaults to


       perfdhcp can report the following errors in the packet exchange:

              A message was received that was too short.

              A message was received which does not match one sent to the server (i.e.  it  is  a
              duplicate message, a message that has arrived after an excessive delay, or one that
              is just not recognized).

              Local system limits have been reached when sending a message.


       perfdhcp exits with one of the following status codes:

       0      Success.

       1      General error.

       2      Error in command-line arguments.

       3      No general failures in operation, but one or more exchanges were unsuccessful.


       Here is an example that simulates regular DHCPv4 traffic of 100 DHCPv4 devices  (-R  100),
       10 packets per second (-r 10), shows the query/response rate details (-xi), shows a report
       every 2 seconds (-t 2), and sends the packets to the IP

          sudo perfdhcp -xi -t 2 -r 10 -R 100

       Here's a similar case, but for DHCPv6. Note  that  the  DHCPv6  protocol  uses  link-local
       addresses,  so the interface (eth0 in this example) must be specified on which to send the
       traffic. all is a convenience alias for All_DHCP_Relay_Agents_and_Servers  (the  multicast
       address   FF02::1:2).  It  is  also  possible  to  use  the  servers  alias  to  refer  to
       All_DHCP_Servers (the multicast address FF05::1:3). The default is all.

          sudo perfdhcp -6 -xi -t 1 -r 1 -R 10 -l eth0 all

       The following examples simulate normal DHCPv4 and DHCPv6 traffic that,  after  3  seconds,
       starts  pretending not to receive any responses from the server for 10 seconds. The DHCPv4
       protocol signals this by an increased secs field,  while  DHCPv6  uses  the  Elapsed  Time
       option.  In  real  networks,  this  indicates  that clients are not getting responses in a
       timely matter. This can be used to simulate some HA scenarios, as Kea uses the secs  field
       and  Elapsed  Time  option  value  as  one  of  the  indicators that the HA partner is not
       responding. When enabled with -y and  -Y,  the  secs  and  Elapsed  Time  values  increase

          sudo perfdhcp -xi -t 1 -r 1 -y 10 -Y 3

          sudo perfdhcp -6 -xi -t 1 -r 1 -y 10 -Y 3 2001:db8::1


       Kea  comes with an extensive Kea Administrator Reference Manual that covers all aspects of
       running  the  Kea  software  -  compilation,  installation,  configuration,  configuration
       examples, and much more. Kea also features a Kea Messages Manual, which lists all possible
       messages Kea can print with a brief description for  each  of  them.  Both  documents  are
       available  in  various  formats  (.txt,  .html,  .pdf)  with the Kea distribution. The Kea
       documentation is available at

       Kea  source  code  is  documented   in   the   Kea   Developer's   Guide,   available   at

       The Kea project website is available at


       There  are two public mailing lists available for the Kea project. kea-users (kea-users at is intended for Kea users, while  kea-dev  (kea-dev  at  is
       intended  for  Kea  developers,  prospective  contributors, and other advanced users. Both
       lists are available at The community provides  best-effort  support
       on both of those lists.

       ISC  provides  professional  support  for  Kea  services. See for


       The perfdhcp tool was initially coded in October 2011 by John DuBois, Francis Dupont,  and
       Marcin  Siodelski  of  ISC.  Kea  1.0.0, which included perfdhcp, was released in December


       kea-dhcp4(8),    kea-dhcp6(8),    kea-dhcp-ddns(8),    kea-ctrl-agent(8),    kea-admin(8),
       kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator Reference Manual.


       Internet Systems Consortium


       2019-2022, Internet Systems Consortium