In addition to documenting the new element, rework the documentation to encourage the use of firmware autoselection and discourage configuring the firmware manually; moreover, rename the "BIOS bootloader" section to the far more accurate "guest firmware". Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/formatcaps.rst | 2 +- docs/formatdomain.rst | 47 ++++++++++++++++------ docs/formatdomaincaps.rst | 85 ++++++++++++++++++++++++--------------- docs/kbase/secureboot.rst | 46 +++++++++++++-------- 4 files changed, 118 insertions(+), 62 deletions(-) diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst index fa8ab5197f..9458e1289a 100644 --- a/docs/formatcaps.rst +++ b/docs/formatcaps.rst @@ -172,7 +172,7 @@ The ``<guest/>`` element will typically wrap up the following elements: Emulator (device model) path, for use in `emulator <formatdomain.html#devices>`__ element of domain XML. ``loader`` - Loader path, for use in `loader <formatdomain.html#bios-bootloader>`__ + Loader path, for use in `loader <formatdomain.html#guest-firmware>`__ element of domain XML. ``machine`` Machine type, for use in diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 82788c15a2..7871613017 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -103,12 +103,16 @@ Operating system booting There are a number of different ways to boot virtual machines each with their own pros and cons. +Guest firmware +~~~~~~~~~~~~~~ -BIOS bootloader -~~~~~~~~~~~~~~~ +.. container:: + :name: bios-bootloader + + .. this container only exists to keep old links working -Booting via the BIOS is available for hypervisors supporting full -virtualization. In this case the BIOS has a boot order priority (floppy, +Booting via a guest firmware is available for hypervisors supporting full +virtualization. In this case the firmware has a boot order priority (floppy, harddisk, cdrom, network) determining where to obtain/find the boot image. :: @@ -192,9 +196,9 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. ``firmware`` The ``firmware`` attribute allows management applications to automatically - fill ``<loader/>`` and ``<nvram/>`` elements and possibly enable some - features required by selected firmware. Accepted values are ``bios`` and - ``efi``. + fill ``<loader/>`` and ``<nvram/>`` or ``<varstore/>`` elements and possibly + enable some features required by selected firmware. Accepted values are + ``bios`` and ``efi``. The selection process scans for files describing installed firmware images in specified location and uses the most specific one which fulfills domain requirements. The locations in order of preference (from generic to most @@ -307,6 +311,23 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. It is not valid to provide this element if the loader is marked as stateless. +``varstore`` + This works much the same way as the ``<nvram/>`` element described above, + except that variable storage is handled by the ``uefi-vars`` QEMU device + instead of being backed by a pflash device. :since:`Since 12.1.0 (QEMU only)` + + The ``path`` attribute contains the path of the domain-specific file where + variables are stored, while the ``template`` attribute points to a template + that the domain-specific file can be (re)generated from. Assuming that the + necessary JSON firmware descriptor files are present, both attributes will + be filled in automatically by libvirt. + + Using ``<varstore/>`` instead of ``<nvram/>`` is particularly useful on + non-x86 architectures such as aarch64, where it represent the only way to + get Secure Boot working. It can be used on x86 too, and doing so will make + it possible to keep UEFI authenticated variables safe from tampering without + requiring the use of SMM emulation. + ``boot`` The ``dev`` attribute takes one of the values "fd", "hd", "cdrom" or "network" and is used to specify the next boot device to consider. The @@ -411,10 +432,10 @@ and full virtualized guests. ``type`` This element has the same semantics as described earlier in the - `BIOS bootloader`_ section. + `guest firmware`_ section. ``loader`` This element has the same semantics as described earlier in the - `BIOS bootloader`_ section. + `guest firmware`_ section. ``kernel`` The contents of this element specify the fully-qualified path to the kernel image in the host OS. @@ -3752,7 +3773,7 @@ paravirtualized driver is specified via the ``disk`` element. attribute is an 8 character string which can be queried by guests on S390 via sclp or diag 308. Linux guests on S390 can use ``loadparm`` to select a boot entry. :since:`Since 3.5.0` The per-device ``boot`` elements cannot be used - together with general boot elements in `BIOS bootloader`_ + together with general boot elements in `guest firmware`_ section. :since:`Since 0.8.8` ``encryption`` since:`Since 3.9.0` the ``encryption`` element is preferred @@ -4917,7 +4938,7 @@ or: Specifies that the device is bootable. The ``order`` attribute determines the order in which devices will be tried during boot sequence. The per-device ``boot`` elements cannot be used together with general boot elements in - `BIOS bootloader`_ section. :since:`Since 0.8.8` for PCI + `guest firmware`_ section. :since:`Since 0.8.8` for PCI devices, :since:`Since 1.0.1` for USB devices. ``rom`` The ``rom`` element is used to change how a PCI device's ROM is presented to @@ -5144,7 +5165,7 @@ USB device redirection through a character device is supported Specifies that the device is bootable. The ``order`` attribute determines the order in which devices will be tried during boot sequence. The per-device ``boot`` elements cannot be used together with general boot elements in - `BIOS bootloader`_ section. ( :since:`Since 1.0.1` ) + `guest firmware`_ section. ( :since:`Since 1.0.1` ) ``redirfilter`` The\ ``redirfilter``\ element is used for creating the filter rule to filter out certain devices from redirection. It uses sub-element ``<usbdev>`` to @@ -6400,7 +6421,7 @@ Specifying boot order For hypervisors which support this, you can set a specific NIC to be used for network boot. The ``order`` attribute determines the order in which devices will be tried during boot sequence. The per-device ``boot`` elements cannot be used -together with general boot elements in `BIOS bootloader`_ +together with general boot elements in `guest firmware`_ section. :since:`Since 0.8.8` Interface ROM BIOS configuration diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst index cca827923c..5a1d3f2670 100644 --- a/docs/formatdomaincaps.rst +++ b/docs/formatdomaincaps.rst @@ -72,11 +72,11 @@ The root element that emulator capability XML document starts with has name Describes the `virtualization type <formatdomain.html#element-and-attribute-overview>`__ (or so called domain type). ``machine`` - The domain's `machine type <formatdomain.html#bios-bootloader>`__. Since not + The domain's `machine type <formatdomain.html#guest-firmware>`__. Since not every hypervisor has a sense of machine types this element might be omitted in such drivers. ``arch`` - The domain's `architecture <formatdomain.html#bios-bootloader>`__. + The domain's `architecture <formatdomain.html#guest-firmware>`__. CPU Allocation ~~~~~~~~~~~~~~ @@ -95,12 +95,17 @@ capabilities, e.g. virtual CPUs: ``vcpu`` The maximum number of supported virtual CPUs -BIOS bootloader -~~~~~~~~~~~~~~~ +Guest firmware +~~~~~~~~~~~~~~ + +.. container:: + :name: bios-bootloader + + .. this container only exists to keep old links working -Sometimes users might want to tweak some BIOS knobs or use UEFI. For cases like -that, `os <formatdomain.html#bios-bootloader>`__ element exposes what values can -be passed to its children. +Exposes information about supported +`guest firmware <formatdomain.html#guest-firmware>`__ configurations for +domains. :: @@ -136,19 +141,22 @@ be passed to its children. <value>no</value> </enum> </loader> + <varstore supported='yes'/> </os> ... <domainCapabilities> -The ``firmware`` enum corresponds to the ``firmware`` attribute of the ``os`` -element in the domain XML. The presence of this enum means libvirt is capable of -the so-called firmware auto-selection feature. And the listed firmware values -represent the accepted input in the domain XML. Note that the ``firmware`` enum -reports only those values for which a firmware "descriptor file" exists on the -host. Firmware descriptor file is a small JSON document that describes details -about a given BIOS or UEFI binary on the host, e.g. the firmware binary path, -its architecture, supported machine types, NVRAM template, etc. This ensures -that the reported values won't cause a failure on guest boot. +The presence of the ``firmware`` enum means that libvirt can perform firmware +autoselection, and each of the values is guaranteed to be usable. In the +domain XML, firmware autoselection is enabled as follows: + +:: + + <os firmware='efi'> + ... + +Autoselection is the recommended mechanism for configuring the guest firmware. +Providing paths and other information manually is discouraged. The ``<firmwareFeatures/>`` element :since:`(since 12.1.0)` contains one enum for each of the features that can be used to fine-tune the firmware @@ -191,27 +199,40 @@ such as: would not work, since ``no`` is not one of the valid values advertised by the ``secureBoot`` enum. -For the ``loader`` element, the following can occur: +The information contained in the ``<loader/>`` element is not relevant when +using firmware autoselection, which is the recommended approach to guest +firmware configuration, and as such can largely be ignored. Its subelements +are the following: ``value`` - List of known firmware binary paths. Currently this is used only to advertise - the known location of OVMF binaries for QEMU. OVMF binaries will only be - listed if they actually exist on host. + One element for each known firmware binary present on the system. + + Note that a binary being present here indicates that the file exists and it + is compatible with the architecture/machine type, but does not provide any + insight into which mechanism (see ``type`` below) should be used to load it. ``type`` - Whether the boot loader is a typical BIOS (``rom``) or a UEFI firmware - (``pflash``). Each ``value`` sub-element under the ``type`` enum represents a - possible value for the ``type`` attribute for the <loader/> element in the - domain XML. E.g. the presence of ``pfalsh`` under the ``type`` enum means - that a domain XML can use UEFI firmware via: <loader/> type="pflash" - ...>/path/to/the/firmware/binary/</loader>. + Whether firmware can be loaded using a ``pflash`` device (UEFI only) or as + a ``rom`` (either UEFI or BIOS). ``readonly`` - Options for the ``readonly`` attribute of the <loader/> element in the domain - XML. + Supported values for the ``readonly`` attribute of the ``<loader/>`` element + in the domain XML. ``secure`` - Options for the ``secure`` attribute of the <loader/> element in the domain - XML. Note that the value ``yes`` is listed only if libvirt detects a firmware - descriptor file that has path to an OVMF binary that supports Secure boot, - and lists its architecture and supported machine type. + Supported values for the ``secure`` attribute of the ``<loader/>`` element + in the domain XML. + + Note that the value ``yes`` is listed if libvirt detects a firmware + descriptor file that points to a firmware binary that implements Secure + Boot and is compatible with the architecture/machine type, but the UEFI + variable store template associated with it might not have the usual set of + Secure Boot certificates enrolled. To figure out whether it's actually + possible to enforce Secure Boot, look at the ``enrolledKeys`` enum inside + the ``<firmwareFeatures/>`` element instead. + +The ``<varstore/>`` element :since:`(since 12.1.0)` indicates whether UEFI +variable storage backed by the ``uefi-vars`` QEMU device can be used as an +alternative to pflash-based NVRAM storage. This is the only type of variable +storage compatible with Secure Boot on non-x86 architectures, but it can be +used on x86 too. CPU configuration ~~~~~~~~~~~~~~~~~ diff --git a/docs/kbase/secureboot.rst b/docs/kbase/secureboot.rst index 6c22b08d22..0c8143bfba 100644 --- a/docs/kbase/secureboot.rst +++ b/docs/kbase/secureboot.rst @@ -74,8 +74,8 @@ Changing an existing VM When a VM is defined, libvirt will pick the firmware that best satisfies the provided criteria and record this information for use -on subsequent boots. The resulting XML configuration will look like -this: +on subsequent boots. The resulting XML configuration will look either +like this: :: @@ -88,14 +88,28 @@ this: <nvram template='/usr/share/edk2/ovmf/OVMF_VARS.secboot.fd'>/var/lib/libvirt/qemu/nvram/vm_VARS.fd</nvram> </os> +or like this: + +:: + + <os firmware='efi'> + <firmware> + <feature enabled='yes' name='enrolled-keys'/> + <feature enabled='yes' name='secure-boot'/> + </firmware> + <loader type='rom' format='raw'>/usr/share/edk2/aarch64/QEMU_EFI.qemuvars.fd</loader> + <varstore template='/usr/share/edk2/aarch64/vars-template.enrolled.json' path='/var/lib/libvirt/qemu/nvram/vm.json'/> + </os> + In order to force libvirt to repeat the firmware autoselection -process, it's necessary to remove the ``<loader>`` and ``<nvram>`` -elements. Failure to do so will likely result in an error. +process, it's necessary to remove the ``<loader>`` as well as the +``<nvram>`` or ``<varstore>`` elements, depending on what's +applicable. Failure to do so will likely result in an error. Note that 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. +**not** enough to change the Secure Boot status: the NVRAM/varstore +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 @@ -107,9 +121,9 @@ 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. +Most guest operating systems will be able to cope with the +NVRAM/varstore file being reinitialized, but in some cases the VM +will be unable to boot after the change. Additional information @@ -126,15 +140,15 @@ 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 +cause libvirt to initialize the NVRAM/varstore 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. +will result in no keys being present in the NVRAM/varstore file. +Unable to verify signatures, the firmware will allow even unsigned +operating systems to run. If running unsigned code is desired, it's also possible to ask for the ``secure-boot`` feature to be disabled, which will cause libvirt -- 2.53.0