Network booting

Install Kairos from network

Most hardware these days, supports booting an operating system from the network. The technology behind this is called Preboot Execution Environment. Kairos releases include artifacts to allow booting from the network. In general, the following files are needed:

  • The initrd image: It’s the system that loads first. It’s responsible to load the kernel.
  • The kernel: This is the kernel of the operating system that will boot.
  • The squashfs: The filesystem of the operating system that will boot.

Booting using these files can happen in two ways:

  • Either with direct support from the machine BIOS plus network configuration (DHCP server etc).
  • Software based network booting. This works with a special ISO, built with ipxe project. Kairos releases include pre-built ISOs for netbooting (named like *.ipxe.iso.ipxe).

Generic hardware based netbooting is out of scope for this document. Below we give instructions on how to use the Kairos release artifacts to netboot.

Boot with pre-built ISOs

The ipxe ISOs from the Kairos release artifacts, were built with a ipxe script that points directly to the kernel, initrd and squashfs artifacts of the same release on GitHub.


set url
set kernel kairos-alpine-opensuse-leap-v1.3.0-kernel
set initrd kairos-alpine-opensuse-leap-v1.3.0-initrd
set rootfs kairos-alpine-opensuse-leap-v1.3.0.squashfs

# Configure interface

# set config
# set cmdline extra.values=1
kernel ${url}/${kernel} initrd=${initrd} rd.neednet=1 ip=dhcp rd.cos.disable root=live:${url}/${rootfs} netboot nodepair.enable config_url=${config} console=tty1 console=ttyS0 ${cmdline}
initrd ${url}/${initrd}

Booting the ISO will automatically download and boot those artifacts. E.g. using qemu:


qemu-img create -f qcow2 disk.img 40g
qemu-system-x86_64 \
    -m 4096 \
    -smp cores=2 \
    -nographic \
    -drive if=virtio,media=disk,file=disk.img \
    -drive if=ide,media=cdrom,file=${1:-kairos.iso}

Notes on booting from network

Another way to boot with the release artifacts is using pixiecore. pixiecore acts as a server which offers net boot files over the network and it’s automatically discovered on a network where a DHCP server is running and is compatible with the pixiecore architecture.

Assuming the current directory has the kernel, initrd and squashfs artifacts, pixiecore server can be started with docker like this:


wget "${VERSION}/kairos-opensuse-${VERSION}-kernel"
wget "${VERSION}/kairos-opensuse-${VERSION}-initrd"
wget "${VERSION}/kairos-opensuse-${VERSION}.squashfs"

cat << EOF > config.yaml

hostname: "hostname.domain.tld"
- name: "kairos"
  passwd: "kairos"

# This will start the pixiecore server.
# Any machine that depends on DHCP to netboot will be send the specified files and the cmd boot line.
docker run \
  -d --name pixiecore --net=host -v $PWD:/files \
    boot /files/kairos-opensuse-${VERSION}-kernel /files/kairos-opensuse-${VERSION}-initrd --cmdline="rd.neednet=1 ip=dhcp rd.cos.disable root=live:{{ ID \"/files/kairos-opensuse-${VERSION}.squashfs\" }} netboot nodepair.enable config_url={{ ID \"/files/config.yaml\" }} console=tty1 console=ttyS0 console=tty0"

If your machine doesn’t support netbooting, you can use our generic image, which is built using an ipxe script from the pixiecore project. The ISO will wait for a DHCP proxy response from pixiecore.

If pixiecore is successfully reached, you should see an output similar to this in the pixiecore docker container:

$ docker logs pixiecore
[DHCP] Offering to boot 08:00:27:e5:22:8c
[DHCP] Offering to boot 08:00:27:e5:22:8c
[HTTP] Sending ipxe boot script to
[HTTP] Sent file "kernel" to
[HTTP] Sent file "initrd-0" to

Last modified January 25, 2023: :warning: add tumbleweed flavor (#710) (83a8989)