Re: [PATCH] docs: Describe protected virtualization guest setup

From: Viktor Mihajlovski <mihajlov(a)linux.ibm.com&gt; 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(a)linux.ibm.com&gt; Reviewed-by: Boris Fiuczynski <fiuczy(a)linux.ibm.com&gt; Reviewed-by: Paulo de Rezende Pinatti <ppinatti(a)linux.ibm.com&gt; --- docs/kbase.html.in | 3 + docs/kbase/protected_virtualization.rst | 188 ++++++++++++++++++++++++

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>

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

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

+========================

+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

+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