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
>From e31f3596893302ee1f96d2eb0cf4e006294c528c Mon Sep 17 00:00:00 2001
From: John Ferlan <jferlan@xxxxxxxxxx>
Date: Wed, 7 Aug 2013 09:05:43 -0400
Subject: [PATCH 4/7] docs: Update the formatdomain disk examples
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 | 164 ++++++++++++++++++++++++++++++++++------------
1 file changed, 121 insertions(+), 43 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 4a927cc..5450be0 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1518,6 +1518,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>
@@ -1525,7 +1561,7 @@
<dt><code>disk</code></dt>
<dd>The <code>disk</code> element is the main container for describing
disks. The <code>type</code> attribute is either "file",
- "block", "dir", or "network"
+ "block", "dir", "network", or "volume"
and refers to the underlying source for the disk. The optional
<code>device</code> attribute indicates how the disk is to be exposed
to the guest OS. Possible values for this attribute are
@@ -1575,57 +1611,96 @@
"network" attribute since 0.8.7; "snapshot" since
0.9.5</span></dd>
<dt><code>source</code></dt>
- <dd>If the disk <code>type</code> is "file", then
- the <code>file</code> attribute specifies the fully-qualified
- path to the file holding the disk. If the disk
- <code>type</code> is "block", then the <code>dev</code>
- attribute specifies the path to the host device to serve as
- the disk. With "file", "block", and "volume", one or more optional
+ <dd>Representation of the disk <code>source</code> depends on the
+ <code>disk type</code> attribute value as follows:
+ <dl>
+ <dt><code>type='file'</code>
+ <span class="since">Since 0.0.3</span></dt>
+ <dd>
+ The <code>file</code> attribute specifies the fully-qualified
+ path to the file holding the disk.
+ </dd>
+ <dt><code>type='block'</code>
+ <span class="since">Since 0.0.3</span></dt>
+ <dd>
+ The <code>dev</code> attribute specifies the path to the
+ host device to serve as the disk.
+ </dd>
+ <dt><code>type='dir'</code>
+ <span class="since">Since 0.7.5</span></dt>
+ <dd>
+ The <code>dir</code> attribute specifies the fully-qualified path
+ to the directory to use as the disk.
+ </dd>
+ <dt><code>type='network'</code>
+ <span class="since">Since 0.8.7</span></dt>
+ <dd>
+ The <code>protocol</code> attribute specifies the protocol to
+ access to the requested image. Possible values are "nbd",
+ "iscsi", "rbd", "sheepdog" or "gluster". If the
+ <code>protocol</code> attribute is "rbd", "sheepdog" or
+ "gluster", an additional attribute <code>name</code> is
+ mandatory to specify which volume/image will be used. For "nbd",
+ the <code>name</code> attribute is optional. For "iscsi"
+ (<span class="since">since 1.0.4</span>), the <code>name</code>
+ attribute may include a logical unit number, separated from the
+ target's name by a slash (e.g.,
+ <code>iqn.2013-07.com.example:iscsi-pool/1</code>). If not
+ specified, the default LUN is zero.
+ </dd>
+ <dt><code>type='volume'</code>
+ <span class="since">Since 1.0.5</span></dt>
+ <dd>
+ The underlying disk source is represented by attributes
+ <code>pool</code> and <code>volume</code>. Attribute
+ <code>pool</code> specifies the name of storage pool (managed
+ by libvirt) where the disk source resides. Attribute
+ <code>volume</code> specifies the name of storage volume (managed
+ by libvirt) used as the disk source.
+
+ <p>
+ 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. Valid values are
+ "direct" and "host". If <code>mode</code> is not specified,
+ the default is to use "host".
+
+ 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://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1').
+
+ Using "host" as the <code>mode</code> value indicates to use the
+ LUN's path as it shows up on host (e.g.
+ 'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1').
+ </p>
+ </dd>
+ </dl>
+ With "file", "block", and "volume", one or more optional
sub-elements <code>seclabel</code>, <a href="#seclabel">described
below</a> (and <span class="since">since 0.9.9</span>), can be
used to override the domain security labeling policy for just
that source file. (NB, for "volume" type disk, <code>seclabel</code>
is only valid when the specified storage volume is of 'file' or
- 'block' type). If the disk <code>type</code> is "dir", then the
- <code>dir</code> attribute specifies the fully-qualified path
- to the directory to use as the disk. If the disk <code>type</code>
- is "network", then the <code>protocol</code> attribute specifies
- the protocol to access to the requested image; possible values
- are "nbd", "iscsi", "rbd", "sheepdog" or "gluster". If the
- <code>protocol</code> attribute is "rbd", "sheepdog" or "gluster", an
- additional attribute <code>name</code> is mandatory to specify which
- volume/image will be used; for "nbd" it is optional. For "iscsi",
- the <code>name</code> attribute may include a logical unit number,
- separated from the target's name by a slash (for example,
- <code>iqn.1992-01.com.example/1</code>); the default LUN is zero.
+ 'block' type).
+ <p>
When the disk <code>type</code> is "network", the <code>source</code>
may have zero or more <code>host</code> sub-elements used to
- specify the hosts to connect. If the disk <code>type</code> is
- "volume", the underlying disk source is represented by attributes
- <code>pool</code> and <code>volume</code>. Attribute <code>pool</code>
- 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.
- file=iscsi://demo.org:6000/iqn.1992-01.com.example/1.
- <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;
- <code>type='volume'</code> since 1.0.5;</span><br/>
+ specify the hosts to connect.
+ </p>
+ <p>
For a "file" or "volume" disk type which represents a cdrom or floppy
(the <code>device</code> attribute), it is possible to define
policy what to do with the disk if the source file is not accessible.
(NB, <code>startupPolicy</code> is not valid for "volume" disk unless
the specified storage volume is of "file" type). This is done by the
- <code>startupPolicy</code> attribute (<span class="since">Since 0.9.7</span>),
+ <code>startupPolicy</code> attribute
+ (<span class="since">Since 0.9.7</span>),
accepting these values:
+ </p>
<table class="top_table">
<tr>
<td> mandatory </td>
@@ -1641,10 +1716,13 @@
<td> drop if missing at any start attempt </td>
</tr>
</table>
- <span class="since">Since 1.1.2</span> the <code>startupPolicy</code> is extended
- to support hard disks besides cdrom and floppy. On guest cold bootup, if a certain disk
- is not accessible or its disk chain is broken, with startupPolicy 'optional' the guest
- will drop this disk. This feature doesn't support migration currently.
+ <p>
+ <span class="since">Since 1.1.2</span> the <code>startupPolicy</code>
+ is extended to support hard disks besides cdrom and floppy. On guest
+ cold bootup, if a certain disk is not accessible or its disk chain is
+ broken, with startupPolicy 'optional' the guest will drop this disk.
+ This feature doesn't support migration currently.
+ </p>
</dd>
<dt><code>mirror</code></dt>
<dd>
--
1.8.3.1
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list