perfdhcp.xml 40.7 KB
Newer Older
1 2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
Francis Dupont's avatar
Francis Dupont committed
3
               [<!ENTITY mdash "&#8212;">]>
4
<!--
5
 - Copyright (C) 2014-2016 Internet Systems Consortium, Inc. ("ISC")
6
 -
7 8 9
 - 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/.
10 11
-->

12
<refentry>
13

14
    <refentryinfo>
15 16 17 18 19 20 21 22 23 24 25 26 27
      <productname>ISC Kea</productname>
      <date>Sep. 28, 2016</date>
      <edition>1.1.0</edition>
      <author>
        <contrib>The Kea software has been written by a number of
        engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
        Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
        Wlodek Wencel and Shawn Routhier.  That list is roughly in the
        chronological order in which the authors made their first
        contribution. For a complete list of authors and
        contributors, see AUTHORS file.</contrib>
        <orgname>Internet Systems Consortium, Inc.</orgname>
      </author>
28 29 30 31
    </refentryinfo>

    <refmeta>
        <refentrytitle>perfdhcp</refentrytitle>
32
        <manvolnum>8</manvolnum>
33
        <refmiscinfo class="manual">Kea</refmiscinfo>
34 35 36 37 38 39 40 41 42
    </refmeta>

    <refnamediv>
        <refname>perfdhcp</refname>
        <refpurpose>DHCP benchmarking tool</refpurpose>
    </refnamediv>

    <docinfo>
        <copyright>
43
            <year>2016</year>
44 45 46 47 48 49 50 51 52
            <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
        </copyright>
    </docinfo>

    <refsynopsisdiv>
        <cmdsynopsis>
            <command>perfdhcp</command>
            <arg><option>-1</option></arg>
            <arg><option>-4|-6</option></arg>
53
            <arg><option>-A <replaceable class="parameter">encapsulation-level</replaceable></option></arg>
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
            <arg><option>-a <replaceable class="parameter">aggressivity</replaceable></option></arg>
            <arg><option>-b <replaceable class="parameter">base</replaceable></option></arg>
            <arg><option>-B</option></arg>
            <arg><option>-c</option></arg>
            <arg><option>-d <replaceable class="parameter">drop-time</replaceable></option></arg>
            <arg><option>-D <replaceable class="parameter">max-drop</replaceable></option></arg>
            <arg><option>-e <replaceable class="parameter">lease-type</replaceable></option></arg>
            <arg><option>-E <replaceable class="parameter">time-offset</replaceable></option></arg>
            <arg><option>-f <replaceable class="parameter">renew-rate</replaceable></option></arg>
            <arg><option>-F <replaceable class="parameter">release-rate</replaceable></option></arg>
            <arg><option>-h</option></arg>
            <arg><option>-i</option></arg>
            <arg><option>-I <replaceable class="parameter">ip-offset</replaceable></option></arg>
            <arg><option>-l <replaceable class="parameter">local-address|interface</replaceable></option></arg>
            <arg><option>-L <replaceable class="parameter">local-port</replaceable></option></arg>
69
            <arg><option>-M <replaceable class="parameter">mac-list-file</replaceable></option></arg>
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
            <arg><option>-n <replaceable class="parameter">num-request</replaceable></option></arg>
            <arg><option>-O <replaceable class="parameter">random-offset</replaceable></option></arg>
            <arg><option>-p <replaceable class="parameter">test-period</replaceable></option></arg>
            <arg><option>-P <replaceable class="parameter">preload</replaceable></option></arg>
            <arg><option>-r <replaceable class="parameter">rate</replaceable></option></arg>
            <arg><option>-R <replaceable class="parameter">num-clients</replaceable></option></arg>
            <arg><option>-s <replaceable class="parameter">seed</replaceable></option></arg>
            <arg><option>-S <replaceable class="parameter">srvid-offset</replaceable></option></arg>
            <arg><option>-t <replaceable class="parameter">report</replaceable></option></arg>
            <arg><option>-T <replaceable class="parameter">template-file</replaceable></option></arg>
            <arg><option>-v</option></arg>
            <arg><option>-W <replaceable class="parameter">wrapped</replaceable></option></arg>
            <arg><option>-x <replaceable class="parameter">diagnostic-selector</replaceable></option></arg>
            <arg><option>-X <replaceable class="parameter">xid-offset</replaceable></option></arg>
            <arg>server</arg>
        </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
        <title>DESCRIPTION</title>
        <para>
