[PATCH 15/17] docs: Convert 'formatsecret' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Also update the link from 'formatstorageencryption' to the
'usage-type-volume' anchor.

Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 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>&lt;usage type='volume'&gt;</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>
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;Super secret name of my first puppy&lt;/description&gt;
-   &lt;uuid&gt;0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f&lt;/uuid&gt;
-   &lt;usage type='volume'&gt;
-      &lt;volume&gt;/var/lib/libvirt/images/puppyname.img&lt;/volume&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-    </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
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;LUKS Sample Secret&lt;/description&gt;
-   &lt;uuid&gt;f52a81b2-424e-490c-823d-6bd4235bc57&lt;/uuid&gt;
-   &lt;usage type='volume'&gt;
-      &lt;volume&gt;/var/lib/libvirt/images/luks-sample.img&lt;/volume&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-
-# 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>
-&lt;encryption format='luks'&gt;
-  &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/&gt;
-&lt;/encryption&gt;
-    </pre>
-
-    <h3><a id="CephUsageType">Usage type "ceph"</a></h3>
-    <p>
-      This secret is associated with a Ceph RBD (rados block device).
-      The <code>&lt;usage type='ceph'&gt;</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>&lt;auth&gt;</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>
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;CEPH passphrase example&lt;/description&gt;
-   &lt;usage type='ceph'&gt;
-      &lt;name&gt;ceph_example&lt;/name&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-    </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>&lt;auth&gt;</code> element in a domain's
-      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
-      element as follows:
-    </p>
-    <pre>
-&lt;auth username='myname'&gt;
-  &lt;secret type='ceph' usage='ceph_example'/&gt;
-&lt;/auth&gt;
-    </pre>
-
-    <p>
-      As well as the <code>&lt;auth&gt;</code> element in a
-      <a href="formatstorage.html">storage pool (rbd)</a>
-      <code>&lt;source&gt;</code> element as follows:
-    </p>
-    <pre>
-&lt;auth type='ceph' username='myname'&gt;
-  &lt;secret usage='ceph_example'/&gt;
-&lt;/auth&gt;
-    </pre>
-
-    <h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3>
-
-    <p>
-      This secret is associated with an iSCSI target for CHAP authentication.
-      The <code>&lt;usage type='iscsi'&gt;</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>&lt;auth&gt;</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>
-&lt;target iqn.2013-07.com.example:iscsi-pool&gt;
-backing-store /home/tgtd/iscsi-pool/disk1
-backing-store /home/tgtd/iscsi-pool/disk2
-incominguser myname mysecret
-&lt;/target&gt;
-      </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>
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;Passphrase for the iSCSI example.com server&lt;/description&gt;
-   &lt;usage type='iscsi'&gt;
-      &lt;target&gt;libvirtiscsi&lt;/target&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-    </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>&lt;auth&gt;</code> element in a domain's
-      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
-      element as follows:
-    </p>
-    <pre>
-&lt;auth username='myname'&gt;
-  &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
-&lt;/auth&gt;
-    </pre>
-
-    <p>
-      As well as the <code>&lt;auth&gt;</code> element in a
-      <a href="formatstorage.html">storage pool (iscsi)</a>
-      <code>&lt;source&gt;</code> element as follows:
-    </p>
-    <pre>
-&lt;auth type='chap' username='myname'&gt;
-  &lt;secret usage='libvirtiscsi'/&gt;
-&lt;/auth&gt;
-    </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>&lt;usage type='tls'&gt;</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
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;sample tls secret&lt;/description&gt;
-   &lt;usage type='tls'&gt;
-      &lt;name&gt;TLS_example&lt;/name&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-
-# 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>&lt;usage type='vtpm'&gt;</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>&lt;encryption&gt;</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
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;sample vTPM secret&lt;/description&gt;
-   &lt;usage type='vtpm'&gt;
-      &lt;name&gt;VTPM_example&lt;/name&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-
-# 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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux