[PATCH 26/32] docs: formatdomain-devices: Split out <tpm>
Peter Krempa
pkrempa at redhat.com
Thu Jul 23 13:21:31 UTC 2020
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatdomain-devices-tpm.rst | 94 ++++++++++++++++++++++++++++++
docs/formatdomain-devices.rst | 96 +------------------------------
docs/meson.build | 1 +
3 files changed, 96 insertions(+), 95 deletions(-)
create mode 100644 docs/formatdomain-devices-tpm.rst
diff --git a/docs/formatdomain-devices-tpm.rst b/docs/formatdomain-devices-tpm.rst
new file mode 100644
index 0000000000..41a7c48ba5
--- /dev/null
+++ b/docs/formatdomain-devices-tpm.rst
@@ -0,0 +1,94 @@
+:anchor:`<a id="elementsTpm"/>`
+
+TPM device
+~~~~~~~~~~
+
+The TPM device enables a QEMU guest to have access to TPM functionality. The TPM
+device may either be a TPM 1.2 or a TPM 2.0.
+
+The TPM passthrough device type provides access to the host's TPM for one QEMU
+guest. No other software may be using the TPM device, typically /dev/tpm0, at
+the time the QEMU guest is started. :since:`'passthrough' since 1.0.5`
+
+Example: usage of the TPM passthrough device
+
+::
+
+ ...
+ <devices>
+ <tpm model='tpm-tis'>
+ <backend type='passthrough'>
+ <device path='/dev/tpm0'/>
+ </backend>
+ </tpm>
+ </devices>
+ ...
+
+The emulator device type gives access to a TPM emulator providing TPM
+functionality for each VM. QEMU talks to it over a Unix socket. With the
+emulator device type each guest gets its own private TPM. :since:`'emulator'
+since 4.5.0` The state of the TPM emulator can be encrypted by providing an
+``encryption`` element. :since:`'encryption' since 5.6.0`
+
+Example: usage of the TPM Emulator
+
+::
+
+ ...
+ <devices>
+ <tpm model='tpm-tis'>
+ <backend type='emulator' version='2.0'>
+ <encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/>
+ </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
+ for non-PPC64 architectures. :since:`Since 4.4.0` , another available choice
+ is the ``tpm-crb``, which should only be used when the backend device is a
+ TPM 2.0. :since:`Since 6.1.0` , pSeries guests on PPC64 are supported and the
+ default is ``tpm-spapr``. :since:`Since 6.5.0` , a new model called
+ ``spapr-tpm-proxy`` was added for pSeries guests. This model only works with
+ the ``passthrough`` backend. It creates a TPM Proxy device that communicates
+ with an existing TPM Resource Manager in the host, for example
+ ``/dev/tpmrm0``, enabling the guest to run in secure virtual machine mode
+ with the help of an Ultravisor. Adding a TPM Proxy to a pSeries guest brings
+ no security benefits unless the guest is running on a PPC64 host that has an
+ Ultravisor and a TPM Resource Manager. Only one TPM Proxy device is allowed
+ per guest, but a TPM Proxy device can be added together with other TPM
+ devices.
+
+``backend``
+ The ``backend`` element specifies the type of TPM device. The following types
+ are supported:
+
+ ``passthrough``
+ Use the host's TPM or TPM Resource Manager device.
+
+ This backend type requires exclusive access to a TPM device on the host.
+ An example for such a device is /dev/tpm0. The fully qualified file name
+ is specified by path attribute of the ``source`` element. If no file name
+ is specified then /dev/tpm0 is automatically used. :since:`Since 6.5.0` ,
+ when choosing the ``spapr-tpm-proxy`` model, the file name specified is
+ expected to be a TPM Resource Manager device, e.g. ``/dev/tpmrm0``.
+
+ ``emulator``
+ For this backend type the 'swtpm' TPM Emulator must be installed on the
+ host. Libvirt will automatically start an independent TPM emulator for
+ each QEMU guest requesting access to it.
+
+``version``
+ The ``version`` attribute indicates the version of the TPM. By default a TPM
+ 1.2 is created. This attribute only works with the ``emulator`` backend. The
+ following versions are supported:
+
+ - '1.2' : creates a TPM 1.2
+ - '2.0' : creates a TPM 2.0
+
+``encryption``
+ The ``encryption`` element allows the state of a TPM emulator to be
+ encrypted. The ``secret`` must reference a secret object that holds the
+ passphrase from which the encryption key will be derived.
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index 1357a906b5..cf7cbc40fc 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -58,101 +58,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
.. include:: formatdomain-devices-watchdog.rst
.. include:: formatdomain-devices-memballoon.rst
.. include:: formatdomain-devices-rng.rst
-
-:anchor:`<a id="elementsTpm"/>`
-
-TPM device
-~~~~~~~~~~
-
-The TPM device enables a QEMU guest to have access to TPM functionality. The TPM
-device may either be a TPM 1.2 or a TPM 2.0.
-
-The TPM passthrough device type provides access to the host's TPM for one QEMU
-guest. No other software may be using the TPM device, typically /dev/tpm0, at
-the time the QEMU guest is started. :since:`'passthrough' since 1.0.5`
-
-Example: usage of the TPM passthrough device
-
-::
-
- ...
- <devices>
- <tpm model='tpm-tis'>
- <backend type='passthrough'>
- <device path='/dev/tpm0'/>
- </backend>
- </tpm>
- </devices>
- ...
-
-The emulator device type gives access to a TPM emulator providing TPM
-functionality for each VM. QEMU talks to it over a Unix socket. With the
-emulator device type each guest gets its own private TPM. :since:`'emulator'
-since 4.5.0` The state of the TPM emulator can be encrypted by providing an
-``encryption`` element. :since:`'encryption' since 5.6.0`
-
-Example: usage of the TPM Emulator
-
-::
-
- ...
- <devices>
- <tpm model='tpm-tis'>
- <backend type='emulator' version='2.0'>
- <encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/>
- </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
- for non-PPC64 architectures. :since:`Since 4.4.0` , another available choice
- is the ``tpm-crb``, which should only be used when the backend device is a
- TPM 2.0. :since:`Since 6.1.0` , pSeries guests on PPC64 are supported and the
- default is ``tpm-spapr``. :since:`Since 6.5.0` , a new model called
- ``spapr-tpm-proxy`` was added for pSeries guests. This model only works with
- the ``passthrough`` backend. It creates a TPM Proxy device that communicates
- with an existing TPM Resource Manager in the host, for example
- ``/dev/tpmrm0``, enabling the guest to run in secure virtual machine mode
- with the help of an Ultravisor. Adding a TPM Proxy to a pSeries guest brings
- no security benefits unless the guest is running on a PPC64 host that has an
- Ultravisor and a TPM Resource Manager. Only one TPM Proxy device is allowed
- per guest, but a TPM Proxy device can be added together with other TPM
- devices.
-
-``backend``
- The ``backend`` element specifies the type of TPM device. The following types
- are supported:
-
- ``passthrough``
- Use the host's TPM or TPM Resource Manager device.
-
- This backend type requires exclusive access to a TPM device on the host.
- An example for such a device is /dev/tpm0. The fully qualified file name
- is specified by path attribute of the ``source`` element. If no file name
- is specified then /dev/tpm0 is automatically used. :since:`Since 6.5.0` ,
- when choosing the ``spapr-tpm-proxy`` model, the file name specified is
- expected to be a TPM Resource Manager device, e.g. ``/dev/tpmrm0``.
-
- ``emulator``
- For this backend type the 'swtpm' TPM Emulator must be installed on the
- host. Libvirt will automatically start an independent TPM emulator for
- each QEMU guest requesting access to it.
-
-``version``
- The ``version`` attribute indicates the version of the TPM. By default a TPM
- 1.2 is created. This attribute only works with the ``emulator`` backend. The
- following versions are supported:
-
- - '1.2' : creates a TPM 1.2
- - '2.0' : creates a TPM 2.0
-
-``encryption``
- The ``encryption`` element allows the state of a TPM emulator to be
- encrypted. The ``secret`` must reference a secret object that holds the
- passphrase from which the encryption key will be derived.
+.. include:: formatdomain-devices-tpm.rst
:anchor:`<a id="elementsNVRAM"/>`
diff --git a/docs/meson.build b/docs/meson.build
index 43268be995..d99a85422b 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -143,6 +143,7 @@ docs_rst_files = [
'formatdomain-devices-watchdog.rst',
'formatdomain-devices-memballoon.rst',
'formatdomain-devices-rng.rst',
+ 'formatdomain-devices-tpm.rst',
]
},
{ 'name': 'hacking' },
--
2.26.2
More information about the libvir-list
mailing list