libvirt/docs/kbase/secureboot.rst

Secure Boot

Quick configuration

If you have libvirt 8.6.0 or newer, when creating a new VM you can ask for Secure Boot to be enabled with

<os firmware='efi'>
  <firmware>
    <feature enabled='yes' name='enrolled-keys'/>
  </firmware>
</os>

and for it to be disabled with

<os firmware='efi'>
  <firmware>
    <feature enabled='no' name='enrolled-keys'/>
  </firmware>
</os>

These configuration will cause unsigned guest operating systems to be rejected and allowed respectively.

Older libvirt versions

If your libvirt version is older than 8.6.0 but newer than 7.2.0, then enabling Secure Boot requires a slightly more verbose XML snippet:

<os firmware='efi'>
  <loader secure='yes'/>
  <firmware>
    <feature enabled='yes' name='enrolled-keys'/>
  </firmware>
</os>

Versions older than 7.2.0 require manually providing all information about the firmware and are not covered here. Please refer to the relevant documentation for details.

Changing an existing VM

Once the VM has been created, updating the XML configuration as described above is not enough to change the Secure Boot status: the NVRAM file associated with the VM has to be regenerated from its template as well.

In order to do that, update the XML and then start the VM with

$ virsh start $vm --reset-nvram

This option is only available starting with libvirt 8.1.0, so if your version of libvirt is older than that you will have to delete the NVRAM file manually before starting the VM.

Most guest operating systems will be able to cope with the NVRAM file being reinitialized, but in some cases the VM will be unable to boot after the change.

Additional information

There are two parts to enabling Secure Boot: the firmware supporting the feature, and it being active.

Most host operating systems ship a build of EDKII (the open source EFI implementation used for QEMU VMs) that supports the Secure Boot feature, but simply using such a build will not result in unsigned guest operating systems being rejected: for that to happen, keys that can be used to validate the operating system signature need to be provided as well.

Asking for the enrolled-keys firmware feature to be enabled will cause libvirt to initialize the NVRAM file associated with the VM from a template that contains a suitable set of keys. These keys being present will cause the firmware to enforce the Secure Boot signing requirements.

The opposite configuration, where the feature is explicitly disabled, will result in no keys being present in the NVRAM file. Unable to verify signatures, the firmware will allow even unsigned operating systems to run.