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 giaddr-list-file] [-l local-address|interface]
13 [-L local-port] [-M mac-list-file] [-n num-request] [-N remote-port]
14 [-O random-offset] [-o code,hexstring] [-p test-period] [-P preload]
15 [-r rate] [-R num-clients] [-s seed] [-S srvid-offset] [--scenario
16 name] [-t report] [-T template-file] [-u] [-v] [-W exit-wait-time] [-w
17 script_name] [-x diagnostic-selector] [-X xid-offset] [server]
18
20 perfdhcp is a DHCP benchmarking tool. It provides a way of measuring
21 the performance of DHCP servers by generating large amounts of traffic
22 from simulated multiple clients. It is able to test both IPv4 and IPv6
23 servers, and provides statistics concerning response times and the num‐
24 ber of requests that are dropped.
25 The tool supports scenarios, which offer certain behaviours. By de‐
27 fault (basic scenario) tests are run using the full four-packet ex‐
28 change sequence (DORA for DHCPv4, SARR for DHCPv6). An option is pro‐
29 vided to run tests using the initial two-packet exchange (DO and SA)
30 instead. It is also possible to configure perfdhcp to send DHCPv6 RENEW
31 and RELEASE messages at a specified rate in parallel with the DHCPv6
32 four-way exchanges. By default, if there is no response received with 1
33 second, a response is considered lost and perfdhcp continues with other
34 transactions.
35 Second scenario is called avalanche, which is selected by --scenario
37 avalanche. It first sends as many Discovery or Solicit messages as re‐
38 quest in -R option then a retransmission (with exponential back off
39 mechanism) is used for each simulated client until all requests are an‐
40 swered. It will generate report when all clients get their addresses or
41 when it will be manually stopped. This scenario attempts to replicate a
42 case where the server is not able to handle the traffic swiftly enough.
43 Real clients will assume the packet or the response was lost and will
44 retransmit, further increasing DHCP traffic. This is sometimes called
45 avalanche effect, thus the scenario name. Option -p is ignored in
46 avalanche scenario.
47 When running a performance test, perfdhcp will exchange packets with
49 the server under test as fast as possible unless the -r parameter is
50 used to limit the request rate. The length of the test can be limited
51 by setting a threshold on any or all of the number of requests made by
52 perfdhcp, the elapsed time, or the number of requests dropped by the
53 server.
54
56 To allow the contents of packets sent to the server to be customized,
57 perfdhcp allows the specification of template files that determine the
58 contents of the packets. For example, the customized packet may contain
59 a DHCPv6 ORO to request a set of options to be returned by the server,
60 or it may contain the Client FQDN option to request that the server
61 perform DNS updates. This may be used to discover performance bottle‐
62 necks for different server configurations (e.g. DDNS enabled or dis‐
63 abled).
64 Up to two template files can be specified on the command line, each
66 file representing the contents of a particular type of packet, the type
67 being determined by the test being carried out. For example, if testing
68 DHCPv6:
69 • With no template files specified on the command line, perfdhcp will
71 generate both SOLICIT and REQUEST packets.
72 • With one template file specified, that file will be used as the pat‐
74 tern for SOLICIT packets: perfdhcp will generate the REQUEST packets.
75 • With two template files given on the command line, the first will be
77 used as the pattern for SOLICIT packets, the second as the pattern
78 for REQUEST packets.
79 (Similar determination applies to DHCPv4's DISCOVER and REQUEST pack‐
81 ets.)
82 The template file holds the DHCP packet represented as a stream of
84 ASCII hexadecimal digits and it excludes any IP/UDP stack headers. The
85 template file must not contain any characters other than hexadecimal
86 digits and spaces. Spaces are discarded when the template file is
87 parsed; in the file, '12B4' is the same as '12 B4' which is the same as
88 '1 2 B 4'.
89 The template files should be used in conjunction with the command-line
91 parameters which specify offsets of the data fields being modified in
92 outbound packets. For example, the -E time-offset switch specifies the
93 offset of the DHCPv6 Elapsed Time option in the packet template. If
94 the offset is specified, perfdhcp will inject the current elapsed-time
95 value into this field before sending the packet to the server.
96 In many scenarios, perfdhcp needs to simulate multiple clients, each
98 having a unique client identifier. Since packets for each client are
99 generated from the same template file, it is necessary to randomize the
100 client identifier (or HW address in DHCPv4) in the packet created from
101 it. The -O random-offset option allows specification of the offset in
102 the template where randomization should be performed. It is important
103 to note that this offset points to the end (not the beginning) of the
104 client identifier (or HW address field). The number of bytes being ran‐
105 domized depends on the number of simulated clients. If the number of
106 simulated clients is between 1 and 255, only one byte (to which the
107 randomization offset points) will be randomized. If the number of simu‐
108 lated clients is between 256 and 65535, two bytes will be randomized.
109 Note that the last two bytes of the client identifier will be random‐
110 ized in this case: the byte which the randomization offset parameter
111 points to, and the one which precedes it (random-offset - 1). If the
112 number of simulated clients exceeds 65535, three bytes will be random‐
113 ized, and so on.
114 Perfdhcp can now simulate traffic from multiple subnets by enabling op‐
116 tion -J and passing path to file that contains v4 addresses that will
117 be used as giaddr in generated messages. That enable testing of vast
118 numbers of Kea shared networks. Kea should be started with
119 KEA_TEST_SEND_RESPONSES_TO_SOURCE environment variable to force Kea to
120 send generated messages to source address of incoming packet. Feature
121 is not available in kea-dhcp6.
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 DISCOVER,
125 REQUEST (DHCPv4). They cannot be used when RENEW or RELEASE packets are
126 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. This is incompatible with the -4
135 option.
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 second.
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) will be requested.
159 prefix-only
161 Only IPv6 prefixes will be requested.
162 address-and-prefix
164 Both IPv6 addresses and prefixes will be requested.
165 The -e prefix-only and -e address-and-prefix forms may not be
167 used with the -4 option.
168 -f renew-rate
170 Specifies the rate at which DHCPv4 or DHCPv6 renew requests are
171 sent to a server. This value is only valid when used in con‐
172 junction with the exchange rate (given by -r rate). Furthermore,
173 the sum of this value and the release-rate (given by -F rate)
174 must be equal to or less than the exchange rate.
175 -g thread-mode
177 Allows selection of thread-mode, which can be either 'single' or
178 'multi'. In multi-thread mode packets are received in a separate
179 thread, which allows better utilisation of CPUs. In a single-CPU
180 system it is better to run in one thread to avoid threads block‐
181 ing each other. If more than one CPU is present in the system,
182 multi-thread mode is the default; otherwise single-thread is the
183 default.
184 -h Prints help and exits.
186 -i Performs only the initial part of the exchange: DISCOVER-OFFER
188 if -4 is selected, SOLICIT-ADVERTISE if -6 is chosen.
189 -i is incompatible with the following options: -1, -d, -D, -E,
191 -S, -I and -F. In addition, it cannot be used with multiple in‐
192 stances of -O, -T and -X.
193 -l local-addr|interface
195 For DHCPv4 operation, specifies the local hostname/address to
196 use when communicating with the server. By default, the inter‐
197 face address through which traffic would normally be routed to
198 the server is used. For DHCPv6 operation, specifies the name of
199 the network interface through which exchanges are initiated.
200 -L local-port
202 Specifies the local port to use. This must be zero or a positive
203 integer up to 65535. A value of 0 (the default) allows perfdhcp
204 to choose its own port.
205 -M mac-list-file
207 Specifies a text file containing a list of MAC addresses, one
208 per line. If provided, a MAC address will be chosen randomly
209 from this list for every new exchange. In DHCPv6, MAC addresses
210 are used to generate DUID-LLs. This parameter must not be used
211 in conjunction with the -b parameter.
212 -N remote-port
214 Specifies the remote port to use. This must be zero or a posi‐
215 tive integer up to 65535. A value of 0 (the default) allows
216 perfdhcp to choose the standard service port.
217 -o code,hexstring
219 Forces perfdhcp to insert the specified extra option (or options
220 if used several times) into packets being transmitted. The code
221 specifies the option code and the hexstring is a hexadecimal
222 string that defines the content of the option. Care should be
223 taken as perfdhcp does not offer any kind of logic behind those
224 options; they are simply inserted into packets and sent as is.
225 Be careful not to duplicate options that are already inserted.
226 For example, to insert client class identifier (option code 60)
227 with a string 'docsis', use -o 60,646f63736973. The -o may be
228 used multiple times. It is necessary to specify the protocol
229 family (either -4 or -6) before using -o.
230 -P preload
232 Initiates preload exchanges back-to-back at startup. Must be 0
233 (the default) or a positive integer.
234 -r rate
236 Initiates the rate of DORA/SARR (or if -i is given, DO/SA) ex‐
237 changes per second. A periodic report is generated showing the
238 number of exchanges which were not completed, as well as the av‐
239 erage response latency. The program continues until interrupted,
240 at which point a final report is generated.
241 -R num-clients
243 Specifies how many different clients are used. With a value of 1
244 (the default), all requests seem to come from the same client.
245 Must be a positive number.
246 -s seed
248 Specifies the seed for randomization, making runs of perfdhcp
249 repeatable. This must be 0 or a positive integer. The value 0
250 means that a seed is not used; this is the default.
251 --scenario name
253 Specifies type of the scenario, can be basic (default) or
254 avalanche.
255 -T template-file
257 Specifies a file containing the template to use as a stream of
258 hexadecimal digits. This may be specified up to two times and
259 controls the contents of the packets sent (see the "Templates"
260 section above).
261 -u Enable checking address uniqueness. Lease valid lifetime should
263 not be shorter than test duration and clients should not request
264 address more than once without releasing it first.
265 -v Prints the version of this program.
267 -W exit-wait-time
269 Specifies the exit-wait-time parameter, which causes perfdhcp to
270 wait for exit-wait-time after an exit condition has been met, to
271 receive all packets without sending any new packets. Expressed
272 in microseconds. If not specified, 0 is used (i.e. exit immedi‐
273 ately after exit conditions are met).
274 -w script_name
276 Specifies the name of the script to be run before/after perfd‐
277 hcp. When called, the script is passed a single parameter, ei‐
278 ther "start" or "stop", indicating whether it is being called
279 before or after perfdhcp.
280 -x diagnostic-selector
282 Includes extended diagnostics in the output. This is a string of
283 single keywords specifying the operations for which verbose out‐
284 put is desired. The selector key letters are:
285 a Prints the decoded command line arguments.
287 e Prints the exit reason.
289 i Prints the rate processing details.
291 s Prints the first server-ID.
293 t When finished, prints timers of all successful exchanges.
295 T When finished, prints templates.
297 -y seconds
299 Time in seconds after which perfdhcp will start simulating the
300 client waiting longer for server responses. This increase the
301 secs field in DHCPv4 and sends increased values in Elapsed op‐
302 tion in DHCPv6. Must be used with '-Y'.
303 -Y seconds
305 Period of time in seconds in which perfdhcp will be simulating
306 the client waiting longer for server responses. This increase
307 the secs field in DHCPv4 and sends increased values in Elapsed
308 option in DHCPv6. Must be used with '-y'.
309
311 The following options only apply for DHCPv4 (i.e. when -4 is given).
312 -B Forces broadcast handling.
314 -J giaddr-list-file
316 Text file that include multiple addresses. If provided perfdhcp
317 will choose randomly one of addresses for each exchange. This is
318 used to generate traffic from multiple subnets. Designed to test
319 shared-networks in kea-dhcp4. Kea should be started with
320 KEA_TEST_SEND_RESPONSES_TO_SOURCE=ENABLE env variable otherwise
321 perfdhcp will not be able to receive responses.
322
324 The following options only apply for DHCPv6 (i.e. when -6 is given).
325 -c Adds a rapid-commit option (exchanges will be SOLICIT-ADVER‐
327 TISE).
328 -F release-rate
330 Specifies the rate at which IPv6 RELEASE requests are sent to a
331 server. This value is only valid when used in conjunction with
332 the exchange rate (given by -r rate). Furthermore, the sum of
333 this value and the renew-rate (given by -f rate) must be equal
334 to or less than the exchange rate value.
335 -A encapsulation-level
337 Specifies that relayed traffic must be generated. The argument
338 specifies the level of encapsulation, i.e. how many relay agents
339 are simulated. Currently the only supported encapsulation-level
340 value is 1, which means that the generated traffic is equivalent
341 to the amount of traffic passing through a single relay agent.
342
344 The following options may only be used in conjunction with -T and con‐
345 trol how perfdhcp modifies the template. The options may be specified
346 multiple times on the command line; each occurrence affects the corre‐
347 sponding template file (see "Templates" above).
348 -E time-offset
350 Specifies the offset of the secs field (DHCPv4) or elapsed-time
351 option (DHCPv6) in the second (i.e. REQUEST) template; must be 0
352 or a positive integer. A value of 0 disables this.
353 -I ip-offset
355 Specifies the offset of the IP address (DHCPv4) in the re‐
356 quested-IP option or IA_NA option (DHCPv6) in the second (RE‐
357 QUEST) template.
358 -O random-offset
360 Specifies the offset of the last octet to randomize in the tem‐
361 plate. This must be an integer greater than 3. The -T switch
362 must be given to use this option.
363 -S srvid-offset
365 Specifies the offset of the server-ID option in the second (RE‐
366 QUEST) template. This must be a positive integer, and the
367 switch can only be used when the template option (-T) is also
368 given.
369 -X xid-offset
371 Specifies the offset of the transaction ID (xid) in the tem‐
372 plate. This must be a positive integer, and the switch can only
373 be used when the template option (-T) is also given.
374
376 -D max-drop
377 Aborts the test immediately if max-drop requests have been
378 dropped. Use -D 0 to abort if even a single request has been
379 dropped. max-drop must be a positive integer. If max-drop in‐
380 cludes the suffix '%', it specifies a maximum percentage of re‐
381 quests that may be dropped before abort. In this case, testing
382 of the threshold begins after 10 requests have been expected to
383 be received.
384 -n num-requests
386 Initiates num-request transactions. No report is generated until
387 all transactions have been initiated/waited-for, after which a
388 report is generated and the program terminates.
389 -p test-period
391 Sends requests for test-period, which is specified in the same
392 manner as -d. This can be used as an alternative to -n or both
393 options can be given, in which case the testing is completed
394 when either limit is reached.
395 -t interval
397 Sets the delay (in seconds) between two successive reports.
398 -C separator
400 Output reduced, an argument is a separator for periodic (-t) re‐
401 ports generated in easy parsable mode. Data output won't be
402 changed, remain identical as in -t option.
403
405 server Indicates the server to test, specified as an IP address. In the
406 DHCPv6 case, the special name 'all' can be used to refer to
407 All_DHCP_Relay_Agents_and_Servers (the multicast address
408 FF02::1:2), or the special name 'servers' to refer to
409 All_DHCP_Servers (the multicast address FF05::1:3). The server
410 is mandatory except where the -l option is given to specify an
411 interface, in which case it defaults to 'all'.
412
414 perfdhcp can report the following errors in the packet exchange:
415 tooshort
417 A message was received that was too short.
418 orphans
420 A message was received which does not match one sent to the
421 server (i.e. it is a duplicate message, a message that has ar‐
422 rived after an excessive delay, or one that is just not recog‐
423 nized).
424 locallimit
426 Local system limits have been reached when sending a message.
427
429 perfdhcp can exit with one of the following status codes:
430 0 Success.
432 1 General error.
434 2 Error in command-line arguments.
436 3 No general failures in operation, but one or more exchanges were
438 unsuccessful.
439
441 Simulate regular DHCPv4 traffic: 100 DHCPv4 devices (-R 100), 10 pack‐
442 ets per second (-r 10), show the query/response rate details (-xi), the
443 report should be shown every 2 seconds (-t 2), send the packets to the
444 IP 192.0.2.1:
445 sudo perfdhcp -xi -t 2 -r 10 -R 100 192.0.2.1
447 Here's a similar case, but for DHCPv6. Note that DHCPv6 protocol uses
449 link-local addresses, so you need to specify the interface (eth0 in
450 this example) to send the traffic. 'all' is a convenience alias for
451 All_DHCP_Relay_Agents_and_Servers (the multicast address FF02::1:2).
452 Alternatively, you can use 'servers' alias to refer to All_DHCP_Servers
453 (the multicast address FF05::1:3), or skip it all together and the de‐
454 fault value (all) will be used.
455 sudo perfdhcp -6 -xi -t 1 -r 1 -R 10 -l eth0 all
457 The following examples simulate normal DHCPv4 and DHCPv6 traffic that
459 after 3 seconds starts pretending to not receive any responses from the
460 server for 10 seconds. DHCPv4 protocol signals this by increased secs
461 field and DHCPv6 uses elapsed option for that. In real networks this
462 indicates that the clients are not getting responses in a timely mat‐
463 ter. This can be used to simulate some HA scenarios, as Kea uses secs
464 field and elapsed option value as one of the indicators that the HA
465 partner is not responding. When enabled with -y and -Y, the secs and
466 elapsed time value increased steadily.
467 sudo perfdhcp -xi -t 1 -r 1 -y 10 -Y 3 192.0.2.1
469 sudo perfdhcp -6 -xi -t 1 -r 1 -y 10 -Y 3 2001:db8::1
471
473 There are two public mailing lists available for the Kea project.
474 kea-users (kea-users at lists.isc.org) is intended for Kea users, while
475 kea-dev (kea-dev at lists.isc.org) is intended for Kea developers,
476 prospective contributors, and other advanced users. Both lists are
477 available at https://lists.isc.org. The community provides best-effort
478 support on both of those lists.
479 ISC provides professional support for Kea services. See
481 https://www.isc.org/kea/ for details.
482
484 The perfdhcp tool was initially coded in October 2011 by John DuBois,
485 Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which included
486 perfdhcp, was released in December 2015.
487
489 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8),
490 kea-admin(8), kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator
491 Reference Manual.
492
494 Internet Systems Consortium
495
497 2019-2021, Internet Systems Consortium
4981.9.4 Feb 08, 2021 PERFDHCP(8)