From a6bab5c34313497f80e8bbae5a5da405d3c4264b Mon Sep 17 00:00:00 2001 From: John Ferlan Date: Mon, 11 Jul 2016 06:59:03 -0400 Subject: [PATCH] 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 --- 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 ffaa7dcfb4..216a83cca6 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -41,19 +41,20 @@
Specifies what this secret is used for. A mandatory type attribute specifies the usage category, currently - only volume, ceph, iscsi, - and passphrase are defined. Specific usage categories - are described below. + only volume, ceph, and iscsi + are defined. Specific usage categories are described below.

Usage type "volume"

- This secret is associated with a volume, and it is safe to delete the - secret after the volume is deleted. The <usage - type='volume'> element must contain a - single volume 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 + <usage type='volume'> element must contain a + single volume element that specifies the path of the volume this secret is associated with. For example, create a volume-secret.xml file as follows:

@@ -69,7 +70,7 @@

- Define the secret and set the pass phrase as follows: + Define the secret and set the passphrase as follows: 

       # virsh secret-define volume-secret.xml
@@ -82,8 +83,8 @@

- The volume type secret can then be used in the XML for a storage volume - encryption as follows: + The volume type secret can be supplied in domain XML for a qcow storage + volume encryption as follows: 

       <encryption format='qcow'>
@@ -91,6 +92,33 @@
       </encryption>
+

+ The volume type secret can be supplied either in volume XML during + creation of a storage volume + in order to provide the passphrase to encrypt the volume or in + domain XML disk device + in order to provide the passphrase to decrypt the volume, + since 2.1.0. An example follows: +

+ 
+      # 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
+      #
+
+

Usage type "ceph"

This secret is associated with a Ceph RBD (rados block device). @@ -243,61 +271,5 @@ </auth> -

Usage type "passphrase"

- -

- 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 - storage volume in order to - provide the passphrase to encrypt a luks volume or by the - disk device in order to - provide the passphrase to decrypt the luks volume for usage. - Since 2.1.0. The following is an example - of a secret.xml file: -

- - 
-      # 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
-      #
-
-
- -

- A secret may also be defined via the - - virSecretDefineXML 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 - virsh secret-set-value to set the secret value. The - - virSecretSetValue API may also be used to set - a more secure secret without using printable/readable characters. -

- - 
-      # MYSECRET=`printf %s "letmein" | base64`
-      # virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
-      Secret value set
-
-
- diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in index 94277a15ec..a700e85591 100644 --- a/docs/formatstorage.html.in +++ b/docs/formatstorage.html.in @@ -752,5 +752,21 @@ </permissions> </target> </volume> + +

Storage volume using LUKS

+ + 
+      <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>
+
diff --git a/docs/formatstorageencryption.html.in b/docs/formatstorageencryption.html.in index f2b0ffdf12..11af97ee25 100644 --- a/docs/formatstorageencryption.html.in +++ b/docs/formatstorageencryption.html.in @@ -27,9 +27,9 @@ secret tags, each with mandatory attributes type and either uuid or usage (since 2.1.0). The only currently defined - value of type is passphrase. The + value of type is volume. The uuid is "uuid" of the secret while - usage is the value "usage" subelement field. + usage is the "usage" subelement field. A secret value can be set in libvirt by the virSecretSetValue API. Alternatively, if supported @@ -40,7 +40,7 @@

"default" format

<encryption format="default"/> 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 encryption tag will be updated. The unmodified contents of the encryption tag can be used @@ -59,13 +59,9 @@

"luks" format

The luks format is specific to a luks encrypted volume - and the secret used in order to either encrypt or decrypt the volume. - A single <secret type='passphrase'...> element is - expected. The secret may be referenced via either a uuid or - usage 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 + <secret type='passphrase'...> element is expected. Since 2.1.0.

@@ -135,22 +131,21 @@ </encryption>

- Assuming a - luks secret is already defined using a - usage element with an name of "luks_example", + Assuming a + luks volume type secret is already defined, a simple example specifying use of the luks format for either volume creation without a specific cipher being defined or as part of a domain volume definition: 

       <encryption format='luks'>
-         <secret type='passphrase' usage='luks_example'/>
+        <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
       </encryption>

- Here is an example, specifying use of the luks format for - a specific cipher algorihm for volume creation: + Here is an example specifying use of the luks format for + a specific cipher algorithm for volume creation: 

       <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>