166 lines
9.0 KiB
Markdown
166 lines
9.0 KiB
Markdown
# Install Hydra OS
|
|
|
|
Hydra OS targets x86_64 UEFI systems. Disable Secure Boot for this first image.
|
|
For a USB flash drive, use the [2026-10-14 corrected ISO](releases/2026-10-14-usb-fix/README.md),
|
|
`hydra-os-usb-fixed.iso`. The original 0.2.0 ISO passed optical-media tests but has
|
|
a raw USB live-boot bug. Write the corrected image to the entire flash drive
|
|
using a host-native image writer; this erases that flash drive. Mounting it before
|
|
reboot is unnecessary. Physical firmware compatibility still requires testing.
|
|
Boot the ISO and enter `:shell` in the terminal VM menu. The live session uses a locked
|
|
`hydra-live` account with local sudo access; changes in the live filesystem are
|
|
volatile. The image provides no default SSH login or universal installed password.
|
|
|
|
`hydra-install` lists disks without selecting one. Inspect the devices, then ask
|
|
for a plan using either the explicitly chosen existing partitions or a whole disk.
|
|
The commands below use placeholders; the installer never chooses devices automatically.
|
|
|
|
## Preserve existing partitions
|
|
|
|
Choose a root partition whose contents you intend to replace and an existing FAT
|
|
GPT EFI System Partition (ESP). Inspect their identities and sizes with `lsblk`.
|
|
Both selected partitions must be unmounted; unrelated mounted siblings are allowed.
|
|
|
|
```sh
|
|
sudo hydra-install --root-partition /dev/CHOSEN_ROOT \
|
|
--esp-partition /dev/CHOSEN_ESP --user YOUR_USER --root-fs btrfs
|
|
```
|
|
|
|
This dry-run describes the operation. To execute the same choice:
|
|
|
|
```sh
|
|
sudo hydra-install --root-partition /dev/CHOSEN_ROOT \
|
|
--esp-partition /dev/CHOSEN_ESP --user YOUR_USER --root-fs btrfs \
|
|
--execute --confirm-format /dev/CHOSEN_ROOT
|
|
```
|
|
|
|
`--confirm-format` must name the canonical resolved root path exactly, even if an
|
|
input path is an alias. This mode formats **only the selected root partition**.
|
|
It never recreates GPT, changes partition boundaries, or formats the ESP. Before
|
|
formatting, it checks uncompressed payload capacity, mounts the ESP read-only,
|
|
refuses any existing `EFI/HydraOS` collision, and requires at least 64 MiB free.
|
|
It fingerprints foreign ESP files and verifies their hashes after installation.
|
|
|
|
GRUB writes `EFI/HydraOS/grubx64.efi` using `--no-nvram` without `--removable`.
|
|
Existing EFI loaders, `EFI/BOOT/BOOTX64.EFI`, and firmware BootOrder are preserved.
|
|
By default, select that Hydra EFI file manually in your firmware boot interface.
|
|
`--register-boot-entry` opts into `efibootmgr --create-only`: it creates a new
|
|
HydraOS entry without adding it to BootOrder. Firmware support for selecting EFI
|
|
files and managing entries varies.
|
|
|
|
Only plain, nonoverlapping GPT partitions on physical disks are supported. Root
|
|
and ESP may reside on different disks. Device mapper, encrypted/LVM/RAID targets,
|
|
nested partition devices, missing identities/bounds, active holders, and ambiguous
|
|
backing information are rejected. Mounted Btrfs filesystems must report every
|
|
backing member; an incomplete or missing-device report is rejected. ZFS backing
|
|
anatomy is unsupported and causes a conservative refusal. The checks are
|
|
repeated just before formatting; do not change mounts or storage topology during
|
|
installation. They cannot replace your inspection and backups.
|
|
|
|
`--root-fs ext4` is the default. Btrfs creates `@root`, `@home`, and `@snapshots`.
|
|
The kernel, `/boot`, and Portage database stay inside `@root`; `/home` (including
|
|
guest disks) uses `@home`, and `/.snapshots` uses `@snapshots`. fstab and boot
|
|
arguments use filesystem UUIDs and named subvolumes, without a fixed root
|
|
subvolume ID. The layout alone does not implement system rollback; full Gentoo
|
|
and kernel recovery requires separate bootable verification.
|
|
|
|
An installed, root-owned mode-0600 `/etc/hydra/storage.json` records format 1, a
|
|
random install UUID, root/ESP filesystem UUIDs and GPT PARTUUIDs, filesystem type,
|
|
and owned EFI path `EFI/HydraOS`. Btrfs additionally records
|
|
`root_subvolume: "@root"`. Treat this identity record as installation metadata,
|
|
not an update payload.
|
|
|
|
## Erase a whole disk
|
|
|
|
Use this mode only when every partition on the explicitly chosen disk may be erased:
|
|
|
|
```sh
|
|
hydra-install
|
|
sudo hydra-install --disk /dev/CHOSEN_DISK --user YOUR_USER
|
|
```
|
|
|
|
Replace the placeholders with an actual whole disk and your desired account
|
|
name. The installer rejects mounted devices, the running root, the live medium,
|
|
and their backing disks. These checks help prevent mistakes; verify the chosen
|
|
disk and preserve backups before executing the plan. Physical disk installation
|
|
requires the operator's explicit choice.
|
|
|
|
To execute, enter the identical resolved whole-disk path in the confirmation:
|
|
|
|
```sh
|
|
sudo hydra-install --disk /dev/CHOSEN_DISK --user YOUR_USER \
|
|
--execute --confirm-erase /dev/CHOSEN_DISK
|
|
```
|
|
|
|
Execution erases the disk, creates a 1 GiB FAT32 EFI partition and an ext4 root (or Btrfs with `--root-fs btrfs`),
|
|
extracts the prepared payload, and prompts twice on the local terminal for your
|
|
installed account password. Passwords have no command-line or configuration
|
|
option. The installed root account stays locked. Defaults are Europe/Moscow and
|
|
English UTF-8, with Russian UTF-8 also available; `--timezone` accepts an IANA
|
|
zone present in the payload.
|
|
|
|
The installer removes the live account, local password-free sudo rule, and
|
|
live autologin overrides, then builds a normal disk initramfs, its owned HydraOS UEFI loader, and a fallback
|
|
UEFI loader on the newly created ESP. Both installation modes keep os-prober disabled. Wait for `Installation completed`, power off, remove the ISO, and boot
|
|
the installed disk. Log in with the account and password you supplied. On
|
|
failure, read the printed live diagnostic path; when a target root was mounted,
|
|
a nonsecret snapshot is also saved at `/var/log/hydra-install.log` on that disk.
|
|
|
|
## Disposable VM acceptance
|
|
|
|
Run the repository harness with QEMU/KVM, `qemu-img`, Python 3, and a generic
|
|
x86_64 QEMU OVMF CODE/VARS pair. A Xen-specific OVMF build is unsuitable: the
|
|
first validation attempt with that variant produced no guest boot output.
|
|
Use trusted image and matching firmware files. For example:
|
|
|
|
```sh
|
|
install -d -m 700 "$HOME/.cache/hydra-tests"
|
|
python3 dev/iso-smoke.py --iso /absolute/path/to/hydra-os.iso \
|
|
--ovmf-code /absolute/path/to/OVMF_CODE.fd \
|
|
--ovmf-vars /absolute/path/to/OVMF_VARS.fd \
|
|
--scratch-parent "$HOME/.cache/hydra-tests"
|
|
```
|
|
|
|
The harness creates a private directory under `--scratch-parent` (`/tmp` by default), a new 32 GiB sparse
|
|
qcow2 disk, and a private copy of OVMF variables. There is no existing disk
|
|
argument. QEMU attaches the ISO read-only; serial and QMP use private Unix
|
|
sockets. Tool overrides `--qemu` and `--qemu-img` support temporary development
|
|
environments. `--scratch-parent`, `--memory`, `--boot-timeout`, and
|
|
`--install-timeout` control retained artifacts and bounded resource use.
|
|
Prefer a disk-backed scratch directory: an installed disk stored on a tmpfs
|
|
such as `/tmp` consumes host RAM. The example keeps test data in the user's cache.
|
|
|
|
The test boots the live image, runs the real installer through the guest's
|
|
controlling terminal using a generated password, writes a persistence sentinel,
|
|
shuts down, and launches a second QEMU with the ISO absent. It verifies password
|
|
login, disk root, removed live overrides, services, bridge/NAT configuration,
|
|
DNS, recovery tools, and a routed new TCP connection from a synthetic LAN to a
|
|
synthetic VM endpoint. Network namespaces and veth interfaces exist only inside
|
|
the disposable Hydra OS guest. When guest KVM is available, it launches a further
|
|
fresh-disk QEMU as the installed account to exercise KVM, the bridge helper,
|
|
and private QMP; this checks VM launch, not a nested operating system boot.
|
|
The installed normal account also exercises the packaged terminal menu,
|
|
downloads a complete nonboot ISO fixture from a private loopback HTTP server,
|
|
starts a scratch VM with `hydra run`, checks cache reuse and stable process/QMP
|
|
identity through `hydra open`, and verifies the default Fastfetch logo/name.
|
|
This fixture checks the command flow, not a nested guest OS boot.
|
|
|
|
The harness also logs the installed account out and back in, checking that the same VM,
|
|
private sockets and user audio services survive a measured interval without an
|
|
open login session. This establishes process/socket continuity, not audio playback.
|
|
|
|
`report.json` records each observed check, ISO/firmware SHA256, failures, and
|
|
skipped nested virtualization. Serial/QEMU logs and the qcow2 remain in the
|
|
printed scratch directory for review; passwords are redacted even across serial
|
|
read boundaries. Cleanup controls only the QEMU process created by this run.
|
|
A passing unit suite establishes harness behavior, not ISO acceptance. An
|
|
actual successful report from the built ISO is required for boot/install/reboot
|
|
acceptance.
|
|
|
|
## Checks requiring the laptop
|
|
|
|
Disposable QEMU results cannot establish ASUS FX517ZC hardware support. Before
|
|
using Hydra OS daily, boot the live ISO and observe Wi-Fi, touchpad, audio,
|
|
brightness, suspend/resume, USB device selection, input capture, and actual
|
|
display refresh. Physical installation and these checks remain pending until
|
|
explicitly performed and recorded.
|