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 will be ignored. 35 36Changes from iperf 2.x 37---------------------- 38 39New options (not necessarily complete, please refer to the manual page 40for a complete list of iperf3 options):: 41 42 -V, --verbose more detailed output than before 43 -J, --json output in JSON format 44 -Z, --zerocopy use a 'zero copy' sendfile() method of sending data 45 -O, --omit N omit the first n seconds (to ignore slowstart) 46 -T, --title str prefix every output line with this string 47 -F, --file name xmit/recv the specified file 48 -A, --affinity n/n,m set CPU affinity (Linux and FreeBSD only) 49 -k, --blockcount #[KMG] number of blocks (packets) to transmit (instead 50 of -t or -n) 51 -L, --flowlabel set IPv6 flow label (Linux only) 52 53Changed flags:: 54 55 -C, --linux-congestion set congestion control algorithm (Linux only) 56 (-Z in iperf2) 57 58 59Deprecated flags (currently no plans to support):: 60 61 -d, --dualtest Do a bidirectional test simultaneously 62 -r, --tradeoff Do a bidirectional test individually 63 -T, --ttl time-to-live, for multicast (default 1) 64 -x, --reportexclude [CDMSV] exclude C(connection) D(data) M(multicast) 65 S(settings) V(server) reports 66 -y, --reportstyle C report as a Comma-Separated Values 67 68Also deprecated is the ability to set the options via environment 69variables. 70 71Known Issues 72------------ 73 74The following problems are notable known issues, which are probably of 75interest to a large fraction of users or have high impact for some 76users, and for which issues have already been filed in the issue 77tracker. These issues are either open (indicating no solution 78currently exists) or closed with the notation that no further attempts 79to solve the problem are currently being made: 80 81* UDP performance: iperf2/iperf3 both only are only about 50% as fast 82 as nuttcp in UDP mode. We are looking into this, but in the 83 meantime, if you want to get UDP above 5Gbps, we recommend using 84 nuttcp instead (http://www.nuttcp.net/). (Issue #55) 85 86* Interval reports on high-loss networks: The way iperf3 is currently 87 implemented, the sender write command will block until the entire 88 block has been written. This means that it might take several 89 seconds to send a full block if the network has high loss, and the 90 interval reports will have widely varying interval times. We are 91 trying to determine the best solution to this, but in the meantime, 92 try using a smaller block size if you get strange interval reports. 93 For example, try ``-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 Linux doubles the value you pass in. (You can see this using 102 iperf3's debug flag.) But then the CWND does not actually ramp up 103 to the doubled value, but only to about 75% of the doubled 104 value. This appears to be by design. (Issue #145) 105 106There are, of course, many other open and closed issues in the issue 107tracker. 108 109Versioning 110---------- 111 112iperf version numbers use three-part release numbers: *MAJOR.MINOR.PATCH* 113 114The developers increment the: 115 116* *MAJOR* version when making incompatible API changes, 117 118* *MINOR* version when adding functionality in a backwards-compatible manner, and 119 120* *PATCH* version when making backwards-compatible bug fixes. 121 122This is roughly along the line of `Semantic Versioning <http://semver.org/>`_. 123 124Release Engineering Checklist 125----------------------------- 126 1271. Update the ``README`` and ``RELEASE_NOTES`` files to be accurate. Make sure 128 that the "Known Issues" section of the ``README`` file is up to date. 129 1302. Compose a release announcement. Most of the release announcement 131 can be written before tagging. 132 1333. Starting from a clean source tree (be sure that ``git status`` emits 134 no output):: 135 136 vi src/version.h # update the strings IPERF_VERSION and IPERF_VERSION_DATE 137 vi configure.ac # update version parameter in AC_INIT 138 vi src/iperf3.1 # update manpage revision date if needed 139 vi src/libiperf.3 # update manpage revision date if needed 140 git commit -a 141 ./bootstrap.sh # regenerate configure script, etc. 142 git commit -a 143 git push 144 145 ./make_release tag # this creates a tag in the local repo that matches the version.h version 146 git push --tags # Push the new tag to the GitHub repo 147 ./make_release tar # create tarball and compute SHA256 hash 148 149 Doing the above steps on CentOS 6 (with its somewhat older 150 autotools / libtools suite) is preferred; newer systems generate 151 ``configure`` and ``Makefile`` scripts that tend to rebuild 152 themselves rather frequently. We might be able to address this 153 problem (and graduate to newer autotools) by using 154 ``AC_MAINTAINER_MODE`` but there's a fair amount of religion 155 associated with this. 156 1574. Stage the tarball (and a file containing the SHA256 hash) to the 158 download site. Currently this is located on ``stats.es.net``. 159 1605. From another host, test the link in the release announcement by 161 downloading a fresh copy of the file and verifying the SHA256 162 checksum. 163 1646. Also verify (with file(1)) that the tarball is actually a gzipped 165 tarball. 166 1677. For extra points, actually try downloading, compiling, and 168 smoke-testing the results of the tarball on all supported 169 platforms. 170 1718. Plug the SHA256 checksum into the release announcement. 172 1739. Send the release announcement (PGP-signed) to these addresses: 174 175 * [email protected] 176 177 * [email protected] 178 179 * [email protected] 180 181 * [email protected] 182 183