Blob Blame History Raw
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