perfdhcp.8.rst 18 KB
Newer Older
1
..
2
   Copyright (C) 2019 Internet Systems Consortium, Inc. ("ISC")
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

   This Source Code Form is subject to the terms of the Mozilla Public
   License, v. 2.0. If a copy of the MPL was not distributed with this
   file, You can obtain one at http://mozilla.org/MPL/2.0/.

   See the COPYRIGHT file distributed with this work for additional
   information regarding copyright ownership.


perfdhcp - DHCP benchmarking tool
---------------------------------

Synopsis
~~~~~~~~

18
:program:`perfdhcp` [**-1**] [**-4**|**-6**] [**-A** encapsulation-level] [**-b** base] [**-B**] [**-c**] [**-d** drop-time] [**-D** max-drop] [-e lease-type] [**-E** time-offset] [**-f** renew-rate] [**-F** release-rate] [**-g** thread-mode] [**-h**] [**-i**] [**-I** ip-offset] [**-l** local-address|interface] [**-L** local-port] [**-M** mac-list-file] [**-n** num-request] [**-N** remote-port] [**-O** random-offset] [**-o** code,hexstring] [**-p** test-period] [**-P** preload] [**-r** rate] [**-R** num-clients] [**-s** seed] [**-S** srvid-offset] [**--scenario** name] [**-t** report] [**-T** template-file] [**-v**] [**-W** exit-wait-time] [**-w** script_name] [**-x** diagnostic-selector] [**-X** xid-offset] [server]
19
20
21

Description
~~~~~~~~~~~
22
23
24
25
26
27
28

``perfdhcp`` is a DHCP benchmarking tool. It provides a way of measuring
the performance of DHCP servers by generating large amounts of traffic
from simulated multiple clients. It is able to test both IPv4 and IPv6
servers, and provides statistics concerning response times and the
number of requests that are dropped.

29
By default (basic scenario) tests are run using the full four-packet exchange sequence
30
31
(DORA for DHCPv4, SARR for DHCPv6). An option is provided to run tests
using the initial two-packet exchange (DO and SA) instead. It is also
32
possible to configure ``perfdhcp`` to send DHCPv6 RENEW and RELEASE messages
33
34
at a specified rate in parallel with the DHCPv6 four-way exchanges.

35
36
37
38
39
40
41
Second scenario is called avalanche, which is selected by ``--scenario avalanche``.
It first sends as many Discovery or Solicit messages as request in -R option then
back off mechanism is used for each simulated client until all requests are
answered. It will generate report when all clients will got their
addresses or when it will be manually stopped. Option ``-p`` is ignored in avalanche
scenario.

42
When running a performance test, ``perfdhcp`` will exchange packets with
43
the server under test as fast as possible unless the ``-r`` parameter is used to
44
45
46
47
48
limit the request rate. The length of the test can be limited by setting
a threshold on any or all of the number of requests made by
``perfdhcp``, the elapsed time, or the number of requests dropped by the
server.

49
50
Templates
~~~~~~~~~
51
52
53
54
55

To allow the contents of packets sent to the server to be customized,
``perfdhcp`` allows the specification of template files that determine
the contents of the packets. For example, the customized packet may
contain a DHCPv6 ORO to request a set of options to be returned by the
56
57
server, or it may contain the Client FQDN option to request that the server
perform DNS updates. This may be used to discover performance
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
bottlenecks for different server configurations (e.g. DDNS enabled or
disabled).

Up to two template files can be specified on the command line, each file
representing the contents of a particular type of packet, the type being
determined by the test being carried out. For example, if testing
DHCPv6:

-  With no template files specified on the command line, ``perfdhcp``
   will generate both SOLICIT and REQUEST packets.

-  With one template file specified, that file will be used as the
   pattern for SOLICIT packets: ``perfdhcp`` will generate the REQUEST
   packets.

-  With two template files given on the command line, the first will be
   used as the pattern for SOLICIT packets, the second as the pattern
   for REQUEST packets.

(Similar determination applies to DHCPv4's DISCOVER and REQUEST
packets.)

The template file holds the DHCP packet represented as a stream of ASCII
hexadecimal digits and it excludes any IP/UDP stack headers. The
template file must not contain any characters other than hexadecimal
83
84
85
digits and spaces. Spaces are discarded when the template file is parsed;
in the file, '12B4' is the same as '12 B4' which is the same as '1 2
B 4'.
86

87
The template files should be used in conjunction with the command-line
88
89
90
parameters which specify offsets of the data fields being modified in
outbound packets. For example, the ``-E time-offset`` switch specifies
the offset of the DHCPv6 Elapsed Time option in the packet template.
91
92
If the offset is specified, ``perfdhcp`` will inject the current elapsed-time
value into this field before sending the packet to the server.
93

