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 relayin generated messages. That enable testing of vast
119 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 renew-rate
171 Specifies the rate at which DHCPv4 or DHCPv6 renew requests are
172 sent to a server. This value is only valid when used in con‐
173 junction with the exchange rate (given by -r rate). Furthermore,
174 the sum of this value and the release-rate (given by -F rate)
175 must be equal to or less than the exchange rate.
176 -g thread-mode
178 Allows selection of thread-mode, which can be either 'single' or
179 'multi'. In multi-thread mode packets are received in a separate
180 thread, which allows better utilisation of CPUs. In a single-CPU
181 system it is better to run in one thread to avoid threads block‐
182 ing each other. If more than one CPU is present in the system,
183 multi-thread mode is the default; otherwise single-thread is the
184 default.
185 -h Prints help and exits.
187 -i Performs only the initial part of the exchange: DISCOVER-OFFER
189 if -4 is selected, SOLICIT-ADVERTISE if -6 is chosen.
190 -i is incompatible with the following options: -1, -d, -D, -E,
192 -S, -I and -F. In addition, it cannot be used with multiple in‐
193 stances of -O, -T and -X.
194 -J remote-address-list-file
196 Text file that include multiple addresses. If provided perfdhcp
197 will choose randomly one of addresses for each exchange. This is
198 used to generate traffic from multiple subnets. Designed to test
199 shared-networks. While testing kea v4 it should be started with
200 KEA_TEST_SEND_RESPONSES_TO_SOURCE=ENABLE env variable otherwise
201 perfdhcp will not be able to receive responses.
202 -l local-addr|interface
204 For DHCPv4 operation, specifies the local hostname/address to
205 use when communicating with the server. By default, the inter‐
206 face address through which traffic would normally be routed to
207 the server is used. For DHCPv6 operation, specifies the name of
208 the network interface through which exchanges are initiated.
209 -L local-port
211 Specifies the local port to use. This must be zero or a positive
212 integer up to 65535. A value of 0 (the default) allows perfdhcp
213 to choose its own port.
214 -M mac-list-file
216 Specifies a text file containing a list of MAC addresses, one
217 per line. If provided, a MAC address will be chosen randomly
218 from this list for every new exchange. In DHCPv6, MAC addresses
219 are used to generate DUID-LLs. This parameter must not be used
220 in conjunction with the -b parameter.
221 -N remote-port
223 Specifies the remote port to use. This must be zero or a posi‐
224 tive integer up to 65535. A value of 0 (the default) allows
225 perfdhcp to choose the standard service port.
226 -o code,hexstring
228 Forces perfdhcp to insert the specified extra option (or options
229 if used several times) into packets being transmitted. The code
230 specifies the option code and the hexstring is a hexadecimal
231 string that defines the content of the option. Care should be
232 taken as perfdhcp does not offer any kind of logic behind those
233 options; they are simply inserted into packets and sent as is.
234 Be careful not to duplicate options that are already inserted.
235 For example, to insert client class identifier (option code 60)
236 with a string 'docsis', use -o 60,646f63736973. The -o may be
237 used multiple times. It is necessary to specify the protocol
238 family (either -4 or -6) before using -o.
239 -P preload
241 Initiates preload exchanges back-to-back at startup. Must be 0
242 (the default) or a positive integer.
243 -r rate
245 Initiates the rate of DORA/SARR (or if -i is given, DO/SA) ex‐
246 changes per second. A periodic report is generated showing the
247 number of exchanges which were not completed, as well as the av‐
248 erage response latency. The program continues until interrupted,
249 at which point a final report is generated.
250 -R num-clients
252 Specifies how many different clients are used. With a value of 1
253 (the default), all requests seem to come from the same client.
254 Must be a positive number.
255 -s seed
257 Specifies the seed for randomization, making runs of perfdhcp
258 repeatable. This must be 0 or a positive integer. The value 0
259 means that a seed is not used; this is the default.
260 --scenario name
262 Specifies type of the scenario, can be basic (default) or
263 avalanche.
264 -T template-file
266 Specifies a file containing the template to use as a stream of
267 hexadecimal digits. This may be specified up to two times and
268 controls the contents of the packets sent (see the "Templates"
269 section above).
270 -u Enable checking address uniqueness. Lease valid lifetime should
272 not be shorter than test duration and clients should not request
273 address more than once without releasing it first.
274 -v Prints the version of this program.
276 -W exit-wait-time
278 Specifies the exit-wait-time parameter, which causes perfdhcp to
279 wait for exit-wait-time after an exit condition has been met, to
280 receive all packets without sending any new packets. Expressed
281 in microseconds. If not specified, 0 is used (i.e. exit immedi‐
282 ately after exit conditions are met).
283 -w script_name
285 Specifies the name of the script to be run before/after perfd‐
286 hcp. When called, the script is passed a single parameter, ei‐
287 ther "start" or "stop", indicating whether it is being called
288 before or after perfdhcp.
289 -x diagnostic-selector
291 Includes extended diagnostics in the output. This is a string of
292 single keywords specifying the operations for which verbose out‐
293 put is desired. The selector key letters are:
294 a Prints the decoded command line arguments.
296 e Prints the exit reason.
298 i Prints the rate processing details.
300 s Prints the first server-ID.
302 t When finished, prints timers of all successful exchanges.
304 T When finished, prints templates.
306 -y seconds
308 Time in seconds after which perfdhcp will start simulating the
309 client waiting longer for server responses. This increase the
310 secs field in DHCPv4 and sends increased values in Elapsed op‐
311 tion in DHCPv6. Must be used with '-Y'.
312 -Y seconds
314 Period of time in seconds in which perfdhcp will be simulating
315 the client waiting longer for server responses. This increase
316 the secs field in DHCPv4 and sends increased values in Elapsed
317 option in DHCPv6. Must be used with '-y'.
318
320 The following options only apply for DHCPv4 (i.e. when -4 is given).
321 -B Forces broadcast handling.
323
325 The following options only apply for DHCPv6 (i.e. when -6 is given).
326 -c Adds a rapid-commit option (exchanges will be SOLICIT-ADVER‐
328 TISE).
329 -F release-rate
331 Specifies the rate at which IPv6 RELEASE requests are sent to a
332 server. This value is only valid when used in conjunction with
333 the exchange rate (given by -r rate). Furthermore, the sum of
334 this value and the renew-rate (given by -f rate) must be equal
335 to or less than the exchange rate value.
336 -A encapsulation-level
338 Specifies that relayed traffic must be generated. The argument
339 specifies the level of encapsulation, i.e. how many relay agents
340 are simulated. Currently the only supported encapsulation-level
341 value is 1, which means that the generated traffic is equivalent
342 to the amount of traffic passing through a single relay agent.
343
345 The following options may only be used in conjunction with -T and con‐
346 trol how perfdhcp modifies the template. The options may be specified
347 multiple times on the command line; each occurrence affects the corre‐
348 sponding template file (see "Templates" above).
349 -E time-offset
351 Specifies the offset of the secs field (DHCPv4) or elapsed-time
352 option (DHCPv6) in the second (i.e. REQUEST) template; must be 0
353 or a positive integer. A value of 0 disables this.
354 -I ip-offset
356 Specifies the offset of the IP address (DHCPv4) in the re‐
357 quested-IP option or IA_NA option (DHCPv6) in the second (RE‐
358 QUEST) template.
359 -O random-offset
361 Specifies the offset of the last octet to randomize in the tem‐
362 plate. This must be an integer greater than 3. The -T switch
363 must be given to use this option.
364 -S srvid-offset
366 Specifies the offset of the server-ID option in the second (RE‐
367 QUEST) template. This must be a positive integer, and the
368 switch can only be used when the template option (-T) is also
369 given.
370 -X xid-offset
372 Specifies the offset of the transaction ID (xid) in the tem‐
373 plate. This must be a positive integer, and the switch can only
374 be used when the template option (-T) is also given.
375
377 -D max-drop
378 Aborts the test immediately if max-drop requests have been
379 dropped. Use -D 0 to abort if even a single request has been
380 dropped. max-drop must be a positive integer. If max-drop in‐
381 cludes the suffix '%', it specifies a maximum percentage of re‐
382 quests that may be dropped before abort. In this case, testing
383 of the threshold begins after 10 requests have been expected to
384 be received.
385 -n num-requests
387 Initiates num-request transactions. No report is generated until
388 all transactions have been initiated/waited-for, after which a
389 report is generated and the program terminates.
390 -p test-period
392 Sends requests for test-period, which is specified in the same
393 manner as -d. This can be used as an alternative to -n or both
394 options can be given, in which case the testing is completed
395 when either limit is reached.
396 -t interval
398 Sets the delay (in seconds) between two successive reports.
399 -C separator
401 Output reduced, an argument is a separator for periodic (-t) re‐
402 ports generated in easy parsable mode. Data output won't be
403 changed, remain identical as in -t option.
404
406 server Indicates the server to test, specified as an IP address. In the
407 DHCPv6 case, the special name 'all' can be used to refer to
408 All_DHCP_Relay_Agents_and_Servers (the multicast address
409 FF02::1:2), or the special name 'servers' to refer to
410 All_DHCP_Servers (the multicast address FF05::1:3). The server
411 is mandatory except where the -l option is given to specify an
412 interface, in which case it defaults to 'all'.
413
415 perfdhcp can report the following errors in the packet exchange:
416 tooshort
418 A message was received that was too short.
419 orphans
421 A message was received which does not match one sent to the
422 server (i.e. it is a duplicate message, a message that has ar‐
423 rived after an excessive delay, or one that is just not recog‐
424 nized).
425 locallimit
427 Local system limits have been reached when sending a message.
428
430 perfdhcp can exit with one of the following status codes:
431 0 Success.
433 1 General error.
435 2 Error in command-line arguments.
437 3 No general failures in operation, but one or more exchanges were
439 unsuccessful.
440
442 Simulate regular DHCPv4 traffic: 100 DHCPv4 devices (-R 100), 10 pack‐
443 ets per second (-r 10), show the query/response rate details (-xi), the
444 report should be shown every 2 seconds (-t 2), send the packets to the
445 IP 192.0.2.1:
446 sudo perfdhcp -xi -t 2 -r 10 -R 100 192.0.2.1
448 Here's a similar case, but for DHCPv6. Note that DHCPv6 protocol uses
450 link-local addresses, so you need to specify the interface (eth0 in
451 this example) to send the traffic. 'all' is a convenience alias for
452 All_DHCP_Relay_Agents_and_Servers (the multicast address FF02::1:2).
453 Alternatively, you can use 'servers' alias to refer to All_DHCP_Servers
454 (the multicast address FF05::1:3), or skip it all together and the de‐
455 fault value (all) will be used.
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 to not receive any responses from the
461 server for 10 seconds. DHCPv4 protocol signals this by increased secs
462 field and DHCPv6 uses elapsed option for that. In real networks this
463 indicates that the clients are not getting responses in a timely mat‐
464 ter. This can be used to simulate some HA scenarios, as Kea uses secs
465 field and elapsed option value as one of the indicators that the HA
466 partner is not responding. When enabled with -y and -Y, the secs and
467 elapsed time value increased 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 There are two public mailing lists available for the Kea project.
475 kea-users (kea-users at lists.isc.org) is intended for Kea users, while
476 kea-dev (kea-dev at lists.isc.org) is intended for Kea developers,
477 prospective contributors, and other advanced users. Both lists are
478 available at https://lists.isc.org. The community provides best-effort
479 support on both of those lists.
480 ISC provides professional support for Kea services. See
482 https://www.isc.org/kea/ for details.
483
485 The perfdhcp tool was initially coded in October 2011 by John DuBois,
486 Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which included
487 perfdhcp, was released in December 2015.
488
490 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8),
491 kea-admin(8), kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator
492 Reference Manual.
493
495 Internet Systems Consortium
496
498 2019-2021, Internet Systems Consortium
4991.9.8 Aug 06, 2021 PERFDHCP(8)