tunectl 1.0.0

Battle-tested VPS performance tuning toolkit for Ubuntu 24.04 LTS

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

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

Option B: Install with pip

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

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

# 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:

# 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:

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.

tunectl discover

Example output:

{
  "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.

# 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.

# 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.

# 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.

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.

# 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

# 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