94
95
In many scenarios, ``perfdhcp`` needs to simulate multiple clients,
each having a unique client identifier. Since packets for each client are
96
97
98
99
100
101
102
generated from the same template file, it is necessary to randomize the
client identifier (or HW address in DHCPv4) in the packet created from
it. The ``-O random-offset`` option allows specification of the offset in
the template where randomization should be performed. It is important to
note that this offset points to the end (not the beginning) of the
client identifier (or HW address field). The number of bytes being
randomized depends on the number of simulated clients. If the number of
103
simulated clients is between 1 and 255, only one byte (to which the
104
105
randomization offset points) will be randomized. If the number of
simulated clients is between 256 and 65535, two bytes will be
106
107
randomized. Note that the last two bytes of the client identifier will be
randomized in this case: the byte which the randomization offset parameter
108
109
points to, and the one which precedes it (random-offset - 1). If the
number of simulated clients exceeds 65535, three bytes will be
110
randomized, and so on.
111

112
Templates may currently be used to generate packets being sent to the
113
114
115
116
server in 4-way exchanges, i.e. SOLICIT, REQUEST (DHCPv6) and DISCOVER,
REQUEST (DHCPv4). They cannot be used when RENEW or RELEASE packets are
being sent.

117
118
Options
~~~~~~~
119
120

``-1``
121
   Takes the server-ID option from the first received message.
122
123

``-4``
124
   Establishes DHCPv4 operation; this is the default. It is incompatible with the
125
126
127
   ``-6`` option.

``-6``
128
   Establishes DHCPv6 operation. This is incompatible with the ``-4`` option.
129
130

``-b basetype=value``
131
   Indicates the base MAC or DUID used to simulate different clients. The basetype
132
133
134
135
   may be "mac" or "duid". (The keyword "ether" may alternatively used
   for MAC.) The ``-b`` option can be specified multiple times. The MAC
   address must consist of six octets separated by single (:) or double
   (::) colons, for example: mac=00:0c:01:02:03:04. The DUID value is a
136
137
   hexadecimal string; it must be at least six octets long and not
   longer than 64 bytes, and the length must be less than 128
138
139
140
   hexadecimal digits, for example: duid=0101010101010101010110111F14.

``-d drop-time``
141
   Specifies the time after which a request is treated as having been
142
143
144
145
146
147
148
   lost. The value is given in seconds and may contain a fractional
   component. The default is 1 second.

``-e lease-type``
   Specifies the type of lease being requested from the server. It may
   be one of the following:

149
   **address-only**
150
151
      Only regular addresses (v4 or v6) will be requested.

152
   **prefix-only**
153
154
      Only IPv6 prefixes will be requested.

155
   **address-and-prefix**
156
157
158
159
160
161
      Both IPv6 addresses and prefixes will be requested.

   The ``-e prefix-only`` and ``-e address-and-prefix`` forms may not be used
   with the ``-4`` option.

``-f renew-rate``
162
   Specifies the rate at which DHCPv4 or DHCPv6 renew requests are sent to a server.
163
   This value is only valid when used in conjunction with the exchange
164
   rate (given by ``-r rate``). Furthermore, the sum of this value and
165
166
167
168
   the release-rate (given by ``-F rate``) must be equal to or less than the
   exchange rate.

``-g thread-mode``
169
170
171
172
173
174
   Allows selection of thread-mode, which can be either 'single' or 'multi'. In multi-thread mode
   packets are received in a separate thread, which allows better
   utilisation of CPUs. In a single-CPU system it is better to run in one
   thread to avoid threads blocking each other. If more than one CPU is
   present in the system, multi-thread mode is the default; otherwise
   single-thread is the default.
175
176

``-h``
177
   Prints help and exits.
178
179

``-i``
180
   Performs only the initial part of the exchange: DISCOVER-OFFER if ``-4`` is
181
182
183
184
185
186
187
   selected, SOLICIT-ADVERTISE if ``-6`` is chosen.

   ``-i`` is incompatible with the following options: ``-1``, ``-d``,
   ``-D``, ``-E``, ``-S``, ``-I`` and ``-F``. In addition, it cannot be
   used with multiple instances of ``-O``, ``-T`` and ``-X``.

``-l local-addr|interface``
188
   For DHCPv4 operation, specifies the local hostname/address to use when
189
190
   communicating with the server. By default, the interface address
   through which traffic would normally be routed to the server is used.
191
   For DHCPv6 operation, specifies the name of the network interface
192
193
194
   through which exchanges are initiated.

``-L local-port``
195
   Specifies the local port to use. This must be zero or a positive
196
197
198
199
   integer up to 65535. A value of 0 (the default) allows ``perfdhcp``
   to choose its own port.

``-M mac-list-file``
200
   Specifies a text file containing a list of MAC addresses, one per line. If
