stornic56/debianito-post-install
1
0
Fork 0
mirror of https://github.com/stornic56/debianito-post-install.git synced 2026-10-31 21:18:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: stornic56/debianito-post-install:149fb56e8c7ed41501915ab6769b975225f2d98b
Branches Tags
stornic56/debianito-post-install:main
..
compare: stornic56/debianito-post-install:main
Branches Tags
stornic56/debianito-post-install:main

78 Commits
149fb56e8c .. main

Author SHA1 Message Date
stornic56 923d9ca5bc KDE: add Custom packages option with verified package list 
Mirror the LXDE/XFCE Custom pattern: fixed base
(kde-plasma-desktop + sddm + konsole, plus
plasma-workspace-wayland on bookworm via the existing
gate) and a 17-entry checklist of extras whose names
are identical on bookworm and trixie (verified against
packages.debian.org). konsole is pinned because it is
only a Recommends of kde-baseapps on trixie. Empty
selection returns without installing; base + selection
are confirmed before any debconf or apt transaction.
knotes (gone on trixie) and konqueror/kwrite (legacy)
are excluded.
 2026-10-21 15:29:26 -05:00
stornic56 c94d918757 KDE: add bookworm Wayland gate and release-aware SDDM session probe 
Bookworm's plasma-workspace ships only the X11 session; the Wayland
session (plasmawayland.desktop) lives in the separate
plasma-workspace-wayland package (a Recommends of plasma-desktop, now
listed explicitly for the same determinism as the explicit sddm). The
package does not exist on trixie, where plasma-workspace integrates
Wayland natively, so naming it off-bookworm would fail the apt
transaction: resolve it once per installer with _kde_wayland_pkg() and
build the package list in a conditional array so neither the pre-apply
summary nor the apt command ever shows an empty argument. Also correct
the header comment: bookworm still defaults SDDM to the X11 session,
while trixie makes Wayland primary (plasma.desktop in
wayland-sessions) with plasmax11.desktop as the X11 fallback.

Replace the hard-coded SDDM autologin session cascade with an
existence-based ordered probe (_sddm_session_candidates) that prefers
Wayland across releases, keeps the LXQt sessions last for when the
module starts offering LXQt, and reads its session roots from
SESSION_DIR_WAYLAND / SESSION_DIR_X11 for hermetic testing.

Extend tests/desktops.bats with 13 offline tests: gate helper output on
bookworm/trixie, captured apt commands for both installers, summary
content (no empty package line), and the ordered session probe against
fixture trees.
 2026-10-21 15:29:26 -05:00
stornic56 9a11ab8981 GNOME: use ptyxis instead of gnome-terminal on trixie+ 
gnome-core declares the OR-dependency "gnome-terminal (>= 3.56)
or gnome-console (>= 46) or ptyxis (>= 47)" (packages.debian.org
/trixie/gnome-core, verified 2026-10-16) and apt resolves an
unset OR-dep with the FIRST alternative, so the desktop pull would
install gnome-terminal by default. Listing the terminal package
explicitly in the same apt transaction steers the resolver to
ptyxis (48.5-1~deb13u1, GTK4) on trixie.

- _gnome_terminal_pkg(): trixie -> ptyxis, anything else or
  empty -> gnome-terminal (ptyxis does not exist in bookworm).
- _install_gnome_full/_install_gnome_core list the resolved
  package in the pre-apply summary and in the apt command.
- No purge or apt-mark: an already-installed gnome-terminal is
  left alone and both can coexist.
- 4 new BATS tests capture the apt command via the existing
  sudo/_run_cmd mocks: ptyxis on trixie (Full and Core),
  gnome-terminal fallback on bookworm and on empty codename.
 2026-10-21 15:29:26 -05:00
stornic56 2f11abbd64 LXDE: add Custom packages option and respect existing display manager 
- New 'LXDE Custom (Choose packages)' menu entry: fixed base
  (lxde-core + xserver-xorg, lightdm only when no display manager
  is configured) plus a data-driven checklist of 16 extras.
- lxterminal, polkitd, notification-daemon and light-locker stay out
  of the checklist: they arrive via lxde-core Recommends (verified
  against packages.debian.org/trixie, 2026-10-16).
- Full/Core/Custom now honor an already-configured display manager
  via _existing_display_manager (GNOME/KDE pattern): no debconf
  preseed, no lightdm install, no enable over an existing DM.
- Extract _select_packages_checklist helper to utils.sh; XFCE
  Custom consumes it with no functional change.
 2026-10-21 15:29:18 -05:00
stornic56 2195db452a UI: convert LXDE/GNOME/KDE submenus to _menu style (XFCE parity) 
Replace _radiolist with the _menu pattern used by xfce_menu:
while-true loop, fixed numbered items array, Back option that
breaks the loop, and direct case dispatch to the unchanged
installers. Navigation is now consistent across all four desktop
submenus (select an option, return to the parent menu, re-enter
without re-triggering a one-shot selection).

- bash -n OK, shellcheck 0 warnings, BATS 36/0
- _radiolist helper kept in utils.sh for compatibility (no callers)
 2026-10-20 07:39:35 -05:00
stornic56 07f09d87eb Perf: speed up System Information via cached detection state 
- Network block now renders from ETH_*/WIFI_* arrays cached by
  detect_network() instead of re-running ip/lsusb/iwgetid probes
  (~210 lines removed, half the subprocesses, no repeated timeouts)
- GPU block renders from GPU_DESC/GPU_VERSION cached by detect_gpu()
  instead of re-parsing lspci and re-running nvidia-smi/dpkg
- Extract _lspci_desc() helper (DRY: same sed in 5 places)
- Reduce local probe timeouts (ip -4 -o addr, iwgetid) from 2s to 1s
- bash -n OK, shellcheck 0 warnings, BATS 36/0, cached renders 15-24x faster
 2026-10-14 23:04:06 -05:00
stornic56 9c0f4eafc6 Add GNU General Public License v3 
Added the GNU General Public License version 3 to the project.
 2026-10-14 22:00:01 -05:00
stornic56 f735b54331 Recovered 70 prior commits from Gitea mirror and resolved divergent history using --allow-unrelated-histories. Integrated 16 recent local commits via patch. Applied targeted technical fixes: added explicit bash shell declaration in shellcheck YAML configuration (commit 693caff) and targeted SC2120 disables in modules/utils.sh (commit 3614b56). All verifications passed: shellcheck compliance, bash syntax check (bash -n), and BATS test suite passing cleanly. Symmetrically synchronized repository state across GitHub and Gitea. 2026-10-14 21:55:51 -05:00
stornic56 89233b0750 Desktop environment support & QA expansion 
- `.github/workflows/ci.yml` added as a new workflow: job `lint-and-test` on `runs-on: ubuntu-latest` with `container: debian:trixie`, checking out via `actions/checkout@v4`, installing `bats` and `shellcheck`, running `shellcheck --severity=error debianito.sh modules/**/*.sh` (with `shopt -s globstar`) and `bats tests/`.

- `debianito.sh` CLI parser: `AUTO_YES=0`, `ALLOW_DESTRUCTIVE=0` declared after `MODULES_DIR` and before `_boot_mark`; `_usage()` prints `Usage: debianito.sh [OPTIONS]` with `--yes`, `--allow-destructive` and `--help`; the `while [ $# -gt 0 ]` / `case` loop consumes `--yes` and `--allow-destructive`, prints `Unknown option: $1 (run with --help for usage)` to stderr and `exit 2` for unknown flags, and `--help|-h` runs `_usage` then `exit 0`.

- `modules/utils.sh`: new global `_SELECTION_CONFIRMED=0` and `_confirm_install_list()` (utils.sh:756-785), which renders items capped at 15 with `... and N more`, computes `height` capped at 24, calls `_confirm "$title" "$list" "$height" 65`, arms `_SELECTION_CONFIRMED=${#items[@]}` on yes, and returns 1 for an empty list or on decline. `_install_pkg()` (utils.sh:789-804) decrements the countdown instead of prompting, and only prompts via `elif ! _confirm "Install: ${pkg}" "Install ${pkg}\nVersion: ${ver}?"; then return 0`.

- Bulk retrofit in `modules/extras/**/*.sh` (18 sites): `_confirm_install_list "Título" "${array[@]}" || return` placed right after the `whiptail` selection is parsed, the install loop left intact, and `_SELECTION_CONFIRMED=0` after the loop. Files: office/office.sh:101, system/software_centers.sh:29, system/system.sh:133, communication/communication.sh:68, design/design.sh:42, download/download.sh:48+55, terminals/terminals.sh:31, security/security.sh:30, players/players.sh:20, themes/fonts/fonts.sh:32, dev/dev.sh:44, programming/programming.sh:57, themes/desktop-themes/desktop-themes.sh:30, fetch/fetch.sh:41, themes/icons/icons.sh:47, themes/cursors/cursors.sh:28, internet/internet.sh:197, java.

- `modules/bullseye/extras.sh` (13 sites) plus `modules/bullseye/legacy.sh` (1 site, `install_gaming_bullseye`, guarded with `if [ ${#_install_pkgs[@]} -gt 0 ]` so a i386-only selection does not blank the summary) plus `modules/desktop_display.sh` (1 site, XFCE Custom — a no-loop `_run_cmd` batch with the reset immediately after it). Special cases: download.sh and bullseye/download each have two checklists merged into one combined summary; legacy.sh gaming skips the reset when the list is empty; XFCE Custom resets before `_xfce_polkit_rules` so the counter cannot leak.

- `modules/desktops/desktop_gnome.sh` (new): `gnome_menu()` runs a `_radiolist` with "1" "GNOME (Full Desktop)", "2" "GNOME Core (Minimal Install)", "3" "Back", then `_install_gnome_full()` and `_install_gnome_core()`. Each arms `_confirm_install_list "GNOME Full Desktop" gnome gdm3 || return` (core: `gnome-core gdm3`), keeps an already-configured display manager via `_existing_display_manager` by setting `target_dm="$keep_dm"`, writes the preseed `echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections`, installs `sudo apt install -y gnome gdm3` / `gnome-core gdm3`, enables `gdm3` only when `target_dm = "gdm3"`, resets `_SELECTION_CONFIRMED=0` and calls `_offer_pipewire_after_desktop`.

- `modules/desktops/desktop_kde.sh` (new): `kde_menu()` runs a `_radiolist` with "1" "KDE Plasma (Full Desktop)", "2" "KDE Plasma Desktop (Minimal)", "3" "Back"; `_install_kde_full()` and `_install_kde_minimal()` arm `_confirm_install_list "KDE Plasma Full" kde-standard sddm || return` (minimal: `kde-plasma-desktop sddm`), preseed `sddm shared/default-x-display-manager select sddm`, install `sudo apt install -y kde-standard sddm` / `kde-plasma-desktop sddm`, enable `sddm` only when it is the target DM, reset the counter and offer PipeWire.

- `modules/desktop_display.sh` `desktop_environment_menu()`: `env_items+=("3" "GNOME")`, `env_items+=("4" "KDE Plasma")`, `env_items+=("5" "Back")`; the case adds `3)` loading `gnome` via `_load_module gnome || continue` and calling `gnome_menu`, and `4)` loading `kde` via `_load_module kde || continue` and calling `kde_menu`; the dead TODO comment was removed.

- PipeWire retrofit in `modules/desktop_display.sh` (6 sites): `_install_lxde_full`, `_install_lxde_core`, `_install_xfce_full`, `_install_xfce_minimal`, `_install_xfce_wayland` and `_install_xfce_custom` each call `_offer_pipewire_after_desktop` after their install block.

- `_offer_pipewire_after_desktop()` and `_existing_display_manager()` added at the end of `modules/desktop_display.sh`: `_offer_pipewire_after_desktop` checks `pipewire-audio` (`pipewire` when `DEBIAN_VERSION = 11`), returns 0 via `is_installed`, otherwise `_confirm "PipeWire Audio" "No PipeWire audio server is installed.\n\nInstall the PipeWire audio stack (recommended)?"` calls `_install_pipewire_standard` and returns 0. `_existing_display_manager` reads `${DM_FILE:-/etc/X11/default-display-manager}`, reads the basename as the DM, and otherwise scans `gdm3 lightdm sddm greetd gdm` with `systemctl is-enabled`, printing nothing when none is found.

- `_ensure_apt_updated` added before the GNOME/KDE `apt install` transactions (4 sites, deduplicated per session); `gnome gdm3` and `kde-standard sddm` are installed alongside even when another display manager is kept as the default.

- Extraction to `modules/desktops/`: `desktop_lxde.sh` (38 lines) and `desktop_xfce.sh` (119 lines) created with the `lxde_menu` / `_install_lxde_full` / `_install_lxde_core` and `xfce_menu` / `_install_xfce_full` / `_install_xfce_minimal` / `_install_xfce_wayland` / `_install_xfce_custom` / `_xfce_polkit_rules` blocks moved verbatim; both carry `# License GPL v3` in their headers.

- `modules/desktop_display.sh` reduced from 542 to 394 lines (−154): lines 55-208 removed, the dispatch (desktop_display.sh:39-46) replaced with `_load_module xfce || continue` / `lxde_menu`, and the file left with `manage_desktop_display`, `desktop_environment_menu`, `display_manager_menu`, `lightdm_config_menu`, `configure_greetd`, `configure_gdm3`, `configure_sddm`, the two shared helpers.

- `modules/utils.sh` `_load_module` map: `xfce)` → `${MODULES_DIR}/desktops/desktop_xfce.sh`, `lxde)` → `${MODULES_DIR}/desktops/desktop_lxde.sh`, `gnome)` → `${MODULES_DIR}/desktops/desktop_gnome.sh`, `kde)` → `${MODULES_DIR}/desktops/desktop_kde.sh`; deps for `xfce`, `lxde`, `gnome` and `kde` are `(desktop_display audio)` and `desktop_display` is `(repos audio)`.

- `modules/desktops/desktop_xfce.sh` `_xfce_polkit_rules()` writes `/etc/polkit-1/rules.d/85-suspend.rules` and `89-backlight.rules` via `sudo tee`, adds the `backlight` group with `groupadd --system` fallback, adds the real login user from `/etc/passwd` to `backlight` and restarts `polkit.service`.

- ES→EN user-facing strings: 14 strings across 4 files — `desktop_display.sh` `lxdе_menu` ("LXDE (Full Desktop)", "LXDE Core (Minimal Install)"), `gpu/nvidia.sh` Kepler legacy-driver notice ("Kepler GPU detected (GKxxx)… Install the legacy driver for Kepler?"), `bullseye/legacy.sh` ("Install NVIDIA driver?", "Skipping NVIDIA driver.", "Installing NVIDIA driver ${gpu_gen}...") and `bullseye/extras.sh` ("firmware-linux-nonfree provides drivers for… Install?").

- ES→EN internal comments: ~35 comments across 9 files — section headers in `_install_nvidia_standard`, `gpu/_helpers.sh` (lines 5, 113), `gpu/nvidia.sh` (lines 8-12, 19-22, 68-70, 167-172, 196, 239-253, 262-263, 275, 291, 336-338, 376), `gpu.sh` (lines 15-17), `bullseye/repos.sh` (line 2), `firmware.sh` (line 235, "--- Load verification ---"), `utils.sh` (lines 129, 132, 153 — timezone Paso 1/2/4) and `utils.sh:546,548`.

- set -e abort fix: `debianito.sh:149` now reads `_system_preferences_menu || true`, consistent with the other dispatch chains (14 of the 15 chains already had the guard); a declined pre-apply summary now leaves the TUI alive instead of terminating the script.

- `docs/desktops_display.md`: 4 hunks — intro now lists GNOME/GNOME Core/KDE Plasma/KDE Plasma Desktop/XFCE/XFCE Wayland/XFCE Custom/LXDE, a new "Modular layout" paragraph describing `modules/desktops/` and lazy loading, Block 1 rewritten into four environments, five new bullets (pre-apply summary, existing-DM preservation, PipeWire offer, stale-lists guard) and a Desktop Environment Packages table.

- `docs/quickstart.md` line 284: Desktop Environment entry expanded to pick from XFCE (full / minimal / Wayland `labwc` on Trixie / custom checklist), LXDE (full / core), GNOME (full / core) or KDE Plasma (full / minimal).

- `_existing_display_manager` now takes the config path via `local dm_file="${DM_FILE:-/etc/X11/default-display-manager}"` so the offline test suite never reads the real system file.

- `tests/test_helper.bash`: added `_mock_systemctl()` for `is-enabled` (units in `MOCK_SYSTEMCTL_ENABLED` report `enabled`, everything else `disabled`), `MOCK_SYSTEMCTL_ENABLED=""`, `WHIPTAIL_CALLS`/`MOCK_WHIPTAIL_OUTPUT`/`MOCK_WHIPTAIL_RC`, `MOCK_DPKG_INSTALLED` and the `systemctl` entry in the mock list and in `mock_reset()`.

- `tests/desktops.bats` created with 16 tests: `_existing_display_manager` (file read, file-preferred over an enabled unit, enabled-unit fallback, candidate order, missing file, nothing configured), `_offer_pipewire_after_desktop` (5 tests: skip-installed, accept-installs, decline-returns-0, Bullseye package name, wrong package name on 11), `_load_module` (4 tests for xfce/lxde/gnome/kde) and an unknown-module case; 17→33 tests total.

- `.github/workflows/ci.yml` shellcheck severity raised from `--severity=error` to `--severity=warning`.

- `debianito.sh`: `RED`, `GREEN`, `YELLOW`, `CYAN` and `NC` plus `AUTO_YES`, `ALLOW_DESTRUCTIVE` and `DEBIAN_CODENAME` are now `export`ed as cross-file globals.

- `modules/utils.sh`: `HAS_NVIDIA`, `DESKTOP_ENV`, `AUDIO_SERVER`, `DEBIAN_VERSION` and the other cross-file globals are `export`ed.

- `modules/extras/system/software_centers.sh` gained a `#!/usr/bin/env bash` shebang.

- `shellcheck` triage (v0.11.0, baseline `--severity=warning` 25 findings → 0): removed two dead-code lines (`headless` in `extras/dev/dev.sh`, orphan `dev_id` in `firmware.sh`); `SC2206` in `extras/dev/essential.sh` fixed by expanding `$comp_pkgs` to `"${comp_pkgs[@]}"`; `SC2010`/`SC2046` (3 sites) replaced `ls … | grep` with `compgen -G "…"`; `SC2155` (2 sites, `gpu.sh` and `rescue.sh`) split command substitutions into separate lines; `SC2166` in `repos.sh` replaced `-o` with `{ … || … }`; `SC2221`/`SC2222` (2 sites, `sysinfo.sh` and `utils.sh`) collapsed the `wl*|wlp*|wlo*|wlan*` alternation to `wl*`; `SC1090` in `extras.sh` gained a justification comment on the disable directive.

- Final verification: `bash -n` on all 15 modified `.sh` files and `set -euo pipefail` at `debianito.sh:3` both intact; `bats tests/` reports 33 ok / 0 failed; invariants `offers 11`, `confirm_install_list 39` and `_SELECTION_CONFIRMED=0 40` hold.
 2026-10-05 23:17:38 -05:00
stornic56 21e9973c2f Integrity fixes: atomic writes, rc checks, curl 
- Verified the repository backup rc in migrate.sh. `_persistent_backup_repos()` now aborts before any destructive step when the tar archive is missing or corrupt, removing the invalid backup itself.
- Verified the restore rc in migrate.sh. `_restore_backup()` now reports failure instead of printing a green "Backup restored" message, and its caller distinguishes a restored backup from a failed restore.
- Made the upgrade phases fail honestly. `apt upgrade` and `apt full-upgrade` now abort with `apt --fix-broken install` + `dpkg --configure -a` instructions instead of reporting "completed successfully" over a partially-upgraded system.
- Made repository source writes atomic. Both writers tee into a `.tmp` file and move into place, and the `/etc/apt/sources.list` removal now happens after the write.
- Corrected the SID warning text in migrate.sh to reflect that security fixes arrive via package uploads rather than a nonexistent sid-security suite.
- Added exit-path cleanup traps for the temp `.deb` files: `trap 'rm -f "$deb_path"' RETURN` in `heroic.sh`and `tools.sh`.
- Tightened Heroic download handling: the API fetch uses `curl -fsS --connect-timeout 10 --max-time 30`, the download uses `curl -fsSL --max-time 300`, and the `.deb` is validated with both `dpkg-deb --info` and `dpkg-deb --contents`; `sudo apt install` is guarded with `if !` before the temporary file is deleted.
- Tightened the OpenRGB install path: the Codeberg API fetch uses `curl -fsS --connect-timeout 10 --max-time 30` and the download `curl -fsSL --max-time 300`, with the same dual `dpkg-deb` integrity check as the Heroic fallback.
- Guarded the OpenRGB post-install side effects: the script now aborts after removing the failed `.deb` if `sudo apt install` returns non-zero, so `modprobe i2c-dev`, `/etc/modules`, the `i2c` group membership, `udevadm`, and the `setcap` step no longer run when the package is absent.
 2026-10-04 23:39:40 -05:00
