Metadata-Version: 2.4
Name: tcptune
Version: 0.1.0
Summary: CLI to tune Linux TCP/sysctl, detect bottlenecks, adjust buffers (BDP), and visualize congestion.
Author-email: Jax <muxover@jax-development.com>
License: MIT
Project-URL: Repository, https://github.com/muxover/tcptune
Project-URL: Changelog, https://github.com/muxover/tcptune/blob/main/CHANGELOG.md
Keywords: linux,tcp,sysctl,networking,performance,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Dynamic: license-file

# TcpTune

<div align="center">

[![CI](https://github.com/muxover/tcptune/actions/workflows/ci.yml/badge.svg)](https://github.com/muxover/tcptune/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Tune Linux TCP/sysctl, detect bottlenecks, adjust buffers (BDP), and visualize congestion — from one CLI.**

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Commands](#-commands--api-overview) • [Configuration](#️-configuration) • [Contributing](#-contributing) • [License](#-license)

</div>

---

A CLI for server admins and power users who want to optimize Linux network stack settings without memorizing sysctl keys or BDP math. It applies presets, recommends buffer sizes from bandwidth and RTT, detects retransmissions and drops, and shows a live view of TCP behavior. **Linux only**; many write operations require root.

## ✨ Features

- **Tune** — Apply named presets (conservative, throughput, low-latency, wan) to sysctl with dry-run and optional backup.
- **Detect** — Spot bottlenecks from `/proc/net/snmp` and interface stats (retransmission rate, drops).
- **Buffers** — Compute BDP from bandwidth and RTT; recommend and optionally apply `tcp_rmem`/`tcp_wmem` and core limits.
- **Viz** — Live terminal view of retransmission rate and connection count over time.
- **Info** — Print current congestion control, qdisc, and key buffer settings.
- **Report** — Export sysctl and TCP stats as JSON or HTML.

## 📦 Installation

On modern Linux (Debian 12+, Ubuntu 22.04+) the system Python is externally managed (PEP 668). Use a virtual environment or pipx — do **not** use `pip install .` against the system Python.

**From source (recommended):**

```bash
git clone https://github.com/muxover/tcptune.git
cd tcptune
python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
pip install .

# Or editable
pip install -e .
```

Then run the CLI as `tcptune` (or `python -m tcptune`) while the venv is active. To get a single global install without activating a venv each time, use **pipx**:

```bash
pipx install .
# or from a clone: pipx install /path/to/tcptune
```

Requires **Python 3.10+** and **Linux**. Tuning (write) operations require root.

## 🚀 Quick Start

```bash
# See current settings
tcptune info

# Check for bottlenecks (no root)
tcptune detect

# Recommend buffers for 1 Gbps, 2 ms RTT
tcptune buffers --bandwidth 1Gbps --rtt 2ms

# Apply a preset (root)
sudo tcptune tune --preset throughput --dry-run   # preview
sudo tcptune tune --preset throughput --backup backup.json

# Live view for 30 seconds
tcptune viz --duration 30
```

## 📋 Commands / API Overview

| Command | Description |
|--------|-------------|
| `tune --preset NAME [--dry-run] [--backup FILE]` | Apply a sysctl preset (throughput, low-latency, wan, conservative). |
| `detect [--json-output]` | Detect bottlenecks (retrans rate, interface drops). |
| `buffers -b BANDWIDTH -r RTT [--apply] [--dry-run]` | BDP-based buffer recommendation; optional apply. |
| `info` | Print current key sysctl and kernel version. |
| `viz [--duration 30] [--refresh 1]` | Live view of retrans rate and connections. |
| `report [--json PATH] [--html PATH]` | Export snapshot to JSON and/or HTML. |

## ⚙️ Configuration

| Flag / option | Description |
|---------------|-------------|
| `--dry-run` (tune, buffers) | Show changes without writing. |
| `--backup FILE` (tune) | Save current sysctl to JSON before applying. |
| `--json-output` (detect) | Machine-readable findings. |
| `--duration`, `--refresh` (viz) | Viz duration (seconds) and refresh interval. |

No config file in v0.1.0; all options are CLI flags.

## 🏗️ Project Layout

```
tcptune/
  pyproject.toml
  src/tcptune/
    cli.py       # CLI and subcommands
    sysctl.py    # /proc/sys read/write
    procfs.py    # /proc/net/snmp, netstat
    bdp.py       # BDP and buffer recommendations
    presets.py   # Tuning presets
    detect.py    # Bottleneck detection
    viz.py       # Live visualization
    report.py    # JSON/HTML export
    info.py      # Current settings summary
    _linux.py    # Platform and root checks
  tests/
```

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## 📄 License

Licensed under [MIT](LICENSE).

## 🔗 Links

- **Repository**: https://github.com/muxover/tcptune
- **Issues**: https://github.com/muxover/tcptune/issues
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)

---

<div align="center">
Made with ❤️ by Jax (@muxover)
</div>
