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: iperf2/iperf3 are both only about 50% as fast 83 as nuttcp in UDP mode. This is being investigated, but in the 84 meantime, if UDP tests above 5Gbps are needed, using 85 `nuttcp <http://www.nuttcp.net/>`_ is recommended. (Issue #55) 86 87* Interval reports on high-loss networks: The way iperf3 is currently 88 implemented, the sender write command will block until the entire 89 block has been written. This means that it might take several 90 seconds to send a full block if the network has high loss, and the 91 interval reports will have widely varying interval times. A 92 solution is being discussed, but in the meantime a work around is to 93 try using a small block size, for example ``-l 4K``. (Issue #125) 94 95* The ``-Z`` flag sometimes hangs on OSX. (Issue #129) 96 97* On OpenBSD, the server seems to require a ``-4`` argument, implying 98 that it can only be used with IPv4. (Issue #108) 99 100* When specifying the TCP buffer size using the ``-w`` flag on Linux, 101 the Linux kernel automatically doubles the value passed in to 102 compensate for overheads. (This can be observed by using 103 iperf3's ``--debug`` flag.) However, CWND does not actually ramp up 104 to the doubled value, but only to about 75% of the doubled 105 value. Some part of this behavior is documented in the tcp(7) 106 manual page. (Issue #145) 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 113There are, of course, many other open and closed issues in the issue 114tracker. 115 116Versioning 117---------- 118 119iperf3 version numbers use (roughly) a `Semantic Versioning 120<http://semver.org/>`_ scheme, in which version numbers consist of 121three parts: *MAJOR.MINOR.PATCH* 122 123The developers increment the: 124 125* *MAJOR* version when making incompatible API changes, 126 127* *MINOR* version when adding functionality in a backwards-compatible manner, and 128 129* *PATCH* version when making backwards-compatible bug fixes. 130 131Release Engineering Checklist 132----------------------------- 133 1341. Update the ``README`` and ``RELEASE_NOTES`` files to be accurate. Make sure 135 that the "Known Issues" section of the ``README`` file is up to date. 136 1372. Compose a release announcement. Most of the release announcement 138 can be written before tagging. 139 1403. Starting from a clean source tree (be sure that ``git status`` emits 141 no output):: 142 143 vi src/version.h # update the strings IPERF_VERSION and IPERF_VERSION_DATE 144 vi configure.ac # update version parameter in AC_INIT 145 vi src/iperf3.1 # update manpage revision date if needed 146 vi src/libiperf.3 # update manpage revision date if needed 147 git commit -a 148 ./bootstrap.sh # regenerate configure script, etc. 149 git commit -a 150 git push 151 152 ./make_release tag # this creates a tag in the local repo that matches the version.h version 153 git push --tags # Push the new tag to the GitHub repo 154 ./make_release tar # create tarball and compute SHA256 hash 155 156 Doing the above steps on CentOS 6 (with its somewhat older 157 autotools / libtools suite) is preferred; newer systems generate 158 ``configure`` and ``Makefile`` scripts that tend to rebuild 159 themselves rather frequently. It might be possible to address this 160 problem (and graduate to newer autotools) by using 161 ``AC_MAINTAINER_MODE`` but there's a fair amount of religion 162 associated with this. 163 1644. Stage the tarball (and a file containing the SHA256 hash) to the 165 download site. Currently this is located on ``stats.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. 170 1716. Also verify (with file(1)) that the tarball is actually a gzipped 172 tarball. 173 1747. For extra points, actually try downloading, compiling, and 175 smoke-testing the results of the tarball on all supported 176 platforms. 177 1788. Plug the SHA256 checksum into the release announcement. 179 1809. Send the release announcement (PGP-signed) to these addresses: 181 182 * [email protected] 183 184 * [email protected] 185 186 * [email protected] 187 188 * [email protected] 189 19010. Update the iperf3 Project News section of the documentation site 191 to announce the new release (see ``docs/news.rst`` in the source 192 tree) and deploy a new build of the documentation to GitHub 193 Pages. 194 195