docs/formatstorageencryption.html.in


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

<html>
  <body>
    <h1>Storage volume encryption XML format</h1>

    <ul id="toc"></ul>

    <h2><a name="StorageEncryption">Storage volume encryption XML</a></h2>

    <p>
      Storage volumes may be encrypted, the XML snippet described below is used
      to represent the details of the encryption.  It can be used as a part
      of a domain or storage configuration.
    </p>
    <p>
      The top-level tag of volume encryption specification
      is <code>encryption</code>, with a mandatory
      attribute <code>format</code>.  Currently defined values
      of <code>format</code> are <code>default</code> and <code>qcow</code>.
      Each value of <code>format</code> implies some expectations about the
      content of the <code>encryption</code> tag.  Other format values may be
      defined in the future.
    </p>
    <p>
      The <code>encryption</code> tag can currently contain a sequence of
      <code>secret</code> tags, each with mandatory attributes <code>type</code>
      and <code>uuid</code>.  The only currently defined value of
      <code>type</code> is <code>passphrase</code>.  <code>uuid</code>
      refers to a secret known to libvirt.  libvirt can use a secret value
      previously set using <code>virSecretSetValue()</code>, or, if supported
      by the particular volume format and driver, automatically generate a
      secret value at the time of volume creation, and store it using the
      specified <code>uuid</code>.
    </p>
    <h3><a name="StorageEncryptionDefault">"default" format</a></h3>
    <p>
      <code>&lt;encryption type="default"/&gt;</code> can be specified only
      when creating a volume.  If the volume is successfully created, the
      encryption formats, parameters and secrets will be auto-generated by
      libvirt and the attached <code>encryption</code> tag will be updated.
      The unmodified contents of the <code>encryption</code> tag can be used
      in later operations with the volume, or when setting up a domain that
      uses the volume.
    </p>
    <h3><a name="StorageEncryptionQcow">"qcow" format</a></h3>
    <p>
      The <code>qcow</code> format specifies that the built-in encryption
      support in <code>qcow</code>- or <code>qcow2</code>-formatted volume
      images should be used.  A single
      <code>&lt;secret type='passphrase'&gt;</code> element is expected.  If
      the <code>secret</code> element is not present during volume creation,
      a secret is automatically generated and attached to the volume.
    </p>

    <h2><a name="example">Example</a></h2>

    <p>
      Here is a simple example, specifying use of the <code>qcow</code> format:
    </p>

    <pre>
      &lt;encryption format='qcow'&gt;
         &lt;secret type='passphrase' uuid='c1f11a6d-8c5d-4a3e-ac7a-4e171c5e0d4a' /&gt;
      &lt;/encryption&gt;</pre>
  </body>
</html>