Docs / HosterOS

HosterOS installation

The fourteen-screen installer, one screen at a time: what each one asks, what it does with the answer, and which decisions you cannot revisit later.

HosterOS turns a machine booted from the live ISO into a configured Hoster node. It partitions the disks, builds the ZFS pools, installs Ubuntu 26.04 LTS or Rocky Linux 10 from an archive already on the media, and configures networking, the internal bridge, swap, the ARC limit and any PCI devices you want to hand to guests.

It is a terminal interface, which means it works the same way on a physical console, in an iDRAC or iLO window, and over SSH. Nothing needs a browser or a graphical session.

The screenshots below were taken in the installer’s UI preview mode (--ui-preview), which draws every screen against sample hardware, needs no root, and touches nothing. The real installer looks identical — it just has your disks in it. To rehearse against your own hardware without erasing it, use --dry-run instead.

Screenshot

Take a photo or capture of the ISO being written to a USB stick, or the server's virtual-media dialog with the HosterOS ISO attached — something that shows the starting point before the installer appears.

Before you start

  • The HosterOS live ISO, written to USB or attached as virtual media.
  • At least one disk you are willing to erase. Two if you want a mirror.
  • Root access on the live environment. The live system boots the installer on tty1 automatically.
  • Networking is optional — the rootfs archives are on the ISO and the install is fully offline. You only need a network if you want to drive the installer over SSH.

Finishing the install from your desk

You almost never have to stay at the console. When the installer starts on the live system it starts SSH, enables root login, generates a one-time password for that boot, and prints the credentials and the exact ssh command on its first screen.

ssh root@<live-environment-ip>
cd /opt/hosteros-installer
./HosterOS

The password is generated once per live boot and stored in the clear at /run/hosteros-installer/ssh-credentials. That is deliberate: the live system is a throwaway, RAM-backed environment, the password does not survive a reboot, and you have to be able to read it off the console. Re-running the installer reuses it rather than locking you out. The installed system’s root password is a separate thing you set on screen 7.

If the live system never got an address, the panel says so and shows no SSH details, because there would be nothing to connect to. Bring up networking and restart the installer and they appear.

Reading the screens

Every screen shares the same frame. On the left is the step list with a marker on where you are, and beneath it a running summary of every decision so far — so the consequences of a change are visible from any screen, not just the review. The bottom bar shows the keys that work here. ? opens the controls help from anywhere, and PgUp/PgDn move between screens.

1 · Welcome

HosterOS installer welcome screen with the step list, a running summary, the remote SSH panel, an installation overview and important notes.
Step 1 of 14 — Welcome. The right column states plainly what the installer will change: it erases only the disks you explicitly check, installs the target archive and boot mode you choose, generates host networking, the internal VM bridge, swap and ARC settings, and optionally prepares PCI functions for passthrough. The notes at the bottom are the ones worth reading twice — disks are addressed by their most stable path (by-id, falling back to by-path, falling back to the raw node), and selected PCI devices are bound to vfio-pci during early boot. In a live install this panel also carries the generated SSH credentials.

The sentence that governs the whole flow is at the foot of the overview: every value is reviewed before a separate hostname confirmation unlocks installation. Nothing here is destructive until screen 13, twice over.

2 · Hostname

Hostname screen with an input, live validation reading valid hostname, and the naming rules.
Step 2 of 14 — Hostname. Validated as you type rather than when you continue. Lowercase letters, digits, hyphens and dots; dots are allowed so you can use a fully qualified name deliberately; 1–63 characters; no leading or trailing hyphen.

Choose carefully — this is also the string you will have to type from memory at the destructive confirmation on screen 13.

3 · Disks

Disk selection listing two Samsung NVMe drives checked and a Micron drive unchecked, with a detail panel for the highlighted disk.
Step 3 of 14 — Disks. The red line at the top is the whole safety model: only checked disks will be erased. Everything else on the machine is left alone. Space toggles the highlighted row. The panel on the right resolves the highlighted disk to the exact path the installer will use and tells you which identifier it settled on — here by-id, with by-path unavailable. The third disk in this example is flagged by-path, meaning it has no stable by-id link.

By-id paths survive re-cabling and controller reordering; /dev/sdX does not. This is why the installer prefers them and shows you which one it picked.

4 · ZFS layout

ZFS topology selection showing stripe and mirror options with usable capacity and protection, and a details panel for mirror.
Step 4 of 14 — ZFS layout. Only topologies your disk selection can actually satisfy are offered, each with its usable capacity and what it survives. Stripe across these two disks yields 3.49 TiB and no redundancy; mirror yields 1.75 TiB and survives one disk. Capacity is computed from the smallest member, so a mismatched pair is priced honestly.

This is the decision you cannot revisit. Changing the topology later means reinstalling. Redundancy is not a backup, but a mirror is the difference between a dead disk being an inconvenience and being an outage.

5 · Target OS

Target OS selection listing Ubuntu 26.04 LTS and Rocky Linux 10 rootfs archives with checksums present, Rocky selected, and locale and timezone actions.
Step 5 of 14 — Target OS. Both distributions ship on the ISO as checksummed rootfs archives, which is what makes the install offline: nothing is fetched. The Checksum: present column is the pre-flight for that — an archive without one will not be used. Locale and timezone are set here too, through the two action buttons at the bottom, and the package mirror comes from the profile unless you override it.

Pick the distribution your team already knows how to operate. Hoster itself behaves the same on both.

6 · Firmware

Firmware mode screen with UEFI selected and BIOS shown as unsupported on this machine.
Step 6 of 14 — Firmware. This decides the partition layout, so it has to match how the machine actually boots. The installer detects what the platform supports and greys out what it does not — here BIOS is unavailable. UEFI is the default and the right answer unless the hardware is genuinely legacy-only, in which case the layout gains a small BIOS boot partition.

7 · Root password

Root password screen with password and confirmation fields, a visibility toggle, live validation and the requirements.
Step 7 of 14 — Root password. For the installed system — unrelated to the one-time live-session password from the welcome screen. Minimum twelve characters, with length and match validated live so you do not discover a typo after the install. There is a visibility toggle, and the reason is in the requirements: Caps Lock state cannot be detected reliably through a remote console.

The requirements panel also states the position worth keeping: password-based remote root login stays disabled unless you explicitly need it. Use keys.

8 · Host network

Host network screen listing two ethernet interfaces and a VLAN, with a link details panel and add and delete VLAN actions.
Step 8 of 14 — Host network. Physical interfaces and VLANs in one list, each with its address, link state and negotiated speed, so you can tell a cabling problem from a configuration problem before you install. The summary line reports readiness across the whole screen: how many interfaces are addressed, how many default routes exist, and how many have DNS. Here eno2 is down and left unchecked, and a VLAN with tag 120 rides on eno1.

Interfaces are matched by MAC and given a stable name, so the configuration survives the kernel renaming devices between boots. Each one can take a static address or DHCP.

9 · PCI passthrough

PCI passthrough screen listing a GPU, its audio function and a network controller with IOMMU groups, and a preparation panel.
Step 9 of 14 — PCI passthrough. Devices you reserve here are bound to vfio-pci in early boot and handed to guests rather than the host. The panel on the right shows the installer detected an AMD CPU and will add amd_iommu=on iommu=pt to the kernel arguments. Note the two NVIDIA rows: selecting the GPU also selected its audio function, because both sit in IOMMU group 34 and an IOMMU group can only move as a unit.

Doing this at install time means the bindings are in the initramfs from first boot, so the host never briefly claims the GPU on its way up.

9.1 · The experimental laptop workaround

The checkbox at the bottom — Laptop/SoC ACS workaround (EXPERIMENTAL) — is for the case where a discrete GPU shares its IOMMU group with an upstream PCIe root port that has no ACS, which is common on laptops and some mini PCs and SoCs. Enabling it installs a boot-time service that binds the selected functions to vfio-pci and unbinds the upstream root port from pcieport, making an otherwise unusable group viable.

Leave it off on desktops and servers. There the GPU usually has its own clean group and releasing a root port is unnecessary and potentially disruptive.

10 · Hoster bridge

Internal bridge screen with subnet, gateway address, DHCP pool start and end, and a defaults panel confirming the layout.
Step 10 of 14 — Hoster bridge. The internal network your guests are born onto. The bridge address is their default gateway and their DNS server, and the pool is the range Hoster assigns from when you deploy a VM without naming an address. The panel does the arithmetic for you — 191 usable addresses here — and validates that the pool sits inside the subnet.

Choose a private range that does not overlap your host uplinks or any VPN you will route to this machine. Overlapping ranges are painful to unpick after guests exist on them.

11 · Swap size

Swap size screen with a recommended preset, an input, and a calculator showing per-disk and total swap.
Step 11 of 14 — Swap size. The number is per disk, not total, and the calculator makes that unambiguous: 16 GiB across two selected disks is 32 GiB of swap. One swap partition is created on each installer disk and added to /etc/fstab. The guidance offers the usual bands — 8 for a small lab box, 16 for a moderate host, 32 or more where memory pressure is real.

12 · ARC limit

ZFS ARC limit screen showing the selected value against the recommendation, with a warning that the selection is below it.
Step 12 of 14 — ARC limit. ARC is the ZFS read cache, and this caps it. The installer detected 128 GiB of RAM and recommends 10% of it; the value typed here is 6000 MiB, and the screen says plainly that this is 7107 MiB below the recommendation rather than silently accepting it. Written as a modprobe setting and included in the initramfs, so the cap applies from the first boot.

The trade-off is stated on the screen and is worth taking seriously on a hypervisor: too little ARC and you lose cache hits, too much and you are competing with the guests for memory. On a host whose job is running VMs, leaving headroom is usually right.

13 · Review

Review screen listing system, storage, target OS, network and PCI passthrough sections of the planned installation.
Step 13 of 14 — Review. Every decision in one scrolling summary, grouped the way you made them. The storage section is titled WILL BE ERASED and names each disk by device and by-id, so you are confirming against stable identifiers rather than the /dev/nvme… name that could have moved. The action bar stays fixed while the summary scrolls, and the warning line at the bottom never leaves the screen.

