2:41 p.m.
Reformat the description to more cleanly delineate the attributes
for a <disk> element.
---
Similar to the recently changed <source> attribute.
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 0d1a74f..9d12293 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1562,56 +1562,77 @@
<dl>
<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", "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
- "floppy", "disk", "cdrom", and "lun",
defaulting to
- "disk". "lun" (<span class="since">since
0.9.10</span>) 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 <code>rawio</code> attribute
- (<span class="since">since 0.9.10</span>) 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, <code>rawio</code> 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, <code>sgio</code> is recommended, it's more
- secure than <code>rawio</code>.
- The optional <code>sgio</code> (<span
class="since">since 1.0.2</span>)
- 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
<code>rawio</code>,
- <code>sgio</code> is only valid for device 'lun'.
- The optional <code>snapshot</code> 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 <a href="formatsnapshot.html">domain snapshot
- creation</a>. Not all snapshot modes are supported;
- for example, <code>snapshot='yes'</code> with a transient
disk
- generally does not make sense. <span class="since">Since 0.0.3;
- "device" attribute since 0.1.4;
- "network" attribute since 0.8.7; "snapshot" since
- 0.9.5</span></dd>
+ disks (<span class="since">since 0.0.3</span>).
+ <dl>
+ <dt><code>type</code> attribute
+ <span class="since">since 0.0.3</span></dt>
+ <dd>
+ Valid values are "file", "block",
+ "dir" (<span class="since">since
0.7.5</span>),
+ "network" (<span class="since">since
0.8.7</span>), or
+ "volume" (<span class="since">since
1.0.5</span>)
+ and refer to the underlying source for the disk.
+ </dd>
+ <dt><code>device</code> attribute
+ <span class="since">since 0.1.4</span></dt>
+ <dd>
+ 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".
+ <p>
+ Using "lun" (<span class="since">since
0.9.10</span>) 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').
+ </p>
+ </dd>
+ <dt><code>rawio</code> attribute
+ <span class="since">since 0.9.10</span></dt>
+ <dd>
+ 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,
<code>rawio</code> 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, <code>sgio</code> is recommended, it's more
+ secure than <code>rawio</code>.
+ </dd>
+ <dt><code>sgio</code> attribute
+ <span class="since">since 1.0.2</span></dt>
+ <dd>
+ Indicates whether the kernel will filter unprivileged
+ SG_IO commands for the disk, valid settings are "filtered" or
+ "unfiltered". Defaults to "filtered". Similar to
<code>rawio</code>,
+ <code>sgio</code> is only valid for device 'lun'.
+ </dd>
+ <dt><code>snapshot</code> attribute
+ <span class="since">since 0.9.5</span></dt>
+ <dd>
+ 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
+ <a href="formatsnapshot.html">domain snapshot
creation</a>.
+ Not all snapshot modes are supported; for example,
+ <code>snapshot='yes'</code> with a transient disk
generally
+ does not make sense.
+ </dd>
+ </dl>
+ </dd>
<dt><code>source</code></dt>
<dd>Representation of the disk <code>source</code> depends on
the
disk <code>type</code> attribute value as follows:
--
1.8.3.1