9:59 a.m.
Also update the link from 'formatstorageencryption' to the
'usage-type-volume' anchor.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatsecret.html.in | 414 ---------------------------
docs/formatsecret.rst | 337 ++++++++++++++++++++++
docs/formatstorageencryption.html.in | 2 +-
docs/meson.build | 2 +-
4 files changed, 339 insertions(+), 416 deletions(-)
delete mode 100644 docs/formatsecret.html.in
create mode 100644 docs/formatsecret.rst
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in
deleted file mode 100644
index 9dc9cdf288..0000000000
--- a/docs/formatsecret.html.in
+++ /dev/null
@@ -1,414 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Secret XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="SecretAttributes">Secret XML</a></h2>
-
- <p>
- Secrets stored by libvirt may have attributes associated with them, using
- the <code>secret</code> element. The <code>secret</code>
element has two
- optional attributes, each with values '<code>yes</code>' and
- '<code>no</code>', and defaulting to
'<code>no</code>':
- </p>
- <dl>
- <dt><code>ephemeral</code></dt>
- <dd>This secret must only be kept in memory, never stored persistently.
- </dd>
- <dt><code>private</code></dt>
- <dd>The value of the secret must not be revealed to any caller of libvirt,
- nor to any other node.
- </dd>
- </dl>
- <p>
- The top-level <code>secret</code> element may contain the following
- elements:
- </p>
- <dl>
- <dt><code>uuid</code></dt>
- <dd>
- An unique identifier for this secret (not necessarily in the UUID
- format). If omitted when defining a new secret, a random UUID is
- generated.
- </dd>
- <dt><code>description</code></dt>
- <dd>A human-readable description of the purpose of the secret.
- </dd>
- <dt><code>usage</code></dt>
- <dd>
- Specifies what this secret is used for. A mandatory
- <code>type</code> attribute specifies the usage category, currently
- only <code>volume</code>, <code>ceph</code>,
<code>iscsi</code>,
- <code>tls</code>, and <code>vtpm</code> are defined.
Specific usage
- categories are described below.
- </dd>
- </dl>
-
- <h3><a id="VolumeUsageType">Usage type
"volume"</a></h3>
-
- <p>
- This secret is associated with a volume, whether the format is either
- for a "luks" encrypted volume. Each volume will have a
- unique secret associated with it and it is safe to delete the
- secret after the volume is deleted. The
- <code><usage type='volume'></code> element must
contain a
- single <code>volume</code> element that specifies the path of the
volume
- this secret is associated with. For example, create a volume-secret.xml
- file as follows:
- </p>
-
- <pre>
-<secret ephemeral='no' private='yes'>
- <description>Super secret name of my first
puppy</description>
- <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid>
- <usage type='volume'>
- <volume>/var/lib/libvirt/images/puppyname.img</volume>
- </usage>
-</secret>
- </pre>
-
- <p>
- Define the secret and set the passphrase as follows:
- </p>
- <pre>
-# virsh secret-define volume-secret.xml
-Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
- </pre>
-
- <p>
- See <a href="#settingSecrets">virsh secret-set-value</a> on
how
- to set the value of the secret.
- </p>
-
- <p>
- The volume type secret can be supplied either in volume XML during
- creation of a <a href="formatstorage.html#StorageVol">storage
volume</a>
- in order to provide the passphrase to encrypt the volume or in
- domain XML <a href="formatdomain.html#elementsDisks">disk
device</a>
- in order to provide the passphrase to decrypt the volume,
- <span class="since">since 2.1.0</span>. An example follows:
- </p>
- <pre>
-# cat luks-secret.xml
-<secret ephemeral='no' private='yes'>
- <description>LUKS Sample Secret</description>
- <uuid>f52a81b2-424e-490c-823d-6bd4235bc57</uuid>
- <usage type='volume'>
-
<volume>/var/lib/libvirt/images/luks-sample.img</volume>
- </usage>
-</secret>
-
-# virsh secret-define luks-secret.xml
-Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
- </pre>
- <p>
- See <a href="#settingSecrets">virsh secret-set-value</a> on
how
- to set the value of the secret.
- </p>
-
- <p>
- The volume type secret can be supplied in domain XML for a luks storage
- volume <a href="formatstorageencryption.html">encryption</a>
as follows:
- </p>
- <pre>
-<encryption format='luks'>
- <secret type='passphrase'
uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/>
-</encryption>
- </pre>
-
- <h3><a id="CephUsageType">Usage type
"ceph"</a></h3>
- <p>
- This secret is associated with a Ceph RBD (rados block device).
- The <code><usage type='ceph'></code> element must
contain
- a single <code>name</code> element that specifies a usage name
- for the secret. The Ceph secret can then be used by UUID or by
- this usage name via the <code><auth></code> element of
- a <a href="formatdomain.html#elementsDisks">disk device</a>
or
- a <a href="formatstorage.html">storage pool (rbd)</a>.
- <span class="since">Since 0.9.7</span>. The following is an
example
- of the steps to be taken. First create a ceph-secret.xml file:
- </p>
-
- <pre>
-<secret ephemeral='no' private='yes'>
- <description>CEPH passphrase example</description>
- <usage type='ceph'>
- <name>ceph_example</name>
- </usage>
-</secret>
- </pre>
-
- <p>
- Next, use <code>virsh secret-define ceph-secret.xml</code> to define
- the secret and <code>virsh secret-set-value</code> using the generated
- UUID value and a base64 generated secret value in order to define the
- chosen secret pass phrase.
- </p>
- <pre>
-# virsh secret-define ceph-secret.xml
-Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
-#
-# virsh secret-list
- UUID Usage
------------------------------------------------------------
- 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
- </pre>
- <p>
- See <a href="#settingSecrets">virsh secret-set-value</a> on
how
- to set the value of the secret.
- </p>
-
- <p>
- The ceph secret can then be used by UUID or by the
- usage name via the <code><auth></code> element in a
domain's
- <a
href="formatdomain.html#elementsDisks"><code><disk></code></a>
- element as follows:
- </p>
- <pre>
-<auth username='myname'>
- <secret type='ceph' usage='ceph_example'/>
-</auth>
- </pre>
-
- <p>
- As well as the <code><auth></code> element in a
- <a href="formatstorage.html">storage pool (rbd)</a>
- <code><source></code> element as follows:
- </p>
- <pre>
-<auth type='ceph' username='myname'>
- <secret usage='ceph_example'/>
-</auth>
- </pre>
-
- <h3><a id="iSCSIUsageType">Usage type
"iscsi"</a></h3>
-
- <p>
- This secret is associated with an iSCSI target for CHAP authentication.
- The <code><usage type='iscsi'></code> element
must contain
- a single <code>target</code> element that specifies a usage name
- for the secret. The iSCSI secret can then be used by UUID or by
- this usage name via the <code><auth></code> element of
- a <a href="formatdomain.html#elementsDisks">disk device</a>
or
- a <a href="formatstorage.html">storage pool (iscsi)</a>.
- <span class="since">Since 1.0.4</span>. The following is an
example
- of the XML that may be used to generate a secret for iSCSI CHAP
- authentication. Assume the following sample entry in an iSCSI
- authentication file:
- </p>
- <pre>
-<target iqn.2013-07.com.example:iscsi-pool>
-backing-store /home/tgtd/iscsi-pool/disk1
-backing-store /home/tgtd/iscsi-pool/disk2
-incominguser myname mysecret
-</target>
- </pre>
- <p>
- Define an iscsi-secret.xml file to describe the secret. Use the
- <code>incominguser</code> username used in your iSCSI authentication
- configuration file as the value for the <code>username</code>
attribute.
- The <code>description</code> attribute should contain configuration
- specific data. The <code>target</code> name may be any name of your
- choosing to be used as the <code>usage</code> when used in the pool
- or disk XML description.
- </p>
- <pre>
-<secret ephemeral='no' private='yes'>
- <description>Passphrase for the iSCSI example.com
server</description>
- <usage type='iscsi'>
- <target>libvirtiscsi</target>
- </usage>
-</secret>
- </pre>
-
- <p>
- Next, use <code>virsh secret-define iscsi-secret.xml</code> to define
- the secret and
- <code><a href="#settingSecrets">virsh
secret-set-value</a></code>
- using the generated
- UUID value and a base64 generated secret value in order to define the
- chosen secret pass phrase. The pass phrase must match the password
- used in the iSCSI authentication configuration file.
- </p>
- <pre>
-# virsh secret-define secret.xml
-Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
-
-# virsh secret-list
- UUID Usage
------------------------------------------------------------
- c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
-
- </pre>
-
- <p>
- See <a href="#settingSecrets">virsh secret-set-value</a> on
how
- to set the value of the secret.
- </p>
-
- <p>
- The iSCSI secret can then be used by UUID or by the
- usage name via the <code><auth></code> element in a
domain's
- <a
href="formatdomain.html#elementsDisks"><code><disk></code></a>
- element as follows:
- </p>
- <pre>
-<auth username='myname'>
- <secret type='iscsi' usage='libvirtiscsi'/>
-</auth>
- </pre>
-
- <p>
- As well as the <code><auth></code> element in a
- <a href="formatstorage.html">storage pool (iscsi)</a>
- <code><source></code> element as follows:
- </p>
- <pre>
-<auth type='chap' username='myname'>
- <secret usage='libvirtiscsi'/>
-</auth>
- </pre>
-
- <h3><a id="tlsUsageType">Usage type
"tls"</a></h3>
-
- <p>
- This secret may be used in order to provide the passphrase for the
- private key used to provide TLS credentials.
- The <code><usage type='tls'></code> element must
contain a
- single <code>name</code> element that specifies a usage name
- for the secret.
- <span class="since">Since 2.3.0</span>.
- The following is an example of the expected XML and processing to
- define the secret:
- </p>
-
- <pre>
-# cat tls-secret.xml
-<secret ephemeral='no' private='yes'>
- <description>sample tls secret</description>
- <usage type='tls'>
- <name>TLS_example</name>
- </usage>
-</secret>
-
-# virsh secret-define tls-secret.xml
-Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
-
-# virsh secret-list
- UUID Usage
------------------------------------------------------------
- 718c71bd-67b5-4a2b-87ec-a24e8ca200dc tls TLS_example
-#
-
- </pre>
-
- <p>
- A secret may also be defined via the
- <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
- <code>virSecretDefineXML</code></a> API.
-
- Once the secret is defined, a secret value will need to be set. The
- secret would be the passphrase used to access the TLS credentials.
- The following is a simple example of using
- <code><a href="#settingSecrets">virsh
secret-set-value</a></code> to set
- the secret value. The
- <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
- <code>virSecretSetValue</code></a> API may also be used to set
- a more secure secret without using printable/readable characters.
- </p>
-
- <h3><a id="vTPMUsageType">Usage type
"vtpm"</a></h3>
-
- <p>
- This secret is associated with a virtualized TPM (vTPM) and serves
- as a passphrase for deriving a key from for encrypting the state
- of the vTPM.
- The <code><usage type='vtpm'></code> element must
contain
- a single <code>name</code> element that specifies a usage name
- for the secret. The vTPM secret can then be used by UUID
- via the <code><encryption></code> element of
- a <a href="formatdomain.html#elementsTpm">tpm</a> when using
an
- emulator.
- <span class="since">Since 5.6.0</span>. The following is an
example
- of the steps to be taken. First create a vtpm-secret.xml file: </p>
-
- <pre>
-# cat vtpm-secret.xml
-<secret ephemeral='no' private='yes'>
- <description>sample vTPM secret</description>
- <usage type='vtpm'>
- <name>VTPM_example</name>
- </usage>
-</secret>
-
-# virsh secret-define vtpm-secret.xml
-Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
-
-# virsh secret-list
- UUID Usage
-----------------------------------------------------------------------------------------
- 6dd3e4a5-1d76-44ce-961f-f119f5aad935 vtpm VTPM_example
-
-#
-
- </pre>
-
- <p>
- A secret may also be defined via the
- <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
- <code>virSecretDefineXML</code></a> API.
-
- Once the secret is defined, a secret value will need to be set. The
- secret would be the passphrase used to decrypt the vTPM state.
- The following is a simple example of using
- <code><a href="#settingSecrets">virsh
secret-set-value</a></code>
- to set the secret value. The
- <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
- <code>virSecretSetValue</code></a> API may also be used to set
- a more secure secret without using printable/readable characters.
- </p>
-
- <h2><a id="settingSecrets">Setting secret values in
virsh</a></h2>
-
- <p>
- To set the value of the secret you can use the following virsh commands.
- If the secret is a password-like string (printable characters, no newline)
- you can use:
- </p>
- <pre>
-# virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935
-Enter new value for secret:
-Secret value set
- </pre>
-
- <p>
- Another secure option is to read the secret from a file. This way the
- secret can contain any bytes (even NUL and non-printable characters). The
- length of the secret is the length of the input file. Alternatively the
- <code>--plain</code> option can be omitted if the file contents are
- base64-encoded.
- </p>
-
- <pre>
-# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain
secretinfile
-Secret value set
- </pre>
-
- <p>
- <b>WARNING</b> The following approach is <b>insecure</b>
and deprecated.
- The secret can also be set via an argument. Note that other users may see
- the actual secret in the process listing!
- The secret must be base64 encoded.
- </p>
-
- <pre>
-# MYSECRET=`printf %s "open sesame" | base64`
-# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
-Secret value set
- </pre>
-
- </body>
-</html>
diff --git a/docs/formatsecret.rst b/docs/formatsecret.rst
new file mode 100644
index 0000000000..a3ffb7c4b9
--- /dev/null
+++ b/docs/formatsecret.rst
@@ -0,0 +1,337 @@
+.. role:: since
+
+=================
+Secret XML format
+=================
+
+.. contents::
+
+Secret XML
+----------
+
+Secrets stored by libvirt may have attributes associated with them, using the
+``secret`` element. The ``secret`` element has two optional attributes, each
+with values '``yes``' and '``no``', and defaulting to '``no``':
+
+``ephemeral``
+ This secret must only be kept in memory, never stored persistently.
+``private``
+ The value of the secret must not be revealed to any caller of libvirt, nor to
+ any other node.
+
+The top-level ``secret`` element may contain the following elements:
+
+``uuid``
+ An unique identifier for this secret (not necessarily in the UUID format). If
+ omitted when defining a new secret, a random UUID is generated.
+``description``
+ A human-readable description of the purpose of the secret.
+``usage``
+ Specifies what this secret is used for. A mandatory ``type`` attribute
+ specifies the usage category, currently only ``volume``, ``ceph``, ``iscsi``,
+ ``tls``, and ``vtpm`` are defined. Specific usage categories are described
+ below.
+
+Usage type "volume"
+~~~~~~~~~~~~~~~~~~~
+
+This secret is associated with a volume, whether the format is either for a
+"luks" encrypted volume. Each volume will have a unique secret associated with
+it and it is safe to delete the secret after the volume is deleted. The
+``<usage type='volume'>`` element must contain a single ``volume`` element
that
+specifies the path of the volume this secret is associated with. For example,
+create a volume-secret.xml file as follows:
+
+::
+
+ <secret ephemeral='no' private='yes'>
+ <description>Super secret name of my first puppy</description>
+ <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid>
+ <usage type='volume'>
+ <volume>/var/lib/libvirt/images/puppyname.img</volume>
+ </usage>
+ </secret>
+
+Define the secret and set the passphrase as follows:
+
+::
+
+ # virsh secret-define volume-secret.xml
+ Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The volume type secret can be supplied either in volume XML during creation of a
+`storage volume <formatstorage.html#StorageVol>`__ in order to provide the
+passphrase to encrypt the volume or in domain XML `disk
+device <formatdomain.html#elementsDisks>`__ in order to provide the passphrase
+to decrypt the volume, :since:`since 2.1.0` . An example follows:
+
+::
+
+ # cat luks-secret.xml
+ <secret ephemeral='no' private='yes'>
+ <description>LUKS Sample Secret</description>
+ <uuid>f52a81b2-424e-490c-823d-6bd4235bc57</uuid>
+ <usage type='volume'>
+ <volume>/var/lib/libvirt/images/luks-sample.img</volume>
+ </usage>
+ </secret>
+
+ # virsh secret-define luks-secret.xml
+ Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The volume type secret can be supplied in domain XML for a luks storage volume
+`encryption <formatstorageencryption.html>`__ as follows:
+
+::
+
+ <encryption format='luks'>
+ <secret type='passphrase'
uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/>
+ </encryption>
+
+Usage type "ceph"
+~~~~~~~~~~~~~~~~~
+
+This secret is associated with a Ceph RBD (rados block device). The
+``<usage type='ceph'>`` element must contain a single ``name`` element
that
+specifies a usage name for the secret. The Ceph secret can then be used by UUID
+or by this usage name via the ``<auth>`` element of a `disk
+device <formatdomain.html#elementsDisks>`__ or a `storage pool
+(rbd) <formatstorage.html>`__. :since:`Since 0.9.7` . The following is an
+example of the steps to be taken. First create a ceph-secret.xml file:
+
+::
+
+ <secret ephemeral='no' private='yes'>
+ <description>CEPH passphrase example</description>
+ <usage type='ceph'>
+ <name>ceph_example</name>
+ </usage>
+ </secret>
+
+Next, use ``virsh secret-define ceph-secret.xml`` to define the secret and
+``virsh secret-set-value`` using the generated UUID value and a base64 generated
+secret value in order to define the chosen secret pass phrase.
+
+::
+
+ # virsh secret-define ceph-secret.xml
+ Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
+ #
+ # virsh secret-list
+ UUID Usage
+ -----------------------------------------------------------
+ 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The ceph secret can then be used by UUID or by the usage name via the ``<auth>``
+element in a domain's `<disk> <formatdomain.html#elementsDisks>`__
element as
+follows:
+
+::
+
+ <auth username='myname'>
+ <secret type='ceph' usage='ceph_example'/>
+ </auth>
+
+As well as the ``<auth>`` element in a `storage pool
+(rbd) <formatstorage.html>`__ ``<source>`` element as follows:
+
+::
+
+ <auth type='ceph' username='myname'>
+ <secret usage='ceph_example'/>
+ </auth>
+
+Usage type "iscsi"
+~~~~~~~~~~~~~~~~~~
+
+This secret is associated with an iSCSI target for CHAP authentication. The
+``<usage type='iscsi'>`` element must contain a single ``target`` element
that
+specifies a usage name for the secret. The iSCSI secret can then be used by UUID
+or by this usage name via the ``<auth>`` element of a `disk
+device <formatdomain.html#elementsDisks>`__ or a `storage pool
+(iscsi) <formatstorage.html>`__. :since:`Since 1.0.4` . The following is an
+example of the XML that may be used to generate a secret for iSCSI CHAP
+authentication. Assume the following sample entry in an iSCSI authentication
+file:
+
+::
+
+ <target iqn.2013-07.com.example:iscsi-pool>
+ backing-store /home/tgtd/iscsi-pool/disk1
+ backing-store /home/tgtd/iscsi-pool/disk2
+ incominguser myname mysecret
+ </target>
+
+Define an iscsi-secret.xml file to describe the secret. Use the ``incominguser``
+username used in your iSCSI authentication configuration file as the value for
+the ``username`` attribute. The ``description`` attribute should contain
+configuration specific data. The ``target`` name may be any name of your
+choosing to be used as the ``usage`` when used in the pool or disk XML
+description.
+
+::
+
+ <secret ephemeral='no' private='yes'>
+ <description>Passphrase for the iSCSI example.com server</description>
+ <usage type='iscsi'>
+ <target>libvirtiscsi</target>
+ </usage>
+ </secret>
+
+Next, use ``virsh secret-define iscsi-secret.xml`` to define the secret and
+``virsh secret-set-value`` using the generated UUID value and a base64 generated
+secret value in order to define the chosen secret pass phrase. The pass phrase
+must match the password used in the iSCSI authentication configuration file.
+
+::
+
+ # virsh secret-define secret.xml
+ Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
+
+ # virsh secret-list
+ UUID Usage
+ -----------------------------------------------------------
+ c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
+
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The iSCSI secret can then be used by UUID or by the usage name via the
+``<auth>`` element in a domain's `<disk>
<formatdomain.html#elementsDisks>`__
+element as follows:
+
+::
+
+ <auth username='myname'>
+ <secret type='iscsi' usage='libvirtiscsi'/>
+ </auth>
+
+As well as the ``<auth>`` element in a `storage pool
+(iscsi) <formatstorage.html>`__ ``<source>`` element as follows:
+
+::
+
+ <auth type='chap' username='myname'>
+ <secret usage='libvirtiscsi'/>
+ </auth>
+
+Usage type "tls"
+~~~~~~~~~~~~~~~~
+
+This secret may be used in order to provide the passphrase for the private key
+used to provide TLS credentials. The ``<usage type='tls'>`` element must
contain
+a single ``name`` element that specifies a usage name for the secret.
+:since:`Since 2.3.0` . The following is an example of the expected XML and
+processing to define the secret:
+
+::
+
+ # cat tls-secret.xml
+ <secret ephemeral='no' private='yes'>
+ <description>sample tls secret</description>
+ <usage type='tls'>
+ <name>TLS_example</name>
+ </usage>
+ </secret>
+
+ # virsh secret-define tls-secret.xml
+ Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
+
+ # virsh secret-list
+ UUID Usage
+ -----------------------------------------------------------
+ 718c71bd-67b5-4a2b-87ec-a24e8ca200dc tls TLS_example
+ #
+
+
+A secret may also be defined via the
+`virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__
+API. Once the secret is defined, a secret value will need to be set. The secret
+would be the passphrase used to access the TLS credentials. The following is a
+simple example of using ``virsh secret-set-value`` to set the secret value. The
+`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API
+may also be used to set a more secure secret without using printable/readable
+characters.
+
+Usage type "vtpm"
+~~~~~~~~~~~~~~~~~
+
+This secret is associated with a virtualized TPM (vTPM) and serves as a
+passphrase for deriving a key from for encrypting the state of the vTPM. The
+``<usage type='vtpm'>`` element must contain a single ``name`` element
that
+specifies a usage name for the secret. The vTPM secret can then be used by UUID
+via the ``<encryption>`` element of a `tpm
<formatdomain.html#elementsTpm>`__
+when using an emulator. :since:`Since 5.6.0` . The following is an example of
+the steps to be taken. First create a vtpm-secret.xml file:
+
+::
+
+ # cat vtpm-secret.xml
+ <secret ephemeral='no' private='yes'>
+ <description>sample vTPM secret</description>
+ <usage type='vtpm'>
+ <name>VTPM_example</name>
+ </usage>
+ </secret>
+
+ # virsh secret-define vtpm-secret.xml
+ Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
+
+ # virsh secret-list
+ UUID Usage
+
----------------------------------------------------------------------------------------
+ 6dd3e4a5-1d76-44ce-961f-f119f5aad935 vtpm VTPM_example
+
+ #
+
+
+A secret may also be defined via the
+`virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__
+API. Once the secret is defined, a secret value will need to be set. The secret
+would be the passphrase used to decrypt the vTPM state. The following is a
+simple example of using ``virsh secret-set-value`` to set the secret value. The
+`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API
+may also be used to set a more secure secret without using printable/readable
+characters.
+
+Setting secret values in virsh
+------------------------------
+
+To set the value of the secret you can use the following virsh commands. If the
+secret is a password-like string (printable characters, no newline) you can use:
+
+::
+
+ # virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935
+ Enter new value for secret:
+ Secret value set
+
+Another secure option is to read the secret from a file. This way the secret can
+contain any bytes (even NUL and non-printable characters). The length of the
+secret is the length of the input file. Alternatively the ``--plain`` option can
+be omitted if the file contents are base64-encoded.
+
+::
+
+ # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain
secretinfile
+ Secret value set
+
+**WARNING** The following approach is **insecure** and deprecated. The secret
+can also be set via an argument. Note that other users may see the actual secret
+in the process listing! The secret must be base64 encoded.
+
+::
+
+ # MYSECRET=`printf %s "open sesame" | base64`
+ # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
+ Secret value set
diff --git a/docs/formatstorageencryption.html.in b/docs/formatstorageencryption.html.in
index c8c9f08d1e..395a7269b1 100644
--- a/docs/formatstorageencryption.html.in
+++ b/docs/formatstorageencryption.html.in
@@ -143,7 +143,7 @@
<h2><a id="example">Examples</a></h2>
<p>
- Assuming a <a href="formatsecret.html#VolumeUsageType">
+ Assuming a <a href="formatsecret.html#usage-type-volume">
<code>luks volume type secret</code></a> is already defined,
a simple example specifying use of the <code>luks</code> format
for either volume creation without a specific cipher being defined or
diff --git a/docs/meson.build b/docs/meson.build
index fce6533301..f614bcadeb 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -46,7 +46,6 @@ docs_html_in_files = [
'formatnetworkport',
'formatnode',
'formatnwfilter',
- 'formatsecret',
'formatstoragecaps',
'formatstorageencryption',
'hooks',
@@ -93,6 +92,7 @@ docs_rst_files = [
'formatbackup',
'formatcheckpoint',
'formatdomain',
+ 'formatsecret',
'formatsnapshot',
'formatstorage',
'glib-adoption',
--
2.35.1