Installing IPERF (on Mac)
Install through the Homebrew package manager. If Homebrew is not already installed, go to http://www.brew.sh and run the “Install Homebrew” command. Once installed, use the command line to enter…
brew install iperf
Tip: this will install Version 2 of IPERF, which is not compatible with Version 3. Make sure both ends are using the same version. Here is the command to check what version of IPERF is running:
iperf -v which returns something like this... iperf version 2.0.5 (08 Jul 2010) pthreads
Template IPERF commands
Server:
iperf -u -s -p4464 ------------------------------------------------------------ Server listening on UDP port 4464 Receiving 1470 byte datagrams UDP buffer size: 192 KByte (default) ------------------------------------------------------------
Meaning: -u (use UDP, not TCP) -s (run as a server, await connections from clients) –p4464 (on port 4464, the default Jacktrip port)
Client:
iperf -u -c [server IP address] -p4464 -b10M -l512 -d
Meaning: -u (use UDP, not TCP) -c (run as a client) [server IP address] (connect to the server at this IP address) -p4464 (connect on port 4464, the default Jacktrip port) -b10M (send packets at 10 megabits/second) -l512 (use packets that are 512 bytes in length) -d (dual test, first the client sends packets to the server, then the server sends packets to the client)
Testing approach:
There are three goals — determine whether there is a connection from one participant to the other, evaluate whether there is sufficient bandwidth to support a jam session, and determine whether there is a good enough connection (low latency and jitter) to jam effectively.
Here’s what success looks like — an example of good connections, in both directions, at 10 mBits/second (more than fast enough for jamming), with low jitter and 0% packet loss (high quality). Both client and server launch tests at the other as clients in “dual test” mode. Note that both sessions report the same results, just in opposite order.
The client (192.168.0.162) session:
------------------------------------------------------------ Client connecting to 192.168.0.150, UDP port 4464 Sending 512 byte datagrams UDP buffer size: 9.00 KByte (default) ------------------------------------------------------------ [ 6] local 192.168.0.162 port 64962 connected with 192.168.0.150 port 4464 [ 5] local 192.168.0.162 port 4464 connected with 192.168.0.150 port 53603 [ ID] Interval Transfer Bandwidth [ 6] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec [ 6] Sent 24451 datagrams [ 5] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec 0.453 ms 0/24450 (0%) [ 5] 0.0-10.0 sec 1 datagrams received out-of-order [ 6] Server Report: [ 6] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec 0.072 ms 0/24450 (0%) [ 6] 0.0-10.0 sec 1 datagrams received out-of-order
The server (192.168.0.150) session:
------------------------------------------------------------ Client connecting to 192.168.0.150, UDP port 4464 Sending 512 byte datagrams UDP buffer size: 9.00 KByte (default) ------------------------------------------------------------ [ 6] local 192.168.0.150 port 53603 connected with 192.168.0.162 port 4464 [ 4] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec 0.073 ms 0/24450 (0%) [ 4] 0.0-10.0 sec 1 datagrams received out-of-order [ 6] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec [ 6] Sent 24451 datagrams [ 6] Server Report: [ 6] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec 0.452 ms 0/24450 (0%) [ 6] 0.0-10.0 sec 1 datagrams received out-of-order
Part One: Connection-test failures
Here is a series of examples showing several ways the two sessions fail to connect properly. These could be due to incorrect packet-forwarding, incorrect computer-firewall settings, incorrect addressing or incorrect command syntax.
This example is created by the participant running as client attempting to connect to an IP address that doesn’t have a server running.
The client (192.168.0.162) session:
iperf -u -c 192.168.0.151 -p4464 -b10M -l512 -d
------------------------------------------------------------
Client connecting to 192.168.0.151, UDP port 4464
Sending 512 byte datagrams
UDP buffer size: 9.00 KByte (default)
------------------------------------------------------------
[ 5] local 192.168.0.162 port 61239 connected with 192.168.0.151 port 4464
[ ID] Interval Transfer Bandwidth
[ 5] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec
[ 5] Sent 24441 datagrams
[ 5] WARNING: did not receive ack of last datagram after 10 tries.
The server (192.168.0.150) sees nothing in this example because it is at a different IP address.
Here is an example of misconfigured port-forwarding and/or computer-firewall settings at the server end. This is what the client sees.
The client (192.168.0.162) session:
iperf -u -c 192.168.0.150 -p4464 -b10M -l512 -d ------------------------------------------------------------ Client connecting to 192.168.0.150, UDP port 4464 Sending 512 byte datagrams UDP buffer size: 9.00 KByte (default) ------------------------------------------------------------ [ 6] local 192.168.0.162 port 61740 connected with 192.168.0.150 port 4464 [ ID] Interval Transfer Bandwidth [ 6] 0.0-10.0 sec 11.5 MBytes 9.62 Mbits/sec [ 6] Sent 24451 datagrams read failed: Connection refused [ 6] WARNING: did not receive ack of last datagram after 10 tries.
The server (192.168.0.150) sees nothing in this example because the packets are blocked by the server’s firewall, their computer, or both.
Here is an example of misconfigured port-forwarding or firewall-settings at the client end. Both participants will see activity, but only for one of the two dual tests. This test provides performance results when the client sends packets to the (correctly-configured) server, but fails when the server attempts to send packets back at the (misconfigured) client. Compare these results with the successful-connection example at the top of this page — only one connection, only one set of performance results.
The client (192.168.0.162) session:
iperf -u -c 192.168.0.150 -p4464 -b10M -l512 -d ------------------------------------------------------------ Client connecting to 192.168.0.150, UDP port 4464 Sending 512 byte datagrams UDP buffer size: 9.00 KByte (default) ------------------------------------------------------------ [ 6] local 192.168.0.162 port 51028 connected with 192.168.0.150 port 4464 [ ID] Interval Transfer Bandwidth [ 6] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec [ 6] Sent 24451 datagrams [ 6] Server Report: [ 6] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec 0.094 ms 0/24450 (0%) [ 6] 0.0-10.0 sec 1 datagrams received out-of-order
The server (192.168.0.150) session:
------------------------------------------------------------ Client connecting to 192.168.0.162, UDP port 4464 Sending 512 byte datagrams UDP buffer size: 9.00 KByte (default) ------------------------------------------------------------ [ 6] local 192.168.0.150 port 62627 connected with 192.168.0.162 port 4464 [ 4] 0.0-10.0 sec 11.9 MBytes 10.0 Mbits/sec 0.094 ms 0/24450 (0%) [ 4] 0.0-10.0 sec 1 datagrams received out-of-order [ 6] 0.0-10.0 sec 11.5 MBytes 9.61 Mbits/sec [ 6] Sent 24451 datagrams read failed: Connection refused [ 6] WARNING: did not receive ack of last datagram after 8 tries.
The notation of who is connecting to who can get confusing. Here are rules to simplify things.
- Whoever is seeing “Connection refused” on their screen needs to tell the other person to take a look at their port-forwarding and computer-firewall configuration.
- Check IPERF command-syntax when client is seeing “WARNING” without “connection refused” and the other person (acting as server) is seeing nothing.
- For new insights, try switching roles between client and server.
Part Two: Evaluating bandwidth
Once connections have been established in both directions, varying the settings in the IPERF client command strings can be used to determine how fast/good the connection is.
The very first example demonstrates that that 10 mBits in both directions works fine.
Example 2:
The client launches a session asking for 40 mBits/second, both directions and exceeds the capacity of the connection both ways. Clues are found in the highlighted numbers, which indicate slower speeds and significant packet-loss in both directions.
Here’s the client session (the server session is exactly the same, except the results are reversed)
iperf -u -c 192.168.0.150 -p4464 -b40m -l512 -d
------------------------------------------------------------
Client connecting to 192.168.0.150, UDP port 4464
Sending 512 byte datagrams
UDP buffer size: 9.00 KByte (default)
------------------------------------------------------------
[ 6] local 192.168.0.162 port 60999 connected with 192.168.0.150 port 4464
[ 5] local 192.168.0.162 port 4464 connected with 192.168.0.150 port 53578
[ ID] Interval Transfer Bandwidth
[ 6] 0.0-10.0 sec 47.9 MBytes 40.2 Mbits/sec
[ 6] Sent 98034 datagrams
[ 5] 0.0-10.3 sec 35.5 MBytes 29.1 Mbits/sec 16.058 ms 25232/97985 (26%)
[ 5] 0.0-10.3 sec 1 datagrams received out-of-order
[ 6] Server Report:
[ 6] 0.0-10.2 sec 19.0 MBytes 15.5 Mbits/sec 15.701 ms 59211/98032 (60%)
[ 6] 0.0-10.2 sec 1 datagrams received out-of-order
Example 3
Since the slowest result is 15.5 mBits/second from the server to the client, let’s try a test at 15 mBits/second. The results are excellent – no packet loss in either direction.
iperf -u -c 192.168.0.150 -p4464 -b15M -l512 -d
------------------------------------------------------------
Client connecting to 192.168.0.150, UDP port 4464
Sending 512 byte datagrams
UDP buffer size: 9.00 KByte (default)
------------------------------------------------------------
[ 6] local 192.168.0.162 port 60445 connected with 192.168.0.150 port 4464
[ 5] local 192.168.0.162 port 4464 connected with 192.168.0.150 port 56000
[ ID] Interval Transfer Bandwidth
[ 6] 0.0-10.0 sec 17.9 MBytes 15.0 Mbits/sec
[ 6] Sent 36631 datagrams
[ 5] 0.0-10.0 sec 17.9 MBytes 15.0 Mbits/sec 0.405 ms 0/36630 (0%)
[ 5] 0.0-10.0 sec 1 datagrams received out-of-order
[ 6] Server Report:
[ 6] 0.0-10.0 sec 17.9 MBytes 15.0 Mbits/sec 0.085 ms 0/36630 (0%)
[ 6] 0.0-10.0 sec 1 datagrams received out-of-order
Example 4
Here are the results of three tests, at 16,17,and 18 Mbits/second that show how packet loss increases pretty quickly at speeds higher than 15 mBits/second on one side of the connection. The conclusion is that there is a solid 15 mBbits/second available for jamming, but not much more. Jamming needs symmetrical bandwidth, so the slower connection defines whether jamming will work. 2 mBits/second is the bare minimum for two participants.
iperf -u -c 192.168.0.150 -p4464 -b16M -l512 -d [ 5] 0.0-10.0 sec 19.1 MBytes 16.0 Mbits/sec 0.366 ms 1/39063 (0.0026%) [ 6] 0.0-10.0 sec 18.9 MBytes 15.9 Mbits/sec 0.082 ms 270/39062 (0.69%) iperf -u -c 192.168.0.150 -p4464 -b17M -l512 -d [ 5] 0.0-10.0 sec 20.3 MBytes 17.1 Mbits/sec 0.342 ms 0/41667 (0%) [ 6] 0.0-10.0 sec 19.0 MBytes 15.9 Mbits/sec 0.063 ms 2854/41665 (6.8%) iperf -u -c 192.168.0.150 -p4464 -b18M -l512 -d [ 5] 0.0-10.0 sec 21.5 MBytes 18.0 Mbits/sec 0.342 ms 0/44053 (0%) [ 6] 0.0-10.0 sec 19.0 MBytes 15.9 Mbits/sec 0.087 ms 5241/44053 (12%
Part Three – Evaluating connection quality
Connection quality is measured in at least two ways – latency and jitter.
Latency
The easiest way to measure latency between two participants is to use ping. Ping will bounce a query off a computer once a second until it is interrupted with control-C.
ping www.example.com PING www.example.com (192.168.0.186): 56 data bytes 64 bytes from 192.168.0.186: icmp_seq=0 ttl=56 time=45.217 ms 64 bytes from 192.168.0.186: icmp_seq=1 ttl=56 time=45.136 ms 64 bytes from 192.168.0.186: icmp_seq=2 ttl=56 time=45.234 ms 64 bytes from 192.168.0.186: icmp_seq=3 ttl=56 time=45.444 ms ^C [interrupt the pings w/control-C] --- 192.168.0.186 ping statistics --- 4 packets transmitted, 4 packets received, 0.0% packet loss round-trip min/avg/max/stddev = 45.136/45.258/45.444/0.114 ms
This example shows pretty consistent 45 ms latency between these computers. Fine for jamming, but somebody will have to be the lead rhythm-provider and can expect to their partner’s notes to be a tiny bit late.
Note that the person who is following the rhythm won’t notice any latency, only the person providing lead. Things get more complicated in a multi-person jam, since the latency between two followers is the sum of their latencies — so life could get complicated.
Jitter
IPERF reports jitter, the variability in how long packets take to arrive. Jitter is the middle number, stated in milliseconds (ms), in each row of performance results.
Since a millisecond translates into about 1 foot of separation between musicians (eg 30 milliseconds of latency equates to musicians playing about 30 feet apart), the numbers we’re seeing in these last reports represent .342 “feet” of perceived variation in the distance between musicians, which will be acceptable in almost all cases.
Look higher in the examples and note that jitter gets to be as high as 16.058 ms in the example where the line got hammered with 40 mBits of transfers. That will not be acceptable to musicians, since that implies that the perceived “distance” between the musicians is varying by 16 “feet” at any given time.
Summary
The goal is a connection that:
- works in both directions,
- is at least 2mbits each way, and
- has acceptable amounts of jitter (less than .500 ms).
Offer yourselves a round of congratulations when you achieve that.