[libvirt] [PATCH 4/6] docs: Update the formatdomain disk examples

[John Ferlan]

Add more iSCSI examples including having a secret attached. There are 4 new
examples one for each way to have an iSCSI - a network disk using virtio,
a passthrough network lun using scsi, a volume disk using "mode='host'",
and a volume disk using "mode='direct'"
---
 docs/formatdomain.html.in | 57 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 49 insertions(+), 8 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index dd22b6d..01253ef 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1514,6 +1514,42 @@
       <source pool='blk-pool0' volume='blk-pool0-vol0'/>
       <target dev='hda' bus='ide'/>
     </disk>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='raw'/>
+      <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'>
+        <host name='example.com' port='3260'/>
+      <source>
+      <auth username='myuser'>
+        <secret type='chap' usage='libvirtiscsi'/>
+      </auth>
+      <target dev='vda' bus='virtio'/>
+    </disk>
+    <disk type='network' device='lun'>
+      <driver name='qemu' type='raw'/>
+      <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'>
+        <host name='example.com' port='3260'/>
+      <source>
+      <auth username='myuser'>
+        <secret type='chap' usage='libvirtiscsi'/>
+      </auth>
+      <target dev='sda' bus='scsi'/>
+    </disk>
+    <disk type='volume' device='disk'>
+      <driver name='qemu' type='raw'/>
+      <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/>
+      <auth username='myuser'>
+        <secret type='chap' usage='libvirtiscsi'/>
+      </auth>
+      <target dev='vda' bus='virtio'/>
+    </disk>
+    <disk type='volume' device='disk'>
+      <driver name='qemu' type='raw'/>
+      <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/>
+      <auth username='myuser'>
+        <secret type='chap' usage='libvirtiscsi'/>
+      </auth>
+      <target dev='vda' bus='virtio'/>
+    </disk>
   </devices>
   ...</pre>
 
@@ -1602,15 +1638,20 @@
         specifies the name of storage pool (managed by libvirt) where the disk
         source resides, and attribute <code>volume</code> specifies the name of
         storage volume (managed by libvirt) used as the disk source. For a
-        "volume" type disk, if the underlying storage pool is "iscsi", attribute
-        <code>mode</code> (<span class="since">since 1.1.1</span>) can be used
-        to indicate how to represent the LUN as the disk source. The value
-        "host" indicates to use the LUN's path as it shows up on host, e.g.
-        /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1).
-        The value "direct" indicates to use the storage pool's
-        <code>source</code> element <code>host</code> attribute as the
-        disk source for the libiscsi URI, e.g.
+        "volume" <code>type</code> disk, if the underlying storage pool is
+        "iscsi", then use the output of the value from the "Name" column of
+        the <code>virsh vol-list [pool-name]</code> command for the
+        <code>volume</code> attribute field. Use the attribute
+        <code>mode</code> (<span class="since">since 1.1.1</span>) to
+        indicate how to represent the LUN as the disk source.
+        Using "direct" as the <code>mode</code> value indicates to use the
+        storage pool's <code>source</code> element <code>host</code>
+        attribute as the disk source to generate the libiscsi URI, e.g.
         file=iscsi://demo.org:6000/iqn.1992-01.com.example/1.
+        Using "host" as the <code>mode</code> value indicates to use the
+        LUN's path as it shows up on host, e.g.
+        /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1).
+        If <code>mode</code> is not specified, the default is to use "host".
         <span class="since">Since 0.0.3; <code>type='dir'</code> since
         0.7.5; <code>type='network'</code> since
         0.8.7; <code>protocol='iscsi'</code> since 1.0.4;
-- 
1.8.3.1