From 778fbc28f6ae7f40082d48bc57c224cd7a8d45d0 Mon Sep 17 00:00:00 2001

Message-Id: <778fbc28f6ae7f40082d48bc57c224cd7a8d45d0@dist-git>

From: John Ferlan <jferlan@redhat.com>

Date: Mon, 25 Jul 2016 12:42:52 -0400

Subject: [PATCH] docs: Update docs to reflect LUKS secret changes

https://bugzilla.redhat.com/show_bug.cgi?id=1301021

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>

(cherry picked from commit a6bab5c34313497f80e8bbae5a5da405d3c4264b)

Resolved some minor formatting conflicts from docs/formatsecret.html.in

since commit id 'c84380106fe69f86842dc7e8c032af6740bef77e' is not present

for downstream

Signed-off-by: John Ferlan <jferlan@redhat.com>

---

 docs/formatsecret.html.in            | 45 +++++++++++++++++++++++++++++-------

 docs/formatstorage.html.in           | 16 +++++++++++++

 docs/formatstorageencryption.html.in | 29 ++++++++++-------------

 3 files changed, 65 insertions(+), 25 deletions(-)

diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in

index c39d2a7..fd698a4 100644

--- a/docs/formatsecret.html.in

+++ b/docs/formatsecret.html.in

@@ -41,7 +41,7 @@

         Specifies what this secret is used for.  A mandatory

         type attribute specifies the usage category, currently

-        only volume, ceph and iscsi

+        only volume, ceph, and iscsi

         are defined. Specific usage categories are described below.

@@ -49,10 +49,12 @@

     
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:

@@ -68,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

@@ -81,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'>

@@ -90,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).

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>

+

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

+    

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

       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>

-- 

2.9.2