Document terminal workflows and provide a backed-up guest runtime update
This commit is contained in:
Codex
@@ -0,0 +1,126 @@
|
||||
# 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. Format validation alone checks that the file looks like an ISO,
|
||||
not who published it. 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, log out of
|
||||
Hydra's graphical session and log in again so the long-running session process
|
||||
loads the new code. Reopening a terminal alone cannot reload that process.
|
||||
Running VMs remain independent of the graphical session.
|
||||
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user