Bufferbane

High-precision network quality monitoring with bufferbloat detection

Bufferbane detects fine-grained network issues on cable internet connections (DOCSIS). It performs per-second measurements to identify latency spikes, jitter, packet loss, and bufferbloat that traditional tools miss.

Bufferbloat: Excessive buffering in network equipment that causes high latency during heavy traffic. Common on cable internet, it makes real-time applications (gaming, video calls) unusable even when bandwidth is available.

Features

✅ Continuous Monitoring

Per-second ICMP latency tests to multiple targets
Microsecond-precision timestamps
Real-time console output or quiet mode (hourly statistics)

✅ Data Collection & Analysis

SQLite database with efficient indexing
Alert detection (latency, jitter, packet loss)
Query by time range, target, or connection type

✅ Export & Visualization

Interactive HTML charts with hover tooltips and clickable legends
Static PNG charts with min/max/avg/P95/P99 lines
CSV export for spreadsheet analysis
Configurable time ranges and aggregation levels

✅ Server Mode (Optional - Phase 2)

Encrypted UDP protocol for accurate measurements
One-way latency tracking (upload vs download)
Built-in clock synchronization
Easy deployment with setup script

Quick Start

Installation

# Clone repository
git clone https://github.com/schuellerf/bufferbane.git
cd bufferbane

# Build and install as systemd service (recommended)
make install
sudo make install-service

# Or just build locally
make

Configuration

# Copy and edit configuration template
cp client.conf.template client.conf
nano client.conf

Run

# Run locally (verbose)
./target/release/bufferbane

# Run as systemd service (quiet mode with hourly stats)
sudo systemctl start bufferbane
sudo journalctl -u bufferbane -f

Usage

Monitoring

# Start continuous monitoring
./target/release/bufferbane

Export Data

# Generate interactive HTML chart (last 24h)
make chart-interactive

# Generate PNG chart (last 24h)
make chart

# Export to CSV
make export

Time ranges:

# Last 6 hours
./target/release/bufferbane --chart --interactive --last 6h

# Specific date range
./target/release/bufferbane --chart --interactive \
  --start "2025-10-18 18:00" \
  --end "2025-10-18 22:00"

Chart features:

Hover to see detailed statistics (min/max/avg/P95/P99)
Click legend or stat panels to hide/show series
Aggregated into 100 time windows (configurable with --segments)
Line breaks at data gaps > 5 minutes

Server Setup (Optional)

# Automated server deployment
./setup-server.sh your-server-hostname

# Or manual setup
make build-server-static
# ... copy to server, configure, run

See INSTALL.md for detailed installation guide.

Use Cases

Diagnose Evening Slowdowns

# Run continuously
./target/release/bufferbane &

# Next day, visualize the evening period
./target/release/bufferbane --chart --interactive \
  --start "2025-10-18 18:00" --end "2025-10-18 23:00"

Result: Visual proof of ISP congestion during peak hours.

Prove Connection Issues to ISP

# Collect data for a week
sudo systemctl enable --now bufferbane

# Generate report
./target/release/bufferbane --export --last 7d --output isp_complaint.csv
./target/release/bufferbane --chart --last 7d --output latency_proof.png

Result: Hard evidence of consistent latency spikes or packet loss.

Makefile Targets

make                    # Build client
make install            # Install binary to /usr/local/bin
make install-service    # Install and enable systemd service

make clean              # Remove build artifacts
make clean-data         # Remove generated charts, CSV, and database

make chart              # Generate PNG chart (last 24h)
make chart-interactive  # Generate HTML chart (last 24h)
make export             # Export CSV (last 24h)

make build-server       # Build server (dynamic linking)
make build-server-static # Build static server (for deployment)
make windows            # Cross-compile for Windows

Roadmap

Documentation

INSTALL.md - Complete installation guide with troubleshooting
UBUNTU_SETUP.md - Ubuntu-specific ICMP setup (no sudo required)
DATA_AGGREGATION_README.md - Data retention and cleanup
CHANGELOG.md - Version history and changes
docs/USAGE.md - Usage examples and command reference
docs/planning/ - Technical specifications and research

Project Structure

bufferbane/
├── client/              # Main application
│   ├── src/
│   │   ├── charts/      # Chart generation (PNG & HTML)
│   │   ├── config/      # Configuration management
│   │   ├── testing/     # ICMP and server testing
│   │   ├── storage/     # SQLite database
│   │   ├── analysis/    # Alert detection
│   │   └── output/      # Console & CSV export
│   └── templates/       # HTML chart template
├── server/              # Optional server component
├── protocol/            # Shared protocol library
├── docs/planning/       # Planning documents
├── Makefile            # Build automation
└── *.conf.template     # Configuration templates

Troubleshooting

ICMP Permission Denied

# Set capability (recommended)
sudo setcap cap_net_raw+ep ./target/release/bufferbane

# Or run with sudo
sudo ./target/release/bufferbane

Database Locked

Only run one instance at a time, or use separate database files via configuration.

No Data in Charts

Ensure bufferbane has been running and collecting data for the specified time range.

Contributing

Contributions welcome! Please ensure:

Code follows Rust best practices
Tests pass: cargo test
Builds without warnings: cargo build --release
Documentation is updated

License

MIT License - see LICENSE

schuellerf/bufferbane