1iperf3 Development 2================== 3 4The iperf3 project is hosted on GitHub at: 5 6http://github.com/esnet/iperf 7 8This site includes the source code repository, issue tracker, and 9wiki. 10 11Mailing Lists 12------------- 13 14The developer list for iperf3 is: [email protected]. 15Information on joining the mailing list can be found at: 16 17http://groups.google.com/group/iperf-dev 18 19There is, at the moment, no mailing list for user questions, although 20a low volume of inquiries on the developer list is probably 21acceptable. If necessary, a user-oriented mailing list might be 22created in the future. 23 24Bug Reports 25----------- 26 27Before submitting a bug report, try checking out the latest version of 28the code, and confirm that it's not already fixed. Then submit to the 29iperf3 issue tracker on GitHub: 30 31https://github.com/esnet/iperf/issues 32 33**Note:** Issues submitted to the old iperf3 issue tracker on Google 34Code (or comments to existing issues on the Google Code issue tracker) 35will be ignored. 36 37Changes from iperf 2.x 38---------------------- 39 40New options (not necessarily complete, please refer to the manual page 41for 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 54Changed flags:: 55 56 -C, --linux-congestion set congestion control algorithm (Linux only) 57 (-Z in iperf2) 58 59 60Deprecated 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 69Also deprecated is the ability to set the options via environment 70variables. 71 72Known Issues 73------------ 74 75The following problems are notable known issues, which are probably of 76interest to a large fraction of users or have high impact for some 77users, and for which issues have already been filed in the issue 78tracker. These issues are either open (indicating no solution 79currently exists) or closed with the notation that no further attempts 80to 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 116There are, of course, many other open and closed issues in the issue 117tracker. 118 119Versioning 120---------- 121 122iperf3 version numbers use (roughly) a `Semantic Versioning 123<http://semver.org/>`_ scheme, in which version numbers consist of 124three parts: *MAJOR.MINOR.PATCH* 125 126The 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 134Release Engineering Checklist 135----------------------------- 136 1371. 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 1402. 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 1443. 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 1684. Stage the tarball (and a file containing the SHA256 hash) to the 169 download site. Currently this is located on ``downloads.es.net``. 170 1715. 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 1766. Also verify (with file(1)) that the tarball is actually a gzipped 177 tarball. 178 1797. For extra points, actually try downloading, compiling, and 180 smoke-testing the results of the tarball on all supported 181 platforms. 182 1838. Plug the SHA256 checksum into the release announcement. 184 1859. 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 19110. 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 19811. 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 * [email protected] 205 206 * [email protected] 207 208 * [email protected] 209 210 * [email protected] 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 22012. 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 22513. If an update to the on-line manual page is needed, it can be 226 generated with this sequence of commands (tested on CentOS 7) and 227 import the result into ``invoking.rst``:: 228 229 TERM= 230 export TERM 231 nroff -Tascii -c -man src/iperf3.1 | ul | sed 's/^/ /' > iperf3.txt 232 233Code Authors 234------------ 235 236The main authors of iperf3 are (in alphabetical order): Jon Dugan, 237Seth Elliott, Bruce A. Mah, Jeff Poskanzer, Kaustubh Prabhu. 238Additional code contributions have come from (also in alphabetical 239order): Mark Ashley, Aaron Brown, Aeneas Jaißle, Susant Sahani, 240Bruce Simpson, Brian Tierney. 241 242iperf3 contains some original code from iperf2. The authors of iperf2 243are (in alphabetical order): Jon Dugan, John Estabrook, Jim Ferbuson, 244Andrew Gallatin, Mark Gates, Kevin Gibbs, Stephen Hemminger, Nathan 245Jones, Feng Qin, Gerrit Renker, Ajay Tirumala, Alex Warshavsky. 246