1PERFDHCP(8) Kea PERFDHCP(8)
2
6 perfdhcp - DHCP benchmarking tool
7
9 perfdhcp [-1] [-4 | -6] [-A encapsulation-level] [-b base] [-B] [-c]
10 [-C separator] [-d drop-time] [-D max-drop] [-e lease-type] [-E
11 time-offset] [-f renew-rate] [-F release-rate] [-g thread-mode] [-h]
12 [-i] [-I ip-offset] [-J remote-address-list-file] [-l local-address|in‐
13 terface] [-L local-port] [-M mac-list-file] [-n num-request] [-N re‐
14 mote-port] [-O random-offset] [-o code,hexstring] [-p test-period] [-P
15 preload] [-r rate] [-R num-clients] [-s seed] [-S srvid-offset] [--sce‐
16 nario name] [-t report] [-T template-file] [-u] [-v] [-W
17 exit-wait-time] [-w script_name] [-x diagnostic-selector] [-X xid-off‐
18 set] [server]
19
21 perfdhcp is a DHCP benchmarking tool. It provides a way to measure the
22 performance of DHCP servers by generating large amounts of traffic from
23 multiple simulated clients. It is able to test both IPv4 and IPv6
24 servers, and provides statistics concerning response times and the num‐
25 ber of requests that are dropped.
26 The tool supports two different scenarios, which offer certain behav‐
28 iors to be tested. By default (the basic scenario), tests are run us‐
29 ing the full four-packet exchange sequence (DORA for DHCPv4, SARR for
30 DHCPv6). An option is provided to run tests using the initial
31 two-packet exchange (DO and SA) instead. It is also possible to config‐
32 ure perfdhcp to send DHCPv6 RENEW and RELEASE messages at a specified
33 rate, in parallel with the DHCPv6 four-way exchanges. By default, if
34 there is no response received with one second, a response is considered
35 lost and perfdhcp continues with other transactions.
36 A second scenario, called avalanche, is selected via --scenario
38 avalanche. It first sends the number of Discovery or Solicit messages
39 specified by the -R option; then a retransmission (with an exponential
40 back-off mechanism) is used for each simulated client, until all re‐
41 quests are answered. It generates a report when all clients receive
42 their addresses, or when it is manually stopped. This scenario attempts
43 to replicate a case where the server is not able to handle the traffic
44 swiftly enough. Real clients will assume the packet or response was
45 lost and will retransmit, further increasing DHCP traffic. This is
46 sometimes called an avalanche effect, thus the scenario name. Option
47 -p is ignored in the avalanche scenario.
48 When running a performance test, perfdhcp exchanges packets with the
50 server under test as quickly as possible, unless the -r parameter is
51 used to limit the request rate. The length of the test can be limited
52 by setting a threshold on any or all of the number of requests made by
53 perfdhcp, the elapsed time, or the number of requests dropped by the
54 server.
55
57 To allow the contents of packets sent to the server to be customized,
58 perfdhcp allows the specification of template files that determine the
59 contents of the packets. For example, the customized packet may contain
60 a DHCPv6 ORO to request a set of options to be returned by the server,
61 or it may contain the Client FQDN option to request that the server
62 perform DNS updates. This may be used to discover performance bottle‐
63 necks for different server configurations (e.g. DDNS enabled or dis‐
64 abled).
65 Up to two template files can be specified on the command line, with
67 each file representing the contents of a particular type of packet, and
68 the type being determined by the test being carried out. For example,
69 if testing DHCPv6:
70 • With no template files specified on the command line, perfdhcp gener‐
72 ates both Solicit and Request packets.
73 • With one template file specified, that file is used as the pattern
75 for Solicit packets: perfdhcp generates the Request packets.
76 • With two template files given on the command line, the first is used
78 as the pattern for Solicit packets, and the second as the pattern for
79 Request packets.
80 (A similar determination applies to DHCPv4's DHCPDISCOVER and DHCPRE‐
82 QUEST packets.)
83 The template file holds the DHCP packet, represented as a stream of
85 ASCII hexadecimal digits; it excludes any IP/UDP stack headers. The
86 template file must not contain any characters other than hexadecimal
87 digits and spaces. Spaces are discarded when the template file is
88 parsed; in the file, 12B4 is the same as 12 B4, which is the same as 1
89 2 B 4.
90 The template files should be used in conjunction with the command-line
92 parameters which specify offsets of the data fields being modified in
93 outbound packets. For example, the -E time-offset switch specifies the
94 offset of the DHCPv6 Elapsed Time option in the packet template. If
95 the offset is specified, perfdhcp injects the current elapsed-time
96 value into this field before sending the packet to the server.
97 In many scenarios, perfdhcp needs to simulate multiple clients, each
99 having a unique client identifier. Since packets for each client are
100 generated from the same template file, it is necessary to randomize the
101 client identifier (or HW address in DHCPv4) in the packet created from
102 it. The -O random-offset option allows specification of the offset in
103 the template where randomization should be performed. It is important
104 to note that this offset points to the end (not the beginning) of the
105 client identifier (or HW address field). The number of bytes being ran‐
106 domized depends on the number of simulated clients. If the number of
107 simulated clients is between 1 and 255, only one byte (to which the
108 randomization offset points) is randomized. If the number of simulated
109 clients is between 256 and 65535, two bytes are randomized. Note that
110 the last two bytes of the client identifier are randomized in this
111 case: the byte which the randomization offset parameter points to, and
112 the one which precedes it (random-offset - 1). If the number of simu‐
113 lated clients exceeds 65535, three bytes are randomized, and so on.
114 perfdhcp can simulate traffic from multiple subnets by enabling option
116 -J and passing a path to a file that contains v4 or v6 addresses to be
117 used as relays in generated messages. That enables testing of vast num‐
118 bers of Kea shared networks. While testing DHCPv4, Kea should be
119 started with the KEA_TEST_SEND_RESPONSES_TO_SOURCE environment vari‐
120 able, to force Kea to send generated messages to the source address of
121 the incoming packet.
122 Templates may currently be used to generate packets being sent to the
124 server in 4-way exchanges, i.e. Solicit, Request (DHCPv6) and DHCPDIS‐
125 COVER, DHCPREQUEST (DHCPv4). They cannot be used when Renew or DHCPRE‐
126 LEASE packets are being sent.
127
129 -1 Takes the server-id option from the first received message.
130 -4 Establishes DHCPv4 operation; this is the default. It is incom‐
132 patible with the -6 option.
133 -6 Establishes DHCPv6 operation. It is incompatible with the -4 op‐
135 tion.
136 -b basetype=value
138 Indicates the base MAC or DUID used to simulate different
139 clients. The basetype may be "mac" or "duid". (The keyword
140 "ether" may alternatively used for MAC.) The -b option can be
141 specified multiple times. The MAC address must consist of six
142 octets separated by single (:) or double (::) colons; for exam‐
143 ple: mac=00:0c:01:02:03:04. The DUID value is a hexadecimal
144 string; it must be at least six octets long and not longer than
145 64 bytes, and the length must be less than 128 hexadecimal dig‐
146 its. For example: duid=0101010101010101010110111F14.
147 -d drop-time
149 Specifies the time after which a request is treated as having
150 been lost. The value is given in seconds and may contain a frac‐
151 tional component. The default is 1.
152 -e lease-type
154 Specifies the type of lease being requested from the server. It
155 may be one of the following:
156 address-only
158 Only regular addresses (v4 or v6) are requested.
159 prefix-only
161 Only IPv6 prefixes are requested.
162 address-and-prefix
164 Both IPv6 addresses and prefixes are requested.
165 The -e prefix-only and -e address-and-prefix forms may not be
167 used with the -4 option.
168 -F release-rate
170 Specifies the rate at which DHCPv4 DHCPRELEASE or DHCPv6 Release
171 requests are sent to a server. This value is only valid when
172 used in conjunction with the exchange rate (given by -r rate).
173 Furthermore, the sum of this value and the renew-rate (given by
174 -f rate) must be equal to or less than the exchange rate value.
175 -f renew-rate
177 Specifies the rate at which DHCPv4 DHCPREQUEST or DHCPv6 Renew
178 requests are sent to a server. This value is only valid when
179 used in conjunction with the exchange rate (given by -r rate).
180 Furthermore, the sum of this value and the release-rate (given
181 by -F rate) must be equal to or less than the exchange rate.
182 -g thread-mode
184 Allows selection of thread-mode, which can be either single or
185 multi. In multi-thread mode, packets are received in a separate
186 thread, which allows better utilisation of CPUs. In a single-CPU
187 system it is better to run in one thread, to avoid threads
188 blocking each other. If more than one CPU is present in the sys‐
189 tem, multi-thread mode is the default; otherwise single-thread
190 is the default.
191 -h Prints help and exits.
193 -i Performs only the initial part of the exchange: DISCOVER-OFFER
195 if -4 is selected, Solicit-Advertise if -6 is chosen.
196 -i is incompatible with the following options: -1, -d, -D, -E,
198 -S, -I and -F. In addition, it cannot be used with multiple in‐
199 stances of -O, -T, and -X.
200 -J remote-address-list-file
202 Specifies a text file that includes multiple addresses, and is
203 designed to test shared networks. If provided, perfdhcp randomly
204 chooses one of the addresses for each exchange, to generate
205 traffic from multiple subnets. When testing DHCPv4, it should be
206 started with the KEA_TEST_SEND_RESPONSES_TO_SOURCE=ENABLE envi‐
207 ronment variable; otherwise, perfdhcp will not be able to re‐
208 ceive responses.
209 -l local-addr|interface
211 For DHCPv4 operation, specifies the local hostname/address to
212 use when communicating with the server. By default, the inter‐
213 face address through which traffic would normally be routed to
214 the server is used. For DHCPv6 operation, specifies the name of
215 the network interface through which exchanges are initiated.
216 -L local-port
218 Specifies the local port to use. This must be zero or a positive
219 integer up to 65535. A value of 0 (the default) allows perfdhcp
220 to choose its own port.
221 -M mac-list-file
223 Specifies a text file containing a list of MAC addresses, one
224 per line. If provided, a MAC address is chosen randomly from
225 this list for every new exchange. In DHCPv6, MAC addresses are
226 used to generate DUID-LLs. This parameter must not be used in
227 conjunction with the -b parameter.
228 -N remote-port
230 Specifies the remote port to use. This must be zero or a posi‐
231 tive integer up to 65535. A value of 0 (the default) allows
232 perfdhcp to choose the standard service port.
233 -o code,hexstring
235 Forces perfdhcp to insert the specified extra option (or options
236 if used several times) into packets being transmitted. The code
237 specifies the option code and the hexstring is a hexadecimal
238 string that defines the content of the option. Care should be
239 taken as perfdhcp does not offer any kind of logic behind those
240 options; they are simply inserted into packets and sent as is.
241 Be careful not to duplicate options that are already inserted.
242 For example, to insert client class identifier (option code 60)
243 with a string "docsis", use "-o 60,646f63736973". The -o may be
244 used multiple times. It is necessary to specify the protocol
245 family (either -4 or -6) before using -o.
246 -P preload
248 Initiates preload exchanges back-to-back at startup. Must be 0
249 (the default) or a positive integer.
250 -r rate
252 Initiates the rate of DORA/SARR (or if -i is given, DO/SA) ex‐
253 changes per second. A periodic report is generated showing the
254 number of exchanges which were not completed, as well as the av‐
255 erage response latency. The program continues until interrupted,
256 at which point a final report is generated.
257 -R num-clients
259 Specifies how many different clients are used. With a value of 1
260 (the default), all requests appear to come from the same client.
261 Must be a positive number.
262 -s seed
264 Specifies the seed for randomization, making runs of perfdhcp
265 repeatable. This must be 0 or a positive integer. The value 0
266 means that a seed is not used; this is the default.
267 --scenario name
269 Specifies the type of scenario, and can be basic (the default)
270 or avalanche.
271 -T template-file
273 Specifies a file containing the template to use as a stream of
274 hexadecimal digits. This may be specified up to two times and
275 controls the contents of the packets sent (see the "Templates"
276 section above).
277 -u Enables checks for address uniqueness. The lease valid-lifetime
279 should not be shorter than the test duration, and clients should
280 not request an address more than once without releasing it.
281 -v Prints the version of this program.
283 -W exit-wait-time
285 Specifies the exit-wait-time parameter, which causes perfdhcp to
286 wait for a certain amount of time after an exit condition has
287 been met, to receive all packets without sending any new pack‐
288 ets. Expressed in microseconds. If not specified, 0 is used
289 (i.e. exit immediately after exit conditions are met).
290 -w script_name
292 Specifies the name of the script to be run before/after perfd‐
293 hcp. When called, the script is passed a single parameter, ei‐
294 ther "start" or "stop", indicating whether it is being called
295 before or after perfdhcp.
296 -x diagnostic-selector
298 Includes extended diagnostics in the output. This is a string of
299 single keywords specifying the operations for which verbose out‐
300 put is desired. The selector key letters are:
301 a Prints the decoded command-line arguments.
303 e Prints the exit reason.
305 i Prints the rate-processing details.
307 l Prints the received leases.
309 s Prints the first server ID.
311 t When finished, prints timers of all successful exchanges.
313 T When finished, prints templates.
315 -y seconds
317 Time in seconds after which perfdhcp starts simulating the
318 client waiting longer for server responses. This increases the
319 secs field in DHCPv4 and sends increased values in the Elapsed
320 Time option in DHCPv6. Must be used with -Y.
321 -Y seconds
323 Time in seconds during which perfdhcp simulates the client wait‐
324 ing longer for server responses. This increases the secs field
325 in DHCPv4 and sends increased values in the Elapsed Time option
326 in DHCPv6. Must be used with -y.
327
329 The following options only apply for DHCPv4 (i.e. when -4 is given).
330 -B Forces broadcast handling.
332
334 The following options only apply for DHCPv6 (i.e. when -6 is given).
335 -c Adds a rapid-commit option (exchanges are Solicit-Advertise).
337 -A encapsulation-level
339 Specifies that relayed traffic must be generated. The argument
340 specifies the level of encapsulation, i.e. how many relay agents
341 are simulated. Currently the only supported encapsulation-level
342 value is 1, which means that the generated traffic is equivalent
343 to the amount of traffic passing through a single relay agent.
344
346 The following options may only be used in conjunction with -T and con‐
347 trol how perfdhcp modifies the template. The options may be specified
348 multiple times on the command line; each occurrence affects the corre‐
349 sponding template file (see "Templates" above).
350 -E time-offset
352 Specifies the offset of the secs field (DHCPv4) or Elapsed Time
353 option (DHCPv6) in the second (i.e. Request) template; must be 0
354 or a positive integer. A value of 0 disables this.
355 -I ip-offset
357 Specifies the offset of the IP address (DHCPv4) in the re‐
358 quested-ip option or IA_NA option (DHCPv6) in the second (Re‐
359 quest) template.
360 -O random-offset
362 Specifies the offset of the last octet to randomize in the tem‐
363 plate. This must be an integer greater than 3. The -T switch
364 must be given to use this option.
365 -S srvid-offset
367 Specifies the offset of the server-id option in the second (Re‐
368 quest) template. This must be a positive integer, and the
369 switch can only be used when the template option (-T) is also
370 given.
371 -X xid-offset
373 Specifies the offset of the transaction ID (xid) in the tem‐
374 plate. This must be a positive integer, and the switch can only
375 be used when the template option (-T) is also given.
376
378 -D max-drop
379 Aborts the test immediately if "max-drop" requests have been
380 dropped. Use -D 0 to abort if even a single request has been
381 dropped. "max-drop" must be a positive integer. If "max-drop"
382 includes the suffix %, it specifies the maximum percentage of
383 requests that may be dropped before aborting. In this case,
384 testing of the threshold begins after 10 requests are expected
385 to have been received.
386 -n num-requests
388 Initiates "num-request" transactions. No report is generated un‐
389 til all transactions have been initiated/waited-for, after which
390 a report is generated and the program terminates.
391 -p test-period
393 Sends requests for "test-period", which is specified in the same
394 manner as -d. This can be used as an alternative to -n, or both
395 options can be given, in which case the testing is completed
396 when either limit is reached.
397 -t interval
399 Sets the delay (in seconds) between two successive reports.
400 -C separator
402 Suppresses the preliminary output and causes the interim data to
403 only contain the values delimited by separator. Used in conjunc‐
404 tion with -t to produce easily parsable reports at -t intervals.
405
407 server Indicates the server to test, specified as an IP address. In the
408 DHCPv6 case, the special name all can be used to refer to
409 All_DHCP_Relay_Agents_and_Servers (the multicast address
410 FF02::1:2), or the special name servers to refer to
411 All_DHCP_Servers (the multicast address FF05::1:3). The server
412 is mandatory except where the -l option is given to specify an
413 interface, in which case it defaults to all.
414
416 perfdhcp can report the following errors in the packet exchange:
417 tooshort
419 A message was received that was too short.
420 orphans
422 A message was received which does not match one sent to the
423 server (i.e. it is a duplicate message, a message that has ar‐
424 rived after an excessive delay, or one that is just not recog‐
425 nized).
426 locallimit
428 Local system limits have been reached when sending a message.
429
431 perfdhcp exits with one of the following status codes:
432 0 Success.
434 1 General error.
436 2 Error in command-line arguments.
438 3 No general failures in operation, but one or more exchanges were
440 unsuccessful.
441
443 Here is an example that simulates regular DHCPv4 traffic of 100 DHCPv4
444 devices (-R 100), 10 packets per second (-r 10), shows the query/re‐
445 sponse rate details (-xi), shows a report every 2 seconds (-t 2), and
446 sends the packets to the IP 192.0.2.1:
447 sudo perfdhcp -xi -t 2 -r 10 -R 100 192.0.2.1
449 Here's a similar case, but for DHCPv6. Note that the DHCPv6 protocol
451 uses link-local addresses, so the interface (eth0 in this example) must
452 be specified on which to send the traffic. all is a convenience alias
453 for All_DHCP_Relay_Agents_and_Servers (the multicast address
454 FF02::1:2). It is also possible to use the servers alias to refer to
455 All_DHCP_Servers (the multicast address FF05::1:3). The default is all.
456 sudo perfdhcp -6 -xi -t 1 -r 1 -R 10 -l eth0 all
458 The following examples simulate normal DHCPv4 and DHCPv6 traffic that,
460 after 3 seconds, starts pretending not to receive any responses from
461 the server for 10 seconds. The DHCPv4 protocol signals this by an in‐
462 creased secs field, while DHCPv6 uses the Elapsed Time option. In real
463 networks, this indicates that clients are not getting responses in a
464 timely matter. This can be used to simulate some HA scenarios, as Kea
465 uses the secs field and Elapsed Time option value as one of the indica‐
466 tors that the HA partner is not responding. When enabled with -y and
467 -Y, the secs and Elapsed Time values increase steadily.
468 sudo perfdhcp -xi -t 1 -r 1 -y 10 -Y 3 192.0.2.1
470 sudo perfdhcp -6 -xi -t 1 -r 1 -y 10 -Y 3 2001:db8::1
472
474 Kea comes with an extensive Kea Administrator Reference Manual that
475 covers all aspects of running the Kea software - compilation, installa‐
476 tion, configuration, configuration examples, and much more. Kea also
477 features a Kea Messages Manual, which lists all possible messages Kea
478 can print with a brief description for each of them. Both documents are
479 available in various formats (.txt, .html, .pdf) with the Kea distribu‐
480 tion. The Kea documentation is available at https://kea.readthedocs.io.
481 Kea source code is documented in the Kea Developer's Guide, available
483 at https://reports.kea.isc.org/dev_guide/.
484 The Kea project website is available at https://kea.isc.org.
486
488 There are two public mailing lists available for the Kea project.
489 kea-users (kea-users at lists.isc.org) is intended for Kea users, while
490 kea-dev (kea-dev at lists.isc.org) is intended for Kea developers,
491 prospective contributors, and other advanced users. Both lists are
492 available at https://lists.isc.org. The community provides best-effort
493 support on both of those lists.
494 ISC provides professional support for Kea services. See
496 https://www.isc.org/kea/ for details.
497
499 The perfdhcp tool was initially coded in October 2011 by John DuBois,
500 Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which included
501 perfdhcp, was released in December 2015.
502
504 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8),
505 kea-admin(8), kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator
506 Reference Manual.
507
509 Internet Systems Consortium
510
512 2019-2022, Internet Systems Consortium
5132.2.0 Jul 27, 2022 PERFDHCP(8)