stornic56 454207209a Security Patches & Architecture Refactoring 
- Extracted hardware detection logic from firmware.sh into new modules/hw_detect.sh. Declares shared arrays (PCI_NET_DEVS, USB_WIFI_DEVS, etc) and _detect_all_network_devices() function. The main script now sources hw_detect.sh immediately after utils.sh. firmware.sh retains only _DETECTED_FW_PKGS and _FW_PLAN_PKG_LINES plus installation logic — the detection loop is fully removed, eliminating the circular dependency with bluetooth.sh.
- Fixed interrupt safety in main script: removed pkill -f "apt.*install" and pkill -f "dpkg.*configure" from _on_interrupt(); updated exit message to "Temp files cleaned." Only the signal handler (trap _on_interrupt INT TERM) remains.
- Added strict URL validation to modules/gaming/heroic.sh and modules/gaming/tools.sh using regex ^https://[A-Za-z0-9./_-]+\.deb$ before passing $deb_url to _run_cmd. Blocks command substitution, non-https URLs, and path traversal attempts that could bypass shell quoting.
- Implemented real Bullseye Archive rewrite in modules/bullseye/legacy.sh: adds idempotency check (grep -q archive.debian.org && return 0), creates timestamped backup of /etc/apt/sources.list with sudo cp, writes exact archive Debian sources via sudo tee heredoc, and runs sudo apt-get update || true on failure.
- Added local scope to modules/bluetooth.sh variable service_enable_only=false before the conditional assignment, preventing state bleed from the previous global-only declaration.
- Applied safe array pattern (while IFS= read -r _pkg; do ...) across 32+ files in modules/extras/* and modules/bullseye/legacy.sh, replacing all vulnerable for pkg in $cleaned / for pkg in $install_list loops. Eliminates word-splitting and command-injection risks.
 2026-10-03 00:04:30 -05:00
stornic56 ab665d0bc8 Security hardening & DRY refactoring 
- Fixed command injection in desktop_display.sh by converting word-splitting loops to safe array-based iteration for LightDM/GDM3 configuration and XFCE package installation.
- Added symlink detection guard before repository file operations in repos.sh to prevent TOCTOU attacks during restore_previous_repos().
- Hardened SUDO_USER resolution with awk validation against /etc/passwd to prevent root fallback and ensure real login users are targeted for sudoers configuration.
- Implemented algorithm (lz4/zstd) and size validation before ZRAM configuration writes in zram.sh to reject invalid inputs.
- Protected grep MemTotal read from /proc/meminfo with 2>/dev/null and default assignment under set -u.
- Added || true guards around apt-cache madison pipelines in firmware.sh, kernel.sh, gpu.sh, and utils.sh to prevent pipefail aborts when backports unavailable.
- Wrapped whiptail installation in if/else blocks to allow offline error messages instead of script termination under set -e.
- Fixed grep -c output duplication in swap.sh with proper || true pattern and default variable assignment.
- Replaced unquoted $cleaned loops with array conversion using while read for secure package iteration across gaming, desktop_display, firmware, and kernel modules.
- Anchored sed regex patterns to space-delimited "main" components to prevent mirror URL corruption in sources.list editing.
- Escaped % characters in _msg() function before passing to whiptail to prevent printf format interpretation crashes.
- Consolidated package version helpers into canonical wrappers: _get_pkg_version, _get_installed_version, _get_backports_version for consistent apt/dpkg queries.
- Created _install_if_missing() and _install_pkg() with proper error handling that respects set -e while providing user feedback on installation failures.
- Removed 6 dead code functions (~51 lines): check_system_time, sync_system_time, get_cpu_summary, get_ram_summary, pkg_versions, get_backports_kernel_version.
- Added detect_displayserver and detect_audio_server to refresh_system_state() for complete state refresh when returning from menus.
- Enhanced _on_interrupt() trap handler to kill lingering apt/dpkg child processes and clean /tmp/debianito.* temporary files on Ctrl+C or TERM.
- Improved restore_previous_repos() with manifest-based backup verification (.backed_up_* markers) to prevent destructive repository file deletion.
- Added mktemp usage for secure temporary deb file downloads in nvidia.sh, heroic.sh, and tools.sh to eliminate TOCTOU vulnerabilities in /tmp.
- Fixed Bluetooth USB dongle misclassification as WiFi devices by excluding "bluetooth" strings from USB_WIFI_DEVS detection in firmware.sh.
- Properly utilized the need array for selective package installation in internet.sh instead of hardcoding full package list.
- Corrected fwupdmgr duplicate execution and grep false positives in system.sh with strict pattern matching for available updates.
- update docs and added quickstart guide
 2026-09-14 20:31:48 -05:00
stornic56 33f3004ab5 Docs Update 
- ZRAM Scaling (docs/QUICKSTART.md): Updated Step 9 with the current fixed-4096MB formula: `≤8 GB → 50%`, `>8 GB → 4096 MB fixed`. Replaced obsolete `ram_gb > 16 ? 25% : 50%` and `/4` vs `/2` logic with the new behavior (`ram_gb <= 8 ? 50% : 4096 MB`). Examples: 4GB → 2048 MB, 8GB → 4096 MB, 16GB → 4096 MB, 32GB → 4096 MB.

- GPU Configuration (docs/gpu.md): Added AMD GCN Migration subsection with duplicate guard (`content_differs-style` check) and sed fix logic. Added Secure Boot warning for NVIDIA DKMS (`mokutil --sb-state` detection). Documented `|| return 1` protection for `/etc/modprobe.d/nvidia-wayland.conf` writing. Renumbered duplicate sections 7 → 8 → 9 to avoid duplicate headings.

- Firmware Installation (docs/firmware.md): Updated Broadcom section with `_run_cmd` wrappers (`|| true`) for `apt install broadcom-sta-dkms` and `modprobe wl`. Added SSH network warning (`WARNING: SSH is not recommended on a router`) before `modprobe -r`. Updated Initramfs step with `_run_cmd` wrapper (`|| true`).

- Repo Configuration (docs/repos_config.md): Removed `REPOS_CONFIGURED=true` from the POST-EXECUTION PHASE diagram and Safety Mechanisms. Added `_write_branch_sources` with its `_restore_backup` rollback and "Branch Migration Rollback" safety note to the diagram.

- System Info & Pre-flight (docs/system_info.md): Added pre-flight init (auto-install whiptail + lsb-release). Added LSPCI_OUTPUT cache with `command -v lspci` guard. Added `_ensure_apt_updated` deduplication helper. Added `STATE_REFRESHED=true` flag mechanism across all menu branches.

- User Home Ownership (docs/user_priv_feed.md): Updated Option 3 (Repair Home Ownership) to use `getent passwd "${SUDO_USER:-$USER}"` instead of the insecure `eval echo "~$USER"` pattern. Added documentation note explaining the security rationale.

- QuickStart ZRAM (docs/QUICKSTART.md): Updated Step 9 ZRAM scaling to "50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB)".
 2026-09-12 16:53:10 -05:00
stornic56 a4352ce734 dual-gpu hardening & wireless robustness 
- Protected apt repository writes across modules/repos.sh by adding `|| return 1` to `_write_deb822()` and `_write_classic()`, ensuring script continuation on failure instead of aborting under set -e.
- Added idempotent backup restoration in restore_previous_repos() with `sudo cp ... || true` and `sudo rm ... || true` to prevent fatal errors during repository recovery operations.
- Implemented rollback mechanism in migrate_to_branch() by wrapping _write_branch_sources() in a conditional check, restoring backup on failure and returning error code 1.
- Hardened firmware installation flow in modules/firmware.sh with `|| true` guards on all apt commands (broadcom-sta-dkms, network firmware packages, backports/stable paths), preventing set -e aborts during package management.
- Secured modprobe operations by adding `|| true` to wl module loading and blacklist file writes, ensuring wireless driver installation proceeds even if kernel module operations fail.
- Added GPU tools installation protection in _helpers.sh with `|| true` guard on vainfo command execution after nvtop installation completes successfully.
- Fixed NVIDIA Wayland configuration in modules/gpu/nvidia.sh by adding `|| return 1` to nvidia-wayland.conf tee operation, preventing silent failures when writing modprobe configuration files.
- Implemented network warning notification before Broadcom wireless module removal to alert users of potential SSH disconnection during WiFi driver transitions.
- Added broadcom blacklist file protection with `|| true` guard on modprobe.d/blacklist-broadcom.conf writes to prevent script termination on filesystem errors.
- Standardized error handling patterns across all firmware and GPU modules, replacing direct command execution with conditional wrappers that maintain script continuity under failure conditions.
 2026-09-12 15:15:01 -05:00
stornic56 6f64fb29d4 dual-gpu fix & lspci cache 
- Replaced the restrictive Broadcom firmware installation flow with a persistent, step-by-step process in modules/firmware.sh. Now installs dkms, wireless-tools, and linux-headers-amd64 separately, then applies blacklist configuration, updates initramfs, and loads conflicting modules properly.
- Fixed conky package name across system.sh and bullseye/extras.sh. Changed from "conky" to "conky-all" with corresponding state variable updates for correct installation via apt.
- Corrected broken GRUB sed command in modules/gpu.sh for AMD GCN support. Added grep guard to prevent duplicate parameter insertion and fixed regex pattern for proper cmdline modification.
- Added whiptail pre-flight check in debianito.sh. Auto-installs required TUI dependencies if missing before the main menu, preventing runtime failures.
- Fixed home directory path resolution bug in modules/sudo_config.sh. Replaced eval echo "~$USER" with getent passwd approach for reliable user home detection across SUDO_USER contexts.
- Implemented global lspci output caching across 18+ locations. Single cache population via _init_lspci_cache() before detect_gpu, all subsequent reads use LSPCI_OUTPUT variable to eliminate redundant hardware polling calls.
- Added apt update deduplication helper in modules/utils.sh. _ensure_apt_updated() with APT_UPDATED flag bypasses redundant package list refreshes across extras/, gaming/, firmware/, and desktop_display/ modules while preserving transactional rollback paths in repos.sh.
- Fixed STATE_REFRESHED logic in debianito.sh main_menu case statement. Added STATE_REFRESHED=true to branches 3, 5, 7, 9, 11, 12, and 13 that mutate system state, ensuring refresh_system_state() triggers correctly after configuration changes.
- Removed dead REPOS_CONFIGURED variable from debianito.sh and modules/repos.sh. Variable was written but never read, eliminated to clean up global namespace without affecting repository functionality.
 2026-08-27 01:41:33 -05:00
stornic56 5d14acecc4 Broadcom wl Single-Path Rewrite 
- Removed 4 Broadcom classification helper functions (`_is_broadcom_brcm`, `_is_broadcom_b43`, `_is_broadcom_b43legacy`, `_detect_broadcom_plan_lines`) and their call in `install_firmware()`.
- Rewrote `_handle_wireless()` to a single-path Broadcom → broadcom-sta-dkms → clean conflicting modules → load wl → verify approach, replacing the old 3-tier classification logic.
- Added `linux-headers-amd64` availability verification via `apt-cache policy` before driver installation.
- Added user confirmation step before installing Broadcom driver.
- Preserved BT combo handling (softdep wl post: btusb) and Post-DKMS verification (Fix 5) with the same behavior as the original code.
- Preserved USB Broadcom device detection (0a5c grep) and final message logic.
- Removed `wl_conflict_offered` variable from `_handle_wireless()`.
- All other helpers, arrays, and logic paths remain unchanged.
 2026-08-22 21:47:44 -05:00
stornic56 3d09747985 Broadcom WiFi & zram enhancements 
- modules/firmware.sh — 4 fixes:
  - Added _detect_broadcom_plan_lines() helper to display firmware-brcm80211 in the firmware plan. The plan now shows the correct package for all Tier 1 Broadcom chips.
  - Added post-install verification for Tier 1 (brcmfmac): checks that /lib/firmware/brcm/brcmfmac43* files exist after apt install. If missing, displays a warning with dpkg-reconfigure guidance.
  - Added conflict detection between broadcom-sta-dkms and brcmfmac (wl). If broadcom-sta-dkms is installed, the script prompts the user to purge it before installing firmware-brcm80211, preserving the correct driver.
  - Added a reboot warning after successful brcmfmac firmware installation: [+] Broadcom brcmfmac firmware installed. A system reboot is required to load the new firmware.
  - Added || true to the Tier 3 (wl) _run_cmd call and introduced a wl_build_failed flag to suppress the "No special WiFi firmware needed" message when the DKMS build fails.
  - Removed BCM4313 (ID 4727), BCM43225 (ID 4357), and BCM43227 (ID 4358) from _is_broadcom_brcm. These chips belong to the wl tier and should use broadcom-sta-dkms, not firmware-brcm80211.

- modules/zram.sh — 1 fix:
  - Changed zram sizing logic from 3 branches to 2: the >16 GB branch (which allocated 25% or 50% of RAM) is replaced by a single threshold check. RAM > 8 GB → fixed 4096 MB; RAM ≤ 8 GB → 50% of RAM (using the same ((RAM_KB / 1024 / 1024 + 1) / 2) * 1024 rounding pattern).
 2026-08-21 01:27:53 -05:00
stornic56 9427934546 Firefox bug fix & LXDE desktop option 
- Resolved Firefox installation conflict: the "both" selection no longer triggers duplicate dialogs or cancellation; the installer now passes the resolved choice to both Mozilla and ESR installers, preserving co-installation without redundant prompts.
- Fixed bugs across Debian 11/12/13 scripts:
- Migrated `migrate.sh` to write classic `.sources` format for Debian 11 and skip the security stanza for SID.
- Corrected non-free token matching in `firmware.sh` to avoid false positives on non-free-firmware-only systems.
- Added `sudo` to `broadcom-combo.conf` creation and fixed `/etc/modprobe.d` directory handling.
- Fixed write propagation in `repos.sh` to prevent silent failures on user rejection.
- Corrected PipeWire state detection for Debian 11 and added SID security stanza exclusion.
- Added LXDE desktop environment option to `debianito.sh`:
- New "LXDE (Full)" and "LXDE Core" options in the Desktop Environment menu.
- Both options install `lightdm` in a single `apt-get install` call and enable the service via `systemctl enable`.
- Includes debconf preseed for LightDM default display manager selection.
- No extra packages, no Openbox/LXDE configuration changes.
- Added `_radiolist()` helper to `utils.sh` for safe radio-list cancellation under `set -e`.
- Added `lxde_menu()` to `desktop_display.sh` with exact 2-option radio list, single-shot dispatch, and clean `return 0` on cancel.
- Added `_install_lxde_full()` and `_install_lxde_core()` with `debconf-set-selections`, single `apt` call, and `systemctl enable lightdm` post-install.
 2026-08-19 00:18:41 -05:00
stornic56 b6027e3453 System-Wide Refactor & Critical Fixes 
- Resolved NVIDIA driver management issues by expanding package detection patterns (including nvidia-open and nvidia-kernel-open-dkms), enhancing purge process to ensure clean uninstallation of v590/595 drivers, and adding conditional skip for manage menu when no driver is installed.  
- Enhanced Firefox variant selection in internet.sh using exact token matching (grep -qx) instead of substring search to prevent incorrect removal or unintended ESR/Firefox conflicts. 
- New XFCE install option with 4 options
- Restructured Desktop Environment into two-level menu system with dispatcher and Xfce sub-menu for scalability, enabling future additions like GNOME/KDE without disrupting existing flows.  
- Added Polkit rules in desktop_display.sh to grant suspend permissions without password prompts on laptops, including idempotent group (backlight) creation and user membership management with || true fallbacks.  
- Enforced LC_ALL=C LANGUAGE=C environment variables for all dpkg-reconfigure commands across System Preferences and utils.sh to ensure native dialogues run consistently in English.  
- Fixed kernel backports menu option availability to only appear on Debian 13, preventing errors on Debian 12 where backports repositories are EOL.  
- Improved ZRAM module initialization sequence by ensuring swapoff and zram module removal occur before writing new configuration files to prevent race conditions during system setup.
 2026-08-17 23:50:39 -05:00
stornic56 a913c88ab0 nvidia ux & bookworm bpo cleanup 
- Removed redundant confirmation dialogs from `_install_nvidia_stack`. Users can now access driver management (including removal) without first confirming installation intent; initial plan display is followed by pause for review instead of blocking prompt.
- Automated CUDA repository enabling on Debian 13/Bookworm paths (590/595). Manual confirmation prompts eliminated; script auto-enables repo via `_enable_cuda_repo` with error handling while maintaining safety checks.
- Split CUDA driver installation into two distinct APT transactions in `nvidia.sh`. Step 1 installs mandatory version pinning (`nvidia-driver-pinning-${ver}`); failure aborts process. Step 2 installs `nvidia-open`, relying on transitive dependencies for firmware rather than explicit package listing.
- Eliminated all Bookworm backports support due to EOL (2026-08-09). Removed `_install_nvidia_bookworm_bpo()`, dead code `install_nvidia_driver()`, and dispatcher logic for Debian 12. Turing now installs standard packages only; Trixie backports remain intact.
- Updated documentation (`docs/gpu.md`) to reflect actual installation flow and removed references to deprecated functions.
 2026-08-10 17:58:03 -05:00
stornic56 3064afe69b Fix NVIDIA CUDA Repo Debian 13 
- Fixed critical abort in `_install_nvidia_cuda_repo` for Debian 13 (Trixie) when installing v590/v595 due to `nvidia-open` availability checks.
- Removed pre-install `apt-cache policy` verification that caused premature script termination on version mismatches.
- Eliminated manual creation of `/etc/apt/preferences.d/block-nvidia`, relying exclusively on official NVIDIA pinning packages (`nvidia-driver-pinning-${ver}`).
- Updated error handling to display real `apt` output on failure instead of generic abort messages, improving troubleshooting visibility.
- Synchronized documentation in `docs/gpu.md` to reflect the simplified CUDA repo flow and removed references to manual pinning or candidate checks.
 2026-08-10 00:55:47 -05:00
stornic56 1c42d4cff2 nvidia menu & management updates 
- Refined `_show_nvidia_version_menu` in `modules/gpu/nvidia.sh` for Debian 12/13 with precise labels ("Newest Stable", "Kepler Support") and explicit official repo recommendations.
- Introduced new standalone module `modules/gpu/nvidia_manage.sh` integrated into the dispatcher to handle driver lifecycle management (Install/Change vs Remove) before version selection.
- Implemented safe removal logic (`_nvidia_remove`) with explicit package purging, explicitly excluding `firmware-misc-nonfree`, and cleaning specific configs/repos without wildcards.
- Ensured idempotency across all steps using `|| true` and preserved user CUDA toolkits while restoring Nouveau via initramfs regeneration.
 2026-08-07 23:43:29 -05:00
stornic56 c51f695698 nvidia & zram fixes 
- Fixed critical NVIDIA driver bug on Debian 13 (Trixie) where repo configuration installed v550 instead of selected v595. Implemented version-specific enabling: cuda-keyring for Trixie, extrepo for Bookworm. Added explicit apt update after repo enable and candidate verification before pinning checks to abort cleanly if expected driver unavailable.
- Rewrote `_install_nvidia_standard()` with auto-detected architecture via `_get_nvidia_arch_family()`. Turing/Ampere/Ada/Blackwell → nvidia-open-kernel-dkms (open module); Maxwell/Pascal/Volta/unknown/empty → nvidia-kernel-dkms (closed, safe fallback). Removed all `nvidia-detect` references across modules and docs.
- Fixed `_install_nvidia_cuda_repo()` to use correct CUDA repository package names: v590/v595 → nvidia-open metapackage (includes nvidia-kernel-open-dkms); v550 and below → nvidia-driver. Added dynamic warning message based on installed module type.
- Fixed uninitialized variable bug in `modules/gaming/tools.sh` causing script abortion under `set -u`. Initialized all local variables (`deb_url`, `sha256`, `json`, `deb_suffix`) with default values and added defensive initialization for `$USER` environment variable.
- Fixed ZRAM configuration persistence bug where old config persisted after changes. Added device reset sequence (swapoff + modprobe -r) before writing new config, post-config verification check, and changed default recommendation from 50% to 25% for systems with >16GB RAM.
- Added `_warn_nvidia_gnome_wayland()` function in `gpu.sh` to warn about Debian bug #1109409 (GDM3 + NVIDIA + Wayland black screen issue). Warning displays only when gdm3 present, GNOME Shell 4.x detected, and NVIDIA driver installed.
- Standardized menu headers across all modules using centralized SCROLL_HINT variable, replacing hardcoded strings with uniform Whiptail instructions. Updated documentation for cuda-keyring (Trixie) and ZRAM configuration flow diagrams.
 2026-08-05 21:13:32 -05:00
stornic56 de476f99a7 nvidia driver stability & version menu 
- Refactored NVIDIA installation with robust DKMS verification (`_verify_nvidia_dkms_build`). Automatically detects build failures for the current kernel and repairs them via `dpkg-reconfigure`, ensuring modules compile against active kernels without manual intervention.
- Added Secure Boot detection (`_nvidia_secure_boot_enabled`) to warn users if the NVIDIA module is compiled but unsigned, preventing boot issues on systems with UEFI security enabled.
- Implemented `_configure_nvidia_wayland()` for Wayland support. Detects hybrid laptops (Optimus) vs desktops using DMI chassis types and battery presence. Configures `NVreg_PreserveVideoMemoryAllocations` only for desktops to avoid Optimus conflicts, and adds architecture-specific guards (e.g., Kepler warnings).
- Introduced version selection menu (`_show_nvidia_version_menu`). Users can select driver versions (470/535/550/590/595) based on Debian release. Parametrized CUDA repo installation for 590/595 with post-install DKMS branch verification.
- Fixed state inconsistency bugs in `NVIDIA_DRIVER_MODE`. Added guards to ensure configuration files are only written upon successful installation, preventing partial setups after failures (e.g., backports, CUDA repo).
- Improved hardware detection helpers (`_is_hybrid_laptop`, `_get_nvidia_arch_family`). Prevents false positives on multi-GPU desktops by verifying iGPU presence alongside dGPU.
- Updated Java/Minecraft support in `modules/extras/java.sh`. Added Temurin 25 ("Minecraft 26+") to the runtime selection menu and updated documentation.
- Enhanced utility robustness (`_run_cmd`, `_configure_lightdm`). Properly propagates exit codes from commands and handles failures gracefully (yellow warnings + skip) instead of crashing under `set -e`.
 2026-08-05 01:25:26 -05:00
stornic56 945d058d00 Repos: Empty Sources, Deb822 & Security Fixes 
- Enhanced repository detection logic in `modules/repos/repo_detect.sh`. Implemented `has_active_deb_sources()` for content-aware scanning across `sources.list`, `*.list`, and `*.sources` files. Empty or comment-only files are now correctly identified as "none" to trigger bootstrapping.
- Enforced Debian 13 (Trixie) specific logic in `detect_repo_format()`. Deb822 format is only applied when `debian.sources` is active; Bookworm and Bullseye systems default strictly to classic sources.list regardless of file presence.
- Added state guard against mixed configuration formats (deb822 + classic active simultaneously) with a warning prompt before writing, preventing duplicate entries in `/etc/apt/sources.list`.
- Rewrote `_repos_enable_components()` in `modules/repos.sh` to remove early returns when components are already enabled. The script now verifies and ensures security and updates sections exist/were written correctly if missing or different.
- Created new `bootstrap_repositories()` function for systems with no active sources. Includes user dialogue for format selection (Trixie) or auto-classic (older versions), backup/restore safety, and cleanup of empty sources.list files post-bootstrap.
- Fixed false success reporting in `modules/firmware.sh` and `gaming.sh`. Added pre-checks to ensure APT sources exist before attempting `sed -i` modifications; if sources are missing, the script now triggers a full repository bootstrap instead of silently failing.
- Implemented post-write verification in firmware/gaming modules to confirm components were actually added before reporting success to the user.
- Generalized backports detection in `modules/utils.sh` (`is_backports_enabled()`) to scan all `*.list` and `*.sources` files rather than relying on fixed canonical filenames.
- Corrected test harness variable expansion order and trimmed whitespace from component parsing logic during development verification.
 2026-08-02 00:10:12 -05:00
stornic56 388f601cf1 Fix NVIDIA Kepler Logic & Kernel Headers 
- Normalized PCI ID case sensitivity in `_helpers.sh`. The `detect_nvidia_arch()` function now converts input to uppercase (`${1^^}`) to match legacy architecture map keys, resolving "unknown" detection for all NVIDIA GPUs.
- Removed silent fallback to standard drivers in `gpu.sh` Bookworm logic. Kepler and other architectures now invoke specific installation functions directly without defaulting to unsupported driver versions (e.g., 535).
- Corrected NVIDIA legacy package name in `nvidia.sh`. Updated `_install_nvidia_bookworm_kepler()` to use `nvidia-tesla-470-driver` instead of deprecated Bullseye naming conventions for Debian 12.
- Replaced specific kernel header references (`linux-headers-$(uname -r)`) with meta-package `linux-headers-amd64` in `firmware.sh`. Fixes DKMS installation failures for Broadcom/WiFi drivers across multiple Debian versions.
 2026-07-31 00:38:30 -05:00
stornic56 630ee87bff audio stack & GPU driver unification 
- Unified PipeWire installation into a single checklist option ("PipeWire Audio Stack"). Removed confusing dual options (Standard/Backports) to streamline Debian 13 workflows. Added Bluetooth Hi-Res codec support (LDAC, aptX, AAC) with automatic detection of `libfdk-aac` variants across all Debian versions.
- Refactored `_install_nvidia_standard()` in `modules/gpu/nvidia.sh` to respect the `NVIDIA_DRIVER_MODE` signal from the dispatcher, eliminating external dependency on `nvidia-detect`. Added logic to select between Open Kernel Modules (Turing/Ada/Ampere) and Classic DKMS (Maxwell/Pascal/Volta). Enhanced confirmation dialogs to display both driver and kernel module versions.
- Updated `_install_mesa_32bit()` in `modules/gaming/_helpers.sh` with the same version resolution and upgrade logic as Audio, ensuring consistent UX for Backports selection on Debian 13.
- Expanded `NVIDIA_FAMILY_MAP` in `modules/gpu/_helpers.sh` to include missing silicon prefixes (Hopper, Blackwell variants) while maintaining "legacy" abstraction for driver policy separation.
 2026-07-30 20:33:21 -05:00
stornic56 e7434f8a38 Fix Mesa 32-bit dependencies on Debian 13 
- Resolved critical dependency conflicts for `libgl1-mesa-dri:i386` and related Mesa libraries on Debian 13 when backports are enabled.
- Modified `_install_mesa_32bit()` in `modules/gaming/_helpers.sh` to force `-t trixie-backports` target repository for i386 packages if detected.
- Prevents version mismatch errors (Stable 25.0.7 vs Backports 26.1.2) and missing `libgbm1:i386` issues by ensuring consistent architecture resolution from the backports branch.
 2026-07-29 00:32:59 -05:00
stornic56 abd2918432 dual-gpu & audio fixes + flatpak migration 
- Fixed `set -euo pipefail` crashes across hardware detection: Added `|| true` guards to all `nvidia-smi`, `dpkg -l`, `apt-cache policy`, and `nvidia-detect` pipelines in `sysinfo.sh` (3 lines) and `gpu/nvidia.sh` (7+ lines).
- Created new Audio & Sound module (`modules/extras/audio/audio.sh`) with Debian version-specific logic: Bullseye basic mode vs Bookworm/Trixie standard PipeWire stack, plus ALSA utilities, pavucontrol, pulsemixer, playerctl. Added menu entry "14 Audio & Sound".
- Migrated Flatpak from System Tools to Software Center category. Renamed menu to "Software Center & Flatpak", converted single-select to multi-select checklist in `software_centers.sh`, removed logic from `system.sh`.
- Implemented robust time synchronization: New `_ensure_time_synced()` function in `utils.sh` forces NTP active, validates timezone with interactive `dpkg-reconfigure tzdata` if needed, restarts `systemd-timesyncd`, and verifies sync status. Replaced `check_system_time` call in main script.
- Fixed System Info network detection: Removed hardcoded 2-line height limit (now dynamic via terminal size), fixed hard-coded array indices to use progressive counters for multiple interfaces including USB WiFi adapters.
 2026-07-28 19:55:22 -05:00
stornic56 640fe01c32 fix harden hardware detection D3cold freezes 
Fixes a critical startup crash on hybrid graphics laptops (e.g., Intel + Nvidia) running fresh Debian installs without proprietary drivers. 

When the secondary GPU enters D3cold power state, kernel-level I/O operations (like `lspci` or reading `/sys/block/`) hang in Uninterruptible Sleep (State D), ignoring standard kill signals and freezing the terminal. Combined with `set -euo pipefail`, these hangs made the script silently fail or enter infinite loops.

Changes:
- Timeout Wrappers: Wrapped all hardware probing commands (`lspci`, `lsblk`, `cat /sys/...`, `ip`, `iwgetid`, `pw-cli`) with `timeout 2` to force-continue if the kernel blocks.
- Pipeline Safety: Added `|| true` to `nvidia-smi` and `dpkg` fallback queries to prevent `pipefail` from killing the script when drivers are missing.
- Loop Hardening: Fixed an infinite loop in `detect_gpu()` where empty `lspci` outputs caused by timeouts would loop forever by adding `[[ -z "$line" ]] && continue`.
- TUI Fallbacks: Added default values for `${LINES:-24}` and `${COLUMNS:-80}` to prevent `set -u` from crashing the `whiptail` menu in restricted shell environments.
 2026-07-26 01:15:57 -05:00
stornic56 94372ad172 fix script 
-fix script and nvidia-smi
 2026-07-25 22:53:18 -05:00
stornic56 4819c671cf bash gpu detection fix & nvidia-smi hardening 
- Fixed critical script termination on hybrid GPU systems (Intel+Nvidia). The `set -euo pipefail` header was causing immediate exit when `read` reached EOF with exit code 1, preventing further execution despite valid hardware detection.
- Added `|| true` to the lspci processing loop in `modules/utils.sh`. This forces the while read condition to always return success (0), allowing clean loop termination and proper variable assignment for `HAS_NVIDIA=true` and `HAS_INTEL=true`.
- Hardened nvidia-smi driver version query with timeout protection. Wrapped the command call with `|| true` to capture exit code 124 from `timeout`, preventing script abortion when GPU enters D3cold state or command fails.
- Changes applied at line 204 (while read loop) and line 243 (nvidia-smi query). Both modifications ensure the main script continues execution after hardware detection completes, enabling full menu loading on dual-GPU laptops.
 2026-07-25 22:03:13 -05:00
stornic56 cb77354044 amd gcn legacy support & kernel overhaul 
- Fixed Mesa 32-bit dependency conflicts by removing mesa-va-drivers from gaming setup; mesa-libgallium now includes VA-API for Mesa >= 25.3.3, resolving solver errors with backports (Mesa 26.x).
- Removed corectrl detection and installation from AMD tools in gpu/amd_intel.sh (retained in System Tools checklist only).
- Added zutty terminal emulator option alongside alacritty for Debian 12+ in terminals.sh.
- Overhauled Kernel menu: replaced "Backports Kernel" with "Kernel" submenu offering Stable, RT, Cloud, and Backports options; removed hardcoded Debian 11 restriction (backports hidden only on Bullseye); headers now installed automatically with all kernel variants; NVIDIA warnings added for Backports (DKMS required) and RT (driver compatibility note).
- Implemented AMD GCN legacy driver migration: is_amd_legacy_gcn() function detects GCN 1.0/1.1 GPUs via whitelist of 85 PCI IDs; offers user prompt to force amdgpu module with GRUB parameters (radeon.si_support=0, radeon.cik_support=0, amdgpu.si_support=1, amdgpu.cik_support=1); safe sed-based injection into GRUB_CMDLINE_LINUX_DEFAULT with backup and idempotency check.
- Standardized UI across 27 checklist locations: unified text to "Check [*] the packages you want installed/updated on your system."; removed SCROLL_HINT variable entirely from all code; changed OK button to "Apply" in _checklist() and _inputbox() only (not in _msg/_menu).
- Reordered gaming menu checklists: i386 moved to top position, steam/mangohud positioned immediately after for better dependency flow.
- Enhanced kernel installation prompts: all variants (Stable, RT, Cloud, Backports) now display candidate version numbers in parentheses using apt-cache policy and madison queries.
- update readme
 2026-07-23 00:18:24 -05:00
stornic56 1a692d38f3 zram menu refactor, mesa fix & sysinfo ui 
- Refactored `install_zram` into a dedicated submenu (`zram_menu`) within `modules/zram.sh`. Split monolithic logic into three distinct operations: `_zram_view`, `_zram_create`, and `_zram_remove`. Enables status verification before installation and safe cleanup. Updated main menu entry in `debianito.sh` to call the new sub-menu.
- Resolved Trixie backports dependency conflicts between `mesa-libgallium` and `mesa-va-drivers` (Mesa 26+). Modified package lists in `_helpers.sh` and `gpu.sh` to exclude `mesa-va-drivers` during backports installs, prioritizing `mesa-vulkan-drivers` for stable Gallium integration.
- Implemented dynamic dimensioning in `_show_sysinfo()`. Calculates optimal width/height based on terminal size (`tput cols`) and content length. Truncates long lines to prevent UI overflow in small terminals, capped at 22-line height.
 2026-07-21 00:58:00 -05:00
stornic56 9bcf25b96f System Refactor, GPU & Terminal Overhaul 
- Bug Fixes: Rewrote `install_gaming_bullseye()` in `modules/bullseye/legacy.sh` to use a unified `_checklist` flow (matching Debian 12/13) with automatic i386 architecture detection and driver installation. Fixed greetd "Back" menu crash on Debian 11 by adding version-specific conditional logic in `desktop_display.sh`. Corrected ZRAM text overflow in `zram.sh` using `\n` line breaks for terminal wrapping. Updated Kernel Backports warning message in `debianito.sh` to clarify Bullseye limitations.

- Architecture & Repositories: Refactored Debian 11 repository configuration (`configure_repos_bullseye`) to reuse modern submenus (`_repos_enable_components`, `_branch_migration`), eliminating ~44 lines of hardcoded logic and duplicate source list management. Restricted `non-free-firmware` component availability to Debian 12+ in `modules/repos.sh`. Implemented mandatory `apt autoremove -y` and `apt autoclean` execution immediately after enabling non-free/contrib components (`_repos_enable_components`).

- UI & Menus: Added a new "Communication" menu (Option 4) between Internet and Media Players, featuring Signal, Telegram (with Trixie backports warning), and Hexchat. Moved all terminal emulators from System Tools to the "Customization System" -> Terminals submenu (`modules/extras/terminals/terminals.sh`) with version-specific logic (Alacritty 12+, Blackbox/Ptyxis 13+). Added Joplin installer in Office & Productivity for Debian 12/13 only. Integrated Synaptic into Software Centers menu alongside GNOME and Plasma stores. Unified Essential Pack UI across versions, switching between `fastfetch` (Trixie) and `neofetch` (Bookworm/Bullseye).

- Hardware Drivers: Replaced deprecated `install_gpu_drivers()` in `modules/gpu.sh` with `_install_amd_intel_stack()` and `_install_nvidia_stack()`. Implemented specific logic for Debian 13 (Trixie): Blackwell GPUs now enable the official NVIDIA CUDA repository; Maxwell/Pascal on Backports forces a stable kernel path to ensure driver compatibility. Deprecated `install_nvidia_driver()` in favor of new stack functions while preserving global state variables (`NVIDIA_DRIVER_MODE`).

- Utilities & Cleanup: Added `gdebi` and `bleachbit` to System Tools (GUI-only). Standardized menu headers across 15 files using a centralized `SCROLL_HINT` variable. Ensured VLC installation is conditional on headless status checks in Essential Pack modules.
 2026-07-19 00:57:57 -05:00
stornic56 019cda56d2 Displays managers & zram menu 
- LightDM Overhaul: Rewrote `install_lightdm()` logic to verify both lightdm and lightdm-gtk-gtk-greeter-settings. Now installs the trio in a single command if missing, skipping only when fully present. Added "Enable autologin" option modifying `/etc/lightdm/lightdm.conf` with robust `sed` patterns for `SUDO_USER`. Fixed missing `debconf-set-selections` to ensure LightDM is set as default during installation.
- GDM3 Implementation: Created a new sub-menu in `modules/desktop_display.sh` allowing independent installation of GDM3, User List toggle (hide/show), Autologin configuration via `/etc/gdm3/daemon.conf`, and conditional "Force Enable Wayland on NVIDIA" for Debian 12/13 using udev symlinks.
- SDDM Integration: Added SDDM as option 3 in the Display Manager menu. Implemented automatic session detection (Wayland > X11) to populate `/etc/sddm.conf.d/autologin.conf` without user input, defaulting to plasmawayland, lxqt-wayland, or generic fallbacks.
- greetd support: Added conditional support for Debian 12 and 13 only. Implemented sub-menu with base install, recommended `tuigreet` (with backports handling for Bookworm), and other manual setup options (`gtkgreet`, `nwg-hello`, `wlgreet`) exclusive to Trixie. 
- ZRAM UX Improvements: Updated descriptions in `modules/zram.sh` to explicitly mention I/O reduction and responsiveness benefits for low-RAM systems (e.g., 4GB). Cleaned up compression algorithm labels (`lz4`, `zstd`) to remove redundancy in menu values.
- General Code Quality: Standardized all user-facing messages to English across modules. Ensured independent package installation checks prevent script abortion if one DM fails, while maintaining strict error handling for system configurations.
- update docs and readme
 2026-07-16 01:02:51 -05:00
stornic56 47db517b67 add GRUB timeout TUI and restructure boot menu 
- Rename "Boot Rescue & Repair" to "Boot Rescue + GRUB"
- Add interactive GRUB timeout settings (Disable, 3s, 5s, Custom)
- Implement robust `_set_grub_var` and `_apply_grub_setting` helpers
- Add /etc/default/grub.d/99_script_override.cfg to bypass VM/Cloud-init overrides
- Handle Secure Boot countdown policy restrictions by using menu style
- Fix independent install check for lightdm and lightdm-gtk-greeter-settings
 2026-07-12 00:13:08 -05:00
stornic56 afd0600543 clean TUI core 
- Stripped forced-scrollbar hack from _menu and _checklist
- Eliminated TUI_ANCHO_REFORZADO overflow across 9 files
- Removed redundant _inst() function globally
- Added dynamic list height calculation for checklists
- Introduced Desktop & Display menu (Option 12)
- Fixed non-free-firmware false positive in repo detection
- Restored terminal transparency for apt/vainfo output"
 2026-07-11 22:05:35 -05:00
stornic56 3371bf8136 Broadcom, Utils & Headless Fixes 
- Removed dead Broadcom hardware IDs (4357/4358/4360/4727) from `_is_broadcom_b43`, retaining only valid ID 4352 to eliminate false positives in the case statement.
- Added a guard in `_handle_wireless` Level 3 to verify `linux-headers` availability via `apt-cache policy`. Skips DKMS compilation if headers are missing, preventing transaction failures during installation.
- Implemented Broadcom combo card detection (WiFi + Bluetooth) by scanning `PCI_BT_DEVS`. Automatically writes `/etc/modprobe.d/broadcom-combo.conf` with `softdep wl post: btusb` and warns users about potential reboot requirements.
- Enhanced Level 2 (`firmware-b43-installer`) with post-installation validation for `/lib/firmware/b43`. Provides clear recovery instructions via `sudo dpkg-reconfigure firmware-b43-installer` if the directory is empty or missing after installation.
- Created a new helper `_msg_red()` in `utils.sh` to handle critical error messages with colored Whiptail output, replacing standard alerts for migration warnings and failures.
- Updated `repos/migrate.sh` to use `_msg_red()` for branch migration warnings and failure states, ensuring visibility of critical issues while keeping completion messages informative.
- Verified headless mode guards across 16 separate extras files (`office.sh`, `fetch.sh`, `cursors.sh`, etc.), preventing unnecessary package installations on servers without display environments.
- Completed syntax verification (`bash -n`) across all core and extra modules, ensuring no errors in the updated logic for firmware, gaming, swap, or repository management scripts.
- update readme.md
 2026-07-10 19:50:36 -05:00
stornic56 2fcfca3bac critical-fixes, swap module & gaming overhaul 
- Fixed script crashes from `whiptail` Cancel/Esc under `set -e`. Added `_menu()`, `_checklist()` and `_inputbox()` wrappers with `|| true` to prevent premature exits.
- Resolved startup failures by using defaults instead of relying on unset variables with `set -u`.
- Hardened sudoers management — `_validate_sudoers()` writes to temp file, validates with `visudo -cf`, only copies if successful.
- Replaced `eval` in `_run_cmd` with safer `bash -c` execution.

Swap Management Module (`modules/swap.sh`)
- New standalone module with 9 internal functions and `manage_swap()` entry point.
- Btrfs CoW detection — applies `chattr +C` before swapfile creation to prevent mkswap rejection on Btrfs.
- Dynamic swappiness configuration — reads current system value instead of hardcoding 60, pre-fills inputbox with existing setting.
- Uses `/run/lock/debianito-swap.lock` for early init compatibility (added as option 9 in main menu).

Repository & Branch Migration (`modules/repos/migrate.sh`)
- Handles branch migration from stable (11/12) to Testing or SID with 5-screen UX flow.
- Persistent backup system — creates timestamped tar.gz backups of `/etc/apt/sources.list*`, auto-restores on apt update failure.
- SID guardrails — installs `apt-listbugs` and `apt-listchanges` before upgrade to warn about critical bugs in unstable packages.
- Dynamic menu options based on Debian version (SID shows only 1-2-3 Exit, non-SID includes backports + branch migration).
- New `_components_enabled()` helper detects current contrib/non-free state.

Gaming Module Overhaul
- Unified gaming checklist — merged i386 toggle into single prompt with lazy evaluation instead of separate pre-check.
- Lazy 32-bit architecture enablement — only enables i386 when needed (steam/lutris/i386 selected) and installs graphics drivers if `need_32bit=true`.
- New `_install_nvidia_32bit()` helper with proper driver detection, version pinning, and legacy/tesla variant handling.

Heroic & OpenRGB Downloads
- Heroic — fetches latest release from GitHub API using `jq` to extract amd64.deb URL, validates with `dpkg-deb --info`.
- OpenRGB — downloads from Codeberg Gitea API with SHA256 verification when available, fallback to `dpkg-deb` validation.
- Dynamic codename detection — now detects Bookworm vs Trixie at runtime instead of hardcoded static values for .deb download URLs.

|Other Improvements
- Renumbered main menu: 8=ZRAM, 9=Swap Management, 10=Extras, 11=Boot Rescue, 12=Exit.
- Improved `detect_storage()` — excludes loop/CD-ROM devices via `lsblk -e 7,11`, explicitly skips zram, detects USB/SD via `/sys/block/$name/removable`.
- Standardized SCROLL_HINT across all files with centralized readonly variable.
 2026-07-10 01:42:57 -05:00
stornic56 723043dd65 NTP Sync, LightDM, Wine & Rescue Updates 
-  System Time (NTP)*: Overhauled `modules/utils.sh`. `check_system_time()` now warns if year < 2025 and enables NTP silently if off but valid. `sync_system_time()` conditionally installs/starts `systemd-timesyncd` and verifies synchronization via `timedatectl NTPSynchronized`.
- LightDM Configuration: Added `_configure_lightdm()` to ensure the user list is visible in the greeter. Installs `lightdm-gtk-greeter-settings` and creates an override config (`99-show-users.conf`) during startup without interrupting the flow.
- Wine Installation: Simplified Wine setup in `system.sh` and Bullseye `extras.sh`. Removed i386 multiarch logic; now installs only `wine64 fonts-wine`. Added post-install version verification to confirm successful deployment.
- Lutris Dependencies: Updated `install_lutris()` in `tools.sh` and `legacy.sh`. Now conditionally adds `wine32` only if the system supports i386 architectures, preventing dependency failures on 64-bit-only setups.
- Boot Rescue Module: Created new standalone `modules/rescue.sh`. Provides UEFI boot repair tools: Secure Boot refirm (shim + GRUB) and Initramfs regeneration for all kernels. Integrated into the main menu as a dedicated rescue section.
- update docs
 2026-07-01 00:31:54 -05:00
stornic56 a3a2fe1fe3 WiFi Detection, vainfo & Java JRE 
- Implemented multi-layered WiFi detection logic in `utils.sh`. Added PCI class text grep, exact `lspci -d ::0280` matching for wireless devices, Broadcom vendor ID fallback (`14e4`), and USB discovery via `lsusb`. Improved `sysinfo.sh` fallback message to guide users toward the Firmware option.
- Added `_pause()` execution after `vainfo` outputs in `gpu/_helpers.sh` (`offer_generic_tools`) and `gpu/amd_intel.sh` (`offer_amd_tools`, `offer_intel_tools`). Ensures users can review hardware info before proceeding with tool installation.
- Refactored Java selection in `extras/java.sh`. Switched from single-option `--menu` to multi-select `--checklist`, enabling simultaneous Temurin JRE installations with all versions enabled by default and iterative installation logic.
 2026-06-28 11:48:48 -05:00
stornic56 c6d36a2326 UX Refactor: Pauses, Status & WiFi 
- Implemented global `_pause()` logic across all modules (`utils`, `gaming`, `firmware`, etc.), replacing hardcoded `read -p` calls to standardize exit pauses.
- Unified MangoHud installation into a single command (`apt install -y mangohud:i386`) for gaming and legacy branches.
- Refactored `_inst()` to return `*` instead of `(installed)`, moving the function globally to `utils.sh` and removing duplicates from helpers.
- Enhanced Broadcom WiFi detection with expanded grep patterns ('network controller', 'wireless', etc.) and ID fallback (`14e4`).
- Updated `_run_cmd` to integrate the new pause logic for consistent workflow interruptions during script execution.
 2026-06-27 00:21:09 -05:00
stornic56 ba02dac8e4 lang & firefox-esr 
- Added `_detect_lang()` helper to `modules/utils.sh` (extracts first 2 chars from `$LANG`, fallback to `en`).
- Created `_detect_lang_pkg()` utility for LibreOffice localization: handles regional variants (`es-ar` → `es`) and skips English packages.
- Implemented `_check_network()` with cascade methods (ping→wget→curl) in `modules/utils.sh`. Warning-only pre-flight check after `check_sudo` in `debianito.sh`, compatible with `set -euo pipefail`.
- Fixed system time validation: changed `2026` threshold to `2025` in `check_system_time()` (replaced self-referential `$(date +%Y)` which always evaluated false).
- Refactored LibreOffice language selection in `office.sh`: replaced 10 lines of inline logic with `_detect_lang_pkg "libreoffice-l10n"`.
- Overhauled Firefox ESR integration in `internet.sh`: added state detection, mutual exclusion guard (both Firefox variants selected → warning), new `install_firefox_esr()` function with language support.
- Updated `install_firefox_mozilla()`: added Debian version guard (`<12`), replaced `_run_install` with `_run_cmd`.
- Standardized header in internet menu and improved whiptail UX for Firefox options.
 2026-06-25 22:06:15 -05:00
stornic56 420f8f6282 Bluetooth Fix & GPU ID Expansion 
- Bluetooth Package Cleanup: Replaced deprecated `bluez-utils` with `bluez-tools` in `modules/bluetooth.sh` and `modules/firmware.sh`. Ensures compatibility across all Debian versions.
- Maxwell GPU Detection: Added 4 ID blocks (`0x1340 – 0x17FF`, 480 IDs total). Captures missing cards: 980M/970M, Quadro M laptop, GTX 960/950, Quadro M2000, TITAN X, GTX 980 Ti, Quadro M6000, and Tesla M40.
- Pascal GPU Detection: Expanded 5 ID blocks (`0x15F0 – 0x1D7F`, 528 IDs total). Added support for TITAN Xp, GTX 1080 Ti, and Quadro P-series. Unified GP106/107 ranges and bounded end at `0x1D7F` to prevent Turing conflicts.
- Validation: Passed `bash -n` checks on all modified files. Confirmed zero ID collisions between Maxwell, Fermi, Kepler, and Pascal architectures.
 2026-06-23 23:18:37 -05:00
stornic56 4d692a07db NVIDIA Fermi/Kepler Fixes & Utils 
- Refined NVIDIA GPU detection in `_helpers.sh`. Corrected Kepler GK208 range (`0x1280–0x12BF`) and added refined Fermi ID ranges to eliminate device collisions across architectures.
- Updated `gpu.sh` driver logic for Debian Bookworm (explicit Fermi veto) and Trixie (unified Kepler/Fermi check). Prevents legacy driver conflicts and ensures correct selection per version.
- Cleaned `bullseye/legacy.sh`. Removed outdated Fermi checks with collisions; now inherits unified validation from `_helpers.sh` to maintain Debian 11 compatibility.
- Fixed Wi-Fi interface regex in `utils.sh`. Added `wlan*` pattern to catch ath9k interfaces (`wlan0`) alongside standard wl/wlp/wlo identifiers.
- Validated syntax across all files with `bash -n`. Confirmed zero collision between Fermi and Kepler device IDs, ensuring stable detection on Debian 11/12/
 2026-06-22 18:39:16 -05:00
stornic56 630c1747c8 Update README.md 2026-06-20 22:58:34 -05:00
stornic56 3e39406148 add retroarch, nvidia - java - internet refactor 
- 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
 2026-06-20 21:54:59 -05:00
stornic56 12541c759e firmware & wireless refactor + extrepo Migration 
- Created standalone modules/bluetooth.sh  for `_install_bluetooth_stack()` with desktop-aware frontend selection (bluedevil/KDE, blueman/XFCE/other). Extracted from `firmware.sh`, reducing it from 438 to 369 lines.

- Added `detect_desktop_environment()` and `detect_audio_server()` functions in `utils.sh` with new globals `DESKTOP_ENV=""` and `AUDIO_SERVER=""`.

- New `found_active_wifi` flag detects Qualcomm Atheros AR9485 PCI chips without loaded firmware, displaying `(no driver — install firmware)` instead of silently disappearing. Auto-installs `firmware-atheros + firmware-linux-nonfree` after Firmware & Wireless Setup.

- New `is_nvidia_blackwell()` detects GPUs in ranges `0x2900–0x29BF` and `0x2B80–0x31FF`. Added `_enable_cuda_repo()` helper for extrepo-based CUDA installation with APT pinning. DKMS verification blocks added to all `_install_nvidia_*` functions.

- Standardized repository enablement across 7 modules using `_enable_*_repo()` helpers:
  - `internet.sh`: Firefox/Floorp/LibreWolf, Pale Moon, Tailscale, Mullvad VPN/Browser, ProtonVPN
  - `jellyfin.sh`, `programming.sh` (VSCodium), `java.sh` (Temurin)
  - New `extras/office/office.sh`: OnlyOffice + LibreOffice with language detection

- The main script was reduced from 233 to 137 lines. Created new `modules/sysinfo.sh` (97 lines) for `_show_sysinfo()`. Source chain: `utils.sh → sysinfo.sh → sudo_config.sh → repos → firmware.sh → bluetooth.sh → gpu.sh → kernel.sh → gaming.sh → extras.sh → zram.sh → java.sh`.

- Renamed menu to `"Firmware, Wireless & Bluetooth"`. Translated NTP dialog (English), basic programs install message, and NVIDIA 32-bit legacy messages.
 2026-06-19 22:32:50 -05:00
stornic56 f35ed4572e Reduce user prompts: firmware & graphics updates 
- Rewrote `modules/firmware.sh` with unified detection and installation flow, reducing user interactions from multiple prompts to single confirmation across all hardware types.
- Enhanced `_detect_all_network_devices()` to scan full PCI device lists without truncation (`head -n1` removed) and filter USB devices by keyword patterns (`wireless`, `wifi`, `802.11`, `bluetooth`, `wlan`) to eliminate false positives from card readers/Realtek audio devices.
- Implemented Broadcom 3-tier firmware strategy: Tier 1 (`brcmsmac`, 8 device IDs) auto-installs without extra confirmation; Tier 2 (`b43`/`b43legacy`, ranges 0x4301–0x4331) requires contrib package warnings; Tier 3 (`broadcom-sta-dkms`) needs DKMS compilation approval with explicit precedence handling for overlapping device ID ranges.
- Streamlined `modules/gpu.sh` flow from 169 to 154 lines, cutting user clicks from 4 (intro → proceed → plan → install) to 2 (plan → install), removing redundant intro message before plan display while preserving Intel/AMD firmware auto-installation and Mesa prompting logic.
- Added Bullseye compatibility hook in `modules/bullseye/extras.sh` (`type _handle_wireless &>/dev/null && _handle_wireless`) to ensure Broadcom wireless handling works correctly in Debian 11 environment with lazy detection fallback for empty PCI network devices.
- Fixed whiptail UI spacing issues in message paragraphs for improved readability and standardized dialog geometry across firmware/graphics dialogs.
 2026-06-17 15:57:07 -05:00
stornic56 ef78ba3642 system overhaul and bug fixeds 
- Replaced the fragile upstream script installer with native Deb822 repository injection and automated GPG keyring management in `jellyfin.sh`. Eliminated external dependencies, checksums, and interactive flags for guaranteed non-interactive support across Bullseye/Bookworm/Trixie.
- Upgraded the NVMe module (`modules/extras/system/system.sh`) to perform multi-drive scanning with dynamic `lsblk` parsing. Replaced single-disk detection logic with a `while read` loop to capture all devices, displaying formatted SMART health diagnostics (Critical Warning, Temperature, Percentage Used).
- Overhauled the 'System Information' TUI into a multi-device dashboard featuring standalone GPU/Driver hierarchies and dynamic storage mapping. Added new globals (`DISPLAY_SERVER`, `STORAGE_SUMMARY`) and comprehensive arrays for Network/Wi-Fi interface indexing in `modules/utils.sh`.
- Redesigned the graphics stack layout to fix multi-GPU text clipping and unified Mesa version prompting logic. Integrated post-install package telemetry to display live versions in the completion screen, separating planning visualization from installation decision points in `modules/gpu.sh`.
- Fixed non-free-firmware conceptual documentation bugs and expanded Backports descriptions with hardware-focused educational text. Added non-free repository safeguards for Trixie/Bullseye compatibility under "Firmware & Wireless Drivers".
- Refactored repository logic in modules/repos.sh to eliminate dead code (redundant default_text variables) and strict-hardcoded layout behaviors, standardizing dialog geometry to a clean matrix.
- Updated README.md
 2026-06-16 19:59:15 -05:00
stornic56 0400c00201 dual-gpu fix & nvme 
- Replaced the restrictive head -n1 hardware parsing with a dynamic while read loop. The script now fully detects and registers multiple coexisting GPUs (Intel+Nvidia / AMD+Nvidia).
- Rewrote install_gpu_drivers() in modules/gpu.sh from a mutually exclusive case block to independent, sequential if conditions. Laptops now install both integrated firmware (Intel/AMD with non-free VA-API acceleration) and dedicated graphics stacks (Nvidia driver + 32-bit libs for Steam) seamlessly in a single pass.
- Improved Nvidia Kepler architecture guards under Debian 13 (Trixie). The script now safely skips missing legacy Nvidia packages without aborting or crashing the remaining Intel/AMD configurations.
- Added nvme-cli utility installation across all Debian versions. For Bookworm and Trixie, it features dynamic hardware validation via lsblk transport filtering and interactive, real-time SMART log viewing with an execution screen-pause.
- Created a brand new standalone module (modules/extras/dev/jellyfin.sh) to cleanly inject Jellyfin Media Server across Debian 11, 12, and 13 using its official setup script, protected by strict SHA256 checksum validations and guaranteed error-cleanup.
- Added OpenRGB to the Gaming menu for Debian 12 and 13. Implemented secure curl downloads with an emulated Chrome User-Agent to bypass Codeberg bot blocks, complete with automatic i2c-dev module configuration, user groups provisioning, and udev permission rules execution.
- Standardized menu headers across 15 separate files using a centralized readonly SCROLL_HINT=" [↑↓]" variable, replacing messy hardcoded strings with clean, uniform Whiptail instructions.
- update README.md
 2026-06-16 16:20:30 -05:00
stornic56 9de6921a0f fix backports and system modules 
- Refactored `is_backports_enabled()` to dynamically detect backports using `DEBIAN_CODENAME` instead of hardcoded strings, improving script portability.
- Added support for standalone classic backports files (`/etc/apt/sources.list.d/debian-backports.list`) and deb822 format (`*.sources`) to ensure consistent detection across different repository configurations.
- Resolved Mesa and Kernel backports detection bugs, ensuring correct dialogue prompts and preventing false error messages during installation.
- Implemented smart rounding for zram memory allocation to the nearest Gigabyte for optimized performance.
- Enhanced Whiptail manual input validation for zram to block empty, non-numeric, or zero values.
- Introduced a dedicated `software_centers.sh` module for the modular and clean installation of GNOME Software and Plasma Discover.
- Added smart desktop environment detection (GTK/QT) to automatically suggest and install the optimal software center.
- Implemented a two-phase installation flow for software centers (Base Store -> Optional Flatpak support) with static consistency warnings based on the detected desktop environment.
- update README.md
 2026-06-14 22:01:56 -05:00
stornic56 4c95051c55 add Java JDK/JRE selection and patches 
- Created dedicated `extras/java.sh` module for modular Temurin/Adoptium repository handling and isolated GPG key management.
- Implemented selective JRE/JDK installation paths: Gaming (Minecraft) vs Development environments with version control selectors.
- Enhanced user group membership logic (`_ensure_sudo_group`) to auto-configure administrative privileges on fresh installs.
- Introduced maintenance-friendly passwordless sudo for `apt`, `systemctl`, and shutdown commands via `/etc/sudoers.d/`.
- Added home directory ownership repair utility to fix root-owned files in user directories after improper `sudo` usage.
- Enabled visual password feedback (`pwfeedback`) toggle for enhanced terminal usability during authentication prompts.
- Refactored Debian 13/Trixie repository sourcing logic to ensure idempotency and prevent backports/duplicate sources conflicts.
- Updated Bullseye legacy modules (extras.sh, repos.sh) to exclude deprecated packages (`hx`, `vscodium`) and enforce Firefox ESR defaults.
- Cleaned repository configurations by removing obsolete `bullseye-updates` source entries to prevent dependency conflicts.
- Implemented NVTOP conditional detection logic ensuring display only on active Nvidia drivers or supported architectures (Trixie/Bookworm).
- Corrected `/modules/bullseye/extras.sh` menu mappings (Programming, Dev Tools) and verified package lists excluding incompatible tools (`hx`, `vscodium`).
- Integrated ClamAV security module with daemon state management and background scan execution flows in all Security menus.
- update README.md
 2026-06-13 19:21:55 -05:00
stornic56 f1bd887a29 add Debian 11 support 
- Created dedicated modules/bullseye/` folder for legacy isolation (Debian 11 support).
- Implemented 4-block inclusive PCI range detection for Nvidia Kepler/Fermi to prevent black screens.
- Centralized system time verification checking against year 2026 before APT execution.
- Cleaned and purged modern package lists for the Bullseye extra software module.
- Updated main menu with conditional sourcing and fixed Option 7 (Gaming Lite) for Bullseye.
- Updated README.md with explicit TUI navigation instructions and full repository directory tree mapping.
 2026-06-11 17:22:11 -05:00
stornic56 b9139c9c91 Update README.md 2026-06-09 23:44:52 -05:00
stornic56 72621e656f Update README.md 2026-06-09 23:04:15 -05:00
stornic56 9febb579d9 Add files via upload 2026-06-09 23:03:30 -05:00
stornic56 9e051d0bb9 Add files via upload 2026-06-03 20:15:52 -05:00
stornic56 547eab815f Add files via upload 
update
 2026-05-23 22:50:36 -05:00
stornic56 4c6a4f7130 Update README.md 2026-05-20 12:28:11 -05:00
stornic56 534faa36c6 Changes 
General changes to the script order
New programs
Changes in flow
Name revisions
 2026-05-20 12:26:06 -05:00
stornic56 c21fe01f10 Add files via upload 2026-05-17 20:19:39 -05:00
stornic56 f79d318178 Update README.md 2026-05-15 16:22:26 -05:00
stornic56 2469916d80 Update README.md 2026-05-15 16:19:35 -05:00
stornic56 5f68470adb Create LICENSE 2026-05-15 16:15:20 -05:00
stornic56 60d0d2685f Delete LICENSE 2026-05-15 16:10:24 -05:00
stornic56 773d51bb0f Add files via upload 2026-05-14 21:52:17 -05:00
stornic56 488036b906 Add files via upload 
update files
 2026-05-11 17:11:11 -05:00
stornic56 111bd9c5e7 Update README.md 2026-05-07 11:45:10 -05:00
stornic56 b5028a4beb Add files via upload 2026-05-07 01:31:33 -05:00
stornic56 3b27d3c461 Add files via upload 2026-05-07 01:31:06 -05:00
stornic56 9655de0e3e Update README.md 2026-05-07 01:30:42 -05:00
stornic56 5de677a3fc Update README.md 2026-05-05 20:56:10 -05:00
stornic56 754e0497aa Update README.md 2026-05-05 20:54:57 -05:00
stornic56 3fdc844458 Create README.md 2026-05-05 20:53:34 -05:00
stornic56 d385555c8c Add files via upload 2026-05-05 20:27:02 -05:00
stornic56 198c74be4e Initial commit 2026-05-05 20:18:12 -05:00
32 changed files with 1039 additions and 1014 deletions
Expand all files Collapse all files
.github/workflows/ci.yml
+18
View File
@@ -0,0 +1,18 @@
name: CI
on: [push, pull_request]
jobs:
lint-and-test:
runs-on: ubuntu-latest
container: debian:trixie
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install bats + shellcheck
run: apt-get update && apt-get install -y bats shellcheck
- name: Shellcheck (entry point + all modules)
shell: bash
run: |
shopt -s globstar
shellcheck --severity=warning debianito.sh modules/**/*.sh
- name: BATS test suite
run: bats tests/
.gitignore
+1
View File
@@ -0,0 +1 @@
tests/.tmp/
LICENSE
+1 -1
View File
@@ -652,7 +652,7 @@ Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode: notice like this when it starts in an interactive mode:
Debianito Copyright (C) 2026 stornic56 <program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details. under certain conditions; type `show c' for details.
README.md
+56 -13
View File
@@ -2,7 +2,7 @@
<div align="center"> <div align="center">
Debianito is a user-friendly post-installation automation script for Debian 11 (Bullseye), Debian 12 (Bookworm) and Debian 13 (Trixie). It streamlines system configuration, driver installation (including NVIDIA drivers), repository setup with backports support, gaming tools integration, and more with an interactive menu-driven interface. Debianito is a post-installation automation script for Debian 11 (Bullseye), Debian 12 (Bookworm) and Debian 13 (Trixie). An interactive menu guides system configuration, driver installation (including NVIDIA drivers), repository setup with backports support and gaming tools.
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg?style=for-the-badge&logo=gnu&logoColor=white)](https://github.com/stornic56/debianito-post-install/blob/main/LICENSE) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg?style=for-the-badge&logo=gnu&logoColor=white)](https://github.com/stornic56/debianito-post-install/blob/main/LICENSE)
![Script](media/gift/script.gif) ![Script](media/gift/script.gif)
@@ -36,13 +36,37 @@ chmod +x debianito.sh && ./debianito.sh
--- ---
## Command-Line Usage
Running `./debianito.sh` with no arguments starts the interactive menu. Three flags change that behavior:
| Flag | Effect |
| ---- | ------ |
| `--yes` | Auto-confirms prompts (unattended mode). Menus still display and still require interaction. |
| `--allow-destructive` | Allows destructive operations, such as branch migration, without the extra safety gate. |
| `--help`, `-h` | Show usage and exit. |
`--yes` alone still blocks branch migration, which is the one operation that can leave the system unbootable. When that happens the script stops and prints `Branch migration is destructive. Re-run with --allow-destructive, or drop --yes to confirm interactively.` to stderr. Combine both flags to run everything unattended:
```bash
./debianito.sh --yes --allow-destructive
```
An unknown option exits with status 2. For boot profiling, set `DEBIANITO_PROFILE=1` to stamp each boot step to stderr with a timestamp:
```bash
DEBIANITO_PROFILE=1 ./debianito.sh
```
---
## Usage ## Usage
After running the script: After running the script:
1. **Select Option:** Use arrow keys or type 1-14. 1. **Select Option:** Use arrow keys or type 1-14.
2. **Navigation:** Use Arrow Keys (Up↑/Down↓) to move between list options and ENTER key to confirm selection. 2. **Navigation:** Use Arrow Keys (Up↑/Down↓) to move between list options and ENTER key to confirm selection.
3. **Confirm Actions:** Installation prompts use whiptail for TUI confirmations. 3. **Confirm Actions:** Installation prompts use whiptail for TUI confirmations. Before a batch of packages is applied, the script shows what it is about to install (up to 15 package names plus a count of the rest) and asks you to proceed.
4. **Review System Info:** Header displays detected Debian version and hardware summary before each action. 4. **Review System Info:** Header displays detected Debian version and hardware summary before each action.
5. **Repeat as Needed:** Return to main menu at any time or exit when done. 5. **Repeat as Needed:** Return to main menu at any time or exit when done.
@@ -60,12 +84,12 @@ After running the script:
| **10** | [Swap Management](/docs/swap.md) | Manage swap file or partition size and enable/disable swap space for system stability | | **10** | [Swap Management](/docs/swap.md) | Manage swap file or partition size and enable/disable swap space for system stability |
| **11** | Install Programs and Software | Browse and install packages by category (Development, Themes, System Tools, etc.) using APT | | **11** | Install Programs and Software | Browse and install packages by category (Development, Themes, System Tools, etc.) using APT |
| **12** | [Boot Rescue + GRUB](/docs/boot.md) | Config and fix GRUB bootloader issues, chroot repair, or restore system boot configuration | | **12** | [Boot Rescue + GRUB](/docs/boot.md) | Config and fix GRUB bootloader issues, chroot repair, or restore system boot configuration |
| **13** | [Desktop & Display](/docs/desktops_display.md) | Install and configure desktops (XFCE, LXDE) and display managers (LightDM, GDM3, SDDM, greetd) | | **13** | [Desktop & Display](/docs/desktops_display.md) | Install and configure desktops (XFCE, LXDE, GNOME, KDE Plasma) and display managers (LightDM, GDM3, SDDM, greetd) |
| **14** | Exit | Return to terminal | | **14** | Exit | Return to terminal |
### Install Programs and Software (Option 11) ### Install Programs and Software (Option 11)
The submenu offers the next categories: The submenu offers these categories:
| Option | Category Title | Description | | Option | Category Title | Description |
| -------- | ------------------------------- | ------------- | | -------- | ------------------------------- | ------------- |
@@ -73,7 +97,7 @@ The submenu offers the next categories:
| **1** | Customization System | Desktop themes, icon themes, cursor themes, and fonts | | **1** | Customization System | Desktop themes, icon themes, cursor themes, and fonts |
| **2** | Download & Network | Downloaders (aria2, ytdlp, FileZilla) + Torrent clients (qBittorrent, Deluge, Transmission) | | **2** | Download & Network | Downloaders (aria2, ytdlp, FileZilla) + Torrent clients (qBittorrent, Deluge, Transmission) |
| **3** | Internet (Browsers, Email Clients, VPN) | Web browsers (Firefox, LibreWolf, Floorp, Chromium, Tor), email client (Thunderbird), and VPN tools (RiseUp, Proton, Mullvad) | | **3** | Internet (Browsers, Email Clients, VPN) | Web browsers (Firefox, LibreWolf, Floorp, Chromium, Tor), email client (Thunderbird), and VPN tools (RiseUp, Proton, Mullvad) |
| **4** | Communication | Signal, Telegram, HexChat — chat and messaging clients (GUI only) | | **4** | Communication | Signal, Telegram, HexChat: chat and messaging clients (GUI only) |
| **5** | Media Players | Multimedia playback with VLC media player and MPV for advanced video/audio support | | **5** | Media Players | Multimedia playback with VLC media player and MPV for advanced video/audio support |
| **6** | Multimedia & Design | Image editing (GIMP), video editing (Kdenlive, HandBrake), 3D modeling (Blender), audio recording (Audacity), and graphics design (Inkscape) | | **6** | Multimedia & Design | Image editing (GIMP), video editing (Kdenlive, HandBrake), 3D modeling (Blender), audio recording (Audacity), and graphics design (Inkscape) |
| **7** | Code Editors & IDEs | vim, vim-gtk3, Neovim, Helix, nano, Emacs, Kate, Mousepad, Gedit, Geany, GNOME Text Editor, and VSCodium (VS Code open-source) | | **7** | Code Editors & IDEs | vim, vim-gtk3, Neovim, Helix, nano, Emacs, Kate, Mousepad, Gedit, Geany, GNOME Text Editor, and VSCodium (VS Code open-source) |
@@ -89,14 +113,14 @@ The submenu offers the next categories:
## Quick Start Guide ## Quick Start Guide
For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick Start Visual Guide](/docs/quickstart.md). It provides: For a full setup in ~15-20 minutes, refer to the [Quick Start Visual Guide](/docs/quickstart.md). It provides:
- Step-by-step recommended order for running Debianito options (Steps 1–13) - Step-by-step recommended order for running Debianito options (Steps 1–13)
- What each option does and when to enable it - What each option does and when to enable it
- Screenshots of key dialogs (whiptail menus, confirmations, hardware detection) - Screenshots of key dialogs (whiptail menus, confirmations, hardware detection)
- Troubleshooting tips for common issues (WiFi after firmware install, NVIDIA + Wayland, GRUB boot menu hidden, etc.) - Troubleshooting tips for common issues (WiFi after firmware install, NVIDIA + Wayland, GRUB boot menu hidden, etc.)
**Tip:** If you're unsure where to start, follow Steps 1–5 from the Quick Start guide. They cover the essentials: system info, permissions, repositories, firmware, and graphics drivers. **Tip:** If you're unsure where to start, follow Steps 1–6 from the Quick Start guide. They cover the essentials: system info, permissions, repositories, firmware, and graphics drivers.
--- ---
## File Structure ## File Structure
@@ -111,9 +135,17 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
| `modules/extras/` | Software installer sub-modules split by category (themes, downloaders, internet, dev tools, etc.). | | `modules/extras/` | Software installer sub-modules split by category (themes, downloaders, internet, dev tools, etc.). |
| `modules/gaming/` | Gaming launcher and optimization scripts: Steam, Heroic, Lutris, performance tools. | | `modules/gaming/` | Gaming launcher and optimization scripts: Steam, Heroic, Lutris, performance tools. |
| `modules/gpu/` | GPU driver installation scripts for AMD and NVIDIA with architecture detection. | | `modules/gpu/` | GPU driver installation scripts for AMD and NVIDIA with architecture detection. |
| `modules/desktops/` | Desktop environment installers: `desktop_xfce.sh`, `desktop_lxde.sh`, `desktop_gnome.sh`, `desktop_kde.sh`. |
| `modules/hw_detect.sh` | Shared hardware detection (PCI/USB network, WiFi and Bluetooth devices); sourced early by `debianito.sh` and consumed by firmware and Bluetooth modules. |
| `modules/repos/` | Repository management scripts: migration tool (`migrate.sh`) and format detection (`repo_detect.sh`). | | `modules/repos/` | Repository management scripts: migration tool (`migrate.sh`) and format detection (`repo_detect.sh`). |
| `tests/` | Offline BATS suite: `utils.bats`, `repo_detect.bats`, `desktops.bats` plus shared setup in `test_helper.bash`. |
| `.github/workflows/ci.yml` | CI pipeline: ShellCheck at warning severity and the BATS suite. |
```bash ```bash
├── .github
│ └── workflows
│ └── ci.yml
├── .gitignore
├── debianito.sh ├── debianito.sh
├── docs ├── docs
│   ├── boot.md │   ├── boot.md
@@ -156,8 +188,13 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
│   │   ├── extras.sh │   │   ├── extras.sh
│   │   ├── legacy.sh │   │   ├── legacy.sh
│   │   └── repos.sh │   │   └── repos.sh
│   ├── desktop_display.sh │ ├── desktop_display.sh
│   ├── extras │ ├── desktops
│ │ ├── desktop_gnome.sh
│ │ ├── desktop_kde.sh
│ │ ├── desktop_lxde.sh
│ │ └── desktop_xfce.sh
│ ├── extras
│   │   ├── audio │   │   ├── audio
│   │   ├── communication │   │   ├── communication
│   │   │   └── communication.sh │   │   │   └── communication.sh
@@ -212,8 +249,9 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
│   │   ├── _helpers.sh │   │   ├── _helpers.sh
│   │   ├── nvidia_manage.sh │   │   ├── nvidia_manage.sh
│   │   └── nvidia.sh │   │   └── nvidia.sh
│   ├── gpu.sh │ ├── gpu.sh
│   ├── kernel.sh │ ├── hw_detect.sh
│ ├── kernel.sh
│   ├── repos │   ├── repos
│   │   ├── migrate.sh │   │   ├── migrate.sh
│   │   └── repo_detect.sh │   │   └── repo_detect.sh
@@ -225,8 +263,13 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
│   ├── system │   ├── system
│   │   ├── audio.sh │   │   ├── audio.sh
│   │   └── system_prefs.sh │   │   └── system_prefs.sh
│   ├── utils.sh │ ├── utils.sh
│   └── zram.sh │ └── zram.sh
├── tests
│ ├── desktops.bats
│ ├── repo_detect.bats
│ ├── test_helper.bash
│ └── utils.bats
└── README.md └── README.md
``` ```
debianito.sh
Regular → Executable
View File
docs/QUICKSTART.md
-331
View File
@@ -1,331 +0,0 @@
# Debianito — Quick Start Visual Guide
> **Scope:** Fresh Debian 11 / 12 / 13 installation → fully configured desktop in ~15-20 minutes.
> **Prerequisites:** Normal user with `sudo` access. Do **not** run the script as root.
> **Related:** [README Overview](../README.md) · [System Info](system_info.md) · [Repositories](repos_config.md) · [Firmware](firmware.md) · [GPU](gpu.md) · [Kernel](kernel.md) · [Gaming](gaming.md)
---
## Before You Start
```bash
git clone https://github.com/stornic56/debianito-post-install
cd debianito-post-install
chmod +x debianito.sh && ./debianito.sh
```
The script automatically checks for `whiptail` and `lsb-release`, installs them if missing, verifies `sudo` access, checks network connectivity, and synchronizes the system clock (`systemd-timesyncd` + `tzdata`).
> **Screenshot placeholder:** `media/screenshots/00-main-menu.png` — Main menu (14 options, whiptail centered at 78×20).
---
## Recommended Order
Each step builds on the previous one. Steps 1-5 + 10 are the essential path; 6-9 are optional.
### Step 1 — Know Your System
**Menu:** `1 System Information`
Opens a whiptail message box populated by `utils.sh` detection functions (`detect_cpu_ram`, `detect_gpu`, `detect_network`, `detect_storage`, `detect_displayserver`, `detect_desktop_environment`).
You will see:
- Debian version and codename
- CPU model and RAM size
- GPU vendor(s) and device IDs (e.g., `10de:2684` for NVIDIA)
- Network adapters (Ethernet + WiFi chipset) and their state/IP
- Storage topology (NVMe / SSD / HDD / USB-SD)
- Display server (Wayland / X11 / tty) and desktop environment
Write down the **GPU line** (Intel / AMD / NVIDIA) and any **WiFi chipset** — you will need them in Steps 4-5.
> **Screenshot placeholder:** `media/screenshots/01-system-info.png` — System Information dialog with hardware summary.
> **Tip:** If `GPU: No GPU detected` appears, you are on a VM or headless server — skip Step 5 (Graphics Drivers).
### Step 2 — Fix Permissions Early (Optional but Recommended)
**Menu:** `2 User Privileges & Feedback`
A sub-menu with four toggles:
| Option | What It Does | When to Enable |
| -------- | -------------- | ---------------- |
| Sudo group membership | `usermod -aG sudo $USER` | Fresh install where the first user is not in `sudo` |
| Passwordless sudo | Creates `/etc/sudoers.d/$USER-nopasswd` with `NOPASSWD` for `apt`, `systemctl`, etc. | Lab / personal machine; skip on shared systems |
| Repair home ownership | `chown -R $USER:$USER $HOME` | Home files owned by root after a mishandled `sudo` |
| Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` — shows `****` while typing | **Enable now** to avoid typos during the many installs that follow |
> **Screenshot placeholder:** `media/screenshots/02-user-privileges.png` — User Privileges & Feedback menu.
> **Screenshot placeholder:** `media/screenshots/02b-pwfeedback.png` — Confirmation dialog for "Sudo Password Feedback" with asterisk preview.
### Step 3 — System Preferences (Optional)
**Menu:** `3 System Preferences`
```
1 Date, Time & Timezone
2 Language, Locales & Keyboard
3 Audio & Sound Stack
4 Back to main menu
```
- **Date, Time & Timezone** — Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update` — a wrong clock breaks GPG verification.
- **Language, Locales & Keyboard** — Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
- **Audio & Sound Stack** — Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [system_prefs.md](system_prefs.md).
> **Screenshot placeholder:** `media/screenshots/03-system-prefs.png` — System Preferences menu.
> **Screenshot placeholder:** `media/screenshots/03b-audio.png` — Audio & Sound checklist with PipeWire selected.
### Step 4 — Configure Repositories (Required)
**Menu:** `4 Configure Repositories`
```
1 Enable Contrib & Non-Free Components
2 Migrate traditional sources.list to DEB822 format
3 Setup/Update Backports repositories
4 [ADVANCED] Upgrade system branch (Testing / SID)
5 Back to main menu
```
1. Choose **1. Enable Contrib & Non-Free** — adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
2. Choose **3. Setup/Update Backports** — answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [repos_config.md](repos_config.md).
> ⚠️ Without `non-free` and `contrib`, Steps 5 and 8 will fail. Do not skip.
> **Screenshot placeholder:** `media/screenshots/04-repos.png` — Repositories menu.
> **Screenshot placeholder:** `media/screenshots/04b-backports.png` — Backports confirmation dialog.
### Step 5 — Install Firmware & Wireless Drivers
**Menu:** `5 Firmware, Wireless & Bluetooth`
The script:
- Scans **all** network hardware (PCI `lspci -nn` + USB `lsusb`, filtered for Realtek/Intel/Mediatek/Atheros/Qualcomm) and Bluetooth controllers
- Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc` — plus `firmware-linux-nonfree` as the base meta-package
- Builds a plan showing detected controllers and planned packages, including Bluetooth handling (KDE → `bluedevil`, XFCE → `blueman`, GNOME → built-in, plus `pipewire-pulse`/`wireplumber` if PipeWire is active)
- Asks for confirmation before installing; offers Stable vs Backports for the base firmware
Accept the plan it shows — it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
> ⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first — the driver needs a fresh load.
> **Screenshot placeholder:** `media/screenshots/05-firmware-plan.png` — Firmware plan dialog with hardware + package list.
> **Screenshot placeholder:** `media/screenshots/05b-bluetooth.png` — Bluetooth section of the plan (if applicable).
### Step 6 — Install Graphics Drivers
**Menu:** `6 Graphics Drivers & Mesa Stack`
Whiptail radiolist with two options:
```
1 Radeon/Intel Mesa
2 NVIDIA Drivers
```
#### Path A — Radeon/Intel Mesa
Shows a plan with detected GPUs (`Intel firmware + intel-media-va-driver-non-free` or `i965-va-driver-shaders` for Gen7-, `firmware-amd-graphics` for AMD, plus `Mesa Vulkan/OpenGL/VA-API`). Offers legacy AMD GCN 1.0/1.1 migration to `amdgpu` via GRUB params (`radeon.si_support=0 ... amdgpu.si_support=1`). Installs Mesa from Backports or Stable (`_install_mesa_backports`), verifies `mesa-vulkan-drivers`, and offers vendor-specific telemetry (`radeontop`, `intel-gpu-tools`, `vainfo`).
#### Path B — NVIDIA Drivers
Shows detected NVIDIA GPUs and a two-stage menu:
1. **Manage menu** (if a driver is already installed): *Install / Change Driver Version* vs *Remove Driver and Restore Nouveau*.
2. **Version menu** (depends on Debian version):
- Bookworm: `v535` (Recommended) or `v470` (Kepler legacy via `nvidia-tesla-470-driver`)
- Trixie: `v550` (Debian stable, Recommended), `v590` or `v595` (NVIDIA CUDA Repo with `cuda-keyring` + `nvidia-open` + `firmware-nvidia-gsp`)
The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility — e.g., Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
> **Screenshot placeholder:** `media/screenshots/06-gpu-choice.png` — GPU type selector (Radeon/Intel vs NVIDIA).
> **Screenshot placeholder:** `media/screenshots/06b-nvidia-version.png` — NVIDIA version menu (535 / 470 or 550 / 590 / 595).
> **Tip:** After installation, **reboot** before testing. NVIDIA drivers need a fresh kernel load.
### Step 7 — Kernel Configuration (Optional)
**Menu:** `7 Kernel`
```
stable Install linux-image-amd64 (Stable)
backports Install from backports (Trixie only)
rt Install linux-image-rt-amd64 (Preempt-RT)
cloud Install linux-image-cloud-amd64
back Return to main menu
```
- **Stable** — default Debian kernel (6.12 LTS on Trixie).
- **Backports** — only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
- **RT** — Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
- **Cloud** — minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
Each variant installs the matching `linux-headers-*` package atomically (`sudo apt install -y [-t trixie-backports] linux-image-* linux-headers-*`). The script warns about DKMS recompilation if NVIDIA is present.
> **Screenshot placeholder:** `media/screenshots/07-kernel.png` — Kernel menu with four variants.
> See [kernel.md](kernel.md) for backports rationale and bootloader details.
### Step 8 — Gaming Setup (Optional)
**Menu:** `8 Gaming Setup`
A single checklist with all options:
```
[*] i386 Enable 32-bit (i386) architecture
[*] steam Steam (requires 32-bit support)
[*] mangohud Performance overlay (Vulkan/OpenGL)
[ ] gamemode Game performance optimization
[*] goverlay MangoHud config GUI
[ ] heroic Heroic Launcher (Epic/GOG)
[ ] java Minecraft Java Runtime
[ ] openrgb OpenRGB (RGB lighting control)
[ ] lutris Lutris + Wine (requires 32-bit support)
[ ] retroarch RetroArch Emulator Frontend
```
- If `steam`, `lutris`, or `i386` is checked, the script runs `dpkg --add-architecture i386` + `apt update`, then installs 32-bit graphics libraries (`_install_nvidia_32bit` or `_install_mesa_32bit`).
- `steam` checks `contrib` (`ensure_contrib_repo`) and installs `steam-installer`.
- `heroic` fetches the latest `.deb` from GitHub releases (`api.github.com`).
- `openrgb` is Bookworm/Trixie only; handles `i2c-dev`, udev, `i2c` group, and `setcap`.
- `java` offers Temurin 8 / 17 / 21 / 25 via `extrepo adoptium`.
- Requires GUI for some installers (skipped on headless).
> **Screenshot placeholder:** `media/screenshots/08-gaming.png` — Gaming checklist with i386 + Steam + MangoHud checked.
> See [gaming.md](gaming.md) and [retroarch.md](retroarch.md).
### Step 9 — ZRAM Compressed Swap (Optional)
**Menu:** `9 ZRAM`
```
1 View ZRAM status
2 Create / Reconfigure ZRAM
3 Remove ZRAM
4 Back to main menu
```
- **View** — Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
- **Create / Reconfigure** — Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
- **Remove** — `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
> **Screenshot placeholder:** `media/screenshots/09-zram-algo.png` — Algorithm choice (lz4 vs zstd).
> **Screenshot placeholder:** `media/screenshots/09b-zram-status.png` — `zramctl` status output in whiptail.
> See [zram.md](zram.md).
### Step 10 — Swap Management (Optional)
**Menu:** `10 Swap Management`
```
1 Show current swap & swappiness
2 Create / resize swapfile
3 Remove swapfile
4 Change swappiness
5 Back to main menu
```
- Uses `/swapfile` with `pri=10` (below ZRAM's 100) and tag `# debianito-managed-swap` in `/etc/fstab`.
- Btrfs: warns about `nodatacow` (`chattr +C`) and hibernation limitations; uses `dd` instead of `fallocate`.
- Fstab is written via a temp file and validated with `findmnt --verify` before replacing `/etc/fstab`.
- Concurrency is guarded by `flock /run/lock/debianito-swap.lock`.
> **Screenshot placeholder:** `media/screenshots/10-swap.png` — Swap Management menu.
> See [swap.md](swap.md).
### Step 11 — Essential Software
**Menu:** `11 Install Programs and Software` → `0 Essential Pack`
One-click install of `htop`, `inxi`, `neofetch`/`fastfetch`, `vlc`, `ufw`, `zip`, `unrar`, `p7zip`, plus `lsb-release` fixes.
After this, browse the other categories as needed:
| Category | Example Packages |
| ---------- | ------------------ |
| Customization System | Desktop themes, icons, cursors, fonts |
| Download & Network | aria2, ytdlp, qBittorrent, Deluge |
| Internet | Firefox, LibreWolf, Chromium, Tor, Thunderbird, RiseUp/Mullvad VPN |
| Communication | Signal, Telegram, HexChat |
| Media Players | VLC, MPV |
| Multimedia & Design | GIMP, Kdenlive, Blender, Audacity, Inkscape |
| Code Editors & IDEs | Neovim, Helix, Emacs, VSCodium, Geany |
| Servers & Dev Tools | Nginx, PostgreSQL, Docker, Temurin JDK, Jellyfin |
| Security & Networking | Wireshark, ClamAV, UFW, fail2ban |
| Software Center & Flatpak | GNOME Software, KDE Discover, Flatpak |
| Office & Productivity | LibreOffice, document tools |
| System Tools | htop/btop, Timeshift, extension-manager, virt-manager |
| Fetch / System Info | fastfetch, neofetch, hyfetch, screenfetch |
> **Screenshot placeholder:** `media/screenshots/11-essentials.png` — Category menu with 0-14 options.
> **Screenshot placeholder:** `media/screenshots/11b-essential-pack.png` — Essential Pack confirmation.
### Step 12 — Boot Rescue
**Menu:** `12 Boot Rescue + GRUB`
- **GRUB boot menu settings** — 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
- **UEFI Secure Boot repair** — reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
- **Initramfs regeneration** — `update-initramfs -u -k all || true`.
> See [boot.md](boot.md).
### Step 13 — Desktop & Display
**Menu:** `13 Desktop & Display`
```
1 Desktop Environment
2 Display Manager
3 Back to main menu
```
- **Desktop Environment** — XFCE (full / minimal / Wayland `labwc` on Trixie / custom checklist) or LXDE (full / core). Installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group.
- **Display Manager** — LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet — manual `/etc/greetd/config.toml` required).
> See [desktops_display.md](desktops_display.md).
---
## After the Script
1. **Reboot** if you installed firmware, GPU drivers, or a new kernel.
2. Verify:
```bash
sudo zramctl # ZRAM active?
sudo swapon --show # Swap with correct priorities?
vainfo # VA-API acceleration?
nvidia-smi # NVIDIA driver loaded?
systemctl status bluetooth # Bluetooth active?
```
3. For gaming, enable `i386` was handled — verify with `dpkg --print-foreign-architectures | grep i386`.
---
## Troubleshooting Quick Answers
| Symptom | Fix |
| --------- | ----- |
| **WiFi not working after firmware** | Reboot. Check `lspci -nn \| grep Network` and verify the package (`firmware-iwlwifi` etc.) is `ii` via `dpkg -l`. Ensure `non-free` + `non-free-firmware` were enabled in Step 4. |
| **Black screen after NVIDIA + Wayland (GNOME/GDM3)** | At login, select *GNOME on Xorg* (gear icon) or disable Wayland: `sudo nano /etc/gdm3/daemon.conf` → `WaylandEnable=false`. The script only warns about Debian bug #1109409, it does not force X11. |
| **GRUB menu hidden and cannot enter** | Hold `ESC` immediately after power-on. Or boot a live USB, `chroot`, and run `12 Boot Rescue → GRUB boot menu settings → Show 5 seconds`. |
| **Steam fails to start** | Verify `i386` is enabled: `dpkg --print-foreign-architectures`. Check `contrib` is in `/etc/apt/sources.list`. Re-run `8 Gaming Setup` and ensure the checklist had `i386` + `steam` checked. |
| **greetd installed but cannot log in** | This is expected — you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
| **Bluetooth tray icon missing** | Reboot or `systemctl restart bluetooth`. Ensure `bluez`, `bluedevil` (KDE) or `blueman` (XFCE) is installed. For PipeWire, check `systemctl --user status pipewire pipewire-pulse wireplumber`. |
| **PipeWire crackling / no Bluetooth Hi-Res codec** | Re-run `3 System Preferences → Audio & Sound → PipeWire Audio Stack`. Verify `libldacbt-*`, `libopenaptx0`, `libfdk-aac2t64` are installed (`dpkg -l \| grep -E 'ldac\|aptx\|fdk'`). |
---
## Taking Screenshots for This Guide
Screenshots are taken from `whiptail` dialogs. To capture them:
1. Run the script inside a terminal that supports image export (e.g., `gnome-terminal` + `gnome-screenshot`, or `asciinema`).
2. For whiptail, press `PrintScreen` or use `import -window root screenshot.png` (ImageMagick).
3. Save under `media/screenshots/` with the filenames referenced above (`01-system-info.png`, `04-repos.png`, etc.).
4. Keep width ≈ 800px; the script uses fixed `TUI_ANCHO=78` and `TUI_ALTO=20` centered dialogs.
> **Note:** Until real screenshots are added, the placeholders above describe the expected content of each image.
docs/boot.md
+7 -7
View File
@@ -2,11 +2,11 @@
### 1. What does this component do? ### 1. What does this component do?
This component serves as a comprehensive rescue toolkit designed to diagnose and fix boot-related issues on Debian systems, specifically targeting GRUB configuration, UEFI Secure Boot integrity, and initrd image validity. It provides three primary operations: configuring the GRUB boot menu behavior (including timeout adjustments and visibility settings), repairing UEFI Secure Boot by reinstalling signed bootloader packages after kernel or driver changes, and regenerating initramfs images to resolve missing driver errors. All modifications are protected by automatic backup creation before system files are altered, with built-in rollback mechanisms that restore the original state if any operation fails during execution. This component diagnoses and fixes boot-related problems on Debian: GRUB configuration, UEFI Secure Boot integrity and initrd image validity. It performs three operations: configuring the GRUB boot menu (timeout and visibility settings), repairing UEFI Secure Boot by reinstalling signed bootloader packages after kernel or driver changes, and regenerating initramfs images to fix missing driver errors. Every modification starts with a timestamped backup, and a failed operation rolls back to the original state.
### 2. Logical Execution Flow ### 2. Logical Execution Flow
**Block 1 — GRUB Boot Menu Settings** **Block 1: GRUB Boot Menu Settings**
- **Menu Options:** Users select from four presets or a custom option to control boot behavior: - **Menu Options:** Users select from four presets or a custom option to control boot behavior:
1. Hide GRUB menu entirely (Fastest boot, requires holding ESC during power-on). 1. Hide GRUB menu entirely (Fastest boot, requires holding ESC during power-on).
@@ -17,7 +17,7 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
- **Backup & Safety:** Before applying changes, the script creates a timestamped backup of `/etc/default/grub`. It writes an override configuration file at `/etc/default/grub.d/99_script_override.cfg` to ensure settings persist across updates. - **Backup & Safety:** Before applying changes, the script creates a timestamped backup of `/etc/default/grub`. It writes an override configuration file at `/etc/default/grub.d/99_script_override.cfg` to ensure settings persist across updates.
- **Execution & Rollback:** The system runs `update-grub` to apply changes. If this command fails, the script automatically restores the timestamped backup and removes the override file to prevent boot issues. - **Execution & Rollback:** The system runs `update-grub` to apply changes. If this command fails, the script automatically restores the timestamped backup and removes the override file to prevent boot issues.
**Block 2 — UEFI Secure Boot Repair** **Block 2: UEFI Secure Boot Repair**
- **Pre-checks:** Before proceeding, the script verifies two conditions: - **Pre-checks:** Before proceeding, the script verifies two conditions:
1. The system is running in UEFI mode (checks for existence of `/sys/firmware/efi`). 1. The system is running in UEFI mode (checks for existence of `/sys/firmware/efi`).
@@ -28,15 +28,15 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
2. Reinstalls GRUB to the EFI partition using `grub-install` with the appropriate target and directory detection (preferring `/boot/efi` over `/boot`). 2. Reinstalls GRUB to the EFI partition using `grub-install` with the appropriate target and directory detection (preferring `/boot/efi` over `/boot`).
3. Regenerates the GRUB configuration via `update-grub`. 3. Regenerates the GRUB configuration via `update-grub`.
**Block 3 — Initramfs Regeneration** **Block 3: Initramfs Regeneration**
- **Confirmation:** The script prompts for user confirmation before proceeding to avoid unintended rebuilds. - **Confirmation:** The script prompts for user confirmation before proceeding to avoid unintended rebuilds.
- **Execution:** Upon approval, it runs `update-initramfs -u -k all || true` to regenerate initrd images for all installed kernels. - **Execution:** Upon approval, it runs `update-initramfs -u -k all || true` to regenerate initrd images for all installed kernels.
- **Purpose:** This fixes boot issues caused by missing drivers or corrupted initrd images that prevent the system from loading properly. - **Purpose:** This fixes boot issues caused by missing drivers or corrupted initrd images that prevent the system from loading properly.
### 3. Intelligent Automation ### 3. Safeguards and Automation
- **EFI Directory Detection:** The script intelligently detects the EFI partition, checking `/boot/efi` first and falling back to `/boot` if necessary. - **EFI Directory Detection:** The script detects the EFI partition, checking `/boot/efi` first and falling back to `/boot` if necessary.
- **Secure Boot State Verification:** Instead of assuming Secure Boot is active, it uses `mokutil --sb-state` to verify the actual state before attempting repairs on non-UEFI or disabled systems. - **Secure Boot State Verification:** Instead of assuming Secure Boot is active, it uses `mokutil --sb-state` to verify the actual state before attempting repairs on non-UEFI or disabled systems.
- **GRUB Backup Strategy:** A timestamped backup file (e.g., `/etc/default/grub.backup.YYYYMMDD_HHMMSS`) is created prior to any modification, ensuring a safe point for rollback. - **GRUB Backup Strategy:** A timestamped backup file (e.g., `/etc/default/grub.backup.YYYYMMDD_HHMMSS`) is created prior to any modification, ensuring a safe point for rollback.
- **Rollback Mechanism:** If `update-grub` fails during the GRUB settings or Secure Boot repair process, the script automatically restores the backup and cleans up temporary override files. - **Rollback Mechanism:** If `update-grub` fails during the GRUB settings or Secure Boot repair process, the script automatically restores the backup and cleans up temporary override files.
@@ -44,7 +44,7 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
- **Input Validation:** Custom timeout inputs are validated using regex matching for integers (e.g., `^-?[0-9]+$`), allowing negative numbers like -1 while rejecting invalid text. - **Input Validation:** Custom timeout inputs are validated using regex matching for integers (e.g., `^-?[0-9]+$`), allowing negative numbers like -1 while rejecting invalid text.
- **Variable Handling Logic:** The `_set_grub_var()` function handles three distinct cases: updating an existing variable, uncommenting a commented variable, or appending a new variable if it does not exist in the configuration file. - **Variable Handling Logic:** The `_set_grub_var()` function handles three distinct cases: updating an existing variable, uncommenting a commented variable, or appending a new variable if it does not exist in the configuration file.
### 4. Paquetes y Recursos Gestionados ### 4. Managed Packages and Resources
**Boot Packages Reinstalled (Secure Boot Repair):** **Boot Packages Reinstalled (Secure Boot Repair):**
docs/desktops_display.md
+12 -12
View File
@@ -10,16 +10,16 @@ This component manages both desktop environments and display managers. Desktop E
The execution logic is divided into five functional blocks: The execution logic is divided into five functional blocks:
**Block 1 — Desktop Environment Selection & Installation** **Block 1: Desktop Environment Selection & Installation**
- The main menu (`manage_desktop_display` in `desktop_display.sh`) offers two primary options: `1 Desktop Environment` and `2 Display Manager` (plus `3 Back to main menu`). - The main menu (`manage_desktop_display` in `desktop_display.sh`) offers two primary options: `1 Desktop Environment` and `2 Display Manager` (plus `3 Back to main menu`).
- **Desktop Environment** opens `desktop_environment_menu` with four environments: - **Desktop Environment** opens `desktop_environment_menu` with four environments:
1. **XFCE** — full / minimal / Wayland (`labwc`, Debian 13 only) / custom package checklist. 1. **XFCE**: full / minimal / Wayland (`labwc`, Debian 13 only) / custom package checklist.
2. **LXDE** — full / core. 2. **LXDE**: full / core.
3. **GNOME** — full (`gnome`) / core (`gnome-core`), with GDM3. 3. **GNOME**: full (`gnome`) / core (`gnome-core`), with GDM3.
4. **KDE Plasma** — full (`kde-standard`) / minimal (`kde-plasma-desktop`), with SDDM. 4. **KDE Plasma**: full (`kde-standard`) / minimal (`kde-plasma-desktop`), with SDDM.
- Each environment lives in its own module under `modules/desktops/` and is lazy-loaded from the menu dispatch with `_load_module xfce|lxde|gnome|kde` (dependencies: `desktop_display` + `audio`). - Each environment lives in its own module under `modules/desktops/` and is lazy-loaded from the menu dispatch with `_load_module xfce|lxde|gnome|kde` (dependencies: `desktop_display` + `audio`).
- **Display Manager** opens `display_manager_menu` — LightDM, GDM3, SDDM, and greetd (12/13 only). - **Display Manager** opens `display_manager_menu`: LightDM, GDM3, SDDM, and greetd (12/13 only).
- **Available Managers:** - **Available Managers:**
- LightDM (available on all Debian versions). - LightDM (available on all Debian versions).
- GDM3 (available on all Debian versions). - GDM3 (available on all Debian versions).
@@ -27,7 +27,7 @@ The execution logic is divided into five functional blocks:
- greetd (available only on Debian 12 and 13). - greetd (available only on Debian 12 and 13).
- Each selected manager opens its own dedicated configuration submenu. - Each selected manager opens its own dedicated configuration submenu.
**Block 2 — LightDM Configuration** **Block 2: LightDM Configuration**
- A checklist menu presents three options: - A checklist menu presents three options:
1. Install LightDM + GTK Greeter (auto-selects the display manager via debconf-set-selections). 1. Install LightDM + GTK Greeter (auto-selects the display manager via debconf-set-selections).
@@ -35,7 +35,7 @@ The execution logic is divided into five functional blocks:
3. Enable autologin for current user (uncomments `autologin-user` and sets timeout to 0 in the main config). 3. Enable autologin for current user (uncomments `autologin-user` and sets timeout to 0 in the main config).
- **Idempotency:** The script checks if `lightdm` and `lightdm-gtk-greeter-settings` are already installed before attempting installation, skipping redundant steps. - **Idempotency:** The script checks if `lightdm` and `lightdm-gtk-greeter-settings` are already installed before attempting installation, skipping redundant steps.
**Block 3 — GDM3 Configuration** **Block 3: GDM3 Configuration**
- A checklist menu presents up to four options: - A checklist menu presents up to four options:
1. Install/Reinstall gdm3 (auto-selects via debconf). 1. Install/Reinstall gdm3 (auto-selects via debconf).
@@ -47,7 +47,7 @@ The execution logic is divided into five functional blocks:
- **Risk Warning:** Displays a warning that this may break graphics or cause instability. - **Risk Warning:** Displays a warning that this may break graphics or cause instability.
- **Toggle Behavior:** If the symlink exists, removing it reverts to default behavior; if not present, creating it enables the override. - **Toggle Behavior:** If the symlink exists, removing it reverts to default behavior; if not present, creating it enables the override.
**Block 4 — SDDM Configuration** **Block 4: SDDM Configuration**
- A submenu offers two options: - A submenu offers two options:
1. Install SDDM (auto-selects via debconf). 1. Install SDDM (auto-selects via debconf).
@@ -56,7 +56,7 @@ The execution logic is divided into five functional blocks:
- **Configuration:** Writes autologin settings to `/etc/sddm.conf.d/autologin.conf`. - **Configuration:** Writes autologin settings to `/etc/sddm.conf.d/autologin.conf`.
- **Fallback:** If no session is found, it enables autologin but warns that SDDM will use the default session. - **Fallback:** If no session is found, it enables autologin but warns that SDDM will use the default session.
**Block 5 — greetd Configuration** **Block 5: greetd Configuration**
- greetd is a minimal, modern display manager designed for Wayland environments. - greetd is a minimal, modern display manager designed for Wayland environments.
- Submenu options vary by Debian version: - Submenu options vary by Debian version:
@@ -65,9 +65,9 @@ The execution logic is divided into five functional blocks:
- **Backports Handling:** On Bookworm, `tuigreet` is installed from backports if not enabled. - **Backports Handling:** On Bookworm, `tuigreet` is installed from backports if not enabled.
- **Important Warning:** greetd is installed but NOT configured by the script. The user must manually create `/etc/greetd/config.toml` to be able to log in. The script displays a warning with references to man pages for configuration details. - **Important Warning:** greetd is installed but NOT configured by the script. The user must manually create `/etc/greetd/config.toml` to be able to log in. The script displays a warning with references to man pages for configuration details.
### 3. Smart Automations ### 3. Automations
The component utilizes several intelligent automation features: The component automates several steps:
- **debconf-set-selections:** Pre-selects the display manager as default before `apt install`, preventing the interactive "Configuring shared/default-x-display-manager" dialog that would otherwise pause the script execution. - **debconf-set-selections:** Pre-selects the display manager as default before `apt install`, preventing the interactive "Configuring shared/default-x-display-manager" dialog that would otherwise pause the script execution.
- **Session Auto-Detection (SDDM):** Checks `.desktop` files in priority order (Wayland first, then X11) to set the correct session type for autologin configuration. - **Session Auto-Detection (SDDM):** Checks `.desktop` files in priority order (Wayland first, then X11) to set the correct session type for autologin configuration.
docs/firmware.md
+24 -24
View File
@@ -1,22 +1,22 @@
# Option 5: Firmware, Wireless & Bluetooth # Option 5: Firmware, Wireless & Bluetooth
## 1. The Hidden Debian "Problem" ## 1. What the Debian Package Misses
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). In standard Debian packaging, the meta-package `firmware-linux-nonfree` collects hardware blobs from many sources. Its dependency rules and conservative versioning mean it often misses vendor-specific firmware for newer or niche network controllers (Realtek Wi-Fi/Bluetooth and Intel Ethernet/Wi-Fi variants in particular).
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. This script fills that gap. It scans the hardware itself instead of trusting the meta-package's `Recommends` field: detection is separate from installation, so a specific blob (e.g., `firmware-iwlwifi`, `firmware-realtek`) is pulled in only when its hardware ID is present, even if the base package is already installed. The result is no network interface that appears but cannot initialize because its firmware is missing.
## 2. Dual Scan Engine (PCI & USB) ## 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: The script scans both the PCI and USB buses with strict filters, which catches more hardware while keeping false positives low:
* **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. * **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), so Ethernet firmware needs are covered too.
* **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`. * **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. * **Deduplication:** The collected device lists are merged into a single array (`dev_list`) so the same hardware is not processed twice across bus categories and the plan stays clean.
## 3. Dynamic Hardware Mapping Matrix ## 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: 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 mapping handles 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. * **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:** * **Package Assignment Logic:**
@@ -26,26 +26,26 @@ The script employs an associative mapping strategy in `_detect_firmware_needs` t
* **MediaTek / Ralink Hardware** ➔ `firmware-mediatek`. * **MediaTek / Ralink Hardware** ➔ `firmware-mediatek`.
* **Atheros / Qualcomm Hardware** ➔ `firmware-atheros`. * **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. So a system with an Intel Wi-Fi 6 card gets `firmware-iwlwifi` queued explicitly, whether or not 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) ## 4. Installation Execution Flow (Atomic Pipeline)
The installation process follows a strict atomic pipeline defined in `install_firmware`, ensuring system stability and version consistency: The installation runs through the atomic pipeline in `install_firmware`:
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. 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. 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):** 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 `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). * If not installed, it presents a choice between Stable (thoroughly 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. 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 Wireless Support (DKMS Single-Path) ## 5. Broadcom Wireless Support (DKMS Single-Path)
Broadcom chipsets require proprietary handling because no open-source driver covers most `14e4:*` devices on modern kernels. The current implementation in `firmware.sh:_handle_wireless` uses a **single-path DKMS flow** (`broadcom-sta-dkms` + `wl` module) — not a 3-tier fallback: Broadcom chipsets require proprietary handling because no open-source driver covers most `14e4:*` devices on modern kernels. The current implementation in `firmware.sh:_handle_wireless` uses a **single-path DKMS flow** (`broadcom-sta-dkms` + `wl` module) instead of a 3-tier fallback:
1. **Device detection** — Iterates `PCI_NET_DEVS` (parsed from `lspci -nn` by the on-demand detection battery) and extracts the Broadcom ID `14e4:XXXX`. Non-Broadcom devices are skipped. 1. **Device detection**: Iterates `PCI_NET_DEVS` (parsed from `lspci -nn` by the on-demand detection battery) and extracts the Broadcom ID `14e4:XXXX`. Non-Broadcom devices are skipped.
2. **Dependency guard** — Verifies `linux-headers-amd64` and `dkms` are available via `apt-cache show`. If missing, shows: `"linux-headers-amd64 or dkms are not available in your repositories."` 2. **Dependency guard**: Verifies `linux-headers-amd64` and `dkms` are available via `apt-cache show`. If missing, shows: `"linux-headers-amd64 or dkms are not available in your repositories."`
3. **User confirmation** — `whiptail --yesno "Install broadcom-sta-dkms, dkms, and wireless-tools?"` 3. **User confirmation**: `whiptail --yesno "Install broadcom-sta-dkms, dkms, and wireless-tools?"`
4. **Step-by-step install** (allows partial failure without aborting the whole module): 4. **Step-by-step install** (allows partial failure without aborting the whole module):
```bash ```bash
@@ -53,7 +53,7 @@ Broadcom chipsets require proprietary handling because no open-source driver cov
_run_cmd "Broadcom Driver" "sudo DEBIAN_FRONTEND=noninteractive apt install -y broadcom-sta-dkms" || true _run_cmd "Broadcom Driver" "sudo DEBIAN_FRONTEND=noninteractive apt install -y broadcom-sta-dkms" || true
``` ```
5. **Blacklist persistence** — Writes `/etc/modprobe.d/blacklist-broadcom.conf`: 5. **Blacklist persistence**: Writes `/etc/modprobe.d/blacklist-broadcom.conf`:
``` ```
blacklist b43 blacklist b43
@@ -63,7 +63,7 @@ Broadcom chipsets require proprietary handling because no open-source driver cov
blacklist ssb blacklist ssb
``` ```
6. **SSH Warning + Module Switch** — Before unloading current WiFi modules, the script warns about SSH disconnection. Then removes conflicting modules and loads the Broadcom driver: 6. **SSH Warning + Module Switch**: Before unloading current WiFi modules, the script warns about SSH disconnection. Then removes conflicting modules and loads the Broadcom driver:
```bash ```bash
_msg "Network Warning" "The script is about to unload current WiFi kernel modules to load the Broadcom driver. _msg "Network Warning" "The script is about to unload current WiFi kernel modules to load the Broadcom driver.
@@ -74,30 +74,30 @@ If you are connected via SSH over WiFi, YOUR CONNECTION WILL DROP. Please reconn
``` ```
7. **Initramfs** — Rebuilds the initramfs to include the new `wl` module: 7. **Initramfs**: Rebuilds the initramfs to include the new `wl` module:
```bash ```bash
_run_cmd "Initramfs" "sudo update-initramfs -u" || true _run_cmd "Initramfs" "sudo update-initramfs -u" || true
``` ```
1. **Combo BT handling** — If a Broadcom Bluetooth device is also present (`PCI_BT_DEVS` grep `broadcom`), writes `softdep wl post: btusb` to `/etc/modprobe.d/broadcom-combo.conf` 1. **Combo BT handling**: If a Broadcom Bluetooth device is also present (`PCI_BT_DEVS` grep `broadcom`), writes `softdep wl post: btusb` to `/etc/modprobe.d/broadcom-combo.conf`
2. **Post-DKMS verification** — Checks for `/lib/modules/$(uname -r)/updates/dkms/wl.ko*`. If missing, shows the last 20 lines of `dmesg` and offers `dpkg-reconfigure broadcom-sta-dkms`. On success, verifies `lsmod | grep ^wl` and reports `Broadcom WiFi activated (wl module loaded)` or `driver installed but wl module did not load — reboot required`. 2. **Post-DKMS verification**: Checks for `/lib/modules/$(uname -r)/updates/dkms/wl.ko*`. If missing, shows the last 20 lines of `dmesg` and offers `dpkg-reconfigure broadcom-sta-dkms`. On success, verifies `lsmod | grep ^wl` and reports `Broadcom WiFi activated (wl module loaded)` or `driver installed but wl module did not load — reboot required`.
USB Broadcom (`0a5c` vendor, `lsusb`) is detected but **not auto-installed** — the script shows a message that Linux lacks native drivers for most USB Broadcom WiFi chips and that `ndiswrapper` may be needed. USB Broadcom (`0a5c` vendor, `lsusb`) is detected but **not auto-installed**: the script shows a message that Linux lacks native drivers for most USB Broadcom WiFi chips and that `ndiswrapper` may be needed.
> **Historical note:** Earlier drafts of this document described a 3-tier system (`firmware-brcm80211` → `firmware-b43-installer` → `broadcom-sta-dkms`). The current script has consolidated to the DKMS path only. The other firmware packages are still available via the base `firmware-linux-nonfree` metapackage and vendor-specific packages (`firmware-realtek`, etc.). > **Historical note:** Earlier drafts of this document described a 3-tier system (`firmware-brcm80211` → `firmware-b43-installer` → `broadcom-sta-dkms`). The current script has consolidated to the DKMS path only. The other firmware packages are still available via the base `firmware-linux-nonfree` metapackage and vendor-specific packages (`firmware-realtek`, etc.).
## 6. Bluetooth Stack Integration ## 6. Bluetooth Stack Integration
Bluetooth support is handled through a dedicated module (`bluetooth.sh`) that integrates seamlessly with the firmware detection process: Bluetooth support is handled through a dedicated module (`bluetooth.sh`) that reuses the firmware module's device detection:
* **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. * **Hardware Detection:** The script identifies both PCI and USB Bluetooth controllers via the `PCI_BT_DEVS` and `USB_BT_DEVS` arrays, covering 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. * **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: * **Desktop Environment Optimization:** Based on the detected desktop environment:
* **KDE:** Installs `bluedevil` and optionally `pipewire-pulse` + `wireplumber` for Pipewire audio server integration. * **KDE:** Installs `bluedevil` and optionally `pipewire-pulse` + `wireplumber` for Pipewire audio server integration.
* **GNOME:** Uses built-in GNOME Bluetooth support in `gnome-control-center`. * **GNOME:** Uses built-in GNOME Bluetooth support in `gnome-control-center`.
* **XFCE/Other:** Installs `blueman` as the GTK Bluetooth manager. * **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. * **Service Management:** The script enables and starts the Bluetooth service on boot, and recommends a session restart or reboot so desktop applets 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. Bluetooth handling stays separate from network firmware; both share the same device detection arrays.
docs/gaming.md
+10 -10
View File
@@ -2,9 +2,9 @@
### 1. Philosophy of the Gaming Environment in Debian ### 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: The Debianito gaming module turns a plain Debian installation into a gaming station. It isolates the gaming dependencies from the base system and configures the compatibility layers without putting system stability at risk. The design 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. **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. **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.
@@ -16,7 +16,7 @@ The module architecture separates concerns into distinct scripts (`steam.sh`, `h
### 2. Launchers and Compatibility Layers (Steam & Heroic) ### 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: **Steam Installation Logic:** The `install_steam()` function in `steam.sh` uses 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: 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:
@@ -25,7 +25,7 @@ The module architecture separates concerns into distinct scripts (`steam.sh`, `h
libgl1-mesa-dri:i386 libegl-mesa0:i386 mesa-va-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: 2. **Runtime Dependency Chain:** The `steam-installer` package depends on several components:
- `debconf` and `cdebconf` for configuration management - `debconf` and `cdebconf` for configuration management
- `default-dbus-session-bus` for inter-process communication - `default-dbus-session-bus` for inter-process communication
- `lsof` for file listing utilities - `lsof` for file listing utilities
@@ -52,7 +52,7 @@ This approach ensures users always get the latest stable release while maintaini
### 3. Optimization Engine and Telemetry (GameMode & MangoHud) ### 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: **Feral GameMode Daemon:** When a game launches with `gamemoderun`, the Feral GameMode daemon performs several optimizations at the kernel level:
1. **CPU Scheduler Priority:** Adjusts scheduling policies to prioritize gaming processes over background tasks, reducing latency spikes during gameplay 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) 2. **I/O Priority Management:** Increases I/O priority for game processes while deprioritizing non-essential system operations (updates, backups)
@@ -83,7 +83,7 @@ if dpkg --print-foreign-architectures | grep -q i386; then
fi 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. The `goverlay` component extends this functionality by integrating with Wayland compositors for smoother overlay behavior on modern desktop environments. The two tools need no game-specific configuration.
--- ---
@@ -121,19 +121,19 @@ This approach eliminates the security risk of running OpenRGB as root while main
| **Temurin 21** | Latest game engines, cutting-edge mods | Provides best performance for modern Java applications | | **Temurin 21** | Latest game engines, cutting-edge mods | Provides best performance for modern Java applications |
| **Temurin 25** | Minecraft 26+ and latest game engines | Best performance for the newest Java applications | | **Temurin 25** | Minecraft 26+ and latest game engines | Best performance for the newest Java applications |
**Repository Management via extrepo:** The script leverages the `extrepo` utility to manage external repositories cleanly rather than manually injecting repository URLs into system files. This approach offers several advantages: **Repository Management via extrepo:** The script uses the `extrepo` utility to manage external repositories instead of injecting repository URLs into system files by hand. This approach offers several advantages:
1. **Automated Keyring Handling:** `extrepo` manages GPG keys and source file configurations automatically, eliminating manual intervention with `/etc/apt/sources.list.d/`. 1. **Automated Keyring Handling:** `extrepo` manages GPG keys and source file configurations automatically, eliminating manual intervention with `/etc/apt/sources.list.d/`.
2. **Dependency Resolution:** The utility checks for its own installation and handles the enabling of the Adoptium Temurin repository before proceeding with package installation. 2. **Dependency Resolution:** The utility checks for its own installation and handles the enabling of the Adoptium Temurin repository before proceeding with package installation.
3. **Maintenance Safety:** Updates to the upstream repository are reflected through `extrepo` without requiring direct edits to system configuration files, reducing the risk of breakage during OS updates. 3. **Maintenance Safety:** Updates to the upstream repository are reflected through `extrepo` without requiring direct edits to system configuration files, reducing the risk of breakage during OS updates.
**Version Selection Logic:** Users can choose which Temurin version to install based on their specific game requirements via a TUI menu (`install_minecraft_java()`). The module justifies offering all four versions because: **Version Selection Logic:** Users can choose which Temurin version to install based on their specific game requirements via a TUI menu (`install_minecraft_java()`). The module offers all four 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 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 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 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. It automatically installs `extrepo` if not present and enables the Adoptium source before proceeding with version-specific packages (e.g., `temurin-8-jre`, `temurin-17-jre`, `temurin-25-jre`). The install avoids multiple conflicting JRE installations. It installs `extrepo` if it is missing, enables the Adoptium source and then installs the chosen packages (e.g., `temurin-8-jre`, `temurin-17-jre`, `temurin-25-jre`).
### References ### References
@@ -147,4 +147,4 @@ The installation process ensures clean repository management without polluting t
- [https://github.com/flightlessmango/Mangohud](https://github.com/flightlessmango/Mangohud) - [https://github.com/flightlessmango/Mangohud](https://github.com/flightlessmango/Mangohud)
- [https://github.com/feralinteractive/gamemode](https://github.com/feralinteractive/gamemode) - [https://github.com/feralinteractive/gamemode](https://github.com/feralinteractive/gamemode)
- [https://gitlab.com/CalcProgrammer1/OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB) - [https://gitlab.com/CalcProgrammer1/OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB)
- [https://adoptium.net/es/installation/linux](https://adoptium.net/es/installation/linux) - [https://adoptium.net/en/installation/linux](https://adoptium.net/en/installation/linux)
docs/gpu.md
+20 -20
View File
@@ -2,19 +2,19 @@
### 1. Philosophy of the Graphics Stack (Open-Source vs. Proprietary) ### 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: The `debianito` script prefers the open-source drivers that ship with the Linux kernel and injects proprietary ones only where performance or legacy support requires it. The work is split across three 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`). 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. 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. 3. **Firmware & Microcode**: A 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. Users on Debian Stable get compatibility by default, while advanced users can opt into backports kernels or the NVIDIA enterprise repository without breaking the base system.
--- ---
### 2. The Automatic GPU Detection Pipeline ### 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. The script runs a pre-flight detection sequence defined in `utils.sh` and executed in `gpu.sh`. It categorizes the hardware before showing installation options, so the user answers fewer questions.
**Detection Flow:** **Detection Flow:**
@@ -40,7 +40,7 @@ The script utilizes a robust pre-flight detection sequence defined in `utils.sh`
* Install Intel firmware/drivers first to ensure the base display server works. * Install Intel firmware/drivers first to ensure the base display server works.
* Install NVIDIA drivers second, configuring them for PRIME offloading if detected. * 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. This detect-then-deploy order keeps users from installing unnecessary drivers (e.g., `i965` on an RTX 4090) and puts the firmware in place before drivers are installed.
--- ---
@@ -123,14 +123,14 @@ fi
The guard checks both `grep -q` (read-only) and `sudo grep -q` (with elevated permissions) to handle systems where `/etc/default/grub` requires root access. If the parameters are already present, the function exits early with a message rather than duplicating the entry. The guard checks both `grep -q` (read-only) and `sudo grep -q` (with elevated permissions) to handle systems where `/etc/default/grub` requires root access. If the parameters are already present, the function exits early with a message rather than duplicating the entry.
#### Additional notes & carifications #### Additional notes & clarifications
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. 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**: 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 `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`). * 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. * **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. 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 covers RDNA 4 as well as RDNA 3 and RDNA 3.5 architectures.
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. 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.
--- ---
@@ -161,7 +161,7 @@ Starting with Turing, NVIDIA introduced the **open kernel module**. From driver
| **Ada Lovelace**<br>*(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. | | **Ada Lovelace**<br>*(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**<br>*(GB100/102/202)* | [570.xx](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`. | | **Blackwell**<br>*(GB100/102/202)* | [570.xx](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 #### Quick context glossary
* **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. * **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). * **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).
@@ -187,14 +187,14 @@ When the script detects Intel or AMD hardware, it triggers a specific installati
| **Intel Gen 8+** | `i915` | `iris` / `anv` | Installs [`intel-media-va-driver-non-free`](https://github.com/intel/media-driver). Modern, preferred backend for Broadwell+. | | **Intel Gen 8+** | `i915` | `iris` / `anv` | Installs [`intel-media-va-driver-non-free`](https://github.com/intel/media-driver). 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. | | **AMD GCN/RDNA** | `amdgpu` | `radeonsi` (GL) + `RADV` (VK) | Uses standard `va-driver-all`. Requires kernel param tuning for older GCN. |
**Critical Consistency Check:** **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. 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** ### 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 the CUDA repository (production branches v590 / v595), and providing appropriate warnings for potential compatibility issues. The NVIDIA driver installation involves proprietary components, kernel version constraints, and DKMS (Dynamic Kernel Module Support) compilation. This section covers the choice between stable and backports kernels, Blackwell GPUs via the CUDA repository (production branches v590 / v595), and the warnings the script shows for compatibility issues.
#### **Kernel Compatibility** #### **Kernel Compatibility**
@@ -203,19 +203,19 @@ The NVIDIA driver installation process is inherently complex due to proprietary
#### **Blackwell Architecture & CUDA v590/v595 (Production Branches)** #### **Blackwell Architecture & CUDA v590/v595 (Production Branches)**
* **Detection**: `_helpers.sh` function `is_nvidia_blackwell()` identifies GPUs via PCI IDs `10de:24xx`, `0x2900–0x29BF`, and `0x2B80–0x31FF`. The same check gates both CUDA branches — Blackwell is unsupported by Debian stable regardless of the selected CUDA version. * **Detection**: `_helpers.sh` function `is_nvidia_blackwell()` identifies GPUs via PCI IDs `10de:24xx`, `0x2900–0x29BF`, and `0x2B80–0x31FF`. The same check gates both CUDA branches: Blackwell is unsupported by Debian stable regardless of the selected CUDA version.
* **Reason for v590/v595**: Debian 13 (Trixie) stable drivers only support up to v550, which lacks Blackwell (GB20x) architecture. The NVIDIA CUDA repository provides two production branches with unified driver packages: **v590**(current long-lived production, [590.48.01](https://download.nvidia.com/XFree86/Linux-x86_64/590.48.01/README/supportedchips.html)) and **v595** ([595.91.07](https://download.nvidia.com/XFree86/Linux-x86_64/595.91.07/README/supportedchips.html)newer production branch, same GB20x support with more recent fixes/features). Both branches expose the same unified metapackage and replace the need for a distro-packaged driver on Blackwell hardware. * **Reason for v590/v595**: Debian 13 (Trixie) stable drivers only support up to v550, which lacks Blackwell (GB20x) architecture. The NVIDIA CUDA repository provides two production branches with unified driver packages: **v590**(current long-lived production, [590.48.01](https://download.nvidia.com/XFree86/Linux-x86_64/590.48.01/README/supportedchips.html)) and **v595** ([595.91.07](https://download.nvidia.com/XFree86/Linux-x86_64/595.91.07/README/supportedchips.html)newer production branch, same GB20x support with more recent fixes/features). Both branches expose the same unified metapackage and replace the need for a distro-packaged driver on Blackwell hardware.
* **CUDA Repository Enablement**: On Debian 13 (Trixie) — the only release that exposes `590` and `595` (`_show_nvidia_version_menu` gates them behind `DEBIAN_VERSION == 13`) — the script enables the `nvidia-cuda` repository via `extrepo` (`sudo apt install -y extrepo` if missing, then `sudo extrepo enable nvidia-cuda`). After enabling, the script always runs an explicit `apt update`, then installs `nvidia-driver-pinning-<ver>` if available (official NVIDIA pinning, optional and version-specific for 590 vs 595), and finally installs the unified metapackage `nvidia-open` plus `firmware-nvidia-gsp` (pulled as a transitive dependency). No manual pinning file is written; if `apt install` fails, the real `apt` error is shown and the installation aborts. * **CUDA Repository Enablement**: On Debian 13 (Trixie), the only release that exposes `590` and `595` (`_show_nvidia_version_menu` gates them behind `DEBIAN_VERSION == 13`), the script enables the `nvidia-cuda` repository via `extrepo` (`sudo apt install -y extrepo` if missing, then `sudo extrepo enable nvidia-cuda`). After enabling, the script always runs an explicit `apt update`, then installs `nvidia-driver-pinning-<ver>` if available (official NVIDIA pinning, optional and version-specific for 590 vs 595), and finally installs the unified metapackage `nvidia-open` plus `firmware-nvidia-gsp` (pulled as a transitive dependency). No manual pinning file is written; if `apt install` fails, the real `apt` error is shown and the installation aborts.
#### **Installation Flow** #### **Installation Flow**
The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu.sh`): The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu.sh`):
1. **Plan** — `_msg` with detected GPUs, then `_pause`. 1. **Plan**: `_msg` with detected GPUs, then `_pause`.
2. **Manage menu** (`_nvidia_manage_menu`): "Install / Change NVIDIA Driver Version" or "Remove NVIDIA Driver and Restore Nouveau". 2. **Manage menu** (`_nvidia_manage_menu`): "Install / Change NVIDIA Driver Version" or "Remove NVIDIA Driver and Restore Nouveau".
3. **Version menu** (`_show_nvidia_version_menu`): Debian 12 → v535 (Recommended) / v470 (Kepler); Debian 13 → v550 (Recommended) / v590 / v595 (NVIDIA CUDA Repo). 3. **Version menu** (`_show_nvidia_version_menu`): Debian 12 → v535 (Recommended) / v470 (Kepler); Debian 13 → v550 (Recommended) / v590 / v595 (NVIDIA CUDA Repo).
4. **Dispatch by hardware**: Kepler → `nvidia-tesla-470-driver`; Fermi → veto with message; Turing+ → `_install_nvidia_standard` (Debian stable); Blackwell on Trixie → CUDA repo v590. 4. **Dispatch by hardware**: Kepler → `nvidia-tesla-470-driver`; Fermi → veto with message; Turing+ → `_install_nvidia_standard` (Debian stable); Blackwell on Trixie → CUDA repo v590.
5. **CUDA repo (590/595)**: two separate APT transactions — `nvidia-driver-pinning-<ver>` (version lock, mandatory) then `nvidia-open` (driver + open kernel modules, firmware via transitive dependency). 5. **CUDA repo (590/595)**: two separate APT transactions: `nvidia-driver-pinning-<ver>` (version lock, mandatory) then `nvidia-open` (driver + open kernel modules, firmware via transitive dependency).
6. **Secure Boot warning**: If Secure Boot is active (`mokutil --sb-state` reports `SecureBoot enabled`), the script displays a warning that the NVIDIA DKMS module is compiled but **NOT signed**. The user must sign the module with MOK or disable Secure Boot in BIOS before rebooting: 6. **Secure Boot warning**: If Secure Boot is active (`mokutil --sb-state` reports `SecureBoot enabled`), the script displays a warning that the NVIDIA DKMS module is compiled but **NOT signed**. The user must sign the module with MOK or disable Secure Boot in BIOS before rebooting:
``` ```
@@ -223,7 +223,7 @@ The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu
You MUST sign the module with MOK or disable Secure Boot in BIOS before rebooting. You MUST sign the module with MOK or disable Secure Boot in BIOS before rebooting.
``` ```
Installation continues — Secure Boot does not block DKMS compilation, but the module will fail to load until signed. Installation continues: Secure Boot does not block DKMS compilation, but the module will fail to load until signed.
7. **Post-install**: `/etc/modprobe.d/nvidia-wayland.conf` (written with `|| return 1` protection) + DKMS verification. 7. **Post-install**: `/etc/modprobe.d/nvidia-wayland.conf` (written with `|| return 1` protection) + DKMS verification.
> Note: Debian 12 (Bookworm) backports reached EOL (2026-08-09); the NVIDIA flow on Bookworm only uses the stable repository. > Note: Debian 12 (Bookworm) backports reached EOL (2026-08-09); the NVIDIA flow on Bookworm only uses the stable repository.
@@ -231,7 +231,7 @@ The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu
### 9.**NVIDIA Driver Compatibility Matrix** ### 9.**NVIDIA Driver Compatibility Matrix**
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: Depending on your GPU generation and your Debian ecosystem, you must select the appropriate legacy or current driver series. The table below lists the verified compatibility across Debian versions and GPU generations:
| Driver NVIDIA | Debian Version | Supported Architectures (Generations) | Notes | | Driver NVIDIA | Debian Version | Supported Architectures (Generations) | Notes |
| :--- | :--- | :--- | :--- | | :--- | :--- | :--- | :--- |
@@ -240,7 +240,7 @@ Depending on your GPU generation and your Debian ecosystem, you must select the
| **[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. | | **[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. | | **[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:** #### **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. * **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. * **Fermi (GTX 400/500)**: Support ended with driver 390. These GPUs are incompatible with modern kernels and drivers beyond Debian 11.
@@ -262,7 +262,7 @@ fi
### 10. Performance Monitoring & Telemetry Tools ### 10. 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. To check that the graphics stack works, `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))**: * **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`). * A cross-platform tool that displays real-time metrics for NVIDIA, AMD, and Intel GPUs in a terminal interface (similar to `htop`).
@@ -272,7 +272,7 @@ To ensure the graphics stack is functioning correctly, `gpu.sh` offers an option
* **Intel Specific ([`intel-gpu-tools`](https://github.com/ChrisCummins/intel-gpu-tools))**: * **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`. * 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))**: * **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. * The script runs `vainfo` to verify that VAAPI is correctly configured. This confirms whether the system can use hardware acceleration for video decoding (e.g., H.264, HEVC) via Intel QuickSync or AMD Video Core Plus.
**Installation Command Logic:** **Installation Command Logic:**
@@ -287,4 +287,4 @@ if _confirm "Install Telemetry Tools"; then
fi fi
``` ```
This modular approach ensures that users can verify their installation immediately after running `debianito`, providing confidence in the performance of their graphics stack. Users can run these tools right after `debianito` to confirm that the graphics stack works.
docs/kernel.md
+19 -19
View File
@@ -11,7 +11,7 @@ The **Kernel** module (`modules/kernel.sh`) manages which Linux kernel your syst
| `rt` | Real-Time | `linux-image-rt-amd64` | Preempt-RT kernel for low-latency / audio production. Warns on NVIDIA. | | `rt` | Real-Time | `linux-image-rt-amd64` | Preempt-RT kernel for low-latency / audio production. Warns on NVIDIA. |
| `cloud` | Cloud | `linux-image-cloud-amd64` | Minimal kernel for VMs, containers, and cloud images. | | `cloud` | Cloud | `linux-image-cloud-amd64` | Minimal kernel for VMs, containers, and cloud images. |
All variants install the matching **headers** package (`linux-headers-amd64`, `linux-headers-rt-amd64`, `linux-headers-cloud-amd64`) in the same transaction — critical for DKMS modules (NVIDIA, VirtualBox, ZFS). All variants install the matching **headers** package (`linux-headers-amd64`, `linux-headers-rt-amd64`, `linux-headers-cloud-amd64`) in the same transaction, which matters for DKMS modules (NVIDIA, VirtualBox, ZFS).
> **Position in menu:** This is Option 7 in the current `debianito.sh` main menu. Previous documentation listed it as Option 6 (Backports only). The module was expanded to support RT and Cloud kernels after the initial release. > **Position in menu:** This is Option 7 in the current `debianito.sh` main menu. Previous documentation listed it as Option 6 (Backports only). The module was expanded to support RT and Cloud kernels after the initial release.
@@ -27,7 +27,7 @@ Debian Stable freezes its kernel at an LTS release (6.12 LTS on Trixie). This is
The `trixie-backports` repository provides a **best-effort newer kernel** without moving the rest of the system to Testing. Debian backports kernels receive security updates but are not LTS themselves. The `trixie-backports` repository provides a **best-effort newer kernel** without moving the rest of the system to Testing. Debian backports kernels receive security updates but are not LTS themselves.
This is why the menu shows `backports` only when `DEBIAN_VERSION == 13` and greys it out otherwise. Bookworm backports is intentionally not offered — its EOL was 2026-08-09 and the NVIDIA path on Bookworm no longer uses backports. This is why the menu shows `backports` only when `DEBIAN_VERSION == 13` and greys it out otherwise. Bookworm backports is intentionally not offered: its EOL was 2026-08-09 and the NVIDIA path on Bookworm no longer uses backports.
--- ---
@@ -42,9 +42,9 @@ _install_kernel_package "linux-image-rt-amd64" "RT" ""
Execution steps: Execution steps:
1. **Availability check** — `apt-cache show <pkg>` must succeed. If the package does not exist for the current Debian version, a whiptail message `Kernel not available` is shown and the function returns. 1. **Availability check**: `apt-cache show <pkg>` must succeed. If the package does not exist for the current Debian version, a whiptail message `Kernel not available` is shown and the function returns.
2. **Hardware warnings** (flavour-specific): 2. **Hardware warnings** (flavour-specific):
- **Backports + NVIDIA** (`GPU_TYPE == "nvidia"`): `_confirm "Kernel" "WARNING: Backports kernel changes the kernel version. Your NVIDIA driver will need recompilation (DKMS)."`. Users can still proceed — DKMS will rebuild on next boot if headers match. - **Backports + NVIDIA** (`GPU_TYPE == "nvidia"`): `_confirm "Kernel" "WARNING: Backports kernel changes the kernel version. Your NVIDIA driver will need recompilation (DKMS)."`. Users can still proceed: DKMS will rebuild on next boot if headers match.
- **RT + NVIDIA**: `_msg "Kernel — RT" "Ensure your NVIDIA driver supports the RT kernel. Some proprietary drivers may not work correctly."`. Not a blocker, but informs that some closed drivers fail with PREEMPT_RT. - **RT + NVIDIA**: `_msg "Kernel — RT" "Ensure your NVIDIA driver supports the RT kernel. Some proprietary drivers may not work correctly."`. Not a blocker, but informs that some closed drivers fail with PREEMPT_RT.
3. **Version resolution** for the confirmation dialog: 3. **Version resolution** for the confirmation dialog:
@@ -57,7 +57,7 @@ Execution steps:
``` ```
The dialog shows `Image: linux-image-amd64 (6.12.22-1)` + `Headers: linux-headers-amd64 (6.12.22-1)` + `From: Trixie-backports` when a backports flag is present. The dialog shows `Image: linux-image-amd64 (6.12.22-1)` + `Headers: linux-headers-amd64 (6.12.22-1)` + `From: Trixie-backports` when a backports flag is present.
4. **User confirmation** — `whiptail --yesno "Install Backports kernel? Image: ... Headers: ..."` with the version string. Declining aborts with `Skipping.`. 4. **User confirmation**: `whiptail --yesno "Install Backports kernel? Image: ... Headers: ..."` with the version string. Declining aborts with `Skipping.`.
5. **Atomic install**: 5. **Atomic install**:
```bash ```bash
@@ -66,8 +66,8 @@ Execution steps:
sudo apt install -y linux-image-cloud-amd64 linux-headers-cloud-amd64 sudo apt install -y linux-image-cloud-amd64 linux-headers-cloud-amd64
``` ```
Both image and headers are passed in a **single `apt` transaction**. This guarantees the symbol tables match and DKMS can rebuild. The helper `_run_cmd "Kernel"` prints the command, captures the exit code, and pauses for the user to review output. Both image and headers are passed in a **single `apt` transaction**. This keeps the symbol tables matched so DKMS can rebuild. The helper `_run_cmd "Kernel"` prints the command, captures the exit code, and pauses for the user to review output.
6. **Post-install** — prints `Backports kernel installed. Reboot to use it.` and pauses. The new kernel is added to `/boot` alongside the old one; GRUB will show both at next boot. The script does not remove the old kernel — rollback is simply rebooting into the previous entry. 6. **Post-install**: prints `Backports kernel installed. Reboot to use it.` and pauses. The new kernel is added to `/boot` alongside the old one; GRUB will show both at next boot. The script does not remove the old kernel; rollback is simply rebooting into the previous entry.
--- ---
@@ -101,9 +101,9 @@ show_kernel_menu() {
Key details: Key details:
- **Backports visibility** — The `backports` entry is only appended when `DEBIAN_VERSION == 13`. On Bullseye/Bookworm it does not appear. - **Backports visibility**: The `backports` entry is only appended when `DEBIAN_VERSION == 13`. On Bullseye/Bookworm it does not appear.
- **Backports guard** — Selecting `backports` without backports enabled shows a message pointing to **Option 4 (Configure Repositories)**. No install is attempted. - **Backports guard**: Selecting `backports` without backports enabled shows a message pointing to **Option 4 (Configure Repositories)**. No install is attempted.
- **Loop** — The menu is a `while true` loop; the user can install multiple variants sequentially (e.g., Stable + RT) before returning with `back` or `ESC`. - **Loop**: The menu is a `while true` loop; the user can install multiple variants sequentially (e.g., Stable + RT) before returning with `back` or `ESC`.
--- ---
@@ -113,20 +113,20 @@ Key details:
| ----------- | -------------- | | ----------- | -------------- |
| **Pre-flight `is_backports_enabled`** | `utils.sh:is_backports_enabled` greps `/etc/apt/sources.list` and `/etc/apt/sources.list.d/*.sources` / `*.list` for `trixie-backports`. Prevents `apt -t` from failing with `E: Release not found`. | | **Pre-flight `is_backports_enabled`** | `utils.sh:is_backports_enabled` greps `/etc/apt/sources.list` and `/etc/apt/sources.list.d/*.sources` / `*.list` for `trixie-backports`. Prevents `apt -t` from failing with `E: Release not found`. |
| **NVIDIA RT warning** | `utils.sh:GPU_TYPE` is set on demand by `detect_gpu` (lspci, via `_ensure_state_detected`). RT kernels change scheduling semantics; some `nvidia.ko` builds reject `PREEMPT_RT`. | | **NVIDIA RT warning** | `utils.sh:GPU_TYPE` is set on demand by `detect_gpu` (lspci, via `_ensure_state_detected`). RT kernels change scheduling semantics; some `nvidia.ko` builds reject `PREEMPT_RT`. |
| **Atomic image+headers** | Both packages in one `apt` call. If headers are missing, `dkms` will fail at boot — so they are never installed separately. | | **Atomic image+headers** | Both packages in one `apt` call. If headers are missing, `dkms` will fail at boot, so they are never installed separately. |
| **Fallback preservation** | `apt` never removes the running kernel. `/boot` retains `vmlinuz-*` and `initrd.img-*` for both. GRUB keeps both entries; if the new kernel panics, select the old one. | | **Fallback preservation** | `apt` never removes the running kernel. `/boot` retains `vmlinuz-*` and `initrd.img-*` for both. GRUB keeps both entries; if the new kernel panics, select the old one. |
| **Version-aware messaging** | The confirmation dialog always shows the exact version string (`apt-cache madison` / `apt-cache show`) so users know they are not reinstalling the same package. | | **Version-aware messaging** | The confirmation dialog always shows the exact version string (`apt-cache madison` / `apt-cache show`) so users know they are not reinstalling the same package. |
GRUB update is **not** explicitly called — `linux-image-*` postinst triggers `update-grub` (or `kernel-install` on systemd-boot) automatically. If GRUB is broken, use **Option 12 (Boot Rescue + GRUB)** to rebuild it. GRUB update is **not** explicitly called: `linux-image-*` postinst triggers `update-grub` (or `kernel-install` on systemd-boot) automatically. If GRUB is broken, use **Option 12 (Boot Rescue + GRUB)** to rebuild it.
--- ---
## 6. Interconnection with Other Modules ## 6. Interconnection with Other Modules
- **Option 4: Repositories** — Must enable `trixie-backports` before `Kernel → backports` is usable. The kernel menu explicitly checks `is_backports_enabled` and directs the user there if missing. - **Option 4: Repositories**: Must enable `trixie-backports` before `Kernel → backports` is usable. The kernel menu explicitly checks `is_backports_enabled` and directs the user there if missing.
- **Option 5: Firmware** — Newer kernels expose new hardware IDs (e.g., `8086:7e40` for Panther Lake). Without updated `firmware-linux-nonfree` or `firmware-iwlwifi`, the new kernel will show the device but fail to load firmware. Run Firmware after a kernel upgrade if WiFi/storage is not recognized. - **Option 5: Firmware**: Newer kernels expose new hardware IDs (e.g., `8086:7e40` for Panther Lake). Without updated `firmware-linux-nonfree` or `firmware-iwlwifi`, the new kernel will show the device but fail to load firmware. Run Firmware after a kernel upgrade if WiFi/storage is not recognized.
- **Option 6: Graphics Drivers** — NVIDIA `dkms` needs the exact `linux-headers-*` version. The atomic install ensures headers match. On Bookworm the NVIDIA path deliberately avoids backports kernels; on Trixie a backports kernel + Maxwell/Pascal GPU is forced to the stable NVIDIA driver (`v550`) to avoid `v590` incompatibility. - **Option 6: Graphics Drivers**: NVIDIA `dkms` needs the exact `linux-headers-*` version. The atomic install ensures headers match. On Bookworm the NVIDIA path deliberately avoids backports kernels; on Trixie a backports kernel + Maxwell/Pascal GPU is forced to the stable NVIDIA driver (`v550`) to avoid `v590` incompatibility.
- **Gaming (`gaming.sh`)** — The backports kernel is sometimes recommended for gaming (scheduler latency, `SCHED_EXT`), but not required. Benchmarks show <3% difference for most titles; enable it only for newer hardware that needs it. - **Gaming (`gaming.sh`)**: The backports kernel is sometimes recommended for gaming (scheduler latency, `SCHED_EXT`), but not required. Benchmarks show <3% difference for most titles; enable it only for newer hardware that needs it.
--- ---
@@ -146,7 +146,7 @@ If the new kernel fails to boot, hold `ESC` (or `Shift` on BIOS) at power-on, se
## References ## References
- [Debian Backports — backports.debian.org](https://backports.debian.org/) - [Debian Backports: backports.debian.org](https://backports.debian.org/)
- [Debian Kernel Handbook](https://kernel-handbook.alioth.debian.org/) - [Debian Kernel Handbook](https://kernel-handbook.alioth.debian.org/)
- [PREEMPT_RT — wiki.debian.org/RealTime](https://wiki.debian.org/RealTime) - [PREEMPT_RT: wiki.debian.org/RealTime](https://wiki.debian.org/RealTime)
- [Installing a new kernel — wiki.debian.org/DebianKernel](https://wiki.debian.org/DebianKernel) - [Installing a new kernel: wiki.debian.org/DebianKernel](https://wiki.debian.org/DebianKernel)
docs/quickstart.md
+55 -43
View File
@@ -1,4 +1,4 @@
# Debianito — Quick Start Visual Guide # Debianito: Quick Start Visual Guide
> **Scope:** Fresh Debian 11 / 12 / 13 installation → fully configured desktop in ~15-20 minutes. > **Scope:** Fresh Debian 11 / 12 / 13 installation → fully configured desktop in ~15-20 minutes.
> **Prerequisites:** Normal user with `sudo` access. Do **not** run the script as root. > **Prerequisites:** Normal user with `sudo` access. Do **not** run the script as root.
@@ -18,13 +18,25 @@ The script automatically checks for `whiptail` and `lsb-release`, installs them
> ![Script](/media/gift/script.gif) > ![Script](/media/gift/script.gif)
With no flags the script runs interactively. Three flags change that (full table in the [README](../README.md#command-line-usage)):
```bash
./debianito.sh --yes # auto-confirm prompts; menus still display
./debianito.sh --yes --allow-destructive # also unblock branch migration
./debianito.sh --help # show usage and exit
```
`--yes` auto-confirms prompts, but the menus still display and still need arrow keys and ENTER. By itself it does not reach branch migration (menu `4 [ADVANCED] Upgrade system branch`): that operation can leave the system unbootable, so the script reports that `--allow-destructive` is required. `DEBIANITO_PROFILE=1 ./debianito.sh` stamps each boot step to stderr with a timestamp, which makes before/after comparisons possible. An unknown option exits with status 2.
Package installs are batched behind a single confirmation: the script lists what it is about to install (the first 15 package names, plus a count of the rest) and asks you to proceed. With `--yes` these confirmations are accepted automatically.
--- ---
## Recommended Order ## Recommended Order
Each step builds on the previous one. Steps 1-5 + 10 are the essential path; 6-9 are optional. Each step builds on the previous one. Steps 1-6 are the essential path; steps 7-10 are optional.
### Step 1 — Know Your System ### Step 1: Know Your System
**Menu:** `1 System Information` **Menu:** `1 System Information`
@@ -39,11 +51,11 @@ You will see:
- Storage topology (NVMe / SSD / HDD / USB-SD) - Storage topology (NVMe / SSD / HDD / USB-SD)
- Display server (Wayland / X11 / tty) and desktop environment - Display server (Wayland / X11 / tty) and desktop environment
Remember the **GPU line** (Intel / AMD / NVIDIA) and any **WiFi chipset** — you will need them in Steps 4-5. Remember the **WiFi chipset** for the firmware mapping in Step 5, and the **GPU line** (Intel / AMD / NVIDIA) for the drivers in Step 6.
> ![Script](/media/screenshots/01-system-info.png) System Information dialog with hardware summary. > ![Script](/media/screenshots/01-system-info.png) System Information dialog with hardware summary.
### Step 2 — Fix Permissions Early (Optional but Recommended) ### Step 2: Fix Permissions Early (Optional but Recommended)
**Menu:** `2 User Privileges & Feedback` **Menu:** `2 User Privileges & Feedback`
@@ -54,12 +66,12 @@ A sub-menu with four toggles:
| Sudo group membership | `usermod -aG sudo $USER` | Fresh install where the first user is not in `sudo` | | Sudo group membership | `usermod -aG sudo $USER` | Fresh install where the first user is not in `sudo` |
| Passwordless sudo | Creates `/etc/sudoers.d/$USER-nopasswd` with `NOPASSWD` for `apt`, `systemctl`, etc. | Lab / personal machine; skip on shared systems | | Passwordless sudo | Creates `/etc/sudoers.d/$USER-nopasswd` with `NOPASSWD` for `apt`, `systemctl`, etc. | Lab / personal machine; skip on shared systems |
| Repair home ownership | `chown -R $USER:$USER $HOME` | Home files owned by root after a mishandled `sudo` | | Repair home ownership | `chown -R $USER:$USER $HOME` | Home files owned by root after a mishandled `sudo` |
| Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` — shows `****` while typing | **Enable now** to avoid typos during the many installs that follow | | Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` (typing then shows `****`) | **Enable now** to avoid typos during the many installs that follow |
> ![Script](/media/screenshots/02-user-privileges.png) User Privileges & Feedback menu. > ![Script](/media/screenshots/02-user-privileges.png) User Privileges & Feedback menu.
> ![Script](/media/screenshots/02b-pwfeedback.png) Confirmation dialog for "Sudo Password Feedback" with asterisk preview. > ![Script](/media/screenshots/02b-pwfeedback.png) Confirmation dialog for "Sudo Password Feedback" with asterisk preview.
### Step 3 — System Preferences (Optional) ### Step 3: System Preferences (Optional)
**Menu:** `3 System Preferences` **Menu:** `3 System Preferences`
@@ -70,13 +82,13 @@ A sub-menu with four toggles:
4 Back to main menu 4 Back to main menu
``` ```
- **Date, Time & Timezone** — Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update` — a wrong clock breaks GPG verification. - **Date, Time & Timezone**: Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update`: a wrong clock breaks GPG verification.
- **Language, Locales & Keyboard** — Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`. - **Language, Locales & Keyboard**: Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
- **Audio & Sound Stack** — Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [System Preferences](system_prefs.md). - **Audio & Sound Stack**: Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [System Preferences](system_prefs.md).
> ![Script](/media/screenshots/03-system-prefs.png) System Preferences menu. > ![Script](/media/screenshots/03-system-prefs.png) System Preferences menu.
### Step 4 — Configure Repositories (Required) ### Step 4: Configure Repositories (Required)
**Menu:** `4 Configure Repositories` **Menu:** `4 Configure Repositories`
@@ -88,32 +100,32 @@ A sub-menu with four toggles:
5 Back to main menu 5 Back to main menu
``` ```
1. Choose **1. Enable Contrib & Non-Free** — adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback. 1. Choose **1. Enable Contrib & Non-Free**: adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
2. Choose **3. Setup/Update Backports** — answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [Configure Repositories](repos_config.md). 2. Choose **3. Setup/Update Backports**: answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [Configure Repositories](repos_config.md).
⚠️ Without `non-free` and `contrib`, Steps 5 and 8 will fail. Do not skip. ⚠️ Without `non-free` and `contrib`, Steps 5 and 8 will fail. Do not skip.
> ![Script](/media/screenshots/04-repos.png) Repositories menu. > ![Script](/media/screenshots/04-repos.png) Repositories menu.
> ![Script](/media/screenshots/04b-backports.png) Backports confirmation dialog. > ![Script](/media/screenshots/04b-backports.png) Backports confirmation dialog.
### Step 5 — Install Firmware & Wireless Drivers ### Step 5: Install Firmware & Wireless Drivers
**Menu:** `5 Firmware, Wireless & Bluetooth` **Menu:** `5 Firmware, Wireless & Bluetooth`
The script: The script:
- Scans **all** network hardware (PCI `lspci -nn` + USB `lsusb`, filtered for Realtek/Intel/Mediatek/Atheros/Qualcomm) and Bluetooth controllers - Scans **all** network hardware (PCI `lspci -nn` + USB `lsusb`, filtered for Realtek/Intel/Mediatek/Atheros/Qualcomm) and Bluetooth controllers
- Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc` — plus `firmware-linux-nonfree` as the base meta-package - Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc`, plus `firmware-linux-nonfree` as the base meta-package
- Builds a plan showing detected controllers and planned packages, including Bluetooth handling (KDE → `bluedevil`, XFCE → `blueman`, GNOME → built-in, plus `pipewire-pulse`/`wireplumber` if PipeWire is active) - Builds a plan showing detected controllers and planned packages, including Bluetooth handling (KDE → `bluedevil`, XFCE → `blueman`, GNOME → built-in, plus `pipewire-pulse`/`wireplumber` if PipeWire is active)
- Asks for confirmation before installing; offers Stable vs Backports for the base firmware - Asks for confirmation before installing; offers Stable vs Backports for the base firmware
Accept the plan it shows — it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`. Accept the plan it shows: it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first — the driver needs a fresh load. ⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first: the driver needs a fresh load.
> ![Script](/media/screenshots/05-firmware-plan.png) Firmware plan dialog with hardware + package list. > ![Script](/media/screenshots/05-firmware-plan.png) Firmware plan dialog with hardware + package list.
### Step 6 — Install Graphics Drivers ### Step 6: Install Graphics Drivers
**Menu:** `6 Graphics Drivers & Mesa Stack` **Menu:** `6 Graphics Drivers & Mesa Stack`
@@ -124,11 +136,11 @@ Whiptail radiolist with two options:
2 NVIDIA Drivers 2 NVIDIA Drivers
``` ```
#### Path A — Radeon/Intel Mesa #### Path A: Radeon/Intel Mesa
Shows a plan with detected GPUs (`Intel firmware + intel-media-va-driver-non-free` or `i965-va-driver-shaders` for Gen7-, `firmware-amd-graphics` for AMD, plus `Mesa Vulkan/OpenGL/VA-API`). Offers legacy AMD GCN 1.0/1.1 migration to `amdgpu` via GRUB params (`radeon.si_support=0 ... amdgpu.si_support=1`). Installs Mesa from Backports or Stable (`_install_mesa_backports`), verifies `mesa-vulkan-drivers`, and offers vendor-specific telemetry (`radeontop`, `intel-gpu-tools`, `vainfo`). Shows a plan with detected GPUs (`Intel firmware + intel-media-va-driver-non-free` or `i965-va-driver-shaders` for Gen7-, `firmware-amd-graphics` for AMD, plus `Mesa Vulkan/OpenGL/VA-API`). Offers legacy AMD GCN 1.0/1.1 migration to `amdgpu` via GRUB params (`radeon.si_support=0 ... amdgpu.si_support=1`). Installs Mesa from Backports or Stable (`_install_mesa_backports`), verifies `mesa-vulkan-drivers`, and offers vendor-specific telemetry (`radeontop`, `intel-gpu-tools`, `vainfo`).
#### Path B — NVIDIA Drivers #### Path B: NVIDIA Drivers
Shows detected NVIDIA GPUs and a two-stage menu: Shows detected NVIDIA GPUs and a two-stage menu:
@@ -137,13 +149,13 @@ Shows detected NVIDIA GPUs and a two-stage menu:
- Bookworm: `v535` (Recommended) or `v470` (Kepler legacy via `nvidia-tesla-470-driver`) - Bookworm: `v535` (Recommended) or `v470` (Kepler legacy via `nvidia-tesla-470-driver`)
- Trixie: `v550` (Debian stable, Recommended), `v590` or `v595` (NVIDIA CUDA Repo with `cuda-keyring` + `nvidia-open` + `firmware-nvidia-gsp`) - Trixie: `v550` (Debian stable, Recommended), `v590` or `v595` (NVIDIA CUDA Repo with `cuda-keyring` + `nvidia-open` + `firmware-nvidia-gsp`)
The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility — e.g., Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message. The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility. For example, Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
> ![Script](/media/screenshots/06-gpu-choice.png) GPU type selector (Radeon/Intel vs NVIDIA). > ![Script](/media/screenshots/06-gpu-choice.png) GPU type selector (Radeon/Intel vs NVIDIA).
After installation, **reboot** before testing. NVIDIA drivers need a fresh kernel load. After installation, **reboot** before testing. NVIDIA drivers need a fresh kernel load.
### Step 7 — Kernel Configuration (Optional) ### Step 7: Kernel Configuration (Optional)
**Menu:** `7 Kernel` **Menu:** `7 Kernel`
@@ -155,17 +167,17 @@ cloud Install linux-image-cloud-amd64
back Return to main menu back Return to main menu
``` ```
- **Stable** — default Debian kernel (6.12 LTS on Trixie). - **Stable**: default Debian kernel (6.12 LTS on Trixie).
- **Backports** — only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc. - **Backports**: only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
- **RT** — Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT). - **RT**: Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
- **Cloud** — minimal kernel for VMs/containers (`linux-image-cloud-amd64`). - **Cloud**: minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
Each variant installs the matching `linux-headers-*` package atomically (`sudo apt install -y [-t trixie-backports] linux-image-* linux-headers-*`). The script warns about DKMS recompilation if NVIDIA is present. Each variant installs the matching `linux-headers-*` package atomically (`sudo apt install -y [-t trixie-backports] linux-image-* linux-headers-*`). The script warns about DKMS recompilation if NVIDIA is present.
> ![Script](/media/screenshots/07-kernel.png) — Kernel menu with four variants. > ![Script](/media/screenshots/07-kernel.png) Kernel menu with four variants.
> See [kernel](kernel.md) for backports rationale and bootloader details. > See [kernel](kernel.md) for backports rationale and bootloader details.
### Step 8 — Gaming Setup (Optional) ### Step 8: Gaming Setup (Optional)
**Menu:** `8 Gaming Setup` **Menu:** `8 Gaming Setup`
@@ -194,7 +206,7 @@ A single checklist with all options:
> ![Script](/media/screenshots/08-gaming.png) Gaming checklist with i386 + Steam + MangoHud checked. > ![Script](/media/screenshots/08-gaming.png) Gaming checklist with i386 + Steam + MangoHud checked.
> See [gaming](gaming.md) and [retroarch](retroarch.md). > See [gaming](gaming.md) and [retroarch](retroarch.md).
### Step 9 — ZRAM Compressed Swap (Optional) ### Step 9: ZRAM Compressed Swap (Optional)
**Menu:** `9 ZRAM` **Menu:** `9 ZRAM`
@@ -205,15 +217,15 @@ A single checklist with all options:
4 Back to main menu 4 Back to main menu
``` ```
- **View** — Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output. - **View**: Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
- **Create / Reconfigure** — Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10). - **Create / Reconfigure**: Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
- **Remove** — `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`. - **Remove**: `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
> ![Script](/media/screenshots/09-zram-algo.png) Algorithm choice (lz4 vs zstd). > ![Script](/media/screenshots/09-zram-algo.png) Algorithm choice (lz4 vs zstd).
> ![Script](/media/screenshots/09b-zram-status.png) `zramctl` status output in whiptail. > ![Script](/media/screenshots/09b-zram-status.png) `zramctl` status output in whiptail.
> See [zram](zram.md). > See [zram](zram.md).
### Step 10 — Swap Management (Optional) ### Step 10: Swap Management (Optional)
**Menu:** `10 Swap Management` **Menu:** `10 Swap Management`
@@ -234,7 +246,7 @@ A single checklist with all options:
> ![Script](/media/screenshots/10b-swap-status.png) Swap status. > ![Script](/media/screenshots/10b-swap-status.png) Swap status.
> See [swap](swap.md). > See [swap](swap.md).
### Step 11 — Install Programs and Software ### Step 11: Install Programs and Software
**Menu:** `11 Install Programs and Software` → `0 Essential Pack` **Menu:** `11 Install Programs and Software` → `0 Essential Pack`
@@ -261,17 +273,17 @@ After this, browse the other categories as needed:
> ![Script](/media/screenshots/11-programs.gif) Category menu with 0-14 options. > ![Script](/media/screenshots/11-programs.gif) Category menu with 0-14 options.
> ![Script](/media/screenshots/11b-essential-pack.png) Essential Pack confirmation. > ![Script](/media/screenshots/11b-essential-pack.png) Essential Pack confirmation.
### Step 12 — Boot Rescue ### Step 12: Boot Rescue
**Menu:** `12 Boot Rescue + GRUB` **Menu:** `12 Boot Rescue + GRUB`
- **GRUB boot menu settings** — 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback. - **GRUB boot menu settings**: 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
- **UEFI Secure Boot repair** — reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`). - **UEFI Secure Boot repair**: reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
- **Initramfs regeneration** — `update-initramfs -u -k all || true`. - **Initramfs regeneration**: `update-initramfs -u -k all || true`.
> See [boot](boot.md). > See [boot](boot.md).
### Step 13 — Desktop & Display ### Step 13: Desktop & Display
**Menu:** `13 Desktop & Display` **Menu:** `13 Desktop & Display`
@@ -281,8 +293,8 @@ After this, browse the other categories as needed:
3 Back to main menu 3 Back to main menu
``` ```
- **Desktop Environment** — pick one of **XFCE** (full / minimal / Wayland `labwc` on Trixie / custom checklist), **LXDE** (full / core), **GNOME** (full / core) or **KDE Plasma** (full / minimal). Each environment installs from its own module in `modules/desktops/` (lazy-loaded). XFCE installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group; GNOME/KDE preseed the display manager while keeping any already-configured one as default. After the install, the script offers the PipeWire audio stack if none is present. - **Desktop Environment**: pick one of **XFCE** (full / minimal / Wayland `labwc` on Trixie / custom checklist), **LXDE** (full / core), **GNOME** (full / core) or **KDE Plasma** (full / minimal). Each environment installs from its own module in `modules/desktops/` (lazy-loaded). XFCE installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group; GNOME/KDE preseed the display manager while keeping any already-configured one as default. After the install, the script offers the PipeWire audio stack if none is present.
- **Display Manager** — LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet — manual `/etc/greetd/config.toml` required). - **Display Manager**: LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet; manual `/etc/greetd/config.toml` required).
> See [Desktop & Display](desktops_display.md). > See [Desktop & Display](desktops_display.md).
@@ -301,7 +313,7 @@ After this, browse the other categories as needed:
systemctl status bluetooth # Bluetooth active? systemctl status bluetooth # Bluetooth active?
``` ```
3. For gaming, enable `i386` was handled — verify with `dpkg --print-foreign-architectures | grep i386`. 3. For gaming, the script adds the `i386` architecture when you check `steam`, `lutris` or `i386`; verify with `dpkg --print-foreign-architectures | grep i386`.
--- ---
@@ -313,6 +325,6 @@ After this, browse the other categories as needed:
| **Black screen after NVIDIA + Wayland (GNOME/GDM3)** | At login, select *GNOME on Xorg* (gear icon) or disable Wayland: `sudo nano /etc/gdm3/daemon.conf` → `WaylandEnable=false`. The script only warns about Debian bug #1109409, it does not force X11. | | **Black screen after NVIDIA + Wayland (GNOME/GDM3)** | At login, select *GNOME on Xorg* (gear icon) or disable Wayland: `sudo nano /etc/gdm3/daemon.conf` → `WaylandEnable=false`. The script only warns about Debian bug #1109409, it does not force X11. |
| **GRUB menu hidden and cannot enter** | Hold `ESC` immediately after power-on. Or boot a live USB, `chroot`, and run `12 Boot Rescue → GRUB boot menu settings → Show 5 seconds`. | | **GRUB menu hidden and cannot enter** | Hold `ESC` immediately after power-on. Or boot a live USB, `chroot`, and run `12 Boot Rescue → GRUB boot menu settings → Show 5 seconds`. |
| **Steam fails to start** | Verify `i386` is enabled: `dpkg --print-foreign-architectures`. Check `contrib` is in `/etc/apt/sources.list`. Re-run `8 Gaming Setup` and ensure the checklist had `i386` + `steam` checked. | | **Steam fails to start** | Verify `i386` is enabled: `dpkg --print-foreign-architectures`. Check `contrib` is in `/etc/apt/sources.list`. Re-run `8 Gaming Setup` and ensure the checklist had `i386` + `steam` checked. |
| **greetd installed but cannot log in** | This is expected — you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. | | **greetd installed but cannot log in** | This is expected: you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
| **Bluetooth tray icon missing** | Reboot or `systemctl restart bluetooth`. Ensure `bluez`, `bluedevil` (KDE) or `blueman` (XFCE) is installed. For PipeWire, check `systemctl --user status pipewire pipewire-pulse wireplumber`. | | **Bluetooth tray icon missing** | Reboot or `systemctl restart bluetooth`. Ensure `bluez`, `bluedevil` (KDE) or `blueman` (XFCE) is installed. For PipeWire, check `systemctl --user status pipewire pipewire-pulse wireplumber`. |
| **PipeWire crackling / no Bluetooth Hi-Res codec** | Re-run `3 System Preferences → Audio & Sound → PipeWire Audio Stack`. Verify `libldacbt-*`, `libopenaptx0`, `libfdk-aac2t64` are installed (`dpkg -l \| grep -E 'ldac\|aptx\|fdk'`). | | **PipeWire crackling / no Bluetooth Hi-Res codec** | Re-run `3 System Preferences → Audio & Sound → PipeWire Audio Stack`. Verify `libldacbt-*`, `libopenaptx0`, `libfdk-aac2t64` are installed (`dpkg -l \| grep -E 'ldac\|aptx\|fdk'`). |
docs/repos_config.md
+14 -14
View File
@@ -2,23 +2,23 @@
### 1. What Does This Component Do? ### 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. The repository configuration module sets up and maintains the APT sources of your Debian system. Each change is written atomically, backed up beforehand and rolled back automatically if the following `apt update` fails.
At its core, this component: It:
- Detects your current repository format (Classic `.list` vs modern DEB822 `.sources`) - Detects your current repository format (Classic `.list` vs modern DEB822 `.sources`)
- Backs up existing configurations before any modifications - Backs up existing configurations before any modifications
- Enables critical non-free components required for hardware drivers and proprietary software - Enables the non-free components required for hardware drivers and proprietary software
- Integrates Debian Backports to access newer kernels and firmware packages - Integrates Debian Backports to access newer kernels and firmware packages
- Validates changes through `apt update` with automatic restoration on failure - 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. Every other configuration option (GPU drivers, kernel upgrades, gaming setup) needs this module to work first.
--- ---
### 2. Supported Injection Formats ### 2. Supported Injection Formats
The script intelligently adapts to your Debian version and existing repository structure: The script adapts to your Debian version and existing repository structure:
#### Classic Format (`/etc/apt/sources.list`) #### Classic Format (`/etc/apt/sources.list`)
@@ -33,7 +33,7 @@ deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmwa
#### Modern DEB822 Format (`/etc/apt/sources.list.d/debian.sources`) #### Modern DEB822 Format (`/etc/apt/sources.list.d/debian.sources`)
- **Structure**: Declarative YAML-like format with `Types`, `URIs`, and `Suites` blocks - **Structure**: Declarative RFC-822 style format with `Types`, `URIs`, and `Suites` blocks
- **Use Case**: Debian 13 (Trixie) default, future-proofing for newer releases - **Use Case**: Debian 13 (Trixie) default, future-proofing for newer releases
- **Characteristics**: Machine-parseable, structured, supports complex repository hierarchies - **Characteristics**: Machine-parseable, structured, supports complex repository hierarchies
- **Example**: - **Example**:
@@ -50,7 +50,7 @@ Components: main contrib non-free non-free-firmware
The script automatically detects your current format and offers migration options: The script automatically detects your current format and offers migration options:
- On Debian 13 (Trixie): Prompts to migrate TO DEB822 or stay with Classic - On Debian 13 (Trixie): Prompts to migrate TO DEB822 or stay with Classic
- Format changes are atomic—backup is created before any modification - Format changes are atomic: a backup is created before any modification
- Old files are renamed with `.disabled` extension rather than deleted - Old files are renamed with `.disabled` extension rather than deleted
--- ---
@@ -160,7 +160,7 @@ The script enables specific APT component branches that are essential for hardwa
| **non-free** | Non-free firmware and proprietary software | NVIDIA GPU drivers, Wi-Fi firmware | Required for hardware support | | **non-free** | Non-free firmware and proprietary software | NVIDIA 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+** | | **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+) #### Why `non-free-firmware` Is Required (Debian 12+)
Starting with Debian Bookworm (12.0), the `non-free-firmware` component was separated into its own repository branch: Starting with Debian Bookworm (12.0), the `non-free-firmware` component was separated into its own repository branch:
@@ -174,10 +174,10 @@ deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmwa
**Impact of Missing `non-free-firmware`:** **Impact of Missing `non-free-firmware`:**
- ❌ Wi-Fi adapters won't work without firmware blobs - Wi-Fi adapters won't work without firmware blobs
- ❌ Bluetooth devices may fail to initialize - Bluetooth devices may fail to initialize
- ❌ Some GPU drivers require proprietary microcode - Some GPU drivers require proprietary microcode
- ❌ Embedded hardware (Raspberry Pi, etc.) becomes unusable - Embedded hardware (Raspberry Pi, etc.) becomes unusable
The script ensures all four components are present because: The script ensures all four components are present because:
@@ -189,7 +189,7 @@ The script ensures all four components are present because:
### 5. Support for Debian Backports ### 5. Support for Debian Backports
The backports integration is a sophisticated feature that enables access to newer, tested packages without compromising system stability: Backports give access to newer, tested packages without compromising system stability:
#### Detection Logic (`detect_backports_status` & `detect_backports_location`) #### Detection Logic (`detect_backports_status` & `detect_backports_location`)
@@ -243,7 +243,7 @@ The backports integration is a sophisticated feature that enables access to newe
#### Why Enable Backports? #### Why Enable Backports?
The script includes a detailed explanation because backports enable critical features: The script explains this in its confirmation dialog because backports change what you get for three components:
| Feature | Without Backports | With Backports | | Feature | Without Backports | With Backports |
| --------- | ------------------- | ---------------- | | --------- | ------------------- | ---------------- |
docs/retroarch.md
+12 -12
View File
@@ -18,16 +18,16 @@ When installed via `apt`, RetroArch uses these locations:
Because the core and info directories are owned by root, you cannot write to them without `sudo`. Because the core and info directories are owned by root, you cannot write to them without `sudo`.
You have two options: You have two options:
1. **Manual installation** – download cores and info files yourself and copy them with `sudo`. 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**. 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. Both methods work; choose the one that suits you best.
--- ---
## Method 1 – Manual Core Installation (Recommended for Reliability) ## Method 1: Manual Core Installation (Recommended for Reliability)
This method guarantees that you can add any core, even if the online updater is blocked. This method works for any core, even when the online updater is blocked.
### 1. Download and Install the Core (`.so`) ### 1. Download and Install the Core (`.so`)
@@ -41,7 +41,7 @@ sudo mv ppsspp_libretro.so /usr/lib/x86_64-linux-gnu/libretro/
rm ppsspp_libretro.so.zip rm ppsspp_libretro.so.zip
``` ```
> **Replace `ppsspp` with any core name** – e.g., `mame_libretro`, `dolphin_libretro`, etc. > **Replace `ppsspp` with any core name**: e.g., `mame_libretro`, `dolphin_libretro`, etc.
> Browse all available cores at: > Browse all available cores at:
> [https://buildbot.libretro.com/nightly/linux/x86_64/latest/](https://buildbot.libretro.com/nightly/linux/x86_64/latest/) > [https://buildbot.libretro.com/nightly/linux/x86_64/latest/](https://buildbot.libretro.com/nightly/linux/x86_64/latest/)
@@ -61,11 +61,11 @@ sudo mv ppsspp_libretro.info /usr/share/libretro/info/
--- ---
## Method 2 – Enable the Built‑in Core Downloader ## 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. 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 ### Step 1: Edit RetroArch Configuration
Create or edit `~/.config/retroarch/retroarch.cfg` and add these lines: Create or edit `~/.config/retroarch/retroarch.cfg` and add these lines:
@@ -82,19 +82,19 @@ mkdir -p ~/.config/retroarch/libretro
mkdir -p ~/.config/retroarch/libretro-info mkdir -p ~/.config/retroarch/libretro-info
``` ```
### Step 2 – Update Core Info Files ### Step 2: Update Core Info Files
- Launch RetroArch. - Launch RetroArch.
- Go to **Online Updater** → **Update Core Info Files**. - Go to **Online Updater** → **Update Core Info Files**.
- Wait for the update to complete. - Wait for the update to complete.
### Step 3 – Download Cores ### Step 3: Download Cores
- Go to **Online Updater** → **Core Downloader**. - Go to **Online Updater** → **Core Downloader**.
- Select the core you want (e.g., PPSSPP). - Select the core you want (e.g., PPSSPP).
- The core will be downloaded to your user directory and will appear in the core list. - 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). > ⚠️ **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).
--- ---
@@ -139,7 +139,7 @@ You can find many asset packs at:
## ROM / Game File Formats ## ROM / Game File Formats
- **Supported formats** for PPSSPP: `.iso`, `.cso`, `.chd`, `.pbp`. - **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. - **Always decompress your ROMs**: do not leave them in `.zip`, `.rar`, or `.7z` archives; the cores cannot read compressed archives directly.
--- ---
@@ -151,13 +151,13 @@ You can find many asset packs at:
| Core info files (GitHub) | [https://github.com/libretro/libretro-core-info](https://github.com/libretro/libretro-core-info) | | 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/) | | 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/) | | Official RetroArch documentation | [https://docs.libretro.com/](https://docs.libretro.com/) |
| Debian Wiki – RetroArch | [https://wiki.debian.org/RetroArch](https://wiki.debian.org/RetroArch) | | Debian Wiki: RetroArch | [https://wiki.debian.org/RetroArch](https://wiki.debian.org/RetroArch) |
--- ---
## Final Notes ## Final Notes
- The Debian package disables auto‑updates and the core downloader **by default** – this is intentional for stability. - 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. - 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/`. - 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. - Always test your video driver setting; `vulkan` is recommended for PPSSPP and other 3D‑heavy cores.
docs/swap.md
+7 -7
View File
@@ -2,7 +2,7 @@
### 1. What does this component do? ### 1. What does this component do?
This module is responsible for the secure management of disk-based swap space within the `debianito` environment. Unlike standard Linux tools that might overwrite existing configurations or conflict with memory compression features (like ZRAM), this script operates as a **priority-aware, persistent swap manager**. This module manages disk-based swap space in the `debianito` environment. It leaves existing configuration alone and works alongside ZRAM instead of conflicting with it.
Its primary functions include: Its primary functions include:
@@ -13,17 +13,17 @@ Its primary functions include:
### 2. How does it work? ### 2. How does it work?
The script leverages several advanced Linux subsystems and safety protocols: The script uses several Linux subsystems and safety mechanisms:
1. **File System Detection:** It identifies the filesystem type of the target partition (e.g., `ext4`, `btrfs`). For Btrfs, it applies specific flags (`chattr +C` for copy-on-write optimization) to prevent performance degradation during swap operations. 1. **File System Detection:** It identifies the filesystem type of the target partition (e.g., `ext4`, `btrfs`). For Btrfs, it applies specific flags (`chattr +C` to disable copy-on-write) to avoid performance loss during swap operations.
2. **Allocation Strategy:** It prefers `fallocate` for instant space reservation on supported filesystems, falling back to `dd if=/dev/zero` for compatibility or zeroing requirements (like Btrfs). 2. **Allocation Strategy:** It prefers `fallocate` for instant space reservation on supported filesystems, falling back to `dd if=/dev/zero` for compatibility or zeroing requirements (like Btrfs).
3. **Fstab Validation:** Before writing changes to `/etc/fstab`, it creates a temporary file and validates the syntax using `findmnt --verify`. If validation fails, the script aborts and restores the original state. 3. **Fstab Validation:** Before writing changes to `/etc/fstab`, it creates a temporary file and validates the syntax using `findmnt --verify`. If validation fails, the script aborts and restores the original state.
4. **Concurrency Control:** It utilizes `flock` on `/run/lock/debianito-swap.lock`. This ensures that if another process is modifying swap settings (e.g., a system update), this script will wait or exit gracefully to prevent filesystem corruption. 4. **Concurrency Control:** It uses `flock` on `/run/lock/debianito-swap.lock`. If another process is modifying swap settings (e.g., a system update), this script waits or exits gracefully to prevent filesystem corruption.
5. **Swappiness Tuning:** It configures `vm.swappiness` via both runtime (`sysctl -w`) and persistent (`/etc/sysctl.d/99-swappiness-debianito.conf`) mechanisms, defaulting to values that favor RAM usage over disk swapping (e.g., 10-20). 5. **Swappiness Tuning:** It configures `vm.swappiness` via both runtime (`sysctl -w`) and persistent (`/etc/sysctl.d/99-swappiness-debianito.conf`) mechanisms, defaulting to values that favor RAM usage over disk swapping (e.g., 10-20).
### 3. The Logical Decision Tree (Step by Step) ### 3. The Logical Decision Tree (Step by Step)
The execution flow follows a strict logical tree designed for safety and idempotency: The execution flow runs in a fixed order and is safe to repeat:
1. **Initialization & Locking:** 1. **Initialization & Locking:**
* The `manage_swap()` function attempts to acquire an exclusive lock (`flock -n`). If the lock is held by another process, it immediately exits with a "Busy" message to prevent conflicts. * The `manage_swap()` function attempts to acquire an exclusive lock (`flock -n`). If the lock is held by another process, it immediately exits with a "Busy" message to prevent conflicts.
@@ -58,7 +58,7 @@ Each option in the swap management submenu serves a specific technical purpose:
* **Option 1: Show current swap & swappiness** * **Option 1: Show current swap & swappiness**
* **Technical Action:** Aggregates data from `/proc/swaps`, `/proc/sys/vm/swappiness`, and `/etc/fstab`. * **Technical Action:** Aggregates data from `/proc/swaps`, `/proc/sys/vm/swappiness`, and `/etc/fstab`.
* **Significance:** Provides an audit trail of the current memory management state. It verifies if ZRAM is active (implied by priority check) and how much disk swap is currently in use. * **Significance:** Shows the current memory management state. It verifies if ZRAM is active (implied by priority check) and how much disk swap is currently in use.
* **Option 2: Create / resize swapfile** * **Option 2: Create / resize swapfile**
* **Technical Action:** Allocates a new block device file (`/swapfile`) or expands an existing one. Sets the `pri=10` flag to ensure it acts as a secondary memory layer after ZRAM fills up. * **Technical Action:** Allocates a new block device file (`/swapfile`) or expands an existing one. Sets the `pri=10` flag to ensure it acts as a secondary memory layer after ZRAM fills up.
@@ -70,7 +70,7 @@ Each option in the swap management submenu serves a specific technical purpose:
* **Option 4: Change swappiness** * **Option 4: Change swappiness**
* **Technical Action:** Modifies the kernel parameter `vm.swappiness`. * **Technical Action:** Modifies the kernel parameter `vm.swappiness`.
* **Significance:** Controls the "aggressiveness" of swapping. A lower value (e.g., 10) tells the kernel to keep data in RAM longer, only using swap as a last resort. This is critical for desktop performance and battery life on laptops. * **Significance:** Controls the "aggressiveness" of swapping. A lower value (e.g., 10) tells the kernel to keep data in RAM longer, only using swap as a last resort. This matters for desktop performance and battery life on laptops.
* **Option 5: Back to main menu** * **Option 5: Back to main menu**
* **Technical Action:** Releases the file lock (`exec 9>&-`) and terminates the submenu loop. * **Technical Action:** Releases the file lock (`exec 9>&-`) and terminates the submenu loop.
docs/system_info.md
+10 -10
View File
@@ -2,20 +2,20 @@
### 1. What Does This Component Do? ### 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 for the other menu options. Its primary function is to perform pre-flight hardware enumeration, OS validation, and environment checks in "cold" mode (before any configuration changes are made). This component performs the hardware enumeration, OS validation and environment checks that the rest of the script builds on. It runs in "cold" mode, before any configuration change is made, and the other menu options read the state it initializes instead of re-detecting everything.
**Initialization** (boot checks in `debianito.sh`, hardware state on demand via `_ensure_state_detected`): **Initialization** (boot checks in `debianito.sh`, hardware state on demand via `_ensure_state_detected`):
1. **Dependency auto-install**: The script checks for `whiptail` and `lsb-release`, installing them automatically if missing — ensuring the TUI and version detection work on minimal systems. 1. **Dependency auto-install**: The script checks for `whiptail` and `lsb-release`, installing them automatically if missing, so the TUI and version detection work on minimal systems.
2. **`lspci` guard and cache**: `command -v lspci &>/dev/null` validates availability before execution. If present, the full `lspci -nn` output is captured once into the global variable `LSPCI_OUTPUT`. All subsequent GPU, Ethernet, and network detection reads from this cache — avoiding redundant `lspci` invocations and ensuring consistent data throughout the session. 2. **`lspci` guard and cache**: `command -v lspci &>/dev/null` validates availability before execution. If present, the full `lspci -nn` output is captured once into the global variable `LSPCI_OUTPUT`. All subsequent GPU, Ethernet, and network detection reads from this cache, avoiding redundant `lspci` invocations and keeping the data consistent throughout the session.
3. **APT update deduplication**: The helper `_ensure_apt_updated` prevents redundant `apt update` calls by tracking whether the package lists have been refreshed recently. This is critical for performance when multiple modules (repos, firmware, GPU, kernel) each need to verify repository state. 3. **APT update deduplication**: The helper `_ensure_apt_updated` prevents redundant `apt update` calls by tracking whether the package lists have been refreshed recently. This matters for performance when multiple modules (repos, firmware, GPU, kernel) each need to verify repository state.
4. **State refresh flag**: `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring that each menu entry starts with a clean, consistent state rather than stale cached data. 4. **State refresh flag**: `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring that each menu entry starts with a clean, consistent state rather than stale cached data.
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. The variables it populates (`DEBIAN_VERSION`, `GPU_TYPE`, `CPU_SUMMARY`, network interface states) give the later menu options real context, so the user is not asked to make blind decisions: installing proprietary drivers on hardware that is not there, or selecting repositories that do not match the current Debian codename.
### 2. System Commands Used (Technical Mapping) ### 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. The table below maps each piece of diagnostic data to the standard Linux tool `utils.sh` reads it from; none of it needs proprietary binaries.
| Feature | Command / Tool | Technical Purpose & Logic | | Feature | Command / Tool | Technical Purpose & Logic |
| :--- | :--- | :--- | | :--- | :--- | :--- |
@@ -28,15 +28,15 @@ The following table details the native Linux tools and file descriptors utilized
| **Storage** | `lsblk -d -o NAME,SIZE,ROTA` | Distinguishes between NVMe (`nvme`), SSD (RoT=0), and HDD (RoT=1) to provide storage topology summary. | | **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. | | **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 ### 3. Why Detection Matters
This diagnostic phase is vital for engineering stability and user experience (UX) integrity within the script architecture: Each check protects a different part of the script:
* **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. * **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. * **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.
* **APT Update Deduplication:** The `_ensure_apt_updated` helper tracks whether `apt update` has been run recently. Multiple modules (repos, firmware, GPU, kernel) share a single update cycle, preventing redundant network calls and inconsistent package state between modules. * **APT Update Deduplication:** The `_ensure_apt_updated` helper tracks whether `apt update` has been run recently. Multiple modules (repos, firmware, GPU, kernel) share a single update cycle, preventing redundant network calls and inconsistent package state between modules.
* **State Refresh Consistency:** `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring each menu entry starts with a clean state and preventing stale variable propagation between sequential selections. * **State Refresh Consistency:** `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring each menu entry starts with a clean state and preventing stale variable propagation between sequential selections.
* **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. * **Time Synchronization Safety:** The `check_system_time` function prevents package installation failures caused by clock skew, which breaks APT's GPG signatures. It offers an automated NTP sync before proceeding so the signatures verify again.
* **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. * **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 ### 4. Formatting and UX in the Terminal
@@ -46,4 +46,4 @@ The raw data collected by these functions is processed into a human-readable for
* **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. * **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. * **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 lspci &>/dev/null` guards GPU detection, `if ! command -v ip &>/dev/null` guards network data). If tools are missing, it gracefully degrades to a warning message rather than crashing the TUI. When `lspci` is present, its output is cached in `LSPCI_OUTPUT` for all subsequent detection calls. * **Conditional Rendering:** The script checks for command availability (e.g., `if ! command -v lspci &>/dev/null` guards GPU detection, `if ! command -v ip &>/dev/null` guards network data). If tools are missing, it gracefully degrades to a warning message rather than crashing the TUI. When `lspci` is present, its output is cached in `LSPCI_OUTPUT` for all subsequent detection calls.
* **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. * **TUI Integration:** The final formatted string is passed to `_msg`, which wraps the output in a `whiptail --msgbox`. This makes the diagnostic information appear as a modal dialog with consistent dimensions and styling (colors defined globally in `debianito.sh`), regardless of the underlying terminal emulator.
docs/system_prefs.md
+17 -17
View File
@@ -2,7 +2,7 @@
## 1. What Does This Component Do? ## 1. What Does This Component Do?
The **System Preferences** module (`modules/system/system_prefs.sh` + `modules/system/audio.sh`) consolidates first-boot personalization into a single menu. It is the only place in Debianito where **locale, timezone, and audio** are configured together — settings that Debian's installer often leaves at generic defaults and that affect every subsequent module. The **System Preferences** module (`modules/system/system_prefs.sh` + `modules/system/audio.sh`) consolidates first-boot personalization into a single menu. It is the only place in Debianito where locale, timezone and audio are configured together, settings that Debian's installer often leaves at generic defaults and that affect every subsequent module.
It groups three independent preference domains behind one entry point: It groups three independent preference domains behind one entry point:
@@ -12,7 +12,7 @@ It groups three independent preference domains behind one entry point:
| **Language, Locales & Keyboard** | `system_prefs.sh:_prefs_locale_keyboard` | `locales`, `keyboard-configuration` | | **Language, Locales & Keyboard** | `system_prefs.sh:_prefs_locale_keyboard` | `locales`, `keyboard-configuration` |
| **Audio & Sound Stack** | `system/audio.sh:_prefs_audio_menu` | PipeWire, ALSA, pavucontrol, pulsemixer, playerctl | | **Audio & Sound Stack** | `system/audio.sh:_prefs_audio_menu` | PipeWire, ALSA, pavucontrol, pulsemixer, playerctl |
The menu itself is `_system_preferences_menu` in `system_prefs.sh` — a simple `while true` loop with `whiptail --menu`: The menu itself is `_system_preferences_menu` in `system_prefs.sh`, a simple `while true` loop with `whiptail --menu`:
``` ```
1 Date, Time & Timezone 1 Date, Time & Timezone
@@ -40,7 +40,7 @@ Timezone: America/Santiago
**What it does technically:** **What it does technically:**
1. Prints the current date/time (`date '+%Y-%m-%d %H:%M'`) and timezone (`timedatectl show -p Timezone --value`). 1. Prints the current date/time (`date '+%Y-%m-%d %H:%M'`) and timezone (`timedatectl show -p Timezone --value`).
2. Prompts via `_confirm "Timezone"` to run `sudo dpkg-reconfigure tzdata` — the Debian-standard interactive timezone selector (ncurses). 2. Prompts via `_confirm "Timezone"` to run `sudo dpkg-reconfigure tzdata`, the Debian-standard interactive timezone selector (ncurses).
3. Calls `_ensure_time_synced` from `utils.sh` regardless of the answer: 3. Calls `_ensure_time_synced` from `utils.sh` regardless of the answer:
- Forces `timedatectl set-ntp true` - Forces `timedatectl set-ntp true`
- Validates the timezone is not `n/a` or `Etc/UTC`; if it is and a display is available, opens `tzdata` again - Validates the timezone is not `n/a` or `Etc/UTC`; if it is and a display is available, opens `tzdata` again
@@ -62,12 +62,12 @@ sudo dpkg-reconfigure keyboard-configuration
**What it does technically:** **What it does technically:**
- **`dpkg-reconfigure locales`** — Opens the Debian locales selector (e.g., `en_US.UTF-8`, `es_CL.UTF-8`). Generates the selected locales via `locale-gen` and updates `/etc/default/locale`. No reboot is required, but a re-login is needed for the new `LANG` to take effect. - **`dpkg-reconfigure locales`**: Opens the Debian locales selector (e.g., `en_US.UTF-8`, `es_CL.UTF-8`). Generates the selected locales via `locale-gen` and updates `/etc/default/locale`. No reboot is required, but a re-login is needed for the new `LANG` to take effect.
- **`dpkg-reconfigure keyboard-configuration`** — Configures `/etc/default/keyboard` (`XKBMODEL`, `XKBLAYOUT`, `XKBVARIANT`, `XKBOPTIONS`) and, on console, the keymap via `setupcon`. This affects both X11/Wayland and TTY. - **`dpkg-reconfigure keyboard-configuration`**: Configures `/etc/default/keyboard` (`XKBMODEL`, `XKBLAYOUT`, `XKBVARIANT`, `XKBOPTIONS`) and, on console, the keymap via `setupcon`. This affects both X11/Wayland and TTY.
Both commands are run with `env LC_ALL=C LANGUAGE=C` to guarantee the debconf dialogs render in English even when the current locale is broken. Both commands are run with `env LC_ALL=C LANGUAGE=C` to guarantee the debconf dialogs render in English even when the current locale is broken.
This option has **no detection logic** — it delegates entirely to Debian's standard tools. It is idempotent and safe to run repeatedly. This option has **no detection logic**: it delegates entirely to Debian's standard tools. It is idempotent and safe to run repeatedly.
--- ---
@@ -91,7 +91,7 @@ items+=("playerctl" "Multimedia key controller (playerctl)" $state)
``` ```
- **`_state <pkg>`** (in `utils.sh`) returns `ON` if `dpkg -l <pkg>` shows `^ii`, otherwise `OFF`. - **`_state <pkg>`** (in `utils.sh`) returns `ON` if `dpkg -l <pkg>` shows `^ii`, otherwise `OFF`.
- **`_is_headless`** returns true when both `$DISPLAY` and `$WAYLAND_DISPLAY` are empty — in that case `pavucontrol` is hidden because it requires a GUI. - **`_is_headless`** returns true when both `$DISPLAY` and `$WAYLAND_DISPLAY` are empty; in that case `pavucontrol` is hidden because it requires a GUI.
- Package name for PipeWire varies by Debian version: - Package name for PipeWire varies by Debian version:
- Debian 11 Bullseye → `pipewire` (the `pipewire-audio` metapackage does not exist) - Debian 11 Bullseye → `pipewire` (the `pipewire-audio` metapackage does not exist)
- Debian 12/13 → `pipewire-audio` - Debian 12/13 → `pipewire-audio`
@@ -100,7 +100,7 @@ The checklist is shown via `whiptail --checklist` with the title **"Audio & Soun
#### 4.2 PipeWire Installation Logic: `_install_pipewire_standard` #### 4.2 PipeWire Installation Logic: `_install_pipewire_standard`
This function handles the **PipeWire Audio Stack with Bluetooth Hi-Res codecs** — the core of modern Linux audio. This function handles the **PipeWire Audio Stack with Bluetooth Hi-Res codecs**.
**Codec package resolution:** **Codec package resolution:**
@@ -147,7 +147,7 @@ systemctl --user restart wireplumber pipewire pipewire-pulse
| --------- | --------- | --------------- | | --------- | --------- | --------------- |
| `alsa-utils` + `alsa-ucm-conf` | ALSA CLI tools (`aplay`, `amixer`, `alsamixer`) and UCM configs for modern sound cards | `is_installed alsa-utils` | | `alsa-utils` + `alsa-ucm-conf` | ALSA CLI tools (`aplay`, `amixer`, `alsamixer`) and UCM configs for modern sound cards | `is_installed alsa-utils` |
| `pavucontrol` | GTK GUI volume control (PulseAudio/PipeWire compatible). Hidden in headless mode. | `is_installed pavucontrol` | | `pavucontrol` | GTK GUI volume control (PulseAudio/PipeWire compatible). Hidden in headless mode. | `is_installed pavucontrol` |
| `pulsemixer` | Terminal (ncurses) mixer — works in TTY and headless | `is_installed pulsemixer` | | `pulsemixer` | Terminal (ncurses) mixer, works in TTY and headless | `is_installed pulsemixer` |
| `playerctl` | MPRIS CLI to control media players via keyboard shortcuts | `is_installed playerctl` | | `playerctl` | MPRIS CLI to control media players via keyboard shortcuts | `is_installed playerctl` |
Each package is installed via `_run_install <pkg>` which confirms the version via `apt-cache policy` before installing. Each package is installed via `_run_install <pkg>` which confirms the version via `apt-cache policy` before installing.
@@ -188,10 +188,10 @@ Each package is installed via `_run_install <pkg>` which confirms the version vi
## 6. Integration with Other Modules ## 6. Integration with Other Modules
- **Firmware (`firmware.sh`)** — Bluetooth firmware packages (`firmware-iwlwifi`, etc.) are separate from the Bluetooth *stack* (`bluez`). This menu complements firmware by ensuring the audio side of Bluetooth (PipeWire codecs) is ready. - **Firmware (`firmware.sh`)**: Bluetooth firmware packages (`firmware-iwlwifi`, etc.) are separate from the Bluetooth *stack* (`bluez`). This menu complements firmware by ensuring the audio side of Bluetooth (PipeWire codecs) is ready.
- **Desktop & Display (`desktop_display.sh`)** — XFCE/LXDE installations often need audio configured afterwards. Running System Preferences → Audio after a new desktop ensures the correct mixer is available. - **Desktop & Display (`desktop_display.sh`)**: New desktop installations (XFCE, LXDE, GNOME or KDE Plasma) often need audio configured afterwards. Running System Preferences → Audio after a new desktop ensures the correct mixer is available.
- **Gaming (`gaming.sh`)** — Many games require PipeWire/PulseAudio for voice chat. The gaming module assumes audio is already functional. - **Gaming (`gaming.sh`)**: Many games require PipeWire/PulseAudio for voice chat. The gaming module assumes audio is already functional.
- **Time sync (`utils.sh:_ensure_time_synced`)** — Also called automatically before the first `apt update`. This menu is the manual override. - **Time sync (`utils.sh:_ensure_time_synced`)**: Also called automatically before the first `apt update`. This menu is the manual override.
--- ---
@@ -210,7 +210,7 @@ Each package is installed via `_run_install <pkg>` which confirms the version vi
## References ## References
- [Debian TimeZone Config — wiki.debian.org/TimeZoneChanges](https://wiki.debian.org/TimeZoneChanges) - [Debian TimeZone Config: wiki.debian.org/TimeZoneChanges](https://wiki.debian.org/TimeZoneChanges)
- [Debian Locales — wiki.debian.org/Locale](https://wiki.debian.org/Locale) - [Debian Locales: wiki.debian.org/Locale](https://wiki.debian.org/Locale)
- [PipeWire — wiki.debian.org/PipeWire](https://wiki.debian.org/PipeWire) - [PipeWire: wiki.debian.org/PipeWire](https://wiki.debian.org/PipeWire)
- [PipeWire Bluetooth Codecs — GitLab PipeWire wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#bluetooth) - [PipeWire Bluetooth Codecs: GitLab PipeWire wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#bluetooth)
docs/user_priv_feed.md
+8 -8
View File
@@ -2,9 +2,9 @@
### 1. What does this component do? ### 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). This module prepares a normal user account for day-to-day administration on a fresh Debian installation, or on one where `sudo` usage has been mishandled. Debian gives a standard user no administrative rights by default, so routine work such as installing software would ask for a password each time; this menu closes that gap and fixes the ownership and feedback annoyances that come with fresh setups.
At a high level, it manages four critical aspects of user privilege: It manages four aspects of user privileges:
1. **Elevated Permissions:** Ensures the current user has membership in the `sudo` group. 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. 2. **Workflow Efficiency:** Configures specific commands to run without authentication (NOPASSWD) for maintenance tasks.
@@ -13,7 +13,7 @@ At a high level, it manages four critical aspects of user privilege:
### 2. What exactly does it do and why ### 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: The script executes a sub-menu loop that allows the user to toggle between four distinct configurations. Each option fixes a specific annoyance in Linux administration:
* **Sudo Group Membership (Option 1):** * **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`. * **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`.
@@ -83,13 +83,13 @@ The execution flow is governed by `sudo_config.sh`, which acts as a state machin
* *On Confirm:* Write `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback`. * *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. * **Step B:** Verify write permission. If successful, notify success; otherwise, log error and return status 1.
### 4. Compatibility with all Debian ### 4. Compatibility Across Debian Versions
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. The module works across the Debian family (Bullseye, Bookworm, Trixie) because it only uses standard POSIX tools and handles paths strictly.
* **Architecture Independence:** The script utilizes `usermod`, `chown`, and `grep` which are available on all x86_64, arm64, and i386 Debian architectures. * **Architecture Independence:** The script uses `usermod`, `chown`, and `grep`, which are available on all x86_64, arm64, and i386 Debian architectures.
* **Version Agnosticism (Debian 11+):** * **Version Independence (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. * **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. * **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. * **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. * **Importance:** Users can move between Debian releases (e.g., from 11 to 12) without reconfiguring these privileges by hand.
docs/zram.md
+18 -18
View File
@@ -1,10 +1,10 @@
# Option 9: ZRAM Configuration & Memory Optimization # Option 9: ZRAM Configuration & Memory Optimization
## 1. The Science of ZRAM vs. Traditional Swap ## 1. ZRAM vs. Traditional Swap
### Core Concept: CPU Cycles vs. Disk I/O ### Core Concept: CPU Cycles vs. Disk I/O
Traditional swap storage operates on a fundamental latency gap that becomes critical under memory pressure: Traditional swap has a latency gap that matters under memory pressure:
| Storage Medium | Latency Range | Write Amplification | SSD Wear Impact | | Storage Medium | Latency Range | Write Amplification | SSD Wear Impact |
| --------------- | --------------- | --------------------- | ----------------- | | --------------- | --------------- | --------------------- | ----------------- |
@@ -27,19 +27,19 @@ ZRAM creates a compressed block device entirely within physical memory. When pag
2. **Stored in RAM pool** at compressed size (typically 2:1 to 3:1 ratio) 2. **Stored in RAM pool** at compressed size (typically 2:1 to 3:1 ratio)
3. **Decompressed instantly** when needed (microseconds vs milliseconds) 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. The trade is CPU cycles for less I/O latency. Modern CPUs compress and decompress pages in microseconds, which is far cheaper than any disk operation.
### Why Only LZ4 and ZSTD? ### Why Only LZ4 and ZSTD?
The script offers only two algorithms because they represent the optimal balance points: The script offers only two algorithms because they hit the best balance of speed and ratio:
| Algorithm | Compression Ratio | Speed | CPU Overhead | Best Use Case | | Algorithm | Compression Ratio | Speed | CPU Overhead | Best Use Case |
|-----------|------------------|-------|--------------|---------------| |-----------|------------------|-------|--------------|---------------|
| **LZ4** | ~2:1–3:1 | Fastest | Lowest | Gaming, real-time workloads | | **LZ4** | ~2:1–3:1 | Fastest | Lowest | Gaming, real-time workloads |
| **ZSTD** | ~3:1–5:1 | Medium | Moderate | General use, better memory savings | | **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). - **LZ4**: Prioritizes speed over compression ratio. Best when CPU is limited or latency matters (gaming servers).
- **ZSTD**: Offers superior compression ratios with acceptable overhead. Best for systems prioritizing maximum effective RAM capacity. - **ZSTD**: Compresses more at acceptable overhead. Best when the goal is maximum effective RAM.
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. 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.
@@ -49,7 +49,7 @@ By intercepting swap writes before they reach physical storage:
- **Write Reduction**: Pages that would write to disk now compress in RAM - **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 - **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) - **System Longevity**: Matters for systems with limited SSD endurance (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."* As the Linux kernel documentation states: *"Users with SSDs as swap devices can extend device lifespan by drastically reducing writes that shorten its life."*
@@ -59,7 +59,7 @@ As the Linux kernel documentation states: *"Users with SSDs as swap devices can
### Pipeline Execution Sequence ### Pipeline Execution Sequence
The script follows a deterministic flow to ensure safe, reproducible configuration: The script follows a fixed sequence:
``` ```
┌─────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────┐
@@ -107,7 +107,7 @@ The script follows a deterministic flow to ensure safe, reproducible configurati
└─────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────┘
``` ```
### Mathematical Size Calculation ### Size Formula
The script uses this formula to determine ZRAM size: The script uses this formula to determine ZRAM size:
@@ -126,7 +126,7 @@ fi
- `/ 1024 / 1024`: Convert KB to GB - `/ 1024 / 1024`: Convert KB to GB
- `+ 1`: Add rounding buffer for odd values - `+ 1`: Add rounding buffer for odd values
- **≤8 GB**: Target 50% of total RAM (generous swap for low-memory systems) - **≤8 GB**: Target 50% of total RAM (generous swap for low-memory systems)
- **>8 GB**: Fixed 4096 MB — avoids excessive RAM reservation on high-memory machines while still providing meaningful swap space - **>8 GB**: Fixed 4096 MB, which avoids excessive RAM reservation on high-memory machines while still providing meaningful swap space
**Examples:** **Examples:**
@@ -168,20 +168,20 @@ This prevents thrashing where pages bounce between slow disk swap and fast RAM-b
### How ZRAM Coexists with Disk Swap ### How ZRAM Coexists with Disk Swap
The script does **not** hardcode `vm.swappiness` or watermark tuning. Instead, it uses a **priority-based swap hierarchy** combined with an explicit swappiness control in the Swap module: The script does **not** hardcode `vm.swappiness` or watermark tuning. It uses a priority-based swap hierarchy combined with explicit swappiness control in the Swap module:
| Swap Device | Priority | Config Location | When It Is Used | | Swap Device | Priority | Config Location | When It Is Used |
|-------------|----------|-----------------|-----------------| |-------------|----------|-----------------|-----------------|
| **ZRAM** | `100` | `/etc/default/zramswap` (`PRIORITY=100`) | **First** — kernel prefers higher priority | | **ZRAM** | `100` | `/etc/default/zramswap` (`PRIORITY=100`) | **First**: kernel prefers higher priority |
| **Disk swapfile** (`/swapfile`) | `10` | `/etc/fstab` (`pri=10`) + `# debianito-managed-swap` tag | **Second** — only after ZRAM device is full | | **Disk swapfile** (`/swapfile`) | `10` | `/etc/fstab` (`pri=10`) + `# debianito-managed-swap` tag | **Second**: only after ZRAM device is full |
This is implemented in `zram.sh:_zram_create` (writes `PRIORITY=100`) and `swap.sh:_swap_create_file` (writes `pri=10`). Priority is the canonical Linux `swapon` mechanism: `swapon --show` lists `PRIO` and the kernel always fills the highest-priority device first. This is implemented in `zram.sh:_zram_create` (writes `PRIORITY=100`) and `swap.sh:_swap_create_file` (writes `pri=10`). Priority is the canonical Linux `swapon` mechanism: `swapon --show` lists `PRIO` and the kernel always fills the highest-priority device first.
### Swappiness Is Managed Separately ### Swappiness Is Managed Separately
Swappiness (`vm.swappiness`, 0–100, default 60 on Debian) controls **how eagerly the kernel swaps at all**, regardless of which device is preferred. Swappiness (`vm.swappiness`, 0–100, default 60 on Debian) controls how eagerly the kernel swaps at all, regardless of which device is preferred.
- The ZRAM module **does not change swappiness**. Changing it would affect both ZRAM and disk swap in ways that are workload-specific. - The ZRAM module does not change swappiness. Changing it would affect both ZRAM and disk swap in ways that are workload-specific.
- To tune it, use **Option 10 → Swap Management → 4. Change swappiness** (`swap.sh:_swap_set_swappiness`): - To tune it, use **Option 10 → Swap Management → 4. Change swappiness** (`swap.sh:_swap_set_swappiness`):
```bash ```bash
@@ -194,10 +194,10 @@ Swappiness (`vm.swappiness`, 0–100, default 60 on Debian) controls **how eager
- Recommended starting points (not enforced by the script): - Recommended starting points (not enforced by the script):
- **General desktop**: `60` (Debian default) - **General desktop**: `60` (Debian default)
- **Gaming / 8 GB or less**: `80–100` — allows ZRAM to be used earlier, trading CPU for reduced disk I/O - **Gaming / 8 GB or less**: `80–100`, which allows ZRAM to be used earlier, trading CPU for reduced disk I/O
- **ZRAM-only, no disk swap**: `100–150` is safe because swap *is* RAM (compressed); there is no SSD wear cost - **ZRAM-only, no disk swap**: `100–150` is safe because swap *is* RAM (compressed); there is no SSD wear cost
> **Previous documentation** recommended `vm.swappiness = 180` plus `watermark_*` and `page-cluster` tuning for ZRAM. Those values are **not written by the current script** and are omitted here to avoid drifting from the implemented behavior. If you need watermark tuning, add it manually to `/etc/sysctl.d/` and validate with your workload. > **Previous documentation** recommended `vm.swappiness = 180` plus `watermark_*` and `page-cluster` tuning for ZRAM. The current script does not write those values; they are omitted here so this document matches the implementation. If you need watermark tuning, add it manually to `/etc/sysctl.d/` and validate with your workload.
### Verifying the Hierarchy ### Verifying the Hierarchy
@@ -280,7 +280,7 @@ watch -n 5 'free -h && zramctl'
### Permanent Configuration ### 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: 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. The following also loads the kernel module:
```bash ```bash
echo "zram" | sudo tee /etc/modules-load.d/zram.conf echo "zram" | sudo tee /etc/modules-load.d/zram.conf
modules/desktop_display.sh
+24 -9
View File
@@ -299,6 +299,29 @@ configure_gdm3() {
done done
} }
# Ordered session candidates for SDDM autologin:
# Wayland first, then X11, per release. Existence
# decides (no codename gates). The LXQt sessions
# stay last for when the module starts offering LXQt.
_sddm_session_candidates() {
local wayland_dir="${SESSION_DIR_WAYLAND:-/usr/share/wayland-sessions}"
local x11_dir="${SESSION_DIR_X11:-/usr/share/xsessions}"
local candidate
for candidate in \
"$wayland_dir/plasmawayland.desktop" \
"$wayland_dir/plasma.desktop" \
"$x11_dir/plasma.desktop" \
"$x11_dir/plasmax11.desktop" \
"$wayland_dir/lxqt-wayland.desktop" \
"$x11_dir/lxqt.desktop"; do
if [ -f "$candidate" ]; then
basename "$candidate" .desktop
return 0
fi
done
return 0
}
configure_sddm() { configure_sddm() {
while true; do while true; do
local choice local choice
@@ -317,19 +340,11 @@ configure_sddm() {
;; ;;
2) 2)
local sddm_session="" local sddm_session=""
sddm_session=$(_sddm_session_candidates)
local sddm_user="${SUDO_USER:-}" local sddm_user="${SUDO_USER:-}"
if [ -z "$sddm_user" ] || [ "$sddm_user" = "root" ]; then if [ -z "$sddm_user" ] || [ "$sddm_user" = "root" ]; then
sddm_user=$(awk -F: '$3>=1000 && $3<65534 {print $1}' /etc/passwd | head -1) sddm_user=$(awk -F: '$3>=1000 && $3<65534 {print $1}' /etc/passwd | head -1)
fi fi
if [ -f /usr/share/wayland-sessions/plasmawayland.desktop ]; then
sddm_session="plasmawayland"
elif [ -f /usr/share/wayland-sessions/lxqt-wayland.desktop ]; then
sddm_session="lxqt-wayland"
elif [ -f /usr/share/xsessions/plasma.desktop ]; then
sddm_session="plasma"
elif [ -f /usr/share/xsessions/lxqt.desktop ]; then
sddm_session="lxqt"
fi
sudo mkdir -p /etc/sddm.conf.d sudo mkdir -p /etc/sddm.conf.d
cat <<EOF | sudo tee /etc/sddm.conf.d/autologin.conf >/dev/null cat <<EOF | sudo tee /etc/sddm.conf.d/autologin.conf >/dev/null
[Autologin] [Autologin]
modules/desktops/desktop_gnome.sh
+48 -19
View File
@@ -4,26 +4,51 @@
# Debian ships GNOME 48 (13), 43 (12) and 3.38 (11). # Debian ships GNOME 48 (13), 43 (12) and 3.38 (11).
# License GPL v3 # License GPL v3
gnome_menu() { # Pick the terminal emulator for this release. gnome-core
local choice # declares the OR-dependency "gnome-terminal (>= 3.56) or
choice=$(_radiolist "GNOME" \ # gnome-console (>= 46) or ptyxis (>= 47)" (packages.debian.org
"Select an option:" $TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA \ # /trixie/gnome-core, verified 2026-10-16) and apt resolves an
"1" "GNOME (Full Desktop)" OFF \ # unset OR-dep with the FIRST alternative, so gnome-core alone
"2" "GNOME Core (Minimal Install)" OFF \ # would pull gnome-terminal. Listing ptyxis in the same apt
"3" "Back" OFF) # transaction satisfies the OR-dep with ptyxis instead. ptyxis
[ -z "$choice" ] && return 0 # (GTK4) exists in trixie (48.5-1~deb13u1) but NOT in bookworm
clear # (packages.debian.org/bookworm/ptyxis → no such package), hence
case "$(echo "$choice" | tr -d '"')" in # the trixie-only gate. An already-installed gnome-terminal is
1) _install_gnome_full ;; # left alone: both can coexist; no purge is ever attempted.
2) _install_gnome_core ;; _gnome_terminal_pkg() {
3) return 0 ;; case "${DEBIAN_CODENAME:-}" in
trixie) printf '%s\n' "ptyxis" ;;
*) printf '%s\n' "gnome-terminal" ;;
esac esac
} }
gnome_menu() {
while true; do
local -a gn_items=()
gn_items+=("1" "GNOME (Full Desktop)")
gn_items+=("2" "GNOME Core (Minimal Install)")
gn_items+=("3" "Back")
local choice
choice=$(_menu "GNOME" \
"Select an option:" $TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA \
"${gn_items[@]}")
[ -z "$choice" ] && break
clear
case "$choice" in
1) _install_gnome_full ;;
2) _install_gnome_core ;;
3) break ;;
esac
done
}
_install_gnome_full() { _install_gnome_full() {
# Pre-apply summary: confirm the selection before any # Pre-apply summary: confirm the selection before any
# debconf or apt transaction starts. # debconf or apt transaction starts. The terminal package
_confirm_install_list "GNOME Full Desktop" gnome gdm3 || return # is resolved once (ptyxis on trixie, gnome-terminal
# elsewhere) so the summary lists what apt will install.
local terminal_pkg
terminal_pkg=$(_gnome_terminal_pkg)
_confirm_install_list "GNOME Full Desktop" gnome gdm3 "$terminal_pkg" || return
echo -e "${GREEN}Installing GNOME (Full Desktop)...${NC}" echo -e "${GREEN}Installing GNOME (Full Desktop)...${NC}"
@@ -37,7 +62,7 @@ _install_gnome_full() {
fi fi
echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections
_ensure_apt_updated _ensure_apt_updated
_run_cmd "GNOME Full" "sudo apt install -y gnome gdm3" \ _run_cmd "GNOME Full" "sudo apt install -y gnome gdm3 $terminal_pkg" \
"Installing GNOME (Full Meta Package) + GDM3..." "Installing GNOME (Full Meta Package) + GDM3..."
if [ "$target_dm" = "gdm3" ]; then if [ "$target_dm" = "gdm3" ]; then
sudo systemctl enable gdm3 sudo systemctl enable gdm3
@@ -51,8 +76,12 @@ _install_gnome_full() {
_install_gnome_core() { _install_gnome_core() {
# Pre-apply summary: confirm the selection before any # Pre-apply summary: confirm the selection before any
# debconf or apt transaction starts. # debconf or apt transaction starts. The terminal package
_confirm_install_list "GNOME Core" gnome-core gdm3 || return # is resolved once (ptyxis on trixie, gnome-terminal
# elsewhere) so the summary lists what apt will install.
local terminal_pkg
terminal_pkg=$(_gnome_terminal_pkg)
_confirm_install_list "GNOME Core" gnome-core gdm3 "$terminal_pkg" || return
echo -e "${GREEN}Installing GNOME Core (Minimal)...${NC}" echo -e "${GREEN}Installing GNOME Core (Minimal)...${NC}"
@@ -66,7 +95,7 @@ _install_gnome_core() {
fi fi
echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections
_ensure_apt_updated _ensure_apt_updated
_run_cmd "GNOME Core" "sudo apt install -y gnome-core gdm3" \ _run_cmd "GNOME Core" "sudo apt install -y gnome-core gdm3 $terminal_pkg" \
"Installing GNOME Core (Minimal) + GDM3..." "Installing GNOME Core (Minimal) + GDM3..."
if [ "$target_dm" = "gdm3" ]; then if [ "$target_dm" = "gdm3" ]; then
sudo systemctl enable gdm3 sudo systemctl enable gdm3
modules/desktops/desktop_kde.sh
+135 -21
View File
@@ -1,30 +1,66 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# desktop_kde.sh — KDE Plasma desktop installer (SP2) # desktop_kde.sh — KDE Plasma desktop installer (SP2)
# Full: kde-standard + sddm | Minimal: kde-plasma-desktop + sddm # Full: kde-standard + sddm | Minimal: kde-plasma-desktop + sddm
# Bookworm ships Plasma 5.27.5; Wayland is the default # Custom: kde-plasma-desktop + sddm + konsole + extras elegidos
# session since Debian 12. # bookworm: Plasma 5.27.5 / KF5 / Qt5; SDDM defaults to
# X11 (plasma.desktop in xsessions); Wayland is optional
# via plasma-workspace-wayland (plasmawayland.desktop).
# trixie: Plasma 6.3.6 / KF6 / Qt6; Wayland is the
# primary session (plasma.desktop in wayland-sessions),
# X11 the alternative (plasmax11.desktop). sddm is only
# Recommends in the meta-kde chain, so the explicit sddm
# in both routes is what guarantees the DM (and
# xserver-xorg/xauth, hard deps of sddm in both releases).
# License GPL v3 # License GPL v3
kde_menu() { # plasma-workspace-wayland exists only on bookworm:
local choice # bookworm's plasma-workspace ships the X11 session only,
choice=$(_radiolist "KDE Plasma" \ # and the Wayland session (plasmawayland.desktop) lives
"Select an option:" $TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA \ # in this separate package (a Recommends of plasma-desktop,
"1" "KDE Plasma (Full Desktop)" OFF \ # listed explicitly for the same determinism as the
"2" "KDE Plasma Desktop (Minimal)" OFF \ # explicit sddm). trixie integrates Wayland into
"3" "Back" OFF) # plasma-workspace itself and the package does not exist
[ -z "$choice" ] && return 0 # there (packages.debian.org/trixie/plasma-workspace-wayland),
clear # so naming it off-bookworm would fail the apt transaction.
case "$(echo "$choice" | tr -d '"')" in _kde_wayland_pkg() {
1) _install_kde_full ;; case "${DEBIAN_CODENAME:-}" in
2) _install_kde_minimal ;; bookworm) printf '%s\n' "plasma-workspace-wayland" ;;
3) return 0 ;; *) printf '%s\n' "" ;;
esac esac
} }
kde_menu() {
while true; do
local -a kd_items=()
kd_items+=("1" "KDE Plasma (Full Desktop)")
kd_items+=("2" "KDE Plasma Desktop (Minimal)")
kd_items+=("3" "KDE Custom (Choose packages)")
kd_items+=("4" "Back")
local choice
choice=$(_menu "KDE Plasma" \
"Select an option:" $TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA \
"${kd_items[@]}")
[ -z "$choice" ] && break
clear
case "$choice" in
1) _install_kde_full ;;
2) _install_kde_minimal ;;
3) _install_kde_custom ;;
4) break ;;
esac
done
}
_install_kde_full() { _install_kde_full() {
# Pre-apply summary: confirm the selection before any # Pre-apply summary: confirm the selection before any
# debconf or apt transaction starts. # debconf or apt transaction starts. The Wayland
_confirm_install_list "KDE Plasma Full" kde-standard sddm || return # session package is resolved once (bookworm only;
# the package does not exist on trixie) so the
# summary lists exactly what apt will install.
local wayland_pkg
wayland_pkg=$(_kde_wayland_pkg)
local -a pkgs=(kde-standard sddm)
[ -n "$wayland_pkg" ] && pkgs+=("$wayland_pkg")
_confirm_install_list "KDE Plasma Full" "${pkgs[@]}" || return
echo -e "${GREEN}Installing KDE Plasma (Full)...${NC}" echo -e "${GREEN}Installing KDE Plasma (Full)...${NC}"
@@ -38,7 +74,7 @@ _install_kde_full() {
fi fi
echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections
_ensure_apt_updated _ensure_apt_updated
_run_cmd "KDE Full" "sudo apt install -y kde-standard sddm" \ _run_cmd "KDE Full" "sudo apt install -y ${pkgs[*]}" \
"Installing KDE Plasma (Full Meta Package) + SDDM..." "Installing KDE Plasma (Full Meta Package) + SDDM..."
if [ "$target_dm" = "sddm" ]; then if [ "$target_dm" = "sddm" ]; then
sudo systemctl enable sddm sudo systemctl enable sddm
@@ -52,8 +88,15 @@ _install_kde_full() {
_install_kde_minimal() { _install_kde_minimal() {
# Pre-apply summary: confirm the selection before any # Pre-apply summary: confirm the selection before any
# debconf or apt transaction starts. # debconf or apt transaction starts. The Wayland
_confirm_install_list "KDE Plasma Minimal" kde-plasma-desktop sddm || return # session package is resolved once (bookworm only;
# the package does not exist on trixie) so the
# summary lists exactly what apt will install.
local wayland_pkg
wayland_pkg=$(_kde_wayland_pkg)
local -a pkgs=(kde-plasma-desktop sddm)
[ -n "$wayland_pkg" ] && pkgs+=("$wayland_pkg")
_confirm_install_list "KDE Plasma Minimal" "${pkgs[@]}" || return
echo -e "${GREEN}Installing KDE Plasma Desktop (Minimal)...${NC}" echo -e "${GREEN}Installing KDE Plasma Desktop (Minimal)...${NC}"
@@ -67,7 +110,7 @@ _install_kde_minimal() {
fi fi
echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections
_ensure_apt_updated _ensure_apt_updated
_run_cmd "KDE Minimal" "sudo apt install -y kde-plasma-desktop sddm" \ _run_cmd "KDE Minimal" "sudo apt install -y ${pkgs[*]}" \
"Installing KDE Plasma Desktop (Minimal) + SDDM..." "Installing KDE Plasma Desktop (Minimal) + SDDM..."
if [ "$target_dm" = "sddm" ]; then if [ "$target_dm" = "sddm" ]; then
sudo systemctl enable sddm sudo systemctl enable sddm
@@ -78,3 +121,74 @@ _install_kde_minimal() {
echo -e "${GREEN}KDE Plasma Desktop installed. Default display manager: ${target_dm}.${NC}" echo -e "${GREEN}KDE Plasma Desktop installed. Default display manager: ${target_dm}.${NC}"
_offer_pipewire_after_desktop _offer_pipewire_after_desktop
} }
_install_kde_custom() {
# Fixed base (not selectable); extras chosen from the
# checklist. konsole is pinned because it is only a
# Recommends of kde-baseapps on trixie. All 17 extra
# names are identical on bookworm and trixie
# (packages.debian.org), so no per-release handling is
# needed beyond the shared Wayland gate. knotes is gone
# on trixie and konqueror/kwrite are legacy: excluded.
local cleaned
cleaned=$(_select_packages_checklist "KDE Custom" \
"Select the extra KDE packages to install:" \
"kate|advanced text editor" \
"ark|archive manager" \
"gwenview|image viewer" \
"okular|document viewer" \
"kcalc|calculator" \
"kde-spectacle|screenshot capture" \
"khelpcenter|documentation center" \
"sweeper|history cleaner" \
"print-manager|printer management" \
"kwalletmanager|password manager" \
"plasma-nm|network applet (needs NetworkManager)" \
"juk|music player" \
"dragonplayer|video player" \
"kmail|email client" \
"korganizer|calendar and tasks" \
"kaddressbook|contacts address book" \
"akregator|RSS feed reader")
[ -z "$cleaned" ] && return
# BH-004: reparse the space-separated selection into an array.
local -a kde_pkgs=()
local _pkg
while IFS= read -r _pkg; do
[ -n "$_pkg" ] && kde_pkgs+=("$_pkg")
done < <(echo "$cleaned" | tr ' ' '\n')
# Fixed base: kde-plasma-desktop + sddm + konsole, plus
# the Wayland session package on bookworm only.
local wayland_pkg
wayland_pkg=$(_kde_wayland_pkg)
local -a base_pkgs=(kde-plasma-desktop sddm konsole)
[ -n "$wayland_pkg" ] && base_pkgs+=("$wayland_pkg")
# Pre-apply summary: confirm base + selection before any
# debconf or apt transaction starts.
_confirm_install_list "KDE Custom" "${base_pkgs[@]}" "${kde_pkgs[@]}" || return
echo -e "${GREEN}Installing KDE Plasma (Custom)...${NC}"
# Keep an already-configured display manager intact.
local target_dm="sddm"
local keep_dm
keep_dm=$(_existing_display_manager)
if [ -n "$keep_dm" ] && [ "$keep_dm" != "sddm" ]; then
echo -e "${YELLOW}Display manager '${keep_dm}' is already configured — keeping it as default.${NC}"
target_dm="$keep_dm"
fi
echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections
_ensure_apt_updated
_run_cmd "KDE Custom" "sudo apt install -y ${base_pkgs[*]} ${kde_pkgs[*]}" \
"Installing KDE Plasma (Custom) + SDDM..."
if [ "$target_dm" = "sddm" ]; then
sudo systemctl enable sddm
fi
# Selection confirmed once above; release the
# per-package prompt suppression.
_SELECTION_CONFIRMED=0
echo -e "${GREEN}KDE Plasma installed. Default display manager: ${target_dm}.${NC}"
_offer_pipewire_after_desktop
}
modules/desktops/desktop_lxde.sh
+143 -23
View File
@@ -5,35 +5,155 @@
# License GPL v3 # License GPL v3
lxde_menu() { lxde_menu() {
local choice while true; do
choice=$(_radiolist "LXDE" \ local -a lx_items=()
"Select an option:" $TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA \ lx_items+=("1" "LXDE (Full Desktop)")
"1" "LXDE (Full Desktop)" OFF \ lx_items+=("2" "LXDE Core (Minimal Install)")
"2" "LXDE Core (Minimal Install)" OFF) lx_items+=("3" "LXDE Custom (Choose packages)")
[ -z "$choice" ] && return 0 lx_items+=("4" "Back")
clear local choice
case "$(echo "$choice" | tr -d '"')" in choice=$(_menu "LXDE" \
1) _install_lxde_full ;; "Select an option:" $TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA \
2) _install_lxde_core ;; "${lx_items[@]}")
esac [ -z "$choice" ] && break
clear
case "$choice" in
1) _install_lxde_full ;;
2) _install_lxde_core ;;
3) _install_lxde_custom ;;
4) break ;;
esac
done
} }
_install_lxde_full() { _install_lxde_full() {
echo -e "${GREEN}Installing LXDE (Full) + LightDM...${NC}" # Pre-apply summary: confirm the selection before any
echo "lightdm shared/default-x-display-manager select lightdm" | sudo debconf-set-selections # debconf or apt transaction starts.
_run_cmd "LXDE Full" "sudo apt install -y lxde lightdm" \ _confirm_install_list "LXDE Full Desktop" lxde lightdm || return
"Installing LXDE (Full Meta Package) + LightDM..."
sudo systemctl enable lightdm echo -e "${GREEN}Installing LXDE (Full Desktop)...${NC}"
echo -e "${GREEN}LXDE installed. LightDM enabled.${NC}"
# Keep an already-configured display manager intact.
local target_dm="lightdm"
local keep_dm
keep_dm=$(_existing_display_manager)
if [ -n "$keep_dm" ] && [ "$keep_dm" != "lightdm" ]; then
echo -e "${YELLOW}Display manager '${keep_dm}' is already configured — keeping it as default.${NC}"
target_dm="$keep_dm"
fi
echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections
_ensure_apt_updated
if [ "$target_dm" = "lightdm" ]; then
_run_cmd "LXDE Full" "sudo apt install -y lxde lightdm" \
"Installing LXDE (Full Meta Package) + LightDM..."
sudo systemctl enable lightdm
else
_run_cmd "LXDE Full" "sudo apt install -y lxde" \
"Installing LXDE (Full Meta Package)..."
fi
# Selection confirmed once above; release the
# per-package prompt suppression.
_SELECTION_CONFIRMED=0
echo -e "${GREEN}LXDE installed. Default display manager: ${target_dm}.${NC}"
_offer_pipewire_after_desktop _offer_pipewire_after_desktop
} }
_install_lxde_core() { _install_lxde_core() {
echo -e "${GREEN}Installing LXDE Core + LightDM...${NC}" # Pre-apply summary: confirm the selection before any
echo "lightdm shared/default-x-display-manager select lightdm" | sudo debconf-set-selections # debconf or apt transaction starts.
_run_cmd "LXDE Core" "sudo apt install -y lxde-core lightdm" \ _confirm_install_list "LXDE Core" lxde-core lightdm || return
"Installing LXDE Core (Minimal) + LightDM..."
sudo systemctl enable lightdm echo -e "${GREEN}Installing LXDE Core (Minimal)...${NC}"
echo -e "${GREEN}LXDE Core installed. LightDM enabled.${NC}"
# Keep an already-configured display manager intact.
local target_dm="lightdm"
local keep_dm
keep_dm=$(_existing_display_manager)
if [ -n "$keep_dm" ] && [ "$keep_dm" != "lightdm" ]; then
echo -e "${YELLOW}Display manager '${keep_dm}' is already configured — keeping it as default.${NC}"
target_dm="$keep_dm"
fi
echo "${target_dm} shared/default-x-display-manager select ${target_dm}" | sudo debconf-set-selections
_ensure_apt_updated
if [ "$target_dm" = "lightdm" ]; then
_run_cmd "LXDE Core" "sudo apt install -y lxde-core lightdm" \
"Installing LXDE Core (Minimal) + LightDM..."
sudo systemctl enable lightdm
else
_run_cmd "LXDE Core" "sudo apt install -y lxde-core" \
"Installing LXDE Core (Minimal)..."
fi
# Selection confirmed once above; release the
# per-package prompt suppression.
_SELECTION_CONFIRMED=0
echo -e "${GREEN}LXDE Core installed. Default display manager: ${target_dm}.${NC}"
_offer_pipewire_after_desktop
}
_install_lxde_custom() {
# Fixed base (not selectable); extras chosen from the checklist.
# lxterminal, polkitd, notification-daemon and light-locker are
# intentionally absent: they arrive via lxde-core's Recommends
# (verified on packages.debian.org/trixie, 2026-10-16).
local cleaned
cleaned=$(_select_packages_checklist "LXDE Custom" \
"Select the extra LXDE packages to install:" \
"lxappearance|Theme/appearance config" \
"lxappearance-obconf|Openbox theme settings" \
"lxrandr|Monitor configuration" \
"lxinput|Keyboard/mouse settings" \
"lxsession-edit|Session editor" \
"lxhotkey-gtk|Keyboard shortcuts config" \
"lxde-icon-theme|LXDE icon theme" \
"gpicview|Image viewer" \
"xarchiver|Archive manager" \
"galculator|Calculator" \
"mousepad|Text editor" \
"lxpolkit|PolicyKit authentication agent" \
"lxtask|Task manager" \
"numlockx|Enable NumLock on startup" \
"network-manager-applet|NetworkManager applet" \
"gnome-disk-utility|Disk utility")
[ -z "$cleaned" ] && return
# BH-004: reparse the space-separated selection into an array.
local -a lxde_pkgs=()
local _pkg
while IFS= read -r _pkg; do
[ -n "$_pkg" ] && lxde_pkgs+=("$_pkg")
done < <(echo "$cleaned" | tr ' ' '\n')
if [ ${#lxde_pkgs[@]} -eq 0 ]; then
_msg "LXDE Custom" "No extra packages selected — installing the\nfixed base only (equivalent to LXDE Core)." 10 60
fi
# Fixed base: lxde-core + xserver-xorg always; lightdm only
# when no display manager is configured yet — never force it
# over an existing one.
local -a base_pkgs=(lxde-core xserver-xorg)
local install_dm=0 keep_dm
keep_dm=$(_existing_display_manager)
if [ -z "$keep_dm" ]; then
base_pkgs+=(lightdm)
install_dm=1
else
echo -e "${YELLOW}Display manager '${keep_dm}' is already configured — keeping it as default.${NC}"
fi
# Pre-apply summary: confirm base + selection before any
# debconf or apt transaction starts.
_confirm_install_list "LXDE Custom" "${base_pkgs[@]}" "${lxde_pkgs[@]}" || return
if [ "$install_dm" -eq 1 ]; then
echo "lightdm shared/default-x-display-manager select lightdm" | sudo debconf-set-selections
fi
_ensure_apt_updated
_run_cmd "LXDE Custom" "sudo apt install -y ${base_pkgs[*]} ${lxde_pkgs[*]}" \
"Installing LXDE base + selected packages..."
if [ "$install_dm" -eq 1 ]; then
sudo systemctl enable lightdm
fi
# Selection confirmed once above; release the
# per-package prompt suppression.
_SELECTION_CONFIRMED=0
echo -e "${GREEN}LXDE installed (base: ${base_pkgs[*]}).${NC}"
_offer_pipewire_after_desktop _offer_pipewire_after_desktop
} }
modules/desktops/desktop_xfce.sh
+16 -15
View File
@@ -51,27 +51,28 @@ _install_xfce_wayland() {
} }
_install_xfce_custom() { _install_xfce_custom() {
local -a items=() # BH-004: helper returns a space-separated selection;
for pkg in thunar xfdesktop4 xfwm4 xfce4-panel xfce4-terminal \ # reparsed into an array to avoid word splitting and injection.
xfce4-screenshooter ristretto mousepad xfce4-session \
xfce4-settings xfce4-power-manager; do
items+=("$pkg" "$pkg" "$(_state "$pkg")")
done
local choices
choices=$(_checklist "XFCE Custom" \
"Select the XFCE packages to install:" $TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA \
"${items[@]}")
[ -z "$choices" ] && return
local cleaned local cleaned
cleaned=$(echo "$choices" | tr -d '"') cleaned=$(_select_packages_checklist "XFCE Custom" \
"Select the XFCE packages to install:" \
"thunar|File manager" \
"xfdesktop4|Desktop manager" \
"xfwm4|Window manager" \
"xfce4-panel|Panel" \
"xfce4-terminal|Terminal emulator" \
"xfce4-screenshooter|Screenshot tool" \
"ristretto|Image viewer" \
"mousepad|Text editor" \
"xfce4-session|Session manager" \
"xfce4-settings|Settings manager" \
"xfce4-power-manager|Power manager")
[ -z "$cleaned" ] && return [ -z "$cleaned" ] && return
# BH-004: Convert to array to avoid word splitting and injection.
local -a xfce_pkgs=() local -a xfce_pkgs=()
local _pkg
while IFS= read -r _pkg; do while IFS= read -r _pkg; do
[ -n "$_pkg" ] && xfce_pkgs+=("$_pkg") [ -n "$_pkg" ] && xfce_pkgs+=("$_pkg")
done < <(echo "$cleaned" | tr ' ' '\n') done < <(echo "$cleaned" | tr ' ' '\n')
# Pre-apply summary: confirm the selection before # Pre-apply summary: confirm the selection before
# the batch apt transaction starts. # the batch apt transaction starts.
_confirm_install_list "XFCE Custom" "${xfce_pkgs[@]}" || return _confirm_install_list "XFCE Custom" "${xfce_pkgs[@]}" || return
modules/extras/audio/audio.sh
-185
View File
@@ -1,185 +0,0 @@
#!/usr/bin/env bash
# audio.sh — Audio & Sound (PipeWire, ALSA, PulseAudio tools)
_cat_audio() {
local headless=false
_is_headless && headless=true
local -a items=()
local pw_label="PipeWire Audio Stack (Bluetooth Hi-Res)"
local pw_state; pw_state=$(_state "pipewire-audio")
items+=(
"pipewire-audio" "$pw_label" "$pw_state"
)
local alsa_state; alsa_state=$(_state "alsa-utils")
items+=(
"alsa-utils" "ALSA Utilities (alsa-utils, alsa-ucm-conf)" "$alsa_state"
)
if ! $headless; then
local pavu_state; pavu_state=$(_state "pavucontrol")
items+=(
"pavucontrol" "Volume Control GUI (pavucontrol)" "$pavu_state"
)
fi
local pulsemixer_state; pulsemixer_state=$(_state "pulsemixer")
local playerctl_state; playerctl_state=$(_state "playerctl")
items+=(
"pulsemixer" "Terminal audio mixer (pulsemixer)" "$pulsemixer_state"
"playerctl" "Multimedia key controller (playerctl)" "$playerctl_state"
)
local item_count=${#items[@]}
local lista_alto=$((item_count > TUI_ALTO_LISTA ? TUI_ALTO_LISTA : item_count))
local choices
choices=$(_checklist "Audio & Sound" "Check [*] the packages you want installed.\n" \
$TUI_ALTO $TUI_ANCHO $lista_alto "${items[@]}")
clear
[ -z "$choices" ] && return
local cleaned; cleaned=$(echo "$choices" | tr -d '"')
for pkg in $cleaned; do
case $pkg in
pipewire-audio) _install_pipewire_standard ;;
alsa-utils)
if ! is_installed "alsa-utils"; then
_run_install "alsa-utils alsa-ucm-conf"
else
echo "alsa-utils already installed."
fi
;;
pavucontrol)
if ! is_installed "pavucontrol"; then
_run_install "pavucontrol"
else
echo "pavucontrol already installed."
fi
;;
pulsemixer)
if ! is_installed "pulsemixer"; then
_run_install "pulsemixer"
else
echo "pulsemixer already installed."
fi
;;
playerctl)
if ! is_installed "playerctl"; then
_run_install "playerctl"
else
echo "playerctl already installed."
fi
;;
esac
done
echo -e "${GREEN}Audio & Sound setup complete.${NC}"
}
_install_pipewire_standard() {
local bt_pkgs="libldacbt-abr2 libldacbt-enc2 libopenaptx0 libspa-0.2-bluetooth"
if apt-cache show libfdk-aac2t64 &>/dev/null; then
bt_pkgs+=" libfdk-aac2t64"
elif apt-cache show libfdk-aac2 &>/dev/null; then
bt_pkgs+=" libfdk-aac2"
fi
# ── Resolve versions (needed for both installed and not-installed branches) ──
local stable_ver=""
stable_ver=$(apt-cache policy pipewire-audio 2>/dev/null | awk 'NR==3 {print $2; exit}') || true
local bpo_ver=""
if [ "$DEBIAN_VERSION" = "13" ] && [ "$(is_backports_enabled)" = "true" ]; then
bpo_ver=$(apt-cache madison pipewire-audio 2>/dev/null | \
grep "${DEBIAN_CODENAME}-backports" | awk '{print $3}' | head -1) || true
fi
local pkg_check="pipewire-audio"
[ "$DEBIAN_VERSION" = "11" ] && pkg_check="pipewire"
# ── Already installed branch ──
if is_installed "$pkg_check"; then
if [ -n "$bpo_ver" ]; then
local current_ver
current_ver=$(dpkg -l "$pkg_check" 2>/dev/null | awk '/^ii/{print $3}') || true
if _confirm "PipeWire" \
"PipeWire ${current_ver:+v${current_ver} }already installed.\n\nUpgrade to backports version v${bpo_ver}?"; then
echo "Upgrading PipeWire Audio Stack..."
echo "-> Target version: v${bpo_ver} (from ${DEBIAN_CODENAME}-backports)"
echo "-> Including Bluetooth Hi-Res codecs (LDAC, aptX, AAC)"
_run_cmd "PipeWire" \
"sudo apt install -y --reinstall -t ${DEBIAN_CODENAME}-backports pipewire-audio $bt_pkgs" \
"Upgrading PipeWire from backports..."
if [ "$DEBIAN_VERSION" != "11" ]; then
echo "Restarting PipeWire services..."
systemctl --user restart wireplumber pipewire pipewire-pulse 2>/dev/null || true
echo -e "${GREEN}PipeWire services restarted.${NC}"
fi
return
fi
fi
echo "$pkg_check already installed."
return
fi
# ── Confirm dialog ──
local apt_target="" pw_ver="" pw_src=""
if [ -n "$bpo_ver" ]; then
local msg="Backports repository is enabled.\n\n"
msg+="Available versions:\n"
msg+=" - Stable: v${stable_ver:-unknown}\n"
msg+=" - Backports: v${bpo_ver}\n\n"
msg+="Install from Backports (Recommended for newer hardware)\nor from Stable (more conservative)?"
if _confirm_custom "PipeWire Install" "$msg" "Backports" "Stable" 14 70; then
apt_target="-t ${DEBIAN_CODENAME}-backports"
pw_ver="$bpo_ver"
pw_src="from ${DEBIAN_CODENAME}-backports"
else
pw_ver="$stable_ver"
fi
else
local msg="PipeWire Audio Stack (v${stable_ver:-unknown})\n"
msg+="will be installed along with Bluetooth Hi-Res\n"
msg+="codecs (LDAC, aptX, AAC).\n\n"
msg+="Continue with installation?"
if ! _confirm "PipeWire Install" "$msg" 12 65; then
echo "PipeWire installation cancelled."
return
fi
pw_ver="$stable_ver"
fi
echo "Installing PipeWire Audio Stack..."
echo "-> Detected version: ${pw_ver:-unknown} ${pw_src:+($pw_src)}"
echo "-> Including Bluetooth Hi-Res codecs (LDAC, aptX, AAC)"
case "$DEBIAN_VERSION" in
11)
_run_cmd "PipeWire" \
"sudo apt install -y pipewire libspa-0.2-bluetooth pipewire-alsa libspa-0.2-jack $bt_pkgs" \
"Installing PipeWire (Bullseye basic mode)..."
echo -e "${GREEN}PipeWire installed (Bullseye basic mode).${NC}"
;;
12)
_run_cmd "PipeWire" \
"sudo apt install -y pipewire-audio $bt_pkgs" \
"Installing pipewire-audio meta-package (Bookworm)..."
echo -e "${GREEN}PipeWire audio stack installed.${NC}"
;;
13)
_run_cmd "PipeWire" \
"sudo apt install -y $apt_target pipewire-audio $bt_pkgs" \
"Installing pipewire-audio meta-package (Trixie)..."
echo -e "${GREEN}PipeWire audio stack installed.${NC}"
;;
esac
if [ "$DEBIAN_VERSION" != "11" ]; then
echo "Restarting PipeWire services..."
systemctl --user restart wireplumber pipewire pipewire-pulse 2>/dev/null || true
echo -e "${GREEN}PipeWire services restarted.${NC}"
fi
}
modules/repos/migrate.sh
+9
View File
@@ -111,6 +111,15 @@ _write_classic_branch() {
} }
_branch_migration() { _branch_migration() {
# Unattended guard: branch migration is the one operation
# that can leave the system unbootable, so --yes alone is
# not enough — it also requires --allow-destructive even
# when every other prompt auto-accepts.
if [ "${AUTO_YES:-0}" = "1" ] && [ "${ALLOW_DESTRUCTIVE:-0}" != "1" ]; then
echo "Branch migration is destructive. Re-run with --allow-destructive, or drop --yes to confirm interactively." >&2
return 1
fi
# ── Screen 1: Risk warning ── # ── Screen 1: Risk warning ──
_msg_red "WARNING: Branch Migration" \ _msg_red "WARNING: Branch Migration" \
"Migrating from Debian Stable to Testing or SID is a\n\ "Migrating from Debian Stable to Testing or SID is a\n\
modules/sysinfo.sh
+42 -169
View File
@@ -19,194 +19,67 @@ _show_sysinfo() {
msg+="Storage: ${STORAGE_SUMMARY}\n" msg+="Storage: ${STORAGE_SUMMARY}\n"
msg+="\n" msg+="\n"
# ── GPU Block ── # ── GPU Block (cached by detect_gpu) ──
local found_gpu=false if [ -n "${GPU_DESC:-}" ] && [ "$GPU_DESC" != "No GPU detected" ]; then
if command -v lspci &>/dev/null; then msg+="GPU: ${GPU_DESC}\n"
local gpu_count=0 msg+=" Driver: ${GPU_VERSION:-unknown}\n"
while IFS= read -r gpu_line; do else
found_gpu=true
gpu_count=$((gpu_count + 1))
local desc
desc=$(echo "$gpu_line" | sed -E 's/.*: //; s/ *\(rev.*//')
if echo "$gpu_line" | grep -qi "nvidia"; then
local nv_ver=""
nv_ver=$(timeout 3 nvidia-smi --query-gpu=driver_version --format=csv,noheader 2>/dev/null | head -1) || true
[ -z "$nv_ver" ] && nv_ver=$(dpkg -l nvidia-driver 2>/dev/null | awk '/^ii/ {print $3}' | sed 's/-.*//') || true
msg+="GPU ${gpu_count}: ${desc}\n"
msg+=" Driver: ${nv_ver:+NVIDIA }${nv_ver:-not installed}\n"
else
local mesa_ver=""
mesa_ver=$(dpkg -l libgl1-mesa-dri 2>/dev/null | awk '/^ii/ {print $3; exit}' | sed 's/-.*//') || true
msg+="GPU ${gpu_count}: ${desc}\n"
msg+=" Driver: ${mesa_ver:+Mesa }${mesa_ver:-unknown}\n"
fi
done < <(echo "$LSPCI_OUTPUT" | grep -E "VGA|3D" || true)
fi
if ! $found_gpu; then
msg+="GPU: No GPU detected\n" msg+="GPU: No GPU detected\n"
fi fi
msg+="\n" msg+="\n"
# ── Network Block (PCI class + live interfaces) ── # ── Network Block (cached by detect_network) ──
msg+="─── Network ───\n" msg+="─── Network ───\n"
# ── 1. Detect ALL Ethernet chipsets (class 0x0200) ──
declare -a pci_eth_lines=()
while IFS= read -r line; do
pci_eth_lines+=("$line")
done < <(echo "$LSPCI_OUTPUT" | grep -i 'ethernet controller' || true)
# ── 2. Detect ALL WiFi chipsets (class 0x0280 + vendor fallbacks) ──
declare -a pci_wifi_lines=()
while IFS= read -r line; do
pci_wifi_lines+=("$line")
done < <(echo "$LSPCI_OUTPUT" | grep -i 'network controller' || true)
# Broadcom vendor-ID fallback (14e4) — include only if not already captured
while IFS= read -r line; do
if echo "$line" | grep -qi '14e4:'; then
local already=false
for existing in "${pci_wifi_lines[@]}"; do
[ "$existing" = "$line" ] && already=true && break
done
! $already && pci_wifi_lines+=("$line")
fi
done < <(echo "$LSPCI_OUTPUT" || true)
# USB WiFi fallback
local usb_wifi_lines=()
while IFS= read -r line; do
usb_wifi_lines+=("$line")
done < <(lsusb 2>/dev/null | grep -iE 'wireless|wifi|wlan|802\.11' || true)
# ── 3. Build chipset description arrays ──
local -a eth_descs=()
local -a wifi_descs=()
local line desc
for line in "${pci_eth_lines[@]}"; do
desc=$(echo "$line" | sed -E 's/^.*\]: //; s/ \[[0-9a-fA-F]{4}:[0-9a-fA-F]{4}\]//; s/ \(rev [0-9a-fA-F]+\)//')
eth_descs+=("$desc")
done
for line in "${pci_wifi_lines[@]}"; do
desc=$(echo "$line" | sed -E 's/^.*\]: //; s/ \[[0-9a-fA-F]{4}:[0-9a-fA-F]{4}\]//; s/ \(rev [0-9a-fA-F]+\)//')
wifi_descs+=("$desc")
done
for line in "${usb_wifi_lines[@]}"; do
desc=$(echo "$line" | sed 's/^.*ID //')
wifi_descs+=("$desc")
done
# ── 4. Enumerate live interfaces ──
local -a shown_eth_descs=()
local -a shown_wifi_descs=()
local has_eth=false has_wifi=false has_other=false
local eth_idx=0
local wifi_idx=0
if ! command -v ip &>/dev/null; then if ! command -v ip &>/dev/null; then
msg+="(install iproute2 for interface details)\n" msg+="(install iproute2 for interface details)\n"
else else
while IFS= read -r line; do local i desc
local iface state ip4 ssid local has_net=false
iface=$(echo "$line" | awk -F': ' '{print $2}' | sed 's/@.*//')
state=$(echo "$line" | awk '{print $9}')
case "$iface" in # Ethernet interfaces (chipset from ETH_DESCS, parallel arrays)
lo | docker* | veth* | br-* | virbr* | tun* | tap* | bond*) continue ;; for i in "${!ETH_NAMES[@]}"; do
esac has_net=true
desc="${ETH_DESCS[$i]:-Unknown Ethernet chipset}"
if [ "${ETH_STATES[$i]}" = "UP" ]; then
msg+="${ETH_NAMES[$i]}: ${desc}\n ↑ ${ETH_IPS[$i]:-no IP}\n"
else
msg+="${ETH_NAMES[$i]}: ${desc}\n ↓\n"
fi
done
ip4=$(timeout 2 ip -4 -o addr show "$iface" 2>/dev/null | awk '{print $4}') # WiFi interfaces (chipset from WIFI_DESCS, parallel arrays)
for i in "${!WIFI_NAMES[@]}"; do
# Determine type by PCI class (most reliable) has_net=true
local pci_class="" desc="${WIFI_DESCS[$i]:-Unknown WiFi chipset}"
pci_class=$(cat "/sys/class/net/${iface}/device/class" 2>/dev/null || true) if [ "${WIFI_STATES[$i]}" = "UP" ]; then
msg+="${WIFI_NAMES[$i]}: ${desc}\n ↑ ${WIFI_IPS[$i]:-no IP}"
case "$pci_class" in [ -n "${WIFI_SSIDS[$i]:-}" ] && msg+=" \"${WIFI_SSIDS[$i]}\""
0x0200*)
has_eth=true
desc="${eth_descs[$eth_idx]:-Unknown Ethernet chipset}"
shown_eth_descs+=("${eth_descs[$eth_idx]:-$desc}")
eth_idx=$((eth_idx + 1))
;;
0x0280*)
has_wifi=true
desc="${wifi_descs[$wifi_idx]:-Unknown WiFi chipset}"
shown_wifi_descs+=("${wifi_descs[$wifi_idx]:-$desc}")
wifi_idx=$((wifi_idx + 1))
ssid=""
[ "$state" = "UP" ] && ssid=$(timeout 2 iwgetid -r "$iface" 2>/dev/null || true)
;;
*)
# Fallback: classify by interface name pattern
case "$iface" in
wl*)
has_wifi=true
desc="${wifi_descs[$wifi_idx]:-Unknown WiFi chipset}"
shown_wifi_descs+=("${wifi_descs[$wifi_idx]:-$desc}")
wifi_idx=$((wifi_idx + 1))
ssid=""
[ "$state" = "UP" ] && ssid=$(timeout 2 iwgetid -r "$iface" 2>/dev/null || true)
;;
eth* | enp* | ens* | enx* | eno*)
has_eth=true
desc="${eth_descs[$eth_idx]:-Unknown Ethernet chipset}"
shown_eth_descs+=("${eth_descs[$eth_idx]:-$desc}")
eth_idx=$((eth_idx + 1))
;;
*)
has_other=true
desc="(network interface)"
;;
esac
;;
esac
if [ "$state" = "UP" ]; then
msg+="${iface}: ${desc}\n ↑ ${ip4:-no IP}"
if [ "$pci_class" = "0x0280" ] || [[ "$iface" == wl* ]]; then
[ -n "${ssid:-}" ] && msg+=" \"${ssid}\""
fi
msg+="\n" msg+="\n"
else else
msg+="${iface}: ${desc}\n ↓\n" msg+="${WIFI_NAMES[$i]}: ${desc}\n ↓\n"
fi fi
done < <(timeout 2 ip -o link show 2>/dev/null)
fi
# ── 5. Show chipsets without an active interface ──
local chip
for chip in "${eth_descs[@]}"; do
local found=false
for shown in "${shown_eth_descs[@]}"; do
[ "$chip" = "$shown" ] && found=true && break
done done
if ! $found; then
msg+="Ethernet: ${chip}\n (no active interface)\n"
shown_eth_descs+=("$chip")
fi
done
for chip in "${wifi_descs[@]}"; do # Chipsets with no live interface
local found=false local chip shown
for shown in "${shown_wifi_descs[@]}"; do for chip in "${ETH_DESCS[@]}"; do
[ "$chip" = "$shown" ] && found=true && break shown=false
for i in "${!ETH_NAMES[@]}"; do
[ "${ETH_DESCS[$i]}" = "$chip" ] && shown=true && break
done
$shown || msg+="Ethernet: ${chip}\n (no active interface)\n"
done
for chip in "${WIFI_DESCS[@]}"; do
shown=false
for i in "${!WIFI_NAMES[@]}"; do
[ "${WIFI_DESCS[$i]}" = "$chip" ] && shown=true && break
done
$shown || msg+="WiFi: ${chip}\n (no active interface)\n"
done done
if ! $found; then
msg+="WiFi: ${chip}\n (no active interface)\n"
shown_wifi_descs+=("$chip")
fi
done
# ── 6. Nothing at all ── if ! $has_net && [ ${#ETH_DESCS[@]} -eq 0 ] && [ ${#WIFI_DESCS[@]} -eq 0 ]; then
if ! $has_eth && ! $has_wifi && ! $has_other && [ ${#eth_descs[@]} -eq 0 ] && [ ${#wifi_descs[@]} -eq 0 ]; then
if command -v ip &>/dev/null; then
msg+="No network interfaces detected\n" msg+="No network interfaces detected\n"
else
msg+="(install iproute2 for interface details)\n"
fi fi
fi fi
modules/utils.sh
+37 -6
View File
@@ -280,8 +280,12 @@ _init_lspci_cache() {
[ -n "${LSPCI_OUTPUT:-}" ] && return [ -n "${LSPCI_OUTPUT:-}" ] && return
LSPCI_OUTPUT=$(timeout 2 lspci -nn 2>/dev/null || true) LSPCI_OUTPUT=$(timeout 2 lspci -nn 2>/dev/null || true)
} }
_lspci_desc() {
# Strip the "bus domain] device ID" and "(rev XX)" fields,
# keeping the human-readable device name.
echo "$1" | sed -E 's/^.*\]: //; s/ \[[0-9a-fA-F]{4}:[0-9a-fA-F]{4}\]//; s/ \(rev [0-9a-fA-F]+\)//'
}
# ----------------------------------
# GPU detection # GPU detection
# ---------------------------------- # ----------------------------------
detect_gpu() { detect_gpu() {
@@ -394,7 +398,7 @@ detect_network() {
local eth_line local eth_line
eth_line=$(echo "$LSPCI_OUTPUT" | grep -i 'Ethernet controller' | head -n1) || true eth_line=$(echo "$LSPCI_OUTPUT" | grep -i 'Ethernet controller' | head -n1) || true
if [ -n "$eth_line" ]; then if [ -n "$eth_line" ]; then
ETH_DESC=$(echo "$eth_line" | sed -E 's/^.*\]: //; s/ \[[0-9a-fA-F]{4}:[0-9a-fA-F]{4}\]//; s/ \(rev [0-9a-fA-F]+\)//') ETH_DESC=$(_lspci_desc "$eth_line")
fi fi
local wifi_line local wifi_line
@@ -410,7 +414,7 @@ detect_network() {
fi fi
if [ -n "$wifi_line" ]; then if [ -n "$wifi_line" ]; then
WIFI_CHIPSET="$wifi_line" WIFI_CHIPSET="$wifi_line"
WIFI_DESC=$(echo "$wifi_line" | sed -E 's/^.*\]: //; s/ \[[0-9a-fA-F]{4}:[0-9a-fA-F]{4}\]//; s/ \(rev [0-9a-fA-F]+\)//') WIFI_DESC=$(_lspci_desc "$wifi_line")
fi fi
# Layer 4: USB WiFi adapter (no PCI device) # Layer 4: USB WiFi adapter (no PCI device)
if [ -z "$wifi_line" ] && command -v lsusb &>/dev/null; then if [ -z "$wifi_line" ] && command -v lsusb &>/dev/null; then
@@ -434,16 +438,16 @@ detect_network() {
state=$(echo "$line" | awk '{print $9}') state=$(echo "$line" | awk '{print $9}')
case "$iface" in case "$iface" in
eth* | enp* | ens* | enx* | eno*) eth* | enp* | ens* | enx* | eno*)
ip4=$(timeout 2 ip -4 -o addr show "$iface" 2>/dev/null | awk '{print $4}') ip4=$(timeout 1 ip -4 -o addr show "$iface" 2>/dev/null | awk '{print $4}')
ETH_NAMES+=("$iface") ETH_NAMES+=("$iface")
ETH_STATES+=("$state") ETH_STATES+=("$state")
ETH_IPS+=("${ip4:-}") ETH_IPS+=("${ip4:-}")
ETH_DESCS+=("${ETH_DESC:-}") ETH_DESCS+=("${ETH_DESC:-}")
;; ;;
wl*) wl*)
ip4=$(timeout 2 ip -4 -o addr show "$iface" 2>/dev/null | awk '{print $4}') ip4=$(timeout 1 ip -4 -o addr show "$iface" 2>/dev/null | awk '{print $4}')
ssid="" ssid=""
[ "$state" = "UP" ] && ssid=$(timeout 2 iwgetid -r "$iface" 2>/dev/null || true) [ "$state" = "UP" ] && ssid=$(timeout 1 iwgetid -r "$iface" 2>/dev/null || true)
WIFI_NAMES+=("$iface") WIFI_NAMES+=("$iface")
WIFI_STATES+=("$state") WIFI_STATES+=("$state")
WIFI_IPS+=("${ip4:-}") WIFI_IPS+=("${ip4:-}")
@@ -647,6 +651,9 @@ install_backports_or_stable() {
# ---------------------------------------------------------------------- # ----------------------------------------------------------------------
_confirm() { _confirm() {
# --yes (unattended mode): auto-accept without
# invoking whiptail; the prompt gate is the flag itself.
[ "${AUTO_YES:-0}" = "1" ] && return 0
whiptail --title "$1" --yes-button "Yes" --no-button "No" \ whiptail --title "$1" --yes-button "Yes" --no-button "No" \
--yesno "$2" "${3:-10}" "${4:-65}" --yesno "$2" "${3:-10}" "${4:-65}"
} }
@@ -711,6 +718,7 @@ _validate_sudoers() {
rm -f "$tmpfile" rm -f "$tmpfile"
} }
# shellcheck disable=SC2120 # Optional prompt arg used by GPU modules.
_pause() { _pause() {
local msg="${1:-Press Enter to continue...}" local msg="${1:-Press Enter to continue...}"
echo -e "$msg" echo -e "$msg"
@@ -797,6 +805,28 @@ _confirm_install_list() {
return 1 return 1
} }
# Show a multi-select checklist of packages and return the
# selection as a space-separated string ("" on cancel/Esc).
# Args: title prompt "pkg|description" [pkg|description ...]
# Already-installed packages are pre-checked via _state.
_select_packages_checklist() {
local title="$1" prompt="$2"
shift 2
local -a items=() entry
for entry in "$@"; do
local pkg="${entry%%|*}"
items+=("$pkg" "${entry#*|}" "$(_state "$pkg")")
done
local choices
# _checklist swallows whiptail's cancel (Esc) exit code
# via `|| true`, so a cancelled dialog looks like an empty
# selection here; an empty result means "nothing to install".
choices=$(_checklist "$title" "$prompt" \
$TUI_ALTO $TUI_ANCHO $TUI_ALTO_LISTA "${items[@]}")
choices=$(echo "$choices" | tr -d '"')
echo "$choices"
}
# Install a package with confirmation prompt. # Install a package with confirmation prompt.
# Handles set -e: failures are caught and reported, not fatal. # Handles set -e: failures are caught and reported, not fatal.
_install_pkg() { _install_pkg() {
@@ -867,6 +897,7 @@ _detect_lang_pkg() {
# ---------------------------------- # ----------------------------------
# Network connectivity check # Network connectivity check
# ---------------------------------- # ----------------------------------
# shellcheck disable=SC2120 # Optional probe target (default: deb.debian.org).
_check_network() { _check_network() {
local target="${1:-deb.debian.org}" local target="${1:-deb.debian.org}"
tests/desktops.bats
+240 -1
View File
@@ -34,9 +34,13 @@ setup() {
# Re-declare it globally for the _load_module tests. # Re-declare it globally for the _load_module tests.
declare -gA _LOADED_MODULES=() declare -gA _LOADED_MODULES=()
# Only function definitions at the top level: safe to source.
# Only function definitions at the top level: safe to source. # Only function definitions at the top level: safe to source.
source "${TEST_PROJECT_ROOT}/modules/desktop_display.sh" source "${TEST_PROJECT_ROOT}/modules/desktop_display.sh"
# The GNOME installers are pure function definitions too;
# desktop_display.sh (their DM/pipewire collaborators) is
# already sourced above.
source "${TEST_PROJECT_ROOT}/modules/desktops/desktop_gnome.sh"
# Fixture redirect for /etc/X11/default-display-manager: # Fixture redirect for /etc/X11/default-display-manager:
# the file exists but is empty, so `-s` fails and the # the file exists but is empty, so `-s` fails and the
# systemctl fallback is exercised deterministically. # systemctl fallback is exercised deterministically.
@@ -56,6 +60,10 @@ teardown() {
if [ -n "${MOCK_APT_ROOT:-}" ]; then if [ -n "${MOCK_APT_ROOT:-}" ]; then
rm -rf "$MOCK_APT_ROOT" rm -rf "$MOCK_APT_ROOT"
fi fi
if [ -n "${SESSION_FIXTURE:-}" ]; then
rm -rf "$SESSION_FIXTURE"
fi
unset SESSION_DIR_WAYLAND SESSION_DIR_X11
} }
# ── _existing_display_manager ──────────────────────── # ── _existing_display_manager ────────────────────────
@@ -188,3 +196,234 @@ _load_module_with_deps_marked() {
run _load_module no_such_module run _load_module no_such_module
[ "$status" -eq 1 ] [ "$status" -eq 1 ]
} }
# ── terminal selection: ptyxis on trixie ──────────────
# gnome-core declares the OR-dep "gnome-terminal or
# gnome-console or ptyxis"; apt resolves an unset OR-dep
# with the first alternative, so listing the terminal
# explicitly in the same apt transaction is what steers
# the resolver. These tests assert the exact package
# that lands in the apt command.
#
# _gnome_capture_apt_cmd runs one installer with every
# external effect stubbed: _run_cmd is replaced so the
# apt command is captured instead of executed, and the
# PATH sudo mock stays in dry-run mode so debconf and
# systemctl invocations are logged, not executed.
_gnome_capture_apt_cmd() {
local installer="$1"
GNOME_APT_CMD=""
_confirm_install_list() { return 0; }
_ensure_apt_updated() { :; }
_run_cmd() { GNOME_APT_CMD="$2"; }
"$installer"
printf '%s\n' "$GNOME_APT_CMD"
}
@test "GNOME Full installs ptyxis on trixie" {
export DEBIAN_CODENAME="trixie"
export MOCK_SUDO_DRY_RUN=1
run _gnome_capture_apt_cmd _install_gnome_full
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y gnome gdm3 ptyxis"* ]]
[[ "$output" != *gnome-terminal* ]]
}
@test "GNOME Core installs ptyxis on trixie" {
export DEBIAN_CODENAME="trixie"
export MOCK_SUDO_DRY_RUN=1
run _gnome_capture_apt_cmd _install_gnome_core
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y gnome-core gdm3 ptyxis"* ]]
[[ "$output" != *gnome-terminal* ]]
}
@test "GNOME Full falls back to gnome-terminal off trixie" {
export DEBIAN_CODENAME="bookworm"
export MOCK_SUDO_DRY_RUN=1
run _gnome_capture_apt_cmd _install_gnome_full
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y gnome gdm3 gnome-terminal"* ]]
[[ "$output" != *ptyxis* ]]
}
@test "GNOME falls back to gnome-terminal when the codename is empty" {
# /etc/os-release missing or without VERSION_CODENAME
# leaves DEBIAN_CODENAME unset: the safe default is the
# historical behaviour.
export DEBIAN_CODENAME=""
export MOCK_SUDO_DRY_RUN=1
run _gnome_capture_apt_cmd _install_gnome_full
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y gnome gdm3 gnome-terminal"* ]]
[[ "$output" != *ptyxis* ]]
}
# ── KDE Plasma: bookworm Wayland gate ─────────────
# plasma-workspace-wayland exists only on bookworm:
# bookworm's plasma-workspace ships the X11 session
# only, so the explicit listing keeps the Wayland
# session in the transaction deterministically; off
# bookworm the package does not exist and nothing is
# named in the apt command.
# _kde_capture_apt_cmd runs one KDE installer with
# every external effect stubbed (same shape as the
# GNOME capture helper): the apt command is captured
# instead of executed, and the PATH sudo mock stays
# in dry-run mode so debconf and systemctl invocations
# are logged, not executed.
_kde_capture_apt_cmd() {
local installer="$1"
_load_module_with_deps_marked kde
KDE_APT_CMD=""
_confirm_install_list() { return 0; }
_ensure_apt_updated() { :; }
_run_cmd() { KDE_APT_CMD="$2"; }
"$installer"
printf '%s\n' "$KDE_APT_CMD"
}
# _kde_capture_confirm runs one KDE installer with the
# pre-apply summary captured instead of shown: _confirm
# records the list _confirm_install_list builds, so the
# summary content (never an empty package line) can be
# asserted directly. The pipewire follow-up offer is
# stubbed so the recorded list is the package summary.
_kde_capture_confirm() {
local installer="$1"
_load_module_with_deps_marked kde
KDE_CONFIRM_LIST=""
_confirm() { KDE_CONFIRM_LIST="$2"; return 0; }
_ensure_apt_updated() { :; }
_run_cmd() { :; }
_offer_pipewire_after_desktop() { :; }
"$installer"
printf '%s\n' "$KDE_CONFIRM_LIST"
}
@test "_kde_wayland_pkg prints plasma-workspace-wayland on bookworm" {
export DEBIAN_CODENAME="bookworm"
_load_module_with_deps_marked kde
run _kde_wayland_pkg
[ "$status" -eq 0 ]
[ "$output" = "plasma-workspace-wayland" ]
}
@test "_kde_wayland_pkg prints nothing off bookworm" {
export DEBIAN_CODENAME="trixie"
_load_module_with_deps_marked kde
run _kde_wayland_pkg
[ "$status" -eq 0 ]
[ -z "$output" ]
}
@test "KDE Full installs the Wayland session package on bookworm" {
export DEBIAN_CODENAME="bookworm"
export MOCK_SUDO_DRY_RUN=1
run _kde_capture_apt_cmd _install_kde_full
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y kde-standard sddm plasma-workspace-wayland"* ]]
}
@test "KDE Full omits the Wayland session package off bookworm" {
export DEBIAN_CODENAME="trixie"
export MOCK_SUDO_DRY_RUN=1
run _kde_capture_apt_cmd _install_kde_full
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y kde-standard sddm"* ]]
[[ "$output" != *"plasma-workspace-wayland"* ]]
}
@test "KDE Minimal installs the Wayland session package on bookworm" {
export DEBIAN_CODENAME="bookworm"
export MOCK_SUDO_DRY_RUN=1
run _kde_capture_apt_cmd _install_kde_minimal
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y kde-plasma-desktop sddm plasma-workspace-wayland"* ]]
}
@test "KDE Minimal omits the Wayland session package off bookworm" {
export DEBIAN_CODENAME="trixie"
export MOCK_SUDO_DRY_RUN=1
run _kde_capture_apt_cmd _install_kde_minimal
[ "$status" -eq 0 ]
[[ "$output" == *"apt install -y kde-plasma-desktop sddm"* ]]
[[ "$output" != *"plasma-workspace-wayland"* ]]
}
@test "KDE Minimal summary lists the Wayland session package on bookworm" {
export DEBIAN_CODENAME="bookworm"
export MOCK_SUDO_DRY_RUN=1
run _kde_capture_confirm _install_kde_minimal
[ "$status" -eq 0 ]
[[ "$output" == *"plasma-workspace-wayland"* ]]
}
@test "KDE Minimal summary shows no empty package line off bookworm" {
export DEBIAN_CODENAME="trixie"
export MOCK_SUDO_DRY_RUN=1
run _kde_capture_confirm _install_kde_minimal
[ "$status" -eq 0 ]
[[ "$output" == *"kde-plasma-desktop"* ]]
[[ "$output" == *"sddm"* ]]
[[ "$output" != *"plasma-workspace-wayland"* ]]
[[ "$output" != *"- "$'\n'* ]]
}
# ── _sddm_session_candidates: ordered session probe ──
# Existence decides (no codename gates) and Wayland is
# preferred. The roots are redirected to a per-test
# fixture tree through SESSION_DIR_WAYLAND /
# SESSION_DIR_X11 (same spirit as the DM_FILE fixture),
# so the probe never touches the real /usr/share tree.
_sddm_session_fixture() {
SESSION_FIXTURE="$(mktemp -d)"
mkdir -p "$SESSION_FIXTURE/wayland" "$SESSION_FIXTURE/x11"
SESSION_DIR_WAYLAND="$SESSION_FIXTURE/wayland"
SESSION_DIR_X11="$SESSION_FIXTURE/x11"
export SESSION_DIR_WAYLAND SESSION_DIR_X11
}
@test "SDDM session probe prefers bookworm Wayland (plasmawayland)" {
_sddm_session_fixture
: >"$SESSION_DIR_WAYLAND/plasmawayland.desktop"
: >"$SESSION_DIR_X11/plasma.desktop"
run _sddm_session_candidates
[ "$status" -eq 0 ]
[ "$output" = "plasmawayland" ]
}
@test "SDDM session probe picks trixie Wayland (plasma.desktop)" {
_sddm_session_fixture
: >"$SESSION_DIR_WAYLAND/plasma.desktop"
: >"$SESSION_DIR_X11/plasmax11.desktop"
run _sddm_session_candidates
[ "$status" -eq 0 ]
[ "$output" = "plasma" ]
}
@test "SDDM session probe falls back to trixie X11 (plasmax11)" {
_sddm_session_fixture
: >"$SESSION_DIR_X11/plasmax11.desktop"
run _sddm_session_candidates
[ "$status" -eq 0 ]
[ "$output" = "plasmax11" ]
}
@test "SDDM session probe keeps LXQt last when no KDE session exists" {
_sddm_session_fixture
: >"$SESSION_DIR_WAYLAND/lxqt-wayland.desktop"
: >"$SESSION_DIR_X11/lxqt.desktop"
run _sddm_session_candidates
[ "$status" -eq 0 ]
[ "$output" = "lxqt-wayland" ]
}
@test "SDDM session probe returns empty when no session file exists" {
_sddm_session_fixture
run _sddm_session_candidates
[ "$status" -eq 0 ]
[ -z "$output" ]
}
tests/test_helper.bash
+5
View File
@@ -352,6 +352,11 @@ mock_reset() {
export MOCK_WHIPTAIL_OUTPUT="" export MOCK_WHIPTAIL_OUTPUT=""
export MOCK_WHIPTAIL_RC="0" export MOCK_WHIPTAIL_RC="0"
# CLI flags (debianito.sh parser) — reset so unattended
# mode never leaks between tests.
export AUTO_YES=0
export ALLOW_DESTRUCTIVE=0
# sudo(8) # sudo(8)
export MOCK_SUDO_DRY_RUN="0" export MOCK_SUDO_DRY_RUN="0"
export MOCK_SUDO_LOG="$(mktemp)" export MOCK_SUDO_LOG="$(mktemp)"
tests/utils.bats
+31
View File
@@ -144,3 +144,34 @@ wlan0 10.0.0.5/24"
[ "${ETH_NAMES[0]}" = "eth0" ] [ "${ETH_NAMES[0]}" = "eth0" ]
[ "${WIFI_NAMES[0]}" = "wlan0" ] [ "${WIFI_NAMES[0]}" = "wlan0" ]
} }
# ── CLI flags: --yes / --allow-destructive ──────────────
# debianito.sh (the parser) is never sourced in tests:
# mock_reset seeds the flag globals and the readers under
# test (_confirm, _branch_migration) are exercised directly.
@test "_confirm auto-accepts when AUTO_YES=1 (no whiptail call)" {
export AUTO_YES=1
# Shadow the PATH mock to count invocations: the gate
# must return before whiptail is ever executed.
WHIPTAIL_CALLS=0
whiptail() { WHIPTAIL_CALLS=$((WHIPTAIL_CALLS + 1)); return 1; }
_confirm "Title" "text"
[ "$WHIPTAIL_CALLS" -eq 0 ]
}
@test "_confirm still prompts when AUTO_YES=0" {
export AUTO_YES=0
export MOCK_WHIPTAIL_RC=1 # user answers "No"
run _confirm "Title" "text"
[ "$status" -eq 1 ]
}
@test "_branch_migration refuses unattended mode without --allow-destructive" {
source "${TEST_PROJECT_ROOT}/modules/repos/migrate.sh"
export AUTO_YES=1
export ALLOW_DESTRUCTIVE=0
run _branch_migration
[ "$status" -eq 1 ]
[[ "$output" == *"destructive"* ]]
}