Skip to main content
Version: v3.7.2

Network booting

Most modern hardware supports booting an operating system from the network. The technology behind this is called Preboot Execution Environment. PXE booting Kairos needs three files: a kernel, an initrd and a squashfs rootfs. These are not shipped as standalone release assets — you obtain them from a Kairos OCI image or ISO.

The recommended way to do this is with AuroraBoot, which pulls a Kairos OCI image, extracts the netboot artifacts and serves them over HTTP, with built-in ProxyDHCP so a target machine on the same network can boot directly. If you'd rather plug Kairos into an existing PXE/TFTP setup, AuroraBoot can also extract the same artifacts ahead of time from a Kairos ISO so you can serve them yourself.

Generic hardware-based netboot setup (PXE BIOS configuration, DHCP, etc.) is out of scope for this document.

Use AuroraBoot​

docker run --rm -ti --net host quay.io/kairos/auroraboot \
                    --set "container_image=quay.io/kairos/ubuntu:24.04-standard-amd64-generic-v3.7.2-k3sv1.35.0-k3s3"
                    # Optionally:
                    # --cloud-config ....

This will netboot the quay.io/kairos/ubuntu:24.04-standard-amd64-generic-v3.7.2-k3sv1.35.0-k3s3 image. AuroraBoot listens for PXE requests on the host network and serves the boot artifacts to any machine on that network configured to boot from the network. See the AuroraBoot documentation for more options (cloud-config, custom command line, disabling DHCP if you already have one, etc.).

If your hardware doesn't support PXE booting from firmware, you can use our generic iPXE ISO to bootstrap iPXE, which will then look for AuroraBoot (or any other ProxyDHCP server) on the network.

Use your own netboot server​

If you'd rather plug Kairos into an existing netboot setup (pixiecore, dnsmasq, a PXE/TFTP server you already run), AuroraBoot exposes two subcommands to support that workflow.

First, extract the kernel, initrd and squashfs from a Kairos ISO:

docker run --rm -v $PWD:/work quay.io/kairos/auroraboot \
    netboot /work/kairos.iso /work/out kairos

This writes kairos-kernel, kairos-initrd and kairos.squashfs into ./out. Feed those files into your existing server.

If you don't have a netboot server yet, AuroraBoot can be one. The start-pixie subcommand runs Pixiecore directly against the artifacts above:

docker run --rm --net host -v $PWD:/work quay.io/kairos/auroraboot \
    start-pixie /work/cloud-config.yaml /work/out/kairos.squashfs 0.0.0.0 8090 \
                /work/out/kairos-initrd /work/out/kairos-kernel

Pixiecore acts as a ProxyDHCP server, so it integrates with whatever DHCP server is already on the network — target machines configured to PXE-boot will pick up the kernel and initrd served on the address and port you passed.