[PATCH 26/32] docs: formatdomain-devices: Split out <tpm>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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