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] [-t report] [-T template-file] [-v] [-W exit-wait-time]
16 [-w script_name] [-x diagnostic-selector] [-X xid-offset] [server]
17
19 perfdhcp is a DHCP benchmarking tool. It provides a way of measuring
20 the performance of DHCP servers by generating large amounts of traffic
21 from simulated multiple clients. It is able to test both IPv4 and IPv6
22 servers, and provides statistics concerning response times and the num‐
23 ber of requests that are dropped.
24 By default, tests are run using the full four-packet exchange sequence
26 (DORA for DHCPv4, SARR for DHCPv6). An option is provided to run tests
27 using the initial two-packet exchange (DO and SA) instead. It is also
28 possible to configure perfdhcp to send DHCPv6 RENEW and RELEASE mes‐
29 sages at a specified rate in parallel with the DHCPv6 four-way
30 exchanges.
31 When running a performance test, perfdhcp will exchange packets with
33 the server under test as fast as possible unless the -r parameter is
34 used to limit the request rate. The length of the test can be limited
35 by setting a threshold on any or all of the number of requests made by
36 perfdhcp, the elapsed time, or the number of requests dropped by the
37 server.
38
40 To allow the contents of packets sent to the server to be customized,
41 perfdhcp allows the specification of template files that determine the
42 contents of the packets. For example, the customized packet may contain
43 a DHCPv6 ORO to request a set of options to be returned by the server,
44 or it may contain the Client FQDN option to request that the server
45 perform DNS updates. This may be used to discover performance bottle‐
46 necks for different server configurations (e.g. DDNS enabled or dis‐
47 abled).
48 Up to two template files can be specified on the command line, each
50 file representing the contents of a particular type of packet, the type
51 being determined by the test being carried out. For example, if testing
52 DHCPv6:
53 · With no template files specified on the command line, perfdhcp will
55 generate both SOLICIT and REQUEST packets.
56 · With one template file specified, that file will be used as the pat‐
58 tern for SOLICIT packets: perfdhcp will generate the REQUEST packets.
59 · With two template files given on the command line, the first will be
61 used as the pattern for SOLICIT packets, the second as the pattern
62 for REQUEST packets.
63 (Similar determination applies to DHCPv4's DISCOVER and REQUEST pack‐
65 ets.)
66 The template file holds the DHCP packet represented as a stream of
68 ASCII hexadecimal digits and it excludes any IP/UDP stack headers. The
69 template file must not contain any characters other than hexadecimal
70 digits and spaces. Spaces are discarded when the template file is
71 parsed; in the file, '12B4' is the same as '12 B4' which is the same as
72 '1 2 B 4'.
73 The template files should be used in conjunction with the command-line
75 parameters which specify offsets of the data fields being modified in
76 outbound packets. For example, the -E time-offset switch specifies the
77 offset of the DHCPv6 Elapsed Time option in the packet template. If
78 the offset is specified, perfdhcp will inject the current elapsed-time
79 value into this field before sending the packet to the server.
80 In many scenarios, perfdhcp needs to simulate multiple clients, each
82 having a unique client identifier. Since packets for each client are
83 generated from the same template file, it is necessary to randomize the
84 client identifier (or HW address in DHCPv4) in the packet created from
85 it. The -O random-offset option allows specification of the offset in
86 the template where randomization should be performed. It is important
87 to note that this offset points to the end (not the beginning) of the
88 client identifier (or HW address field). The number of bytes being ran‐
89 domized depends on the number of simulated clients. If the number of
90 simulated clients is between 1 and 255, only one byte (to which the
91 randomization offset points) will be randomized. If the number of simu‐
92 lated clients is between 256 and 65535, two bytes will be randomized.
93 Note that the last two bytes of the client identifier will be random‐
94 ized in this case: the byte which the randomization offset parameter
95 points to, and the one which precedes it (random-offset - 1). If the
96 number of simulated clients exceeds 65535, three bytes will be random‐
97 ized, and so on.
98 Templates may currently be used to generate packets being sent to the
100 server in 4-way exchanges, i.e. SOLICIT, REQUEST (DHCPv6) and DISCOVER,
101 REQUEST (DHCPv4). They cannot be used when RENEW or RELEASE packets are
102 being sent.
103
105 -1 Takes the server-ID option from the first received message.
106 -4 Establishes DHCPv4 operation; this is the default. It is incom‐
108 patible with the -6 option.
109 -6 Establishes DHCPv6 operation. This is incompatible with the -4
111 option.
112 -b basetype=value
114 Indicates the base MAC or DUID used to simulate different
115 clients. The basetype may be "mac" or "duid". (The keyword
116 "ether" may alternatively used for MAC.) The -b option can be
117 specified multiple times. The MAC address must consist of six
118 octets separated by single (:) or double (::) colons, for exam‐
119 ple: mac=00:0c:01:02:03:04. The DUID value is a hexadecimal
120 string; it must be at least six octets long and not longer than
121 64 bytes, and the length must be less than 128 hexadecimal dig‐
122 its, for example: duid=0101010101010101010110111F14.
123 -d drop-time
125 Specifies the time after which a request is treated as having
126 been lost. The value is given in seconds and may contain a frac‐
127 tional component. The default is 1 second.
128 -e lease-type
130 Specifies the type of lease being requested from the server. It
131 may be one of the following:
132 address-only
134 Only regular addresses (v4 or v6) will be requested.
135 prefix-only
137 Only IPv6 prefixes will be requested.
138 address-and-prefix
140 Both IPv6 addresses and prefixes will be requested.
141 The -e prefix-only and -e address-and-prefix forms may not be
143 used with the -4 option.
144 -f renew-rate
146 Specifies the rate at which DHCPv4 or DHCPv6 renew requests are
147 sent to a server. This value is only valid when used in con‐
148 junction with the exchange rate (given by -r rate). Furthermore,
149 the sum of this value and the release-rate (given by -F rate)
150 must be equal to or less than the exchange rate.
151 -g thread-mode
153 Allows selection of thread-mode, which can be either 'single' or
154 'multi'. In multi-thread mode packets are received in a separate
155 thread, which allows better utilisation of CPUs. In a single-CPU
156 system it is better to run in one thread to avoid threads block‐
157 ing each other. If more than one CPU is present in the system,
158 multi-thread mode is the default; otherwise single-thread is the
159 default.
160 -h Prints help and exits.
162 -i Performs only the initial part of the exchange: DISCOVER-OFFER
164 if -4 is selected, SOLICIT-ADVERTISE if -6 is chosen.
165 -i is incompatible with the following options: -1, -d, -D, -E,
167 -S, -I and -F. In addition, it cannot be used with multiple
168 instances of -O, -T and -X.
169 -l local-addr|interface
171 For DHCPv4 operation, specifies the local hostname/address to
172 use when communicating with the server. By default, the inter‐
173 face address through which traffic would normally be routed to
174 the server is used. For DHCPv6 operation, specifies the name of
175 the network interface through which exchanges are initiated.
176 -L local-port
178 Specifies the local port to use. This must be zero or a positive
179 integer up to 65535. A value of 0 (the default) allows perfdhcp
180 to choose its own port.
181 -M mac-list-file
183 Specifies a text file containing a list of MAC addresses, one
184 per line. If provided, a MAC address will be chosen randomly
185 from this list for every new exchange. In DHCPv6, MAC addresses
186 are used to generate DUID-LLs. This parameter must not be used
187 in conjunction with the -b parameter.
188 -N remote-port
190 Specifies the remote port to use. This must be zero or a posi‐
191 tive integer up to 65535. A value of 0 (the default) allows
192 perfdhcp to choose the standard service port.
193 -o code,hexstring
195 Forces perfdhcp to insert the specified extra option (or options
196 if used several times) into packets being transmitted. The code
197 specifies the option code and the hexstring is a hexadecimal
198 string that defines the content of the option. Care should be
199 taken as perfdhcp does not offer any kind of logic behind those
200 options; they are simply inserted into packets and sent as is.
201 Be careful not to duplicate options that are already inserted.
202 For example, to insert client class identifier (option code 60)
203 with a string 'docsis', use -o 60,646f63736973. The -o may be
204 used multiple times. It is necessary to specify the protocol
205 family (either -4 or -6) before using -o.
206 -P preload
208 Initiates preload exchanges back-to-back at startup. Must be 0
209 (the default) or a positive integer.
210 -r rate
212 Initiates the rate of DORA/SARR (or if -i is given, DO/SA)
213 exchanges per second. A periodic report is generated showing the
214 number of exchanges which were not completed, as well as the
215 average response latency. The program continues until inter‐
216 rupted, at which point a final report is generated.
217 -R num-clients
219 Specifies how many different clients are used. With a value of 1
220 (the default), all requests seem to come from the same client.
221 Must be a positive number.
222 -s seed
224 Specifies the seed for randomization, making runs of perfdhcp
225 repeatable. This must be 0 or a positive integer. The value 0
226 means that a seed is not used; this is the default.
227 -T template-file
229 Specifies a file containing the template to use as a stream of
230 hexadecimal digits. This may be specified up to two times and
231 controls the contents of the packets sent (see the "Templates"
232 section above).
233 -v Prints the version of this program.
235 -W exit-wait-time
237 Specifies the exit-wait-time parameter, which causes perfdhcp to
238 wait for exit-wait-time after an exit condition has been met, to
239 receive all packets without sending any new packets. Expressed
240 in microseconds. If not specified, 0 is used (i.e. exit immedi‐
241 ately after exit conditions are met).
242 -w script_name
244 Specifies the name of the script to be run before/after perfd‐
245 hcp. When called, the script is passed a single parameter,
246 either "start" or "stop", indicating whether it is being called
247 before or after perfdhcp.
248 -x diagnostic-selector
250 Includes extended diagnostics in the output. This is a string of
251 single keywords specifying the operations for which verbose out‐
252 put is desired. The selector key letters are:
253 a Prints the decoded command line arguments.
255 e Prints the exit reason.
257 i Prints the rate processing details.
259 s Prints the first server-ID.
261 t When finished, prints timers of all successful exchanges.
263 T When finished, prints templates.
265
267 The following options only apply for DHCPv4 (i.e. when -4 is given).
268 -B Forces broadcast handling.
270
272 The following options only apply for DHCPv6 (i.e. when -6 is given).
273 -c Adds a rapid-commit option (exchanges will be SOLICIT-ADVER‐
275 TISE).
276 -F release-rate
278 Specifies the rate at which IPv6 RELEASE requests are sent to a
279 server. This value is only valid when used in conjunction with
280 the exchange rate (given by -r rate). Furthermore, the sum of
281 this value and the renew-rate (given by -f rate) must be equal
282 to or less than the exchange rate value.
283 -A encapsulation-level
285 Specifies that relayed traffic must be generated. The argument
286 specifies the level of encapsulation, i.e. how many relay agents
287 are simulated. Currently the only supported encapsulation-level
288 value is 1, which means that the generated traffic is equivalent
289 to the amount of traffic passing through a single relay agent.
290
292 The following options may only be used in conjunction with -T and con‐
293 trol how perfdhcp modifies the template. The options may be specified
294 multiple times on the command line; each occurrence affects the corre‐
295 sponding template file (see "Templates" above).
296 -E time-offset
298 Specifies the offset of the secs field (DHCPv4) or elapsed-time
299 option (DHCPv6) in the second (i.e. REQUEST) template; must be 0
300 or a positive integer. A value of 0 disables this.
301 -I ip-offset
303 Specifies the offset of the IP address (DHCPv4) in the
304 requested-IP option or IA_NA option (DHCPv6) in the second
305 (REQUEST) template.
306 -O random-offset
308 Specifies the offset of the last octet to randomize in the tem‐
309 plate. This must be an integer greater than 3. The -T switch
310 must be given to use this option.
311 -S srvid-offset
313 Specifies the offset of the server-ID option in the second
314 (REQUEST) template. This must be a positive integer, and the
315 switch can only be used when the template option (-T) is also
316 given.
317 -X xid-offset
319 Specifies the offset of the transaction ID (xid) in the tem‐
320 plate. This must be a positive integer, and the switch can only
321 be used when the template option (-T) is also given.
322
324 -D max-drop
325 Aborts the test immediately if max-drop requests have been
326 dropped. Use -D 0 to abort if even a single request has been
327 dropped. max-drop must be a positive integer. If max-drop
328 includes the suffix '%', it specifies a maximum percentage of
329 requests that may be dropped before abort. In this case, testing
330 of the threshold begins after 10 requests have been expected to
331 be received.
332 -n num-requests
334 Initiates num-request transactions. No report is generated until
335 all transactions have been initiated/waited-for, after which a
336 report is generated and the program terminates.
337 -p test-period
339 Sends requests for test-period, which is specified in the same
340 manner as -d. This can be used as an alternative to -n or both
341 options can be given, in which case the testing is completed
342 when either limit is reached.
343 -t interval
345 Sets the delay (in seconds) between two successive reports.
346
348 server Indicates the server to test, specified as an IP address. In the
349 DHCPv6 case, the special name 'all' can be used to refer to
350 All_DHCP_Relay_Agents_and_Servers (the multicast address
351 FF02::1:2), or the special name 'servers' to refer to
352 All_DHCP_Servers (the multicast address FF05::1:3). The server
353 is mandatory except where the -l option is given to specify an
354 interface, in which case it defaults to 'all'.
355
357 perfdhcp can report the following errors in the packet exchange:
358 tooshort
360 A message was received that was too short.
361 orphans
363 A message was received which does not match one sent to the
364 server (i.e. it is a duplicate message, a message that has
365 arrived after an excessive delay, or one that is just not recog‐
366 nized).
367 locallimit
369 Local system limits have been reached when sending a message.
370
372 perfdhcp can exit with one of the following status codes:
373 0 Success.
375 1 General error.
377 2 Error in command-line arguments.
379 3 No general failures in operation, but one or more exchanges were
381 unsuccessful.
382
384 There are two public mailing lists available for the Kea project.
385 kea-users (kea-users at lists.isc.org) is intended for Kea users, while
386 kea-dev (kea-dev at lists.isc.org) is intended for Kea developers,
387 prospective contributors, and other advanced users. Both lists are
388 available at https://lists.isc.org. The community provides best-effort
389 support on both of those lists.
390 ISC provides professional support for Kea services. See
392 https://www.isc.org/kea/ for details.
393
395 The perfdhcp tool was initially coded in October 2011 by John DuBois,
396 Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which included
397 perfdhcp, was released in December 2015.
398
400 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8),
401 kea-admin(8), kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator
402 Reference Manual.
403
405 Internet Systems Consortium
406
408 2020, Internet Systems Consortium
4091.6.0 Jan 29, 2020 PERFDHCP(8)