1PERFDHCP(8)                           Kea                          PERFDHCP(8)
2
3
4

NAME

6       perfdhcp - DHCP benchmarking tool
7

SYNOPSIS

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

DESCRIPTION

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
27       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
34       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

TEMPLATES

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
51       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
56       ·   With no template files specified on the command line, perfdhcp will
57           generate both SOLICIT and REQUEST packets.
58
59       ·   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
63       ·   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
67       (Similar determination applies to DHCPv4's DISCOVER and REQUEST
68       packets.)
69
70       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
77       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
84       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
102       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

OPTIONS

108       -1
109           Take the server-ID option from the first received message.
110
111       -4
112           DHCPv4 operation; this is the default. It is incompatible with the
113           -6 option.
114
115       -6
116           DHCPv6 operation. This is incompatible with the -4 option.
117
118       -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
123       -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
134       -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
139       -e lease-type
140           Specifies the type of lease being requested from the server. It may
141           be one of the following:
142
143           address-only
144               Only regular addresses (v4 or v6) will be requested.
145
146           prefix-only
147               Only IPv6 prefixes will be requested.
148
149           address-and-prefix
150               Both IPv6 addresses and prefixes will be requested.
151
152           The -e prefix-only and -e address-and-prefix forms may not be used
153           with the -4 option.
154
155       -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
162       -h
163           Print help and exit.
164
165       -i
166           Do only the initial part of the exchange: DISCOVER-OFFER if -4 is
167           selected, SOLICIT-ADVERTISE if -6 is chosen.
168
169           -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
173       -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
180       -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
185       -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
192       -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
205       -P preload
206           Initiate preload exchanges back to back at startup.  preload must
207           be 0 (the default) or a positive integer.
208
209       -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
216       -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
221       -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
226       -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
232       -v
233           Print the version of this program.
234
235       -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
242       -w wrapped
243           Command to call with a single parameter of "start" or "stop" at the
244           beginning/end of the program.
245
246       -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
251           a
252               Print the decoded command line arguments.
253
254           e
255               Print the exit reason.
256
257           i
258               Print rate processing details.
259
260           s
261               Print the first server-ID.
262
263           t
264               When finished, print timers of all successful exchanges.
265
266           T
267               When finished, print templates
268
269   DHCPv4-Only Options
270       The following options only apply for DHCPv4 (i.e. when -4 is given).
271
272       -B
273           Force broadcast handling.
274
275   DHCPv6-Only Options
276       The following options only apply for DHCPv6 (i.e. when -6 is given).
277
278       -c
279           Add a rapid commit option (exchanges will be SOLICIT-ADVERTISE).
280
281       -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
288       -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
295   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
301       -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
306       -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
310       -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
315       -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
320       -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
325   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
334       -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
339       -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
345       -t interval
346           Sets the delay (in seconds) between two successive reports.
347
348   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

ERRORS

359       perfdhcp can report the following errors in the packet exchange:
360
361       tooshort
362           A message was received that was too short.
363
364       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
369       locallimit
370           Reached local system limits when sending a message.
371

EXIT STATUS

373       perfdhcp can exit with one of the following status codes:
374
375       0
376           Success.
377
378       1
379           General error.
380
381       2
382           Error in command-line arguments.
383
384       3
385           No general failures in operation, but one or more exchanges were
386           unsuccessful.
387

MAILING LISTS AND SUPPORT

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
396       ISC provides professional support for Kea services. See
397       https://www.isc.org/kea/ for details.
398

HISTORY

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

SEE ALSO

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

AUTHOR

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")
419
420
421
422ISC Kea 1.5.0                    Dec 14, 2018                      PERFDHCP(8)
Impressum