170 lines
7.0 KiB
Markdown
170 lines
7.0 KiB
Markdown
# Using Hydra OS from the terminal
|
|
|
|
Hydra OS keeps the host small. Virtual machines have independent disks and
|
|
processes; closing a screen or the host menu does not power them off.
|
|
|
|
## Open a machine
|
|
|
|
The initial session shows the VM menu. Enter a number or a VM name. Enter alone
|
|
uses the last selection when it still exists, or the only configured VM. A
|
|
stopped VM starts; an already running one reconnects. Ctrl+Alt+Shift+Escape
|
|
opens the menu while working inside a VM, and Ctrl+Alt+Shift+Left/Right switch
|
|
between VM workspaces.
|
|
|
|
An ordinary terminal or SSH session can use:
|
|
|
|
```sh
|
|
hydra open work
|
|
hydra start work
|
|
hydra status work
|
|
hydra shutdown work
|
|
```
|
|
|
|
`open` requires a graphical display unless `--no-view` is supplied. `start`
|
|
and `shutdown` are the existing explicit lifecycle commands. Shutdown requests
|
|
an orderly guest poweroff; it does not promise instantaneous completion.
|
|
|
|
## Download and run an installer
|
|
|
|
Use a direct `.iso` download URL supplied by the distribution:
|
|
|
|
```sh
|
|
hydra run 'https://example.org/distribution.iso' --name work --memory 4096 --cpus 2
|
|
```
|
|
|
|
Replace the example URL. The command downloads a validated image, creates a
|
|
new profile, starts that VM and opens its screen. Existing names are refused
|
|
before downloads or disk changes; use `hydra open work` next time. The same
|
|
command accepts a local ISO path. Use `--no-view` to run without a viewer.
|
|
|
|
To download without creating a machine:
|
|
|
|
```sh
|
|
hydra download 'https://example.org/distribution.iso'
|
|
```
|
|
|
|
Add `--sha256` followed by the publisher's 64 hexadecimal digits to check the
|
|
download. Supported images are ISO9660 and ISO9660/UDF hybrids; pure UDF
|
|
images are currently refused because their completeness cannot be validated.
|
|
Format validation checks the declared ISO9660 volume fits the file; it does not
|
|
verify the publisher or optional trailing hybrid data. Validated files are cached under
|
|
`~/.cache/hydra/iso` (or `$XDG_CACHE_HOME/hydra/iso`). Ctrl+C cancels an active
|
|
download without publishing its partial file. HTTP is available for a local
|
|
test transfer; prefer the publisher's HTTPS endpoint for Internet downloads.
|
|
|
|
The guest OS installer still performs installation inside its virtual disk.
|
|
After it finishes, shut the guest down, detach the installer and reopen it:
|
|
|
|
```sh
|
|
hydra shutdown work
|
|
hydra status work
|
|
# Wait until status is stopped:
|
|
hydra media work --detach
|
|
hydra open work
|
|
```
|
|
|
|
This avoids accidentally booting the live ISO again. No guest disk is recreated.
|
|
|
|
## Network and host controls
|
|
|
|
The menu offers host shell and network actions. `sudo nmtui` controls the
|
|
physical host's Wi-Fi/Ethernet connections. Guests see virtual Ethernet and
|
|
receive Internet access through Hydra; they do not each select the Wi-Fi SSID.
|
|
When testing Hydra inside another VM, physical Wi-Fi remains controlled by the
|
|
outer host (currently NixOS).
|
|
|
|
The guest bridge uses `10.203.0.1/24`. A guest can SSH to `10.203.0.1` after
|
|
SSH service and authentication have been configured on Hydra. An SSH login is
|
|
not enabled automatically. Networking between Hydra and its guests does not
|
|
require Internet access. VPN clients can run in individual guests; a shared
|
|
host VPN requires routing guest traffic through that VPN explicitly.
|
|
|
|
## If something fails
|
|
|
|
- Download returns HTML: copy the actual ISO link, not its web download page.
|
|
- A checksum mismatch: do not boot that download; verify the source/checksum.
|
|
- A missing ISO: attach a valid image, or detach installation media after the
|
|
guest was installed and stopped.
|
|
- Insufficient RAM: stop an unused VM or choose a smaller guest allocation.
|
|
The launch check reserves 768 MiB on Hydra. A nested Hydra cannot see memory
|
|
pressure on the outer NixOS host; leave headroom there too.
|
|
- A viewer closes: reopen the VM. Closing a viewer does not erase its disk or
|
|
stop its running workloads.
|
|
- An unknown VM state: inspect the reported error/QEMU log. Hydra will not
|
|
blindly start a duplicate or signal a process whose identity it cannot verify.
|
|
|
|
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
|
|
|
|
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
|
|
```
|