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 @@

       
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