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 of measuring
22 the performance of DHCP servers by generating large amounts of traffic
23 from simulated multiple 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 scenarios, which offer certain behaviours. By de‐
28 fault (basic scenario) tests are run using the full four-packet ex‐
29 change sequence (DORA for DHCPv4, SARR for DHCPv6). An option is pro‐
30 vided to run tests using the initial two-packet exchange (DO and SA)
31 instead. It is also possible to configure perfdhcp to send DHCPv6 RENEW
32 and RELEASE messages at a specified rate in parallel with the DHCPv6
33 four-way exchanges. By default, if there is no response received with 1
34 second, a response is considered lost and perfdhcp continues with other
35 transactions.
36 Second scenario is called avalanche, which is selected by --scenario
38 avalanche. It first sends as many Discovery or Solicit messages as re‐
39 quest in -R option then a retransmission (with exponential back off
40 mechanism) is used for each simulated client until all requests are an‐
41 swered. It will generate report when all clients get their addresses or
42 when it will be manually stopped. This scenario attempts to replicate a
43 case where the server is not able to handle the traffic swiftly enough.
44 Real clients will assume the packet or the response was lost and will
45 retransmit, further increasing DHCP traffic. This is sometimes called
46 avalanche effect, thus the scenario name. Option -p is ignored in
47 avalanche scenario.
48 When running a performance test, perfdhcp will exchange packets with
50 the server under test as fast 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, each
67 file representing the contents of a particular type of packet, the type
68 being determined by the test being carried out. For example, if testing
69 DHCPv6:
70 • With no template files specified on the command line, perfdhcp will
72 generate both SOLICIT and REQUEST packets.
73 • With one template file specified, that file will be used as the pat‐
75 tern for SOLICIT packets: perfdhcp will generate the REQUEST packets.
76 • With two template files given on the command line, the first will be
78 used as the pattern for SOLICIT packets, the second as the pattern
79 for REQUEST packets.
80 (Similar determination applies to DHCPv4's DISCOVER and REQUEST pack‐
82 ets.)
83 The template file holds the DHCP packet represented as a stream of
85 ASCII hexadecimal digits and 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
89 '1 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 will inject 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) will be randomized. If the number of simu‐
109 lated clients is between 256 and 65535, two bytes will be randomized.
110 Note that the last two bytes of the client identifier will be random‐
111 ized in this case: the byte which the randomization offset parameter
112 points to, and the one which precedes it (random-offset - 1). If the
113 number of simulated clients exceeds 65535, three bytes will be random‐
114 ized, and so on.
115 Perfdhcp can now simulate traffic from multiple subnets by enabling op‐
117 tion -J and passing path to file that contains v4 or v6 addresses that
118 will be used as relay in generated messages. That enable testing of
119 vast numbers of Kea shared networks. While testing Kea v4 it should be
120 started with KEA_TEST_SEND_RESPONSES_TO_SOURCE environment variable to
121 force Kea to send generated messages to source address of incoming
122 packet.
123 Templates may currently be used to generate packets being sent to the
125 server in 4-way exchanges, i.e. SOLICIT, REQUEST (DHCPv6) and DISCOVER,
126 REQUEST (DHCPv4). They cannot be used when RENEW or RELEASE packets are
127 being sent.
128
130 -1 Takes the server-ID option from the first received message.
131 -4 Establishes DHCPv4 operation; this is the default. It is incom‐
133 patible with the -6 option.
134 -6 Establishes DHCPv6 operation. This is incompatible with the -4
136 option.
137 -b basetype=value
139 Indicates the base MAC or DUID used to simulate different
140 clients. The basetype may be "mac" or "duid". (The keyword
141 "ether" may alternatively used for MAC.) The -b option can be
142 specified multiple times. The MAC address must consist of six
143 octets separated by single (:) or double (::) colons, for exam‐
144 ple: mac=00:0c:01:02:03:04. The DUID value is a hexadecimal
145 string; it must be at least six octets long and not longer than
146 64 bytes, and the length must be less than 128 hexadecimal dig‐
147 its, for example: duid=0101010101010101010110111F14.
148 -d drop-time
150 Specifies the time after which a request is treated as having
151 been lost. The value is given in seconds and may contain a frac‐
152 tional component. The default is 1 second.
153 -e lease-type
155 Specifies the type of lease being requested from the server. It
156 may be one of the following:
157 address-only
159 Only regular addresses (v4 or v6) will be requested.
160 prefix-only
162 Only IPv6 prefixes will be requested.
163 address-and-prefix
165 Both IPv6 addresses and prefixes will be requested.
166 The -e prefix-only and -e address-and-prefix forms may not be
168 used with the -4 option.
169 -F release-rate
171 Specifies the rate at which RELEASE requests are sent to a
172 server. This value is only valid when used in conjunction with
173 the exchange rate (given by -r rate). Furthermore, the sum of
174 this value and the renew-rate (given by -f rate) must be equal
175 to or less than the exchange rate value.
176 -f renew-rate
178 Specifies the rate at which DHCPv4 or DHCPv6 renew requests are
179 sent to a server. This value is only valid when used in con‐
180 junction with the exchange rate (given by -r rate). Furthermore,
181 the sum of this value and the release-rate (given by -F rate)
182 must be equal to or less than the exchange rate.
183 -g thread-mode
185 Allows selection of thread-mode, which can be either 'single' or
186 'multi'. In multi-thread mode packets are received in a separate
187 thread, which allows better utilisation of CPUs. In a single-CPU
188 system it is better to run in one thread to avoid threads block‐
189 ing each other. If more than one CPU is present in the system,
190 multi-thread mode is the default; otherwise single-thread is the
191 default.
192 -h Prints help and exits.
194 -i Performs only the initial part of the exchange: DISCOVER-OFFER
196 if -4 is selected, SOLICIT-ADVERTISE if -6 is chosen.
197 -i is incompatible with the following options: -1, -d, -D, -E,
199 -S, -I and -F. In addition, it cannot be used with multiple in‐
200 stances of -O, -T and -X.
201 -J remote-address-list-file
203 Text file that include multiple addresses. If provided perfdhcp
204 will choose randomly one of addresses for each exchange. This is
205 used to generate traffic from multiple subnets. Designed to test
206 shared-networks. While testing kea v4 it should be started with
207 KEA_TEST_SEND_RESPONSES_TO_SOURCE=ENABLE env variable otherwise
208 perfdhcp will not be able to receive 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 will be chosen randomly
225 from this list for every new exchange. In DHCPv6, MAC addresses
226 are used to generate DUID-LLs. This parameter must not be used
227 in 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 seem 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 type of the scenario, can be basic (default) or
270 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 Enable checking address uniqueness. Lease valid lifetime should
279 not be shorter than test duration and clients should not request
280 address more than once without releasing it first.
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 exit-wait-time after an exit condition has been met, to
287 receive all packets without sending any new packets. Expressed
288 in microseconds. If not specified, 0 is used (i.e. exit immedi‐
289 ately 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 will start simulating the
318 client waiting longer for server responses. This increase the
319 secs field in DHCPv4 and sends increased values in Elapsed op‐
320 tion in DHCPv6. Must be used with '-Y'.
321 -Y seconds
323 Period of time in seconds in which perfdhcp will be simulating
324 the client waiting longer for server responses. This increase
325 the secs field in DHCPv4 and sends increased values in Elapsed
326 option 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 will be SOLICIT-ADVER‐
337 TISE).
338 -A encapsulation-level
340 Specifies that relayed traffic must be generated. The argument
341 specifies the level of encapsulation, i.e. how many relay agents
342 are simulated. Currently the only supported encapsulation-level
343 value is 1, which means that the generated traffic is equivalent
344 to the amount of traffic passing through a single relay agent.
345
347 The following options may only be used in conjunction with -T and con‐
348 trol how perfdhcp modifies the template. The options may be specified
349 multiple times on the command line; each occurrence affects the corre‐
350 sponding template file (see "Templates" above).
351 -E time-offset
353 Specifies the offset of the secs field (DHCPv4) or elapsed-time
354 option (DHCPv6) in the second (i.e. REQUEST) template; must be 0
355 or a positive integer. A value of 0 disables this.
356 -I ip-offset
358 Specifies the offset of the IP address (DHCPv4) in the re‐
359 quested-IP option or IA_NA option (DHCPv6) in the second (RE‐
360 QUEST) template.
361 -O random-offset
363 Specifies the offset of the last octet to randomize in the tem‐
364 plate. This must be an integer greater than 3. The -T switch
365 must be given to use this option.
366 -S srvid-offset
368 Specifies the offset of the server-ID option in the second (RE‐
369 QUEST) template. This must be a positive integer, and the
370 switch can only be used when the template option (-T) is also
371 given.
372 -X xid-offset
374 Specifies the offset of the transaction ID (xid) in the tem‐
375 plate. This must be a positive integer, and the switch can only
376 be used when the template option (-T) is also given.
377
379 -D max-drop
380 Aborts the test immediately if max-drop requests have been
381 dropped. Use -D 0 to abort if even a single request has been
382 dropped. max-drop must be a positive integer. If max-drop in‐
383 cludes the suffix '%', it specifies a maximum percentage of re‐
384 quests that may be dropped before abort. In this case, testing
385 of the threshold begins after 10 requests have been expected to
386 be received.
387 -n num-requests
389 Initiates num-request transactions. No report is generated until
390 all transactions have been initiated/waited-for, after which a
391 report is generated and the program terminates.
392 -p test-period
394 Sends requests for test-period, which is specified in the same
395 manner as -d. This can be used as an alternative to -n or both
396 options can be given, in which case the testing is completed
397 when either limit is reached.
398 -t interval
400 Sets the delay (in seconds) between two successive reports.
401 -C separator
403 Output reduced, an argument is a separator for periodic (-t) re‐
404 ports generated in easy parsable mode. Data output won't be
405 changed, remain identical as in -t option.
406
408 server Indicates the server to test, specified as an IP address. In the
409 DHCPv6 case, the special name 'all' can be used to refer to
410 All_DHCP_Relay_Agents_and_Servers (the multicast address
411 FF02::1:2), or the special name 'servers' to refer to
412 All_DHCP_Servers (the multicast address FF05::1:3). The server
413 is mandatory except where the -l option is given to specify an
414 interface, in which case it defaults to 'all'.
415
417 perfdhcp can report the following errors in the packet exchange:
418 tooshort
420 A message was received that was too short.
421 orphans
423 A message was received which does not match one sent to the
424 server (i.e. it is a duplicate message, a message that has ar‐
425 rived after an excessive delay, or one that is just not recog‐
426 nized).
427 locallimit
429 Local system limits have been reached when sending a message.
430
432 perfdhcp can exit with one of the following status codes:
433 0 Success.
435 1 General error.
437 2 Error in command-line arguments.
439 3 No general failures in operation, but one or more exchanges were
441 unsuccessful.
442
444 Simulate regular DHCPv4 traffic: 100 DHCPv4 devices (-R 100), 10 pack‐
445 ets per second (-r 10), show the query/response rate details (-xi), the
446 report should be shown every 2 seconds (-t 2), send the packets to the
447 IP 192.0.2.1:
448 sudo perfdhcp -xi -t 2 -r 10 -R 100 192.0.2.1
450 Here's a similar case, but for DHCPv6. Note that DHCPv6 protocol uses
452 link-local addresses, so you need to specify the interface (eth0 in
453 this example) to send the traffic. 'all' is a convenience alias for
454 All_DHCP_Relay_Agents_and_Servers (the multicast address FF02::1:2).
455 Alternatively, you can use 'servers' alias to refer to All_DHCP_Servers
456 (the multicast address FF05::1:3), or skip it all together and the de‐
457 fault value (all) will be used.
458 sudo perfdhcp -6 -xi -t 1 -r 1 -R 10 -l eth0 all
460 The following examples simulate normal DHCPv4 and DHCPv6 traffic that
462 after 3 seconds starts pretending to not receive any responses from the
463 server for 10 seconds. DHCPv4 protocol signals this by increased secs
464 field and DHCPv6 uses elapsed option for that. In real networks this
465 indicates that the clients are not getting responses in a timely mat‐
466 ter. This can be used to simulate some HA scenarios, as Kea uses secs
467 field and elapsed option value as one of the indicators that the HA
468 partner is not responding. When enabled with -y and -Y, the secs and
469 elapsed time value increased steadily.
470 sudo perfdhcp -xi -t 1 -r 1 -y 10 -Y 3 192.0.2.1
472 sudo perfdhcp -6 -xi -t 1 -r 1 -y 10 -Y 3 2001:db8::1
474
476 There are two public mailing lists available for the Kea project.
477 kea-users (kea-users at lists.isc.org) is intended for Kea users, while
478 kea-dev (kea-dev at lists.isc.org) is intended for Kea developers,
479 prospective contributors, and other advanced users. Both lists are
480 available at https://lists.isc.org. The community provides best-effort
481 support on both of those lists.
482 ISC provides professional support for Kea services. See
484 https://www.isc.org/kea/ for details.
485
487 The perfdhcp tool was initially coded in October 2011 by John DuBois,
488 Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which included
489 perfdhcp, was released in December 2015.
490
492 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8),
493 kea-admin(8), kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator
494 Reference Manual.
495
497 Internet Systems Consortium
498
500 2019-2022, Internet Systems Consortium
5012.0.2 Mar 03, 2022 PERFDHCP(8)