netwatch

A modern network traffic monitor for Unix systems, inspired by nload but written in Rust with enhanced features and beautiful terminal interfaces.

✨ Features

Core Monitoring

• Real-time network monitoring - Live bandwidth and packet statistics
• Multi-interface support - Monitor multiple network interfaces simultaneously
• Cross-platform - Native support for Linux and macOS
• nload compatibility - Drop-in replacement with all nload command-line options

Advanced Analytics

• SRE Dashboard - Advanced network forensics and diagnostics
• Active Diagnostics - Real-time connectivity testing and health monitoring
• Connection Tracking - Monitor TCP/UDP connections with process information
• Performance Analysis - Bottleneck detection and network quality metrics
• System Integration - CPU, memory, and disk usage correlation

Modern Interface

• Beautiful Terminal UI - Rich, colorful terminal interface with graphs
• Multiple Display Modes - Dashboard, simple overview, or classic nload-style
• Interactive Controls - Keyboard shortcuts for navigation and configuration
• Export Capabilities - Log to files in various formats

Quick Start

Installation

Automated Installation (Recommended)

# Install latest version
curl -sSL https://raw.githubusercontent.com/vietcgi/netwatch/main/install.sh | bash

# Or with wget
wget -qO- https://raw.githubusercontent.com/vietcgi/netwatch/main/install.sh | bash

# Install to custom directory
INSTALL_DIR=~/.local/bin curl -sSL https://raw.githubusercontent.com/vietcgi/netwatch/main/install.sh | bash

Package Managers

# Rust/Cargo
cargo install netwatch-rs

# Homebrew (macOS)
brew install netwatch

# Docker
docker run --rm -it --net=host ghcr.io/vietcgi/netwatch:latest

Manual Download

Download pre-built binaries from the Releases page for:

• Linux x86_64 (glibc & musl)
• Linux ARM64 (glibc & musl)
• macOS x86_64 & ARM64

From Source

git clone https://github.com/vietcgi/netwatch
cd netwatch
cargo install --path .

Basic Usage

# Auto-detect and monitor default interface
netwatch

# List available interfaces
netwatch --list

# Monitor specific interface
netwatch en0

# SRE forensics dashboard mode
netwatch --sre-terminal

# Simple overview mode
netwatch --show-overview

# Monitor multiple interfaces
netwatch -m

📊 Display Modes

1. SRE Dashboard (Default)

Advanced network forensics interface with:

• Real-time connection analysis
• Active diagnostics and health checks
• Performance bottleneck detection
• System resource correlation
• Security monitoring alerts

2. Simple Overview

Clean, minimal interface showing:

• Interface statistics
• Bandwidth utilization
• Packet counts and rates
• Error summaries

3. Multi-Interface Mode

Monitor multiple interfaces with:

• Side-by-side comparisons
• Aggregate statistics
• Per-interface details

⚙️ Command Line Options

Core Options (nload compatible)

-l, --list                    List available network interfaces
-a, --average <seconds>       Average window length [default: 300]
-i, --incoming <kBit/s>       Max incoming bandwidth scale (0 = auto)
-o, --outgoing <kBit/s>       Max outgoing bandwidth scale (0 = auto)
-t, --interval <ms>           Refresh interval in milliseconds [default: 1000]
    --high-perf               Enable high performance mode (slower updates, less CPU, optimized security)
-u, --unit <unit>             Traffic unit format [default: k]
-U, --data-unit <unit>        Data unit for totals [default: M]
-m, --multiple                Show multiple devices
-f, --file <path>             Log traffic data to file

Display Modes

--sre-terminal               SRE forensics dashboard mode
--show-overview              Simple overview mode
--debug-dashboard            Debug mode with detailed metrics
--test                       Test mode - single output and exit
--force-terminal             Force terminal mode (no TUI)

Unit Formats

• h - Human-readable bits (auto-scaling)
• H - Human-readable bytes (auto-scaling)
• k/K - Kilobits/Kilobytes
• m/M - Megabits/Megabytes
• g/G - Gigabits/Gigabytes
• b/B - Raw bits/bytes

