From KVM
Revision as of 11:10, 15 June 2013 by Lersek (Talk | contribs) (Reword build instructions, recommend to check the SRPMs)


OVMF "is a project to enable UEFI support for Virtual Machines". This page tries to give yet another mini-howto about playing with OVMF boot firmware in qemu-kvm virtual machines plus libvirt, deferring heavily to the TianoCore upstream wiki. Do mercilessly edit any inaccuracies or wrong statements.

This page is written as of edk2 svn rev 14423 (virtio-blk, virtio-scsi and virtio-net are supported, and several guests can be booted with, and recognize secure boot). For using OVMF directly with the qemu command line, refer to the README; this page tries to detail OVMF usage under (RHEL-6.4) libvirt.

The recommended way for testing OVMF is installing Gerd Hoffman's RPM packages from his repo at, using yum. (The package to install is edk2.git-ovmf-x64; yum will pull in several dependencies from the repo.) The firmware images are located in the /usr/share/edk2.git/ovmf-x64 directory. OVMF-pure-efi.fd is a "pure UEFI" image, while OVMF-with-csm.fd includes the Compatibility Support Module (CSM) build of SeaBIOS. bios.bin is a symlink to the latter.

Building from source

Clone either the main SVN repository (git svn recommended) or one of the git mirrors listed in the TianoCore wiki.

Frequent rebuilds

For developers it is recommended to create a branch called base_config or something similar off the master branch (in the git svn or plain git clone), capture the config steps described here in commits (including setting up a reasonable .gitignore file), and keep rebasing base_config after git svn rebase --use-log-author / git pull commands. Fork/rebase your own development branches off/to base_config.

