Docs · 1.0

What is keelOS

keelOS is a virtualization system for the one server in a home or small office. A NAS, a router, a Windows desktop and a few Linux servers each run in their own virtual machine, all on the same box. It is built on FreeBSD, bhyve and OpenZFS, and is managed from a web page, the command line or an HTTPS API.

The biggest difference from other virtualization systems: when the host system is upgraded or restarted, the virtual machines do not have to shut down. They pause for about 25 seconds and then carry on where they were, with their TCP connections intact.

How it works

A keelOS host has three layers:

The host system is a read-only image: the base system runs from memory and /usr is read from the boot disk. When the host restarts it does not have to go through the BIOS/UEFI power-on self-test again, so it takes about 50 seconds from the start of the restart until you can log in. In keelOS this kind of host restart without firmware is called a reload, and the interface uses the same word.

During a reload:

• Virtual machines pause for 24-26 seconds (measured on our development servers with ping, iperf and fio running inside the VMs). After they resume the disk data is intact and the clock is corrected.
• Devices passed through to a virtual machine (disk controllers, NVMe drives, graphics cards) keep working, because the IOMMU is managed by hyp and does not restart with the host.
• For each virtual machine you can choose whether it is suspended and resumed at a reload (the default) or shut down; see Virtual machines.

Only when hyp itself is upgraded does the whole machine need a firmware restart, and the virtual machines have to shut down. hyp is kept very small precisely so this happens as rarely as possible; see Upgrade and restart.

For the details behind this, read the article "Is a 99.99% SLA hard to reach for a home system?" (in Chinese, on keelos.dev).

What 1.0 can do

• Virtual machines: Windows 11 (virtual TPM 2.0 and Secure Boot, no need to bypass the checks), Windows 10 and Server, old systems such as Windows XP/2003/7 (using SeaBIOS and the drivers that ship with the OS), Linux, FreeBSD and other BSDs, and various router and NAS systems. See Virtual machines.
• Seeing the screen: a graphical console and a serial console in the web page; on a monitor plugged into the host itself, Ctrl-Alt-F2 to F12 switch between virtual machines; any RDP client can connect straight to a virtual machine's screen without installing anything inside the VM. See Console and remote desktop.
• Device passthrough: PCIe devices, discrete graphics cards, Intel integrated graphics, and SR-IOV VFs of network cards. Passed-through devices keep working across a reload. See Device passthrough.
• Storage: ZFS pools with mirror and raidz layouts, and you can have several pools. Virtual machine disks are presented as virtio-blk, NVMe or AHCI. See Storage.
• Network: virtual switches and VLANs; a physical port can be shared between the host and virtual machines. See Network.
• Upgrades: the boot partition has two slots, A and B. A new version is written to the slot that is not running, tried out, then confirmed, and you can switch back at any time. See Upgrade and restart.
• Snapshots and migration: a snapshot captures all of a virtual machine's disks, its configuration and its UEFI variables at once; a virtual machine can be cold-migrated to another keelOS host. See Snapshots, backup and migration.
• Management port: for machines without IPMI, keelRM gives you a management web page that is independent of the host, so you can see the screen and reset the machine even when the host is stuck or reloading. See The keelRM management port.
• Ways to manage: the web page (Chinese, English, Japanese), the keel command line, and the HTTPS API. Tokens can be limited in what they may do, and write operations go into an audit log. See Accounts, tokens and permissions, The keel command line and HTTP API.

keelNAS, keelAuth, keelMGR and the kRDPclient client also ship with 1.0; their documentation will be added later.

What 1.0 does not do

• AMD CPUs: 1.0 needs an Intel CPU; AMD support is still in development. See Hardware requirements.
• Live migration (moving a running virtual machine with its memory to another host) and PCI hot-plug: planned for after 1.0. What 1.0 can do is cold migration.
• Performance tuning: 1.0 is about stability; performance is the goal for 2.0.
• Multi-tenancy, SDN, automatic scheduling, shared storage: keelOS does not plan to do these. It is meant for the one machine of an individual or a small office.

A few common terms