1 iperf3 Development 2 ================== 3 4 The iperf3 project is hosted on GitHub at: 5 6 http://github.com/esnet/iperf 7 8 This site includes the source code repository, issue tracker, and 9 wiki. 10 11 Mailing Lists 12 ------------- 13 14 The developer list for iperf3 is: iperf-dev (a] googlegroups.com. 15 Information on joining the mailing list can be found at: 16 17 http://groups.google.com/group/iperf-dev 18 19 There is, at the moment, no mailing list for user questions, although 20 a low volume of inquiries on the developer list is probably 21 acceptable. If necessary, a user-oriented mailing list might be 22 created in the future. 23 24 Bug Reports 25 ----------- 26 27 Before submitting a bug report, try checking out the latest version of 28 the code, and confirm that it's not already fixed. Also see the :doc:`faq`. 29 Then submit to the iperf3 issue tracker on GitHub: 30 31 https://github.com/esnet/iperf/issues 32 33 **Note:** Issues submitted to the old iperf3 issue tracker on Google 34 Code (or comments to existing issues on the Google Code issue tracker) 35 will be ignored. 36 37 Changes from iperf 2.x 38 ---------------------- 39 40 New options (not necessarily complete, please refer to the manual page 41 for 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 54 Changed flags:: 55 56 -C, --linux-congestion set congestion control algorithm (Linux only) 57 (-Z in iperf2) 58 59 60 Deprecated 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 69 Also deprecated is the ability to set the options via environment 70 variables. 71 72 Known Issues 73 ------------ 74 75 The following problems are notable known issues, which are probably of 76 interest to a large fraction of users or have high impact for some 77 users, and for which issues have already been filed in the issue 78 tracker. These issues are either open (indicating no solution 79 currently exists) or closed with the notation that no further attempts 80 to 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 112 There are, of course, many other open and closed issues in the issue 113 tracker. 114 115 Versioning 116 ---------- 117 118 iperf3 version numbers use (roughly) a `Semantic Versioning 119 <http://semver.org/>`_ scheme, in which version numbers consist of 120 three parts: *MAJOR.MINOR.PATCH* 121 122 The 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 130 Release Engineering Checklist 131 ----------------------------- 132 133 1. Update the ``README`` and ``RELEASE_NOTES`` files to be accurate. Make sure 134 that the "Known Issues" section of the ``README`` file and in this document 135 are up to date. 136 137 2. Compose a release announcement. Most of the release announcement 138 can be written before tagging. Usually the previous version's 139 announcement can be used as a starting point. 140 141 3. Preferably starting from a clean source tree (be sure that ``git 142 status`` emits no output), make the changes necessary to produce 143 the new version, such as bumping version numbers:: 144 145 vi RELEASE_NOTES # update version number and release date 146 vi configure.ac # update version parameter in AC_INIT 147 vi src/iperf3.1 # update manpage revision date if needed 148 vi src/libiperf.3 # update manpage revision date if needed 149 git commit -a # commit changes to the local repository only 150 ./bootstrap.sh # regenerate configure script, etc. 151 git commit -a # commit changes to the local repository only 152 153 # Assuming that $VERSION is the version number to be released... 154 ./make_release tag $VERSION # this creates a tag in the local repo 155 ./make_release tar $VERSION # create tarball and compute SHA256 hash 156 157 These steps should be done on a platform with a relatively recent 158 version of autotools / libtools. Examples are MacOS / MacPorts or 159 FreeBSD. The versions of these tools in CentOS 6 are somewhat 160 older and probably should be avoided. 161 162 The result will be a release artifact that should be used for 163 pre-testing. 164 165 4. Stage the tarball (and a file containing the SHA256 hash) to the 166 download site. Currently this is located on ``downloads.es.net``. 167 168 5. From another host, test the link in the release announcement by 169 downloading a fresh copy of the file and verifying the SHA256 170 checksum. Checking all other links in the release announcement is 171 strongly recommended as well. 172 173 6. Also verify (with file(1)) that the tarball is actually a gzipped 174 tarball. 175 176 7. For extra points, actually try downloading, compiling, and 177 smoke-testing the results of the tarball on all supported 178 platforms. 179 180 8. Plug the SHA256 checksum into the release announcement. 181 182 9. PGP-sign the release announcement text using ``gpg --clearsign``. 183 The signed announcement will be sent out in a subsequent emails, 184 but could also be archived. Decoupling the signing from emailing 185 allows a signed release announcement to be resent via email or sent 186 by other, non-email means. 187 188 10. At this point, the release can and should be considered 189 finalized. To commit the release-engineering-related changes to 190 GitHub and make them public, push them out thusly:: 191 192 git push # Push version changes 193 git push --tags # Push the new tag to the GitHub repo 194 195 11. Send the PGP-signed release announcement to the following 196 addresses. Remember to turn off signing in the MUA, if 197 applicable. Remember to check the source address when posting to 198 lists, as "closed" list will reject posting from all from 199 registered email addresses. 200 201 * iperf-dev (a] googlegroups.com 202 203 * iperf-users (a] lists.sourceforge.net 204 205 * perfsonar-user (a] internet2.edu 206 207 * perfsonar-developer (a] internet2.edu 208 209 Note: Thunderbird sometimes mangles the PGP-signed release 210 announcement so that it does not verify correctly. This could be 211 due to Thunderbird trying to wrap the length of extremely long 212 lines (such as the SHA256 hash). Apple Mail and mutt seem to 213 handle this situation correctly. Testing the release announcement 214 sending process by sending a copy to oneself first and attempting 215 to verify the signature is highly encouraged. 216 217 12. Update the iperf3 Project News section of the documentation site 218 to announce the new release (see ``docs/news.rst`` and 219 ``docs/conf.py`` in the source tree) and deploy a new build of the 220 documentation to GitHub Pages. 221 222 13. If an update to the on-line manual page is needed, it can be 223 generated with this sequence of commands (tested on CentOS 7) and 224 import the result into ``invoking.rst``:: 225 226 TERM= 227 export TERM 228 nroff -Tascii -c -man src/iperf3.1 | ul | sed 's/^/ /' > iperf3.txt 229 230 Code Authors 231 ------------ 232 233 The main authors of iperf3 are (in alphabetical order): Jon Dugan, 234 Seth Elliott, Bruce A. Mah, Jeff Poskanzer, Kaustubh Prabhu. 235 Additional code contributions have come from (also in alphabetical 236 order): Mark Ashley, Aaron Brown, Aeneas Jaile, Susant Sahani, 237 Bruce Simpson, Brian Tierney. 238 239 iperf3 contains some original code from iperf2. The authors of iperf2 240 are (in alphabetical order): Jon Dugan, John Estabrook, Jim Ferbuson, 241 Andrew Gallatin, Mark Gates, Kevin Gibbs, Stephen Hemminger, Nathan 242 Jones, Feng Qin, Gerrit Renker, Ajay Tirumala, Alex Warshavsky. 243
