From: Andrea Bolognani Date: Fri, 22 Apr 2016 11:51:50 +0000 (+0200) Subject: docs: Fix some formatting oddities X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=7867c579eacc4b33d97cbad779a80adfbfefc02a;p=libvirt.git docs: Fix some formatting oddities When describing attributes and elements, we mostly stick to a certain pattern; however, there are a few cases when the information is not presented in the usual way. Since there doesn't seem to be any reason not to follow the tried and true formula, rework those bits to fit the rest of the documentation. --- diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index a9c657d48d..a3cf86698d 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -2013,20 +2013,19 @@
disk
-
The disk element is the main container for describing - disks (since 0.0.3). +
The disk element is the main container for + describing disks and supports the following attributes:
-
type attribute - since 0.0.3
+
type
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. + Since 0.0.3
-
device attribute - since 0.1.4
+
device
Indicates how the disk is to be exposed to the guest OS. Possible values for this attribute are "floppy", "disk", "cdrom", and "lun", @@ -2046,10 +2045,10 @@ 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'). + Since 0.1.4

-
rawio attribute - since 0.9.10
+
rawio
Indicates whether the disk needs rawio capability. Valid settings are "yes" or "no" (default is "no"). If any one disk @@ -2063,17 +2062,17 @@ To confine the capability as much as possible for QEMU driver as this stage, sgio is recommended, it's more secure than rawio. + Since 0.9.10
-
sgio attribute - since 1.0.2
+
sgio
If supported by the hypervisor and OS, indicates whether unprivileged SG_IO commands are filtered for the disk. Valid settings are "filtered" or "unfiltered" where the default is "filtered". Only available when the device is 'lun'. + Since 1.0.2
-
snapshot attribute - since 0.9.5
+
snapshot
Indicates the default behavior of the disk during disk snapshots: "internal" requires a file format such as qcow2 that can store @@ -2087,6 +2086,7 @@ Not all snapshot modes are supported; for example, snapshot='yes' with a transient disk generally does not make sense. + Since 0.9.5
@@ -2094,26 +2094,25 @@
Representation of the disk source depends on the disk type attribute value as follows:
-
type='file' - since 0.0.3
+
file
The file attribute specifies the fully-qualified path to the file holding the disk. + Since 0.0.3
-
type='block' - since 0.0.3
+
block
The dev attribute specifies the fully-qualified path to the host device to serve as the disk. + Since 0.0.3
-
type='dir' - since 0.7.5
+
dir
The dir attribute specifies the fully-qualified path to the directory to use as the disk. + Since 0.7.5
-
type='network' - since 0.8.7
+
network
The protocol attribute specifies the protocol to access to the requested image. Possible values are "nbd", @@ -2127,9 +2126,9 @@ target's name by a slash (e.g., iqn.2013-07.com.example:iscsi-pool/1). If not specified, the default LUN is zero. + Since 0.8.7
-
type='volume' - since 1.0.5
+
volume
The underlying disk source is represented by attributes pool and volume. Attribute @@ -2163,6 +2162,7 @@ of 'lun' with respect to how the LUN is presented to and may used by the guest. + Since 1.0.5

