54 lines
3.4 KiB
Markdown
54 lines
3.4 KiB
Markdown
# 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.
|