[PATCH] docs: Describe protected virtualization guest setup

[Boris Fiuczynski]

On 4/29/20 3:29 PM, Daniel P. Berrangé wrote:
> 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
Done

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

As discussed changed to "Protected virtualization on s390".

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

Done

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

As discussed changed to "Protected virtualization on 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.

Extending virt-host-validate can be done.
This documentation follows the same bare bone approach as is used in 
docs/kbase/launch_security_sev.rst.
Would it be OK to explain both with and without libvirt means?

I will have a look at virt-host-validate once the cache invalidation is 
ready.

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

Yes, as I wrote to your other mail... we are working on it.


> 
> Regards,
> Daniel
> 


-- 
Mit freundlichen Grüßen/Kind regards
    Boris Fiuczynski

IBM Deutschland Research & Development GmbH
Vorsitzender des Aufsichtsrats: Gregor Pillen
Geschäftsführung: Dirk Wittkopp
Sitz der Gesellschaft: Böblingen
Registergericht: Amtsgericht Stuttgart, HRB 243294