Knowledge Base

xfr

3 min read

xfr

Rust-based network bandwidth testing tool. Modern alternative to iperf3 with a live terminal UI, multi-protocol support, and Prometheus metrics export.

Usage

# Start server
xfr serve                    # Listen on port 5201
xfr serve -p 9000            # Custom port
xfr serve --tui              # Live dashboard showing active tests
xfr serve --one-off          # Exit after one test
xfr serve --max-duration 60s # Limit test duration
xfr serve --push-gateway http://pushgateway:9091  # Push metrics on test complete
xfr serve --psk mysecret     # Require PSK authentication
xfr serve --rate-limit 2     # Max 2 concurrent tests per IP
xfr serve --allow 192.168.0.0/16 --deny 0.0.0.0/0  # IP ACL
 
# Run client tests
xfr 192.168.1.1              # TCP test, 10s, single stream
xfr 192.168.1.1 -t 30s       # 30 second test
xfr 192.168.1.1 -P 4         # 4 parallel streams
xfr 192.168.1.1 -R           # Reverse (download test)
xfr 192.168.1.1 --bidir      # Bidirectional
xfr 192.168.1.1 -6           # Force IPv6 only
xfr ::1 -6                   # IPv6 localhost
 
# UDP Mode
 
xfr 192.168.1.1 -u           # UDP mode
xfr 192.168.1.1 -u -b 1G     # UDP at 1 Gbps
xfr 192.168.1.1 -u -b 100M   # UDP at 100 Mbps
 
# QUIC Mode
 
xfr 192.168.1.1 --quic       # QUIC transport (encrypted)
xfr 192.168.1.1 --quic -P 4  # QUIC with 4 parallel streams
xfr 192.168.1.1 --quic -R    # QUIC download test
 
# MPTCP Mode
 
xfr 192.168.1.1 --mptcp       # MPTCP (Multi-Path TCP, Linux 5.6+)
xfr 192.168.1.1 --mptcp -P 4  # MPTCP with 4 parallel streams
xfr 192.168.1.1 --mptcp -R    # MPTCP download test
 
# Output Formats
 
xfr <host> --json              # JSON summary
xfr <host> --json-stream       # JSON per interval (for scripting)
xfr <host> --csv               # CSV output
xfr <host> -q                  # Quiet mode (summary only)
xfr <host> -o results.json     # Save to file
xfr <host> --no-tui            # Plain text, no TUI
xfr <host> --timestamp-format iso8601  # ISO 8601 timestamps
 
# Interval Control
 
xfr <host> -i 2                # Report every 2 seconds
xfr <host> --omit 3            # Skip first 3s of intervals (TCP ramp-up)
 
# Compare Results
 
xfr diff baseline.json current.json
xfr diff baseline.json current.json --threshold 5
 
# Discovery
 
xfr discover                 # Find xfr servers on LAN
xfr discover --timeout 10s   # Extended search

Features

  • Live TUI with real-time throughput graphs and per-stream stats
  • TCP, UDP, and QUIC transport support
  • Multi-client server (simultaneous connections)
  • JSON, CSV, plain text output
  • Built-in diff for detecting throughput regressions
  • LAN discovery via mDNS
  • Prometheus metrics export

Prometheus Monitoring

Continuous performance monitoring:

# Scrape metrics or view in Grafana
xfr serve --prometheus 9090 --push-gateway http://pushgateway:9091

Graph View