[PATCH pve-docs v3 19/19] qm: document the custom firmware of the bios option

[Christian Ludwig <christian_ludwig@genua.de>]

Describe how to set and remove a custom EFI firmware image, and what to
consider for migration, replication, templates and backups.

Signed-off-by: Christian Ludwig <christian_ludwig@genua.de>
---
 qm.adoc | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index 18a4fbe..81d97e7 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1250,6 +1250,61 @@ NOTE: The markers `ms-cert=2023` and `ms-cert=2023w` may indicate partial
 enrollment. The VM start task log will warn about this. You should apply the
 enrollment procedure for such EFI disks too.
 
+[[qm_custom_efi_firmware]]
+Custom EFI Firmware
+^^^^^^^^^^^^^^^^^^^
+
+By default, {pve} uses the system-provided OVMF firmware images. If you need a
+custom or vendor-specific EFI firmware code image, you can override the default
+firmware with the `firmware` property of the `bios` VM option.
+
+The firmware image must first be uploaded to a storage that has the
+`efi-firmware` content type enabled. It must be a raw image and its file name
+must end with `.fd`.
+
+To configure a VM to use a custom firmware image:
+
+----
+# qm set <vmid> -bios ovmf,firmware=<storage>:efi-firmware/<name>.fd
+----
+
+For example:
+
+----
+# qm set 100 -bios ovmf,firmware=local:efi-firmware/custom-ovmf-code.fd
+----
+
+NOTE: A custom firmware image is only supported with the `ovmf` BIOS type.
+
+The custom image replaces the firmware code (pflash0) only. The EFI vars disk
+(`efidisk0`) keeps its contents, which are created from the vars template of
+the system-provided firmware. If they do not match the custom image, the guest
+may fail to boot. A matching vars image can be imported with:
+
+----
+# qm set <vmid> -efidisk0 <storage>:0,efitype=4m,pre-enrolled-keys=0,import-from=<source>
+----
+
+Confidential VMs (AMD SEV-SNP, Intel TDX) load the firmware read-only via
+`-bios` and use no EFI vars disk at all, so this does not apply to them. For
+that reason, the web interface only offers custom firmware images for such VMs,
+through the 'BIOS' entry in the 'Hardware' panel of a VM.
+
+A VM that references a custom firmware image can only start if the image is
+available on the node. This also applies to templates and to backups of stopped
+VMs, which start the VM for the duration of the backup, and to VMs restored on
+another node or cluster.
+
+The firmware image is neither copied when a VM migrates nor replicated. To be
+able to migrate a VM, put the image on a shared storage, so that it is available
+on all nodes.
+
+To remove a custom firmware assignment and revert to the default OVMF image:
+
+----
+# qm set <vmid> -bios ovmf
+----
+
 [[qm_tpm]]
 Trusted Platform Module (TPM)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.34.1