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

[Ján Tomko]

On 08/08/2013 02:43 AM, John Ferlan wrote:
> 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,
           ^
Missing punctuation.

> 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>
             ^
Missing slash.

> +      <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>
             ^
Here too.

> +      <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.

Isn't this true for all storage pools and mentioned just a few sentences earlier?

> 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).

It would be nicer if the URI and the path were for the same disk.

> +        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;
> 

ACK with the "Name" column reference removed.

Jan