From e2f88bd51503615700467ed4a15331e79d21d0fe Mon Sep 17 00:00:00 2001 Message-Id: From: John Ferlan 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>
+
-- 1.8.3.2