1PERFDHCP(8) Kea PERFDHCP(8)
2
6 perfdhcp - DHCP benchmarking tool
7
9 perfdhcp [-1] [-4|-6] [-A encapsulation-level] [-a aggressivity]
10 [-b base] [-B] [-c] [-d drop-time] [-D max-drop]
11 [-e lease-type] [-E time-offset] [-f renew-rate]
12 [-F release-rate] [-h] [-i] [-I ip-offset]
13 [-l local-address|interface] [-L local-port]
14 [-M mac-list-file] [-n num-request] [-O random-offset]
15 [-o code,hexstring] [-p test-period] [-P preload] [-r rate]
16 [-R num-clients] [-s seed] [-S srvid-offset] [-t report]
17 [-T template-file] [-v] [-W exit-wait-time] [-w wrapped]
18 [-x diagnostic-selector] [-X xid-offset] [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
25 number of requests that are dropped.
26 By default, tests are run using the full four-packet exchange sequence
28 (DORA for DHCPv4, SARR for DHCPv6). An option is provided to run tests
29 using the initial two-packet exchange (DO and SA) instead. It is also
30 possible to configure perfdhcp to send DHCPv6 RENEW and RELEASE
31 messages at a specified rate in parallel with the DHCPv6 four-way
32 exchanges.
33 When running a performance test, perfdhcp will exchange packets with
35 the server under test as fast as possible unless the -r is given to
36 limit the request rate. The length of the test can be limited by
37 setting a threshold on any or all of the number of requests made by
38 perfdhcp, the elapsed time, or the number of requests dropped by the
39 server.
40
42 To allow the contents of packets sent to the server to be customized,
43 perfdhcp allows the specification of template files that determine the
44 contents of the packets. For example, the customized packet may contain
45 a DHCPv6 ORO to request a set of options to be returned by the server,
46 or it may contain the Client FQDN option to request that server
47 performs DNS updates. This may be used to discover performance
48 bottlenecks for different server configurations (e.g. DDNS enabled or
49 disabled).
50 Up to two template files can be specified on the command line, each
52 file representing the contents of a particular type of packet, the type
53 being determined by the test being carried out. For example, if testing
54 DHCPv6:
55 · With no template files specified on the command line, perfdhcp will
57 generate both SOLICIT and REQUEST packets.
58 · With one template file specified, that file will be used as the
60 pattern for SOLICIT packets: perfdhcp will generate the REQUEST
61 packets.
62 · With two template files given on the command line, the first will
64 be used as the pattern for SOLICIT packets, the second as the
65 pattern for REQUEST packets.
66 (Similar determination applies to DHCPv4's DISCOVER and REQUEST
68 packets.)
69 The template file holds the DHCP packet represented as a stream of
71 ASCII hexadecimal digits and it excludes any IP/UDP stack headers. The
72 template file must not contain any characters other than hexadecimal
73 digits and spaces. Spaces are discarded when the template file is
74 parsed (so in the file, '12B4' is the same as '12 B4' which is the same
75 as '1 2 B 4')
76 The template files should be used in conjunction with the command line
78 parameters which specify offsets of the data fields being modified in
79 outbound packets. For example, the -E time-offset switch specifies the
80 offset of the DHCPv6 Elapsed Time option in the packet template. If the
81 offset is specified, perfdhcp will inject the current elapsed time
82 value into this field before sending the packet to the server.
83 In many scenarios, perfdhcp needs to simulate multiple clients (having
85 unique client identifier). Since packets for each client are generated
86 from the same template file, it is necessary to randomize the client
87 identifier (or HW address in DHCPv4) in the packet created from it. The
88 -O random-offset option allows specification of the offset in the
89 template where randomization should be performed. It is important to
90 note that this offset points to the end (not the beginning) of the
91 client identifier (or HW address field). The number of bytes being
92 randomized depends on the number of simulated clients. If the number of
93 simulated clients is between 1 and 255, only one byte (to which
94 randomization offset points) will be randomized. If the number of
95 simulated clients is between 256 and 65535, two bytes will be
96 randomized. Note, that two last bytes of the client identifier will be
97 randomized in this case: the byte which randomization offset parameter
98 points to, and the one which precedes it (random-offset - 1). If the
99 number of simulated clients exceeds 65535, three bytes will be
100 randomized; and so on.
101 Templates may be currently used to generate packets being sent to the
103 server in 4-way exchanges, i.e. SOLICIT, REQUEST (DHCPv6) and DISCOVER,
104 REQUEST (DHCPv4). They cannot be used when RENEW or RELEASE packets are
105 being sent.
106
108 -1
109 Take the server-ID option from the first received message.
110 -4
112 DHCPv4 operation; this is the default. It is incompatible with the
113 -6 option.
114 -6
116 DHCPv6 operation. This is incompatible with the -4 option.
117 -a aggressivity
119 When the target sending rate is not yet reached, control how many
120 exchanges are initiated before the next pause. This is a positive
121 integer and defaults to 1.
122 -b basetype=value
124 The base MAC or DUID used to simulate different clients. The
125 basetype may be "mac" or "duid". (The keyword "ether" may
126 alternatively used for MAC.) The -b option can be specified
127 multiple times. The MAC address must consist of six octets
128 separated by single (:) or double (::) colons, for example:
129 mac=00:0c:01:02:03:04. The DUID value is a hexadecimal string: it
130 must be at least six octets long and must not be longer than 64
131 bytes and the length must be less than 128 hexadecimal digits, for
132 example: duid=0101010101010101010110111F14.
133 -d drop-time
135 Specify the time after which a request is treated as having been
136 lost. The value is given in seconds and may contain a fractional
137 component. The default is 1 second.
138 -e lease-type
140 Specifies the type of lease being requested from the server. It may
141 be one of the following:
142 address-only
144 Only regular addresses (v4 or v6) will be requested.
145 prefix-only
147 Only IPv6 prefixes will be requested.
148 address-and-prefix
150 Both IPv6 addresses and prefixes will be requested.
151 The -e prefix-only and -e address-and-prefix forms may not be used
153 with the -4 option.
154 -f renew-rate
156 Rate at which DHCPv4 or DHCPv6 renew requests are sent to a server.
157 This value is only valid when used in conjunction with the exchange
158 rate (given by -r rate). Furthermore the sum of this value and the
159 release-rate (given by -F rate) must be equal to or less than the
160 exchange rate.
161 -h
163 Print help and exit.
164 -i
166 Do only the initial part of the exchange: DISCOVER-OFFER if -4 is
167 selected, SOLICIT-ADVERTISE if -6 is chosen.
168 -i is incompatible with the following options: -1, -d, -D, -E, -S,
170 -I and -F. In addition, it cannot be used with multiple instances
171 of -O, -T and -X.
172 -l local-addr|interface
174 For DHCPv4 operation, specify the local hostname/address to use
175 when communicating with the server. By default, the interface
176 address through which traffic would normally be routed to the
177 server is used. For DHCPv6 operation, specify the name of the
178 network interface through which exchanges are initiated.
179 -L local-port
181 Specify the local port to use. This must be zero or a positive
182 integer up to 65535. A value of 0 (the default) allows perfdhcp to
183 choose its own port.
184 -M mac-list-file
186 A text file containing a list of MAC addresses, one per line. If
187 provided, a MAC address will be chosen randomly from this list for
188 every new exchange. In the DHCPv6 case, MAC addresses are used to
189 generate DUID-LLs. This parameter must not be used in conjunction
190 with the -b parameter.
191 -o code,hexstring
193 This forces perfdhcp to insert specified extra option (or options
194 if used several times) into packets being transmitted. The code
195 specifies option code and the hexstring is a hexadecimal string
196 that defines the content of the option. Care should be taken as
197 perfdhcp does not offer any kind of logic behind those options.
198 They're simply inserted into packets being sent as is. Be careful
199 not to insert options that are already inserted. For example, to
200 insert client class identifier (option code 60) with a string
201 'docsis', you can use -o 60,646f63736973. The -o may be used
202 multiple times. It is necessary to specify protocol family (either
203 -4 or -6) before using -o.
204 -P preload
206 Initiate preload exchanges back to back at startup. preload must
207 be 0 (the default) or a positive integer.
208 -r rate
210 Initiate rate DORA/SARR (or if -i is given, DO/SA) exchanges per
211 second. A periodic report is generated showing the number of
212 exchanges which were not completed, as well as the average response
213 latency. The program continues until interrupted, at which point a
214 final report is generated.
215 -R num-clients
217 Specify how many different clients are used. With a value of 1 (the
218 default), all requests seem to come from the same client.
219 num-clients must be a positive number.
220 -s seed
222 Specify the seed for randomization, making runs of perfdhcp
223 repeatable. seed is 0 or a positive integer. The value 0 means
224 that a seed is not used; this is the default.
225 -T template-file
227 The name of a file containing the template to use as a stream of
228 hexadecimal digits. This may be specified up to two times and
229 controls the contents of the packets sent (see the "TEMPLATES"
230 section above).
231 -v
233 Print the version of this program.
234 -W exit-wait-time
236 Specifies exit-wait-time parameter, that makes perfdhcp wait for
237 exit-wait-time us after an exit condition has been met to receive
238 all packets without sending any new packets. Expressed in
239 microseconds. If not specified, 0 is used (i.e. exit immediately
240 after exit conditions are met).
241 -w wrapped
243 Command to call with a single parameter of "start" or "stop" at the
244 beginning/end of the program.
245 -x diagnostic-selector
247 Include extended diagnostics in the output. diagnostic-selector is
248 a string of single-keywords specifying the operations for which
249 verbose output is desired. The selector key letters are:
250 a
252 Print the decoded command line arguments.
253 e
255 Print the exit reason.
256 i
258 Print rate processing details.
259 s
261 Print the first server-ID.
262 t
264 When finished, print timers of all successful exchanges.
265 T
267 When finished, print templates
268 DHCPv4-Only Options
270 The following options only apply for DHCPv4 (i.e. when -4 is given).
271 -B
273 Force broadcast handling.
274 DHCPv6-Only Options
276 The following options only apply for DHCPv6 (i.e. when -6 is given).
277 -c
279 Add a rapid commit option (exchanges will be SOLICIT-ADVERTISE).
280 -F release-rate
282 Rate at which IPv6 RELEASE requests are sent to a server. This
283 value is only valid when used in conjunction with the exchange rate
284 (given by -r rate). Furthermore the sum of this value and the
285 renew-rate (given by -f rate) must be equal to or less than the
286 exchange rate.
287 -A encapsulation-level
289 Specifies that relayed traffic must be generated. The argument
290 specifies the level of encapsulation, i.e. how many relay agents
291 are simulated. Currently the only supported encapsulation-level
292 value is 1, which means that the generated traffic is an equivalent
293 of the traffic passing through a single relay agent.
294 Template-Related Options
296 The following options may only be used in conjunction with -T and
297 control how perfdhcp modifies the template. The options may be
298 specified multiple times on the command line; each occurrence affects
299 the corresponding template file (see "TEMPLATES" above).
300 -E time-offset
302 Offset of the (DHCPv4) secs field or (DHCPv6) elapsed-time option
303 in the (second i.e. REQUEST) template and must be 0 or a positive
304 integer: a value of 0 disables this.
305 -I ip-offset
307 Offset of the (DHCPv4) IP address in the requested-IP option /
308 (DHCPv6) IA_NA option in the (second/request) template.
309 -O random-offset
311 Offset of the last octet to randomize in the template.
312 random-offset must be an integer greater than 3. The -T switch must
313 be given to use this option.
314 -S srvid-offset
316 Offset of the server-ID option in the (second/request) template.
317 srvid-offset must be a positive integer, and the switch can only be
318 used when the template option (-T) is also given.
319 -X xid-offset
321 Offset of the transaction ID (xid) in the template. xid-offset
322 must be a positive integer, and the switch can only be used when
323 the template option (-T) is also given.
324 Options Controlling a Test
326 -D max-drop
327 Abort the test immediately if max-drop requests have been dropped.
328 Use -D 0 to abort if even a single request has been dropped.
329 max-drop must be a positive integer. If max-drop includes the
330 suffix '%', it specifies a maximum percentage of requests that may
331 be dropped before abort. In this case, testing of the threshold
332 begins after 10 requests have been expected to be received.
333 -n num-requests
335 Initiate num-request transactions. No report is generated until all
336 transactions have been initiated/waited-for, after which a report
337 is generated and the program terminates.
338 -p test-period
340 Send requests for test-period, which is specified in the same
341 manner as -d. This can be used as an alternative to -n, or both
342 options can be given, in which case the testing is completed when
343 either limit is reached.
344 -t interval
346 Sets the delay (in seconds) between two successive reports.
347 Arguments
349 server
350 Server to test, specified as an IP address. In the DHCPv6 case, the
351 special name 'all' can be used to refer to
352 All_DHCP_Relay_Agents_and_Servers (the multicast address
353 FF02::1:2), or the special name 'servers' to refer to
354 All_DHCP_Servers (the multicast address FF05::1:3). The server is
355 mandatory except where the -l option is given to specify an
356 interface, in which case it defaults to 'all'.
357
359 perfdhcp can report the following errors in the packet exchange:
360 tooshort
362 A message was received that was too short.
363 orphans
365 Received a message which doesn't match one sent to the server (i.e.
366 it is a duplicate message, a message that has arrived after an
367 excessive delay, or one that is just not recognized).
368 locallimit
370 Reached local system limits when sending a message.
371
373 perfdhcp can exit with one of the following status codes:
374 0
376 Success.
377 1
379 General error.
380 2
382 Error in command-line arguments.
383 3
385 No general failures in operation, but one or more exchanges were
386 unsuccessful.
387
389 There are two mailing lists available for Kea project. kea-users
390 (kea-users at lists.isc.org) is intended for Kea users, while kea-dev
391 (kea-dev at lists.isc.org) is intended for Kea developers, prospective
392 contributors and other advanced users. Both lists are available at
393 http://lists.isc.org. The community provides best effort type of
394 support on both of those lists.
395 ISC provides professional support for Kea services. See
397 https://www.isc.org/kea/ for details.
398
400 The perfdhcp tool was initially coded in October 2011 by John DuBois,
401 Francis Dupont and Marcin Siodelski of ISC. Kea 1.0.0 that included
402 perfdhcp was released in December 2015.
403
405 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8), kea-
406 admin(8), kea-netconf(8), keactrl(8), kea-lfc(8), Kea Administrator's
407 Guide.
408
410 The Kea software has been written by a number of engineers working
411 for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas
412 Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn
413 Routhier. That list is roughly in the chronological order in which
414 the authors made their first contribution. For a complete list of
415 authors and contributors, see AUTHORS file.
416
418 Copyright © 2016-2018 Internet Systems Consortium, Inc. ("ISC")
419ISC Kea 1.5.0 Dec 14, 2018 PERFDHCP(8)