[libvirt PATCH] docs: document external swtpm

Ján Tomko posted 1 patch 2 weeks, 2 days ago
docs/formatdomain.rst | 43 ++++++++++++++++++++++++++++++++++++-------
1 file changed, 36 insertions(+), 7 deletions(-)
[libvirt PATCH] docs: document external swtpm
Posted by Ján Tomko 2 weeks, 2 days ago
When external swtpm support was added back in 9.0.0, I omitted
the update of the XML docs.

Add it now, especially since the 'emulator' backend can now
also use the <source> element.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
---
 docs/formatdomain.rst | 43 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index b3f9f453aa..a5510e82f5 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -8140,6 +8140,20 @@ Example: usage of the TPM Emulator
      </devices>
      ...
 
+Example: usage of external TPM emulator :since:`Since 9.0.0`
+
+::
+
+     ...
+     <devices>
+       <tpm model='tpm-tis'>
+         <backend type='external'>
+           <source type='unix' mode='connect' path='/tmp/path.sock'/>
+         </backend>
+       </tpm>
+     </devices>
+     ...
+
 ``model``
    The ``model`` attribute specifies what device model QEMU provides to the
    guest. If no model name is provided, ``tpm-tis`` will automatically be chosen
@@ -8178,6 +8192,12 @@ Example: usage of the TPM Emulator
       parameter can be used to enable logging in the emulator backend, and
       accepts non-zero integer values.
 
+   ``external``
+      For this backend, libvirt expects the TPM emulator to be started externally.
+      The path to the unix socket where the emulator is listening is passed
+      via the ``source`` element. Other ``backend`` sub-elements do not apply
+      in these case, since they are controlled by the emulator command line.
+
 ``version``
    The ``version`` attribute indicates the version of the TPM. This attribute
    only works with the ``emulator`` backend. The following versions are
@@ -8190,8 +8210,13 @@ Example: usage of the TPM Emulator
    architecture, TPM model and backend.
 
 ``source``
-   The ``source`` element specifies the location of the TPM state storage . This
-   element only works with the ``emulator`` backend.
+   For the ``emulator`` backend, the ``source`` element specifies the location
+   of the TPM state storage. :since:`Since v10.10.0`
+
+   For the ``external`` backend, it specifies the socket of the externally
+   run TPM emulator. :since:`Since v9.0.0`
+
+   This element does not work with the ``passthrough`` backend.
 
    When specified, it is the user's responsability to prevent files from being
    used by multiple VMs or emulators (swtpm will also use advisory locking). If
@@ -8202,14 +8227,18 @@ Example: usage of the TPM Emulator
    The following attributes are supported:
 
    ``type``
-      The type of storage. It's possible to provide "file" to utilize a single
-      file or block device where the TPM state will be stored, or "dir" for the
-      directory where the files will be stored.
+      For ``external`` backend, only type ``unix`` is supported.
+      For ``emulator`` backend, it's possible to provide ``file`` to utilize
+      a single file or block device where the TPM state will be stored,
+      or ``dir`` for the directory where the files will be stored.
+
+   ``mode``
+      Connection mode for the ``unix`` socket. Only ``connect`` is supported.
+      Can be omitted.
 
    ``path``
-      The path to the TPM state storage.
+      The path to the TPM state storage, or the unix socket.
 
-   :since:`Since v10.10.0`
 
 ``persistent_state``
    The ``persistent_state`` attribute indicates whether 'swtpm' TPM state is
-- 
2.47.0
Re: [libvirt PATCH] docs: document external swtpm
Posted by Andrea Bolognani 2 weeks, 1 day ago
On Wed, Nov 20, 2024 at 03:30:54PM +0100, Ján Tomko wrote:
> +   ``external``
> +      For this backend, libvirt expects the TPM emulator to be started externally.
> +      The path to the unix socket where the emulator is listening is passed
> +      via the ``source`` element. Other ``backend`` sub-elements do not apply
> +      in these case, since they are controlled by the emulator command line.

*this case

>  ``source``
> -   The ``source`` element specifies the location of the TPM state storage . This
> -   element only works with the ``emulator`` backend.
> +   For the ``emulator`` backend, the ``source`` element specifies the location
> +   of the TPM state storage. :since:`Since v10.10.0`
> +
> +   For the ``external`` backend, it specifies the socket of the externally
> +   run TPM emulator. :since:`Since v9.0.0`

Maybe "externally started"?

With the typo fixed,

  Reviewed-by: Andrea Bolognani <abologna@redhat.com>

-- 
Andrea Bolognani / Red Hat / Virtualization