From nobody Fri Mar 29 08:27:12 2024
Delivered-To: importer@patchew.org
Received-SPF: pass (zohomail.com: domain of redhat.com designates
205.139.110.61 as permitted sender) client-ip=205.139.110.61;
envelope-from=libvir-list-bounces@redhat.com;
helo=us-smtp-delivery-1.mimecast.com;
Authentication-Results: mx.zohomail.com;
dkim=pass;
spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass(p=none dis=none) header.from=redhat.com
ARC-Seal: i=1; a=rsa-sha256; t=1595510518; cv=none;
d=zohomail.com; s=zohoarc;
b=I/N5waYRu5SKSXuhXM2R7aXukD9IZWiQ1KsvAvOMZHoV4Erwutn8MbAfHKZKMULGDZH0WQHoGZk9+cNggMKxrB0J+j2qg25BDtsuzW3N1jphDcTdL1YEAmSvtf0njgViP3h0H2aZ1TmXrD0AQxrlEUpRSkC9+gsm0N1KP78uOls=
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com;
s=zohoarc;
t=1595510518;
h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To;
bh=Np0yQI6CsdzE7lu+vhxFGEMOe6KnUcV2Wagth0h+OHY=;
b=fxDVvy+NJuEvlGqfATfg0W/Gu1LGVA2keYpW97c5TMXiIxXDhevEZ1dj/Qzz0Vxsq1ym/HLSS3cIGYZEk5rPLsbLGbFuHZ+fajqbyWSnPEfYCvX67sF/OvrVca5DFg02Zx44qwFUkc9J5krALv8GZOlVTS78Va+afQCPgQ0rw5A=
ARC-Authentication-Results: i=1; mx.zohomail.com;
dkim=pass;
spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass header.from=
- This section describes the XML format used to represent domains, the=
re are
- variations on the format based on the kind of domains run and the op=
tions
- used to launch them. For hypervisor specific details consult the
- driver docs
-
- The root element required for all virtual machines is
- named
- The libvirt XML parser will accept both a provided GUID value
- or just <genid/> in which case a GUID will be generated
- and saved in the XML. For the transitions such as above, libvirt
- will change the GUID before re-executing.
- There are a number of different ways to boot virtual machines
- each with their own pros and cons.
-
- 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.
- Up till here the BIOS/UEFI configuration knobs are generic enough=
to
- be implemented by majority (if not all) firmwares out there. However,
- from now on not every single setting makes sense to all firmwares. F=
or
- instance,
- 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
- 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 capabili=
ty
- is usually available for both para and full virtualized guests.
-
- When booting a domain using container based virtualization, instead
- of a kernel / boot image, a path to the init binary is required, usi=
ng
- the
- To set environment variables, use the
- To set a custom work directory for the init, use the
- To run the init command as a given user or group, use the
- If you want to enable user namespace, set the
- 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
- The
- IOThreads are dedicated event loop threads for supported disk
- devices to perform block I/O requests in order to improve
- scalability especially on an SMP host/guest with many LUNs.
- Since 1.2.8 (QEMU only)
- The optional
- Hypervisors may allow for virtual machines to be placed into
- resource partitions, potentially with nesting of said partitions.
- The
- Resource partitions are currently supported by the QEMU and
- LXC drivers, which map partition paths to cgroups directories,
- in all mounted controllers. Since 1.0.5
-
- Requirements for CPU model, its features and topology can be specifi=
ed
- using the following collection of elements.
- Since 0.7.5
-
- In case no restrictions need to be put on CPU model and its features=
, a
- simpler Individual CPU feature names are specified as part of the
-
- Guest NUMA topology can be specified using the
- Each for inline literals (``blah``) in rst
but rather puts them in the '.literal' class. Add a selector for making
them bold as well.
Signed-off-by: Peter Krempa
which was nested in a link () was removed as rst
doesn't support nesting of inline markup.
Signed-off-by: Peter Krempa
- will be matched with the maximum number of virtual CPUs declared in =
the
- Domain XML format
-
-
-
-
Element and attribute overview
-
- domain
. It has two attributes, the
- type
- specifies the hypervisor used for running
- the domain. The allowed values are driver specific, but
- include "xen", "kvm", "qemu" and "lxc". The
- second attribute is id
which is a unique
- integer identifier for the running guest machine. Inactive
- machines have no id value.
- General metadata
-
-
-<domain type=3D'kvm' id=3D'1'>
- <name>MyGuest</name>
- <uuid>4dea22b3-1d52-d8f3-2516-782e98ab3fa0</uuid>
- <genid>43dc0cf8-809b-4adb-9bea-a9abb5f3d90e</genid>
- <title>A short description - title - of the domain</title>
- <description>Some human readable description</description>
- <metadata>
- <app1:foo xmlns:app1=3D"http://app1.org/app1/">..</app1:foo&g=
t;
- <app2:bar xmlns:app2=3D"http://app1.org/app2/">..</app2:bar&g=
t;
- </metadata>
- ...
-
-
-
-
- name
name
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. Since 0.0.1uuid
uuid
element provides
- a globally unique identifier for the virtual machine.
- The format must be RFC 4122 compliant,
- eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b
.
- If omitted when defining/creating a new machine, a random
- UUID is generated. It is also possible to provide the UUID
- via a sysinfo
- specification. Since 0.0.1, sysinfo
- since 0.8.7genid
genid
- element can be used to add a Virtual Machine Generation ID which
- exposes a 128-bit, cryptographically random, integer value identif=
ier,
- referred to as a Globally Unique Identifier (GUID) using the same
- format as the uuid
. The value is used to help notify
- the guest operating system when the virtual machine is re-executing
- something that has already executed before, such as:
-
-
-
-
- The guest operating system notices the change and is then able to
- react as appropriate by marking its copies of distributed databases
- as dirty, re-initializing its random number generator, etc.
-
- title
title
provides space for a
- short description of the domain. The title should not contain
- any newlines. Since 0.9.10.description
description
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. Since 0.7.2metadata
metadata
node can be used by applications
- to store custom metadata in the form of XML
- nodes/trees. Applications must use custom namespaces on their
- XML nodes/trees, with only one top-level element per namespace
- (if the application needs structure, they should have
- sub-elements to their namespace
- element). Since 0.9.10Operating system booting
-
- BIOS bootloader
-
-
-...
-<os firmware=3D'efi'>
- <type>hvm</type>
- <loader readonly=3D'yes' secure=3D'no' type=3D'rom'>/usr/lib/xen/b=
oot/hvmloader</loader>
- <nvram template=3D'/usr/share/OVMF/OVMF_VARS.fd'>/var/lib/libvirt/=
nvram/guest_VARS.fd</nvram>
- <boot dev=3D'hd'/>
- <boot dev=3D'cdrom'/>
- <bootmenu enable=3D'yes' timeout=3D'3000'/>
- <smbios mode=3D'sysinfo'/>
- <bios useserial=3D'yes' rebootTimeout=3D'0'/>
-</os>
-...
-
-
-
- firmware
firmware
attribute allows management
- applications to automatically fill <loader/>
- and <nvram/>
elements and possibly enable
- some features required by selected firmware. Accepted values are
- bios
and efi
.
- The selection process scans for files describing installed
- firmware images in specified location and uses the most specific
- one which fulfils domain requirements. The locations in order of
- preference (from generic to most specific one) are:
-
-
- For more information refer to firmware metadata specification as
- described in /usr/share/qemu/firmware
/etc/qemu/firmware
$XDG_CONFIG_HOME/qemu/firmware
docs/interop/firmware.json
in QEMU
- repository. Regular users do not need to bother.
- Since 5.2.0 (QEMU and KVM only)
- For VMware guests, this is set to efi
when the guest
- uses UEFI, and it is not set when using BIOS.
- Since 5.3.0 (VMware ESX and Workstation/Play=
er)
- type
type
element specifies the
- type of operating system to be booted in the virtual machine.
- hvm
indicates that the OS is one designed to run
- on bare metal, so requires full virtualization. linux
- (badly named!) refers to an OS that supports the Xen 3 hypervisor
- guest ABI. There are also two optional attributes, arch
- specifying the CPU architecture to virtualization,
- and
machine
refe=
rring
- to the machine type. The Capabilities =
XML
- provides details on allowed values for
- these. If arch
is omitted then for most hypervisor
- drivers, the host native arch will be chosen. For the test=
code>,
-
ESX
and VMWare
hypervisor drivers, howev=
er,
- the i686
arch will always be chosen even on an
- x86_64
host. Since 0.0.1=
loader
loader
tag refers to a firmware blob,
- which is specified by absolute path,
- used to assist the domain creation process. It is used by Xen
- fully virtualized domains as well as setting the QEMU BIOS file
- path for QEMU/KVM domains. Xen since 0.1.0,
- QEMU/KVM since 0.9.12 Then, since
- 1.2.8 it's possible for the element to have two
- optional attributes: readonly
(accepted values are
- yes
and no
) to reflect the fact that the
- image should be writable or read-only. The second attribute
- type
accepts values rom
and
- pflash
. It tells the hypervisor where in the guest
- memory the file should be mapped. For instance, if the loader
- path points to an UEFI image, type
should be
- pflash
. Moreover, some firmwares may
- implement the Secure boot feature. Attribute
- secure
can be used then to control it.
- Since 2.1.0nvram
qemu.conf
. If needed, the template=
code>
- attribute can be used to per domain override map of master NVRAM s=
tores
- from the config file. Note, that for transient domains if the NVRA=
M file
- has been created by libvirt it is left behind and it is management
- application's responsibility to save and remove file (if needed to=
be
- persistent). Since 1.2.8
boot
dev
attribute takes one of the values "fd", "hd=
",
- "cdrom" or "network" and is used to specify the next boot device
- to consider. The boot
element can be repeated multiple
- times to setup a priority list of boot devices to try in turn.
- Multiple devices of the same type are sorted according to their
- targets while preserving the order of buses. After defining the
- domain, its XML configuration returned by libvirt (through
- virDomainGetXMLDesc) lists devices in the sorted order. Once sorte=
d,
- the first device is marked as bootable. Thus, e.g., a domain
- configured to boot from "hd" with vdb, hda, vda, and hdc disks
- assigned to it will boot from vda (the sorted list is vda, vdb, hd=
a,
- hdc). Similar domain with hdc, vda, vdb, and hda disks will boot f=
rom
- hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to
- configure in the desired way, which is why per-device boot elements
- (see disks,
- network interfaces, and
- USB and PCI devices sections belo=
w) were
- introduced and they are the preferred way providing full control o=
ver
- booting order. The boot
element and per-device boot
- elements are mutually exclusive. Since 0.1.3,
- per-device boot since 0.8.8
- smbios
mode
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
- virConnectGetSysinfo
call can be
- used to see what values are copied), or "sysinfo" (use the values =
in
- the sysinfo element). If not
- specified, the hypervisor default is used.
- Since 0.8.7
- rebootTimeout
doesn't make sense for UEFI,
- useserial
might not be usable with a BIOS firmware that
- doesn't produce any output onto serial line, etc. Moreover, firmwares
- don't usually export their capabilities for libvirt (or users) to ch=
eck.
- And the set of their capabilities can change with every new release.
- Hence users are advised to try the settings they use before relying =
on
- them in production.
-
-
- bootmenu
enable
attribute can be either "yes" or "n=
o".
- If not specified, the hypervisor default is used.
- Since 0.8.3
- Additional attribute timeout
takes the number of millis=
econds
- the boot menu should wait until it times out. Allowed values are nu=
mbers
- in range [0, 65535] inclusive and it is ignored unless enable<=
/code>
- is set to "yes". Since 1.2.8
-
bios
useserial
with possible
- values yes
or no
. It enables or disables
- Serial Graphics Adapter which allows users to see BIOS messages
- on a serial port. Therefore, one needs to have
- serial port defined.
- Since 0.9.4.
- Since 0.10.2 (QEMU only) there is
- another attribute, rebootTimeout
that controls
- whether and after how long the guest should start booting
- again in case the boot fails (according to BIOS). The value is
- in milliseconds with maximum of 65535
and special
- value -1
disables the reboot.
- Host bootloader
-
- pygrub
with Xen. The Bhyve hypervisor
- also uses a host bootloader, either bhyveload
or
- grub-bhyve
.
-
-...
-<bootloader>/usr/bin/pygrub</bootloader>
-<bootloader_args>--append single</bootloader_args>
-...
-
-
-
-
- bootloader
bootloader
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. Since 0.1.0=
bootloader_args
bootloader_args
element allows
- command line arguments to be passed to the bootloader.
- Since 0.2.3
- Direct kernel boot
-
-
-...
-<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=3DttyS0 ks=3Dhttp://example.com/f8-i386/os/</c=
mdline>
- <dtb>/root/ppc.dtb</dtb>
- <acpi>
- <table type=3D'slic'>/path/to/slic.dat</table>
- </acpi>
-</os>
-...
-
-
-
-
- type
loader
kernel
initrd
cmdline
dtb
acpi
table
element contains a fully-qualified path
- to the ACPI table. The type
attribute contains the
- ACPI table type (currently only slic
is supported)
- Since 1.3.5 (QEMU)
- Since 5.9.0 (Xen)Container boot
-
- init
element. By default this will be launched with
- no arguments. To specify the initial argv, use the initarg
- element, repeated as many time as is required. The
cmdline
- element, if set will be used to provide an equivalent to
/proc=
/cmdline
- but will not affect init argv.
- initenv
element, =
one
- for each variable.
- initdir=
code>
- element.
-
init=
user
- or initgroup
elements respectively. Both elements can b=
e provided
- either a user (resp. group) id or a name. Prefixing the user or grou=
p id with
- a +
will force it to be considered like a numeric value=
. Without
- this, it will be first tried as a user or group name.
-
-<os>
- <type arch=3D'x86_64'>exe</type>
- <init>/bin/systemd</init>
- <initarg>--unit</initarg>
- <initarg>emergency.service</initarg>
- <initenv name=3D'MYENV'>some value</initenv>
- <initdir>/my/custom/cwd</initdir>
- <inituser>tester</inituser>
- <initgroup>1000</initgroup>
-</os>
-
-
-
- idmap
ele=
ment.
- The uid
and gid
elements have three attrib=
utes:
-
-
-
- start
target
count
-<idmap>
- <uid start=3D'0' target=3D'1000' count=3D'10'/>
- <gid start=3D'0' target=3D'1000' count=3D'10'/>
-</idmap>
-
-
-
- SMBIOS System Information
-
- dmidecode
command in the guest). The
- optional sysinfo
element covers all such categories
- of information. Since 0.8.7
-
-...
-<os>
- <smbios mode=3D'sysinfo'/>
- ...
-</os>
-<sysinfo type=3D'smbios'>
- <bios>
- <entry name=3D'vendor'>LENOVO</entry>
- </bios>
- <system>
- <entry name=3D'manufacturer'>Fedora</entry>
- <entry name=3D'product'>Virt-Manager</entry>
- <entry name=3D'version'>0.9.4</entry>
- </system>
- <baseBoard>
- <entry name=3D'manufacturer'>LENOVO</entry>
- <entry name=3D'product'>20BE0061MC</entry>
- <entry name=3D'version'>0B98401 Pro</entry>
- <entry name=3D'serial'>W1KS427111E</entry>
- </baseBoard>
- <chassis>
- <entry name=3D'manufacturer'>Dell Inc.</entry>
- <entry name=3D'version'>2.12</entry>
- <entry name=3D'serial'>65X0XF2</entry>
- <entry name=3D'asset'>40000101</entry>
- <entry name=3D'sku'>Type3Sku1</entry>
- </chassis>
- <oemStrings>
- <entry>myappname:some arbitrary data</entry>
- <entry>otherappname:more arbitrary data</entry>
- </oemStrings>
-</sysinfo>
-<sysinfo type=3D'fwcfg'>
- <entry name=3D'opt/com.example/name'>example value</entry>
- <entry name=3D'opt/com.coreos/config' file=3D'/tmp/provision.ign'/>
-</sysinfo>
-...
-
- sysinfo
element has a mandatory
- attribute type
that determine the layout of
- sub-elements, with supported values of:
-
-
-
- smbios
smbios
sub-element of
- the os
element. Each
- sub-element of sysinfo
names a SMBIOS block, and
- within those elements can be a list of entry
- elements that describe a field within the block. The following
- blocks and entries are recognized:
-
-
- bios
-
- vendor
version
date
release
system
-
- manufacturer
product
version
serial
uuid
uuid
elemen=
t,
- then the two values must match.sku
family
baseBoard
-
- NB: Incorrectly supplied entries for the
- manufacturer
product
version
serial
asset
location
bios
, system
or baseBoard
- blocks will be ignored without error. Other than
uuid=
code>
- validation and
date
format checking, all values a=
re
- passed as strings to the hypervisor driver.
- chassis
-
- manufacturer
version
serial
asset
sku
oemStrings
entry
child elements, each prov=
iding
- arbitrary string data. There are no restrictions on what data =
can
- be provided in the entries, however, if the data is intended t=
o be
- consumed by an application in the guest, it is recommended to =
use
- the application name as a prefix in the string. (Since 4.1.0)
- fwcfg
/sys/firmware/qemu_fw_cfg
. Note, that the=
se
- values apply regardless the <smbios/> mode under <os/>.
- Since 6.5.0
-
-
- <smbios type=3D'fwcfg'>
- <entry name=3D'opt/com.example/name'>example value</entry>
- <entry name=3D'opt/com.coreos/config' file=3D'/tmp/provision.ign'/&=
gt;
- </smbios>
-
-
- The smbios
element can have multiple entry
- child elements. Each element then has mandatory name
- attribute, which defines the name of the blob and must begin with
- "opt/"
and to avoid clashing with other names is advis=
ed to
- be in form "opt/$RFQDN/$name"
where $RFQDN
is a
- reverse fully qualified domain name you control.
- Then, the element can either contain the value (to set the blob val=
ue
- directly), or file
attribute (to set the blob value fr=
om
- the file).
- CPU Allocation
-
-
-<domain>
- ...
- <vcpu placement=3D'static' cpuset=3D"1-4,^3,6" current=3D"1">2<=
/vcpu>
- <vcpus>
- <vcpu id=3D'0' enabled=3D'yes' hotpluggable=3D'no' order=3D'1'/>
- <vcpu id=3D'1' enabled=3D'no' hotpluggable=3D'yes'/>
- </vcpus>
- ...
-</domain>
-
-
-
-
-
- vcpu
-
- cpuset
cpuset
is a comma-separated
- list of physical CPU numbers that domain process and virtual CP=
Us
- can be pinned to by default. (NB: The pinning policy of domain
- process and virtual CPUs can be specified separately by
- cputune
. If the attribute emulatorpin
- of cputune
is specified, the cpuset
- specified by vcpu
here will be ignored. Similarly,
- for virtual CPUs which have the vcpupin
specified,
- the cpuset
specified by cpuset
here
- will be ignored. For virtual CPUs which don't have
- vcpupin
specified, each will be pinned to the phys=
ical
- CPUs specified by cpuset
here).
- Each element in that list is either a single CPU number,
- a range of CPU numbers, or a caret followed by a CPU number to
- be excluded from a previous range.
- Since 0.4.4
- current
current
can
- be used to specify whether fewer than the maximum number of
- virtual CPUs should be enabled.
- Since 0.8.5
- placement
placement
can be used to
- indicate the CPU placement mode for domain process. The value c=
an
- be either "static" or "auto", but defaults to placement=
code>
- of
numatune
or "static" if cpuset
is
- specified. Using "auto" indicates the domain process will be pi=
nned
- to the advisory nodeset from querying numad and the value of
- attribute cpuset
will be ignored if it's specified.
- If both cpuset
and placement
are not
- specified or if placement
is "static", but no
- cpuset
is specified, the domain process will be
- pinned to all the available physical CPUs.
- Since 0.9.11 (QEMU and KVM only)
- vcpus
id
attribute specifies the vCPU id as used by lib=
virt
- in other places such as vCPU pinning, scheduler information and NU=
MA
- assignment. Note that the vCPU ID as seen in the guest may differ =
from
- libvirt ID in certain cases. Valid IDs are from 0 to the maximum v=
CPU
- count as set by the vcpu
element minus 1.
-
- The enabled
attribute allows to control the state of =
the
- vCPU. Valid values are yes
and no
.
-
- hotpluggable
controls whether given vCPU can be hotpl=
ugged
- and hotunplugged in cases when the CPU is enabled at boot. Note th=
at
- all disabled vCPUs must be hotpluggable. Valid values are
- yes
and no
.
-
- order
allows to specify the order to add the online v=
CPUs.
- For hypervisors/platforms that require to insert multiple vCPUs at=
once
- the order may be duplicated across all vCPUs that need to be
- enabled at once. Specifying order is not necessary, vCPUs are then
- added in an arbitrary order. If order info is used, it must be use=
d for
- all online vCPUs. Hypervisors may clear or update ordering informa=
tion
- during certain operations to assure valid configuration.
-
- Note that hypervisors may create hotpluggable vCPUs differently fr=
om
- boot vCPUs thus special initialization may be necessary.
-
- Hypervisors may require that vCPUs enabled on boot which are not
- hotpluggable are clustered at the beginning starting with ID 0. It=
may
- be also required that vCPU 0 is always present and non-hotpluggabl=
e.
-
- Note that providing state for individual CPUs may be necessary to =
enable
- support of addressable vCPU hotplug and this feature may not be
- supported by all hypervisors.
-
- For QEMU the following conditions are required. vCPU 0 needs to be
- enabled and non-hotpluggable. On PPC64 along with it vCPUs that ar=
e in
- the same core need to be enabled as well. All non-hotpluggable CPUs
- present at boot need to be grouped after vCPU 0.
- Since 2.2.0 (QEMU only)
- IOThreads Allocation
-
-<domain>
- ...
- <iothreads>4</iothreads>
- ...
-</domain>
-
-
-<domain>
- ...
- <iothreadids>
- <iothread id=3D"2"/>
- <iothread id=3D"4"/>
- <iothread id=3D"6"/>
- <iothread id=3D"8"/>
- </iothreadids>
- ...
-</domain>
-
-
-
-
-
- iothreads
iothreadids
iothreadids
element provides the capabil=
ity
- to specifically define the IOThread ID's for the domain. By defau=
lt,
- IOThread ID's are sequentially numbered starting from 1 through the
- number of iothreads
defined for the domain. The
- id
attribute is used to define the IOThread ID. The
- id
attribute must be a positive integer greater than =
0.
- If there are less iothreadids
defined than
- iothreads
defined for the domain, then libvirt will
- sequentially fill iothreadids
starting at 1 avoiding
- any predefined id
. If there are more
- iothreadids
defined than iothreads
- defined for the domain, then the iothreads
value
- will be adjusted accordingly.
- Since 1.2.15
- CPU Tuning
-
-
-<domain>
- ...
- <cputune>
- <vcpupin vcpu=3D"0" cpuset=3D"1-4,^2"/>
- <vcpupin vcpu=3D"1" cpuset=3D"0,1"/>
- <vcpupin vcpu=3D"2" cpuset=3D"2,3"/>
- <vcpupin vcpu=3D"3" cpuset=3D"0,4"/>
- <emulatorpin cpuset=3D"1-3"/>
- <iothreadpin iothread=3D"1" cpuset=3D"5,6"/>
- <iothreadpin iothread=3D"2" cpuset=3D"7,8"/>
- <shares>2048</shares>
- <period>1000000</period>
- <quota>-1</quota>
- <global_period>1000000</global_period>
- <global_quota>-1</global_quota>
- <emulator_period>1000000</emulator_period>
- <emulator_quota>-1</emulator_quota>
- <iothread_period>1000000</iothread_period>
- <iothread_quota>-1</iothread_quota>
- <vcpusched vcpus=3D'0-4,^3' scheduler=3D'fifo' priority=3D'1'/>
- <iothreadsched iothreads=3D'2' scheduler=3D'batch'/>
- <cachetune vcpus=3D'0-3'>
- <cache id=3D'0' level=3D'3' type=3D'both' size=3D'3' unit=3D'MiB'=
/>
- <cache id=3D'1' level=3D'3' type=3D'both' size=3D'3' unit=3D'MiB'=
/>
- <monitor level=3D'3' vcpus=3D'1'/>
- <monitor level=3D'3' vcpus=3D'0-3'/>
- </cachetune>
- <cachetune vcpus=3D'4-5'>
- <monitor level=3D'3' vcpus=3D'4'/>
- <monitor level=3D'3' vcpus=3D'5'/>
- </cachetune>
- <memorytune vcpus=3D'0-3'>
- <node id=3D'0' bandwidth=3D'60'/>
- </memorytune>
-
- </cputune>
- ...
-</domain>
-
-
-
-
-
-
- cputune
cputune
element provides details
- regarding the CPU tunable parameters for the domain.
- Note: for the qemu driver, the optional vcpupin
- and emulatorpin
pinning settings are honored after
- the emulator is launched and NUMA constraints considered. This
- means that it is expected that other physical CPUs of the host
- will be used during this time by the domain, which will be
- reflected by the output of virsh cpu-stats
.
- Since 0.9.0
- vcpupin
vcpupin
element specifies which of host's
- physical CPUs the domain vCPU will be pinned to. If this is omitte=
d,
- and attribute cpuset
of element vcpu
is
- not specified, the vCPU is pinned to all the physical CPUs by defa=
ult.
- It contains two required attributes, the attribute vcpu
- specifies vCPU id, and the attribute
cpuset
is same as
- attribute cpuset
of element vcpu
.
- (NB: Only qemu driver support)
- Since 0.9.0
- emulatorpin
emulatorpin
element specifies which of =
host
- physical CPUs the "emulator", a subset of a domain not including =
vCPU
- or iothreads will be pinned to. If this is omitted, and attribute
- cpuset
of element vcpu
is not specified,
- "emulator" is pinned to all the physical CPUs by default. It cont=
ains
- one required attribute cpuset
specifying which physi=
cal
- CPUs to pin to.
- iothreadpin
iothreadpin
element specifies which of =
host
- physical CPUs the IOThreads will be pinned to. If this is omitted
- and attribute cpuset
of element vcpu
is
- not specified, the IOThreads are pinned to all the physical CPUs
- by default. There are two required attributes, the attribute
- iothread
specifies the IOThread ID and the attribute
- cpuset
specifying which physical CPUs to pin to. See
- the iothreadids
- description
=
- for valid iothread
values.
- Since 1.2.9
- shares
shares
element specifies the proportional
- weighted share for the domain. If this is omitted, it defaults to
- the OS provided defaults. NB, There is no unit for the value,
- it's a relative measure based on the setting of other VM,
- e.g. A VM configured with value
- 2048 will get twice as much CPU time as a VM configured with value=
1024.
- Since 0.9.0
- period
period
element specifies the enforcement
- interval (unit: microseconds). Within period
, each vC=
PU of
- the domain will not be allowed to consume more than quota
- worth of runtime. The value should be in range [1000, 1000000]. A =
period
- with value 0 means no value.
- Only QEMU driver support since 0.9.4, LXC si=
nce
- 0.9.10
-
quota
quota
element specifies the maximum allo=
wed
- bandwidth (unit: microseconds). A domain with quota
a=
s any
- negative value indicates that the domain has infinite bandwidth for
- vCPU threads, which means that it is not bandwidth controlled. The=
value
- should be in range [1000, 18446744073709551] or less than 0. A quo=
ta
- with value 0 means no value. You can use this feature to ensure th=
at all
- vCPUs run at the same speed.
- Only QEMU driver support since 0.9.4, LXC si=
nce
- 0.9.10
- global_period
global_period
element specifies the
- enforcement CFS scheduler interval (unit: microseconds) for the wh=
ole
- domain in contrast with period
which enforces the int=
erval
- per vCPU. The value should be in range 1000, 1000000]. A
- global_period
with value 0 means no value.
- Only QEMU driver support since 1.3.3
- global_quota
global_quota
element specifies the maxim=
um
- allowed bandwidth (unit: microseconds) within a period for the who=
le
- domain. A domain with global_quota
as any negative
- value indicates that the domain has infinite bandwidth, which mean=
s that
- it is not bandwidth controlled. The value should be in range
- [1000, 18446744073709551] or less than 0. A global_quota
- with value 0 means no value.
- Only QEMU driver support since 1.3.3
-
emulator_period
emulator_period
element specifies the en=
forcement
- interval (unit: microseconds). Within emulator_period
=
, emulator
- threads (those excluding vCPUs) of the domain will not be allowed =
to consume
- more than emulator_quota
worth of runtime. The value =
should be
- in range [1000, 1000000]. A period with value 0 means no value.
- Only QEMU driver support since 0.10.0
- emulator_quota
emulator_quota
element specifies the max=
imum
- allowed bandwidth (unit: microseconds) for domain's emulator threa=
ds (those
- excluding vCPUs). A domain with emulator_quota
as any=
negative
- value indicates that the domain has infinite bandwidth for emulato=
r threads
- (those excluding vCPUs), which means that it is not bandwidth cont=
rolled.
- The value should be in range [1000, 18446744073709551] or less tha=
n 0. A
- quota with value 0 means no value.
- Only QEMU driver support since 0.10.0
- iothread_period
iothread_period
element specifies the
- enforcement interval (unit: microseconds) for IOThreads. Within
- iothread_period
, each IOThread of the domain will
- not be allowed to consume more than iothread_quota
- worth of runtime. The value should be in range [1000, 1000000].
- An iothread_period with value 0 means no value.
- Only QEMU driver support since 2.1.0
- iothread_quota
iothread_quota
element specifies the max=
imum
- allowed bandwidth (unit: microseconds) for IOThreads. A domain with
- iothread_quota
as any negative value indicates that t=
he
- domain IOThreads have infinite bandwidth, which means that it is
- not bandwidth controlled. The value should be in range
- [1000, 18446744073709551] or less than 0. An iothread_quota<=
/code>
- with value 0 means no value. You can use this feature to ensure th=
at
- all IOThreads run at the same speed.
- Only QEMU driver support since 2.1.0
-
vcpusched
, iothreadsched
- and emulatorsched
vcpusched
, iothreadsched
- and emulatorsched
elements specify the scheduler type
- (values batch
, idle
, fifo
,
- rr
) for particular vCPU, IOThread and emulator threads
- respecively. For vcpusched
and iothreadsched=
code>
- the attributes
vcpus
and iothreads
select
- which vCPUs/IOThreads this setting applies to, leaving them out se=
ts the
- default. The element emulatorsched
does not have that
- attribute. Valid vcpus
values start at 0 through one =
less
- than the number of vCPU's defined for the
- domain. Valid iothreads
values are described in
- the iothreadids
- description
<=
/a>.
- If no iothreadids
are defined, then libvirt numbers
- IOThreads from 1 to the number of iothreads
available
- for the domain. For real-time schedulers (fifo
,
- rr
), priority must be specified as
- well (and is ignored for non-real-time ones). The value range
- for the priority depends on the host kernel (usually 1-99).
- Since 1.2.13
- emulatorsched
since 5.3.0
- cachetune
Since 4.1.0=
dt>
- cachetune
element can control allocations fo=
r CPU
- caches using the resctrl on the host. Whether or not is this suppo=
rted
- can be gathered from capabilities where some limitations like mini=
mum
- size and required granularity are reported as well. The required
- attribute vcpus
specifies to which vCPUs this allocat=
ion
- applies. A vCPU can only be member of one cachetune
e=
lement
- allocation. The vCPUs specified by cachetune can be identical with=
those
- in memorytune, however they are not allowed to overlap.
- Supported subelements are:
-
-
- cache
-
- level
id
type
code
for code
- (instructions), data
for data or both=
code>
- for both code and data (unified). Currently the allocation=
can
- be done only with the same type as the host supports, mean=
ing
- you cannot request
both
for host with CDP
- (code/data prioritization) enabled.
- size
unit
attribute can be used to =
scale
- the value.
- unit
(optional)memory
element
- for Memory Allocatio=
n)
- in which size
is specified, defaults to bytes.
- monitor
Since 4.10.0monitor
creates the cache
- monitor(s) for current cache allocation and has the following
- required attributes:
-
-
- level
vcpus
memorytune
Since 4.7.0<=
/dt>
- memorytune
element can control allocations f=
or
- memory bandwidth using the resctrl on the host. Whether or not is =
this
- supported can be gathered from capabilities where some limitations=
like
- minimum bandwidth and required granularity are reported as well. T=
he
- required attribute vcpus
specifies to which vCPUs this
- allocation applies. A vCPU can only be member of one
- memorytune
element allocation. The vcpus
=
specified
- by memorytune
can be identical to those specified by
- cachetune
. However they are not allowed to overlap ea=
ch other.
- Supported subelements are:
-
-
- node
-
- id
bandwidth
Memory Allocation
-
-
-<domain>
- ...
- <maxMemory slots=3D'16' unit=3D'KiB'>1524288</maxMemory>
- <memory unit=3D'KiB'>524288</memory>
- <currentMemory unit=3D'KiB'>524288</currentMemory>
- ...
-</domain>
-
-
-
-
-
-
- memory
unit
, which defaults to "KiB"
- (kibibytes, 210 or blocks of 1024 bytes). Valid
- units are "b" or "bytes" for bytes, "KB" for kilobytes
- (103 or 1,000 bytes), "k" or "KiB" for kibibytes
- (1024 bytes), "MB" for megabytes (106 or 1,000,000
- bytes), "M" or "MiB" for mebibytes (220 or
- 1,048,576 bytes), "GB" for gigabytes (109 or
- 1,000,000,000 bytes), "G" or "GiB" for gibibytes
- (230 or 1,073,741,824 bytes), "TB" for terabytes
- (1012 or 1,000,000,000,000 bytes), or "T" or "TiB"
- for tebibytes (240 or 1,099,511,627,776 bytes).
- However, the value will be rounded up to the nearest kibibyte
- by libvirt, and may be further rounded to the granularity
- supported by the hypervisor. Some hypervisors also enforce a
- minimum, such as 4000KiB.
-
- In case NUMA is configured for the gu=
est the
- memory
element can be omitted.
-
- In the case of crash, optional attribute dumpCore
- can be used to control whether the guest memory should be
- included in the generated coredump or not (values "on", "off").
-
- unit
since 0.9.11,
- dumpCore
since 0.10.2
- (QEMU only)maxMemory
<memory>
element=
or
- the NUMA cell size configuration can be increased by hot-plugging =
of
- memory to the limit specified by this element.
-
- The unit
attribute behaves the same as for
- <memory>
.
-
- The slots
attribute specifies the number of slots
- available for adding memory to the guest. The bounds are hypervisor
- specific.
-
- Note that due to alignment of the memory chunks added via memory
- hotplug the full size allocation specified by this element may be
- impossible to achieve.
- Since 1.2.14 supported by the QEMU driver.=
span>
- currentMemory
memory
element.
- The unit
attribute behaves the same as
- for memory
.Memory Backing
-
-
-<domain>
- ...
- <memoryBacking>
- <hugepages>
- <page size=3D"1" unit=3D"G" nodeset=3D"0-3,5"/>
- <page size=3D"2" unit=3D"M" nodeset=3D"4"/>
- </hugepages>
- <nosharepages/>
- <locked/>
- <source type=3D"file|anonymous|memfd"/>
- <access mode=3D"shared|private"/>
- <allocation mode=3D"immediate|ondemand"/>
- <discard/>
- </memoryBacking>
- ...
-</domain>
-
-
- memoryBacking
element may contain several
- elements that influence how virtual memory pages are backed by host
- pages.
-
-
-
- hugepages
page
element is
- introduced. It has one compulsory attribute size
which
- specifies which hugepages should be used (especially useful on syste=
ms
- supporting hugepages of different sizes). The default unit for the
- size
attribute is kilobytes (multiplier of 1024). If you
- want to use different unit, use optional unit
attribute.
- For systems with NUMA, the optional nodeset
attribute m=
ay
- come handy as it ties given guest's NUMA nodes to certain hugepage
- sizes. From the example snippet, one gigabyte hugepages are used for
- every NUMA node except node number four. For the correct syntax see
- this.nosharepages
locked
hard_limit
(see
- memory tuning) on memory all=
ocation
- suitable for the specific environment at the same time to mitigate
- the risks described above. Since 1.0.6source
type
attribute, it's possible to
- provide "file" to utilize file memorybacking or keep the
- default "anonymous". Since 4.10.0,
- you may choose "memfd" backing. (QEMU/KVM only)access
mode
attribute, specify if the memory is
- to be "shared" or "private". This can be overridden per numa node=
by
- memAccess
.allocation
mode
attribute, specify when to allocate
- the memory by supplying either "immediate" or "ondemand".discard
Memory Tuning
-
-
-<domain>
- ...
- <memtune>
- <hard_limit unit=3D'G'>1</hard_limit>
- <soft_limit unit=3D'M'>128</soft_limit>
- <swap_hard_limit unit=3D'G'>2</swap_hard_limit>
- <min_guarantee unit=3D'bytes'>67108864</min_guarantee>
- </memtune>
- ...
-</domain>
-
-
-
-
-
-
- memtune
memtune
element provides details
- regarding the memory tunable parameters for the domain. If this is
- omitted, it defaults to the OS provided defaults. For QEMU/KVM, the
- parameters are applied to the QEMU process as a whole. Thus, when
- counting them, one needs to add up guest RAM, guest video RAM, and
- some memory overhead of QEMU itself. The last piece is hard to
- determine so one needs guess and try. For each tunable, it
- is possible to designate which unit the number is in on
- input, using the same values as
- for <memory>
. For backwards
- compatibility, output is always in
- KiB. unit
- since 0.9.11
- Possible values for all *_limit parameters are in range from 0 to
- VIR_DOMAIN_MEMORY_PARAM_UNLIMITED.hard_limit
hard_limit
element is the maximum mem=
ory
- the guest can use. The units for this value are kibibytes (i.e. bl=
ocks
- of 1024 bytes). Users of QEMU and KVM are strongly advised not to =
set
- this limit as domain may get killed by the kernel if the guess is =
too
- low, and determining the memory needed for a process to run is an
-
- undecidable problem; that said, if you already set
- locked
in
- memory backing because your
- workload demands it, you'll have to take into account the specific=
s of
- your deployment and figure out a value for hard_limit
=
that
- is large enough to support the memory requirements of your guest, =
but
- small enough to protect your host against a malicious guest lockin=
g all
- memory.soft_limit
soft_limit
element is the memory limi=
t to
- enforce during memory contention. The units for this value are
- kibibytes (i.e. blocks of 1024 bytes)swap_hard_limit
swap_hard_limit
element is the maximum
- memory plus swap the guest can use. The units for this value are
- kibibytes (i.e. blocks of 1024 bytes). This has to be more than
- hard_limit value providedmin_guarantee
min_guarantee
element is the guarante=
ed
- minimum memory allocation for the guest. The units for this value =
are
- kibibytes (i.e. blocks of 1024 bytes). This element is only suppor=
ted
- by VMware ESX and OpenVZ drivers.NUMA Node Tuning
-
-
-<domain>
- ...
- <numatune>
- <memory mode=3D"strict" nodeset=3D"1-4,^3"/>
- <memnode cellid=3D"0" mode=3D"strict" nodeset=3D"1"/>
- <memnode cellid=3D"2" mode=3D"preferred" nodeset=3D"2"/>
- </numatune>
- ...
-</domain>
-
-
-
-
-
-
- numatune
numatune
element provides details of
- how to tune the performance of a NUMA host via controlling NUMA po=
licy
- for domain process. NB, only supported by QEMU driver.
- Since 0.9.3
- memory
memory
element specifies how to allocate=
memory
- for the domain process on a NUMA host. It contains several optional
- attributes. Attribute mode
is either 'interleave',
- 'strict', or 'preferred', defaults to 'strict'. Attribute
- nodeset
specifies the NUMA nodes, using the same synt=
ax as
- attribute cpuset
of element vcpu
. Attrib=
ute
- placement
(since 0.9.12)=
can be
- used to indicate the memory placement mode for domain process, its=
value
- can be either "static" or "auto", defaults to placement of
-
vcpu
, or "static" if nodeset
is specifie=
d.
- "auto" indicates the domain process will only allocate memory from=
the
- advisory nodeset returned from querying numad, and the value of at=
tribute
- nodeset
will be ignored if it's specified.
-
- If placement
of vcpu
is 'auto', and
- numatune
is not specified, a default numatune=
code>
- with
placement
'auto' and mode
'strict' =
will
- be added implicitly.
-
- Since 0.9.3
- memnode
memnode
elements can specify memory allocati=
on
- policies per each guest NUMA node. For those nodes having no
- corresponding memnode
element, the default from
- element memory
will be used. Attribute cellid<=
/code>
- addresses guest NUMA node for which the settings are applied.
- Attributes
mode
and nodeset
have the same
- meaning and syntax as in memory
element.
-
- This setting is not compatible with automatic placement.
- QEMU Since 1.2.7
- Block I/O Tuning
-
-<domain>
- ...
- <blkiotune>
- <weight>800</weight>
- <device>
- <path>/dev/sda</path>
- <weight>1000</weight>
- </device>
- <device>
- <path>/dev/sdb</path>
- <weight>500</weight>
- <read_bytes_sec>10000</read_bytes_sec>
- <write_bytes_sec>10000</write_bytes_sec>
- <read_iops_sec>20000</read_iops_sec>
- <write_iops_sec>20000</write_iops_sec>
- </device>
- </blkiotune>
- ...
-</domain>
-
-
-
-
-
-
- blkiotune
blkiotune
element provides the ability
- to tune Blkio cgroup tunable parameters for the domain. If this is
- omitted, it defaults to the OS provided
- defaults. Since 0.8.8weight
weight
element is the overall I/O
- weight of the guest. The value should be in the range [100,
- 1000]. After kernel 2.6.39, the value could be in the
- range [10, 1000].device
device
elements
- that further tune the weights for each host block device in
- use by the domain. Note that
- multiple guest disks can share a
- single host block device, if they are backed by files within
- the same host file system, which is why this tuning parameter
- is at the global domain level rather than associated with each
- guest disk device (contrast this to
- the <iotune>
- element which can apply to an
- individual <disk>
).
- Each device
element has two
- mandatory sub-elements, path
describing the
- absolute path of the device, and weight
giving
- the relative weight of that device, in the range [100,
- 1000]. After kernel 2.6.39, the value could be in the
- range [10, 1000]. Since 0.9.8
- Additionally, the following optional sub-elements can be used:
-
-
read_bytes_sec
write_bytes_sec
read_iops_sec
write_iops_sec
Resource partitioning
-
- resource
element groups together configuration
- related to resource partitioning. It currently supports a child
- element partition
whose content defines the absolute pa=
th
- of the resource partition in which to place the domain. If no
- partition is listed, then the domain will be placed in a default
- partition. It is the responsibility of the app/admin to ensure
- that the partition exists prior to starting the guest. Only the
- (hypervisor specific) default partition can be assumed to exist
- by default.
-
-...
-<resource>
- <partition>/virtualmachines/production</partition>
-</resource>
-...
-
-
- CPU model and topology
-
-
-...
-<cpu match=3D'exact'>
- <model fallback=3D'allow'>core2duo</model>
- <vendor>Intel</vendor>
- <topology sockets=3D'1' dies=3D'1' cores=3D'2' threads=3D'1'/>
- <cache level=3D'3' mode=3D'emulate'/>
- <feature policy=3D'disable' name=3D'lahf_lm'/>
-</cpu>
-...
-
-
-<cpu mode=3D'host-model'>
- <model fallback=3D'forbid'/>
- <topology sockets=3D'1' dies=3D'1' cores=3D'2' threads=3D'1'/>
-</cpu>
-...
-
-
-<cpu mode=3D'host-passthrough' migratable=3D'off'>
- <cache mode=3D'passthrough'/>
- <feature policy=3D'disable' name=3D'lahf_lm'/>
-...
-
- cpu
element can be used.
- Since 0.7.6
-
-...
-<cpu>
- <topology sockets=3D'1' dies=3D'1' cores=3D'2' threads=3D'1'/>
-</cpu>
-...
-
-
-
-
- cpu
cpu
element is the main container for describing
- guest CPU requirements. Its match
attribute specifies=
how
- strictly the virtual CPU provided to the guest matches these
- requirements. Since 0.7.6 the
- match
attribute can be omitted if topology
- is the only element within
cpu
. Possible values for t=
he
- match
attribute are:
-
-
-
-
- Since 0.8.5 the minimum
host-model
mode; the domain
- will not be created if the provided virtual CPU does not meet
- the requirements.exact
strict
match
- attribute can be omitted and will default to exact
.
-
- Sometimes the hypervisor is not able to create a virtual CPU exact=
ly
- matching the specification passed by libvirt.
- Since 3.2.0, an optional check<=
/code>
- attribute can be used to request a specific way of checking whether
- the virtual CPU matches the specification. It is usually safe to o=
mit
- this attribute when starting a domain and stick with the default
- value. Once the domain starts, libvirt will automatically change t=
he
-
check
attribute to the best supported value to ensure=
the
- virtual CPU does not change when the domain is migrated to another
- host. The following values can be used:
-
-
-
-
- Since 0.9.10, an optional none
partial
full
mode<=
/code>
- attribute may be used to make it easier to configure a guest CPU t=
o be
- as close to host CPU as possible. Possible values for the
-
mode
attribute are:
-
-
-
-
- Both custom
cpu
element describes the CPU
- that should be presented to the guest. This is the default when =
no
- mode
attribute is specified. This mode makes it so =
that
- a persistent guest will see the same hardware no matter what host
- the guest is booted on.host-model
host-model
mode is essentially a shortcut to
- copying host CPU definition from capabilities XML into domain XM=
L.
- Since the CPU definition is copied just before starting a domain,
- exactly the same XML can be used on different hosts while still
- providing the best guest CPU each host supports. The
- match
attribute can't be used in this mode. Specify=
ing
- CPU model is not supported either, but model
's
- fallback
attribute may still be used. Using the
- feature
element, specific flags may be enabled or
- disabled specifically in addition to the host model. This may be
- used to fine tune features that can be emulated.
- (Since 1.1.1).
- Libvirt does not model every aspect of each CPU so
- the guest CPU will not match the host CPU exactly. On the other
- hand, the ABI provided to the guest is reproducible. During
- migration, complete CPU model definition is transferred to the
- destination host so the migrated guest will see exactly the same=
CPU
- model for the running instance of the guest, even if the destina=
tion
- host contains more capable CPUs or newer kernel; but shutting do=
wn and restarting
- the guest may present different hardware to the guest according =
to
- the capabilities of the new host. Prior to libvirt 3.2.0 and QEMU
- 2.9.0 detection of the host CPU model via QEMU is not supported.
- Thus the CPU configuration created using host-model
- may not work as expected.
- Since 3.2.0 and QEMU 2.9.0 this mode
- works the way it was designed and it is indicated by the
- fallback
attribute set to forbid
in the
- host-model CPU definition advertised in
- domain capabilitie=
s XML.
- When fallback
attribute is set to allow
- in the domain capabilities XML, it is recommended to use
- custom
mode with just the CPU model from the host
- capabilities XML. Since 1.2.11 Powe=
rISA
- allows processors to run VMs in binary compatibility mode suppor=
ting
- an older version of ISA. Libvirt on PowerPC architecture uses t=
he
- host-model
to signify a guest mode CPU running in
- binary compatibility mode. Example:
- When a user needs a power7 VM to run in compatibility mode
- on a Power8 host, this can be described in XML as follows :
-
-<cpu mode=3D'host-model'>
- <model>power7</model>
-</cpu>
-...
- host-passthrough
feature
elements. Migration of a g=
uest
- using host-passthrough is dangerous if the source and destinatio=
n hosts
- are not identical in both hardware, QEMU version, microcode vers=
ion
- and configuration. If such a migration is attempted then the gue=
st may
- hang or crash upon resuming execution on the destination host.
- Depending on hypervisor version the virtual CPU may or may not
- contain features which may block migration even to an identical =
host.
- Since 6.5.0 optional
- migratable
attribute may be used to explicitly requ=
est
- such features to be removed from (on
) or kept in
- (off
) the virtual CPU. This attribute does not make
- migration to another host safer: even with
- migratable=3D'on'
migration will be dangerous unles=
s both
- hosts are identical as described above.
- host-model
and host-passthrough
mod=
es
- make sense when a domain can run directly on the host CPUs (for
- example, domains with type kvm
). The actual host CPU =
is
- irrelevant for domains with emulated virtual CPUs (such as domains=
with
- type qemu
). However, for backward compatibility
- host-model
may be implemented even for domains runnin=
g on
- emulated CPUs in which case the best CPU the hypervisor is able to
- emulate may be used rather then trying to mimic the host CPU model.
- model
model
element specifies CPU model
- requested by the guest. The list of available CPU models and their
- definition can be found in cpu_map.xml
file installed
- in libvirt's data directory. If a hypervisor is not able to use the
- exact CPU model, libvirt automatically falls back to a closest mod=
el
- supported by the hypervisor while maintaining the list of CPU
- features. Since 0.9.10, an optional
- fallback
attribute can be used to forbid this behavio=
r,
- in which case an attempt to start a domain requesting an unsupport=
ed
- CPU model will fail. Supported values for fallback
- attribute are: allow
(this is the default), and
- forbid
. The optional vendor_id
attribute
- (Since 0.10.0) can be used to set the
- vendor id seen by the guest. It must be exactly 12 characters long.
- If not set the vendor id of the host is used. Typical possible
- values are "AuthenticAMD" and "GenuineIntel".vendor
vendor
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 cpu_map.xml
.topology
topology
element specifies requested topology of
- virtual CPU provided to the guest. Four attributes, sockets<=
/code>,
-
dies
, cores
, and threads
,
- accept non-zero positive integer values. They refer to the number =
of
- CPU sockets per NUMA node, number of dies per socket, number of co=
res
- per die, and number of threads per core, respectively. The d=
ies
- attribute is optional and will default to 1 if omitted, while the =
other
- attributes are all mandatory. Hypervisors may require that the max=
imum
- number of vCPUs specified by the cpus
element equals =
to
- the number of vcpus resulting from the topology.feature
cpu
element can contain zero or more
- elements
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 feature
- element depends on its
policy
attribute, which has to=
be
- set to one of the following values:
-
-
-
-
- Since 0.8.5 the force
require
optional
disable
forbid
policy
- attribute can be omitted and will default to require
.
-
- name
attribute. For example, to explicitly specify
- the 'pcid' feature with Intel IvyBridge CPU model:
-
-...
-<cpu match=3D'exact'>
- <model fallback=3D'forbid'>IvyBridge</model>
- <vendor>Intel</vendor>
- <feature policy=3D'require' name=3D'pcid'/>
-</cpu>
-...
-
- cache
cache
- element describes the virtual CPU cache. If the element is missing,
- the hypervisor will use a sensible default.
-
-
-
- level
cache
elements w=
ith
- the level
attribute set and those without the
- attribute is forbidden.mode
-
- emulate
passthrough
disable
level
attrib=
ute
- is missing).numa
ele=
ment.
- Since 0.9.8
-
-...
-<cpu>
- ...
- <numa>
- <cell id=3D'0' cpus=3D'0-3' memory=3D'512000' unit=3D'KiB' discard=
=3D'yes'/>
- <cell id=3D'1' cpus=3D'4-7' memory=3D'512000' unit=3D'KiB' memAcces=
s=3D'shared'/>
- </numa>
- ...
-</cpu>
-...
-
- cell
element specifies a NUMA cell or a NUMA node.
- cpus
specifies the CPU or range of CPUs that are
- part of the node. Since 6.5.0 For the q=
emu
- driver, if the emulator binary supports disjointed cpus
=
ranges
- in each cell
, the sum of all CPUs declared in each vcpu
element. This is done by filling any remaining CPUs
- into the first NUMA cell
. Users are encouraged to suppl=
y a
- complete NUMA topology, where the sum of the NUMA CPUs matches the m=
aximum
- virtual CPUs number declared in vcpus
, to make the doma=
in
- consistent across qemu and libvirt versions.
- memory
specifies the node memory
- in kibibytes (i.e. blocks of 1024 bytes).
- Since 6.6.0 the cpus
attri=
bute
- is optional and if omitted a CPU-less NUMA node is created.
- Since 1.2.11 one can use an additional =
unit
attribu=
te to
- define units in which memory
is specified.
- Since 1.2.7 all cells should
- have id
attribute in case referring to some cell is
- necessary in the code, otherwise the cells are
- assigned id
s in the increasing order starting from
- 0. Mixing cells with and without the id
attribute
- is not recommended as it may result in unwanted behaviour.
-
- Since 1.2.9 the optional attribute
- memAccess
can control whether the memory is to be
- mapped as "shared" or "private". This is valid only for
- hugepages-backed memory and nvdimm modules.
-
- Each cell
element can have an optional
- discard
attribute which fine tunes the discard
- feature for given numa node as described under
- Memory Backing.
- Accepted values are yes
and no
.
- Since 4.4.0
-
- This guest NUMA specification is currently available only for - QEMU/KVM and Xen. -
- -
- A NUMA hardware architecture supports the notion of distances
- between NUMA cells. Since 3.10.0 it
- is possible to define the distance between NUMA cells using the
- distances
element within a NUMA cell
- description. The sibling
sub-element is used to
- specify the distance value between sibling NUMA cells. For more
- details, see the chapter explaining the system's SLIT (System
- Locality Information Table) within the ACPI (Advanced
- Configuration and Power Interface) specification.
-
-... -<cpu> - ... - <numa> - <cell id=3D'0' cpus=3D'0,4-7' memory=3D'512000' unit=3D'KiB'> - <distances> - <sibling id=3D'0' value=3D'10'/> - <sibling id=3D'1' value=3D'21'/> - <sibling id=3D'2' value=3D'31'/> - <sibling id=3D'3' value=3D'41'/> - </distances> - </cell> - <cell id=3D'1' cpus=3D'1,8-10,12-15' memory=3D'512000' unit=3D'KiB'= memAccess=3D'shared'> - <distances> - <sibling id=3D'0' value=3D'21'/> - <sibling id=3D'1' value=3D'10'/> - <sibling id=3D'2' value=3D'21'/> - <sibling id=3D'3' value=3D'31'/> - </distances> - </cell> - <cell id=3D'2' cpus=3D'2,11' memory=3D'512000' unit=3D'KiB' memAcce= ss=3D'shared'> - <distances> - <sibling id=3D'0' value=3D'31'/> - <sibling id=3D'1' value=3D'21'/> - <sibling id=3D'2' value=3D'10'/> - <sibling id=3D'3' value=3D'21'/> - </distances> - </cell> - <cell id=3D'3' cpus=3D'3' memory=3D'512000' unit=3D'KiB'> - <distances> - <sibling id=3D'0' value=3D'41'/> - <sibling id=3D'1' value=3D'31'/> - <sibling id=3D'2' value=3D'21'/> - <sibling id=3D'3' value=3D'10'/> - </distances> - </cell> - </numa> - ... -</cpu> -...- -
- Describing distances between NUMA cells is currently only supported
- by Xen and QEMU. If no distances
are given to describe
- the SLIT data between different cells, it will default to a scheme
- using 10 for local and 20 for remote distances.
-
-... -<cpu> - ... - <numa> - <cell id=3D'0' cpus=3D'0-3' memory=3D'512000' unit=3D'KiB' discard= =3D'yes'/> - <cell id=3D'1' cpus=3D'4-7' memory=3D'512000' unit=3D'KiB' memAcces= s=3D'shared'/> - <cell id=3D'3' cpus=3D'0-3' memory=3D'2097152' unit=3D'KiB'> - <cache level=3D'1' associativity=3D'direct' policy=3D'writeback'&= gt; - <size value=3D'10' unit=3D'KiB'/> - <line value=3D'8' unit=3D'B'/> - </cache> - </cell> - <interconnects> - <latency initiator=3D'0' target=3D'0' type=3D'access' value=3D'5'= /> - <latency initiator=3D'0' target=3D'0' cache=3D'1' type=3D'access'= value=3D'10'/> - <bandwidth initiator=3D'0' target=3D'0' type=3D'access' value=3D'= 204800' unit=3D'KiB'/> - </interconnects> - </numa> - ... -</cpu> -...- -
- Since 6.6.0 the cell
eleme=
nt can
- have a cache
child element which describes memory side =
cache
- for memory proximity domains. The cache
element has a
- level
attribute describing the cache level and thus the
- element can be repeated multiple times to describe different levels =
of
- the cache.
-
- The cache
element then has following mandatory attribut=
es:
-
level
associativity
none,
- direct
and full
).
-
policy
none
, writeback
and
- writethrough
).
-
- The cache
element has two mandatory child elements then:
- size
and line
which describe cache size and
- cache line size. Both elements accept two attributes: value
- and
unit
which set the value of corresponding cache
- attribute.
-
- The NUMA description has an optional interconnects
elem=
ent that
- describes the normalized memory read/write latency, read/write bandw=
idth
- between Initiator Proximity Domains (Processor or I/O) and Target
- Proximity Domains (Memory).
-
- The interconnects
element can have zero or more
- latency
child elements to describe latency between two
- memory nodes and zero or more bandwidth
child elements =
to
- describe bandwidth between two memory nodes. Both these have the
- following mandatory attributes:
-
initiator
target
type
access
,
- read
, write
value
unit
attribute to change the units.
- To describe latency from one NUMA node to a cache of another NUMA no=
de
- the latency
element has optional cache
- attribute which in combination with target
attribute cr=
eates
- full reference to distant NUMA node's cache level. For instance,
- target=3D'0' cache=3D'1'
refers to the first level cach=
e of NUMA
- node 0.
-
- It is sometimes necessary to override the default actions taken
- on various events. Not all hypervisors support all events and action=
s.
- The actions may be taken as a result of calls to libvirt APIs
-
- virDomainReboot
- ,
-
- virDomainShutdown
- ,
- or
-
- virDomainShutdownFlags
- .
- Using virsh reboot
or virsh shutdown
would
- also trigger the event.
-
-... -<on_poweroff>destroy</on_poweroff> -<on_reboot>restart</on_reboot> -<on_crash>restart</on_crash> -<on_lockfailure>poweroff</on_lockfailure> -...- -
- The following collections of elements allow the actions to be - specified when a guest OS triggers a lifecycle operation. A - common use case is to force a reboot to be treated as a poweroff - when doing the initial OS installation. This allows the VM to be - re-configured for the first post-install bootup. -
-on_poweroff
on_reboot
on_crash
- Each of these states allow for the same four possible actions. -
- -destroy
restart
preserve
rename-restart
- QEMU/KVM supports the on_poweroff
and on_reboot
- events handling the
destroy
and restart
acti=
ons.
- The preserve
action for an on_reboot
event
- is treated as a destroy
and the rename-restart
- action for an
on_poweroff
event is treated as a
- restart
event.
-
- The on_crash
event supports these additional
- actions since 0.8.4.
-
coredump-destroy
coredump-restart
- Since 3.9.0, the lifecycle events can
- be configured via the
-
- virDomainSetLifecycleAction
API.
-
- The on_lockfailure
element (since
- 1.0.0) may be used to configure what action should be
- taken when a lock manager loses resource locks. The following
- actions are recognized by libvirt, although not all of them need
- to be supported by individual lock managers. When no action is
- specified, each lock manager will take its default action.
-
poweroff
restart
pause
ignore
- Since 0.10.2 it is possible to - forcibly enable or disable BIOS advertisements to the guest - OS. (NB: Only qemu driver support) -
- --... -<pm> - <suspend-to-disk enabled=3D'no'/> - <suspend-to-mem enabled=3D'yes'/> -</pm> -...- -
pm
- Hypervisors may allow certain CPU / machine features to be - toggled on/off. -
- --... -<features> - <pae/> - <acpi/> - <apic/> - <hap/> - <privnet/> - <hyperv> - <relaxed state=3D'on'/> - <vapic state=3D'on'/> - <spinlocks state=3D'on' retries=3D'4096'/> - <vpindex state=3D'on'/> - <runtime state=3D'on'/> - <synic state=3D'on'/> - <stimer state=3D'on'> - <direct state=3D'on'/> - </stimer> - <reset state=3D'on'/> - <vendor_id state=3D'on' value=3D'KVM Hv'/> - <frequencies state=3D'on'/> - <reenlightenment state=3D'on'/> - <tlbflush state=3D'on'/> - <ipi state=3D'on'/> - <evmcs state=3D'on'/> - </hyperv> - <kvm> - <hidden state=3D'on'/> - <hint-dedicated state=3D'on'/> - </kvm> - <xen> - <e820_host state=3D'on'/> - <passthrough state=3D'on' mode=3D'share_pt'/> - </xen> - <pvspinlock state=3D'on'/> - <gic version=3D'2'/> - <ioapic driver=3D'qemu'/> - <hpt resizing=3D'required'> - <maxpagesize unit=3D'MiB'>16</maxpagesize> - </hpt> - <vmcoreinfo state=3D'on'/> - <smm state=3D'on'> - <tseg unit=3D'MiB'>48</tseg> - </smm> - <htm state=3D'on'/> - <ccf-assist state=3D'on'/> - <msrs unknown=3D'ignore'/> - <cfpc value=3D'workaround'/> - <sbbc value=3D'workaround'/> - <ibs value=3D'fixed-na'/> -</features> -...- -
- All features are listed within the features
- element, omitting a togglable feature tag turns it off.
- The available features can be found by asking
- for the capabilities XML and
- domain capabilities XML,
- but a common set for fully virtualized domains are:
-
pae
acpi
apic
eoi
with values on
- and off
which toggles the availability of EOI (End of
- Interrupt) for the guest.
- hap
state
attribute (values on=
code>,
- off
) enable or disable use of Hardware Assisted Pagin=
g.
- The default is on
if the hypervisor detects availabil=
ity
- of Hardware Assisted Paging.
-
viridian
privnet
hyperv
Feature | -Description | -Value | -Since | -
---|---|---|---|
relaxed | -Relax constraints on timers | -on, off | -1.0.0 (QEMU 2.0) | -
vapic | -Enable virtual APIC | -on, off | -1.1.0 (QEMU 2.0) | -
spinlocks | -Enable spinlock support | -on, off; retries - at least 4095 | -1.1.0 (QEMU 2.0) | -
vpindex | -Virtual processor index | -on, off | -1.3.3 (QEMU 2.5) | -
runtime | -Processor time spent on running guest code and on behalf of = guest code | -on, off | -1.3.3 (QEMU 2.5) | -
synic | -Enable Synthetic Interrupt Controller (SynIC) | -on, off | -1.3.3 (QEMU 2.6) | -
stimer | -Enable SynIC timers, optionally with Direct Mode support | -on, off; direct - on,off | -1.3.3 (QEMU 2.6), direct mode 5.7.0 (Q= EMU 4.1) | -
reset | -Enable hypervisor reset | -on, off | -1.3.3 (QEMU 2.5) | -
vendor_id | -Set hypervisor vendor id | -on, off; value - string, up to 12 characters | -1.3.3 (QEMU 2.5) | -
frequencies | -Expose frequency MSRs | -on, off | -4.7.0 (QEMU 2.12) | -
reenlightenment | -Enable re-enlightenment notification on migration | -on, off | -4.7.0 (QEMU 3.0) | -
tlbflush | -Enable PV TLB flush support | -on, off | -4.7.0 (QEMU 3.0) | -
ipi | -Enable PV IPI support | -on, off | -4.10.0 (QEMU 3.1) | -
evmcs | -Enable Enlightened VMCS | -on, off | -4.10.0 (QEMU 3.1) | -
pvspinlock
state=3D'off'
- attribute.
- kvm
Feature | -Description | -Value | -Since | -
---|---|---|---|
hidden | -Hide the KVM hypervisor from standard MSR based discovery - | on, off | -1.2.8 (QEMU 2.1.0) | -
hint-dedicated | -Allows a guest to enable optimizations when running on dedic= ated vCPUs | -on, off | -5.7.0 (QEMU 2.12.0) | -
xen
Feature | -Description | -Value | -Since | -
---|---|---|---|
e820_host | -Expose the host e820 to the guest (PV only) | -on, off | -6.3.0 | -
passthrough | -Enable IOMMU mappings allowing PCI passthrough | -on, off; mode - optional string sync_pt or share_pt | -6.3.0 | -
pmu
state
attribute (values on=
code>,
- off
, default on
) enable or disable the
- performance monitoring unit for the guest.
- Since 1.2.12
-
vmport
state
attribute (values on=
code>,
- off
, default on
) enable or disable
- the emulation of VMware IO port, for vmmouse etc.
- Since 1.2.16
-
gic
gic
instead of apic
. The optional
- attribute version
specifies the GIC version;
- however, it may not be supported by all hypervisors. Accepted
- values are 2
, 3
and host
.
- Since 1.2.16
- smm
- Depending on the state
attribute (values on=
code>,
-
off
, default on
) enable or disable
- System Management Mode.
- Since 2.1.0
-
Optional sub-element tseg
can be used to spec=
ify
- the amount of memory dedicated to SMM's extended TSEG. That offe=
rs a
- fourth option size apart from the existing ones (1 MiB, 2 MiB an=
d 8
- MiB) that the guest OS (or rather loader) can choose from. The s=
ize
- can be specified as a value of that element, optional attribute
- unit
can be used to specify the unit of the
- aforementioned value (defaults to 'MiB'). If set to 0 the exten=
ded
- size is not advertised and only the default ones (see above) are
- available.
-
- If the VM is booting you should leave this option alone, unle= ss you - are very certain you know what you are doing. -
- This value is configurable due to the fact that the calculation =
cannot
- be done right with the guarantee that it will work correctly. In
- QEMU, the user-configurable extended TSEG feature was unavailabl=
e up
- to and including pc-q35-2.9
. Starting with
- pc-q35-2.10
the feature is available, with default =
size
- 16 MiB. That should suffice for up to roughly 272 vCPUs, 5 GiB =
guest
- RAM in total, no hotplug memory range, and 32 GiB of 64-bit PCI =
MMIO
- aperture. Or for 48 vCPUs, with 1TB of guest RAM, no hotplug DI=
MM
- range, and 32GB of 64-bit PCI MMIO aperture. The values may also=
vary
- based on the loader the VM is using.
-
- Additional size might be needed for significantly higher vCPU co= unts - or increased address space (that can be memory, maxMemory, 64-bi= t PCI - MMIO aperture size; roughly 8 MiB of TSEG per 1 TiB of address s= pace) - which can also be rounded up. -
- Due to the nature of this setting being similar to "how much RAM - should the guest have" users are advised to either consult the - documentation of the guest OS or loader (if there is any), or te= st - this by trial-and-error changing the value until the VM boots - successfully. Yet another guiding value for users might be the = fact - that 48 MiB should be enough for pretty large guests (240 vCPUs = and - 4TB guest RAM), but it is on purpose not set as default as 48 Mi= B of - unavailable RAM might be too much for small guests (e.g. with 51= 2 MiB - of RAM). -
- See Memory Allocation
- for more details about the unit
attribute.
- Since 4.5.0 (QEMU only)
-
ioapic
driver
attribute are:
- kvm
(default for KVM domains)
- and qemu
which puts I/O APIC in userspace
- which is also known as a split I/O APIC mode.
- Since 3.4.0 (QEMU/KVM only)
- hpt
resizing
attribute are
- enabled
, which causes HPT resizing to be enabled if
- both the guest and the host support it; disabled
, w=
hich
- causes HPT resizing to be disabled regardless of guest and host
- support; and required
, which prevents the guest from
- starting unless both the guest and the host support HPT resizing=
. If
- the attribute is not defined, the hypervisor default will be use=
d.
- Since 3.10.0 (QEMU/KVM only).
-
- The optional maxpagesize
subelement can be used =
to
- limit the usable page size for HPT guests. Common values are 64 =
KiB,
- 16 MiB and 16 GiB; when not specified, the hypervisor default wi=
ll
- be used. Since 4.5.0 (QEMU/KVM only=
).
vmcoreinfo
htm
state
attri=
bute
- are on
and off
. If the attribute is not
- defined, the hypervisor default will be used.
- Since 4.6.0 (QEMU/KVM only)
- nested-hv
state
attribute are
- on
and off
. If the attribute is not
- defined, the hypervisor default will be used.
- Since 4.10.0 (QEMU/KVM only)
- msrs
unknown
attribute
- of msrs
to ignore
. If the attribute is
- not defined, or set to fault
, unknown reads and wri=
tes
- will not be ignored.
- Since 5.1.0 (bhyve only)
- ccf-assist
state
attribute
- are on
and off
. If the attribute is not
- defined, the hypervisor default will be used.
- Since 5.9.0 (QEMU/KVM only)
- cfpc
value
attribute
- are broken
(no protection), workaround
- (software workaround available) and fixed
(fixed in
- hardware). If the attribute is not defined, the hypervisor
- default will be used.
- Since 6.3.0 (QEMU/KVM only)
- sbbc
value
attribute
- are broken
(no protection), workaround
- (software workaround available) and fixed
(fixed in
- hardware). If the attribute is not defined, the hypervisor
- default will be used.
- Since 6.3.0 (QEMU/KVM only)
- ibs
value
attribute
- are broken
(no protection), workaround
- (count cache flush), fixed-ibs
(fixed by
- serializing indirect branches), fixed-ccd
(fixed by
- disabling the cache count) and fixed-na (fixed in
- hardware - no longer applicable)
.
- If the attribute is not defined, the hypervisor
- default will be used.
- Since 6.3.0 (QEMU/KVM only)
- - 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'. -
- --... -<clock offset=3D'localtime'> - <timer name=3D'rtc' tickpolicy=3D'catchup' track=3D'guest'> - <catchup threshold=3D'123' slew=3D'120' limit=3D'10000'/> - </timer> - <timer name=3D'pit' tickpolicy=3D'delay'/> -</clock> -...- -
clock
The offset
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.
utc
adjustment
attribute. If the value is 'reset', the
- conversion is never done (not all hypervisors can
- synchronize to UTC on each boot; use of 'reset' will cause
- an error on those hypervisors). A numeric value
- forces the conversion to 'variable' mode using the value as the
- initial adjustment. The default adjustment
is
- hypervisor specific.
- localtime
adjustmen=
t
- attribute behaves the same as in 'utc' mode.
- timezone
timezone
attribute.
- Since 0.7.7
- variable
basis
- attribute. The delta relative to UTC (or localtime) is specifi=
ed
- in seconds, using the adjustment
attribute.
- The guest is free to adjust the RTC over time and expect
- that it will be honored at next reboot. This is in
- contrast to 'utc' and 'localtime' mode (with the optional
- attribute adjustment=3D'reset'), where the RTC adjustments are
- lost at each reboot. Since 0.7.7
- Since 0.9.11 the basis
- attribute can be either 'utc' (default) or 'localtime'.
-
- A clock
may have zero or more
- timer
sub-elements. Since
- 0.8.0
-
timer
- Each timer element requires a name
attribute,
- and has other optional attributes that depend on
- the name
specified. Various hypervisors
- support different combinations of attributes.
-
name
name
attribute selects which timer is
- being modified, and can be one of
- "platform" (currently unsupported),
- "hpet" (xen, qemu, lxc), "kvmclock" (qemu),
- "pit" (qemu), "rtc" (qemu, lxc), "tsc" (xen, qemu -
- since 3.2.0), "hypervclock"
- (qemu - since 1.2.2) or
- "armvtimer" (qemu - since 6.1.0).
-
- The hypervclock
timer adds support for the
- reference time counter and the reference page for iTSC
- feature for guests running the Microsoft Windows
- operating system.
- track
track
attribute specifies what the timer
- tracks, and can be "boot", "guest", or "wall".
- Only valid for name=3D"rtc"
- or name=3D"platform"
.
- tickpolicy
- The tickpolicy
attribute determines what
- happens when QEMU misses a deadline for injecting a
- tick to the guest. This can happen, for example, because the
- guest was paused.
-
delay
catchup
merge
discard
If the policy is "catchup", there can be further details in
- the catchup
sub-element.
catchup
catchup
element has three optional
- attributes, each a positive integer. The attributes
- are threshold
, slew
,
- and limit
.
- - Note that hypervisors are not required to support all polici= es across all time sources -
-frequency
frequency
attribute is an unsigned
- integer specifying the frequency at
- which name=3D"tsc"
runs.
- mode
mode
attribute controls how
- the name=3D"tsc"
timer is managed, and can be
- "auto", "native", "emulate", "paravirt", or "smpsafe".
- Other timers are always emulated.
- present
present
attribute can be "yes" or "no" to
- specify whether a particular timer is available to the guest.
-
- Some platforms allow monitoring of performance of the virtual machin=
e and
- the code executed inside. To enable the performance monitoring events
- you can either specify them in the perf
element or enab=
le
- them via virDomainSetPerfEvents
API. The performance va=
lues
- are then retrieved using the virConnectGetAllDomainStats API.
- Since 2.0.0
-
-... -<perf> - <event name=3D'cmt' enabled=3D'yes'/> - <event name=3D'mbmt' enabled=3D'no'/> - <event name=3D'mbml' enabled=3D'yes'/> - <event name=3D'cpu_cycles' enabled=3D'no'/> - <event name=3D'instructions' enabled=3D'yes'/> - <event name=3D'cache_references' enabled=3D'no'/> - <event name=3D'cache_misses' enabled=3D'no'/> - <event name=3D'branch_instructions' enabled=3D'no'/> - <event name=3D'branch_misses' enabled=3D'no'/> - <event name=3D'bus_cycles' enabled=3D'no'/> - <event name=3D'stalled_cycles_frontend' enabled=3D'no'/> - <event name=3D'stalled_cycles_backend' enabled=3D'no'/> - <event name=3D'ref_cpu_cycles' enabled=3D'no'/> - <event name=3D'cpu_clock' enabled=3D'no'/> - <event name=3D'task_clock' enabled=3D'no'/> - <event name=3D'page_faults' enabled=3D'no'/> - <event name=3D'context_switches' enabled=3D'no'/> - <event name=3D'cpu_migrations' enabled=3D'no'/> - <event name=3D'page_faults_min' enabled=3D'no'/> - <event name=3D'page_faults_maj' enabled=3D'no'/> - <event name=3D'alignment_faults' enabled=3D'no'/> - <event name=3D'emulation_faults' enabled=3D'no'/> -</perf> -... -- -
event name | -Description | -stats parameter name | -
---|---|---|
cmt |
- usage of l3 cache in bytes by applications running on the platfo= rm | -perf.cmt |
-
mbmt |
- total system bandwidth from one level of cache | -perf.mbmt |
-
mbml |
- bandwidth of memory traffic for a memory controller | -perf.mbml |
-
cpu_cycles |
- the count of CPU cycles (total/elapsed) | -perf.cpu_cycles |
-
instructions |
- the count of instructions by applications running on the platfor= m | -perf.instructions |
-
cache_references |
- the count of cache hits by applications running on the platform<= /td> - | perf.cache_references |
-
cache_misses |
- the count of cache misses by applications running on the platfor= m | -perf.cache_misses |
-
branch_instructions |
- the count of branch instructions by applications running on the = platform | -perf.branch_instructions |
-
branch_misses |
- the count of branch misses by applications running on the platfo= rm | -perf.branch_misses |
-
bus_cycles |
- the count of bus cycles by applications running on the platform<= /td> - | perf.bus_cycles |
-
stalled_cycles_frontend |
- the count of stalled CPU cycles in the frontend of the instructi= on - processor pipeline by applications running on the platform | -perf.stalled_cycles_frontend |
-
stalled_cycles_backend |
- the count of stalled CPU cycles in the backend of the instruction - processor pipeline by applications running on the platform | -perf.stalled_cycles_backend |
-
ref_cpu_cycles |
- the count of total CPU cycles not affected by CPU frequency scal= ing - by applications running on the platform | -perf.ref_cpu_cycles |
-
cpu_clock |
- the count of CPU clock time, as measured by a monotonic - high-resolution per-CPU timer, by applications running on - the platform | -perf.cpu_clock |
-
task_clock |
- the count of task clock time, as measured by a monotonic - high-resolution CPU timer, specific to the task that - is run by applications running on the platform | -perf.task_clock |
-
page_faults |
- the count of page faults by applications running on the - platform. This includes minor, major, invalid and other - types of page faults | -perf.page_faults |
-
context_switches |
- the count of context switches by applications running on - the platform | -perf.context_switches |
-
cpu_migrations |
- the count of CPU migrations, that is, where the process - moved from one logical processor to another, by - applications running on the platform | -perf.cpu_migrations |
-
page_faults_min |
- the count of minor page faults, that is, where the - page was present in the page cache, and therefore - the fault avoided loading it from storage, by - applications running on the platform | -perf.page_faults_min |
-
page_faults_maj |
- the count of major page faults, that is, where the - page was not present in the page cache, and - therefore had to be fetched from storage, by - applications running on the platform | -perf.page_faults_maj |
-
alignment_faults |
- the count of alignment faults, that is when - the load or store is not aligned properly, by - applications running on the platform | -perf.alignment_faults |
-
emulation_faults |
- the count of emulation faults, that is when - the kernel traps on unimplemented instrucions - and emulates them for user space, by - applications running on the platform | -perf.emulation_faults |
-
- 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 devices
element.
- Since 0.1.3
-
-... -<devices> - <emulator>/usr/lib/xen/bin/qemu-dm</emulator> -</devices> -...- -
emulator
emulator
element specify
- the fully qualified path to the device model emulator binary.
- The capabilities XML specifies
- the recommended default emulator to use for each particular
- domain type / architecture combination.
-
- To help users identifying devices they care about, every
- device can have direct child alias
element
- which then has name
attribute where users can
- store identifier for the device. The identifier has to have
- "ua-" prefix and must be unique within the domain. Additionally, the
- identifier must consist only of the following characters:
- [a-zA-Z0-9_-]
.
- Since 3.9.0
-
-<devices> - <disk type=3D'file'> - <alias name=3D'ua-myDisk'/> - </disk> - <interface type=3D'network' trustGuestRxFilters=3D'yes'> - <alias name=3D'ua-myNIC'/> - </interface> - ... -</devices> -- -
- Any device that looks like a disk, be it a floppy, harddisk,
- cdrom, or paravirtualized driver is specified via the disk
- element.
-
-... -<devices> - <disk type=3D'file' snapshot=3D'external'> - <driver name=3D"tap" type=3D"aio" cache=3D"default"/> - <source file=3D'/var/lib/xen/images/fv0' startupPolicy=3D'optional'= > - <seclabel relabel=3D'no'/> - </source> - <target dev=3D'hda' bus=3D'ide'/> - <iotune> - <total_bytes_sec>10000000</total_bytes_sec> - <read_iops_sec>400000</read_iops_sec> - <write_iops_sec>100000</write_iops_sec> - </iotune> - <boot order=3D'2'/> - <encryption type=3D'...'> - ... - </encryption> - <shareable/> - <serial> - ... - </serial> - </disk> - ... - <disk type=3D'network'> - <driver name=3D"qemu" type=3D"raw" io=3D"threads" ioeventfd=3D"on" = event_idx=3D"off"/> - <source protocol=3D"sheepdog" name=3D"image_name"> - <host name=3D"hostname" port=3D"7000"/> - </source> - <target dev=3D"hdb" bus=3D"ide"/> - <boot order=3D'1'/> - <transient/> - <address type=3D'drive' controller=3D'0' bus=3D'1' unit=3D'0'/> - </disk> - <disk type=3D'network'> - <driver name=3D"qemu" type=3D"raw"/> - <source protocol=3D"rbd" name=3D"image_name2"> - <host name=3D"hostname" port=3D"7000"/> - <snapshot name=3D"snapname"/> - <config file=3D"/path/to/file"/> - <auth username=3D'myuser'> - <secret type=3D'ceph' usage=3D'mypassid'/> - </auth> - </source> - <target dev=3D"hdc" bus=3D"ide"/> - </disk> - <disk type=3D'block' device=3D'cdrom'> - <driver name=3D'qemu' type=3D'raw'/> - <target dev=3D'hdd' bus=3D'ide' tray=3D'open'/> - <readonly/> - </disk> - <disk type=3D'network' device=3D'cdrom'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D"http" name=3D"url_path" query=3D"foo=3Dbar&= amp;baz=3Dflurb> - <host name=3D"hostname" port=3D"80"/> - <cookies> - <cookie name=3D"test">somevalue</cookie> - </cookies> - <readahead size=3D'65536'/> - <timeout seconds=3D'6'/> - </source> - <target dev=3D'hde' bus=3D'ide' tray=3D'open'/> - <readonly/> - </disk> - <disk type=3D'network' device=3D'cdrom'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D"https" name=3D"url_path"> - <host name=3D"hostname" port=3D"443"/> - <ssl verify=3D"no"/> - </source> - <target dev=3D'hdf' bus=3D'ide' tray=3D'open'/> - <readonly/> - </disk> - <disk type=3D'network' device=3D'cdrom'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D"ftp" name=3D"url_path"> - <host name=3D"hostname" port=3D"21"/> - </source> - <target dev=3D'hdg' bus=3D'ide' tray=3D'open'/> - <readonly/> - </disk> - <disk type=3D'network' device=3D'cdrom'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D"ftps" name=3D"url_path"> - <host name=3D"hostname" port=3D"990"/> - </source> - <target dev=3D'hdh' bus=3D'ide' tray=3D'open'/> - <readonly/> - </disk> - <disk type=3D'network' device=3D'cdrom'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D"tftp" name=3D"url_path"> - <host name=3D"hostname" port=3D"69"/> - </source> - <target dev=3D'hdi' bus=3D'ide' tray=3D'open'/> - <readonly/> - </disk> - <disk type=3D'block' device=3D'lun'> - <driver name=3D'qemu' type=3D'raw'/> - <source dev=3D'/dev/sda'> - <slices> - <slice type=3D'storage' offset=3D'12345' size=3D'123'/> - </slices> - <reservations managed=3D'no'> - <source type=3D'unix' path=3D'/path/to/qemu-pr-helper' mode=3D'= client'/> - </reservations> - </source> - <target dev=3D'sda' bus=3D'scsi'/> - <address type=3D'drive' controller=3D'0' bus=3D'0' target=3D'3' uni= t=3D'0'/> - </disk> - <disk type=3D'block' device=3D'disk'> - <driver name=3D'qemu' type=3D'raw'/> - <source dev=3D'/dev/sda'/> - <geometry cyls=3D'16383' heads=3D'16' secs=3D'63' trans=3D'lba'/> - <blockio logical_block_size=3D'512' physical_block_size=3D'4096'/&g= t; - <target dev=3D'hdj' bus=3D'ide'/> - </disk> - <disk type=3D'volume' device=3D'disk'> - <driver name=3D'qemu' type=3D'raw'/> - <source pool=3D'blk-pool0' volume=3D'blk-pool0-vol0'/> - <target dev=3D'hdk' bus=3D'ide'/> - </disk> - <disk type=3D'network' device=3D'disk'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D'iscsi' name=3D'iqn.2013-07.com.example:iscsi-no= pool/2'> - <host name=3D'example.com' port=3D'3260'/> - <auth username=3D'myuser'> - <secret type=3D'iscsi' usage=3D'libvirtiscsi'/> - </auth> - </source> - <target dev=3D'vda' bus=3D'virtio'/> - </disk> - <disk type=3D'network' device=3D'lun'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D'iscsi' name=3D'iqn.2013-07.com.example:iscsi-no= pool/1'> - <host name=3D'example.com' port=3D'3260'/> - <auth username=3D'myuser'> - <secret type=3D'iscsi' usage=3D'libvirtiscsi'/> - </auth> - </source> - <target dev=3D'sdb' bus=3D'scsi'/> - </disk> - <disk type=3D'network' device=3D'lun'> - <driver name=3D'qemu' type=3D'raw'/> - <source protocol=3D'iscsi' name=3D'iqn.2013-07.com.example:iscsi-no= pool/0'> - <host name=3D'example.com' port=3D'3260'/> - <initiator> - <iqn name=3D'iqn.2013-07.com.example:client'/> - </initiator> - </source> - <target dev=3D'sdb' bus=3D'scsi'/> - </disk> - <disk type=3D'volume' device=3D'disk'> - <driver name=3D'qemu' type=3D'raw'/> - <source pool=3D'iscsi-pool' volume=3D'unit:0:0:1' mode=3D'host'/> - <target dev=3D'vdb' bus=3D'virtio'/> - </disk> - <disk type=3D'volume' device=3D'disk'> - <driver name=3D'qemu' type=3D'raw'/> - <source pool=3D'iscsi-pool' volume=3D'unit:0:0:2' mode=3D'direct'/&= gt; - <target dev=3D'vdc' bus=3D'virtio'/> - </disk> - <disk type=3D'file' device=3D'disk'> - <driver name=3D'qemu' type=3D'qcow2' queues=3D'4'/> - <source file=3D'/var/lib/libvirt/images/domain.qcow'/> - <backingStore type=3D'file'> - <format type=3D'qcow2'/> - <source file=3D'/var/lib/libvirt/images/snapshot.qcow'/> - <backingStore type=3D'block'> - <format type=3D'raw'/> - <source dev=3D'/dev/mapper/base'/> - <backingStore/> - </backingStore> - </backingStore> - <target dev=3D'vdd' bus=3D'virtio'/> - </disk> - <disk type=3D'nvme' device=3D'disk'> - <driver name=3D'qemu' type=3D'raw'/> - <source type=3D'pci' managed=3D'yes' namespace=3D'1'> - <address domain=3D'0x0000' bus=3D'0x01' slot=3D'0x00' function=3D= '0x0'/> - </source> - <target dev=3D'vde' bus=3D'virtio'/> - </disk> -</devices> -...- -
disk
disk
element is the main container for
- describing disks and supports the following attributes:
- type
device
- Using "lun" (since 0.9.10) is only
- valid when the type
is "block" or "network" for
- protocol=3D'iscsi'
or when the type
- is "volume" when using an iSCSI source pool
- for mode
"host" or as an
- NPIV<=
/a>
- virtual Host Bus Adapter (vHBA) using a Fibre Channel storage =
pool.
- Configured in this manner, the LUN behaves identically to "dis=
k",
- except that generic SCSI commands from the guest are accepted
- and passed through to the physical device. Also note that
- device=3D'lun' will only be recognized for actual raw devices,
- but never for individual partitions or LVM partitions (in those
- cases, the kernel will reject the generic SCSI commands, making
- it identical to device=3D'disk').
- Since 0.1.4
-
model
bus
property but
- for bus
"virtio" the model can be specified furth=
er
- with "virtio-transitional", "virtio-non-transitional", or
- "virtio". See
- Virtio transitional de=
vices
- for more details.
- Since 5.2.0
- rawio
rawio
int=
ends
- to confine the capability per-device, however, current QEMU
- implementation gives the domain process broader capability
- than that (per-process basis, affects all the domain disks).
- To confine the capability as much as possible for QEMU driver
- as this stage, sgio
is recommended, it's more
- secure than rawio
.
- Since 0.9.10
- sgio
device
is 'lu=
n'.
- Since 1.0.2
- snapshot
internal
" requires a file format such as qcow2 t=
hat
- can store both the snapshot and the data changes since the sna=
pshot;
- "external
" will separate the snapshot from the li=
ve
- data; and "no
" means the disk will not participat=
e in
- snapshots. Read-only disks default to "no
", while=
the
- default for other disks depends on the hypervisor's capabiliti=
es.
- Some hypervisors allow a per-snapshot choice as well, during
- domain snapshot creation.
- Not all snapshot modes are supported; for example, enabling
- snapshots with a transient disk generally does not make sense.
- Since 0.9.5
- source
source
depends on the
- disk type
attribute value as follows:
- file
file
attribute specifies the fully-qualified
- path to the file holding the disk.
- Since 0.0.3
- block
dev
attribute specifies the fully-qualified=
path
- to the host device to serve as the disk.
- Since 0.0.3
- dir
dir
attribute specifies the fully-qualified=
path
- to the directory to use as the disk.
- Since 0.7.5
- network
protocol
attribute specifies the protocol to
- access to the requested image. Possible values are "nbd",
- "iscsi", "rbd", "sheepdog", "gluster", "vxhs", "http", "http=
s",
- "ftp", ftps", or "tftp".
-
- For any protocol
other than nbd
- an additional attribute name
- is mandatory to specify which volume/image will be used.
-
For "nbd", the name
attribute is optional. T=
LS
- transport for NBD can be enabled by setting the tls
- attribute to
yes
. For the QEMU hypervisor, usag=
e of
- a TLS environment can also be globally controlled on the hos=
t by
- the nbd_tls
and nbd_tls_x509_cert_dir in
- /etc/libvirt/qemu.conf.
- ('tls' Since 4.5.0)
-
For protocols http
and https
an
- optional attribute query
specifies the query st=
ring.
- (Since 6.2.0)
-
For "iscsi" (since 1.0.4), t=
he
- name
attribute may include a logical unit numbe=
r,
- separated from the target's name by a slash (e.g.,
- iqn.2013-07.com.example:iscsi-pool/1
). If not
- specified, the default LUN is zero.
-
For "vxhs" (since 3.8.0), the
- name
is the UUID of the volume, assigned by the
- HyperScale server. Additionally, an optional attribute
- tls
(QEMU only) can be used to control whether a
- VxHS block device would utilize a hypervisor configured TLS
- X.509 certificate environment in order to encrypt the data
- channel. For the QEMU hypervisor, usage of a TLS environment=
can
- also be globally controlled on the host by the
- vxhs_tls
and vxhs_tls_x509_cert_dir
or
- default_tls_x509_cert_dir
settings in the file
- /etc/libvirt/qemu.conf. If vxhs_tls
is enabled,
- then unless the domain tls
attribute is set to =
"no",
- libvirt will use the host configured TLS environment. If the
- tls
attribute is set to "yes", then regardless =
of
- the qemu.conf setting, TLS authentication will be attempted.
-
volume
pool
and volume
. Attribute
- pool
specifies the name of the
- storage pool (managed
- by libvirt) where the disk source resides. Attribute
- volume
specifies the name of storage volume (ma=
naged
- by libvirt) used as the disk source. The value for the
- volume
attribute will be the output from the "N=
ame"
- column of a virsh vol-list [pool-name]
command.
-
- Use the attribute mode
- (since 1.1.1) to indicate how to
- represent the LUN as the disk source. Valid values are
- "direct" and "host". If mode
is not specified,
- the default is to use "host".
-
- Using "direct" as the mode
value indicates to u=
se
- the storage pool's
- source
element host
attribute as
- the disk source to generate the libiscsi URI (e.g.
- 'file=3Discsi://example.com:3260/iqn.2013-07.com.example:isc=
si-pool/1').
-
- Using "host" as the mode
value indicates to use=
the
- LUN's path as it shows up on host (e.g.
- 'file=3D/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013=
-07.com.example:iscsi-pool-lun-1').
-
- Using a LUN from an iSCSI source pool provides the same
- features as a disk
configured using
- type
'block' or 'network' and device
- of 'lun' with respect to how the LUN is presented to and
- may be used by the guest.
-
- Since 1.0.5
-
nvme
source
- element has the following attributes:
- type
address
- sub-element. Currently, only pci
value is
- accepted.
- managed
yes)
- or expect the controller to be detached by system
- administrator (no
).
-
namespace
<disk type=3D'nvme'>
- and <hostdev/>
is that the latter is plain
- host device assignment with all its limitations (e.g. no live
- migration), while the former makes hypervisor to run the NVMe
- disk through hypervisor's block layer thus enabling all
- features provided by the layer (e.g. snapshots, domain
- migration, etc.). Moreover, since the NVMe disk is unbinded
- from its PCI driver, the host kernel storage stack is not
- involved (compared to passing say /dev/nvme0n1
=
via
- <disk type=3D'block'>
and therefore lower
- latencies can be achieved.
-
seclabel
, described
- below (and since 0.9.9), can be
- used to override the domain security labeling policy for just
- that source file. (NB, for "volume" type disk, seclabel
- is only valid when the specified storage volume is of 'file' or
- 'block' type).
-
- The source
element may also have the index
- attribute with same semantics the
- index
attribute of backingStore
-
-
- The source
element may contain the following sub elem=
ents:
-
-
-
- host
- -
-
- When the disk type
is "network", the source=
- may have zero or more host
sub-elements used to
- specify the hosts to connect.
-
- The host
element supports 4 attributes, viz. "na=
me",
- "port", "transport" and "socket", which specify the hostname,
- the port number, transport type and path to socket, respective=
ly.
- The meaning of this element and the number of the elements dep=
end
- on the protocol attribute.
-
-
-
- Protocol
- Meaning
- Number of hosts
- Default port
-
-
- nbd
- a server running nbd-server
- only one
- 10809
-
-
- iscsi
- an iSCSI server
- only one
- 3260
-
-
- rbd
- monitor servers of RBD
- one or more
- librados default
-
-
- sheepdog
- one of the sheepdog servers (default is localhost:700=
0)
- zero or one
- 7000
-
-
- gluster
- a server running glusterd daemon
- one or more (Since 2.1.0=
), just one prior to that
- 24007
-
-
- vxhs
- a server running Veritas HyperScale daemon
- only one
- 9999
-
-
-
- gluster supports "tcp", "rdma", "unix" as valid values for the
- transport attribute. nbd supports "tcp" and "unix". Others o=
nly
- support "tcp". If nothing is specified, "tcp" is assumed. If =
the
- transport is "unix", the socket attribute specifies the path t=
o an
- AF_UNIX socket.
-
-
- snapshot
- -
- The
name
attribute of snapshot
eleme=
nt can
- optionally specify an internal snapshot name to be used as the
- source for storage protocols.
- Supported for 'rbd' since 1.2.11 (QEMU o=
nly).
-
- config
- -
- The
file
attribute for the config
el=
ement
- provides a fully qualified path to a configuration file to be
- provided as a parameter to the client of a networked storage
- protocol. Supported for 'rbd' since 1.2.=
11
- (QEMU only).
-
- auth
- - Since libvirt 3.9.0, the
-
auth
element is supported for a disk
- type
"network" that is using a source
- element with the protocol
attributes "rbd" or "is=
csi".
- If present, the auth
element provides the
- authentication credentials needed to access the source. It
- includes a mandatory attribute username
, which
- identifies the username to use during authentication, as well
- as a sub-element secret
with mandatory
- attribute type
, to tie back to
- a libvirt secret object that
- holds the actual password or other credentials (the domain XML
- intentionally does not expose the password, only the reference
- to the object that does manage the password).
- Known secret types are "ceph" for Ceph RBD network sources and
- "iscsi" for CHAP authentication of iSCSI targets.
- Both will require either a uuid
attribute
- with the UUID of the secret object or a usage
- attribute matching the key that was specified in the
- secret object.
-
- encryption
- - Since libvirt 3.9.0, the
-
encryption
can be a sub-element of the
- source
element for encrypted storage sources.
- If present, specifies how the storage source is encrypted
- See the
- Storage Encryption
- page for more information.
-
- Note that the 'qcow' format of encryption is broken and thus i=
s no
- longer supported for use with disk images.
- (Since libvirt 4.5.0)
-
- reservations
- - Since libvirt 4.4.0, the
-
reservations
can be a sub-element of the
- source
element for storage sources (QEMU driver o=
nly).
- If present it enables persistent reservations for SCSI
- based disks. The element has one mandatory attribute
- managed
with accepted values yes
and
- no
. If managed
is enabled libvirt pr=
epares
- and manages any resources needed. When the persistent reservat=
ions
- are unmanaged, then the hypervisor acts as a client and the pa=
th to
- the server socket must be provided in the child element
- source
, which currently accepts only the following
- attributes:
- type
with one value unix
,
- path
path to the socket, and
- finally mode
which accepts one value
- client
specifying the role of hypervisor.
- It's recommended to allow libvirt manage the persistent
- reservations.
-
- initiator
- - Since libvirt 4.7.0, the
-
initiator
element is supported for a disk
- type
"network" that is using a source
- element with the protocol
attribute "iscsi".
- If present, the initiator
element provides the
- initiator IQN needed to access the source via mandatory
- attribute name
.
-
- address
- - For disk of type
nvme
this element
- specifies the PCI address of the host NVMe
- controller.
- Since 6.0.0
-
- slices
- - The
slices
element using its slice
- sub-elements allows configuring offset and size of either the
- location of the image format (slice type=3D'storage')
- inside the storage source or the guest data inside the image f=
ormat
- container (future expansion).
-
- The offset
and size
values are in by=
tes.
- Since 6.1.0
-
- ssl
- -
- For
https
and ftps
accessed storage =
it's
- possible to tweak the SSL transport parameters with this eleme=
nt.
- The verify
attribute allows to turn on or off SSL
- certificate validation. Supported values are yes
=
and
- no
. Since 6.2.0
-
- cookies
- -
- For
http
and https
accessed storage =
it's
- possible to pass one or more cookies. The cookie name and value
- must conform to the HTTP specification.
- Since 6.2.0
-
- readahead
- -
- Specifies the size of the readahead buffer for protocols
- which support it. (all 'curl' based drivers in qemu). The size
- is in bytes. Note that '0' is considered as if the value is not
- provided.
- Since 6.2.0
-
- timeout
- -
- Specifies the connection timeout for protocols which support i=
t.
- Note that '0' is considered as if the value is not provided.
- Since 6.2.0
-
-
-
-
- For a "file" or "volume" disk type which represents a cdrom or flo=
ppy
- (the device
attribute), it is possible to define
- policy what to do with the disk if the source file is not accessib=
le.
- (NB, startupPolicy
is not valid for "volume" disk unl=
ess
- the specified storage volume is of "file" type). This is done by =
the
- startupPolicy
attribute
- (since 0.9.7),
- accepting these values:
-
-
-
- mandatory
- fail if missing for any reason (the default)
-
-
- requisite
- fail if missing on boot up,
- drop if missing on migrate/restore/revert
-
-
- optional
- drop if missing at any start attempt
-
-
-
- Since 1.1.2 the startupPolicy=
code>
- is extended to support hard disks besides cdrom and floppy. On gue=
st
- cold bootup, if a certain disk is not accessible or its disk chain=
is
- broken, with startupPolicy 'optional' the guest will drop this dis=
k.
- This feature doesn't support migration currently.
-
-
backingStore
source
element.
- Since 1.2.4.
-
- If the hypervisor driver does not support the
-
- backingStoreInput
- (Since 5.10.0)
- domain feature the backingStore
is ignored on
- input and only used for output to describe the detected
- backing chains of running domains.
-
- If backingStoreInput
is supported
- the backingStore
is used as the backing image of
- source
or other backingStore
overriding
- any backing image information recorded in the image metadata.
-
- An empty backingStore
element means the sibling
- source is self-contained and is not based on any backing store.
-
- For the detected backing chain information to be accurate, the
- backing format must be correctly specified in the metadata of
- each file of the chain (files created by libvirt satisfy this
- property, but using existing external files for snapshot or
- block copy operations requires the end user to pre-create the
- file correctly). The following attributes are
- supported in backingStore
:
- type
type
attribute represents the type of disk us=
ed
- by the backing store, see disk type attribute above for more
- details and possible values.
- index
virDomainBlockRebase
API). For example,
- vda[2]
refers to the backing store with
- index=3D'2'
of the disk with vda
tar=
get.
- backingStore
supports the following sub-ele=
ments:
- format
format
element contains type
- attribute which specifies the internal format of the backing
- store, such as raw
or qcow2
.
- source
source
- element in disk
. It specifies which file, device,
- or network location contains the data of the described backing
- store.
- backingStore
backingStore
- element.
- mirror
source
sub-element will eventually have the
- same contents as the source, and with the file format in the
- sub-element format
(which might differ from the
- format of the source). The details of the source
- sub-element are determined by the type
attribute
- of the mirror, similar to what is done for the
- overall disk
device element. The job
- attribute mentions which API started the operation ("copy" for
- the virDomainBlockRebase
API, or "active-commit"
- for the virDomainBlockCommit
- API), since 1.2.7. The
- attribute ready
, if present, tracks progress of
- the job: yes
if the disk is known to be ready to
- pivot, or, since
- 1.2.7, abort
or pivot
if the
- job is in the process of completing. If ready
is
- not present, the disk is probably still
- copying. For now, this element only valid in output; it is
- ignored on input. The source
sub-element exists
- for all two-phase jobs since 1.2.6.
- Older libvirt supported only block copy to a
- file, since 0.9.12; for
- compatibility with older clients, such jobs include redundant
- information in the attributes file
- and format
in the mirror
element.
- target
target
element controls the bus / device
- under which the disk is exposed to the guest
- OS. The dev
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 bus
- attribute specifies the type of disk device to emulate;
- possible values are driver specific, with typical values being
- "ide", "scsi", "virtio", "xen", "usb", "sata", or
- "sd" "sd" since 1.1.2. If omitted, th=
e bus
- type is inferred from the style of the device name (e.g. a device =
named
- 'sda' will typically be exported using a SCSI bus). The optional
- attribute tray
indicates the tray status of the
- removable disks (i.e. CDROM or Floppy disk), the value can be eith=
er
- "open" or "closed", defaults to "closed". NB, the value of
- tray
could be updated while the domain is running.
- The optional attribute removable
sets the
- removable flag for USB disks, and its value can be either "on"
- or "off", defaulting to "off". Since
- 0.0.3; bus
attribute since 0.4.3;
- tray
attribute since 0.9.11; "usb" attribute value si=
nce
- after 0.4.4; "sata" attribute value since 0.9.7; "removable" attri=
bute
- value since 1.1.3
- iotune
iotune
element provides the
- ability to provide additional per-device I/O tuning, with
- values that can vary for each device (contrast this to
- the <blkiotune>
- element, which applies globally to the domain). Currently,
- the only tuning available is Block I/O throttling for qemu.
- This element has optional sub-elements; any sub-element not
- specified or given with a value of 0 implies no
- limit. Since 0.9.8
- total_bytes_sec
total_bytes_sec
element is the
- total throughput limit in bytes per second. This cannot
- appear with read_bytes_sec
- or write_bytes_sec
.read_bytes_sec
read_bytes_sec
element is the
- read throughput limit in bytes per second.write_bytes_sec
write_bytes_sec
element is the
- write throughput limit in bytes per second.total_iops_sec
total_iops_sec
element is the
- total I/O operations per second. This cannot
- appear with read_iops_sec
- or write_iops_sec
.read_iops_sec
read_iops_sec
element is the
- read I/O operations per second.write_iops_sec
write_iops_sec
element is the
- write I/O operations per second.total_bytes_sec_max
total_bytes_sec_max
element is the
- maximum total throughput limit in bytes per second. This cann=
ot
- appear with read_bytes_sec_max
- or write_bytes_sec_max
.read_bytes_sec_max
read_bytes_sec_max
element is the
- maximum read throughput limit in bytes per second.write_bytes_sec_max
write_bytes_sec_max
element is the
- maximum write throughput limit in bytes per second.total_iops_sec_max
total_iops_sec_max
element is the
- maximum total I/O operations per second. This cannot
- appear with read_iops_sec_max
- or write_iops_sec_max
.read_iops_sec_max
read_iops_sec_max
element is the
- maximum read I/O operations per second.write_iops_sec_max
write_iops_sec_max
element is the
- maximum write I/O operations per second.size_iops_sec
size_iops_sec
element is the
- size of I/O operations per second.
- - Throughput limits since 1.2.11 and QEMU = 1.7 -
-group_name
group_name
provides the cability
- to share I/O throttling quota between multiple drives. This
- prevents end-users from circumventing a hosting provider's
- throttling policy by splitting 1 large drive in N small drives
- and getting N times the normal throttling quota. Any name may
- be used.
- - group_name since 3.0.0 and QEMU 2.4 -
-total_bytes_sec_max_length
total_bytes_sec_max_length
- element is the maximum duration in seconds for the
- total_bytes_sec_max
burst period. Only valid
- when the total_bytes_sec_max
is set.read_bytes_sec_max_length
read_bytes_sec_max_length
- element is the maximum duration in seconds for the
- read_bytes_sec_max
burst period. Only valid
- when the read_bytes_sec_max
is set.write_bytes_sec_max
write_bytes_sec_max_length
- element is the maximum duration in seconds for the
- write_bytes_sec_max
burst period. Only valid
- when the write_bytes_sec_max
is set.total_iops_sec_max_length
total_iops_sec_max_length
- element is the maximum duration in seconds for the
- total_iops_sec_max
burst period. Only valid
- when the total_iops_sec_max
is set.read_iops_sec_max_length
read_iops_sec_max_length
- element is the maximum duration in seconds for the
- read_iops_sec_max
burst period. Only valid
- when the read_iops_sec_max
is set.write_iops_sec_max
write_iops_sec_max_length
- element is the maximum duration in seconds for the
- write_iops_sec_max
burst period. Only valid
- when the write_iops_sec_max
is set.
- - Throughput length since 2.4.0 and QEMU 2= .6 -
-driver
name
attribute selects the primary
- backend driver name, while the optional type
- 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".
- cache
attribute controls the
- cache mechanism, possible values are "default", "none",
- "writethrough", "writeback", "directsync" (like
- "writethrough", but it bypasses the host page cache) and
- "unsafe" (host may cache all disk io, and sync requests from
- guest are ignored).
-
- Since 0.6.0,
- "directsync" since 0.9.5,
- "unsafe" since 0.9.7
-
- error_policy
attribute controls
- how the hypervisor will behave on a disk read or write
- error, possible values are "stop", "report", "ignore", and
- "enospace".Since 0.8.0, "report" since
- 0.9.7 The default is left to the discretion of the
- hypervisor. There is also an
- optional rerror_policy
that controls behavior
- for read errors only. Since
- 0.9.7. If no rerror_policy is given, error_policy
- is used for both read and write errors. If rerror_policy
- is given, it overrides the error_policy
for
- read errors. Also note that "enospace" is not a valid
- policy for read errors, so if error_policy
is
- set to "enospace" and no rerror_policy
is
- given, the read error policy will be left at its default.
- io
attribute controls specific
- policies on I/O; qemu guests support "threads" and
- "native" Since 0.8.8, io_uring
- Since 6.3.0 (QEMU 5.0).
- ioeventfd
attribute allows users to
- set
- domain I/O asynchronous handling 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.
- Since 0.9.3 (QEMU and KVM only)
- In general you should leave this option alone, unless you
- are very certain you know what you are doing.
- event_idx
attribute controls
- some aspects of device event processing. The value can be
- either 'on' or 'off' - if it is on, it will reduce the
- number of interrupts and exits for the guest. The default
- is determined by QEMU; usually if the feature is
- supported, default is on. In case there is a situation
- where this behavior is suboptimal, this attribute provides
- a way to force the feature off.
- Since 0.9.5 (QEMU and KVM only)
- In general you should leave this option alone, unless you
- are very certain you know what you are doing.
- copy_on_read
attribute controls
- whether to copy read backing file into the image file. The
- value can be either "on" or "off".
- Copy-on-read avoids accessing the same backing file sectors
- repeatedly and is useful when the backing file is over a slow
- network. By default copy-on-read is off.
- Since 0.9.10 (QEMU and KVM only)
- discard
attribute controls whether
- discard requests (also known as "trim" or "unmap") are
- ignored or passed to the filesystem. The value can be either
- "unmap" (allow the discard request to be passed) or "ignore"
- (ignore the discard request).
- Since 1.0.6 (QEMU and KVM only)
- detect_zeroes
attribute controls whe=
ther
- to detect zero write requests. The value can be "off", "on" or
- "unmap". First two values turn the detection off and on,
- respectively. The third value ("unmap") turns the detection on
- and additionally tries to discard such areas from the image ba=
sed
- on the value of discard
above (it will act as "on"
- if discard
is set to "ignore"). NB enabling the
- detection is a compute intensive operation, but can save file
- space and/or time on slow media.
- Since 2.0.0
- iothread
attribute assigns the
- disk to an IOThread as defined by the range for the domain
- iothreads
- value. Multiple disks may be assigned to the same IOThread and
- are numbered from 1 to the domain iothreads value. Available
- for a disk device target
configured to use "virti=
o"
- bus
and "pci" or "ccw" address
types.
- Since 1.2.8 (QEMU 2.1)
- queues
attribute specifies the numbe=
r of
- virt queues for virtio-blk. (Since 3.9.0=
)
- backenddomain
backenddomain
element allows specifyin=
g a
- backend domain (aka driver domain) hosting the disk. Use the
- name
attribute to specify the backend domain name.
- Since 1.2.13 (Xen only)
- boot
order
- attribute determines the order in which devices will be tried duri=
ng
- boot sequence. On the S390 architecture only the first boot device=
is
- used. The optional loadparm
attribute is an 8 charact=
er
- string which can be queried by guests on S390 via sclp or diag 308.
- Linux guests on S390 can use loadparm
to select a boot
- entry. Since 3.5.0
- The per-device boot
elements cannot be used together
- with general boot elements in
- BIOS bootloader section.
- Since 0.8.8
- encryption
encryption
element is preferred to be a sub-element
- of the source
element. If present, specifies how the
- volume is encrypted using "qcow". See the
- Storage Encryption pa=
ge
- for more information.
- readonly
device=3D'cdrom'
.
- shareable
transient
serial
<serial>WD-WMAP9A966149</serial>
.
- Not supported for scsi-block devices, that is those using
- disk type
'block' using device
'lun'
- on bus
'scsi'.
- Since 0.7.1
- wwn
vendor
product
address
address
element ties the disk
- to a given slot of a controller (the
- actual <controller>
device can often be
- inferred by libvirt, although it can
- be explicitly specified).
- The type
attribute is mandatory, and is typically
- "pci" or "drive". For a "pci" controller, additional
- attributes for bus
, slot
,
- and function
must be present, as well as
- optional domain
and multifunction
.
- Multifunction defaults to 'off'; any other value requires
- QEMU 0.1.3 and libvirt 0.9.7. For a
- "drive" controller, additional attributes
- controller
, bus
, target
- (libvirt 0.9.11), and unit
- are available, each defaulting to 0.
-
auth
auth
element is preferred to be a sub-element of
- the source
element. The element is still read and
- managed as a disk
sub-element. It is invalid to use
- auth
as both a sub-element of disk
- and source
. The auth
element was
- introduced as a disk
sub-element in
- libvirt 0.9.7.
- geometry
geometry
element provides the
- ability to override geometry settings. This mostly useful for
- S390 DASD-disks or older DOS-disks. 0.10.0<=
/span>
- cyls
cyls
attribute is the
- number of cylinders. heads
heads
attribute is the
- number of heads. secs
secs
attribute is the
- number of sectors per track. trans
trans
attribute is the
- BIOS-Translation-Modus (none, lba or auto)blockio
blockio
element allows
- to override any of the block device properties listed below.
- Since 0.10.2 (QEMU and KVM)
- logical_block_size
physical_block_size
- A directory on the host that can be accessed directly from the guest. - since 0.3.3, since 0.8.5 for QEMU/KVM -
- --... -<devices> - <filesystem type=3D'template'> - <source name=3D'my-vm-template'/> - <target dir=3D'/'/> - </filesystem> - <filesystem type=3D'mount' accessmode=3D'passthrough' multidevs=3D're= map'> - <driver type=3D'path' wrpolicy=3D'immediate'/> - <source dir=3D'/export/to/guest'/> - <target dir=3D'/import/from/host'/> - <readonly/> - </filesystem> - <filesystem type=3D'file' accessmode=3D'passthrough'> - <driver type=3D'loop' format=3D'raw'/> - <driver type=3D'path' wrpolicy=3D'immediate'/> - <source file=3D'/export/to/guest.img'/> - <target dir=3D'/import/from/host'/> - <readonly/> - </filesystem> - <filesystem type=3D'mount' accessmode=3D'passthrough'> - <driver type=3D'virtiofs' queue=3D'1024'/> - <binary path=3D'/usr/libexec/virtiofsd' xattr=3D'on'> - <cache mode=3D'always'/> - <lock posix=3D'on' flock=3D'on'/> - </binary> - <source dir=3D'/path'/> - <target dir=3D'mount_tag'/> - </filesystem> - ... -</devices> -...- -
filesystem
type
specifies the type of the
- source
. The possible values are:
-
- mount
type
if one is not specified.
- This mode also has an optional
- sub-element driver
, with an
- attribute type=3D'path'
- or type=3D'handle'
(since
- 0.9.7). The driver block has an optional attribute
- wrpolicy
that further controls interaction with
- the host page cache; omitting the attribute gives default behavior,
- while the value immediate
means that a host writeback
- is immediately triggered for all pages touched during a guest file
- write operation (since 0.9.10).
- Since 6.2.0, type=3D'virtiofs'<=
/code>
- is also supported. Using virtiofs requires setting up shared memor=
y,
- see the guide: Virtio-FS
-
template
file
block
ram
usage
- which gives the memory usage limit in KiB, unless units
- are specified by the units
attribute. Only used
- by LXC driver.
- (since 0.9.13)bind
accessmode
- which specifies the security mode for accessing the source
- (since 0.8.5). Currently this only works
- with type=3D'mount'
for the QEMU/KVM driver.
- For driver type virtiofs
, only passthrough
=
is
- supported. For other driver types, the possible
- values are:
-
-
- passthrough
- -
- The
source
is accessed with the permissions of the
- user inside the guest. This is the default accessmode
=
if
- one is not specified.
- More info
-
- mapped
- -
- The
source
is accessed with the permissions of the
- hypervisor (QEMU process).
- More info
-
- squash
- -
- 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.
- More info
-
-
-
-
- Since 5.2.0, the filesystem element
- has an optional attribute model
with supported values
- "virtio-transitional", "virtio-non-transitional", or "virtio".
- See Virtio transitional devi=
ces
- for more details.
-
-
-
- The filesystem element has an optional attribute multidevs
- which specifies how to deal with a filesystem export containing more=
than
- one device, in order to avoid file ID collisions on guest when using=
9pfs
- (since 6.3.0, requires QEMU 4.2).
- This attribute is not available for virtiofs. The possible values ar=
e:
-
-
-
- default
- -
- Use QEMU's default setting (which currently is
warn
).
-
- remap
- -
- This setting allows guest to access multiple devices per export wi=
thout
- encountering misbehaviours. Inode numbers from host are automatica=
lly
- remapped on guest to actively prevent file ID collisions if guest
- accesses one export containing multiple devices.
-
- forbid
- -
- Only allow to access one device per export by guest. Attempts to a=
ccess
- additional devices on the same export will cause the individual
- filesystem access by guest to fail with an error and being logged =
(once)
- as error on host side.
-
- warn
- -
- This setting resembles the behaviour of 9pfs prior to QEMU 4.2, th=
at is
- no action is performed to prevent any potential file ID collisions=
if an
- export contains multiple devices, with the only exception: a warni=
ng is
- logged (once) on host side now. This setting may lead to misbehavi=
ours
- on guest side if more than one device is exported per export, due =
to the
- potential file ID collisions this may cause on guest side in that =
case.
-
-
-
-
- The filesystem
element may contain the following subele=
ments:
-
driver
type
attribute selects the primary
- backend driver name, while the format
- attribute provides the format type. For example, LXC
- supports a type of "loop", with a format of "raw" or
- "nbd" with any format. QEMU supports a type of "path"
- or "handle", but no formats. Virtuozzo driver supports
- a type of "ploop" with a format of "ploop".
- virtiofs
, the queue
attribute ca=
n be used
- to specify the queue size (i.e. how many requests can the queu=
e fit).
- (Since 6.2.0)
- binary
binary
element can tune the options for =
virtiofsd.
- All of the following attributes and elements are optional.
- The attribute path
can be used to override the path t=
o the daemon.
- Attribute xattr
enables the use of filesystem extende=
d attributes.
- Caching can be tuned via the cache
element, possible =
mode
- values being none
and always
.
- Locking can be controlled via the lock
- element - attributes posix
and flock
bot=
h accepting
- values on
or off
.
- (Since 6.2.0)
- source
name
attribute must be used with
- type=3D'template'
, and the dir
attribute=
must
- be used with type=3D'mount'
. The usage
a=
ttribute
- is used with type=3D'ram'
to set the memory limit in =
KiB,
- unless units are specified by the units
attribute.
- target
source
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.
- readonly
space_hard_limit
space_soft_limit
- Many devices have an optional <address>
- sub-element to describe where the device is placed on the
- virtual bus presented to the guest. If an address (or any
- optional attribute within an address) is omitted on
- input, libvirt will generate an appropriate address; but an
- explicit address is required if more control over layout is
- required. See below for device examples including an address
- element.
-
- Every address has a mandatory attribute type
that
- describes which bus the device is on. The choice of which
- address to use for a given device is constrained in part by the
- device and the architecture of the guest. For example,
- a <disk>
device
- uses type=3D'drive'
, while
- a <console>
device would
- use type=3D'pci'
on i686 or x86_64 guests,
- or type=3D'spapr-vio'
on PowerPC64 pseries guests.
- Each address type has further optional attributes that control
- where on the bus the device will be placed:
-
pci
domain
(a 2-byte hex integer, not
- currently used by qemu), bus
(a hex value between
- 0 and 0xff, inclusive), slot
(a hex value between
- 0x0 and 0x1f, inclusive), and function
(a value
- between 0 and 7, inclusive). Also available is
- the multifunction
attribute, which controls
- turning on the multifunction bit for a particular
- slot/function in the PCI control register
- (since 0.9.7, requires QEMU
- 0.13). multifunction
defaults to 'off',
- but should be set to 'on' for function 0 of a slot that will
- have multiple functions used.
- (Since 4.10.0), PCI address extensions
- depending on the architecture are supported. For example, PCI
- addresses for S390 guests will have a zpci
child
- element, with two attributes: uid
(a hex value
- between 0x0001 and 0xffff, inclusive), and fid
(a
- hex value between 0x00000000 and 0xffffffff, inclusive) used by
- PCI devices on S390 for User-defined Identifiers and Function
- Identifiers.<address type=3D'pci'/>
- element with no other attributes as an explicit request to
- assign a PCI address for the device rather than some other
- type of address that may also be appropriate for that same
- device (e.g. virtio-mmio).drive
controller
(a 2-digit controller
- number), bus
(a 2-digit bus number),
- target
(a 2-digit target number),
- and unit
(a 2-digit unit number on the bus).
- virtio-serial
controller
(a 2-digit controller
- number), bus
(a 2-digit bus number),
- and slot
(a 2-digit slot within the bus).
- ccid
bus
(a 2-digit bus
- number), and slot
attribute (a 2-digit slot
- within the bus). Since 0.8.8.
- usb
bus
(a hex value between 0 and 0xfff,
- inclusive), and port
(a dotted notation of up to
- four octets, such as 1.2 or 2.1.3.1).
- spapr-vio
reg
(the hex value address
- of the starting register). Since
- 0.9.9.
- ccw
machine
value of
- s390-ccw-virtio use the native CCW bus for I/O devices.
- CCW bus addresses have the following additional attributes:
- cssid
(a hex value between 0 and 0xfe, inclusive),
- ssid
(a value between 0 and 3, inclusive) and
- devno
(a hex value between 0 and 0xffff, inclusive).
- Partially specified bus addresses are not allowed.
- If omitted, libvirt will assign a free bus address with
- cssid=3D0xfe and ssid=3D0. Virtio-ccw devices must have their cssid
- set to 0xfe.
- Since 1.0.4
- virtio-mmio
armv7l
and
- aarch64
virtual machines. virtio-mmio addresses
- do not have any additional attributes.
- Since 1.1.3aarch64
and the machine
- type is virt
, libvirt will automatically assign PCI
- addresses to devices; however, the presence of a single device
- with virtio-mmio address in the guest configuration will cause
- libvirt to assign virtio-mmio addresses to all further devices.
- Since 3.0.0
- isa
iobase
and irq
.
- Since 1.2.1
- unassigned
<address type=3D'unassigned'/>
- allows the admin to include a PCI hostdev in the domain XML defini=
tion,
- without making it available for the guest. This allows for configu=
rations
- in which Libvirt manages the device as a regular PCI hostdev,
- regardless of whether the guest will have access to it.
- <address type=3D'unassigned'/>
is an invalid ad=
dress
- type for all other device types.
- Since 6.0.0
-
- QEMU's virtio devices have some attributes related to the virtio tra=
nsport under
- the driver
element:
- The iommu
attribute enables the use of emulated IOMMU
- by the device. The attribute ats
controls the Address
- Translation Service support for PCIe devices. This is needed to make=
use
- of IOTLB support (see IOMMU device).
- Possible values are on
or off
.
- Since 3.5.0
-
- The attribute packed
controls if QEMU should try to use
- packed virtqueues. Compared to regular split queues, packed queues
- consist of only a single descriptor ring replacing available and used
- ring, index and descriptor buffer. This can result in better cache
- utilization and performance. If packed virtqueues are actually used
- depends on the feature negotiation between QEMU, vhost backends and =
guest
- drivers. Possible values are on
or off
.
- Since 6.3.0 (QEMU and KVM only)
-
- Since 5.2.0, some of QEMU's virtio devi=
ces,
- when used with PCI/PCIe machine types, accept the following
- model
values:
-
virtio-transitional
virtio-non-transitional
virtio
virtio-non-transitional
- device when plugged into a PCI Express slot, and like a
- virtio-transitional
device otherwise; libvirt will
- pick one or the other based on the machine type. This is the best
- choice when compatibility with libvirt versions older than 5.2.0
- is necessary, but it's otherwise not recommended to use it.
- - While the information outlined above applies to most virtio devices, - there are a few exceptions: -
- -virtio-scsi
must be used instead
- of virtio
for backwards compatibility reasons;
- virtio
, which will result in a non-transitional devic=
e.
- - For more details see the - qemu patch posting and the - virtio-1.0 spec. -
- - -- Depending on the guest architecture, some device buses can - appear more than once, with a group of virtual devices tied to a - virtual controller. Normally, libvirt can automatically infer such - controllers without requiring explicit XML markup, but sometimes - it is necessary to provide an explicit controller element, notably - when planning the PCI topology - for guests where device hotplug is expected. -
- --... -<devices> - <controller type=3D'ide' index=3D'0'/> - <controller type=3D'virtio-serial' index=3D'0' ports=3D'16' vectors= =3D'4'/> - <controller type=3D'virtio-serial' index=3D'1'> - <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x0a' = function=3D'0x0'/> - </controller> - <controller type=3D'scsi' index=3D'0' model=3D'virtio-scsi'> - <driver iothread=3D'4'/> - <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x0b' = function=3D'0x0'/> - </controller> - <controller type=3D'xenbus' maxGrantFrames=3D'64' maxEventChannels=3D= '2047'/> - ... -</devices> -...- -
- Each controller has a mandatory attribute type
,
- which must be one of 'ide', 'fdc', 'scsi', 'sata', 'usb',
- 'ccid', 'virtio-serial' or 'pci', and a mandatory
- attribute index
which is the decimal integer
- describing in which order the bus controller is encountered (for
- use in controller
attributes of
- <address>
elements).
- Since 1.3.5 the index is optional; if
- not specified, it will be auto-assigned to be the lowest unused
- index for the given controller type. Some controller types have
- additional attributes that control specific features, such as:
-
virtio-serial
virtio-serial
controller has two additional
- optional attributes ports
and vectors
,
- which control how many devices can be connected through the
- controller. Since 5.2.0, it
- supports an optional attribute model
which can
- be 'virtio', 'virtio-transitional', or 'virtio-non-transitional'. =
See
- Virtio transitional device=
s
- for more details.
- scsi
scsi
controller has an optional attribute
- model
, which is one of 'auto', 'buslogic', 'ibmvscsi',
- 'lsilogic', 'lsisas1068', 'lsisas1078', 'virtio-scsi',
- 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. See
- Virtio transitional device=
s
- for more details.
- usb
usb
controller has an optional attribute
- model
, which is one of "piix3-uhci", "piix4-uhci",
- "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3",
- "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pvusb
- with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu
- backend, version 2.0) or "qemu-xhci". Additionally,
- since 0.10.0, if the USB bus needs to
- be explicitly disabled for the guest, model=3D'none'
- may be used. Since 1.0.5, no default
- USB controller will be built on s390.
- Since 1.3.5, USB controllers accept a
- ports
attribute to configure how many devices can be
- connected to the controller.ide
ide
controller has an optional attribute
- model
, which is one of "piix3", "piix4" or "ich6".
- xenbus
xenbus
- controller has an optional attribute maxGrantFrames
,
- which specifies the maximum number of grant frames the controller
- makes available for connected devices.
- Since 6.3.0, the xenbus controller
- supports the optional maxEventChannels
attribute,
- which specifies maximum number of event channels (PV interrupts)
- that can be used by the guest.
- Note: The PowerPC64 "spapr-vio" addresses do not have an - associated controller. -
- -
- For controllers that are themselves devices on a PCI or USB bus,
- an optional sub-element <address>
can specify
- the exact relationship of the controller to its master bus, with
- semantics given above.
-
- An optional sub-element driver
can specify the driver
- specific options:
-
queues
queues
attribute specifies the number of
- queues for the controller. For best performance, it's recommended =
to
- specify a value matching the number of vCPUs.
- Since 1.0.5 (QEMU and KVM only)
- cmd_per_lun
cmd_per_lun
attribute specifies the maxi=
mum
- number of commands that can be queued on devices controlled by the
- host.
- Since 1.2.7 (QEMU and KVM only)
- max_sectors
max_sectors
attribute specifies the maxi=
mum
- amount of data in bytes that will be transferred to or from the de=
vice
- in a single command. The transfer length is measured in sectors, w=
here
- a sector is 512 bytes.
- Since 1.2.7 (QEMU and KVM only)
- ioeventfd
ioeventfd
attribute specifies
- whether the controller should use
-
- I/O asynchronous handling or not. Accepted values are
- "on" and "off". Since 1.2.18
- iothread
scsi
using model
- virtio-scsi
for address
types
- pci
and ccw
- since 1.3.5 (QEMU 2.4).
-
- The optional iothread
attribute assigns the controller
- to an IOThread as defined by the range for the domain
- iothreads
- value. Each SCSI disk
assigned to use the specified
- controller
will utilize the same IOThread. If a speci=
fic
- IOThread is desired for a specific SCSI disk
, then
- multiple controllers must be defined each having a specific
- iothread
value. The iothread
value
- must be within the range 1 to the domain iothreads value.
-
- USB companion controllers have an optional
- sub-element <master>
to specify the exact
- relationship of the companion to its master controller.
- A companion controller is on the same bus as its master, so
- the companion index
value should be equal.
- Not all controller models can be used as companion controllers
- and libvirt might provide some sensible defaults (settings
- of master startport
and function
of an
- address) for some particular models.
- Preferred companion controllers are ich-uhci[123]
.
-
-... -<devices> - <controller type=3D'usb' index=3D'0' model=3D'ich9-ehci1'> - <address type=3D'pci' domain=3D'0' bus=3D'0' slot=3D'4' function=3D= '7'/> - </controller> - <controller type=3D'usb' index=3D'0' model=3D'ich9-uhci1'> - <master startport=3D'0'/> - <address type=3D'pci' domain=3D'0' bus=3D'0' slot=3D'4' function=3D= '0' multifunction=3D'on'/> - </controller> - ... -</devices> -...- -
- PCI controllers have an optional model
attribute; possi=
ble
- values for this attribute are
-
pci-root
, pci-bridge
- (since 1.0.5)
- pcie-root
, dmi-to-pci-bridge
- (since 1.1.2)
- pcie-root-port
, pcie-switch-upstream-port
,
- pcie-switch-downstream-port
- (since 1.2.19)
- pci-expander-bus
, pcie-expander-bus
- (since 1.3.4)
- pcie-to-pci-bridge
- (since 4.3.0)
-
- The root controllers (pci-root
- and pcie-root
) have an
- optional pcihole64
element specifying how big (in
- kilobytes, or in the unit specified by pcihole64
's
- unit
attribute) the 64-bit PCI hole should be. Some gue=
sts (like
- Windows XP or Windows Server 2003) might crash when QEMU and Seabios
- are recent enough to support 64-bit PCI holes, unless this is disabl=
ed
- (set to 0). Since 1.1.2 (QEMU only)
-
- PCI controllers also have an optional
- subelement <model>
with an attribute
- name
. The name attribute holds the name of the
- specific device that qemu is emulating (e.g. "i82801b11-bridge")
- rather than simply the class of device ("pcie-to-pci-bridge",
- "pci-bridge"), which is set in the controller element's
- model attribute. In almost all cases, you should not
- manually add a <model>
subelement to a
- controller, nor should you modify one that is automatically
- generated by libvirt. Since 1.2.19 (QEMU
- only).
-
- PCI controllers also have an optional
- subelement <target>
with the attributes and
- subelements listed below. These are configurable items that 1)
- are visible to the guest OS so must be preserved for guest ABI
- compatibility, and 2) are usually left to default values or
- derived automatically by libvirt. In almost all cases, you
- should not manually add a <target>
subelement
- to a controller, nor should you modify the values in the those
- that are automatically generated by
- libvirt. Since 1.2.19 (QEMU only).
-
chassisNr
chassisNr
attribute in
- the <target>
subelement, which is used to
- control QEMU's "chassis_nr" option for the pci-bridge device
- (normally libvirt automatically sets this to the same value as
- the index attribute of the pci controller). If set, chassisNr
- must be between 1 and 255.
- chassis
chassis
attribute in
- the <target>
subelement, which is used to
- set the controller's "chassis" configuration value, which is
- visible to the virtual machine. If set, chassis must be
- between 0 and 255.
- port
port
attribute in
- the <target>
subelement, which
- is used to set the controller's "port" configuration value,
- which is visible to the virtual machine. If set, port must be
- between 0 and 255.
- hotplug
hotplug
attribute in
- the <target>
subelement, which is used to
- disable hotplug/unplug of devices on a particular
- controller. The default setting of hotplug
- is on
; it should be set to off
to
- disable hotplug/unplug of devices on a particular controller.
- Since 6.3.0
- busNr
busNr
attribute (1-254). This will be
- the bus number of the new bus; All bus numbers between that
- specified and 255 will be available only for assignment to
- PCI/PCIe controllers plugged into the hierarchy starting with
- this expander bus, and bus numbers less than the specified
- value will be available to the next lower expander-bus (or the
- root-bus if there are no lower expander buses). If you do not
- specify a busNumber, libvirt will find the lowest existing
- busNumber in all other expander buses (or use 256 if there are
- no others) and auto-assign the busNr of that found bus - 2,
- which provides one bus number for the pci-expander-bus and one
- for the pci-bridge that is automatically attached to it (if
- you plan on adding more pci-bridges to the hierarchy of the
- bus, you should manually set busNr to a lower value).
- - A similar algorithm is used for automatically determining - the busNr attribute for pcie-expander-bus, but since the - pcie-expander-bus doesn't have any built-in pci-bridge, the - 2nd bus-number is just being reserved for the pcie-root-port - that must necessarily be connected to the bus in order to - actually plug in an endpoint device. If you intend to plug - multiple devices into a pcie-expander-bus, you must connect - a pcie-switch-upstream-port to the pcie-root-port that is - plugged into the pcie-expander-bus, and multiple - pcie-switch-downstream-ports to the - pcie-switch-upstream-port, and of course for this to work - properly, you will need to decrease the pcie-expander-bus' - busNr accordingly so that there are enough unused bus - numbers above it to accommodate giving out one bus number for - the upstream-port and one for each downstream-port (in - addition to the pcie-root-port and the pcie-expander-bus - itself). -
-node
pci-expander-bus
for the pc
- machine type, pcie-expander-bus
for the q35 machine
- type and, since 3.6.0,
- pci-root
for the pseries machine type) can have an
- optional <node>
subelement within
- the <target>
subelement, which is used to
- set the NUMA node reported to the guest OS for that bus - the
- guest OS will then know that all devices on that bus are a
- part of the specified NUMA node (it is up to the user of the
- libvirt API to attach host devices to the correct
- pci-expander-bus when assigning them to the domain).
- index
- For machine types which provide an implicit PCI bus, the pci-root - controller with index=3D0 is auto-added and required to use PCI devi= ces. - pci-root has no address. - PCI bridges are auto-added if there are too many devices to fit on - the one bus provided by pci-root, or a PCI bus number greater than z= ero - was specified. - PCI bridges can also be specified manually, but their addresses shou= ld - only refer to PCI buses provided by already specified PCI controller= s. - Leaving gaps in the PCI controller indexes might lead to an invalid - configuration. -
--... -<devices> - <controller type=3D'pci' index=3D'0' model=3D'pci-root'/> - <controller type=3D'pci' index=3D'1' model=3D'pci-bridge'> - <address type=3D'pci' domain=3D'0' bus=3D'0' slot=3D'5' function=3D= '0' multifunction=3D'off'/> - </controller> -</devices> -...- -
- For machine types which provide an implicit PCI Express (PCIe)
- bus (for example, the machine types based on the Q35 chipset),
- the pcie-root controller with index=3D0 is auto-added to the
- domain's configuration. pcie-root has also no address, provides
- 31 slots (numbered 1-31) that can be used to attach PCIe or PCI
- devices (although libvirt will never auto-assign a PCI device to
- a PCIe slot, it will allow manual specification of such an
- assignment). Devices connected to pcie-root cannot be
- hotplugged. If traditional PCI devices are present in the guest
- configuration, a pcie-to-pci-bridge
controller will
- automatically be added: this controller, which plugs into a
- pcie-root-port
, provides 31 usable PCI slots (1-31) with
- hotplug support (since 4.3.0). If the Q=
EMU
- binary doesn't support the corresponding device, then a
- dmi-to-pci-bridge
controller will be added instead,
- usually at the defacto standard location of slot=3D0x1e. A
- dmi-to-pci-bridge controller plugs into a PCIe slot (as provided
- by pcie-root), and itself provides 31 standard PCI slots (which
- also do not support device hotplug). In order to have
- hot-pluggable PCI slots in the guest system, a pci-bridge
- controller will also be automatically created and connected to
- one of the slots of the auto-created dmi-to-pci-bridge
- controller; all guest PCI devices with addresses that are
- auto-determined by libvirt will be placed on this pci-bridge
- device. (since 1.1.2).
-
- Domains with an implicit pcie-root can also add controllers
- with model=3D'pcie-root-port'
,
- model=3D'pcie-switch-upstream-port'
,
- and model=3D'pcie-switch-downstream-port'
. pcie-root-po=
rt
- is a simple type of bridge device that can connect only to one
- of the 31 slots on the pcie-root bus on its upstream side, and
- makes a single (PCIe, hotpluggable) port available on the
- downstream side (at slot=3D'0'). pcie-root-port can be used to
- provide a single slot to later hotplug a PCIe device (but is not
- itself hotpluggable - it must be in the configuration when the
- domain is started).
- (since 1.2.19)
-
- pcie-switch-upstream-port is a more flexible (but also more - complex) device that can only plug into a pcie-root-port or - pcie-switch-downstream-port on the upstream side (and only - before the domain is started - it is not hot-pluggable), and - provides 32 ports on the downstream side (slot=3D'0' - slot=3D'31') - that accept only pcie-switch-downstream-port devices; each - pcie-switch-downstream-port device can only plug into a - pcie-switch-upstream-port on its upstream side (again, not - hot-pluggable), and on its downstream side provides a single - hotpluggable pcie port that can accept any standard pci or pcie - device (or another pcie-switch-upstream-port), i.e. identical in - function to a pcie-root-port. (since - 1.2.19) -
--... -<devices> - <controller type=3D'pci' index=3D'0' model=3D'pcie-root'/> - <controller type=3D'pci' index=3D'1' model=3D'pcie-root-port'> - <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x01' = function=3D'0x0'/> - </controller> - <controller type=3D'pci' index=3D'2' model=3D'pcie-to-pci-bridge'> - <address type=3D'pci' domain=3D'0x0000' bus=3D'0x01' slot=3D'0x00' = function=3D'0x0'/> - </controller> -</devices> -...- -
- When using a lock manager, it may be desirable to record device leas= es - against a VM. The lock manager will ensure the VM won't start unless - the leases can be acquired. -
- --... -<devices> - ... - <lease> - <lockspace>somearea</lockspace> - <key>somekey</key> - <target path=3D'/some/lease/path' offset=3D'1024'/> - </lease> - ... -</devices> -...- -
lockspace
key
target
- USB, PCI and SCSI devices attached to the host can be passed through
- to the guest using the hostdev
element.
- since after 0.4.4 for USB, 0.6.0 for PCI (KVM =
only)
- and 1.0.6 for SCSI (KVM only):
-
-... -<devices> - <hostdev mode=3D'subsystem' type=3D'usb'> - <source startupPolicy=3D'optional'> - <vendor id=3D'0x1234'/> - <product id=3D'0xbeef'/> - </source> - <boot order=3D'2'/> - </hostdev> -</devices> -...- -
or:
- --... -<devices> - <hostdev mode=3D'subsystem' type=3D'pci' managed=3D'yes'> - <source> - <address domain=3D'0x0000' bus=3D'0x06' slot=3D'0x02' function=3D= '0x0'/> - </source> - <boot order=3D'1'/> - <rom bar=3D'on' file=3D'/etc/fake/boot.bin'/> - </hostdev> -</devices> -...- -
or:
- --... -<devices> - <hostdev mode=3D'subsystem' type=3D'scsi' sgio=3D'filtered' rawio=3D'= yes'> - <source> - <adapter name=3D'scsi_host0'/> - <address bus=3D'0' target=3D'0' unit=3D'0'/> - </source> - <readonly/> - <address type=3D'drive' controller=3D'0' bus=3D'0' target=3D'0' uni= t=3D'0'/> - </hostdev> -</devices> -...- - -
or:
- --... -<devices> - <hostdev mode=3D'subsystem' type=3D'scsi'> - <source protocol=3D'iscsi' name=3D'iqn.2014-08.com.example:iscsi-no= pool/1'> - <host name=3D'example.com' port=3D'3260'/> - <auth username=3D'myuser'> - <secret type=3D'iscsi' usage=3D'libvirtiscsi'/> - </auth> - </source> - <address type=3D'drive' controller=3D'0' bus=3D'0' target=3D'0' uni= t=3D'0'/> - </hostdev> -</devices> -...- -
or:
- -- ... - <devices> - <hostdev mode=3D'subsystem' type=3D'scsi_host'> - <source protocol=3D'vhost' wwpn=3D'naa.50014057667280d8'/> - </hostdev> - </devices> - ...- -
or:
- -- ... - <devices> - <hostdev mode=3D'subsystem' type=3D'mdev' model=3D'vfio-pci'> - <source> - <address uuid=3D'c2177883-f1bb-47f0-914d-32a22e3a8804'/> - </source> - </hostdev> - <hostdev mode=3D'subsystem' type=3D'mdev' model=3D'vfio-ccw'> - <source> - <address uuid=3D'9063cba3-ecef-47b6-abcf-3fef4fdcad85'/> - </source> - <address type=3D'ccw' cssid=3D'0xfe' ssid=3D'0x0' devno=3D'0x0001'/= > - </hostdev> - </devices> - ...- -
hostdev
hostdev
element is the main container for descr=
ibing
- host devices. For each device, the mode
is always
- "subsystem" and the type
is one of the following valu=
es
- with additional attributes noted.
- usb
pci
managed
is "yes" it is
- detached from the host before being passed on to the guest
- and reattached to the host after the guest exits. If
- managed
is omitted or "no", the user is
- responsible to call virNodeDeviceDetachFlags
- (or virsh nodedev-detach
before starting the guest
- or hot-plugging the device and virNodeDeviceReAttach
- (or virsh nodedev-reattach
) after hot-unplug or
- stopping the guest.
-
scsi
sgio
(since 1.0.6<=
/span>)
- attribute indicates whether unprivileged SG_IO commands are
- filtered for the disk. Valid settings are "filtered" or
- "unfiltered", where the default is "filtered".
- The optional rawio
- (since 1.2.9) attribute indicates
- whether the lun needs the rawio capability. Valid settings are
- "yes" or "no". See the rawio description within the
- disk section.
- If a disk lun in the domain already has the rawio capability,
- then this setting not required.
- scsi_host
type
passes all LUNs presented by a single HBA to
- the guest. Since 5.2.0, the
- model
attribute can be specified further
- with "virtio-transitional", "virtio-non-transitional", or
- "virtio". See
- Virtio transitional de=
vices
- for more details.
- mdev
model
attribute specifies the device API which
- determines how the host's vfio driver will expose the device to =
the
- guest. Currently, model=3D'vfio-pci'
,
- model=3D'vfio-ccw'
(Since 4.4=
.0)
- and model=3D'vfio-ap'
(Since =
4.9.0)
- is supported. MDEV section
- provides more information about mediated devices as well as how =
to
- create mediated devices on the host.
- Since 4.6.0 (QEMU 2.12) an optional
- display
attribute may be used to enable or disable
- support for an accelerated remote desktop backed by a mediated
- device (such as NVIDIA vGPU or Intel GVT-g) as an alternative to
- emulated video devices. This attr=
ibute
- is limited to model=3D'vfio-pci'
only. Supported va=
lues
- are either on
or off
(default is 'off'=
).
- It is required to use a
- graphical framebuffer in order=
to
- use this attribute, currently only supported with VNC, Spice and
- egl-headless graphics devices.
-
- Since version 5.10.0, there is an o=
ptional
- ramfb
attribute for devices with
- model=3D'vfio-pci'
. Supported values are either
- on
or off
(default is 'off'). When
- enabled, this attribute provides a memory framebuffer device to =
the
- guest. This framebuffer will be used as a boot display when a v=
gpu
- device is the primary display.
-
- Note: There are also some implications on the usage of guest's
- address type depending on the model
attribute,
- see the address
element below.
-
- Note: The managed
attribute is only used with
- type=3D'pci'
and is ignored by all the other device=
types,
- thus setting managed
explicitly with other than a P=
CI
- device has the same effect as omitting it. Similarly,
- model
attribute is only supported by mediated devic=
es and
- ignored by all other device types.
-
source
usb
vendor
and product
elements
- or by the device's address on the host using the
- address
element.
-
- Since 1.0.0, the source
- element of USB devices may contain
startupPolicy
- attribute which can be used to define policy what to do if the
- specified host USB device is not found. The attribute accepts
- the following values:
-
mandatory | -fail if missing for any reason (the default) | -
requisite | -fail if missing on boot up, - drop if missing on migrate/restore/revert | -
optional | -drop if missing at any start attempt | -
pci
address.
-
scsi
adapter
- and address
elements. The address
- element includes a bus
attribute (a 2-digit bus
- number), a target
attribute (a 10-digit target
- number), and a unit
attribute (a 20-digit unit
- number on the bus). Not all hypervisors support larger
- target
and unit
values. It is up
- to each hypervisor to determine the maximum value supported
- for the adapter.
-
- Since 1.2.8, the source
- element of a SCSI device may contain the
protocol
- attribute. When the attribute is set to "iscsi", the host
- device XML follows the network disk=
- device using the same name
attribute and optional=
ly
- using the auth
element to provide the authenticat=
ion
- credentials to the iSCSI server.
-
scsi_host
protocol
- attribute set to "vhost" and a wwpn
attribute that
- is the vhost_scsi wwpn (16 hexadecimal digits with a prefix of
- "naa.") established in the host configfs.
- mdev
address
element. The
- address
element contains a single mandatory attri=
bute
- uuid
.
- vendor
, product
vendor
and product
elements each h=
ave an
- id
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.boot
order
- attribute determines the order in which devices will be tried during
- boot sequence. The per-device boot
elements cannot be
- used together with general boot elements in
- BIOS bootloader section.
- Since 0.8.8 for PCI devices,
- Since 1.0.1 for USB devices.
- rom
rom
element is used to change how a PCI
- device's ROM is presented to the guest. The optional bar
- attribute can be set to "on" or "off", and determines whether
- or not the device's ROM will be visible in the guest's memory
- map. (In PCI documentation, the "rombar" setting controls the
- presence of the Base Address Register for the ROM). If no rom
- bar is specified, the qemu default will be used (older
- versions of qemu used a default of "off", while newer qemus
- have a default of "on"). Since
- 0.9.7 (QEMU and KVM only). The optional
- file
attribute contains an absolute path to a binary =
file
- to be presented to the guest as the device's ROM BIOS. This
- can be useful, for example, to provide a PXE boot ROM for a
- virtual function of an sr-iov capable ethernet device (which
- has no boot ROMs for the VFs).
- Since 0.9.10 (QEMU and KVM only).
- The optional enabled
attribute can be set to
- no
to disable PCI ROM loading completely for the devi=
ce;
- if PCI ROM loading is disabled through this attribute, attempts to
- tweak the loading process further using the bar
or
- file
attributes will be rejected.
- Since 4.3.0 (QEMU and KVM only).
-
address
address
element for USB devices has a
- bus
and device
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 4 attributes allowing to designa=
te
- the device as can be found with the lspci
or
- with virsh nodedev-list
. For SCSI devices a 'drive'
- address type must be used. For mediated devices, which are software-=
only
- devices defining an allocation of resources on the physical parent d=
evice,
- the address type used must conform to the model
attribu=
te
- of element hostdev
, e.g. any address type other than PC=
I for
- vfio-pci
device API or any address type other than CCW =
for
- vfio-ccw
device API will result in an error.
- See above for more details on the a=
ddress
- element.driver
driver
- subelement that specifies which backend driver to use for PCI
- device assignment. Use the name
attribute to
- select either "vfio" (for the new VFIO device assignment
- backend, which is compatible with UEFI SecureBoot) or "kvm"
- (the legacy device assignment handled directly by the KVM
- kernel module)Since 1.0.5 (QEMU and KVM
- only, requires kernel 3.6 or newer). When specified,
- device assignment will fail if the requested method of device
- assignment isn't available on the host. When not specified,
- the default is "vfio" on systems where the VFIO driver is
- available and loaded, and "kvm" on older systems, or those
- where the VFIO driver hasn't been
- loaded Since 1.1.3 (prior to that
- the default was always "kvm").
- readonly
shareable
- Note: Although shareable
was introduced
- in 1.0.6, it did not work as
- as expected until 1.2.2.
-
- Block / character devices from the host can be passed through
- to the guest using the hostdev
element. This is
- only possible with container based virtualization. Devices are speci=
fied
- by a fully qualified path.
- since after 1.0.1 for LXC:
-
-... -<hostdev mode=3D'capabilities' type=3D'storage'> - <source> - <block>/dev/sdf1</block> - </source> -</hostdev> -... -- -
-... -<hostdev mode=3D'capabilities' type=3D'misc'> - <source> - <char>/dev/input/event3</char> - </source> -</hostdev> -... -- -
-... -<hostdev mode=3D'capabilities' type=3D'net'> - <source> - <interface>eth0</interface> - </source> -</hostdev> -... -- -
hostdev
hostdev
element is the main container for descr=
ibing
- host devices. For block/character device passthrough mode is
- always "capabilities" and type
is "storage" for a blo=
ck
- device, "misc" for a character device and "net" for a host network
- interface.
-
source
- USB device redirection through a character device is - supported since after 0.9.5 (KVM - only): -
- --... -<devices> - <redirdev bus=3D'usb' type=3D'tcp'> - <source mode=3D'connect' host=3D'localhost' service=3D'4000'/> - <boot order=3D'1'/> - </redirdev> - <redirfilter> - <usbdev class=3D'0x08' vendor=3D'0x1234' product=3D'0xbeef' version= =3D'2.56' allow=3D'yes'/> - <usbdev allow=3D'no'/> - </redirfilter> -</devices> -...- -
redirdev
redirdev
element is the main container for
- describing redirected devices. bus
must be "usb"
- for a USB device.
-
- An additional attribute type
is required,
- matching one of the
- supported serial device types,
- to describe the host side of the
- tunnel; type=3D'tcp'
- or type=3D'spicevmc'
(which uses the usbredir
- channel of a SPICE graphics
- device) are typical. The redirdev element has an optional
- sub-element <address>
which can tie the
- device to a particular controller. Further sub-elements,
- such as <source>
, may be required according
- to the given type, although a <target>
sub-elem=
ent
- is not required (since the consumer of the character device is
- the hypervisor itself, rather than a device visible in the guest).
- boot
order
attribute determines the order in which
- devices will be tried during boot sequence. The per-device
- boot
elements cannot be used together with general
- boot elements in BIOS bootloader =
section.
- (Since 1.0.1)
- redirfilter
redirfilter
element is used for creating the
- filter rule to filter out certain devices from redirection.
- It uses sub-element <usbdev>
to define each fil=
ter rule.
- class
attribute is the USB Class code, for example,
- 0x08 represents mass storage devices. The USB device can be addres=
sed by
- vendor / product id using the vendor
and produc=
t
attributes.
- version
is the device revision from the bcdDevice fie=
ld (not
- the version of the USB protocol).
- These four attributes are optional and -1
can be used=
to allow
- any value for them. allow
attribute is mandatory,
- 'yes' means allow, 'no' for deny.
-
- A virtual smartcard device can be supplied to the guest via the
- smartcard
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. Since 0.8.8
-
-... -<devices> - <smartcard mode=3D'host'/> - <smartcard mode=3D'host-certificates'> - <certificate>cert1</certificate> - <certificate>cert2</certificate> - <certificate>cert3</certificate> - <database>/etc/pki/nssdb/</database> - </smartcard> - <smartcard mode=3D'passthrough' type=3D'tcp'> - <source mode=3D'bind' host=3D'127.0.0.1' service=3D'2001'/> - <protocol type=3D'raw'/> - <address type=3D'ccid' controller=3D'0' slot=3D'0'/> - </smartcard> - <smartcard mode=3D'passthrough' type=3D'spicevmc'/> -</devices> -... -- -
- The <smartcard>
element has a mandatory
- attribute mode
. 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.
-
host
<address>
sub-element.host-certificates
certutil -d /etc/pki/nssdb -x -t
- CT,CT,CT -S -s CN=3Dcert1 -n cert1
, and the resulting three
- certificate names must be supplied as the content of each of
- three <certificate>
sub-elements. An
- additional sub-element <database>
can specify
- the absolute path to an alternate directory (matching
- the -d
option of the certutil
command
- when creating the certificates); if not present, it defaults to
- /etc/pki/nssdb.passthrough
type
is required, matching one of the
- supported serial device types, to
- describe the host side of the tunnel; type=3D'tcp'
- or type=3D'spicevmc'
(which uses the smartcard
- channel of a SPICE graphics
- device) are typical. Further sub-elements, such
- as <source>
, may be required according to the
- given type, although a <target>
sub-element
- is not required (since the consumer of the character device is
- the hypervisor itself, rather than a device visible in the
- guest).
- Each mode supports an optional
- sub-element <address>
, which fine-tunes the
- correlation between the smartcard and a ccid bus
- controller, documented above.
- For now, qemu only supports at most one
- smartcard, with an address of bus=3D0 slot=3D0.
-
-... -<devices> - <interface type=3D'direct' trustGuestRxFilters=3D'yes'> - <source dev=3D'eth0'/> - <mac address=3D'52:54:00:5d:c7:9e'/> - <boot order=3D'1'/> - <rom bar=3D'off'/> - </interface> -</devices> -...- -
- There are several possibilities for specifying a network - interface visible to the guest. Each subsection below provides - more details about common setup options. -
-
- Since 1.2.10),
- the interface
element
- property trustGuestRxFilters
provides the
- capability for the host to detect and trust reports from the
- guest regarding changes to the interface mac address and receive
- filters by setting the attribute to yes
. The default
- setting for the attribute is no
for security
- reasons and support depends on the guest network device model as
- well as the type of connection on the host - currently it is
- only supported for the virtio device model and for macvtap
- connections on the host.
-
- Each <interface>
element has an
- optional <address>
sub-element that can tie
- the interface to a particular pci slot, with
- attribute type=3D'pci'
- as documented above.
-
- Since 6.6.0, one can force libvirt to k=
eep the
- provided MAC address when it's in the reserved VMware range by addin=
g a
- type=3D"static"
attribute to the <mac/> element.
- Note that this attribute is useless if the provided MAC address is o=
utside of
- the reserved VMWare ranges.
-
-
- 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 <network>
- definition Since 0.9.4).
-
-
-
- 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 <forward>
element given), NAT'ing to an
- explicit network device or to the default route
- (<forward mode=3D'nat'>
), routed with no NAT
- (<forward mode=3D'route'/>
), or connected
- directly to one of the host's network interfaces (via macvtap)
- or bridge devices ((<forward
- mode=3D'bridge|private|vepa|passthrough'/>
Since
- 0.9.4)
-
- 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
- 'virsh net-dumpxml [networkname]
'. 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 192.168.122.0/255.255.255.0
. Each guest will
- have an associated tun device created with a name of vnetN,
- which can also be overridden with the <target> element
- (see
- overriding the target elemen=
t).
-
- When the source of an interface is a network,
- a portgroup
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. Since 0.9.4.
-
- When a guest is running an interface of type network
- may include a portid
attribute. This provides the UUID
- of an associated virNetworkPortPtr object that records the associati=
on
- between the domain interface and the network. This attribute is
- read-only since port objects are create and deleted automatically
- during startup and shutdown. Since 5.1.0
-
- Also, similar to direct
network connections
- (described below), a connection of type network
may
- specify a virtualport
element, with configuration
- data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant
- switch (Since 0.8.2), or to an
- Open vSwitch virtual switch (Since
- 0.9.11).
-
- Since the actual type of switch may vary depending on the
- configuration in the <network>
on the host,
- it is acceptable to omit the virtualport type
- attribute, and specify attributes from multiple different
- virtualport types (and also to leave out certain attributes); at
- domain startup time, a complete <virtualport>
- element will be constructed by merging together the type and
- attributes defined in the network and the portgroup referenced
- by the interface. The newly-constructed virtualport is a combination
- of them. The attributes from lower virtualport can't make change
- on the ones defined in higher virtualport.
- Interface takes the highest priority, portgroup is lowest priority.
- (Since 0.10.0). For example, in order
- to work properly with both an 802.1Qbh switch and an Open vSwitch
- switch, you may choose to specify no type, but both
- a profileid
(in case the switch is 802.1Qbh) and
- an interfaceid
(in case the switch is Open vSwitch)
- (you may also omit the other attributes, such as managerid,
- typeid, or profileid, to be filled in from the
- network's <virtualport>
). If you want to
- limit a guest to connecting only to certain types of switches,
- you can specify the virtualport type, but still omit some/all of
- the parameters - in this case if the host's network has a
- different type of virtualport, connection of the interface will
- fail.
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - </interface> - ... - <interface type=3D'network'> - <source network=3D'default' portgroup=3D'engineering'/> - <target dev=3D'vnet7'/> - <mac address=3D"00:11:22:33:44:55"/> - <virtualport> - <parameters instanceid=3D'09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&= gt; - </virtualport> - </interface> -</devices> -...- -
- - This is the recommended config for general guest connectivity on - hosts with static wired networking configs. - -
- -- Provides a bridge from the VM directly to the LAN. This assumes - there is a bridge device on the host which has one or more of the ho= sts - physical NICs attached. The guest VM will have an associated tun dev= ice - created with a name of vnetN, which can also be overridden with the - <target> element (see - overriding the target elemen= t). - The tun device will be attached to the bridge. The IP range / network - configuration is whatever is used on the LAN. This provides the gues= t VM - full incoming & outgoing net access just like a physical machine. -
-
- On Linux systems, the bridge device is normally a standard Linux
- host bridge. On hosts that support Open vSwitch, it is also
- possible to connect to an Open vSwitch bridge device by adding
- a <virtualport type=3D'openvswitch'/>
to the
- interface definition. (Since
- 0.9.11). The Open vSwitch type virtualport accepts two
- parameters in its <parameters>
element -
- an interfaceid
which is a standard uuid used to
- uniquely identify this particular interface to Open vSwitch (if
- you do not specify one, a random interfaceid will be generated
- for you when you first define the interface), and an
- optional profileid
which is sent to Open vSwitch as
- the interfaces "port-profile".
-
-... -<devices> - ... - <interface type=3D'bridge'> - <source bridge=3D'br0'/> - </interface> - <interface type=3D'bridge'> - <source bridge=3D'br1'/> - <target dev=3D'vnet7'/> - <mac address=3D"00:11:22:33:44:55"/> - </interface> - <interface type=3D'bridge'> - <source bridge=3D'ovsbr'/> - <virtualport type=3D'openvswitch'> - <parameters profileid=3D'menial' interfaceid=3D'09b11c53-8b5c-4ee= b-8f00-d84eaa0aaa4f'/> - </virtualport> - </interface> - ... -</devices> -...- -
- On hosts that support Open vSwitch on the kernel side and have the
- Midonet Host Agent configured, it is also possible to connect to the
- 'midonet' bridge device by adding a
- <virtualport type=3D'midonet'/>
to the
- interface definition. (Since
- 1.2.13). The Midonet virtualport type requires an
- interfaceid
attribute in its
- <parameters>
element. This interface id is the UU=
ID
- that specifies which port in the virtual network topology will be bo=
und
- to the interface.
-
-... -<devices> - ... - <interface type=3D'bridge'> - <source bridge=3D'br0'/> - </interface> - <interface type=3D'bridge'> - <source bridge=3D'br1'/> - <target dev=3D'vnet7'/> - <mac address=3D"00:11:22:33:44:55"/> - </interface> - <interface type=3D'bridge'> - <source bridge=3D'midonet'/> - <virtualport type=3D'midonet'> - <parameters interfaceid=3D'0b2d64da-3d0e-431e-afdd-804415d6ebbb'/= > - </virtualport> - </interface> - ... -</devices> -...- -
- Provides a virtual LAN with NAT to the outside world. The virtual
- network has DHCP & DNS services and will give the guest VM addre=
sses
- starting from 10.0.2.15
. The default router will be
- 10.0.2.2
and the DNS server will be 10.0.2.3.
- This networking is the only option for unprivileged users who need t=
heir
- VMs to have outgoing access. Since 3.8.0
- it is possible to override the default network address by
- including an
ip
element specifying an IPv4
- address in its one mandatory attribute, address
.
- Optionally, a second ip
element with a
- family
attribute set to "ipv6" can be
- specified to add an IPv6 address to the interface.
- address
. Optionally, address
- prefix
can be specified.
-
-... -<devices> - <interface type=3D'user'/> - ... - <interface type=3D'user'> - <mac address=3D"00:11:22:33:44:55"/> - <ip family=3D'ipv4' address=3D'172.17.2.0' prefix=3D'24'/> - <ip family=3D'ipv6' address=3D'2001:db8:ac10:fd01::' prefix=3D'64'/= > - </interface> -</devices> -...- - -
- Provides a means to use a new or existing tap device (or veth - device pair, depening on the needs of the hypervisor driver) - that is partially or wholly setup external to libvirt (either - prior to the guest starting, or while the guest is being started - via an optional script specified in the config). -
-
- The name of the tap device can optionally be specified with
- the dev
attribute of the
- <target>
element. If no target dev is
- specified, libvirt will create a new standard tap device with a
- name of the pattern "vnetN", where "N" is replaced with a
- number. If a target dev is specified and that device doesn't
- exist, then a new standard tap device will be created with the
- exact dev name given. If the specified target dev does exist,
- then that existing device will be used. Usually some basic setup
- of the device is done by libvirt, including setting a MAC
- address, and the IFF_UP flag, but if the dev
is a
- pre-existing device, and the managed
attribute of
- the target
element is also set to "no" (the default
- value is "yes"), even this basic setup will not be performed -
- libvirt will simply pass the device on to the hypervisor with no
- setup at all. Since 5.7.0 Using
- managed=3D'no' with a pre-created tap device is useful because
- it permits a virtual machine managed by an unprivileged libvirtd
- to have emulated network devices based on tap devices.
-
- After creating/opening the tap device, an optional shell script
- (given in the path
attribute of
- the <script>
element) will be run.
- Since 0.2.1
- Also, after detaching/closing the tap device, an optional shell
- script (given in the path
attribute of
- the <downscript>
element) will be run.
- Since 5.1.0
- These can be used to do whatever extra host network integration is
- required.
-
-... -<devices> - <interface type=3D'ethernet'> - <script path=3D'/etc/qemu-ifup-mynet'/> - <downscript path=3D'/etc/qemu-ifdown-mynet'/> - </interface> - ... - <interface type=3D'ethernet'> - <target dev=3D'mytap1' managed=3D'no'/> - <model type=3D'virtio'/> - </interface> -</devices> -...- -
- Provides direct attachment of the virtual machine's NIC to the given
- physical interface of the host.
- Since 0.7.7 (QEMU and KVM only)
- This setup requires the Linux macvtap
- driver to be available. (Since Linux 2.6.34.)<=
/span>
- One of the modes 'vepa'
- (
- 'Virtual Ethernet Port Aggregator'), '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:
-
- If the model type is set to virtio
and
- interface's trustGuestRxFilters
attribute is set
- to yes
, changes made to the interface mac address,
- unicast/multicast receive filters, and vlan settings in the
- guest will be monitored and propagated to the associated macvtap
- device on the host (Since
- 1.2.10). If trustGuestRxFilters
is not set,
- or is not supported for the device model in use, an attempted
- change to the mac address originating from the guest side will
- result in a non-working network connection.
-
vepa
bridge
vepa
m=
ode,
- a VEPA capable bridge is required.private
private
mode.passthrough
-... -<devices> - ... - <interface type=3D'direct' trustGuestRxFilters=3D'no'> - <source dev=3D'eth0' mode=3D'vepa'/> - </interface> -</devices> -...- -
- 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. -
-- 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 det= ail - 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. Since 0.8.2 -
-- Please note that IEEE 802.1Qbg requires a non-zero value for the - VLAN ID. -
-managerid
typeid
typeidversion
instanceid
-... -<devices> - ... - <interface type=3D'direct'> - <source dev=3D'eth0.2' mode=3D'vepa'/> - <virtualport type=3D"802.1Qbg"> - <parameters managerid=3D"11" typeid=3D"1193047" typeidversion=3D"= 2" instanceid=3D"09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/> - </virtualport> - </interface> -</devices> -...- -
- 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. Since 0.8.2 -
-profileid
-... -<devices> - ... - <interface type=3D'direct'> - <source dev=3D'eth0' mode=3D'private'/> - <virtualport type=3D'802.1Qbh'> - <parameters profileid=3D'finance'/> - </virtualport> - </interface> -</devices> -... -- - -
- A PCI network device (specified by the <source> element) - is directly assigned to the guest using generic device - passthrough, after first optionally setting the device's MAC - address to the configured value, and associating the device with - an 802.1Qbh capable switch using an optionally specified - <virtualport> element (see the examples of virtualport - given above for type=3D'direct' network devices). Note that - due - to limitations in standard single-port PCI ethernet card driver - design - only SR-IOV (Single Root I/O Virtualization) virtual - function (VF) devices can be assigned in this manner; to assign - a standard single-port PCI or PCIe ethernet card to a guest, use - the traditional <hostdev> device definition and - Since 0.9.11 -
- -
- To use VFIO device assignment rather than traditional/legacy KVM
- device assignment (VFIO is a new method of device assignment
- that is compatible with UEFI Secure Boot), a type=3D'hostdev'
- interface can have an optional driver
sub-element
- with a name
attribute set to "vfio". To use legacy
- KVM device assignment you can set name
to "kvm" (or
- simply omit the <driver>
element, since "kvm"
- is currently the default).
- Since 1.0.5 (QEMU and KVM only, requires kerne=
l 3.6 or newer)
-
- Note that this "intelligent passthrough" of network devices is - very similar to the functionality of a standard <hostdev> - device, the difference being that this method allows specifying - a MAC address and <virtualport> for the passed-through - device. If these capabilities are not required, if you have a - standard single-port PCI, PCIe, or USB network card that doesn't - support SR-IOV (and hence would anyway lose the configured MAC - address during reset after being assigned to the guest domain), - or if you are using a version of libvirt older than 0.9.11, you - should use standard <hostdev> to assign the device to the - guest instead of <interface type=3D'hostdev'/>. -
- -
- Similar to the functionality of a standard <hostdev> device,
- when managed
is "yes", it is detached from the host
- before being passed on to the guest, and reattached to the host
- after the guest exits. If managed
is omitted or "no",
- the user is responsible to call virNodeDeviceDettach
- (or virsh nodedev-detach
) before starting the guest
- or hot-plugging the device, and virNodeDeviceReAttach
- (or virsh nodedev-reattach
) after hot-unplug or
- stopping the guest.
-
-... -<devices> - <interface type=3D'hostdev' managed=3D'yes'> - <driver name=3D'vfio'/> - <source> - <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x07= ' function=3D'0x0'/> - </source> - <mac address=3D'52:54:00:6d:90:02'/> - <virtualport type=3D'802.1Qbh'> - <parameters profileid=3D'finance'/> - </virtualport> - </interface> -</devices> -...- -
- Since 6.1.0 (QEMU and KVM only, requires
- QEMU 4.2.0 or newer and a guest virtio-net driver supporting
- the "failover" feature, such as the one included in Linux
- kernel 4.18 and newer)
-
- The <teaming>
element of two interfaces can
- be used to connect them as a team/bond device in the guest
- (assuming proper support in the hypervisor and the guest
- network driver).
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'mybridge'/> - <mac address=3D'00:11:22:33:44:55'/> - <model type=3D'virtio'/> - <teaming type=3D'persistent'/> - <alias name=3D'ua-backup0'/> - </interface> - <interface type=3D'network'> - <source network=3D'hostdev-pool'/> - <mac address=3D'00:11:22:33:44:55'/> - <model type=3D'virtio'/> - <teaming type=3D'transient' persistent=3D'ua-backup0'/> - </interface> -</devices> -...- -
- The <teaming>
element required
- attribute type
will be set to
- either "persistent"
to indicate a device that
- should always be present in the domain,
- or "transient"
to indicate a device that may
- periodically be removed, then later re-added to the domain. When
- type=3D"transient", there should be a second attribute
- to <teaming>
called "persistent"
- - this attribute should be set to the alias name of the other
- device in the pair (the one that has <teaming
- type=3D"persistent'/>
).
-
- In the particular case of QEMU,
- libvirt's <teaming>
element is used to setup
- a virtio-net "failover" device pair. For this setup, the
- persistent device must be an interface with <model
- type=3D"virtio"/>
, and the transient device must
- be <interface type=3D'hostdev'/>
- (or <interface type=3D'network'/>
where the
- referenced network defines a pool of SRIOV VFs). The guest will
- then have a simple network team/bond device made of the virtio
- NIC + hostdev NIC pair. In this configuration, the
- higher-performing hostdev NIC will normally be preferred for all
- network traffic, but when the domain is migrated, QEMU will
- automatically unplug the VF from the guest, and then hotplug a
- similar device once migration is completed; while migration is
- taking place, network traffic will use the virtio NIC. (Of
- course the emulated virtio NIC and the hostdev NIC must be
- connected to the same subnet for bonding to work properly).
-
- NB1: Since you must know the alias name of the virtio NIC when - configuring the hostdev NIC, it will need to be manually set in - the virtio NIC's configuration (as with all other manually set - alias names, this means it must start with "ua-"). -
-- NB2: Currently the only implementation of the guest OS - virtio-net driver supporting virtio-net failover requires that - the MAC addresses of the virtio and hostdev NIC must - match. Since that may not always be a requirement in the future, - libvirt doesn't enforce this limitation - it is up to the - person/management application that is creating the configuration - to assure the MAC addresses of the two devices match. -
-
- NB3: Since the PCI addresses of the SRIOV VFs on the hosts that
- are the source and destination of the migration will almost
- certainly be different, either higher level management software
- will need to modify the <source>
of the
- hostdev NIC (<interface type=3D'hostdev'>
) at
- the start of migration, or (a simpler solution) the
- configuration will need to use a libvirt "hostdev" virtual
- network that maintains a pool of such devices, as is implied in
- the example's use of the libvirt network named "hostdev-pool" -
- as long as the hostdev network pools on both hosts have the same
- name, libvirt itself will take care of allocating an appropriate
- device on both ends of the migration. Similarly the XML for the
- virtio interface must also either work correctly unmodified on
- both the source and destination of the migration (e.g. by
- connecting to the same bridge device on both hosts, or by using
- the same virtual network), or the management software must
- properly modify the interface XML during migration so that the
- virtio device remains connected to the same network segment
- before and after migration.
-
- A multicast group is setup to represent a virtual network. Any VMs - whose network devices are in the same multicast group can talk to ea= ch - other even across hosts. This mode is also available to unprivileged - users. There is no default DNS or DHCP support and no outgoing netwo= rk - access. To provide outgoing network access, one of the VMs should ha= ve a - 2nd NIC which is connected to one of the first 4 network types and d= o 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. -
- --... -<devices> - <interface type=3D'mcast'> - <mac address=3D'52:54:00:6d:90:01'/> - <source address=3D'230.0.0.1' port=3D'5558'/> - </interface> -</devices> -...- -
- 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 serve= r. - This mode is also available to unprivileged users. There is no defau= lt - DNS or DHCP support and no outgoing network access. To provide outgo= ing - network access, one of the VMs should have a 2nd NIC which is connec= ted - to one of the first 4 network types and do the appropriate routing.<= /p> - -
-... -<devices> - <interface type=3D'server'> - <mac address=3D'52:54:00:22:c9:42'/> - <source address=3D'192.168.0.1' port=3D'5558'/> - </interface> - ... - <interface type=3D'client'> - <mac address=3D'52:54:00:8b:c9:51'/> - <source address=3D'192.168.0.1' port=3D'5558'/> - </interface> -</devices> -...- -
- A UDP unicast architecture provides a virtual network which enables - connections between QEMU instances using QEMU's UDP infrastructure. - - The xml "source" address is the endpoint address to which the UDP sock= et - packets will be sent from the host running QEMU. - The xml "local" address is the address of the interface from which the - UDP socket packets will originate from the QEMU host. - Since 1.2.20
- --... -<devices> - <interface type=3D'udp'> - <mac address=3D'52:54:00:22:c9:42'/> - <source address=3D'127.0.0.1' port=3D'11115'> - <local address=3D'127.0.0.1' port=3D'11116'/> - </source> - </interface> -</devices> -...- -
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet1'/> - <model type=3D'ne2k_pci'/> - </interface> -</devices> -...- -
- For hypervisors which support this, you can set the model of - emulated network interface card. -
- -
- The values for type
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:
-
-qemu -net nic,model=3D? /dev/null -qemu-kvm -net nic,model=3D? /dev/null -- -
- Typical values for QEMU and KVM include:
- ne2k_isa i82551 i82557b i82559er ne2k_pci pcnet rtl8139 e1000 virtio.
- Since 5.2.0, virtio-transitional<=
/code>
- and
virtio-non-transitional
values are supported.
- See Virtio transitional devi=
ces
- for more details.
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet1'/> - <model type=3D'virtio'/> - <driver name=3D'vhost' txmode=3D'iothread' ioeventfd=3D'on' even= t_idx=3D'off' queues=3D'5' rx_queue_size=3D'256' tx_queue_size=3D'256'> - <host csum=3D'off' gso=3D'off' tso4=3D'off' tso6=3D'off' ecn=3D'o= ff' ufo=3D'off' mrg_rxbuf=3D'off'/> - <guest csum=3D'off' tso4=3D'off' tso6=3D'off' ecn=3D'off' ufo=3D'= off'/> - </driver> - </interface> -</devices> -...- -
- Some NICs may have tunable driver-specific options. These are
- set as attributes of the driver
sub-element of the
- interface definition. Currently the following attributes are
- available for the "virtio"
NIC driver:
-
name
name
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.
- Since 0.8.8 (QEMU and KVM only)
- name
attribute can optionally be set to
- "vfio" or "kvm". "vfio" tells libvirt to use VFIO device
- assignment rather than traditional KVM device assignment (VFIO
- is a new method of device assignment that is compatible with
- UEFI Secure Boot), and "kvm" tells libvirt to use the legacy
- device assignment performed directly by the kvm kernel module
- (the default is currently "kvm", but is subject to change).
- Since 1.0.5 (QEMU and KVM only, requires
- kernel 3.6 or newer)
- name
- attribute is ignored. The backend driver used is always
- vhost-user.
- txmode
txmode
attribute specifies how to handle
- transmission of packets when the transmit buffer is full. The
- value can be either 'iothread' or 'timer'.
- Since 0.8.8 (QEMU and KVM only)ioeventfd
event_idx
event_idx
attribute controls some aspects of
- device event processing. The value can be either 'on' or 'off'
- - if it is on, it will reduce the number of interrupts and
- exits for the guest. The default is determined by QEMU;
- usually if the feature is supported, default is on. In case
- there is a situation where this behavior is suboptimal, this
- attribute provides a way to force the feature off.
- Since 0.9.5 (QEMU and KVM only)queues
queues
attribute controls the number
- of queues to be used for either
- Multiqueue
- virtio-net or vhost-user net=
work
- interfaces. Use of multiple packet processing queues requires the
- interface having the <model type=3D'virtio'/>
- element. Each queue will potentially be handled by a different
- processor, resulting in much higher throughput.
- virtio-net since 1.0.6 (QEMU and KVM only)=
span>
- vhost-user since 1.2.17 (QEMU and KVM only)<=
/span>
- rx_queue_size
rx_queue_size
attribute controls
- the size of virtio ring for each queue as described above.
- The default value is hypervisor dependent and may change
- across its releases. Moreover, some hypervisors may pose
- some restrictions on actual value. For instance, latest
- QEMU (as of 2016-09-01) requires value to be a power of two
- from [256, 1024] range.
- Since 2.3.0 (QEMU and KVM only)tx_queue_size
tx_queue_size
attribute controls
- the size of virtio ring for each queue as described above.
- The default value is hypervisor dependent and may change
- across its releases. Moreover, some hypervisors may pose
- some restrictions on actual value. For instance, QEMU
- v2.9 requires value to be a power of two from [256, 1024]
- range. In addition to that, this may work only for a subset of
- interface types, e.g. aforementioned QEMU enables this option
- only for vhostuser
type.
- Since 3.7.0 (QEMU and KVM only)- Offloading options for the host and guest can be configured using - the following sub-elements: -
-host
csum
, gso
, tso4
,
- tso6
, ecn
and ufo
- attributes with possible values on
- and off
can be used to turn off host offloading optio=
ns.
- By default, the supported offloads are enabled by QEMU.
- Since 1.2.9 (QEMU only)
- The mrg_rxbuf
attribute can be used to control
- mergeable rx buffers on the host side. Possible values are
- on
(default) and off
.
- Since 1.2.13 (QEMU only)
- guest
csum
, tso4
,
- tso6
, ecn
and ufo
- attributes with possible values on
- and off
can be used to turn off guest offloading opti=
ons.
- By default, the supported offloads are enabled by QEMU.
- Since 1.2.9 (QEMU only)
- -... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet1'/> - <model type=3D'virtio'/> - <backend tap=3D'/dev/net/tun' vhost=3D'/dev/vhost-net'/> - <driver name=3D'vhost' txmode=3D'iothread' ioeventfd=3D'on' event_i= dx=3D'off' queues=3D'5'/> - <tune> - <sndbuf>1600</sndbuf> - </tune> - </interface> -</devices> -...- -
- For tuning the backend of the network, the backend
elem=
ent
- can be used. The vhost
attribute can override the defau=
lt vhost
- device path (/dev/vhost-net
) for devices with vir=
tio
model.
- The tap
attribute overrides the tun/tap device path (de=
fault:
- /dev/net/tun
) for network and bridge interfaces. This d=
oes not work
- in session mode. Since 1.2.9
-
- For tap devices there is also sndbuf
element which can
- adjust the size of send buffer in the host. Si=
nce
- 0.8.8
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet1'/> - </interface> -</devices> -...- -
- If no target is specified, certain hypervisors will - automatically generate a name for the created tun device. This - name can be manually specified, however the name should not - start with either 'vnet', 'vif', 'macvtap', or 'macvlan', - which are prefixes reserved by libvirt and certain hypervisors. - Manually specified targets using these prefixes may be ignored. -
- -
- Note that for LXC containers, this defines the name of the interface
- on the host side. Since 1.2.7, to define
- the name of the device on the guest side, the guest
- element should be used, as in the following snippet:
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <guest dev=3D'myeth'/> - </interface> -</devices> -...- -
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet1'/> - <boot order=3D'1'/> - </interface> -</devices> -...- -
- For hypervisors which support this, you can set a specific NIC to
- be used for network boot. The order
attribute determines
- the order in which devices will be tried during boot sequence. The
- per-device boot
elements cannot be used together with
- general boot elements in
- BIOS bootloader section.
- Since 0.8.8
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet1'/> - <rom bar=3D'on' file=3D'/etc/fake/boot.bin'/> - </interface> -</devices> -...- -
- For hypervisors which support this, you can change how a PCI Network
- device's ROM is presented to the guest. The bar
- attribute can be set to "on" or "off", and determines whether
- or not the device's ROM will be visible in the guest's memory
- map. (In PCI documentation, the "rombar" setting controls the
- presence of the Base Address Register for the ROM). If no rom
- bar is specified, the qemu default will be used (older
- versions of qemu used a default of "off", while newer qemus
- have a default of "on").
- The optional file
attribute is used to point to a
- binary file to be presented to the guest as the device's ROM
- BIOS. This can be useful to provide an alternative boot ROM for a
- network device.
- Since 0.9.10 (QEMU and KVM only).
-
-... -<devices> - ... - <interface type=3D'bridge'> - <source bridge=3D'br0'/> - <backenddomain name=3D'netvm'/> - </interface> - ... -</devices> -...- -
- The optional backenddomain
element allows specifying a
- backend domain (aka driver domain) for the interface. Use the
- name
attribute to specify the backend domain name. You
- can use it to create a direct network link between domains (so data
- will not go through host system). Use with type 'ethernet' to create
- plain network link, or with type 'bridge' to connect to a bridge ins=
ide
- the backend domain.
- Since 1.2.13 (Xen only)
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet0'/> - <bandwidth> - <inbound average=3D'1000' peak=3D'5000' floor=3D'200' burst=3D'10= 24'/> - <outbound average=3D'128' peak=3D'256' burst=3D'256'/> - </bandwidth> - </interface> -</devices> -...- -
- This part of interface XML provides setting quality of service. Inco=
ming
- and outgoing traffic can be shaped independently.
- The bandwidth
element and its child elements are descri=
bed
- in the QoS section of
- the Network XML.
-
-... -<devices> - <interface type=3D'bridge'> - <vlan> - <tag id=3D'42'/> - </vlan> - <source bridge=3D'ovsbr0'/> - <virtualport type=3D'openvswitch'> - <parameters interfaceid=3D'09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/= > - </virtualport> - </interface> - <interface type=3D'bridge'> - <vlan trunk=3D'yes'> - <tag id=3D'42'/> - <tag id=3D'123' nativeMode=3D'untagged'/> - </vlan> - ... - </interface> -</devices> -...- -
- If (and only if) the network connection used by the guest
- supports VLAN tagging transparent to the guest, an
- optional <vlan>
element can specify one or
- more VLAN tags to apply to the guest's network
- traffic Since 0.10.0. Network
- connections that support guest-transparent VLAN tagging include
- 1) type=3D'bridge' interfaces connected to an Open vSwitch bridge
- Since 0.10.0, 2) SRIOV Virtual
- Functions (VF) used via type=3D'hostdev' (direct device
- assignment) Since 0.10.0, and 3)
- SRIOV VFs used via type=3D'direct' with mode=3D'passthrough'
- (macvtap "passthru" mode) Since
- 1.3.5. All other connection types, including standard
- linux bridges and libvirt's own virtual networks, do not
- support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
- provide their own way (outside of libvirt) to tag guest traffic
- onto a specific VLAN. Each tag is given in a
- separate <tag>
subelement
- of <vlan>
(for example: <tag
- id=3D'42'/>
). For VLAN trunking of multiple tags (which
- is supported only on Open vSwitch connections),
- multiple <tag>
subelements can be specified,
- which implies that the user wants to do VLAN trunking on the
- interface for all the specified tags. In the case that VLAN
- trunking of a single tag is desired, the optional
- attribute trunk=3D'yes'
can be added to the toplevel
- <vlan>
element to differentiate trunking of a
- single tag from normal tagging.
-
- For network connections using Open vSwitch it is also possible
- to configure 'native-tagged' and 'native-untagged' VLAN modes
- Since 1.1.0. This is done with the
- optional nativeMode
attribute on
- the <tag>
subelement: nativeMode
- may be set to 'tagged' or 'untagged'. The id
- attribute of the <tag>
subelement
- containing nativeMode
sets which VLAN is considered
- to be the "native" VLAN for this interface, and
- the nativeMode
attribute determines whether or not
- traffic for that VLAN will be tagged.
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <port isolated=3D'yes'/> - </interface> -</devices> -...- -
- Since 6.1.0. The port
- element property isolated
, when set
- to yes
(default setting is no
) is used
- to isolate this interface's network traffic from that of other
- guest interfaces connected to the same network that also
- have <port isolated=3D'yes'/>
. This setting is
- only supported for emulated interface devices that use a
- standard tap device to connect to the network via a Linux host
- bridge. This property can be inherited from a libvirt network,
- so if all guests that will be connected to the network should be
- isolated, it is better to put the setting in the network
- configuration. (NB: this only prevents guests that
- have isolated=3D'yes'
from communicating with each
- other; if there is a guest on the same bridge that doesn't
- have isolated=3D'yes'
, even the isolated guests will
- be able to communicate with it.)
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet0'/> - <link state=3D'down'/> - </interface> -</devices> -...- -
- This element provides means of setting state of the virtual network =
link.
- Possible values for attribute state
are up
=
and
- down
. If down
is specified as the value, t=
he interface
- behaves as if it had the network cable disconnected. Default behavio=
r if this
- element is unspecified is to have the link state up
.
- Since 0.9.5
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet0'/> - <mtu size=3D'1500'/> - </interface> -</devices> -...- -
- This element provides means of setting MTU of the virtual network li=
nk.
- Currently there is just one attribute size
which accept=
s a
- non-negative integer which specifies the MTU size for the interface.
- Since 3.1.0
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet0'/> - <coalesce> - <rx> - <frames max=3D'7'/> - </rx> - </coalesce> - </interface> -</devices> -...- -
- This element provides means of setting coalesce settings for
- some interface devices (currently only type network
- and bridge
. Currently there is just one attribute,
- max
, to tweak, in element frames
for
- the rx
group, which accepts a non-negative integer
- that specifies the maximum number of packets that will be
- received before an interrupt.
- Since 3.3.0
-
-... -<devices> - <interface type=3D'network'> - <source network=3D'default'/> - <target dev=3D'vnet0'/> - <ip address=3D'192.168.122.5' prefix=3D'24'/> - <ip address=3D'192.168.122.5' prefix=3D'24' peer=3D'10.0.0.10'/&= gt; - <route family=3D'ipv4' address=3D'192.168.122.0' prefix=3D'24' g= ateway=3D'192.168.122.1'/> - <route family=3D'ipv4' address=3D'192.168.122.8' gateway=3D'192.= 168.122.1'/> - </interface> - ... - <hostdev mode=3D'capabilities' type=3D'net'> - <source> - <interface>eth0</interface> - </source> - <ip address=3D'192.168.122.6' prefix=3D'24'/> - <route family=3D'ipv4' address=3D'192.168.122.0' prefix=3D'24' g= ateway=3D'192.168.122.1'/> - <route family=3D'ipv4' address=3D'192.168.122.8' gateway=3D'192.= 168.122.1'/> - </hostdev> - ... -</devices> -... -- -
- Since 1.2.12 network devices and
- hostdev devices with network capabilities can optionally be provided
- one or more IP addresses to set on the network device in the
- guest. Note that some hypervisors or network device types will
- simply ignore them or only use the first one.
- The family
attribute can be set to
- either ipv4
or ipv6
, and the
- address
attribute contains the IP address. The
- optional prefix
is the number of 1 bits in the
- netmask, and will be automatically set if not specified - for
- IPv4 the default prefix is determined according to the network
- "class" (A, B, or C - see RFC870), and for IPv6 the default
- prefix is 64. The optional peer
attribute holds the
- IP address of the other end of a point-to-point network
- device (since 2.1.0).
-
- Since 1.2.12 route elements can also be
- added to define IP routes to add in the guest. The attributes of
- this element are described in the documentation for
- the route
element
- in network
- definitions. This is used by the LXC driver.
-
-... -<devices> - <interface type=3D'ethernet'> - <source/> - <ip address=3D'192.168.123.1' prefix=3D'24'/> - <ip address=3D'10.0.0.10' prefix=3D'24' peer=3D'192.168.122.5'= /> - <route family=3D'ipv4' address=3D'192.168.42.0' prefix=3D'24' = gateway=3D'192.168.123.4'/> - <source/> - ... - </interface> - ... -</devices> -... -- -
- Since 2.1.0 network devices of type
- "ethernet" can optionally be provided one or more IP addresses
- and one or more routes to set on the host side of the
- network device. These are configured as subelements of
- the <source>
element of the interface, and
- have the same attributes as the similarly named elements used to
- configure the guest side of the interface (described above).
-
- Since 1.2.7 the vhost-user enables the - communication between a QEMU virtual machine and other userspace proce= ss - using the Virtio transport protocol. A char dev (e.g. Unix socket) is= used - for the control plane, while the data plane is based on shared memory. -
- --... -<devices> - <interface type=3D'vhostuser'> - <mac address=3D'52:54:00:3b:83:1a'/> - <source type=3D'unix' path=3D'/tmp/vhost1.sock' mode=3D'server'/> - <model type=3D'virtio'/> - </interface> - <interface type=3D'vhostuser'> - <mac address=3D'52:54:00:3b:83:1b'/> - <source type=3D'unix' path=3D'/tmp/vhost2.sock' mode=3D'client'> - <reconnect enabled=3D'yes' timeout=3D'10'/> - </source> - <model type=3D'virtio'/> - <driver queues=3D'5'/> - </interface> -</devices> -...- -
- The <source>
element has to be specified
- along with the type of char device.
- Currently, only type=3D'unix' is supported, where the path (the
- directory path of the socket) and mode attributes are required.
- Both mode=3D'server'
and mode=3D'client'
- are supported.
- vhost-user requires the virtio model type, thus the
- <model>
element is mandatory.
- Since 4.1.0 the element has an
- optional child element reconnect
which
- configures reconnect timeout if the connection is lost. It
- has two attributes enabled
(which accepts
- yes
and no
) and
- timeout
which specifies the amount of seconds
- after which hypervisor tries to reconnect.
-
- Since 0.8.0 an nwfilter
prof=
ile
- can be assigned to a domain interface, which allows configuring
- traffic filter rules for the virtual machine.
-
- See the nwfilter documentation for=
more
- complete details.
-
-... -<devices> - <interface ...> - ... - <filterref filter=3D'clean-traffic'/> - </interface> - <interface ...> - ... - <filterref filter=3D'myfilter'> - <parameter name=3D'IP' value=3D'104.207.129.11'/> - <parameter name=3D'IP6_ADDR' value=3D'2001:19f0:300:2102::'/> - <parameter name=3D'IP6_MASK' value=3D'64'/> - ... - </filterref> - </interface> -</devices> -...- -
- The filter
attribute specifies the name of the nwfilter
- to use. Optional <parameter>
elements may be
- specified for passing additional info to the nwfilter via the
- name
and value
attributes. See
- the nwfilter
- docs for info on parameters.
-
- 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. -
- --... -<devices> - <input type=3D'mouse' bus=3D'usb'/> - <input type=3D'keyboard' bus=3D'usb'/> - <input type=3D'mouse' bus=3D'virtio'/> - <input type=3D'keyboard' bus=3D'virtio'/> - <input type=3D'tablet' bus=3D'virtio'/> - <input type=3D'passthrough' bus=3D'virtio'> - <source evdev=3D'/dev/input/event1'/> - </input> -</devices> -...- -
input
input
element has one mandatory attribute,
- the type
whose value can be 'mouse', 'tablet',
- (since 1.2.2) 'keyboard' or
- (since 1.3.0) 'passthrough'.
- The tablet provides absolute cursor movement,
- while the mouse uses relative movement. The optional
- bus
attribute can be used to refine the exact device =
type.
- It takes values "xen" (paravirtualized), "ps2" and "usb" or
- (since 1.3.0) "virtio".
- The input
element has an optional
- sub-element <address>
which can tie the
- device to a particular PCI
- slot, documented above.
- On S390, address
can be used to provide a CCW address f=
or
- an input device (since 4.2.0).
-
- For type passthrough
, the mandatory sub-element s=
ource
- must have an evdev
attribute containing the absolute pa=
th to the
- event device passed through to guests. (KVM only)
-
- Since 5.2.0, the input
ele=
ment
- accepts a model
attribute which has the values 'virtio',
- 'virtio-transitional' and 'virtio-non-transitional'. See
- Virtio transitional devices<=
/a>
- for more details.
-
- The subelement driver
can be used to tune the virtio
- options of the device:
- Virtio-specific options can also be
- set. (Since 3.5.0)
-
- A hub is a device that expands a single port into several so - that there are more ports available to connect devices to a host - system. -
- --... -<devices> - <hub type=3D'usb'/> -</devices> -...- -
hub
hub
element has one mandatory attribute,
- the type
whose value can only be 'usb'.
- The hub
element has an optional
- sub-element <address>
- with type=3D'usb'
which can tie the device to a
- particular controller, documented
- above.
-
- 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. -
- --... -<devices> - <graphics type=3D'sdl' display=3D':0.0'/> - <graphics type=3D'vnc' port=3D'5904' sharePolicy=3D'allow-exclusive'&= gt; - <listen type=3D'address' address=3D'1.2.3.4'/> - </graphics> - <graphics type=3D'rdp' autoport=3D'yes' multiUser=3D'yes' /> - <graphics type=3D'desktop' fullscreen=3D'yes'/> - <graphics type=3D'spice'> - <listen type=3D'network' network=3D'rednet'/> - </graphics> -</devices> -...- -
graphics
- The graphics
element has a mandatory type
- attribute which takes the value
sdl
, vnc,
-
spice
, rdp
, desktop
or
- egl-headless
:
-
sdl
- This displays a window on the host desktop, it can take 3 op=
tional
- arguments: a display
attribute for the display =
to use,
- an xauth
attribute for the authentication ident=
ifier,
- and an optional fullscreen
attribute accepting =
values
- yes
or no
.
-
- You can use a gl
with the enable=3D"yes"<=
/code>
- property to enable OpenGL support in SDL. Likewise you can
- explicitly disable OpenGL support with
enable=3D"no"=
code>.
-
vnc
- Starts a VNC server. The port
attribute specifi=
es
- the TCP port number (with -1 as legacy syntax indicating tha=
t it
- should be auto-allocated). The autoport
attribu=
te is
- the new preferred syntax for indicating auto-allocation of t=
he TCP
- port to use. The passwd
attribute provides a VNC
- password in clear text. If the passwd
attribute=
is
- set to an empty string, then VNC access is disabled. The
- keymap
attribute specifies the keymap to use. I=
t is
- possible to set a limit on the validity of the password by g=
iving
- a timestamp passwdValidTo=3D'2010-04-09T15:51:00'
- assumed to be in UTC. The
connected
attribute a=
llows
- control of connected client during password changes. VNC acc=
epts
- keep
value only since 0.9=
.3.
- NB, this may not be supported by all hypervisors.
-
- The optional sharePolicy
attribute specifies vnc
- server display sharing policy. allow-exclusive
=
allows
- clients to ask for exclusive access by dropping other connec=
tions.
- Connecting multiple clients in parallel requires all clients=
asking
- for a shared session (vncviewer: -Shared switch). This is
- the default value. force-shared
disables exclus=
ive
- client access, every connection has to specify -Shared switc=
h for
- vncviewer. ignore
welcomes every connection
- unconditionally since 1.0.6.
-
- Rather than using listen/port, QEMU supports a socket<=
/code>
- attribute for listening on a unix domain socket path
- Since 0.8.8.
-
- For VNC WebSocket functionality, websocket
attr=
ibute
- may be used to specify port to listen on (with -1 meaning
- auto-allocation and autoport
having no effect d=
ue to
- security reasons) Since 1.0.6.
-
- Although VNC doesn't support OpenGL natively, it can be pair=
ed
- with graphics type egl-headless
(see below) whi=
ch
- will instruct QEMU to open and use drm nodes for OpenGL rend=
ering.
-
spice
Since 0.8.6<=
/dt>
-
- Starts a SPICE server. The port
attribute speci=
fies
- the TCP port number (with -1 as legacy syntax indicating tha=
t it
- should be auto-allocated), while tlsPort
gives
- an alternative secure port number. The autoport
- attribute is the new preferred syntax for indicating
- auto-allocation of needed port numbers. The passwd
- attribute provides a SPICE password in clear text. If the
-
passwd
attribute is set to an empty string, then
- SPICE access is disabled. The keymap
attribute
- specifies the keymap to use. It is possible to set a limit on
- the validity of the password by giving a timestamp
- passwdValidTo=3D'2010-04-09T15:51:00'
assumed t=
o be
- in UTC.
-
- The connected
attribute allows control of conne=
cted
- client during password changes. SPICE accepts keep to
- keep client connected,
disconnect
to disconnect=
client
- and fail
to fail changing password . NB, this m=
ay not
- be supported by all hypervisors.
- Since 0.9.3
-
- The defaultMode
attribute sets the default chan=
nel
- security policy, valid values are secure
,
- insecure
and the default any
(whic=
h is
- secure if possible, but falls back to insecure rather than e=
rroring
- out if no secure path is available).
- Since 0.9.12
-
- When SPICE has both a normal and TLS secured TCP port config=
ured,
- it can be desirable to restrict what channels can be run on =
each
- port. This is achieved by adding one or more <chann=
el>
-
elements inside the main <graphics>
- element and setting the
mode
attribute to either
- secure
or insecure
. Setting the mo=
de
- attribute overrides the default value as set by
- the defaultMode
attribute. (Note that specifying
- any
as mode discards the entry as the channel w=
ould
- inherit the default mode anyways.) Valid channel names inclu=
de
- main
, display
, inputs
,
- cursor
, playback
, record
- (all since 0.8.6);
-
smartcard
(since 0.8.8);
- and usbredir
(since 0.9.1=
2).
-
-<graphics type=3D'spice' port=3D'-1' tlsPort=3D'-1' autoport=3D'yes'> - <channel name=3D'main' mode=3D'secure'/> - <channel name=3D'record' mode=3D'insecure'/> - <image compression=3D'auto_glz'/> - <streaming mode=3D'filter'/> - <clipboard copypaste=3D'no'/> - <mouse mode=3D'client'/> - <filetransfer enable=3D'no'/> - <gl enable=3D'yes' rendernode=3D'/dev/dri/by-path/pci-0000:00:02.0-re= nder'/> -</graphics>-
- Spice supports variable compression settings for audio, imag=
es and
- streaming. These settings are accessible via the compr=
ession
-
attribute in all following elements: image to
- set image compression (accepts
auto_glz
,
- auto_lz
, quic
, glz
,
- lz
, off
), jpeg
for JP=
EG
- compression for images over wan (accepts auto
,
- never
, always
), zlib
=
for
- configuring wan image compression (accepts auto
,
- never
, always
) and playback=
- for enabling audio stream compression (accepts on or
-
off
). Since 0.9.1
-
- Streaming mode is set by the streaming
element,
- settings its mode
attribute to one of
- filter
, all
or off
.
- Since 0.9.2
-
- Copy & Paste functionality (via Spice agent) is set by t=
he
- clipboard
element. It is enabled by default, an=
d can
- be disabled by setting the copypaste
property to
- no
. Since 0.9.3
-
- Mouse mode is set by the mouse
element, setting=
its
- mode
attribute to one of server
or
- client
. If no mode is specified, the qemu defau=
lt will
- be used (client mode). Since 0.9.11
-
- File transfer functionality (via Spice agent) is set using t=
he
- filetransfer
element. It is enabled by default,=
and
- can be disabled by setting the enable
property =
to
- no
. Since 1.2.2
-
- Spice may provide accelerated server-side rendering with Ope=
nGL.
- You can enable or disable OpenGL support explicitly with
- the gl
element, by setting the enable
- property. (QEMU only, since 1.3.3).
- Note that this only works locally, since this requires usage=
of
- UNIX sockets, i.e. using
listen
types 'socket' =
or
- 'none'. For accelerated OpenGL with remote support, consider
- pairing this element with type egl-headless
- (see below). However, this will deliver weaker performance
- compared to native Spice OpenGL support.
-
- By default, QEMU will pick the first available GPU DRM rende= r node. - You may specify a DRM render node path to use instead. (QEMU= only, - since 3.1.0). -
-rdp
- Starts a RDP server. The port
attribute specifi=
es the
- TCP port number (with -1 as legacy syntax indicating that it=
should
- be auto-allocated). The autoport
attribute is t=
he new
- preferred syntax for indicating auto-allocation of the TCP p=
ort to
- use. In the VirtualBox driver, the autoport
wil=
l make
- the hypervisor pick available port from 3389-3689 range when=
the VM
- is started. The chosen port will be reflected in the p=
ort
- attribute. The multiUser
attribute is a boolean=
deciding
- whether multiple simultaneous connections to the VM are perm=
itted.
- The replaceUser
attribute is a boolean deciding=
whether
- the existing connection must be dropped and a new connection=
must
- be established by the VRDP server, when a new client connect=
s in
- single connection mode.
-
desktop
- This value is reserved for VirtualBox domains for the moment=
. It
- displays a window on the host desktop, similarly to "sdl", b=
ut
- using the VirtualBox viewer. Just like "sdl", it accepts
- the optional attributes display
and
- fullscreen
.
-
egl-headless
Since 4.6.0=
span>
- This display type provides support for an OpenGL accelerated
- display accessible both locally and remotely (for comparison,
- Spice's native OpenGL support only works locally using UNIX
- sockets at the moment, but has better performance). Since th=
is
- display type doesn't provide any window or graphical console=
like
- the other types, for practical reasons it should be paired w=
ith
- either vnc
or spice
graphics types.
- This display type is only supported by QEMU domains
- (needs QEMU 2.10 or newer).
- 5.0.0 this element accepts a
- <gl/>
sub-element with an optional attrib=
ute
- rendernode
which can be used to specify an abso=
lute
- path to a host's DRI device to be used for OpenGL rendering.
-
-<graphics type=3D'spice' autoport=3D'yes'/> -<graphics type=3D'egl-headless'> - <gl rendernode=3D'/dev/dri/renderD128'/> -</graphics> --
- Graphics device uses a <listen>
to set up where
- the device should listen for clients. It has a mandatory attribute
- type
which specifies the listen type. Only vnc,
-
spice
and rdp
supports <listen>
-
element. Since 0.9.4.
- Available types are:
-
address
- Tells a graphics device to use an address specified in the
- address
attribute, which will contain either an IP =
address
- or hostname (which will be resolved to an IP address via a DNS q=
uery)
- to listen on.
-
- It is possible to omit the address
attribute in ord=
er to
- use an address from config files Since 1.3=
.5.
-
- The address
attribute is duplicated as listen=
- attribute in graphics
element for backward compatib=
ility.
- If both are provided they must be equal.
-
network
- This is used to specify an existing network in the network=
- attribute from libvirt's list of configured networks. The named =
network
- configuration will be examined to determine an appropriate listen
- address and the address will be stored in live XML in addr=
ess
-
attribute. For example, if the network has an IPv4 addre=
ss in
- its configuration (e.g. if it has a forward type of route<=
/code>,
-
nat
, 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 addre=
ss
- associated with that bridge device will be used, and if the netw=
ork is
- describing one of the 'direct' (macvtap) modes, the first IPv4 a=
ddress
- of the first forward dev will be used.
-
socket
since 2.0.0 (QEMU only=
)
- This listen type tells a graphics server to listen on unix socke=
t.
- Attribute socket
contains a path to unix socket. If=
this
- attribute is omitted libvirt will generate this path for you.
- Supported by graphics type vnc
and spice.
-
- For vnc
graphics be backward compatible
- the socket
attribute of first listen
e=
lement
- is duplicated as socket
attribute in graphics=
- element. If graphics
element contains a socke=
t
- attribute all listen
elements are ignored.
-
none
since 2.0.0 (QEMU only)<=
/span>
- This listen type doesn't have any other attribute. Libvirt suppo=
rts
- passing a file descriptor through our APIs virDomainOpenGraphics=
() and
- virDomainOpenGraphicsFD(). No other listen types are allowed if =
this
- one is used and the graphics device doesn't listen anywhere. You=
need
- to use one of the two APIs to pass a FD to QEMU in order to conn=
ect to
- this graphics device. Supported by graphics type vnc
and
- spice
.
-
- A video device. -
- --... -<devices> - <video> - <model type=3D'vga' vram=3D'16384' heads=3D'1'> - <acceleration accel3d=3D'yes' accel2d=3D'yes'/> - </model> - <driver name=3D'qemu'/> - </video> -</devices> -...- -
video
- The video
element is the container for describing
- video devices. For backwards compatibility, if no video
- is set but there is a
graphics
in domain xml, then
- libvirt will add a default video
according to the g=
uest
- type.
-
- For a guest of type "kvm", the default video
is:
- type
with value "cirrus", vram
with va=
lue
- "16384" and heads
with value "1". By default, the f=
irst
- video device in domain xml is the primary one, but the optional
- attribute primary
(since 1.0.=
2)
- with value 'yes' can be used to mark the primary in cases of mul=
tiple
- video device. The non-primary must be type of "qxl" or
- (since 2.4.0) "virtio".
-
model
- The model
element has a mandatory type
- attribute which takes the value "vga", "cirrus", "vmvga", "xen",
- "vbox", "qxl" (since 0.8.6),
- "virtio" (since 1.3.0),
- "gop" (since 3.2.0),
- "bochs" (since 5.6.0), "ramfb"
- (since 5.9.0), or "none"
- (since 4.6.0, depending on the hyp=
ervisor
- features available.
- The purpose of the type none
is to instruct libvirt=
not
- to add a default video device in the guest (see the paragraph ab=
ove).
- This legacy behaviour can be inconvenient in cases where GPU med=
iated
- devices are meant to be the only rendering device within a guest=
and
- so specifying another video
device along with type
- none
.
- Refer to Host device assignment to=
see
- how to add a mediated device into a guest.
-
- You can provide the amount of video memory in kibibytes (blocks =
of
- 1024 bytes) using vram
. This is supported only for =
guest
- type of "vz", "qemu", "vbox", "vmx" and "xen". If no
- value is provided the default is used. If the size is not a powe=
r of
- two it will be rounded to closest one.
-
- The number of screen can be set using heads
. This is
- supported only for guests type of "vz", "kvm", "vbox" and "vmx".
-
- For guest type of "kvm" or "qemu" and model type "qxl" there are
- optional attributes. Attribute ram
(
- since 1.0.2) specifies the size of the primary bar, while=
the
- attribute vram
specifies the secondary bar size.
- If ram
or vram
are not supplied a defa=
ult
- value is used. The ram
should also be rounded to po=
wer of
- two as vram
. There is also optional attribute
- vgamem
(since 1.2.11) =
to set
- the size of VGA framebuffer for fallback mode of QXL device.
- Attribute vram64
(since 1.3.3=
)
- extends secondary bar and makes it addressable as 64bit memory.
-
Since 5.9.0, the model
- element may also have an optional resolution
sub-elem=
ent.
- The resolution
element has attributes x
=
and
- y
to set the minimum resolution for the video device.=
This
- sub-element is valid for model types "vga", "qxl", "bochs", and
- "virtio".
-
acceleration
accel2d
accel3d
rendernode
address
address
sub-element can be used to
- tie the video device to a particular PCI slot.
- On S390, address
can be used to provide the
- CCW address for the video device (
- since 4.2.0).
- driver
driver
can be used to tune the device:
- name
virtio
- device).
- vgaconf
attribute which takes the value "io", "on" =
or "off".
- At present, it's only applicable to the bhyve's "gop" video mode=
l type
- (Since 3.5.0)
- - A character device provides a way to interact with the virtual machi= ne. - Paravirtualized consoles, serial ports, parallel ports and channels = are - all classed as character devices and so represented using the same s= yntax. -
- --... -<devices> - <parallel type=3D'pty'> - <source path=3D'/dev/pts/2'/> - <target port=3D'0'/> - </parallel> - <serial type=3D'pty'> - <source path=3D'/dev/pts/3'/> - <target port=3D'0'/> - </serial> - <serial type=3D'file'> - <source path=3D'/tmp/file' append=3D'on'> - <seclabel model=3D'dac' relabel=3D'no'/> - </source> - <target port=3D'0'/> - </serial> - <console type=3D'pty'> - <source path=3D'/dev/pts/4'/> - <target port=3D'0'/> - </console> - <channel type=3D'unix'> - <source mode=3D'bind' path=3D'/tmp/guestfwd'/> - <target type=3D'guestfwd' address=3D'10.0.2.1' port=3D'4600'/> - </channel> -</devices> -...- -
- In each of these directives, the top-level element name (parallel, s=
erial,
- console, channel) describes how the device is presented to the guest=
. The
- guest interface is configured by the target
element.
-
- The interface presented to the host is given in the type
- attribute of the top-level element. The host interface is
- configured by the source
element.
-
- The source
element may contain an optional
- seclabel
to override the way that labelling
- is done on the socket path. If this element is not present,
- the security label is inherited from
- the per-domain setting.
-
- If the interface type
presented to the host is "file",
- then the source
element may contain an optional attribu=
te
- append
that specifies whether or not the information in
- the file should be preserved on domain restart. Allowed values are
- "on" and "off" (default). Since 1.3.1.
-
- Regardless of the type
, character devices can
- have an optional log file associated with them. This is
- expressed via a log
sub-element, with a
- file
attribute. There can also be an append
- attribute which takes the same values described above.
- Since 1.3.3.
-
-... -<log file=3D"/var/log/libvirt/qemu/guestname-serial0.log" append=3D"off= "/> -...- -
- Each character device element has an optional
- sub-element <address>
which can tie the
- device to a
- particular controller or PCI
- slot.
-
- For character device with type unix
or tcp
- the source
has an optional element reconnect
- which configures reconnect timeout if the connection is lost.
- There are two attributes,
enabled
where possible
- values are "yes" and "no" and timeout
which is in
- seconds. The reconnect
attribute is valid only
- for connect
mode.
- Since 3.7.0 (QEMU driver only).
-
- A character device presents itself to the guest as one of the follow= ing - types. -
- --... -<devices> - <parallel type=3D'pty'> - <source path=3D'/dev/pts/2'/> - <target port=3D'0'/> - </parallel> -</devices> -...- -
- target
can have a port
attribute, which
- specifies the port number. Ports are numbered starting from 0. There=
are
- usually 0, 1 or 2 parallel ports.
-
-... -<devices> - <!-- Serial port --> - <serial type=3D'pty'> - <source path=3D'/dev/pts/3'/> - <target port=3D'0'/> - </serial> -</devices> -...- -
-... -<devices> - <!-- USB serial port --> - <serial type=3D'pty'> - <target type=3D'usb-serial' port=3D'0'> - <model name=3D'usb-serial'/> - </target> - <address type=3D'usb' bus=3D'0' port=3D'1'/> - </serial> -</devices> -...- -
- The target
element can have an optional port
- attribute, which specifies the port number (starting from 0), and an
- optional
type
attribute: valid values are,
- since 1.0.2, isa-serial
(u=
sable
- with x86 guests), usb-serial
(usable whenever USB suppo=
rt
- is available) and pci-serial
(usable whenever PCI suppo=
rt
- is available); since 3.10.0,
- spapr-vio-serial
(usable with ppc64/pseries guests),
- system-serial
(usable with aarch64/virt and,
- since 4.7.0, riscv/virt guests) and
- sclp-serial
(usable with s390 and s390x guests) are
- available as well.
-
- Since 3.10.0, the target
- element can have an optional model
subelement;
- valid values for its name
attribute are:
- isa-serial
(usable with the isa-serial
tar=
get
- type); usb-serial
(usable with the usb-serial
- target type);
pci-serial
- (usable with the pci-serial
target type);
- spapr-vty
(usable with the spapr-vio-serial
- target type); pl011
and,
- since 4.7.0, 16550a
(usable
- with the system-serial
target type);
- sclpconsole
and sclplmconsole
(usable with
- the sclp-serial
target type). Providing a target model =
is
- usually unnecessary: libvirt will automatically pick one that's suit=
able
- for the chosen target type, and overriding that value is generally n=
ot
- recommended.
-
- If any of the attributes is not specified by the user, libvirt will - choose a value suitable for most users. -
- -
- Most target types support configuring the guest-visible device
- address as documented above; more
- specifically, acceptable address types are isa
(for
- isa-serial
), usb
(for usb-serial),
-
pci
(for pci-serial
) and spapr-vio=
code>
- (for
spapr-vio-serial
). The system-serial
- and sclp-serial
target types don't support specifying an
- address.
-
- For the relationship between serial ports and consoles, - see below. -
- --... -<devices> - <!-- Serial console --> - <console type=3D'pty'> - <source path=3D'/dev/pts/2'/> - <target type=3D'serial' port=3D'0'/> - </console> -</devices> -...- -
-... -<devices> - <!-- KVM virtio console --> - <console type=3D'pty'> - <source path=3D'/dev/pts/5'/> - <target type=3D'virtio' port=3D'0'/> - </console> -</devices> -...- -
- The console
element is used to represent interactive
- serial consoles. Depending on the type of guest in use and the speci=
fics
- of the configuration, the console
element might represe=
nt
- the same device as an existing serial
element or a sepa=
rate
- device.
-
- A target
subelement is supported and works the same
- way as with the serial
element
- (see above for details).
- Valid values for the type
attribute are:
- serial
(described below);
- virtio
(usable whenever VirtIO support is available);
- xen
, lxc
and openvz
- (available when the corresponding hypervisor is in use).
- sclp
and sclplm
(usable for s390 and
- s390x QEMU guests) are supported for compatibility reasons but should
- not be used for new guests: use the sclpconsole
and
- sclplmconsole
target models, respectively, with the
- serial
element instead.
-
- Of the target types listed above, serial
is special in
- that it doesn't represents a separate device, but rather the same
- device as the first serial
element. Due to this, there =
can
- only be a single console
element with target type
- serial
per guest.
-
- Virtio consoles are usually accessible as /dev/hvc[0-7]
- from inside the guest; for more information, see
- http=
://fedoraproject.org/wiki/Features/VirtioSerial.
- Since 0.8.3
-
- For the relationship between serial ports and consoles, - see below. -
- -
- Due to hystorical reasons, the serial
and
- console
elements have partially overlapping scopes.
-
- In general, both elements are used to configure one or more serial
- consoles to be used for interacting with the guest. The main differe=
nce
- between the two is that serial
is used for emulated,
- usually native, serial consoles, whereas console
is used
- for paravirtualized ones.
-
- Both emulated and paravirtualized serial consoles have advantages and - disadvantages: -
- -- A configuration such as: -
- --... -<devices> - <console type=3D'pty'> - <target type=3D'serial'/> - </console> - <console type=3D'pty'> - <target type=3D'virtio'/> - </console> -</devices> -...- -
- will work on any platform and will result in one emulated serial con=
sole
- for early boot logging / interactive / recovery use, and one
- paravirtualized serial console to be used eg. as a side channel. Most
- people will be fine with having just the first console
- element in their configuration, but if a specific configuration is
- desired then both elements should be specified.
-
- Note that, due to the compatibility concerns mentioned earlier, all = the - following configurations: -
- --... -<devices> - <serial type=3D'pty'/> -</devices> -...- -
-... -<devices> - <console type=3D'pty'/> -</devices> -...- -
-... -<devices> - <serial type=3D'pty'/> - <console type=3D'pty'/> -</devices> -...- -
- will be treated the same and will result in a single emulated serial - console being available to the guest. -
- -- This represents a private communication channel between the host and= the - guest. -
- --... -<devices> - <channel type=3D'unix'> - <source mode=3D'bind' path=3D'/tmp/guestfwd'/> - <target type=3D'guestfwd' address=3D'10.0.2.1' port=3D'4600'/> - </channel> - - <!-- KVM virtio channel --> - <channel type=3D'pty'> - <target type=3D'virtio' name=3D'arbitrary.virtio.serial.port.name'/= > - </channel> - <channel type=3D'unix'> - <source mode=3D'bind' path=3D'/var/lib/libvirt/qemu/f16x86_64.agent= '/> - <target type=3D'virtio' name=3D'org.qemu.guest_agent.0' state=3D'co= nnected'/> - </channel> - <channel type=3D'spicevmc'> - <target type=3D'virtio' name=3D'com.redhat.spice.0'/> - </channel> -</devices> -...- -
- This can be implemented in a variety of ways. The specific type of
- channel is given in the type
attribute of the
- target
element. Different channel types have different
- target
attributes.
-
guestfwd
target
- element must have address
and port
attri=
butes.
- Since 0.7.3
virtio
name
is spec=
ified,
- /dev/virtio-ports/$name (for more info, please see
- ht=
tp://fedoraproject.org/wiki/Features/VirtioSerial). The
- optional element address
can tie the channel to a
- particular type=3D'virtio-serial'
- controller, documented above.
- With qemu, if name
is "org.qemu.guest_agent.0",
- then libvirt can interact with a guest agent installed in the
- guest, for actions such as guest shutdown or file system quiescing.
- Since 0.7.7, guest agent interaction
- since 0.9.10 Moreover, since 1.0.6
- it is possible to have source path auto generated for virtio unix =
channels.
- This is very useful in case of a qemu guest agent, where users don=
't
- usually care about the source path since it's libvirt who talks to
- the guest agent. In case users want to utilize this feature, they =
should
- leave <source>
element out. Since
- 1.2.11 the active XML for a virtio channel may contain an o=
ptional
- state
attribute that reflects whether a process in the
- guest is active on the channel. This is an output-only attribute.
- Possible values for the state
attribute are
- connected
and disconnected
.
- xen
state
attribute is not supported since Xen channe=
ls
- lack the necessary probing mechanism.
- Since 2.3.0
- spicevmc
main
channel. The target
- element must be present, with
- attribute type=3D'virtio'
; an optional
- attribute name
controls how the guest will have
- access to the channel, and defaults
- to name=3D'com.redhat.spice.0'
. The
- optional address
element can tie the channel to a
- particular type=3D'virtio-serial'
controller.
- Since 0.8.8- A character device presents itself to the host as one of the followi= ng - types. -
- -- This disables all input on the character device, and sends output - into the virtual machine's logfile -
- --... -<devices> - <console type=3D'stdio'> - <target port=3D'1'/> - </console> -</devices> -...- - -
- A file is opened and all data sent to the character - device is written to the file. -
- --... -<devices> - <serial type=3D"file"> - <source path=3D"/var/log/vm/vm-serial.log"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- 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" -
- --... -<devices> - <serial type=3D'vc'> - <target port=3D"1"/> - </serial> -</devices> -...- -
- Connects the character device to the void. No data is ever - provided to the input. All data written is discarded. -
- --... -<devices> - <serial type=3D'null'> - <target port=3D"1"/> - </serial> -</devices> -...- -
- A Pseudo TTY is allocated using /dev/ptmx. A suitable client - such as 'virsh console' can connect to interact with the - serial port locally. -
- --... -<devices> - <serial type=3D"pty"> - <source path=3D"/dev/pts/3"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- NB special case if <console type=3D'pty'>, then the TTY - path is also duplicated as an attribute tty=3D'/dev/pts/3' - on the top level <console> tag. This provides compat - with existing syntax for <console> tags. -
- -- 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. -
- --... -<devices> - <serial type=3D"dev"> - <source path=3D"/dev/ttyS0"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- The character device writes output to a named pipe. See pipe(7) for - more info. -
- --... -<devices> - <serial type=3D"pipe"> - <source path=3D"/tmp/mypipe"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- The character device acts as a TCP client connecting to a - remote server. -
- --... -<devices> - <serial type=3D"tcp"> - <source mode=3D"connect" host=3D"0.0.0.0" service=3D"2445"/> - <protocol type=3D"raw"/> - <target port=3D"1"/> - </serial> -</devices> - ...- -
- Or as a TCP server waiting for a client connection. -
- --... -<devices> - <serial type=3D"tcp"> - <source mode=3D"bind" host=3D"127.0.0.1" service=3D"2445"/> - <protocol type=3D"raw"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- Alternatively you can use telnet
instead
- of raw
TCP in order to utilize the telnet protocol
- for the connection.
-
- Since 0.8.5, some hypervisors support
- use of either telnets
(secure telnet) or tls
- (via secure sockets layer) as the transport protocol for connections.
-
-... -<devices> - <serial type=3D"tcp"> - <source mode=3D"connect" host=3D"0.0.0.0" service=3D"2445"/> - <protocol type=3D"telnet"/> - <target port=3D"1"/> - </serial> - ... - <serial type=3D"tcp"> - <source mode=3D"bind" host=3D"127.0.0.1" service=3D"2445"/> - <protocol type=3D"telnet"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- Since 2.4.0, the optional attribute
- tls
can be used to control whether a chardev
- TCP communication channel would utilize a hypervisor configured
- TLS X.509 certificate environment in order to encrypt the data
- channel. For the QEMU hypervisor, usage of a TLS environment can
- be controlled on the host by the chardev_tls
and
- chardev_tls_x509_cert_dir
or
- default_tls_x509_cert_dir
settings in the file
- /etc/libvirt/qemu.conf. If chardev_tls
is enabled,
- then unless the tls
attribute is set to "no", libvirt
- will use the host configured TLS environment.
- If chardev_tls
is disabled, but the tls
- attribute is set to "yes", then libvirt will attempt to use the
- host TLS environment if either the chardev_tls_x509_cert_dir=
code>
- or
default_tls_x509_cert_dir
TLS directory structure ex=
ists.
-
-... -<devices> - <serial type=3D"tcp"> - <source mode=3D'connect' host=3D"127.0.0.1" service=3D"5555" tls=3D= "yes"/> - <protocol type=3D"raw"/> - <target port=3D"0"/> - </serial> -</devices> -...- -
- The character device acts as a UDP netconsole service, - sending and receiving packets. This is a lossy service. -
- --... -<devices> - <serial type=3D"udp"> - <source mode=3D"bind" host=3D"0.0.0.0" service=3D"2445"/> - <source mode=3D"connect" host=3D"0.0.0.0" service=3D"2445"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- The character device acts as a UNIX domain socket server, - accepting connections from local clients. -
- --... -<devices> - <serial type=3D"unix"> - <source mode=3D"bind" path=3D"/tmp/foo"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- The character device is accessible through spice connection
- under a channel name specified in the channel
- attribute. Since 1.2.2
-
- Note: depending on the hypervisor, spiceports might (or might not) - be enabled on domains with or without = spice - graphics. -
- --... -<devices> - <serial type=3D"spiceport"> - <source channel=3D"org.qemu.console.serial.0"/> - <target port=3D"1"/> - </serial> -</devices> -...- -
- The nmdm device driver, available on FreeBSD, provides two - tty devices connected together by a virtual null modem cable. - Since 1.2.4 -
- --... -<devices> - <serial type=3D"nmdm"> - <source master=3D"/dev/nmdm0A" slave=3D"/dev/nmdm0B"/> - </serial> -</devices> -...- -
- The source
element has these attributes:
-
master
slave
- A virtual sound card can be attached to the host via the
- sound
element. Since 0.4.3
-
-... -<devices> - <sound model=3D'es1370'/> -</devices> -...- -
sound
sound
element has one mandatory attribute,
- model
, which specifies what real sound device is emul=
ated.
- Valid values are specific to the underlying hypervisor, though typ=
ical
- choices are 'es1370', 'sb16', 'ac97', 'ich6' and 'usb'.
- (
- 'ac97' only since 0.6.0, 'ich6' only since 0.8.8,
- 'usb' only since 1.2.7)
-
- Since 0.9.13, a sound element
- with ich6
model can have optional
- sub-elements <codec>
to attach various audio
- codecs to the audio device. If not specified, a default codec
- will be attached to allow playback and recording.
-
- Valid values are: -
--
-... -<devices> - <sound model=3D'ich6'> - <codec type=3D'micro'/> - </sound> -</devices> -...- -
- Each sound
element has an optional
- sub-element <address>
which can tie the
- device to a particular PCI
- slot, documented above.
-
- A virtual hardware watchdog device can be added to the guest via
- the watchdog
element.
- Since 0.7.3, QEMU and KVM only
-
- 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. -
- -- Currently libvirt does not support notification when the - watchdog fires. This feature is planned for a future version of - libvirt. -
- --... -<devices> - <watchdog model=3D'i6300esb'/> -</devices> -...- -
- ... - <devices> - <watchdog model=3D'i6300esb' action=3D'poweroff'/> - </devices> -</domain>- -
model
- The required model
attribute specifies what real
- watchdog device is emulated. Valid values are specific to the
- underlying hypervisor.
-
- QEMU and KVM support: -
-action
- The optional action
attribute describes what
- action to take when the watchdog expires. Valid values are
- specific to the underlying hypervisor.
-
- QEMU and KVM support: -
-- 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. -
-
- Note 2: the directory to save dump files can be configured
- by auto_dump_path
in file /etc/libvirt/qemu.conf.
-
- A virtual memory balloon device is added to all Xen and KVM/QEMU
- guests. It will be seen as memballoon
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.
- Since 0.8.3, Xen, QEMU and KVM only
- Additionally, since 0.8.4, if the
- memballoon device needs to be explicitly disabled,
- model=3D'none'
may be used.
-
- Example: automatically added device with KVM -
--... -<devices> - <memballoon model=3D'virtio'/> -</devices> -...- -
- Example: manually added device with static PCI slot 2 requested -
-- ... - <devices> - <memballoon model=3D'virtio'> - <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x02= ' function=3D'0x0'/> - <stats period=3D'10'/> - <driver iommu=3D'on' ats=3D'on'/> - </memballoon> - </devices> -</domain>- -
model
- The required model
attribute specifies what type
- of balloon device is provided. Valid values are specific to
- the virtualization platform
-
autodeflate
- The optional autodeflate
attribute allows to
- enable/disable (values "on"/"off", respectively) the ability of =
the
- QEMU virtio memory balloon to release some memory at the last mo=
ment
- before a guest's process get killed by Out of Memory killer.
- Since 1.3.1, QEMU and KVM only
-
period
- The optional period
allows the QEMU virtio memory b=
alloon
- driver to provide statistics through the virsh dommemstat
- [domain]
command. By default, collection is not enabled. =
In
- order to enable, use the virsh dommemstat [domain] --period
- [number]
command or virsh edit
command to ad=
d the
- option to the XML definition. The virsh dommemstat
=
will
- accept the options --live
, --current
,
- or --config
. If an option is not provided, the cha=
nge
- for a running domain will only be made to the active guest. If =
the
- QEMU driver is not at the right revision, the attempt to set the
- period will fail. Large values (e.g. many years) might be ignor=
ed.
- Since 1.1.1, requires QEMU 1.5
-
driver
virtio
memballoon,
- Virtio-specific options can also be
- set. (Since 3.5.0)
- - The virtual random number generator device allows the host to pass - through entropy to guest operating systems. - Since 1.0.3 -
- -- Example: usage of the RNG device: -
--... -<devices> - <rng model=3D'virtio'> - <rate period=3D"2000" bytes=3D"1234"/> - <backend model=3D'random'>/dev/random</backend> - <!-- OR --> - <backend model=3D'egd' type=3D'udp'> - <source mode=3D'bind' service=3D'1234'/> - <source mode=3D'connect' host=3D'1.2.3.4' service=3D'1234'/> - </backend> - <!-- OR --> - <backend model=3D'builtin'/> - </rng> -</devices> -... --
model
- The required model
attribute specifies what type
- of RNG device is provided. Valid values are specific to
- the virtualization platform:
-
rate
- The optional rate
element allows limiting the rate =
at
- which entropy can be consumed from the source. The mandatory
- attribute bytes
specifies how many bytes are permit=
ted
- to be consumed per period. An optional period
attr=
ibute
- specifies the duration of a period in milliseconds; if omitted, =
the
- period is taken as 1000 milliseconds (1 second).
- Since 1.0.4
-
backend
- The backend
element specifies the source of entropy
- to be used for the domain. The source model is configured using =
the
- model
attribute. Supported source models are:
-
random
- This backend type expects a non-blocking character device
- as input. The file name is specified as contents of the
- backend
element. Since
- 1.3.4 any path is accepted. Before that
- /dev/random
and /dev/hwrng
were
- the only accepted paths. When no file name is specified,
- the hypervisor default is used. For QEMU, the default is
- /dev/random
. However, the recommended source
- of entropy is /dev/urandom
(as it doesn't
- have the limitations of /dev/random
).
-
egd
- This backend connects to a source using the EGD protocol. - The source is specified as a character device. Refer to - character device host= interface - for more information. -
-builtin
- This backend uses qemu builtin random generator, which uses
- getrandom()
syscall as the source of entropy.
- (Since 6.1.0 and QEMU 4.2)
-
driver
driver
can be used to tune the device:
- - The TPM device enables a QEMU guest to have access to TPM - functionality. The TPM device may either be a TPM 1.2 or - a TPM 2.0. -
-- The TPM passthrough device type provides access to the host's TPM - for one QEMU guest. No other software may be using the TPM device, - typically /dev/tpm0, at the time the QEMU guest is started. - 'passthrough' since 1.0.5 -
- -- Example: usage of the TPM passthrough device -
--... -<devices> - <tpm model=3D'tpm-tis'> - <backend type=3D'passthrough'> - <device path=3D'/dev/tpm0'/> - </backend> - </tpm> -</devices> -... -- -
- The emulator device type gives access to a TPM emulator providing
- TPM functionality for each VM. QEMU talks to it over a Unix socket. =
With
- the emulator device type each guest gets its own private TPM.
- 'emulator' since 4.5.0
- The state of the TPM emulator can be encrypted by providing an
- encryption
element.
- 'encryption' since 5.6.0
-
- Example: usage of the TPM Emulator -
-- ... - <devices> - <tpm model=3D'tpm-tis'> - <backend type=3D'emulator' version=3D'2.0'> - <encryption secret=3D'6dd3e4a5-1d76-44ce-961f-f119f5aad935'/> - </backend> - </tpm> - </devices> - ... --
model
- The model
attribute specifies what device
- model QEMU provides to the guest. If no model name is provided,
- tpm-tis
will automatically be chosen for non-PPC64
- architectures.
- Since 4.4.0, another available choi=
ce
- is the tpm-crb
, which should only be used when the
- backend device is a TPM 2.0. Since 6.1.0=
span>,
- pSeries guests on PPC64 are supported and the default is
- tpm-spapr
.
-
- Since 6.5.0, a new model called
- spapr-tpm-proxy
was added for pSeries guests. This =
model
- only works with the passthrough
backend. It creates=
a
- TPM Proxy device that communicates with an existing TPM Resource=
Manager
- in the host, for example /dev/tpmrm0
, enabling the =
guest to
- run in secure virtual machine mode with the help of an Ultraviso=
r. Adding
- a TPM Proxy to a pSeries guest brings no security benefits unles=
s the guest
- is running on a PPC64 host that has an Ultravisor and a TPM Reso=
urce Manager.
- Only one TPM Proxy device is allowed per guest, but a TPM Proxy =
device can
- be added together with
- other TPM devices.
-
backend
- The backend
element specifies the type of
- TPM device. The following types are supported:
-
passthrough
- Use the host's TPM or TPM Resource Manager device. -
-
- This backend type requires exclusive access to a TPM device =
on
- the host. An example for such a device is /dev/tpm0. The ful=
ly
- qualified file name is specified by path attribute of the
- source
element. If no file name is specified th=
en
- /dev/tpm0 is automatically used.
-
- Since 6.5.0, when choosing the
- spapr-tpm-proxy
model, the file name specified =
is
- expected to be a TPM Resource Manager device, e.g.
- /dev/tpmrm0
.
-
emulator
- For this backend type the 'swtpm' TPM Emulator must be insta= lled on the - host. Libvirt will automatically start an independent TPM em= ulator - for each QEMU guest requesting access to it. -
-version
- The version
attribute indicates the version
- of the TPM. By default a TPM 1.2 is created. This attribute
- only works with the emulator
backend. The following
- versions are supported:
-
encryption
- The encryption
element allows the state of a TPM em=
ulator
- to be encrypted. The secret
must reference a secret=
object
- that holds the passphrase from which the encryption key will be =
derived.
-
- nvram device is always added to pSeries guest on PPC64, and its addr=
ess
- is allowed to be changed. Element nvram
(only valid for
- pSeries guest, since 1.0.5) is provided=
to
- enable the address setting.
-
- Example: usage of NVRAM configuration -
--... -<devices> - <nvram> - <address type=3D'spapr-vio' reg=3D'0x00003000'/> - </nvram> -</devices> -... --
spapr-vio
- VIO device address type, only valid for PPC64. -
-reg
- Device address -
-- panic device enables libvirt to receive panic notification from a QE= MU - guest. - Since 1.2.1, QEMU and KVM only -
-- This feature is always enabled for: -
-
- For the guest types listed above, libvirt automatically adds a
- panic
element to the domain XML.
-
- Example: usage of panic configuration -
--... -<devices> - <panic model=3D'hyperv'/> - <panic model=3D'isa'> - <address type=3D'isa' iobase=3D'0x505'/> - </panic> -</devices> -... --
model
- The optional model
attribute specifies what type
- of panic device is provided. The panic model used when this attr=
ibute
- is missing depends on the hypervisor and guest arch.
-
address
- address of panic. The default ioport is 0x505. Most users - don't need to specify an address, and doing so is forbidden - altogether for s390, pseries and hyperv models. -
-- A shared memory device allows to share a memory region between - different virtual machines and the host. - Since 1.2.10, QEMU and KVM only -
- --... -<devices> - <shmem name=3D'my_shmem0'> - <model type=3D'ivshmem-plain'/> - <size unit=3D'M'>4</size> - </shmem> - <shmem name=3D'shmem_server'> - <model type=3D'ivshmem-doorbell'/> - <size unit=3D'M'>2</size> - <server path=3D'/tmp/socket-shmem'/> - <msi vectors=3D'32' ioeventfd=3D'on'/> - </shmem> -</devices> -... -- -
shmem
shmem
element has one mandatory attribute,
- name
to identify the shared memory. This attribute cann=
ot
- be directory specific to .
or ..
as well as
- it cannot involve path separator /
.
- model
type
of the optional element model
- specifies the model of the underlying device providing the
- shmem
device. The models currently supported are
- ivshmem
(supports both server and server-less shmem, bu=
t is
- deprecated by newer QEMU in favour of the -plain and -doorbell varia=
nts),
- ivshmem-plain
(only for server-less shmem) and
- ivshmem-doorbell
(only for shmem with the server).
-
size
size
element specifies the size of the sha=
red
- memory. This must be power of 2 and greater than or equal to 1 MiB.
- server
server
element can be used to configure a =
server
- socket the device is supposed to connect to. The optional
- path
attribute specifies the absolute path to the unix =
socket
- and defaults to /var/lib/libvirt/shmem/$shmem-$name-sock
.
- msi
msi
element enables/disables (values "on"/=
"off",
- respectively) MSI interrupts. This option can currently be used only
- together with the server
element. The vectors
- attribute can be used to specify the number of interrupt
- vectors. The ioeventd
attribute enables/disables (values
- "on"/"off", respectively) ioeventfd.
-
- In addition to the initial memory assigned to the guest, memory de= vices - allow additional memory to be assigned to the guest in the form of - memory modules. - - A memory device can be hot-plugged or hot-unplugged depending on t= he - guests' memory resource needs. - - Some hypervisors may require NUMA configured for the guest. -
- -- Example: usage of the memory devices -
--... -<devices> - <memory model=3D'dimm' access=3D'private' discard=3D'yes'> - <target> - <size unit=3D'KiB'>524287</size> - <node>0</node> - </target> - </memory> - <memory model=3D'dimm'> - <source> - <pagesize unit=3D'KiB'>4096</pagesize> - <nodemask>1-3</nodemask> - </source> - <target> - <size unit=3D'KiB'>524287</size> - <node>1</node> - </target> - </memory> - <memory model=3D'nvdimm'> - <uuid> - <source> - <path>/tmp/nvdimm</path> - </source> - <target> - <size unit=3D'KiB'>524288</size> - <node>1</node> - <label> - <size unit=3D'KiB'>128</size> - </label> - <readonly/> - </target> - </memory> - <memory model=3D'nvdimm' access=3D'shared'> - <uuid> - <source> - <path>/dev/dax0.0</path> - <alignsize unit=3D'KiB'>2048</alignsize> - <pmem/> - </source> - <target> - <size unit=3D'KiB'>524288</size> - <node>1</node> - <label> - <size unit=3D'KiB'>128</size> - </label> - </target> - </memory> -</devices> -... --
model
- Provide dimm
to add a virtual DIMM module to the gu=
est.
- Since 1.2.14
- Provide nvdimm
model adds a Non-Volatile DIMM
- module. Since 3.2.0
-
access
- An optional attribute access
- (since 3.2.0) that provides
- capability to fine tune mapping of the memory on per
- module basis. Values are the same as
- Memory Backing:
- shared
and private
.
- For nvdimm
model, if using real NVDIMM DAX device as
- backend, shared
is required.
-
discard
- An optional attribute discard
- (since 4.4.0) that provides
- capability to fine tune discard of data on per module
- basis. Accepted values are yes
and
- no
. The feature is described here:
- Memory Backing.
- This attribute is allowed only for
- model=3D'dimm'
.
-
uuid
- For pSeries guests, an uuid can be set to identify the
- nvdimm module. If absent, libvirt will generate an uuid.
- automatically. This attribute is allowed only for
- model=3D'nvdimm'
for pSeries guests.
- Since 6.2.0
-
source
- For model dimm
this element is optional and allows =
to
- fine tune the source of the memory used for the given memory dev=
ice.
- If the element is not provided defaults configured via
- numatune
are used. If dimm
is provided,
- then the following optional elements can be provided as well:
-
pagesize
- This element can be used to override the default - host page size used for backing the memory device. - The configured value must correspond to a page size - supported by the host. -
-nodemask
- This element can be used to override the default - set of NUMA nodes where the memory would be - allocated. -
-
- For model nvdimm
this element is mandatory. The
- mandatory child element path
represents a path in
- the host that backs the nvdimm module in the guest. The following
- optional elements may be used:
-
alignsize
- The alignsize
element defines the page size
- alignment used to mmap the address range for the backend
- path
. If not supplied the host page size is use=
d.
- For example, to mmap a real NVDIMM device a 2M-aligned page =
may
- be required, and host page size is 4KB, then we need to set =
this
- element to 2MB.
- Since 5.0.0
-
pmem
- If persistent memory is supported and enabled by the hypervi=
sor
- in order to guarantee the persistence of writes to the vNVDI=
MM
- backend, then use the pmem
element in order to
- utilize the feature.
- Since 5.0.0
-
target
- The mandatory target
element configures the placeme=
nt and
- sizing of the added memory from the perspective of the guest.
-
- The mandatory size
subelement configures the size o=
f the
- added memory as a scaled integer.
-
- The node
subelement configures the guest NUMA node =
to
- attach the memory to. The element shall be used only if the gues=
t has
- NUMA nodes configured.
-
- The following optional elements may be used: -
- -label
- For NVDIMM type devices one can use label
and i=
ts
- subelement size
to configure the size of
- namespaces label storage within the NVDIMM module. The
- size
element has usual meaning described
- here.
- label
is mandatory for pSeries guests and optio=
nal
- for all other architectures.
- For QEMU domains the following restrictions apply:
-
readonly
- The readonly
element is used to mark the vNVDIMM
- as read-only. Only the real NVDIMM device backend can guaran=
tee
- the guest write persistence, so other backend types should u=
se
- the readonly
element.
- Since 5.0.0
-
- The iommu
element can be used to add an IOMMU device.
- Since 2.1.0
-
- Example: -
--... -<devices> - <iommu model=3D'intel'> - <driver intremap=3D'on'/> - </iommu> -</devices> -... --
model
- Supported values are intel
(for Q35 guests) and,
- since 5.5.0, smmuv3
(f=
or
- ARM virt guests).
-
driver
- The driver
subelement can be used to configure
- additional options, some of which might only be available for
- certain IOMMU models:
-
intremap
- The intremap
attribute with possible values
- on
and off
can be used to
- turn on interrupt remapping, a part of the VT-d functionalit=
y.
- Currently this requires split I/O APIC
- (<ioapic driver=3D'qemu'/>
).
- Since 3.4.0 (QEMU/KVM only)
-
caching_mode
- The caching_mode
attribute with possible values
- on
and off
can be used to
- turn on the VT-d caching mode (useful for assigned devices).
- Since 3.4.0 (QEMU/KVM only)
-
eim
- The eim
attribute (with possible values
- on
and off
) can be used to
- configure Extended Interrupt Mode. A q35 domain with
- split I/O APIC (as described in
- hypervisor features),
- and both interrupt remapping and EIM turned on for
- the IOMMU, will be able to use more than 255 vCPUs.
- Since 3.4.0 (QEMU/KVM only)
-
iotlb
- The iotlb
attribute with possible values
- on
and off
can be used to
- turn on the IOTLB used to cache address translation
- requests from devices.
- Since 3.5.0 (QEMU/KVM only)
-
aw_bits
- The aw_bits
attribute can be used to set
- the address width to allow mapping larger iova addresses
- in the guest.
- Since 6.5.0 (QEMU/KVM only)
-
A vsock host/guest interface. The model
attribute
- defaults to virtio
. Since 5.2.0
- model
can also be 'virtio-transitional' and
- 'virtio-non-transitional', see
- Virtio transitional devices
- for more details.
- The optional attribute address
of the cid
- element specifies the CID assigned to the guest. If the attribute
- auto
is set to yes
, libvirt
- will assign a free CID automatically on domain startup.
- Since 4.4.0
-... -<devices> - <vsock model=3D'virtio'> - <cid auto=3D'no' address=3D'3'/> - </vsock> -</devices> -...- - -
- The seclabel
element allows control over the
- operation of the security drivers. There are three basic
- modes of operation, 'dynamic' where libvirt automatically
- generates a unique security label, 'static' where the
- application/administrator chooses the labels, or 'none'
- where confinement is disabled. With dynamic
- label generation, libvirt will always automatically
- relabel any resources associated with the virtual machine.
- With static label assignment, by default, the administrator
- or application must ensure labels are set correctly on any
- resources, however, automatic relabeling can be enabled
- if desired. 'dynamic' since 0.6.1, 'static'
- since 0.6.2, and 'none' since 0.9.10.
-
- If more than one security driver is used by libvirt, multiple
- seclabel
tags can be used, one for each driver and
- the security driver referenced by each tag can be defined using
- the attribute model
-
- Valid input XML configurations for the top-level security label - are: -
- --<seclabel type=3D'dynamic' model=3D'selinux'/> - -<seclabel type=3D'dynamic' model=3D'selinux'> - <baselabel>system_u:system_r:my_svirt_t:s0</baselabel> -</seclabel> - -<seclabel type=3D'static' model=3D'selinux' relabel=3D'no'> - <label>system_u:system_r:svirt_t:s0:c392,c662</label> -</seclabel> - -<seclabel type=3D'static' model=3D'selinux' relabel=3D'yes'> - <label>system_u:system_r:svirt_t:s0:c392,c662</label> -</seclabel> - -<seclabel type=3D'none'/> -- -
- If no 'type' attribute is provided in the input XML, then - the security driver default setting will be used, which - may be either 'none' or 'dynamic'. If a 'baselabel' is set - but no 'type' is set, then the type is presumed to be 'dynamic' -
- -
- When viewing the XML for a running guest with automatic
- resource relabeling active, an additional XML element,
- imagelabel
, will be included. This is an
- output-only element, so will be ignored in user supplied
- XML documents
-
type
static
, dynamic
or none=
code>
- to determine whether libvirt automatically generates a unique secu=
rity
- label or not.
-
model
dac
is not available
- when guest is run by unprivileged user.
- relabel
yes
or no
. This must always
- be yes
if dynamic label assignment is used. With
- static label assignment it will default to no
.
- label
baselabel
type
field of the
- baselabel in the generated label. Other fields are inherited from
- the parent process when using SELinux baselabels.
-
- (The example above demonstrates the use of my_svirt_t
- as the value for the type
field.)
- imagelabel
When relabeling is in effect, it is also possible to fine-tune
- the labeling done for specific source file names, by either
- disabling the labeling (useful if the file lives on NFS or other
- file system that lacks security labeling) or requesting an
- alternate label (useful when a management application creates a
- special label to allow sharing of some, but not all, resources
- between domains), since 0.9.9. When
- a seclabel
element is attached to a specific path
- rather than the top-level domain assignment, only the
- attribute relabel
or the
- sub-element label
are supported. Additionally,
- since 1.1.2, an output-only
- element labelskip
will be present for active
- domains on disks where labeling was skipped due to the image
- being on a file system that lacks security labeling.
-
The content of the optional keywrap
element specifi=
es
- whether the guest will be allowed to perform the S390 cryptographi=
c key
- management operations. A clear key can be protected by encrypting =
it
- under a unique wrapping key that is generated for each guest VM ru=
nning
- on the host. Two variations of wrapping keys are generated: one ve=
rsion
- for encrypting protected keys using the DEA/TDEA algorithm, and an=
other
- version for keys encrypted using the AES algorithm. If a
- keywrap
element is not included, the guest will be gr=
anted
- access to both AES and DEA/TDEA key wrapping by default.
-<domain> - ... - <keywrap> - <cipher name=3D'aes' state=3D'off'/> - </keywrap> - ... -</domain> --
- At least one cipher
element must be nested within the
- keywrap
element.
-
cipher
name
attribute identifies the algorithm
- for encrypting a protected key. The values supported for this attr=
ibute
- are aes
for encryption under the AES wrapping key, or
- dea
for encryption under the DEA/TDEA wrapping key. T=
he
- state
attribute indicates whether the cryptographic k=
ey
- management operations should be turned on for the specified encryp=
tion
- algorithm. The value can be set to on
or off.
-
Note: DEA/TDEA is synonymous with DES/TDES.
- -
- The contents of the <launchSecurity type=3D'sev'>
element
- is used to provide the guest owners input used for creating an encr=
ypted
- VM using the AMD SEV feature (Secure Encrypted Virtualization).
-
- SEV is an extension to the AMD-V architecture which supports running
- encrypted virtual machine (VMs) under the control of KVM. Encrypted
- VMs have their pages (code and data) secured such that only the gue=
st
- itself has access to the unencrypted version. Each encrypted VM is
- associated with a unique encryption key; if its data is accessed to=
a
- different entity using a different key the encrypted guests data wi=
ll
- be incorrectly decrypted, leading to unintelligible data.
-
- For more information see various input parameters and its format se=
e the
- SEV API spec
- Since 4.4.0
-
-<domain> - ... - <launchSecurity type=3D'sev'> - <policy>0x0001</policy> - <cbitpos>47</cbitpos> - <reducedPhysBits>1</reducedPhysBits> - <dhCert>RBBBSDDD=3DFDDCCCDDDG</dhCert> - <session>AAACCCDD=3DFFFCCCDSDS</session> - </launchSecurity> - ... -</domain> -- -
cbitpos
cbitpos
element provides the C-bit (ak=
a encryption bit)
- location in guest page table entry. The value of cbitpos
is
- hypervisor dependent and can be obtained through the sev
element
- from the domain capabilities.
- reducedPhysBits
reducedPhysBits
element provides the p=
hysical
- address bit reducation. Similar to cbitpos
the value of=
- reduced-phys-bit
is hypervisor dependent and can be obtained
- through the sev
element from the domain capabilities.
- policy
policy
element provides the guest poli=
cy
- which must be maintained by the SEV firmware. This policy is enforce=
d by
- the firmware and restricts what configuration and operational comman=
ds
- can be performed on this guest by the hypervisor. The guest policy
- provided during guest launch is bound to the guest and cannot be cha=
nged
- throughout the lifetime of the guest. The policy is also transmitted
- during snapshot and migration flows and enforced on the destination =
platform.
-
- The guest policy is a 4 unsigned byte with the fields shown in Table:
-
- Bit(s) | -Description | -
---|---|
0 | -Debugging of the guest is disallowed when set | -
1 | -Sharing keys with other guests is disallowed when set | -
2 | -SEV-ES is required when set | -
3 | -Sending the guest to another platform is disallowed when se= t | -
4 | -The guest must not be transmitted to another platform that = is - not in the domain when set. | -
5 | -The guest must not be transmitted to another platform that = is - not SEV capable when set. | -
6:15 | -reserved | -
16:32 | -The guest must not be transmitted to another platform with a - lower firmware version. | -
dhCert
dhCert
element provides the guest owne=
rs
- base64 encoded Diffie-Hellman (DH) key. The key is used to negotiate=
a
- master secret key between the SEV firmware and guest owner. This mas=
ter
- secret key is then used to establish a trusted channel between SEV
- firmware and guest owner.
- session
session
element provides the guest own=
ers
- base64 encoded session blob defined in the SEV API spec.
-
- See SEV spec LAUNCH_START section for the session blob format.
- - Example configurations for each driver are provide on the - driver specific pages listed below -
- - - - diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst new file mode 100644 index 0000000000..776dcf7e25 --- /dev/null +++ b/docs/formatdomain.rst @@ -0,0 +1,7442 @@ +.. role:: since +.. role:: anchor(raw) + :format: html + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Domain XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +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 `driver +docs