docs/formatdomain.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Domain XML format</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <p>
  10       This section describes the XML format used to represent domains, there are
  11       variations on the format based on the kind of domains run and the options
  12       used to launch them. For hypervisor specific details consult the
  13       <a href="drivers.html">driver docs</a>
  14     </p>
  15
  16
  17     <h2><a id="elements">Element and attribute overview</a></h2>
  18
  19     <p>
  20       The root element required for all virtual machines is
  21       named <code>domain</code>. It has two attributes, the
  22       <a id="attributeDomainType"><code>type</code></a>
  23       specifies the hypervisor used for running
  24       the domain. The allowed values are driver specific, but
  25       include "xen", "kvm", "qemu" and "lxc". The
  26       second attribute is <code>id</code> which is a unique
  27       integer identifier for the running guest machine. Inactive
  28       machines have no id value.
  29     </p>
  30
  31
  32     <h3><a id="elementsMetadata">General metadata</a></h3>
  33
  34 <pre>
  35 &lt;domain type='kvm' id='1'&gt;
  36   &lt;name&gt;MyGuest&lt;/name&gt;
  37   &lt;uuid&gt;4dea22b3-1d52-d8f3-2516-782e98ab3fa0&lt;/uuid&gt;
  38   &lt;genid&gt;43dc0cf8-809b-4adb-9bea-a9abb5f3d90e&lt;/genid&gt;
  39   &lt;title&gt;A short description - title - of the domain&lt;/title&gt;
  40   &lt;description&gt;Some human readable description&lt;/description&gt;
  41   &lt;metadata&gt;
  42     &lt;app1:foo xmlns:app1="http://app1.org/app1/"&gt;..&lt;/app1:foo&gt;
  43     &lt;app2:bar xmlns:app2="http://app1.org/app2/"&gt;..&lt;/app2:bar&gt;
  44   &lt;/metadata&gt;
  45   ...</pre>
  46
  47     <dl>
  48       <dt><code>name</code></dt>
  49       <dd>The content of the <code>name</code> element provides
  50         a short name for the virtual machine. This name should
  51         consist only of alpha-numeric characters and is required
  52         to be unique within the scope of a single host. It is
  53         often used to form the filename for storing the persistent
  54         configuration file. <span class="since">Since 0.0.1</span></dd>
  55       <dt><code>uuid</code></dt>
  56       <dd>The content of the <code>uuid</code> element provides
  57         a globally unique identifier for the virtual machine.
  58         The format must be RFC 4122 compliant,
  59         eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
  60         If omitted when defining/creating a new machine, a random
  61         UUID is generated. It is also possible to provide the UUID
  62         via a <a href="#elementsSysinfo"><code>sysinfo</code></a>
  63         specification. <span class="since">Since 0.0.1, sysinfo
  64         since 0.8.7</span></dd>
  65
  66       <dt><code>genid</code></dt>
  67       <dd><span class="since">Since 4.4.0</span>, the <code>genid</code>
  68         element can be used to add a Virtual Machine Generation ID which
  69         exposes a 128-bit, cryptographically random, integer value identifier,
  70         referred to as a Globally Unique Identifier (GUID) using the same
  71         format as the <code>uuid</code>. The value is used to help notify
  72         the guest operating system when the virtual machine is re-executing
  73         something that has already executed before, such as:
  74
  75         <ul>
  76           <li>VM starts executing a snapshot</li>
  77           <li>VM is recovered from backup</li>
  78           <li>VM is failover in a disaster recovery environment</li>
  79           <li>VM is imported, copied, or cloned</li>
  80         </ul>
  81
  82         The guest operating system notices the change and is then able to
  83         react as appropriate by marking its copies of distributed databases
  84         as dirty, re-initializing its random number generator, etc.
  85
  86         <p>
  87         The libvirt XML parser will accept both a provided GUID value
  88         or just &lt;genid/&gt; in which case a GUID will be generated
  89         and saved in the XML. For the transitions such as above, libvirt
  90         will change the GUID before re-executing.</p></dd>
  91
  92       <dt><code>title</code></dt>
  93       <dd>The optional element <code>title</code> provides space for a
  94         short description of the domain. The title should not contain
  95         any newlines. <span class="since">Since 0.9.10</span>.</dd>
  96
  97       <dt><code>description</code></dt>
  98       <dd>The content of the <code>description</code> element provides a
  99         human readable description of the virtual machine. This data is not
 100         used by libvirt in any way, it can contain any information the user
 101         wants. <span class="since">Since 0.7.2</span></dd>
 102
 103       <dt><code>metadata</code></dt>
 104       <dd>The <code>metadata</code> node can be used by applications
 105         to store custom metadata in the form of XML
 106         nodes/trees. Applications must use custom namespaces on their
 107         XML nodes/trees, with only one top-level element per namespace
 108         (if the application needs structure, they should have
 109         sub-elements to their namespace
 110         element). <span class="since">Since 0.9.10</span></dd>
 111    </dl>
 112
 113     <h3><a id="elementsOS">Operating system booting</a></h3>
 114
 115     <p>
 116       There are a number of different ways to boot virtual machines
 117       each with their own pros and cons.
 118     </p>
 119
 120     <h4><a id="elementsOSBIOS">BIOS bootloader</a></h4>
 121
 122     <p>
 123       Booting via the BIOS is available for hypervisors supporting
 124       full virtualization. In this case the BIOS has a boot order
 125       priority (floppy, harddisk, cdrom, network) determining where
 126       to obtain/find the boot image.
 127     </p>
 128
 129 <pre>
 130 ...
 131 &lt;os firmware='efi'&gt;
 132   &lt;type&gt;hvm&lt;/type&gt;
 133   &lt;loader readonly='yes' secure='no' type='rom'&gt;/usr/lib/xen/boot/hvmloader&lt;/loader&gt;
 134   &lt;nvram template='/usr/share/OVMF/OVMF_VARS.fd'&gt;/var/lib/libvirt/nvram/guest_VARS.fd&lt;/nvram&gt;
 135   &lt;boot dev='hd'/&gt;
 136   &lt;boot dev='cdrom'/&gt;
 137   &lt;bootmenu enable='yes' timeout='3000'/&gt;
 138   &lt;smbios mode='sysinfo'/&gt;
 139   &lt;bios useserial='yes' rebootTimeout='0'/&gt;
 140 &lt;/os&gt;
 141 ...</pre>
 142
 143     <dl>
 144       <dt><code>firmware</code></dt>
 145       <dd>The <code>firmware</code> attribute allows management
 146         applications to automatically fill <code>&lt;loader/&gt;</code>
 147         and <code>&lt;nvram/&gt;</code> elements and possibly enable
 148         some features required by selected firmware. Accepted values are
 149         <code>bios</code> and <code>efi</code>.<br/>
 150         The selection process scans for files describing installed
 151         firmware images in specified location and uses the most specific
 152         one which fulfils domain requirements. The locations in order of
 153         preference (from generic to most specific one) are:
 154         <ul>
 155           <li><code>/usr/share/qemu/firmware</code></li>
 156           <li><code>/etc/qemu/firmware</code></li>
 157           <li><code>$XDG_CONFIG_HOME/qemu/firmware</code></li>
 158         </ul>
 159         For more information refer to firmware metadata specification as
 160         described in <code>docs/interop/firmware.json</code> in QEMU
 161         repository. Regular users do not need to bother.
 162         <span class="since">Since 5.2.0 (QEMU and KVM only)</span><br/>
 163         For VMware guests, this is set to <code>efi</code> when the guest
 164         uses UEFI, and it is not set when using BIOS.
 165         <span class="since">Since 5.3.0 (VMware ESX and Workstation/Player)</span>
 166       </dd>
 167       <dt><code>type</code></dt>
 168       <dd>The content of the <code>type</code> element specifies the
 169         type of operating system to be booted in the virtual machine.
 170         <code>hvm</code> indicates that the OS is one designed to run
 171         on bare metal, so requires full virtualization. <code>linux</code>
 172         (badly named!) refers to an OS that supports the Xen 3 hypervisor
 173         guest ABI. There are also two optional attributes, <code>arch</code>
 174         specifying the CPU architecture to virtualization,
 175         and <a id="attributeOSTypeMachine"><code>machine</code></a> referring
 176         to the machine type. The <a href="formatcaps.html">Capabilities XML</a>
 177         provides details on allowed values for
 178         these. <span class="since">Since 0.0.1</span></dd>
 179       <dt><a id="elementLoader"><code>loader</code></a></dt>
 180       <dd>The optional <code>loader</code> tag refers to a firmware blob,
 181         which is specified by absolute path,
 182         used to assist the domain creation process. It is used by Xen
 183         fully virtualized domains as well as setting the QEMU BIOS file
 184         path for QEMU/KVM domains. <span class="since">Xen since 0.1.0,
 185         QEMU/KVM since 0.9.12</span> Then, <span class="since">since
 186         1.2.8</span> it's possible for the element to have two
 187         optional attributes: <code>readonly</code> (accepted values are
 188         <code>yes</code> and <code>no</code>) to reflect the fact that the
 189         image should be writable or read-only. The second attribute
 190         <code>type</code> accepts values <code>rom</code> and
 191         <code>pflash</code>. It tells the hypervisor where in the guest
 192         memory the file should be mapped.  For instance, if the loader
 193         path points to an UEFI image, <code>type</code> should be
 194         <code>pflash</code>. Moreover, some firmwares may
 195         implement the Secure boot feature. Attribute
 196         <code>secure</code> can be used then to control it.
 197         <span class="since">Since 2.1.0</span></dd>
 198       <dt><code>nvram</code></dt>
 199       <dd>Some UEFI firmwares may want to use a non-volatile memory to store
 200         some variables. In the host, this is represented as a file and the
 201         absolute path to the file is stored in this element. Moreover, when the
 202         domain is started up libvirt copies so called master NVRAM store file
 203         defined in <code>qemu.conf</code>. If needed, the <code>template</code>
 204         attribute can be used to per domain override map of master NVRAM stores
 205         from the config file. Note, that for transient domains if the NVRAM file
 206         has been created by libvirt it is left behind and it is management
 207         application's responsibility to save and remove file (if needed to be
 208         persistent). <span class="since">Since 1.2.8</span></dd>
 209       <dt><code>boot</code></dt>
 210       <dd>The <code>dev</code> attribute takes one of the values "fd", "hd",
 211         "cdrom" or "network" and is used to specify the next boot device
 212         to consider. The <code>boot</code> element can be repeated multiple
 213         times to setup a priority list of boot devices to try in turn.
 214         Multiple devices of the same type are sorted according to their
 215         targets while preserving the order of buses. After defining the
 216         domain, its XML configuration returned by libvirt (through
 217         virDomainGetXMLDesc) lists devices in the sorted order. Once sorted,
 218         the first device is marked as bootable. Thus, e.g., a domain
 219         configured to boot from "hd" with vdb, hda, vda, and hdc disks
 220         assigned to it will boot from vda (the sorted list is vda, vdb, hda,
 221         hdc). Similar domain with hdc, vda, vdb, and hda disks will boot from
 222         hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to
 223         configure in the desired way, which is why per-device boot elements
 224         (see <a href="#elementsDisks">disks</a>,
 225         <a href="#elementsNICS">network interfaces</a>, and
 226         <a href="#elementsHostDev">USB and PCI devices</a> sections below) were
 227         introduced and they are the preferred way providing full control over
 228         booting order. The <code>boot</code> element and per-device boot
 229         elements are mutually exclusive. <span class="since">Since 0.1.3,
 230         per-device boot since 0.8.8</span>
 231       </dd>
 232       <dt><code>smbios</code></dt>
 233       <dd>How to populate SMBIOS information visible in the guest.
 234         The <code>mode</code> attribute must be specified, and is either
 235         "emulate" (let the hypervisor generate all values), "host" (copy
 236         all of Block 0 and Block 1, except for the UUID, from the host's
 237         SMBIOS values;
 238         the <a href="html/libvirt-libvirt-host.html#virConnectGetSysinfo">
 239         <code>virConnectGetSysinfo</code></a> call can be
 240         used to see what values are copied), or "sysinfo" (use the values in
 241         the <a href="#elementsSysinfo">sysinfo</a> element).  If not
 242         specified, the hypervisor default is used. <span class="since">
 243         Since 0.8.7</span>
 244       </dd>
 245   </dl>
 246       <p>Up till here the BIOS/UEFI configuration knobs are generic enough to
 247       be implemented by majority (if not all) firmwares out there. However,
 248       from now on not every single setting makes sense to all firmwares. For
 249       instance, <code>rebootTimeout</code> doesn't make sense for UEFI,
 250       <code>useserial</code> might not be usable with a BIOS firmware that
 251       doesn't produce any output onto serial line, etc. Moreover, firmwares
 252       don't usually export their capabilities for libvirt (or users) to check.
 253       And the set of their capabilities can change with every new release.
 254       Hence users are advised to try the settings they use before relying on
 255       them in production.</p>
 256   <dl>
 257       <dt><code>bootmenu</code></dt>
 258       <dd> Whether or not to enable an interactive boot menu prompt on guest
 259       startup. The <code>enable</code> attribute can be either "yes" or "no".
 260       If not specified, the hypervisor default is used. <span class="since">
 261       Since 0.8.3</span>
 262       Additional attribute <code>timeout</code> takes the number of milliseconds
 263       the boot menu should wait until it times out.  Allowed values are numbers
 264       in range [0, 65535] inclusive and it is ignored unless <code>enable</code>
 265       is set to "yes". <span class="since">Since 1.2.8</span>
 266       </dd>
 267       <dt><code>bios</code></dt>
 268       <dd>This element has attribute <code>useserial</code> with possible
 269         values <code>yes</code> or <code>no</code>. It enables or disables
 270         Serial Graphics Adapter which allows users to see BIOS messages
 271         on a serial port. Therefore, one needs to have
 272         <a href="#elementCharSerial">serial port</a> defined.
 273         <span class="since">Since 0.9.4</span>.
 274         <span class="since">Since 0.10.2 (QEMU only)</span> there is
 275         another attribute, <code>rebootTimeout</code> that controls
 276         whether and after how long the guest should start booting
 277         again in case the boot fails (according to BIOS). The value is
 278         in milliseconds with maximum of <code>65535</code> and special
 279         value <code>-1</code> disables the reboot.
 280       </dd>
 281     </dl>
 282
 283     <h4><a id="elementsOSBootloader">Host bootloader</a></h4>
 284
 285     <p>
 286       Hypervisors employing paravirtualization do not usually emulate
 287       a BIOS, and instead the host is responsible to kicking off the
 288       operating system boot. This may use a pseudo-bootloader in the
 289       host to provide an interface to choose a kernel for the guest.
 290       An example is <code>pygrub</code> with Xen. The Bhyve hypervisor
 291       also uses a host bootloader, either <code>bhyveload</code> or
 292       <code>grub-bhyve</code>.
 293     </p>
 294
 295 <pre>
 296 ...
 297 &lt;bootloader&gt;/usr/bin/pygrub&lt;/bootloader&gt;
 298 &lt;bootloader_args&gt;--append single&lt;/bootloader_args&gt;
 299 ...</pre>
 300
 301     <dl>
 302       <dt><code>bootloader</code></dt>
 303       <dd>The content of the <code>bootloader</code> element provides
 304         a fully qualified path to the bootloader executable in the
 305         host OS. This bootloader will be run to choose which kernel
 306         to boot. The required output of the bootloader is dependent
 307         on the hypervisor in use. <span class="since">Since 0.1.0</span></dd>
 308       <dt><code>bootloader_args</code></dt>
 309       <dd>The optional <code>bootloader_args</code> element allows
 310         command line arguments to be passed to the bootloader.
 311         <span class="since">Since 0.2.3</span>
 312         </dd>
 313
 314     </dl>
 315
 316     <h4><a id="elementsOSKernel">Direct kernel boot</a></h4>
 317
 318     <p>
 319       When installing a new guest OS it is often useful to boot directly
 320       from a kernel and initrd stored in the host OS, allowing command
 321       line arguments to be passed directly to the installer. This capability
 322       is usually available for both para and full virtualized guests.
 323     </p>
 324
 325 <pre>
 326 ...
 327 &lt;os&gt;
 328   &lt;type&gt;hvm&lt;/type&gt;
 329   &lt;loader&gt;/usr/lib/xen/boot/hvmloader&lt;/loader&gt;
 330   &lt;kernel&gt;/root/f8-i386-vmlinuz&lt;/kernel&gt;
 331   &lt;initrd&gt;/root/f8-i386-initrd&lt;/initrd&gt;
 332   &lt;cmdline&gt;console=ttyS0 ks=http://example.com/f8-i386/os/&lt;/cmdline&gt;
 333   &lt;dtb&gt;/root/ppc.dtb&lt;/dtb&gt;
 334   &lt;acpi&gt;
 335     &lt;table type='slic'&gt;/path/to/slic.dat&lt;/table&gt;
 336   &lt;/acpi&gt;
 337 &lt;/os&gt;
 338 ...</pre>
 339
 340     <dl>
 341       <dt><code>type</code></dt>
 342       <dd>This element has the same semantics as described earlier in the
 343         <a href="#elementsOSBIOS">BIOS boot section</a></dd>
 344       <dt><code>loader</code></dt>
 345       <dd>This element has the same semantics as described earlier in the
 346         <a href="#elementsOSBIOS">BIOS boot section</a></dd>
 347       <dt><code>kernel</code></dt>
 348       <dd>The contents of this element specify the fully-qualified path
 349         to the kernel image in the host OS.</dd>
 350       <dt><code>initrd</code></dt>
 351       <dd>The contents of this element specify the fully-qualified path
 352         to the (optional) ramdisk image in the host OS.</dd>
 353       <dt><code>cmdline</code></dt>
 354       <dd>The contents of this element specify arguments to be passed to
 355         the kernel (or installer) at boot time. This is often used to
 356         specify an alternate primary console (eg serial port), or the
 357         installation media source / kickstart file</dd>
 358       <dt><code>dtb</code></dt>
 359       <dd>The contents of this element specify the fully-qualified path
 360         to the (optional) device tree binary (dtb) image in the host OS.
 361         <span class="since">Since 1.0.4</span></dd>
 362       <dt><code>acpi</code></dt>
 363       <dd>The <code>table</code> element contains a fully-qualified path
 364         to the ACPI table. The <code>type</code> attribute contains the
 365         ACPI table type (currently only <code>slic</code> is supported)
 366         <span class="since">Since 1.3.5 (QEMU only)</span></dd>
 367     </dl>
 368
 369     <h4><a id="elementsOSContainer">Container boot</a></h4>
 370
 371     <p>
 372       When booting a domain using container based virtualization, instead
 373       of a kernel / boot image, a path to the init binary is required, using
 374       the <code>init</code> element. By default this will be launched with
 375       no arguments. To specify the initial argv, use the <code>initarg</code>
 376       element, repeated as many time as is required. The <code>cmdline</code>
 377       element, if set will be used to provide an equivalent to <code>/proc/cmdline</code>
 378       but will not affect init argv.
 379     </p>
 380     <p>
 381       To set environment variables, use the <code>initenv</code> element, one
 382       for each variable.
 383     </p>
 384     <p>
 385       To set a custom work directory for the init, use the <code>initdir</code>
 386       element.
 387     </p>
 388     <p>
 389       To run the init command as a given user or group, use the <code>inituser</code>
 390       or <code>initgroup</code> elements respectively. Both elements can be provided
 391       either a user (resp. group) id or a name. Prefixing the user or group id with
 392       a <code>+</code> will force it to be considered like a numeric value. Without
 393       this, it will be first tried as a user or group name.
 394     </p>
 395
 396     <pre>
 397 &lt;os&gt;
 398   &lt;type arch='x86_64'&gt;exe&lt;/type&gt;
 399   &lt;init&gt;/bin/systemd&lt;/init&gt;
 400   &lt;initarg&gt;--unit&lt;/initarg&gt;
 401   &lt;initarg&gt;emergency.service&lt;/initarg&gt;
 402   &lt;initenv name='MYENV'&gt;some value&lt;/initenv&gt;
 403   &lt;initdir&gt;/my/custom/cwd&lt;/initdir&gt;
 404   &lt;inituser&gt;tester&lt;/inituser&gt;
 405   &lt;initgroup&gt;1000&lt;/initgroup&gt;
 406 &lt;/os&gt;
 407     </pre>
 408
 409
 410     <p>
 411       If you want to enable user namespace, set the <code>idmap</code> element.
 412       The <code>uid</code> and <code>gid</code> elements have three attributes:
 413     </p>
 414
 415     <dl>
 416       <dt><code>start</code></dt>
 417       <dd>First user ID in container. It must be '0'.</dd>
 418       <dt><code>target</code></dt>
 419       <dd>The first user ID in container will be mapped to this target user
 420           ID in host.</dd>
 421       <dt><code>count</code></dt>
 422       <dd>How many users in container are allowed to map to host's user.</dd>
 423     </dl>
 424
 425     <pre>
 426 &lt;idmap&gt;
 427   &lt;uid start='0' target='1000' count='10'/&gt;
 428   &lt;gid start='0' target='1000' count='10'/&gt;
 429 &lt;/idmap&gt;
 430     </pre>
 431
 432
 433     <h3><a id="elementsSysinfo">SMBIOS System Information</a></h3>
 434
 435     <p>
 436       Some hypervisors allow control over what system information is
 437       presented to the guest (for example, SMBIOS fields can be
 438       populated by a hypervisor and inspected via
 439       the <code>dmidecode</code> command in the guest).  The
 440       optional <code>sysinfo</code> element covers all such categories
 441       of information. <span class="since">Since 0.8.7</span>
 442     </p>
 443
 444 <pre>
 445 ...
 446 &lt;os&gt;
 447   &lt;smbios mode='sysinfo'/&gt;
 448   ...
 449 &lt;/os&gt;
 450 &lt;sysinfo type='smbios'&gt;
 451   &lt;bios&gt;
 452     &lt;entry name='vendor'&gt;LENOVO&lt;/entry&gt;
 453   &lt;/bios&gt;
 454   &lt;system&gt;
 455     &lt;entry name='manufacturer'&gt;Fedora&lt;/entry&gt;
 456     &lt;entry name='product'&gt;Virt-Manager&lt;/entry&gt;
 457     &lt;entry name='version'&gt;0.9.4&lt;/entry&gt;
 458   &lt;/system&gt;
 459   &lt;baseBoard&gt;
 460     &lt;entry name='manufacturer'&gt;LENOVO&lt;/entry&gt;
 461     &lt;entry name='product'&gt;20BE0061MC&lt;/entry&gt;
 462     &lt;entry name='version'&gt;0B98401 Pro&lt;/entry&gt;
 463     &lt;entry name='serial'&gt;W1KS427111E&lt;/entry&gt;
 464   &lt;/baseBoard&gt;
 465   &lt;chassis&gt;
 466     &lt;entry name='manufacturer'&gt;Dell Inc.&lt;/entry&gt;
 467     &lt;entry name='version'&gt;2.12&lt;/entry&gt;
 468     &lt;entry name='serial'&gt;65X0XF2&lt;/entry&gt;
 469     &lt;entry name='asset'&gt;40000101&lt;/entry&gt;
 470     &lt;entry name='sku'&gt;Type3Sku1&lt;/entry&gt;
 471   &lt;/chassis&gt;
 472   &lt;oemStrings&gt;
 473     &lt;entry&gt;myappname:some arbitrary data&lt;/entry&gt;
 474     &lt;entry&gt;otherappname:more arbitrary data&lt;/entry&gt;
 475   &lt;/oemStrings&gt;
 476 &lt;/sysinfo&gt;
 477 ...</pre>
 478
 479     <p>
 480       The <code>sysinfo</code> element has a mandatory
 481       attribute <code>type</code> that determine the layout of
 482       sub-elements, with supported values of:
 483     </p>
 484
 485     <dl>
 486       <dt><code>smbios</code></dt>
 487       <dd>Sub-elements call out specific SMBIOS values, which will
 488       affect the guest if used in conjunction with
 489       the <code>smbios</code> sub-element of
 490       the <a href="#elementsOS"><code>os</code></a> element.  Each
 491       sub-element of <code>sysinfo</code> names a SMBIOS block, and
 492       within those elements can be a list of <code>entry</code>
 493       elements that describe a field within the block.  The following
 494       blocks and entries are recognized:
 495         <dl>
 496           <dt><code>bios</code></dt>
 497           <dd>
 498             This is block 0 of SMBIOS, with entry names drawn from:
 499             <dl>
 500                <dt><code>vendor</code></dt>
 501                <dd>BIOS Vendor's Name</dd>
 502                <dt><code>version</code></dt>
 503                <dd>BIOS Version</dd>
 504                <dt><code>date</code></dt>
 505                <dd>BIOS release date. If supplied, is in either mm/dd/yy or
 506                    mm/dd/yyyy format. If the year portion of the string is
 507                    two digits, the year is assumed to be 19yy.</dd>
 508                <dt><code>release</code></dt>
 509                <dd>System BIOS Major and Minor release number values
 510                    concatenated together as one string separated by
 511                    a period, for example, 10.22.</dd>
 512            </dl>
 513           </dd>
 514           <dt><code>system</code></dt>
 515           <dd>
 516             This is block 1 of SMBIOS, with entry names drawn from:
 517             <dl>
 518                 <dt><code>manufacturer</code></dt>
 519                 <dd>Manufacturer of BIOS</dd>
 520                 <dt><code>product</code></dt>
 521                 <dd>Product Name</dd>
 522                 <dt><code>version</code></dt>
 523                 <dd>Version of the product</dd>
 524                 <dt><code>serial</code></dt>
 525                 <dd>Serial number</dd>
 526                 <dt><code>uuid</code></dt>
 527                 <dd>Universal Unique ID number. If this entry is provided
 528                 alongside a top-level
 529                 <a href="#elementsMetadata"><code>uuid</code></a> element,
 530                 then the two values must match.</dd>
 531                 <dt><code>sku</code></dt>
 532                 <dd>SKU number to identify a particular configuration.</dd>
 533                 <dt><code>family</code></dt>
 534                 <dd>Identify the family a particular computer belongs to.</dd>
 535             </dl>
 536           </dd>
 537           <dt><code>baseBoard</code></dt>
 538           <dd>
 539             This is block 2 of SMBIOS. This element can be repeated multiple
 540             times to describe all the base boards; however, not all
 541             hypervisors necessarily support the repetition. The element can
 542             have the following children:
 543             <dl>
 544                 <dt><code>manufacturer</code></dt>
 545                 <dd>Manufacturer of BIOS</dd>
 546                 <dt><code>product</code></dt>
 547                 <dd>Product Name</dd>
 548                 <dt><code>version</code></dt>
 549                 <dd>Version of the product</dd>
 550                 <dt><code>serial</code></dt>
 551                 <dd>Serial number</dd>
 552                 <dt><code>asset</code></dt>
 553                 <dd>Asset tag</dd>
 554                 <dt><code>location</code></dt>
 555                 <dd>Location in chassis</dd>
 556             </dl>
 557             NB: Incorrectly supplied entries for the
 558             <code>bios</code>, <code>system</code> or <code>baseBoard</code>
 559             blocks will be ignored without error.  Other than <code>uuid</code>
 560             validation and <code>date</code> format checking, all values are
 561             passed as strings to the hypervisor driver.
 562           </dd>
 563           <dt><code>chassis</code></dt>
 564           <dd>
 565             <span class="since">Since 4.1.0,</span> this is block 3 of
 566             SMBIOS, with entry names drawn from:
 567             <dl>
 568                 <dt><code>manufacturer</code></dt>
 569                 <dd>Manufacturer of Chassis</dd>
 570                 <dt><code>version</code></dt>
 571                 <dd>Version of the Chassis</dd>
 572                 <dt><code>serial</code></dt>
 573                 <dd>Serial number</dd>
 574                 <dt><code>asset</code></dt>
 575                 <dd>Asset tag</dd>
 576                 <dt><code>sku</code></dt>
 577                 <dd>SKU number</dd>
 578             </dl>
 579           </dd>
 580           <dt><code>oemStrings</code></dt>
 581           <dd>
 582             This is block 11 of SMBIOS. This element should appear once and
 583             can have multiple <code>entry</code> child elements, each providing
 584             arbitrary string data. There are no restrictions on what data can
 585             be provided in the entries, however, if the data is intended to be
 586             consumed by an application in the guest, it is recommended to use
 587             the application name as a prefix in the string. (<span class="since">Since 4.1.0</span>)
 588           </dd>
 589         </dl>
 590       </dd>
 591     </dl>
 592
 593     <h3><a id="elementsCPUAllocation">CPU Allocation</a></h3>
 594
 595 <pre>
 596 &lt;domain&gt;
 597   ...
 598   &lt;vcpu placement='static' cpuset="1-4,^3,6" current="1"&gt;2&lt;/vcpu&gt;
 599   &lt;vcpus&gt;
 600     &lt;vcpu id='0' enabled='yes' hotpluggable='no' order='1'/&gt;
 601     &lt;vcpu id='1' enabled='no' hotpluggable='yes'/&gt;
 602   &lt;/vcpus&gt;
 603   ...
 604 &lt;/domain&gt;
 605 </pre>
 606
 607     <dl>
 608       <dt><code>vcpu</code></dt>
 609       <dd>The content of this element defines the maximum number of virtual
 610         CPUs allocated for the guest OS, which must be between 1 and
 611         the maximum supported by the hypervisor.
 612         <dl>
 613          <dt><code>cpuset</code></dt>
 614          <dd>
 615            The optional attribute <code>cpuset</code> is a comma-separated
 616            list of physical CPU numbers that domain process and virtual CPUs
 617            can be pinned to by default. (NB: The pinning policy of domain
 618            process and virtual CPUs can be specified separately by
 619            <code>cputune</code>. If the attribute <code>emulatorpin</code>
 620            of <code>cputune</code> is specified, the <code>cpuset</code>
 621            specified by <code>vcpu</code> here will be ignored. Similarly,
 622            for virtual CPUs which have the <code>vcpupin</code> specified,
 623            the <code>cpuset</code> specified by <code>cpuset</code> here
 624            will be ignored. For virtual CPUs which don't have
 625            <code>vcpupin</code> specified, each will be pinned to the physical
 626            CPUs specified by <code>cpuset</code> here).
 627            Each element in that list is either a single CPU number,
 628            a range of CPU numbers, or a caret followed by a CPU number to
 629            be excluded from a previous range.
 630            <span class="since">Since 0.4.4</span>
 631          </dd>
 632          <dt><code>current</code></dt>
 633          <dd>
 634            The optional attribute <code>current</code> can
 635            be used to specify whether fewer than the maximum number of
 636            virtual CPUs should be enabled.
 637            <span class="since">Since 0.8.5</span>
 638          </dd>
 639          <dt><code>placement</code></dt>
 640          <dd>
 641            The optional attribute <code>placement</code> can be used to
 642            indicate the CPU placement mode for domain process. The value can
 643            be either "static" or "auto", but defaults to <code>placement</code>
 644            of <code>numatune</code> or "static" if <code>cpuset</code> is
 645            specified. Using "auto" indicates the domain process will be pinned
 646            to the advisory nodeset from querying numad and the value of
 647            attribute <code>cpuset</code> will be ignored if it's specified.
 648            If both <code>cpuset</code> and <code>placement</code> are not
 649            specified or if <code>placement</code> is "static", but no
 650            <code>cpuset</code> is specified, the domain process will be
 651            pinned to all the available physical CPUs.
 652            <span class="since">Since 0.9.11 (QEMU and KVM only)</span>
 653          </dd>
 654         </dl>
 655       </dd>
 656       <dt><code>vcpus</code></dt>
 657       <dd>
 658         The vcpus element allows to control state of individual vCPUs.
 659
 660         The <code>id</code> attribute specifies the vCPU id as used by libvirt
 661         in other places such as vCPU pinning, scheduler information and NUMA
 662         assignment. Note that the vCPU ID as seen in the guest may differ from
 663         libvirt ID in certain cases. Valid IDs are from 0 to the maximum vCPU
 664         count as set by the <code>vcpu</code> element minus 1.
 665
 666         The <code>enabled</code> attribute allows to control the state of the
 667         vCPU. Valid values are <code>yes</code> and <code>no</code>.
 668
 669         <code>hotpluggable</code> controls whether given vCPU can be hotplugged
 670         and hotunplugged in cases when the CPU is enabled at boot. Note that
 671         all disabled vCPUs must be hotpluggable. Valid values are
 672         <code>yes</code> and <code>no</code>.
 673
 674         <code>order</code> allows to specify the order to add the online vCPUs.
 675         For hypervisors/platforms that require to insert multiple vCPUs at once
 676         the order may be duplicated across all vCPUs that need to be
 677         enabled at once. Specifying order is not necessary, vCPUs are then
 678         added in an arbitrary order. If order info is used, it must be used for
 679         all online vCPUs. Hypervisors may clear or update ordering information
 680         during certain operations to assure valid configuration.
 681
 682         Note that hypervisors may create hotpluggable vCPUs differently from
 683         boot vCPUs thus special initialization may be necessary.
 684
 685         Hypervisors may require that vCPUs enabled on boot which are not
 686         hotpluggable are clustered at the beginning starting with ID 0. It may
 687         be also required that vCPU 0 is always present and non-hotpluggable.
 688
 689         Note that providing state for individual CPUs may be necessary to enable
 690         support of addressable vCPU hotplug and this feature may not be
 691         supported by all hypervisors.
 692
 693         For QEMU the following conditions are required. vCPU 0 needs to be
 694         enabled and non-hotpluggable. On PPC64 along with it vCPUs that are in
 695         the same core need to be enabled as well. All non-hotpluggable CPUs
 696         present at boot need to be grouped after vCPU 0.
 697         <span class="since">Since 2.2.0 (QEMU only)</span>
 698       </dd>
 699     </dl>
 700
 701     <h3><a id="elementsIOThreadsAllocation">IOThreads Allocation</a></h3>
 702       <p>
 703         IOThreads are dedicated event loop threads for supported disk
 704         devices to perform block I/O requests in order to improve
 705         scalability especially on an SMP host/guest with many LUNs.
 706         <span class="since">Since 1.2.8 (QEMU only)</span>
 707       </p>
 708
 709 <pre>
 710 &lt;domain&gt;
 711   ...
 712   &lt;iothreads&gt;4&lt;/iothreads&gt;
 713   ...
 714 &lt;/domain&gt;
 715 </pre>
 716 <pre>
 717 &lt;domain&gt;
 718   ...
 719   &lt;iothreadids&gt;
 720     &lt;iothread id="2"/&gt;
 721     &lt;iothread id="4"/&gt;
 722     &lt;iothread id="6"/&gt;
 723     &lt;iothread id="8"/&gt;
 724   &lt;/iothreadids&gt;
 725   ...
 726 &lt;/domain&gt;
 727 </pre>
 728
 729     <dl>
 730       <dt><code>iothreads</code></dt>
 731       <dd>
 732         The content of this optional element defines the number
 733         of IOThreads to be assigned to the domain for use by
 734         supported target storage devices. There
 735         should be only 1 or 2 IOThreads per host CPU. There may be more
 736         than one supported device assigned to each IOThread.
 737         <span class="since">Since 1.2.8</span>
 738       </dd>
 739       <dt><code>iothreadids</code></dt>
 740       <dd>
 741         The optional <code>iothreadids</code> element provides the capability
 742         to specifically define the IOThread ID's for the domain.  By default,
 743         IOThread ID's are sequentially numbered starting from 1 through the
 744         number of <code>iothreads</code> defined for the domain. The
 745         <code>id</code> attribute is used to define the IOThread ID. The
 746         <code>id</code> attribute must be a positive integer greater than 0.
 747         If there are less <code>iothreadids</code> defined than
 748         <code>iothreads</code> defined for the domain, then libvirt will
 749         sequentially fill <code>iothreadids</code> starting at 1 avoiding
 750         any predefined <code>id</code>. If there are more
 751         <code>iothreadids</code> defined than <code>iothreads</code>
 752         defined for the domain, then the <code>iothreads</code> value
 753         will be adjusted accordingly.
 754         <span class="since">Since 1.2.15</span>
 755        </dd>
 756     </dl>
 757
 758     <h3><a id="elementsCPUTuning">CPU Tuning</a></h3>
 759
 760 <pre>
 761 &lt;domain&gt;
 762   ...
 763   &lt;cputune&gt;
 764     &lt;vcpupin vcpu="0" cpuset="1-4,^2"/&gt;
 765     &lt;vcpupin vcpu="1" cpuset="0,1"/&gt;
 766     &lt;vcpupin vcpu="2" cpuset="2,3"/&gt;
 767     &lt;vcpupin vcpu="3" cpuset="0,4"/&gt;
 768     &lt;emulatorpin cpuset="1-3"/&gt;
 769     &lt;iothreadpin iothread="1" cpuset="5,6"/&gt;
 770     &lt;iothreadpin iothread="2" cpuset="7,8"/&gt;
 771     &lt;shares&gt;2048&lt;/shares&gt;
 772     &lt;period&gt;1000000&lt;/period&gt;
 773     &lt;quota&gt;-1&lt;/quota&gt;
 774     &lt;global_period&gt;1000000&lt;/global_period&gt;
 775     &lt;global_quota&gt;-1&lt;/global_quota&gt;
 776     &lt;emulator_period&gt;1000000&lt;/emulator_period&gt;
 777     &lt;emulator_quota&gt;-1&lt;/emulator_quota&gt;
 778     &lt;iothread_period&gt;1000000&lt;/iothread_period&gt;
 779     &lt;iothread_quota&gt;-1&lt;/iothread_quota&gt;
 780     &lt;vcpusched vcpus='0-4,^3' scheduler='fifo' priority='1'/&gt;
 781     &lt;iothreadsched iothreads='2' scheduler='batch'/&gt;
 782     &lt;cachetune vcpus='0-3'&gt;
 783       &lt;cache id='0' level='3' type='both' size='3' unit='MiB'/&gt;
 784       &lt;cache id='1' level='3' type='both' size='3' unit='MiB'/&gt;
 785       &lt;monitor level='3' vcpus='1'/&gt;
 786       &lt;monitor level='3' vcpus='0-3'/&gt;
 787     &lt;/cachetune&gt;
 788     &lt;cachetune vcpus='4-5'&gt;
 789       &lt;monitor level='3' vcpus='4'/&gt;
 790       &lt;monitor level='3' vcpus='5'/&gt;
 791     &lt;/cachetune&gt;
 792     &lt;memorytune vcpus='0-3'&gt;
 793       &lt;node id='0' bandwidth='60'/&gt;
 794     &lt;/memorytune&gt;
 795
 796   &lt;/cputune&gt;
 797   ...
 798 &lt;/domain&gt;
 799 </pre>
 800
 801     <dl>
 802       <dt><code>cputune</code></dt>
 803       <dd>
 804          The optional <code>cputune</code> element provides details
 805          regarding the CPU tunable parameters for the domain.
 806          <span class="since">Since 0.9.0</span>
 807       </dd>
 808       <dt><code>vcpupin</code></dt>
 809       <dd>
 810         The optional <code>vcpupin</code> element specifies which of host's
 811         physical CPUs the domain vCPU will be pinned to. If this is omitted,
 812         and attribute <code>cpuset</code> of element <code>vcpu</code> is
 813         not specified, the vCPU is pinned to all the physical CPUs by default.
 814         It contains two required attributes, the attribute <code>vcpu</code>
 815         specifies vCPU id, and the attribute <code>cpuset</code> is same as
 816         attribute <code>cpuset</code> of element <code>vcpu</code>.
 817         (NB: Only qemu driver support)
 818         <span class="since">Since 0.9.0</span>
 819        </dd>
 820        <dt><code>emulatorpin</code></dt>
 821        <dd>
 822          The optional <code>emulatorpin</code> element specifies which of host
 823          physical CPUs the "emulator", a subset of a domain not including vCPU
 824          or iothreads will be pinned to. If this is omitted, and attribute
 825          <code>cpuset</code> of element <code>vcpu</code> is not specified,
 826          "emulator" is pinned to all the physical CPUs by default. It contains
 827          one required attribute <code>cpuset</code> specifying which physical
 828          CPUs to pin to.
 829        </dd>
 830        <dt><code>iothreadpin</code></dt>
 831        <dd>
 832          The optional <code>iothreadpin</code> element specifies which of host
 833          physical CPUs the IOThreads will be pinned to. If this is omitted
 834          and attribute <code>cpuset</code> of element <code>vcpu</code> is
 835          not specified, the IOThreads are pinned to all the physical CPUs
 836          by default. There are two required attributes, the attribute
 837          <code>iothread</code> specifies the IOThread ID and the attribute
 838          <code>cpuset</code> specifying which physical CPUs to pin to. See
 839          the <code>iothreadids</code>
 840          <a href="#elementsIOThreadsAllocation"><code>description</code></a>
 841          for valid <code>iothread</code> values.
 842         <span class="since">Since 1.2.9</span>
 843        </dd>
 844       <dt><code>shares</code></dt>
 845       <dd>
 846         The optional <code>shares</code> element specifies the proportional
 847         weighted share for the domain. If this is omitted, it defaults to
 848         the OS provided defaults. NB, There is no unit for the value,
 849         it's a relative measure based on the setting of other VM,
 850         e.g. A VM configured with value
 851         2048 will get twice as much CPU time as a VM configured with value 1024.
 852         <span class="since">Since 0.9.0</span>
 853       </dd>
 854       <dt><code>period</code></dt>
 855       <dd>
 856         The optional <code>period</code> element specifies the enforcement
 857         interval (unit: microseconds). Within <code>period</code>, each vCPU of
 858         the domain will not be allowed to consume more than <code>quota</code>
 859         worth of runtime. The value should be in range [1000, 1000000]. A period
 860         with value 0 means no value.
 861         <span class="since">Only QEMU driver support since 0.9.4, LXC since
 862         0.9.10</span>
 863       </dd>
 864       <dt><code>quota</code></dt>
 865       <dd>
 866         The optional <code>quota</code> element specifies the maximum allowed
 867         bandwidth (unit: microseconds). A domain with <code>quota</code> as any
 868         negative value indicates that the domain has infinite bandwidth for
 869         vCPU threads, which means that it is not bandwidth controlled. The value
 870         should be in range [1000, 18446744073709551] or less than 0. A quota
 871         with value 0 means no value. You can use this feature to ensure that all
 872         vCPUs run at the same speed.
 873         <span class="since">Only QEMU driver support since 0.9.4, LXC since
 874         0.9.10</span>
 875       </dd>
 876       <dt><code>global_period</code></dt>
 877       <dd>
 878         The optional <code>global_period</code> element specifies the
 879         enforcement CFS scheduler interval (unit: microseconds) for the whole
 880         domain in contrast with <code>period</code> which enforces the interval
 881         per vCPU. The value should be in range 1000, 1000000]. A
 882         <code>global_period</code> with value 0 means no value.
 883         <span class="since">Only QEMU driver support since 1.3.3</span>
 884       </dd>
 885       <dt><code>global_quota</code></dt>
 886       <dd>
 887         The optional <code>global_quota</code> element specifies the maximum
 888         allowed bandwidth (unit: microseconds) within a period for the whole
 889         domain. A domain with <code>global_quota</code> as any negative
 890         value indicates that the domain has infinite bandwidth, which means that
 891         it is not bandwidth controlled. The value should be in range
 892         [1000, 18446744073709551] or less than 0. A <code>global_quota</code>
 893         with value 0 means no value.
 894         <span class="since">Only QEMU driver support since 1.3.3</span>
 895       </dd>
 896
 897       <dt><code>emulator_period</code></dt>
 898       <dd>
 899         The optional <code>emulator_period</code> element specifies the enforcement
 900         interval (unit: microseconds). Within <code>emulator_period</code>, emulator
 901         threads (those excluding vCPUs) of the domain will not be allowed to consume
 902         more than <code>emulator_quota</code> worth of runtime. The value should be
 903         in range [1000, 1000000]. A period with value 0 means no value.
 904         <span class="since">Only QEMU driver support since 0.10.0</span>
 905       </dd>
 906       <dt><code>emulator_quota</code></dt>
 907       <dd>
 908         The optional <code>emulator_quota</code> element specifies the maximum
 909         allowed bandwidth (unit: microseconds) for domain's emulator threads (those
 910         excluding vCPUs). A domain with <code>emulator_quota</code> as any negative
 911         value indicates that the domain has infinite bandwidth for emulator threads
 912         (those excluding vCPUs), which means that it is not bandwidth controlled.
 913         The value should be in range [1000, 18446744073709551] or less than 0. A
 914         quota with value 0 means no value.
 915         <span class="since">Only QEMU driver support since 0.10.0</span>
 916       </dd>
 917
 918       <dt><code>iothread_period</code></dt>
 919       <dd>
 920         The optional <code>iothread_period</code> element specifies the
 921         enforcement interval (unit: microseconds) for IOThreads. Within
 922         <code>iothread_period</code>, each IOThread of the domain will
 923         not be allowed to consume more than <code>iothread_quota</code>
 924         worth of runtime. The value should be in range [1000, 1000000].
 925         An iothread_period with value 0 means no value.
 926         <span class="since">Only QEMU driver support since 2.1.0</span>
 927       </dd>
 928       <dt><code>iothread_quota</code></dt>
 929       <dd>
 930         The optional <code>iothread_quota</code> element specifies the maximum
 931         allowed bandwidth (unit: microseconds) for IOThreads. A domain with
 932         <code>iothread_quota</code> as any negative value indicates that the
 933         domain IOThreads have infinite bandwidth, which means that it is
 934         not bandwidth controlled. The value should be in range
 935         [1000, 18446744073709551] or less than 0. An <code>iothread_quota</code>
 936         with value 0 means no value. You can use this feature to ensure that
 937         all IOThreads run at the same speed.
 938         <span class="since">Only QEMU driver support since 2.1.0</span>
 939       </dd>
 940
 941       <dt><code>vcpusched</code>, <code>iothreadsched</code>
 942       and <code>emulatorsched</code></dt>
 943       <dd>
 944         The optional
 945         <code>vcpusched</code>, <code>iothreadsched</code>
 946         and <code>emulatorsched</code> elements specify the scheduler type
 947         (values <code>batch</code>, <code>idle</code>, <code>fifo</code>,
 948         <code>rr</code>) for particular vCPU, IOThread and emulator threads
 949         respecively.  For <code>vcpusched</code> and <code>iothreadsched</code>
 950         the attributes <code>vcpus</code> and <code>iothreads</code> select
 951         which vCPUs/IOThreads this setting applies to, leaving them out sets the
 952         default.  The element <code>emulatorsched</code> does not have that
 953         attribute. Valid <code>vcpus</code> values start at 0 through one less
 954         than the number of vCPU's defined for the
 955         domain. Valid <code>iothreads</code> values are described in
 956         the <code>iothreadids</code>
 957         <a href="#elementsIOThreadsAllocation"><code>description</code></a>.
 958         If no <code>iothreadids</code> are defined, then libvirt numbers
 959         IOThreads from 1 to the number of <code>iothreads</code> available
 960         for the domain. For real-time schedulers (<code>fifo</code>,
 961         <code>rr</code>), priority must be specified as
 962         well (and is ignored for non-real-time ones). The value range
 963         for the priority depends on the host kernel (usually 1-99).
 964         <span class="since">Since 1.2.13</span>
 965         <code>emulatorsched</code> <span class="since">since 5.3.0</span>
 966       </dd>
 967
 968       <dt><code>cachetune</code><span class="since">Since 4.1.0</span></dt>
 969       <dd>
 970         Optional <code>cachetune</code> element can control allocations for CPU
 971         caches using the resctrl on the host. Whether or not is this supported
 972         can be gathered from capabilities where some limitations like minimum
 973         size and required granularity are reported as well. The required
 974         attribute <code>vcpus</code> specifies to which vCPUs this allocation
 975         applies. A vCPU can only be member of one <code>cachetune</code> element
 976         allocation. The vCPUs specified by cachetune can be identical with those
 977         in memorytune, however they are not allowed to overlap.
 978         Supported subelements are:
 979         <dl>
 980           <dt><code>cache</code></dt>
 981           <dd>
 982             This optional element controls the allocation of CPU cache and has
 983             the following attributes:
 984             <dl>
 985               <dt><code>level</code></dt>
 986               <dd>
 987                 Host cache level from which to allocate.
 988               </dd>
 989               <dt><code>id</code></dt>
 990               <dd>
 991                 Host cache id from which to allocate.
 992               </dd>
 993               <dt><code>type</code></dt>
 994               <dd>
 995                 Type of allocation. Can be <code>code</code> for code
 996                 (instructions), <code>data</code> for data or <code>both</code>
 997                 for both code and data (unified). Currently the allocation can
 998                 be done only with the same type as the host supports, meaning
 999                 you cannot request <code>both</code> for host with CDP
1000                 (code/data prioritization) enabled.
1001               </dd>
1002               <dt><code>size</code></dt>
1003               <dd>
1004                 The size of the region to allocate. The value by default is in
1005                 bytes, but the <code>unit</code> attribute can be used to scale
1006                 the value.
1007               </dd>
1008               <dt><code>unit</code> (optional)</dt>
1009               <dd>
1010                 If specified it is the unit such as KiB, MiB, GiB, or TiB
1011                 (described in the <code>memory</code> element
1012                 for <a href="#elementsMemoryAllocation">Memory Allocation</a>)
1013                 in which <code>size</code> is specified, defaults to bytes.
1014               </dd>
1015             </dl>
1016           </dd>
1017           <dt><code>monitor</code><span class="since">Since 4.10.0</span></dt>
1018           <dd>
1019             The optional element <code>monitor</code> creates the cache
1020             monitor(s) for current cache allocation and has the following
1021             required attributes:
1022             <dl>
1023               <dt><code>level</code></dt>
1024               <dd>
1025                 Host cache level the monitor belongs to.
1026               </dd>
1027               <dt><code>vcpus</code></dt>
1028               <dd>
1029                 vCPU list the monitor applies to. A monitor's vCPU list
1030                 can only be the member(s) of the vCPU list of the associated
1031                 allocation. The default monitor has the same vCPU list as the
1032                 associated allocation. For non-default monitors, overlapping
1033                 vCPUs are not permitted.
1034               </dd>
1035             </dl>
1036           </dd>
1037         </dl>
1038       </dd>
1039
1040       <dt><code>memorytune</code><span class="since">Since 4.7.0</span></dt>
1041       <dd>
1042         Optional <code>memorytune</code> element can control allocations for
1043         memory bandwidth using the resctrl on the host. Whether or not is this
1044         supported can be gathered from capabilities where some limitations like
1045         minimum bandwidth and required granularity are reported as well. The
1046         required attribute <code>vcpus</code> specifies to which vCPUs this
1047         allocation applies. A vCPU can only be member of one
1048         <code>memorytune</code> element allocation. The <code>vcpus</code> specified
1049         by <code>memorytune</code> can be identical to those specified by
1050         <code>cachetune</code>. However they are not allowed to overlap each other.
1051         Supported subelements are:
1052         <dl>
1053           <dt><code>node</code></dt>
1054           <dd>
1055             This element controls the allocation of CPU memory bandwidth and has the
1056             following attributes:
1057             <dl>
1058               <dt><code>id</code></dt>
1059               <dd>
1060                 Host node id from which to allocate memory bandwidth.
1061               </dd>
1062               <dt><code>bandwidth</code></dt>
1063               <dd>
1064                 The memory bandwidth to allocate from this node. The value by default
1065                 is in percentage.
1066               </dd>
1067             </dl>
1068           </dd>
1069         </dl>
1070       </dd>
1071     </dl>
1072
1073
1074     <h3><a id="elementsMemoryAllocation">Memory Allocation</a></h3>
1075
1076 <pre>
1077 &lt;domain&gt;
1078   ...
1079   &lt;maxMemory slots='16' unit='KiB'&gt;1524288&lt;/maxMemory&gt;
1080   &lt;memory unit='KiB'&gt;524288&lt;/memory&gt;
1081   &lt;currentMemory unit='KiB'&gt;524288&lt;/currentMemory&gt;
1082   ...
1083 &lt;/domain&gt;
1084 </pre>
1085
1086     <dl>
1087       <dt><code>memory</code></dt>
1088       <dd>The maximum allocation of memory for the guest at boot time. The
1089         memory allocation includes possible additional memory devices specified
1090         at start or hotplugged later.
1091         The units for this value are determined by the optional
1092         attribute <code>unit</code>, which defaults to "KiB"
1093         (kibibytes, 2<sup>10</sup> or blocks of 1024 bytes).  Valid
1094         units are "b" or "bytes" for bytes, "KB" for kilobytes
1095         (10<sup>3</sup> or 1,000 bytes), "k" or "KiB" for kibibytes
1096         (1024 bytes), "MB" for megabytes (10<sup>6</sup> or 1,000,000
1097         bytes), "M" or "MiB" for mebibytes (2<sup>20</sup> or
1098         1,048,576 bytes), "GB" for gigabytes (10<sup>9</sup> or
1099         1,000,000,000 bytes), "G" or "GiB" for gibibytes
1100         (2<sup>30</sup> or 1,073,741,824 bytes), "TB" for terabytes
1101         (10<sup>12</sup> or 1,000,000,000,000 bytes), or "T" or "TiB"
1102         for tebibytes (2<sup>40</sup> or 1,099,511,627,776 bytes).
1103         However, the value will be rounded up to the nearest kibibyte
1104         by libvirt, and may be further rounded to the granularity
1105         supported by the hypervisor.  Some hypervisors also enforce a
1106         minimum, such as 4000KiB.
1107
1108         In case <a href="#elementsCPU">NUMA</a> is configured for the guest the
1109         <code>memory</code> element can be omitted.
1110
1111         In the case of crash, optional attribute <code>dumpCore</code>
1112         can be used to control whether the guest memory should be
1113         included in the generated coredump or not (values "on", "off").
1114
1115         <span class='since'><code>unit</code> since 0.9.11</span>,
1116         <span class='since'><code>dumpCore</code> since 0.10.2
1117         (QEMU only)</span></dd>
1118       <dt><code>maxMemory</code></dt>
1119       <dd>The run time maximum memory allocation of the guest. The initial
1120         memory specified by either the <code>&lt;memory&gt;</code> element or
1121         the NUMA cell size configuration can be increased by hot-plugging of
1122         memory to the limit specified by this element.
1123
1124         The <code>unit</code> attribute behaves the same as for
1125         <code>&lt;memory&gt;</code>.
1126
1127         The <code>slots</code> attribute specifies the number of slots
1128         available for adding memory to the guest. The bounds are hypervisor
1129         specific.
1130
1131         Note that due to alignment of the memory chunks added via memory
1132         hotplug the full size allocation specified by this element may be
1133         impossible to achieve.
1134         <span class='since'>Since 1.2.14 supported by the QEMU driver.</span>
1135       </dd>
1136
1137       <dt><code>currentMemory</code></dt>
1138       <dd>The actual allocation of memory for the guest. This value can
1139         be less than the maximum allocation, to allow for ballooning
1140         up the guests memory on the fly. If this is omitted, it defaults
1141         to the same value as the <code>memory</code> element.
1142         The <code>unit</code> attribute behaves the same as
1143         for <code>memory</code>.</dd>
1144     </dl>
1145
1146
1147     <h3><a id="elementsMemoryBacking">Memory Backing</a></h3>
1148
1149 <pre>
1150 &lt;domain&gt;
1151   ...
1152   &lt;memoryBacking&gt;
1153     &lt;hugepages&gt;
1154       &lt;page size="1" unit="G" nodeset="0-3,5"/&gt;
1155       &lt;page size="2" unit="M" nodeset="4"/&gt;
1156     &lt;/hugepages&gt;
1157     &lt;nosharepages/&gt;
1158     &lt;locked/&gt;
1159     &lt;source type="file|anonymous|memfd"/&gt;
1160     &lt;access mode="shared|private"/&gt;
1161     &lt;allocation mode="immediate|ondemand"/&gt;
1162     &lt;discard/&gt;
1163   &lt;/memoryBacking&gt;
1164   ...
1165 &lt;/domain&gt;
1166 </pre>
1167
1168     <p>The optional <code>memoryBacking</code> element may contain several
1169       elements that influence how virtual memory pages are backed by host
1170       pages.</p>
1171
1172     <dl>
1173       <dt><code>hugepages</code></dt>
1174       <dd>This tells the hypervisor that the guest should have its memory
1175       allocated using hugepages instead of the normal native page size.
1176       <span class='since'>Since 1.2.5</span> it's possible to set hugepages
1177       more specifically per numa node. The <code>page</code> element is
1178       introduced. It has one compulsory attribute <code>size</code> which
1179       specifies which hugepages should be used (especially useful on systems
1180       supporting hugepages of different sizes). The default unit for the
1181       <code>size</code> attribute is kilobytes (multiplier of 1024). If you
1182       want to use different unit, use optional <code>unit</code> attribute.
1183       For systems with NUMA, the optional <code>nodeset</code> attribute may
1184       come handy as it ties given guest's NUMA nodes to certain hugepage
1185       sizes. From the example snippet, one gigabyte hugepages are used for
1186       every NUMA node except node number four. For the correct syntax see
1187       <a href="#elementsNUMATuning">this</a>.</dd>
1188       <dt><code>nosharepages</code></dt>
1189       <dd>Instructs hypervisor to disable shared pages (memory merge, KSM) for
1190         this domain. <span class="since">Since 1.0.6</span></dd>
1191       <dt><code>locked</code></dt>
1192       <dd>When set and supported by the hypervisor, memory pages belonging
1193         to the domain will be locked in host's memory and the host will not
1194         be allowed to swap them out, which might be required for some
1195         workloads such as real-time. For QEMU/KVM guests, the memory used by
1196         the QEMU process itself will be locked too: unlike guest memory, this
1197         is an amount libvirt has no way of figuring out in advance, so it has
1198         to remove the limit on locked memory altogether. Thus, enabling this
1199         option opens up to a potential security risk: the host will be unable
1200         to reclaim the locked memory back from the guest when it's running out
1201         of memory, which means a malicious guest allocating large amounts of
1202         locked memory could cause a denial-of-service attack on the host.
1203         Because of this, using this option is discouraged unless your workload
1204         demands it; even then, it's highly recommended to set a
1205         <code>hard_limit</code> (see
1206         <a href="#elementsMemoryTuning">memory tuning</a>) on memory allocation
1207         suitable for the specific environment at the same time to mitigate
1208         the risks described above. <span class="since">Since 1.0.6</span></dd>
1209        <dt><code>source</code></dt>
1210        <dd>Using the <code>type</code> attribute, it's possible to
1211        provide "file" to utilize file memorybacking or keep the
1212        default "anonymous". <span class="since">Since 4.10.0</span>,
1213        you may choose "memfd" backing. (QEMU/KVM only)</dd>
1214        <dt><code>access</code></dt>
1215        <dd>Using the <code>mode</code> attribute, specify if the memory is
1216          to be "shared" or "private". This can be overridden per numa node by
1217          <code>memAccess</code>.</dd>
1218        <dt><code>allocation</code></dt>
1219        <dd>Using the <code>mode</code> attribute, specify when to allocate
1220          the memory by supplying either "immediate" or "ondemand".</dd>
1221        <dt><code>discard</code></dt>
1222        <dd>When set and supported by hypervisor the memory
1223          content is discarded just before guest shuts down (or
1224          when DIMM module is unplugged). Please note that this is
1225          just an optimization and is not guaranteed to work in
1226          all cases (e.g. when hypervisor crashes).
1227          <span class="since">Since 4.4.0</span> (QEMU/KVM only)
1228        </dd>
1229     </dl>
1230
1231
1232     <h3><a id="elementsMemoryTuning">Memory Tuning</a></h3>
1233
1234 <pre>
1235 &lt;domain&gt;
1236   ...
1237   &lt;memtune&gt;
1238     &lt;hard_limit unit='G'&gt;1&lt;/hard_limit&gt;
1239     &lt;soft_limit unit='M'&gt;128&lt;/soft_limit&gt;
1240     &lt;swap_hard_limit unit='G'&gt;2&lt;/swap_hard_limit&gt;
1241     &lt;min_guarantee unit='bytes'&gt;67108864&lt;/min_guarantee&gt;
1242   &lt;/memtune&gt;
1243   ...
1244 &lt;/domain&gt;
1245 </pre>
1246
1247     <dl>
1248       <dt><code>memtune</code></dt>
1249       <dd> The optional <code>memtune</code> element provides details
1250         regarding the memory tunable parameters for the domain. If this is
1251         omitted, it defaults to the OS provided defaults. For QEMU/KVM, the
1252         parameters are applied to the QEMU process as a whole. Thus, when
1253         counting them, one needs to add up guest RAM, guest video RAM, and
1254         some memory overhead of QEMU itself. The last piece is hard to
1255         determine so one needs guess and try.  For each tunable, it
1256         is possible to designate which unit the number is in on
1257         input, using the same values as
1258         for <code>&lt;memory&gt;</code>.  For backwards
1259         compatibility, output is always in
1260         KiB.  <span class='since'><code>unit</code>
1261         since 0.9.11</span>
1262         Possible values for all *_limit parameters are in range from 0 to
1263         VIR_DOMAIN_MEMORY_PARAM_UNLIMITED.</dd>
1264       <dt><code>hard_limit</code></dt>
1265       <dd> The optional <code>hard_limit</code> element is the maximum memory
1266         the guest can use. The units for this value are kibibytes (i.e. blocks
1267         of 1024 bytes). Users of QEMU and KVM are strongly advised not to set
1268         this limit as domain may get killed by the kernel if the guess is too
1269         low, and determining the memory needed for a process to run is an
1270         <a href="http://en.wikipedia.org/wiki/Undecidable_problem">
1271         undecidable problem</a>; that said, if you already set
1272         <code>locked</code> in
1273         <a href="#elementsMemoryBacking">memory backing</a> because your
1274         workload demands it, you'll have to take into account the specifics of
1275         your deployment and figure out a value for <code>hard_limit</code> that
1276         is large enough to support the memory requirements of your guest, but
1277         small enough to protect your host against a malicious guest locking all
1278         memory.</dd>
1279       <dt><code>soft_limit</code></dt>
1280       <dd> The optional <code>soft_limit</code> element is the memory limit to
1281         enforce during memory contention. The units for this value are
1282         kibibytes (i.e. blocks of 1024 bytes)</dd>
1283       <dt><code>swap_hard_limit</code></dt>
1284       <dd> The optional <code>swap_hard_limit</code> element is the maximum
1285         memory plus swap the guest can use. The units for this value are
1286         kibibytes (i.e. blocks of 1024 bytes). This has to be more than
1287         hard_limit value provided</dd>
1288       <dt><code>min_guarantee</code></dt>
1289       <dd> The optional <code>min_guarantee</code> element is the guaranteed
1290         minimum memory allocation for the guest. The units for this value are
1291         kibibytes (i.e. blocks of 1024 bytes). This element is only supported
1292         by VMware ESX and OpenVZ drivers.</dd>
1293     </dl>
1294
1295
1296     <h3><a id="elementsNUMATuning">NUMA Node Tuning</a></h3>
1297
1298 <pre>
1299 &lt;domain&gt;
1300   ...
1301   &lt;numatune&gt;
1302     &lt;memory mode="strict" nodeset="1-4,^3"/&gt;
1303     &lt;memnode cellid="0" mode="strict" nodeset="1"/&gt;
1304     &lt;memnode cellid="2" mode="preferred" nodeset="2"/&gt;
1305   &lt;/numatune&gt;
1306   ...
1307 &lt;/domain&gt;
1308 </pre>
1309
1310     <dl>
1311       <dt><code>numatune</code></dt>
1312       <dd>
1313         The optional <code>numatune</code> element provides details of
1314         how to tune the performance of a NUMA host via controlling NUMA policy
1315         for domain process. NB, only supported by QEMU driver.
1316         <span class='since'>Since 0.9.3</span>
1317       </dd>
1318       <dt><code>memory</code></dt>
1319       <dd>
1320         The optional <code>memory</code> element specifies how to allocate memory
1321         for the domain process on a NUMA host. It contains several optional
1322         attributes. Attribute <code>mode</code> is either 'interleave',
1323         'strict', or 'preferred', defaults to 'strict'. Attribute
1324         <code>nodeset</code> specifies the NUMA nodes, using the same syntax as
1325         attribute <code>cpuset</code> of element <code>vcpu</code>. Attribute
1326         <code>placement</code> (<span class='since'>since 0.9.12</span>) can be
1327         used to indicate the memory placement mode for domain process, its value
1328         can be either "static" or "auto", defaults to <code>placement</code> of
1329         <code>vcpu</code>, or "static" if <code>nodeset</code> is specified.
1330         "auto" indicates the domain process will only allocate memory from the
1331         advisory nodeset returned from querying numad, and the value of attribute
1332         <code>nodeset</code> will be ignored if it's specified.
1333
1334         If <code>placement</code> of <code>vcpu</code> is 'auto', and
1335         <code>numatune</code> is not specified, a default <code>numatune</code>
1336         with <code>placement</code> 'auto' and <code>mode</code> 'strict' will
1337         be added implicitly.
1338
1339         <span class='since'>Since 0.9.3</span>
1340       </dd>
1341       <dt><code>memnode</code></dt>
1342       <dd>
1343         Optional <code>memnode</code> elements can specify memory allocation
1344         policies per each guest NUMA node.  For those nodes having no
1345         corresponding <code>memnode</code> element, the default from
1346         element <code>memory</code> will be used.  Attribute <code>cellid</code>
1347         addresses guest NUMA node for which the settings are applied.
1348         Attributes <code>mode</code> and <code>nodeset</code> have the same
1349         meaning and syntax as in <code>memory</code> element.
1350
1351         This setting is not compatible with automatic placement.
1352         <span class='since'>QEMU Since 1.2.7</span>
1353       </dd>
1354     </dl>
1355
1356
1357     <h3><a id="elementsBlockTuning">Block I/O Tuning</a></h3>
1358 <pre>
1359 &lt;domain&gt;
1360   ...
1361   &lt;blkiotune&gt;
1362     &lt;weight&gt;800&lt;/weight&gt;
1363     &lt;device&gt;
1364       &lt;path&gt;/dev/sda&lt;/path&gt;
1365       &lt;weight&gt;1000&lt;/weight&gt;
1366     &lt;/device&gt;
1367     &lt;device&gt;
1368       &lt;path&gt;/dev/sdb&lt;/path&gt;
1369       &lt;weight&gt;500&lt;/weight&gt;
1370       &lt;read_bytes_sec&gt;10000&lt;/read_bytes_sec&gt;
1371       &lt;write_bytes_sec&gt;10000&lt;/write_bytes_sec&gt;
1372       &lt;read_iops_sec&gt;20000&lt;/read_iops_sec&gt;
1373       &lt;write_iops_sec&gt;20000&lt;/write_iops_sec&gt;
1374     &lt;/device&gt;
1375   &lt;/blkiotune&gt;
1376   ...
1377 &lt;/domain&gt;
1378 </pre>
1379
1380     <dl>
1381       <dt><code>blkiotune</code></dt>
1382       <dd> The optional <code>blkiotune</code> element provides the ability
1383         to tune Blkio cgroup tunable parameters for the domain. If this is
1384         omitted, it defaults to the OS provided
1385         defaults. <span class="since">Since 0.8.8</span></dd>
1386       <dt><code>weight</code></dt>
1387       <dd> The optional <code>weight</code> element is the overall I/O
1388         weight of the guest. The value should be in the range [100,
1389         1000]. After kernel 2.6.39, the value could be in the
1390         range [10, 1000].</dd>
1391       <dt><code>device</code></dt>
1392       <dd>The domain may have multiple <code>device</code> elements
1393         that further tune the weights for each host block device in
1394         use by the domain.  Note that
1395         multiple <a href="#elementsDisks">guest disks</a> can share a
1396         single host block device, if they are backed by files within
1397         the same host file system, which is why this tuning parameter
1398         is at the global domain level rather than associated with each
1399         guest disk device (contrast this to
1400         the <a href="#elementsDisks"><code>&lt;iotune&gt;</code></a>
1401         element which can apply to an
1402         individual <code>&lt;disk&gt;</code>).
1403         Each <code>device</code> element has two
1404         mandatory sub-elements, <code>path</code> describing the
1405         absolute path of the device, and <code>weight</code> giving
1406         the relative weight of that device, in the range [100,
1407         1000]. After kernel 2.6.39, the value could be in the
1408         range [10, 1000]. <span class="since">Since 0.9.8</span><br/>
1409         Additionally, the following optional sub-elements can be used:
1410         <dl>
1411           <dt><code>read_bytes_sec</code></dt>
1412           <dd>Read throughput limit in bytes per second.
1413             <span class="since">Since 1.2.2</span></dd>
1414           <dt><code>write_bytes_sec</code></dt>
1415           <dd>Write throughput limit in bytes per second.
1416             <span class="since">Since 1.2.2</span></dd>
1417           <dt><code>read_iops_sec</code></dt>
1418           <dd>Read I/O operations per second limit.
1419             <span class="since">Since 1.2.2</span></dd>
1420           <dt><code>write_iops_sec</code></dt>
1421           <dd>Write I/O operations per second limit.
1422             <span class="since">Since 1.2.2</span></dd>
1423       </dl></dd></dl>
1424
1425
1426     <h3><a id="resPartition">Resource partitioning</a></h3>
1427
1428     <p>
1429       Hypervisors may allow for virtual machines to be placed into
1430       resource partitions, potentially with nesting of said partitions.
1431       The <code>resource</code> element groups together configuration
1432       related to resource partitioning. It currently supports a child
1433       element <code>partition</code> whose content defines the absolute path
1434       of the resource partition in which to place the domain. If no
1435       partition is listed, then the domain will be placed in a default
1436       partition. It is the responsibility of the app/admin to ensure
1437       that the partition exists prior to starting the guest. Only the
1438       (hypervisor specific) default partition can be assumed to exist
1439       by default.
1440     </p>
1441 <pre>
1442 ...
1443 &lt;resource&gt;
1444   &lt;partition&gt;/virtualmachines/production&lt;/partition&gt;
1445 &lt;/resource&gt;
1446 ...
1447 </pre>
1448
1449     <p>
1450       Resource partitions are currently supported by the QEMU and
1451       LXC drivers, which map partition paths to cgroups directories,
1452       in all mounted controllers. <span class="since">Since 1.0.5</span>
1453     </p>
1454
1455     <h3><a id="elementsCPU">CPU model and topology</a></h3>
1456
1457     <p>
1458       Requirements for CPU model, its features and topology can be specified
1459       using the following collection of elements.
1460       <span class="since">Since 0.7.5</span>
1461     </p>
1462
1463 <pre>
1464 ...
1465 &lt;cpu match='exact'&gt;
1466   &lt;model fallback='allow'&gt;core2duo&lt;/model&gt;
1467   &lt;vendor&gt;Intel&lt;/vendor&gt;
1468   &lt;topology sockets='1' cores='2' threads='1'/&gt;
1469   &lt;cache level='3' mode='emulate'/&gt;
1470   &lt;feature policy='disable' name='lahf_lm'/&gt;
1471 &lt;/cpu&gt;
1472 ...</pre>
1473
1474 <pre>
1475 &lt;cpu mode='host-model'&gt;
1476   &lt;model fallback='forbid'/&gt;
1477   &lt;topology sockets='1' cores='2' threads='1'/&gt;
1478 &lt;/cpu&gt;
1479 ...</pre>
1480
1481 <pre>
1482 &lt;cpu mode='host-passthrough'&gt;
1483   &lt;cache mode='passthrough'/&gt;
1484   &lt;feature policy='disable' name='lahf_lm'/&gt;
1485 ...</pre>
1486
1487     <p>
1488       In case no restrictions need to be put on CPU model and its features, a
1489       simpler <code>cpu</code> element can be used.
1490       <span class="since">Since 0.7.6</span>
1491     </p>
1492
1493 <pre>
1494 ...
1495 &lt;cpu&gt;
1496   &lt;topology sockets='1' cores='2' threads='1'/&gt;
1497 &lt;/cpu&gt;
1498 ...</pre>
1499
1500     <dl>
1501       <dt><code>cpu</code></dt>
1502       <dd>The <code>cpu</code> element is the main container for describing
1503         guest CPU requirements. Its <code>match</code> attribute specifies how
1504         strictly the virtual CPU provided to the guest matches these
1505         requirements. <span class="since">Since 0.7.6</span> the
1506         <code>match</code> attribute can be omitted if <code>topology</code>
1507         is the only element within <code>cpu</code>. Possible values for the
1508         <code>match</code> attribute are:
1509
1510         <dl>
1511           <dt><code>minimum</code></dt>
1512           <dd>The specified CPU model and features describes the minimum
1513             requested CPU. A better CPU will be provided to the guest if it
1514             is possible with the requested hypervisor on the current host.
1515             This is a constrained <code>host-model</code> mode; the domain
1516             will not be created if the provided virtual CPU does not meet
1517             the requirements.</dd>
1518
1519           <dt><code>exact</code></dt>
1520           <dd>The virtual CPU provided to the guest should exactly match the
1521             specification. If such CPU is not supported, libvirt will refuse
1522             to start the domain.</dd>
1523
1524           <dt><code>strict</code></dt>
1525           <dd>The domain will not be created unless the host CPU exactly
1526             matches the specification. This is not very useful in practice
1527             and should only be used if there is a real reason.</dd>
1528         </dl>
1529
1530         <span class="since">Since 0.8.5</span> the <code>match</code>
1531         attribute can be omitted and will default to <code>exact</code>.
1532
1533         Sometimes the hypervisor is not able to create a virtual CPU exactly
1534         matching the specification passed by libvirt.
1535         <span class="since">Since 3.2.0</span>, an optional <code>check</code>
1536         attribute can be used to request a specific way of checking whether
1537         the virtual CPU matches the specification. It is usually safe to omit
1538         this attribute when starting a domain and stick with the default
1539         value. Once the domain starts, libvirt will automatically change the
1540         <code>check</code> attribute to the best supported value to ensure the
1541         virtual CPU does not change when the domain is migrated to another
1542         host. The following values can be used:
1543
1544         <dl>
1545           <dt><code>none</code></dt>
1546           <dd>Libvirt does no checking and it is up to the hypervisor to
1547             refuse to start the domain if it cannot provide the requested CPU.
1548             With QEMU this means no checking is done at all since the default
1549             behavior of QEMU is to emit warnings, but start the domain anyway.
1550           </dd>
1551
1552           <dt><code>partial</code></dt>
1553           <dd>Libvirt will check the guest CPU specification before starting
1554             a domain, but the rest is left on the hypervisor. It can still
1555             provide a different virtual CPU.</dd>
1556
1557           <dt><code>full</code></dt>
1558           <dd>The virtual CPU created by the hypervisor will be checked
1559             against the CPU specification and the domain will not be started
1560             unless the two CPUs match.</dd>
1561         </dl>
1562
1563         <span class="since">Since 0.9.10</span>, an optional <code>mode</code>
1564         attribute may be used to make it easier to configure a guest CPU to be
1565         as close to host CPU as possible. Possible values for the
1566         <code>mode</code> attribute are:
1567
1568         <dl>
1569           <dt><code>custom</code></dt>
1570           <dd>In this mode, the <code>cpu</code> element describes the CPU
1571           that should be presented to the guest. This is the default when no
1572           <code>mode</code> attribute is specified. This mode makes it so that
1573           a persistent guest will see the same hardware no matter what host
1574           the guest is booted on.</dd>
1575           <dt><code>host-model</code></dt>
1576           <dd>The <code>host-model</code> mode is essentially a shortcut to
1577           copying host CPU definition from capabilities XML into domain XML.
1578           Since the CPU definition is copied just before starting a domain,
1579           exactly the same XML can be used on different hosts while still
1580           providing the best guest CPU each host supports. The
1581           <code>match</code> attribute can't be used in this mode. Specifying
1582           CPU model is not supported either, but <code>model</code>'s
1583           <code>fallback</code> attribute may still be used. Using the
1584           <code>feature</code> element, specific flags may be enabled or
1585           disabled specifically in addition to the host model. This may be
1586           used to fine tune features that can be emulated.
1587           <span class="since">(Since 1.1.1)</span>.
1588           Libvirt does not model every aspect of each CPU so
1589           the guest CPU will not match the host CPU exactly. On the other
1590           hand, the ABI provided to the guest is reproducible. During
1591           migration, complete CPU model definition is transferred to the
1592           destination host so the migrated guest will see exactly the same CPU
1593           model even if the destination host contains more capable CPUs for
1594           the running instance of the guest; but shutting down and restarting
1595           the guest may present different hardware to the guest according to
1596           the capabilities of the new host. Prior to libvirt 3.2.0 and QEMU
1597           2.9.0 detection of the host CPU model via QEMU is not supported.
1598           Thus the CPU configuration created using <code>host-model</code>
1599           may not work as expected.
1600           <span class="since">Since 3.2.0 and QEMU 2.9.0</span> this mode
1601           works the way it was designed and it is indicated by the
1602           <code>fallback</code> attribute set to <code>forbid</code> in the
1603           host-model CPU definition advertised in
1604           <a href="formatdomaincaps.html#elementsCPU">domain capabilities XML</a>.
1605           When <code>fallback</code> attribute is set to <code>allow</code>
1606           in the domain capabilities XML, it is recommended to use
1607           <code>custom</code> mode with just the CPU model from the host
1608           capabilities XML. <span class="since">Since 1.2.11</span> PowerISA
1609           allows processors to run VMs in binary compatibility mode supporting
1610           an older version of ISA.  Libvirt on PowerPC architecture uses the
1611           <code>host-model</code> to signify a guest mode CPU running in
1612           binary compatibility mode. Example:
1613           When a user needs a power7 VM to run in compatibility mode
1614           on a Power8 host, this can be described in XML as follows :
1615 <pre>
1616 &lt;cpu mode='host-model'&gt;
1617   &lt;model&gt;power7&lt;/model&gt;
1618 &lt;/cpu&gt;
1619 ...</pre>
1620           </dd>
1621           <dt><code>host-passthrough</code></dt>
1622           <dd>With this mode, the CPU visible to the guest should be exactly
1623           the same as the host CPU even in the aspects that libvirt does not
1624           understand. Though the downside of this mode is that the guest
1625           environment cannot be reproduced on different hardware. Thus, if you
1626           hit any bugs, you are on your own. Further details of that CPU can
1627           be changed using <code>feature</code> elements. Migration of a guest
1628           using host-passthrough is dangerous if the source and destination
1629           hosts are not identical in both hardware and configuration. If such
1630           a migration is attempted then the guest may hang or crash upon
1631           resuming execution on the destination host.</dd>
1632         </dl>
1633
1634         Both <code>host-model</code> and <code>host-passthrough</code> modes
1635         make sense when a domain can run directly on the host CPUs (for
1636         example, domains with type <code>kvm</code>). The actual host CPU is
1637         irrelevant for domains with emulated virtual CPUs (such as domains with
1638         type <code>qemu</code>). However, for backward compatibility
1639         <code>host-model</code> may be implemented even for domains running on
1640         emulated CPUs in which case the best CPU the hypervisor is able to
1641         emulate may be used rather then trying to mimic the host CPU model.
1642       </dd>
1643
1644       <dt><code>model</code></dt>
1645       <dd>The content of the <code>model</code> element specifies CPU model
1646         requested by the guest. The list of available CPU models and their
1647         definition can be found in <code>cpu_map.xml</code> file installed
1648         in libvirt's data directory. If a hypervisor is not able to use the
1649         exact CPU model, libvirt automatically falls back to a closest model
1650         supported by the hypervisor while maintaining the list of CPU
1651         features. <span class="since">Since 0.9.10</span>, an optional
1652         <code>fallback</code> attribute can be used to forbid this behavior,
1653         in which case an attempt to start a domain requesting an unsupported
1654         CPU model will fail. Supported values for <code>fallback</code>
1655         attribute are: <code>allow</code> (this is the default), and
1656         <code>forbid</code>. The optional <code>vendor_id</code> attribute
1657         (<span class="since">Since 0.10.0</span>)  can be used to set the
1658         vendor id seen by the guest. It must be exactly 12 characters long.
1659         If not set the vendor id of the host is used. Typical possible
1660         values are "AuthenticAMD" and "GenuineIntel".</dd>
1661
1662       <dt><code>vendor</code></dt>
1663       <dd><span class="since">Since 0.8.3</span> the content of the
1664         <code>vendor</code> element specifies CPU vendor requested by the
1665         guest. If this element is missing, the guest can be run on a CPU
1666         matching given features regardless on its vendor. The list of
1667         supported vendors can be found in <code>cpu_map.xml</code>.</dd>
1668
1669       <dt><code>topology</code></dt>
1670       <dd>The <code>topology</code> element specifies requested topology of
1671         virtual CPU provided to the guest. Three non-zero values have to be
1672         given for <code>sockets</code>, <code>cores</code>, and
1673         <code>threads</code>: total number of CPU sockets, number of cores per
1674         socket, and number of threads per core, respectively. Hypervisors may
1675         require that the maximum number of vCPUs specified by the
1676         <code>cpus</code> element equals to the number of vcpus resulting
1677         from the topology.</dd>
1678
1679       <dt><code>feature</code></dt>
1680       <dd>The <code>cpu</code> element can contain zero or more
1681         <code>elements</code> used to fine-tune features provided by the
1682         selected CPU model. The list of known feature names can be found in
1683         the same file as CPU models. The meaning of each <code>feature</code>
1684         element depends on its <code>policy</code> attribute, which has to be
1685         set to one of the following values:
1686
1687         <dl>
1688           <dt><code>force</code></dt>
1689           <dd>The virtual CPU will claim the feature is supported regardless
1690             of it being supported by host CPU.</dd>
1691           <dt><code>require</code></dt>
1692           <dd>Guest creation will fail unless the feature is supported by the
1693             host CPU or the hypervisor is able to emulate it.</dd>
1694           <dt><code>optional</code></dt>
1695           <dd>The feature will be supported by virtual CPU if and only if it
1696             is supported by host CPU.</dd>
1697           <dt><code>disable</code></dt>
1698           <dd>The feature will not be supported by virtual CPU.</dd>
1699           <dt><code>forbid</code></dt>
1700           <dd>Guest creation will fail if the feature is supported by host
1701             CPU.</dd>
1702         </dl>
1703
1704         <span class="since">Since 0.8.5</span> the <code>policy</code>
1705         attribute can be omitted and will default to <code>require</code>.
1706
1707         <p> Individual CPU feature names are specified as part of the
1708         <code>name</code> attribute. For example, to explicitly specify
1709         the 'pcid' feature with Intel IvyBridge CPU model:
1710         </p>
1711
1712 <pre>
1713 ...
1714 &lt;cpu match='exact'&gt;
1715   &lt;model fallback='forbid'&gt;IvyBridge&lt;/model&gt;
1716   &lt;vendor&gt;Intel&lt;/vendor&gt;
1717   &lt;feature policy='require' name='pcid'/&gt;
1718 &lt;/cpu&gt;
1719 ...</pre>
1720
1721       </dd>
1722
1723       <dt><code>cache</code></dt>
1724       <dd><span class="since">Since 3.3.0</span> the <code>cache</code>
1725         element describes the virtual CPU cache. If the element is missing,
1726         the hypervisor will use a sensible default.
1727
1728         <dl>
1729           <dt><code>level</code></dt>
1730           <dd>This optional attribute specifies which cache level is described
1731             by the element. Missing attribute means the element describes all
1732             CPU cache levels at once. Mixing <code>cache</code> elements with
1733             the <code>level</code> attribute set and those without the
1734             attribute is forbidden.</dd>
1735
1736           <dt><code>mode</code></dt>
1737           <dd>
1738             The following values are supported:
1739             <dl>
1740               <dt><code>emulate</code></dt>
1741               <dd>The hypervisor will provide a fake CPU cache data.</dd>
1742
1743               <dt><code>passthrough</code></dt>
1744               <dd>The real CPU cache data reported by the host CPU will be
1745                 passed through to the virtual CPU.</dd>
1746
1747               <dt><code>disable</code></dt>
1748               <dd>The virtual CPU will report no CPU cache of the specified
1749                 level (or no cache at all if the <code>level</code> attribute
1750                 is missing).</dd>
1751             </dl>
1752           </dd>
1753         </dl>
1754       </dd>
1755     </dl>
1756
1757     <p>
1758       Guest NUMA topology can be specified using the <code>numa</code> element.
1759       <span class="since">Since 0.9.8</span>
1760     </p>
1761
1762 <pre>
1763 ...
1764 &lt;cpu&gt;
1765   ...
1766   &lt;numa&gt;
1767     &lt;cell id='0' cpus='0-3' memory='512000' unit='KiB' discard='yes'/&gt;
1768     &lt;cell id='1' cpus='4-7' memory='512000' unit='KiB' memAccess='shared'/&gt;
1769   &lt;/numa&gt;
1770   ...
1771 &lt;/cpu&gt;
1772 ...</pre>
1773
1774     <p>
1775       Each <code>cell</code> element specifies a NUMA cell or a NUMA node.
1776       <code>cpus</code> specifies the CPU or range of CPUs that are
1777       part of the node. <code>memory</code> specifies the node memory
1778       in kibibytes (i.e. blocks of 1024 bytes).
1779       <span class="since">Since 1.2.11</span> one can use an additional <a
1780           href="#elementsMemoryAllocation"><code>unit</code></a> attribute to
1781       define units in which <code>memory</code> is specified.
1782       <span class="since">Since 1.2.7</span> all cells should
1783       have <code>id</code> attribute in case referring to some cell is
1784       necessary in the code, otherwise the cells are
1785       assigned <code>id</code>s in the increasing order starting from
1786       0.  Mixing cells with and without the <code>id</code> attribute
1787       is not recommended as it may result in unwanted behaviour.
1788
1789       <span class='since'>Since 1.2.9</span> the optional attribute
1790       <code>memAccess</code> can control whether the memory is to be
1791       mapped as "shared" or "private".  This is valid only for
1792       hugepages-backed memory and nvdimm modules.
1793
1794       Each <code>cell</code> element can have an optional
1795       <code>discard</code> attribute which fine tunes the discard
1796       feature for given numa node as described under
1797       <a href="#elementsMemoryBacking">Memory Backing</a>.
1798       Accepted values are <code>yes</code> and <code>no</code>.
1799       <span class='since'>Since 4.4.0</span>
1800     </p>
1801
1802     <p>
1803       This guest NUMA specification is currently available only for
1804       QEMU/KVM and Xen.
1805     </p>
1806
1807     <p>
1808       A NUMA hardware architecture supports the notion of distances
1809       between NUMA cells. <span class="since">Since 3.10.0</span> it
1810       is possible to define the distance between NUMA cells using the
1811       <code>distances</code> element within a NUMA <code>cell</code>
1812       description. The <code>sibling</code> sub-element is used to
1813       specify the distance value between sibling NUMA cells. For more
1814       details, see the chapter explaining the system's SLIT (System
1815       Locality Information Table) within the ACPI (Advanced
1816       Configuration and Power Interface) specification.
1817     </p>
1818
1819 <pre>
1820 ...
1821 &lt;cpu&gt;
1822   ...
1823   &lt;numa&gt;
1824     &lt;cell id='0' cpus='0,4-7' memory='512000' unit='KiB'&gt;
1825       &lt;distances&gt;
1826         &lt;sibling id='0' value='10'/&gt;
1827         &lt;sibling id='1' value='21'/&gt;
1828         &lt;sibling id='2' value='31'/&gt;
1829         &lt;sibling id='3' value='41'/&gt;
1830       &lt;/distances&gt;
1831     &lt;/cell&gt;
1832     &lt;cell id='1' cpus='1,8-10,12-15' memory='512000' unit='KiB' memAccess='shared'&gt;
1833       &lt;distances&gt;
1834         &lt;sibling id='0' value='21'/&gt;
1835         &lt;sibling id='1' value='10'/&gt;
1836         &lt;sibling id='2' value='21'/&gt;
1837         &lt;sibling id='3' value='31'/&gt;
1838       &lt;/distances&gt;
1839     &lt;/cell&gt;
1840     &lt;cell id='2' cpus='2,11' memory='512000' unit='KiB' memAccess='shared'&gt;
1841       &lt;distances&gt;
1842         &lt;sibling id='0' value='31'/&gt;
1843         &lt;sibling id='1' value='21'/&gt;
1844         &lt;sibling id='2' value='10'/&gt;
1845         &lt;sibling id='3' value='21'/&gt;
1846       &lt;/distances&gt;
1847     &lt;/cell&gt;
1848     &lt;cell id='3' cpus='3' memory='512000' unit='KiB'&gt;
1849       &lt;distances&gt;
1850         &lt;sibling id='0' value='41'/&gt;
1851         &lt;sibling id='1' value='31'/&gt;
1852         &lt;sibling id='2' value='21'/&gt;
1853         &lt;sibling id='3' value='10'/&gt;
1854       &lt;/distances&gt;
1855     &lt;/cell&gt;
1856   &lt;/numa&gt;
1857   ...
1858 &lt;/cpu&gt;
1859 ...</pre>
1860
1861     <p>
1862       Describing distances between NUMA cells is currently only supported
1863       by Xen and QEMU. If no <code>distances</code> are given to describe
1864       the SLIT data between different cells, it will default to a scheme
1865       using 10 for local and 20 for remote distances.
1866     </p>
1867
1868     <h3><a id="elementsEvents">Events configuration</a></h3>
1869
1870     <p>
1871       It is sometimes necessary to override the default actions taken
1872       on various events. Not all hypervisors support all events and actions.
1873       The actions may be taken as a result of calls to libvirt APIs
1874       <a href="html/libvirt-libvirt-domain.html#virDomainReboot">
1875         <code>virDomainReboot</code>
1876       </a>,
1877       <a href="html/libvirt-libvirt-domain.html#virDomainShutdown">
1878         <code>virDomainShutdown</code>
1879       </a>,
1880       or
1881       <a href="html/libvirt-libvirt-domain.html#virDomainShutdownFlags">
1882         <code>virDomainShutdownFlags</code>
1883       </a>.
1884       Using <code>virsh reboot</code> or <code>virsh shutdown</code> would
1885       also trigger the event.
1886     </p>
1887
1888 <pre>
1889 ...
1890 &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
1891 &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
1892 &lt;on_crash&gt;restart&lt;/on_crash&gt;
1893 &lt;on_lockfailure&gt;poweroff&lt;/on_lockfailure&gt;
1894 ...</pre>
1895
1896     <p>
1897       The following collections of elements allow the actions to be
1898       specified when a guest OS triggers a lifecycle operation. A
1899       common use case is to force a reboot to be treated as a poweroff
1900       when doing the initial OS installation. This allows the VM to be
1901       re-configured for the first post-install bootup.
1902     </p>
1903     <dl>
1904       <dt><code>on_poweroff</code></dt>
1905       <dd>The content of this element specifies the action to take when
1906         the guest requests a poweroff.</dd>
1907       <dt><code>on_reboot</code></dt>
1908       <dd>The content of this element specifies the action to take when
1909         the guest requests a reboot.</dd>
1910       <dt><code>on_crash</code></dt>
1911       <dd>The content of this element specifies the action to take when
1912         the guest crashes.</dd>
1913     </dl>
1914
1915     <p>
1916       Each of these states allow for the same four possible actions.
1917     </p>
1918
1919     <dl>
1920       <dt><code>destroy</code></dt>
1921       <dd>The domain will be terminated completely and all resources
1922         released.</dd>
1923       <dt><code>restart</code></dt>
1924       <dd>The domain will be terminated and then restarted with
1925         the same configuration.</dd>
1926       <dt><code>preserve</code></dt>
1927       <dd>The domain will be terminated and its resource preserved
1928         to allow analysis.</dd>
1929       <dt><code>rename-restart</code></dt>
1930       <dd>The domain will be terminated and then restarted with
1931         a new name.</dd>
1932     </dl>
1933
1934     <p>
1935     QEMU/KVM supports the <code>on_poweroff</code> and <code>on_reboot</code>
1936     events handling the <code>destroy</code> and <code>restart</code> actions.
1937     The <code>preserve</code> action for an <code>on_reboot</code> event
1938     is treated as a <code>destroy</code> and the <code>rename-restart</code>
1939     action for an <code>on_poweroff</code> event is treated as a
1940     <code>restart</code> event.
1941     </p>
1942
1943     <p>
1944       The <code>on_crash</code> event supports these additional
1945       actions <span class="since">since 0.8.4</span>.
1946     </p>
1947
1948     <dl>
1949       <dt><code>coredump-destroy</code></dt>
1950       <dd>The crashed domain's core will be dumped, and then the
1951         domain will be terminated completely and all resources
1952         released</dd>
1953       <dt><code>coredump-restart</code></dt>
1954       <dd>The crashed domain's core will be dumped, and then the
1955         domain will be restarted with the same configuration</dd>
1956     </dl>
1957
1958     <p>
1959       <span class="since">Since 3.9.0</span>, the lifecycle events can
1960       be configured via the
1961       <a href="html/libvirt-libvirt-domain.html#virDomainSetLifecycleAction">
1962         <code>virDomainSetLifecycleAction</code></a> API.
1963     </p>
1964
1965     <p>
1966       The <code>on_lockfailure</code> element (<span class="since">since
1967       1.0.0</span>) may be used to configure what action should be
1968       taken when a lock manager loses resource locks. The following
1969       actions are recognized by libvirt, although not all of them need
1970       to be supported by individual lock managers. When no action is
1971       specified, each lock manager will take its default action.
1972     </p>
1973     <dl>
1974       <dt><code>poweroff</code></dt>
1975       <dd>The domain will be forcefully powered off.</dd>
1976       <dt><code>restart</code></dt>
1977       <dd>The domain will be powered off and started up again to
1978         reacquire its locks.</dd>
1979       <dt><code>pause</code></dt>
1980       <dd>The domain will be paused so that it can be manually resumed
1981         when lock issues are solved.</dd>
1982       <dt><code>ignore</code></dt>
1983       <dd>Keep the domain running as if nothing happened.</dd>
1984     </dl>
1985
1986     <h3><a id="elementsPowerManagement">Power Management</a></h3>
1987
1988     <p>
1989       <span class="since">Since 0.10.2</span> it is possible to
1990       forcibly enable or disable BIOS advertisements to the guest
1991       OS. (NB: Only qemu driver support)
1992     </p>
1993
1994 <pre>
1995 ...
1996 &lt;pm&gt;
1997   &lt;suspend-to-disk enabled='no'/&gt;
1998   &lt;suspend-to-mem enabled='yes'/&gt;
1999 &lt;/pm&gt;
2000 ...</pre>
2001
2002     <dl>
2003       <dt><code>pm</code></dt>
2004       <dd>These elements enable ('yes') or disable ('no') BIOS support
2005         for S3 (suspend-to-mem) and S4 (suspend-to-disk) ACPI sleep
2006         states. If nothing is specified, then the hypervisor will be
2007         left with its default value.<br/>
2008         Note: This setting cannot prevent the guest OS from performing
2009         a suspend as the guest OS itself can choose to circumvent the
2010         unavailability of the sleep states (e.g. S4 by turning off
2011         completely).</dd>
2012     </dl>
2013
2014     <h3><a id="elementsFeatures">Hypervisor features</a></h3>
2015
2016     <p>
2017       Hypervisors may allow certain CPU / machine features to be
2018       toggled on/off.
2019     </p>
2020
2021 <pre>
2022 ...
2023 &lt;features&gt;
2024   &lt;pae/&gt;
2025   &lt;acpi/&gt;
2026   &lt;apic/&gt;
2027   &lt;hap/&gt;
2028   &lt;privnet/&gt;
2029   &lt;hyperv&gt;
2030     &lt;relaxed state='on'/&gt;
2031     &lt;vapic state='on'/&gt;
2032     &lt;spinlocks state='on' retries='4096'/&gt;
2033     &lt;vpindex state='on'/&gt;
2034     &lt;runtime state='on'/&gt;
2035     &lt;synic state='on'/&gt;
2036     &lt;reset state='on'/&gt;
2037     &lt;vendor_id state='on' value='KVM Hv'/&gt;
2038     &lt;frequencies state='on'/&gt;
2039     &lt;reenlightenment state='on'/&gt;
2040     &lt;tlbflush state='on'/&gt;
2041     &lt;ipi state='on'/&gt;
2042     &lt;evmcs state='on'/&gt;
2043     &lt;msrs unknown='ignore'/&gt;
2044   &lt;/hyperv&gt;
2045   &lt;kvm&gt;
2046     &lt;hidden state='on'/&gt;
2047   &lt;/kvm&gt;
2048   &lt;pvspinlock state='on'/&gt;
2049   &lt;gic version='2'/&gt;
2050   &lt;ioapic driver='qemu'/&gt;
2051   &lt;hpt resizing='required'&gt;
2052     &lt;maxpagesize unit='MiB'&gt;16&lt;/maxpagesize&gt;
2053   &lt;/hpt&gt;
2054   &lt;vmcoreinfo state='on'/&gt;
2055   &lt;smm state='on'&gt;
2056     &lt;tseg unit='MiB'&gt;48&lt;/tseg&gt;
2057   &lt;/smm&gt;
2058   &lt;htm state='on'/&gt;
2059 &lt;/features&gt;
2060 ...</pre>
2061
2062     <p>
2063       All features are listed within the <code>features</code>
2064       element, omitting a togglable feature tag turns it off.
2065       The available features can be found by asking
2066       for the <a href="formatcaps.html">capabilities XML</a> and
2067       <a href="formatdomaincaps.html">domain capabilities XML</a>,
2068       but a common set for fully virtualized domains are:
2069     </p>
2070
2071     <dl>
2072       <dt><code>pae</code></dt>
2073       <dd>Physical address extension mode allows 32-bit guests
2074         to address more than 4 GB of memory.</dd>
2075       <dt><code>acpi</code></dt>
2076       <dd>ACPI is useful for power management, for example, with
2077         KVM guests it is required for graceful shutdown to work.
2078       </dd>
2079       <dt><code>apic</code></dt>
2080       <dd>APIC allows the use of programmable IRQ
2081       management. <span class="since">Since 0.10.2 (QEMU only)</span> there is
2082       an optional attribute <code>eoi</code> with values <code>on</code>
2083       and <code>off</code> which toggles the availability of EOI (End of
2084       Interrupt) for the guest.
2085       </dd>
2086       <dt><code>hap</code></dt>
2087       <dd>Depending on the <code>state</code> attribute (values <code>on</code>,
2088         <code>off</code>) enable or disable use of Hardware Assisted Paging.
2089         The default is <code>on</code> if the hypervisor detects availability
2090         of Hardware Assisted Paging.
2091       </dd>
2092       <dt><code>viridian</code></dt>
2093       <dd>Enable Viridian hypervisor extensions for paravirtualizing
2094         guest operating systems
2095       </dd>
2096       <dt><code>privnet</code></dt>
2097       <dd>Always create a private network namespace. This is
2098         automatically set if any interface devices are defined.
2099         This feature is only relevant for container based
2100         virtualization drivers, such as LXC.
2101       </dd>
2102       <dt><code>hyperv</code></dt>
2103       <dd>Enable various features improving behavior of guests
2104         running Microsoft Windows.
2105       <table class="top_table">
2106         <tr>
2107           <th>Feature</th>
2108           <th>Description</th>
2109           <th>Value</th>
2110           <th>Since</th>
2111         </tr>
2112         <tr>
2113           <td>relaxed</td>
2114           <td>Relax constraints on timers</td>
2115           <td>on, off</td>
2116           <td><span class="since">1.0.0 (QEMU 2.0)</span></td>
2117         </tr>
2118         <tr>
2119           <td>vapic</td>
2120           <td>Enable virtual APIC</td>
2121           <td>on, off</td>
2122           <td><span class="since">1.1.0 (QEMU 2.0)</span></td>
2123         </tr>
2124         <tr>
2125           <td>spinlocks</td>
2126           <td>Enable spinlock support</td>
2127           <td>on, off; retries - at least 4095</td>
2128           <td><span class="since">1.1.0 (QEMU 2.0)</span></td>
2129         </tr>
2130         <tr>
2131           <td>vpindex</td>
2132           <td>Virtual processor index</td>
2133           <td>on, off</td>
2134           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2135         </tr>
2136         <tr>
2137           <td>runtime</td>
2138           <td>Processor time spent on running guest code and on behalf of guest code</td>
2139           <td>on, off</td>
2140           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2141         </tr>
2142         <tr>
2143           <td>synic</td>
2144           <td>Enable Synthetic Interrupt Controller (SyNIC)</td>
2145           <td>on, off</td>
2146           <td><span class="since">1.3.3 (QEMU 2.6)</span></td>
2147         </tr>
2148         <tr>
2149           <td>stimer</td>
2150           <td>Enable SyNIC timers</td>
2151           <td>on, off</td>
2152           <td><span class="since">1.3.3 (QEMU 2.6)</span></td>
2153         </tr>
2154         <tr>
2155           <td>reset</td>
2156           <td>Enable hypervisor reset</td>
2157           <td>on, off</td>
2158           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2159         </tr>
2160         <tr>
2161           <td>vendor_id</td>
2162           <td>Set hypervisor vendor id</td>
2163           <td>on, off; value - string, up to 12 characters</td>
2164           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2165         </tr>
2166         <tr>
2167           <td>frequencies</td>
2168           <td>Expose frequency MSRs</td>
2169           <td>on, off</td>
2170           <td><span class="since">4.7.0 (QEMU 2.12)</span></td>
2171         </tr>
2172         <tr>
2173           <td>reenlightenment</td>
2174           <td>Enable re-enlightenment notification on migration</td>
2175           <td>on, off</td>
2176           <td><span class="since">4.7.0 (QEMU 3.0)</span></td>
2177         </tr>
2178         <tr>
2179           <td>tlbflush</td>
2180           <td>Enable PV TLB flush support</td>
2181           <td>on, off</td>
2182           <td><span class="since">4.7.0 (QEMU 3.0)</span></td>
2183         </tr>
2184         <tr>
2185           <td>ipi</td>
2186           <td>Enable PV IPI support</td>
2187           <td>on, off</td>
2188           <td><span class="since">4.10.0 (QEMU 3.1)</span></td>
2189         </tr>
2190         <tr>
2191           <td>evmcs</td>
2192           <td>Enable Enlightened VMCS</td>
2193           <td>on, off</td>
2194           <td><span class="since">4.10.0 (QEMU 3.1)</span></td>
2195         </tr>
2196       </table>
2197       </dd>
2198       <dt><code>pvspinlock</code></dt>
2199       <dd>Notify the guest that the host supports paravirtual spinlocks
2200           for example by exposing the pvticketlocks mechanism. This feature
2201           can be explicitly disabled by using <code>state='off'</code>
2202           attribute.
2203       </dd>
2204       <dt><code>kvm</code></dt>
2205       <dd>Various features to change the behavior of the KVM hypervisor.
2206       <table class="top_table">
2207         <tr>
2208           <th>Feature</th>
2209           <th>Description</th>
2210           <th>Value</th>
2211           <th>Since</th>
2212         </tr>
2213         <tr>
2214           <td>hidden</td>
2215           <td>Hide the KVM hypervisor from standard MSR based discovery</td>
2216           <td>on, off</td>
2217           <td><span class="since">1.2.8 (QEMU 2.1.0)</span></td>
2218         </tr>
2219       </table>
2220       </dd>
2221       <dt><code>pmu</code></dt>
2222       <dd>Depending on the <code>state</code> attribute (values <code>on</code>,
2223         <code>off</code>, default <code>on</code>) enable or disable the
2224         performance monitoring unit for the guest.
2225         <span class="since">Since 1.2.12</span>
2226       </dd>
2227       <dt><code>vmport</code></dt>
2228       <dd>Depending on the <code>state</code> attribute (values <code>on</code>,
2229         <code>off</code>, default <code>on</code>) enable or disable
2230         the emulation of VMware IO port, for vmmouse etc.
2231         <span class="since">Since 1.2.16</span>
2232       </dd>
2233       <dt><code>gic</code></dt>
2234       <dd>Enable for architectures using a General Interrupt
2235           Controller instead of APIC in order to handle interrupts.
2236           For example, the 'aarch64' architecture uses
2237           <code>gic</code> instead of <code>apic</code>. The optional
2238           attribute <code>version</code> specifies the GIC version;
2239           however, it may not be supported by all hypervisors. Accepted
2240           values are <code>2</code>, <code>3</code> and <code>host</code>.
2241           <span class="since">Since 1.2.16</span>
2242       </dd>
2243       <dt><code>smm</code></dt>
2244       <dd>
2245         <p>
2246           Depending on the <code>state</code> attribute (values <code>on</code>,
2247           <code>off</code>, default <code>on</code>) enable or disable
2248           System Management Mode.
2249           <span class="since">Since 2.1.0</span>
2250         </p><p> Optional sub-element <code>tseg</code> can be used to specify
2251           the amount of memory dedicated to SMM's extended TSEG. That offers a
2252           fourth option size apart from the existing ones (1 MiB, 2 MiB and 8
2253           MiB) that the guest OS (or rather loader) can choose from. The size
2254           can be specified as a value of that element, optional attribute
2255           <code>unit</code> can be used to specify the unit of the
2256           aforementioned value (defaults to 'MiB').  If set to 0 the extended
2257           size is not advertised and only the default ones (see above) are
2258           available.
2259         </p><p>
2260           <b>If the VM is booting you should leave this option alone, unless you
2261           are very certain you know what you are doing.</b>
2262         </p><p>
2263           This value is configurable due to the fact that the calculation cannot
2264           be done right with the guarantee that it will work correctly.  In
2265           QEMU, the user-configurable extended TSEG feature was unavailable up
2266           to and including <code>pc-q35-2.9</code>. Starting with
2267           <code>pc-q35-2.10</code> the feature is available, with default size
2268           16 MiB.  That should suffice for up to roughly 272 vCPUs, 5 GiB guest
2269           RAM in total, no hotplug memory range, and 32 GiB of 64-bit PCI MMIO
2270           aperture.  Or for 48 vCPUs, with 1TB of guest RAM, no hotplug DIMM
2271           range, and 32GB of 64-bit PCI MMIO aperture. The values may also vary
2272           based on the loader the VM is using.
2273         </p><p>
2274           Additional size might be needed for significantly higher vCPU counts
2275           or increased address space (that can be memory, maxMemory, 64-bit PCI
2276           MMIO aperture size; roughly 8 MiB of TSEG per 1 TiB of address space)
2277           which can also be rounded up.
2278         </p><p>
2279           Due to the nature of this setting being similar to "how much RAM
2280           should the guest have" users are advised to either consult the
2281           documentation of the guest OS or loader (if there is any), or test
2282           this by trial-and-error changing the value until the VM boots
2283           successfully.  Yet another guiding value for users might be the fact
2284           that 48 MiB should be enough for pretty large guests (240 vCPUs and
2285           4TB guest RAM), but it is on purpose not set as default as 48 MiB of
2286           unavailable RAM might be too much for small guests (e.g. with 512 MiB
2287           of RAM).
2288         </p><p>
2289           See <a href="#elementsMemoryAllocation">Memory Allocation</a>
2290           for more details about the <code>unit</code> attribute.
2291           <span class="since">Since 4.5.0</span> (QEMU only)
2292         </p>
2293       </dd>
2294       <dt><code>ioapic</code></dt>
2295       <dd>Tune the I/O APIC. Possible values for the
2296           <code>driver</code> attribute are:
2297           <code>kvm</code> (default for KVM domains)
2298           and <code>qemu</code> which puts I/O APIC in userspace
2299           which is also known as a split I/O APIC mode.
2300           <span class="since">Since 3.4.0</span> (QEMU/KVM only)
2301       </dd>
2302       <dt><code>hpt</code></dt>
2303       <dd>Configure the HPT (Hash Page Table) of a pSeries guest. Possible
2304           values for the <code>resizing</code> attribute are
2305           <code>enabled</code>, which causes HPT resizing to be enabled if
2306           both the guest and the host support it; <code>disabled</code>, which
2307           causes HPT resizing to be disabled regardless of guest and host
2308           support; and <code>required</code>, which prevents the guest from
2309           starting unless both the guest and the host support HPT resizing. If
2310           the attribute is not defined, the hypervisor default will be used.
2311           <span class="since">Since 3.10.0</span> (QEMU/KVM only).
2312
2313           <p>The optional <code>maxpagesize</code> subelement can be used to
2314           limit the usable page size for HPT guests. Common values are 64 KiB,
2315           16 MiB and 16 GiB; when not specified, the hypervisor default will
2316           be used. <span class="since">Since 4.5.0</span> (QEMU/KVM only).</p>
2317       </dd>
2318       <dt><code>vmcoreinfo</code></dt>
2319       <dd>Enable QEMU vmcoreinfo device to let the guest kernel save debug
2320           details. <span class="since">Since 4.4.0</span> (QEMU only)
2321       </dd>
2322       <dt><code>htm</code></dt>
2323       <dd>Configure HTM (Hardware Transational Memory) availability for
2324           pSeries guests. Possible values for the <code>state</code> attribute
2325           are <code>on</code> and <code>off</code>. If the attribute is not
2326           defined, the hypervisor default will be used.
2327           <span class="since">Since 4.6.0</span> (QEMU/KVM only)
2328       </dd>
2329       <dt><code>nested-hv</code></dt>
2330       <dd>Configure nested HV availability for pSeries guests. This needs to
2331           be enabled from the host (L0) in order to be effective; having HV
2332           support in the (L1) guest is very desiderable if it's planned to
2333           run nested (L2) guests inside it, because it will result in those
2334           nested guests having much better performance than they would when
2335           using KVM PR or TCG.
2336           Possible values for the <code>state</code> attribute are
2337           <code>on</code> and <code>off</code>. If the attribute is not
2338           defined, the hypervisor default will be used.
2339           <span class="since">Since 4.10.0</span> (QEMU/KVM only)
2340       </dd>
2341       <dt><code>msrs</code></dt>
2342       <dd>Some guests might require ignoring unknown
2343           Model Specific Registers (MSRs) reads and writes. It's possible
2344           to switch this by setting <code>unknown</code> attribute
2345           of <code>msrs</code> to <code>ignore</code>. If the attribute is
2346           not defined, or set to <code>fault</code>, unknown reads and writes
2347           will not be ignored.
2348           <span class="since">Since 5.1.0</span> (bhyve only)
2349       </dd>
2350     </dl>
2351
2352     <h3><a id="elementsTime">Time keeping</a></h3>
2353
2354     <p>
2355       The guest clock is typically initialized from the host clock.
2356       Most operating systems expect the hardware clock to be kept
2357       in UTC, and this is the default. Windows, however, expects
2358       it to be in so called 'localtime'.
2359     </p>
2360
2361 <pre>
2362 ...
2363 &lt;clock offset='localtime'&gt;
2364   &lt;timer name='rtc' tickpolicy='catchup' track='guest'&gt;
2365     &lt;catchup threshold='123' slew='120' limit='10000'/&gt;
2366   &lt;/timer&gt;
2367   &lt;timer name='pit' tickpolicy='delay'/&gt;
2368 &lt;/clock&gt;
2369 ...</pre>
2370
2371     <dl>
2372       <dt><code>clock</code></dt>
2373       <dd>
2374         <p>The <code>offset</code> attribute takes four possible
2375           values, allowing fine grained control over how the guest
2376           clock is synchronized to the host. NB, not all hypervisors
2377           support all modes.</p>
2378         <dl>
2379           <dt><code>utc</code></dt>
2380           <dd>
2381             The guest clock will always be synchronized to UTC when
2382             booted.
2383             <span class="since">Since 0.9.11</span> 'utc' mode can be converted
2384             to 'variable' mode, which can be controlled by using the
2385             <code>adjustment</code> attribute. If the value is 'reset', the
2386             conversion is never done (not all hypervisors can
2387             synchronize to UTC on each boot; use of 'reset' will cause
2388             an error on those hypervisors). A numeric value
2389             forces the conversion to 'variable' mode using the value as the
2390             initial adjustment. The default <code>adjustment</code> is
2391             hypervisor specific.
2392           </dd>
2393           <dt><code>localtime</code></dt>
2394           <dd>
2395             The guest clock will be synchronized to the host's configured
2396             timezone when booted, if any.
2397             <span class="since">Since 0.9.11,</span> the <code>adjustment</code>
2398             attribute behaves the same as in 'utc' mode.
2399           </dd>
2400           <dt><code>timezone</code></dt>
2401           <dd>
2402             The guest clock will be synchronized to the requested timezone
2403             using the <code>timezone</code> attribute.
2404             <span class="since">Since 0.7.7</span>
2405           </dd>
2406           <dt><code>variable</code></dt>
2407           <dd>
2408             The guest clock will have an arbitrary offset applied
2409             relative to UTC or localtime, depending on the <code>basis</code>
2410             attribute. The delta relative to UTC (or localtime) is specified
2411             in seconds, using the <code>adjustment</code> attribute.
2412             The guest is free to adjust the RTC over time and expect
2413             that it will be honored at next reboot. This is in
2414             contrast to 'utc' and 'localtime' mode (with the optional
2415             attribute adjustment='reset'), where the RTC adjustments are
2416             lost at each reboot. <span class="since">Since 0.7.7</span>
2417             <span class="since">Since 0.9.11</span> the <code>basis</code>
2418             attribute can be either 'utc' (default) or 'localtime'.
2419           </dd>
2420         </dl>
2421         <p>
2422           A <code>clock</code> may have zero or more
2423           <code>timer</code> sub-elements. <span class="since">Since
2424           0.8.0</span>
2425         </p>
2426       </dd>
2427       <dt><code>timer</code></dt>
2428       <dd>
2429         <p>
2430           Each timer element requires a <code>name</code> attribute,
2431           and has other optional attributes that depend on
2432           the <code>name</code> specified.  Various hypervisors
2433           support different combinations of attributes.
2434         </p>
2435         <dl>
2436           <dt><code>name</code></dt>
2437           <dd>
2438             The <code>name</code> attribute selects which timer is
2439             being modified, and can be one of
2440             "platform" (currently unsupported),
2441             "hpet" (libxl, xen, qemu), "kvmclock" (qemu),
2442             "pit" (qemu), "rtc" (qemu), "tsc" (libxl) or "hypervclock"
2443             (qemu - <span class="since">since 1.2.2</span>).
2444
2445             The <code>hypervclock</code> timer adds support for the
2446             reference time counter and the reference page for iTSC
2447             feature for guests running the Microsoft Windows
2448             operating system.
2449           </dd>
2450           <dt><code>track</code></dt>
2451           <dd>
2452             The <code>track</code> attribute specifies what the timer
2453             tracks, and can be "boot", "guest", or "wall".
2454             Only valid for <code>name="rtc"</code>
2455             or <code>name="platform"</code>.
2456           </dd>
2457           <dt><code>tickpolicy</code></dt>
2458           <dd>
2459             <p>
2460             The <code>tickpolicy</code> attribute determines what
2461             happens when QEMU misses a deadline for injecting a
2462             tick to the guest:
2463             </p>
2464             <dl>
2465               <dt><code>delay</code></dt>
2466               <dd>Continue to deliver ticks at the normal rate.
2467                 The guest time will be delayed due to the late
2468                 tick</dd>
2469               <dt><code>catchup</code></dt>
2470               <dd>Deliver ticks at a higher rate to catch up
2471                 with the missed tick. The guest time should
2472                 not be delayed once catchup is complete.</dd>
2473               <dt><code>merge</code></dt>
2474               <dd>Merge the missed tick(s) into one tick and
2475                 inject. The guest time may be delayed, depending
2476                 on how the OS reacts to the merging of ticks</dd>
2477               <dt><code>discard</code></dt>
2478               <dd>Throw away the missed tick(s) and continue
2479                 with future injection normally. The guest time
2480                 may be delayed, unless the OS has explicit
2481                 handling of lost ticks</dd>
2482             </dl>
2483             <p>If the policy is "catchup", there can be further details in
2484             the <code>catchup</code> sub-element.</p>
2485             <dl>
2486               <dt><code>catchup</code></dt>
2487               <dd>
2488                 The <code>catchup</code> element has three optional
2489                 attributes, each a positive integer.  The attributes
2490                 are <code>threshold</code>, <code>slew</code>,
2491                 and <code>limit</code>.
2492               </dd>
2493             </dl>
2494             <p>
2495               Note that hypervisors are not required to support all policies across all time sources
2496             </p>
2497           </dd>
2498           <dt><code>frequency</code></dt>
2499           <dd>
2500             The <code>frequency</code> attribute is an unsigned
2501             integer specifying the frequency at
2502             which <code>name="tsc"</code> runs.
2503           </dd>
2504           <dt><code>mode</code></dt>
2505           <dd>
2506             The <code>mode</code> attribute controls how
2507             the <code>name="tsc"</code> timer is managed, and can be
2508             "auto", "native", "emulate", "paravirt", or "smpsafe".
2509             Other timers are always emulated.
2510           </dd>
2511           <dt><code>present</code></dt>
2512           <dd>
2513             The <code>present</code> attribute can be "yes" or "no" to
2514             specify whether a particular timer is available to the guest.
2515           </dd>
2516         </dl>
2517       </dd>
2518     </dl>
2519
2520     <h3><a id="elementsPerf">Performance monitoring events</a></h3>
2521
2522     <p>
2523       Some platforms allow monitoring of performance of the virtual machine and
2524       the code executed inside. To enable the performance monitoring events
2525       you can either specify them in the <code>perf</code> element or enable
2526       them via <code>virDomainSetPerfEvents</code> API. The performance values
2527       are then retrieved using the virConnectGetAllDomainStats API.
2528       <span class="since">Since 2.0.0</span>
2529     </p>
2530
2531 <pre>
2532 ...
2533 &lt;perf&gt;
2534   &lt;event name='cmt' enabled='yes'/&gt;
2535   &lt;event name='mbmt' enabled='no'/&gt;
2536   &lt;event name='mbml' enabled='yes'/&gt;
2537   &lt;event name='cpu_cycles' enabled='no'/&gt;
2538   &lt;event name='instructions' enabled='yes'/&gt;
2539   &lt;event name='cache_references' enabled='no'/&gt;
2540   &lt;event name='cache_misses' enabled='no'/&gt;
2541   &lt;event name='branch_instructions' enabled='no'/&gt;
2542   &lt;event name='branch_misses' enabled='no'/&gt;
2543   &lt;event name='bus_cycles' enabled='no'/&gt;
2544   &lt;event name='stalled_cycles_frontend' enabled='no'/&gt;
2545   &lt;event name='stalled_cycles_backend' enabled='no'/&gt;
2546   &lt;event name='ref_cpu_cycles' enabled='no'/&gt;
2547   &lt;event name='cpu_clock' enabled='no'/&gt;
2548   &lt;event name='task_clock' enabled='no'/&gt;
2549   &lt;event name='page_faults' enabled='no'/&gt;
2550   &lt;event name='context_switches' enabled='no'/&gt;
2551   &lt;event name='cpu_migrations' enabled='no'/&gt;
2552   &lt;event name='page_faults_min' enabled='no'/&gt;
2553   &lt;event name='page_faults_maj' enabled='no'/&gt;
2554   &lt;event name='alignment_faults' enabled='no'/&gt;
2555   &lt;event name='emulation_faults' enabled='no'/&gt;
2556 &lt;/perf&gt;
2557 ...
2558 </pre>
2559
2560   <table class="top_table">
2561     <tr>
2562       <th>event name</th>
2563       <th>Description</th>
2564       <th>stats parameter name</th>
2565     </tr>
2566     <tr>
2567       <td><code>cmt</code></td>
2568       <td>usage of l3 cache in bytes by applications running on the platform</td>
2569       <td><code>perf.cmt</code></td>
2570     </tr>
2571     <tr>
2572       <td><code>mbmt</code></td>
2573       <td>total system bandwidth from one level of cache</td>
2574       <td><code>perf.mbmt</code></td>
2575     </tr>
2576     <tr>
2577       <td><code>mbml</code></td>
2578       <td>bandwidth of memory traffic for a memory controller</td>
2579       <td><code>perf.mbml</code></td>
2580     </tr>
2581     <tr>
2582       <td><code>cpu_cycles</code></td>
2583       <td>the count of CPU cycles (total/elapsed)</td>
2584       <td><code>perf.cpu_cycles</code></td>
2585     </tr>
2586     <tr>
2587       <td><code>instructions</code></td>
2588       <td>the count of instructions by applications running on the platform</td>
2589       <td><code>perf.instructions</code></td>
2590     </tr>
2591     <tr>
2592       <td><code>cache_references</code></td>
2593       <td>the count of cache hits by applications running on the platform</td>
2594       <td><code>perf.cache_references</code></td>
2595     </tr>
2596     <tr>
2597       <td><code>cache_misses</code></td>
2598       <td>the count of cache misses by applications running on the platform</td>
2599       <td><code>perf.cache_misses</code></td>
2600     </tr>
2601     <tr>
2602       <td><code>branch_instructions</code></td>
2603       <td>the count of branch instructions by applications running on the platform</td>
2604       <td><code>perf.branch_instructions</code></td>
2605     </tr>
2606     <tr>
2607       <td><code>branch_misses</code></td>
2608       <td>the count of branch misses by applications running on the platform</td>
2609       <td><code>perf.branch_misses</code></td>
2610     </tr>
2611     <tr>
2612       <td><code>bus_cycles</code></td>
2613       <td>the count of bus cycles by applications running on the platform</td>
2614       <td><code>perf.bus_cycles</code></td>
2615     </tr>
2616     <tr>
2617       <td><code>stalled_cycles_frontend</code></td>
2618       <td>the count of stalled CPU cycles in the frontend of the instruction
2619           processor pipeline by applications running on the platform</td>
2620       <td><code>perf.stalled_cycles_frontend</code></td>
2621     </tr>
2622     <tr>
2623       <td><code>stalled_cycles_backend</code></td>
2624       <td>the count of stalled CPU cycles in the backend of the instruction
2625           processor pipeline by applications running on the platform</td>
2626       <td><code>perf.stalled_cycles_backend</code></td>
2627     </tr>
2628     <tr>
2629       <td><code>ref_cpu_cycles</code></td>
2630       <td>the count of total CPU cycles not affected by CPU frequency scaling
2631          by applications running on the platform</td>
2632       <td><code>perf.ref_cpu_cycles</code></td>
2633     </tr>
2634     <tr>
2635       <td><code>cpu_clock</code></td>
2636       <td>the count of CPU clock time, as measured by a monotonic
2637           high-resolution per-CPU timer, by applications running on
2638           the platform</td>
2639       <td><code>perf.cpu_clock</code></td>
2640     </tr>
2641     <tr>
2642       <td><code>task_clock</code></td>
2643       <td>the count of task clock time, as measured by a monotonic
2644           high-resolution CPU timer, specific to the task that
2645           is run by applications running on the platform</td>
2646       <td><code>perf.task_clock</code></td>
2647     </tr>
2648     <tr>
2649       <td><code>page_faults</code></td>
2650       <td>the count of page faults by applications running on the
2651           platform. This includes minor, major, invalid and other
2652           types of page faults</td>
2653       <td><code>perf.page_faults</code></td>
2654     </tr>
2655     <tr>
2656       <td><code>context_switches</code></td>
2657       <td>the count of context switches by applications running on
2658           the platform</td>
2659       <td><code>perf.context_switches</code></td>
2660     </tr>
2661     <tr>
2662       <td><code>cpu_migrations</code></td>
2663       <td>the count of CPU migrations, that is, where the process
2664           moved from one logical processor to another, by
2665           applications running on the platform</td>
2666       <td><code>perf.cpu_migrations</code></td>
2667     </tr>
2668     <tr>
2669       <td><code>page_faults_min</code></td>
2670       <td>the count of minor page faults, that is, where the
2671           page was present in the page cache, and therefore
2672           the fault avoided loading it from storage, by
2673           applications running on the platform</td>
2674       <td><code>perf.page_faults_min</code></td>
2675     </tr>
2676     <tr>
2677       <td><code>page_faults_maj</code></td>
2678       <td>the count of major page faults, that is, where the
2679           page was not present in the page cache, and
2680           therefore had to be fetched from storage, by
2681           applications running on the platform</td>
2682       <td><code>perf.page_faults_maj</code></td>
2683     </tr>
2684     <tr>
2685       <td><code>alignment_faults</code></td>
2686       <td>the count of alignment faults, that is when
2687           the load or store is not aligned properly, by
2688           applications running on the platform</td>
2689       <td><code>perf.alignment_faults</code></td>
2690     </tr>
2691     <tr>
2692       <td><code>emulation_faults</code></td>
2693       <td>the count of emulation faults, that is when
2694           the kernel traps on unimplemented instrucions
2695           and emulates them for user space, by
2696           applications running on the platform</td>
2697       <td><code>perf.emulation_faults</code></td>
2698     </tr>
2699   </table>
2700
2701     <h3><a id="elementsDevices">Devices</a></h3>
2702
2703     <p>
2704       The final set of XML elements are all used to describe devices
2705       provided to the guest domain. All devices occur as children
2706       of the main <code>devices</code> element.
2707       <span class="since">Since 0.1.3</span>
2708     </p>
2709
2710 <pre>
2711 ...
2712 &lt;devices&gt;
2713   &lt;emulator&gt;/usr/lib/xen/bin/qemu-dm&lt;/emulator&gt;
2714 &lt;/devices&gt;
2715 ...</pre>
2716
2717     <dl>
2718       <dt><a id="elementEmulator"><code>emulator</code></a></dt>
2719       <dd>
2720         The contents of the <code>emulator</code> element specify
2721         the fully qualified path to the device model emulator binary.
2722         The <a href="formatcaps.html">capabilities XML</a> specifies
2723         the recommended default emulator to use for each particular
2724         domain type / architecture combination.
2725       </dd>
2726     </dl>
2727
2728     <p>
2729       To help users identifying devices they care about, every
2730       device can have direct child <code>alias</code> element
2731       which then has <code>name</code> attribute where users can
2732       store identifier for the device. The identifier has to have
2733       "ua-" prefix and must be unique within the domain. Additionally, the
2734       identifier must consist only of the following characters:
2735       <code>[a-zA-Z0-9_-]</code>.
2736       <span class="since">Since 3.9.0</span>
2737     </p>
2738
2739 <pre>
2740 &lt;devices&gt;
2741   &lt;disk type='file'&gt;
2742     &lt;alias name='ua-myDisk'/&gt;
2743   &lt;/disk&gt;
2744   &lt;interface type='network' trustGuestRxFilters='yes'&gt;
2745     &lt;alias name='ua-myNIC'/&gt;
2746   &lt;/interface&gt;
2747   ...
2748 &lt;/devices&gt;
2749 </pre>
2750
2751     <h4><a id="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
2752
2753     <p>
2754       Any device that looks like a disk, be it a floppy, harddisk,
2755       cdrom, or paravirtualized driver is specified via the <code>disk</code>
2756       element.
2757     </p>
2758
2759 <pre>
2760 ...
2761 &lt;devices&gt;
2762   &lt;disk type='file' snapshot='external'&gt;
2763     &lt;driver name="tap" type="aio" cache="default"/&gt;
2764     &lt;source file='/var/lib/xen/images/fv0' startupPolicy='optional'&gt;
2765       &lt;seclabel relabel='no'/&gt;
2766     &lt;/source&gt;
2767     &lt;target dev='hda' bus='ide'/&gt;
2768     &lt;iotune&gt;
2769       &lt;total_bytes_sec&gt;10000000&lt;/total_bytes_sec&gt;
2770       &lt;read_iops_sec&gt;400000&lt;/read_iops_sec&gt;
2771       &lt;write_iops_sec&gt;100000&lt;/write_iops_sec&gt;
2772     &lt;/iotune&gt;
2773     &lt;boot order='2'/&gt;
2774     &lt;encryption type='...'&gt;
2775       ...
2776     &lt;/encryption&gt;
2777     &lt;shareable/&gt;
2778     &lt;serial&gt;
2779       ...
2780     &lt;/serial&gt;
2781   &lt;/disk&gt;
2782     ...
2783   &lt;disk type='network'&gt;
2784     &lt;driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/&gt;
2785     &lt;source protocol="sheepdog" name="image_name"&gt;
2786       &lt;host name="hostname" port="7000"/&gt;
2787     &lt;/source&gt;
2788     &lt;target dev="hdb" bus="ide"/&gt;
2789     &lt;boot order='1'/&gt;
2790     &lt;transient/&gt;
2791     &lt;address type='drive' controller='0' bus='1' unit='0'/&gt;
2792   &lt;/disk&gt;
2793   &lt;disk type='network'&gt;
2794     &lt;driver name="qemu" type="raw"/&gt;
2795     &lt;source protocol="rbd" name="image_name2"&gt;
2796       &lt;host name="hostname" port="7000"/&gt;
2797       &lt;snapshot name="snapname"/&gt;
2798       &lt;config file="/path/to/file"/&gt;
2799       &lt;auth username='myuser'&gt;
2800         &lt;secret type='ceph' usage='mypassid'/&gt;
2801       &lt;/auth&gt;
2802     &lt;/source&gt;
2803     &lt;target dev="hdc" bus="ide"/&gt;
2804   &lt;/disk&gt;
2805   &lt;disk type='block' device='cdrom'&gt;
2806     &lt;driver name='qemu' type='raw'/&gt;
2807     &lt;target dev='hdd' bus='ide' tray='open'/&gt;
2808     &lt;readonly/&gt;
2809   &lt;/disk&gt;
2810   &lt;disk type='network' device='cdrom'&gt;
2811     &lt;driver name='qemu' type='raw'/&gt;
2812     &lt;source protocol="http" name="url_path"&gt;
2813       &lt;host name="hostname" port="80"/&gt;
2814     &lt;/source&gt;
2815     &lt;target dev='hde' bus='ide' tray='open'/&gt;
2816     &lt;readonly/&gt;
2817   &lt;/disk&gt;
2818   &lt;disk type='network' device='cdrom'&gt;
2819     &lt;driver name='qemu' type='raw'/&gt;
2820     &lt;source protocol="https" name="url_path"&gt;
2821       &lt;host name="hostname" port="443"/&gt;
2822     &lt;/source&gt;
2823     &lt;target dev='hdf' bus='ide' tray='open'/&gt;
2824     &lt;readonly/&gt;
2825   &lt;/disk&gt;
2826   &lt;disk type='network' device='cdrom'&gt;
2827     &lt;driver name='qemu' type='raw'/&gt;
2828     &lt;source protocol="ftp" name="url_path"&gt;
2829       &lt;host name="hostname" port="21"/&gt;
2830     &lt;/source&gt;
2831     &lt;target dev='hdg' bus='ide' tray='open'/&gt;
2832     &lt;readonly/&gt;
2833   &lt;/disk&gt;
2834   &lt;disk type='network' device='cdrom'&gt;
2835     &lt;driver name='qemu' type='raw'/&gt;
2836     &lt;source protocol="ftps" name="url_path"&gt;
2837       &lt;host name="hostname" port="990"/&gt;
2838     &lt;/source&gt;
2839     &lt;target dev='hdh' bus='ide' tray='open'/&gt;
2840     &lt;readonly/&gt;
2841   &lt;/disk&gt;
2842   &lt;disk type='network' device='cdrom'&gt;
2843     &lt;driver name='qemu' type='raw'/&gt;
2844     &lt;source protocol="tftp" name="url_path"&gt;
2845       &lt;host name="hostname" port="69"/&gt;
2846     &lt;/source&gt;
2847     &lt;target dev='hdi' bus='ide' tray='open'/&gt;
2848     &lt;readonly/&gt;
2849   &lt;/disk&gt;
2850   &lt;disk type='block' device='lun'&gt;
2851     &lt;driver name='qemu' type='raw'/&gt;
2852     &lt;source dev='/dev/sda'&gt;
2853       &lt;reservations managed='no'&gt;
2854         &lt;source type='unix' path='/path/to/qemu-pr-helper' mode='client'/&gt;
2855       &lt;/reservations&gt;
2856     &lt;target dev='sda' bus='scsi'/&gt;
2857     &lt;address type='drive' controller='0' bus='0' target='3' unit='0'/&gt;
2858   &lt;/disk&gt;
2859   &lt;disk type='block' device='disk'&gt;
2860     &lt;driver name='qemu' type='raw'/&gt;
2861     &lt;source dev='/dev/sda'/&gt;
2862     &lt;geometry cyls='16383' heads='16' secs='63' trans='lba'/&gt;
2863     &lt;blockio logical_block_size='512' physical_block_size='4096'/&gt;
2864     &lt;target dev='hdj' bus='ide'/&gt;
2865   &lt;/disk&gt;
2866   &lt;disk type='volume' device='disk'&gt;
2867     &lt;driver name='qemu' type='raw'/&gt;
2868     &lt;source pool='blk-pool0' volume='blk-pool0-vol0'/&gt;
2869     &lt;target dev='hdk' bus='ide'/&gt;
2870   &lt;/disk&gt;
2871   &lt;disk type='network' device='disk'&gt;
2872     &lt;driver name='qemu' type='raw'/&gt;
2873     &lt;source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'&gt;
2874       &lt;host name='example.com' port='3260'/&gt;
2875       &lt;auth username='myuser'&gt;
2876         &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
2877       &lt;/auth&gt;
2878     &lt;/source&gt;
2879     &lt;target dev='vda' bus='virtio'/&gt;
2880   &lt;/disk&gt;
2881   &lt;disk type='network' device='lun'&gt;
2882     &lt;driver name='qemu' type='raw'/&gt;
2883     &lt;source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/1'&gt;
2884       &lt;host name='example.com' port='3260'/&gt;
2885       &lt;auth username='myuser'&gt;
2886         &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
2887       &lt;/auth&gt;
2888     &lt;/source&gt;
2889     &lt;target dev='sdb' bus='scsi'/&gt;
2890   &lt;/disk&gt;
2891   &lt;disk type='network' device='lun'&gt;
2892     &lt;driver name='qemu' type='raw'/&gt;
2893     &lt;source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'&gt;
2894       &lt;host name='example.com' port='3260'/&gt;
2895       &lt;initiator&gt;
2896         &lt;iqn name='iqn.2013-07.com.example:client'/&gt;
2897       &lt;/initiator&gt;
2898     &lt;/source&gt;
2899     &lt;target dev='sdb' bus='scsi'/&gt;
2900   &lt;/disk&gt;
2901   &lt;disk type='volume' device='disk'&gt;
2902     &lt;driver name='qemu' type='raw'/&gt;
2903     &lt;source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/&gt;
2904     &lt;target dev='vdb' bus='virtio'/&gt;
2905   &lt;/disk&gt;
2906   &lt;disk type='volume' device='disk'&gt;
2907     &lt;driver name='qemu' type='raw'/&gt;
2908     &lt;source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/&gt;
2909     &lt;target dev='vdc' bus='virtio'/&gt;
2910   &lt;/disk&gt;
2911   &lt;disk type='file' device='disk'&gt;
2912     &lt;driver name='qemu' type='qcow2' queues='4'/&gt;
2913     &lt;source file='/var/lib/libvirt/images/domain.qcow'/&gt;
2914     &lt;backingStore type='file'&gt;
2915       &lt;format type='qcow2'/&gt;
2916       &lt;source file='/var/lib/libvirt/images/snapshot.qcow'/&gt;
2917       &lt;backingStore type='block'&gt;
2918         &lt;format type='raw'/&gt;
2919         &lt;source dev='/dev/mapper/base'/&gt;
2920         &lt;backingStore/&gt;
2921       &lt;/backingStore&gt;
2922     &lt;/backingStore&gt;
2923     &lt;target dev='vdd' bus='virtio'/&gt;
2924   &lt;/disk&gt;
2925 &lt;/devices&gt;
2926 ...</pre>
2927
2928     <dl>
2929       <dt><code>disk</code></dt>
2930       <dd>The <code>disk</code> element is the main container for
2931       describing disks and supports the following attributes:
2932         <dl>
2933           <dt><code>type</code></dt>
2934             <dd>
2935             Valid values are "file", "block",
2936             "dir" (<span class="since">since 0.7.5</span>),
2937             "network" (<span class="since">since 0.8.7</span>), or
2938             "volume" (<span class="since">since 1.0.5</span>)
2939             and refer to the underlying source for the disk.
2940             <span class="since">Since 0.0.3</span>
2941             </dd>
2942           <dt><code>device</code></dt>
2943             <dd>
2944             Indicates how the disk is to be exposed to the guest OS. Possible
2945             values for this attribute are "floppy", "disk", "cdrom", and "lun",
2946             defaulting to "disk".
2947             <p>
2948             Using "lun" (<span class="since">since 0.9.10</span>) is only
2949             valid when the <code>type</code> is "block" or "network" for
2950             <code>protocol='iscsi'</code> or when the <code>type</code>
2951             is "volume" when using an iSCSI source <code>pool</code>
2952             for <code>mode</code> "host" or as an
2953             <a href="http://wiki.libvirt.org/page/NPIV_in_libvirt">NPIV</a>
2954             virtual Host Bus Adapter (vHBA) using a Fibre Channel storage pool.
2955             Configured in this manner, the LUN behaves identically to "disk",
2956             except that generic SCSI commands from the guest are accepted
2957             and passed through to the physical device. Also note that
2958             device='lun' will only be recognized for actual raw devices,
2959             but never for individual partitions or LVM partitions (in those
2960             cases, the kernel will reject the generic SCSI commands, making
2961             it identical to device='disk').
2962             <span class="since">Since 0.1.4</span>
2963             </p>
2964             </dd>
2965           <dt><code>model</code></dt>
2966             <dd>
2967             Indicates the emulated device model of the disk. Typically
2968             this is indicated solely by the <code>bus</code> property but
2969             for <code>bus</code> "virtio" the model can be specified further
2970             with "virtio-transitional", "virtio-non-transitional", or
2971             "virtio". See
2972             <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
2973             for more details.
2974             <span class="since">Since 5.2.0</span>
2975             </dd>
2976           <dt><code>rawio</code></dt>
2977             <dd>
2978             Indicates whether the disk needs rawio capability. Valid
2979             settings are "yes" or "no" (default is "no"). If any one disk
2980             in a domain has rawio='yes', rawio capability will be enabled
2981             for all disks in the domain (because, in the case of QEMU, this
2982             capability can only be set on a per-process basis). This attribute
2983             is only valid when device is "lun". NB, <code>rawio</code> intends
2984             to confine the capability per-device, however, current QEMU
2985             implementation gives the domain process broader capability
2986             than that (per-process basis, affects all the domain disks).
2987             To confine the capability as much as possible for QEMU driver
2988             as this stage, <code>sgio</code> is recommended, it's more
2989             secure than <code>rawio</code>.
2990             <span class="since">Since 0.9.10</span>
2991             </dd>
2992           <dt><code>sgio</code></dt>
2993             <dd>
2994             If supported by the hypervisor and OS, indicates whether
2995             unprivileged SG_IO commands are filtered for the disk. Valid
2996             settings are "filtered" or "unfiltered" where the default is
2997             "filtered". Only available when the <code>device</code> is 'lun'.
2998             <span class="since">Since 1.0.2</span>
2999             </dd>
3000           <dt><code>snapshot</code></dt>
3001             <dd>
3002             Indicates the default behavior of the disk during disk snapshots:
3003             "<code>internal</code>" requires a file format such as qcow2 that
3004             can store both the snapshot and the data changes since the snapshot;
3005             "<code>external</code>" will separate the snapshot from the live
3006             data; and "<code>no</code>" means the disk will not participate in
3007             snapshots. Read-only disks default to "<code>no</code>", while the
3008             default for other disks depends on the hypervisor's capabilities.
3009             Some hypervisors allow a per-snapshot choice as well, during
3010             <a href="formatsnapshot.html">domain snapshot creation</a>.
3011             Not all snapshot modes are supported; for example, enabling
3012             snapshots with a transient disk generally does not make sense.
3013             <span class="since">Since 0.9.5</span>
3014             </dd>
3015         </dl>
3016       </dd>
3017       <dt><code>source</code></dt>
3018       <dd>Representation of the disk <code>source</code> depends on the
3019       disk <code>type</code> attribute value as follows:
3020           <dl>
3021             <dt><code>file</code></dt>
3022               <dd>
3023               The <code>file</code> attribute specifies the fully-qualified
3024               path to the file holding the disk.
3025               <span class="since">Since 0.0.3</span>
3026               </dd>
3027             <dt><code>block</code></dt>
3028               <dd>
3029               The <code>dev</code> attribute specifies the fully-qualified path
3030               to the host device to serve as the disk.
3031               <span class="since">Since 0.0.3</span>
3032               </dd>
3033             <dt><code>dir</code></dt>
3034               <dd>
3035               The <code>dir</code> attribute specifies the fully-qualified path
3036               to the directory to use as the disk.
3037               <span class="since">Since 0.7.5</span>
3038               </dd>
3039             <dt><code>network</code></dt>
3040               <dd>
3041               The <code>protocol</code> attribute specifies the protocol to
3042               access to the requested image. Possible values are "nbd",
3043               "iscsi", "rbd", "sheepdog", "gluster" or "vxhs".
3044
3045               <p>If the <code>protocol</code> attribute is "rbd", "sheepdog",
3046               "gluster", or "vxhs", an additional attribute <code>name</code>
3047               is mandatory to specify which volume/image will be used.
3048               </p>
3049
3050               <p>For "nbd", the <code>name</code> attribute is optional. TLS
3051               transport for NBD can be enabled by setting the <code>tls</code>
3052               attribute to <code>yes</code>. For the QEMU hypervisor, usage of
3053               a TLS environment can also be globally controlled on the host by
3054               the <code>nbd_tls</code> and <code>nbd_tls_x509_cert_dir</code> in
3055               /etc/libvirt/qemu.conf.
3056               ('tls' <span class="since">Since 4.5.0</span>)
3057               </p>
3058
3059               <p>For "iscsi" (<span class="since">since 1.0.4</span>), the
3060               <code>name</code> attribute may include a logical unit number,
3061               separated from the target's name by a slash (e.g.,
3062               <code>iqn.2013-07.com.example:iscsi-pool/1</code>). If not
3063               specified, the default LUN is zero.
3064               </p>
3065
3066               <p>For "vxhs" (<span class="since">since 3.8.0</span>), the
3067               <code>name</code> is the UUID of the volume, assigned by the
3068               HyperScale server. Additionally, an optional attribute
3069               <code>tls</code> (QEMU only) can be used to control whether a
3070               VxHS block device would utilize a hypervisor configured TLS
3071               X.509 certificate environment in order to encrypt the data
3072               channel. For the QEMU hypervisor, usage of a TLS environment can
3073               also be globally controlled on the host by the
3074               <code>vxhs_tls</code> and <code>vxhs_tls_x509_cert_dir</code> or
3075               <code>default_tls_x509_cert_dir</code> settings in the file
3076               /etc/libvirt/qemu.conf. If <code>vxhs_tls</code> is enabled,
3077               then unless the domain <code>tls</code> attribute is set to "no",
3078               libvirt will use the host configured TLS environment. If the
3079               <code>tls</code> attribute is set to "yes", then regardless of
3080               the qemu.conf setting, TLS authentication will be attempted.
3081               </p>
3082               <span class="since">Since 0.8.7</span>
3083               </dd>
3084             <dt><code>volume</code></dt>
3085               <dd>
3086               The underlying disk source is represented by attributes
3087               <code>pool</code> and <code>volume</code>. Attribute
3088               <code>pool</code> specifies the name of the
3089               <a href="formatstorage.html">storage pool</a> (managed
3090               by libvirt) where the disk source resides. Attribute
3091               <code>volume</code> specifies the name of storage volume (managed
3092               by libvirt) used as the disk source. The value for the
3093               <code>volume</code> attribute will be the output from the "Name"
3094               column of a <code>virsh vol-list [pool-name]</code> command.
3095               <p>
3096               Use the attribute <code>mode</code>
3097               (<span class="since">since 1.1.1</span>) to indicate how to
3098               represent the LUN as the disk source. Valid values are
3099               "direct" and "host". If <code>mode</code> is not specified,
3100               the default is to use "host".
3101
3102               Using "direct" as the <code>mode</code> value indicates to use
3103               the <a href="formatstorage.html">storage pool's</a>
3104               <code>source</code> element <code>host</code> attribute as
3105               the disk source to generate the libiscsi URI (e.g.
3106               'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1').
3107
3108               Using "host" as the <code>mode</code> value indicates to use the
3109               LUN's path as it shows up on host (e.g.
3110               'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1').
3111
3112               Using a LUN from an iSCSI source pool provides the same
3113               features as a <code>disk</code> configured using
3114               <code>type</code> 'block' or 'network' and <code>device</code>
3115               of 'lun' with respect to how the LUN is presented to and
3116               may be used by the guest.
3117
3118               <span class="since">Since 1.0.5</span>
3119               </p>
3120               </dd>
3121           </dl>
3122         With "file", "block", and "volume", one or more optional
3123         sub-elements <code>seclabel</code>, <a href="#seclabel">described
3124         below</a> (and <span class="since">since 0.9.9</span>), can be
3125         used to override the domain security labeling policy for just
3126         that source file. (NB, for "volume" type disk, <code>seclabel</code>
3127         is only valid when the specified storage volume is of 'file' or
3128         'block' type).
3129         <p>
3130         The <code>source</code> element may also have the <code>index</code>
3131         attribute with same semantics the <a href='#elementsDiskBackingStoreIndex'>
3132         <code>index</code></a> attribute of <code>backingStore</code>
3133         </p>
3134         <p>
3135         The <code>source</code> element may contain the following sub elements:
3136         </p>
3137
3138         <dl>
3139           <dt><code>host</code></dt>
3140           <dd>
3141             <p>
3142             When the disk <code>type</code> is "network", the <code>source</code>
3143             may have zero or more <code>host</code> sub-elements used to
3144             specify the hosts to connect.
3145
3146             The <code>host</code> element supports 4 attributes, viz.  "name",
3147             "port", "transport" and "socket", which specify the hostname,
3148             the port number, transport type and path to socket, respectively.
3149             The meaning of this element and the number of the elements depend
3150             on the protocol attribute.
3151             </p>
3152             <table class="top_table">
3153               <tr>
3154                 <th> Protocol </th>
3155                 <th> Meaning </th>
3156                 <th> Number of hosts </th>
3157                 <th> Default port </th>
3158               </tr>
3159               <tr>
3160                 <td> nbd </td>
3161                 <td> a server running nbd-server </td>
3162                 <td> only one </td>
3163                 <td> 10809 </td>
3164               </tr>
3165               <tr>
3166                 <td> iscsi </td>
3167                 <td> an iSCSI server </td>
3168                 <td> only one </td>
3169                 <td> 3260 </td>
3170               </tr>
3171               <tr>
3172                 <td> rbd </td>
3173                 <td> monitor servers of RBD </td>
3174                 <td> one or more </td>
3175                 <td> librados default </td>
3176               </tr>
3177               <tr>
3178                 <td> sheepdog </td>
3179                 <td> one of the sheepdog servers (default is localhost:7000) </td>
3180                 <td> zero or one </td>
3181                 <td> 7000 </td>
3182               </tr>
3183               <tr>
3184                 <td> gluster </td>
3185                 <td> a server running glusterd daemon </td>
3186                 <td> one or more (<span class="since">Since 2.1.0</span>), just one prior to that </td>
3187                 <td> 24007 </td>
3188               </tr>
3189               <tr>
3190                 <td> vxhs </td>
3191                 <td> a server running Veritas HyperScale daemon </td>
3192                 <td> only one </td>
3193                 <td> 9999 </td>
3194               </tr>
3195             </table>
3196             <p>
3197             gluster supports "tcp", "rdma", "unix" as valid values for the
3198             transport attribute.  nbd supports "tcp" and "unix".  Others only
3199             support "tcp".  If nothing is specified, "tcp" is assumed. If the
3200             transport is "unix", the socket attribute specifies the path to an
3201             AF_UNIX socket.
3202             </p>
3203           </dd>
3204           <dt><code>snapshot</code></dt>
3205           <dd>
3206             The <code>name</code> attribute of <code>snapshot</code> element can
3207             optionally specify an internal snapshot name to be used as the
3208             source for storage protocols.
3209             Supported for 'rbd' <span class="since">since 1.2.11 (QEMU only).</span>
3210           </dd>
3211           <dt><code>config</code></dt>
3212           <dd>
3213             The <code>file</code> attribute for the <code>config</code> element
3214             provides a fully qualified path to a configuration file to be
3215             provided as a parameter to the client of a networked storage
3216             protocol. Supported for 'rbd' <span class="since">since 1.2.11
3217             (QEMU only).</span>
3218           </dd>
3219           <dt><code>auth</code></dt>
3220           <dd><span class="since">Since libvirt 3.9.0</span>, the
3221             <code>auth</code> element is supported for a disk
3222             <code>type</code> "network" that is using a <code>source</code>
3223             element with the <code>protocol</code> attributes "rbd" or "iscsi".
3224             If present, the <code>auth</code> element provides the
3225             authentication credentials needed to access the source.  It
3226             includes a mandatory attribute <code>username</code>, which
3227             identifies the username to use during authentication, as well
3228             as a sub-element <code>secret</code> with mandatory
3229             attribute <code>type</code>, to tie back to
3230             a <a href="formatsecret.html">libvirt secret object</a> that
3231             holds the actual password or other credentials (the domain XML
3232             intentionally does not expose the password, only the reference
3233             to the object that does manage the password).
3234             Known secret types are "ceph" for Ceph RBD network sources and
3235             "iscsi" for CHAP authentication of iSCSI targets.
3236             Both will require either a <code>uuid</code> attribute
3237             with the UUID of the secret object or a <code>usage</code>
3238             attribute matching the key that was specified in the
3239             secret object.
3240           </dd>
3241           <dt><code>encryption</code></dt>
3242           <dd><span class="since">Since libvirt 3.9.0</span>, the
3243             <code>encryption</code> can be a sub-element of the
3244             <code>source</code> element for encrypted storage sources.
3245             If present, specifies how the storage source is encrypted
3246             See the
3247             <a href="formatstorageencryption.html">Storage Encryption</a>
3248             page for more information.
3249             <p/>
3250             Note that the 'qcow' format of encryption is broken and thus is no
3251             longer supported for use with disk images.
3252             (<span class="since">Since libvirt 4.5.0</span>)
3253           </dd>
3254           <dt><code>reservations</code></dt>
3255           <dd><span class="since">Since libvirt 4.4.0</span>, the
3256             <code>reservations</code> can be a sub-element of the
3257             <code>source</code> element for storage sources (QEMU driver only).
3258             If present it enables persistent reservations for SCSI
3259             based disks. The element has one mandatory attribute
3260             <code>managed</code> with accepted values <code>yes</code> and
3261             <code>no</code>. If <code>managed</code> is enabled libvirt prepares
3262             and manages any resources needed. When the persistent reservations
3263             are unmanaged, then the hypervisor acts as a client and the path to
3264             the server socket must be provided in the child element
3265             <code>source</code>, which currently accepts only the following
3266             attributes:
3267             <code>type</code> with one value <code>unix</code>,
3268             <code>path</code> path to the socket, and
3269             finally <code>mode</code> which accepts one value
3270             <code>client</code> specifying the role of hypervisor.
3271             It's recommended to allow libvirt manage the persistent
3272             reservations.
3273           </dd>
3274           <dt><code>initiator</code></dt>
3275           <dd><span class="since">Since libvirt 4.7.0</span>, the
3276             <code>initiator</code> element is supported for a disk
3277             <code>type</code> "network" that is using a <code>source</code>
3278             element with the <code>protocol</code> attribute "iscsi".
3279             If present, the <code>initiator</code> element provides the
3280             initiator IQN needed to access the source via mandatory
3281             attribute <code>name</code>.
3282           </dd>
3283         </dl>
3284
3285         <p>
3286         For a "file" or "volume" disk type which represents a cdrom or floppy
3287         (the <code>device</code> attribute), it is possible to define
3288         policy what to do with the disk if the source file is not accessible.
3289         (NB, <code>startupPolicy</code> is not valid for "volume" disk unless
3290          the specified storage volume is of "file" type). This is done by the
3291         <code>startupPolicy</code> attribute
3292         (<span class="since">since 0.9.7</span>),
3293         accepting these values:
3294         </p>
3295         <table class="top_table">
3296           <tr>
3297             <td> mandatory </td>
3298             <td> fail if missing for any reason (the default) </td>
3299           </tr>
3300           <tr>
3301             <td> requisite </td>
3302             <td> fail if missing on boot up,
3303                  drop if missing on migrate/restore/revert </td>
3304           </tr>
3305           <tr>
3306             <td> optional </td>
3307             <td> drop if missing at any start attempt </td>
3308           </tr>
3309         </table>
3310         <p>
3311         <span class="since">Since 1.1.2</span> the <code>startupPolicy</code>
3312         is extended to support hard disks besides cdrom and floppy. On guest
3313         cold bootup, if a certain disk is not accessible or its disk chain is
3314         broken, with startupPolicy 'optional' the guest will drop this disk.
3315         This feature doesn't support migration currently.
3316         </p>
3317         </dd>
3318       <dt><code>backingStore</code></dt>
3319       <dd>
3320         This element describes the backing store used by the disk
3321         specified by sibling <code>source</code> element. It is
3322         currently ignored on input and only used for output to
3323         describe the detected backing chains of running
3324         domains <span class="since">since 1.2.4</span> (although a
3325         future version of libvirt may start accepting chains on input,
3326         or output information for offline domains). An
3327         empty <code>backingStore</code> element means the sibling
3328         source is self-contained and is not based on any backing
3329         store. For backing chain information to be accurate, the
3330         backing format must be correctly specified in the metadata of
3331         each file of the chain (files created by libvirt satisfy this
3332         property, but using existing external files for snapshot or
3333         block copy operations requires the end user to pre-create the
3334         file correctly). The following attributes are
3335         supported in <code>backingStore</code>:
3336         <dl>
3337           <dt><code>type</code></dt>
3338           <dd>
3339             The <code>type</code> attribute represents the type of disk used
3340             by the backing store, see disk type attribute above for more
3341             details and possible values.
3342           </dd>
3343           <dt><code><a id="elementsDiskBackingStoreIndex">index</a></code></dt>
3344           <dd>
3345             This attribute is only valid in output (and ignored on input) and
3346             it can be used to refer to a specific part of the disk chain when
3347             doing block operations (such as via the
3348             <code>virDomainBlockRebase</code> API). For example,
3349             <code>vda[2]</code> refers to the backing store with
3350             <code>index='2'</code> of the disk with <code>vda</code> target.
3351           </dd>
3352         </dl>
3353         Moreover, <code>backingStore</code> supports the following sub-elements:
3354         <dl>
3355           <dt><code>format</code></dt>
3356           <dd>
3357             The <code>format</code> element contains <code>type</code>
3358             attribute which specifies the internal format of the backing
3359             store, such as <code>raw</code> or <code>qcow2</code>.
3360           </dd>
3361           <dt><code>source</code></dt>
3362           <dd>
3363             This element has the same structure as the <code>source</code>
3364             element in <code>disk</code>. It specifies which file, device,
3365             or network location contains the data of the described backing
3366             store.
3367           </dd>
3368           <dt><code>backingStore</code></dt>
3369           <dd>
3370             If the backing store is not self-contained, the next element
3371             in the chain is described by nested <code>backingStore</code>
3372             element.
3373           </dd>
3374         </dl>
3375       </dd>
3376       <dt><code>mirror</code></dt>
3377       <dd>
3378         This element is present if the hypervisor has started a
3379         long-running block job operation, where the mirror location in
3380         the <code>source</code> sub-element will eventually have the
3381         same contents as the source, and with the file format in the
3382         sub-element <code>format</code> (which might differ from the
3383         format of the source).  The details of the <code>source</code>
3384         sub-element are determined by the <code>type</code> attribute
3385         of the mirror, similar to what is done for the
3386         overall <code>disk</code> device element. The <code>job</code>
3387         attribute mentions which API started the operation ("copy" for
3388         the <code>virDomainBlockRebase</code> API, or "active-commit"
3389         for the <code>virDomainBlockCommit</code>
3390         API), <span class="since">since 1.2.7</span>.  The
3391         attribute <code>ready</code>, if present, tracks progress of
3392         the job: <code>yes</code> if the disk is known to be ready to
3393         pivot, or, <span class="since">since
3394         1.2.7</span>, <code>abort</code> or <code>pivot</code> if the
3395         job is in the process of completing.  If <code>ready</code> is
3396         not present, the disk is probably still
3397         copying.  For now, this element only valid in output; it is
3398         ignored on input.  The <code>source</code> sub-element exists
3399         for all two-phase jobs <span class="since">since 1.2.6</span>.
3400         Older libvirt supported only block copy to a
3401         file, <span class="since">since 0.9.12</span>; for
3402         compatibility with older clients, such jobs include redundant
3403         information in the attributes <code>file</code>
3404         and <code>format</code> in the <code>mirror</code> element.
3405       </dd>
3406       <dt><code>target</code></dt>
3407       <dd>The <code>target</code> element controls the bus / device
3408         under which the disk is exposed to the guest
3409         OS. The <code>dev</code> attribute indicates the "logical"
3410         device name. The actual device name specified is not
3411         guaranteed to map to the device name in the guest OS. Treat it
3412         as a device ordering hint.  The optional <code>bus</code>
3413         attribute specifies the type of disk device to emulate;
3414         possible values are driver specific, with typical values being
3415         "ide", "scsi", "virtio", "xen", "usb", "sata", or
3416         "sd" <span class="since">"sd" since 1.1.2</span>. If omitted, the bus
3417         type is inferred from the style of the device name (e.g. a device named
3418         'sda' will typically be exported using a SCSI bus). The optional
3419         attribute <code>tray</code> indicates the tray status of the
3420         removable disks (i.e. CDROM or Floppy disk), the value can be either
3421         "open" or "closed", defaults to "closed". NB, the value of
3422         <code>tray</code> could be updated while the domain is running.
3423         The optional attribute <code>removable</code> sets the
3424         removable flag for USB disks, and its value can be either "on"
3425         or "off", defaulting to "off". <span class="since">Since
3426         0.0.3; <code>bus</code> attribute since 0.4.3;
3427         <code>tray</code> attribute since 0.9.11; "usb" attribute value since
3428         after 0.4.4; "sata" attribute value since 0.9.7; "removable" attribute
3429         value since 1.1.3</span>
3430       </dd>
3431       <dt><code>iotune</code></dt>
3432       <dd>The optional <code>iotune</code> element provides the
3433         ability to provide additional per-device I/O tuning, with
3434         values that can vary for each device (contrast this to
3435         the <a href="#elementsBlockTuning"><code>&lt;blkiotune&gt;</code></a>
3436         element, which applies globally to the domain).  Currently,
3437         the only tuning available is Block I/O throttling for qemu.
3438         This element has optional sub-elements; any sub-element not
3439         specified or given with a value of 0 implies no
3440         limit.  <span class="since">Since 0.9.8</span>
3441         <dl>
3442           <dt><code>total_bytes_sec</code></dt>
3443           <dd>The optional <code>total_bytes_sec</code> element is the
3444             total throughput limit in bytes per second.  This cannot
3445             appear with <code>read_bytes_sec</code>
3446             or <code>write_bytes_sec</code>.</dd>
3447           <dt><code>read_bytes_sec</code></dt>
3448           <dd>The optional <code>read_bytes_sec</code> element is the
3449             read throughput limit in bytes per second.</dd>
3450           <dt><code>write_bytes_sec</code></dt>
3451           <dd>The optional <code>write_bytes_sec</code> element is the
3452             write throughput limit in bytes per second.</dd>
3453           <dt><code>total_iops_sec</code></dt>
3454           <dd>The optional <code>total_iops_sec</code> element is the
3455             total I/O operations per second.  This cannot
3456             appear with <code>read_iops_sec</code>
3457             or <code>write_iops_sec</code>.</dd>
3458           <dt><code>read_iops_sec</code></dt>
3459           <dd>The optional <code>read_iops_sec</code> element is the
3460             read I/O operations per second.</dd>
3461           <dt><code>write_iops_sec</code></dt>
3462           <dd>The optional <code>write_iops_sec</code> element is the
3463             write I/O operations per second.</dd>
3464           <dt><code>total_bytes_sec_max</code></dt>
3465           <dd>The optional <code>total_bytes_sec_max</code> element is the
3466             maximum total throughput limit in bytes per second.  This cannot
3467             appear with <code>read_bytes_sec_max</code>
3468             or <code>write_bytes_sec_max</code>.</dd>
3469           <dt><code>read_bytes_sec_max</code></dt>
3470           <dd>The optional <code>read_bytes_sec_max</code> element is the
3471             maximum read throughput limit in bytes per second.</dd>
3472           <dt><code>write_bytes_sec_max</code></dt>
3473           <dd>The optional <code>write_bytes_sec_max</code> element is the
3474             maximum write throughput limit in bytes per second.</dd>
3475           <dt><code>total_iops_sec_max</code></dt>
3476           <dd>The optional <code>total_iops_sec_max</code> element is the
3477             maximum total I/O operations per second.  This cannot
3478             appear with <code>read_iops_sec_max</code>
3479             or <code>write_iops_sec_max</code>.</dd>
3480           <dt><code>read_iops_sec_max</code></dt>
3481           <dd>The optional <code>read_iops_sec_max</code> element is the
3482             maximum read I/O operations per second.</dd>
3483           <dt><code>write_iops_sec_max</code></dt>
3484           <dd>The optional <code>write_iops_sec_max</code> element is the
3485             maximum write I/O operations per second.</dd>
3486           <dt><code>size_iops_sec</code></dt>
3487           <dd>The optional <code>size_iops_sec</code> element is the
3488             size of I/O operations per second.
3489           <p>
3490             <span class="since">Throughput limits since 1.2.11 and QEMU 1.7</span>
3491           </p>
3492           </dd>
3493           <dt><code>group_name</code></dt>
3494           <dd>The optional <code>group_name</code> provides the cability
3495             to share I/O throttling quota between multiple drives. This
3496             prevents end-users from circumventing a hosting provider's
3497             throttling policy by splitting 1 large drive in N small drives
3498             and getting N times the normal throttling quota. Any name may
3499             be used.
3500           <p>
3501             <span class="since">group_name since 3.0.0 and QEMU 2.4</span>
3502           </p>
3503           </dd>
3504           <dt><code>total_bytes_sec_max_length</code></dt>
3505           <dd>The optional <code>total_bytes_sec_max_length</code>
3506             element is the maximum duration in seconds for the
3507             <code>total_bytes_sec_max</code> burst period. Only valid
3508             when the <code>total_bytes_sec_max</code> is set.</dd>
3509           <dt><code>read_bytes_sec_max_length</code></dt>
3510           <dd>The optional <code>read_bytes_sec_max_length</code>
3511             element is the maximum duration in seconds for the
3512             <code>read_bytes_sec_max</code> burst period. Only valid
3513             when the <code>read_bytes_sec_max</code> is set.</dd>
3514           <dt><code>write_bytes_sec_max</code></dt>
3515           <dd>The optional <code>write_bytes_sec_max_length</code>
3516             element is the maximum duration in seconds for the
3517             <code>write_bytes_sec_max</code> burst period. Only valid
3518             when the <code>write_bytes_sec_max</code> is set.</dd>
3519           <dt><code>total_iops_sec_max_length</code></dt>
3520           <dd>The optional <code>total_iops_sec_max_length</code>
3521             element is the maximum duration in seconds for the
3522             <code>total_iops_sec_max</code> burst period. Only valid
3523             when the <code>total_iops_sec_max</code> is set.</dd>
3524           <dt><code>read_iops_sec_max_length</code></dt>
3525           <dd>The optional <code>read_iops_sec_max_length</code>
3526             element is the maximum duration in seconds for the
3527             <code>read_iops_sec_max</code> burst period. Only valid
3528             when the <code>read_iops_sec_max</code> is set.</dd>
3529           <dt><code>write_iops_sec_max</code></dt>
3530           <dd>The optional <code>write_iops_sec_max_length</code>
3531             element is the maximum duration in seconds for the
3532             <code>write_iops_sec_max</code> burst period. Only valid
3533             when the <code>write_iops_sec_max</code> is set.
3534           <p>
3535             <span class="since">Throughput length since 2.4.0 and QEMU 2.6</span>
3536           </p>
3537           </dd>
3538         </dl>
3539       </dd>
3540       <dt><code>driver</code></dt>
3541       <dd>
3542         The optional driver element allows specifying further details
3543         related to the hypervisor driver used to provide the disk.
3544         <span class="since">Since 0.1.8</span>
3545         <ul>
3546           <li>
3547             If the hypervisor supports multiple backend drivers, then
3548             the <code>name</code> attribute selects the primary
3549             backend driver name, while the optional <code>type</code>
3550             attribute provides the sub-type.  For example, xen
3551             supports a name of "tap", "tap2", "phy", or "file", with a
3552             type of "aio", while qemu only supports a name of "qemu",
3553             but multiple types including "raw", "bochs", "qcow2", and
3554             "qed".
3555           </li>
3556           <li>
3557             The optional <code>cache</code> attribute controls the
3558             cache mechanism, possible values are "default", "none",
3559             "writethrough", "writeback", "directsync" (like
3560             "writethrough", but it bypasses the host page cache) and
3561             "unsafe" (host may cache all disk io, and sync requests from
3562             guest are ignored).
3563             <span class="since">
3564               Since 0.6.0,
3565               "directsync" since 0.9.5,
3566               "unsafe" since 0.9.7
3567             </span>
3568           </li>
3569           <li>
3570             The optional <code>error_policy</code> attribute controls
3571             how the hypervisor will behave on a disk read or write
3572             error, possible values are "stop", "report", "ignore", and
3573             "enospace".<span class="since">Since 0.8.0, "report" since
3574             0.9.7</span> The default is left to the discretion of the
3575             hypervisor. There is also an
3576             optional <code>rerror_policy</code> that controls behavior
3577             for read errors only. <span class="since">Since
3578             0.9.7</span>. If no rerror_policy is given, error_policy
3579             is used for both read and write errors. If rerror_policy
3580             is given, it overrides the <code>error_policy</code> for
3581             read errors. Also note that "enospace" is not a valid
3582             policy for read errors, so if <code>error_policy</code> is
3583             set to "enospace" and no <code>rerror_policy</code> is
3584             given, the read error policy will be left at its default.
3585           </li>
3586           <li>
3587             The optional <code>io</code> attribute controls specific
3588             policies on I/O; qemu guests support "threads" and
3589             "native". <span class="since">Since 0.8.8</span>
3590           </li>
3591           <li>
3592             The optional <code>ioeventfd</code> attribute allows users to
3593             set <a href='https://patchwork.kernel.org/patch/43390/'>
3594             domain I/O asynchronous handling</a> for disk device.
3595             The default is left to the discretion of the hypervisor.
3596             Accepted values are "on" and "off". Enabling this allows
3597             qemu to execute VM while a separate thread handles I/O.
3598             Typically guests experiencing high system CPU utilization
3599             during I/O will benefit from this. On the other hand,
3600             on overloaded host it could increase guest I/O latency.
3601             <span class="since">Since 0.9.3 (QEMU and KVM only)</span>
3602             <b>In general you should leave this option alone, unless you
3603             are very certain you know what you are doing.</b>
3604           </li>
3605           <li>
3606             The optional <code>event_idx</code> attribute controls
3607             some aspects of device event processing. The value can be
3608             either 'on' or 'off' - if it is on, it will reduce the
3609             number of interrupts and exits for the guest. The default
3610             is determined by QEMU; usually if the feature is
3611             supported, default is on. In case there is a situation
3612             where this behavior is suboptimal, this attribute provides
3613             a way to force the feature off.
3614             <span class="since">Since 0.9.5 (QEMU and KVM only)</span>
3615             <b>In general you should leave this option alone, unless you
3616             are very certain you know what you are doing.</b>
3617           </li>
3618           <li>
3619             The optional <code>copy_on_read</code> attribute controls
3620             whether to copy read backing file into the image file. The
3621             value can be either "on" or "off".
3622             Copy-on-read avoids accessing the same backing file sectors
3623             repeatedly and is useful when the backing file is over a slow
3624             network. By default copy-on-read is off.
3625             <span class='since'>Since 0.9.10 (QEMU and KVM only)</span>
3626           </li>
3627           <li>
3628             The optional <code>discard</code> attribute controls whether
3629             discard requests (also known as "trim" or "unmap") are
3630             ignored or passed to the filesystem. The value can be either
3631             "unmap" (allow the discard request to be passed) or "ignore"
3632             (ignore the discard request).
3633             <span class='since'>Since 1.0.6 (QEMU and KVM only)</span>
3634           </li>
3635           <li>
3636             The optional <code>detect_zeroes</code> attribute controls whether
3637             to detect zero write requests.  The value can be "off", "on" or
3638             "unmap".  First two values turn the detection off and on,
3639             respectively.  The third value ("unmap") turns the detection on
3640             and additionally tries to discard such areas from the image based
3641             on the value of <code>discard</code> above (it will act as "on"
3642             if <code>discard</code> is set to "ignore").  NB enabling the
3643             detection is a compute intensive operation, but can save file
3644             space and/or time on slow media.
3645             <span class='since'>Since 2.0.0</span>
3646           </li>
3647           <li>
3648             The optional <code>iothread</code> attribute assigns the
3649             disk to an IOThread as defined by the range for the domain
3650             <a href="#elementsIOThreadsAllocation"><code>iothreads</code></a>
3651             value. Multiple disks may be assigned to the same IOThread and
3652             are numbered from 1 to the domain iothreads value. Available
3653             for a disk device <code>target</code> configured to use "virtio"
3654             <code>bus</code> and "pci" or "ccw" <code>address</code> types.
3655             <span class='since'>Since 1.2.8 (QEMU 2.1)</span>
3656           </li>
3657           <li>
3658             The optional <code>queues</code> attribute specifies the number of
3659             virt queues for virtio-blk. (<span class="since">Since 3.9.0</span>)
3660           </li>
3661           <li>
3662           For virtio disks,
3663           <a href="#elementsVirtio">Virtio-specific options</a> can also be
3664           set. (<span class="since">Since 3.5.0</span>)
3665           </li>
3666         </ul>
3667       </dd>
3668       <dt><code>backenddomain</code></dt>
3669       <dd>The optional <code>backenddomain</code> element allows specifying a
3670           backend domain (aka driver domain) hosting the disk.  Use the
3671           <code>name</code> attribute to specify the backend domain name.
3672           <span class="since">Since 1.2.13 (Xen only)</span>
3673       </dd>
3674       <dt><code>boot</code></dt>
3675       <dd>Specifies that the disk is bootable. The <code>order</code>
3676         attribute determines the order in which devices will be tried during
3677         boot sequence. On the S390 architecture only the first boot device is
3678         used. The optional <code>loadparm</code> attribute is an 8 character
3679         string which can be queried by guests on S390 via sclp or diag 308.
3680         Linux guests on S390 can use <code>loadparm</code> to select a boot
3681         entry. <span class="since">Since 3.5.0</span>
3682         The per-device <code>boot</code> elements cannot be used together
3683         with general boot elements in
3684         <a href="#elementsOSBIOS">BIOS bootloader</a> section.
3685         <span class="since">Since 0.8.8</span>
3686       </dd>
3687       <dt><code>encryption</code></dt>
3688       <dd>Starting with <span class="since">libvirt 3.9.0</span> the
3689         <code>encryption</code> element is preferred to be a sub-element
3690         of the <code>source</code> element. If present, specifies how the
3691         volume is encrypted using "qcow". See the
3692         <a href="formatstorageencryption.html">Storage Encryption</a> page
3693         for more information.
3694       </dd>
3695       <dt><code>readonly</code></dt>
3696       <dd>If present, this indicates the device cannot be modified by
3697         the guest.  For now, this is the default for disks with
3698         attribute <code>device='cdrom'</code>.
3699       </dd>
3700       <dt><code>shareable</code></dt>
3701       <dd>If present, this indicates the device is expected to be shared
3702           between domains (assuming the hypervisor and OS support this),
3703           which means that caching should be deactivated for that device.
3704       </dd>
3705       <dt><code>transient</code></dt>
3706       <dd>If present, this indicates that changes to the device
3707         contents should be reverted automatically when the guest
3708         exits.  With some hypervisors, marking a disk transient
3709         prevents the domain from participating in migration or
3710         snapshots. <span class="since">Since 0.9.5</span>
3711       </dd>
3712       <dt><code>serial</code></dt>
3713       <dd>If present, this specify serial number of virtual hard drive.
3714           For example, it may look
3715           like <code>&lt;serial&gt;WD-WMAP9A966149&lt;/serial&gt;</code>.
3716           Not supported for scsi-block devices, that is those using
3717           disk <code>type</code> 'block' using <code>device</code> 'lun'
3718           on <code>bus</code> 'scsi'.
3719           <span class="since">Since 0.7.1</span>
3720       </dd>
3721       <dt><code>wwn</code></dt>
3722       <dd>If present, this element specifies the WWN (World Wide Name)
3723         of a virtual hard disk or CD-ROM drive. It must be composed
3724         of 16 hexadecimal digits.
3725         <span class='since'>Since 0.10.1</span>
3726       </dd>
3727       <dt><code>vendor</code></dt>
3728       <dd>If present, this element specifies the vendor of a virtual hard
3729         disk or CD-ROM device. It must not be longer than 8 printable
3730         characters.
3731         <span class='since'>Since 1.0.1</span>
3732       </dd>
3733       <dt><code>product</code></dt>
3734       <dd>If present, this element specifies the product of a virtual hard
3735         disk or CD-ROM device. It must not be longer than 16 printable
3736         characters.
3737         <span class='since'>Since 1.0.1</span>
3738       </dd>
3739       <dt><code>address</code></dt>
3740       <dd>If present, the <code>address</code> element ties the disk
3741         to a given slot of a controller (the
3742         actual <code>&lt;controller&gt;</code> device can often be
3743         inferred by libvirt, although it can
3744         be <a href="#elementsControllers">explicitly specified</a>).
3745         The <code>type</code> attribute is mandatory, and is typically
3746         "pci" or "drive".  For a "pci" controller, additional
3747         attributes for <code>bus</code>, <code>slot</code>,
3748         and <code>function</code> must be present, as well as
3749         optional <code>domain</code> and <code>multifunction</code>.
3750         Multifunction defaults to 'off'; any other value requires
3751         QEMU 0.1.3 and <span class="since">libvirt 0.9.7</span>.  For a
3752         "drive" controller, additional attributes
3753         <code>controller</code>, <code>bus</code>, <code>target</code>
3754         (<span class="since">libvirt 0.9.11</span>), and <code>unit</code>
3755         are available, each defaulting to 0.
3756       </dd>
3757       <dt><code>auth</code></dt>
3758       <dd>Starting with <span class="since">libvirt 3.9.0</span> the
3759         <code>auth</code> element is preferred to be a sub-element of
3760         the <code>source</code> element. The element is still read and
3761         managed as a <code>disk</code> sub-element. It is invalid to use
3762         <code>auth</code> as both a sub-element of <code>disk</code>
3763         and <code>source</code>. The <code>auth</code> element was
3764         introduced as a <code>disk</code> sub-element in
3765         <span class="since">libvirt 0.9.7.</span>
3766       </dd>
3767       <dt><code>geometry</code></dt>
3768       <dd>The optional <code>geometry</code> element provides the
3769         ability to override geometry settings. This mostly useful for
3770         S390 DASD-disks or older DOS-disks.  <span class="since">0.10.0</span>
3771         <dl>
3772           <dt><code>cyls</code></dt>
3773           <dd>The <code>cyls</code> attribute is the
3774             number of cylinders. </dd>
3775           <dt><code>heads</code></dt>
3776           <dd>The <code>heads</code> attribute is the
3777             number of heads. </dd>
3778           <dt><code>secs</code></dt>
3779           <dd>The <code>secs</code> attribute is the
3780             number of sectors per track. </dd>
3781           <dt><code>trans</code></dt>
3782           <dd>The optional <code>trans</code> attribute is the
3783             BIOS-Translation-Modus (none, lba or auto)</dd>
3784         </dl>
3785       </dd>
3786       <dt><code>blockio</code></dt>
3787       <dd>If present, the <code>blockio</code> element allows
3788         to override any of the block device properties listed below.
3789         <span class="since">Since 0.10.2 (QEMU and KVM)</span>
3790         <dl>
3791           <dt><code>logical_block_size</code></dt>
3792           <dd>The logical block size the disk will report to the guest
3793             OS. For Linux this would be the value returned by the
3794             BLKSSZGET ioctl and describes the smallest units for disk
3795             I/O.
3796           </dd>
3797           <dt><code>physical_block_size</code></dt>
3798           <dd>The physical block size the disk will report to the guest
3799             OS. For Linux this would be the value returned by the
3800             BLKPBSZGET ioctl and describes the disk's hardware sector
3801             size which can be relevant for the alignment of disk data.
3802           </dd>
3803         </dl>
3804       </dd>
3805     </dl>
3806
3807     <h4><a id="elementsFilesystems">Filesystems</a></h4>
3808
3809     <p>
3810       A directory on the host that can be accessed directly from the guest.
3811       <span class="since">since 0.3.3, since 0.8.5 for QEMU/KVM</span>
3812     </p>
3813
3814 <pre>
3815 ...
3816 &lt;devices&gt;
3817   &lt;filesystem type='template'&gt;
3818     &lt;source name='my-vm-template'/&gt;
3819     &lt;target dir='/'/&gt;
3820   &lt;/filesystem&gt;
3821   &lt;filesystem type='mount' accessmode='passthrough'&gt;
3822     &lt;driver type='path' wrpolicy='immediate'/&gt;
3823     &lt;source dir='/export/to/guest'/&gt;
3824     &lt;target dir='/import/from/host'/&gt;
3825     &lt;readonly/&gt;
3826   &lt;/filesystem&gt;
3827   &lt;filesystem type='file' accessmode='passthrough'&gt;
3828     &lt;driver name='loop' type='raw'/&gt;
3829     &lt;driver type='path' wrpolicy='immediate'/&gt;
3830     &lt;source file='/export/to/guest.img'/&gt;
3831     &lt;target dir='/import/from/host'/&gt;
3832     &lt;readonly/&gt;
3833   &lt;/filesystem&gt;
3834   ...
3835 &lt;/devices&gt;
3836 ...</pre>
3837
3838     <dl>
3839       <dt><code>filesystem</code></dt>
3840       <dd>
3841
3842       The filesystem attribute <code>type</code> specifies the type of the
3843       <code>source</code>. The possible values are:
3844
3845         <dl>
3846         <dt><code>mount</code></dt>
3847         <dd>
3848         A host directory to mount in the guest. Used by LXC,
3849         OpenVZ <span class="since">(since 0.6.2)</span>
3850         and QEMU/KVM <span class="since">(since 0.8.5)</span>.
3851         This is the default <code>type</code> if one is not specified.
3852         This mode also has an optional
3853         sub-element <code>driver</code>, with an
3854         attribute <code>type='path'</code>
3855         or <code>type='handle'</code> <span class="since">(since
3856         0.9.7)</span>. The driver block has an optional attribute
3857         <code>wrpolicy</code> that further controls interaction with
3858         the host page cache; omitting the attribute gives default behavior,
3859         while the value <code>immediate</code> means that a host writeback
3860         is immediately triggered for all pages touched during a guest file
3861         write operation <span class="since">(since 0.9.10)</span>.
3862         </dd>
3863         <dt><code>template</code></dt>
3864         <dd>
3865         OpenVZ filesystem template. Only used by OpenVZ driver.
3866         </dd>
3867         <dt><code>file</code></dt>
3868         <dd>
3869         A host file will be treated as an image and mounted in
3870         the guest. The filesystem format will be autodetected.
3871         Only used by LXC driver.
3872         </dd>
3873         <dt><code>block</code></dt>
3874         <dd>
3875         A host block device to mount in the guest. The filesystem
3876         format will be autodetected. Only used by LXC driver
3877         <span class="since">(since 0.9.5)</span>.
3878         </dd>
3879         <dt><code>ram</code></dt>
3880         <dd>
3881           An in-memory filesystem, using memory from the host OS.
3882           The source element has a single attribute <code>usage</code>
3883           which gives the memory usage limit in KiB, unless units
3884           are specified by the <code>units</code> attribute. Only used
3885           by LXC driver.
3886           <span class="since"> (since 0.9.13)</span></dd>
3887         <dt><code>bind</code></dt>
3888         <dd>
3889           A directory inside the guest will be bound to another
3890           directory inside the guest. Only used by LXC driver
3891           <span class="since"> (since 0.9.13)</span></dd>
3892         </dl>
3893
3894       The filesystem block has an optional attribute <code>accessmode</code>
3895       which specifies the security mode for accessing the source
3896       <span class="since">(since 0.8.5)</span>. Currently this only works
3897       with <code>type='mount'</code> for the QEMU/KVM driver. The possible
3898       values are:
3899
3900         <dl>
3901         <dt><code>passthrough</code></dt>
3902         <dd>
3903         The <code>source</code> is accessed with the permissions of the
3904         user inside the guest. This is the default <code>accessmode</code> if
3905         one is not specified.
3906         <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html">More info</a>
3907         </dd>
3908         <dt><code>mapped</code></dt>
3909         <dd>
3910         The <code>source</code> is accessed with the permissions of the
3911         hypervisor (QEMU process).
3912         <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html">More info</a>
3913         </dd>
3914         <dt><code>squash</code></dt>
3915         <dd>
3916         Similar to 'passthrough', the exception is that failure of
3917         privileged operations like 'chown' are ignored. This makes a
3918         passthrough-like mode usable for people who run the hypervisor
3919         as non-root.
3920         <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html">More info</a>
3921         </dd>
3922         </dl>
3923
3924       <span class="since">Since 5.2.0</span>, the filesystem element
3925       has an optional attribute <code>model</code> with supported values
3926       "virtio-transitional", "virtio-non-transitional", or "virtio".
3927       See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
3928       for more details.
3929       </dd>
3930
3931       <dt><code>driver</code></dt>
3932       <dd>
3933         The optional driver element allows specifying further details
3934         related to the hypervisor driver used to provide the filesystem.
3935         <span class="since">Since 1.0.6</span>
3936         <ul>
3937           <li>
3938             If the hypervisor supports multiple backend drivers, then
3939             the <code>type</code> attribute selects the primary
3940             backend driver name, while the <code>format</code>
3941             attribute provides the format type. For example, LXC
3942             supports a type of "loop", with a format of "raw" or
3943             "nbd" with any format. QEMU supports a type of "path"
3944             or "handle", but no formats. Virtuozzo driver supports
3945             a type of "ploop" with a format of "ploop".
3946           </li>
3947           <li>
3948           For virtio-backed devices,
3949           <a href="#elementsVirtio">Virtio-specific options</a> can also be
3950           set. (<span class="since">Since 3.5.0</span>)
3951           </li>
3952         </ul>
3953       </dd>
3954
3955       <dt><code>source</code></dt>
3956       <dd>
3957         The resource on the host that is being accessed in the guest. The
3958         <code>name</code> attribute must be used with
3959         <code>type='template'</code>, and the <code>dir</code> attribute must
3960         be used with <code>type='mount'</code>. The <code>usage</code> attribute
3961         is used with <code>type='ram'</code> to set the memory limit in KiB,
3962         unless units are specified by the <code>units</code> attribute.
3963       </dd>
3964
3965       <dt><code>target</code></dt>
3966       <dd>
3967         Where the <code>source</code> can be accessed in the guest. For
3968         most drivers this is an automatic mount point, but for QEMU/KVM
3969         this is merely an arbitrary string tag that is exported to the
3970         guest as a hint for where to mount.
3971       </dd>
3972
3973       <dt><code>readonly</code></dt>
3974       <dd>
3975         Enables exporting filesystem as a readonly mount for guest, by
3976         default read-write access is given (currently only works for
3977         QEMU/KVM driver).
3978       </dd>
3979
3980       <dt><code>space_hard_limit</code></dt>
3981       <dd>
3982         Maximum space available to this guest's filesystem.
3983         <span class="since">Since 0.9.13</span>
3984       </dd>
3985
3986       <dt><code>space_soft_limit</code></dt>
3987       <dd>
3988         Maximum space available to this guest's filesystem. The container is
3989         permitted to exceed its soft limits for a grace period of time. Afterwards the
3990         hard limit is enforced.
3991         <span class="since">Since 0.9.13</span>
3992       </dd>
3993     </dl>
3994
3995     <h4><a id="elementsAddress">Device Addresses</a></h4>
3996
3997     <p>
3998       Many devices have an optional <code>&lt;address&gt;</code>
3999       sub-element to describe where the device is placed on the
4000       virtual bus presented to the guest.  If an address (or any
4001       optional attribute within an address) is omitted on
4002       input, libvirt will generate an appropriate address; but an
4003       explicit address is required if more control over layout is
4004       required.  See below for device examples including an address
4005       element.
4006     </p>
4007
4008     <p>
4009       Every address has a mandatory attribute <code>type</code> that
4010       describes which bus the device is on.  The choice of which
4011       address to use for a given device is constrained in part by the
4012       device and the architecture of the guest.  For example,
4013       a <code>&lt;disk&gt;</code> device
4014       uses <code>type='drive'</code>, while
4015       a <code>&lt;console&gt;</code> device would
4016       use <code>type='pci'</code> on i686 or x86_64 guests,
4017       or <code>type='spapr-vio'</code> on PowerPC64 pseries guests.
4018       Each address type has further optional attributes that control
4019       where on the bus the device will be placed:
4020     </p>
4021
4022     <dl>
4023       <dt><code>pci</code></dt>
4024       <dd>PCI addresses have the following additional
4025         attributes: <code>domain</code> (a 2-byte hex integer, not
4026         currently used by qemu), <code>bus</code> (a hex value between
4027         0 and 0xff, inclusive), <code>slot</code> (a hex value between
4028         0x0 and 0x1f, inclusive), and <code>function</code> (a value
4029         between 0 and 7, inclusive).  Also available is
4030         the <code>multifunction</code> attribute, which controls
4031         turning on the multifunction bit for a particular
4032         slot/function in the PCI control register
4033         (<span class="since">since 0.9.7, requires QEMU
4034         0.13</span>). <code>multifunction</code> defaults to 'off',
4035         but should be set to 'on' for function 0 of a slot that will
4036         have multiple functions used.
4037         (<span class="since">Since 4.10.0</span>), PCI address extensions
4038         depending on the architecture are supported. For example, PCI
4039         addresses for S390 guests will have a <code>zpci</code> child
4040         element, with two attributes: <code>uid</code> (a hex value
4041         between 0x0001 and 0xffff, inclusive), and <code>fid</code> (a
4042         hex value between 0x00000000 and 0xffffffff, inclusive) used by
4043         PCI devices on S390 for User-defined Identifiers and Function
4044         Identifiers.<br/>
4045         <span class="since">Since 1.3.5</span>, some hypervisor
4046         drivers may accept an <code>&lt;address type='pci'/&gt;</code>
4047         element with no other attributes as an explicit request to
4048         assign a PCI address for the device rather than some other
4049         type of address that may also be appropriate for that same
4050         device (e.g. virtio-mmio).
4051       </dd>
4052       <dt><code>drive</code></dt>
4053       <dd>Drive addresses have the following additional
4054         attributes: <code>controller</code> (a 2-digit controller
4055         number), <code>bus</code> (a 2-digit bus number),
4056         <code>target</code> (a 2-digit target number),
4057         and <code>unit</code> (a 2-digit unit number on the bus).
4058       </dd>
4059       <dt><code>virtio-serial</code></dt>
4060       <dd>Each virtio-serial address has the following additional
4061         attributes: <code>controller</code> (a 2-digit controller
4062         number), <code>bus</code> (a 2-digit bus number),
4063         and <code>slot</code> (a 2-digit slot within the bus).
4064       </dd>
4065       <dt><code>ccid</code></dt>
4066       <dd>A CCID address, for smart-cards, has the following
4067         additional attributes: <code>bus</code> (a 2-digit bus
4068         number), and <code>slot</code> attribute (a 2-digit slot
4069         within the bus).  <span class="since">Since 0.8.8.</span>
4070       </dd>
4071       <dt><code>usb</code></dt>
4072       <dd>USB addresses have the following additional
4073         attributes: <code>bus</code> (a hex value between 0 and 0xfff,
4074         inclusive), and <code>port</code> (a dotted notation of up to
4075         four octets, such as 1.2 or 2.1.3.1).
4076       </dd>
4077       <dt><code>spapr-vio</code></dt>
4078       <dd>On PowerPC pseries guests, devices can be assigned to the
4079         SPAPR-VIO bus.  It has a flat 32-bit address space; by
4080         convention, devices are generally assigned at a non-zero
4081         multiple of 0x00001000, but other addresses are valid and
4082         permitted by libvirt.  Each address has the following
4083         additional attribute: <code>reg</code> (the hex value address
4084         of the starting register).  <span class="since">Since
4085         0.9.9.</span>
4086       </dd>
4087       <dt><code>ccw</code></dt>
4088       <dd>S390 guests with a <code>machine</code> value of
4089         s390-ccw-virtio use the native CCW bus for I/O devices.
4090         CCW bus addresses have the following additional attributes:
4091         <code>cssid</code> (a hex value between 0 and 0xfe, inclusive),
4092         <code>ssid</code> (a value between 0 and 3, inclusive) and
4093         <code>devno</code> (a hex value between 0 and 0xffff, inclusive).
4094         Partially specified bus addresses are not allowed.
4095         If omitted, libvirt will assign a free bus address with
4096         cssid=0xfe and ssid=0. Virtio-ccw devices must have their cssid
4097         set to 0xfe.
4098         <span class="since">Since 1.0.4</span>
4099       </dd>
4100       <dt><code>virtio-mmio</code></dt>
4101       <dd>This places the device on the virtio-mmio transport, which is
4102         currently only available for some <code>armv7l</code> and
4103         <code>aarch64</code> virtual machines. virtio-mmio addresses
4104         do not have any additional attributes.
4105         <span class="since">Since 1.1.3</span><br/>
4106         If the guest architecture is <code>aarch64</code> and the machine
4107         type is <code>virt</code>, libvirt will automatically assign PCI
4108         addresses to devices; however, the presence of a single device
4109         with virtio-mmio address in the guest configuration will cause
4110         libvirt to assign virtio-mmio addresses to all further devices.
4111         <span class="since">Since 3.0.0</span>
4112       </dd>
4113       <dt><code>isa</code></dt>
4114       <dd>ISA addresses have the following additional
4115         attributes: <code>iobase</code> and <code>irq</code>.
4116         <span class="since">Since 1.2.1</span>
4117       </dd>
4118     </dl>
4119
4120     <h4><a id="elementsVirtio">Virtio-related options</a></h4>
4121
4122     <p>
4123       QEMU's virtio devices have some attributes related to the virtio transport under
4124       the <code>driver</code> element:
4125       The <code>iommu</code> attribute enables the use of emulated IOMMU
4126       by the device. The attribute <code>ats</code> controls the Address
4127       Translation Service support for PCIe devices. This is needed to make use
4128       of IOTLB support (see <a href="#elementsIommu">IOMMU device</a>).
4129       Possible values are <code>on</code> or <code>off</code>.
4130       <span class="since">Since 3.5.0</span>
4131     </p>
4132
4133     <h4><a id="elementsVirtioTransitional">Virtio transitional devices</a></h4>
4134
4135     <p>
4136       <span class="since">Since 5.2.0</span>, some of QEMU's virtio devices,
4137       when used with PCI/PCIe machine types, accept the following
4138       <code>model</code> values:
4139     </p>
4140
4141     <dl>
4142       <dt><code>virtio-transitional</code></dt>
4143       <dd>This device can work both with virtio 0.9 and virtio 1.0 guest
4144       drivers, so it's the best choice when compatibility with older
4145       guest operating systems is desired. libvirt will plug the device
4146       into a conventional PCI slot.
4147       </dd>
4148       <dt><code>virtio-non-transitional</code></dt>
4149       <dd>This device can only work with virtio 1.0 guest drivers, and it's
4150       the recommended option unless compatibility with older guest
4151       operating systems is necessary. libvirt will plug the device into
4152       either a PCI Express slot or a conventional PCI slot based on the
4153       machine type, resulting in a more optimized PCI topology.
4154       </dd>
4155       <dt><code>virtio</code></dt>
4156       <dd>This device will work like a <code>virtio-non-transitional</code>
4157       device when plugged into a PCI Express slot, and like a
4158       <code>virtio-transitional</code> device otherwise; libvirt will
4159       pick one or the other based on the machine type. This is the best
4160       choice when compatibility with libvirt versions older than 5.2.0
4161       is necessary, but it's otherwise not recommended to use it.
4162       </dd>
4163     </dl>
4164
4165     <p>
4166       While the information outlined above applies to most virtio devices,
4167       there are a few exceptions:
4168     </p>
4169
4170     <ul>
4171       <li>
4172         for SCSI controllers, <code>virtio-scsi</code> must be used instead
4173         of <code>virtio</code> for backwards compatibility reasons;
4174       </li>
4175       <li>
4176         some devices, such as GPUs and input devices (keyboard, tablet and
4177         mouse), are only defined in the virtio 1.0 spec and as such don't
4178         have a transitional variant: the only accepted model is
4179         <code>virtio</code>, which will result in a non-transitional device.
4180       </li>
4181     </ul>
4182
4183     <p>
4184       For more details see the
4185       <a href="https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html">qemu patch posting</a> and the
4186       <a href="http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html">virtio-1.0 spec</a>.
4187     </p>
4188
4189
4190     <h4><a id="elementsControllers">Controllers</a></h4>
4191
4192     <p>
4193       Depending on the guest architecture, some device buses can
4194       appear more than once, with a group of virtual devices tied to a
4195       virtual controller.  Normally, libvirt can automatically infer such
4196       controllers without requiring explicit XML markup, but sometimes
4197       it is necessary to provide an explicit controller element, notably
4198       when planning the <a href="pci-hotplug.html">PCI topology</a>
4199       for guests where device hotplug is expected.
4200     </p>
4201
4202 <pre>
4203 ...
4204 &lt;devices&gt;
4205   &lt;controller type='ide' index='0'/&gt;
4206   &lt;controller type='virtio-serial' index='0' ports='16' vectors='4'/&gt;
4207   &lt;controller type='virtio-serial' index='1'&gt;
4208     &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/&gt;
4209   &lt;/controller&gt;
4210   &lt;controller type='scsi' index='0' model='virtio-scsi'&gt;
4211     &lt;driver iothread='4'/&gt;
4212     &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/&gt;
4213   &lt;/controller&gt;
4214   &lt;controller type='xenbus' maxGrantFrames='64'/&gt;
4215   ...
4216 &lt;/devices&gt;
4217 ...</pre>
4218
4219     <p>
4220       Each controller has a mandatory attribute <code>type</code>,
4221       which must be one of 'ide', 'fdc', 'scsi', 'sata', 'usb',
4222       'ccid', 'virtio-serial' or 'pci', and a mandatory
4223       attribute <code>index</code> which is the decimal integer
4224       describing in which order the bus controller is encountered (for
4225       use in <code>controller</code> attributes of
4226       <code>&lt;address&gt;</code> elements).
4227       <span class="since">Since 1.3.5</span> the index is optional; if
4228       not specified, it will be auto-assigned to be the lowest unused
4229       index for the given controller type. Some controller types have
4230       additional attributes that control specific features, such as:
4231     </p>
4232
4233       <dl>
4234         <dt><code>virtio-serial</code></dt>
4235         <dd>The <code>virtio-serial</code> controller has two additional
4236         optional attributes <code>ports</code> and <code>vectors</code>,
4237         which control how many devices can be connected through the
4238         controller. <span class="since">Since 5.2.0</span>, it
4239         supports an optional attribute <code>model</code> which can
4240         be 'virtio', 'virtio-transitional', or 'virtio-non-transitional'. See
4241         <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
4242         for more details.
4243         </dd>
4244         <dt><code>scsi</code></dt>
4245         <dd>A <code>scsi</code> controller has an optional attribute
4246         <code>model</code>, which is one of 'auto', 'buslogic', 'ibmvscsi',
4247         'lsilogic', 'lsisas1068', 'lsisas1078', 'virtio-scsi',
4248         'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. See
4249         <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
4250         for more details.
4251         </dd>
4252         <dt><code>usb</code></dt>
4253         <dd>A <code>usb</code> controller has an optional attribute
4254         <code>model</code>, which is one of "piix3-uhci", "piix4-uhci",
4255         "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3",
4256         "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pvusb
4257         with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu
4258         backend, version 2.0) or "qemu-xhci". Additionally,
4259          <span class="since">since 0.10.0</span>, if the USB bus needs to
4260          be explicitly disabled for the guest, <code>model='none'</code>
4261          may be used.  <span class="since">Since 1.0.5</span>, no default
4262          USB controller will be built on s390.
4263          <span class="since">Since 1.3.5</span>, USB controllers accept a
4264          <code>ports</code> attribute to configure how many devices can be
4265          connected to the controller.</dd>
4266         <dt><code>ide</code></dt>
4267         <dd><span class="since">Since 3.10.0</span> for the vbox driver, the
4268         <code>ide</code> controller has an optional attribute
4269         <code>model</code>, which is one of "piix3", "piix4" or "ich6".</dd>
4270         <dt><code>xenbus</code></dt>
4271         <dd><span class="since">Since 5.2.0</span>, the <code>xenbus</code>
4272         controller has an optional attribute <code>maxGrantFrames</code>,
4273         which specifies the maximum number of grant frames the controller
4274         makes available for connected devices.</dd>
4275       </dl>
4276
4277     <p>
4278       Note: The PowerPC64 "spapr-vio" addresses do not have an
4279       associated controller.
4280     </p>
4281
4282     <p>
4283       For controllers that are themselves devices on a PCI or USB bus,
4284       an optional sub-element <code>&lt;address&gt;</code> can specify
4285       the exact relationship of the controller to its master bus, with
4286       semantics <a href="#elementsAddress">given above</a>.
4287     </p>
4288
4289     <p>
4290       An optional sub-element <code>driver</code> can specify the driver
4291       specific options:
4292     </p>
4293     <dl>
4294       <dt><code>queues</code></dt>
4295       <dd>
4296         The optional <code>queues</code> attribute specifies the number of
4297         queues for the controller. For best performance, it's recommended to
4298         specify a value matching the number of vCPUs.
4299         <span class="since">Since 1.0.5 (QEMU and KVM only)</span>
4300       </dd>
4301       <dt><code>cmd_per_lun</code></dt>
4302       <dd>
4303         The optional <code>cmd_per_lun</code> attribute specifies the maximum
4304         number of commands that can be queued on devices controlled by the
4305         host.
4306         <span class="since">Since 1.2.7 (QEMU and KVM only)</span>
4307       </dd>
4308       <dt><code>max_sectors</code></dt>
4309       <dd>
4310         The optional <code>max_sectors</code> attribute specifies the maximum
4311         amount of data in bytes that will be transferred to or from the device
4312         in a single command. The transfer length is measured in sectors, where
4313         a sector is 512 bytes.
4314         <span class="since">Since 1.2.7 (QEMU and KVM only)</span>
4315       </dd>
4316       <dt><code>ioeventfd</code></dt>
4317       <dd>
4318         The optional <code>ioeventfd</code> attribute specifies
4319         whether the controller should use
4320         <a href='https://patchwork.kernel.org/patch/43390/'>
4321         I/O asynchronous handling</a> or not.  Accepted values are
4322         "on" and "off". <span class="since">Since 1.2.18</span>
4323       </dd>
4324       <dt><code>iothread</code></dt>
4325       <dd>
4326         Supported for controller type <code>scsi</code> using model
4327         <code>virtio-scsi</code> for <code>address</code> types
4328         <code>pci</code> and <code>ccw</code>
4329         <span class="since">since 1.3.5 (QEMU 2.4)</span>.
4330
4331         The optional <code>iothread</code> attribute assigns the controller
4332         to an IOThread as defined by the range for the domain
4333         <a href="#elementsIOThreadsAllocation"><code>iothreads</code></a>
4334         value. Each SCSI <code>disk</code> assigned to use the specified
4335         <code>controller</code> will utilize the same IOThread. If a specific
4336         IOThread is desired for a specific SCSI <code>disk</code>, then
4337         multiple controllers must be defined each having a specific
4338         <code>iothread</code> value. The <code>iothread</code> value
4339         must be within the range 1 to the domain iothreads value.
4340       </dd>
4341       <dt>virtio options</dt>
4342       <dd>
4343         For virtio controllers,
4344         <a href="#elementsVirtio">Virtio-specific options</a> can also be
4345         set. (<span class="since">Since 3.5.0</span>)
4346       </dd>
4347     </dl>
4348     <p>
4349       USB companion controllers have an optional
4350       sub-element <code>&lt;master&gt;</code> to specify the exact
4351       relationship of the companion to its master controller.
4352       A companion controller is on the same bus as its master, so
4353       the companion <code>index</code> value should be equal.
4354       Not all controller models can be used as companion controllers
4355       and libvirt might provide some sensible defaults (settings
4356       of <code>master startport</code> and <code>function</code> of an
4357       address) for some particular models.
4358       Preferred companion controllers are <code>ich-uhci[123]</code>.
4359     </p>
4360
4361 <pre>
4362 ...
4363 &lt;devices&gt;
4364   &lt;controller type='usb' index='0' model='ich9-ehci1'&gt;
4365     &lt;address type='pci' domain='0' bus='0' slot='4' function='7'/&gt;
4366   &lt;/controller&gt;
4367   &lt;controller type='usb' index='0' model='ich9-uhci1'&gt;
4368     &lt;master startport='0'/&gt;
4369     &lt;address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/&gt;
4370   &lt;/controller&gt;
4371   ...
4372 &lt;/devices&gt;
4373 ...</pre>
4374
4375     <p>
4376       PCI controllers have an optional <code>model</code> attribute; possible
4377       values for this attribute are
4378     </p>
4379     <ul>
4380       <li>
4381         <code>pci-root</code>, <code>pci-bridge</code>
4382         (<span class="since">since 1.0.5</span>)
4383       </li>
4384       <li>
4385         <code>pcie-root</code>, <code>dmi-to-pci-bridge</code>
4386         (<span class="since">since 1.1.2</span>)
4387       </li>
4388       <li>
4389         <code>pcie-root-port</code>, <code>pcie-switch-upstream-port</code>,
4390         <code>pcie-switch-downstream-port</code>
4391         (<span class="since">since 1.2.19</span>)
4392       </li>
4393       <li>
4394         <code>pci-expander-bus</code>, <code>pcie-expander-bus</code>
4395         (<span class="since">since 1.3.4</span>)
4396       </li>
4397       <li>
4398         <code>pcie-to-pci-bridge</code>
4399         (<span class="since">since 4.3.0</span>)
4400       </li>
4401     </ul>
4402     <p>
4403       The root controllers (<code>pci-root</code>
4404       and <code>pcie-root</code>) have an
4405       optional <code>pcihole64</code> element specifying how big (in
4406       kilobytes, or in the unit specified by <code>pcihole64</code>'s
4407       <code>unit</code> attribute) the 64-bit PCI hole should be. Some guests (like
4408       Windows XP or Windows Server 2003) might crash when QEMU and Seabios
4409       are recent enough to support 64-bit PCI holes, unless this is disabled
4410       (set to 0). <span class="since">Since 1.1.2 (QEMU only)</span>
4411     </p>
4412     <p>
4413       PCI controllers also have an optional
4414       subelement <code>&lt;model&gt;</code> with an attribute
4415       <code>name</code>. The name attribute holds the name of the
4416       specific device that qemu is emulating (e.g. "i82801b11-bridge")
4417       rather than simply the class of device ("pcie-to-pci-bridge",
4418       "pci-bridge"), which is set in the controller element's
4419       model <b>attribute</b>.  In almost all cases, you should not
4420       manually add a <code>&lt;model&gt;</code> subelement to a
4421       controller, nor should you modify one that is automatically
4422       generated by libvirt. <span class="since">Since 1.2.19 (QEMU
4423       only).</span>
4424     </p>
4425     <p>
4426       PCI controllers also have an optional
4427       subelement <code>&lt;target&gt;</code> with the attributes and
4428       subelements listed below. These are configurable items that 1)
4429       are visible to the guest OS so must be preserved for guest ABI
4430       compatibility, and 2) are usually left to default values or
4431       derived automatically by libvirt. In almost all cases, you
4432       should not manually add a <code>&lt;target&gt;</code> subelement
4433       to a controller, nor should you modify the values in the those
4434       that are automatically generated by
4435       libvirt. <span class="since">Since 1.2.19 (QEMU only).</span>
4436     </p>
4437     <dl>
4438       <dt><code>chassisNr</code></dt>
4439       <dd>
4440         PCI controllers that have attribute model="pci-bridge", can
4441         also have a <code>chassisNr</code> attribute in
4442         the <code>&lt;target&gt;</code> subelement, which is used to
4443         control QEMU's "chassis_nr" option for the pci-bridge device
4444         (normally libvirt automatically sets this to the same value as
4445         the index attribute of the pci controller). If set, chassisNr
4446         must be between 1 and 255.
4447       </dd>
4448       <dt><code>chassis</code></dt>
4449       <dd>
4450         pcie-root-port and pcie-switch-downstream-port controllers can
4451         also have a <code>chassis</code> attribute in
4452         the <code>&lt;target&gt;</code> subelement, which is used to
4453         set the controller's "chassis" configuration value, which is
4454         visible to the virtual machine. If set, chassis must be
4455         between 0 and 255.
4456       </dd>
4457       <dt><code>port</code></dt>
4458       <dd>
4459         pcie-root-port and pcie-switch-downstream-port controllers can
4460         also have a <code>port</code> attribute in
4461         the <code>&lt;target&gt;</code> subelement, which
4462         is used to set the controller's "port" configuration value,
4463         which is visible to the virtual machine. If set, port must be
4464         between 0 and 255.
4465       </dd>
4466       <dt><code>busNr</code></dt>
4467       <dd>
4468         pci-expander-bus and pcie-expander-bus controllers can have an
4469         optional <code>busNr</code> attribute (1-254). This will be
4470         the bus number of the new bus; All bus numbers between that
4471         specified and 255 will be available only for assignment to
4472         PCI/PCIe controllers plugged into the hierarchy starting with
4473         this expander bus, and bus numbers less than the specified
4474         value will be available to the next lower expander-bus (or the
4475         root-bus if there are no lower expander buses). If you do not
4476         specify a busNumber, libvirt will find the lowest existing
4477         busNumber in all other expander buses (or use 256 if there are
4478         no others) and auto-assign the busNr of that found bus - 2,
4479         which provides one bus number for the pci-expander-bus and one
4480         for the pci-bridge that is automatically attached to it (if
4481         you plan on adding more pci-bridges to the hierarchy of the
4482         bus, you should manually set busNr to a lower value).
4483         <p>
4484           A similar algorithm is used for automatically determining
4485           the busNr attribute for pcie-expander-bus, but since the
4486           pcie-expander-bus doesn't have any built-in pci-bridge, the
4487           2nd bus-number is just being reserved for the pcie-root-port
4488           that must necessarily be connected to the bus in order to
4489           actually plug in an endpoint device. If you intend to plug
4490           multiple devices into a pcie-expander-bus, you must connect
4491           a pcie-switch-upstream-port to the pcie-root-port that is
4492           plugged into the pcie-expander-bus, and multiple
4493           pcie-switch-downstream-ports to the
4494           pcie-switch-upstream-port, and of course for this to work
4495           properly, you will need to decrease the pcie-expander-bus'
4496           busNr accordingly so that there are enough unused bus
4497           numbers above it to accommodate giving out one bus number for
4498           the upstream-port and one for each downstream-port (in
4499           addition to the pcie-root-port and the pcie-expander-bus
4500           itself).
4501         </p>
4502       </dd>
4503       <dt><code>node</code></dt>
4504       <dd>
4505         Some PCI controllers (<code>pci-expander-bus</code> for the pc
4506         machine type, <code>pcie-expander-bus</code> for the q35 machine
4507         type and, <span class="since">since 3.6.0</span>,
4508         <code>pci-root</code> for the pseries machine type) can have an
4509         optional <code>&lt;node&gt;</code> subelement within
4510         the <code>&lt;target&gt;</code> subelement, which is used to
4511         set the NUMA node reported to the guest OS for that bus - the
4512         guest OS will then know that all devices on that bus are a
4513         part of the specified NUMA node (it is up to the user of the
4514         libvirt API to attach host devices to the correct
4515         pci-expander-bus when assigning them to the domain).
4516       </dd>
4517       <dt><code>index</code></dt>
4518       <dd>
4519         pci-root controllers for pSeries guests use this attribute to
4520         record the order they will show up in the guest.
4521         <span class="since">Since 3.6.0</span>
4522       </dd>
4523     </dl>
4524     <p>
4525       For machine types which provide an implicit PCI bus, the pci-root
4526       controller with index=0 is auto-added and required to use PCI devices.
4527       pci-root has no address.
4528       PCI bridges are auto-added if there are too many devices to fit on
4529       the one bus provided by pci-root, or a PCI bus number greater than zero
4530       was specified.
4531       PCI bridges can also be specified manually, but their addresses should
4532       only refer to PCI buses provided by already specified PCI controllers.
4533       Leaving gaps in the PCI controller indexes might lead to an invalid
4534       configuration.
4535     </p>
4536 <pre>
4537 ...
4538 &lt;devices&gt;
4539   &lt;controller type='pci' index='0' model='pci-root'/&gt;
4540   &lt;controller type='pci' index='1' model='pci-bridge'&gt;
4541     &lt;address type='pci' domain='0' bus='0' slot='5' function='0' multifunction='off'/&gt;
4542   &lt;/controller&gt;
4543 &lt;/devices&gt;
4544 ...</pre>
4545
4546     <p>
4547       For machine types which provide an implicit PCI Express (PCIe)
4548       bus (for example, the machine types based on the Q35 chipset),
4549       the pcie-root controller with index=0 is auto-added to the
4550       domain's configuration. pcie-root has also no address, provides
4551       31 slots (numbered 1-31) that can be used to attach PCIe or PCI
4552       devices (although libvirt will never auto-assign a PCI device to
4553       a PCIe slot, it will allow manual specification of such an
4554       assignment). Devices connected to pcie-root cannot be
4555       hotplugged. If traditional PCI devices are present in the guest
4556       configuration, a <code>pcie-to-pci-bridge</code> controller will
4557       automatically be added: this controller, which plugs into a
4558       <code>pcie-root-port</code>, provides 31 usable PCI slots (1-31) with
4559       hotplug support (<span class="since">since 4.3.0</span>). If the QEMU
4560       binary doesn't support the corresponding device, then a
4561       <code>dmi-to-pci-bridge</code> controller will be added instead,
4562       usually at the defacto standard location of slot=0x1e. A
4563       dmi-to-pci-bridge controller plugs into a PCIe slot (as provided
4564       by pcie-root), and itself provides 31 standard PCI slots (which
4565       also do not support device hotplug). In order to have
4566       hot-pluggable PCI slots in the guest system, a pci-bridge
4567       controller will also be automatically created and connected to
4568       one of the slots of the auto-created dmi-to-pci-bridge
4569       controller; all guest PCI devices with addresses that are
4570       auto-determined by libvirt will be placed on this pci-bridge
4571       device.  (<span class="since">since 1.1.2</span>).
4572     </p>
4573     <p>
4574       Domains with an implicit pcie-root can also add controllers
4575       with <code>model='pcie-root-port'</code>,
4576       <code>model='pcie-switch-upstream-port'</code>,
4577       and <code>model='pcie-switch-downstream-port'</code>. pcie-root-port
4578       is a simple type of bridge device that can connect only to one
4579       of the 31 slots on the pcie-root bus on its upstream side, and
4580       makes a single (PCIe, hotpluggable) port available on the
4581       downstream side (at slot='0'). pcie-root-port can be used to
4582       provide a single slot to later hotplug a PCIe device (but is not
4583       itself hotpluggable - it must be in the configuration when the
4584       domain is started).
4585       (<span class="since">since 1.2.19</span>)
4586     </p>
4587     <p>
4588       pcie-switch-upstream-port is a more flexible (but also more
4589       complex) device that can only plug into a pcie-root-port or
4590       pcie-switch-downstream-port on the upstream side (and only
4591       before the domain is started - it is not hot-pluggable), and
4592       provides 32 ports on the downstream side (slot='0' - slot='31')
4593       that accept only pcie-switch-downstream-port devices; each
4594       pcie-switch-downstream-port device can only plug into a
4595       pcie-switch-upstream-port on its upstream side (again, not
4596       hot-pluggable), and on its downstream side provides a single
4597       hotpluggable pcie port that can accept any standard pci or pcie
4598       device (or another pcie-switch-upstream-port), i.e. identical in
4599       function to a pcie-root-port.  (<span class="since">since
4600       1.2.19</span>)
4601     </p>
4602 <pre>
4603 ...
4604 &lt;devices&gt;
4605   &lt;controller type='pci' index='0' model='pcie-root'/&gt;
4606   &lt;controller type='pci' index='1' model='pcie-root-port'&gt;
4607     &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/&gt;
4608   &lt;/controller&gt;
4609   &lt;controller type='pci' index='2' model='pcie-to-pci-bridge'&gt;
4610     &lt;address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/&gt;
4611   &lt;/controller&gt;
4612 &lt;/devices&gt;
4613 ...</pre>
4614
4615     <h4><a id="elementsLease">Device leases</a></h4>
4616
4617     <p>
4618       When using a lock manager, it may be desirable to record device leases
4619       against a VM. The lock manager will ensure the VM won't start unless
4620       the leases can be acquired.
4621     </p>
4622
4623 <pre>
4624 ...
4625 &lt;devices&gt;
4626   ...
4627   &lt;lease&gt;
4628     &lt;lockspace&gt;somearea&lt;/lockspace&gt;
4629     &lt;key&gt;somekey&lt;/key&gt;
4630     &lt;target path='/some/lease/path' offset='1024'/&gt;
4631   &lt;/lease&gt;
4632   ...
4633 &lt;/devices&gt;
4634 ...</pre>
4635
4636     <dl>
4637       <dt><code>lockspace</code></dt>
4638       <dd>This is an arbitrary string, identifying the lockspace
4639         within which the key is held. Lock managers may impose
4640         extra restrictions on the format, or length of the lockspace
4641         name.</dd>
4642       <dt><code>key</code></dt>
4643       <dd>This is an arbitrary string, uniquely identifying the
4644         lease to be acquired. Lock managers may impose extra
4645         restrictions on the format, or length of the key.
4646       </dd>
4647       <dt><code>target</code></dt>
4648       <dd>This is the fully qualified path of the file associated
4649         with the lockspace. The offset specifies where the lease
4650         is stored within the file. If the lock manager does not
4651         require an offset, just pass 0.
4652       </dd>
4653     </dl>
4654
4655     <h4><a id="elementsHostDev">Host device assignment</a></h4>
4656
4657     <h5><a id="elementsHostDevSubsys">USB / PCI / SCSI devices</a></h5>
4658
4659     <p>
4660       USB, PCI and SCSI devices attached to the host can be passed through
4661       to the guest using the <code>hostdev</code> element.
4662       <span class="since">since after 0.4.4 for USB, 0.6.0 for PCI (KVM only)
4663         and 1.0.6 for SCSI (KVM only)</span>:
4664     </p>
4665
4666 <pre>
4667 ...
4668 &lt;devices&gt;
4669   &lt;hostdev mode='subsystem' type='usb'&gt;
4670     &lt;source startupPolicy='optional'&gt;
4671       &lt;vendor id='0x1234'/&gt;
4672       &lt;product id='0xbeef'/&gt;
4673     &lt;/source&gt;
4674     &lt;boot order='2'/&gt;
4675   &lt;/hostdev&gt;
4676 &lt;/devices&gt;
4677 ...</pre>
4678
4679     <p>or:</p>
4680
4681 <pre>
4682 ...
4683 &lt;devices&gt;
4684   &lt;hostdev mode='subsystem' type='pci' managed='yes'&gt;
4685     &lt;source&gt;
4686       &lt;address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/&gt;
4687     &lt;/source&gt;
4688     &lt;boot order='1'/&gt;
4689     &lt;rom bar='on' file='/etc/fake/boot.bin'/&gt;
4690   &lt;/hostdev&gt;
4691 &lt;/devices&gt;
4692 ...</pre>
4693
4694     <p>or:</p>
4695
4696 <pre>
4697 ...
4698 &lt;devices&gt;
4699   &lt;hostdev mode='subsystem' type='scsi' sgio='filtered' rawio='yes'&gt;
4700     &lt;source&gt;
4701       &lt;adapter name='scsi_host0'/&gt;
4702       &lt;address bus='0' target='0' unit='0'/&gt;
4703     &lt;/source&gt;
4704     &lt;readonly/&gt;
4705     &lt;address type='drive' controller='0' bus='0' target='0' unit='0'/&gt;
4706   &lt;/hostdev&gt;
4707 &lt;/devices&gt;
4708 ...</pre>
4709
4710
4711     <p>or:</p>
4712
4713 <pre>
4714 ...
4715 &lt;devices&gt;
4716   &lt;hostdev mode='subsystem' type='scsi'&gt;
4717     &lt;source protocol='iscsi' name='iqn.2014-08.com.example:iscsi-nopool/1'&gt;
4718       &lt;host name='example.com' port='3260'/&gt;
4719       &lt;auth username='myuser'&gt;
4720         &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
4721       &lt;/auth&gt;
4722     &lt;/source&gt;
4723     &lt;address type='drive' controller='0' bus='0' target='0' unit='0'/&gt;
4724   &lt;/hostdev&gt;
4725 &lt;/devices&gt;
4726 ...</pre>
4727
4728     <p>or:</p>
4729
4730 <pre>
4731   ...
4732   &lt;devices&gt;
4733     &lt;hostdev mode='subsystem' type='scsi_host'&gt;
4734       &lt;source protocol='vhost' wwpn='naa.50014057667280d8'/&gt;
4735     &lt;/hostdev&gt;
4736   &lt;/devices&gt;
4737   ...</pre>
4738
4739     <p>or:</p>
4740
4741 <pre>
4742   ...
4743   &lt;devices&gt;
4744     &lt;hostdev mode='subsystem' type='mdev' model='vfio-pci'&gt;
4745     &lt;source&gt;
4746       &lt;address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'/&gt;
4747     &lt;/source&gt;
4748     &lt;/hostdev&gt;
4749     &lt;hostdev mode='subsystem' type='mdev' model='vfio-ccw'&gt;
4750     &lt;source&gt;
4751       &lt;address uuid='9063cba3-ecef-47b6-abcf-3fef4fdcad85'/&gt;
4752     &lt;/source&gt;
4753     &lt;address type='ccw' cssid='0xfe' ssid='0x0' devno='0x0001'/&gt;
4754     &lt;/hostdev&gt;
4755   &lt;/devices&gt;
4756   ...</pre>
4757
4758     <dl>
4759       <dt><code>hostdev</code></dt>
4760       <dd>The <code>hostdev</code> element is the main container for describing
4761         host devices. For each device, the <code>mode</code> is always
4762         "subsystem" and the <code>type</code> is one of the following values
4763         with additional attributes noted.
4764         <dl>
4765           <dt><code>usb</code></dt>
4766           <dd>USB devices are detached from the host on guest startup
4767             and reattached after the guest exits or the device is
4768             hot-unplugged.
4769           </dd>
4770           <dt><code>pci</code></dt>
4771           <dd>For PCI devices, when <code>managed</code> is "yes" it is
4772             detached from the host before being passed on to the guest
4773             and reattached to the host after the guest exits. If
4774             <code>managed</code> is omitted or "no", the user is
4775             responsible to call <code>virNodeDeviceDetachFlags</code>
4776             (or <code>virsh nodedev-detach</code> before starting the guest
4777             or hot-plugging the device and <code>virNodeDeviceReAttach</code>
4778             (or <code>virsh nodedev-reattach</code>) after hot-unplug or
4779             stopping the guest.
4780           </dd>
4781           <dt><code>scsi</code></dt>
4782           <dd>For SCSI devices, user is responsible to make sure the device
4783             is not used by host. If supported by the hypervisor and OS, the
4784             optional <code>sgio</code> (<span class="since">since 1.0.6</span>)
4785             attribute indicates whether unprivileged SG_IO commands are
4786             filtered for the disk. Valid settings are "filtered" or
4787             "unfiltered", where the default is "filtered".
4788             The optional <code>rawio</code>
4789             (<span class="since">since 1.2.9</span>) attribute indicates
4790             whether the lun needs the rawio capability. Valid settings are
4791             "yes" or "no". See the rawio description within the
4792             <a href="#elementsDisks">disk</a> section.
4793             If a disk lun in the domain already has the rawio capability,
4794             then this setting not required.
4795           </dd>
4796           <dt><code>scsi_host</code></dt>
4797           <dd><span class="since">since 2.5.0</span>For SCSI devices, user
4798             is responsible to make sure the device is not used by host. This
4799             <code>type</code> passes all LUNs presented by a single HBA to
4800             the guest. <span class="since">Since 5.2.0,</span> the
4801             <code>model</code> attribute can be specified further
4802             with "virtio-transitional", "virtio-non-transitional", or
4803             "virtio". See
4804             <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
4805             for more details.
4806           </dd>
4807           <dt><code>mdev</code></dt>
4808           <dd>For mediated devices (<span class="since">Since 3.2.0</span>)
4809           the <code>model</code> attribute specifies the device API which
4810           determines how the host's vfio driver will expose the device to the
4811           guest. Currently, <code>model='vfio-pci'</code>,
4812           <code>model='vfio-ccw'</code> (<span class="since">Since 4.4.0</span>)
4813           and <code>model='vfio-ap'</code> (<span class="since">Since 4.9.0</span>)
4814           is supported. <a href="drvnodedev.html#MDEV">MDEV</a> section
4815           provides more information about mediated devices as well as how to
4816           create mediated devices on the host.
4817           <span class="since">Since 4.6.0 (QEMU 2.12)</span> an optional
4818           <code>display</code> attribute may be used to enable or disable
4819           support for an accelerated remote desktop backed by a mediated
4820           device (such as NVIDIA vGPU or Intel GVT-g) as an alternative to
4821           emulated <a href="#elementsVideo">video devices</a>. This attribute
4822           is limited to <code>model='vfio-pci'</code> only. Supported values
4823           are either <code>on</code> or <code>off</code> (default is 'off').
4824           It is required to use a
4825           <a href="#elementsGraphics">graphical framebuffer</a> in order to
4826           use this attribute, currently only supported with VNC, Spice and
4827           egl-headless graphics devices.
4828           <p>
4829             Note: There are also some implications on the usage of guest's
4830             address type depending on the <code>model</code> attribute,
4831             see the <code>address</code> element below.
4832           </p>
4833           </dd>
4834         </dl>
4835         <p>
4836           Note: The <code>managed</code> attribute is only used with
4837           <code>type='pci'</code> and is ignored by all the other device types,
4838           thus setting <code>managed</code> explicitly with other than a PCI
4839           device has the same effect as omitting it. Similarly,
4840           <code>model</code> attribute is only supported by mediated devices and
4841           ignored by all other device types.
4842         </p>
4843       </dd>
4844       <dt><code>source</code></dt>
4845       <dd>The source element describes the device as seen from the host using
4846         the following mechanism to describe:
4847         <dl>
4848           <dt><code>usb</code></dt>
4849           <dd>The USB device can either be addressed by vendor / product id
4850             using the <code>vendor</code> and <code>product</code> elements
4851             or by the device's address on the host using the
4852             <code>address</code> element.
4853             <p>
4854             <span class="since">Since 1.0.0</span>, the <code>source</code>
4855             element of USB devices may contain <code>startupPolicy</code>
4856             attribute which can be used to define policy what to do if the
4857             specified host USB device is not found. The attribute accepts
4858             the following values:
4859             </p>
4860             <table class="top_table">
4861               <tr>
4862                 <td> mandatory </td>
4863                 <td> fail if missing for any reason (the default) </td>
4864               </tr>
4865               <tr>
4866                 <td> requisite </td>
4867                 <td> fail if missing on boot up,
4868                      drop if missing on migrate/restore/revert </td>
4869               </tr>
4870               <tr>
4871                 <td> optional </td>
4872                 <td> drop if missing at any start attempt </td>
4873               </tr>
4874             </table>
4875           </dd>
4876           <dt><code>pci</code></dt>
4877           <dd>PCI devices can only be described by their <code>address</code>.
4878           </dd>
4879           <dt><code>scsi</code></dt>
4880           <dd>SCSI devices are described by both the <code>adapter</code>
4881             and <code>address</code> elements. The <code>address</code>
4882             element includes a <code>bus</code> attribute (a 2-digit bus
4883             number), a <code>target</code> attribute (a 10-digit target
4884             number), and a <code>unit</code> attribute (a 20-digit unit
4885             number on the bus). Not all hypervisors support larger
4886             <code>target</code> and <code>unit</code> values. It is up
4887             to each hypervisor to determine the maximum value supported
4888             for the adapter.
4889             <p>
4890             <span class="since">Since 1.2.8</span>, the <code>source</code>
4891             element of a SCSI device may contain the <code>protocol</code>
4892             attribute. When the attribute is set to "iscsi", the host
4893             device XML follows the network <a href="#elementsDisks">disk</a>
4894             device using the same <code>name</code> attribute and optionally
4895             using the <code>auth</code> element to provide the authentication
4896             credentials to the iSCSI server.
4897             </p>
4898           </dd>
4899           <dt><code>scsi_host</code></dt>
4900           <dd><span class="since">Since 2.5.0</span>, multiple LUNs behind a
4901             single SCSI HBA are described by a <code>protocol</code>
4902             attribute set to "vhost" and a <code>wwpn</code> attribute that
4903             is the vhost_scsi wwpn (16 hexadecimal digits with a prefix of
4904             "naa.") established in the host configfs.
4905           </dd>
4906           <dt><code>mdev</code></dt>
4907           <dd>Mediated devices (<span class="since">Since 3.2.0</span>) are
4908             described by the <code>address</code> element. The
4909             <code>address</code> element contains a single mandatory attribute
4910             <code>uuid</code>.
4911           </dd>
4912         </dl>
4913       </dd>
4914       <dt><code>vendor</code>, <code>product</code></dt>
4915       <dd>The <code>vendor</code> and <code>product</code> elements each have an
4916       <code>id</code> attribute that specifies the USB vendor and product id.
4917       The ids can be given in decimal, hexadecimal (starting with 0x) or
4918       octal (starting with 0) form.</dd>
4919       <dt><code>boot</code></dt>
4920       <dd>Specifies that the device is bootable. The <code>order</code>
4921       attribute determines the order in which devices will be tried during
4922       boot sequence. The per-device <code>boot</code> elements cannot be
4923       used together with general boot elements in
4924       <a href="#elementsOSBIOS">BIOS bootloader</a> section.
4925       <span class="since">Since 0.8.8</span> for PCI devices,
4926       <span class="since">Since 1.0.1</span> for USB devices.
4927       </dd>
4928       <dt><code>rom</code></dt>
4929       <dd>The <code>rom</code> element is used to change how a PCI
4930         device's ROM is presented to the guest. The optional <code>bar</code>
4931         attribute can be set to "on" or "off", and determines whether
4932         or not the device's ROM will be visible in the guest's memory
4933         map. (In PCI documentation, the "rombar" setting controls the
4934         presence of the Base Address Register for the ROM). If no rom
4935         bar is specified, the qemu default will be used (older
4936         versions of qemu used a default of "off", while newer qemus
4937         have a default of "on"). <span class="since">Since
4938         0.9.7 (QEMU and KVM only)</span>. The optional
4939         <code>file</code> attribute contains an absolute path to a binary file
4940         to be presented to the guest as the device's ROM BIOS. This
4941         can be useful, for example, to provide a PXE boot ROM for a
4942         virtual function of an sr-iov capable ethernet device (which
4943         has no boot ROMs for the VFs).
4944         <span class="since">Since 0.9.10 (QEMU and KVM only)</span>.
4945         The optional <code>enabled</code> attribute can be set to
4946         <code>no</code> to disable PCI ROM loading completely for the device;
4947         if PCI ROM loading is disabled through this attribute, attempts to
4948         tweak the loading process further using the <code>bar</code> or
4949         <code>file</code> attributes will be rejected.
4950         <span class="since">Since 4.3.0 (QEMU and KVM only)</span>.
4951       </dd>
4952       <dt><code>address</code></dt>
4953       <dd>The <code>address</code> element for USB devices has a
4954       <code>bus</code> and <code>device</code> attribute to specify the
4955       USB bus and device number the device appears at on the host.
4956       The values of these attributes can be given in decimal, hexadecimal
4957       (starting with 0x) or octal (starting with 0) form.
4958       For PCI devices the element carries 4 attributes allowing to designate
4959       the device as can be found with the <code>lspci</code> or
4960       with <code>virsh nodedev-list</code>. For SCSI devices a 'drive'
4961       address type must be used. For mediated devices, which are software-only
4962       devices defining an allocation of resources on the physical parent device,
4963       the address type used must conform to the <code>model</code> attribute
4964       of element <code>hostdev</code>, e.g. any address type other than PCI for
4965       <code>vfio-pci</code> device API or any address type other than CCW for
4966       <code>vfio-ccw</code> device API will result in an error.
4967       <a href="#elementsAddress">See above</a> for more details on the address
4968       element.</dd>
4969       <dt><code>driver</code></dt>
4970       <dd>
4971         PCI devices can have an optional <code>driver</code>
4972         subelement that specifies which backend driver to use for PCI
4973         device assignment. Use the <code>name</code> attribute to
4974         select either "vfio" (for the new VFIO device assignment
4975         backend, which is compatible with UEFI SecureBoot) or "kvm"
4976         (the legacy device assignment handled directly by the KVM
4977         kernel module)<span class="since">Since 1.0.5 (QEMU and KVM
4978         only, requires kernel 3.6 or newer)</span>. When specified,
4979         device assignment will fail if the requested method of device
4980         assignment isn't available on the host. When not specified,
4981         the default is "vfio" on systems where the VFIO driver is
4982         available and loaded, and "kvm" on older systems, or those
4983         where the VFIO driver hasn't been
4984         loaded <span class="since">Since 1.1.3</span> (prior to that
4985         the default was always "kvm").
4986       </dd>
4987       <dt><code>readonly</code></dt>
4988       <dd>Indicates that the device is readonly, only supported by SCSI host
4989         device now. <span class="since">Since 1.0.6 (QEMU and KVM only)</span>
4990       </dd>
4991       <dt><code>shareable</code></dt>
4992       <dd>If present, this indicates the device is expected to be shared
4993         between domains (assuming the hypervisor and OS support this).
4994         Only supported by SCSI host device.
4995         <span class="since">Since 1.0.6</span>
4996         <p>
4997           Note: Although <code>shareable</code> was introduced
4998           <span class="since">in 1.0.6</span>, it did not work as
4999           as expected until <span class="since">1.2.2</span>.
5000         </p>
5001       </dd>
5002     </dl>
5003
5004
5005     <h5><a id="elementsHostDevCaps">Block / character devices</a></h5>
5006
5007     <p>
5008       Block / character devices from the host can be passed through
5009       to the guest using the <code>hostdev</code> element. This is
5010       only possible with container based virtualization. Devices are specified
5011       by a fully qualified path.
5012       <span class="since">since after 1.0.1 for LXC</span>:
5013     </p>
5014
5015     <pre>
5016 ...
5017 &lt;hostdev mode='capabilities' type='storage'&gt;
5018   &lt;source&gt;
5019     &lt;block&gt;/dev/sdf1&lt;/block&gt;
5020   &lt;/source&gt;
5021 &lt;/hostdev&gt;
5022 ...
5023     </pre>
5024
5025     <pre>
5026 ...
5027 &lt;hostdev mode='capabilities' type='misc'&gt;
5028   &lt;source&gt;
5029     &lt;char&gt;/dev/input/event3&lt;/char&gt;
5030   &lt;/source&gt;
5031 &lt;/hostdev&gt;
5032 ...
5033     </pre>
5034
5035     <pre>
5036 ...
5037 &lt;hostdev mode='capabilities' type='net'&gt;
5038   &lt;source&gt;
5039     &lt;interface&gt;eth0&lt;/interface&gt;
5040   &lt;/source&gt;
5041 &lt;/hostdev&gt;
5042 ...
5043     </pre>
5044
5045     <dl>
5046       <dt><code>hostdev</code></dt>
5047       <dd>The <code>hostdev</code> element is the main container for describing
5048         host devices. For block/character device passthrough <code>mode</code> is
5049         always "capabilities" and <code>type</code> is "storage" for a block
5050         device, "misc" for a character device and "net" for a host network
5051         interface.
5052       </dd>
5053       <dt><code>source</code></dt>
5054       <dd>The source element describes the device as seen from the host.
5055         For block devices, the path to the block device in the host
5056         OS is provided in the nested "block" element, while for character
5057         devices the "char" element is used. For network interfaces, the
5058         name of the interface is provided in the "interface" element.
5059       </dd>
5060     </dl>
5061
5062     <h4><a id="elementsRedir">Redirected devices</a></h4>
5063
5064     <p>
5065       USB device redirection through a character device is
5066       supported <span class="since">since after 0.9.5 (KVM
5067       only)</span>:
5068     </p>
5069
5070 <pre>
5071 ...
5072 &lt;devices&gt;
5073   &lt;redirdev bus='usb' type='tcp'&gt;
5074     &lt;source mode='connect' host='localhost' service='4000'/&gt;
5075     &lt;boot order='1'/&gt;
5076   &lt;/redirdev&gt;
5077   &lt;redirfilter&gt;
5078     &lt;usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/&gt;
5079     &lt;usbdev allow='no'/&gt;
5080   &lt;/redirfilter&gt;
5081 &lt;/devices&gt;
5082 ...</pre>
5083
5084     <dl>
5085       <dt><code>redirdev</code></dt>
5086       <dd>The <code>redirdev</code> element is the main container for
5087         describing redirected devices. <code>bus</code> must be "usb"
5088         for a USB device.
5089
5090         An additional attribute <code>type</code> is required,
5091         matching one of the
5092         supported <a href="#elementsConsole">serial device</a> types,
5093         to describe the host side of the
5094         tunnel; <code>type='tcp'</code>
5095         or <code>type='spicevmc'</code> (which uses the usbredir
5096         channel of a <a href="#elementsGraphics">SPICE graphics
5097         device</a>) are typical. The redirdev element has an optional
5098         sub-element <code>&lt;address&gt;</code> which can tie the
5099         device to a particular controller. Further sub-elements,
5100         such as <code>&lt;source&gt;</code>, may be required according
5101         to the given type, although a <code>&lt;target&gt;</code> sub-element
5102         is not required (since the consumer of the character device is
5103         the hypervisor itself, rather than a device visible in the guest).
5104       </dd>
5105       <dt><code>boot</code></dt>
5106
5107       <dd>Specifies that the device is bootable.
5108         The <code>order</code> attribute determines the order in which
5109         devices will be tried during boot sequence. The per-device
5110         <code>boot</code> elements cannot be used together with general
5111         boot elements in  <a href="#elementsOSBIOS">BIOS bootloader</a> section.
5112         (<span class="since">Since 1.0.1</span>)
5113       </dd>
5114       <dt><code>redirfilter</code></dt>
5115       <dd>The<code> redirfilter </code>element is used for creating the
5116         filter rule to filter out certain devices from redirection.
5117         It uses sub-element <code>&lt;usbdev&gt;</code> to define each filter rule.
5118         <code>class</code> attribute is the USB Class code, for example,
5119         0x08 represents mass storage devices. The USB device can be addressed by
5120         vendor / product id using the <code>vendor</code> and <code>product</code> attributes.
5121         <code>version</code> is the device revision from the bcdDevice field (not
5122         the version of the USB protocol).
5123         These four attributes are optional and <code>-1</code> can be used to allow
5124         any value for them. <code>allow</code> attribute is mandatory,
5125         'yes' means allow, 'no' for deny.
5126       </dd>
5127     </dl>
5128
5129     <h4><a id="elementsSmartcard">Smartcard devices</a></h4>
5130
5131     <p>
5132       A virtual smartcard device can be supplied to the guest via the
5133       <code>smartcard</code> element. A USB smartcard reader device on
5134       the host cannot be used on a guest with simple device
5135       passthrough, since it will then not be available on the host,
5136       possibly locking the host computer when it is "removed".
5137       Therefore, some hypervisors provide a specialized virtual device
5138       that can present a smartcard interface to the guest, with
5139       several modes for describing how credentials are obtained from
5140       the host or even a from a channel created to a third-party
5141       smartcard provider. <span class="since">Since 0.8.8</span>
5142     </p>
5143
5144 <pre>
5145 ...
5146 &lt;devices&gt;
5147   &lt;smartcard mode='host'/&gt;
5148   &lt;smartcard mode='host-certificates'&gt;
5149     &lt;certificate&gt;cert1&lt;/certificate&gt;
5150     &lt;certificate&gt;cert2&lt;/certificate&gt;
5151     &lt;certificate&gt;cert3&lt;/certificate&gt;
5152     &lt;database&gt;/etc/pki/nssdb/&lt;/database&gt;
5153   &lt;/smartcard&gt;
5154   &lt;smartcard mode='passthrough' type='tcp'&gt;
5155     &lt;source mode='bind' host='127.0.0.1' service='2001'/&gt;
5156     &lt;protocol type='raw'/&gt;
5157     &lt;address type='ccid' controller='0' slot='0'/&gt;
5158   &lt;/smartcard&gt;
5159   &lt;smartcard mode='passthrough' type='spicevmc'/&gt;
5160 &lt;/devices&gt;
5161 ...
5162 </pre>
5163
5164     <p>
5165       The <code>&lt;smartcard&gt;</code> element has a mandatory
5166       attribute <code>mode</code>.  The following modes are supported;
5167       in each mode, the guest sees a device on its USB bus that
5168       behaves like a physical USB CCID (Chip/Smart Card Interface
5169       Device) card.
5170     </p>
5171
5172     <dl>
5173       <dt><code>host</code></dt>
5174       <dd>The simplest operation, where the hypervisor relays all
5175       requests from the guest into direct access to the host's
5176       smartcard via NSS.  No other attributes or sub-elements are
5177       required.  See below about the use of an
5178       optional <code>&lt;address&gt;</code> sub-element.</dd>
5179
5180       <dt><code>host-certificates</code></dt>
5181       <dd>Rather than requiring a smartcard to be plugged into the
5182       host, it is possible to provide three NSS certificate names
5183       residing in a database on the host.  These certificates can be
5184       generated via the command <code>certutil -d /etc/pki/nssdb -x -t
5185       CT,CT,CT -S -s CN=cert1 -n cert1</code>, and the resulting three
5186       certificate names must be supplied as the content of each of
5187       three <code>&lt;certificate&gt;</code> sub-elements.  An
5188       additional sub-element <code>&lt;database&gt;</code> can specify
5189       the absolute path to an alternate directory (matching
5190       the <code>-d</code> option of the <code>certutil</code> command
5191       when creating the certificates); if not present, it defaults to
5192       /etc/pki/nssdb.</dd>
5193
5194       <dt><code>passthrough</code></dt>
5195       <dd>Rather than having the hypervisor directly communicate with
5196       the host, it is possible to tunnel all requests through a
5197       secondary character device to a third-party provider (which may
5198       in turn be talking to a smartcard or using three certificate
5199       files).  In this mode of operation, an additional
5200       attribute <code>type</code> is required, matching one of the
5201       supported <a href="#elementsConsole">serial device</a> types, to
5202       describe the host side of the tunnel; <code>type='tcp'</code>
5203       or <code>type='spicevmc'</code> (which uses the smartcard
5204       channel of a <a href="#elementsGraphics">SPICE graphics
5205       device</a>) are typical.  Further sub-elements, such
5206       as <code>&lt;source&gt;</code>, may be required according to the
5207       given type, although a <code>&lt;target&gt;</code> sub-element
5208       is not required (since the consumer of the character device is
5209       the hypervisor itself, rather than a device visible in the
5210       guest).</dd>
5211     </dl>
5212
5213     <p>
5214       Each mode supports an optional
5215       sub-element <code>&lt;address&gt;</code>, which fine-tunes the
5216       correlation between the smartcard and a ccid bus
5217       controller, <a href="#elementsAddress">documented above</a>.
5218       For now, qemu only supports at most one
5219       smartcard, with an address of bus=0 slot=0.
5220     </p>
5221
5222     <h4><a id="elementsNICS">Network interfaces</a></h4>
5223
5224 <pre>
5225 ...
5226 &lt;devices&gt;
5227   &lt;interface type='direct' trustGuestRxFilters='yes'&gt;
5228     &lt;source dev='eth0'/&gt;
5229     &lt;mac address='52:54:00:5d:c7:9e'/&gt;
5230     &lt;boot order='1'/&gt;
5231     &lt;rom bar='off'/&gt;
5232   &lt;/interface&gt;
5233 &lt;/devices&gt;
5234 ...</pre>
5235
5236     <p>
5237       There are several possibilities for specifying a network
5238       interface visible to the guest.  Each subsection below provides
5239       more details about common setup options.
5240     </p>
5241     <p>
5242       <span class="since">Since 1.2.10</span>),
5243       the <code>interface</code> element
5244       property <code>trustGuestRxFilters</code> provides the
5245       capability for the host to detect and trust reports from the
5246       guest regarding changes to the interface mac address and receive
5247       filters by setting the attribute to <code>yes</code>. The default
5248       setting for the attribute is <code>no</code> for security
5249       reasons and support depends on the guest network device model as
5250       well as the type of connection on the host - currently it is
5251       only supported for the virtio device model and for macvtap
5252       connections on the host.
5253     </p>
5254     <p>
5255       Each <code>&lt;interface&gt;</code> element has an
5256       optional <code>&lt;address&gt;</code> sub-element that can tie
5257       the interface to a particular pci slot, with
5258       attribute <code>type='pci'</code>
5259       as <a href="#elementsAddress">documented above</a>.
5260     </p>
5261
5262     <h5><a id="elementsNICSVirtual">Virtual network</a></h5>
5263
5264     <p>
5265       <strong><em>
5266       This is the recommended config for general guest connectivity on
5267       hosts with dynamic / wireless networking configs (or multi-host
5268       environments where the host hardware details are described
5269       separately in a <code>&lt;network&gt;</code>
5270       definition <span class="since">Since 0.9.4</span>).
5271       </em></strong>
5272     </p>
5273
5274     <p>
5275
5276       Provides a connection whose details are described by the named
5277       network definition. Depending on the virtual network's "forward
5278       mode" configuration, the network may be totally isolated
5279       (no <code>&lt;forward&gt;</code> element given), NAT'ing to an
5280       explicit network device or to the default route
5281       (<code>&lt;forward mode='nat'&gt;</code>), routed with no NAT
5282       (<code>&lt;forward mode='route'/&gt;</code>), or connected
5283       directly to one of the host's network interfaces (via macvtap)
5284       or bridge devices ((<code>&lt;forward
5285       mode='bridge|private|vepa|passthrough'/&gt;</code> <span class="since">Since
5286       0.9.4</span>)
5287     </p>
5288     <p>
5289       For networks with a forward mode of bridge, private, vepa, and
5290       passthrough, it is assumed that the host has any necessary DNS
5291       and DHCP services already setup outside the scope of libvirt. In
5292       the case of isolated, nat, and routed networks, DHCP and DNS are
5293       provided on the virtual network by libvirt, and the IP range can
5294       be determined by examining the virtual network config with
5295       '<code>virsh net-dumpxml [networkname]</code>'. There is one
5296       virtual network called 'default' setup out of the box which does
5297       NAT'ing to the default route and has an IP range
5298       of <code>192.168.122.0/255.255.255.0</code>. Each guest will
5299       have an associated tun device created with a name of vnetN,
5300       which can also be overridden with the &lt;target&gt; element
5301       (see
5302       <a href="#elementsNICSTargetOverride">overriding the target element</a>).
5303     </p>
5304     <p>
5305       When the source of an interface is a network,
5306       a <code>portgroup</code> can be specified along with the name of
5307       the network; one network may have multiple portgroups defined,
5308       with each portgroup containing slightly different configuration
5309       information for different classes of network
5310       connections. <span class="since">Since 0.9.4</span>.
5311     </p>
5312     <p>
5313       When a guest is running an interface of type <code>network</code>
5314       may include a <code>portid</code> attribute. This provides the UUID
5315       of an associated virNetworkPortPtr object that records the association
5316       between the domain interface and the network. This attribute is
5317       read-only since port objects are create and deleted automatically
5318       during startup and shutdown. <span class="since">Since 5.1.0</span>
5319     </p>
5320     <p>
5321       Also, similar to <code>direct</code> network connections
5322       (described below), a connection of type <code>network</code> may
5323       specify a <code>virtualport</code> element, with configuration
5324       data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant
5325       switch (<span class="since">Since 0.8.2</span>), or to an
5326       Open vSwitch virtual switch (<span class="since">Since
5327       0.9.11</span>).
5328     </p>
5329     <p>
5330       Since the actual type of switch may vary depending on the
5331       configuration in the <code>&lt;network&gt;</code> on the host,
5332       it is acceptable to omit the virtualport <code>type</code>
5333       attribute, and specify attributes from multiple different
5334       virtualport types (and also to leave out certain attributes); at
5335       domain startup time, a complete <code>&lt;virtualport&gt;</code>
5336       element will be constructed by merging together the type and
5337       attributes defined in the network and the portgroup referenced
5338       by the interface. The newly-constructed virtualport is a combination
5339       of them. The attributes from lower virtualport can't make change
5340       on the ones defined in higher virtualport.
5341       Interface takes the highest priority, portgroup is lowest priority.
5342       (<span class="since">Since 0.10.0</span>). For example, in order
5343       to work properly with both an 802.1Qbh switch and an Open vSwitch
5344       switch, you may choose to specify no type, but both
5345       a <code>profileid</code> (in case the switch is 802.1Qbh) and
5346       an <code>interfaceid</code> (in case the switch is Open vSwitch)
5347       (you may also omit the other attributes, such as managerid,
5348       typeid, or profileid, to be filled in from the
5349       network's <code>&lt;virtualport&gt;</code>). If you want to
5350       limit a guest to connecting only to certain types of switches,
5351       you can specify the virtualport type, but still omit some/all of
5352       the parameters - in this case if the host's network has a
5353       different type of virtualport, connection of the interface will
5354       fail.
5355     </p>
5356
5357 <pre>
5358 ...
5359 &lt;devices&gt;
5360   &lt;interface type='network'&gt;
5361     &lt;source network='default'/&gt;
5362   &lt;/interface&gt;
5363   ...
5364   &lt;interface type='network'&gt;
5365     &lt;source network='default' portgroup='engineering'/&gt;
5366     &lt;target dev='vnet7'/&gt;
5367     &lt;mac address="00:11:22:33:44:55"/&gt;
5368     &lt;virtualport&gt;
5369       &lt;parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&gt;
5370     &lt;/virtualport&gt;
5371   &lt;/interface&gt;
5372 &lt;/devices&gt;
5373 ...</pre>
5374
5375     <h5><a id="elementsNICSBridge">Bridge to LAN</a></h5>
5376
5377     <p>
5378       <strong><em>
5379       This is the recommended config for general guest connectivity on
5380       hosts with static wired networking configs.
5381       </em></strong>
5382     </p>
5383
5384     <p>
5385       Provides a bridge from the VM directly to the LAN. This assumes
5386       there is a bridge device on the host which has one or more of the hosts
5387       physical NICs enslaved. The guest VM will have an associated tun device
5388       created with a name of vnetN, which can also be overridden with the
5389       &lt;target&gt; element (see
5390       <a href="#elementsNICSTargetOverride">overriding the target element</a>).
5391       The tun device will be enslaved to the bridge. The IP range / network
5392       configuration is whatever is used on the LAN. This provides the guest VM
5393       full incoming &amp; outgoing net access just like a physical machine.
5394     </p>
5395     <p>
5396       On Linux systems, the bridge device is normally a standard Linux
5397       host bridge. On hosts that support Open vSwitch, it is also
5398       possible to connect to an Open vSwitch bridge device by adding
5399       a <code>&lt;virtualport type='openvswitch'/&gt;</code> to the
5400       interface definition.  (<span class="since">Since
5401       0.9.11</span>). The Open vSwitch type virtualport accepts two
5402       parameters in its <code>&lt;parameters&gt;</code> element -
5403       an <code>interfaceid</code> which is a standard uuid used to
5404       uniquely identify this particular interface to Open vSwitch (if
5405       you do not specify one, a random interfaceid will be generated
5406       for you when you first define the interface), and an
5407       optional <code>profileid</code> which is sent to Open vSwitch as
5408       the interfaces "port-profile".
5409     </p>
5410 <pre>
5411 ...
5412 &lt;devices&gt;
5413   ...
5414   &lt;interface type='bridge'&gt;
5415     &lt;source bridge='br0'/&gt;
5416   &lt;/interface&gt;
5417   &lt;interface type='bridge'&gt;
5418     &lt;source bridge='br1'/&gt;
5419     &lt;target dev='vnet7'/&gt;
5420     &lt;mac address="00:11:22:33:44:55"/&gt;
5421   &lt;/interface&gt;
5422   &lt;interface type='bridge'&gt;
5423     &lt;source bridge='ovsbr'/&gt;
5424     &lt;virtualport type='openvswitch'&gt;
5425       &lt;parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&gt;
5426     &lt;/virtualport&gt;
5427   &lt;/interface&gt;
5428   ...
5429 &lt;/devices&gt;
5430 ...</pre>
5431
5432     <p>
5433       On hosts that support Open vSwitch on the kernel side and have the
5434       Midonet Host Agent configured, it is also possible to connect to the
5435       'midonet' bridge device by adding a
5436       <code>&lt;virtualport type='midonet'/&gt;</code> to the
5437       interface definition.  (<span class="since">Since
5438       1.2.13</span>). The Midonet virtualport type requires an
5439       <code>interfaceid</code> attribute in its
5440       <code>&lt;parameters&gt;</code> element. This interface id is the UUID
5441       that specifies which port in the virtual network topology will be bound
5442       to the interface.
5443     </p>
5444 <pre>
5445 ...
5446 &lt;devices&gt;
5447   ...
5448   &lt;interface type='bridge'&gt;
5449     &lt;source bridge='br0'/&gt;
5450   &lt;/interface&gt;
5451   &lt;interface type='bridge'&gt;
5452     &lt;source bridge='br1'/&gt;
5453     &lt;target dev='vnet7'/&gt;
5454     &lt;mac address="00:11:22:33:44:55"/&gt;
5455   &lt;/interface&gt;
5456   &lt;interface type='bridge'&gt;
5457     &lt;source bridge='midonet'/&gt;
5458     &lt;virtualport type='midonet'&gt;
5459       &lt;parameters interfaceid='0b2d64da-3d0e-431e-afdd-804415d6ebbb'/&gt;
5460     &lt;/virtualport&gt;
5461   &lt;/interface&gt;
5462   ...
5463 &lt;/devices&gt;
5464 ...</pre>
5465
5466     <h5><a id="elementsNICSSlirp">Userspace SLIRP stack</a></h5>
5467
5468     <p>
5469       Provides a virtual LAN with NAT to the outside world. The virtual
5470       network has DHCP &amp; DNS services and will give the guest VM addresses
5471       starting from <code>10.0.2.15</code>. The default router will be
5472       <code>10.0.2.2</code> and the DNS server will be <code>10.0.2.3</code>.
5473       This networking is the only option for unprivileged users who need their
5474       VMs to have outgoing access. <span class="since">Since 3.8.0</span>
5475       it is possible to override the default network address by
5476       including an <code>ip</code> element specifying an IPv4
5477       address in its one mandatory attribute, <code>address</code>.
5478       Optionally, a second <code>ip</code> element with a
5479       <code>family</code> attribute set to "ipv6" can be
5480       specified to add an IPv6 address to the interface.
5481       <code>address</code>. Optionally, address
5482       <code>prefix</code> can be specified.
5483     </p>
5484
5485 <pre>
5486 ...
5487 &lt;devices&gt;
5488   &lt;interface type='user'/&gt;
5489   ...
5490   &lt;interface type='user'&gt;
5491     &lt;mac address="00:11:22:33:44:55"/&gt;
5492     &lt;ip family='ipv4' address='172.17.2.0' prefix='24'/&gt;
5493     &lt;ip family='ipv6' address='2001:db8:ac10:fd01::' prefix='64'/&gt;
5494   &lt;/interface&gt;
5495 &lt;/devices&gt;
5496 ...</pre>
5497
5498
5499     <h5><a id="elementsNICSEthernet">Generic ethernet connection</a></h5>
5500
5501     <p>
5502       Provides a means for the administrator to execute an arbitrary script
5503       to connect the guest's network to the LAN. The guest will have a tun
5504       device created with a name of vnetN, which can also be overridden with the
5505       &lt;target&gt; element. After creating the tun device a shell script will
5506       be run which is expected to do whatever host network integration is
5507       required. By default this script is called /etc/qemu-ifup but can be
5508       overridden.
5509     </p>
5510
5511 <pre>
5512 ...
5513 &lt;devices&gt;
5514   &lt;interface type='ethernet'/&gt;
5515   ...
5516   &lt;interface type='ethernet'&gt;
5517     &lt;target dev='vnet7'/&gt;
5518     &lt;script path='/etc/qemu-ifup-mynet'/&gt;
5519   &lt;/interface&gt;
5520 &lt;/devices&gt;
5521 ...</pre>
5522
5523     <h5><a id="elementsNICSDirect">Direct attachment to physical interface</a></h5>
5524
5525     <p>
5526       Provides direct attachment of the virtual machine's NIC to the given
5527       physical interface of the host.
5528       <span class="since">Since 0.7.7 (QEMU and KVM only)</span><br/>
5529       This setup requires the Linux macvtap
5530       driver to be available. <span class="since">(Since Linux 2.6.34.)</span>
5531       One of the modes 'vepa'
5532       ( <a href="http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf">
5533       'Virtual Ethernet Port Aggregator'</a>), 'bridge' or 'private'
5534       can be chosen for the operation mode of the macvtap device, 'vepa'
5535       being the default mode. The individual modes cause the delivery of
5536       packets to behave as follows:
5537     </p>
5538     <p>
5539       If the model type is set to <code>virtio</code> and
5540       interface's <code>trustGuestRxFilters</code> attribute is set
5541       to <code>yes</code>, changes made to the interface mac address,
5542       unicast/multicast receive filters, and vlan settings in the
5543       guest will be monitored and propagated to the associated macvtap
5544       device on the host (<span class="since">Since
5545       1.2.10</span>). If <code>trustGuestRxFilters</code> is not set,
5546       or is not supported for the device model in use, an attempted
5547       change to the mac address originating from the guest side will
5548       result in a non-working network connection.
5549     </p>
5550
5551     <dl>
5552       <dt><code>vepa</code></dt>
5553       <dd>All VMs' packets are sent to the external bridge. Packets
5554       whose destination is a VM on the same host as where the
5555       packet originates from are sent back to the host by the VEPA
5556       capable bridge (today's bridges are typically not VEPA capable).</dd>
5557       <dt><code>bridge</code></dt>
5558       <dd>Packets whose destination is on the same host as where they
5559       originate from are directly delivered to the target macvtap device.
5560       Both origin and destination devices need to be in bridge mode
5561       for direct delivery. If either one of them is in <code>vepa</code> mode,
5562       a VEPA capable bridge is required.</dd>
5563       <dt><code>private</code></dt>
5564       <dd>All packets are sent to the external bridge and will only be
5565       delivered to a target VM on the same host if they are sent through an
5566       external router or gateway and that device sends them back to the
5567       host. This procedure is followed if either the source or destination
5568       device is in <code>private</code> mode.</dd>
5569       <dt><code>passthrough</code></dt>
5570       <dd>This feature attaches a virtual function of a SRIOV capable
5571       NIC directly to a VM without losing the migration capability.
5572       All packets are sent to the VF/IF of the configured network device.
5573       Depending on the capabilities of the device additional prerequisites or
5574       limitations may apply; for example, on Linux this requires
5575       kernel 2.6.38 or newer. <span class="since">Since 0.9.2</span></dd>
5576     </dl>
5577
5578 <pre>
5579 ...
5580 &lt;devices&gt;
5581   ...
5582   &lt;interface type='direct' trustGuestRxFilters='no'&gt;
5583     &lt;source dev='eth0' mode='vepa'/&gt;
5584   &lt;/interface&gt;
5585 &lt;/devices&gt;
5586 ...</pre>
5587
5588     <p>
5589       The network access of direct attached virtual machines can be
5590       managed by the hardware switch to which the physical interface
5591       of the host machine is connected to.
5592     </p>
5593     <p>
5594       The interface can have additional parameters as shown below,
5595       if the switch is conforming to the IEEE 802.1Qbg standard.
5596       The parameters of the virtualport element are documented in more detail
5597       in the IEEE 802.1Qbg standard. The values are network specific and
5598       should be provided by the network administrator. In 802.1Qbg terms,
5599       the Virtual Station Interface (VSI) represents the virtual interface
5600       of a virtual machine. <span class="since">Since 0.8.2</span>
5601     </p>
5602     <p>
5603       Please note that IEEE 802.1Qbg requires a non-zero value for the
5604       VLAN ID.
5605     </p>
5606     <dl>
5607       <dt><code>managerid</code></dt>
5608       <dd>The VSI Manager ID identifies the database containing the VSI type
5609         and instance definitions. This is an integer value and the
5610         value 0 is reserved.</dd>
5611       <dt><code>typeid</code></dt>
5612       <dd>The VSI Type ID identifies a VSI type characterizing the network
5613         access. VSI types are typically managed by network administrator.
5614         This is an integer value.
5615       </dd>
5616       <dt><code>typeidversion</code></dt>
5617       <dd>The VSI Type Version allows multiple versions of a VSI Type.
5618         This is an integer value.
5619       </dd>
5620       <dt><code>instanceid</code></dt>
5621       <dd>The VSI Instance ID Identifier is generated when a VSI instance
5622         (i.e. a virtual interface of a virtual machine) is created.
5623         This is a globally unique identifier.
5624       </dd>
5625     </dl>
5626 <pre>
5627 ...
5628 &lt;devices&gt;
5629   ...
5630   &lt;interface type='direct'&gt;
5631     &lt;source dev='eth0.2' mode='vepa'/&gt;
5632     &lt;virtualport type="802.1Qbg"&gt;
5633       &lt;parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/&gt;
5634     &lt;/virtualport&gt;
5635   &lt;/interface&gt;
5636 &lt;/devices&gt;
5637 ...</pre>
5638
5639     <p>
5640       The interface can have additional parameters as shown below
5641       if the switch is conforming to the IEEE 802.1Qbh standard.
5642       The values are network specific and should be provided by the
5643       network administrator. <span class="since">Since 0.8.2</span>
5644     </p>
5645     <dl>
5646       <dt><code>profileid</code></dt>
5647       <dd>The profile ID contains the name of the port profile that is to
5648         be applied to this interface.  This name is resolved by the port
5649         profile database into the network parameters from the port profile,
5650         and those network parameters will be applied to this interface.
5651       </dd>
5652     </dl>
5653   <pre>
5654 ...
5655 &lt;devices&gt;
5656   ...
5657   &lt;interface type='direct'&gt;
5658     &lt;source dev='eth0' mode='private'/&gt;
5659     &lt;virtualport type='802.1Qbh'&gt;
5660       &lt;parameters profileid='finance'/&gt;
5661     &lt;/virtualport&gt;
5662   &lt;/interface&gt;
5663 &lt;/devices&gt;
5664 ...
5665 </pre>
5666
5667
5668     <h5><a id="elementsNICSHostdev">PCI Passthrough</a></h5>
5669
5670     <p>
5671       A PCI network device (specified by the &lt;source&gt; element)
5672       is directly assigned to the guest using generic device
5673       passthrough, after first optionally setting the device's MAC
5674       address to the configured value, and associating the device with
5675       an 802.1Qbh capable switch using an optionally specified
5676       &lt;virtualport&gt; element (see the examples of virtualport
5677       given above for type='direct' network devices). Note that - due
5678       to limitations in standard single-port PCI ethernet card driver
5679       design - only SR-IOV (Single Root I/O Virtualization) virtual
5680       function (VF) devices can be assigned in this manner; to assign
5681       a standard single-port PCI or PCIe ethernet card to a guest, use
5682       the traditional &lt;hostdev&gt; device definition and
5683       <span class="since">Since 0.9.11</span>
5684     </p>
5685
5686     <p>
5687       To use VFIO device assignment rather than traditional/legacy KVM
5688       device assignment (VFIO is a new method of device assignment
5689       that is compatible with UEFI Secure Boot), a type='hostdev'
5690       interface can have an optional <code>driver</code> sub-element
5691       with a <code>name</code> attribute set to "vfio". To use legacy
5692       KVM device assignment you can set <code>name</code> to "kvm" (or
5693       simply omit the <code>&lt;driver&gt;</code> element, since "kvm"
5694       is currently the default).
5695       <span class="since">Since 1.0.5 (QEMU and KVM only, requires kernel 3.6 or newer)</span>
5696     </p>
5697
5698     <p>
5699       Note that this "intelligent passthrough" of network devices is
5700       very similar to the functionality of a standard &lt;hostdev&gt;
5701       device, the difference being that this method allows specifying
5702       a MAC address and &lt;virtualport&gt; for the passed-through
5703       device. If these capabilities are not required, if you have a
5704       standard single-port PCI, PCIe, or USB network card that doesn't
5705       support SR-IOV (and hence would anyway lose the configured MAC
5706       address during reset after being assigned to the guest domain),
5707       or if you are using a version of libvirt older than 0.9.11, you
5708       should use standard &lt;hostdev&gt; to assign the device to the
5709       guest instead of &lt;interface type='hostdev'/&gt;.
5710     </p>
5711
5712     <p>
5713       Similar to the functionality of a standard &lt;hostdev&gt; device,
5714       when <code>managed</code> is "yes", it is detached from the host
5715       before being passed on to the guest, and reattached to the host
5716       after the guest exits. If <code>managed</code> is omitted or "no",
5717       the user is responsible to call <code>virNodeDeviceDettach</code>
5718       (or <code>virsh nodedev-detach</code>) before starting the guest
5719       or hot-plugging the device, and <code>virNodeDeviceReAttach</code>
5720       (or <code>virsh nodedev-reattach</code>) after hot-unplug or
5721       stopping the guest.
5722     </p>
5723
5724 <pre>
5725 ...
5726 &lt;devices&gt;
5727   &lt;interface type='hostdev' managed='yes'&gt;
5728     &lt;driver name='vfio'/&gt;
5729     &lt;source&gt;
5730       &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/&gt;
5731     &lt;/source&gt;
5732     &lt;mac address='52:54:00:6d:90:02'/&gt;
5733     &lt;virtualport type='802.1Qbh'&gt;
5734       &lt;parameters profileid='finance'/&gt;
5735     &lt;/virtualport&gt;
5736   &lt;/interface&gt;
5737 &lt;/devices&gt;
5738 ...</pre>
5739
5740
5741     <h5><a id="elementsNICSMulticast">Multicast tunnel</a></h5>
5742
5743     <p>
5744       A multicast group is setup to represent a virtual network. Any VMs
5745       whose network devices are in the same multicast group can talk to each
5746       other even across hosts. This mode is also available to unprivileged
5747       users. There is no default DNS or DHCP support and no outgoing network
5748       access. To provide outgoing network access, one of the VMs should have a
5749       2nd NIC which is connected to one of the first 4 network types and do the
5750       appropriate routing. The multicast protocol is compatible with that used
5751       by user mode linux guests too. The source address used must be from the
5752       multicast address block.
5753     </p>
5754
5755 <pre>
5756 ...
5757 &lt;devices&gt;
5758   &lt;interface type='mcast'&gt;
5759     &lt;mac address='52:54:00:6d:90:01'/&gt;
5760     &lt;source address='230.0.0.1' port='5558'/&gt;
5761   &lt;/interface&gt;
5762 &lt;/devices&gt;
5763 ...</pre>
5764
5765     <h5><a id="elementsNICSTCP">TCP tunnel</a></h5>
5766
5767     <p>
5768       A TCP client/server architecture provides a virtual network. One VM
5769       provides the server end of the network, all other VMS are configured as
5770       clients. All network traffic is routed between the VMs via the server.
5771       This mode is also available to unprivileged users. There is no default
5772       DNS or DHCP support and no outgoing network access. To provide outgoing
5773       network access, one of the VMs should have a 2nd NIC which is connected
5774       to one of the first 4 network types and do the appropriate routing.</p>
5775
5776 <pre>
5777 ...
5778 &lt;devices&gt;
5779   &lt;interface type='server'&gt;
5780     &lt;mac address='52:54:00:22:c9:42'/&gt;
5781     &lt;source address='192.168.0.1' port='5558'/&gt;
5782   &lt;/interface&gt;
5783   ...
5784   &lt;interface type='client'&gt;
5785     &lt;mac address='52:54:00:8b:c9:51'/&gt;
5786     &lt;source address='192.168.0.1' port='5558'/&gt;
5787   &lt;/interface&gt;
5788 &lt;/devices&gt;
5789 ...</pre>
5790
5791     <h5><a id="elementsNICSUDP">UDP unicast tunnel</a></h5>
5792
5793     <p>
5794     A UDP unicast architecture provides a virtual network which enables
5795     connections between QEMU instances using QEMU's UDP infrastructure.
5796
5797     The xml "source" address is the endpoint address to which the UDP socket
5798     packets will be sent from the host running QEMU.
5799     The xml "local" address is the address of the interface from which the
5800     UDP socket packets will originate from the QEMU host.
5801     <span class="since">Since 1.2.20</span></p>
5802
5803 <pre>
5804 ...
5805 &lt;devices&gt;
5806   &lt;interface type='udp'&gt;
5807     &lt;mac address='52:54:00:22:c9:42'/&gt;
5808     &lt;source address='127.0.0.1' port='11115'&gt;
5809       &lt;local address='127.0.0.1' port='11116'/&gt;
5810     &lt;/source&gt;
5811   &lt;/interface&gt;
5812 &lt;/devices&gt;
5813 ...</pre>
5814
5815     <h5><a id="elementsNICSModel">Setting the NIC model</a></h5>
5816
5817 <pre>
5818 ...
5819 &lt;devices&gt;
5820   &lt;interface type='network'&gt;
5821     &lt;source network='default'/&gt;
5822     &lt;target dev='vnet1'/&gt;
5823     <b>&lt;model type='ne2k_pci'/&gt;</b>
5824   &lt;/interface&gt;
5825 &lt;/devices&gt;
5826 ...</pre>
5827
5828     <p>
5829       For hypervisors which support this, you can set the model of
5830       emulated network interface card.
5831     </p>
5832
5833     <p>
5834       The values for <code>type</code> aren't defined specifically by
5835       libvirt, but by what the underlying hypervisor supports (if
5836       any).  For QEMU and KVM you can get a list of supported models
5837       with these commands:
5838     </p>
5839
5840 <pre>
5841 qemu -net nic,model=? /dev/null
5842 qemu-kvm -net nic,model=? /dev/null
5843 </pre>
5844
5845     <p>
5846       Typical values for QEMU and KVM include:
5847       ne2k_isa i82551 i82557b i82559er ne2k_pci pcnet rtl8139 e1000 virtio.
5848       <span class="since">Since 5.2.0</span>, <code>virtio-transitional</code>
5849       and <code>virtio-non-transitional</code> values are supported.
5850       See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
5851       for more details.
5852     </p>
5853
5854     <h5><a id="elementsDriverBackendOptions">Setting NIC driver-specific options</a></h5>
5855
5856 <pre>
5857 ...
5858 &lt;devices&gt;
5859   &lt;interface type='network'&gt;
5860     &lt;source network='default'/&gt;
5861     &lt;target dev='vnet1'/&gt;
5862     &lt;model type='virtio'/&gt;
5863     <b>&lt;driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'&gt;
5864       &lt;host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/&gt;
5865       &lt;guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/&gt;
5866     &lt;/driver&gt;
5867     </b>&lt;/interface&gt;
5868 &lt;/devices&gt;
5869 ...</pre>
5870
5871     <p>
5872       Some NICs may have tunable driver-specific options. These are
5873       set as attributes of the <code>driver</code> sub-element of the
5874       interface definition. Currently the following attributes are
5875       available for the <code>"virtio"</code> NIC driver:
5876     </p>
5877
5878     <dl>
5879       <dt><code>name</code></dt>
5880       <dd>
5881         The optional <code>name</code> attribute forces which type of
5882         backend driver to use. The value can be either 'qemu' (a
5883         user-space backend) or 'vhost' (a kernel backend, which
5884         requires the vhost module to be provided by the kernel); an
5885         attempt to require the vhost driver without kernel support
5886         will be rejected.  If this attribute is not present, then the
5887         domain defaults to 'vhost' if present, but silently falls back
5888         to 'qemu' without error.
5889         <span class="since">Since 0.8.8 (QEMU and KVM only)</span>
5890       </dd>
5891       <dd>
5892         For interfaces of type='hostdev' (PCI passthrough devices)
5893         the <code>name</code> attribute can optionally be set to
5894         "vfio" or "kvm". "vfio" tells libvirt to use VFIO device
5895         assignment rather than traditional KVM device assignment (VFIO
5896         is a new method of device assignment that is compatible with
5897         UEFI Secure Boot), and "kvm" tells libvirt to use the legacy
5898         device assignment performed directly by the kvm kernel module
5899         (the default is currently "kvm", but is subject to change).
5900         <span class="since">Since 1.0.5 (QEMU and KVM only, requires
5901         kernel 3.6 or newer)</span>
5902       </dd>
5903       <dd>
5904         For interfaces of type='vhostuser', the <code>name</code>
5905         attribute is ignored. The backend driver used is always
5906         vhost-user.
5907       </dd>
5908
5909       <dt><code>txmode</code></dt>
5910       <dd>
5911         The <code>txmode</code> attribute specifies how to handle
5912         transmission of packets when the transmit buffer is full. The
5913         value can be either 'iothread' or 'timer'.
5914         <span class="since">Since 0.8.8 (QEMU and KVM only)</span><br/><br/>
5915
5916         If set to 'iothread', packet tx is all done in an iothread in
5917         the bottom half of the driver (this option translates into
5918         adding "tx=bh" to the qemu commandline -device virtio-net-pci
5919         option).<br/><br/>
5920
5921         If set to 'timer', tx work is done in qemu, and if there is
5922         more tx data than can be sent at the present time, a timer is
5923         set before qemu moves on to do other things; when the timer
5924         fires, another attempt is made to send more data.<br/><br/>
5925
5926         The resulting difference, according to the qemu developer who
5927         added the option is: "bh makes tx more asynchronous and reduces
5928         latency, but potentially causes more processor bandwidth
5929         contention since the CPU doing the tx isn't necessarily the
5930         CPU where the guest generated the packets."<br/><br/>
5931
5932         <b>In general you should leave this option alone, unless you
5933         are very certain you know what you are doing.</b>
5934       </dd>
5935       <dt><code>ioeventfd</code></dt>
5936       <dd>
5937         This optional attribute allows users to set
5938         <a href='https://patchwork.kernel.org/patch/43390/'>
5939         domain I/O asynchronous handling</a> for interface device.
5940         The default is left to the discretion of the hypervisor.
5941         Accepted values are "on" and "off". Enabling this allows
5942         qemu to execute VM while a separate thread handles I/O.
5943         Typically guests experiencing high system CPU utilization
5944         during I/O will benefit from this. On the other hand,
5945         on overloaded host it could increase guest I/O latency.
5946         <span class="since">Since 0.9.3 (QEMU and KVM only)</span><br/><br/>
5947
5948         <b>In general you should leave this option alone, unless you
5949         are very certain you know what you are doing.</b>
5950       </dd>
5951       <dt><code>event_idx</code></dt>
5952       <dd>
5953         The <code>event_idx</code> attribute controls some aspects of
5954         device event processing. The value can be either 'on' or 'off'
5955         - if it is on, it will reduce the number of interrupts and
5956         exits for the guest. The default is determined by QEMU;
5957         usually if the feature is supported, default is on. In case
5958         there is a situation where this behavior is suboptimal, this
5959         attribute provides a way to force the feature off.
5960         <span class="since">Since 0.9.5 (QEMU and KVM only)</span><br/><br/>
5961
5962         <b>In general you should leave this option alone, unless you
5963         are very certain you know what you are doing.</b>
5964       </dd>
5965       <dt><code>queues</code></dt>
5966       <dd>
5967         The optional <code>queues</code> attribute controls the number
5968         of queues to be used for either
5969         <a href="https://www.linux-kvm.org/page/Multiqueue"> Multiqueue
5970         virtio-net</a> or <a href="#elementVhostuser">vhost-user</a> network
5971         interfaces.  Use of multiple packet processing queues requires the
5972         interface having the <code>&lt;model type='virtio'/&gt;</code>
5973         element.  Each queue will potentially be handled by a different
5974         processor, resulting in much higher throughput.
5975         <span class="since">virtio-net since 1.0.6 (QEMU and KVM only)</span>
5976         <span class="since">vhost-user since 1.2.17 (QEMU and KVM only)</span>
5977       </dd>
5978       <dt><code>rx_queue_size</code></dt>
5979       <dd>
5980         The optional <code>rx_queue_size</code> attribute controls
5981         the size of virtio ring for each queue as described above.
5982         The default value is hypervisor dependent and may change
5983         across its releases. Moreover, some hypervisors may pose
5984         some restrictions on actual value. For instance, latest
5985         QEMU (as of 2016-09-01) requires value to be a power of two
5986         from [256, 1024] range.
5987         <span class="since">Since 2.3.0 (QEMU and KVM only)</span><br/><br/>
5988
5989         <b>In general you should leave this option alone, unless you
5990         are very certain you know what you are doing.</b>
5991       </dd>
5992       <dt><code>tx_queue_size</code></dt>
5993       <dd>
5994         The optional <code>tx_queue_size</code> attribute controls
5995         the size of virtio ring for each queue as described above.
5996         The default value is hypervisor dependent and may change
5997         across its releases. Moreover, some hypervisors may pose
5998         some restrictions on actual value. For instance, QEMU
5999         v2.9  requires value to be a power of two from [256, 1024]
6000         range. In addition to that, this may work only for a subset of
6001         interface types, e.g. aforementioned QEMU enables this option
6002         only for <code>vhostuser</code> type.
6003         <span class="since">Since 3.7.0 (QEMU and KVM only)</span><br/><br/>
6004
6005         <b>In general you should leave this option alone, unless you
6006         are very certain you know what you are doing.</b>
6007       </dd>
6008       <dt>virtio options</dt>
6009       <dd>
6010         For virtio interfaces,
6011         <a href="#elementsVirtio">Virtio-specific options</a> can also be
6012         set. (<span class="since">Since 3.5.0</span>)
6013       </dd>
6014     </dl>
6015     <p>
6016       Offloading options for the host and guest can be configured using
6017       the following sub-elements:
6018     </p>
6019     <dl>
6020       <dt><code>host</code></dt>
6021       <dd>
6022         The <code>csum</code>, <code>gso</code>, <code>tso4</code>,
6023         <code>tso6</code>, <code>ecn</code> and <code>ufo</code>
6024         attributes with possible values <code>on</code>
6025         and <code>off</code> can be used to turn off host offloading options.
6026         By default, the supported offloads are enabled by QEMU.
6027         <span class="since">Since 1.2.9 (QEMU only)</span>
6028         The <code>mrg_rxbuf</code> attribute can be used to control
6029         mergeable rx buffers on the host side. Possible values are
6030         <code>on</code> (default) and <code>off</code>.
6031         <span class="since">Since 1.2.13 (QEMU only)</span>
6032       </dd>
6033       <dt><code>guest</code></dt>
6034       <dd>
6035         The <code>csum</code>, <code>tso4</code>,
6036         <code>tso6</code>, <code>ecn</code> and <code>ufo</code>
6037         attributes with possible values <code>on</code>
6038         and <code>off</code> can be used to turn off guest offloading options.
6039         By default, the supported offloads are enabled by QEMU.
6040         <span class="since">Since 1.2.9 (QEMU only)</span>
6041       </dd>
6042     </dl>
6043
6044     <h5><a id="elementsBackendOptions">Setting network backend-specific options</a></h5>
6045
6046 <pre>
6047 ...
6048 &lt;devices&gt;
6049   &lt;interface type='network'&gt;
6050     &lt;source network='default'/&gt;
6051     &lt;target dev='vnet1'/&gt;
6052     &lt;model type='virtio'/&gt;
6053     <b>&lt;backend tap='/dev/net/tun' vhost='/dev/vhost-net'/&gt;</b>
6054     &lt;driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5'/&gt;
6055     <b>&lt;tune&gt;
6056       &lt;sndbuf&gt;1600&lt;/sndbuf&gt;
6057     &lt;/tune&gt;</b>
6058   &lt;/interface&gt;
6059 &lt;/devices&gt;
6060 ...</pre>
6061
6062     <p>
6063       For tuning the backend of the network, the <code>backend</code> element
6064       can be used. The <code>vhost</code> attribute can override the default vhost
6065       device path (<code>/dev/vhost-net</code>) for devices with <code>virtio</code> model.
6066       The <code>tap</code> attribute overrides the tun/tap device path (default:
6067       <code>/dev/net/tun</code>) for network and bridge interfaces. This does not work
6068       in session mode. <span class="since">Since 1.2.9</span>
6069     </p>
6070     <p>
6071       For tap devices there is also <code>sndbuf</code> element which can
6072       adjust the size of send buffer in the host. <span class="since">Since
6073       0.8.8</span>
6074     </p>
6075     <h5><a id="elementsNICSTargetOverride">Overriding the target element</a></h5>
6076
6077 <pre>
6078 ...
6079 &lt;devices&gt;
6080   &lt;interface type='network'&gt;
6081     &lt;source network='default'/&gt;
6082     <b>&lt;target dev='vnet1'/&gt;</b>
6083   &lt;/interface&gt;
6084 &lt;/devices&gt;
6085 ...</pre>
6086
6087     <p>
6088       If no target is specified, certain hypervisors will
6089       automatically generate a name for the created tun device. This
6090       name can be manually specified, however the name <i>should not
6091       start with either 'vnet', 'vif', 'macvtap', or 'macvlan'</i>,
6092       which are prefixes reserved by libvirt and certain hypervisors.
6093       Manually specified targets using these prefixes may be ignored.
6094     </p>
6095
6096     <p>
6097       Note that for LXC containers, this defines the name of the interface
6098       on the host side. <span class="since">Since 1.2.7</span>, to define
6099       the name of the device on the guest side, the <code>guest</code>
6100       element should be used, as in the following snippet:
6101     </p>
6102
6103 <pre>
6104 ...
6105 &lt;devices&gt;
6106   &lt;interface type='network'&gt;
6107     &lt;source network='default'/&gt;
6108     <b>&lt;guest dev='myeth'/&gt;</b>
6109   &lt;/interface&gt;
6110 &lt;/devices&gt;
6111 ...</pre>
6112
6113     <h5><a id="elementsNICSBoot">Specifying boot order</a></h5>
6114
6115 <pre>
6116 ...
6117 &lt;devices&gt;
6118   &lt;interface type='network'&gt;
6119     &lt;source network='default'/&gt;
6120     &lt;target dev='vnet1'/&gt;
6121     <b>&lt;boot order='1'/&gt;</b>
6122   &lt;/interface&gt;
6123 &lt;/devices&gt;
6124 ...</pre>
6125
6126     <p>
6127       For hypervisors which support this, you can set a specific NIC to
6128       be used for network boot. The <code>order</code> attribute determines
6129       the order in which devices will be tried during boot sequence. The
6130       per-device <code>boot</code> elements cannot be used together with
6131       general boot elements in
6132       <a href="#elementsOSBIOS">BIOS bootloader</a> section.
6133       <span class="since">Since 0.8.8</span>
6134     </p>
6135
6136     <h5><a id="elementsNICSROM">Interface ROM BIOS configuration</a></h5>
6137
6138 <pre>
6139 ...
6140 &lt;devices&gt;
6141   &lt;interface type='network'&gt;
6142     &lt;source network='default'/&gt;
6143     &lt;target dev='vnet1'/&gt;
6144     <b>&lt;rom bar='on' file='/etc/fake/boot.bin'/&gt;</b>
6145   &lt;/interface&gt;
6146 &lt;/devices&gt;
6147 ...</pre>
6148
6149     <p>
6150       For hypervisors which support this, you can change how a PCI Network
6151       device's ROM is presented to the guest. The <code>bar</code>
6152       attribute can be set to "on" or "off", and determines whether
6153       or not the device's ROM will be visible in the guest's memory
6154       map. (In PCI documentation, the "rombar" setting controls the
6155       presence of the Base Address Register for the ROM). If no rom
6156       bar is specified, the qemu default will be used (older
6157       versions of qemu used a default of "off", while newer qemus
6158       have a default of "on").
6159       The optional <code>file</code> attribute is used to point to a
6160       binary file to be presented to the guest as the device's ROM
6161       BIOS. This can be useful to provide an alternative boot ROM for a
6162       network device.
6163       <span class="since">Since 0.9.10 (QEMU and KVM only)</span>.
6164     </p>
6165     <h5><a id="elementDomain">Setting up a network backend in a driver domain</a></h5>
6166 <pre>
6167 ...
6168 &lt;devices&gt;
6169   ...
6170   &lt;interface type='bridge'&gt;
6171     &lt;source bridge='br0'/&gt;
6172     <b>&lt;backenddomain name='netvm'/&gt;</b>
6173   &lt;/interface&gt;
6174   ...
6175 &lt;/devices&gt;
6176 ...</pre>
6177
6178     <p>
6179       The optional <code>backenddomain</code> element allows specifying a
6180       backend domain (aka driver domain) for the interface. Use the
6181       <code>name</code> attribute to specify the backend domain name. You
6182       can use it to create a direct network link between domains (so data
6183       will not go through host system). Use with type 'ethernet' to create
6184       plain network link, or with type 'bridge' to connect to a bridge inside
6185       the backend domain.
6186       <span class="since">Since 1.2.13 (Xen only)</span>
6187     </p>
6188
6189     <h5><a id="elementQoS">Quality of service</a></h5>
6190
6191 <pre>
6192 ...
6193 &lt;devices&gt;
6194   &lt;interface type='network'&gt;
6195     &lt;source network='default'/&gt;
6196     &lt;target dev='vnet0'/&gt;
6197     <b>&lt;bandwidth&gt;
6198       &lt;inbound average='1000' peak='5000' floor='200' burst='1024'/&gt;
6199       &lt;outbound average='128' peak='256' burst='256'/&gt;
6200     &lt;/bandwidth&gt;</b>
6201   &lt;/interface&gt;
6202 &lt;/devices&gt;
6203 ...</pre>
6204
6205     <p>
6206       This part of interface XML provides setting quality of service. Incoming
6207       and outgoing traffic can be shaped independently.
6208       The <code>bandwidth</code> element and its child elements are described
6209       in the <a href="formatnetwork.html#elementQoS">QoS</a> section of
6210       the Network XML.
6211     </p>
6212
6213     <h5><a id="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
6214
6215 <pre>
6216 ...
6217 &lt;devices&gt;
6218   &lt;interface type='bridge'&gt;
6219     <b>&lt;vlan&gt;</b>
6220       <b>&lt;tag id='42'/&gt;</b>
6221     <b>&lt;/vlan&gt;</b>
6222     &lt;source bridge='ovsbr0'/&gt;
6223     &lt;virtualport type='openvswitch'&gt;
6224       &lt;parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&gt;
6225     &lt;/virtualport&gt;
6226   &lt;/interface&gt;
6227   &lt;interface type='bridge'&gt;
6228     <b>&lt;vlan trunk='yes'&gt;</b>
6229       <b>&lt;tag id='42'/&gt;</b>
6230       <b>&lt;tag id='123' nativeMode='untagged'/&gt;</b>
6231     <b>&lt;/vlan&gt;</b>
6232     ...
6233   &lt;/interface&gt;
6234 &lt;/devices&gt;
6235 ...</pre>
6236
6237     <p>
6238       If (and only if) the network connection used by the guest
6239       supports VLAN tagging transparent to the guest, an
6240       optional <code>&lt;vlan&gt;</code> element can specify one or
6241       more VLAN tags to apply to the guest's network
6242       traffic <span class="since">Since 0.10.0</span>. Network
6243       connections that support guest-transparent VLAN tagging include
6244       1) type='bridge' interfaces connected to an Open vSwitch bridge
6245       <span class="since">Since 0.10.0</span>, 2) SRIOV Virtual
6246       Functions (VF) used via type='hostdev' (direct device
6247       assignment) <span class="since">Since 0.10.0</span>, and 3)
6248       SRIOV VFs used via type='direct' with mode='passthrough'
6249       (macvtap "passthru" mode) <span class="since">Since
6250       1.3.5</span>. All other connection types, including standard
6251       linux bridges and libvirt's own virtual networks, <b>do not</b>
6252       support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
6253       provide their own way (outside of libvirt) to tag guest traffic
6254       onto a specific VLAN. Each tag is given in a
6255       separate <code>&lt;tag&gt;</code> subelement
6256       of <code>&lt;vlan&gt;</code> (for example: <code>&lt;tag
6257       id='42'/&gt;</code>). For VLAN trunking of multiple tags (which
6258       is supported only on Open vSwitch connections),
6259       multiple <code>&lt;tag&gt;</code> subelements can be specified,
6260       which implies that the user wants to do VLAN trunking on the
6261       interface for all the specified tags. In the case that VLAN
6262       trunking of a single tag is desired, the optional
6263       attribute <code>trunk='yes'</code> can be added to the toplevel
6264       <code>&lt;vlan&gt;</code> element to differentiate trunking of a
6265       single tag from normal tagging.
6266     </p>
6267     <p>
6268       For network connections using Open vSwitch it is also possible
6269       to configure 'native-tagged' and 'native-untagged' VLAN modes
6270       <span class="since">Since 1.1.0.</span> This is done with the
6271       optional <code>nativeMode</code> attribute on
6272       the <code>&lt;tag&gt;</code> subelement: <code>nativeMode</code>
6273       may be set to 'tagged' or 'untagged'. The <code>id</code>
6274       attribute of the <code>&lt;tag&gt;</code> subelement
6275       containing <code>nativeMode</code> sets which VLAN is considered
6276       to be the "native" VLAN for this interface, and
6277       the <code>nativeMode</code> attribute determines whether or not
6278       traffic for that VLAN will be tagged.
6279     </p>
6280
6281     <h5><a id="elementLink">Modifying virtual link state</a></h5>
6282 <pre>
6283 ...
6284 &lt;devices&gt;
6285   &lt;interface type='network'&gt;
6286     &lt;source network='default'/&gt;
6287     &lt;target dev='vnet0'/&gt;
6288     <b>&lt;link state='down'/&gt;</b>
6289   &lt;/interface&gt;
6290 &lt;/devices&gt;
6291 ...</pre>
6292
6293     <p>
6294       This element provides means of setting state of the virtual network link.
6295       Possible values for attribute <code>state</code> are <code>up</code> and
6296       <code>down</code>. If <code>down</code> is specified as the value, the interface
6297       behaves as if it had the network cable disconnected. Default behavior if this
6298       element is unspecified is to have the link state <code>up</code>.
6299       <span class="since">Since 0.9.5</span>
6300     </p>
6301
6302     <h5><a id="mtu">MTU configuration</a></h5>
6303 <pre>
6304 ...
6305 &lt;devices&gt;
6306   &lt;interface type='network'&gt;
6307     &lt;source network='default'/&gt;
6308     &lt;target dev='vnet0'/&gt;
6309     <b>&lt;mtu size='1500'/&gt;</b>
6310   &lt;/interface&gt;
6311 &lt;/devices&gt;
6312 ...</pre>
6313
6314     <p>
6315       This element provides means of setting MTU of the virtual network link.
6316       Currently there is just one attribute <code>size</code> which accepts a
6317       non-negative integer which specifies the MTU size for the interface.
6318       <span class="since">Since 3.1.0</span>
6319     </p>
6320
6321     <h5><a id="coalesce">Coalesce settings</a></h5>
6322 <pre>
6323 ...
6324 &lt;devices&gt;
6325   &lt;interface type='network'&gt;
6326     &lt;source network='default'/&gt;
6327     &lt;target dev='vnet0'/&gt;
6328     <b>&lt;coalesce&gt;
6329       &lt;rx&gt;
6330         &lt;frames max='7'/&gt;
6331       &lt;/rx&gt;
6332     &lt;/coalesce&gt;</b>
6333   &lt;/interface&gt;
6334 &lt;/devices&gt;
6335 ...</pre>
6336
6337     <p>
6338       This element provides means of setting coalesce settings for
6339       some interface devices (currently only type <code>network</code>
6340       and <code>bridge</code>.  Currently there is just one attribute,
6341       <code>max</code>, to tweak, in element <code>frames</code> for
6342       the <code>rx</code> group, which accepts a non-negative integer
6343       that specifies the maximum number of packets that will be
6344       received before an interrupt.
6345       <span class="since">Since 3.3.0</span>
6346     </p>
6347
6348     <h5><a id="ipconfig">IP configuration</a></h5>
6349 <pre>
6350 ...
6351 &lt;devices&gt;
6352   &lt;interface type='network'&gt;
6353     &lt;source network='default'/&gt;
6354     &lt;target dev='vnet0'/&gt;
6355     <b>&lt;ip address='192.168.122.5' prefix='24'/&gt;</b>
6356     <b>&lt;ip address='192.168.122.5' prefix='24' peer='10.0.0.10'/&gt;</b>
6357     <b>&lt;route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/&gt;</b>
6358     <b>&lt;route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/&gt;</b>
6359   &lt;/interface&gt;
6360   ...
6361   &lt;hostdev mode='capabilities' type='net'&gt;
6362     &lt;source&gt;
6363       &lt;interface&gt;eth0&lt;/interface&gt;
6364     &lt;/source&gt;
6365     <b>&lt;ip address='192.168.122.6' prefix='24'/&gt;</b>
6366     <b>&lt;route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/&gt;</b>
6367     <b>&lt;route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/&gt;</b>
6368   &lt;/hostdev&gt;
6369   ...
6370 &lt;/devices&gt;
6371 ...
6372 </pre>
6373
6374     <p>
6375       <span class="since">Since 1.2.12</span> network devices and
6376       hostdev devices with network capabilities can optionally be provided
6377       one or more IP addresses to set on the network device in the
6378       guest. Note that some hypervisors or network device types will
6379       simply ignore them or only use the first one.
6380       The <code>family</code> attribute can be set to
6381       either <code>ipv4</code> or <code>ipv6</code>, and the
6382       <code>address</code> attribute contains the IP address. The
6383       optional <code>prefix</code> is the number of 1 bits in the
6384       netmask, and will be automatically set if not specified - for
6385       IPv4 the default prefix is determined according to the network
6386       "class" (A, B, or C - see RFC870), and for IPv6 the default
6387       prefix is 64. The optional <code>peer</code> attribute holds the
6388       IP address of the other end of a point-to-point network
6389       device <span class="since">(since 2.1.0)</span>.
6390     </p>
6391
6392     <p>
6393     <span class="since">Since 1.2.12</span> route elements can also be
6394     added to define IP routes to add in the guest.  The attributes of
6395     this element are described in the documentation for
6396     the <code>route</code> element
6397     in <a href="formatnetwork.html#elementsStaticroute">network
6398     definitions</a>.  This is used by the LXC driver.
6399     </p>
6400
6401 <pre>
6402 ...
6403 &lt;devices&gt;
6404   &lt;interface type='ethernet'&gt;
6405     <b>&lt;source/&gt;</b>
6406       <b>&lt;ip address='192.168.123.1' prefix='24'/&gt;</b>
6407       <b>&lt;ip address='10.0.0.10' prefix='24' peer='192.168.122.5'/&gt;</b>
6408       <b>&lt;route family='ipv4' address='192.168.42.0' prefix='24' gateway='192.168.123.4'/&gt;</b>
6409     <b>&lt;source/&gt;</b>
6410     ...
6411   &lt;/interface&gt;
6412   ...
6413 &lt;/devices&gt;
6414 ...
6415 </pre>
6416
6417     <p>
6418       <span class="since">Since 2.1.0</span> network devices of type
6419       "ethernet" can optionally be provided one or more IP addresses
6420       and one or more routes to set on the <b>host</b> side of the
6421       network device. These are configured as subelements of
6422       the <code>&lt;source&gt;</code> element of the interface, and
6423       have the same attributes as the similarly named elements used to
6424       configure the guest side of the interface (described above).
6425     </p>
6426
6427     <h5><a id="elementVhostuser">vhost-user interface</a></h5>
6428
6429     <p>
6430     <span class="since">Since 1.2.7</span> the vhost-user enables the
6431     communication between a QEMU virtual machine and other userspace process
6432     using the Virtio transport protocol.  A char dev (e.g. Unix socket) is used
6433     for the control plane, while the data plane is based on shared memory.
6434     </p>
6435
6436 <pre>
6437 ...
6438 &lt;devices&gt;
6439   &lt;interface type='vhostuser'&gt;
6440     &lt;mac address='52:54:00:3b:83:1a'/&gt;
6441     &lt;source type='unix' path='/tmp/vhost1.sock' mode='server'/&gt;
6442     &lt;model type='virtio'/&gt;
6443   &lt;/interface&gt;
6444   &lt;interface type='vhostuser'&gt;
6445     &lt;mac address='52:54:00:3b:83:1b'/&gt;
6446     &lt;source type='unix' path='/tmp/vhost2.sock' mode='client'&gt;
6447       &lt;reconnect enabled='yes' timeout='10'/&gt;
6448     &lt;/source&gt;
6449     &lt;model type='virtio'/&gt;
6450     &lt;driver queues='5'/&gt;
6451   &lt;/interface&gt;
6452 &lt;/devices&gt;
6453 ...</pre>
6454
6455     <p>
6456       The <code>&lt;source&gt;</code> element has to be specified
6457       along with the type of char device.
6458       Currently, only type='unix' is supported, where the path (the
6459       directory path of the socket) and mode attributes are required.
6460       Both <code>mode='server'</code> and <code>mode='client'</code>
6461       are supported.
6462       vhost-user requires the virtio model type, thus the
6463       <code>&lt;model&gt;</code> element is mandatory.
6464       <span class="since">Since 4.1.0</span> the element has an
6465       optional child element <code>reconnect</code> which
6466       configures reconnect timeout if the connection is lost. It
6467       has two attributes <code>enabled</code> (which accepts
6468       <code>yes</code> and <code>no</code>) and
6469       <code>timeout</code> which specifies the amount of seconds
6470       after which hypervisor tries to reconnect.
6471     </p>
6472
6473     <h5><a id="elementNwfilter">Traffic filtering with NWFilter</a></h5>
6474
6475     <p>
6476     <span class="since">Since 0.8.0</span> an <code>nwfilter</code> profile
6477     can be assigned to a domain interface, which allows configuring
6478     traffic filter rules for the virtual machine.
6479
6480     See the <a href="formatnwfilter.html">nwfilter</a> documentation for more
6481     complete details.
6482     </p>
6483
6484 <pre>
6485 ...
6486 &lt;devices&gt;
6487   &lt;interface ...&gt;
6488     ...
6489     &lt;filterref filter='clean-traffic'/&gt;
6490   &lt;/interface&gt;
6491   &lt;interface ...&gt;
6492     ...
6493     &lt;filterref filter='myfilter'&gt;
6494       &lt;parameter name='IP' value='104.207.129.11'/&gt;
6495       &lt;parameter name='IP6_ADDR' value='2001:19f0:300:2102::'/&gt;
6496       &lt;parameter name='IP6_MASK' value='64'/&gt;
6497       ...
6498     &lt;/filterref&gt;
6499   &lt;/interface&gt;
6500 &lt;/devices&gt;
6501 ...</pre>
6502
6503     <p>
6504       The <code>filter</code> attribute specifies the name of the nwfilter
6505       to use. Optional <code>&lt;parameter&gt;</code> elements may be
6506       specified for passing additional info to the nwfilter via the
6507       <code>name</code> and <code>value</code> attributes. See
6508       the <a href="formatnwfilter.html#nwfconceptsvars">nwfilter</a>
6509       docs for info on parameters.
6510     </p>
6511
6512
6513     <h4><a id="elementsInput">Input devices</a></h4>
6514
6515     <p>
6516       Input devices allow interaction with the graphical framebuffer
6517       in the guest virtual machine. When enabling the framebuffer, an
6518       input device is automatically provided. It may be possible to
6519       add additional devices explicitly, for example,
6520       to provide a graphics tablet for absolute cursor movement.
6521     </p>
6522
6523 <pre>
6524 ...
6525 &lt;devices&gt;
6526   &lt;input type='mouse' bus='usb'/&gt;
6527   &lt;input type='keyboard' bus='usb'/&gt;
6528   &lt;input type='mouse' bus='virtio'/&gt;
6529   &lt;input type='keyboard' bus='virtio'/&gt;
6530   &lt;input type='tablet' bus='virtio'/&gt;
6531   &lt;input type='passthrough' bus='virtio'&gt;
6532     &lt;source evdev='/dev/input/event1/&gt;
6533   &lt;/input&gt;
6534 &lt;/devices&gt;
6535 ...</pre>
6536
6537     <dl>
6538       <dt><code>input</code></dt>
6539       <dd>The <code>input</code> element has one mandatory attribute,
6540         the <code>type</code> whose value can be 'mouse', 'tablet',
6541         (<span class="since">since 1.2.2</span>) 'keyboard' or
6542         (<span class="since">since 1.3.0</span>) 'passthrough'.
6543         The tablet provides absolute cursor movement,
6544         while the mouse uses relative movement. The optional
6545         <code>bus</code> attribute can be used to refine the exact device type.
6546         It takes values "xen" (paravirtualized), "ps2" and "usb" or
6547         (<span class="since">since 1.3.0</span>) "virtio".</dd>
6548     </dl>
6549
6550     <p>
6551       The <code>input</code> element has an optional
6552       sub-element <code>&lt;address&gt;</code> which can tie the
6553       device to a particular PCI
6554       slot, <a href="#elementsAddress">documented above</a>.
6555       On S390, <code>address</code> can be used to provide a CCW address for
6556       an input device (<span class="since">since 4.2.0</span>).
6557
6558       For type <code>passthrough</code>, the mandatory sub-element <code>source</code>
6559       must have an <code>evdev</code> attribute containing the absolute path to the
6560       event device passed through to guests. (KVM only)
6561
6562       <span class="since">Since 5.2.0</span>, the <code>input</code> element
6563       accepts a <code>model</code> attribute which has the values 'virtio',
6564       'virtio-transitional' and 'virtio-non-transitional'. See
6565       <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
6566       for more details.
6567     </p>
6568
6569     <p>
6570         The subelement <code>driver</code> can be used to tune the virtio
6571         options of the device:
6572         <a href="#elementsVirtio">Virtio-specific options</a> can also be
6573         set. (<span class="since">Since 3.5.0</span>)
6574     </p>
6575
6576     <h4><a id="elementsHub">Hub devices</a></h4>
6577
6578     <p>
6579       A hub is a device that expands a single port into several so
6580       that there are more ports available to connect devices to a host
6581       system.
6582     </p>
6583
6584 <pre>
6585 ...
6586 &lt;devices&gt;
6587   &lt;hub type='usb'/&gt;
6588 &lt;/devices&gt;
6589 ...</pre>
6590
6591     <dl>
6592       <dt><code>hub</code></dt>
6593       <dd>The <code>hub</code> element has one mandatory attribute,
6594         the <code>type</code> whose value can only be 'usb'.</dd>
6595     </dl>
6596
6597     <p>
6598       The <code>hub</code> element has an optional
6599       sub-element <code>&lt;address&gt;</code>
6600       with <code>type='usb'</code>which can tie the device to a
6601       particular controller, <a href="#elementsAddress">documented
6602       above</a>.
6603     </p>
6604
6605     <h4><a id="elementsGraphics">Graphical framebuffers</a></h4>
6606
6607     <p>
6608       A graphics device allows for graphical interaction with the
6609       guest OS. A guest will typically have either a framebuffer
6610       or a text console configured to allow interaction with the
6611       admin.
6612     </p>
6613
6614 <pre>
6615 ...
6616 &lt;devices&gt;
6617   &lt;graphics type='sdl' display=':0.0'/&gt;
6618   &lt;graphics type='vnc' port='5904' sharePolicy='allow-exclusive'&gt;
6619     &lt;listen type='address' address='1.2.3.4'/&gt;
6620   &lt;/graphics&gt;
6621   &lt;graphics type='rdp' autoport='yes' multiUser='yes' /&gt;
6622   &lt;graphics type='desktop' fullscreen='yes'/&gt;
6623   &lt;graphics type='spice'&gt;
6624     &lt;listen type='network' network='rednet'/&gt;
6625   &lt;/graphics&gt;
6626 &lt;/devices&gt;
6627 ...</pre>
6628
6629     <dl>
6630       <dt><code>graphics</code></dt>
6631       <dd>
6632         <p>
6633           The <code>graphics</code> element has a mandatory <code>type</code>
6634           attribute which takes the value <code>sdl</code>, <code>vnc</code>,
6635           <code>spice</code>, <code>rdp</code>, <code>desktop</code> or
6636           <code>egl-headless</code>:
6637         </p>
6638         <dl>
6639           <dt><code>sdl</code></dt>
6640           <dd>
6641             <p>
6642               This displays a window on the host desktop, it can take 3 optional
6643               arguments: a <code>display</code> attribute for the display to use,
6644               an <code>xauth</code> attribute for the authentication identifier,
6645               and an optional <code>fullscreen</code> attribute accepting values
6646               <code>yes</code> or <code>no</code>.
6647             </p>
6648
6649             <p>
6650               You can use a <code>gl</code> with the <code>enable="yes"</code>
6651               property to enable OpenGL support in SDL. Likewise you can
6652               explicitly disable OpenGL support with <code>enable="no"</code>.
6653             </p>
6654           </dd>
6655           <dt><code>vnc</code></dt>
6656           <dd>
6657             <p>
6658               Starts a VNC server. The <code>port</code> attribute specifies
6659               the TCP port number (with -1 as legacy syntax indicating that it
6660               should be auto-allocated). The <code>autoport</code> attribute is
6661               the new preferred syntax for indicating auto-allocation of the TCP
6662               port to use. The <code>passwd</code> attribute provides a VNC
6663               password in clear text. If the <code>passwd</code> attribute is
6664               set to an empty string, then VNC access is disabled. The
6665               <code>keymap</code> attribute specifies the keymap to use. It is
6666               possible to set a limit on the validity of the password by giving
6667               a timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
6668               assumed to be in UTC. The <code>connected</code> attribute allows
6669               control of connected client during password changes. VNC accepts
6670               <code>keep</code> value only <span class="since">since 0.9.3</span>.
6671               NB, this may not be supported by all hypervisors.
6672             </p>
6673             <p>
6674               The optional <code>sharePolicy</code> attribute specifies vnc
6675               server display sharing policy. <code>allow-exclusive</code> allows
6676               clients to ask for exclusive access by dropping other connections.
6677               Connecting multiple clients in parallel requires all clients asking
6678               for a shared session (vncviewer: -Shared switch). This is
6679               the default value. <code>force-shared</code> disables exclusive
6680               client access, every connection has to specify -Shared switch for
6681               vncviewer. <code>ignore</code> welcomes every connection
6682               unconditionally <span class="since">since 1.0.6</span>.
6683             </p>
6684             <p>
6685               Rather than using listen/port, QEMU supports a <code>socket</code>
6686               attribute for listening on a unix domain socket path
6687               <span class="since">Since 0.8.8</span>.
6688             </p>
6689             <p>
6690               For VNC WebSocket functionality, <code>websocket</code> attribute
6691               may be used to specify port to listen on (with -1 meaning
6692               auto-allocation and <code>autoport</code> having no effect due to
6693               security reasons) <span class="since">Since 1.0.6</span>.
6694             </p>
6695             <p>
6696               Although VNC doesn't support OpenGL natively, it can be paired
6697               with graphics type <code>egl-headless</code> (see below) which
6698               will instruct QEMU to open and use drm nodes for OpenGL rendering.
6699             </p>
6700           </dd>
6701           <dt><code>spice</code> <span class="since">Since 0.8.6</span></dt>
6702           <dd>
6703             <p>
6704               Starts a SPICE server. The <code>port</code> attribute specifies
6705               the TCP port number (with -1 as legacy syntax indicating that it
6706               should be auto-allocated), while <code>tlsPort</code> gives
6707               an alternative secure port number. The <code>autoport</code>
6708               attribute is the new preferred syntax for indicating
6709               auto-allocation of needed port numbers. The <code>passwd</code>
6710               attribute provides a SPICE password in clear text. If the
6711               <code>passwd</code> attribute is set to an empty string, then
6712               SPICE access is disabled. The <code>keymap</code> attribute
6713               specifies the keymap to use. It is possible to set a limit on
6714               the validity of the password by giving a timestamp
6715               <code>passwdValidTo='2010-04-09T15:51:00'</code> assumed to be
6716               in UTC.
6717             </p>
6718             <p>
6719               The <code>connected</code> attribute allows control of connected
6720               client during password changes. SPICE accepts <code>keep</code> to
6721               keep client connected, <code>disconnect</code> to disconnect client
6722               and <code>fail</code> to fail changing password . NB, this may not
6723               be supported by all hypervisors.
6724               <span class="since">Since 0.9.3</span>
6725             </p>
6726             <p>
6727               The <code>defaultMode</code> attribute sets the default channel
6728               security policy, valid values are <code>secure</code>,
6729               <code>insecure</code> and the default <code>any</code> (which is
6730               secure if possible, but falls back to insecure rather than erroring
6731               out if no secure path is available).
6732               <span class="since">Since 0.9.12</span>
6733             </p>
6734             <p>
6735               When SPICE has both a normal and TLS secured TCP port configured,
6736               it can be desirable to restrict what channels can be run on each
6737               port. This is achieved by adding one or more <code>&lt;channel&gt;
6738               </code> elements inside the main <code>&lt;graphics&gt;</code>
6739               element and setting the <code>mode</code> attribute to either
6740               <code>secure</code> or <code>insecure</code>. Setting the mode
6741               attribute overrides the default value as set by
6742               the <code>defaultMode</code> attribute. (Note that specifying
6743               <code>any</code> as mode discards the entry as the channel would
6744               inherit the default mode anyways.) Valid channel names include
6745               <code>main</code>, <code>display</code>, <code>inputs</code>,
6746               <code>cursor</code>, <code>playback</code>, <code>record</code>
6747               (all <span class="since"> since 0.8.6</span>);
6748               <code>smartcard</code> (<span class="since">since 0.8.8</span>);
6749               and <code>usbredir</code> (<span class="since">since 0.9.12</span>).
6750             </p>
6751             <pre>
6752 &lt;graphics type='spice' port='-1' tlsPort='-1' autoport='yes'&gt;
6753   &lt;channel name='main' mode='secure'/&gt;
6754   &lt;channel name='record' mode='insecure'/&gt;
6755   &lt;image compression='auto_glz'/&gt;
6756   &lt;streaming mode='filter'/&gt;
6757   &lt;clipboard copypaste='no'/&gt;
6758   &lt;mouse mode='client'/&gt;
6759   &lt;filetransfer enable='no'/&gt;
6760   &lt;gl enable='yes' rendernode='/dev/dri/by-path/pci-0000:00:02.0-render'/&gt;
6761 &lt;/graphics&gt;</pre>
6762             <p>
6763               Spice supports variable compression settings for audio, images and
6764               streaming. These settings are accessible via the <code>compression
6765               </code> attribute in all following elements: <code>image</code> to
6766               set image compression (accepts <code>auto_glz</code>,
6767               <code>auto_lz</code>, <code>quic</code>, <code>glz</code>,
6768               <code>lz</code>, <code>off</code>), <code>jpeg</code> for JPEG
6769               compression for images over wan (accepts <code>auto</code>,
6770               <code>never</code>, <code>always</code>), <code>zlib</code> for
6771               configuring wan image compression (accepts <code>auto</code>,
6772               <code>never</code>, <code>always</code>)  and <code>playback</code>
6773               for enabling audio stream compression (accepts <code>on</code> or
6774               <code>off</code>). <span class="since">Since 0.9.1</span>
6775             </p>
6776             <p>
6777               Streaming mode is set by the <code>streaming</code> element,
6778               settings its <code>mode</code> attribute to one of
6779               <code>filter</code>, <code>all</code> or <code>off</code>.
6780               <span class="since">Since 0.9.2</span>
6781             </p>
6782             <p>
6783               Copy &amp; Paste functionality (via Spice agent) is set by the
6784               <code>clipboard</code> element. It is enabled by default, and can
6785               be disabled by setting the <code>copypaste</code> property to
6786               <code>no</code>. <span class="since">Since 0.9.3</span>
6787             </p>
6788             <p>
6789               Mouse mode is set by the <code>mouse</code> element, setting its
6790               <code>mode</code> attribute to one of <code>server</code> or
6791               <code>client</code>. If no mode is specified, the qemu default will
6792               be used (client mode). <span class="since">Since 0.9.11</span>
6793             </p>
6794             <p>
6795               File transfer functionality (via Spice agent) is set using the
6796               <code>filetransfer</code> element. It is enabled by default, and
6797               can be disabled by setting the <code>enable</code> property to
6798               <code>no</code>. <span class="since">Since 1.2.2</span>
6799             </p>
6800             <p>
6801               Spice may provide accelerated server-side rendering with OpenGL.
6802               You can enable or disable OpenGL support explicitly with
6803               the <code>gl</code> element, by setting the <code>enable</code>
6804               property. (QEMU only, <span class="since">since 1.3.3</span>).
6805               Note that this only works locally, since this requires usage of
6806               UNIX sockets, i.e. using <code>listen</code> types 'socket' or
6807               'none'. For accelerated OpenGL with remote support, consider
6808               pairing this element with type <code>egl-headless</code>
6809               (see below). However, this will deliver weaker performance
6810               compared to native Spice OpenGL support.
6811             </p>
6812             <p>
6813               By default, QEMU will pick the first available GPU DRM render node.
6814               You may specify a DRM render node path to use instead. (QEMU only,
6815               <span class="since">since 3.1.0</span>).
6816             </p>
6817           </dd>
6818           <dt><code>rdp</code></dt>
6819           <dd>
6820             <p>
6821               Starts a RDP server. The <code>port</code> attribute specifies the
6822               TCP port number (with -1 as legacy syntax indicating that it should
6823               be auto-allocated). The <code>autoport</code> attribute is the new
6824               preferred syntax for indicating auto-allocation of the TCP port to
6825               use. In the VirtualBox driver, the <code>autoport</code> will make
6826               the hypervisor pick available port from 3389-3689 range when the VM
6827               is started. The chosen port will be reflected in the <code>port</code>
6828               attribute. The <code>multiUser</code> attribute is a boolean deciding
6829               whether multiple simultaneous connections to the VM are permitted.
6830               The <code>replaceUser</code> attribute is a boolean deciding whether
6831               the existing connection must be dropped and a new connection must
6832               be established by the VRDP server, when a new client connects in
6833               single connection mode.
6834             </p>
6835           </dd>
6836           <dt><code>desktop</code></dt>
6837           <dd>
6838             <p>
6839               This value is reserved for VirtualBox domains for the moment. It
6840               displays a window on the host desktop, similarly to "sdl", but
6841               using the VirtualBox viewer. Just like "sdl", it accepts
6842               the optional attributes <code>display</code> and
6843               <code>fullscreen</code>.
6844             </p>
6845           </dd>
6846           <dt><code>egl-headless</code><span class="since">Since 4.6.0</span></dt>
6847           <dd>
6848             <p>
6849               This display type provides support for an OpenGL accelerated
6850               display accessible both locally and remotely (for comparison,
6851               Spice's native OpenGL support only works locally using UNIX
6852               sockets at the moment, but has better performance). Since this
6853               display type doesn't provide any window or graphical console like
6854               the other types, for practical reasons it should be paired with
6855               either <code>vnc</code> or <code>spice</code> graphics types.
6856               This display type is only supported by QEMU domains
6857               (needs QEMU <span class="since">2.10</span> or newer).
6858               <span class="Since">5.0.0</span> this element accepts a
6859               <code>&lt;gl/&gt;</code> sub-element with an optional attribute
6860               <code>rendernode</code> which can be used to specify an absolute
6861               path to a host's DRI device to be used for OpenGL rendering.
6862             </p>
6863             <pre>
6864 &lt;graphics type='spice' autoport='yes'/&gt;
6865 &lt;graphics type='egl-headless'&gt;
6866   &lt;gl rendernode='/dev/dri/renderD128'/&gt;
6867 &lt;/graphics&gt;
6868             </pre>
6869           </dd>
6870         </dl>
6871       </dd>
6872     </dl>
6873
6874     <p>
6875       Graphics device uses a <code>&lt;listen&gt;</code> to set up where
6876       the device should listen for clients. It has a mandatory attribute
6877       <code>type</code> which specifies the listen type. Only <code>vnc</code>,
6878       <code>spice</code> and <code>rdp</code> supports <code>&lt;listen&gt;
6879       </code> element. <span class="since">Since 0.9.4</span>.
6880       Available types are:
6881     </p>
6882     <dl>
6883       <dt><code>address</code></dt>
6884       <dd>
6885         <p>
6886           Tells a graphics device to use an address specified in the
6887           <code>address</code> attribute, which will contain either an IP address
6888           or hostname (which will be resolved to an IP address via a DNS query)
6889           to listen on.
6890         </p>
6891         <p>
6892           It is possible to omit the <code>address</code> attribute in order to
6893           use an address from config files <span class="since">Since 1.3.5</span>.
6894         </p>
6895         <p>
6896           The <code>address</code> attribute is duplicated as <code>listen</code>
6897           attribute in <code>graphics</code> element for backward compatibility.
6898           If both are provided they must be equal.
6899         </p>
6900       </dd>
6901       <dt><code>network</code></dt>
6902       <dd>
6903         <p>
6904           This is used to specify an existing network in the <code>network</code>
6905           attribute from libvirt's list of configured networks. The named network
6906           configuration will be examined to determine an appropriate listen
6907           address and the address will be stored in live XML in <code>address
6908           </code> attribute. For example, if the network has an IPv4 address in
6909           its configuration (e.g. if it has a forward type of <code>route</code>,
6910           <code>nat</code>, or no forward type (isolated)), the first IPv4
6911           address listed in the network's configuration will be used.
6912           If the network is describing a host bridge, the first IPv4 address
6913           associated with that bridge device will be used, and if the network is
6914           describing one of the 'direct' (macvtap) modes, the first IPv4 address
6915           of the first forward dev will be used.
6916         </p>
6917       </dd>
6918       <dt><code>socket</code> <span class="since">since 2.0.0 (QEMU only)</span></dt>
6919       <dd>
6920         <p>
6921           This listen type tells a graphics server to listen on unix socket.
6922           Attribute <code>socket</code> contains a path to unix socket. If this
6923           attribute is omitted libvirt will generate this path for you.
6924           Supported by graphics type <code>vnc</code> and <code>spice</code>.
6925         </p>
6926         <p>
6927           For <code>vnc</code> graphics be backward compatible
6928           the <code>socket</code> attribute of first <code>listen</code> element
6929           is duplicated as <code>socket</code> attribute in <code>graphics</code>
6930           element. If <code>graphics</code> element contains a <code>socket</code>
6931           attribute all <code>listen</code> elements are ignored.
6932         </p>
6933       </dd>
6934       <dt><code>none</code> <span class="since">since 2.0.0 (QEMU only)</span></dt>
6935       <dd>
6936         <p>
6937           This listen type doesn't have any other attribute. Libvirt supports
6938           passing a file descriptor through our APIs virDomainOpenGraphics() and
6939           virDomainOpenGraphicsFD(). No other listen types are allowed if this
6940           one is used and the graphics device doesn't listen anywhere. You need
6941           to use one of the two APIs to pass a FD to QEMU in order to connect to
6942           this graphics device. Supported by graphics type <code>vnc</code> and
6943           <code>spice</code>.
6944         </p>
6945       </dd>
6946     </dl>
6947
6948     <h4><a id="elementsVideo">Video devices</a></h4>
6949     <p>
6950       A video device.
6951     </p>
6952
6953 <pre>
6954 ...
6955 &lt;devices&gt;
6956   &lt;video&gt;
6957     &lt;model type='vga' vram='16384' heads='1'&gt;
6958       &lt;acceleration accel3d='yes' accel2d='yes'/&gt;
6959     &lt;/model&gt;
6960   &lt;/video&gt;
6961 &lt;/devices&gt;
6962 ...</pre>
6963
6964     <dl>
6965       <dt><code>video</code></dt>
6966       <dd>
6967         <p>
6968           The <code>video</code> element is the container for describing
6969           video devices. For backwards compatibility, if no <code>video</code>
6970           is set but there is a <code>graphics</code> in domain xml, then
6971           libvirt will add a default <code>video</code> according to the guest
6972           type.
6973         </p>
6974         <p>
6975           For a guest of type "kvm", the default <code>video</code> is:
6976           <code>type</code> with value "cirrus", <code>vram</code> with value
6977           "16384" and <code>heads</code> with value "1". By default, the first
6978           video device in domain xml is the primary one, but the optional
6979           attribute <code>primary</code> (<span class="since">since 1.0.2</span>)
6980           with value 'yes' can be used to mark the primary in cases of multiple
6981           video device. The non-primary must be type of "qxl" or
6982           (<span class="since">since 2.4.0</span>) "virtio".
6983         </p>
6984       </dd>
6985
6986       <dt><code>model</code></dt>
6987       <dd>
6988         <p>
6989           The <code>model</code> element has a mandatory <code>type</code>
6990           attribute which takes the value "vga", "cirrus", "vmvga", "xen",
6991           "vbox", "qxl" (<span class="since">since 0.8.6</span>),
6992           "virtio" (<span class="since">since 1.3.0</span>),
6993           "gop" (<span class="since">since 3.2.0</span>), or
6994           "none" (<span class="since">since 4.6.0</span>)
6995           depending on the hypervisor features available.
6996           The purpose of the type <code>none</code> is to instruct libvirt not
6997           to add a default video device in the guest (see the paragraph above).
6998           This legacy behaviour can be inconvenient in cases where GPU mediated
6999           devices are meant to be the only rendering device within a guest and
7000           so specifying another <code>video</code> device along with type
7001           <code>none</code>.
7002           Refer to <a id="elementsHostDev">Host device assignment</a> to see
7003           how to add a mediated device into a guest.
7004         </p>
7005         <p>
7006           You can provide the amount of video memory in kibibytes (blocks of
7007           1024 bytes) using <code>vram</code>. This is supported only for guest
7008           type of "libxl", "vz", "qemu", "vbox", "vmx" and "xen". If no
7009           value is provided the default is used. If the size is not a power of
7010           two it will be rounded to closest one.
7011         </p>
7012         <p>
7013           The number of screen can be set using <code>heads</code>. This is
7014           supported only for guests type of "vz", "kvm", "vbox" and "vmx".
7015         </p>
7016         <p>
7017           For guest type of "kvm" or "qemu" and model type "qxl" there are
7018           optional attributes. Attribute <code>ram</code> (<span class="since">
7019           since 1.0.2</span>) specifies the size of the primary bar, while the
7020           attribute <code>vram</code> specifies the secondary bar size.
7021           If <code>ram</code> or <code>vram</code> are not supplied a default
7022           value is used. The <code>ram</code> should also be rounded to power of
7023           two as <code>vram</code>. There is also optional attribute
7024           <code>vgamem</code> (<span class="since">since 1.2.11</span>) to set
7025           the size of VGA framebuffer for fallback mode of QXL device.
7026           Attribute <code>vram64</code> (<span class="since">since 1.3.3</span>)
7027           extends secondary bar and makes it addressable as 64bit memory.
7028         </p>
7029       </dd>
7030
7031       <dt><code>acceleration</code></dt>
7032       <dd>
7033         Configure if video acceleration should be enabled.
7034         <dl>
7035         <dt><code>accel2d</code></dt>
7036         <dd>Enable 2D acceleration (for vbox driver only,
7037         <span class="since">since 0.7.1</span>)</dd>
7038
7039         <dt><code>accel3d</code></dt>
7040         <dd>Enable 3D acceleration (for vbox driver
7041         <span class="since">since 0.7.1</span>, qemu driver
7042         <span class="since">since 1.3.0</span>)</dd>
7043         </dl>
7044       </dd>
7045
7046       <dt><code>address</code></dt>
7047       <dd>
7048         The optional <code>address</code> sub-element can be used to
7049         tie the video device to a particular PCI slot.
7050         On S390, <code>address</code> can be used to provide the
7051         CCW address for the video device (<span class="since">
7052         since 4.2.0</span>).
7053       </dd>
7054
7055       <dt><code>driver</code></dt>
7056       <dd>
7057         The subelement <code>driver</code> can be used to tune the device:
7058         <dl>
7059           <dt>virtio options</dt>
7060           <dd>
7061           <a href="#elementsVirtio">Virtio-specific options</a> can also be
7062           set (<span class="since">Since 3.5.0</span>)
7063           </dd>
7064           <dt>VGA configuration</dt>
7065           <dd>
7066           Control how the video devices exposed to the guest using the
7067           <code>vgaconf</code> attribute which takes the value "io", "on" or "off".
7068           At present, it's only applicable to the bhyve's "gop" video model type
7069           (<span class="since">Since 3.5.0</span>)
7070           </dd>
7071         </dl>
7072       </dd>
7073     </dl>
7074
7075     <h4><a id="elementsConsole">Consoles, serial, parallel &amp; channel devices</a></h4>
7076
7077     <p>
7078       A character device provides a way to interact with the virtual machine.
7079       Paravirtualized consoles, serial ports, parallel ports and channels are
7080       all classed as character devices and so represented using the same syntax.
7081     </p>
7082
7083 <pre>
7084 ...
7085 &lt;devices&gt;
7086   &lt;parallel type='pty'&gt;
7087     &lt;source path='/dev/pts/2'/&gt;
7088     &lt;target port='0'/&gt;
7089   &lt;/parallel&gt;
7090   &lt;serial type='pty'&gt;
7091     &lt;source path='/dev/pts/3'/&gt;
7092     &lt;target port='0'/&gt;
7093   &lt;/serial&gt;
7094   &lt;serial type='file'&gt;
7095     &lt;source path='/tmp/file' append='on'&gt;
7096       &lt;seclabel model='dac' relabel='no'/&gt;
7097     &lt;/source&gt;
7098     &lt;target port='0'/&gt;
7099   &lt;/serial&gt;
7100   &lt;console type='pty'&gt;
7101     &lt;source path='/dev/pts/4'/&gt;
7102     &lt;target port='0'/&gt;
7103   &lt;/console&gt;
7104   &lt;channel type='unix'&gt;
7105     &lt;source mode='bind' path='/tmp/guestfwd'/&gt;
7106     &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
7107   &lt;/channel&gt;
7108 &lt;/devices&gt;
7109 ...</pre>
7110
7111     <p>
7112       In each of these directives, the top-level element name (parallel, serial,
7113       console, channel) describes how the device is presented to the guest. The
7114       guest interface is configured by the <code>target</code> element.
7115     </p>
7116
7117     <p>
7118       The interface presented to the host is given in the <code>type</code>
7119       attribute of the top-level element. The host interface is
7120       configured by the <code>source</code> element.
7121     </p>
7122
7123     <p>
7124       The <code>source</code> element may contain an optional
7125       <code>seclabel</code> to override the way that labelling
7126       is done on the socket path.  If this element is not present,
7127       the <a href="#seclabel">security label is inherited from
7128         the per-domain setting</a>.
7129     </p>
7130
7131     <p>
7132       If the interface <code>type</code> presented to the host is "file",
7133       then the <code>source</code> element may contain an optional attribute
7134       <code>append</code> that specifies whether or not the information in
7135       the file should be preserved on domain restart. Allowed values are
7136       "on" and "off" (default). <span class="since">Since 1.3.1</span>.
7137     </p>
7138
7139     <p>
7140       Regardless of the <code>type</code>, character devices can
7141       have an optional log file associated with them. This is
7142       expressed via a <code>log</code> sub-element, with a
7143       <code>file</code> attribute. There can also be an <code>append</code>
7144       attribute which takes the same values described above.
7145       <span class="since">Since 1.3.3</span>.
7146     </p>
7147
7148     <pre>
7149 ...
7150 &lt;log file="/var/log/libvirt/qemu/guestname-serial0.log" append="off"/&gt;
7151 ...</pre>
7152
7153     <p>
7154       Each character device element has an optional
7155       sub-element <code>&lt;address&gt;</code> which can tie the
7156       device to a
7157       particular <a href="#elementsControllers">controller</a> or PCI
7158       slot.
7159     </p>
7160
7161     <p>
7162       For character device with type <code>unix</code> or <code>tcp</code>
7163       the <code>source</code> has an optional element <code>reconnect</code>
7164       which configures reconnect timeout if the connection is lost.
7165       There are two attributes, <code>enabled</code> where possible
7166       values are "yes" and "no" and <code>timeout</code> which is in
7167       seconds. The <code>reconnect</code> attribute is valid only
7168       for <code>connect</code> mode.
7169       <span class="since">Since 3.7.0 (QEMU driver only)</span>.
7170     </p>
7171
7172     <h5><a id="elementsCharGuestInterface">Guest interface</a></h5>
7173
7174     <p>
7175       A character device presents itself to the guest as one of the following
7176       types.
7177     </p>
7178
7179     <h6><a id="elementCharParallel">Parallel port</a></h6>
7180
7181 <pre>
7182 ...
7183 &lt;devices&gt;
7184   &lt;parallel type='pty'&gt;
7185     &lt;source path='/dev/pts/2'/&gt;
7186     &lt;target port='0'/&gt;
7187   &lt;/parallel&gt;
7188 &lt;/devices&gt;
7189 ...</pre>
7190
7191     <p>
7192       <code>target</code> can have a <code>port</code> attribute, which
7193       specifies the port number. Ports are numbered starting from 0. There are
7194       usually 0, 1 or 2 parallel ports.
7195     </p>
7196
7197     <h6><a id="elementCharSerial">Serial port</a></h6>
7198
7199 <pre>
7200 ...
7201 &lt;devices&gt;
7202   &lt;!-- Serial port --&gt;
7203   &lt;serial type='pty'&gt;
7204     &lt;source path='/dev/pts/3'/&gt;
7205     &lt;target port='0'/&gt;
7206   &lt;/serial&gt;
7207 &lt;/devices&gt;
7208 ...</pre>
7209
7210 <pre>
7211 ...
7212 &lt;devices&gt;
7213   &lt;!-- USB serial port --&gt;
7214   &lt;serial type='pty'&gt;
7215     &lt;target type='usb-serial' port='0'&gt;
7216       &lt;model name='usb-serial'/&gt;
7217     &lt;/target&gt;
7218     &lt;address type='usb' bus='0' port='1'/&gt;
7219   &lt;/serial&gt;
7220 &lt;/devices&gt;
7221 ...</pre>
7222
7223     <p>
7224       The <code>target</code> element can have an optional <code>port</code>
7225       attribute, which specifies the port number (starting from 0), and an
7226       optional <code>type</code> attribute: valid values are,
7227       <span class="since">since 1.0.2</span>, <code>isa-serial</code> (usable
7228       with x86 guests), <code>usb-serial</code> (usable whenever USB support
7229       is available) and <code>pci-serial</code> (usable whenever PCI support
7230       is available); <span class="since">since 3.10.0</span>,
7231       <code>spapr-vio-serial</code> (usable with ppc64/pseries guests),
7232       <code>system-serial</code> (usable with aarch64/virt and,
7233       <span class="since">since 4.7.0</span>, riscv/virt guests) and
7234       <code>sclp-serial</code> (usable with s390 and s390x guests) are
7235       available as well.
7236     </p>
7237
7238     <p>
7239       <span class="since">Since 3.10.0</span>, the <code>target</code>
7240       element can have an optional <code>model</code> subelement;
7241       valid values for its <code>name</code> attribute are:
7242       <code>isa-serial</code> (usable with the <code>isa-serial</code> target
7243       type); <code>usb-serial</code> (usable with the <code>usb-serial</code>
7244       target type); <code>pci-serial</code>
7245       (usable with the <code>pci-serial</code> target type);
7246       <code>spapr-vty</code> (usable with the <code>spapr-vio-serial</code>
7247       target type); <code>pl011</code> and,
7248       <span class="since">since 4.7.0</span>, <code>16550a</code> (usable
7249       with the <code>system-serial</code> target type);
7250       <code>sclpconsole</code> and <code>sclplmconsole</code> (usable with
7251       the <code>sclp-serial</code> target type).
7252     </p>
7253
7254     <p>
7255       If any of the attributes is not specified by the user, libvirt will
7256       choose a value suitable for most users.
7257     </p>
7258
7259     <p>
7260       Most target types support configuring the guest-visible device
7261       address as <a href="#elementsAddress">documented above</a>; more
7262       specifically, acceptable address types are <code>isa</code> (for
7263       <code>isa-serial</code>), <code>usb</code> (for <code>usb-serial</code>),
7264       <code>pci</code> (for <code>pci-serial</code>) and <code>spapr-vio</code>
7265       (for <code>spapr-vio-serial</code>). The <code>system-serial</code>
7266       and <code>sclp-serial</code> target types don't support specifying an
7267       address.
7268     </p>
7269
7270     <p>
7271       For the relationship between serial ports and consoles,
7272       <a href="#elementCharSerialAndConsole">see below</a>.
7273     </p>
7274
7275     <h6><a id="elementCharConsole">Console</a></h6>
7276
7277 <pre>
7278 ...
7279 &lt;devices&gt;
7280   &lt;!-- Serial console --&gt;
7281   &lt;console type='pty'&gt;
7282     &lt;source path='/dev/pts/2'/&gt;
7283    &lt;target type='serial' port='0'/&gt;
7284   &lt;/console&gt;
7285 &lt;/devices&gt;
7286 ...</pre>
7287
7288 <pre>
7289 ...
7290 &lt;devices&gt;
7291   &lt;!-- KVM virtio console --&gt;
7292   &lt;console type='pty'&gt;
7293     &lt;source path='/dev/pts/5'/&gt;
7294     &lt;target type='virtio' port='0'/&gt;
7295   &lt;/console&gt;
7296 &lt;/devices&gt;
7297 ...</pre>
7298
7299     <p>
7300       The <code>console</code> element is used to represent interactive
7301       serial consoles. Depending on the type of guest in use and the specifics
7302       of the configuration, the <code>console</code> element might represent
7303       the same device as an existing <code>serial</code> element or a separate
7304       device.
7305     </p>
7306
7307     <p>
7308       A <code>target</code> subelement is supported and works the same
7309       way as with the <code>serial</code> element
7310       (<a href="#elementCharSerial">see above</a> for details).
7311       Valid values for the <code>type</code> attribute are:
7312       <code>serial</code> (described below);
7313       <code>virtio</code> (usable whenever VirtIO support is available);
7314       <code>xen</code>, <code>lxc</code> and <code>openvz</code>
7315       (available when the corresponding hypervisor is in use).
7316       <code>sclp</code> and <code>sclplm</code> (usable for s390 and
7317       s390x QEMU guests) are supported for compatibility reasons but should
7318       not be used for new guests: use the <code>sclpconsole</code> and
7319       <code>sclplmconsole</code> target models, respectively, with the
7320       <code>serial</code> element instead.
7321     </p>
7322
7323     <p>
7324       Of the target types listed above, <code>serial</code> is special in
7325       that it doesn't represents a separate device, but rather the same
7326       device as the first <code>serial</code> element. Due to this, there can
7327       only be a single <code>console</code> element with target type
7328       <code>serial</code> per guest.
7329     </p>
7330
7331     <p>
7332       Virtio consoles are usually accessible as <code>/dev/hvc[0-7]</code>
7333       from inside the guest; for more information, see
7334       <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>.
7335       <span class="since">Since 0.8.3</span>
7336     </p>
7337
7338     <p>
7339       For the relationship between serial ports and consoles,
7340       <a href="#elementCharSerialAndConsole">see below</a>.
7341     </p>
7342
7343     <h6><a id="elementCharSerialAndConsole">Relationship between serial ports and consoles</a></h6>
7344
7345     <p>
7346       Due to hystorical reasons, the <code>serial</code> and
7347       <code>console</code> elements have partially overlapping scopes.
7348     </p>
7349
7350     <p>
7351       In general, both elements are used to configure one or more serial
7352       consoles to be used for interacting with the guest. The main difference
7353       between the two is that <code>serial</code> is used for emulated,
7354       usually native, serial consoles, whereas <code>console</code> is used
7355       for paravirtualized ones.
7356     </p>
7357
7358     <p>
7359       Both emulated and paravirtualized serial consoles have advantages and
7360       disadvantages:
7361     </p>
7362
7363     <ul>
7364       <li>
7365         emulated serial consoles are usually initialized much earlier than
7366         paravirtualized ones, so they can be used to control the bootloader
7367         and display both firmware and early boot messages;
7368       </li>
7369       <li>
7370         on several platforms, there can only be a single emulated serial
7371         console per guest but paravirtualized consoles don't suffer from the
7372         same limitation.
7373       </li>
7374     </ul>
7375
7376     <p>
7377       A configuration such as:
7378     </p>
7379
7380 <pre>
7381 ...
7382 &lt;devices&gt;
7383   &lt;console type='pty'&gt;
7384     &lt;target type='serial'/&gt;
7385   &lt;/console&gt;
7386   &lt;console type='pty'&gt;
7387     &lt;target type='virtio'/&gt;
7388   &lt;/console&gt;
7389 &lt;/devices&gt;
7390 ...</pre>
7391
7392     <p>
7393       will work on any platform and will result in one emulated serial console
7394       for early boot logging / interactive / recovery use, and one
7395       paravirtualized serial console to be used eg. as a side channel. Most
7396       people will be fine with having just the first <code>console</code>
7397       element in their configuration.
7398     </p>
7399
7400     <p>
7401       Note that, due to the compatibility concerns mentioned earlier, all the
7402       following configurations:
7403     </p>
7404
7405 <pre>
7406 ...
7407 &lt;devices&gt;
7408   &lt;serial type='pty'/&gt;
7409 &lt;/devices&gt;
7410 ...</pre>
7411
7412 <pre>
7413 ...
7414 &lt;devices&gt;
7415   &lt;console type='pty'/&gt;
7416 &lt;/devices&gt;
7417 ...</pre>
7418
7419 <pre>
7420 ...
7421 &lt;devices&gt;
7422   &lt;serial type='pty'/&gt;
7423   &lt;console type='pty'/&gt;
7424 &lt;/devices&gt;
7425 ...</pre>
7426
7427     <p>
7428       will be treated the same and will result in a single emulated serial
7429       console being available to the guest.
7430     </p>
7431
7432     <h6><a id="elementCharChannel">Channel</a></h6>
7433
7434     <p>
7435       This represents a private communication channel between the host and the
7436       guest.
7437     </p>
7438
7439 <pre>
7440 ...
7441 &lt;devices&gt;
7442   &lt;channel type='unix'&gt;
7443     &lt;source mode='bind' path='/tmp/guestfwd'/&gt;
7444     &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
7445   &lt;/channel&gt;
7446
7447   &lt;!-- KVM virtio channel --&gt;
7448   &lt;channel type='pty'&gt;
7449     &lt;target type='virtio' name='arbitrary.virtio.serial.port.name'/&gt;
7450   &lt;/channel&gt;
7451   &lt;channel type='unix'&gt;
7452     &lt;source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/&gt;
7453     &lt;target type='virtio' name='org.qemu.guest_agent.0' state='connected'/&gt;
7454   &lt;/channel&gt;
7455   &lt;channel type='spicevmc'&gt;
7456     &lt;target type='virtio' name='com.redhat.spice.0'/&gt;
7457   &lt;/channel&gt;
7458 &lt;/devices&gt;
7459 ...</pre>
7460
7461     <p>
7462       This can be implemented in a variety of ways. The specific type of
7463       channel is given in the <code>type</code> attribute of the
7464       <code>target</code> element. Different channel types have different
7465       <code>target</code> attributes.
7466     </p>
7467
7468     <dl>
7469       <dt><code>guestfwd</code></dt>
7470       <dd>TCP traffic sent by the guest to a given IP address and port is
7471         forwarded to the channel device on the host. The <code>target</code>
7472         element must have <code>address</code> and <code>port</code> attributes.
7473         <span class="since">Since 0.7.3</span></dd>
7474
7475       <dt><code>virtio</code></dt>
7476       <dd>Paravirtualized virtio channel. Channel is exposed in the guest under
7477         /dev/vport*, and if the optional element <code>name</code> is specified,
7478         /dev/virtio-ports/$name (for more info, please see
7479         <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>). The
7480         optional element <code>address</code> can tie the channel to a
7481         particular <code>type='virtio-serial'</code>
7482         controller, <a href="#elementsAddress">documented above</a>.
7483         With qemu, if <code>name</code> is "org.qemu.guest_agent.0",
7484         then libvirt can interact with a guest agent installed in the
7485         guest, for actions such as guest shutdown or file system quiescing.
7486         <span class="since">Since 0.7.7, guest agent interaction
7487         since 0.9.10</span> Moreover, <span class="since">since 1.0.6</span>
7488         it is possible to have source path auto generated for virtio unix channels.
7489         This is very useful in case of a qemu guest agent, where users don't
7490         usually care about the source path since it's libvirt who talks to
7491         the guest agent. In case users want to utilize this feature, they should
7492         leave <code>&lt;source&gt;</code> element out. <span class="since">Since
7493         1.2.11</span> the active XML for a virtio channel may contain an optional
7494         <code>state</code> attribute that reflects whether a process in the
7495         guest is active on the channel. This is an output-only attribute.
7496         Possible values for the <code>state</code> attribute are
7497         <code>connected</code> and <code>disconnected</code>.
7498       </dd>
7499       <dt><code>xen</code></dt>
7500       <dd> Paravirtualized Xen channel. Channel is exposed in the guest as a
7501         Xen console but identified with a name. Setup and consumption of a Xen
7502         channel depends on software and configuration in the guest
7503         (for more info, please see <a href="http://xenbits.xen.org/docs/unstable/misc/channel.txt">http://xenbits.xen.org/docs/unstable/misc/channel.txt</a>).
7504         Channel source path semantics are the same as the virtio target type.
7505         The <code>state</code> attribute is not supported since Xen channels
7506         lack the necessary probing mechanism.
7507         <span class="since">Since 2.3.0</span>
7508       </dd>
7509       <dt><code>spicevmc</code></dt>
7510       <dd>Paravirtualized SPICE channel. The domain must also have a
7511         SPICE server as a <a href="#elementsGraphics">graphics
7512         device</a>, at which point the host piggy-backs messages
7513         across the <code>main</code> channel.  The <code>target</code>
7514         element must be present, with
7515         attribute <code>type='virtio'</code>; an optional
7516         attribute <code>name</code> controls how the guest will have
7517         access to the channel, and defaults
7518         to <code>name='com.redhat.spice.0'</code>.  The
7519         optional <code>address</code> element can tie the channel to a
7520         particular <code>type='virtio-serial'</code> controller.
7521         <span class="since">Since 0.8.8</span></dd>
7522     </dl>
7523
7524     <h5><a id="elementsCharHostInterface">Host interface</a></h5>
7525
7526     <p>
7527       A character device presents itself to the host as one of the following
7528       types.
7529     </p>
7530
7531     <h6><a id="elementsCharSTDIO">Domain logfile</a></h6>
7532
7533     <p>
7534       This disables all input on the character device, and sends output
7535       into the virtual machine's logfile
7536     </p>
7537
7538 <pre>
7539 ...
7540 &lt;devices&gt;
7541   &lt;console type='stdio'&gt;
7542     &lt;target port='1'/&gt;
7543   &lt;/console&gt;
7544 &lt;/devices&gt;
7545 ...</pre>
7546
7547
7548     <h6><a id="elementsCharFle">Device logfile</a></h6>
7549
7550     <p>
7551       A file is opened and all data sent to the character
7552       device is written to the file.
7553     </p>
7554
7555 <pre>
7556 ...
7557 &lt;devices&gt;
7558   &lt;serial type="file"&gt;
7559     &lt;source path="/var/log/vm/vm-serial.log"/&gt;
7560     &lt;target port="1"/&gt;
7561   &lt;/serial&gt;
7562 &lt;/devices&gt;
7563 ...</pre>
7564
7565     <h6><a id="elementsCharVC">Virtual console</a></h6>
7566
7567     <p>
7568       Connects the character device to the graphical framebuffer in
7569       a virtual console. This is typically accessed via a special
7570       hotkey sequence such as "ctrl+alt+3"
7571     </p>
7572
7573 <pre>
7574 ...
7575 &lt;devices&gt;
7576   &lt;serial type='vc'&gt;
7577     &lt;target port="1"/&gt;
7578   &lt;/serial&gt;
7579 &lt;/devices&gt;
7580 ...</pre>
7581
7582     <h6><a id="elementsCharNull">Null device</a></h6>
7583
7584     <p>
7585       Connects the character device to the void. No data is ever
7586       provided to the input. All data written is discarded.
7587     </p>
7588
7589 <pre>
7590 ...
7591 &lt;devices&gt;
7592   &lt;serial type='null'&gt;
7593     &lt;target port="1"/&gt;
7594   &lt;/serial&gt;
7595 &lt;/devices&gt;
7596 ...</pre>
7597
7598     <h6><a id="elementsCharPTY">Pseudo TTY</a></h6>
7599
7600     <p>
7601       A Pseudo TTY is allocated using /dev/ptmx. A suitable client
7602       such as 'virsh console' can connect to interact with the
7603       serial port locally.
7604     </p>
7605
7606 <pre>
7607 ...
7608 &lt;devices&gt;
7609   &lt;serial type="pty"&gt;
7610     &lt;source path="/dev/pts/3"/&gt;
7611     &lt;target port="1"/&gt;
7612   &lt;/serial&gt;
7613 &lt;/devices&gt;
7614 ...</pre>
7615
7616     <p>
7617       NB special case if &lt;console type='pty'&gt;, then the TTY
7618       path is also duplicated as an attribute tty='/dev/pts/3'
7619       on the top level &lt;console&gt; tag. This provides compat
7620       with existing syntax for &lt;console&gt; tags.
7621     </p>
7622
7623     <h6><a id="elementsCharHost">Host device proxy</a></h6>
7624
7625     <p>
7626       The character device is passed through to the underlying
7627       physical character device. The device types must match,
7628       eg the emulated serial port should only be connected to
7629       a host serial port - don't connect a serial port to a parallel
7630       port.
7631     </p>
7632
7633 <pre>
7634 ...
7635 &lt;devices&gt;
7636   &lt;serial type="dev"&gt;
7637     &lt;source path="/dev/ttyS0"/&gt;
7638     &lt;target port="1"/&gt;
7639   &lt;/serial&gt;
7640 &lt;/devices&gt;
7641 ...</pre>
7642
7643     <h6><a id="elementsCharPipe">Named pipe</a></h6>
7644
7645     <p>
7646       The character device writes output to a named pipe. See pipe(7) for
7647       more info.
7648     </p>
7649
7650 <pre>
7651 ...
7652 &lt;devices&gt;
7653   &lt;serial type="pipe"&gt;
7654     &lt;source path="/tmp/mypipe"/&gt;
7655     &lt;target port="1"/&gt;
7656   &lt;/serial&gt;
7657 &lt;/devices&gt;
7658 ...</pre>
7659
7660     <h6><a id="elementsCharTCP">TCP client/server</a></h6>
7661
7662     <p>
7663       The character device acts as a TCP client connecting to a
7664       remote server.
7665     </p>
7666
7667 <pre>
7668 ...
7669 &lt;devices&gt;
7670   &lt;serial type="tcp"&gt;
7671     &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
7672     &lt;protocol type="raw"/&gt;
7673     &lt;target port="1"/&gt;
7674   &lt;/serial&gt;
7675 &lt;/devices&gt;
7676  ...</pre>
7677
7678     <p>
7679       Or as a TCP server waiting for a client connection.
7680     </p>
7681
7682 <pre>
7683 ...
7684 &lt;devices&gt;
7685   &lt;serial type="tcp"&gt;
7686     &lt;source mode="bind" host="127.0.0.1" service="2445"/&gt;
7687     &lt;protocol type="raw"/&gt;
7688     &lt;target port="1"/&gt;
7689   &lt;/serial&gt;
7690 &lt;/devices&gt;
7691 ...</pre>
7692
7693     <p>
7694       Alternatively you can use <code>telnet</code> instead
7695       of <code>raw</code> TCP in order to utilize the telnet protocol
7696       for the connection.
7697     </p>
7698     <p>
7699       <span class="since">Since 0.8.5,</span> some hypervisors support
7700       use of either <code>telnets</code> (secure telnet) or <code>tls</code>
7701       (via secure sockets layer) as the transport protocol for connections.
7702     </p>
7703
7704 <pre>
7705 ...
7706 &lt;devices&gt;
7707   &lt;serial type="tcp"&gt;
7708     &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
7709     &lt;protocol type="telnet"/&gt;
7710     &lt;target port="1"/&gt;
7711   &lt;/serial&gt;
7712   ...
7713   &lt;serial type="tcp"&gt;
7714     &lt;source mode="bind" host="127.0.0.1" service="2445"/&gt;
7715     &lt;protocol type="telnet"/&gt;
7716     &lt;target port="1"/&gt;
7717   &lt;/serial&gt;
7718 &lt;/devices&gt;
7719 ...</pre>
7720
7721     <p>
7722       <span class="since">Since 2.4.0,</span> the optional attribute
7723       <code>tls</code> can be used to control whether a chardev
7724       TCP communication channel would utilize a hypervisor configured
7725       TLS X.509 certificate environment in order to encrypt the data
7726       channel. For the QEMU hypervisor, usage of a TLS environment can
7727       be controlled on the host by the <code>chardev_tls</code> and
7728       <code>chardev_tls_x509_cert_dir</code> or
7729       <code>default_tls_x509_cert_dir</code> settings in the file
7730       /etc/libvirt/qemu.conf. If <code>chardev_tls</code> is enabled,
7731       then unless the <code>tls</code> attribute is set to "no", libvirt
7732       will use the host configured TLS environment.
7733       If <code>chardev_tls</code> is disabled, but the <code>tls</code>
7734       attribute is set to "yes", then libvirt will attempt to use the
7735       host TLS environment if either the <code>chardev_tls_x509_cert_dir</code>
7736       or <code>default_tls_x509_cert_dir</code> TLS directory structure exists.
7737     </p>
7738 <pre>
7739 ...
7740 &lt;devices&gt;
7741   &lt;serial type="tcp"&gt;
7742     &lt;source mode='connect' host="127.0.0.1" service="5555" tls="yes"/&gt;
7743     &lt;protocol type="raw"/&gt;
7744     &lt;target port="0"/&gt;
7745   &lt;/serial&gt;
7746 &lt;/devices&gt;
7747 ...</pre>
7748
7749     <h6><a id="elementsCharUDP">UDP network console</a></h6>
7750
7751     <p>
7752       The character device acts as a UDP netconsole service,
7753       sending and receiving packets. This is a lossy service.
7754     </p>
7755
7756 <pre>
7757 ...
7758 &lt;devices&gt;
7759   &lt;serial type="udp"&gt;
7760     &lt;source mode="bind" host="0.0.0.0" service="2445"/&gt;
7761     &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
7762     &lt;target port="1"/&gt;
7763   &lt;/serial&gt;
7764 &lt;/devices&gt;
7765 ...</pre>
7766
7767     <h6><a id="elementsCharUNIX">UNIX domain socket client/server</a></h6>
7768
7769     <p>
7770       The character device acts as a UNIX domain socket server,
7771       accepting connections from local clients.
7772     </p>
7773
7774 <pre>
7775 ...
7776 &lt;devices&gt;
7777   &lt;serial type="unix"&gt;
7778     &lt;source mode="bind" path="/tmp/foo"/&gt;
7779     &lt;target port="1"/&gt;
7780   &lt;/serial&gt;
7781 &lt;/devices&gt;
7782 ...</pre>
7783
7784     <h6><a id="elementsCharSpiceport">Spice channel</a></h6>
7785
7786     <p>
7787       The character device is accessible through spice connection
7788       under a channel name specified in the <code>channel</code>
7789       attribute.  <span class="since">Since 1.2.2</span>
7790     </p>
7791     <p>
7792       Note: depending on the hypervisor, spiceports might (or might not)
7793       be enabled on domains with or without <a href="#elementsGraphics">spice
7794       graphics</a>.
7795     </p>
7796
7797 <pre>
7798 ...
7799 &lt;devices&gt;
7800   &lt;serial type="spiceport"&gt;
7801     &lt;source channel="org.qemu.console.serial.0"/&gt;
7802     &lt;target port="1"/&gt;
7803   &lt;/serial&gt;
7804 &lt;/devices&gt;
7805 ...</pre>
7806
7807     <h6><a id="elementsNmdm">Nmdm device</a></h6>
7808
7809     <p>
7810       The nmdm device driver, available on FreeBSD, provides two
7811       tty devices connected together by a virtual null modem cable.
7812       <span class="since">Since 1.2.4</span>
7813     </p>
7814
7815 <pre>
7816 ...
7817 &lt;devices&gt;
7818   &lt;serial type="nmdm"&gt;
7819     &lt;source master="/dev/nmdm0A" slave="/dev/nmdm0B"/&gt;
7820   &lt;/serial&gt;
7821 &lt;/devices&gt;
7822 ...</pre>
7823
7824     <p>
7825       The <code>source</code> element has these attributes:
7826     </p>
7827
7828     <dl>
7829       <dt><code>master</code></dt>
7830       <dd>Master device of the pair, that is passed to the hypervisor.
7831       Device is specified by a fully qualified path.</dd>
7832
7833       <dt><code>slave</code></dt>
7834       <dd>Slave device of the pair, that is passed to the clients for connection
7835       to the guest console. Device is specified by a fully qualified path.</dd>
7836     </dl>
7837
7838     <h4><a id="elementsSound">Sound devices</a></h4>
7839
7840     <p>
7841       A virtual sound card can be attached to the host via the
7842       <code>sound</code> element. <span class="since">Since 0.4.3</span>
7843     </p>
7844
7845 <pre>
7846 ...
7847 &lt;devices&gt;
7848   &lt;sound model='es1370'/&gt;
7849 &lt;/devices&gt;
7850 ...</pre>
7851
7852     <dl>
7853       <dt><code>sound</code></dt>
7854       <dd>
7855         The <code>sound</code> element has one mandatory attribute,
7856         <code>model</code>, which specifies what real sound device is emulated.
7857         Valid values are specific to the underlying hypervisor, though typical
7858         choices are 'es1370', 'sb16', 'ac97', 'ich6' and 'usb'.
7859         (<span class="since">
7860          'ac97' only since 0.6.0, 'ich6' only since 0.8.8,
7861          'usb' only since 1.2.7</span>)
7862       </dd>
7863     </dl>
7864
7865     <p>
7866       <span class="since">Since 0.9.13</span>, a sound element
7867       with <code>ich6</code> model can have optional
7868       sub-elements <code>&lt;codec&gt;</code> to attach various audio
7869       codecs to the audio device. If not specified, a default codec
7870       will be attached to allow playback and recording.
7871       </p>
7872       <p>
7873       Valid values are:
7874       </p>
7875       <p>
7876       <ul>
7877         <li>'duplex' - advertise a line-in and a line-out </li>
7878         <li>'micro' -  advertise a speaker and a microphone </li>
7879         <li>'output' - advertise a line-out
7880             <span class="since">Since 4.4.0</span></li>
7881       </ul>
7882     </p>
7883
7884 <pre>
7885 ...
7886 &lt;devices&gt;
7887   &lt;sound model='ich6'&gt;
7888     &lt;codec type='micro'/&gt;
7889   &lt;/sound&gt;
7890 &lt;/devices&gt;
7891 ...</pre>
7892
7893     <p>
7894       Each <code>sound</code> element has an optional
7895       sub-element <code>&lt;address&gt;</code> which can tie the
7896       device to a particular PCI
7897       slot, <a href="#elementsAddress">documented above</a>.
7898     </p>
7899
7900     <h4><a id="elementsWatchdog">Watchdog device</a></h4>
7901
7902     <p>
7903       A virtual hardware watchdog device can be added to the guest via
7904       the <code>watchdog</code> element.
7905       <span class="since">Since 0.7.3, QEMU and KVM only</span>
7906     </p>
7907
7908     <p>
7909       The watchdog device requires an additional driver and management
7910       daemon in the guest.  Just enabling the watchdog in the libvirt
7911       configuration does not do anything useful on its own.
7912     </p>
7913
7914     <p>
7915       Currently libvirt does not support notification when the
7916       watchdog fires.  This feature is planned for a future version of
7917       libvirt.
7918     </p>
7919
7920 <pre>
7921 ...
7922 &lt;devices&gt;
7923   &lt;watchdog model='i6300esb'/&gt;
7924 &lt;/devices&gt;
7925 ...</pre>
7926
7927 <pre>
7928   ...
7929   &lt;devices&gt;
7930     &lt;watchdog model='i6300esb' action='poweroff'/&gt;
7931   &lt;/devices&gt;
7932 &lt;/domain&gt;</pre>
7933
7934     <dl>
7935       <dt><code>model</code></dt>
7936       <dd>
7937         <p>
7938         The required <code>model</code> attribute specifies what real
7939         watchdog device is emulated.  Valid values are specific to the
7940         underlying hypervisor.
7941         </p>
7942         <p>
7943         QEMU and KVM support:
7944         </p>
7945         <ul>
7946           <li>'i6300esb' - the recommended device,
7947             emulating a PCI Intel 6300ESB </li>
7948           <li>'ib700' - emulating an ISA iBase IB700 </li>
7949           <li>'diag288' - emulating an S390 DIAG288 device
7950             <span class="since">Since 1.2.17</span></li>
7951         </ul>
7952       </dd>
7953       <dt><code>action</code></dt>
7954       <dd>
7955         <p>
7956         The optional <code>action</code> attribute describes what
7957         action to take when the watchdog expires.  Valid values are
7958         specific to the underlying hypervisor.
7959         </p>
7960         <p>
7961         QEMU and KVM support:
7962         </p>
7963         <ul>
7964           <li>'reset' - default, forcefully reset the guest</li>
7965           <li>'shutdown' - gracefully shutdown the guest
7966             (not recommended) </li>
7967           <li>'poweroff' - forcefully power off the guest</li>
7968           <li>'pause' - pause the guest</li>
7969           <li>'none' - do nothing</li>
7970           <li>'dump' - automatically dump the guest
7971             <span class="since">Since 0.8.7</span></li>
7972           <li>'inject-nmi' - inject a non-maskable interrupt
7973             into the guest
7974             <span class="since">Since 1.2.17</span></li>
7975         </ul>
7976         <p>
7977         Note 1: the 'shutdown' action requires that the guest
7978         is responsive to ACPI signals.  In the sort of situations
7979         where the watchdog has expired, guests are usually unable
7980         to respond to ACPI signals.  Therefore using 'shutdown'
7981         is not recommended.
7982         </p>
7983         <p>
7984         Note 2: the directory to save dump files can be configured
7985         by <code>auto_dump_path</code> in file /etc/libvirt/qemu.conf.
7986         </p>
7987       </dd>
7988     </dl>
7989
7990     <h4><a id="elementsMemBalloon">Memory balloon device</a></h4>
7991
7992     <p>
7993       A virtual memory balloon device is added to all Xen and KVM/QEMU
7994       guests. It will be seen as <code>memballoon</code> element.
7995       It will be automatically added when appropriate, so there is no
7996       need to explicitly add this element in the guest XML unless a
7997       specific PCI slot needs to be assigned.
7998       <span class="since">Since 0.8.3, Xen, QEMU and KVM only</span>
7999       Additionally, <span class="since">since 0.8.4</span>, if the
8000       memballoon device needs to be explicitly disabled,
8001       <code>model='none'</code> may be used.
8002     </p>
8003
8004     <p>
8005       Example: automatically added device with KVM
8006     </p>
8007 <pre>
8008 ...
8009 &lt;devices&gt;
8010   &lt;memballoon model='virtio'/&gt;
8011 &lt;/devices&gt;
8012 ...</pre>
8013
8014     <p>
8015       Example: manually added device with static PCI slot 2 requested
8016     </p>
8017 <pre>
8018   ...
8019   &lt;devices&gt;
8020     &lt;memballoon model='virtio'&gt;
8021       &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/&gt;
8022       &lt;stats period='10'/&gt;
8023       &lt;driver iommu='on' ats='on'/&gt;
8024     &lt;/memballoon&gt;
8025   &lt;/devices&gt;
8026 &lt;/domain&gt;</pre>
8027
8028     <dl>
8029       <dt><code>model</code></dt>
8030       <dd>
8031         <p>
8032           The required <code>model</code> attribute specifies what type
8033           of balloon device is provided. Valid values are specific to
8034           the virtualization platform
8035         </p>
8036         <ul>
8037           <li>'virtio' - default with QEMU/KVM</li>
8038           <li>'virtio-transitional' <span class="since">Since 5.2.0</span></li>
8039           <li>'virtio-non-transitional' <span class="since">Since 5.2.0</span></li>
8040           <li>'xen' - default with Xen</li>
8041         </ul>
8042         See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
8043         for more details.
8044       </dd>
8045       <dt><code>autodeflate</code></dt>
8046       <dd>
8047         <p>
8048           The optional <code>autodeflate</code> attribute allows to
8049           enable/disable (values "on"/"off", respectively) the ability of the
8050           QEMU virtio memory balloon to release some memory at the last moment
8051           before a guest's process get killed by Out of Memory killer.
8052           <span class="since">Since 1.3.1, QEMU and KVM only</span>
8053         </p>
8054       </dd>
8055       <dt><code>period</code></dt>
8056       <dd>
8057         <p>
8058           The optional <code>period</code> allows the QEMU virtio memory balloon
8059           driver to provide statistics through the <code>virsh dommemstat
8060           [domain]</code> command. By default, collection is not enabled. In
8061           order to enable, use the <code>virsh dommemstat [domain] --period
8062           [number]</code> command or <code>virsh edit</code> command to add the
8063           option to the XML definition.  The <code>virsh dommemstat</code> will
8064           accept the options <code>--live</code>, <code>--current</code>,
8065           or <code>--config</code>.  If an option is not provided, the change
8066           for a running domain will only be made to the active guest.  If the
8067           QEMU driver is not at the right revision, the attempt to set the
8068           period will fail.  Large values (e.g. many years) might be ignored.
8069           <span class='since'>Since 1.1.1, requires QEMU 1.5</span>
8070         </p>
8071       </dd>
8072       <dt><code>driver</code></dt>
8073       <dd>
8074         For model <code>virtio</code> memballoon,
8075         <a href="#elementsVirtio">Virtio-specific options</a> can also be
8076         set. (<span class="since">Since 3.5.0</span>)
8077       </dd>
8078     </dl>
8079     <h4><a id="elementsRng">Random number generator device</a></h4>
8080
8081     <p>
8082       The virtual random number generator device allows the host to pass
8083       through entropy to guest operating systems.
8084       <span class="since">Since 1.0.3</span>
8085     </p>
8086
8087     <p>
8088       Example: usage of the RNG device:
8089     </p>
8090 <pre>
8091 ...
8092 &lt;devices&gt;
8093   &lt;rng model='virtio'&gt;
8094     &lt;rate period="2000" bytes="1234"/&gt;
8095     &lt;backend model='random'&gt;/dev/random&lt;/backend&gt;
8096     &lt;!-- OR --&gt;
8097     &lt;backend model='egd' type='udp'&gt;
8098       &lt;source mode='bind' service='1234'/&gt;
8099       &lt;source mode='connect' host='1.2.3.4' service='1234'/&gt;
8100     &lt;/backend&gt;
8101   &lt;/rng&gt;
8102 &lt;/devices&gt;
8103 ...
8104 </pre>
8105     <dl>
8106       <dt><code>model</code></dt>
8107       <dd>
8108         <p>
8109           The required <code>model</code> attribute specifies what type
8110           of RNG device is provided. Valid values are specific to
8111           the virtualization platform:
8112         </p>
8113         <ul>
8114           <li>'virtio' - supported by qemu and virtio-rng kernel module</li>
8115           <li>'virtio-transitional' <span class='since'>Since 5.2.0</span></li>
8116           <li>'virtio-non-transitional' <span class='since'>Since 5.2.0</span></li>
8117         </ul>
8118         See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
8119         for more details.
8120       </dd>
8121       <dt><code>rate</code></dt>
8122       <dd>
8123         <p>
8124           The optional <code>rate</code> element allows limiting the rate at
8125           which entropy can be consumed from the source.  The mandatory
8126           attribute <code>bytes</code> specifies how many bytes are permitted
8127           to be consumed per period.  An optional <code>period</code> attribute
8128           specifies the duration of a period in milliseconds; if omitted, the
8129           period is taken as 1000 milliseconds (1 second).
8130           <span class='since'>Since 1.0.4</span>
8131         </p>
8132       </dd>
8133       <dt><code>backend</code></dt>
8134       <dd>
8135         <p>
8136           The <code>backend</code> element specifies the source of entropy
8137           to be used for the domain. The source model is configured using the
8138           <code>model</code> attribute. Supported source models are:
8139         </p>
8140         <dl>
8141           <dt><code>random</code></dt>
8142           <dd>
8143             <p>
8144               This backend type expects a non-blocking character device
8145               as input. The file name is specified as contents of the
8146               <code>backend</code> element. <span class='since'>Since
8147               1.3.4</span> any path is accepted. Before that
8148               <code>/dev/random</code> and <code>/dev/hwrng</code> were
8149               the only accepted paths. When no file name is specified,
8150               the hypervisor default is used. For QEMU, the default is
8151               <code>/dev/random</code>. However, the recommended source
8152               of entropy is <code>/dev/urandom</code> (as it doesn't
8153               have the limitations of <code>/dev/random</code>).
8154             </p>
8155           </dd>
8156           <dt><code>egd</code></dt>
8157           <dd>
8158             <p>
8159               This backend connects to a source using the EGD protocol.
8160               The source is specified as a character device. Refer to
8161               <a href='#elementsCharHostInterface'>character device host interface</a>
8162               for more information.
8163             </p>
8164           </dd>
8165         </dl>
8166       </dd>
8167       <dt><code>driver</code></dt>
8168       <dd>
8169         The subelement <code>driver</code> can be used to tune the device:
8170         <dl>
8171           <dt>virtio options</dt>
8172           <dd>
8173           <a href="#elementsVirtio">Virtio-specific options</a> can also be
8174           set. (<span class="since">Since 3.5.0</span>)
8175           </dd>
8176         </dl>
8177       </dd>
8178
8179     </dl>
8180
8181     <h4><a id="elementsTpm">TPM device</a></h4>
8182
8183     <p>
8184       The TPM device enables a QEMU guest to have access to TPM
8185       functionality. The TPM device may either be a TPM 1.2 or
8186       a TPM 2.0.
8187     </p>
8188     <p>
8189       The TPM passthrough device type provides access to the host's TPM
8190       for one QEMU guest. No other software may be using the TPM device,
8191       typically /dev/tpm0, at the time the QEMU guest is started.
8192       <span class="since">'passthrough' since 1.0.5</span>
8193     </p>
8194
8195     <p>
8196      Example: usage of the TPM passthrough device
8197     </p>
8198 <pre>
8199 ...
8200 &lt;devices&gt;
8201   &lt;tpm model='tpm-tis'&gt;
8202     &lt;backend type='passthrough'&gt;
8203       &lt;device path='/dev/tpm0'/&gt;
8204     &lt;/backend&gt;
8205   &lt;/tpm&gt;
8206 &lt;/devices&gt;
8207 ...
8208 </pre>
8209
8210     <p>
8211       The emulator device type gives access to a TPM emulator providing
8212       TPM functionality for each VM. QEMU talks to it over a Unix socket. With
8213       the emulator device type each guest gets its own private TPM.
8214       <span class="since">'emulator' since 4.5.0</span>
8215     </p>
8216     <p>
8217      Example: usage of the TPM Emulator
8218     </p>
8219 <pre>
8220   ...
8221   &lt;devices&gt;
8222     &lt;tpm model='tpm-tis'&gt;
8223       &lt;backend type='emulator' version='2.0'&gt;
8224       &lt;/backend&gt;
8225     &lt;/tpm&gt;
8226   &lt;/devices&gt;
8227   ...
8228 </pre>
8229     <dl>
8230       <dt><code>model</code></dt>
8231       <dd>
8232         <p>
8233           The <code>model</code> attribute specifies what device
8234           model QEMU provides to the guest. If no model name is provided,
8235           <code>tpm-tis</code> will automatically be chosen.
8236           <span class="since">Since 4.4.0</span>, another available choice
8237           is the <code>tpm-crb</code>, which should only be used when the
8238           backend device is a TPM 2.0.
8239         </p>
8240       </dd>
8241       <dt><code>backend</code></dt>
8242       <dd>
8243         <p>
8244           The <code>backend</code> element specifies the type of
8245           TPM device. The following types are supported:
8246         </p>
8247         <dl>
8248           <dt><code>passthrough</code></dt>
8249           <dd>
8250             <p>
8251               Use the host's TPM device.
8252             </p>
8253             <p>
8254               This backend type requires exclusive access to a TPM device on
8255               the host. An example for such a device is /dev/tpm0. The fully
8256               qualified file name is specified by path attribute of the
8257               <code>source</code> element. If no file name is specified then
8258               /dev/tpm0 is automatically used.
8259             </p>
8260           </dd>
8261         </dl>
8262         <dl>
8263           <dt><code>emulator</code></dt>
8264           <dd>
8265             <p>
8266               For this backend type the 'swtpm' TPM Emulator must be installed on the
8267               host. Libvirt will automatically start an independent TPM emulator
8268               for each QEMU guest requesting access to it.
8269             </p>
8270           </dd>
8271         </dl>
8272       </dd>
8273       <dt><code>version</code></dt>
8274       <dd>
8275         <p>
8276           The <code>version</code> attribute indicates the version
8277           of the TPM. By default a TPM 1.2 is created. This attribute
8278           only works with the <code>emulator</code> backend. The following
8279           versions are supported:
8280         </p>
8281         <ul>
8282           <li>'1.2' : creates a TPM 1.2</li>
8283           <li>'2.0' : creates a TPM 2.0</li>
8284         </ul>
8285       </dd>
8286     </dl>
8287
8288     <h4><a id="elementsNVRAM">NVRAM device</a></h4>
8289     <p>
8290       nvram device is always added to pSeries guest on PPC64, and its address
8291       is allowed to be changed.  Element <code>nvram</code> (only valid for
8292       pSeries guest, <span class="since">since 1.0.5</span>) is provided to
8293       enable the address setting.
8294     </p>
8295     <p>
8296       Example: usage of NVRAM configuration
8297     </p>
8298 <pre>
8299 ...
8300 &lt;devices&gt;
8301   &lt;nvram&gt;
8302     &lt;address type='spapr-vio' reg='0x00003000'/&gt;
8303   &lt;/nvram&gt;
8304 &lt;/devices&gt;
8305 ...
8306 </pre>
8307   <dl>
8308     <dt><code>spapr-vio</code></dt>
8309     <dd>
8310       <p>
8311         VIO device address type, only valid for PPC64.
8312       </p>
8313     </dd>
8314     <dt><code>reg</code></dt>
8315     <dd>
8316       <p>
8317         Device address
8318       </p>
8319     </dd>
8320   </dl>
8321
8322     <h4><a id="elementsPanic">panic device</a></h4>
8323     <p>
8324       panic device enables libvirt to receive panic notification from a QEMU
8325       guest.
8326       <span class="since">Since 1.2.1, QEMU and KVM only</span>
8327     </p>
8328     <p>
8329       This feature is always enabled for:
8330     </p>
8331     <ul>
8332       <li>pSeries guests, since it's implemented by the guest firmware</li>
8333       <li>S390 guests, since it's an integral part of the S390 architecture</li>
8334     </ul>
8335     <p>
8336       For the guest types listed above, libvirt automatically adds a
8337       <code>panic</code> element to the domain XML.
8338     </p>
8339     <p>
8340       Example: usage of panic configuration
8341     </p>
8342 <pre>
8343 ...
8344 &lt;devices&gt;
8345   &lt;panic model='hyperv'/&gt;
8346   &lt;panic model='isa'&gt;
8347     &lt;address type='isa' iobase='0x505'/&gt;
8348   &lt;/panic&gt;
8349 &lt;/devices&gt;
8350 ...
8351 </pre>
8352   <dl>
8353     <dt><code>model</code></dt>
8354       <dd>
8355         <p>
8356           The optional <code>model</code> attribute specifies what type
8357           of panic device is provided. The panic model used when this attribute
8358           is missing depends on the hypervisor and guest arch.
8359         </p>
8360         <ul>
8361           <li>'isa' - for ISA pvpanic device</li>
8362           <li>'pseries' - default and valid only for pSeries guests.</li>
8363           <li>'hyperv' - for Hyper-V crash CPU feature.
8364             <span class="since">Since 1.3.0, QEMU and KVM only</span></li>
8365           <li>'s390' - default for S390 guests.
8366             <span class="since">Since 1.3.5</span></li>
8367         </ul>
8368       </dd>
8369     <dt><code>address</code></dt>
8370     <dd>
8371       <p>
8372         address of panic. The default ioport is 0x505. Most users
8373         don't need to specify an address, and doing so is forbidden
8374         altogether for s390, pseries and hyperv models.
8375       </p>
8376     </dd>
8377   </dl>
8378
8379   <h4><a id="elementsShmem">Shared memory device</a></h4>
8380
8381     <p>
8382       A shared memory device allows to share a memory region between
8383       different virtual machines and the host.
8384       <span class="since">Since 1.2.10, QEMU and KVM only</span>
8385     </p>
8386
8387 <pre>
8388 ...
8389 &lt;devices&gt;
8390   &lt;shmem name='my_shmem0'&gt;
8391     &lt;model type='ivshmem-plain'/&gt;
8392     &lt;size unit='M'&gt;4&lt;/size&gt;
8393   &lt;/shmem&gt;
8394   &lt;shmem name='shmem_server'&gt;
8395     &lt;model type='ivshmem-doorbell'/&gt;
8396     &lt;size unit='M'&gt;2&lt;/size&gt;
8397     &lt;server path='/tmp/socket-shmem'/&gt;
8398     &lt;msi vectors='32' ioeventfd='on'/&gt;
8399   &lt;/shmem&gt;
8400 &lt;/devices&gt;
8401 ...
8402 </pre>
8403
8404   <dl>
8405     <dt><code>shmem</code></dt>
8406     <dd>
8407       The <code>shmem</code> element has one mandatory attribute,
8408       <code>name</code> to identify the shared memory. This attribute cannot
8409       be directory specific to <code>.</code> or <code>..</code> as well as
8410       it cannot involve path separator <code>/</code>.
8411     </dd>
8412     <dt><code>model</code></dt>
8413     <dd>
8414       Attribute <code>type</code> of the optional element <code>model</code>
8415       specifies the model of the underlying device providing the
8416       <code>shmem</code> device.  The models currently supported are
8417       <code>ivshmem</code> (supports both server and server-less shmem, but is
8418       deprecated by newer QEMU in favour of the -plain and -doorbell variants),
8419       <code>ivshmem-plain</code> (only for server-less shmem) and
8420       <code>ivshmem-doorbell</code> (only for shmem with the server).
8421     </dd>
8422     <dt><code>size</code></dt>
8423     <dd>
8424       The optional <code>size</code> element specifies the size of the shared
8425       memory. This must be power of 2 and greater than or equal to 1 MiB.
8426     </dd>
8427     <dt><code>server</code></dt>
8428     <dd>
8429       The optional <code>server</code> element can be used to configure a server
8430       socket the device is supposed to connect to.  The optional
8431       <code>path</code> attribute specifies the absolute path to the unix socket
8432       and defaults to <code>/var/lib/libvirt/shmem/$shmem-$name-sock</code>.
8433     </dd>
8434     <dt><code>msi</code></dt>
8435     <dd>
8436       The optional <code>msi</code> element enables/disables (values "on"/"off",
8437       respectively) MSI interrupts. This option can currently be used only
8438       together with the <code>server</code> element. The <code>vectors</code>
8439       attribute can be used to specify the number of interrupt
8440       vectors. The <code>ioeventd</code> attribute enables/disables (values
8441       "on"/"off", respectively) ioeventfd.
8442     </dd>
8443   </dl>
8444
8445     <h4><a id="elementsMemory">Memory devices</a></h4>
8446
8447     <p>
8448         In addition to the initial memory assigned to the guest, memory devices
8449         allow additional memory to be assigned to the guest in the form of
8450         memory modules.
8451
8452         A memory device can be hot-plugged or hot-unplugged depending on the
8453         guests' memory resource needs.
8454
8455         Some hypervisors may require NUMA configured for the guest.
8456     </p>
8457
8458     <p>
8459       Example: usage of the memory devices
8460     </p>
8461 <pre>
8462 ...
8463 &lt;devices&gt;
8464   &lt;memory model='dimm' access='private' discard='yes'&gt;
8465     &lt;target&gt;
8466       &lt;size unit='KiB'&gt;524287&lt;/size&gt;
8467       &lt;node&gt;0&lt;/node&gt;
8468     &lt;/target&gt;
8469   &lt;/memory&gt;
8470   &lt;memory model='dimm'&gt;
8471     &lt;source&gt;
8472       &lt;pagesize unit='KiB'&gt;4096&lt;/pagesize&gt;
8473       &lt;nodemask&gt;1-3&lt;/nodemask&gt;
8474     &lt;/source&gt;
8475     &lt;target&gt;
8476       &lt;size unit='KiB'&gt;524287&lt;/size&gt;
8477       &lt;node&gt;1&lt;/node&gt;
8478     &lt;/target&gt;
8479   &lt;/memory&gt;
8480   &lt;memory model='nvdimm'&gt;
8481     &lt;source&gt;
8482       &lt;path&gt;/tmp/nvdimm&lt;/path&gt;
8483       &lt;alignsize unit='KiB'&gt;2048&lt;/alignsize&gt;
8484     &lt;/source&gt;
8485     &lt;target&gt;
8486       &lt;size unit='KiB'&gt;524288&lt;/size&gt;
8487       &lt;node&gt;1&lt;/node&gt;
8488       &lt;label&gt;
8489         &lt;size unit='KiB'&gt;128&lt;/size&gt;
8490       &lt;/label&gt;
8491       &lt;readonly/&gt;
8492     &lt;/target&gt;
8493   &lt;/memory&gt;
8494   &lt;memory model='nvdimm'&gt;
8495     &lt;source&gt;
8496       &lt;path&gt;/dev/dax0.0&lt;/path&gt;
8497       &lt;pmem/&gt;
8498     &lt;/source&gt;
8499     &lt;target&gt;
8500       &lt;size unit='KiB'&gt;524288&lt;/size&gt;
8501       &lt;node&gt;1&lt;/node&gt;
8502       &lt;label&gt;
8503         &lt;size unit='KiB'&gt;128&lt;/size&gt;
8504       &lt;/label&gt;
8505     &lt;/target&gt;
8506   &lt;/memory&gt;
8507 &lt;/devices&gt;
8508 ...
8509 </pre>
8510     <dl>
8511       <dt><code>model</code></dt>
8512       <dd>
8513         <p>
8514           Provide <code>dimm</code> to add a virtual DIMM module to the guest.
8515           <span class="since">Since 1.2.14</span>
8516           Provide <code>nvdimm</code> model adds a Non-Volatile DIMM
8517           module. <span class="since">Since 3.2.0</span>
8518         </p>
8519       </dd>
8520
8521       <dt><code>access</code></dt>
8522       <dd>
8523         <p>
8524           An optional attribute <code>access</code>
8525           (<span class="since">since 3.2.0</span>) that provides
8526           capability to fine tune mapping of the memory on per
8527           module basis. Values are the same as
8528           <a href="#elementsMemoryBacking">Memory Backing</a>:
8529           <code>shared</code> and <code>private</code>.
8530         </p>
8531       </dd>
8532
8533       <dt><code>discard</code></dt>
8534       <dd>
8535         <p>
8536           An optional attribute <code>discard</code>
8537           (<span class="since">since 4.4.0</span>) that provides
8538           capability to fine tune discard of data on per module
8539           basis. Accepted values are <code>yes</code> and
8540           <code>no</code>. The feature is described here:
8541           <a href="#elementsMemoryBacking">Memory Backing</a>.
8542           This attribute is allowed only for
8543           <code>model='dimm'</code>.
8544         </p>
8545       </dd>
8546
8547       <dt><code>source</code></dt>
8548       <dd>
8549         <p>
8550           For model <code>dimm</code> this element is optional and allows to
8551           fine tune the source of the memory used for the given memory device.
8552           If the element is not provided defaults configured via
8553           <code>numatune</code> are used. If <code>dimm</code> is provided,
8554           then the following optional elements can be provided as well:
8555         </p>
8556
8557         <dl>
8558           <dt><code>pagesize</code></dt>
8559           <dd>
8560             <p>
8561               This element can be used to override the default
8562               host page size used for backing the memory device.
8563               The configured value must correspond to a page size
8564               supported by the host.
8565             </p>
8566           </dd>
8567
8568           <dt><code>nodemask</code></dt>
8569           <dd>
8570             <p>
8571               This element can be used to override the default
8572               set of NUMA nodes where the memory would be
8573               allocated.
8574             </p>
8575           </dd>
8576         </dl>
8577
8578         <p>
8579           For model <code>nvdimm</code> this element is mandatory. The
8580           mandatory child element <code>path</code> represents a path in
8581           the host that backs the nvdimm module in the guest. The following
8582           optional elements may be used:
8583         </p>
8584
8585         <dl>
8586           <dt><code>alignsize</code></dt>
8587           <dd>
8588             <p>
8589               The <code>alignsize</code> element defines the page size
8590               alignment used to mmap the address range for the backend
8591               <code>path</code>. If not supplied the host page size is used.
8592               For example, to mmap a real NVDIMM device a 2M-aligned page may
8593               be required.
8594               <span class="since">Since 5.0.0</span>
8595             </p>
8596           </dd>
8597
8598           <dt><code>pmem</code></dt>
8599           <dd>
8600             <p>
8601               If persistent memory is supported and enabled by the hypervisor
8602               in order to guarantee the persistence of writes to the vNVDIMM
8603               backend, then use the <code>pmem</code> element in order to
8604               utilize the feature.
8605               <span class="since">Since 5.0.0</span>
8606             </p>
8607           </dd>
8608         </dl>
8609       </dd>
8610
8611       <dt><code>target</code></dt>
8612       <dd>
8613         <p>
8614           The mandatory <code>target</code> element configures the placement and
8615           sizing of the added memory from the perspective of the guest.
8616         </p>
8617         <p>
8618           The mandatory <code>size</code> subelement configures the size of the
8619           added memory as a scaled integer.
8620         </p>
8621         <p>
8622           The <code>node</code> subelement configures the guest NUMA node to
8623           attach the memory to. The element shall be used only if the guest has
8624           NUMA nodes configured.
8625         </p>
8626         <p>
8627           The following optional elements may be used:
8628         </p>
8629
8630         <dl>
8631           <dt><code>label</code></dt>
8632           <dd>
8633             <p>
8634               For NVDIMM type devices one can optionally use
8635               <code>label</code> and its subelement <code>size</code>
8636               to configure the size of namespaces label storage
8637               within the NVDIMM module. The <code>size</code> element
8638               has usual meaning described
8639               <a href="#elementsMemoryAllocation">here</a>.
8640               For QEMU domains the following restrictions apply:
8641             </p>
8642             <ol>
8643               <li>the minimum label size is 128KiB,</li>
8644               <li>the remaining size (total-size - label-size) will be aligned
8645                 to 4KiB as default.</li>
8646             </ol>
8647           </dd>
8648
8649           <dt><code>readonly</code></dt>
8650           <dd>
8651             <p>
8652               The <code>readonly</code> element is used to mark the vNVDIMM
8653               as read-only. Only the real NVDIMM device backend can guarantee
8654               the guest write persistence, so other backend types should use
8655               the <code>readonly</code> element.
8656               <span class="since">Since 5.0.0</span>
8657             </p>
8658           </dd>
8659         </dl>
8660       </dd>
8661     </dl>
8662
8663     <h4><a id="elementsIommu">IOMMU devices</a></h4>
8664
8665     <p>
8666       The <code>iommu</code> element can be used to add an IOMMU device.
8667       <span class="since">Since 2.1.0</span>
8668     </p>
8669
8670     <p>
8671       Example:
8672     </p>
8673 <pre>
8674 ...
8675 &lt;devices&gt;
8676   &lt;iommu model='intel'&gt;
8677     &lt;driver intremap='on'/&gt;
8678   &lt;/iommu&gt;
8679 &lt;/devices&gt;
8680 ...
8681 </pre>
8682     <dl>
8683       <dt><code>model</code></dt>
8684       <dd>
8685         <p>
8686           Supported values are <code>intel</code> (for Q35 guests) and,
8687           <span class="since">since 5.5.0</span>, <code>smmuv3</code> (for
8688           ARM virt guests).
8689         </p>
8690       </dd>
8691       <dt><code>driver</code></dt>
8692       <dd>
8693         <p>
8694           The <code>driver</code> subelement can be used to configure
8695           additional options, some of which might only be available for
8696           certain IOMMU models:
8697         </p>
8698         <dl>
8699           <dt><code>intremap</code></dt>
8700           <dd>
8701             <p>
8702               The <code>intremap</code> attribute with possible values
8703               <code>on</code> and <code>off</code> can be used to
8704               turn on interrupt remapping, a part of the VT-d functionality.
8705               Currently this requires split I/O APIC
8706               (<code>&lt;ioapic driver='qemu'/&gt;</code>).
8707               <span class="since">Since 3.4.0</span> (QEMU/KVM only)
8708             </p>
8709           </dd>
8710           <dt><code>caching_mode</code></dt>
8711           <dd>
8712             <p>
8713               The <code>caching_mode</code> attribute with possible values
8714               <code>on</code> and <code>off</code> can be used to
8715               turn on the VT-d caching mode (useful for assigned devices).
8716               <span class="since">Since 3.4.0</span> (QEMU/KVM only)
8717             </p>
8718           </dd>
8719           <dt><code>eim</code></dt>
8720           <dd>
8721             <p>
8722               The <code>eim</code> attribute (with possible values
8723               <code>on</code> and <code>off</code>) can be used to
8724               configure Extended Interrupt Mode. A q35 domain with
8725               split I/O APIC (as described in
8726               <a href="#elementsFeatures">hypervisor features</a>),
8727               and both interrupt remapping and EIM turned on for
8728               the IOMMU, will be able to use more than 255 vCPUs.
8729               <span class="since">Since 3.4.0</span> (QEMU/KVM only)
8730             </p>
8731           </dd>
8732           <dt><code>iotlb</code></dt>
8733           <dd>
8734             <p>
8735               The <code>iotlb</code> attribute with possible values
8736               <code>on</code> and <code>off</code> can be used to
8737               turn on the IOTLB used to cache address translation
8738               requests from devices.
8739               <span class="since">Since 3.5.0</span> (QEMU/KVM only)
8740             </p>
8741           </dd>
8742         </dl>
8743       </dd>
8744     </dl>
8745
8746     <h3><a id="vsock">Vsock</a></h3>
8747
8748     <p>A vsock host/guest interface. The <code>model</code> attribute
8749     defaults to <code>virtio</code>. <span class="since">Since 5.2.0</span>
8750     <code>model</code> can also be 'virtio-transitional' and
8751     'virtio-non-transitional', see
8752     <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
8753     for more details.
8754     The optional attribute <code>address</code> of the <code>cid</code>
8755     element specifies the CID assigned to the guest. If the attribute
8756     <code>auto</code> is set to <code>yes</code>, libvirt
8757     will assign a free CID automatically on domain startup.
8758     <span class="since">Since 4.4.0</span></p>
8759
8760 <pre>
8761 ...
8762 &lt;devices&gt;
8763   &lt;vsock model='virtio'&gt;
8764     &lt;cid auto='no' address='3'/&gt;
8765   &lt;/vsock&gt;
8766 &lt;/devices&gt;
8767 ...</pre>
8768
8769
8770     <h3><a id="seclabel">Security label</a></h3>
8771
8772     <p>
8773       The <code>seclabel</code> element allows control over the
8774       operation of the security drivers. There are three basic
8775       modes of operation, 'dynamic' where libvirt automatically
8776       generates a unique security label, 'static' where the
8777       application/administrator chooses the labels, or 'none'
8778       where confinement is disabled. With dynamic
8779       label generation, libvirt will always automatically
8780       relabel any resources associated with the virtual machine.
8781       With static label assignment, by default, the administrator
8782       or application must ensure labels are set correctly on any
8783       resources, however, automatic relabeling can be enabled
8784       if desired.  <span class="since">'dynamic' since 0.6.1, 'static'
8785       since 0.6.2, and 'none' since 0.9.10.</span>
8786     </p>
8787
8788     <p>
8789       If more than one security driver is used by libvirt, multiple
8790       <code>seclabel</code> tags can be used, one for each driver and
8791       the security driver referenced by each tag can be defined using
8792       the attribute <code>model</code>
8793     </p>
8794
8795     <p>
8796       Valid input XML configurations for the top-level security label
8797       are:
8798     </p>
8799
8800     <pre>
8801 &lt;seclabel type='dynamic' model='selinux'/&gt;
8802
8803 &lt;seclabel type='dynamic' model='selinux'&gt;
8804   &lt;baselabel&gt;system_u:system_r:my_svirt_t:s0&lt;/baselabel&gt;
8805 &lt;/seclabel&gt;
8806
8807 &lt;seclabel type='static' model='selinux' relabel='no'&gt;
8808   &lt;label&gt;system_u:system_r:svirt_t:s0:c392,c662&lt;/label&gt;
8809 &lt;/seclabel&gt;
8810
8811 &lt;seclabel type='static' model='selinux' relabel='yes'&gt;
8812   &lt;label&gt;system_u:system_r:svirt_t:s0:c392,c662&lt;/label&gt;
8813 &lt;/seclabel&gt;
8814
8815 &lt;seclabel type='none'/&gt;
8816     </pre>
8817
8818     <p>
8819       If no 'type' attribute is provided in the input XML, then
8820       the security driver default setting will be used, which
8821       may be either 'none' or 'dynamic'. If a 'baselabel' is set
8822       but no 'type' is set, then the type is presumed to be 'dynamic'
8823     </p>
8824
8825     <p>
8826       When viewing the XML for a running guest with automatic
8827       resource relabeling active, an additional XML element,
8828       <code>imagelabel</code>, will be included. This is an
8829       output-only element, so will be ignored in user supplied
8830       XML documents
8831     </p>
8832     <dl>
8833       <dt><code>type</code></dt>
8834       <dd>Either <code>static</code>, <code>dynamic</code> or <code>none</code>
8835         to determine whether libvirt automatically generates a unique security
8836         label or not.
8837       </dd>
8838       <dt><code>model</code></dt>
8839       <dd>A valid security model name, matching the currently
8840         activated security model
8841       </dd>
8842       <dt><code>relabel</code></dt>
8843       <dd>Either <code>yes</code> or <code>no</code>. This must always
8844         be <code>yes</code> if dynamic label assignment is used. With
8845         static label assignment it will default to <code>no</code>.
8846       </dd>
8847       <dt><code>label</code></dt>
8848       <dd>If static labelling is used, this must specify the full
8849         security label to assign to the virtual domain. The format
8850         of the content depends on the security driver in use:
8851         <ul>
8852           <li>SELinux: a SELinux context.</li>
8853           <li>AppArmor: an AppArmor profile.</li>
8854           <li>
8855             DAC: owner and group separated by colon. They can be
8856             defined both as user/group names or uid/gid. The driver will first
8857             try to parse these values as names, but a leading plus sign can
8858             used to force the driver to parse them as uid or gid.
8859           </li>
8860         </ul>
8861       </dd>
8862       <dt><code>baselabel</code></dt>
8863       <dd>If dynamic labelling is used, this can optionally be
8864         used to specify the base security label that will be used to generate
8865         the actual label. The format of the content depends on the security
8866         driver in use.
8867
8868         The SELinux driver uses only the <code>type</code> field of the
8869         baselabel in the generated label. Other fields are inherited from
8870         the parent process when using SELinux baselabels.
8871
8872         (The example above demonstrates the use of <code>my_svirt_t</code>
8873         as the value for the <code>type</code> field.)
8874       </dd>
8875       <dt><code>imagelabel</code></dt>
8876       <dd>This is an output only element, which shows the
8877         security label used on resources associated with the virtual domain.
8878         The format of the content depends on the security driver in use
8879       </dd>
8880     </dl>
8881
8882     <p>When relabeling is in effect, it is also possible to fine-tune
8883       the labeling done for specific source file names, by either
8884       disabling the labeling (useful if the file lives on NFS or other
8885       file system that lacks security labeling) or requesting an
8886       alternate label (useful when a management application creates a
8887       special label to allow sharing of some, but not all, resources
8888       between domains), <span class="since">since 0.9.9</span>.  When
8889       a <code>seclabel</code> element is attached to a specific path
8890       rather than the top-level domain assignment, only the
8891       attribute <code>relabel</code> or the
8892       sub-element <code>label</code> are supported.  Additionally,
8893       <span class="since">since 1.1.2</span>, an output-only
8894       element <code>labelskip</code> will be present for active
8895       domains on disks where labeling was skipped due to the image
8896       being on a file system that lacks security labeling.
8897     </p>
8898
8899     <h3><a id="keywrap">Key Wrap</a></h3>
8900
8901        <p>The content of the optional <code>keywrap</code> element specifies
8902         whether the guest will be allowed to perform the S390 cryptographic key
8903         management operations. A clear key can be protected by encrypting it
8904         under a unique wrapping key that is generated for each guest VM running
8905         on the host. Two variations of wrapping keys are generated: one version
8906         for encrypting protected keys using the DEA/TDEA algorithm, and another
8907         version for keys encrypted using the AES algorithm. If a
8908         <code>keywrap</code> element is not included, the guest will be granted
8909         access to both AES and DEA/TDEA key wrapping by default.</p>
8910
8911         <pre>
8912 &lt;domain&gt;
8913   ...
8914   &lt;keywrap&gt;
8915     &lt;cipher name='aes' state='off'/&gt;
8916   &lt;/keywrap&gt;
8917   ...
8918 &lt;/domain&gt;
8919 </pre>
8920     <p>
8921       At least one <code>cipher</code> element must be nested within the
8922       <code>keywrap</code> element.
8923     </p>
8924     <dl>
8925       <dt><code>cipher</code></dt>
8926       <dd>The <code>name</code> attribute identifies the algorithm
8927         for encrypting a protected key. The values supported for this attribute
8928         are <code>aes</code> for encryption under the AES wrapping key, or
8929         <code>dea</code> for encryption under the DEA/TDEA wrapping key. The
8930         <code>state</code> attribute indicates whether the cryptographic key
8931         management operations should be turned on for the specified encryption
8932         algorithm. The value can be set to <code>on</code> or <code>off</code>.
8933       </dd>
8934     </dl>
8935
8936     <p>Note: DEA/TDEA is synonymous with DES/TDES.</p>
8937
8938     <h3><a id="launchSecurity">Launch Security</a></h3>
8939
8940     <p>
8941        The contents of the <code>&lt;launchSecurity type='sev'&gt;</code> element
8942        is used to provide the guest owners input used for creating an encrypted
8943        VM using the AMD SEV feature (Secure Encrypted Virtualization).
8944
8945        SEV is an extension to the AMD-V architecture which supports running
8946        encrypted virtual machine (VMs) under the control of KVM. Encrypted
8947        VMs have their pages (code and data) secured such that only the guest
8948        itself has access to the unencrypted version. Each encrypted VM is
8949        associated with a unique encryption key; if its data is accessed to a
8950        different entity using a different key the encrypted guests data will
8951        be incorrectly decrypted, leading to unintelligible data.
8952
8953        For more information see various input parameters and its format see the
8954        <a href="https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf">SEV API spec</a>
8955        <span class="since">Since 4.4.0</span>
8956        </p>
8957     <pre>
8958 &lt;domain&gt;
8959   ...
8960   &lt;launchSecurity type='sev'&gt;
8961     &lt;policy&gt;0x0001&lt;/policy&gt;
8962     &lt;cbitpos&gt;47&lt;/cbitpos&gt;
8963     &lt;reducedPhysBits&gt;1&lt;/reducedPhysBits&gt;
8964     &lt;dhCert&gt;RBBBSDDD=FDDCCCDDDG&lt;/dhCert&gt;
8965     &lt;session&gt;AAACCCDD=FFFCCCDSDS&lt;/session&gt;
8966   &lt;/launchSecurity&gt;
8967   ...
8968 &lt;/domain&gt;
8969 </pre>
8970
8971     <dl>
8972       <dt><code>cbitpos</code></dt>
8973       <dd>The required <code>cbitpos</code> element provides the C-bit (aka encryption bit)
8974       location in guest page table entry. The value of <code>cbitpos</code> is
8975       hypervisor dependent and can be obtained through the <code>sev</code> element
8976       from the domain capabilities.
8977       </dd>
8978       <dt><code>reducedPhysBits</code></dt>
8979       <dd>The required <code>reducedPhysBits</code> element provides the physical
8980       address bit reducation. Similar to <code>cbitpos</code> the value of <code>
8981       reduced-phys-bit</code> is hypervisor dependent and can be obtained
8982       through the <code>sev</code> element from the domain capabilities.
8983       </dd>
8984       <dt><code>policy</code></dt>
8985       <dd>The required <code>policy</code> element provides the guest policy
8986       which must be maintained by the SEV firmware. This policy is enforced by
8987       the firmware and restricts what configuration and operational commands
8988       can be performed on this guest by the hypervisor. The guest policy
8989       provided during guest launch is bound to the guest and cannot be changed
8990       throughout the lifetime of the guest. The policy is also transmitted
8991       during snapshot and migration flows and enforced on the destination platform.
8992
8993       The guest policy is a 4 unsigned byte with the fields shown in Table:
8994
8995       <table class="top_table">
8996         <tr>
8997           <th> Bit(s) </th>
8998           <th> Description </th>
8999         </tr>
9000         <tr>
9001           <td> 0 </td>
9002           <td> Debugging of the guest is disallowed when set </td>
9003         </tr>
9004         <tr>
9005           <td> 1 </td>
9006           <td> Sharing keys with other guests is disallowed when set </td>
9007         </tr>
9008         <tr>
9009           <td> 2 </td>
9010           <td> SEV-ES is required when set</td>
9011         </tr>
9012         <tr>
9013           <td> 3 </td>
9014           <td> Sending the guest to another platform is disallowed when set</td>
9015         </tr>
9016         <tr>
9017           <td> 4 </td>
9018           <td> The guest must not be transmitted to another platform that is
9019                not in the domain when set. </td>
9020         </tr>
9021         <tr>
9022           <td> 5 </td>
9023           <td> The guest must not be transmitted to another platform that is
9024                not SEV capable when set. </td>
9025         </tr>
9026         <tr>
9027           <td> 6:15 </td>
9028           <td> reserved </td>
9029         </tr>
9030         <tr>
9031           <td> 16:32 </td>
9032           <td> The guest must not be transmitted to another platform with a
9033                lower firmware version. </td>
9034         </tr>
9035       </table>
9036
9037       </dd>
9038       <dt><code>dhCert</code></dt>
9039       <dd>The optional <code>dhCert</code> element provides the guest owners
9040       base64 encoded Diffie-Hellman (DH) key. The key is used to negotiate a
9041       master secret key between the SEV firmware and guest owner. This master
9042       secret key is then used to establish a trusted channel between SEV
9043       firmware and guest owner.
9044       </dd>
9045       <dt><code>session</code></dt>
9046       <dd>The optional <code>session</code> element provides the guest owners
9047       base64 encoded session blob defined in the SEV API spec.
9048
9049       See SEV spec LAUNCH_START section for the session blob format.
9050       </dd>
9051     </dl>
9052
9053     <h2><a id="examples">Example configs</a></h2>
9054
9055     <p>
9056       Example configurations for each driver are provide on the
9057       driver specific pages listed below
9058     </p>
9059
9060     <ul>
9061       <li><a href="drvxen.html#xmlconfig">Xen examples</a></li>
9062       <li><a href="drvqemu.html#xmlconfig">QEMU/KVM examples</a></li>
9063     </ul>
9064   </body>
9065 </html>