🎮 Interactive Controls

Navigation

• Arrow keys - Navigate between interfaces/sections
• Tab - Switch between dashboard panels
• Enter - Select/drill down into details

Display Controls

• Space - Pause/resume monitoring
• r - Reset statistics
• g - Toggle graph display
• +/- - Zoom graph scale
• u - Cycle through unit formats

System Controls

• F2 - Show options/settings
• F5 - Save current configuration
• F6 - Reload configuration
• q or Ctrl+C - Quit

📁 Configuration

Configuration Files

Configuration is stored in TOML format:

• ~/.netwatch/config.toml - Primary configuration
• ~/.nload - nload compatibility mode

Example Configuration

# ~/.netwatch configuration file
AverageWindow = 300
BarMaxIn = 0
BarMaxOut = 0
DataFormat = "M"
Devices = "all"
MultipleDevices = false
RefreshInterval = 500
TrafficFormat = "k"

# Active Diagnostics Configuration
# These targets will be tested for connectivity and performance
DiagnosticTargets = [
    "1.1.1.1",           # Cloudflare DNS (fast, privacy-focused)
    "8.8.8.8",           # Google DNS (widely accessible)
    "9.9.9.9"            # Quad9 DNS (security-focused)
]

# DNS domains to test for resolution performance
DNSDomains = [
    "cloudflare.com",    # Reliable test domain
    "google.com",        # Reliable test domain
    "github.com"         # Development-relevant domain
]

Note: See example.netwatch in the repository for a complete configuration template.

🔧 Building from Source

Requirements

• Rust 1.70+ - Latest stable Rust toolchain
• Unix-like system - Linux, macOS, or BSD
• Development tools - git, cargo

Build Process

# Clone repository
git clone https://github.com/vietcgi/netwatch
cd netwatch

# Build release version
cargo build --release

# Run tests
cargo test

# Install locally
cargo install --path .

Development

# Run with debug logging
RUST_LOG=debug cargo run

# Run specific interface
cargo run -- en0

# Run tests with output
cargo test -- --nocapture

# Format code
cargo fmt

# Lint code
cargo clippy

🧪 Testing

Test Interface

# Test mode - single output and exit
netwatch --test

# Debug dashboard without TUI
netwatch --debug-dashboard

# List interfaces (good for CI)
netwatch --list

📈 Performance

• Memory efficient - Rust's zero-cost abstractions
• Low CPU overhead - Optimized for continuous monitoring
• Scalable - Handles hundreds of network interfaces
• Battery friendly - Configurable refresh intervals

🔒 Security

• Memory safe - Rust prevents buffer overflows and memory leaks
• Privilege separation - Runs with minimal required permissions
• No network transmission - Only reads local system statistics
• Input validation - All inputs are validated and sanitized

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/vietcgi/netwatch
cd netwatch

# Initial setup (installs git hooks, builds project)
make setup

# Development workflow
make dev          # Run fmt, clippy, and tests
make check        # Run all quality checks
make help         # Show all available commands

Git Hooks

This project uses automated git hooks for code quality:

• Pre-commit: Runs cargo fmt, cargo clippy, and cargo test
• Auto-installation: Run make setup or ./scripts/setup-hooks.sh

Development Commands

make build        # Build the project  
make test         # Run tests
make fmt          # Format code
make clippy       # Run linting
make clean        # Clean build artifacts
make install      # Install locally
make watch        # Watch for changes

Package Information

• Crate name: netwatch-rs (on crates.io)
• Binary name: netwatch (command users run)
• Repository: vietcgi/netwatch (GitHub)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by nload by Roland Riegel
• Built with ratatui for terminal UI
• Uses clap for command-line parsing

📞 Support

• Issues: GitHub Issues
• Security: See SECURITY.md for reporting security issues
• Discussions: GitHub Discussions

netwatch - Modern network monitoring for the terminal era