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, sometimes at 84 speeds above 1Gbps). The symptom is that on any particular run of 85 iperf3 the receiver reports a loss rate of about 20%, regardless of 86 the ``-b`` option used on the client side. This problem appears not 87 to be iperf3-specific, and may be due to the placement of the iperf3 88 process on a CPU and its relation to the inbound NIC. In some cases 89 this problem can be mitigated by increasing the socket buffer sizes 90 with the ``-w`` option, or by an appropriate use of the CPU affinity 91 (``-A``) option. 92 93* The ``-Z`` flag sometimes causes the iperf3 client to hang on OSX. 94 (Issue #129) 95 96* When specifying the TCP buffer size using the ``-w`` flag on Linux, 97 the Linux kernel automatically doubles the value passed in to 98 compensate for overheads. (This can be observed by using 99 iperf3's ``--debug`` flag.) However, CWND does not actually ramp up 100 to the doubled value, but only to about 75% of the doubled 101 value. Some part of this behavior is documented in the tcp(7) 102 manual page. 103 104* Although the ``-w`` flag is documented as setting the (TCP) window 105 size, it is also used to set the socket buffer size. This has been 106 shown to be helpful with high-bitrate UDP tests. 107 108* On some platforms (observed on at least one version of Ubuntu 109 Linux), it might be necessary to invoke ``ldconfig`` manually after 110 doing a ``make install`` before the ``iperf3`` executable can find 111 its shared library. (Issue #153) 112 113* The results printed on the server side at the end of a test do not 114 correctly reflect the client-side measurements. This is due to the 115 ordering of computing and transferring results between the client 116 and server. (Issue #293) 117 118* The server could have a very short measurement reporting interval at 119 the end of a test (particularly a UDP test), containing few or no 120 packets. This issue is due to an artifact of timing between the 121 client and server. (Issue #278) 122 123There are, of course, many other open and closed issues in the issue 124tracker. 125 126Versioning 127---------- 128 129iperf3 version numbers use (roughly) a `Semantic Versioning 130<http://semver.org/>`_ scheme, in which version numbers consist of 131three parts: *MAJOR.MINOR.PATCH* 132 133The developers increment the: 134 135* *MAJOR* version when making incompatible API changes, 136 137* *MINOR* version when adding functionality in a backwards-compatible manner, and 138 139* *PATCH* version when making backwards-compatible bug fixes. 140 141Release Engineering Checklist 142----------------------------- 143 1441. Update the ``README`` and ``RELEASE_NOTES`` files to be accurate. Make sure 145 that the "Known Issues" section of the ``README`` file is up to date. 146 1472. Compose a release announcement. Most of the release announcement 148 can be written before tagging. Usually the previous version's 149 announcement can be used as a starting point. 150 1513. Preferably starting from a clean source tree (be sure that ``git 152 status`` emits no output), make the changes necessary to produce 153 the new version, such as bumping version numbers:: 154 155 vi RELEASE_NOTES # update version number and release date 156 vi configure.ac # update version parameter in AC_INIT 157 vi src/iperf3.1 # update manpage revision date if needed 158 vi src/libiperf.3 # update manpage revision date if needed 159 git commit -a # commit changes to the local repository only 160 ./bootstrap.sh # regenerate configure script, etc. 161 git commit -a # commit changes to the local repository only 162 163 # Assuming that $VERSION is the version number to be released... 164 ./make_release tag $VERSION # this creates a tag in the local repo 165 ./make_release tar $VERSION # create tarball and compute SHA256 hash 166 167 These steps should be done on a platform with a relatively recent 168 version of autotools / libtools. Examples are MacOS / MacPorts or 169 FreeBSD. The versions of these tools in CentOS 6 are somewhat 170 older and probably should be avoided. 171 172 The result will be a release artifact that should be used for 173 pre-testing. 174 1754. Stage the tarball (and a file containing the SHA256 hash) to the 176 download site. Currently this is located on ``downloads.es.net``. 177 1785. From another host, test the link in the release announcement by 179 downloading a fresh copy of the file and verifying the SHA256 180 checksum. Checking all other links in the release announcement is 181 strongly recommended as well. 182 1836. Also verify (with file(1)) that the tarball is actually a gzipped 184 tarball. 185 1867. For extra points, actually try downloading, compiling, and 187 smoke-testing the results of the tarball on all supported 188 platforms. 189 1908. Plug the SHA256 checksum into the release announcement. 191 1929. PGP-sign the release announcement text using ``gpg --clearsign``. 193 The signed announcement will be sent out in a subsequent emails, 194 but could also be archived. Decoupling the signing from emailing 195 allows a signed release announcement to be resent via email or sent 196 by other, non-email means. 197 19810. At this point, the release can and should be considered 199 finalized. To commit the release-engineering-related changes to 200 GitHub and make them public, push them out thusly:: 201 202 git push # Push version changes 203 git push --tags # Push the new tag to the GitHub repo 204 20511. Send the PGP-signed release announcement to the following 206 addresses. Remember to turn off signing in the MUA, if 207 applicable. Remember to check the source address when posting to 208 lists, as "closed" list will reject posting from all from 209 registered email addresses. 210 211 * [email protected] 212 213 * [email protected] 214 215 * [email protected] 216 217 * [email protected] 218 219 Note: Thunderbird sometimes mangles the PGP-signed release 220 announcement so that it does not verify correctly. This could be 221 due to Thunderbird trying to wrap the length of extremely long 222 lines (such as the SHA256 hash). Apple Mail and mutt seem to 223 handle this situation correctly. Testing the release announcement 224 sending process by sending a copy to oneself first and attempting 225 to verify the signature is highly encouraged. 226 22712. Update the iperf3 Project News section of the documentation site 228 to announce the new release (see ``docs/news.rst`` and 229 ``docs/conf.py`` in the source tree) and deploy a new build of the 230 documentation to GitHub Pages. 231 23213. If an update to the on-line manual page is needed, it can be 233 generated with this sequence of commands (tested on CentOS 7) and 234 import the result into ``invoking.rst``:: 235 236 TERM= 237 export TERM 238 nroff -Tascii -c -man src/iperf3.1 | ul | sed 's/^/ /' > iperf3.txt 239 240Code Authors 241------------ 242 243The main authors of iperf3 are (in alphabetical order): Jon Dugan, 244Seth Elliott, Bruce A. Mah, Jeff Poskanzer, Kaustubh Prabhu. 245Additional code contributions have come from (also in alphabetical 246order): Mark Ashley, Aaron Brown, Aeneas Jaißle, Susant Sahani, 247Bruce Simpson, Brian Tierney. 248 249iperf3 contains some original code from iperf2. The authors of iperf2 250are (in alphabetical order): Jon Dugan, John Estabrook, Jim Ferbuson, 251Andrew Gallatin, Mark Gates, Kevin Gibbs, Stephen Hemminger, Nathan 252Jones, Feng Qin, Gerrit Renker, Ajay Tirumala, Alex Warshavsky. 253