Live ISO and PXE image reference

For an introduction to running Fedora CoreOS directly from RAM, see the provisioning guide.

Passing the PXE rootfs to a machine

The Fedora CoreOS PXE image includes three components: a kernel, an initramfs, and a rootfs. All three are mandatory and the live PXE environment will not boot without them.

There are multiple ways to pass the rootfs to a machine:

  • Specify only the initramfs file as the initrd in your PXE configuration, and pass an HTTP(S) or TFTP URL for the rootfs using the coreos.live.rootfs_url= kernel argument. This method requires 2 GiB of RAM, and is the recommended option unless you have special requirements.

  • 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. This method is slower than the first method and requires 4 GiB of RAM.

  • Concatenate the initramfs and rootfs files together, and specify the combined file as the initrd. This method is slower and requires 4 GiB of RAM.

Passing an Ignition config to a live PXE system

When booting Fedora CoreOS via live PXE, the kernel command line must include the arguments ignition.firstboot ignition.platform.id=metal to run Ignition. If running in a virtual machine, replace metal with the platform ID for your platform, such as qemu or vmware.

There are several ways to pass an Ignition config when booting Fedora CoreOS via PXE:

  • Add ignition.config.url=<config-url> to the kernel command line. Supported URL schemes include http, https, tftp, s3, and gs.

  • If running virtualized, pass the Ignition config via the hypervisor, exactly as you would when booting from a disk image. Ensure the ignition.platform.id kernel argument is set to the platform ID for your platform.

  • Generate a customized version of the initramfs containing your Ignition config using coreos-installer pxe customize. For example, run:

    coreos-installer pxe customize --live-ignition config.ign -o custom-initramfs.img \
    fedora-coreos-41.20241027.3.0-live-initramfs.x86_64.img

  • If you prefer to keep the Ignition config separate from the Fedora CoreOS initramfs image, generate a separate initrd with the low-level coreos-installer pxe ignition wrap command and pass it as an additional initrd. For example, run:

    coreos-installer pxe ignition wrap -i config.ign -o ignition.img

    and then use a PXELINUX APPEND line similar to:

    APPEND initrd=fedora-coreos-41.20241027.3.0-live-initramfs.x86_64.img,fedora-coreos-41.20241027.3.0-live-rootfs.x86_64.img,ignition.img ignition.firstboot ignition.platform.id=metal

Passing network configuration to a live ISO or PXE system

On Fedora CoreOS, networking is typically configured via NetworkManager keyfiles. If your network requires special configuration such as static IP addresses, and your Ignition config fetches resources from the network, you cannot simply include those keyfiles in your Ignition config, since that would create a circular dependency.

Instead, you can use coreos-installer iso customize or coreos-installer pxe customize with the --network-keyfile option to create a customized ISO image or PXE initramfs image which applies your network settings before running Ignition. For example:

coreos-installer iso customize --network-keyfile custom.nmconnection -o custom.iso \
    fedora-coreos-41.20241027.3.0-live.x86_64.iso

If you’re PXE booting and want to keep your network settings separate from the Fedora CoreOS initramfs image, you can also use the lower-level coreos-installer pxe network wrap command to create a separate initrd image, and pass that as an additional initrd. For example, run:

coreos-installer pxe network wrap -k custom.nmconnection -o network.img

and then use a PXELINUX APPEND line similar to:

APPEND initrd=fedora-coreos-41.20241027.3.0-live-initramfs.x86_64.img,fedora-coreos-41.20241027.3.0-live-rootfs.x86_64.img,network.img ignition.firstboot ignition.platform.id=metal

Passing kernel arguments to a live ISO system

If you want to modify the default kernel arguments of a live ISO system, you can use the --live-karg-{append,replace,delete} options to coreos-installer iso customize. For example, if you want to enable simultaneous multithreading (SMT) even on CPUs where that is insecure, you can run:

coreos-installer iso customize --live-karg-delete mitigations=auto,nosmt -o custom.iso \
    fedora-coreos-41.20241027.3.0-live.x86_64.iso

Extracting PXE artifacts from a live ISO image

If you want the Fedora CoreOS PXE artifacts and already have an ISO image, you can extract the PXE artifacts from it:

podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \
    quay.io/coreos/coreos-installer:release iso extract pxe \
    fedora-coreos-41.20241027.3.0-live.x86_64.iso

The command will print the paths to the artifacts it extracted.

Using the minimal ISO image

In some cases, you may want to boot the Fedora CoreOS ISO image on a machine equipped with Lights-Out Management (LOM) hardware. You can upload the ISO to the LOM controller as a virtual CD image, but the ISO may be larger than the LOM controller supports.

To avoid this problem, you can convert the ISO image to a smaller minimal ISO image without the rootfs. Similar to the PXE image, the minimal ISO must fetch the rootfs from the network during boot.

Suppose you plan to host the rootfs image at https://example.com/fedora-coreos-41.20241027.3.0-live-rootfs.x86_64.img. This command will extract a minimal ISO image and a rootfs from an ISO image, embedding a coreos.live.rootfs_url kernel argument with the correct URL:

podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \
    quay.io/coreos/coreos-installer:release iso extract minimal-iso \
    --output-rootfs fedora-coreos-41.20241027.3.0-live-rootfs.x86_64.img \
    --rootfs-url https://example.com/fedora-coreos-41.20241027.3.0-live-rootfs.x86_64.img \
    fedora-coreos-41.20241027.3.0-live.x86_64.iso \
    fedora-coreos-41.20241027.3.0-live-minimal.x86_64.iso

Want to help? Learn how to contribute to Fedora Docs ›