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