201
   provided, a MAC address will be chosen randomly from this list for
202
   every new exchange. In DHCPv6, MAC addresses are used to
203
204
205
206
   generate DUID-LLs. This parameter must not be used in conjunction
   with the -b parameter.

``-N remote-port``
207
   Specifies the remote port to use. This must be zero or a positive
208
209
210
211
   integer up to 65535. A value of 0 (the default) allows ``perfdhcp``
   to choose the standard service port.

``-o code,hexstring``
212
   Forces ``perfdhcp`` to insert the specified extra option (or options if
213
   used several times) into packets being transmitted. The code
214
215
216
217
   specifies the option code and the hexstring is a hexadecimal string that
   defines the content of the option. Care should be taken as ``perfdhcp``
   does not offer any kind of logic behind those options; they are simply
   inserted into packets and sent as is. Be careful not to duplicate
218
   options that are already inserted. For example, to insert client
219
   class identifier (option code 60) with a string 'docsis', use
220
   -o 60,646f63736973. The ``-o`` may be used multiple times. It is
221
   necessary to specify the protocol family (either ``-4`` or ``-6``) before
222
223
224
   using ``-o``.

``-P preload``
225
   Initiates preload exchanges back-to-back at startup. Must be 0
226
227
228
   (the default) or a positive integer.

``-r rate``
229
   Initiates the rate of DORA/SARR (or if ``-i`` is given, DO/SA) exchanges per
230
231
232
233
234
235
   second. A periodic report is generated showing the number of
   exchanges which were not completed, as well as the average response
   latency. The program continues until interrupted, at which point a
   final report is generated.

``-R num-clients``
236
237
238
   Specifies how many different clients are used. With a value of 1 (the
   default), all requests seem to come from the same client.
   Must be a positive number.
239
240

``-s seed``
241
242
   Specifies the seed for randomization, making runs of ``perfdhcp``
   repeatable. This must be 0 or a positive integer. The value 0 means that a
243
244
   seed is not used; this is the default.

245
246
247
``--scenario name``
   Specifies type of the scenario, can be **basic** (default) or **avalanche**.

248
``-T template-file``
249
   Specifies a file containing the template to use as a stream of
250
   hexadecimal digits. This may be specified up to two times and
251
   controls the contents of the packets sent (see the "Templates"
252
253
254
   section above).

``-v``
255
   Prints the version of this program.
256
257

``-W exit-wait-time``
258
259
   Specifies the exit-wait-time parameter, which causes ``perfdhcp`` to wait for
   exit-wait-time after an exit condition has been met, to receive all
260
261
262
263
   packets without sending any new packets. Expressed in microseconds.
   If not specified, 0 is used (i.e. exit immediately after exit
   conditions are met).

264
265
266
267
``-w script_name``
   Specifies the name of the script to be run before/after ``perfdhcp``.
   When called, the script is passed a single parameter, either "start" or
   "stop", indicating whether it is being called before or after ``perfdhcp``.
268
269

``-x diagnostic-selector``
270
271
   Includes extended diagnostics in the output. This is a
   string of single keywords specifying the operations for which verbose
272
273
   output is desired. The selector key letters are:

274
275
   **a**
      Prints the decoded command line arguments.
276

277
278
   **e**
      Prints the exit reason.
279

280
281
   **i**
      Prints the rate processing details.
282

283
284
   **s**
      Prints the first server-ID.
285

286
287
   **t**
      When finished, prints timers of all successful exchanges.
288

289
290
   **T**
      When finished, prints templates.
291
292

DHCPv4-Only Options
Michal Nowikowski's avatar
Michal Nowikowski committed
293
~~~~~~~~~~~~~~~~~~~
294
295
296
297

The following options only apply for DHCPv4 (i.e. when ``-4`` is given).

``-B``
298
   Forces broadcast handling.
299
300

DHCPv6-Only Options
Michal Nowikowski's avatar
Michal Nowikowski committed
301
~~~~~~~~~~~~~~~~~~~
302
303
304
305

The following options only apply for DHCPv6 (i.e. when ``-6`` is given).

``-c``
306
   Adds a rapid-commit option (exchanges will be SOLICIT-ADVERTISE).
307
308

``-F release-rate``
309
   Specifies the rate at which IPv6 RELEASE requests are sent to a server. This value
310
   is only valid when used in conjunction with the exchange rate (given
311
   by ``-r rate``). Furthermore, the sum of this value and the renew-rate
312
   (given by ``-f rate``) must be equal to or less than the exchange
313
   rate value.
314
315
316
317
318

``-A encapsulation-level``
   Specifies that relayed traffic must be generated. The argument
   specifies the level of encapsulation, i.e. how many relay agents are
   simulated. Currently the only supported encapsulation-level value is
319
   1, which means that the generated traffic is equivalent to the amount of
320
321
322
   traffic passing through a single relay agent.

Template-Related Options
Michal Nowikowski's avatar
Michal Nowikowski committed
323
~~~~~~~~~~~~~~~~~~~~~~~~
324
325
326
327

The following options may only be used in conjunction with ``-T`` and
control how ``perfdhcp`` modifies the template. The options may be
specified multiple times on the command line; each occurrence affects
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
the corresponding template file (see "Templates" above).

``-E time-offset``
   Specifies the offset of the secs field (DHCPv4) or elapsed-time option (DHCPv6) in the
   second (i.e. REQUEST) template; must be 0 or a positive integer. A
   value of 0 disables this.

``-I ip-offset``
   Specifies the offset of the IP address (DHCPv4) in the requested-IP
   option or IA_NA option (DHCPv6) in the second (REQUEST) template.

``-O random-offset``
   Specifies the offset of the last octet to randomize in the template. This
   must be an integer greater than 3. The ``-T`` switch must be given to
   use this option.

``-S srvid-offset``
   Specifies the offset of the server-ID option in the second (REQUEST) template.
   This must be a positive integer, and the switch can only be used
   when the template option (``-T``) is also given.

``-X xid-offset``
   Specifies the offset of the transaction ID (xid) in the template. This must be a
   positive integer, and the switch can only be used when the template
   option (``-T``) is also given.
353
354

Options Controlling a Test
Michal Nowikowski's avatar
Michal Nowikowski committed
355
~~~~~~~~~~~~~~~~~~~~~~~~~~
356
357

``-D max-drop``
358
   Aborts the test immediately if **max-drop** requests have been dropped.
359
   Use ``-D 0`` to abort if even a single request has
360
   been dropped. **max-drop** must be a positive integer. If **max-drop**
361
362
363
364
365
366
   includes the suffix '%', it specifies a maximum percentage of
   requests that may be dropped before abort. In this case, testing of
   the threshold begins after 10 requests have been expected to be
   received.

``-n num-requests``
367
   Initiates **num-request** transactions. No report is generated until all
368
369
370
371
   transactions have been initiated/waited-for, after which a report is
   generated and the program terminates.

``-p test-period``
372
373
   Sends requests for **test-period**, which is specified in the same manner
   as ``-d``. This can be used as an alternative to ``-n`` or both
374
375
376
377
378
379
380
   options can be given, in which case the testing is completed when
   either limit is reached.

``-t interval``
   Sets the delay (in seconds) between two successive reports.

Arguments
Michal Nowikowski's avatar
Michal Nowikowski committed
381
~~~~~~~~~
382
383

server
384
   Indicates the server to test, specified as an IP address. In the DHCPv6 case, the
385
386
387
388
389
390
391
   special name 'all' can be used to refer to
   All_DHCP_Relay_Agents_and_Servers (the multicast address FF02::1:2),
   or the special name 'servers' to refer to All_DHCP_Servers (the
   multicast address FF05::1:3). The server is mandatory except where
   the ``-l`` option is given to specify an interface, in which case it
   defaults to 'all'.

392
393
Errors
~~~~~~
394
395
396
397
398
399
400

``perfdhcp`` can report the following errors in the packet exchange:

tooshort
   A message was received that was too short.

orphans
401
   A message was received which does not match one sent to the server (i.e.
402
403
404
405
   it is a duplicate message, a message that has arrived after an
   excessive delay, or one that is just not recognized).

locallimit
406
   Local system limits have been reached when sending a message.
407

408
409
Exit Status
~~~~~~~~~~~
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425

``perfdhcp`` can exit with one of the following status codes:

0
   Success.

1
   General error.

2
   Error in command-line arguments.

3
   No general failures in operation, but one or more exchanges were
   unsuccessful.

426
427
Mailing Lists and Support
~~~~~~~~~~~~~~~~~~~~~~~~~
428

429
430
There are two public mailing lists available for the Kea project. **kea-users**
(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev**
431
(kea-dev at lists.isc.org) is intended for Kea developers, prospective
432
433
contributors, and other advanced users. Both lists are available at
https://lists.isc.org. The community provides best-effort support
434
435
436
437
438
on both of those lists.

ISC provides professional support for Kea services. See
https://www.isc.org/kea/ for details.

439
440
History
~~~~~~~
441
442

The ``perfdhcp`` tool was initially coded in October 2011 by John
443
444
DuBois, Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which
included ``perfdhcp``, was released in December 2015.
445

446
447
See Also
~~~~~~~~
448

449
450
451
:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, :manpage:`kea-dhcp-ddns(8)`,
:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`kea-netconf(8)`,
:manpage:`keactrl(8)`, :manpage:`kea-lfc(8)`, Kea Administrator Reference Manual.