blob: 88aee750464a69deea497411cc2484cc8ab10962 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>iperf3 Development &#8212; iperf3 3.15 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css?v=4468db6d" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/esnet/esnet.css" type="text/css" />
<script src="_static/documentation_options.js?v=c35749de"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/jquery-1.11.0.min.js"></script>
<script src="_static/js/jquery-fix.js"></script>
<script src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
<script src="_static/bootstrap-sphinx.js"></script>
<link rel="icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="iperf3 FAQ" href="faq.html" />
<link rel="prev" title="Invoking iperf3" href="invoking.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
</head><body>
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">
iperf3</a>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="index.html">Section <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="news.html">iperf3 Project News</a></li>
<li class="toctree-l1"><a class="reference internal" href="obtaining.html">Obtaining iperf3</a></li>
<li class="toctree-l1"><a class="reference internal" href="building.html">Building iperf3</a></li>
<li class="toctree-l1"><a class="reference internal" href="invoking.html">Invoking iperf3</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">iperf3 Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">iperf3 FAQ</a></li>
</ul>
</ul>
</li>
<li>
<a href="invoking.html" title="Previous Chapter: Invoking iperf3">
<span class="glyphicon glyphicon-chevron-left"></span>
<span class="hidden-sm">
Invoking iperf3
</span>
</a>
</li>
<li>
<a href="faq.html" title="Next Chapter: iperf3 FAQ">
<span class="hidden-sm">
iperf3 FAQ
</span>
<span class="glyphicon glyphicon-chevron-right"></span>
</a>
</li>
<li class="divider-vertical"></li>
<li><a href="genindex.html">Index</a></li>
<li><a href="https://www.es.net">ESnet</a></li>
<li><a href="https://github.com/esnet/iperf"><img src="_static/icon-github.png" height="20" width="20"></a></li>
<li class="hidden-sm">
<div id="sourcelink">
<a href="_sources/dev.rst.txt"
rel="nofollow">Source</a>
</div></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3">
<div id="sidebar" class="bs-sidenav" role="complementary"><ul>
<li><a class="reference internal" href="#">iperf3 Development</a><ul>
<li><a class="reference internal" href="#mailing-lists">Mailing Lists</a></li>
<li><a class="reference internal" href="#bug-reports">Bug Reports</a></li>
<li><a class="reference internal" href="#changes-from-iperf-2-x">Changes from iperf 2.x</a></li>
<li><a class="reference internal" href="#known-issues">Known Issues</a></li>
<li><a class="reference internal" href="#versioning">Versioning</a></li>
<li><a class="reference internal" href="#release-engineering-checklist">Release Engineering Checklist</a></li>
<li><a class="reference internal" href="#code-authors">Code Authors</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="col-md-9">
<section id="iperf3-development">
<h1>iperf3 Development<a class="headerlink" href="#iperf3-development" title="Link to this heading"></a></h1>
<p>The iperf3 project is hosted on GitHub at:</p>
<p><a class="reference external" href="http://github.com/esnet/iperf">http://github.com/esnet/iperf</a></p>
<p>This site includes the source code repository, issue tracker, and
wiki.</p>
<section id="mailing-lists">
<h2>Mailing Lists<a class="headerlink" href="#mailing-lists" title="Link to this heading"></a></h2>
<p>The developer list for iperf3 is: <a class="reference external" href="mailto:iperf-dev&#37;&#52;&#48;googlegroups&#46;com">iperf-dev<span>&#64;</span>googlegroups<span>&#46;</span>com</a>.
Information on joining the mailing list can be found at:</p>
<p><a class="reference external" href="http://groups.google.com/group/iperf-dev">http://groups.google.com/group/iperf-dev</a></p>
<p>There is, at the moment, no mailing list for user questions, although
a low volume of inquiries on the developer list is probably
acceptable. If necessary, a user-oriented mailing list might be
created in the future.</p>
</section>
<section id="bug-reports">
<h2>Bug Reports<a class="headerlink" href="#bug-reports" title="Link to this heading"></a></h2>
<p>Before submitting a bug report, try checking out the latest version of
the code, and confirm that it’s not already fixed. Also see the <a class="reference internal" href="faq.html"><span class="doc">iperf3 FAQ</span></a>.
Then submit to the iperf3 issue tracker on GitHub:</p>
<p><a class="reference external" href="https://github.com/esnet/iperf/issues">https://github.com/esnet/iperf/issues</a></p>
<p>For reporting potential security issues, please contact the developers at
<a class="reference external" href="mailto:iperf&#37;&#52;&#48;es&#46;net">iperf<span>&#64;</span>es<span>&#46;</span>net</a>.</p>
<p><strong>Note:</strong> Issues submitted to the old iperf3 issue tracker on Google
Code (or comments to existing issues on the Google Code issue tracker)
will be ignored.</p>
</section>
<section id="changes-from-iperf-2-x">
<h2>Changes from iperf 2.x<a class="headerlink" href="#changes-from-iperf-2-x" title="Link to this heading"></a></h2>
<p>New options (not necessarily complete, please refer to the manual page
for a complete list of iperf3 options):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">V</span><span class="p">,</span> <span class="o">--</span><span class="n">verbose</span> <span class="n">more</span> <span class="n">detailed</span> <span class="n">output</span> <span class="n">than</span> <span class="n">before</span>
<span class="o">-</span><span class="n">J</span><span class="p">,</span> <span class="o">--</span><span class="n">json</span> <span class="n">output</span> <span class="ow">in</span> <span class="n">JSON</span> <span class="nb">format</span>
<span class="o">-</span><span class="n">Z</span><span class="p">,</span> <span class="o">--</span><span class="n">zerocopy</span> <span class="n">use</span> <span class="n">a</span> <span class="s1">&#39;zero copy&#39;</span> <span class="n">sendfile</span><span class="p">()</span> <span class="n">method</span> <span class="n">of</span> <span class="n">sending</span> <span class="n">data</span>
<span class="o">-</span><span class="n">O</span><span class="p">,</span> <span class="o">--</span><span class="n">omit</span> <span class="n">N</span> <span class="n">omit</span> <span class="n">the</span> <span class="n">first</span> <span class="n">n</span> <span class="n">seconds</span> <span class="p">(</span><span class="n">to</span> <span class="n">ignore</span> <span class="n">slowstart</span><span class="p">)</span>
<span class="o">-</span><span class="n">T</span><span class="p">,</span> <span class="o">--</span><span class="n">title</span> <span class="nb">str</span> <span class="n">prefix</span> <span class="n">every</span> <span class="n">output</span> <span class="n">line</span> <span class="k">with</span> <span class="n">this</span> <span class="n">string</span>
<span class="o">-</span><span class="n">F</span><span class="p">,</span> <span class="o">--</span><span class="n">file</span> <span class="n">name</span> <span class="n">xmit</span><span class="o">/</span><span class="n">recv</span> <span class="n">the</span> <span class="n">specified</span> <span class="n">file</span>
<span class="o">-</span><span class="n">A</span><span class="p">,</span> <span class="o">--</span><span class="n">affinity</span> <span class="n">n</span><span class="o">/</span><span class="n">n</span><span class="p">,</span><span class="n">m</span> <span class="nb">set</span> <span class="n">CPU</span> <span class="n">affinity</span> <span class="p">(</span><span class="n">Linux</span> <span class="ow">and</span> <span class="n">FreeBSD</span> <span class="n">only</span><span class="p">)</span>
<span class="o">-</span><span class="n">k</span><span class="p">,</span> <span class="o">--</span><span class="n">blockcount</span> <span class="c1">#[KMG] number of blocks (packets) to transmit (instead</span>
<span class="n">of</span> <span class="o">-</span><span class="n">t</span> <span class="ow">or</span> <span class="o">-</span><span class="n">n</span><span class="p">)</span>
<span class="o">-</span><span class="n">L</span><span class="p">,</span> <span class="o">--</span><span class="n">flowlabel</span> <span class="nb">set</span> <span class="n">IPv6</span> <span class="n">flow</span> <span class="n">label</span> <span class="p">(</span><span class="n">Linux</span> <span class="n">only</span><span class="p">)</span>
</pre></div>
</div>
<p>Changed flags:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">C</span><span class="p">,</span> <span class="o">--</span><span class="n">linux</span><span class="o">-</span><span class="n">congestion</span> <span class="nb">set</span> <span class="n">congestion</span> <span class="n">control</span> <span class="n">algorithm</span> <span class="p">(</span><span class="n">Linux</span> <span class="n">only</span><span class="p">)</span>
<span class="p">(</span><span class="o">-</span><span class="n">Z</span> <span class="ow">in</span> <span class="n">iperf2</span><span class="p">)</span>
</pre></div>
</div>
<p>Deprecated flags (currently no plans to support):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">d</span><span class="p">,</span> <span class="o">--</span><span class="n">dualtest</span> <span class="n">Do</span> <span class="n">a</span> <span class="n">bidirectional</span> <span class="n">test</span> <span class="n">simultaneously</span>
<span class="o">-</span><span class="n">r</span><span class="p">,</span> <span class="o">--</span><span class="n">tradeoff</span> <span class="n">Do</span> <span class="n">a</span> <span class="n">bidirectional</span> <span class="n">test</span> <span class="n">individually</span>
<span class="o">-</span><span class="n">T</span><span class="p">,</span> <span class="o">--</span><span class="n">ttl</span> <span class="n">time</span><span class="o">-</span><span class="n">to</span><span class="o">-</span><span class="n">live</span><span class="p">,</span> <span class="k">for</span> <span class="n">multicast</span> <span class="p">(</span><span class="n">default</span> <span class="mi">1</span><span class="p">)</span>
<span class="o">-</span><span class="n">x</span><span class="p">,</span> <span class="o">--</span><span class="n">reportexclude</span> <span class="p">[</span><span class="n">CDMSV</span><span class="p">]</span> <span class="n">exclude</span> <span class="n">C</span><span class="p">(</span><span class="n">connection</span><span class="p">)</span> <span class="n">D</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> <span class="n">M</span><span class="p">(</span><span class="n">multicast</span><span class="p">)</span>
<span class="n">S</span><span class="p">(</span><span class="n">settings</span><span class="p">)</span> <span class="n">V</span><span class="p">(</span><span class="n">server</span><span class="p">)</span> <span class="n">reports</span>
<span class="o">-</span><span class="n">y</span><span class="p">,</span> <span class="o">--</span><span class="n">reportstyle</span> <span class="n">C</span> <span class="n">report</span> <span class="k">as</span> <span class="n">a</span> <span class="n">Comma</span><span class="o">-</span><span class="n">Separated</span> <span class="n">Values</span>
</pre></div>
</div>
<p>Also deprecated is the ability to set the options via environment
variables.</p>
</section>
<section id="known-issues">
<h2>Known Issues<a class="headerlink" href="#known-issues" title="Link to this heading"></a></h2>
<p>The following problems are notable known issues, which are probably of
interest to a large fraction of users or have high impact for some
users, and for which issues have already been filed in the issue
tracker. These issues are either open (indicating no solution
currently exists) or closed with the notation that no further attempts
to solve the problem are currently being made:</p>
<ul class="simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">-Z</span></code> flag sometimes causes the iperf3 client to hang on OSX.
(Issue #129)</p></li>
<li><p>When specifying the TCP buffer size using the <code class="docutils literal notranslate"><span class="pre">-w</span></code> flag on Linux,
the Linux kernel automatically doubles the value passed in to
compensate for overheads. (This can be observed by using
iperf3’s <code class="docutils literal notranslate"><span class="pre">--debug</span></code> flag.) However, CWND does not actually ramp up
to the doubled value, but only to about 75% of the doubled
value. Some part of this behavior is documented in the tcp(7)
manual page.</p></li>
<li><p>Although the <code class="docutils literal notranslate"><span class="pre">-w</span></code> flag is documented as setting the (TCP) window
size, it is also used to set the socket buffer size. This has been
shown to be helpful with high-bitrate UDP tests.</p></li>
<li><p>On some platforms (observed on at least one version of Ubuntu
Linux), it might be necessary to invoke <code class="docutils literal notranslate"><span class="pre">ldconfig</span></code> manually after
doing a <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code> before the <code class="docutils literal notranslate"><span class="pre">iperf3</span></code> executable can find
its shared library. (Issue #153)</p></li>
<li><p>The results printed on the server side at the end of a test do not
correctly reflect the client-side measurements. This is due to the
ordering of computing and transferring results between the client
and server. (Issue #293)</p></li>
<li><p>The server could have a very short measurement reporting interval at
the end of a test (particularly a UDP test), containing few or no
packets. This issue is due to an artifact of timing between the
client and server. (Issue #278)</p></li>
</ul>
<p>There are, of course, many other open and closed issues in the issue
tracker.</p>
</section>
<section id="versioning">
<h2>Versioning<a class="headerlink" href="#versioning" title="Link to this heading"></a></h2>
<p>iperf3 version numbers use (roughly) a <a class="reference external" href="http://semver.org/">Semantic Versioning</a> scheme, in which version numbers consist of
three parts: <em>MAJOR.MINOR.PATCH</em></p>
<p>The developers increment the:</p>
<ul class="simple">
<li><p><em>MAJOR</em> version when making incompatible API changes,</p></li>
<li><p><em>MINOR</em> version when adding functionality in a backwards-compatible manner, and</p></li>
<li><p><em>PATCH</em> version when making backwards-compatible bug fixes.</p></li>
</ul>
</section>
<section id="release-engineering-checklist">
<h2>Release Engineering Checklist<a class="headerlink" href="#release-engineering-checklist" title="Link to this heading"></a></h2>
<ol class="arabic">
<li><p>Update the <code class="docutils literal notranslate"><span class="pre">README.md</span></code> and <code class="docutils literal notranslate"><span class="pre">RELNOTES.md</span></code> files to be accurate. Make sure
that the “Known Issues” section of the <code class="docutils literal notranslate"><span class="pre">README.md</span></code> file and in this document
are up to date.</p></li>
<li><p>Compose a release announcement. Most of the release announcement
can be written before tagging. Usually the previous version’s
announcement can be used as a starting point.</p></li>
<li><p>Preferably starting from a clean source tree (be sure that <code class="docutils literal notranslate"><span class="pre">git</span>
<span class="pre">status</span></code> emits no output), make the changes necessary to produce
the new version, such as bumping version numbers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>vi RELNOTES.md # update version number and release date
vi configure.ac # update version parameter in AC_INIT
vi src/iperf3.1 # update manpage revision date if needed
vi src/libiperf.3 # update manpage revision date if needed
git commit -a # commit changes to the local repository only
./bootstrap.sh # regenerate configure script, etc.
git commit -a # commit changes to the local repository only
# Assuming that $VERSION is the version number to be released...
./make_release tag $VERSION # this creates a tag in the local repo
./make_release tar $VERSION # create tarball and compute SHA256 hash
</pre></div>
</div>
<p>These steps should be done on a platform with a relatively recent
version of autotools / libtools. Examples are MacOS / MacPorts or
FreeBSD. The versions of these tools in CentOS 6 are somewhat
older and probably should be avoided.</p>
<p>The result will be a release artifact that should be used for
pre-testing.</p>
</li>
<li><p>Stage the tarball (and a file containing the SHA256 hash) to the
download site. Currently this is located on <code class="docutils literal notranslate"><span class="pre">downloads.es.net</span></code>.</p></li>
<li><p>From another host, test the link in the release announcement by
downloading a fresh copy of the file and verifying the SHA256
checksum. Checking all other links in the release announcement is
strongly recommended as well.</p></li>
<li><p>Also verify (with file(1)) that the tarball is actually a gzipped
tarball.</p></li>
<li><p>For extra points, actually try downloading, compiling, and
smoke-testing the results of the tarball on all supported
platforms.</p></li>
<li><p>Plug the SHA256 checksum into the release announcement.</p></li>
<li><p>PGP-sign the release announcement text using <code class="docutils literal notranslate"><span class="pre">gpg</span> <span class="pre">--clearsign</span></code>.
The signed announcement will be sent out in a subsequent emails,
but could also be archived. Decoupling the signing from emailing
allows a signed release announcement to be resent via email or sent
by other, non-email means.</p></li>
<li><p>At this point, the release can and should be considered
finalized. To commit the release-engineering-related changes to
GitHub and make them public, push them out thusly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span> <span class="c1"># Push version changes</span>
<span class="n">git</span> <span class="n">push</span> <span class="o">--</span><span class="n">tags</span> <span class="c1"># Push the new tag to the GitHub repo</span>
</pre></div>
</div>
</li>
<li><p>Send the PGP-signed release announcement to the following
addresses. Remember to turn off signing in the MUA, if
applicable. Remember to check the source address when posting to
lists, as “closed” list will reject posting from all from
registered email addresses.</p>
<ul class="simple">
<li><p><a class="reference external" href="mailto:iperf-dev&#37;&#52;&#48;googlegroups&#46;com">iperf-dev<span>&#64;</span>googlegroups<span>&#46;</span>com</a></p></li>
<li><p><a class="reference external" href="mailto:iperf-users&#37;&#52;&#48;lists&#46;sourceforge&#46;net">iperf-users<span>&#64;</span>lists<span>&#46;</span>sourceforge<span>&#46;</span>net</a></p></li>
<li><p><a class="reference external" href="mailto:perfsonar-user&#37;&#52;&#48;internet2&#46;edu">perfsonar-user<span>&#64;</span>internet2<span>&#46;</span>edu</a></p></li>
<li><p><a class="reference external" href="mailto:perfsonar-developer&#37;&#52;&#48;internet2&#46;edu">perfsonar-developer<span>&#64;</span>internet2<span>&#46;</span>edu</a></p></li>
</ul>
<p>Note: Thunderbird sometimes mangles the PGP-signed release
announcement so that it does not verify correctly. This could be
due to Thunderbird trying to wrap the length of extremely long
lines (such as the SHA256 hash). Apple Mail and mutt seem to
handle this situation correctly. Testing the release announcement
sending process by sending a copy to oneself first and attempting
to verify the signature is highly encouraged.</p>
</li>
<li><p>Update GitHub Releases with the current release notes.</p></li>
<li><p>Update the iperf3 Project News section of the documentation site
to announce the new release (see <code class="docutils literal notranslate"><span class="pre">docs/news.rst</span></code> and
<code class="docutils literal notranslate"><span class="pre">docs/conf.py</span></code> in the source tree) and deploy a new build of the
documentation to GitHub Pages.</p></li>
<li><p>If an update to the on-line manual page is needed, it can be
generated with this sequence of commands (tested on CentOS 7) and
import the result into <code class="docutils literal notranslate"><span class="pre">invoking.rst</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TERM</span><span class="o">=</span>
<span class="n">export</span> <span class="n">TERM</span>
<span class="n">nroff</span> <span class="o">-</span><span class="n">Tascii</span> <span class="o">-</span><span class="n">c</span> <span class="o">-</span><span class="n">man</span> <span class="n">src</span><span class="o">/</span><span class="n">iperf3</span><span class="mf">.1</span> <span class="o">|</span> <span class="n">ul</span> <span class="o">|</span> <span class="n">sed</span> <span class="s1">&#39;s/^/ /&#39;</span> <span class="o">&gt;</span> <span class="n">iperf3</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
</li>
</ol>
</section>
<section id="code-authors">
<h2>Code Authors<a class="headerlink" href="#code-authors" title="Link to this heading"></a></h2>
<p>The main authors of iperf3 are (in alphabetical order): Jon Dugan,
Seth Elliott, Bruce A. Mah, Jeff Poskanzer, Kaustubh Prabhu.
Additional code contributions have come from (also in alphabetical
order): Mark Ashley, Aaron Brown, Aeneas Jaißle, Susant Sahani,
Bruce Simpson, Brian Tierney.</p>
<p>iperf3 contains some original code from iperf2. The authors of iperf2
are (in alphabetical order): Jon Dugan, John Estabrook, Jim Ferbuson,
Andrew Gallatin, Mark Gates, Kevin Gibbs, Stephen Hemminger, Nathan
Jones, Feng Qin, Gerrit Renker, Ajay Tirumala, Alex Warshavsky.</p>
</section>
</section>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<div class="row">
<div class="col-md-1">
<a href="http://www.es.net/"><img src="_static/ESnet_Final_Logos_All_Blue_Circle_Stamp_RGB.png" alt="[ESnet]"></a>
</div>
<div class="col-md-11">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
&copy; Copyright 2014-2023, ESnet.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 7.2.6.<br/>
</p>
</div>
</div>
</div>
</footer>
</body>
</html>