# tunectl

**Battle-tested VPS performance tuning toolkit for Ubuntu 24.04 LTS.**

Extracted from production server tuning missions — 86 tuning parameters, 3 risk tiers, automatic rollback. Battle-tested on DigitalOcean droplets (4 vCPU / 8 GB). Supports servers with 1–8 GB RAM with automatic parameter scaling.

---

## Prerequisites

| Requirement | Details |
|-------------|---------|
| **OS** | Ubuntu 24.04 LTS |
| **Python** | Python 3.x (Ubuntu 24.04 ships 3.12) |
| **Shell** | bash |
| **Node.js / npm** | Optional — only needed for `npx tunectl` usage |
| **jq** | Required by the bash scripts for JSON parsing |
| **Root access** | Required for `apply` and `rollback` commands only |

---

## Installation

### Option A: Clone and run directly

```bash
git clone https://github.com/symulacr/tunectl.git
cd tunectl
python3 -m tunectl --help
```

### Option B: Install with pip

```bash
git clone https://github.com/symulacr/tunectl.git
cd tunectl
pip install .
tunectl --help
```

### Option C: Run via npx (requires Node.js + npm)

```bash
# Run directly without cloning
npx tunectl --help

# Run any subcommand via npx
npx tunectl discover
npx tunectl plan --tier balanced
sudo npx tunectl apply --tier conservative
```

---

## Quick Start

tunectl follows a **discover → plan → apply → audit → benchmark** workflow:

```bash
# 1. Discover — detect your system environment
tunectl discover

# 2. Plan — preview tuning changes (dry-run, no modifications)
tunectl plan --tier balanced

# 3. Apply — apply the tuning (creates automatic backup first)
sudo tunectl apply --tier balanced

# 4. Audit — verify all parameters were applied correctly
tunectl audit

# 5. Benchmark — measure performance improvements
tunectl benchmark
```

For a before/after performance comparison, capture a baseline before applying:

```bash
tunectl benchmark --baseline          # Capture baseline metrics
sudo tunectl apply --tier balanced    # Apply tuning
tunectl benchmark --compare           # Compare against baseline
```

---

## Usage

### `tunectl discover`

Detect the system environment and output a JSON profile. Strictly read-only — no system modifications.

```bash
tunectl discover
```

Example output:

```json
{
  "os_version": "Ubuntu 24.04 LTS",
  "kernel_version": "6.8.0-101-generic",
  "ram_mb": 8192,
  "cpu_count": 4,
  "disk_type": "virtio",
  "swap_configured": true,
  "swap_type": "zram",
  "swap_total_mb": 4096
}
```

### `tunectl plan --tier <tier>`

Show a dry-run tuning plan for the selected tier. Displays all parameters that would be changed, their current values, and target values. No system files are modified.

```bash
# Preview conservative tier (51 entries, zero risk)
tunectl plan --tier conservative

# Preview balanced tier (80 entries, very low risk)
tunectl plan --tier balanced

# Preview aggressive tier (all 86 entries)
tunectl plan --tier aggressive
```

### `tunectl apply --tier <tier>`

Apply tuning changes for the selected tier. Automatically creates a timestamped backup before making any modifications. Requires root.

```bash
# Apply conservative tier (safest — zero breakage risk)
sudo tunectl apply --tier conservative

# Apply balanced tier (recommended for most servers)
sudo tunectl apply --tier balanced

# Apply aggressive tier (maximum performance)
sudo tunectl apply --tier aggressive
```

### `tunectl rollback`

Restore system configuration from a backup created by `tunectl apply`. By default, restores from the most recent backup. Requires root for restore operations.

```bash
# List available backups (no root needed)
tunectl rollback --list

# Rollback to the most recent backup
sudo tunectl rollback

# Rollback to a specific backup
sudo tunectl rollback --backup 2025-01-15T14-30-00
```

### `tunectl audit`

Verify all 86 manifest tuning entries against the live system state. Reports PASS, FAIL, or SKIP for each entry. Strictly read-only.

```bash
tunectl audit
```

Example output:

```
[SWAP-001] PASS  vm.swappiness  expected=180  actual=180
[MEM-001]  FAIL  vm.dirty_ratio  expected=40  actual=20
...
51/86 checks passed
```

### `tunectl benchmark`

Run CPU, memory, and disk I/O performance benchmarks using sysbench and fio. Supports baseline capture and before/after comparison.

