stornic56/debianito-post-install
1
0
Fork 0
mirror of https://github.com/stornic56/debianito-post-install.git synced 2026-09-14 06:02:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
53088aad4bf26469995a0fa404279f3981482041
debianito-post-install/docs/system_prefs.md
T
stornic56 53088aad4b 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

217 lines
11 KiB
Markdown
Raw Blame History

# Option 3: System Preferences
## 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.
It groups three independent preference domains behind one entry point:
| Sub-menu | Script | What It Configures |
| ---------- | -------- | --------------------- |
| **Date, Time & Timezone** | `system_prefs.sh:_prefs_date_time` | System clock, NTP sync, `tzdata` |
| **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 |
The menu itself is `_system_preferences_menu` in `system_prefs.sh` — a simple `while true` loop with `whiptail --menu`:
```
1 Date, Time & Timezone
2 Language, Locales & Keyboard
3 Audio & Sound Stack
4 Back to main menu
```
> **Note:** This option was added after the initial repository setup. The main `README.md` menu previously started directly at "Configure Repositories". All Quick Start guides now reference System Preferences as Step 3.
---
## 2. Date, Time & Timezone
### Function: `_prefs_date_time` (`system_prefs.sh`)
```
Current system date/time: 2026-03-15 14:22
Timezone: America/Santiago
→ Confirm "Change the system timezone (dpkg-reconfigure tzdata)?"
→ sudo dpkg-reconfigure tzdata
→ _ensure_time_synced
```
**What it does technically:**
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).
3. Calls `_ensure_time_synced` from `utils.sh` regardless of the answer:
- 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
- Ensures `systemd-timesyncd` is installed, enabled and restarted
- Waits 2 seconds and checks `timedatectl show --property=NTPSynchronized --value` for `yes`
**Why it matters:** An incorrect clock breaks APT GPG verification (`Release file is not valid yet`) and TLS certificates. The script runs a similar check automatically at startup (`_ensure_time_synced` in `debianito.sh` line 108), but this menu allows the user to fix timezone manually without re-running the whole script.
---
## 3. Language, Locales & Keyboard
### Function: `_prefs_locale_keyboard` (`system_prefs.sh`)
```bash
sudo dpkg-reconfigure locales
sudo dpkg-reconfigure keyboard-configuration
```
**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 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.
This option has **no detection logic** — it delegates entirely to Debian's standard tools. It is idempotent and safe to run repeatedly.
---
## 4. Audio & Sound Stack
### Function: `_prefs_audio_menu` (`system/audio.sh`)
This is the most complex sub-menu. It presents a checklist built dynamically based on system state:
#### 4.1 Menu Construction
```bash
items+=("pipewire-audio" "PipeWire Audio Stack (Bluetooth Hi-Res)" $state)
items+=("alsa-utils" "ALSA Utilities (alsa-utils, alsa-ucm-conf)" $state)
# headless check — pavucontrol is GUI-only
if ! _is_headless; then
items+=("pavucontrol" "Volume Control GUI (pavucontrol)" $state)
fi
items+=("pulsemixer" "Terminal audio mixer (pulsemixer)" $state)
items+=("playerctl" "Multimedia key controller (playerctl)" $state)
```
- **`_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.
- Package name for PipeWire varies by Debian version:
- Debian 11 Bullseye → `pipewire` (the `pipewire-audio` metapackage does not exist)
- Debian 12/13 → `pipewire-audio`
The checklist is shown via `whiptail --checklist` with the title **"Audio & Sound"**.
#### 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.
**Codec package resolution:**
```bash
bt_pkgs="libldacbt-abr2 libldacbt-enc2 libopenaptx0 libspa-0.2-bluetooth"
# Transitional package name: libfdk-aac2t64 on Trixie (64-bit time_t), libfdk-aac2 on older
if apt-cache show libfdk-aac2t64; then bt_pkgs+=" libfdk-aac2t64"
elif apt-cache show libfdk-aac2; then bt_pkgs+=" libfdk-aac2"
fi
```
These packages provide **LDAC** (Sony), **aptX** (Qualcomm), and **AAC** (via FDK) Bluetooth codecs that are not in the default PipeWire installation.
**Version selection (Trixie only, when backports is enabled):**
| Condition | Dialog | Effect |
| ----------- | -------- | -------- |
| Already installed + backports available | `Upgrade to backports vX?` (Yes/No) | `sudo apt install --reinstall -t trixie-backports pipewire-audio $bt_pkgs` + `systemctl --user restart wireplumber pipewire pipewire-pulse` |
| Not installed + backports available | `Backports vX` vs `Stable vY` (Backports/Stable buttons) | Installs from chosen repository; on Trixie `apt_target="-t trixie-backports"` if Backports chosen |
| No backports | `Install PipeWire vX with Hi-Res codecs?` | Installs from stable |
**Per-Debian-version install commands:**
```bash
# Debian 11 Bullseye
sudo apt install -y pipewire libspa-0.2-bluetooth pipewire-alsa libspa-0.2-jack $bt_pkgs
# Debian 12 Bookworm
sudo apt install -y pipewire-audio $bt_pkgs
# Debian 13 Trixie
sudo apt install -y [-t trixie-backports] pipewire-audio $bt_pkgs
```
After installation on Debian 12/13, user PipeWire services are restarted:
```bash
systemctl --user restart wireplumber pipewire pipewire-pulse
```
#### 4.3 Other Audio Packages
| Package | Purpose | Install Guard |
| --------- | --------- | --------------- |
| `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` |
| `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` |
Each package is installed via `_run_install <pkg>` which confirms the version via `apt-cache policy` before installing.
---
## 5. Logical Execution Flow
```
┌──────────────────────────────────────────────────────────┐
│ _system_preferences_menu (system_prefs.sh) │
├──────────────────────────────────────────────────────────┤
│ whiptail --menu "System Preferences" │
│ 1 Date, Time & Timezone │
│ 2 Language, Locales & Keyboard │
│ 3 Audio & Sound Stack │
│ 4 Back to main menu │
└──────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
_prefs_date_time _prefs_locale_ _prefs_audio
keyboard → _prefs_audio_menu
│ │ │
│ │ ┌───────┴────────┐
│ │ │ Dynamic checklist│
│ │ │ based on │
│ │ │ _state + headless│
│ │ └───────┬────────┘
│ │ │
│ │ pipewire-audio ──→ _install_pipewire_standard
│ │ alsa-utils ──→ apt install alsa-utils
│ │ pavucontrol ──→ apt install pavucontrol
│ │ pulsemixer ──→ apt install pulsemixer
│ │ playerctl ──→ apt install playerctl
```
---
## 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.
- **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.
- **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 at script startup. This menu is the manual override.
---
## 7. Detection & State Variables
| Variable / Function | Source | Used Here |
| --------------------- | -------- | ----------- |
| `DEBIAN_VERSION` (`11`/`12`/`13`) | `utils.sh:detect_debian_version` | PipeWire package name + install path |
| `AUDIO_SERVER` (`pipewire`/`pulseaudio`/`none`) | `utils.sh:detect_audio_server` | Bluetooth integration in `firmware.sh` |
| `is_backports_enabled` | `utils.sh:is_backports_enabled` | PipeWire backports version choice (Trixie) |
| `_is_headless` | `utils.sh:_is_headless` | Hides `pavucontrol` in TTY/SSH |
| `_state <pkg>` | `utils.sh:_state` | Checklist ON/OFF state |
| `_ensure_time_synced` | `utils.sh:_ensure_time_synced` | Called after timezone change |
---
## References
- [Debian TimeZone Config — wiki.debian.org/TimeZoneChanges](https://wiki.debian.org/TimeZoneChanges)
- [Debian Locales — wiki.debian.org/Locale](https://wiki.debian.org/Locale)
- [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)
Reference in New Issue View Git Blame Copy Permalink