XFR(1)

NAME
xfr - modern network bandwidth testing with TUI

SYNOPSIS
xfr [OPTIONS] HOST
xfr serve [OPTIONS]
xfr diff BASELINE CURRENT [OPTIONS]
xfr discover [OPTIONS]

DESCRIPTION
xfr is a fast, modern network bandwidth testing tool with a terminal user interface. It is designed as a replacement for iperf with additional features like live TUI, multi-client server support, QUIC transport, and result comparison.

CLIENT OPTIONS

-p, --port PORT
    Server port (default: 5201). Environment: XFR_PORT

-t, --time DURATION
    Test duration (default: 10s). Supports units: s, m, h. Environment: XFR_DURATION

-u ,  --udp
    Use UDP instead of TCP

-Q ,  --quic
    Use QUIC transport (encrypted, multiplexed streams over UDP)

-b, --bitrate RATE
    Target bitrate for UDP mode (e.g., 1G, 100M, 10K)

-P, --parallel N
    Number of parallel streams (default: 1)

-R ,  --reverse
    Reverse direction (server sends to client, i.e., download test)

--bidir
    Bidirectional test (both upload and download)

--json
    Output results as JSON

--json-stream
    JSON streaming output (one JSON object per line per interval)

--csv
    CSV output format

-q ,  --quiet
    Quiet mode - suppress interval output, show only summary

-o, --output FILE
    Save results to file

--no-tui
    Disable terminal UI, use plain text output

--theme THEME
    Color theme: default, kawaii, cyber, dracula, monochrome, matrix, nord, gruvbox, catppuccin, tokyo_night, solarized

-i, --interval SECS
    Report interval in seconds (default: 1.0)

--omit N
    Omit first N seconds from interval output (TCP ramp-up)

--tcp-nodelay
    Disable Nagle algorithm (TCP_NODELAY)

--window SIZE
    TCP window size (e.g., 512K, 1M, 4M)

--congestion ALGO
    TCP congestion control algorithm (e.g., cubic, bbr, reno). Applied on both client and server sockets via setsockopt(TCP_CONGESTION). Requires kernel support for the selected algorithm.

--timestamp-format FORMAT
    Timestamp format: relative (default), iso8601, unix

--log-file PATH
    Log file path (e.g., ~/.config/xfr/xfr.log)

--log-level LEVEL
    Log level: error, warn, info, debug, trace

--psk KEY
    Pre-shared key for server authentication. Environment: XFR_PSK

--psk-file FILE
    Read PSK from file

-4 ,  --ipv4
    Force IPv4 only

-6 ,  --ipv6
    Force IPv6 only

--bind ADDR
    Local address to bind to (e.g., 192.168.1.100 or ::1)

--cport PORT
    Client source port for firewall traversal (UDP/QUIC only)

--mptcp
    Use MPTCP (Multi-Path TCP, Linux 5.6+)

--random
    Use random payload data (default for TCP/UDP client-sent traffic)

--zeros
    Use zero-filled payload data instead of random bytes

--completions SHELL
    Generate shell completions: bash, zsh, fish, powershell, elvish

SERVER OPTIONS

-p, --port PORT
    Listen port (default: 5201). Environment: XFR_PORT

--one-off
    Exit after a single test

--tui
    Enable TUI dashboard showing active tests

--max-duration DURATION
    Maximum test duration (server-side limit)

--push-gateway URL
    Prometheus push gateway URL (e.g., http://pushgateway:9091)

--log-file PATH
    Log file path

--log-level LEVEL
    Log level: error, warn, info, debug, trace

--psk KEY
    Pre-shared key for authentication. Environment: XFR_PSK

--psk-file FILE
    Read PSK from file

--rate-limit N
    Max concurrent tests per IP

--rate-limit-window DURATION
    Rate limit time window (default: 60s)

--allow IP/SUBNET
    Allow IP or subnet (can be repeated)

--deny IP/SUBNET
    Deny IP or subnet (can be repeated)

--acl-file FILE
    Load ACL rules from file

-B, --bind IP
    Bind to specific address (e.g., 192.168.1.1, ::1). Rejects unspecified addresses; use -4/-6 instead to control address family. Validates against -4/-6 flags.

--no-mdns
    Disable mDNS service registration. By default the server registers itself via mDNS for automatic discovery by xfr discover. Use this flag when another service already uses mDNS or when running in environments where multicast is unwanted.

-4 ,  --ipv4
    Force IPv4 only

-6 ,  --ipv6
    Force IPv6 only

DIFF OPTIONS

--threshold PERCENT
    Regression threshold percentage (default: 0)

DISCOVER OPTIONS

--timeout DURATION
    Discovery timeout (default: 5s)

CONFIGURATION
xfr reads configuration from ~/.config/xfr/config.toml if present. CLI arguments override config file values. Environment variables override config file.

Example config:
    [client]
    duration_secs = 30
    parallel_streams = 4
    theme = "dracula"
    [server]
    port = 5201
    psk = "secret"
    rate_limit = 5
    no_mdns = false
    allow = ["192.168.0.0/16"]

ENVIRONMENT

XFR_PORT
    Server/client port

XFR_DURATION
    Test duration

XFR_PSK
    Pre-shared key

XFR_PUSH_GATEWAY
    Prometheus push gateway URL

XFR_LOG_FILE
    Log file path

XFR_LOG_LEVEL
    Log level

XFR_TIMESTAMP_FORMAT
    Timestamp format

EXAMPLES

xfr 192.168.1.1
    Run a 10-second TCP upload test

xfr 192.168.1.1 -t 30s -P 4
    30-second test with 4 parallel streams

xfr 192.168.1.1 -R
    Download test (server sends to client)

xfr 192.168.1.1 -u -b 1G
    UDP test at 1 Gbps

xfr 192.168.1.1 --quic
    QUIC encrypted test

xfr 192.168.1.1 --json --no-tui
    JSON output for scripting

xfr 192.168.1.1 --zeros
    Use zero-filled payloads for compression/dedup testing

xfr serve
    Start server on default port 5201

xfr serve --tui
    Start server with live dashboard

xfr serve --psk secret --rate-limit 2
    Authenticated server with rate limiting

xfr serve --allow 192.168.0.0/16 --deny 0.0.0.0/0
    Server with IP access control

xfr diff baseline.json current.json --threshold 5
    Compare results, fail if throughput drops more than 5%

xfr discover
    Find xfr servers on the local network via mDNS

EXIT STATUS

0   Success

1   Error or regression detected (with diff command)

2   Invalid arguments

3   Server rejected test (auth, rate limit, ACL)

FILES

~/.config/xfr/config.toml
    User configuration file

~/.config/xfr/prefs.toml
    User preferences (theme)

SEE ALSO
iperf3(1)

BUGS
Report bugs at: https://github.com/lance0/xfr/issues

AUTHOR
lance0