From 44d8ec7532a065d3c0ea81d5e357456d03bff910 Mon Sep 17 00:00:00 2001
Message-Id: <44d8ec7532a065d3c0ea81d5e357456d03bff910.1377873642.git.jdenemar@redhat.com>
From: John Ferlan <jferlan@redhat.com>
Date: Thu, 22 Aug 2013 16:56:29 -0400
Subject: [PATCH] docs: Reformat <disk> attribute description in formatdomain
https://bugzilla.redhat.com/show_bug.cgi?id=1000169
Reformat the description to more cleanly delineate the attributes
for a <disk> 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 @@
<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.2