diff --git a/README.md b/README.md index a8f0b19..f406661 100644 --- a/README.md +++ b/README.md @@ -284,6 +284,10 @@ The bootstrap auto-switches to dracut when `method: tpm2` is set. Override via ` | `chroot.tool` | string | `arch-chroot` | `arch-chroot`, `chroot`, or `systemd-nspawn` | | `initramfs.generator` | string | auto-detected | Override initramfs generator (see below) | | `desktop.*` | dict | see below | Desktop environment settings (see [4.2.5](#425-systemfeaturesdesktop)) | +| `firmware.*` | dict | see below | Vendor firmware blobs and CPU microcode (see [4.2.6](#426-systemfeaturesfirmware)) | +| `gpu.*` | dict | see below | Mesa/Vulkan and per-vendor GPU userspace (see [4.2.7](#427-systemfeaturesgpu)) | +| `peripherals.*` | dict | see below | Fingerprint readers, webcams, DisplayLink (see [4.2.8](#428-systemfeaturesperipherals)) | +| `hardware.*` | dict | see below | Hardware-detection profile override (see [4.2.9](#429-systemfeatureshardware)) | **Initramfs generator auto-detection:** RedHat → dracut, Arch → mkinitcpio, Debian/Ubuntu → initramfs-tools. Override with `dracut`, `mkinitcpio`, or `initramfs-tools`. When LUKS TPM2 auto-unlock is enabled and the @@ -303,6 +307,80 @@ and bluetooth services, and sets the systemd default target to `graphical.target Display manager auto-detection: gnome→gdm, kde→sddm, xfce→lightdm, sway→greetd, hyprland→ly. +#### 4.2.6 `system.features.firmware` + +| Key | Type | Default | Description | +| ----------- | --------------- | ------- | ----------------------------------------------------------------- | +| `enabled` | bool \| `auto` | `auto` | Install vendor firmware blobs. `auto` = on for `physical`, off for `virtual` | +| `microcode` | bool \| `auto` | `auto` | Install CPU microcode. `auto` follows `firmware.enabled` | + +Defaults are designed so a baremetal install picks up firmware automatically with no inventory entry needed, +while VMs skip it (the hypervisor handles those). The environment role detects CPU/GPU/wireless vendors from +the live host (via `lscpu` and `lspci`) and the bootstrap role installs only the matching firmware packages. +On Arch, this uses the vendor splits (`linux-firmware-amdgpu`, `linux-firmware-realtek`, etc.) so the install +stays minimal. On Debian, it uses the equivalent `firmware-*` packages. Distros without firmware splits fall +back to a single meta package. + +#### 4.2.7 `system.features.gpu` + +| Key | Type | Default | Description | +| --------------- | ------ | ------- | ---------------------------------------------------- | +| `enabled` | bool | `false` | Install Mesa, Vulkan, and per-GPU userspace | +| `nvidia_driver` | string | `auto` | One of `auto`, `open`, `proprietary`, `nouveau` | + +Pair with `desktop.enabled: true` for a working desktop. The package set is determined by the same hardware +profile as `firmware`. The `nvidia_driver: auto` default picks **`open`** (`nvidia-open` kernel modules) for +Turing or newer GPUs, falls back to **`proprietary`** for older cards on distros that ship the proprietary +driver, and falls back to **`nouveau`** elsewhere. Force a specific flavor by setting the value explicitly. + +Proprietary and open Nvidia drivers on Fedora require RPMFusion non-free, which the bootstrap enables +automatically when needed. Debian uses `nvidia-driver` from the `non-free` component (already enabled in the +managed `sources.list`). Ubuntu uses `restricted`. Arch ships both `nvidia-open-dkms` and `nvidia-dkms` in +the `extra` repository - no third-party setup required. + +#### 4.2.8 `system.features.peripherals` + +| Key | Type | Default | Description | +| ------------- | --------------- | ------- | ---------------------------------------------------------- | +| `enabled` | bool \| `auto` | `auto` | Master switch. `auto` follows `desktop.enabled` | +| `fingerprint` | bool \| `auto` | `auto` | `fprintd`/`libfprint`. `auto` = install when reader detected | +| `webcam` | bool \| `auto` | `auto` | `v4l-utils` and userspace tooling. `auto` follows `enabled` | +| `displaylink` | bool | `false` | DisplayLink dock support (explicit opt-in; see notes) | + +Fingerprint detection scans `lsusb` for known reader vendor IDs (Synaptics, Validity, Goodix, Elan, Egis, +Broadcom, AuthenTec, Upek, Futronic). When `fingerprint: auto` and a reader is present, `fprintd` and the +PAM helper are installed. PAM enrollment must be done post-install (`fprintd-enroll`). + +DisplayLink ships proprietary userspace that distros do not package consistently. The bootstrap installs the +in-tree `evdi-dkms` kernel module on Debian/Ubuntu and the `evdi` module on Fedora, but the userspace blob +must still be installed manually from DisplayLink's site after first boot. Arch users typically use AUR +(`displaylink`); this is not wired into the bootstrap. + +#### 4.2.9 `system.features.hardware` + +| Key | Type | Default | Description | +| --------- | ---- | ------- | -------------------------------------------------------------------- | +| `profile` | dict | `{}` | Hardware-detection override; empty means autodetect from live host | + +When empty, hardware is detected at the start of the bootstrap. When set, detection is skipped and the +supplied profile drives package selection - this is the **golden-image** flow: bake an image with a fixed +profile, snapshot it, and reuse the same profile on every deploy of that hardware class. + +Profile shape: + +```yaml +system: + features: + hardware: + profile: + cpu: intel # intel | amd + gpus: [intel, nvidia] # any of: intel, amd, nvidia + nvidia_supports_open: true # set false to force proprietary/nouveau + wireless: [intel] # any of: intel, amd, atheros, broadcom, + # mediatek, marvell, realtek, qcom, cirrus + fingerprint: false # set true to force fprintd install +``` + ### 4.3 `hypervisor` Dictionary | Key | Type | Default | Description |