<?xml version="1.0"?>
<!DOCTYPE texinfo PUBLIC "-//GNU//DTD TexinfoML V4.13//EN" "http://www.gnu.org/software/texinfo/dtd/4.13/texinfo.dtd">
<texinfo xml:lang="en">
  <setfilename>netperf.xml</setfilename>
  <settitle>Care and Feeding of Netperf 2.5.X</settitle>
<!-- %**end of header -->
  <para>This is Rick Jones' feeble attempt at a Texinfo-based manual for the netperf benchmark.</para>
  <para>Copyright &copyright; 2005-2011 Hewlett-Packard Company</para>
  <quotation>
    <para>Permission is granted to copy, distribute and/or modify this document per the terms of the netperf source license, a copy of which can be found in the file <file>COPYING</file> of the basic netperf distribution.</para>
  </quotation>
  <titlepage>
    <booktitle>Care and Feeding of Netperf</booktitle>
    <booksubtitle>Versions 2.5.0 and Later</booksubtitle>
    <author>Rick Jones &lt;email&gt;&lt;emailaddress&gt;rick.jones2@hp.com&lt;/emailaddress&gt;&lt;/email&gt;</author>
<!-- this is here to start the copyright page -->
    <para>This is Rick Jones' feeble attempt at a Texinfo-based manual for the netperf benchmark.</para>
    <para>Copyright &copyright; 2005-2011 Hewlett-Packard Company</para>
    <quotation>
      <para>Permission is granted to copy, distribute and/or modify this document per the terms of the netperf source license, a copy of which can be found in the file <file>COPYING</file> of the basic netperf distribution.</para>
    </quotation>
  </titlepage>
<!-- begin with a table of contents -->
  <contents></contents>
  <node>
    <nodename>Top</nodename>
    <nodenext>Introduction</nodenext>
    <nodeprev>(dir)</nodeprev>
    <nodeup>(dir)</nodeup>
    <unnumbered>
      <title>Netperf Manual</title>
      <para>This is Rick Jones' feeble attempt at a Texinfo-based manual for the netperf benchmark.</para>
      <para>Copyright &copyright; 2005-2011 Hewlett-Packard Company</para>
      <quotation>
        <para>Permission is granted to copy, distribute and/or modify this document per the terms of the netperf source license, a copy of which can be found in the file <file>COPYING</file> of the basic netperf distribution.</para>
      </quotation>
      <menu>
        <menuentry>
          <menunode>Introduction</menunode>
          <menutitle>Introduction</menutitle>
          <menucomment>An introduction to netperf - what itis and what it is not.</menucomment>
        </menuentry>
        <menuentry>
          <menunode>Installing Netperf</menunode>
          <menutitle>Installing Netperf</menutitle>
          <menucomment>How to go about installing netperf.</menucomment>
        </menuentry>
        <menuentry>
          <menunode>The Design of Netperf</menunode>
          <menutitle>The Design of Netperf</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Global Command-line Options</menunode>
          <menutitle>Global Command-line Options</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Using Netperf to Measure Bulk Data Transfer</menunode>
          <menutitle>Using Netperf to Measure Bulk Data Transfer</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Using Netperf to Measure Request/Response</menunode>
          <menutitle>Using Netperf to Measure Request/Response </menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Using Netperf to Measure Aggregate Performance</menunode>
          <menutitle>Using Netperf to Measure Aggregate Performance</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Using Netperf to Measure Bidirectional Transfer</menunode>
          <menutitle>Using Netperf to Measure Bidirectional Transfer</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>The Omni Tests</menunode>
          <menutitle>The Omni Tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Other Netperf Tests</menunode>
          <menutitle>Other Netperf Tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Address Resolution</menunode>
          <menutitle>Address Resolution</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Enhancing Netperf</menunode>
          <menutitle>Enhancing Netperf</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Netperf4</menunode>
          <menutitle>Netperf4</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Concept Index</menunode>
          <menutitle>Concept Index</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Option Index</menunode>
          <menutitle>Option Index</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </unnumbered>
  </node>
  <node>
    <nodename>Introduction</nodename>
    <nodenext>Installing Netperf</nodenext>
    <nodeprev>Top</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>Introduction</title>
      <para><indexterm index="cp">Introduction</indexterm> Netperf is a benchmark that can be use to measure various aspect of networking performance.  The primary foci are bulk (aka unidirectional) data transfer and request/response performance using either TCP or UDP and the Berkeley Sockets interface.  As of this writing, the tests available either unconditionally or conditionally include:</para>
      <itemize>
        <itemfunction>&bullet;</itemfunction>
        <item>
          <para>TCP and UDP unidirectional transfer and request/response over IPv4 and IPv6 using the Sockets interface.</para>
        </item>
        <item>
          <para>TCP and UDP unidirectional transfer and request/response over IPv4 using the XTI interface.</para>
        </item>
        <item>
          <para>Link-level unidirectional transfer and request/response using the DLPI interface.</para>
        </item>
        <item>
          <para>Unix domain sockets</para>
        </item>
        <item>
          <para>SCTP unidirectional transfer and request/response over IPv4 and IPv6 using the sockets interface.</para>
        </item>
      </itemize>
      <para>While not every revision of netperf will work on every platform listed, the intention is that at least some version of netperf will work on the following platforms:</para>
      <itemize>
        <itemfunction>&bullet;</itemfunction>
        <item>
          <para>Unix - at least all the major variants.</para>
        </item>
        <item>
          <para>Linux</para>
        </item>
        <item>
          <para>Windows</para>
        </item>
        <item>
          <para>Others</para>
        </item>
      </itemize>
      <para>Netperf is maintained and informally supported primarily by Rick Jones, who can perhaps be best described as Netperf Contributing Editor.  Non-trivial and very appreciated assistance comes from others in the network performance community, who are too numerous to mention here. While it is often used by them, netperf is NOT supported via any of the formal Hewlett-Packard support channels.  You should feel free to make enhancements and modifications to netperf to suit your nefarious porpoises, so long as you stay within the guidelines of the netperf copyright.  If you feel so inclined, you can send your changes to <email><emailaddress>netperf-feedback@netperf.org</emailaddress><emailname>netperf-feedback</emailname></email> for possible inclusion into subsequent versions of netperf.</para>
      <para>It is the Contributing Editor's belief that the netperf license walks like open source and talks like open source. However, the license was never submitted for &ldquo;certification&rdquo; as an open source license.  If you would prefer to make contributions to a networking benchmark using a certified open source license, please consider netperf4, which is distributed under the terms of the GPLv2.</para>
      <para>The <email><emailaddress>netperf-talk@netperf.org</emailaddress><emailname>netperf-talk</emailname></email> mailing list is available to discuss the care and feeding of netperf with others who share your interest in network performance benchmarking. The netperf-talk mailing list is a closed list (to deal with spam) and you must first subscribe by sending email to <email><emailaddress>netperf-talk-request@netperf.org</emailaddress><emailname>netperf-talk-request</emailname></email>.</para>
      <menu>
        <menuentry>
          <menunode>Conventions</menunode>
          <menutitle>Conventions</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Conventions</nodename>
    <nodeprev>Introduction</nodeprev>
    <nodeup>Introduction</nodeup>
    <section>
      <title>Conventions</title>
      <para>A <dfn>sizespec</dfn> is a one or two item, comma-separated list used as an argument to a command-line option that can set one or two, related netperf parameters.  If you wish to set both parameters to separate values, items should be separated by a comma:</para>
      <example xml:space="preserve">parameter1,parameter2</example>
      <para>If you wish to set the first parameter without altering the value of the second from its default, you should follow the first item with a comma:</para>
      <example xml:space="preserve">parameter1,</example>
      <para>Likewise, precede the item with a comma if you wish to set only the second parameter:</para>
      <example xml:space="preserve">,parameter2</example>
      <para>An item with no commas:</para>
      <example xml:space="preserve">parameter1and2</example>
      <para>will set both parameters to the same value.  This last mode is one of the most frequently used.</para>
      <para>There is another variant of the comma-separated, two-item list called a <dfn>optionspec</dfn> which is like a sizespec with the exception that a single item with no comma:</para>
      <example xml:space="preserve">parameter1</example>
      <para>will only set the value of the first parameter and will leave the second parameter at its default value.</para>
      <para>Netperf has two types of command-line options.  The first are global command line options.  They are essentially any option not tied to a particular test or group of tests.  An example of a global command-line option is the one which sets the test type - <option>-t</option>.</para>
      <para>The second type of options are test-specific options.  These are options which are only applicable to a particular test or set of tests.  An example of a test-specific option would be the send socket buffer size for a TCP_STREAM test.</para>
      <para>Global command-line options are specified first with test-specific options following after a <code>--</code> as in:</para>
      <example xml:space="preserve">netperf &lt;global&gt; -- &lt;test-specific&gt;</example>
    </section>
  </node>
  <node>
    <nodename>Installing Netperf</nodename>
    <nodenext>The Design of Netperf</nodenext>
    <nodeprev>Introduction</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>Installing Netperf</title>
      <para><indexterm index="cp">Installation</indexterm> Netperf's primary form of distribution is source code.  This allows installation on systems other than those to which the authors have ready access and thus the ability to create binaries.  There are two styles of netperf installation.  The first runs the netperf server program - netserver - as a child of inetd.  This requires the installer to have sufficient privileges to edit the files <file>/etc/services</file> and <file>/etc/inetd.conf</file> or their platform-specific equivalents.</para>
      <para>The second style is to run netserver as a standalone daemon.  This second method does not require edit privileges on <file>/etc/services</file> and <file>/etc/inetd.conf</file> but does mean you must remember to run the netserver program explicitly after every system reboot.</para>
      <para>This manual assumes that those wishing to measure networking performance already know how to use anonymous FTP and/or a web browser. It is also expected that you have at least a passing familiarity with the networking protocols and interfaces involved. In all honesty, if you do not have such familiarity, likely as not you have some experience to gain before attempting network performance measurements.  The excellent texts by authors such as Stevens, Fenner and Rudoff and/or Stallings would be good starting points. There are likely other excellent sources out there as well.</para>
      <menu>
        <menuentry>
          <menunode>Getting Netperf Bits</menunode>
          <menutitle>Getting Netperf Bits</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Installing Netperf Bits</menunode>
          <menutitle>Installing Netperf Bits</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Verifying Installation</menunode>
          <menutitle>Verifying Installation</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Getting Netperf Bits</nodename>
    <nodenext>Installing Netperf Bits</nodenext>
    <nodeprev>Installing Netperf</nodeprev>
    <nodeup>Installing Netperf</nodeup>
    <section>
      <title>Getting Netperf Bits</title>
      <para>Gzipped tar files of netperf sources can be retrieved via <uref><urefurl>ftp://ftp.netperf.org/netperf</urefurl><urefdesc>anonymous FTP</urefdesc></uref> for &ldquo;released&rdquo; versions of the bits.  Pre-release versions of the bits can be retrieved via anonymous FTP from the <uref><urefurl>ftp://ftp.netperf.org/netperf/experimental</urefurl><urefdesc>experimental</urefdesc></uref> subdirectory.</para>
      <para>For convenience and ease of remembering, a link to the download site is provided via the <uref><urefurl>http://www.netperf.org/</urefurl><urefdesc>NetperfPage</urefdesc></uref></para>
      <para>The bits corresponding to each discrete release of netperf are <uref><urefurl>http://www.netperf.org/svn/netperf2/tags</urefurl><urefdesc>tagged</urefdesc></uref> for retrieval via subversion.  For example, there is a tag for the first version corresponding to this version of the manual - <uref><urefurl>http://www.netperf.org/svn/netperf2/tags/netperf-2.5.0</urefurl><urefdesc>netperf 2.5.0</urefdesc></uref>.  Those wishing to be on the bleeding edge of netperf development can use subversion to grab the <uref><urefurl>http://www.netperf.org/svn/netperf2/trunk</urefurl><urefdesc>top of trunk</urefdesc></uref>.  When fixing bugs or making enhancements, patches against the top-of-trunk are preferred.</para>
      <para>There are likely other places around the Internet from which one can download netperf bits.  These may be simple mirrors of the main netperf site, or they may be local variants on netperf.  As with anything one downloads from the Internet, take care to make sure it is what you really wanted and isn't some malicious Trojan or whatnot. Caveat downloader.</para>
      <para>As a general rule, binaries of netperf and netserver are not distributed from ftp.netperf.org.  From time to time a kind soul or souls has packaged netperf as a Debian package available via the apt-get mechanism or as an RPM.  I would be most interested in learning how to enhance the makefiles to make that easier for people.</para>
    </section>
  </node>
  <node>
    <nodename>Installing Netperf Bits</nodename>
    <nodenext>Verifying Installation</nodenext>
    <nodeprev>Getting Netperf Bits</nodeprev>
    <nodeup>Installing Netperf</nodeup>
    <section>
      <title>Installing Netperf</title>
      <para>Once you have downloaded the tar file of netperf sources onto your system(s), it is necessary to unpack the tar file, cd to the netperf directory, run configure and then make.  Most of the time it should be sufficient to just:</para>
      <example xml:space="preserve">gzcat netperf-&lt;version&gt;.tar.gz | tar xf -
cd netperf-&lt;version&gt;
./configure
make
make install</example>
      <para>Most of the &ldquo;usual&rdquo; configure script options should be present dealing with where to install binaries and whatnot.</para>
      <example xml:space="preserve">./configure --help</example>
      <para>should list all of those and more.  You may find the <code>--prefix</code> option helpful in deciding where the binaries and such will be put during the <code>make install</code>.</para>
      <para><indexterm index="vr">&ndash;enable-cpuutil, Configure</indexterm>If the netperf configure script does not know how to automagically detect which CPU utilization mechanism to use on your platform you may want to add a <code>--enable-cpuutil=mumble</code> option to the configure command.   If you have knowledge and/or experience to contribute to that area, feel free to contact <email><emailaddress>netperf-feedback@netperf.org</emailaddress></email>.</para>
      <para><indexterm index="vr">&ndash;enable-xti, Configure</indexterm><indexterm index="vr">&ndash;enable-unixdomain, Configure</indexterm><indexterm index="vr">&ndash;enable-dlpi, Configure</indexterm><indexterm index="vr">&ndash;enable-sctp, Configure</indexterm>Similarly, if you want tests using the XTI interface, Unix Domain Sockets, DLPI or SCTP it will be necessary to add one or more <code>--enable-[xti|unixdomain|dlpi|sctp]=yes</code> options to the configure command.  As of this writing, the configure script will not include those tests automagically.</para>
      <para><indexterm index="vr">&ndash;enable-omni, Configure</indexterm>Starting with version 2.5.0, netperf is migrating most of the &ldquo;classic&rdquo; netperf tests found in <file>src/nettest_bsd.c</file> to the so-called &ldquo;omni&rdquo; tests (aka &ldquo;two routines to run them all&rdquo;) found in <file>src/nettest_omni.c</file>.  This migration enables a number of new features such as greater control over what output is included, and new things to output.  The &ldquo;omni&rdquo; test is enabled by default in 2.5.0 and a number of the classic tests are migrated - you can tell if a test has been migrated from the presence of <code>MIGRATED</code> in the test banner.  If you encounter problems with either the omni or migrated tests, please first attempt to obtain resolution via <email><emailaddress>netperf-talk@netperf.org</emailaddress></email> or <email><emailaddress>netperf-feedback@netperf.org</emailaddress></email>.  If that is unsuccessful, you can add a <code>--enable-omni=no</code> to the configure command and the omni tests will not be compiled-in and the classic tests will not be migrated.</para>
      <para>Starting with version 2.5.0, netperf will include the &ldquo;burst mode&rdquo; functionality in a default compilation of the bits.  If you encounter problems with this, please first attempt to obtain help via <email><emailaddress>netperf-talk@netperf.org</emailaddress></email> or <email><emailaddress>netperf-feedback@netperf.org</emailaddress></email>.  If that is unsuccessful, you can add a <code>--enable-burst=no</code> to the configure command and the burst mode functionality will not be compiled-in.</para>
      <para>On some platforms, it may be necessary to precede the configure command with a CFLAGS and/or LIBS variable as the netperf configure script is not yet smart enough to set them itself.  Whenever possible, these requirements will be found in <file>README.<var>platform</var></file> files. Expertise and assistance in making that more automagic in the configure script would be most welcome.</para>
      <para><indexterm index="cp">Limiting Bandwidth</indexterm><indexterm index="cp">Bandwidth Limitation</indexterm><indexterm index="vr">&ndash;enable-intervals, Configure</indexterm><indexterm index="vr">&ndash;enable-histogram, Configure</indexterm>Other optional configure-time settings include <code>--enable-intervals=yes</code> to give netperf the ability to &ldquo;pace&rdquo; its _STREAM tests and <code>--enable-histogram=yes</code> to have netperf keep a histogram of interesting times.  Each of these will have some effect on the measured result.  If your system supports <code>gethrtime()</code> the effect of the histogram measurement should be minimized but probably still measurable.  For example, the histogram of a netperf TCP_RR test will be of the individual transaction times:</para>
      <example xml:space="preserve">netperf -t TCP_RR -H lag -v 2
TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to lag.hpl.hp.com (15.4.89.214) port 0 AF_INET : histogram
Local /Remote
Socket Size   Request  Resp.   Elapsed  Trans.
Send   Recv   Size     Size    Time     Rate
bytes  Bytes  bytes    bytes   secs.    per sec

16384  87380  1        1       10.00    3538.82
32768  32768
Alignment      Offset
Local  Remote  Local  Remote
Send   Recv    Send   Recv
    8      0       0      0
Histogram of request/response times
UNIT_USEC     :    0:    0:    0:    0:    0:    0:    0:    0:    0:    0
TEN_USEC      :    0:    0:    0:    0:    0:    0:    0:    0:    0:    0
HUNDRED_USEC  :    0: 34480:  111:   13:   12:    6:    9:    3:    4:    7
UNIT_MSEC     :    0:   60:   50:   51:   44:   44:   72:  119:  100:  101
TEN_MSEC      :    0:  105:    0:    0:    0:    0:    0:    0:    0:    0
HUNDRED_MSEC  :    0:    0:    0:    0:    0:    0:    0:    0:    0:    0
UNIT_SEC      :    0:    0:    0:    0:    0:    0:    0:    0:    0:    0
TEN_SEC       :    0:    0:    0:    0:    0:    0:    0:    0:    0:    0
&gt;100_SECS: 0
HIST_TOTAL:      35391</example>
      <para>The histogram you see above is basically a base-10 log histogram where we can see that most of the transaction times were on the order of one hundred to one-hundred, ninety-nine microseconds, but they were occasionally as long as ten to nineteen milliseconds</para>
      <para>The <option>--enable-demo=yes</option> configure option will cause code to be included to report interim results during a test run.  The rate at which interim results are reported can then be controlled via the global <option>-D</option> option.  Here is an example of <option>-D</option> output:</para>
      <example xml:space="preserve">$ src/netperf -D 1.35 -H tardy.hpl.hp.com -f M
MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to tardy.hpl.hp.com (15.9.116.144) port 0 AF_INET : demo
Interim result:    5.41 MBytes/s over 1.35 seconds ending at 1308789765.848
Interim result:   11.07 MBytes/s over 1.36 seconds ending at 1308789767.206
Interim result:   16.00 MBytes/s over 1.36 seconds ending at 1308789768.566
Interim result:   20.66 MBytes/s over 1.36 seconds ending at 1308789769.922
Interim result:   22.74 MBytes/s over 1.36 seconds ending at 1308789771.285
Interim result:   23.07 MBytes/s over 1.36 seconds ending at 1308789772.647
Interim result:   23.77 MBytes/s over 1.37 seconds ending at 1308789774.016
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    MBytes/sec

 87380  16384  16384    10.06      17.81</example>
      <para>Notice how the units of the interim result track that requested by the <option>-f</option> option.  Also notice that sometimes the interval will be longer than the value specified in the <option>-D</option> option.  This is normal and stems from how demo mode is implemented not by relying on interval timers or frequent calls to get the current time, but by calculating how many units of work must be performed to take at least the desired interval.</para>
      <para>Those familiar with this option in earlier versions of netperf will note the addition of the &ldquo;ending at&rdquo; text.  This is the time as reported by a <code>gettimeofday()</code> call (or its emulation) with a <code>NULL</code> timezone pointer.  This addition is intended to make it easier to insert interim results into an <uref><urefurl>http://oss.oetiker.ch/rrdtool/doc/rrdtool.en.html</urefurl><urefdesc>rrdtool</urefdesc></uref> Round-Robin Database (RRD).  A likely bug-riddled example of doing so can be found in <file>doc/examples/netperf_interim_to_rrd.sh</file>.  The time is reported out to milliseconds rather than microseconds because that is the most rrdtool understands as of the time of this writing.</para>
      <para>As of this writing, a <code>make install</code> will not actually update the files <file>/etc/services</file> and/or <file>/etc/inetd.conf</file> or their platform-specific equivalents.  It remains necessary to perform that bit of installation magic by hand.  Patches to the makefile sources to effect an automagic editing of the necessary files to have netperf installed as a child of inetd would be most welcome.</para>
      <para>Starting the netserver as a standalone daemon should be as easy as:</para>
      <example xml:space="preserve">$ netserver
Starting netserver at port 12865
Starting netserver at hostname 0.0.0.0 port 12865 and family 0</example>
      <para>Over time the specifics of the messages netserver prints to the screen may change but the gist will remain the same.</para>
      <para>If the compilation of netperf or netserver happens to fail, feel free to contact <email><emailaddress>netperf-feedback@netperf.org</emailaddress></email> or join and ask in <email><emailaddress>netperf-talk@netperf.org</emailaddress></email>.  However, it is quite important that you include the actual compilation errors and perhaps even the configure log in your email.  Otherwise, it will be that much more difficult for someone to assist you.</para>
    </section>
  </node>
  <node>
    <nodename>Verifying Installation</nodename>
    <nodeprev>Installing Netperf Bits</nodeprev>
    <nodeup>Installing Netperf</nodeup>
    <section>
      <title>Verifying Installation</title>
      <para>Basically, once netperf is installed and netserver is configured as a child of inetd, or launched as a standalone daemon, simply typing:</para>
      <example xml:space="preserve">netperf</example>
      <para>should result in output similar to the following:</para>
      <example xml:space="preserve">$ netperf
TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

 87380  16384  16384    10.00    2997.84</example>
    </section>
  </node>
  <node>
    <nodename>The Design of Netperf</nodename>
    <nodenext>Global Command-line Options</nodenext>
    <nodeprev>Installing Netperf</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>The Design of Netperf</title>
      <para><indexterm index="cp">Design of Netperf</indexterm> Netperf is designed around a basic client-server model.  There are two executables - netperf and netserver.  Generally you will only execute the netperf program, with the netserver program being invoked by the remote system's inetd or having been previously started as its own standalone daemon.</para>
      <para>When you execute netperf it will establish a &ldquo;control connection&rdquo; to the remote system.  This connection will be used to pass test configuration information and results to and from the remote system. Regardless of the type of test to be run, the control connection will be a TCP connection using BSD sockets.  The control connection can use either IPv4 or IPv6.</para>
      <para>Once the control connection is up and the configuration information has been passed, a separate &ldquo;data&rdquo; connection will be opened for the measurement itself using the API's and protocols appropriate for the specified test.  When the test is completed, the data connection will be torn-down and results from the netserver will be passed-back via the control connection and combined with netperf's result for display to the user.</para>
      <para>Netperf places no traffic on the control connection while a test is in progress.  Certain TCP options, such as SO_KEEPALIVE, if set as your systems' default, may put packets out on the control connection while a test is in progress.  Generally speaking this will have no effect on the results.</para>
      <menu>
        <menuentry>
          <menunode>CPU Utilization</menunode>
          <menutitle>CPU Utilization</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>CPU Utilization</nodename>
    <nodeprev>The Design of Netperf</nodeprev>
    <nodeup>The Design of Netperf</nodeup>
    <section>
      <title>CPU Utilization</title>
      <para><indexterm index="cp">CPU Utilization</indexterm> CPU utilization is an important, and alas all-too infrequently reported component of networking performance.  Unfortunately, it can be one of the most difficult metrics to measure accurately and portably.  Netperf will do its level best to report accurate CPU utilization figures, but some combinations of processor, OS and configuration may make that difficult.</para>
      <para>CPU utilization in netperf is reported as a value between 0 and 100% regardless of the number of CPUs involved.  In addition to CPU utilization, netperf will report a metric called a <dfn>service demand</dfn>.  The service demand is the normalization of CPU utilization and work performed.  For a _STREAM test it is the microseconds of CPU time consumed to transfer on KB (K == 1024) of data.  For a _RR test it is the microseconds of CPU time consumed processing a single transaction.   For both CPU utilization and service demand, lower is better.</para>
      <para>Service demand can be particularly useful when trying to gauge the effect of a performance change.  It is essentially a measure of efficiency, with smaller values being more efficient and thus &ldquo;better.&rdquo;</para>
      <para>Netperf is coded to be able to use one of several, generally platform-specific CPU utilization measurement mechanisms.  Single letter codes will be included in the CPU portion of the test banner to indicate which mechanism was used on each of the local (netperf) and remote (netserver) system.</para>
      <para>As of this writing those codes are:</para>
      <table>
        <tableitem>
          <tableterm><code>U</code></tableterm>
          <item>
            <para>The CPU utilization measurement mechanism was unknown to netperf or netperf/netserver was not compiled to include CPU utilization measurements. The code for the null CPU utilization mechanism can be found in <file>src/netcpu_none.c</file>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>I</code></tableterm>
          <item>
            <para>An HP-UX-specific CPU utilization mechanism whereby the kernel incremented a per-CPU counter by one for each trip through the idle loop. This mechanism was only available on specially-compiled HP-UX kernels prior to HP-UX 10 and is mentioned here only for the sake of historical completeness and perhaps as a suggestion to those who might be altering other operating systems. While rather simple, perhaps even simplistic, this mechanism was quite robust and was not affected by the concerns of statistical methods, or methods attempting to track time in each of user, kernel, interrupt and idle modes which require quite careful accounting.  It can be thought-of as the in-kernel version of the looper <code>L</code> mechanism without the context switch overhead. This mechanism required calibration.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>P</code></tableterm>
          <item>
            <para>An HP-UX-specific CPU utilization mechanism whereby the kernel keeps-track of time (in the form of CPU cycles) spent in the kernel idle loop (HP-UX 10.0 to 11.31 inclusive), or where the kernel keeps track of time spent in idle, user, kernel and interrupt processing (HP-UX 11.23 and later).  The former requires calibration, the latter does not.  Values in either case are retrieved via one of the pstat(2) family of calls, hence the use of the letter <code>P</code>.  The code for these mechanisms is found in <file>src/netcpu_pstat.c</file> and <file>src/netcpu_pstatnew.c</file> respectively.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>K</code></tableterm>
          <item>
            <para>A Solaris-specific CPU utilization mechanism whereby the kernel keeps track of ticks (eg HZ) spent in the idle loop.  This method is statistical and is known to be inaccurate when the interrupt rate is above epsilon as time spent processing interrupts is not subtracted from idle.  The value is retrieved via a kstat() call - hence the use of the letter <code>K</code>.  Since this mechanism uses units of ticks (HZ) the calibration value should invariably match HZ. (Eg 100) The code for this mechanism is implemented in <file>src/netcpu_kstat.c</file>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>M</code></tableterm>
          <item>
            <para>A Solaris-specific mechanism available on Solaris 10 and latter which uses the new microstate accounting mechanisms.  There are two, alas, overlapping, mechanisms.  The first tracks nanoseconds spent in user, kernel, and idle modes. The second mechanism tracks nanoseconds spent in interrupt.  Since the mechanisms overlap, netperf goes through some hand-waving to try to &ldquo;fix&rdquo; the problem.  Since the accuracy of the handwaving cannot be completely determined, one must presume that while better than the <code>K</code> mechanism, this mechanism too is not without issues.  The values are retrieved via kstat() calls, but the letter code is set to <code>M</code> to distinguish this mechanism from the even less accurate <code>K</code> mechanism.  The code for this mechanism is implemented in <file>src/netcpu_kstat10.c</file>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>L</code></tableterm>
          <item>
            <para>A mechanism based on &ldquo;looper&rdquo;or &ldquo;soaker&rdquo; processes which sit in tight loops counting as fast as they possibly can. This mechanism starts a looper process for each known CPU on the system.  The effect of processor hyperthreading on the mechanism is not yet known.  This mechanism definitely requires calibration.  The code for the &ldquo;looper&rdquo;mechanism can be found in <file>src/netcpu_looper.c</file></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>N</code></tableterm>
          <item>
            <para>A Microsoft Windows-specific mechanism, the code for which can be found in <file>src/netcpu_ntperf.c</file>.  This mechanism too is based on what appears to be a form of micro-state accounting and requires no calibration.  On laptops, or other systems which may dynamically alter the CPU frequency to minimize power consumption, it has been suggested that this mechanism may become slightly confused, in which case using BIOS/uEFI settings to disable the power saving would be indicated.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>S</code></tableterm>
          <item>
            <para>This mechanism uses <file>/proc/stat</file> on Linux to retrieve time (ticks) spent in idle mode.  It is thought but not known to be reasonably accurate.  The code for this mechanism can be found in <file>src/netcpu_procstat.c</file>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>C</code></tableterm>
          <item>
            <para>A mechanism somewhat similar to <code>S</code> but using the sysctl() call on BSD-like Operating systems (*BSD and MacOS X).  The code for this mechanism can be found in <file>src/netcpu_sysctl.c</file>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>Others</code></tableterm>
          <item>
            <para>Other mechanisms included in netperf in the past have included using the times() and getrusage() calls.  These calls are actually rather poorly suited to the task of measuring CPU overhead for networking as they tend to be process-specific and much network-related processing can happen outside the context of a process, in places where it is not a given it will be charged to the correct, or even a process.  They are mentioned here as a warning to anyone seeing those mechanisms used in other networking benchmarks.  These mechanisms are not available in netperf 2.4.0 and later.</para>
          </item>
        </tableitem>
      </table>
      <para>For many platforms, the configure script will chose the best available CPU utilization mechanism.  However, some platforms have no particularly good mechanisms.  On those platforms, it is probably best to use the &ldquo;LOOPER&rdquo; mechanism which is basically some number of processes (as many as there are processors) sitting in tight little loops counting as fast as they can.  The rate at which the loopers count when the system is believed to be idle is compared with the rate when the system is running netperf and the ratio is used to compute CPU utilization.</para>
      <para>In the past, netperf included some mechanisms that only reported CPU time charged to the calling process.  Those mechanisms have been removed from netperf versions 2.4.0 and later because they are hopelessly inaccurate.  Networking can and often results in CPU time being spent in places - such as interrupt contexts - that do not get charged to a or the correct process.</para>
      <para>In fact, time spent in the processing of interrupts is a common issue for many CPU utilization mechanisms.  In particular, the &ldquo;PSTAT&rdquo; mechanism was eventually known to have problems accounting for certain interrupt time prior to HP-UX 11.11 (11iv1).  HP-UX 11iv2 and later are known/presumed to be good. The &ldquo;KSTAT&rdquo; mechanism is known to have problems on all versions of Solaris up to and including Solaris 10.  Even the microstate accounting available via kstat in Solaris 10 has issues, though perhaps not as bad as those of prior versions.</para>
      <para>The /proc/stat mechanism under Linux is in what the author would consider an &ldquo;uncertain&rdquo; category as it appears to be statistical, which may also have issues with time spent processing interrupts.</para>
      <para>In summary, be sure to &ldquo;sanity-check&rdquo; the CPU utilization figures with other mechanisms.  However, platform tools such as top, vmstat or mpstat are often based on the same mechanisms used by netperf.</para>
      <menu>
        <menuentry>
          <menunode>CPU Utilization in a Virtual Guest</menunode>
          <menutitle>CPU Utilization in a Virtual Guest</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </section>
  </node>
  <node>
    <nodename>CPU Utilization in a Virtual Guest</nodename>
    <nodeprev>CPU Utilization</nodeprev>
    <nodeup>CPU Utilization</nodeup>
    <subsection>
      <title>CPU Utilization in a Virtual Guest</title>
      <para>The CPU utilization mechanisms used by netperf are &ldquo;inline&rdquo; in that they are run by the same netperf or netserver process as is running the test itself.  This works just fine for &ldquo;bare iron&rdquo; tests but runs into a problem when using virtual machines.</para>
      <para>The relationship between virtual guest and hypervisor can be thought of as being similar to that between a process and kernel in a bare iron system.  As such, (m)any CPU utilization mechanisms used in the virtual guest are similar to &ldquo;process-local&rdquo; mechanisms in a bare iron situation.  However, just as with bare iron and process-local mechanisms, much networking processing happens outside the context of the virtual guest.  It takes place in the hypervisor, and is not visible to mechanisms running in the guest(s).  For this reason, one should not really trust CPU utilization figures reported by netperf or netserver when running in a virtual guest.</para>
      <para>If one is looking to measure the added overhead of a virtualization mechanism, rather than rely on CPU utilization, one can rely instead on netperf _RR tests - path-lengths and overheads can be a significant fraction of the latency, so increases in overhead should appear as decreases in transaction rate.  Whatever you do, <b>DO NOT</b> rely on the throughput of a _STREAM test.  Achieving link-rate can be done via a multitude of options that mask overhead rather than eliminate it.</para>
    </subsection>
  </node>
  <node>
    <nodename>Global Command-line Options</nodename>
    <nodenext>Using Netperf to Measure Bulk Data Transfer</nodenext>
    <nodeprev>The Design of Netperf</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>Global Command-line Options</title>
      <para>This section describes each of the global command-line options available in the netperf and netserver binaries.  Essentially, it is an expanded version of the usage information displayed by netperf or netserver when invoked with the <option>-h</option> global command-line option.</para>
      <menu>
        <menuentry>
          <menunode>Command-line Options Syntax</menunode>
          <menutitle>Command-line Options Syntax</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Global Options</menunode>
          <menutitle>Global Options</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Command-line Options Syntax</nodename>
    <nodenext>Global Options</nodenext>
    <nodeprev>Global Command-line Options</nodeprev>
    <nodeup>Global Command-line Options</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Command-line Options Syntax</title>
      <para>Revision 1.8 of netperf introduced enough new functionality to overrun the English alphabet for mnemonic command-line option names, and the author was not and is not quite ready to switch to the contemporary <option>--mumble</option> style of command-line options. (Call him a Luddite if you wish :).</para>
      <para>For this reason, the command-line options were split into two parts - the first are the global command-line options.  They are options that affect nearly any and every test type of netperf.  The second type are the test-specific command-line options.  Both are entered on the same command line, but they must be separated from one another by a <code>--</code> for correct parsing.  Global command-line options come first, followed by the <code>--</code> and then test-specific command-line options.  If there are no test-specific options to be set, the <code>--</code> may be omitted.  If there are no global command-line options to be set, test-specific options must still be preceded by a <code>--</code>.  For example:</para>
      <example xml:space="preserve">netperf &lt;global&gt; -- &lt;test-specific&gt;</example>
      <para>sets both global and test-specific options:</para>
      <example xml:space="preserve">netperf &lt;global&gt;</example>
      <para>sets just global options and:</para>
      <example xml:space="preserve">netperf -- &lt;test-specific&gt;</example>
      <para>sets just test-specific options.</para>
    </section>
  </node>
  <node>
    <nodename>Global Options</nodename>
    <nodeprev>Command-line Options Syntax</nodeprev>
    <nodeup>Global Command-line Options</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Global Options</title>
      <table><indexterm index="vr">-a, Global</indexterm>
        <tableitem>
          <tableterm><code>-a &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option allows you to alter the alignment of the buffers used in the sending and receiving calls on the local system.. Changing the alignment of the buffers can force the system to use different copy schemes, which can have a measurable effect on performance.  If the page size for the system were 4096 bytes, and you want to pass page-aligned buffers beginning on page boundaries, you could use <samp>-a 4096</samp>.  By default the units are bytes, but suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively. A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively. [Default: 8 bytes]</para>
            <para><indexterm index="vr">-A, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-A &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option is identical to the <option>-a</option> option with the difference being it affects alignments for the remote system.</para>
            <para><indexterm index="vr">-b, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-b &lt;size&gt;</code></tableterm>
          <item>
            <para>This option is only present when netperf has been configure with &ndash;enable-intervals=yes prior to compilation.  It sets the size of the burst of send calls in a _STREAM test.  When used in conjunction with the <option>-w</option> option it can cause the rate at which data is sent to be &ldquo;paced.&rdquo;</para>
            <para><indexterm index="vr">-B, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-B &lt;string&gt;</code></tableterm>
          <item>
            <para>This option will cause <option>&lt;string&gt;</option> to be appended to the brief (see -P) output of netperf.</para>
            <para><indexterm index="vr">-c, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-c [rate]</code></tableterm>
          <item>
            <para>This option will ask that CPU utilization and service demand be calculated for the local system.  For those CPU utilization mechanisms requiring calibration, the options rate parameter may be specified to preclude running another calibration step, saving 40 seconds of time. For those CPU utilization mechanisms requiring no calibration, the optional rate parameter will be utterly and completely ignored. [Default: no CPU measurements]</para>
            <para><indexterm index="vr">-C, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-C [rate]</code></tableterm>
          <item>
            <para>This option requests CPU utilization and service demand calculations for the remote system.  It is otherwise identical to the <option>-c</option> option.</para>
            <para><indexterm index="vr">-d, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-d</code></tableterm>
          <item>
            <para>Each instance of this option will increase the quantity of debugging output displayed during a test.  If the debugging output level is set high enough, it may have a measurable effect on performance. Debugging information for the local system is printed to stdout. Debugging information for the remote system is sent by default to the file <file>/tmp/netperf.debug</file>. [Default: no debugging output]</para>
            <para><indexterm index="vr">-D, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-D [interval,units]</code></tableterm>
          <item>
            <para>This option is only available when netperf is configured with &ndash;enable-demo=yes.  When set, it will cause netperf to emit periodic reports of performance during the run.  [<var>interval</var>,<var>units</var>] follow the semantics of an optionspec. If specified, <var>interval</var> gives the minimum interval in real seconds, it does not have to be whole seconds.  The <var>units</var> value can be used for the first guess as to how many units of work (bytes or transactions) must be done to take at least <var>interval</var> seconds. If omitted, <var>interval</var> defaults to one second and <var>units</var> to values specific to each test type.</para>
            <para><indexterm index="vr">-f, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-f G|M|K|g|m|k|x</code></tableterm>
          <item>
            <para>This option can be used to change the reporting units for _STREAM tests.  Arguments of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will set the units to 2^30, 2^20 or 2^10 bytes/s respectively (EG power of two GB, MB or KB).  Arguments of &ldquo;g,&rdquo; &ldquo;,m&rdquo; or &ldquo;k&rdquo; will set the units to 10^9, 10^6 or 10^3 bits/s respectively.  An argument of &ldquo;x&rdquo; requests the units be transactions per second and is only meaningful for a request-response test. [Default: &ldquo;m&rdquo; or 10^6 bits/s]</para>
            <para><indexterm index="vr">-F, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-F &lt;fillfile&gt;</code></tableterm>
          <item>
            <para>This option specified the file from which send which buffers will be pre-filled .  While the buffers will contain data from the specified file, the file is not fully transferred to the remote system as the receiving end of the test will not write the contents of what it receives to a file.  This can be used to pre-fill the send buffers with data having different compressibility and so is useful when measuring performance over mechanisms which perform compression.</para>
            <para>While previously required for a TCP_SENDFILE test, later versions of netperf removed that restriction, creating a temporary file as needed.  While the author cannot recall exactly when that took place, it is known to be unnecessary in version 2.5.0 and later.</para>
            <para><indexterm index="vr">-h, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-h</code></tableterm>
          <item>
            <para>This option causes netperf to display its &ldquo;global&rdquo; usage string and exit to the exclusion of all else.</para>
            <para><indexterm index="vr">-H, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-H &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>This option will set the name of the remote system and or the address family used for the control connection.  For example:</para>
            <example xml:space="preserve">-H linger,4</example>
            <para>will set the name of the remote system to &ldquo;linger&rdquo; and tells netperf to use IPv4 addressing only.</para>
            <example xml:space="preserve">-H ,6</example>
            <para>will leave the name of the remote system at its default, and request that only IPv6 addresses be used for the control connection.</para>
            <example xml:space="preserve">-H lag</example>
            <para>will set the name of the remote system to &ldquo;lag&rdquo; and leave the address family to AF_UNSPEC which means selection of IPv4 vs IPv6 is left to the system's address resolution.</para>
            <para>A value of &ldquo;inet&rdquo; can be used in place of &ldquo;4&rdquo; to request IPv4 only addressing.  Similarly, a value of &ldquo;inet6&rdquo; can be used in place of &ldquo;6&rdquo; to request IPv6 only addressing.  A value of &ldquo;0&rdquo; can be used to request either IPv4 or IPv6 addressing as name resolution dictates.</para>
            <para>By default, the options set with the global <option>-H</option> option are inherited by the test for its data connection, unless a test-specific <option>-H</option> option is specified.</para>
            <para>If a <option>-H</option> option follows either the <option>-4</option> or <option>-6</option> options, the family setting specified with the -H option will override the <option>-4</option> or <option>-6</option> options for the remote address family. If no address family is specified, settings from a previous <option>-4</option> or <option>-6</option> option will remain.  In a nutshell, the last explicit global command-line option wins.</para>
            <para>[Default:  &ldquo;localhost&rdquo; for the remote name/IP address and &ldquo;0&rdquo; (eg AF_UNSPEC) for the remote address family.]</para>
            <para><indexterm index="vr">-I, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-I &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>This option enables the calculation of confidence intervals and sets the confidence and width parameters with the first half of the optionspec being either 99 or 95 for 99% or 95% confidence respectively.  The second value of the optionspec specifies the width of the desired confidence interval.  For example</para>
            <example xml:space="preserve">-I 99,5</example>
            <para>asks netperf to be 99% confident that the measured mean values for throughput and CPU utilization are within +/- 2.5% of the &ldquo;real&rdquo; mean values.  If the <option>-i</option> option is specified and the <option>-I</option> option is omitted, the confidence defaults to 99% and the width to 5% (giving +/- 2.5%)</para>
            <para>If classic netperf test calculates that the desired confidence intervals have not been met, it emits a noticeable warning that cannot be suppressed with the <option>-P</option> or <option>-v</option> options:</para>
            <example xml:space="preserve">netperf -H tardy.cup -i 3 -I 99,5
TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to tardy.cup.hp.com (15.244.44.58) port 0 AF_INET : +/-2.5% &space;99% conf.
!!! WARNING
!!! Desired confidence was not achieved within the specified iterations.
!!! This implies that there was variability in the test environment that
!!! must be investigated before going further.
!!! Confidence intervals: Throughput      :  6.8%
!!!                       Local CPU util  :  0.0%
!!!                       Remote CPU util :  0.0%

Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

 32768  16384  16384    10.01      40.23</example>
            <para>In the example above we see that netperf did not meet the desired confidence intervals.  Instead of being 99% confident it was within +/- 2.5% of the real mean value of throughput it is only confident it was within +/-3.4%.  In this example, increasing the <option>-i</option> option (described below) and/or increasing the iteration length with the <option>-l</option> option might resolve the situation.</para>
            <para>In an explicit &ldquo;omni&rdquo; test, failure to meet the confidence intervals will not result in netperf emitting a warning.  To verify the hitting, or not, of the confidence intervals one will need to include them as part of an <xref><xrefnodename>Omni Output Selection</xrefnodename><xrefinfoname>output selection</xrefinfoname></xref> in the test-specific <option>-o</option>, <option>-O</option> or <option>k</option> output selection options.  The warning about not hitting the confidence intervals will remain in a &ldquo;migrated&rdquo; classic netperf test.</para>
            <para><indexterm index="vr">-i, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-i &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option enables the calculation of confidence intervals and sets the minimum and maximum number of iterations to run in attempting to achieve the desired confidence interval.  The first value sets the maximum number of iterations to run, the second, the minimum.  The maximum number of iterations is silently capped at 30 and the minimum is silently floored at 3.  Netperf repeats the measurement the minimum number of iterations and continues until it reaches either the desired confidence interval, or the maximum number of iterations, whichever comes first.  A classic or migrated netperf test will not display the actual number of iterations run. An <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni test</xrefinfoname></xref> will emit the number of iterations run if the <code>CONFIDENCE_ITERATION</code> output selector is included in the <xref><xrefnodename>Omni Output Selection</xrefnodename><xrefinfoname>output selection</xrefinfoname></xref>.</para>
            <para>If the <option>-I</option> option is specified and the <option>-i</option> option omitted the maximum number of iterations is set to 10 and the minimum to three.</para>
            <para>Output of a warning upon not hitting the desired confidence intervals follows the description provided for the <option>-I</option> option.</para>
            <para>The total test time will be somewhere between the minimum and maximum number of iterations multiplied by the test length supplied by the <option>-l</option> option.</para>
            <para><indexterm index="vr">-j, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-j</code></tableterm>
          <item>
            <para>This option instructs netperf to keep additional timing statistics when explicitly running an <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni test</xrefinfoname></xref>.  These can be output when the test-specific <option>-o</option>, <option>-O</option> or <option>-k</option> <xref><xrefnodename>Omni Output Selectors</xrefnodename><xrefinfoname>output selectors</xrefinfoname></xref> include one or more of:</para>
            <itemize>
              <itemfunction>&bullet;</itemfunction>
              <item>
                <para>MIN_LATENCY</para>
              </item>
              <item>
                <para>MAX_LATENCY</para>
              </item>
              <item>
                <para>P50_LATENCY</para>
              </item>
              <item>
                <para>P90_LATENCY</para>
              </item>
              <item>
                <para>P99_LATENCY</para>
              </item>
              <item>
                <para>MEAN_LATENCY</para>
              </item>
              <item>
                <para>STDDEV_LATENCY</para>
              </item>
            </itemize>
            <para>These statistics will be based on an expanded (100 buckets per row rather than 10) histogram of times rather than a terribly long list of individual times.  As such, there will be some slight error thanks to the bucketing. However, the reduction in storage and processing overheads is well worth it.  When running a request/response test, one might get some idea of the error by comparing the <xref><xrefnodename>Omni Output Selectors</xrefnodename><xrefinfoname><code>MEAN_LATENCY</code></xrefinfoname></xref> calculated from the histogram with the <code>RT_LATENCY</code> calculated from the number of request/response transactions and the test run time.</para>
            <para>In the case of a request/response test the latencies will be transaction latencies.  In the case of a receive-only test they will be time spent in the receive call.  In the case of a send-only test they will be time spent in the send call. The units will be microseconds. Added in netperf 2.5.0.</para>
            <para><indexterm index="vr">-l, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-l testlen</code></tableterm>
          <item>
            <para>This option controls the length of any <b>one</b> iteration of the requested test.  A positive value for <var>testlen</var> will run each iteration of the test for at least <var>testlen</var> seconds.  A negative value for <var>testlen</var> will run each iteration for the absolute value of <var>testlen</var> transactions for a _RR test or bytes for a _STREAM test. Certain tests, notably those using UDP can only be timed, they cannot be limited by transaction or byte count.  This limitation may be relaxed in an <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni</xrefinfoname></xref> test.</para>
            <para>In some situations, individual iterations of a test may run for longer for the number of seconds specified by the <option>-l</option> option.  In particular, this may occur for those tests where the socket buffer size(s) are significantly longer than the bandwidthXdelay product of the link(s) over which the data connection passes, or those tests where there may be non-trivial numbers of retransmissions.</para>
            <para>If confidence intervals are enabled via either <option>-I</option> or <option>-i</option> the total length of the netperf test will be somewhere between the minimum and maximum iteration count multiplied by <var>testlen</var>.</para>
            <para><indexterm index="vr">-L, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-L &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>This option is identical to the <option>-H</option> option with the difference being it sets the _local_ hostname/IP and/or address family information.  This option is generally unnecessary, but can be useful when you wish to make sure that the netperf control and data connections go via different paths.  It can also come-in handy if one is trying to run netperf through those evil, end-to-end breaking things known as firewalls.</para>
            <para>[Default: 0.0.0.0 (eg INADDR_ANY) for IPv4 and ::0 for IPv6 for the local name.  AF_UNSPEC for the local address family.]</para>
            <para><indexterm index="vr">-n, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-n numcpus</code></tableterm>
          <item>
            <para>This option tells netperf how many CPUs it should ass-u-me are active on the system running netperf.  In particular, this is used for the <xref><xrefnodename>CPU Utilization</xrefnodename><xrefinfoname>CPU utilization</xrefinfoname></xref> and service demand calculations. On certain systems, netperf is able to determine the number of CPU's automagically. This option will override any number netperf might be able to determine on its own.</para>
            <para>Note that this option does _not_ set the number of CPUs on the system running netserver.  When netperf/netserver cannot automagically determine the number of CPUs that can only be set for netserver via a netserver <option>-n</option> command-line option.</para>
            <para>As it is almost universally possible for netperf/netserver to determine the number of CPUs on the system automagically, 99 times out of 10 this option should not be necessary and may be removed in a future release of netperf.</para>
            <para><indexterm index="vr">-N, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-N</code></tableterm>
          <item>
            <para>This option tells netperf to forgo establishing a control connection. This makes it is possible to run some limited netperf tests without a corresponding netserver on the remote system.</para>
            <para>With this option set, the test to be run is to get all the addressing information it needs to establish its data connection from the command line or internal defaults.  If not otherwise specified by test-specific command line options, the data connection for a &ldquo;STREAM&rdquo; or &ldquo;SENDFILE&rdquo; test will be to the &ldquo;discard&rdquo; port, an &ldquo;RR&rdquo; test will be to the &ldquo;echo&rdquo; port, and a &ldquo;MEARTS&rdquo; test will be to the chargen port.</para>
            <para>The response size of an &ldquo;RR&rdquo; test will be silently set to be the same as the request size.  Otherwise the test would hang if the response size was larger than the request size, or would report an incorrect, inflated transaction rate if the response size was less than the request size.</para>
            <para>Since there is no control connection when this option is specified, it is not possible to set &ldquo;remote&rdquo; properties such as socket buffer size and the like via the netperf command line. Nor is it possible to retrieve such interesting remote information as CPU utilization. These items will be displayed as values which should make it immediately obvious that was the case.</para>
            <para>The only way to change remote characteristics such as socket buffer size or to obtain information such as CPU utilization is to employ platform-specific methods on the remote system.  Frankly, if one has access to the remote system to employ those methods one aught to be able to run a netserver there.  However, that ability may not be present in certain &ldquo;support&rdquo; situations, hence the addition of this option.</para>
            <para>Added in netperf 2.4.3.</para>
            <para><indexterm index="vr">-o, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-o &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>The value(s) passed-in with this option will be used as an offset added to the alignment specified with the <option>-a</option> option.  For example:</para>
            <example xml:space="preserve">-o 3 -a 4096</example>
            <para>will cause the buffers passed to the local (netperf) send and receive calls to begin three bytes past an address aligned to 4096 bytes. [Default: 0 bytes]</para>
            <para><indexterm index="vr">-O, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-O &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option behaves just as the <option>-o</option> option but on the remote (netserver) system and in conjunction with the <option>-A</option> option. [Default: 0 bytes]</para>
            <para><indexterm index="vr">-p, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-p &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>The first value of the optionspec passed-in with this option tells netperf the port number at which it should expect the remote netserver to be listening for control connections.  The second value of the optionspec will request netperf to bind to that local port number before establishing the control connection.  For example</para>
            <example xml:space="preserve">-p 12345</example>
            <para>tells netperf that the remote netserver is listening on port 12345 and leaves selection of the local port number for the control connection up to the local TCP/IP stack whereas</para>
            <example xml:space="preserve">-p ,32109</example>
            <para>leaves the remote netserver port at the default value of 12865 and causes netperf to bind to the local port number 32109 before connecting to the remote netserver.</para>
            <para>In general, setting the local port number is only necessary when one is looking to run netperf through those evil, end-to-end breaking things known as firewalls.</para>
            <para><indexterm index="vr">-P, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-P 0|1</code></tableterm>
          <item>
            <para>A value of &ldquo;1&rdquo; for the <option>-P</option> option will enable display of the test banner.  A value of &ldquo;0&rdquo; will disable display of the test banner. One might want to disable display of the test banner when running the same basic test type (eg TCP_STREAM) multiple times in succession where the test banners would then simply be redundant and unnecessarily clutter the output. [Default: 1 - display test banners]</para>
            <para><indexterm index="vr">-s, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-s &lt;seconds&gt;</code></tableterm>
          <item>
            <para>This option will cause netperf to sleep <samp>&lt;seconds&gt;</samp> before actually transferring data over the data connection.  This may be useful in situations where one wishes to start a great many netperf instances and do not want the earlier ones affecting the ability of the later ones to get established.</para>
            <para>Added somewhere between versions 2.4.3 and 2.5.0.</para>
            <para><indexterm index="vr">-S, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-S</code></tableterm>
          <item>
            <para>This option will cause an attempt to be made to set SO_KEEPALIVE on the data socket of a test using the BSD sockets interface.  The attempt will be made on the netperf side of all tests, and will be made on the netserver side of an <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni</xrefinfoname></xref> or <xref><xrefnodename>Migrated Tests</xrefnodename><xrefinfoname>migrated</xrefinfoname></xref> test.  No indication of failure is given unless debug output is enabled with the global <option>-d</option> option.</para>
            <para>Added in version 2.5.0.</para>
            <para><indexterm index="vr">-t, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-t testname</code></tableterm>
          <item>
            <para>This option is used to tell netperf which test you wish to run.  As of this writing, valid values for <var>testname</var> include:</para>
            <itemize>
              <itemfunction>&bullet;</itemfunction>
              <item>
                <para><xref><xrefnodename>TCP_STREAM</xrefnodename></xref>, <xref><xrefnodename>TCP_MAERTS</xrefnodename></xref>, <xref><xrefnodename>TCP_SENDFILE</xrefnodename></xref>, <xref><xrefnodename>TCP_RR</xrefnodename></xref>, <xref><xrefnodename>TCP_CRR</xrefnodename></xref>, <xref><xrefnodename>TCP_CC</xrefnodename></xref></para>
              </item>
              <item>
                <para><xref><xrefnodename>UDP_STREAM</xrefnodename></xref>, <xref><xrefnodename>UDP_RR</xrefnodename></xref></para>
              </item>
              <item>
                <para><xref><xrefnodename>XTI_TCP_STREAM</xrefnodename></xref>,  <xref><xrefnodename>XTI_TCP_RR</xrefnodename></xref>, <xref><xrefnodename>XTI_TCP_CRR</xrefnodename></xref>, <xref><xrefnodename>XTI_TCP_CC</xrefnodename></xref></para>
              </item>
              <item>
                <para><xref><xrefnodename>XTI_UDP_STREAM</xrefnodename></xref>, <xref><xrefnodename>XTI_UDP_RR</xrefnodename></xref></para>
              </item>
              <item>
                <para><xref><xrefnodename>SCTP_STREAM</xrefnodename></xref>, <xref><xrefnodename>SCTP_RR</xrefnodename></xref></para>
              </item>
              <item>
                <para><xref><xrefnodename>DLCO_STREAM</xrefnodename></xref>, <xref><xrefnodename>DLCO_RR</xrefnodename></xref>,  <xref><xrefnodename>DLCL_STREAM</xrefnodename></xref>, <xref><xrefnodename>DLCL_RR</xrefnodename></xref></para>
              </item>
              <item>
                <para><xref><xrefnodename>Other Netperf Tests</xrefnodename><xrefinfoname>LOC_CPU</xrefinfoname></xref>, <xref><xrefnodename>Other Netperf Tests</xrefnodename><xrefinfoname>REM_CPU</xrefinfoname></xref></para>
              </item>
              <item>
                <para><xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>OMNI</xrefinfoname></xref></para>
              </item>
            </itemize>
            <para>Not all tests are always compiled into netperf.  In particular, the &ldquo;XTI,&rdquo; &ldquo;SCTP,&rdquo; &ldquo;UNIXDOMAIN,&rdquo; and &ldquo;DL*&rdquo; tests are only included in netperf when configured with <option>--enable-[xti|sctp|unixdomain|dlpi]=yes</option>.</para>
            <para>Netperf only runs one type of test no matter how many <option>-t</option> options may be present on the command-line.  The last <option>-t</option> global command-line option will determine the test to be run. [Default: TCP_STREAM]</para>
            <para><indexterm index="vr">-T, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-T &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>This option controls the CPU, and probably by extension memory, affinity of netperf and/or netserver.</para>
            <example xml:space="preserve">netperf -T 1</example>
            <para>will bind both netperf and netserver to &ldquo;CPU 1&rdquo; on their respective systems.</para>
            <example xml:space="preserve">netperf -T 1,</example>
            <para>will bind just netperf to &ldquo;CPU 1&rdquo; and will leave netserver unbound.</para>
            <example xml:space="preserve">netperf -T ,2</example>
            <para>will leave netperf unbound and will bind netserver to &ldquo;CPU 2.&rdquo;</para>
            <example xml:space="preserve">netperf -T 1,2</example>
            <para>will bind netperf to &ldquo;CPU 1&rdquo; and netserver to &ldquo;CPU 2.&rdquo;</para>
            <para>This can be particularly useful when investigating performance issues involving where processes run relative to where NIC interrupts are processed or where NICs allocate their DMA buffers.</para>
            <para><indexterm index="vr">-v, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-v verbosity</code></tableterm>
          <item>
            <para>This option controls how verbose netperf will be in its output, and is often used in conjunction with the <option>-P</option> option. If the verbosity is set to a value of &ldquo;0&rdquo; then only the test's SFM (Single Figure of Merit) is displayed.  If local <xref><xrefnodename>CPU Utilization</xrefnodename><xrefinfoname>CPU utilization</xrefinfoname></xref> is requested via the <option>-c</option> option then the SFM is the local service demand.  Othersise, if remote CPU utilization is requested via the <option>-C</option> option then the SFM is the remote service demand.  If neither local nor remote CPU utilization are requested the SFM will be the measured throughput or transaction rate as implied by the test specified with the <option>-t</option> option.</para>
            <para>If the verbosity level is set to &ldquo;1&rdquo; then the &ldquo;normal&rdquo; netperf result output for each test is displayed.</para>
            <para>If the verbosity level is set to &ldquo;2&rdquo; then &ldquo;extra&rdquo; information will be displayed.  This may include, but is not limited to the number of send or recv calls made and the average number of bytes per send or recv call, or a histogram of the time spent in each send() call or for each transaction if netperf was configured with <option>--enable-histogram=yes</option>. [Default: 1 - normal verbosity]</para>
            <para>In an <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni</xrefinfoname></xref> test the verbosity setting is largely ignored, save for when asking for the time histogram to be displayed. In version 2.5.0 there is no <xref><xrefnodename>Omni Output Selectors</xrefnodename><xrefinfoname>output selector</xrefinfoname></xref> for the histogram and so it remains displayed only when the verbosity level is set to 2.</para>
            <para><indexterm index="vr">-V, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-V</code></tableterm>
          <item>
            <para>This option displays the netperf version and then exits.</para>
            <para>Added in netperf 2.4.4.</para>
            <para><indexterm index="vr">-w, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-w time</code></tableterm>
          <item>
            <para>If netperf was configured with <option>--enable-intervals=yes</option> then this value will set the inter-burst time to time milliseconds, and the <option>-b</option> option will set the number of sends per burst.  The actual inter-burst time may vary depending on the system's timer resolution.</para>
            <para><indexterm index="vr">-W, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-W &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option controls the number of buffers in the send (first or only value) and or receive (second or only value) buffer rings.  Unlike some benchmarks, netperf does not continuously send or receive from a single buffer.  Instead it rotates through a ring of buffers. [Default: One more than the size of the send or receive socket buffer sizes (<option>-s</option> and/or <option>-S</option> options) divided by the send <option>-m</option> or receive <option>-M</option> buffer size respectively]</para>
            <para><indexterm index="vr">-4, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-4</code></tableterm>
          <item>
            <para>Specifying this option will set both the local and remote address families to AF_INET - that is use only IPv4 addresses on the control connection.  This can be overridden by a subsequent <option>-6</option>, <option>-H</option> or <option>-L</option> option.  Basically, the last option explicitly specifying an address family wins.  Unless overridden by a test-specific option, this will be inherited for the data connection as well.</para>
            <para><indexterm index="vr">-6, Global</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-6</code></tableterm>
          <item>
            <para>Specifying this option will set both local and and remote address families to AF_INET6 - that is use only IPv6 addresses on the control connection.  This can be overridden by a subsequent <option>-4</option>, <option>-H</option> or <option>-L</option> option.  Basically, the last address family explicitly specified wins.  Unless overridden by a test-specific option, this will be inherited for the data connection as well.</para>
          </item>
        </tableitem>
      </table>
    </section>
  </node>
  <node>
    <nodename>Using Netperf to Measure Bulk Data Transfer</nodename>
    <nodenext>Using Netperf to Measure Request/Response</nodenext>
    <nodeprev>Global Command-line Options</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>Using Netperf to Measure Bulk Data Transfer</title>
      <para>The most commonly measured aspect of networked system performance is that of bulk or unidirectional transfer performance.  Everyone wants to know how many bits or bytes per second they can push across the network. The classic netperf convention for a bulk data transfer test name is to tack a &ldquo;_STREAM&rdquo; suffix to a test name.</para>
      <menu>
        <menuentry>
          <menunode>Issues in Bulk Transfer</menunode>
          <menutitle>Issues in Bulk Transfer</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Options common to TCP UDP and SCTP tests</menunode>
          <menutitle>Options common to TCP UDP and SCTP tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Issues in Bulk Transfer</nodename>
    <nodenext>Options common to TCP UDP and SCTP tests</nodenext>
    <nodeprev>Using Netperf to Measure Bulk Data Transfer</nodeprev>
    <nodeup>Using Netperf to Measure Bulk Data Transfer</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Issues in Bulk Transfer</title>
      <para>There are any number of things which can affect the performance of a bulk transfer test.</para>
      <para>Certainly, absent compression, bulk-transfer tests can be limited by the speed of the slowest link in the path from the source to the destination.  If testing over a gigabit link, you will not see more than a gigabit :) Such situations can be described as being <dfn>network-limited</dfn> or <dfn>NIC-limited</dfn>.</para>
      <para>CPU utilization can also affect the results of a bulk-transfer test. If the networking stack requires a certain number of instructions or CPU cycles per KB of data transferred, and the CPU is limited in the number of instructions or cycles it can provide, then the transfer can be described as being <dfn>CPU-bound</dfn>.</para>
      <para>A bulk-transfer test can be CPU bound even when netperf reports less than 100% CPU utilization.  This can happen on an MP system where one or more of the CPUs saturate at 100% but other CPU's remain idle. Typically, a single flow of data, such as that from a single instance of a netperf _STREAM test cannot make use of much more than the power of one CPU. Exceptions to this generally occur when netperf and/or netserver run on CPU(s) other than the CPU(s) taking interrupts from the NIC(s). In that case, one might see as much as two CPUs' worth of processing being used to service the flow of data.</para>
      <para>Distance and the speed-of-light can affect performance for a bulk-transfer; often this can be mitigated by using larger windows. One common limit to the performance of a transport using window-based flow-control is:</para>
      <example xml:space="preserve">Throughput &lt;= WindowSize/RoundTripTime</example>
      <para>As the sender can only have a window's-worth of data outstanding on the network at any one time, and the soonest the sender can receive a window update from the receiver is one RoundTripTime (RTT).  TCP and SCTP are examples of such protocols.</para>
      <para>Packet losses and their effects can be particularly bad for performance.  This is especially true if the packet losses result in retransmission timeouts for the protocol(s) involved.  By the time a retransmission timeout has happened, the flow or connection has sat idle for a considerable length of time.</para>
      <para>On many platforms, some variant on the <command>netstat</command> command can be used to retrieve statistics about packet loss and retransmission. For example:</para>
      <example xml:space="preserve">netstat -p tcp</example>
      <para>will retrieve TCP statistics on the HP-UX Operating System.  On other platforms, it may not be possible to retrieve statistics for a specific protocol and something like:</para>
      <example xml:space="preserve">netstat -s</example>
      <para>would be used instead.</para>
      <para>Many times, such network statistics are keep since the time the stack started, and we are only really interested in statistics from when netperf was running.  In such situations something along the lines of:</para>
      <example xml:space="preserve">netstat -p tcp &gt; before
