From: Andrei Pavel <andrei@isc.org>
Date: Tue, 25 May 2021 16:54:57 +0000 (+0300)
Subject: [#1119] perfdhcp usage as raw string literal
X-Git-Tag: Kea-1.9.9~109
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2ab5b504ed6b176599a7354da8e162cf2c59fd35;p=thirdparty%2Fkea.git

[#1119] perfdhcp usage as raw string literal
---

diff --git a/src/bin/perfdhcp/command_options.cc b/src/bin/perfdhcp/command_options.cc
index 60d3a87f1f..cb2f79f9f0 100644
--- a/src/bin/perfdhcp/command_options.cc
+++ b/src/bin/perfdhcp/command_options.cc
@@ -1168,184 +1168,186 @@ CommandOptions::printCommandLine() const {
 void
 CommandOptions::usage() {
     std::cout <<
-        "perfdhcp [-1] [-4 | -6] [-A encapsulation-level] [-b base] [-B] [-c]\n"
-        "         [-C separator] [-d drop-time] [-D max-drop] [-e lease-type]\n"
-        "         [-E time-offset] [-f renew-rate] [-F release-rate] [-g thread-mode]\n"
-        "         [-h] [-i] [-I ip-offset] [-J remote-address-list-file]\n"
-        "         [-l local-address|interface] [-L local-port] [-M mac-list-file]\n"
-        "         [-n num-request] [-N remote-port] [-O random-offset]\n"
-        "         [-o code,hexstring] [-p test-period] [-P preload] [-r rate]\n"
-        "         [-R num-clients] [-s seed] [-S srvid-offset] [--scenario name]\n"
-        "         [-t report] [-T template-file] [-u] [-v] [-W exit-wait-time]\n"
-        "         [-w script_name] [-x diagnostic-selector] [-X xid-offset] [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"
-        "The other scenario is an avalanche which is selected by\n"
-        "--scenario avalanche. It first sends as many Discovery or Solicit\n"
-        "messages as request in -R option then back off mechanism is used for\n"
-        "each simulated client until all requests are answered. At the end\n"
-        "time of whole scenario is reported.\n"
-        "\n"
-        "Options:\n"
-        "-1: Take the server-ID option from the first received message.\n"
-        "-4: DHCPv4 operation (default). This is incompatible with the -6 option.\n"
-        "-6: DHCPv6 operation. This is incompatible with the -4 option.\n"
-        "-b<base>: The base mac, duid, IP, etc, used to simulate different\n"
-        "    clients.  This can be specified multiple times, each instance is\n"
-        "    in the <type>=<value> form, for instance:\n"
-        "    (and default) mac=00:0c:01:02:03:04.\n"
-        "-d<drop-time>: Specify the time after which a request is treated as\n"
-        "    having been lost.  The value is given in seconds and may contain a\n"
-        "    fractional component.  The default is 1 second.\n"
-        "-e<lease-type>: A type of lease being requested from the server. It\n"
-        "    may be one of the following: address-only, prefix-only or\n"
-        "    address-and-prefix. The address-only indicates that the regular\n"
-        "    address (v4 or v6) will be requested. The prefix-only indicates\n"
-        "    that the IPv6 prefix will be requested. The address-and-prefix\n"
-        "    indicates that both IPv6 address and prefix will be requested.\n"
-        "    The '-e prefix-only' and -'e address-and-prefix' must not be\n"
-        "    used with -4.\n"
-        "-E<time-offset>: Offset of the (DHCPv4) secs field / (DHCPv6)\n"
-        "    elapsed-time option in the (second/request) template.\n"
-        "    The value 0 disables it.\n"
-        "-f<renew-rate>: Rate at which DHCPv4 or DHCPv6 renew requests are sent\n"
-        "    to a server. This value is only valid when used in conjunction\n"
-        "    with the exchange rate (given by -r<rate>).  Furthermore the sum of\n"
-        "    this value and the release-rate (given by -F<rate) must be equal\n"
-        "    to or less than the exchange rate.\n"
-        "-g<thread-mode>: 'single' or 'multi'. In multi-thread mode packets\n"
-        "    are received in separate thread. This allows better utilisation of CPUs.\n"
-        "    If more than 1 CPU is present then multi-thread mode is the default,\n"
-        "    otherwise single-thread is the default.\n"
-        "-h: Print this help.\n"
-        "-i: Do only the initial part of an exchange: DO or SA, depending on\n"
-        "    whether -6 is given.\n"
-        "-I<ip-offset>: Offset of the (DHCPv4) IP address in the requested-IP\n"
-        "    option / (DHCPv6) IA_NA option in the (second/request) template.\n"
-        "-J<remote-address-list-file>: Text file that include multiple addresses.\n"
-        "    If provided perfdhcp will choose randomly one of addresses for each\n"
-        "    exchange.\n"
-        "-l<local-addr|interface>: For DHCPv4 operation, specify the local\n"
-        "    hostname/address to use when communicating with the server.  By\n"
-        "    default, the interface address through which traffic would\n"
-        "    normally be routed to the server is used.\n"
-        "    For DHCPv6 operation, specify the name of the network interface\n"
-        "    via which exchanges are initiated.\n"
-        "-L<local-port>: Specify the local port to use\n"
-        "    (the value 0 means to use the default).\n"
-        "-M<mac-list-file>: A text file containing a list of MAC addresses,\n"
-        "   one per line. If provided, a MAC address will be chosen randomly\n"
-        "   from this list for every new exchange. In the DHCPv6 case, MAC\n"
-        "   addresses are used to generate DUID-LLs. This parameter must not be\n"
-        "   used in conjunction with the -b parameter.\n"
-        "-N<remote-port>: Specify the remote port to use\n"
-        "    (the value 0 means to use the default).\n"
-        "-o<code,hexstring>: Send custom option with the specified code and the\n"
-        "    specified buffer in hexstring format.\n"
-        "-O<random-offset>: Offset of the last octet to randomize in the template.\n"
-        "-P<preload>: Initiate first <preload> exchanges back to back at startup.\n"
-        "-r<rate>: Initiate <rate> DORA/SARR (or if -i is given, DO/SA)\n"
-        "    exchanges per second.  A periodic report is generated showing the\n"
-        "    number of exchanges which were not completed, as well as the\n"
-        "    average response latency.  The program continues until\n"
-        "    interrupted, at which point a final report is generated.\n"
-        "-R<range>: Specify how many different clients are used. With 1\n"
-        "    (the default), all requests seem to come from the same client.\n"
-        "-s<seed>: Specify the seed for randomization, making it repeatable.\n"
-        "--scenario <name>: where name is 'basic' (default) or 'avalanche'.\n"
-        "-S<srvid-offset>: Offset of the server-ID option in the\n"
-        "    (second/request) template.\n"
-        "-T<template-file>: The name of a file containing the template to use\n"
-        "    as a stream of hexadecimal digits.\n"
-        "-u: Enable checking address uniqueness. Lease valid lifetime\n"
-        "    should not be shorter than test duration.\n"
-        "-v: Report the version number of this program.\n"
-        "-W<time>: Specifies exit-wait-time parameter, that makes perfdhcp wait\n"
-        "    for <time> us after an exit condition has been met to receive all\n"
-        "    packets without sending any new packets. Expressed in microseconds.\n"
-        "-w<wrapped>: Command to call with start/stop at the beginning/end of\n"
-        "    the program.\n"
-        "-x<diagnostic-selector>: Include extended diagnostics in the output.\n"
-        "    <diagnostic-selector> is a string of single-keywords specifying\n"
-        "    the operations for which verbose output is desired.  The selector\n"
-        "    key letters are:\n"
-        "   * 'a': print the decoded command line arguments\n"
-        "   * 'e': print the exit reason\n"
-        "   * 'i': print rate processing details\n"
-        "   * 'l': print received leases\n"
-        "   * 's': print first server-id\n"
-        "   * 't': when finished, print timers of all successful exchanges\n"
-        "   * 'T': when finished, print templates\n"
-        "-X<xid-offset>: Transaction ID (aka. xid) offset in the template.\n"
-        "-Y<time>: time in seconds after which perfdhcp will start sending\n"
-        "    messages with increased elapsed time option.\n"
-        "-y<time>: period of time in seconds in which perfdhcp will be sending\n"
-        "    messages with increased elapsed time option.\n"
-        "DHCPv4 only options:\n"
-        "-B: Force broadcast handling.\n"
-        "\n"
-        "DHCPv6 only options:\n"
-        "-c: Add a rapid commit option (exchanges will be SA).\n"
-        "-F<release-rate>: Rate at which IPv6 Release requests are sent to\n"
-        "    a server. This value is only valid when used in conjunction with\n"
-        "    the exchange rate (given by -r<rate>).  Furthermore the sum of\n"
-        "    this value and the renew-rate (given by -f<rate) must be equal\n"
-        "    to or less than the exchange rate.\n"
-        "-A<encapsulation-level>: Specifies that relayed traffic must be\n"
-        "    generated. The argument specifies the level of encapsulation, i.e.\n"
-        "    how many relay agents are simulated. Currently the only supported\n"
-        "    <encapsulation-level> value is 1, which means that the generated\n"
-        "    traffic is an equivalent of the traffic passing through a single\n"
-        "    relay agent.\n"
-        "\n"
-        "The remaining options are typically used in conjunction with -r:\n"
-        "\n"
-        "-D<max-drop>: Abort the test immediately if max-drop requests have\n"
-        "    been dropped.  max-drop must be a positive integer. If max-drop\n"
-        "    includes the suffix '%', it specifies a maximum percentage of\n"
-        "    requests that may be dropped before abort. In this case, testing\n"
-        "    of the threshold begins after 10 requests have been expected to\n"
-        "    be received.\n"
-        "-n<num-request>: Initiate <num-request> transactions.  No report is\n"
-        "    generated until all transactions have been initiated/waited-for,\n"
-        "    after which a report is generated and the program terminates.\n"
-        "-p<test-period>: Send requests for the given test period, which is\n"
-        "    specified in the same manner as -d.  This can be used as an\n"
-        "    alternative to -n, or both options can be given, in which case the\n"
-        "    testing is completed when either limit is reached.\n"
-        "-t<report>: Delay in seconds between two periodic reports.\n"
-        "-C<separator>: Output reduced, an argument is a separator for periodic\n"
-        "    (-t) reports generated in easy parsable mode. Data output won't be\n"
-        "    changed, remain identical as in -t option.\n"
-        "\n"
-        "Errors:\n"
-        "- tooshort: received a too short message\n"
-        "- orphans: received a message which doesn't match an exchange\n"
-        "   (duplicate, late or not related)\n"
-        "- locallimit: reached to local system limits when sending a message.\n"
-        "\n"
-        "Exit status:\n"
-        "The exit status is:\n"
-        "0 on complete success.\n"
-        "1 for a general error.\n"
-        "2 if an error is found in the command line arguments.\n"
-        "3 if there are no general failures in operation, but one or more\n"
-        "  exchanges are not successfully completed.\n";
+R"(perfdhcp [-1] [-4 | -6] [-A encapsulation-level] [-b base] [-B] [-c]
+         [-C separator] [-d drop-time] [-D max-drop] [-e lease-type]
+         [-E time-offset] [-f renew-rate] [-F release-rate] [-g thread-mode]
+         [-h] [-i] [-I ip-offset] [-J remote-address-list-file]
+         [-l local-address|interface] [-L local-port] [-M mac-list-file]
+         [-n num-request] [-N remote-port] [-O random-offset]
+         [-o code,hexstring] [-p test-period] [-P preload] [-r rate]
+         [-R num-clients] [-s seed] [-S srvid-offset] [--scenario name]
+         [-t report] [-T template-file] [-u] [-v] [-W exit-wait-time]
+         [-w script_name] [-x diagnostic-selector] [-X xid-offset] [server]
+
+The [server] argument is the name/address of the DHCP server to
+contact.  For DHCPv4 operation, exchanges are initiated by
+transmitting a DHCP DISCOVER to this address.
+
+For DHCPv6 operation, exchanges are initiated by transmitting a DHCP
+SOLICIT to this 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]
+argument is optional only in the case that -l is used to specify an
+interface, in which case [server] defaults to 'all'.
+
+The default is to perform a single 4-way exchange, effectively pinging
+the server.
+The -r option is used to set up a performance test, without
+it exchanges are initiated as fast as possible.
+The other scenario is an avalanche which is selected by
+--scenario avalanche. It first sends as many Discovery or Solicit
+messages as request in -R option then back off mechanism is used for
+each simulated client until all requests are answered. At the end
+time of whole scenario is reported.
+
+Options:
+-1: Take the server-ID option from the first received message.
+-4: DHCPv4 operation (default). This is incompatible with the -6 option.
+-6: DHCPv6 operation. This is incompatible with the -4 option.
+-b<base>: The base mac, duid, IP, etc, used to simulate different
+    clients.  This can be specified multiple times, each instance is
+    in the <type>=<value> form, for instance:
+    (and default) mac=00:0c:01:02:03:04.
+-d<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.
+-e<lease-type>: A 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.
+-E<time-offset>: Offset of the (DHCPv4) secs field / (DHCPv6)
+    elapsed-time option in the (second/request) template.
+    The value 0 disables it.
+-f<renew-rate>: 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 -r<rate>).  Furthermore the sum of
+    this value and the release-rate (given by -F<rate>) must be equal
+    to or less than the exchange rate.
+-g<thread-mode>: 'single' or 'multi'. In multi-thread mode packets
+    are received in separate thread. This allows better utilisation of CPUs.
+    If more than 1 CPU is present then multi-thread mode is the default,
+    otherwise single-thread is the default.
+-h: Print this help.
+-i: Do only the initial part of an exchange: DO or SA, depending on
+    whether -6 is given.
+-I<ip-offset>: Offset of the (DHCPv4) IP address in the requested-IP
+    option / (DHCPv6) IA_NA option in the (second/request) template.
+-J<remote-address-list-file>: Text file that include multiple addresses.
+    If provided perfdhcp will choose randomly one of addresses for each
+    exchange.
+-l<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.
+-L<local-port>: Specify the local port to use
+    (the value 0 means to use the default).
+-M<mac-list-file>: A text file containing a list of MAC addresses,
+   one per line. If provided, a MAC address will be chosen 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.
+-N<remote-port>: Specify the remote port to use
+    (the value 0 means to use the default).
+-o<code,hexstring>: Send custom option with the specified code and the
+    specified buffer in hexstring format.
+-O<random-offset>: Offset of the last octet to randomize in the template.
+-P<preload>: Initiate first <preload> exchanges back to back at startup.
+-r<rate>: Initiate <rate> DORA/SARR (or if -i 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.
+-R<range>: Specify how many different clients are used. With 1
+    (the default), all requests seem to come from the same client.
+-s<seed>: Specify the seed for randomization, making it repeatable.
+--scenario <name>: where name is 'basic' (default) or 'avalanche'.
+-S<srvid-offset>: Offset of the server-ID option in the
+    (second/request) template.
+-T<template-file>: The name of a file containing the template to use
+    as a stream of hexadecimal digits.
+-u: Enable checking address uniqueness. Lease valid lifetime should not be
+    shorter than test duration and clients should not request address more than
+    once without releasing it first.
+-v: Report the version number of this program.
+-W<time>: Specifies exit-wait-time parameter, that makes perfdhcp wait
+    for <time> us after an exit condition has been met to receive all
+    packets without sending any new packets. Expressed in microseconds.
+-w<wrapped>: Command to call with start/stop at the beginning/end of
+    the program.
+-x<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
+    key letters are:
+   * 'a': print the decoded command line arguments
+   * 'e': print the exit reason
+   * 'i': print rate processing details
+   * 'l': print received leases
+   * 's': print first server-id
+   * 't': when finished, print timers of all successful exchanges
+   * 'T': when finished, print templates
+-X<xid-offset>: Transaction ID (aka. xid) offset in the template.
+-Y<time>: time in seconds after which perfdhcp will start sending
+    messages with increased elapsed time option.
+-y<time>: period of time in seconds in which perfdhcp will be sending
+    messages with increased elapsed time option.
+DHCPv4 only options:
+-B: Force broadcast handling.
+
+DHCPv6 only options:
+-c: Add a rapid commit option (exchanges will be SA).
+-F<release-rate>: Rate at which Release requests are sent to
+    a server. This value is only valid when used in conjunction with
+    the exchange rate (given by -r<rate>).  Furthermore the sum of
+    this value and the renew-rate (given by -f<rate>) must be equal
+    to or less than the exchange rate.
+-A<encapsulation-level>: 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
+    <encapsulation-level> value is 1, which means that the generated
+    traffic is an equivalent of the traffic passing through a single
+    relay agent.
+
+The remaining options are typically used in conjunction with -r:
+
+-D<max-drop>: Abort the test immediately if max-drop requests have
+    been dropped.  max-drop must be a positive integer. 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.
+-n<num-request>: 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.
+-p<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.
+-t<report>: Delay in seconds between two periodic reports.
+-C<separator>: Output reduced, an argument is a separator for periodic
+    (-t) reports generated in easy parsable mode. Data output won't be
+    changed, remain identical as in -t option.
+
+Errors:
+- tooshort: received a too short message
+- orphans: received a message which doesn't match an exchange
+   (duplicate, late or not related)
+- locallimit: reached to local system limits when sending a message.
+
+Exit status:
+The exit status is:
+0 on complete success.
+1 for a general error.
+2 if an error is found in the command line arguments.
+3 if there are no general failures in operation, but one or more
+  exchanges are not successfully completed.
+)";
 }
 
 void