openkylin
/
libvirt
mirror of https://gitee.com/openkylin/libvirt.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Reformat <disk> attribute description in formatdomain 

Reformat the description to more cleanly delineate the attributes
for a <disk> element.
This commit is contained in:
John Ferlan 2013-08-20 15:37:00 -04:00
parent 106a2ddaa7
commit fc82f0adde
1 changed files with 71 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/formatdomain.html.in
View File

@ -1562,56 +1562,77 @@
<dl> <dl>
<dt><code>disk</code></dt> <dt><code>disk</code></dt>
<dd>The <code>disk</code> element is the main container for describing <dd>The <code>disk</code> element is the main container for describing
disks. The <code>type</code> attribute is either "file", disks (<span class="since">since 0.0.3</span>).
"block", "dir", "network", or "volume" <dl>
and refers to the underlying source for the disk. The optional <dt><code>type</code> attribute
<code>device</code> attribute indicates how the disk is to be exposed <span class="since">since 0.0.3</span></dt>
to the guest OS. Possible values for this attribute are <dd>
"floppy", "disk", "cdrom", and "lun", defaulting to Valid values are "file", "block",
"disk". "lun" (<span class="since">since 0.9.10</span>) is only "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" valid when type is "block" and the target element's "bus"
attribute is "virtio", and behaves identically to "disk", attribute is "virtio", and behaves identically to "disk",
except that generic SCSI commands from the guest are accepted except that generic SCSI commands from the guest are accepted
and passed through to the physical device and passed through to the physical device. Also note that
- also note that device='lun' will only be recognized for device='lun' will only be recognized for actual raw devices,
actual raw devices, never for individual partitions or LVM but never for individual partitions or LVM partitions (in those
partitions (in those cases, the kernel will reject the generic cases, the kernel will reject the generic SCSI commands, making
SCSI commands, making it identical to device='disk'). it identical to device='disk').
The optional <code>rawio</code> attribute </p>
(<span class="since">since 0.9.10</span>) indicates whether </dd>
the disk is needs rawio capability; valid settings are "yes" <dt><code>rawio</code> attribute
or "no" (default is "no"). If any one disk in a domain has <span class="since">since 0.9.10</span></dt>
rawio='yes', rawio capability will be enabled for all disks in <dd>
the domain (because, in the case of QEMU, this capability can Indicates whether the disk is needs rawio capability; valid
only be set on a per-process basis). This attribute is only settings are "yes" or "no" (default is "no"). If any one disk
valid when device is "lun". NB, <code>rawio</code> intends to in a domain has rawio='yes', rawio capability will be enabled
confine the capability per-device, however, current QEMU 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 implementation gives the domain process broader capability
than that (per-process basis, affects all the domain disks). than that (per-process basis, affects all the domain disks).
To confine the capability as much as possible for QEMU driver To confine the capability as much as possible for QEMU driver
as this stage, <code>sgio</code> is recommended, it's more as this stage, <code>sgio</code> is recommended, it's more
secure than <code>rawio</code>. secure than <code>rawio</code>.
The optional <code>sgio</code> (<span class="since">since 1.0.2</span>) </dd>
attribute indicates whether the kernel will filter unprivileged <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 SG_IO commands for the disk, valid settings are "filtered" or
"unfiltered". Defaults to "filtered". Similar to <code>rawio</code>, "unfiltered". Defaults to "filtered". Similar to <code>rawio</code>,
<code>sgio</code> is only valid for device 'lun'. <code>sgio</code> is only valid for device 'lun'.
The optional <code>snapshot</code> attribute indicates the default </dd>
behavior of the disk during disk snapshots: "internal" <dt><code>snapshot</code> attribute
requires a file format such as qcow2 that can store both the <span class="since">since 0.9.5</span></dt>
snapshot and the data changes since the snapshot; <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 "external" will separate the snapshot from the live data; and
"no" means the disk will not participate in snapshots. "no" means the disk will not participate in snapshots. Read-only
Read-only disks default to "no", while the default for other disks default to "no", while the default for other disks depends
disks depends on the hypervisor's capabilities. Some on the hypervisor's capabilities. Some hypervisors allow a
hypervisors allow a per-snapshot choice as well, per-snapshot choice as well, during
during <a href="formatsnapshot.html">domain snapshot <a href="formatsnapshot.html">domain snapshot creation</a>.
creation</a>. Not all snapshot modes are supported; Not all snapshot modes are supported; for example,
for example, <code>snapshot='yes'</code> with a transient disk <code>snapshot='yes'</code> with a transient disk generally
generally does not make sense. <span class="since">Since 0.0.3; does not make sense.
"device" attribute since 0.1.4; </dd>
"network" attribute since 0.8.7; "snapshot" since </dl>
0.9.5</span></dd> </dd>
<dt><code>source</code></dt> <dt><code>source</code></dt>
<dd>Representation of the disk <code>source</code> depends on the <dd>Representation of the disk <code>source</code> depends on the
disk <code>type</code> attribute value as follows: disk <code>type</code> attribute value as follows: