boot-repair: refuse shadow-file cleanup on BIOS systems with no ESP
Some checks are pending
Pre-commit checks / pre-commit (push) Waiting to run
Shell tests / shell-tests (push) Waiting to run
Shell tests / arch-tests (push) Waiting to run

clean_shadow_files() assumed UEFI with an ESP mounted at /boot. On a
BIOS/GRUB system with no ESP, /boot is a plain directory on the root
filesystem holding the only kernel the machine has -- and neither existing
guard catches it: findmnt /boot is empty (GUARD 1 passes) and there is no
EFI/ or loader/ (GUARD 2 passes). boot-repair therefore read the real
vmlinuz-linux and initramfs-linux.img as "orphaned kernel file(s)
shadowing the ESP" and deleted them, leaving the machine unbootable.

Measured 2026-08-22 in a vmbox BIOS/GRUB sandbox, not theorised: after
sudo boot-repair the guest never booted again.

GUARD 3: if /sys/firmware/efi does not exist the system booted via BIOS,
so there is no ESP and nothing in /boot can be a shadow. warn + return 1,
matching the existing guards' tone and exit convention. Overridable with
the existing --esp DEVICE -- naming the ESP by hand asserts the firmware
assumption the guard otherwise checks -- rather than adding a new flag.

The check goes through rpath(), so a --root fixture declares its own
firmware type and the case is testable without a VM. On the live UEFI
machine it resolves to the real /sys path, so behaviour there is unchanged.

Audit of the other BIOS-unsafe paths (none destructive, left alone):
  * mount_esp(): resolve_esp_device fails with no /boot fstab entry, so it
    reports and does not mount. Non-destructive.
  * sync_kernel_image()/rebuild_initramfs(): gated behind boot_is_mounted,
    which is false on BIOS, so they never write.
  * check_fstab_options(): reports "no /boot entry" -- noise on BIOS, but
    it writes nothing.
  * run_preflight(): aborts every kernel upgrade on a BIOS box. Fail-closed
    and non-destructive, so out of scope here.

Tests: three cases in tests/lib/boot_repair_bios_cases.sh (new file; the
existing case lib is at the 250-line cap) -- the guard refuses and explains,
--esp overrides it, and a UEFI fixture still cleans shadows as before.
Verified failing without the guard (38/4) and passing with it (42/0).

Sandbox: BIOS guest keeps both kernel files, says why, and still boots
afterwards (uname -r 7.1.9-arch1-2 after a clean poweroff). shellcheck clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
This commit is contained in:
Krzysztof Rudnicki 2026-08-22 23:46:20 +02:00
parent d59932b262
commit aec2b275c1
5 changed files with 207 additions and 4 deletions

View File

