docs/formatsecret.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Secret XML format</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <h2><a name="SecretAttributes">Secret XML</a></h2>
  10
  11     <p>
  12       Secrets stored by libvirt may have attributes associated with them, using
  13       the <code>secret</code> element.  The <code>secret</code> element has two
  14       optional attributes, each with values '<code>yes</code>' and
  15       '<code>no</code>', and defaulting to '<code>no</code>':
  16     </p>
  17     <dl>
  18       <dt><code>ephemeral</code></dt>
  19       <dd>This secret must only be kept in memory, never stored persistently.
  20       </dd>
  21       <dt><code>private</code></dt>
  22       <dd>The value of the secret must not be revealed to any caller of libvirt,
  23         nor to any other node.
  24       </dd>
  25     </dl>
  26     <p>
  27       The top-level <code>secret</code> element may contain the following
  28       elements:
  29     </p>
  30     <dl>
  31       <dt><code>uuid</code></dt>
  32       <dd>
  33         An unique identifier for this secret (not necessarily in the UUID
  34         format).  If omitted when defining a new secret, a random UUID is
  35         generated.
  36       </dd>
  37       <dt><code>description</code></dt>
  38       <dd>A human-readable description of the purpose of the secret.
  39       </dd>
  40       <dt><code>usage</code></dt>
  41       <dd>
  42         Specifies what this secret is used for.  A mandatory
  43         <code>type</code> attribute specifies the usage category, currently
  44         only <code>volume</code>, <code>ceph</code> and <code>iscsi</code>
  45         are defined. Specific usage categories are described below.
  46       </dd>
  47     </dl>
  48
  49     <h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
  50
  51     <p>
  52       This secret is associated with a volume, and it is safe to delete the
  53       secret after the volume is deleted.  The <code>&lt;usage
  54       type='volume'&gt;</code> element must contain a
  55       single <code>volume</code> element that specifies the key of the volume
  56       this secret is associated with. For example, create a volume-secret.xml
  57       file as follows:
  58     </p>
  59
  60     <pre>
  61       &lt;secret ephemeral='no' private='yes'&gt;
  62          &lt;description&gt;Super secret name of my first puppy&lt;/description&gt;
  63          &lt;uuid&gt;0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f&lt;/uuid&gt;
  64          &lt;usage type='volume'&gt;
  65             &lt;volume&gt;/var/lib/libvirt/images/puppyname.img&lt;/volume&gt;
  66          &lt;/usage&gt;
  67       &lt;/secret&gt;
  68     </pre>
  69
  70     <p>
  71       Define the secret and set the pass phrase as follows:
  72     </p>
  73     <pre>
  74       # virsh secret-define volume-secret.xml
  75       Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
  76       #
  77       # MYSECRET=`printf %s "open sesame" | base64`
  78       # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
  79       Secret value set
  80       #
  81     </pre>
  82
  83     <p>
  84       The volume type secret can then be used in the XML for a storage volume
  85       <a href="formatstorageencryption.html">encryption</a> as follows:
  86     </p>
  87     <pre>
  88       &lt;encryption format='qcow'&gt;
  89         &lt;secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/&gt;
  90       &lt;/encryption&gt;
  91     </pre>
  92
  93     <h3><a name="CephUsageType">Usage type "ceph"</a></h3>
  94     <p>
  95       This secret is associated with a Ceph RBD (rados block device).
  96       The <code>&lt;usage type='ceph'&gt;</code> element must contain
  97       a single <code>name</code> element that specifies a usage name
  98       for the secret.  The Ceph secret can then be used by UUID or by
  99       this usage name via the <code>&lt;auth&gt;</code> element of
 100       a <a href="formatdomain.html#elementsDisks">disk device</a> or
 101       a <a href="formatstorage.html">storage pool (rbd)</a>.
 102       <span class="since">Since 0.9.7</span>. The following is an example
 103       of the steps to be taken.  First create a ceph-secret.xml file:
 104     </p>
 105
 106     <pre>
 107       &lt;secret ephemeral='no' private='yes'&gt;
 108          &lt;description&gt;CEPH passphrase example&lt;/description&gt;
 109          &lt;usage type='ceph'&gt;
 110             &lt;name&gt;ceph_example&lt;/name&gt;
 111          &lt;/usage&gt;
 112       &lt;/secret&gt;
 113     </pre>
 114
 115     <p>
 116       Next, use <code>virsh secret-define ceph-secret.xml</code> to define
 117       the secret and <code>virsh secret-set-value</code> using the generated
 118       UUID value and a base64 generated secret value in order to define the
 119       chosen secret pass phrase.
 120     </p>
 121     <pre>
 122       # virsh secret-define ceph-secret.xml
 123       Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
 124       #
 125       # virsh secret-list
 126       UUID                                 Usage
 127       -----------------------------------------------------------
 128       1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
 129       #
 130       # CEPHPHRASE=`printf %s "pass phrase" | base64`
 131       # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE
 132       Secret value set
 133
 134       #
 135     </pre>
 136
 137     <p>
 138       The ceph secret can then be used by UUID or by the
 139       usage name via the <code>&lt;auth&gt;</code> element in a domain's
 140       <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
 141       element as follows:
 142     </p>
 143     <pre>
 144       &lt;auth username='myname'&gt;
 145         &lt;secret type='ceph' usage='ceph_example'/&gt;
 146       &lt;/auth&gt;
 147     </pre>
 148
 149     <p>
 150       As well as the <code>&lt;auth&gt;</code> element in a
 151       <a href="formatstorage.html">storage pool (rbd)</a>
 152       <code>&lt;source&gt;</code> element as follows:
 153     </p>
 154     <pre>
 155       &lt;auth type='ceph' username='myname'&gt;
 156         &lt;secret usage='ceph_example'/&gt;
 157       &lt;/auth&gt;
 158     </pre>
 159
 160     <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3>
 161
 162     <p>
 163       This secret is associated with an iSCSI target for CHAP authentication.
 164       The <code>&lt;usage type='iscsi'&gt;</code> element must contain
 165       a single <code>target</code> element that specifies a usage name
 166       for the secret. The iSCSI secret can then be used by UUID or by
 167       this usage name via the <code>&lt;auth&gt;</code> element of
 168       a <a href="formatdomain.html#elementsDisks">disk device</a> or
 169       a <a href="formatstorage.html">storage pool (iscsi)</a>.
 170       <span class="since">Since 1.0.4</span>. The following is an example
 171       of the XML that may be used to generate a secret for iSCSI CHAP
 172       authentication. Assume the following sample entry in an iSCSI
 173       authentication file:
 174     </p>
 175       <pre>
 176       &lt;target iqn.2013-07.com.example:iscsi-pool&gt;
 177       backing-store /home/tgtd/iscsi-pool/disk1
 178       backing-store /home/tgtd/iscsi-pool/disk2
 179       incominguser myname mysecret
 180       &lt;/target&gt;
 181       </pre>
 182     <p>
 183       Define an iscsi-secret.xml file to describe the secret. Use the
 184       <code>incominguser</code> username used in your iSCSI authentication
 185       configuration file as the value for the <code>username</code> attribute.
 186       The <code>description</code> attribute should contain configuration
 187       specific data. The <code>target</code> name may be any name of your
 188       choosing to be used as the <code>usage</code> when used in the pool
 189       or disk XML description.
 190     </p>
 191     <pre>
 192       &lt;secret ephemeral='no' private='yes'&gt;
 193          &lt;description&gt;Passphrase for the iSCSI example.com server&lt;/description&gt;
 194          &lt;usage type='iscsi'&gt;
 195             &lt;target&gt;libvirtiscsi&lt;/target&gt;
 196          &lt;/usage&gt;
 197       &lt;/secret&gt;
 198     </pre>
 199
 200     <p>
 201       Next, use <code>virsh secret-define iscsi-secret.xml</code> to define
 202       the secret and <code>virsh secret-set-value</code> using the generated
 203       UUID value and a base64 generated secret value in order to define the
 204       chosen secret pass phrase.  The pass phrase must match the password
 205       used in the iSCSI authentication configuration file.
 206     </p>
 207     <pre>
 208       # virsh secret-define secret.xml
 209       Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
 210
 211       # virsh secret-list
 212       UUID                                 Usage
 213       -----------------------------------------------------------
 214       c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
 215
 216       # MYSECRET=`printf %s "mysecret" | base64`
 217       # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET
 218       Secret value set
 219       #
 220     </pre>
 221
 222     <p>
 223       The iSCSI secret can then be used by UUID or by the
 224       usage name via the <code>&lt;auth&gt;</code> element in a domain's
 225       <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
 226       element as follows:
 227     </p>
 228     <pre>
 229       &lt;auth username='myname'&gt;
 230         &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
 231       &lt;/auth&gt;
 232     </pre>
 233
 234     <p>
 235       As well as the <code>&lt;auth&gt;</code> element in a
 236       <a href="formatstorage.html">storage pool (iscsi)</a>
 237       <code>&lt;source&gt;</code> element as follows:
 238     </p>
 239     <pre>
 240       &lt;auth type='chap' username='myname'&gt;
 241         &lt;secret usage='libvirtiscsi'/&gt;
 242       &lt;/auth&gt;
 243     </pre>
 244   </body>
 245 </html>