From: Stephen Morris Date: Fri, 21 Feb 2014 16:04:08 +0000 (+0000) Subject: [2307] Added the full list of options to the perfdhcp man page X-Git-Tag: bind10-1.2.0beta1-release~21^2~3 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6ca0d329098fd60d5c6af5d0ea5c5a07eebf7de5;p=thirdparty%2Fkea.git [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. --- diff --git a/tests/tools/perfdhcp/perfdhcp.xml b/tests/tools/perfdhcp/perfdhcp.xml index 05a997ddf1..6f23ae4373 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" []> - - - - September 25, 2013 - - - - perfdhcp - 1 - BIND10 - - - - perfdhcp - DHCP benchmarking tool - - - - - 2013 - Internet Systems Consortium, Inc. ("ISC") - - - - - - - - - perfdhcp - - - - - - DESCRIPTION - perfdhcp 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). - - - - - - OPTIONS - - The arguments are as follows: - - - - - - - - - Take the server-ID option from the first received - message. - - - - - - - - - - - DHCPv4 operation. This is the default. This is incompatible - with the -6 option. - - - - - - - - - DHCPv6 operation. This is incompatible with the -4 - option. - - - - - - - aggressivity - - - 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. - - - - - - - - basetype=value - - - The base MAC or DUID used to simulate different clients. - The basetype - 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. - - - - - - - - drop-time - - - 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. - - - - - - - time-offset - - - 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. - - - - - - - lease-type - - - 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'.) - - - - - - - - - Print help. - - - - - - - - - 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. - - - - - - - - ip-offset - - - 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. - - - - - - - local-addr|interface - - - 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. - - - - - - - local-port - - - Specify the local port to use. - The value must be 0 or a positive integer up to 65535. - - The value 0 means to use the default. - - - - - - - random-offset - - - 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. - - - - - - - preload - - - Initiate first - preload - exchanges back to back at startup. - The value must be 0 or a positive integer. - - - - - - - - rate - - - Initiate - rate - 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. - - - - - - - range - - - 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. - - - - - - - - seed - - - 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. - - - - - - - srvid-offset - - - Offset of the server-ID option in the - (second/request) template. The value is a positive integer. - This is incompatible with the -i option. - - - - - - - template-file - - - The name of a file containing the template to use - as a stream of hexadecimal digits. - - - - - - - - - - Report the version number of this program. - - - - - - - wrapped - - - Command to call with start/stop at the - beginning/end of the program. - - - - - - - diagnostic-selector - - - Include extended diagnostics in the output. - diagnostic-selector - - 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. - - - - - - - xid-offset - - - Transaction ID (xid) offset in the - template. The value is a positive integer. - The -T switch must be used with -X. - - - - DHCPv4 only option: - - - - - - Force broadcast handling. This is a DHCPv4-only - (-4) option, and is not compatible with IPv6 (-6). - - - - - DHCPv6 only options: - - - - - - 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. - - - - The remaining options are used only in conjunction with - -r: - - - - - max-drop - - - Abort the test if more than - max-drop - requests have been dropped. Use -D0 - to abort if even a single request has been dropped. If - max-drop - 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. - The -D option must be used with the -r switch. - - - - - - - num-request - - - Initiate - num-request - 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. - The -n option must be used with the -r switch. - - - - - - - test-period - - - 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. - - - - - - - report - - - Delay in seconds between two periodic - reports. The value is a positive integer. - The -t option must be used with the -r switch. - - - - - + - - - - - - EXIT STATUS - - The perfdhcp utility exits with one of - the following values: - - - - - 0 - Complete success. - - - 1 - General error. - - - 2 - An error in the command line - arguments. - - - 3 - One or more exchanges were not successfully - completed (and no general failures in operation). - - - - - - SEE ALSO - - - b10-dhcp48 - , - - b10-dhcp68 - , - BIND 10 Guide, - DHCP Performance Guide. - - + + + February 19, 2014 + + + + perfdhcp + 1 + Kea + + + + perfdhcp + DHCP benchmarking tool + + + + + 2014 + Internet Systems Consortium, Inc. ("ISC") + + + + + + perfdhcp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + server + + + + + DESCRIPTION + + perfdhcp is a DHCP benchmarking tool. It provides a way of measuring the performance of DHCP + servers by generating large amounts of traffic from simulated multiple clients. It is able to test both IPv4 and + IPv6 servers, and provides statistics concerning response times and the number of requests that are dropped. + + + + 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. + + + + When running a performance test, perfdhcp will exchange packets with the server under test as + fast as possible unless the 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 perfdhcp, + the elapsed time, or the number of requests dropped by the server. + + + + + TEMPLATES + + To allow the contents of packets sent to the server to be customised, perfdhcp allows the + specification of template files that determine the contents of the packets. For example, the customized packet + may contain a DHCPv6 ORO to request a set of options to be returned by the 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). + + + + Up to two template files can be specified on the command line, each file representing the contents of a particular + type of packet, the type being determined by the test being carried out. For example, if testing DHCPv6: + + + + + + With no template files specified on the command line, perfdhcp will generate both + SOLICIT and ADVERTISE packets. + + + + With one template file specified, that file will be used as the pattern for SOLICIT packets: + perfdhcp will generate the ADVERTISE packets. + . + + + With two template files given on the command line, the first will be used as the pattern for SOLICIT + packets, the second as the pattern for ADVERTISE packets. + + + + + + (Similar determination applies to DHCPv4's DISCOVER and REQUEST packets.) + + + + The template file holds the DHCP packet represented as a stream of ASCII hexadecimal digits and it excludes + any IP/UDP stack headers. The template file must not contain any characters other than hexadecimal 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') + + + + 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 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. + + + + In many scenarios, perfdhcp 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 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. + + + + 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. + + + + + + OPTIONS + + + + + + + + Take the server-ID option from the first received + message. + + + + + + + + + DHCPv4 operation; this is the default. It is incompatible with the option. + + + + + + + + + DHCPv6 operation. This is incompatible with the option. + + + + + + + + + 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. + + + + + + + + + The base MAC or DUID used to simulate different clients. The basetype may be "mac" or "duid". (The keyword "ether" may + alternatively used for MAC.) The 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. + + + + + + + + + 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. + + + + + + + + + Specifies the type of lease being requested from the server. It may be one of the following: + + + + + address-only + + Only regular addresses (v4 or v6) will be requested. + + + + + prefix-only + + Only IPv6 prefixes will be requested. + + + + + address-and-prefix + + Both IPv6 addresses and prefixes will be requested. + + + + + + The and forms may not be used + with the option. + + + + + + + + + Print help and exit. + + + + + + + + + Do only the initial part of the exchange: DISCOVER-OFFER if is selected, + SOLICIT-ADVERTISE if is chosen. + + + + is incompatible with the following options: , , + , , , and . + In addition, it cannot be used with multiple instances of , + and . + + + + + + + + + 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. + + + + + + + + + Specify the local port to use. This must be zero or a positive integer up to 65535. A value of 0 + (the default) allows perfdhcp to choose its own port. + + + + + + + + + Initiate preload exchanges back to back at startup. + preload must be 0 (the default) or a positive integer. + + + + + + + + + Initiate rate DORA/SARR (or if 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. + + + + + + + + + Specify how many different clients are used. With a value of 1 (the default), all requests seem to come + from the same client. num-clients must be a positive number. + + + + + + + + + Specify the seed for randomization, making runs of perfdhcp repeatable. seed is 0 or a positive integer. The value 0 means that a seed is + not used; this is the default. + + + + + + + + + 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). + + + + + + + + + Print the version of this program. + + + + + + + + + Command to call with a single parameter of "start" or "stop" at the beginning/end of the program. + + + + + + + + + Include extended diagnostics in the output. diagnostic-selector 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 the first server-ID. + + + + + t + + When finished, print timers of all successful exchanges. + + + + + T + + When finished, print templates + + + + + + + + + + + DHCPv4-Only Options + + The following options only apply for DHCPv4 (i.e. when is given). + + + + + + + + Force broadcast handling. + + + + + + + + DHCPv6-Only Options + + The following options only apply for DHCPv6 (i.e. when is given). + + + + + + + + + Add a rapid commit option (exchanges will be + SOLICIT-ADVERTISE). + + + + + + + + + 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 ). Furthermore the sum of this value and the + release-rate (given by ) + must be equal to or less than the exchange rate. + + + + + + + + + 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 ). Furthermore the sum of this value and the + renew-rate (given by ) + must be equal to or less than the exchange rate. + + + + + + + + + Template-Related Options + + The following options may only be used in conjunction with and control how + perfdhcp modifies the template. The options may be specified multiple times on the command + line; each occurrence affects the corresponding template file (see "TEMPLATES" above). + + + + + + + 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. + + + + + + + + + Offset of the (DHCPv4) IP address in the requested-IP option / (DHCPv6) IA_NA option in the + (second/request) template. + + + + + + + + + Offset of the last octet to randomize in the template. random-offset must be an integer greater than 3. The + switch must be given to use this option. + + + + + + + + + Offset of the server-ID option in the (second/request) template. srvid-offset must be a positive integer, and the switch can only be + used when the template option () is also given. + + + + + + + + + Offset of the transaction ID (xid) in the template. xid-offset must be a positive integer, and the switch can only be + used when the template option () is also given. + + + + + + + Options Controlling a Test + + The following options may only be used in conjunction with and control both the length + of the test and the frequency of reports. + + + + + + + + + Abort the test if more than max-drop requests have + been dropped. Use to abort if even a single request has been dropped. + If max-drop 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. + + + + + + + + + Initiate num-request transactions. No report is + generated until all transactions have been initiated/waited-for, after which a report is generated + and the program terminates. + + + + + + + + + Send requests for test-period, which is specified in + the same manner as . This can be used as an alternative to , + or both options can be given, in which case the testing is completed when either limit is reached. + + + + + + + + + Sets the delay (in seconds) between two successive reports. + + + + + + + + + Arguments + + + + server + + + 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 is given to specify an interface, in which + case it defauls to 'all'. + + + + + + + + + + + ERRORS + + + perfdhcp can report the following errors in the packet exchange: + + + + + tooshort + + A message was received that was too short. + + + + + orphans + + + 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). + + + + + + locallimit + + Reached local system limits when sending a message. + + + + + + + + EXIT STATUS + + + perfdhcp can exit with one of the following status codes: + + + + + 0 + Success. + + + + + 1 + + General error. + + + + + 2 + + Error in command-line arguments. + + + + + 3 + + No general failures in operation, but one or more exchanges were unsuccessful. + + + + + + + + SEE ALSO + + b10-dhcp48, + b10-dhcp68, + BIND 10 Guide, + DHCP Performance Guide. + + - - - +