@ -0,0 +1,67 @@
{
"intent": "Stop boot-repair from deleting the only kernel on a BIOS/GRUB system that has no EFI System Partition, without changing its behaviour on kuhy's UEFI machine.",
"scope": [
"linux_configuration/scripts/boot_recovery/boot-repair (clean_shadow_files, new system_is_uefi helper, header invariants, --esp help text)",
"linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_bios_cases.sh (new)",
"linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_cases.sh (make_root firmware parameter)",
"linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh (source + register the new cases)",
"Non-goal: fixing the other BIOS-unsafe-but-non-destructive paths (mount_esp, check_fstab_options, run_preflight) -- audited and left alone deliberately"
],
"changes": [
"Added GUARD 3 to clean_shadow_files(): when rpath(/sys/firmware/efi) is absent the system booted via BIOS, has no ESP, and /boot holds the real kernel -- warn and return 1 instead of deleting.",
"Added system_is_uefi(), expressed through rpath() so --root fixtures declare their own firmware type and the guard is testable without a VM; on ROOT=/ it resolves to the real /sys path.",
"Made the guard overridable via the existing --esp DEVICE rather than adding a new flag: naming the ESP by hand asserts the firmware assumption the guard checks.",
"Gave make_root() a third 'firmware' parameter defaulting to uefi (creates sys/firmware/efi), so the pre-existing UEFI-shaped fixtures keep their meaning.",
"Added three cases: BIOS guard refuses and explains, --esp overrides it, and a UEFI fixture still cleans shadows (regression guard for the no-behaviour-change requirement)."
],
"verification": [
{
"command": "linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh",
"result": "pass",
"evidence": "=== 42 passed, 0 failed === (was 33 before; +9 assertions across 3 new cases)"
},
{
"command": "test_boot_repair.sh with GUARD 3 neutered (system_is_uefi() { return 0; }) in a scratch copy",
"result": "fail-as-expected",
"evidence": "=== 38 passed, 4 failed === -- fails 'explains why it refused', 'names the override', 'does not claim shadows', 'real initramfs preserved'. Proves the new case actually catches the bug rather than passing vacuously."
},
{
"command": "vm new bg && vm run bg 'sudo /usr/local/sbin/boot-repair' (BIOS/GRUB sandbox)",
"result": "pass",
"evidence": "Guest confirmed BIOS-shaped first: no /sys/firmware/efi, no /boot fstab entry, findmnt /boot empty (GUARD 1 passes), no EFI//loader/ (GUARD 2 passes). boot-repair printed '[WARN] no /sys/firmware/efi -- this system booted via BIOS and has no ESP' and left /boot/vmlinuz-linux (17101312 b) and /boot/initramfs-linux.img (14957933 b) untouched. Exit 1 from the pre-existing 'no /boot entry in /etc/fstab' finding, which is BIOS noise, not a regression."
},
{
"command": "vm run bg 'sudo systemctl poweroff' then vm run bg 'uname -r'",
"result": "pass",
"evidence": "Host-side VERDICT: clean poweroff (reached 'reboot: Power down'), then the guest booted again into 7.1.9-arch1-2 with both kernel files present. This is the exact scenario that previously left the guest permanently unbootable."
},
{
"command": "vm run bg '~/tam/.../tests/test_boot_repair.sh'",
"result": "pass",
"evidence": "=== 42 passed, 0 failed === inside the BIOS guest as well as on the UEFI host."
},
{
"command": "./boot-repair --dry-run (on the real UEFI host)",
"result": "pass",
"evidence": "No BIOS warning; '[ OK ] /boot mounted (/dev/nvme0n1p1)', ESP kernel and initramfs both OK. Confirms the required no-behaviour-change on kuhy's actual machine."
},
{
"command": "shellcheck boot-repair tests/test_boot_repair.sh tests/lib/*.sh",
"result": "pass",
"evidence": "no findings"
},
{
"command": "pre-commit run --files <changed-files>",
"result": "pass",
"evidence": "all hooks pass, including the 250-line cap and shellcheck"
}
],
"risks": [
"A UEFI machine booted with efivars unavailable (e.g. an ISO rescue booted in legacy mode to repair a UEFI install) now refuses shadow cleanup. Mitigated by the --esp DEVICE override, which is named in the warning text itself.",
"The guard only covers the destructive path. A BIOS box still gets noisy FAIL lines from check_fstab_options and mount_esp, and run_preflight would abort kernel upgrades there. All are fail-closed and non-destructive; noted in the commit message rather than fixed, to keep this change narrow."
],
"rollback": [
"git revert the commit; boot-repair is self-contained and installed by copy, so re-run linux_configuration/scripts/boot_recovery/install.sh to push the reverted script to /usr/local/sbin.",
"After rollback, confirm ./boot-repair --dry-run on the UEFI host still reports '/boot mounted' and do NOT run it on any BIOS system -- the deletion bug is live again."
]
}

View File