@@ -2303,16 +2303,16 @@ each file of the chain (files created by libvirt satisfy this property, but using existing external files for snapshot or block copy operations requires the end user to pre-create the - file correctly). The following attributes and sub-elements are + file correctly). The following attributes are supported in backingStore:
-
type attribute
+
type
The type attribute represents the type of disk used by the backing store, see disk type attribute above for more details and possible values.
-
index attribute
+
index
This attribute is only valid in output (and ignored on input) and it can be used to refer to a specific part of the disk chain when @@ -2321,20 +2321,23 @@ vda[2] refers to the backing store with index='2' of the disk with vda target.
-
format sub-element
+
+ Moreover, backingStore supports the following sub-elements: +
+
format
The format element contains type attribute which specifies the internal format of the backing store, such as raw or qcow2.
-
source sub-element
+
source
This element has the same structure as the source element in disk. It specifies which file, device, or network location contains the data of the described backing store.
-
backingStore sub-element
+
backingStore
If the backing store is not self-contained, the next element in the chain is described by nested backingStore @@ -2745,7 +2748,7 @@ source. The possible values are:
-
type='mount'
+
mount
A host directory to mount in the guest. Used by LXC, OpenVZ (since 0.6.2) @@ -2762,23 +2765,23 @@ is immediately triggered for all pages touched during a guest file write operation (since 0.9.10).
-
type='template'
+
template
OpenVZ filesystem template. Only used by OpenVZ driver.
-
type='file'
+
file
A host file will be treated as an image and mounted in the guest. The filesystem format will be autodetected. Only used by LXC driver.
-
type='block'
+
block
A host block device to mount in the guest. The filesystem format will be autodetected. Only used by LXC driver (since 0.9.5).
-
type='ram'
+
ram
An in-memory filesystem, using memory from the host OS. The source element has a single attribute usage @@ -2786,7 +2789,7 @@ are specified by the units attribute. Only used by LXC driver. (since 0.9.13)
-
type='bind'
+
bind
A directory inside the guest will be bound to another directory inside the guest. Only used by LXC driver @@ -2800,20 +2803,20 @@ values are:
-
accessmode='passthrough'
+
passthrough
The source is accessed with the permissions of the user inside the guest. This is the default accessmode if one is not specified. More info
-
accessmode='mapped'
+
mapped
The source is accessed with the permissions of the hypervisor (QEMU process). More info
-
accessmode='squash'
+
squash
Similar to 'passthrough', the exception is that failure of privileged operations like 'chown' are ignored. This makes a @@ -2912,7 +2915,7 @@

-
type='pci'
+
pci
PCI addresses have the following additional attributes: domain (a 2-byte hex integer, not currently used by qemu), bus (a hex value between @@ -2927,32 +2930,32 @@ but should be set to 'on' for function 0 of a slot that will have multiple functions used.
-
type='drive'
+
drive
Drive addresses have the following additional attributes: controller (a 2-digit controller number), bus (a 2-digit bus number), target (a 2-digit target number), and unit (a 2-digit unit number on the bus).
-
type='virtio-serial'
+
virtio-serial
Each virtio-serial address has the following additional attributes: controller (a 2-digit controller number), bus (a 2-digit bus number), and slot (a 2-digit slot within the bus).
-
type='ccid'
+
ccid
A CCID address, for smart-cards, has the following additional attributes: bus (a 2-digit bus number), and slot attribute (a 2-digit slot within the bus). Since 0.8.8.
-
type='usb'
+
usb
USB addresses have the following additional attributes: bus (a hex value between 0 and 0xfff, inclusive), and port (a dotted notation of up to four octets, such as 1.2 or 2.1.3.1).
-
type='spapr-vio'
+
spapr-vio
On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It has a flat 64-bit address space; by convention, devices are generally assigned at a non-zero @@ -2962,7 +2965,7 @@ of the starting register). Since 0.9.9.
-
type='ccw'
+
ccw
s390 guests with a machine value of s390-ccw-virtio use the native CCW bus for I/O devices. CCW bus addresses have the following additional attributes: @@ -2975,7 +2978,7 @@ set to 0xfe. Since 1.0.4
-
type='isa'
+
isa
ISA addresses have the following additional attributes: iobase and irq. Since 1.2.1 @@ -3210,7 +3213,7 @@ downstream-port).

-
<node>
+
node
pci-expander-bus controllers can have an optional <node> subelement within @@ -3772,14 +3775,14 @@

