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

On 20/08/13 05:21, John Ferlan wrote: > > >From e31f3596893302ee1f96d2eb0cf4e006294c528c Mon Sep 17 00:00:00 2001 > From: John Ferlan <jferlan(a)redhat.com&gt; > 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 @@ > &lt;source pool='blk-pool0' volume='blk-pool0-vol0'/&gt; > &lt;target dev='hda' bus='ide'/&gt; > &lt;/disk&gt; > + &lt;disk type='network' device='disk'&gt; > + &lt;driver name='qemu' type='raw'/&gt; > + &lt;source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'&gt; > + &lt;host name='example.com' port='3260'/&gt; > + &lt;/source&gt; > + &lt;auth username='myuser'&gt; > + &lt;secret type='chap' usage='libvirtiscsi'/&gt; > + &lt;/auth&gt; > + &lt;target dev='vda' bus='virtio'/&gt; > + &lt;/disk&gt; > + &lt;disk type='network' device='lun'&gt; > + &lt;driver name='qemu' type='raw'/&gt; > + &lt;source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'&gt; > + &lt;host name='example.com' port='3260'/&gt; > + &lt;/source&gt; > + &lt;auth username='myuser'&gt; > + &lt;secret type='chap' usage='libvirtiscsi'/&gt; > + &lt;/auth&gt; > + &lt;target dev='sda' bus='scsi'/&gt; > + &lt;/disk&gt; > + &lt;disk type='volume' device='disk'&gt; > + &lt;driver name='qemu' type='raw'/&gt; > + &lt;source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/&gt; > + &lt;auth username='myuser'&gt; > + &lt;secret type='chap' usage='libvirtiscsi'/&gt; > + &lt;/auth&gt; > + &lt;target dev='vda' bus='virtio'/&gt; > + &lt;/disk&gt; > + &lt;disk type='volume' device='disk'&gt; > + &lt;driver name='qemu' type='raw'/&gt; > + &lt;source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/&gt; > + &lt;auth username='myuser'&gt; > + &lt;secret type='chap' usage='libvirtiscsi'/&gt; > + &lt;/auth&gt; > + &lt;target dev='vda' bus='virtio'/&gt; > + &lt;/disk&gt; > &lt;/devices&gt; > ...</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: disk <code>type</code>

> + <dl> > + <dt><code>type='file'</code> if you are 2 spaces as the indention...... > + <span class="since">Since 0.0.3</span></dt> > + <dd> > + The <code>file</code> attribute specifies the fully-qualified Then you will have enough spaces to indent lines like this with 2 spaces too.

> + 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. It sounds like it only works when the storage pool is "iscsi". one can use "virsh vol-list" to find out the volume name for any type of storage pool.

> 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> Do we want a link to the storage pool document here?

> + 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 Except the indentions and the small nits, it looks quite nice overrall, much more readable than before.