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 [-p test-period] [-P preload] [-r rate] [-R num-clients]
16 [-s seed] [-S srvid-offset] [-t report] [-T template-file]
17 [-v] [-W wrapped] [-x diagnostic-selector] [-X xid-offset]
18 [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 -P preload
193 Initiate preload exchanges back to back at startup. preload must
194 be 0 (the default) or a positive integer.
195 -r rate
197 Initiate rate DORA/SARR (or if -i is given, DO/SA) exchanges per
198 second. A periodic report is generated showing the number of
199 exchanges which were not completed, as well as the average response
200 latency. The program continues until interrupted, at which point a
201 final report is generated.
202 -R num-clients
204 Specify how many different clients are used. With a value of 1 (the
205 default), all requests seem to come from the same client.
206 num-clients must be a positive number.
207 -s seed
209 Specify the seed for randomization, making runs of perfdhcp
210 repeatable. seed is 0 or a positive integer. The value 0 means
211 that a seed is not used; this is the default.
212 -T template-file
214 The name of a file containing the template to use as a stream of
215 hexadecimal digits. This may be specified up to two times and
216 controls the contents of the packets sent (see the "TEMPLATES"
217 section above).
218 -v
220 Print the version of this program.
221 -w wrapped
223 Command to call with a single parameter of "start" or "stop" at the
224 beginning/end of the program.
225 -x diagnostic-selector
227 Include extended diagnostics in the output. diagnostic-selector is
228 a string of single-keywords specifying the operations for which
229 verbose output is desired. The selector key letters are:
230 a
232 Print the decoded command line arguments.
233 e
235 Print the exit reason.
236 i
238 Print rate processing details.
239 s
241 Print the first server-ID.
242 t
244 When finished, print timers of all successful exchanges.
245 T
247 When finished, print templates
248 DHCPv4-Only Options
250 The following options only apply for DHCPv4 (i.e. when -4 is given).
251 -B
253 Force broadcast handling.
254 DHCPv6-Only Options
256 The following options only apply for DHCPv6 (i.e. when -6 is given).
257 -c
259 Add a rapid commit option (exchanges will be SOLICIT-ADVERTISE).
260 -F release-rate
262 Rate at which IPv6 RELEASE requests are sent to a server. This
263 value is only valid when used in conjunction with the exchange rate
264 (given by -r rate). Furthermore the sum of this value and the
265 renew-rate (given by -f rate) must be equal to or less than the
266 exchange rate.
267 -A encapsulation-level
269 Specifies that relayed traffic must be generated. The argument
270 specifies the level of encapsulation, i.e. how many relay agents
271 are simulated. Currently the only supported encapsulation-level
272 value is 1, which means that the generated traffic is an equivalent
273 of the traffic passing through a single relay agent.
274 Template-Related Options
276 The following options may only be used in conjunction with -T and
277 control how perfdhcp modifies the template. The options may be
278 specified multiple times on the command line; each occurrence affects
279 the corresponding template file (see "TEMPLATES" above).
280 -E time-offset
282 Offset of the (DHCPv4) secs field or (DHCPv6) elapsed-time option
283 in the (second i.e. REQUEST) template and must be 0 or a positive
284 integer: a value of 0 disables this.
285 -I ip-offset
287 Offset of the (DHCPv4) IP address in the requested-IP option /
288 (DHCPv6) IA_NA option in the (second/request) template.
289 -O random-offset
291 Offset of the last octet to randomize in the template.
292 random-offset must be an integer greater than 3. The -T switch must
293 be given to use this option.
294 -S srvid-offset
296 Offset of the server-ID option in the (second/request) template.
297 srvid-offset must be a positive integer, and the switch can only be
298 used when the template option (-T) is also given.
299 -X xid-offset
301 Offset of the transaction ID (xid) in the template. xid-offset
302 must be a positive integer, and the switch can only be used when
303 the template option (-T) is also given.
304 Options Controlling a Test
306 The following options may only be used in conjunction with -r and
307 control both the length of the test and the frequency of reports.
308 -D max-drop
310 Abort the test if more than max-drop requests have been dropped.
311 Use -D 0 to abort if even a single request has been dropped. If
312 max-drop includes the suffix '%', it specifies a maximum percentage
313 of requests that may be dropped before abort. In this case, testing
314 of the threshold begins after 10 requests have been expected to be
315 received.
316 -n num-requests
318 Initiate num-request transactions. No report is generated until all
319 transactions have been initiated/waited-for, after which a report
320 is generated and the program terminates.
321 -p test-period
323 Send requests for test-period, which is specified in the same
324 manner as -d. This can be used as an alternative to -n, or both
325 options can be given, in which case the testing is completed when
326 either limit is reached.
327 -t interval
329 Sets the delay (in seconds) between two successive reports.
330 Arguments
332 server
333 Server to test, specified as an IP address. In the DHCPv6 case, the
334 special name 'all' can be used to refer to
335 All_DHCP_Relay_Agents_and_Servers (the multicast address
336 FF02::1:2), or the special name 'servers' to refer to
337 All_DHCP_Servers (the multicast address FF05::1:3). The server is
338 mandatory except where the -l option is given to specify an
339 interface, in which case it defaults to 'all'.
340
342 perfdhcp can report the following errors in the packet exchange:
343 tooshort
345 A message was received that was too short.
346 orphans
348 Received a message which doesn't match one sent to the server (i.e.
349 it is a duplicate message, a message that has arrived after an
350 excessive delay, or one that is just not recognized).
351 locallimit
353 Reached local system limits when sending a message.
354
356 perfdhcp can exit with one of the following status codes:
357 0
359 Success.
360 1
362 General error.
363 2
365 Error in command-line arguments.
366 3
368 No general failures in operation, but one or more exchanges were
369 unsuccessful.
370
372 There are two mailing lists available for Kea project. kea-users
373 (kea-users at lists.isc.org) is intended for Kea users, while kea-dev
374 (kea-dev at lists.isc.org) is intended for Kea developers, prospective
375 contributors and other advanced users. Both lists are available at
376 http://lists.isc.org. The community provides best effort type of
377 support on both of those lists.
378 ISC provides professional support for Kea services. See
380 https://www.isc.org/kea/ for details.
381
383 The perfdhcp tool was initially coded in October 2011 by John DuBois,
384 Francis Dupont and Marcin Siodelski of ISC. Kea 1.0.0 that included
385 perfdhcp was released in December 2015.
386
388 kea-dhcp4(8), kea-dhcp6(8), kea-dhcp-ddns(8), kea-ctrl-agent(8), kea-
389 admin(8), keactrl(8), kea-lfc(8), Kea Administrator's Guide.
390
392 The Kea software has been written by a number of engineers working for
393 ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas
394 Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn
395 Routhier. That list is roughly in the chronological order in which the
396 authors made their first contribution. For a complete list of authors
397 and contributors, see AUTHORS file.
398
400 Copyright © 2016-2017 Internet Systems Consortium, Inc. ("ISC")
401ISC Kea 1.3.0 Oct. 27, 2017 PERFDHCP(8)