Provisioning Fedora CoreOS on QEMU

This guide shows how to provision new Fedora CoreOS (FCOS) instances on a bare QEMU hypervisor.

Prerequisites

Before provisioning an FCOS machine, you must have an Ignition configuration file containing your customizations. If you do not have one, see Producing an Ignition File.

Fedora CoreOS has a default core user that can be used to explore the OS. If you want to use it, finalize its configuration by providing e.g. an SSH key.

You also need to have access to a host machine with KVM support. The examples below use the qemu-kvm command-line tool, which must be separately installed beforehand.

If running with SELinux enabled, make sure your OS image and Ignition file are labeled as svirt_home_t, for example by placing them under ~/.local/share/libvirt/images/.

Booting a new VM on QEMU

This section shows how to boot a new VM on QEMU. Based on the platform, The Ignition file is passed to the VM, which sets the opt/com.coreos/config key in the QEMU firmware configuration device.

You can use -snapshot to make qemu-kvm allocate temporary storage for the VM, or qemu-img create to first create a layered qcow2.

Fetching the QCOW2 image

Fetch the latest image suitable for your target stream (or download and verify it from the web).

STREAM="stable"
coreos-installer download -s "${STREAM}" -p qemu -f qcow2.xz --decompress -C ~/.local/share/libvirt/images/

Setting up a new VM

Launch the new VM using qemu-kvm.

In snapshot mode, all changes that are performed live after boot are discarded once the machine is powered off. If you need to persist your changes, it is recommended to set up a dedicated persistent disk first.

Launching FCOS with QEMU (temporary storage)

IGNITION_CONFIG="/path/to/example.ign"
IMAGE="/path/to/image.qcow2"
# for x86/aarch64:
IGNITION_DEVICE_ARG="-fw_cfg name=opt/com.coreos/config,file=${IGNITION_CONFIG}"

# for s390x/ppc64le:
IGNITION_DEVICE_ARG="-drive file=${IGNITION_CONFIG},if=none,format=raw,readonly=on,id=ignition -device virtio-blk,serial=ignition,drive=ignition"

qemu-kvm -m 2048 -cpu host -nographic -snapshot \
  -drive if=virtio,file=${IMAGE} ${IGNITION_DEVICE_ARG} \
  -nic user,model=virtio,hostfwd=tcp::2222-:22

Launching FCOS with QEMU (persistent storage)

qemu-img create -f qcow2 -F qcow2 -b ${IMAGE} my-fcos-vm.qcow2
qemu-kvm -m 2048 -cpu host -nographic \
  -drive if=virtio,file=my-fcos-vm.qcow2 ${IGNITION_DEVICE_ARG} \
  -nic user,model=virtio,hostfwd=tcp::2222-:22

Exploring the OS

With QEMU usermode networking, the assigned IP address is not reachable from the host.

The examples above use hostfwd to selectively forward the SSH port on the guest machine to the local host (port 2222).

If you set up an SSH key for the default core user, you can SSH into the VM via the forwarded port:

ssh -p 2222 core@localhost

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