diff --git a/README.md b/README.md index cd40e01..47b4414 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ a refresh-rate setting does not prove delivered FPS. - [Session design](docs/superpowers/specs/2026-10-13-graphics-session-design.md) - [Implementation plan](docs/superpowers/plans/2026-10-13-graphics-session.md) - [Hardware target](docs/hardware/asus-fx517zc.md) +- [Signed runtime updates](docs/updates.md) +- [Offline Gentoo base recovery](docs/system-recovery.md) Build outputs, VM disks, runtime state and credentials stay outside Git. diff --git a/docs/legacy-runtime-update.md b/docs/legacy-runtime-update.md new file mode 100644 index 0000000..76cecfc --- /dev/null +++ b/docs/legacy-runtime-update.md @@ -0,0 +1,78 @@ +# Legacy development bundle recovery + +This procedure applies only to the early local development `.pyz` bundles. +They are not the signed public update mechanism. Do not download and execute an +untrusted bundle. New installations use [signed runtime updates](updates.md). +The following instructions are retained for recovering an already applied old +bundle and its existing backup. + + +The first ISO predates this interface. A runtime bundle updates the Hydra +program and branding files while retaining the original image manifest and +backing up replaced files under `/var/lib/hydra/updates`. It leaves VM profiles, +disks, the kernel and network configuration in place. To build one from a +trusted checkout: + +```sh +python3 dev/guest-update.py --build . --output /tmp/hydra-os-update.pyz +``` + +Copy the resulting file into Hydra, then inspect and apply it **inside Hydra**: + +```sh +python3 hydra-os-update.pyz +sudo python3 hydra-os-update.pyz --apply +``` + +The first command only prints the file inventory. After applying, open the +current Hydra recovery terminal with Ctrl+Alt+Shift+Escape, enter `:shell`, then +run this command **inside that installed Hydra graphical session**: + +```sh +labwc --exit +``` + +At the login screen, log in again as the same Hydra user. This restarts the +long-running session process with the updated code. Use this from the recovery +shell, not an SSH login or the outer host terminal. Reopening a terminal alone +cannot reload that process. Running VMs remain independent of the graphical +session. + +To reverse a successful update, or finish recovery after a reported partial +rollback, use the exact retained backup path printed by the updater. Correct +the reported filesystem problem first. Inspect its records inside Hydra: + +```sh +backup='/var/lib/hydra/updates/REPLACE_WITH_THE_REPORTED_BACKUP' +sudo python3 -m json.tool "$backup/backup.json" +``` + +Process every listed path relative to `/`. For an entry with `"existed": true`, +restore that path from the same relative location in the backup. For example, +after confirming the CLI entry originally existed: + +```sh +relative='usr/lib/hydra/hydra/cli.py' +sudo cp --no-dereference --remove-destination --preserve=mode,timestamps -- "$backup/$relative" "/$relative" +``` + +Use the same operation for other originally existing files. When `"symlink"` +is recorded, restore the symlink itself with this command; do not copy its +referent. In particular, restoring `etc/os-release` must recreate its recorded +vendor symlink while leaving `/usr/lib/os-release` intact. Check the restored +link with `readlink /etc/os-release` and compare it to `backup.json`. + +For each entry with `"existed": false`, remove only that exact installed file +using `sudo rm -f -- /THE_RECORDED_RELATIVE_PATH`; no backup copy exists for it. +This includes newly added modules, logos or the runtime-update receipt when +listed as originally absent. Copying the backup directory over `/` alone will +leave these additions behind. Confirm restored regular-file modes and SHA-256 +values against their records, retain the backup, then exit the Hydra graphical +session and log in again as described above. + +This bundle contains the Fastfetch configuration and logo, but no executable +packages. If the old installation lacks Fastfetch, install it inside Hydra: + +```sh +sudo emerge --getbinpkg --noreplace app-misc/fastfetch +``` diff --git a/docs/terminal-usage.md b/docs/terminal-usage.md index e9ca4b1..f78b40d 100644 --- a/docs/terminal-usage.md +++ b/docs/terminal-usage.md @@ -96,74 +96,30 @@ host VPN requires routing guest traffic through that VPN explicitly. Run `fastfetch` for the host summary and Hydra OS logo. Advanced administration remains ordinary Gentoo administration from the host shell. -## Update an existing test installation +## Updates and recovery -The first ISO predates this interface. A runtime bundle updates the Hydra -program and branding files while retaining the original image manifest and -backing up replaced files under `/var/lib/hydra/updates`. It leaves VM profiles, -disks, the kernel and network configuration in place. To build one from a -trusted checkout: +New images include signed runtime updates from the public repository: ```sh -python3 dev/guest-update.py --build . --output /tmp/hydra-os-update.pyz +hydra update check +sudo hydra update apply +hydra update status ``` -Copy the resulting file into Hydra, then inspect and apply it **inside Hydra**: +Record the transaction printed by apply. To reverse that runtime update, use +`sudo hydra update rollback TRANSACTION`. If the update was interrupted or the +normal CLI is damaged, run `sudo hydra-update-recover`. See +[update trust, backups and limits](updates.md). -```sh -python3 hydra-os-update.pyz -sudo python3 hydra-os-update.pyz --apply -``` +After applying or rolling back, open the host shell from the terminal menu and +run `labwc --exit` inside the Hydra graphical session. Log in again to load the +new session code; running VMs keep their independent processes and disks. -The first command only prints the file inventory. After applying, open the -current Hydra recovery terminal with Ctrl+Alt+Shift+Escape, enter `:shell`, then -run this command **inside that installed Hydra graphical session**: +Runtime updates leave the Gentoo base, kernel and guest data in place. For +Portage/kernel recovery, Btrfs installations support separate +[offline root and EFI checkpoints](system-recovery.md) made from the live ISO. -```sh -labwc --exit -``` - -At the login screen, log in again as the same Hydra user. This restarts the -long-running session process with the updated code. Use this from the recovery -shell, not an SSH login or the outer host terminal. Reopening a terminal alone -cannot reload that process. Running VMs remain independent of the graphical -session. - -To reverse a successful update, or finish recovery after a reported partial -rollback, use the exact retained backup path printed by the updater. Correct -the reported filesystem problem first. Inspect its records inside Hydra: - -```sh -backup='/var/lib/hydra/updates/REPLACE_WITH_THE_REPORTED_BACKUP' -sudo python3 -m json.tool "$backup/backup.json" -``` - -Process every listed path relative to `/`. For an entry with `"existed": true`, -restore that path from the same relative location in the backup. For example, -after confirming the CLI entry originally existed: - -```sh -relative='usr/lib/hydra/hydra/cli.py' -sudo cp --no-dereference --remove-destination --preserve=mode,timestamps -- "$backup/$relative" "/$relative" -``` - -Use the same operation for other originally existing files. When `"symlink"` -is recorded, restore the symlink itself with this command; do not copy its -referent. In particular, restoring `etc/os-release` must recreate its recorded -vendor symlink while leaving `/usr/lib/os-release` intact. Check the restored -link with `readlink /etc/os-release` and compare it to `backup.json`. - -For each entry with `"existed": false`, remove only that exact installed file -using `sudo rm -f -- /THE_RECORDED_RELATIVE_PATH`; no backup copy exists for it. -This includes newly added modules, logos or the runtime-update receipt when -listed as originally absent. Copying the backup directory over `/` alone will -leave these additions behind. Confirm restored regular-file modes and SHA-256 -values against their records, retain the backup, then exit the Hydra graphical -session and log in again as described above. - -This bundle contains the Fastfetch configuration and logo, but no executable -packages. If the old installation lacks Fastfetch, install it inside Hydra: - -```sh -sudo emerge --getbinpkg --noreplace app-misc/fastfetch -``` +Early images lack the trusted updater and pinned key; boot/install the verified +new ISO or follow the independently verified bootstrap guidance in the update +documentation. [Legacy local bundle recovery](legacy-runtime-update.md) remains +available for old test installations that already used those bundles.