'\" t
.\"     Title: perfdhcp
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: Sep. 28, 2016
.\"    Manual: Kea
.\"    Source: ISC Kea 1.1.0
.\"  Language: English
.\"
.TH "PERFDHCP" "8" "Sep\&. 28, 2016" "ISC Kea 1.1.0" "Kea"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perfdhcp \- DHCP benchmarking tool
.SH "SYNOPSIS"
.HP \w'\fBperfdhcp\fR\ 'u
\fBperfdhcp\fR [\fB\-1\fR] [\fB\-4|\-6\fR] [\fB\-A\ \fR\fB\fIencapsulation\-level\fR\fR] [\fB\-a\ \fR\fB\fIaggressivity\fR\fR] [\fB\-b\ \fR\fB\fIbase\fR\fR] [\fB\-B\fR] [\fB\-c\fR] [\fB\-d\ \fR\fB\fIdrop\-time\fR\fR] [\fB\-D\ \fR\fB\fImax\-drop\fR\fR] [\fB\-e\ \fR\fB\fIlease\-type\fR\fR] [\fB\-E\ \fR\fB\fItime\-offset\fR\fR] [\fB\-f\ \fR\fB\fIrenew\-rate\fR\fR] [\fB\-F\ \fR\fB\fIrelease\-rate\fR\fR] [\fB\-h\fR] [\fB\-i\fR] [\fB\-I\ \fR\fB\fIip\-offset\fR\fR] [\fB\-l\ \fR\fB\fIlocal\-address|interface\fR\fR] [\fB\-L\ \fR\fB\fIlocal\-port\fR\fR] [\fB\-M\ \fR\fB\fImac\-list\-file\fR\fR] [\fB\-n\ \fR\fB\fInum\-request\fR\fR] [\fB\-O\ \fR\fB\fIrandom\-offset\fR\fR] [\fB\-p\ \fR\fB\fItest\-period\fR\fR] [\fB\-P\ \fR\fB\fIpreload\fR\fR] [\fB\-r\ \fR\fB\fIrate\fR\fR] [\fB\-R\ \fR\fB\fInum\-clients\fR\fR] [\fB\-s\ \fR\fB\fIseed\fR\fR] [\fB\-S\ \fR\fB\fIsrvid\-offset\fR\fR] [\fB\-t\ \fR\fB\fIreport\fR\fR] [\fB\-T\ \fR\fB\fItemplate\-file\fR\fR] [\fB\-v\fR] [\fB\-W\ \fR\fB\fIwrapped\fR\fR] [\fB\-x\ \fR\fB\fIdiagnostic\-selector\fR\fR] [\fB\-X\ \fR\fB\fIxid\-offset\fR\fR] [server]
.SH "DESCRIPTION"
.PP
\fBperfdhcp\fR
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\&.
.PP
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\&.
.PP
When running a performance test,
\fBperfdhcp\fR
will exchange packets with the server under test as fast as possible unless the
\fB\-r\fR
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
\fBperfdhcp\fR, the elapsed time, or the number of requests dropped by the server\&.
.SH "TEMPLATES"
.PP
To allow the contents of packets sent to the server to be customized,
\fBperfdhcp\fR
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)\&.
.PP
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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
With no template files specified on the command line,
\fBperfdhcp\fR
will generate both SOLICIT and REQUEST packets\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
With one template file specified, that file will be used as the pattern for SOLICIT packets:
\fBperfdhcp\fR
will generate the REQUEST packets\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.PP
(Similar determination applies to DHCPv4\*(Aqs DISCOVER and REQUEST packets\&.)
.PP
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, \*(Aq12B4\*(Aq is the same as \*(Aq12 B4\*(Aq which is the same as \*(Aq1 2 B 4\*(Aq)
.PP
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, the
\fB\-E \fR\fB\fItime\-offset\fR\fR
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\&.
.PP
In many scenarios,
\fBperfdhcp\fR
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
\fB\-O \fR\fB\fIrandom\-offset\fR\fR
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\&.
.PP
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\&.
.SH "OPTIONS"
.PP
\fB\-1\fR
.RS 4
Take the server\-ID option from the first received message\&.
.RE
.PP
\fB\-4\fR
.RS 4
DHCPv4 operation; this is the default\&. It is incompatible with the
\fB\-6\fR
option\&.
.RE
.PP
\fB\-6\fR
.RS 4
DHCPv6 operation\&. This is incompatible with the
\fB\-4\fR
option\&.
.RE
.PP
\fB\-a \fR\fB\fIaggressivity\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-b \fR\fB\fIbasetype=value\fR\fR
.RS 4
The base MAC or DUID used to simulate different clients\&. The
\fIbasetype\fR
may be "mac" or "duid"\&. (The keyword "ether" may alternatively used for MAC\&.) The
\fB\-b\fR
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\&.
.RE
.PP
\fB\-d \fR\fB\fIdrop\-time\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-e \fR\fB\fIlease\-type\fR\fR
.RS 4
Specifies the type of lease being requested from the server\&. It may be one of the following:
.PP
address\-only
.RS 4
Only regular addresses (v4 or v6) will be requested\&.
.RE
.PP
prefix\-only
.RS 4
Only IPv6 prefixes will be requested\&.
.RE
.PP
address\-and\-prefix
.RS 4
Both IPv6 addresses and prefixes will be requested\&.
.RE
.sp
The
\fB\-e prefix\-only\fR
and
\fB\-e address\-and\-prefix\fR
forms may not be used with the
\fB\-4\fR
option\&.
.RE
.PP
\fB\-f \fR\fB\fIrenew\-rate\fR\fR
.RS 4
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
\fB\-r \fR\fB\fIrate\fR\fR)\&. Furthermore the sum of this value and the release\-rate (given by
\fB\-F \fR\fB\fI rate\fR\fR) must be equal to or less than the exchange rate\&.
.RE
.PP
\fB\-h\fR
.RS 4
Print help and exit\&.
.RE
.PP
\fB\-i\fR
.RS 4
Do only the initial part of the exchange: DISCOVER\-OFFER if
\fB\-4\fR
is selected, SOLICIT\-ADVERTISE if
\fB\-6\fR
is chosen\&.
.sp
\fB\-i\fR
is incompatible with the following options:
\fB\-1\fR,
\fB\-d\fR,
\fB\-D\fR,
\fB\-E\fR,
\fB\-S\fR,
\fB\-I\fR
and
\fB\-F\fR\&. In addition, it cannot be used with multiple instances of
\fB\-O\fR,
\fB\-T\fR
and
\fB\-X\fR\&.
.RE
.PP
\fB\-l \fR\fB\fIlocal\-addr|interface\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-L \fR\fB\fIlocal\-port\fR\fR
.RS 4
Specify the local port to use\&. This must be zero or a positive integer up to 65535\&. A value of 0 (the default) allows
\fBperfdhcp\fR
to choose its own port\&.
.RE
.PP
\fB\-M \fR\fB\fImac\-list\-file\fR\fR
.RS 4
A text file containing a list of MAC addresses, one per line\&. If provided, a MAC address will be choosen randomly 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\&.
.RE
.PP
\fB\-P \fR\fB\fIpreload\fR\fR
.RS 4
Initiate
\fIpreload\fR
exchanges back to back at startup\&.
\fIpreload\fR
must be 0 (the default) or a positive integer\&.
.RE
.PP
\fB\-r \fR\fB\fIrate\fR\fR
.RS 4
Initiate
\fIrate\fR
DORA/SARR (or if
\fB\-i\fR
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\&.
.RE
.PP
\fB\-R \fR\fB\fInum\-clients\fR\fR
.RS 4
Specify how many different clients are used\&. With a value of 1 (the default), all requests seem to come from the same client\&.
\fInum\-clients\fR
must be a positive number\&.
.RE
.PP
\fB\-s \fR\fB\fIseed\fR\fR
.RS 4
Specify the seed for randomization, making runs of
\fBperfdhcp\fR
repeatable\&.
\fIseed\fR
is 0 or a positive integer\&. The value 0 means that a seed is not used; this is the default\&.
.RE
.PP
\fB\-T \fR\fB\fItemplate\-file\fR\fR
.RS 4
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)\&.
.RE
.PP
\fB\-v\fR
.RS 4
Print the version of this program\&.
.RE
.PP
\fB\-w \fR\fB\fIwrapped\fR\fR
.RS 4
Command to call with a single parameter of "start" or "stop" at the beginning/end of the program\&.
.RE
.PP
\fB\-x \fR\fB\fIdiagnostic\-selector\fR\fR
.RS 4
Include extended diagnostics in the output\&.
\fIdiagnostic\-selector\fR
is a string of single\-keywords specifying the operations for which verbose output is desired\&. The selector key letters are:
.PP
a
.RS 4
Print the decoded command line arguments\&.
.RE
.PP
e
.RS 4
Print the exit reason\&.
.RE
.PP
i
.RS 4
Print rate processing details\&.
.RE
.PP
s
.RS 4
Print the first server\-ID\&.
.RE
.PP
t
.RS 4
When finished, print timers of all successful exchanges\&.
.RE
.PP
T
.RS 4
When finished, print templates
.RE
.RE
.SS "DHCPv4\-Only Options"
.PP
The following options only apply for DHCPv4 (i\&.e\&. when
\fB\-4\fR
is given)\&.
.PP
\fB\-B\fR
.RS 4
Force broadcast handling\&.
.RE
.SS "DHCPv6\-Only Options"
.PP
The following options only apply for DHCPv6 (i\&.e\&. when
\fB\-6\fR
is given)\&.
.PP
\fB\-c\fR
.RS 4
Add a rapid commit option (exchanges will be SOLICIT\-ADVERTISE)\&.
.RE
.PP
\fB\-F \fR\fB\fIrelease\-rate\fR\fR
.RS 4
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
\fB\-r \fR\fB\fIrate\fR\fR)\&. Furthermore the sum of this value and the renew\-rate (given by
\fB\-f \fR\fB\fIrate\fR\fR) must be equal to or less than the exchange rate\&.
.RE
.PP
\fB\-A \fR\fB\fIencapsulation\-level\fR\fR
.RS 4
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
\fIencapsulation\-level\fR
value is 1, which means that the generated traffic is an equivalent of the traffic passing through a single relay agent\&.
.RE
.SS "Template\-Related Options"
.PP
The following options may only be used in conjunction with
\fB\-T\fR
and control how
\fBperfdhcp\fR
modifies the template\&. The options may be specified multiple times on the command line; each occurrence affects the corresponding template file (see "TEMPLATES" above)\&.
.PP
\fB\-E \fR\fB\fItime\-offset\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-I \fR\fB\fIip\-offset\fR\fR
.RS 4
Offset of the (DHCPv4) IP address in the requested\-IP option / (DHCPv6) IA_NA option in the (second/request) template\&.
.RE
.PP
\fB\-O \fR\fB\fIrandom\-offset\fR\fR
.RS 4
Offset of the last octet to randomize in the template\&.
\fIrandom\-offset\fR
must be an integer greater than 3\&. The
\fB\-T\fR
switch must be given to use this option\&.
.RE
.PP
\fB\-S \fR\fB\fIsrvid\-offset\fR\fR
.RS 4
Offset of the server\-ID option in the (second/request) template\&.
\fIsrvid\-offset\fR
must be a positive integer, and the switch can only be used when the template option (\fB\-T\fR) is also given\&.
.RE
.PP
\fB\-X \fR\fB\fIxid\-offset\fR\fR
.RS 4
Offset of the transaction ID (xid) in the template\&.
\fIxid\-offset\fR
must be a positive integer, and the switch can only be used when the template option (\fB\-T\fR) is also given\&.
.RE
.SS "Options Controlling a Test"
.PP
The following options may only be used in conjunction with
\fB\-r\fR
and control both the length of the test and the frequency of reports\&.
.PP
\fB\-D \fR\fB\fImax\-drop\fR\fR
.RS 4
Abort the test if more than
\fImax\-drop\fR
requests have been dropped\&. Use
\fB\-D 0\fR
to abort if even a single request has been dropped\&. If
\fImax\-drop\fR
includes the suffix \*(Aq%\*(Aq, 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\&.
.RE
.PP
\fB\-n \fR\fB\fInum\-requests\fR\fR
.RS 4
Initiate
\fInum\-request\fR
transactions\&. No report is generated until all transactions have been initiated/waited\-for, after which a report is generated and the program terminates\&.
.RE
.PP
\fB\-p \fR\fB\fItest\-period\fR\fR
.RS 4
Send requests for
\fItest\-period\fR, which is specified in the same manner as
\fB\-d\fR\&. This can be used as an alternative to
\fB\-n\fR, or both options can be given, in which case the testing is completed when either limit is reached\&.
.RE
.PP
\fB\-t \fR\fB\fIinterval\fR\fR
.RS 4
Sets the delay (in seconds) between two successive reports\&.
.RE
.SS "Arguments"
.PP
server
.RS 4
Server to test, specified as an IP address\&. In the DHCPv6 case, the special name \*(Aqall\*(Aq can be used to refer to All_DHCP_Relay_Agents_and_Servers (the multicast address FF02::1:2), or the special name \*(Aqservers\*(Aq to refer to All_DHCP_Servers (the multicast address FF05::1:3)\&. The server is mandatory except where the
\fB\-l\fR
option is given to specify an interface, in which case it defaults to \*(Aqall\*(Aq\&.
.RE
.SH "ERRORS"
.PP
\fBperfdhcp\fR
can report the following errors in the packet exchange:
.PP
tooshort
.RS 4
A message was received that was too short\&.
.RE
.PP
orphans
.RS 4
Received a message which doesn\*(Aqt 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)\&.
.RE
.PP
locallimit
.RS 4
Reached local system limits when sending a message\&.
.RE
.SH "EXIT STATUS"
.PP
\fBperfdhcp\fR
can exit with one of the following status codes:
.PP
0
.RS 4
Success\&.
.RE
.PP
1
.RS 4
General error\&.
.RE
.PP
2
.RS 4
Error in command\-line arguments\&.
.RE
.PP
3
.RS 4
No general failures in operation, but one or more exchanges were unsuccessful\&.
.RE
.SH "MAILING LISTS AND SUPPORT"
.PP
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\&.
.PP
ISC provides professional support for Kea services\&. See https://www\&.isc\&.org/kea/ for details\&.
.SH "HISTORY"
.PP
The
\fBperfdhcp\fR
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\&.
.SH "SEE ALSO"
.PP
\fBkea-dhcp4\fR(8),
\fBkea-dhcp6\fR(8),
\fBkea-dhcp-ddns\fR(8),
\fBkea-admin\fR(8),
\fBkeactrl\fR(8),
\fBkea-lfc\fR(8),
Kea Administrator\*(Aqs Guide\&.
.SH "AUTHOR"
.br
.PP
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\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2016 Internet Systems Consortium, Inc. ("ISC")
.br