iperfer

What is iperfer?

I got tired of the usual iperf3 song and dance.

You know the drill: SSH into the remote box, start the server, flip back to your machine, run the test, then go back and kill the server—hoping you remembered to clean up the process. All that hassle just to check how your LAN or VPN is holding up.

So I wrote a helper.

iperfer.sh is a tiny shell script that automates remote-side setup for iperf3 bandwidth tests. It:

• Connects to the remote host via SSH
• Launches iperf3 in server mode (backgrounded and PID-tracked)
• Runs a local client test with parallel streams
• Cleans up the remote server process afterward

It even checks if iperf3 is installed on the remote side before trying. One command. One step. No leftovers.

🧱 Script Highlights

• Auto-starts iperf3 -s on the target host over SSH
• Tracks the PID and cleans up after the test
• Runs a 4-stream client test with customizable duration
• Leaves no background processes or temp files behind
• Written in portable Bash with safe defaults (set -euo pipefail)

⚙️ Usage

iperfer.sh <host> [user] [duration]

• If [user] is omitted, it defaults to your current $USER
• If [duration] is omitted, it defaults to 10 seconds
• The test runs 4 parallel streams and outputs standard iperf3 stats

Example

iperfer.sh gir forfaxx 15

That runs a 15-second test to gir as user forfaxx, then stops the remote server.

📄 Installing iperfer.sh

Save the script below to ~/bin/iperfer.sh (or anywhere in your $PATH), then make it executable:

chmod +x ~/bin/iperfer.sh

Make sure the script is present on both your local and remote machines in a consistent location so SSH can find it.

#!/usr/bin/env bash
#
# iperfer.sh — Run an iperf3 test over SSH by auto-starting a remote server
#
# Usage:
#   iperfer.sh <target-host> [remote-user] [duration]
#
# Example:
#   iperfer.sh gir grumble 15
#
# Description:
#   Starts iperf3 in server mode on the target over SSH,
#   runs a parallelized client test locally,
#   then shuts down the server process cleanly.
#
# Author: forfaxx @ adminjitsu.com

set -euo pipefail
IFS=$'\n\t'

usage() {
  cat <<EOF
Usage: $0 <target-host> [remote-user] [duration]
Runs iperf3 test from this machine to <target-host> using SSH to start/stop the server.

Defaults:
  remote-user = $USER
  duration    = 10 seconds
EOF
  exit 1
}

run_iperf_test() {
  local target="$1"
  local user="${2:-$USER}"
  local duration="${3:-10}"

  echo "🔍 Checking if iperf3 is installed on $target..."
  if ! ssh "$user@$target" "command -v iperf3 >/dev/null 2>&1"; then
    echo "❌ iperf3 is not installed on $target. Aborting."
    exit 1
  fi

  echo "🔄 Starting iperf3 server on $target..."
  ssh "$user@$target" "nohup iperf3 -s > /dev/null 2>&1 & echo \$! > /tmp/.iperf3.pid"

  sleep 1

  echo "📡 Running iperf3 client to $target for $duration seconds..."
  if ! iperf3 -c "$target" -t "$duration" -P 4; then
    echo "⚠️  iperf3 test failed"
  fi

  echo "🛑 Stopping iperf3 server on $target..."
  ssh "$user@$target" "kill \$(cat /tmp/.iperf3.pid) 2>/dev/null || true && rm -f /tmp/.iperf3.pid"
}

main() {
  if [[ $# -lt 1 ]]; then
    usage
  fi
  run_iperf_test "$@"
}

main "$@"

Final Thoughts

It’s a small thing, but being able to spin up a remote iperf3 test in one step has saved me tons of clicks and mental overhead.

More than that, the pattern of starting remote processes over SSH and tracking their PIDs for cleanup has proven useful in other scripts too. iperfer.sh just happens to be where I reached for it first.

If you try it or adapt the pattern for something else, I’d love to hear about it. Feedback and ideas always welcome: feedback@adminjitsu.com