[2230] Added perfdhcp command line examples.

tests/tools/dhcp-ubench/dhcp-perf-guide.xml

@@ -603,8 +603,7 @@ SQLite version: 3.7.9sourceid version is 2011-11-01 00:52:41 c7c6050ef060877ebe7
         well.
       </para>
     </section>
-
-    <section>
+    <section id="perfdhcp-key-features">
       <title>Key features</title>
       <para>
         The perfdhcp exposes the number of command line parameters to
@@ -615,8 +614,8 @@ SQLite version: 3.7.9sourceid version is 2011-11-01 00:52:41 c7c6050ef060877ebe7
             <para>
               Rate control - control how many DHCP exchanges
               are initiated within a period of time. Tool can also simulate
-              best effort conditions where it attempts to start as many
-              exchanges as possible.
+              best effort conditions attempting to initiate as many DHCP
+              packet exchanges within a unit of time as possible.
             </para>
           </listitem>
           <listitem>
@@ -661,7 +660,6 @@ SQLite version: 3.7.9sourceid version is 2011-11-01 00:52:41 c7c6050ef060877ebe7
         </orderedlist>
       </para>
     </section>
-
     <section id="perfdhcp-command-line">
       <title>Command line options</title>
       <para>
@@ -793,8 +791,8 @@ The exit status is:
         </screen>
       </para>
     </section>
-    <section>
-      <title>Running a test</title>
+    <section id="starting-perfdhcp">
+      <title>Starting perfdhcp</title>
       <para>
         In order to run performance test at least two separate systems
         have to be installed: client and server. The first one has to have
@@ -806,35 +804,262 @@ The exit status is:
       </para>
       <para>
         The DHCP operates on low port numbers (67 for DHCPv4 relays and
-        547 for DHCPv6) running perfdhcp with non-root priviliges will
+        547 for DHCPv6). Running perfdhcp with non-root priviliges will
         usually result in the error message similar to this:
         <screen><userinput>$./perfdhcp -4 -l eth3 -r 100 all</userinput>
 Error running perfdhcp: Failed to bind socket 3 to 172.16.1.2/port=67
         </screen>
-        perfdhcp exposes '-L' command line option that
-        imposes use of custom local port and the following command line will
-        work:
+        perfdhcp has the '-L' command line option that
+        imposes use of custom local port. Thus the following command
+        line will work:
         <screen><userinput>$./perfdhcp -4 -l eth3 -r 100 -L 10067 all</userinput></screen>
         but in the standard configuration no responses will be received
         from the ISC DHCP server because server responds to default relay
         port 67.
+        Alternative way to overcome this issue  is to run perfdhcp as root.
       </para>
       <para>
-        Alternative way to overcome the issue with lack of privileges
-        to use default DHCP port number is to run perfdhcp as root.
+        Currently, perfdhcp is seen from the server perspective as relay agent.
+        This simplifies its implementation (specifically there is no need to
+        receive traffic sent to braodcast addresses). This imposes that IPv4
+        address has to be set manually on the interface that will be used to
+        communicate with the server. For example, if DHCPv4 server is listening
+        on the interface connected to 172.16.1.0 subnet, interface on client
+        machine has to have network address assigned from the same subnet
+        on one of its interfaces connected to this subnet:
+        <screen><userinput>#ifconfig eth3 172.16.1.2. netmask 255.255.255.0 up</userinput></screen>
       </para>
-
+    </section>
+    <section id="perfdhcp-commandline-examples">
+      <title>perfdhcp command line examples</title>
       <para>
-        In this section the perfdhcp command line options examples
+        In this section the perfdhcp command line examples
         are presented as a quick start guide for new users. For the
         detailed list of command line options refer to
         <xref linkend="perfdhcp-command-line"/>.
       </para>
