[virt-tools-list] [virt-install PATCH 6/7] man: Provide a documentation for the SEV feature

[Erik Skultety]

Signed-off-by: Erik Skultety <eskultet at redhat.com>
---
 man/virt-install.pod | 75 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 74 insertions(+), 1 deletion(-)

diff --git a/man/virt-install.pod b/man/virt-install.pod
index 51e1e159..b2745ae1 100644
--- a/man/virt-install.pod
+++ b/man/virt-install.pod
@@ -386,7 +386,64 @@ Configure guest power management features. Example:
 
 Use --pm=? to see a list of all available sub options. Complete details at L<https://libvirt.org/formatdomain.html#elementsPowerManagement>
 
+=item B<--launch-security> TYPE[,OPTS]
 
+Enable launch security for the guest, e.g. AMD SEV.
+
+Use --launch-security=? to see a list of all available sub options. Complete
+details at L<https://libvirt.org/formatdomain.html#launchSecurity>.
+
+=over 4
+
+=item policy=HEX
+
+A 4-byte integer bitfield used to alter the SEV firmware behaviour. See the
+link above for more details on the meaning of individual bits. If policy is not
+supplied, 0x0003 will be used as default.
+
+=item cbitpos=NUM
+
+Denotes which bit in the guest page table entry is the encryption bit. Unless
+there's a good reason to specify this explicitly, it will be filled in from
+hypervisor capabilities
+
+=item reduced_phys_bits=NUM
+
+Denotes how many bits from the physical address space are sacrificed for the
+encryption feature. Unless there's a good reason to specify this explicitly,
+it will be filled in from hypervisor capabilities
+
+=item dh_cert=BASE64_ENCODED_CERTIFICATE
+
+This option is used to supply the VM owner's Diffie-Hellman certificate which
+the SEV firmware will use to establish a secure communication channel. The
+certificate is not necessary to boot an SEV-encrypted guest, however the
+encryption key will be derived from a random secret, thus no data can be
+exchanged with the SEV firmware, e.g to perform a validation of the guest boot
+firmware.
+
+=item session=BASE64_ENCODED_SESSION_BLOB
+
+This is an SEV guest runtime session blob which is defined in the AMD SEV API
+spec.
+
+=back
+
+Note that launch security for SEV is only available with UEFI and Q35 machine
+type. The current version of virt-install alo requires usage of I<--memtune>
+along with I<--launch-security> because the SEV encrypted pages cannot
+be swapped out or move around so the memory needs to be pinned. Since certain
+memory regions allocated by QEMU (UEFI pflash, device ROMs, etc.) have to be
+encrypted as well, and given that computing the hard limit in an automated
+manner accurately is non-deterministic, the limit must be set manually -
+256MiB extra over the total guest RAM should suffice most workloads and is a
+good starting point for tailoring it to your needs.
+
+    # 4GiB of guest RAM + 256MiB extra limit expressed in KiB
+    --memtune hard_limit=4563402
+
+See the EXAMPLES section for common invocations, especially if usage of virtio
+devices is desired.
 
 =back
 
@@ -1582,7 +1639,6 @@ Configure a vsock host/guest interface. A typical configuration would be
 
 Use --vsock=? to see a list of all available sub options. Complete details at L<https://libvirt.org/formatdomain.html#vsock>.
 
-
 =back
 
 =head1 MISCELLANEOUS OPTIONS
@@ -1764,6 +1820,23 @@ Start serial QEMU ARM VM, which requires specifying a manual kernel.
        --boot kernel=/tmp/my-arm-kernel,initrd=/tmp/my-arm-initrd,dtb=/tmp/my-arm-dtb,kernel_args="console=ttyAMA0 rw root=/dev/mmcblk0p3" \
        --graphics none
 
+Start an SEV launch security VM with 4GB of RAM with a couple of virtio devices
+(Note that the IOMMU flag needs to be turned on with driver.iommu):
+
+  # virt-install \
+       --name foo \
+       --memory 4096 \
+       --boot uefi \
+       --machine q35 \
+       --memtune hard_limit=4563402
+       --disk size=15,target.bus=scsi \
+       --controller type=scsi,model=virtio-scsi,driver.iommu=on \
+       --controller type=virtio-serial,driver.iommu=on \
+       --network network=default,model=virtio,driver.iommu=on \
+       --rng driver,iommu=on \
+       --memballoon driver.iommu=on \
+       --launch-security sev
+
 =head1 BUGS
 
 Please see L<https://virt-manager.org/bugs>
-- 
2.20.1