External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-07 17:28:15 +00:00
Code

docs: Update the formatdomain disk examples

Browse Source 
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'"
This commit is contained in:
John Ferlan 2013-08-07 09:05:43 -04:00
parent 1fa7946fba
commit cb3b7dce7c
1 changed files with 122 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
docs/formatdomain.html.in
View File

@ -1519,6 +1519,43 @@
<source pool='blk-pool0' volume='blk-pool0-vol0'/> <source pool='blk-pool0' volume='blk-pool0-vol0'/>
<target dev='hda' bus='ide'/> <target dev='hda' bus='ide'/>
</disk> </disk>
<disk type='network' device='disk'>
<driver name='qemu' type='raw'/>
<source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/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-07.com.example:iscsi-nopool/1'>
iqn.2013-07.com.example:iscsi-pool
<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> </devices>
...</pre> ...</pre>
@ -1526,7 +1563,7 @@
<dt><code>disk</code></dt> <dt><code>disk</code></dt>
<dd>The <code>disk</code> element is the main container for describing <dd>The <code>disk</code> element is the main container for describing
disks. The <code>type</code> attribute is either "file", 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 and refers to the underlying source for the disk. The optional
<code>device</code> attribute indicates how the disk is to be exposed <code>device</code> attribute indicates how the disk is to be exposed
to the guest OS. Possible values for this attribute are to the guest OS. Possible values for this attribute are
@ -1576,57 +1613,96 @@
"network" attribute since 0.8.7; "snapshot" since "network" attribute since 0.8.7; "snapshot" since
0.9.5</span></dd> 0.9.5</span></dd>
<dt><code>source</code></dt> <dt><code>source</code></dt>
<dd>If the disk <code>type</code> is "file", then <dd>Representation of the disk <code>source</code> depends on the
the <code>file</code> attribute specifies the fully-qualified disk <code>type</code> attribute value as follows:
path to the file holding the disk. If the disk <dl>
<code>type</code> is "block", then the <code>dev</code> <dt><code>type='file'</code>
attribute specifies the path to the host device to serve as <span class="since">since 0.0.3</span></dt>
the disk. With "file", "block", and "volume", one or more optional <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 the
<a href="formatstorage.html">storage pool</a> (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. The value for the
<code>volume</code> attribute will be the output from the "Name"
column of a <code>virsh vol-list [pool-name]</code> command.
<p>
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 <a href="formatstorage.html">storage pool's</a>
<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 sub-elements <code>seclabel</code>, <a href="#seclabel">described
below</a> (and <span class="since">since 0.9.9</span>), can be below</a> (and <span class="since">since 0.9.9</span>), can be
used to override the domain security labeling policy for just used to override the domain security labeling policy for just
that source file. (NB, for "volume" type disk, <code>seclabel</code> that source file. (NB, for "volume" type disk, <code>seclabel</code>
is only valid when the specified storage volume is of 'file' or is only valid when the specified storage volume is of 'file' or
'block' type). If the disk <code>type</code> is "dir", then the 'block' type).
<code>dir</code> attribute specifies the fully-qualified path <p>
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.
When the disk <code>type</code> is "network", the <code>source</code> When the disk <code>type</code> is "network", the <code>source</code>
may have zero or more <code>host</code> sub-elements used to may have zero or more <code>host</code> sub-elements used to
specify the hosts to connect. If the disk <code>type</code> is specify the hosts to connect.
"volume", the underlying disk source is represented by attributes </p>
<code>pool</code> and <code>volume</code>. Attribute <code>pool</code> <p>
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/>
For a "file" or "volume" disk type which represents a cdrom or floppy For a "file" or "volume" disk type which represents a cdrom or floppy
(the <code>device</code> attribute), it is possible to define (the <code>device</code> attribute), it is possible to define
policy what to do with the disk if the source file is not accessible. 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 (NB, <code>startupPolicy</code> is not valid for "volume" disk unless
the specified storage volume is of "file" type). This is done by the 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: accepting these values:
</p>
<table class="top_table"> <table class="top_table">
<tr> <tr>
<td> mandatory </td> <td> mandatory </td>
@ -1642,10 +1718,13 @@
<td> drop if missing at any start attempt </td> <td> drop if missing at any start attempt </td>
</tr> </tr>
</table> </table>
<span class="since">Since 1.1.2</span> the <code>startupPolicy</code> is extended <p>
to support hard disks besides cdrom and floppy. On guest cold bootup, if a certain disk <span class="since">Since 1.1.2</span> the <code>startupPolicy</code>
is not accessible or its disk chain is broken, with startupPolicy 'optional' the guest is extended to support hard disks besides cdrom and floppy. On guest
will drop this disk. This feature doesn't support migration currently. 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> </dd>
<dt><code>mirror</code></dt> <dt><code>mirror</code></dt>
<dd> <dd>