diff options
Diffstat (limited to 'docs')
25 files changed, 2693 insertions, 0 deletions
diff --git a/docs/2017-04-27.txt b/docs/2017-04-27.txt new file mode 100644 index 0000000..dc8206e --- /dev/null +++ b/docs/2017-04-27.txt @@ -0,0 +1,95 @@ +Subject: iperf3 status, April 2017 + +This is the first of a series of (maybe periodic?) updates about +iperf3 development: + +State of the iperf3 World, as seen from ESnet... +------------------------------------------------ + +iperf3 was originally written to be a "better", more maintainable +follow-on to iperf2. This was seen to be necessary to fill the +requirements for the perfSONAR project (http://www.perfsonar.net). + +In the past few years, iperf2 development has been restarted by Bob +McMahon of Broadcom. He (and other contributors) have fixed a number +of problems with iperf2 and added some new features +(https://sourceforge.net/projects/iperf2/). We're happy to observe +that iperf2 is once again under active development, and we have +started discussing ways in which these two projects could productively +interact. + +We note that iperf3 lacks several features found in iperf2, for +example multicast tests, bidirectional tests, multi-threading, and +official Windows support. Given the active state of iperf2 +development and maintenance, we feel that the needs of users requiring +such functionality are best met by using a recent version of iperf2 +instead of waiting for them to be backported or reimplemented in +iperf3. + +ESnet's main interest in iperf3 is for testing high-performance +Research and Education (R&E) networks, especially as a part of the +perfSONAR toolkit. iperf3 can be useful in other circumstances as +well, but high-speed R&E network performance testing will remain the +primary use case. (Much of iperf2's recent development +has focused on the use of UDP for end-to-end latency testing on a +broad range of platforms, although it too is useful for many other +testing scenarios.) + +iperf3 Support +-------------- + +We're trying to work down the support backlog for iperf3. To that +end, we've been aggressively triaging iperf3 issues in the issue +tracker on GitHub. Over the past several weeks, we've gone from about +180 open issues to less than 75. A number of these issues were user +questions, not bug reports or enhancement requests. We're now +discouraging the use of the iperf3 issue tracker for questions. +Instead we'd like users to either use the mailing list +(iperf-dev@google-groups.com) or to look to various question sites on +the Internet such as Stack Overflow (http://www.stackoverflow.com). + +We're happy to accept enhancement requests, although it should be +noted that ESnet's time commitments to iperf3 are somewhat limited and +we need to prioritize our work to match our own requirements. We have +begun using the "Help Wanted" label in the issue tracker on GitHub to +indicate requests we agree with (or at least don't object to), but +which we don't have the time to work on ourselves. These are good +candidates for someone in the community to work on and submit as a +pull request. + +Pull requests are still encouraged, as long as they're compatible with +ESnet's goals and requirements for iperf3. If you're contemplating a +code change that would have a major, fundamental change on the iperf3 +architecture, we strongly encourage discussion with the iperf3 +maintainers before doing a significant amount of work. + +Some of the above considerations are now documented in GitHub +templates that we've recently installed for new issues, pull requests, +and contribution guidelines. + +To make it easier for new users with common questions, we have created +a Frequently Asked Questions (FAQ) list, which is now available on the +iperf3 Web site, at: + +http://software.es.net/iperf/faq.html + +Future Plans +------------ + +In the near-term, we're planning another iperf3 release that will +include some recently added changes. Because some of the changes are +rather large, we're considering basing this release off the mainline +which would make it the first 3.2 release, rather than try to backport +these changes and make another "bugfix" 3.1 release. No decisions +have been made yet. + +The main changes (already on the master branch) are authentication +(#517), a more fine-grained pacing timer (#460), and some portability +fixes. We'd appreciate any testing and feedback that users in the +community could give on these. + +Thanks for your interest and support of iperf3, + +Bruce Mah +Software Engineering Group +ESnet diff --git a/docs/2017-06-06.txt b/docs/2017-06-06.txt new file mode 100644 index 0000000..e5a16cd --- /dev/null +++ b/docs/2017-06-06.txt @@ -0,0 +1,43 @@ +Subject: iperf3 status, June 2017 + +iperf 3.2 Release Plans +----------------------- + +We've done quite a bit of work the past few weeks getting the master +branch in shape to cut a new release, which will be the first of the +3.2.x series. These changes include fixes for a number of +long-standing bugs (such as some of the statistics computation, and +fixes for --file), as well as new features (for example optional +authentication and a configurable client connection timeout) and +general improvements (better timing for the --bitrate/--bandwidth +options). + +We'd like to encourage users in the community who are comfortable +compiling iperf3 from GitHub sources, to checkout / clone the iperf3 +master branch from GitHub and try it out in their environments. (No +tarballs will be produced until the official 3.2 release, although I'd +say we're basically in "release candidate" stage now.) + +There is a mostly-final set of release notes in the RELEASE_NOTES file +on master, so you can see what's new, changed, fixed, and so on. + +Assuming no serious problems, we're aiming for an official release in +mid- to late-June (2017!). + +iperf3 Support +-------------- + +After a lot of issue triage, we're down to 38 issues in the issue +tracker (plus three outstanding pull requests). As mentioned in an +earlier update, a lot of the issues we closed were user questions, not +bug reports or enhancement requests. We'd like to direct user +questions to either the mailing lists or to look on various question +sites such as Stack Overflow. For bug reports (where you think iperf3 +is doing something wrong) and enhancement requests (what can it do +better), please file an issue. + +Thanks for your interest and support of iperf3, + +Bruce Mah +Software Engineering Group +ESnet diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..fc04d3d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/iperf.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/iperf.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/iperf" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/iperf" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/_esnet/LICENSE b/docs/_esnet/LICENSE new file mode 100644 index 0000000..ea4c32f --- /dev/null +++ b/docs/_esnet/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2014, ESnet +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the {organization} nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file diff --git a/docs/_esnet/README.rst b/docs/_esnet/README.rst new file mode 100644 index 0000000..0b47098 --- /dev/null +++ b/docs/_esnet/README.rst @@ -0,0 +1,107 @@ +esnet-gh-pages-base +=================== + +Base templates for ESnet's GitHub pages. These pages are created using the +Sphinx_ documentation package using the sphinx-bootstrap-theme_ with some +pages. This repo is meant to be included into a project using git subtree and +provides the overrides and customizations to the base theme. + +.. _Sphinx: http://sphinx-doc.org +.. _sphinx-bootstrap-theme: https://github.com/ryan-roemer/sphinx-bootstrap-theme + +Installation +------------ + +1. Install Sphinx and sphinx-bootstrap-theme. See the instructions below for + installing these either using the Mac OS X base system python or MacPorts. +2. ``cd $PROJECT_ROOT`` +3. ``mkdir docs`` +4. ``git subtree add --prefix docs/_esnet https://github.com/esnet/esnet-gh-pages-base.git master --squash`` +5. ``cd docs`` +6. ``sphinx-quickstart`` +7. ``ln -s ../_esnet/static _static/esnet`` +8. edit ``conf.py`` as described in the next section + +Editing conf.py +^^^^^^^^^^^^^^^ + +``sphinx-quickstart`` creates a basic conf.py file, however to use the ESnet +theme we need to make some changes. Make the following changes to conf.py:: + + # add this with the imports at the top of the file + import sphinx_bootstrap_theme + + # change templates_path to this + templates_path = ['_esnet/templates'] + + # add _esnet to exclude_patterns + exclude_patterns = ['_build', '_esnet'] + + # change html_theme and html_theme_path: + html_theme = 'bootstrap' + html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() + + # add html_theme options: + html_theme_options = { + "navbar_pagenav": False, + "nosidebar": False, + "navbar_class": "navbar", + "navbar_site_name": "Section", + "source_link_position": "footer", + "navbar_links": [ + ("Index", "genindex"), + ("ESnet", "https://www.es.net", True), + ], + } + + # add html_logo and html_sidebars + html_logo = "_esnet/static/logo-esnet-ball-sm.png" + html_sidebars = {'index': None, 'search': None, '*': ['localtoc.html']} + html_favicon = "_esnet/static/favicon.ico" + html_context = { + "github_url": "https://github.com/esnet/PROJNAME", + } + +That's it! + +Sphinx Installation using Mac OS X Base Python +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. sudo /usr/bin/easy_install pip +2. sudo /usr/local/bin/pip install sphinx sphinx-bootstrap-theme + +Sphinx Installation using MacPorts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. port install python27 py27-pip py27-sphinx +2. port select pip py27-pip +3. port select sphinx py27-sphinx +4. pip install sphinx sphinx-bootstrap-theme # make sure this is + /opt/local/bin/pip + +Creating Content, Previewing and Publishing +------------------------------------------- + +The files are in the ``docs`` directory. Take a look at the content of +``index.rst``. Take a look at the docs from other projects and review the +documentation for Sphinx_. + +Building HTML +^^^^^^^^^^^^^ + +In the ``docs`` directory run ``make clean html``. + +Previewing the site +^^^^^^^^^^^^^^^^^^^ + +``open _build/html/index.html`` + +or + +``open -a /Application/Google\ Chrome.app _build/html/index.html`` + +Publishing the site +^^^^^^^^^^^^^^^^^^^ + +From the ``docs`` directory run ``_esnet/deploy.sh``. It will be visible at: +``http://github.com/esnet/PROJECT``. diff --git a/docs/_esnet/deploy.sh b/docs/_esnet/deploy.sh new file mode 100755 index 0000000..223718c --- /dev/null +++ b/docs/_esnet/deploy.sh @@ -0,0 +1,18 @@ +#!/bin/sh + +GIT_URL=`git remote show origin | awk '/Push URL/ { print $NF }'` +DEPLOY_DIR=/tmp/deploy.$$ +mkdir ${DEPLOY_DIR} +(cd ${DEPLOY_DIR} ; \ + git clone ${GIT_URL} . \ + && git checkout gh-pages \ + && git rm -rf . +) +cp -r _build/html/* ${DEPLOY_DIR} +touch ${DEPLOY_DIR}/.nojekyll +(cd ${DEPLOY_DIR} ; \ + git add .nojekyll * \ + && git commit -m "deploy" \ + && git push) + +rm -rf ${DEPLOY_DIR} diff --git a/docs/_esnet/static/ESnet_Final_Logos_All_Blue_Circle_Stamp_RGB.png b/docs/_esnet/static/ESnet_Final_Logos_All_Blue_Circle_Stamp_RGB.png Binary files differnew file mode 100644 index 0000000..5fcd14a --- /dev/null +++ b/docs/_esnet/static/ESnet_Final_Logos_All_Blue_Circle_Stamp_RGB.png diff --git a/docs/_esnet/static/esnet.css b/docs/_esnet/static/esnet.css new file mode 100644 index 0000000..5526ebb --- /dev/null +++ b/docs/_esnet/static/esnet.css @@ -0,0 +1,84 @@ +body { + padding-top: 70px; // bootstrap default +} + +.navbar-default { + background-color: #006495; + border-color: #004e74; +} +.navbar-default .navbar-brand { + color: #ecf0f1; +} +.navbar-default .navbar-brand:hover, .navbar-default .navbar-brand:focus { + color: #ffffff; +} +.navbar-default .navbar-text { + color: #ecf0f1; +} +.navbar-default .navbar-nav > li > a { + color: #ecf0f1; +} +.navbar-default .navbar-nav > li > a:hover, .navbar-default .navbar-nav > li > a:focus { + color: #ffffff; +} +.navbar-default .navbar-nav > .active > a, .navbar-default .navbar-nav > .active > a:hover, .navbar-default .navbar-nav > .active > a:focus { + color: #ffffff; + background-color: #004e74; +} +.navbar-default .navbar-nav > .open > a, .navbar-default .navbar-nav > .open > a:hover, .navbar-default .navbar-nav > .open > a:focus { + color: #ffffff; + background-color: #004e74; +} +.navbar-default .navbar-toggle { + border-color: #004e74; +} +.navbar-default .navbar-toggle:hover, .navbar-default .navbar-toggle:focus { + background-color: #004e74; +} +.navbar-default .navbar-toggle .icon-bar { + background-color: #ecf0f1; +} +.navbar-default .navbar-collapse, +.navbar-default .navbar-form { + border-color: #ecf0f1; +} +.navbar-default .navbar-link { + color: #ecf0f1; +} +.navbar-default .navbar-link:hover { + color: #ffffff; +} + +@media (max-width: 767px) { + .navbar-default .navbar-nav .open .dropdown-menu > li > a { + color: #ecf0f1; + } + .navbar-default .navbar-nav .open .dropdown-menu > li > a:hover, .navbar-default .navbar-nav .open .dropdown-menu > li > a:focus { + color: #ffffff; + } + .navbar-default .navbar-nav .open .dropdown-menu > .active > a, .navbar-default .navbar-nav .open .dropdown-menu > .active > a:hover, .navbar-default .navbar-nav .open .dropdown-menu > .active > a:focus { + color: #ffffff; + background-color: #004e74; + } +} + +/* + * Vertical divider + */ +.navbar .divider-vertical { + height: 50px; + margin: 0 9px; + border-right: 1px solid #ecf0f1; + border-left: 1px solid #ecf0f1; +} + +.navbar-inverse .divider-vertical { + border-right-color: #222222; + border-left-color: #111111; +} + +@media (max-width: 767px) { + .navbar-collapse .nav > .divider-vertical { + display: none; + } +} diff --git a/docs/_esnet/static/favicon.ico b/docs/_esnet/static/favicon.ico Binary files differnew file mode 100644 index 0000000..227e65f --- /dev/null +++ b/docs/_esnet/static/favicon.ico diff --git a/docs/_esnet/static/icon-github.png b/docs/_esnet/static/icon-github.png Binary files differnew file mode 100755 index 0000000..a9c6940 --- /dev/null +++ b/docs/_esnet/static/icon-github.png diff --git a/docs/_esnet/static/logo-esnet-ball-sm.png b/docs/_esnet/static/logo-esnet-ball-sm.png Binary files differnew file mode 100644 index 0000000..16db9f1 --- /dev/null +++ b/docs/_esnet/static/logo-esnet-ball-sm.png diff --git a/docs/_esnet/static/logo-esnet-ball.png b/docs/_esnet/static/logo-esnet-ball.png Binary files differnew file mode 100644 index 0000000..16db9f1 --- /dev/null +++ b/docs/_esnet/static/logo-esnet-ball.png diff --git a/docs/_esnet/static/logo-esnet-name.png b/docs/_esnet/static/logo-esnet-name.png Binary files differnew file mode 100644 index 0000000..f9ec806 --- /dev/null +++ b/docs/_esnet/static/logo-esnet-name.png diff --git a/docs/_esnet/static/logo-esnet.png b/docs/_esnet/static/logo-esnet.png Binary files differnew file mode 100644 index 0000000..78b2497 --- /dev/null +++ b/docs/_esnet/static/logo-esnet.png diff --git a/docs/_esnet/templates/layout.html b/docs/_esnet/templates/layout.html new file mode 100644 index 0000000..694ecb3 --- /dev/null +++ b/docs/_esnet/templates/layout.html @@ -0,0 +1,134 @@ +{% extends "basic/layout.html" %} + +{% set theme_css_files = [] %} +{% if theme_bootstrap_version == "3" %} + {% set bootstrap_version, bootstrap_additional_css, navbar_version = "3.3.6", "theme", "" %} + {% set bs_span_prefix = "col-md-" %} +{% else %} + {% set bootstrap_version, bootstrap_additional_css, navbar_version = "2.3.2", "responsive", "-2" %} + {% set bs_span_prefix = "span" %} +{% endif %} + +{% set theme_css_files = theme_css_files + [ + '_static/bootstrap-' + bootstrap_version + '/css/bootstrap.min.css', + '_static/bootstrap-sphinx.css', + '_static/esnet/esnet.css' + ] +%} + +{% if not bootswatch_css_custom %} + {% set bootswatch_css_custom = [] %} +{% endif %} +{% set css_files = css_files + theme_css_files + bootswatch_css_custom %} + +{% set script_files = script_files + [ + '_static/js/jquery-1.11.0.min.js', + '_static/js/jquery-fix.js', + '_static/bootstrap-' + bootstrap_version + '/js/bootstrap.min.js', + '_static/bootstrap-sphinx.js' + ] +%} + +{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and sidebars %} +{# set render_sidebar = True %} +{%- set sidebars = ['localtoc.html', 'sourcelink.html', 'searchbox.html'] #} +{%- set bs_content_width = render_sidebar and "9" or "9"%} + +{%- block doctype -%} +<!DOCTYPE html> +{%- endblock %} + +{# Sidebar: Rework into our Bootstrap nav section. #} +{% macro navBar() %} +{% include "navbar" + navbar_version + ".html" %} +{% endmacro %} + +{% if theme_bootstrap_version == "3" %} + {%- macro bsidebar() %} + {%- if render_sidebar %} + <div class="{{ bs_span_prefix }}3"> + <div id="sidebar" class="bs-sidenav" role="complementary"> + {%- for sidebartemplate in sidebars %} + {%- include sidebartemplate %} + {%- endfor %} + </div> + </div> + {%- else %} + <div class="{{ bs_span_prefix }}1"></div> + {%- endif %} + {%- endmacro %} +{% else %} + {%- macro bsidebar() %} + {%- if render_sidebar %} + <div class="{{ bs_span_prefix }}3"> + <div id="sidebar" class="bs-sidenav well" data-spy="affix"> + {%- for sidebartemplate in sidebars %} + {%- include sidebartemplate %} + {%- endfor %} + </div> + </div> + {%- endif %} + {%- endmacro %} +{% endif %} + +{%- block extrahead %} +<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"> +{% endblock %} + +{# Silence the sidebar's, relbar's #} +{% block header %}{% endblock %} +{% block relbar1 %}{% endblock %} +{% block relbar2 %}{% endblock %} +{% block sidebarsourcelink %}{% endblock %} + +{%- block content %} +{{ navBar() }} +<div class="container"> + <div class="row"> + {%- block sidebar1 %}{{ bsidebar() }}{% endblock %} + <div class="{{ bs_span_prefix }}{{ bs_content_width }}"> + {% block body %}{% endblock %} + </div> + {% block sidebar2 %} {# possible location for sidebar #} {% endblock %} + </div> +</div> +{%- endblock %} + +{%- block footer %} +<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> + {% if theme_source_link_position == "footer" %} + <br/> + {% include "sourcelink.html" %} + {% endif %} + </p> + <p> + {%- if show_copyright %} + {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/> + {%- else %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %}<br/> + {%- endif %} + {%- endif %} + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/> + {%- endif %} + {%- if show_sphinx %} + {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}<br/> + {%- endif %} + </p> + </div> + </div> + </div> +</footer> +{%- endblock %} diff --git a/docs/_esnet/templates/navbar.html b/docs/_esnet/templates/navbar.html new file mode 100644 index 0000000..d458cf2 --- /dev/null +++ b/docs/_esnet/templates/navbar.html @@ -0,0 +1,49 @@ + <div id="navbar" class="{{ theme_navbar_class }} navbar-default {% if theme_navbar_fixed_top == 'true' -%} navbar-fixed-top{%- endif -%}"> + <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="{{ pathto(master_doc) }}"> + {%- block sidebarlogo %} + {%- if logo %}<img src="{{ pathto('_static/' + logo, 1) }}">{%- endif %} + {%- endblock %} + {% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%} + </a> + </div> + + <div class="collapse navbar-collapse nav-collapse"> + <ul class="nav navbar-nav"> + {% block navbartoc %} + {% include "globaltoc.html" %} + {% if theme_navbar_pagenav %} + {% include "navbartoc.html" %} + {% endif %} + {% endblock %} + {% if theme_navbar_sidebarrel %} + {% block sidebarrel %} + {% include "relations.html" %} + {% endblock %} + {% endif %} + <li class="divider-vertical"></li> + {% if theme_navbar_links %} + {%- for link in theme_navbar_links %} + <li><a href="{{ pathto(*link[1:]) }}">{{ link[0] }}</a></li> + {%- endfor %} + {% endif %} + <li><a href="{{ github_url }}"><img src="_static/icon-github.png" height="20" width="20"></a></li> + {% block navbarextra %} + {% endblock %} + {% if theme_source_link_position == "nav" %} + <li class="hidden-sm">{% include "sourcelink.html" %}</li> + {% endif %} + </ul> + {% block navbarsearch %} + {% include "navbarsearchbox.html" %} + {% endblock %} + </div> + </div> + </div> diff --git a/docs/_esnet/templates/relations.html b/docs/_esnet/templates/relations.html new file mode 100644 index 0000000..e85b69c --- /dev/null +++ b/docs/_esnet/templates/relations.html @@ -0,0 +1,21 @@ +{# Switch to icon instead of text in `sm` view size for BS3 only. #} +{%- if prev %} + <li> + <a href="{{ prev.link|e }}" title="{{ _('Previous Chapter: ') + prev.title|striptags }}"> + <span class="glyphicon glyphicon-chevron-left"></span> + <span class="hidden-sm"> + {{ prev.title|striptags|truncate(length=16, killwords=True) }} + </span> + </a> + </li> +{%- endif %} +{%- if next %} + <li> + <a href="{{ next.link|e }}" title="{{ _('Next Chapter: ') + next.title|striptags }}"> + <span class="hidden-sm"> + {{ next.title|striptags|truncate(length=16, killwords=True) }} + </span> + <span class="glyphicon glyphicon-chevron-right"></span> + </a> + </li> +{%- endif %} diff --git a/docs/building.rst b/docs/building.rst new file mode 100644 index 0000000..9494d00 --- /dev/null +++ b/docs/building.rst @@ -0,0 +1,26 @@ +Building iperf3 +=============== + +Building iperf3, as with most tools of this type, is a fairly +straightforward operation. The instructions in this section assume +that the source distribution has already been unpacked. + +Prerequisites +------------- + +iperf3 requires few (if any) dependencies on common operating +systems. The only known prerequisites are listed here. + +Building +-------- + +In many cases, iperf3 can be built and installed as follows: + +``./configure && make && make install`` + +In some cases, configuration might fail. If this happens, it might +help to run ``./bootstrap.sh`` first from the top-level directory. + +By default, the ``libiperf`` library is built in both shared and +static forms. Either can be suppressed by using the +``--disabled-shared`` or ``--disable-static`` configure-time options. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..b03fcbd --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,274 @@ +# -*- coding: utf-8 -*- +# +# iperf documentation build configuration file, created by +# sphinx-quickstart on Fri Mar 28 14:58:40 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import sphinx_bootstrap_theme + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_esnet/templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'iperf3' +copyright = u'2014-2023, ESnet' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '3.15' +# The full version, including alpha/beta/rc tags. + +release = '3.15' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build', '_esnet'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'bootstrap' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + "navbar_pagenav": False, + "nosidebar": False, + "navbar_class": "navbar", + "navbar_site_name": "Section", + "navbar_links": [ + ("Index", "genindex"), + ("ESnet", "https://www.es.net", True), + ], +} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "_static/esnet/ESnet_Final_Logos_All_Blue_Circle_Stamp_RGB.png" + + + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = "_esnet/static/favicon.ico" +html_context = { + "github_url": "https://github.com/esnet/iperf", +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static/esnet'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +html_sidebars = {'index': None, 'search': None, '*': ['localtoc.html']} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'iperfdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'iperf.tex', u'iperf Documentation', + u'ESnet', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'iperf', u'iperf Documentation', + [u'ESnet'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'iperf', u'iperf Documentation', + u'ESnet', 'iperf', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/dev.rst b/docs/dev.rst new file mode 100644 index 0000000..c65524b --- /dev/null +++ b/docs/dev.rst @@ -0,0 +1,247 @@ +iperf3 Development +================== + +The iperf3 project is hosted on GitHub at: + +http://github.com/esnet/iperf + +This site includes the source code repository, issue tracker, and +wiki. + +Mailing Lists +------------- + +The developer list for iperf3 is: iperf-dev@googlegroups.com. +Information on joining the mailing list can be found at: + +http://groups.google.com/group/iperf-dev + +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. + +Bug Reports +----------- + +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 :doc:`faq`. +Then submit to the iperf3 issue tracker on GitHub: + +https://github.com/esnet/iperf/issues + +For reporting potential security issues, please contact the developers at +iperf@es.net. + +**Note:** 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. + +Changes from iperf 2.x +---------------------- + +New options (not necessarily complete, please refer to the manual page +for a complete list of iperf3 options):: + + -V, --verbose more detailed output than before + -J, --json output in JSON format + -Z, --zerocopy use a 'zero copy' sendfile() method of sending data + -O, --omit N omit the first n seconds (to ignore slowstart) + -T, --title str prefix every output line with this string + -F, --file name xmit/recv the specified file + -A, --affinity n/n,m set CPU affinity (Linux and FreeBSD only) + -k, --blockcount #[KMG] number of blocks (packets) to transmit (instead + of -t or -n) + -L, --flowlabel set IPv6 flow label (Linux only) + +Changed flags:: + + -C, --linux-congestion set congestion control algorithm (Linux only) + (-Z in iperf2) + + +Deprecated flags (currently no plans to support):: + + -d, --dualtest Do a bidirectional test simultaneously + -r, --tradeoff Do a bidirectional test individually + -T, --ttl time-to-live, for multicast (default 1) + -x, --reportexclude [CDMSV] exclude C(connection) D(data) M(multicast) + S(settings) V(server) reports + -y, --reportstyle C report as a Comma-Separated Values + +Also deprecated is the ability to set the options via environment +variables. + +Known Issues +------------ + +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: + +* The ``-Z`` flag sometimes causes the iperf3 client to hang on OSX. + (Issue #129) + +* When specifying the TCP buffer size using the ``-w`` flag on Linux, + the Linux kernel automatically doubles the value passed in to + compensate for overheads. (This can be observed by using + iperf3's ``--debug`` 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. + +* Although the ``-w`` 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. + +* On some platforms (observed on at least one version of Ubuntu + Linux), it might be necessary to invoke ``ldconfig`` manually after + doing a ``make install`` before the ``iperf3`` executable can find + its shared library. (Issue #153) + +* 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) + +* 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) + +There are, of course, many other open and closed issues in the issue +tracker. + +Versioning +---------- + +iperf3 version numbers use (roughly) a `Semantic Versioning +<http://semver.org/>`_ scheme, in which version numbers consist of +three parts: *MAJOR.MINOR.PATCH* + +The developers increment the: + +* *MAJOR* version when making incompatible API changes, + +* *MINOR* version when adding functionality in a backwards-compatible manner, and + +* *PATCH* version when making backwards-compatible bug fixes. + +Release Engineering Checklist +----------------------------- + +1. Update the ``README.md`` and ``RELNOTES.md`` files to be accurate. Make sure + that the "Known Issues" section of the ``README.md`` file and in this document + are up to date. + +2. 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. + +3. Preferably starting from a clean source tree (be sure that ``git + status`` emits no output), make the changes necessary to produce + the new version, such as bumping version numbers:: + + 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 + + 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. + + The result will be a release artifact that should be used for + pre-testing. + +4. Stage the tarball (and a file containing the SHA256 hash) to the + download site. Currently this is located on ``downloads.es.net``. + +5. 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. + +6. Also verify (with file(1)) that the tarball is actually a gzipped + tarball. + +7. For extra points, actually try downloading, compiling, and + smoke-testing the results of the tarball on all supported + platforms. + +8. Plug the SHA256 checksum into the release announcement. + +9. PGP-sign the release announcement text using ``gpg --clearsign``. + 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. + +10. 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:: + + git push # Push version changes + git push --tags # Push the new tag to the GitHub repo + +11. 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. + + * iperf-dev@googlegroups.com + + * iperf-users@lists.sourceforge.net + + * perfsonar-user@internet2.edu + + * perfsonar-developer@internet2.edu + + 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. + +12. Update GitHub Releases with the current release notes. + +13. Update the iperf3 Project News section of the documentation site + to announce the new release (see ``docs/news.rst`` and + ``docs/conf.py`` in the source tree) and deploy a new build of the + documentation to GitHub Pages. + +14. 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 ``invoking.rst``:: + + TERM= + export TERM + nroff -Tascii -c -man src/iperf3.1 | ul | sed 's/^/ /' > iperf3.txt + +Code Authors +------------ + +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. + +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. diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000..7b70026 --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,254 @@ +.. _faq: + +iperf3 FAQ +========== + +What is the history of iperf3, and what is the difference between iperf2 and iperf3? + iperf2 was orphaned in the late 2000s at version 2.0.5, despite some + known bugs and issues. After spending some time trying to fix + iperf2's problems, ESnet decided by 2010 that a new, simpler tool + was needed, and began development of iperf3. The goal was make the + tool as simple as possible, so others could contribute to the code + base. For this reason, it was decided to make the tool single + threaded, and not worry about backwards compatibility with + iperf2. Many of the feature requests for iperf3 came from the + perfSONAR project (http://www.perfsonar.net). + + Then in 2014, Bob (Robert) McMahon from Broadcom restarted + development of iperf2 (See + https://sourceforge.net/projects/iperf2/). He fixed many of the + problems with iperf2, and added a number of new features similar to + iperf3. iperf2.0.8, released in 2015, made iperf2 a useful tool. iperf2's + current development is focused is on using UDP for latency testing, as well + as broad platform support. + + As of this writing (2017), both iperf2 and iperf3 are being actively + (although independently) developed. We recommend being familiar with + both tools, and use whichever tool’s features best match your needs. + + A feature comparison of iperf2, iperf3, and nuttcp is available at: + https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/throughput-tool-comparision/ + +iperf3 parallel stream performance is much less than iperf2. Why? + iperf3 is single threaded, and iperf2 is multi-threaded. We + recommend using iperf2 for parallel streams. + If you want to use multiple iperf3 streams use the method described `here <https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/multi-stream-iperf3/>`_. + +I’m trying to use iperf3 on Windows, but having trouble. What should I do? + iperf3 is not officially supported on Windows, but iperf2 is. We + recommend you use iperf2. + + Some people are using Cygwin to run iperf3 in Windows, but not all + options will work. Some community-provided binaries of iperf3 for + Windows exist. + +How can I build a statically-linked executable of iperf3? + There are a number of reasons for building an iperf3 executable with + no dependencies on any shared libraries. Unfortunately this isn't + quite a straight-forward process. + + The steps below have nominally been tested on CentOS 7.4, but + can probably be adapted for use with other Linux distributions: + + #. If necessary, install the static C libraries; for CentOS this is + the ``glibc-static`` package. + + #. If OpenSSL is installed, be sure that its static libraries are + also installed, from the ``openssl-static`` package. + + #. Be sure that ``lksctp-*`` packages are not installed, because + as of this writing, there do not appear to be any static + libraries available for SCTP. + + #. Configure iperf3 thusly: ``configure "LDFLAGS=--static" + --disable-shared`` These options are necessary to disable the + generation of shared libraries and link the executable + statically. For iperf-3.8 or later, configuring as ``configure + --enable-static-bin`` is another, shorter way to accomplish + this. If SCTP is installed on the system it might also be + necessary to pass the ``--without-sctp`` flag at configure + time. + + #. Compile as normal. + + It appears that for FreeBSD (tested on FreeBSD 11.1-RELEASE), only + the last two steps are needed to produce a static executable. + +How can I build on a system that doesn't support profiled executables? + This problem has been noted by users attempting to build iperf3 for + Android systems, as well as some recent versions of macOS. + There are several workarounds. In order from least + effort to most effort: + + #. Beginning with iperf-3.8, profiled executables are actually not + built by default, so this question becomes somewhat moot. Pass + the ``--enable-profiling`` flag to ``configure`` to build + profiled executables. + + #. In iperf-3.6 and iperf-3.7, the ``--disable-profiling`` flag can be + passed to ``configure`` to disable the building of profiled + object files and the profiled executable. + + #. At the time the linking of the iperf3 profiled executable fails, + the "normal" iperf3 executable is probably already created. So if + you are willing to accept the error exit from the make process + (and a little bit of wasted work on the build host), you might + not need to do anything. + + #. After the configure step, there will be a definition in + ``src/Makefile`` that looks like this:: + + noinst_PROGRAMS = t_timer$(EXEEXT) t_units$(EXEEXT) t_uuid$(EXEEXT) \ + iperf3_profile$(EXEEXT) + + If you edit it to look like this, it will disable the build of the profiled iperf3:: + + noinst_PROGRAMS = t_timer$(EXEEXT) t_units$(EXEEXT) t_uuid$(EXEEXT) + + #. Similar to item 2 above, but more permanent...if you edit + ``src/Makefile.am`` and change the line reading like this:: + + noinst_PROGRAMS = t_timer t_units t_uuid iperf3_profile + + To look like this:: + + noinst_PROGRAMS = t_timer t_units t_uuid + + And then run ``./bootstrap.sh``, that will regenerate the project + Makefiles to make the exclusion of the profiled iperf3 executable + permanent (within that source tree). + +I'm seeing quite a bit of unexpected UDP loss. Why? + First, confirm you are using iperf 3.1.5 or higher. There was an + issue with the default UDP send size that was fixed in + 3.1.5. Second, try adding the flag ``-w2M`` to increase the socket + buffer sizes. That seems to make a big difference on some hosts. + +iperf3 UDP does not seem to work at bandwidths less than 100Kbps. Why? + You'll need to reduce the default packet length to get UDP rates of less that 100Kbps. Try ``-l100``. + +TCP throughput drops to (almost) zero during a test, what's going on? + A drop in throughput to almost zero, except maybe for the first + reported interval(s), may be related to problems in NIC TCP Offload, + which is used to offload TCP functionality to the NIC (see + https://en.wikipedia.org/wiki/TCP_offload_engine). The goal of TCP + Offload is to save main CPU performance, mainly in the areas of + segmentation and reassembly of large packets and checksum + computation. + + When TCP packets are sent with the "Don't Fragment" flag set, which + is the recommended setting, segmentation is done by the TCP stack + based on the reported next hop MSS in the ICMP Fragmentation Needed + message. With TCP Offload, active segmentation is done by the NIC on + the sending side, which is known as TCP Segmentation offload (TSO) + or in Windows as Large Send Offload (LSO). It seems that there are + TSO/LSO implementations which for some reason ignore the reported + MSS and therefore don’t perform segmentation. In these cases, when + large packets are sent, e.g. the default iperf3 128KB (131,072 + bytes), iperf3 will show that data was sent in the first interval, + but since the packets don’t get to the server, no ack is received + and therefore no data is sent in the following intervals. It may + happen that after certain timeout the main CPU will re-send the + packet by re-segmenting it, and in these cases data will get to the + server after a while. However, it seems that segmentation is not + automatically continued with the next packet, so the data transfer + rate be very low. + + The recommended solution in such a case is to disable TSO/LSO, at + least on the relevant port. See for example: + https://atomicit.ca/kb/articles/slow-network-speed-windows-10/. If + that doesn’t help then "Don't Fragment" TCP flag may be + disabled. See for example: + https://support.microsoft.com/en-us/help/900926/recommended-tcp-ip-settings-for-wan-links-with-a-mtu-size-of-less-than. However, + note that disabling the “Don’t Fragment” flag may cause other + issues. + + To test whether TSO/LSO may be the problem, do the following: + + * If different machine configurations are used for the client and + server, try the iperf3 reverse mode (``-R``). If TSO/LSO is only + enabled on the client machine, this test should succeed. + * Reduce the sending length to a small value that should not require + segmentation, using the iperf3 ``-l`` option, e.g. ``-l 512``. It + may also help to reduce the MTU by using the iperf3 ``-M`` option, + e.g. ``-M 1460``. + * Using tools like Wireshark, identify the required MSS in the ICMP + Fragmentation Needed messages (if reported). Run tests with the + ``-l`` value set to 2 times the MSS and then 4 times, 6 times, + etc. With TSO/LSO issue in each test the throughput should be + reduced more. It may help to increase the testing time beyond the + default 10 seconds to better see the behavior (iperf3 ``-t`` + option). + +What congestion control algorithms are supported? + On Linux, run this command to see the available congestion control + algorithms (note that some algorithms are packaged as kernel + modules, which must be loaded before they can be used):: + + /sbin/sysctl net.ipv4.tcp_available_congestion_control + + On FreeBSD, the equivalent command is:: + + /sbin/sysctl net.inet.tcp.cc.available + +I’m using the ``--logfile`` option. How do I see file output in real time? + Use the ``--forceflush`` flag. + +I'm using the --fq-rate flag, but it does not seem to be working. Why? + You need to add 'net.core.default_qdisc = fq' to /etc/sysctl.conf for that option to work. + +I'm having trouble getting iperf3 to work on Windows, Android, etc. Where can I get help? + iperf3 only supports Linux, FreeBSD, and OSX. For other platforms we recommend using iperf2. + +I managed to get a Windows executable built, but why do I get a BSOD on Windows 7? + There seems to be a bug in Windows 7 where running iperf3 from a + network filesystem can cause a system crash (in other words Blue + Screen of Death, or BSOD). This is a Windows bug addressed in kb2839149: + + https://support.microsoft.com/en-us/help/2839149/stop-error-0x00000027-in-the-rdbss-sys-process-in-windows-7-or-windows + + A hotfix is available under kb2732673: + + https://support.microsoft.com/en-us/help/2732673/-delayed-write-failed-error-message-when--pst-files-are-stored-on-a-ne + +Why can’t I run a UDP client with no server? + This is potentially dangerous, and an attacker could use this for a + denial of service attack. We don't want iperf3 to be an attack tool. + +I'm trying to use iperf3 to test a 40G/100G link...What do I need to know? + See the following pages on fasterdata.es.net: + + - https://fasterdata.es.net/host-tuning/100g-tuning/ + - https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/multi-stream-iperf3/ + +My receiver didn't get all the bytes that got sent but there was no loss. Huh? + iperf3 uses a control connection between the client and server to + manage the start and end of each test. Sometimes the commands on + the control connection can be received and acted upon before all of + the test data has been processed. Thus the test ends with data + still in flight. This effect can be significant for short (a few + seconds) tests, but is probably negligible for longer tests. + +A file sent using the ``-F`` option got corrupted...what happened? + The ``-F`` option to iperf3 is not a file transfer utility. It's a + way of testing the end-to-end performance of a file transfer, + including filesystem and disk overheads. So while the test will + mimic an actual file transfer, the data stored to disk may not be + the same as what was sent. In particular, the file size will be + rounded up to the next larger multiple of the transfer block size, + and for UDP tests, iperf's metadata (containing timestamps and + sequence numbers) will overwrite the start of every UDP packet + payload. + +I have a question regarding iperf3...what's the best way to get help? + Searching on the Internet is a good first step. + http://stackoverflow.com/ has a number of iperf3-related questions + and answers, but a simple query into your favorite search engine can + also yield some results. + + There is a mailing list nominally used for iperf3 development, + iperf-dev@googlegroups.com. + + We discourage the use of the iperf3 issue tracker on GitHub for + support questions. Actual bug reports, enhancement requests, or + pull requests are encouraged, however. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..0f4b4c6 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,70 @@ +.. iperf documentation master file, created by + sphinx-quickstart on Fri Mar 28 14:58:40 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +iperf3 +====== + +The iperf series of tools perform active measurements to determine the +maximum achievable bandwidth on IP networks. It supports tuning of +various parameters related to timing, protocols, and buffers. For +each test it reports the measured throughput, loss, and other +parameters. + +This version, sometimes referred to as iperf3, is a redesign of an +original version developed at NLANR / DAST. iperf3 is a new +implementation from scratch, with the goal of a smaller, simpler code +base, and a library version of the functionality that can be used in +other programs. iperf3 also incorporates a number of features found in +other tools such as nuttcp and netperf, but were missing from the +original iperf. These include, for example, a zero-copy mode and +optional JSON output. Note that iperf3 is *not* backwards compatible +with the original iperf. + +Primary development for iperf3 takes place on CentOS Linux, FreeBSD, +and macOS. At this time, these are the only officially +supported platforms, however there have been some reports of success +with OpenBSD, Android, and other Linux distributions. + +iperf3 is principally developed by `ESnet <http://www.es.net/>`_ / +`Lawrence Berkeley National Laboratory <http://www.lbl.gov/>`_. It +is released under a three-clause BSD license. + +iperf2 is no longer being developed by its original maintainers. +However, beginning in 2014, another developer began fixing bugs and +enhancing functionality, and generating releases of iperf2. Both +projects (as of late 2017) are currently being developed actively, but +independently. More information can be found in the :ref:`faq`. + +Links for the Impatient +----------------------- + +Project homepage and documentation hosted on GitHub Pages: +https://software.es.net/iperf/ + +Project site (source code repository, issue tracker) hosted on GitHub: +https://github.com/esnet/iperf + +Source code downloads: +https://downloads.es.net/pub/iperf/ + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + news + obtaining + building + invoking + dev + faq + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/invoking.rst b/docs/invoking.rst new file mode 100644 index 0000000..5b09463 --- /dev/null +++ b/docs/invoking.rst @@ -0,0 +1,518 @@ +Invoking iperf3 +=============== + +iperf3 includes a manual page listing all of the command-line options. +The manual page is the most up-to-date reference to the various flags and parameters. + +For sample command line usage, see: + +https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/ + +Using the default options, iperf3 is meant to show typical well +designed application performance. "Typical well designed application" +means avoiding artificial enhancements that work only for testing +(such as ``splice()``-ing the data to ``/dev/null``). iperf3 does +also have flags for "extreme best case" optimizations but they must be +explicitly activated. These flags include the ``-Z`` (``--zerocopy``) +and ``-A`` (``--affinity``) options. + +iperf3 Manual Page +------------------ + +This section contains a plaintext rendering of the iperf3 manual page. +It is presented here only for convenience; the text here might not +correspond to the current version of iperf3. The authoritative iperf3 +manual page is included in the source tree and installed along with +the executable. + +:: + + IPERF3(1) User Manuals IPERF3(1) + + + + NAME + iperf3 - perform network throughput tests + + SYNOPSIS + iperf3 -s [ options ] + iperf3 -c server [ options ] + + + DESCRIPTION + iperf3 is a tool for performing network throughput measurements. It + can test TCP, UDP, or SCTP throughput. To perform an iperf3 test the + user must establish both a server and a client. + + The iperf3 executable contains both client and server functionality. + An iperf3 server can be started using either of the -s or --server com- + mand-line parameters, for example: + + iperf3 -s + + iperf3 --server + + Note that many iperf3 parameters have both short (-s) and long + (--server) forms. In this section we will generally use the short form + of command-line flags, unless only the long form of a flag is avail- + able. + + By default, the iperf3 server listens on TCP port 5201 for connections + from an iperf3 client. A custom port can be specified by using the -p + flag, for example: + + iperf3 -s -p 5002 + + After the server is started, it will listen for connections from iperf3 + clients (in other words, the iperf3 program run in client mode). The + client mode can be started using the -c command-line option, which also + requires a host to which iperf3 should connect. The host can by speci- + fied by hostname, IPv4 literal, or IPv6 literal: + + iperf3 -c iperf3.example.com + + iperf3 -c 192.0.2.1 + + iperf3 -c 2001:db8::1 + + If the iperf3 server is running on a non-default TCP port, that port + number needs to be specified on the client as well: + + iperf3 -c iperf3.example.com -p 5002 + + The initial TCP connection is used to exchange test parameters, control + the start and end of the test, and to exchange test results. This is + sometimes referred to as the "control connection". The actual test + data is sent over a separate TCP connection, as a separate flow of UDP + packets, or as an independent SCTP connection, depending on what proto- + col was specified by the client. + + Normally, the test data is sent from the client to the server, and mea- + sures the upload speed of the client. Measuring the download speed + from the server can be done by specifying the -R flag on the client. + This causes data to be sent from the server to the client. + + iperf3 -c iperf3.example.com -p 5202 -R + + Results are displayed on both the client and server. There will be at + least one line of output per measurement interval (by default a mea- + surement interval lasts for one second, but this can be changed by the + -i option). Each line of output includes (at least) the time since the + start of the test, amount of data transferred during the interval, and + the average bitrate over that interval. Note that the values for each + measurement interval are taken from the point of view of the endpoint + process emitting that output (in other words, the output on the client + shows the measurement interval data for the client. + + At the end of the test is a set of statistics that shows (at least as + much as possible) a summary of the test as seen by both the sender and + the receiver, with lines tagged accordingly. Recall that by default + the client is the sender and the server is the receiver, although as + indicated above, use of the -R flag will reverse these roles. + + The client can be made to retrieve the server-side output for a given + test by specifying the --get-server-output flag. + + Either the client or the server can produce its output in a JSON struc- + ture, useful for integration with other programs, by passing it the -J + flag. Because the contents of the JSON structure are only completely + known after the test has finished, no JSON output will be emitted until + the end of the test. + + iperf3 has a (overly) large set of command-line options that can be + used to set the parameters of a test. They are given in the "GENERAL + OPTIONS" section of the manual page below, as well as summarized in + iperf3's help output, which can be viewed by running iperf3 with the -h + flag. + + GENERAL OPTIONS + -p, --port n + set server port to listen on/connect to to n (default 5201) + + -f, --format + [kmgtKMGT] format to report: Kbits/Mbits/Gbits/Tbits + + -i, --interval n + pause n seconds between periodic throughput reports; default is + 1, use 0 to disable + + -I, --pidfile file + write a file with the process ID, most useful when running as a + daemon. + + -F, --file name + Use a file as the source (on the sender) or sink (on the + receiver) of data, rather than just generating random data or + throwing it away. This feature is used for finding whether or + not the storage subsystem is the bottleneck for file transfers. + It does not turn iperf3 into a file transfer tool. The length, + attributes, and in some cases contents of the received file may + not match those of the original file. + + -A, --affinity n/n,m + Set the CPU affinity, if possible (Linux, FreeBSD, and Windows + only). On both the client and server you can set the local + affinity by using the n form of this argument (where n is a CPU + number). In addition, on the client side you can override the + server's affinity for just that one test, using the n,m form of + argument. Note that when using this feature, a process will + only be bound to a single CPU (as opposed to a set containing + potentially multiple CPUs). + + -B, --bind host[%dev] + bind to the specific interface associated with address host. If + an optional interface is specified, it is treated as a shortcut + for --bind-dev dev. Note that a percent sign and interface + device name are required for IPv6 link-local address literals. + + --bind-dev dev + bind to the specified network interface. This option uses + SO_BINDTODEVICE, and may require root permissions. (Available + on Linux and possibly other systems.) + + -V, --verbose + give more detailed output + + -J, --json + output in JSON format + + --logfile file + send output to a log file. + + --forceflush + force flushing output at every interval. Used to avoid buffer- + ing when sending output to pipe. + + --timestamps[=format] + prepend a timestamp at the start of each output line. By + default, timestamps have the format emitted by ctime(1). + Optionally, = followed by a format specification can be passed + to customize the timestamps, see strftime(3). If this optional + format is given, the = must immediately follow the --timestamps + option with no whitespace intervening. + + --rcv-timeout # + set idle timeout for receiving data during active tests. The + receiver will halt a test if no data is received from the sender + for this number of ms (default to 12000 ms, or 2 minutes). + + --snd-timeout # + set timeout for unacknowledged TCP data (on both test and con- + trol connections) This option can be used to force a faster test + timeout in case of a network partition during a test. The + required parameter is specified in ms, and defaults to the sys- + tem settings. This functionality depends on the TCP_USER_TIME- + OUT socket option, and will not work on systems that do not sup- + port it. + + -d, --debug + emit debugging output. Primarily (perhaps exclusively) of use + to developers. + + -v, --version + show version information and quit + + -h, --help + show a help synopsis + + + SERVER SPECIFIC OPTIONS + -s, --server + run in server mode + + -D, --daemon + run the server in background as a daemon + + -1, --one-off + handle one client connection, then exit. If an idle time is + set, the server will exit after that amount of time with no con- + nection. + + --idle-timeout n + restart the server after n seconds in case it gets stuck. In + one-off mode, this is the number of seconds the server will wait + before exiting. + + --server-bitrate-limit n[KMGT] + set a limit on the server side, which will cause a test to abort + if the client specifies a test of more than n bits per second, + or if the average data sent or received by the client (including + all data streams) is greater than n bits per second. The + default limit is zero, which implies no limit. The interval + over which to average the data rate is 5 seconds by default, but + can be specified by adding a '/' and a number to the bitrate + specifier. + + --rsa-private-key-path file + path to the RSA private key (not password-protected) used to + decrypt authentication credentials from the client (if built + with OpenSSL support). + + --authorized-users-path file + path to the configuration file containing authorized users cre- + dentials to run iperf tests (if built with OpenSSL support). + The file is a comma separated list of usernames and password + hashes; more information on the structure of the file can be + found in the EXAMPLES section. + + --time-skew-thresholdsecond seconds + time skew threshold (in seconds) between the server and client + during the authentication process. + + CLIENT SPECIFIC OPTIONS + -c, --client host[%dev] + run in client mode, connecting to the specified server. By + default, a test consists of sending data from the client to the + server, unless the -R flag is specified. If an optional inter- + face is specified, it is treated as a shortcut for --bind-dev + dev. Note that a percent sign and interface device name are + required for IPv6 link-local address literals. + + --sctp use SCTP rather than TCP (FreeBSD and Linux) + + -u, --udp + use UDP rather than TCP + + --connect-timeout n + set timeout for establishing the initial control connection to + the server, in milliseconds. The default behavior is the oper- + ating system's timeout for TCP connection establishment. Pro- + viding a shorter value may speed up detection of a down iperf3 + server. + + -b, --bitrate n[KMGT] + set target bitrate to n bits/sec (default 1 Mbit/sec for UDP, + unlimited for TCP/SCTP). If there are multiple streams (-P + flag), the throughput limit is applied separately to each + stream. You can also add a '/' and a number to the bitrate + specifier. This is called "burst mode". It will send the given + number of packets without pausing, even if that temporarily + exceeds the specified throughput limit. Setting the target + bitrate to 0 will disable bitrate limits (particularly useful + for UDP tests). This throughput limit is implemented internally + inside iperf3, and is available on all platforms. Compare with + the --fq-rate flag. This option replaces the --bandwidth flag, + which is now deprecated but (at least for now) still accepted. + + --pacing-timer n[KMGT] + set pacing timer interval in microseconds (default 1000 + microseconds, or 1 ms). This controls iperf3's internal pacing + timer for the -b/--bitrate option. The timer fires at the + interval set by this parameter. Smaller values of the pacing + timer parameter smooth out the traffic emitted by iperf3, but + potentially at the cost of performance due to more frequent + timer processing. + + --fq-rate n[KMGT] + Set a rate to be used with fair-queueing based socket-level pac- + ing, in bits per second. This pacing (if specified) will be in + addition to any pacing due to iperf3's internal throughput pac- + ing (-b/--bitrate flag), and both can be specified for the same + test. Only available on platforms supporting the SO_MAX_PAC- + ING_RATE socket option (currently only Linux). The default is + no fair-queueing based pacing. + + --no-fq-socket-pacing + This option is deprecated and will be removed. It is equivalent + to specifying --fq-rate=0. + + -t, --time n + time in seconds to transmit for (default 10 secs) + + -n, --bytes n[KMGT] + number of bytes to transmit (instead of -t) + + -k, --blockcount n[KMGT] + number of blocks (packets) to transmit (instead of -t or -n) + + -l, --length n[KMGT] + length of buffer to read or write. For TCP tests, the default + value is 128KB. In the case of UDP, iperf3 tries to dynamically + determine a reasonable sending size based on the path MTU; if + that cannot be determined it uses 1460 bytes as a sending size. + For SCTP tests, the default size is 64KB. + + --cport port + bind data streams to a specific client port (for TCP and UDP + only, default is to use an ephemeral port) + + -P, --parallel n + number of parallel client streams to run. Note that iperf3 is + single threaded, so if you are CPU bound, this will not yield + higher throughput. + + -R, --reverse + reverse the direction of a test, so that the server sends data + to the client + + --bidir + test in both directions (normal and reverse), with both the + client and server sending and receiving data simultaneously + + -w, --window n[KMGT] + set socket buffer size / window size. This value gets sent to + the server and used on that side too; on both sides this option + sets both the sending and receiving socket buffer sizes. This + option can be used to set (indirectly) the maximum TCP window + size. Note that on Linux systems, the effective maximum window + size is approximately double what is specified by this option + (this behavior is not a bug in iperf3 but a "feature" of the + Linux kernel, as documented by tcp(7) and socket(7)). + + -M, --set-mss n + set TCP/SCTP maximum segment size (MTU - 40 bytes) + + -N, --no-delay + set TCP/SCTP no delay, disabling Nagle's Algorithm + + -4, --version4 + only use IPv4 + + -6, --version6 + only use IPv6 + + -S, --tos n + set the IP type of service. The usual prefixes for octal and hex + can be used, i.e. 52, 064 and 0x34 all specify the same value. + + --dscp dscp + set the IP DSCP bits. Both numeric and symbolic values are + accepted. Numeric values can be specified in decimal, octal and + hex (see --tos above). To set both the DSCP bits and the ECN + bits, use --tos. + + -L, --flowlabel n + set the IPv6 flow label (currently only supported on Linux) + + -X, --xbind name + Bind SCTP associations to a specific subset of links using + sctp_bindx(3). The --B flag will be ignored if this flag is + specified. Normally SCTP will include the protocol addresses of + all active links on the local host when setting up an associa- + tion. Specifying at least one --X name will disable this behav- + iour. This flag must be specified for each link to be included + in the association, and is supported for both iperf servers and + clients (the latter are supported by passing the first --X argu- + ment to bind(2)). Hostnames are accepted as arguments and are + resolved using getaddrinfo(3). If the --4 or --6 flags are + specified, names which do not resolve to addresses within the + specified protocol family will be ignored. + + --nstreams n + Set number of SCTP streams. + + -Z, --zerocopy + Use a "zero copy" method of sending data, such as sendfile(2), + instead of the usual write(2). + + -O, --omit n + Perform pre-test for N seconds and omit the pre-test statistics, + to skip past the TCP slow-start period. + + -T, --title str + Prefix every output line with this string. + + --extra-data str + Specify an extra data string field to be included in JSON out- + put. + + -C, --congestion algo + Set the congestion control algorithm (Linux and FreeBSD only). + An older --linux-congestion synonym for this flag is accepted + but is deprecated. + + --get-server-output + Get the output from the server. The output format is determined + by the server (in particular, if the server was invoked with the + --json flag, the output will be in JSON format, otherwise it + will be in human-readable format). If the client is run with + --json, the server output is included in a JSON object; other- + wise it is appended at the bottom of the human-readable output. + + --udp-counters-64bit + Use 64-bit counters in UDP test packets. The use of this option + can help prevent counter overflows during long or high-bitrate + UDP tests. Both client and server need to be running at least + version 3.1 for this option to work. It may become the default + behavior at some point in the future. + + --repeating-payload + Use repeating pattern in payload, instead of random bytes. The + same payload is used in iperf2 (ASCII '0..9' repeating). It + might help to test and reveal problems in networking gear with + hardware compression (including some WiFi access points), where + iperf2 and iperf3 perform differently, just based on payload + entropy. + + --dont-fragment + Set the IPv4 Don't Fragment (DF) bit on outgoing packets. Only + applicable to tests doing UDP over IPv4. + + --username username + username to use for authentication to the iperf server (if built + with OpenSSL support). The password will be prompted for inter- + actively when the test is run. Note, the password to use can + also be specified via the IPERF3_PASSWORD environment variable. + If this variable is present, the password prompt will be + skipped. + + --rsa-public-key-path file + path to the RSA public key used to encrypt authentication cre- + dentials (if built with OpenSSL support) + + + EXAMPLES + Authentication - RSA Keypair + The authentication feature of iperf3 requires an RSA public keypair. + The public key is used to encrypt the authentication token containing + the user credentials, while the private key is used to decrypt the + authentication token. The private key must be in PEM format and addi- + tionally must not have a password set. The public key must be in PEM + format and use SubjectPrefixKeyInfo encoding. An example of a set of + UNIX/Linux commands using OpenSSL to generate a correctly-formed key- + pair follows: + + > openssl genrsa -des3 -out private.pem 2048 + > openssl rsa -in private.pem -outform PEM -pubout -out public.pem + > openssl rsa -in private.pem -out private_not_protected.pem -out- + form PEM + + After these commands, the public key will be contained in the file pub- + lic.pem and the private key will be contained in the file pri- + vate_not_protected.pem. + + Authentication - Authorized users configuration file + A simple plaintext file must be provided to the iperf3 server in order + to specify the authorized user credentials. The file is a simple list + of comma-separated pairs of a username and a corresponding password + hash. The password hash is a SHA256 hash of the string "{$user}$pass- + word". The file can also contain commented lines (starting with the # + character). An example of commands to generate the password hash on a + UNIX/Linux system is given below: + + > S_USER=mario S_PASSWD=rossi + > echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{ print $1 }' + + An example of a password file (with an entry corresponding to the above + username and password) is given below: + > cat credentials.csv + # file format: username,sha256 + mario,bf7a49a846d44b454a5d11e7acfaf13d138bbe0b7483aa3e050879700572709b + + + + AUTHORS + A list of the contributors to iperf3 can be found within the documenta- + tion located at https://software.es.net/iperf/dev.html#authors. + + + SEE ALSO + libiperf(3), https://software.es.net/iperf + + + + ESnet September 2022 IPERF3(1) + + +The iperf3 manual page will typically be installed in manual +section 1. diff --git a/docs/news.rst b/docs/news.rst new file mode 100644 index 0000000..b0bcfac --- /dev/null +++ b/docs/news.rst @@ -0,0 +1,469 @@ +iperf3 Project News +=================== + +2023-09-14: iperf-3.15 released +-------------------------------- +| URL: https://downloads.es.net/pub/iperf/iperf-3.15.tar.gz +| SHA256: ``bdb77c11f72bce90214883159577fa24412013e62b2083cf5f54391d79b1d8ff`` + +iperf 3.15 fixes that could cause an iperf3 server process to hang +waiting for input on the control connection. For more information, +please see: + +https://downloads.es.net/pub/iperf/esnet-secadv-2023-0002.txt.asc + +This version of iperf3 also includes several other minor bug fixes, +which are summarized in the release notes. + +2023-07-07: iperf-3.14 released +-------------------------------- +| URL: https://downloads.es.net/pub/iperf/iperf-3.14.tar.gz +| SHA256: ``723fcc430a027bc6952628fa2a3ac77584a1d0bd328275e573fc9b206c155004`` + +iperf 3.14 fixes a memory allocation hazard that allowed a remote user +to crash an iperf3 process (server or client). + +More information on this specific fix can be found at: + +https://downloads.es.net/pub/iperf/esnet-secadv-2023-0001.txt.asc + +This version of iperf3 also includes a number of minor bug fixes, +which are summarized in the release notes. + +2023-02-16: iperf-3.13 released +---------------------------------- +| URL: https://downloads.es.net/pub/iperf/iperf-3.13.tar.gz +| SHA256: ``bee427aeb13d6a2ee22073f23261f63712d82befaa83ac8cb4db5da4c2bdc865`` + +iperf 3.13 is primarily a bugfix release. + + +2022-09-30: iperf-3.12 released +---------------------------------- +| URL: https://downloads.es.net/pub/iperf/iperf-3.12.tar.gz +| SHA256: ``72034ecfb6a7d6d67e384e19fb6efff3236ca4f7ed4c518d7db649c447e1ffd6`` + +iperf 3.12 is principally a bugfix release, although it includes an +updated version of cJSON and adds a few new features. + + +2022-01-28: iperf-3.11 released +---------------------------------- +| URL: https://downloads.es.net/pub/iperf/iperf-3.11.tar.gz +| SHA256: ``de8cb409fad61a0574f4cb07eb19ce1159707403ac2dc01b5d175e91240b7e5f`` + +iperf 3.11 is principally a bugfix release. Also GitHub +Discussions are now supported. + + +2021-06-02: iperf-3.10.1 released +---------------------------------- + +| URL: https://downloads.es.net/pub/iperf/iperf-3.10.1.tar.gz +| SHA256: ``03bc9760cc54a245191d46bfc8edaf8a4750f0e87abca6764486972044d6715a iperf-3.10.1.tar.gz`` + +iperf 3.10.1 fixes a problem with the configure script that made it +make not work correctly in some circumstances. It is functionally +identical to iperf 3.10. + +2021-05-26: iperf-3.10 released +-------------------------------- + +| URL: https://downloads.es.net/pub/iperf/iperf-3.10.tar.gz +| SHA256: ``4390982928542256c17d6dd1f56eede9092649ebfd8a97c8cecfad12d238ad57 iperf-3.10.tar.gz`` + +iperf 3.10 is principally a bugfix release. A few new features have +been added (``--time-skew-threshold``, ``--bind-dev``, +``--rcv-timeout``, and ``--dont-fragment``). More information on +these new features can be found in the release notes. + +2020-08-17: iperf-3.9 released +--------------------------------- + +| URL: https://downloads.es.net/pub/iperf/iperf-3.9.tar.gz +| SHA256: ``24b63a26382325f759f11d421779a937b63ca1bc17c44587d2fcfedab60ac038 iperf-3.9.tar.gz`` + +iperf 3.9 adds a ``--timestamps`` flag, which prepends a timestamp to +each output line. A new ``--server-bitrate-limit`` flag has been +added as a server command-line argument, and allows an iperf3 server +to enforce a maximum throughput rate. More information on these new +features can be found in the release notes. + +2020-06-10: iperf-3.8.1 released +--------------------------------- + +| URL: https://downloads.es.net/pub/iperf/iperf-3.8.1.tar.gz +| SHA256: ``e5b080f3273a8a715a4100f13826ac2ca31cc7b1315925631b2ecf64957ded96 iperf-3.8.1.tar.gz`` + +iperf 3.8.1 fixes a regression with ``make install`` in iperf 3.8. It +is otherwise identical to iperf 3.8. + +2020-06-08: iperf-3.8 released +------------------------------- + +| URL: https://downloads.es.net/pub/iperf/iperf-3.8.tar.gz +| SHA256: ``edc1c317b0ae31925e5eb84f0295faefbaa1db3229f4693e11d954d114de4bcd iperf-3.8.tar.gz`` + +iperf 3.8 contains minor bugfixes and enhancements. + + +2019-06-21: iperf-3.7 released +------------------------------- + +| URL: https://downloads.es.net/pub/iperf/iperf-3.7.tar.gz +| SHA256: ``d846040224317caf2f75c843d309a950a7db23f9b44b94688ccbe557d6d1710c iperf-3.7.tar.gz`` + +iperf 3.7 adds the ``--bidir`` flag for bidirectional tests, includes +some minor enhancements, and fixes a number of bugs. More details can +be found in the release notes. + +Note: Documentation for the ``--bidir`` flag was inadvertently +omitted from the manual page. This will be fixed in a future +release. + +2018-06-25: iperf-3.6 released +------------------------------- + +| URL: https://downloads.es.net/pub/iperf/iperf-3.6.tar.gz +| SHA256: ``de5d51e46dc460cc590fb4d44f95e7cad54b74fea1eba7d6ebd6f8887d75946e iperf-3.6.tar.gz`` + +iperf 3.6 adds the ``--extra-data`` and ``--repeating-payload`` +options and fixes some minor bugs. + +2018-03-02: iperf-3.5 released +------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.5.tar.gz +| SHA256: ``539bd9ecdca1b8c1157ff85b70ed09b3c75242e69886fc16b54883b399f72cd5 iperf-3.5.tar.gz`` + +iperf 3.5 fixes a bug that could over-count data transfers (and hence +measured bitrate). + +2018-02-14: iperf-3.4 released +------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.4.tar.gz +| SHA256: ``71528332d751df85e046d1944d9a0269773cadd6e51840aecdeed30925f79111 iperf-3.4.tar.gz`` + +iperf 3.4 fixes a number of minor bugs and adds a few enhancements. + +2017-10-31: iperf-3.3 released +------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.3.tar.gz +| SHA256: ``6f596271251056bffc11bbb8f17d4244ad9a7d4a317c2459fdbb853ae51284d8 iperf-3.3.tar.gz`` + +New minor release of iperf 3.3, fixing a number of minor bugs. + +2017-06-26: iperf-3.2 released +------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.2.tar.gz +| SHA256: ``f207b36f861485845dbdf09f909c62f3d2222a3cf3d2682095aede8213cd9c1d iperf-3.2.tar.gz`` + +New minor release of iperf 3.2, with new features, bugfixes, and enhancements. + +2017-06-06: iperf3 update, June 2017 +-------------------------------------- + +https://raw.githubusercontent.com/esnet/iperf/master/docs/2017-06-06.txt + + +2017-04-27: iperf3 update, April 2017 +-------------------------------------- + +https://raw.githubusercontent.com/esnet/iperf/master/docs/2017-04-27.txt + + +2017-03-06: iperf-3.1.7 released +--------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.7.tar.gz +| SHA256: ``a4ef73406fe92250602b8da2ae89ec53211f805df97a1d1d629db5a14043734f iperf-3.1.7.tar.gz`` + +This version of iperf3 contains two documentation fixes, but is +otherwise identical to the prior release. + + +2017-02-02: iperf-3.1.6 released +--------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.6.tar.gz +| SHA256: ``70f0c72d9e60c6ecb2c478ed17e4fd81d3b827d57896fee43bcd0c53abccb29d iperf-3.1.6.tar.gz`` + +This version of iperf3 contains two minor fixes. Notably, one of them +unbreaks JSON output with UDP tests. + + +2017-01-12: iperf-3.1.5 released +--------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.5.tar.gz +| SHA256: ``6e1a6200cd38baeab58ef0d7b8769e7aa6410c3a3168e65ea8277a4de79e5500 iperf-3.1.5.tar.gz`` + +This version of iperf3 makes some improvements to the fair-queue-based +pacing and improves the selection of the default UDP packet size. +Users who use either of these aspects of iperf3 are encourage to +review the release notes for this version. + + +2016-10-31: iperf-3.1.4 released +--------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.4.tar.gz +| SHA256: ``db61d70ac62003ebe0bf15496bd8c4b3c4b728578a44d0a1a88fcf8afc0e8f76 iperf-3.1.4.tar.gz`` + +This release fixes a few minor bugs, including a +(non-security-impacting) buffer overflow fix ported from upstream +cjson. + + +2016-06-08: Security Issue: iperf-3.1.3, iperf-3.0.12 released +---------------------------------------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.3.tar.gz +| SHA256: ``60d8db69b1d74a64d78566c2317c373a85fef691b8d277737ee5d29f448595bf iperf-3.1.3.tar.gz`` + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.12.tar.gz +| SHA256: ``9393d646e4e616f0cd7864bc8ceacc379f5d36b08003a3d8d65cd7c99d15daec iperf-3.0.12.tar.gz`` + +These releases address a security issue that could cause a crash of an +iperf3 process (it could theoretically lead to a remote code +execution). Although the risk for common use cases is believed to be +low, all users are encouraged to update to these versions or newer as +soon as possible. More information on the security vulnerability can +be found in the following ESnet Software Security Advisory: + +https://raw.githubusercontent.com/esnet/security/master/cve-2016-4303/esnet-secadv-2016-0001.txt.asc + +iperf-3.1.3 also includes support for fair-queueing, per-socket based +pacing of tests on platforms that support it (currently recent Linux +distributions), as well as several other fixes. + + +2016-02-01: iperf-3.1.2 released +--------------------------------- + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.2.tar.gz +| SHA256: ``f9dbdb99f869c077d14bc1de78675f5e4b8d1bf78dc92381e96c3eb5b1fd7d86 iperf-3.1.2.tar.gz`` + +This release fixes a couple of minor bugs, including one that results +in invalid JSON being emitted for UDP tests. + +Older News +---------- + +2015-11-19: iperf-3.1.1 released +................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.1.tar.gz +| SHA256: ``62f7c64eafe19046ba974b3ef2d962a5597194d6fbbddde328a15a5e74110564 iperf-3.1.1.tar.gz`` + +This release fixes a few minor bugs. + +2015-10-16: iperf3 Development Status +...................................... + +Beginning with the release of iperf 3.1, ESnet plans to support iperf3 +in "maintenance mode". At this point, we have no definite plans for +further iperf3 releases, and ESnet will be providing a very limited +amount of resources for support and development, going forward. +However, ESnet could issue new iperf3 releases to deal with security +issues or high-impact bug fixes. + +Requests for support, enhancements, and questions should best be +directed to the iperf-dev mailing list. ESnet would be open to adding +project members/committers from the community, in case there are +developers who are interested in doing more active work with iperf3 +and/or supporting the user base. + + +2015-10-16: iperf-3.1 released +............................... + +| URL: http://downloads.es.net/pub/iperf/iperf-3.1.tar.gz +| SHA256: ``4385a32ece25cb09d4606b4c99316356b3d2cb03b318aa056b99cdb91c5ce656 iperf-3.1.tar.gz`` + +This release adds support for SCTP on supported platforms, better +feature detection on FreeBSD, better compatibility with various +platforms, and a number of bug fixes. + + +2015-01-09: iperf-3.0.11 released +.................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.11.tar.gz +| SHA256: ``e01db5be6f47f67c987463095fe4f5b8b9ff891fb92c39104d042ad8fde97f6e iperf-3.0.11.tar.gz`` + +This maintenance release adds a -1 flag to make the iperf3 execute a +single test and exit, needed for an upcoming bwctl release. A few +other bugs are also fixed. + +2014-12-16: iperf-3.0.10 released +.................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.10.tar.gz +| SHA256: ``a113442967cf0981b0b2d538be7c88903b2fb0f87b0d281384e41b462e33059d iperf-3.0.10.tar.gz`` + +This maintenance release fixes building on MacOS X Yosemite, as well +as making the -w option work correctly with UDP tests. + +2014-10-14: iperf-3.0.9 released +................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.9.tar.gz +| SHA256: ``40249a2b30d26b937350b969bcb19f88e1beb356f886ed31422b554bac692459 iperf-3.0.9.tar.gz`` + +This maintenance release fixes an issue for a situation in which +attempting a UDP test with pathologically large (and illegal) packet +sizes could put the iperf3 server in a state where it would stop +accepting connections from clients, thus causing the clients to crash +when interrupted. + + +2014-09-30: iperf-3.0.8 released +................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.8.tar.gz +| SHA256: ``81b8d91159862896c57f9b90a006e8b5dc22bd94175d97bd0db50b0ae2c1a78e iperf-3.0.8.tar.gz`` + +This maintenance release is functionally identical to 3.0.7. It +incorporates updated license verbage and a minor compilation fix. + + +2014-08-28: iperf-3.0.7 released +................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.7.tar.gz +| SHA256: ``49510e886f9e876cd73dcd80414bfb8c49b147c82125585e09c2a6e92369d3f2 iperf-3.0.7.tar.gz`` + +This maintenance release fixes several minor bugs. Of particular +note: + +* A bug that caused some problems with bwctl / perfSONAR has been + fixed. + +* A bug that made it possible to disrupt existing, running tests has + been fixed. + +2014-07-28: iperf-3.0.6 released +................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.6.tar.gz +| SHA256: ``3c5909c9b286b6503ffa141a94cfc588915d6e67f2aa732b08df0af73e21938 iperf-3.0.6.tar.gz`` + +This maintenance release includes the following bug fixes: + +* Several problems with the -B option have been fixed. Also, API + calls have been added to libiperf to extend this functionality to + API clients. + +* Some portability fixes for OpenBSD and Solaris have been merged from + the mainline. + +As always, more details can be found in the ``RELNOTES.md`` file in +the source distribution. + +2014-06-16: Project documentation on GitHub Pages +.................................................. + +iperf3 project documentation can now be found at: + +| URL: http://software.es.net/iperf/ + +This is a GitHub Pages site. In an ongoing series of steps, content +will be migrated from the iperf3 wiki to GitHub Pages. + +2014-06-16: iperf-3.0.5 released +................................. + +| URL: http://downloads.es.net/pub/iperf/iperf-3.0.5.tar.gz +| SHA256: ``e1e1989985b17a4c03b0fa207004ad164b137e37ab0682fecbf5e93bcaa920a6 iperf-3.0.5.tar.gz`` + +This is the third maintenance release of iperf 3, with few more +enhancements and bug fixes. Highlights: + +* A timing issue which caused measurement intervals to be wrong with + TCP tests on lossy networks has been fixed. + +* It is now possible to get (most of) the server-side output at + the client by using the ``--get-server-output`` flag. + +* A number of bugs with ``--json`` output have been fixed. + +A more extensive list of changes can always be found in the +``RELNOTES.md`` file in the source distribution. + +Note: An iperf-3.0.4 release was planned and tagged, but not +officially released. + +2014-06-10: New iperf3 download site +..................................... + +iperf3 downloads are now hosted on a new server at ESnet: + +| URL: http://downloads.es.net/pub/iperf/ + +Going forward, new releases will be made available in this directory. +Older releases will, at least for now, continue to also be available +at the previous location. + +2014-03-26: iperf-3.0.3 released +................................. + +| URL: http://stats.es.net/software/iperf-3.0.3.tar.gz +| SHA256: ``79daf3e5e5c933b2fc4843d6d21c98d741fe39b33ac05bd7a11c50d321a2f59d iperf-3.0.3.tar.gz`` + +This is the second maintenance release of iperf 3.0, containing a few bug fixes and enhancements, notably: + +* The structure of the JSON output is more consistent between the + cases of one stream and multiple streams. + +* The example programs once again build correctly. + +* A possible buffer overflow related to error output has been fixed. + (This is not believed to be exploitable.) + +More information on changes can be found in the ``RELNOTES.md`` +file in the source distribution. + +2014-03-10: iperf-3.0.2 released +................................. + +| URL: http://stats.es.net/software/iperf-3.0.2.tar.gz +| SHA256: ``3c379360bf40e6ac91dfc508cb43fefafb4739c651d9a8d905a30ec99095b282 iperf-3.0.2.tar.gz`` + +**Note:** Due to a mistake in the release process, the distribution tarball referred to above is actually not compressed, despite its ``.tar.gz`` extension. Instead it is an uncompressed tar archive. The file checksum is correct, as are the file contents. + +This version is a maintenance release that +fixes a number of bugs, many reported by users, adds a few minor +enhancements, and tracks the migration of the iperf3 project to +GitHub. Of particular interest: + +* Build / runtime fixes for CentOS 5, MacOS 10.9, and FreeBSD. + +* TCP snd_cwnd output on Linux in the default output format. + +* libiperf is now built as both a shared and static library; by + default, the iperf3 binary links to the shared library. + +More information on changes can be found in the ``RELNOTES.md`` +file in the source distribution. + +2014-02-28: iperf migrated to GitHub +..................................... + +The new project page can be found at: + +https://github.com/esnet/iperf + +2014-01-10: iperf-3.0.1 released +................................. + +| URL: http://stats.es.net/software/iperf-3.0.1.tar.gz +| SHA256: ``32b419ef634dd7670328c3cecc158babf7d706bd4b3d248cf95965528a20e614 iperf-3.0.1.tar.gz`` + +During development, there were various distributions of the source +code unofficially released carrying a 3.0.0 version number. Because +of the possibility for confusion, this first public release of iperf3 +was numbered 3.0.1. diff --git a/docs/obtaining.rst b/docs/obtaining.rst new file mode 100644 index 0000000..453e0b3 --- /dev/null +++ b/docs/obtaining.rst @@ -0,0 +1,80 @@ +.. _obtaining: + +Obtaining iperf3 +================ + +Binary Distributions +-------------------- + +Note that ESnet does not distribute binary packages of iperf3. All of +the packages listed in this section are provided by third parties, who +are solely responsible for their contents. This is an incomplete list +of binary packages for various operating systems and distributions: + +* FreeBSD: via the FreeBSD Ports Collection with ``sudo pkg install + benchmarks/iperf3``. +* Fedora / RedHat Linux / CentOS / Rocky: `iperf3 + <https://packages.fedoraproject.org/pkgs/iperf3/iperf3/>`_ and + `iperf3-devel + <https://packages.fedoraproject.org/pkgs/iperf3/iperf3-devel/>`_ in Fedora + 19 and 20 and in Fedora EPEL 5, 6, and 7. iperf3 is included as a + part of RedHat Enterprise Linux 7.4 and later (as well as CentOS 7.4 + and later, and all versions of Rocky Linux), and can generally be + installed with ``yum install iperf3``. +* Ubuntu: `iperf3 <https://launchpad.net/ubuntu/+source/iperf3>`_, + is available in Trusty (backports), and as a part of the main + release in Vivid and newer. It can generally be installed with + ``sudo apt-get install iperf3``. +* macOS: via HomeBrew with ``brew install iperf3`` or MacPorts with + ``sudo port install iperf3``. +* Windows: iperf3 binaries for Windows (built with `Cygwin <https://www.cygwin.com/>`_) can be found in a variety of + locations, including `<https://files.budman.pw/>`_ + (`discussion thread + <https://www.neowin.net/forum/topic/1234695-iperf/>`_). +* Android: iperf3 binaries for Android can be found in several + locations, including `<https://github.com/davidBar-On/android-iperf3/>`_. + +Source Distributions +-------------------- + +Source distributions of iperf are available as compressed (gzip) +tarballs at: + +https://downloads.es.net/pub/iperf/ + +**Note:** Due to a software packaging error, the 3.0.2 release +tarball was not compressed, even though its filename had a ``.tar.gz`` +suffix. + +**Note:** GitHub, which currently hosts the iperf3 project, supports +a "Releases" feature, which can automatically generate ``.zip`` or ``.tar.gz`` +archives, on demand, from tags in the iperf3 source tree. These tags are +created during the release engineering process to mark the exact +version of files making up a release. + +In theory, the ``.tar.gz`` files produced by GitHub contain the same +contents as what are in the official tarballs, note that the tarballs +themselves will be different due to internal timestamps or other +metadata. Therefore these files will *not* match the published SHA256 +checksums and no guarantees can be made about the integrity of the +files. The authors of iperf3 always recommend downloading source +distributions from the the directory above (or a mirror site), and +verifying the SHA256 checksums before using them for any purpose, to +ensure the files have not been tampered with. + +Source Code Repository +---------------------- + +The iperf3 project is hosted on GitHub at: + +https://github.com/esnet/iperf + +The iperf3 source code repository can be checked out directly from +GitHub using: + +``git clone https://github.com/esnet/iperf.git`` + +Primary development for iperf3 takes place on CentOS 7 Linux, FreeBSD 11, +and macOS 10.12. At this time, these are the only officially supported +platforms, however there have been some reports of success with +NetBSD, OpenBSD, Windows, Solaris, Android, and iOS. |
