mirror of https://gitee.com/openkylin/libvirt.git
docs: Update docs to reflect LUKS secret changes
Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
This commit is contained in:
John Ferlan
parent
a8d0afc75a
commit
a6bab5c343
|
|
@ -41,19 +41,20 @@
|
|||
<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>passphrase</code> are defined. Specific usage categories
|
||||
are described below.
|
||||
only <code>volume</code>, <code>ceph</code>, and <code>iscsi</code>
|
||||
are defined. Specific usage categories are described below.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
|
||||
|
||||
<p>
|
||||
This secret is associated with a volume, 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 key of the volume
|
||||
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>
|
||||
|
|
@ -69,7 +70,7 @@
|
|||
</pre>
|
||||
|
||||
<p>
|
||||
Define the secret and set the pass phrase as follows:
|
||||
Define the secret and set the passphrase as follows:
|
||||
</p>
|
||||
<pre>
|
||||
# virsh secret-define volume-secret.xml
|
||||
|
|
@ -82,8 +83,8 @@
|
|||
</pre>
|
||||
|
||||
<p>
|
||||
The volume type secret can then be used in the XML for a storage volume
|
||||
<a href="formatstorageencryption.html">encryption</a> as follows:
|
||||
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'>
|
||||
|
|
@ -91,6 +92,33 @@
|
|||
</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 name="CephUsageType">Usage type "ceph"</a></h3>
|
||||
<p>
|
||||
This secret is associated with a Ceph RBD (rados block device).
|
||||
|
|
@ -243,61 +271,5 @@
|
|||
</auth>
|
||||
</pre>
|
||||
|
||||
<h3><a name="passphraseUsageType">Usage type "passphrase"</a></h3>
|
||||
|
||||
<p>
|
||||
This secret is a general purpose secret to be used by various libvirt
|
||||
objects to provide a single passphrase as required by the object in
|
||||
order to perform its authentication. For example, this secret will
|
||||
be used either by the
|
||||
<a href="formatstorage.html#StorageVol">storage volume</a> in order to
|
||||
provide the passphrase to encrypt a luks volume or by the
|
||||
<a href="formatdomain.html#elementsDisks">disk device</a> in order to
|
||||
provide the passphrase to decrypt the luks volume for usage.
|
||||
<span class="since">Since 2.1.0</span>. The following is an example
|
||||
of a secret.xml file:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
# cat secret.xml
|
||||
<secret ephemeral='no' private='yes'>
|
||||
<description>sample passphrase secret</description>
|
||||
<usage type='passphrase'>
|
||||
<name>name_example</name>
|
||||
</usage>
|
||||
</secret>
|
||||
|
||||
# virsh secret-define secret.xml
|
||||
Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
|
||||
|
||||
# virsh secret-list
|
||||
UUID Usage
|
||||
-----------------------------------------------------------
|
||||
718c71bd-67b5-4a2b-87ec-a24e8ca200dc passphrase name_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. This
|
||||
value would be the same used to create and use the volume.
|
||||
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>
|
||||
|
|
|
|||
|
|
@ -752,5 +752,21 @@
|
|||
</permissions>
|
||||
</target>
|
||||
</volume></pre>
|
||||
|
||||
<h3><a name="exampleLuks">Storage volume using LUKS</a></h3>
|
||||
|
||||
<pre>
|
||||
<volume>
|
||||
<name>MyLuks.img</name>
|
||||
<capacity unit="G">5</capacity>
|
||||
<target>
|
||||
<path>/var/lib/virt/images/MyLuks.img</path>
|
||||
<format type='luks'/>
|
||||
<encryption format='luks'>
|
||||
<secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
|
||||
</encryption>
|
||||
</target>
|
||||
</volume>
|
||||
</pre>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -27,9 +27,9 @@
|
|||
<code>secret</code> tags, each with mandatory attributes <code>type</code>
|
||||
and either <code>uuid</code> or <code>usage</code>
|
||||
(<span class="since">since 2.1.0</span>). The only currently defined
|
||||
value of <code>type</code> is <code>passphrase</code>. The
|
||||
value of <code>type</code> is <code>volume</code>. The
|
||||
<code>uuid</code> is "uuid" of the <code>secret</code> while
|
||||
<code>usage</code> is the value "usage" subelement field.
|
||||
<code>usage</code> is the "usage" subelement field.
|
||||
A secret value can be set in libvirt by the
|
||||
<a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
|
||||
<code>virSecretSetValue</code></a> API. Alternatively, if supported
|
||||
|
|
@ -40,7 +40,7 @@
|
|||
<h3><a name="StorageEncryptionDefault">"default" format</a></h3>
|
||||
<p>
|
||||
<code><encryption format="default"/></code> can be specified only
|
||||
when creating a volume. If the volume is successfully created, the
|
||||
when creating a qcow 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
|
||||
|
|
@ -59,13 +59,9 @@
|
|||
<h3><a name="StorageEncryptionLuks">"luks" format</a></h3>
|
||||
<p>
|
||||
The <code>luks</code> format is specific to a luks encrypted volume
|
||||
and the secret used in order to either encrypt or decrypt the volume.
|
||||
A single <code><secret type='passphrase'...></code> element is
|
||||
expected. The secret may be referenced via either a <code>uuid</code> or
|
||||
<code>usage</code> attribute. One of the two must be present. When
|
||||
present for volume creation, the secret will be used in order for
|
||||
volume encryption. When present for domain usage, the secret will
|
||||
be used as the passphrase to decrypt the volume.
|
||||
and the secret is used in order to either encrypt during volume creation
|
||||
or decrypt the volume for usage by the domain. A single
|
||||
<code><secret type='passphrase'...></code> element is expected.
|
||||
<span class="since">Since 2.1.0</span>.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -135,22 +131,21 @@
|
|||
</encryption></pre>
|
||||
|
||||
<p>
|
||||
Assuming a <a href="formatsecret.html#luksUsageType">
|
||||
<code>luks secret</code></a> is already defined using a
|
||||
<code>usage</code> element with an <code>name</code> of "luks_example",
|
||||
Assuming a <a href="formatsecret.html#VolumeUsageType">
|
||||
<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
|
||||
as part of a domain volume definition:
|
||||
</p>
|
||||
<pre>
|
||||
<encryption format='luks'>
|
||||
<secret type='passphrase' usage='luks_example'/>
|
||||
<secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
|
||||
</encryption>
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
Here is an example, specifying use of the <code>luks</code> format for
|
||||
a specific cipher algorihm for volume creation:
|
||||
Here is an example specifying use of the <code>luks</code> format for
|
||||
a specific cipher algorithm for volume creation:
|
||||
</p>
|
||||
<pre>
|
||||
<volume>
|
||||
|
|
@ -160,7 +155,7 @@
|
|||
<path>/var/lib/libvirt/images/demo.luks</path>
|
||||
<format type='luks'/>
|
||||
<encryption format='luks'>
|
||||
<secret type='passphrase' usage='luks_example'/>
|
||||
<secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
|
||||
<cipher name='twofish' size='256' mode='cbc' hash='sha256'/>
|
||||
<ivgen name='plain64' hash='sha256'/>
|
||||
</encryption>
|
||||
|
|
|
|||
Loading…
Reference in New Issue