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 [-d drop-time] [-D max-drop] [-e lease-type] [-E time-offset] [-f
11 renew-rate] [-F release-rate] [-g thread-mode] [-h] [-i] [-I ip-offset]
12 [-l local-address|interface] [-L local-port] [-M mac-list-file] [-n
13 num-request] [-N remote-port] [-O random-offset] [-o code,hexstring]
14 [-p test-period] [-P preload] [-r rate] [-R num-clients] [-s seed] [-S
15 srvid-offset] [--scenario name] [-t report] [-T template-file] [-v] [-W
16 exit-wait-time] [-w script_name] [-x diagnostic-selector] [-X xid-off‐
17 set] [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
27 default (basic scenario) tests are run using the full four-packet
28 exchange 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
38 request in -R option then a retransmission (with exponential back off
39 mechanism) is used for each simulated client until all requests are
40 answered. It will generate report when all clients get their addresses
41 or when it will be manually stopped. This scenario attempts to repli‐
42 cate a case where the server is not able to handle the traffic swiftly
43 enough. Real clients will assume the packet or the response was lost
44 and will retransmit, further increasing DHCP traffic. This is sometimes
45 called avalanche effect, thus the scenario name. Option -p is ignored
46 in 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
116 option -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 -u Enable checking address uniqueness. Lease valid lifetime should
138 not be shorter than test duration and clients should not request
139 address more than once without releasing it first.
140 -b basetype=value
142 Indicates the base MAC or DUID used to simulate different
143 clients. The basetype may be "mac" or "duid". (The keyword
144 "ether" may alternatively used for MAC.) The -b option can be
145 specified multiple times. The MAC address must consist of six
146 octets separated by single (:) or double (::) colons, for exam‐
147 ple: mac=00:0c:01:02:03:04. The DUID value is a hexadecimal
148 string; it must be at least six octets long and not longer than
149 64 bytes, and the length must be less than 128 hexadecimal dig‐
150 its, for example: duid=0101010101010101010110111F14.
151 -d drop-time
153 Specifies the time after which a request is treated as having
154 been lost. The value is given in seconds and may contain a frac‐
155 tional component. The default is 1 second.
156 -e lease-type
158 Specifies the type of lease being requested from the server. It
159 may be one of the following:
160 address-only
162 Only regular addresses (v4 or v6) will be requested.
163 prefix-only
165 Only IPv6 prefixes will be requested.
166 address-and-prefix
168 Both IPv6 addresses and prefixes will be requested.
169 The -e prefix-only and -e address-and-prefix forms may not be
171 used with the -4 option.
172 -f renew-rate
174 Specifies the rate at which DHCPv4 or DHCPv6 renew requests are
175 sent to a server. This value is only valid when used in con‐
176 junction with the exchange rate (given by -r rate). Furthermore,
177 the sum of this value and the release-rate (given by -F rate)
178 must be equal to or less than the exchange rate.
179 -g thread-mode
181 Allows selection of thread-mode, which can be either 'single' or
182 'multi'. In multi-thread mode packets are received in a separate
183 thread, which allows better utilisation of CPUs. In a single-CPU
184 system it is better to run in one thread to avoid threads block‐
185 ing each other. If more than one CPU is present in the system,
186 multi-thread mode is the default; otherwise single-thread is the
187 default.
188 -h Prints help and exits.
190 -i Performs only the initial part of the exchange: DISCOVER-OFFER
192 if -4 is selected, SOLICIT-ADVERTISE if -6 is chosen.
193 -i is incompatible with the following options: -1, -d, -D, -E,
195 -S, -I and -F. In addition, it cannot be used with multiple
196 instances of -O, -T and -X.
197 -l local-addr|interface
199 For DHCPv4 operation, specifies the local hostname/address to
200 use when communicating with the server. By default, the inter‐
201 face address through which traffic would normally be routed to
202 the server is used. For DHCPv6 operation, specifies the name of
203 the network interface through which exchanges are initiated.
204 -L local-port
206 Specifies the local port to use. This must be zero or a positive
207 integer up to 65535. A value of 0 (the default) allows perfdhcp
208 to choose its own port.
209 -M mac-list-file
211 Specifies a text file containing a list of MAC addresses, one
212 per line. If provided, a MAC address will be chosen randomly
213 from this list for every new exchange. In DHCPv6, MAC addresses
214 are used to generate DUID-LLs. This parameter must not be used
215 in conjunction with the -b parameter.
216 -N remote-port
218 Specifies the remote port to use. This must be zero or a posi‐
219 tive integer up to 65535. A value of 0 (the default) allows
220 perfdhcp to choose the standard service port.
221 -o code,hexstring
223 Forces perfdhcp to insert the specified extra option (or options
224 if used several times) into packets being transmitted. The code
225 specifies the option code and the hexstring is a hexadecimal
226 string that defines the content of the option. Care should be
227 taken as perfdhcp does not offer any kind of logic behind those
228 options; they are simply inserted into packets and sent as is.
229 Be careful not to duplicate options that are already inserted.
230 For example, to insert client class identifier (option code 60)
231 with a string 'docsis', use -o 60,646f63736973. The -o may be
232 used multiple times. It is necessary to specify the protocol
233 family (either -4 or -6) before using -o.
234 -P preload
236 Initiates preload exchanges back-to-back at startup. Must be 0
237 (the default) or a positive integer.
238 -r rate
240 Initiates the rate of DORA/SARR (or if -i is given, DO/SA)
241 exchanges per second. A periodic report is generated showing the
242 number of exchanges which were not completed, as well as the
243 average response latency. The program continues until inter‐
244 rupted, at which point a final report is generated.
245 -R num-clients
247 Specifies how many different clients are used. With a value of 1
248 (the default), all requests seem to come from the same client.
249 Must be a positive number.
250 -s seed
252 Specifies the seed for randomization, making runs of perfdhcp
253 repeatable. This must be 0 or a positive integer. The value 0
254 means that a seed is not used; this is the default.
255 --scenario name
257 Specifies type of the scenario, can be basic (default) or
258 avalanche.
259 -T template-file
261 Specifies a file containing the template to use as a stream of
262 hexadecimal digits. This may be specified up to two times and
263 controls the contents of the packets sent (see the "Templates"
264 section above).
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,
278 either "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
299 The following options only apply for DHCPv4 (i.e. when -4 is given).
300 -B Forces broadcast handling.
302 -J<giaddr-list-file>
304 Text file that include multiple addresses. If provided perfdhcp
305 will choose randomly one of addresses for each exchange. This is
306 used to generate traffic from multiple subnets. Designed to test
307 shared-networks in kea-dhcp4. Kea should be started with
308 KEA_TEST_SEND_RESPONSES_TO_SOURCE=ENABLE env variable otherwise
309 perfdhcp will not be able to receive responses.
310
312 The following options only apply for DHCPv6 (i.e. when -6 is given).
313 -c Adds a rapid-commit option (exchanges will be SOLICIT-ADVER‐
315 TISE).
316 -F release-rate
318 Specifies the rate at which IPv6 RELEASE requests are sent to a
319 server. This value is only valid when used in conjunction with
320 the exchange rate (given by -r rate). Furthermore, the sum of
321 this value and the renew-rate (given by -f rate) must be equal
322 to or less than the exchange rate value.
323 -A encapsulation-level
325 Specifies that relayed traffic must be generated. The argument
326 specifies the level of encapsulation, i.e. how many relay agents
327 are simulated. Currently the only supported encapsulation-level
328 value is 1, which means that the generated traffic is equivalent
329 to the amount of traffic passing through a single relay agent.
330
332 The following options may only be used in conjunction with -T and con‐
333 trol how perfdhcp modifies the template. The options may be specified
334 multiple times on the command line; each occurrence affects the corre‐
335 sponding template file (see "Templates" above).
336 -E time-offset
338 Specifies the offset of the secs field (DHCPv4) or elapsed-time
339 option (DHCPv6) in the second (i.e. REQUEST) template; must be 0
340 or a positive integer. A value of 0 disables this.
341 -I ip-offset
343 Specifies the offset of the IP address (DHCPv4) in the
344 requested-IP option or IA_NA option (DHCPv6) in the second
345 (REQUEST) template.
346 -O random-offset
348 Specifies the offset of the last octet to randomize in the tem‐
349 plate. This must be an integer greater than 3. The -T switch
350 must be given to use this option.
351 -S srvid-offset
353 Specifies the offset of the server-ID option in the second
354 (REQUEST) template. This must be a positive integer, and the
355 switch can only be used when the template option (-T) is also
356 given.
357 -X xid-offset
359 Specifies the offset of the transaction ID (xid) in the tem‐
360 plate. This must be a positive integer, and the switch can only
361 be used when the template option (-T) is also given.
362
364 -D max-drop
365 Aborts the test immediately if max-drop requests have been
366 dropped. Use -D 0 to abort if even a single request has been
367 dropped. max-drop must be a positive integer. If max-drop
368 includes the suffix '%', it specifies a maximum percentage of
369 requests that may be dropped before abort. In this case, testing
370 of the threshold begins after 10 requests have been expected to
371 be received.
372 -n num-requests
374 Initiates num-request transactions. No report is generated until
375 all transactions have been initiated/waited-for, after which a
376 report is generated and the program terminates.
377 -p test-period
379 Sends requests for test-period, which is specified in the same
380 manner as -d. This can be used as an alternative to -n or both
381 options can be given, in which case the testing is completed
382 when either limit is reached.
383 -t interval
385 Sets the delay (in seconds) between two successive reports.
386 -C<separator>
388 Output reduced, an argument is a separator for periodic (-t)
389 reports generated in easy parsable mode. Data output won't be
390 changed, remain identical as in -t option.
391
393 server Indicates the server to test, specified as an IP address. In the
394 DHCPv6 case, the special name 'all' can be used to refer to
395 All_DHCP_Relay_Agents_and_Servers (the multicast address
396 FF02::1:2), or the special name 'servers' to refer to
397 All_DHCP_Servers (the multicast address FF05::1:3). The server
398 is mandatory except where the -l option is given to specify an
399 interface, in which case it defaults to 'all'.
400
402 perfdhcp can report the following errors in the packet exchange:
403 tooshort
405 A message was received that was too short.
406 orphans
408 A message was received which does not match one sent to the
409 server (i.e. it is a duplicate message, a message that has
410 arrived after an excessive delay, or one that is just not recog‐
411 nized).
412 locallimit
414 Local system limits have been reached when sending a message.
415
417 perfdhcp can exit with one of the following status codes:
418 0 Success.
420 1 General error.
422 2 Error in command-line arguments.
424 3 No general failures in operation, but one or more exchanges were
426 unsuccessful.
427
429 There are two public mailing lists available for the Kea project.
430 kea-users (kea-users at lists.isc.org) is intended for Kea users, while
431 kea-dev (kea-dev at lists.isc.org) is intended for Kea developers,
432 prospective contributors, and other advanced users. Both lists are
433 available at https://lists.isc.org. The community provides best-effort
434 support on both of those lists.
435 ISC provides professional support for Kea services. See
437 https://www.isc.org/kea/ for details.
438
440 The perfdhcp tool was initially coded in October 2011 by John DuBois,
441 Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which included
442 perfdhcp, was released in December 2015.
443
445 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8),
446 kea-admin(8), kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator
447 Reference Manual.
448
450 Internet Systems Consortium
451
453 2020, Internet Systems Consortium
4541.7.9 Jul 28, 2020 PERFDHCP(8)