-      <para>
-        <screen>
-          <userinput></userinput>
-        </screen>
-      </para>
+      <section id="perfdhcp-basic-usage">
+        <title>Example: basic usage</title>
+        <para>
+          If server is listening on interface with IPv4 address 172.16.1.1
+          the simpliest perfdhcp command line will look like this:
+          <screen><userinput>#./perfdhcp 172.16.1.1</userinput>
+***Rate statistics***
+Rate: 206.345
+
+***Statistics for: DISCOVER-OFFER***
+sent packets: 21641
+received packets: 350
+drops: 21291
+orphans: 0
+
+min delay: 9.022 ms
+avg delay: 143.100 ms
+max delay: 259.303 ms
+std deviation: 56.074 ms
+collected packets: 30
+
+***Statistics for: REQUEST-ACK***
+sent packets: 350
+received packets: 268
+drops: 82
+orphans: 0
+
+min delay: 3.010 ms
+avg delay: 152.470 ms
+max delay: 258.634 ms
+std deviation: 56.936 ms
+collected packets: 0
+          </screen>
+          In this case perfdhcp will use remote address 172.16.1.1 as a
+          destination address and will use suitable local interface for
+          communication. Since, no rate control parameters have been specified
+          it will be initiating DHCP exchanges with the maximum possible
+          rate (it will try to initiate maximum number of exchanges per
+          second and count number of completed exchanged). Due to server's
+          performance constraints, many DHCP packets sent to server are likely
+          to be dropped. The performance test will be running until it is
+          not interrupted by the user (with ^C).
+        </para>
+        <para>
+          The default performance statistics reported by perfdhcp have the
+          following meaning:
+          <itemizedlist>
+            <listitem><para>Rate - number of packet exchanges (packet sent
+            to the server and matching response received from the server)
+            completed within a second.</para></listitem>
+            <listitem><para>sent packets - total number of DHCP packets of
+            a specific type sent to the server.</para></listitem>
+            <listitem><para>received packets - total number of DHCP packets
+            of specific type received from the server.</para></listitem>
+            <listitem><para>drops - number of dropped packets for the
+            particular exchange. Number of dropped packets is calculated as
+            a difference between number of sent packets and number of
+            response packets received from the server. It is likely that
+            server sent the reponse but perfdhcp execution had ended before
+            reponse arrived. In such case this packet will be assumed
+            dropped.</para></listitem>
+            <listitem><para>orphans - number of packets that have been
+            received from the server and did not match any packet sent by
+            perfdhcp. This may occur if received packet has been sent
+            to some other host or if exchange time out has occured and
+            has been been garbage collected.</para></listitem>
+            <listitem><para>min delay - minimum delay that occured between
+            sending the packet to the server and receiving reponse from
+            it.</para></listitem>
+            <listitem><para>avg delay - average delay between sending the
+            packet of the specific type the server and receiving response
+            from it.</para></listitem>
+            <listitem><para>max delay - maximum delat that occured between
+            sedning the packet to the server and receiveing response from
+            it.</para></listitem>
+            <listitem><para>std deviation - standard deviation of delay
+            between sending the packet of a specific type to the server and
+            receiving response from it.</para></listitem>
+            <listitem><para>collected packets - number of garbage collected
+            sent packets. Packets may get garbage collected when waiting time
+            for server response exceeds value set with
+            <![CDATA[-d<drop-time>]]>.</para></listitem>
+          </itemizedlist>
+        </para>
+        <para>
+          perfdhcp allows to run the test using specified interface:
+          <screen><userinput>#./perfdhcp -l eth3</userinput></screen>
+          or local address assigned to it:
+          <screen><userinput>#./perfdhcp -l 172.16.1.2</userinput></screen>
+        </para>
+      </section>
+      <section id="perfdhcp-rate-control">
+        <title>Example: rate control</title>
+        <para>
+          In the examples above perfdhcp initiates new exchanges with best
+          effort rate. In this case many packets is expected to be dropped by the
+          server due to performance limitations. Many times it is desired to set
+          the expected (reasonable) rate and verify if generated traffic is
+          handled without packet dropes by DHCP server. The following command will
+          make perfdhcp to initiate 300 4-way exchanges per second and test will
+          last for 60 seconds:
+          <screen><userinput>#./perfdhcp -l eth3 -p 60 -r 300</userinput>
+***Rate statistics***
+Rate: 256.683 exchanges/second, expected rate: 300 exchanges/second
+
+***Statistics for: DISCOVER-OFFER***
+sent packets: 17783
+received packets: 15401
+drops: 2382
+orphans: 0
+
+min delay: 0.109 ms
+avg delay: 75.756 ms
+max delay: 575.614 ms
+std deviation: 60.513 ms
+collected packets: 11
+
+***Statistics for: REQUEST-ACK***
+sent packets: 15401
+received packets: 15317
+drops: 84
+orphans: 0
+
+min delay: 0.536 ms
+avg delay: 72.072 ms
+max delay: 576.749 ms
+std deviation: 58.189 ms
+collected packets: 0
+          </screen>
+          Note that in this example the packet drops have been significantly
+          reduced thanks to setting reasonable rate. The non-zero number of
+          packet drops and achived rate (256/s) below expected rate (300/s)
+          indicate that server's measured performance is lower than 300 leases
+          per second. Further rate decrease should eliminate most of the packet
+          drops and bring achived rate close to expected rate:
+          <screen><userinput>#./perfdhcp -l eth3 -p 60 -r 100 -R 30</userinput>
+***Rate statistics***
+Rate: 99.8164 exchanges/second, expected rate: 100 exchanges/second
+
+***Statistics for: DISCOVER-OFFER***
+sent packets: 5989
+received packets: 5989
+drops: 0
+orphans: 0
+
+min delay: 0.023 ms
+avg delay: 2.198 ms
+max delay: 181.760 ms
+std deviation: 9.429 ms
+collected packets: 0
+
+***Statistics for: REQUEST-ACK***
+sent packets: 5989
+received packets: 5989
+drops: 0
+orphans: 0
+
+min delay: 0.473 ms
+avg delay: 2.355 ms
+max delay: 189.658 ms
+std deviation: 5.876 ms
+collected packets: 0
+          </screen>
+          Note that the last parameter (-R 30) configures perfdhcp to simulate
+          traffic from distinct 30 clients.
+        </para>
+      </section>
+      <section id="perfdhcp-templates">
+        <title>Example: templates</title>
+        <para>
+          By default the DHCP messages are formed in-flight with default options.
+          If desired, there is a way to define custom packet format with template
+          files. Content in template files is encoded in hexadecimal format. The
+          perfdhcp forms the packet by replacing parts of the binary stream read
+          from the file with variable data such as elapsed time, HW address, DUID
+          etc. The offsets where such variable data is placed is specific to the
+          template file and have to be specified from the command line. Refer to
+          <xref linkend="perfdhcp-command-line"/> to find out how to
+          specify offsets for particular options and fields. With the following
+          command line the DHCPv6 SOLICIT and REQUEST packets will be formed from
+          solicit-example.hex and request6-example.hex packets:
+          <screen><userinput>#./perfdhcp -6 -l eth3 -r 100 -R 20 -T templates/solicit-example.hex -T templates/request6-example.hex -O 21 -E 84 -S 22 -I 40 servers</userinput>
+***Rate statistics***
+Rate: 99.5398 exchanges/second, expected rate: 100 exchanges/second
+
+***Statistics for: SOLICIT-ADVERTISE***
+sent packets: 570
+received packets: 569
+drops: 1
+orphans: 0
+
+min delay: 0.259 ms
+avg delay: 0.912 ms
+max delay: 6.979 ms
+std deviation: 0.709 ms
+collected packets: 0
+
+***Statistics for: REQUEST-REPLY***
+sent packets: 569
+received packets: 569
+drops: 0
+orphans: 0
+
+min delay: 0.084 ms
+avg delay: 0.607 ms
+max delay: 6.490 ms
+std deviation: 0.518 ms
+collected packets: 0
+          </screen>
+          where:
+          <itemizedlist>
+            <listitem><para>two occurences of -O 21 - DUID's last octet
+            positions in SOLICIT and REQUEST respectively.</para></listitem>
+            <listitem><para>-E 84 - elapsed time option position in
+            REQUEST template</para></listitem>
+            <listitem><para>-S 22 - server id position in REQUEST
+            template</para></listitem>
+            <listitem><para>-I 40 - IA_NA option position in REQUEST
+            template</para></listitem>
+          </itemizedlist>
+        </para>
+      </section>
     </section>
   </chapter>
 </book>