Docs · 1.0

Installation

keelOS is installed at the beginning of one disk, as a 2 GiB boot partition. The installer only asks which disk to install on; everything else (the rest of the space on that disk, other disks, the admin password) is set up afterwards in the web page. The whole process takes about ten minutes.

Read the hardware requirements first, especially that in the firmware you must turn Secure Boot off and boot in UEFI mode only.

1. Download the ISO

Download the latest keelos-<version>.iso from the releases page on GitHub. The .sha256 file next to it can be used to verify the download. The version number is a commit id plus the build time, for example keelos-3c16e6c-20261012T040844Z.iso.

This ISO is a "hybrid" image: it can be used as an optical disc (the virtual CD drive of a server's IPMI) and it can also be written to a USB stick as it is.

2. Write it to a USB stick (or mount it over IPMI)

With a USB stick (1 GB or more is enough; everything on it will be erased):

• Windows: use Rufus, pick the ISO, and in the dialog that pops up choose Write in DD Image mode. Afterwards Disk Management shows two partitions (about 480 MB and 4 MB); that is correct.
• Linux / FreeBSD: dd if=keelos-<version>.iso of=/dev/<usb stick> bs=4M (be sure to get the device name after of= right).
• Do not use Ventoy, and do not use Rufus's "ISO Image mode": they can get the system to boot, but once it is up it cannot see the ISO, and the installer says it cannot find the keelOS installation medium (no ISO9660 volume KEELOS). Rewrite the stick with the methods above. Do not unplug the stick before the installation is finished.

With a server's IPMI / BMC: mount the ISO as virtual media (Virtual Media) and boot from the CD drive next time.

3. Boot from the USB stick

1. Plug in the stick, press the boot menu key while powering on (commonly F11, F12 or Esc), and choose the entry with UEFI: in its name.
2. First you see FreeBSD booting (the installation disc does not start the keel hypervisor, so the screen stays at the firmware's resolution), and finally the installer appears. Reading the system from the stick takes a minute or two.

If you cannot see the stick: check that CSM/Legacy and Secure Boot are off in the firmware; on Lenovo machines also check whether the stick is in the Excluded from boot order list (see Hardware requirements).

4. The installer

The installer is a text question-and-answer session on the console, in English (the console font has no Chinese). Just press Enter to take the default in square brackets.

First question: install or quit

  1) install
  2) quit: write nothing
Choice [1]:

• 1) install: install to disk.
• 2) quit: write nothing and return to the login prompt. The installation disc has no "just try it" mode: without an installation there is no storage pool, so virtual machines cannot start.

If keelOS is already installed on this machine, there are three choices instead: 1) upgrade (writes the new version to the other slot; settings, storage pools and virtual machines are untouched; see Upgrade and restart), 2) fresh install (wipes one disk and installs from scratch) and 3) quit.

Second question: which disk to install on

The installer lists all disks: the name (like ada0, nda0), the size, the model, and what is on the disk now (partitions, other systems, ZFS pools).

1. Type the name of the disk, for example nda0.
2. If there is something on the disk, the installer says what it is and asks you to type the disk name again to confirm the wipe. Press Enter to choose a different disk instead.
3. ZFS pools left by other systems (for example the data disks of a former NAS) are listed, but the installer does not touch them; you can import those disks later in the web page, or pass them through to a NAS virtual machine.

Note: all existing data on the chosen disk is erased. The space after the boot partition is not used by the installer; it is left for you to decide when you create a storage pool in the web page.

Confirm

The installer shows a summary (which disk, how big the boot partition is). Once you confirm, it writes the disk, which takes a minute or two. When done it prompts Reboot now: remove the stick and press Enter to restart.

5. First boot

1. The machine boots from the hard disk: first the hypervisor, then the host system, which takes a minute or two.
2. On the first boot keelOS asks for an address by DHCP on all network ports. Once it has one, the address of the web page, for example https://192.168.1.10/, is shown on the host's screen (and serial port).
3. If there is no DHCP on the network, the screen asks for network settings: which port, whether it is a VLAN trunk port (if not, enter 0), the address (for example 192.168.1.10/24), the gateway and DNS. You can also redo this later on the host console with keel host net setup; see Network.

Next, open this address in a browser and do the first-time setup.

What is on the disk after installation

The host's settings live on the boot partition rather than in a storage pool: if the storage pool has a problem, the host can still boot and you can still log in to the web page.

Reinstalling or changing disks

• Reinstall: boot from the USB stick, choose fresh install, pick the same disk and type its name again. The storage pool zones left by the previous installation is wiped too.
• Upgrade only: no USB stick needed, just upgrade in the web page; see Upgrade and restart. Choosing upgrade when booting from a stick has the same effect.