[PATCH] docs: Describe protected virtualization guest setup

[Daniel P. Berrangé]

On Tue, Apr 28, 2020 at 05:58:02PM +0200, Boris Fiuczynski wrote:
> From: Viktor Mihajlovski <mihajlov at linux.ibm.com>
> 
> Protected virtualization/IBM Secure Execution for Linux protects
> guest memory and state from the host.
> 
> Add some basic information about technology and a brief guide
> on setting up secure guests with libvirt.
> 
> Signed-off-by: Viktor Mihajlovski <mihajlov at linux.ibm.com>
> Reviewed-by: Boris Fiuczynski <fiuczy at linux.ibm.com>
> Reviewed-by: Paulo de Rezende Pinatti <ppinatti at linux.ibm.com>
> ---
>  docs/kbase.html.in                      |   3 +
>  docs/kbase/protected_virtualization.rst | 188 ++++++++++++++++++++++++

I'd suggest calling this  s390_protected_virt.rst

> diff --git a/docs/kbase.html.in b/docs/kbase.html.in
> index c586e0f676..05a3239224 100644
> --- a/docs/kbase.html.in
> +++ b/docs/kbase.html.in
> @@ -14,6 +14,9 @@
>          <dt><a href="kbase/secureusage.html">Secure usage</a></dt>
>          <dd>Secure usage of the libvirt APIs</dd>
>  
> +        <dt><a href="kbase/protected_virtualization.html">Protected virtualization</a></dt>

"s390 Protected virtualization"  as the title

> +        <dd>Running secure guests with IBM Secure Execution</dd>

s/secure guests/secure s390 guests/

> +
>          <dt><a href="kbase/launch_security_sev.html">Launch security</a></dt>
>          <dd>Securely launching VMs with AMD SEV</dd>
>  
> diff --git a/docs/kbase/protected_virtualization.rst b/docs/kbase/protected_virtualization.rst
> new file mode 100644
> index 0000000000..48f2add14e
> --- /dev/null
> +++ b/docs/kbase/protected_virtualization.rst
> @@ -0,0 +1,188 @@
> +========================
> +Protected Virtualization

s/^/s390/

> +========================

> +Host Requirements
> +=================
> +
> +IBM Secure Execution for Linux has some hardware and firmware
> +requirements. The system hardware must be an IBM z15 (or newer),
> +or an IBM LinuxONE III (or newer).
> +
> +It is also necessary that the IBM Secure Execution feature is
> +enabled for that system. Check for facility '158', e.g.
> +
> +::
> +
> +   $ grep facilities /proc/cpuinfo | grep 158

I'd suggest that "virt-host-validate" be probing for this
so we can just tell them to run that command.

> +The kernel must include the protected virtualization support
> +which can be verified by checking for the presence of directory
> +``/sys/firmware/uv``. It will only be present when both the
> +hardware and the kernel support are available.
> +
> +Finally, the host operating system must donate some memory to
> +the ultravisor needed to store memory security information.
> +This is achieved by specifying the following kernel command
> +line parameter to the host boot configuration
> +
> +::
> +
> +   prot_virt=1
> +
> +
> +Guest Requirements
> +==================
> +
> +Guest Boot
> +----------
> +
> +To start a guest in protected virtualization secure mode, the
> +boot image must have been prepared first with the program
> +``genprotimg`` using the correct public key for this host.
> +``genprotimg`` is part of the package ``s390-tools``, or
> +``s390-utils``, depending on the Linux distribution being used.
> +It can also be found at
> +`<https://github.com/ibm-s390-tools/s390-tools/tree/master/genprotimg>`_
> +
> +The guests have to be configured to use the host CPU model, which
> +must contain the ``unpack`` facility indicating ultravisor guest support.
> +
> +With the following command it's possible to check whether the host
> +CPU model satisfies the requirement
> +
> +::
> +
> +   $ virsh domcapabilities | grep unpack
> +
> +which should return
> +
> +::
> +
> +   <feature policy='require' name='unpack'/>
> +
> +If the check fails despite the host system actually supporting
> +protected virtualization guests, this can be caused by a stale
> +libvirt capabilities cache. To recover, run the following
> +commands
> +
> +::
> +
> +   $ systemctl stop libvirtd
> +   $ rm /var/cache/libvirt/qemu/capabilities/*.xml
> +   $ systemctl start libvirtd

If this is truly needed that it is a bug in libvirt - we're missing
something in the cache invalidation logic.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|