Document current signed update workflow and retain legacy recovery guidance

2026-10-13 21:55:51 +03:00
parent 352f1f9acb
commit 70b7edae8a
3 changed files with 99 additions and 63 deletions
@@ -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
+```