1:07 p.m.
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(a)redhat.com>
---
docs/formatsecret.html.in | 104 +++++++++++++----------------------
docs/formatstorage.html.in | 16 ++++++
docs/formatstorageencryption.html.in | 29 ++++------
3 files changed, 66 insertions(+), 83 deletions(-)
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in
index ffaa7dc..216a83c 100644
--- a/docs/formatsecret.html.in
+++ b/docs/formatsecret.html.in
@@ -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>
diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in
index 94277a1..a700e85 100644
--- a/docs/formatstorage.html.in
+++ b/docs/formatstorage.html.in
@@ -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>
diff --git a/docs/formatstorageencryption.html.in b/docs/formatstorageencryption.html.in
index f2b0ffd..11af97e 100644
--- a/docs/formatstorageencryption.html.in
+++ b/docs/formatstorageencryption.html.in
@@ -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>
--
2.5.5