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 | 81 +++++++++++++++++++++++----------------
docs/kbase/secureboot.rst | 46 ++++++++++++++--------
4 files changed, 114 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 87644ad42a..ccd284b8c6 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 is here 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.
@@ -3699,7 +3720,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
@@ -4864,7 +4885,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
@@ -5088,7 +5109,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
@@ -6344,7 +6365,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 8b4f0ecff3..1d6b80dff7 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 is here 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.
::
@@ -126,41 +131,53 @@ 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 ``<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.
-For the ``loader`` element, the following can occur:
+The ``<loader/>`` element contains the following information:
``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.
+
+ This information is exposed primarily for backwards compatibility reasons.
+ It is recommended to ignore it and use firmware autoselection instead.
``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 only 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.
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