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

[Cole Robinson]

On 6/6/19 6:00 AM, Erik Skultety wrote:
> 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.
>  

These docs are nice! But when I see this much information in
virt-install docs I start to get worried :) The man page isn't
consistent here but I think for most cli options we should do little
more than point to the libvirt documentation, otherwise we duplicate
information that will inevitably get out of date. If libvirt docs aren't
sufficient here, like documenting the memtune/q35/uefi caveat stuff,
then those docs should be updated, or libvirt made to give really
explicit error messages that leave no room for confusion about what's
missing.

IMO no one should be going to the virt-install man page to learn about
how a virt features works or what's required to full specify it, but
instead learn about things that are specific to the virt-install tool
and possibly some details on commonly used options. So for example I
don't think this section needs to have an explicit break down of each
sub option.

What I think would be sufficient here is giving a couple example
invocations and a brief explanation. So if '--launchSecurity sev' gives
a working config, explain that it enables sev with default values but
because dhCert isn't specified you only get blah blah blah. And then
maybe a full example invocation

>  =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>.
>  
> -

Stray whitespace change

Thanks,
Cole

>  =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
> +

Interesting about the iommu bit. What's the failure scenario if iommu
isn't specified, does qemu fail to start?

Thanks,
Cole