[PATCH docs/manager 0/4] manager/docs: fix: #6211: ui: docs: add reference to vm options protection/IDX/SEV

[PATCH docs/manager 0/4] manager/docs: fix: #6211: ui: docs: add reference to vm options protection/IDX/SEV

[Elias Huhsovitz]

This series addresses bug #6211 by improving the documentation and UI
help links for several VM options. Specifically, it adds a help button
and a descriptive hint for the ambiguous "protection" option, and
corrects the documentation links for AMD SEV and Intel TDX.

Because the UI changes require corresponding documentation updates,
this series is split across two repositories:

pve-docs:
- Adds a new documentation section for Intel TDX.
- Fixes dead links in the existing AMD SEV documentation section.

pve-manager:
- Adds a help button and a descriptive hint to the Protection edit dialog.
- Updates the AMD SEV and Intel TDX dialogs to point to the correct
  memory encryption documentation anchors.

This requires first applying patch 2/4 to pve-docs and bumping it, so
pve-manager can pick up the new documentation chapter when being built.


pve-docs:

Elias Huhsovitz (2):
  qm_memory: update dead links in qm_memory_encryption_sev section on
    AMD SEV
  qm_memory: expand qm_memory_encryption documentation to include Intel
    TDX

 qm.adoc | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 157 insertions(+), 4 deletions(-)


pve-manager:

Elias Huhsovitz (2):
  fix #6211: ui: vm: options:
  fix #6211: ui: vm: options:

 www/manager6/qemu/Options.js | 25 +++++++++++++++++++------
 www/manager6/qemu/SevEdit.js |  2 +-
 www/manager6/qemu/TdxEdit.js |  2 +-
 3 files changed, 21 insertions(+), 8 deletions(-)


Summary over all repositories:
  4 files changed, 178 insertions(+), 12 deletions(-)

-- 
Generated by murpp 0.12.0

[PATCH docs 1/4] qm_memory: update dead links in qm_memory_encryption_sev section on AMD SEV

[Elias Huhsovitz]

The section on AMD SEV included dead links.
Replace dead links with up-to-date working links.

Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
---
 qm.adoc | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index 96ba68b..8213758 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -922,10 +922,9 @@ Links:
 * https://developer.amd.com/sev/
 * https://github.com/AMDESE/AMDSEV
 * https://www.qemu.org/docs/master/system/i386/amd-memory-encryption.html
-* https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf
-* https://documentation.suse.com/sles/15-SP1/html/SLES-amd-sev/index.html
-* https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf[
-SEV Secure Nested Paging Firmware ABI Specification]
+* https://docs.amd.com/v/u/en-US/55766_PUB_3.24_SEV_API
+* 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_network_device]]
 Network Device
-- 
2.47.3

[PATCH docs 2/4] qm_memory: expand qm_memory_encryption documentation to include Intel TDX

[Elias Huhsovitz]

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 <e.huhsovitz@proxmox.com>
---
 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 <vmid> -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

[PATCH manager 3/4] fix #6211: ui: vm: options:

[Elias Huhsovitz]

The help buttons in the AMD SEV and Intel TDX dialos were pointing to
the general
memory documentation.
Update the links to use the correct documentation anchors

Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
---
 www/manager6/qemu/SevEdit.js | 2 +-
 www/manager6/qemu/TdxEdit.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/www/manager6/qemu/SevEdit.js b/www/manager6/qemu/SevEdit.js
index 44db34bd..c308b3ab 100644
--- a/www/manager6/qemu/SevEdit.js
+++ b/www/manager6/qemu/SevEdit.js
@@ -2,7 +2,7 @@ Ext.define('PVE.qemu.SevInputPanel', {
     extend: 'Proxmox.panel.InputPanel',
     xtype: 'pveSevInputPanel',
 
-    onlineHelp: 'qm_memory', // TODO: change to 'qm_memory_encryption' one available
+    onlineHelp: 'qm_memory_encryption_sev',
 
     viewModel: {
         data: {
diff --git a/www/manager6/qemu/TdxEdit.js b/www/manager6/qemu/TdxEdit.js
index c1f990a9..38948a6c 100644
--- a/www/manager6/qemu/TdxEdit.js
+++ b/www/manager6/qemu/TdxEdit.js
@@ -2,7 +2,7 @@ Ext.define('PVE.qemu.TdxInputPanel', {
     extend: 'Proxmox.panel.InputPanel',
     xtype: 'pveTdxInputPanel',
 
-    onlineHelp: 'qm_memory', // TODO: change to 'qm_memory_encryption' one available
+    onlineHelp: 'qm_memory_encryption_tdx',
 
     viewModel: {
         data: {
-- 
2.47.3

[PATCH manager 4/4] fix #6211: ui: vm: options:

[Elias Huhsovitz]

The "protection" options was ambiguous.
Add hint to briefly describe the feature.
Add help button that points to Options section containing a description
of the "protection" option.

Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
---
 www/manager6/qemu/Options.js | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/www/manager6/qemu/Options.js b/www/manager6/qemu/Options.js
index 8a4721a0..664606da 100644
--- a/www/manager6/qemu/Options.js
+++ b/www/manager6/qemu/Options.js
@@ -319,13 +319,26 @@ Ext.define('PVE.qemu.Options', {
                     ? {
                           xtype: 'proxmoxWindowEdit',
                           subject: gettext('Protection'),
+                          onlineHelp: 'qm_options',
                           items: {
-                              xtype: 'proxmoxcheckbox',
-                              name: 'protection',
-                              uncheckedValue: 0,
-                              defaultValue: 0,
-                              deleteDefaultValue: true,
-                              fieldLabel: gettext('Enabled'),
+                              xtype: 'inputpanel',
+                              items: [
+                                  {
+                                      xtype: 'proxmoxcheckbox',
+                                      name: 'protection',
+                                      uncheckedValue: 0,
+                                      defaultValue: 0,
+                                      deleteDefaultValue: true,
+                                      fieldLabel: gettext('Enabled'),
+                                  },
+                                  {
+                                      xtype: 'displayfield',
+                                      userCls: 'pmx-hint',
+                                      value: gettext(
+                                          'Prevents the VM and its disks from being removed',
+                                      ),
+                                  },
+                              ],
                           },
                       }
                     : undefined,
-- 
2.47.3