LAN Performance

This recipe runs a quick LAN throughput test with iperf3, updates a TerminalWidget target, and also prints the measured Mbps to STDOUT.

It is designed for a Synology host running iperf3 (default host alias: syn), but it also works on other Linux/Unix systems with minimal changes to host and binary paths.

Script path:

• _{/bin/widget-network-perf}.sh

1) Requirements

Install and verify:

• ssh access to the remote host alias (default: syn)
• iperf3 on the remote host at /usr/local/bin/iperf3 (this path is common on Synology; adjust on other systems)
• local client binary iperf3-darwin in PATH
• terminal-widget CLI in PATH

Quick checks:

command -v ssh
command -v iperf3-darwin
command -v terminal-widget
ssh syn 'command -v /usr/local/bin/iperf3'

2) Make It Executable

chmod +x ~/scripts/widget-network-perf.sh

3) Configure Variables

Open the script and edit the variables at the top if needed:

• SSH_HOST
• IPERF_SERVER_BIN
• IPERF_CLIENT_BIN
• IPERF_CLIENT_TARGET
• REMOTE_SERVER_LOG
• WIDGET_TARGET
• WIDGET_TITLE
• WIDGET_BG
• WIDGET_FG

This is intentionally grouped at the top so sharing/customization is easy.

4) Run Manually

~/scripts/widget-network-perf.sh

Expected behavior:

• Starts a one-shot iperf3 server remotely
• Runs local iperf client against IPERF_CLIENT_TARGET
• Updates widget target network_perf with multiline text:
  • LAN Performance
  • <mbps>Mb/s
  • timestamp (%m/%d %H:%M)
• Prints raw Mbps value to STDOUT

5) Use As a TerminalWidget Recipe

Use your existing TerminalWidget recipe mechanism and set the command to:

~/scripts/widget-network-perf.sh

Recommended:

• Refresh interval: 5-15 minutes for a stable signal
• Keep widget target as network_perf unless you want a different widget ID

6) Troubleshooting

If the widget does not update:

• Confirm terminal-widget is installed and in PATH
• Run script directly in Terminal to see STDERR output
• Confirm remote host alias resolves and allows SSH

If throughput cannot be parsed:

• iperf output format may differ; run:

iperf3-darwin -c Cyberzerk.local

• verify output includes Mbits/sec on sender or receiver summary lines

#!/usr/bin/env bash

# Editable settings for sharing/reuse
SSH_HOST="syn"
IPERF_SERVER_BIN="/usr/local/bin/iperf3"
IPERF_CLIENT_BIN="iperf3-darwin"
IPERF_CLIENT_TARGET="Cyberzerk.local"
REMOTE_SERVER_LOG="/tmp/iperf3-server.log"

WIDGET_TARGET="network_perf"
WIDGET_TITLE="LAN Performance"
WIDGET_BG="rgba(18, 116, 117, 1.00)"
WIDGET_FG="rgba(245, 223, 187, 1.00)"

remote_pid="$(ssh "$SSH_HOST" "nohup $IPERF_SERVER_BIN -s -1 >$REMOTE_SERVER_LOG 2>&1 & echo \\$!")"
ssh_status=$?

if [ "$ssh_status" -ne 0 ]; then
	echo "Failed to start remote iperf3 server on $SSH_HOST" >&2
	exit 1
fi

if [ -z "$remote_pid" ]; then
	echo "Remote iperf3 server PID was not returned" >&2
	exit 1
fi

sleep 1

iperf_output="$($IPERF_CLIENT_BIN -c "$IPERF_CLIENT_TARGET" 2>&1)"
iperf_status=$?

ssh "$SSH_HOST" "kill $remote_pid" >/dev/null 2>&1 || true

if [ "$iperf_status" -ne 0 ]; then
	echo "iperf3 client command failed" >&2
	printf '%s\n' "$iperf_output" >&2
	exit 1
fi

mbps="$(printf '%s\n' "$iperf_output" | awk '/sender$/ {for (i = 1; i <= NF; i++) if ($i == "Mbits/sec") {print $(i - 1); exit}}')"

if [ -z "$mbps" ]; then
	mbps="$(printf '%s\n' "$iperf_output" | awk '/receiver$/ {for (i = 1; i <= NF; i++) if ($i == "Mbits/sec") {print $(i - 1); exit}}')"
fi

if [ -z "$mbps" ]; then
	echo "Could not parse total Mbits/sec from iperf output" >&2
	printf '%s\n' "$iperf_output" >&2
	exit 1
fi

printf '%s\n%sMb/s\n%s\n' "$WIDGET_TITLE" "$mbps" "$(date '+%m/%d %H:%M')" |
	terminal-widget --target "$WIDGET_TARGET" --text - --fit-text --bg "$WIDGET_BG" --fg "$WIDGET_FG" >/dev/null 2>&1 || true

printf '%s\n' "$mbps"

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.terminalwidget.lan-performance</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>~/bin/lan-performance.sh</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>StartInterval</key>
  <integer>3600</integer>
  <key>StandardOutPath</key>
  <string>/tmp/com.terminalwidget.lan-performance.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/com.terminalwidget.lan-performance.err</string>
</dict>
</plist>

mkdir -p ~/bin ~/Library/LaunchAgents
# Save your script to ~/bin/lan-performance.sh
cat > ~/Library/LaunchAgents/com.terminalwidget.lan-performance.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.terminalwidget.lan-performance</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>~/bin/lan-performance.sh</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>StartInterval</key>
  <integer>3600</integer>
  <key>StandardOutPath</key>
  <string>/tmp/com.terminalwidget.lan-performance.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/com.terminalwidget.lan-performance.err</string>
</dict>
</plist>
EOF
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.terminalwidget.lan-performance.plist