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

Mon Jun 10 15:40:38 UTC 2019

On Thu, Jun 06, 2019 at 05:13:26PM -0400, Cole Robinson wrote:
> 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.

True, I'll strip those verbose bits and try to propose a dedicated libvirt
page, kind of like Michal did for the NSS switch module.

>
> 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?

Depends on which device the iommu bit is missing, that kind of determines at
what phase the boot is going to be stuck at, but QEMU will always start...I
believe at some point I even managed to boot into the system and get a physical
console, but right after submitting the user password the system became
unresponsive, but I'd have to go and try different combinations again :(.

Erik