BIND 10 trac2307, updated. 6ca0d329098fd60d5c6af5d0ea5c5a07eebf7de5 [2307] Added the full list of options to the perfdhcp man page
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri Feb 21 16:05:48 UTC 2014
The branch, trac2307 has been updated
via 6ca0d329098fd60d5c6af5d0ea5c5a07eebf7de5 (commit)
from 142b9b66f006f8fec3a7b04bb10b615fea175b7c (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 6ca0d329098fd60d5c6af5d0ea5c5a07eebf7de5
Author: Stephen Morris <stephen at isc.org>
Date: Fri Feb 21 16:04:08 2014 +0000
[2307] Added the full list of options to the perfdhcp man page
Also added section on templates, separate the options out into
different categories, and generally tidied up the XML.
-----------------------------------------------------------------------
Summary of changes:
tests/tools/perfdhcp/perfdhcp.xml | 1298 +++++++++++++++++++++----------------
1 file changed, 734 insertions(+), 564 deletions(-)
-----------------------------------------------------------------------
diff --git a/tests/tools/perfdhcp/perfdhcp.xml b/tests/tools/perfdhcp/perfdhcp.xml
index 05a997d..6f23ae4 100644
--- a/tests/tools/perfdhcp/perfdhcp.xml
+++ b/tests/tools/perfdhcp/perfdhcp.xml
@@ -2,7 +2,7 @@
"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
@@ -17,571 +17,741 @@
- 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>
More information about the bind10-changes
mailing list