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 for the running instance of the guest, even if the destination
1594           host contains more capable CPUs or newer kernel; 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 hosts
1629           are not identical in both hardware, QEMU version, microcode version
1630           and configuration. If such a migration is attempted then the guest may
1631           hang or crash upon 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;stimer state='on'&gt;
2037       &lt;direct state='on'/&gt;
2038     &lt;/stimer&gt;
2039     &lt;reset state='on'/&gt;
2040     &lt;vendor_id state='on' value='KVM Hv'/&gt;
2041     &lt;frequencies state='on'/&gt;
2042     &lt;reenlightenment state='on'/&gt;
2043     &lt;tlbflush state='on'/&gt;
2044     &lt;ipi state='on'/&gt;
2045     &lt;evmcs state='on'/&gt;
2046   &lt;/hyperv&gt;
2047   &lt;kvm&gt;
2048     &lt;hidden state='on'/&gt;
2049     &lt;hint-dedicated state='on'/&gt;
2050   &lt;/kvm&gt;
2051   &lt;pvspinlock state='on'/&gt;
2052   &lt;gic version='2'/&gt;
2053   &lt;ioapic driver='qemu'/&gt;
2054   &lt;hpt resizing='required'&gt;
2055     &lt;maxpagesize unit='MiB'&gt;16&lt;/maxpagesize&gt;
2056   &lt;/hpt&gt;
2057   &lt;vmcoreinfo state='on'/&gt;
2058   &lt;smm state='on'&gt;
2059     &lt;tseg unit='MiB'&gt;48&lt;/tseg&gt;
2060   &lt;/smm&gt;
2061   &lt;htm state='on'/&gt;
2062   &lt;msrs unknown='ignore'/&gt;
2063 &lt;/features&gt;
2064 ...</pre>
2065
2066     <p>
2067       All features are listed within the <code>features</code>
2068       element, omitting a togglable feature tag turns it off.
2069       The available features can be found by asking
2070       for the <a href="formatcaps.html">capabilities XML</a> and
2071       <a href="formatdomaincaps.html">domain capabilities XML</a>,
2072       but a common set for fully virtualized domains are:
2073     </p>
2074
2075     <dl>
2076       <dt><code>pae</code></dt>
2077       <dd>Physical address extension mode allows 32-bit guests
2078         to address more than 4 GB of memory.</dd>
2079       <dt><code>acpi</code></dt>
2080       <dd>ACPI is useful for power management, for example, with
2081         KVM guests it is required for graceful shutdown to work.
2082       </dd>
2083       <dt><code>apic</code></dt>
2084       <dd>APIC allows the use of programmable IRQ
2085       management. <span class="since">Since 0.10.2 (QEMU only)</span> there is
2086       an optional attribute <code>eoi</code> with values <code>on</code>
2087       and <code>off</code> which toggles the availability of EOI (End of
2088       Interrupt) for the guest.
2089       </dd>
2090       <dt><code>hap</code></dt>
2091       <dd>Depending on the <code>state</code> attribute (values <code>on</code>,
2092         <code>off</code>) enable or disable use of Hardware Assisted Paging.
2093         The default is <code>on</code> if the hypervisor detects availability
2094         of Hardware Assisted Paging.
2095       </dd>
2096       <dt><code>viridian</code></dt>
2097       <dd>Enable Viridian hypervisor extensions for paravirtualizing
2098         guest operating systems
2099       </dd>
2100       <dt><code>privnet</code></dt>
2101       <dd>Always create a private network namespace. This is
2102         automatically set if any interface devices are defined.
2103         This feature is only relevant for container based
2104         virtualization drivers, such as LXC.
2105       </dd>
2106       <dt><code>hyperv</code></dt>
2107       <dd>Enable various features improving behavior of guests
2108         running Microsoft Windows.
2109       <table class="top_table">
2110         <tr>
2111           <th>Feature</th>
2112           <th>Description</th>
2113           <th>Value</th>
2114           <th>Since</th>
2115         </tr>
2116         <tr>
2117           <td>relaxed</td>
2118           <td>Relax constraints on timers</td>
2119           <td>on, off</td>
2120           <td><span class="since">1.0.0 (QEMU 2.0)</span></td>
2121         </tr>
2122         <tr>
2123           <td>vapic</td>
2124           <td>Enable virtual APIC</td>
2125           <td>on, off</td>
2126           <td><span class="since">1.1.0 (QEMU 2.0)</span></td>
2127         </tr>
2128         <tr>
2129           <td>spinlocks</td>
2130           <td>Enable spinlock support</td>
2131           <td>on, off; retries - at least 4095</td>
2132           <td><span class="since">1.1.0 (QEMU 2.0)</span></td>
2133         </tr>
2134         <tr>
2135           <td>vpindex</td>
2136           <td>Virtual processor index</td>
2137           <td>on, off</td>
2138           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2139         </tr>
2140         <tr>
2141           <td>runtime</td>
2142           <td>Processor time spent on running guest code and on behalf of guest code</td>
2143           <td>on, off</td>
2144           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2145         </tr>
2146         <tr>
2147           <td>synic</td>
2148           <td>Enable Synthetic Interrupt Controller (SynIC)</td>
2149           <td>on, off</td>
2150           <td><span class="since">1.3.3 (QEMU 2.6)</span></td>
2151         </tr>
2152         <tr>
2153           <td>stimer</td>
2154           <td>Enable SynIC timers, optionally with Direct Mode support</td>
2155           <td>on, off; direct - on,off</td>
2156           <td><span class="since">1.3.3 (QEMU 2.6), direct mode 5.7.0 (QEMU 4.1)</span></td>
2157         </tr>
2158         <tr>
2159           <td>reset</td>
2160           <td>Enable hypervisor reset</td>
2161           <td>on, off</td>
2162           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2163         </tr>
2164         <tr>
2165           <td>vendor_id</td>
2166           <td>Set hypervisor vendor id</td>
2167           <td>on, off; value - string, up to 12 characters</td>
2168           <td><span class="since">1.3.3 (QEMU 2.5)</span></td>
2169         </tr>
2170         <tr>
2171           <td>frequencies</td>
2172           <td>Expose frequency MSRs</td>
2173           <td>on, off</td>
2174           <td><span class="since">4.7.0 (QEMU 2.12)</span></td>
2175         </tr>
2176         <tr>
2177           <td>reenlightenment</td>
2178           <td>Enable re-enlightenment notification on migration</td>
2179           <td>on, off</td>
2180           <td><span class="since">4.7.0 (QEMU 3.0)</span></td>
2181         </tr>
2182         <tr>
2183           <td>tlbflush</td>
2184           <td>Enable PV TLB flush support</td>
2185           <td>on, off</td>
2186           <td><span class="since">4.7.0 (QEMU 3.0)</span></td>
2187         </tr>
2188         <tr>
2189           <td>ipi</td>
2190           <td>Enable PV IPI support</td>
2191           <td>on, off</td>
2192           <td><span class="since">4.10.0 (QEMU 3.1)</span></td>
2193         </tr>
2194         <tr>
2195           <td>evmcs</td>
2196           <td>Enable Enlightened VMCS</td>
2197           <td>on, off</td>
2198           <td><span class="since">4.10.0 (QEMU 3.1)</span></td>
2199         </tr>
2200       </table>
2201       </dd>
2202       <dt><code>pvspinlock</code></dt>
2203       <dd>Notify the guest that the host supports paravirtual spinlocks
2204           for example by exposing the pvticketlocks mechanism. This feature
2205           can be explicitly disabled by using <code>state='off'</code>
2206           attribute.
2207       </dd>
2208       <dt><code>kvm</code></dt>
2209       <dd>Various features to change the behavior of the KVM hypervisor.
2210       <table class="top_table">
2211         <tr>
2212           <th>Feature</th>
2213           <th>Description</th>
2214           <th>Value</th>
2215           <th>Since</th>
2216         </tr>
2217         <tr>
2218           <td>hidden</td>
2219           <td>Hide the KVM hypervisor from standard MSR based discovery</td>
2220           <td>on, off</td>
2221           <td><span class="since">1.2.8 (QEMU 2.1.0)</span></td>
2222         </tr>
2223         <tr>
2224           <td>hint-dedicated</td>
2225           <td>Allows a guest to enable optimizations when running on dedicated vCPUs</td>
2226           <td>on, off</td>
2227           <td><span class="since">5.7.0 (QEMU 2.12.1)</span></td>
2228         </tr>
2229       </table>
2230       </dd>
2231       <dt><code>pmu</code></dt>
2232       <dd>Depending on the <code>state</code> attribute (values <code>on</code>,
2233         <code>off</code>, default <code>on</code>) enable or disable the
2234         performance monitoring unit for the guest.
2235         <span class="since">Since 1.2.12</span>
2236       </dd>
2237       <dt><code>vmport</code></dt>
2238       <dd>Depending on the <code>state</code> attribute (values <code>on</code>,
2239         <code>off</code>, default <code>on</code>) enable or disable
2240         the emulation of VMware IO port, for vmmouse etc.
2241         <span class="since">Since 1.2.16</span>
2242       </dd>
2243       <dt><code>gic</code></dt>
2244       <dd>Enable for architectures using a General Interrupt
2245           Controller instead of APIC in order to handle interrupts.
2246           For example, the 'aarch64' architecture uses
2247           <code>gic</code> instead of <code>apic</code>. The optional
2248           attribute <code>version</code> specifies the GIC version;
2249           however, it may not be supported by all hypervisors. Accepted
2250           values are <code>2</code>, <code>3</code> and <code>host</code>.
2251           <span class="since">Since 1.2.16</span>
2252       </dd>
2253       <dt><code>smm</code></dt>
2254       <dd>
2255         <p>
2256           Depending on the <code>state</code> attribute (values <code>on</code>,
2257           <code>off</code>, default <code>on</code>) enable or disable
2258           System Management Mode.
2259           <span class="since">Since 2.1.0</span>
2260         </p><p> Optional sub-element <code>tseg</code> can be used to specify
2261           the amount of memory dedicated to SMM's extended TSEG. That offers a
2262           fourth option size apart from the existing ones (1 MiB, 2 MiB and 8
2263           MiB) that the guest OS (or rather loader) can choose from. The size
2264           can be specified as a value of that element, optional attribute
2265           <code>unit</code> can be used to specify the unit of the
2266           aforementioned value (defaults to 'MiB').  If set to 0 the extended
2267           size is not advertised and only the default ones (see above) are
2268           available.
2269         </p><p>
2270           <b>If the VM is booting you should leave this option alone, unless you
2271           are very certain you know what you are doing.</b>
2272         </p><p>
2273           This value is configurable due to the fact that the calculation cannot
2274           be done right with the guarantee that it will work correctly.  In
2275           QEMU, the user-configurable extended TSEG feature was unavailable up
2276           to and including <code>pc-q35-2.9</code>. Starting with
2277           <code>pc-q35-2.10</code> the feature is available, with default size
2278           16 MiB.  That should suffice for up to roughly 272 vCPUs, 5 GiB guest
2279           RAM in total, no hotplug memory range, and 32 GiB of 64-bit PCI MMIO
2280           aperture.  Or for 48 vCPUs, with 1TB of guest RAM, no hotplug DIMM
2281           range, and 32GB of 64-bit PCI MMIO aperture. The values may also vary
2282           based on the loader the VM is using.
2283         </p><p>
2284           Additional size might be needed for significantly higher vCPU counts
2285           or increased address space (that can be memory, maxMemory, 64-bit PCI
2286           MMIO aperture size; roughly 8 MiB of TSEG per 1 TiB of address space)
2287           which can also be rounded up.
2288         </p><p>
2289           Due to the nature of this setting being similar to "how much RAM
2290           should the guest have" users are advised to either consult the
2291           documentation of the guest OS or loader (if there is any), or test
2292           this by trial-and-error changing the value until the VM boots
2293           successfully.  Yet another guiding value for users might be the fact
2294           that 48 MiB should be enough for pretty large guests (240 vCPUs and
2295           4TB guest RAM), but it is on purpose not set as default as 48 MiB of
2296           unavailable RAM might be too much for small guests (e.g. with 512 MiB
2297           of RAM).
2298         </p><p>
2299           See <a href="#elementsMemoryAllocation">Memory Allocation</a>
2300           for more details about the <code>unit</code> attribute.
2301           <span class="since">Since 4.5.0</span> (QEMU only)
2302         </p>
2303       </dd>
2304       <dt><code>ioapic</code></dt>
2305       <dd>Tune the I/O APIC. Possible values for the
2306           <code>driver</code> attribute are:
2307           <code>kvm</code> (default for KVM domains)
2308           and <code>qemu</code> which puts I/O APIC in userspace
2309           which is also known as a split I/O APIC mode.
2310           <span class="since">Since 3.4.0</span> (QEMU/KVM only)
2311       </dd>
2312       <dt><code>hpt</code></dt>
2313       <dd>Configure the HPT (Hash Page Table) of a pSeries guest. Possible
2314           values for the <code>resizing</code> attribute are
2315           <code>enabled</code>, which causes HPT resizing to be enabled if
2316           both the guest and the host support it; <code>disabled</code>, which
2317           causes HPT resizing to be disabled regardless of guest and host
2318           support; and <code>required</code>, which prevents the guest from
2319           starting unless both the guest and the host support HPT resizing. If
2320           the attribute is not defined, the hypervisor default will be used.
2321           <span class="since">Since 3.10.0</span> (QEMU/KVM only).
2322
2323           <p>The optional <code>maxpagesize</code> subelement can be used to
2324           limit the usable page size for HPT guests. Common values are 64 KiB,
2325           16 MiB and 16 GiB; when not specified, the hypervisor default will
2326           be used. <span class="since">Since 4.5.0</span> (QEMU/KVM only).</p>
2327       </dd>
2328       <dt><code>vmcoreinfo</code></dt>
2329       <dd>Enable QEMU vmcoreinfo device to let the guest kernel save debug
2330           details. <span class="since">Since 4.4.0</span> (QEMU only)
2331       </dd>
2332       <dt><code>htm</code></dt>
2333       <dd>Configure HTM (Hardware Transational Memory) availability for
2334           pSeries guests. Possible values for the <code>state</code> attribute
2335           are <code>on</code> and <code>off</code>. If the attribute is not
2336           defined, the hypervisor default will be used.
2337           <span class="since">Since 4.6.0</span> (QEMU/KVM only)
2338       </dd>
2339       <dt><code>nested-hv</code></dt>
2340       <dd>Configure nested HV availability for pSeries guests. This needs to
2341           be enabled from the host (L0) in order to be effective; having HV
2342           support in the (L1) guest is very desiderable if it's planned to
2343           run nested (L2) guests inside it, because it will result in those
2344           nested guests having much better performance than they would when
2345           using KVM PR or TCG.
2346           Possible values for the <code>state</code> attribute are
2347           <code>on</code> and <code>off</code>. If the attribute is not
2348           defined, the hypervisor default will be used.
2349           <span class="since">Since 4.10.0</span> (QEMU/KVM only)
2350       </dd>
2351       <dt><code>msrs</code></dt>
2352       <dd>Some guests might require ignoring unknown
2353           Model Specific Registers (MSRs) reads and writes. It's possible
2354           to switch this by setting <code>unknown</code> attribute
2355           of <code>msrs</code> to <code>ignore</code>. If the attribute is
2356           not defined, or set to <code>fault</code>, unknown reads and writes
2357           will not be ignored.
2358           <span class="since">Since 5.1.0</span> (bhyve only)
2359       </dd>
2360     </dl>
2361
2362     <h3><a id="elementsTime">Time keeping</a></h3>
2363
2364     <p>
2365       The guest clock is typically initialized from the host clock.
2366       Most operating systems expect the hardware clock to be kept
2367       in UTC, and this is the default. Windows, however, expects
2368       it to be in so called 'localtime'.
2369     </p>
2370
2371 <pre>
2372 ...
2373 &lt;clock offset='localtime'&gt;
2374   &lt;timer name='rtc' tickpolicy='catchup' track='guest'&gt;
2375     &lt;catchup threshold='123' slew='120' limit='10000'/&gt;
2376   &lt;/timer&gt;
2377   &lt;timer name='pit' tickpolicy='delay'/&gt;
2378 &lt;/clock&gt;
2379 ...</pre>
2380
2381     <dl>
2382       <dt><code>clock</code></dt>
2383       <dd>
2384         <p>The <code>offset</code> attribute takes four possible
2385           values, allowing fine grained control over how the guest
2386           clock is synchronized to the host. NB, not all hypervisors
2387           support all modes.</p>
2388         <dl>
2389           <dt><code>utc</code></dt>
2390           <dd>
2391             The guest clock will always be synchronized to UTC when
2392             booted.
2393             <span class="since">Since 0.9.11</span> 'utc' mode can be converted
2394             to 'variable' mode, which can be controlled by using the
2395             <code>adjustment</code> attribute. If the value is 'reset', the
2396             conversion is never done (not all hypervisors can
2397             synchronize to UTC on each boot; use of 'reset' will cause
2398             an error on those hypervisors). A numeric value
2399             forces the conversion to 'variable' mode using the value as the
2400             initial adjustment. The default <code>adjustment</code> is
2401             hypervisor specific.
2402           </dd>
2403           <dt><code>localtime</code></dt>
2404           <dd>
2405             The guest clock will be synchronized to the host's configured
2406             timezone when booted, if any.
2407             <span class="since">Since 0.9.11,</span> the <code>adjustment</code>
2408             attribute behaves the same as in 'utc' mode.
2409           </dd>
2410           <dt><code>timezone</code></dt>
2411           <dd>
2412             The guest clock will be synchronized to the requested timezone
2413             using the <code>timezone</code> attribute.
2414             <span class="since">Since 0.7.7</span>
2415           </dd>
2416           <dt><code>variable</code></dt>
2417           <dd>
2418             The guest clock will have an arbitrary offset applied
2419             relative to UTC or localtime, depending on the <code>basis</code>
2420             attribute. The delta relative to UTC (or localtime) is specified
2421             in seconds, using the <code>adjustment</code> attribute.
2422             The guest is free to adjust the RTC over time and expect
2423             that it will be honored at next reboot. This is in
2424             contrast to 'utc' and 'localtime' mode (with the optional
2425             attribute adjustment='reset'), where the RTC adjustments are
2426             lost at each reboot. <span class="since">Since 0.7.7</span>
2427             <span class="since">Since 0.9.11</span> the <code>basis</code>
2428             attribute can be either 'utc' (default) or 'localtime'.
2429           </dd>
2430         </dl>
2431         <p>
2432           A <code>clock</code> may have zero or more
2433           <code>timer</code> sub-elements. <span class="since">Since
2434           0.8.0</span>
2435         </p>
2436       </dd>
2437       <dt><code>timer</code></dt>
2438       <dd>
2439         <p>
2440           Each timer element requires a <code>name</code> attribute,
2441           and has other optional attributes that depend on
2442           the <code>name</code> specified.  Various hypervisors
2443           support different combinations of attributes.
2444         </p>
2445         <dl>
2446           <dt><code>name</code></dt>
2447           <dd>
2448             The <code>name</code> attribute selects which timer is
2449             being modified, and can be one of
2450             "platform" (currently unsupported),
2451             "hpet" (libxl, xen, qemu), "kvmclock" (qemu),
2452             "pit" (qemu), "rtc" (qemu), "tsc" (libxl, qemu -
2453             <span class="since">since 3.2.0</span>)
2454             or "hypervclock"
2455             (qemu - <span class="since">since 1.2.2</span>).
2456
2457             The <code>hypervclock</code> timer adds support for the
2458             reference time counter and the reference page for iTSC
2459             feature for guests running the Microsoft Windows
2460             operating system.
2461           </dd>
2462           <dt><code>track</code></dt>
2463           <dd>
2464             The <code>track</code> attribute specifies what the timer
2465             tracks, and can be "boot", "guest", or "wall".
2466             Only valid for <code>name="rtc"</code>
2467             or <code>name="platform"</code>.
2468           </dd>
2469           <dt><code>tickpolicy</code></dt>
2470           <dd>
2471             <p>
2472             The <code>tickpolicy</code> attribute determines what
2473             happens when QEMU misses a deadline for injecting a
2474             tick to the guest:
2475             </p>
2476             <dl>
2477               <dt><code>delay</code></dt>
2478               <dd>Continue to deliver ticks at the normal rate.
2479                 The guest time will be delayed due to the late
2480                 tick</dd>
2481               <dt><code>catchup</code></dt>
2482               <dd>Deliver ticks at a higher rate to catch up
2483                 with the missed tick. The guest time should
2484                 not be delayed once catchup is complete.</dd>
2485               <dt><code>merge</code></dt>
2486               <dd>Merge the missed tick(s) into one tick and
2487                 inject. The guest time may be delayed, depending
2488                 on how the OS reacts to the merging of ticks</dd>
2489               <dt><code>discard</code></dt>
2490               <dd>Throw away the missed tick(s) and continue
2491                 with future injection normally. The guest time
2492                 may be delayed, unless the OS has explicit
2493                 handling of lost ticks</dd>
2494             </dl>
2495             <p>If the policy is "catchup", there can be further details in
2496             the <code>catchup</code> sub-element.</p>
2497             <dl>
2498               <dt><code>catchup</code></dt>
2499               <dd>
2500                 The <code>catchup</code> element has three optional
2501                 attributes, each a positive integer.  The attributes
2502                 are <code>threshold</code>, <code>slew</code>,
2503                 and <code>limit</code>.
2504               </dd>
2505             </dl>
2506             <p>
2507               Note that hypervisors are not required to support all policies across all time sources
2508             </p>
2509           </dd>
2510           <dt><code>frequency</code></dt>
2511           <dd>
2512             The <code>frequency</code> attribute is an unsigned
2513             integer specifying the frequency at
2514             which <code>name="tsc"</code> runs.
2515           </dd>
2516           <dt><code>mode</code></dt>
2517           <dd>
2518             The <code>mode</code> attribute controls how
2519             the <code>name="tsc"</code> timer is managed, and can be
2520             "auto", "native", "emulate", "paravirt", or "smpsafe".
2521             Other timers are always emulated.
2522           </dd>
2523           <dt><code>present</code></dt>
2524           <dd>
2525             The <code>present</code> attribute can be "yes" or "no" to
2526             specify whether a particular timer is available to the guest.
2527           </dd>
2528         </dl>
2529       </dd>
2530     </dl>
2531
2532     <h3><a id="elementsPerf">Performance monitoring events</a></h3>
2533
2534     <p>
2535       Some platforms allow monitoring of performance of the virtual machine and
2536       the code executed inside. To enable the performance monitoring events
2537       you can either specify them in the <code>perf</code> element or enable
2538       them via <code>virDomainSetPerfEvents</code> API. The performance values
2539       are then retrieved using the virConnectGetAllDomainStats API.
2540       <span class="since">Since 2.0.0</span>
2541     </p>
2542
2543 <pre>
2544 ...
2545 &lt;perf&gt;
2546   &lt;event name='cmt' enabled='yes'/&gt;
2547   &lt;event name='mbmt' enabled='no'/&gt;
2548   &lt;event name='mbml' enabled='yes'/&gt;
2549   &lt;event name='cpu_cycles' enabled='no'/&gt;
2550   &lt;event name='instructions' enabled='yes'/&gt;
2551   &lt;event name='cache_references' enabled='no'/&gt;
2552   &lt;event name='cache_misses' enabled='no'/&gt;
2553   &lt;event name='branch_instructions' enabled='no'/&gt;
2554   &lt;event name='branch_misses' enabled='no'/&gt;
2555   &lt;event name='bus_cycles' enabled='no'/&gt;
2556   &lt;event name='stalled_cycles_frontend' enabled='no'/&gt;
2557   &lt;event name='stalled_cycles_backend' enabled='no'/&gt;
2558   &lt;event name='ref_cpu_cycles' enabled='no'/&gt;
2559   &lt;event name='cpu_clock' enabled='no'/&gt;
2560   &lt;event name='task_clock' enabled='no'/&gt;
2561   &lt;event name='page_faults' enabled='no'/&gt;
2562   &lt;event name='context_switches' enabled='no'/&gt;
2563   &lt;event name='cpu_migrations' enabled='no'/&gt;
2564   &lt;event name='page_faults_min' enabled='no'/&gt;
2565   &lt;event name='page_faults_maj' enabled='no'/&gt;
2566   &lt;event name='alignment_faults' enabled='no'/&gt;
2567   &lt;event name='emulation_faults' enabled='no'/&gt;
2568 &lt;/perf&gt;
2569 ...
2570 </pre>
2571
2572   <table class="top_table">
2573     <tr>
2574       <th>event name</th>
2575       <th>Description</th>
2576       <th>stats parameter name</th>
2577     </tr>
2578     <tr>
2579       <td><code>cmt</code></td>
2580       <td>usage of l3 cache in bytes by applications running on the platform</td>
2581       <td><code>perf.cmt</code></td>
2582     </tr>
2583     <tr>
2584       <td><code>mbmt</code></td>
2585       <td>total system bandwidth from one level of cache</td>
2586       <td><code>perf.mbmt</code></td>
2587     </tr>
2588     <tr>
2589       <td><code>mbml</code></td>
2590       <td>bandwidth of memory traffic for a memory controller</td>
2591       <td><code>perf.mbml</code></td>
2592     </tr>
2593     <tr>
2594       <td><code>cpu_cycles</code></td>
2595       <td>the count of CPU cycles (total/elapsed)</td>
2596       <td><code>perf.cpu_cycles</code></td>
2597     </tr>
2598     <tr>
2599       <td><code>instructions</code></td>
2600       <td>the count of instructions by applications running on the platform</td>
2601       <td><code>perf.instructions</code></td>
2602     </tr>
2603     <tr>
2604       <td><code>cache_references</code></td>
2605       <td>the count of cache hits by applications running on the platform</td>
2606       <td><code>perf.cache_references</code></td>
2607     </tr>
2608     <tr>
2609       <td><code>cache_misses</code></td>
2610       <td>the count of cache misses by applications running on the platform</td>
2611       <td><code>perf.cache_misses</code></td>
2612     </tr>
2613     <tr>
2614       <td><code>branch_instructions</code></td>
2615       <td>the count of branch instructions by applications running on the platform</td>
2616       <td><code>perf.branch_instructions</code></td>
2617     </tr>
2618     <tr>
2619       <td><code>branch_misses</code></td>
2620       <td>the count of branch misses by applications running on the platform</td>
2621       <td><code>perf.branch_misses</code></td>
2622     </tr>
2623     <tr>
2624       <td><code>bus_cycles</code></td>
2625       <td>the count of bus cycles by applications running on the platform</td>
2626       <td><code>perf.bus_cycles</code></td>
2627     </tr>
2628     <tr>
2629       <td><code>stalled_cycles_frontend</code></td>
2630       <td>the count of stalled CPU cycles in the frontend of the instruction
2631           processor pipeline by applications running on the platform</td>
2632       <td><code>perf.stalled_cycles_frontend</code></td>
2633     </tr>
2634     <tr>
2635       <td><code>stalled_cycles_backend</code></td>
2636       <td>the count of stalled CPU cycles in the backend of the instruction
2637           processor pipeline by applications running on the platform</td>
2638       <td><code>perf.stalled_cycles_backend</code></td>
2639     </tr>
2640     <tr>
2641       <td><code>ref_cpu_cycles</code></td>
2642       <td>the count of total CPU cycles not affected by CPU frequency scaling
2643          by applications running on the platform</td>
2644       <td><code>perf.ref_cpu_cycles</code></td>
2645     </tr>
2646     <tr>
2647       <td><code>cpu_clock</code></td>
2648       <td>the count of CPU clock time, as measured by a monotonic
2649           high-resolution per-CPU timer, by applications running on
2650           the platform</td>
2651       <td><code>perf.cpu_clock</code></td>
2652     </tr>
2653     <tr>
2654       <td><code>task_clock</code></td>
2655       <td>the count of task clock time, as measured by a monotonic
2656           high-resolution CPU timer, specific to the task that
2657           is run by applications running on the platform</td>
2658       <td><code>perf.task_clock</code></td>
2659     </tr>
2660     <tr>
2661       <td><code>page_faults</code></td>
2662       <td>the count of page faults by applications running on the
2663           platform. This includes minor, major, invalid and other
2664           types of page faults</td>
2665       <td><code>perf.page_faults</code></td>
2666     </tr>
2667     <tr>
2668       <td><code>context_switches</code></td>
2669       <td>the count of context switches by applications running on
2670           the platform</td>
2671       <td><code>perf.context_switches</code></td>
2672     </tr>
2673     <tr>
2674       <td><code>cpu_migrations</code></td>
2675       <td>the count of CPU migrations, that is, where the process
2676           moved from one logical processor to another, by
2677           applications running on the platform</td>
2678       <td><code>perf.cpu_migrations</code></td>
2679     </tr>
2680     <tr>
2681       <td><code>page_faults_min</code></td>
2682       <td>the count of minor page faults, that is, where the
2683           page was present in the page cache, and therefore
2684           the fault avoided loading it from storage, by
2685           applications running on the platform</td>
2686       <td><code>perf.page_faults_min</code></td>
2687     </tr>
2688     <tr>
2689       <td><code>page_faults_maj</code></td>
2690       <td>the count of major page faults, that is, where the
2691           page was not present in the page cache, and
2692           therefore had to be fetched from storage, by
2693           applications running on the platform</td>
2694       <td><code>perf.page_faults_maj</code></td>
2695     </tr>
2696     <tr>
2697       <td><code>alignment_faults</code></td>
2698       <td>the count of alignment faults, that is when
2699           the load or store is not aligned properly, by
2700           applications running on the platform</td>
2701       <td><code>perf.alignment_faults</code></td>
2702     </tr>
2703     <tr>
2704       <td><code>emulation_faults</code></td>
2705       <td>the count of emulation faults, that is when
2706           the kernel traps on unimplemented instrucions
2707           and emulates them for user space, by
2708           applications running on the platform</td>
2709       <td><code>perf.emulation_faults</code></td>
2710     </tr>
2711   </table>
2712
2713     <h3><a id="elementsDevices">Devices</a></h3>
2714
2715     <p>
2716       The final set of XML elements are all used to describe devices
2717       provided to the guest domain. All devices occur as children
2718       of the main <code>devices</code> element.
2719       <span class="since">Since 0.1.3</span>
2720     </p>
2721
2722 <pre>
2723 ...
2724 &lt;devices&gt;
2725   &lt;emulator&gt;/usr/lib/xen/bin/qemu-dm&lt;/emulator&gt;
2726 &lt;/devices&gt;
2727 ...</pre>
2728
2729     <dl>
2730       <dt><a id="elementEmulator"><code>emulator</code></a></dt>
2731       <dd>
2732         The contents of the <code>emulator</code> element specify
2733         the fully qualified path to the device model emulator binary.
2734         The <a href="formatcaps.html">capabilities XML</a> specifies
2735         the recommended default emulator to use for each particular
2736         domain type / architecture combination.
2737       </dd>
2738     </dl>
2739
2740     <p>
2741       To help users identifying devices they care about, every
2742       device can have direct child <code>alias</code> element
2743       which then has <code>name</code> attribute where users can
2744       store identifier for the device. The identifier has to have
2745       "ua-" prefix and must be unique within the domain. Additionally, the
2746       identifier must consist only of the following characters:
2747       <code>[a-zA-Z0-9_-]</code>.
2748       <span class="since">Since 3.9.0</span>
2749     </p>
2750
2751 <pre>
2752 &lt;devices&gt;
2753   &lt;disk type='file'&gt;
2754     &lt;alias name='ua-myDisk'/&gt;
2755   &lt;/disk&gt;
2756   &lt;interface type='network' trustGuestRxFilters='yes'&gt;
2757     &lt;alias name='ua-myNIC'/&gt;
2758   &lt;/interface&gt;
2759   ...
2760 &lt;/devices&gt;
2761 </pre>
2762
2763     <h4><a id="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
2764
2765     <p>
2766       Any device that looks like a disk, be it a floppy, harddisk,
2767       cdrom, or paravirtualized driver is specified via the <code>disk</code>
2768       element.
2769     </p>
2770
2771 <pre>
2772 ...
2773 &lt;devices&gt;
2774   &lt;disk type='file' snapshot='external'&gt;
2775     &lt;driver name="tap" type="aio" cache="default"/&gt;
2776     &lt;source file='/var/lib/xen/images/fv0' startupPolicy='optional'&gt;
2777       &lt;seclabel relabel='no'/&gt;
2778     &lt;/source&gt;
2779     &lt;target dev='hda' bus='ide'/&gt;
2780     &lt;iotune&gt;
2781       &lt;total_bytes_sec&gt;10000000&lt;/total_bytes_sec&gt;
2782       &lt;read_iops_sec&gt;400000&lt;/read_iops_sec&gt;
2783       &lt;write_iops_sec&gt;100000&lt;/write_iops_sec&gt;
2784     &lt;/iotune&gt;
2785     &lt;boot order='2'/&gt;
2786     &lt;encryption type='...'&gt;
2787       ...
2788     &lt;/encryption&gt;
2789     &lt;shareable/&gt;
2790     &lt;serial&gt;
2791       ...
2792     &lt;/serial&gt;
2793   &lt;/disk&gt;
2794     ...
2795   &lt;disk type='network'&gt;
2796     &lt;driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/&gt;
2797     &lt;source protocol="sheepdog" name="image_name"&gt;
2798       &lt;host name="hostname" port="7000"/&gt;
2799     &lt;/source&gt;
2800     &lt;target dev="hdb" bus="ide"/&gt;
2801     &lt;boot order='1'/&gt;
2802     &lt;transient/&gt;
2803     &lt;address type='drive' controller='0' bus='1' unit='0'/&gt;
2804   &lt;/disk&gt;
2805   &lt;disk type='network'&gt;
2806     &lt;driver name="qemu" type="raw"/&gt;
2807     &lt;source protocol="rbd" name="image_name2"&gt;
2808       &lt;host name="hostname" port="7000"/&gt;
2809       &lt;snapshot name="snapname"/&gt;
2810       &lt;config file="/path/to/file"/&gt;
2811       &lt;auth username='myuser'&gt;
2812         &lt;secret type='ceph' usage='mypassid'/&gt;
2813       &lt;/auth&gt;
2814     &lt;/source&gt;
2815     &lt;target dev="hdc" bus="ide"/&gt;
2816   &lt;/disk&gt;
2817   &lt;disk type='block' device='cdrom'&gt;
2818     &lt;driver name='qemu' type='raw'/&gt;
2819     &lt;target dev='hdd' bus='ide' tray='open'/&gt;
2820     &lt;readonly/&gt;
2821   &lt;/disk&gt;
2822   &lt;disk type='network' device='cdrom'&gt;
2823     &lt;driver name='qemu' type='raw'/&gt;
2824     &lt;source protocol="http" name="url_path"&gt;
2825       &lt;host name="hostname" port="80"/&gt;
2826     &lt;/source&gt;
2827     &lt;target dev='hde' bus='ide' tray='open'/&gt;
2828     &lt;readonly/&gt;
2829   &lt;/disk&gt;
2830   &lt;disk type='network' device='cdrom'&gt;
2831     &lt;driver name='qemu' type='raw'/&gt;
2832     &lt;source protocol="https" name="url_path"&gt;
2833       &lt;host name="hostname" port="443"/&gt;
2834     &lt;/source&gt;
2835     &lt;target dev='hdf' bus='ide' tray='open'/&gt;
2836     &lt;readonly/&gt;
2837   &lt;/disk&gt;
2838   &lt;disk type='network' device='cdrom'&gt;
2839     &lt;driver name='qemu' type='raw'/&gt;
2840     &lt;source protocol="ftp" name="url_path"&gt;
2841       &lt;host name="hostname" port="21"/&gt;
2842     &lt;/source&gt;
2843     &lt;target dev='hdg' bus='ide' tray='open'/&gt;
2844     &lt;readonly/&gt;
2845   &lt;/disk&gt;
2846   &lt;disk type='network' device='cdrom'&gt;
2847     &lt;driver name='qemu' type='raw'/&gt;
2848     &lt;source protocol="ftps" name="url_path"&gt;
2849       &lt;host name="hostname" port="990"/&gt;
2850     &lt;/source&gt;
2851     &lt;target dev='hdh' bus='ide' tray='open'/&gt;
2852     &lt;readonly/&gt;
2853   &lt;/disk&gt;
2854   &lt;disk type='network' device='cdrom'&gt;
2855     &lt;driver name='qemu' type='raw'/&gt;
2856     &lt;source protocol="tftp" name="url_path"&gt;
2857       &lt;host name="hostname" port="69"/&gt;
2858     &lt;/source&gt;
2859     &lt;target dev='hdi' bus='ide' tray='open'/&gt;
2860     &lt;readonly/&gt;
2861   &lt;/disk&gt;
2862   &lt;disk type='block' device='lun'&gt;
2863     &lt;driver name='qemu' type='raw'/&gt;
2864     &lt;source dev='/dev/sda'&gt;
2865       &lt;reservations managed='no'&gt;
2866         &lt;source type='unix' path='/path/to/qemu-pr-helper' mode='client'/&gt;
2867       &lt;/reservations&gt;
2868     &lt;target dev='sda' bus='scsi'/&gt;
2869     &lt;address type='drive' controller='0' bus='0' target='3' unit='0'/&gt;
2870   &lt;/disk&gt;
2871   &lt;disk type='block' device='disk'&gt;
2872     &lt;driver name='qemu' type='raw'/&gt;
2873     &lt;source dev='/dev/sda'/&gt;
2874     &lt;geometry cyls='16383' heads='16' secs='63' trans='lba'/&gt;
2875     &lt;blockio logical_block_size='512' physical_block_size='4096'/&gt;
2876     &lt;target dev='hdj' bus='ide'/&gt;
2877   &lt;/disk&gt;
2878   &lt;disk type='volume' device='disk'&gt;
2879     &lt;driver name='qemu' type='raw'/&gt;
2880     &lt;source pool='blk-pool0' volume='blk-pool0-vol0'/&gt;
2881     &lt;target dev='hdk' bus='ide'/&gt;
2882   &lt;/disk&gt;
2883   &lt;disk type='network' device='disk'&gt;
2884     &lt;driver name='qemu' type='raw'/&gt;
2885     &lt;source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'&gt;
2886       &lt;host name='example.com' port='3260'/&gt;
2887       &lt;auth username='myuser'&gt;
2888         &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
2889       &lt;/auth&gt;
2890     &lt;/source&gt;
2891     &lt;target dev='vda' bus='virtio'/&gt;
2892   &lt;/disk&gt;
2893   &lt;disk type='network' device='lun'&gt;
2894     &lt;driver name='qemu' type='raw'/&gt;
2895     &lt;source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/1'&gt;
2896       &lt;host name='example.com' port='3260'/&gt;
2897       &lt;auth username='myuser'&gt;
2898         &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
2899       &lt;/auth&gt;
2900     &lt;/source&gt;
2901     &lt;target dev='sdb' bus='scsi'/&gt;
2902   &lt;/disk&gt;
2903   &lt;disk type='network' device='lun'&gt;
2904     &lt;driver name='qemu' type='raw'/&gt;
2905     &lt;source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'&gt;
2906       &lt;host name='example.com' port='3260'/&gt;
2907       &lt;initiator&gt;
2908         &lt;iqn name='iqn.2013-07.com.example:client'/&gt;
2909       &lt;/initiator&gt;
2910     &lt;/source&gt;
2911     &lt;target dev='sdb' bus='scsi'/&gt;
2912   &lt;/disk&gt;
2913   &lt;disk type='volume' device='disk'&gt;
2914     &lt;driver name='qemu' type='raw'/&gt;
2915     &lt;source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/&gt;
2916     &lt;target dev='vdb' bus='virtio'/&gt;
2917   &lt;/disk&gt;
2918   &lt;disk type='volume' device='disk'&gt;
2919     &lt;driver name='qemu' type='raw'/&gt;
2920     &lt;source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/&gt;
2921     &lt;target dev='vdc' bus='virtio'/&gt;
2922   &lt;/disk&gt;
2923   &lt;disk type='file' device='disk'&gt;
2924     &lt;driver name='qemu' type='qcow2' queues='4'/&gt;
2925     &lt;source file='/var/lib/libvirt/images/domain.qcow'/&gt;
2926     &lt;backingStore type='file'&gt;
2927       &lt;format type='qcow2'/&gt;
2928       &lt;source file='/var/lib/libvirt/images/snapshot.qcow'/&gt;
2929       &lt;backingStore type='block'&gt;
2930         &lt;format type='raw'/&gt;
2931         &lt;source dev='/dev/mapper/base'/&gt;
2932         &lt;backingStore/&gt;
2933       &lt;/backingStore&gt;
2934     &lt;/backingStore&gt;
2935     &lt;target dev='vdd' bus='virtio'/&gt;
2936   &lt;/disk&gt;
2937 &lt;/devices&gt;
2938 ...</pre>
2939
2940     <dl>
2941       <dt><code>disk</code></dt>
2942       <dd>The <code>disk</code> element is the main container for
2943       describing disks and supports the following attributes:
2944         <dl>
2945           <dt><code>type</code></dt>
2946             <dd>
2947             Valid values are "file", "block",
2948             "dir" (<span class="since">since 0.7.5</span>),
2949             "network" (<span class="since">since 0.8.7</span>), or
2950             "volume" (<span class="since">since 1.0.5</span>)
2951             and refer to the underlying source for the disk.
2952             <span class="since">Since 0.0.3</span>
2953             </dd>
2954           <dt><code>device</code></dt>
2955             <dd>
2956             Indicates how the disk is to be exposed to the guest OS. Possible
2957             values for this attribute are "floppy", "disk", "cdrom", and "lun",
2958             defaulting to "disk".
2959             <p>
2960             Using "lun" (<span class="since">since 0.9.10</span>) is only
2961             valid when the <code>type</code> is "block" or "network" for
2962             <code>protocol='iscsi'</code> or when the <code>type</code>
2963             is "volume" when using an iSCSI source <code>pool</code>
2964             for <code>mode</code> "host" or as an
2965             <a href="http://wiki.libvirt.org/page/NPIV_in_libvirt">NPIV</a>
2966             virtual Host Bus Adapter (vHBA) using a Fibre Channel storage pool.
2967             Configured in this manner, the LUN behaves identically to "disk",
2968             except that generic SCSI commands from the guest are accepted
2969             and passed through to the physical device. Also note that
2970             device='lun' will only be recognized for actual raw devices,
2971             but never for individual partitions or LVM partitions (in those
2972             cases, the kernel will reject the generic SCSI commands, making
2973             it identical to device='disk').
2974             <span class="since">Since 0.1.4</span>
2975             </p>
2976             </dd>
2977           <dt><code>model</code></dt>
2978             <dd>
2979             Indicates the emulated device model of the disk. Typically
2980             this is indicated solely by the <code>bus</code> property but
2981             for <code>bus</code> "virtio" the model can be specified further
2982             with "virtio-transitional", "virtio-non-transitional", or
2983             "virtio". See
2984             <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
2985             for more details.
2986             <span class="since">Since 5.2.0</span>
2987             </dd>
2988           <dt><code>rawio</code></dt>
2989             <dd>
2990             Indicates whether the disk needs rawio capability. Valid
2991             settings are "yes" or "no" (default is "no"). If any one disk
2992             in a domain has rawio='yes', rawio capability will be enabled
2993             for all disks in the domain (because, in the case of QEMU, this
2994             capability can only be set on a per-process basis). This attribute
2995             is only valid when device is "lun". NB, <code>rawio</code> intends
2996             to confine the capability per-device, however, current QEMU
2997             implementation gives the domain process broader capability
2998             than that (per-process basis, affects all the domain disks).
2999             To confine the capability as much as possible for QEMU driver
3000             as this stage, <code>sgio</code> is recommended, it's more
3001             secure than <code>rawio</code>.
3002             <span class="since">Since 0.9.10</span>
3003             </dd>
3004           <dt><code>sgio</code></dt>
3005             <dd>
3006             If supported by the hypervisor and OS, indicates whether
3007             unprivileged SG_IO commands are filtered for the disk. Valid
3008             settings are "filtered" or "unfiltered" where the default is
3009             "filtered". Only available when the <code>device</code> is 'lun'.
3010             <span class="since">Since 1.0.2</span>
3011             </dd>
3012           <dt><code>snapshot</code></dt>
3013             <dd>
3014             Indicates the default behavior of the disk during disk snapshots:
3015             "<code>internal</code>" requires a file format such as qcow2 that
3016             can store both the snapshot and the data changes since the snapshot;
3017             "<code>external</code>" will separate the snapshot from the live
3018             data; and "<code>no</code>" means the disk will not participate in
3019             snapshots. Read-only disks default to "<code>no</code>", while the
3020             default for other disks depends on the hypervisor's capabilities.
3021             Some hypervisors allow a per-snapshot choice as well, during
3022             <a href="formatsnapshot.html">domain snapshot creation</a>.
3023             Not all snapshot modes are supported; for example, enabling
3024             snapshots with a transient disk generally does not make sense.
3025             <span class="since">Since 0.9.5</span>
3026             </dd>
3027         </dl>
3028       </dd>
3029       <dt><code>source</code></dt>
3030       <dd>Representation of the disk <code>source</code> depends on the
3031       disk <code>type</code> attribute value as follows:
3032           <dl>
3033             <dt><code>file</code></dt>
3034               <dd>
3035               The <code>file</code> attribute specifies the fully-qualified
3036               path to the file holding the disk.
3037               <span class="since">Since 0.0.3</span>
3038               </dd>
3039             <dt><code>block</code></dt>
3040               <dd>
3041               The <code>dev</code> attribute specifies the fully-qualified path
3042               to the host device to serve as the disk.
3043               <span class="since">Since 0.0.3</span>
3044               </dd>
3045             <dt><code>dir</code></dt>
3046               <dd>
3047               The <code>dir</code> attribute specifies the fully-qualified path
3048               to the directory to use as the disk.
3049               <span class="since">Since 0.7.5</span>
3050               </dd>
3051             <dt><code>network</code></dt>
3052               <dd>
3053               The <code>protocol</code> attribute specifies the protocol to
3054               access to the requested image. Possible values are "nbd",
3055               "iscsi", "rbd", "sheepdog", "gluster" or "vxhs".
3056
3057               <p>If the <code>protocol</code> attribute is "rbd", "sheepdog",
3058               "gluster", or "vxhs", an additional attribute <code>name</code>
3059               is mandatory to specify which volume/image will be used.
3060               </p>
3061
3062               <p>For "nbd", the <code>name</code> attribute is optional. TLS
3063               transport for NBD can be enabled by setting the <code>tls</code>
3064               attribute to <code>yes</code>. For the QEMU hypervisor, usage of
3065               a TLS environment can also be globally controlled on the host by
3066               the <code>nbd_tls</code> and <code>nbd_tls_x509_cert_dir</code> in
3067               /etc/libvirt/qemu.conf.
3068               ('tls' <span class="since">Since 4.5.0</span>)
3069               </p>
3070
3071               <p>For "iscsi" (<span class="since">since 1.0.4</span>), the
3072               <code>name</code> attribute may include a logical unit number,
3073               separated from the target's name by a slash (e.g.,
3074               <code>iqn.2013-07.com.example:iscsi-pool/1</code>). If not
3075               specified, the default LUN is zero.
3076               </p>
3077
3078               <p>For "vxhs" (<span class="since">since 3.8.0</span>), the
3079               <code>name</code> is the UUID of the volume, assigned by the
3080               HyperScale server. Additionally, an optional attribute
3081               <code>tls</code> (QEMU only) can be used to control whether a
3082               VxHS block device would utilize a hypervisor configured TLS
3083               X.509 certificate environment in order to encrypt the data
3084               channel. For the QEMU hypervisor, usage of a TLS environment can
3085               also be globally controlled on the host by the
3086               <code>vxhs_tls</code> and <code>vxhs_tls_x509_cert_dir</code> or
3087               <code>default_tls_x509_cert_dir</code> settings in the file
3088               /etc/libvirt/qemu.conf. If <code>vxhs_tls</code> is enabled,
3089               then unless the domain <code>tls</code> attribute is set to "no",
3090               libvirt will use the host configured TLS environment. If the
3091               <code>tls</code> attribute is set to "yes", then regardless of
3092               the qemu.conf setting, TLS authentication will be attempted.
3093               </p>
3094               <span class="since">Since 0.8.7</span>
3095               </dd>
3096             <dt><code>volume</code></dt>
3097               <dd>
3098               The underlying disk source is represented by attributes
3099               <code>pool</code> and <code>volume</code>. Attribute
3100               <code>pool</code> specifies the name of the
3101               <a href="formatstorage.html">storage pool</a> (managed
3102               by libvirt) where the disk source resides. Attribute
3103               <code>volume</code> specifies the name of storage volume (managed
3104               by libvirt) used as the disk source. The value for the
3105               <code>volume</code> attribute will be the output from the "Name"
3106               column of a <code>virsh vol-list [pool-name]</code> command.
3107               <p>
3108               Use the attribute <code>mode</code>
3109               (<span class="since">since 1.1.1</span>) to indicate how to
3110               represent the LUN as the disk source. Valid values are
3111               "direct" and "host". If <code>mode</code> is not specified,
3112               the default is to use "host".
3113
3114               Using "direct" as the <code>mode</code> value indicates to use
3115               the <a href="formatstorage.html">storage pool's</a>
3116               <code>source</code> element <code>host</code> attribute as
3117               the disk source to generate the libiscsi URI (e.g.
3118               'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1').
3119
3120               Using "host" as the <code>mode</code> value indicates to use the
3121               LUN's path as it shows up on host (e.g.
3122               'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1').
3123
3124               Using a LUN from an iSCSI source pool provides the same
3125               features as a <code>disk</code> configured using
3126               <code>type</code> 'block' or 'network' and <code>device</code>
3127               of 'lun' with respect to how the LUN is presented to and
3128               may be used by the guest.
3129
3130               <span class="since">Since 1.0.5</span>
3131               </p>
3132               </dd>
3133           </dl>
3134         With "file", "block", and "volume", one or more optional
3135         sub-elements <code>seclabel</code>, <a href="#seclabel">described
3136         below</a> (and <span class="since">since 0.9.9</span>), can be
3137         used to override the domain security labeling policy for just
3138         that source file. (NB, for "volume" type disk, <code>seclabel</code>
3139         is only valid when the specified storage volume is of 'file' or
3140         'block' type).
3141         <p>
3142         The <code>source</code> element may also have the <code>index</code>
3143         attribute with same semantics the <a href='#elementsDiskBackingStoreIndex'>
3144         <code>index</code></a> attribute of <code>backingStore</code>
3145         </p>
3146         <p>
3147         The <code>source</code> element may contain the following sub elements:
3148         </p>
3149
3150         <dl>
3151           <dt><code>host</code></dt>
3152           <dd>
3153             <p>
3154             When the disk <code>type</code> is "network", the <code>source</code>
3155             may have zero or more <code>host</code> sub-elements used to
3156             specify the hosts to connect.
3157
3158             The <code>host</code> element supports 4 attributes, viz.  "name",
3159             "port", "transport" and "socket", which specify the hostname,
3160             the port number, transport type and path to socket, respectively.
3161             The meaning of this element and the number of the elements depend
3162             on the protocol attribute.
3163             </p>
3164             <table class="top_table">
3165               <tr>
3166                 <th> Protocol </th>
3167                 <th> Meaning </th>
3168                 <th> Number of hosts </th>
3169                 <th> Default port </th>
3170               </tr>
3171               <tr>
3172                 <td> nbd </td>
3173                 <td> a server running nbd-server </td>
3174                 <td> only one </td>
3175                 <td> 10809 </td>
3176               </tr>
3177               <tr>
3178                 <td> iscsi </td>
3179                 <td> an iSCSI server </td>
3180                 <td> only one </td>
3181                 <td> 3260 </td>
3182               </tr>
3183               <tr>
3184                 <td> rbd </td>
3185                 <td> monitor servers of RBD </td>
3186                 <td> one or more </td>
3187                 <td> librados default </td>
3188               </tr>
3189               <tr>
3190                 <td> sheepdog </td>
3191                 <td> one of the sheepdog servers (default is localhost:7000) </td>
3192                 <td> zero or one </td>
3193                 <td> 7000 </td>
3194               </tr>
3195               <tr>
3196                 <td> gluster </td>
3197                 <td> a server running glusterd daemon </td>
3198                 <td> one or more (<span class="since">Since 2.1.0</span>), just one prior to that </td>
3199                 <td> 24007 </td>
3200               </tr>
3201               <tr>
3202                 <td> vxhs </td>
3203                 <td> a server running Veritas HyperScale daemon </td>
3204                 <td> only one </td>
3205                 <td> 9999 </td>
3206               </tr>
3207             </table>
3208             <p>
3209             gluster supports "tcp", "rdma", "unix" as valid values for the
3210             transport attribute.  nbd supports "tcp" and "unix".  Others only
3211             support "tcp".  If nothing is specified, "tcp" is assumed. If the
3212             transport is "unix", the socket attribute specifies the path to an
3213             AF_UNIX socket.
3214             </p>
3215           </dd>
3216           <dt><code>snapshot</code></dt>
3217           <dd>
3218             The <code>name</code> attribute of <code>snapshot</code> element can
3219             optionally specify an internal snapshot name to be used as the
3220             source for storage protocols.
3221             Supported for 'rbd' <span class="since">since 1.2.11 (QEMU only).</span>
3222           </dd>
3223           <dt><code>config</code></dt>
3224           <dd>
3225             The <code>file</code> attribute for the <code>config</code> element
3226             provides a fully qualified path to a configuration file to be
3227             provided as a parameter to the client of a networked storage
3228             protocol. Supported for 'rbd' <span class="since">since 1.2.11
3229             (QEMU only).</span>
3230           </dd>
3231           <dt><code>auth</code></dt>
3232           <dd><span class="since">Since libvirt 3.9.0</span>, the
3233             <code>auth</code> element is supported for a disk
3234             <code>type</code> "network" that is using a <code>source</code>
3235             element with the <code>protocol</code> attributes "rbd" or "iscsi".
3236             If present, the <code>auth</code> element provides the
3237             authentication credentials needed to access the source.  It
3238             includes a mandatory attribute <code>username</code>, which
3239             identifies the username to use during authentication, as well
3240             as a sub-element <code>secret</code> with mandatory
3241             attribute <code>type</code>, to tie back to
3242             a <a href="formatsecret.html">libvirt secret object</a> that
3243             holds the actual password or other credentials (the domain XML
3244             intentionally does not expose the password, only the reference
3245             to the object that does manage the password).
3246             Known secret types are "ceph" for Ceph RBD network sources and
3247             "iscsi" for CHAP authentication of iSCSI targets.
3248             Both will require either a <code>uuid</code> attribute
3249             with the UUID of the secret object or a <code>usage</code>
3250             attribute matching the key that was specified in the
3251             secret object.
3252           </dd>
3253           <dt><code>encryption</code></dt>
3254           <dd><span class="since">Since libvirt 3.9.0</span>, the
3255             <code>encryption</code> can be a sub-element of the
3256             <code>source</code> element for encrypted storage sources.
3257             If present, specifies how the storage source is encrypted
3258             See the
3259             <a href="formatstorageencryption.html">Storage Encryption</a>
3260             page for more information.
3261             <p/>
3262             Note that the 'qcow' format of encryption is broken and thus is no
3263             longer supported for use with disk images.
3264             (<span class="since">Since libvirt 4.5.0</span>)
3265           </dd>
3266           <dt><code>reservations</code></dt>
3267           <dd><span class="since">Since libvirt 4.4.0</span>, the
3268             <code>reservations</code> can be a sub-element of the
3269             <code>source</code> element for storage sources (QEMU driver only).
3270             If present it enables persistent reservations for SCSI
3271             based disks. The element has one mandatory attribute
3272             <code>managed</code> with accepted values <code>yes</code> and
3273             <code>no</code>. If <code>managed</code> is enabled libvirt prepares
3274             and manages any resources needed. When the persistent reservations
3275             are unmanaged, then the hypervisor acts as a client and the path to
3276             the server socket must be provided in the child element
3277             <code>source</code>, which currently accepts only the following
3278             attributes:
3279             <code>type</code> with one value <code>unix</code>,
3280             <code>path</code> path to the socket, and
3281             finally <code>mode</code> which accepts one value
3282             <code>client</code> specifying the role of hypervisor.
3283             It's recommended to allow libvirt manage the persistent
3284             reservations.
3285           </dd>
3286           <dt><code>initiator</code></dt>
3287           <dd><span class="since">Since libvirt 4.7.0</span>, the
3288             <code>initiator</code> element is supported for a disk
3289             <code>type</code> "network" that is using a <code>source</code>
3290             element with the <code>protocol</code> attribute "iscsi".
3291             If present, the <code>initiator</code> element provides the
3292             initiator IQN needed to access the source via mandatory
3293             attribute <code>name</code>.
3294           </dd>
3295         </dl>
3296
3297         <p>
3298         For a "file" or "volume" disk type which represents a cdrom or floppy
3299         (the <code>device</code> attribute), it is possible to define
3300         policy what to do with the disk if the source file is not accessible.
3301         (NB, <code>startupPolicy</code> is not valid for "volume" disk unless
3302          the specified storage volume is of "file" type). This is done by the
3303         <code>startupPolicy</code> attribute
3304         (<span class="since">since 0.9.7</span>),
3305         accepting these values:
3306         </p>
3307         <table class="top_table">
3308           <tr>
3309             <td> mandatory </td>
3310             <td> fail if missing for any reason (the default) </td>
3311           </tr>
3312           <tr>
3313             <td> requisite </td>
3314             <td> fail if missing on boot up,
3315                  drop if missing on migrate/restore/revert </td>
3316           </tr>
3317           <tr>
3318             <td> optional </td>
3319             <td> drop if missing at any start attempt </td>
3320           </tr>
3321         </table>
3322         <p>
3323         <span class="since">Since 1.1.2</span> the <code>startupPolicy</code>
3324         is extended to support hard disks besides cdrom and floppy. On guest
3325         cold bootup, if a certain disk is not accessible or its disk chain is
3326         broken, with startupPolicy 'optional' the guest will drop this disk.
3327         This feature doesn't support migration currently.
3328         </p>
3329         </dd>
3330       <dt><code>backingStore</code></dt>
3331       <dd>
3332         This element describes the backing store used by the disk
3333         specified by sibling <code>source</code> element. It is
3334         currently ignored on input and only used for output to
3335         describe the detected backing chains of running
3336         domains <span class="since">since 1.2.4</span> (although a
3337         future version of libvirt may start accepting chains on input,
3338         or output information for offline domains). An
3339         empty <code>backingStore</code> element means the sibling
3340         source is self-contained and is not based on any backing
3341         store. For backing chain information to be accurate, the
3342         backing format must be correctly specified in the metadata of
3343         each file of the chain (files created by libvirt satisfy this
3344         property, but using existing external files for snapshot or
3345         block copy operations requires the end user to pre-create the
3346         file correctly). The following attributes are
3347         supported in <code>backingStore</code>:
3348         <dl>
3349           <dt><code>type</code></dt>
3350           <dd>
3351             The <code>type</code> attribute represents the type of disk used
3352             by the backing store, see disk type attribute above for more
3353             details and possible values.
3354           </dd>
3355           <dt><code><a id="elementsDiskBackingStoreIndex">index</a></code></dt>
3356           <dd>
3357             This attribute is only valid in output (and ignored on input) and
3358             it can be used to refer to a specific part of the disk chain when
3359             doing block operations (such as via the
3360             <code>virDomainBlockRebase</code> API). For example,
3361             <code>vda[2]</code> refers to the backing store with
3362             <code>index='2'</code> of the disk with <code>vda</code> target.
3363           </dd>
3364         </dl>
3365         Moreover, <code>backingStore</code> supports the following sub-elements:
3366         <dl>
3367           <dt><code>format</code></dt>
3368           <dd>
3369             The <code>format</code> element contains <code>type</code>
3370             attribute which specifies the internal format of the backing
3371             store, such as <code>raw</code> or <code>qcow2</code>.
3372           </dd>
3373           <dt><code>source</code></dt>
3374           <dd>
3375             This element has the same structure as the <code>source</code>
3376             element in <code>disk</code>. It specifies which file, device,
3377             or network location contains the data of the described backing
3378             store.
3379           </dd>
3380           <dt><code>backingStore</code></dt>
3381           <dd>
3382             If the backing store is not self-contained, the next element
3383             in the chain is described by nested <code>backingStore</code>
3384             element.
3385           </dd>
3386         </dl>
3387       </dd>
3388       <dt><code>mirror</code></dt>
3389       <dd>
3390         This element is present if the hypervisor has started a
3391         long-running block job operation, where the mirror location in
3392         the <code>source</code> sub-element will eventually have the
3393         same contents as the source, and with the file format in the
3394         sub-element <code>format</code> (which might differ from the
3395         format of the source).  The details of the <code>source</code>
3396         sub-element are determined by the <code>type</code> attribute
3397         of the mirror, similar to what is done for the
3398         overall <code>disk</code> device element. The <code>job</code>
3399         attribute mentions which API started the operation ("copy" for
3400         the <code>virDomainBlockRebase</code> API, or "active-commit"
3401         for the <code>virDomainBlockCommit</code>
3402         API), <span class="since">since 1.2.7</span>.  The
3403         attribute <code>ready</code>, if present, tracks progress of
3404         the job: <code>yes</code> if the disk is known to be ready to
3405         pivot, or, <span class="since">since
3406         1.2.7</span>, <code>abort</code> or <code>pivot</code> if the
3407         job is in the process of completing.  If <code>ready</code> is
3408         not present, the disk is probably still
3409         copying.  For now, this element only valid in output; it is
3410         ignored on input.  The <code>source</code> sub-element exists
3411         for all two-phase jobs <span class="since">since 1.2.6</span>.
3412         Older libvirt supported only block copy to a
3413         file, <span class="since">since 0.9.12</span>; for
3414         compatibility with older clients, such jobs include redundant
3415         information in the attributes <code>file</code>
3416         and <code>format</code> in the <code>mirror</code> element.
3417       </dd>
3418       <dt><code>target</code></dt>
3419       <dd>The <code>target</code> element controls the bus / device
3420         under which the disk is exposed to the guest
3421         OS. The <code>dev</code> attribute indicates the "logical"
3422         device name. The actual device name specified is not
3423         guaranteed to map to the device name in the guest OS. Treat it
3424         as a device ordering hint.  The optional <code>bus</code>
3425         attribute specifies the type of disk device to emulate;
3426         possible values are driver specific, with typical values being
3427         "ide", "scsi", "virtio", "xen", "usb", "sata", or
3428         "sd" <span class="since">"sd" since 1.1.2</span>. If omitted, the bus
3429         type is inferred from the style of the device name (e.g. a device named
3430         'sda' will typically be exported using a SCSI bus). The optional
3431         attribute <code>tray</code> indicates the tray status of the
3432         removable disks (i.e. CDROM or Floppy disk), the value can be either
3433         "open" or "closed", defaults to "closed". NB, the value of
3434         <code>tray</code> could be updated while the domain is running.
3435         The optional attribute <code>removable</code> sets the
3436         removable flag for USB disks, and its value can be either "on"
3437         or "off", defaulting to "off". <span class="since">Since
3438         0.0.3; <code>bus</code> attribute since 0.4.3;
3439         <code>tray</code> attribute since 0.9.11; "usb" attribute value since
3440         after 0.4.4; "sata" attribute value since 0.9.7; "removable" attribute
3441         value since 1.1.3</span>
3442       </dd>
3443       <dt><code>iotune</code></dt>
3444       <dd>The optional <code>iotune</code> element provides the
3445         ability to provide additional per-device I/O tuning, with
3446         values that can vary for each device (contrast this to
3447         the <a href="#elementsBlockTuning"><code>&lt;blkiotune&gt;</code></a>
3448         element, which applies globally to the domain).  Currently,
3449         the only tuning available is Block I/O throttling for qemu.
3450         This element has optional sub-elements; any sub-element not
3451         specified or given with a value of 0 implies no
3452         limit.  <span class="since">Since 0.9.8</span>
3453         <dl>
3454           <dt><code>total_bytes_sec</code></dt>
3455           <dd>The optional <code>total_bytes_sec</code> element is the
3456             total throughput limit in bytes per second.  This cannot
3457             appear with <code>read_bytes_sec</code>
3458             or <code>write_bytes_sec</code>.</dd>
3459           <dt><code>read_bytes_sec</code></dt>
3460           <dd>The optional <code>read_bytes_sec</code> element is the
3461             read throughput limit in bytes per second.</dd>
3462           <dt><code>write_bytes_sec</code></dt>
3463           <dd>The optional <code>write_bytes_sec</code> element is the
3464             write throughput limit in bytes per second.</dd>
3465           <dt><code>total_iops_sec</code></dt>
3466           <dd>The optional <code>total_iops_sec</code> element is the
3467             total I/O operations per second.  This cannot
3468             appear with <code>read_iops_sec</code>
3469             or <code>write_iops_sec</code>.</dd>
3470           <dt><code>read_iops_sec</code></dt>
3471           <dd>The optional <code>read_iops_sec</code> element is the
3472             read I/O operations per second.</dd>
3473           <dt><code>write_iops_sec</code></dt>
3474           <dd>The optional <code>write_iops_sec</code> element is the
3475             write I/O operations per second.</dd>
3476           <dt><code>total_bytes_sec_max</code></dt>
3477           <dd>The optional <code>total_bytes_sec_max</code> element is the
3478             maximum total throughput limit in bytes per second.  This cannot
3479             appear with <code>read_bytes_sec_max</code>
3480             or <code>write_bytes_sec_max</code>.</dd>
3481           <dt><code>read_bytes_sec_max</code></dt>
3482           <dd>The optional <code>read_bytes_sec_max</code> element is the
3483             maximum read throughput limit in bytes per second.</dd>
3484           <dt><code>write_bytes_sec_max</code></dt>
3485           <dd>The optional <code>write_bytes_sec_max</code> element is the
3486             maximum write throughput limit in bytes per second.</dd>
3487           <dt><code>total_iops_sec_max</code></dt>
3488           <dd>The optional <code>total_iops_sec_max</code> element is the
3489             maximum total I/O operations per second.  This cannot
3490             appear with <code>read_iops_sec_max</code>
3491             or <code>write_iops_sec_max</code>.</dd>
3492           <dt><code>read_iops_sec_max</code></dt>
3493           <dd>The optional <code>read_iops_sec_max</code> element is the
3494             maximum read I/O operations per second.</dd>
3495           <dt><code>write_iops_sec_max</code></dt>
3496           <dd>The optional <code>write_iops_sec_max</code> element is the
3497             maximum write I/O operations per second.</dd>
3498           <dt><code>size_iops_sec</code></dt>
3499           <dd>The optional <code>size_iops_sec</code> element is the
3500             size of I/O operations per second.
3501           <p>
3502             <span class="since">Throughput limits since 1.2.11 and QEMU 1.7</span>
3503           </p>
3504           </dd>
3505           <dt><code>group_name</code></dt>
3506           <dd>The optional <code>group_name</code> provides the cability
3507             to share I/O throttling quota between multiple drives. This
3508             prevents end-users from circumventing a hosting provider's
3509             throttling policy by splitting 1 large drive in N small drives
3510             and getting N times the normal throttling quota. Any name may
3511             be used.
3512           <p>
3513             <span class="since">group_name since 3.0.0 and QEMU 2.4</span>
3514           </p>
3515           </dd>
3516           <dt><code>total_bytes_sec_max_length</code></dt>
3517           <dd>The optional <code>total_bytes_sec_max_length</code>
3518             element is the maximum duration in seconds for the
3519             <code>total_bytes_sec_max</code> burst period. Only valid
3520             when the <code>total_bytes_sec_max</code> is set.</dd>
3521           <dt><code>read_bytes_sec_max_length</code></dt>
3522           <dd>The optional <code>read_bytes_sec_max_length</code>
3523             element is the maximum duration in seconds for the
3524             <code>read_bytes_sec_max</code> burst period. Only valid
3525             when the <code>read_bytes_sec_max</code> is set.</dd>
3526           <dt><code>write_bytes_sec_max</code></dt>
3527           <dd>The optional <code>write_bytes_sec_max_length</code>
3528             element is the maximum duration in seconds for the
3529             <code>write_bytes_sec_max</code> burst period. Only valid
3530             when the <code>write_bytes_sec_max</code> is set.</dd>
3531           <dt><code>total_iops_sec_max_length</code></dt>
3532           <dd>The optional <code>total_iops_sec_max_length</code>
3533             element is the maximum duration in seconds for the
3534             <code>total_iops_sec_max</code> burst period. Only valid
3535             when the <code>total_iops_sec_max</code> is set.</dd>
3536           <dt><code>read_iops_sec_max_length</code></dt>
3537           <dd>The optional <code>read_iops_sec_max_length</code>
3538             element is the maximum duration in seconds for the
3539             <code>read_iops_sec_max</code> burst period. Only valid
3540             when the <code>read_iops_sec_max</code> is set.</dd>
3541           <dt><code>write_iops_sec_max</code></dt>
3542           <dd>The optional <code>write_iops_sec_max_length</code>
3543             element is the maximum duration in seconds for the
3544             <code>write_iops_sec_max</code> burst period. Only valid
3545             when the <code>write_iops_sec_max</code> is set.
3546           <p>
3547             <span class="since">Throughput length since 2.4.0 and QEMU 2.6</span>
3548           </p>
3549           </dd>
3550         </dl>
3551       </dd>
3552       <dt><code>driver</code></dt>
3553       <dd>
3554         The optional driver element allows specifying further details
3555         related to the hypervisor driver used to provide the disk.
3556         <span class="since">Since 0.1.8</span>
3557         <ul>
3558           <li>
3559             If the hypervisor supports multiple backend drivers, then
3560             the <code>name</code> attribute selects the primary
3561             backend driver name, while the optional <code>type</code>
3562             attribute provides the sub-type.  For example, xen
3563             supports a name of "tap", "tap2", "phy", or "file", with a
3564             type of "aio", while qemu only supports a name of "qemu",
3565             but multiple types including "raw", "bochs", "qcow2", and
3566             "qed".
3567           </li>
3568           <li>
3569             The optional <code>cache</code> attribute controls the
3570             cache mechanism, possible values are "default", "none",
3571             "writethrough", "writeback", "directsync" (like
3572             "writethrough", but it bypasses the host page cache) and
3573             "unsafe" (host may cache all disk io, and sync requests from
3574             guest are ignored).
3575             <span class="since">
3576               Since 0.6.0,
3577               "directsync" since 0.9.5,
3578               "unsafe" since 0.9.7
3579             </span>
3580           </li>
3581           <li>
3582             The optional <code>error_policy</code> attribute controls
3583             how the hypervisor will behave on a disk read or write
3584             error, possible values are "stop", "report", "ignore", and
3585             "enospace".<span class="since">Since 0.8.0, "report" since
3586             0.9.7</span> The default is left to the discretion of the
3587             hypervisor. There is also an
3588             optional <code>rerror_policy</code> that controls behavior
3589             for read errors only. <span class="since">Since
3590             0.9.7</span>. If no rerror_policy is given, error_policy
3591             is used for both read and write errors. If rerror_policy
3592             is given, it overrides the <code>error_policy</code> for
3593             read errors. Also note that "enospace" is not a valid
3594             policy for read errors, so if <code>error_policy</code> is
3595             set to "enospace" and no <code>rerror_policy</code> is
3596             given, the read error policy will be left at its default.
3597           </li>
3598           <li>
3599             The optional <code>io</code> attribute controls specific
3600             policies on I/O; qemu guests support "threads" and
3601             "native". <span class="since">Since 0.8.8</span>
3602           </li>
3603           <li>
3604             The optional <code>ioeventfd</code> attribute allows users to
3605             set <a href='https://patchwork.kernel.org/patch/43390/'>
3606             domain I/O asynchronous handling</a> for disk device.
3607             The default is left to the discretion of the hypervisor.
3608             Accepted values are "on" and "off". Enabling this allows
3609             qemu to execute VM while a separate thread handles I/O.
3610             Typically guests experiencing high system CPU utilization
3611             during I/O will benefit from this. On the other hand,
3612             on overloaded host it could increase guest I/O latency.
3613             <span class="since">Since 0.9.3 (QEMU and KVM only)</span>
3614             <b>In general you should leave this option alone, unless you
3615             are very certain you know what you are doing.</b>
3616           </li>
3617           <li>
3618             The optional <code>event_idx</code> attribute controls
3619             some aspects of device event processing. The value can be
3620             either 'on' or 'off' - if it is on, it will reduce the
3621             number of interrupts and exits for the guest. The default
3622             is determined by QEMU; usually if the feature is
3623             supported, default is on. In case there is a situation
3624             where this behavior is suboptimal, this attribute provides
3625             a way to force the feature off.
3626             <span class="since">Since 0.9.5 (QEMU and KVM only)</span>
3627             <b>In general you should leave this option alone, unless you
3628             are very certain you know what you are doing.</b>
3629           </li>
3630           <li>
3631             The optional <code>copy_on_read</code> attribute controls
3632             whether to copy read backing file into the image file. The
3633             value can be either "on" or "off".
3634             Copy-on-read avoids accessing the same backing file sectors
3635             repeatedly and is useful when the backing file is over a slow
3636             network. By default copy-on-read is off.
3637             <span class='since'>Since 0.9.10 (QEMU and KVM only)</span>
3638           </li>
3639           <li>
3640             The optional <code>discard</code> attribute controls whether
3641             discard requests (also known as "trim" or "unmap") are
3642             ignored or passed to the filesystem. The value can be either
3643             "unmap" (allow the discard request to be passed) or "ignore"
3644             (ignore the discard request).
3645             <span class='since'>Since 1.0.6 (QEMU and KVM only)</span>
3646           </li>
3647           <li>
3648             The optional <code>detect_zeroes</code> attribute controls whether
3649             to detect zero write requests.  The value can be "off", "on" or
3650             "unmap".  First two values turn the detection off and on,
3651             respectively.  The third value ("unmap") turns the detection on
3652             and additionally tries to discard such areas from the image based
3653             on the value of <code>discard</code> above (it will act as "on"
3654             if <code>discard</code> is set to "ignore").  NB enabling the
3655             detection is a compute intensive operation, but can save file
3656             space and/or time on slow media.
3657             <span class='since'>Since 2.0.0</span>
3658           </li>
3659           <li>
3660             The optional <code>iothread</code> attribute assigns the
3661             disk to an IOThread as defined by the range for the domain
3662             <a href="#elementsIOThreadsAllocation"><code>iothreads</code></a>
3663             value. Multiple disks may be assigned to the same IOThread and
3664             are numbered from 1 to the domain iothreads value. Available
3665             for a disk device <code>target</code> configured to use "virtio"
3666             <code>bus</code> and "pci" or "ccw" <code>address</code> types.
3667             <span class='since'>Since 1.2.8 (QEMU 2.1)</span>
3668           </li>
3669           <li>
3670             The optional <code>queues</code> attribute specifies the number of
3671             virt queues for virtio-blk. (<span class="since">Since 3.9.0</span>)
3672           </li>
3673           <li>
3674           For virtio disks,
3675           <a href="#elementsVirtio">Virtio-specific options</a> can also be
3676           set. (<span class="since">Since 3.5.0</span>)
3677           </li>
3678         </ul>
3679       </dd>
3680       <dt><code>backenddomain</code></dt>
3681       <dd>The optional <code>backenddomain</code> element allows specifying a
3682           backend domain (aka driver domain) hosting the disk.  Use the
3683           <code>name</code> attribute to specify the backend domain name.
3684           <span class="since">Since 1.2.13 (Xen only)</span>
3685       </dd>
3686       <dt><code>boot</code></dt>
3687       <dd>Specifies that the disk is bootable. The <code>order</code>
3688         attribute determines the order in which devices will be tried during
3689         boot sequence. On the S390 architecture only the first boot device is
3690         used. The optional <code>loadparm</code> attribute is an 8 character
3691         string which can be queried by guests on S390 via sclp or diag 308.
3692         Linux guests on S390 can use <code>loadparm</code> to select a boot
3693         entry. <span class="since">Since 3.5.0</span>
3694         The per-device <code>boot</code> elements cannot be used together
3695         with general boot elements in
3696         <a href="#elementsOSBIOS">BIOS bootloader</a> section.
3697         <span class="since">Since 0.8.8</span>
3698       </dd>
3699       <dt><code>encryption</code></dt>
3700       <dd>Starting with <span class="since">libvirt 3.9.0</span> the
3701         <code>encryption</code> element is preferred to be a sub-element
3702         of the <code>source</code> element. If present, specifies how the
3703         volume is encrypted using "qcow". See the
3704         <a href="formatstorageencryption.html">Storage Encryption</a> page
3705         for more information.
3706       </dd>
3707       <dt><code>readonly</code></dt>
3708       <dd>If present, this indicates the device cannot be modified by
3709         the guest.  For now, this is the default for disks with
3710         attribute <code>device='cdrom'</code>.
3711       </dd>
3712       <dt><code>shareable</code></dt>
3713       <dd>If present, this indicates the device is expected to be shared
3714           between domains (assuming the hypervisor and OS support this),
3715           which means that caching should be deactivated for that device.
3716       </dd>
3717       <dt><code>transient</code></dt>
3718       <dd>If present, this indicates that changes to the device
3719         contents should be reverted automatically when the guest
3720         exits.  With some hypervisors, marking a disk transient
3721         prevents the domain from participating in migration or
3722         snapshots. <span class="since">Since 0.9.5</span>
3723       </dd>
3724       <dt><code>serial</code></dt>
3725       <dd>If present, this specify serial number of virtual hard drive.
3726           For example, it may look
3727           like <code>&lt;serial&gt;WD-WMAP9A966149&lt;/serial&gt;</code>.
3728           Not supported for scsi-block devices, that is those using
3729           disk <code>type</code> 'block' using <code>device</code> 'lun'
3730           on <code>bus</code> 'scsi'.
3731           <span class="since">Since 0.7.1</span>
3732       </dd>
3733       <dt><code>wwn</code></dt>
3734       <dd>If present, this element specifies the WWN (World Wide Name)
3735         of a virtual hard disk or CD-ROM drive. It must be composed
3736         of 16 hexadecimal digits.
3737         <span class='since'>Since 0.10.1</span>
3738       </dd>
3739       <dt><code>vendor</code></dt>
3740       <dd>If present, this element specifies the vendor of a virtual hard
3741         disk or CD-ROM device. It must not be longer than 8 printable
3742         characters.
3743         <span class='since'>Since 1.0.1</span>
3744       </dd>
3745       <dt><code>product</code></dt>
3746       <dd>If present, this element specifies the product of a virtual hard
3747         disk or CD-ROM device. It must not be longer than 16 printable
3748         characters.
3749         <span class='since'>Since 1.0.1</span>
3750       </dd>
3751       <dt><code>address</code></dt>
3752       <dd>If present, the <code>address</code> element ties the disk
3753         to a given slot of a controller (the
3754         actual <code>&lt;controller&gt;</code> device can often be
3755         inferred by libvirt, although it can
3756         be <a href="#elementsControllers">explicitly specified</a>).
3757         The <code>type</code> attribute is mandatory, and is typically
3758         "pci" or "drive".  For a "pci" controller, additional
3759         attributes for <code>bus</code>, <code>slot</code>,
3760         and <code>function</code> must be present, as well as
3761         optional <code>domain</code> and <code>multifunction</code>.
3762         Multifunction defaults to 'off'; any other value requires
3763         QEMU 0.1.3 and <span class="since">libvirt 0.9.7</span>.  For a
3764         "drive" controller, additional attributes
3765         <code>controller</code>, <code>bus</code>, <code>target</code>
3766         (<span class="since">libvirt 0.9.11</span>), and <code>unit</code>
3767         are available, each defaulting to 0.
3768       </dd>
3769       <dt><code>auth</code></dt>
3770       <dd>Starting with <span class="since">libvirt 3.9.0</span> the
3771         <code>auth</code> element is preferred to be a sub-element of
3772         the <code>source</code> element. The element is still read and
3773         managed as a <code>disk</code> sub-element. It is invalid to use
3774         <code>auth</code> as both a sub-element of <code>disk</code>
3775         and <code>source</code>. The <code>auth</code> element was
3776         introduced as a <code>disk</code> sub-element in
3777         <span class="since">libvirt 0.9.7.</span>
3778       </dd>
3779       <dt><code>geometry</code></dt>
3780       <dd>The optional <code>geometry</code> element provides the
3781         ability to override geometry settings. This mostly useful for
3782         S390 DASD-disks or older DOS-disks.  <span class="since">0.10.0</span>
3783         <dl>
3784           <dt><code>cyls</code></dt>
3785           <dd>The <code>cyls</code> attribute is the
3786             number of cylinders. </dd>
3787           <dt><code>heads</code></dt>
3788           <dd>The <code>heads</code> attribute is the
3789             number of heads. </dd>
3790           <dt><code>secs</code></dt>
3791           <dd>The <code>secs</code> attribute is the
3792             number of sectors per track. </dd>
3793           <dt><code>trans</code></dt>
3794           <dd>The optional <code>trans</code> attribute is the
3795             BIOS-Translation-Modus (none, lba or auto)</dd>
3796         </dl>
3797       </dd>
3798       <dt><code>blockio</code></dt>
3799       <dd>If present, the <code>blockio</code> element allows
3800         to override any of the block device properties listed below.
3801         <span class="since">Since 0.10.2 (QEMU and KVM)</span>
3802         <dl>
3803           <dt><code>logical_block_size</code></dt>
3804           <dd>The logical block size the disk will report to the guest
3805             OS. For Linux this would be the value returned by the
3806             BLKSSZGET ioctl and describes the smallest units for disk
3807             I/O.
3808           </dd>
3809           <dt><code>physical_block_size</code></dt>
3810           <dd>The physical block size the disk will report to the guest
3811             OS. For Linux this would be the value returned by the
3812             BLKPBSZGET ioctl and describes the disk's hardware sector
3813             size which can be relevant for the alignment of disk data.
3814           </dd>
3815         </dl>
3816       </dd>
3817     </dl>
3818
3819     <h4><a id="elementsFilesystems">Filesystems</a></h4>
3820
3821     <p>
3822       A directory on the host that can be accessed directly from the guest.
3823       <span class="since">since 0.3.3, since 0.8.5 for QEMU/KVM</span>
3824     </p>
3825
3826 <pre>
3827 ...
3828 &lt;devices&gt;
3829   &lt;filesystem type='template'&gt;
3830     &lt;source name='my-vm-template'/&gt;
3831     &lt;target dir='/'/&gt;
3832   &lt;/filesystem&gt;
3833   &lt;filesystem type='mount' accessmode='passthrough'&gt;
3834     &lt;driver type='path' wrpolicy='immediate'/&gt;
3835     &lt;source dir='/export/to/guest'/&gt;
3836     &lt;target dir='/import/from/host'/&gt;
3837     &lt;readonly/&gt;
3838   &lt;/filesystem&gt;
3839   &lt;filesystem type='file' accessmode='passthrough'&gt;
3840     &lt;driver name='loop' type='raw'/&gt;
3841     &lt;driver type='path' wrpolicy='immediate'/&gt;
3842     &lt;source file='/export/to/guest.img'/&gt;
3843     &lt;target dir='/import/from/host'/&gt;
3844     &lt;readonly/&gt;
3845   &lt;/filesystem&gt;
3846   ...
3847 &lt;/devices&gt;
3848 ...</pre>
3849
3850     <dl>
3851       <dt><code>filesystem</code></dt>
3852       <dd>
3853
3854       The filesystem attribute <code>type</code> specifies the type of the
3855       <code>source</code>. The possible values are:
3856
3857         <dl>
3858         <dt><code>mount</code></dt>
3859         <dd>
3860         A host directory to mount in the guest. Used by LXC,
3861         OpenVZ <span class="since">(since 0.6.2)</span>
3862         and QEMU/KVM <span class="since">(since 0.8.5)</span>.
3863         This is the default <code>type</code> if one is not specified.
3864         This mode also has an optional
3865         sub-element <code>driver</code>, with an
3866         attribute <code>type='path'</code>
3867         or <code>type='handle'</code> <span class="since">(since
3868         0.9.7)</span>. The driver block has an optional attribute
3869         <code>wrpolicy</code> that further controls interaction with
3870         the host page cache; omitting the attribute gives default behavior,
3871         while the value <code>immediate</code> means that a host writeback
3872         is immediately triggered for all pages touched during a guest file
3873         write operation <span class="since">(since 0.9.10)</span>.
3874         </dd>
3875         <dt><code>template</code></dt>
3876         <dd>
3877         OpenVZ filesystem template. Only used by OpenVZ driver.
3878         </dd>
3879         <dt><code>file</code></dt>
3880         <dd>
3881         A host file will be treated as an image and mounted in
3882         the guest. The filesystem format will be autodetected.
3883         Only used by LXC driver.
3884         </dd>
3885         <dt><code>block</code></dt>
3886         <dd>
3887         A host block device to mount in the guest. The filesystem
3888         format will be autodetected. Only used by LXC driver
3889         <span class="since">(since 0.9.5)</span>.
3890         </dd>
3891         <dt><code>ram</code></dt>
3892         <dd>
3893           An in-memory filesystem, using memory from the host OS.
3894           The source element has a single attribute <code>usage</code>
3895           which gives the memory usage limit in KiB, unless units
3896           are specified by the <code>units</code> attribute. Only used
3897           by LXC driver.
3898           <span class="since"> (since 0.9.13)</span></dd>
3899         <dt><code>bind</code></dt>
3900         <dd>
3901           A directory inside the guest will be bound to another
3902           directory inside the guest. Only used by LXC driver
3903           <span class="since"> (since 0.9.13)</span></dd>
3904         </dl>
3905
3906       The filesystem block has an optional attribute <code>accessmode</code>
3907       which specifies the security mode for accessing the source
3908       <span class="since">(since 0.8.5)</span>. Currently this only works
3909       with <code>type='mount'</code> for the QEMU/KVM driver. The possible
3910       values are:
3911
3912         <dl>
3913         <dt><code>passthrough</code></dt>
3914         <dd>
3915         The <code>source</code> is accessed with the permissions of the
3916         user inside the guest. This is the default <code>accessmode</code> if
3917         one is not specified.
3918         <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html">More info</a>
3919         </dd>
3920         <dt><code>mapped</code></dt>
3921         <dd>
3922         The <code>source</code> is accessed with the permissions of the
3923         hypervisor (QEMU process).
3924         <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html">More info</a>
3925         </dd>
3926         <dt><code>squash</code></dt>
3927         <dd>
3928         Similar to 'passthrough', the exception is that failure of
3929         privileged operations like 'chown' are ignored. This makes a
3930         passthrough-like mode usable for people who run the hypervisor
3931         as non-root.
3932         <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html">More info</a>
3933         </dd>
3934         </dl>
3935
3936       <span class="since">Since 5.2.0</span>, the filesystem element
3937       has an optional attribute <code>model</code> with supported values
3938       "virtio-transitional", "virtio-non-transitional", or "virtio".
3939       See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
3940       for more details.
3941       </dd>
3942
3943       <dt><code>driver</code></dt>
3944       <dd>
3945         The optional driver element allows specifying further details
3946         related to the hypervisor driver used to provide the filesystem.
3947         <span class="since">Since 1.0.6</span>
3948         <ul>
3949           <li>
3950             If the hypervisor supports multiple backend drivers, then
3951             the <code>type</code> attribute selects the primary
3952             backend driver name, while the <code>format</code>
3953             attribute provides the format type. For example, LXC
3954             supports a type of "loop", with a format of "raw" or
3955             "nbd" with any format. QEMU supports a type of "path"
3956             or "handle", but no formats. Virtuozzo driver supports
3957             a type of "ploop" with a format of "ploop".
3958           </li>
3959           <li>
3960           For virtio-backed devices,
3961           <a href="#elementsVirtio">Virtio-specific options</a> can also be
3962           set. (<span class="since">Since 3.5.0</span>)
3963           </li>
3964         </ul>
3965       </dd>
3966
3967       <dt><code>source</code></dt>
3968       <dd>
3969         The resource on the host that is being accessed in the guest. The
3970         <code>name</code> attribute must be used with
3971         <code>type='template'</code>, and the <code>dir</code> attribute must
3972         be used with <code>type='mount'</code>. The <code>usage</code> attribute
3973         is used with <code>type='ram'</code> to set the memory limit in KiB,
3974         unless units are specified by the <code>units</code> attribute.
3975       </dd>
3976
3977       <dt><code>target</code></dt>
3978       <dd>
3979         Where the <code>source</code> can be accessed in the guest. For
3980         most drivers this is an automatic mount point, but for QEMU/KVM
3981         this is merely an arbitrary string tag that is exported to the
3982         guest as a hint for where to mount.
3983       </dd>
3984
3985       <dt><code>readonly</code></dt>
3986       <dd>
3987         Enables exporting filesystem as a readonly mount for guest, by
3988         default read-write access is given (currently only works for
3989         QEMU/KVM driver).
3990       </dd>
3991
3992       <dt><code>space_hard_limit</code></dt>
3993       <dd>
3994         Maximum space available to this guest's filesystem.
3995         <span class="since">Since 0.9.13</span>
3996       </dd>
3997
3998       <dt><code>space_soft_limit</code></dt>
3999       <dd>
4000         Maximum space available to this guest's filesystem. The container is
4001         permitted to exceed its soft limits for a grace period of time. Afterwards the
4002         hard limit is enforced.
4003         <span class="since">Since 0.9.13</span>
4004       </dd>
4005     </dl>
4006
4007     <h4><a id="elementsAddress">Device Addresses</a></h4>
4008
4009     <p>
4010       Many devices have an optional <code>&lt;address&gt;</code>
4011       sub-element to describe where the device is placed on the
4012       virtual bus presented to the guest.  If an address (or any
4013       optional attribute within an address) is omitted on
4014       input, libvirt will generate an appropriate address; but an
4015       explicit address is required if more control over layout is
4016       required.  See below for device examples including an address
4017       element.
4018     </p>
4019
4020     <p>
4021       Every address has a mandatory attribute <code>type</code> that
4022       describes which bus the device is on.  The choice of which
4023       address to use for a given device is constrained in part by the
4024       device and the architecture of the guest.  For example,
4025       a <code>&lt;disk&gt;</code> device
4026       uses <code>type='drive'</code>, while
4027       a <code>&lt;console&gt;</code> device would
4028       use <code>type='pci'</code> on i686 or x86_64 guests,
4029       or <code>type='spapr-vio'</code> on PowerPC64 pseries guests.
4030       Each address type has further optional attributes that control
4031       where on the bus the device will be placed:
4032     </p>
4033
4034     <dl>
4035       <dt><code>pci</code></dt>
4036       <dd>PCI addresses have the following additional
4037         attributes: <code>domain</code> (a 2-byte hex integer, not
4038         currently used by qemu), <code>bus</code> (a hex value between
4039         0 and 0xff, inclusive), <code>slot</code> (a hex value between
4040         0x0 and 0x1f, inclusive), and <code>function</code> (a value
4041         between 0 and 7, inclusive).  Also available is
4042         the <code>multifunction</code> attribute, which controls
4043         turning on the multifunction bit for a particular
4044         slot/function in the PCI control register
4045         (<span class="since">since 0.9.7, requires QEMU
4046         0.13</span>). <code>multifunction</code> defaults to 'off',
4047         but should be set to 'on' for function 0 of a slot that will
4048         have multiple functions used.
4049         (<span class="since">Since 4.10.0</span>), PCI address extensions
4050         depending on the architecture are supported. For example, PCI
4051         addresses for S390 guests will have a <code>zpci</code> child
4052         element, with two attributes: <code>uid</code> (a hex value
4053         between 0x0001 and 0xffff, inclusive), and <code>fid</code> (a
4054         hex value between 0x00000000 and 0xffffffff, inclusive) used by
4055         PCI devices on S390 for User-defined Identifiers and Function
4056         Identifiers.<br/>
4057         <span class="since">Since 1.3.5</span>, some hypervisor
4058         drivers may accept an <code>&lt;address type='pci'/&gt;</code>
4059         element with no other attributes as an explicit request to
4060         assign a PCI address for the device rather than some other
4061         type of address that may also be appropriate for that same
4062         device (e.g. virtio-mmio).
4063       </dd>
4064       <dt><code>drive</code></dt>
4065       <dd>Drive addresses have the following additional
4066         attributes: <code>controller</code> (a 2-digit controller
4067         number), <code>bus</code> (a 2-digit bus number),
4068         <code>target</code> (a 2-digit target number),
4069         and <code>unit</code> (a 2-digit unit number on the bus).
4070       </dd>
4071       <dt><code>virtio-serial</code></dt>
4072       <dd>Each virtio-serial address has the following additional
4073         attributes: <code>controller</code> (a 2-digit controller
4074         number), <code>bus</code> (a 2-digit bus number),
4075         and <code>slot</code> (a 2-digit slot within the bus).
4076       </dd>
4077       <dt><code>ccid</code></dt>
4078       <dd>A CCID address, for smart-cards, has the following
4079         additional attributes: <code>bus</code> (a 2-digit bus
4080         number), and <code>slot</code> attribute (a 2-digit slot
4081         within the bus).  <span class="since">Since 0.8.8.</span>
4082       </dd>
4083       <dt><code>usb</code></dt>
4084       <dd>USB addresses have the following additional
4085         attributes: <code>bus</code> (a hex value between 0 and 0xfff,
4086         inclusive), and <code>port</code> (a dotted notation of up to
4087         four octets, such as 1.2 or 2.1.3.1).
4088       </dd>
4089       <dt><code>spapr-vio</code></dt>
4090       <dd>On PowerPC pseries guests, devices can be assigned to the
4091         SPAPR-VIO bus.  It has a flat 32-bit address space; by
4092         convention, devices are generally assigned at a non-zero
4093         multiple of 0x00001000, but other addresses are valid and
4094         permitted by libvirt.  Each address has the following
4095         additional attribute: <code>reg</code> (the hex value address
4096         of the starting register).  <span class="since">Since
4097         0.9.9.</span>
4098       </dd>
4099       <dt><code>ccw</code></dt>
4100       <dd>S390 guests with a <code>machine</code> value of
4101         s390-ccw-virtio use the native CCW bus for I/O devices.
4102         CCW bus addresses have the following additional attributes:
4103         <code>cssid</code> (a hex value between 0 and 0xfe, inclusive),
4104         <code>ssid</code> (a value between 0 and 3, inclusive) and
4105         <code>devno</code> (a hex value between 0 and 0xffff, inclusive).
4106         Partially specified bus addresses are not allowed.
4107         If omitted, libvirt will assign a free bus address with
4108         cssid=0xfe and ssid=0. Virtio-ccw devices must have their cssid
4109         set to 0xfe.
4110         <span class="since">Since 1.0.4</span>
4111       </dd>
4112       <dt><code>virtio-mmio</code></dt>
4113       <dd>This places the device on the virtio-mmio transport, which is
4114         currently only available for some <code>armv7l</code> and
4115         <code>aarch64</code> virtual machines. virtio-mmio addresses
4116         do not have any additional attributes.
4117         <span class="since">Since 1.1.3</span><br/>
4118         If the guest architecture is <code>aarch64</code> and the machine
4119         type is <code>virt</code>, libvirt will automatically assign PCI
4120         addresses to devices; however, the presence of a single device
4121         with virtio-mmio address in the guest configuration will cause
4122         libvirt to assign virtio-mmio addresses to all further devices.
4123         <span class="since">Since 3.0.0</span>
4124       </dd>
4125       <dt><code>isa</code></dt>
4126       <dd>ISA addresses have the following additional
4127         attributes: <code>iobase</code> and <code>irq</code>.
4128         <span class="since">Since 1.2.1</span>
4129       </dd>
4130     </dl>
4131
4132     <h4><a id="elementsVirtio">Virtio-related options</a></h4>
4133
4134     <p>
4135       QEMU's virtio devices have some attributes related to the virtio transport under
4136       the <code>driver</code> element:
4137       The <code>iommu</code> attribute enables the use of emulated IOMMU
4138       by the device. The attribute <code>ats</code> controls the Address
4139       Translation Service support for PCIe devices. This is needed to make use
4140       of IOTLB support (see <a href="#elementsIommu">IOMMU device</a>).
4141       Possible values are <code>on</code> or <code>off</code>.
4142       <span class="since">Since 3.5.0</span>
4143     </p>
4144
4145     <h4><a id="elementsVirtioTransitional">Virtio transitional devices</a></h4>
4146
4147     <p>
4148       <span class="since">Since 5.2.0</span>, some of QEMU's virtio devices,
4149       when used with PCI/PCIe machine types, accept the following
4150       <code>model</code> values:
4151     </p>
4152
4153     <dl>
4154       <dt><code>virtio-transitional</code></dt>
4155       <dd>This device can work both with virtio 0.9 and virtio 1.0 guest
4156       drivers, so it's the best choice when compatibility with older
4157       guest operating systems is desired. libvirt will plug the device
4158       into a conventional PCI slot.
4159       </dd>
4160       <dt><code>virtio-non-transitional</code></dt>
4161       <dd>This device can only work with virtio 1.0 guest drivers, and it's
4162       the recommended option unless compatibility with older guest
4163       operating systems is necessary. libvirt will plug the device into
4164       either a PCI Express slot or a conventional PCI slot based on the
4165       machine type, resulting in a more optimized PCI topology.
4166       </dd>
4167       <dt><code>virtio</code></dt>
4168       <dd>This device will work like a <code>virtio-non-transitional</code>
4169       device when plugged into a PCI Express slot, and like a
4170       <code>virtio-transitional</code> device otherwise; libvirt will
4171       pick one or the other based on the machine type. This is the best
4172       choice when compatibility with libvirt versions older than 5.2.0
4173       is necessary, but it's otherwise not recommended to use it.
4174       </dd>
4175     </dl>
4176
4177     <p>
4178       While the information outlined above applies to most virtio devices,
4179       there are a few exceptions:
4180     </p>
4181
4182     <ul>
4183       <li>
4184         for SCSI controllers, <code>virtio-scsi</code> must be used instead
4185         of <code>virtio</code> for backwards compatibility reasons;
4186       </li>
4187       <li>
4188         some devices, such as GPUs and input devices (keyboard, tablet and
4189         mouse), are only defined in the virtio 1.0 spec and as such don't
4190         have a transitional variant: the only accepted model is
4191         <code>virtio</code>, which will result in a non-transitional device.
4192       </li>
4193     </ul>
4194
4195     <p>
4196       For more details see the
4197       <a href="https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html">qemu patch posting</a> and the
4198       <a href="http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html">virtio-1.0 spec</a>.
4199     </p>
4200
4201
4202     <h4><a id="elementsControllers">Controllers</a></h4>
4203
4204     <p>
4205       Depending on the guest architecture, some device buses can
4206       appear more than once, with a group of virtual devices tied to a
4207       virtual controller.  Normally, libvirt can automatically infer such
4208       controllers without requiring explicit XML markup, but sometimes
4209       it is necessary to provide an explicit controller element, notably
4210       when planning the <a href="pci-hotplug.html">PCI topology</a>
4211       for guests where device hotplug is expected.
4212     </p>
4213
4214 <pre>
4215 ...
4216 &lt;devices&gt;
4217   &lt;controller type='ide' index='0'/&gt;
4218   &lt;controller type='virtio-serial' index='0' ports='16' vectors='4'/&gt;
4219   &lt;controller type='virtio-serial' index='1'&gt;
4220     &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/&gt;
4221   &lt;/controller&gt;
4222   &lt;controller type='scsi' index='0' model='virtio-scsi'&gt;
4223     &lt;driver iothread='4'/&gt;
4224     &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/&gt;
4225   &lt;/controller&gt;
4226   &lt;controller type='xenbus' maxGrantFrames='64'/&gt;
4227   ...
4228 &lt;/devices&gt;
4229 ...</pre>
4230
4231     <p>
4232       Each controller has a mandatory attribute <code>type</code>,
4233       which must be one of 'ide', 'fdc', 'scsi', 'sata', 'usb',
4234       'ccid', 'virtio-serial' or 'pci', and a mandatory
4235       attribute <code>index</code> which is the decimal integer
4236       describing in which order the bus controller is encountered (for
4237       use in <code>controller</code> attributes of
4238       <code>&lt;address&gt;</code> elements).
4239       <span class="since">Since 1.3.5</span> the index is optional; if
4240       not specified, it will be auto-assigned to be the lowest unused
4241       index for the given controller type. Some controller types have
4242       additional attributes that control specific features, such as:
4243     </p>
4244
4245       <dl>
4246         <dt><code>virtio-serial</code></dt>
4247         <dd>The <code>virtio-serial</code> controller has two additional
4248         optional attributes <code>ports</code> and <code>vectors</code>,
4249         which control how many devices can be connected through the
4250         controller. <span class="since">Since 5.2.0</span>, it
4251         supports an optional attribute <code>model</code> which can
4252         be 'virtio', 'virtio-transitional', or 'virtio-non-transitional'. See
4253         <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
4254         for more details.
4255         </dd>
4256         <dt><code>scsi</code></dt>
4257         <dd>A <code>scsi</code> controller has an optional attribute
4258         <code>model</code>, which is one of 'auto', 'buslogic', 'ibmvscsi',
4259         'lsilogic', 'lsisas1068', 'lsisas1078', 'virtio-scsi',
4260         'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. See
4261         <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
4262         for more details.
4263         </dd>
4264         <dt><code>usb</code></dt>
4265         <dd>A <code>usb</code> controller has an optional attribute
4266         <code>model</code>, which is one of "piix3-uhci", "piix4-uhci",
4267         "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3",
4268         "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pvusb
4269         with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu
4270         backend, version 2.0) or "qemu-xhci". Additionally,
4271          <span class="since">since 0.10.0</span>, if the USB bus needs to
4272          be explicitly disabled for the guest, <code>model='none'</code>
4273          may be used.  <span class="since">Since 1.0.5</span>, no default
4274          USB controller will be built on s390.
4275          <span class="since">Since 1.3.5</span>, USB controllers accept a
4276          <code>ports</code> attribute to configure how many devices can be
4277          connected to the controller.</dd>
4278         <dt><code>ide</code></dt>
4279         <dd><span class="since">Since 3.10.0</span> for the vbox driver, the
4280         <code>ide</code> controller has an optional attribute
4281         <code>model</code>, which is one of "piix3", "piix4" or "ich6".</dd>
4282         <dt><code>xenbus</code></dt>
4283         <dd><span class="since">Since 5.2.0</span>, the <code>xenbus</code>
4284         controller has an optional attribute <code>maxGrantFrames</code>,
4285         which specifies the maximum number of grant frames the controller
4286         makes available for connected devices.</dd>
4287       </dl>
4288
4289     <p>
4290       Note: The PowerPC64 "spapr-vio" addresses do not have an
4291       associated controller.
4292     </p>
4293
4294     <p>
4295       For controllers that are themselves devices on a PCI or USB bus,
4296       an optional sub-element <code>&lt;address&gt;</code> can specify
4297       the exact relationship of the controller to its master bus, with
4298       semantics <a href="#elementsAddress">given above</a>.
4299     </p>
4300
4301     <p>
4302       An optional sub-element <code>driver</code> can specify the driver
4303       specific options:
4304     </p>
4305     <dl>
4306       <dt><code>queues</code></dt>
4307       <dd>
4308         The optional <code>queues</code> attribute specifies the number of
4309         queues for the controller. For best performance, it's recommended to
4310         specify a value matching the number of vCPUs.
4311         <span class="since">Since 1.0.5 (QEMU and KVM only)</span>
4312       </dd>
4313       <dt><code>cmd_per_lun</code></dt>
4314       <dd>
4315         The optional <code>cmd_per_lun</code> attribute specifies the maximum
4316         number of commands that can be queued on devices controlled by the
4317         host.
4318         <span class="since">Since 1.2.7 (QEMU and KVM only)</span>
4319       </dd>
4320       <dt><code>max_sectors</code></dt>
4321       <dd>
4322         The optional <code>max_sectors</code> attribute specifies the maximum
4323         amount of data in bytes that will be transferred to or from the device
4324         in a single command. The transfer length is measured in sectors, where
4325         a sector is 512 bytes.
4326         <span class="since">Since 1.2.7 (QEMU and KVM only)</span>
4327       </dd>
4328       <dt><code>ioeventfd</code></dt>
4329       <dd>
4330         The optional <code>ioeventfd</code> attribute specifies
4331         whether the controller should use
4332         <a href='https://patchwork.kernel.org/patch/43390/'>
4333         I/O asynchronous handling</a> or not.  Accepted values are
4334         "on" and "off". <span class="since">Since 1.2.18</span>
4335       </dd>
4336       <dt><code>iothread</code></dt>
4337       <dd>
4338         Supported for controller type <code>scsi</code> using model
4339         <code>virtio-scsi</code> for <code>address</code> types
4340         <code>pci</code> and <code>ccw</code>
4341         <span class="since">since 1.3.5 (QEMU 2.4)</span>.
4342
4343         The optional <code>iothread</code> attribute assigns the controller
4344         to an IOThread as defined by the range for the domain
4345         <a href="#elementsIOThreadsAllocation"><code>iothreads</code></a>
4346         value. Each SCSI <code>disk</code> assigned to use the specified
4347         <code>controller</code> will utilize the same IOThread. If a specific
4348         IOThread is desired for a specific SCSI <code>disk</code>, then
4349         multiple controllers must be defined each having a specific
4350         <code>iothread</code> value. The <code>iothread</code> value
4351         must be within the range 1 to the domain iothreads value.
4352       </dd>
4353       <dt>virtio options</dt>
4354       <dd>
4355         For virtio controllers,
4356         <a href="#elementsVirtio">Virtio-specific options</a> can also be
4357         set. (<span class="since">Since 3.5.0</span>)
4358       </dd>
4359     </dl>
4360     <p>
4361       USB companion controllers have an optional
4362       sub-element <code>&lt;master&gt;</code> to specify the exact
4363       relationship of the companion to its master controller.
4364       A companion controller is on the same bus as its master, so
4365       the companion <code>index</code> value should be equal.
4366       Not all controller models can be used as companion controllers
4367       and libvirt might provide some sensible defaults (settings
4368       of <code>master startport</code> and <code>function</code> of an
4369       address) for some particular models.
4370       Preferred companion controllers are <code>ich-uhci[123]</code>.
4371     </p>
4372
4373 <pre>
4374 ...
4375 &lt;devices&gt;
4376   &lt;controller type='usb' index='0' model='ich9-ehci1'&gt;
4377     &lt;address type='pci' domain='0' bus='0' slot='4' function='7'/&gt;
4378   &lt;/controller&gt;
4379   &lt;controller type='usb' index='0' model='ich9-uhci1'&gt;
4380     &lt;master startport='0'/&gt;
4381     &lt;address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/&gt;
4382   &lt;/controller&gt;
4383   ...
4384 &lt;/devices&gt;
4385 ...</pre>
4386
4387     <p>
4388       PCI controllers have an optional <code>model</code> attribute; possible
4389       values for this attribute are
4390     </p>
4391     <ul>
4392       <li>
4393         <code>pci-root</code>, <code>pci-bridge</code>
4394         (<span class="since">since 1.0.5</span>)
4395       </li>
4396       <li>
4397         <code>pcie-root</code>, <code>dmi-to-pci-bridge</code>
4398         (<span class="since">since 1.1.2</span>)
4399       </li>
4400       <li>
4401         <code>pcie-root-port</code>, <code>pcie-switch-upstream-port</code>,
4402         <code>pcie-switch-downstream-port</code>
4403         (<span class="since">since 1.2.19</span>)
4404       </li>
4405       <li>
4406         <code>pci-expander-bus</code>, <code>pcie-expander-bus</code>
4407         (<span class="since">since 1.3.4</span>)
4408       </li>
4409       <li>
4410         <code>pcie-to-pci-bridge</code>
4411         (<span class="since">since 4.3.0</span>)
4412       </li>
4413     </ul>
4414     <p>
4415       The root controllers (<code>pci-root</code>
4416       and <code>pcie-root</code>) have an
4417       optional <code>pcihole64</code> element specifying how big (in
4418       kilobytes, or in the unit specified by <code>pcihole64</code>'s
4419       <code>unit</code> attribute) the 64-bit PCI hole should be. Some guests (like
4420       Windows XP or Windows Server 2003) might crash when QEMU and Seabios
4421       are recent enough to support 64-bit PCI holes, unless this is disabled
4422       (set to 0). <span class="since">Since 1.1.2 (QEMU only)</span>
4423     </p>
4424     <p>
4425       PCI controllers also have an optional
4426       subelement <code>&lt;model&gt;</code> with an attribute
4427       <code>name</code>. The name attribute holds the name of the
4428       specific device that qemu is emulating (e.g. "i82801b11-bridge")
4429       rather than simply the class of device ("pcie-to-pci-bridge",
4430       "pci-bridge"), which is set in the controller element's
4431       model <b>attribute</b>.  In almost all cases, you should not
4432       manually add a <code>&lt;model&gt;</code> subelement to a
4433       controller, nor should you modify one that is automatically
4434       generated by libvirt. <span class="since">Since 1.2.19 (QEMU
4435       only).</span>
4436     </p>
4437     <p>
4438       PCI controllers also have an optional
4439       subelement <code>&lt;target&gt;</code> with the attributes and
4440       subelements listed below. These are configurable items that 1)
4441       are visible to the guest OS so must be preserved for guest ABI
4442       compatibility, and 2) are usually left to default values or
4443       derived automatically by libvirt. In almost all cases, you
4444       should not manually add a <code>&lt;target&gt;</code> subelement
4445       to a controller, nor should you modify the values in the those
4446       that are automatically generated by
4447       libvirt. <span class="since">Since 1.2.19 (QEMU only).</span>
4448     </p>
4449     <dl>
4450       <dt><code>chassisNr</code></dt>
4451       <dd>
4452         PCI controllers that have attribute model="pci-bridge", can
4453         also have a <code>chassisNr</code> attribute in
4454         the <code>&lt;target&gt;</code> subelement, which is used to
4455         control QEMU's "chassis_nr" option for the pci-bridge device
4456         (normally libvirt automatically sets this to the same value as
4457         the index attribute of the pci controller). If set, chassisNr
4458         must be between 1 and 255.
4459       </dd>
4460       <dt><code>chassis</code></dt>
4461       <dd>
4462         pcie-root-port and pcie-switch-downstream-port controllers can
4463         also have a <code>chassis</code> attribute in
4464         the <code>&lt;target&gt;</code> subelement, which is used to
4465         set the controller's "chassis" configuration value, which is
4466         visible to the virtual machine. If set, chassis must be
4467         between 0 and 255.
4468       </dd>
4469       <dt><code>port</code></dt>
4470       <dd>
4471         pcie-root-port and pcie-switch-downstream-port controllers can
4472         also have a <code>port</code> attribute in
4473         the <code>&lt;target&gt;</code> subelement, which
4474         is used to set the controller's "port" configuration value,
4475         which is visible to the virtual machine. If set, port must be
4476         between 0 and 255.
4477       </dd>
4478       <dt><code>busNr</code></dt>
4479       <dd>
4480         pci-expander-bus and pcie-expander-bus controllers can have an
4481         optional <code>busNr</code> attribute (1-254). This will be
4482         the bus number of the new bus; All bus numbers between that
4483         specified and 255 will be available only for assignment to
4484         PCI/PCIe controllers plugged into the hierarchy starting with
4485         this expander bus, and bus numbers less than the specified
4486         value will be available to the next lower expander-bus (or the
4487         root-bus if there are no lower expander buses). If you do not
4488         specify a busNumber, libvirt will find the lowest existing
4489         busNumber in all other expander buses (or use 256 if there are
4490         no others) and auto-assign the busNr of that found bus - 2,
4491         which provides one bus number for the pci-expander-bus and one
4492         for the pci-bridge that is automatically attached to it (if
4493         you plan on adding more pci-bridges to the hierarchy of the
4494         bus, you should manually set busNr to a lower value).
4495         <p>
4496           A similar algorithm is used for automatically determining
4497           the busNr attribute for pcie-expander-bus, but since the
4498           pcie-expander-bus doesn't have any built-in pci-bridge, the
4499           2nd bus-number is just being reserved for the pcie-root-port
4500           that must necessarily be connected to the bus in order to
4501           actually plug in an endpoint device. If you intend to plug
4502           multiple devices into a pcie-expander-bus, you must connect
4503           a pcie-switch-upstream-port to the pcie-root-port that is
4504           plugged into the pcie-expander-bus, and multiple
4505           pcie-switch-downstream-ports to the
4506           pcie-switch-upstream-port, and of course for this to work
4507           properly, you will need to decrease the pcie-expander-bus'
4508           busNr accordingly so that there are enough unused bus
4509           numbers above it to accommodate giving out one bus number for
4510           the upstream-port and one for each downstream-port (in
4511           addition to the pcie-root-port and the pcie-expander-bus
4512           itself).
4513         </p>
4514       </dd>
4515       <dt><code>node</code></dt>
4516       <dd>
4517         Some PCI controllers (<code>pci-expander-bus</code> for the pc
4518         machine type, <code>pcie-expander-bus</code> for the q35 machine
4519         type and, <span class="since">since 3.6.0</span>,
4520         <code>pci-root</code> for the pseries machine type) can have an
4521         optional <code>&lt;node&gt;</code> subelement within
4522         the <code>&lt;target&gt;</code> subelement, which is used to
4523         set the NUMA node reported to the guest OS for that bus - the
4524         guest OS will then know that all devices on that bus are a
4525         part of the specified NUMA node (it is up to the user of the
4526         libvirt API to attach host devices to the correct
4527         pci-expander-bus when assigning them to the domain).
4528       </dd>
4529       <dt><code>index</code></dt>
4530       <dd>
4531         pci-root controllers for pSeries guests use this attribute to
4532         record the order they will show up in the guest.
4533         <span class="since">Since 3.6.0</span>
4534       </dd>
4535     </dl>
4536     <p>
4537       For machine types which provide an implicit PCI bus, the pci-root
4538       controller with index=0 is auto-added and required to use PCI devices.
4539       pci-root has no address.
4540       PCI bridges are auto-added if there are too many devices to fit on
4541       the one bus provided by pci-root, or a PCI bus number greater than zero
4542       was specified.
4543       PCI bridges can also be specified manually, but their addresses should
4544       only refer to PCI buses provided by already specified PCI controllers.
4545       Leaving gaps in the PCI controller indexes might lead to an invalid
4546       configuration.
4547     </p>
4548 <pre>
4549 ...
4550 &lt;devices&gt;
4551   &lt;controller type='pci' index='0' model='pci-root'/&gt;
4552   &lt;controller type='pci' index='1' model='pci-bridge'&gt;
4553     &lt;address type='pci' domain='0' bus='0' slot='5' function='0' multifunction='off'/&gt;
4554   &lt;/controller&gt;
4555 &lt;/devices&gt;
4556 ...</pre>
4557
4558     <p>
4559       For machine types which provide an implicit PCI Express (PCIe)
4560       bus (for example, the machine types based on the Q35 chipset),
4561       the pcie-root controller with index=0 is auto-added to the
4562       domain's configuration. pcie-root has also no address, provides
4563       31 slots (numbered 1-31) that can be used to attach PCIe or PCI
4564       devices (although libvirt will never auto-assign a PCI device to
4565       a PCIe slot, it will allow manual specification of such an
4566       assignment). Devices connected to pcie-root cannot be
4567       hotplugged. If traditional PCI devices are present in the guest
4568       configuration, a <code>pcie-to-pci-bridge</code> controller will
4569       automatically be added: this controller, which plugs into a
4570       <code>pcie-root-port</code>, provides 31 usable PCI slots (1-31) with
4571       hotplug support (<span class="since">since 4.3.0</span>). If the QEMU
4572       binary doesn't support the corresponding device, then a
4573       <code>dmi-to-pci-bridge</code> controller will be added instead,
4574       usually at the defacto standard location of slot=0x1e. A
4575       dmi-to-pci-bridge controller plugs into a PCIe slot (as provided
4576       by pcie-root), and itself provides 31 standard PCI slots (which
4577       also do not support device hotplug). In order to have
4578       hot-pluggable PCI slots in the guest system, a pci-bridge
4579       controller will also be automatically created and connected to
4580       one of the slots of the auto-created dmi-to-pci-bridge
4581       controller; all guest PCI devices with addresses that are
4582       auto-determined by libvirt will be placed on this pci-bridge
4583       device.  (<span class="since">since 1.1.2</span>).
4584     </p>
4585     <p>
4586       Domains with an implicit pcie-root can also add controllers
4587       with <code>model='pcie-root-port'</code>,
4588       <code>model='pcie-switch-upstream-port'</code>,
4589       and <code>model='pcie-switch-downstream-port'</code>. pcie-root-port
4590       is a simple type of bridge device that can connect only to one
4591       of the 31 slots on the pcie-root bus on its upstream side, and
4592       makes a single (PCIe, hotpluggable) port available on the
4593       downstream side (at slot='0'). pcie-root-port can be used to
4594       provide a single slot to later hotplug a PCIe device (but is not
4595       itself hotpluggable - it must be in the configuration when the
4596       domain is started).
4597       (<span class="since">since 1.2.19</span>)
4598     </p>
4599     <p>
4600       pcie-switch-upstream-port is a more flexible (but also more
4601       complex) device that can only plug into a pcie-root-port or
4602       pcie-switch-downstream-port on the upstream side (and only
4603       before the domain is started - it is not hot-pluggable), and
4604       provides 32 ports on the downstream side (slot='0' - slot='31')
4605       that accept only pcie-switch-downstream-port devices; each
4606       pcie-switch-downstream-port device can only plug into a
4607       pcie-switch-upstream-port on its upstream side (again, not
4608       hot-pluggable), and on its downstream side provides a single
4609       hotpluggable pcie port that can accept any standard pci or pcie
4610       device (or another pcie-switch-upstream-port), i.e. identical in
4611       function to a pcie-root-port.  (<span class="since">since
4612       1.2.19</span>)
4613     </p>
4614 <pre>
4615 ...
4616 &lt;devices&gt;
4617   &lt;controller type='pci' index='0' model='pcie-root'/&gt;
4618   &lt;controller type='pci' index='1' model='pcie-root-port'&gt;
4619     &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/&gt;
4620   &lt;/controller&gt;
4621   &lt;controller type='pci' index='2' model='pcie-to-pci-bridge'&gt;
4622     &lt;address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/&gt;
4623   &lt;/controller&gt;
4624 &lt;/devices&gt;
4625 ...</pre>
4626
4627     <h4><a id="elementsLease">Device leases</a></h4>
4628
4629     <p>
4630       When using a lock manager, it may be desirable to record device leases
4631       against a VM. The lock manager will ensure the VM won't start unless
4632       the leases can be acquired.
4633     </p>
4634
4635 <pre>
4636 ...
4637 &lt;devices&gt;
4638   ...
4639   &lt;lease&gt;
4640     &lt;lockspace&gt;somearea&lt;/lockspace&gt;
4641     &lt;key&gt;somekey&lt;/key&gt;
4642     &lt;target path='/some/lease/path' offset='1024'/&gt;
4643   &lt;/lease&gt;
4644   ...
4645 &lt;/devices&gt;
4646 ...</pre>
4647
4648     <dl>
4649       <dt><code>lockspace</code></dt>
4650       <dd>This is an arbitrary string, identifying the lockspace
4651         within which the key is held. Lock managers may impose
4652         extra restrictions on the format, or length of the lockspace
4653         name.</dd>
4654       <dt><code>key</code></dt>
4655       <dd>This is an arbitrary string, uniquely identifying the
4656         lease to be acquired. Lock managers may impose extra
4657         restrictions on the format, or length of the key.
4658       </dd>
4659       <dt><code>target</code></dt>
4660       <dd>This is the fully qualified path of the file associated
4661         with the lockspace. The offset specifies where the lease
4662         is stored within the file. If the lock manager does not
4663         require an offset, just pass 0.
4664       </dd>
4665     </dl>
4666
4667     <h4><a id="elementsHostDev">Host device assignment</a></h4>
4668
4669     <h5><a id="elementsHostDevSubsys">USB / PCI / SCSI devices</a></h5>
4670
4671     <p>
4672       USB, PCI and SCSI devices attached to the host can be passed through
4673       to the guest using the <code>hostdev</code> element.
4674       <span class="since">since after 0.4.4 for USB, 0.6.0 for PCI (KVM only)
4675         and 1.0.6 for SCSI (KVM only)</span>:
4676     </p>
4677
4678 <pre>
4679 ...
4680 &lt;devices&gt;
4681   &lt;hostdev mode='subsystem' type='usb'&gt;
4682     &lt;source startupPolicy='optional'&gt;
4683       &lt;vendor id='0x1234'/&gt;
4684       &lt;product id='0xbeef'/&gt;
4685     &lt;/source&gt;
4686     &lt;boot order='2'/&gt;
4687   &lt;/hostdev&gt;
4688 &lt;/devices&gt;
4689 ...</pre>
4690
4691     <p>or:</p>
4692
4693 <pre>
4694 ...
4695 &lt;devices&gt;
4696   &lt;hostdev mode='subsystem' type='pci' managed='yes'&gt;
4697     &lt;source&gt;
4698       &lt;address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/&gt;
4699     &lt;/source&gt;
4700     &lt;boot order='1'/&gt;
4701     &lt;rom bar='on' file='/etc/fake/boot.bin'/&gt;
4702   &lt;/hostdev&gt;
4703 &lt;/devices&gt;
4704 ...</pre>
4705
4706     <p>or:</p>
4707
4708 <pre>
4709 ...
4710 &lt;devices&gt;
4711   &lt;hostdev mode='subsystem' type='scsi' sgio='filtered' rawio='yes'&gt;
4712     &lt;source&gt;
4713       &lt;adapter name='scsi_host0'/&gt;
4714       &lt;address bus='0' target='0' unit='0'/&gt;
4715     &lt;/source&gt;
4716     &lt;readonly/&gt;
4717     &lt;address type='drive' controller='0' bus='0' target='0' unit='0'/&gt;
4718   &lt;/hostdev&gt;
4719 &lt;/devices&gt;
4720 ...</pre>
4721
4722
4723     <p>or:</p>
4724
4725 <pre>
4726 ...
4727 &lt;devices&gt;
4728   &lt;hostdev mode='subsystem' type='scsi'&gt;
4729     &lt;source protocol='iscsi' name='iqn.2014-08.com.example:iscsi-nopool/1'&gt;
4730       &lt;host name='example.com' port='3260'/&gt;
4731       &lt;auth username='myuser'&gt;
4732         &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
4733       &lt;/auth&gt;
4734     &lt;/source&gt;
4735     &lt;address type='drive' controller='0' bus='0' target='0' unit='0'/&gt;
4736   &lt;/hostdev&gt;
4737 &lt;/devices&gt;
4738 ...</pre>
4739
4740     <p>or:</p>
4741
4742 <pre>
4743   ...
4744   &lt;devices&gt;
4745     &lt;hostdev mode='subsystem' type='scsi_host'&gt;
4746       &lt;source protocol='vhost' wwpn='naa.50014057667280d8'/&gt;
4747     &lt;/hostdev&gt;
4748   &lt;/devices&gt;
4749   ...</pre>
4750
4751     <p>or:</p>
4752
4753 <pre>
4754   ...
4755   &lt;devices&gt;
4756     &lt;hostdev mode='subsystem' type='mdev' model='vfio-pci'&gt;
4757     &lt;source&gt;
4758       &lt;address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'/&gt;
4759     &lt;/source&gt;
4760     &lt;/hostdev&gt;
4761     &lt;hostdev mode='subsystem' type='mdev' model='vfio-ccw'&gt;
4762     &lt;source&gt;
4763       &lt;address uuid='9063cba3-ecef-47b6-abcf-3fef4fdcad85'/&gt;
4764     &lt;/source&gt;
4765     &lt;address type='ccw' cssid='0xfe' ssid='0x0' devno='0x0001'/&gt;
4766     &lt;/hostdev&gt;
4767   &lt;/devices&gt;
4768   ...</pre>
4769
4770     <dl>
4771       <dt><code>hostdev</code></dt>
4772       <dd>The <code>hostdev</code> element is the main container for describing
4773         host devices. For each device, the <code>mode</code> is always
4774         "subsystem" and the <code>type</code> is one of the following values
4775         with additional attributes noted.
4776         <dl>
4777           <dt><code>usb</code></dt>
4778           <dd>USB devices are detached from the host on guest startup
4779             and reattached after the guest exits or the device is
4780             hot-unplugged.
4781           </dd>
4782           <dt><code>pci</code></dt>
4783           <dd>For PCI devices, when <code>managed</code> is "yes" it is
4784             detached from the host before being passed on to the guest
4785             and reattached to the host after the guest exits. If
4786             <code>managed</code> is omitted or "no", the user is
4787             responsible to call <code>virNodeDeviceDetachFlags</code>
4788             (or <code>virsh nodedev-detach</code> before starting the guest
4789             or hot-plugging the device and <code>virNodeDeviceReAttach</code>
4790             (or <code>virsh nodedev-reattach</code>) after hot-unplug or
4791             stopping the guest.
4792           </dd>
4793           <dt><code>scsi</code></dt>
4794           <dd>For SCSI devices, user is responsible to make sure the device
4795             is not used by host. If supported by the hypervisor and OS, the
4796             optional <code>sgio</code> (<span class="since">since 1.0.6</span>)
4797             attribute indicates whether unprivileged SG_IO commands are
4798             filtered for the disk. Valid settings are "filtered" or
4799             "unfiltered", where the default is "filtered".
4800             The optional <code>rawio</code>
4801             (<span class="since">since 1.2.9</span>) attribute indicates
4802             whether the lun needs the rawio capability. Valid settings are
4803             "yes" or "no". See the rawio description within the
4804             <a href="#elementsDisks">disk</a> section.
4805             If a disk lun in the domain already has the rawio capability,
4806             then this setting not required.
4807           </dd>
4808           <dt><code>scsi_host</code></dt>
4809           <dd><span class="since">since 2.5.0</span>For SCSI devices, user
4810             is responsible to make sure the device is not used by host. This
4811             <code>type</code> passes all LUNs presented by a single HBA to
4812             the guest. <span class="since">Since 5.2.0,</span> the
4813             <code>model</code> attribute can be specified further
4814             with "virtio-transitional", "virtio-non-transitional", or
4815             "virtio". See
4816             <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
4817             for more details.
4818           </dd>
4819           <dt><code>mdev</code></dt>
4820           <dd>For mediated devices (<span class="since">Since 3.2.0</span>)
4821           the <code>model</code> attribute specifies the device API which
4822           determines how the host's vfio driver will expose the device to the
4823           guest. Currently, <code>model='vfio-pci'</code>,
4824           <code>model='vfio-ccw'</code> (<span class="since">Since 4.4.0</span>)
4825           and <code>model='vfio-ap'</code> (<span class="since">Since 4.9.0</span>)
4826           is supported. <a href="drvnodedev.html#MDEV">MDEV</a> section
4827           provides more information about mediated devices as well as how to
4828           create mediated devices on the host.
4829           <span class="since">Since 4.6.0 (QEMU 2.12)</span> an optional
4830           <code>display</code> attribute may be used to enable or disable
4831           support for an accelerated remote desktop backed by a mediated
4832           device (such as NVIDIA vGPU or Intel GVT-g) as an alternative to
4833           emulated <a href="#elementsVideo">video devices</a>. This attribute
4834           is limited to <code>model='vfio-pci'</code> only. Supported values
4835           are either <code>on</code> or <code>off</code> (default is 'off').
4836           It is required to use a
4837           <a href="#elementsGraphics">graphical framebuffer</a> in order to
4838           use this attribute, currently only supported with VNC, Spice and
4839           egl-headless graphics devices.
4840           <p>
4841             Note: There are also some implications on the usage of guest's
4842             address type depending on the <code>model</code> attribute,
4843             see the <code>address</code> element below.
4844           </p>
4845           </dd>
4846         </dl>
4847         <p>
4848           Note: The <code>managed</code> attribute is only used with
4849           <code>type='pci'</code> and is ignored by all the other device types,
4850           thus setting <code>managed</code> explicitly with other than a PCI
4851           device has the same effect as omitting it. Similarly,
4852           <code>model</code> attribute is only supported by mediated devices and
4853           ignored by all other device types.
4854         </p>
4855       </dd>
4856       <dt><code>source</code></dt>
4857       <dd>The source element describes the device as seen from the host using
4858         the following mechanism to describe:
4859         <dl>
4860           <dt><code>usb</code></dt>
4861           <dd>The USB device can either be addressed by vendor / product id
4862             using the <code>vendor</code> and <code>product</code> elements
4863             or by the device's address on the host using the
4864             <code>address</code> element.
4865             <p>
4866             <span class="since">Since 1.0.0</span>, the <code>source</code>
4867             element of USB devices may contain <code>startupPolicy</code>
4868             attribute which can be used to define policy what to do if the
4869             specified host USB device is not found. The attribute accepts
4870             the following values:
4871             </p>
4872             <table class="top_table">
4873               <tr>
4874                 <td> mandatory </td>
4875                 <td> fail if missing for any reason (the default) </td>
4876               </tr>
4877               <tr>
4878                 <td> requisite </td>
4879                 <td> fail if missing on boot up,
4880                      drop if missing on migrate/restore/revert </td>
4881               </tr>
4882               <tr>
4883                 <td> optional </td>
4884                 <td> drop if missing at any start attempt </td>
4885               </tr>
4886             </table>
4887           </dd>
4888           <dt><code>pci</code></dt>
4889           <dd>PCI devices can only be described by their <code>address</code>.
4890           </dd>
4891           <dt><code>scsi</code></dt>
4892           <dd>SCSI devices are described by both the <code>adapter</code>
4893             and <code>address</code> elements. The <code>address</code>
4894             element includes a <code>bus</code> attribute (a 2-digit bus
4895             number), a <code>target</code> attribute (a 10-digit target
4896             number), and a <code>unit</code> attribute (a 20-digit unit
4897             number on the bus). Not all hypervisors support larger
4898             <code>target</code> and <code>unit</code> values. It is up
4899             to each hypervisor to determine the maximum value supported
4900             for the adapter.
4901             <p>
4902             <span class="since">Since 1.2.8</span>, the <code>source</code>
4903             element of a SCSI device may contain the <code>protocol</code>
4904             attribute. When the attribute is set to "iscsi", the host
4905             device XML follows the network <a href="#elementsDisks">disk</a>
4906             device using the same <code>name</code> attribute and optionally
4907             using the <code>auth</code> element to provide the authentication
4908             credentials to the iSCSI server.
4909             </p>
4910           </dd>
4911           <dt><code>scsi_host</code></dt>
4912           <dd><span class="since">Since 2.5.0</span>, multiple LUNs behind a
4913             single SCSI HBA are described by a <code>protocol</code>
4914             attribute set to "vhost" and a <code>wwpn</code> attribute that
4915             is the vhost_scsi wwpn (16 hexadecimal digits with a prefix of
4916             "naa.") established in the host configfs.
4917           </dd>
4918           <dt><code>mdev</code></dt>
4919           <dd>Mediated devices (<span class="since">Since 3.2.0</span>) are
4920             described by the <code>address</code> element. The
4921             <code>address</code> element contains a single mandatory attribute
4922             <code>uuid</code>.
4923           </dd>
4924         </dl>
4925       </dd>
4926       <dt><code>vendor</code>, <code>product</code></dt>
4927       <dd>The <code>vendor</code> and <code>product</code> elements each have an
4928       <code>id</code> attribute that specifies the USB vendor and product id.
4929       The ids can be given in decimal, hexadecimal (starting with 0x) or
4930       octal (starting with 0) form.</dd>
4931       <dt><code>boot</code></dt>
4932       <dd>Specifies that the device is bootable. The <code>order</code>
4933       attribute determines the order in which devices will be tried during
4934       boot sequence. The per-device <code>boot</code> elements cannot be
4935       used together with general boot elements in
4936       <a href="#elementsOSBIOS">BIOS bootloader</a> section.
4937       <span class="since">Since 0.8.8</span> for PCI devices,
4938       <span class="since">Since 1.0.1</span> for USB devices.
4939       </dd>
4940       <dt><code>rom</code></dt>
4941       <dd>The <code>rom</code> element is used to change how a PCI
4942         device's ROM is presented to the guest. The optional <code>bar</code>
4943         attribute can be set to "on" or "off", and determines whether
4944         or not the device's ROM will be visible in the guest's memory
4945         map. (In PCI documentation, the "rombar" setting controls the
4946         presence of the Base Address Register for the ROM). If no rom
4947         bar is specified, the qemu default will be used (older
4948         versions of qemu used a default of "off", while newer qemus
4949         have a default of "on"). <span class="since">Since
4950         0.9.7 (QEMU and KVM only)</span>. The optional
4951         <code>file</code> attribute contains an absolute path to a binary file
4952         to be presented to the guest as the device's ROM BIOS. This
4953         can be useful, for example, to provide a PXE boot ROM for a
4954         virtual function of an sr-iov capable ethernet device (which
4955         has no boot ROMs for the VFs).
4956         <span class="since">Since 0.9.10 (QEMU and KVM only)</span>.
4957         The optional <code>enabled</code> attribute can be set to
4958         <code>no</code> to disable PCI ROM loading completely for the device;
4959         if PCI ROM loading is disabled through this attribute, attempts to
4960         tweak the loading process further using the <code>bar</code> or
4961         <code>file</code> attributes will be rejected.
4962         <span class="since">Since 4.3.0 (QEMU and KVM only)</span>.
4963       </dd>
4964       <dt><code>address</code></dt>
4965       <dd>The <code>address</code> element for USB devices has a
4966       <code>bus</code> and <code>device</code> attribute to specify the
4967       USB bus and device number the device appears at on the host.
4968       The values of these attributes can be given in decimal, hexadecimal
4969       (starting with 0x) or octal (starting with 0) form.
4970       For PCI devices the element carries 4 attributes allowing to designate
4971       the device as can be found with the <code>lspci</code> or
4972       with <code>virsh nodedev-list</code>. For SCSI devices a 'drive'
4973       address type must be used. For mediated devices, which are software-only
4974       devices defining an allocation of resources on the physical parent device,
4975       the address type used must conform to the <code>model</code> attribute
4976       of element <code>hostdev</code>, e.g. any address type other than PCI for
4977       <code>vfio-pci</code> device API or any address type other than CCW for
4978       <code>vfio-ccw</code> device API will result in an error.
4979       <a href="#elementsAddress">See above</a> for more details on the address
4980       element.</dd>
4981       <dt><code>driver</code></dt>
4982       <dd>
4983         PCI devices can have an optional <code>driver</code>
4984         subelement that specifies which backend driver to use for PCI
4985         device assignment. Use the <code>name</code> attribute to
4986         select either "vfio" (for the new VFIO device assignment
4987         backend, which is compatible with UEFI SecureBoot) or "kvm"
4988         (the legacy device assignment handled directly by the KVM
4989         kernel module)<span class="since">Since 1.0.5 (QEMU and KVM
4990         only, requires kernel 3.6 or newer)</span>. When specified,
4991         device assignment will fail if the requested method of device
4992         assignment isn't available on the host. When not specified,
4993         the default is "vfio" on systems where the VFIO driver is
4994         available and loaded, and "kvm" on older systems, or those
4995         where the VFIO driver hasn't been
4996         loaded <span class="since">Since 1.1.3</span> (prior to that
4997         the default was always "kvm").
4998       </dd>
4999       <dt><code>readonly</code></dt>
5000       <dd>Indicates that the device is readonly, only supported by SCSI host
5001         device now. <span class="since">Since 1.0.6 (QEMU and KVM only)</span>
5002       </dd>
5003       <dt><code>shareable</code></dt>
5004       <dd>If present, this indicates the device is expected to be shared
5005         between domains (assuming the hypervisor and OS support this).
5006         Only supported by SCSI host device.
5007         <span class="since">Since 1.0.6</span>
5008         <p>
5009           Note: Although <code>shareable</code> was introduced
5010           <span class="since">in 1.0.6</span>, it did not work as
5011           as expected until <span class="since">1.2.2</span>.
5012         </p>
5013       </dd>
5014     </dl>
5015
5016
5017     <h5><a id="elementsHostDevCaps">Block / character devices</a></h5>
5018
5019     <p>
5020       Block / character devices from the host can be passed through
5021       to the guest using the <code>hostdev</code> element. This is
5022       only possible with container based virtualization. Devices are specified
5023       by a fully qualified path.
5024       <span class="since">since after 1.0.1 for LXC</span>:
5025     </p>
5026
5027     <pre>
5028 ...
5029 &lt;hostdev mode='capabilities' type='storage'&gt;
5030   &lt;source&gt;
5031     &lt;block&gt;/dev/sdf1&lt;/block&gt;
5032   &lt;/source&gt;
5033 &lt;/hostdev&gt;
5034 ...
5035     </pre>
5036
5037     <pre>
5038 ...
5039 &lt;hostdev mode='capabilities' type='misc'&gt;
5040   &lt;source&gt;
5041     &lt;char&gt;/dev/input/event3&lt;/char&gt;
5042   &lt;/source&gt;
5043 &lt;/hostdev&gt;
5044 ...
5045     </pre>
5046
5047     <pre>
5048 ...
5049 &lt;hostdev mode='capabilities' type='net'&gt;
5050   &lt;source&gt;
5051     &lt;interface&gt;eth0&lt;/interface&gt;
5052   &lt;/source&gt;
5053 &lt;/hostdev&gt;
5054 ...
5055     </pre>
5056
5057     <dl>
5058       <dt><code>hostdev</code></dt>
5059       <dd>The <code>hostdev</code> element is the main container for describing
5060         host devices. For block/character device passthrough <code>mode</code> is
5061         always "capabilities" and <code>type</code> is "storage" for a block
5062         device, "misc" for a character device and "net" for a host network
5063         interface.
5064       </dd>
5065       <dt><code>source</code></dt>
5066       <dd>The source element describes the device as seen from the host.
5067         For block devices, the path to the block device in the host
5068         OS is provided in the nested "block" element, while for character
5069         devices the "char" element is used. For network interfaces, the
5070         name of the interface is provided in the "interface" element.
5071       </dd>
5072     </dl>
5073
5074     <h4><a id="elementsRedir">Redirected devices</a></h4>
5075
5076     <p>
5077       USB device redirection through a character device is
5078       supported <span class="since">since after 0.9.5 (KVM
5079       only)</span>:
5080     </p>
5081
5082 <pre>
5083 ...
5084 &lt;devices&gt;
5085   &lt;redirdev bus='usb' type='tcp'&gt;
5086     &lt;source mode='connect' host='localhost' service='4000'/&gt;
5087     &lt;boot order='1'/&gt;
5088   &lt;/redirdev&gt;
5089   &lt;redirfilter&gt;
5090     &lt;usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/&gt;
5091     &lt;usbdev allow='no'/&gt;
5092   &lt;/redirfilter&gt;
5093 &lt;/devices&gt;
5094 ...</pre>
5095
5096     <dl>
5097       <dt><code>redirdev</code></dt>
5098       <dd>The <code>redirdev</code> element is the main container for
5099         describing redirected devices. <code>bus</code> must be "usb"
5100         for a USB device.
5101
5102         An additional attribute <code>type</code> is required,
5103         matching one of the
5104         supported <a href="#elementsConsole">serial device</a> types,
5105         to describe the host side of the
5106         tunnel; <code>type='tcp'</code>
5107         or <code>type='spicevmc'</code> (which uses the usbredir
5108         channel of a <a href="#elementsGraphics">SPICE graphics
5109         device</a>) are typical. The redirdev element has an optional
5110         sub-element <code>&lt;address&gt;</code> which can tie the
5111         device to a particular controller. Further sub-elements,
5112         such as <code>&lt;source&gt;</code>, may be required according
5113         to the given type, although a <code>&lt;target&gt;</code> sub-element
5114         is not required (since the consumer of the character device is
5115         the hypervisor itself, rather than a device visible in the guest).
5116       </dd>
5117       <dt><code>boot</code></dt>
5118
5119       <dd>Specifies that the device is bootable.
5120         The <code>order</code> attribute determines the order in which
5121         devices will be tried during boot sequence. The per-device
5122         <code>boot</code> elements cannot be used together with general
5123         boot elements in  <a href="#elementsOSBIOS">BIOS bootloader</a> section.
5124         (<span class="since">Since 1.0.1</span>)
5125       </dd>
5126       <dt><code>redirfilter</code></dt>
5127       <dd>The<code> redirfilter </code>element is used for creating the
5128         filter rule to filter out certain devices from redirection.
5129         It uses sub-element <code>&lt;usbdev&gt;</code> to define each filter rule.
5130         <code>class</code> attribute is the USB Class code, for example,
5131         0x08 represents mass storage devices. The USB device can be addressed by
5132         vendor / product id using the <code>vendor</code> and <code>product</code> attributes.
5133         <code>version</code> is the device revision from the bcdDevice field (not
5134         the version of the USB protocol).
5135         These four attributes are optional and <code>-1</code> can be used to allow
5136         any value for them. <code>allow</code> attribute is mandatory,
5137         'yes' means allow, 'no' for deny.
5138       </dd>
5139     </dl>
5140
5141     <h4><a id="elementsSmartcard">Smartcard devices</a></h4>
5142
5143     <p>
5144       A virtual smartcard device can be supplied to the guest via the
5145       <code>smartcard</code> element. A USB smartcard reader device on
5146       the host cannot be used on a guest with simple device
5147       passthrough, since it will then not be available on the host,
5148       possibly locking the host computer when it is "removed".
5149       Therefore, some hypervisors provide a specialized virtual device
5150       that can present a smartcard interface to the guest, with
5151       several modes for describing how credentials are obtained from
5152       the host or even a from a channel created to a third-party
5153       smartcard provider. <span class="since">Since 0.8.8</span>
5154     </p>
5155
5156 <pre>
5157 ...
5158 &lt;devices&gt;
5159   &lt;smartcard mode='host'/&gt;
5160   &lt;smartcard mode='host-certificates'&gt;
5161     &lt;certificate&gt;cert1&lt;/certificate&gt;
5162     &lt;certificate&gt;cert2&lt;/certificate&gt;
5163     &lt;certificate&gt;cert3&lt;/certificate&gt;
5164     &lt;database&gt;/etc/pki/nssdb/&lt;/database&gt;
5165   &lt;/smartcard&gt;
5166   &lt;smartcard mode='passthrough' type='tcp'&gt;
5167     &lt;source mode='bind' host='127.0.0.1' service='2001'/&gt;
5168     &lt;protocol type='raw'/&gt;
5169     &lt;address type='ccid' controller='0' slot='0'/&gt;
5170   &lt;/smartcard&gt;
5171   &lt;smartcard mode='passthrough' type='spicevmc'/&gt;
5172 &lt;/devices&gt;
5173 ...
5174 </pre>
5175
5176     <p>
5177       The <code>&lt;smartcard&gt;</code> element has a mandatory
5178       attribute <code>mode</code>.  The following modes are supported;
5179       in each mode, the guest sees a device on its USB bus that
5180       behaves like a physical USB CCID (Chip/Smart Card Interface
5181       Device) card.
5182     </p>
5183
5184     <dl>
5185       <dt><code>host</code></dt>
5186       <dd>The simplest operation, where the hypervisor relays all
5187       requests from the guest into direct access to the host's
5188       smartcard via NSS.  No other attributes or sub-elements are
5189       required.  See below about the use of an
5190       optional <code>&lt;address&gt;</code> sub-element.</dd>
5191
5192       <dt><code>host-certificates</code></dt>
5193       <dd>Rather than requiring a smartcard to be plugged into the
5194       host, it is possible to provide three NSS certificate names
5195       residing in a database on the host.  These certificates can be
5196       generated via the command <code>certutil -d /etc/pki/nssdb -x -t
5197       CT,CT,CT -S -s CN=cert1 -n cert1</code>, and the resulting three
5198       certificate names must be supplied as the content of each of
5199       three <code>&lt;certificate&gt;</code> sub-elements.  An
5200       additional sub-element <code>&lt;database&gt;</code> can specify
5201       the absolute path to an alternate directory (matching
5202       the <code>-d</code> option of the <code>certutil</code> command
5203       when creating the certificates); if not present, it defaults to
5204       /etc/pki/nssdb.</dd>
5205
5206       <dt><code>passthrough</code></dt>
5207       <dd>Rather than having the hypervisor directly communicate with
5208       the host, it is possible to tunnel all requests through a
5209       secondary character device to a third-party provider (which may
5210       in turn be talking to a smartcard or using three certificate
5211       files).  In this mode of operation, an additional
5212       attribute <code>type</code> is required, matching one of the
5213       supported <a href="#elementsConsole">serial device</a> types, to
5214       describe the host side of the tunnel; <code>type='tcp'</code>
5215       or <code>type='spicevmc'</code> (which uses the smartcard
5216       channel of a <a href="#elementsGraphics">SPICE graphics
5217       device</a>) are typical.  Further sub-elements, such
5218       as <code>&lt;source&gt;</code>, may be required according to the
5219       given type, although a <code>&lt;target&gt;</code> sub-element
5220       is not required (since the consumer of the character device is
5221       the hypervisor itself, rather than a device visible in the
5222       guest).</dd>
5223     </dl>
5224
5225     <p>
5226       Each mode supports an optional
5227       sub-element <code>&lt;address&gt;</code>, which fine-tunes the
5228       correlation between the smartcard and a ccid bus
5229       controller, <a href="#elementsAddress">documented above</a>.
5230       For now, qemu only supports at most one
5231       smartcard, with an address of bus=0 slot=0.
5232     </p>
5233
5234     <h4><a id="elementsNICS">Network interfaces</a></h4>
5235
5236 <pre>
5237 ...
5238 &lt;devices&gt;
5239   &lt;interface type='direct' trustGuestRxFilters='yes'&gt;
5240     &lt;source dev='eth0'/&gt;
5241     &lt;mac address='52:54:00:5d:c7:9e'/&gt;
5242     &lt;boot order='1'/&gt;
5243     &lt;rom bar='off'/&gt;
5244   &lt;/interface&gt;
5245 &lt;/devices&gt;
5246 ...</pre>
5247
5248     <p>
5249       There are several possibilities for specifying a network
5250       interface visible to the guest.  Each subsection below provides
5251       more details about common setup options.
5252     </p>
5253     <p>
5254       <span class="since">Since 1.2.10</span>),
5255       the <code>interface</code> element
5256       property <code>trustGuestRxFilters</code> provides the
5257       capability for the host to detect and trust reports from the
5258       guest regarding changes to the interface mac address and receive
5259       filters by setting the attribute to <code>yes</code>. The default
5260       setting for the attribute is <code>no</code> for security
5261       reasons and support depends on the guest network device model as
5262       well as the type of connection on the host - currently it is
5263       only supported for the virtio device model and for macvtap
5264       connections on the host.
5265     </p>
5266     <p>
5267       Each <code>&lt;interface&gt;</code> element has an
5268       optional <code>&lt;address&gt;</code> sub-element that can tie
5269       the interface to a particular pci slot, with
5270       attribute <code>type='pci'</code>
5271       as <a href="#elementsAddress">documented above</a>.
5272     </p>
5273
5274     <h5><a id="elementsNICSVirtual">Virtual network</a></h5>
5275
5276     <p>
5277       <strong><em>
5278       This is the recommended config for general guest connectivity on
5279       hosts with dynamic / wireless networking configs (or multi-host
5280       environments where the host hardware details are described
5281       separately in a <code>&lt;network&gt;</code>
5282       definition <span class="since">Since 0.9.4</span>).
5283       </em></strong>
5284     </p>
5285
5286     <p>
5287
5288       Provides a connection whose details are described by the named
5289       network definition. Depending on the virtual network's "forward
5290       mode" configuration, the network may be totally isolated
5291       (no <code>&lt;forward&gt;</code> element given), NAT'ing to an
5292       explicit network device or to the default route
5293       (<code>&lt;forward mode='nat'&gt;</code>), routed with no NAT
5294       (<code>&lt;forward mode='route'/&gt;</code>), or connected
5295       directly to one of the host's network interfaces (via macvtap)
5296       or bridge devices ((<code>&lt;forward
5297       mode='bridge|private|vepa|passthrough'/&gt;</code> <span class="since">Since
5298       0.9.4</span>)
5299     </p>
5300     <p>
5301       For networks with a forward mode of bridge, private, vepa, and
5302       passthrough, it is assumed that the host has any necessary DNS
5303       and DHCP services already setup outside the scope of libvirt. In
5304       the case of isolated, nat, and routed networks, DHCP and DNS are
5305       provided on the virtual network by libvirt, and the IP range can
5306       be determined by examining the virtual network config with
5307       '<code>virsh net-dumpxml [networkname]</code>'. There is one
5308       virtual network called 'default' setup out of the box which does
5309       NAT'ing to the default route and has an IP range
5310       of <code>192.168.122.0/255.255.255.0</code>. Each guest will
5311       have an associated tun device created with a name of vnetN,
5312       which can also be overridden with the &lt;target&gt; element
5313       (see
5314       <a href="#elementsNICSTargetOverride">overriding the target element</a>).
5315     </p>
5316     <p>
5317       When the source of an interface is a network,
5318       a <code>portgroup</code> can be specified along with the name of
5319       the network; one network may have multiple portgroups defined,
5320       with each portgroup containing slightly different configuration
5321       information for different classes of network
5322       connections. <span class="since">Since 0.9.4</span>.
5323     </p>
5324     <p>
5325       When a guest is running an interface of type <code>network</code>
5326       may include a <code>portid</code> attribute. This provides the UUID
5327       of an associated virNetworkPortPtr object that records the association
5328       between the domain interface and the network. This attribute is
5329       read-only since port objects are create and deleted automatically
5330       during startup and shutdown. <span class="since">Since 5.1.0</span>
5331     </p>
5332     <p>
5333       Also, similar to <code>direct</code> network connections
5334       (described below), a connection of type <code>network</code> may
5335       specify a <code>virtualport</code> element, with configuration
5336       data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant
5337       switch (<span class="since">Since 0.8.2</span>), or to an
5338       Open vSwitch virtual switch (<span class="since">Since
5339       0.9.11</span>).
5340     </p>
5341     <p>
5342       Since the actual type of switch may vary depending on the
5343       configuration in the <code>&lt;network&gt;</code> on the host,
5344       it is acceptable to omit the virtualport <code>type</code>
5345       attribute, and specify attributes from multiple different
5346       virtualport types (and also to leave out certain attributes); at
5347       domain startup time, a complete <code>&lt;virtualport&gt;</code>
5348       element will be constructed by merging together the type and
5349       attributes defined in the network and the portgroup referenced
5350       by the interface. The newly-constructed virtualport is a combination
5351       of them. The attributes from lower virtualport can't make change
5352       on the ones defined in higher virtualport.
5353       Interface takes the highest priority, portgroup is lowest priority.
5354       (<span class="since">Since 0.10.0</span>). For example, in order
5355       to work properly with both an 802.1Qbh switch and an Open vSwitch
5356       switch, you may choose to specify no type, but both
5357       a <code>profileid</code> (in case the switch is 802.1Qbh) and
5358       an <code>interfaceid</code> (in case the switch is Open vSwitch)
5359       (you may also omit the other attributes, such as managerid,
5360       typeid, or profileid, to be filled in from the
5361       network's <code>&lt;virtualport&gt;</code>). If you want to
5362       limit a guest to connecting only to certain types of switches,
5363       you can specify the virtualport type, but still omit some/all of
5364       the parameters - in this case if the host's network has a
5365       different type of virtualport, connection of the interface will
5366       fail.
5367     </p>
5368
5369 <pre>
5370 ...
5371 &lt;devices&gt;
5372   &lt;interface type='network'&gt;
5373     &lt;source network='default'/&gt;
5374   &lt;/interface&gt;
5375   ...
5376   &lt;interface type='network'&gt;
5377     &lt;source network='default' portgroup='engineering'/&gt;
5378     &lt;target dev='vnet7'/&gt;
5379     &lt;mac address="00:11:22:33:44:55"/&gt;
5380     &lt;virtualport&gt;
5381       &lt;parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&gt;
5382     &lt;/virtualport&gt;
5383   &lt;/interface&gt;
5384 &lt;/devices&gt;
5385 ...</pre>
5386
5387     <h5><a id="elementsNICSBridge">Bridge to LAN</a></h5>
5388
5389     <p>
5390       <strong><em>
5391       This is the recommended config for general guest connectivity on
5392       hosts with static wired networking configs.
5393       </em></strong>
5394     </p>
5395
5396     <p>
5397       Provides a bridge from the VM directly to the LAN. This assumes
5398       there is a bridge device on the host which has one or more of the hosts
5399       physical NICs enslaved. The guest VM will have an associated tun device
5400       created with a name of vnetN, which can also be overridden with the
5401       &lt;target&gt; element (see
5402       <a href="#elementsNICSTargetOverride">overriding the target element</a>).
5403       The tun device will be enslaved to the bridge. The IP range / network
5404       configuration is whatever is used on the LAN. This provides the guest VM
5405       full incoming &amp; outgoing net access just like a physical machine.
5406     </p>
5407     <p>
5408       On Linux systems, the bridge device is normally a standard Linux
5409       host bridge. On hosts that support Open vSwitch, it is also
5410       possible to connect to an Open vSwitch bridge device by adding
5411       a <code>&lt;virtualport type='openvswitch'/&gt;</code> to the
5412       interface definition.  (<span class="since">Since
5413       0.9.11</span>). The Open vSwitch type virtualport accepts two
5414       parameters in its <code>&lt;parameters&gt;</code> element -
5415       an <code>interfaceid</code> which is a standard uuid used to
5416       uniquely identify this particular interface to Open vSwitch (if
5417       you do not specify one, a random interfaceid will be generated
5418       for you when you first define the interface), and an
5419       optional <code>profileid</code> which is sent to Open vSwitch as
5420       the interfaces "port-profile".
5421     </p>
5422 <pre>
5423 ...
5424 &lt;devices&gt;
5425   ...
5426   &lt;interface type='bridge'&gt;
5427     &lt;source bridge='br0'/&gt;
5428   &lt;/interface&gt;
5429   &lt;interface type='bridge'&gt;
5430     &lt;source bridge='br1'/&gt;
5431     &lt;target dev='vnet7'/&gt;
5432     &lt;mac address="00:11:22:33:44:55"/&gt;
5433   &lt;/interface&gt;
5434   &lt;interface type='bridge'&gt;
5435     &lt;source bridge='ovsbr'/&gt;
5436     &lt;virtualport type='openvswitch'&gt;
5437       &lt;parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&gt;
5438     &lt;/virtualport&gt;
5439   &lt;/interface&gt;
5440   ...
5441 &lt;/devices&gt;
5442 ...</pre>
5443
5444     <p>
5445       On hosts that support Open vSwitch on the kernel side and have the
5446       Midonet Host Agent configured, it is also possible to connect to the
5447       'midonet' bridge device by adding a
5448       <code>&lt;virtualport type='midonet'/&gt;</code> to the
5449       interface definition.  (<span class="since">Since
5450       1.2.13</span>). The Midonet virtualport type requires an
5451       <code>interfaceid</code> attribute in its
5452       <code>&lt;parameters&gt;</code> element. This interface id is the UUID
5453       that specifies which port in the virtual network topology will be bound
5454       to the interface.
5455     </p>
5456 <pre>
5457 ...
5458 &lt;devices&gt;
5459   ...
5460   &lt;interface type='bridge'&gt;
5461     &lt;source bridge='br0'/&gt;
5462   &lt;/interface&gt;
5463   &lt;interface type='bridge'&gt;
5464     &lt;source bridge='br1'/&gt;
5465     &lt;target dev='vnet7'/&gt;
5466     &lt;mac address="00:11:22:33:44:55"/&gt;
5467   &lt;/interface&gt;
5468   &lt;interface type='bridge'&gt;
5469     &lt;source bridge='midonet'/&gt;
5470     &lt;virtualport type='midonet'&gt;
5471       &lt;parameters interfaceid='0b2d64da-3d0e-431e-afdd-804415d6ebbb'/&gt;
5472     &lt;/virtualport&gt;
5473   &lt;/interface&gt;
5474   ...
5475 &lt;/devices&gt;
5476 ...</pre>
5477
5478     <h5><a id="elementsNICSSlirp">Userspace SLIRP stack</a></h5>
5479
5480     <p>
5481       Provides a virtual LAN with NAT to the outside world. The virtual
5482       network has DHCP &amp; DNS services and will give the guest VM addresses
5483       starting from <code>10.0.2.15</code>. The default router will be
5484       <code>10.0.2.2</code> and the DNS server will be <code>10.0.2.3</code>.
5485       This networking is the only option for unprivileged users who need their
5486       VMs to have outgoing access. <span class="since">Since 3.8.0</span>
5487       it is possible to override the default network address by
5488       including an <code>ip</code> element specifying an IPv4
5489       address in its one mandatory attribute, <code>address</code>.
5490       Optionally, a second <code>ip</code> element with a
5491       <code>family</code> attribute set to "ipv6" can be
5492       specified to add an IPv6 address to the interface.
5493       <code>address</code>. Optionally, address
5494       <code>prefix</code> can be specified.
5495     </p>
5496
5497 <pre>
5498 ...
5499 &lt;devices&gt;
5500   &lt;interface type='user'/&gt;
5501   ...
5502   &lt;interface type='user'&gt;
5503     &lt;mac address="00:11:22:33:44:55"/&gt;
5504     &lt;ip family='ipv4' address='172.17.2.0' prefix='24'/&gt;
5505     &lt;ip family='ipv6' address='2001:db8:ac10:fd01::' prefix='64'/&gt;
5506   &lt;/interface&gt;
5507 &lt;/devices&gt;
5508 ...</pre>
5509
5510
5511     <h5><a id="elementsNICSEthernet">Generic ethernet connection</a></h5>
5512
5513     <p>
5514       Provides a means for the administrator to execute an arbitrary script
5515       to connect the guest's network to the LAN. The guest will have a tun
5516       device created with a name of vnetN, which can also be overridden with the
5517       &lt;target&gt; element. After creating the tun device a shell script will
5518       be run which is expected to do whatever host network integration is
5519       required. By default this script is called /etc/qemu-ifup but can be
5520       overridden.
5521     </p>
5522
5523 <pre>
5524 ...
5525 &lt;devices&gt;
5526   &lt;interface type='ethernet'/&gt;
5527   ...
5528   &lt;interface type='ethernet'&gt;
5529     &lt;target dev='vnet7'/&gt;
5530     &lt;script path='/etc/qemu-ifup-mynet'/&gt;
5531   &lt;/interface&gt;
5532 &lt;/devices&gt;
5533 ...</pre>
5534
5535     <h5><a id="elementsNICSDirect">Direct attachment to physical interface</a></h5>
5536
5537     <p>
5538       Provides direct attachment of the virtual machine's NIC to the given
5539       physical interface of the host.
5540       <span class="since">Since 0.7.7 (QEMU and KVM only)</span><br/>
5541       This setup requires the Linux macvtap
5542       driver to be available. <span class="since">(Since Linux 2.6.34.)</span>
5543       One of the modes 'vepa'
5544       ( <a href="http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf">
5545       'Virtual Ethernet Port Aggregator'</a>), 'bridge' or 'private'
5546       can be chosen for the operation mode of the macvtap device, 'vepa'
5547       being the default mode. The individual modes cause the delivery of
5548       packets to behave as follows:
5549     </p>
5550     <p>
5551       If the model type is set to <code>virtio</code> and
5552       interface's <code>trustGuestRxFilters</code> attribute is set
5553       to <code>yes</code>, changes made to the interface mac address,
5554       unicast/multicast receive filters, and vlan settings in the
5555       guest will be monitored and propagated to the associated macvtap
5556       device on the host (<span class="since">Since
5557       1.2.10</span>). If <code>trustGuestRxFilters</code> is not set,
5558       or is not supported for the device model in use, an attempted
5559       change to the mac address originating from the guest side will
5560       result in a non-working network connection.
5561     </p>
5562
5563     <dl>
5564       <dt><code>vepa</code></dt>
5565       <dd>All VMs' packets are sent to the external bridge. Packets
5566       whose destination is a VM on the same host as where the
5567       packet originates from are sent back to the host by the VEPA
5568       capable bridge (today's bridges are typically not VEPA capable).</dd>
5569       <dt><code>bridge</code></dt>
5570       <dd>Packets whose destination is on the same host as where they
5571       originate from are directly delivered to the target macvtap device.
5572       Both origin and destination devices need to be in bridge mode
5573       for direct delivery. If either one of them is in <code>vepa</code> mode,
5574       a VEPA capable bridge is required.</dd>
5575       <dt><code>private</code></dt>
5576       <dd>All packets are sent to the external bridge and will only be
5577       delivered to a target VM on the same host if they are sent through an
5578       external router or gateway and that device sends them back to the
5579       host. This procedure is followed if either the source or destination
5580       device is in <code>private</code> mode.</dd>
5581       <dt><code>passthrough</code></dt>
5582       <dd>This feature attaches a virtual function of a SRIOV capable
5583       NIC directly to a VM without losing the migration capability.
5584       All packets are sent to the VF/IF of the configured network device.
5585       Depending on the capabilities of the device additional prerequisites or
5586       limitations may apply; for example, on Linux this requires
5587       kernel 2.6.38 or newer. <span class="since">Since 0.9.2</span></dd>
5588     </dl>
5589
5590 <pre>
5591 ...
5592 &lt;devices&gt;
5593   ...
5594   &lt;interface type='direct' trustGuestRxFilters='no'&gt;
5595     &lt;source dev='eth0' mode='vepa'/&gt;
5596   &lt;/interface&gt;
5597 &lt;/devices&gt;
5598 ...</pre>
5599
5600     <p>
5601       The network access of direct attached virtual machines can be
5602       managed by the hardware switch to which the physical interface
5603       of the host machine is connected to.
5604     </p>
5605     <p>
5606       The interface can have additional parameters as shown below,
5607       if the switch is conforming to the IEEE 802.1Qbg standard.
5608       The parameters of the virtualport element are documented in more detail
5609       in the IEEE 802.1Qbg standard. The values are network specific and
5610       should be provided by the network administrator. In 802.1Qbg terms,
5611       the Virtual Station Interface (VSI) represents the virtual interface
5612       of a virtual machine. <span class="since">Since 0.8.2</span>
5613     </p>
5614     <p>
5615       Please note that IEEE 802.1Qbg requires a non-zero value for the
5616       VLAN ID.
5617     </p>
5618     <dl>
5619       <dt><code>managerid</code></dt>
5620       <dd>The VSI Manager ID identifies the database containing the VSI type
5621         and instance definitions. This is an integer value and the
5622         value 0 is reserved.</dd>
5623       <dt><code>typeid</code></dt>
5624       <dd>The VSI Type ID identifies a VSI type characterizing the network
5625         access. VSI types are typically managed by network administrator.
5626         This is an integer value.
5627       </dd>
5628       <dt><code>typeidversion</code></dt>
5629       <dd>The VSI Type Version allows multiple versions of a VSI Type.
5630         This is an integer value.
5631       </dd>
5632       <dt><code>instanceid</code></dt>
5633       <dd>The VSI Instance ID Identifier is generated when a VSI instance
5634         (i.e. a virtual interface of a virtual machine) is created.
5635         This is a globally unique identifier.
5636       </dd>
5637     </dl>
5638 <pre>
5639 ...
5640 &lt;devices&gt;
5641   ...
5642   &lt;interface type='direct'&gt;
5643     &lt;source dev='eth0.2' mode='vepa'/&gt;
5644     &lt;virtualport type="802.1Qbg"&gt;
5645       &lt;parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/&gt;
5646     &lt;/virtualport&gt;
5647   &lt;/interface&gt;
5648 &lt;/devices&gt;
5649 ...</pre>
5650
5651     <p>
5652       The interface can have additional parameters as shown below
5653       if the switch is conforming to the IEEE 802.1Qbh standard.
5654       The values are network specific and should be provided by the
5655       network administrator. <span class="since">Since 0.8.2</span>
5656     </p>
5657     <dl>
5658       <dt><code>profileid</code></dt>
5659       <dd>The profile ID contains the name of the port profile that is to
5660         be applied to this interface.  This name is resolved by the port
5661         profile database into the network parameters from the port profile,
5662         and those network parameters will be applied to this interface.
5663       </dd>
5664     </dl>
5665   <pre>
5666 ...
5667 &lt;devices&gt;
5668   ...
5669   &lt;interface type='direct'&gt;
5670     &lt;source dev='eth0' mode='private'/&gt;
5671     &lt;virtualport type='802.1Qbh'&gt;
5672       &lt;parameters profileid='finance'/&gt;
5673     &lt;/virtualport&gt;
5674   &lt;/interface&gt;
5675 &lt;/devices&gt;
5676 ...
5677 </pre>
5678
5679
5680     <h5><a id="elementsNICSHostdev">PCI Passthrough</a></h5>
5681
5682     <p>
5683       A PCI network device (specified by the &lt;source&gt; element)
5684       is directly assigned to the guest using generic device
5685       passthrough, after first optionally setting the device's MAC
5686       address to the configured value, and associating the device with
5687       an 802.1Qbh capable switch using an optionally specified
5688       &lt;virtualport&gt; element (see the examples of virtualport
5689       given above for type='direct' network devices). Note that - due
5690       to limitations in standard single-port PCI ethernet card driver
5691       design - only SR-IOV (Single Root I/O Virtualization) virtual
5692       function (VF) devices can be assigned in this manner; to assign
5693       a standard single-port PCI or PCIe ethernet card to a guest, use
5694       the traditional &lt;hostdev&gt; device definition and
5695       <span class="since">Since 0.9.11</span>
5696     </p>
5697
5698     <p>
5699       To use VFIO device assignment rather than traditional/legacy KVM
5700       device assignment (VFIO is a new method of device assignment
5701       that is compatible with UEFI Secure Boot), a type='hostdev'
5702       interface can have an optional <code>driver</code> sub-element
5703       with a <code>name</code> attribute set to "vfio". To use legacy
5704       KVM device assignment you can set <code>name</code> to "kvm" (or
5705       simply omit the <code>&lt;driver&gt;</code> element, since "kvm"
5706       is currently the default).
5707       <span class="since">Since 1.0.5 (QEMU and KVM only, requires kernel 3.6 or newer)</span>
5708     </p>
5709
5710     <p>
5711       Note that this "intelligent passthrough" of network devices is
5712       very similar to the functionality of a standard &lt;hostdev&gt;
5713       device, the difference being that this method allows specifying
5714       a MAC address and &lt;virtualport&gt; for the passed-through
5715       device. If these capabilities are not required, if you have a
5716       standard single-port PCI, PCIe, or USB network card that doesn't
5717       support SR-IOV (and hence would anyway lose the configured MAC
5718       address during reset after being assigned to the guest domain),
5719       or if you are using a version of libvirt older than 0.9.11, you
5720       should use standard &lt;hostdev&gt; to assign the device to the
5721       guest instead of &lt;interface type='hostdev'/&gt;.
5722     </p>
5723
5724     <p>
5725       Similar to the functionality of a standard &lt;hostdev&gt; device,
5726       when <code>managed</code> is "yes", it is detached from the host
5727       before being passed on to the guest, and reattached to the host
5728       after the guest exits. If <code>managed</code> is omitted or "no",
5729       the user is responsible to call <code>virNodeDeviceDettach</code>
5730       (or <code>virsh nodedev-detach</code>) before starting the guest
5731       or hot-plugging the device, and <code>virNodeDeviceReAttach</code>
5732       (or <code>virsh nodedev-reattach</code>) after hot-unplug or
5733       stopping the guest.
5734     </p>
5735
5736 <pre>
5737 ...
5738 &lt;devices&gt;
5739   &lt;interface type='hostdev' managed='yes'&gt;
5740     &lt;driver name='vfio'/&gt;
5741     &lt;source&gt;
5742       &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/&gt;
5743     &lt;/source&gt;
5744     &lt;mac address='52:54:00:6d:90:02'/&gt;
5745     &lt;virtualport type='802.1Qbh'&gt;
5746       &lt;parameters profileid='finance'/&gt;
5747     &lt;/virtualport&gt;
5748   &lt;/interface&gt;
5749 &lt;/devices&gt;
5750 ...</pre>
5751
5752
5753     <h5><a id="elementsNICSMulticast">Multicast tunnel</a></h5>
5754
5755     <p>
5756       A multicast group is setup to represent a virtual network. Any VMs
5757       whose network devices are in the same multicast group can talk to each
5758       other even across hosts. This mode is also available to unprivileged
5759       users. There is no default DNS or DHCP support and no outgoing network
5760       access. To provide outgoing network access, one of the VMs should have a
5761       2nd NIC which is connected to one of the first 4 network types and do the
5762       appropriate routing. The multicast protocol is compatible with that used
5763       by user mode linux guests too. The source address used must be from the
5764       multicast address block.
5765     </p>
5766
5767 <pre>
5768 ...
5769 &lt;devices&gt;
5770   &lt;interface type='mcast'&gt;
5771     &lt;mac address='52:54:00:6d:90:01'/&gt;
5772     &lt;source address='230.0.0.1' port='5558'/&gt;
5773   &lt;/interface&gt;
5774 &lt;/devices&gt;
5775 ...</pre>
5776
5777     <h5><a id="elementsNICSTCP">TCP tunnel</a></h5>
5778
5779     <p>
5780       A TCP client/server architecture provides a virtual network. One VM
5781       provides the server end of the network, all other VMS are configured as
5782       clients. All network traffic is routed between the VMs via the server.
5783       This mode is also available to unprivileged users. There is no default
5784       DNS or DHCP support and no outgoing network access. To provide outgoing
5785       network access, one of the VMs should have a 2nd NIC which is connected
5786       to one of the first 4 network types and do the appropriate routing.</p>
5787
5788 <pre>
5789 ...
5790 &lt;devices&gt;
5791   &lt;interface type='server'&gt;
5792     &lt;mac address='52:54:00:22:c9:42'/&gt;
5793     &lt;source address='192.168.0.1' port='5558'/&gt;
5794   &lt;/interface&gt;
5795   ...
5796   &lt;interface type='client'&gt;
5797     &lt;mac address='52:54:00:8b:c9:51'/&gt;
5798     &lt;source address='192.168.0.1' port='5558'/&gt;
5799   &lt;/interface&gt;
5800 &lt;/devices&gt;
5801 ...</pre>
5802
5803     <h5><a id="elementsNICSUDP">UDP unicast tunnel</a></h5>
5804
5805     <p>
5806     A UDP unicast architecture provides a virtual network which enables
5807     connections between QEMU instances using QEMU's UDP infrastructure.
5808
5809     The xml "source" address is the endpoint address to which the UDP socket
5810     packets will be sent from the host running QEMU.
5811     The xml "local" address is the address of the interface from which the
5812     UDP socket packets will originate from the QEMU host.
5813     <span class="since">Since 1.2.20</span></p>
5814
5815 <pre>
5816 ...
5817 &lt;devices&gt;
5818   &lt;interface type='udp'&gt;
5819     &lt;mac address='52:54:00:22:c9:42'/&gt;
5820     &lt;source address='127.0.0.1' port='11115'&gt;
5821       &lt;local address='127.0.0.1' port='11116'/&gt;
5822     &lt;/source&gt;
5823   &lt;/interface&gt;
5824 &lt;/devices&gt;
5825 ...</pre>
5826
5827     <h5><a id="elementsNICSModel">Setting the NIC model</a></h5>
5828
5829 <pre>
5830 ...
5831 &lt;devices&gt;
5832   &lt;interface type='network'&gt;
5833     &lt;source network='default'/&gt;
5834     &lt;target dev='vnet1'/&gt;
5835     <b>&lt;model type='ne2k_pci'/&gt;</b>
5836   &lt;/interface&gt;
5837 &lt;/devices&gt;
5838 ...</pre>
5839
5840     <p>
5841       For hypervisors which support this, you can set the model of
5842       emulated network interface card.
5843     </p>
5844
5845     <p>
5846       The values for <code>type</code> aren't defined specifically by
5847       libvirt, but by what the underlying hypervisor supports (if
5848       any).  For QEMU and KVM you can get a list of supported models
5849       with these commands:
5850     </p>
5851
5852 <pre>
5853 qemu -net nic,model=? /dev/null
5854 qemu-kvm -net nic,model=? /dev/null
5855 </pre>
5856
5857     <p>
5858       Typical values for QEMU and KVM include:
5859       ne2k_isa i82551 i82557b i82559er ne2k_pci pcnet rtl8139 e1000 virtio.
5860       <span class="since">Since 5.2.0</span>, <code>virtio-transitional</code>
5861       and <code>virtio-non-transitional</code> values are supported.
5862       See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
5863       for more details.
5864     </p>
5865
5866     <h5><a id="elementsDriverBackendOptions">Setting NIC driver-specific options</a></h5>
5867
5868 <pre>
5869 ...
5870 &lt;devices&gt;
5871   &lt;interface type='network'&gt;
5872     &lt;source network='default'/&gt;
5873     &lt;target dev='vnet1'/&gt;
5874     &lt;model type='virtio'/&gt;
5875     <b>&lt;driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'&gt;
5876       &lt;host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/&gt;
5877       &lt;guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/&gt;
5878     &lt;/driver&gt;
5879     </b>&lt;/interface&gt;
5880 &lt;/devices&gt;
5881 ...</pre>
5882
5883     <p>
5884       Some NICs may have tunable driver-specific options. These are
5885       set as attributes of the <code>driver</code> sub-element of the
5886       interface definition. Currently the following attributes are
5887       available for the <code>"virtio"</code> NIC driver:
5888     </p>
5889
5890     <dl>
5891       <dt><code>name</code></dt>
5892       <dd>
5893         The optional <code>name</code> attribute forces which type of
5894         backend driver to use. The value can be either 'qemu' (a
5895         user-space backend) or 'vhost' (a kernel backend, which
5896         requires the vhost module to be provided by the kernel); an
5897         attempt to require the vhost driver without kernel support
5898         will be rejected.  If this attribute is not present, then the
5899         domain defaults to 'vhost' if present, but silently falls back
5900         to 'qemu' without error.
5901         <span class="since">Since 0.8.8 (QEMU and KVM only)</span>
5902       </dd>
5903       <dd>
5904         For interfaces of type='hostdev' (PCI passthrough devices)
5905         the <code>name</code> attribute can optionally be set to
5906         "vfio" or "kvm". "vfio" tells libvirt to use VFIO device
5907         assignment rather than traditional KVM device assignment (VFIO
5908         is a new method of device assignment that is compatible with
5909         UEFI Secure Boot), and "kvm" tells libvirt to use the legacy
5910         device assignment performed directly by the kvm kernel module
5911         (the default is currently "kvm", but is subject to change).
5912         <span class="since">Since 1.0.5 (QEMU and KVM only, requires
5913         kernel 3.6 or newer)</span>
5914       </dd>
5915       <dd>
5916         For interfaces of type='vhostuser', the <code>name</code>
5917         attribute is ignored. The backend driver used is always
5918         vhost-user.
5919       </dd>
5920
5921       <dt><code>txmode</code></dt>
5922       <dd>
5923         The <code>txmode</code> attribute specifies how to handle
5924         transmission of packets when the transmit buffer is full. The
5925         value can be either 'iothread' or 'timer'.
5926         <span class="since">Since 0.8.8 (QEMU and KVM only)</span><br/><br/>
5927
5928         If set to 'iothread', packet tx is all done in an iothread in
5929         the bottom half of the driver (this option translates into
5930         adding "tx=bh" to the qemu commandline -device virtio-net-pci
5931         option).<br/><br/>
5932
5933         If set to 'timer', tx work is done in qemu, and if there is
5934         more tx data than can be sent at the present time, a timer is
5935         set before qemu moves on to do other things; when the timer
5936         fires, another attempt is made to send more data.<br/><br/>
5937
5938         The resulting difference, according to the qemu developer who
5939         added the option is: "bh makes tx more asynchronous and reduces
5940         latency, but potentially causes more processor bandwidth
5941         contention since the CPU doing the tx isn't necessarily the
5942         CPU where the guest generated the packets."<br/><br/>
5943
5944         <b>In general you should leave this option alone, unless you
5945         are very certain you know what you are doing.</b>
5946       </dd>
5947       <dt><code>ioeventfd</code></dt>
5948       <dd>
5949         This optional attribute allows users to set
5950         <a href='https://patchwork.kernel.org/patch/43390/'>
5951         domain I/O asynchronous handling</a> for interface device.
5952         The default is left to the discretion of the hypervisor.
5953         Accepted values are "on" and "off". Enabling this allows
5954         qemu to execute VM while a separate thread handles I/O.
5955         Typically guests experiencing high system CPU utilization
5956         during I/O will benefit from this. On the other hand,
5957         on overloaded host it could increase guest I/O latency.
5958         <span class="since">Since 0.9.3 (QEMU and KVM only)</span><br/><br/>
5959
5960         <b>In general you should leave this option alone, unless you
5961         are very certain you know what you are doing.</b>
5962       </dd>
5963       <dt><code>event_idx</code></dt>
5964       <dd>
5965         The <code>event_idx</code> attribute controls some aspects of
5966         device event processing. The value can be either 'on' or 'off'
5967         - if it is on, it will reduce the number of interrupts and
5968         exits for the guest. The default is determined by QEMU;
5969         usually if the feature is supported, default is on. In case
5970         there is a situation where this behavior is suboptimal, this
5971         attribute provides a way to force the feature off.
5972         <span class="since">Since 0.9.5 (QEMU and KVM only)</span><br/><br/>
5973
5974         <b>In general you should leave this option alone, unless you
5975         are very certain you know what you are doing.</b>
5976       </dd>
5977       <dt><code>queues</code></dt>
5978       <dd>
5979         The optional <code>queues</code> attribute controls the number
5980         of queues to be used for either
5981         <a href="https://www.linux-kvm.org/page/Multiqueue"> Multiqueue
5982         virtio-net</a> or <a href="#elementVhostuser">vhost-user</a> network
5983         interfaces.  Use of multiple packet processing queues requires the
5984         interface having the <code>&lt;model type='virtio'/&gt;</code>
5985         element.  Each queue will potentially be handled by a different
5986         processor, resulting in much higher throughput.
5987         <span class="since">virtio-net since 1.0.6 (QEMU and KVM only)</span>
5988         <span class="since">vhost-user since 1.2.17 (QEMU and KVM only)</span>
5989       </dd>
5990       <dt><code>rx_queue_size</code></dt>
5991       <dd>
5992         The optional <code>rx_queue_size</code> attribute controls
5993         the size of virtio ring for each queue as described above.
5994         The default value is hypervisor dependent and may change
5995         across its releases. Moreover, some hypervisors may pose
5996         some restrictions on actual value. For instance, latest
5997         QEMU (as of 2016-09-01) requires value to be a power of two
5998         from [256, 1024] range.
5999         <span class="since">Since 2.3.0 (QEMU and KVM only)</span><br/><br/>
6000
6001         <b>In general you should leave this option alone, unless you
6002         are very certain you know what you are doing.</b>
6003       </dd>
6004       <dt><code>tx_queue_size</code></dt>
6005       <dd>
6006         The optional <code>tx_queue_size</code> attribute controls
6007         the size of virtio ring for each queue as described above.
6008         The default value is hypervisor dependent and may change
6009         across its releases. Moreover, some hypervisors may pose
6010         some restrictions on actual value. For instance, QEMU
6011         v2.9  requires value to be a power of two from [256, 1024]
6012         range. In addition to that, this may work only for a subset of
6013         interface types, e.g. aforementioned QEMU enables this option
6014         only for <code>vhostuser</code> type.
6015         <span class="since">Since 3.7.0 (QEMU and KVM only)</span><br/><br/>
6016
6017         <b>In general you should leave this option alone, unless you
6018         are very certain you know what you are doing.</b>
6019       </dd>
6020       <dt>virtio options</dt>
6021       <dd>
6022         For virtio interfaces,
6023         <a href="#elementsVirtio">Virtio-specific options</a> can also be
6024         set. (<span class="since">Since 3.5.0</span>)
6025       </dd>
6026     </dl>
6027     <p>
6028       Offloading options for the host and guest can be configured using
6029       the following sub-elements:
6030     </p>
6031     <dl>
6032       <dt><code>host</code></dt>
6033       <dd>
6034         The <code>csum</code>, <code>gso</code>, <code>tso4</code>,
6035         <code>tso6</code>, <code>ecn</code> and <code>ufo</code>
6036         attributes with possible values <code>on</code>
6037         and <code>off</code> can be used to turn off host offloading options.
6038         By default, the supported offloads are enabled by QEMU.
6039         <span class="since">Since 1.2.9 (QEMU only)</span>
6040         The <code>mrg_rxbuf</code> attribute can be used to control
6041         mergeable rx buffers on the host side. Possible values are
6042         <code>on</code> (default) and <code>off</code>.
6043         <span class="since">Since 1.2.13 (QEMU only)</span>
6044       </dd>
6045       <dt><code>guest</code></dt>
6046       <dd>
6047         The <code>csum</code>, <code>tso4</code>,
6048         <code>tso6</code>, <code>ecn</code> and <code>ufo</code>
6049         attributes with possible values <code>on</code>
6050         and <code>off</code> can be used to turn off guest offloading options.
6051         By default, the supported offloads are enabled by QEMU.
6052         <span class="since">Since 1.2.9 (QEMU only)</span>
6053       </dd>
6054     </dl>
6055
6056     <h5><a id="elementsBackendOptions">Setting network backend-specific options</a></h5>
6057
6058 <pre>
6059 ...
6060 &lt;devices&gt;
6061   &lt;interface type='network'&gt;
6062     &lt;source network='default'/&gt;
6063     &lt;target dev='vnet1'/&gt;
6064     &lt;model type='virtio'/&gt;
6065     <b>&lt;backend tap='/dev/net/tun' vhost='/dev/vhost-net'/&gt;</b>
6066     &lt;driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5'/&gt;
6067     <b>&lt;tune&gt;
6068       &lt;sndbuf&gt;1600&lt;/sndbuf&gt;
6069     &lt;/tune&gt;</b>
6070   &lt;/interface&gt;
6071 &lt;/devices&gt;
6072 ...</pre>
6073
6074     <p>
6075       For tuning the backend of the network, the <code>backend</code> element
6076       can be used. The <code>vhost</code> attribute can override the default vhost
6077       device path (<code>/dev/vhost-net</code>) for devices with <code>virtio</code> model.
6078       The <code>tap</code> attribute overrides the tun/tap device path (default:
6079       <code>/dev/net/tun</code>) for network and bridge interfaces. This does not work
6080       in session mode. <span class="since">Since 1.2.9</span>
6081     </p>
6082     <p>
6083       For tap devices there is also <code>sndbuf</code> element which can
6084       adjust the size of send buffer in the host. <span class="since">Since
6085       0.8.8</span>
6086     </p>
6087     <h5><a id="elementsNICSTargetOverride">Overriding the target element</a></h5>
6088
6089 <pre>
6090 ...
6091 &lt;devices&gt;
6092   &lt;interface type='network'&gt;
6093     &lt;source network='default'/&gt;
6094     <b>&lt;target dev='vnet1'/&gt;</b>
6095   &lt;/interface&gt;
6096 &lt;/devices&gt;
6097 ...</pre>
6098
6099     <p>
6100       If no target is specified, certain hypervisors will
6101       automatically generate a name for the created tun device. This
6102       name can be manually specified, however the name <i>should not
6103       start with either 'vnet', 'vif', 'macvtap', or 'macvlan'</i>,
6104       which are prefixes reserved by libvirt and certain hypervisors.
6105       Manually specified targets using these prefixes may be ignored.
6106     </p>
6107
6108     <p>
6109       Note that for LXC containers, this defines the name of the interface
6110       on the host side. <span class="since">Since 1.2.7</span>, to define
6111       the name of the device on the guest side, the <code>guest</code>
6112       element should be used, as in the following snippet:
6113     </p>
6114
6115 <pre>
6116 ...
6117 &lt;devices&gt;
6118   &lt;interface type='network'&gt;
6119     &lt;source network='default'/&gt;
6120     <b>&lt;guest dev='myeth'/&gt;</b>
6121   &lt;/interface&gt;
6122 &lt;/devices&gt;
6123 ...</pre>
6124
6125     <h5><a id="elementsNICSBoot">Specifying boot order</a></h5>
6126
6127 <pre>
6128 ...
6129 &lt;devices&gt;
6130   &lt;interface type='network'&gt;
6131     &lt;source network='default'/&gt;
6132     &lt;target dev='vnet1'/&gt;
6133     <b>&lt;boot order='1'/&gt;</b>
6134   &lt;/interface&gt;
6135 &lt;/devices&gt;
6136 ...</pre>
6137
6138     <p>
6139       For hypervisors which support this, you can set a specific NIC to
6140       be used for network boot. The <code>order</code> attribute determines
6141       the order in which devices will be tried during boot sequence. The
6142       per-device <code>boot</code> elements cannot be used together with
6143       general boot elements in
6144       <a href="#elementsOSBIOS">BIOS bootloader</a> section.
6145       <span class="since">Since 0.8.8</span>
6146     </p>
6147
6148     <h5><a id="elementsNICSROM">Interface ROM BIOS configuration</a></h5>
6149
6150 <pre>
6151 ...
6152 &lt;devices&gt;
6153   &lt;interface type='network'&gt;
6154     &lt;source network='default'/&gt;
6155     &lt;target dev='vnet1'/&gt;
6156     <b>&lt;rom bar='on' file='/etc/fake/boot.bin'/&gt;</b>
6157   &lt;/interface&gt;
6158 &lt;/devices&gt;
6159 ...</pre>
6160
6161     <p>
6162       For hypervisors which support this, you can change how a PCI Network
6163       device's ROM is presented to the guest. The <code>bar</code>
6164       attribute can be set to "on" or "off", and determines whether
6165       or not the device's ROM will be visible in the guest's memory
6166       map. (In PCI documentation, the "rombar" setting controls the
6167       presence of the Base Address Register for the ROM). If no rom
6168       bar is specified, the qemu default will be used (older
6169       versions of qemu used a default of "off", while newer qemus
6170       have a default of "on").
6171       The optional <code>file</code> attribute is used to point to a
6172       binary file to be presented to the guest as the device's ROM
6173       BIOS. This can be useful to provide an alternative boot ROM for a
6174       network device.
6175       <span class="since">Since 0.9.10 (QEMU and KVM only)</span>.
6176     </p>
6177     <h5><a id="elementDomain">Setting up a network backend in a driver domain</a></h5>
6178 <pre>
6179 ...
6180 &lt;devices&gt;
6181   ...
6182   &lt;interface type='bridge'&gt;
6183     &lt;source bridge='br0'/&gt;
6184     <b>&lt;backenddomain name='netvm'/&gt;</b>
6185   &lt;/interface&gt;
6186   ...
6187 &lt;/devices&gt;
6188 ...</pre>
6189
6190     <p>
6191       The optional <code>backenddomain</code> element allows specifying a
6192       backend domain (aka driver domain) for the interface. Use the
6193       <code>name</code> attribute to specify the backend domain name. You
6194       can use it to create a direct network link between domains (so data
6195       will not go through host system). Use with type 'ethernet' to create
6196       plain network link, or with type 'bridge' to connect to a bridge inside
6197       the backend domain.
6198       <span class="since">Since 1.2.13 (Xen only)</span>
6199     </p>
6200
6201     <h5><a id="elementQoS">Quality of service</a></h5>
6202
6203 <pre>
6204 ...
6205 &lt;devices&gt;
6206   &lt;interface type='network'&gt;
6207     &lt;source network='default'/&gt;
6208     &lt;target dev='vnet0'/&gt;
6209     <b>&lt;bandwidth&gt;
6210       &lt;inbound average='1000' peak='5000' floor='200' burst='1024'/&gt;
6211       &lt;outbound average='128' peak='256' burst='256'/&gt;
6212     &lt;/bandwidth&gt;</b>
6213   &lt;/interface&gt;
6214 &lt;/devices&gt;
6215 ...</pre>
6216
6217     <p>
6218       This part of interface XML provides setting quality of service. Incoming
6219       and outgoing traffic can be shaped independently.
6220       The <code>bandwidth</code> element and its child elements are described
6221       in the <a href="formatnetwork.html#elementQoS">QoS</a> section of
6222       the Network XML.
6223     </p>
6224
6225     <h5><a id="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
6226
6227 <pre>
6228 ...
6229 &lt;devices&gt;
6230   &lt;interface type='bridge'&gt;
6231     <b>&lt;vlan&gt;</b>
6232       <b>&lt;tag id='42'/&gt;</b>
6233     <b>&lt;/vlan&gt;</b>
6234     &lt;source bridge='ovsbr0'/&gt;
6235     &lt;virtualport type='openvswitch'&gt;
6236       &lt;parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&gt;
6237     &lt;/virtualport&gt;
6238   &lt;/interface&gt;
6239   &lt;interface type='bridge'&gt;
6240     <b>&lt;vlan trunk='yes'&gt;</b>
6241       <b>&lt;tag id='42'/&gt;</b>
6242       <b>&lt;tag id='123' nativeMode='untagged'/&gt;</b>
6243     <b>&lt;/vlan&gt;</b>
6244     ...
6245   &lt;/interface&gt;
6246 &lt;/devices&gt;
6247 ...</pre>
6248
6249     <p>
6250       If (and only if) the network connection used by the guest
6251       supports VLAN tagging transparent to the guest, an
6252       optional <code>&lt;vlan&gt;</code> element can specify one or
6253       more VLAN tags to apply to the guest's network
6254       traffic <span class="since">Since 0.10.0</span>. Network
6255       connections that support guest-transparent VLAN tagging include
6256       1) type='bridge' interfaces connected to an Open vSwitch bridge
6257       <span class="since">Since 0.10.0</span>, 2) SRIOV Virtual
6258       Functions (VF) used via type='hostdev' (direct device
6259       assignment) <span class="since">Since 0.10.0</span>, and 3)
6260       SRIOV VFs used via type='direct' with mode='passthrough'
6261       (macvtap "passthru" mode) <span class="since">Since
6262       1.3.5</span>. All other connection types, including standard
6263       linux bridges and libvirt's own virtual networks, <b>do not</b>
6264       support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
6265       provide their own way (outside of libvirt) to tag guest traffic
6266       onto a specific VLAN. Each tag is given in a
6267       separate <code>&lt;tag&gt;</code> subelement
6268       of <code>&lt;vlan&gt;</code> (for example: <code>&lt;tag
6269       id='42'/&gt;</code>). For VLAN trunking of multiple tags (which
6270       is supported only on Open vSwitch connections),
6271       multiple <code>&lt;tag&gt;</code> subelements can be specified,
6272       which implies that the user wants to do VLAN trunking on the
6273       interface for all the specified tags. In the case that VLAN
6274       trunking of a single tag is desired, the optional
6275       attribute <code>trunk='yes'</code> can be added to the toplevel
6276       <code>&lt;vlan&gt;</code> element to differentiate trunking of a
6277       single tag from normal tagging.
6278     </p>
6279     <p>
6280       For network connections using Open vSwitch it is also possible
6281       to configure 'native-tagged' and 'native-untagged' VLAN modes
6282       <span class="since">Since 1.1.0.</span> This is done with the
6283       optional <code>nativeMode</code> attribute on
6284       the <code>&lt;tag&gt;</code> subelement: <code>nativeMode</code>
6285       may be set to 'tagged' or 'untagged'. The <code>id</code>
6286       attribute of the <code>&lt;tag&gt;</code> subelement
6287       containing <code>nativeMode</code> sets which VLAN is considered
6288       to be the "native" VLAN for this interface, and
6289       the <code>nativeMode</code> attribute determines whether or not
6290       traffic for that VLAN will be tagged.
6291     </p>
6292
6293     <h5><a id="elementLink">Modifying virtual link state</a></h5>
6294 <pre>
6295 ...
6296 &lt;devices&gt;
6297   &lt;interface type='network'&gt;
6298     &lt;source network='default'/&gt;
6299     &lt;target dev='vnet0'/&gt;
6300     <b>&lt;link state='down'/&gt;</b>
6301   &lt;/interface&gt;
6302 &lt;/devices&gt;
6303 ...</pre>
6304
6305     <p>
6306       This element provides means of setting state of the virtual network link.
6307       Possible values for attribute <code>state</code> are <code>up</code> and
6308       <code>down</code>. If <code>down</code> is specified as the value, the interface
6309       behaves as if it had the network cable disconnected. Default behavior if this
6310       element is unspecified is to have the link state <code>up</code>.
6311       <span class="since">Since 0.9.5</span>
6312     </p>
6313
6314     <h5><a id="mtu">MTU configuration</a></h5>
6315 <pre>
6316 ...
6317 &lt;devices&gt;
6318   &lt;interface type='network'&gt;
6319     &lt;source network='default'/&gt;
6320     &lt;target dev='vnet0'/&gt;
6321     <b>&lt;mtu size='1500'/&gt;</b>
6322   &lt;/interface&gt;
6323 &lt;/devices&gt;
6324 ...</pre>
6325
6326     <p>
6327       This element provides means of setting MTU of the virtual network link.
6328       Currently there is just one attribute <code>size</code> which accepts a
6329       non-negative integer which specifies the MTU size for the interface.
6330       <span class="since">Since 3.1.0</span>
6331     </p>
6332
6333     <h5><a id="coalesce">Coalesce settings</a></h5>
6334 <pre>
6335 ...
6336 &lt;devices&gt;
6337   &lt;interface type='network'&gt;
6338     &lt;source network='default'/&gt;
6339     &lt;target dev='vnet0'/&gt;
6340     <b>&lt;coalesce&gt;
6341       &lt;rx&gt;
6342         &lt;frames max='7'/&gt;
6343       &lt;/rx&gt;
6344     &lt;/coalesce&gt;</b>
6345   &lt;/interface&gt;
6346 &lt;/devices&gt;
6347 ...</pre>
6348
6349     <p>
6350       This element provides means of setting coalesce settings for
6351       some interface devices (currently only type <code>network</code>
6352       and <code>bridge</code>.  Currently there is just one attribute,
6353       <code>max</code>, to tweak, in element <code>frames</code> for
6354       the <code>rx</code> group, which accepts a non-negative integer
6355       that specifies the maximum number of packets that will be
6356       received before an interrupt.
6357       <span class="since">Since 3.3.0</span>
6358     </p>
6359
6360     <h5><a id="ipconfig">IP configuration</a></h5>
6361 <pre>
6362 ...
6363 &lt;devices&gt;
6364   &lt;interface type='network'&gt;
6365     &lt;source network='default'/&gt;
6366     &lt;target dev='vnet0'/&gt;
6367     <b>&lt;ip address='192.168.122.5' prefix='24'/&gt;</b>
6368     <b>&lt;ip address='192.168.122.5' prefix='24' peer='10.0.0.10'/&gt;</b>
6369     <b>&lt;route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/&gt;</b>
6370     <b>&lt;route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/&gt;</b>
6371   &lt;/interface&gt;
6372   ...
6373   &lt;hostdev mode='capabilities' type='net'&gt;
6374     &lt;source&gt;
6375       &lt;interface&gt;eth0&lt;/interface&gt;
6376     &lt;/source&gt;
6377     <b>&lt;ip address='192.168.122.6' prefix='24'/&gt;</b>
6378     <b>&lt;route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/&gt;</b>
6379     <b>&lt;route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/&gt;</b>
6380   &lt;/hostdev&gt;
6381   ...
6382 &lt;/devices&gt;
6383 ...
6384 </pre>
6385
6386     <p>
6387       <span class="since">Since 1.2.12</span> network devices and
6388       hostdev devices with network capabilities can optionally be provided
6389       one or more IP addresses to set on the network device in the
6390       guest. Note that some hypervisors or network device types will
6391       simply ignore them or only use the first one.
6392       The <code>family</code> attribute can be set to
6393       either <code>ipv4</code> or <code>ipv6</code>, and the
6394       <code>address</code> attribute contains the IP address. The
6395       optional <code>prefix</code> is the number of 1 bits in the
6396       netmask, and will be automatically set if not specified - for
6397       IPv4 the default prefix is determined according to the network
6398       "class" (A, B, or C - see RFC870), and for IPv6 the default
6399       prefix is 64. The optional <code>peer</code> attribute holds the
6400       IP address of the other end of a point-to-point network
6401       device <span class="since">(since 2.1.0)</span>.
6402     </p>
6403
6404     <p>
6405     <span class="since">Since 1.2.12</span> route elements can also be
6406     added to define IP routes to add in the guest.  The attributes of
6407     this element are described in the documentation for
6408     the <code>route</code> element
6409     in <a href="formatnetwork.html#elementsStaticroute">network
6410     definitions</a>.  This is used by the LXC driver.
6411     </p>
6412
6413 <pre>
6414 ...
6415 &lt;devices&gt;
6416   &lt;interface type='ethernet'&gt;
6417     <b>&lt;source/&gt;</b>
6418       <b>&lt;ip address='192.168.123.1' prefix='24'/&gt;</b>
6419       <b>&lt;ip address='10.0.0.10' prefix='24' peer='192.168.122.5'/&gt;</b>
6420       <b>&lt;route family='ipv4' address='192.168.42.0' prefix='24' gateway='192.168.123.4'/&gt;</b>
6421     <b>&lt;source/&gt;</b>
6422     ...
6423   &lt;/interface&gt;
6424   ...
6425 &lt;/devices&gt;
6426 ...
6427 </pre>
6428
6429     <p>
6430       <span class="since">Since 2.1.0</span> network devices of type
6431       "ethernet" can optionally be provided one or more IP addresses
6432       and one or more routes to set on the <b>host</b> side of the
6433       network device. These are configured as subelements of
6434       the <code>&lt;source&gt;</code> element of the interface, and
6435       have the same attributes as the similarly named elements used to
6436       configure the guest side of the interface (described above).
6437     </p>
6438
6439     <h5><a id="elementVhostuser">vhost-user interface</a></h5>
6440
6441     <p>
6442     <span class="since">Since 1.2.7</span> the vhost-user enables the
6443     communication between a QEMU virtual machine and other userspace process
6444     using the Virtio transport protocol.  A char dev (e.g. Unix socket) is used
6445     for the control plane, while the data plane is based on shared memory.
6446     </p>
6447
6448 <pre>
6449 ...
6450 &lt;devices&gt;
6451   &lt;interface type='vhostuser'&gt;
6452     &lt;mac address='52:54:00:3b:83:1a'/&gt;
6453     &lt;source type='unix' path='/tmp/vhost1.sock' mode='server'/&gt;
6454     &lt;model type='virtio'/&gt;
6455   &lt;/interface&gt;
6456   &lt;interface type='vhostuser'&gt;
6457     &lt;mac address='52:54:00:3b:83:1b'/&gt;
6458     &lt;source type='unix' path='/tmp/vhost2.sock' mode='client'&gt;
6459       &lt;reconnect enabled='yes' timeout='10'/&gt;
6460     &lt;/source&gt;
6461     &lt;model type='virtio'/&gt;
6462     &lt;driver queues='5'/&gt;
6463   &lt;/interface&gt;
6464 &lt;/devices&gt;
6465 ...</pre>
6466
6467     <p>
6468       The <code>&lt;source&gt;</code> element has to be specified
6469       along with the type of char device.
6470       Currently, only type='unix' is supported, where the path (the
6471       directory path of the socket) and mode attributes are required.
6472       Both <code>mode='server'</code> and <code>mode='client'</code>
6473       are supported.
6474       vhost-user requires the virtio model type, thus the
6475       <code>&lt;model&gt;</code> element is mandatory.
6476       <span class="since">Since 4.1.0</span> the element has an
6477       optional child element <code>reconnect</code> which
6478       configures reconnect timeout if the connection is lost. It
6479       has two attributes <code>enabled</code> (which accepts
6480       <code>yes</code> and <code>no</code>) and
6481       <code>timeout</code> which specifies the amount of seconds
6482       after which hypervisor tries to reconnect.
6483     </p>
6484
6485     <h5><a id="elementNwfilter">Traffic filtering with NWFilter</a></h5>
6486
6487     <p>
6488     <span class="since">Since 0.8.0</span> an <code>nwfilter</code> profile
6489     can be assigned to a domain interface, which allows configuring
6490     traffic filter rules for the virtual machine.
6491
6492     See the <a href="formatnwfilter.html">nwfilter</a> documentation for more
6493     complete details.
6494     </p>
6495
6496 <pre>
6497 ...
6498 &lt;devices&gt;
6499   &lt;interface ...&gt;
6500     ...
6501     &lt;filterref filter='clean-traffic'/&gt;
6502   &lt;/interface&gt;
6503   &lt;interface ...&gt;
6504     ...
6505     &lt;filterref filter='myfilter'&gt;
6506       &lt;parameter name='IP' value='104.207.129.11'/&gt;
6507       &lt;parameter name='IP6_ADDR' value='2001:19f0:300:2102::'/&gt;
6508       &lt;parameter name='IP6_MASK' value='64'/&gt;
6509       ...
6510     &lt;/filterref&gt;
6511   &lt;/interface&gt;
6512 &lt;/devices&gt;
6513 ...</pre>
6514
6515     <p>
6516       The <code>filter</code> attribute specifies the name of the nwfilter
6517       to use. Optional <code>&lt;parameter&gt;</code> elements may be
6518       specified for passing additional info to the nwfilter via the
6519       <code>name</code> and <code>value</code> attributes. See
6520       the <a href="formatnwfilter.html#nwfconceptsvars">nwfilter</a>
6521       docs for info on parameters.
6522     </p>
6523
6524
6525     <h4><a id="elementsInput">Input devices</a></h4>
6526
6527     <p>
6528       Input devices allow interaction with the graphical framebuffer
6529       in the guest virtual machine. When enabling the framebuffer, an
6530       input device is automatically provided. It may be possible to
6531       add additional devices explicitly, for example,
6532       to provide a graphics tablet for absolute cursor movement.
6533     </p>
6534
6535 <pre>
6536 ...
6537 &lt;devices&gt;
6538   &lt;input type='mouse' bus='usb'/&gt;
6539   &lt;input type='keyboard' bus='usb'/&gt;
6540   &lt;input type='mouse' bus='virtio'/&gt;
6541   &lt;input type='keyboard' bus='virtio'/&gt;
6542   &lt;input type='tablet' bus='virtio'/&gt;
6543   &lt;input type='passthrough' bus='virtio'&gt;
6544     &lt;source evdev='/dev/input/event1/&gt;
6545   &lt;/input&gt;
6546 &lt;/devices&gt;
6547 ...</pre>
6548
6549     <dl>
6550       <dt><code>input</code></dt>
6551       <dd>The <code>input</code> element has one mandatory attribute,
6552         the <code>type</code> whose value can be 'mouse', 'tablet',
6553         (<span class="since">since 1.2.2</span>) 'keyboard' or
6554         (<span class="since">since 1.3.0</span>) 'passthrough'.
6555         The tablet provides absolute cursor movement,
6556         while the mouse uses relative movement. The optional
6557         <code>bus</code> attribute can be used to refine the exact device type.
6558         It takes values "xen" (paravirtualized), "ps2" and "usb" or
6559         (<span class="since">since 1.3.0</span>) "virtio".</dd>
6560     </dl>
6561
6562     <p>
6563       The <code>input</code> element has an optional
6564       sub-element <code>&lt;address&gt;</code> which can tie the
6565       device to a particular PCI
6566       slot, <a href="#elementsAddress">documented above</a>.
6567       On S390, <code>address</code> can be used to provide a CCW address for
6568       an input device (<span class="since">since 4.2.0</span>).
6569
6570       For type <code>passthrough</code>, the mandatory sub-element <code>source</code>
6571       must have an <code>evdev</code> attribute containing the absolute path to the
6572       event device passed through to guests. (KVM only)
6573
6574       <span class="since">Since 5.2.0</span>, the <code>input</code> element
6575       accepts a <code>model</code> attribute which has the values 'virtio',
6576       'virtio-transitional' and 'virtio-non-transitional'. See
6577       <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
6578       for more details.
6579     </p>
6580
6581     <p>
6582         The subelement <code>driver</code> can be used to tune the virtio
6583         options of the device:
6584         <a href="#elementsVirtio">Virtio-specific options</a> can also be
6585         set. (<span class="since">Since 3.5.0</span>)
6586     </p>
6587
6588     <h4><a id="elementsHub">Hub devices</a></h4>
6589
6590     <p>
6591       A hub is a device that expands a single port into several so
6592       that there are more ports available to connect devices to a host
6593       system.
6594     </p>
6595
6596 <pre>
6597 ...
6598 &lt;devices&gt;
6599   &lt;hub type='usb'/&gt;
6600 &lt;/devices&gt;
6601 ...</pre>
6602
6603     <dl>
6604       <dt><code>hub</code></dt>
6605       <dd>The <code>hub</code> element has one mandatory attribute,
6606         the <code>type</code> whose value can only be 'usb'.</dd>
6607     </dl>
6608
6609     <p>
6610       The <code>hub</code> element has an optional
6611       sub-element <code>&lt;address&gt;</code>
6612       with <code>type='usb'</code>which can tie the device to a
6613       particular controller, <a href="#elementsAddress">documented
6614       above</a>.
6615     </p>
6616
6617     <h4><a id="elementsGraphics">Graphical framebuffers</a></h4>
6618
6619     <p>
6620       A graphics device allows for graphical interaction with the
6621       guest OS. A guest will typically have either a framebuffer
6622       or a text console configured to allow interaction with the
6623       admin.
6624     </p>
6625
6626 <pre>
6627 ...
6628 &lt;devices&gt;
6629   &lt;graphics type='sdl' display=':0.0'/&gt;
6630   &lt;graphics type='vnc' port='5904' sharePolicy='allow-exclusive'&gt;
6631     &lt;listen type='address' address='1.2.3.4'/&gt;
6632   &lt;/graphics&gt;
6633   &lt;graphics type='rdp' autoport='yes' multiUser='yes' /&gt;
6634   &lt;graphics type='desktop' fullscreen='yes'/&gt;
6635   &lt;graphics type='spice'&gt;
6636     &lt;listen type='network' network='rednet'/&gt;
6637   &lt;/graphics&gt;
6638 &lt;/devices&gt;
6639 ...</pre>
6640
6641     <dl>
6642       <dt><code>graphics</code></dt>
6643       <dd>
6644         <p>
6645           The <code>graphics</code> element has a mandatory <code>type</code>
6646           attribute which takes the value <code>sdl</code>, <code>vnc</code>,
6647           <code>spice</code>, <code>rdp</code>, <code>desktop</code> or
6648           <code>egl-headless</code>:
6649         </p>
6650         <dl>
6651           <dt><code>sdl</code></dt>
6652           <dd>
6653             <p>
6654               This displays a window on the host desktop, it can take 3 optional
6655               arguments: a <code>display</code> attribute for the display to use,
6656               an <code>xauth</code> attribute for the authentication identifier,
6657               and an optional <code>fullscreen</code> attribute accepting values
6658               <code>yes</code> or <code>no</code>.
6659             </p>
6660
6661             <p>
6662               You can use a <code>gl</code> with the <code>enable="yes"</code>
6663               property to enable OpenGL support in SDL. Likewise you can
6664               explicitly disable OpenGL support with <code>enable="no"</code>.
6665             </p>
6666           </dd>
6667           <dt><code>vnc</code></dt>
6668           <dd>
6669             <p>
6670               Starts a VNC server. The <code>port</code> attribute specifies
6671               the TCP port number (with -1 as legacy syntax indicating that it
6672               should be auto-allocated). The <code>autoport</code> attribute is
6673               the new preferred syntax for indicating auto-allocation of the TCP
6674               port to use. The <code>passwd</code> attribute provides a VNC
6675               password in clear text. If the <code>passwd</code> attribute is
6676               set to an empty string, then VNC access is disabled. The
6677               <code>keymap</code> attribute specifies the keymap to use. It is
6678               possible to set a limit on the validity of the password by giving
6679               a timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
6680               assumed to be in UTC. The <code>connected</code> attribute allows
6681               control of connected client during password changes. VNC accepts
6682               <code>keep</code> value only <span class="since">since 0.9.3</span>.
6683               NB, this may not be supported by all hypervisors.
6684             </p>
6685             <p>
6686               The optional <code>sharePolicy</code> attribute specifies vnc
6687               server display sharing policy. <code>allow-exclusive</code> allows
6688               clients to ask for exclusive access by dropping other connections.
6689               Connecting multiple clients in parallel requires all clients asking
6690               for a shared session (vncviewer: -Shared switch). This is
6691               the default value. <code>force-shared</code> disables exclusive
6692               client access, every connection has to specify -Shared switch for
6693               vncviewer. <code>ignore</code> welcomes every connection
6694               unconditionally <span class="since">since 1.0.6</span>.
6695             </p>
6696             <p>
6697               Rather than using listen/port, QEMU supports a <code>socket</code>
6698               attribute for listening on a unix domain socket path
6699               <span class="since">Since 0.8.8</span>.
6700             </p>
6701             <p>
6702               For VNC WebSocket functionality, <code>websocket</code> attribute
6703               may be used to specify port to listen on (with -1 meaning
6704               auto-allocation and <code>autoport</code> having no effect due to
6705               security reasons) <span class="since">Since 1.0.6</span>.
6706             </p>
6707             <p>
6708               Although VNC doesn't support OpenGL natively, it can be paired
6709               with graphics type <code>egl-headless</code> (see below) which
6710               will instruct QEMU to open and use drm nodes for OpenGL rendering.
6711             </p>
6712           </dd>
6713           <dt><code>spice</code> <span class="since">Since 0.8.6</span></dt>
6714           <dd>
6715             <p>
6716               Starts a SPICE server. The <code>port</code> attribute specifies
6717               the TCP port number (with -1 as legacy syntax indicating that it
6718               should be auto-allocated), while <code>tlsPort</code> gives
6719               an alternative secure port number. The <code>autoport</code>
6720               attribute is the new preferred syntax for indicating
6721               auto-allocation of needed port numbers. The <code>passwd</code>
6722               attribute provides a SPICE password in clear text. If the
6723               <code>passwd</code> attribute is set to an empty string, then
6724               SPICE access is disabled. The <code>keymap</code> attribute
6725               specifies the keymap to use. It is possible to set a limit on
6726               the validity of the password by giving a timestamp
6727               <code>passwdValidTo='2010-04-09T15:51:00'</code> assumed to be
6728               in UTC.
6729             </p>
6730             <p>
6731               The <code>connected</code> attribute allows control of connected
6732               client during password changes. SPICE accepts <code>keep</code> to
6733               keep client connected, <code>disconnect</code> to disconnect client
6734               and <code>fail</code> to fail changing password . NB, this may not
6735               be supported by all hypervisors.
6736               <span class="since">Since 0.9.3</span>
6737             </p>
6738             <p>
6739               The <code>defaultMode</code> attribute sets the default channel
6740               security policy, valid values are <code>secure</code>,
6741               <code>insecure</code> and the default <code>any</code> (which is
6742               secure if possible, but falls back to insecure rather than erroring
6743               out if no secure path is available).
6744               <span class="since">Since 0.9.12</span>
6745             </p>
6746             <p>
6747               When SPICE has both a normal and TLS secured TCP port configured,
6748               it can be desirable to restrict what channels can be run on each
6749               port. This is achieved by adding one or more <code>&lt;channel&gt;
6750               </code> elements inside the main <code>&lt;graphics&gt;</code>
6751               element and setting the <code>mode</code> attribute to either
6752               <code>secure</code> or <code>insecure</code>. Setting the mode
6753               attribute overrides the default value as set by
6754               the <code>defaultMode</code> attribute. (Note that specifying
6755               <code>any</code> as mode discards the entry as the channel would
6756               inherit the default mode anyways.) Valid channel names include
6757               <code>main</code>, <code>display</code>, <code>inputs</code>,
6758               <code>cursor</code>, <code>playback</code>, <code>record</code>
6759               (all <span class="since"> since 0.8.6</span>);
6760               <code>smartcard</code> (<span class="since">since 0.8.8</span>);
6761               and <code>usbredir</code> (<span class="since">since 0.9.12</span>).
6762             </p>
6763             <pre>
6764 &lt;graphics type='spice' port='-1' tlsPort='-1' autoport='yes'&gt;
6765   &lt;channel name='main' mode='secure'/&gt;
6766   &lt;channel name='record' mode='insecure'/&gt;
6767   &lt;image compression='auto_glz'/&gt;
6768   &lt;streaming mode='filter'/&gt;
6769   &lt;clipboard copypaste='no'/&gt;
6770   &lt;mouse mode='client'/&gt;
6771   &lt;filetransfer enable='no'/&gt;
6772   &lt;gl enable='yes' rendernode='/dev/dri/by-path/pci-0000:00:02.0-render'/&gt;
6773 &lt;/graphics&gt;</pre>
6774             <p>
6775               Spice supports variable compression settings for audio, images and
6776               streaming. These settings are accessible via the <code>compression
6777               </code> attribute in all following elements: <code>image</code> to
6778               set image compression (accepts <code>auto_glz</code>,
6779               <code>auto_lz</code>, <code>quic</code>, <code>glz</code>,
6780               <code>lz</code>, <code>off</code>), <code>jpeg</code> for JPEG
6781               compression for images over wan (accepts <code>auto</code>,
6782               <code>never</code>, <code>always</code>), <code>zlib</code> for
6783               configuring wan image compression (accepts <code>auto</code>,
6784               <code>never</code>, <code>always</code>)  and <code>playback</code>
6785               for enabling audio stream compression (accepts <code>on</code> or
6786               <code>off</code>). <span class="since">Since 0.9.1</span>
6787             </p>
6788             <p>
6789               Streaming mode is set by the <code>streaming</code> element,
6790               settings its <code>mode</code> attribute to one of
6791               <code>filter</code>, <code>all</code> or <code>off</code>.
6792               <span class="since">Since 0.9.2</span>
6793             </p>
6794             <p>
6795               Copy &amp; Paste functionality (via Spice agent) is set by the
6796               <code>clipboard</code> element. It is enabled by default, and can
6797               be disabled by setting the <code>copypaste</code> property to
6798               <code>no</code>. <span class="since">Since 0.9.3</span>
6799             </p>
6800             <p>
6801               Mouse mode is set by the <code>mouse</code> element, setting its
6802               <code>mode</code> attribute to one of <code>server</code> or
6803               <code>client</code>. If no mode is specified, the qemu default will
6804               be used (client mode). <span class="since">Since 0.9.11</span>
6805             </p>
6806             <p>
6807               File transfer functionality (via Spice agent) is set using the
6808               <code>filetransfer</code> element. It is enabled by default, and
6809               can be disabled by setting the <code>enable</code> property to
6810               <code>no</code>. <span class="since">Since 1.2.2</span>
6811             </p>
6812             <p>
6813               Spice may provide accelerated server-side rendering with OpenGL.
6814               You can enable or disable OpenGL support explicitly with
6815               the <code>gl</code> element, by setting the <code>enable</code>
6816               property. (QEMU only, <span class="since">since 1.3.3</span>).
6817               Note that this only works locally, since this requires usage of
6818               UNIX sockets, i.e. using <code>listen</code> types 'socket' or
6819               'none'. For accelerated OpenGL with remote support, consider
6820               pairing this element with type <code>egl-headless</code>
6821               (see below). However, this will deliver weaker performance
6822               compared to native Spice OpenGL support.
6823             </p>
6824             <p>
6825               By default, QEMU will pick the first available GPU DRM render node.
6826               You may specify a DRM render node path to use instead. (QEMU only,
6827               <span class="since">since 3.1.0</span>).
6828             </p>
6829           </dd>
6830           <dt><code>rdp</code></dt>
6831           <dd>
6832             <p>
6833               Starts a RDP server. The <code>port</code> attribute specifies the
6834               TCP port number (with -1 as legacy syntax indicating that it should
6835               be auto-allocated). The <code>autoport</code> attribute is the new
6836               preferred syntax for indicating auto-allocation of the TCP port to
6837               use. In the VirtualBox driver, the <code>autoport</code> will make
6838               the hypervisor pick available port from 3389-3689 range when the VM
6839               is started. The chosen port will be reflected in the <code>port</code>
6840               attribute. The <code>multiUser</code> attribute is a boolean deciding
6841               whether multiple simultaneous connections to the VM are permitted.
6842               The <code>replaceUser</code> attribute is a boolean deciding whether
6843               the existing connection must be dropped and a new connection must
6844               be established by the VRDP server, when a new client connects in
6845               single connection mode.
6846             </p>
6847           </dd>
6848           <dt><code>desktop</code></dt>
6849           <dd>
6850             <p>
6851               This value is reserved for VirtualBox domains for the moment. It
6852               displays a window on the host desktop, similarly to "sdl", but
6853               using the VirtualBox viewer. Just like "sdl", it accepts
6854               the optional attributes <code>display</code> and
6855               <code>fullscreen</code>.
6856             </p>
6857           </dd>
6858           <dt><code>egl-headless</code><span class="since">Since 4.6.0</span></dt>
6859           <dd>
6860             <p>
6861               This display type provides support for an OpenGL accelerated
6862               display accessible both locally and remotely (for comparison,
6863               Spice's native OpenGL support only works locally using UNIX
6864               sockets at the moment, but has better performance). Since this
6865               display type doesn't provide any window or graphical console like
6866               the other types, for practical reasons it should be paired with
6867               either <code>vnc</code> or <code>spice</code> graphics types.
6868               This display type is only supported by QEMU domains
6869               (needs QEMU <span class="since">2.10</span> or newer).
6870               <span class="Since">5.0.0</span> this element accepts a
6871               <code>&lt;gl/&gt;</code> sub-element with an optional attribute
6872               <code>rendernode</code> which can be used to specify an absolute
6873               path to a host's DRI device to be used for OpenGL rendering.
6874             </p>
6875             <pre>
6876 &lt;graphics type='spice' autoport='yes'/&gt;
6877 &lt;graphics type='egl-headless'&gt;
6878   &lt;gl rendernode='/dev/dri/renderD128'/&gt;
6879 &lt;/graphics&gt;
6880             </pre>
6881           </dd>
6882         </dl>
6883       </dd>
6884     </dl>
6885
6886     <p>
6887       Graphics device uses a <code>&lt;listen&gt;</code> to set up where
6888       the device should listen for clients. It has a mandatory attribute
6889       <code>type</code> which specifies the listen type. Only <code>vnc</code>,
6890       <code>spice</code> and <code>rdp</code> supports <code>&lt;listen&gt;
6891       </code> element. <span class="since">Since 0.9.4</span>.
6892       Available types are:
6893     </p>
6894     <dl>
6895       <dt><code>address</code></dt>
6896       <dd>
6897         <p>
6898           Tells a graphics device to use an address specified in the
6899           <code>address</code> attribute, which will contain either an IP address
6900           or hostname (which will be resolved to an IP address via a DNS query)
6901           to listen on.
6902         </p>
6903         <p>
6904           It is possible to omit the <code>address</code> attribute in order to
6905           use an address from config files <span class="since">Since 1.3.5</span>.
6906         </p>
6907         <p>
6908           The <code>address</code> attribute is duplicated as <code>listen</code>
6909           attribute in <code>graphics</code> element for backward compatibility.
6910           If both are provided they must be equal.
6911         </p>
6912       </dd>
6913       <dt><code>network</code></dt>
6914       <dd>
6915         <p>
6916           This is used to specify an existing network in the <code>network</code>
6917           attribute from libvirt's list of configured networks. The named network
6918           configuration will be examined to determine an appropriate listen
6919           address and the address will be stored in live XML in <code>address
6920           </code> attribute. For example, if the network has an IPv4 address in
6921           its configuration (e.g. if it has a forward type of <code>route</code>,
6922           <code>nat</code>, or no forward type (isolated)), the first IPv4
6923           address listed in the network's configuration will be used.
6924           If the network is describing a host bridge, the first IPv4 address
6925           associated with that bridge device will be used, and if the network is
6926           describing one of the 'direct' (macvtap) modes, the first IPv4 address
6927           of the first forward dev will be used.
6928         </p>
6929       </dd>
6930       <dt><code>socket</code> <span class="since">since 2.0.0 (QEMU only)</span></dt>
6931       <dd>
6932         <p>
6933           This listen type tells a graphics server to listen on unix socket.
6934           Attribute <code>socket</code> contains a path to unix socket. If this
6935           attribute is omitted libvirt will generate this path for you.
6936           Supported by graphics type <code>vnc</code> and <code>spice</code>.
6937         </p>
6938         <p>
6939           For <code>vnc</code> graphics be backward compatible
6940           the <code>socket</code> attribute of first <code>listen</code> element
6941           is duplicated as <code>socket</code> attribute in <code>graphics</code>
6942           element. If <code>graphics</code> element contains a <code>socket</code>
6943           attribute all <code>listen</code> elements are ignored.
6944         </p>
6945       </dd>
6946       <dt><code>none</code> <span class="since">since 2.0.0 (QEMU only)</span></dt>
6947       <dd>
6948         <p>
6949           This listen type doesn't have any other attribute. Libvirt supports
6950           passing a file descriptor through our APIs virDomainOpenGraphics() and
6951           virDomainOpenGraphicsFD(). No other listen types are allowed if this
6952           one is used and the graphics device doesn't listen anywhere. You need
6953           to use one of the two APIs to pass a FD to QEMU in order to connect to
6954           this graphics device. Supported by graphics type <code>vnc</code> and
6955           <code>spice</code>.
6956         </p>
6957       </dd>
6958     </dl>
6959
6960     <h4><a id="elementsVideo">Video devices</a></h4>
6961     <p>
6962       A video device.
6963     </p>
6964
6965 <pre>
6966 ...
6967 &lt;devices&gt;
6968   &lt;video&gt;
6969     &lt;model type='vga' vram='16384' heads='1'&gt;
6970       &lt;acceleration accel3d='yes' accel2d='yes'/&gt;
6971     &lt;/model&gt;
6972   &lt;/video&gt;
6973 &lt;/devices&gt;
6974 ...</pre>
6975
6976     <dl>
6977       <dt><code>video</code></dt>
6978       <dd>
6979         <p>
6980           The <code>video</code> element is the container for describing
6981           video devices. For backwards compatibility, if no <code>video</code>
6982           is set but there is a <code>graphics</code> in domain xml, then
6983           libvirt will add a default <code>video</code> according to the guest
6984           type.
6985         </p>
6986         <p>
6987           For a guest of type "kvm", the default <code>video</code> is:
6988           <code>type</code> with value "cirrus", <code>vram</code> with value
6989           "16384" and <code>heads</code> with value "1". By default, the first
6990           video device in domain xml is the primary one, but the optional
6991           attribute <code>primary</code> (<span class="since">since 1.0.2</span>)
6992           with value 'yes' can be used to mark the primary in cases of multiple
6993           video device. The non-primary must be type of "qxl" or
6994           (<span class="since">since 2.4.0</span>) "virtio".
6995         </p>
6996       </dd>
6997
6998       <dt><code>model</code></dt>
6999       <dd>
7000         <p>
7001           The <code>model</code> element has a mandatory <code>type</code>
7002           attribute which takes the value "vga", "cirrus", "vmvga", "xen",
7003           "vbox", "qxl" (<span class="since">since 0.8.6</span>),
7004           "virtio" (<span class="since">since 1.3.0</span>),
7005           "gop" (<span class="since">since 3.2.0</span>),
7006           "none" (<span class="since">since 4.6.0</span>, or "bochs"
7007           (<span class="since">since 5.6.0</span>)
7008           depending on the hypervisor features available.
7009           The purpose of the type <code>none</code> is to instruct libvirt not
7010           to add a default video device in the guest (see the paragraph above).
7011           This legacy behaviour can be inconvenient in cases where GPU mediated
7012           devices are meant to be the only rendering device within a guest and
7013           so specifying another <code>video</code> device along with type
7014           <code>none</code>.
7015           Refer to <a id="elementsHostDev">Host device assignment</a> to see
7016           how to add a mediated device into a guest.
7017         </p>
7018         <p>
7019           You can provide the amount of video memory in kibibytes (blocks of
7020           1024 bytes) using <code>vram</code>. This is supported only for guest
7021           type of "libxl", "vz", "qemu", "vbox", "vmx" and "xen". If no
7022           value is provided the default is used. If the size is not a power of
7023           two it will be rounded to closest one.
7024         </p>
7025         <p>
7026           The number of screen can be set using <code>heads</code>. This is
7027           supported only for guests type of "vz", "kvm", "vbox" and "vmx".
7028         </p>
7029         <p>
7030           For guest type of "kvm" or "qemu" and model type "qxl" there are
7031           optional attributes. Attribute <code>ram</code> (<span class="since">
7032           since 1.0.2</span>) specifies the size of the primary bar, while the
7033           attribute <code>vram</code> specifies the secondary bar size.
7034           If <code>ram</code> or <code>vram</code> are not supplied a default
7035           value is used. The <code>ram</code> should also be rounded to power of
7036           two as <code>vram</code>. There is also optional attribute
7037           <code>vgamem</code> (<span class="since">since 1.2.11</span>) to set
7038           the size of VGA framebuffer for fallback mode of QXL device.
7039           Attribute <code>vram64</code> (<span class="since">since 1.3.3</span>)
7040           extends secondary bar and makes it addressable as 64bit memory.
7041         </p>
7042       </dd>
7043
7044       <dt><code>acceleration</code></dt>
7045       <dd>
7046         Configure if video acceleration should be enabled.
7047         <dl>
7048         <dt><code>accel2d</code></dt>
7049         <dd>Enable 2D acceleration (for vbox driver only,
7050         <span class="since">since 0.7.1</span>)</dd>
7051
7052         <dt><code>accel3d</code></dt>
7053         <dd>Enable 3D acceleration (for vbox driver
7054         <span class="since">since 0.7.1</span>, qemu driver
7055         <span class="since">since 1.3.0</span>)</dd>
7056         </dl>
7057       </dd>
7058
7059       <dt><code>address</code></dt>
7060       <dd>
7061         The optional <code>address</code> sub-element can be used to
7062         tie the video device to a particular PCI slot.
7063         On S390, <code>address</code> can be used to provide the
7064         CCW address for the video device (<span class="since">
7065         since 4.2.0</span>).
7066       </dd>
7067
7068       <dt><code>driver</code></dt>
7069       <dd>
7070         The subelement <code>driver</code> can be used to tune the device:
7071         <dl>
7072           <dt>virtio options</dt>
7073           <dd>
7074           <a href="#elementsVirtio">Virtio-specific options</a> can also be
7075           set (<span class="since">Since 3.5.0</span>)
7076           </dd>
7077           <dt>VGA configuration</dt>
7078           <dd>
7079           Control how the video devices exposed to the guest using the
7080           <code>vgaconf</code> attribute which takes the value "io", "on" or "off".
7081           At present, it's only applicable to the bhyve's "gop" video model type
7082           (<span class="since">Since 3.5.0</span>)
7083           </dd>
7084         </dl>
7085       </dd>
7086     </dl>
7087
7088     <h4><a id="elementsConsole">Consoles, serial, parallel &amp; channel devices</a></h4>
7089
7090     <p>
7091       A character device provides a way to interact with the virtual machine.
7092       Paravirtualized consoles, serial ports, parallel ports and channels are
7093       all classed as character devices and so represented using the same syntax.
7094     </p>
7095
7096 <pre>
7097 ...
7098 &lt;devices&gt;
7099   &lt;parallel type='pty'&gt;
7100     &lt;source path='/dev/pts/2'/&gt;
7101     &lt;target port='0'/&gt;
7102   &lt;/parallel&gt;
7103   &lt;serial type='pty'&gt;
7104     &lt;source path='/dev/pts/3'/&gt;
7105     &lt;target port='0'/&gt;
7106   &lt;/serial&gt;
7107   &lt;serial type='file'&gt;
7108     &lt;source path='/tmp/file' append='on'&gt;
7109       &lt;seclabel model='dac' relabel='no'/&gt;
7110     &lt;/source&gt;
7111     &lt;target port='0'/&gt;
7112   &lt;/serial&gt;
7113   &lt;console type='pty'&gt;
7114     &lt;source path='/dev/pts/4'/&gt;
7115     &lt;target port='0'/&gt;
7116   &lt;/console&gt;
7117   &lt;channel type='unix'&gt;
7118     &lt;source mode='bind' path='/tmp/guestfwd'/&gt;
7119     &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
7120   &lt;/channel&gt;
7121 &lt;/devices&gt;
7122 ...</pre>
7123
7124     <p>
7125       In each of these directives, the top-level element name (parallel, serial,
7126       console, channel) describes how the device is presented to the guest. The
7127       guest interface is configured by the <code>target</code> element.
7128     </p>
7129
7130     <p>
7131       The interface presented to the host is given in the <code>type</code>
7132       attribute of the top-level element. The host interface is
7133       configured by the <code>source</code> element.
7134     </p>
7135
7136     <p>
7137       The <code>source</code> element may contain an optional
7138       <code>seclabel</code> to override the way that labelling
7139       is done on the socket path.  If this element is not present,
7140       the <a href="#seclabel">security label is inherited from
7141         the per-domain setting</a>.
7142     </p>
7143
7144     <p>
7145       If the interface <code>type</code> presented to the host is "file",
7146       then the <code>source</code> element may contain an optional attribute
7147       <code>append</code> that specifies whether or not the information in
7148       the file should be preserved on domain restart. Allowed values are
7149       "on" and "off" (default). <span class="since">Since 1.3.1</span>.
7150     </p>
7151
7152     <p>
7153       Regardless of the <code>type</code>, character devices can
7154       have an optional log file associated with them. This is
7155       expressed via a <code>log</code> sub-element, with a
7156       <code>file</code> attribute. There can also be an <code>append</code>
7157       attribute which takes the same values described above.
7158       <span class="since">Since 1.3.3</span>.
7159     </p>
7160
7161     <pre>
7162 ...
7163 &lt;log file="/var/log/libvirt/qemu/guestname-serial0.log" append="off"/&gt;
7164 ...</pre>
7165
7166     <p>
7167       Each character device element has an optional
7168       sub-element <code>&lt;address&gt;</code> which can tie the
7169       device to a
7170       particular <a href="#elementsControllers">controller</a> or PCI
7171       slot.
7172     </p>
7173
7174     <p>
7175       For character device with type <code>unix</code> or <code>tcp</code>
7176       the <code>source</code> has an optional element <code>reconnect</code>
7177       which configures reconnect timeout if the connection is lost.
7178       There are two attributes, <code>enabled</code> where possible
7179       values are "yes" and "no" and <code>timeout</code> which is in
7180       seconds. The <code>reconnect</code> attribute is valid only
7181       for <code>connect</code> mode.
7182       <span class="since">Since 3.7.0 (QEMU driver only)</span>.
7183     </p>
7184
7185     <h5><a id="elementsCharGuestInterface">Guest interface</a></h5>
7186
7187     <p>
7188       A character device presents itself to the guest as one of the following
7189       types.
7190     </p>
7191
7192     <h6><a id="elementCharParallel">Parallel port</a></h6>
7193
7194 <pre>
7195 ...
7196 &lt;devices&gt;
7197   &lt;parallel type='pty'&gt;
7198     &lt;source path='/dev/pts/2'/&gt;
7199     &lt;target port='0'/&gt;
7200   &lt;/parallel&gt;
7201 &lt;/devices&gt;
7202 ...</pre>
7203
7204     <p>
7205       <code>target</code> can have a <code>port</code> attribute, which
7206       specifies the port number. Ports are numbered starting from 0. There are
7207       usually 0, 1 or 2 parallel ports.
7208     </p>
7209
7210     <h6><a id="elementCharSerial">Serial port</a></h6>
7211
7212 <pre>
7213 ...
7214 &lt;devices&gt;
7215   &lt;!-- Serial port --&gt;
7216   &lt;serial type='pty'&gt;
7217     &lt;source path='/dev/pts/3'/&gt;
7218     &lt;target port='0'/&gt;
7219   &lt;/serial&gt;
7220 &lt;/devices&gt;
7221 ...</pre>
7222
7223 <pre>
7224 ...
7225 &lt;devices&gt;
7226   &lt;!-- USB serial port --&gt;
7227   &lt;serial type='pty'&gt;
7228     &lt;target type='usb-serial' port='0'&gt;
7229       &lt;model name='usb-serial'/&gt;
7230     &lt;/target&gt;
7231     &lt;address type='usb' bus='0' port='1'/&gt;
7232   &lt;/serial&gt;
7233 &lt;/devices&gt;
7234 ...</pre>
7235
7236     <p>
7237       The <code>target</code> element can have an optional <code>port</code>
7238       attribute, which specifies the port number (starting from 0), and an
7239       optional <code>type</code> attribute: valid values are,
7240       <span class="since">since 1.0.2</span>, <code>isa-serial</code> (usable
7241       with x86 guests), <code>usb-serial</code> (usable whenever USB support
7242       is available) and <code>pci-serial</code> (usable whenever PCI support
7243       is available); <span class="since">since 3.10.0</span>,
7244       <code>spapr-vio-serial</code> (usable with ppc64/pseries guests),
7245       <code>system-serial</code> (usable with aarch64/virt and,
7246       <span class="since">since 4.7.0</span>, riscv/virt guests) and
7247       <code>sclp-serial</code> (usable with s390 and s390x guests) are
7248       available as well.
7249     </p>
7250
7251     <p>
7252       <span class="since">Since 3.10.0</span>, the <code>target</code>
7253       element can have an optional <code>model</code> subelement;
7254       valid values for its <code>name</code> attribute are:
7255       <code>isa-serial</code> (usable with the <code>isa-serial</code> target
7256       type); <code>usb-serial</code> (usable with the <code>usb-serial</code>
7257       target type); <code>pci-serial</code>
7258       (usable with the <code>pci-serial</code> target type);
7259       <code>spapr-vty</code> (usable with the <code>spapr-vio-serial</code>
7260       target type); <code>pl011</code> and,
7261       <span class="since">since 4.7.0</span>, <code>16550a</code> (usable
7262       with the <code>system-serial</code> target type);
7263       <code>sclpconsole</code> and <code>sclplmconsole</code> (usable with
7264       the <code>sclp-serial</code> target type).
7265     </p>
7266
7267     <p>
7268       If any of the attributes is not specified by the user, libvirt will
7269       choose a value suitable for most users.
7270     </p>
7271
7272     <p>
7273       Most target types support configuring the guest-visible device
7274       address as <a href="#elementsAddress">documented above</a>; more
7275       specifically, acceptable address types are <code>isa</code> (for
7276       <code>isa-serial</code>), <code>usb</code> (for <code>usb-serial</code>),
7277       <code>pci</code> (for <code>pci-serial</code>) and <code>spapr-vio</code>
7278       (for <code>spapr-vio-serial</code>). The <code>system-serial</code>
7279       and <code>sclp-serial</code> target types don't support specifying an
7280       address.
7281     </p>
7282
7283     <p>
7284       For the relationship between serial ports and consoles,
7285       <a href="#elementCharSerialAndConsole">see below</a>.
7286     </p>
7287
7288     <h6><a id="elementCharConsole">Console</a></h6>
7289
7290 <pre>
7291 ...
7292 &lt;devices&gt;
7293   &lt;!-- Serial console --&gt;
7294   &lt;console type='pty'&gt;
7295     &lt;source path='/dev/pts/2'/&gt;
7296    &lt;target type='serial' port='0'/&gt;
7297   &lt;/console&gt;
7298 &lt;/devices&gt;
7299 ...</pre>
7300
7301 <pre>
7302 ...
7303 &lt;devices&gt;
7304   &lt;!-- KVM virtio console --&gt;
7305   &lt;console type='pty'&gt;
7306     &lt;source path='/dev/pts/5'/&gt;
7307     &lt;target type='virtio' port='0'/&gt;
7308   &lt;/console&gt;
7309 &lt;/devices&gt;
7310 ...</pre>
7311
7312     <p>
7313       The <code>console</code> element is used to represent interactive
7314       serial consoles. Depending on the type of guest in use and the specifics
7315       of the configuration, the <code>console</code> element might represent
7316       the same device as an existing <code>serial</code> element or a separate
7317       device.
7318     </p>
7319
7320     <p>
7321       A <code>target</code> subelement is supported and works the same
7322       way as with the <code>serial</code> element
7323       (<a href="#elementCharSerial">see above</a> for details).
7324       Valid values for the <code>type</code> attribute are:
7325       <code>serial</code> (described below);
7326       <code>virtio</code> (usable whenever VirtIO support is available);
7327       <code>xen</code>, <code>lxc</code> and <code>openvz</code>
7328       (available when the corresponding hypervisor is in use).
7329       <code>sclp</code> and <code>sclplm</code> (usable for s390 and
7330       s390x QEMU guests) are supported for compatibility reasons but should
7331       not be used for new guests: use the <code>sclpconsole</code> and
7332       <code>sclplmconsole</code> target models, respectively, with the
7333       <code>serial</code> element instead.
7334     </p>
7335
7336     <p>
7337       Of the target types listed above, <code>serial</code> is special in
7338       that it doesn't represents a separate device, but rather the same
7339       device as the first <code>serial</code> element. Due to this, there can
7340       only be a single <code>console</code> element with target type
7341       <code>serial</code> per guest.
7342     </p>
7343
7344     <p>
7345       Virtio consoles are usually accessible as <code>/dev/hvc[0-7]</code>
7346       from inside the guest; for more information, see
7347       <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>.
7348       <span class="since">Since 0.8.3</span>
7349     </p>
7350
7351     <p>
7352       For the relationship between serial ports and consoles,
7353       <a href="#elementCharSerialAndConsole">see below</a>.
7354     </p>
7355
7356     <h6><a id="elementCharSerialAndConsole">Relationship between serial ports and consoles</a></h6>
7357
7358     <p>
7359       Due to hystorical reasons, the <code>serial</code> and
7360       <code>console</code> elements have partially overlapping scopes.
7361     </p>
7362
7363     <p>
7364       In general, both elements are used to configure one or more serial
7365       consoles to be used for interacting with the guest. The main difference
7366       between the two is that <code>serial</code> is used for emulated,
7367       usually native, serial consoles, whereas <code>console</code> is used
7368       for paravirtualized ones.
7369     </p>
7370
7371     <p>
7372       Both emulated and paravirtualized serial consoles have advantages and
7373       disadvantages:
7374     </p>
7375
7376     <ul>
7377       <li>
7378         emulated serial consoles are usually initialized much earlier than
7379         paravirtualized ones, so they can be used to control the bootloader
7380         and display both firmware and early boot messages;
7381       </li>
7382       <li>
7383         on several platforms, there can only be a single emulated serial
7384         console per guest but paravirtualized consoles don't suffer from the
7385         same limitation.
7386       </li>
7387     </ul>
7388
7389     <p>
7390       A configuration such as:
7391     </p>
7392
7393 <pre>
7394 ...
7395 &lt;devices&gt;
7396   &lt;console type='pty'&gt;
7397     &lt;target type='serial'/&gt;
7398   &lt;/console&gt;
7399   &lt;console type='pty'&gt;
7400     &lt;target type='virtio'/&gt;
7401   &lt;/console&gt;
7402 &lt;/devices&gt;
7403 ...</pre>
7404
7405     <p>
7406       will work on any platform and will result in one emulated serial console
7407       for early boot logging / interactive / recovery use, and one
7408       paravirtualized serial console to be used eg. as a side channel. Most
7409       people will be fine with having just the first <code>console</code>
7410       element in their configuration.
7411     </p>
7412
7413     <p>
7414       Note that, due to the compatibility concerns mentioned earlier, all the
7415       following configurations:
7416     </p>
7417
7418 <pre>
7419 ...
7420 &lt;devices&gt;
7421   &lt;serial type='pty'/&gt;
7422 &lt;/devices&gt;
7423 ...</pre>
7424
7425 <pre>
7426 ...
7427 &lt;devices&gt;
7428   &lt;console type='pty'/&gt;
7429 &lt;/devices&gt;
7430 ...</pre>
7431
7432 <pre>
7433 ...
7434 &lt;devices&gt;
7435   &lt;serial type='pty'/&gt;
7436   &lt;console type='pty'/&gt;
7437 &lt;/devices&gt;
7438 ...</pre>
7439
7440     <p>
7441       will be treated the same and will result in a single emulated serial
7442       console being available to the guest.
7443     </p>
7444
7445     <h6><a id="elementCharChannel">Channel</a></h6>
7446
7447     <p>
7448       This represents a private communication channel between the host and the
7449       guest.
7450     </p>
7451
7452 <pre>
7453 ...
7454 &lt;devices&gt;
7455   &lt;channel type='unix'&gt;
7456     &lt;source mode='bind' path='/tmp/guestfwd'/&gt;
7457     &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
7458   &lt;/channel&gt;
7459
7460   &lt;!-- KVM virtio channel --&gt;
7461   &lt;channel type='pty'&gt;
7462     &lt;target type='virtio' name='arbitrary.virtio.serial.port.name'/&gt;
7463   &lt;/channel&gt;
7464   &lt;channel type='unix'&gt;
7465     &lt;source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/&gt;
7466     &lt;target type='virtio' name='org.qemu.guest_agent.0' state='connected'/&gt;
7467   &lt;/channel&gt;
7468   &lt;channel type='spicevmc'&gt;
7469     &lt;target type='virtio' name='com.redhat.spice.0'/&gt;
7470   &lt;/channel&gt;
7471 &lt;/devices&gt;
7472 ...</pre>
7473
7474     <p>
7475       This can be implemented in a variety of ways. The specific type of
7476       channel is given in the <code>type</code> attribute of the
7477       <code>target</code> element. Different channel types have different
7478       <code>target</code> attributes.
7479     </p>
7480
7481     <dl>
7482       <dt><code>guestfwd</code></dt>
7483       <dd>TCP traffic sent by the guest to a given IP address and port is
7484         forwarded to the channel device on the host. The <code>target</code>
7485         element must have <code>address</code> and <code>port</code> attributes.
7486         <span class="since">Since 0.7.3</span></dd>
7487
7488       <dt><code>virtio</code></dt>
7489       <dd>Paravirtualized virtio channel. Channel is exposed in the guest under
7490         /dev/vport*, and if the optional element <code>name</code> is specified,
7491         /dev/virtio-ports/$name (for more info, please see
7492         <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>). The
7493         optional element <code>address</code> can tie the channel to a
7494         particular <code>type='virtio-serial'</code>
7495         controller, <a href="#elementsAddress">documented above</a>.
7496         With qemu, if <code>name</code> is "org.qemu.guest_agent.0",
7497         then libvirt can interact with a guest agent installed in the
7498         guest, for actions such as guest shutdown or file system quiescing.
7499         <span class="since">Since 0.7.7, guest agent interaction
7500         since 0.9.10</span> Moreover, <span class="since">since 1.0.6</span>
7501         it is possible to have source path auto generated for virtio unix channels.
7502         This is very useful in case of a qemu guest agent, where users don't
7503         usually care about the source path since it's libvirt who talks to
7504         the guest agent. In case users want to utilize this feature, they should
7505         leave <code>&lt;source&gt;</code> element out. <span class="since">Since
7506         1.2.11</span> the active XML for a virtio channel may contain an optional
7507         <code>state</code> attribute that reflects whether a process in the
7508         guest is active on the channel. This is an output-only attribute.
7509         Possible values for the <code>state</code> attribute are
7510         <code>connected</code> and <code>disconnected</code>.
7511       </dd>
7512       <dt><code>xen</code></dt>
7513       <dd> Paravirtualized Xen channel. Channel is exposed in the guest as a
7514         Xen console but identified with a name. Setup and consumption of a Xen
7515         channel depends on software and configuration in the guest
7516         (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>).
7517         Channel source path semantics are the same as the virtio target type.
7518         The <code>state</code> attribute is not supported since Xen channels
7519         lack the necessary probing mechanism.
7520         <span class="since">Since 2.3.0</span>
7521       </dd>
7522       <dt><code>spicevmc</code></dt>
7523       <dd>Paravirtualized SPICE channel. The domain must also have a
7524         SPICE server as a <a href="#elementsGraphics">graphics
7525         device</a>, at which point the host piggy-backs messages
7526         across the <code>main</code> channel.  The <code>target</code>
7527         element must be present, with
7528         attribute <code>type='virtio'</code>; an optional
7529         attribute <code>name</code> controls how the guest will have
7530         access to the channel, and defaults
7531         to <code>name='com.redhat.spice.0'</code>.  The
7532         optional <code>address</code> element can tie the channel to a
7533         particular <code>type='virtio-serial'</code> controller.
7534         <span class="since">Since 0.8.8</span></dd>
7535     </dl>
7536
7537     <h5><a id="elementsCharHostInterface">Host interface</a></h5>
7538
7539     <p>
7540       A character device presents itself to the host as one of the following
7541       types.
7542     </p>
7543
7544     <h6><a id="elementsCharSTDIO">Domain logfile</a></h6>
7545
7546     <p>
7547       This disables all input on the character device, and sends output
7548       into the virtual machine's logfile
7549     </p>
7550
7551 <pre>
7552 ...
7553 &lt;devices&gt;
7554   &lt;console type='stdio'&gt;
7555     &lt;target port='1'/&gt;
7556   &lt;/console&gt;
7557 &lt;/devices&gt;
7558 ...</pre>
7559
7560
7561     <h6><a id="elementsCharFle">Device logfile</a></h6>
7562
7563     <p>
7564       A file is opened and all data sent to the character
7565       device is written to the file.
7566     </p>
7567
7568 <pre>
7569 ...
7570 &lt;devices&gt;
7571   &lt;serial type="file"&gt;
7572     &lt;source path="/var/log/vm/vm-serial.log"/&gt;
7573     &lt;target port="1"/&gt;
7574   &lt;/serial&gt;
7575 &lt;/devices&gt;
7576 ...</pre>
7577
7578     <h6><a id="elementsCharVC">Virtual console</a></h6>
7579
7580     <p>
7581       Connects the character device to the graphical framebuffer in
7582       a virtual console. This is typically accessed via a special
7583       hotkey sequence such as "ctrl+alt+3"
7584     </p>
7585
7586 <pre>
7587 ...
7588 &lt;devices&gt;
7589   &lt;serial type='vc'&gt;
7590     &lt;target port="1"/&gt;
7591   &lt;/serial&gt;
7592 &lt;/devices&gt;
7593 ...</pre>
7594
7595     <h6><a id="elementsCharNull">Null device</a></h6>
7596
7597     <p>
7598       Connects the character device to the void. No data is ever
7599       provided to the input. All data written is discarded.
7600     </p>
7601
7602 <pre>
7603 ...
7604 &lt;devices&gt;
7605   &lt;serial type='null'&gt;
7606     &lt;target port="1"/&gt;
7607   &lt;/serial&gt;
7608 &lt;/devices&gt;
7609 ...</pre>
7610
7611     <h6><a id="elementsCharPTY">Pseudo TTY</a></h6>
7612
7613     <p>
7614       A Pseudo TTY is allocated using /dev/ptmx. A suitable client
7615       such as 'virsh console' can connect to interact with the
7616       serial port locally.
7617     </p>
7618
7619 <pre>
7620 ...
7621 &lt;devices&gt;
7622   &lt;serial type="pty"&gt;
7623     &lt;source path="/dev/pts/3"/&gt;
7624     &lt;target port="1"/&gt;
7625   &lt;/serial&gt;
7626 &lt;/devices&gt;
7627 ...</pre>
7628
7629     <p>
7630       NB special case if &lt;console type='pty'&gt;, then the TTY
7631       path is also duplicated as an attribute tty='/dev/pts/3'
7632       on the top level &lt;console&gt; tag. This provides compat
7633       with existing syntax for &lt;console&gt; tags.
7634     </p>
7635
7636     <h6><a id="elementsCharHost">Host device proxy</a></h6>
7637
7638     <p>
7639       The character device is passed through to the underlying
7640       physical character device. The device types must match,
7641       eg the emulated serial port should only be connected to
7642       a host serial port - don't connect a serial port to a parallel
7643       port.
7644     </p>
7645
7646 <pre>
7647 ...
7648 &lt;devices&gt;
7649   &lt;serial type="dev"&gt;
7650     &lt;source path="/dev/ttyS0"/&gt;
7651     &lt;target port="1"/&gt;
7652   &lt;/serial&gt;
7653 &lt;/devices&gt;
7654 ...</pre>
7655
7656     <h6><a id="elementsCharPipe">Named pipe</a></h6>
7657
7658     <p>
7659       The character device writes output to a named pipe. See pipe(7) for
7660       more info.
7661     </p>
7662
7663 <pre>
7664 ...
7665 &lt;devices&gt;
7666   &lt;serial type="pipe"&gt;
7667     &lt;source path="/tmp/mypipe"/&gt;
7668     &lt;target port="1"/&gt;
7669   &lt;/serial&gt;
7670 &lt;/devices&gt;
7671 ...</pre>
7672
7673     <h6><a id="elementsCharTCP">TCP client/server</a></h6>
7674
7675     <p>
7676       The character device acts as a TCP client connecting to a
7677       remote server.
7678     </p>
7679
7680 <pre>
7681 ...
7682 &lt;devices&gt;
7683   &lt;serial type="tcp"&gt;
7684     &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
7685     &lt;protocol type="raw"/&gt;
7686     &lt;target port="1"/&gt;
7687   &lt;/serial&gt;
7688 &lt;/devices&gt;
7689  ...</pre>
7690
7691     <p>
7692       Or as a TCP server waiting for a client connection.
7693     </p>
7694
7695 <pre>
7696 ...
7697 &lt;devices&gt;
7698   &lt;serial type="tcp"&gt;
7699     &lt;source mode="bind" host="127.0.0.1" service="2445"/&gt;
7700     &lt;protocol type="raw"/&gt;
7701     &lt;target port="1"/&gt;
7702   &lt;/serial&gt;
7703 &lt;/devices&gt;
7704 ...</pre>
7705
7706     <p>
7707       Alternatively you can use <code>telnet</code> instead
7708       of <code>raw</code> TCP in order to utilize the telnet protocol
7709       for the connection.
7710     </p>
7711     <p>
7712       <span class="since">Since 0.8.5,</span> some hypervisors support
7713       use of either <code>telnets</code> (secure telnet) or <code>tls</code>
7714       (via secure sockets layer) as the transport protocol for connections.
7715     </p>
7716
7717 <pre>
7718 ...
7719 &lt;devices&gt;
7720   &lt;serial type="tcp"&gt;
7721     &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
7722     &lt;protocol type="telnet"/&gt;
7723     &lt;target port="1"/&gt;
7724   &lt;/serial&gt;
7725   ...
7726   &lt;serial type="tcp"&gt;
7727     &lt;source mode="bind" host="127.0.0.1" service="2445"/&gt;
7728     &lt;protocol type="telnet"/&gt;
7729     &lt;target port="1"/&gt;
7730   &lt;/serial&gt;
7731 &lt;/devices&gt;
7732 ...</pre>
7733
7734     <p>
7735       <span class="since">Since 2.4.0,</span> the optional attribute
7736       <code>tls</code> can be used to control whether a chardev
7737       TCP communication channel would utilize a hypervisor configured
7738       TLS X.509 certificate environment in order to encrypt the data
7739       channel. For the QEMU hypervisor, usage of a TLS environment can
7740       be controlled on the host by the <code>chardev_tls</code> and
7741       <code>chardev_tls_x509_cert_dir</code> or
7742       <code>default_tls_x509_cert_dir</code> settings in the file
7743       /etc/libvirt/qemu.conf. If <code>chardev_tls</code> is enabled,
7744       then unless the <code>tls</code> attribute is set to "no", libvirt
7745       will use the host configured TLS environment.
7746       If <code>chardev_tls</code> is disabled, but the <code>tls</code>
7747       attribute is set to "yes", then libvirt will attempt to use the
7748       host TLS environment if either the <code>chardev_tls_x509_cert_dir</code>
7749       or <code>default_tls_x509_cert_dir</code> TLS directory structure exists.
7750     </p>
7751 <pre>
7752 ...
7753 &lt;devices&gt;
7754   &lt;serial type="tcp"&gt;
7755     &lt;source mode='connect' host="127.0.0.1" service="5555" tls="yes"/&gt;
7756     &lt;protocol type="raw"/&gt;
7757     &lt;target port="0"/&gt;
7758   &lt;/serial&gt;
7759 &lt;/devices&gt;
7760 ...</pre>
7761
7762     <h6><a id="elementsCharUDP">UDP network console</a></h6>
7763
7764     <p>
7765       The character device acts as a UDP netconsole service,
7766       sending and receiving packets. This is a lossy service.
7767     </p>
7768
7769 <pre>
7770 ...
7771 &lt;devices&gt;
7772   &lt;serial type="udp"&gt;
7773     &lt;source mode="bind" host="0.0.0.0" service="2445"/&gt;
7774     &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
7775     &lt;target port="1"/&gt;
7776   &lt;/serial&gt;
7777 &lt;/devices&gt;
7778 ...</pre>
7779
7780     <h6><a id="elementsCharUNIX">UNIX domain socket client/server</a></h6>
7781
7782     <p>
7783       The character device acts as a UNIX domain socket server,
7784       accepting connections from local clients.
7785     </p>
7786
7787 <pre>
7788 ...
7789 &lt;devices&gt;
7790   &lt;serial type="unix"&gt;
7791     &lt;source mode="bind" path="/tmp/foo"/&gt;
7792     &lt;target port="1"/&gt;
7793   &lt;/serial&gt;
7794 &lt;/devices&gt;
7795 ...</pre>
7796
7797     <h6><a id="elementsCharSpiceport">Spice channel</a></h6>
7798
7799     <p>
7800       The character device is accessible through spice connection
7801       under a channel name specified in the <code>channel</code>
7802       attribute.  <span class="since">Since 1.2.2</span>
7803     </p>
7804     <p>
7805       Note: depending on the hypervisor, spiceports might (or might not)
7806       be enabled on domains with or without <a href="#elementsGraphics">spice
7807       graphics</a>.
7808     </p>
7809
7810 <pre>
7811 ...
7812 &lt;devices&gt;
7813   &lt;serial type="spiceport"&gt;
7814     &lt;source channel="org.qemu.console.serial.0"/&gt;
7815     &lt;target port="1"/&gt;
7816   &lt;/serial&gt;
7817 &lt;/devices&gt;
7818 ...</pre>
7819
7820     <h6><a id="elementsNmdm">Nmdm device</a></h6>
7821
7822     <p>
7823       The nmdm device driver, available on FreeBSD, provides two
7824       tty devices connected together by a virtual null modem cable.
7825       <span class="since">Since 1.2.4</span>
7826     </p>
7827
7828 <pre>
7829 ...
7830 &lt;devices&gt;
7831   &lt;serial type="nmdm"&gt;
7832     &lt;source master="/dev/nmdm0A" slave="/dev/nmdm0B"/&gt;
7833   &lt;/serial&gt;
7834 &lt;/devices&gt;
7835 ...</pre>
7836
7837     <p>
7838       The <code>source</code> element has these attributes:
7839     </p>
7840
7841     <dl>
7842       <dt><code>master</code></dt>
7843       <dd>Master device of the pair, that is passed to the hypervisor.
7844       Device is specified by a fully qualified path.</dd>
7845
7846       <dt><code>slave</code></dt>
7847       <dd>Slave device of the pair, that is passed to the clients for connection
7848       to the guest console. Device is specified by a fully qualified path.</dd>
7849     </dl>
7850
7851     <h4><a id="elementsSound">Sound devices</a></h4>
7852
7853     <p>
7854       A virtual sound card can be attached to the host via the
7855       <code>sound</code> element. <span class="since">Since 0.4.3</span>
7856     </p>
7857
7858 <pre>
7859 ...
7860 &lt;devices&gt;
7861   &lt;sound model='es1370'/&gt;
7862 &lt;/devices&gt;
7863 ...</pre>
7864
7865     <dl>
7866       <dt><code>sound</code></dt>
7867       <dd>
7868         The <code>sound</code> element has one mandatory attribute,
7869         <code>model</code>, which specifies what real sound device is emulated.
7870         Valid values are specific to the underlying hypervisor, though typical
7871         choices are 'es1370', 'sb16', 'ac97', 'ich6' and 'usb'.
7872         (<span class="since">
7873          'ac97' only since 0.6.0, 'ich6' only since 0.8.8,
7874          'usb' only since 1.2.7</span>)
7875       </dd>
7876     </dl>
7877
7878     <p>
7879       <span class="since">Since 0.9.13</span>, a sound element
7880       with <code>ich6</code> model can have optional
7881       sub-elements <code>&lt;codec&gt;</code> to attach various audio
7882       codecs to the audio device. If not specified, a default codec
7883       will be attached to allow playback and recording.
7884       </p>
7885       <p>
7886       Valid values are:
7887       </p>
7888       <p>
7889       <ul>
7890         <li>'duplex' - advertise a line-in and a line-out </li>
7891         <li>'micro' -  advertise a speaker and a microphone </li>
7892         <li>'output' - advertise a line-out
7893             <span class="since">Since 4.4.0</span></li>
7894       </ul>
7895     </p>
7896
7897 <pre>
7898 ...
7899 &lt;devices&gt;
7900   &lt;sound model='ich6'&gt;
7901     &lt;codec type='micro'/&gt;
7902   &lt;/sound&gt;
7903 &lt;/devices&gt;
7904 ...</pre>
7905
7906     <p>
7907       Each <code>sound</code> element has an optional
7908       sub-element <code>&lt;address&gt;</code> which can tie the
7909       device to a particular PCI
7910       slot, <a href="#elementsAddress">documented above</a>.
7911     </p>
7912
7913     <h4><a id="elementsWatchdog">Watchdog device</a></h4>
7914
7915     <p>
7916       A virtual hardware watchdog device can be added to the guest via
7917       the <code>watchdog</code> element.
7918       <span class="since">Since 0.7.3, QEMU and KVM only</span>
7919     </p>
7920
7921     <p>
7922       The watchdog device requires an additional driver and management
7923       daemon in the guest.  Just enabling the watchdog in the libvirt
7924       configuration does not do anything useful on its own.
7925     </p>
7926
7927     <p>
7928       Currently libvirt does not support notification when the
7929       watchdog fires.  This feature is planned for a future version of
7930       libvirt.
7931     </p>
7932
7933 <pre>
7934 ...
7935 &lt;devices&gt;
7936   &lt;watchdog model='i6300esb'/&gt;
7937 &lt;/devices&gt;
7938 ...</pre>
7939
7940 <pre>
7941   ...
7942   &lt;devices&gt;
7943     &lt;watchdog model='i6300esb' action='poweroff'/&gt;
7944   &lt;/devices&gt;
7945 &lt;/domain&gt;</pre>
7946
7947     <dl>
7948       <dt><code>model</code></dt>
7949       <dd>
7950         <p>
7951         The required <code>model</code> attribute specifies what real
7952         watchdog device is emulated.  Valid values are specific to the
7953         underlying hypervisor.
7954         </p>
7955         <p>
7956         QEMU and KVM support:
7957         </p>
7958         <ul>
7959           <li>'i6300esb' - the recommended device,
7960             emulating a PCI Intel 6300ESB </li>
7961           <li>'ib700' - emulating an ISA iBase IB700 </li>
7962           <li>'diag288' - emulating an S390 DIAG288 device
7963             <span class="since">Since 1.2.17</span></li>
7964         </ul>
7965       </dd>
7966       <dt><code>action</code></dt>
7967       <dd>
7968         <p>
7969         The optional <code>action</code> attribute describes what
7970         action to take when the watchdog expires.  Valid values are
7971         specific to the underlying hypervisor.
7972         </p>
7973         <p>
7974         QEMU and KVM support:
7975         </p>
7976         <ul>
7977           <li>'reset' - default, forcefully reset the guest</li>
7978           <li>'shutdown' - gracefully shutdown the guest
7979             (not recommended) </li>
7980           <li>'poweroff' - forcefully power off the guest</li>
7981           <li>'pause' - pause the guest</li>
7982           <li>'none' - do nothing</li>
7983           <li>'dump' - automatically dump the guest
7984             <span class="since">Since 0.8.7</span></li>
7985           <li>'inject-nmi' - inject a non-maskable interrupt
7986             into the guest
7987             <span class="since">Since 1.2.17</span></li>
7988         </ul>
7989         <p>
7990         Note 1: the 'shutdown' action requires that the guest
7991         is responsive to ACPI signals.  In the sort of situations
7992         where the watchdog has expired, guests are usually unable
7993         to respond to ACPI signals.  Therefore using 'shutdown'
7994         is not recommended.
7995         </p>
7996         <p>
7997         Note 2: the directory to save dump files can be configured
7998         by <code>auto_dump_path</code> in file /etc/libvirt/qemu.conf.
7999         </p>
8000       </dd>
8001     </dl>
8002
8003     <h4><a id="elementsMemBalloon">Memory balloon device</a></h4>
8004
8005     <p>
8006       A virtual memory balloon device is added to all Xen and KVM/QEMU
8007       guests. It will be seen as <code>memballoon</code> element.
8008       It will be automatically added when appropriate, so there is no
8009       need to explicitly add this element in the guest XML unless a
8010       specific PCI slot needs to be assigned.
8011       <span class="since">Since 0.8.3, Xen, QEMU and KVM only</span>
8012       Additionally, <span class="since">since 0.8.4</span>, if the
8013       memballoon device needs to be explicitly disabled,
8014       <code>model='none'</code> may be used.
8015     </p>
8016
8017     <p>
8018       Example: automatically added device with KVM
8019     </p>
8020 <pre>
8021 ...
8022 &lt;devices&gt;
8023   &lt;memballoon model='virtio'/&gt;
8024 &lt;/devices&gt;
8025 ...</pre>
8026
8027     <p>
8028       Example: manually added device with static PCI slot 2 requested
8029     </p>
8030 <pre>
8031   ...
8032   &lt;devices&gt;
8033     &lt;memballoon model='virtio'&gt;
8034       &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/&gt;
8035       &lt;stats period='10'/&gt;
8036       &lt;driver iommu='on' ats='on'/&gt;
8037     &lt;/memballoon&gt;
8038   &lt;/devices&gt;
8039 &lt;/domain&gt;</pre>
8040
8041     <dl>
8042       <dt><code>model</code></dt>
8043       <dd>
8044         <p>
8045           The required <code>model</code> attribute specifies what type
8046           of balloon device is provided. Valid values are specific to
8047           the virtualization platform
8048         </p>
8049         <ul>
8050           <li>'virtio' - default with QEMU/KVM</li>
8051           <li>'virtio-transitional' <span class="since">Since 5.2.0</span></li>
8052           <li>'virtio-non-transitional' <span class="since">Since 5.2.0</span></li>
8053           <li>'xen' - default with Xen</li>
8054         </ul>
8055         See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
8056         for more details.
8057       </dd>
8058       <dt><code>autodeflate</code></dt>
8059       <dd>
8060         <p>
8061           The optional <code>autodeflate</code> attribute allows to
8062           enable/disable (values "on"/"off", respectively) the ability of the
8063           QEMU virtio memory balloon to release some memory at the last moment
8064           before a guest's process get killed by Out of Memory killer.
8065           <span class="since">Since 1.3.1, QEMU and KVM only</span>
8066         </p>
8067       </dd>
8068       <dt><code>period</code></dt>
8069       <dd>
8070         <p>
8071           The optional <code>period</code> allows the QEMU virtio memory balloon
8072           driver to provide statistics through the <code>virsh dommemstat
8073           [domain]</code> command. By default, collection is not enabled. In
8074           order to enable, use the <code>virsh dommemstat [domain] --period
8075           [number]</code> command or <code>virsh edit</code> command to add the
8076           option to the XML definition.  The <code>virsh dommemstat</code> will
8077           accept the options <code>--live</code>, <code>--current</code>,
8078           or <code>--config</code>.  If an option is not provided, the change
8079           for a running domain will only be made to the active guest.  If the
8080           QEMU driver is not at the right revision, the attempt to set the
8081           period will fail.  Large values (e.g. many years) might be ignored.
8082           <span class='since'>Since 1.1.1, requires QEMU 1.5</span>
8083         </p>
8084       </dd>
8085       <dt><code>driver</code></dt>
8086       <dd>
8087         For model <code>virtio</code> memballoon,
8088         <a href="#elementsVirtio">Virtio-specific options</a> can also be
8089         set. (<span class="since">Since 3.5.0</span>)
8090       </dd>
8091     </dl>
8092     <h4><a id="elementsRng">Random number generator device</a></h4>
8093
8094     <p>
8095       The virtual random number generator device allows the host to pass
8096       through entropy to guest operating systems.
8097       <span class="since">Since 1.0.3</span>
8098     </p>
8099
8100     <p>
8101       Example: usage of the RNG device:
8102     </p>
8103 <pre>
8104 ...
8105 &lt;devices&gt;
8106   &lt;rng model='virtio'&gt;
8107     &lt;rate period="2000" bytes="1234"/&gt;
8108     &lt;backend model='random'&gt;/dev/random&lt;/backend&gt;
8109     &lt;!-- OR --&gt;
8110     &lt;backend model='egd' type='udp'&gt;
8111       &lt;source mode='bind' service='1234'/&gt;
8112       &lt;source mode='connect' host='1.2.3.4' service='1234'/&gt;
8113     &lt;/backend&gt;
8114   &lt;/rng&gt;
8115 &lt;/devices&gt;
8116 ...
8117 </pre>
8118     <dl>
8119       <dt><code>model</code></dt>
8120       <dd>
8121         <p>
8122           The required <code>model</code> attribute specifies what type
8123           of RNG device is provided. Valid values are specific to
8124           the virtualization platform:
8125         </p>
8126         <ul>
8127           <li>'virtio' - supported by qemu and virtio-rng kernel module</li>
8128           <li>'virtio-transitional' <span class='since'>Since 5.2.0</span></li>
8129           <li>'virtio-non-transitional' <span class='since'>Since 5.2.0</span></li>
8130         </ul>
8131         See <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
8132         for more details.
8133       </dd>
8134       <dt><code>rate</code></dt>
8135       <dd>
8136         <p>
8137           The optional <code>rate</code> element allows limiting the rate at
8138           which entropy can be consumed from the source.  The mandatory
8139           attribute <code>bytes</code> specifies how many bytes are permitted
8140           to be consumed per period.  An optional <code>period</code> attribute
8141           specifies the duration of a period in milliseconds; if omitted, the
8142           period is taken as 1000 milliseconds (1 second).
8143           <span class='since'>Since 1.0.4</span>
8144         </p>
8145       </dd>
8146       <dt><code>backend</code></dt>
8147       <dd>
8148         <p>
8149           The <code>backend</code> element specifies the source of entropy
8150           to be used for the domain. The source model is configured using the
8151           <code>model</code> attribute. Supported source models are:
8152         </p>
8153         <dl>
8154           <dt><code>random</code></dt>
8155           <dd>
8156             <p>
8157               This backend type expects a non-blocking character device
8158               as input. The file name is specified as contents of the
8159               <code>backend</code> element. <span class='since'>Since
8160               1.3.4</span> any path is accepted. Before that
8161               <code>/dev/random</code> and <code>/dev/hwrng</code> were
8162               the only accepted paths. When no file name is specified,
8163               the hypervisor default is used. For QEMU, the default is
8164               <code>/dev/random</code>. However, the recommended source
8165               of entropy is <code>/dev/urandom</code> (as it doesn't
8166               have the limitations of <code>/dev/random</code>).
8167             </p>
8168           </dd>
8169           <dt><code>egd</code></dt>
8170           <dd>
8171             <p>
8172               This backend connects to a source using the EGD protocol.
8173               The source is specified as a character device. Refer to
8174               <a href='#elementsCharHostInterface'>character device host interface</a>
8175               for more information.
8176             </p>
8177           </dd>
8178         </dl>
8179       </dd>
8180       <dt><code>driver</code></dt>
8181       <dd>
8182         The subelement <code>driver</code> can be used to tune the device:
8183         <dl>
8184           <dt>virtio options</dt>
8185           <dd>
8186           <a href="#elementsVirtio">Virtio-specific options</a> can also be
8187           set. (<span class="since">Since 3.5.0</span>)
8188           </dd>
8189         </dl>
8190       </dd>
8191
8192     </dl>
8193
8194     <h4><a id="elementsTpm">TPM device</a></h4>
8195
8196     <p>
8197       The TPM device enables a QEMU guest to have access to TPM
8198       functionality. The TPM device may either be a TPM 1.2 or
8199       a TPM 2.0.
8200     </p>
8201     <p>
8202       The TPM passthrough device type provides access to the host's TPM
8203       for one QEMU guest. No other software may be using the TPM device,
8204       typically /dev/tpm0, at the time the QEMU guest is started.
8205       <span class="since">'passthrough' since 1.0.5</span>
8206     </p>
8207
8208     <p>
8209      Example: usage of the TPM passthrough device
8210     </p>
8211 <pre>
8212 ...
8213 &lt;devices&gt;
8214   &lt;tpm model='tpm-tis'&gt;
8215     &lt;backend type='passthrough'&gt;
8216       &lt;device path='/dev/tpm0'/&gt;
8217     &lt;/backend&gt;
8218   &lt;/tpm&gt;
8219 &lt;/devices&gt;
8220 ...
8221 </pre>
8222
8223     <p>
8224       The emulator device type gives access to a TPM emulator providing
8225       TPM functionality for each VM. QEMU talks to it over a Unix socket. With
8226       the emulator device type each guest gets its own private TPM.
8227       <span class="since">'emulator' since 4.5.0</span>
8228       The state of the TPM emulator can be encrypted by providing an
8229       <code>encryption</code> element.
8230       <span class="since">'encryption' since 5.6.0</span>
8231     </p>
8232     <p>
8233      Example: usage of the TPM Emulator
8234     </p>
8235 <pre>
8236   ...
8237   &lt;devices&gt;
8238     &lt;tpm model='tpm-tis'&gt;
8239       &lt;backend type='emulator' version='2.0'&gt;
8240         &lt;encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/&gt;
8241       &lt;/backend&gt;
8242     &lt;/tpm&gt;
8243   &lt;/devices&gt;
8244   ...
8245 </pre>
8246     <dl>
8247       <dt><code>model</code></dt>
8248       <dd>
8249         <p>
8250           The <code>model</code> attribute specifies what device
8251           model QEMU provides to the guest. If no model name is provided,
8252           <code>tpm-tis</code> will automatically be chosen.
8253           <span class="since">Since 4.4.0</span>, another available choice
8254           is the <code>tpm-crb</code>, which should only be used when the
8255           backend device is a TPM 2.0.
8256         </p>
8257       </dd>
8258       <dt><code>backend</code></dt>
8259       <dd>
8260         <p>
8261           The <code>backend</code> element specifies the type of
8262           TPM device. The following types are supported:
8263         </p>
8264         <dl>
8265           <dt><code>passthrough</code></dt>
8266           <dd>
8267             <p>
8268               Use the host's TPM device.
8269             </p>
8270             <p>
8271               This backend type requires exclusive access to a TPM device on
8272               the host. An example for such a device is /dev/tpm0. The fully
8273               qualified file name is specified by path attribute of the
8274               <code>source</code> element. If no file name is specified then
8275               /dev/tpm0 is automatically used.
8276             </p>
8277           </dd>
8278         </dl>
8279         <dl>
8280           <dt><code>emulator</code></dt>
8281           <dd>
8282             <p>
8283               For this backend type the 'swtpm' TPM Emulator must be installed on the
8284               host. Libvirt will automatically start an independent TPM emulator
8285               for each QEMU guest requesting access to it.
8286             </p>
8287           </dd>
8288         </dl>
8289       </dd>
8290       <dt><code>version</code></dt>
8291       <dd>
8292         <p>
8293           The <code>version</code> attribute indicates the version
8294           of the TPM. By default a TPM 1.2 is created. This attribute
8295           only works with the <code>emulator</code> backend. The following
8296           versions are supported:
8297         </p>
8298         <ul>
8299           <li>'1.2' : creates a TPM 1.2</li>
8300           <li>'2.0' : creates a TPM 2.0</li>
8301         </ul>
8302       </dd>
8303       <dt><code>encryption</code></dt>
8304       <dd>
8305         <p>
8306           The <code>encryption</code> element allows the state of a TPM emulator
8307           to be encrypted. The <code>secret</code> must reference a secret object
8308           that holds the passphrase from which the encryption key will be derived.
8309         </p>
8310       </dd>
8311     </dl>
8312
8313     <h4><a id="elementsNVRAM">NVRAM device</a></h4>
8314     <p>
8315       nvram device is always added to pSeries guest on PPC64, and its address
8316       is allowed to be changed.  Element <code>nvram</code> (only valid for
8317       pSeries guest, <span class="since">since 1.0.5</span>) is provided to
8318       enable the address setting.
8319     </p>
8320     <p>
8321       Example: usage of NVRAM configuration
8322     </p>
8323 <pre>
8324 ...
8325 &lt;devices&gt;
8326   &lt;nvram&gt;
8327     &lt;address type='spapr-vio' reg='0x00003000'/&gt;
8328   &lt;/nvram&gt;
8329 &lt;/devices&gt;
8330 ...
8331 </pre>
8332   <dl>
8333     <dt><code>spapr-vio</code></dt>
8334     <dd>
8335       <p>
8336         VIO device address type, only valid for PPC64.
8337       </p>
8338     </dd>
8339     <dt><code>reg</code></dt>
8340     <dd>
8341       <p>
8342         Device address
8343       </p>
8344     </dd>
8345   </dl>
8346
8347     <h4><a id="elementsPanic">panic device</a></h4>
8348     <p>
8349       panic device enables libvirt to receive panic notification from a QEMU
8350       guest.
8351       <span class="since">Since 1.2.1, QEMU and KVM only</span>
8352     </p>
8353     <p>
8354       This feature is always enabled for:
8355     </p>
8356     <ul>
8357       <li>pSeries guests, since it's implemented by the guest firmware</li>
8358       <li>S390 guests, since it's an integral part of the S390 architecture</li>
8359     </ul>
8360     <p>
8361       For the guest types listed above, libvirt automatically adds a
8362       <code>panic</code> element to the domain XML.
8363     </p>
8364     <p>
8365       Example: usage of panic configuration
8366     </p>
8367 <pre>
8368 ...
8369 &lt;devices&gt;
8370   &lt;panic model='hyperv'/&gt;
8371   &lt;panic model='isa'&gt;
8372     &lt;address type='isa' iobase='0x505'/&gt;
8373   &lt;/panic&gt;
8374 &lt;/devices&gt;
8375 ...
8376 </pre>
8377   <dl>
8378     <dt><code>model</code></dt>
8379       <dd>
8380         <p>
8381           The optional <code>model</code> attribute specifies what type
8382           of panic device is provided. The panic model used when this attribute
8383           is missing depends on the hypervisor and guest arch.
8384         </p>
8385         <ul>
8386           <li>'isa' - for ISA pvpanic device</li>
8387           <li>'pseries' - default and valid only for pSeries guests.</li>
8388           <li>'hyperv' - for Hyper-V crash CPU feature.
8389             <span class="since">Since 1.3.0, QEMU and KVM only</span></li>
8390           <li>'s390' - default for S390 guests.
8391             <span class="since">Since 1.3.5</span></li>
8392         </ul>
8393       </dd>
8394     <dt><code>address</code></dt>
8395     <dd>
8396       <p>
8397         address of panic. The default ioport is 0x505. Most users
8398         don't need to specify an address, and doing so is forbidden
8399         altogether for s390, pseries and hyperv models.
8400       </p>
8401     </dd>
8402   </dl>
8403
8404   <h4><a id="elementsShmem">Shared memory device</a></h4>
8405
8406     <p>
8407       A shared memory device allows to share a memory region between
8408       different virtual machines and the host.
8409       <span class="since">Since 1.2.10, QEMU and KVM only</span>
8410     </p>
8411
8412 <pre>
8413 ...
8414 &lt;devices&gt;
8415   &lt;shmem name='my_shmem0'&gt;
8416     &lt;model type='ivshmem-plain'/&gt;
8417     &lt;size unit='M'&gt;4&lt;/size&gt;
8418   &lt;/shmem&gt;
8419   &lt;shmem name='shmem_server'&gt;
8420     &lt;model type='ivshmem-doorbell'/&gt;
8421     &lt;size unit='M'&gt;2&lt;/size&gt;
8422     &lt;server path='/tmp/socket-shmem'/&gt;
8423     &lt;msi vectors='32' ioeventfd='on'/&gt;
8424   &lt;/shmem&gt;
8425 &lt;/devices&gt;
8426 ...
8427 </pre>
8428
8429   <dl>
8430     <dt><code>shmem</code></dt>
8431     <dd>
8432       The <code>shmem</code> element has one mandatory attribute,
8433       <code>name</code> to identify the shared memory. This attribute cannot
8434       be directory specific to <code>.</code> or <code>..</code> as well as
8435       it cannot involve path separator <code>/</code>.
8436     </dd>
8437     <dt><code>model</code></dt>
8438     <dd>
8439       Attribute <code>type</code> of the optional element <code>model</code>
8440       specifies the model of the underlying device providing the
8441       <code>shmem</code> device.  The models currently supported are
8442       <code>ivshmem</code> (supports both server and server-less shmem, but is
8443       deprecated by newer QEMU in favour of the -plain and -doorbell variants),
8444       <code>ivshmem-plain</code> (only for server-less shmem) and
8445       <code>ivshmem-doorbell</code> (only for shmem with the server).
8446     </dd>
8447     <dt><code>size</code></dt>
8448     <dd>
8449       The optional <code>size</code> element specifies the size of the shared
8450       memory. This must be power of 2 and greater than or equal to 1 MiB.
8451     </dd>
8452     <dt><code>server</code></dt>
8453     <dd>
8454       The optional <code>server</code> element can be used to configure a server
8455       socket the device is supposed to connect to.  The optional
8456       <code>path</code> attribute specifies the absolute path to the unix socket
8457       and defaults to <code>/var/lib/libvirt/shmem/$shmem-$name-sock</code>.
8458     </dd>
8459     <dt><code>msi</code></dt>
8460     <dd>
8461       The optional <code>msi</code> element enables/disables (values "on"/"off",
8462       respectively) MSI interrupts. This option can currently be used only
8463       together with the <code>server</code> element. The <code>vectors</code>
8464       attribute can be used to specify the number of interrupt
8465       vectors. The <code>ioeventd</code> attribute enables/disables (values
8466       "on"/"off", respectively) ioeventfd.
8467     </dd>
8468   </dl>
8469
8470     <h4><a id="elementsMemory">Memory devices</a></h4>
8471
8472     <p>
8473         In addition to the initial memory assigned to the guest, memory devices
8474         allow additional memory to be assigned to the guest in the form of
8475         memory modules.
8476
8477         A memory device can be hot-plugged or hot-unplugged depending on the
8478         guests' memory resource needs.
8479
8480         Some hypervisors may require NUMA configured for the guest.
8481     </p>
8482
8483     <p>
8484       Example: usage of the memory devices
8485     </p>
8486 <pre>
8487 ...
8488 &lt;devices&gt;
8489   &lt;memory model='dimm' access='private' discard='yes'&gt;
8490     &lt;target&gt;
8491       &lt;size unit='KiB'&gt;524287&lt;/size&gt;
8492       &lt;node&gt;0&lt;/node&gt;
8493     &lt;/target&gt;
8494   &lt;/memory&gt;
8495   &lt;memory model='dimm'&gt;
8496     &lt;source&gt;
8497       &lt;pagesize unit='KiB'&gt;4096&lt;/pagesize&gt;
8498       &lt;nodemask&gt;1-3&lt;/nodemask&gt;
8499     &lt;/source&gt;
8500     &lt;target&gt;
8501       &lt;size unit='KiB'&gt;524287&lt;/size&gt;
8502       &lt;node&gt;1&lt;/node&gt;
8503     &lt;/target&gt;
8504   &lt;/memory&gt;
8505   &lt;memory model='nvdimm'&gt;
8506     &lt;source&gt;
8507       &lt;path&gt;/tmp/nvdimm&lt;/path&gt;
8508       &lt;alignsize unit='KiB'&gt;2048&lt;/alignsize&gt;
8509     &lt;/source&gt;
8510     &lt;target&gt;
8511       &lt;size unit='KiB'&gt;524288&lt;/size&gt;
8512       &lt;node&gt;1&lt;/node&gt;
8513       &lt;label&gt;
8514         &lt;size unit='KiB'&gt;128&lt;/size&gt;
8515       &lt;/label&gt;
8516       &lt;readonly/&gt;
8517     &lt;/target&gt;
8518   &lt;/memory&gt;
8519   &lt;memory model='nvdimm'&gt;
8520     &lt;source&gt;
8521       &lt;path&gt;/dev/dax0.0&lt;/path&gt;
8522       &lt;pmem/&gt;
8523     &lt;/source&gt;
8524     &lt;target&gt;
8525       &lt;size unit='KiB'&gt;524288&lt;/size&gt;
8526       &lt;node&gt;1&lt;/node&gt;
8527       &lt;label&gt;
8528         &lt;size unit='KiB'&gt;128&lt;/size&gt;
8529       &lt;/label&gt;
8530     &lt;/target&gt;
8531   &lt;/memory&gt;
8532 &lt;/devices&gt;
8533 ...
8534 </pre>
8535     <dl>
8536       <dt><code>model</code></dt>
8537       <dd>
8538         <p>
8539           Provide <code>dimm</code> to add a virtual DIMM module to the guest.
8540           <span class="since">Since 1.2.14</span>
8541           Provide <code>nvdimm</code> model adds a Non-Volatile DIMM
8542           module. <span class="since">Since 3.2.0</span>
8543         </p>
8544       </dd>
8545
8546       <dt><code>access</code></dt>
8547       <dd>
8548         <p>
8549           An optional attribute <code>access</code>
8550           (<span class="since">since 3.2.0</span>) that provides
8551           capability to fine tune mapping of the memory on per
8552           module basis. Values are the same as
8553           <a href="#elementsMemoryBacking">Memory Backing</a>:
8554           <code>shared</code> and <code>private</code>.
8555         </p>
8556       </dd>
8557
8558       <dt><code>discard</code></dt>
8559       <dd>
8560         <p>
8561           An optional attribute <code>discard</code>
8562           (<span class="since">since 4.4.0</span>) that provides
8563           capability to fine tune discard of data on per module
8564           basis. Accepted values are <code>yes</code> and
8565           <code>no</code>. The feature is described here:
8566           <a href="#elementsMemoryBacking">Memory Backing</a>.
8567           This attribute is allowed only for
8568           <code>model='dimm'</code>.
8569         </p>
8570       </dd>
8571
8572       <dt><code>source</code></dt>
8573       <dd>
8574         <p>
8575           For model <code>dimm</code> this element is optional and allows to
8576           fine tune the source of the memory used for the given memory device.
8577           If the element is not provided defaults configured via
8578           <code>numatune</code> are used. If <code>dimm</code> is provided,
8579           then the following optional elements can be provided as well:
8580         </p>
8581
8582         <dl>
8583           <dt><code>pagesize</code></dt>
8584           <dd>
8585             <p>
8586               This element can be used to override the default
8587               host page size used for backing the memory device.
8588               The configured value must correspond to a page size
8589               supported by the host.
8590             </p>
8591           </dd>
8592
8593           <dt><code>nodemask</code></dt>
8594           <dd>
8595             <p>
8596               This element can be used to override the default
8597               set of NUMA nodes where the memory would be
8598               allocated.
8599             </p>
8600           </dd>
8601         </dl>
8602
8603         <p>
8604           For model <code>nvdimm</code> this element is mandatory. The
8605           mandatory child element <code>path</code> represents a path in
8606           the host that backs the nvdimm module in the guest. The following
8607           optional elements may be used:
8608         </p>
8609
8610         <dl>
8611           <dt><code>alignsize</code></dt>
8612           <dd>
8613             <p>
8614               The <code>alignsize</code> element defines the page size
8615               alignment used to mmap the address range for the backend
8616               <code>path</code>. If not supplied the host page size is used.
8617               For example, to mmap a real NVDIMM device a 2M-aligned page may
8618               be required.
8619               <span class="since">Since 5.0.0</span>
8620             </p>
8621           </dd>
8622
8623           <dt><code>pmem</code></dt>
8624           <dd>
8625             <p>
8626               If persistent memory is supported and enabled by the hypervisor
8627               in order to guarantee the persistence of writes to the vNVDIMM
8628               backend, then use the <code>pmem</code> element in order to
8629               utilize the feature.
8630               <span class="since">Since 5.0.0</span>
8631             </p>
8632           </dd>
8633         </dl>
8634       </dd>
8635
8636       <dt><code>target</code></dt>
8637       <dd>
8638         <p>
8639           The mandatory <code>target</code> element configures the placement and
8640           sizing of the added memory from the perspective of the guest.
8641         </p>
8642         <p>
8643           The mandatory <code>size</code> subelement configures the size of the
8644           added memory as a scaled integer.
8645         </p>
8646         <p>
8647           The <code>node</code> subelement configures the guest NUMA node to
8648           attach the memory to. The element shall be used only if the guest has
8649           NUMA nodes configured.
8650         </p>
8651         <p>
8652           The following optional elements may be used:
8653         </p>
8654
8655         <dl>
8656           <dt><code>label</code></dt>
8657           <dd>
8658             <p>
8659               For NVDIMM type devices one can optionally use
8660               <code>label</code> and its subelement <code>size</code>
8661               to configure the size of namespaces label storage
8662               within the NVDIMM module. The <code>size</code> element
8663               has usual meaning described
8664               <a href="#elementsMemoryAllocation">here</a>.
8665               For QEMU domains the following restrictions apply:
8666             </p>
8667             <ol>
8668               <li>the minimum label size is 128KiB,</li>
8669               <li>the remaining size (total-size - label-size) will be aligned
8670                 to 4KiB as default.</li>
8671             </ol>
8672           </dd>
8673
8674           <dt><code>readonly</code></dt>
8675           <dd>
8676             <p>
8677               The <code>readonly</code> element is used to mark the vNVDIMM
8678               as read-only. Only the real NVDIMM device backend can guarantee
8679               the guest write persistence, so other backend types should use
8680               the <code>readonly</code> element.
8681               <span class="since">Since 5.0.0</span>
8682             </p>
8683           </dd>
8684         </dl>
8685       </dd>
8686     </dl>
8687
8688     <h4><a id="elementsIommu">IOMMU devices</a></h4>
8689
8690     <p>
8691       The <code>iommu</code> element can be used to add an IOMMU device.
8692       <span class="since">Since 2.1.0</span>
8693     </p>
8694
8695     <p>
8696       Example:
8697     </p>
8698 <pre>
8699 ...
8700 &lt;devices&gt;
8701   &lt;iommu model='intel'&gt;
8702     &lt;driver intremap='on'/&gt;
8703   &lt;/iommu&gt;
8704 &lt;/devices&gt;
8705 ...
8706 </pre>
8707     <dl>
8708       <dt><code>model</code></dt>
8709       <dd>
8710         <p>
8711           Supported values are <code>intel</code> (for Q35 guests) and,
8712           <span class="since">since 5.5.0</span>, <code>smmuv3</code> (for
8713           ARM virt guests).
8714         </p>
8715       </dd>
8716       <dt><code>driver</code></dt>
8717       <dd>
8718         <p>
8719           The <code>driver</code> subelement can be used to configure
8720           additional options, some of which might only be available for
8721           certain IOMMU models:
8722         </p>
8723         <dl>
8724           <dt><code>intremap</code></dt>
8725           <dd>
8726             <p>
8727               The <code>intremap</code> attribute with possible values
8728               <code>on</code> and <code>off</code> can be used to
8729               turn on interrupt remapping, a part of the VT-d functionality.
8730               Currently this requires split I/O APIC
8731               (<code>&lt;ioapic driver='qemu'/&gt;</code>).
8732               <span class="since">Since 3.4.0</span> (QEMU/KVM only)
8733             </p>
8734           </dd>
8735           <dt><code>caching_mode</code></dt>
8736           <dd>
8737             <p>
8738               The <code>caching_mode</code> attribute with possible values
8739               <code>on</code> and <code>off</code> can be used to
8740               turn on the VT-d caching mode (useful for assigned devices).
8741               <span class="since">Since 3.4.0</span> (QEMU/KVM only)
8742             </p>
8743           </dd>
8744           <dt><code>eim</code></dt>
8745           <dd>
8746             <p>
8747               The <code>eim</code> attribute (with possible values
8748               <code>on</code> and <code>off</code>) can be used to
8749               configure Extended Interrupt Mode. A q35 domain with
8750               split I/O APIC (as described in
8751               <a href="#elementsFeatures">hypervisor features</a>),
8752               and both interrupt remapping and EIM turned on for
8753               the IOMMU, will be able to use more than 255 vCPUs.
8754               <span class="since">Since 3.4.0</span> (QEMU/KVM only)
8755             </p>
8756           </dd>
8757           <dt><code>iotlb</code></dt>
8758           <dd>
8759             <p>
8760               The <code>iotlb</code> attribute with possible values
8761               <code>on</code> and <code>off</code> can be used to
8762               turn on the IOTLB used to cache address translation
8763               requests from devices.
8764               <span class="since">Since 3.5.0</span> (QEMU/KVM only)
8765             </p>
8766           </dd>
8767         </dl>
8768       </dd>
8769     </dl>
8770
8771     <h3><a id="vsock">Vsock</a></h3>
8772
8773     <p>A vsock host/guest interface. The <code>model</code> attribute
8774     defaults to <code>virtio</code>. <span class="since">Since 5.2.0</span>
8775     <code>model</code> can also be 'virtio-transitional' and
8776     'virtio-non-transitional', see
8777     <a href="#elementsVirtioTransitional">Virtio transitional devices</a>
8778     for more details.
8779     The optional attribute <code>address</code> of the <code>cid</code>
8780     element specifies the CID assigned to the guest. If the attribute
8781     <code>auto</code> is set to <code>yes</code>, libvirt
8782     will assign a free CID automatically on domain startup.
8783     <span class="since">Since 4.4.0</span></p>
8784
8785 <pre>
8786 ...
8787 &lt;devices&gt;
8788   &lt;vsock model='virtio'&gt;
8789     &lt;cid auto='no' address='3'/&gt;
8790   &lt;/vsock&gt;
8791 &lt;/devices&gt;
8792 ...</pre>
8793
8794
8795     <h3><a id="seclabel">Security label</a></h3>
8796
8797     <p>
8798       The <code>seclabel</code> element allows control over the
8799       operation of the security drivers. There are three basic
8800       modes of operation, 'dynamic' where libvirt automatically
8801       generates a unique security label, 'static' where the
8802       application/administrator chooses the labels, or 'none'
8803       where confinement is disabled. With dynamic
8804       label generation, libvirt will always automatically
8805       relabel any resources associated with the virtual machine.
8806       With static label assignment, by default, the administrator
8807       or application must ensure labels are set correctly on any
8808       resources, however, automatic relabeling can be enabled
8809       if desired.  <span class="since">'dynamic' since 0.6.1, 'static'
8810       since 0.6.2, and 'none' since 0.9.10.</span>
8811     </p>
8812
8813     <p>
8814       If more than one security driver is used by libvirt, multiple
8815       <code>seclabel</code> tags can be used, one for each driver and
8816       the security driver referenced by each tag can be defined using
8817       the attribute <code>model</code>
8818     </p>
8819
8820     <p>
8821       Valid input XML configurations for the top-level security label
8822       are:
8823     </p>
8824
8825     <pre>
8826 &lt;seclabel type='dynamic' model='selinux'/&gt;
8827
8828 &lt;seclabel type='dynamic' model='selinux'&gt;
8829   &lt;baselabel&gt;system_u:system_r:my_svirt_t:s0&lt;/baselabel&gt;
8830 &lt;/seclabel&gt;
8831
8832 &lt;seclabel type='static' model='selinux' relabel='no'&gt;
8833   &lt;label&gt;system_u:system_r:svirt_t:s0:c392,c662&lt;/label&gt;
8834 &lt;/seclabel&gt;
8835
8836 &lt;seclabel type='static' model='selinux' relabel='yes'&gt;
8837   &lt;label&gt;system_u:system_r:svirt_t:s0:c392,c662&lt;/label&gt;
8838 &lt;/seclabel&gt;
8839
8840 &lt;seclabel type='none'/&gt;
8841     </pre>
8842
8843     <p>
8844       If no 'type' attribute is provided in the input XML, then
8845       the security driver default setting will be used, which
8846       may be either 'none' or 'dynamic'. If a 'baselabel' is set
8847       but no 'type' is set, then the type is presumed to be 'dynamic'
8848     </p>
8849
8850     <p>
8851       When viewing the XML for a running guest with automatic
8852       resource relabeling active, an additional XML element,
8853       <code>imagelabel</code>, will be included. This is an
8854       output-only element, so will be ignored in user supplied
8855       XML documents
8856     </p>
8857     <dl>
8858       <dt><code>type</code></dt>
8859       <dd>Either <code>static</code>, <code>dynamic</code> or <code>none</code>
8860         to determine whether libvirt automatically generates a unique security
8861         label or not.
8862       </dd>
8863       <dt><code>model</code></dt>
8864       <dd>A valid security model name, matching the currently
8865         activated security model
8866       </dd>
8867       <dt><code>relabel</code></dt>
8868       <dd>Either <code>yes</code> or <code>no</code>. This must always
8869         be <code>yes</code> if dynamic label assignment is used. With
8870         static label assignment it will default to <code>no</code>.
8871       </dd>
8872       <dt><code>label</code></dt>
8873       <dd>If static labelling is used, this must specify the full
8874         security label to assign to the virtual domain. The format
8875         of the content depends on the security driver in use:
8876         <ul>
8877           <li>SELinux: a SELinux context.</li>
8878           <li>AppArmor: an AppArmor profile.</li>
8879           <li>
8880             DAC: owner and group separated by colon. They can be
8881             defined both as user/group names or uid/gid. The driver will first
8882             try to parse these values as names, but a leading plus sign can
8883             used to force the driver to parse them as uid or gid.
8884           </li>
8885         </ul>
8886       </dd>
8887       <dt><code>baselabel</code></dt>
8888       <dd>If dynamic labelling is used, this can optionally be
8889         used to specify the base security label that will be used to generate
8890         the actual label. The format of the content depends on the security
8891         driver in use.
8892
8893         The SELinux driver uses only the <code>type</code> field of the
8894         baselabel in the generated label. Other fields are inherited from
8895         the parent process when using SELinux baselabels.
8896
8897         (The example above demonstrates the use of <code>my_svirt_t</code>
8898         as the value for the <code>type</code> field.)
8899       </dd>
8900       <dt><code>imagelabel</code></dt>
8901       <dd>This is an output only element, which shows the
8902         security label used on resources associated with the virtual domain.
8903         The format of the content depends on the security driver in use
8904       </dd>
8905     </dl>
8906
8907     <p>When relabeling is in effect, it is also possible to fine-tune
8908       the labeling done for specific source file names, by either
8909       disabling the labeling (useful if the file lives on NFS or other
8910       file system that lacks security labeling) or requesting an
8911       alternate label (useful when a management application creates a
8912       special label to allow sharing of some, but not all, resources
8913       between domains), <span class="since">since 0.9.9</span>.  When
8914       a <code>seclabel</code> element is attached to a specific path
8915       rather than the top-level domain assignment, only the
8916       attribute <code>relabel</code> or the
8917       sub-element <code>label</code> are supported.  Additionally,
8918       <span class="since">since 1.1.2</span>, an output-only
8919       element <code>labelskip</code> will be present for active
8920       domains on disks where labeling was skipped due to the image
8921       being on a file system that lacks security labeling.
8922     </p>
8923
8924     <h3><a id="keywrap">Key Wrap</a></h3>
8925
8926        <p>The content of the optional <code>keywrap</code> element specifies
8927         whether the guest will be allowed to perform the S390 cryptographic key
8928         management operations. A clear key can be protected by encrypting it
8929         under a unique wrapping key that is generated for each guest VM running
8930         on the host. Two variations of wrapping keys are generated: one version
8931         for encrypting protected keys using the DEA/TDEA algorithm, and another
8932         version for keys encrypted using the AES algorithm. If a
8933         <code>keywrap</code> element is not included, the guest will be granted
8934         access to both AES and DEA/TDEA key wrapping by default.</p>
8935
8936         <pre>
8937 &lt;domain&gt;
8938   ...
8939   &lt;keywrap&gt;
8940     &lt;cipher name='aes' state='off'/&gt;
8941   &lt;/keywrap&gt;
8942   ...
8943 &lt;/domain&gt;
8944 </pre>
8945     <p>
8946       At least one <code>cipher</code> element must be nested within the
8947       <code>keywrap</code> element.
8948     </p>
8949     <dl>
8950       <dt><code>cipher</code></dt>
8951       <dd>The <code>name</code> attribute identifies the algorithm
8952         for encrypting a protected key. The values supported for this attribute
8953         are <code>aes</code> for encryption under the AES wrapping key, or
8954         <code>dea</code> for encryption under the DEA/TDEA wrapping key. The
8955         <code>state</code> attribute indicates whether the cryptographic key
8956         management operations should be turned on for the specified encryption
8957         algorithm. The value can be set to <code>on</code> or <code>off</code>.
8958       </dd>
8959     </dl>
8960
8961     <p>Note: DEA/TDEA is synonymous with DES/TDES.</p>
8962
8963     <h3><a id="launchSecurity">Launch Security</a></h3>
8964
8965     <p>
8966        The contents of the <code>&lt;launchSecurity type='sev'&gt;</code> element
8967        is used to provide the guest owners input used for creating an encrypted
8968        VM using the AMD SEV feature (Secure Encrypted Virtualization).
8969
8970        SEV is an extension to the AMD-V architecture which supports running
8971        encrypted virtual machine (VMs) under the control of KVM. Encrypted
8972        VMs have their pages (code and data) secured such that only the guest
8973        itself has access to the unencrypted version. Each encrypted VM is
8974        associated with a unique encryption key; if its data is accessed to a
8975        different entity using a different key the encrypted guests data will
8976        be incorrectly decrypted, leading to unintelligible data.
8977
8978        For more information see various input parameters and its format see the
8979        <a href="https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf">SEV API spec</a>
8980        <span class="since">Since 4.4.0</span>
8981        </p>
8982     <pre>
8983 &lt;domain&gt;
8984   ...
8985   &lt;launchSecurity type='sev'&gt;
8986     &lt;policy&gt;0x0001&lt;/policy&gt;
8987     &lt;cbitpos&gt;47&lt;/cbitpos&gt;
8988     &lt;reducedPhysBits&gt;1&lt;/reducedPhysBits&gt;
8989     &lt;dhCert&gt;RBBBSDDD=FDDCCCDDDG&lt;/dhCert&gt;
8990     &lt;session&gt;AAACCCDD=FFFCCCDSDS&lt;/session&gt;
8991   &lt;/launchSecurity&gt;
8992   ...
8993 &lt;/domain&gt;
8994 </pre>
8995
8996     <dl>
8997       <dt><code>cbitpos</code></dt>
8998       <dd>The required <code>cbitpos</code> element provides the C-bit (aka encryption bit)
8999       location in guest page table entry. The value of <code>cbitpos</code> is
9000       hypervisor dependent and can be obtained through the <code>sev</code> element
9001       from the domain capabilities.
9002       </dd>
9003       <dt><code>reducedPhysBits</code></dt>
9004       <dd>The required <code>reducedPhysBits</code> element provides the physical
9005       address bit reducation. Similar to <code>cbitpos</code> the value of <code>
9006       reduced-phys-bit</code> is hypervisor dependent and can be obtained
9007       through the <code>sev</code> element from the domain capabilities.
9008       </dd>
9009       <dt><code>policy</code></dt>
9010       <dd>The required <code>policy</code> element provides the guest policy
9011       which must be maintained by the SEV firmware. This policy is enforced by
9012       the firmware and restricts what configuration and operational commands
9013       can be performed on this guest by the hypervisor. The guest policy
9014       provided during guest launch is bound to the guest and cannot be changed
9015       throughout the lifetime of the guest. The policy is also transmitted
9016       during snapshot and migration flows and enforced on the destination platform.
9017
9018       The guest policy is a 4 unsigned byte with the fields shown in Table:
9019
9020       <table class="top_table">
9021         <tr>
9022           <th> Bit(s) </th>
9023           <th> Description </th>
9024         </tr>
9025         <tr>
9026           <td> 0 </td>
9027           <td> Debugging of the guest is disallowed when set </td>
9028         </tr>
9029         <tr>
9030           <td> 1 </td>
9031           <td> Sharing keys with other guests is disallowed when set </td>
9032         </tr>
9033         <tr>
9034           <td> 2 </td>
9035           <td> SEV-ES is required when set</td>
9036         </tr>
9037         <tr>
9038           <td> 3 </td>
9039           <td> Sending the guest to another platform is disallowed when set</td>
9040         </tr>
9041         <tr>
9042           <td> 4 </td>
9043           <td> The guest must not be transmitted to another platform that is
9044                not in the domain when set. </td>
9045         </tr>
9046         <tr>
9047           <td> 5 </td>
9048           <td> The guest must not be transmitted to another platform that is
9049                not SEV capable when set. </td>
9050         </tr>
9051         <tr>
9052           <td> 6:15 </td>
9053           <td> reserved </td>
9054         </tr>
9055         <tr>
9056           <td> 16:32 </td>
9057           <td> The guest must not be transmitted to another platform with a
9058                lower firmware version. </td>
9059         </tr>
9060       </table>
9061
9062       </dd>
9063       <dt><code>dhCert</code></dt>
9064       <dd>The optional <code>dhCert</code> element provides the guest owners
9065       base64 encoded Diffie-Hellman (DH) key. The key is used to negotiate a
9066       master secret key between the SEV firmware and guest owner. This master
9067       secret key is then used to establish a trusted channel between SEV
9068       firmware and guest owner.
9069       </dd>
9070       <dt><code>session</code></dt>
9071       <dd>The optional <code>session</code> element provides the guest owners
9072       base64 encoded session blob defined in the SEV API spec.
9073
9074       See SEV spec LAUNCH_START section for the session blob format.
9075       </dd>
9076     </dl>
9077
9078     <h2><a id="examples">Example configs</a></h2>
9079
9080     <p>
9081       Example configurations for each driver are provide on the
9082       driver specific pages listed below
9083     </p>
9084
9085     <ul>
9086       <li><a href="drvxen.html#xmlconfig">Xen examples</a></li>
9087       <li><a href="drvqemu.html#xmlconfig">QEMU/KVM examples</a></li>
9088     </ul>
9089   </body>
9090 </html>