Read the network section carefully — it is the last place the VLAN tags, the bridge range and the DHCP pool appear together before they are written.

Destructive confirmation listing the disks to be erased and requiring the hostname to be typed before installing.
Step 13 of 14 — the destructive confirmation. The last gate, and the only one that asks you to type. It re-lists exactly which disks will be erased with their sizes and models, then requires the hostname from screen 2 before the install button does anything. Typing a name is a deliberately poor fit for muscle memory — you cannot dismiss this by holding Enter.

14 · Install

Installation running at 83 percent on step five of six, with a progress bar and a live execution log.
Step 14 of 14 — Install, running. Six phases, with the current one named, a percentage, elapsed time and a live execution log — plus Show raw file log when you want the unfiltered output. The left-hand summary grows a progress line so the state is legible even from a narrow console. Ctrl+C requests cancellation rather than killing it outright.

A real install runs seven steps, in order, each with rollback if it fails:

  1. Preflight — confirms it is on supported live media, that every disk and ZFS tool it needs is present on the ISO, and stops zed so it cannot fight over the pools.
  2. Disk preparation — swap off, partition tables and filesystem signatures wiped, then the layout written to each selected disk (see below).
  3. Pool creation — rpool in the topology you chose, plus bpool where the target uses a separate boot pool, mirrored when there are several disks.
  4. Datasets — the standard dataset hierarchy under rpool.
  5. Bootstrap — verifies the rootfs archive against its checksum, extracts it, and sets hostname, /etc/hosts and package repositories.
  6. Chroot setup — locale, timezone, kernel, GRUB/EFI, the profile’s network backend, the ZFS hostid and the ZFS initramfs hooks.
  7. Finalize — everything is unmounted and the pools are exported cleanly.

The screenshot above shows six stages because preview mode simulates a shortened run. A real install reports seven.

The partition layout depends on the distribution you picked

This is the one place where screen 5 has a consequence beyond which userland you get:

Ubuntu Rocky
EFI partition 512 MB 4 GB
Swap your size, per disk your size, per disk
Separate bpool yes, 3 GB no
Root pool remaining space remaining space

Ubuntu keeps /boot on a small separate ZFS pool, so GRUB only has to read a pool created with a conservative feature set. Rocky puts it in a larger EFI partition and has no bpool at all. BIOS mode adds a 1 MB BIOS boot partition, where a separate boot pool is in use.

Nothing about operating the node changes; it is worth knowing before you go looking for bpool on a Rocky machine and do not find it.

Installation complete at one hundred percent with a dialog offering exit or reboot.
Step 14 of 14 — complete. All six phases done and the pools exported. On a real install the dialog offers Exit or Reboot; in preview mode it says outright that no disks were changed and no machine will reboot. Exporting the pools cleanly is what makes the first boot from ZFS uneventful.
Screenshot

Take a screenshot of the first successful boot: the GRUB entry, or the login prompt of the installed system with the hostname visible.

After the reboot

Remove the installation media and reboot. The machine comes up on its new ZFS root, with the network, bridge, swap and ARC settings you chose, and any passthrough devices already bound to vfio-pci.

Expect it to reboot itself once or twice more

This is normal, and it is not a failure. After your first boot the machine will restart itself — usually once, sometimes two or three times in total before it settles. Let it. Do not interrupt it, and do not reach for the installer again.

Those extra boots are how the root pool’s import gets made reliable. Running the root filesystem on ZFS means the pool has to be imported by the initramfs, before the system that owns it is running, and getting that to happen the same way every time takes a handful of things agreeing with each other:

  • a stable /etc/hostid, generated for this machine and also passed on the kernel command line as spl_hostid, so the pool is not seen as belonging to another host
  • a zpool.cache baked into the initramfs that matches the pool as it now exists
  • an initramfs rebuilt after both of those are in place

The installer sets all of it up, but some of it can only settle on a real boot of the installed system rather than from inside the installer’s chroot. A one-shot service handles that pass and then disables itself, leaving a marker at /var/lib/hosteros/first-boot-reboot.done so it never runs again.

We would rather this were not here. It is a limitation of ZFS-on-root that we have not found a clean way around yet, not a design decision. If the machine is still rebooting after the third time, that is a genuine fault — grab /var/log/hosteros-installer.log and tell us, because at that point something else is wrong.

There is no bootstrap step — the installer already did that work. Log in, check the node with hoster host info, and go straight to Your first VM.

Running it again, or by hand

The installer is a single binary on the live media. If it exits you land in a rescue shell and can start it again:

cd /opt/hosteros-installer
./HosterOS
Flag Default What it does
--dry-run false Walks every screen against your real hardware and simulates the phases, without touching a disk
--ui-preview false Draws every screen against synthetic hardware; needs no root and does no discovery
--log-path /var/log/hosteros-installer.log Where the installation log is written
--version — Print the version and exit

--dry-run is the honest way to rehearse an install — on the exact machine, with its real disks listed, without erasing anything.

Something unclear on this page?

Ask about this specific page and we will come back to you. Your question arrives with a link to it, so you do not have to describe where you were.