mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-05 04:41:20 +00:00
c0c074c3aa
Not "Programmable Interrupt Controller" but "Peripheral Component Interconnect". Signed-off-by: Philipp Hahn <hahn@univention.de>
2318 lines
85 KiB
HTML
2318 lines
85 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'/>
|
|
</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>
|
|
</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="elementsResources">Basic resources</a></h3>
|
|
|
|
<pre>
|
|
...
|
|
<memory>524288</memory>
|
|
<currentMemory>524288</currentMemory>
|
|
<memoryBacking>
|
|
<hugepages/>
|
|
</memoryBacking>
|
|
<blkiotune>
|
|
<weight>800</weight>
|
|
</blkiotune>
|
|
<memtune>
|
|
<hard_limit>1048576</hard_limit>
|
|
<soft_limit>131072</soft_limit>
|
|
<swap_hard_limit>2097152</swap_hard_limit>
|
|
<min_guarantee>65536</min_guarantee>
|
|
</memtune>
|
|
<vcpu cpuset="1-4,^3,6" current="1">2</vcpu>
|
|
...</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>
|
|
<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>
|
|
<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>
|
|
<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.</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
|
|
swap the guest can use. The units for this value are kilobytes
|
|
(i.e. blocks of 1024 bytes)</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>
|
|
<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="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"/>
|
|
<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
|
|
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>
|
|
</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 as <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="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="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
|
|
</em></strong>
|
|
</p>
|
|
|
|
<p>
|
|
Provides a virtual network using a bridge device in the host.
|
|
Depending on the virtual network configuration, the network may be
|
|
totally isolated, NAT'ing to an explicit network device, or NAT'ing to
|
|
the default route. DHCP and DNS are provided on the virtual network in
|
|
all cases 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>
|
|
|
|
<pre>
|
|
...
|
|
<devices>
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
</interface>
|
|
...
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet7'/>
|
|
<mac address="00:11:22:33:44:55"/>
|
|
</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.
|
|
<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>
|
|
</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.
|
|
</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' mode='vepa'/>
|
|
<virtualport type="802.1Qbg">
|
|
<parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
|
|
</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'/></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>
|
|
</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>
|
|
|
|
<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'/>
|
|
<graphics type='rdp' autoport='yes' multiUser='yes' />
|
|
<graphics type='desktop' fullscreen='yes'/>
|
|
</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. 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. NB, this may not be supported by all hypervisors.
|
|
</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'/>
|
|
</graphics></pre>
|
|
</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>
|
|
|
|
<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.
|
|
</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", "qxl",
|
|
"xen" or "vbox", 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 1. 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 1. 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>
|
|
|
|
<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>
|