-
mode='host'
+
host
The simplest operation, where the hypervisor relays all requests from the guest into direct access to the host's smartcard via NSS. No other attributes or sub-elements are required. See below about the use of an optional <address> sub-element.
-
mode='host-certificates'
+
host-certificates
Rather than requiring a smartcard to be plugged into the host, it is possible to provide three NSS certificate names residing in a database on the host. These certificates can be @@ -3793,7 +3796,7 @@ when creating the certificates); if not present, it defaults to /etc/pki/nssdb.
-
mode='passthrough'
+
passthrough
Rather than having the hypervisor directly communicate with the host, it is possible to tunnel all requests through a secondary character device to a third-party provider (which may @@ -4557,7 +4560,13 @@ qemu-kvm -net nic,model=? /dev/null virtio-net since 1.0.6 (QEMU and KVM only) vhost-user since 1.2.17 (QEMU and KVM only)
-
host offloading options
+
+

+ Offloading options for the host and guest can be configured using + the following sub-elements: +

+
+
host
The csum, gso, tso4, tso6, ecn and ufo @@ -4570,7 +4579,7 @@ qemu-kvm -net nic,model=? /dev/null on (default) and off. Since 1.2.13 (QEMU only)
-
guest offloading options
+
guest
The csum, tso4, tso6, ecn and ufo @@ -5059,7 +5068,7 @@ qemu-kvm -net nic,model=? /dev/null spice, rdp or desktop:

-
"sdl"
+
sdl

This displays a window on the host desktop, it can take 3 optional @@ -5069,7 +5078,7 @@ qemu-kvm -net nic,model=? /dev/null yes or no.

-
"vnc"
+
vnc

Starts a VNC server. The port attribute specifies @@ -5110,7 +5119,7 @@ qemu-kvm -net nic,model=? /dev/null security reasons) Since 1.0.6.

-
"spice" Since 0.8.6
+
spice Since 0.8.6

Starts a SPICE server. The port attribute specifies @@ -5216,7 +5225,7 @@ qemu-kvm -net nic,model=? /dev/null property. (QEMU only, since 1.3.2).

-
"rdp"
+
rdp

Starts a RDP server. The port attribute specifies the @@ -5231,7 +5240,7 @@ qemu-kvm -net nic,model=? /dev/null single connection mode.

-
"desktop"
+
desktop

This value is reserved for VirtualBox domains for the moment. It @@ -6230,29 +6239,27 @@ qemu-kvm -net nic,model=? /dev/null to be used for the domain. The source model is configured using the model attribute. Supported source models are:

-
    -
  • 'random' — /dev/random (default) or /dev/hwrng - device as source (for now, no other sources are permitted)
    • -
  • 'egd' — a EGD protocol backend
    • -
-
-
backend model='random'
-
-

- This backend type expects a non-blocking character device as input. - The only accepted paths are /dev/random and /dev/hwrng. The file - name is specified as contents of the backend element. - When no file name is specified the hypervisor default is used. -

-
-
backend model='egd'
-
-

- This backend connects to a source using the EGD protocol. - The source is specified as a character device. Refer to - character device host interface - for more information. -

+
+
random
+
+

+ This backend type expects a non-blocking character device as + input. The only accepted paths are /dev/random and /dev/hwrng. + The file name is specified as contents of the + backend element. When no file name is specified + the hypervisor default is used. +

+
+
egd
+
+

+ This backend connects to a source using the EGD protocol. + The source is specified as a character device. Refer to + character device host interface + for more information. +

+
+
@@ -6299,19 +6306,21 @@ qemu-kvm -net nic,model=? /dev/null The backend element specifies the type of TPM device. The following types are supported:

-
    -
  • 'passthrough' — use the host's TPM device.
    • -
-
-
backend type='passthrough'
-
-

- This backend type requires exclusive access to a TPM device on - the host. - An example for such a device is /dev/tpm0. The fully qualified file - name is specified by path attribute of the source element. - If no file name is specified then /dev/tpm0 is automatically used. -

+
+
passthrough
+
+

+ Use the host's TPM device. +

+

+ This backend type requires exclusive access to a TPM device on + the host. An example for such a device is /dev/tpm0. The fully + qualified file name is specified by path attribute of the + source element. If no file name is specified then + /dev/tpm0 is automatically used. +

+
+
diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in index 6abed8f64c..50dc751a0e 100644 --- a/docs/formatnetwork.html.in +++ b/docs/formatnetwork.html.in @@ -54,13 +54,14 @@ The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b. If omitted when defining/creating a new network, a random UUID is generated. Since 0.3.0
-
ipv6='yes'
-
The new, optional parameter ipv6='yes' enables +
ipv6
+
When set to yes, the optional parameter + ipv6 enables a network definition with no IPv6 gateway addresses specified to have guest-to-guest communications. For further information, see the example below for the example with no gateway addresses. Since 1.0.1
-
trustGuestRxFilters='yes'
+
trustGuestRxFilters
The optional parameter trustGuestRxFilters can be used to set that attribute of the same name for each domain interface connected to this network (since