Over the last weeks I've been working on adding a bunch of helper code for edk2 firmware testing to the virt firmware project. Partly this has been taked from test cases, partly this has been written new from scratch. The idea is to have useful helper code available as python module to simplify writing test cases.

There are also command line tools to manage and use cloud images. They showcase how the python modules can be used, but they are also useful on their own.

This is available in the 26.8 version just released, parts of the code are also in the older 26.7.x versions. If you want check this out I'd recommend the latest and greatest of course. Enough introduction, lets dive in.

virt-cloud-fetch

This is a tool to download cloud images. Supports Fedora, CentOS Stream and RHEL. Just specify the version you want on the command line, like this: 

virt-cloud-fetch --fedora 44

The tool can also cleanup stale images. Useful for CentOS Stream where the images are updated every few days: 

virt-cloud-fetch --centos 10 --cleanup

To fetch RHEL images you might have to set the REDHAT_MIRROR environment variable to point the tool to the download server it should use.

By default the images are stored in $HOME/.cache/virt-distro. This can be overridden using the VIRT_DISTRO_IMGDIR environment variable or using the --imgdir command line switch.

virt-cloud-boot

The tool to boot cloud images. In the simplest case just specify the version and be done with it: 

virt-cloud-boot --fedora 44

The tool will create a temporary writable qcow2 image with the cloud image as backing storage, so the cloud image will never be updated and on every start your guest will boot with a pristine cloud image.

The tool will also generate a cloud init iso image to setup the guest, in the simplest case just set the hostname and add a user to allow login on the serial console. Command line switches are available to pick username + password, to install packages and more.

The tool will use the json files in /usr/share/qemu/firmware to automatically select and configure the firmware images. Command line switches are available to ask for specific firmware properties such as secure boot being enabled or confidential computing being used. Booting a confidential guest is as simple as this ... 

virt-cloud-boot --fedora 44 --snp

... which will both pick a SNP-capable firmware and turn on SNP mode in qemu. You might want add --rpm snpguest to get the guest tooling installed automatically.

There are also options for hardware setup. Pick memory and vcpus, setup storage. The --help switch is there to bring the full list, a man page is available too.

python modules overview

The tools code for the most part just handle the command line parsing and processing. Most of the actual functionality is in python modules and available for reuse. Here is a list:

virt.qemutest.autoconf
Helper functions for automatic configuration. Find qemu binary, select firmware config, pick sensible defaults for machine type and cpu.
virt.qemutest.cloudinit
CloudInitISO class to generate cloud init iso images.
virt.qemutest.distro.*
Python classes to download distro artifacts. This is not limited to cloud images, support for fetching installer iso images is available too.
virt.qemutest.firmware
QemuFirmware class to parse and manage firmware json files. Query firmware properties, generate qemu command line snippets and more.
virt.qemutest.qemucfg
QemuCfg class. Helps generating qemu command lines.

Next item on my TODO list: Update edk2-tests to use (more of) the new modules. But that will be covered in another blog article.