mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-23 21:34:54 +03:00
0aa9f522c4
These are supported by nbd-server and by the NBD server that QEMU embeds for live image access. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com>
4496 lines
182 KiB
HTML
4496 lines
182 KiB
HTML
<html>
|
|
<body>
|
|
<h1>Domain XML format</h1>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<p>
|
|
This section describes the XML format used to represent domains, there are
|
|
variations on the format based on the kind of domains run and the options
|
|
used to launch them. For hypervisor specific details consult the
|
|
<a href="drivers.html">driver docs</a>
|
|
</p>
|
|
|
|
|
|
<h2><a name="elements">Element and attribute overview</a></h2>
|
|
|
|
<p>
|
|
The root element required for all virtual machines is
|
|
named <code>domain</code>. It has two attributes, the
|
|
<code>type</code> specifies the hypervisor used for running
|
|
the domain. The allowed values are driver specific, but
|
|
include "xen", "kvm", "qemu", "lxc" and "kqemu". The
|
|
second attribute is <code>id</code> which is a unique
|
|
integer identifier for the running guest machine. Inactive
|
|
machines have no id value.
|
|
</p>
|
|
|
|
|
|
<h3><a name="elementsMetadata">General metadata</a></h3>
|
|
|
|
<pre>
|
|
<domain type='xen' id='3'>
|
|
<name>fv0</name>
|
|
<uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
|
|
<title>A short description - title - of the domain</title>
|
|
<description>Some human readable description</description>
|
|
<metadata>
|
|
<app1:foo xmlns:app1="http://app1.org/app1/">..</app1:foo>
|
|
<app2:bar xmlns:app2="http://app1.org/app2/">..</app2:bar>
|
|
</metadata>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>The content of the <code>name</code> element provides
|
|
a short name for the virtual machine. This name should
|
|
consist only of alpha-numeric characters and is required
|
|
to be unique within the scope of a single host. It is
|
|
often used to form the filename for storing the persistent
|
|
configuration file. <span class="since">Since 0.0.1</span></dd>
|
|
<dt><code>uuid</code></dt>
|
|
<dd>The content of the <code>uuid</code> element provides
|
|
a globally unique identifier for the virtual machine.
|
|
The format must be RFC 4122 compliant,
|
|
eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
|
|
If omitted when defining/creating a new machine, a random
|
|
UUID is generated. It is also possible to provide the UUID
|
|
via a <a href="#elementsSysinfo"><code>sysinfo</code></a>
|
|
specification. <span class="since">Since 0.0.1, sysinfo
|
|
since 0.8.7</span></dd>
|
|
|
|
<dt><code>title</code></dt>
|
|
<dd>The optional element <code>title</code> provides space for a
|
|
short description of the domain. The title should not contain
|
|
any newlines. <span class="since">Since 0.9.10</span>.</dd>
|
|
|
|
<dt><code>description</code></dt>
|
|
<dd>The content of the <code>description</code> element provides a
|
|
human readable description of the virtual machine. This data is not
|
|
used by libvirt in any way, it can contain any information the user
|
|
wants. <span class="since">Since 0.7.2</span></dd>
|
|
|
|
<dt><code>metadata</code></dt>
|
|
<dd>The <code>metadata</code> node can be used by applications
|
|
to store custom metadata in the form of XML
|
|
nodes/trees. Applications must use custom namespaces on their
|
|
XML nodes/trees, with only one top-level element per namespace
|
|
(if the application needs structure, they should have
|
|
sub-elements to their namespace
|
|
element). <span class="since">Since 0.9.10</span></dd>
|
|
</dl>
|
|
|
|
<h3><a name="elementsOS">Operating system booting</a></h3>
|
|
|
|
<p>
|
|
There are a number of different ways to boot virtual machines
|
|
each with their own pros and cons.
|
|
</p>
|
|
|
|
<h4><a name="elementsOSBIOS">BIOS bootloader</a></h4>
|
|
|
|
<p>
|
|
Booting via the BIOS is available for hypervisors supporting
|
|
full virtualization. In this case the BIOS has a boot order
|
|
priority (floppy, harddisk, cdrom, network) determining where
|
|
to obtain/find the boot image.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<os>
|
|
<type>hvm</type>
|
|
<loader>/usr/lib/xen/boot/hvmloader</loader>
|
|
<boot dev='hd'/>
|
|
<boot dev='cdrom'/>
|
|
<bootmenu enable='yes'/>
|
|
<smbios mode='sysinfo'/>
|
|
<bios useserial='yes' rebootTimeout='0'/>
|
|
</os>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>type</code></dt>
|
|
<dd>The content of the <code>type</code> element specifies the
|
|
type of operating system to be booted in the virtual machine.
|
|
<code>hvm</code> indicates that the OS is one designed to run
|
|
on bare metal, so requires full virtualization. <code>linux</code>
|
|
(badly named!) refers to an OS that supports the Xen 3 hypervisor
|
|
guest ABI. There are also two optional attributes, <code>arch</code>
|
|
specifying the CPU architecture to virtualization,
|
|
and <code>machine</code> referring to the machine
|
|
type. The <a href="formatcaps.html">Capabilities XML</a>
|
|
provides details on allowed values for
|
|
these. <span class="since">Since 0.0.1</span></dd>
|
|
<dt><code>loader</code></dt>
|
|
<dd>The optional <code>loader</code> tag refers to a firmware blob
|
|
used to assist the domain creation process. At this time, it is
|
|
only needed by Xen fully virtualized
|
|
domains. <span class="since">Since 0.1.0</span></dd>
|
|
<dt><code>boot</code></dt>
|
|
<dd>The <code>dev</code> attribute takes one of the values "fd", "hd",
|
|
"cdrom" or "network" and is used to specify the next boot device
|
|
to consider. The <code>boot</code> element can be repeated multiple
|
|
times to setup a priority list of boot devices to try in turn.
|
|
Multiple devices of the same type are sorted according to their
|
|
targets while preserving the order of buses. After defining the
|
|
domain, its XML configuration returned by libvirt (through
|
|
virDomainGetXMLDesc) lists devices in the sorted order. Once sorted,
|
|
the first device is marked as bootable. Thus, e.g., a domain
|
|
configured to boot from "hd" with vdb, hda, vda, and hdc disks
|
|
assigned to it will boot from vda (the sorted list is vda, vdb, hda,
|
|
hdc). Similar domain with hdc, vda, vdb, and hda disks will boot from
|
|
hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to
|
|
configure in the desired way, which is why per-device boot elements
|
|
(see <a href="#elementsDisks">disks</a>,
|
|
<a href="#elementsNICS">network interfaces</a>, and
|
|
<a href="#elementsUSB">USB and PCI devices</a> sections below) were
|
|
introduced and they are the preferred way providing full control over
|
|
booting order. The <code>boot</code> element and per-device boot
|
|
elements are mutually exclusive. <span class="since">Since 0.1.3,
|
|
per-device boot since 0.8.8</span>
|
|
</dd>
|
|
<dt><code>bootmenu</code></dt>
|
|
<dd> Whether or not to enable an interactive boot menu prompt on guest
|
|
startup. The <code>enable</code> attribute can be either "yes" or "no".
|
|
If not specified, the hypervisor default is used. <span class="since">
|
|
Since 0.8.3</span>
|
|
</dd>
|
|
<dt><code>smbios</code></dt>
|
|
<dd>How to populate SMBIOS information visible in the guest.
|
|
The <code>mode</code> attribute must be specified, and is either
|
|
"emulate" (let the hypervisor generate all values), "host" (copy
|
|
all of Block 0 and Block 1, except for the UUID, from the host's
|
|
SMBIOS values;
|
|
the <a href="html/libvirt-libvirt.html#virConnectGetSysinfo">
|
|
<code>virConnectGetSysinfo</code></a> call can be
|
|
used to see what values are copied), or "sysinfo" (use the values in
|
|
the <a href="#elementsSysinfo">sysinfo</a> element). If not
|
|
specified, the hypervisor default is used. <span class="since">
|
|
Since 0.8.7</span>
|
|
</dd>
|
|
<dt><code>bios</code></dt>
|
|
<dd>This element has attribute <code>useserial</code> with possible
|
|
values <code>yes</code> or <code>no</code>. It enables or disables
|
|
Serial Graphics Adapter which allows users to see BIOS messages
|
|
on a serial port. Therefore, one needs to have
|
|
<a href="#elementCharSerial">serial port</a> defined.
|
|
<span class="since">Since 0.9.4</span>.
|
|
<span class="since">Since 0.10.2 (QEMU only)</span> there is
|
|
another attribute, <code>rebootTimeout</code> that controls
|
|
whether and after how long the guest should start booting
|
|
again in case the boot fails (according to BIOS). The value is
|
|
in milliseconds with maximum of <code>65535</code> and special
|
|
value <code>-1</code> disables the reboot.
|
|
</dl>
|
|
|
|
<h4><a name="elementsOSBootloader">Host bootloader</a></h4>
|
|
|
|
<p>
|
|
Hypervisors employing paravirtualization do not usually emulate
|
|
a BIOS, and instead the host is responsible to kicking off the
|
|
operating system boot. This may use a pseudo-bootloader in the
|
|
host to provide an interface to choose a kernel for the guest.
|
|
An example is <code>pygrub</code> with Xen.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<bootloader>/usr/bin/pygrub</bootloader>
|
|
<bootloader_args>--append single</bootloader_args>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>bootloader</code></dt>
|
|
<dd>The content of the <code>bootloader</code> element provides
|
|
a fully qualified path to the bootloader executable in the
|
|
host OS. This bootloader will be run to choose which kernel
|
|
to boot. The required output of the bootloader is dependent
|
|
on the hypervisor in use. <span class="since">Since 0.1.0</span></dd>
|
|
<dt><code>bootloader_args</code></dt>
|
|
<dd>The optional <code>bootloader_args</code> element allows
|
|
command line arguments to be passed to the bootloader.
|
|
<span class="since">Since 0.2.3</span>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h4><a name="elementsOSKernel">Direct kernel boot</a></h4>
|
|
|
|
<p>
|
|
When installing a new guest OS it is often useful to boot directly
|
|
from a kernel and initrd stored in the host OS, allowing command
|
|
line arguments to be passed directly to the installer. This capability
|
|
is usually available for both para and full virtualized guests.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<os>
|
|
<type>hvm</type>
|
|
<loader>/usr/lib/xen/boot/hvmloader</loader>
|
|
<kernel>/root/f8-i386-vmlinuz</kernel>
|
|
<initrd>/root/f8-i386-initrd</initrd>
|
|
<cmdline>console=ttyS0 ks=http://example.com/f8-i386/os/</cmdline>
|
|
</os>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>type</code></dt>
|
|
<dd>This element has the same semantics as described earlier in the
|
|
<a href="#elementsOSBIOS">BIOS boot section</a></dd>
|
|
<dt><code>loader</code></dt>
|
|
<dd>This element has the same semantics as described earlier in the
|
|
<a href="#elementsOSBIOS">BIOS boot section</a></dd>
|
|
<dt><code>kernel</code></dt>
|
|
<dd>The contents of this element specify the fully-qualified path
|
|
to the kernel image in the host OS.</dd>
|
|
<dt><code>initrd</code></dt>
|
|
<dd>The contents of this element specify the fully-qualified path
|
|
to the (optional) ramdisk image in the host OS.</dd>
|
|
<dt><code>cmdline</code></dt>
|
|
<dd>The contents of this element specify arguments to be passed to
|
|
the kernel (or installer) at boottime. This is often used to
|
|
specify an alternate primary console (eg serial port), or the
|
|
installation media source / kickstart file</dd>
|
|
</dl>
|
|
|
|
<h4><a name="eleemntsOSContainer">Container boot</a></h4>
|
|
|
|
<p>
|
|
When booting a domain using container based virtualization, instead
|
|
of a kernel / boot image, a path to the init binary is required, using
|
|
the <code>init</code> element. By default this will be launched with
|
|
no arguments. To specify the initial argv, use the <code>initarg</code>
|
|
element, repeated as many time as is required. The <code>cmdline</code>
|
|
element, if set will be used to provide an equivalent to <code>/proc/cmdline</code>
|
|
but will not effect init argv.
|
|
</p>
|
|
|
|
<pre>
|
|
<os>
|
|
<type arch='x86_64'>exe</type>
|
|
<init>/bin/systemd</init>
|
|
<initarg>--unit</initarg>
|
|
<initarg>emergency.service</initarg>
|
|
</os>
|
|
</pre>
|
|
|
|
|
|
<h3><a name="elementsSysinfo">SMBIOS System Information</a></h3>
|
|
|
|
<p>
|
|
Some hypervisors allow control over what system information is
|
|
presented to the guest (for example, SMBIOS fields can be
|
|
populated by a hypervisor and inspected via
|
|
the <code>dmidecode</code> command in the guest). The
|
|
optional <code>sysinfo</code> element covers all such categories
|
|
of information. <span class="since">Since 0.8.7</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<os>
|
|
<smbios mode='sysinfo'/>
|
|
...
|
|
</os>
|
|
<sysinfo type='smbios'>
|
|
<bios>
|
|
<entry name='vendor'>LENOVO</entry>
|
|
</bios>
|
|
<system>
|
|
<entry name='manufacturer'>Fedora</entry>
|
|
<entry name='vendor'>Virt-Manager</entry>
|
|
</system>
|
|
</sysinfo>
|
|
...</pre>
|
|
|
|
<p>
|
|
The <code>sysinfo</code> element has a mandatory
|
|
attribute <code>type</code> that determine the layout of
|
|
sub-elements, with supported values of:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>smbios</code></dt>
|
|
<dd>Sub-elements call out specific SMBIOS values, which will
|
|
affect the guest if used in conjunction with
|
|
the <code>smbios</code> sub-element of
|
|
the <a href="#elementsOS"><code>os</code></a> element. Each
|
|
sub-element of <code>sysinfo</code> names a SMBIOS block, and
|
|
within those elements can be a list of <code>entry</code>
|
|
elements that describe a field within the block. The following
|
|
blocks and entries are recognized:
|
|
<dl>
|
|
<dt><code>bios</code></dt>
|
|
<dd>
|
|
This is block 0 of SMBIOS, with entry names drawn from
|
|
"vendor", "version", "date", and "release".
|
|
</dd>
|
|
<dt><code>system</code></dt>
|
|
<dd>
|
|
This is block 1 of SMBIOS, with entry names drawn from
|
|
"manufacturer", "product", "version", "serial", "uuid",
|
|
"sku", and "family". If a "uuid" entry is provided
|
|
alongside a
|
|
top-level <a href="#elementsMetadata"><code>uuid</code>
|
|
element</a>, the two values must match.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a name="elementsCPUAllocation">CPU Allocation</a></h3>
|
|
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<vcpu placement='static' cpuset="1-4,^3,6" current="1">2</vcpu>
|
|
...
|
|
</domain>
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>vcpu</code></dt>
|
|
<dd>The content of this element defines the maximum number of virtual
|
|
CPUs allocated for the guest OS, which must be between 1 and
|
|
the maximum supported by the hypervisor. <span class="since">Since
|
|
0.4.4</span>, this element can contain an optional
|
|
<code>cpuset</code> attribute, which is a comma-separated
|
|
list of physical CPU numbers that domain process and virtual CPUs
|
|
can be pinned to by default. (NB: The pinning policy of domain
|
|
process and virtual CPUs can be specified separately by
|
|
<code>cputune</code>. If attribute <code>emulatorpin</code>
|
|
of <code>cputune</code> is specified, <code>cpuset</code>
|
|
specified by <code>vcpu</code> here will be ingored; Similarly,
|
|
For virtual CPUs which has <code>vcpupin</code> specified,
|
|
<code>cpuset</code> specified by <code>cpuset</code> here
|
|
will be ignored; For virtual CPUs which doesn't have
|
|
<code>vcpupin</code> specified, it will be pinned to the physical
|
|
CPUs specified by <code>cpuset</code> here).
|
|
Each element in that list is either a single CPU number,
|
|
a range of CPU numbers, or a caret followed by a CPU number to
|
|
be excluded from a previous range. <span class="since">Since
|
|
0.8.5</span>, the optional attribute <code>current</code> can
|
|
be used to specify whether fewer than the maximum number of
|
|
virtual CPUs should be enabled. <span class="since">Since
|
|
0.9.11 (QEMU and KVM only)</span>, the optional attribute
|
|
<code>placement</code> can be used to indicate the CPU placement
|
|
mode for domain process, its value can be either "static" or
|
|
"auto", defaults to <code>placement</code> of <code>numatune</code>,
|
|
or "static" if <code>cpuset</code> is specified. "auto" indicates
|
|
the domain process will be pinned to the advisory nodeset from querying
|
|
numad, and the value of attribute <code>cpuset</code> will be ignored
|
|
if it's specified. If both <code>cpuset</code> and <code>placement</code>
|
|
are not specified, or if <code>placement</code> is "static", but no
|
|
<code>cpuset</code> is specified, the domain process will be pinned to
|
|
all the available physical CPUs.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsCPUTuning">CPU Tuning</a></h3>
|
|
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<cputune>
|
|
<vcpupin vcpu="0" cpuset="1-4,^2"/>
|
|
<vcpupin vcpu="1" cpuset="0,1"/>
|
|
<vcpupin vcpu="2" cpuset="2,3"/>
|
|
<vcpupin vcpu="3" cpuset="0,4"/>
|
|
<emulatorpin cpuset="1-3"/>
|
|
<shares>2048</shares>
|
|
<period>1000000</period>
|
|
<quota>-1</quota>
|
|
<emulator_period>1000000</emulator_period>
|
|
<emulator_quota>-1</emulator_quota>
|
|
</cputune>
|
|
...
|
|
</domain>
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>cputune</code></dt>
|
|
<dd>
|
|
The optional <code>cputune</code> element provides details
|
|
regarding the cpu tunable parameters for the domain.
|
|
<span class="since">Since 0.9.0</span>
|
|
</dd>
|
|
<dt><code>vcpupin</code></dt>
|
|
<dd>
|
|
The optional <code>vcpupin</code> element specifies which of host's
|
|
physical CPUs the domain VCPU will be pinned to. If this is omitted,
|
|
and attribute <code>cpuset</code> of element <code>vcpu</code> is
|
|
not specified, the vCPU is pinned to all the physical CPUs by default.
|
|
It contains two required attributes, the attribute <code>vcpu</code>
|
|
specifies vcpu id, and the attribute <code>cpuset</code> is same as
|
|
attribute <code>cpuset</code> of element <code>vcpu</code>.
|
|
(NB: Only qemu driver support)
|
|
<span class="since">Since 0.9.0</span>
|
|
</dd>
|
|
<dt><code>emulatorpin</code></dt>
|
|
<dd>
|
|
The optional <code>emulatorpin</code> element specifies which of host
|
|
physical CPUs the "emulator", a subset of a domain not including vcpu,
|
|
will be pinned to. If this is omitted, and attribute
|
|
<code>cpuset</code> of element <code>vcpu</code> is not specified,
|
|
"emulator" is pinned to all the physical CPUs by default. It contains
|
|
one required attribute <code>cpuset</code> specifying which physical
|
|
CPUs to pin to. NB, <code>emulatorpin</code> is not allowed if
|
|
attribute <code>placement</code> of element <code>vcpu</code> is
|
|
"auto".
|
|
</dd>
|
|
<dt><code>shares</code></dt>
|
|
<dd>
|
|
The optional <code>shares</code> element specifies the proportional
|
|
weighted share for the domain. If this is omitted, it defaults to
|
|
the OS provided defaults. NB, There is no unit for the value,
|
|
it's a relative measure based on the setting of other VM,
|
|
e.g. A VM configured with value
|
|
2048 will get twice as much CPU time as a VM configured with value 1024.
|
|
<span class="since">Since 0.9.0</span>
|
|
</dd>
|
|
<dt><code>period</code></dt>
|
|
<dd>
|
|
The optional <code>period</code> element specifies the enforcement
|
|
interval(unit: microseconds). Within <code>period</code>, each vcpu of
|
|
the domain will not be allowed to consume more than <code>quota</code>
|
|
worth of runtime. The value should be in range [1000, 1000000]. A period
|
|
with value 0 means no value.
|
|
<span class="since">Only QEMU driver support since 0.9.4, LXC since
|
|
0.9.10</span>
|
|
</dd>
|
|
<dt><code>quota</code></dt>
|
|
<dd>
|
|
The optional <code>quota</code> element specifies the maximum allowed
|
|
bandwidth(unit: microseconds). A domain with <code>quota</code> as any
|
|
negative value indicates that the domain has infinite bandwidth, which
|
|
means that it is not bandwidth controlled. The value should be in range
|
|
[1000, 18446744073709551] or less than 0. A quota with value 0 means no
|
|
value. You can use this feature to ensure that all vcpus run at the same
|
|
speed.
|
|
<span class="since">Only QEMU driver support since 0.9.4, LXC since
|
|
0.9.10</span>
|
|
</dd>
|
|
|
|
<dt><code>emulator_period</code></dt>
|
|
<dd>
|
|
The optional <code>emulator_period</code> element specifies the enforcement
|
|
interval(unit: microseconds). Within <code>emulator_period</code>, emulator
|
|
threads(those excluding vcpus) of the domain will not be allowed to consume
|
|
more than <code>emulator_quota</code> worth of runtime. The value should be
|
|
in range [1000, 1000000]. A period with value 0 means no value.
|
|
<span class="since">Only QEMU driver support since 0.10.0</span>
|
|
</dd>
|
|
<dt><code>emulator_quota</code></dt>
|
|
<dd>
|
|
The optional <code>emulator_quota</code> element specifies the maximum
|
|
allowed bandwidth(unit: microseconds) for domain's emulator threads(those
|
|
excluding vcpus). A domain with <code>emulator_quota</code> as any negative
|
|
value indicates that the domain has infinite bandwidth for emulator threads
|
|
(those excluding vcpus), which means that it is not bandwidth controlled.
|
|
The value should be in range [1000, 18446744073709551] or less than 0. A
|
|
quota with value 0 means no value.
|
|
<span class="since">Only QEMU driver support since 0.10.0</span>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsMemoryAllocation">Memory Allocation</a></h3>
|
|
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<memory unit='KiB'>524288</memory>
|
|
<currentMemory unit='KiB'>524288</currentMemory>
|
|
...
|
|
</domain>
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>memory</code></dt>
|
|
<dd>The maximum allocation of memory for the guest at boot time.
|
|
The units for this value are determined by the optional
|
|
attribute <code>unit</code>, which defaults to "KiB"
|
|
(kibibytes, 2<sup>10</sup> or blocks of 1024 bytes). Valid
|
|
units are "b" or "bytes" for bytes, "KB" for kilobytes
|
|
(10<sup>3</sup> or 1,000 bytes), "k" or "KiB" for kibibytes
|
|
(1024 bytes), "MB" for megabytes (10<sup>6</sup> or 1,000,000
|
|
bytes), "M" or "MiB" for mebibytes (2<sup>20</sup> or
|
|
1,048,576 bytes), "GB" for gigabytes (10<sup>9</sup> or
|
|
1,000,000,000 bytes), "G" or "GiB" for gibibytes
|
|
(2<sup>30</sup> or 1,073,741,824 bytes), "TB" for terabytes
|
|
(10<sup>12</sup> or 1,000,000,000,000 bytes), or "T" or "TiB"
|
|
for tebibytes (2<sup>40</sup> or 1,099,511,627,776 bytes).
|
|
However, the value will be rounded up to the nearest kibibyte
|
|
by libvirt, and may be further rounded to the granularity
|
|
supported by the hypervisor. Some hypervisors also enforce a
|
|
minimum, such as 4000KiB.
|
|
|
|
In the case of crash, optional attribute <code>dumpCore</code>
|
|
can be used to control whether the guest memory should be
|
|
included in the generated coredump or not (values "on", "off").
|
|
|
|
<span class='since'><code>unit</code> since 0.9.11</span>,
|
|
<span class='since'><code>dumpCore</code> since 0.10.2
|
|
(QEMU only)</span></dd>
|
|
<dt><code>currentMemory</code></dt>
|
|
<dd>The actual allocation of memory for the guest. This value can
|
|
be less than the maximum allocation, to allow for ballooning
|
|
up the guests memory on the fly. If this is omitted, it defaults
|
|
to the same value as the <code>memory</code> element.
|
|
The <code>unit</code> attribute behaves the same as
|
|
for <code>memory</code>.</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsMemoryBacking">Memory Backing</a></h3>
|
|
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<memoryBacking>
|
|
<hugepages/>
|
|
</memoryBacking>
|
|
...
|
|
</domain>
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>memoryBacking</code></dt>
|
|
<dd>The optional <code>memoryBacking</code> element, may have an
|
|
<code>hugepages</code> element set within it. This tells the
|
|
hypervisor that the guest should have its memory allocated using
|
|
hugepages instead of the normal native page size.</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsMemoryTuning">Memory Tuning</a></h3>
|
|
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<memtune>
|
|
<hard_limit unit='G'>1</hard_limit>
|
|
<soft_limit unit='M'>128</soft_limit>
|
|
<swap_hard_limit unit='G'>2</swap_hard_limit>
|
|
<min_guarantee unit='bytes'>67108864</min_guarantee>
|
|
</memtune>
|
|
...
|
|
</domain>
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>memtune</code></dt>
|
|
<dd> The optional <code>memtune</code> element provides details
|
|
regarding the memory tunable parameters for the domain. If this is
|
|
omitted, it defaults to the OS provided defaults. For QEMU/KVM, the
|
|
parameters are applied to the QEMU process as a whole. Thus, when
|
|
counting them, one needs to add up guest RAM, guest video RAM, and
|
|
some memory overhead of QEMU itself. The last piece is hard to
|
|
determine so one needs guess and try. For each tunable, it
|
|
is possible to designate which unit the number is in on
|
|
input, using the same values as
|
|
for <code><memory></code>. For backwards
|
|
compatibility, output is always in
|
|
KiB. <span class='since'><code>unit</code>
|
|
since 0.9.11</span></dd>
|
|
<dt><code>hard_limit</code></dt>
|
|
<dd> The optional <code>hard_limit</code> element is the maximum memory
|
|
the guest can use. The units for this value are kibibytes (i.e. blocks
|
|
of 1024 bytes)</dd>
|
|
<dt><code>soft_limit</code></dt>
|
|
<dd> The optional <code>soft_limit</code> element is the memory limit to
|
|
enforce during memory contention. The units for this value are
|
|
kibibytes (i.e. blocks of 1024 bytes)</dd>
|
|
<dt><code>swap_hard_limit</code></dt>
|
|
<dd> The optional <code>swap_hard_limit</code> element is the maximum
|
|
memory plus swap the guest can use. The units for this value are
|
|
kibibytes (i.e. blocks of 1024 bytes). This has to be more than
|
|
hard_limit value provided</dd>
|
|
<dt><code>min_guarantee</code></dt>
|
|
<dd> The optional <code>min_guarantee</code> element is the guaranteed
|
|
minimum memory allocation for the guest. The units for this value are
|
|
kibibytes (i.e. blocks of 1024 bytes)</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsNUMATuning">NUMA Node Tuning</a></h3>
|
|
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<numatune>
|
|
<memory mode="strict" nodeset="1-4,^3"/>
|
|
</numatune>
|
|
...
|
|
</domain>
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>numatune</code></dt>
|
|
<dd>
|
|
The optional <code>numatune</code> element provides details of
|
|
how to tune the performance of a NUMA host via controlling NUMA policy
|
|
for domain process. NB, only supported by QEMU driver.
|
|
<span class='since'>Since 0.9.3</span>
|
|
<dt><code>memory</code></dt>
|
|
<dd>
|
|
The optional <code>memory</code> element specifies how to allocate memory
|
|
for the domain process on a NUMA host. It contains several optional
|
|
attributes. Attribute <code>mode</code> is either 'interleave',
|
|
'strict', or 'preferred', defaults to 'strict'. Attribute
|
|
<code>nodeset</code> specifies the NUMA nodes, using the same syntax as
|
|
attribute <code>cpuset</code> of element <code>vcpu</code>. Attribute
|
|
<code>placement</code> (<span class='since'>since 0.9.12</span>) can be
|
|
used to indicate the memory placement mode for domain process, its value
|
|
can be either "static" or "auto", defaults to <code>placement</code> of
|
|
<code>vcpu</code>, or "static" if <code>nodeset</code> is specified.
|
|
"auto" indicates the domain process will only allocate memory from the
|
|
advisory nodeset returned from querying numad, and the value of attribute
|
|
<code>nodeset</code> will be ignored if it's specified.
|
|
|
|
If <code>placement</code> of <code>vcpu</code> is 'auto', and
|
|
<code>numatune</code> is not specified, a default <code>numatune</code>
|
|
with <code>placement</code> 'auto' and <code>mode</code> 'strict' will
|
|
be added implicitly.
|
|
|
|
<span class='since'>Since 0.9.3</span>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsBlockTuning">Block I/O Tuning</a></h3>
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<blkiotune>
|
|
<weight>800</weight>
|
|
<device>
|
|
<path>/dev/sda</path>
|
|
<weight>1000</weight>
|
|
</device>
|
|
<device>
|
|
<path>/dev/sdb</path>
|
|
<weight>500</weight>
|
|
</device>
|
|
</blkiotune>
|
|
...
|
|
</domain>
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>blkiotune</code></dt>
|
|
<dd> The optional <code>blkiotune</code> element provides the ability
|
|
to tune Blkio cgroup tunable parameters for the domain. If this is
|
|
omitted, it defaults to the OS provided
|
|
defaults. <span class="since">Since 0.8.8</span></dd>
|
|
<dt><code>weight</code></dt>
|
|
<dd> The optional <code>weight</code> element is the overall I/O
|
|
weight of the guest. The value should be in the range [100,
|
|
1000].</dd>
|
|
<dt><code>device</code></dt>
|
|
<dd>The domain may have multiple <code>device</code> elements
|
|
that further tune the weights for each host block device in
|
|
use by the domain. Note that
|
|
multiple <a href="#elementsDisks">guest disks</a> can share a
|
|
single host block device, if they are backed by files within
|
|
the same host file system, which is why this tuning parameter
|
|
is at the global domain level rather than associated with each
|
|
guest disk device (contrast this to
|
|
the <a href="#elementsDisks"><code><iotune></code></a>
|
|
element which can apply to an
|
|
individual <code><disk></code>).
|
|
Each <code>device</code> element has two
|
|
mandatory sub-elements, <code>path</code> describing the
|
|
absolute path of the device, and <code>weight</code> giving
|
|
the relative weight of that device, in the range [100,
|
|
1000]. <span class="since">Since 0.9.8</span></dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsCPU">CPU model and topology</a></h3>
|
|
|
|
<p>
|
|
Requirements for CPU model, its features and topology can be specified
|
|
using the following collection of elements.
|
|
<span class="since">Since 0.7.5</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<cpu match='exact'>
|
|
<model fallback='allow'>core2duo</model>
|
|
<vendor>Intel</vendor>
|
|
<topology sockets='1' cores='2' threads='1'/>
|
|
<feature policy='disable' name='lahf_lm'/>
|
|
</cpu>
|
|
...</pre>
|
|
|
|
<pre>
|
|
<cpu mode='host-model'>
|
|
<model fallback='forbid'/>
|
|
<topology sockets='1' cores='2' threads='1'/>
|
|
</cpu>
|
|
...</pre>
|
|
|
|
<pre>
|
|
<cpu mode='host-passthrough'/>
|
|
...</pre>
|
|
|
|
<p>
|
|
In case no restrictions need to be put on CPU model and its features, a
|
|
simpler <code>cpu</code> element can be used.
|
|
<span class="since">Since 0.7.6</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<cpu>
|
|
<topology sockets='1' cores='2' threads='1'/>
|
|
</cpu>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>cpu</code></dt>
|
|
<dd>The <code>cpu</code> element is the main container for describing
|
|
guest CPU requirements. Its <code>match</code> attribute specified how
|
|
strictly has the virtual CPU provided to the guest match these
|
|
requirements. <span class="since">Since 0.7.6</span> the
|
|
<code>match</code> attribute can be omitted if <code>topology</code>
|
|
is the only element within <code>cpu</code>. Possible values for the
|
|
<code>match</code> attribute are:
|
|
|
|
<dl>
|
|
<dt><code>minimum</code></dt>
|
|
<dd>The specified CPU model and features describes the minimum
|
|
requested CPU.</dd>
|
|
<dt><code>exact</code></dt>
|
|
<dd>The virtual CPU provided to the guest will exactly match the
|
|
specification</dd>
|
|
<dt><code>strict</code></dt>
|
|
<dd>The guest will not be created unless the host CPU does exactly
|
|
match the specification.</dd>
|
|
</dl>
|
|
|
|
<span class="since">Since 0.8.5</span> the <code>match</code>
|
|
attribute can be omitted and will default to <code>exact</code>.
|
|
|
|
<span class="since">Since 0.9.10</span>, an optional <code>mode</code>
|
|
attribute may be used to make it easier to configure a guest CPU to be
|
|
as close to host CPU as possible. Possible values for the
|
|
<code>mode</code> attribute are:
|
|
|
|
<dl>
|
|
<dt><code>custom</code></dt>
|
|
<dd>In this mode, the <code>cpu</code> element describes the CPU
|
|
that should be presented to the guest. This is the default when no
|
|
<code>mode</code> attribute is specified. This mode makes it so that
|
|
a persistent guest will see the same hardware no matter what host
|
|
the guest is booted on.</dd>
|
|
<dt><code>host-model</code></dt>
|
|
<dd>The <code>host-model</code> mode is essentially a shortcut to
|
|
copying host CPU definition from capabilities XML into domain XML.
|
|
Since the CPU definition is copied just before starting a domain,
|
|
exactly the same XML can be used on different hosts while still
|
|
providing the best guest CPU each host supports. Neither
|
|
<code>match</code> attribute nor any <code>feature</code> elements
|
|
can be used in this mode. Specifying CPU model is not supported
|
|
either, but <code>model</code>'s <code>fallback</code> attribute may
|
|
still be used. Libvirt does not model every aspect of each CPU so
|
|
the guest CPU will not match the host CPU exactly. On the other
|
|
hand, the ABI provided to the guest is reproducible. During
|
|
migration, complete CPU model definition is transferred to the
|
|
destination host so the migrated guest will see exactly the same CPU
|
|
model even if the destination host contains more capable CPUs for
|
|
the running instance of the guest; but shutting down and restarting
|
|
the guest may present different hardware to the guest according to
|
|
the capabilities of the new host.</dd>
|
|
<dt><code>host-passthrough</code></dt>
|
|
<dd>With this mode, the CPU visible to the guest should be exactly
|
|
the same as the host CPU even in the aspects that libvirt does not
|
|
understand. Though the downside of this mode is that the guest
|
|
environment cannot be reproduced on different hardware. Thus, if you
|
|
hit any bugs, you are on your own. Neither <code>model</code> nor
|
|
<code>feature</code> elements are allowed in this mode.</dd>
|
|
</dl>
|
|
|
|
In both <code>host-model</code> and <code>host-passthrough</code>
|
|
mode, the real (approximate in <code>host-passthrough</code> mode) CPU
|
|
definition which would be used on current host can be determined by
|
|
specifying <code>VIR_DOMAIN_XML_UPDATE_CPU</code> flag when calling
|
|
<code>virDomainGetXMLDesc</code> API. When running a guest that might
|
|
be prone to operating system reactivation when presented with
|
|
different hardware, and which will be migrated between hosts with
|
|
different capabilities, you can use this output to rewrite XML to the
|
|
<code>custom</code> mode for more robust migration.
|
|
</dd>
|
|
|
|
<dt><code>model</code></dt>
|
|
<dd>The content of the <code>model</code> element specifies CPU model
|
|
requested by the guest. The list of available CPU models and their
|
|
definition can be found in <code>cpu_map.xml</code> file installed
|
|
in libvirt's data directory. If a hypervisor is not able to use the
|
|
exact CPU model, libvirt automatically falls back to a closest model
|
|
supported by the hypervisor while maintaining the list of CPU
|
|
features. <span class="since">Since 0.9.10</span>, an optional
|
|
<code>fallback</code> attribute can be used to forbid this behavior,
|
|
in which case an attempt to start a domain requesting an unsupported
|
|
CPU model will fail. Supported values for <code>fallback</code>
|
|
attribute are: <code>allow</code> (this is the default), and
|
|
<code>forbid</code>. The optional <code>vendor_id</code> attribute
|
|
(<span class="since">Since 0.10.0</span>) can be used to set the
|
|
vendor id seen by the guest. It must be exactly 12 characters long.
|
|
If not set the vendor id of the host is used. Typical possible
|
|
values are "AuthenticAMD" and "GenuineIntel".</dd>
|
|
|
|
<dt><code>vendor</code></dt>
|
|
<dd><span class="since">Since 0.8.3</span> the content of the
|
|
<code>vendor</code> element specifies CPU vendor requested by the
|
|
guest. If this element is missing, the guest can be run on a CPU
|
|
matching given features regardless on its vendor. The list of
|
|
supported vendors can be found in <code>cpu_map.xml</code>.</dd>
|
|
|
|
<dt><code>topology</code></dt>
|
|
<dd>The <code>topology</code> element specifies requested topology of
|
|
virtual CPU provided to the guest. Three non-zero values have to be
|
|
given for <code>sockets</code>, <code>cores</code>, and
|
|
<code>threads</code>: total number of CPU sockets, number of cores per
|
|
socket, and number of threads per core, respectively.</dd>
|
|
|
|
<dt><code>feature</code></dt>
|
|
<dd>The <code>cpu</code> element can contain zero or more
|
|
<code>elements</code> used to fine-tune features provided by the
|
|
selected CPU model. The list of known feature names can be found in
|
|
the same file as CPU models. The meaning of each <code>feature</code>
|
|
element depends on its <code>policy</code> attribute, which has to be
|
|
set to one of the following values:
|
|
|
|
<dl>
|
|
<dt><code>force</code></dt>
|
|
<dd>The virtual CPU will claim the feature is supported regardless
|
|
of it being supported by host CPU.</dd>
|
|
<dt><code>require</code></dt>
|
|
<dd>Guest creation will fail unless the feature is supported by host
|
|
CPU.</dd>
|
|
<dt><code>optional</code></dt>
|
|
<dd>The feature will be supported by virtual CPU if and only if it
|
|
is supported by host CPU.</dd>
|
|
<dt><code>disable</code></dt>
|
|
<dd>The feature will not be supported by virtual CPU.</dd>
|
|
<dt><code>forbid</code></dt>
|
|
<dd>Guest creation will fail if the feature is supported by host
|
|
CPU.</dd>
|
|
</dl>
|
|
|
|
<span class="since">Since 0.8.5</span> the <code>policy</code>
|
|
attribute can be omitted and will default to <code>require</code>.
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
Guest NUMA topology can be specifed using the <code>numa</code> element.
|
|
<span class="since">Since 0.9.8</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<cpu>
|
|
...
|
|
<numa>
|
|
<cell cpus='0-3' memory='512000'/>
|
|
<cell cpus='4-7' memory='512000'/>
|
|
</numa>
|
|
...
|
|
</cpu>
|
|
...</pre>
|
|
|
|
<p>
|
|
Each <code>cell</code> element specifies a NUMA cell or a NUMA node.
|
|
<code>cpus</code> specifies the CPU or range of CPUs that are part of
|
|
the node. <code>memory</code> specifies the node memory in kibibytes
|
|
(i.e. blocks of 1024 bytes). Each cell or node is assigned cellid
|
|
or nodeid in the increasing order starting from 0.
|
|
</p>
|
|
|
|
<p>
|
|
This guest NUMA specification is currently available only for QEMU/KVM.
|
|
</p>
|
|
|
|
<h3><a name="elementsEvents">Events configuration</a></h3>
|
|
|
|
<p>
|
|
It is sometimes necessary to override the default actions taken
|
|
on various events.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<on_poweroff>destroy</on_poweroff>
|
|
<on_reboot>restart</on_reboot>
|
|
<on_crash>restart</on_crash>
|
|
<on_lockfailure>poweroff</on_lockfailure>
|
|
...</pre>
|
|
|
|
<p>
|
|
The following collections of elements allow the actions to be
|
|
specified when a guest OS triggers a lifecycle operation. A
|
|
common use case is to force a reboot to be treated as a poweroff
|
|
when doing the initial OS installation. This allows the VM to be
|
|
re-configured for the first post-install bootup.
|
|
</p>
|
|
<dl>
|
|
<dt><code>on_poweroff</code></dt>
|
|
<dd>The content of this element specifies the action to take when
|
|
the guest requests a poweroff.</dd>
|
|
<dt><code>on_reboot</code></dt>
|
|
<dd>The content of this element specifies the action to take when
|
|
the guest requests a reboot.</dd>
|
|
<dt><code>on_crash</code></dt>
|
|
<dd>The content of this element specifies the action to take when
|
|
the guest crashes.</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
Each of these states allow for the same four possible actions.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>destroy</code></dt>
|
|
<dd>The domain will be terminated completely and all resources
|
|
released</dd>
|
|
<dt><code>restart</code></dt>
|
|
<dd>The domain will be terminated, and then restarted with
|
|
the same configuration</dd>
|
|
<dt><code>preserve</code></dt>
|
|
<dd>The domain will be terminated, and its resource preserved
|
|
to allow analysis.</dd>
|
|
<dt><code>rename-restart</code></dt>
|
|
<dd>The domain will be terminated, and then restarted with
|
|
a new name</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
on_crash supports these additional
|
|
actions <span class="since">since 0.8.4</span>.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>coredump-destroy</code></dt>
|
|
<dd>The crashed domain's core will be dumped, and then the
|
|
domain will be terminated completely and all resources
|
|
released</dd>
|
|
<dt><code>coredump-restart</code></dt>
|
|
<dd>The crashed domain's core will be dumped, and then the
|
|
domain will be restarted with the same configuration</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
The <code>on_lockfailure</code> element (<span class="since">since
|
|
1.0.0</span>) may be used to configure what action should be
|
|
taken when a lock manager loses resource locks. The following
|
|
actions are recognized by libvirt, although not all of them need
|
|
to be supported by individual lock managers. When no action is
|
|
specified, each lock manager will take its default action.
|
|
</p>
|
|
<dl>
|
|
<dt><code>poweroff</code></dt>
|
|
<dd>The domain will be forcefully powered off.</dd>
|
|
<dt><code>restart</code></dt>
|
|
<dd>The domain will be powered off and started up again to
|
|
reacquire its locks.</dd>
|
|
<dt><code>pause</code></dt>
|
|
<dd>The domain will be paused so that it can be manually resumed
|
|
when lock issues are solved.</dd>
|
|
<dt><code>ignore</code></dt>
|
|
<dd>Keep the domain running as if nothing happened.</dd>
|
|
</dl>
|
|
|
|
<h3><a name="elementsPowerManagement">Power Management</a></h3>
|
|
|
|
<p>
|
|
<span class="since">Since 0.10.2</span> it is possible to
|
|
forcibly enable or disable BIOS advertisements to the guest
|
|
OS. (NB: Only qemu driver support)
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<pm>
|
|
<suspend-to-disk enabled='no'/>
|
|
<suspend-to-mem enabled='yes'/>
|
|
</pm>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>pm</code></dt>
|
|
<dd>These elements enable ('yes') or disable ('no') BIOS support
|
|
for S3 (suspend-to-disk) and S4 (suspend-to-mem) ACPI sleep
|
|
states. If nothing is specified, then the hypervisor will be
|
|
left with its default value.</dd>
|
|
</dl>
|
|
|
|
<h3><a name="elementsFeatures">Hypervisor features</a></h3>
|
|
|
|
<p>
|
|
Hypervisors may allow certain CPU / machine features to be
|
|
toggled on/off.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<features>
|
|
<pae/>
|
|
<acpi/>
|
|
<apic/>
|
|
<hap/>
|
|
<privnet/>
|
|
<hyperv>
|
|
<relaxed state='on'/>
|
|
</hyperv>
|
|
|
|
</features>
|
|
...</pre>
|
|
|
|
<p>
|
|
All features are listed within the <code>features</code>
|
|
element, omitting a togglable feature tag turns it off.
|
|
The available features can be found by asking
|
|
for the <a href="formatcaps.html">capabilities XML</a>,
|
|
but a common set for fully virtualized domains are:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>pae</code></dt>
|
|
<dd>Physical address extension mode allows 32-bit guests
|
|
to address more than 4 GB of memory.</dd>
|
|
<dt><code>acpi</code></dt>
|
|
<dd>ACPI is useful for power management, for example, with
|
|
KVM guests it is required for graceful shutdown to work.
|
|
</dd>
|
|
<dt><code>apic</code></dt>
|
|
<dd>APIC allows the use of programmable IRQ
|
|
management. <span class="since">Since 0.10.2 (QEMU only)</span> there is
|
|
an optional attribute <code>eoi</code> with values <code>on</code>
|
|
and <code>off</code> which toggles the availability of EOI (End of
|
|
Interrupt) for the guest.
|
|
</dd>
|
|
<dt><code>hap</code></dt>
|
|
<dd>Enable use of Hardware Assisted Paging if available in
|
|
the hardware.
|
|
</dd>
|
|
<dt><code>viridian</code></dt>
|
|
<dd>Enable Viridian hypervisor extensions for paravirtualizing
|
|
guest operating systems
|
|
</dd>
|
|
<dt><code>privnet</code></dt>
|
|
<dd>Always create a private network namespace. This is
|
|
automatically set if any interface devices are defined.
|
|
This feature is only relevant for container based
|
|
virtualization drivers, such as LXC.
|
|
</dd>
|
|
<dt><code>hyperv</code></dt>
|
|
<dd>Enable various features improving behavior of guests
|
|
running Microsoft Windows.
|
|
<table class="top_table">
|
|
<tr>
|
|
<th>Feature</th>
|
|
<th>Description</th>
|
|
<th>Value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>relaxed</td>
|
|
<td>Relax contstraints on timers</td>
|
|
<td> on, off</td>
|
|
</tr>
|
|
</table>
|
|
<span class="since">Since 1.0.0 (QEMU only)</span>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a name="elementsTime">Time keeping</a></h3>
|
|
|
|
<p>
|
|
The guest clock is typically initialized from the host clock.
|
|
Most operating systems expect the hardware clock to be kept
|
|
in UTC, and this is the default. Windows, however, expects
|
|
it to be in so called 'localtime'.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<clock offset='localtime'>
|
|
<timer name='rtc' tickpolicy='catchup' track='guest'>
|
|
<catchup threshold='123' slew='120' limit='10000'/>
|
|
</timer>
|
|
<timer name='pit' tickpolicy='delay'/>
|
|
</clock>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>clock</code></dt>
|
|
<dd>
|
|
<p>The <code>offset</code> attribute takes four possible
|
|
values, allowing fine grained control over how the guest
|
|
clock is synchronized to the host. NB, not all hypervisors
|
|
support all modes.</p>
|
|
<dl>
|
|
<dt><code>utc</code></dt>
|
|
<dd>
|
|
The guest clock will always be synchronized to UTC when
|
|
booted.
|
|
<span class="since">Since 0.9.11</span> 'utc' mode can be converted
|
|
to 'variable' mode, which can be controlled by using the
|
|
<code>adjustment</code> attribute. If the value is 'reset', the
|
|
conversion is never done (not all hypervisors can
|
|
synchronize to UTC on each boot; use of 'reset' will cause
|
|
an error on those hypervisors). A numeric value
|
|
forces the conversion to 'variable' mode using the value as the
|
|
initial adjustment. The default <code>adjustment</code> is
|
|
hypervisor specific.
|
|
</dd>
|
|
<dt><code>localtime</code></dt>
|
|
<dd>
|
|
The guest clock will be synchronized to the host's configured
|
|
timezone when booted, if any.
|
|
<span class="since">Since 0.9.11,</span> the <code>adjustment</code>
|
|
attribute behaves the same as in 'utc' mode.
|
|
</dd>
|
|
<dt><code>timezone</code></dt>
|
|
<dd>
|
|
The guest clock will be synchronized to the requested timezone
|
|
using the <code>timezone</code> attribute.
|
|
<span class="since">Since 0.7.7</span>
|
|
</dd>
|
|
<dt><code>variable</code></dt>
|
|
<dd>
|
|
The guest clock will have an arbitrary offset applied
|
|
relative to UTC or localtime, depending on the <code>basis</code>
|
|
attribute. The delta relative to UTC (or localtime) is specified
|
|
in seconds, using the <code>adjustment</code> attribute.
|
|
The guest is free to adjust the RTC over time and expect
|
|
that it will be honored at next reboot. This is in
|
|
contrast to 'utc' and 'localtime' mode (with the optional
|
|
attribute adjustment='reset'), where the RTC adjustments are
|
|
lost at each reboot. <span class="since">Since 0.7.7</span>
|
|
<span class="since">Since 0.9.11</span> the <code>basis</code>
|
|
attribute can be either 'utc' (default) or 'localtime'.
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
A <code>clock</code> may have zero or more
|
|
<code>timer</code>sub-elements. <span class="since">Since
|
|
0.8.0</span>
|
|
</p>
|
|
</dd>
|
|
<dt><code>timer</code></dt>
|
|
<dd>
|
|
<p>
|
|
Each timer element requires a <code>name</code> attribute,
|
|
and has other optional attributes that depend on
|
|
the <code>name</code> specified. Various hypervisors
|
|
support different combinations of attributes.
|
|
</p>
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>
|
|
The <code>name</code> attribute selects which timer is
|
|
being modified, and can be one of "platform", "hpet",
|
|
"kvmclock", "pit", "rtc", or "tsc".
|
|
</dd>
|
|
<dt><code>track</code></dt>
|
|
<dd>
|
|
The <code>track</code> attribute specifies what the timer
|
|
tracks, and can be "boot", "guest", or "wall".
|
|
Only valid for <code>name="rtc"</code>
|
|
or <code>name="platform"</code>.
|
|
</dd>
|
|
<dt><code>tickpolicy</code></dt>
|
|
<dd>
|
|
<p>
|
|
The <code>tickpolicy</code> attribute determines what
|
|
happens whens QEMU misses a deadline for injecting a
|
|
tick to the guest:
|
|
</p>
|
|
<dl>
|
|
<dt><code>delay</code></dt>
|
|
<dd>Continue to deliver ticks at the normal rate.
|
|
The guest time will be delayed due to the late
|
|
tick</dd>
|
|
<dt><code>catchup</code></dt>
|
|
<dd>Deliver ticks at a higher rate to catch up
|
|
with the missed tick. The guest time should
|
|
not be delayed once catchup is complete.</dd>
|
|
<dt><code>merge</code></dt>
|
|
<dd>Merge the missed tick(s) into one tick and
|
|
inject. The guest time may be delayed, depending
|
|
on how the OS reacts to the merging of ticks</dd>
|
|
<dt><code>discard</code></dt>
|
|
<dd>Throw away the missed tick(s) and continue
|
|
with future injection normally. The guest time
|
|
may be delayed, unless the OS has explicit
|
|
handling of lost ticks</dd>
|
|
</dl>
|
|
<p>If the policy is "catchup", there can be further details in
|
|
the <code>catchup</code> sub-element.</p>
|
|
<dl>
|
|
<dt><code>catchup</code></dt>
|
|
<dd>
|
|
The <code>catchup</code> element has three optional
|
|
attributes, each a positive integer. The attributes
|
|
are <code>threshold</code>, <code>slew</code>,
|
|
and <code>limit</code>.
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
Note that hypervisors are not required to support all policies across all time sources
|
|
</p>
|
|
</dd>
|
|
<dt><code>frequency</code></dt>
|
|
<dd>
|
|
The <code>frequency</code> attribute is an unsigned
|
|
integer specifying the frequency at
|
|
which <code>name="tsc"</code> runs.
|
|
</dd>
|
|
<dt><code>mode</code></dt>
|
|
<dd>
|
|
The <code>mode</code> attribute controls how
|
|
the <code>name="tsc"</code> timer is managed, and can be
|
|
"auto", "native", "emulate", "paravirt", or "smpsafe".
|
|
Other timers are always emulated.
|
|
</dd>
|
|
<dt><code>present</code></dt>
|
|
<dd>
|
|
The <code>present</code> attribute can be "yes" or "no" to
|
|
specify whether a particular timer is available to the guest.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a name="elementsDevices">Devices</a></h3>
|
|
|
|
<p>
|
|
The final set of XML elements are all used to describe devices
|
|
provided to the guest domain. All devices occur as children
|
|
of the main <code>devices</code> element.
|
|
<span class="since">Since 0.1.3</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<emulator>/usr/lib/xen/bin/qemu-dm</emulator>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>emulator</code></dt>
|
|
<dd>
|
|
The contents of the <code>emulator</code> element specify
|
|
the fully qualified path to the device model emulator binary.
|
|
The <a href="formatcaps.html">capabilities XML</a> specifies
|
|
the recommended default emulator to use for each particular
|
|
domain type / architecture combination.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
|
|
|
|
<p>
|
|
Any device that looks like a disk, be it a floppy, harddisk,
|
|
cdrom, or paravirtualized driver is specified via the <code>disk</code>
|
|
element.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<disk type='file' snapshot='external'>
|
|
<driver name="tap" type="aio" cache="default"/>
|
|
<source file='/var/lib/xen/images/fv0' startupPolicy='optional'>
|
|
<seclabel relabel='no'/>
|
|
</source>
|
|
<target dev='hda' bus='ide'/>
|
|
<iotune>
|
|
<total_bytes_sec>10000000</total_bytes_sec>
|
|
<read_iops_sec>400000</read_iops_sec>
|
|
<write_iops_sec>100000</write_iops_sec>
|
|
</iotune>
|
|
<boot order='2'/>
|
|
<encryption type='...'>
|
|
...
|
|
</encryption>
|
|
<shareable/>
|
|
<serial>
|
|
...
|
|
</serial>
|
|
</disk>
|
|
...
|
|
<disk type='network'>
|
|
<driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/>
|
|
<source protocol="sheepdog" name="image_name">
|
|
<host name="hostname" port="7000"/>
|
|
</source>
|
|
<target dev="hdb" bus="ide"/>
|
|
<boot order='1'/>
|
|
<transient/>
|
|
<address type='drive' controller='0' bus='1' unit='0'/>
|
|
</disk>
|
|
<disk type='network'>
|
|
<driver name="qemu" type="raw"/>
|
|
<source protocol="rbd" name="image_name2">
|
|
<host name="hostname" port="7000"/>
|
|
</source>
|
|
<target dev="hdd" bus="ide"/>
|
|
<auth username='myuser'>
|
|
<secret type='ceph' usage='mypassid'/>
|
|
</auth>
|
|
</disk>
|
|
<disk type='block' device='cdrom'>
|
|
<driver name='qemu' type='raw'/>
|
|
<target dev='hdc' bus='ide' tray='open'/>
|
|
<readonly/>
|
|
</disk>
|
|
<disk type='block' device='lun'>
|
|
<driver name='qemu' type='raw'/>
|
|
<source dev='/dev/sda'/>
|
|
<target dev='sda' bus='scsi'/>
|
|
<address type='drive' controller='0' bus='0' target='3' unit='0'/>
|
|
</disk>
|
|
<disk type='block' device='disk'>
|
|
<driver name='qemu' type='raw'/>
|
|
<source dev='/dev/sda'/>
|
|
<geometry cyls='16383' heads='16' secs='63' trans='lba'/>
|
|
<blockio logical_block_size='512' physical_block_size='4096'/>
|
|
<target dev='hda' bus='ide'/>
|
|
</disk>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<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", or "network"
|
|
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>
|
|
<dt><code>source</code></dt>
|
|
<dd>If the disk <code>type</code> is "file", then
|
|
the <code>file</code> attribute specifies the fully-qualified
|
|
path to the file holding the disk. If the disk
|
|
<code>type</code> is "block", then the <code>dev</code>
|
|
attribute specifies the path to the host device to serve as
|
|
the disk. With both "file" and "block", one or more optional
|
|
sub-elements <code>seclabel</code>, <a href="#seclabel">described
|
|
below</a> (and <span class="since">since 0.9.9</span>), can be
|
|
used to override the domain security labeling policy for just
|
|
that source file. If the disk <code>type</code> is "dir", then the
|
|
<code>dir</code> attribute specifies the fully-qualified path
|
|
to the directory to use as the disk. If the disk <code>type</code>
|
|
is "network", then the <code>protocol</code> attribute specifies
|
|
the protocol to access to the requested image; possible values
|
|
are "nbd", "rbd", "sheepdog" or "gluster". If the
|
|
<code>protocol</code> attribute is "rbd", "sheepdog" or "gluster", an
|
|
additional attribute <code>name</code> is mandatory to specify which
|
|
volume/image will be used; for "nbd" it is optional. When the disk
|
|
<code>type</code> is "network", the <code>source</code> may have zero
|
|
or more <code>host</code> sub-elements used to specify the hosts
|
|
to connect.
|
|
<span class="since">Since 0.0.3; <code>type='dir'</code> since
|
|
0.7.5; <code>type='network'</code> since 0.8.7</span><br/>
|
|
For a "file" disk type which represents a cdrom or floppy
|
|
(the <code>device</code> attribute), it is possible to define
|
|
policy what to do with the disk if the source file is not accessible.
|
|
This is done by the <code>startupPolicy</code> attribute, accepting
|
|
these values:
|
|
<table class="top_table">
|
|
<tr>
|
|
<td> mandatory </td>
|
|
<td> fail if missing for any reason (the default) </td>
|
|
</tr>
|
|
<tr>
|
|
<td> requisite </td>
|
|
<td> fail if missing on boot up,
|
|
drop if missing on migrate/restore/revert </td>
|
|
</tr>
|
|
<tr>
|
|
<td> optional </td>
|
|
<td> drop if missing at any start attempt </td>
|
|
</tr>
|
|
</table>
|
|
<span class="since">Since 0.9.7</span>
|
|
</dd>
|
|
<dt><code>mirror</code></dt>
|
|
<dd>
|
|
This element is present if the hypervisor has started a block
|
|
copy operation (via the <code>virDomainBlockCopy</code> API),
|
|
where the mirror location in attribute <code>file</code> will
|
|
eventually have the same contents as the source, and with the
|
|
file format in attribute <code>format</code> (which might
|
|
differ from the format of the source). If
|
|
attribute <code>ready</code> is present, then it is known the
|
|
disk is ready to pivot; otherwise, the disk is probably still
|
|
copying. For now, this element only valid in output; it is
|
|
ignored on input. <span class="since">Since 0.9.12</span>
|
|
</dd>
|
|
<dt><code>target</code></dt>
|
|
<dd>The <code>target</code> element controls the bus / device
|
|
under which the disk is exposed to the guest
|
|
OS. The <code>dev</code> attribute indicates the "logical"
|
|
device name. The actual device name specified is not
|
|
guaranteed to map to the device name in the guest OS. Treat it
|
|
as a device ordering hint. The optional <code>bus</code>
|
|
attribute specifies the type of disk device to emulate;
|
|
possible values are driver specific, with typical values being
|
|
"ide", "scsi", "virtio", "xen", "usb" or "sata". If omitted, the bus
|
|
type is inferred from the style of the device name (e.g. a device named
|
|
'sda' will typically be exported using a SCSI bus). The optional
|
|
attribute <code>tray</code> indicates the tray status of the
|
|
removable disks (i.e. CDROM or Floppy disk), the value can be either
|
|
"open" or "closed", defaults to "closed". NB, the value of
|
|
<code>tray</code> could be updated while the domain is running.
|
|
<span class="since">Since 0.0.3; <code>bus</code> attribute since 0.4.3;
|
|
<code>tray</code> attribute since 0.9.11; "usb" attribute value since
|
|
after 0.4.4; "sata" attribute value since 0.9.7</span>
|
|
</dd>
|
|
<dt><code>iotune</code></dt>
|
|
<dd>The optional <code>iotune</code> element provides the
|
|
ability to provide additional per-device I/O tuning, with
|
|
values that can vary for each device (contrast this to
|
|
the <a href="#elementsBlockTuning"><code><blkiotune></code></a>
|
|
element, which applies globally to the domain). Currently,
|
|
the only tuning available is Block I/O throttling for qemu.
|
|
This element has optional sub-elements; any sub-element not
|
|
specified or given with a value of 0 implies no
|
|
limit. <span class="since">Since 0.9.8</span>
|
|
<dl>
|
|
<dt><code>total_bytes_sec</code></dt>
|
|
<dd>The optional <code>total_bytes_sec</code> element is the
|
|
total throughput limit in bytes per second. This cannot
|
|
appear with <code>read_bytes_sec</code>
|
|
or <code>write_bytes_sec</code>.</dd>
|
|
<dt><code>read_bytes_sec</code></dt>
|
|
<dd>The optional <code>read_bytes_sec</code> element is the
|
|
read throughput limit in bytes per second.</dd>
|
|
<dt><code>write_bytes_sec</code></dt>
|
|
<dd>The optional <code>write_bytes_sec</code> element is the
|
|
write throughput limit in bytes per second.</dd>
|
|
<dt><code>total_iops_sec</code></dt>
|
|
<dd>The optional <code>total_iops_sec</code> element is the
|
|
total I/O operations per second. This cannot
|
|
appear with <code>read_iops_sec</code>
|
|
or <code>write_iops_sec</code>.</dd>
|
|
<dt><code>read_iops_sec</code></dt>
|
|
<dd>The optional <code>read_iops_sec</code> element is the
|
|
read I/O operations per second.</dd>
|
|
<dt><code>write_iops_sec</code></dt>
|
|
<dd>The optional <code>write_iops_sec</code> element is the
|
|
write I/O operations per second.</dd>
|
|
</dl>
|
|
<dt><code>driver</code></dt>
|
|
<dd>
|
|
The optional driver element allows specifying further details
|
|
related to the hypervisor driver used to provide the disk.
|
|
<span class="since">Since 0.1.8</span>
|
|
<ul>
|
|
<li>
|
|
If the hypervisor supports multiple backend drivers, then
|
|
the <code>name</code> attribute selects the primary
|
|
backend driver name, while the optional <code>type</code>
|
|
attribute provides the sub-type. For example, xen
|
|
supports a name of "tap", "tap2", "phy", or "file", with a
|
|
type of "aio", while qemu only supports a name of "qemu",
|
|
but multiple types including "raw", "bochs", "qcow2", and
|
|
"qed".
|
|
</li>
|
|
<li>
|
|
The optional <code>cache</code> attribute controls the
|
|
cache mechanism, possible values are "default", "none",
|
|
"writethrough", "writeback", "directsync" (like
|
|
"writethrough", but it bypasses the host page cache) and
|
|
"unsafe" (host may cache all disk io, and sync requests from
|
|
guest are ignored).
|
|
<span class="since">
|
|
Since 0.6.0,
|
|
"directsync" since 0.9.5,
|
|
"unsafe" since 0.9.7
|
|
</span>
|
|
</li>
|
|
<li>
|
|
The optional <code>error_policy</code> attribute controls
|
|
how the hypervisor will behave on a disk read or write
|
|
error, possible values are "stop", "report", "ignore", and
|
|
"enospace".<span class="since">Since 0.8.0, "report" since
|
|
0.9.7</span> The default setting of error_policy is "report".
|
|
There is also an
|
|
optional <code>rerror_policy</code> that controls behavior
|
|
for read errors only. <span class="since">Since
|
|
0.9.7</span>. If no rerror_policy is given, error_policy
|
|
is used for both read and write errors. If rerror_policy
|
|
is given, it overrides the <code>error_policy</code> for
|
|
read errors. Also note that "enospace" is not a valid
|
|
policy for read errors, so if <code>error_policy</code> is
|
|
set to "enospace" and no <code>rerror_policy</code> is
|
|
given, the read error policy will be left at its default,
|
|
which is "report".
|
|
</li>
|
|
<li>
|
|
The optional <code>io</code> attribute controls specific
|
|
policies on I/O; qemu guests support "threads" and
|
|
"native". <span class="since">Since 0.8.8</span>
|
|
</li>
|
|
<li>
|
|
The optional <code>ioeventfd</code> attribute allows users to
|
|
set <a href='https://patchwork.kernel.org/patch/43390/'>
|
|
domain I/O asynchronous handling</a> for disk device.
|
|
The default is left to the discretion of the hypervisor.
|
|
Accepted values are "on" and "off". Enabling this allows
|
|
qemu to execute VM while a separate thread handles I/O.
|
|
Typically guests experiencing high system CPU utilization
|
|
during I/O will benefit from this. On the other hand,
|
|
on overloaded host it could increase guest I/O latency.
|
|
<span class="since">Since 0.9.3 (QEMU and KVM only)</span>
|
|
<b>In general you should leave this option alone, unless you
|
|
are very certain you know what you are doing.</b>
|
|
</li>
|
|
<li>
|
|
The optional <code>event_idx</code> attribute controls
|
|
some aspects of device event processing. The value can be
|
|
either 'on' or 'off' - if it is on, it will reduce the
|
|
number of interrupts and exits for the guest. The default
|
|
is determined by QEMU; usually if the feature is
|
|
supported, default is on. In case there is a situation
|
|
where this behavior is suboptimal, this attribute provides
|
|
a way to force the feature off.
|
|
<span class="since">Since 0.9.5 (QEMU and KVM only)</span>
|
|
<b>In general you should leave this option alone, unless you
|
|
are very certain you know what you are doing.</b>
|
|
</li>
|
|
<li>
|
|
The optional <code>copy_on_read</code> attribute controls
|
|
whether to copy read backing file into the image file. The
|
|
value can be either "on" or "off".
|
|
Copy-on-read avoids accessing the same backing file sectors
|
|
repeatedly and is useful when the backing file is over a slow
|
|
network. By default copy-on-read is off.
|
|
<span class='since'>Since 0.9.10 (QEMU and KVM only)</span>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
<dt><code>boot</code></dt>
|
|
<dd>Specifies that the disk is bootable. The <code>order</code>
|
|
attribute determines the order in which devices will be tried during
|
|
boot sequence. The per-device <code>boot</code> elements cannot be
|
|
used together with general boot elements in
|
|
<a href="#elementsOSBIOS">BIOS bootloader</a> section.
|
|
<span class="since">Since 0.8.8</span>
|
|
</dd>
|
|
<dt><code>encryption</code></dt>
|
|
<dd>If present, specifies how the volume is encrypted. See
|
|
the <a href="formatstorageencryption.html">Storage Encryption</a> page
|
|
for more information.
|
|
</dd>
|
|
<dt><code>readonly</code></dt>
|
|
<dd>If present, this indicates the device cannot be modified by
|
|
the guest. For now, this is the default for disks with
|
|
attribute <code>device='cdrom'</code>.
|
|
</dd>
|
|
<dt><code>shareable</code></dt>
|
|
<dd>If present, this indicates the device is expected to be shared
|
|
between domains (assuming the hypervisor and OS support this),
|
|
which means that caching should be deactivated for that device.
|
|
</dd>
|
|
<dt><code>transient</code></dt>
|
|
<dd>If present, this indicates that changes to the device
|
|
contents should be reverted automatically when the guest
|
|
exits. With some hypervisors, marking a disk transient
|
|
prevents the domain from participating in migration or
|
|
snapshots. <span class="since">Since 0.9.5</span>
|
|
</dd>
|
|
<dt><code>serial</code></dt>
|
|
<dd>If present, this specify serial number of virtual hard drive.
|
|
For example, it may look
|
|
like <code><serial>WD-WMAP9A966149</serial></code>.
|
|
<span class="since">Since 0.7.1</span>
|
|
</dd>
|
|
<dt><code>wwn</code></dt>
|
|
<dd>If present, this element specifies the WWN (World Wide Name)
|
|
of a virtual hard disk or CD-ROM drive. It must be composed
|
|
of 16 hexadecimal digits.
|
|
<span class='since'>Since 0.10.1</span>
|
|
</dd>
|
|
<dt><code>vendor</code></dt>
|
|
<dd>If present, this element specifies the vendor of a virtual hard
|
|
disk or CD-ROM device. It must not be longer than 8 printable
|
|
characters.
|
|
<span class='since'>Since 1.0.1</span>
|
|
</dd>
|
|
<dt><code>product</code></dt>
|
|
<dd>If present, this element specifies the product of a virtual hard
|
|
disk or CD-ROM device. It must not be longer than 16 printable
|
|
characters.
|
|
<span class='since'>Since 1.0.1</span>
|
|
</dd>
|
|
<dt><code>host</code></dt>
|
|
<dd>The <code>host</code> element supports 4 attributes, viz. "name",
|
|
"port", "transport" and "socket", which specify the hostname, the port
|
|
number, transport type and path to socket, respectively. The meaning
|
|
of this element and the number of the elements depend on the protocol
|
|
attribute.
|
|
<table class="top_table">
|
|
<tr>
|
|
<th> Protocol </th>
|
|
<th> Meaning </th>
|
|
<th> Number of hosts </th>
|
|
</tr>
|
|
<tr>
|
|
<td> nbd </td>
|
|
<td> a server running nbd-server </td>
|
|
<td> only one </td>
|
|
</tr>
|
|
<tr>
|
|
<td> rbd </td>
|
|
<td> monitor servers of RBD </td>
|
|
<td> one or more </td>
|
|
</tr>
|
|
<tr>
|
|
<td> sheepdog </td>
|
|
<td> one of the sheepdog servers (default is localhost:7000) </td>
|
|
<td> zero or one </td>
|
|
</tr>
|
|
<tr>
|
|
<td> gluster </td>
|
|
<td> a server running glusterd daemon </td>
|
|
<td> only one </td>
|
|
</tr>
|
|
</table>
|
|
In case of gluster, valid values for transport attribute are tcp, rdma
|
|
or unix. If nothing is specified, tcp is assumed. If transport is unix,
|
|
socket attribute specifies path to unix socket.
|
|
</dd>
|
|
<dt><code>address</code></dt>
|
|
<dd>If present, the <code>address</code> element ties the disk
|
|
to a given slot of a controller (the
|
|
actual <code><controller></code> device can often be
|
|
inferred by libvirt, although it can
|
|
be <a href="#elementsControllers">explicitly specified</a>).
|
|
The <code>type</code> attribute is mandatory, and is typically
|
|
"pci" or "drive". For a "pci" controller, additional
|
|
attributes for <code>bus</code>, <code>slot</code>,
|
|
and <code>function</code> must be present, as well as
|
|
optional <code>domain</code> and <code>multifunction</code>.
|
|
Multifunction defaults to 'off'; any other value requires
|
|
QEMU 0.1.3 and <span class="since">libvirt 0.9.7</span>. For a
|
|
"drive" controller, additional attributes
|
|
<code>controller</code>, <code>bus</code>, <code>target</code>
|
|
(<span class="since">libvirt 0.9.11</span>), and <code>unit</code>
|
|
are available, each defaulting to 0.
|
|
</dd>
|
|
<dt><code>auth</code></dt>
|
|
<dd>If present, the <code>auth</code> element provides the
|
|
authentication credentials needed to access the source. It
|
|
includes a mandatory attribute <code>username</code>, which
|
|
identifies the username to use during authentication, as well
|
|
as a sub-element <code>secret</code> with mandatory
|
|
attribute <code>type</code>, to tie back to
|
|
a <a href="formatsecret.html">libvirt secret object</a> that
|
|
holds the actual password or other credentials (the domain XML
|
|
intentionally does not expose the password, only the reference
|
|
to the object that does manage the password). For now, the
|
|
only known secret <code>type</code> is "ceph", for Ceph RBD
|
|
network sources, and requires either an
|
|
attribute <code>uuid</code> with the UUID of the Ceph secret
|
|
object, or an attribute <code>usage</code> with the name
|
|
associated with the Ceph secret
|
|
object. <span class="since">libvirt 0.9.7</span>
|
|
</dd>
|
|
<dt><code>geometry</code></dt>
|
|
<dd>The optional <code>geometry</code> element provides the
|
|
ability to override geometry settings. This mostly useful for
|
|
S390 DASD-disks or older DOS-disks. <span class="since">0.10.0</span>
|
|
<dl>
|
|
<dt><code>cyls</code></dt>
|
|
<dd>The <code>cyls</code> attribute is the
|
|
number of cylinders. </dd>
|
|
<dt><code>heads</code></dt>
|
|
<dd>The <code>heads</code> attribute is the
|
|
number of heads. </dd>
|
|
<dt><code>secs</code></dt>
|
|
<dd>The <code>secs</code> attribute is the
|
|
number of sectors per track. </dd>
|
|
<dt><code>trans</code></dt>
|
|
<dd>The optional <code>trans</code> attribute is the
|
|
BIOS-Translation-Modus (none, lba or auto)</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>blockio</code></dt>
|
|
<dd>If present, the <code>blockio</code> element allows
|
|
to override any of the block device properties listed below.
|
|
<span class="since">Since 0.10.2 (QEMU and KVM)</span>
|
|
<dl>
|
|
<dt><code>logical_block_size</code></dt>
|
|
<dd>The logical block size the disk will report to the guest
|
|
OS. For Linux this would be the value returned by the
|
|
BLKSSZGET ioctl and describes the smallest units for disk
|
|
I/O.
|
|
<dt><code>physical_block_size</code></dt>
|
|
<dd>The physical block size the disk will report to the guest
|
|
OS. For Linux this would be the value returned by the
|
|
BLKPBSZGET ioctl and describes the disk's hardware sector
|
|
size which can be relevant for the alignment of disk data.
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsFilesystems">Filesystems</a></h4>
|
|
|
|
<p>
|
|
A directory on the host that can be accessed directly from the guest.
|
|
<span class="since">since 0.3.3, since 0.8.5 for QEMU/KVM</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<filesystem type='template'>
|
|
<source name='my-vm-template'/>
|
|
<target dir='/'/>
|
|
</filesystem>
|
|
<filesystem type='mount' accessmode='passthrough'>
|
|
<driver type='path' wrpolicy='immediate'/>
|
|
<source dir='/export/to/guest'/>
|
|
<target dir='/import/from/host'/>
|
|
<readonly/>
|
|
</filesystem>
|
|
...
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>filesystem</code></dt>
|
|
<dd>
|
|
|
|
The filesystem attribute <code>type</code> specifies the type of the
|
|
<code>source</code>. The possible values are:
|
|
|
|
<dl>
|
|
<dt><code>type='mount'</code></dt>
|
|
<dd>
|
|
A host directory to mount in the guest. Used by LXC,
|
|
OpenVZ <span class="since">(since 0.6.2)</span>
|
|
and QEMU/KVM <span class="since">(since 0.8.5)</span>.
|
|
This is the default <code>type</code> if one is not specified.
|
|
This mode also has an optional
|
|
sub-element <code>driver</code>, with an
|
|
attribute <code>type='path'</code>
|
|
or <code>type='handle'</code> <span class="since">(since
|
|
0.9.7)</span>. The driver block has an optional attribute
|
|
<code>wrpolicy</code> that further controls interaction with
|
|
the host page cache; omitting the attribute gives default behavior,
|
|
while the value <code>immediate</code> means that a host writeback
|
|
is immediately triggered for all pages touched during a guest file
|
|
write operation <span class="since">(since 0.9.10)</span>.
|
|
</dd>
|
|
<dt><code>type='template'</code></dt>
|
|
<dd>
|
|
OpenVZ filesystem template. Only used by OpenVZ driver.
|
|
</dd>
|
|
<dt><code>type='file'</code></dt>
|
|
<dd>
|
|
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.
|
|
</dd>
|
|
<dt><code>type='block'</code></dt>
|
|
<dd>
|
|
A host block device to mount in the guest. The filesystem
|
|
format will be autodetected. Only used by LXC driver
|
|
<span class="since">(since 0.9.5)</span>.
|
|
</dd>
|
|
<dt><code>type='ram'</code></dt>
|
|
<dd>
|
|
An in-memory filesystem, using memory from the host OS.
|
|
The source element has a single attribute <code>usage</code>
|
|
which gives the memory usage limit in kibibytes. Only used
|
|
by LXC driver.
|
|
<span class="since"> (since 0.9.13)</span></dd>
|
|
<dt><code>type='bind'</code></dt>
|
|
<dd>
|
|
A directory inside the guest will be bound to another
|
|
directory inside the guest. Only used by LXC driver
|
|
<span class="since"> (since 0.9.13)</span></dd>
|
|
</dl>
|
|
|
|
The filesystem block has an optional attribute <code>accessmode</code>
|
|
which specifies the security mode for accessing the source
|
|
<span class="since">(since 0.8.5)</span>. Currently this only works
|
|
with <code>type='mount'</code> for the QEMU/KVM driver. The possible
|
|
values are:
|
|
|
|
<dl>
|
|
<dt><code>accessmode='passthrough'</code></dt>
|
|
<dd>
|
|
The <code>source</code> is accessed with the permissions of the
|
|
user inside the guest. This is the default <code>accessmode</code> if
|
|
one is not specified.
|
|
<a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html">More info</a>
|
|
</dd>
|
|
<dt><code>accessmode='mapped'</code></dt>
|
|
<dd>
|
|
The <code>source</code> is accessed with the permissions of the
|
|
hypervisor (QEMU process).
|
|
<a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html">More info</a>
|
|
</dd>
|
|
<dt><code>accessmode='squash'</code></dt>
|
|
<dd>
|
|
Similar to 'passthrough', the exception is that failure of
|
|
privileged operations like 'chown' are ignored. This makes a
|
|
passthrough-like mode usable for people who run the hypervisor
|
|
as non-root.
|
|
<a href="http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html">More info</a>
|
|
</dd>
|
|
</dl>
|
|
|
|
</dd>
|
|
|
|
<dt><code>source</code></dt>
|
|
<dd>
|
|
The resource on the host that is being accessed in the guest. The
|
|
<code>name</code> attribute must be used with
|
|
<code>type='template'</code>, and the <code>dir</code> attribute must
|
|
be used with <code>type='mount'</code>. The <code>usage</code> attribute
|
|
is used with <code>type='ram'</code> to set the memory limit in KB.
|
|
</dd>
|
|
|
|
<dt><code>target</code></dt>
|
|
<dd>
|
|
Where the <code>source</code> can be accessed in the guest. For
|
|
most drivers this is an automatic mount point, but for QEMU/KVM
|
|
this is merely an arbitrary string tag that is exported to the
|
|
guest as a hint for where to mount.
|
|
</dd>
|
|
|
|
<dt><code>readonly</code></dt>
|
|
<dd>
|
|
Enables exporting filesytem as a readonly mount for guest, by
|
|
default read-write access is given (currently only works for
|
|
QEMU/KVM driver).
|
|
</dd>
|
|
|
|
<dt><code>space_hard_limit</code></dt>
|
|
<dd>
|
|
Maximum space available to this guest's filesystem.
|
|
<span class="since">Since 0.9.13</span>
|
|
</dd>
|
|
|
|
<dt><code>space_soft_limit</code></dt>
|
|
<dd>
|
|
Maximum space available to this guest's filesystem. The container is
|
|
permitted to exceed its soft limits for a grace period of time. Afterwards the
|
|
hard limit is enforced.
|
|
<span class="since">Since 0.9.13</span>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsAddress">Device Addresses</a></h4>
|
|
|
|
<p>
|
|
Many devices have an optional <code><address></code>
|
|
sub-element to describe where the device is placed on the
|
|
virtual bus presented to the guest. If an address (or any
|
|
optional attribute within an address) is omitted on
|
|
input, libvirt will generate an appropriate address; but an
|
|
explicit address is required if more control over layout is
|
|
required. See below for device examples including an address
|
|
element.
|
|
</p>
|
|
|
|
<p>
|
|
Every address has a mandatory attribute <code>type</code> that
|
|
describes which bus the device is on. The choice of which
|
|
address to use for a given device is constrained in part by the
|
|
device and the architecture of the guest. For example,
|
|
a <code><disk></code> device
|
|
uses <code>type='disk'</code>, while
|
|
a <code><console></code> device would
|
|
use <code>type='pci'</code> on i686 or x86_64 guests,
|
|
or <code>type='spapr-vio'</code> on PowerPC64 pseries guests.
|
|
Each address type has further optional attributes that control
|
|
where on the bus the device will be placed:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>type='pci'</code></dt>
|
|
<dd>PCI addresses have the following additional
|
|
attributes: <code>domain</code> (a 2-byte hex integer, not
|
|
currently used by qemu), <code>bus</code> (a hex value between
|
|
0 and 0xff, inclusive), <code>slot</code> (a hex value between
|
|
0x0 and 0x1f, inclusive), and <code>function</code> (a value
|
|
between 0 and 7, inclusive). Also available is
|
|
the <code>multifunction</code> attribute, which controls
|
|
turning on the multifunction bit for a particular
|
|
slot/function in the PCI control register
|
|
(<span class="since">since 0.9.7, requires QEMU
|
|
0.13</span>). <code>multifunction</code> defaults to 'off',
|
|
but should be set to 'on' for function 0 of a slot that will
|
|
have multiple functions used.
|
|
</dd>
|
|
<dt><code>type='drive'</code></dt>
|
|
<dd>Drive addresses have the following additional
|
|
attributes: <code>controller</code> (a 2-digit controller
|
|
number), <code>bus</code> (a 2-digit bus number),
|
|
<code>target</code> (a 2-digit bus number),
|
|
and <code>unit</code> (a 2-digit unit number on the bus).
|
|
</dd>
|
|
<dt><code>type='virtio-serial'</code></dt>
|
|
<dd>Each virtio-serial address has the following additional
|
|
attributes: <code>controller</code> (a 2-digit controller
|
|
number), <code>bus</code> (a 2-digit bus number),
|
|
and <code>slot</code> (a 2-digit slot within the bus).
|
|
</dd>
|
|
<dt><code>type='ccid'</code></dt>
|
|
<dd>A CCID address, for smart-cards, has the following
|
|
additional attributes: <code>bus</code> (a 2-digit bus
|
|
number), and <code>slot</code> attribute (a 2-digit slot
|
|
within the bus). <span class="since">Since 0.8.8.</span>
|
|
<dt><code>type='usb'</code></dt>
|
|
<dd>USB addresses have the following additional
|
|
attributes: <code>bus</code> (a hex value between 0 and 0xfff,
|
|
inclusive), and <code>port</code> (a dotted notation of up to
|
|
four octets, such as 1.2 or 2.1.3.1).
|
|
</dd>
|
|
<dt><code>type='spapr-vio'</code></dt>
|
|
<dd>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
|
|
multiple of 0x1000, but other addresses are valid and
|
|
permitted by libvirt. Each address has the following
|
|
additional attribute: <code>reg</code> (the hex value address
|
|
of the starting register). <span class="since">Since
|
|
0.9.9.</span>
|
|
</dd>
|
|
<dt><code>type='ccw'</code></dt>
|
|
<dd>s390 guests with a <code>machine</code> value of
|
|
s390-ccw-virtio use the native CCW bus for I/O devices.
|
|
CCW bus addresses have the following additional attributes:
|
|
<code>cssid</code> (a hex value between 0 and 0xfe, inclusive),
|
|
<code>ssid</code> (a value between 0 and 3, inclusive) and
|
|
<code>devno</code> (a hex value between 0 and 0xffff, inclusive).
|
|
Partially specified bus addresses are not allowed.
|
|
If omitted, libvirt will assign a free bus address with
|
|
cssid=0xfe and ssid=0. Virtio devices for s390 must have their
|
|
cssid set to 0xfe in order to be recognized by the guest
|
|
operating system.
|
|
<span class="since">Since 1.0.4</span>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsControllers">Controllers</a></h4>
|
|
|
|
<p>
|
|
Depending on the guest architecture, some device busses can
|
|
appear more than once, with a group of virtual devices tied to a
|
|
virtual controller. Normally, libvirt can automatically infer such
|
|
controllers without requiring explicit XML markup, but sometimes
|
|
it is necessary to provide an explicit controller element.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<controller type='ide' index='0'/>
|
|
<controller type='virtio-serial' index='0' ports='16' vectors='4'/>
|
|
<controller type='virtio-serial' index='1'>
|
|
<address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
|
|
</controller>
|
|
...
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
Each controller has a mandatory attribute <code>type</code>,
|
|
which must be one of "ide", "fdc", "scsi", "sata", "usb",
|
|
"ccid", or "virtio-serial", and a mandatory
|
|
attribute <code>index</code> which is the decimal integer
|
|
describing in which order the bus controller is encountered (for
|
|
use in <code>controller</code> attributes
|
|
of <code><address></code> elements). The "virtio-serial"
|
|
controller has two additional optional
|
|
attributes <code>ports</code> and <code>vectors</code>, which
|
|
control how many devices can be connected through the
|
|
controller. A "scsi" controller has an optional
|
|
attribute <code>model</code>, which is one of "auto", "buslogic",
|
|
"ibmvscsi", "lsilogic", "lsias1068", "virtio-scsi" or "vmpvscsi".
|
|
A "usb" controller has an optional attribute <code>model</code>,
|
|
which is one of "piix3-uhci", "piix4-uhci", "ehci",
|
|
"ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3",
|
|
"vt82c686b-uhci", "pci-ohci" or "nec-xhci". Additionally,
|
|
<span class="since">since 0.10.0</span>, if the USB bus needs to be
|
|
explicitly disabled for the guest, <code>model='none'</code> may be used.
|
|
The PowerPC64 "spapr-vio" addresses do not have an associated controller.
|
|
</p>
|
|
|
|
<p>
|
|
For controllers that are themselves devices on a PCI or USB bus,
|
|
an optional sub-element <code><address></code> can specify
|
|
the exact relationship of the controller to its master bus, with
|
|
semantics <a href="#elementsAddress">given above</a>.
|
|
</p>
|
|
|
|
<p>
|
|
USB companion controllers have an optional
|
|
sub-element <code><master></code> to specify the exact
|
|
relationship of the companion to its master controller.
|
|
A companion controller is on the same bus as its master, so
|
|
the companion <code>index</code> value should be equal.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<controller type='usb' index='0' model='ich9-ehci1'>
|
|
<address type='pci' domain='0' bus='0' slot='4' function='7'/>
|
|
</controller>
|
|
<controller type='usb' index='0' model='ich9-uhci1'>
|
|
<master startport='0'/>
|
|
<address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/>
|
|
</controller>
|
|
...
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h4><a name="elementsLease">Device leases</a></h4>
|
|
|
|
<p>
|
|
When using a lock manager, it may be desirable to record device leases
|
|
against a VM. The lock manager will ensure the VM won't start unless
|
|
the leases can be acquired.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
...
|
|
<lease>
|
|
<lockspace>somearea</lockspace>
|
|
<key>somekey</key>
|
|
<target path='/some/lease/path' offset='1024'/>
|
|
</lease>
|
|
...
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt>lockspace</dt>
|
|
<dd>This is an arbitrary string, identifying the lockspace
|
|
within which the key is held. Lock managers may impose
|
|
extra restrictions on the format, or length of the lockspace
|
|
name.</dd>
|
|
<dt>key</dt>
|
|
<dd>This is an arbitrary string, uniquely identifying the
|
|
lease to be acquired. Lock managers may impose extra
|
|
restrictions on the format, or length of the key.
|
|
</dd>
|
|
<dt>target</dt>
|
|
<dd>This is the fully qualified path of the file associated
|
|
with the lockspace. The offset specifies where the lease
|
|
is stored within the file. If the lock manager does not
|
|
require a offset, just pass 0.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsHostDev">Host device assignment</a></h4>
|
|
|
|
<h5><a href="elementsHostDevSubsys">USB / PCI devices</a></h5>
|
|
|
|
<p>
|
|
USB and PCI devices attached to the host can be passed through
|
|
to the guest using the <code>hostdev</code> element.
|
|
<span class="since">since after 0.4.4 for USB and 0.6.0 for PCI
|
|
(KVM only)</span>:
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<hostdev mode='subsystem' type='usb'>
|
|
<source startupPolicy='optional'>
|
|
<vendor id='0x1234'/>
|
|
<product id='0xbeef'/>
|
|
</source>
|
|
<boot order='2'/>
|
|
</hostdev>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>or:</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<hostdev mode='subsystem' type='pci' managed='yes'>
|
|
<source>
|
|
<address bus='0x06' slot='0x02' function='0x0'/>
|
|
</source>
|
|
<boot order='1'/>
|
|
<rom bar='on' file='/etc/fake/boot.bin'/>
|
|
</hostdev>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>hostdev</code></dt>
|
|
<dd>The <code>hostdev</code> element is the main container for describing
|
|
host devices. For usb device passthrough <code>mode</code> is always
|
|
"subsystem" and <code>type</code> is "usb" for a USB device and "pci"
|
|
for a PCI device. When <code>managed</code> is "yes" for a PCI
|
|
device, it is detached from the host before being passed on to
|
|
the guest, and reattached to the host after the guest exits.
|
|
If <code>managed</code> is omitted or "no", and for USB
|
|
devices, the user is responsible to
|
|
call <code>virNodeDeviceDettach</code> (or <code>virsh
|
|
nodedev-dettach</code>) before starting the guest or
|
|
hot-plugging the device,
|
|
and <code>virNodeDeviceReAttach</code> (or <code>virsh
|
|
nodedev-reattach</code>) after hot-unplug or stopping the
|
|
guest.</dd>
|
|
<dt><code>source</code></dt>
|
|
<dd>The source element describes the device as seen from the host.
|
|
The USB device can either be addressed by vendor / product id using the
|
|
<code>vendor</code> and <code>product</code> elements or by the device's
|
|
address on the hosts using the <code>address</code> element. PCI devices
|
|
on the other hand can only be described by their <code>address</code>.
|
|
|
|
<span class="since">Since 1.0.0</span>, the <code>source</code> element
|
|
of USB devices may contain <code>startupPolicy</code> attribute which can
|
|
be used to define policy what to do if the specified host USB device is
|
|
not found. The attribute accepts the following values:
|
|
<table class="top_table">
|
|
<tr>
|
|
<td> mandatory </td>
|
|
<td> fail if missing for any reason (the default) </td>
|
|
</tr>
|
|
<tr>
|
|
<td> requisite </td>
|
|
<td> fail if missing on boot up,
|
|
drop if missing on migrate/restore/revert </td>
|
|
</tr>
|
|
<tr>
|
|
<td> optional </td>
|
|
<td> drop if missing at any start attempt </td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
<dt><code>vendor</code>, <code>product</code></dt>
|
|
<dd>The <code>vendor</code> and <code>product</code> elements each have an
|
|
<code>id</code> attribute that specifies the USB vendor and product id.
|
|
The ids can be given in decimal, hexadecimal (starting with 0x) or
|
|
octal (starting with 0) form.</dd>
|
|
<dt><code>boot</code></dt>
|
|
<dd>Specifies that the device is bootable. The <code>order</code>
|
|
attribute determines the order in which devices will be tried during
|
|
boot sequence. The per-device <code>boot</code> elements cannot be
|
|
used together with general boot elements in
|
|
<a href="#elementsOSBIOS">BIOS bootloader</a> section.
|
|
<span class="since">Since 0.8.8</span> for PCI devices,
|
|
<span class="since">Since 1.0.1</span> for USB devices.
|
|
<dt><code>rom</code></dt>
|
|
<dd>The <code>rom</code> element is used to change how a PCI
|
|
device's ROM is presented to the guest. The optional <code>bar</code>
|
|
attribute can be set to "on" or "off", and determines whether
|
|
or not the device's ROM will be visible in the guest's memory
|
|
map. (In PCI documentation, the "rombar" setting controls the
|
|
presence of the Base Address Register for the ROM). If no rom
|
|
bar is specified, the qemu default will be used (older
|
|
versions of qemu used a default of "off", while newer qemus
|
|
have a default of "on"). <span class="since">Since
|
|
0.9.7 (QEMU and KVM only)</span>. The optional
|
|
<code>file</code> attribute is used to point to a binary file
|
|
to be presented to the guest as the device's ROM BIOS. This
|
|
can be useful, for example, to provide a PXE boot ROM for a
|
|
virtual function of an sr-iov capable ethernet device (which
|
|
has no boot ROMs for the VFs).
|
|
<span class="since">Since 0.9.10 (QEMU and KVM only)</span>.
|
|
</dd>
|
|
<dt><code>address</code></dt>
|
|
<dd>The <code>address</code> element for USB devices has a
|
|
<code>bus</code> and <code>device</code> attribute to specify the
|
|
USB bus and device number the device appears at on the host.
|
|
The values of these attributes can be given in decimal, hexadecimal
|
|
(starting with 0x) or octal (starting with 0) form.
|
|
For PCI devices the element carries 3 attributes allowing to designate
|
|
the device as can be found with the <code>lspci</code> or
|
|
with <code>virsh
|
|
nodedev-list</code>. <a href="#elementsAddress">See above</a> for
|
|
more details on the address element.
|
|
</dl>
|
|
|
|
|
|
<h5><a href="elementsHostDevCaps">Block / character devices</a></h5>
|
|
|
|
<p>
|
|
Block / character devices from the host can be passed through
|
|
to the guest using the <code>hostdev</code> element. This is
|
|
only possible with container based virtualization.
|
|
<span class="since">since after 1.0.1 for LXC</span>:
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<hostdev mode='capabilities' type='storage'>
|
|
<source>
|
|
<block>/dev/sdf1</block>
|
|
</source>
|
|
</hostdev>
|
|
...
|
|
</pre>
|
|
|
|
<pre>
|
|
...
|
|
<hostdev mode='capabilities' type='misc'>
|
|
<source>
|
|
<char>/dev/input/event3</char>
|
|
</source>
|
|
</hostdev>
|
|
...
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><code>hostdev</code></dt>
|
|
<dd>The <code>hostdev</code> element is the main container for describing
|
|
host devices. For block/character device passthrough <code>mode</code> is
|
|
always "capabilities" and <code>type</code> is "block" for a block
|
|
device and "char" for a character device.
|
|
</dd>
|
|
<dt><code>source</code></dt>
|
|
<dd>The source element describes the device as seen from the host.
|
|
For block devices, the path to the block device in the host
|
|
OS is provided in the nested "block" element, while for character
|
|
devices the "char" element is used
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsRedir">Redirected devices</a></h4>
|
|
|
|
<p>
|
|
USB device redirection through a character device is
|
|
supported <span class="since">since after 0.9.5 (KVM
|
|
only)</span>:
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<redirdev bus='usb' type='tcp'>
|
|
<source mode='connect' host='localhost' service='4000'/>
|
|
<boot order='1'/>
|
|
</redirdev>
|
|
<redirfilter>
|
|
<usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.00' allow='yes'/>
|
|
<usbdev allow='no'/>
|
|
</redirfilter>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>redirdev</code></dt>
|
|
<dd>The <code>redirdev</code> element is the main container for
|
|
describing redirected devices. <code>bus</code> must be "usb"
|
|
for a USB device.
|
|
|
|
An additional attribute <code>type</code> is required,
|
|
matching one of the
|
|
supported <a href="#elementsConsole">serial device</a> types,
|
|
to describe the host side of the
|
|
tunnel; <code>type='tcp'</code>
|
|
or <code>type='spicevmc'</code> (which uses the usbredir
|
|
channel of a <a href="#elementsGraphics">SPICE graphics
|
|
device</a>) are typical. The redirdev element has an optional
|
|
sub-element <code><address></code> which can tie the
|
|
device to a particular controller. Further sub-elements,
|
|
such as <code><source></code>, may be required according
|
|
to the given type, although a <code><target></code> sub-element
|
|
is not required (since the consumer of the character device is
|
|
the hypervisor itself, rather than a device visible in the guest).
|
|
</dd>
|
|
<dt><code>boot</code></dt>
|
|
|
|
<dd>Specifies that the device is bootable.
|
|
The <code>order</code> attribute determines the order in which
|
|
devices will be tried during boot sequence. The per-device
|
|
<code>boot</code> elements cannot be used together with general
|
|
boot elements in <a href="#elementsOSBIOS">BIOS bootloader</a> section.
|
|
(<span class="since">Since 1.0.1</span>)
|
|
</dd>
|
|
<dt><code>redirfilter</code></dt>
|
|
<dd>The<code> redirfilter </code>element is used for creating the
|
|
filter rule to filter out certain devices from redirection.
|
|
It uses sub-element <code><usbdev></code> to define each filter rule.
|
|
<code>class</code> attribute is the USB Class code, for example,
|
|
0x08 represents mass storage devices. The USB device can be addressed by
|
|
vendor / product id using the <code>vendor</code> and <code>product</code> attributes.
|
|
<code>version</code> is the bcdDevice value of USB device, such as 1.00, 1.10 and 2.00.
|
|
These four attributes are optional and <code>-1</code> can be used to allow
|
|
any value for them. <code>allow</code> attribute is mandatory,
|
|
'yes' means allow, 'no' for deny.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsSmartcard">Smartcard devices</a></h4>
|
|
|
|
<p>
|
|
A virtual smartcard device can be supplied to the guest via the
|
|
<code>smartcard</code> element. A USB smartcard reader device on
|
|
the host cannot be used on a guest with simple device
|
|
passthrough, since it will then not be available on the host,
|
|
possibly locking the host computer when it is "removed".
|
|
Therefore, some hypervisors provide a specialized virtual device
|
|
that can present a smartcard interface to the guest, with
|
|
several modes for describing how credentials are obtained from
|
|
the host or even a from a channel created to a third-party
|
|
smartcard provider. <span class="since">Since 0.8.8</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<smartcard mode='host'/>
|
|
<smartcard mode='host-certificates'>
|
|
<certificate>cert1</certificate>
|
|
<certificate>cert2</certificate>
|
|
<certificate>cert3</certificate>
|
|
<database>/etc/pki/nssdb/</database>
|
|
</smartcard>
|
|
<smartcard mode='passthrough' type='tcp'>
|
|
<source mode='bind' host='127.0.0.1' service='2001'/>
|
|
<protocol type='raw'/>
|
|
<address type='ccid' controller='0' slot='0'/>
|
|
</smartcard>
|
|
<smartcard mode='passthrough' type='spicevmc'/>
|
|
</devices>
|
|
...
|
|
</pre>
|
|
|
|
<p>
|
|
The <code><smartcard></code> element has a mandatory
|
|
attribute <code>mode</code>. The following modes are supported;
|
|
in each mode, the guest sees a device on its USB bus that
|
|
behaves like a physical USB CCID (Chip/Smart Card Interface
|
|
Device) card.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>mode='host'</code></dt>
|
|
<dd>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 <code><address></code> sub-element.</dd>
|
|
|
|
<dt><code>mode='host-certificates'</code></dt>
|
|
<dd>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
|
|
generated via the command <code>certutil -d /etc/pki/nssdb -x -t
|
|
CT,CT,CT -S -s CN=cert1 -n cert1</code>, and the resulting three
|
|
certificate names must be supplied as the content of each of
|
|
three <code><certificate></code> sub-elements. An
|
|
additional sub-element <code><database></code> can specify
|
|
the absolute path to an alternate directory (matching
|
|
the <code>-d</code> option of the <code>certutil</code> command
|
|
when creating the certificates); if not present, it defaults to
|
|
/etc/pki/nssdb.</dd>
|
|
|
|
<dt><code>mode='passthrough'</code></dt>
|
|
<dd>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
|
|
in turn be talking to a smartcard or using three certificate
|
|
files). In this mode of operation, an additional
|
|
attribute <code>type</code> is required, matching one of the
|
|
supported <a href="#elementsConsole">serial device</a> types, to
|
|
describe the host side of the tunnel; <code>type='tcp'</code>
|
|
or <code>type='spicevmc'</code> (which uses the smartcard
|
|
channel of a <a href="#elementsGraphics">SPICE graphics
|
|
device</a>) are typical. Further sub-elements, such
|
|
as <code><source></code>, may be required according to the
|
|
given type, although a <code><target></code> sub-element
|
|
is not required (since the consumer of the character device is
|
|
the hypervisor itself, rather than a device visible in the
|
|
guest).</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
Each mode supports an optional
|
|
sub-element <code><address></code>, which fine-tunes the
|
|
correlation between the smartcard and a ccid bus
|
|
controller, <a href="#elementsAddress">documented above</a>.
|
|
For now, qemu only supports at most one
|
|
smartcard, with an address of bus=0 slot=0.
|
|
</p>
|
|
|
|
<h4><a name="elementsNICS">Network interfaces</a></h4>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='bridge'>
|
|
<source bridge='xenbr0'/>
|
|
<mac address='00:16:3e:5d:c7:9e'/>
|
|
<script path='vif-bridge'/>
|
|
<boot order='1'/>
|
|
<rom bar='off'/>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
There are several possibilities for specifying a network
|
|
interface visible to the guest. Each subsection below provides
|
|
more details about common setup options. Additionally,
|
|
each <code><interface></code> element has an
|
|
optional <code><address></code> sub-element that can tie
|
|
the interface to a particular pci slot, with
|
|
attribute <code>type='pci'</code>
|
|
as <a href="#elementsAddress">documented above</a>.
|
|
</p>
|
|
|
|
<h5><a name="elementsNICSVirtual">Virtual network</a></h5>
|
|
|
|
<p>
|
|
<strong><em>
|
|
This is the recommended config for general guest connectivity on
|
|
hosts with dynamic / wireless networking configs (or multi-host
|
|
environments where the host hardware details are described
|
|
separately in a <code><network></code>
|
|
definition <span class="since">Since 0.9.4</span>).
|
|
</em></strong>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
Provides a connection whose details are described by the named
|
|
network definition. Depending on the virtual network's "forward
|
|
mode" configuration, the network may be totally isolated
|
|
(no <code><forward></code> element given), NAT'ing to an
|
|
explicit network device or to the default route
|
|
(<code><forward mode='nat'></code>), routed with no NAT
|
|
(<code><forward mode='route'/></code>), or connected
|
|
directly to one of the host's network interfaces (via macvtap)
|
|
or bridge devices ((<code><forward
|
|
mode='bridge|private|vepa|passthrough'/></code> <span class="since">Since
|
|
0.9.4</span>)
|
|
</p>
|
|
<p>
|
|
For networks with a forward mode of bridge, private, vepa, and
|
|
passthrough, it is assumed that the host has any necessary DNS
|
|
and DHCP services already setup outside the scope of libvirt. In
|
|
the case of isolated, nat, and routed networks, DHCP and DNS are
|
|
provided on the virtual network by libvirt, and the IP range can
|
|
be determined by examining the virtual network config with
|
|
'<code>virsh net-dumpxml [networkname]</code>'. There is one
|
|
virtual network called 'default' setup out of the box which does
|
|
NAT'ing to the default route and has an IP range
|
|
of <code>192.168.122.0/255.255.255.0</code>. Each guest will
|
|
have an associated tun device created with a name of vnetN,
|
|
which can also be overridden with the <target> element
|
|
(see
|
|
<a href="#elementsNICSTargetOverride">overriding the target element</a>).
|
|
</p>
|
|
<p>
|
|
When the source of an interface is a network,
|
|
a <code>portgroup</code> can be specified along with the name of
|
|
the network; one network may have multiple portgroups defined,
|
|
with each portgroup containing slightly different configuration
|
|
information for different classes of network
|
|
connections. <span class="since">Since 0.9.4</span>.
|
|
</p>
|
|
<p>
|
|
Also, similar to <code>direct</code> network connections
|
|
(described below), a connection of type <code>network</code> may
|
|
specify a <code>virtualport</code> element, with configuration
|
|
data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant
|
|
switch (<span class="since">Since 0.8.2</span>), or to an
|
|
Open vSwitch virtual switch (<span class="since">Since
|
|
0.9.11</span>).
|
|
</p>
|
|
<p>
|
|
Since the actual type of switch may vary depending on the
|
|
configuration in the <code><network></code> on the host,
|
|
it is acceptable to omit the virtualport <code>type</code>
|
|
attribute, and specify attributes from multiple different
|
|
virtualport types (and also to leave out certain attributes); at
|
|
domain startup time, a complete <code><virtualport></code>
|
|
element will be constructed by merging together the type and
|
|
attributes defined in the network and the portgroup referenced
|
|
by the interface. The newly-constructed virtualport is a combination
|
|
of them. The attributes from lower virtualport can't make change
|
|
on the ones defined in higher virtualport.
|
|
Interface takes the highest priority, portgroup is lowest priority.
|
|
(<span class="since">Since 0.10.0</span>). For example, in order
|
|
to work properly with both an 802.1Qbh switch and an Open vSwitch
|
|
switch, you may choose to specify no type, but both
|
|
an <code>profileid</code> (in case the switch is 802.1Qbh) and
|
|
an <code>interfaceid</code> (in case the switch is Open vSwitch)
|
|
(you may also omit the other attributes, such as managerid,
|
|
typeid, or profileid, to be filled in from the
|
|
network's <code><virtualport></code>). If you want to
|
|
limit a guest to connecting only to certain types of switches,
|
|
you can specify the virtualport type, but still omit some/all of
|
|
the parameters - in this case if the host's network has a
|
|
different type of virtualport, connection of the interface will
|
|
fail.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
</interface>
|
|
...
|
|
<interface type='network'>
|
|
<source network='default' portgroup='engineering'/>
|
|
<target dev='vnet7'/>
|
|
<mac address="00:11:22:33:44:55"/>
|
|
<virtualport>
|
|
<parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
|
|
</virtualport>
|
|
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h5><a name="elementsNICSBridge">Bridge to LAN</a></h5>
|
|
|
|
<p>
|
|
<strong><em>
|
|
This is the recommended config for general guest connectivity on
|
|
hosts with static wired networking configs.
|
|
</em></strong>
|
|
</p>
|
|
|
|
<p>
|
|
Provides a bridge from the VM directly onto the LAN. This assumes
|
|
there is a bridge device on the host which has one or more of the hosts
|
|
physical NICs enslaved. The guest VM will have an associated tun device
|
|
created with a name of vnetN, which can also be overridden with the
|
|
<target> element (see
|
|
<a href="#elementsNICSTargetOverride">overriding the target element</a>).
|
|
The tun device will be enslaved to the bridge. The IP range / network
|
|
configuration is whatever is used on the LAN. This provides the guest VM
|
|
full incoming & outgoing net access just like a physical machine.
|
|
</p>
|
|
<p>
|
|
On Linux systems, the bridge device is normally a standard Linux
|
|
host bridge. On hosts that support Open vSwitch, it is also
|
|
possible to connect to an open vSwitch bridge device by adding
|
|
a <code><virtualport type='openvswitch'/></code> to the
|
|
interface definition. (<span class="since">Since
|
|
0.9.11</span>). The Open vSwitch type virtualport accepts two
|
|
parameters in its <code><parameters></code> element -
|
|
an <code>interfaceid</code> which is a standard uuid used to
|
|
uniquely identify this particular interface to Open vSwitch (if
|
|
you do no specify one, a random interfaceid will be generated
|
|
for you when you first define the interface), and an
|
|
optional <code>profileid</code> which is sent to Open vSwitch as
|
|
the interfaces "port-profile".
|
|
</p>
|
|
<pre>
|
|
...
|
|
<devices>
|
|
...
|
|
<interface type='bridge'>
|
|
<source bridge='br0'/>
|
|
</interface>
|
|
<interface type='bridge'>
|
|
<source bridge='br1'/>
|
|
<target dev='vnet7'/>
|
|
<mac address="00:11:22:33:44:55"/>
|
|
</interface>
|
|
<interface type='bridge'>
|
|
<source bridge='ovsbr'/>
|
|
<virtualport type='openvswitch'>
|
|
<parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
|
|
</virtualport>
|
|
</interface>
|
|
...
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h5><a name="elementsNICSSlirp">Userspace SLIRP stack</a></h5>
|
|
|
|
<p>
|
|
Provides a virtual LAN with NAT to the outside world. The virtual
|
|
network has DHCP & DNS services and will give the guest VM addresses
|
|
starting from <code>10.0.2.15</code>. The default router will be
|
|
<code>10.0.2.2</code> and the DNS server will be <code>10.0.2.3</code>.
|
|
This networking is the only option for unprivileged users who need their
|
|
VMs to have outgoing access.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='user'/>
|
|
...
|
|
<interface type='user'>
|
|
<mac address="00:11:22:33:44:55"/>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
|
|
<h5><a name="elementsNICSEthernet">Generic ethernet connection</a></h5>
|
|
|
|
<p>
|
|
Provides a means for the administrator to execute an arbitrary script
|
|
to connect the guest's network to the LAN. The guest will have a tun
|
|
device created with a name of vnetN, which can also be overridden with the
|
|
<target> element. After creating the tun device a shell script will
|
|
be run which is expected to do whatever host network integration is
|
|
required. By default this script is called /etc/qemu-ifup but can be
|
|
overridden.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='ethernet'/>
|
|
...
|
|
<interface type='ethernet'>
|
|
<target dev='vnet7'/>
|
|
<script path='/etc/qemu-ifup-mynet'/>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h5><a name="elementsNICSDirect">Direct attachment to physical interface</a></h5>
|
|
|
|
<p>
|
|
Provides direct attachment of the virtual machine's NIC to the given
|
|
physial interface of the host.
|
|
<span class="since">Since 0.7.7 (QEMU and KVM only)</span><br/>
|
|
This setup requires the Linux macvtap
|
|
driver to be available. <span class="since">(Since Linux 2.6.34.)</span>
|
|
One of the modes 'vepa'
|
|
( <a href="http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf">
|
|
'Virtual Ethernet Port Aggregator'</a>), 'bridge' or 'private'
|
|
can be chosen for the operation mode of the macvtap device, 'vepa'
|
|
being the default mode. The individual modes cause the delivery of
|
|
packets to behave as follows:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>vepa</code></dt>
|
|
<dd>All VMs' packets are sent to the external bridge. Packets
|
|
whose destination is a VM on the same host as where the
|
|
packet originates from are sent back to the host by the VEPA
|
|
capable bridge (today's bridges are typically not VEPA capable).</dd>
|
|
<dt><code>bridge</code></dt>
|
|
<dd>Packets whose destination is on the same host as where they
|
|
originate from are directly delivered to the target macvtap device.
|
|
Both origin and destination devices need to be in bridge mode
|
|
for direct delivery. If either one of them is in <code>vepa</code> mode,
|
|
a VEPA capable bridge is required.</dd>
|
|
<dt><code>private</code></dt>
|
|
<dd>All packets are sent to the external bridge and will only be
|
|
delivered to a target VM on the same host if they are sent through an
|
|
external router or gateway and that device sends them back to the
|
|
host. This procedure is followed if either the source or destination
|
|
device is in <code>private</code> mode.</dd>
|
|
<dt><code>passthrough</code></dt>
|
|
<dd>This feature attaches a virtual function of a SRIOV capable
|
|
NIC directly to a VM without losing the migration capability.
|
|
All packets are sent to the VF/IF of the configured network device.
|
|
Depending on the capabilities of the device additional prerequisites or
|
|
limitations may apply; for example, on Linux this requires
|
|
kernel 2.6.38 or newer. <span class="since">Since 0.9.2</span></dd>
|
|
</dl>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
...
|
|
<interface type='direct'>
|
|
<source dev='eth0' mode='vepa'/>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
The network access of direct attached virtual machines can be
|
|
managed by the hardware switch to which the physical interface
|
|
of the host machine is connected to.
|
|
</p>
|
|
<p>
|
|
The interface can have additional parameters as shown below,
|
|
if the switch is conforming to the IEEE 802.1Qbg standard.
|
|
The parameters of the virtualport element are documented in more detail
|
|
in the IEEE 802.1Qbg standard. The values are network specific and
|
|
should be provided by the network administrator. In 802.1Qbg terms,
|
|
the Virtual Station Interface (VSI) represents the virtual interface
|
|
of a virtual machine. <span class="since">Since 0.8.2</span>
|
|
</p>
|
|
<p>
|
|
Please note that IEEE 802.1Qbg requires a non-zero value for the
|
|
VLAN ID.
|
|
</p>
|
|
<dl>
|
|
<dt><code>managerid</code></dt>
|
|
<dd>The VSI Manager ID identifies the database containing the VSI type
|
|
and instance definitions. This is an integer value and the
|
|
value 0 is reserved.</dd>
|
|
<dt><code>typeid</code></dt>
|
|
<dd>The VSI Type ID identifies a VSI type characterizing the network
|
|
access. VSI types are typically managed by network administrator.
|
|
This is an integer value.
|
|
</dd>
|
|
<dt><code>typeidversion</code></dt>
|
|
<dd>The VSI Type Version allows multiple versions of a VSI Type.
|
|
This is an integer value.
|
|
</dd>
|
|
<dt><code>instanceid</code></dt>
|
|
<dd>The VSI Instance ID Identifier is generated when a VSI instance
|
|
(i.e. a virtual interface of a virtual machine) is created.
|
|
This is a globally unique identifier.
|
|
</dd>
|
|
</dl>
|
|
<pre>
|
|
...
|
|
<devices>
|
|
...
|
|
<interface type='direct'>
|
|
<source dev='eth0.2' mode='vepa'/>
|
|
<virtualport type="802.1Qbg">
|
|
<parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
|
|
</virtualport>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
The interface can have additional parameters as shown below
|
|
if the switch is conforming to the IEEE 802.1Qbh standard.
|
|
The values are network specific and should be provided by the
|
|
network administrator. <span class="since">Since 0.8.2</span>
|
|
</p>
|
|
<dl>
|
|
<dt><code>profileid</code></dt>
|
|
<dd>The profile ID contains the name of the port profile that is to
|
|
be applied onto this interface. This name is resolved by the port
|
|
profile database into the network parameters from the port profile,
|
|
and those network parameters will be applied to this interface.
|
|
</dd>
|
|
</dl>
|
|
<pre>
|
|
...
|
|
<devices>
|
|
...
|
|
<interface type='direct'>
|
|
<source dev='eth0' mode='private'/>
|
|
<virtualport type='802.1Qbh'>
|
|
<parameters profileid='finance'/>
|
|
</virtualport>
|
|
</interface>
|
|
</devices>
|
|
...
|
|
</pre>
|
|
|
|
|
|
<h5><a name="elementsNICSHostdev">PCI Passthrough</a></h5>
|
|
|
|
<p>
|
|
A PCI network device (specified by the <source> element)
|
|
is directly assigned to the guest using generic device
|
|
passthrough, after first optionally setting the device's MAC
|
|
address to the configured value, and associating the device with
|
|
an 802.1Qbh capable switch using an optionally specified
|
|
<virtualport> element (see the examples of virtualport
|
|
given above for type='direct' network devices). Note that - due
|
|
to limitations in standard single-port PCI ethernet card driver
|
|
design - only SR-IOV (Single Root I/O Virtualization) virtual
|
|
function (VF) devices can be assigned in this manner; to assign
|
|
a standard single-port PCI or PCIe ethernet card to a guest, use
|
|
the traditional <hostdev> device definition and
|
|
<span class="since">Since 0.9.11</span>
|
|
</p>
|
|
|
|
<p>
|
|
Note that this "intelligent passthrough" of network devices is
|
|
very similar to the functionality of a standard <hostdev>
|
|
device, the difference being that this method allows specifying
|
|
a MAC address and <virtualport> for the passed-through
|
|
device. If these capabilities are not required, if you have a
|
|
standard single-port PCI, PCIe, or USB network card that doesn't
|
|
support SR-IOV (and hence would anyway lose the configured MAC
|
|
address during reset after being assigned to the guest domain),
|
|
or if you are using a version of libvirt older than 0.9.11, you
|
|
should use standard <hostdev> to assign the device to the
|
|
guest instead of <interface type='hostdev'/>.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='hostdev'>
|
|
<source>
|
|
<address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
|
|
</source>
|
|
<mac address='52:54:00:6d:90:02'>
|
|
<virtualport type='802.1Qbh'>
|
|
<parameters profileid='finance'/>
|
|
</virtualport>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
|
|
<h5><a name="elementsNICSMulticast">Multicast tunnel</a></h5>
|
|
|
|
<p>
|
|
A multicast group is setup to represent a virtual network. Any VMs
|
|
whose network devices are in the same multicast group can talk to each
|
|
other even across hosts. This mode is also available to unprivileged
|
|
users. There is no default DNS or DHCP support and no outgoing network
|
|
access. To provide outgoing network access, one of the VMs should have a
|
|
2nd NIC which is connected to one of the first 4 network types and do the
|
|
appropriate routing. The multicast protocol is compatible with that used
|
|
by user mode linux guests too. The source address used must be from the
|
|
multicast address block.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='mcast'>
|
|
<mac address='52:54:00:6d:90:01'>
|
|
<source address='230.0.0.1' port='5558'/>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h5><a name="elementsNICSTCP">TCP tunnel</a></h5>
|
|
|
|
<p>
|
|
A TCP client/server architecture provides a virtual network. One VM
|
|
provides the server end of the network, all other VMS are configured as
|
|
clients. All network traffic is routed between the VMs via the server.
|
|
This mode is also available to unprivileged users. There is no default
|
|
DNS or DHCP support and no outgoing network access. To provide outgoing
|
|
network access, one of the VMs should have a 2nd NIC which is connected
|
|
to one of the first 4 network types and do the appropriate routing.</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='server'>
|
|
<mac address='52:54:00:22:c9:42'>
|
|
<source address='192.168.0.1' port='5558'/>
|
|
</interface>
|
|
...
|
|
<interface type='client'>
|
|
<mac address='52:54:00:8b:c9:51'>
|
|
<source address='192.168.0.1' port='5558'/>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h5><a name="elementsNICSModel">Setting the NIC model</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet1'/>
|
|
<b><model type='ne2k_pci'/></b>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
For hypervisors which support this, you can set the model of
|
|
emulated network interface card.
|
|
</p>
|
|
|
|
<p>
|
|
The values for <code>type</code> aren't defined specifically by
|
|
libvirt, but by what the underlying hypervisor supports (if
|
|
any). For QEMU and KVM you can get a list of supported models
|
|
with these commands:
|
|
</p>
|
|
|
|
<pre>
|
|
qemu -net nic,model=? /dev/null
|
|
qemu-kvm -net nic,model=? /dev/null
|
|
</pre>
|
|
|
|
<p>
|
|
Typical values for QEMU and KVM include:
|
|
ne2k_isa i82551 i82557b i82559er ne2k_pci pcnet rtl8139 e1000 virtio
|
|
</p>
|
|
|
|
<h5><a name="elementsDriverBackendOptions">Setting NIC driver-specific options</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet1'/>
|
|
<model type='virtio'/>
|
|
<b><driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off'/></b>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
Some NICs may have tunable driver-specific options. These are
|
|
set as attributes of the <code>driver</code> sub-element of the
|
|
interface definition. Currently the following attributes are
|
|
available for the <code>"virtio"</code> NIC driver:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>
|
|
The optional <code>name</code> attribute forces which type of
|
|
backend driver to use. The value can be either 'qemu' (a
|
|
user-space backend) or 'vhost' (a kernel backend, which
|
|
requires the vhost module to be provided by the kernel); an
|
|
attempt to require the vhost driver without kernel support
|
|
will be rejected. If this attribute is not present, then the
|
|
domain defaults to 'vhost' if present, but silently falls back
|
|
to 'qemu' without error.
|
|
<span class="since">Since 0.8.8 (QEMU and KVM only)</span>
|
|
</dd>
|
|
<dt><code>txmode</code></dt>
|
|
<dd>
|
|
The <code>txmode</code> attribute specifies how to handle
|
|
transmission of packets when the transmit buffer is full. The
|
|
value can be either 'iothread' or 'timer'.
|
|
<span class="since">Since 0.8.8 (QEMU and KVM only)</span><br/><br/>
|
|
|
|
If set to 'iothread', packet tx is all done in an iothread in
|
|
the bottom half of the driver (this option translates into
|
|
adding "tx=bh" to the qemu commandline -device virtio-net-pci
|
|
option).<br/><br/>
|
|
|
|
If set to 'timer', tx work is done in qemu, and if there is
|
|
more tx data than can be sent at the present time, a timer is
|
|
set before qemu moves on to do other things; when the timer
|
|
fires, another attempt is made to send more data.<br/><br/>
|
|
|
|
The resulting difference, according to the qemu developer who
|
|
added the option is: "bh makes tx more asynchronous and reduces
|
|
latency, but potentially causes more processor bandwidth
|
|
contention since the cpu doing the tx isn't necessarily the
|
|
cpu where the guest generated the packets."<br/><br/>
|
|
|
|
<b>In general you should leave this option alone, unless you
|
|
are very certain you know what you are doing.</b>
|
|
</dd>
|
|
<dt><code>ioeventfd</code></dt>
|
|
<dd>
|
|
This optional attribute allows users to set
|
|
<a href='https://patchwork.kernel.org/patch/43390/'>
|
|
domain I/O asynchronous handling</a> for interface device.
|
|
The default is left to the discretion of the hypervisor.
|
|
Accepted values are "on" and "off". Enabling this allows
|
|
qemu to execute VM while a separate thread handles I/O.
|
|
Typically guests experiencing high system CPU utilization
|
|
during I/O will benefit from this. On the other hand,
|
|
on overloaded host it could increase guest I/O latency.
|
|
<span class="since">Since 0.9.3 (QEMU and KVM only)</span><br/><br/>
|
|
|
|
<b>In general you should leave this option alone, unless you
|
|
are very certain you know what you are doing.</b>
|
|
</dd>
|
|
<dt><code>event_idx</code></dt>
|
|
<dd>
|
|
The <code>event_idx</code> attribute controls some aspects of
|
|
device event processing. The value can be either 'on' or 'off'
|
|
- if it is on, it will reduce the number of interrupts and
|
|
exits for the guest. The default is determined by QEMU;
|
|
usually if the feature is supported, default is on. In case
|
|
there is a situation where this behavior is suboptimal, this
|
|
attribute provides a way to force the feature off.
|
|
<span class="since">Since 0.9.5 (QEMU and KVM only)</span><br/><br/>
|
|
|
|
<b>In general you should leave this option alone, unless you
|
|
are very certain you know what you are doing.</b>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h5><a name="elementsNICSTargetOverride">Overriding the target element</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<b><target dev='vnet1'/></b>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
If no target is specified, certain hypervisors will
|
|
automatically generate a name for the created tun device. This
|
|
name can be manually specifed, however the name <i>must not
|
|
start with either 'vnet' or 'vif'</i>, which are prefixes
|
|
reserved by libvirt and certain hypervisors. Manually specified
|
|
targets using these prefixes will be ignored.
|
|
</p>
|
|
|
|
<h5><a name="elementsNICSBoot">Specifying boot order</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet1'/>
|
|
<b><boot order='1'/></b>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
For hypervisors which support this, you can set a specific NIC to
|
|
be used for network boot. The <code>order</code> attribute determines
|
|
the order in which devices will be tried during boot sequence. The
|
|
per-device <code>boot</code> elements cannot be used together with
|
|
general boot elements in
|
|
<a href="#elementsOSBIOS">BIOS bootloader</a> section.
|
|
<span class="since">Since 0.8.8</span>
|
|
</p>
|
|
|
|
<h5><a name="elementsNICSROM">Interface ROM BIOS configuration</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet1'/>
|
|
<b><rom bar='on' file='/etc/fake/boot.bin'/></b>
|
|
</interface>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
For hypervisors which support this, you can change how a PCI Network
|
|
device's ROM is presented to the guest. The <code>bar</code>
|
|
attribute can be set to "on" or "off", and determines whether
|
|
or not the device's ROM will be visible in the guest's memory
|
|
map. (In PCI documentation, the "rombar" setting controls the
|
|
presence of the Base Address Register for the ROM). If no rom
|
|
bar is specified, the qemu default will be used (older
|
|
versions of qemu used a default of "off", while newer qemus
|
|
have a default of "on").
|
|
The optional <code>file</code> attribute is used to point to a
|
|
binary file to be presented to the guest as the device's ROM
|
|
BIOS. This can be useful to provide an alternative boot ROM for a
|
|
network device.
|
|
<span class="since">Since 0.9.10 (QEMU and KVM only)</span>.
|
|
</p>
|
|
|
|
<h5><a name="elementQoS">Quality of service</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet0'/>
|
|
<b><bandwidth>
|
|
<inbound average='1000' peak='5000' floor='200' burst='1024'/>
|
|
<outbound average='128' peak='256' burst='256'/>
|
|
</bandwidth></b>
|
|
</interface>
|
|
<devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
This part of interface XML provides setting quality of service. Incoming
|
|
and outgoing traffic can be shaped independently. The
|
|
<code>bandwidth</code> element can have at most one <code>inbound</code>
|
|
and at most one <code>outbound</code> child elements. Leaving any of these
|
|
children element out result in no QoS applied on that traffic direction.
|
|
So, when you want to shape only domain's incoming traffic, use
|
|
<code>inbound</code> only, and vice versa. Each of these elements have one
|
|
mandatory attribute <code>average</code> (or <code>floor</code> as
|
|
described below). <code>average</code> specifies average bit rate on
|
|
the interface being shaped. Then there are two optional attributes:
|
|
<code>peak</code>, which specifies maximum rate at which interface can send
|
|
data, and <code>burst</code>, amount of bytes that can be burst at
|
|
<code>peak</code> speed. Accepted values for attributes are integer
|
|
numbers. The units for <code>average</code> and <code>peak</code> attributes
|
|
are kilobytes per second, and for the <code>burst</code> just kilobytes.
|
|
<span class="since">Since 0.9.4</span> The <code>inbound</code> can
|
|
optionally have <code>floor</code> attribute. This is there for
|
|
guaranteeing minimal throughput for shaped interfaces. This, however,
|
|
requires that all traffic goes through one point where QoS decisions can
|
|
take place. That's why this attribute works only for virtual networks for
|
|
now (that is <code><interface type='network'/></code> with a
|
|
forward type of route, nat, or no forward at all). Moreover, the
|
|
virtual network the interface is connected to is required to have at least
|
|
inbound QoS set (<code>average</code> at least). Moreover, with
|
|
<code>floor<code> attribute users don't need to specify
|
|
<code>average</code>. However, <code>peak</code> and <code>burst</code>
|
|
attributes still require <code>average</code>. Currently, linux kernel
|
|
doesn't allow ingress qdiscs to have any classes therefore
|
|
<code>floor</code> can be applied only on <code>inbound</code> and not
|
|
</code>outbound</code>. <span class="since">Since 1.0.1</span>
|
|
</p>
|
|
|
|
<h5><a name="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='bridge'>
|
|
<b><vlan></b>
|
|
<b><tag id='42'/></b>
|
|
<b></vlan></b>
|
|
<source bridge='ovsbr0'/>
|
|
<virtualport type='openvswitch'>
|
|
<parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
|
|
</virtualport>
|
|
</interface>
|
|
<devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
If (and only if) the network connection used by the guest
|
|
supports vlan tagging transparent to the guest, an
|
|
optional <code><vlan></code> element can specify one or
|
|
more vlan tags to apply to the guest's network
|
|
traffic <span class="since">Since 0.10.0</span>. (openvswitch
|
|
and type='hostdev' SR-IOV interfaces do support transparent vlan
|
|
tagging of guest traffic; everything else, including standard
|
|
linux bridges and libvirt's own virtual networks, <b>do not</b>
|
|
support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
|
|
provide their own way (outside of libvirt) to tag guest traffic
|
|
onto specific vlans.) To allow for specification of multiple
|
|
tags (in the case of vlan trunking), a
|
|
subelement, <code><tag></code>, specifies which vlan tag
|
|
to use (for example: <code><tag id='42'/></code>. If an
|
|
interface has more than one <code><vlan></code> element
|
|
defined, it is assumed that the user wants to do VLAN trunking
|
|
using all the specified tags. In the case that vlan trunking
|
|
with a single tag is desired, the optional
|
|
attribute <code>trunk='yes'</code> can be added to the toplevel
|
|
vlan element.
|
|
</p>
|
|
|
|
<h5><a name="elementLink">Modifying virtual link state</a></h5>
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet0'/>
|
|
<b><link state='down'/></b>
|
|
</interface>
|
|
<devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
This element provides means of setting state of the virtual network link.
|
|
Possible values for attribute <code>state</code> are <code>up</code> and
|
|
<code>down</code>. If <code>down</code> is specified as the value, the interface
|
|
behaves as if it had the network cable disconnected. Default behavior if this
|
|
element is unspecified is to have the link state <code>up</code>.
|
|
<span class="since">Since 0.9.5</span>
|
|
</p>
|
|
|
|
<h4><a name="elementsInput">Input devices</a></h4>
|
|
|
|
<p>
|
|
Input devices allow interaction with the graphical framebuffer
|
|
in the guest virtual machine. When enabling the framebuffer, an
|
|
input device is automatically provided. It may be possible to
|
|
add additional devices explicitly, for example,
|
|
to provide a graphics tablet for absolute cursor movement.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<input type='mouse' bus='usb'/>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>input</code></dt>
|
|
<dd>The <code>input</code> element has one mandatory attribute,
|
|
the <code>type</code> whose value can be either 'mouse' or
|
|
'tablet'. The latter provides absolute
|
|
cursor movement, while the former uses relative movement. The optional
|
|
<code>bus</code> attribute can be used to refine the exact device type.
|
|
It takes values "xen" (paravirtualized), "ps2" and "usb".</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
The <code>input</code> element has an optional
|
|
sub-element <code><address></code> which can tie the
|
|
device to a particular PCI
|
|
slot, <a href="#elementsAddress">documented above</a>.
|
|
</p>
|
|
|
|
<h4><a name="elementsHub">Hub devices</a></h4>
|
|
|
|
<p>
|
|
A hub is a device that expands a single port into several so
|
|
that there are more ports available to connect devices to a host
|
|
system.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<hub type='usb'/>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>hub</code></dt>
|
|
<dd>The <code>hub</code> element has one mandatory attribute,
|
|
the <code>type</code> whose value can only be 'usb'.</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
The <code>hub</code> element has an optional
|
|
sub-element <code><address></code>
|
|
with <code>type='usb'</code>which can tie the device to a
|
|
particular controller, <a href="#elementsAddress">documented
|
|
above</a>.
|
|
</p>
|
|
|
|
<h4><a name="elementsGraphics">Graphical framebuffers</a></h4>
|
|
|
|
<p>
|
|
A graphics device allows for graphical interaction with the
|
|
guest OS. A guest will typically have either a framebuffer
|
|
or a text console configured to allow interaction with the
|
|
admin.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<graphics type='sdl' display=':0.0'/>
|
|
<graphics type='vnc' port='5904'>
|
|
<listen type='address' address='1.2.3.4'/>
|
|
</graphics>
|
|
<graphics type='rdp' autoport='yes' multiUser='yes' />
|
|
<graphics type='desktop' fullscreen='yes'/>
|
|
<graphics type='spice'>
|
|
<listen type='network' network='rednet'/>
|
|
</graphics>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>graphics</code></dt>
|
|
<dd>The <code>graphics</code> element has a mandatory <code>type</code>
|
|
attribute which takes the value "sdl", "vnc", "rdp" or "desktop":
|
|
<dl>
|
|
<dt><code>"sdl"</code></dt>
|
|
<dd>
|
|
This displays a window on the host desktop, it can take 3
|
|
optional arguments: a <code>display</code> attribute for
|
|
the display to use, an <code>xauth</code> attribute for
|
|
the authentication identifier, and an
|
|
optional <code>fullscreen</code> attribute accepting
|
|
values 'yes' or 'no'.
|
|
</dd>
|
|
<dt><code>"vnc"</code></dt>
|
|
<dd>
|
|
Starts a VNC server. The <code>port</code> attribute
|
|
specifies the TCP port number (with -1 as legacy syntax
|
|
indicating that it should be
|
|
auto-allocated). The <code>autoport</code> attribute is
|
|
the new preferred syntax for indicating autoallocation of
|
|
the TCP port to use. The <code>listen</code> attribute is
|
|
an IP address for the server to listen
|
|
on. The <code>passwd</code> attribute provides a VNC
|
|
password in clear text. The <code>keymap</code> attribute
|
|
specifies the keymap to use. It is possible to set a limit
|
|
on the validity of the password be giving an
|
|
timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
|
|
assumed to be in UTC. The <code>connected</code> attribute
|
|
allows control of connected client during password changes.
|
|
VNC accepts <code>keep</code> value only.
|
|
<span class="since">since 0.9.3</span>
|
|
NB, this may not be supported by all hypervisors.<br/> <br/>
|
|
Rather than using listen/port, QEMU supports a
|
|
<code>socket</code> attribute for listening on a unix
|
|
domain socket path.<span class="since">Since 0.8.8</span>
|
|
</dd>
|
|
<dt><code>"spice"</code></dt>
|
|
<dd>
|
|
<p>
|
|
Starts a SPICE server. The <code>port</code> attribute
|
|
specifies the TCP port number (with -1 as legacy syntax
|
|
indicating that it should be auto-allocated),
|
|
while <code>tlsPort</code> gives an alternative secure
|
|
port number. The <code>autoport</code> attribute is the
|
|
new preferred syntax for indicating autoallocation of
|
|
both port numbers. The <code>listen</code> attribute is
|
|
an IP address for the server to listen
|
|
on. The <code>passwd</code> attribute provides a SPICE
|
|
password in clear text. The <code>keymap</code>
|
|
attribute specifies the keymap to use. It is possible to
|
|
set a limit on the validity of the password be giving an
|
|
timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
|
|
assumed to be in UTC. The <code>connected</code> attribute
|
|
allows control of connected client during password changes.
|
|
SPICE accepts <code>keep</code> to keep client connected,
|
|
<code>disconnect</code> to disconnect client and
|
|
<code>fail</code> to fail changing password.
|
|
<span class="since">Since 0.9.3</span>
|
|
NB, this may not be supported by all hypervisors.
|
|
<span class="since">"spice" since 0.8.6</span>.
|
|
The <code>defaultMode</code> attribute sets the default channel
|
|
security policy, valid values are <code>secure</code>,
|
|
<code>insecure</code> and the default <code>any</code>
|
|
(which is secure if possible, but falls back to insecure
|
|
rather than erroring out if no secure path is
|
|
available). <span class="since">"defaultMode" since
|
|
0.9.12</span>.
|
|
</p>
|
|
<p>
|
|
When SPICE has both a normal and TLS secured TCP port
|
|
configured, it can be desirable to restrict what
|
|
channels can be run on each port. This is achieved by
|
|
adding one or more <channel> elements inside the
|
|
main <graphics> element. Valid channel names
|
|
include <code>main</code>, <code>display</code>,
|
|
<code>inputs</code>, <code>cursor</code>,
|
|
<code>playback</code>, <code>record</code>
|
|
(all <span class="since"> since 0.8.6</span>);
|
|
<code>smartcard</code> (<span class="since">since
|
|
0.8.8</span>); and <code>usbredir</code>
|
|
(<span class="since">since 0.9.12</span>).
|
|
</p>
|
|
<pre>
|
|
<graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
|
|
<channel name='main' mode='secure'/>
|
|
<channel name='record' mode='insecure'/>
|
|
<image compression='auto_glz'/>
|
|
<streaming mode='filter'/>
|
|
<clipboard copypaste='no'/>
|
|
<mouse mode='client'/>
|
|
</graphics></pre>
|
|
<p>
|
|
Spice supports variable compression settings for audio,
|
|
images and streaming, <span class="since">since
|
|
0.9.1</span>. These settings are accessible via
|
|
the <code>compression</code> attribute in all following
|
|
elements: <code>image</code> to set image compression
|
|
(accepts <code>auto_glz</code>, <code>auto_lz</code>,
|
|
<code>quic</code>, <code>glz</code>, <code>lz</code>,
|
|
<code>off</code>), <code>jpeg</code> for JPEG
|
|
compression for images over wan
|
|
(accepts <code>auto</code>, <code>never</code>,
|
|
<code>always</code>), <code>zlib</code> for configuring
|
|
wan image compression (accepts <code>auto</code>,
|
|
<code>never</code>, <code>always</code>)
|
|
and <code>playback</code> for enabling audio stream
|
|
compression (accepts <code>on</code> or <code>off</code>).
|
|
</p>
|
|
<p>
|
|
Streaming mode is set by the <code>streaming</code>
|
|
element, settings its <code>mode</code> attribute to one
|
|
of <code>filter</code>, <code>all</code>
|
|
or <code>off</code>, <span class="since">since 0.9.2</span>.
|
|
</p>
|
|
<p>
|
|
Copy & Paste functionality (via Spice agent) is set
|
|
by the <code>clipboard</code> element. It is enabled by
|
|
default, and can be disabled by setting
|
|
the <code>copypaste</code> property
|
|
to <code>no</code>, <span class="since">since
|
|
0.9.3</span>.
|
|
</p>
|
|
<p>
|
|
Mouse mode is set by the <code>mouse</code> element,
|
|
setting its <code>mode</code> attribute to one of
|
|
<code>server</code> or <code>client</code> ,
|
|
<span class="since">since 0.9.11</span>. If no mode is
|
|
specified, the qemu default will be used (client mode).
|
|
</p>
|
|
</dd>
|
|
<dt><code>"rdp"</code></dt>
|
|
<dd>
|
|
Starts a RDP server. The <code>port</code> attribute
|
|
specifies the TCP port number (with -1 as legacy syntax
|
|
indicating that it should be
|
|
auto-allocated). The <code>autoport</code> attribute is
|
|
the new preferred syntax for indicating autoallocation of
|
|
the TCP port to use. The <code>replaceUser</code>
|
|
attribute is a boolean deciding whether multiple
|
|
simultaneous connections to the VM are permitted.
|
|
The <code>multiUser</code> whether the existing connection
|
|
must be dropped and a new connection must be established
|
|
by the VRDP server, when a new client connects in single
|
|
connection mode.
|
|
</dd>
|
|
<dt><code>"desktop"</code></dt>
|
|
<dd>
|
|
This value is reserved for VirtualBox domains for the
|
|
moment. It displays a window on the host desktop,
|
|
similarly to "sdl", but using the VirtualBox viewer. Just
|
|
like "sdl", it accepts the optional
|
|
attributes <code>display</code>
|
|
and <code>fullscreen</code>.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
Rather than putting the address information used to set up the
|
|
listening socket for graphics types <code>vnc</code>
|
|
and <code>spice</code> in
|
|
the <code><graphics></code> <code>listen</code> attribute,
|
|
a separate subelement of <code><graphics></code>,
|
|
called <code><listen></code> can be specified (see the
|
|
examples above)<span class="since">since
|
|
0.9.4</span>. <code><listen></code> accepts the following
|
|
attributes:
|
|
</p>
|
|
<dl>
|
|
<dt><code>type</code></dt>
|
|
<dd>Set to either <code>address</code>
|
|
or <code>network</code>. This tells whether this listen
|
|
element is specifying the address to be used directly, or by
|
|
naming a network (which will then be used to determine an
|
|
appropriate address for listening).
|
|
</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>address</code></dt>
|
|
<dd>if <code>type='address'</code>, the <code>address</code>
|
|
attribute will contain either an IP address or hostname (which
|
|
will be resolved to an IP address via a DNS query) to listen
|
|
on. In the "live" XML of a running domain, this attribute will
|
|
be set to the IP address used for listening, even
|
|
if <code>type='network'</code>.
|
|
</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>network</code></dt>
|
|
<dd>if <code>type='network'</code>, the <code>network</code>
|
|
attribute will contain the name of a network in libvirt's list
|
|
of configured networks. The named network configuration will
|
|
be examined to determine an appropriate listen address. For
|
|
example, if the network has an IPv4 address in its
|
|
configuration (e.g. if it has a forward type
|
|
of <code>route</code>, <code>nat</code>, or no forward type
|
|
(isolated)), the first IPv4 address listed in the network's
|
|
configuration will be used. If the network is describing a
|
|
host bridge, the first IPv4 address associated with that
|
|
bridge device will be used, and if the network is describing
|
|
one of the 'direct' (macvtap) modes, the first IPv4 address of
|
|
the first forward dev will be used.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsVideo">Video devices</a></h4>
|
|
<p>
|
|
A video device.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<video>
|
|
<model type='vga' vram='8192' heads='1'>
|
|
<acceleration accel3d='yes' accel2d='yes'/>
|
|
</model>
|
|
</video>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>video</code></dt>
|
|
<dd>
|
|
The <code>video</code> element is the container for describing
|
|
video devices. For backwards compatibility, if no <code>video</code>
|
|
is set but there is a <code>graphics</code> in domain xml, then libvirt
|
|
will add a default <code>video</code> according to the guest type.
|
|
For a guest of type "kvm", the default <code>video</code> for it is:
|
|
<code>type</code> with value "cirrus", <code>vram</code> with value
|
|
"9216", and <code>heads</code> with value "1". By default, the first
|
|
video device in domain xml is the primary one, but the optional
|
|
attribute <code>primary</code> (<span class="since">since 1.0.2</span>)
|
|
with value 'yes' can be used to mark the primary in cases of mutiple
|
|
video device. The non-primary must be type of "qxl". The optional
|
|
attribute <code>ram</code> (<span class="since">since
|
|
1.0.2</span>) is allowed for "qxl" type only and specifies
|
|
the size of the primary bar, while <code>vram</code> specifies the
|
|
secondary bar size. If "ram" or "vram" are not supplied a default
|
|
value is used.
|
|
</dd>
|
|
|
|
<dt><code>model</code></dt>
|
|
<dd>
|
|
The <code>model</code> element has a mandatory <code>type</code>
|
|
attribute which takes the value "vga", "cirrus", "vmvga", "xen",
|
|
"vbox", or "qxl" (<span class="since">since 0.8.6</span>)
|
|
depending on the hypervisor features available.
|
|
You can also provide the amount of video memory in kibibytes
|
|
(blocks of 1024 bytes) using
|
|
<code>vram</code> and the number of screen with <code>heads</code>.
|
|
</dd>
|
|
|
|
<dt><code>acceleration</code></dt>
|
|
<dd>
|
|
If acceleration should be enabled (if supported) using the
|
|
<code>accel3d</code> and <code>accel2d</code> attributes in the
|
|
<code>acceleration</code> element.
|
|
</dd>
|
|
|
|
<dt><code>address</code></dt>
|
|
<dd>
|
|
The optional <code>address</code> sub-element can be used to
|
|
tie the video device to a particular PCI slot.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsConsole">Consoles, serial, parallel & channel devices</a></h4>
|
|
|
|
<p>
|
|
A character device provides a way to interact with the virtual machine.
|
|
Paravirtualized consoles, serial ports, parallel ports and channels are
|
|
all classed as character devices and so represented using the same syntax.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<parallel type='pty'>
|
|
<source path='/dev/pts/2'/>
|
|
<target port='0'/>
|
|
</parallel>
|
|
<serial type='pty'>
|
|
<source path='/dev/pts/3'/>
|
|
<target port='0'/>
|
|
</serial>
|
|
<console type='pty'>
|
|
<source path='/dev/pts/4'/>
|
|
<target port='0'/>
|
|
</console>
|
|
<channel type='unix'>
|
|
<source mode='bind' path='/tmp/guestfwd'/>
|
|
<target type='guestfwd' address='10.0.2.1' port='4600'/>
|
|
</channel>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
In each of these directives, the top-level element name (parallel, serial,
|
|
console, channel) describes how the device is presented to the guest. The
|
|
guest interface is configured by the <code>target</code> element.
|
|
</p>
|
|
|
|
<p>
|
|
The interface presented to the host is given in the <code>type</code>
|
|
attribute of the top-level element. The host interface is
|
|
configured by the <code>source</code> element.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>source</code> element may contain an optional
|
|
<code>seclabel</code> to override the way that labelling
|
|
is done on the socket path. If this element is not present,
|
|
the <a href="#seclabel">security label is inherited from
|
|
the per-domain setting</a>.
|
|
</p>
|
|
|
|
<p>
|
|
Each character device element has an optional
|
|
sub-element <code><address></code> which can tie the
|
|
device to a
|
|
particular <a href="#elementsControllers">controller</a> or PCI
|
|
slot.
|
|
</p>
|
|
|
|
<h5><a name="elementsCharGuestInterface">Guest interface</a></h5>
|
|
|
|
<p>
|
|
A character device presents itself to the guest as one of the following
|
|
types.
|
|
</p>
|
|
|
|
<h6><a name="elementCharParallel">Parallel port</a></h6>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<parallel type='pty'>
|
|
<source path='/dev/pts/2'/>
|
|
<target port='0'/>
|
|
</parallel>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
<code>target</code> can have a <code>port</code> attribute, which
|
|
specifies the port number. Ports are numbered starting from 0. There are
|
|
usually 0, 1 or 2 parallel ports.
|
|
</p>
|
|
|
|
<h6><a name="elementCharSerial">Serial port</a></h6>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type='pty'>
|
|
<source path='/dev/pts/3'/>
|
|
<target port='0'/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
<code>target</code> can have a <code>port</code> attribute, which
|
|
specifies the port number. Ports are numbered starting from 0. There are
|
|
usually 0, 1 or 2 serial ports. There is also an optional
|
|
<code>type</code> attribute <span class="since">since 1.0.2</span>
|
|
which has two choices for its value, one is <code>isa-serial</code>,
|
|
the other is <code>usb-serial</code>. If <code>type</code> is missing,
|
|
<code>isa-serial</code> will be used by default. For <code>usb-serial</code>
|
|
an optional sub-element <code><address></code> with
|
|
<code>type='usb'</code> can tie the device to a particular controller,
|
|
<a href="#elementsAddress">documented above</a>.
|
|
</p>
|
|
|
|
<h6><a name="elementCharConsole">Console</a></h6>
|
|
|
|
<p>
|
|
The console element is used to represent interactive consoles. Depending
|
|
on the type of guest in use, the consoles might be paravirtualized devices,
|
|
or they might be a clone of a serial device, according to the following
|
|
rules:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>If no <code>targetType</code> attribute is set, then the default
|
|
device type is according to the hypervisor's rules. The default
|
|
type will be added when re-querying the XML fed into libvirt.
|
|
For fully virtualized guests, the default device type will usually
|
|
be a serial port.</li>
|
|
<li>If the <code>targetType</code> attribute is <code>serial</code>,
|
|
then if no <code><serial></code> element exists, the console
|
|
element will be copied to the serial element. If a <code><serial></code>
|
|
element does already exist, the console element will be ignored.</li>
|
|
<li>If the <code>targetType</code> attribute is not <code>serial</code>,
|
|
it will be treated normally.</li>
|
|
<li>Only the first <code>console</code> element may use a <code>targetType</code>
|
|
of <code>serial</code>. Secondary consoles must all be paravirtualized.
|
|
</li>
|
|
<li>On s390, the <code>console</code> element may use a
|
|
<code>targetType</code> of <code>sclp</code> or <code>sclplm</code>
|
|
(line mode). SCLP is the native console type for s390. There's no
|
|
controller associated to SCLP consoles.
|
|
<span class="since">Since 1.0.2</span>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
A virtio console device is exposed in the
|
|
guest as /dev/hvc[0-7] (for more information, see
|
|
<a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>)
|
|
<span class="since">Since 0.8.3</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<console type='pty'>
|
|
<source path='/dev/pts/4'/>
|
|
<target port='0'/>
|
|
</console>
|
|
|
|
<!-- KVM virtio console -->
|
|
<console type='pty'>
|
|
<source path='/dev/pts/5'/>
|
|
<target type='virtio' port='0'/>
|
|
</console>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<!-- KVM s390 sclp console -->
|
|
<console type='pty'>
|
|
<source path='/dev/pts/1'/>
|
|
<target type='sclp' port='0'/>
|
|
</console>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
If the console is presented as a serial port, the <code>target</code>
|
|
element has the same attributes as for a serial port. There is usually
|
|
only 1 console.
|
|
</p>
|
|
|
|
<h6><a name="elementCharChannel">Channel</a></h6>
|
|
|
|
<p>
|
|
This represents a private communication channel between the host and the
|
|
guest.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<channel type='unix'>
|
|
<source mode='bind' path='/tmp/guestfwd'/>
|
|
<target type='guestfwd' address='10.0.2.1' port='4600'/>
|
|
</channel>
|
|
|
|
<!-- KVM virtio channel -->
|
|
<channel type='pty'>
|
|
<target type='virtio' name='arbitrary.virtio.serial.port.name'/>
|
|
</channel>
|
|
<channel type='unix'>
|
|
<source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/>
|
|
<target type='virtio' name='org.qemu.guest_agent.0'/>
|
|
</channel>
|
|
<channel type='spicevmc'>
|
|
<target type='virtio' name='com.redhat.spice.0'/>
|
|
</channel>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
This can be implemented in a variety of ways. The specific type of
|
|
channel is given in the <code>type</code> attribute of the
|
|
<code>target</code> element. Different channel types have different
|
|
<code>target</code> attributes.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>guestfwd</code></dt>
|
|
<dd>TCP traffic sent by the guest to a given IP address and port is
|
|
forwarded to the channel device on the host. The <code>target</code>
|
|
element must have <code>address</code> and <code>port</code> attributes.
|
|
<span class="since">Since 0.7.3</span></dd>
|
|
|
|
<dt><code>virtio</code></dt>
|
|
<dd>Paravirtualized virtio channel. Channel is exposed in the guest under
|
|
/dev/vport*, and if the optional element <code>name</code> is specified,
|
|
/dev/virtio-ports/$name (for more info, please see
|
|
<a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>). The
|
|
optional element <code>address</code> can tie the channel to a
|
|
particular <code>type='virtio-serial'</code>
|
|
controller, <a href="#elementsAddress">documented above</a>.
|
|
With qemu, if <code>name</code> is "org.qemu.guest_agent.0",
|
|
then libvirt can interact with a guest agent installed in the
|
|
guest, for actions such as guest shutdown or file system quiescing.
|
|
<span class="since">Since 0.7.7, guest agent interaction
|
|
since 0.9.10</span></dd>
|
|
|
|
<dt><code>spicevmc</code></dt>
|
|
<dd>Paravirtualized SPICE channel. The domain must also have a
|
|
SPICE server as a <a href="#elementsGraphics">graphics
|
|
device</a>, at which point the host piggy-backs messages
|
|
across the <code>main</code> channel. The <code>target</code>
|
|
element must be present, with
|
|
attribute <code>type='virtio'</code>; an optional
|
|
attribute <code>name</code> controls how the guest will have
|
|
access to the channel, and defaults
|
|
to <code>name='com.redhat.spice.0'</code>. The
|
|
optional <code>address</code> element can tie the channel to a
|
|
particular <code>type='virtio-serial'</code> controller.
|
|
<span class="since">Since 0.8.8</span></dd>
|
|
</dl>
|
|
|
|
<h5><a name="elementsCharHostInterface">Host interface</a></h5>
|
|
|
|
<p>
|
|
A character device presents itself to the host as one of the following
|
|
types.
|
|
</p>
|
|
|
|
<h6><a name="elementsCharSTDIO">Domain logfile</a></h6>
|
|
|
|
<p>
|
|
This disables all input on the character device, and sends output
|
|
into the virtual machine's logfile
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<console type='stdio'>
|
|
<target port='1'/>
|
|
</console>
|
|
</devices>
|
|
...</pre>
|
|
|
|
|
|
<h6><a name="elementsCharFle">Device logfile</a></h6>
|
|
|
|
<p>
|
|
A file is opened and all data sent to the character
|
|
device is written to the file.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="file">
|
|
<source path="/var/log/vm/vm-serial.log"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h6><a name="elementsCharVC">Virtual console</a></h6>
|
|
|
|
<p>
|
|
Connects the character device to the graphical framebuffer in
|
|
a virtual console. This is typically accessed via a special
|
|
hotkey sequence such as "ctrl+alt+3"
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type='vc'>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h6><a name="elementsCharNull">Null device</a></h6>
|
|
|
|
<p>
|
|
Connects the character device to the void. No data is ever
|
|
provided to the input. All data written is discarded.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type='null'>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h6><a name="elementsCharPTY">Pseudo TTY</a></h6>
|
|
|
|
<p>
|
|
A Pseudo TTY is allocated using /dev/ptmx. A suitable client
|
|
such as 'virsh console' can connect to interact with the
|
|
serial port locally.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="pty">
|
|
<source path="/dev/pts/3"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
NB special case if <console type='pty'>, then the TTY
|
|
path is also duplicated as an attribute tty='/dev/pts/3'
|
|
on the top level <console> tag. This provides compat
|
|
with existing syntax for <console> tags.
|
|
</p>
|
|
|
|
<h6><a name="elementsCharHost">Host device proxy</a></h6>
|
|
|
|
<p>
|
|
The character device is passed through to the underlying
|
|
physical character device. The device types must match,
|
|
eg the emulated serial port should only be connected to
|
|
a host serial port - don't connect a serial port to a parallel
|
|
port.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="dev">
|
|
<source path="/dev/ttyS0"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h6><a name="elementsCharPipe">Named pipe</a></h6>
|
|
|
|
<p>
|
|
The character device writes output to a named pipe. See pipe(7) for
|
|
more info.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="pipe">
|
|
<source path="/tmp/mypipe"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h6><a name="elementsCharTCP">TCP client/server</a></h6>
|
|
|
|
<p>
|
|
The character device acts as a TCP client connecting to a
|
|
remote server.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="tcp">
|
|
<source mode="connect" host="0.0.0.0" service="2445"/>
|
|
<protocol type="raw"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
Or as a TCP server waiting for a client connection.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="tcp">
|
|
<source mode="bind" host="127.0.0.1" service="2445"/>
|
|
<protocol type="raw"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
Alternatively you can use <code>telnet</code> instead
|
|
of <code>raw</code> TCP. <span class="since">Since 0.8.5</span>
|
|
you can also use <code>telnets</code>
|
|
(secure telnet) and <code>tls</code>.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="tcp">
|
|
<source mode="connect" host="0.0.0.0" service="2445"/>
|
|
<protocol type="telnet"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
...
|
|
<serial type="tcp">
|
|
<source mode="bind" host="127.0.0.1" service="2445"/>
|
|
<protocol type="telnet"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h6><a name="elementsCharUDP">UDP network console</a></h6>
|
|
|
|
<p>
|
|
The character device acts as a UDP netconsole service,
|
|
sending and receiving packets. This is a lossy service.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="udp">
|
|
<source mode="bind" host="0.0.0.0" service="2445"/>
|
|
<source mode="connect" host="0.0.0.0" service="2445"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<h6><a name="elementsCharUNIX">UNIX domain socket client/server</a></h6>
|
|
|
|
<p>
|
|
The character device acts as a UNIX domain socket server,
|
|
accepting connections from local clients.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<serial type="unix">
|
|
<source mode="bind" path="/tmp/foo"/>
|
|
<target port="1"/>
|
|
</serial>
|
|
</devices>
|
|
...</pre>
|
|
|
|
|
|
<h4><a name="elementsSound">Sound devices</a></h4>
|
|
|
|
<p>
|
|
A virtual sound card can be attached to the host via the
|
|
<code>sound</code> element. <span class="since">Since 0.4.3</span>
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<sound model='es1370'/>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>sound</code></dt>
|
|
<dd>
|
|
The <code>sound</code> element has one mandatory attribute,
|
|
<code>model</code>, which specifies what real sound device is emulated.
|
|
Valid values are specific to the underlying hypervisor, though typical
|
|
choices are 'es1370', 'sb16', 'ac97', and 'ich6'
|
|
(<span class="since">
|
|
'ac97' only since 0.6.0, 'ich6' only since 0.8.8</span>)
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
<span class="since">Since 0.9.13</span>, a sound element
|
|
with <code>ich6</code> model can have optional
|
|
sub-elements <code><codec></code> to attach various audio
|
|
codecs to the audio device. If not specified, a default codec
|
|
will be attached to allow playback and recording. Valid values
|
|
are 'duplex' (advertise a line-in and a line-out) and 'micro'
|
|
(advertise a speaker and a microphone).
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<sound model='ich6'>
|
|
<codec type='micro'/>
|
|
<sound/>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
Each <code>sound</code> element has an optional
|
|
sub-element <code><address></code> which can tie the
|
|
device to a particular PCI
|
|
slot, <a href="#elementsAddress">documented above</a>.
|
|
</p>
|
|
|
|
<h4><a name="elementsWatchdog">Watchdog device</a></h4>
|
|
|
|
<p>
|
|
A virtual hardware watchdog device can be added to the guest via
|
|
the <code>watchdog</code> element.
|
|
<span class="since">Since 0.7.3, QEMU and KVM only</span>
|
|
</p>
|
|
|
|
<p>
|
|
The watchdog device requires an additional driver and management
|
|
daemon in the guest. Just enabling the watchdog in the libvirt
|
|
configuration does not do anything useful on its own.
|
|
</p>
|
|
|
|
<p>
|
|
Currently libvirt does not support notification when the
|
|
watchdog fires. This feature is planned for a future version of
|
|
libvirt.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<watchdog model='i6300esb'/>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<watchdog model='i6300esb' action='poweroff'/>
|
|
</devices>
|
|
</domain></pre>
|
|
|
|
<dl>
|
|
<dt><code>model</code></dt>
|
|
<dd>
|
|
<p>
|
|
The required <code>model</code> attribute specifies what real
|
|
watchdog device is emulated. Valid values are specific to the
|
|
underlying hypervisor.
|
|
</p>
|
|
<p>
|
|
QEMU and KVM support:
|
|
</p>
|
|
<ul>
|
|
<li> 'i6300esb' — the recommended device,
|
|
emulating a PCI Intel 6300ESB </li>
|
|
<li> 'ib700' — emulating an ISA iBase IB700 </li>
|
|
</ul>
|
|
</dd>
|
|
<dt><code>action</code></dt>
|
|
<dd>
|
|
<p>
|
|
The optional <code>action</code> attribute describes what
|
|
action to take when the watchdog expires. Valid values are
|
|
specific to the underlying hypervisor.
|
|
</p>
|
|
<p>
|
|
QEMU and KVM support:
|
|
</p>
|
|
<ul>
|
|
<li>'reset' — default, forcefully reset the guest</li>
|
|
<li>'shutdown' — gracefully shutdown the guest
|
|
(not recommended) </li>
|
|
<li>'poweroff' — forcefully power off the guest</li>
|
|
<li>'pause' — pause the guest</li>
|
|
<li>'none' — do nothing</li>
|
|
<li>'dump' — automatically dump the guest
|
|
<span class="since">Since 0.8.7</span></li>
|
|
</ul>
|
|
<p>
|
|
Note 1: the 'shutdown' action requires that the guest
|
|
is responsive to ACPI signals. In the sort of situations
|
|
where the watchdog has expired, guests are usually unable
|
|
to respond to ACPI signals. Therefore using 'shutdown'
|
|
is not recommended.
|
|
</p>
|
|
<p>
|
|
Note 2: the directory to save dump files can be configured
|
|
by <code>auto_dump_path</code> in file /etc/libvirt/qemu.conf.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsMemBalloon">Memory balloon device</a></h4>
|
|
|
|
<p>
|
|
A virtual memory balloon device is added to all Xen and KVM/QEMU
|
|
guests. It will be seen as <code>memballoon</code> element.
|
|
It will be automatically added when appropriate, so there is no
|
|
need to explicitly add this element in the guest XML unless a
|
|
specific PCI slot needs to be assigned.
|
|
<span class="since">Since 0.8.3, Xen, QEMU and KVM only</span>
|
|
Additionally, <span class="since">since 0.8.4</span>, if the
|
|
memballoon device needs to be explicitly disabled,
|
|
<code>model='none'</code> may be used.
|
|
</p>
|
|
|
|
<p>
|
|
Example automatically added device with KVM
|
|
</p>
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<memballoon model='virtio'/>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<p>
|
|
Example manually added device with static PCI slot 2 requested
|
|
</p>
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<watchdog model='virtio'/>
|
|
<address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
|
|
</devices>
|
|
</domain></pre>
|
|
|
|
<dl>
|
|
<dt><code>model</code></dt>
|
|
<dd>
|
|
<p>
|
|
The required <code>model</code> attribute specifies what type
|
|
of balloon device is provided. Valid values are specific to
|
|
the virtualization platform
|
|
</p>
|
|
<ul>
|
|
<li>'virtio' — default with QEMU/KVM</li>
|
|
<li>'xen' — default with Xen</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
<h4><a name="elementsRng">Random number generator device</a></h4>
|
|
|
|
<p>
|
|
The virtual random number generator device allows the host to pass
|
|
through entropy to guest operating systems.
|
|
<span class="since">Since 1.0.3</span>
|
|
</p>
|
|
|
|
<p>
|
|
Example: usage of the RNG device:
|
|
</p>
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<rng model='virtio'>
|
|
<rate period="2000" bytes="1234"/>
|
|
<backend model='random'>/dev/random</backend>
|
|
<!-- OR -->
|
|
<backend model='egd' type='udp'>
|
|
<source mode='bind' service='1234'>
|
|
<source mode='connect' host='1.2.3.4' service='1234'>
|
|
</backend>
|
|
</rng>
|
|
</devices>
|
|
...
|
|
</pre>
|
|
<dl>
|
|
<dt><code>model</code></dt>
|
|
<dd>
|
|
<p>
|
|
The required <code>model</code> attribute specifies what type
|
|
of RNG device is provided. Valid values are specific to
|
|
the virtualization platform:
|
|
</p>
|
|
<ul>
|
|
<li>'virtio' — supported by qemu and virtio-rng kernel module</li>
|
|
</ul>
|
|
</dd>
|
|
<dt><code>rate</code></dt>
|
|
<dd>
|
|
<p>
|
|
The optional <code>rate</code> element allows limiting the rate at
|
|
which entropy can be consumed from the source. The mandatory
|
|
attribute <code>bytes</code> specifies how many bytes are permitted
|
|
to be consumed per period. An optional <code>period</code> attribute
|
|
specifies the duration of a period in milliseconds; if omitted, the
|
|
period is taken as 1000 milliseconds (1 second).
|
|
<span class='since'>Since 1.0.4</span>
|
|
</p>
|
|
</dd>
|
|
<dt><code>backend</code></dt>
|
|
<dd>
|
|
<p>
|
|
The <code>backend</code> element specifies the source of entropy
|
|
to be used for the domain. The source model is configured using the
|
|
<code>model</code> attribute. Supported source models are:
|
|
</p>
|
|
<ul>
|
|
<li>'random' — /dev/random (default) or /dev/hwrng
|
|
device as source (for now, no other sources are permitted)</li>
|
|
<li>'egd' — a EGD protocol backend</li>
|
|
</ul>
|
|
</dd>
|
|
<dt><code>backend model='random'</code></dt>
|
|
<dd>
|
|
<p>
|
|
This backend type expects a non-blocking character device as input.
|
|
Examples of such devices are /dev/random and /dev/urandom. The file
|
|
name is specified as contents of the <code>backend</code> element.
|
|
When no file name is specified the hypervisor default is used.
|
|
</p>
|
|
</dd>
|
|
<dt><code>backend model='egd'</code></dt>
|
|
<dd>
|
|
<p>
|
|
This backend connects to a source using the EGD protocol.
|
|
The source is specified as a character device. Refer to
|
|
<a href='#elementsCharHostInterface'>character device host interface</a>
|
|
for more information.
|
|
</p>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h3><a name="seclabel">Security label</a></h3>
|
|
|
|
<p>
|
|
The <code>seclabel</code> element allows control over the
|
|
operation of the security drivers. There are three basic
|
|
modes of operation, 'dynamic' where libvirt automatically
|
|
generates a unique security label, 'static' where the
|
|
application/administrator chooses the labels, or 'none'
|
|
where confinement is disabled. With dynamic
|
|
label generation, libvirt will always automatically
|
|
relabel any resources associated with the virtual machine.
|
|
With static label assignment, by default, the administrator
|
|
or application must ensure labels are set correctly on any
|
|
resources, however, automatic relabeling can be enabled
|
|
if desired. <span class="since">'dynamic' since 0.6.1, 'static'
|
|
since 0.6.2, and 'none' since 0.9.10.</span>
|
|
</p>
|
|
|
|
<p>
|
|
If more than one security driver is used by libvirt, multiple
|
|
<code>seclabel</code> tags can be used, one for each driver and
|
|
the security driver referenced by each tag can be defined using
|
|
the attribute <code>model</code>
|
|
</p>
|
|
|
|
<p>
|
|
Valid input XML configurations for the top-level security label
|
|
are:
|
|
</p>
|
|
|
|
<pre>
|
|
<seclabel type='dynamic' model='selinux'/>
|
|
|
|
<seclabel type='dynamic' model='selinux'>
|
|
<baselabel>system_u:system_r:my_svirt_t:s0</baselabel>
|
|
</seclabel>
|
|
|
|
<seclabel type='static' model='selinux' relabel='no'>
|
|
<label>system_u:system_r:svirt_t:s0:c392,c662</label>
|
|
</seclabel>
|
|
|
|
<seclabel type='static' model='selinux' relabel='yes'>
|
|
<label>system_u:system_r:svirt_t:s0:c392,c662</label>
|
|
</seclabel>
|
|
|
|
<seclabel type='none'/>
|
|
</pre>
|
|
|
|
<p>
|
|
If no 'type' attribute is provided in the input XML, then
|
|
the security driver default setting will be used, which
|
|
may be either 'none' or 'dynamic'. If a 'baselabel' is set
|
|
but no 'type' is set, then the type is presumed to be 'dynamic'
|
|
</p>
|
|
|
|
<p>
|
|
When viewing the XML for a running guest with automatic
|
|
resource relabeling active, an additional XML element,
|
|
<code>imagelabel</code>, will be included. This is an
|
|
output-only element, so will be ignored in user supplied
|
|
XML documents
|
|
</p>
|
|
<dl>
|
|
<dt><code>type</code></dt>
|
|
<dd>Either <code>static</code>, <code>dynamic</code> or <code>none</code>
|
|
to determine whether libvirt automatically generates a unique security
|
|
label or not.
|
|
</dd>
|
|
<dt><code>model</code></dt>
|
|
<dd>A valid security model name, matching the currently
|
|
activated security model
|
|
</dd>
|
|
<dt><code>relabel</code></dt>
|
|
<dd>Either <code>yes</code> or <code>no</code>. This must always
|
|
be <code>yes</code> if dynamic label assignment is used. With
|
|
static label assignment it will default to <code>no</code>.
|
|
</dd>
|
|
<dt><code>label</code></dt>
|
|
<dd>If static labelling is used, this must specify the full
|
|
security label to assign to the virtual domain. The format
|
|
of the content depends on the security driver in use:
|
|
<ul>
|
|
<li>SELinux: a SELinux context.</li>
|
|
<li>AppArmor: an AppArmor profile.</li>
|
|
<li>
|
|
DAC: owner and group separated by colon. They can be
|
|
defined both as user/group names or uid/gid. The driver will first
|
|
try to parse these values as names, but a leading plus sign can
|
|
used to force the driver to parse them as uid or gid.
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
<dt><code>baselabel</code></dt>
|
|
<dd>If dynamic labelling is used, this can optionally be
|
|
used to specify the base security label. The format
|
|
of the content depends on the security driver in use.
|
|
</dd>
|
|
<dt><code>imagelabel</code></dt>
|
|
<dd>This is an output only element, which shows the
|
|
security label used on resources associated with the virtual domain.
|
|
The format of the content depends on the security driver in use
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>When relabeling is in effect, it is also possible to fine-tune
|
|
the labeling done for specific source file names, by either
|
|
disabling the labeling (useful if the file lives on NFS or other
|
|
file system that lacks security labeling) or requesting an
|
|
alternate label (useful when a management application creates a
|
|
special label to allow sharing of some, but not all, resources
|
|
between domains), <span class="since">since 0.9.9</span>. When
|
|
a <code>seclabel</code> element is attached to a specific path
|
|
rather than the top-level domain assignment, only the
|
|
attribute <code>relabel</code> or the
|
|
sub-element <code>label</code> are supported.
|
|
</p>
|
|
|
|
<h2><a name="examples">Example configs</a></h2>
|
|
|
|
<p>
|
|
Example configurations for each driver are provide on the
|
|
driver specific pages listed below
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="drvxen.html#xmlconfig">Xen examples</a></li>
|
|
<li><a href="drvqemu.html#xmlconfig">QEMU/KVM examples</a></li>
|
|
</ul>
|
|
</body>
|
|
</html>
|