From nobody Thu Dec 26 10:58:18 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 17321130926051006.9419180226394; Wed, 20 Nov 2024 06:31:32 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id 7D069155D; Wed, 20 Nov 2024 09:31:31 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id A1FCF1412; Wed, 20 Nov 2024 09:31:09 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id B483813FB; Wed, 20 Nov 2024 09:31:07 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 01CA113E7 for ; Wed, 20 Nov 2024 09:31:03 -0500 (EST) Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-586-nJBnBHfmMcSiCD6usqExFg-1; Wed, 20 Nov 2024 09:31:02 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8367B195419F for ; Wed, 20 Nov 2024 14:31:01 +0000 (UTC) Received: from fedora.redhat.com (unknown [10.45.226.18]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D79371956086; Wed, 20 Nov 2024 14:30:59 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1732113063; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=ICJbLDyN0Y7xDRw4pqglp8WCtu5TLNUMHko2Nt9cVUA=; b=G1oynG0ekh2SmdOhgXKr5wUmmF0LDSaYSWF7G3f0CHrr8C60dMTkvpPuzV55vU3IAwPjDq 7FZJjYq4CMfDEBgOpAqzascsQxO03KrgXrwVMyROtCpY6pFQ0l9mJJv6hBFBpfEg69Dc+W i82jp/pskrgIl192RPqxB4q+bliXyDI= X-MC-Unique: nJBnBHfmMcSiCD6usqExFg-1 X-Mimecast-MFC-AGG-ID: nJBnBHfmMcSiCD6usqExFg From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: devel@lists.libvirt.org Subject: [libvirt PATCH] docs: document external swtpm Date: Wed, 20 Nov 2024 15:30:54 +0100 Message-ID: <4ac112216c375ac64087ae4c0e98e6e1542a7e7e.1732113054.git.jtomko@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: lEEmAOOg_q-RHjcpxSPmTYh1KNeXY0Od4Xg5VK0RHgI_1732113061 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: BWU3GVGIL56IQZZHUCYBNZIM42GZPSUQ X-Message-ID-Hash: BWU3GVGIL56IQZZHUCYBNZIM42GZPSUQ X-MailFrom: jtomko@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header CC: marcandre.lureau@redhat.com, cohuck@redhat.com X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1732113094484116600 Content-Type: text/plain; charset="utf-8" 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 element. Signed-off-by: J=C3=A1n Tomko --- 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 ... =20 +Example: usage of external TPM emulator :since:`Since 9.0.0` + +:: + + ... + + + + + + + + ... + ``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. =20 + ``external`` + For this backend, libvirt expects the TPM emulator to be started ext= ernally. + The path to the unix socket where the emulator is listening is passed + via the ``source`` element. Other ``backend`` sub-elements do not ap= ply + in these case, since they are controlled by the emulator command lin= e. + ``version`` The ``version`` attribute indicates the version of the TPM. This attrib= ute 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. =20 ``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 loca= tion + 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. =20 When specified, it is the user's responsability to prevent files from b= eing 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: =20 ``type`` - The type of storage. It's possible to provide "file" to utilize a si= ngle - file or block device where the TPM state will be stored, or "dir" fo= r 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 utili= ze + 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 support= ed. + Can be omitted. =20 ``path`` - The path to the TPM state storage. + The path to the TPM state storage, or the unix socket. =20 - :since:`Since v10.10.0` =20 ``persistent_state`` The ``persistent_state`` attribute indicates whether 'swtpm' TPM state = is --=20 2.47.0