Skip to content

README.md

Latest commit

 

History

History
265 lines (189 loc) · 11.7 KB

README.md

File metadata and controls

265 lines (189 loc) · 11.7 KB
Raw

PECU logo
Proxmox Enhanced Configuration Utility
( PECU )

CI Status Wiki Latest release License

Buy Me a Coffee ko-fi

Table of Contents

Overview

PECU is a Bash-based utility for Proxmox VE focused on repeatable host configuration and GPU passthrough workflows. It provides an interactive menu-driven interface for common operations (repositories, kernel parameters, VFIO, rollback), with an emphasis on safe reruns (idempotency), backups, and clear logging.

Primary use cases:

  • GPU passthrough setup and verification (NVIDIA / AMD / Intel)
  • Bootloader-aware kernel parameter management (systemd-boot / GRUB)
  • VFIO configuration with validation and rollback support
  • VM template creation (and a declarative template system)

Requirements & Compatibility
Platform Proxmox VE 7 / 8 / 9
CPU arch x86-64 required
Privileges root or sudo required
Boot GRUB / systemd-boot

Notes:

  • ARM / Raspberry Pi builds of Proxmox are not supported at this time.
  • This project modifies system configuration (boot params, initramfs, modprobe). Review changes and ensure you have console access before applying.
  • The declarative template tooling needs python3, PyYAML, and jsonschema for local validation. A real Proxmox host is required only for non-dry-run apply.

Quick Start

Direct execution (recommended)

The release selector fetches available tagged releases and lets you launch a chosen version/channel.

bash <(curl -fsSL https://raw.githubusercontent.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/main/scripts/pecu_release_selector.sh)

Release Selector

PECU Release Selector - Standard View

Premium Interface (optional)

PECU Release Selector - Premium Interface

PECU UI

PECU Script Interface

Run a specific release tag

To run a specific release directly (recommended for reproducibility in documentation and automation):

TAG="v2026.01.05"
bash <(curl -fsSL "https://raw.githubusercontent.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/${TAG}/src/proxmox-configurator.sh")

Offline / local install

All releases ship a .tar.gz bundle.

VERSION="v2026.01.05"  # choose a tag from the Releases page
wget "https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases/download/${VERSION}/PECU-${VERSION#v}.tar.gz"
wget "https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases/download/${VERSION}/SHA256SUMS"
sha256sum -c SHA256SUMS
tar -xzf "PECU-${VERSION#v}.tar.gz"
cd "PECU-${VERSION#v}"

# Robust entrypoint detection (bundle layouts may differ between releases)
if [ -x "src/proxmox-configurator.sh" ]; then
  chmod +x src/proxmox-configurator.sh
  sudo ./src/proxmox-configurator.sh
elif [ -x "proxmox-configurator.sh" ]; then
  chmod +x proxmox-configurator.sh
  sudo ./proxmox-configurator.sh
else
  echo "Could not find proxmox-configurator.sh in the extracted bundle."
  echo "Expected: ./src/proxmox-configurator.sh or ./proxmox-configurator.sh"
  exit 1
fi

Release Selector

pecu_release_selector.sh is an interactive menu that queries GitHub releases/tags and groups them by PECU-Channel metadata (Stable, Beta, Preview, Experimental, Nightly). This is intended to keep the list readable and to reduce accidental use of non-stable builds.

Telemetry in the release selector is optional. In interactive mode it is disabled unless you explicitly opt in; it can also be forced off with PECU_TELEMETRY=off. Use --json-preview to inspect the telemetry payload without sending it.

The legacy selector script (if present) is kept only for compatibility and may be removed in a future release.

VM Templates System

PECU includes a declarative VM template system with CLI tools.

Highlights:

  • Declarative YAML templates for common configurations
  • JSON Schema validation
  • CLI management (templatectl.sh) with render and apply --dry-run
  • Safe apply path: commands are executed as argument arrays, not through eval
  • Storage pool flexibility (local-lvm, local, auto-detection)
  • Explicit policy gates for machine pinning and unsafe raw QEMU args

Quick usage:

# List available templates
src/tools/templatectl.sh list --channel Experimental

# Validate all templates
src/tools/templatectl.sh validate templates/

# Preview commands (safe, no execution)
src/tools/templatectl.sh render templates/windows/windows-gaming.yaml \
  --vmid 200 --storage-pool local-lvm

# Preview apply plan (safe, no execution, no Proxmox required)
src/tools/templatectl.sh apply templates/windows/windows-gaming.yaml \
  --vmid 200 --storage-pool local-lvm --dry-run

# Apply template (creates VM)
sudo src/tools/templatectl.sh apply templates/windows/windows-gaming.yaml \
  --vmid 200 --storage-pool local-lvm

See templates/README.md for details.

Known limitations

Before reporting a new issue, review the following known topics:

  • SR-IOV environments and GPU selection: virtual functions can affect discovery and device selection. See #32.
  • APU/iGPU platforms (e.g., AMD Ryzen Phoenix): VFIO binding must be surgical; incorrect binding can include unintended PCI IDs. See #33.
  • Offline/local install path differences: bundle layout can vary between releases; follow the robust offline steps above. See #31.
  • AMD 5700 XT vendor reset: vendor-reset effectiveness depends on model/kernel; tracked as FYI. See #29.
  • Template behavior reports: tracked in #25. Templates are schema-validated and dry-run tested in CI, but non-dry-run qm apply still needs validation on real Proxmox storage/network combinations.

Issue tracker: https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/issues

Features

Category Highlights
Repositories Backup/restore sources, optional no-subscription repo, safe idempotent ops
GPU passthrough Guided setup for NVIDIA/AMD/Intel; rollback; verification helpers
Kernel parameters Add/validate common flags with risk prompts
Multi-GPU & discovery Detects multiple GPUs; improved discovery in complex PCI topologies
VM templates Declarative templates + CLI management
Logging /var/log/pecu.log with timestamps and rotation

Community & Contribution

Bug reports and feature requests:

  • Use the GitHub Issue tracker.
  • Include the release tag you ran, host details (PVE version, CPU, GPU), and relevant logs/output.

Code contributions:

  • Keep commits focused, run shellcheck, and open a Pull Request against main.

Discord: https://discord.gg/euQTVNc2xg Patreon: https://www.patreon.com/c/DVNILXP95

Star History

Star History Chart

Support the Project

If PECU is useful in your workflows and you want to support continued development:

Buy Me a Coffee ko-fi

License

See LICENSE.