@ -25,7 +25,8 @@
#
# Safety invariants:
# * Files under /boot are ONLY deleted while /boot is not a mountpoint AND
# contains no EFI/ or loader/ directory. Deleting them after mounting
# contains no EFI/ or loader/ directory AND the system booted via UEFI.
# Deleting them after mounting, or on a BIOS box that has no ESP at all,
# would destroy the real kernel and leave the machine unbootable.
# * EFI/ and loader/ on the ESP are never written or removed.
# * The running kernel's module tree is never deleted.
@ -96,7 +97,10 @@ Options:
only when it acts or fails.
--root DIR Operate on an alternate root (testing, or an Arch ISO
chroot). Live-only steps are skipped.
--esp DEVICE Use DEVICE as the ESP instead of auto-detecting it.
--esp DEVICE Use DEVICE as the ESP instead of auto-detecting it. Also
overrides the BIOS guard: on a system with no
/sys/firmware/efi, shadow-file cleanup is refused unless
the ESP device is named explicitly here.
-h, --help Show this help.
Exit status:
@ -243,6 +247,13 @@ boot_is_mounted() {
findmnt -n "$ESP_MOUNTPOINT" > /dev/null 2>&1
}
# True when the system booted via UEFI, i.e. an ESP can exist at all. The
# kernel only creates /sys/firmware/efi when it was loaded by EFI firmware.
#
# Expressed via rpath so a fixture tree can declare its own firmware type;
# on the live machine this resolves to the real /sys path and is exact.
system_is_uefi() { [[ -d "$(rpath /sys/firmware/efi)" ]]; }
# ----------------------------------------------------------------------------
# Repair steps
# ----------------------------------------------------------------------------
@ -373,7 +384,7 @@ check_fstab_options() {
# while the ESP was unmounted. They shadow the real ESP and waste ~250 MB.
#
# This is the single most dangerous step in the script: doing it after mounting
# would delete the real kernel. Hence the two hard guards below.
# would delete the real kernel. Hence the three hard guards below.
clean_shadow_files() {
local bootdir
bootdir="$(rpath $ESP_MOUNTPOINT)"
@ -389,6 +400,17 @@ clean_shadow_files() {
warn "unmounted $ESP_MOUNTPOINT contains EFI/ or loader/ — refusing to delete anything"
return 1
fi
# GUARD 3: on a BIOS/GRUB system there is no ESP at all, so an unmounted
# /boot is not a shadow — it is the only kernel the machine has. Deleting it
# leaves the machine unbootable (measured 2026-08-22: a BIOS guest never
# booted again). --esp is the deliberate override: naming the device by hand
# asserts the firmware assumption that /sys/firmware/efi otherwise proves.
if ! system_is_uefi && [[ -z $ESP_DEV_OVERRIDE ]]; then
warn "no /sys/firmware/efi — this system booted via BIOS and has no ESP;"
warn " $ESP_MOUNTPOINT holds the real kernel. Refusing to delete anything."
warn " If that is wrong, name the ESP explicitly: $SCRIPT_NAME --esp DEVICE"
return 1
fi
local -a shadows=()
local f

View File

@ -0,0 +1,103 @@
#!/bin/bash
# ============================================================================
# boot-repair fixture cases: BIOS/GRUB firmware guard (GUARD 3).
#
# Split out of boot_repair_cases.sh, which is at the 250-line cap. Sourced by
# test_boot_repair.sh and relies on the helpers defined there (make_root,
# run_repair, assert_*).
#
# The bug these cover was measured on 2026-08-22 in a vmbox sandbox: on a
# BIOS/GRUB guest with no ESP, boot-repair read the real /boot/vmlinuz-linux
# and /boot/initramfs-linux.img as "orphaned kernel file(s) shadowing the ESP"
# and deleted them. The guest never booted again.
# ============================================================================
# A BIOS box, shaped exactly like the guest that lost its kernel: no
# sys/firmware/efi, and a /boot that holds the real kernel with no EFI/ or
# loader/ to trip GUARD 2.
make_bios_root() {
local name="$1"
local r
r="$(make_root "$name" 7.1.5-arch1-2 bios)"
# GRUB keeps its kernel in a plain /boot directory on the root filesystem.
rm -rf "${r:?}/boot"
mkdir -p "$r/boot/grub"
printf 'Linux version 7.1.5-arch1-2 (linux@archlinux) fake image\n' \
>"$r/boot/vmlinuz-linux"
printf 'usr/lib/modules/7.1.5-arch1-2/kernel/fs/fat/vfat.ko.zst\n' \
>"$r/boot/initramfs-linux.img"
# A BIOS system has no /boot entry in fstab; /boot is just part of /.
printf 'UUID=DEAD-BEEF\t/\text4\tdefaults\t0 1\n' >"$r/etc/fstab"
printf '%s' "$r"
}
test_bios_guard_refuses_to_delete_real_kernel() {
echo "TEST: SAFETY — BIOS/GRUB system without an ESP keeps its real kernel"
local r out
r="$(make_bios_root bios)"
out="$(run_repair "$r")"
assert_contains "explains why it refused" "$out" "this system booted via BIOS"
assert_contains "names the override" "$out" "--esp DEVICE"
assert_not_contains "does not claim shadows" "$out" "removed 2 shadow file"
if [[ -f $r/boot/vmlinuz-linux ]]; then
pass "real kernel image preserved"
else
fail "real kernel image preserved" "boot-repair deleted the only kernel!"
fi
if [[ -f $r/boot/initramfs-linux.img ]]; then
pass "real initramfs preserved"
else
fail "real initramfs preserved" "boot-repair deleted the only initramfs!"
fi
}
test_bios_guard_overridden_by_explicit_esp() {
echo "TEST: --esp DEVICE overrides the BIOS guard"
local r out
r="$(make_bios_root biosesp)"
# Naming the ESP by hand asserts the firmware assumption the guard checks,
# so cleanup proceeds exactly as it would on a UEFI box.
out="$(run_repair "$r" --esp /dev/fake1)"
assert_not_contains "guard is silent" "$out" "this system booted via BIOS"
assert_contains "treats the files as shadows" "$out" "orphaned kernel file"
# initramfs-linux.img is not regenerated by a --root run, so its absence
# proves the deletion happened. (vmlinuz-linux legitimately reappears:
# sync_kernel_image reinstalls the target kernel straight afterwards.)
if [[ ! -f $r/boot/initramfs-linux.img ]]; then
pass "shadow initramfs deleted under --esp"
else
fail "shadow initramfs deleted under --esp" "guard did not yield to --esp"
fi
}
# A UEFI fixture must keep behaving exactly as before — the guard must not
# change anything on kuhy's actual (UEFI) machine.
test_uefi_shadow_cleanup_still_works() {
echo "TEST: REGRESSION — UEFI system still cleans shadow files"
local r out
r="$(make_root uefishadow)"
rm -rf "${r:?}/boot"
mkdir -p "$r/boot"
printf 'Linux version 7.1.5-arch1-2 (linux@archlinux) fake\n' >"$r/boot/vmlinuz-linux"
printf 'stale\n' >"$r/boot/initramfs-linux-fallback.img"
out="$(run_repair "$r")"
assert_not_contains "guard stays out of the way" "$out" "this system booted via BIOS"
assert_contains "still detects shadows" "$out" "orphaned kernel file"
if [[ ! -f $r/boot/initramfs-linux-fallback.img ]]; then
pass "UEFI shadow deletion unchanged"
else
fail "UEFI shadow deletion unchanged" "guard blocked a legitimate cleanup"
fi
}

View File

@ -13,13 +13,20 @@
#
# Builds a consistent system: one complete kernel tree, an ESP whose kernel
# and initramfs match it, a gating fstab and serial downloads.
# make_root <name> [kver] [firmware]
# firmware: "uefi" (default) creates sys/firmware/efi, so boot-repair sees an
# ESP-capable system; "bios" omits it, which is what a GRUB/BIOS box looks like.
make_root() {
local name="$1"
local r="$WORKROOT/$name"
local kver="${2:-7.1.5-arch1-2}"
local firmware="${3:-uefi}"
mkdir -p "$r/usr/lib/modules/$kver/kernel/fs/fat"
mkdir -p "$r/boot" "$r/etc" "$r/var/cache/pacman/pkg"
if [[ $firmware == "uefi" ]]; then
mkdir -p "$r/sys/firmware/efi"
fi
# Fake kernel image carrying the version banner boot-repair greps for.
printf 'Linux version %s (linux@archlinux) fake image\n' "$kver" \

View File

@ -64,7 +64,8 @@ assert_eq() {
# shellcheck source=lib/boot_repair_cases.sh
source "$SCRIPT_DIR/lib/boot_repair_cases.sh"
# shellcheck source=lib/boot_repair_bios_cases.sh
source "$SCRIPT_DIR/lib/boot_repair_bios_cases.sh"
# ----------------------------------------------------------------------------
# Runner
@ -91,6 +92,9 @@ main() {
test_fstab_nofail_fixed
test_shadow_files_removed
test_shadow_guard_refuses_real_esp
test_bios_guard_refuses_to_delete_real_kernel
test_bios_guard_overridden_by_explicit_esp
test_uefi_shadow_cleanup_still_works
test_parallel_downloads_fixed
test_missing_modules_dep
test_no_kernel_at_all