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 @@
</dd>
</dl>
- <h3>Usage type "volume"</h3>
+ <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.
+ this secret is associated with. For example, create a volume-secret.xml
+ file as follows:
</p>
- <h3>Usage type "ceph"</h3>
+ <pre>
+ <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>
+ </pre>
+
+ <p>
+ Define the secret and set the pass phrase as follows:
+ </p>
+ <pre>
+ # 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
+ #
+ </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:
+ </p>
+ <pre>
+ <encryption format='qcow'>
+ <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/>
+ </encryption>
+ </pre>
+ <h3><a name="CephUsageType">Usage type "ceph"</a></h3>
<p>
This secret is associated with a Ceph RBD (rados block device).
The <code><usage type='ceph'></code> element must contain
@@ -66,30 +99,149 @@
this usage name via the <code><auth></code> element of
a <a href="formatdomain.html#elementsDisks">disk device</a> or
a <a href="formatstorage.html">storage pool (rbd)</a>.
- <span class="since">Since 0.9.7</span>.
+ <span class="since">Since 0.9.7</span>. The following is an example
+ of the steps to be taken. First create a ceph-secret.xml file:
+ </p>
+
+ <pre>
+ <secret ephemeral='no' private='yes'>
+ <description>CEPH passphrase example</description>
+ <auth type='ceph' username='myname'/>
+ <usage type='ceph'>
+ <name>ceph_example</name>
+ </usage>
+ </secret>
+ </pre>
+
+ <p>
+ Next, use <code>virsh secret-define ceph-secret.xml</code> to define
+ the secret and <code>virsh secret-set-value</code> using the generated
+ UUID value and a base64 generated secret value in order to define the
+ chosen secret pass phrase.
+ </p>
+ <pre>
+ # 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
+
+ #
+ </pre>
+
+ <p>
+ The ceph secret can then be used by UUID or by the
+ usage name via the <code><auth></code> element in a domain's
+ <a href="formatdomain.html#elementsDisks"><code><disk></code></a>
+ element as follows:
</p>
+ <pre>
+ <auth username='myname'>
+ <secret type='ceph' usage='ceph_example'/>
+ </auth>
+ </pre>
+
+ <p>
+ As well as the <code><auth></code> element in a
+ <a href="formatstorage.html">storage pool (rbd)</a>
+ <code><source></code> element as follows:
+ </p>
+ <pre>
+ <auth type='ceph' username='myname'>
+ <secret usage='ceph_example'/>
+ </auth>
+ </pre>
- <h3>Usage type "iscsi"</h3>
+ <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3>
<p>
This secret is associated with an iSCSI target for CHAP authentication.
The <code><usage type='iscsi'></code> element must contain
a single <code>target</code> 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 <code><auth></code> element of
a <a href="formatdomain.html#elementsDisks">disk device</a> or
a <a href="formatstorage.html">storage pool (iscsi)</a>.
- <span class="since">Since 1.0.4</span>.
+ <span class="since">Since 1.0.4</span>. 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:
+ </p>
+ <pre>
+ <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>
+ </pre>
+ <p>
+ Define an iscsi-secret.xml file to describe the secret. Use the
+ <code>incominguser</code> username used in your iSCSI authentication
+ configuration file as the value for the <code>username</code> attribute.
+ The <code>description</code> attribute should contain configuration
+ specific data. The <code>target</code> name may be any name of your
+ choosing to be used as the <code>usage</code> when used in the pool
+ or disk XML description.
</p>
-
- <h2><a name="example">Example</a></h2>
-
<pre>
<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></pre>
+ </secret>
+ </pre>
+
+ <p>
+ Next, use <code>virsh secret-define iscsi-secret.xml</code> to define
+ the secret and <code>virsh secret-set-value</code> 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.
+ </p>
+ <pre>
+ # 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
+ #
+ </pre>
+
+ <p>
+ The iSCSI secret can then be used by UUID or by the
+ usage name via the <code><auth></code> element in a domain's
+ <a href="formatdomain.html#elementsDisks"><code><disk></code></a>
+ element as follows:
+ </p>
+ <pre>
+ <auth username='myname'>
+ <secret type='iscsi' usage='libvirtiscsi'/>
+ </auth>
+ </pre>
+
+ <p>
+ As well as the <code><auth></code> element in a
+ <a href="formatstorage.html">storage pool (iscsi)</a>
+ <code><source></code> element as follows:
+ </p>
+ <pre>
+ <auth type='chap' username='myname'>
+ <secret usage='libvirtiscsi'/>
+ </auth>
+ </pre>
</body>
</html>
--
1.8.3.2