docs: Update formatsecrets to include more examples of each type

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

@@ -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 volume-secret.xml
+      file as follows:
     </p>
 
-    <h3>Usage type "ceph"</h3>
+    <pre>
+      &lt;secret ephemeral='no' private='yes'&gt;
+         &lt;description&gt;Super secret name of my first puppy&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/puppyname.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 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>
+      &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,30 +99,149 @@
       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
+
+      #
+    </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
+      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
+      element as follows:
     </p>
+    <pre>
+      &lt;auth username='myname'&gt;
+        &lt;secret type='ceph' usage='ceph_example'/&gt;
+      &lt;/auth&gt;
+    </pre>
+
+    <p>
+      As well as the <code>&lt;auth&gt;</code> element in a
+      <a href="formatstorage.html">storage pool (rbd)</a>
+      <code>&lt;source&gt;</code> element as follows:
+    </p>
+    <pre>
+      &lt;auth type='ceph' username='myname'&gt;
+        &lt;secret usage='ceph_example'/&gt;
+      &lt;/auth&gt;
+    </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>&lt;usage type='iscsi'&gt;</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>&lt;auth&gt;</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>
+      &lt;target iqn.2013-07.com.example:iscsi-pool&gt;
+      backing-store /home/tgtd/iscsi-pool/disk1
+      backing-store /home/tgtd/iscsi-pool/disk2
+      incominguser myname mysecret
+      &lt;/target&gt;
+      </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>
       &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;Passphrase for the iSCSI example.com server&lt;/description&gt;
+         &lt;auth type='chap' username='myname'/&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.
+    </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>&lt;auth&gt;</code> element in a domain's
+      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
+      element as follows:
+    </p>
+    <pre>
+      &lt;auth username='myname'&gt;
+        &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
+      &lt;/auth&gt;
+    </pre>
+
+    <p>
+      As well as the <code>&lt;auth&gt;</code> element in a
+      <a href="formatstorage.html">storage pool (iscsi)</a>
+      <code>&lt;source&gt;</code> element as follows:
+    </p>
+    <pre>
+      &lt;auth type='chap' username='myname'&gt;
+        &lt;secret usage='libvirtiscsi'/&gt;
+      &lt;/auth&gt;
+    </pre>
   </body>
 </html>