xfr

A fast, modern network bandwidth testing tool with TUI. Built in Rust as an iperf replacement.

Quick Start

# Server
xfr serve

# Client (in another terminal or machine)
xfr 192.168.1.1              # Basic TCP test
xfr 192.168.1.1 -P 4         # 4 parallel streams
xfr 192.168.1.1 -u -b 1G     # UDP at 1 Gbps

Features

• Live TUI with real-time throughput graphs and per-stream stats
• Server dashboard - xfr serve --tui for monitoring active tests
• Multi-client server - handle multiple simultaneous tests
• TCP and UDP with configurable bitrate and parallel streams
• Bidirectional testing - measure upload and download simultaneously
• Multiple output formats - plain text, JSON, JSON streaming, CSV
• Result comparison - xfr diff to detect performance regressions
• LAN discovery - find xfr servers with mDNS (xfr discover)
• Prometheus metrics - export stats for monitoring dashboards
• Config file - save defaults in ~/.config/xfr/config.toml
• Environment variables - XFR_PORT, XFR_DURATION overrides

vs iperf3

Installation

From crates.io (Recommended)

cargo install xfr

From Source

git clone https://github.com/lance0/xfr
cd xfr && cargo build --release
sudo cp target/release/xfr /usr/local/bin/

With Optional Features

# Prometheus metrics support
cargo install xfr --features prometheus

# io_uring backend (Linux only, requires kernel 5.10+)
cargo install xfr --features io-uring

# All features
cargo install xfr --all-features

Usage

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 --tls --tls-cert cert.pem --tls-key key.pem  # Enable TLS
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

Client

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

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

Keybindings (Client TUI)

Keybindings (Server TUI)

Themes

xfr includes 11 built-in color themes. Select with --theme or press t during a test:

xfr host --theme dracula     # Dark purple theme
xfr host --theme matrix      # Green on black hacker style
xfr host --theme catppuccin  # Soothing pastels
xfr host --theme nord        # Arctic blue tones

Available themes: default, kawaii, cyber, dracula, monochrome, matrix, nord, gruvbox, catppuccin, tokyo_night, solarized

Your theme preference is auto-saved to ~/.config/xfr/prefs.toml.

Configuration

xfr reads defaults from ~/.config/xfr/config.toml:

[client]
duration_secs = 10
parallel_streams = 1
tcp_nodelay = false
json_output = false
no_tui = false
theme = "default"  # or dracula, catppuccin, nord, matrix, etc.
timestamp_format = "relative"  # or "iso8601", "unix"
log_file = "~/.config/xfr/xfr.log"
log_level = "info"

[server]
port = 5201
push_gateway = "http://pushgateway:9091"
log_file = "~/.config/xfr/xfr-server.log"
log_level = "info"
psk = "my-secret-key"
rate_limit = 5
allow = ["192.168.0.0/16", "10.0.0.0/8"]
audit_log = "/var/log/xfr-audit.log"
audit_format = "json"

Environment variables override config file:

export XFR_PORT=9000
export XFR_DURATION=30s

Prometheus Metrics

Enable with --features prometheus:

xfr serve --prometheus-port 9090

Metrics available at http://localhost:9090/metrics:

• xfr_bytes_total - Total bytes transferred
• xfr_throughput_mbps - Current throughput
• xfr_active_tests - Number of active tests
• xfr_retransmits_total - TCP retransmissions

See examples/grafana-dashboard.json for a sample Grafana dashboard.

CLI Reference

Platform Support

Troubleshooting

Permission denied on port 5201

Use a port above 1024 or run with elevated privileges:

xfr serve -p 9000

Connection refused

Ensure the server is running and the port is not blocked by a firewall.

Low throughput

• Try multiple parallel streams: -P 4
• Disable Nagle's algorithm: --tcp-nodelay
• Increase TCP window size: --window 4M

UDP packet loss

• Reduce bitrate: -b 500M
• Check for network congestion or firewall issues

Documentation

• Changelog - Release history
• Roadmap - Planned features
• Contributing - Development guidelines

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.