<?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>, and <code>tls</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 "qcow" or 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 # # MYSECRET=`printf %s "open sesame" | base64` # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET Secret value set # </pre> <p> The volume type secret can be supplied in domain XML for a qcow storage volume <a href="formatstorageencryption.html">encryption</a> as follows: </p> <pre> <encryption format='qcow'> <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/> </encryption> </pre> <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 # # MYSECRET=`printf %s "letmein" | base64` # virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET Secret value set # </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 # # CEPHPHRASE=`printf %s "pass phrase" | base64` # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE Secret value set # </pre> <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>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. 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 # MYSECRET=`printf %s "mysecret" | base64` # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET Secret value set # </pre> <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>virsh secret-set-value</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> <pre> # MYSECRET=`printf %s "letmein" | base64` # virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET Secret value set </pre> </body> </html>