|
 |
43fe83 |
From 002a473e60b72997b5b1b96f9d96de3ec9081ef4 Mon Sep 17 00:00:00 2001
|
|
|
43fe83 |
Message-Id: <002a473e60b72997b5b1b96f9d96de3ec9081ef4.1377873641.git.jdenemar@redhat.com>
|
|
|
43fe83 |
From: John Ferlan <jferlan@redhat.com>
|
|
|
43fe83 |
Date: Thu, 22 Aug 2013 16:56:26 -0400
|
|
|
43fe83 |
Subject: [PATCH] docs: Update the formatdomain disk examples
|
|
|
43fe83 |
|
|
|
43fe83 |
https://bugzilla.redhat.com/show_bug.cgi?id=1000169
|
|
|
43fe83 |
|
|
|
43fe83 |
Add more iSCSI examples including having a secret attached. There are 4 new
|
|
|
43fe83 |
examples; one for each way to have an iSCSI - a network disk using virtio,
|
|
|
43fe83 |
a passthrough network lun using scsi, a volume disk using "mode='host'",
|
|
|
43fe83 |
and a volume disk using "mode='direct'"
|
|
|
43fe83 |
|
|
|
43fe83 |
(cherry picked from commit cb3b7dce7ce7186f8ef438724fabfec11855e3fd)
|
|
|
43fe83 |
---
|
|
|
43fe83 |
docs/formatdomain.html.in | 165 ++++++++++++++++++++++++++++++++++------------
|
|
|
43fe83 |
1 file changed, 122 insertions(+), 43 deletions(-)
|
|
|
43fe83 |
|
|
|
43fe83 |
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
|
|
|
43fe83 |
index fb7d671..203e557 100644
|
|
|
43fe83 |
--- a/docs/formatdomain.html.in
|
|
|
43fe83 |
+++ b/docs/formatdomain.html.in
|
|
|
43fe83 |
@@ -1514,6 +1514,43 @@
|
|
|
43fe83 |
<source pool='blk-pool0' volume='blk-pool0-vol0'/>
|
|
|
43fe83 |
<target dev='hda' bus='ide'/>
|
|
|
43fe83 |
</disk>
|
|
|
43fe83 |
+ <disk type='network' device='disk'>
|
|
|
43fe83 |
+ <driver name='qemu' type='raw'/>
|
|
|
43fe83 |
+ <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'>
|
|
|
43fe83 |
+ <host name='example.com' port='3260'/>
|
|
|
43fe83 |
+ </source>
|
|
|
43fe83 |
+ <auth username='myuser'>
|
|
|
43fe83 |
+ <secret type='chap' usage='libvirtiscsi'/>
|
|
|
43fe83 |
+ </auth>
|
|
|
43fe83 |
+ <target dev='vda' bus='virtio'/>
|
|
|
43fe83 |
+ </disk>
|
|
|
43fe83 |
+ <disk type='network' device='lun'>
|
|
|
43fe83 |
+ <driver name='qemu' type='raw'/>
|
|
|
43fe83 |
+ <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/1'>
|
|
|
43fe83 |
+ iqn.2013-07.com.example:iscsi-pool
|
|
|
43fe83 |
+ <host name='example.com' port='3260'/>
|
|
|
43fe83 |
+ </source>
|
|
|
43fe83 |
+ <auth username='myuser'>
|
|
|
43fe83 |
+ <secret type='chap' usage='libvirtiscsi'/>
|
|
|
43fe83 |
+ </auth>
|
|
|
43fe83 |
+ <target dev='sda' bus='scsi'/>
|
|
|
43fe83 |
+ </disk>
|
|
|
43fe83 |
+ <disk type='volume' device='disk'>
|
|
|
43fe83 |
+ <driver name='qemu' type='raw'/>
|
|
|
43fe83 |
+ <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/>
|
|
|
43fe83 |
+ <auth username='myuser'>
|
|
|
43fe83 |
+ <secret type='chap' usage='libvirtiscsi'/>
|
|
|
43fe83 |
+ </auth>
|
|
|
43fe83 |
+ <target dev='vda' bus='virtio'/>
|
|
|
43fe83 |
+ </disk>
|
|
|
43fe83 |
+ <disk type='volume' device='disk'>
|
|
|
43fe83 |
+ <driver name='qemu' type='raw'/>
|
|
|
43fe83 |
+ <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/>
|
|
|
43fe83 |
+ <auth username='myuser'>
|
|
|
43fe83 |
+ <secret type='chap' usage='libvirtiscsi'/>
|
|
|
43fe83 |
+ </auth>
|
|
|
43fe83 |
+ <target dev='vda' bus='virtio'/>
|
|
|
43fe83 |
+ </disk>
|
|
|
43fe83 |
</devices>
|
|
|
43fe83 |
...
|
|
|
43fe83 |
|
|
|
43fe83 |
@@ -1521,7 +1558,7 @@
|
|
|
43fe83 |
disk
|
|
|
43fe83 |
The disk element is the main container for describing
|
|
|
43fe83 |
disks. The type attribute is either "file",
|
|
|
43fe83 |
- "block", "dir", or "network"
|
|
|
43fe83 |
+ "block", "dir", "network", or "volume"
|
|
|
43fe83 |
and refers to the underlying source for the disk. The optional
|
|
|
43fe83 |
device attribute indicates how the disk is to be exposed
|
|
|
43fe83 |
to the guest OS. Possible values for this attribute are
|
|
|
43fe83 |
@@ -1571,57 +1608,96 @@
|
|
|
43fe83 |
"network" attribute since 0.8.7; "snapshot" since
|
|
|
43fe83 |
0.9.5
|
|
|
43fe83 |
source
|
|
|
43fe83 |
- If the disk type is "file", then
|
|
|
43fe83 |
- the file attribute specifies the fully-qualified
|
|
|
43fe83 |
- path to the file holding the disk. If the disk
|
|
|
43fe83 |
- type is "block", then the dev
|
|
|
43fe83 |
- attribute specifies the path to the host device to serve as
|
|
|
43fe83 |
- the disk. With "file", "block", and "volume", one or more optional
|
|
|
43fe83 |
+ Representation of the disk source depends on the
|
|
|
43fe83 |
+ disk type attribute value as follows:
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ type='file'
|
|
|
43fe83 |
+ since 0.0.3
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The file attribute specifies the fully-qualified
|
|
|
43fe83 |
+ path to the file holding the disk.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ type='block'
|
|
|
43fe83 |
+ since 0.0.3
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The dev attribute specifies the path to the
|
|
|
43fe83 |
+ host device to serve as the disk.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ type='dir'
|
|
|
43fe83 |
+ since 0.7.5
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The dir attribute specifies the fully-qualified path
|
|
|
43fe83 |
+ to the directory to use as the disk.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ type='network'
|
|
|
43fe83 |
+ since 0.8.7
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The protocol attribute specifies the protocol to
|
|
|
43fe83 |
+ access to the requested image. Possible values are "nbd",
|
|
|
43fe83 |
+ "iscsi", "rbd", "sheepdog" or "gluster". If the
|
|
|
43fe83 |
+ protocol attribute is "rbd", "sheepdog" or
|
|
|
43fe83 |
+ "gluster", an additional attribute name is
|
|
|
43fe83 |
+ mandatory to specify which volume/image will be used. For "nbd",
|
|
|
43fe83 |
+ the name attribute is optional. For "iscsi"
|
|
|
43fe83 |
+ (since 1.0.4), the name
|
|
|
43fe83 |
+ attribute may include a logical unit number, separated from the
|
|
|
43fe83 |
+ target's name by a slash (e.g.,
|
|
|
43fe83 |
+ iqn.2013-07.com.example:iscsi-pool/1). If not
|
|
|
43fe83 |
+ specified, the default LUN is zero.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ type='volume'
|
|
|
43fe83 |
+ since 1.0.5
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The underlying disk source is represented by attributes
|
|
|
43fe83 |
+ pool and volume. Attribute
|
|
|
43fe83 |
+ pool specifies the name of the
|
|
|
43fe83 |
+ storage pool (managed
|
|
|
43fe83 |
+ by libvirt) where the disk source resides. Attribute
|
|
|
43fe83 |
+ volume specifies the name of storage volume (managed
|
|
|
43fe83 |
+ by libvirt) used as the disk source. The value for the
|
|
|
43fe83 |
+ volume attribute will be the output from the "Name"
|
|
|
43fe83 |
+ column of a virsh vol-list [pool-name] command.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Use the attribute mode
|
|
|
43fe83 |
+ (since 1.1.1) to indicate how to
|
|
|
43fe83 |
+ represent the LUN as the disk source. Valid values are
|
|
|
43fe83 |
+ "direct" and "host". If mode is not specified,
|
|
|
43fe83 |
+ the default is to use "host".
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Using "direct" as the mode value indicates to use
|
|
|
43fe83 |
+ the storage pool's
|
|
|
43fe83 |
+ source element host attribute as
|
|
|
43fe83 |
+ the disk source to generate the libiscsi URI (e.g.
|
|
|
43fe83 |
+ 'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1').
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Using "host" as the mode value indicates to use the
|
|
|
43fe83 |
+ LUN's path as it shows up on host (e.g.
|
|
|
43fe83 |
+ 'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1').
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ With "file", "block", and "volume", one or more optional
|
|
|
43fe83 |
sub-elements seclabel, described
|
|
|
43fe83 |
below (and since 0.9.9), can be
|
|
|
43fe83 |
used to override the domain security labeling policy for just
|
|
|
43fe83 |
that source file. (NB, for "volume" type disk, seclabel
|
|
|
43fe83 |
is only valid when the specified storage volume is of 'file' or
|
|
|
43fe83 |
- 'block' type). If the disk type is "dir", then the
|
|
|
43fe83 |
- dir attribute specifies the fully-qualified path
|
|
|
43fe83 |
- to the directory to use as the disk. If the disk type
|
|
|
43fe83 |
- is "network", then the protocol attribute specifies
|
|
|
43fe83 |
- the protocol to access to the requested image; possible values
|
|
|
43fe83 |
- are "nbd", "iscsi", "rbd", "sheepdog" or "gluster". If the
|
|
|
43fe83 |
- protocol attribute is "rbd", "sheepdog" or "gluster", an
|
|
|
43fe83 |
- additional attribute name is mandatory to specify which
|
|
|
43fe83 |
- volume/image will be used; for "nbd" it is optional. For "iscsi",
|
|
|
43fe83 |
- the name attribute may include a logical unit number,
|
|
|
43fe83 |
- separated from the target's name by a slash (for example,
|
|
|
43fe83 |
- iqn.1992-01.com.example/1); the default LUN is zero.
|
|
|
43fe83 |
+ 'block' type).
|
|
|
43fe83 |
+
|
|
|
43fe83 |
When the disk type is "network", the source
|
|
|
43fe83 |
may have zero or more host sub-elements used to
|
|
|
43fe83 |
- specify the hosts to connect. If the disk type is
|
|
|
43fe83 |
- "volume", the underlying disk source is represented by attributes
|
|
|
43fe83 |
- pool and volume. Attribute pool
|
|
|
43fe83 |
- specifies the name of storage pool (managed by libvirt) where the disk
|
|
|
43fe83 |
- source resides, and attribute volume specifies the name of
|
|
|
43fe83 |
- storage volume (managed by libvirt) used as the disk source. For a
|
|
|
43fe83 |
- "volume" type disk, if the underlying storage pool is "iscsi", attribute
|
|
|
43fe83 |
- mode (since 1.1.1) can be used
|
|
|
43fe83 |
- to indicate how to represent the LUN as the disk source. The value
|
|
|
43fe83 |
- "host" indicates to use the LUN's path as it shows up on host, e.g.
|
|
|
43fe83 |
- /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1).
|
|
|
43fe83 |
- The value "direct" indicates to use the storage pool's
|
|
|
43fe83 |
- source element host attribute as the
|
|
|
43fe83 |
- disk source for the libiscsi URI, e.g.
|
|
|
43fe83 |
- file=iscsi://demo.org:6000/iqn.1992-01.com.example/1.
|
|
|
43fe83 |
- Since 0.0.3; type='dir' since
|
|
|
43fe83 |
- 0.7.5; type='network' since
|
|
|
43fe83 |
- 0.8.7; protocol='iscsi' since 1.0.4;
|
|
|
43fe83 |
- type='volume' since 1.0.5;
|
|
|
43fe83 |
+ specify the hosts to connect.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
For a "file" or "volume" disk type which represents a cdrom or floppy
|
|
|
43fe83 |
(the device attribute), it is possible to define
|
|
|
43fe83 |
policy what to do with the disk if the source file is not accessible.
|
|
|
43fe83 |
(NB, startupPolicy is not valid for "volume" disk unless
|
|
|
43fe83 |
the specified storage volume is of "file" type). This is done by the
|
|
|
43fe83 |
- startupPolicy attribute (Since 0.9.7),
|
|
|
43fe83 |
+ startupPolicy attribute
|
|
|
43fe83 |
+ (since 0.9.7),
|
|
|
43fe83 |
accepting these values:
|
|
|
43fe83 |
+
|
|
|
43fe83 |
|
|
|
43fe83 |
|
|
|
43fe83 |
mandatory
|
|
|
43fe83 |
@@ -1637,10 +1713,13 @@
|
|
|
43fe83 |
drop if missing at any start attempt
|
|
|
43fe83 |
|
|
|
43fe83 |
|
|
|
43fe83 |
- Since 1.1.2 the startupPolicy is extended
|
|
|
43fe83 |
- to support hard disks besides cdrom and floppy. On guest cold bootup, if a certain disk
|
|
|
43fe83 |
- is not accessible or its disk chain is broken, with startupPolicy 'optional' the guest
|
|
|
43fe83 |
- will drop this disk. This feature doesn't support migration currently.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Since 1.1.2 the startupPolicy
|
|
|
43fe83 |
+ is extended to support hard disks besides cdrom and floppy. On guest
|
|
|
43fe83 |
+ cold bootup, if a certain disk is not accessible or its disk chain is
|
|
|
43fe83 |
+ broken, with startupPolicy 'optional' the guest will drop this disk.
|
|
|
43fe83 |
+ This feature doesn't support migration currently.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
|
|
|
43fe83 |
mirror
|
|
|
43fe83 |
|
|
|
43fe83 |
--
|
|
|
43fe83 |
1.8.3.2
|
|
|
43fe83 |
|