91 92 93 94 95 96
            <command>perfdhcp</command> 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.
97 98 99
        </para>

        <para>
100 101 102 103 104 105
            By default, tests are run using the full four-packet exchange
            sequence (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 possible to configure perfdhcp to
            send DHCPv6 RENEW and RELEASE messages at a specified rate in
            parallel with the DHCPv6 four-way exchanges.
106 107 108
        </para>

        <para>
109 110 111 112 113 114 115
            When running a performance test, <command>perfdhcp</command>
            will exchange packets with the server under test as fast as
            possible unless the <option>-r</option> is given to 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
            <command>perfdhcp</command>, the elapsed time, or the number of
            requests dropped by the server.
116 117 118 119 120 121
        </para>
    </refsect1>

    <refsect1>
        <title>TEMPLATES</title>
        <para>
122 123 124 125 126 127 128 129
            To allow the contents of packets sent to the server to be
            customized, <command>perfdhcp</command> 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 server, or it may
            contain the Client FQDN option to request that server performs DNS
            updates. This may be used to discover performance bottlenecks for
            different server configurations (e.g. DDNS enabled or disabled).
130 131 132
        </para>

        <para>
133 134 135 136
            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:
137 138 139 140 141
        </para>

        <itemizedlist>
            <listitem>
                <para>
142 143 144
                    With no template files specified on the command line,
                    <command>perfdhcp</command> will generate both SOLICIT
                    and REQUEST packets.
145 146 147
                </para>
            </listitem> <listitem>
                <para>
148 149 150 151
                    With one template file specified, that file
                    will be used as the pattern for SOLICIT packets:
                    <command>perfdhcp</command> will generate the REQUEST
                    packets.
152
                </para>
153 154
            </listitem> <listitem>
                <para>
155 156 157
                    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.
158 159 160 161 162
                </para>
            </listitem>
        </itemizedlist>

        <para>
163 164
            (Similar determination applies to DHCPv4's DISCOVER and REQUEST
            packets.)
165 166 167
        </para>

        <para>
168 169 170 171 172 173
            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 digits and spaces. Spaces are discarded when the
            template file is parsed (so in the file, '12B4' is the same as
            '12 B4' which is the same as '1 2 B 4')
174 175 176
        </para>

        <para>
177 178
            The template files should be used in conjunction with the command
            line parameters which specify offsets of the data fields being
Jeremy C. Reed's avatar
Jeremy C. Reed committed
179
            modified in outbound packets. For example, the <option>-E
180 181 182 183 184
            <replaceable class="parameter">time-offset</replaceable></option>
            switch specifies the offset of the DHCPv6 Elapsed Time option in
            the packet template. If the offset is specified, perfdhcp will
            inject the current elapsed time value into this field before
            sending the packet to the server.
185 186 187
        </para>

        <para>
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
            In many scenarios, <command>perfdhcp</command> needs to simulate
            multiple clients (having unique client identifier). Since
            packets for each client are 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 <option>-O
            <replaceable class="parameter">random-offset</replaceable></option>
            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 simulated clients is between 1 and 255, only one byte
            (to which randomization offset points) will be randomized. If the
            number of simulated clients is between 256 and 65535, two bytes
            will be randomized. Note, that two last bytes of the client
            identifier will be randomized in this case: the byte which
            randomization offset parameter points to, and the one which
            precedes it (random-offset - 1). If the number of simulated
            clients exceeds 65535, three bytes will be randomized; and so on.
207 208 209
        </para>

        <para>
210 211 212 213
            Templates may be currently used to generate packets being sent
            to the 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.
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
        </para>

    </refsect1>

    <refsect1>
        <title>OPTIONS</title>

        <variablelist>

            <varlistentry>
                <term><option>-1</option></term>
                <listitem>
                    <para>
                        Take the server-ID option from the first received
                        message.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-4</option></term>
                <listitem>
                    <para>
237 238
                        DHCPv4 operation; this is the default. It is
                        incompatible with the <option>-6</option> option.
239 240 241 242 243 244 245 246
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-6</option></term>
                <listitem>
                    <para>
247 248
                        DHCPv6 operation. This is incompatible with the
                        <option>-4</option> option.
249 250 251 252 253 254 255 256
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-a <replaceable class="parameter">aggressivity</replaceable></option></term>
                <listitem>
                    <para>
257 258 259 260
                        When the target sending rate is not yet reached,
                        control how many exchanges are initiated before the
                        next pause. This is a positive integer and defaults
                        to 1.
261 262 263 264 265 266 267 268
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-b <replaceable class="parameter">basetype=value</replaceable></option></term>
                <listitem>
                    <para>
269 270 271 272 273 274 275 276 277 278 279 280
                        The base MAC or DUID used to simulate
                        different clients. The <replaceable
                        class="parameter">basetype</replaceable> may be "mac"
                        or "duid". (The keyword "ether" may alternatively
                        used for MAC.)  The <option>-b</option> 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 hexadecimal string: it must be at least six
                        octets long and must not be longer than 64 bytes and
                        the length must be less than 128 hexadecimal digits,
                        for example: duid=0101010101010101010110111F14.
281 282 283 284 285 286 287 288
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-d <replaceable class="parameter">drop-time</replaceable></option></term>
                <listitem>
                    <para>
289 290 291 292
                        Specify the time after which a request is treated
                        as having been lost.  The value is given in seconds
                        and may contain a fractional component.  The default
                        is 1 second.
293 294 295 296 297 298 299 300
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-e <replaceable class="parameter">lease-type</replaceable></option></term>
                <listitem>
                    <para>
301 302
                        Specifies the type of lease being requested from
                        the server. It may be one of the following:
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328
                    </para>

                    <variablelist>
                        <varlistentry>
                            <term>address-only</term>
                            <listitem>
                                <para>Only regular addresses (v4 or v6) will be requested.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term>prefix-only</term>
                            <listitem>
                                <para>Only IPv6 prefixes will be requested.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term>address-and-prefix</term>
                            <listitem>
                                <para>Both IPv6 addresses and prefixes will be requested.</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>

                    <para>
329 330
                        The <option>-e prefix-only</option> and <option>-e
                        address-and-prefix</option> forms may not be used
331 332 333 334 335
                        with the <option>-4</option> option.
                    </para>
                </listitem>
            </varlistentry>

336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
            <varlistentry>
              <term><option>-f <replaceable class="parameter">renew-rate</replaceable></option></term>
              <listitem>
                <para>
                    Rate at which DHCPv4 or DHCPv6 renew requests are sent
                    to a server. This value is only valid when used in conjunction
                    with the exchange rate (given by <option>-r <replaceable
                    class="parameter">rate</replaceable></option>).
                    Furthermore the sum of this value and the release-rate
                    (given by <option>-F <replaceable class="parameter">
                    rate</replaceable></option>) must be equal to or less than
                    the exchange rate.
                </para>
              </listitem>
            </varlistentry>


353 354 355 356 357 358 359 360 361 362 363 364 365
            <varlistentry>
                <term><option>-h</option></term>
                <listitem>
                    <para>
                        Print help and exit.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-i</option></term>
                <listitem>
                    <para>
366 367
                        Do only the initial part of the exchange:
                        DISCOVER-OFFER if <option>-4</option> is selected,
368 369 370 371
                        SOLICIT-ADVERTISE if <option>-6</option> is chosen.
                    </para>

                    <para>
372 373 374 375 376 377 378
                        <option>-i</option> is incompatible with the following
                        options: <option>-1</option>, <option>-d</option>,
                        <option>-D</option>, <option>-E</option>,
                        <option>-S</option>, <option>-I</option> and
                        <option>-F</option>.  In addition, it cannot be
                        used with multiple instances of <option>-O</option>,
                        <option>-T</option> and <option>-X</option>.
379 380 381 382 383 384 385 386
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-l <replaceable class="parameter">local-addr|interface</replaceable></option></term>
                <listitem>
                    <para>
387 388 389 390 391 392 393
                        For DHCPv4 operation, specify the local
                        hostname/address to use when communicating with
                        the server.  By default, the interface address
                        through which traffic would normally be routed to
                        the server is used.  For DHCPv6 operation, specify
                        the name of the network interface through which
                        exchanges are initiated.
394 395 396 397 398 399 400 401
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-L <replaceable class="parameter">local-port</replaceable></option></term>
                <listitem>
                    <para>
402 403 404 405
                        Specify the local port to use.  This must be zero
                        or a positive integer up to 65535.  A value of 0
                        (the default) allows <command>perfdhcp</command>
                        to choose its own port.
406 407 408 409
                    </para>
                </listitem>
            </varlistentry>

410 411 412 413 414
            <varlistentry>
                <term><option>-M <replaceable class="parameter">mac-list-file</replaceable></option></term>
                <listitem>
                    <para>
                      A text file containing a list of MAC addresses,
Vincent Legout's avatar
Vincent Legout committed
415
                      one per line. If provided, a MAC address will be chosen randomly
416 417 418 419 420 421 422
                      from this list for every new exchange. In the DHCPv6 case, MAC
                      addresses are used to generate DUID-LLs. This parameter must not be
                      used in conjunction with the -b parameter.
                    </para>
                </listitem>
            </varlistentry>

423 424 425 426
            <varlistentry>
                <term><option>-P <replaceable class="parameter">preload</replaceable></option></term>
                <listitem>
                    <para>
427 428 429 430 431
                        Initiate <replaceable
                        class="parameter">preload</replaceable>
                        exchanges back to back at startup.  <replaceable
                        class="parameter">preload</replaceable> must be 0
                        (the default) or a positive integer.
432 433 434 435 436 437 438 439
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-r <replaceable class="parameter">rate</replaceable></option></term>
                <listitem>
                    <para>
440 441 442 443 444 445 446 447
                        Initiate <replaceable
                        class="parameter">rate</replaceable> DORA/SARR (or
                        if <option>-i</option> is given, DO/SA) exchanges
                        per 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.
448 449 450 451 452 453 454 455
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-R <replaceable class="parameter">num-clients</replaceable></option></term>
                <listitem>
                    <para>
456 457 458 459 460
                        Specify how many different clients are used. With
                        a value of 1 (the default), all requests seem
                        to come from the same client. <replaceable
                        class="parameter">num-clients</replaceable> must be
                        a positive number.
461 462 463 464 465 466 467 468
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-s <replaceable class="parameter">seed</replaceable></option></term>
                <listitem>
                    <para>
469 470 471 472 473
                        Specify the seed for randomization, making runs of
                        <command>perfdhcp</command> repeatable. <replaceable
                        class="parameter">seed</replaceable> is 0 or a positive
                        integer. The value 0 means that a seed is not used;
                        this is the default.
474 475 476 477 478 479 480 481
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-T <replaceable class="parameter">template-file</replaceable></option></term>
                <listitem>
                    <para>
482 483 484 485
                        The name of a file containing the template to use as a
                        stream of hexadecimal digits.  This may be specified
                        up to two times and controls the contents of the
                        packets sent (see the "TEMPLATES" section above).
486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-v</option></term>
                <listitem>
                    <para>
                        Print the version of this program.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-w <replaceable class="parameter">wrapped</replaceable></option></term>
                <listitem>
                    <para>
503 504
                        Command to call with  a single parameter of "start"
                        or "stop" at the beginning/end of the program.
505 506 507 508 509 510 511 512
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-x <replaceable class="parameter">diagnostic-selector</replaceable></option></term>
                <listitem>
                    <para>
513 514 515 516 517 518
                        Include extended diagnostics
                        in the output.  <replaceable
                        class="parameter">diagnostic-selector</replaceable>
                        is a string of single-keywords specifying the
                        operations for which verbose output is desired.
                        The selector key letters are:
519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572
                    </para>

                    <variablelist>
                        <varlistentry>
                            <term>a</term>
                            <listitem>
                                <para>Print the decoded command line arguments.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term>e</term>
                            <listitem>
                                <para>Print the exit reason.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term>i</term>
                            <listitem>
                                <para>Print rate processing details.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term>s</term>
                            <listitem>
                                <para>Print the first server-ID.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term>t</term>
                            <listitem>
                                <para>When finished, print timers of all successful exchanges.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term>T</term>
                            <listitem>
                                <para>When finished, print templates</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>

            </varlistentry>

        </variablelist>

        <refsect2>
            <title>DHCPv4-Only Options</title>
            <para>
573 574
                The following options only apply for DHCPv4 (i.e. when
                <option>-4</option> is given).
575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591
            </para>

            <variablelist>
                <varlistentry>
                    <term><option>-B</option></term>
                    <listitem>
                        <para>
                            Force broadcast handling.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>

        <refsect2>
            <title>DHCPv6-Only Options</title>
            <para>
592 593
                The following options only apply for DHCPv6 (i.e. when
                <option>-6</option> is given).
594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611
            </para>

            <variablelist>

                <varlistentry>
                    <term><option>-c</option></term>
                    <listitem>
                        <para>
                            Add a rapid commit option (exchanges will be
                            SOLICIT-ADVERTISE).
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term><option>-F <replaceable class="parameter">release-rate</replaceable></option></term>
                    <listitem>
                        <para>
612 613 614 615 616 617 618 619
                            Rate at which IPv6 RELEASE requests are
                            sent to a server. This value is only valid
                            when used in conjunction with the exchange
                            rate (given by <option>-r <replaceable
                            class="parameter">rate</replaceable></option>).
                            Furthermore the sum of this value and the
                            renew-rate (given by <option>-f <replaceable
                            class="parameter">rate</replaceable></option>)
620 621 622 623 624
                            must be equal to or less than the exchange rate.
                        </para>
                    </listitem>
                </varlistentry>

625 626 627 628 629 630 631 632 633 634 635 636 637 638
                <varlistentry>
                  <term><option>-A <replaceable class="parameter">encapsulation-level</replaceable></option></term>
                  <listitem>
                    <para>
                      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
                      <replaceable class="parameter">encapsulation-level</replaceable>
                      value is 1, which means that the generated traffic is an equivalent
                      of the traffic passing through a single relay agent.
                    </para>
                  </listitem>
                </varlistentry>

639 640 641 642 643 644
            </variablelist>
        </refsect2>

        <refsect2>
            <title>Template-Related Options</title>
            <para>
645 646 647 648 649
                The following options may only be used in conjunction with
                <option>-T</option> and control how <command>perfdhcp</command>
                modifies the template.  The options may be specified multiple
                times on the command line; each occurrence affects the
                corresponding template file (see "TEMPLATES" above).
650 651 652 653 654 655
            </para>

            <varlistentry>
                <term><option>-E <replaceable class="parameter">time-offset</replaceable></option></term>
                <listitem>
                    <para>
656 657 658 659
                        Offset of the (DHCPv4) secs field or (DHCPv6)
                        elapsed-time option in the (second i.e. REQUEST)
                        template and must be 0 or a positive integer:
                        a value of 0 disables this.
660 661 662 663 664 665 666 667
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-I <replaceable class="parameter">ip-offset</replaceable></option></term>
                <listitem>
                    <para>
668 669 670
                        Offset of the (DHCPv4) IP address in the requested-IP
                        option / (DHCPv6) IA_NA option in the (second/request)
                        template.
671 672 673 674 675 676 677 678
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-O <replaceable class="parameter">random-offset</replaceable></option></term>
                <listitem>
                    <para>
679 680 681 682 683
                        Offset of the last octet to
                        randomize in the template.  <replaceable
                        class="parameter">random-offset</replaceable> must be
                        an integer greater than 3.  The <option>-T</option>
                        switch must be given to use this option.
684 685 686 687 688 689 690 691
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-S <replaceable class="parameter">srvid-offset</replaceable></option></term>
                <listitem>
                    <para>
692 693 694 695 696 697
                        Offset of the server-ID option in the
                        (second/request) template.  <replaceable
                        class="parameter">srvid-offset</replaceable> must
                        be a positive integer, and the switch can only be
                        used when the template option (<option>-T</option>)
                        is also given.
698 699 700 701 702 703 704 705
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-X <replaceable class="parameter">xid-offset</replaceable></option></term>
                <listitem>
                    <para>
706 707 708 709 710
                        Offset of the transaction ID (xid) in the template.
                        <replaceable class="parameter">xid-offset</replaceable>
                        must be a positive integer, and the switch can only
                        be used when the template option (<option>-T</option>)
                        is also given.
711 712 713 714 715 716 717 718
                    </para>
                </listitem>
            </varlistentry>
        </refsect2>

        <refsect2>
            <title>Options Controlling a Test</title>
            <para>
719 720 721
                The following options may only be used in conjunction with
                <option>-r</option> and control both the length of the test
                and the frequency of reports.
722 723 724 725 726 727 728 729
            </para>

            <variablelist>

                <varlistentry>
                    <term><option>-D <replaceable class="parameter">max-drop</replaceable></option></term>
                    <listitem>
                        <para>
730 731 732 733 734 735 736 737 738 739
                            Abort the test if more than <replaceable
                            class="parameter">max-drop</replaceable>
                            requests have been dropped.  Use <option>-D
                            0</option> to abort if even a single
                            request has been dropped.  If <replaceable
                            class="parameter">max-drop</replaceable> 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.
740 741 742 743 744 745 746 747
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term><option>-n <replaceable class="parameter">num-requests</replaceable></option></term>
                    <listitem>
                        <para>
748 749 750 751 752 753
                            Initiate <replaceable
                            class="parameter">num-request</replaceable>
                            transactions.  No report is generated until all
                            transactions have been initiated/waited-for,
                            after which a report is generated and the
                            program terminates.
754 755 756 757 758 759 760 761
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term><option>-p <replaceable class="parameter">test-period</replaceable></option></term>
                    <listitem>
                        <para>
762 763 764 765 766 767 768
                            Send requests for <replaceable
                            class="parameter">test-period</replaceable>,
                            which is specified in the same manner as
                            <option>-d</option>.  This can be used as an
                            alternative to <option>-n</option>, or both
                            options can be given, in which case the testing
                            is completed when either limit is reached.
769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term><option>-t <replaceable class="parameter">interval</replaceable></option></term>
                    <listitem>
                        <para>
                            Sets the delay (in seconds) between two successive reports.
                        </para>
                    </listitem>
                </varlistentry>

            </variablelist>
        </refsect2>

        <refsect2>
            <title>Arguments</title>

            <variablelist>
                <varlistentry>
                    <term>server</term>
                    <listitem>
                        <para>
793 794 795 796 797 798 799 800
                            Server to test, specified as an IP address.
                            In the DHCPv6 case, the 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 <option>-l</option>
                            option is given to specify an interface, in
Jeremy C. Reed's avatar
Jeremy C. Reed committed
801
                            which case it defaults to 'all'.
802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect2>


    </refsect1>

    <refsect1>
        <title>ERRORS</title>

        <para>
            <command>perfdhcp</command> can report the following errors in the packet exchange:
        </para>

        <variablelist>
            <varlistentry>
                <term>tooshort</term>
                <listitem>
                    <para>A message was received that was too short.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>orphans</term>
                <listitem>
                    <para>
830 831 832 833
                        Received a message which doesn't match one sent
                        to the server (i.e. it is a duplicate message, a
                        message that has arrived after an excessive delay,
                        or one that is just not recognized).
834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>locallimit</term>
                <listitem>
                    <para>Reached local system limits when sending a message.</para>
                </listitem>
            </varlistentry>
        </variablelist>

    </refsect1>

    <refsect1>
        <title>EXIT STATUS</title>

        <para>
852 853
            <command>perfdhcp</command> can exit with one of the following
            status codes:
854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886
        </para>

        <variablelist>
            <varlistentry>
                <term>0</term> <listitem>
                    <para>Success.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>1</term>
                <listitem>
                    <para>General error.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>2</term>
                <listitem>
                    <para>Error in command-line arguments.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>3</term>
                <listitem>
                    <para>No general failures in operation, but one or more exchanges were unsuccessful.</para>
                </listitem>
            </varlistentry>
        </variablelist>

    </refsect1>

887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906
    <!-- perfdhcp is not documented in the User's Guide at
         all. There's one reference when we list binaries, but that's
         it. Once it's documented, we can copy over the DOCUMENTATION
         section from src/bin/dhcp4/kea-dhcp4.xml -->

  <refsect1>
    <title>MAILING LISTS AND SUPPORT</title>
    <para>
      There are two mailing lists available for Kea project. kea-users
      (kea-users at lists.isc.org) is intended for Kea users, while kea-dev
      (kea-dev at lists.isc.org) is intended for Kea developers, prospective
      contributors and other advanced users.  Both lists are available at
      http://lists.isc.org. The community provides best effort type of support
      on both of those lists.
    </para>
    <para>
      ISC provides professional support for Kea services. See
      https://www.isc.org/kea/ for details.
    </para>
  </refsect1>
907

908 909 910
    <refsect1>
        <title>HISTORY</title>
        <para>
911 912 913 914
            The <command>perfdhcp</command> tool was initially coded
            in October 2011 by John DuBois, Francis Dupont and Marcin
            Siodelski of ISC. Kea 1.0.0 that included perfdhcp was
            released in December 2015.
915 916
        </para>
    </refsect1>
917

918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935
  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>kea-dhcp4</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-dhcp6</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-dhcp-ddns</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

936 937 938 939 940
      <citerefentry>
        <refentrytitle>kea-ctrl-agent</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960
      <citerefentry>
        <refentrytitle>kea-admin</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>keactrl</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-lfc</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citetitle>Kea Administrator's Guide</citetitle>.

    </para>
  </refsect1>

961
</refentry>