rperf3-rs

A high-performance network throughput measurement tool written in Rust, inspired by iperf3. Provides accurate bandwidth testing for TCP and UDP protocols with memory safety, async I/O, and comprehensive metrics.

What is rperf3-rs?

rperf3-rs is a modern network performance measurement tool that allows you to measure the maximum achievable bandwidth between two network endpoints. Whether you're diagnosing network performance issues, validating infrastructure upgrades, or benchmarking network equipment, rperf3-rs provides detailed, real-time statistics about your network's capabilities.

Built from the ground up in Rust, rperf3-rs leverages modern async I/O (via Tokio) to achieve high throughput while maintaining memory safety guarantees. Unlike traditional C-based tools, rperf3-rs eliminates entire classes of bugs (buffer overflows, use-after-free, data races) through Rust's compile-time checks.

Why rperf3-rs?

Memory Safety: Rust's ownership system eliminates memory safety bugs at compile time, making rperf3-rs more reliable than C-based alternatives. No buffer overflows, no use-after-free, no data races.

High Performance: Built on Tokio's async runtime with optimized buffer management, rperf3-rs achieves 25-30 Gbps throughput on localhost tests, matching or exceeding traditional tools.

Developer-Friendly: Clean API design with builder patterns, comprehensive error handling, and extensive documentation make integration straightforward. Use it as a CLI tool or embed it as a library.

Modern Architecture: Async/await syntax, modular design, and thread-safe statistics collection provide a solid foundation for building network testing applications.

Full-Featured: Supports TCP and UDP testing, bidirectional tests, bandwidth limiting, packet loss and jitter measurement, real-time callbacks, and JSON output for automation.

Features

• TCP & UDP Testing: Measure throughput for both reliable and unreliable protocols
• Bidirectional Testing: Normal mode (client → server) and reverse mode (server → client)
• Bandwidth Limiting: Control send rate with K/M/G notation (e.g., 100M = 100 Mbps)
• UDP Metrics: Packet loss percentage, jitter (RFC 3550), and out-of-order detection
• TCP Statistics: Retransmits, RTT, congestion window, and PMTU (Linux)
• Real-time Callbacks: Monitor test progress programmatically with event-driven callbacks
• JSON Output: Machine-readable output compatible with automation systems
• Parallel Streams: Multiple concurrent connections for aggregate testing
• Library & CLI: Use as a standalone tool or integrate as a Rust library
• Cross-Platform: Linux, macOS, and Windows support

Quick Start

Installation

From crates.io (when published):

cargo install rperf3

From source:

git clone https://github.com/arunkumar-mourougappane/rperf3-rs.git
cd rperf3-rs
cargo build --release

Binary available at target/release/rperf3.

Basic Usage

# Terminal 1 - Start server
./target/release/rperf3 server

# Terminal 2 - Run client test
./target/release/rperf3 client 127.0.0.1

Usage Examples

TCP Tests

# Basic TCP test (10 seconds)
rperf3 client 192.168.1.100

# 30-second test with custom interval
rperf3 client 192.168.1.100 -t 30 -i 2

# Reverse mode (server sends data)
rperf3 client 192.168.1.100 -R

# Reverse mode with bandwidth limiting
rperf3 client 192.168.1.100 -R -b 200M

# Parallel streams
rperf3 client 192.168.1.100 -P 4

UDP Tests

# UDP test with 100 Mbps target
rperf3 client 192.168.1.100 -u -b 100M

# UDP reverse mode with bandwidth limit
rperf3 client 192.168.1.100 -u -R -b 50M

# UDP with custom buffer size
rperf3 client 192.168.1.100 -u -b 1G -l 8192

Server Options

# Default server (port 5201)
rperf3 server

# Custom port
rperf3 server -p 8080

# Bind to specific address
rperf3 server -b 192.168.1.100

# JSON output
rperf3 server -J

Library Usage

Add to your Cargo.toml:

[dependencies]
# From crates.io (when published)
rperf3 = "0.4"

# Or from git
# rperf3 = { git = "https://github.com/arunkumar-mourougappane/rperf3-rs" }

tokio = { version = "1", features = ["full"] }

Basic Client Example

use rperf3::{Client, Config, Protocol};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::client("192.168.1.100".to_string(), 5201)
        .with_protocol(Protocol::Tcp)
        .with_duration(Duration::from_secs(10));

    let client = Client::new(config)?;
    client.run().await?;

    let measurements = client.get_measurements();
    println!("Bandwidth: {:.2} Mbps",
             measurements.total_bits_per_second() / 1_000_000.0);

    Ok(())
}

