"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY mdash "—">]>
<!--
- - Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC")
+ - Copyright (C) 2014 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- PERFORMANCE OF THIS SOFTWARE.
-->
-<refentry>
-
- <refentryinfo>
- <date>September 25, 2013</date>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>perfdhcp</refentrytitle>
- <manvolnum>1</manvolnum>
- <refmiscinfo>BIND10</refmiscinfo>
- </refmeta>
-
- <refnamediv>
- <refname>perfdhcp</refname>
- <refpurpose>DHCP benchmarking tool</refpurpose>
- </refnamediv>
-
- <docinfo>
- <copyright>
- <year>2013</year>
- <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
- </copyright>
- </docinfo>
-
-<!-- TODO: some examples show -fflag and -f flag - do both work? -->
-<!-- TODO: rewrite descriptions so say string or number etc -->
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>perfdhcp</command>
- <arg><option>-e</option></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>DESCRIPTION</title>
- <para><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.
- It is able to test both IPv4 and IPv6 servers.
- It can time the initial two-packet exchange (DO and SA) and
- the four-packet exchange (DORA and SARR).
- </para>
-
- </refsect1>
-
- <refsect1>
- <title>OPTIONS</title>
-
- <para>The arguments are as follows:</para>
-
- <variablelist>
-
- <varlistentry>
- <term>
- <option>-1</option>
- </term>
- <listitem>
- <para>Take the server-ID option from the first received
- message.
-<!-- TODO: The default is .... (not to use the server-ID option
-from the first received message. -->
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-4</option>
- </term>
- <listitem>
- <para>DHCPv4 operation. This is the default. This is incompatible
- with the -6 option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-6</option>
- </term>
- <listitem>
- <para>DHCPv6 operation. This is incompatible with the -4
- option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-a</option>
- <replaceable class="parameter">aggressivity</replaceable>
- </term>
- <listitem>
- <para>When the target sending rate is not yet reached,
- control how many exchanges are initiated before the next
- pause. This is set to a positive integer. The default is 1.</para>
- </listitem>
- </varlistentry>
-
- <!-- TODO: number? -->
- <varlistentry>
- <term>
- <option>-b</option>
- <replaceable class="parameter">basetype=value</replaceable>
- </term>
- <listitem>
- <para>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 -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 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.</para>
-<!-- TODO: code mentions duid=0F1234 but isn't that too short? -->
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-d</option>
- <replaceable class="parameter">drop-time</replaceable>
- </term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-E</option>
- <replaceable class="parameter">time-offset</replaceable>
- </term>
- <listitem>
- <para>Offset of the (DHCPv4) secs field / (DHCPv6)
- elapsed-time option in the (second/request) template.
- The value must be 0 or a positive integer.
- The value 0 disables it. This is incompatible
- with the -i option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-e</option>
- <replaceable class="parameter">lease-type</replaceable>
- </term>
- <listitem>
- <para>The type of lease being requested from the server.
- It may be one of the following: address-only, prefix-only
- or address-and-prefix. The address-only indicates that
- the regular address (v4 or v6) will be requested. The
- prefix-only indicates that the IPv6 prefix will be
- requested. The address-and-prefix indicates that both
- IPv6 address and prefix will be requested. The '-e
- prefix-only' and '-e address-and-prefix' must not be used
- with -4. (The -6 option must be used if lease type other
- than '-e address-only'.)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-h</option>
- </term>
- <listitem>
- <para>Print help.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-i</option>
- </term>
- <listitem>
- <para>Do only the initial part of an exchange: DO or SA.
- If DHCPv4 mode (-4) is does DISCOVER-OFFER only.
- If DHCPv6 mode (-6) is does SOLICIT-ADVERTISE only.</para>
-<!-- TODO: The default is to use 4-way DORA for
-DHCPv4 and SARR for DHCPv6. -->
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-I</option>
- <replaceable class="parameter">ip-offset</replaceable>
- </term>
- <listitem>
- <para>Offset of the (DHCPv4) IP address in the
- requested-IP option / (DHCPv6) IA_NA option in the
- (second/request) template. This value is a positive integer.
- This is incompatible with the -i option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-l</option>
- <replaceable class="parameter">local-addr|interface</replaceable>
- </term>
- <listitem>
- <para>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 via which exchanges are initiated.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-L</option>
- <replaceable class="parameter">local-port</replaceable>
- </term>
- <listitem>
- <para>Specify the local port to use.
- The value must be 0 or a positive integer up to 65535.
-<!-- NOTE: within uint16_t -->
- The value 0 means to use the default.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-O</option>
- <replaceable class="parameter">random-offset</replaceable>
- </term>
- <listitem>
- <para>Offset of the last octet to randomize in the
- template. The value must be greater than 3.
- The -T switch must be used with -O.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-P</option>
- <replaceable class="parameter">preload</replaceable>
- </term>
- <listitem>
- <para>Initiate first
- <replaceable class="parameter">preload</replaceable>
- exchanges back to back at startup.
- The value must be 0 or a positive integer.</para>
-<!-- TODO: The default is 0 - what does that mean? -->
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-r</option>
- <replaceable class="parameter">rate</replaceable>
- </term>
- <listitem>
- <para>Initiate
- <replaceable class="parameter">rate</replaceable>
- DORA/SARR (or if -i is given, DO/SA)
- exchanges per second. The value is a positive integer.
- 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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-R</option>
- <replaceable class="parameter">range</replaceable>
- </term>
- <listitem>
- <para>Specify how many different clients are used. With 1
- (the default), all requests seem to come from the same
- client.
- The value must be 0 or a positive integer.</para>
-<!-- TODO: Why does help say default is 1? what does 0 mean? -->
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-s</option>
- <replaceable class="parameter">seed</replaceable>
- </term>
- <listitem>
- <para>Specify the seed for randomization, making it
- repeatable.
- The value must be 0 or a positive integer.
- The value 0 means a seed is not used; this is the default.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-S</option>
- <replaceable class="parameter">srvid-offset</replaceable>
- </term>
- <listitem>
- <para>Offset of the server-ID option in the
- (second/request) template. The value is a positive integer.
- This is incompatible with the -i option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-T</option>
- <replaceable class="parameter">template-file</replaceable>
- </term>
- <listitem>
- <para>The name of a file containing the template to use
- as a stream of hexadecimal digits.</para>
-<!-- TODO: this switch can be used a second time except with -i -->
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-v</option>
- </term>
- <listitem>
- <para>Report the version number of this program.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-w</option>
- <replaceable class="parameter">wrapped</replaceable>
- </term>
- <listitem>
- <para>Command to call with start/stop at the
- beginning/end of the program.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-x</option>
- <replaceable class="parameter">diagnostic-selector</replaceable>
- </term>
- <listitem>
- <para>Include extended diagnostics in the output.
- <replaceable class="parameter">diagnostic-selector</replaceable>
-<!-- TODO: fix formatting -->
- is a string of single-keywords specifying the operations
- for which verbose output is desired. The selector keyletters
- are: 'a' print the decoded command line arguments,
- 'e' print the exit reason, 'i' print rate processing
- details, 's' print first server-id, 't' when finished,
- print timers of all successful exchanges, 'T' when
- finished, print templates.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-X</option>
- <replaceable class="parameter">xid-offset</replaceable>
- </term>
- <listitem>
- <para>Transaction ID (xid) offset in the
- template. The value is a positive integer.
- The -T switch must be used with -X.</para>
- </listitem>
- </varlistentry>
-
- <para>DHCPv4 only option:</para>
- <varlistentry>
- <term>
- <option>-B</option>
- </term>
- <listitem>
- <para>Force broadcast handling. This is a DHCPv4-only
- (-4) option, and is not compatible with IPv6 (-6).</para>
-<!-- TODO: mention this is the default when "all" is the server name. -->
- </listitem>
- </varlistentry>
-
- <para>DHCPv6 only options:</para>
- <varlistentry>
- <term>
- <option>-c</option>
- </term>
- <listitem>
- <para>Add a rapid commit option (exchanges will be
- SA). This is a DHCPv6-only (-6) option.
- The -i switch must be set to use -c.</para>
- </listitem>
- </varlistentry>
-
- <para>The remaining options are used only in conjunction with
- -r:</para>
-
- <varlistentry>
- <term>
- <option>-D</option>
- <replaceable class="parameter">max-drop</replaceable>
- </term>
- <listitem>
- <para>Abort the test if more than
- <replaceable class="parameter">max-drop</replaceable>
- requests have been dropped. Use -D0
- 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.</para>
- <para>The -D option must be used with the -r switch.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-n</option>
- <replaceable class="parameter">num-request</replaceable>
- </term>
- <listitem>
- <para>Initiate
- <replaceable class="parameter">num-request</replaceable>
- transactions.
- The value is a positive integer.
- No report is generated until all transactions have been
- initiated/waited-for after which a report is generated
- and the program terminates.</para>
- <para>The -n option must be used with the -r switch.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-p</option>
- <replaceable class="parameter">test-period</replaceable>
- </term>
- <listitem>
- <para>Send requests for the given test period, which is
- specified in the same manner as -d. This can be used as
- an alternative to -n, or both options can be given, in
- which case the testing is completed when either limit is
- reached. The value must be a positive integer.
- The -p option must be used with the -r switch.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-t</option>
- <replaceable class="parameter">report</replaceable>
- </term>
- <listitem>
- <para>Delay in seconds between two periodic
- reports. The value is a positive integer.
- The -t option must be used with the -r switch.</para>
- </listitem>
- </varlistentry>
-
-
-<!--
-TODO: where is this displayed?
- "Errors:\n"
- <varlistentry><term><option> tooshort</option></term><listitem><para>received a too short message\n"
- <varlistentry><term><option> orphans</option></term><listitem><para>received a message which doesn't match an exchange\n"
- " (duplicate, late or not related)\n"
- <varlistentry><term><option> locallimit</option></term><listitem><para>reached to local system limits when sending a message.</para></listitem></varlistentry>
-
--->
+<!-- Note: This XML file is best viewed with a screen width of 123 characters or more -->
- </variablelist>
-
- </refsect1>
-
- <refsect1>
- <title>EXIT STATUS</title>
- <para>
- The <command>perfdhcp</command> utility exits with one of
- the following values:
- </para>
-
- <variablelist>
- <varlistentry>
- <term>0</term>
- <listitem><simpara>Complete success.</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>1</term>
- <listitem><simpara>General error.</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>2</term>
- <listitem><simpara>An error in the command line
- arguments.</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>3</term>
- <listitem><simpara>One or more exchanges were not successfully
- completed (and no general failures in operation).</simpara></listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>SEE ALSO</title>
- <para>
- <citerefentry>
- <refentrytitle>b10-dhcp4</refentrytitle><manvolnum>8</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>b10-dhcp6</refentrytitle><manvolnum>8</manvolnum>
- </citerefentry>,
- <citetitle>BIND 10 Guide</citetitle>,
- <citetitle>DHCP Performance Guide</citetitle>.
- </para>
- </refsect1>
+<refentry>
+ <refentryinfo>
+ <date>February 19, 2014</date>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>perfdhcp</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo>Kea</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>perfdhcp</refname>
+ <refpurpose>DHCP benchmarking tool</refpurpose>
+ </refnamediv>
+
+ <docinfo>
+ <copyright>
+ <year>2014</year>
+ <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>
+ <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>
+ <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>
+ <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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>TEMPLATES</title>
+ <para>
+ To allow the contents of packets sent to the server to be customised, <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).
+ </para>
+
+ <para>
+ 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:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ With no template files specified on the command line, <command>perfdhcp</command> will generate both
+ SOLICIT and ADVERTISE packets.
+ </para>
+ </listitem> <listitem>
+ <para>
+ With one template file specified, that file will be used as the pattern for SOLICIT packets:
+ <command>perfdhcp</command> will generate the ADVERTISE packets.
+ .</para>
+ </listitem> <listitem>
+ <para>
+ 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 ADVERTISE packets.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ (Similar determination applies to DHCPv4's DISCOVER and REQUEST packets.)
+ </para>
+
+ <para>
+ 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')
+ </para>
+
+ <para>
+ The template files should be used in conjunction with the command line parameters which specify offsets
+ of the data fields being modified in outbound packets. For example, example, the <option>-E <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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </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>
+ DHCPv4 operation; this is the default. It is incompatible with the <option>-6</option> option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-6</option></term>
+ <listitem>
+ <para>
+ DHCPv6 operation. This is incompatible with the <option>-4</option> option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-a <replaceable class="parameter">aggressivity</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-b <replaceable class="parameter">basetype=value</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-d <replaceable class="parameter">drop-time</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-e <replaceable class="parameter">lease-type</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the type of lease being requested from the server. It may be one of the following:
+ </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>
+ The <option>-e prefix-only</option> and <option>-e address-and-prefix</option> forms may not be used
+ with the <option>-4</option> option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-h</option></term>
+ <listitem>
+ <para>
+ Print help and exit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-i</option></term>
+ <listitem>
+ <para>
+ Do only the initial part of the exchange: DISCOVER-OFFER if <option>-4</option> is selected,
+ SOLICIT-ADVERTISE if <option>-6</option> is chosen.
+ </para>
+
+ <para>
+ <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>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-l <replaceable class="parameter">local-addr|interface</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-L <replaceable class="parameter">local-port</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-P <replaceable class="parameter">preload</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-r <replaceable class="parameter">rate</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-R <replaceable class="parameter">num-clients</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s <replaceable class="parameter">seed</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-T <replaceable class="parameter">template-file</replaceable></option></term>
+ <listitem>
+ <para>
+ 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).
+ </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>
+ Command to call with a single parameter of "start" or "stop" at the beginning/end of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-x <replaceable class="parameter">diagnostic-selector</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 keyletters are:
+ </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>
+ The following options only apply for DHCPv4 (i.e. when <option>-4</option> is given).
+ </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>
+ The following options only apply for DHCPv6 (i.e. when <option>-6</option> is given).
+ </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">renew-rate</replaceable></option></term>
+ <listitem>
+ <para>
+ Rate at which IPv6 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>
+
+ <varlistentry>
+ <term><option>-F <replaceable class="parameter">release-rate</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>)
+ must be equal to or less than the exchange rate.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Template-Related Options</title>
+ <para>
+ 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).
+ </para>
+
+ <varlistentry>
+ <term><option>-E <replaceable class="parameter">time-offset</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-I <replaceable class="parameter">ip-offset</replaceable></option></term>
+ <listitem>
+ <para>
+ Offset of the (DHCPv4) IP address in the requested-IP option / (DHCPv6) IA_NA option in the
+ (second/request) template.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O <replaceable class="parameter">random-offset</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-S <replaceable class="parameter">srvid-offset</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-X <replaceable class="parameter">xid-offset</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </refsect2>
+
+ <refsect2>
+ <title>Options Controlling a Test</title>
+ <para>
+ 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.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-D <replaceable class="parameter">max-drop</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-n <replaceable class="parameter">num-requests</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-p <replaceable class="parameter">test-period</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </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>
+ 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 which
+ case it defauls to 'all'.
+ </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>
+ 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 recognised).
+ </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>
+ <command>perfdhcp</command> can exit with one of the following status codes:
+ </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>
+
+ <refsect1>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry><refentrytitle>b10-dhcp4</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>b10-dhcp6</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citetitle>BIND 10 Guide</citetitle>,
+ <citetitle>DHCP Performance Guide</citetitle>.
+ </para>
+ </refsect1>
<!--
- <refsect1>
- <title>HISTORY</title>
- <para>
- The <command>perfdhcp</command> tool was first implemented
- by John Dubois in November 2011.
- </para>
- </refsect1>
--->
-
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
+ <refsect1>
+ <title>HISTORY</title>
+ <para>
+ The <command>perfdhcp</command> tool was initially coded by
+ John DuBois, Francis Dupont and Marcin Siodelski of ISC.
+ </para>
+ </refsect1>
-->
-<!--
-
- "perfdhcp [-hv] [-4|-6] [-r<rate>] [-t<report>] [-R<range>] [-b<base>]\n"
- " [-n<num-request>] [-p<test-period>] [-d<drop-time>] [-D<max-drop>]\n"
- " [-l<local-addr|interface>] [-P<preload>] [-a<aggressivity>]\n"
- " [-L<local-port>] [-s<seed>] [-i] [-B] [-c] [-1]\n"
- " [-T<template-file>] [-X<xid-offset>] [-O<random-offset]\n"
- " [-E<time-offset>] [-S<srvid-offset>] [-I<ip-offset>]\n"
- " [-x<diagnostic-selector>] [-w<wrapped>] [server]\n"
- "\n"
- "The [server] argument is the name/address of the DHCP server to\n"
- "contact. For DHCPv4 operation, exchanges are initiated by\n"
- "transmitting a DHCP DISCOVER to this address.\n"
- "\n"
- "For DHCPv6 operation, exchanges are initiated by transmitting a DHCP\n"
- "SOLICIT to this address. In the DHCPv6 case, the special name 'all'\n"
- "can be used to refer to All_DHCP_Relay_Agents_and_Servers (the\n"
- "multicast address FF02::1:2), or the special name 'servers' to refer\n"
- "to All_DHCP_Servers (the multicast address FF05::1:3). The [server]\n"
- "argument is optional only in the case that -l is used to specify an\n"
- "interface, in which case [server] defaults to 'all'.\n"
- "\n"
- "The default is to perform a single 4-way exchange, effectively pinging\n"
- "the server.\n"
- "The -r option is used to set up a performance test, without\n"
- "it exchanges are initiated as fast as possible.\n"
--->
+</refentry>
projects / thirdparty / kea.git / commitdiff
