<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <!-- This file is autogenerated from formatsecret.html.in Do not edit this file. Changes will be lost. --> <!-- This page was generated at Mon Nov 13 21:46:26 UTC 2017. --> <head> <meta charset="UTF-8"/> <meta name="viewport" content="width=device-width, initial-scale=1"/> <link rel="stylesheet" type="text/css" href="main.css"/> <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"/> <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/> <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/> <link rel="manifest" href="/manifest.json"/> <meta name="theme-color" content="#ffffff"/> <title>libvirt: Secret XML format</title> <meta name="description" content="libvirt, virtualization, virtualization API"/> <script type="text/javascript"> <!-- function init() { window.addEventListener('scroll', function(e){ var distanceY = window.pageYOffset || document.documentElement.scrollTop, shrinkOn = 94 home = document.getElementById("home"); links = document.getElementById("jumplinks"); search = document.getElementById("search"); body = document.getElementById("body"); if (distanceY > shrinkOn) { if (home.className != "navhide") { body.className = "navhide" home.className = "navhide" links.className = "navhide" search.className = "navhide" } } else { if (home.className == "navhide") { body.className = "" home.className = "" links.className = "" search.className = "" } } }); } window.onload = init(); --> </script> </head> <body> <div id="body"> <div id="content"> <h1>Secret XML format</h1> <ul> <li> <a href="#SecretAttributes">Secret XML</a> <ul> <li> <a href="#VolumeUsageType">Usage type "volume"</a> </li> <li> <a href="#CephUsageType">Usage type "ceph"</a> </li> <li> <a href="#iSCSIUsageType">Usage type "iscsi"</a> </li> <li> <a href="#tlsUsageType">Usage type "tls"</a> </li> </ul> </li> </ul> <h2> <a id="SecretAttributes">Secret XML</a> <a class="headerlink" href="#SecretAttributes" title="Permalink to this headline">¶</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> <a class="headerlink" href="#VolumeUsageType" title="Permalink to this headline">¶</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> <a class="headerlink" href="#CephUsageType" title="Permalink to this headline">¶</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> <a class="headerlink" href="#iSCSIUsageType" title="Permalink to this headline">¶</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> <a class="headerlink" href="#tlsUsageType" title="Permalink to this headline">¶</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> </div> </div> <div id="nav"> <div id="home"> <a href="index.html">Home</a> </div> <div id="jumplinks"> <ul> <li> <a href="downloads.html">Download</a> </li> <li> <a href="contribute.html">Contribute</a> </li> <li> <a href="docs.html">Docs</a> </li> </ul> </div> <div id="search"> <form action="search.php" enctype="application/x-www-form-urlencoded" method="get"> <div> <input name="query" type="text" size="12" value=""/> <input name="submit" type="submit" value="Go"/> </div> </form> </div> </div> <div id="footer"> <div id="contact"> <h3>Contact</h3> <ul> <li> <a href="contact.html#email">email</a> </li> <li> <a href="contact.html#irc">irc</a> </li> </ul> </div> <div id="community"> <h3>Community</h3> <ul> <li> <a href="https://twitter.com/hashtag/libvirt">twitter</a> </li> <li> <a href="https://plus.google.com/communities/109522598353007505282">google+</a> </li> <li> <a href="http://stackoverflow.com/questions/tagged/libvirt">stackoverflow</a> </li> <li> <a href="http://serverfault.com/questions/tagged/libvirt">serverfault</a> </li> </ul> </div> <div id="conduct"> Participants in the libvirt project agree to abide by <a href="governance.html#codeofconduct">the project code of conduct</a></div> <br class="clear"/> </div> </body> </html>