```bash
# Run benchmarks and display current results
tunectl benchmark

# Capture a baseline before tuning
tunectl benchmark --baseline

# After tuning, compare against the baseline
tunectl benchmark --compare
```

Example comparison output:

```
Metric                  Baseline    Current     Change     %Change
cpu_single_thread       1234 eps    1356 eps    +122       +9.9%
memory_write            5678 MiB/s  6012 MiB/s  +334       +5.9%
disk_randread_iops      12000       14500       +2500      +20.8%
```

---

## Risk Tiers

tunectl organizes 86 tuning parameters into three risk tiers. Each higher tier includes all parameters from the tiers below it.

| Tier | Included Risk Levels | Entry Count | Description |
|------|---------------------|-------------|-------------|
| **conservative** | `none` | 51 | Zero breakage risk. Sysctl memory/dirty tuning, inotify limits, I/O scheduler, readahead, noatime. No reboot required. |
| **balanced** | `none` + `low` | 80 | Very low risk, well-tested. Adds zram swap, BBR networking, socket buffers, THP, KSM, jemalloc, service tuning, tmpfs /tmp. Some items may need reboot. |
| **aggressive** | `none` + `low` + `med` | 86 | Low-to-medium risk. Adds preempt=none scheduling, cgroup isolation, memory overcommit, balanced CPU mitigations. Reboot required. |

---

## Rollback

### Automatic Backups

Every time you run `tunectl apply`, a timestamped backup is automatically created **before** any changes are written. This ensures you can always restore your previous configuration.

### Backup Location

Backups are stored at:

```
/var/lib/tunectl/backups/YYYY-MM-DDTHH-MM-SS/
```

Each backup directory contains copies of every config file that was modified during that apply operation.

### How to Rollback

```bash
# List all available backups (newest first)
tunectl rollback --list

# Restore from the most recent backup
sudo tunectl rollback

# Restore from a specific backup by timestamp
sudo tunectl rollback --backup 2025-01-15T14-30-00
```

After rollback, sysctl values are automatically reloaded into the running kernel. The backup directory is preserved after restore (not deleted), so you can rollback to the same snapshot multiple times.

---

## Architecture

```
tunectl/
├── tune-manifest.json      ← Single source of truth: 86 tuning parameters
├── scripts/
│   ├── discover.sh          ← System environment detection (JSON output)
│   ├── tune.sh              ← Tuning engine (dry-run / apply with backup)
│   ├── rollback.sh          ← Restore config from timestamped backups
│   ├── audit.sh             ← Verify tuning against live system state
│   └── benchmark.sh         ← Performance benchmarks (sysbench + fio)
├── tunectl/
│   ├── __init__.py           ← Package version
│   ├── __main__.py           ← python3 -m tunectl support
│   └── cli.py                ← Python CLI (argparse, delegates to scripts)
├── bin/
│   └── tunectl               ← npm/npx shim (bash → python3 -m tunectl)
├── package.json              ← npm package definition
├── setup.py                  ← pip install support
└── tests/                    ← Test suite
```

**Data flow:** `tune-manifest.json` → bash scripts → Python CLI → npm shim

- **tune-manifest.json** is the single source of truth for all 86 tuning parameters. Every script reads from this file — no hardcoded tuning values anywhere.
- **Bash scripts** contain the core logic: discovery, planning, applying, rollback, auditing, and benchmarking.
- **Python CLI** (`tunectl/cli.py`) provides the user-facing `tunectl` command with 6 subcommands, each delegating to the corresponding bash script.
- **npm shim** (`bin/tunectl`) enables `npx tunectl` by checking for python3 and forwarding to `python3 -m tunectl`.

---

## RAM Auto-Scaling

tunectl supports servers with **1–8 GB RAM**. Parameters with RAM-dependent values are automatically scaled proportionally based on detected system memory. The manifest reference values are calibrated for 8 GB:

```
scaled_value = reference_value × (detected_ram_gb / 8)
```

Values are rounded to sensible boundaries (powers of 2 for memory sizes, integers for counts). Parameters without a scaling note use their manifest value directly. No manual configuration needed — tunectl detects your RAM and adjusts automatically.

---

## Exit Codes

All commands use consistent exit codes:

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Operational failure |
| 2 | Usage error |

For `audit`: exit code 0 means all checks passed; exit code 1 means one or more checks failed.

---

## License

MIT