netperf -t TCP_mumble...
netstat -p tcp &gt; after</example>
      <para>is indicated.  The <uref><urefurl>ftp://ftp.cup.hp.com/dist/networking/tools/</urefurl><urefdesc>beforeafter</urefdesc></uref> utility can be used to subtract the statistics in <file>before</file> from the statistics in <file>after</file>:</para>
      <example xml:space="preserve">beforeafter before after &gt; delta</example>
      <para>and then one can look at the statistics in <file>delta</file>.  Beforeafter is distributed in source form so one can compile it on the platform(s) of interest.</para>
      <para>If running a version 2.5.0 or later &ldquo;omni&rdquo; test under Linux one can include either or both of:</para>
      <itemize>
        <itemfunction>&bullet;</itemfunction>
        <item>
          <para>LOCAL_TRANSPORT_RETRANS</para>
        </item>
        <item>
          <para>REMOTE_TRANSPORT_RETRANS</para>
        </item>
      </itemize>
      <para>in the values provided via a test-specific <option>-o</option>, <option>-O</option>, or <option>-k</option> output selction option and netperf will report the retransmissions experienced on the data connection, as reported via a <code>getsockopt(TCP_INFO)</code> call.  If confidence intervals have been requested via the global <option>-I</option> or <option>-i</option> options, the reported value(s) will be for the last iteration.  If the test is over a protocol other than TCP, or on a platform other than Linux, the results are undefined.</para>
      <para>While it was written with HP-UX's netstat in mind, the <uref><urefurl>ftp://ftp.cup.hp.com/dist/networking/briefs/annotated_netstat.txt</urefurl><urefdesc>annotated netstat</urefdesc></uref> writeup may be helpful with other platforms as well.</para>
    </section>
  </node>
  <node>
    <nodename>Options common to TCP UDP and SCTP tests</nodename>
    <nodeprev>Issues in Bulk Transfer</nodeprev>
    <nodeup>Using Netperf to Measure Bulk Data Transfer</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Options common to TCP UDP and SCTP tests</title>
      <para>Many &ldquo;test-specific&rdquo; options are actually common across the different tests.  For those tests involving TCP, UDP and SCTP, whether using the BSD Sockets or the XTI interface those common options include:</para>
      <table><indexterm index="vr">-h, Test-specific</indexterm>
        <tableitem>
          <tableterm><code>-h</code></tableterm>
          <item>
            <para>Display the test-suite-specific usage string and exit.  For a TCP_ or UDP_ test this will be the usage string from the source file nettest_bsd.c.  For an XTI_ test, this will be the usage string from the source file nettest_xti.c.  For an SCTP test, this will be the usage string from the source file nettest_sctp.c.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-H &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>Normally, the remote hostname|IP and address family information is inherited from the settings for the control connection (eg global command-line <option>-H</option>, <option>-4</option> and/or <option>-6</option> options). The test-specific <option>-H</option> will override those settings for the data (aka test) connection only.  Settings for the control connection are left unchanged.</para>
            <para><indexterm index="vr">-L, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-L &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>The test-specific <option>-L</option> option is identical to the test-specific <option>-H</option> option except it affects the local hostname|IP and address family information.  As with its global command-line counterpart, this is generally only useful when measuring though those evil, end-to-end breaking things called firewalls.</para>
            <para><indexterm index="vr">-m, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-m bytes</code></tableterm>
          <item>
            <para>Set the size of the buffer passed-in to the &ldquo;send&rdquo; calls of a _STREAM test.  Note that this may have only an indirect effect on the size of the packets sent over the network, and certain Layer 4 protocols do _not_ preserve or enforce message boundaries, so setting <option>-m</option> for the send size does not necessarily mean the receiver will receive that many bytes at any one time. By default the units are bytes, but suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively. A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively. For example:</para>
            <example xml:space="preserve"><code>-m 32K</code></example>
            <para>will set the size to 32KB or 32768 bytes. [Default: the local send socket buffer size for the connection - either the system's default or the value set via the <option>-s</option> option.]</para>
            <para><indexterm index="vr">-M, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-M bytes</code></tableterm>
          <item>
            <para>Set the size of the buffer passed-in to the &ldquo;recv&rdquo; calls of a _STREAM test.  This will be an upper bound on the number of bytes received per receive call. By default the units are bytes, but suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively.  A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively. For example:</para>
            <example xml:space="preserve"><code>-M 32K</code></example>
            <para>will set the size to 32KB or 32768 bytes. [Default: the remote receive socket buffer size for the data connection - either the system's default or the value set via the <option>-S</option> option.]</para>
            <para><indexterm index="vr">-P, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-P &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>Set the local and/or remote port numbers for the data connection.</para>
            <para><indexterm index="vr">-s, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-s &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option sets the local (netperf) send and receive socket buffer sizes for the data connection to the value(s) specified.  Often, this will affect the advertised and/or effective TCP or other window, but on some platforms it may not. By default the units are bytes, but suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively.  A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively. For example:</para>
            <example xml:space="preserve"><code>-s 128K</code></example>
            <para>Will request the local send and receive socket buffer sizes to be 128KB or 131072 bytes.</para>
            <para>While the historic expectation is that setting the socket buffer size has a direct effect on say the TCP window, today that may not hold true for all stacks. Further, while the historic expectation is that the value specified in a <code>setsockopt()</code> call will be the value returned via a <code>getsockopt()</code> call, at least one stack is known to deliberately ignore history.  When running under Windows a value of 0 may be used which will be an indication to the stack the user wants to enable a form of copy avoidance. [Default: -1 - use the system's default socket buffer sizes]</para>
            <para><indexterm index="vr">-S Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-S &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option sets the remote (netserver) send and/or receive socket buffer sizes for the data connection to the value(s) specified. Often, this will affect the advertised and/or effective TCP or other window, but on some platforms it may not. By default the units are bytes, but suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively.  A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively.  For example:</para>
            <example xml:space="preserve"><code>-s 128K</code></example>
            <para>Will request the remote send and receive socket buffer sizes to be 128KB or 131072 bytes.</para>
            <para>While the historic expectation is that setting the socket buffer size has a direct effect on say the TCP window, today that may not hold true for all stacks.  Further, while the historic expectation is that the value specified in a <code>setsockopt()</code> call will be the value returned via a <code>getsockopt()</code> call, at least one stack is known to deliberately ignore history.  When running under Windows a value of 0 may be used which will be an indication to the stack the user wants to enable a form of copy avoidance. [Default: -1 - use the system's default socket buffer sizes]</para>
            <para><indexterm index="vr">-4, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-4</code></tableterm>
          <item>
            <para>Set the local and remote address family for the data connection to AF_INET - ie use IPv4 addressing only.  Just as with their global command-line counterparts the last of the <option>-4</option>, <option>-6</option>, <option>-H</option> or <option>-L</option> option wins for their respective address families.</para>
            <para><indexterm index="vr">-6, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-6</code></tableterm>
          <item>
            <para>This option is identical to its <option>-4</option> cousin, but requests IPv6 addresses for the local and remote ends of the data connection.</para>
          </item>
        </tableitem>
      </table>
      <menu>
        <menuentry>
          <menunode>TCP_STREAM</menunode>
          <menutitle>TCP_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>TCP_MAERTS</menunode>
          <menutitle>TCP_MAERTS</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>TCP_SENDFILE</menunode>
          <menutitle>TCP_SENDFILE</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>UDP_STREAM</menunode>
          <menutitle>UDP_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>XTI_TCP_STREAM</menunode>
          <menutitle>XTI_TCP_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>XTI_UDP_STREAM</menunode>
          <menutitle>XTI_UDP_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>SCTP_STREAM</menunode>
          <menutitle>SCTP_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>DLCO_STREAM</menunode>
          <menutitle>DLCO_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>DLCL_STREAM</menunode>
          <menutitle>DLCL_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>STREAM_STREAM</menunode>
          <menutitle>STREAM_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>DG_STREAM</menunode>
          <menutitle>DG_STREAM</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </section>
  </node>
  <node>
    <nodename>TCP_STREAM</nodename>
    <nodenext>TCP_MAERTS</nodenext>
    <nodeprev>Options common to TCP UDP and SCTP tests</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
    <subsection>
      <title>TCP_STREAM</title>
      <para>The TCP_STREAM test is the default test in netperf.  It is quite simple, transferring some quantity of data from the system running netperf to the system running netserver.  While time spent establishing the connection is not included in the throughput calculation, time spent flushing the last of the data to the remote at the end of the test is.  This is how netperf knows that all the data it sent was received by the remote.  In addition to the <xref><xrefnodename>Options common to TCP UDP and SCTP tests</xrefnodename><xrefinfoname>options common to STREAM tests</xrefinfoname></xref>, the following test-specific options can be included to possibly alter the behavior of the test:</para>
      <table>
        <tableitem>
          <tableterm><code>-C</code></tableterm>
          <item>
            <para>This option will set TCP_CORK mode on the data connection on those systems where TCP_CORK is defined (typically Linux).  A full description of TCP_CORK is beyond the scope of this manual, but in a nutshell it forces sub-MSS sends to be buffered so every segment sent is Maximum Segment Size (MSS) unless the application performs an explicit flush operation or the connection is closed.  At present netperf does not perform any explicit flush operations.  Setting TCP_CORK may improve the bitrate of tests where the &ldquo;send size&rdquo; (<option>-m</option> option) is smaller than the MSS.  It should also improve (make smaller) the service demand.</para>
            <para>The Linux tcp(7) manpage states that TCP_CORK cannot be used in conjunction with TCP_NODELAY (set via the <option>-d</option> option), however netperf does not validate command-line options to enforce that.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-D</code></tableterm>
          <item>
            <para>This option will set TCP_NODELAY on the data connection on those systems where TCP_NODELAY is defined.  This disables something known as the Nagle Algorithm, which is intended to make the segments TCP sends as large as reasonably possible.  Setting TCP_NODELAY for a TCP_STREAM test should either have no effect when the send size (<option>-m</option> option) is larger than the MSS or will decrease reported bitrate and increase service demand when the send size is smaller than the MSS.  This stems from TCP_NODELAY causing each sub-MSS send to be its own TCP segment rather than being aggregated with other small sends.  This means more trips up and down the protocol stack per KB of data transferred, which means greater CPU utilization.</para>
            <para>If setting TCP_NODELAY with <option>-D</option> affects throughput and/or service demand for tests where the send size (<option>-m</option>) is larger than the MSS it suggests the TCP/IP stack's implementation of the Nagle Algorithm _may_ be broken, perhaps interpreting the Nagle Algorithm on a segment by segment basis rather than the proper user send by user send basis.  However, a better test of this can be achieved with the <xref><xrefnodename>TCP_RR</xrefnodename></xref> test.</para>
          </item>
        </tableitem>
      </table>
      <para>Here is an example of a basic TCP_STREAM test, in this case from a Debian Linux (2.6 kernel) system to an HP-UX 11iv2 (HP-UX 11.23) system:</para>
      <example xml:space="preserve">$ netperf -H lag
TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to lag.hpl.hp.com (15.4.89.214) port 0 AF_INET
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

 32768  16384  16384    10.00      80.42</example>
      <para>We see that the default receive socket buffer size for the receiver (lag - HP-UX 11.23) is 32768 bytes, and the default socket send buffer size for the sender (Debian 2.6 kernel) is 16384 bytes, however Linux does &ldquo;auto tuning&rdquo; of socket buffer and TCP window sizes, which means the send socket buffer size may be different at the end of the test than it was at the beginning.  This is addressed in the <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni tests</xrefinfoname></xref> added in version 2.5.0 and <xref><xrefnodename>Omni Output Selection</xrefnodename><xrefinfoname>output selection</xrefinfoname></xref>.  Throughput is expressed as 10^6 (aka Mega) bits per second, and the test ran for 10 seconds.  IPv4 addresses (AF_INET) were used.</para>
    </subsection>
  </node>
  <node>
    <nodename>TCP_MAERTS</nodename>
    <nodenext>TCP_SENDFILE</nodenext>
    <nodeprev>TCP_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>TCP_MAERTS</title>
      <para>A TCP_MAERTS (MAERTS is STREAM backwards) test is &ldquo;just like&rdquo; a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test except the data flows from the netserver to the netperf. The global command-line <option>-F</option> option is ignored for this test type.  The test-specific command-line <option>-C</option> option is ignored for this test type.</para>
      <para>Here is an example of a TCP_MAERTS test between the same two systems as in the example for the <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test.  This time we request larger socket buffers with <option>-s</option> and <option>-S</option> options:</para>
      <example xml:space="preserve">$ netperf -H lag -t TCP_MAERTS -- -s 128K -S 128K
TCP MAERTS TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to lag.hpl.hp.com (15.4.89.214) port 0 AF_INET
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

221184 131072 131072    10.03      81.14</example>
      <para>Where we see that Linux, unlike HP-UX, may not return the same value in a <code>getsockopt()</code> as was requested in the prior <code>setsockopt()</code>.</para>
      <para>This test is included more for benchmarking convenience than anything else.</para>
    </subsection>
  </node>
  <node>
    <nodename>TCP_SENDFILE</nodename>
    <nodenext>UDP_STREAM</nodenext>
    <nodeprev>TCP_MAERTS</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>TCP_SENDFILE</title>
      <para>The TCP_SENDFILE test is &ldquo;just like&rdquo; a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test except netperf the platform's <code>sendfile()</code> call instead of calling <code>send()</code>.  Often this results in a <dfn>zero-copy</dfn> operation where data is sent directly from the filesystem buffer cache.  This _should_ result in lower CPU utilization and possibly higher throughput.  If it does not, then you may want to contact your vendor(s) because they have a problem on their hands.</para>
      <para>Zero-copy mechanisms may also alter the characteristics (size and number of buffers per) of packets passed to the NIC.  In many stacks, when a copy is performed, the stack can &ldquo;reserve&rdquo; space at the beginning of the destination buffer for things like TCP, IP and Link headers.  This then has the packet contained in a single buffer which can be easier to DMA to the NIC.  When no copy is performed, there is no opportunity to reserve space for headers and so a packet will be contained in two or more buffers.</para>
      <para>As of some time before version 2.5.0, the <xref><xrefnodename>Global Options</xrefnodename><xrefinfoname>global <option>-F</option> option</xrefinfoname></xref> is no longer required for this test.  If it is not specified, netperf will create a temporary file, which it will delete at the end of the test.  If the <option>-F</option> option is specified it must reference a file of at least the size of the send ring (See <xref><xrefnodename>Global Options</xrefnodename><xrefinfoname>the global <option>-W</option> option</xrefinfoname></xref>.) multiplied by the send size (See <xref><xrefnodename>Options common to TCP UDP and SCTP tests</xrefnodename><xrefinfoname>the test-specific <option>-m</option> option</xrefinfoname></xref>.).  All other TCP-specific options remain available and optional.</para>
      <para>In this first example:</para>
      <example xml:space="preserve">$ netperf -H lag -F ../src/netperf -t TCP_SENDFILE -- -s 128K -S 128K
TCP SENDFILE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to lag.hpl.hp.com (15.4.89.214) port 0 AF_INET
alloc_sendfile_buf_ring: specified file too small.
file must be larger than send_width * send_size</example>
      <para>we see what happens when the file is too small.  Here:</para>
      <example xml:space="preserve">$ netperf -H lag -F /boot/vmlinuz-2.6.8-1-686 -t TCP_SENDFILE -- -s 128K -S 128K
TCP SENDFILE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to lag.hpl.hp.com (15.4.89.214) port 0 AF_INET
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

131072 221184 221184    10.02      81.83</example>
      <para>we resolve that issue by selecting a larger file.</para>
    </subsection>
  </node>
  <node>
    <nodename>UDP_STREAM</nodename>
    <nodenext>XTI_TCP_STREAM</nodenext>
    <nodeprev>TCP_SENDFILE</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
    <subsection>
      <title>UDP_STREAM</title>
      <para>A UDP_STREAM test is similar to a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test except UDP is used as the transport rather than TCP.</para>
      <para><indexterm index="cp">Limiting Bandwidth</indexterm>A UDP_STREAM test has no end-to-end flow control - UDP provides none and neither does netperf.  However, if you wish, you can configure netperf with <code>--enable-intervals=yes</code> to enable the global command-line <option>-b</option> and <option>-w</option> options to pace bursts of traffic onto the network.</para>
      <para>This has a number of implications.</para>
      <para>The biggest of these implications is the data which is sent might not be received by the remote.  For this reason, the output of a UDP_STREAM test shows both the sending and receiving throughput.  On some platforms, it may be possible for the sending throughput to be reported as a value greater than the maximum rate of the link.  This is common when the CPU(s) are faster than the network and there is no <dfn>intra-stack</dfn> flow-control.</para>
      <para>Here is an example of a UDP_STREAM test between two systems connected by a 10 Gigabit Ethernet link:</para>
      <example xml:space="preserve">$ netperf -t UDP_STREAM -H 192.168.2.125 -- -m 32768
UDP UNIDIRECTIONAL SEND TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 192.168.2.125 (192.168.2.125) port 0 AF_INET
Socket  Message  Elapsed      Messages
Size    Size     Time         Okay Errors   Throughput
bytes   bytes    secs            #      #   10^6bits/sec

124928   32768   10.00      105672      0    2770.20
135168           10.00      104844           2748.50
</example>
      <para>The first line of numbers are statistics from the sending (netperf) side. The second line of numbers are from the receiving (netserver) side.  In this case, 105672 - 104844 or 828 messages did not make it all the way to the remote netserver process.</para>
      <para>If the value of the <option>-m</option> option is larger than the local send socket buffer size (<option>-s</option> option) netperf will likely abort with an error message about how the send call failed:</para>
      <example xml:space="preserve">netperf -t UDP_STREAM -H 192.168.2.125
UDP UNIDIRECTIONAL SEND TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 192.168.2.125 (192.168.2.125) port 0 AF_INET
udp_send: data send error: Message too long</example>
      <para>If the value of the <option>-m</option> option is larger than the remote socket receive buffer, the reported receive throughput will likely be zero as the remote UDP will discard the messages as being too large to fit into the socket buffer.</para>
      <example xml:space="preserve">$ netperf -t UDP_STREAM -H 192.168.2.125 -- -m 65000 -S 32768
UDP UNIDIRECTIONAL SEND TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 192.168.2.125 (192.168.2.125) port 0 AF_INET
Socket  Message  Elapsed      Messages
Size    Size     Time         Okay Errors   Throughput
bytes   bytes    secs            #      #   10^6bits/sec

124928   65000   10.00       53595      0    2786.99
 65536           10.00           0              0.00</example>
      <para>The example above was between a pair of systems running a &ldquo;Linux&rdquo; kernel. Notice that the remote Linux system returned a value larger than that passed-in to the <option>-S</option> option.  In fact, this value was larger than the message size set with the <option>-m</option> option. That the remote socket buffer size is reported as 65536 bytes would suggest to any sane person that a message of 65000 bytes would fit, but the socket isn't _really_ 65536 bytes, even though Linux is telling us so.  Go figure.</para>
    </subsection>
  </node>
  <node>
    <nodename>XTI_TCP_STREAM</nodename>
    <nodenext>XTI_UDP_STREAM</nodenext>
    <nodeprev>UDP_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
    <subsection>
      <title>XTI_TCP_STREAM</title>
      <para>An XTI_TCP_STREAM test is simply a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test using the XTI rather than BSD Sockets interface.  The test-specific <option>-X &lt;devspec&gt;</option> option can be used to specify the name of the local and/or remote XTI device files, which is required by the <code>t_open()</code> call made by netperf XTI tests.</para>
      <para>The XTI_TCP_STREAM test is only present if netperf was configured with <code>--enable-xti=yes</code>.  The remote netserver must have also been configured with <code>--enable-xti=yes</code>.</para>
    </subsection>
  </node>
  <node>
    <nodename>XTI_UDP_STREAM</nodename>
    <nodenext>SCTP_STREAM</nodenext>
    <nodeprev>XTI_TCP_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
    <subsection>
      <title>XTI_UDP_STREAM</title>
      <para>An XTI_UDP_STREAM test is simply a <xref><xrefnodename>UDP_STREAM</xrefnodename></xref> test using the XTI rather than BSD Sockets Interface.  The test-specific <option>-X &lt;devspec&gt;</option> option can be used to specify the name of the local and/or remote XTI device files, which is required by the <code>t_open()</code> call made by netperf XTI tests.</para>
      <para>The XTI_UDP_STREAM test is only present if netperf was configured with <code>--enable-xti=yes</code>. The remote netserver must have also been configured with <code>--enable-xti=yes</code>.</para>
    </subsection>
  </node>
  <node>
    <nodename>SCTP_STREAM</nodename>
    <nodenext>DLCO_STREAM</nodenext>
    <nodeprev>XTI_UDP_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
    <subsection>
      <title>SCTP_STREAM</title>
      <para>An SCTP_STREAM test is essentially a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test using the SCTP rather than TCP.  The <option>-D</option> option will set SCTP_NODELAY, which is much like the TCP_NODELAY option for TCP.  The <option>-C</option> option is not applicable to an SCTP test as there is no corresponding SCTP_CORK option.  The author is still figuring-out what the test-specific <option>-N</option> option does :)</para>
      <para>The SCTP_STREAM test is only present if netperf was configured with <code>--enable-sctp=yes</code>. The remote netserver must have also been configured with <code>--enable-sctp=yes</code>.</para>
    </subsection>
  </node>
  <node>
    <nodename>DLCO_STREAM</nodename>
    <nodenext>DLCL_STREAM</nodenext>
    <nodeprev>SCTP_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
    <subsection>
      <title>DLCO_STREAM</title>
      <para>A DLPI Connection Oriented Stream (DLCO_STREAM) test is very similar in concept to a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test.  Both use reliable, connection-oriented protocols.  The DLPI test differs from the TCP test in that its protocol operates only at the link-level and does not include TCP-style segmentation and reassembly.  This last difference means that the value  passed-in  with the <option>-m</option> option must be less than the interface MTU.  Otherwise, the <option>-m</option> and <option>-M</option> options are just like their TCP/UDP/SCTP counterparts.</para>
      <para>Other DLPI-specific options include:</para>
      <table>
        <tableitem>
          <tableterm><code>-D &lt;devspec&gt;</code></tableterm>
          <item>
            <para>This option is used to provide the fully-qualified names for the local and/or remote DLPI device files.  The syntax is otherwise identical to that of a <dfn>sizespec</dfn>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-p &lt;ppaspec&gt;</code></tableterm>
          <item>
            <para>This option is used to specify the local and/or remote DLPI PPA(s). The PPA is used to identify the interface over which traffic is to be sent/received. The syntax of a <dfn>ppaspec</dfn> is otherwise the same as a <dfn>sizespec</dfn>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-s sap</code></tableterm>
          <item>
            <para>This option specifies the 802.2 SAP for the test.  A SAP is somewhat like either the port field of a TCP or UDP header or the protocol field of an IP header.  The specified SAP should not conflict with any other active SAPs on the specified PPA's (<option>-p</option> option).</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-w &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option specifies the local send and receive window sizes in units of frames on those platforms which support setting such things.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-W &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option specifies the remote send and receive window sizes in units of frames on those platforms which support setting such things.</para>
          </item>
        </tableitem>
      </table>
      <para>The DLCO_STREAM test is only present if netperf was configured with <code>--enable-dlpi=yes</code>. The remote netserver must have also been configured with <code>--enable-dlpi=yes</code>.</para>
    </subsection>
  </node>
  <node>
    <nodename>DLCL_STREAM</nodename>
    <nodenext>STREAM_STREAM</nodenext>
    <nodeprev>DLCO_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
    <subsection>
      <title>DLCL_STREAM</title>
      <para>A DLPI ConnectionLess Stream (DLCL_STREAM) test is analogous to a <xref><xrefnodename>UDP_STREAM</xrefnodename></xref> test in that both make use of unreliable/best-effort, connection-less transports.  The DLCL_STREAM test differs from the <xref><xrefnodename>UDP_STREAM</xrefnodename></xref> test in that the message size (<option>-m</option> option) must always be less than the link MTU as there is no IP-like fragmentation and reassembly available and netperf does not presume to provide one.</para>
      <para>The test-specific command-line options for a DLCL_STREAM test are the same as those for a <xref><xrefnodename>DLCO_STREAM</xrefnodename></xref> test.</para>
      <para>The DLCL_STREAM test is only present if netperf was configured with <code>--enable-dlpi=yes</code>. The remote netserver must have also been configured with <code>--enable-dlpi=yes</code>.</para>
    </subsection>
  </node>
  <node>
    <nodename>STREAM_STREAM</nodename>
    <nodenext>DG_STREAM</nodenext>
    <nodeprev>DLCL_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>STREAM_STREAM</title>
      <para>A Unix Domain Stream Socket Stream test (STREAM_STREAM) is similar in concept to a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test, but using Unix Domain sockets.  It is, naturally, limited to intra-machine traffic.  A STREAM_STREAM test shares the <option>-m</option>, <option>-M</option>, <option>-s</option> and <option>-S</option> options of the other _STREAM tests.  In a STREAM_STREAM test the <option>-p</option> option sets the directory in which the pipes will be created rather than setting a port number.  The default is to create the pipes in the system default for the <code>tempnam()</code> call.</para>
      <para>The STREAM_STREAM test is only present if netperf was configured with <code>--enable-unixdomain=yes</code>. The remote netserver must have also been configured with <code>--enable-unixdomain=yes</code>.</para>
    </subsection>
  </node>
  <node>
    <nodename>DG_STREAM</nodename>
    <nodeprev>STREAM_STREAM</nodeprev>
    <nodeup>Options common to TCP UDP and SCTP tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>DG_STREAM</title>
      <para>A Unix Domain Datagram Socket Stream test (SG_STREAM) is very much like a <xref><xrefnodename>TCP_STREAM</xrefnodename></xref> test except that message boundaries are preserved. In this way, it may also be considered similar to certain flavors of SCTP test which can also preserve message boundaries.</para>
      <para>All the options of a <xref><xrefnodename>STREAM_STREAM</xrefnodename></xref> test are applicable to a DG_STREAM test.</para>
      <para>The DG_STREAM test is only present if netperf was configured with <code>--enable-unixdomain=yes</code>. The remote netserver must have also been configured with <code>--enable-unixdomain=yes</code>.</para>
    </subsection>
  </node>
  <node>
    <nodename>Using Netperf to Measure Request/Response</nodename>
    <nodenext>Using Netperf to Measure Aggregate Performance</nodenext>
    <nodeprev>Using Netperf to Measure Bulk Data Transfer</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>Using Netperf to Measure Request/Response</title>
      <para>Request/response performance is often overlooked, yet it is just as important as bulk-transfer performance.  While things like larger socket buffers and TCP windows, and stateless offloads like TSO and LRO can cover a multitude of latency and even path-length sins, those sins cannot easily hide from a request/response test.  The convention for a request/response test is to have a _RR suffix.  There are however a few &ldquo;request/response&rdquo; tests that have other suffixes.</para>
      <para>A request/response test, particularly synchronous, one transaction at a time test such as those found by default in netperf, is particularly sensitive to the path-length of the networking stack.  An _RR test can also uncover those platforms where the NICs are strapped by default with overbearing interrupt avoidance settings in an attempt to increase the bulk-transfer performance (or rather, decrease the CPU utilization of a bulk-transfer test).  This sensitivity is most acute for small request and response sizes, such as the single-byte default for a netperf _RR test.</para>
      <para>While a bulk-transfer test reports its results in units of bits or bytes transferred per second, by default a mumble_RR test reports transactions per second where a transaction is defined as the completed exchange of a request and a response.  One can invert the transaction rate to arrive at the average round-trip latency.  If one is confident about the symmetry of the connection, the average one-way latency can be taken as one-half the average round-trip latency. As of version 2.5.0 (actually slightly before) netperf still does not do the latter, but will do the former if one sets the verbosity to 2 for a classic netperf test, or includes the appropriate <xref><xrefnodename>Omni Output Selectors</xrefnodename><xrefinfoname>output selector</xrefinfoname></xref> in an <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni test</xrefinfoname></xref>.  It will also allow the user to switch the throughput units from transactions per second to bits or bytes per second with the global <option>-f</option> option.</para>
      <menu>
        <menuentry>
          <menunode>Issues in Request/Response</menunode>
          <menutitle>Issues in Request/Response</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Options Common to TCP UDP and SCTP _RR tests</menunode>
          <menutitle>Options Common to TCP UDP and SCTP _RR tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Issues in Request/Response</nodename>
    <nodenext>Options Common to TCP UDP and SCTP _RR tests</nodenext>
    <nodeprev>Using Netperf to Measure Request/Response</nodeprev>
    <nodeup>Using Netperf to Measure Request/Response</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Issues in Request/Response</title>
      <para>Most if not all the <xref><xrefnodename>Issues in Bulk Transfer</xrefnodename></xref> apply to request/response.  The issue of round-trip latency is even more important as netperf generally only has one transaction outstanding at a time.</para>
      <para>A single instance of a one transaction outstanding _RR test should _never_ completely saturate the CPU of a system.  If testing between otherwise evenly matched systems, the symmetric nature of a _RR test with equal request and response sizes should result in equal CPU loading on both systems. However, this may not hold true on MP systems, particularly if one CPU binds the netperf and netserver differently via the global <option>-T</option> option.</para>
      <para>For smaller request and response sizes packet loss is a bigger issue as there is no opportunity for a <dfn>fast retransmit</dfn> or retransmission prior to a retransmission timer expiring.</para>
      <para>Virtualization may considerably increase the effective path length of a networking stack.  While this may not preclude achieving link-rate on a comparatively slow link (eg 1 Gigabit Ethernet) on a _STREAM test, it can show-up as measurably fewer transactions per second on an _RR test.  However, this may still be masked by interrupt coalescing in the NIC/driver.</para>
      <para>Certain NICs have ways to minimize the number of interrupts sent to the host.  If these are strapped badly they can significantly reduce the performance of something like a single-byte request/response test. Such setups are distinguished by seriously low reported CPU utilization and what seems like a low (even if in the thousands) transaction per second rate.  Also, if you run such an OS/driver combination on faster or slower hardware and do not see a corresponding change in the transaction rate, chances are good that the driver is strapping the NIC with aggressive interrupt avoidance settings.  Good for bulk throughput, but bad for latency.</para>
      <para>Some drivers may try to automagically adjust the interrupt avoidance settings.  If they are not terribly good at it, you will see considerable run-to-run variation in reported transaction rates. Particularly if you &ldquo;mix-up&rdquo; _STREAM and _RR tests.</para>
    </section>
  </node>
  <node>
    <nodename>Options Common to TCP UDP and SCTP _RR tests</nodename>
    <nodeprev>Issues in Request/Response</nodeprev>
    <nodeup>Using Netperf to Measure Request/Response</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Options Common to TCP UDP and SCTP _RR tests</title>
      <para>Many &ldquo;test-specific&rdquo; options are actually common across the different tests.  For those tests involving TCP, UDP and SCTP, whether using the BSD Sockets or the XTI interface those common options include:</para>
      <table><indexterm index="vr">-h, Test-specific</indexterm>
        <tableitem>
          <tableterm><code>-h</code></tableterm>
          <item>
            <para>Display the test-suite-specific usage string and exit.  For a TCP_ or UDP_ test this will be the usage string from the source file <file>nettest_bsd.c</file>.  For an XTI_ test, this will be the usage string from the source file <file>src/nettest_xti.c</file>.  For an SCTP test, this will be the usage string from the source file <file>src/nettest_sctp.c</file>.</para>
            <para><indexterm index="vr">-H, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-H &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>Normally, the remote hostname|IP and address family information is inherited from the settings for the control connection (eg global command-line <option>-H</option>, <option>-4</option> and/or <option>-6</option> options. The test-specific <option>-H</option> will override those settings for the data (aka test) connection only.  Settings for the control connection are left unchanged.  This might be used to cause the control and data connections to take different paths through the network.</para>
            <para><indexterm index="vr">-L, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-L &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>The test-specific <option>-L</option> option is identical to the test-specific <option>-H</option> option except it affects the local hostname|IP and address family information.  As with its global command-line counterpart, this is generally only useful when measuring though those evil, end-to-end breaking things called firewalls.</para>
            <para><indexterm index="vr">-P, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-P &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>Set the local and/or remote port numbers for the data connection.</para>
            <para><indexterm index="vr">-r, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-r &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option sets the request (first value) and/or response (second value) sizes for an _RR test. By default the units are bytes, but a suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively.  A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively. For example:</para>
            <example xml:space="preserve"><code>-r 128,16K</code></example>
            <para>Will set the request size to 128 bytes and the response size to 16 KB or 16384 bytes. [Default: 1 - a single-byte request and response ]</para>
            <para><indexterm index="vr">-s, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-s &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option sets the local (netperf) send and receive socket buffer sizes for the data connection to the value(s) specified.  Often, this will affect the advertised and/or effective TCP or other window, but on some platforms it may not. By default the units are bytes, but a suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively.  A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively. For example:</para>
            <example xml:space="preserve"><code>-s 128K</code></example>
            <para>Will request the local send (netperf) and receive socket buffer sizes to be 128KB or 131072 bytes.</para>
            <para>While the historic expectation is that setting the socket buffer size has a direct effect on say the TCP window, today that may not hold true for all stacks.  When running under Windows a value of 0 may be used which will be an indication to the stack the user wants to enable a form of copy avoidance. [Default: -1 - use the system's default socket buffer sizes]</para>
            <para><indexterm index="vr">-S, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-S &lt;sizespec&gt;</code></tableterm>
          <item>
            <para>This option sets the remote (netserver) send and/or receive socket buffer sizes for the data connection to the value(s) specified. Often, this will affect the advertised and/or effective TCP or other window, but on some platforms it may not. By default the units are bytes, but a suffix of &ldquo;G,&rdquo; &ldquo;M,&rdquo; or &ldquo;K&rdquo; will specify the units to be 2^30 (GB), 2^20 (MB) or 2^10 (KB) respectively.  A suffix of &ldquo;g,&rdquo; &ldquo;m&rdquo; or &ldquo;k&rdquo; will specify units of 10^9, 10^6 or 10^3 bytes respectively.  For example:</para>
            <example xml:space="preserve"><code>-s 128K</code></example>
            <para>Will request the remote (netserver) send and receive socket buffer sizes to be 128KB or 131072 bytes.</para>
            <para>While the historic expectation is that setting the socket buffer size has a direct effect on say the TCP window, today that may not hold true for all stacks.  When running under Windows a value of 0 may be used which will be an indication to the stack the user wants to enable a form of copy avoidance.  [Default: -1 - use the system's default socket buffer sizes]</para>
            <para><indexterm index="vr">-4, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-4</code></tableterm>
          <item>
            <para>Set the local and remote address family for the data connection to AF_INET - ie use IPv4 addressing only.  Just as with their global command-line counterparts the last of the <option>-4</option>, <option>-6</option>, <option>-H</option> or <option>-L</option> option wins for their respective address families.</para>
            <para><indexterm index="vr">-6 Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-6</code></tableterm>
          <item>
            <para>This option is identical to its <option>-4</option> cousin, but requests IPv6 addresses for the local and remote ends of the data connection.</para>
          </item>
        </tableitem>
      </table>
      <menu>
        <menuentry>
          <menunode>TCP_RR</menunode>
          <menutitle>TCP_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>TCP_CC</menunode>
          <menutitle>TCP_CC</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>TCP_CRR</menunode>
          <menutitle>TCP_CRR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>UDP_RR</menunode>
          <menutitle>UDP_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>XTI_TCP_RR</menunode>
          <menutitle>XTI_TCP_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>XTI_TCP_CC</menunode>
          <menutitle>XTI_TCP_CC</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>XTI_TCP_CRR</menunode>
          <menutitle>XTI_TCP_CRR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>XTI_UDP_RR</menunode>
          <menutitle>XTI_UDP_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>DLCL_RR</menunode>
          <menutitle>DLCL_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>DLCO_RR</menunode>
          <menutitle>DLCO_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>SCTP_RR</menunode>
          <menutitle>SCTP_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </section>
  </node>
  <node>
    <nodename>TCP_RR</nodename>
    <nodenext>TCP_CC</nodenext>
    <nodeprev>Options Common to TCP UDP and SCTP _RR tests</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
    <subsection>
      <title>TCP_RR</title>
      <para><indexterm index="cp">Measuring Latency</indexterm><indexterm index="cp">Latency, Request-Response</indexterm> A TCP_RR (TCP Request/Response) test is requested by passing a value of &ldquo;TCP_RR&rdquo; to the global <option>-t</option> command-line option.  A TCP_RR test can be thought-of as a user-space to user-space <code>ping</code> with no think time - it is by default a synchronous, one transaction at a time, request/response test.</para>
      <para>The transaction rate is the number of complete transactions exchanged divided by the length of time it took to perform those transactions.</para>
      <para>If the two Systems Under Test are otherwise identical, a TCP_RR test with the same request and response size should be symmetric - it should not matter which way the test is run, and the CPU utilization measured should be virtually the same on each system.  If not, it suggests that the CPU utilization mechanism being used may have some, well, issues measuring CPU utilization completely and accurately.</para>
      <para>Time to establish the TCP connection is not counted in the result.  If you want connection setup overheads included, you should consider the <xref><xrefnodename>TCP_CC</xrefnodename><xrefinfoname>TPC_CC</xrefinfoname></xref> or <xref><xrefnodename>TCP_CRR</xrefnodename><xrefinfoname>TCP_CRR</xrefinfoname></xref> tests.</para>
      <para>If specifying the <option>-D</option> option to set TCP_NODELAY and disable the Nagle Algorithm increases the transaction rate reported by a TCP_RR test, it implies the stack(s) over which the TCP_RR test is running have a broken implementation of the Nagle Algorithm.  Likely as not they are interpreting Nagle on a segment by segment basis rather than a user send by user send basis.  You should contact your stack vendor(s) to report the problem to them.</para>
      <para>Here is an example of two systems running a basic TCP_RR test over a 10 Gigabit Ethernet link:</para>
      <example xml:space="preserve">netperf -t TCP_RR -H 192.168.2.125
TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 192.168.2.125 (192.168.2.125) port 0 AF_INET
Local /Remote
Socket Size   Request  Resp.   Elapsed  Trans.
Send   Recv   Size     Size    Time     Rate
bytes  Bytes  bytes    bytes   secs.    per sec

16384  87380  1        1       10.00    29150.15
16384  87380</example>
      <para>In this example the request and response sizes were one byte, the socket buffers were left at their defaults, and the test ran for all of 10 seconds.  The transaction per second rate was rather good for the time :)</para>
    </subsection>
  </node>
  <node>
    <nodename>TCP_CC</nodename>
    <nodenext>TCP_CRR</nodenext>
    <nodeprev>TCP_RR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
    <subsection>
      <title>TCP_CC</title>
      <para><indexterm index="cp">Connection Latency</indexterm><indexterm index="cp">Latency, Connection Establishment</indexterm> A TCP_CC (TCP Connect/Close) test is requested by passing a value of &ldquo;TCP_CC&rdquo; to the global <option>-t</option> option.  A TCP_CC test simply measures how fast the pair of systems can open and close connections between one another in a synchronous (one at a time) manner.  While this is considered an _RR test, no request or response is exchanged over the connection.</para>
      <para><indexterm index="cp">Port Reuse</indexterm><indexterm index="cp">TIME_WAIT</indexterm>The issue of TIME_WAIT reuse is an important one for a TCP_CC test. Basically, TIME_WAIT reuse is when a pair of systems churn through connections fast enough that they wrap the 16-bit port number space in less time than the length of the TIME_WAIT state.  While it is indeed theoretically possible to &ldquo;reuse&rdquo; a connection in TIME_WAIT, the conditions under which such reuse is possible are rather rare.  An attempt to reuse a connection in TIME_WAIT can result in a non-trivial delay in connection establishment.</para>
      <para>Basically, any time the connection churn rate approaches:</para>
      <para>Sizeof(clientportspace) / Lengthof(TIME_WAIT)</para>
      <para>there is the risk of TIME_WAIT reuse.  To minimize the chances of this happening, netperf will by default select its own client port numbers from the range of 5000 to 65535.  On systems with a 60 second TIME_WAIT state, this should allow roughly 1000 transactions per second.  The size of the client port space used by netperf can be controlled via the test-specific <option>-p</option> option, which takes a <dfn>sizespec</dfn> as a value setting the minimum (first value) and maximum (second value) port numbers used by netperf at the client end.</para>
      <para>Since no requests or responses are exchanged during a TCP_CC test, only the <option>-H</option>, <option>-L</option>, <option>-4</option> and <option>-6</option> of the &ldquo;common&rdquo; test-specific options are likely to have an effect, if any, on the results.  The <option>-s</option> and <option>-S</option> options _may_ have some effect if they alter the number and/or type of options carried in the TCP SYNchronize segments, such as Window Scaling or Timestamps. The <option>-P</option> and <option>-r</option> options are utterly ignored.</para>
      <para>Since connection establishment and tear-down for TCP is not symmetric, a TCP_CC test is not symmetric in its loading of the two systems under test.</para>
    </subsection>
  </node>
  <node>
    <nodename>TCP_CRR</nodename>
    <nodenext>UDP_RR</nodenext>
    <nodeprev>TCP_CC</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
    <subsection>
      <title>TCP_CRR</title>
      <para><indexterm index="cp">Latency, Connection Establishment</indexterm><indexterm index="cp">Latency, Request-Response</indexterm> The TCP Connect/Request/Response (TCP_CRR) test is requested by passing a value of &ldquo;TCP_CRR&rdquo; to the global <option>-t</option> command-line option.  A TCP_CRR test is like a merger of a <xref><xrefnodename>TCP_RR</xrefnodename></xref> and <xref><xrefnodename>TCP_CC</xrefnodename></xref> test which measures the performance of establishing a connection, exchanging a single request/response transaction, and tearing-down that connection.  This is very much like what happens in an HTTP 1.0 or HTTP 1.1 connection when HTTP Keepalives are not used. In fact, the TCP_CRR test was added to netperf to simulate just that.</para>
      <para>Since a request and response are exchanged the <option>-r</option>, <option>-s</option> and <option>-S</option> options can have an effect on the performance.</para>
      <para>The issue of TIME_WAIT reuse exists for the TCP_CRR test just as it does for the TCP_CC test.  Similarly, since connection establishment and tear-down is not symmetric, a TCP_CRR test is not symmetric even when the request and response sizes are the same.</para>
    </subsection>
  </node>
  <node>
    <nodename>UDP_RR</nodename>
    <nodenext>XTI_TCP_RR</nodenext>
    <nodeprev>TCP_CRR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
    <subsection>
      <title>UDP_RR</title>
      <para><indexterm index="cp">Latency, Request-Response</indexterm><indexterm index="cp">Packet Loss</indexterm> A UDP Request/Response (UDP_RR) test is requested by passing a value of &ldquo;UDP_RR&rdquo; to a global <option>-t</option> option.  It is very much the same as a TCP_RR test except UDP is used rather than TCP.</para>
      <para>UDP does not provide for retransmission of lost UDP datagrams, and netperf does not add anything for that either.  This means that if _any_ request or response is lost, the exchange of requests and responses will stop from that point until the test timer expires. Netperf will not really &ldquo;know&rdquo; this has happened - the only symptom will be a low transaction per second rate.  If <option>--enable-burst</option> was included in the <code>configure</code> command and a test-specific <option>-b</option> option used, the UDP_RR test will &ldquo;survive&rdquo; the loss of requests and responses until the sum is one more than the value passed via the <option>-b</option> option. It will though almost certainly run more slowly.</para>
      <para>The netperf side of a UDP_RR test will call <code>connect()</code> on its data socket and thenceforth use the <code>send()</code> and <code>recv()</code> socket calls.  The netserver side of a UDP_RR test will not call <code>connect()</code> and will use <code>recvfrom()</code> and <code>sendto()</code> calls.  This means that even if the request and response sizes are the same, a UDP_RR test is _not_ symmetric in its loading of the two systems under test.</para>
      <para>Here is an example of a UDP_RR test between two otherwise identical two-CPU systems joined via a 1 Gigabit Ethernet network:</para>
      <example xml:space="preserve">$ netperf -T 1 -H 192.168.1.213 -t UDP_RR -c -C
UDP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 192.168.1.213 (192.168.1.213) port 0 AF_INET
Local /Remote
Socket Size   Request Resp.  Elapsed Trans.   CPU    CPU    S.dem   S.dem
Send   Recv   Size    Size   Time    Rate     local  remote local   remote
bytes  bytes  bytes   bytes  secs.   per sec  % I    % I    us/Tr   us/Tr

65535  65535  1       1      10.01   15262.48   13.90  16.11  18.221  21.116
65535  65535</example>
      <para>This example includes the <option>-c</option> and <option>-C</option> options to enable CPU utilization reporting and shows the asymmetry in CPU loading.  The <option>-T</option> option was used to make sure netperf and netserver ran on a given CPU and did not move around during the test.</para>
    </subsection>
  </node>
  <node>
    <nodename>XTI_TCP_RR</nodename>
    <nodenext>XTI_TCP_CC</nodenext>
    <nodeprev>UDP_RR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
    <subsection>
      <title>XTI_TCP_RR</title>
      <para><indexterm index="cp">Latency, Request-Response</indexterm> An XTI_TCP_RR test is essentially the same as a <xref><xrefnodename>TCP_RR</xrefnodename></xref> test only using the XTI rather than BSD Sockets interface. It is requested by passing a value of &ldquo;XTI_TCP_RR&rdquo; to the <option>-t</option> global command-line option.</para>
      <para>The test-specific options for an XTI_TCP_RR test are the same as those for a TCP_RR test with the addition of the <option>-X &lt;devspec&gt;</option> option to specify the names of the local and/or remote XTI device file(s).</para>
    </subsection>
  </node>
  <node>
    <nodename>XTI_TCP_CC</nodename>
    <nodenext>XTI_TCP_CRR</nodenext>
    <nodeprev>XTI_TCP_RR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>XTI_TCP_CC</title>
      <para><indexterm index="cp">Latency, Connection Establishment</indexterm> An XTI_TCP_CC test is essentially the same as a <xref><xrefnodename>TCP_CC</xrefnodename><xrefinfoname>TCP_CC</xrefinfoname></xref> test, only using the XTI rather than BSD Sockets interface.</para>
      <para>The test-specific options for an XTI_TCP_CC test are the same as those for a TCP_CC test with the addition of the <option>-X &lt;devspec&gt;</option> option to specify the names of the local and/or remote XTI device file(s).</para>
    </subsection>
  </node>
  <node>
    <nodename>XTI_TCP_CRR</nodename>
    <nodenext>XTI_UDP_RR</nodenext>
    <nodeprev>XTI_TCP_CC</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>XTI_TCP_CRR</title>
      <para><indexterm index="cp">Latency, Connection Establishment</indexterm><indexterm index="cp">Latency, Request-Response</indexterm> The XTI_TCP_CRR test is essentially the same as a <xref><xrefnodename>TCP_CRR</xrefnodename><xrefinfoname>TCP_CRR</xrefinfoname></xref> test, only using the XTI rather than BSD Sockets interface.</para>
      <para>The test-specific options for an XTI_TCP_CRR test are the same as those for a TCP_RR test with the addition of the <option>-X &lt;devspec&gt;</option> option to specify the names of the local and/or remote XTI device file(s).</para>
    </subsection>
  </node>
  <node>
    <nodename>XTI_UDP_RR</nodename>
    <nodenext>DLCL_RR</nodenext>
    <nodeprev>XTI_TCP_CRR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
    <subsection>
      <title>XTI_UDP_RR</title>
      <para><indexterm index="cp">Latency, Request-Response</indexterm> An XTI_UDP_RR test is essentially the same as a UDP_RR test only using the XTI rather than BSD Sockets interface.  It is requested by passing a value of &ldquo;XTI_UDP_RR&rdquo; to the <option>-t</option> global command-line option.</para>
      <para>The test-specific options for an XTI_UDP_RR test are the same as those for a UDP_RR test with the addition of the <option>-X &lt;devspec&gt;</option> option to specify the name of the local and/or remote XTI device file(s).</para>
    </subsection>
  </node>
  <node>
    <nodename>DLCL_RR</nodename>
    <nodenext>DLCO_RR</nodenext>
    <nodeprev>XTI_UDP_RR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>DLCL_RR</title>
      <para><indexterm index="cp">Latency, Request-Response</indexterm></para>
    </subsection>
  </node>
  <node>
    <nodename>DLCO_RR</nodename>
    <nodenext>SCTP_RR</nodenext>
    <nodeprev>DLCL_RR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>DLCO_RR</title>
      <para><indexterm index="cp">Latency, Request-Response</indexterm></para>
    </subsection>
  </node>
  <node>
    <nodename>SCTP_RR</nodename>
    <nodeprev>DLCO_RR</nodeprev>
    <nodeup>Options Common to TCP UDP and SCTP _RR tests</nodeup>
<!-- node-name,  next,  previous,  up -->
    <subsection>
      <title>SCTP_RR</title>
      <para><indexterm index="cp">Latency, Request-Response</indexterm></para>
    </subsection>
  </node>
  <node>
    <nodename>Using Netperf to Measure Aggregate Performance</nodename>
    <nodenext>Using Netperf to Measure Bidirectional Transfer</nodenext>
    <nodeprev>Using Netperf to Measure Request/Response</nodeprev>
    <nodeup>Top</nodeup>
<!-- node-name,  next,  previous,  up -->
    <chapter>
      <title>Using Netperf to Measure Aggregate Performance</title>
      <para><indexterm index="cp">Aggregate Performance</indexterm><indexterm index="vr">&ndash;enable-burst, Configure</indexterm> Ultimately, <xref><xrefnodename>Netperf4</xrefnodename><xrefinfoname>Netperf4</xrefinfoname></xref> will be the preferred benchmark to use when one wants to measure aggregate performance because netperf has no support for explicit synchronization of concurrent tests. Until netperf4 is ready for prime time, one can make use of the heuristics and procedures mentioned here for the 85% solution.</para>
      <para>There are a few ways to measure aggregate performance with netperf. The first is to run multiple, concurrent netperf tests and can be applied to any of the netperf tests.  The second is to configure netperf with <code>--enable-burst</code> and is applicable to the TCP_RR test. The third is a variation on the first.</para>
      <menu>
        <menuentry>
          <menunode>Running Concurrent Netperf Tests</menunode>
          <menutitle>Running Concurrent Netperf Tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Using --enable-burst</menunode>
          <menutitle>Using &ndash;enable-burst</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Using --enable-demo</menunode>
          <menutitle>Using &ndash;enable-demo</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Running Concurrent Netperf Tests</nodename>
    <nodenext>Using --enable-burst</nodenext>
    <nodeprev>Using Netperf to Measure Aggregate Performance</nodeprev>
    <nodeup>Using Netperf to Measure Aggregate Performance</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Running Concurrent Netperf Tests</title>
      <para><xref><xrefnodename>Netperf4</xrefnodename><xrefinfoname>Netperf4</xrefinfoname></xref> is the preferred benchmark to use when one wants to measure aggregate performance because netperf has no support for explicit synchronization of concurrent tests.  This leaves netperf2 results vulnerable to <dfn>skew</dfn> errors.</para>
      <para>However, since there are times when netperf4 is unavailable it may be necessary to run netperf. The skew error can be minimized by making use of the confidence interval functionality.  Then one simply launches multiple tests from the shell using a <code>for</code> loop or the like:</para>
      <example xml:space="preserve">for i in 1 2 3 4
do
netperf -t TCP_STREAM -H tardy.cup.hp.com -i 10 -P 0 &amp;
done</example>
      <para>which will run four, concurrent <xref><xrefnodename>TCP_STREAM</xrefnodename><xrefinfoname>TCP_STREAM</xrefinfoname></xref> tests from the system on which it is executed to tardy.cup.hp.com.  Each concurrent netperf will iterate 10 times thanks to the <option>-i</option> option and will omit the test banners (option <option>-P</option>) for brevity.  The output looks something like this:</para>
      <example xml:space="preserve"> 87380  16384  16384    10.03     235.15
 87380  16384  16384    10.03     235.09
 87380  16384  16384    10.03     235.38
 87380  16384  16384    10.03     233.96</example>
      <para>We can take the sum of the results and be reasonably confident that the aggregate performance was 940 Mbits/s.</para>
      <para>If you see warnings about netperf not achieving the confidence intervals, the best thing to do is to increase the number of iterations with <option>-i</option> and/or increase the run length of each iteration with <option>-l</option>.</para>
      <para>You can also enable local (<option>-c</option>) and/or remote (<option>-C</option>) CPU utilization:</para>
      <example xml:space="preserve">for i in 1 2 3 4
do
netperf -t TCP_STREAM -H tardy.cup.hp.com -i 10 -P 0 -c -C &amp;
done

87380  16384  16384    10.03       235.47   3.67     5.09     10.226  14.180
87380  16384  16384    10.03       234.73   3.67     5.09     10.260  14.225
87380  16384  16384    10.03       234.64   3.67     5.10     10.263  14.231
87380  16384  16384    10.03       234.87   3.67     5.09     10.253  14.215</example>
      <para>If the CPU utilizations reported for the same system are the same or very very close you can be reasonably confident that skew error is minimized.  Presumably one could then omit <option>-i</option> but that is not advised, particularly when/if the CPU utilization approaches 100 percent.  In the example above we see that the CPU utilization on the local system remains the same for all four tests, and is only off by 0.01 out of 5.09 on the remote system.  As the number of CPUs in the system increases, and so too the odds of saturating a single CPU, the accuracy of similar CPU utilization implying little skew error is diminished.  This is also the case for those increasingly rare single CPU systems if the utilization is reported as 100% or very close to it.</para>
      <quotation>
        <para><b>NOTE: It is very important to remember that netperf is calculating system-wide CPU utilization.  When calculating the service demand (those last two columns in the output above) each netperf assumes it is the only thing running on the system.  This means that for concurrent tests the service demands reported by netperf will be wrong.  One has to compute service demands for concurrent tests by hand.</b></para>
      </quotation>
      <para>If you wish you can add a unique, global <option>-B</option> option to each command line to append the given string to the output:</para>
      <example xml:space="preserve">for i in 1 2 3 4
do
netperf -t TCP_STREAM -H tardy.cup.hp.com -B "this is test $i" -i 10 -P 0 &amp;
done

87380  16384  16384    10.03     234.90   this is test 4
87380  16384  16384    10.03     234.41   this is test 2
87380  16384  16384    10.03     235.26   this is test 1
87380  16384  16384    10.03     235.09   this is test 3</example>
      <para>You will notice that the tests completed in an order other than they were started from the shell.  This underscores why there is a threat of skew error and why netperf4 is the preferred tool for aggregate tests.  Even if you see the Netperf Contributing Editor acting to the contrary!-)</para>
      <menu>
        <menuentry>
          <menunode>Issues in Running Concurrent Tests</menunode>
          <menutitle>Issues in Running Concurrent Tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </section>
  </node>
  <node>
    <nodename>Issues in Running Concurrent Tests</nodename>
    <nodeprev>Running Concurrent Netperf Tests</nodeprev>
    <nodeup>Running Concurrent Netperf Tests</nodeup>
    <subsection>
      <title>Issues in Running Concurrent Tests</title>
      <para>In addition to the aforementioned issue of skew error, there can be other issues to consider when running concurrent netperf tests.</para>
      <para>For example, when running concurrent tests over multiple interfaces, one is not always assured that the traffic one thinks went over a given interface actually did so.  In particular, the Linux networking stack takes a particularly strong stance on its following the so called <samp>weak end system model</samp>.  As such, it is willing to answer ARP requests for any of its local IP addresses on any of its interfaces.  If multiple interfaces are connected to the same broadcast domain, then even if they are configured into separate IP subnets there is no a priori way of knowing which interface was actually used for which connection(s).  This can be addressed by setting the <samp>arp_ignore</samp> sysctl before configuring interfaces.</para>
      <para>As it is quite important, we will repeat that it is very important to remember that each concurrent netperf instance is calculating system-wide CPU utilization.  When calculating the service demand each netperf assumes it is the only thing running on the system.  This means that for concurrent tests the service demands reported by netperf <b>will be wrong</b>.  One has to compute service demands for concurrent tests by hand</para>
      <para>Running concurrent tests can also become difficult when there is no one &ldquo;central&rdquo; node.  Running tests between pairs of systems may be more difficult, calling for remote shell commands in the for loop rather than netperf commands.  This introduces more skew error, which the confidence intervals may not be able to sufficiently mitigate. One possibility is to actually run three consecutive netperf tests on each node - the first being a warm-up, the last being a cool-down. The idea then is to ensure that the time it takes to get all the netperfs started is less than the length of the first netperf command in the sequence of three.  Similarly, it assumes that all &ldquo;middle&rdquo; netperfs will complete before the first of the &ldquo;last&rdquo; netperfs complete.</para>
    </subsection>
  </node>
  <node>
    <nodename>Using --enable-burst</nodename>
    <nodenext>Using --enable-demo</nodenext>
    <nodeprev>Running Concurrent Netperf Tests</nodeprev>
    <nodeup>Using Netperf to Measure Aggregate Performance</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Using - -enable-burst</title>
      <para>Starting in version 2.5.0 <code>--enable-burst=yes</code> is the default, which means one no longer must:</para>
      <example xml:space="preserve">configure --enable-burst</example>
      <para>To have burst-mode functionality present in netperf.  This enables a test-specific <option>-b num</option> option in <xref><xrefnodename>TCP_RR</xrefnodename><xrefinfoname>TCP_RR</xrefinfoname></xref>, <xref><xrefnodename>UDP_RR</xrefnodename><xrefinfoname>UDP_RR</xrefinfoname></xref> and <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>omni</xrefinfoname></xref> tests.</para>
      <para>Normally, netperf will attempt to ramp-up the number of outstanding requests to <option>num</option> plus one transactions in flight at one time. The ramp-up is to avoid transactions being smashed together into a smaller number of segments when the transport's congestion window (if any) is smaller at the time than what netperf wants to have outstanding at one time. If, however, the user specifies a negative value for <option>num</option> this ramp-up is bypassed and the burst of sends is made without consideration of transport congestion window.</para>
      <para>This burst-mode is used as an alternative to or even in conjunction with multiple-concurrent _RR tests and as a way to implement a single-connection, bidirectional bulk-transfer test.  When run with just a single instance of netperf, increasing the burst size can determine the maximum number of transactions per second which can be serviced by a single process:</para>
      <example xml:space="preserve">for b in 0 1 2 4 8 16 32
do
 netperf -v 0 -t TCP_RR -B "-b $b" -H hpcpc108 -P 0 -- -b $b
done

9457.59 -b 0
9975.37 -b 1
10000.61 -b 2
20084.47 -b 4
29965.31 -b 8
71929.27 -b 16
109718.17 -b 32</example>
      <para>The global <option>-v</option> and <option>-P</option> options were used to minimize the output to the single figure of merit which in this case the transaction rate.  The global <code>-B</code> option was used to more clearly label the output, and the test-specific <option>-b</option> option enabled by <code>--enable-burst</code> increase the number of transactions in flight at one time.</para>
      <para>Now, since the test-specific <option>-D</option> option was not specified to set TCP_NODELAY, the stack was free to &ldquo;bundle&rdquo; requests and/or responses into TCP segments as it saw fit, and since the default request and response size is one byte, there could have been some considerable bundling even in the absence of transport congestion window issues.  If one wants to try to achieve a closer to one-to-one correspondence between a request and response and a TCP segment, add the test-specific <option>-D</option> option:</para>
      <example xml:space="preserve">for b in 0 1 2 4 8 16 32
do
 netperf -v 0 -t TCP_RR -B "-b $b -D" -H hpcpc108 -P 0 -- -b $b -D
done

 8695.12 -b 0 -D
 19966.48 -b 1 -D
 20691.07 -b 2 -D
 49893.58 -b 4 -D
 62057.31 -b 8 -D
 108416.88 -b 16 -D
 114411.66 -b 32 -D</example>
      <para>You can see that this has a rather large effect on the reported transaction rate.  In this particular instance, the author believes it relates to interactions between the test and interrupt coalescing settings in the driver for the NICs used.</para>
      <quotation>
        <para><b>NOTE: Even if you set the <option>-D</option> option that is still not a guarantee that each transaction is in its own TCP segments.  You should get into the habit of verifying the relationship between the transaction rate and the packet rate via other means.</b></para>
      </quotation>
      <para>You can also combine <code>--enable-burst</code> functionality with concurrent netperf tests.  This would then be an &ldquo;aggregate of aggregates&rdquo; if you like:</para>
      <example xml:space="preserve">
for i in 1 2 3 4
do
 netperf -H hpcpc108 -v 0 -P 0 -i 10 -B "aggregate $i -b 8 -D" -t TCP_RR -- -b 8 -D &amp;
done

 46668.38 aggregate 4 -b 8 -D
 44890.64 aggregate 2 -b 8 -D
 45702.04 aggregate 1 -b 8 -D
 46352.48 aggregate 3 -b 8 -D
</example>
      <para>Since each netperf did hit the confidence intervals, we can be reasonably certain that the aggregate transaction per second rate was the sum of all four concurrent tests, or something just shy of 184,000 transactions per second.  To get some idea if that was also the packet per second rate, we could bracket that <code>for</code> loop with something to gather statistics and run the results through <uref><urefurl>ftp://ftp.cup.hp.com/dist/networking/tools</urefurl><urefdesc>beforeafter</urefdesc></uref>:</para>
      <example xml:space="preserve">/usr/sbin/ethtool -S eth2 &gt; before
for i in 1 2 3 4
do
 netperf -H 192.168.2.108 -l 60 -v 0 -P 0 -B "aggregate $i -b 8 -D" -t TCP_RR -- -b 8 -D &amp;
done
wait
/usr/sbin/ethtool -S eth2 &gt; after

 52312.62 aggregate 2 -b 8 -D
 50105.65 aggregate 4 -b 8 -D
 50890.82 aggregate 1 -b 8 -D
 50869.20 aggregate 3 -b 8 -D

beforeafter before after &gt; delta

grep packets delta
     rx_packets: 12251544
     tx_packets: 12251550
</example>
      <para>This example uses <code>ethtool</code> because the system being used is running Linux.  Other platforms have other tools - for example HP-UX has lanadmin:</para>
      <example xml:space="preserve">lanadmin -g mibstats &lt;ppa&gt;</example>
      <para>and of course one could instead use <code>netstat</code>.</para>
      <para>The <code>wait</code> is important because we are launching concurrent netperfs in the background.  Without it, the second ethtool command would be run before the tests finished and perhaps even before the last of them got started!</para>
      <para>The sum of the reported transaction rates is 204178 over 60 seconds, which is a total of 12250680 transactions.  Each transaction is the exchange of a request and a response, so we multiply that by 2 to arrive at 24501360.</para>
      <para>The sum of the ethtool stats is 24503094 packets which matches what netperf was reporting very well.</para>
      <para>Had the request or response size differed, we would need to know how it compared with the <dfn>MSS</dfn> for the connection.</para>
      <para>Just for grins, here is the exercise repeated, using <code>netstat</code> instead of <code>ethtool</code></para>
      <example xml:space="preserve">netstat -s -t &gt; before
for i in 1 2 3 4
do
 netperf -l 60 -H 192.168.2.108 -v 0 -P 0 -B "aggregate $i -b 8 -D" -t TCP_RR -- -b 8 -D &amp; done
wait
netstat -s -t &gt; after

 51305.88 aggregate 4 -b 8 -D
 51847.73 aggregate 2 -b 8 -D
 50648.19 aggregate 3 -b 8 -D
 53605.86 aggregate 1 -b 8 -D

beforeafter before after &gt; delta

grep segments delta
    12445708 segments received
    12445730 segments send out
    1 segments retransmited
    0 bad segments received.</example>
      <para>The sums are left as an exercise to the reader :)</para>
      <para>Things become considerably more complicated if there are non-trvial packet losses and/or retransmissions.</para>
      <para>Of course all this checking is unnecessary if the test is a UDP_RR test because UDP &ldquo;never&rdquo; aggregates multiple sends into the same UDP datagram, and there are no ACKnowledgements in UDP.  The loss of a single request or response will not bring a &ldquo;burst&rdquo; UDP_RR test to a screeching halt, but it will reduce the number of transactions outstanding at any one time.  A &ldquo;burst&rdquo; UDP_RR test <b>will</b> come to a halt if the sum of the lost requests and responses reaches the value specified in the test-specific <option>-b</option> option.</para>
    </section>
  </node>
  <node>
    <nodename>Using --enable-demo</nodename>
    <nodeprev>Using --enable-burst</nodeprev>
    <nodeup>Using Netperf to Measure Aggregate Performance</nodeup>
    <section>
      <title>Using - -enable-demo</title>
      <para>One can</para>
      <example xml:space="preserve">configure --enable-demo</example>
      <para>and compile netperf to enable netperf to emit &ldquo;interim results&rdquo; at semi-regular intervals.  This enables a global <code>-D</code> option which takes a reporting interval as an argument.  With that specified, the output of netperf will then look something like</para>
      <example xml:space="preserve">$ src/netperf -D 1.25
MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain () port 0 AF_INET : demo
Interim result: 25425.52 10^6bits/s over 1.25 seconds ending at 1327962078.405
Interim result: 25486.82 10^6bits/s over 1.25 seconds ending at 1327962079.655
Interim result: 25474.96 10^6bits/s over 1.25 seconds ending at 1327962080.905
Interim result: 25523.49 10^6bits/s over 1.25 seconds ending at 1327962082.155
Interim result: 25053.57 10^6bits/s over 1.27 seconds ending at 1327962083.429
Interim result: 25349.64 10^6bits/s over 1.25 seconds ending at 1327962084.679
Interim result: 25292.84 10^6bits/s over 1.25 seconds ending at 1327962085.932
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

 87380  16384  16384    10.00    25375.66</example>
      <para>The units of the &ldquo;Interim result&rdquo; lines will follow the units selected via the global <code>-f</code> option.  If the test-specific <code>-o</code> option is specified on the command line, the format will be CSV:</para>
      <example xml:space="preserve">...
2978.81,MBytes/s,1.25,1327962298.035
...</example>
      <para>If the test-specific <code>-k</code> option is used the format will be keyval with each keyval being given an index:</para>
      <example xml:space="preserve">...
NETPERF_INTERIM_RESULT[2]=25.00
NETPERF_UNITS[2]=10^9bits/s
NETPERF_INTERVAL[2]=1.25
NETPERF_ENDING[2]=1327962357.249
...</example>
      <para>The expectation is it may be easier to utilize the keyvals if they have indices.</para>
      <para>But how does this help with aggregate tests?  Well, what one can do is start the netperfs via a script, giving each a Very Long (tm) run time.  Direct the output to a file per instance.  Then, once all the netperfs have been started, take a timestamp and wait for some desired test interval.  Once that interval expires take another timestamp and then start terminating the netperfs by sending them a SIGALRM signal via the likes of the <code>kill</code> or <code>pkill</code> command.  The netperfs will terminate and emit the rest of the &ldquo;usual&rdquo; output, and you can then bring the files to a central location for post processing to find the aggregate performance over the &ldquo;test interval.&rdquo;</para>
      <para>This method has the advantage that it does not require advance knowledge of how long it takes to get netperf tests started and/or stopped.  It does though require sufficiently synchronized clocks on all the test systems.</para>
      <para>While calls to get the current time can be inexpensive, that neither has nor is universally true.  For that reason netperf tries to minimize the number of such &ldquo;timestamping&rdquo; calls (eg <code>gettimeofday</code>) calls it makes when in demo mode.  Rather than take a timestamp after each <code>send</code> or <code>recv</code> call completes netperf tries to guess how many units of work will be performed over the desired interval.  Only once that many units of work have been completed will netperf check the time.  If the reporting interval has passed, netperf will emit an &ldquo;interim result.&rdquo;  If the interval has not passed, netperf will update its estimate for units and continue.</para>
      <para>After a bit of thought one can see that if things &ldquo;speed-up&rdquo; netperf will still honor the interval.  However, if things &ldquo;slow-down&rdquo; netperf may be late with an &ldquo;interim result.&rdquo;  Here is an example of both of those happening during a test - with the interval being honored while throughput increases, and then about half-way through when another netperf (not shown) is started we see things slowing down and netperf not hitting the interval as desired.</para>
      <example xml:space="preserve">$ src/netperf -D 2 -H tardy.hpl.hp.com -l 20
MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to tardy.hpl.hp.com () port 0 AF_INET : demo
Interim result:   36.46 10^6bits/s over 2.01 seconds ending at 1327963880.565
Interim result:   59.19 10^6bits/s over 2.00 seconds ending at 1327963882.569
Interim result:   73.39 10^6bits/s over 2.01 seconds ending at 1327963884.576
Interim result:   84.01 10^6bits/s over 2.03 seconds ending at 1327963886.603
Interim result:   75.63 10^6bits/s over 2.21 seconds ending at 1327963888.814
Interim result:   55.52 10^6bits/s over 2.72 seconds ending at 1327963891.538
Interim result:   70.94 10^6bits/s over 2.11 seconds ending at 1327963893.650
Interim result:   80.66 10^6bits/s over 2.13 seconds ending at 1327963895.777
Interim result:   86.42 10^6bits/s over 2.12 seconds ending at 1327963897.901
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

 87380  16384  16384    20.34      68.87</example>
      <para>So long as your post-processing mechanism can account for that, there should be no problem.  As time passes there may be changes to try to improve the netperf's honoring the interval but one should not ass-u-me it will always do so.  One should not assume the precision will remain fixed - future versions may change it - perhaps going beyond tenths of seconds in reporting the interval length etc.</para>
    </section>
  </node>
  <node>
    <nodename>Using Netperf to Measure Bidirectional Transfer</nodename>
    <nodenext>The Omni Tests</nodenext>
    <nodeprev>Using Netperf to Measure Aggregate Performance</nodeprev>
    <nodeup>Top</nodeup>
<!-- node-name,  next,  previous,  up -->
    <chapter>
      <title>Using Netperf to Measure Bidirectional Transfer</title>
      <para>There are two ways to use netperf to measure the performance of bidirectional transfer.  The first is to run concurrent netperf tests from the command line.  The second is to configure netperf with <code>--enable-burst</code> and use a single instance of the <xref><xrefnodename>TCP_RR</xrefnodename><xrefinfoname>TCP_RR</xrefinfoname></xref> test.</para>
      <para>While neither method is more &ldquo;correct&rdquo; than the other, each is doing so in different ways, and that has possible implications.  For instance, using the concurrent netperf test mechanism means that multiple TCP connections and multiple processes are involved, whereas using the single instance of TCP_RR there is only one TCP connection and one process on each end.  They may behave differently, especially on an MP system.</para>
      <menu>
        <menuentry>
          <menunode>Bidirectional Transfer with Concurrent Tests</menunode>
          <menutitle>Bidirectional Transfer with Concurrent Tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Bidirectional Transfer with TCP_RR</menunode>
          <menutitle>Bidirectional Transfer with TCP_RR</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Implications of Concurrent Tests vs Burst Request/Response</menunode>
          <menutitle>Implications of Concurrent Tests vs Burst Request/Response</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Bidirectional Transfer with Concurrent Tests</nodename>
    <nodenext>Bidirectional Transfer with TCP_RR</nodenext>
    <nodeprev>Using Netperf to Measure Bidirectional Transfer</nodeprev>
    <nodeup>Using Netperf to Measure Bidirectional Transfer</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Bidirectional Transfer with Concurrent Tests</title>
      <para>If we had two hosts Fred and Ethel, we could simply run a netperf <xref><xrefnodename>TCP_STREAM</xrefnodename><xrefinfoname>TCP_STREAM</xrefinfoname></xref> test on Fred pointing at Ethel, and a concurrent netperf TCP_STREAM test on Ethel pointing at Fred, but since there are no mechanisms to synchronize netperf tests and we would be starting tests from two different systems, there is a considerable risk of skew error.</para>
      <para>Far better would be to run simultaneous TCP_STREAM and <xref><xrefnodename>TCP_MAERTS</xrefnodename><xrefinfoname>TCP_MAERTS</xrefinfoname></xref> tests from just <b>one</b> system, using the concepts and procedures outlined in <xref><xrefnodename>Running Concurrent Netperf Tests</xrefnodename><xrefinfoname>Running Concurrent Netperf Tests</xrefinfoname></xref>. Here then is an example:</para>
      <example xml:space="preserve">for i in 1
do
 netperf -H 192.168.2.108 -t TCP_STREAM -B "outbound" -i 10 -P 0 -v 0 \
   -- -s 256K -S 256K &amp;
 netperf -H 192.168.2.108 -t TCP_MAERTS -B "inbound"  -i 10 -P 0 -v 0 \
   -- -s 256K -S 256K &amp;
done

 892.66 outbound
 891.34 inbound</example>
      <para>We have used a <code>for</code> loop in the shell with just one iteration because that will be <b>much</b> easier to get both tests started at more or less the same time than doing it by hand.  The global <option>-P</option> and <option>-v</option> options are used because we aren't interested in anything other than the throughput, and the global <option>-B</option> option is used to tag each output so we know which was inbound and which outbound relative to the system on which we were running netperf.  Of course that sense is switched on the system running netserver :)  The use of the global <option>-i</option> option is explained in <xref><xrefnodename>Running Concurrent Netperf Tests</xrefnodename><xrefinfoname>Running Concurrent Netperf Tests</xrefinfoname></xref>.</para>
      <para>Beginning with version 2.5.0 we can accomplish a similar result with the <xref><xrefnodename>The Omni Tests</xrefnodename><xrefinfoname>the omni tests</xrefinfoname></xref> and <xref><xrefnodename>Omni Output Selectors</xrefnodename><xrefinfoname>output selectors</xrefinfoname></xref>:</para>
      <example xml:space="preserve">for i in 1
do
  netperf -H 192.168.1.3 -t omni -l 10 -P 0 -- \
    -d stream -s 256K -S 256K -o throughput,direction &amp;
  netperf -H 192.168.1.3 -t omni -l 10 -P 0 -- \
    -d maerts -s 256K -S 256K -o throughput,direction &amp;
done

805.26,Receive
828.54,Send</example>
    </section>
  </node>
  <node>
    <nodename>Bidirectional Transfer with TCP_RR</nodename>
    <nodenext>Implications of Concurrent Tests vs Burst Request/Response</nodenext>
    <nodeprev>Bidirectional Transfer with Concurrent Tests</nodeprev>
    <nodeup>Using Netperf to Measure Bidirectional Transfer</nodeup>
<!-- node-name,  next,  previous,  up -->
    <section>
      <title>Bidirectional Transfer with TCP_RR</title>
      <para>Starting with version 2.5.0 the <code>--enable-burst</code> configure option defaults to <code>yes</code>, and starting some time before version 2.5.0 but after 2.4.0 the global <option>-f</option> option would affect the &ldquo;throughput&rdquo; reported by request/response tests.  If one uses the test-specific <option>-b</option> option to have several &ldquo;transactions&rdquo; in flight at one time and the test-specific <option>-r</option> option to increase their size, the test looks more and more like a single-connection bidirectional transfer than a simple request/response test.</para>
      <para>So, putting it all together one can do something like:</para>
      <example xml:space="preserve">netperf -f m -t TCP_RR -H 192.168.1.3 -v 2 -- -b 6 -r 32K -S 256K -S 256K
MIGRATED TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 192.168.1.3 (192.168.1.3) port 0 AF_INET : interval : first burst 6
Local /Remote
Socket Size   Request  Resp.   Elapsed
Send   Recv   Size     Size    Time     Throughput
bytes  Bytes  bytes    bytes   secs.    10^6bits/sec

16384  87380  32768    32768   10.00    1821.30
524288 524288
Alignment      Offset         RoundTrip  Trans    Throughput
Local  Remote  Local  Remote  Latency    Rate     10^6bits/s
Send   Recv    Send   Recv    usec/Tran  per sec  Outbound   Inbound
    8      0       0      0   2015.402   3473.252 910.492    910.492</example>
      <para>to get a bidirectional bulk-throughput result. As one can see, the -v 2 output will include a number of interesting, related values.</para>
      <quotation>
        <para><b>NOTE: The logic behind <code>--enable-burst</code> is very simple, and there are no calls to <code>poll()</code> or <code>select()</code> which means we want to make sure that the <code>send()</code> calls will never block, or we run the risk of deadlock with each side stuck trying to call <code>send()</code> and neither calling <code>recv()</code>.</b></para>
      </quotation>
      <para>Fortunately, this is easily accomplished by setting a &ldquo;large enough&rdquo; socket buffer size with the test-specific <option>-s</option> and <option>-S</option> options.  Presently this must be performed by the user.  Future versions of netperf might attempt to do this automagically, but there are some issues to be worked-out.</para>
    </section>
  </node>
  <node>
    <nodename>Implications of Concurrent Tests vs Burst Request/Response</nodename>
    <nodeprev>Bidirectional Transfer with TCP_RR</nodeprev>
    <nodeup>Using Netperf to Measure Bidirectional Transfer</nodeup>
    <section>
      <title>Implications of Concurrent Tests vs Burst Request/Response</title>
      <para>There are perhaps subtle but important differences between using concurrent unidirectional tests vs a burst-mode request to measure bidirectional performance.</para>
      <para>Broadly speaking, a single &ldquo;connection&rdquo; or &ldquo;flow&rdquo; of traffic cannot make use of the services of more than one or two CPUs at either end.  Whether one or two CPUs will be used processing a flow will depend on the specifics of the stack(s) involved and whether or not the global <option>-T</option> option has been used to bind netperf/netserver to specific CPUs.</para>
      <para>When using concurrent tests there will be two concurrent connections or flows, which means that upwards of four CPUs will be employed processing the packets (global <option>-T</option> used, no more than two if not), however, with just a single, bidirectional request/response test no more than two CPUs will be employed (only one if the global <option>-T</option> is not used).</para>
      <para>If there is a CPU bottleneck on either system this may result in rather different results between the two methods.</para>
      <para>Also, with a bidirectional request/response test there is something of a natural balance or synchronization between inbound and outbound - a response will not be sent until a request is received, and (once the burst level is reached) a subsequent request will not be sent until a response is received.  This may mask favoritism in the NIC between inbound and outbound processing.</para>
      <para>With two concurrent unidirectional tests there is no such synchronization or balance and any favoritism in the NIC may be exposed.</para>
    </section>
  </node>
  <node>
    <nodename>The Omni Tests</nodename>
    <nodenext>Other Netperf Tests</nodenext>
    <nodeprev>Using Netperf to Measure Bidirectional Transfer</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>The Omni Tests</title>
      <para>Beginning with version 2.5.0, netperf begins a migration to the <samp>omni</samp> tests or &ldquo;Two routines to measure them all.&rdquo;  The code for the omni tests can be found in <file>src/nettest_omni.c</file> and the goal is to make it easier for netperf to support multiple protocols and report a great many additional things about the systems under test. Additionally, a flexible output selection mechanism is present which allows the user to chose specifically what values she wishes to have reported and in what format.</para>
      <para>The omni tests are included by default in version 2.5.0.  To disable them, one must:</para>
      <example xml:space="preserve">./configure --enable-omni=no ...</example>
      <para>and remake netperf.  Remaking netserver is optional because even in 2.5.0 it has &ldquo;unmigrated&rdquo; netserver side routines for the classic (eg <file>src/nettest_bsd.c</file>) tests.</para>
      <menu>
        <menuentry>
          <menunode>Native Omni Tests</menunode>
          <menutitle>Native Omni Tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Migrated Tests</menunode>
          <menutitle>Migrated Tests</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>Omni Output Selection</menunode>
          <menutitle>Omni Output Selection</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>Native Omni Tests</nodename>
    <nodenext>Migrated Tests</nodenext>
    <nodeprev>The Omni Tests</nodeprev>
    <nodeup>The Omni Tests</nodeup>
    <section>
      <title>Native Omni Tests</title>
      <para>One access the omni tests &ldquo;natively&rdquo; by using a value of &ldquo;OMNI&rdquo; with the global <option>-t</option> test-selection option.  This will then cause netperf to use the code in <file>src/nettest_omni.c</file> and in particular the test-specific options parser for the omni tests.  The test-specific options for the omni tests are a superset of those for &ldquo;classic&rdquo; tests.  The options added by the omni tests are:</para>
      <table><indexterm index="vr">-c, Test-specific</indexterm>
        <tableitem>
          <tableterm><code>-c</code></tableterm>
          <item>
            <para>This explicitly declares that the test is to include connection establishment and tear-down as in either a TCP_CRR or TCP_CC test.</para>
            <para><indexterm index="vr">-d, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-d &lt;direction&gt;</code></tableterm>
          <item>
            <para>This option sets the direction of the test relative to the netperf process.  As of version 2.5.0 one can use the following in a case-insensitive manner:</para>
            <table>
              <tableitem>
                <tableterm><code>send, stream, transmit, xmit or 2</code></tableterm>
                <item>
                  <para>Any of which will cause netperf to send to the netserver.</para>
                </item>
              </tableitem>
              <tableitem>
                <tableterm><code>recv, receive, maerts or 4</code></tableterm>
                <item>
                  <para>Any of which will cause netserver to send to netperf.</para>
                </item>
              </tableitem>
              <tableitem>
                <tableterm><code>rr or 6</code></tableterm>
                <item>
                  <para>Either of which will cause a request/response test.</para>
                </item>
              </tableitem>
            </table>
            <para>Additionally, one can specify two directions separated by a '|' character and they will be OR'ed together.  In this way one can use the &rdquo;Send|Recv&rdquo; that will be emitted by the <xref><xrefnodename>Omni Output Selectors</xrefnodename><xrefinfoname>DIRECTION</xrefinfoname></xref> <xref><xrefnodename>Omni Output Selection</xrefnodename><xrefinfoname>output selector</xrefinfoname></xref> when used with a request/response test.</para>
            <para><indexterm index="vr">-k, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-k [<xref><xrefnodename>Omni Output Selection</xrefnodename><xrefinfoname>output selector</xrefinfoname></xref>]</code></tableterm>
          <item>
            <para>This option sets the style of output to &ldquo;keyval&rdquo; where each line of output has the form:</para>
            <example xml:space="preserve">key=value</example>
            <para>For example:</para>
            <example xml:space="preserve">$ netperf -t omni -- -d rr -k "THROUGHPUT,THROUGHPUT_UNITS"
OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
THROUGHPUT=59092.65
THROUGHPUT_UNITS=Trans/s</example>
            <para>Using the <option>-k</option> option will override any previous, test-specific <option>-o</option> or <option>-O</option> option.</para>
            <para><indexterm index="vr">-o, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-o [<xref><xrefnodename>Omni Output Selection</xrefnodename><xrefinfoname>output selector</xrefinfoname></xref>]</code></tableterm>
          <item>
            <para>This option sets the style of output to &ldquo;CSV&rdquo; where there will be one line of comma-separated values, preceded by one line of column names unless the global <option>-P</option> option is used with a value of 0:</para>
            <example xml:space="preserve">$ netperf -t omni -- -d rr -o "THROUGHPUT,THROUGHPUT_UNITS"
OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
Throughput,Throughput Units
60999.07,Trans/s</example>
            <para>Using the <option>-o</option> option will override any previous, test-specific <option>-k</option> or <option>-O</option> option.</para>
            <para><indexterm index="vr">-O, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-O [<xref><xrefnodename>Omni Output Selection</xrefnodename><xrefinfoname>output selector</xrefinfoname></xref>]</code></tableterm>
          <item>
            <para>This option sets the style of output to &ldquo;human readable&rdquo; which will look quite similar to classic netperf output:</para>
            <example xml:space="preserve">$ netperf -t omni -- -d rr -O "THROUGHPUT,THROUGHPUT_UNITS"
OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
Throughput Throughput
           Units


60492.57   Trans/s</example>
            <para>Using the <option>-O</option> option will override any previous, test-specific <option>-k</option> or <option>-o</option> option.</para>
            <para><indexterm index="vr">-t, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-t</code></tableterm>
          <item>
            <para>This option explicitly sets the socket type for the test's data connection. As of version 2.5.0 the known socket types include &ldquo;stream&rdquo; and &ldquo;dgram&rdquo; for SOCK_STREAM and SOCK_DGRAM respectively.</para>
            <para><indexterm index="vr">-T, Test-specific</indexterm></para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-T &lt;protocol&gt;</code></tableterm>
          <item>
            <para>This option is used to explicitly set the protocol used for the test. It is case-insensitive. As of version 2.5.0 the protocols known to netperf include:</para>
            <table>
              <tableitem>
                <tableterm><code>TCP</code></tableterm>
                <item>
                  <para>Select the Transmission Control Protocol</para>
                </item>
              </tableitem>
              <tableitem>
                <tableterm><code>UDP</code></tableterm>
                <item>
                  <para>Select the User Datagram Protocol</para>
                </item>
              </tableitem>
              <tableitem>
                <tableterm><code>SDP</code></tableterm>
                <item>
                  <para>Select the Sockets Direct Protocol</para>
                </item>
              </tableitem>
              <tableitem>
                <tableterm><code>DCCP</code></tableterm>
                <item>
                  <para>Select the Datagram Congestion Control Protocol</para>
                </item>
              </tableitem>
              <tableitem>
                <tableterm><code>SCTP</code></tableterm>
                <item>
                  <para>Select the Stream Control Transport Protocol</para>
                </item>
              </tableitem>
              <tableitem>
                <tableterm><code>udplite</code></tableterm>
                <item>
                  <para>Select UDP Lite</para>
                </item>
              </tableitem>
            </table>
            <para>The default is implicit based on other settings.</para>
          </item>
        </tableitem>
      </table>
      <para>The omni tests also extend the interpretation of some of the classic, test-specific options for the BSD Sockets tests:</para>
      <table>
        <tableitem>
          <tableterm><code>-m &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>This can set the send size for either or both of the netperf and netserver sides of the test:</para>
            <example xml:space="preserve">-m 32K</example>
            <para>sets only the netperf-side send size to 32768 bytes, and or's-in transmit for the direction. This is effectively the same behaviour as for the classic tests.</para>
            <example xml:space="preserve">-m ,32K</example>
            <para>sets only the netserver side send size to 32768 bytes and or's-in receive for the direction.</para>
            <example xml:space="preserve">-m 16K,32K
sets the netperf side send size to 16284 bytes, the netserver side
send size to 32768 bytes and the direction will be "Send|Recv."</example>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>-M &lt;optionspec&gt;</code></tableterm>
          <item>
            <para>This can set the receive size for either or both of the netperf and netserver sides of the test:</para>
            <example xml:space="preserve">-M 32K</example>
            <para>sets only the netserver side receive size to 32768 bytes and or's-in send for the test direction.</para>
            <example xml:space="preserve">-M ,32K</example>
            <para>sets only the netperf side receive size to 32768 bytes and or's-in receive for the test direction.</para>
            <example xml:space="preserve">-M 16K,32K</example>
            <para>sets the netserver side receive size to 16384 bytes and the netperf side receive size to 32768 bytes and the direction will be "Send|Recv."</para>
          </item>
        </tableitem>
      </table>
    </section>
  </node>
  <node>
    <nodename>Migrated Tests</nodename>
    <nodenext>Omni Output Selection</nodenext>
    <nodeprev>Native Omni Tests</nodeprev>
    <nodeup>The Omni Tests</nodeup>
    <section>
      <title>Migrated Tests</title>
      <para>As of version 2.5.0 several tests have been migrated to use the omni code in <file>src/nettest_omni.c</file> for the core of their testing.  A migrated test retains all its previous output code and so should still &ldquo;look and feel&rdquo; just like a pre-2.5.0 test with one exception - the first line of the test banners will include the word &ldquo;MIGRATED&rdquo; at the beginning as in:</para>
      <example xml:space="preserve">$ netperf
MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
Recv   Send    Send
Socket Socket  Message  Elapsed
Size   Size    Size     Time     Throughput
bytes  bytes   bytes    secs.    10^6bits/sec

 87380  16384  16384    10.00    27175.27</example>
      <para>The tests migrated in version 2.5.0 are:</para>
      <itemize>
        <itemfunction>&bullet;</itemfunction>
        <item>
          <para>TCP_STREAM</para>
        </item>
        <item>
          <para>TCP_MAERTS</para>
        </item>
        <item>
          <para>TCP_RR</para>
        </item>
        <item>
          <para>TCP_CRR</para>
        </item>
        <item>
          <para>UDP_STREAM</para>
        </item>
        <item>
          <para>UDP_RR</para>
        </item>
      </itemize>
      <para>It is expected that future releases will have additional tests migrated to use the &ldquo;omni&rdquo; functionality.</para>
      <para>If one uses &ldquo;omni-specific&rdquo; test-specific options in conjunction with a migrated test, instead of using the classic output code, the new omni output code will be used. For example if one uses the <option>-k</option> test-specific option with a value of &ldquo;MIN_LATENCY,MAX_LATENCY&rdquo; with a migrated TCP_RR test one will see:</para>
      <example xml:space="preserve">$ netperf -t tcp_rr -- -k THROUGHPUT,THROUGHPUT_UNITS
MIGRATED TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
THROUGHPUT=60074.74
THROUGHPUT_UNITS=Trans/s</example>
      <para>rather than:</para>
      <example xml:space="preserve">$ netperf -t tcp_rr
MIGRATED TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
Local /Remote
Socket Size   Request  Resp.   Elapsed  Trans.
Send   Recv   Size     Size    Time     Rate
bytes  Bytes  bytes    bytes   secs.    per sec

16384  87380  1        1       10.00    59421.52
16384  87380</example>
    </section>
  </node>
  <node>
    <nodename>Omni Output Selection</nodename>
    <nodeprev>Migrated Tests</nodeprev>
    <nodeup>The Omni Tests</nodeup>
    <section>
      <title>Omni Output Selection</title>
      <para>The omni test-specific <option>-k</option>, <option>-o</option> and <option>-O</option> options take an optional <code>output selector</code> by which the user can configure what values are reported.  The output selector can take several forms:</para>
      <table>
        <tableitem>
          <tableterm><code><file>filename</file></code></tableterm>
          <item>
            <para>The output selections will be read from the named file. Within the file there can be up to four lines of comma-separated output selectors. This controls how many multi-line blocks of output are emitted when the <option>-O</option> option is used.  This output, while not identical to &ldquo;classic&rdquo; netperf output, is inspired by it.  Multiple lines have no effect for <option>-k</option> and <option>-o</option> options.  Putting output selections in a file can be useful when the list of selections is long.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>comma and/or semi-colon-separated list</code></tableterm>
          <item>
            <para>The output selections will be parsed from a comma and/or semi-colon-separated list of output selectors. When the list is given to a <option>-O</option> option a semi-colon specifies a new output block should be started.  Semi-colons have the same meaning as commas when used with the <option>-k</option> or <option>-o</option> options.  Depending on the command interpreter being used, the semi-colon may have to be escaped somehow to keep it from being interpreted by the command interpreter. This can often be done by enclosing the entire list in quotes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>all</code></tableterm>
          <item>
            <para>If the keyword <b>all</b> is specified it means that all known output values should be displayed at the end of the test.  This can be a great deal of output.  As of version 2.5.0 there are 157 different output selectors.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>?</code></tableterm>
          <item>
            <para>If a &ldquo;?&rdquo; is given as the output selection, the list of all known output selectors will be displayed and no test actually run.  When passed to the <option>-O</option> option they will be listed one per line. Otherwise they will be listed as a comma-separated list.  It may be necessary to protect the &ldquo;?&rdquo; from the command interpreter by escaping it or enclosing it in quotes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>no selector</code></tableterm>
          <item>
            <para>If nothing is given to the <option>-k</option>, <option>-o</option> or <option>-O</option> option then the code selects a default set of output selectors inspired by classic netperf output. The format will be the <samp>human readable</samp> format emitted by the test-specific <option>-O</option> option.</para>
          </item>
        </tableitem>
      </table>
      <para>The order of evaluation will first check for an output selection.  If none is specified with the <option>-k</option>, <option>-o</option> or <option>-O</option> option netperf will select a default based on the characteristics of the test.  If there is an output selection, the code will first check for <samp>?</samp>, then check to see if it is the magic <samp>all</samp> keyword. After that it will check for either <samp>,</samp> or <samp>;</samp> in the selection and take that to mean it is a comma and/or semi-colon-separated list. If none of those checks match, netperf will then assume the output specification is a filename and attempt to open and parse the file.</para>
      <menu>
        <menuentry>
          <menunode>Omni Output Selectors</menunode>
          <menutitle>Omni Output Selectors</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </section>
  </node>
  <node>
    <nodename>Omni Output Selectors</nodename>
    <nodeprev>Omni Output Selection</nodeprev>
    <nodeup>Omni Output Selection</nodeup>
    <subsection>
      <title>Omni Output Selectors</title>
      <para>As of version 2.5.0 the output selectors are:</para>
      <table>
        <tableitem>
          <tableterm><code>OUTPUT_NONE</code></tableterm>
          <item>
            <para>This is essentially a null output.  For <option>-k</option> output it will simply add a line that reads &ldquo;OUTPUT_NONE=&rdquo; to the output. For <option>-o</option> it will cause an empty &ldquo;column&rdquo; to be included. For <option>-O</option> output it will cause extra spaces to separate &ldquo;real&rdquo; output.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>SOCKET_TYPE</code></tableterm>
          <item>
            <para>This will cause the socket type (eg SOCK_STREAM, SOCK_DGRAM) for the data connection to be output.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>PROTOCOL</code></tableterm>
          <item>
            <para>This will cause the protocol used for the data connection to be displayed.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>DIRECTION</code></tableterm>
          <item>
            <para>This will display the data flow direction relative to the netperf process. Units: Send or Recv for a unidirectional bulk-transfer test, or Send|Recv for a request/response test.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>ELAPSED_TIME</code></tableterm>
          <item>
            <para>This will display the elapsed time in seconds for the test.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>THROUGHPUT</code></tableterm>
          <item>
            <para>This will display the throughput for the test. Units: As requested via the global <option>-f</option> option and displayed by the THROUGHPUT_UNITS output selector.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>THROUGHPUT_UNITS</code></tableterm>
          <item>
            <para>This will display the units for what is displayed by the <code>THROUGHPUT</code> output selector.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LSS_SIZE_REQ</code></tableterm>
          <item>
            <para>This will display the local (netperf) send socket buffer size (aka SO_SNDBUF) requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LSS_SIZE</code></tableterm>
          <item>
            <para>This will display the local (netperf) send socket buffer size (SO_SNDBUF) immediately after the data connection socket was created. Peculiarities of different networking stacks may lead to this differing from the size requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LSS_SIZE_END</code></tableterm>
          <item>
            <para>This will display the local (netperf) send socket buffer size (SO_SNDBUF) immediately before the data connection socket is closed. Peculiarities of different networking stacks may lead this to differ from the size requested via the command line and/or the size immediately after the data connection socket was created. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LSR_SIZE_REQ</code></tableterm>
          <item>
            <para>This will display the local (netperf) receive socket buffer size (aka SO_RCVBUF) requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LSR_SIZE</code></tableterm>
          <item>
            <para>This will display the local (netperf) receive socket buffer size (SO_RCVBUF) immediately after the data connection socket was created. Peculiarities of different networking stacks may lead to this differing from the size requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LSR_SIZE_END</code></tableterm>
          <item>
            <para>This will display the local (netperf) receive socket buffer size (SO_RCVBUF) immediately before the data connection socket is closed. Peculiarities of different networking stacks may lead this to differ from the size requested via the command line and/or the size immediately after the data connection socket was created. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RSS_SIZE_REQ</code></tableterm>
          <item>
            <para>This will display the remote (netserver) send socket buffer size (aka SO_SNDBUF) requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RSS_SIZE</code></tableterm>
          <item>
            <para>This will display the remote (netserver) send socket buffer size (SO_SNDBUF) immediately after the data connection socket was created. Peculiarities of different networking stacks may lead to this differing from the size requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RSS_SIZE_END</code></tableterm>
          <item>
            <para>This will display the remote (netserver) send socket buffer size (SO_SNDBUF) immediately before the data connection socket is closed. Peculiarities of different networking stacks may lead this to differ from the size requested via the command line and/or the size immediately after the data connection socket was created. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RSR_SIZE_REQ</code></tableterm>
          <item>
            <para>This will display the remote (netserver) receive socket buffer size (aka SO_RCVBUF) requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RSR_SIZE</code></tableterm>
          <item>
            <para>This will display the remote (netserver) receive socket buffer size (SO_RCVBUF) immediately after the data connection socket was created. Peculiarities of different networking stacks may lead to this differing from the size requested via the command line. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RSR_SIZE_END</code></tableterm>
          <item>
            <para>This will display the remote (netserver) receive socket buffer size (SO_RCVBUF) immediately before the data connection socket is closed. Peculiarities of different networking stacks may lead this to differ from the size requested via the command line and/or the size immediately after the data connection socket was created. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SEND_SIZE</code></tableterm>
          <item>
            <para>This will display the size of the buffers netperf passed in any &ldquo;send&rdquo; calls it made on the data connection for a non-request/response test. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_SIZE</code></tableterm>
          <item>
            <para>This will display the size of the buffers netperf passed in any &ldquo;receive&rdquo; calls it made on the data connection for a non-request/response test. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_SEND_SIZE</code></tableterm>
          <item>
            <para>This will display the size of the buffers netserver passed in any &ldquo;send&rdquo; calls it made on the data connection for a non-request/response test. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_RECV_SIZE</code></tableterm>
          <item>
            <para>This will display the size of the buffers netserver passed in any &ldquo;receive&rdquo; calls it made on the data connection for a non-request/response test. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REQUEST_SIZE</code></tableterm>
          <item>
            <para>This will display the size of the requests netperf sent in a request-response test. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RESPONSE_SIZE</code></tableterm>
          <item>
            <para>This will display the size of the responses netserver sent in a request-response test. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_UTIL</code></tableterm>
          <item>
            <para>This will display the overall CPU utilization during the test as measured by netperf. Units: 0 to 100 percent.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_METHOD</code></tableterm>
          <item>
            <para>This will display the method used by netperf to measure CPU utilization. Units: single character denoting method.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SD</code></tableterm>
          <item>
            <para>This will display the service demand, or units of CPU consumed per unit of work, as measured by netperf. Units: microseconds of CPU consumed per either KB (K==1024) of data transferred or request/response transaction.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_UTIL</code></tableterm>
          <item>
            <para>This will display the overall CPU utilization during the test as measured by netserver. Units 0 to 100 percent.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_METHOD</code></tableterm>
          <item>
            <para>This will display the method used by netserver to measure CPU utilization. Units: single character denoting method.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_SD</code></tableterm>
          <item>
            <para>This will display the service demand, or units of CPU consumed per unit of work, as measured by netserver. Units: microseconds of CPU consumed per either KB (K==1024) of data transferred or request/response transaction.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>SD_UNITS</code></tableterm>
          <item>
            <para>This will display the units for LOCAL_SD and REMOTE_SD</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>CONFIDENCE_LEVEL</code></tableterm>
          <item>
            <para>This will display the confidence level requested by the user either explicitly via the global <option>-I</option> option, or implicitly via the global <option>-i</option> option.  The value will be either 95 or 99 if confidence intervals have been requested or 0 if they were not. Units: Percent</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>CONFIDENCE_INTERVAL</code></tableterm>
          <item>
            <para>This will display the width of the confidence interval requested either explicitly via the global <option>-I</option> option or implicitly via the global <option>-i</option> option.  Units: Width in percent of mean value computed. A value of -1.0 means that confidence intervals were not requested.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>CONFIDENCE_ITERATION</code></tableterm>
          <item>
            <para>This will display the number of test iterations netperf undertook, perhaps while attempting to achieve the requested confidence interval and level. If confidence intervals were requested via the command line then the value will be between 3 and 30.  If confidence intervals were not requested the value will be 1.  Units: Iterations</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>THROUGHPUT_CONFID</code></tableterm>
          <item>
            <para>This will display the width of the confidence interval actually achieved for <code>THROUGHPUT</code> during the test.  Units: Width of interval as percentage of reported throughput value.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_CONFID</code></tableterm>
          <item>
            <para>This will display the width of the confidence interval actually achieved for overall CPU utilization on the system running netperf (<code>LOCAL_CPU_UTIL</code>) during the test, if CPU utilization measurement was enabled.  Units: Width of interval as percentage of reported CPU utilization.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_CONFID</code></tableterm>
          <item>
            <para>This will display the width of the confidence interval actually achieved for overall CPU utilization on the system running netserver (<code>REMOTE_CPU_UTIL</code>) during the test, if CPU utilization measurement was enabled. Units: Width of interval as percentage of reported CPU utilization.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>TRANSACTION_RATE</code></tableterm>
          <item>
            <para>This will display the transaction rate in transactions per second for a request/response test even if the user has requested a throughput in units of bits or bytes per second via the global <option>-f</option> option. It is undefined for a non-request/response test. Units: Transactions per second.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RT_LATENCY</code></tableterm>
          <item>
            <para>This will display the average round-trip latency for a request/response test, accounting for number of transactions in flight at one time. It is undefined for a non-request/response test. Units: Microseconds per transaction</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>BURST_SIZE</code></tableterm>
          <item>
            <para>This will display the &ldquo;burst size&rdquo; or added transactions in flight in a request/response test as requested via a test-specific <option>-b</option> option.  The number of transactions in flight at one time will be one greater than this value.  It is undefined for a non-request/response test. Units: added Transactions in flight.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_TRANSPORT_RETRANS</code></tableterm>
          <item>
            <para>This will display the number of retransmissions experienced on the data connection during the test as determined by netperf.  A value of -1 means the attempt to determine the number of retransmissions failed or the concept was not valid for the given protocol or the mechanism is not known for the platform. A value of -2 means it was not attempted. As of version 2.5.0 the meaning of values are in flux and subject to change.  Units: number of retransmissions.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_TRANSPORT_RETRANS</code></tableterm>
          <item>
            <para>This will display the number of retransmissions experienced on the data connection during the test as determined by netserver.  A value of -1 means the attempt to determine the number of retransmissions failed or the concept was not valid for the given protocol or the mechanism is not known for the platform. A value of -2 means it was not attempted. As of version 2.5.0 the meaning of values are in flux and subject to change.  Units: number of retransmissions.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>TRANSPORT_MSS</code></tableterm>
          <item>
            <para>This will display the Maximum Segment Size (aka MSS) or its equivalent for the protocol being used during the test.  A value of -1 means either the concept of an MSS did not apply to the protocol being used, or there was an error in retrieving it. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SEND_THROUGHPUT</code></tableterm>
          <item>
            <para>The throughput as measured by netperf for the successful &ldquo;send&rdquo; calls it made on the data connection. Units: as requested via the global <option>-f</option> option and displayed via the <code>THROUGHPUT_UNITS</code> output selector.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_THROUGHPUT</code></tableterm>
          <item>
            <para>The throughput as measured by netperf for the successful &ldquo;receive&rdquo; calls it made on the data connection. Units: as requested via the global <option>-f</option> option and displayed via the <code>THROUGHPUT_UNITS</code> output selector.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_SEND_THROUGHPUT</code></tableterm>
          <item>
            <para>The throughput as measured by netserver for the successful &ldquo;send&rdquo; calls it made on the data connection. Units: as requested via the global <option>-f</option> option and displayed via the <code>THROUGHPUT_UNITS</code> output selector.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_RECV_THROUGHPUT</code></tableterm>
          <item>
            <para>The throughput as measured by netserver for the successful &ldquo;receive&rdquo; calls it made on the data connection. Units: as requested via the global <option>-f</option> option and displayed via the <code>THROUGHPUT_UNITS</code> output selector.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_BIND</code></tableterm>
          <item>
            <para>The CPU to which netperf was bound, if at all, during the test. A value of -1 means that netperf was not explicitly bound to a CPU during the test. Units: CPU ID</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_COUNT</code></tableterm>
          <item>
            <para>The number of CPUs (cores, threads) detected by netperf. Units: CPU count.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_PEAK_UTIL</code></tableterm>
          <item>
            <para>The utilization of the CPU most heavily utilized during the test, as measured by netperf. This can be used to see if any one CPU of a multi-CPU system was saturated even though the overall CPU utilization as reported by <code>LOCAL_CPU_UTIL</code> was low. Units: 0 to 100%</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_PEAK_ID</code></tableterm>
          <item>
            <para>The id of the CPU most heavily utilized during the test as determined by netperf. Units: CPU ID.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_MODEL</code></tableterm>
          <item>
            <para>Model information for the processor(s) present on the system running netperf. Assumes all processors in the system (as perceived by netperf) on which netperf is running are the same model. Units: Text</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CPU_FREQUENCY</code></tableterm>
          <item>
            <para>The frequency of the processor(s) on the system running netperf, at the time netperf made the call.  Assumes that all processors present in the system running netperf are running at the same frequency. Units: MHz</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_BIND</code></tableterm>
          <item>
            <para>The CPU to which netserver was bound, if at all, during the test. A value of -1 means that netperf was not explicitly bound to a CPU during the test. Units: CPU ID</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_COUNT</code></tableterm>
          <item>
            <para>The number of CPUs (cores, threads) detected by netserver. Units: CPU count.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_PEAK_UTIL</code></tableterm>
          <item>
            <para>The utilization of the CPU most heavily utilized during the test, as measured by netserver. This can be used to see if any one CPU of a multi-CPU system was saturated even though the overall CPU utilization as reported by <code>REMOTE_CPU_UTIL</code> was low. Units: 0 to 100%</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_PEAK_ID</code></tableterm>
          <item>
            <para>The id of the CPU most heavily utilized during the test as determined by netserver. Units: CPU ID.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_MODEL</code></tableterm>
          <item>
            <para>Model information for the processor(s) present on the system running netserver. Assumes all processors in the system (as perceived by netserver) on which netserver is running are the same model. Units: Text</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_CPU_FREQUENCY</code></tableterm>
          <item>
            <para>The frequency of the processor(s) on the system running netserver, at the time netserver made the call.  Assumes that all processors present in the system running netserver are running at the same frequency. Units: MHz</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>SOURCE_PORT</code></tableterm>
          <item>
            <para>The port ID/service name to which the data socket created by netperf was bound.  A value of 0 means the data socket was not explicitly bound to a port number. Units: ASCII text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>SOURCE_ADDR</code></tableterm>
          <item>
            <para>The name/address to which the data socket created by netperf was bound. A value of 0.0.0.0 means the data socket was not explicitly bound to an address. Units: ASCII text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>SOURCE_FAMILY</code></tableterm>
          <item>
            <para>The address family to which the data socket created by netperf was bound.  A value of 0 means the data socket was not explicitly bound to a given address family. Units: ASCII text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>DEST_PORT</code></tableterm>
          <item>
            <para>The port ID to which the data socket created by netserver was bound. A value of 0 means the data socket was not explicitly bound to a port number.  Units: ASCII text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>DEST_ADDR</code></tableterm>
          <item>
            <para>The name/address of the data socket created by netserver.  Units: ASCII text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>DEST_FAMILY</code></tableterm>
          <item>
            <para>The address family to which the data socket created by netserver was bound. A value of 0 means the data socket was not explicitly bound to a given address family. Units: ASCII text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SEND_CALLS</code></tableterm>
          <item>
            <para>The number of successful &ldquo;send&rdquo; calls made by netperf against its data socket. Units: Calls.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_CALLS</code></tableterm>
          <item>
            <para>The number of successful &ldquo;receive&rdquo; calls made by netperf against its data socket. Units: Calls.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_BYTES_PER_RECV</code></tableterm>
          <item>
            <para>The average number of bytes per &ldquo;receive&rdquo; call made by netperf against its data socket. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_BYTES_PER_SEND</code></tableterm>
          <item>
            <para>The average number of bytes per &ldquo;send&rdquo; call made by netperf against its data socket. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_BYTES_SENT</code></tableterm>
          <item>
            <para>The number of bytes successfully sent by netperf through its data socket. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_BYTES_RECVD</code></tableterm>
          <item>
            <para>The number of bytes successfully received by netperf through its data socket. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_BYTES_XFERD</code></tableterm>
          <item>
            <para>The sum of bytes sent and received by netperf through its data socket. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SEND_OFFSET</code></tableterm>
          <item>
            <para>The offset from the alignment of the buffers passed by netperf in its &ldquo;send&rdquo; calls. Specified via the global <option>-o</option> option and defaults to 0. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_OFFSET</code></tableterm>
          <item>
            <para>The offset from the alignment of the buffers passed by netperf in its &ldquo;receive&rdquo; calls. Specified via the global <option>-o</option> option and defaults to 0. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SEND_ALIGN</code></tableterm>
          <item>
            <para>The alignment of the buffers passed by netperf in its &ldquo;send&rdquo; calls as specified via the global <option>-a</option> option. Defaults to 8. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_ALIGN</code></tableterm>
          <item>
            <para>The alignment of the buffers passed by netperf in its &ldquo;receive&rdquo; calls as specified via the global <option>-a</option> option. Defaults to 8. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SEND_WIDTH</code></tableterm>
          <item>
            <para>The &ldquo;width&rdquo; of the ring of buffers through which netperf cycles as it makes its &ldquo;send&rdquo; calls.  Defaults to one more than the local send socket buffer size divided by the send size as determined at the time the data socket is created. Can be used to make netperf more processor data cache unfriendly. Units: number of buffers.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_WIDTH</code></tableterm>
          <item>
            <para>The &ldquo;width&rdquo; of the ring of buffers through which netperf cycles as it makes its &ldquo;receive&rdquo; calls.  Defaults to one more than the local receive socket buffer size divided by the receive size as determined at the time the data socket is created. Can be used to make netperf more processor data cache unfriendly. Units: number of buffers.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SEND_DIRTY_COUNT</code></tableterm>
          <item>
            <para>The number of bytes to &ldquo;dirty&rdquo; (write to) before netperf makes a &ldquo;send&rdquo; call. Specified via the global <option>-k</option> option, which requires that &ndash;enable-dirty=yes was specified with the configure command prior to building netperf. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_DIRTY_COUNT</code></tableterm>
          <item>
            <para>The number of bytes to &ldquo;dirty&rdquo; (write to) before netperf makes a &ldquo;recv&rdquo; call. Specified via the global <option>-k</option> option which requires that &ndash;enable-dirty was specified with the configure command prior to building netperf. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RECV_CLEAN_COUNT</code></tableterm>
          <item>
            <para>The number of bytes netperf should read &ldquo;cleanly&rdquo; before making a &ldquo;receive&rdquo; call. Specified via the global <option>-k</option> option which requires that &ndash;enable-dirty was specified with configure command prior to building netperf.  Clean reads start were dirty writes ended. Units: Bytes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_NODELAY</code></tableterm>
          <item>
            <para>Indicates whether or not setting the test protocol-specific &ldquo;no delay&rdquo; (eg TCP_NODELAY) option on the data socket used by netperf was requested by the test-specific <option>-D</option> option and successful. Units: 0 means no, 1 means yes.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_CORK</code></tableterm>
          <item>
            <para>Indicates whether or not TCP_CORK was set on the data socket used by netperf as requested via the test-specific <option>-C</option> option. 1 means yes, 0 means no/not applicable.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_SEND_CALLS</code></tableterm>
          <tableterm><code>REMOTE_RECV_CALLS</code></tableterm>
          <tableterm><code>REMOTE_BYTES_PER_RECV</code></tableterm>
          <tableterm><code>REMOTE_BYTES_PER_SEND</code></tableterm>
          <tableterm><code>REMOTE_BYTES_SENT</code></tableterm>
          <tableterm><code>REMOTE_BYTES_RECVD</code></tableterm>
          <tableterm><code>REMOTE_BYTES_XFERD</code></tableterm>
          <tableterm><code>REMOTE_SEND_OFFSET</code></tableterm>
          <tableterm><code>REMOTE_RECV_OFFSET</code></tableterm>
          <tableterm><code>REMOTE_SEND_ALIGN</code></tableterm>
          <tableterm><code>REMOTE_RECV_ALIGN</code></tableterm>
          <tableterm><code>REMOTE_SEND_WIDTH</code></tableterm>
          <tableterm><code>REMOTE_RECV_WIDTH</code></tableterm>
          <tableterm><code>REMOTE_SEND_DIRTY_COUNT</code></tableterm>
          <tableterm><code>REMOTE_RECV_DIRTY_COUNT</code></tableterm>
          <tableterm><code>REMOTE_RECV_CLEAN_COUNT</code></tableterm>
          <tableterm><code>REMOTE_NODELAY</code></tableterm>
          <tableterm><code>REMOTE_CORK</code></tableterm>
          <item>
            <para>These are all like their &ldquo;LOCAL_&rdquo; counterparts only for the netserver rather than netperf.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SYSNAME</code></tableterm>
          <item>
            <para>The name of the OS (eg &ldquo;Linux&rdquo;) running on the system on which netperf was running. Units: ASCII Text</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SYSTEM_MODEL</code></tableterm>
          <item>
            <para>The model name of the system on which netperf was running. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_RELEASE</code></tableterm>
          <item>
            <para>The release name/number of the OS running on the system on which netperf  was running. Units: ASCII Text</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_VERSION</code></tableterm>
          <item>
            <para>The version number of the OS running on the system on which netperf was running. Units: ASCII Text</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_MACHINE</code></tableterm>
          <item>
            <para>The machine architecture of the machine on which netperf was running. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_SYSNAME</code></tableterm>
          <tableterm><code>REMOTE_SYSTEM_MODEL</code></tableterm>
          <tableterm><code>REMOTE_RELEASE</code></tableterm>
          <tableterm><code>REMOTE_VERSION</code></tableterm>
          <tableterm><code>REMOTE_MACHINE</code></tableterm>
          <item>
            <para>These are all like their &ldquo;LOCAL_&rdquo; counterparts only for the netserver rather than netperf.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERFACE_NAME</code></tableterm>
          <item>
            <para>The name of the probable egress interface through which the data connection went on the system running netperf. Example: eth0. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERFACE_VENDOR</code></tableterm>
          <item>
            <para>The vendor ID of the probable egress interface through which traffic on the data connection went on the system running netperf. Units: Hexadecimal IDs as might be found in a <file>pci.ids</file> file or at <uref><urefurl>http://pciids.sourceforge.net/</urefurl><urefdesc>the PCI ID Repository</urefdesc></uref>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERFACE_DEVICE</code></tableterm>
          <item>
            <para>The device ID of the probable egress interface through which traffic on the data connection went on the system running netperf. Units: Hexadecimal IDs as might be found in a <file>pci.ids</file> file or at <uref><urefurl>http://pciids.sourceforge.net/</urefurl><urefdesc>the PCI ID Repository</urefdesc></uref>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERFACE_SUBVENDOR</code></tableterm>
          <item>
            <para>The sub-vendor ID of the probable egress interface through which traffic on the data connection went on the system running netperf. Units: Hexadecimal IDs as might be found in a <file>pci.ids</file> file or at <uref><urefurl>http://pciids.sourceforge.net/</urefurl><urefdesc>the PCI ID Repository</urefdesc></uref>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERFACE_SUBDEVICE</code></tableterm>
          <item>
            <para>The sub-device ID of the probable egress interface through which traffic on the data connection went on the system running netperf. Units: Hexadecimal IDs as might be found in a <file>pci.ids</file> file or at <uref><urefurl>http://pciids.sourceforge.net/</urefurl><urefdesc>the PCI ID Repository</urefdesc></uref>.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_DRIVER_NAME</code></tableterm>
          <item>
            <para>The name of the driver used for the probable egress interface through which traffic on the data connection went on the system running netperf. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_DRIVER_VERSION</code></tableterm>
          <item>
            <para>The version string for the driver used for the probable egress interface through which traffic on the data connection went on the system running netperf. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_DRIVER_FIRMWARE</code></tableterm>
          <item>
            <para>The firmware version for the driver used for the probable egress interface through which traffic on the data connection went on the system running netperf. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_DRIVER_BUS</code></tableterm>
          <item>
            <para>The bus address of the probable egress interface through which traffic on the data connection went on the system running netperf. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERFACE_SLOT</code></tableterm>
          <item>
            <para>The slot ID of the probable egress interface through which traffic on the data connection went on the system running netperf. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_INTERFACE_NAME</code></tableterm>
          <tableterm><code>REMOTE_INTERFACE_VENDOR</code></tableterm>
          <tableterm><code>REMOTE_INTERFACE_DEVICE</code></tableterm>
          <tableterm><code>REMOTE_INTERFACE_SUBVENDOR</code></tableterm>
          <tableterm><code>REMOTE_INTERFACE_SUBDEVICE</code></tableterm>
          <tableterm><code>REMOTE_DRIVER_NAME</code></tableterm>
          <tableterm><code>REMOTE_DRIVER_VERSION</code></tableterm>
          <tableterm><code>REMOTE_DRIVER_FIRMWARE</code></tableterm>
          <tableterm><code>REMOTE_DRIVER_BUS</code></tableterm>
          <tableterm><code>REMOTE_INTERFACE_SLOT</code></tableterm>
          <item>
            <para>These are all like their &ldquo;LOCAL_&rdquo; counterparts only for the netserver rather than netperf.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERVAL_USECS</code></tableterm>
          <item>
            <para>The interval at which bursts of operations (sends, receives, transactions) were attempted by netperf.  Specified by the global <option>-w</option> option which requires &ndash;enable-intervals to have been specified with the configure command prior to building netperf. Units: Microseconds (though specified by default in milliseconds on the command line)</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_INTERVAL_BURST</code></tableterm>
          <item>
            <para>The number of operations (sends, receives, transactions depending on the test) which were attempted by netperf each LOCAL_INTERVAL_USECS units of time. Specified by the global <option>-b</option> option which requires &ndash;enable-intervals to have been specified with the configure command prior to building netperf.  Units: number of operations per burst.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_INTERVAL_USECS</code></tableterm>
          <item>
            <para>The interval at which bursts of operations (sends, receives, transactions) were attempted by netserver.  Specified by the global <option>-w</option> option which requires &ndash;enable-intervals to have been specified with the configure command prior to building netperf. Units: Microseconds (though specified by default in milliseconds on the command line)</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>REMOTE_INTERVAL_BURST</code></tableterm>
          <item>
            <para>The number of operations (sends, receives, transactions depending on the test) which were attempted by netperf each LOCAL_INTERVAL_USECS units of time. Specified by the global <option>-b</option> option which requires &ndash;enable-intervals to have been specified with the configure command prior to building netperf.  Units: number of operations per burst.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>LOCAL_SECURITY_TYPE_ID</code></tableterm>
          <tableterm><code>LOCAL_SECURITY_TYPE</code></tableterm>
          <tableterm><code>LOCAL_SECURITY_ENABLED_NUM</code></tableterm>
          <tableterm><code>LOCAL_SECURITY_ENABLED</code></tableterm>
          <tableterm><code>LOCAL_SECURITY_SPECIFIC</code></tableterm>
          <tableterm><code>REMOTE_SECURITY_TYPE_ID</code></tableterm>
          <tableterm><code>REMOTE_SECURITY_TYPE</code></tableterm>
          <tableterm><code>REMOTE_SECURITY_ENABLED_NUM</code></tableterm>
          <tableterm><code>REMOTE_SECURITY_ENABLED</code></tableterm>
          <tableterm><code>REMOTE_SECURITY_SPECIFIC</code></tableterm>
          <item>
            <para>A bunch of stuff related to what sort of security mechanisms (eg SELINUX) were enabled on the systems during the test.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>RESULT_BRAND</code></tableterm>
          <item>
            <para>The string specified by the user with the global <option>-B</option> option. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>UUID</code></tableterm>
          <item>
            <para>The universally unique identifier associated with this test, either generated automagically by netperf, or passed to netperf via an omni test-specific <option>-u</option> option. Note: Future versions may make this a global command-line option. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>MIN_LATENCY</code></tableterm>
          <item>
            <para>The minimum &ldquo;latency&rdquo; or operation time (send, receive or request/response exchange depending on the test) as measured on the netperf side when the global <option>-j</option> option was specified. Units: Microseconds.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>MAX_LATENCY</code></tableterm>
          <item>
            <para>The maximum &ldquo;latency&rdquo; or operation time (send, receive or request/response exchange depending on the test) as measured on the netperf side when the global <option>-j</option> option was specified. Units: Microseconds.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>P50_LATENCY</code></tableterm>
          <item>
            <para>The 50th percentile value of &ldquo;latency&rdquo; or operation time (send, receive or request/response exchange depending on the test) as measured on the netperf side when the global <option>-j</option> option was specified. Units: Microseconds.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>P90_LATENCY</code></tableterm>
          <item>
            <para>The 90th percentile value of &ldquo;latency&rdquo; or operation time (send, receive or request/response exchange depending on the test) as measured on the netperf side when the global <option>-j</option> option was specified. Units: Microseconds.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>P99_LATENCY</code></tableterm>
          <item>
            <para>The 99th percentile value of &ldquo;latency&rdquo; or operation time (send, receive or request/response exchange depending on the test) as measured on the netperf side when the global <option>-j</option> option was specified. Units: Microseconds.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>MEAN_LATENCY</code></tableterm>
          <item>
            <para>The average &ldquo;latency&rdquo; or operation time (send, receive or request/response exchange depending on the test) as measured on the netperf side when the global <option>-j</option> option was specified. Units: Microseconds.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>STDDEV_LATENCY</code></tableterm>
          <item>
            <para>The standard deviation of &ldquo;latency&rdquo; or operation time (send, receive or request/response exchange depending on the test) as measured on the netperf side when the global <option>-j</option> option was specified. Units: Microseconds.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>COMMAND_LINE</code></tableterm>
          <item>
            <para>The full command line used when invoking netperf. Units: ASCII Text.</para>
          </item>
        </tableitem>
        <tableitem>
          <tableterm><code>OUTPUT_END</code></tableterm>
          <item>
            <para>While emitted with the list of output selectors, it is ignored when specified as an output selector.</para>
          </item>
        </tableitem>
      </table>
    </subsection>
  </node>
  <node>
    <nodename>Other Netperf Tests</nodename>
    <nodenext>Address Resolution</nodenext>
    <nodeprev>The Omni Tests</nodeprev>
    <nodeup>Top</nodeup>
    <chapter>
      <title>Other Netperf Tests</title>
      <para>Apart from the typical performance tests, netperf contains some tests which can be used to streamline measurements and reporting.  These include CPU rate calibration (present) and host identification (future enhancement).</para>
      <menu>
        <menuentry>
          <menunode>CPU rate calibration</menunode>
          <menutitle>CPU rate calibration</menutitle>
          <menucomment></menucomment>
        </menuentry>
        <menuentry>
          <menunode>UUID Generation</menunode>
          <menutitle>UUID Generation</menutitle>
          <menucomment></menucomment>
        </menuentry>
      </menu>
    </chapter>
  </node>
  <node>
    <nodename>CPU rate calibration</nodename>
    <nodenext>UUID Generation</nodenext>
    <nodeprev>Other Netperf Tests</nodeprev>
    <nodeup>Other Netperf Tests</nodeup>
    <section>
      <title>CPU rate calibration</title>
      <para>Some of the CPU utilization measurement mechanisms of netperf work by comparing the rate at which some counter increments when the system is idle with the rate at which that same counter increments when the system is running a netperf test.  The ratio of those rates is used to arrive at a CPU utilization percentage.</para>
      <para>This means that netperf must know the rate at which the counter increments when the system is presumed to be &ldquo;idle.&rdquo;  If it does not know the rate, netperf will measure it before starting a data transfer test.  This calibration step takes 40 seconds for each of the local or remote systems, and if repeated for each netperf test would make taking repeated measurements rather slow.</para>
      <para>Thus, the netperf CPU utilization options <option>-c</option> and and <option>-C</option> can take an optional calibration value.  This value is used as the &ldquo;idle rate&rdquo; and the calibration step is not performed. To determine the idle rate, netperf can be used to run special tests which only report the value of the calibration - they are the LOC_CPU and REM_CPU tests.  These return the calibration value for the local and remote system respectively.  A common way to use these tests is to store their results into an environment variable and use that in subsequent netperf commands:</para>
      <example xml:space="preserve">LOC_RATE=`netperf -t LOC_CPU`
REM_RATE=`netperf -H &lt;remote&gt; -t REM_CPU`
netperf -H &lt;remote&gt; -c $LOC_RATE -C $REM_RATE ... -- ...
...
netperf -H &lt;remote&gt; -c $LOC_RATE -C $REM_RATE ... -- ...</example>
      <para>If you are going to use netperf to measure aggregate results, it is important to use the LOC_CPU and REM_CPU tests to get the calibration values first to avoid issues with some of the aggregate netperf tests transferring data while others are &ldquo;idle&rdquo; and getting bogus calibration values.  When running aggregate tests, it is very important to remember that any one instance of netperf does not know about the other instances of netperf.  It will report global CPU utilization and will calculate service demand believing it was the only thing causing that CPU utilization.  So, you can use the CPU utilization reported by netperf in an aggregate test, but you have to calculate service demands by hand.</para>
    </section>
  </node>
  <node>
    <nodename>UUID Generation</nodename>
    <nodeprev>CPU rate calibration</nodeprev>
    <nodeup>Other Netperf Tests</nodeup>
    <section>
      <title>UUID Generation</title>
      <para>Beginning with version 2.5.0 netperf can generate Universally Unique IDentifiers (UUIDs).  This can be done explicitly via the &ldquo;UUID&rdquo; test:</para>
      <example xml:space="preserve">$ netperf -t UUID
2c8561ae-9ebd-11e0-a297-0f5bfa0349d0</example>
      <para>In and of itself, this is not terribly useful, but used in conjunction with the test-specific <option>-u</option> option of an &ldquo;omni&rdquo; test to set the UUID emitted by the <xref><xrefnodename>Omni Output Selectors</xrefnodename><xrefinfoname>UUID</xrefinfoname></xref> output selector, it can be used to tie-together the separate instances of an aggregate netperf test.  Say, for instance if they were inserted into a database of some sort.</para>
    </section>
  </node>
  <node>
    <nodename>Address Resolution</nodename>
    <nodenext>Enhancing Netperf</nodenext>
    <nodeprev>Other Netperf Tests</nodeprev>
    <nodeup>Top</nodeup>
<!-- node-name,  next,  previous,  up -->
    <chapter>
      <title>Address Resolution</title>
      <para>Netperf versions 2.4.0 and later have merged IPv4 and IPv6 tests so the functionality of the tests in <file>src/nettest_ipv6.c</file> has been subsumed into the tests in <file>src/nettest_bsd.c</file>  This has been accomplished in part by switching from <code>gethostbyname()</code>to <code>getaddrinfo()</code> exclusively.  While it was theoretically possible to get multiple results for a hostname from <code>gethostbyname()</code> it was generally unlikely and netperf's ignoring of the second and later results was not much of an issue.</para>
      <para>Now with <code>getaddrinfo</code> and particularly with AF_UNSPEC it is increasingly likely that a given hostname will have multiple associated addresses.  The <code>establish_control()</code> routine of <file>src/netlib.c</file> will indeed attempt to chose from among all the matching IP addresses when establishing the control connection. Netperf does not _really_ care if the control connection is IPv4 or IPv6 or even mixed on either end.</para>
      <para>However, the individual tests still ass-u-me that the first result in the address list is the one to be used.  Whether or not this will turn-out to be an issue has yet to be determined.</para>
      <para>If you do run into problems with this, the easiest workaround is to specify IP addresses for the data connection explicitly in the test-specific <option>-H</option> and <option>-L</option> options.  At some point, the netperf tests _may_ try to be more sophisticated in their parsing of returns from <code>getaddrinfo()</code> - straw-man patches to <email><emailaddress>netperf-feedback@netperf.org</emailaddress></email> would of course be most welcome :)</para>
      <para>Netperf has leveraged code from other open-source projects with amenable licensing to provide a replacement <code>getaddrinfo()</code> call on those platforms where the <command>configure</command> script believes there is no native getaddrinfo call.  As of this writing, the replacement <code>getaddrinfo()</code> as been tested on HP-UX 11.0 and then presumed to run elsewhere.</para>
    </chapter>
  </node>
  <node>
    <nodename>Enhancing Netperf</nodename>
    <nodenext>Netperf4</nodenext>
    <nodeprev>Address Resolution</nodeprev>
    <nodeup>Top</nodeup>
<!-- node-name,  next,  previous,  up -->
    <chapter>
      <title>Enhancing Netperf</title>
      <para>Netperf is constantly evolving.  If you find you want to make enhancements to netperf, by all means do so.  If you wish to add a new &ldquo;suite&rdquo; of tests to netperf the general idea is to:</para>
      <enumerate first="1">
        <item>
          <para>Add files <file>src/nettest_mumble.c</file> and <file>src/nettest_mumble.h</file> where mumble is replaced with something meaningful for the test-suite.</para>
        </item>
        <item>
          <para>Add support for an appropriate <option>--enable-mumble</option> option in <file>configure.ac</file>.</para>
        </item>
        <item>
          <para>Edit <file>src/netperf.c</file>, <file>netsh.c</file>, and <file>netserver.c</file> as required, using #ifdef WANT_MUMBLE.</para>
        </item>
        <item>
          <para>Compile and test</para>
        </item>
      </enumerate>
      <para>However, with the addition of the &ldquo;omni&rdquo; tests in version 2.5.0 it is preferred that one attempt to make the necessary changes to <file>src/nettest_omni.c</file> rather than adding new source files, unless this would make the omni tests entirely too complicated.</para>
      <para>If you wish to submit your changes for possible inclusion into the mainline sources, please try to base your changes on the latest available sources. (See <xref><xrefnodename>Getting Netperf Bits</xrefnodename></xref>.) and then send email describing the changes at a high level to <email><emailaddress>netperf-feedback@netperf.org</emailaddress></email> or perhaps <email><emailaddress>netperf-talk@netperf.org</emailaddress></email>.  If the consensus is positive, then sending context <command>diff</command> results to <email><emailaddress>netperf-feedback@netperf.org</emailaddress></email> is the next step.  From that point, it is a matter of pestering the Netperf Contributing Editor until he gets the changes incorporated :)</para>
    </chapter>
  </node>
  <node>
    <nodename>Netperf4</nodename>
    <nodenext>Concept Index</nodenext>
    <nodeprev>Enhancing Netperf</nodeprev>
    <nodeup>Top</nodeup>
<!-- node-name,  next,  previous,  up -->
    <chapter>
      <title>Netperf4</title>
      <para>Netperf4 is the shorthand name given to version 4.X.X of netperf. This is really a separate benchmark more than a newer version of netperf, but it is a descendant of netperf so the netperf name is kept.  The facetious way to describe netperf4 is to say it is the egg-laying-woolly-milk-pig version of netperf :)  The more respectful way to describe it is to say it is the version of netperf with support for synchronized, multiple-thread, multiple-test, multiple-system, network-oriented benchmarking.</para>
      <para>Netperf4 is still undergoing evolution. Those wishing to work with or on netperf4 are encouraged to join the <uref><urefurl>http://www.netperf.org/cgi-bin/mailman/listinfo/netperf-dev</urefurl><urefdesc>netperf-dev</urefdesc></uref> mailing list and/or peruse the <uref><urefurl>http://www.netperf.org/svn/netperf4/trunk</urefurl><urefdesc>current sources</urefdesc></uref>.</para>
    </chapter>
  </node>
  <node>
    <nodename>Concept Index</nodename>
    <nodenext>Option Index</nodenext>
    <nodeprev>Netperf4</nodeprev>
    <nodeup>Top</nodeup>
    <unnumbered>
      <title>Concept Index</title>
      <printindex>cp</printindex>
    </unnumbered>
  </node>
  <node>
    <nodename>Option Index</nodename>
    <nodeprev>Concept Index</nodeprev>
    <nodeup>Top</nodeup>
<!-- node-name,  next,  previous,  up -->
    <unnumbered>
      <title>Option Index</title>
      <printindex>vr</printindex>
    </unnumbered>
  </node>
</texinfo>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-indent-step:1
sgml-indent-data:nil
End:
-->