UDP Test with Metrics

use rperf3::{Client, Config, Protocol};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::client("192.168.1.100".to_string(), 5201)
        .with_protocol(Protocol::Udp)
        .with_bandwidth(100_000_000) // 100 Mbps
        .with_duration(Duration::from_secs(10));

    let client = Client::new(config)?;
    client.run().await?;

    let measurements = client.get_measurements();
    println!("Bandwidth: {:.2} Mbps", 
             measurements.total_bits_per_second() / 1_000_000.0);
    println!("Packets: {}, Loss: {} ({:.2}%), Jitter: {:.3} ms",
             measurements.total_packets,
             measurements.lost_packets,
             (measurements.lost_packets as f64 / measurements.total_packets as f64) * 100.0,
             measurements.jitter_ms);

    Ok(())
}

Progress Callbacks

use rperf3::{Client, Config, ProgressEvent};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::client("192.168.1.100".to_string(), 5201)
        .with_duration(Duration::from_secs(10));

    let client = Client::new(config)?
        .with_callback(|event: ProgressEvent| {
            match event {
                ProgressEvent::TestStarted => {
                    println!("Test started");
                }
                ProgressEvent::IntervalUpdate { bits_per_second, .. } => {
                    println!("Current: {:.2} Mbps", bits_per_second / 1_000_000.0);
                }
                ProgressEvent::TestCompleted { bits_per_second, .. } => {
                    println!("Average: {:.2} Mbps", bits_per_second / 1_000_000.0);
                }
                ProgressEvent::Error(msg) => {
                    eprintln!("Error: {}", msg);
                }
            }
        });

    client.run().await?;
    Ok(())
}

Server Example

use rperf3::{Server, Config};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::server(5201);
    let server = Server::new(config);
    
    println!("Server listening on port 5201");
    server.run().await?;
    
    Ok(())
}

Command-Line Options

Server

Client

Bandwidth Notation

Use K/M/G suffixes for bandwidth values:

• 100K = 100,000 bits/second
• 100M = 100,000,000 bits/second
• 1G = 1,000,000,000 bits/second

Performance

Typical performance on modern hardware:

• TCP localhost: 25-30 Gbps
• UDP with limiting: Accurate rate control within 2-3% of target
• Packet loss detection: Sub-millisecond precision
• Jitter measurement: RFC 3550 compliant algorithm

Built on Tokio's async runtime with optimized buffer management for maximum throughput.

JSON Output Format

Use --json flag for machine-readable output compatible with automation:

rperf3 client 192.168.1.100 -u -b 100M --json

Output includes:

• Start: Connection info, system info, test configuration
• Intervals: Per-second measurements with bytes, throughput, packets
• End: Summary statistics with jitter, packet loss, retransmits (TCP)

Architecture

┌─────────────────────────────────────┐
│        rperf3-rs Application        │
├─────────────────────────────────────┤
│  CLI (main.rs)  │  Library API      │
├─────────────────────────────────────┤
│  Client Module  │  Server Module    │
│  - TCP/UDP Send │  - TCP/UDP Recv   │
│  - Statistics   │  - Statistics     │
├─────────────────────────────────────┤
│  Measurements   │  Protocol         │
│  - Metrics      │  - Messages       │
│  - Calculations │  - Serialization  │
├─────────────────────────────────────┤
│        Tokio Async Runtime          │
└─────────────────────────────────────┘

Recent Updates

v0.4.0 (Current)

• ✅ UDP reverse mode implementation
• ✅ Bandwidth limiting for TCP and UDP
• ✅ Bidirectional bandwidth calculations
• ✅ UDP packet loss and jitter measurement (RFC 3550)
• ✅ Out-of-order packet detection
• ✅ Comprehensive documentation updates
• ✅ All clippy warnings resolved

Roadmap

Planned Features

• Enhanced parallel stream support with aggregation
• IPv6 testing and dual-stack support
• CPU utilization monitoring
• Additional output formats (CSV)
• Configurable congestion control algorithms
• SCTP protocol support

Comparison with iperf3

Contributing

Contributions welcome! Please ensure:

1. Code passes cargo fmt and cargo clippy
2. All tests pass: cargo test
3. Add tests for new features
4. Update documentation

# Development workflow
git clone https://github.com/arunkumar-mourougappane/rperf3-rs.git
cd rperf3-rs
cargo build
cargo test
cargo clippy
cargo fmt

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Acknowledgments

Inspired by iperf3 - the industry-standard network testing tool.

Author: Arunkumar Mourougappane
Repository: https://github.com/arunkumar-mourougappane/rperf3-rs