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><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
