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 DE78D1FF13A for ; Wed, 08 Jul 2026 15:05:01 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 0063021454; Wed, 08 Jul 2026 15:05:01 +0200 (CEST) From: Elias Huhsovitz To: pve-devel@lists.proxmox.com Subject: [PATCH docs 2/4] qm_memory: expand qm_memory_encryption documentation to include Intel TDX Date: Wed, 8 Jul 2026 15:04:49 +0200 Message-ID: <20260708130453.166084-3-e.huhsovitz@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260708130453.166084-1-e.huhsovitz@proxmox.com> References: <20260708130453.166084-1-e.huhsovitz@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1783515885850 X-SPAM-LEVEL: Spam detection results: 0 AWL -0.000 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) KAM_SHORT 0.001 Use of a URL Shortener for very short URL SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: LT7RKY7ZT34U2JUNLZ3SPIKUFCQ3DC5S X-Message-ID-Hash: LT7RKY7ZT34U2JUNLZ3SPIKUFCQ3DC5S X-MailFrom: e.huhsovitz@proxmox.com 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 CC: Elias Huhsovitz X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: The pve-manager provides a help-button in the Intel TDX edit window, but there was no documentation regarding this. Now includes basic information about Intel Trust Domain Extensions (TDX). Signed-off-by: Elias Huhsovitz --- qm.adoc | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) diff --git a/qm.adoc b/qm.adoc index 8213758..cf82ad1 100644 --- a/qm.adoc +++ b/qm.adoc @@ -926,6 +926,160 @@ Links: * https://documentation.suse.com/sles/15-SP7/single-html/SLES-amd-sev/article-amd-sev.html * https://www.amd.com/content/dam/amd/en/documents/developer/56860.pdf[SEV Secure Nested Paging Firmware ABI Specification] +[[qm_memory_encryption_tdx]] +Intel TDX +^^^^^^^^^ + +Intel Trust Domain Extensions (TDX) protect guest VM memory and CPU state +from the host hypervisor. TDX uses Intel Multi-Key Total Memory Encryption +(MKTME) to provide per-VM memory encryption and introduces a CPU-isolated +module that manages the creation and execution of protected VMs (called Trust +Domains, or TDs). + +*Host Requirements:* + +* 4th Generation Intel Xeon Scalable processor (Codename: Sapphire Rapids) + or newer. TDX is a hardware feature introduced with Sapphire Rapids and is + not available on earlier Xeon generations. + See https://www.intel.com/content/www/us/en/support/articles/000091103/processors/intel-xeon-processors.html[Intel — Xeon processors with TDX support]. +* Enable TDX in the BIOS/UEFI settings. The kernel assumes the TDX module + is loaded by the BIOS at boot. + See https://docs.kernel.org/arch/x86/tdx.html#tdx-host-kernel-support[TDX host kernel support] +* A host kernel with TDX support. The kernel detects TDX by detecting TDX + private KeyIDs configured by the BIOS during https://docs.kernel.org/arch/x86/tdx.html#tdx-boot-time-detection[early boot]. + +*Notes:* + +* Add `nohibernate` to the kernel command line if hibernation support is + compiled in. TDX cannot survive S3 (suspend-to-RAM) or S4 (hibernation) + power states — the hardware resets and disables TDX completely when the + platform enters these states. + See https://docs.kernel.org/arch/x86/tdx.html#interaction-vs-s3-and-deeper-states[Interaction vs S3 and deeper states] +* TDX module initialization + https://docs.kernel.org/arch/x86/tdx.html#tdx-module-initialization[consumes approximately 1/256th of system RAM] for + the Physical Address Metadata Table (PAMT). +* The TDX module is initialized https://docs.kernel.org/arch/x86/tdx.html#tdx-module-initialization[on demand] (when the first TDX guest is + created), not at boot time. + +*Verify Intel TDX is Enabled on Host:* + +To https://docs.kernel.org/arch/x86/tdx.html#tdx-boot-time-detection[check if TDX is enabled on the host], search for `tdx` in `dmesg`. +If the BIOS has enabled TDX and the TDX module was successfully initialized, +the output should look like this: + +---- +# dmesg | grep -i tdx +[...] virt/tdx: BIOS enabled: private KeyID range [64, 128) +[...] virt/tdx: 1050644 KB allocated for PAMT +[...] virt/tdx: module initialized +---- + +If the TDX module is not loaded by the BIOS, dmesg will show: + +---- +[...] virt/tdx: module not loaded +---- + +If TDX initialization fails because hibernation is enabled in the kernel: + +---- +[...] virt/tdx: initialization failed: Hibernation support is enabled +---- + +The current TDX module version can be https://docs.kernel.org/arch/x86/tdx.html#how-to-update-the-tdx-module[checked at runtime]: + +---- +# cat /sys/devices/faux/tdx_host/version +---- ++ +(If this path does not exist, the TDX module has not been initialized yet.) + +*Guest Requirements:* + +* https://www.qemu.org/docs/master/system/i386/tdx.html#trust-domain-virtual-firmware-tdvf[Trust Domain Virtual Firmware (TDVF)]. + TDVF is a TDX-enabled build of OVMF + that provides TD services to boot the guest OS. Standard OVMF without TDX + support cannot be used. TDVF is loaded via the `-bios` option because TDX + does not support readonly memslots, so TDVF cannot be mapped as a pflash + device. +* The guest operating system must contain https://docs.kernel.org/arch/x86/tdx.html#tdx-guest-support[TDX guest support]. + For Linux, this + means a kernel with TDX guest support enabled, which sets up a #VE + (Virtualization Exception) handler and shared-memory infrastructure at + boot. +* The `kernel-irqchip` must be set to `split`. QEMU sets this + https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[automatically] + when launching a TDX guest if the setting is left on its default `auto` + value. +* Advisable to use Q35 + +*Limitations:* + +* Windows guests are not supported. + See https://pve.proxmox.com/wiki/Roadmap[Proxmox VE Roadmap] +* Live migration is currently unsupported. + See https://www.qemu.org/docs/master/system/i386/tdx.html#live-migration[QEMU — Live Migration] and https://pve.proxmox.com/wiki/Roadmap[PVE Roadmap] +* PCI passthrough to TDX guests is limited. Device MMIO regions and DMA + buffers are mapped as shared memory, which means the hypervisor controls + their content. Shared memory must never be used for sensitive data. + See https://docs.kernel.org/arch/x86/tdx.html#ve-on-memory-accesses[#VE on Memory Accesses], + https://docs.kernel.org/arch/x86/tdx.html#shared-memory-conversions[Shared Memory Conversions], + https://intel.github.io/ccc-linux-guest-hardening-docs/security-spec.html[Intel TDX Guest Kernel Security Specification] +* S3 (suspend-to-RAM) and hibernation (S4) are not supported on the host + when TDX is enabled. + See https://docs.kernel.org/arch/x86/tdx.html#interaction-vs-s3-and-deeper-states[interaction-vs-s3-and-deeper-states] +* Physical https://docs.kernel.org/arch/x86/tdx.html#cpu-hotplug[CPU Hotplug (ACPI)] is not supported when TDX is enabled. Logical + CPU online/offline is supported. +* https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[No SMM support]. + TDX does not allow the hypervisor to manipulate guest + register states, which SMM requires. +* https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[No readonly support for private memory]. + +*Example Configuration:* + +---- +# qm set -intel-tdx 1 +---- + +This enables Intel TDX for the specified VM. Proxmox configures QEMU to create +a TDX guest by instantiating the `tdx-guest` object and setting the +`confidential-guest-support` machine property. +See https://www.qemu.org/docs/master/system/i386/tdx.html#launching-a-td-tdx-vm[Launching a TD] + +The VM must also use a TDVF-enabled firmware image. +See https://www.qemu.org/docs/master/system/i386/tdx.html#trust-domain-virtual-firmware-tdvf[trust-domain-virtual-firmware-tdvf] + +The QEMU TDX guest object supports configurable attributes via a raw 64-bit +field. The most relevant bit is DEBUG (bit 0), which enables off-TD debug mode +and allows the hypervisor to inspect TD state. Debug mode should only be +enabled for development and troubleshooting, as it reduces the security +guarantees of the TD. See the +https://www.qemu.org/docs/master/system/i386/tdx.html#td-attributes[TD attributes] +for details on configurable TDX attributes. + +*Verify TDX in the VM* + +The `dmesg` output should look similar to this +footnote:[Ubuntu TDX guide https://github.com/canonical/tdx/blob/3.3/README.md#7-verify-td]: + +---- +# dmesg | grep -i tdx +[...] tdx: Guest detected +[...] DMI: QEMU Standard PC (Q35 + ICH9, 2009), BIOS 2023.05-2+tdx1.0~ubuntu23.10.1 10/17/2023 +[...] process: using TDX aware idle routine +[...] Memory Encryption Features active: Intel TDX +---- + +Links: + +* https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html[Intel IDX documentation] +* https://www.qemu.org/docs/master/system/i386/tdx.html[QEMU Intel IDX] +* https://docs.kernel.org/virt/kvm/x86/intel-tdx.html +* https://docs.kernel.org/arch/x86/tdx.html +* https://intel.github.io/ccc-linux-guest-hardening-docs/security-spec.html[Intel Trust Domain Extension Linux Guest Kernel Security Specification] +* https://www.intel.com/content/www/us/en/support/articles/000091103/processors/intel-xeon-processors.html[What Intel® Xeon Processors Support for Intel® Trust Domain Extensions (Intel® TDX)?] +* https://www.intel.com/content/www/us/en/developer/articles/technical/tdx-performance-analysis-reference-documentation.html[Intel Trust Domain Extensions (Intel® TDX) Performance Analysis Reference Documentation] + [[qm_network_device]] Network Device ~~~~~~~~~~~~~~ -- 2.47.3