|
1 | | -# Proxmox-Enhanced-Configuration-Utility (PECU) |
| 1 | +<h1 align="center"> |
| 2 | + <img src="doc/img/Logo-PECU.png" width="150" alt="PECU logo"/> |
| 3 | + <br> |
| 4 | + Proxmox-Enhanced-Configuration-Utility<br><sub>( PECU )</sub> |
| 5 | +</h1> |
| 6 | + |
| 7 | + |
| 8 | +<p align="center"> |
| 9 | + <a href="https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/actions"> |
| 10 | + <img src="https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/actions/workflows/release.yml/badge.svg" alt="CI Status"></a> |
| 11 | + <a href="https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/wiki"> |
| 12 | + <img src="https://img.shields.io/badge/wiki-up%20to%20date-blue?logo=read-the-docs" alt="Wiki"></a> |
| 13 | + <a href="https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases"> |
| 14 | + <img src="https://img.shields.io/github/v/release/Danilop95/Proxmox-Enhanced-Configuration-Utility?include_prereleases" alt="Latest release"></a> |
| 15 | + <a href="LICENSE"> |
| 16 | + <img src="https://img.shields.io/github/license/Danilop95/Proxmox-Enhanced-Configuration-Utility" alt="License"></a> |
| 17 | +</p> |
| 18 | + |
| 19 | +--- |
2 | 20 |
|
3 | 21 | ## Table of Contents |
4 | | - |
5 | 22 | - [Overview](#overview) |
| 23 | +- [Requirements & Compatibility](#requirements--compatibility) |
| 24 | +- [Quick Start](#quick-start) |
| 25 | + - [Direct execution (recommended)](#direct-execution-recommended) |
| 26 | + - [Offline / local install](#offline--local-install) |
| 27 | +- [What Is the Release Selector?](#what-is-the-release-selector) |
6 | 28 | - [Features](#features) |
7 | | -- [Requirements](#requirements) |
8 | | -- [Compatible Proxmox Versions](#compatible-proxmox-versions) |
9 | | -- [Usage and Installation](#usage-and-installation) |
10 | | -- [Contribution](#contribution) |
11 | | -- [Support](#support) |
| 29 | +- [Community & Contribution](#community--contribution) |
| 30 | +- [Support the Project](#support-the-project) |
12 | 31 | - [License](#license) |
13 | 32 |
|
14 | | -> ⚠️ **Experimental Features Notice** |
15 | | -> The latest updates, including Intel iGPU detection, rollback functionality for GPU passthrough, and multi-GPU support, are currently in a testing phase. These features may not be fully stable and could require further adjustments. Use with caution, especially in production environments, and report any issues you encounter to help improve the script’s reliability. |
| 33 | +--- |
16 | 34 |
|
17 | 35 | ## Overview |
| 36 | +**PECU** is a single-shell utility that makes day-to-day Proxmox VE management |
| 37 | +as painless as possible: |
18 | 38 |
|
19 | | -The **Proxmox-Enhanced-Configuration-Utility (PECU)** is a powerful Bash script designed to streamline the configuration and management of Proxmox VE environments. This utility provides an interactive menu system for performing key tasks, such as managing package repositories and configuring GPU passthrough, simplifying Proxmox setup and optimization for diverse use cases. |
| 39 | +* one-line installer |
| 40 | +* interactive menus for repositories, kernel flags, GPU passthrough, etc. |
| 41 | +* reversible operations (backup / rollback built-in) |
| 42 | +* auto-detects NVIDIA, AMD **and** Intel iGPUs out of the box |
20 | 43 |
|
21 | | -## Features |
| 44 | +--- |
22 | 45 |
|
23 | | -The `proxmox-configurator.sh` script includes the following features: |
| 46 | +### Requirements & Compatibility |
24 | 47 |
|
25 | | -- **Dependency Installation**: |
26 | | - - **Backup and Restore**: Create and restore backups of the `sources.list` file, ensuring recovery points for system configurations. |
27 | | - - **Modify `sources.list`**: Edit the `sources.list` file directly within the script interface using Nano or automatically add recommended repositories. |
| 48 | +> The selector and the underlying scripts are designed for a **typical, up-to-date Proxmox host**. |
| 49 | +> If your stack falls outside the matrix below, use at your own risk. |
28 | 50 |
|
29 | | -- **GPU Passthrough Configuration**: |
30 | | - - Set up GPU passthrough to assign dedicated graphics cards to virtual machines, improving performance for compute-intensive tasks. |
31 | | - - Includes rollback functionality to undo passthrough configurations if needed. |
| 51 | +| | | |
| 52 | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 53 | +| **Platform** | <img src="https://img.shields.io/badge/Proxmox VE-7.x %2F 8.x-000000?style=for-the-badge&logo=proxmox&logoColor=white" alt="Proxmox 7 / 8 badge"> *(tested weekly on the latest ISO)* | |
| 54 | +| **CPU arch** | <img src="https://img.shields.io/badge/x86--64-required-6A737D?style=for-the-badge"> | |
| 55 | +| **Privileges** | <img src="https://img.shields.io/badge/root_or_sudo-required-E74C3C?style=for-the-badge" alt="root badge"> |
32 | 56 |
|
33 | | -- **System Configuration Checks**: |
34 | | - - Verifies if the Proxmox package repositories are correctly configured. |
35 | | - - Displays the state of IOMMU and MSI options to optimize hardware settings. |
| 57 | +> **Heads-up** PECU does **not** support ARM / Raspberry Pi builds of Proxmox at this time. |
| 58 | +> Community ports are welcome, but official testing is x86-64 only. |
36 | 59 |
|
37 | | -- **Multi-GPU Support**: |
38 | | - - Detects and displays details for NVIDIA, AMD, and Intel GPUs, with tailored options for Data Center or Gaming GPUs. |
| 60 | +--- |
39 | 61 |
|
40 | | -- **Exit Option**: |
41 | | - - Safely exits the script, ensuring a clean shutdown of any ongoing operations. |
42 | 62 |
|
43 | | -## Requirements |
| 63 | +## Quick Start |
44 | 64 |
|
45 | | -To use this script, the following are required: |
| 65 | +### Direct execution (recommended) |
46 | 66 |
|
47 | | -- **Proxmox VE**: This script is designed specifically for use on Proxmox VE systems. |
48 | | -- **Root Privileges**: Must be run with root or sudo privileges to modify system configurations and perform installations. |
49 | | -- **Basic Proxmox Knowledge**: Familiarity with Proxmox setup and configuration is recommended for optimal use of the script's features. |
| 67 | +> **New in 2025-05** – a tiny selector script fetches **all** tagged releases and |
| 68 | +> lets you launch whichever version (Stable, Beta, Experimental…) you want. |
50 | 69 |
|
51 | | -## Compatible Proxmox Versions |
| 70 | +```bash |
| 71 | +# run the selector straight from GitHub |
| 72 | +bash <(curl -sL \ |
| 73 | + https://raw.githubusercontent.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/refs/heads/main/scripts/pecu_release_selector.sh) |
| 74 | +``` |
52 | 75 |
|
53 | | -The `proxmox-configurator.sh` script has been tested and is compatible with the following Proxmox VE versions: |
| 76 | +<details> |
| 77 | +<summary>Live preview — choose <code>Stable</code>, <code>Beta</code>, or <code>⚠ Experimental</code></summary> |
54 | 78 |
|
55 | | -- Proxmox VE 7.x |
56 | | -- Proxmox VE 8.x |
| 79 | +#### Screenshot (Real) |
57 | 80 |
|
58 | | -## Usage and Installation |
| 81 | +<p align="center"> |
| 82 | + <img src="doc/img/pecu_release_selector.png" width="90%" alt="PECU selector in action"> |
| 83 | +</p> |
59 | 84 |
|
60 | | -You can run the script directly from your Proxmox server or clone the repository and execute it locally. Follow the instructions below for each method. |
| 85 | +#### ANSI-mock-up |
61 | 86 |
|
62 | | -### Direct Execution |
| 87 | +<pre><samp><span style="color:#3fb950">Stable</span> Production ready |
| 88 | +<span style="color:#ff7b72">Beta</span> Release candidate |
| 89 | +<span style="color:#a5d6ff">Preview</span> Feature preview |
| 90 | +<span style="color:#ffa657">Experimental</span> High-risk build |
| 91 | +<span style="color:#1f6feb">Nightly</span> Un-tested daily build |
63 | 92 |
|
64 | | -To run the script directly from the internet, use the following command: |
| 93 | +<span style="color:#8b949e"># TAG TITLE DATE [CHANNEL]</span> |
| 94 | + <span style="color:#ff7b72">1 v2025.06.17 Intel iGPU support 2025-06-17 [beta ] ★LATEST |
| 95 | + <span style="color:#a5d6ff">2 v2025.05.14 Whiptail UI overhaul 2025-05-14 [preview] |
| 96 | + <span style="color:#3fb950">3 v2025.04.14 Performance & bug-fix roll-up 2025-04-14 [stable ] |
| 97 | + <span style="color:#ffa657">4 v2025.03.03 Initial automated release 2025-03-03 [⚠ exp ] |
65 | 98 |
|
66 | | -```bash |
67 | | -bash <(curl -sL https://raw.githubusercontent.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/refs/heads/main/scripts/pecu_release_selector_old.sh) |
68 | | -``` |
| 99 | +Select #release: <span style="color:#3fb950">3</span> |
| 100 | +────────────────────────────────────────────────────────────────────────────── |
| 101 | +TAG: v2025.04.14 |
| 102 | +TITLE: Performance & bug-fix roll-up |
| 103 | +NOTE: Safe for production |
| 104 | +────────────────────────────────────────────────────────────────────────────── |
| 105 | +Press Y to run | any other key to cancel:</samp></pre> |
69 | 106 |
|
70 | | -> **Note**: This command requires an active internet connection and is specific to Linux systems with Bash and Curl installed. |
| 107 | +</details> |
71 | 108 |
|
72 | | -### Local Installation |
| 109 | +--- |
73 | 110 |
|
74 | | -If you prefer to work with the code locally, you can download the stable release archive directly from the [Releases](https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases) page. For example, for release `v2025.04.14`, run: |
75 | 111 |
|
76 | | -1. **Clone the Repository**: |
77 | 112 |
|
78 | | -```bash |
79 | | -wget https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases/download/v2025.04.14/PECU-2025.04.14.tar.gz && \ |
80 | | -tar -xzvf PECU-2025.04.14.tar.gz && \ |
81 | | -cd PECU-2025.04.14 |
| 113 | +### Offline / local install |
| 114 | + |
| 115 | +All releases ship a `.tar.gz` bundle: |
82 | 116 |
|
| 117 | +```bash |
| 118 | +VERSION="v2025.04.14" # pick any tag |
| 119 | +wget https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases/download/$VERSION/PECU-${VERSION#v}.tar.gz |
| 120 | +tar -xzf PECU-${VERSION#v}.tar.gz |
| 121 | +cd PECU-${VERSION#v}/src |
| 122 | +chmod +x proxmox-configurator.sh |
| 123 | +sudo ./proxmox-configurator.sh |
83 | 124 | ``` |
84 | 125 |
|
85 | | -2. **Set Execution Permissions**: |
| 126 | +--- |
86 | 127 |
|
87 | | - Ensure the script has the necessary execution permissions. If not, grant them with: |
| 128 | +## What Is the Release Selector? |
88 | 129 |
|
89 | | - ```bash |
90 | | - chmod +x proxmox-configurator.sh |
91 | | - ``` |
| 130 | +* `pecu_release_selector.sh` is a **new ASCII-driven menu** I built over the last few months. |
| 131 | + It talks directly to the GitHub API, parses every tag, and sorts them by the |
| 132 | + custom **`PECU-Channel`** labels I introduced (Stable, Beta, Preview, Experimental, Nightly). |
| 133 | + The channels keep the list tidy and make it obvious which way the project is heading. |
| 134 | +* Marking a build as **Experimental** instantly flags it orange in the menu, |
| 135 | + so I can ship rough prototypes or quick-fix versions without confusing people who only want Stable releases. |
| 136 | +lector. |
| 137 | +* `pecu_release_selector_old.sh` still exists **only as a shim** that `exec`s the new script — **it will be removed on _05 July 2025_**. |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +## Features |
92 | 142 |
|
93 | | -3. **Run the Script**: |
| 143 | +| Category | Highlights | |
| 144 | +| --------------------- | ---------------------------------------------------------------------------------------- | |
| 145 | +| **Repositories** | Backup / restore `sources.list`, add “non-subscription” repo, edit with Nano. | |
| 146 | +| **GPU Passthrough** | Wizard-style setup for NVIDIA, AMD, Intel; supports driverctl override; rollback option. | |
| 147 | +| **Kernel Tweaks** | Add `pcie_acs_override`, `video=efifb:off`, or custom flags with risk prompts. | |
| 148 | +| **Multi-GPU** | Detects multiple GPUs and lets you choose the one to passthrough. | |
| 149 | +| **Intel iGPU (test)** | Experimental automatic isolation of iGPU functions. | |
| 150 | +| **Logging** | Detailed `/var/log/pecu.log` with timestamps. | |
94 | 151 |
|
95 | | - Execute the script with root privileges: |
| 152 | +--- |
96 | 153 |
|
97 | | - ```bash |
98 | | - sudo ./proxmox-configurator.sh |
99 | | - ``` |
| 154 | +## Community & Contribution |
100 | 155 |
|
101 | | -4. **Follow the Interactive Menu**: |
| 156 | +PECU grows through clear bug reports, well-scoped ideas, and peer-reviewed code. |
| 157 | +If you would like to get involved, choose the channel that best suits your needs: |
102 | 158 |
|
103 | | - The script will present an interactive menu. Follow the on-screen instructions to perform the desired operations. |
| 159 | +| Purpose | Channel | |
| 160 | +|---------|---------| |
| 161 | +| **Bug reports / feature requests** | Use the GitHub [Issue tracker](../../issues). Please include the tag you were running, a concise description, and any relevant console output. | |
| 162 | +| **Code contributions** | Fork the repository, branch from `main`, run `shellcheck`, keep commits focused, then open a Pull Request. | |
| 163 | +| **Technical discussion and quick feedback** | Join the PECU Discord server: <https://discord.gg/euQTVNc2xg>. The server is used for informal Q&A, brainstorming future features, and sharing configuration tips. | |
| 164 | +| **Sustained support and early-access builds** | Patreon memberships are available at <https://www.patreon.com/c/DVNILXP95>. Patrons receive preview builds, detailed implementation notes, and can vote on the development roadmap. | |
104 | 165 |
|
105 | | -## Contribution |
| 166 | +--- |
106 | 167 |
|
107 | | -We welcome contributions to enhance the functionality and compatibility of this utility script. You can contribute in several ways: |
| 168 | +### Support the Project |
108 | 169 |
|
109 | | -- **Issues**: Report bugs or suggest new features by opening an issue on our GitHub repository. |
110 | | -- **Pull Requests**: Submit your improvements through a pull request. Make sure to follow the contribution guidelines in the repository. |
| 170 | +If PECU saves you time in daily operations and you wish to accelerate its development, consider a one-off donation: |
111 | 171 |
|
112 | | -## Support |
| 172 | +<p align="center"> |
| 173 | + <a href="https://buymeacoffee.com/danilop95ps" target="_blank"> |
| 174 | + <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" |
| 175 | + alt="Buy Me a Coffee" height="37"> |
| 176 | + </a> |
| 177 | +</p> |
113 | 178 |
|
114 | | -If you find this project helpful and would like to support its development, consider buying me a coffee! |
| 179 | +Your support funds additional test hardware. |
115 | 180 |
|
116 | | -<a href="https://buymeacoffee.com/danilop95pS" target="_blank"> |
117 | | -<img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 37px !important;width: 170px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;"> |
118 | | -</a> |
119 | 181 |
|
120 | 182 | ## License |
121 | 183 |
|
122 | | -This project is licensed under the [GNU General Public License v3.0 (GPL-3.0)](LICENSE). For more information, please refer to the [LICENSE](LICENSE) file in the repository. |
| 184 | +**GPL-3.0** – see [LICENSE](LICENSE). |
| 185 | +Feel free to fork, adapt, and share under the same terms. |
0 commit comments