storage_pool: Rework chap XML to mimic ceph

The existing 'chap' XML logic was never used - just defined.  Rather than
try to insert a square peg into a round hole, blow it up and rewrite the
logic to follow the 'ceph' format.

Remove the former "chap.login" and "chap.passwd" fields and replace
with "chap.username" and "chap.secret" in _virStoragePoolAuthChap.
Adjust the virStoragePoolDefParseAuthChap() to process.

Change the rng file to describe the new layout

Update the formatstorage.html to describe the usage of the secret element
to mention that the secret type "iscsi" and "ceph" can be used
to storage pool too.

Update the formatsecret.html to include a reference to the storage pool

Update tests to handle the changes from 'login' and 'passwd' to 'username'
and '<secret>' format

docs/formatsecret.html.in

@@ -64,8 +64,9 @@
       a single <code>name</code> element that specifies a usage name
       for the secret.  The Ceph 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>. <span class="since">Since 0.9.7</span>.
+      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>.
     </p>
 
     <h3>Usage type "iscsi"</h3>
@@ -76,8 +77,9 @@
       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
       this usage name via the <code>&lt;auth&gt;</code> element of
-      a <a href="formatdomain.html#elementsDisks">disk
-      device</a>. <span class="since">Since 1.0.4</span>.
+      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>.
     </p>
 
     <h2><a name="example">Example</a></h2>

docs/formatstorage.html.in

@@ -72,6 +72,9 @@
         <source>
           <host name="iscsi.example.com"/>
           <device path="demo-target"/>
+          <auth type='chap' username='myname'>
+            <secret type='iscsi' usage='mycluster_myname'/>
+          </auth>
           <vendor name="Acme"/>
           <product name="model"/>
         </source>
@@ -79,7 +82,6 @@
 
     <pre>
         ...
-        &lt;source&gt;
         &lt;source&gt;
           &lt;adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/&gt;
         &lt;/source&gt;
@@ -123,6 +125,27 @@
         which is the hostname or IP address of the server. May optionally
         contain a <code>port</code> attribute for the protocol specific
         port number. <span class="since">Since 0.4.1</span></dd>
+      <dt><code>auth</code></dt>
+      <dd>If present, the <code>auth</code> element provides the
+        authentication credentials needed to access the source by the
+        setting of the <code>type</code> attribute. The <code>type</code>
+        must be either "chap" or "ceph". Additionally a mandatory attribute
+        <code>username</code> identifies the username to use during
+        authentication as well as a sub-element <code>secret</code> with
+        a mandatory attribute <code>type</code>, to tie back to a
+        <a href="formatsecret.html">libvirt secret object</a> that
+        holds the actual password or other credentials. The domain XML
+        intentionally does not expose the password, only the reference
+        to the object that manages the password. The secret element
+        <code>type</code> must be either "ceph" or "iscsi". Use "ceph" for
+        Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
+        (Challenge-Handshake Authentication Protocol) iSCSI targets.
+        The <code>secret</code> element requires either a <code>uuid</code>
+        attribute with the UUID of the secret object or a <code>usage</code>
+        attribute matching the key that was specified in the
+        secret object.  <span class="since">Since 0.9.7 for "ceph" and
+        1.1.1 for "chap"</span>
+      </dd>
       <dt><code>name</code></dt>
       <dd>Provides the source for pools backed by storage from a
         named element (e.g., a logical volume group name).

docs/schemas/storagepool.rng

@@ -286,22 +286,10 @@
           <value>ceph</value>
         </choice>
       </attribute>
-      <choice>
-        <attribute name='login'>
-          <text/>
-        </attribute>
-        <attribute name='username'>
-          <text/>
-        </attribute>
-      </choice>
-      <optional>
-        <attribute name='passwd'>
-          <text/>
-        </attribute>
-      </optional>
-      <optional>
-        <ref name='sourceinfoauthsecret'/>
-      </optional>
+      <attribute name='username'>
+        <text/>
+      </attribute>
+      <ref name='sourceinfoauthsecret'/>
     </element>
   </define>