[libvirt] [PATCH 4/6] docs: Update the formatdomain disk examples
John Ferlan
jferlan at redhat.com
Mon Aug 19 21:21:00 UTC 2013
On 08/16/2013 11:17 AM, Ján Tomko wrote:
> 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
>
That whole source paragraph is quite confusing with the
various ways to represent the source xml. It's made more
confusing because an iSCSI volume can either be represented
as something from a pool via the "pool" element or directly
via the "protocol" element. In essence, there's 4 ways to
represent an iSCSI volume (thus the 4 new examples).
The point of the "Name" column was to give a hint as to which
value to provide for that specific option. For example, the
on my system I get the following:
# virsh vol-list iscsi-pool
Name Path
-----------------------------------------
unit:0:0:1 /dev/disk/by-path/ip-192.168.122.1:3260-iscsi-iqn.2013-07.localhost:iscsi-pool-lun-1
unit:0:0:2 /dev/disk/by-path/ip-192.168.122.1:3260-iscsi-iqn.2013-07.localhost:iscsi-pool-lun-2
So the comment in that section was to use "unit:0:0:1" or
"unit:0:0:2" rather than anything else when using the "pool"
attribute.
I've updated the description quite a bit to perhaps and
hopefully clear things up a bit more. I attached a patch
based on top of trunk from just a bit ago... I also changed
the examples to be based on what's running now on my test
system (although I changed the ipaddr to be example.com to
look better).
John
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0004-docs-Update-the-formatdomain-disk-examples.patch
Type: text/x-patch
Size: 11846 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130819/c5fb200f/attachment-0001.bin>
More information about the libvir-list
mailing list