3.4 KiB
Offline recovery of the Gentoo base
This separately verified part of laptop preparation supplies real OS rollback, not just runtime-file rollback. It is deliberately offline: create checkpoints from the trusted live ISO while the installed root and ESP are unmounted, perform ordinary Portage updates in the installed system, and use the ISO to recover if needed. No online application-consistency or automatic failed-boot claim is made.
The explicit Btrfs layout is @root, @home, @snapshots; /boot, kernel modules, Portage package database and world remain in @root. There must be no nested subvolumes within @root. VM disks and user data in @home survive OS recovery. GRUB/fstab/initramfs select UUID plus subvol=@root, never fixed subvolume IDs.
/etc/hydra/storage.json is the installation ownership marker with exact fields:
format=1, install_uuid, root_fs_uuid, root_partuuid, esp_uuid, esp_partuuid,
owned_efi_path='EFI/HydraOS', filesystem='btrfs', root_subvolume='@root'. The ESP
must be the recorded FAT partition; never operate on foreign EFI paths or NVRAM.
CLI hydra-system checkpoint --root-uuid UUID --esp-partuuid PARTUUID --name NAME,
hydra-system list --root-uuid UUID, and
hydra-system restore --root-uuid UUID --checkpoint ID. Changes require --execute
and --confirm-root-uuid UUID. Default plans/list are read-only. Require a genuine
Hydra live marker, root execution for changes, exactly one matching root and ESP,
ordinary unmounted partitions without active swap/holders, single-device Btrfs,
matching partition/filesystem/install UUIDs and supported owned layout.
Checkpoint mounts selected filesystems privately, snapshots @root read-only into @snapshots/ID/root and saves only EFI/HydraOS with a hash/metadata manifest. Preserve exact installed root and EFI state while offline. Durably publish the completed checkpoint descriptor last. Incomplete checkpoints cannot be restored. Snapshots remain on the same disk and are not external backups.
Restore validates all metadata, recorded source/snapshot UUIDs, readonly snapshot, layout marker and saved EFI bytes before mutation. Prepare a writable snapshot, record a durable transaction outside @root, retain the previous root under a unique failed-root name, rename the new root to @root, then restore only owned EFI files. Keep checkpoints and failed roots. Never delete @home or alter GPT, fallback EFI, foreign partitions/EFI directories or BootOrder. Directory fsync and filesystem sync delimit journal transitions. Lock operations and reject unexplained state.
Root/ESP replacement is not atomic across Btrfs and FAT. A power interruption can leave the install temporarily unbootable; rerunning restore from the live ISO must verify identities and resume the recorded transaction without guessing or deleting either root. Recovery must not invoke installed programs, fetch files, or require network access. Symlinks, malformed paths, unexpected files and tampered backup metadata fail closed before writes.
Actual acceptance uses a fresh UEFI VM, preserved foreign EFI/data sentinels, Btrfs install, live checkpoint, a real local Portage package upgrade, changed HOME, and damaged installed kernel/own EFI. After recovery boot without ISO and verify old package database/world/kernel artifacts together, updated HOME retained, and foreign bytes/GPT/BootOrder unchanged. Exercise restart after journal transition failures. Do not claim a two-kernel-version upgrade unless separately exercised.