Annotation of embedaddon/iperf/docs/dev.rst, revision 1.1
1.1 ! misho 1: iperf3 Development
! 2: ==================
! 3:
! 4: The iperf3 project is hosted on GitHub at:
! 5:
! 6: http://github.com/esnet/iperf
! 7:
! 8: This site includes the source code repository, issue tracker, and
! 9: wiki.
! 10:
! 11: Mailing Lists
! 12: -------------
! 13:
! 14: The developer list for iperf3 is: iperf-dev@googlegroups.com.
! 15: Information on joining the mailing list can be found at:
! 16:
! 17: http://groups.google.com/group/iperf-dev
! 18:
! 19: There is, at the moment, no mailing list for user questions, although
! 20: a low volume of inquiries on the developer list is probably
! 21: acceptable. If necessary, a user-oriented mailing list might be
! 22: created in the future.
! 23:
! 24: Bug Reports
! 25: -----------
! 26:
! 27: Before submitting a bug report, try checking out the latest version of
! 28: the code, and confirm that it's not already fixed. Then submit to the
! 29: iperf3 issue tracker on GitHub:
! 30:
! 31: https://github.com/esnet/iperf/issues
! 32:
! 33: **Note:** Issues submitted to the old iperf3 issue tracker on Google
! 34: Code (or comments to existing issues on the Google Code issue tracker)
! 35: will be ignored.
! 36:
! 37: Changes from iperf 2.x
! 38: ----------------------
! 39:
! 40: New options (not necessarily complete, please refer to the manual page
! 41: for a complete list of iperf3 options)::
! 42:
! 43: -V, --verbose more detailed output than before
! 44: -J, --json output in JSON format
! 45: -Z, --zerocopy use a 'zero copy' sendfile() method of sending data
! 46: -O, --omit N omit the first n seconds (to ignore slowstart)
! 47: -T, --title str prefix every output line with this string
! 48: -F, --file name xmit/recv the specified file
! 49: -A, --affinity n/n,m set CPU affinity (Linux and FreeBSD only)
! 50: -k, --blockcount #[KMG] number of blocks (packets) to transmit (instead
! 51: of -t or -n)
! 52: -L, --flowlabel set IPv6 flow label (Linux only)
! 53:
! 54: Changed flags::
! 55:
! 56: -C, --linux-congestion set congestion control algorithm (Linux only)
! 57: (-Z in iperf2)
! 58:
! 59:
! 60: Deprecated flags (currently no plans to support)::
! 61:
! 62: -d, --dualtest Do a bidirectional test simultaneously
! 63: -r, --tradeoff Do a bidirectional test individually
! 64: -T, --ttl time-to-live, for multicast (default 1)
! 65: -x, --reportexclude [CDMSV] exclude C(connection) D(data) M(multicast)
! 66: S(settings) V(server) reports
! 67: -y, --reportstyle C report as a Comma-Separated Values
! 68:
! 69: Also deprecated is the ability to set the options via environment
! 70: variables.
! 71:
! 72: Known Issues
! 73: ------------
! 74:
! 75: The following problems are notable known issues, which are probably of
! 76: interest to a large fraction of users or have high impact for some
! 77: users, and for which issues have already been filed in the issue
! 78: tracker. These issues are either open (indicating no solution
! 79: currently exists) or closed with the notation that no further attempts
! 80: to solve the problem are currently being made:
! 81:
! 82: * UDP performance: Some problems have been noticed with iperf3 on the
! 83: ESnet 100G testbed at high UDP rates (above 10Gbps). The symptom is
! 84: that on any particular run of iperf3 the receiver reports a loss
! 85: rate of about 20%, regardless of the ``-b`` option used on the client
! 86: side. This problem appears not to be iperf3-specific, and may be
! 87: due to the placement of the iperf3 process on a CPU and its relation
! 88: to the inbound NIC. In some cases this problem can be mitigated by
! 89: an appropriate use of the CPU affinity (``-A``) option. (Issue #55)
! 90:
! 91: * Interval reports on high-loss networks: The way iperf3 is currently
! 92: implemented, the sender write command will block until the entire
! 93: block has been written. This means that it might take several
! 94: seconds to send a full block if the network has high loss, and the
! 95: interval reports will have widely varying interval times. A
! 96: solution is being discussed, but in the meantime a work around is to
! 97: try using a small block size, for example ``-l 4K``. (Issue #125,
! 98: a fix will be released in iperf 3.1)
! 99:
! 100: * The ``-Z`` flag sometimes causes the iperf3 client to hang on OSX.
! 101: (Issue #129)
! 102:
! 103: * When specifying the TCP buffer size using the ``-w`` flag on Linux,
! 104: the Linux kernel automatically doubles the value passed in to
! 105: compensate for overheads. (This can be observed by using
! 106: iperf3's ``--debug`` flag.) However, CWND does not actually ramp up
! 107: to the doubled value, but only to about 75% of the doubled
! 108: value. Some part of this behavior is documented in the tcp(7)
! 109: manual page. (Issue #145)
! 110:
! 111: * On some platforms (observed on at least one version of Ubuntu
! 112: Linux), it might be necessary to invoke ``ldconfig`` manually after
! 113: doing a ``make install`` before the ``iperf3`` executable can find
! 114: its shared library. (Issue #153)
! 115:
! 116: There are, of course, many other open and closed issues in the issue
! 117: tracker.
! 118:
! 119: Versioning
! 120: ----------
! 121:
! 122: iperf3 version numbers use (roughly) a `Semantic Versioning
! 123: <http://semver.org/>`_ scheme, in which version numbers consist of
! 124: three parts: *MAJOR.MINOR.PATCH*
! 125:
! 126: The developers increment the:
! 127:
! 128: * *MAJOR* version when making incompatible API changes,
! 129:
! 130: * *MINOR* version when adding functionality in a backwards-compatible manner, and
! 131:
! 132: * *PATCH* version when making backwards-compatible bug fixes.
! 133:
! 134: Release Engineering Checklist
! 135: -----------------------------
! 136:
! 137: 1. Update the ``README`` and ``RELEASE_NOTES`` files to be accurate. Make sure
! 138: that the "Known Issues" section of the ``README`` file is up to date.
! 139:
! 140: 2. Compose a release announcement. Most of the release announcement
! 141: can be written before tagging. Usually the previous version's
! 142: announcement can be used as a starting point.
! 143:
! 144: 3. Preferably starting from a clean source tree (be sure that ``git
! 145: status`` emits no output), make the changes necessary to produce
! 146: the new version, such as bumping version numbers::
! 147:
! 148: vi RELEASE_NOTES # update version number and release date
! 149: vi configure.ac # update version parameter in AC_INIT
! 150: vi src/iperf3.1 # update manpage revision date if needed
! 151: vi src/libiperf.3 # update manpage revision date if needed
! 152: git commit -a # commit changes to the local repository only
! 153: ./bootstrap.sh # regenerate configure script, etc.
! 154: git commit -a # commit changes to the local repository only
! 155:
! 156: # Assuming that $VERSION is the version number to be released...
! 157: ./make_release tag $VERSION # this creates a tag in the local repo
! 158: ./make_release tar $VERSION # create tarball and compute SHA256 hash
! 159:
! 160: These steps should be done on a platform with a relatively recent
! 161: version of autotools / libtools. Examples are MacOS / MacPorts or
! 162: FreeBSD. The versions of these tools in CentOS 6 are somewhat
! 163: older and probably should be avoided.
! 164:
! 165: The result will be a release artifact that should be used for
! 166: pre-testing.
! 167:
! 168: 4. Stage the tarball (and a file containing the SHA256 hash) to the
! 169: download site. Currently this is located on ``downloads.es.net``.
! 170:
! 171: 5. From another host, test the link in the release announcement by
! 172: downloading a fresh copy of the file and verifying the SHA256
! 173: checksum. Checking all other links in the release announcement is
! 174: strongly recommended as well.
! 175:
! 176: 6. Also verify (with file(1)) that the tarball is actually a gzipped
! 177: tarball.
! 178:
! 179: 7. For extra points, actually try downloading, compiling, and
! 180: smoke-testing the results of the tarball on all supported
! 181: platforms.
! 182:
! 183: 8. Plug the SHA256 checksum into the release announcement.
! 184:
! 185: 9. PGP-sign the release announcement text using ``gpg --clearsign``.
! 186: The signed announcement will be sent out in a subsequent emails,
! 187: but could also be archived. Decoupling the signing from emailing
! 188: allows a signed release announcement to be resent via email or sent
! 189: by other, non-email means.
! 190:
! 191: 10. At this point, the release can and should be considered
! 192: finalized. To commit the release-engineering-related changes to
! 193: GitHub and make them public, push them out thusly::
! 194:
! 195: git push # Push version changes
! 196: git push --tags # Push the new tag to the GitHub repo
! 197:
! 198: 11. Send the PGP-signed release announcement to the following
! 199: addresses. Remember to turn off signing in the MUA, if
! 200: applicable. Remember to check the source address when posting to
! 201: lists, as "closed" list will reject posting from all from
! 202: registered email addresses.
! 203:
! 204: * iperf-dev@googlegroups.com
! 205:
! 206: * iperf-users@lists.sourceforge.net
! 207:
! 208: * perfsonar-user@internet2.edu
! 209:
! 210: * perfsonar-developer@internet2.edu
! 211:
! 212: Note: Thunderbird sometimes mangles the PGP-signed release
! 213: announcement so that it does not verify correctly. This could be
! 214: due to Thunderbird trying to wrap the length of extremely long
! 215: lines (such as the SHA256 hash). Apple Mail and mutt seem to
! 216: handle this situation correctly. Testing the release announcement
! 217: sending process by sending a copy to oneself first and attempting
! 218: to verify the signature is highly encouraged.
! 219:
! 220: 12. Update the iperf3 Project News section of the documentation site
! 221: to announce the new release (see ``docs/news.rst`` and
! 222: ``docs/conf.py`` in the source tree) and deploy a new build of the
! 223: documentation to GitHub Pages.
! 224:
! 225: Code Authors
! 226: ------------
! 227:
! 228: The main authors of iperf3 are (in alphabetical order): Jon Dugan,
! 229: Seth Elliott, Bruce A. Mah, Jeff Poskanzer, Kaustubh Prabhu.
! 230: Additional code contributions have come from (also in alphabetical
! 231: order): Mark Ashley, Aaron Brown, Aeneas Jaißle, Susant Sahani,
! 232: Bruce Simpson, Brian Tierney.
! 233:
! 234: iperf3 contains some original code from iperf2. The authors of iperf2
! 235: are (in alphabetical order): Jon Dugan, John Estabrook, Jim Ferbuson,
! 236: Andrew Gallatin, Mark Gates, Kevin Gibbs, Stephen Hemminger, Nathan
! 237: Jones, Feng Qin, Gerrit Renker, Ajay Tirumala, Alex Warshavsky.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dev.rst CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf / docs