First pass at new iperf3 documentation, implemented in reStructuredText.

Building and deploying the documentation requires some infrastructure that's not part of this tree.
2014-03-31 11:52:23 -07:00 · 2014-03-31 11:52:23 -07:00 · 14741dcbb4
--- a/.gitignore
+++ b/.gitignore
@ -10,6 +10,7 @@ autom4te.cache
 config/test-driver
 config.log
 config.status
+docs/_build
 libtool
 src/.deps
 src/.libs
--- a/docs/building.rst
+++ b/docs/building.rst
@ -0,0 +1,33 @@
+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 prerequesites are listed here.
+
+* ``libuuid``:  ``libuuid`` is not installed by default on Debian /
+  Ubuntu Linux systems.  To install this, use this command before
+  building iperf3:
+
+  ``apt-get install uuid-dev``
+
+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.
+
--- a/docs/conf.py
+++ b/docs/conf.py
@ -0,0 +1,272 @@
+# -*- 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'iperf'
+copyright = u'2014, 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.0.3'
+# The full version, including alpha/beta/rc tags.
+release = '3.0.3'
+
+# 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 = "_esnet/static/logo-esnet-ball-sm.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']
+
+# 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
--- a/docs/dev.rst
+++ b/docs/dev.rst
@ -0,0 +1,182 @@
+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:  iperf3-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.  Then submit to the
+iperf3 issue tracker on GitHub:
+
+https://github.com/esnet/iperf/issues
+
+**Note:**  Issues submitted to the old iperf3 issue tracker on Google
+Code 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:
+
+* UDP performance: iperf2/iperf3 both only are only about 50% as fast
+  as nuttcp in UDP mode.  We are looking into this, but in the
+  meantime, if you want to get UDP above 5Gbps, we recommend using
+  nuttcp instead (http://www.nuttcp.net/).  (Issue #55)
+
+* Interval reports on high-loss networks: The way iperf3 is currently
+  implemented, the sender write command will block until the entire
+  block has been written. This means that it might take several
+  seconds to send a full block if the network has high loss, and the
+  interval reports will have widely varying interval times. We are
+  trying to determine the best solution to this, but in the meantime,
+  try using a smaller block size if you get strange interval reports.
+  For example, try ``-l 4K``.  (Issue #125)
+
+* The ``-Z`` flag sometimes hangs on OSX.  (Issue #129)
+
+* On OpenBSD, the server seems to require a ``-4`` argument, implying
+  that it can only be used with IPv4.  (Issue #108)
+
+* When specifying the TCP buffer size using the ``-w`` flag on Linux,
+  Linux doubles the value you pass in. (You can see this using
+  iperf3's debug flag.)  But then the CWND does not actually ramp up
+  to the doubled value, but only to about 75% of the doubled
+  value. This appears to be by design.  (Issue #145)
+
+There are, of course, many other open and closed issues in the issue
+tracker.
+
+Versioning
+----------
+
+iperf version numbers use three-part release numbers:  *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.
+
+This is roughly along the line of `Semantic Versioning <http://semver.org/>`_.
+
+Release Engineering Checklist
+-----------------------------
+
+1. Update the ``README`` and ``RELEASE_NOTES`` files to be accurate. Make sure
+   that the "Known Issues" section of the ``README`` file is up to date.
+
+2. Compose a release announcement.  Most of the release announcement
+   can be written before tagging.
+
+3. Starting from a clean source tree (be sure that ``git status`` emits
+   no output)::
+
+    vi src/version.h   # update the strings IPERF_VERSION and IPERF_VERSION_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
+    ./bootstrap.sh     # regenerate configure script, etc.
+    git commit -a
+    git push
+
+    ./make_release tag  # this creates a tag in the local repo that matches the version.h version
+    git push --tags     # Push the new tag to the GitHub repo
+    ./make_release tar  # create tarball and compute SHA256 hash
+
+   Doing the above steps on CentOS 6 (with its somewhat older
+   autotools / libtools suite) is preferred; newer systems generate
+   ``configure`` and ``Makefile`` scripts that tend to rebuild
+   themselves rather frequently.  We might be able to address this
+   problem (and graduate to newer autotools) by using
+   ``AC_MAINTAINER_MODE`` but there's a fair amount of religion
+   associated with this.
+
+4. Stage the tarball (and a file containing the SHA256 hash) to the
+   download site.  Currently this is located on ``stats.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.
+
+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. Send the release announcement (PGP-signed) to these addresses:
+
+   * iperf-dev@googlegroups.com
+
+   * iperf-users@lists.sourceforge.net
+
+   * perfsonar-user@internet2.edu
+
+   * perfsonar-dev@internet2.edu
+
--- a/docs/index.rst
+++ b/docs/index.rst
@ -0,0 +1,62 @@
+.. 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
+======
+
+iperf is a tool for active measurements of 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 bandwidth, 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 X.  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 / Lawrence Berkleley National
+Laboratory.  It is released under a three-clause BSD license.
+
+The iperf3 project is hosted on GitHub at:
+
+https://github.com/esnet/iperf
+
+The GitHub project site includes the source code repository, issue
+tracker.
+
+This documention tree is hosted on GitHub pages at:
+
+https://esnet.github.io/iperf/
+
+For more information on obtaining iperf3, see :ref:`obtaining`.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   news
+   obtaining
+   building
+   invoking
+   dev
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
--- a/docs/invoking.rst
+++ b/docs/invoking.rst
@ -0,0 +1,199 @@
+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: 
+
+http://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf-and-iperf3/
+
+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 authoritative iperf3
+manual page is included in the source tree and installed along with
+the executable.
+
+::
+
+   IPERF(1)                         User Manuals                         IPERF(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 either TCP or UDP throughput.  To perform an iperf3  test  the
+   user must establish both a server and a client.
+
+
+   GENERAL OPTIONS
+   ‐p, ‐‐port n
+   set server port to listen on/connect to to n (default 5201)
+
+   ‐f, ‐‐format
+   [kmKM]   format to report: Kbits, Mbits, KBytes, MBytes
+
+   ‐i, ‐‐interval n
+   pause  n  seconds between periodic bandwidth reports; default is
+   1, use 0 to disable
+
+   ‐F, ‐‐file name
+   client‐side: read from  the  file  and  write  to  the  network,
+   instead of using random data; server‐side: read from the network
+   and write to the file, instead of throwing the data away
+
+   ‐A, ‐‐affinity n/n,m
+   Set the CPU affinity, if possible (Linux and FreeBSD 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 potentialy  mul‐
+   tiple CPUs).
+
+   ‐B, ‐‐bind host
+   bind to a specific interface
+
+   ‐V, ‐‐verbose
+   give more detailed output
+
+   ‐J, ‐‐json
+   output in JSON format
+
+   ‐‐logfile file
+   send output to a log file.
+
+   ‐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
+
+   ‐I, ‐‐pidfile file
+   write a file with the process ID, most useful when running as  a
+   daemon.
+
+
+   CLIENT SPECIFIC OPTIONS
+   ‐c, ‐‐client host
+   run in client mode, connecting to the specified server
+
+   ‐‐sctp use SCTP rather than TCP (FreeBSD and Linux)
+
+   ‐u, ‐‐udp
+   use UDP rather than TCP
+
+   ‐b, ‐‐bandwidth n[KM]
+   set  target bandwidth to n bits/sec (default 1 Mbit/sec for UDP,
+   unlimited for TCP).  If there are multiple  streams  (‐P  flag),
+   the  bandwidth  limit is applied separately to each stream.  You
+   can also add a ’/’ and a  number  to  the  bandwidth  specifier.
+   This  is  called "burst mode".  It will send the given number of
+   packets without pausing, even if that  temporarily  exceeds  the
+   specified bandwidth limit.
+
+   ‐t, ‐‐time n
+   time in seconds to transmit for (default 10 secs)
+
+   ‐n, ‐‐bytes n[KM]
+   number of bytes to transmit (instead of ‐t)
+
+   ‐k, ‐‐blockcount n[KM]
+   number of blocks (packets) to transmit (instead of ‐t or ‐n)
+
+   ‐l, ‐‐length n[KM]
+   length  of  buffer to read or write (default 128 KB for TCP, 8KB
+   for UDP)
+
+   ‐P, ‐‐parallel n
+   number of parallel client streams to run
+
+   ‐R, ‐‐reverse
+   run in reverse mode (server sends, client receives)
+
+   ‐w, ‐‐window n[KM]
+   TCP window size / socket buffer size  (this  gets  sent  to  the
+   server and used on that side too)
+
+   ‐M, ‐‐set‐mss n
+   set TCP maximum segment size (MTU ‐ 40 bytes)
+
+   ‐N, ‐‐no‐delay
+   set TCP 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’
+
+   ‐L, ‐‐flowlabel n
+   set the IPv6 flow label (currently only supported on Linux)
+
+   ‐Z, ‐‐zerocopy
+   Use  a  "zero copy" method of sending data, such as sendfile(2),
+   instead of the usual write(2).
+
+   ‐O, ‐‐omit n
+   Omit the first n seconds of the test, to skip past the TCP slow‐
+   start period.
+
+   ‐T, ‐‐title str
+   Prefix every output line with this string.
+
+   ‐C, ‐‐linux‐congestion algo
+   Set the congestion control algorithm (linux only).
+
+
+   AUTHORS
+   Iperf  was  originally  written by Mark Gates and Alex Warshavsky.  Man
+   page and maintence by Jon Dugan <jdugan at x1024 dot net>.  Other  con‐
+   tributions  from  Ajay  Tirumala,  Jim Ferguson, Feng Qin, Kevin Gibbs,
+   John Estabrook <jestabro at ncsa.uiuc.edu>, Andrew  Gallatin  <gallatin
+   at gmail.com>, Stephen Hemminger <shemminger at linux‐foundation.org>
+
+
+   SEE ALSO
+   libiperf(3), https://github.com/esnet/iperf
+
+
+
+   ESnet                            February 2014                        IPERF(1)
+
+The iperf3 manual page will typically be installed in manual
+section 1.
+
--- a/docs/news.rst
+++ b/docs/news.rst
@ -0,0 +1,63 @@
+iperf3 Project News
+===================
+
+2014-03-26:  iperf-3.0.3 released
+---------------------------------
+
+| http://stats.es.net/software/iperf-3.0.3.tar.gz
+| ``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 RELEASE_NOTES
+file in the source distribution.
+
+2014-03-10:  iperf-3.0.2 released
+---------------------------------
+
+| http://stats.es.net/software/iperf-3.0.2.tar.gz
+| ``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 RELEASE_NOTES
+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
+---------------------------------
+
+| http://stats.es.net/software/iperf-3.0.1.tar.gz
+| ``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 possiblity for confusion, this first public release of iperf3
+was numbered 3.0.1.
+
--- a/docs/obtaining.rst
+++ b/docs/obtaining.rst
@ -0,0 +1,41 @@
+.. _obtaining:
+
+Obtaining iperf3
+================
+
+Binary Distributions
+--------------------
+
+Binary packages are available for several supported operating systems:
+
+* FreeBSD:  `Ports Collection <http://freshports.org/benchmarks/iperf3>`_
+* Fedora / CentOS:
+
+Source Distributions
+--------------------
+
+Source distributions of iperf are available as compressed (gzip)
+tarballs at:
+
+http://stats.es.net/software/
+
+**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.
+
+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 6 Linux, FreeBSD,
+and MacOS X. 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.