Booting live Fedora CoreOS via iPXE

This guide shows how to boot a transient Fedora CoreOS (FCOS) system via iPXE. By default this will run FCOS in a stateless way, completely out of RAM. Separately, FCOS can also be installed to disk.

Prerequisite

Before booting FCOS, you must have an Ignition configuration file and host it somewhere (e.g. on a reachable web server). If you do not have one, see Producing an Ignition File.

Booting the live PXE image requires at least 2 GiB of RAM with the coreos.live.rootfs_url kernel argument, and 3 GiB otherwise.

PXE images

Before August 2020, the Fedora CoreOS PXE image included two components: a kernel image and an initramfs image. Beginning August 12, a third rootfs image was added. At present, the rootfs image is optional, and Fedora CoreOS displays a warning on login if the system was booted without it. After an initial migration period, the rootfs image will be mandatory and the live PXE system will not boot without it.

The migration timeline is:

  • August 12: rootfs image available in next, testing, and stable streams

  • August 25: rootfs image required in next stream

  • September 22: rootfs image required in testing stream

  • October 6: rootfs image required in stable stream

To boot with the rootfs artifact, make one of the following changes to your PXE config:

  • Specify only the initramfs file as the initrd, and pass an HTTP(S) URL for the rootfs using the coreos.live.rootfs_url= kernel argument.

  • Specify both initramfs and rootfs files as initrds in your PXE configuration. This can be done via multiple initrd directives, or using additional initrd= parameters as kernel arguments.

  • Concatenate the initramfs and rootfs files together, and specify the combined file as the initrd.

For more information on this change, see the tracker issue.

Setting up the Boot Script

An iPXE-capable machine needs to be provided with a relevant Boot Script to fetch and load FCOS artifacts.

The example below shows how to load those directly from Fedora infrastructure. For performance and reliability reasons it is recommended to mirror them on the local infrastructure, and then tweak the BASEURL as needed.

#!ipxe

set STREAM stable
set VERSION 32.20200726.3.1
set CONFIGURL https://example.com/config.ign

set BASEURL https://builds.coreos.fedoraproject.org/prod/streams/${STREAM}/builds/${VERSION}/x86_64

kernel ${BASEURL}/fedora-coreos-${VERSION}-live-kernel-x86_64 coreos.live.rootfs_url=${BASEURL}/fedora-coreos-${VERSION}-live-rootfs.x86_64.img ignition.firstboot ignition.platform.id=metal ignition.config.url=${CONFIGURL} systemd.unified_cgroup_hierarchy=0
initrd ${BASEURL}/fedora-coreos-${VERSION}-live-initramfs.x86_64.img

boot

Update process

Since the traditional FCOS upgrade process requires a disk, live-PXE systems are not able to auto-update in place. For this reason, Zincati is not running there.

Instead, it is recommended that images references in the PXE configuration are regularly refreshed. Once infrastructure and configurations are updated, the live-PXE instance simply needs to be rebooted in order to start running the new FCOS version.