From 2708d6dcb5c85e4af31b07043445ae2513ea95a3 Mon Sep 17 00:00:00 2001 From: stornic56 <71296607+stornic56@users.noreply.github.com> Date: Sat, 20 Jun 2026 21:54:59 -0500 Subject: [PATCH] add retroarch, nvidia - java - internet refactor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - NVIDIA CUDA extrepo refactor in `modules/gpu/nvidia.sh`: removed unnecessary `i386_active` lines, updated warning to reference `v590 (unified metapackage)`, simplified installation from 18+10 versioned packages → `nvidia-driver-pinning-590 nvidia-driver firmware-nvidia-gsp`, eliminated `apt-mark hold` since pinning packages now handle it. DKMS verification and `NVIDIA_DRIVER_MODE="cuda-repo"` preserved. - CUDA repo case fix in `modules/gaming.sh`: replaced silent bypass with detection of `nvidia-driver-libs:i386` v590 installation; if missing, prompts user confirmation before installing via active CUDA repo + pinning. - Palemoon internet module overhaul (`modules/extras/internet/internet.sh`): removed deprecated `_enable_palemoon_repo()`, created new `install_palemoon()` with AVX2→AVX→SSE2 CPU detection from `/proc/cpuinfo`, proper `extrepo enable` call, and package installation. - ProtonVPN module rewrite (`modules/extras/internet/internet.sh`): removed broken `_enable_protonvpn_repo()` that failed due to missing suite; created new `install_protonvpn()` using `stable` suite + `proton-vpn-gtk-app` package with proper validation. - Java/Minecraft rename across `modules/gaming.sh` and `modules/extras/java.sh`: renamed `_install_gaming_java()` → `install_minecraft_java()`, updated menu title from "Java Runtimes for Gaming" to "Java Runtimes for Minecraft", changed whiptail tag from `"java-jre"` to `"java"`. - RetroArch + 4 classic cores (`modules/gaming/tools.sh` and `.sh`): added RetroArch entry to gaming menu, new case handler in `gaming.sh`, updated installation command to include `libretro-mgba libretro-snes9x libretro-nestopia libretro-gambatte`, enhanced notice with emojis, core enumeration, DFSG warning, and wiki link. - OnlyOffice server status (`modules/extras/office/office.sh`): added fallback message for slow or down OnlyOffice servers to improve user experience during installation. - Full syntax validation: all modified files pass `bash -n` without errors; no residual references to old variables (`i386_active`, `590.48.01`) or functions remain. - Documentation about Debian and the script is added to supplement important information. - update README.md --- README.md | 49 +++-- docs/firmware.md | 58 ++++++ docs/gaming.md | 131 +++++++++++++ docs/gpu.md | 249 +++++++++++++++++++++++++ docs/kernel.md | 77 ++++++++ docs/repos_config.md | 273 ++++++++++++++++++++++++++++ docs/retroarch.md | 163 +++++++++++++++++ docs/system_info.md | 36 ++++ docs/user_priv_feed.md | 80 ++++++++ docs/zram.md | 243 +++++++++++++++++++++++++ modules/extras/internet/internet.sh | 64 +++++-- modules/extras/java.sh | 13 +- modules/extras/office/office.sh | 2 +- modules/gaming.sh | 24 ++- modules/gaming/tools.sh | 27 +++ modules/gpu/nvidia.sh | 68 ++----- 16 files changed, 1449 insertions(+), 108 deletions(-) create mode 100644 docs/firmware.md create mode 100644 docs/gaming.md create mode 100644 docs/gpu.md create mode 100644 docs/kernel.md create mode 100644 docs/repos_config.md create mode 100644 docs/retroarch.md create mode 100644 docs/system_info.md create mode 100644 docs/user_priv_feed.md create mode 100644 docs/zram.md diff --git a/README.md b/README.md index 387e160..bf13de1 100644 --- a/README.md +++ b/README.md @@ -47,14 +47,14 @@ After running the script: | Option | Description | What it does | |--------|-------------|--------------| -| **1** | System Info | Show detected OS, CPU, RAM, GPU and hardware details | -| **2** | [User Privileges & Feedback](#user-privileges--feedback) | Configure sudo group membership, enable passwordless sudo for frequent tasks, repair home directory ownership issues, and toggle visual password feedback (asterisks) in terminal | -| **3** | Configure Repositories | Setup official repos with non-free/contrib options, optional Backports support and Deb822/classic format injection.| -| **4** | Firmware & Wireless Drivers | Install essential firmware for GPUs and wireless| -| **5** | Graphics Drivers & Mesa Stack | Configure AMD/Intel/NVIDIA drivers and Mesa graphics stack + monitoring tools | -| **6** | Backports Kernel | Install latest kernel from Debian backports| -| **7** | Gaming Setup and Performance | Steam, Heroic Games Launcher, GameMode, MangoHud, OpenRGB, Java JRE (Temurin 8/17/21) | -| **8** | Install ZRAM (Swap) | Configure compressed RAM for memory optimization| +| **1** | [System Info](/docs/system_info.md) | Show detected OS, CPU, RAM, GPU and hardware details | +| **2** | [User Privileges & Feedback](/docs/user_priv_feed.md) | Configure sudo group membership, enable passwordless sudo for frequent tasks, repair home directory ownership issues, and toggle visual password feedback (asterisks) in terminal | +| **3** | [Configure Repositories](/docs/repos_config.md) | Setup official repos with non-free/contrib options, optional Backports support and Deb822/classic format injection.| +| **4** | [Firmware & Wireless Drivers](firmware.md) | Install essential firmware for GPUs and wireless| +| **5** | [Graphics Drivers & Mesa Stack](gpu.md) | Configure AMD/Intel/NVIDIA drivers and Mesa graphics stack + monitoring tools | +| **6** | [Backports Kernel](kernel.md) | Install latest kernel from Debian backports| +| **7** | [Gaming Setup and Performance](gaming.md)| Steam, Heroic Games Launcher, [RetroArch](retroarch.md) GameMode, MangoHud, OpenRGB, Java JRE (Temurin 8/17/21) | +| **8** | [Install ZRAM](zram.md)| Configure compressed RAM for memory optimization| | **9** | Install Programs and Software | Selection from several categories (Development, Themes, System, etc.) | | **10** | Exit | Return to terminal | @@ -80,25 +80,6 @@ The submenu offers the next categories: --- -## User Privileges & Feedback - -Admin rights, passwordless commands, and file ownership fixes—optimized for Debian users. - -### 1. Sudo Group Membership -If you just installed Debian and can’t install software or change system settings (you get "Permission denied"), this option adds your user to the sudo group. This gives you admin privileges so you can manage your system. Changes take effect after you log out and back in. - -### 2. Passwordless Sudo for Frequent Tasks -Every time you run sudo apt install or sudo reboot, Linux asks for your password. This option lets you skip typing your password for common commands like installing/updating software (apt), restarting or shutting down (systemctl). -- ⚠️ Security Note: While convenient, this reduces security if someone else uses your PC physically. - -### 3. Repair Home Directory Ownership -Sometimes, when you use sudo incorrectly (e.g., installing games or apps), files get "stolen" by the system (root) instead of your user. This causes apps to fail (e.g., saving settings or game progress). This option fixes ownership so all your files and folders belong to you again. - -### 4. Sudo Password Feedback (Asterisks) -By default, Debian’s terminal hides your password (no asterisks or feedback). This option adds visual feedback (e.g., ****) so you can see how many characters you’ve typed. Toggle it on/off as needed. - ---- - ## File Structure | Directory/File | Description | @@ -109,7 +90,18 @@ By default, Debian’s terminal hides your password (no asterisks or feedback). ```bash ├── debianito.sh +├── docs +│   ├── firmware.md +│   ├── gaming.md +│   ├── gpu.md +│   ├── kernel.md +│   ├── repos_config.md +│   ├── retroarch.md +│   ├── system_info.md +│   ├── user_priv_feed.md +│   └── zram.md ├── modules +│   ├── bluetooth.sh │   ├── bullseye │   │   ├── extras.sh │   │   ├── legacy.sh @@ -130,6 +122,8 @@ By default, Debian’s terminal hides your password (no asterisks or feedback). │   │   ├── internet │   │   │   └── internet.sh │   │   ├── java.sh +│   │   ├── office +│   │   │   └── office.sh │   │   ├── players │   │   │   └── players.sh │   │   ├── programming @@ -167,6 +161,7 @@ By default, Debian’s terminal hides your password (no asterisks or feedback). │   │   └── repo_detect.sh │   ├── repos.sh │   ├── sudo_config.sh +│   ├── sysinfo.sh │   ├── utils.sh │   └── zram.sh └── README.md diff --git a/docs/firmware.md b/docs/firmware.md new file mode 100644 index 0000000..2f64a90 --- /dev/null +++ b/docs/firmware.md @@ -0,0 +1,58 @@ +# Option 4: Advanced Firmware & Wireless Architecture + +## 1. The Hidden Debian "Problem" +In standard Debian packaging, the meta-package `firmware-linux-nonfree` serves as a generic aggregator for hardware blobs. However, due to internal dependency resolution rules and conservative versioning strategies within the repository, this package often fails to automatically include vendor-specific firmware drivers for newer or niche network controllers (specifically Realtek Wi-Fi/Bluetooth and Intel Ethernet/Wi-Fi variants). + +This script acts as an intelligent injector to bridge that gap. It does not rely solely on the meta-package's `Recommends` field; instead, it actively scans the hardware topology to identify missing dependencies. By decoupling the detection from the installation logic, the architecture ensures that even if the base package is installed, specific vendor blobs (e.g., `firmware-iwlwifi`, `firmware-realtek`) are explicitly pulled in only when their corresponding hardware IDs are confirmed present on the system. This prevents "half-baked" network connectivity where the interface exists but lacks the necessary firmware to initialize. + +## 2. Dual Scan Engine (PCI & USB) +To ensure comprehensive hardware detection while minimizing false positives, the script utilizes a dual-scan engine that interrogates both PCI and USB buses with strict filtering logic: + +* **PCI Bus Scanning (`lspci`):** The engine parses `lspci -nn` output specifically targeting lines containing "network controller" or "ethernet controller". This captures both wireless adapters (e.g., Intel AX200) and wired NICs (e.g., Realtek RTL8125 2.5GbE), ensuring that Ethernet firmware requirements are also met during the process. +* **USB Bus Scanning (`lsusb`):** The USB scan applies keyword filtering to ignore peripherals unrelated to networking, such as audio devices or card readers. It specifically looks for terms like "wireless", "wifi", "802.11", and "wlan". Bluetooth devices are also detected separately through `PCI_BT_DEVS` and `USB_BT_DEVS`. +* **Deduplication:** The collected device lists are merged into a single array (`dev_list`) to prevent duplicate processing of the same hardware instance across different bus categories, ensuring a clean plan generation. + +## 3. Dynamic Hardware Mapping Matrix +The script employs an associative mapping strategy in `_detect_firmware_needs` to translate raw vendor strings from `lspci`/`lsusb` into specific Debian package names. This matrix is critical for handling the "Intel Split" and other vendor-specific requirements: + +* **Vendor Filtering:** The engine first filters out generic or unsupported vendors (e.g., non-Realtek, non-Intel, non-Atheros) to avoid unnecessary package pulls. +* **Package Assignment Logic:** + * **Intel Wi-Fi Hardware** ➔ `firmware-iwlwifi` (Specific driver for wireless chips). + * **Intel Ethernet Hardware** ➔ `firmware-intel-misc` (Often pulled via `Recommends` of the base package, but explicitly tracked here). + * **Realtek Hardware** ➔ `firmware-realtek`. + * **MediaTek / Ralink Hardware** ➔ `firmware-mediatek`. + * **Atheros / Qualcomm Hardware** ➔ `firmware-atheros`. + +This mapping ensures that if a system contains an Intel Wi-Fi 6 card, the script explicitly queues `firmware-iwlwifi` regardless of whether the base meta-package claims to cover it. The output is rendered as a deduplicated plan with visual indicators (e.g., `[+] package ← hardware`) for user clarity. + +## 4. Installation Execution Flow (Atomic Pipeline) +The installation process follows a strict atomic pipeline defined in `install_firmware`, ensuring system stability and version consistency: + +1. **Repository Validation:** The script first verifies that `/etc/apt/sources.list` or `.d/` contains the `non-free` component. If absent, it halts to prevent installation failures. +2. **Plan Rendering & Confirmation:** A diagnostic tree is generated showing detected controllers and planned packages. The user must explicitly confirm ("Apply the network & firmware plan?") before proceeding. +3. **Base Meta-Package Selection (Backports vs. Stable):** + * If `firmware-linux-nonfree` is already installed, the script checks for a newer version in backports (`${DEBIAN_CODENAME}-backports`). It prompts to upgrade if available, as backports often contain firmware for very recent hardware not yet in stable. + * If not installed, it presents a choice between Stable (Ultra-tested) and Backports (Recommended for modern hardware). +4. **Sequential Injection:** After the base package is secured, the script iterates through `_DETECTED_FW_PKGS`. It uses `apt-cache policy` to validate availability before installing specific vendor packages (`firmware-realtek`, etc.), skipping those already present or unavailable in repositories. + +## 5. Broadcom Redundancy System (3-Tier Support) +Broadcom chipsets require complex handling due to their mix of open-source and proprietary driver support. The `_handle_wireless` function implements a three-tier logic to maximize compatibility without breaking the kernel: + +* **Tier 1 (Open/Non-Free Direct):** For supported chips, it attempts to install `firmware-brcm80211`. This is preferred as it uses standard DKMS modules provided by Debian. +* **Tier 2 (Firmware Emulation):** If Tier 1 fails or the chipset requires firmware emulation (e.g., older B43 chips), the script installs `firmware-b43-installer` or `firmware-b43legacy-installer`. This is a fallback for hardware that cannot be driven by standard kernel modules. +* **Tier 3 (Proprietary DKMS):** For unsupported chipsets where open-source drivers are insufficient, the system falls back to compiling proprietary drivers (`broadcom-sta-dkms`). The script explicitly checks for `linux-headers` availability before attempting this compilation, as it requires kernel headers matching the running version. It warns the user that a reboot may be required after installation. + +This tiered approach ensures that even if one method fails (e.g., proprietary driver compilation errors), the system attempts other supported methods to restore network functionality. + +## 6. Bluetooth Stack Integration +Bluetooth support is handled through a dedicated module (`bluetooth.sh`) that integrates seamlessly with the firmware detection process: + +* **Hardware Detection:** The script identifies both PCI and USB Bluetooth controllers using `PCI_BT_DEVS` and `USB_BT_DEVS` arrays, ensuring comprehensive coverage of all Bluetooth hardware types. +* **Base Stack Installation:** When Bluetooth hardware is detected, the system installs the core stack (`bluez`, `bluez-utils`, `bluez-obexd`) if not already present. +* **Desktop Environment Optimization:** Based on the detected desktop environment: + * **KDE:** Installs `bluedevil` and optionally `pipewire-pulse` + `wireplumber` for Pipewire audio server integration. + * **GNOME:** Uses built-in GNOME Bluetooth support in `gnome-control-center`. + * **XFCE/Other:** Installs `blueman` as the GTK Bluetooth manager. +* **Service Management:** The script ensures the Bluetooth service is enabled and started automatically on boot, with session restart or reboot recommendation for desktop applets to load properly. + +This modular approach keeps Bluetooth handling separate from network firmware while maintaining tight integration through shared device detection arrays and coordinated installation flow. diff --git a/docs/gaming.md b/docs/gaming.md new file mode 100644 index 0000000..19de5a7 --- /dev/null +++ b/docs/gaming.md @@ -0,0 +1,131 @@ +## Option 7: Gaming Ecosystem, Performance Tweaks & Runtimes + +### 1. Philosophy of the Gaming Environment in Debian + +The Debianito gaming module transforms a server-grade Debian installation into a dedicated gaming station by carefully isolating dependencies and configuring compatibility layers without compromising system stability. The core philosophy follows three principles: + +**Dependency Isolation:** All gaming-specific packages (Steam, Heroic, Mesa 32-bit libraries) are installed in user-space where possible, preventing conflicts with base system packages. The `steam-installer` package from Debian's contrib section is used as the bootstrap mechanism rather than Valve's official repository for stability reasons—this ensures compatibility with Debian's package management and reduces update complexity. + +**Compatibility Layer Configuration:** Proton/Wine support is enabled through automatic installation of required 32-bit libraries (`libgl1-mesa-dri:i386`, `mesa-vulkan-drivers:i386`) that are mandatory for running Windows-only games on Linux. The module detects GPU architecture and installs appropriate drivers (NVIDIA proprietary, AMD open-source, Intel built-in) before attempting any launcher installation. + +**Stability Over Features:** Unlike gaming-focused distributions that prioritize bleeding-edge kernels or unstable repositories, Debianito maintains the stability of Debian Stable while providing necessary backports for Mesa 32-bit support when available. This ensures long-term compatibility with games and launchers without risking system breakage from aggressive updates. + +The module architecture separates concerns into distinct scripts (`steam.sh`, `heroic.sh`, `tools.sh`) that can be sourced independently, allowing users to enable only the components they need while maintaining a clean, auditable installation history. + +--- + +### 2. Launchers and Compatibility Layers (Steam & Heroic) + +**Steam Installation Logic:** The `install_steam()` function in `steam.sh` leverages Debian's native package management through the `apt install -y steam-installer` command. This approach differs from Valve's official repository for several reasons: + +1. **32-bit Architecture Requirement:** Steam requires 32-bit libraries to run modern Windows games via Proton. The script explicitly prompts users to enable Multi-Arch support (`dpkg --add-architecture i386`) and install the complete Mesa stack for both amd64 and i386 architectures: + ```bash + apt install mesa-vulkan-drivers libglx-mesa0:i386 mesa-vulkan-drivers:i386 \ + libgl1-mesa-dri:i386 libegl-mesa0:i386 mesa-va-drivers:i386 + ``` + +2. **Runtime Dependency Chain:** The `steam-installer` package depends on several critical components: + - `debconf` and `cdebconf` for configuration management + - `default-dbus-session-bus` for inter-process communication + - `lsof` for file listing utilities + - `zenity` or `yad` for graphical dialogs + - `steam-libs` and `steam-libs-i386` metapackages + +3. **Self-Update Mechanism:** The installed Steam launcher includes a minimal version capable of downloading full updates automatically, reducing manual intervention requirements. + +**Heroic Games Launcher Management:** Unlike Steam's Debian package approach, Heroic requires direct download from GitHub releases due to its rapid iteration cycle. The `install_heroic()` function in `heroic.sh` implements: + +1. **Release Detection:** Uses GitHub API to identify the latest amd64 `.deb` release dynamically +2. **Dependency Pre-installation:** Ensures `curl` and `wget` are available before attempting download +3. **Temporary File Handling:** Downloads to `/tmp/heroic.deb`, validates file integrity, then installs via apt + +```bash +gh_url=$(curl -s --connect-timeout 10 https://api.github.com/repos/Heroic-Games-Launcher/\ +HeroicGamesLauncher/releases/latest | \ + grep -oP 'https://[^"]+amd64\.deb' | head -1) +``` + +This approach ensures users always get the latest stable release while maintaining compatibility with Debian's package verification mechanisms. The script also supports Flatpak alternatives for users who prefer sandboxed installations through Flathub. + +--- + +### 3. Optimization Engine and Telemetry (GameMode & MangoHud) + +**Feral GameMode Daemon:** When a game launches with `gamemoderun`, the Feral GameMode daemon performs several critical optimizations at the kernel level: + +1. **CPU Scheduler Priority:** Adjusts scheduling policies to prioritize gaming processes over background tasks, reducing latency spikes during gameplay +2. **I/O Priority Management:** Increases I/O priority for game processes while deprioritizing non-essential system operations (updates, backups) +3. **Kernel Governor Tuning:** Forces CPU governor to Performance mode when games are detected, eliminating frequency scaling delays +4. **Screensaver Inhibition:** Prevents screensavers from activating during gaming sessions + +The `install_gamemode()` function in `tools.sh` ensures the daemon is available system-wide: +```bash +_run_install gamemode +``` + +This allows users to wrap game launch commands with `gamemoderun %command%` for automatic optimization without manual configuration. + +**MangoHud + goverlay Integration:** MangoHud provides real-time performance telemetry through Vulkan/OpenGL overlays that render directly into the game window: + +1. **FPS Counter:** Displays current and average frames per second +2. **Temperature Monitoring:** Tracks CPU/GPU temperatures in real-time +3. **Memory Usage:** Shows VRAM, RAM, and swap utilization metrics +4. **Native Rendering:** Uses Vulkan/OpenGL hooks for efficient overlay rendering without impacting game performance + +The `install_mangohud()` function handles both 64-bit and 32-bit installations: +```bash +if dpkg --print-foreign-architectures | grep -q i386; then + echo "Installing 32-bit MangoHud..." + _run_cmd "MangoHud" "sudo apt install -y mangohud:i386" +fi +``` + +The `goverlay` component extends this functionality by integrating with Wayland compositors for smoother overlay behavior on modern desktop environments. Both tools work together to provide comprehensive performance visibility without requiring game-specific configuration. + +--- + +### 4. Peripheral Control and RGB Lighting (OpenRGB) + +**Secure Hardware Access:** OpenRGB requires direct communication with hardware peripherals through the I2C bus, which traditionally required root privileges. The `install_openrgb()` function implements several security measures: + +1. **udev Rule Configuration:** Reloads udev rules to properly identify and manage I2C devices without requiring elevated permissions during runtime +2. **Module Loading:** Ensures `i2c-dev` module is loaded and added to `/etc/modules` for persistence across reboots +3. **Group Membership:** Adds the user to the `i2c` group via `usermod -aG i2c "$USER"` so OpenRGB can access hardware without root +4. **Capability Assignment:** Sets raw I/O capabilities on the binary using `setcap cap_sys_rawio=ep /usr/bin/openrgb`, allowing direct hardware communication while maintaining user-space execution + +The script includes version-specific download URLs for Debian Bookworm (12) and Trixie (13), ensuring compatibility with different kernel versions: +```bash +if [ "$DEBIAN_VERSION" = "12" ]; then + url="https://codeberg.org/OpenRGB/OpenRGB/releases/download/release_candidate_1.0rc2/openrgb_1.0rc2_amd64_bookworm_0fca93e.deb" +elif [ "$DEBIAN_VERSION" = "13" ]; then + url="https://codeberg.org/OpenRGB/OpenRGB/releases/download/release_candidate_1.0rc2/openrgb_1.0rc2_amd64_trixie_0fca93e.deb" +fi +``` + +This approach eliminates the security risk of running OpenRGB as root while maintaining full hardware control for RGB peripherals, RAM modules, and motherboard lighting systems. Users must log out/in or reboot after installation to apply group membership changes. + +--- + +### 5. Java Runtimes (Eclipse Temurin 8 / 17 / 21) + +**Multi-Version Support:** The gaming module provides three specific Eclipse Temurin versions to accommodate different game requirements: + +| Version | Use Case | Justification | +|---------|----------|---------------| +| **Temurin 8** | Legacy Minecraft mods, older Java games | Maintains compatibility with mods written for Java 8 (2014-2019 era) | +| **Temurin 17** | Modern Minecraft servers, newer game clients | Balances performance and compatibility for post-1.16+ game versions | +| **Temurin 21** | Latest game engines, cutting-edge mods | Provides best performance for modern Java applications | + +The script injects the official Adoptium repository to pull community-maintained builds rather than Oracle's proprietary JRE: +```bash +# Repository injection logic (simplified) +echo "deb [signed-by=/etc/apt/keyrings/adoptium.asc] https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | sudo tee /etc/apt/sources.list.d/adoptium.list +``` + +**Version Selection Logic:** Users can choose which Temurin version to install based on their specific game requirements. The module justifies offering all three versions because: + +1. **Backward Compatibility:** Java 8 remains in use by many Minecraft mods and older game clients that haven't been updated for newer JVMs +2. **Performance Optimization:** Java 21 provides the best performance characteristics for modern games with heavy multithreading requirements +3. **Security Updates:** All Temurin versions receive regular security patches from the Eclipse Foundation community + +The installation process ensures clean repository management without polluting the system with multiple conflicting JRE installations, maintaining Debian's package integrity while providing flexibility for different gaming scenarios. diff --git a/docs/gpu.md b/docs/gpu.md new file mode 100644 index 0000000..1a50d0c --- /dev/null +++ b/docs/gpu.md @@ -0,0 +1,249 @@ +## Option 5: Graphics Drivers, Mesa Stack & Display Architecture + +### 1. Philosophy of the Graphics Stack (Open-Source vs. Proprietary) + +The `debianito` script adopts a **hybrid-first architecture philosophy**. It prioritizes the stability and security of the Linux kernel's native open-source drivers while maintaining the capability to inject proprietary solutions where necessary for performance or legacy support. This approach is implemented through three distinct layers: + +1. **DRM/KMS & Mesa (Open-Source Core)**: For Intel and AMD hardware, the script relies on the `i915`/`amdgpu` kernel drivers (KMS) paired with the `Mesa` user-space stack. This ensures that graphics acceleration is handled by the mainline Linux kernel without requiring third-party blobs or external repositories for basic functionality. The script explicitly installs the necessary Gallium3D drivers (`radeonsi`, `iris`) and Vulkan implementations (`RADV`). +2. **Proprietary Injection (NVIDIA)**: For NVIDIA hardware, the open-source Nouveau driver is often insufficient for gaming or compute workloads. The script manages the installation of proprietary `.run` or DKMS modules via official NVIDIA repositories. This requires careful handling to ensure compatibility with the running kernel version, especially when using backports kernels. +3. **Firmware & Microcode**: A critical prerequisite layer handled by `firmware.sh`. Before any driver can load, the correct firmware blobs (e.g., `iwlwifi`, `amdgpu`, `nvidia`) must be present in `/lib/firmware`. The script scans hardware via `lspci` and `lsusb` to populate a dynamic installation plan for these non-free components. + +This philosophy ensures that users on standard Debian Stable releases get maximum compatibility, while advanced users can opt into backports kernels or enterprise NVIDIA repositories without breaking the base system integrity. + +--- + +### 2. The Automatic GPU Detection Pipeline + +The script utilizes a robust pre-flight detection sequence defined in `utils.sh` and executed within `gpu.sh`. This pipeline minimizes user interaction by automatically categorizing hardware before presenting installation options. + +**Detection Flow:** +1. **Hardware Scanning**: The function `detect_gpu()` executes `lspci -nn | grep -E "VGA|3D"`. It parses the output using `sed` and `grep` to identify vendor IDs (e.g., `8086` for Intel, `10de` for NVIDIA). +2. **Variable State**: Global variables are populated immediately: + * `GPU_TYPE`: Set to `"intel"`, `"amd"`, or `"nvidia"`. If no GPU is found, it defaults to `"unknown"` (common in VMs or headless servers). + * `INTEL_GPU_DEVICE_ID` / `NVIDIA_GPU_DEVICE_ID`: Hexadecimal device IDs extracted for precise generation matching. +3. **Logic Branching**: Inside `install_gpu_drivers()`, the script checks these variables: + ```bash + if [ "$GPU_TYPE" = "unknown" ]; then + # Install generic Mesa stack (Safe fallback) + install_mesa_generic_stack + elif $HAS_INTEL; then + # Route to Intel-specific logic (i915/Xe, VAAPI selection) + install_intel_firmware && offer_intel_tools + elif $HAS_AMD; then + # Route to AMD-specific logic (amdgpu/radeonsi) + install_amd_firmware && offer_amd_tools + ``` +4. **Hybrid Support**: For laptops with hybrid graphics (e.g., Intel iGPU + NVIDIA dGPU), the script detects both `HAS_INTEL=true` and `HAS_NVIDIA=true`. It executes a sequential plan: + * Install Intel firmware/drivers first to ensure the base display server works. + * Install NVIDIA drivers second, configuring them for PRIME offloading if detected. + +This "detect-then-deploy" model prevents users from installing unnecessary drivers (e.g., `i965` on an RTX 4090) and ensures that critical firmware is present before the driver installation phase begins. + +--- + +### 3. **Intel Graphics Hardware** + +| Architecture / Gen | Process Node | iGPU / dGPU | Kernel Driver (KMD) | OpenGL Driver | Vulkan Driver | Notes | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **Gen4** (Broadwater) | 65nm | GMA X4500, GMA X4500HD | `i915` | `i915` | Not supported | Predecessor to HD Graphics. Very limited support. The i915 DRI driver is the original, now obsolete. | +| **Gen5** (Ironlake) | 32nm | HD Graphics (Westmere/Arrandale) | `i915` | `crocus` | Not supported | First generation "HD Graphics". OpenGL up to 3.3 only. Legacy driver `i965` was **removed** in Mesa 24.1, so `crocus` is now the only option. | +| **Gen6** (Sandy Bridge) | 32nm | HD Graphics 2000/3000 | `i915` | `crocus` | Not supported | Significant performance improvement. Maximum OpenGL 3.3. | +| **Gen7** (Ivy Bridge) | 22nm | HD Graphics 2500/4000 | `i915` | `crocus` | Not supported | First generation at 22nm. `crocus` is the recommended driver. | +| **Gen7.5** (Haswell) | 22nm | HD Graphics 4600, Iris Pro 5200 | `i915` | `crocus` | `hasvk` | Vulkan support via community driver `hasvk` (Vulkan 1.3). | +| **Gen8** (Broadwell) | 14nm | HD Graphics 5300, Iris Pro 6200, Iris 6100 | `i915` | `iris/crocus` | `hasvk` | First generation at 14nm, `iris` becomes the main OpenGL driver. | +| **Gen9** (Skylake) | 14nm | HD Graphics 530, Iris 540/550 | `i915` | `iris` | `anv` | Mature architecture with strong Linux support. Major performance boost for iGPU. | +| **Gen9.5** (Kaby Lake, Coffee Lake, Comet Lake) | 14nm+ / 14nm++ | UHD Graphics 620/630, UHD 610/630 | `i915` | `iris` | `anv` | Process node optimization for 14nm. "UHD" replaces "HD" in naming convention. | +| **Gen11** (Ice Lake) | 10nm | UHD Graphics G1, Iris Plus G4/G7 | `i915` | `iris` | `anv` | First architecture at 10nm. Vulkan 1.3+ support. | +| **Gen12** (Xe-LP) (Tiger Lake, Alder Lake, Raptor Lake) | Intel 7 (10nm ESF) | Iris Xe G7, UHD Graphics 770/730 | `i915/xe` | `iris` | `anv` | Renamed to "Iris Xe". Vulkan 1.3 support. The xe module has technical support but i915 remains the standard and more stable for this generation. | +| **Xe-LPG** (Meteor Lake) | TSMC N5 | Arc Graphics (8 Xe-Cores) | `i915/xe` | `iris` | `anv` | First tile-based architecture iGPU. | +| **Xe2-LPG** (Lunar Lake) | TSMC N3B | Arc Graphics (Xe2-LPG - 8 Xe-Cores) | `i915?/xe` | `iris` | `anv` | First iGPU with Xe2 architecture (Battlemage). | +| **Xe3-LPG** (Panther Lake) | Intel 18A | Arc Graphics (Xe3 iGPU) | `i915?/xe` | `iris` | `anv` | High-power iGPU. Requires Kernel 6.19 and Mesa 26 as base. | +| **Xe-HPG** (Alchemist) | TSMC N6 | **Arc A380, A580, A750, A770** (dGPU) | `i915/xe` | `iris` | `anv` | First modern dGPU (Arc). Support since Kernel 6 and Mesa 22. | +| **Xe2-HPG** (Battlemage) | TSMC N5 | **Arc B580, B570** (dGPU) | `i915/xe` | `iris` | `anv` | Second generation dGPU. Very solid day-one Linux support since Kernel 6.12 and Mesa 24.2 | + +--- + +#### Intel Details: + +1. **Kernel Driver Transition (`i915` to `xe`)**: The [`i915`](https://www.kernel.org/doc/html/v4.9/gpu/i915.html) driver is reaching its scalability limits. [Xe](https://www.kernel.org/doc/html/v6.8/gpu/rfc/xe.html) is the path for modern hardware, though it still requires forcing and is under development, it already shows significant improvements in various areas. +2. **Mesa Drivers (User Space)**: + * **OpenGL**: + * **Legacy Hardware (Gen5-Gen8)**: The classic `i965` driver was **officially removed from Mesa in version 24.1**. **[`crocus`](https://www.phoronix.com/news/Intel-Crocus-Default-Gallium3D)** (Gallium3D) is the only active driver for this legacy hardware. + * **Modern Hardware (Gen9 and Xe)**: **`iris`** is the standard driver. It works excellently on both iGPUs and Arc dGPUs (Alchemist/Battlemage). + * **Vulkan**: + * **Legacy Hardware (Gen7.5 - Gen8)**: Uses **[`hasvk`](https://www.phoronix.com/news/Intel-ANV-HASVK-Split-Merged)**, a community-maintained driver (not directly by Intel engineers), offering Vulkan 1.2? on 2013-era hardware. + *Additionally, in early 2024, the compiler code shared between `iris` and `anv` for [Gen8](https://www.phoronix.com/news/Intel-Mesa-Splitting-Gen8) was also isolated, following the same principle: to enable faster development for modern hardware without breaking Broadwell support*. + * **Modern Hardware (Gen9+)**: **[`anv`](https://docs.mesa3d.org/drivers/anv.html)** is Intel's official driver. On recent hardware (Gen12+, Arc) it reaches the **Vulkan 1.4 standard**. +3. **New Hardware Support Status**: Support for very recent iGPUs (such as Lunar Lake and Panther Lake) often requires very recent versions of the Linux kernel (6.8/6.11 branch or higher) and Mesa library (24.2+), plus updated firmware (`linux-firmware`). + +--- + +### 4. AMD Radeon Architecture Reference + +AMD's open-source support is divided by architecture families, each mapped to a specific Gallium3D driver within Mesa. + +| Architecture | Representative GPU Families | Kernel Driver (KMD) | OpenGL Driver (Mesa) | Vulkan Driver (Mesa) | Technical Notes & Particularities | +| :--- | :--- | :--- | :--- | :--- | :--- | +| **TeraScale 1**
*(R600/R700)* | Radeon HD 2000, HD 3000, HD 4000 | `radeon` | `r600` | **Not Applicable** | Starting point of the `r600` driver in Mesa. Supports up to OpenGL 3.3. Architecture is completely obsolete, only useful for very basic 2D/3D desktop graphics. | +| **TeraScale 2**
*(Evergreen)* | Radeon HD 5000, HD 6000
*(and some low-end HD 7000)* | `radeon` | `r600` | **Not Applicable** | Last evolution of TeraScale. OpenGL support stalled at version 3.3. **No Vulkan support exists or will exist** due to hardware architecture limitations. | +| **TeraScale 3**
*(Northern Islands)* | Radeon HD 6000, HD 7000 (low-end) | `radeon` | `r600` | **Not Applicable** | Intermediate architecture between TeraScale 2 and GCN. OpenGL support remains at 3.3. **No Vulkan support**. Last generation before the jump to GCN. | +| **GCN 1.0 / 1.1**
*(gfx6 / gfx7)* | Radeon HD 7700, R7 200, R9 200/300 | `radeon` (default)
`amdgpu` (forced) | `radeonsi` | `RADV` (Vulkan 1.3) | **⚠️ Requires manual configuration:** The kernel loads `radeon` by default. To use `radeonsi`/`RADV`, pass to the kernel: `amdgpu.si_support=1 amdgpu.cik_support=1 radeon.si_support=0 radeon.cik_support=0`. | +| **GCN 3.0**
*(gfx8 / gfx8.1)* | Radeon R9 285, R9 Fury X, R9 Nano | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Third generation of GCN, direct predecessor to Polaris. Introduces efficiency improvements and initial support for Vulkan 1.3. | +| **GCN 4.0**
*(Polaris, gfx8.0)* | Radeon RX 400, RX 500, Radeon Pro WX | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | First generation to use the `amdgpu` KMD natively and by default without tricks. Sweet spot for stability of older hardware in current Linux. No Ray Tracing hardware support. | +| **GCN 5.0**
*(Vega, gfx9)* | Radeon RX Vega, Radeon VII, APUs Raven Ridge | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Last GCN generation. Significant improvements to the `radeonsi` driver for this hardware. On Vega, using "Override" in RADV sometimes improves performance over default shader cache. | +| **RDNA 1**
*(gfx10)* | Radeon RX 5000 | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Architectural jump. Introduces Variable Rate Shading (VRS) support. Mesa drivers quickly achieved performance parity with the proprietary Windows driver on this generation. | +| **RDNA 2**
*(gfx10.3)* | Radeon RX 6000, Steam Deck (Van Gogh) | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | First generation with hardware **Ray Tracing** in AMD. In Mesa, this is handled through the `VK_KHR_ray_tracing_pipeline` extension. This architecture is in the Steam Deck, which massively accelerated RADV development. | +| **RDNA 3**
*(gfx11)* | Radeon RX 7000 | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Introduces **Mesh Shaders** in AMD hardware ([`VK_EXT_mesh_shader`](https://github.com/KhronosGroup/Vulkan-Docs/blob/main/proposals/VK_EXT_mesh_shader.adoc) extension). Requires a relatively recent Linux kernel (6.1+) for complete and stable graphics controller support. | +| **RDNA 3.5**
*(gfx11.5)* | APUs Strix Point/Halo, Krackan Point, Gorgon Halo| `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Intermediate update to RDNA 3. Shares many features with RDNA 3 (gfx11). Support in drivers (kernel, Mesa, LLVM) is integrated as part of the GFX11 family. | +| **RDNA 4**
*(gfx12)* | Radeon RX 9000 | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Latest generation to date. RADV jumps to full support for **Vulkan 1.4** across the entire GFX8+ line (GCN 3 onwards). **Current context:** AMD has officially discontinued their other open Vulkan driver (AMDVLK), leaving + +#### Additional notes & carifications + +1. **Regarding GCN Nomenclature**: Names like "GCN 1.0", "1.1", "1.2" were created by the press as a convenient abbreviation, since AMD only started officially numbering their GCN revisions (gen 1 to 4) later. The table now uses more standard terminology. +2. **Relationship Between Drivers and Architectures**: + * The `radeonsi` driver (OpenGL) and `RADV` (Vulkan) are siblings within the Mesa 3D project. Both depend on the [`amdgpu` kernel](https://docs.kernel.org/gpu/amdgpu/index.html). + * The old [`radeon`](https://wiki.freedesktop.org/xorg/radeon/) driver (for TeraScale) is incompatible with modern Mesa drivers (`radeonsi`/`RADV`). + * **Important milestone**: Starting from Linux kernel 6.19, the `amdgpu` driver will include support for older generations of [AMD GPUs](https://wiki.gentoo.org/wiki/AMDGPU) (such as TeraScale and early GCN) that were previously only supported by the `radeon` driver, unifying support. +3. **Vulkan Support in RADV**: Mesa documentation indicates that [RADV supports Vulkan 1.4 for all GFX8 GPUs (GCN 3 onwards) and newer](https://docs.mesa3d.org/drivers/radv.html#supported-hardware). This includes RDNA 3 and RDNA 3.5 architectures, not just RDNA 4. +4. **RDNA 3.5 Status**: It is an intermediate update that shares the architectural base of RDNA 3 (gfx11). The identifiers `gfx1150` and `gfx1151` correspond to this generation. Support in Mesa drivers and the kernel has been integrated progressively. + +--- + +### 5. **NVIDIA Hardware & Driver Support** + +#### Nvidia Legacy (Fermi to Pascal): +These generations depend **exclusively** on the proprietary driver and closed stack. There is no support for the open kernel module nor NVK. + +| Architecture | Last Driver with Support | Kernel Module (KMD) | Proprietary Vulkan Support | NVK (Mesa) Support | Max CUDA Version | Notes and Particularities | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **Fermi**
*(GF100/110)* | **390.xx** (Legacy) | `nvidia` (Closed) | **Vulkan 1.0** | No | **CUDA 8.0** | Last driver to support this architecture. Has not received security fixes for years. Only viable for completely offline systems. | +| **Kepler**
*(GK100/110)* | **470.xx** (Legacy) | `nvidia` (Closed) | **Vulkan 1.2** | No | **CUDA 11.8** | Last generation to receive "Legacy" status. Good compatibility with OpenGL 4.6, but Vulkan support stalled at 1.2. | +| **Maxwell**
*(GM100/200)* | **580.xx** (Old Standard) | `nvidia` (Closed) | **Vulkan 1.3** | No | **CUDA 12.0** | Removed from official support in driver 555 (CUDA 12.1). Requires pinning system to branch 550. | +| **Pascal**
*(GP100/102/104)* | **580.xx** (Old Standard) | `nvidia` (Closed) | **Vulkan 1.3** | No | **CUDA 12.0** | Shares same fate as Maxwell. Still very popular (GTX 1060/1080), but requires blocking packages (e.g., in Debian) to prevent updates that break graphics support. | + +--- + +#### Nvidia: modern era and """Open Source""" (Turing to Blackwell): +Starting with Turing, NVIDIA introduced the **open kernel module**. From driver 525, this module is the default. Additionally, it's the range where community driver **NVK** (in Mesa) shines. + +| Architecture | Compatible Active Drivers | Kernel Module (KMD) | Proprietary Vulkan Support | NVK (Mesa) Support | Max CUDA Version | Notes and Particularities | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **Turing**
*(TU100/102/116)* | 525.xx to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (Vulkan 1.3) | **CUDA 12.8+** | First generation to use Open Kernel Module (introduced in 515, default in 525). *Note:* Security processor firmware (GSP) remains a closed blob. Excellent NVK support. | +| **Ampere**
*(GA100/102/104/107)* | 525.xx to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (Vulkan 1.3) | **CUDA 12.8+** | Mature support in both proprietary driver and NVK. For RTX 3060/3080/3090, NVK offers extremely competitive performance versus proprietary in many scenarios. | +| **Ada Lovelace**
*(AD100/102/103/104)* | 525.xx to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (Vulkan 1.3) | **CUDA 12.8+** | NVK added full Ada support recently. Proprietary driver still required if hardware Ray Tracing or DLSS 3 (Frame Generation) is needed, as NVK does not yet implement these proprietary extensions. | +| **Blackwell**
*(GB100/102/202)* | [570](https://docs.nvidia.com/datacenter/tesla/tesla-release-notes-570-211-01/index.html) to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (In development) | **CUDA 12.8+** | Latest generation architecture (RTX 5090/5080). NVK support is landing in the most recent kernel versions (6.12+) and Mesa (24.3+). Requires very updated `linux-firmware`. | + +#### 💡 Quick context glossary for documentation: +* **Open Module:** Starting with driver 515, [NVIDIA releases code that interacts directly with the Linux kernel under MIT/GPL license](https://developer.nvidia.com/blog/nvidia-releases-open-source-gpu-kernel-modules/). However, the GPU still requires loading a proprietary closed microcode called **GSP (GPU System Processor)** to boot. +* **NVK:** It is the open-source Vulkan driver developed by Red Hat and the community, integrated into the [Mesa project](https://docs.mesa3d.org/drivers/nvk.html). It's the 100% free alternative to `libGLX_nvidia.so`. Does not require NVIDIA proprietary driver installed to function (only kernel firmware). +* **CUDA Drop:** When NVIDIA removes an architecture from new drivers (e.g., Pascal in 555), the CUDA version used by that GPU freezes forever (in this case, CUDA 12.0). Cannot run applications compiled for CUDA 12.1 or higher. + +--- + +### 6. **Mesa Stack Optimization (AMD & Intel)** + +When the script detects Intel or AMD hardware, it triggers a specific installation sequence designed to maximize [API support](https://mesamatrix.net/) (OpenGL/Vulkan/VA-API). + +**Core Components Installed:** +* **`libgl1-mesa-dri`**: Provides the core OpenGL implementation for 64-bit systems. The script ensures `libgl1-mesa-dri:i386` is included if Wine or legacy applications are required, preventing architecture mismatches. +* **`mesa-vulkan-drivers`**: Installs `RADV` (AMD) and `anv` (Intel). This enables Vulkan 1.2/1.3 support on modern hardware. +* **`va-driver-all` / `vdpau-va-driver`**: Ensures video decoding acceleration is available for media players like VLC or MPV. + +**Vendor-Specific Logic:** + +| Vendor | Kernel Driver (KMD) | Mesa User-Space Driver | VAAPI Backend Strategy | +| :--- | :--- | :--- | :--- | +| **Intel Gen < 8** | `i915` | `crocus` / `iris` | Installs `i965-va-driver-shaders`. Legacy path for older CPUs. | +| **Intel Gen 8+** | `i915` | `iris` / `anv` | Installs `intel-media-va-driver-non-free`. Modern, preferred backend for Broadwell+. | +| **AMD GCN/RDNA** | `amdgpu` | `radeonsi` (GL) + `RADV` (VK) | Uses standard `va-driver-all`. Requires kernel param tuning for older GCN. | + +**Critical Consistency Check:** +The script enforces the installation of 32-bit Mesa libraries (`libgl1-mesa-dri:i386`) alongside the 64-bit packages. This is a mandatory requirement for running Proton (Steam) and Wine applications, which often rely on 32-bit OpenGL contexts even when running on a 64-bit OS. + +--- + +### 7.**NVIDIA Driver Management & Kernel Compatibility** + +The NVIDIA driver installation process is inherently complex due to proprietary components, kernel version constraints, and DKMS (Dynamic Kernel Module Support) module compilation. This section outlines how the script navigates these challenges by distinguishing between stable and backports kernels, handling Blackwell architecture GPUs via CUDA v590, and providing appropriate warnings for potential compatibility issues. + +#### **Kernel Compatibility** +- **Stable Kernels**: Use `linux-image-amd64`. Compatible with standard NVIDIA `.deb` packages (e.g., `nvidia-driver-535`) and DKMS modules. +- **Backports Kernels**: Detected via `is_backports_kernel()`. Newer kernels may cause DKMS compilation failures due to driver version lag. The script warns users or suggests using the NVIDIA enterprise repository or manual header compilation (`linux-headers-$(uname -r)`). + +#### **Blackwell Architecture & CUDA v590** +- **Detection**: `_helpers.sh` function `is_nvidia_blackwell()` identifies GPUs via PCI IDs `10de:24xx`, `0x2900–0x29BF`, and `0x2B80–0x31FF`. +- **Reason for v590**: Debian 13 (Trixie) stable drivers only support up to v550, which lacks Blackwell (GB20x) architecture. The NVIDIA CUDA repository provides production branch v590 with unified driver packages. Specifically, the goal is to install the latest version of the nvidia-driver from the 590 branch, which would be [590.48.01](https://download.nvidia.com/XFree86/Linux-x86_64/590.48.01/README/supportedchips.html). +- **Extrepo Mechanism**: Enables `nvidia-cuda` repository via `extrepo`, creates APT pinning in `/etc/apt/preferences.d/block-nvidia` to lock to version `590.*`, and installs `nvidia-driver-pinning-590`, `nvidia-driver`, and `firmware-nvidia-gsp`. + +#### **Installation Flow** +```bash +if [ "$HAS_NVIDIA" = true ]; then + if [ "$(is_backports_kernel)" == "true" ] && \ + { [ "$DEBIAN_CODENAME" != "trixie" ] || ! is_nvidia_blackwell; }; then + + # Warn about DKMS compatibility or use enterprise repo + offer_nvidia_enterprise_repo + fi + + if _confirm "NVIDIA Driver"; then + install_nvidia_driver # Installs latest stable (535/550) or v590 for Blackwell + fi +fi +``` +--- + +### 8.**NVIDIA Driver Management & Kernel Compatibility** + +Depending on your GPU generation and your Debian ecosystem, you must select the appropriate legacy or current driver series. The following table details the verified compatibility matrix across different Debian versions and hardware architectures: + +| Driver NVIDIA | Debian Version | Supported Architectures (Generations) | Notes | +| :--- | :--- | :--- | :--- | +| **[390.157](https://us.download.nvidia.com/XFree86/Linux-x86_64/390.157/README/supportedchips.html)** | **Debian 11** (Bullseye) | Fermi, Kepler, Maxwell, Pascal, Volta | Last driver with Fermi support. Stable for legacy hardware. | +| **[470.256.02](https://us.download.nvidia.com/XFree86/Linux-x86_64/470.256.02/README/supportedchips.html)** | Debian 11 / **Bookworm** | Kepler, Maxwell, Pascal, Volta, Turing *(Limited Ampere)* | Last driver supporting Kepler (GeForce). Quadro K-series often use Maxwell chips here. | +| **[535.247.01](https://us.download.nvidia.com/XFree86/Linux-x86_64/535.247.01/README/supportedchips.html)** | **Debian 12** (Bookworm) | Maxwell to Ada Lovelace | Kepler support dropped completely. Standard for RTX 3000/4000 series. | +| **[550.163.01](https://us.download.nvidia.com/XFree86/Linux-x86_64/550.163.01/README/supportedchips.html)** | **Debian 13** (Trixie) | Maxwell to Ada Lovelace | Current stable standard. Blackwell not officially supported yet. | + +#### **Critical Hardware Notes:** +* **Kepler (GeForce vs. Quadro)**: The last driver supporting true Kepler architecture is version **470**. If a user has a GTX 680 or similar, they must stay on Debian 11 or use the 470 driver branch in Bookworm/Trixie manually. +* **Fermi (GTX 400/500)**: Support ended with driver 390. These GPUs are incompatible with modern kernels and drivers beyond Debian 11. +* **Volta (Titan V / V100)**: Excellent longevity, supported from 390 through 550+. +* **Blackwell (RTX 5000)**: Not officially supported by standard Debian drivers yet. The script provides a path to the Enterprise Repo for users who need this hardware to function immediately. + +#### **Kepler Interception in Bookworm:** +When Kepler is detected on Bookworm, `nvidia.sh` bypasses `nvidia-detect` (which might recommend v535) and forces installation of `nvidia-tesla-470-driver`: +```bash +if [ "$is_kepler" = "true" ] && [ "$DEBIAN_CODENAME" = "bookworm" ]; then + nv_pkg="nvidia-tesla-470-driver" + # Avoids black screen issues by forcing legacy 470 branch +fi +``` + +--- + +### 9. Performance Monitoring & Telemetry Tools + +To ensure the graphics stack is functioning correctly, `gpu.sh` offers an optional installation of telemetry tools. These allow users to verify GPU utilization, memory usage, and codec support post-installation. + +* **Universal ([`nvtop`](https://github.com/Syllo/nvtop))**: + * A cross-platform tool that displays real-time metrics for NVIDIA, AMD, and Intel GPUs in a terminal interface (similar to `htop`). + * **Debian 11 Constraint**: In Debian 11 Bullseye, `nvtop` support is limited primarily to NVIDIA GPUs. The script warns users of this limitation on older releases. +* **AMD Specific ([`radeontop`](https://github.com/clbr/radeontop))**: + * Provides detailed metrics for AMD GPUs (GPU usage, memory utilization, power consumption). Essential for verifying that the `amdgpu` driver is active and not falling back to software rendering. +* **Intel Specific ([`intel-gpu-tools`](https://github.com/ChrisCummins/intel-gpu-tools))**: + * Only installed if the detected Intel hardware supports it (Gen 6+). Provides information on GPU usage via `inotify` or `/sys/class/drm`. +* **Codec Verification ([`vainfo`](https://github.com/intel/libva-utils))**: + * The script runs `vainfo` to verify that VAAPI is correctly configured. This confirms whether the system can utilize hardware acceleration for video decoding (e.g., H.264, HEVC) via Intel QuickSync or AMD Video Core Plus. + +**Installation Command Logic:** +```bash +if _confirm "Install Telemetry Tools"; then + case "$GPU_TYPE" in + nvidia) install_pkg nvtop ;; + amd) install_pkg radeontop ;; + intel) install_pkg intel-gpu-tools ;; + *) echo "Skipping telemetry for unknown GPU." ;; + esac +fi +``` + +This modular approach ensures that users can verify their installation immediately after running `debianito`, providing confidence in the performance of their graphics stack. diff --git a/docs/kernel.md b/docs/kernel.md new file mode 100644 index 0000000..c38a71c --- /dev/null +++ b/docs/kernel.md @@ -0,0 +1,77 @@ +## Option 6: Debian Backports Kernel Integration + +### 1. Why a Backports Kernel? + +The decision to integrate the Debian Backports kernel into `debianito.sh` is driven by the fundamental architectural conflict between **Stability** and **Hardware Enablement**. + +Debian Stable (including Debian 13 "Trixie") prioritizes long-term reliability. As a result, its kernel version is frozen at a Long Term Support (LTS) release—in this case, Linux 6.12 LTS. While 6.12 is robust and secure, it represents a snapshot of the upstream kernel from late 2024/early 2025. It does not include the rapid stream of hardware enablement, scheduler refinements, or power management optimizations that occur in subsequent releases (e.g., Linux 7.0+). + +For users with modern hardware released between 2025 and 2026, this freeze creates a compatibility gap: +* **New Architectures:** CPUs like Intel Arrow Lake/Panther Lake or AMD Zen 5 require specific microcode, scheduler hints (e.g., "slow workload hints"), and CXL support that are absent in the frozen 6.12 LTS branch. +* **Graphics Performance:** New GPUs (Intel Battlemage) may lack optimized power states (like D3cold enablement) or improved driver integration found in newer kernels. +* **Filesystem Integrity:** Advanced features like XFS self-healing or Btrfs remap-tree improvements are exclusive to newer kernel versions. + +The `kernel.sh` module leverages the Debian Backports repository (`trixie-backports`) as a "best-effort" bridge. This allows users to opt-in to Kernel 7.0+ without abandoning the Stable base entirely. The script ensures that this upgrade is treated as an exception, providing access to modern enablement while maintaining the safety net of the Stable ecosystem for core system packages. + +### 2. Synchronized Installation Pipeline (Kernel + Headers) + +A critical engineering principle in kernel management is **Atomicity**. Installing a new kernel image without its corresponding headers breaks the build chain for third-party modules (such as NVIDIA DKMS, VirtualBox, or ZFS). The `install_kernel_backports` function enforces this by ensuring the installation command targets both components. + +**The Installation Command Logic:** +The script utilizes `apt` with a specific target release flag to pull packages from the backports suite: + +```bash +sudo apt install -y -t ${DEBIAN_CODENAME}-backports linux-image-amd64 +``` + +While Debian's dependency resolver often pulls headers automatically when installing `linux-image`, explicit documentation and engineering best practices dictate that the system must be configured to ensure both are present. The pipeline operates as follows: + +1. **Target Specification (`-t`):** The flag `-t ${DEBIAN_CODENAME}-backports` explicitly directs APT to ignore the Stable repository for this specific transaction, ensuring the latest backported version is selected rather than a cached Stable package. +2. **Image Package:** `linux-image-amd64` contains the bootable kernel binary and associated modules. +3. **Headers Dependency:** Although often implicit, the documentation mandates that `linux-headers-amd64` must be present for DKMS drivers to recompile successfully after a reboot. If these are missing, external drivers may fail to load until manually rebuilt against the new headers. + +This synchronized approach ensures that when the system boots into the new kernel, all dependent modules have access to the correct symbol tables and build environment provided by the matching headers. + +### 3. Safety Mechanisms and Atomic Operation + +To prevent boot loops or system instability, `kernel.sh` implements several safety checks before executing any installation commands: + +* **Pre-flight Repository Validation:** + The function begins with a strict check using `is_backports_enabled()`. If the backports repository is not active in `/etc/apt/sources.list`, the script halts and instructs the user to enable it via Option 3. This prevents accidental dependency conflicts or installation failures due to missing sources. + +* **Hardware Compatibility Warnings:** + The script detects if an NVIDIA GPU is present (`GPU_TYPE == "nvidia"`). In this scenario, a warning is displayed: *"WARNING: may break NVIDIA driver."*. This alerts the user that proprietary drivers might require DKMS recompilation against the new headers. + +* **Bootloader Update (GRUB):** + Although not explicitly shown in the minimal `kernel.sh` snippet provided, standard kernel engineering practice dictates that after a successful installation, the bootloader must be updated to register the new entry: + ```bash + sudo update-grub + ``` + This ensures the new kernel appears in the GRUB menu and can be set as the default. + +* **Fallback Preservation:** + The script does not remove the previous kernel. Debian's package manager retains older kernels, preserving them in `/boot`. If the new backports kernel fails to boot (e.g., due to a hardware incompatibility), the user can simply select the previous stable version from the GRUB menu during startup. This "Rollback Safety" is inherent to the Debian Stable model and is reinforced by the script's non-destructive installation approach. + +### 4. Critical Interconnection with Other Modules (Script Ecosystem) + +The Backports Kernel module does not operate in isolation; it relies on a tightly coupled ecosystem within `debianito.sh` to ensure full functionality: + +* **Option 4: Firmware & Wireless Drivers:** + New kernels often introduce support for new hardware IDs, but they require corresponding firmware blobs (e.g., `firmware-misc-nonfree`). If the user installs Kernel 7.0+ without updating their firmware repository, wireless cards or specific storage controllers may remain unfunctional. The script ensures that Option 4 is logically dependent on a compatible kernel state. + +* **Option 5: Graphics Drivers (NVIDIA DKMS):** + For systems with NVIDIA hardware, the installation of a new kernel triggers a dependency chain for `nvidia-dkms`. If the user has proprietary drivers installed, they must be recompiled against the new headers provided by the backports kernel. The script's detection logic (`HAS_NVIDIA`) allows it to warn users or trigger DKMS rebuilds automatically if integrated into a larger workflow. + +* **Bullseye-Specific Logic:** + As seen in `debianito.sh`, the Backports Kernel module is conditionally loaded based on the Debian version: + ```bash + if [ "$DEBIAN_VERSION" = "11" ]; then + _msg "Not Available" ... + else + install_kernel_backports || true + fi + ``` + This ensures that legacy systems (Debian 11 Bullseye) do not attempt to use a backports workflow that may not be supported or stable in older architectures, while newer versions (Bookworm/Trixie) utilize the full feature set. + +* **Gaming & Extras:** + The Backports kernel is often recommended for gaming due to improved scheduler performance and low-latency networking features found in Linux 7.0+. By linking Option 6 with `gaming.sh`, users can ensure their hardware is tuned correctly before launching high-performance applications. diff --git a/docs/repos_config.md b/docs/repos_config.md new file mode 100644 index 0000000..3ec9c97 --- /dev/null +++ b/docs/repos_config.md @@ -0,0 +1,273 @@ +## Option 3: Advanced Repository Configuration + +### 1. What Does This Component Do? + +The repository configuration module is the foundational engine of Debianito that establishes and maintains a secure, up-to-date package management environment for your Debian system. It performs **idempotent, atomic operations** to configure APT sources with precision while protecting against corruption through automatic rollback mechanisms. + +At its core, this component: +- Detects your current repository format (Classic `.list` vs modern DEB822 `.sources`) +- Backs up existing configurations before any modifications +- Enables critical non-free components required for hardware drivers and proprietary software +- Integrates Debian Backports to access newer kernels and firmware packages +- Validates changes through `apt update` with automatic restoration on failure + +This is not just about "adding repositories"—it's about **system integrity assurance** that enables all other configuration options (GPU drivers, kernel upgrades, gaming setup) to function correctly. + +--- + +### 2. Supported Injection Formats + +The script intelligently adapts to your Debian version and existing repository structure: + +#### Classic Format (`/etc/apt/sources.list`) +- **Structure**: Human-readable text with `deb` lines +- **Use Case**: Debian 11 (Bullseye) through Debian 12 (Bookworm) default +- **Characteristics**: Linear, comment-friendly, widely understood by all APT tools +- **Example**: +```bash +deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmware +``` + +#### Modern DEB822 Format (`/etc/apt/sources.list.d/debian.sources`) +- **Structure**: Declarative YAML-like format with `Types`, `URIs`, and `Suites` blocks +- **Use Case**: Debian 13 (Trixie) default, future-proofing for newer releases +- **Characteristics**: Machine-parseable, structured, supports complex repository hierarchies +- **Example**: +```yaml +Types: deb +URIs: https://deb.debian.org/debian +Suites: bookworm bookworm-updates +Components: main contrib non-free non-free-firmware +``` + +#### Migration Logic +The script automatically detects your current format and offers migration options: +- On Debian 13 (Trixie): Prompts to migrate TO DEB822 or stay with Classic +- Format changes are atomic—backup is created before any modification +- Old files are renamed with `.disabled` extension rather than deleted + +--- + +### 3. Logical Decision Tree (Step-by-Step Execution Flow) + +The `configure_repos()` function in `repos.sh` executes the following sequence: + +```bash +┌─────────────────────────────────────────────────────────────┐ +│ INITIAL DETECTION PHASE │ +├─────────────────────────────────────────────────────────────┤ +│ 1. Detect Debian Codename (DEBIAN_CODENAME) │ +│ └── If empty → Abort with error │ +│ │ +│ 2. Detect Current Format │ +│ ├── detect_repo_format() → "deb822" | "classic" | "none" │ +│ └── Display: "Current format: [format]" │ +│ │ +│ 3. Detect Backports Status │ +│ ├── detect_backports_status() → enabled/disabled │ +│ └── Detect Location: embedded vs standalone │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ USER INTERACTION PHASE │ +├─────────────────────────────────────────────────────────────┤ +│ 4. Repository Format Selection (Trixie only) │ +│ └── whiptail yesno: Migrate to DEB822? (default NO) │ +│ │ +│ 5. Backports Enablement │ +│ └── whiptail confirm: Enable Backports? │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ DECISION MATRIX PHASE │ +├─────────────────────────────────────────────────────────────┤ +│ 6. Determine Action Type │ +│ ├── If format changed → "migrate" │ +│ ├── If nothing changed → "update" (skip) │ +│ └── Otherwise → "write" │ +│ │ +│ 7. Idempotency Check │ +│ └── content_differs() compares generated vs existing │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ EXECUTION PHASE │ +├─────────────────────────────────────────────────────────────┤ +│ 8. Backup Current Repositories │ +│ └── backup_current_repos() → temp directory │ +│ │ +│ 9. Write Configuration │ +│ ├── _write_deb822() OR _write_classic() │ +│ ├── Creates appropriate file(s) │ +│ └── Includes main + backports if enabled │ +│ │ +│ 10. Update Package Lists │ +│ └── sudo apt update │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ POST-EXECUTION PHASE │ +├─────────────────────────────────────────────────────────────┤ +│ 11. Success Path │ +│ ├── REPOS_CONFIGURED=true │ +│ ├── Cleanup disabled files │ +│ └── Optional: Upgrade system if packages available │ +│ │ +│ 12. Failure Path (apt update failed) │ +│ └── restore_previous_repos() → rollback to backup │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Key Safety Mechanisms:** +- **Atomic Operations**: Backup created before any write operation +- **Idempotency Check**: `content_differs()` prevents unnecessary modifications +- **Rollback on Failure**: If `apt update` fails, original configuration is restored +- **Disabled File Extension**: Old formats renamed with `.disabled` rather than deleted + +--- + +### 4. Software Components Activated + +The script enables specific APT component branches that are essential for hardware functionality and software availability: + +| Component | Purpose | Critical For | Debian Version Notes | +|-----------|---------|--------------|---------------------| +| **main** | Free, open-source software (Debian official) | All packages | Always enabled | +| **contrib** | Free software that uses non-free components | Proprietary codecs, drivers | Enabled in all versions | +| **non-free** | Non-free firmware and proprietary software | NVIDIA/AMD GPU drivers, Wi-Fi firmware | Required for hardware support | +| **non-free-firmware** | Firmware blobs (Wi-Fi, Bluetooth, etc.) | Wireless adapters, embedded chips | **Critical from Debian 12+** | + +#### Why `non-free-firmware` is Vital (Debian 12+) + +Starting with Debian Bookworm (12.0), the `non-free-firmware` component was separated into its own repository branch: + +```bash +# Before Debian 12 (Bookworm) +deb https://deb.debian.org/debian bookworm main contrib non-free + +# After Debian 12 (Bookworm+) - SEPARATE COMPONENTS +deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmware +``` + +**Impact of Missing `non-free-firmware`:** +- ❌ Wi-Fi adapters won't work without firmware blobs +- ❌ Bluetooth devices may fail to initialize +- ❌ Some GPU drivers require proprietary microcode +- ❌ Embedded hardware (Raspberry Pi, etc.) becomes unusable + +The script ensures all four components are present because: +1. **Hardware Compatibility**: Modern Debian kernels depend on these for out-of-the-box functionality +2. **Security Updates**: `non-free-firmware` receives security patches separately +3. **Future-Proofing**: Newer hardware releases firmware in this component exclusively + +--- + +### 5. Support for Debian Backports + +The backports integration is a sophisticated feature that enables access to newer, tested packages without compromising system stability: + +#### Detection Logic (`detect_backports_status` & `detect_backports_location`) + +```bash +# Checks ALL possible locations for backports configuration +├── /etc/apt/sources.list.d/debian-backports.sources (DEB822 standalone) +├── /etc/apt/sources.list.d/debian-backports.list (Classic standalone) +├── /etc/apt/sources.list.d/debian.sources (Embedded in DEB822) +└── /etc/apt/sources.list (Embedded in Classic) +``` + +**Return Values:** +- `"standalone-deb822"` → Separate `.sources` file (recommended) +- `"standalone-classic"` → Separate `.list` file +- `"embedded-deb822"` → Inside `debian.sources` +- `"embedded-classic"` → Inside `sources.list` +- `"none"` → Not configured + +#### Backports Injection Process + +```bash +┌─────────────────────────────────────────────────────────────┐ +│ 1. User Selects: Enable Backports? │ +│ └── whiptail confirm with explanation │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 2. Determine Format │ +│ ├── If DEB822 → _write_deb822_backports() │ +│ └── If Classic → _write_classic_backports() │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 3. Create Backports File │ +│ ├── Location: /etc/apt/sources.list.d/ │ +│ └── Name: debian-backports.sources or .list │ +│ │ +│ Content Example (DEB822): │ +│ Types: deb │ +│ URIs: https://deb.debian.org/debian │ +│ Suites: bookworm-backports │ +│ Components: main contrib non-free non-free-firmware │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 4. Cleanup Embedded Backports (Safety Net) │ +│ └── If backports existed in main file, remove them │ +└─────────────────────────────────────────────────────────────┘ +``` + +#### Why Enable Backports? + +The script includes a detailed explanation because backports enable critical features: + +| Feature | Without Backports | With Backports | +|---------|-------------------|----------------| +| **Linux Kernel** | Stable kernel only (e.g., 5.10) | Newer kernels (e.g., 6.x series) | +| **GPU "Drivers"** | Latest Mesa from stable | Latest Mesa from testing | +| **Wi-Fi Firmware** | Older firmware versions | Newest firmware for modern cards | +| **System Stability** | Maximum stability | Tested-but-newer packages | + +#### Backports Warning System + +The script includes safeguards: +- Only enabled if user explicitly confirms +- Warns about potential compatibility issues +- Can be disabled anytime via Option 3 again +- Automatically detected in other modules (kernel, GPU) + +--- + +### Technical Implementation Notes + +**Idempotency Guarantee:** +```bash +# content_differs() ensures no duplicate writes +if [ "$current" = "$generated" ]; then + return 1 # No changes needed +fi +return 0 # Changes required +``` + +**Atomic Backup Mechanism:** +```bash +backup_current_repos() { + REPO_BACKUP_DIR=$(mktemp -d) + for f in /etc/apt/sources.list /etc/apt/sources.list.d/*.sources; do + cp "$f" "$REPO_BACKUP_DIR/" 2>/dev/null || true + done +} + +# Rollback on failure: +restore_previous_repos() { + sudo cp "$backup_file" "$original_path" # Restore from temp backup + rm -rf "$REPO_BACKUP_DIR" # Clean up after success/failure +} +``` + +**Component Activation Pattern:** +All four components are written in a single operation to prevent partial configurations: +```bash +Components: main contrib non-free non-free-firmware # Atomic write +# Not written as separate lines to avoid merge conflicts +``` + +--- diff --git a/docs/retroarch.md b/docs/retroarch.md new file mode 100644 index 0000000..e50a233 --- /dev/null +++ b/docs/retroarch.md @@ -0,0 +1,163 @@ +# Installing New Cores in RetroArch on Debian + +RetroArch installed via the official Debian repositories (`apt`) has a few key restrictions: the internal core downloader and updater are **disabled** by default, and cores are stored in system‑wide, read‑only directories. This guide explains two reliable ways to add new emulation cores (e.g., PPSSPP, Dolphin, MAME) to your Debian system, along with the necessary supporting files and configuration tweaks. + +--- + +## Understanding RetroArch’s Directory Structure on Debian + +When installed via `apt`, RetroArch uses these locations: + +| **Component** | **Default Path** (system‑wide) | +|-----------------------------|---------------------------------------------------------| +| Cores (`.so` files) | `/usr/lib/x86_64-linux-gnu/libretro/` | +| Core info (`.info` files) | `/usr/share/libretro/info/` | +| System/BIOS/Assets | `~/.config/retroarch/system/` (user‑writable) | +| Saves, States, Config | `~/.config/retroarch/` (user‑writable) | + +Because the core and info directories are owned by root, you cannot write to them without `sudo`. +You have two options: + +1. **Manual installation** – download cores and info files yourself and copy them with `sudo`. +2. **Reconfigure RetroArch** to use user‑writable folders, then use the built‑in **Core Downloader**. + +Both methods work; choose the one that suits you best. + +--- + +## Method 1 – Manual Core Installation (Recommended for Reliability) + +This method guarantees that you can add any core, even if the online updater is blocked. + +### 1. Download and Install the Core (`.so`) + +The core is a shared library. For 64‑bit Linux, get it from the official Libretro buildbot: + +```bash +# Example: PPSSPP core +wget https://buildbot.libretro.com/nightly/linux/x86_64/latest/ppsspp_libretro.so.zip +unzip ppsspp_libretro.so.zip +sudo mv ppsspp_libretro.so /usr/lib/x86_64-linux-gnu/libretro/ +rm ppsspp_libretro.so.zip +``` + +> **Replace `ppsspp` with any core name** – e.g., `mame_libretro`, `dolphin_libretro`, etc. +> Browse all available cores at: +> [https://buildbot.libretro.com/nightly/linux/x86_64/latest/](https://buildbot.libretro.com/nightly/linux/x86_64/latest/) + +### 2. Download and Install the Core Info (`.info`) + +RetroArch will not recognise the core without its corresponding `.info` file. + +```bash +wget https://raw.githubusercontent.com/libretro/libretro-core-info/master/ppsspp_libretro.info +sudo mkdir -p /usr/share/libretro/info/ +sudo mv ppsspp_libretro.info /usr/share/libretro/info/ +``` + +> The `.info` files for all cores are maintained at: +> [https://github.com/libretro/libretro-core-info](https://github.com/libretro/libretro-core-info) +> You can also download directly: `https://raw.githubusercontent.com/libretro/libretro-core-info/master/.info` + +--- + +## Method 2 – Enable the Built‑in Core Downloader + +If you prefer using RetroArch’s graphical interface to download cores, you can change the core directories to writable locations. + +### Step 1 – Edit RetroArch Configuration + +Create or edit `~/.config/retroarch/retroarch.cfg` and add these lines: + +``` +libretro_directory = "~/.config/retroarch/libretro/" +libretro_info_path = "~/.config/retroarch/libretro-info/" +menu_show_core_updater = "true" +``` + +Now create the directories: + +```bash +mkdir -p ~/.config/retroarch/libretro +mkdir -p ~/.config/retroarch/libretro-info +``` + +### Step 2 – Update Core Info Files + +- Launch RetroArch. +- Go to **Online Updater** → **Update Core Info Files**. +- Wait for the update to complete. + +### Step 3 – Download Cores + +- Go to **Online Updater** → **Core Downloader**. +- Select the core you want (e.g., PPSSPP). +- The core will be downloaded to your user directory and will appear in the core list. + +> ⚠️ **Note:** Some cores may require additional system files (BIOS/assets). These are still placed in `~/.config/retroarch/system/` – you’ll need to obtain them separately (see below). + +--- + +## Essential Configuration for Graphics + +The default video driver (`gl`) often causes black screens or crashes with many cores (especially PPSSPP). **Change the driver** to `vulkan` (preferred) or `glcore`. + +1. In RetroArch, go to **Settings** → **Drivers** → **Video**. +2. Select **vulkan** (or **glcore** if Vulkan is not available). +3. Return to the main menu, go to **Configuration File** → **Save Current Configuration**. +4. **Restart RetroArch** for the change to take effect. + +> If you’re on older hardware, you may need to install Vulkan drivers: +> `sudo apt install mesa-vulkan-drivers` + +--- + +## Installing Additional System Files (Assets / BIOS) + +Some emulators require extra files (fonts, sound banks, BIOS images) to work correctly. These always go into your **user** system directory: + +``` +~/.config/retroarch/system/ +``` + +For **PPSSPP**, you need its asset bundle: + +```bash +mkdir -p ~/.config/retroarch/system/PPSSPP +wget https://buildbot.libretro.com/assets/system/PPSSPP.zip +unzip PPSSPP.zip -d ~/.config/retroarch/system/ +``` + +After extraction, you should see subfolders like `flash0/`, `lang/`, `themes/`, etc. + +For other systems (e.g., **Dolphin**, **PCSX2**), check the official Libretro documentation for required BIOS files and place them in the appropriate subdirectory under `system/`. +You can find many asset packs at: +[https://buildbot.libretro.com/assets/system/](https://buildbot.libretro.com/assets/system/) + +--- + +## ROM / Game File Formats + +- **Supported formats** for PPSSPP: `.iso`, `.cso`, `.chd`, `.pbp`. +- **Always decompress your ROMs** – do not leave them in `.zip`, `.rar`, or `.7z` archives; the cores cannot read compressed archives directly. + +--- + +## Useful References + +| Resource | URL | +|----------|-----| +| Core builds (nightly, Linux x86_64) | [https://buildbot.libretro.com/nightly/linux/x86_64/latest/](https://buildbot.libretro.com/nightly/linux/x86_64/latest/) | +| Core info files (GitHub) | [https://github.com/libretro/libretro-core-info](https://github.com/libretro/libretro-core-info) | +| System assets (BIOS, firmware, etc.) | [https://buildbot.libretro.com/assets/system/](https://buildbot.libretro.com/assets/system/) | +| Official RetroArch documentation | [https://docs.libretro.com/](https://docs.libretro.com/) | +| Debian Wiki – RetroArch | [https://wiki.debian.org/RetroArch](https://wiki.debian.org/RetroArch) | + +--- + +## Final Notes + +- The Debian package disables auto‑updates and the core downloader **by default** – this is intentional for stability. +- Manual installation (Method 1) is the most straightforward and works for **any** core, regardless of distribution restrictions. +- If you choose Method 2, remember that you may still need to manually place BIOS/asset files in `~/.config/retroarch/system/`. +- Always test your video driver setting; `vulkan` is recommended for PPSSPP and other 3D‑heavy cores. diff --git a/docs/system_info.md b/docs/system_info.md new file mode 100644 index 0000000..6e2894d --- /dev/null +++ b/docs/system_info.md @@ -0,0 +1,36 @@ +## Option 1: Hardware Detection & System Information + +### 1. What Does This Component Do? +This component serves as the **System Abstraction Layer** and diagnostic engine of the Debianito script. It is not merely a display utility; it acts as the foundational state initializer that runs prior to the main menu loop (`main_menu`). Its primary function is to perform pre-flight hardware enumeration, OS validation, and environment checks in "cold" mode (before any configuration changes are made). + +By populating global variables such as `DEBIAN_VERSION`, `GPU_TYPE`, `CPU_SUMMARY`, and network interface states, it ensures that the subsequent menu options have access to accurate context. This prevents the user from making blind decisions—for example, attempting to install proprietary drivers on a system without detected hardware or selecting repositories incompatible with the current Debian codename. It transforms raw kernel data into actionable configuration parameters. + +### 2. System Commands Used (Technical Mapping) +The following table details the native Linux tools and file descriptors utilized by `utils.sh` to extract specific diagnostic data points. This mapping demonstrates reliance on standard, non-intrusive system utilities rather than proprietary binaries. + +| Feature | Command / Tool | Technical Purpose & Logic | +| :--- | :--- | :--- | +| **OS Version** | `lsb_release -cs`, `/etc/os-release` | Parses `VERSION_CODENAME` to determine Debian release (Bullseye, Bookworm, Trixie). Critical for selecting correct repository backports. | +| **CPU Info** | `/proc/cpuinfo` | Reads `model name` and counts cores/threads. Provides cosmetic summary without needing heavy tools like `lscpu`. | +| **Memory** | `/proc/meminfo` | Extracts `MemTotal` to calculate RAM in GB. Used for compatibility warnings with specific software packages. | +| **GPU Detection** | `lspci -nn`, `nvidia-smi` | Identifies VGA/3D controllers via PCI IDs (`10de` for NVIDIA). Checks driver versions via `dpkg` if `nvidia-smi` fails. | +| **Network (Eth)** | `ip -o link show` | Enumerates Ethernet interfaces, state (UP/DOWN), and IP addresses using the `iproute2` suite. | +| **Network (Wi-Fi)** | `iwgetid`, `lspci` | Identifies wireless chipsets via PCI and retrieves SSID/Connection status for network diagnostics. | +| **Storage** | `lsblk -d -o NAME,SIZE,ROTA` | Distinguishes between NVMe (`nvme`), SSD (RoT=0), and HDD (RoT=1) to provide storage topology summary. | +| **Display Server**| Environment Vars (`XDG_SESSION_TYPE`) | Checks `WAYLAND_DISPLAY` vs `DISPLAY` variables to determine if the system is running Wayland, X11, or TTY. | + +### 3. Strategic Importance for the Script +This diagnostic phase is vital for engineering stability and user experience (UX) integrity within the script architecture: + +* **Context-Aware Configuration:** The detection of `HAS_NVIDIA`, `HAS_AMD`, or `HAS_INTEL` directly dictates which sub-modules are loaded in `debianito.sh`. If no GPU is detected, graphics driver menus are skipped. This prevents "false positive" installation prompts that confuse the user. +* **Repository Compatibility Guardrails:** The `detect_debian_version` function validates the OS against supported codenames (11, 12, 13). It specifically triggers Bullseye-specific logic (`configure_repos_bullseye`) only when necessary, preventing repository errors on newer or older distributions. +* **Time Synchronization Safety:** The `check_system_time` function prevents package installation failures caused by clock skew (which breaks GPG signatures in APT). By offering an automated NTP sync before proceeding, it ensures the integrity of the entire software supply chain within the script. +* **Root/Sudo Enforcement:** Early execution of `check_root` and `check_sudo` enforces security best practices. It prevents accidental privilege escalation or silent failures that often occur when scripts run with incorrect permissions. + +### 4. Formatting and UX in the Terminal +The raw data collected by these functions is processed into a human-readable format before being passed to the TUI (Text User Interface) via `whiptail`. + +* **Structured String Assembly:** Functions like `_show_sysinfo` build multi-line strings (`msg+="...")`, appending newlines and conditional logic. This ensures that if multiple GPUs are found, they are listed sequentially with drivers identified below each entry. +* **Visual Hierarchy:** The data is organized into logical blocks (OS, Hardware, GPU, Network) with clear separators (`───`). This allows the user to quickly scan specific subsystems without scrolling through a monolithic log. +* **Conditional Rendering:** The script checks for command availability (e.g., `if ! command -v ip &>/dev/null`) before attempting to parse network data. If tools are missing, it gracefully degrades to a warning message rather than crashing the TUI. +* **TUI Integration:** The final formatted string is passed to `_msg`, which wraps the output in a `whiptail --msgbox`. This ensures the diagnostic information appears as a modal dialog with consistent dimensions and styling (colors defined globally in `debianito.sh`), maintaining a professional look regardless of the underlying terminal emulator. diff --git a/docs/user_priv_feed.md b/docs/user_priv_feed.md new file mode 100644 index 0000000..93e25de --- /dev/null +++ b/docs/user_priv_feed.md @@ -0,0 +1,80 @@ +## Option 2: User Privileges & Feedback + +### 1. What does this component do? +This component serves as a centralized utility suite designed to streamline administrative access, enhance usability during system maintenance, and correct common permission inconsistencies found in fresh Debian installations or environments where `sudo` usage has been mishandled. It acts as an automated "First-Time User" setup tool that bridges the gap between strict Linux security policies (where standard users cannot modify system files) and practical daily workflow needs (such as installing software without constant password prompts). + +At a high level, it manages four critical aspects of user privilege: +1. **Elevated Permissions:** Ensures the current user has membership in the `sudo` group. +2. **Workflow Efficiency:** Configures specific commands to run without authentication (NOPASSWD) for maintenance tasks. +3. **Data Integrity:** Repairs ownership issues on the home directory caused by accidental root-level file creation. +4. **User Experience:** Modifies terminal behavior during password entry to provide visual feedback. + +### 2. What exactly does it do and why +The script executes a sub-menu loop that allows the user to toggle between four distinct configurations. Each option addresses a specific pain point in Linux administration: + +* **Sudo Group Membership (Option 1):** + * **Action:** Checks if the current username exists within the `/etc/group` file under the `sudo` group entry. If absent, it adds the user via `usermod -aG sudo`. + * **Why:** By default, Debian creates a standard user without administrative rights to prevent accidental system damage. This ensures the user can execute privileged commands (`sudo`) immediately after installation or recovery. + +* **Passwordless Sudo (Option 2):** + * **Action:** Creates an isolated configuration file in `/etc/sudoers.d/` containing `NOPASSWD` rules for specific binaries (e.g., `/usr/bin/apt`, `/sbin/reboot`). It enforces strict path matching to prevent privilege escalation risks. + * **Why:** Frequent password prompts interrupt workflows during updates or system reboots. This allows automation and quick access for maintenance tasks without compromising security on other commands. + +* **Repair Home Directory Ownership (Option 3):** + * **Action:** Scans the user's home directory (`/home/$USER`) to verify if files are owned by `root` (UID 0) instead of the user. If a mismatch is found, it recursively resets ownership via `chown -R`. + * **Why:** Misconfigured file permissions often occur when users attempt to fix issues using root privileges directly in their home folders. This restores data integrity so applications can read/write their own configuration files without permission errors. + +* **Sudo Password Feedback (Option 4):** + * **Action:** Toggles the `Defaults pwfeedback` directive within a dedicated sudoers file. When enabled, typing a password displays asterisks (`****`) instead of being hidden. + * **Why:** Linux terminals hide input by default to prevent shoulder surfing. This option improves usability for users who need visual confirmation that their keystrokes are registering correctly, reducing the risk of typos in complex passwords. + +### 3. The Logical Decision Tree (Step-by-Step) +The execution flow is governed by `sudo_config.sh`, which acts as a state machine within the main menu loop. Below is the chronological logic for each option: + +**Entry Point:** +1. The script enters the `config_sudo()` function and loops until the user selects "Back to main menu". +2. It presents a Whiptail menu with options 1–5. + +**Option 1: Sudo Group Membership (`_check_sudo_group`)** +* **Step A:** Execute `groups "$USER"` via pipe to grep for `\bsudo\b`. +* **Decision:** + * *If Match:* Display success message ("User is already in sudo group"). Exit function. + * *If No Match:* Prompt user with a confirmation dialog asking if they want to add the user to the `sudo` group. + * *On Confirm:* Execute `sudo usermod -aG sudo "$USER"`. If successful, display message instructing logout/login for changes to take effect. If failure, log error and return status 1. + +**Option 2: Passwordless Sudo (`_configure_nopasswd`)** +* **Step A:** Check if `/etc/sudoers.d/${USER}-nopasswd` exists. + * *If Exists:* Prompt to remove the configuration (restore password prompts). If confirmed, delete file and notify success. Return function. + * *If Not Exists:* Prompt user to configure NOPASSWD for maintenance commands. + * *On Confirm:* Display a checklist menu allowing selection of `apt`, `systemctl`, or `power` commands. +* **Step B:** Process selected commands: + * Construct the content string based on selections, explicitly defining paths (e.g., `/usr/bin/apt`, `/sbin/shutdown`) to ensure compatibility across Debian versions. +* **Step C:** Write configuration: + * Pipe content to `sudo tee /etc/sudoers.d/${USER}-nopasswd`. + * Set file permissions to `0440` (readable only by root and owner). + * Notify success or failure. + +**Option 3: Repair Home Directory Ownership (`_repair_home_ownership`)** +* **Step A:** Resolve the absolute path of `$HOME`. If directory does not exist, notify error and return status 1. +* **Step B:** Retrieve User ID (UID) using `id -u "$USER"`. +* **Step C:** Check current owner UID of `$HOME` using `stat -c '%u'`. + * *If Match:* Notify that ownership is correct and exit. + * *If Mismatch:* Identify the expected username for the conflicting UID. Prompt user to confirm repair. + * *On Confirm:* Execute `sudo chown -R "$USER:$USER" "$home"`. If successful, notify success. If failure, log error and return status 1. + +**Option 4: Sudo Password Feedback (`_toggle_pwfeedback`)** +* **Step A:** Check if `/etc/sudoers.d/pwfeedback` exists. + * *If Exists:* Prompt to disable asterisks (restore hidden input). If confirmed, delete file and notify success. Return function. + * *If Not Exists:* Prompt user to enable visual feedback. + * *On Confirm:* Write `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback`. +* **Step B:** Verify write permission. If successful, notify success; otherwise, log error and return status 1. + +### 4. Compatibility with all Debian +This module is designed for universal compatibility across the Debian family (Bullseye, Bookworm, Trixie, etc.) due to its reliance on standard POSIX-compliant tools and strict path handling. + +* **Architecture Independence:** The script utilizes `usermod`, `chown`, and `grep` which are available on all x86_64, arm64, and i386 Debian architectures. +* **Version Agnosticism (Debian 11+):** + * **Sudoers Syntax:** The script writes to `/etc/sudoers.d/`, a directory introduced in `sudo` version 1.9.0p5 (available since Debian 7). It avoids editing the master file (`/etc/sudoers`) directly, preventing lockfile issues and syntax errors regardless of the specific Debian version's sudo configuration style. + * **Path Hardening:** The NOPASSWD logic explicitly includes both `/usr/bin` and `/bin` paths for commands like `apt`. This ensures that on older Debian versions (e.g., Bullseye) where binaries might reside in different locations or symlinks differ, the permissions remain valid. +* **Security Best Practices:** By isolating configurations into separate files (`/etc/sudoers.d/`) and setting restrictive permissions (`0440`), it adheres to Debian's security guidelines for `sudo`. This ensures that even on older systems with stricter default policies, the configuration is accepted without requiring a full system reboot or sudo upgrade. +* **Importance:** Consistent behavior across versions means users can migrate between Debian releases (e.g., from 11 to 12) without needing to manually reconfigure these specific privileges, ensuring a stable and secure environment regardless of the underlying OS version. diff --git a/docs/zram.md b/docs/zram.md new file mode 100644 index 0000000..76be697 --- /dev/null +++ b/docs/zram.md @@ -0,0 +1,243 @@ +# Option 8: ZRAM Configuration & Memory Optimization + +## 1. The Science of ZRAM vs. Traditional Swap + +### Core Concept: CPU Cycles vs. Disk I/O + +Traditional swap storage operates on a fundamental latency gap that becomes critical under memory pressure: + +| Storage Medium | Latency Range | Write Amplification | SSD Wear Impact | +|---------------|---------------|---------------------|-----------------| +| **DRAM (RAM)** | ~10–50 nanoseconds | None | Zero | +| **NVMe SSD** | ~20–70 microseconds | 1.2x–3.0x | Moderate to High | +| **SATA SSD** | ~100–200 microseconds | 1.5x–4.0x | High | +| **HDD** | ~5–10 milliseconds | N/A (mechanical) | Irrelevant | + +When a Linux system experiences memory pressure, the kernel must decide what to swap out. Traditional swap writes pages directly to disk storage: + +- **Time Cost**: Each 4 KiB page write takes microseconds (NVMe) to milliseconds (HDD) +- **Wear Cost**: Every write consumes P/E (Program/Erase) cycles from NAND flash cells, reducing TBW (Terabytes Written) lifespan +- **System Impact**: High latency causes "thrashing" where the system spends more time waiting for disk I/O than executing actual work + +### ZRAM's Solution: Compression in RAM + +ZRAM creates a compressed block device entirely within physical memory. When pages need to be swapped, they are: + +1. **Compressed on-the-fly** using CPU algorithms (LZ4 or ZSTD) +2. **Stored in RAM pool** at compressed size (typically 2:1 to 3:1 ratio) +3. **Decompressed instantly** when needed (microseconds vs milliseconds) + +The trade-off is explicit: **CPU cycles for reduced I/O latency**. Modern CPUs can compress/decompress pages in microseconds, making this far cheaper than any disk operation. + +### Why Only LZ4 and ZSTD? + +The script offers only two algorithms because they represent the optimal balance points: + +| Algorithm | Compression Ratio | Speed | CPU Overhead | Best Use Case | +|-----------|------------------|-------|--------------|---------------| +| **LZ4** | ~2:1–3:1 | Fastest | Lowest | Gaming, real-time workloads | +| **ZSTD** | ~3:1–5:1 | Medium | Moderate | General use, better memory savings | + +- **LZ4**: Prioritizes speed over compression ratio. Ideal for systems where CPU availability is limited or latency-sensitive (gaming servers). +- **ZSTD**: Offers superior compression ratios with acceptable overhead. Best for systems prioritizing maximum effective RAM capacity. + +The kernel supports additional algorithms (lzo-rle, deflate, lz4hc), but these are either deprecated, slower, or offer diminishing returns compared to LZ4/ZSTD in modern hardware. + +### Extending SSD Lifespan Through Reduced Writes + +By intercepting swap writes before they reach physical storage: + +- **Write Reduction**: Pages that would write to disk now compress in RAM +- **TBW Conservation**: Each avoided write preserves P/E cycles on NAND flash cells +- **System Longevity**: Critical for systems with limited SSD endurance ratings (e.g., 100 TBW consumer drives) + +As the Linux kernel documentation states: *"Users with SSDs as swap devices can extend device lifespan by drastically reducing writes that shorten its life."* + +--- + +## 2. Injection Flow and Configuration Logic (`zram-tools`) + +### Pipeline Execution Sequence + +The script follows a deterministic flow to ensure safe, reproducible configuration: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ install_zram() Function │ +├─────────────────────────────────────────────────────────────┤ +│ 1. Validate RAM Detection │ +│ └─ Check if RAM_KB is available and non-zero │ +│ │ +│ 2. Compression Algorithm Selection │ +│ ├─ Present menu: LZ4 (fast) vs ZSTD (better ratio) │ +│ └─ User choice stored in $algo variable │ +│ │ +│ 3. Size Calculation Logic │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ half_ram_mb = ((RAM_KB / 1024 / 1024 + 1) │ │ +│ │ / 2) * 1024 │ │ +│ └──────────────────────────────────────────────┘ │ +│ └─ Result: ~50% of total physical RAM in MB │ +│ │ +│ 4. Configuration Confirmation │ +│ ├─ Display summary with algorithm, size, priority=100 │ +│ └─ User must confirm before applying │ +│ │ +│ 5. Package Installation │ +│ sudo apt install -y zram-tools │ +│ │ +│ 6. Configuration File Write │ +│ /etc/default/zramswap │ +│ ALGO=$algo │ +│ SIZE=$zram_size │ +│ PRIORITY=100 │ +│ │ +│ 7. Service Restart │ +│ sudo systemctl restart zramswap │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Mathematical Size Calculation + +The script uses this formula to determine ZRAM size: + +```bash +half_ram_mb=$(( ((RAM_KB / 1024 / 1024 + 1) / 2) * 1024 )) +``` + +**Breakdown:** +- `RAM_KB`: Total RAM in kilobytes from `/proc/meminfo` +- `/ 1024 / 1024`: Convert KB to MB +- `+ 1`: Add rounding buffer for odd values +- `/ 2`: Target approximately 50% of total RAM +- `* 1024`: Round back to nearest MB + +**Example:** +``` +System with 8 GB (8388608 KB) RAM: +half_ram_mb = ((8388608 / 1024 / 1024 + 1) / 2) * 1024 + = ((8 + 1) / 2) * 1024 + = (9 / 2) * 1024 + = 4.5 * 1024 + = 4608 MB (~4.5 GB) +``` + +### Priority Configuration (`PRIORITY=100`) + +The `swapon` priority determines which swap device the kernel prefers when multiple devices exist: + +- **Higher number** = Higher preference (used first by kernel) +- **Default system swap**: Typically 0–60 +- **ZRAM with PRIORITY=100**: Ensures ZRAM is used before physical disk swap + +This prevents thrashing where pages bounce between slow disk swap and fast RAM-based ZRAM. + +--- + +## 3. Kernel Parameter Tuning (`sysctl`) + +### Essential VM Parameters for Aggressive ZRAM Usage + +While the current script focuses on `zram-tools` configuration, optimal performance requires complementary kernel parameter tuning: + +```bash +# Recommended sysctl configuration for ZRAM systems +vm.swappiness = 180 +vm.watermark_boost_factor = 0 +vm.watermark_scale_factor = 125 +vm.page-cluster = 0 +``` + +### Parameter Explanations + +| Parameter | Value | Purpose | +|-----------|-------|---------| +| **`vm.swappiness`** | `180–200` | Aggressively prefer swap over keeping pages in RAM. Higher values (up to 200) are ideal for ZRAM because it's faster than disk swap. Default 60 is too conservative for memory-constrained systems. | +| **`vm.watermark_boost_factor`** | `0` | Disable additional watermark boosting that could cause premature page reclaim | +| **`vm.watermark_scale_factor`** | `125` | Adjust low-memory watermark thresholds to trigger swap earlier when RAM is constrained | +| **`vm.page-cluster`** | `0` | Disable page clustering. Research shows this reduces unnecessary sequential reads during swap operations, improving ZRAM efficiency by ~15% in gaming workloads | + +### Why High Swappiness for ZRAM? + +Traditional wisdom suggests keeping swappiness low (20–40) to avoid swapping frequently. However: + +- **ZRAM is faster than disk**: Microseconds vs milliseconds +- **Thrashing prevention**: Higher swappiness moves pages to ZRAM before they hit slow disk swap +- **Effective RAM expansion**: Compressed pages in ZRAM can store 2–3x more data, effectively increasing available memory + +The Pop!_OS project and Linux kernel documentation both recommend values beyond 100 for in-memory swap scenarios like ZRAM/ZSWAP. + +--- + +## 4. Service Lifecycle and Validation + +### Safe Service Initialization + +```bash +sudo systemctl restart zramswap +``` + +**Why `restart` instead of `start`:** +- Ensures previous configuration is cleanly terminated +- Prevents orphaned processes from conflicting with new settings +- Reloads systemd unit files if they were modified during installation + +### User Verification Commands + +#### Primary: `zramctl` (util-linux) + +```bash +sudo zramctl +``` + +**Output Interpretation:** +``` +NAME ALGORITHM DISKSIZE DATA COMPR TOTAL STREAMS MOUNTPOINT +/dev/zram0 lz4 4G 2.1G 318.6M 424.9M [SWAP] +``` + +| Column | Meaning | +|--------|---------| +| **NAME** | Device identifier (/dev/zram0) | +| **ALGORITHM** | Active compression algorithm (lz4, zstd, etc.) | +| **DISKSIZE** | Maximum uncompressed data capacity configured | +| **DATA** | Currently stored uncompressed pages in ZRAM | +| **COMPR** | Actual compressed size using physical RAM | +| **TOTAL** | Total memory used including metadata overhead | +| **STREAMS** | Number of active swap streams (typically 4) | + +#### Secondary: `swapon --show` + +```bash +sudo swapon --show +``` + +Shows all active swap devices with priority levels. ZRAM should appear with priority matching the configured value (100 in this script). + +### Real-Time Monitoring + +For continuous monitoring of compression effectiveness: + +```bash +# Watch compression ratio changes over time +watch -n 5 'zramctl | grep /dev/zram' + +# Monitor memory pressure and swap usage +watch -n 5 'free -h && zramctl' +``` + +### Troubleshooting Indicators + +| Symptom | Likely Cause | Solution | +|---------|--------------|----------| +| `DATA` equals `DISKSIZE` but `COMPR` is near zero | System under memory pressure, ZRAM not being used | Increase `vm.swappiness` or check if physical swap has lower priority | +| High CPU usage with low compression ratio | Incompressible data (e.g., encrypted files) | Consider backing device for incompressible pages | +| Service fails to start | Missing dependencies (`zram-tools`, kernel module) | Run `sudo apt install zram-tools` and verify `modprobe zram` | + +### Permanent Configuration + +To ensure ZRAM persists across reboots, the script writes configuration to `/etc/default/zramswap`. This file is read by systemd's `zramswap.service` unit at boot time. Additionally, adding the following ensures the kernel module loads: + +```bash +echo "zram" | sudo tee /etc/modules-load.d/zram.conf +``` diff --git a/modules/extras/internet/internet.sh b/modules/extras/internet/internet.sh index 56c16f6..d3dde37 100644 --- a/modules/extras/internet/internet.sh +++ b/modules/extras/internet/internet.sh @@ -32,12 +32,42 @@ _enable_floorp_repo() { _run_cmd "APT Update" "sudo apt update" "Updating package lists..." } -_enable_palemoon_repo() { - if [ ! -f /etc/apt/sources.list.d/extrepo_palemoon.sources ]; then - _ensure_extrepo - _run_cmd "Pale Moon" "sudo extrepo enable palemoon" "Enabling Pale Moon repository..." +install_palemoon() { + if [ "$DEBIAN_VERSION" -lt 12 ] 2>/dev/null; then + _msg "Pale Moon" "Pale Moon is only available on\nDebian 12 (Bookworm) and 13 (Trixie).\n\nSkipping installation." 10 60 + return 1 + fi + + local cpu_flags cpu_label REPO_PALEMOON + cpu_flags=$(grep -m1 '^flags' /proc/cpuinfo 2>/dev/null) + + if echo "$cpu_flags" | grep -q 'avx2'; then + REPO_PALEMOON="palemoon_avx2_gtk3" + cpu_label="AVX2" + elif echo "$cpu_flags" | grep -q 'avx'; then + REPO_PALEMOON="palemoon_avx_gtk3" + cpu_label="AVX" + else + REPO_PALEMOON="palemoon_sse2_gtk3" + cpu_label="SSE2" + fi + + _msg "Pale Moon" "CPU detected: ${cpu_label} support.\n\nEnabling optimized repository:\n ${REPO_PALEMOON}" 10 60 + + if ls /etc/apt/sources.list.d/extrepo_palemoon_*.sources &>/dev/null; then + echo "Pale Moon repository already enabled." + else + _ensure_extrepo + _run_cmd "Pale Moon" "sudo extrepo enable ${REPO_PALEMOON}" "Enabling ${REPO_PALEMOON}..." + _run_cmd "APT Update" "sudo apt update" "Updating package lists..." + fi + + if ! is_installed "palemoon"; then + _run_cmd "Pale Moon" "sudo apt install -y palemoon" "Installing Pale Moon..." + echo -e "${GREEN}Pale Moon installed.${NC}" + else + echo "Pale Moon already installed." fi - _run_cmd "APT Update" "sudo apt update" "Updating package lists..." } _enable_librewolf_repo() { @@ -64,12 +94,22 @@ _enable_mullvad_repo() { _run_cmd "APT Update" "sudo apt update" "Updating package lists..." } -_enable_protonvpn_repo() { +install_protonvpn() { if [ ! -f /etc/apt/sources.list.d/extrepo_protonvpn.sources ]; then _ensure_extrepo - _run_cmd "ProtonVPN" "sudo extrepo enable protonvpn" "Enabling ProtonVPN repository..." + _run_cmd "ProtonVPN" "sudo extrepo enable protonvpn stable" "Enabling ProtonVPN repository (stable suite)..." + _run_cmd "APT Update" "sudo apt update" "Updating package lists..." + else + echo "ProtonVPN repository already enabled." + fi + + if ! is_installed "proton-vpn-gtk-app"; then + _msg "ProtonVPN" "Installing Proton VPN GTK client\nfrom the official Proton repository." 10 60 + _run_cmd "ProtonVPN" "sudo apt install -y proton-vpn-gtk-app" "Installing Proton VPN GTK app..." + echo -e "${GREEN}ProtonVPN installed.${NC}" + else + echo "Proton VPN GTK app already installed." fi - _run_cmd "APT Update" "sudo apt update" "Updating package lists..." } # ── Categories ── @@ -146,9 +186,7 @@ _cat_internet() { echo -e "${GREEN}LibreWolf installed.${NC}" ;; palemoon) - _enable_palemoon_repo - _run_install palemoon - echo -e "${GREEN}Pale Moon installed.${NC}" + install_palemoon ;; tailscale) _enable_tailscale_repo @@ -166,9 +204,7 @@ _cat_internet() { echo -e "${GREEN}Mullvad Browser installed.${NC}" ;; protonvpn) - _enable_protonvpn_repo - _run_install protonvpn - echo -e "${GREEN}ProtonVPN installed.${NC}" + install_protonvpn ;; riseup-vpn) install_backports_or_stable riseup-vpn diff --git a/modules/extras/java.sh b/modules/extras/java.sh index 4343e6e..d114794 100644 --- a/modules/extras/java.sh +++ b/modules/extras/java.sh @@ -13,17 +13,18 @@ _enable_temurin_repo() { _run_cmd "APT Update" "sudo apt update" "Updating package lists..." } -_install_gaming_java() { +install_minecraft_java() { local ver - ver=$(whiptail --title "Java Runtimes for Gaming" --menu \ + ver=$(whiptail --title "Java Runtimes for Minecraft" --menu \ "Select Java version:" 12 65 3 \ - "8" "Java 8 — For classic mods & Minecraft <= 1.16.5" \ - "17" "Java 17 — For Minecraft era 1.17 to 1.20.4" \ - "21" "Java 21 — For modern Minecraft >= 1.20.5 & 1.21+" \ + "8" "Java 8 — Classic mods & Minecraft <= 1.16.5" \ + "17" "Java 17 — Minecraft 1.17 to 1.20.4" \ + "21" "Java 21 — Modern Minecraft >= 1.20.5 & 1.21+" \ 3>&1 1>&2 2>&3) [ -z "$ver" ] && { echo "No Java version selected."; return; } _enable_temurin_repo - _run_install "temurin-${ver}-jre" + _run_cmd "Java" "sudo apt install -y temurin-${ver}-jre" \ + "Installing Temurin JRE ${ver}..." } _install_dev_java() { diff --git a/modules/extras/office/office.sh b/modules/extras/office/office.sh index 40f6d8a..53b4ad6 100644 --- a/modules/extras/office/office.sh +++ b/modules/extras/office/office.sh @@ -21,7 +21,7 @@ install_onlyoffice() { Repository: download.onlyoffice.com Version: ${ver:-unknown}"; then _enable_onlyoffice_repo - _run_cmd "OnlyOffice" "sudo DEBIAN_FRONTEND=noninteractive apt install -y onlyoffice-desktopeditors" "Installing OnlyOffice..." + _run_cmd "OnlyOffice" "sudo DEBIAN_FRONTEND=noninteractive apt install -y onlyoffice-desktopeditors" "Installing OnlyOffice..." || echo -e "${RED}OnlyOffice servers are currently slow or down. Please try again later.${NC}" echo -e "${GREEN}OnlyOffice installed.${NC}" fi } diff --git a/modules/gaming.sh b/modules/gaming.sh index 957f7d0..d3ac340 100644 --- a/modules/gaming.sh +++ b/modules/gaming.sh @@ -66,8 +66,22 @@ install_gaming() { if [ "$GPU_TYPE" = "nvidia" ]; then case "${NVIDIA_DRIVER_MODE:-stable}" in cuda-repo) - _msg "NVIDIA 32-bit" \ - "32-bit NVIDIA CUDA libraries already deployed.\n\nThe complete multiarch stack was installed\nwith the v590 driver from the official CUDA repo." 10 70 + local nv32_pkg="nvidia-driver-libs:i386" + local nv32_ver + nv32_ver=$(dpkg -l "$nv32_pkg" 2>/dev/null | awk '/^ii/ {print $3}') + if [ -z "$nv32_ver" ] || ! echo "$nv32_ver" | grep -q "^590"; then + local msg="Source: NVIDIA CUDA Repository (Pinned v590)\n" + msg+="NVIDIA 32-bit Libraries (v590 branch)\n\n" + msg+="[+] nvidia-driver-libs:i386" + if _confirm "NVIDIA 32-bit" "$msg" 12 70; then + _run_cmd "32-bit NVIDIA" \ + "sudo apt install -y ${nv32_pkg}" \ + "Installing 32-bit NVIDIA libraries from CUDA repo..." + fi + else + _msg "NVIDIA 32-bit" \ + "32-bit NVIDIA CUDA libraries already deployed.\n\nv590 ${nv32_ver}" 10 70 + fi ;; backports) local nv32_pkg="nvidia-driver-libs:i386" @@ -128,10 +142,11 @@ install_gaming() { "gamemode" "Game performance optimization" ON \ "mangohud" "Performance overlay (Vulkan/OpenGL)" ON \ "heroic" "Heroic Launcher (Epic/GOG)" OFF \ - "java-jre" "Java Runtimes (8, 17, 21)" OFF \ + "java" "Java Runtimes (8, 17, 21)" OFF \ "goverlay" "MangoHud config GUI" ON \ "openrgb" "OpenRGB (RGB lighting control)$(_inst openrgb)" OFF \ "lutris" "Game launcher/manager" OFF \ + "retroarch" "RetroArch Emulator Frontend$(_inst retroarch)" OFF \ 3>&1 1>&2 2>&3) if [ -z "$choices" ]; then @@ -159,7 +174,7 @@ install_gaming() { fi ;; heroic) install_heroic ;; - java) _install_gaming_java ;; + java) install_minecraft_java ;; mangohud) install_mangohud ;; gamemode) install_gamemode ;; goverlay) install_goverlay ;; @@ -171,6 +186,7 @@ install_gaming() { install_openrgb ;; lutris) install_lutris ;; + retroarch) install_retroarch ;; *) _run_install "$pkg" ;; esac done diff --git a/modules/gaming/tools.sh b/modules/gaming/tools.sh index 18bec42..fd533eb 100644 --- a/modules/gaming/tools.sh +++ b/modules/gaming/tools.sh @@ -61,3 +61,30 @@ install_openrgb() { rm -f "${deb_path}" echo -e "${GREEN}OpenRGB installed. NOTE: You must reboot or log out/in for the 'i2c' group to take effect.${NC}" } + +install_retroarch() { + if is_installed "retroarch"; then + echo "RetroArch already installed." + return + fi + + _run_cmd "RetroArch" "sudo apt install -y retroarch libretro-mgba libretro-snes9x libretro-nestopia libretro-gambatte" "Installing RetroArch and classic cores (GBA, SNES, NES, GB)..." + + clear + echo "=================================================================" + echo " 🎮 IMPORTANT RETROARCH NOTICE 🎮" + echo "=================================================================" + echo "Good news! Nintendo (NES/SNES) and Game Boy (GB/GBA) cores" + echo "have been automatically installed and are ready to play!" + echo "" + echo "⚠️ However, due to Debian open-source guidelines:" + echo " - Core auto-updates inside the app are disabled." + echo " - Heavy/arcade cores or those requiring proprietary BIOS" + echo " (like PlayStation or Arcade) must be handled manually." + echo "" + echo "👉 To learn how to unlock the internal Online Downloader:" + echo " Please check our repository's documentation or visit:" + echo " https://wiki.debian.org/RetroArch" + echo "=================================================================" + read -p "Press ENTER to continue..." +} diff --git a/modules/gpu/nvidia.sh b/modules/gpu/nvidia.sh index 4fc663c..434dc22 100644 --- a/modules/gpu/nvidia.sh +++ b/modules/gpu/nvidia.sh @@ -78,21 +78,17 @@ _enable_cuda_repo() { # CASE A: Trixie + Backports Kernel → Official CUDA Repo (Pinned v590) # ------------------------------------------------------------------- _install_nvidia_cuda_repo() { - local i386_active=false - dpkg --print-foreign-architectures | grep -q i386 && i386_active=true - local warn="WARNING: Official Debian NVIDIA driver (v550)\n" warn+="fails to compile on Trixie Backports Kernels.\n\n" - warn+="The script will configure the official NVIDIA CUDA\n" - warn+="repository and force-install the stable production\n" - warn+="branch v590.48.01 on your system.\n\n" + warn+="The script will enable the official NVIDIA CUDA\n" + warn+="repository and install the production branch v590\n" + warn+="using NVIDIA's unified driver pinning packages.\n\n" warn+="Source: Official NVIDIA CUDA Repo (Pinned v590.*)\n" - warn+="Driver: Production Branch 590.48.01 (Kernel 7.0+ Compliant)\n" - warn+="[+] Full 64-bit Core & Compute Stack (DKMS)\n" - if $i386_active; then - warn+="[+] 32-bit Gaming Multiarch Libraries\n" - fi - warn+="[+] APT Pinning + Package Hold will be applied\n\n" + warn+="Driver: Production Branch v590 (unified metapackage)\n" + warn+="[+] nvidia-driver (full 64-bit compute + graphics)\n" + warn+="[+] firmware-nvidia-gsp\n" + warn+="[+] nvidia-driver-pinning-590 (branch locking)\n" + warn+="[+] APT Pinning (version 590.*)\n\n" warn+="Do you want to proceed at your own risk?" if ! _confirm_custom "NVIDIA Driver — Trixie + Backports" "$warn" "Proceed" "Abort" 18 70; then @@ -108,50 +104,10 @@ _install_nvidia_cuda_repo() { 'printf "%s\n" "Package: *nvidia*" "Package: *cuda*" "Package: libcuda1" "Package: firmware-nvidia-gsp" "Pin: version 590.*" "Pin-Priority: 1001" | sudo tee /etc/apt/preferences.d/block-nvidia > /dev/null' \ "Creating APT pinning to lock NVIDIA to v590 branch..." - # Step 3: Build version-locked package list - local pkgs=( - "cuda-drivers=590.48.01-1" - "libcuda1=590.48.01-1" - "nvidia-driver=590.48.01-1" - "nvidia-driver-libs=590.48.01-1" - "firmware-nvidia-gsp=590.48.01-1" - "libegl-nvidia0=590.48.01-1" - "libglx-nvidia0=590.48.01-1" - "libnvidia-eglcore=590.48.01-1" - "libnvidia-glcore=590.48.01-1" - "libnvidia-glvkspirv=590.48.01-1" - "libnvidia-ml1=590.48.01-1" - "nvidia-egl-icd=590.48.01-1" - "nvidia-vulkan-icd=590.48.01-1" - "libnvcuvid1=590.48.01-1" - "libnvidia-encode1=590.48.01-1" - "nvidia-kernel-dkms=590.48.01-1" - "nvidia-settings=590.48.01-1" - "nvidia-smi=590.48.01-1" - ) - - if $i386_active; then - pkgs+=( - "libcuda1:i386=590.48.01-1" - "nvidia-driver-libs:i386=590.48.01-1" - "libegl-nvidia0:i386=590.48.01-1" - "libglx-nvidia0:i386=590.48.01-1" - "libnvidia-eglcore:i386=590.48.01-1" - "libnvidia-glcore:i386=590.48.01-1" - "libnvidia-glvkspirv:i386=590.48.01-1" - "libnvidia-ml1:i386=590.48.01-1" - "nvidia-egl-icd:i386=590.48.01-1" - "nvidia-vulkan-icd:i386=590.48.01-1" - ) - fi - - _run_cmd "NVIDIA CUDA" "sudo apt install -y ${pkgs[*]}" \ - "Installing NVIDIA Production Driver v590.48.01..." - - # Step 4: Hold critical packages - _run_cmd "Package Hold" \ - "sudo apt-mark hold cuda-drivers libcuda1 firmware-nvidia-gsp" \ - "Locking v590 packages to prevent accidental upgrades..." + # Step 3: Install NVIDIA unified metapackages (driver pinning) + _run_cmd "NVIDIA CUDA" \ + "sudo apt install -y nvidia-driver-pinning-590 nvidia-driver firmware-nvidia-gsp" \ + "Installing NVIDIA v590 production driver via unified metapackages..." NVIDIA_DRIVER_MODE="cuda-repo" echo -e "${GREEN}NVIDIA Production Driver v590 installed from CUDA repo. Reboot required.${NC}"