From e2f88bd51503615700467ed4a15331e79d21d0fe Mon Sep 17 00:00:00 2001

Message-Id: <e2f88bd51503615700467ed4a15331e79d21d0fe.1377873641.git.jdenemar@redhat.com>

From: John Ferlan <jferlan@redhat.com>

Date: Thu, 22 Aug 2013 16:56:27 -0400

Subject: [PATCH] docs: Update formatsecrets to include more examples of each

 type

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

Update formatsecret docs to describe the various options and provide examples

in order to set up secrets for each type of secret.

(cherry picked from commit 4ba052907848b85d5f61144707b101ad82314674)

---

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

 1 file changed, 166 insertions(+), 14 deletions(-)

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

index 3e306b5..651f722 100644

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

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

@@ -46,18 +46,51 @@

-    
Usage type "volume"

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

+      this secret is associated with. For example, create a volume-secret.xml

+      file as follows:

-    
Usage type "ceph"

+    

+      <secret ephemeral='no' private='yes'>

+         <description>Super secret name of my first puppy</description>

+         <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid>

+         <usage type='volume'>

+            <volume>/var/lib/libvirt/images/puppyname.img</volume>

+         </usage>

+      </secret>

+    

+

+    

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

+    

+    

+      # virsh secret-define volume-secret.xml

+      Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created

+      #

+      # MYSECRET=`printf %s "open sesame" | base64`

+      # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET

+      Secret value set

+      #

+    

+

+    

+      The volume type secret can then be used in the XML for a storage volume

+      encryption as follows:

+    

+    

+      <encryption format='qcow'>

+        <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/>

+      </encryption>

+    

+    
Usage type "ceph"

       This secret is associated with a Ceph RBD (rados block device).

       The <usage type='ceph'> element must contain

@@ -66,30 +99,149 @@

       this usage name via the <auth> element of

       a disk device or

       a storage pool (rbd).

-      Since 0.9.7.

+      Since 0.9.7. The following is an example

+      of the steps to be taken.  First create a ceph-secret.xml file:

+    

+

+    

+      <secret ephemeral='no' private='yes'>

+         <description>CEPH passphrase example</description>

+         <auth type='ceph' username='myname'/>

+         <usage type='ceph'>

+            <name>ceph_example</name>

+         </usage>

+      </secret>

+    

+

+    

+      Next, use virsh secret-define ceph-secret.xml to define

+      the secret and virsh secret-set-value using the generated

+      UUID value and a base64 generated secret value in order to define the

+      chosen secret pass phrase.

+    

+    

+      # virsh secret-define ceph-secret.xml

+      Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created

+      #

+      # virsh secret-list

+      UUID                                 Usage

+      -----------------------------------------------------------

+      1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example

+      #

+      # CEPHPHRASE=`printf %s "pass phrase" | base64`

+      # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE

+      Secret value set

+

+      #

+    

+

+    

+      The ceph secret can then be used by UUID or by the

+      usage name via the <auth> element in a domain's

+      <disk>

+      element as follows:

+    

+      <auth username='myname'>

+        <secret type='ceph' usage='ceph_example'/>

+      </auth>

+    

+

+    

+      As well as the <auth> element in a

+      storage pool (rbd)

+      <source> element as follows:

+    

+    

+      <auth type='ceph' username='myname'>

+        <secret usage='ceph_example'/>

+      </auth>

+    

-    
Usage type "iscsi"

+    
Usage type "iscsi"

       This secret is associated with an iSCSI target for CHAP authentication.

       The <usage type='iscsi'> element must contain

       a single target element that specifies a usage name

-      for the secret.  The iSCSI secret can then be used by UUID or by

+      for the secret. The iSCSI secret can then be used by UUID or by

       this usage name via the <auth> element of

       a disk device or

       a storage pool (iscsi).

-      Since 1.0.4.

+      Since 1.0.4. The following is an example

+      of the XML that may be used to generate a secret for iSCSI CHAP

+      authentication. Assume the following sample entry in an iSCSI

+      authentication file:

+    

+      

+      <target iqn.2013-07.com.example:iscsi-pool>

+      backing-store /home/tgtd/iscsi-pool/disk1

+      backing-store /home/tgtd/iscsi-pool/disk2

+      incominguser myname mysecret

+      </target>

+      

+    

+      Define an iscsi-secret.xml file to describe the secret. Use the

+      incominguser username used in your iSCSI authentication

+      configuration file as the value for the username attribute.

+      The description attribute should contain configuration

+      specific data. The target name may be any name of your

+      choosing to be used as the usage when used in the pool

+      or disk XML description.

-

-    
Example

-

       <secret ephemeral='no' private='yes'>

-         <description>LUKS passphrase for the main hard drive of our mail server</description>

-         <usage type='volume'>

-            <volume>/var/lib/libvirt/images/mail.img</volume>

+         <description>Passphrase for the iSCSI example.com server</description>

+         <auth type='chap' username='myname'/>

+         <usage type='iscsi'>

+            <target>libvirtiscsi</target>

          </usage>

-      </secret>

+      </secret>

+    

+

+    

+      Next, use virsh secret-define iscsi-secret.xml to define

+      the secret and virsh secret-set-value using the generated

+      UUID value and a base64 generated secret value in order to define the

+      chosen secret pass phrase.  The pass phrase must match the password

+      used in the iSCSI authentication configuration file.

+    

+    

+      # virsh secret-define secret.xml

+      Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created

+

+      # virsh secret-list

+      UUID                                 Usage

+      -----------------------------------------------------------

+      c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi

+

+      # MYSECRET=`printf %s "mysecret" | base64`

+      # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET

+      Secret value set

+      #

+    

+

+    

+      The iSCSI secret can then be used by UUID or by the

+      usage name via the <auth> element in a domain's

+      <disk>

+      element as follows:

+    

+    

+      <auth username='myname'>

+        <secret type='iscsi' usage='libvirtiscsi'/>

+      </auth>

+    

+

+    

+      As well as the <auth> element in a

+      storage pool (iscsi)

+      <source> element as follows:

+    

+    

+      <auth type='chap' username='myname'>

+        <secret usage='libvirtiscsi'/>

+      </auth>

+    

   </body>

 </html>

-- 

1.8.3.2