Network-debug – A CLI tool to fix slow Wi-Fi and poor network tuning on Linux

7 hours ago 2

A comprehensive CLI tool for diagnosing Wi-Fi bottlenecks and optimizing network performance on Linux systems. Built for developers, system administrators, and power users who need production-grade network optimization with safety-first design.

Comprehensive Network Diagnosis: Automatically detects Wi-Fi, DNS, TCP, and driver configuration issues
Safety-First Design: Dry-run simulation, timestamped backups, and rollback capabilities
Interactive & Automated Modes: Choose between guided optimization or fully automated safe fixes
Cross-Distribution Support: Works on Ubuntu, Pop!_OS, Arch, Fedora, Alpine, and containers
Professional Reporting: JSON export, Markdown reports, and before/after benchmarking
Modular Architecture: Plugin-based optimization rules with 6 built-in modules

# Download and make executable chmod +x network_debug.py # Check system dependencies ./network_debug.py --check-deps # Run comprehensive diagnosis ./network_debug.py --diagnose # Apply safe optimizations (requires root) sudo ./network_debug.py --auto-fix --dry-run # Simulate first sudo ./network_debug.py --auto-fix # Apply changes

Python: 3.7 or higher
Platform: Linux (any distribution)
Privileges: Root access required for system-level optimizations

# Install Python dependency pip install PyYAML>=5.1 # Or install system-wide sudo apt install python3-yaml # Ubuntu/Debian sudo dnf install python3-PyYAML # Fedora sudo pacman -S python-yaml # Arch sudo apk add py3-yaml # Alpine

For full functionality, install these system utilities:

# Ubuntu/Debian sudo apt install iw wireless-tools ethtool speedtest-cli iperf3 dnsutils # Fedora sudo dnf install iw wireless-tools ethtool speedtest-cli iperf3 bind-utils # Arch Linux sudo pacman -S iw wireless_tools ethtool speedtest-cli iperf3 bind # Alpine Linux sudo apk add iw wireless-tools ethtool speedtest-cli iperf3 bind-tools

# Comprehensive network diagnosis ./network_debug.py --diagnose # Speed test only ./network_debug.py --check-speed # List available optimization rules ./network_debug.py --list-rules # Check system dependencies ./network_debug.py --check-deps

# Simulate optimizations (no changes made) ./network_debug.py --auto-fix --dry-run # Apply safe optimizations sudo ./network_debug.py --auto-fix # Interactive mode with user prompts sudo ./network_debug.py --interactive # Quick performance tuning sudo ./network_debug.py --tune

# Generate optimization suggestions only ./network_debug.py --optimize-suggestions # System configuration analysis ./network_debug.py --crawl-config --output system-config.json # Before/after performance benchmarking ./network_debug.py --benchmark-before # ... apply optimizations ... ./network_debug.py --benchmark-after --output benchmark-report.md # Export detailed diagnostics ./network_debug.py --expert-json --output diagnostic.json # Skip specific optimization categories ./network_debug.py --auto-fix --skip-rule vpn --skip-rule driver # Use custom configuration ./network_debug.py --auto-fix --config custom-rules.yaml

Option Description

--diagnose	Perform comprehensive network diagnosis (default)
--check-speed	Run network speed test only
--tune	Apply automatic performance optimizations
--auto-fix	Automatically apply safe optimizations
--interactive	Interactively prompt before applying each optimization
--optimize-suggestions	Generate optimization suggestions without applying
--benchmark-before	Run baseline benchmark and save measurements
--benchmark-after	Run benchmark and compare with baseline
--benchmark-report	Generate markdown benchmark comparison report
--crawl-config	Analyze system configuration files and parameters
--expert-json	Export detailed diagnostic data as JSON
--list-rules	List all available optimization rules
--check-deps	Check availability of system dependencies
--dry-run	Simulate changes without modifying system
--no-color	Disable colored output
--verbose, -v	Enable verbose debug output
--output, -o	Specify output file for JSON/Markdown export
--skip-rule	Skip specific optimization rule (can be used multiple times)
--config	Path to configuration YAML file for rule settings
--version	Show program version

============================================================ Network Diagnostic Results ============================================================ System Information: Hostname: pop-os Distribution: Pop!_OS Kernel: 6.12.10-76061203-generic Timestamp: 2025-07-08 15:04:35 Network Interfaces: enp7s0: DOWN (ethernet, r8169) wlo1: UP (wifi, iwlwifi) Wi-Fi Information: Interface: wlo1 SSID: SHAW-F528 Frequency: 5.2 GHz (5GHz) Channel: 44 Signal: -30 dBm Bitrate: 1.2009 Gb/s Diagnostic Findings: [⚠] WARNING: • Power saving enabled on wlo1 → Disable power saving for better performance: iw wlo1 set power_save off [i] INFO: • TCP tuning can improve performance → Add to /etc/sysctl.conf: net.core.rmem_max = 134217728 net.core.wmem_max = 134217728 net.ipv4.tcp_window_scaling = 1 Summary: 1 Warning, 1 Info System Context: Wi-Fi interface: ✓ Available Internet access: ✓ Connected Init system: systemd Network tools: ✓ 7/7 tools available ✓ Full diagnostic capability ============================================================

$ sudo ./network_debug.py --tune --dry-run Dry-run mode: No system changes will be made Simulating performance tuning... → Would disable power saving on wlo1 Would execute: iw wlo1 set power_save off Simulating TCP optimization parameters... → Would update /etc/sysctl.conf with: net.core.rmem_max = 134217728 net.core.wmem_max = 134217728 net.ipv4.tcp_window_scaling = 1 net.ipv4.tcp_timestamps = 1 net.ipv4.tcp_sack = 1 Would run 'sysctl -p /etc/sysctl.conf' Would verify all parameters are set correctly

$ ./network_debug.py --check-deps Dependency Status: Required: ✓ ping ✓ ip Recommended: ✓ iperf3 ✓ speedtest-cli ✓ iw ✓ ethtool ✓ nmcli Optional: ✓ dig ✓ nslookup ✓ iwconfig ✓ rfkill

The tool includes 6 built-in optimization modules:

Rule Category Description

TCP	System	TCP buffer optimization, congestion control, window scaling
Wi-Fi	Wireless	Power management, band selection, signal strength analysis
DNS	Network	DNS server performance, caching configuration
Driver	Hardware	Known driver issues and optimizations
Interface	Hardware	Network interface hardware settings
VPN	Network	VPN detection and performance recommendations

Create custom optimization rules by adding Python files to the rules/ directory:

""" Custom optimization rules. """ from typing import List from network_debug import OptimizationRule, Severity def analyze(context) -> List[OptimizationRule]: """Analyze system and return optimization rules""" rules = [] # Your custom analysis logic here # Access system data via context.system_config, context.interfaces, etc. rules.append(OptimizationRule( name="Custom Optimization", category="Custom", severity=Severity.INFO, description="Custom optimization description", current_value="current", recommended_value="recommended", rationale="Why this optimization helps", fix_command="command to apply fix", impact="Expected performance improvement", safe_to_auto_apply=True )) return rules

Root Privilege Enforcement: System-level changes require explicit root access
Dry-Run Simulation: Preview all changes before applying them
Timestamped Backups: Automatic backup of all modified configuration files
Rollback Capability: Automatic rollback on failed verification
Verification Checks: Confirm all applied settings are working correctly
No Silent Changes: All modifications are logged and reported