Annotation of embedaddon/iperf/docs/dev.rst, revision 1.1.1.2
1.1 misho 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@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
1.1.1.2 ! misho 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:
1.1 misho 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)
1.1.1.2 ! misho 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.
1.1 misho 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:
1.1.1.2 ! misho 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:
1.1 misho 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
1.1.1.2 ! misho 134: that the "Known Issues" section of the ``README`` file and in this document
! 135: are up to date.
1.1 misho 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@googlegroups.com
202:
203: * iperf-users@lists.sourceforge.net
204:
205: * perfsonar-user@internet2.edu
206:
207: * perfsonar-developer@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:
1.1.1.2 ! misho 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:
1.1 misho 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 Jaißle, 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dev.rst CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf / docs