From 002a473e60b72997b5b1b96f9d96de3ec9081ef4 Mon Sep 17 00:00:00 2001 Message-Id: <002a473e60b72997b5b1b96f9d96de3ec9081ef4.1377873641.git.jdenemar@redhat.com> From: John Ferlan Date: Thu, 22 Aug 2013 16:56:26 -0400 Subject: [PATCH] docs: Update the formatdomain disk examples https://bugzilla.redhat.com/show_bug.cgi?id=1000169 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'" (cherry picked from commit cb3b7dce7ce7186f8ef438724fabfec11855e3fd) --- docs/formatdomain.html.in | 165 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 122 insertions(+), 43 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index fb7d671..203e557 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1514,6 +1514,43 @@ <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-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> ... @@ -1521,7 +1558,7 @@
disk
The disk element is the main container for describing disks. The type attribute is either "file", - "block", "dir", or "network" + "block", "dir", "network", or "volume" and refers to the underlying source for the disk. The optional device attribute indicates how the disk is to be exposed to the guest OS. Possible values for this attribute are @@ -1571,57 +1608,96 @@ "network" attribute since 0.8.7; "snapshot" since 0.9.5
source
-
If the disk type is "file", then - the file attribute specifies the fully-qualified - path to the file holding the disk. If the disk - type is "block", then the dev - attribute specifies the path to the host device to serve as - the disk. With "file", "block", and "volume", one or more optional +
Representation of the disk source depends on the + disk type attribute value as follows: +
+
type='file' + since 0.0.3
+
+ The file attribute specifies the fully-qualified + path to the file holding the disk. +
+
type='block' + since 0.0.3
+
+ The dev attribute specifies the path to the + host device to serve as the disk. +
+
type='dir' + since 0.7.5
+
+ The dir attribute specifies the fully-qualified path + to the directory to use as the disk. +
+
type='network' + since 0.8.7
+
+ The protocol attribute specifies the protocol to + access to the requested image. Possible values are "nbd", + "iscsi", "rbd", "sheepdog" or "gluster". If the + protocol attribute is "rbd", "sheepdog" or + "gluster", an additional attribute name is + mandatory to specify which volume/image will be used. For "nbd", + the name attribute is optional. For "iscsi" + (since 1.0.4), the name + attribute may include a logical unit number, separated from the + target's name by a slash (e.g., + iqn.2013-07.com.example:iscsi-pool/1). If not + specified, the default LUN is zero. +
+
type='volume' + since 1.0.5
+
+ The underlying disk source is represented by attributes + pool and volume. Attribute + pool specifies the name of the + storage pool (managed + by libvirt) where the disk source resides. Attribute + volume specifies the name of storage volume (managed + by libvirt) used as the disk source. The value for the + volume attribute will be the output from the "Name" + column of a virsh vol-list [pool-name] command. +

+ Use the attribute mode + (since 1.1.1) to indicate how to + represent the LUN as the disk source. Valid values are + "direct" and "host". If mode is not specified, + the default is to use "host". + + Using "direct" as the mode value indicates to use + the storage pool's + source element host 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 mode 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'). +

+
+
+ With "file", "block", and "volume", one or more optional sub-elements seclabel, described below (and since 0.9.9), can be used to override the domain security labeling policy for just that source file. (NB, for "volume" type disk, seclabel is only valid when the specified storage volume is of 'file' or - 'block' type). If the disk type is "dir", then the - dir attribute specifies the fully-qualified path - to the directory to use as the disk. If the disk type - is "network", then the protocol attribute specifies - the protocol to access to the requested image; possible values - are "nbd", "iscsi", "rbd", "sheepdog" or "gluster". If the - protocol attribute is "rbd", "sheepdog" or "gluster", an - additional attribute name is mandatory to specify which - volume/image will be used; for "nbd" it is optional. For "iscsi", - the name attribute may include a logical unit number, - separated from the target's name by a slash (for example, - iqn.1992-01.com.example/1); the default LUN is zero. + 'block' type). +

When the disk type is "network", the source may have zero or more host sub-elements used to - specify the hosts to connect. If the disk type is - "volume", the underlying disk source is represented by attributes - pool and volume. Attribute pool - specifies the name of storage pool (managed by libvirt) where the disk - source resides, and attribute volume 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 - mode (since 1.1.1) 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 - source element host attribute as the - disk source for the libiscsi URI, e.g. - file=iscsi://demo.org:6000/iqn.1992-01.com.example/1. - Since 0.0.3; type='dir' since - 0.7.5; type='network' since - 0.8.7; protocol='iscsi' since 1.0.4; - type='volume' since 1.0.5;
+ specify the hosts to connect. +

+

For a "file" or "volume" disk type which represents a cdrom or floppy (the device attribute), it is possible to define policy what to do with the disk if the source file is not accessible. (NB, startupPolicy is not valid for "volume" disk unless the specified storage volume is of "file" type). This is done by the - startupPolicy attribute (Since 0.9.7), + startupPolicy attribute + (since 0.9.7), accepting these values: +

@@ -1637,10 +1713,13 @@
mandatory drop if missing at any start attempt
- Since 1.1.2 the startupPolicy 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. +

+ Since 1.1.2 the startupPolicy + 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. +

mirror
-- 1.8.3.2