From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id 080871FF0DE for ; Thu, 19 Nov 2026 15:16:12 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 41BB521728; Thu, 19 Nov 2026 15:15:15 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=genua.de; s=202307; t=1795097676; bh=PfqHO99iQYtqeMl48m7dyUYGmKf/D7RQO/BRlOwrvhw=; h=Date:From:To:Subject:References:In-Reply-To:From; b=G0wmGSxFdNaBUvPligYkk9o6BFoGJ06RSUKItRzIIPaUo+cJSWlbqOmo5df1IgO4b 6ZqfN/oByNqUbgKnBv+7xBIPWGxWsJeNJoUMrB1/XxnYPiFj/XwypqjB4R+sxZzlPZ P24GjSe+nuooGxmGK4O4jEHz6YpghQUlb6vKc63QJ7MMbF/Ogre0JweR08GQkNQK/f oE7vAoAwpy8iMEgAN/5437IfD5i96uxWc0RQDHJjQNkXCUDOtnrID0xBMmCA/E+/wu iz4Y/9rHMaVyDXoNjEWdIsVDc+eJTn7fe77RgvX/gSc4KHlT0kPFnOamKIKCGYyd4E x0NPeGo2B//jA== Date: Thu, 19 Nov 2026 15:14:35 +0100 From: Christian Ludwig To: Subject: [PATCH pve-docs v4 20/20] qm: document the custom firmware of the bios option Message-ID: <6a40f3ffc9cf024d524b7e7392880082016f9c39.1795092172.git.christian_ludwig@genua.de> References: MIME-Version: 1.0 In-Reply-To: X-Originating-IP: [192.168.217.185] X-ClientProxiedBy: kch1-mta08.win.genua.de (10.208.16.108) To kch1-mta07.win.genua.de (10.208.16.107) Content-Type: text/plain; charset="us-ascii" Content-Disposition: inline X-SPAM-LEVEL: Spam detection results: 0 AWL 0.054 Adjusted score from AWL reputation of From: address DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain DMARC_PASS -0.1 DMARC pass policy RCVD_IN_DNSWL_NONE -0.0001 Sender listed at https://www.dnswl.org/, no trust SPF_HELO_PASS -0.001 SPF: HELO matches SPF record SPF_PASS -0.001 SPF: sender matches SPF record UNPARSEABLE_RELAY 0.001 Informational: message has unparseable relay lines Message-ID-Hash: C7UB7MOQRYYIJ27XSXHARLZ6IUHD4GLI X-Message-ID-Hash: C7UB7MOQRYYIJ27XSXHARLZ6IUHD4GLI X-MailFrom: christian_ludwig@genua.de X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- qm.adoc | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/qm.adoc b/qm.adoc index e55c7a8..a8adc87 100644 --- a/qm.adoc +++ b/qm.adoc @@ -1254,6 +1254,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 -bios ovmf,firmware=:efi-firmware/.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 -efidisk0 :0,efitype=4m,pre-enrolled-keys=0,import-from= +---- + +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 -bios ovmf +---- + [[qm_tpm]] Trusted Platform Module (TPM) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 2.34.1