Quickstart

From a USB stick to the first VM.

About fifteen minutes. keelOS takes a small part at the front of one disk; everything else is done in the browser.

1. 1

   Write the ISO to a USB stick

   Download keelos-VERSION.iso from the releases page (there is no public release yet). Write it to the stick with balenaEtcher, dd, or Rufus in DD image mode. Everything on the stick is erased.

   dd if=keelos-VERSION.iso of=/dev/sdX bs=4M   # sdX: the USB stick

2. 2

   Boot from the stick

   Open the firmware's boot menu (often F11 or F12) and pick the USB stick. keelOS starts from RAM and asks on the console:

     1) install
     2) try only: write nothing
   Choice [1]:

   2) try only writes nothing to any disk: good for a first look. 1) install continues below.

3. 3

   Pick a disk and the network

   The wizard lists every disk with what is on it now (partitions, file systems, ZFS pools), so a disk holding Windows or an old pool is easy to spot. An empty disk is offered first; a disk with data on it must be confirmed by typing its name.

   Disk to install to [ada2]: ada0
     ada0 holds GPT: ms-basic-data 1 GiB (msdosfs "WINDOWS").
     Everything on ada0 will be erased.
     Type ada0 to erase it (empty: pick another disk): ada0

   Then pick the network port (the one with a link is offered) and DHCP or a fixed address. Installing takes a minute or two. Take out the stick and let the machine restart.

4. 4

   Open the web interface and set the password

   The console shows the address above the login prompt, for example https://192.168.1.10/. Open it in a browser; the certificate is the host's own, so the browser asks you to accept it once.

   The first page is Set the admin password (at least 8 characters). It is root's password too, for the console and ssh. Whoever opens the page first sets it, so do this straight after installing. Forgotten it? Run keel admin reset on the host's own console and set a new one.

5. 5

   Make the storage pool

   Storage → Make the pool zones. Tick the free space left on the boot disk and/or other disks. One disk gives a single disk, two a mirror, three or more raidz, four or more raidz2. Disks with data on them are confirmed by name.

   Optional, on the same page: a copy of the boot partition on a second disk, so the host still boots if the first one dies.

6. 6

   Set up the network

   Network → Physical ports → Probe. keelOS listens on each port and finds the subnets, VLANs, routers and DHCP servers on it. Under Found on the ports, take the networks it suggests (or make one by hand). VMs are connected to a network, not to a port.

7. 7

   Add an installer ISO

   Storage → ISO images → Upload ISO from your computer, or give an address and let the host download it itself.

8. 8

   Create the first VM

   Virtual machines → New virtual machine. Pick a template (Windows 11, Linux, FreeBSD, …): it carries the firmware, disk and network models and, for Windows 11, the TPM. Fill in name, CPUs, memory, disk, the ISO and the network, tick start it now and Create.

   Open Screen (VNC) in the browser and install the system as on a real machine. Any RDP client can also connect to the VM's screen, with nothing installed in the guest.

Next

• Restart the host (shutdown -r now on it) and watch the VM pause and carry on. That is the point of keelOS.
• Upgrade: System → Upgrade, give it the new keelOS ISO. It goes into the other slot of the boot partition and the host restarts into it while the VMs pause. If the new version does not come up, the next start goes back to the old one. Settings are kept.
• Give a disk controller or NVMe drive to a NAS VM, or SR-IOV VFs of the network card to a router: see the passthrough article (Chinese).