The very first time you build the tree, and after git clean -fdx commands, you must (re)build BaseTools with make -C "$EDK_TOOLS_PATH". (You're going to have that variable set in your environment after sourcing in the root project dir; see the TianoCore Wiki again.)

One-off builds

OvmfPkg/ takes care of BaseTools, configuration (according to command line options) and the main build. One potentially useful option is -n THREADNUMBER, which enables parallel make.

-D FLAG options control optional build features/aspects. Consult OvmfPkg/, OvmfPkg/README, the OvmfPkg/*.dsc and OvmfPkg/*.fdf files, and Gerd's SRPMs.

Making guests use it

So now you have either downloaded a prebuilt binary, or installed the noarch RPM in the host, or built OVMF.fd yourself. This "Flash Device" file is passed to qemu-kvm with the -bios option (with full pathname), which is accessible in the libvirt domain XML as the /domain/os/loader element.

Neither virt-manager nor virt-install seem to make this option readily configurable at guest installation time in RHEL-6.3. The following list of commands is one workaround. The EMULATOR bit is elaborated upon under #qemu debug port.

# "configuration"

# create a domain XML template for guest installation:
# - 4 VCPUs, 4G RAM
# - virtio target disk, 25 GB in size
# - first IDE CD-ROM has install disk
# - second IDE CD-ROM has virtio driver disk
#   (should only be necessary for proprietary guests without built-in drivers)
virt-install                                                                 \
    --connect=qemu:///system                                                 \
    --name=$NAME                                                             \
    --ram=4096                                                               \
    --arch=x86_64                                                            \
    --machine=rhel6.3.0                                                      \
    --vcpus=4                                                                \
    --boot=cdrom,hd                                                          \
    --disk=path=$TARGET_DISK,size=25,bus=virtio,format=qcow2                 \
    --disk=path=$DRIVER_ISO,device=cdrom,bus=ide,perms=ro,format=raw         \
    --disk=path=$INSTALL_ISO,device=cdrom,bus=ide,perms=ro,format=raw        \
    --print-step=1                                                           \
| xmlstarlet ed -u /domain/devices/emulator                     -v $EMULATOR \
                -s /domain/os                 -t elem -n loader -v $LOADER   \

# Import the template to libvirt
virsh define template.xml

# Now customize the guest further with "virsh edit" or inside virt-manager,
# then start the installation.

For a virtio-scsi disk, apply the following changes:

  1. in the TARGET_DISK specification, replace bus=virtio with bus=scsi,
  2. append the following options to the xmlstarlet command line:
                    -s /domain/devices            -t elem -n controller -v ''          \
                    -s /domain/devices/controller -t attr -n type       -v scsi        \
                    -s /domain/devices/controller -t attr -n model      -v virtio-scsi \

Saving OVMF debug messages

Debug log verbosity is controlled at build time. See the gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel bitmask in OvmfPkg/OvmfPkgX64.dsc. The individual bits (DEBUG_* macros) are explained in MdePkg/Include/Library/DebugLib.h.

serial console

Debug messages are written to the qemu debug port per default (see below), but they can be redirected to the (virtual) serial console with the -D DEBUG_ON_SERIAL_PORT option at build time. In this case however the serial console will intermix framework debug messages with the TUI of the (U)EFI shell and other UEFI applications.

qemu debug port

This is where the debug messages are written by default, but capturing them on the host requires the -debugcon DEV -global isa-debugcon.iobase=0x402 qemu-kvm command line switches. These can be set on a guest-by-guest basis in the libvirt VM config XML files, using qemu:arg.

Alternatively, one might contemplate a qemu-kvm wrapper script like the following:

set -e -C -u

for ARG in "$@"; do
  if [ x"$ARG" = x-name ]; then
  elif [ $NAME -ne 0 ]; then
    exec /usr/libexec/qemu-kvm "$@" \
        -debugcon file:"$FNAME" -global isa-debugcon.iobase=0x402
exec /usr/libexec/qemu-kvm "$@"

The full path to the wrapper script is specified in the /domain/devices/emulator element of the libvirt guest XML.

The script is adapted to the fact that libvirt invokes the emulator in two forms. XML validation after virsh edit seems to invoke the emulator for verification purposes only, without the -name option. In this case no debug file should be created / rewritten. When libvirt starts the guest, the -name option is present, and the script constructs the logfile's name from the corresponding option-argument.

On an SELinux enabled system, the script's context should be set to that of the wrapped emulator, qemu-kvm. See chcon --reference.

Furthermore, on an SELinux enabled system, a new instance of the same guest will be seclabelled differently from the previous instance, and will fail to overwrite the debug log produced by the previous instance. This could be worked around perhaps by reconfiguring libvirt's labelling practices for the guest, or changing the SELinux profile, or (horribile dictu) flipping SELinux to permissive. Removing the debug file manually before starting the next instance of the guest is simplest.

(Needless to say, never do any of this in production.)

Tested guest OS'en

Apparently working nicely

  • Fedora 18 Alpha (XFCE edition). Secure boot tested as well.
  • RHEL-6.3. (Its grub does not support booting from a virtio-blk disk. See #Making guests use it how to specify a virtio-scsi boot disk.)
  • Windows 8 Consumer Preview Build 8250. Secure boot tested as well. The fix for qemu-kvm RHBZ#854304 may be necessary to run this guest. (Upstream qemu contains the fix of course.)
  • Reportedly, Windows Server 2012.

Windows Server 2008 R2 SP1

This guest does not work correctly. Its UEFI installer is composed of several programs, some being UEFI applications, and the last layer being the Windows Pre-Installation Environment, running on the Windows 2008 R2 kernel.

The UEFI applications before the last layer correctly use the OVMF GOP (graphics output protocol), which drives the emulated Cirrus 5446 video card. Unfortunately, the last layer (WinPE) has a hard dependency on VGA BIOS interrupt 0x10, which is not provided by any OVMF CSM (compatibility support module) as of now.

This hard dependency is a Windows 2008 R2 bug; the WinPE layer should (actively) inherit the linear framebuffer characteristics from the GOP (UEFI boot phase), and use that until the kernel-level graphics drivers are loaded.

One (quite shabby) workaround for the time being is automated installation of this OS on top of OVMF, and then connecting to it with rdesktop.

During most of the installation (ie. in the WinPE phase), nothing can be seen in the VNC window. The VM reboots several times, at which points cdboot.efi shortly displays a (visible) message, "press a key to continue booting from the installation CD". No key should be pressed, as expected, but after the timeout, cdboot.efi tends to crash, violating an edk2 framework ASSERT and falling into an infinite loop (watch the debug log).

If this happens, force off the VM, restart it, enter the OVMF setup utility, and manually set the on-hdd boot loader. The installation should resume then.

For the remote desktop connection, the IP address of the running guest can be fetched by searching /var/lib/libvirt/dnsmasq/default.leases for the guest's MAC address (which is present in its libvirt XML file).

An example AutoUnattend.xml file, and a corresponding guest XML template (to be used with virsh define) are inserted below as a base-64 encoded, xz-compressed tarball. (Unfortunately, File Upload refuses xml and xml.gz files.) The install ISO that was augmented with the AutoUnattend.xml file is named en_windows_server_2008_r2_with_sp1_x64_dvd_617601.iso, its SHA1 is D3FD7BF85EE1D5BDD72DE5B2C69A7B470733CD0A.

Note: the first ProductKey element in the XML is a default key from \SOURCES\PRODUCT.INI. It does not participate in product activation, it contributes to product selection at installation time.

begin-base64 600 example.tar.xz

Confirmation of secure boot in Fedora 18

(This is a write-up of an earlier test.)

  1. I rebuilt OVMF with secure boot support.
  2. I downloaded the x86_64 binary RPM for pesign-0.10-5.fc18 and extracted the /etc/pki/pesign directory to $HOME/tmp/f18-keys.
  3. I extracted two certificates in DER format, standing in $HOME/tmp:
    certutil -L -d f18-keys -n 'Red Hat Test Certificate' -r \
    certutil -L -d f18-keys -n 'Red Hat Test CA' -r \
  4. I created a 64MB zero file,
    • set up /dev/loop1 on it,
    • created an MBR partition table with one 0x0c partition (cfdisk),
    • (maybe ran kpartx -a /dev/loop1,)
    • formatted /dev/mapper/loop1p1 as FAT32 with mkdosfs,
    • mounted it, created a directory called Red Hat Secure Boot Keys,
    • copied the output files from the previous step there.
    • NOTE: libguestfs / guestfish is a much better way to do the same.
  5. I attached the above image file as second disk to my preexistent guest while it was shut down.
  6. I started the guest.
    • As soon as the TianoCore splash screen showed, I entered the setup menu and selected Device Manager | Secure Boot Options,
    • enrolled RedHatTestCA.der as PK.
    • enrolled RedHatTestCertificate.der as one KEK and one DB entry,
    • made sure shim.efi from the first disk was the first boot option in Boot Maintenance Manager | Boot Options,
    • allowed the boot to continue.
  7. shim.efi printed Binary is whitelisted. grub2 printed secure boot forbids insmod four times. The F18 XFCE GUI started. The guest dmesg contains
    [    0.000000] Secure boot enabled
  8. OVMF secure boot configuration (enrolled keys etc) don't persist across guest shutdown (maybe not even across in-guest reboot); OVMF reverts to non-secure boot. Copying the certificates to the F18 boot partition didn't change this. What's more, when OVMF is built with Secure Boot support, even the boot order saved from last time is forgotten and default options are regenerated (even with no keys enrolled).

Confirmation of secure boot in Windows 8 Consumer Preview Build 8250

(This is also a write-up of an earlier test.)

Basically re-executed #Confirmation of secure boot in Fedora 18, with the following changes: