sandwich/Ansible-Bootstrap
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(bootstrap): document firmware/gpu/peripherals/hardware features

Browse Source
This commit is contained in:
Sandwich
2026-04-29 22:51:09 +02:00
parent 7d45f25a7e
commit db7dc53bd7
1 changed files with 78 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@@ -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 |