tunectl 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tunectl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# 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

package/bin/tunectl

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# tunectl — npm/npx shim that delegates to the Python CLI.
+#
+# This script is the bin entry point for the npm package. It checks
+# that python3 is available, then invokes `python3 -m tunectl` with
+# all arguments forwarded unchanged.
+
+set -euo pipefail
+
+# Resolve the package root (one level up from bin/).
+# Follow symlinks so npm link / npx scenarios resolve correctly.
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE" ]]; do
+    DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    # Handle relative symlinks
+    [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+PACKAGE_ROOT="$(cd "$(dirname "$SOURCE")/.." && pwd)"
+
+# Check that python3 is available
+if ! command -v python3 &>/dev/null; then
+    echo "Error: python3 is required but was not found on PATH." >&2
+    echo "" >&2
+    echo "Install Python 3 for your platform:" >&2
+    echo "  Ubuntu/Debian:  sudo apt install python3" >&2
+    echo "  macOS:          brew install python3" >&2
+    echo "  Fedora/RHEL:    sudo dnf install python3" >&2
+    echo "  Arch Linux:     sudo pacman -S python" >&2
+    echo "" >&2
+    echo "Then re-run: npx tunectl $*" >&2
+    exit 1
+fi
+
+# Ensure the tunectl Python package is importable by adding the
+# package root to PYTHONPATH (needed for npm link / npx scenarios
+# where the package is not pip-installed).
+export PYTHONPATH="${PACKAGE_ROOT}${PYTHONPATH:+:$PYTHONPATH}"
+
+# Delegate to the Python CLI, running from the package root so that
+# scripts/ and tune-manifest.json are located correctly.
+cd "$PACKAGE_ROOT"
+exec python3 -m tunectl "$@"

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "tunectl",
+  "version": "1.0.0",
+  "description": "Battle-tested VPS performance tuning toolkit for Ubuntu 24.04 LTS",
+  "bin": {
+    "tunectl": "./bin/tunectl"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "tunectl/",
+    "tune-manifest.json",
+    "setup.py"
+  ],
+  "keywords": [
+    "vps",
+    "performance",
+    "tuning",
+    "sysctl",
+    "linux",
+    "ubuntu"
+  ],
+  "license": "MIT",
+  "author": "tunectl contributors",
+  "homepage": "https://github.com/symulacr/tunectl",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/symulacr/tunectl.git"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}