From 44d8ec7532a065d3c0ea81d5e357456d03bff910 Mon Sep 17 00:00:00 2001 Message-Id: <44d8ec7532a065d3c0ea81d5e357456d03bff910.1377873642.git.jdenemar@redhat.com> From: John Ferlan Date: Thu, 22 Aug 2013 16:56:29 -0400 Subject: [PATCH] docs: Reformat attribute description in formatdomain https://bugzilla.redhat.com/show_bug.cgi?id=1000169 Reformat the description to more cleanly delineate the attributes for a element. (cherry picked from commit fc82f0addec21e1fc8b184a9b303c8e7a0dca37f) --- docs/formatdomain.html.in | 121 +++++++++++++++++++++++++++------------------- 1 file changed, 71 insertions(+), 50 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 203e557..a1803df 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1557,56 +1557,77 @@
disk
The disk element is the main container for describing - disks. The type attribute is either "file", - "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 - "floppy", "disk", "cdrom", and "lun", defaulting to - "disk". "lun" (since 0.9.10) is only - valid when type is "block" and the target element's "bus" - attribute is "virtio", and behaves identically to "disk", - except that generic SCSI commands from the guest are accepted - and passed through to the physical device - - also note that device='lun' will only be recognized for - actual raw devices, never for individual partitions or LVM - partitions (in those cases, the kernel will reject the generic - SCSI commands, making it identical to device='disk'). - The optional rawio attribute - (since 0.9.10) indicates whether - the disk is needs rawio capability; valid settings are "yes" - or "no" (default is "no"). If any one disk in a domain has - rawio='yes', rawio capability will be enabled for all disks in - the domain (because, in the case of QEMU, this capability can - only be set on a per-process basis). This attribute is only - valid when device is "lun". NB, rawio intends to - confine the capability per-device, however, current QEMU - implementation gives the domain process broader capability - than that (per-process basis, affects all the domain disks). - To confine the capability as much as possible for QEMU driver - as this stage, sgio is recommended, it's more - secure than rawio. - The optional sgio (since 1.0.2) - attribute indicates whether the kernel will filter unprivileged - SG_IO commands for the disk, valid settings are "filtered" or - "unfiltered". Defaults to "filtered". Similar to rawio, - sgio is only valid for device 'lun'. - The optional snapshot attribute indicates the default - behavior of the disk during disk snapshots: "internal" - requires a file format such as qcow2 that can store both the - snapshot and the data changes since the snapshot; - "external" will separate the snapshot from the live data; and - "no" means the disk will not participate in snapshots. - Read-only disks default to "no", while the default for other - disks depends on the hypervisor's capabilities. Some - hypervisors allow a per-snapshot choice as well, - during domain snapshot - creation. Not all snapshot modes are supported; - for example, snapshot='yes' with a transient disk - generally does not make sense. Since 0.0.3; - "device" attribute since 0.1.4; - "network" attribute since 0.8.7; "snapshot" since - 0.9.5
+ disks (since 0.0.3). +
+
type attribute + since 0.0.3
+
+ Valid values are "file", "block", + "dir" (since 0.7.5), + "network" (since 0.8.7), or + "volume" (since 1.0.5) + and refer to the underlying source for the disk. +
+
device attribute + since 0.1.4
+
+ Indicates how the disk is to be exposed to the guest OS. Possible + values for this attribute are "floppy", "disk", "cdrom", and "lun", + defaulting to "disk". +

+ Using "lun" (since 0.9.10) is only + valid when type is "block" and the target element's "bus" + attribute is "virtio", and behaves identically to "disk", + except that generic SCSI commands from the guest are accepted + and passed through to the physical device. Also note that + device='lun' will only be recognized for actual raw devices, + but never for individual partitions or LVM partitions (in those + cases, the kernel will reject the generic SCSI commands, making + it identical to device='disk'). +

+
+
rawio attribute + since 0.9.10
+
+ Indicates whether the disk is needs rawio capability; valid + settings are "yes" or "no" (default is "no"). If any one disk + in a domain has rawio='yes', rawio capability will be enabled + for all disks in the domain (because, in the case of QEMU, this + capability can only be set on a per-process basis). This attribute + is only valid when device is "lun". NB, rawio intends + to confine the capability per-device, however, current QEMU + implementation gives the domain process broader capability + than that (per-process basis, affects all the domain disks). + To confine the capability as much as possible for QEMU driver + as this stage, sgio is recommended, it's more + secure than rawio. +
+
sgio attribute + since 1.0.2
+
+ Indicates whether the kernel will filter unprivileged + SG_IO commands for the disk, valid settings are "filtered" or + "unfiltered". Defaults to "filtered". Similar to rawio, + sgio is only valid for device 'lun'. +
+
snapshot attribute + since 0.9.5
+
+ Indicates the default behavior of the disk during disk snapshots: + "internal" requires a file format such as qcow2 that can store + both the snapshot and the data changes since the snapshot; + "external" will separate the snapshot from the live data; and + "no" means the disk will not participate in snapshots. Read-only + disks default to "no", while the default for other disks depends + on the hypervisor's capabilities. Some hypervisors allow a + per-snapshot choice as well, during + domain snapshot creation. + Not all snapshot modes are supported; for example, + snapshot='yes' with a transient disk generally + does not make sense. +
+
+
source
Representation of the disk source depends on the disk type attribute value as follows: -- 1.8.3.2