[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [libvirt] [PATCH 5/6] docs: Update formatsecrets to include more examples of each type



On 08/08/13 08:43, John Ferlan wrote:
Update formatsecret docs to describe the various options and provide examples
in order to set up secrets for each type of secret.
---
  docs/formatsecret.html.in | 156 ++++++++++++++++++++++++++++++++++++++++++----
  1 file changed, 145 insertions(+), 11 deletions(-)

diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in
index 3e306b5..7dd0927 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>&lt;usage
        type='volume'&gt;</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 demo-secret.xml

Given the way you names the xml file for other secret types in this context,
this should be volume-secret.xml

+      file as follows:
      </p>
- <h3>Usage type "ceph"</h3>
+    <pre>
+      &lt;secret ephemeral='no' private='yes'&gt;
+         &lt;description&gt;LUKS passphrase for the main hard drive of our mail server&lt;/description&gt;
+         &lt;uuid&gt;0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f&lt;/uuid&gt;
+         &lt;usage type='volume'&gt;
+            &lt;volume&gt;/var/lib/libvirt/images/mail.img&lt;/volume&gt;
+         &lt;/usage&gt;
+      &lt;/secret&gt;
+    </pre>
+
+    <p>
+      Define the secret and set the pass phrase as follows:
+    </p>
+    <pre>
+      # virsh secret-define demo-secret.xml
+      Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
+      #
+      # MYSECRET=`printf %s "open seseme" | base64`
+      # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
+      Secret value set
+      #
+    </pre>
+
+    <p>
+      The volume can then be used in the XML for a disk volume

s/volume can/volume secret/, or s/volume can/volume type secret/,
I prefer the latter one, since both of "volume" and "secret" are general
terms in libvirt.

And s/disk volume/storage volume/,

+      <a href="formatstorageencryption.html">encryption</a> as follows:
+    </p>
+    <pre>
+      &lt;encryption format='qcow'&gt;
+        &lt;secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/&gt;
+      &lt;/encryption&gt;
+    </pre>
+ <h3><a name="CephUsageType">Usage type "ceph"</a></h3>
      <p>
        This secret is associated with a Ceph RBD (rados block device).
        The <code>&lt;usage type='ceph'&gt;</code> element must contain
@@ -66,10 +99,57 @@
        this usage name via the <code>&lt;auth&gt;</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>
+      &lt;secret ephemeral='no' private='yes'&gt;
+         &lt;description&gt;CEPH passphrase example&lt;/description&gt;
+         &lt;auth type='ceph' username='myname'/&gt;
+         &lt;usage type='ceph'&gt;
+            &lt;name&gt;ceph_example&lt;/name&gt;
+         &lt;/usage&gt;
+      &lt;/secret&gt;
+    </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
- <h3>Usage type "iscsi"</h3>
+      #
+    </pre>
+
+    <p>
+      The ceph secret can then be used by UUID or by the
+      usage name via the <code>&lt;auth&gt;</code> element in a
+      domain's <code>&lt;disk&gt;</code> element as follows:
+    </p>
+    <pre>
+      &lt;source protocol='rbd' name='pool/image'&gt;
+        &lt;host name='mon1.example.org' port='6321'/&gt;
+      &lt;/source&gt;
+      &lt;auth username='myname'&gt;
+        &lt;secret type='ceph' usage='ceph_example'/&gt;
+      &lt;/auth&gt;
+    </pre>
+

Given that you created example for storage pool chap auth. Here
we should have example for storage pool ceph auth too.

+    <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3>
<p>
        This secret is associated with an iSCSI target for CHAP authentication.
@@ -82,14 +162,68 @@
        <span class="since">Since 1.0.4</span>.
      </p>
- <h2><a name="example">Example</a></h2>
-
+    <p>
+      The following is an example of the XML that may be used to generate
+      a secret for iSCSI CHAP authentication. First define an iscsi-secret.xml
+      file to describe the secret. Replace the <code>username</code> field
+      with the username used in your iSCSI authentication configuration file.
+      The description field 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>
      <pre>
        &lt;secret ephemeral='no' private='yes'&gt;
-         &lt;description&gt;LUKS passphrase for the main hard drive of our mail server&lt;/description&gt;
-         &lt;usage type='volume'&gt;
-            &lt;volume&gt;/var/lib/libvirt/images/mail.img&lt;/volume&gt;
+         &lt;description&gt;iSCSI passphrase for the iSCSI example.com server&lt;/description&gt;
+         &lt;auth type='chap' username='myuser'/&gt;
+         &lt;usage type='iscsi'&gt;
+            &lt;target&gt;libvirtiscsi&lt;/target&gt;
           &lt;/usage&gt;
-      &lt;/secret&gt;</pre>
+      &lt;/secret&gt;
+    </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.

Add an example for "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 "redhat" | 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

[1]

+      usage name via the <code>&lt;auth&gt;</code> element in a
+      domain's <code>&lt;disk&gt;</code> element as follows:
+    </p>
+    <pre>
+      &lt;auth username='libvirt'&gt;
+        &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
+      &lt;/auth&gt;
+    </pre>
+
+    <p>
+      The iSCSI secret can then be used by UUID or by the

Duplicate with [1], could be more compact I think.

+      usage name via the <code>&lt;auth&gt;</code> element in a
+      storage pool <code>&lt;source&gt;</code> element as follows:
+    </p>
+    <pre>
+      &lt;auth type='chap' username='libvirt'&gt;
+        &lt;secret usage='libvirtiscsi'/&gt;
+      &lt;/auth&gt;
+    </pre>
    </body>
  </html>


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]