Emil_Shanaty/Hydra-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document current signed update workflow and retain legacy recovery guidance

Browse Source
This commit is contained in:
Codex
2026-10-13 21:55:51 +03:00
parent 352f1f9acb
commit 70b7edae8a
3 changed files with 99 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2
View File
@@ -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.
docs/legacy-runtime-update.md
+78
View File
@@ -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
```
docs/terminal-usage.md
+19 -63
View File
@@ -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.