mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-25 15:15:25 +00:00
ef79fb5b5f
Once it's plugged in, the <listen> element will be an optional
replacement for the "listen" attribute that graphics elements already
have. If the <listen> element is type='address', it will have an
attribute called 'address' which will contain an IP address or dns
name that the guest's display server should listen on. If, however,
type='network', the <listen> element should have an attribute called
'network' that will be set to the name of a network configuration to
get the IP address from.
* docs/schemas/domain.rng: updated to allow the <listen> element
* docs/formatdomain.html.in: document the <listen> element and its
attributes.
* src/conf/domain_conf.[hc]:
1) The domain parser, formatter, and data structure are modified to
support 0 or more <listen> subelements to each <graphics>
element. The old style "legacy" listen attribute is also still
accepted, and will be stored internally just as if it were a
separate <listen> element. On output (i.e. format), the address
attribute of the first <listen> element of type 'address' will be
duplicated in the legacy "listen" attribute of the <graphic>
element.
2) The "listenAddr" attribute has been removed from the unions in
virDomainGRaphicsDef for graphics types vnc, rdp, and spice.
This attribute is now in the <listen> subelement (aka
virDomainGraphicsListenDef)
3) Helper functions were written to provide simple access
(both Get and Set) to the listen elements and their attributes.
* src/libvirt_private.syms: export the listen helper functions
* src/qemu/qemu_command.c, src/qemu/qemu_hotplug.c,
src/qemu/qemu_migration.c, src/vbox/vbox_tmpl.c,
src/vmx/vmx.c, src/xenxs/xen_sxpr.c, src/xenxs/xen_xm.c
Modify all these files to use the listen helper functions rather
than directly referencing the (now missing) listenAddr
attribute. There can be multiple <listen> elements to a single
<graphics>, but the drivers all currently only support one, so all
replacements of direct access with a helper function indicate index
"0".
* tests/* - only 3 of these are new files added explicitly to test the
new <listen> element. All the others have been modified to reflect
the fact that any legacy "listen" attributes passed in to the domain
parse will be saved in a <listen> element (i.e. one of the
virDomainGraphicsListenDefs), and during the domain format function,
both the <listen> element as well as the legacy attributes will be
output.
2978 lines
110 KiB
HTML
2978 lines
110 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>
|
|
<description>Some human readable description</description>
|
|
...</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>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>
|
|
</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'/>
|
|
</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. The
|
|
<code>boot</code> element cannot be used if per-device boot elements
|
|
are used (see <a href="#elementsDisks">disks</a>,
|
|
<a href="#elementsNICS">network interfaces</a>, and
|
|
<a href="#elementsUSB">USB and PCI devices</a> sections below).
|
|
<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>
|
|
</dd>
|
|
</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>
|
|
|
|
<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 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 virtual CPUs can be pinned
|
|
to. 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.
|
|
</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"/>
|
|
<shares>2048</shares>
|
|
<period>1000000</period>
|
|
<quota>-1</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
|
|
physical CPUS the domain VCPU will be pinned to. If this is ommited,
|
|
each VCPU 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>shares</code></dt>
|
|
<dd>
|
|
The optional <code>shares</code> element specifies the proportional
|
|
weighted share for the domain. If this is ommited, 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. (NB: Only qemu driver support)
|
|
<span class="since">Since 0.9.4</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. (NB: Only qemu driver support)
|
|
<span class="since">Since 0.9.4</span>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="elementsMemoryAllocation">Memory Allocation</a></h3>
|
|
|
|
<pre>
|
|
<domain>
|
|
...
|
|
<memory>524288</memory>
|
|
<currentMemory>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 kilobytes (i.e. blocks of 1024 bytes)</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</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>1048576</hard_limit>
|
|
<soft_limit>131072</soft_limit>
|
|
<swap_hard_limit>2097152</swap_hard_limit>
|
|
<min_guarantee>65536</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.</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 kilobytes (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
|
|
kilobytes (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
|
|
kilobytes (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
|
|
kilobytes (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 specify how to allocate memory
|
|
for the domain process on a NUMA host. It contains two attributes,
|
|
attribute <code>mode</code> is either 'interleave', 'strict',
|
|
or 'preferred',
|
|
attribute <code>nodeset</code> specifies the NUMA nodes, it leads same
|
|
syntax with attribute <code>cpuset</code> of element <code>vcpu</code>.
|
|
<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>
|
|
</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.</dd>
|
|
<dt><code>weight</code></dt>
|
|
<dd> The optional <code>weight</code> element is the I/O weight of the
|
|
guest. The value should be in range [100, 1000].</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>core2duo</model>
|
|
<vendor>Intel</vendor>
|
|
<topology sockets='1' cores='2' threads='1'/>
|
|
<feature policy='disable' name='lahf_lm'/>
|
|
</cpu>
|
|
...</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>.
|
|
</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.</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>
|
|
|
|
<h3><a name="elementsLifecycle">Lifecycle control</a></h3>
|
|
|
|
<p>
|
|
It is sometimes necessary to override the default actions taken
|
|
when a guest OS triggers a lifecycle operation. The following
|
|
collections of elements allow the actions to be specified. 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>
|
|
|
|
<pre>
|
|
...
|
|
<on_poweroff>destroy</on_poweroff>
|
|
<on_reboot>restart</on_reboot>
|
|
<on_crash>restart</on_crash>
|
|
...</pre>
|
|
|
|
<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>
|
|
|
|
<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/>
|
|
</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>hap</code></dt>
|
|
<dd>Enable use of Hardware Assisted Paging if available in
|
|
the hardware.
|
|
</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="none"/>
|
|
</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</dd>
|
|
<dt><code>localtime</code></dt>
|
|
<dd>
|
|
The guest clock will be synchronized to the host's configured
|
|
timezone when booted, if any.
|
|
</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. The delta relative to UTC is specified
|
|
in seconds, using the <code>adjustment</code> attribute.
|
|
The guest is free to adjust the RTC over time an expect
|
|
that it will be honoured at next reboot. This is in
|
|
contrast to 'utc' mode, where the RTC adjustments are
|
|
lost at each reboot. <span class="since">Since 0.7.7</span>
|
|
</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", "pit",
|
|
"rtc", "hpet", 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>
|
|
The <code>tickpolicy</code> attribute determines how
|
|
missed ticks in the guest are handled, and can be "delay",
|
|
"catchup", "merge", or "discard". If the policy is
|
|
"catchup", there can be further details in
|
|
the <code>catchup</code> sub-element.
|
|
<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>
|
|
</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'>
|
|
<driver name="tap" type="aio" cache="default"/>
|
|
<source file='/var/lib/xen/images/fv0'/>
|
|
<target dev='hda' bus='ide'/>
|
|
<boot order='2'/>
|
|
<encryption type='...'>
|
|
...
|
|
</encryption>
|
|
<shareable/>
|
|
<serial>
|
|
...
|
|
</serial>
|
|
</disk>
|
|
...
|
|
<disk type='network'>
|
|
<driver name="qemu" type="raw" io="threads" ioeventfd="on"/>
|
|
<source protocol="sheepdog" name="image_name">
|
|
<host name="hostname" port="7000"/>
|
|
</source>
|
|
<target dev="hdb" bus="ide"/>
|
|
<boot order='1'/>
|
|
<address type='drive' controller='0' bus='1' unit='0'/>
|
|
</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"
|
|
and "cdrom", defaulting to "disk".
|
|
<span class="since">Since 0.0.3; "device" attribute since 0.1.4;
|
|
"network" attribute since 0.8.7</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. 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", and "sheepdog". If the <code>protocol</code> attribute
|
|
is "rbd" or "sheepdog", an additional
|
|
attribute <code>name</code> is mandatory to specify which
|
|
image to be used. 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</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" or "usb". If omitted, the bus type is
|
|
inferred from the style of the device name. eg, a device named 'sda'
|
|
will typically be exported using a SCSI bus.
|
|
<span class="since">Since 0.0.3; <code>bus</code> attribute since 0.4.3;
|
|
"usb" attribute value since after 0.4.4</span></dd>
|
|
<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" and "writeback".
|
|
<span class="since">Since 0.6.0</span>
|
|
</li>
|
|
<li>
|
|
The optional <code>error_policy</code> attribute controls
|
|
how the hypervisor will behave on an error, possible
|
|
values are "stop", "ignore", and "enospace".
|
|
<span class="since">Since 0.8.0</span>
|
|
</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>
|
|
</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>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>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>host</code></dt>
|
|
<dd>The <code>host</code> element has two attributes "name" and "port",
|
|
which specify the hostname and the port number. 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>
|
|
</table>
|
|
</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 an
|
|
optional <code>domain</code>. For a "drive" controller,
|
|
additional attributes <code>controller</code>, <code>bus</code>,
|
|
and <code>unit</code> are available, each defaulting to 0.
|
|
</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'>
|
|
<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.
|
|
</dd>
|
|
<dt><code>type='template'</code></dt>
|
|
<dd>
|
|
OpenVZ filesystem template. Only used by OpenVZ driver.
|
|
</dd>
|
|
<dt><code>type='file'</code></dt>
|
|
<dd>
|
|
Currently unused.
|
|
</dd>
|
|
<dt><code>type='block'</code></dt>
|
|
<dd>
|
|
Currently unused.
|
|
</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>
|
|
</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>
|
|
An optional <code>readonly</code> attribute is available but currently
|
|
unused.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="elementsControllers">Controllers</a></h4>
|
|
|
|
<p>
|
|
Many devices that have an <code><address></code>
|
|
sub-element are designed to work with a controller to manage
|
|
related devices. 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", "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", "lsilogic", "lsias1068", or "vmpvscsi".
|
|
</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 like any other device's <code>address</code>
|
|
sub-element.
|
|
</p>
|
|
|
|
<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="elementsUSB">USB and PCI devices</a></h4>
|
|
|
|
<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>
|
|
<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'/>
|
|
</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.</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></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></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>. The
|
|
<code>bus</code> attribute allows the hexadecimal values 0 to ff, the
|
|
<code>slot</code> attribute allows the hexadecimal values 0 to 1f, and
|
|
the <code>function</code> attribute allows the hexadecimal values 0 to
|
|
7. There is also an optional <code>domain</code> attribute for the
|
|
PCI domain, with hexadecimal values 0 to ffff, but it is currently
|
|
not used by qemu.</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.
|
|
If present, the element must have an attribute
|
|
of <code>type='ccid'</code> as well as a <code>bus</code>
|
|
attribute listing the index of the bus that the smartcard
|
|
utilizes. An optional <code>slot</code> attribute lists which
|
|
slot within the bus. 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'/>
|
|
</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> and additional
|
|
attributes <code>domain</code>, <code>bus</code>, <code>slot</code>,
|
|
and <code>function</code> as appropriate.
|
|
</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>). Also,
|
|
similar to <code>direct</code> network connections (described
|
|
below), a connection of type <code>network</code> may specify
|
|
a <code>virtportprofile</code> element, with configuration data
|
|
to be forwarded to a vepa or 802.1Qbh compliant switch.
|
|
</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 type='802.1Qbg'>
|
|
<parameters managerid='11' typeid='1193047' typeidversion='2' 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>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='bridge'>
|
|
<source bridge='br0'/>
|
|
</interface>
|
|
...
|
|
<interface type='bridge'>
|
|
<source bridge='br0'/>
|
|
<target dev='vnet7'/>
|
|
<mac address="00:11:22:33:44:55"/>
|
|
</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'/>
|
|
...
|
|
<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'/>
|
|
...
|
|
<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'/>
|
|
...
|
|
<interface type='direct'>
|
|
<source dev='eth0' mode='private'/>
|
|
<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'>
|
|
<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'>
|
|
<source address='192.168.0.1' port='5558'/>
|
|
</interface>
|
|
...
|
|
<interface type='client'>
|
|
<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'/></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>
|
|
</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 exact NIC which should
|
|
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="elementQoS">Quality of service</a></h5>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet0'/>
|
|
<b><bandwidth>
|
|
<inbound average='1000' peak='5000' 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>. It specifies average bit rate on
|
|
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>
|
|
</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.
|
|
</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>.
|
|
</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>;
|
|
and <span class="since">since
|
|
0.8.8</span>: <code>smartcard</code>.
|
|
</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'/>
|
|
</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 it's <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>
|
|
</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' accel3d='yes'/>
|
|
</model>
|
|
</video>
|
|
</devices>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>video</code></dt>
|
|
<dd>
|
|
The <code>video</code> element is the a container for describing
|
|
video devices. For backwards compatability, 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".
|
|
</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 kilobytes 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>
|
|
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.
|
|
</p>
|
|
|
|
<h6><a name="elementCharConsole">Console</a></h6>
|
|
|
|
<p>
|
|
This represents the primary console. This can be the paravirtualized
|
|
console with Xen guests, virtio console for QEMU/KVM, or duplicates
|
|
the primary serial port for fully virtualized guests without a
|
|
paravirtualized console.
|
|
</p>
|
|
|
|
<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>
|
|
|
|
<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='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.
|
|
<span class="since">Since 0.7.7</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>
|
|
Each <code>sound</code> element has an optional
|
|
sub-element <code><address></code> which can tie the
|
|
device to a particular PCI slot.
|
|
</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>
|
|
|
|
<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 two basic
|
|
modes of operation, dynamic where libvirt automatically
|
|
generates a unique security label, or static where the
|
|
application/administrator chooses the labels. 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
|
|
</p>
|
|
|
|
<p>
|
|
Valid input XML configurations for the 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>
|
|
</pre>
|
|
|
|
<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> or <code>dynamic</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
|
|
</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>
|
|
|
|
<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>
|