From nobody Mon Feb 9 00:07:31 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) client-ip=207.211.31.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510558; cv=none; d=zohomail.com; s=zohoarc; b=GWrWciZTrY791YxAf1WSDD9S9yVPsHnxa/Yca9uucj4MfD6P+JpcO1ql79PSJRMNbSs/8q1dbX4Lo4f4hsaIFzpqn/rXd7j4QVUYsUGXI3jwH1F6QRlM732EO11EhKrtlaiCkPKmaoT2lw12lhTiiBadiLUzXSD59Ha8Q/p7CMc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510558; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=JsmPQa+VTN5mLjtEtyto9ia8jTGG88HFK7jsT55bcyI=; b=UOnLEmcRJQOpUWYVzqWE8OefQnPUYcOXRfMHkh/l2VYY0VvvDFDXHn+tdQNWBRXW6ydeqe/s8ScIuVCCZCcI6uXMT1tfr5Kure/xXz9y/DEhZ+1VNPS2S1Uypdv20nyMyxO3BhnsqelygqTH+b7xqz0be3jokEasqmqfe0guudE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by mx.zohomail.com with SMTPS id 1595510558101293.8528024044938; Thu, 23 Jul 2020 06:22:38 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-445-6uaHk0YaMqa5ylPxYRCF3Q-1; Thu, 23 Jul 2020 09:22:05 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 2F1F9192FDB6; Thu, 23 Jul 2020 13:21:58 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id EC79171D37; Thu, 23 Jul 2020 13:21:57 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id A238F9A13F; Thu, 23 Jul 2020 13:21:57 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDLtNm028409 for ; Thu, 23 Jul 2020 09:21:55 -0400 Received: by smtp.corp.redhat.com (Postfix) id 7A3D81A91F; Thu, 23 Jul 2020 13:21:55 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7271619D7B for ; Thu, 23 Jul 2020 13:21:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510556; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=JsmPQa+VTN5mLjtEtyto9ia8jTGG88HFK7jsT55bcyI=; b=EHaqQrVkKdeDGAQ0pgV62nH2bVLTwBimx7mGAdax34HDY72uv1l4r6dkTQ8K4kNW+4mWNo pZ2STIJ9kbXyQXvnfLwaFb5Q2mIlST+sGO6sy3IAdBmN8oxNP9gZbjo8vSgRyN7CGMLmZ7 8+ZCWNsuyRY+Bo/6lEJhvL7mXkyUXJs= X-MC-Unique: 6uaHk0YaMqa5ylPxYRCF3Q-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 05/32] docs: formatdomain: Convert to rst Date: Thu, 23 Jul 2020 15:21:10 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" For now just plain conversion to rst. Anchors which existed until now are preserved, but the table of contents now uses the docutils-generated ones. Additionally which was nested in a link () was removed as rst doesn't support nesting of inline markup. Signed-off-by: Peter Krempa --- docs/formatdomain.html.in | 9848 ------------------------------------- docs/formatdomain.rst | 7442 ++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 7443 insertions(+), 9849 deletions(-) delete mode 100644 docs/formatdomain.html.in create mode 100644 docs/formatdomain.rst diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in deleted file mode 100644 index f3a639b972..0000000000 --- a/docs/formatdomain.html.in +++ /dev/null @@ -1,9848 +0,0 @@ - - - - -

Domain XML format

- -
    - -

    - This section describes the XML format used to represent domains, the= re are - variations on the format based on the kind of domains run and the op= tions - used to launch them. For hypervisor specific details consult the - driver docs -

    - - -

    Element and attribute overview

    - -

    - The root element required for all virtual machines is - named domain. It has two attributes, the - type - specifies the hypervisor used for running - the domain. The allowed values are driver specific, but - include "xen", "kvm", "qemu" and "lxc". The - second attribute is id which is a unique - integer identifier for the running guest machine. Inactive - machines have no id value. -

    - - -

    General metadata

    - -
    -<domain type=3D'kvm' id=3D'1'>
-  <name>MyGuest</name>
-  <uuid>4dea22b3-1d52-d8f3-2516-782e98ab3fa0</uuid>
-  <genid>43dc0cf8-809b-4adb-9bea-a9abb5f3d90e</genid>
-  <title>A short description - title - of the domain</title>
-  <description>Some human readable description</description>
-  <metadata>
-    <app1:foo xmlns:app1=3D"http://app1.org/app1/">..</app1:foo&g=
t;
-    <app2:bar xmlns:app2=3D"http://app1.org/app2/">..</app2:bar&g=
t;
-  </metadata>
-  ...
    - -
    -
    name
    -
    The content of the name element provides - a short name for the virtual machine. This name should - consist only of alpha-numeric characters and is required - to be unique within the scope of a single host. It is - often used to form the filename for storing the persistent - configuration file. Since 0.0.1
    -
    uuid
    -
    The content of the uuid element provides - a globally unique identifier for the virtual machine. - The format must be RFC 4122 compliant, - eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b. - If omitted when defining/creating a new machine, a random - UUID is generated. It is also possible to provide the UUID - via a sysinfo - specification. Since 0.0.1, sysinfo - since 0.8.7
    - -
    genid
    -
    Since 4.4.0, the genid - element can be used to add a Virtual Machine Generation ID which - exposes a 128-bit, cryptographically random, integer value identif= ier, - referred to as a Globally Unique Identifier (GUID) using the same - format as the uuid. The value is used to help notify - the guest operating system when the virtual machine is re-executing - something that has already executed before, such as: - -
      -
    • VM starts executing a snapshot
      • -
    • VM is recovered from backup
      • -
    • VM is failover in a disaster recovery environment
      • -
    • VM is imported, copied, or cloned
      • -
    - - The guest operating system notices the change and is then able to - react as appropriate by marking its copies of distributed databases - as dirty, re-initializing its random number generator, etc. - -

    - The libvirt XML parser will accept both a provided GUID value - or just <genid/> in which case a GUID will be generated - and saved in the XML. For the transitions such as above, libvirt - will change the GUID before re-executing.

    - -
    title
    -
    The optional element title provides space for a - short description of the domain. The title should not contain - any newlines. Since 0.9.10.
    - -
    description
    -
    The content of the description element provides a - human readable description of the virtual machine. This data is not - used by libvirt in any way, it can contain any information the user - wants. Since 0.7.2
    - -
    metadata
    -
    The metadata node can be used by applications - to store custom metadata in the form of XML - nodes/trees. Applications must use custom namespaces on their - XML nodes/trees, with only one top-level element per namespace - (if the application needs structure, they should have - sub-elements to their namespace - element). Since 0.9.10
    -
    - -

    Operating system booting

    - -

    - There are a number of different ways to boot virtual machines - each with their own pros and cons. -

    - -

    BIOS bootloader

    - -

    - Booting via the BIOS is available for hypervisors supporting - full virtualization. In this case the BIOS has a boot order - priority (floppy, harddisk, cdrom, network) determining where - to obtain/find the boot image. -

    - -
    -...
-<os firmware=3D'efi'>
-  <type>hvm</type>
-  <loader readonly=3D'yes' secure=3D'no' type=3D'rom'>/usr/lib/xen/b=
oot/hvmloader</loader>
-  <nvram template=3D'/usr/share/OVMF/OVMF_VARS.fd'>/var/lib/libvirt/=
nvram/guest_VARS.fd</nvram>
-  <boot dev=3D'hd'/>
-  <boot dev=3D'cdrom'/>
-  <bootmenu enable=3D'yes' timeout=3D'3000'/>
-  <smbios mode=3D'sysinfo'/>
-  <bios useserial=3D'yes' rebootTimeout=3D'0'/>
-</os>
-...
    - -
    -
    firmware
    -
    The firmware attribute allows management - applications to automatically fill <loader/> - and <nvram/> elements and possibly enable - some features required by selected firmware. Accepted values are - bios and efi.
    - The selection process scans for files describing installed - firmware images in specified location and uses the most specific - one which fulfils domain requirements. The locations in order of - preference (from generic to most specific one) are: -
      -
    • /usr/share/qemu/firmware
      • -
    • /etc/qemu/firmware
      • -
    • $XDG_CONFIG_HOME/qemu/firmware
      • -
    - For more information refer to firmware metadata specification as - described in docs/interop/firmware.json in QEMU - repository. Regular users do not need to bother. - Since 5.2.0 (QEMU and KVM only)
    - For VMware guests, this is set to efi when the guest - uses UEFI, and it is not set when using BIOS. - Since 5.3.0 (VMware ESX and Workstation/Play= er) -
    -
    type
    -
    The content of the type element specifies the - type of operating system to be booted in the virtual machine. - hvm indicates that the OS is one designed to run - on bare metal, so requires full virtualization. linux - (badly named!) refers to an OS that supports the Xen 3 hypervisor - guest ABI. There are also two optional attributes, arch - specifying the CPU architecture to virtualization, - and machine refe= rring - to the machine type. The Capabilities = XML - provides details on allowed values for - these. If arch is omitted then for most hypervisor - drivers, the host native arch will be chosen. For the test, - ESX and VMWare hypervisor drivers, howev= er, - the i686 arch will always be chosen even on an - x86_64 host. Since 0.0.1=
    -
    loader
    -
    The optional loader tag refers to a firmware blob, - which is specified by absolute path, - used to assist the domain creation process. It is used by Xen - fully virtualized domains as well as setting the QEMU BIOS file - path for QEMU/KVM domains. Xen since 0.1.0, - QEMU/KVM since 0.9.12 Then, since - 1.2.8 it's possible for the element to have two - optional attributes: readonly (accepted values are - yes and no) to reflect the fact that the - image should be writable or read-only. The second attribute - type accepts values rom and - pflash. It tells the hypervisor where in the guest - memory the file should be mapped. For instance, if the loader - path points to an UEFI image, type should be - pflash. Moreover, some firmwares may - implement the Secure boot feature. Attribute - secure can be used then to control it. - Since 2.1.0
    -
    nvram
    -
    Some UEFI firmwares may want to use a non-volatile memory to sto= re - some variables. In the host, this is represented as a file and the - absolute path to the file is stored in this element. Moreover, whe= n the - domain is started up libvirt copies so called master NVRAM store f= ile - defined in qemu.conf. If needed, the template - attribute can be used to per domain override map of master NVRAM s= tores - from the config file. Note, that for transient domains if the NVRA= M file - has been created by libvirt it is left behind and it is management - application's responsibility to save and remove file (if needed to= be - persistent). Since 1.2.8
    -
    boot
    -
    The dev attribute takes one of the values "fd", "hd= ", - "cdrom" or "network" and is used to specify the next boot device - to consider. The boot element can be repeated multiple - times to setup a priority list of boot devices to try in turn. - Multiple devices of the same type are sorted according to their - targets while preserving the order of buses. After defining the - domain, its XML configuration returned by libvirt (through - virDomainGetXMLDesc) lists devices in the sorted order. Once sorte= d, - the first device is marked as bootable. Thus, e.g., a domain - configured to boot from "hd" with vdb, hda, vda, and hdc disks - assigned to it will boot from vda (the sorted list is vda, vdb, hd= a, - hdc). Similar domain with hdc, vda, vdb, and hda disks will boot f= rom - hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to - configure in the desired way, which is why per-device boot elements - (see disks, - network interfaces, and - USB and PCI devices sections belo= w) were - introduced and they are the preferred way providing full control o= ver - booting order. The boot element and per-device boot - elements are mutually exclusive. Since 0.1.3, - per-device boot since 0.8.8 -
    -
    smbios
    -
    How to populate SMBIOS information visible in the guest. - The mode attribute must be specified, and is either - "emulate" (let the hypervisor generate all values), "host" (copy - all of Block 0 and Block 1, except for the UUID, from the host's - SMBIOS values; - the - virConnectGetSysinfo call can be - used to see what values are copied), or "sysinfo" (use the values = in - the sysinfo element). If not - specified, the hypervisor default is used. - Since 0.8.7 -
    -
    -

    Up till here the BIOS/UEFI configuration knobs are generic enough= to - be implemented by majority (if not all) firmwares out there. However, - from now on not every single setting makes sense to all firmwares. F= or - instance, rebootTimeout doesn't make sense for UEFI, - useserial might not be usable with a BIOS firmware that - doesn't produce any output onto serial line, etc. Moreover, firmwares - don't usually export their capabilities for libvirt (or users) to ch= eck. - And the set of their capabilities can change with every new release. - Hence users are advised to try the settings they use before relying = on - them in production.

    -
    -
    bootmenu
    -
    Whether or not to enable an interactive boot menu prompt on gue= st - startup. The enable attribute can be either "yes" or "n= o". - If not specified, the hypervisor default is used. - Since 0.8.3 - Additional attribute timeout takes the number of millis= econds - the boot menu should wait until it times out. Allowed values are nu= mbers - in range [0, 65535] inclusive and it is ignored unless enable<= /code> - is set to "yes". Since 1.2.8 -
    -
    bios
    -
    This element has attribute useserial with possible - values yes or no. It enables or disables - Serial Graphics Adapter which allows users to see BIOS messages - on a serial port. Therefore, one needs to have - serial port defined. - Since 0.9.4. - Since 0.10.2 (QEMU only) there is - another attribute, rebootTimeout that controls - whether and after how long the guest should start booting - again in case the boot fails (according to BIOS). The value is - in milliseconds with maximum of 65535 and special - value -1 disables the reboot. -
    -
    - -

    Host bootloader

    - -

    - Hypervisors employing paravirtualization do not usually emulate - a BIOS, and instead the host is responsible to kicking off the - operating system boot. This may use a pseudo-bootloader in the - host to provide an interface to choose a kernel for the guest. - An example is pygrub with Xen. The Bhyve hypervisor - also uses a host bootloader, either bhyveload or - grub-bhyve. -

    - -
    -...
-<bootloader>/usr/bin/pygrub</bootloader>
-<bootloader_args>--append single</bootloader_args>
-...
    - -
    -
    bootloader
    -
    The content of the bootloader element provides - a fully qualified path to the bootloader executable in the - host OS. This bootloader will be run to choose which kernel - to boot. The required output of the bootloader is dependent - on the hypervisor in use. Since 0.1.0=
    -
    bootloader_args
    -
    The optional bootloader_args element allows - command line arguments to be passed to the bootloader. - Since 0.2.3 -
    - -
    - -

    Direct kernel boot

    - -

    - When installing a new guest OS it is often useful to boot directly - from a kernel and initrd stored in the host OS, allowing command - line arguments to be passed directly to the installer. This capabili= ty - is usually available for both para and full virtualized guests. -

    - -
    -...
-<os>
-  <type>hvm</type>
-  <loader>/usr/lib/xen/boot/hvmloader</loader>
-  <kernel>/root/f8-i386-vmlinuz</kernel>
-  <initrd>/root/f8-i386-initrd</initrd>
-  <cmdline>console=3DttyS0 ks=3Dhttp://example.com/f8-i386/os/</c=
mdline>
-  <dtb>/root/ppc.dtb</dtb>
-  <acpi>
-    <table type=3D'slic'>/path/to/slic.dat</table>
-  </acpi>
-</os>
-...
    - -
    -
    type
    -
    This element has the same semantics as described earlier in the - BIOS boot section
    -
    loader
    -
    This element has the same semantics as described earlier in the - BIOS boot section
    -
    kernel
    -
    The contents of this element specify the fully-qualified path - to the kernel image in the host OS.
    -
    initrd
    -
    The contents of this element specify the fully-qualified path - to the (optional) ramdisk image in the host OS.
    -
    cmdline
    -
    The contents of this element specify arguments to be passed to - the kernel (or installer) at boot time. This is often used to - specify an alternate primary console (eg serial port), or the - installation media source / kickstart file
    -
    dtb
    -
    The contents of this element specify the fully-qualified path - to the (optional) device tree binary (dtb) image in the host OS. - Since 1.0.4
    -
    acpi
    -
    The table element contains a fully-qualified path - to the ACPI table. The type attribute contains the - ACPI table type (currently only slic is supported) - Since 1.3.5 (QEMU) - Since 5.9.0 (Xen)
    -
    - -

    Container boot

    - -

    - When booting a domain using container based virtualization, instead - of a kernel / boot image, a path to the init binary is required, usi= ng - the init element. By default this will be launched with - no arguments. To specify the initial argv, use the initarg - element, repeated as many time as is required. The cmdline - element, if set will be used to provide an equivalent to /proc= /cmdline - but will not affect init argv. -

    -

    - To set environment variables, use the initenv element, = one - for each variable. -

    -

    - To set a custom work directory for the init, use the initdir - element. -

    -

    - To run the init command as a given user or group, use the init= user - or initgroup elements respectively. Both elements can b= e provided - either a user (resp. group) id or a name. Prefixing the user or grou= p id with - a + will force it to be considered like a numeric value= . Without - this, it will be first tried as a user or group name. -

    - - 
    -<os>
-  <type arch=3D'x86_64'>exe</type>
-  <init>/bin/systemd</init>
-  <initarg>--unit</initarg>
-  <initarg>emergency.service</initarg>
-  <initenv name=3D'MYENV'>some value</initenv>
-  <initdir>/my/custom/cwd</initdir>
-  <inituser>tester</inituser>
-  <initgroup>1000</initgroup>
-</os>
-
    - - -

    - If you want to enable user namespace, set the idmap ele= ment. - The uid and gid elements have three attrib= utes: -

    - -
    -
    start
    -
    First user ID in container. It must be '0'.
    -
    target
    -
    The first user ID in container will be mapped to this target user - ID in host.
    -
    count
    -
    How many users in container are allowed to map to host's user. -
    - - 
    -<idmap>
-  <uid start=3D'0' target=3D'1000' count=3D'10'/>
-  <gid start=3D'0' target=3D'1000' count=3D'10'/>
-</idmap>
-
    - - -

    SMBIOS System Information

    - -

    - Some hypervisors allow control over what system information is - presented to the guest (for example, SMBIOS fields can be - populated by a hypervisor and inspected via - the dmidecode command in the guest). The - optional sysinfo element covers all such categories - of information. Since 0.8.7 -

    - -
    -...
-<os>
-  <smbios mode=3D'sysinfo'/>
-  ...
-</os>
-<sysinfo type=3D'smbios'>
-  <bios>
-    <entry name=3D'vendor'>LENOVO</entry>
-  </bios>
-  <system>
-    <entry name=3D'manufacturer'>Fedora</entry>
-    <entry name=3D'product'>Virt-Manager</entry>
-    <entry name=3D'version'>0.9.4</entry>
-  </system>
-  <baseBoard>
-    <entry name=3D'manufacturer'>LENOVO</entry>
-    <entry name=3D'product'>20BE0061MC</entry>
-    <entry name=3D'version'>0B98401 Pro</entry>
-    <entry name=3D'serial'>W1KS427111E</entry>
-  </baseBoard>
-  <chassis>
-    <entry name=3D'manufacturer'>Dell Inc.</entry>
-    <entry name=3D'version'>2.12</entry>
-    <entry name=3D'serial'>65X0XF2</entry>
-    <entry name=3D'asset'>40000101</entry>
-    <entry name=3D'sku'>Type3Sku1</entry>
-  </chassis>
-  <oemStrings>
-    <entry>myappname:some arbitrary data</entry>
-    <entry>otherappname:more arbitrary data</entry>
-  </oemStrings>
-</sysinfo>
-<sysinfo type=3D'fwcfg'>
-  <entry name=3D'opt/com.example/name'>example value</entry>
-  <entry name=3D'opt/com.coreos/config' file=3D'/tmp/provision.ign'/>
-</sysinfo>
-...
    - -

    - The sysinfo element has a mandatory - attribute type that determine the layout of - sub-elements, with supported values of: -

    - -
    -
    smbios
    -
    Sub-elements call out specific SMBIOS values, which will - affect the guest if used in conjunction with - the smbios sub-element of - the os element. Each - sub-element of sysinfo names a SMBIOS block, and - within those elements can be a list of entry - elements that describe a field within the block. The following - blocks and entries are recognized: -
    -
    bios
    -
    - This is block 0 of SMBIOS, with entry names drawn from: -
    -
    vendor
    -
    BIOS Vendor's Name
    -
    version
    -
    BIOS Version
    -
    date
    -
    BIOS release date. If supplied, is in either mm/dd/yy or - mm/dd/yyyy format. If the year portion of the string is - two digits, the year is assumed to be 19yy.
    -
    release
    -
    System BIOS Major and Minor release number values - concatenated together as one string separated by - a period, for example, 10.22.
    -
    -
    -
    system
    -
    - This is block 1 of SMBIOS, with entry names drawn from: -
    -
    manufacturer
    -
    Manufacturer of BIOS
    -
    product
    -
    Product Name
    -
    version
    -
    Version of the product
    -
    serial
    -
    Serial number
    -
    uuid
    -
    Universal Unique ID number. If this entry is provided - alongside a top-level - uuid elemen= t, - then the two values must match.
    -
    sku
    -
    SKU number to identify a particular configuration.
    -
    family
    -
    Identify the family a particular computer belongs to.<= /dd> -
    -
    -
    baseBoard
    -
    - This is block 2 of SMBIOS. This element can be repeated multip= le - times to describe all the base boards; however, not all - hypervisors necessarily support the repetition. The element can - have the following children: -
    -
    manufacturer
    -
    Manufacturer of BIOS
    -
    product
    -
    Product Name
    -
    version
    -
    Version of the product
    -
    serial
    -
    Serial number
    -
    asset
    -
    Asset tag
    -
    location
    -
    Location in chassis
    -
    - NB: Incorrectly supplied entries for the - bios, system or baseBoard - blocks will be ignored without error. Other than uuid - validation and date format checking, all values a= re - passed as strings to the hypervisor driver. -
    -
    chassis
    -
    - Since 4.1.0, this is block 3 of - SMBIOS, with entry names drawn from: -
    -
    manufacturer
    -
    Manufacturer of Chassis
    -
    version
    -
    Version of the Chassis
    -
    serial
    -
    Serial number
    -
    asset
    -
    Asset tag
    -
    sku
    -
    SKU number
    -
    -
    -
    oemStrings
    -
    - This is block 11 of SMBIOS. This element should appear once and - can have multiple entry child elements, each prov= iding - arbitrary string data. There are no restrictions on what data = can - be provided in the entries, however, if the data is intended t= o be - consumed by an application in the guest, it is recommended to = use - the application name as a prefix in the string. (Since 4.1.0) -
    -
    -
    - -
    fwcfg
    -
    - Some hypervisors provide unified way to tweak how firmware configur= es - itself, or may contain tables to be installed for the guest OS, for - instance boot order, ACPI, SMBIOS, etc. It even allows users to def= ine - their own config blobs. In case of QEMU, these then appear under do= main's - sysfs, under /sys/firmware/qemu_fw_cfg. Note, that the= se - values apply regardless the <smbios/> mode under <os/>. - Since 6.5.0 - -
    -  <smbios type=3D'fwcfg'>
-    <entry name=3D'opt/com.example/name'>example value</entry>
-    <entry name=3D'opt/com.coreos/config' file=3D'/tmp/provision.ign'/&=
gt;
-  </smbios>
-
    - - The smbios element can have multiple entry - child elements. Each element then has mandatory name - attribute, which defines the name of the blob and must begin with - "opt/" and to avoid clashing with other names is advis= ed to - be in form "opt/$RFQDN/$name" where $RFQDN is a - reverse fully qualified domain name you control. - Then, the element can either contain the value (to set the blob val= ue - directly), or file attribute (to set the blob value fr= om - the file). -
    -
    - -

    CPU Allocation

    - -
    -<domain>
-  ...
-  <vcpu placement=3D'static' cpuset=3D"1-4,^3,6" current=3D"1">2<=
/vcpu>
-  <vcpus>
-    <vcpu id=3D'0' enabled=3D'yes' hotpluggable=3D'no' order=3D'1'/>
-    <vcpu id=3D'1' enabled=3D'no' hotpluggable=3D'yes'/>
-  </vcpus>
-  ...
-</domain>
-
    - -
    -
    vcpu
    -
    The content of this element defines the maximum number of virtual - CPUs allocated for the guest OS, which must be between 1 and - the maximum supported by the hypervisor. -
    -
    cpuset
    -
    - The optional attribute cpuset is a comma-separated - list of physical CPU numbers that domain process and virtual CP= Us - can be pinned to by default. (NB: The pinning policy of domain - process and virtual CPUs can be specified separately by - cputune. If the attribute emulatorpin - of cputune is specified, the cpuset - specified by vcpu here will be ignored. Similarly, - for virtual CPUs which have the vcpupin specified, - the cpuset specified by cpuset here - will be ignored. For virtual CPUs which don't have - vcpupin specified, each will be pinned to the phys= ical - CPUs specified by cpuset here). - Each element in that list is either a single CPU number, - a range of CPU numbers, or a caret followed by a CPU number to - be excluded from a previous range. - Since 0.4.4 -
    -
    current
    -
    - The optional attribute current can - be used to specify whether fewer than the maximum number of - virtual CPUs should be enabled. - Since 0.8.5 -
    -
    placement
    -
    - The optional attribute placement can be used to - indicate the CPU placement mode for domain process. The value c= an - be either "static" or "auto", but defaults to placement - of numatune or "static" if cpuset is - specified. Using "auto" indicates the domain process will be pi= nned - to the advisory nodeset from querying numad and the value of - attribute cpuset will be ignored if it's specified. - If both cpuset and placement are not - specified or if placement is "static", but no - cpuset is specified, the domain process will be - pinned to all the available physical CPUs. - Since 0.9.11 (QEMU and KVM only) -
    -
    -
    -
    vcpus
    -
    - The vcpus element allows to control state of individual vCPUs. - - The id attribute specifies the vCPU id as used by lib= virt - in other places such as vCPU pinning, scheduler information and NU= MA - assignment. Note that the vCPU ID as seen in the guest may differ = from - libvirt ID in certain cases. Valid IDs are from 0 to the maximum v= CPU - count as set by the vcpu element minus 1. - - The enabled attribute allows to control the state of = the - vCPU. Valid values are yes and no. - - hotpluggable controls whether given vCPU can be hotpl= ugged - and hotunplugged in cases when the CPU is enabled at boot. Note th= at - all disabled vCPUs must be hotpluggable. Valid values are - yes and no. - - order allows to specify the order to add the online v= CPUs. - For hypervisors/platforms that require to insert multiple vCPUs at= once - the order may be duplicated across all vCPUs that need to be - enabled at once. Specifying order is not necessary, vCPUs are then - added in an arbitrary order. If order info is used, it must be use= d for - all online vCPUs. Hypervisors may clear or update ordering informa= tion - during certain operations to assure valid configuration. - - Note that hypervisors may create hotpluggable vCPUs differently fr= om - boot vCPUs thus special initialization may be necessary. - - Hypervisors may require that vCPUs enabled on boot which are not - hotpluggable are clustered at the beginning starting with ID 0. It= may - be also required that vCPU 0 is always present and non-hotpluggabl= e. - - Note that providing state for individual CPUs may be necessary to = enable - support of addressable vCPU hotplug and this feature may not be - supported by all hypervisors. - - For QEMU the following conditions are required. vCPU 0 needs to be - enabled and non-hotpluggable. On PPC64 along with it vCPUs that ar= e in - the same core need to be enabled as well. All non-hotpluggable CPUs - present at boot need to be grouped after vCPU 0. - Since 2.2.0 (QEMU only) -
    -
    - -

    IOThreads Allocation

    -

    - IOThreads are dedicated event loop threads for supported disk - devices to perform block I/O requests in order to improve - scalability especially on an SMP host/guest with many LUNs. - Since 1.2.8 (QEMU only) -

    - -
    -<domain>
-  ...
-  <iothreads>4</iothreads>
-  ...
-</domain>
-
    -
    -<domain>
-  ...
-  <iothreadids>
-    <iothread id=3D"2"/>
-    <iothread id=3D"4"/>
-    <iothread id=3D"6"/>
-    <iothread id=3D"8"/>
-  </iothreadids>
-  ...
-</domain>
-
    - -
    -
    iothreads
    -
    - The content of this optional element defines the number - of IOThreads to be assigned to the domain for use by - supported target storage devices. There - should be only 1 or 2 IOThreads per host CPU. There may be more - than one supported device assigned to each IOThread. - Since 1.2.8 -
    -
    iothreadids
    -
    - The optional iothreadids element provides the capabil= ity - to specifically define the IOThread ID's for the domain. By defau= lt, - IOThread ID's are sequentially numbered starting from 1 through the - number of iothreads defined for the domain. The - id attribute is used to define the IOThread ID. The - id attribute must be a positive integer greater than = 0. - If there are less iothreadids defined than - iothreads defined for the domain, then libvirt will - sequentially fill iothreadids starting at 1 avoiding - any predefined id. If there are more - iothreadids defined than iothreads - defined for the domain, then the iothreads value - will be adjusted accordingly. - Since 1.2.15 -
    -
    - -

    CPU Tuning

    - -
    -<domain>
-  ...
-  <cputune>
-    <vcpupin vcpu=3D"0" cpuset=3D"1-4,^2"/>
-    <vcpupin vcpu=3D"1" cpuset=3D"0,1"/>
-    <vcpupin vcpu=3D"2" cpuset=3D"2,3"/>
-    <vcpupin vcpu=3D"3" cpuset=3D"0,4"/>
-    <emulatorpin cpuset=3D"1-3"/>
-    <iothreadpin iothread=3D"1" cpuset=3D"5,6"/>
-    <iothreadpin iothread=3D"2" cpuset=3D"7,8"/>
-    <shares>2048</shares>
-    <period>1000000</period>
-    <quota>-1</quota>
-    <global_period>1000000</global_period>
-    <global_quota>-1</global_quota>
-    <emulator_period>1000000</emulator_period>
-    <emulator_quota>-1</emulator_quota>
-    <iothread_period>1000000</iothread_period>
-    <iothread_quota>-1</iothread_quota>
-    <vcpusched vcpus=3D'0-4,^3' scheduler=3D'fifo' priority=3D'1'/>
-    <iothreadsched iothreads=3D'2' scheduler=3D'batch'/>
-    <cachetune vcpus=3D'0-3'>
-      <cache id=3D'0' level=3D'3' type=3D'both' size=3D'3' unit=3D'MiB'=
/>
-      <cache id=3D'1' level=3D'3' type=3D'both' size=3D'3' unit=3D'MiB'=
/>
-      <monitor level=3D'3' vcpus=3D'1'/>
-      <monitor level=3D'3' vcpus=3D'0-3'/>
-    </cachetune>
-    <cachetune vcpus=3D'4-5'>
-      <monitor level=3D'3' vcpus=3D'4'/>
-      <monitor level=3D'3' vcpus=3D'5'/>
-    </cachetune>
-    <memorytune vcpus=3D'0-3'>
-      <node id=3D'0' bandwidth=3D'60'/>
-    </memorytune>
-
-  </cputune>
-  ...
-</domain>
-
    - -
    -
    cputune
    -
    - The optional cputune element provides details - regarding the CPU tunable parameters for the domain. - Note: for the qemu driver, the optional vcpupin - and emulatorpin pinning settings are honored after - the emulator is launched and NUMA constraints considered. This - means that it is expected that other physical CPUs of the host - will be used during this time by the domain, which will be - reflected by the output of virsh cpu-stats. - Since 0.9.0 -
    -
    vcpupin
    -
    - The optional vcpupin element specifies which of host's - physical CPUs the domain vCPU will be pinned to. If this is omitte= d, - and attribute cpuset of element vcpu is - not specified, the vCPU is pinned to all the physical CPUs by defa= ult. - It contains two required attributes, the attribute vcpu - specifies vCPU id, and the attribute cpuset is same as - attribute cpuset of element vcpu. - (NB: Only qemu driver support) - Since 0.9.0 -
    -
    emulatorpin
    -
    - The optional emulatorpin element specifies which of = host - physical CPUs the "emulator", a subset of a domain not including = vCPU - or iothreads will be pinned to. If this is omitted, and attribute - cpuset of element vcpu is not specified, - "emulator" is pinned to all the physical CPUs by default. It cont= ains - one required attribute cpuset specifying which physi= cal - CPUs to pin to. -
    -
    iothreadpin
    -
    - The optional iothreadpin element specifies which of = host - physical CPUs the IOThreads will be pinned to. If this is omitted - and attribute cpuset of element vcpu is - not specified, the IOThreads are pinned to all the physical CPUs - by default. There are two required attributes, the attribute - iothread specifies the IOThread ID and the attribute - cpuset specifying which physical CPUs to pin to. See - the iothreadids - description= - for valid iothread values. - Since 1.2.9 -
    -
    shares
    -
    - The optional shares element specifies the proportional - weighted share for the domain. If this is omitted, it defaults to - the OS provided defaults. NB, There is no unit for the value, - it's a relative measure based on the setting of other VM, - e.g. A VM configured with value - 2048 will get twice as much CPU time as a VM configured with value= 1024. - Since 0.9.0 -
    -
    period
    -
    - The optional period element specifies the enforcement - interval (unit: microseconds). Within period, each vC= PU of - the domain will not be allowed to consume more than quota - worth of runtime. The value should be in range [1000, 1000000]. A = period - with value 0 means no value. - Only QEMU driver support since 0.9.4, LXC si= nce - 0.9.10 -
    -
    quota
    -
    - The optional quota element specifies the maximum allo= wed - bandwidth (unit: microseconds). A domain with quota a= s any - negative value indicates that the domain has infinite bandwidth for - vCPU threads, which means that it is not bandwidth controlled. The= value - should be in range [1000, 18446744073709551] or less than 0. A quo= ta - with value 0 means no value. You can use this feature to ensure th= at all - vCPUs run at the same speed. - Only QEMU driver support since 0.9.4, LXC si= nce - 0.9.10 -
    -
    global_period
    -
    - The optional global_period element specifies the - enforcement CFS scheduler interval (unit: microseconds) for the wh= ole - domain in contrast with period which enforces the int= erval - per vCPU. The value should be in range 1000, 1000000]. A - global_period with value 0 means no value. - Only QEMU driver support since 1.3.3 -
    -
    global_quota
    -
    - The optional global_quota element specifies the maxim= um - allowed bandwidth (unit: microseconds) within a period for the who= le - domain. A domain with global_quota as any negative - value indicates that the domain has infinite bandwidth, which mean= s that - it is not bandwidth controlled. The value should be in range - [1000, 18446744073709551] or less than 0. A global_quota - with value 0 means no value. - Only QEMU driver support since 1.3.3 -
    - -
    emulator_period
    -
    - The optional emulator_period element specifies the en= forcement - interval (unit: microseconds). Within emulator_period= , emulator - threads (those excluding vCPUs) of the domain will not be allowed = to consume - more than emulator_quota worth of runtime. The value = should be - in range [1000, 1000000]. A period with value 0 means no value. - Only QEMU driver support since 0.10.0 -
    -
    emulator_quota
    -
    - The optional emulator_quota element specifies the max= imum - allowed bandwidth (unit: microseconds) for domain's emulator threa= ds (those - excluding vCPUs). A domain with emulator_quota as any= negative - value indicates that the domain has infinite bandwidth for emulato= r threads - (those excluding vCPUs), which means that it is not bandwidth cont= rolled. - The value should be in range [1000, 18446744073709551] or less tha= n 0. A - quota with value 0 means no value. - Only QEMU driver support since 0.10.0 -
    - -
    iothread_period
    -
    - The optional iothread_period element specifies the - enforcement interval (unit: microseconds) for IOThreads. Within - iothread_period, each IOThread of the domain will - not be allowed to consume more than iothread_quota - worth of runtime. The value should be in range [1000, 1000000]. - An iothread_period with value 0 means no value. - Only QEMU driver support since 2.1.0 -
    -
    iothread_quota
    -
    - The optional iothread_quota element specifies the max= imum - allowed bandwidth (unit: microseconds) for IOThreads. A domain with - iothread_quota as any negative value indicates that t= he - domain IOThreads have infinite bandwidth, which means that it is - not bandwidth controlled. The value should be in range - [1000, 18446744073709551] or less than 0. An iothread_quota<= /code> - with value 0 means no value. You can use this feature to ensure th= at - all IOThreads run at the same speed. - Only QEMU driver support since 2.1.0 -
    - -
    vcpusched, iothreadsched - and emulatorsched
    -
    - The optional - vcpusched, iothreadsched - and emulatorsched elements specify the scheduler type - (values batch, idle, fifo, - rr) for particular vCPU, IOThread and emulator threads - respecively. For vcpusched and iothreadsched - the attributes vcpus and iothreads select - which vCPUs/IOThreads this setting applies to, leaving them out se= ts the - default. The element emulatorsched does not have that - attribute. Valid vcpus values start at 0 through one = less - than the number of vCPU's defined for the - domain. Valid iothreads values are described in - the iothreadids - description<= /a>. - If no iothreadids are defined, then libvirt numbers - IOThreads from 1 to the number of iothreads available - for the domain. For real-time schedulers (fifo, - rr), priority must be specified as - well (and is ignored for non-real-time ones). The value range - for the priority depends on the host kernel (usually 1-99). - Since 1.2.13 - emulatorsched since 5.3.0 -
    - -
    cachetuneSince 4.1.0 -
    - Optional cachetune element can control allocations fo= r CPU - caches using the resctrl on the host. Whether or not is this suppo= rted - can be gathered from capabilities where some limitations like mini= mum - size and required granularity are reported as well. The required - attribute vcpus specifies to which vCPUs this allocat= ion - applies. A vCPU can only be member of one cachetune e= lement - allocation. The vCPUs specified by cachetune can be identical with= those - in memorytune, however they are not allowed to overlap. - Supported subelements are: -
    -
    cache
    -
    - This optional element controls the allocation of CPU cache and= has - the following attributes: -
    -
    level
    -
    - Host cache level from which to allocate. -
    -
    id
    -
    - Host cache id from which to allocate. -
    -
    type
    -
    - Type of allocation. Can be code for code - (instructions), data for data or both - for both code and data (unified). Currently the allocation= can - be done only with the same type as the host supports, mean= ing - you cannot request both for host with CDP - (code/data prioritization) enabled. -
    -
    size
    -
    - The size of the region to allocate. The value by default i= s in - bytes, but the unit attribute can be used to = scale - the value. -
    -
    unit (optional)
    -
    - If specified it is the unit such as KiB, MiB, GiB, or TiB - (described in the memory element - for Memory Allocatio= n) - in which size is specified, defaults to bytes. -
    -
    -
    -
    monitorSince 4.10.0
    -
    - The optional element monitor creates the cache - monitor(s) for current cache allocation and has the following - required attributes: -
    -
    level
    -
    - Host cache level the monitor belongs to. -
    -
    vcpus
    -
    - vCPU list the monitor applies to. A monitor's vCPU list - can only be the member(s) of the vCPU list of the associat= ed - allocation. The default monitor has the same vCPU list as = the - associated allocation. For non-default monitors, overlappi= ng - vCPUs are not permitted. -
    -
    -
    -
    -
    - -
    memorytuneSince 4.7.0<= /dt> -
    - Optional memorytune element can control allocations f= or - memory bandwidth using the resctrl on the host. Whether or not is = this - supported can be gathered from capabilities where some limitations= like - minimum bandwidth and required granularity are reported as well. T= he - required attribute vcpus specifies to which vCPUs this - allocation applies. A vCPU can only be member of one - memorytune element allocation. The vcpus= specified - by memorytune can be identical to those specified by - cachetune. However they are not allowed to overlap ea= ch other. - Supported subelements are: -
    -
    node
    -
    - This element controls the allocation of CPU memory bandwidth a= nd has the - following attributes: -
    -
    id
    -
    - Host node id from which to allocate memory bandwidth. -
    -
    bandwidth
    -
    - The memory bandwidth to allocate from this node. The value= by default - is in percentage. -
    -
    -
    -
    -
    -
    - - -

    Memory Allocation

    - -
    -<domain>
-  ...
-  <maxMemory slots=3D'16' unit=3D'KiB'>1524288</maxMemory>
-  <memory unit=3D'KiB'>524288</memory>
-  <currentMemory unit=3D'KiB'>524288</currentMemory>
-  ...
-</domain>
-
    - -
    -
    memory
    -
    The maximum allocation of memory for the guest at boot time. The - memory allocation includes possible additional memory devices spec= ified - at start or hotplugged later. - The units for this value are determined by the optional - attribute unit, which defaults to "KiB" - (kibibytes, 210 or blocks of 1024 bytes). Valid - units are "b" or "bytes" for bytes, "KB" for kilobytes - (103 or 1,000 bytes), "k" or "KiB" for kibibytes - (1024 bytes), "MB" for megabytes (106 or 1,000,000 - bytes), "M" or "MiB" for mebibytes (220 or - 1,048,576 bytes), "GB" for gigabytes (109 or - 1,000,000,000 bytes), "G" or "GiB" for gibibytes - (230 or 1,073,741,824 bytes), "TB" for terabytes - (1012 or 1,000,000,000,000 bytes), or "T" or "TiB" - for tebibytes (240 or 1,099,511,627,776 bytes). - However, the value will be rounded up to the nearest kibibyte - by libvirt, and may be further rounded to the granularity - supported by the hypervisor. Some hypervisors also enforce a - minimum, such as 4000KiB. - - In case NUMA is configured for the gu= est the - memory element can be omitted. - - In the case of crash, optional attribute dumpCore - can be used to control whether the guest memory should be - included in the generated coredump or not (values "on", "off"). - - unit since 0.9.11, - dumpCore since 0.10.2 - (QEMU only)
    -
    maxMemory
    -
    The run time maximum memory allocation of the guest. The initial - memory specified by either the <memory> element= or - the NUMA cell size configuration can be increased by hot-plugging = of - memory to the limit specified by this element. - - The unit attribute behaves the same as for - <memory>. - - The slots attribute specifies the number of slots - available for adding memory to the guest. The bounds are hypervisor - specific. - - Note that due to alignment of the memory chunks added via memory - hotplug the full size allocation specified by this element may be - impossible to achieve. - Since 1.2.14 supported by the QEMU driver. -
    - -
    currentMemory
    -
    The actual allocation of memory for the guest. This value can - be less than the maximum allocation, to allow for ballooning - up the guests memory on the fly. If this is omitted, it defaults - to the same value as the memory element. - The unit attribute behaves the same as - for memory.
    -
    - - -

    Memory Backing

    - -
    -<domain>
-  ...
-  <memoryBacking>
-    <hugepages>
-      <page size=3D"1" unit=3D"G" nodeset=3D"0-3,5"/>
-      <page size=3D"2" unit=3D"M" nodeset=3D"4"/>
-    </hugepages>
-    <nosharepages/>
-    <locked/>
-    <source type=3D"file|anonymous|memfd"/>
-    <access mode=3D"shared|private"/>
-    <allocation mode=3D"immediate|ondemand"/>
-    <discard/>
-  </memoryBacking>
-  ...
-</domain>
-
    - -

    The optional memoryBacking element may contain several - elements that influence how virtual memory pages are backed by host - pages.

    - -
    -
    hugepages
    -
    This tells the hypervisor that the guest should have its memory - allocated using hugepages instead of the normal native page size. - Since 1.2.5 it's possible to set hugepa= ges - more specifically per numa node. The page element is - introduced. It has one compulsory attribute size which - specifies which hugepages should be used (especially useful on syste= ms - supporting hugepages of different sizes). The default unit for the - size attribute is kilobytes (multiplier of 1024). If you - want to use different unit, use optional unit attribute. - For systems with NUMA, the optional nodeset attribute m= ay - come handy as it ties given guest's NUMA nodes to certain hugepage - sizes. From the example snippet, one gigabyte hugepages are used for - every NUMA node except node number four. For the correct syntax see - this.
    -
    nosharepages
    -
    Instructs hypervisor to disable shared pages (memory merge, KSM)= for - this domain. Since 1.0.6
    -
    locked
    -
    When set and supported by the hypervisor, memory pages belonging - to the domain will be locked in host's memory and the host will not - be allowed to swap them out, which might be required for some - workloads such as real-time. For QEMU/KVM guests, the memory used = by - the QEMU process itself will be locked too: unlike guest memory, t= his - is an amount libvirt has no way of figuring out in advance, so it = has - to remove the limit on locked memory altogether. Thus, enabling th= is - option opens up to a potential security risk: the host will be una= ble - to reclaim the locked memory back from the guest when it's running= out - of memory, which means a malicious guest allocating large amounts = of - locked memory could cause a denial-of-service attack on the host. - Because of this, using this option is discouraged unless your work= load - demands it; even then, it's highly recommended to set a - hard_limit (see - memory tuning) on memory all= ocation - suitable for the specific environment at the same time to mitigate - the risks described above. Since 1.0.6
    -
    source
    -
    Using the type attribute, it's possible to - provide "file" to utilize file memorybacking or keep the - default "anonymous". Since 4.10.0, - you may choose "memfd" backing. (QEMU/KVM only)
    -
    access
    -
    Using the mode attribute, specify if the memory is - to be "shared" or "private". This can be overridden per numa node= by - memAccess.
    -
    allocation
    -
    Using the mode attribute, specify when to allocate - the memory by supplying either "immediate" or "ondemand".
    -
    discard
    -
    When set and supported by hypervisor the memory - content is discarded just before guest shuts down (or - when DIMM module is unplugged). Please note that this is - just an optimization and is not guaranteed to work in - all cases (e.g. when hypervisor crashes). - Since 4.4.0 (QEMU/KVM only) -
    -
    - - -

    Memory Tuning

    - -
    -<domain>
-  ...
-  <memtune>
-    <hard_limit unit=3D'G'>1</hard_limit>
-    <soft_limit unit=3D'M'>128</soft_limit>
-    <swap_hard_limit unit=3D'G'>2</swap_hard_limit>
-    <min_guarantee unit=3D'bytes'>67108864</min_guarantee>
-  </memtune>
-  ...
-</domain>
-
    - -
    -
    memtune
    -
    The optional memtune element provides details - regarding the memory tunable parameters for the domain. If this is - omitted, it defaults to the OS provided defaults. For QEMU/KVM, the - parameters are applied to the QEMU process as a whole. Thus, when - counting them, one needs to add up guest RAM, guest video RAM, and - some memory overhead of QEMU itself. The last piece is hard to - determine so one needs guess and try. For each tunable, it - is possible to designate which unit the number is in on - input, using the same values as - for <memory>. For backwards - compatibility, output is always in - KiB. unit - since 0.9.11 - Possible values for all *_limit parameters are in range from 0 to - VIR_DOMAIN_MEMORY_PARAM_UNLIMITED.
    -
    hard_limit
    -
    The optional hard_limit element is the maximum mem= ory - the guest can use. The units for this value are kibibytes (i.e. bl= ocks - of 1024 bytes). Users of QEMU and KVM are strongly advised not to = set - this limit as domain may get killed by the kernel if the guess is = too - low, and determining the memory needed for a process to run is an - - undecidable problem; that said, if you already set - locked in - memory backing because your - workload demands it, you'll have to take into account the specific= s of - your deployment and figure out a value for hard_limit= that - is large enough to support the memory requirements of your guest, = but - small enough to protect your host against a malicious guest lockin= g all - memory.
    -
    soft_limit
    -
    The optional soft_limit element is the memory limi= t to - enforce during memory contention. The units for this value are - kibibytes (i.e. blocks of 1024 bytes)
    -
    swap_hard_limit
    -
    The optional swap_hard_limit element is the maximum - memory plus swap the guest can use. The units for this value are - kibibytes (i.e. blocks of 1024 bytes). This has to be more than - hard_limit value provided
    -
    min_guarantee
    -
    The optional min_guarantee element is the guarante= ed - minimum memory allocation for the guest. The units for this value = are - kibibytes (i.e. blocks of 1024 bytes). This element is only suppor= ted - by VMware ESX and OpenVZ drivers.
    -
    - - -

    NUMA Node Tuning

    - -
    -<domain>
-  ...
-  <numatune>
-    <memory mode=3D"strict" nodeset=3D"1-4,^3"/>
-    <memnode cellid=3D"0" mode=3D"strict" nodeset=3D"1"/>
-    <memnode cellid=3D"2" mode=3D"preferred" nodeset=3D"2"/>
-  </numatune>
-  ...
-</domain>
-
    - -
    -
    numatune
    -
    - The optional numatune element provides details of - how to tune the performance of a NUMA host via controlling NUMA po= licy - for domain process. NB, only supported by QEMU driver. - Since 0.9.3 -
    -
    memory
    -
    - The optional memory element specifies how to allocate= memory - for the domain process on a NUMA host. It contains several optional - attributes. Attribute mode is either 'interleave', - 'strict', or 'preferred', defaults to 'strict'. Attribute - nodeset specifies the NUMA nodes, using the same synt= ax as - attribute cpuset of element vcpu. Attrib= ute - placement (since 0.9.12)= can be - used to indicate the memory placement mode for domain process, its= value - can be either "static" or "auto", defaults to placement of - vcpu, or "static" if nodeset is specifie= d. - "auto" indicates the domain process will only allocate memory from= the - advisory nodeset returned from querying numad, and the value of at= tribute - nodeset will be ignored if it's specified. - - If placement of vcpu is 'auto', and - numatune is not specified, a default numatune - with placement 'auto' and mode 'strict' = will - be added implicitly. - - Since 0.9.3 -
    -
    memnode
    -
    - Optional memnode elements can specify memory allocati= on - policies per each guest NUMA node. For those nodes having no - corresponding memnode element, the default from - element memory will be used. Attribute cellid<= /code> - addresses guest NUMA node for which the settings are applied. - Attributes mode and nodeset have the same - meaning and syntax as in memory element. - - This setting is not compatible with automatic placement. - QEMU Since 1.2.7 -
    -
    - - -

    Block I/O Tuning

    -
    -<domain>
-  ...
-  <blkiotune>
-    <weight>800</weight>
-    <device>
-      <path>/dev/sda</path>
-      <weight>1000</weight>
-    </device>
-    <device>
-      <path>/dev/sdb</path>
-      <weight>500</weight>
-      <read_bytes_sec>10000</read_bytes_sec>
-      <write_bytes_sec>10000</write_bytes_sec>
-      <read_iops_sec>20000</read_iops_sec>
-      <write_iops_sec>20000</write_iops_sec>
-    </device>
-  </blkiotune>
-  ...
-</domain>
-
    - -
    -
    blkiotune
    -
    The optional blkiotune element provides the ability - to tune Blkio cgroup tunable parameters for the domain. If this is - omitted, it defaults to the OS provided - defaults. Since 0.8.8
    -
    weight
    -
    The optional weight element is the overall I/O - weight of the guest. The value should be in the range [100, - 1000]. After kernel 2.6.39, the value could be in the - range [10, 1000].
    -
    device
    -
    The domain may have multiple device elements - that further tune the weights for each host block device in - use by the domain. Note that - multiple guest disks can share a - single host block device, if they are backed by files within - the same host file system, which is why this tuning parameter - is at the global domain level rather than associated with each - guest disk device (contrast this to - the <iotune> - element which can apply to an - individual <disk>). - Each device element has two - mandatory sub-elements, path describing the - absolute path of the device, and weight giving - the relative weight of that device, in the range [100, - 1000]. After kernel 2.6.39, the value could be in the - range [10, 1000]. Since 0.9.8
    - Additionally, the following optional sub-elements can be used: -
    -
    read_bytes_sec
    -
    Read throughput limit in bytes per second. - Since 1.2.2
    -
    write_bytes_sec
    -
    Write throughput limit in bytes per second. - Since 1.2.2
    -
    read_iops_sec
    -
    Read I/O operations per second limit. - Since 1.2.2
    -
    write_iops_sec
    -
    Write I/O operations per second limit. - Since 1.2.2
    -
    - - -

    Resource partitioning

    - -

    - Hypervisors may allow for virtual machines to be placed into - resource partitions, potentially with nesting of said partitions. - The resource element groups together configuration - related to resource partitioning. It currently supports a child - element partition whose content defines the absolute pa= th - of the resource partition in which to place the domain. If no - partition is listed, then the domain will be placed in a default - partition. It is the responsibility of the app/admin to ensure - that the partition exists prior to starting the guest. Only the - (hypervisor specific) default partition can be assumed to exist - by default. -

    -
    -...
-<resource>
-  <partition>/virtualmachines/production</partition>
-</resource>
-...
-
    - -

    - Resource partitions are currently supported by the QEMU and - LXC drivers, which map partition paths to cgroups directories, - in all mounted controllers. Since 1.0.5 -

    - -

    CPU model and topology

    - -

    - Requirements for CPU model, its features and topology can be specifi= ed - using the following collection of elements. - Since 0.7.5 -

    - -
    -...
-<cpu match=3D'exact'>
-  <model fallback=3D'allow'>core2duo</model>
-  <vendor>Intel</vendor>
-  <topology sockets=3D'1' dies=3D'1' cores=3D'2' threads=3D'1'/>
-  <cache level=3D'3' mode=3D'emulate'/>
-  <feature policy=3D'disable' name=3D'lahf_lm'/>
-</cpu>
-...
    - -
    -<cpu mode=3D'host-model'>
-  <model fallback=3D'forbid'/>
-  <topology sockets=3D'1' dies=3D'1' cores=3D'2' threads=3D'1'/>
-</cpu>
-...
    - -
    -<cpu mode=3D'host-passthrough' migratable=3D'off'>
-  <cache mode=3D'passthrough'/>
-  <feature policy=3D'disable' name=3D'lahf_lm'/>
-...
    - -

    - In case no restrictions need to be put on CPU model and its features= , a - simpler cpu element can be used. - Since 0.7.6 -

    - -
    -...
-<cpu>
-  <topology sockets=3D'1' dies=3D'1' cores=3D'2' threads=3D'1'/>
-</cpu>
-...
    - -
    -
    cpu
    -
    The cpu element is the main container for describing - guest CPU requirements. Its match attribute specifies= how - strictly the virtual CPU provided to the guest matches these - requirements. Since 0.7.6 the - match attribute can be omitted if topology - is the only element within cpu. Possible values for t= he - match attribute are: - -
    -
    minimum
    -
    The specified CPU model and features describes the minimum - requested CPU. A better CPU will be provided to the guest if it - is possible with the requested hypervisor on the current host. - This is a constrained host-model mode; the domain - will not be created if the provided virtual CPU does not meet - the requirements.
    - -
    exact
    -
    The virtual CPU provided to the guest should exactly match t= he - specification. If such CPU is not supported, libvirt will refu= se - to start the domain.
    - -
    strict
    -
    The domain will not be created unless the host CPU exactly - matches the specification. This is not very useful in practice - and should only be used if there is a real reason.
    -
    - - Since 0.8.5 the match - attribute can be omitted and will default to exact. - - Sometimes the hypervisor is not able to create a virtual CPU exact= ly - matching the specification passed by libvirt. - Since 3.2.0, an optional check<= /code> - attribute can be used to request a specific way of checking whether - the virtual CPU matches the specification. It is usually safe to o= mit - this attribute when starting a domain and stick with the default - value. Once the domain starts, libvirt will automatically change t= he - check attribute to the best supported value to ensure= the - virtual CPU does not change when the domain is migrated to another - host. The following values can be used: - -
    -
    none
    -
    Libvirt does no checking and it is up to the hypervisor to - refuse to start the domain if it cannot provide the requested = CPU. - With QEMU this means no checking is done at all since the defa= ult - behavior of QEMU is to emit warnings, but start the domain any= way. -
    - -
    partial
    -
    Libvirt will check the guest CPU specification before starti= ng - a domain, but the rest is left on the hypervisor. It can still - provide a different virtual CPU.
    - -
    full
    -
    The virtual CPU created by the hypervisor will be checked - against the CPU specification and the domain will not be start= ed - unless the two CPUs match.
    -
    - - Since 0.9.10, an optional mode<= /code> - attribute may be used to make it easier to configure a guest CPU t= o be - as close to host CPU as possible. Possible values for the - mode attribute are: - -
    -
    custom
    -
    In this mode, the cpu element describes the CPU - that should be presented to the guest. This is the default when = no - mode attribute is specified. This mode makes it so = that - a persistent guest will see the same hardware no matter what host - the guest is booted on.
    -
    host-model
    -
    The host-model mode is essentially a shortcut to - copying host CPU definition from capabilities XML into domain XM= L. - Since the CPU definition is copied just before starting a domain, - exactly the same XML can be used on different hosts while still - providing the best guest CPU each host supports. The - match attribute can't be used in this mode. Specify= ing - CPU model is not supported either, but model's - fallback attribute may still be used. Using the - feature element, specific flags may be enabled or - disabled specifically in addition to the host model. This may be - used to fine tune features that can be emulated. - (Since 1.1.1). - Libvirt does not model every aspect of each CPU so - the guest CPU will not match the host CPU exactly. On the other - hand, the ABI provided to the guest is reproducible. During - migration, complete CPU model definition is transferred to the - destination host so the migrated guest will see exactly the same= CPU - model for the running instance of the guest, even if the destina= tion - host contains more capable CPUs or newer kernel; but shutting do= wn and restarting - the guest may present different hardware to the guest according = to - the capabilities of the new host. Prior to libvirt 3.2.0 and QEMU - 2.9.0 detection of the host CPU model via QEMU is not supported. - Thus the CPU configuration created using host-model - may not work as expected. - Since 3.2.0 and QEMU 2.9.0 this mode - works the way it was designed and it is indicated by the - fallback attribute set to forbid in the - host-model CPU definition advertised in - domain capabilitie= s XML. - When fallback attribute is set to allow - in the domain capabilities XML, it is recommended to use - custom mode with just the CPU model from the host - capabilities XML. Since 1.2.11 Powe= rISA - allows processors to run VMs in binary compatibility mode suppor= ting - an older version of ISA. Libvirt on PowerPC architecture uses t= he - host-model to signify a guest mode CPU running in - binary compatibility mode. Example: - When a user needs a power7 VM to run in compatibility mode - on a Power8 host, this can be described in XML as follows : -
    -<cpu mode=3D'host-model'>
-  <model>power7</model>
-</cpu>
-...
    -
    -
    host-passthrough
    -
    With this mode, the CPU visible to the guest should be exact= ly - the same as the host CPU even in the aspects that libvirt does n= ot - understand. Though the downside of this mode is that the guest - environment cannot be reproduced on different hardware. Thus, if= you - hit any bugs, you are on your own. Further details of that CPU c= an - be changed using feature elements. Migration of a g= uest - using host-passthrough is dangerous if the source and destinatio= n hosts - are not identical in both hardware, QEMU version, microcode vers= ion - and configuration. If such a migration is attempted then the gue= st may - hang or crash upon resuming execution on the destination host. - Depending on hypervisor version the virtual CPU may or may not - contain features which may block migration even to an identical = host. - Since 6.5.0 optional - migratable attribute may be used to explicitly requ= est - such features to be removed from (on) or kept in - (off) the virtual CPU. This attribute does not make - migration to another host safer: even with - migratable=3D'on' migration will be dangerous unles= s both - hosts are identical as described above. -
    -
    - - Both host-model and host-passthrough mod= es - make sense when a domain can run directly on the host CPUs (for - example, domains with type kvm). The actual host CPU = is - irrelevant for domains with emulated virtual CPUs (such as domains= with - type qemu). However, for backward compatibility - host-model may be implemented even for domains runnin= g on - emulated CPUs in which case the best CPU the hypervisor is able to - emulate may be used rather then trying to mimic the host CPU model. -
    - -
    model
    -
    The content of the model element specifies CPU model - requested by the guest. The list of available CPU models and their - definition can be found in cpu_map.xml file installed - in libvirt's data directory. If a hypervisor is not able to use the - exact CPU model, libvirt automatically falls back to a closest mod= el - supported by the hypervisor while maintaining the list of CPU - features. Since 0.9.10, an optional - fallback attribute can be used to forbid this behavio= r, - in which case an attempt to start a domain requesting an unsupport= ed - CPU model will fail. Supported values for fallback - attribute are: allow (this is the default), and - forbid. The optional vendor_id attribute - (Since 0.10.0) can be used to set the - vendor id seen by the guest. It must be exactly 12 characters long. - If not set the vendor id of the host is used. Typical possible - values are "AuthenticAMD" and "GenuineIntel".
    - -
    vendor
    -
    Since 0.8.3 the content of the - vendor element specifies CPU vendor requested by the - guest. If this element is missing, the guest can be run on a CPU - matching given features regardless on its vendor. The list of - supported vendors can be found in cpu_map.xml.
    - -
    topology
    -
    The topology element specifies requested topology of - virtual CPU provided to the guest. Four attributes, sockets<= /code>, - dies, cores, and threads, - accept non-zero positive integer values. They refer to the number = of - CPU sockets per NUMA node, number of dies per socket, number of co= res - per die, and number of threads per core, respectively. The d= ies - attribute is optional and will default to 1 if omitted, while the = other - attributes are all mandatory. Hypervisors may require that the max= imum - number of vCPUs specified by the cpus element equals = to - the number of vcpus resulting from the topology.
    - -
    feature
    -
    The cpu element can contain zero or more - elements used to fine-tune features provided by the - selected CPU model. The list of known feature names can be found in - the same file as CPU models. The meaning of each feature - element depends on its policy attribute, which has to= be - set to one of the following values: - -
    -
    force
    -
    The virtual CPU will claim the feature is supported regardle= ss - of it being supported by host CPU.
    -
    require
    -
    Guest creation will fail unless the feature is supported by = the - host CPU or the hypervisor is able to emulate it.
    -
    optional
    -
    The feature will be supported by virtual CPU if and only if = it - is supported by host CPU.
    -
    disable
    -
    The feature will not be supported by virtual CPU.
    -
    forbid
    -
    Guest creation will fail if the feature is supported by host - CPU.
    -
    - - Since 0.8.5 the policy - attribute can be omitted and will default to require. - -

    Individual CPU feature names are specified as part of the - name attribute. For example, to explicitly specify - the 'pcid' feature with Intel IvyBridge CPU model: -

    - -
    -...
-<cpu match=3D'exact'>
-  <model fallback=3D'forbid'>IvyBridge</model>
-  <vendor>Intel</vendor>
-  <feature policy=3D'require' name=3D'pcid'/>
-</cpu>
-...
    - -
    - -
    cache
    -
    Since 3.3.0 the cache - element describes the virtual CPU cache. If the element is missing, - the hypervisor will use a sensible default. - -
    -
    level
    -
    This optional attribute specifies which cache level is descr= ibed - by the element. Missing attribute means the element describes = all - CPU cache levels at once. Mixing cache elements w= ith - the level attribute set and those without the - attribute is forbidden.
    - -
    mode
    -
    - The following values are supported: -
    -
    emulate
    -
    The hypervisor will provide a fake CPU cache data.
    - -
    passthrough
    -
    The real CPU cache data reported by the host CPU will be - passed through to the virtual CPU.
    - -
    disable
    -
    The virtual CPU will report no CPU cache of the specified - level (or no cache at all if the level attrib= ute - is missing).
    -
    -
    -
    -
    -
    - -

    - Guest NUMA topology can be specified using the numa ele= ment. - Since 0.9.8 -

    - -
    -...
-<cpu>
-  ...
-  <numa>
-    <cell id=3D'0' cpus=3D'0-3' memory=3D'512000' unit=3D'KiB' discard=
=3D'yes'/>
-    <cell id=3D'1' cpus=3D'4-7' memory=3D'512000' unit=3D'KiB' memAcces=
s=3D'shared'/>
-  </numa>
-  ...
-</cpu>
-...
    - -

    - Each cell element specifies a NUMA cell or a NUMA node. - cpus specifies the CPU or range of CPUs that are - part of the node. Since 6.5.0 For the q= emu - driver, if the emulator binary supports disjointed cpus= ranges - in each cell, the sum of all CPUs declared in each cell - will be matched with the maximum number of virtual CPUs declared in = the - vcpu element. This is done by filling any remaining CPUs - into the first NUMA cell. Users are encouraged to suppl= y a - complete NUMA topology, where the sum of the NUMA CPUs matches the m= aximum - virtual CPUs number declared in vcpus, to make the doma= in - consistent across qemu and libvirt versions. - memory specifies the node memory - in kibibytes (i.e. blocks of 1024 bytes). - Since 6.6.0 the cpus attri= bute - is optional and if omitted a CPU-less NUMA node is created. - Since 1.2.11 one can use an additional = unit attribu= te to - define units in which memory is specified. - Since 1.2.7 all cells should - have id attribute in case referring to some cell is - necessary in the code, otherwise the cells are - assigned ids in the increasing order starting from - 0. Mixing cells with and without the id attribute - is not recommended as it may result in unwanted behaviour. - - Since 1.2.9 the optional attribute - memAccess can control whether the memory is to be - mapped as "shared" or "private". This is valid only for - hugepages-backed memory and nvdimm modules. - - Each cell element can have an optional - discard attribute which fine tunes the discard - feature for given numa node as described under - Memory Backing. - Accepted values are yes and no. - Since 4.4.0 -

    - -

    - This guest NUMA specification is currently available only for - QEMU/KVM and Xen. -

    - -

    - A NUMA hardware architecture supports the notion of distances - between NUMA cells. Since 3.10.0 it - is possible to define the distance between NUMA cells using the - distances element within a NUMA cell - description. The sibling sub-element is used to - specify the distance value between sibling NUMA cells. For more - details, see the chapter explaining the system's SLIT (System - Locality Information Table) within the ACPI (Advanced - Configuration and Power Interface) specification. -

    - -
    -...
-<cpu>
-  ...
-  <numa>
-    <cell id=3D'0' cpus=3D'0,4-7' memory=3D'512000' unit=3D'KiB'>
-      <distances>
-        <sibling id=3D'0' value=3D'10'/>
-        <sibling id=3D'1' value=3D'21'/>
-        <sibling id=3D'2' value=3D'31'/>
-        <sibling id=3D'3' value=3D'41'/>
-      </distances>
-    </cell>
-    <cell id=3D'1' cpus=3D'1,8-10,12-15' memory=3D'512000' unit=3D'KiB'=
 memAccess=3D'shared'>
-      <distances>
-        <sibling id=3D'0' value=3D'21'/>
-        <sibling id=3D'1' value=3D'10'/>
-        <sibling id=3D'2' value=3D'21'/>
-        <sibling id=3D'3' value=3D'31'/>
-      </distances>
-    </cell>
-    <cell id=3D'2' cpus=3D'2,11' memory=3D'512000' unit=3D'KiB' memAcce=
ss=3D'shared'>
-      <distances>
-        <sibling id=3D'0' value=3D'31'/>
-        <sibling id=3D'1' value=3D'21'/>
-        <sibling id=3D'2' value=3D'10'/>
-        <sibling id=3D'3' value=3D'21'/>
-      </distances>
-    </cell>
-    <cell id=3D'3' cpus=3D'3' memory=3D'512000' unit=3D'KiB'>
-      <distances>
-        <sibling id=3D'0' value=3D'41'/>
-        <sibling id=3D'1' value=3D'31'/>
-        <sibling id=3D'2' value=3D'21'/>
-        <sibling id=3D'3' value=3D'10'/>
-      </distances>
-    </cell>
-  </numa>
-  ...
-</cpu>
-...
    - -

    - Describing distances between NUMA cells is currently only supported - by Xen and QEMU. If no distances are given to describe - the SLIT data between different cells, it will default to a scheme - using 10 for local and 20 for remote distances. -

    - -

    ACPI Heterogeneous Memory Attribute Table

    - -
    -...
-<cpu>
-  ...
-  <numa>
-    <cell id=3D'0' cpus=3D'0-3' memory=3D'512000' unit=3D'KiB' discard=
=3D'yes'/>
-    <cell id=3D'1' cpus=3D'4-7' memory=3D'512000' unit=3D'KiB' memAcces=
s=3D'shared'/>
-    <cell id=3D'3' cpus=3D'0-3' memory=3D'2097152' unit=3D'KiB'>
-      <cache level=3D'1' associativity=3D'direct' policy=3D'writeback'&=
gt;
-        <size value=3D'10' unit=3D'KiB'/>
-        <line value=3D'8' unit=3D'B'/>
-      </cache>
-    </cell>
-    <interconnects>
-      <latency initiator=3D'0' target=3D'0' type=3D'access' value=3D'5'=
/>
-      <latency initiator=3D'0' target=3D'0' cache=3D'1' type=3D'access'=
 value=3D'10'/>
-      <bandwidth initiator=3D'0' target=3D'0' type=3D'access' value=3D'=
204800' unit=3D'KiB'/>
-    </interconnects>
-  </numa>
-  ...
-</cpu>
-...
    - -

    - Since 6.6.0 the cell eleme= nt can - have a cache child element which describes memory side = cache - for memory proximity domains. The cache element has a - level attribute describing the cache level and thus the - element can be repeated multiple times to describe different levels = of - the cache. -

    - -

    - The cache element then has following mandatory attribut= es: -

    - -
    -
    level
    -
    - Level of the cache this description refers to. -
    - -
    associativity
    -
    - Describes cache associativity (accepted values are none, - direct and full). -
    - -
    policy
    -
    - Describes cache write associativity (accepted values are - none, writeback and - writethrough). -
    -
    - -

    - The cache element has two mandatory child elements then: - size and line which describe cache size and - cache line size. Both elements accept two attributes: value - and unit which set the value of corresponding cache - attribute. -

    - -

    - The NUMA description has an optional interconnects elem= ent that - describes the normalized memory read/write latency, read/write bandw= idth - between Initiator Proximity Domains (Processor or I/O) and Target - Proximity Domains (Memory). -

    - -

    - The interconnects element can have zero or more - latency child elements to describe latency between two - memory nodes and zero or more bandwidth child elements = to - describe bandwidth between two memory nodes. Both these have the - following mandatory attributes: -

    - -
    -
    initiator
    -
    Refers to the source NUMA node
    - -
    target
    -
    Refers to the target NUMA node
    - -
    type
    -
    The type of the access. Accepted values: access, - read, write
    - -
    value
    -
    The actual value. For latency this is delay in nanoseconds, for - bandwidth this value is in kibibytes per second. Use additional - unit attribute to change the units.
    -
    - -

    - To describe latency from one NUMA node to a cache of another NUMA no= de - the latency element has optional cache - attribute which in combination with target attribute cr= eates - full reference to distant NUMA node's cache level. For instance, - target=3D'0' cache=3D'1' refers to the first level cach= e of NUMA - node 0. -

    - -

    Events configuration

    - -

    - It is sometimes necessary to override the default actions taken - on various events. Not all hypervisors support all events and action= s. - The actions may be taken as a result of calls to libvirt APIs - - virDomainReboot - , - - virDomainShutdown - , - or - - virDomainShutdownFlags - . - Using virsh reboot or virsh shutdown would - also trigger the event. -

    - -
    -...
-<on_poweroff>destroy</on_poweroff>
-<on_reboot>restart</on_reboot>
-<on_crash>restart</on_crash>
-<on_lockfailure>poweroff</on_lockfailure>
-...
    - -

    - The following collections of elements allow the actions to be - specified when a guest OS triggers a lifecycle operation. A - common use case is to force a reboot to be treated as a poweroff - when doing the initial OS installation. This allows the VM to be - re-configured for the first post-install bootup. -

    -
    -
    on_poweroff
    -
    The content of this element specifies the action to take when - the guest requests a poweroff.
    -
    on_reboot
    -
    The content of this element specifies the action to take when - the guest requests a reboot.
    -
    on_crash
    -
    The content of this element specifies the action to take when - the guest crashes.
    -
    - -

    - Each of these states allow for the same four possible actions. -

    - -
    -
    destroy
    -
    The domain will be terminated completely and all resources - released.
    -
    restart
    -
    The domain will be terminated and then restarted with - the same configuration.
    -
    preserve
    -
    The domain will be terminated and its resource preserved - to allow analysis.
    -
    rename-restart
    -
    The domain will be terminated and then restarted with - a new name.
    -
    - -

    - QEMU/KVM supports the on_poweroff and on_reboot - events handling the destroy and restart acti= ons. - The preserve action for an on_reboot event - is treated as a destroy and the rename-restart - action for an on_poweroff event is treated as a - restart event. -

    - -

    - The on_crash event supports these additional - actions since 0.8.4. -

    - -
    -
    coredump-destroy
    -
    The crashed domain's core will be dumped, and then the - domain will be terminated completely and all resources - released
    -
    coredump-restart
    -
    The crashed domain's core will be dumped, and then the - domain will be restarted with the same configuration
    -
    - -

    - Since 3.9.0, the lifecycle events can - be configured via the - - virDomainSetLifecycleAction API. -

    - -

    - The on_lockfailure element (since - 1.0.0) may be used to configure what action should be - taken when a lock manager loses resource locks. The following - actions are recognized by libvirt, although not all of them need - to be supported by individual lock managers. When no action is - specified, each lock manager will take its default action. -

    -
    -
    poweroff
    -
    The domain will be forcefully powered off.
    -
    restart
    -
    The domain will be powered off and started up again to - reacquire its locks.
    -
    pause
    -
    The domain will be paused so that it can be manually resumed - when lock issues are solved.
    -
    ignore
    -
    Keep the domain running as if nothing happened.
    -
    - -

    Power Management

    - -

    - Since 0.10.2 it is possible to - forcibly enable or disable BIOS advertisements to the guest - OS. (NB: Only qemu driver support) -

    - -
    -...
-<pm>
-  <suspend-to-disk enabled=3D'no'/>
-  <suspend-to-mem enabled=3D'yes'/>
-</pm>
-...
    - -
    -
    pm
    -
    These elements enable ('yes') or disable ('no') BIOS support - for S3 (suspend-to-mem) and S4 (suspend-to-disk) ACPI sleep - states. If nothing is specified, then the hypervisor will be - left with its default value.
    - Note: This setting cannot prevent the guest OS from performing - a suspend as the guest OS itself can choose to circumvent the - unavailability of the sleep states (e.g. S4 by turning off - completely).
    -
    - -

    Hypervisor features

    - -

    - Hypervisors may allow certain CPU / machine features to be - toggled on/off. -

    - -
    -...
-<features>
-  <pae/>
-  <acpi/>
-  <apic/>
-  <hap/>
-  <privnet/>
-  <hyperv>
-    <relaxed state=3D'on'/>
-    <vapic state=3D'on'/>
-    <spinlocks state=3D'on' retries=3D'4096'/>
-    <vpindex state=3D'on'/>
-    <runtime state=3D'on'/>
-    <synic state=3D'on'/>
-    <stimer state=3D'on'>
-      <direct state=3D'on'/>
-    </stimer>
-    <reset state=3D'on'/>
-    <vendor_id state=3D'on' value=3D'KVM Hv'/>
-    <frequencies state=3D'on'/>
-    <reenlightenment state=3D'on'/>
-    <tlbflush state=3D'on'/>
-    <ipi state=3D'on'/>
-    <evmcs state=3D'on'/>
-  </hyperv>
-  <kvm>
-    <hidden state=3D'on'/>
-    <hint-dedicated state=3D'on'/>
-  </kvm>
-  <xen>
-    <e820_host state=3D'on'/>
-    <passthrough state=3D'on' mode=3D'share_pt'/>
-  </xen>
-  <pvspinlock state=3D'on'/>
-  <gic version=3D'2'/>
-  <ioapic driver=3D'qemu'/>
-  <hpt resizing=3D'required'>
-    <maxpagesize unit=3D'MiB'>16</maxpagesize>
-  </hpt>
-  <vmcoreinfo state=3D'on'/>
-  <smm state=3D'on'>
-    <tseg unit=3D'MiB'>48</tseg>
-  </smm>
-  <htm state=3D'on'/>
-  <ccf-assist state=3D'on'/>
-  <msrs unknown=3D'ignore'/>
-  <cfpc value=3D'workaround'/>
-  <sbbc value=3D'workaround'/>
-  <ibs value=3D'fixed-na'/>
-</features>
-...
    - -

    - All features are listed within the features - element, omitting a togglable feature tag turns it off. - The available features can be found by asking - for the capabilities XML and - domain capabilities XML, - but a common set for fully virtualized domains are: -

    - -
    -
    pae
    -
    Physical address extension mode allows 32-bit guests - to address more than 4 GB of memory.
    -
    acpi
    -
    ACPI is useful for power management, for example, with - KVM guests it is required for graceful shutdown to work. -
    -
    apic
    -
    APIC allows the use of programmable IRQ - management. Since 0.10.2 (QEMU only) th= ere is - an optional attribute eoi with values on - and off which toggles the availability of EOI (End of - Interrupt) for the guest. -
    -
    hap
    -
    Depending on the state attribute (values on, - off) enable or disable use of Hardware Assisted Pagin= g. - The default is on if the hypervisor detects availabil= ity - of Hardware Assisted Paging. -
    -
    viridian
    -
    Enable Viridian hypervisor extensions for paravirtualizing - guest operating systems -
    -
    privnet
    -
    Always create a private network namespace. This is - automatically set if any interface devices are defined. - This feature is only relevant for container based - virtualization drivers, such as LXC. -
    -
    hyperv
    -
    Enable various features improving behavior of guests - running Microsoft Windows. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FeatureDescriptionValueSince
    relaxedRelax constraints on timerson, off1.0.0 (QEMU 2.0)
    vapicEnable virtual APICon, off1.1.0 (QEMU 2.0)
    spinlocksEnable spinlock supporton, off; retries - at least 40951.1.0 (QEMU 2.0)
    vpindexVirtual processor indexon, off1.3.3 (QEMU 2.5)
    runtimeProcessor time spent on running guest code and on behalf of = guest codeon, off1.3.3 (QEMU 2.5)
    synicEnable Synthetic Interrupt Controller (SynIC)on, off1.3.3 (QEMU 2.6)
    stimerEnable SynIC timers, optionally with Direct Mode supporton, off; direct - on,off1.3.3 (QEMU 2.6), direct mode 5.7.0 (Q= EMU 4.1)
    resetEnable hypervisor reseton, off1.3.3 (QEMU 2.5)
    vendor_idSet hypervisor vendor idon, off; value - string, up to 12 characters1.3.3 (QEMU 2.5)
    frequenciesExpose frequency MSRson, off4.7.0 (QEMU 2.12)
    reenlightenmentEnable re-enlightenment notification on migrationon, off4.7.0 (QEMU 3.0)
    tlbflushEnable PV TLB flush supporton, off4.7.0 (QEMU 3.0)
    ipiEnable PV IPI supporton, off4.10.0 (QEMU 3.1)
    evmcsEnable Enlightened VMCSon, off4.10.0 (QEMU 3.1)
    -
    -
    pvspinlock
    -
    Notify the guest that the host supports paravirtual spinlocks - for example by exposing the pvticketlocks mechanism. This feature - can be explicitly disabled by using state=3D'off' - attribute. -
    -
    kvm
    -
    Various features to change the behavior of the KVM hypervisor. - - - - - - - - - - - - - - - - - - -
    FeatureDescriptionValueSince
    hiddenHide the KVM hypervisor from standard MSR based discovery - on, off1.2.8 (QEMU 2.1.0)
    hint-dedicatedAllows a guest to enable optimizations when running on dedic= ated vCPUson, off5.7.0 (QEMU 2.12.0)
    -
    -
    xen
    -
    Various features to change the behavior of the Xen hypervisor. - - - - - - - - - - - - - - - - - - - -
    FeatureDescriptionValueSince
    e820_hostExpose the host e820 to the guest (PV only)on, off6.3.0
    passthroughEnable IOMMU mappings allowing PCI passthroughon, off; mode - optional string sync_pt or share_pt6.3.0
    -
    -
    pmu
    -
    Depending on the state attribute (values on, - off, default on) enable or disable the - performance monitoring unit for the guest. - Since 1.2.12 -
    -
    vmport
    -
    Depending on the state attribute (values on, - off, default on) enable or disable - the emulation of VMware IO port, for vmmouse etc. - Since 1.2.16 -
    -
    gic
    -
    Enable for architectures using a General Interrupt - Controller instead of APIC in order to handle interrupts. - For example, the 'aarch64' architecture uses - gic instead of apic. The optional - attribute version specifies the GIC version; - however, it may not be supported by all hypervisors. Accepted - values are 2, 3 and host. - Since 1.2.16 -
    -
    smm
    -
    -

    - Depending on the state attribute (values on, - off, default on) enable or disable - System Management Mode. - Since 2.1.0 -

    Optional sub-element tseg can be used to spec= ify - the amount of memory dedicated to SMM's extended TSEG. That offe= rs a - fourth option size apart from the existing ones (1 MiB, 2 MiB an= d 8 - MiB) that the guest OS (or rather loader) can choose from. The s= ize - can be specified as a value of that element, optional attribute - unit can be used to specify the unit of the - aforementioned value (defaults to 'MiB'). If set to 0 the exten= ded - size is not advertised and only the default ones (see above) are - available. -

    - If the VM is booting you should leave this option alone, unle= ss you - are very certain you know what you are doing. -

    - This value is configurable due to the fact that the calculation = cannot - be done right with the guarantee that it will work correctly. In - QEMU, the user-configurable extended TSEG feature was unavailabl= e up - to and including pc-q35-2.9. Starting with - pc-q35-2.10 the feature is available, with default = size - 16 MiB. That should suffice for up to roughly 272 vCPUs, 5 GiB = guest - RAM in total, no hotplug memory range, and 32 GiB of 64-bit PCI = MMIO - aperture. Or for 48 vCPUs, with 1TB of guest RAM, no hotplug DI= MM - range, and 32GB of 64-bit PCI MMIO aperture. The values may also= vary - based on the loader the VM is using. -

    - Additional size might be needed for significantly higher vCPU co= unts - or increased address space (that can be memory, maxMemory, 64-bi= t PCI - MMIO aperture size; roughly 8 MiB of TSEG per 1 TiB of address s= pace) - which can also be rounded up. -

    - Due to the nature of this setting being similar to "how much RAM - should the guest have" users are advised to either consult the - documentation of the guest OS or loader (if there is any), or te= st - this by trial-and-error changing the value until the VM boots - successfully. Yet another guiding value for users might be the = fact - that 48 MiB should be enough for pretty large guests (240 vCPUs = and - 4TB guest RAM), but it is on purpose not set as default as 48 Mi= B of - unavailable RAM might be too much for small guests (e.g. with 51= 2 MiB - of RAM). -

    - See Memory Allocation - for more details about the unit attribute. - Since 4.5.0 (QEMU only) -

    -
    -
    ioapic
    -
    Tune the I/O APIC. Possible values for the - driver attribute are: - kvm (default for KVM domains) - and qemu which puts I/O APIC in userspace - which is also known as a split I/O APIC mode. - Since 3.4.0 (QEMU/KVM only) -
    -
    hpt
    -
    Configure the HPT (Hash Page Table) of a pSeries guest. Possible - values for the resizing attribute are - enabled, which causes HPT resizing to be enabled if - both the guest and the host support it; disabled, w= hich - causes HPT resizing to be disabled regardless of guest and host - support; and required, which prevents the guest from - starting unless both the guest and the host support HPT resizing= . If - the attribute is not defined, the hypervisor default will be use= d. - Since 3.10.0 (QEMU/KVM only). - -

    The optional maxpagesize subelement can be used = to - limit the usable page size for HPT guests. Common values are 64 = KiB, - 16 MiB and 16 GiB; when not specified, the hypervisor default wi= ll - be used. Since 4.5.0 (QEMU/KVM only= ).

    -
    -
    vmcoreinfo
    -
    Enable QEMU vmcoreinfo device to let the guest kernel save debug - details. Since 4.4.0 (QEMU only) -
    -
    htm
    -
    Configure HTM (Hardware Transational Memory) availability for - pSeries guests. Possible values for the state attri= bute - are on and off. If the attribute is not - defined, the hypervisor default will be used. - Since 4.6.0 (QEMU/KVM only) -
    -
    nested-hv
    -
    Configure nested HV availability for pSeries guests. This needs = to - be enabled from the host (L0) in order to be effective; having HV - support in the (L1) guest is very desiderable if it's planned to - run nested (L2) guests inside it, because it will result in those - nested guests having much better performance than they would when - using KVM PR or TCG. - Possible values for the state attribute are - on and off. If the attribute is not - defined, the hypervisor default will be used. - Since 4.10.0 (QEMU/KVM only) -
    -
    msrs
    -
    Some guests might require ignoring unknown - Model Specific Registers (MSRs) reads and writes. It's possible - to switch this by setting unknown attribute - of msrs to ignore. If the attribute is - not defined, or set to fault, unknown reads and wri= tes - will not be ignored. - Since 5.1.0 (bhyve only) -
    -
    ccf-assist
    -
    Configure ccf-assist (Count Cache Flush Assist) availability for - pSeries guests. - Possible values for the state attribute - are on and off. If the attribute is not - defined, the hypervisor default will be used. - Since 5.9.0 (QEMU/KVM only) -
    -
    cfpc
    -
    Configure cfpc (Cache Flush on Privilege Change) availability for - pSeries guests. - Possible values for the value attribute - are broken (no protection), workaround - (software workaround available) and fixed (fixed in - hardware). If the attribute is not defined, the hypervisor - default will be used. - Since 6.3.0 (QEMU/KVM only) -
    -
    sbbc
    -
    Configure sbbc (Speculation Barrier Bounds Checking) availabilit= y for - pSeries guests. - Possible values for the value attribute - are broken (no protection), workaround - (software workaround available) and fixed (fixed in - hardware). If the attribute is not defined, the hypervisor - default will be used. - Since 6.3.0 (QEMU/KVM only) -
    -
    ibs
    -
    Configure ibs (Indirect Branch Speculation) availability for - pSeries guests. - Possible values for the value attribute - are broken (no protection), workaround - (count cache flush), fixed-ibs (fixed by - serializing indirect branches), fixed-ccd (fixed by - disabling the cache count) and fixed-na (fixed in - hardware - no longer applicable). - If the attribute is not defined, the hypervisor - default will be used. - Since 6.3.0 (QEMU/KVM only) -
    -
    - -

    Time keeping

    - -

    - The guest clock is typically initialized from the host clock. - Most operating systems expect the hardware clock to be kept - in UTC, and this is the default. Windows, however, expects - it to be in so called 'localtime'. -

    - -
    -...
-<clock offset=3D'localtime'>
-  <timer name=3D'rtc' tickpolicy=3D'catchup' track=3D'guest'>
-    <catchup threshold=3D'123' slew=3D'120' limit=3D'10000'/>
-  </timer>
-  <timer name=3D'pit' tickpolicy=3D'delay'/>
-</clock>
-...
    - -
    -
    clock
    -
    -

    The offset attribute takes four possible - values, allowing fine grained control over how the guest - clock is synchronized to the host. NB, not all hypervisors - support all modes.

    -
    -
    utc
    -
    - The guest clock will always be synchronized to UTC when - booted. - Since 0.9.11 'utc' mode can be co= nverted - to 'variable' mode, which can be controlled by using the - adjustment attribute. If the value is 'reset', the - conversion is never done (not all hypervisors can - synchronize to UTC on each boot; use of 'reset' will cause - an error on those hypervisors). A numeric value - forces the conversion to 'variable' mode using the value as the - initial adjustment. The default adjustment is - hypervisor specific. -
    -
    localtime
    -
    - The guest clock will be synchronized to the host's configured - timezone when booted, if any. - Since 0.9.11, the adjustmen= t - attribute behaves the same as in 'utc' mode. -
    -
    timezone
    -
    - The guest clock will be synchronized to the requested timezone - using the timezone attribute. - Since 0.7.7 -
    -
    variable
    -
    - The guest clock will have an arbitrary offset applied - relative to UTC or localtime, depending on the basis - attribute. The delta relative to UTC (or localtime) is specifi= ed - in seconds, using the adjustment attribute. - The guest is free to adjust the RTC over time and expect - that it will be honored at next reboot. This is in - contrast to 'utc' and 'localtime' mode (with the optional - attribute adjustment=3D'reset'), where the RTC adjustments are - lost at each reboot. Since 0.7.7 - Since 0.9.11 the basis - attribute can be either 'utc' (default) or 'localtime'. -
    -
    -

    - A clock may have zero or more - timer sub-elements. Since - 0.8.0 -

    -
    -
    timer
    -
    -

    - Each timer element requires a name attribute, - and has other optional attributes that depend on - the name specified. Various hypervisors - support different combinations of attributes. -

    -
    -
    name
    -
    - The name attribute selects which timer is - being modified, and can be one of - "platform" (currently unsupported), - "hpet" (xen, qemu, lxc), "kvmclock" (qemu), - "pit" (qemu), "rtc" (qemu, lxc), "tsc" (xen, qemu - - since 3.2.0), "hypervclock" - (qemu - since 1.2.2) or - "armvtimer" (qemu - since 6.1.0). - - The hypervclock timer adds support for the - reference time counter and the reference page for iTSC - feature for guests running the Microsoft Windows - operating system. -
    -
    track
    -
    - The track attribute specifies what the timer - tracks, and can be "boot", "guest", or "wall". - Only valid for name=3D"rtc" - or name=3D"platform". -
    -
    tickpolicy
    -
    -

    - The tickpolicy attribute determines what - happens when QEMU misses a deadline for injecting a - tick to the guest. This can happen, for example, because the - guest was paused. -

    -
    -
    delay
    -
    Continue to deliver ticks at the normal rate. The guest = OS - will not notice anything is amiss, as from its point of vi= ew - time will have continued to flow normally. The time in the - guest should now be behind the time in the host by exactly - the amount of time during which ticks have been missed. -
    catchup
    -
    Deliver ticks at a higher rate to catch up with the miss= ed - ticks. The guest OS will not notice anything is amiss, as - from its point of view time will have continued to flow - normally. Once the timer has managed to catch up with all - the missing ticks, the time in the guest and in the host - should match.
    -
    merge
    -
    Merge the missed tick(s) into one tick and - inject. The guest time may be delayed, depending - on how the OS reacts to the merging of ticks
    -
    discard
    -
    Throw away the missed ticks and continue with future - injection normally. The guest OS will see the timer jump - ahead by a potentially quite significant amount all at onc= e, - as if the intervening chunk of time had simply not existed; - needless to say, such a sudden jump can easily confuse a - guest OS which is not specifically prepared to deal with i= t. - Assuming the guest OS can deal correctly with the time jum= p, - the time in the guest and in the host should now match. -
    -

    If the policy is "catchup", there can be further details in - the catchup sub-element.

    -
    -
    catchup
    -
    - The catchup element has three optional - attributes, each a positive integer. The attributes - are threshold, slew, - and limit. -
    -
    -

    - Note that hypervisors are not required to support all polici= es across all time sources -

    -
    -
    frequency
    -
    - The frequency attribute is an unsigned - integer specifying the frequency at - which name=3D"tsc" runs. -
    -
    mode
    -
    - The mode attribute controls how - the name=3D"tsc" timer is managed, and can be - "auto", "native", "emulate", "paravirt", or "smpsafe". - Other timers are always emulated. -
    -
    present
    -
    - The present attribute can be "yes" or "no" to - specify whether a particular timer is available to the guest. -
    -
    -
    -
    - -

    Performance monitoring events

    - -

    - Some platforms allow monitoring of performance of the virtual machin= e and - the code executed inside. To enable the performance monitoring events - you can either specify them in the perf element or enab= le - them via virDomainSetPerfEvents API. The performance va= lues - are then retrieved using the virConnectGetAllDomainStats API. - Since 2.0.0 -

    - -
    -...
-<perf>
-  <event name=3D'cmt' enabled=3D'yes'/>
-  <event name=3D'mbmt' enabled=3D'no'/>
-  <event name=3D'mbml' enabled=3D'yes'/>
-  <event name=3D'cpu_cycles' enabled=3D'no'/>
-  <event name=3D'instructions' enabled=3D'yes'/>
-  <event name=3D'cache_references' enabled=3D'no'/>
-  <event name=3D'cache_misses' enabled=3D'no'/>
-  <event name=3D'branch_instructions' enabled=3D'no'/>
-  <event name=3D'branch_misses' enabled=3D'no'/>
-  <event name=3D'bus_cycles' enabled=3D'no'/>
-  <event name=3D'stalled_cycles_frontend' enabled=3D'no'/>
-  <event name=3D'stalled_cycles_backend' enabled=3D'no'/>
-  <event name=3D'ref_cpu_cycles' enabled=3D'no'/>
-  <event name=3D'cpu_clock' enabled=3D'no'/>
-  <event name=3D'task_clock' enabled=3D'no'/>
-  <event name=3D'page_faults' enabled=3D'no'/>
-  <event name=3D'context_switches' enabled=3D'no'/>
-  <event name=3D'cpu_migrations' enabled=3D'no'/>
-  <event name=3D'page_faults_min' enabled=3D'no'/>
-  <event name=3D'page_faults_maj' enabled=3D'no'/>
-  <event name=3D'alignment_faults' enabled=3D'no'/>
-  <event name=3D'emulation_faults' enabled=3D'no'/>
-</perf>
-...
-
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    event nameDescriptionstats parameter name
    cmtusage of l3 cache in bytes by applications running on the platfo= rmperf.cmt
    mbmttotal system bandwidth from one level of cacheperf.mbmt
    mbmlbandwidth of memory traffic for a memory controllerperf.mbml
    cpu_cyclesthe count of CPU cycles (total/elapsed)perf.cpu_cycles
    instructionsthe count of instructions by applications running on the platfor= mperf.instructions
    cache_referencesthe count of cache hits by applications running on the platform<= /td> - perf.cache_references
    cache_missesthe count of cache misses by applications running on the platfor= mperf.cache_misses
    branch_instructionsthe count of branch instructions by applications running on the = platformperf.branch_instructions
    branch_missesthe count of branch misses by applications running on the platfo= rmperf.branch_misses
    bus_cyclesthe count of bus cycles by applications running on the platform<= /td> - perf.bus_cycles
    stalled_cycles_frontendthe count of stalled CPU cycles in the frontend of the instructi= on - processor pipeline by applications running on the platformperf.stalled_cycles_frontend
    stalled_cycles_backendthe count of stalled CPU cycles in the backend of the instruction - processor pipeline by applications running on the platformperf.stalled_cycles_backend
    ref_cpu_cyclesthe count of total CPU cycles not affected by CPU frequency scal= ing - by applications running on the platformperf.ref_cpu_cycles
    cpu_clockthe count of CPU clock time, as measured by a monotonic - high-resolution per-CPU timer, by applications running on - the platformperf.cpu_clock
    task_clockthe count of task clock time, as measured by a monotonic - high-resolution CPU timer, specific to the task that - is run by applications running on the platformperf.task_clock
    page_faultsthe count of page faults by applications running on the - platform. This includes minor, major, invalid and other - types of page faultsperf.page_faults
    context_switchesthe count of context switches by applications running on - the platformperf.context_switches
    cpu_migrationsthe count of CPU migrations, that is, where the process - moved from one logical processor to another, by - applications running on the platformperf.cpu_migrations
    page_faults_minthe count of minor page faults, that is, where the - page was present in the page cache, and therefore - the fault avoided loading it from storage, by - applications running on the platformperf.page_faults_min
    page_faults_majthe count of major page faults, that is, where the - page was not present in the page cache, and - therefore had to be fetched from storage, by - applications running on the platformperf.page_faults_maj
    alignment_faultsthe count of alignment faults, that is when - the load or store is not aligned properly, by - applications running on the platformperf.alignment_faults
    emulation_faultsthe count of emulation faults, that is when - the kernel traps on unimplemented instrucions - and emulates them for user space, by - applications running on the platformperf.emulation_faults
    - -

    Devices

    - -

    - The final set of XML elements are all used to describe devices - provided to the guest domain. All devices occur as children - of the main devices element. - Since 0.1.3 -

    - -
    -...
-<devices>
-  <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
-</devices>
-...
    - -
    -
    emulator
    -
    - The contents of the emulator element specify - the fully qualified path to the device model emulator binary. - The capabilities XML specifies - the recommended default emulator to use for each particular - domain type / architecture combination. -
    -
    - -

    - To help users identifying devices they care about, every - device can have direct child alias element - which then has name attribute where users can - store identifier for the device. The identifier has to have - "ua-" prefix and must be unique within the domain. Additionally, the - identifier must consist only of the following characters: - [a-zA-Z0-9_-]. - Since 3.9.0 -

    - -
    -<devices>
-  <disk type=3D'file'>
-    <alias name=3D'ua-myDisk'/>
-  </disk>
-  <interface type=3D'network' trustGuestRxFilters=3D'yes'>
-    <alias name=3D'ua-myNIC'/>
-  </interface>
-  ...
-</devices>
-
    - -

    Hard drives, floppy disks, CDROMs

    - -

    - Any device that looks like a disk, be it a floppy, harddisk, - cdrom, or paravirtualized driver is specified via the disk - element. -

    - -
    -...
-<devices>
-  <disk type=3D'file' snapshot=3D'external'>
-    <driver name=3D"tap" type=3D"aio" cache=3D"default"/>
-    <source file=3D'/var/lib/xen/images/fv0' startupPolicy=3D'optional'=
>
-      <seclabel relabel=3D'no'/>
-    </source>
-    <target dev=3D'hda' bus=3D'ide'/>
-    <iotune>
-      <total_bytes_sec>10000000</total_bytes_sec>
-      <read_iops_sec>400000</read_iops_sec>
-      <write_iops_sec>100000</write_iops_sec>
-    </iotune>
-    <boot order=3D'2'/>
-    <encryption type=3D'...'>
-      ...
-    </encryption>
-    <shareable/>
-    <serial>
-      ...
-    </serial>
-  </disk>
-    ...
-  <disk type=3D'network'>
-    <driver name=3D"qemu" type=3D"raw" io=3D"threads" ioeventfd=3D"on" =
event_idx=3D"off"/>
-    <source protocol=3D"sheepdog" name=3D"image_name">
-      <host name=3D"hostname" port=3D"7000"/>
-    </source>
-    <target dev=3D"hdb" bus=3D"ide"/>
-    <boot order=3D'1'/>
-    <transient/>
-    <address type=3D'drive' controller=3D'0' bus=3D'1' unit=3D'0'/>
-  </disk>
-  <disk type=3D'network'>
-    <driver name=3D"qemu" type=3D"raw"/>
-    <source protocol=3D"rbd" name=3D"image_name2">
-      <host name=3D"hostname" port=3D"7000"/>
-      <snapshot name=3D"snapname"/>
-      <config file=3D"/path/to/file"/>
-      <auth username=3D'myuser'>
-        <secret type=3D'ceph' usage=3D'mypassid'/>
-      </auth>
-    </source>
-    <target dev=3D"hdc" bus=3D"ide"/>
-  </disk>
-  <disk type=3D'block' device=3D'cdrom'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <target dev=3D'hdd' bus=3D'ide' tray=3D'open'/>
-    <readonly/>
-  </disk>
-  <disk type=3D'network' device=3D'cdrom'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D"http" name=3D"url_path" query=3D"foo=3Dbar&=
amp;baz=3Dflurb>
-      <host name=3D"hostname" port=3D"80"/>
-      <cookies>
-        <cookie name=3D"test">somevalue</cookie>
-      </cookies>
-      <readahead size=3D'65536'/>
-      <timeout seconds=3D'6'/>
-    </source>
-    <target dev=3D'hde' bus=3D'ide' tray=3D'open'/>
-    <readonly/>
-  </disk>
-  <disk type=3D'network' device=3D'cdrom'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D"https" name=3D"url_path">
-      <host name=3D"hostname" port=3D"443"/>
-      <ssl verify=3D"no"/>
-    </source>
-    <target dev=3D'hdf' bus=3D'ide' tray=3D'open'/>
-    <readonly/>
-  </disk>
-  <disk type=3D'network' device=3D'cdrom'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D"ftp" name=3D"url_path">
-      <host name=3D"hostname" port=3D"21"/>
-    </source>
-    <target dev=3D'hdg' bus=3D'ide' tray=3D'open'/>
-    <readonly/>
-  </disk>
-  <disk type=3D'network' device=3D'cdrom'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D"ftps" name=3D"url_path">
-      <host name=3D"hostname" port=3D"990"/>
-    </source>
-    <target dev=3D'hdh' bus=3D'ide' tray=3D'open'/>
-    <readonly/>
-  </disk>
-  <disk type=3D'network' device=3D'cdrom'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D"tftp" name=3D"url_path">
-      <host name=3D"hostname" port=3D"69"/>
-    </source>
-    <target dev=3D'hdi' bus=3D'ide' tray=3D'open'/>
-    <readonly/>
-  </disk>
-  <disk type=3D'block' device=3D'lun'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source dev=3D'/dev/sda'>
-      <slices>
-        <slice type=3D'storage' offset=3D'12345' size=3D'123'/>
-      </slices>
-      <reservations managed=3D'no'>
-        <source type=3D'unix' path=3D'/path/to/qemu-pr-helper' mode=3D'=
client'/>
-      </reservations>
-    </source>
-    <target dev=3D'sda' bus=3D'scsi'/>
-    <address type=3D'drive' controller=3D'0' bus=3D'0' target=3D'3' uni=
t=3D'0'/>
-  </disk>
-  <disk type=3D'block' device=3D'disk'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source dev=3D'/dev/sda'/>
-    <geometry cyls=3D'16383' heads=3D'16' secs=3D'63' trans=3D'lba'/>
-    <blockio logical_block_size=3D'512' physical_block_size=3D'4096'/&g=
t;
-    <target dev=3D'hdj' bus=3D'ide'/>
-  </disk>
-  <disk type=3D'volume' device=3D'disk'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source pool=3D'blk-pool0' volume=3D'blk-pool0-vol0'/>
-    <target dev=3D'hdk' bus=3D'ide'/>
-  </disk>
-  <disk type=3D'network' device=3D'disk'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D'iscsi' name=3D'iqn.2013-07.com.example:iscsi-no=
pool/2'>
-      <host name=3D'example.com' port=3D'3260'/>
-      <auth username=3D'myuser'>
-        <secret type=3D'iscsi' usage=3D'libvirtiscsi'/>
-      </auth>
-    </source>
-    <target dev=3D'vda' bus=3D'virtio'/>
-  </disk>
-  <disk type=3D'network' device=3D'lun'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D'iscsi' name=3D'iqn.2013-07.com.example:iscsi-no=
pool/1'>
-      <host name=3D'example.com' port=3D'3260'/>
-      <auth username=3D'myuser'>
-        <secret type=3D'iscsi' usage=3D'libvirtiscsi'/>
-      </auth>
-    </source>
-    <target dev=3D'sdb' bus=3D'scsi'/>
-  </disk>
-  <disk type=3D'network' device=3D'lun'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source protocol=3D'iscsi' name=3D'iqn.2013-07.com.example:iscsi-no=
pool/0'>
-      <host name=3D'example.com' port=3D'3260'/>
-      <initiator>
-        <iqn name=3D'iqn.2013-07.com.example:client'/>
-      </initiator>
-    </source>
-    <target dev=3D'sdb' bus=3D'scsi'/>
-  </disk>
-  <disk type=3D'volume' device=3D'disk'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source pool=3D'iscsi-pool' volume=3D'unit:0:0:1' mode=3D'host'/>
-    <target dev=3D'vdb' bus=3D'virtio'/>
-  </disk>
-  <disk type=3D'volume' device=3D'disk'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source pool=3D'iscsi-pool' volume=3D'unit:0:0:2' mode=3D'direct'/&=
gt;
-    <target dev=3D'vdc' bus=3D'virtio'/>
-  </disk>
-  <disk type=3D'file' device=3D'disk'>
-    <driver name=3D'qemu' type=3D'qcow2' queues=3D'4'/>
-    <source file=3D'/var/lib/libvirt/images/domain.qcow'/>
-    <backingStore type=3D'file'>
-      <format type=3D'qcow2'/>
-      <source file=3D'/var/lib/libvirt/images/snapshot.qcow'/>
-      <backingStore type=3D'block'>
-        <format type=3D'raw'/>
-        <source dev=3D'/dev/mapper/base'/>
-        <backingStore/>
-      </backingStore>
-    </backingStore>
-    <target dev=3D'vdd' bus=3D'virtio'/>
-  </disk>
-  <disk type=3D'nvme' device=3D'disk'>
-    <driver name=3D'qemu' type=3D'raw'/>
-    <source type=3D'pci' managed=3D'yes' namespace=3D'1'>
-      <address domain=3D'0x0000' bus=3D'0x01' slot=3D'0x00' function=3D=
'0x0'/>
-    </source>
-    <target dev=3D'vde' bus=3D'virtio'/>
-  </disk>
-</devices>
-...
    - -
    -
    disk
    -
    The disk element is the main container for - describing disks and supports the following attributes: -
    -
    type
    -
    - Valid values are "file", "block", - "dir" (since 0.7.5), - "network" (since 0.8.7), or - "volume" (since 1.0.5), or - "nvme" (since 6.0.0) - and refer to the underlying source for the disk. - Since 0.0.3 -
    -
    device
    -
    - Indicates how the disk is to be exposed to the guest OS. Possi= ble - values for this attribute are "floppy", "disk", "cdrom", and "= lun", - defaulting to "disk". -

    - Using "lun" (since 0.9.10) is only - valid when the type is "block" or "network" for - protocol=3D'iscsi' or when the type - is "volume" when using an iSCSI source pool - for mode "host" or as an - NPIV<= /a> - virtual Host Bus Adapter (vHBA) using a Fibre Channel storage = pool. - Configured in this manner, the LUN behaves identically to "dis= k", - except that generic SCSI commands from the guest are accepted - and passed through to the physical device. Also note that - device=3D'lun' will only be recognized for actual raw devices, - but never for individual partitions or LVM partitions (in those - cases, the kernel will reject the generic SCSI commands, making - it identical to device=3D'disk'). - Since 0.1.4 -

    -
    -
    model
    -
    - Indicates the emulated device model of the disk. Typically - this is indicated solely by the bus property but - for bus "virtio" the model can be specified furth= er - with "virtio-transitional", "virtio-non-transitional", or - "virtio". See - Virtio transitional de= vices - for more details. - Since 5.2.0 -
    -
    rawio
    -
    - Indicates whether the disk needs rawio capability. Valid - settings are "yes" or "no" (default is "no"). If any one disk - in a domain has rawio=3D'yes', rawio capability will be enabled - for all disks in the domain (because, in the case of QEMU, this - capability can only be set on a per-process basis). This attri= bute - is only valid when device is "lun". NB, rawio int= ends - to confine the capability per-device, however, current QEMU - implementation gives the domain process broader capability - than that (per-process basis, affects all the domain disks). - To confine the capability as much as possible for QEMU driver - as this stage, sgio is recommended, it's more - secure than rawio. - Since 0.9.10 -
    -
    sgio
    -
    - If supported by the hypervisor and OS, indicates whether - unprivileged SG_IO commands are filtered for the disk. Valid - settings are "filtered" or "unfiltered" where the default is - "filtered". Only available when the device is 'lu= n'. - Since 1.0.2 -
    -
    snapshot
    -
    - Indicates the default behavior of the disk during disk snapsho= ts: - "internal" requires a file format such as qcow2 t= hat - can store both the snapshot and the data changes since the sna= pshot; - "external" will separate the snapshot from the li= ve - data; and "no" means the disk will not participat= e in - snapshots. Read-only disks default to "no", while= the - default for other disks depends on the hypervisor's capabiliti= es. - Some hypervisors allow a per-snapshot choice as well, during - domain snapshot creation. - Not all snapshot modes are supported; for example, enabling - snapshots with a transient disk generally does not make sense. - Since 0.9.5 -
    -
    -
    -
    source
    -
    Representation of the disk source depends on the - disk type attribute value as follows: -
    -
    file
    -
    - The file attribute specifies the fully-qualified - path to the file holding the disk. - Since 0.0.3 -
    -
    block
    -
    - The dev attribute specifies the fully-qualified= path - to the host device to serve as the disk. - Since 0.0.3 -
    -
    dir
    -
    - The dir attribute specifies the fully-qualified= path - to the directory to use as the disk. - Since 0.7.5 -
    -
    network
    -
    - The protocol attribute specifies the protocol to - access to the requested image. Possible values are "nbd", - "iscsi", "rbd", "sheepdog", "gluster", "vxhs", "http", "http= s", - "ftp", ftps", or "tftp". - -

    For any protocol other than nbd - an additional attribute name - is mandatory to specify which volume/image will be used. -

    - -

    For "nbd", the name attribute is optional. T= LS - transport for NBD can be enabled by setting the tls - attribute to yes. For the QEMU hypervisor, usag= e of - a TLS environment can also be globally controlled on the hos= t by - the nbd_tls and nbd_tls_x509_cert_dir in - /etc/libvirt/qemu.conf. - ('tls' Since 4.5.0) -

    - -

    For protocols http and https an - optional attribute query specifies the query st= ring. - (Since 6.2.0) -

    - -

    For "iscsi" (since 1.0.4), t= he - name attribute may include a logical unit numbe= r, - separated from the target's name by a slash (e.g., - iqn.2013-07.com.example:iscsi-pool/1). If not - specified, the default LUN is zero. -

    - -

    For "vxhs" (since 3.8.0), the - name is the UUID of the volume, assigned by the - HyperScale server. Additionally, an optional attribute - tls (QEMU only) can be used to control whether a - VxHS block device would utilize a hypervisor configured TLS - X.509 certificate environment in order to encrypt the data - channel. For the QEMU hypervisor, usage of a TLS environment= can - also be globally controlled on the host by the - vxhs_tls and vxhs_tls_x509_cert_dir or - default_tls_x509_cert_dir settings in the file - /etc/libvirt/qemu.conf. If vxhs_tls is enabled, - then unless the domain tls attribute is set to = "no", - libvirt will use the host configured TLS environment. If the - tls attribute is set to "yes", then regardless = of - the qemu.conf setting, TLS authentication will be attempted. -

    - Since 0.8.7 -
    -
    volume
    -
    - The underlying disk source is represented by attributes - pool and volume. Attribute - pool specifies the name of the - storage pool (managed - by libvirt) where the disk source resides. Attribute - volume specifies the name of storage volume (ma= naged - by libvirt) used as the disk source. The value for the - volume attribute will be the output from the "N= ame" - column of a virsh vol-list [pool-name] command. -

    - Use the attribute mode - (since 1.1.1) to indicate how to - represent the LUN as the disk source. Valid values are - "direct" and "host". If mode is not specified, - the default is to use "host". - - Using "direct" as the mode value indicates to u= se - the storage pool's - source element host attribute as - the disk source to generate the libiscsi URI (e.g. - 'file=3Discsi://example.com:3260/iqn.2013-07.com.example:isc= si-pool/1'). - - Using "host" as the mode value indicates to use= the - LUN's path as it shows up on host (e.g. - 'file=3D/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013= -07.com.example:iscsi-pool-lun-1'). - - Using a LUN from an iSCSI source pool provides the same - features as a disk configured using - type 'block' or 'network' and device - of 'lun' with respect to how the LUN is presented to and - may be used by the guest. - - Since 1.0.5 -

    -
    -
    nvme
    -
    - To specify disk source for NVMe disk the source - element has the following attributes: -
    -
    type
    -
    The type of address specified in address - sub-element. Currently, only pci value is - accepted. -
    - -
    managed
    -
    This attribute instructs libvirt to detach NVMe - controller automatically on domain startup (yes) - or expect the controller to be detached by system - administrator (no). -
    - -
    namespace
    -
    The namespace ID which should be assigned to the domai= n. - According to NVMe standard, namespace numbers start from 1, - including. -
    -
    - - The difference between <disk type=3D'nvme'> - and <hostdev/> is that the latter is plain - host device assignment with all its limitations (e.g. no live - migration), while the former makes hypervisor to run the NVMe - disk through hypervisor's block layer thus enabling all - features provided by the layer (e.g. snapshots, domain - migration, etc.). Moreover, since the NVMe disk is unbinded - from its PCI driver, the host kernel storage stack is not - involved (compared to passing say /dev/nvme0n1 = via - <disk type=3D'block'> and therefore lower - latencies can be achieved. -
    -
    - With "file", "block", and "volume", one or more optional - sub-elements seclabel, described - below (and since 0.9.9), can be - used to override the domain security labeling policy for just - that source file. (NB, for "volume" type disk, seclabel - is only valid when the specified storage volume is of 'file' or - 'block' type). -

    - The source element may also have the index - attribute with same semantics the - index attribute of backingStore -

    -

    - The source element may contain the following sub elem= ents: -

    - -
    -
    host
    -
    -

    - When the disk type is "network", the source= - may have zero or more host sub-elements used to - specify the hosts to connect. - - The host element supports 4 attributes, viz. "na= me", - "port", "transport" and "socket", which specify the hostname, - the port number, transport type and path to socket, respective= ly. - The meaning of this element and the number of the elements dep= end - on the protocol attribute. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Protocol Meaning Number of hosts Default port
    nbd a server running nbd-server only one 10809
    iscsi an iSCSI server only one 3260
    rbd monitor servers of RBD one or more librados default
    sheepdog one of the sheepdog servers (default is localhost:700= 0) zero or one 7000
    gluster a server running glusterd daemon one or more (Since 2.1.0= ), just one prior to that 24007
    vxhs a server running Veritas HyperScale daemon only one 9999
    -

    - gluster supports "tcp", "rdma", "unix" as valid values for the - transport attribute. nbd supports "tcp" and "unix". Others o= nly - support "tcp". If nothing is specified, "tcp" is assumed. If = the - transport is "unix", the socket attribute specifies the path t= o an - AF_UNIX socket. -

    -
    -
    snapshot
    -
    - The name attribute of snapshot eleme= nt can - optionally specify an internal snapshot name to be used as the - source for storage protocols. - Supported for 'rbd' since 1.2.11 (QEMU o= nly). -
    -
    config
    -
    - The file attribute for the config el= ement - provides a fully qualified path to a configuration file to be - provided as a parameter to the client of a networked storage - protocol. Supported for 'rbd' since 1.2.= 11 - (QEMU only). -
    -
    auth
    -
    Since libvirt 3.9.0, the - auth element is supported for a disk - type "network" that is using a source - element with the protocol attributes "rbd" or "is= csi". - If present, the auth element provides the - authentication credentials needed to access the source. It - includes a mandatory attribute username, which - identifies the username to use during authentication, as well - as a sub-element secret with mandatory - attribute type, to tie back to - a libvirt secret object that - holds the actual password or other credentials (the domain XML - intentionally does not expose the password, only the reference - to the object that does manage the password). - Known secret types are "ceph" for Ceph RBD network sources and - "iscsi" for CHAP authentication of iSCSI targets. - Both will require either a uuid attribute - with the UUID of the secret object or a usage - attribute matching the key that was specified in the - secret object. -
    -
    encryption
    -
    Since libvirt 3.9.0, the - encryption can be a sub-element of the - source element for encrypted storage sources. - If present, specifies how the storage source is encrypted - See the - Storage Encryption - page for more information. -

    - Note that the 'qcow' format of encryption is broken and thus i= s no - longer supported for use with disk images. - (Since libvirt 4.5.0) -

    -
    reservations
    -
    Since libvirt 4.4.0, the - reservations can be a sub-element of the - source element for storage sources (QEMU driver o= nly). - If present it enables persistent reservations for SCSI - based disks. The element has one mandatory attribute - managed with accepted values yes and - no. If managed is enabled libvirt pr= epares - and manages any resources needed. When the persistent reservat= ions - are unmanaged, then the hypervisor acts as a client and the pa= th to - the server socket must be provided in the child element - source, which currently accepts only the following - attributes: - type with one value unix, - path path to the socket, and - finally mode which accepts one value - client specifying the role of hypervisor. - It's recommended to allow libvirt manage the persistent - reservations. -
    -
    initiator
    -
    Since libvirt 4.7.0, the - initiator element is supported for a disk - type "network" that is using a source - element with the protocol attribute "iscsi". - If present, the initiator element provides the - initiator IQN needed to access the source via mandatory - attribute name. -
    -
    address
    -
    For disk of type nvme this element - specifies the PCI address of the host NVMe - controller. - Since 6.0.0 -
    -
    slices
    -
    The slices element using its slice - sub-elements allows configuring offset and size of either the - location of the image format (slice type=3D'storage') - inside the storage source or the guest data inside the image f= ormat - container (future expansion). - - The offset and size values are in by= tes. - Since 6.1.0 -
    -
    ssl
    -
    - For https and ftps accessed storage = it's - possible to tweak the SSL transport parameters with this eleme= nt. - The verify attribute allows to turn on or off SSL - certificate validation. Supported values are yes = and - no. Since 6.2.0 -
    -
    cookies
    -
    - For http and https accessed storage = it's - possible to pass one or more cookies. The cookie name and value - must conform to the HTTP specification. - Since 6.2.0 -
    -
    readahead
    -
    - Specifies the size of the readahead buffer for protocols - which support it. (all 'curl' based drivers in qemu). The size - is in bytes. Note that '0' is considered as if the value is not - provided. - Since 6.2.0 -
    -
    timeout
    -
    - Specifies the connection timeout for protocols which support i= t. - Note that '0' is considered as if the value is not provided. - Since 6.2.0 -
    -
    - -

    - For a "file" or "volume" disk type which represents a cdrom or flo= ppy - (the device attribute), it is possible to define - policy what to do with the disk if the source file is not accessib= le. - (NB, startupPolicy is not valid for "volume" disk unl= ess - the specified storage volume is of "file" type). This is done by = the - startupPolicy attribute - (since 0.9.7), - accepting these values: -

    - - - - - - - - - - - - - -
    mandatory fail if missing for any reason (the default)
    requisite fail if missing on boot up, - drop if missing on migrate/restore/revert
    optional drop if missing at any start attempt
    -

    - Since 1.1.2 the startupPolicy - is extended to support hard disks besides cdrom and floppy. On gue= st - cold bootup, if a certain disk is not accessible or its disk chain= is - broken, with startupPolicy 'optional' the guest will drop this dis= k. - This feature doesn't support migration currently. -

    -
    -
    backingStore
    -
    - This element describes the backing store used by the disk - specified by sibling source element. - Since 1.2.4. - - If the hypervisor driver does not support the - - backingStoreInput - (Since 5.10.0) - domain feature the backingStore is ignored on - input and only used for output to describe the detected - backing chains of running domains. - - If backingStoreInput is supported - the backingStore is used as the backing image of - source or other backingStore overriding - any backing image information recorded in the image metadata. - - An empty backingStore element means the sibling - source is self-contained and is not based on any backing store. - - For the detected backing chain information to be accurate, the - backing format must be correctly specified in the metadata of - each file of the chain (files created by libvirt satisfy this - property, but using existing external files for snapshot or - block copy operations requires the end user to pre-create the - file correctly). The following attributes are - supported in backingStore: -
    -
    type
    -
    - The type attribute represents the type of disk us= ed - by the backing store, see disk type attribute above for more - details and possible values. -
    -
    index
    -
    - This attribute is only valid in output (and ignored on input) = and - it can be used to refer to a specific part of the disk chain w= hen - doing block operations (such as via the - virDomainBlockRebase API). For example, - vda[2] refers to the backing store with - index=3D'2' of the disk with vda tar= get. -
    -
    - Moreover, backingStore supports the following sub-ele= ments: -
    -
    format
    -
    - The format element contains type - attribute which specifies the internal format of the backing - store, such as raw or qcow2. -
    -
    source
    -
    - This element has the same structure as the source - element in disk. It specifies which file, device, - or network location contains the data of the described backing - store. -
    -
    backingStore
    -
    - If the backing store is not self-contained, the next element - in the chain is described by nested backingStore - element. -
    -
    -
    -
    mirror
    -
    - This element is present if the hypervisor has started a - long-running block job operation, where the mirror location in - the source sub-element will eventually have the - same contents as the source, and with the file format in the - sub-element format (which might differ from the - format of the source). The details of the source - sub-element are determined by the type attribute - of the mirror, similar to what is done for the - overall disk device element. The job - attribute mentions which API started the operation ("copy" for - the virDomainBlockRebase API, or "active-commit" - for the virDomainBlockCommit - API), since 1.2.7. The - attribute ready, if present, tracks progress of - the job: yes if the disk is known to be ready to - pivot, or, since - 1.2.7, abort or pivot if the - job is in the process of completing. If ready is - not present, the disk is probably still - copying. For now, this element only valid in output; it is - ignored on input. The source sub-element exists - for all two-phase jobs since 1.2.6. - Older libvirt supported only block copy to a - file, since 0.9.12; for - compatibility with older clients, such jobs include redundant - information in the attributes file - and format in the mirror element. -
    -
    target
    -
    The target element controls the bus / device - under which the disk is exposed to the guest - OS. The dev attribute indicates the "logical" - device name. The actual device name specified is not - guaranteed to map to the device name in the guest OS. Treat it - as a device ordering hint. The optional bus - attribute specifies the type of disk device to emulate; - possible values are driver specific, with typical values being - "ide", "scsi", "virtio", "xen", "usb", "sata", or - "sd" "sd" since 1.1.2. If omitted, th= e bus - type is inferred from the style of the device name (e.g. a device = named - 'sda' will typically be exported using a SCSI bus). The optional - attribute tray indicates the tray status of the - removable disks (i.e. CDROM or Floppy disk), the value can be eith= er - "open" or "closed", defaults to "closed". NB, the value of - tray could be updated while the domain is running. - The optional attribute removable sets the - removable flag for USB disks, and its value can be either "on" - or "off", defaulting to "off". Since - 0.0.3; bus attribute since 0.4.3; - tray attribute since 0.9.11; "usb" attribute value si= nce - after 0.4.4; "sata" attribute value since 0.9.7; "removable" attri= bute - value since 1.1.3 -
    -
    iotune
    -
    The optional iotune element provides the - ability to provide additional per-device I/O tuning, with - values that can vary for each device (contrast this to - the <blkiotune> - element, which applies globally to the domain). Currently, - the only tuning available is Block I/O throttling for qemu. - This element has optional sub-elements; any sub-element not - specified or given with a value of 0 implies no - limit. Since 0.9.8 -
    -
    total_bytes_sec
    -
    The optional total_bytes_sec element is the - total throughput limit in bytes per second. This cannot - appear with read_bytes_sec - or write_bytes_sec.
    -
    read_bytes_sec
    -
    The optional read_bytes_sec element is the - read throughput limit in bytes per second.
    -
    write_bytes_sec
    -
    The optional write_bytes_sec element is the - write throughput limit in bytes per second.
    -
    total_iops_sec
    -
    The optional total_iops_sec element is the - total I/O operations per second. This cannot - appear with read_iops_sec - or write_iops_sec.
    -
    read_iops_sec
    -
    The optional read_iops_sec element is the - read I/O operations per second.
    -
    write_iops_sec
    -
    The optional write_iops_sec element is the - write I/O operations per second.
    -
    total_bytes_sec_max
    -
    The optional total_bytes_sec_max element is the - maximum total throughput limit in bytes per second. This cann= ot - appear with read_bytes_sec_max - or write_bytes_sec_max.
    -
    read_bytes_sec_max
    -
    The optional read_bytes_sec_max element is the - maximum read throughput limit in bytes per second.
    -
    write_bytes_sec_max
    -
    The optional write_bytes_sec_max element is the - maximum write throughput limit in bytes per second.
    -
    total_iops_sec_max
    -
    The optional total_iops_sec_max element is the - maximum total I/O operations per second. This cannot - appear with read_iops_sec_max - or write_iops_sec_max.
    -
    read_iops_sec_max
    -
    The optional read_iops_sec_max element is the - maximum read I/O operations per second.
    -
    write_iops_sec_max
    -
    The optional write_iops_sec_max element is the - maximum write I/O operations per second.
    -
    size_iops_sec
    -
    The optional size_iops_sec element is the - size of I/O operations per second. -

    - Throughput limits since 1.2.11 and QEMU = 1.7 -

    -
    -
    group_name
    -
    The optional group_name provides the cability - to share I/O throttling quota between multiple drives. This - prevents end-users from circumventing a hosting provider's - throttling policy by splitting 1 large drive in N small drives - and getting N times the normal throttling quota. Any name may - be used. -

    - group_name since 3.0.0 and QEMU 2.4 -

    -
    -
    total_bytes_sec_max_length
    -
    The optional total_bytes_sec_max_length - element is the maximum duration in seconds for the - total_bytes_sec_max burst period. Only valid - when the total_bytes_sec_max is set.
    -
    read_bytes_sec_max_length
    -
    The optional read_bytes_sec_max_length - element is the maximum duration in seconds for the - read_bytes_sec_max burst period. Only valid - when the read_bytes_sec_max is set.
    -
    write_bytes_sec_max
    -
    The optional write_bytes_sec_max_length - element is the maximum duration in seconds for the - write_bytes_sec_max burst period. Only valid - when the write_bytes_sec_max is set.
    -
    total_iops_sec_max_length
    -
    The optional total_iops_sec_max_length - element is the maximum duration in seconds for the - total_iops_sec_max burst period. Only valid - when the total_iops_sec_max is set.
    -
    read_iops_sec_max_length
    -
    The optional read_iops_sec_max_length - element is the maximum duration in seconds for the - read_iops_sec_max burst period. Only valid - when the read_iops_sec_max is set.
    -
    write_iops_sec_max
    -
    The optional write_iops_sec_max_length - element is the maximum duration in seconds for the - write_iops_sec_max burst period. Only valid - when the write_iops_sec_max is set. -

    - Throughput length since 2.4.0 and QEMU 2= .6 -

    -
    -
    -
    -
    driver
    -
    - The optional driver element allows specifying further details - related to the hypervisor driver used to provide the disk. - Since 0.1.8 -
      -
    • - If the hypervisor supports multiple backend drivers, then - the name attribute selects the primary - backend driver name, while the optional type - attribute provides the sub-type. For example, xen - supports a name of "tap", "tap2", "phy", or "file", with a - type of "aio", while qemu only supports a name of "qemu", - but multiple types including "raw", "bochs", "qcow2", and - "qed". -
      • -
    • - The optional cache attribute controls the - cache mechanism, possible values are "default", "none", - "writethrough", "writeback", "directsync" (like - "writethrough", but it bypasses the host page cache) and - "unsafe" (host may cache all disk io, and sync requests from - guest are ignored). - - Since 0.6.0, - "directsync" since 0.9.5, - "unsafe" since 0.9.7 - -
      • -
    • - The optional error_policy attribute controls - how the hypervisor will behave on a disk read or write - error, possible values are "stop", "report", "ignore", and - "enospace".Since 0.8.0, "report" since - 0.9.7 The default is left to the discretion of the - hypervisor. There is also an - optional rerror_policy that controls behavior - for read errors only. Since - 0.9.7. If no rerror_policy is given, error_policy - is used for both read and write errors. If rerror_policy - is given, it overrides the error_policy for - read errors. Also note that "enospace" is not a valid - policy for read errors, so if error_policy is - set to "enospace" and no rerror_policy is - given, the read error policy will be left at its default. -
      • -
    • - The optional io attribute controls specific - policies on I/O; qemu guests support "threads" and - "native" Since 0.8.8, io_uring - Since 6.3.0 (QEMU 5.0). -
      • -
    • - The optional ioeventfd attribute allows users to - set - domain I/O asynchronous handling for disk device. - The default is left to the discretion of the hypervisor. - Accepted values are "on" and "off". Enabling this allows - qemu to execute VM while a separate thread handles I/O. - Typically guests experiencing high system CPU utilization - during I/O will benefit from this. On the other hand, - on overloaded host it could increase guest I/O latency. - Since 0.9.3 (QEMU and KVM only) - In general you should leave this option alone, unless you - are very certain you know what you are doing. -
      • -
    • - The optional event_idx attribute controls - some aspects of device event processing. The value can be - either 'on' or 'off' - if it is on, it will reduce the - number of interrupts and exits for the guest. The default - is determined by QEMU; usually if the feature is - supported, default is on. In case there is a situation - where this behavior is suboptimal, this attribute provides - a way to force the feature off. - Since 0.9.5 (QEMU and KVM only) - In general you should leave this option alone, unless you - are very certain you know what you are doing. -
      • -
    • - The optional copy_on_read attribute controls - whether to copy read backing file into the image file. The - value can be either "on" or "off". - Copy-on-read avoids accessing the same backing file sectors - repeatedly and is useful when the backing file is over a slow - network. By default copy-on-read is off. - Since 0.9.10 (QEMU and KVM only) -
      • -
    • - The optional discard attribute controls whether - discard requests (also known as "trim" or "unmap") are - ignored or passed to the filesystem. The value can be either - "unmap" (allow the discard request to be passed) or "ignore" - (ignore the discard request). - Since 1.0.6 (QEMU and KVM only) -
      • -
    • - The optional detect_zeroes attribute controls whe= ther - to detect zero write requests. The value can be "off", "on" or - "unmap". First two values turn the detection off and on, - respectively. The third value ("unmap") turns the detection on - and additionally tries to discard such areas from the image ba= sed - on the value of discard above (it will act as "on" - if discard is set to "ignore"). NB enabling the - detection is a compute intensive operation, but can save file - space and/or time on slow media. - Since 2.0.0 -
      • -
    • - The optional iothread attribute assigns the - disk to an IOThread as defined by the range for the domain - iothreads - value. Multiple disks may be assigned to the same IOThread and - are numbered from 1 to the domain iothreads value. Available - for a disk device target configured to use "virti= o" - bus and "pci" or "ccw" address types. - Since 1.2.8 (QEMU 2.1) -
      • -
    • - The optional queues attribute specifies the numbe= r of - virt queues for virtio-blk. (Since 3.9.0= ) -
      • -
    • - For virtio disks, - Virtio-specific options can also= be - set. (Since 3.5.0) -
      • -
    -
    -
    backenddomain
    -
    The optional backenddomain element allows specifyin= g a - backend domain (aka driver domain) hosting the disk. Use the - name attribute to specify the backend domain name. - Since 1.2.13 (Xen only) -
    -
    boot
    -
    Specifies that the disk is bootable. The order - attribute determines the order in which devices will be tried duri= ng - boot sequence. On the S390 architecture only the first boot device= is - used. The optional loadparm attribute is an 8 charact= er - string which can be queried by guests on S390 via sclp or diag 308. - Linux guests on S390 can use loadparm to select a boot - entry. Since 3.5.0 - The per-device boot elements cannot be used together - with general boot elements in - BIOS bootloader section. - Since 0.8.8 -
    -
    encryption
    -
    Starting with libvirt 3.9.0 the - encryption element is preferred to be a sub-element - of the source element. If present, specifies how the - volume is encrypted using "qcow". See the - Storage Encryption pa= ge - for more information. -
    -
    readonly
    -
    If present, this indicates the device cannot be modified by - the guest. For now, this is the default for disks with - attribute device=3D'cdrom'. -
    -
    shareable
    -
    If present, this indicates the device is expected to be shared - between domains (assuming the hypervisor and OS support this), - which means that caching should be deactivated for that device. -
    -
    transient
    -
    If present, this indicates that changes to the device - contents should be reverted automatically when the guest - exits. With some hypervisors, marking a disk transient - prevents the domain from participating in migration or - snapshots. Since 0.9.5 -
    -
    serial
    -
    If present, this specify serial number of virtual hard drive. - For example, it may look - like <serial>WD-WMAP9A966149</serial>. - Not supported for scsi-block devices, that is those using - disk type 'block' using device 'lun' - on bus 'scsi'. - Since 0.7.1 -
    -
    wwn
    -
    If present, this element specifies the WWN (World Wide Name) - of a virtual hard disk or CD-ROM drive. It must be composed - of 16 hexadecimal digits. - Since 0.10.1 -
    -
    vendor
    -
    If present, this element specifies the vendor of a virtual hard - disk or CD-ROM device. It must not be longer than 8 printable - characters. - Since 1.0.1 -
    -
    product
    -
    If present, this element specifies the product of a virtual hard - disk or CD-ROM device. It must not be longer than 16 printable - characters. - Since 1.0.1 -
    -
    address
    -
    If present, the address element ties the disk - to a given slot of a controller (the - actual <controller> device can often be - inferred by libvirt, although it can - be explicitly specified). - The type attribute is mandatory, and is typically - "pci" or "drive". For a "pci" controller, additional - attributes for bus, slot, - and function must be present, as well as - optional domain and multifunction. - Multifunction defaults to 'off'; any other value requires - QEMU 0.1.3 and libvirt 0.9.7. For a - "drive" controller, additional attributes - controller, bus, target - (libvirt 0.9.11), and unit - are available, each defaulting to 0. -
    -
    auth
    -
    Starting with libvirt 3.9.0 the - auth element is preferred to be a sub-element of - the source element. The element is still read and - managed as a disk sub-element. It is invalid to use - auth as both a sub-element of disk - and source. The auth element was - introduced as a disk sub-element in - libvirt 0.9.7. -
    -
    geometry
    -
    The optional geometry element provides the - ability to override geometry settings. This mostly useful for - S390 DASD-disks or older DOS-disks. 0.10.0<= /span> -
    -
    cyls
    -
    The cyls attribute is the - number of cylinders.
    -
    heads
    -
    The heads attribute is the - number of heads.
    -
    secs
    -
    The secs attribute is the - number of sectors per track.
    -
    trans
    -
    The optional trans attribute is the - BIOS-Translation-Modus (none, lba or auto)
    -
    -
    -
    blockio
    -
    If present, the blockio element allows - to override any of the block device properties listed below. - Since 0.10.2 (QEMU and KVM) -
    -
    logical_block_size
    -
    The logical block size the disk will report to the guest - OS. For Linux this would be the value returned by the - BLKSSZGET ioctl and describes the smallest units for disk - I/O. -
    -
    physical_block_size
    -
    The physical block size the disk will report to the guest - OS. For Linux this would be the value returned by the - BLKPBSZGET ioctl and describes the disk's hardware sector - size which can be relevant for the alignment of disk data. -
    -
    -
    -
    - -

    Filesystems

    - -

    - A directory on the host that can be accessed directly from the guest. - since 0.3.3, since 0.8.5 for QEMU/KVM -

    - -
    -...
-<devices>
-  <filesystem type=3D'template'>
-    <source name=3D'my-vm-template'/>
-    <target dir=3D'/'/>
-  </filesystem>
-  <filesystem type=3D'mount' accessmode=3D'passthrough' multidevs=3D're=
map'>
-    <driver type=3D'path' wrpolicy=3D'immediate'/>
-    <source dir=3D'/export/to/guest'/>
-    <target dir=3D'/import/from/host'/>
-    <readonly/>
-  </filesystem>
-  <filesystem type=3D'file' accessmode=3D'passthrough'>
-    <driver type=3D'loop' format=3D'raw'/>
-    <driver type=3D'path' wrpolicy=3D'immediate'/>
-    <source file=3D'/export/to/guest.img'/>
-    <target dir=3D'/import/from/host'/>
-    <readonly/>
-  </filesystem>
-  <filesystem type=3D'mount' accessmode=3D'passthrough'>
-      <driver type=3D'virtiofs' queue=3D'1024'/>
-      <binary path=3D'/usr/libexec/virtiofsd' xattr=3D'on'>
-         <cache mode=3D'always'/>
-         <lock posix=3D'on' flock=3D'on'/>
-      </binary>
-      <source dir=3D'/path'/>
-      <target dir=3D'mount_tag'/>
-  </filesystem>
-  ...
-</devices>
-...
    - -
    -
    filesystem
    -
    - - The filesystem attribute type specifies the type of the - source. The possible values are: - -
    -
    mount
    -
    - A host directory to mount in the guest. Used by LXC, - OpenVZ (since 0.6.2) - and QEMU/KVM (since 0.8.5). - This is the default type if one is not specified. - This mode also has an optional - sub-element driver, with an - attribute type=3D'path' - or type=3D'handle' (since - 0.9.7). The driver block has an optional attribute - wrpolicy that further controls interaction with - the host page cache; omitting the attribute gives default behavior, - while the value immediate means that a host writeback - is immediately triggered for all pages touched during a guest file - write operation (since 0.9.10). - Since 6.2.0, type=3D'virtiofs'<= /code> - is also supported. Using virtiofs requires setting up shared memor= y, - see the guide: Virtio-FS -
    -
    template
    -
    - OpenVZ filesystem template. Only used by OpenVZ driver. -
    -
    file
    -
    - A host file will be treated as an image and mounted in - the guest. The filesystem format will be autodetected. - Only used by LXC driver. -
    -
    block
    -
    - A host block device to mount in the guest. The filesystem - format will be autodetected. Only used by LXC driver - (since 0.9.5). -
    -
    ram
    -
    - An in-memory filesystem, using memory from the host OS. - The source element has a single attribute usage - which gives the memory usage limit in KiB, unless units - are specified by the units attribute. Only used - by LXC driver. - (since 0.9.13)
    -
    bind
    -
    - A directory inside the guest will be bound to another - directory inside the guest. Only used by LXC driver - (since 0.9.13)
    -
    - - The filesystem element has an optional attribute accessmode - which specifies the security mode for accessing the source - (since 0.8.5). Currently this only works - with type=3D'mount' for the QEMU/KVM driver. - For driver type virtiofs, only passthrough= is - supported. For other driver types, the possible - values are: - -
    -
    passthrough
    -
    - The source is accessed with the permissions of the - user inside the guest. This is the default accessmode= if - one is not specified. - More info -
    -
    mapped
    -
    - The source is accessed with the permissions of the - hypervisor (QEMU process). - More info -
    -
    squash
    -
    - Similar to 'passthrough', the exception is that failure of - privileged operations like 'chown' are ignored. This makes a - passthrough-like mode usable for people who run the hypervisor - as non-root. - More info -
    -
    - -

    - Since 5.2.0, the filesystem element - has an optional attribute model with supported values - "virtio-transitional", "virtio-non-transitional", or "virtio". - See Virtio transitional devi= ces - for more details. -

    - -

    - The filesystem element has an optional attribute multidevs - which specifies how to deal with a filesystem export containing more= than - one device, in order to avoid file ID collisions on guest when using= 9pfs - (since 6.3.0, requires QEMU 4.2). - This attribute is not available for virtiofs. The possible values ar= e: -

    - -
    -
    default
    -
    - Use QEMU's default setting (which currently is warn). -
    -
    remap
    -
    - This setting allows guest to access multiple devices per export wi= thout - encountering misbehaviours. Inode numbers from host are automatica= lly - remapped on guest to actively prevent file ID collisions if guest - accesses one export containing multiple devices. -
    -
    forbid
    -
    - Only allow to access one device per export by guest. Attempts to a= ccess - additional devices on the same export will cause the individual - filesystem access by guest to fail with an error and being logged = (once) - as error on host side. -
    -
    warn
    -
    - This setting resembles the behaviour of 9pfs prior to QEMU 4.2, th= at is - no action is performed to prevent any potential file ID collisions= if an - export contains multiple devices, with the only exception: a warni= ng is - logged (once) on host side now. This setting may lead to misbehavi= ours - on guest side if more than one device is exported per export, due = to the - potential file ID collisions this may cause on guest side in that = case. -
    -
    - -
    - -

    - The filesystem element may contain the following subele= ments: -

    - -
    driver
    -
    - The optional driver element allows specifying further details - related to the hypervisor driver used to provide the filesystem. - Since 1.0.6 -
      -
    • - If the hypervisor supports multiple backend drivers, then - the type attribute selects the primary - backend driver name, while the format - attribute provides the format type. For example, LXC - supports a type of "loop", with a format of "raw" or - "nbd" with any format. QEMU supports a type of "path" - or "handle", but no formats. Virtuozzo driver supports - a type of "ploop" with a format of "ploop". -
      • -
    • - For virtio-backed devices, - Virtio-specific options can also= be - set. (Since 3.5.0) -
      • -
    • - For virtiofs, the queue attribute ca= n be used - to specify the queue size (i.e. how many requests can the queu= e fit). - (Since 6.2.0) -
      • -
    -
    - -
    binary
    -
    - The optional binary element can tune the options for = virtiofsd. - All of the following attributes and elements are optional. - The attribute path can be used to override the path t= o the daemon. - Attribute xattr enables the use of filesystem extende= d attributes. - Caching can be tuned via the cache element, possible = mode - values being none and always. - Locking can be controlled via the lock - element - attributes posix and flock bot= h accepting - values on or off. - (Since 6.2.0) -
    - -
    source
    -
    - The resource on the host that is being accessed in the guest. The - name attribute must be used with - type=3D'template', and the dir attribute= must - be used with type=3D'mount'. The usage a= ttribute - is used with type=3D'ram' to set the memory limit in = KiB, - unless units are specified by the units attribute. -
    - -
    target
    -
    - Where the source can be accessed in the guest. For - most drivers this is an automatic mount point, but for QEMU/KVM - this is merely an arbitrary string tag that is exported to the - guest as a hint for where to mount. -
    - -
    readonly
    -
    - Enables exporting filesystem as a readonly mount for guest, by - default read-write access is given (currently only works for - QEMU/KVM driver). -
    - -
    space_hard_limit
    -
    - Maximum space available to this guest's filesystem. - Since 0.9.13 -
    - -
    space_soft_limit
    -
    - Maximum space available to this guest's filesystem. The container = is - permitted to exceed its soft limits for a grace period of time. Af= terwards the - hard limit is enforced. - Since 0.9.13 -
    -
    - -

    Device Addresses

    - -

    - Many devices have an optional <address> - sub-element to describe where the device is placed on the - virtual bus presented to the guest. If an address (or any - optional attribute within an address) is omitted on - input, libvirt will generate an appropriate address; but an - explicit address is required if more control over layout is - required. See below for device examples including an address - element. -

    - -

    - Every address has a mandatory attribute type that - describes which bus the device is on. The choice of which - address to use for a given device is constrained in part by the - device and the architecture of the guest. For example, - a <disk> device - uses type=3D'drive', while - a <console> device would - use type=3D'pci' on i686 or x86_64 guests, - or type=3D'spapr-vio' on PowerPC64 pseries guests. - Each address type has further optional attributes that control - where on the bus the device will be placed: -

    - -
    -
    pci
    -
    PCI addresses have the following additional - attributes: domain (a 2-byte hex integer, not - currently used by qemu), bus (a hex value between - 0 and 0xff, inclusive), slot (a hex value between - 0x0 and 0x1f, inclusive), and function (a value - between 0 and 7, inclusive). Also available is - the multifunction attribute, which controls - turning on the multifunction bit for a particular - slot/function in the PCI control register - (since 0.9.7, requires QEMU - 0.13). multifunction defaults to 'off', - but should be set to 'on' for function 0 of a slot that will - have multiple functions used. - (Since 4.10.0), PCI address extensions - depending on the architecture are supported. For example, PCI - addresses for S390 guests will have a zpci child - element, with two attributes: uid (a hex value - between 0x0001 and 0xffff, inclusive), and fid (a - hex value between 0x00000000 and 0xffffffff, inclusive) used by - PCI devices on S390 for User-defined Identifiers and Function - Identifiers.
    - Since 1.3.5, some hypervisor - drivers may accept an <address type=3D'pci'/> - element with no other attributes as an explicit request to - assign a PCI address for the device rather than some other - type of address that may also be appropriate for that same - device (e.g. virtio-mmio).
    - The relationship between the PCI addresses configured in the domain - XML and those seen by the guest OS can sometime seem confusing: a - separate document describes how PCI - addresses work in more detail. -
    -
    drive
    -
    Drive addresses have the following additional - attributes: controller (a 2-digit controller - number), bus (a 2-digit bus number), - target (a 2-digit target number), - and unit (a 2-digit unit number on the bus). -
    -
    virtio-serial
    -
    Each virtio-serial address has the following additional - attributes: controller (a 2-digit controller - number), bus (a 2-digit bus number), - and slot (a 2-digit slot within the bus). -
    -
    ccid
    -
    A CCID address, for smart-cards, has the following - additional attributes: bus (a 2-digit bus - number), and slot attribute (a 2-digit slot - within the bus). Since 0.8.8. -
    -
    usb
    -
    USB addresses have the following additional - attributes: bus (a hex value between 0 and 0xfff, - inclusive), and port (a dotted notation of up to - four octets, such as 1.2 or 2.1.3.1). -
    -
    spapr-vio
    -
    On PowerPC pseries guests, devices can be assigned to the - SPAPR-VIO bus. It has a flat 32-bit address space; by - convention, devices are generally assigned at a non-zero - multiple of 0x00001000, but other addresses are valid and - permitted by libvirt. Each address has the following - additional attribute: reg (the hex value address - of the starting register). Since - 0.9.9. -
    -
    ccw
    -
    S390 guests with a machine value of - s390-ccw-virtio use the native CCW bus for I/O devices. - CCW bus addresses have the following additional attributes: - cssid (a hex value between 0 and 0xfe, inclusive), - ssid (a value between 0 and 3, inclusive) and - devno (a hex value between 0 and 0xffff, inclusive). - Partially specified bus addresses are not allowed. - If omitted, libvirt will assign a free bus address with - cssid=3D0xfe and ssid=3D0. Virtio-ccw devices must have their cssid - set to 0xfe. - Since 1.0.4 -
    -
    virtio-mmio
    -
    This places the device on the virtio-mmio transport, which is - currently only available for some armv7l and - aarch64 virtual machines. virtio-mmio addresses - do not have any additional attributes. - Since 1.1.3
    - If the guest architecture is aarch64 and the machine - type is virt, libvirt will automatically assign PCI - addresses to devices; however, the presence of a single device - with virtio-mmio address in the guest configuration will cause - libvirt to assign virtio-mmio addresses to all further devices. - Since 3.0.0 -
    -
    isa
    -
    ISA addresses have the following additional - attributes: iobase and irq. - Since 1.2.1 -
    -
    unassigned
    -
    For PCI hostdevs, <address type=3D'unassigned'/> - allows the admin to include a PCI hostdev in the domain XML defini= tion, - without making it available for the guest. This allows for configu= rations - in which Libvirt manages the device as a regular PCI hostdev, - regardless of whether the guest will have access to it. - <address type=3D'unassigned'/> is an invalid ad= dress - type for all other device types. - Since 6.0.0 -
    -
    - -

    Virtio-related options

    - -

    - QEMU's virtio devices have some attributes related to the virtio tra= nsport under - the driver element: - The iommu attribute enables the use of emulated IOMMU - by the device. The attribute ats controls the Address - Translation Service support for PCIe devices. This is needed to make= use - of IOTLB support (see IOMMU device). - Possible values are on or off. - Since 3.5.0 -

    -

    - The attribute packed controls if QEMU should try to use - packed virtqueues. Compared to regular split queues, packed queues - consist of only a single descriptor ring replacing available and used - ring, index and descriptor buffer. This can result in better cache - utilization and performance. If packed virtqueues are actually used - depends on the feature negotiation between QEMU, vhost backends and = guest - drivers. Possible values are on or off. - Since 6.3.0 (QEMU and KVM only) -

    - -

    Virtio transitional devices

    - -

    - Since 5.2.0, some of QEMU's virtio devi= ces, - when used with PCI/PCIe machine types, accept the following - model values: -

    - -
    -
    virtio-transitional
    -
    This device can work both with virtio 0.9 and virtio 1.0 guest - drivers, so it's the best choice when compatibility with older - guest operating systems is desired. libvirt will plug the device - into a conventional PCI slot. -
    -
    virtio-non-transitional
    -
    This device can only work with virtio 1.0 guest drivers, and it's - the recommended option unless compatibility with older guest - operating systems is necessary. libvirt will plug the device into - either a PCI Express slot or a conventional PCI slot based on the - machine type, resulting in a more optimized PCI topology. -
    -
    virtio
    -
    This device will work like a virtio-non-transitional - device when plugged into a PCI Express slot, and like a - virtio-transitional device otherwise; libvirt will - pick one or the other based on the machine type. This is the best - choice when compatibility with libvirt versions older than 5.2.0 - is necessary, but it's otherwise not recommended to use it. -
    -
    - -

    - While the information outlined above applies to most virtio devices, - there are a few exceptions: -

    - -
      -
    • - for SCSI controllers, virtio-scsi must be used instead - of virtio for backwards compatibility reasons; -
      • -
    • - some devices, such as GPUs and input devices (keyboard, tablet and - mouse), are only defined in the virtio 1.0 spec and as such don't - have a transitional variant: the only accepted model is - virtio, which will result in a non-transitional devic= e. -
      • -
    - -

    - For more details see the - qemu patch posting and the - virtio-1.0 spec. -

    - - -

    Controllers

    - -

    - Depending on the guest architecture, some device buses can - appear more than once, with a group of virtual devices tied to a - virtual controller. Normally, libvirt can automatically infer such - controllers without requiring explicit XML markup, but sometimes - it is necessary to provide an explicit controller element, notably - when planning the PCI topology - for guests where device hotplug is expected. -

    - -
    -...
-<devices>
-  <controller type=3D'ide' index=3D'0'/>
-  <controller type=3D'virtio-serial' index=3D'0' ports=3D'16' vectors=
=3D'4'/>
-  <controller type=3D'virtio-serial' index=3D'1'>
-    <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x0a' =
function=3D'0x0'/>
-  </controller>
-  <controller type=3D'scsi' index=3D'0' model=3D'virtio-scsi'>
-    <driver iothread=3D'4'/>
-    <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x0b' =
function=3D'0x0'/>
-  </controller>
-  <controller type=3D'xenbus' maxGrantFrames=3D'64' maxEventChannels=3D=
'2047'/>
-  ...
-</devices>
-...
    - -

    - Each controller has a mandatory attribute type, - which must be one of 'ide', 'fdc', 'scsi', 'sata', 'usb', - 'ccid', 'virtio-serial' or 'pci', and a mandatory - attribute index which is the decimal integer - describing in which order the bus controller is encountered (for - use in controller attributes of - <address> elements). - Since 1.3.5 the index is optional; if - not specified, it will be auto-assigned to be the lowest unused - index for the given controller type. Some controller types have - additional attributes that control specific features, such as: -

    - -
    -
    virtio-serial
    -
    The virtio-serial controller has two additional - optional attributes ports and vectors, - which control how many devices can be connected through the - controller. Since 5.2.0, it - supports an optional attribute model which can - be 'virtio', 'virtio-transitional', or 'virtio-non-transitional'. = See - Virtio transitional device= s - for more details. -
    -
    scsi
    -
    A scsi controller has an optional attribute - model, which is one of 'auto', 'buslogic', 'ibmvscsi', - 'lsilogic', 'lsisas1068', 'lsisas1078', 'virtio-scsi', - 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. See - Virtio transitional device= s - for more details. -
    -
    usb
    -
    A usb controller has an optional attribute - model, which is one of "piix3-uhci", "piix4-uhci", - "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3", - "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pvusb - with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu - backend, version 2.0) or "qemu-xhci". Additionally, - since 0.10.0, if the USB bus needs to - be explicitly disabled for the guest, model=3D'none' - may be used. Since 1.0.5, no default - USB controller will be built on s390. - Since 1.3.5, USB controllers accept a - ports attribute to configure how many devices can be - connected to the controller.
    -
    ide
    -
    Since 3.10.0 for the vbox driver,= the - ide controller has an optional attribute - model, which is one of "piix3", "piix4" or "ich6". -
    xenbus
    -
    Since 5.2.0, the xenbus - controller has an optional attribute maxGrantFrames, - which specifies the maximum number of grant frames the controller - makes available for connected devices. - Since 6.3.0, the xenbus controller - supports the optional maxEventChannels attribute, - which specifies maximum number of event channels (PV interrupts) - that can be used by the guest.
    -
    - -

    - Note: The PowerPC64 "spapr-vio" addresses do not have an - associated controller. -

    - -

    - For controllers that are themselves devices on a PCI or USB bus, - an optional sub-element <address> can specify - the exact relationship of the controller to its master bus, with - semantics given above. -

    - -

    - An optional sub-element driver can specify the driver - specific options: -

    -
    -
    queues
    -
    - The optional queues attribute specifies the number of - queues for the controller. For best performance, it's recommended = to - specify a value matching the number of vCPUs. - Since 1.0.5 (QEMU and KVM only) -
    -
    cmd_per_lun
    -
    - The optional cmd_per_lun attribute specifies the maxi= mum - number of commands that can be queued on devices controlled by the - host. - Since 1.2.7 (QEMU and KVM only) -
    -
    max_sectors
    -
    - The optional max_sectors attribute specifies the maxi= mum - amount of data in bytes that will be transferred to or from the de= vice - in a single command. The transfer length is measured in sectors, w= here - a sector is 512 bytes. - Since 1.2.7 (QEMU and KVM only) -
    -
    ioeventfd
    -
    - The optional ioeventfd attribute specifies - whether the controller should use - - I/O asynchronous handling or not. Accepted values are - "on" and "off". Since 1.2.18 -
    -
    iothread
    -
    - Supported for controller type scsi using model - virtio-scsi for address types - pci and ccw - since 1.3.5 (QEMU 2.4). - - The optional iothread attribute assigns the controller - to an IOThread as defined by the range for the domain - iothreads - value. Each SCSI disk assigned to use the specified - controller will utilize the same IOThread. If a speci= fic - IOThread is desired for a specific SCSI disk, then - multiple controllers must be defined each having a specific - iothread value. The iothread value - must be within the range 1 to the domain iothreads value. -
    -
    virtio options
    -
    - For virtio controllers, - Virtio-specific options can also be - set. (Since 3.5.0) -
    -
    -

    - USB companion controllers have an optional - sub-element <master> to specify the exact - relationship of the companion to its master controller. - A companion controller is on the same bus as its master, so - the companion index value should be equal. - Not all controller models can be used as companion controllers - and libvirt might provide some sensible defaults (settings - of master startport and function of an - address) for some particular models. - Preferred companion controllers are ich-uhci[123]. -

    - -
    -...
-<devices>
-  <controller type=3D'usb' index=3D'0' model=3D'ich9-ehci1'>
-    <address type=3D'pci' domain=3D'0' bus=3D'0' slot=3D'4' function=3D=
'7'/>
-  </controller>
-  <controller type=3D'usb' index=3D'0' model=3D'ich9-uhci1'>
-    <master startport=3D'0'/>
-    <address type=3D'pci' domain=3D'0' bus=3D'0' slot=3D'4' function=3D=
'0' multifunction=3D'on'/>
-  </controller>
-  ...
-</devices>
-...
    - -

    - PCI controllers have an optional model attribute; possi= ble - values for this attribute are -

    -
      -
    • - pci-root, pci-bridge - (since 1.0.5) -
      • -
    • - pcie-root, dmi-to-pci-bridge - (since 1.1.2) -
      • -
    • - pcie-root-port, pcie-switch-upstream-port, - pcie-switch-downstream-port - (since 1.2.19) -
      • -
    • - pci-expander-bus, pcie-expander-bus - (since 1.3.4) -
      • -
    • - pcie-to-pci-bridge - (since 4.3.0) -
      • -
    -

    - The root controllers (pci-root - and pcie-root) have an - optional pcihole64 element specifying how big (in - kilobytes, or in the unit specified by pcihole64's - unit attribute) the 64-bit PCI hole should be. Some gue= sts (like - Windows XP or Windows Server 2003) might crash when QEMU and Seabios - are recent enough to support 64-bit PCI holes, unless this is disabl= ed - (set to 0). Since 1.1.2 (QEMU only) -

    -

    - PCI controllers also have an optional - subelement <model> with an attribute - name. The name attribute holds the name of the - specific device that qemu is emulating (e.g. "i82801b11-bridge") - rather than simply the class of device ("pcie-to-pci-bridge", - "pci-bridge"), which is set in the controller element's - model attribute. In almost all cases, you should not - manually add a <model> subelement to a - controller, nor should you modify one that is automatically - generated by libvirt. Since 1.2.19 (QEMU - only). -

    -

    - PCI controllers also have an optional - subelement <target> with the attributes and - subelements listed below. These are configurable items that 1) - are visible to the guest OS so must be preserved for guest ABI - compatibility, and 2) are usually left to default values or - derived automatically by libvirt. In almost all cases, you - should not manually add a <target> subelement - to a controller, nor should you modify the values in the those - that are automatically generated by - libvirt. Since 1.2.19 (QEMU only). -

    -
    -
    chassisNr
    -
    - PCI controllers that have attribute model=3D"pci-bridge", can - also have a chassisNr attribute in - the <target> subelement, which is used to - control QEMU's "chassis_nr" option for the pci-bridge device - (normally libvirt automatically sets this to the same value as - the index attribute of the pci controller). If set, chassisNr - must be between 1 and 255. -
    -
    chassis
    -
    - pcie-root-port and pcie-switch-downstream-port controllers can - also have a chassis attribute in - the <target> subelement, which is used to - set the controller's "chassis" configuration value, which is - visible to the virtual machine. If set, chassis must be - between 0 and 255. -
    -
    port
    -
    - pcie-root-port and pcie-switch-downstream-port controllers can - also have a port attribute in - the <target> subelement, which - is used to set the controller's "port" configuration value, - which is visible to the virtual machine. If set, port must be - between 0 and 255. -
    -
    hotplug
    -
    - pcie-root-port and pcie-switch-downstream-port controllers can - also have a hotplug attribute in - the <target> subelement, which is used to - disable hotplug/unplug of devices on a particular - controller. The default setting of hotplug - is on; it should be set to off to - disable hotplug/unplug of devices on a particular controller. - Since 6.3.0 -
    -
    busNr
    -
    - pci-expander-bus and pcie-expander-bus controllers can have an - optional busNr attribute (1-254). This will be - the bus number of the new bus; All bus numbers between that - specified and 255 will be available only for assignment to - PCI/PCIe controllers plugged into the hierarchy starting with - this expander bus, and bus numbers less than the specified - value will be available to the next lower expander-bus (or the - root-bus if there are no lower expander buses). If you do not - specify a busNumber, libvirt will find the lowest existing - busNumber in all other expander buses (or use 256 if there are - no others) and auto-assign the busNr of that found bus - 2, - which provides one bus number for the pci-expander-bus and one - for the pci-bridge that is automatically attached to it (if - you plan on adding more pci-bridges to the hierarchy of the - bus, you should manually set busNr to a lower value). -

    - A similar algorithm is used for automatically determining - the busNr attribute for pcie-expander-bus, but since the - pcie-expander-bus doesn't have any built-in pci-bridge, the - 2nd bus-number is just being reserved for the pcie-root-port - that must necessarily be connected to the bus in order to - actually plug in an endpoint device. If you intend to plug - multiple devices into a pcie-expander-bus, you must connect - a pcie-switch-upstream-port to the pcie-root-port that is - plugged into the pcie-expander-bus, and multiple - pcie-switch-downstream-ports to the - pcie-switch-upstream-port, and of course for this to work - properly, you will need to decrease the pcie-expander-bus' - busNr accordingly so that there are enough unused bus - numbers above it to accommodate giving out one bus number for - the upstream-port and one for each downstream-port (in - addition to the pcie-root-port and the pcie-expander-bus - itself). -

    -
    -
    node
    -
    - Some PCI controllers (pci-expander-bus for the pc - machine type, pcie-expander-bus for the q35 machine - type and, since 3.6.0, - pci-root for the pseries machine type) can have an - optional <node> subelement within - the <target> subelement, which is used to - set the NUMA node reported to the guest OS for that bus - the - guest OS will then know that all devices on that bus are a - part of the specified NUMA node (it is up to the user of the - libvirt API to attach host devices to the correct - pci-expander-bus when assigning them to the domain). -
    -
    index
    -
    - pci-root controllers for pSeries guests use this attribute to - record the order they will show up in the guest. - Since 3.6.0 -
    -
    -

    - For machine types which provide an implicit PCI bus, the pci-root - controller with index=3D0 is auto-added and required to use PCI devi= ces. - pci-root has no address. - PCI bridges are auto-added if there are too many devices to fit on - the one bus provided by pci-root, or a PCI bus number greater than z= ero - was specified. - PCI bridges can also be specified manually, but their addresses shou= ld - only refer to PCI buses provided by already specified PCI controller= s. - Leaving gaps in the PCI controller indexes might lead to an invalid - configuration. -

    -
    -...
-<devices>
-  <controller type=3D'pci' index=3D'0' model=3D'pci-root'/>
-  <controller type=3D'pci' index=3D'1' model=3D'pci-bridge'>
-    <address type=3D'pci' domain=3D'0' bus=3D'0' slot=3D'5' function=3D=
'0' multifunction=3D'off'/>
-  </controller>
-</devices>
-...
    - -

    - For machine types which provide an implicit PCI Express (PCIe) - bus (for example, the machine types based on the Q35 chipset), - the pcie-root controller with index=3D0 is auto-added to the - domain's configuration. pcie-root has also no address, provides - 31 slots (numbered 1-31) that can be used to attach PCIe or PCI - devices (although libvirt will never auto-assign a PCI device to - a PCIe slot, it will allow manual specification of such an - assignment). Devices connected to pcie-root cannot be - hotplugged. If traditional PCI devices are present in the guest - configuration, a pcie-to-pci-bridge controller will - automatically be added: this controller, which plugs into a - pcie-root-port, provides 31 usable PCI slots (1-31) with - hotplug support (since 4.3.0). If the Q= EMU - binary doesn't support the corresponding device, then a - dmi-to-pci-bridge controller will be added instead, - usually at the defacto standard location of slot=3D0x1e. A - dmi-to-pci-bridge controller plugs into a PCIe slot (as provided - by pcie-root), and itself provides 31 standard PCI slots (which - also do not support device hotplug). In order to have - hot-pluggable PCI slots in the guest system, a pci-bridge - controller will also be automatically created and connected to - one of the slots of the auto-created dmi-to-pci-bridge - controller; all guest PCI devices with addresses that are - auto-determined by libvirt will be placed on this pci-bridge - device. (since 1.1.2). -

    -

    - Domains with an implicit pcie-root can also add controllers - with model=3D'pcie-root-port', - model=3D'pcie-switch-upstream-port', - and model=3D'pcie-switch-downstream-port'. pcie-root-po= rt - is a simple type of bridge device that can connect only to one - of the 31 slots on the pcie-root bus on its upstream side, and - makes a single (PCIe, hotpluggable) port available on the - downstream side (at slot=3D'0'). pcie-root-port can be used to - provide a single slot to later hotplug a PCIe device (but is not - itself hotpluggable - it must be in the configuration when the - domain is started). - (since 1.2.19) -

    -

    - pcie-switch-upstream-port is a more flexible (but also more - complex) device that can only plug into a pcie-root-port or - pcie-switch-downstream-port on the upstream side (and only - before the domain is started - it is not hot-pluggable), and - provides 32 ports on the downstream side (slot=3D'0' - slot=3D'31') - that accept only pcie-switch-downstream-port devices; each - pcie-switch-downstream-port device can only plug into a - pcie-switch-upstream-port on its upstream side (again, not - hot-pluggable), and on its downstream side provides a single - hotpluggable pcie port that can accept any standard pci or pcie - device (or another pcie-switch-upstream-port), i.e. identical in - function to a pcie-root-port. (since - 1.2.19) -

    -
    -...
-<devices>
-  <controller type=3D'pci' index=3D'0' model=3D'pcie-root'/>
-  <controller type=3D'pci' index=3D'1' model=3D'pcie-root-port'>
-    <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x01' =
function=3D'0x0'/>
-  </controller>
-  <controller type=3D'pci' index=3D'2' model=3D'pcie-to-pci-bridge'>
-    <address type=3D'pci' domain=3D'0x0000' bus=3D'0x01' slot=3D'0x00' =
function=3D'0x0'/>
-  </controller>
-</devices>
-...
    - -

    Device leases

    - -

    - When using a lock manager, it may be desirable to record device leas= es - against a VM. The lock manager will ensure the VM won't start unless - the leases can be acquired. -

    - -
    -...
-<devices>
-  ...
-  <lease>
-    <lockspace>somearea</lockspace>
-    <key>somekey</key>
-    <target path=3D'/some/lease/path' offset=3D'1024'/>
-  </lease>
-  ...
-</devices>
-...
    - -
    -
    lockspace
    -
    This is an arbitrary string, identifying the lockspace - within which the key is held. Lock managers may impose - extra restrictions on the format, or length of the lockspace - name.
    -
    key
    -
    This is an arbitrary string, uniquely identifying the - lease to be acquired. Lock managers may impose extra - restrictions on the format, or length of the key. -
    -
    target
    -
    This is the fully qualified path of the file associated - with the lockspace. The offset specifies where the lease - is stored within the file. If the lock manager does not - require an offset, just pass 0. -
    -
    - -

    Host device assignment

    - -
    USB / PCI / SCSI devices
    - -

    - USB, PCI and SCSI devices attached to the host can be passed through - to the guest using the hostdev element. - since after 0.4.4 for USB, 0.6.0 for PCI (KVM = only) - and 1.0.6 for SCSI (KVM only): -

    - -
    -...
-<devices>
-  <hostdev mode=3D'subsystem' type=3D'usb'>
-    <source startupPolicy=3D'optional'>
-      <vendor id=3D'0x1234'/>
-      <product id=3D'0xbeef'/>
-    </source>
-    <boot order=3D'2'/>
-  </hostdev>
-</devices>
-...
    - -

    or:

    - -
    -...
-<devices>
-  <hostdev mode=3D'subsystem' type=3D'pci' managed=3D'yes'>
-    <source>
-      <address domain=3D'0x0000' bus=3D'0x06' slot=3D'0x02' function=3D=
'0x0'/>
-    </source>
-    <boot order=3D'1'/>
-    <rom bar=3D'on' file=3D'/etc/fake/boot.bin'/>
-  </hostdev>
-</devices>
-...
    - -

    or:

    - -
    -...
-<devices>
-  <hostdev mode=3D'subsystem' type=3D'scsi' sgio=3D'filtered' rawio=3D'=
yes'>
-    <source>
-      <adapter name=3D'scsi_host0'/>
-      <address bus=3D'0' target=3D'0' unit=3D'0'/>
-    </source>
-    <readonly/>
-    <address type=3D'drive' controller=3D'0' bus=3D'0' target=3D'0' uni=
t=3D'0'/>
-  </hostdev>
-</devices>
-...
    - - -

    or:

    - -
    -...
-<devices>
-  <hostdev mode=3D'subsystem' type=3D'scsi'>
-    <source protocol=3D'iscsi' name=3D'iqn.2014-08.com.example:iscsi-no=
pool/1'>
-      <host name=3D'example.com' port=3D'3260'/>
-      <auth username=3D'myuser'>
-        <secret type=3D'iscsi' usage=3D'libvirtiscsi'/>
-      </auth>
-    </source>
-    <address type=3D'drive' controller=3D'0' bus=3D'0' target=3D'0' uni=
t=3D'0'/>
-  </hostdev>
-</devices>
-...
    - -

    or:

    - -
    -  ...
-  <devices>
-    <hostdev mode=3D'subsystem' type=3D'scsi_host'>
-      <source protocol=3D'vhost' wwpn=3D'naa.50014057667280d8'/>
-    </hostdev>
-  </devices>
-  ...
    - -

    or:

    - -
    -  ...
-  <devices>
-    <hostdev mode=3D'subsystem' type=3D'mdev' model=3D'vfio-pci'>
-    <source>
-      <address uuid=3D'c2177883-f1bb-47f0-914d-32a22e3a8804'/>
-    </source>
-    </hostdev>
-    <hostdev mode=3D'subsystem' type=3D'mdev' model=3D'vfio-ccw'>
-    <source>
-      <address uuid=3D'9063cba3-ecef-47b6-abcf-3fef4fdcad85'/>
-    </source>
-    <address type=3D'ccw' cssid=3D'0xfe' ssid=3D'0x0' devno=3D'0x0001'/=
>
-    </hostdev>
-  </devices>
-  ...
    - -
    -
    hostdev
    -
    The hostdev element is the main container for descr= ibing - host devices. For each device, the mode is always - "subsystem" and the type is one of the following valu= es - with additional attributes noted. -
    -
    usb
    -
    USB devices are detached from the host on guest startup - and reattached after the guest exits or the device is - hot-unplugged. -
    -
    pci
    -
    For PCI devices, when managed is "yes" it is - detached from the host before being passed on to the guest - and reattached to the host after the guest exits. If - managed is omitted or "no", the user is - responsible to call virNodeDeviceDetachFlags - (or virsh nodedev-detach before starting the guest - or hot-plugging the device and virNodeDeviceReAttach - (or virsh nodedev-reattach) after hot-unplug or - stopping the guest. -
    -
    scsi
    -
    For SCSI devices, user is responsible to make sure the device - is not used by host. If supported by the hypervisor and OS, the - optional sgio (since 1.0.6<= /span>) - attribute indicates whether unprivileged SG_IO commands are - filtered for the disk. Valid settings are "filtered" or - "unfiltered", where the default is "filtered". - The optional rawio - (since 1.2.9) attribute indicates - whether the lun needs the rawio capability. Valid settings are - "yes" or "no". See the rawio description within the - disk section. - If a disk lun in the domain already has the rawio capability, - then this setting not required. -
    -
    scsi_host
    -
    since 2.5.0For SCSI devices, us= er - is responsible to make sure the device is not used by host. Th= is - type passes all LUNs presented by a single HBA to - the guest. Since 5.2.0, the - model attribute can be specified further - with "virtio-transitional", "virtio-non-transitional", or - "virtio". See - Virtio transitional de= vices - for more details. -
    -
    mdev
    -
    For mediated devices (Since 3.2.0) - the model attribute specifies the device API which - determines how the host's vfio driver will expose the device to = the - guest. Currently, model=3D'vfio-pci', - model=3D'vfio-ccw' (Since 4.4= .0) - and model=3D'vfio-ap' (Since = 4.9.0) - is supported. MDEV section - provides more information about mediated devices as well as how = to - create mediated devices on the host. - Since 4.6.0 (QEMU 2.12) an optional - display attribute may be used to enable or disable - support for an accelerated remote desktop backed by a mediated - device (such as NVIDIA vGPU or Intel GVT-g) as an alternative to - emulated video devices. This attr= ibute - is limited to model=3D'vfio-pci' only. Supported va= lues - are either on or off (default is 'off'= ). - It is required to use a - graphical framebuffer in order= to - use this attribute, currently only supported with VNC, Spice and - egl-headless graphics devices. - - Since version 5.10.0, there is an o= ptional - ramfb attribute for devices with - model=3D'vfio-pci'. Supported values are either - on or off (default is 'off'). When - enabled, this attribute provides a memory framebuffer device to = the - guest. This framebuffer will be used as a boot display when a v= gpu - device is the primary display. -

    - Note: There are also some implications on the usage of guest's - address type depending on the model attribute, - see the address element below. -

    -
    -
    -

    - Note: The managed attribute is only used with - type=3D'pci' and is ignored by all the other device= types, - thus setting managed explicitly with other than a P= CI - device has the same effect as omitting it. Similarly, - model attribute is only supported by mediated devic= es and - ignored by all other device types. -

    -
    -
    source
    -
    The source element describes the device as seen from the host us= ing - the following mechanism to describe: -
    -
    usb
    -
    The USB device can either be addressed by vendor / product id - using the vendor and product elements - or by the device's address on the host using the - address element. -

    - Since 1.0.0, the source - element of USB devices may contain startupPolicy - attribute which can be used to define policy what to do if the - specified host USB device is not found. The attribute accepts - the following values: -

    - - - - - - - - - - - - - -
    mandatory fail if missing for any reason (the default)
    requisite fail if missing on boot up, - drop if missing on migrate/restore/revert
    optional drop if missing at any start attempt
    -
    -
    pci
    -
    PCI devices can only be described by their address. -
    -
    scsi
    -
    SCSI devices are described by both the adapter - and address elements. The address - element includes a bus attribute (a 2-digit bus - number), a target attribute (a 10-digit target - number), and a unit attribute (a 20-digit unit - number on the bus). Not all hypervisors support larger - target and unit values. It is up - to each hypervisor to determine the maximum value supported - for the adapter. -

    - Since 1.2.8, the source - element of a SCSI device may contain the protocol - attribute. When the attribute is set to "iscsi", the host - device XML follows the network disk= - device using the same name attribute and optional= ly - using the auth element to provide the authenticat= ion - credentials to the iSCSI server. -

    -
    -
    scsi_host
    -
    Since 2.5.0, multiple LUNs behi= nd a - single SCSI HBA are described by a protocol - attribute set to "vhost" and a wwpn attribute that - is the vhost_scsi wwpn (16 hexadecimal digits with a prefix of - "naa.") established in the host configfs. -
    -
    mdev
    -
    Mediated devices (Since 3.2.0) = are - described by the address element. The - address element contains a single mandatory attri= bute - uuid. -
    -
    -
    -
    vendor, product
    -
    The vendor and product elements each h= ave an - id attribute that specifies the USB vendor and product = id. - The ids can be given in decimal, hexadecimal (starting with 0x) or - octal (starting with 0) form.
    -
    boot
    -
    Specifies that the device is bootable. The order - attribute determines the order in which devices will be tried during - boot sequence. The per-device boot elements cannot be - used together with general boot elements in - BIOS bootloader section. - Since 0.8.8 for PCI devices, - Since 1.0.1 for USB devices. -
    -
    rom
    -
    The rom element is used to change how a PCI - device's ROM is presented to the guest. The optional bar - attribute can be set to "on" or "off", and determines whether - or not the device's ROM will be visible in the guest's memory - map. (In PCI documentation, the "rombar" setting controls the - presence of the Base Address Register for the ROM). If no rom - bar is specified, the qemu default will be used (older - versions of qemu used a default of "off", while newer qemus - have a default of "on"). Since - 0.9.7 (QEMU and KVM only). The optional - file attribute contains an absolute path to a binary = file - to be presented to the guest as the device's ROM BIOS. This - can be useful, for example, to provide a PXE boot ROM for a - virtual function of an sr-iov capable ethernet device (which - has no boot ROMs for the VFs). - Since 0.9.10 (QEMU and KVM only). - The optional enabled attribute can be set to - no to disable PCI ROM loading completely for the devi= ce; - if PCI ROM loading is disabled through this attribute, attempts to - tweak the loading process further using the bar or - file attributes will be rejected. - Since 4.3.0 (QEMU and KVM only). -
    -
    address
    -
    The address element for USB devices has a - bus and device attribute to specify the - USB bus and device number the device appears at on the host. - The values of these attributes can be given in decimal, hexadecimal - (starting with 0x) or octal (starting with 0) form. - For PCI devices the element carries 4 attributes allowing to designa= te - the device as can be found with the lspci or - with virsh nodedev-list. For SCSI devices a 'drive' - address type must be used. For mediated devices, which are software-= only - devices defining an allocation of resources on the physical parent d= evice, - the address type used must conform to the model attribu= te - of element hostdev, e.g. any address type other than PC= I for - vfio-pci device API or any address type other than CCW = for - vfio-ccw device API will result in an error. - See above for more details on the a= ddress - element.
    -
    driver
    -
    - PCI devices can have an optional driver - subelement that specifies which backend driver to use for PCI - device assignment. Use the name attribute to - select either "vfio" (for the new VFIO device assignment - backend, which is compatible with UEFI SecureBoot) or "kvm" - (the legacy device assignment handled directly by the KVM - kernel module)Since 1.0.5 (QEMU and KVM - only, requires kernel 3.6 or newer). When specified, - device assignment will fail if the requested method of device - assignment isn't available on the host. When not specified, - the default is "vfio" on systems where the VFIO driver is - available and loaded, and "kvm" on older systems, or those - where the VFIO driver hasn't been - loaded Since 1.1.3 (prior to that - the default was always "kvm"). -
    -
    readonly
    -
    Indicates that the device is readonly, only supported by SCSI ho= st - device now. Since 1.0.6 (QEMU and KVM only)<= /span> -
    -
    shareable
    -
    If present, this indicates the device is expected to be shared - between domains (assuming the hypervisor and OS support this). - Only supported by SCSI host device. - Since 1.0.6 -

    - Note: Although shareable was introduced - in 1.0.6, it did not work as - as expected until 1.2.2. -

    -
    -
    - - -
    Block / character devices
    - -

    - Block / character devices from the host can be passed through - to the guest using the hostdev element. This is - only possible with container based virtualization. Devices are speci= fied - by a fully qualified path. - since after 1.0.1 for LXC: -

    - - 
    -...
-<hostdev mode=3D'capabilities' type=3D'storage'>
-  <source>
-    <block>/dev/sdf1</block>
-  </source>
-</hostdev>
-...
-
    - - 
    -...
-<hostdev mode=3D'capabilities' type=3D'misc'>
-  <source>
-    <char>/dev/input/event3</char>
-  </source>
-</hostdev>
-...
-
    - - 
    -...
-<hostdev mode=3D'capabilities' type=3D'net'>
-  <source>
-    <interface>eth0</interface>
-  </source>
-</hostdev>
-...
-
    - -
    -
    hostdev
    -
    The hostdev element is the main container for descr= ibing - host devices. For block/character device passthrough mode is - always "capabilities" and type is "storage" for a blo= ck - device, "misc" for a character device and "net" for a host network - interface. -
    -
    source
    -
    The source element describes the device as seen from the host. - For block devices, the path to the block device in the host - OS is provided in the nested "block" element, while for character - devices the "char" element is used. For network interfaces, the - name of the interface is provided in the "interface" element. -
    -
    - -

    Redirected devices

    - -

    - USB device redirection through a character device is - supported since after 0.9.5 (KVM - only): -

    - -
    -...
-<devices>
-  <redirdev bus=3D'usb' type=3D'tcp'>
-    <source mode=3D'connect' host=3D'localhost' service=3D'4000'/>
-    <boot order=3D'1'/>
-  </redirdev>
-  <redirfilter>
-    <usbdev class=3D'0x08' vendor=3D'0x1234' product=3D'0xbeef' version=
=3D'2.56' allow=3D'yes'/>
-    <usbdev allow=3D'no'/>
-  </redirfilter>
-</devices>
-...
    - -
    -
    redirdev
    -
    The redirdev element is the main container for - describing redirected devices. bus must be "usb" - for a USB device. - - An additional attribute type is required, - matching one of the - supported serial device types, - to describe the host side of the - tunnel; type=3D'tcp' - or type=3D'spicevmc' (which uses the usbredir - channel of a SPICE graphics - device) are typical. The redirdev element has an optional - sub-element <address> which can tie the - device to a particular controller. Further sub-elements, - such as <source>, may be required according - to the given type, although a <target> sub-elem= ent - is not required (since the consumer of the character device is - the hypervisor itself, rather than a device visible in the guest). -
    -
    boot
    - -
    Specifies that the device is bootable. - The order attribute determines the order in which - devices will be tried during boot sequence. The per-device - boot elements cannot be used together with general - boot elements in BIOS bootloader = section. - (Since 1.0.1) -
    -
    redirfilter
    -
    The redirfilter element is used for creating the - filter rule to filter out certain devices from redirection. - It uses sub-element <usbdev> to define each fil= ter rule. - class attribute is the USB Class code, for example, - 0x08 represents mass storage devices. The USB device can be addres= sed by - vendor / product id using the vendor and produc= t attributes. - version is the device revision from the bcdDevice fie= ld (not - the version of the USB protocol). - These four attributes are optional and -1 can be used= to allow - any value for them. allow attribute is mandatory, - 'yes' means allow, 'no' for deny. -
    -
    - -

    Smartcard devices

    - -

    - A virtual smartcard device can be supplied to the guest via the - smartcard element. A USB smartcard reader device on - the host cannot be used on a guest with simple device - passthrough, since it will then not be available on the host, - possibly locking the host computer when it is "removed". - Therefore, some hypervisors provide a specialized virtual device - that can present a smartcard interface to the guest, with - several modes for describing how credentials are obtained from - the host or even a from a channel created to a third-party - smartcard provider. Since 0.8.8 -

    - -
    -...
-<devices>
-  <smartcard mode=3D'host'/>
-  <smartcard mode=3D'host-certificates'>
-    <certificate>cert1</certificate>
-    <certificate>cert2</certificate>
-    <certificate>cert3</certificate>
-    <database>/etc/pki/nssdb/</database>
-  </smartcard>
-  <smartcard mode=3D'passthrough' type=3D'tcp'>
-    <source mode=3D'bind' host=3D'127.0.0.1' service=3D'2001'/>
-    <protocol type=3D'raw'/>
-    <address type=3D'ccid' controller=3D'0' slot=3D'0'/>
-  </smartcard>
-  <smartcard mode=3D'passthrough' type=3D'spicevmc'/>
-</devices>
-...
-
    - -

    - The <smartcard> element has a mandatory - attribute mode. The following modes are supported; - in each mode, the guest sees a device on its USB bus that - behaves like a physical USB CCID (Chip/Smart Card Interface - Device) card. -

    - -
    -
    host
    -
    The simplest operation, where the hypervisor relays all - requests from the guest into direct access to the host's - smartcard via NSS. No other attributes or sub-elements are - required. See below about the use of an - optional <address> sub-element.
    - -
    host-certificates
    -
    Rather than requiring a smartcard to be plugged into the - host, it is possible to provide three NSS certificate names - residing in a database on the host. These certificates can be - generated via the command certutil -d /etc/pki/nssdb -x -t - CT,CT,CT -S -s CN=3Dcert1 -n cert1, and the resulting three - certificate names must be supplied as the content of each of - three <certificate> sub-elements. An - additional sub-element <database> can specify - the absolute path to an alternate directory (matching - the -d option of the certutil command - when creating the certificates); if not present, it defaults to - /etc/pki/nssdb.
    - -
    passthrough
    -
    Rather than having the hypervisor directly communicate with - the host, it is possible to tunnel all requests through a - secondary character device to a third-party provider (which may - in turn be talking to a smartcard or using three certificate - files). In this mode of operation, an additional - attribute type is required, matching one of the - supported serial device types, to - describe the host side of the tunnel; type=3D'tcp' - or type=3D'spicevmc' (which uses the smartcard - channel of a SPICE graphics - device) are typical. Further sub-elements, such - as <source>, may be required according to the - given type, although a <target> sub-element - is not required (since the consumer of the character device is - the hypervisor itself, rather than a device visible in the - guest).
    -
    - -

    - Each mode supports an optional - sub-element <address>, which fine-tunes the - correlation between the smartcard and a ccid bus - controller, documented above. - For now, qemu only supports at most one - smartcard, with an address of bus=3D0 slot=3D0. -

    - -

    Network interfaces

    - -
    -...
-<devices>
-  <interface type=3D'direct' trustGuestRxFilters=3D'yes'>
-    <source dev=3D'eth0'/>
-    <mac address=3D'52:54:00:5d:c7:9e'/>
-    <boot order=3D'1'/>
-    <rom bar=3D'off'/>
-  </interface>
-</devices>
-...
    - -

    - There are several possibilities for specifying a network - interface visible to the guest. Each subsection below provides - more details about common setup options. -

    -

    - Since 1.2.10), - the interface element - property trustGuestRxFilters provides the - capability for the host to detect and trust reports from the - guest regarding changes to the interface mac address and receive - filters by setting the attribute to yes. The default - setting for the attribute is no for security - reasons and support depends on the guest network device model as - well as the type of connection on the host - currently it is - only supported for the virtio device model and for macvtap - connections on the host. -

    -

    - Each <interface> element has an - optional <address> sub-element that can tie - the interface to a particular pci slot, with - attribute type=3D'pci' - as documented above. -

    -

    - Since 6.6.0, one can force libvirt to k= eep the - provided MAC address when it's in the reserved VMware range by addin= g a - type=3D"static" attribute to the <mac/> element. - Note that this attribute is useless if the provided MAC address is o= utside of - the reserved VMWare ranges. -

    - -
    Virtual network
    - -

    - - This is the recommended config for general guest connectivity on - hosts with dynamic / wireless networking configs (or multi-host - environments where the host hardware details are described - separately in a <network> - definition Since 0.9.4). - -

    - -

    - - Provides a connection whose details are described by the named - network definition. Depending on the virtual network's "forward - mode" configuration, the network may be totally isolated - (no <forward> element given), NAT'ing to an - explicit network device or to the default route - (<forward mode=3D'nat'>), routed with no NAT - (<forward mode=3D'route'/>), or connected - directly to one of the host's network interfaces (via macvtap) - or bridge devices ((<forward - mode=3D'bridge|private|vepa|passthrough'/> Since - 0.9.4) -

    -

    - For networks with a forward mode of bridge, private, vepa, and - passthrough, it is assumed that the host has any necessary DNS - and DHCP services already setup outside the scope of libvirt. In - the case of isolated, nat, and routed networks, DHCP and DNS are - provided on the virtual network by libvirt, and the IP range can - be determined by examining the virtual network config with - 'virsh net-dumpxml [networkname]'. There is one - virtual network called 'default' setup out of the box which does - NAT'ing to the default route and has an IP range - of 192.168.122.0/255.255.255.0. Each guest will - have an associated tun device created with a name of vnetN, - which can also be overridden with the <target> element - (see - overriding the target elemen= t). -

    -

    - When the source of an interface is a network, - a portgroup can be specified along with the name of - the network; one network may have multiple portgroups defined, - with each portgroup containing slightly different configuration - information for different classes of network - connections. Since 0.9.4. -

    -

    - When a guest is running an interface of type network - may include a portid attribute. This provides the UUID - of an associated virNetworkPortPtr object that records the associati= on - between the domain interface and the network. This attribute is - read-only since port objects are create and deleted automatically - during startup and shutdown. Since 5.1.0 -

    -

    - Also, similar to direct network connections - (described below), a connection of type network may - specify a virtualport element, with configuration - data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant - switch (Since 0.8.2), or to an - Open vSwitch virtual switch (Since - 0.9.11). -

    -

    - Since the actual type of switch may vary depending on the - configuration in the <network> on the host, - it is acceptable to omit the virtualport type - attribute, and specify attributes from multiple different - virtualport types (and also to leave out certain attributes); at - domain startup time, a complete <virtualport> - element will be constructed by merging together the type and - attributes defined in the network and the portgroup referenced - by the interface. The newly-constructed virtualport is a combination - of them. The attributes from lower virtualport can't make change - on the ones defined in higher virtualport. - Interface takes the highest priority, portgroup is lowest priority. - (Since 0.10.0). For example, in order - to work properly with both an 802.1Qbh switch and an Open vSwitch - switch, you may choose to specify no type, but both - a profileid (in case the switch is 802.1Qbh) and - an interfaceid (in case the switch is Open vSwitch) - (you may also omit the other attributes, such as managerid, - typeid, or profileid, to be filled in from the - network's <virtualport>). If you want to - limit a guest to connecting only to certain types of switches, - you can specify the virtualport type, but still omit some/all of - the parameters - in this case if the host's network has a - different type of virtualport, connection of the interface will - fail. -

    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-  </interface>
-  ...
-  <interface type=3D'network'>
-    <source network=3D'default' portgroup=3D'engineering'/>
-    <target dev=3D'vnet7'/>
-    <mac address=3D"00:11:22:33:44:55"/>
-    <virtualport>
-      <parameters instanceid=3D'09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&=
gt;
-    </virtualport>
-  </interface>
-</devices>
-...
    - -
    Bridge to LAN
    - -

    - - This is the recommended config for general guest connectivity on - hosts with static wired networking configs. - -

    - -

    - Provides a bridge from the VM directly to the LAN. This assumes - there is a bridge device on the host which has one or more of the ho= sts - physical NICs attached. The guest VM will have an associated tun dev= ice - created with a name of vnetN, which can also be overridden with the - <target> element (see - overriding the target elemen= t). - The tun device will be attached to the bridge. The IP range / network - configuration is whatever is used on the LAN. This provides the gues= t VM - full incoming & outgoing net access just like a physical machine. -

    -

    - On Linux systems, the bridge device is normally a standard Linux - host bridge. On hosts that support Open vSwitch, it is also - possible to connect to an Open vSwitch bridge device by adding - a <virtualport type=3D'openvswitch'/> to the - interface definition. (Since - 0.9.11). The Open vSwitch type virtualport accepts two - parameters in its <parameters> element - - an interfaceid which is a standard uuid used to - uniquely identify this particular interface to Open vSwitch (if - you do not specify one, a random interfaceid will be generated - for you when you first define the interface), and an - optional profileid which is sent to Open vSwitch as - the interfaces "port-profile". -

    -
    -...
-<devices>
-  ...
-  <interface type=3D'bridge'>
-    <source bridge=3D'br0'/>
-  </interface>
-  <interface type=3D'bridge'>
-    <source bridge=3D'br1'/>
-    <target dev=3D'vnet7'/>
-    <mac address=3D"00:11:22:33:44:55"/>
-  </interface>
-  <interface type=3D'bridge'>
-    <source bridge=3D'ovsbr'/>
-    <virtualport type=3D'openvswitch'>
-      <parameters profileid=3D'menial' interfaceid=3D'09b11c53-8b5c-4ee=
b-8f00-d84eaa0aaa4f'/>
-    </virtualport>
-  </interface>
-  ...
-</devices>
-...
    - -

    - On hosts that support Open vSwitch on the kernel side and have the - Midonet Host Agent configured, it is also possible to connect to the - 'midonet' bridge device by adding a - <virtualport type=3D'midonet'/> to the - interface definition. (Since - 1.2.13). The Midonet virtualport type requires an - interfaceid attribute in its - <parameters> element. This interface id is the UU= ID - that specifies which port in the virtual network topology will be bo= und - to the interface. -

    -
    -...
-<devices>
-  ...
-  <interface type=3D'bridge'>
-    <source bridge=3D'br0'/>
-  </interface>
-  <interface type=3D'bridge'>
-    <source bridge=3D'br1'/>
-    <target dev=3D'vnet7'/>
-    <mac address=3D"00:11:22:33:44:55"/>
-  </interface>
-  <interface type=3D'bridge'>
-    <source bridge=3D'midonet'/>
-    <virtualport type=3D'midonet'>
-      <parameters interfaceid=3D'0b2d64da-3d0e-431e-afdd-804415d6ebbb'/=
>
-    </virtualport>
-  </interface>
-  ...
-</devices>
-...
    - -
    Userspace SLIRP stack
    - -

    - Provides a virtual LAN with NAT to the outside world. The virtual - network has DHCP & DNS services and will give the guest VM addre= sses - starting from 10.0.2.15. The default router will be - 10.0.2.2 and the DNS server will be 10.0.2.3. - This networking is the only option for unprivileged users who need t= heir - VMs to have outgoing access. Since 3.8.0 - it is possible to override the default network address by - including an ip element specifying an IPv4 - address in its one mandatory attribute, address. - Optionally, a second ip element with a - family attribute set to "ipv6" can be - specified to add an IPv6 address to the interface. - address. Optionally, address - prefix can be specified. -

    - -
    -...
-<devices>
-  <interface type=3D'user'/>
-  ...
-  <interface type=3D'user'>
-    <mac address=3D"00:11:22:33:44:55"/>
-    <ip family=3D'ipv4' address=3D'172.17.2.0' prefix=3D'24'/>
-    <ip family=3D'ipv6' address=3D'2001:db8:ac10:fd01::' prefix=3D'64'/=
>
-  </interface>
-</devices>
-...
    - - -
    Generic ethernet connection
    - -

    - Provides a means to use a new or existing tap device (or veth - device pair, depening on the needs of the hypervisor driver) - that is partially or wholly setup external to libvirt (either - prior to the guest starting, or while the guest is being started - via an optional script specified in the config). -

    -

    - The name of the tap device can optionally be specified with - the dev attribute of the - <target> element. If no target dev is - specified, libvirt will create a new standard tap device with a - name of the pattern "vnetN", where "N" is replaced with a - number. If a target dev is specified and that device doesn't - exist, then a new standard tap device will be created with the - exact dev name given. If the specified target dev does exist, - then that existing device will be used. Usually some basic setup - of the device is done by libvirt, including setting a MAC - address, and the IFF_UP flag, but if the dev is a - pre-existing device, and the managed attribute of - the target element is also set to "no" (the default - value is "yes"), even this basic setup will not be performed - - libvirt will simply pass the device on to the hypervisor with no - setup at all. Since 5.7.0 Using - managed=3D'no' with a pre-created tap device is useful because - it permits a virtual machine managed by an unprivileged libvirtd - to have emulated network devices based on tap devices. -

    -

    - After creating/opening the tap device, an optional shell script - (given in the path attribute of - the <script> element) will be run. - Since 0.2.1 - Also, after detaching/closing the tap device, an optional shell - script (given in the path attribute of - the <downscript> element) will be run. - Since 5.1.0 - These can be used to do whatever extra host network integration is - required. -

    - -
    -...
-<devices>
-  <interface type=3D'ethernet'>
-    <script path=3D'/etc/qemu-ifup-mynet'/>
-    <downscript path=3D'/etc/qemu-ifdown-mynet'/>
-  </interface>
-  ...
-  <interface type=3D'ethernet'>
-    <target dev=3D'mytap1' managed=3D'no'/>
-    <model type=3D'virtio'/>
-  </interface>
-</devices>
-...
    - -
    Direct attachment to physical interfa= ce
    - -

    - Provides direct attachment of the virtual machine's NIC to the given - physical interface of the host. - Since 0.7.7 (QEMU and KVM only)
    - This setup requires the Linux macvtap - driver to be available. (Since Linux 2.6.34.)<= /span> - One of the modes 'vepa' - ( - 'Virtual Ethernet Port Aggregator'), 'bridge' or 'private' - can be chosen for the operation mode of the macvtap device, 'vepa' - being the default mode. The individual modes cause the delivery of - packets to behave as follows: -

    -

    - If the model type is set to virtio and - interface's trustGuestRxFilters attribute is set - to yes, changes made to the interface mac address, - unicast/multicast receive filters, and vlan settings in the - guest will be monitored and propagated to the associated macvtap - device on the host (Since - 1.2.10). If trustGuestRxFilters is not set, - or is not supported for the device model in use, an attempted - change to the mac address originating from the guest side will - result in a non-working network connection. -

    - -
    -
    vepa
    -
    All VMs' packets are sent to the external bridge. Packets - whose destination is a VM on the same host as where the - packet originates from are sent back to the host by the VEPA - capable bridge (today's bridges are typically not VEPA capable).
    -
    bridge
    -
    Packets whose destination is on the same host as where they - originate from are directly delivered to the target macvtap device. - Both origin and destination devices need to be in bridge mode - for direct delivery. If either one of them is in vepa m= ode, - a VEPA capable bridge is required.
    -
    private
    -
    All packets are sent to the external bridge and will only be - delivered to a target VM on the same host if they are sent through an - external router or gateway and that device sends them back to the - host. This procedure is followed if either the source or destination - device is in private mode.
    -
    passthrough
    -
    This feature attaches a virtual function of a SRIOV capable - NIC directly to a VM without losing the migration capability. - All packets are sent to the VF/IF of the configured network device. - Depending on the capabilities of the device additional prerequisites= or - limitations may apply; for example, on Linux this requires - kernel 2.6.38 or newer. Since 0.9.2
    -
    - -
    -...
-<devices>
-  ...
-  <interface type=3D'direct' trustGuestRxFilters=3D'no'>
-    <source dev=3D'eth0' mode=3D'vepa'/>
-  </interface>
-</devices>
-...
    - -

    - The network access of direct attached virtual machines can be - managed by the hardware switch to which the physical interface - of the host machine is connected to. -

    -

    - The interface can have additional parameters as shown below, - if the switch is conforming to the IEEE 802.1Qbg standard. - The parameters of the virtualport element are documented in more det= ail - in the IEEE 802.1Qbg standard. The values are network specific and - should be provided by the network administrator. In 802.1Qbg terms, - the Virtual Station Interface (VSI) represents the virtual interface - of a virtual machine. Since 0.8.2 -

    -

    - Please note that IEEE 802.1Qbg requires a non-zero value for the - VLAN ID. -

    -
    -
    managerid
    -
    The VSI Manager ID identifies the database containing the VSI ty= pe - and instance definitions. This is an integer value and the - value 0 is reserved.
    -
    typeid
    -
    The VSI Type ID identifies a VSI type characterizing the network - access. VSI types are typically managed by network administrator. - This is an integer value. -
    -
    typeidversion
    -
    The VSI Type Version allows multiple versions of a VSI Type. - This is an integer value. -
    -
    instanceid
    -
    The VSI Instance ID Identifier is generated when a VSI instance - (i.e. a virtual interface of a virtual machine) is created. - This is a globally unique identifier. -
    -
    -
    -...
-<devices>
-  ...
-  <interface type=3D'direct'>
-    <source dev=3D'eth0.2' mode=3D'vepa'/>
-    <virtualport type=3D"802.1Qbg">
-      <parameters managerid=3D"11" typeid=3D"1193047" typeidversion=3D"=
2" instanceid=3D"09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
-    </virtualport>
-  </interface>
-</devices>
-...
    - -

    - The interface can have additional parameters as shown below - if the switch is conforming to the IEEE 802.1Qbh standard. - The values are network specific and should be provided by the - network administrator. Since 0.8.2 -

    -
    -
    profileid
    -
    The profile ID contains the name of the port profile that is to - be applied to this interface. This name is resolved by the port - profile database into the network parameters from the port profile, - and those network parameters will be applied to this interface. -
    -
    - 
    -...
-<devices>
-  ...
-  <interface type=3D'direct'>
-    <source dev=3D'eth0' mode=3D'private'/>
-    <virtualport type=3D'802.1Qbh'>
-      <parameters profileid=3D'finance'/>
-    </virtualport>
-  </interface>
-</devices>
-...
-
    - - -
    PCI Passthrough
    - -

    - A PCI network device (specified by the <source> element) - is directly assigned to the guest using generic device - passthrough, after first optionally setting the device's MAC - address to the configured value, and associating the device with - an 802.1Qbh capable switch using an optionally specified - <virtualport> element (see the examples of virtualport - given above for type=3D'direct' network devices). Note that - due - to limitations in standard single-port PCI ethernet card driver - design - only SR-IOV (Single Root I/O Virtualization) virtual - function (VF) devices can be assigned in this manner; to assign - a standard single-port PCI or PCIe ethernet card to a guest, use - the traditional <hostdev> device definition and - Since 0.9.11 -

    - -

    - To use VFIO device assignment rather than traditional/legacy KVM - device assignment (VFIO is a new method of device assignment - that is compatible with UEFI Secure Boot), a type=3D'hostdev' - interface can have an optional driver sub-element - with a name attribute set to "vfio". To use legacy - KVM device assignment you can set name to "kvm" (or - simply omit the <driver> element, since "kvm" - is currently the default). - Since 1.0.5 (QEMU and KVM only, requires kerne= l 3.6 or newer) -

    - -

    - Note that this "intelligent passthrough" of network devices is - very similar to the functionality of a standard <hostdev> - device, the difference being that this method allows specifying - a MAC address and <virtualport> for the passed-through - device. If these capabilities are not required, if you have a - standard single-port PCI, PCIe, or USB network card that doesn't - support SR-IOV (and hence would anyway lose the configured MAC - address during reset after being assigned to the guest domain), - or if you are using a version of libvirt older than 0.9.11, you - should use standard <hostdev> to assign the device to the - guest instead of <interface type=3D'hostdev'/>. -

    - -

    - Similar to the functionality of a standard <hostdev> device, - when managed is "yes", it is detached from the host - before being passed on to the guest, and reattached to the host - after the guest exits. If managed is omitted or "no", - the user is responsible to call virNodeDeviceDettach - (or virsh nodedev-detach) before starting the guest - or hot-plugging the device, and virNodeDeviceReAttach - (or virsh nodedev-reattach) after hot-unplug or - stopping the guest. -

    - -
    -...
-<devices>
-  <interface type=3D'hostdev' managed=3D'yes'>
-    <driver name=3D'vfio'/>
-    <source>
-      <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x07=
' function=3D'0x0'/>
-    </source>
-    <mac address=3D'52:54:00:6d:90:02'/>
-    <virtualport type=3D'802.1Qbh'>
-      <parameters profileid=3D'finance'/>
-    </virtualport>
-  </interface>
-</devices>
-...
    - -
    Teaming a virtio/hostdev NIC pair - -

    - Since 6.1.0 (QEMU and KVM only, requires - QEMU 4.2.0 or newer and a guest virtio-net driver supporting - the "failover" feature, such as the one included in Linux - kernel 4.18 and newer) - - The <teaming> element of two interfaces can - be used to connect them as a team/bond device in the guest - (assuming proper support in the hypervisor and the guest - network driver). -

    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'mybridge'/>
-    <mac address=3D'00:11:22:33:44:55'/>
-    <model type=3D'virtio'/>
-    <teaming type=3D'persistent'/>
-    <alias name=3D'ua-backup0'/>
-  </interface>
-  <interface type=3D'network'>
-    <source network=3D'hostdev-pool'/>
-    <mac address=3D'00:11:22:33:44:55'/>
-    <model type=3D'virtio'/>
-    <teaming type=3D'transient' persistent=3D'ua-backup0'/>
-  </interface>
-</devices>
-...
    - -

    - The <teaming> element required - attribute type will be set to - either "persistent" to indicate a device that - should always be present in the domain, - or "transient" to indicate a device that may - periodically be removed, then later re-added to the domain. When - type=3D"transient", there should be a second attribute - to <teaming> called "persistent" - - this attribute should be set to the alias name of the other - device in the pair (the one that has <teaming - type=3D"persistent'/>). -

    -

    - In the particular case of QEMU, - libvirt's <teaming> element is used to setup - a virtio-net "failover" device pair. For this setup, the - persistent device must be an interface with <model - type=3D"virtio"/>, and the transient device must - be <interface type=3D'hostdev'/> - (or <interface type=3D'network'/> where the - referenced network defines a pool of SRIOV VFs). The guest will - then have a simple network team/bond device made of the virtio - NIC + hostdev NIC pair. In this configuration, the - higher-performing hostdev NIC will normally be preferred for all - network traffic, but when the domain is migrated, QEMU will - automatically unplug the VF from the guest, and then hotplug a - similar device once migration is completed; while migration is - taking place, network traffic will use the virtio NIC. (Of - course the emulated virtio NIC and the hostdev NIC must be - connected to the same subnet for bonding to work properly). -

    -

    - NB1: Since you must know the alias name of the virtio NIC when - configuring the hostdev NIC, it will need to be manually set in - the virtio NIC's configuration (as with all other manually set - alias names, this means it must start with "ua-"). -

    -

    - NB2: Currently the only implementation of the guest OS - virtio-net driver supporting virtio-net failover requires that - the MAC addresses of the virtio and hostdev NIC must - match. Since that may not always be a requirement in the future, - libvirt doesn't enforce this limitation - it is up to the - person/management application that is creating the configuration - to assure the MAC addresses of the two devices match. -

    -

    - NB3: Since the PCI addresses of the SRIOV VFs on the hosts that - are the source and destination of the migration will almost - certainly be different, either higher level management software - will need to modify the <source> of the - hostdev NIC (<interface type=3D'hostdev'>) at - the start of migration, or (a simpler solution) the - configuration will need to use a libvirt "hostdev" virtual - network that maintains a pool of such devices, as is implied in - the example's use of the libvirt network named "hostdev-pool" - - as long as the hostdev network pools on both hosts have the same - name, libvirt itself will take care of allocating an appropriate - device on both ends of the migration. Similarly the XML for the - virtio interface must also either work correctly unmodified on - both the source and destination of the migration (e.g. by - connecting to the same bridge device on both hosts, or by using - the same virtual network), or the management software must - properly modify the interface XML during migration so that the - virtio device remains connected to the same network segment - before and after migration. -

    - -
    Multicast tunnel
    - -

    - A multicast group is setup to represent a virtual network. Any VMs - whose network devices are in the same multicast group can talk to ea= ch - other even across hosts. This mode is also available to unprivileged - users. There is no default DNS or DHCP support and no outgoing netwo= rk - access. To provide outgoing network access, one of the VMs should ha= ve a - 2nd NIC which is connected to one of the first 4 network types and d= o the - appropriate routing. The multicast protocol is compatible with that = used - by user mode linux guests too. The source address used must be from = the - multicast address block. -

    - -
    -...
-<devices>
-  <interface type=3D'mcast'>
-    <mac address=3D'52:54:00:6d:90:01'/>
-    <source address=3D'230.0.0.1' port=3D'5558'/>
-  </interface>
-</devices>
-...
    - -
    TCP tunnel
    - -

    - A TCP client/server architecture provides a virtual network. One VM - provides the server end of the network, all other VMS are configured= as - clients. All network traffic is routed between the VMs via the serve= r. - This mode is also available to unprivileged users. There is no defau= lt - DNS or DHCP support and no outgoing network access. To provide outgo= ing - network access, one of the VMs should have a 2nd NIC which is connec= ted - to one of the first 4 network types and do the appropriate routing.<= /p> - -

    -...
-<devices>
-  <interface type=3D'server'>
-    <mac address=3D'52:54:00:22:c9:42'/>
-    <source address=3D'192.168.0.1' port=3D'5558'/>
-  </interface>
-  ...
-  <interface type=3D'client'>
-    <mac address=3D'52:54:00:8b:c9:51'/>
-    <source address=3D'192.168.0.1' port=3D'5558'/>
-  </interface>
-</devices>
-...
    - -
    UDP unicast tunnel
    - -

    - A UDP unicast architecture provides a virtual network which enables - connections between QEMU instances using QEMU's UDP infrastructure. - - The xml "source" address is the endpoint address to which the UDP sock= et - packets will be sent from the host running QEMU. - The xml "local" address is the address of the interface from which the - UDP socket packets will originate from the QEMU host. - Since 1.2.20

    - -
    -...
-<devices>
-  <interface type=3D'udp'>
-    <mac address=3D'52:54:00:22:c9:42'/>
-    <source address=3D'127.0.0.1' port=3D'11115'>
-      <local address=3D'127.0.0.1' port=3D'11116'/>
-    </source>
-  </interface>
-</devices>
-...
    - -
    Setting the NIC model
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet1'/>
-    <model type=3D'ne2k_pci'/>
-  </interface>
-</devices>
-...
    - -

    - For hypervisors which support this, you can set the model of - emulated network interface card. -

    - -

    - The values for type aren't defined specifically by - libvirt, but by what the underlying hypervisor supports (if - any). For QEMU and KVM you can get a list of supported models - with these commands: -

    - -
    -qemu -net nic,model=3D? /dev/null
-qemu-kvm -net nic,model=3D? /dev/null
-
    - -

    - Typical values for QEMU and KVM include: - ne2k_isa i82551 i82557b i82559er ne2k_pci pcnet rtl8139 e1000 virtio. - Since 5.2.0, virtio-transitional<= /code> - and virtio-non-transitional values are supported. - See Virtio transitional devi= ces - for more details. -

    - -
    Setting NIC driver-specific= options
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet1'/>
-    <model type=3D'virtio'/>
-    <driver name=3D'vhost' txmode=3D'iothread' ioeventfd=3D'on' even=
t_idx=3D'off' queues=3D'5' rx_queue_size=3D'256' tx_queue_size=3D'256'>
-      <host csum=3D'off' gso=3D'off' tso4=3D'off' tso6=3D'off' ecn=3D'o=
ff' ufo=3D'off' mrg_rxbuf=3D'off'/>
-      <guest csum=3D'off' tso4=3D'off' tso6=3D'off' ecn=3D'off' ufo=3D'=
off'/>
-    </driver>
-    </interface>
-</devices>
-...
    - -

    - Some NICs may have tunable driver-specific options. These are - set as attributes of the driver sub-element of the - interface definition. Currently the following attributes are - available for the "virtio" NIC driver: -

    - -
    -
    name
    -
    - The optional name attribute forces which type of - backend driver to use. The value can be either 'qemu' (a - user-space backend) or 'vhost' (a kernel backend, which - requires the vhost module to be provided by the kernel); an - attempt to require the vhost driver without kernel support - will be rejected. If this attribute is not present, then the - domain defaults to 'vhost' if present, but silently falls back - to 'qemu' without error. - Since 0.8.8 (QEMU and KVM only) -
    -
    - For interfaces of type=3D'hostdev' (PCI passthrough devices) - the name attribute can optionally be set to - "vfio" or "kvm". "vfio" tells libvirt to use VFIO device - assignment rather than traditional KVM device assignment (VFIO - is a new method of device assignment that is compatible with - UEFI Secure Boot), and "kvm" tells libvirt to use the legacy - device assignment performed directly by the kvm kernel module - (the default is currently "kvm", but is subject to change). - Since 1.0.5 (QEMU and KVM only, requires - kernel 3.6 or newer) -
    -
    - For interfaces of type=3D'vhostuser', the name - attribute is ignored. The backend driver used is always - vhost-user. -
    - -
    txmode
    -
    - The txmode attribute specifies how to handle - transmission of packets when the transmit buffer is full. The - value can be either 'iothread' or 'timer'. - Since 0.8.8 (QEMU and KVM only)
    <= br/> - - If set to 'iothread', packet tx is all done in an iothread in - the bottom half of the driver (this option translates into - adding "tx=3Dbh" to the qemu commandline -device virtio-net-pci - option).

    - - If set to 'timer', tx work is done in qemu, and if there is - more tx data than can be sent at the present time, a timer is - set before qemu moves on to do other things; when the timer - fires, another attempt is made to send more data.

    - - The resulting difference, according to the qemu developer who - added the option is: "bh makes tx more asynchronous and reduces - latency, but potentially causes more processor bandwidth - contention since the CPU doing the tx isn't necessarily the - CPU where the guest generated the packets."

    - - In general you should leave this option alone, unless you - are very certain you know what you are doing. -
    -
    ioeventfd
    -
    - This optional attribute allows users to set - - domain I/O asynchronous handling for interface device. - The default is left to the discretion of the hypervisor. - Accepted values are "on" and "off". Enabling this allows - qemu to execute VM while a separate thread handles I/O. - Typically guests experiencing high system CPU utilization - during I/O will benefit from this. On the other hand, - on overloaded host it could increase guest I/O latency. - Since 0.9.3 (QEMU and KVM only)
    <= br/> - - In general you should leave this option alone, unless you - are very certain you know what you are doing. -
    -
    event_idx
    -
    - The event_idx attribute controls some aspects of - device event processing. The value can be either 'on' or 'off' - - if it is on, it will reduce the number of interrupts and - exits for the guest. The default is determined by QEMU; - usually if the feature is supported, default is on. In case - there is a situation where this behavior is suboptimal, this - attribute provides a way to force the feature off. - Since 0.9.5 (QEMU and KVM only)
    <= br/> - - In general you should leave this option alone, unless you - are very certain you know what you are doing. -
    -
    queues
    -
    - The optional queues attribute controls the number - of queues to be used for either - Multiqueue - virtio-net or vhost-user net= work - interfaces. Use of multiple packet processing queues requires the - interface having the <model type=3D'virtio'/> - element. Each queue will potentially be handled by a different - processor, resulting in much higher throughput. - virtio-net since 1.0.6 (QEMU and KVM only) - vhost-user since 1.2.17 (QEMU and KVM only)<= /span> -
    -
    rx_queue_size
    -
    - The optional rx_queue_size attribute controls - the size of virtio ring for each queue as described above. - The default value is hypervisor dependent and may change - across its releases. Moreover, some hypervisors may pose - some restrictions on actual value. For instance, latest - QEMU (as of 2016-09-01) requires value to be a power of two - from [256, 1024] range. - Since 2.3.0 (QEMU and KVM only)
    <= br/> - - In general you should leave this option alone, unless you - are very certain you know what you are doing. -
    -
    tx_queue_size
    -
    - The optional tx_queue_size attribute controls - the size of virtio ring for each queue as described above. - The default value is hypervisor dependent and may change - across its releases. Moreover, some hypervisors may pose - some restrictions on actual value. For instance, QEMU - v2.9 requires value to be a power of two from [256, 1024] - range. In addition to that, this may work only for a subset of - interface types, e.g. aforementioned QEMU enables this option - only for vhostuser type. - Since 3.7.0 (QEMU and KVM only)
    <= br/> - - In general you should leave this option alone, unless you - are very certain you know what you are doing. -
    -
    virtio options
    -
    - For virtio interfaces, - Virtio-specific options can also be - set. (Since 3.5.0) -
    -
    -

    - Offloading options for the host and guest can be configured using - the following sub-elements: -

    -
    -
    host
    -
    - The csum, gso, tso4, - tso6, ecn and ufo - attributes with possible values on - and off can be used to turn off host offloading optio= ns. - By default, the supported offloads are enabled by QEMU. - Since 1.2.9 (QEMU only) - The mrg_rxbuf attribute can be used to control - mergeable rx buffers on the host side. Possible values are - on (default) and off. - Since 1.2.13 (QEMU only) -
    -
    guest
    -
    - The csum, tso4, - tso6, ecn and ufo - attributes with possible values on - and off can be used to turn off guest offloading opti= ons. - By default, the supported offloads are enabled by QEMU. - Since 1.2.9 (QEMU only) -
    -
    - -
    Setting network backend-specific = options
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet1'/>
-    <model type=3D'virtio'/>
-    <backend tap=3D'/dev/net/tun' vhost=3D'/dev/vhost-net'/>
-    <driver name=3D'vhost' txmode=3D'iothread' ioeventfd=3D'on' event_i=
dx=3D'off' queues=3D'5'/>
-    <tune>
-      <sndbuf>1600</sndbuf>
-    </tune>
-  </interface>
-</devices>
-...
    - -

    - For tuning the backend of the network, the backend elem= ent - can be used. The vhost attribute can override the defau= lt vhost - device path (/dev/vhost-net) for devices with vir= tio model. - The tap attribute overrides the tun/tap device path (de= fault: - /dev/net/tun) for network and bridge interfaces. This d= oes not work - in session mode. Since 1.2.9 -

    -

    - For tap devices there is also sndbuf element which can - adjust the size of send buffer in the host. Si= nce - 0.8.8 -

    -
    Overriding the target element=
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet1'/>
-  </interface>
-</devices>
-...
    - -

    - If no target is specified, certain hypervisors will - automatically generate a name for the created tun device. This - name can be manually specified, however the name should not - start with either 'vnet', 'vif', 'macvtap', or 'macvlan', - which are prefixes reserved by libvirt and certain hypervisors. - Manually specified targets using these prefixes may be ignored. -

    - -

    - Note that for LXC containers, this defines the name of the interface - on the host side. Since 1.2.7, to define - the name of the device on the guest side, the guest - element should be used, as in the following snippet: -

    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <guest dev=3D'myeth'/>
-  </interface>
-</devices>
-...
    - -
    Specifying boot order
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet1'/>
-    <boot order=3D'1'/>
-  </interface>
-</devices>
-...
    - -

    - For hypervisors which support this, you can set a specific NIC to - be used for network boot. The order attribute determines - the order in which devices will be tried during boot sequence. The - per-device boot elements cannot be used together with - general boot elements in - BIOS bootloader section. - Since 0.8.8 -

    - -
    Interface ROM BIOS configuration
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet1'/>
-    <rom bar=3D'on' file=3D'/etc/fake/boot.bin'/>
-  </interface>
-</devices>
-...
    - -

    - For hypervisors which support this, you can change how a PCI Network - device's ROM is presented to the guest. The bar - attribute can be set to "on" or "off", and determines whether - or not the device's ROM will be visible in the guest's memory - map. (In PCI documentation, the "rombar" setting controls the - presence of the Base Address Register for the ROM). If no rom - bar is specified, the qemu default will be used (older - versions of qemu used a default of "off", while newer qemus - have a default of "on"). - The optional file attribute is used to point to a - binary file to be presented to the guest as the device's ROM - BIOS. This can be useful to provide an alternative boot ROM for a - network device. - Since 0.9.10 (QEMU and KVM only). -

    -
    Setting up a network backend in a driver d= omain
    -
    -...
-<devices>
-  ...
-  <interface type=3D'bridge'>
-    <source bridge=3D'br0'/>
-    <backenddomain name=3D'netvm'/>
-  </interface>
-  ...
-</devices>
-...
    - -

    - The optional backenddomain element allows specifying a - backend domain (aka driver domain) for the interface. Use the - name attribute to specify the backend domain name. You - can use it to create a direct network link between domains (so data - will not go through host system). Use with type 'ethernet' to create - plain network link, or with type 'bridge' to connect to a bridge ins= ide - the backend domain. - Since 1.2.13 (Xen only) -

    - -
    Quality of service
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet0'/>
-    <bandwidth>
-      <inbound average=3D'1000' peak=3D'5000' floor=3D'200' burst=3D'10=
24'/>
-      <outbound average=3D'128' peak=3D'256' burst=3D'256'/>
-    </bandwidth>
-  </interface>
-</devices>
-...
    - -

    - This part of interface XML provides setting quality of service. Inco= ming - and outgoing traffic can be shaped independently. - The bandwidth element and its child elements are descri= bed - in the QoS section of - the Network XML. -

    - -
    Setting VLAN tag (on supported network ty= pes only)
    - -
    -...
-<devices>
-  <interface type=3D'bridge'>
-    <vlan>
-      <tag id=3D'42'/>
-    </vlan>
-    <source bridge=3D'ovsbr0'/>
-    <virtualport type=3D'openvswitch'>
-      <parameters interfaceid=3D'09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/=
>
-    </virtualport>
-  </interface>
-  <interface type=3D'bridge'>
-    <vlan trunk=3D'yes'>
-      <tag id=3D'42'/>
-      <tag id=3D'123' nativeMode=3D'untagged'/>
-    </vlan>
-    ...
-  </interface>
-</devices>
-...
    - -

    - If (and only if) the network connection used by the guest - supports VLAN tagging transparent to the guest, an - optional <vlan> element can specify one or - more VLAN tags to apply to the guest's network - traffic Since 0.10.0. Network - connections that support guest-transparent VLAN tagging include - 1) type=3D'bridge' interfaces connected to an Open vSwitch bridge - Since 0.10.0, 2) SRIOV Virtual - Functions (VF) used via type=3D'hostdev' (direct device - assignment) Since 0.10.0, and 3) - SRIOV VFs used via type=3D'direct' with mode=3D'passthrough' - (macvtap "passthru" mode) Since - 1.3.5. All other connection types, including standard - linux bridges and libvirt's own virtual networks, do not - support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches - provide their own way (outside of libvirt) to tag guest traffic - onto a specific VLAN. Each tag is given in a - separate <tag> subelement - of <vlan> (for example: <tag - id=3D'42'/>). For VLAN trunking of multiple tags (which - is supported only on Open vSwitch connections), - multiple <tag> subelements can be specified, - which implies that the user wants to do VLAN trunking on the - interface for all the specified tags. In the case that VLAN - trunking of a single tag is desired, the optional - attribute trunk=3D'yes' can be added to the toplevel - <vlan> element to differentiate trunking of a - single tag from normal tagging. -

    -

    - For network connections using Open vSwitch it is also possible - to configure 'native-tagged' and 'native-untagged' VLAN modes - Since 1.1.0. This is done with the - optional nativeMode attribute on - the <tag> subelement: nativeMode - may be set to 'tagged' or 'untagged'. The id - attribute of the <tag> subelement - containing nativeMode sets which VLAN is considered - to be the "native" VLAN for this interface, and - the nativeMode attribute determines whether or not - traffic for that VLAN will be tagged. -

    - -
    Isolating guests's network traffic from each= other
    - -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <port isolated=3D'yes'/>
-  </interface>
-</devices>
-...
    - -

    - Since 6.1.0. The port - element property isolated, when set - to yes (default setting is no) is used - to isolate this interface's network traffic from that of other - guest interfaces connected to the same network that also - have <port isolated=3D'yes'/>. This setting is - only supported for emulated interface devices that use a - standard tap device to connect to the network via a Linux host - bridge. This property can be inherited from a libvirt network, - so if all guests that will be connected to the network should be - isolated, it is better to put the setting in the network - configuration. (NB: this only prevents guests that - have isolated=3D'yes' from communicating with each - other; if there is a guest on the same bridge that doesn't - have isolated=3D'yes', even the isolated guests will - be able to communicate with it.) -

    - -
    Modifying virtual link state
    -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet0'/>
-    <link state=3D'down'/>
-  </interface>
-</devices>
-...
    - -

    - This element provides means of setting state of the virtual network = link. - Possible values for attribute state are up= and - down. If down is specified as the value, t= he interface - behaves as if it had the network cable disconnected. Default behavio= r if this - element is unspecified is to have the link state up. - Since 0.9.5 -

    - -
    MTU configuration
    -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet0'/>
-    <mtu size=3D'1500'/>
-  </interface>
-</devices>
-...
    - -

    - This element provides means of setting MTU of the virtual network li= nk. - Currently there is just one attribute size which accept= s a - non-negative integer which specifies the MTU size for the interface. - Since 3.1.0 -

    - -
    Coalesce settings
    -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet0'/>
-    <coalesce>
-      <rx>
-        <frames max=3D'7'/>
-      </rx>
-    </coalesce>
-  </interface>
-</devices>
-...
    - -

    - This element provides means of setting coalesce settings for - some interface devices (currently only type network - and bridge. Currently there is just one attribute, - max, to tweak, in element frames for - the rx group, which accepts a non-negative integer - that specifies the maximum number of packets that will be - received before an interrupt. - Since 3.3.0 -

    - -
    IP configuration
    -
    -...
-<devices>
-  <interface type=3D'network'>
-    <source network=3D'default'/>
-    <target dev=3D'vnet0'/>
-    <ip address=3D'192.168.122.5' prefix=3D'24'/>
-    <ip address=3D'192.168.122.5' prefix=3D'24' peer=3D'10.0.0.10'/&=
gt;
-    <route family=3D'ipv4' address=3D'192.168.122.0' prefix=3D'24' g=
ateway=3D'192.168.122.1'/>
-    <route family=3D'ipv4' address=3D'192.168.122.8' gateway=3D'192.=
168.122.1'/>
-  </interface>
-  ...
-  <hostdev mode=3D'capabilities' type=3D'net'>
-    <source>
-      <interface>eth0</interface>
-    </source>
-    <ip address=3D'192.168.122.6' prefix=3D'24'/>
-    <route family=3D'ipv4' address=3D'192.168.122.0' prefix=3D'24' g=
ateway=3D'192.168.122.1'/>
-    <route family=3D'ipv4' address=3D'192.168.122.8' gateway=3D'192.=
168.122.1'/>
-  </hostdev>
-  ...
-</devices>
-...
-
    - -

    - Since 1.2.12 network devices and - hostdev devices with network capabilities can optionally be provided - one or more IP addresses to set on the network device in the - guest. Note that some hypervisors or network device types will - simply ignore them or only use the first one. - The family attribute can be set to - either ipv4 or ipv6, and the - address attribute contains the IP address. The - optional prefix is the number of 1 bits in the - netmask, and will be automatically set if not specified - for - IPv4 the default prefix is determined according to the network - "class" (A, B, or C - see RFC870), and for IPv6 the default - prefix is 64. The optional peer attribute holds the - IP address of the other end of a point-to-point network - device (since 2.1.0). -

    - -

    - Since 1.2.12 route elements can also be - added to define IP routes to add in the guest. The attributes of - this element are described in the documentation for - the route element - in network - definitions. This is used by the LXC driver. -

    - -
    -...
-<devices>
-  <interface type=3D'ethernet'>
-    <source/>
-      <ip address=3D'192.168.123.1' prefix=3D'24'/>
-      <ip address=3D'10.0.0.10' prefix=3D'24' peer=3D'192.168.122.5'=
/>
-      <route family=3D'ipv4' address=3D'192.168.42.0' prefix=3D'24' =
gateway=3D'192.168.123.4'/>
-    <source/>
-    ...
-  </interface>
-  ...
-</devices>
-...
-
    - -

    - Since 2.1.0 network devices of type - "ethernet" can optionally be provided one or more IP addresses - and one or more routes to set on the host side of the - network device. These are configured as subelements of - the <source> element of the interface, and - have the same attributes as the similarly named elements used to - configure the guest side of the interface (described above). -

    - -
    vhost-user interface
    - -

    - Since 1.2.7 the vhost-user enables the - communication between a QEMU virtual machine and other userspace proce= ss - using the Virtio transport protocol. A char dev (e.g. Unix socket) is= used - for the control plane, while the data plane is based on shared memory. -

    - -
    -...
-<devices>
-  <interface type=3D'vhostuser'>
-    <mac address=3D'52:54:00:3b:83:1a'/>
-    <source type=3D'unix' path=3D'/tmp/vhost1.sock' mode=3D'server'/>
-    <model type=3D'virtio'/>
-  </interface>
-  <interface type=3D'vhostuser'>
-    <mac address=3D'52:54:00:3b:83:1b'/>
-    <source type=3D'unix' path=3D'/tmp/vhost2.sock' mode=3D'client'>
-      <reconnect enabled=3D'yes' timeout=3D'10'/>
-    </source>
-    <model type=3D'virtio'/>
-    <driver queues=3D'5'/>
-  </interface>
-</devices>
-...
    - -

    - The <source> element has to be specified - along with the type of char device. - Currently, only type=3D'unix' is supported, where the path (the - directory path of the socket) and mode attributes are required. - Both mode=3D'server' and mode=3D'client' - are supported. - vhost-user requires the virtio model type, thus the - <model> element is mandatory. - Since 4.1.0 the element has an - optional child element reconnect which - configures reconnect timeout if the connection is lost. It - has two attributes enabled (which accepts - yes and no) and - timeout which specifies the amount of seconds - after which hypervisor tries to reconnect. -

    - -
    Traffic filtering with NWFilter
    - -

    - Since 0.8.0 an nwfilter prof= ile - can be assigned to a domain interface, which allows configuring - traffic filter rules for the virtual machine. - - See the nwfilter documentation for= more - complete details. -

    - -
    -...
-<devices>
-  <interface ...>
-    ...
-    <filterref filter=3D'clean-traffic'/>
-  </interface>
-  <interface ...>
-    ...
-    <filterref filter=3D'myfilter'>
-      <parameter name=3D'IP' value=3D'104.207.129.11'/>
-      <parameter name=3D'IP6_ADDR' value=3D'2001:19f0:300:2102::'/>
-      <parameter name=3D'IP6_MASK' value=3D'64'/>
-      ...
-    </filterref>
-  </interface>
-</devices>
-...
    - -

    - The filter attribute specifies the name of the nwfilter - to use. Optional <parameter> elements may be - specified for passing additional info to the nwfilter via the - name and value attributes. See - the nwfilter - docs for info on parameters. -

    - - -

    Input devices

    - -

    - Input devices allow interaction with the graphical framebuffer - in the guest virtual machine. When enabling the framebuffer, an - input device is automatically provided. It may be possible to - add additional devices explicitly, for example, - to provide a graphics tablet for absolute cursor movement. -

    - -
    -...
-<devices>
-  <input type=3D'mouse' bus=3D'usb'/>
-  <input type=3D'keyboard' bus=3D'usb'/>
-  <input type=3D'mouse' bus=3D'virtio'/>
-  <input type=3D'keyboard' bus=3D'virtio'/>
-  <input type=3D'tablet' bus=3D'virtio'/>
-  <input type=3D'passthrough' bus=3D'virtio'>
-    <source evdev=3D'/dev/input/event1'/>
-  </input>
-</devices>
-...
    - -
    -
    input
    -
    The input element has one mandatory attribute, - the type whose value can be 'mouse', 'tablet', - (since 1.2.2) 'keyboard' or - (since 1.3.0) 'passthrough'. - The tablet provides absolute cursor movement, - while the mouse uses relative movement. The optional - bus attribute can be used to refine the exact device = type. - It takes values "xen" (paravirtualized), "ps2" and "usb" or - (since 1.3.0) "virtio".
    -
    - -

    - The input element has an optional - sub-element <address> which can tie the - device to a particular PCI - slot, documented above. - On S390, address can be used to provide a CCW address f= or - an input device (since 4.2.0). - - For type passthrough, the mandatory sub-element s= ource - must have an evdev attribute containing the absolute pa= th to the - event device passed through to guests. (KVM only) - - Since 5.2.0, the input ele= ment - accepts a model attribute which has the values 'virtio', - 'virtio-transitional' and 'virtio-non-transitional'. See - Virtio transitional devices<= /a> - for more details. -

    - -

    - The subelement driver can be used to tune the virtio - options of the device: - Virtio-specific options can also be - set. (Since 3.5.0) -

    - -

    Hub devices

    - -

    - A hub is a device that expands a single port into several so - that there are more ports available to connect devices to a host - system. -

    - -
    -...
-<devices>
-  <hub type=3D'usb'/>
-</devices>
-...
    - -
    -
    hub
    -
    The hub element has one mandatory attribute, - the type whose value can only be 'usb'.
    -
    - -

    - The hub element has an optional - sub-element <address> - with type=3D'usb'which can tie the device to a - particular controller, documented - above. -

    - -

    Graphical framebuffers

    - -

    - A graphics device allows for graphical interaction with the - guest OS. A guest will typically have either a framebuffer - or a text console configured to allow interaction with the - admin. -

    - -
    -...
-<devices>
-  <graphics type=3D'sdl' display=3D':0.0'/>
-  <graphics type=3D'vnc' port=3D'5904' sharePolicy=3D'allow-exclusive'&=
gt;
-    <listen type=3D'address' address=3D'1.2.3.4'/>
-  </graphics>
-  <graphics type=3D'rdp' autoport=3D'yes' multiUser=3D'yes' />
-  <graphics type=3D'desktop' fullscreen=3D'yes'/>
-  <graphics type=3D'spice'>
-    <listen type=3D'network' network=3D'rednet'/>
-  </graphics>
-</devices>
-...
    - -
    -
    graphics
    -
    -

    - The graphics element has a mandatory type - attribute which takes the value sdl, vnc, - spice, rdp, desktop or - egl-headless: -

    -
    -
    sdl
    -
    -

    - This displays a window on the host desktop, it can take 3 op= tional - arguments: a display attribute for the display = to use, - an xauth attribute for the authentication ident= ifier, - and an optional fullscreen attribute accepting = values - yes or no. -

    - -

    - You can use a gl with the enable=3D"yes"<= /code> - property to enable OpenGL support in SDL. Likewise you can - explicitly disable OpenGL support with enable=3D"no". -

    -
    -
    vnc
    -
    -

    - Starts a VNC server. The port attribute specifi= es - the TCP port number (with -1 as legacy syntax indicating tha= t it - should be auto-allocated). The autoport attribu= te is - the new preferred syntax for indicating auto-allocation of t= he TCP - port to use. The passwd attribute provides a VNC - password in clear text. If the passwd attribute= is - set to an empty string, then VNC access is disabled. The - keymap attribute specifies the keymap to use. I= t is - possible to set a limit on the validity of the password by g= iving - a timestamp passwdValidTo=3D'2010-04-09T15:51:00' - assumed to be in UTC. The connected attribute a= llows - control of connected client during password changes. VNC acc= epts - keep value only since 0.9= .3. - NB, this may not be supported by all hypervisors. -

    -

    - The optional sharePolicy attribute specifies vnc - server display sharing policy. allow-exclusive = allows - clients to ask for exclusive access by dropping other connec= tions. - Connecting multiple clients in parallel requires all clients= asking - for a shared session (vncviewer: -Shared switch). This is - the default value. force-shared disables exclus= ive - client access, every connection has to specify -Shared switc= h for - vncviewer. ignore welcomes every connection - unconditionally since 1.0.6. -

    -

    - Rather than using listen/port, QEMU supports a socket<= /code> - attribute for listening on a unix domain socket path - Since 0.8.8. -

    -

    - For VNC WebSocket functionality, websocket attr= ibute - may be used to specify port to listen on (with -1 meaning - auto-allocation and autoport having no effect d= ue to - security reasons) Since 1.0.6. -

    -

    - Although VNC doesn't support OpenGL natively, it can be pair= ed - with graphics type egl-headless (see below) whi= ch - will instruct QEMU to open and use drm nodes for OpenGL rend= ering. -

    -
    -
    spice Since 0.8.6<= /dt> -
    -

    - Starts a SPICE server. The port attribute speci= fies - the TCP port number (with -1 as legacy syntax indicating tha= t it - should be auto-allocated), while tlsPort gives - an alternative secure port number. The autoport - attribute is the new preferred syntax for indicating - auto-allocation of needed port numbers. The passwd - attribute provides a SPICE password in clear text. If the - passwd attribute is set to an empty string, then - SPICE access is disabled. The keymap attribute - specifies the keymap to use. It is possible to set a limit on - the validity of the password by giving a timestamp - passwdValidTo=3D'2010-04-09T15:51:00' assumed t= o be - in UTC. -

    -

    - The connected attribute allows control of conne= cted - client during password changes. SPICE accepts keep to - keep client connected, disconnect to disconnect= client - and fail to fail changing password . NB, this m= ay not - be supported by all hypervisors. - Since 0.9.3 -

    -

    - The defaultMode attribute sets the default chan= nel - security policy, valid values are secure, - insecure and the default any (whic= h is - secure if possible, but falls back to insecure rather than e= rroring - out if no secure path is available). - Since 0.9.12 -

    -

    - When SPICE has both a normal and TLS secured TCP port config= ured, - it can be desirable to restrict what channels can be run on = each - port. This is achieved by adding one or more <chann= el> - elements inside the main <graphics> - element and setting the mode attribute to either - secure or insecure. Setting the mo= de - attribute overrides the default value as set by - the defaultMode attribute. (Note that specifying - any as mode discards the entry as the channel w= ould - inherit the default mode anyways.) Valid channel names inclu= de - main, display, inputs, - cursor, playback, record - (all since 0.8.6); - smartcard (since 0.8.8); - and usbredir (since 0.9.1= 2). -

    - 
    -<graphics type=3D'spice' port=3D'-1' tlsPort=3D'-1' autoport=3D'yes'>
-  <channel name=3D'main' mode=3D'secure'/>
-  <channel name=3D'record' mode=3D'insecure'/>
-  <image compression=3D'auto_glz'/>
-  <streaming mode=3D'filter'/>
-  <clipboard copypaste=3D'no'/>
-  <mouse mode=3D'client'/>
-  <filetransfer enable=3D'no'/>
-  <gl enable=3D'yes' rendernode=3D'/dev/dri/by-path/pci-0000:00:02.0-re=
nder'/>
-</graphics>
    -

    - Spice supports variable compression settings for audio, imag= es and - streaming. These settings are accessible via the compr= ession - attribute in all following elements: image to - set image compression (accepts auto_glz, - auto_lz, quic, glz, - lz, off), jpeg for JP= EG - compression for images over wan (accepts auto, - never, always), zlib = for - configuring wan image compression (accepts auto, - never, always) and playback= - for enabling audio stream compression (accepts on or - off). Since 0.9.1 -

    -

    - Streaming mode is set by the streaming element, - settings its mode attribute to one of - filter, all or off. - Since 0.9.2 -

    -

    - Copy & Paste functionality (via Spice agent) is set by t= he - clipboard element. It is enabled by default, an= d can - be disabled by setting the copypaste property to - no. Since 0.9.3 -

    -

    - Mouse mode is set by the mouse element, setting= its - mode attribute to one of server or - client. If no mode is specified, the qemu defau= lt will - be used (client mode). Since 0.9.11 -

    -

    - File transfer functionality (via Spice agent) is set using t= he - filetransfer element. It is enabled by default,= and - can be disabled by setting the enable property = to - no. Since 1.2.2 -

    -

    - Spice may provide accelerated server-side rendering with Ope= nGL. - You can enable or disable OpenGL support explicitly with - the gl element, by setting the enable - property. (QEMU only, since 1.3.3). - Note that this only works locally, since this requires usage= of - UNIX sockets, i.e. using listen types 'socket' = or - 'none'. For accelerated OpenGL with remote support, consider - pairing this element with type egl-headless - (see below). However, this will deliver weaker performance - compared to native Spice OpenGL support. -

    -

    - By default, QEMU will pick the first available GPU DRM rende= r node. - You may specify a DRM render node path to use instead. (QEMU= only, - since 3.1.0). -

    -
    -
    rdp
    -
    -

    - Starts a RDP server. The port attribute specifi= es the - TCP port number (with -1 as legacy syntax indicating that it= should - be auto-allocated). The autoport attribute is t= he new - preferred syntax for indicating auto-allocation of the TCP p= ort to - use. In the VirtualBox driver, the autoport wil= l make - the hypervisor pick available port from 3389-3689 range when= the VM - is started. The chosen port will be reflected in the p= ort - attribute. The multiUser attribute is a boolean= deciding - whether multiple simultaneous connections to the VM are perm= itted. - The replaceUser attribute is a boolean deciding= whether - the existing connection must be dropped and a new connection= must - be established by the VRDP server, when a new client connect= s in - single connection mode. -

    -
    -
    desktop
    -
    -

    - This value is reserved for VirtualBox domains for the moment= . It - displays a window on the host desktop, similarly to "sdl", b= ut - using the VirtualBox viewer. Just like "sdl", it accepts - the optional attributes display and - fullscreen. -

    -
    -
    egl-headlessSince 4.6.0
    -
    -

    - This display type provides support for an OpenGL accelerated - display accessible both locally and remotely (for comparison, - Spice's native OpenGL support only works locally using UNIX - sockets at the moment, but has better performance). Since th= is - display type doesn't provide any window or graphical console= like - the other types, for practical reasons it should be paired w= ith - either vnc or spice graphics types. - This display type is only supported by QEMU domains - (needs QEMU 2.10 or newer). - 5.0.0 this element accepts a - <gl/> sub-element with an optional attrib= ute - rendernode which can be used to specify an abso= lute - path to a host's DRI device to be used for OpenGL rendering. -

    - 
    -<graphics type=3D'spice' autoport=3D'yes'/>
-<graphics type=3D'egl-headless'>
-  <gl rendernode=3D'/dev/dri/renderD128'/>
-</graphics>
-
    -
    -
    -
    -
    - -

    - Graphics device uses a <listen> to set up where - the device should listen for clients. It has a mandatory attribute - type which specifies the listen type. Only vnc, - spice and rdp supports <listen> - element. Since 0.9.4. - Available types are: -

    -
    -
    address
    -
    -

    - Tells a graphics device to use an address specified in the - address attribute, which will contain either an IP = address - or hostname (which will be resolved to an IP address via a DNS q= uery) - to listen on. -

    -

    - It is possible to omit the address attribute in ord= er to - use an address from config files Since 1.3= .5. -

    -

    - The address attribute is duplicated as listen= - attribute in graphics element for backward compatib= ility. - If both are provided they must be equal. -

    -
    -
    network
    -
    -

    - This is used to specify an existing network in the network= - attribute from libvirt's list of configured networks. The named = network - configuration will be examined to determine an appropriate listen - address and the address will be stored in live XML in addr= ess - attribute. For example, if the network has an IPv4 addre= ss in - its configuration (e.g. if it has a forward type of route<= /code>, - nat, or no forward type (isolated)), the first IPv4 - address listed in the network's configuration will be used. - If the network is describing a host bridge, the first IPv4 addre= ss - associated with that bridge device will be used, and if the netw= ork is - describing one of the 'direct' (macvtap) modes, the first IPv4 a= ddress - of the first forward dev will be used. -

    -
    -
    socket since 2.0.0 (QEMU only= )
    -
    -

    - This listen type tells a graphics server to listen on unix socke= t. - Attribute socket contains a path to unix socket. If= this - attribute is omitted libvirt will generate this path for you. - Supported by graphics type vnc and spice. -

    -

    - For vnc graphics be backward compatible - the socket attribute of first listen e= lement - is duplicated as socket attribute in graphics= - element. If graphics element contains a socke= t - attribute all listen elements are ignored. -

    -
    -
    none since 2.0.0 (QEMU only)<= /span>
    -
    -

    - This listen type doesn't have any other attribute. Libvirt suppo= rts - passing a file descriptor through our APIs virDomainOpenGraphics= () and - virDomainOpenGraphicsFD(). No other listen types are allowed if = this - one is used and the graphics device doesn't listen anywhere. You= need - to use one of the two APIs to pass a FD to QEMU in order to conn= ect to - this graphics device. Supported by graphics type vnc and - spice. -

    -
    -
    - -

    Video devices

    -

    - A video device. -

    - -
    -...
-<devices>
-  <video>
-    <model type=3D'vga' vram=3D'16384' heads=3D'1'>
-      <acceleration accel3d=3D'yes' accel2d=3D'yes'/>
-    </model>
-    <driver name=3D'qemu'/>
-  </video>
-</devices>
-...
    - -
    -
    video
    -
    -

    - The video element is the container for describing - video devices. For backwards compatibility, if no video - is set but there is a graphics in domain xml, then - libvirt will add a default video according to the g= uest - type. -

    -

    - For a guest of type "kvm", the default video is: - type with value "cirrus", vram with va= lue - "16384" and heads with value "1". By default, the f= irst - video device in domain xml is the primary one, but the optional - attribute primary (since 1.0.= 2) - with value 'yes' can be used to mark the primary in cases of mul= tiple - video device. The non-primary must be type of "qxl" or - (since 2.4.0) "virtio". -

    -
    - -
    model
    -
    -

    - The model element has a mandatory type - attribute which takes the value "vga", "cirrus", "vmvga", "xen", - "vbox", "qxl" (since 0.8.6), - "virtio" (since 1.3.0), - "gop" (since 3.2.0), - "bochs" (since 5.6.0), "ramfb" - (since 5.9.0), or "none" - (since 4.6.0, depending on the hyp= ervisor - features available. - The purpose of the type none is to instruct libvirt= not - to add a default video device in the guest (see the paragraph ab= ove). - This legacy behaviour can be inconvenient in cases where GPU med= iated - devices are meant to be the only rendering device within a guest= and - so specifying another video device along with type - none. - Refer to Host device assignment to= see - how to add a mediated device into a guest. -

    -

    - You can provide the amount of video memory in kibibytes (blocks = of - 1024 bytes) using vram. This is supported only for = guest - type of "vz", "qemu", "vbox", "vmx" and "xen". If no - value is provided the default is used. If the size is not a powe= r of - two it will be rounded to closest one. -

    -

    - The number of screen can be set using heads. This is - supported only for guests type of "vz", "kvm", "vbox" and "vmx". -

    -

    - For guest type of "kvm" or "qemu" and model type "qxl" there are - optional attributes. Attribute ram ( - since 1.0.2) specifies the size of the primary bar, while= the - attribute vram specifies the secondary bar size. - If ram or vram are not supplied a defa= ult - value is used. The ram should also be rounded to po= wer of - two as vram. There is also optional attribute - vgamem (since 1.2.11) = to set - the size of VGA framebuffer for fallback mode of QXL device. - Attribute vram64 (since 1.3.3= ) - extends secondary bar and makes it addressable as 64bit memory. -

    -

    Since 5.9.0, the model - element may also have an optional resolution sub-elem= ent. - The resolution element has attributes x = and - y to set the minimum resolution for the video device.= This - sub-element is valid for model types "vga", "qxl", "bochs", and - "virtio". -

    -
    - -
    acceleration
    -
    - Configure if video acceleration should be enabled. -
    -
    accel2d
    -
    Enable 2D acceleration (for vbox driver only, - since 0.7.1)
    - -
    accel3d
    -
    Enable 3D acceleration (for vbox driver - since 0.7.1, qemu driver - since 1.3.0)
    - -
    rendernode
    -
    Absolute path to a host's DRI device to be used for - rendering (for 'vhostuser' driver only, since 5.8.0). If none is specified, - libvirt will pick one available.
    -
    -
    - -
    address
    -
    - The optional address sub-element can be used to - tie the video device to a particular PCI slot. - On S390, address can be used to provide the - CCW address for the video device ( - since 4.2.0). -
    - -
    driver
    -
    - The subelement driver can be used to tune the device: -
    -
    name
    -
    - Specify the backend driver to use, either "qemu" or - "vhostuser" depending on the hypervisor features available - (since 5.8.0). "qemu" is the - default QEMU backend. "vhostuser" will use a separate - vhost-user process backend (for virtio - device). -
    -
    virtio options
    -
    - Virtio-specific options can also= be - set (Since 3.5.0) -
    -
    VGA configuration
    -
    - Control how the video devices exposed to the guest using the - vgaconf attribute which takes the value "io", "on" = or "off". - At present, it's only applicable to the bhyve's "gop" video mode= l type - (Since 3.5.0) -
    -
    -
    -
    - -

    Consoles, serial, parallel & channel= devices

    - -

    - A character device provides a way to interact with the virtual machi= ne. - Paravirtualized consoles, serial ports, parallel ports and channels = are - all classed as character devices and so represented using the same s= yntax. -

    - -
    -...
-<devices>
-  <parallel type=3D'pty'>
-    <source path=3D'/dev/pts/2'/>
-    <target port=3D'0'/>
-  </parallel>
-  <serial type=3D'pty'>
-    <source path=3D'/dev/pts/3'/>
-    <target port=3D'0'/>
-  </serial>
-  <serial type=3D'file'>
-    <source path=3D'/tmp/file' append=3D'on'>
-      <seclabel model=3D'dac' relabel=3D'no'/>
-    </source>
-    <target port=3D'0'/>
-  </serial>
-  <console type=3D'pty'>
-    <source path=3D'/dev/pts/4'/>
-    <target port=3D'0'/>
-  </console>
-  <channel type=3D'unix'>
-    <source mode=3D'bind' path=3D'/tmp/guestfwd'/>
-    <target type=3D'guestfwd' address=3D'10.0.2.1' port=3D'4600'/>
-  </channel>
-</devices>
-...
    - -

    - In each of these directives, the top-level element name (parallel, s= erial, - console, channel) describes how the device is presented to the guest= . The - guest interface is configured by the target element. -

    - -

    - The interface presented to the host is given in the type - attribute of the top-level element. The host interface is - configured by the source element. -

    - -

    - The source element may contain an optional - seclabel to override the way that labelling - is done on the socket path. If this element is not present, - the security label is inherited from - the per-domain setting. -

    - -

    - If the interface type presented to the host is "file", - then the source element may contain an optional attribu= te - append that specifies whether or not the information in - the file should be preserved on domain restart. Allowed values are - "on" and "off" (default). Since 1.3.1. -

    - -

    - Regardless of the type, character devices can - have an optional log file associated with them. This is - expressed via a log sub-element, with a - file attribute. There can also be an append - attribute which takes the same values described above. - Since 1.3.3. -

    - - 
    -...
-<log file=3D"/var/log/libvirt/qemu/guestname-serial0.log" append=3D"off=
"/>
-...
    - -

    - Each character device element has an optional - sub-element <address> which can tie the - device to a - particular controller or PCI - slot. -

    - -

    - For character device with type unix or tcp - the source has an optional element reconnect - which configures reconnect timeout if the connection is lost. - There are two attributes, enabled where possible - values are "yes" and "no" and timeout which is in - seconds. The reconnect attribute is valid only - for connect mode. - Since 3.7.0 (QEMU driver only). -

    - -
    Guest interface
    - -

    - A character device presents itself to the guest as one of the follow= ing - types. -

    - -
    Parallel port
    - -
    -...
-<devices>
-  <parallel type=3D'pty'>
-    <source path=3D'/dev/pts/2'/>
-    <target port=3D'0'/>
-  </parallel>
-</devices>
-...
    - -

    - target can have a port attribute, which - specifies the port number. Ports are numbered starting from 0. There= are - usually 0, 1 or 2 parallel ports. -

    - -
    Serial port
    - -
    -...
-<devices>
-  <!-- Serial port -->
-  <serial type=3D'pty'>
-    <source path=3D'/dev/pts/3'/>
-    <target port=3D'0'/>
-  </serial>
-</devices>
-...
    - -
    -...
-<devices>
-  <!-- USB serial port -->
-  <serial type=3D'pty'>
-    <target type=3D'usb-serial' port=3D'0'>
-      <model name=3D'usb-serial'/>
-    </target>
-    <address type=3D'usb' bus=3D'0' port=3D'1'/>
-  </serial>
-</devices>
-...
    - -

    - The target element can have an optional port - attribute, which specifies the port number (starting from 0), and an - optional type attribute: valid values are, - since 1.0.2, isa-serial (u= sable - with x86 guests), usb-serial (usable whenever USB suppo= rt - is available) and pci-serial (usable whenever PCI suppo= rt - is available); since 3.10.0, - spapr-vio-serial (usable with ppc64/pseries guests), - system-serial (usable with aarch64/virt and, - since 4.7.0, riscv/virt guests) and - sclp-serial (usable with s390 and s390x guests) are - available as well. -

    - -

    - Since 3.10.0, the target - element can have an optional model subelement; - valid values for its name attribute are: - isa-serial (usable with the isa-serial tar= get - type); usb-serial (usable with the usb-serial - target type); pci-serial - (usable with the pci-serial target type); - spapr-vty (usable with the spapr-vio-serial - target type); pl011 and, - since 4.7.0, 16550a (usable - with the system-serial target type); - sclpconsole and sclplmconsole (usable with - the sclp-serial target type). Providing a target model = is - usually unnecessary: libvirt will automatically pick one that's suit= able - for the chosen target type, and overriding that value is generally n= ot - recommended. -

    - -

    - If any of the attributes is not specified by the user, libvirt will - choose a value suitable for most users. -

    - -

    - Most target types support configuring the guest-visible device - address as documented above; more - specifically, acceptable address types are isa (for - isa-serial), usb (for usb-serial), - pci (for pci-serial) and spapr-vio - (for spapr-vio-serial). The system-serial - and sclp-serial target types don't support specifying an - address. -

    - -

    - For the relationship between serial ports and consoles, - see below. -

    - -
    Console
    - -
    -...
-<devices>
-  <!-- Serial console -->
-  <console type=3D'pty'>
-    <source path=3D'/dev/pts/2'/>
-   <target type=3D'serial' port=3D'0'/>
-  </console>
-</devices>
-...
    - -
    -...
-<devices>
-  <!-- KVM virtio console -->
-  <console type=3D'pty'>
-    <source path=3D'/dev/pts/5'/>
-    <target type=3D'virtio' port=3D'0'/>
-  </console>
-</devices>
-...
    - -

    - The console element is used to represent interactive - serial consoles. Depending on the type of guest in use and the speci= fics - of the configuration, the console element might represe= nt - the same device as an existing serial element or a sepa= rate - device. -

    - -

    - A target subelement is supported and works the same - way as with the serial element - (see above for details). - Valid values for the type attribute are: - serial (described below); - virtio (usable whenever VirtIO support is available); - xen, lxc and openvz - (available when the corresponding hypervisor is in use). - sclp and sclplm (usable for s390 and - s390x QEMU guests) are supported for compatibility reasons but should - not be used for new guests: use the sclpconsole and - sclplmconsole target models, respectively, with the - serial element instead. -

    - -

    - Of the target types listed above, serial is special in - that it doesn't represents a separate device, but rather the same - device as the first serial element. Due to this, there = can - only be a single console element with target type - serial per guest. -

    - -

    - Virtio consoles are usually accessible as /dev/hvc[0-7] - from inside the guest; for more information, see - http= ://fedoraproject.org/wiki/Features/VirtioSerial. - Since 0.8.3 -

    - -

    - For the relationship between serial ports and consoles, - see below. -

    - -
    Relationship between serial = ports and consoles
    - -

    - Due to hystorical reasons, the serial and - console elements have partially overlapping scopes. -

    - -

    - In general, both elements are used to configure one or more serial - consoles to be used for interacting with the guest. The main differe= nce - between the two is that serial is used for emulated, - usually native, serial consoles, whereas console is used - for paravirtualized ones. -

    - -

    - Both emulated and paravirtualized serial consoles have advantages and - disadvantages: -

    - -
      -
    • - emulated serial consoles are usually initialized much earlier than - paravirtualized ones, so they can be used to control the bootloader - and display both firmware and early boot messages; -
      • -
    • - on several platforms, there can only be a single emulated serial - console per guest but paravirtualized consoles don't suffer from t= he - same limitation. -
      • -
    - -

    - A configuration such as: -

    - -
    -...
-<devices>
-  <console type=3D'pty'>
-    <target type=3D'serial'/>
-  </console>
-  <console type=3D'pty'>
-    <target type=3D'virtio'/>
-  </console>
-</devices>
-...
    - -

    - will work on any platform and will result in one emulated serial con= sole - for early boot logging / interactive / recovery use, and one - paravirtualized serial console to be used eg. as a side channel. Most - people will be fine with having just the first console - element in their configuration, but if a specific configuration is - desired then both elements should be specified. -

    - -

    - Note that, due to the compatibility concerns mentioned earlier, all = the - following configurations: -

    - -
    -...
-<devices>
-  <serial type=3D'pty'/>
-</devices>
-...
    - -
    -...
-<devices>
-  <console type=3D'pty'/>
-</devices>
-...
    - -
    -...
-<devices>
-  <serial type=3D'pty'/>
-  <console type=3D'pty'/>
-</devices>
-...
    - -

    - will be treated the same and will result in a single emulated serial - console being available to the guest. -

    - -
    Channel
    - -

    - This represents a private communication channel between the host and= the - guest. -

    - -
    -...
-<devices>
-  <channel type=3D'unix'>
-    <source mode=3D'bind' path=3D'/tmp/guestfwd'/>
-    <target type=3D'guestfwd' address=3D'10.0.2.1' port=3D'4600'/>
-  </channel>
-
-  <!-- KVM virtio channel -->
-  <channel type=3D'pty'>
-    <target type=3D'virtio' name=3D'arbitrary.virtio.serial.port.name'/=
>
-  </channel>
-  <channel type=3D'unix'>
-    <source mode=3D'bind' path=3D'/var/lib/libvirt/qemu/f16x86_64.agent=
'/>
-    <target type=3D'virtio' name=3D'org.qemu.guest_agent.0' state=3D'co=
nnected'/>
-  </channel>
-  <channel type=3D'spicevmc'>
-    <target type=3D'virtio' name=3D'com.redhat.spice.0'/>
-  </channel>
-</devices>
-...
    - -

    - This can be implemented in a variety of ways. The specific type of - channel is given in the type attribute of the - target element. Different channel types have different - target attributes. -

    - -
    -
    guestfwd
    -
    TCP traffic sent by the guest to a given IP address and port is - forwarded to the channel device on the host. The target - element must have address and port attri= butes. - Since 0.7.3
    - -
    virtio
    -
    Paravirtualized virtio channel. Channel is exposed in the guest = under - /dev/vport*, and if the optional element name is spec= ified, - /dev/virtio-ports/$name (for more info, please see - ht= tp://fedoraproject.org/wiki/Features/VirtioSerial). The - optional element address can tie the channel to a - particular type=3D'virtio-serial' - controller, documented above. - With qemu, if name is "org.qemu.guest_agent.0", - then libvirt can interact with a guest agent installed in the - guest, for actions such as guest shutdown or file system quiescing. - Since 0.7.7, guest agent interaction - since 0.9.10 Moreover, since 1.0.6 - it is possible to have source path auto generated for virtio unix = channels. - This is very useful in case of a qemu guest agent, where users don= 't - usually care about the source path since it's libvirt who talks to - the guest agent. In case users want to utilize this feature, they = should - leave <source> element out. Since - 1.2.11 the active XML for a virtio channel may contain an o= ptional - state attribute that reflects whether a process in the - guest is active on the channel. This is an output-only attribute. - Possible values for the state attribute are - connected and disconnected. -
    -
    xen
    -
    Paravirtualized Xen channel. Channel is exposed in the guest as= a - Xen console but identified with a name. Setup and consumption of a= Xen - channel depends on software and configuration in the guest - (for more info, please see http://xenbits.xen.org/docs/unstable/misc/channe= l.txt). - Channel source path semantics are the same as the virtio target ty= pe. - The state attribute is not supported since Xen channe= ls - lack the necessary probing mechanism. - Since 2.3.0 -
    -
    spicevmc
    -
    Paravirtualized SPICE channel. The domain must also have a - SPICE server as a graphics - device, at which point the host piggy-backs messages - across the main channel. The target - element must be present, with - attribute type=3D'virtio'; an optional - attribute name controls how the guest will have - access to the channel, and defaults - to name=3D'com.redhat.spice.0'. The - optional address element can tie the channel to a - particular type=3D'virtio-serial' controller. - Since 0.8.8
    -
    - -
    Host interface
    - -

    - A character device presents itself to the host as one of the followi= ng - types. -

    - -
    Domain logfile
    - -

    - This disables all input on the character device, and sends output - into the virtual machine's logfile -

    - -
    -...
-<devices>
-  <console type=3D'stdio'>
-    <target port=3D'1'/>
-  </console>
-</devices>
-...
    - - -
    Device logfile
    - -

    - A file is opened and all data sent to the character - device is written to the file. -

    - -
    -...
-<devices>
-  <serial type=3D"file">
-    <source path=3D"/var/log/vm/vm-serial.log"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    Virtual console
    - -

    - Connects the character device to the graphical framebuffer in - a virtual console. This is typically accessed via a special - hotkey sequence such as "ctrl+alt+3" -

    - -
    -...
-<devices>
-  <serial type=3D'vc'>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    Null device
    - -

    - Connects the character device to the void. No data is ever - provided to the input. All data written is discarded. -

    - -
    -...
-<devices>
-  <serial type=3D'null'>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    Pseudo TTY
    - -

    - A Pseudo TTY is allocated using /dev/ptmx. A suitable client - such as 'virsh console' can connect to interact with the - serial port locally. -

    - -
    -...
-<devices>
-  <serial type=3D"pty">
-    <source path=3D"/dev/pts/3"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -

    - NB special case if <console type=3D'pty'>, then the TTY - path is also duplicated as an attribute tty=3D'/dev/pts/3' - on the top level <console> tag. This provides compat - with existing syntax for <console> tags. -

    - -
    Host device proxy
    - -

    - The character device is passed through to the underlying - physical character device. The device types must match, - eg the emulated serial port should only be connected to - a host serial port - don't connect a serial port to a parallel - port. -

    - -
    -...
-<devices>
-  <serial type=3D"dev">
-    <source path=3D"/dev/ttyS0"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    Named pipe
    - -

    - The character device writes output to a named pipe. See pipe(7) for - more info. -

    - -
    -...
-<devices>
-  <serial type=3D"pipe">
-    <source path=3D"/tmp/mypipe"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    TCP client/server
    - -

    - The character device acts as a TCP client connecting to a - remote server. -

    - -
    -...
-<devices>
-  <serial type=3D"tcp">
-    <source mode=3D"connect" host=3D"0.0.0.0" service=3D"2445"/>
-    <protocol type=3D"raw"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
- ...
    - -

    - Or as a TCP server waiting for a client connection. -

    - -
    -...
-<devices>
-  <serial type=3D"tcp">
-    <source mode=3D"bind" host=3D"127.0.0.1" service=3D"2445"/>
-    <protocol type=3D"raw"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -

    - Alternatively you can use telnet instead - of raw TCP in order to utilize the telnet protocol - for the connection. -

    -

    - Since 0.8.5, some hypervisors support - use of either telnets (secure telnet) or tls - (via secure sockets layer) as the transport protocol for connections. -

    - -
    -...
-<devices>
-  <serial type=3D"tcp">
-    <source mode=3D"connect" host=3D"0.0.0.0" service=3D"2445"/>
-    <protocol type=3D"telnet"/>
-    <target port=3D"1"/>
-  </serial>
-  ...
-  <serial type=3D"tcp">
-    <source mode=3D"bind" host=3D"127.0.0.1" service=3D"2445"/>
-    <protocol type=3D"telnet"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -

    - Since 2.4.0, the optional attribute - tls can be used to control whether a chardev - TCP communication channel would utilize a hypervisor configured - TLS X.509 certificate environment in order to encrypt the data - channel. For the QEMU hypervisor, usage of a TLS environment can - be controlled on the host by the chardev_tls and - chardev_tls_x509_cert_dir or - default_tls_x509_cert_dir settings in the file - /etc/libvirt/qemu.conf. If chardev_tls is enabled, - then unless the tls attribute is set to "no", libvirt - will use the host configured TLS environment. - If chardev_tls is disabled, but the tls - attribute is set to "yes", then libvirt will attempt to use the - host TLS environment if either the chardev_tls_x509_cert_dir - or default_tls_x509_cert_dir TLS directory structure ex= ists. -

    -
    -...
-<devices>
-  <serial type=3D"tcp">
-    <source mode=3D'connect' host=3D"127.0.0.1" service=3D"5555" tls=3D=
"yes"/>
-    <protocol type=3D"raw"/>
-    <target port=3D"0"/>
-  </serial>
-</devices>
-...
    - -
    UDP network console
    - -

    - The character device acts as a UDP netconsole service, - sending and receiving packets. This is a lossy service. -

    - -
    -...
-<devices>
-  <serial type=3D"udp">
-    <source mode=3D"bind" host=3D"0.0.0.0" service=3D"2445"/>
-    <source mode=3D"connect" host=3D"0.0.0.0" service=3D"2445"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    UNIX domain socket client/server - -

    - The character device acts as a UNIX domain socket server, - accepting connections from local clients. -

    - -
    -...
-<devices>
-  <serial type=3D"unix">
-    <source mode=3D"bind" path=3D"/tmp/foo"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    Spice channel
    - -

    - The character device is accessible through spice connection - under a channel name specified in the channel - attribute. Since 1.2.2 -

    -

    - Note: depending on the hypervisor, spiceports might (or might not) - be enabled on domains with or without = spice - graphics. -

    - -
    -...
-<devices>
-  <serial type=3D"spiceport">
-    <source channel=3D"org.qemu.console.serial.0"/>
-    <target port=3D"1"/>
-  </serial>
-</devices>
-...
    - -
    Nmdm device
    - -

    - The nmdm device driver, available on FreeBSD, provides two - tty devices connected together by a virtual null modem cable. - Since 1.2.4 -

    - -
    -...
-<devices>
-  <serial type=3D"nmdm">
-    <source master=3D"/dev/nmdm0A" slave=3D"/dev/nmdm0B"/>
-  </serial>
-</devices>
-...
    - -

    - The source element has these attributes: -

    - -
    -
    master
    -
    Master device of the pair, that is passed to the hypervisor. - Device is specified by a fully qualified path.
    - -
    slave
    -
    Slave device of the pair, that is passed to the clients for conn= ection - to the guest console. Device is specified by a fully qualified path.=
    -
    - -

    Sound devices

    - -

    - A virtual sound card can be attached to the host via the - sound element. Since 0.4.3 -

    - -
    -...
-<devices>
-  <sound model=3D'es1370'/>
-</devices>
-...
    - -
    -
    sound
    -
    - The sound element has one mandatory attribute, - model, which specifies what real sound device is emul= ated. - Valid values are specific to the underlying hypervisor, though typ= ical - choices are 'es1370', 'sb16', 'ac97', 'ich6' and 'usb'. - ( - 'ac97' only since 0.6.0, 'ich6' only since 0.8.8, - 'usb' only since 1.2.7) -
    -
    - -

    - Since 0.9.13, a sound element - with ich6 model can have optional - sub-elements <codec> to attach various audio - codecs to the audio device. If not specified, a default codec - will be attached to allow playback and recording. -

    -

    - Valid values are: -

    -

    -

      -
    • 'duplex' - advertise a line-in and a line-out
      • -
    • 'micro' - advertise a speaker and a microphone
      • -
    • 'output' - advertise a line-out - Since 4.4.0
      • -
    -

    - -
    -...
-<devices>
-  <sound model=3D'ich6'>
-    <codec type=3D'micro'/>
-  </sound>
-</devices>
-...
    - -

    - Each sound element has an optional - sub-element <address> which can tie the - device to a particular PCI - slot, documented above. -

    - -

    Watchdog device

    - -

    - A virtual hardware watchdog device can be added to the guest via - the watchdog element. - Since 0.7.3, QEMU and KVM only -

    - -

    - The watchdog device requires an additional driver and management - daemon in the guest. Just enabling the watchdog in the libvirt - configuration does not do anything useful on its own. -

    - -

    - Currently libvirt does not support notification when the - watchdog fires. This feature is planned for a future version of - libvirt. -

    - -
    -...
-<devices>
-  <watchdog model=3D'i6300esb'/>
-</devices>
-...
    - -
    -  ...
-  <devices>
-    <watchdog model=3D'i6300esb' action=3D'poweroff'/>
-  </devices>
-</domain>
    - -
    -
    model
    -
    -

    - The required model attribute specifies what real - watchdog device is emulated. Valid values are specific to the - underlying hypervisor. -

    -

    - QEMU and KVM support: -

    -
      -
    • 'i6300esb' - the recommended device, - emulating a PCI Intel 6300ESB
      • -
    • 'ib700' - emulating an ISA iBase IB700
      • -
    • 'diag288' - emulating an S390 DIAG288 device - Since 1.2.17
      • -
    -
    -
    action
    -
    -

    - The optional action attribute describes what - action to take when the watchdog expires. Valid values are - specific to the underlying hypervisor. -

    -

    - QEMU and KVM support: -

    -
      -
    • 'reset' - default, forcefully reset the guest
      • -
    • 'shutdown' - gracefully shutdown the guest - (not recommended)
      • -
    • 'poweroff' - forcefully power off the guest
      • -
    • 'pause' - pause the guest
      • -
    • 'none' - do nothing
      • -
    • 'dump' - automatically dump the guest - Since 0.8.7
      • -
    • 'inject-nmi' - inject a non-maskable interrupt - into the guest - Since 1.2.17
      • -
    -

    - Note 1: the 'shutdown' action requires that the guest - is responsive to ACPI signals. In the sort of situations - where the watchdog has expired, guests are usually unable - to respond to ACPI signals. Therefore using 'shutdown' - is not recommended. -

    -

    - Note 2: the directory to save dump files can be configured - by auto_dump_path in file /etc/libvirt/qemu.conf. -

    -
    -
    - -

    Memory balloon device

    - -

    - A virtual memory balloon device is added to all Xen and KVM/QEMU - guests. It will be seen as memballoon element. - It will be automatically added when appropriate, so there is no - need to explicitly add this element in the guest XML unless a - specific PCI slot needs to be assigned. - Since 0.8.3, Xen, QEMU and KVM only - Additionally, since 0.8.4, if the - memballoon device needs to be explicitly disabled, - model=3D'none' may be used. -

    - -

    - Example: automatically added device with KVM -

    -
    -...
-<devices>
-  <memballoon model=3D'virtio'/>
-</devices>
-...
    - -

    - Example: manually added device with static PCI slot 2 requested -

    -
    -  ...
-  <devices>
-    <memballoon model=3D'virtio'>
-      <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x02=
' function=3D'0x0'/>
-      <stats period=3D'10'/>
-      <driver iommu=3D'on' ats=3D'on'/>
-    </memballoon>
-  </devices>
-</domain>
    - -
    -
    model
    -
    -

    - The required model attribute specifies what type - of balloon device is provided. Valid values are specific to - the virtualization platform -

    -
      -
    • 'virtio' - default with QEMU/KVM
      • -
    • 'virtio-transitional' Since 5.2.0
      • -
    • 'virtio-non-transitional' Since 5.2.0<= /span>
      • -
    • 'xen' - default with Xen
      • -
    - See Virtio transitional de= vices - for more details. -
    -
    autodeflate
    -
    -

    - The optional autodeflate attribute allows to - enable/disable (values "on"/"off", respectively) the ability of = the - QEMU virtio memory balloon to release some memory at the last mo= ment - before a guest's process get killed by Out of Memory killer. - Since 1.3.1, QEMU and KVM only -

    -
    -
    period
    -
    -

    - The optional period allows the QEMU virtio memory b= alloon - driver to provide statistics through the virsh dommemstat - [domain] command. By default, collection is not enabled. = In - order to enable, use the virsh dommemstat [domain] --period - [number] command or virsh edit command to ad= d the - option to the XML definition. The virsh dommemstat= will - accept the options --live, --current, - or --config. If an option is not provided, the cha= nge - for a running domain will only be made to the active guest. If = the - QEMU driver is not at the right revision, the attempt to set the - period will fail. Large values (e.g. many years) might be ignor= ed. - Since 1.1.1, requires QEMU 1.5 -

    -
    -
    driver
    -
    - For model virtio memballoon, - Virtio-specific options can also be - set. (Since 3.5.0) -
    -
    -

    Random number generator device

    - -

    - The virtual random number generator device allows the host to pass - through entropy to guest operating systems. - Since 1.0.3 -

    - -

    - Example: usage of the RNG device: -

    -
    -...
-<devices>
-  <rng model=3D'virtio'>
-    <rate period=3D"2000" bytes=3D"1234"/>
-    <backend model=3D'random'>/dev/random</backend>
-    <!-- OR -->
-    <backend model=3D'egd' type=3D'udp'>
-      <source mode=3D'bind' service=3D'1234'/>
-      <source mode=3D'connect' host=3D'1.2.3.4' service=3D'1234'/>
-    </backend>
-    <!-- OR -->
-    <backend model=3D'builtin'/>
-  </rng>
-</devices>
-...
-
    -
    -
    model
    -
    -

    - The required model attribute specifies what type - of RNG device is provided. Valid values are specific to - the virtualization platform: -

    -
      -
    • 'virtio' - supported by qemu and virtio-rng kernel module -
    • 'virtio-transitional' Since 5.2.0
      • -
    • 'virtio-non-transitional' Since 5.2.0<= /span>
      • -
    - See Virtio transitional de= vices - for more details. -
    -
    rate
    -
    -

    - The optional rate element allows limiting the rate = at - which entropy can be consumed from the source. The mandatory - attribute bytes specifies how many bytes are permit= ted - to be consumed per period. An optional period attr= ibute - specifies the duration of a period in milliseconds; if omitted, = the - period is taken as 1000 milliseconds (1 second). - Since 1.0.4 -

    -
    -
    backend
    -
    -

    - The backend element specifies the source of entropy - to be used for the domain. The source model is configured using = the - model attribute. Supported source models are: -

    -
    -
    random
    -
    -

    - This backend type expects a non-blocking character device - as input. The file name is specified as contents of the - backend element. Since - 1.3.4 any path is accepted. Before that - /dev/random and /dev/hwrng were - the only accepted paths. When no file name is specified, - the hypervisor default is used. For QEMU, the default is - /dev/random. However, the recommended source - of entropy is /dev/urandom (as it doesn't - have the limitations of /dev/random). -

    -
    -
    egd
    -
    -

    - This backend connects to a source using the EGD protocol. - The source is specified as a character device. Refer to - character device host= interface - for more information. -

    -
    -
    builtin
    -
    -

    - This backend uses qemu builtin random generator, which uses - getrandom() syscall as the source of entropy. - (Since 6.1.0 and QEMU 4.2) -

    -
    -
    -
    -
    driver
    -
    - The subelement driver can be used to tune the device: -
    -
    virtio options
    -
    - Virtio-specific options can also= be - set. (Since 3.5.0) -
    -
    -
    - -
    - -

    TPM device

    - -

    - The TPM device enables a QEMU guest to have access to TPM - functionality. The TPM device may either be a TPM 1.2 or - a TPM 2.0. -

    -

    - The TPM passthrough device type provides access to the host's TPM - for one QEMU guest. No other software may be using the TPM device, - typically /dev/tpm0, at the time the QEMU guest is started. - 'passthrough' since 1.0.5 -

    - -

    - Example: usage of the TPM passthrough device -

    -
    -...
-<devices>
-  <tpm model=3D'tpm-tis'>
-    <backend type=3D'passthrough'>
-      <device path=3D'/dev/tpm0'/>
-    </backend>
-  </tpm>
-</devices>
-...
-
    - -

    - The emulator device type gives access to a TPM emulator providing - TPM functionality for each VM. QEMU talks to it over a Unix socket. = With - the emulator device type each guest gets its own private TPM. - 'emulator' since 4.5.0 - The state of the TPM emulator can be encrypted by providing an - encryption element. - 'encryption' since 5.6.0 -

    -

    - Example: usage of the TPM Emulator -

    -
    -  ...
-  <devices>
-    <tpm model=3D'tpm-tis'>
-      <backend type=3D'emulator' version=3D'2.0'>
-        <encryption secret=3D'6dd3e4a5-1d76-44ce-961f-f119f5aad935'/>
-      </backend>
-    </tpm>
-  </devices>
-  ...
-
    -
    -
    model
    -
    -

    - The model attribute specifies what device - model QEMU provides to the guest. If no model name is provided, - tpm-tis will automatically be chosen for non-PPC64 - architectures. - Since 4.4.0, another available choi= ce - is the tpm-crb, which should only be used when the - backend device is a TPM 2.0. Since 6.1.0, - pSeries guests on PPC64 are supported and the default is - tpm-spapr. - - Since 6.5.0, a new model called - spapr-tpm-proxy was added for pSeries guests. This = model - only works with the passthrough backend. It creates= a - TPM Proxy device that communicates with an existing TPM Resource= Manager - in the host, for example /dev/tpmrm0, enabling the = guest to - run in secure virtual machine mode with the help of an Ultraviso= r. Adding - a TPM Proxy to a pSeries guest brings no security benefits unles= s the guest - is running on a PPC64 host that has an Ultravisor and a TPM Reso= urce Manager. - Only one TPM Proxy device is allowed per guest, but a TPM Proxy = device can - be added together with - other TPM devices. -

    -
    -
    backend
    -
    -

    - The backend element specifies the type of - TPM device. The following types are supported: -

    -
    -
    passthrough
    -
    -

    - Use the host's TPM or TPM Resource Manager device. -

    -

    - This backend type requires exclusive access to a TPM device = on - the host. An example for such a device is /dev/tpm0. The ful= ly - qualified file name is specified by path attribute of the - source element. If no file name is specified th= en - /dev/tpm0 is automatically used. - - Since 6.5.0, when choosing the - spapr-tpm-proxy model, the file name specified = is - expected to be a TPM Resource Manager device, e.g. - /dev/tpmrm0. -

    -
    -
    -
    -
    emulator
    -
    -

    - For this backend type the 'swtpm' TPM Emulator must be insta= lled on the - host. Libvirt will automatically start an independent TPM em= ulator - for each QEMU guest requesting access to it. -

    -
    -
    -
    -
    version
    -
    -

    - The version attribute indicates the version - of the TPM. By default a TPM 1.2 is created. This attribute - only works with the emulator backend. The following - versions are supported: -

    -
      -
    • '1.2' : creates a TPM 1.2
      • -
    • '2.0' : creates a TPM 2.0
      • -
    -
    -
    encryption
    -
    -

    - The encryption element allows the state of a TPM em= ulator - to be encrypted. The secret must reference a secret= object - that holds the passphrase from which the encryption key will be = derived. -

    -
    -
    - -

    NVRAM device

    -

    - nvram device is always added to pSeries guest on PPC64, and its addr= ess - is allowed to be changed. Element nvram (only valid for - pSeries guest, since 1.0.5) is provided= to - enable the address setting. -

    -

    - Example: usage of NVRAM configuration -

    -
    -...
-<devices>
-  <nvram>
-    <address type=3D'spapr-vio' reg=3D'0x00003000'/>
-  </nvram>
-</devices>
-...
-
    -
    -
    spapr-vio
    -
    -

    - VIO device address type, only valid for PPC64. -

    -
    -
    reg
    -
    -

    - Device address -

    -
    -
    - -

    panic device

    -

    - panic device enables libvirt to receive panic notification from a QE= MU - guest. - Since 1.2.1, QEMU and KVM only -

    -

    - This feature is always enabled for: -

    -
      -
    • pSeries guests, since it's implemented by the guest firmware
      • -
    • S390 guests, since it's an integral part of the S390 architectur= e
      • -
    -

    - For the guest types listed above, libvirt automatically adds a - panic element to the domain XML. -

    -

    - Example: usage of panic configuration -

    -
    -...
-<devices>
-  <panic model=3D'hyperv'/>
-  <panic model=3D'isa'>
-    <address type=3D'isa' iobase=3D'0x505'/>
-  </panic>
-</devices>
-...
-
    -
    -
    model
    -
    -

    - The optional model attribute specifies what type - of panic device is provided. The panic model used when this attr= ibute - is missing depends on the hypervisor and guest arch. -

    -
      -
    • 'isa' - for ISA pvpanic device
      • -
    • 'pseries' - default and valid only for pSeries guests.
      • -
    • 'hyperv' - for Hyper-V crash CPU feature. - Since 1.3.0, QEMU and KVM only -
    • 's390' - default for S390 guests. - Since 1.3.5
      • -
    -
    -
    address
    -
    -

    - address of panic. The default ioport is 0x505. Most users - don't need to specify an address, and doing so is forbidden - altogether for s390, pseries and hyperv models. -

    -
    -
    - -

    Shared memory device

    - -

    - A shared memory device allows to share a memory region between - different virtual machines and the host. - Since 1.2.10, QEMU and KVM only -

    - -
    -...
-<devices>
-  <shmem name=3D'my_shmem0'>
-    <model type=3D'ivshmem-plain'/>
-    <size unit=3D'M'>4</size>
-  </shmem>
-  <shmem name=3D'shmem_server'>
-    <model type=3D'ivshmem-doorbell'/>
-    <size unit=3D'M'>2</size>
-    <server path=3D'/tmp/socket-shmem'/>
-    <msi vectors=3D'32' ioeventfd=3D'on'/>
-  </shmem>
-</devices>
-...
-
    - -
    -
    shmem
    -
    - The shmem element has one mandatory attribute, - name to identify the shared memory. This attribute cann= ot - be directory specific to . or .. as well as - it cannot involve path separator /. -
    -
    model
    -
    - Attribute type of the optional element model - specifies the model of the underlying device providing the - shmem device. The models currently supported are - ivshmem (supports both server and server-less shmem, bu= t is - deprecated by newer QEMU in favour of the -plain and -doorbell varia= nts), - ivshmem-plain (only for server-less shmem) and - ivshmem-doorbell (only for shmem with the server). -
    -
    size
    -
    - The optional size element specifies the size of the sha= red - memory. This must be power of 2 and greater than or equal to 1 MiB. -
    -
    server
    -
    - The optional server element can be used to configure a = server - socket the device is supposed to connect to. The optional - path attribute specifies the absolute path to the unix = socket - and defaults to /var/lib/libvirt/shmem/$shmem-$name-sock. -
    -
    msi
    -
    - The optional msi element enables/disables (values "on"/= "off", - respectively) MSI interrupts. This option can currently be used only - together with the server element. The vectors - attribute can be used to specify the number of interrupt - vectors. The ioeventd attribute enables/disables (values - "on"/"off", respectively) ioeventfd. -
    -
    - -

    Memory devices

    - -

    - In addition to the initial memory assigned to the guest, memory de= vices - allow additional memory to be assigned to the guest in the form of - memory modules. - - A memory device can be hot-plugged or hot-unplugged depending on t= he - guests' memory resource needs. - - Some hypervisors may require NUMA configured for the guest. -

    - -

    - Example: usage of the memory devices -

    -
    -...
-<devices>
-  <memory model=3D'dimm' access=3D'private' discard=3D'yes'>
-    <target>
-      <size unit=3D'KiB'>524287</size>
-      <node>0</node>
-    </target>
-  </memory>
-  <memory model=3D'dimm'>
-    <source>
-      <pagesize unit=3D'KiB'>4096</pagesize>
-      <nodemask>1-3</nodemask>
-    </source>
-    <target>
-      <size unit=3D'KiB'>524287</size>
-      <node>1</node>
-    </target>
-  </memory>
-  <memory model=3D'nvdimm'>
-    <uuid>
-    <source>
-      <path>/tmp/nvdimm</path>
-    </source>
-    <target>
-      <size unit=3D'KiB'>524288</size>
-      <node>1</node>
-      <label>
-        <size unit=3D'KiB'>128</size>
-      </label>
-      <readonly/>
-    </target>
-  </memory>
-  <memory model=3D'nvdimm' access=3D'shared'>
-    <uuid>
-    <source>
-      <path>/dev/dax0.0</path>
-      <alignsize unit=3D'KiB'>2048</alignsize>
-      <pmem/>
-    </source>
-    <target>
-      <size unit=3D'KiB'>524288</size>
-      <node>1</node>
-      <label>
-        <size unit=3D'KiB'>128</size>
-      </label>
-    </target>
-  </memory>
-</devices>
-...
-
    -
    -
    model
    -
    -

    - Provide dimm to add a virtual DIMM module to the gu= est. - Since 1.2.14 - Provide nvdimm model adds a Non-Volatile DIMM - module. Since 3.2.0 -

    -
    - -
    access
    -
    -

    - An optional attribute access - (since 3.2.0) that provides - capability to fine tune mapping of the memory on per - module basis. Values are the same as - Memory Backing: - shared and private. - For nvdimm model, if using real NVDIMM DAX device as - backend, shared is required. -

    -
    - -
    discard
    -
    -

    - An optional attribute discard - (since 4.4.0) that provides - capability to fine tune discard of data on per module - basis. Accepted values are yes and - no. The feature is described here: - Memory Backing. - This attribute is allowed only for - model=3D'dimm'. -

    -
    - -
    uuid
    -
    -

    - For pSeries guests, an uuid can be set to identify the - nvdimm module. If absent, libvirt will generate an uuid. - automatically. This attribute is allowed only for - model=3D'nvdimm' for pSeries guests. - Since 6.2.0 -

    -
    - -
    source
    -
    -

    - For model dimm this element is optional and allows = to - fine tune the source of the memory used for the given memory dev= ice. - If the element is not provided defaults configured via - numatune are used. If dimm is provided, - then the following optional elements can be provided as well: -

    - -
    -
    pagesize
    -
    -

    - This element can be used to override the default - host page size used for backing the memory device. - The configured value must correspond to a page size - supported by the host. -

    -
    - -
    nodemask
    -
    -

    - This element can be used to override the default - set of NUMA nodes where the memory would be - allocated. -

    -
    -
    - -

    - For model nvdimm this element is mandatory. The - mandatory child element path represents a path in - the host that backs the nvdimm module in the guest. The following - optional elements may be used: -

    - -
    -
    alignsize
    -
    -

    - The alignsize element defines the page size - alignment used to mmap the address range for the backend - path. If not supplied the host page size is use= d. - For example, to mmap a real NVDIMM device a 2M-aligned page = may - be required, and host page size is 4KB, then we need to set = this - element to 2MB. - Since 5.0.0 -

    -
    - -
    pmem
    -
    -

    - If persistent memory is supported and enabled by the hypervi= sor - in order to guarantee the persistence of writes to the vNVDI= MM - backend, then use the pmem element in order to - utilize the feature. - Since 5.0.0 -

    -
    -
    -
    - -
    target
    -
    -

    - The mandatory target element configures the placeme= nt and - sizing of the added memory from the perspective of the guest. -

    -

    - The mandatory size subelement configures the size o= f the - added memory as a scaled integer. -

    -

    - The node subelement configures the guest NUMA node = to - attach the memory to. The element shall be used only if the gues= t has - NUMA nodes configured. -

    -

    - The following optional elements may be used: -

    - -
    -
    label
    -
    -

    - For NVDIMM type devices one can use label and i= ts - subelement size to configure the size of - namespaces label storage within the NVDIMM module. The - size element has usual meaning described - here. - label is mandatory for pSeries guests and optio= nal - for all other architectures. - For QEMU domains the following restrictions apply: -

    -
      -
    1. the minimum label size is 128KiB,
      2. -
    2. the remaining size (total-size - label-size), also calle= d guest - area, will be aligned to 4KiB as default. For pSeries gues= ts, the - guest area will be aligned down to 256MiB, and the minimum= size - of the guest area must be at least 256MiB.
      3. -
    -
    - -
    readonly
    -
    -

    - The readonly element is used to mark the vNVDIMM - as read-only. Only the real NVDIMM device backend can guaran= tee - the guest write persistence, so other backend types should u= se - the readonly element. - Since 5.0.0 -

    -
    -
    -
    -
    - -

    IOMMU devices

    - -

    - The iommu element can be used to add an IOMMU device. - Since 2.1.0 -

    - -

    - Example: -

    -
    -...
-<devices>
-  <iommu model=3D'intel'>
-    <driver intremap=3D'on'/>
-  </iommu>
-</devices>
-...
-
    -
    -
    model
    -
    -

    - Supported values are intel (for Q35 guests) and, - since 5.5.0, smmuv3 (f= or - ARM virt guests). -

    -
    -
    driver
    -
    -

    - The driver subelement can be used to configure - additional options, some of which might only be available for - certain IOMMU models: -

    -
    -
    intremap
    -
    -

    - The intremap attribute with possible values - on and off can be used to - turn on interrupt remapping, a part of the VT-d functionalit= y. - Currently this requires split I/O APIC - (<ioapic driver=3D'qemu'/>). - Since 3.4.0 (QEMU/KVM only) -

    -
    -
    caching_mode
    -
    -

    - The caching_mode attribute with possible values - on and off can be used to - turn on the VT-d caching mode (useful for assigned devices). - Since 3.4.0 (QEMU/KVM only) -

    -
    -
    eim
    -
    -

    - The eim attribute (with possible values - on and off) can be used to - configure Extended Interrupt Mode. A q35 domain with - split I/O APIC (as described in - hypervisor features), - and both interrupt remapping and EIM turned on for - the IOMMU, will be able to use more than 255 vCPUs. - Since 3.4.0 (QEMU/KVM only) -

    -
    -
    iotlb
    -
    -

    - The iotlb attribute with possible values - on and off can be used to - turn on the IOTLB used to cache address translation - requests from devices. - Since 3.5.0 (QEMU/KVM only) -

    -
    -
    aw_bits
    -
    -

    - The aw_bits attribute can be used to set - the address width to allow mapping larger iova addresses - in the guest. - Since 6.5.0 (QEMU/KVM only) -

    -
    -
    -
    -
    - -

    Vsock

    - -

    A vsock host/guest interface. The model attribute - defaults to virtio. Since 5.2.0 - model can also be 'virtio-transitional' and - 'virtio-non-transitional', see - Virtio transitional devices - for more details. - The optional attribute address of the cid - element specifies the CID assigned to the guest. If the attribute - auto is set to yes, libvirt - will assign a free CID automatically on domain startup. - Since 4.4.0

    - -
    -...
-<devices>
-  <vsock model=3D'virtio'>
-    <cid auto=3D'no' address=3D'3'/>
-  </vsock>
-</devices>
-...
    - - -

    Security label

    - -

    - The seclabel element allows control over the - operation of the security drivers. There are three basic - modes of operation, 'dynamic' where libvirt automatically - generates a unique security label, 'static' where the - application/administrator chooses the labels, or 'none' - where confinement is disabled. With dynamic - label generation, libvirt will always automatically - relabel any resources associated with the virtual machine. - With static label assignment, by default, the administrator - or application must ensure labels are set correctly on any - resources, however, automatic relabeling can be enabled - if desired. 'dynamic' since 0.6.1, 'static' - since 0.6.2, and 'none' since 0.9.10. -

    - -

    - If more than one security driver is used by libvirt, multiple - seclabel tags can be used, one for each driver and - the security driver referenced by each tag can be defined using - the attribute model -

    - -

    - Valid input XML configurations for the top-level security label - are: -

    - - 
    -<seclabel type=3D'dynamic' model=3D'selinux'/>
-
-<seclabel type=3D'dynamic' model=3D'selinux'>
-  <baselabel>system_u:system_r:my_svirt_t:s0</baselabel>
-</seclabel>
-
-<seclabel type=3D'static' model=3D'selinux' relabel=3D'no'>
-  <label>system_u:system_r:svirt_t:s0:c392,c662</label>
-</seclabel>
-
-<seclabel type=3D'static' model=3D'selinux' relabel=3D'yes'>
-  <label>system_u:system_r:svirt_t:s0:c392,c662</label>
-</seclabel>
-
-<seclabel type=3D'none'/>
-
    - -

    - If no 'type' attribute is provided in the input XML, then - the security driver default setting will be used, which - may be either 'none' or 'dynamic'. If a 'baselabel' is set - but no 'type' is set, then the type is presumed to be 'dynamic' -

    - -

    - When viewing the XML for a running guest with automatic - resource relabeling active, an additional XML element, - imagelabel, will be included. This is an - output-only element, so will be ignored in user supplied - XML documents -

    -
    -
    type
    -
    Either static, dynamic or none - to determine whether libvirt automatically generates a unique secu= rity - label or not. -
    -
    model
    -
    A valid security model name, matching the currently - activated security model. Model dac is not available - when guest is run by unprivileged user. -
    -
    relabel
    -
    Either yes or no. This must always - be yes if dynamic label assignment is used. With - static label assignment it will default to no. -
    -
    label
    -
    If static labelling is used, this must specify the full - security label to assign to the virtual domain. The format - of the content depends on the security driver in use: -
      -
    • SELinux: a SELinux context.
      • -
    • AppArmor: an AppArmor profile.
      • -
    • - DAC: owner and group separated by colon. They can be - defined both as user/group names or uid/gid. The driver will f= irst - try to parse these values as names, but a leading plus sign can - used to force the driver to parse them as uid or gid. -
      • -
    -
    -
    baselabel
    -
    If dynamic labelling is used, this can optionally be - used to specify the base security label that will be used to gener= ate - the actual label. The format of the content depends on the security - driver in use. - - The SELinux driver uses only the type field of the - baselabel in the generated label. Other fields are inherited from - the parent process when using SELinux baselabels. - - (The example above demonstrates the use of my_svirt_t - as the value for the type field.) -
    -
    imagelabel
    -
    This is an output only element, which shows the - security label used on resources associated with the virtual domai= n. - The format of the content depends on the security driver in use -
    -
    - -

    When relabeling is in effect, it is also possible to fine-tune - the labeling done for specific source file names, by either - disabling the labeling (useful if the file lives on NFS or other - file system that lacks security labeling) or requesting an - alternate label (useful when a management application creates a - special label to allow sharing of some, but not all, resources - between domains), since 0.9.9. When - a seclabel element is attached to a specific path - rather than the top-level domain assignment, only the - attribute relabel or the - sub-element label are supported. Additionally, - since 1.1.2, an output-only - element labelskip will be present for active - domains on disks where labeling was skipped due to the image - being on a file system that lacks security labeling. -

    - -

    Key Wrap

    - -

    The content of the optional keywrap element specifi= es - whether the guest will be allowed to perform the S390 cryptographi= c key - management operations. A clear key can be protected by encrypting = it - under a unique wrapping key that is generated for each guest VM ru= nning - on the host. Two variations of wrapping keys are generated: one ve= rsion - for encrypting protected keys using the DEA/TDEA algorithm, and an= other - version for keys encrypted using the AES algorithm. If a - keywrap element is not included, the guest will be gr= anted - access to both AES and DEA/TDEA key wrapping by default.

    - - 
    -<domain>
-  ...
-  <keywrap>
-    <cipher name=3D'aes' state=3D'off'/>
-  </keywrap>
-  ...
-</domain>
-
    -

    - At least one cipher element must be nested within the - keywrap element. -

    -
    -
    cipher
    -
    The name attribute identifies the algorithm - for encrypting a protected key. The values supported for this attr= ibute - are aes for encryption under the AES wrapping key, or - dea for encryption under the DEA/TDEA wrapping key. T= he - state attribute indicates whether the cryptographic k= ey - management operations should be turned on for the specified encryp= tion - algorithm. The value can be set to on or off. -
    -
    - -

    Note: DEA/TDEA is synonymous with DES/TDES.

    - -

    Launch Security

    - -

    - The contents of the <launchSecurity type=3D'sev'> element - is used to provide the guest owners input used for creating an encr= ypted - VM using the AMD SEV feature (Secure Encrypted Virtualization). - - SEV is an extension to the AMD-V architecture which supports running - encrypted virtual machine (VMs) under the control of KVM. Encrypted - VMs have their pages (code and data) secured such that only the gue= st - itself has access to the unencrypted version. Each encrypted VM is - associated with a unique encryption key; if its data is accessed to= a - different entity using a different key the encrypted guests data wi= ll - be incorrectly decrypted, leading to unintelligible data. - - For more information see various input parameters and its format se= e the - SEV API spec - Since 4.4.0 -

    - 
    -<domain>
-  ...
-  <launchSecurity type=3D'sev'>
-    <policy>0x0001</policy>
-    <cbitpos>47</cbitpos>
-    <reducedPhysBits>1</reducedPhysBits>
-    <dhCert>RBBBSDDD=3DFDDCCCDDDG</dhCert>
-    <session>AAACCCDD=3DFFFCCCDSDS</session>
-  </launchSecurity>
-  ...
-</domain>
-
    - -
    -
    cbitpos
    -
    The required cbitpos element provides the C-bit (ak= a encryption bit) - location in guest page table entry. The value of cbitpos is - hypervisor dependent and can be obtained through the sev element - from the domain capabilities. -
    -
    reducedPhysBits
    -
    The required reducedPhysBits element provides the p= hysical - address bit reducation. Similar to cbitpos the value of= - reduced-phys-bit is hypervisor dependent and can be obtained - through the sev element from the domain capabilities. -
    -
    policy
    -
    The required policy element provides the guest poli= cy - which must be maintained by the SEV firmware. This policy is enforce= d by - the firmware and restricts what configuration and operational comman= ds - can be performed on this guest by the hypervisor. The guest policy - provided during guest launch is bound to the guest and cannot be cha= nged - throughout the lifetime of the guest. The policy is also transmitted - during snapshot and migration flows and enforced on the destination = platform. - - The guest policy is a 4 unsigned byte with the fields shown in Table: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Bit(s) Description
    0 Debugging of the guest is disallowed when set
    1 Sharing keys with other guests is disallowed when set
    2 SEV-ES is required when set
    3 Sending the guest to another platform is disallowed when se= t
    4 The guest must not be transmitted to another platform that = is - not in the domain when set.
    5 The guest must not be transmitted to another platform that = is - not SEV capable when set.
    6:15 reserved
    16:32 The guest must not be transmitted to another platform with a - lower firmware version.
    - -
    -
    dhCert
    -
    The optional dhCert element provides the guest owne= rs - base64 encoded Diffie-Hellman (DH) key. The key is used to negotiate= a - master secret key between the SEV firmware and guest owner. This mas= ter - secret key is then used to establish a trusted channel between SEV - firmware and guest owner. -
    -
    session
    -
    The optional session element provides the guest own= ers - base64 encoded session blob defined in the SEV API spec. - - See SEV spec LAUNCH_START section for the session blob format. -
    -
    - -

    Example configs

    - -

    - Example configurations for each driver are provide on the - driver specific pages listed below -

    - - - - diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst new file mode 100644 index 0000000000..776dcf7e25 --- /dev/null +++ b/docs/formatdomain.rst @@ -0,0 +1,7442 @@ +.. role:: since +.. role:: anchor(raw) + :format: html + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Domain XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +This section describes the XML format used to represent domains, there are +variations on the format based on the kind of domains run and the options = used +to launch them. For hypervisor specific details consult the `driver +docs `__ + +:anchor:`` + +Element and attribute overview +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + +The root element required for all virtual machines is named ``domain``. It= has +two attributes, the ``type`` specifies the hypervisor used for running the +domain. The allowed values are driver specific, but include "xen", "kvm", = "qemu" +and "lxc". The second attribute is ``id`` which is a unique integer identi= fier +for the running guest machine. Inactive machines have no id value. + +:anchor:`` + +General metadata +---------------- + +:: + + + MyGuest + 4dea22b3-1d52-d8f3-2516-782e98ab3fa0 + 43dc0cf8-809b-4adb-9bea-a9abb5f3d90e + A short description - title - of the domain + Some human readable description + + .. + .. + + ... + +``name`` + The content of the ``name`` element provides a short name for the virtu= al + machine. This name should consist only of alpha-numeric characters and = is + required to be unique within the scope of a single host. It is often us= ed to + form the filename for storing the persistent configuration file. + :since:`Since 0.0.1` +``uuid`` + The content of the ``uuid`` element provides a globally unique identifi= er for + the virtual machine. The format must be RFC 4122 compliant, eg + ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/crea= ting a + new machine, a random UUID is generated. It is also possible to provide= the + UUID via a `sysinfo <#elementsSysinfo>`__ specification. :since:`Since = 0.0.1, + sysinfo since 0.8.7` +``genid`` + :since:`Since 4.4.0` , the ``genid`` element can be used to add a Virtu= al + Machine Generation ID which exposes a 128-bit, cryptographically random, + integer value identifier, referred to as a Globally Unique Identifier (= GUID) + using the same format as the ``uuid``. The value is used to help notify= the + guest operating system when the virtual machine is re-executing somethi= ng + that has already executed before, such as: + + - VM starts executing a snapshot + - VM is recovered from backup + - VM is failover in a disaster recovery environment + - VM is imported, copied, or cloned + + The guest operating system notices the change and is then able to react= as + appropriate by marking its copies of distributed databases as dirty, + re-initializing its random number generator, etc. + + The libvirt XML parser will accept both a provided GUID value or just + in which case a GUID will be generated and saved in the XML. F= or the + transitions such as above, libvirt will change the GUID before re-execu= ting. + +``title`` + The optional element ``title`` provides space for a short description o= f the + domain. The title should not contain any newlines. :since:`Since 0.9.10= ` . +``description`` + The content of the ``description`` element provides a human readable + description of the virtual machine. This data is not used by libvirt in= any + way, it can contain any information the user wants. :since:`Since 0.7.2` +``metadata`` + The ``metadata`` node can be used by applications to store custom metad= ata in + the form of XML nodes/trees. Applications must use custom namespaces on= their + XML nodes/trees, with only one top-level element per namespace (if the + application needs structure, they should have sub-elements to their nam= espace + element). :since:`Since 0.9.10` + +:anchor:`` + +Operating system booting +------------------------ + +There are a number of different ways to boot virtual machines each with th= eir +own pros and cons. + +:anchor:`` + +BIOS bootloader +~~~~~~~~~~~~~~~ + +Booting via the BIOS is available for hypervisors supporting full +virtualization. In this case the BIOS has a boot order priority (floppy, +harddisk, cdrom, network) determining where to obtain/find the boot image. + +:: + + ... + + hvm + /usr/lib/xen/boot= /hvmloader + /var/lib/libvirt/nvr= am/guest_VARS.fd + + + + + + + ... + +``firmware`` + The ``firmware`` attribute allows management applications to automatica= lly + fill ```` and ```` elements and possibly enable some + features required by selected firmware. Accepted values are ``bios`` and + ``efi``. + The selection process scans for files describing installed firmware ima= ges in + specified location and uses the most specific one which fulfils domain + requirements. The locations in order of preference (from generic to most + specific one) are: + + - ``/usr/share/qemu/firmware`` + - ``/etc/qemu/firmware`` + - ``$XDG_CONFIG_HOME/qemu/firmware`` + + For more information refer to firmware metadata specification as descri= bed in + ``docs/interop/firmware.json`` in QEMU repository. Regular users do not= need + to bother. :since:`Since 5.2.0 (QEMU and KVM only)` + For VMware guests, this is set to ``efi`` when the guest uses UEFI, and= it is + not set when using BIOS. :since:`Since 5.3.0 (VMware ESX and + Workstation/Player)` +``type`` + The content of the ``type`` element specifies the type of operating sys= tem to + be booted in the virtual machine. ``hvm`` indicates that the OS is one + designed to run on bare metal, so requires full virtualization. ``linux= `` + (badly named!) refers to an OS that supports the Xen 3 hypervisor guest= ABI. + There are also two optional attributes, ``arch`` specifying the CPU + architecture to virtualization, and ``machine`` referring to the machine + type. The `Capabilities XML `__ provides details on al= lowed + values for these. If ``arch`` is omitted then for most hypervisor drive= rs, + the host native arch will be chosen. For the ``test``, ``ESX`` and ``VM= Ware`` + hypervisor drivers, however, the ``i686`` arch will always be chosen ev= en on + an ``x86_64`` host. :since:`Since 0.0.1` +``loader`` + The optional ``loader`` tag refers to a firmware blob, which is specifi= ed by + absolute path, used to assist the domain creation process. It is used b= y Xen + fully virtualized domains as well as setting the QEMU BIOS file path for + QEMU/KVM domains. :since:`Xen since 0.1.0, QEMU/KVM since 0.9.12` Then, + :since:`since 1.2.8` it's possible for the element to have two optional + attributes: ``readonly`` (accepted values are ``yes`` and ``no``) to re= flect + the fact that the image should be writable or read-only. The second att= ribute + ``type`` accepts values ``rom`` and ``pflash``. It tells the hypervisor= where + in the guest memory the file should be mapped. For instance, if the loa= der + path points to an UEFI image, ``type`` should be ``pflash``. Moreover, = some + firmwares may implement the Secure boot feature. Attribute ``secure`` c= an be + used then to control it. :since:`Since 2.1.0` +``nvram`` + Some UEFI firmwares may want to use a non-volatile memory to store some + variables. In the host, this is represented as a file and the absolute = path + to the file is stored in this element. Moreover, when the domain is sta= rted + up libvirt copies so called master NVRAM store file defined in ``qemu.c= onf``. + If needed, the ``template`` attribute can be used to per domain overrid= e map + of master NVRAM stores from the config file. Note, that for transient d= omains + if the NVRAM file has been created by libvirt it is left behind and it = is + management application's responsibility to save and remove file (if nee= ded to + be persistent). :since:`Since 1.2.8` +``boot`` + The ``dev`` attribute takes one of the values "fd", "hd", "cdrom" or + "network" and is used to specify the next boot device to consider. The + ``boot`` element can be repeated multiple times to setup a priority lis= t of + boot devices to try in turn. Multiple devices of the same type are sort= ed + according to their targets while preserving the order of buses. After + defining the domain, its XML configuration returned by libvirt (through + virDomainGetXMLDesc) lists devices in the sorted order. Once sorted, the + first device is marked as bootable. Thus, e.g., a domain configured to = boot + from "hd" with vdb, hda, vda, and hdc disks assigned to it will boot fr= om vda + (the sorted list is vda, vdb, hda, hdc). Similar domain with hdc, vda, = vdb, + and hda disks will boot from hda (sorted disks are: hda, hdc, vda, vdb)= . It + can be tricky to configure in the desired way, which is why per-device = boot + elements (see `disks <#elementsDisks>`__, `network + interfaces <#elementsNICS>`__, and `USB and PCI devices <#elementsHostD= ev>`__ + sections below) were introduced and they are the preferred way providin= g full + control over booting order. The ``boot`` element and per-device boot el= ements + are mutually exclusive. :since:`Since 0.1.3, per-device boot since 0.8.= 8` +``smbios`` + How to populate SMBIOS information visible in the guest. The ``mode`` + attribute must be specified, and is either "emulate" (let the hypervisor + generate all values), "host" (copy all of Block 0 and Block 1, except f= or the + UUID, from the host's SMBIOS values; the + `virConnectGetSysinfo `__ + call can be used to see what values are copied), or "sysinfo" (use the = values + in the `sysinfo <#elementsSysinfo>`__ element). If not specified, the + hypervisor default is used. :since:` Since 0.8.7` + +Up till here the BIOS/UEFI configuration knobs are generic enough to be +implemented by majority (if not all) firmwares out there. However, from no= w on +not every single setting makes sense to all firmwares. For instance, +``rebootTimeout`` doesn't make sense for UEFI, ``useserial`` might not be = usable +with a BIOS firmware that doesn't produce any output onto serial line, etc. +Moreover, firmwares don't usually export their capabilities for libvirt (or +users) to check. And the set of their capabilities can change with every n= ew +release. Hence users are advised to try the settings they use before relyi= ng on +them in production. + +``bootmenu`` + Whether or not to enable an interactive boot menu prompt on guest start= up. + The ``enable`` attribute can be either "yes" or "no". If not specified,= the + hypervisor default is used. :since:` Since 0.8.3` Additional attribute + ``timeout`` takes the number of milliseconds the boot menu should wait = until + it times out. Allowed values are numbers in range [0, 65535] inclusive = and it + is ignored unless ``enable`` is set to "yes". :since:`Since 1.2.8` +``bios`` + This element has attribute ``useserial`` with possible values ``yes`` or + ``no``. It enables or disables Serial Graphics Adapter which allows use= rs to + see BIOS messages on a serial port. Therefore, one needs to have `serial + port <#elementCharSerial>`__ defined. :since:`Since 0.9.4` . :since:`Si= nce + 0.10.2 (QEMU only)` there is another attribute, ``rebootTimeout`` that + controls whether and after how long the guest should start booting agai= n in + case the boot fails (according to BIOS). The value is in milliseconds w= ith + maximum of ``65535`` and special value ``-1`` disables the reboot. + +:anchor:`` + +Host bootloader +~~~~~~~~~~~~~~~ + +Hypervisors employing paravirtualization do not usually emulate a BIOS, and +instead the host is responsible to kicking off the operating system boot. = This +may use a pseudo-bootloader in the host to provide an interface to choose a +kernel for the guest. An example is ``pygrub`` with Xen. The Bhyve hypervi= sor +also uses a host bootloader, either ``bhyveload`` or ``grub-bhyve``. + +:: + + ... + /usr/bin/pygrub + --append single + ... + +``bootloader`` + The content of the ``bootloader`` element provides a fully qualified pa= th to + the bootloader executable in the host OS. This bootloader will be run to + choose which kernel to boot. The required output of the bootloader is + dependent on the hypervisor in use. :since:`Since 0.1.0` +``bootloader_args`` + The optional ``bootloader_args`` element allows command line arguments = to be + passed to the bootloader. :since:`Since 0.2.3` + +:anchor:`` + +Direct kernel boot +~~~~~~~~~~~~~~~~~~ + +When installing a new guest OS it is often useful to boot directly from a = kernel +and initrd stored in the host OS, allowing command line arguments to be pa= ssed +directly to the installer. This capability is usually available for both p= ara +and full virtualized guests. + +:: + + ... + + hvm + /usr/lib/xen/boot/hvmloader + /root/f8-i386-vmlinuz + /root/f8-i386-initrd + console=3DttyS0 ks=3Dhttp://example.com/f8-i386/os/ + /root/ppc.dtb + + /path/to/slic.dat
    +     +     + ... + +``type`` + This element has the same semantics as described earlier in the `BIOS b= oot + section <#elementsOSBIOS>`__ +``loader`` + This element has the same semantics as described earlier in the `BIOS b= oot + section <#elementsOSBIOS>`__ +``kernel`` + The contents of this element specify the fully-qualified path to the ke= rnel + image in the host OS. +``initrd`` + The contents of this element specify the fully-qualified path to the + (optional) ramdisk image in the host OS. +``cmdline`` + The contents of this element specify arguments to be passed to the kern= el (or + installer) at boot time. This is often used to specify an alternate pri= mary + console (eg serial port), or the installation media source / kickstart = file +``dtb`` + The contents of this element specify the fully-qualified path to the + (optional) device tree binary (dtb) image in the host OS. :since:`Since + 1.0.4` +``acpi`` + The ``table`` element contains a fully-qualified path to the ACPI table= . The + ``type`` attribute contains the ACPI table type (currently only ``slic`= ` is + supported) :since:`Since 1.3.5 (QEMU)` :since:`Since 5.9.0 (Xen)` + +:anchor:`    ` + +Container boot +~~~~~~~~~~~~~~ + +When booting a domain using container based virtualization, instead of a k= ernel +/ boot image, a path to the init binary is required, using the ``init`` el= ement. +By default this will be launched with no arguments. To specify the initial= argv, +use the ``initarg`` element, repeated as many time as is required. The +``cmdline`` element, if set will be used to provide an equivalent to +``/proc/cmdline`` but will not affect init argv. + +To set environment variables, use the ``initenv`` element, one for each +variable. + +To set a custom work directory for the init, use the ``initdir`` element. + +To run the init command as a given user or group, use the ``inituser`` or +``initgroup`` elements respectively. Both elements can be provided either = a user +(resp. group) id or a name. Prefixing the user or group id with a ``+`` wi= ll +force it to be considered like a numeric value. Without this, it will be f= irst +tried as a user or group name. + +:: + + + exe + /bin/systemd + --unit + emergency.service + some value + /my/custom/cwd + tester + 1000 + + +If you want to enable user namespace, set the ``idmap`` element. The ``uid= `` and +``gid`` elements have three attributes: + +``start`` + First user ID in container. It must be '0'. +``target`` + The first user ID in container will be mapped to this target user ID in= host. +``count`` + How many users in container are allowed to map to host's user. + +:: + + + + + + +:anchor:`` + +SMBIOS System Information +------------------------- + +Some hypervisors allow control over what system information is presented t= o the +guest (for example, SMBIOS fields can be populated by a hypervisor and ins= pected +via the ``dmidecode`` command in the guest). The optional ``sysinfo`` elem= ent +covers all such categories of information. :since:`Since 0.8.7` + +:: + + ... + + + ... + + + + LENOVO + + + Fedora + Virt-Manager + 0.9.4 + + + LENOVO + 20BE0061MC + 0B98401 Pro + W1KS427111E + + + Dell Inc. + 2.12 + 65X0XF2 + 40000101 + Type3Sku1 + + + myappname:some arbitrary data + otherappname:more arbitrary data + + + + example value + + + ... + +The ``sysinfo`` element has a mandatory attribute ``type`` that determine = the +layout of sub-elements, with supported values of: + +``smbios`` + Sub-elements call out specific SMBIOS values, which will affect the gue= st if + used in conjunction with the ``smbios`` sub-element of the + `os <#elementsOS>`__ element. Each sub-element of ``sysinfo`` names a S= MBIOS + block, and within those elements can be a list of ``entry`` elements th= at + describe a field within the block. The following blocks and entries are + recognized: + + ``bios`` + This is block 0 of SMBIOS, with entry names drawn from: + + ``vendor`` + BIOS Vendor's Name + ``version`` + BIOS Version + ``date`` + BIOS release date. If supplied, is in either mm/dd/yy or mm/dd/yy= yy + format. If the year portion of the string is two digits, the year= is + assumed to be 19yy. + ``release`` + System BIOS Major and Minor release number values concatenated to= gether + as one string separated by a period, for example, 10.22. + + ``system`` + This is block 1 of SMBIOS, with entry names drawn from: + + ``manufacturer`` + Manufacturer of BIOS + ``product`` + Product Name + ``version`` + Version of the product + ``serial`` + Serial number + ``uuid`` + Universal Unique ID number. If this entry is provided alongside a + top-level `uuid <#elementsMetadata>`__ element, then the two valu= es + must match. + ``sku`` + SKU number to identify a particular configuration. + ``family`` + Identify the family a particular computer belongs to. + + ``baseBoard`` + This is block 2 of SMBIOS. This element can be repeated multiple tim= es to + describe all the base boards; however, not all hypervisors necessari= ly + support the repetition. The element can have the following children: + + ``manufacturer`` + Manufacturer of BIOS + ``product`` + Product Name + ``version`` + Version of the product + ``serial`` + Serial number + ``asset`` + Asset tag + ``location`` + Location in chassis + + NB: Incorrectly supplied entries for the ``bios``, ``system`` or + ``baseBoard`` blocks will be ignored without error. Other than ``uui= d`` + validation and ``date`` format checking, all values are passed as st= rings + to the hypervisor driver. + ``chassis`` + :since:`Since 4.1.0,` this is block 3 of SMBIOS, with entry names dr= awn + from: + + ``manufacturer`` + Manufacturer of Chassis + ``version`` + Version of the Chassis + ``serial`` + Serial number + ``asset`` + Asset tag + ``sku`` + SKU number + + ``oemStrings`` + This is block 11 of SMBIOS. This element should appear once and can = have + multiple ``entry`` child elements, each providing arbitrary string d= ata. + There are no restrictions on what data can be provided in the entrie= s, + however, if the data is intended to be consumed by an application in= the + guest, it is recommended to use the application name as a prefix in = the + string. ( :since:`Since 4.1.0` ) + +``fwcfg`` + Some hypervisors provide unified way to tweak how firmware configures i= tself, + or may contain tables to be installed for the guest OS, for instance bo= ot + order, ACPI, SMBIOS, etc. It even allows users to define their own conf= ig + blobs. In case of QEMU, these then appear under domain's sysfs, under + ``/sys/firmware/qemu_fw_cfg``. Note, that these values apply regardless= the + mode under . :since:`Since 6.5.0` + + :: + + + example value + + + + The ``smbios`` element can have multiple ``entry`` child elements. Each + element then has mandatory ``name`` attribute, which defines the name o= f the + blob and must begin with ``"opt/"`` and to avoid clashing with other na= mes is + advised to be in form ``"opt/$RFQDN/$name"`` where ``$RFQDN`` is a reve= rse + fully qualified domain name you control. Then, the element can either c= ontain + the value (to set the blob value directly), or ``file`` attribute (to s= et the + blob value from the file). + +:anchor:`` + +CPU Allocation +-------------- + +:: + + + ... + 2 + + + + + ... + + +``vcpu`` + The content of this element defines the maximum number of virtual CPUs + allocated for the guest OS, which must be between 1 and the maximum sup= ported + by the hypervisor. + + ``cpuset`` + The optional attribute ``cpuset`` is a comma-separated list of physi= cal + CPU numbers that domain process and virtual CPUs can be pinned to by + default. (NB: The pinning policy of domain process and virtual CPUs = can be + specified separately by ``cputune``. If the attribute ``emulatorpin`= ` of + ``cputune`` is specified, the ``cpuset`` specified by ``vcpu`` here = will + be ignored. Similarly, for virtual CPUs which have the ``vcpupin`` + specified, the ``cpuset`` specified by ``cpuset`` here will be ignor= ed. + For virtual CPUs which don't have ``vcpupin`` specified, each will be + pinned to the physical CPUs specified by ``cpuset`` here). Each elem= ent in + that list is either a single CPU number, a range of CPU numbers, or a + caret followed by a CPU number to be excluded from a previous range. + :since:`Since 0.4.4` + ``current`` + The optional attribute ``current`` can be used to specify whether fe= wer + than the maximum number of virtual CPUs should be enabled. :since:`S= ince + 0.8.5` + ``placement`` + The optional attribute ``placement`` can be used to indicate the CPU + placement mode for domain process. The value can be either "static" = or + "auto", but defaults to ``placement`` of ``numatune`` or "static" if + ``cpuset`` is specified. Using "auto" indicates the domain process w= ill be + pinned to the advisory nodeset from querying numad and the value of + attribute ``cpuset`` will be ignored if it's specified. If both ``cp= uset`` + and ``placement`` are not specified or if ``placement`` is "static",= but + no ``cpuset`` is specified, the domain process will be pinned to all= the + available physical CPUs. :since:`Since 0.9.11 (QEMU and KVM only)` + +``vcpus`` + The vcpus element allows to control state of individual vCPUs. The ``id= `` + attribute specifies the vCPU id as used by libvirt in other places such= as + vCPU pinning, scheduler information and NUMA assignment. Note that the = vCPU + ID as seen in the guest may differ from libvirt ID in certain cases. Va= lid + IDs are from 0 to the maximum vCPU count as set by the ``vcpu`` element= minus + 1. The ``enabled`` attribute allows to control the state of the vCPU. V= alid + values are ``yes`` and ``no``. ``hotpluggable`` controls whether given = vCPU + can be hotplugged and hotunplugged in cases when the CPU is enabled at = boot. + Note that all disabled vCPUs must be hotpluggable. Valid values are ``y= es`` + and ``no``. ``order`` allows to specify the order to add the online vCP= Us. + For hypervisors/platforms that require to insert multiple vCPUs at once= the + order may be duplicated across all vCPUs that need to be enabled at onc= e. + Specifying order is not necessary, vCPUs are then added in an arbitrary + order. If order info is used, it must be used for all online vCPUs. + Hypervisors may clear or update ordering information during certain + operations to assure valid configuration. Note that hypervisors may cre= ate + hotpluggable vCPUs differently from boot vCPUs thus special initializat= ion + may be necessary. Hypervisors may require that vCPUs enabled on boot wh= ich + are not hotpluggable are clustered at the beginning starting with ID 0.= It + may be also required that vCPU 0 is always present and non-hotpluggable= . Note + that providing state for individual CPUs may be necessary to enable sup= port + of addressable vCPU hotplug and this feature may not be supported by all + hypervisors. For QEMU the following conditions are required. vCPU 0 nee= ds to + be enabled and non-hotpluggable. On PPC64 along with it vCPUs that are = in the + same core need to be enabled as well. All non-hotpluggable CPUs present= at + boot need to be grouped after vCPU 0. :since:`Since 2.2.0 (QEMU only)` + +:anchor:`` + +IOThreads Allocation +-------------------- + +IOThreads are dedicated event loop threads for supported disk devices to p= erform +block I/O requests in order to improve scalability especially on an SMP +host/guest with many LUNs. :since:`Since 1.2.8 (QEMU only)` + +:: + + + ... + 4 + ... + + +:: + + + ... + + + + + + + ... + + +``iothreads`` + The content of this optional element defines the number of IOThreads to= be + assigned to the domain for use by supported target storage devices. The= re + should be only 1 or 2 IOThreads per host CPU. There may be more than one + supported device assigned to each IOThread. :since:`Since 1.2.8` +``iothreadids`` + The optional ``iothreadids`` element provides the capability to specifi= cally + define the IOThread ID's for the domain. By default, IOThread ID's are + sequentially numbered starting from 1 through the number of ``iothreads= `` + defined for the domain. The ``id`` attribute is used to define the IOTh= read + ID. The ``id`` attribute must be a positive integer greater than 0. If = there + are less ``iothreadids`` defined than ``iothreads`` defined for the dom= ain, + then libvirt will sequentially fill ``iothreadids`` starting at 1 avoid= ing + any predefined ``id``. If there are more ``iothreadids`` defined than + ``iothreads`` defined for the domain, then the ``iothreads`` value will= be + adjusted accordingly. :since:`Since 1.2.15` + +:anchor:`` + +CPU Tuning +---------- + +:: + + + ... + + + + + + + + + 2048 + 1000000 + -1 + 1000000 + -1 + 1000000 + -1 + 1000000 + -1 + + + + + + + + + + + + + + + + + + ... + + +``cputune`` + The optional ``cputune`` element provides details regarding the CPU tun= able + parameters for the domain. Note: for the qemu driver, the optional + ``vcpupin`` and ``emulatorpin`` pinning settings are honored after the + emulator is launched and NUMA constraints considered. This means that i= t is + expected that other physical CPUs of the host will be used during this = time + by the domain, which will be reflected by the output of ``virsh cpu-sta= ts``. + :since:`Since 0.9.0` +``vcpupin`` + The optional ``vcpupin`` element specifies which of host's physical CPU= s the + domain vCPU will be pinned to. If this is omitted, and attribute ``cpus= et`` + of element ``vcpu`` is not specified, the vCPU is pinned to all the phy= sical + CPUs by default. It contains two required attributes, the attribute ``v= cpu`` + specifies vCPU id, and the attribute ``cpuset`` is same as attribute + ``cpuset`` of element ``vcpu``. (NB: Only qemu driver support) :since:`= Since + 0.9.0` +``emulatorpin`` + The optional ``emulatorpin`` element specifies which of host physical C= PUs + the "emulator", a subset of a domain not including vCPU or iothreads wi= ll be + pinned to. If this is omitted, and attribute ``cpuset`` of element ``vc= pu`` + is not specified, "emulator" is pinned to all the physical CPUs by defa= ult. + It contains one required attribute ``cpuset`` specifying which physical= CPUs + to pin to. +``iothreadpin`` + The optional ``iothreadpin`` element specifies which of host physical C= PUs + the IOThreads will be pinned to. If this is omitted and attribute ``cpu= set`` + of element ``vcpu`` is not specified, the IOThreads are pinned to all t= he + physical CPUs by default. There are two required attributes, the attrib= ute + ``iothread`` specifies the IOThread ID and the attribute ``cpuset`` + specifying which physical CPUs to pin to. See the ``iothreadids`` + `description <#elementsIOThreadsAllocation>`__ for valid ``iothread`` v= alues. + :since:`Since 1.2.9` +``shares`` + The optional ``shares`` element specifies the proportional weighted sha= re for + the domain. If this is omitted, it defaults to the OS provided defaults= . NB, + There is no unit for the value, it's a relative measure based on the se= tting + of other VM, e.g. A VM configured with value 2048 will get twice as muc= h CPU + time as a VM configured with value 1024. :since:`Since 0.9.0` +``period`` + The optional ``period`` element specifies the enforcement interval (uni= t: + microseconds). Within ``period``, each vCPU of the domain will not be a= llowed + to consume more than ``quota`` worth of runtime. The value should be in= range + [1000, 1000000]. A period with value 0 means no value. :since:`Only QEMU + driver support since 0.9.4, LXC since 0.9.10` +``quota`` + The optional ``quota`` element specifies the maximum allowed bandwidth = (unit: + microseconds). A domain with ``quota`` as any negative value indicates = that + the domain has infinite bandwidth for vCPU threads, which means that it= is + not bandwidth controlled. The value should be in range [1000, + 18446744073709551] or less than 0. A quota with value 0 means no value.= You + can use this feature to ensure that all vCPUs run at the same speed. + :since:`Only QEMU driver support since 0.9.4, LXC since 0.9.10` +``global_period`` + The optional ``global_period`` element specifies the enforcement CFS + scheduler interval (unit: microseconds) for the whole domain in contras= t with + ``period`` which enforces the interval per vCPU. The value should be in= range + 1000, 1000000]. A ``global_period`` with value 0 means no value. :since= :`Only + QEMU driver support since 1.3.3` +``global_quota`` + The optional ``global_quota`` element specifies the maximum allowed ban= dwidth + (unit: microseconds) within a period for the whole domain. A domain with + ``global_quota`` as any negative value indicates that the domain has in= finite + bandwidth, which means that it is not bandwidth controlled. The value s= hould + be in range [1000, 18446744073709551] or less than 0. A ``global_quota`= ` with + value 0 means no value. :since:`Only QEMU driver support since 1.3.3` +``emulator_period`` + The optional ``emulator_period`` element specifies the enforcement inte= rval + (unit: microseconds). Within ``emulator_period``, emulator threads (tho= se + excluding vCPUs) of the domain will not be allowed to consume more than + ``emulator_quota`` worth of runtime. The value should be in range [1000, + 1000000]. A period with value 0 means no value. :since:`Only QEMU driver + support since 0.10.0` +``emulator_quota`` + The optional ``emulator_quota`` element specifies the maximum allowed + bandwidth (unit: microseconds) for domain's emulator threads (those exc= luding + vCPUs). A domain with ``emulator_quota`` as any negative value indicate= s that + the domain has infinite bandwidth for emulator threads (those excluding + vCPUs), which means that it is not bandwidth controlled. The value shou= ld be + in range [1000, 18446744073709551] or less than 0. A quota with value 0= means + no value. :since:`Only QEMU driver support since 0.10.0` +``iothread_period`` + The optional ``iothread_period`` element specifies the enforcement inte= rval + (unit: microseconds) for IOThreads. Within ``iothread_period``, each IO= Thread + of the domain will not be allowed to consume more than ``iothread_quota= `` + worth of runtime. The value should be in range [1000, 1000000]. An + iothread_period with value 0 means no value. :since:`Only QEMU driver s= upport + since 2.1.0` +``iothread_quota`` + The optional ``iothread_quota`` element specifies the maximum allowed + bandwidth (unit: microseconds) for IOThreads. A domain with + ``iothread_quota`` as any negative value indicates that the domain IOTh= reads + have infinite bandwidth, which means that it is not bandwidth controlle= d. The + value should be in range [1000, 18446744073709551] or less than 0. An + ``iothread_quota`` with value 0 means no value. You can use this featur= e to + ensure that all IOThreads run at the same speed. :since:`Only QEMU driv= er + support since 2.1.0` +``vcpusched``, ``iothreadsched`` and ``emulatorsched`` + The optional ``vcpusched``, ``iothreadsched`` and ``emulatorsched`` ele= ments + specify the scheduler type (values ``batch``, ``idle``, ``fifo``, ``rr`= `) for + particular vCPU, IOThread and emulator threads respecively. For ``vcpus= ched`` + and ``iothreadsched`` the attributes ``vcpus`` and ``iothreads`` select= which + vCPUs/IOThreads this setting applies to, leaving them out sets the defa= ult. + The element ``emulatorsched`` does not have that attribute. Valid ``vcp= us`` + values start at 0 through one less than the number of vCPU's defined fo= r the + domain. Valid ``iothreads`` values are described in the ``iothreadids`` + `description <#elementsIOThreadsAllocation>`__. If no ``iothreadids`` a= re + defined, then libvirt numbers IOThreads from 1 to the number of ``iothr= eads`` + available for the domain. For real-time schedulers (``fifo``, ``rr``), + priority must be specified as well (and is ignored for non-real-time on= es). + The value range for the priority depends on the host kernel (usually 1-= 99). + :since:`Since 1.2.13` ``emulatorsched`` :since:`since 5.3.0` +``cachetune`` :since:`Since 4.1.0` + Optional ``cachetune`` element can control allocations for CPU caches u= sing + the resctrl on the host. Whether or not is this supported can be gather= ed + from capabilities where some limitations like minimum size and required + granularity are reported as well. The required attribute ``vcpus`` spec= ifies + to which vCPUs this allocation applies. A vCPU can only be member of one + ``cachetune`` element allocation. The vCPUs specified by cachetune can = be + identical with those in memorytune, however they are not allowed to ove= rlap. + Supported subelements are: + + ``cache`` + This optional element controls the allocation of CPU cache and has t= he + following attributes: + + ``level`` + Host cache level from which to allocate. + ``id`` + Host cache id from which to allocate. + ``type`` + Type of allocation. Can be ``code`` for code (instructions), ``da= ta`` + for data or ``both`` for both code and data (unified). Currently = the + allocation can be done only with the same type as the host suppor= ts, + meaning you cannot request ``both`` for host with CDP (code/data + prioritization) enabled. + ``size`` + The size of the region to allocate. The value by default is in by= tes, + but the ``unit`` attribute can be used to scale the value. + ``unit`` (optional) + If specified it is the unit such as KiB, MiB, GiB, or TiB (descri= bed in + the ``memory`` element for `Memory + Allocation <#elementsMemoryAllocation>`__) in which ``size`` is + specified, defaults to bytes. + + ``monitor`` :since:`Since 4.10.0` + The optional element ``monitor`` creates the cache monitor(s) for cu= rrent + cache allocation and has the following required attributes: + + ``level`` + Host cache level the monitor belongs to. + ``vcpus`` + vCPU list the monitor applies to. A monitor's vCPU list can only = be the + member(s) of the vCPU list of the associated allocation. The defa= ult + monitor has the same vCPU list as the associated allocation. For + non-default monitors, overlapping vCPUs are not permitted. + +``memorytune`` :since:`Since 4.7.0` + Optional ``memorytune`` element can control allocations for memory band= width + using the resctrl on the host. Whether or not is this supported can be + gathered from capabilities where some limitations like minimum bandwidt= h and + required granularity are reported as well. The required attribute ``vcp= us`` + specifies to which vCPUs this allocation applies. A vCPU can only be me= mber + of one ``memorytune`` element allocation. The ``vcpus`` specified by + ``memorytune`` can be identical to those specified by ``cachetune``. Ho= wever + they are not allowed to overlap each other. Supported subelements are: + + ``node`` + This element controls the allocation of CPU memory bandwidth and has= the + following attributes: + + ``id`` + Host node id from which to allocate memory bandwidth. + ``bandwidth`` + The memory bandwidth to allocate from this node. The value by def= ault + is in percentage. + +:anchor:`` + +Memory Allocation +----------------- + +:: + + + ... + 1524288 + 524288 + 524288 + ... + + +``memory`` + The maximum allocation of memory for the guest at boot time. The memory + allocation includes possible additional memory devices specified at sta= rt or + hotplugged later. The units for this value are determined by the option= al + attribute ``unit``, which defaults to "KiB" (kibibytes, 2\ :sup:`10` or + blocks of 1024 bytes). Valid units are "b" or "bytes" for bytes, "KB" f= or + kilobytes (10:sup:`3` or 1,000 bytes), "k" or "KiB" for kibibytes (1024 + bytes), "MB" for megabytes (10:sup:`6` or 1,000,000 bytes), "M" or "MiB= " for + mebibytes (2:sup:`20` or 1,048,576 bytes), "GB" for gigabytes (10:sup:`= 9` or + 1,000,000,000 bytes), "G" or "GiB" for gibibytes (2:sup:`30` or 1,073,7= 41,824 + bytes), "TB" for terabytes (10:sup:`12` or 1,000,000,000,000 bytes), or= "T" + or "TiB" for tebibytes (2:sup:`40` or 1,099,511,627,776 bytes). However= , the + value will be rounded up to the nearest kibibyte by libvirt, and may be + further rounded to the granularity supported by the hypervisor. Some + hypervisors also enforce a minimum, such as 4000KiB. In case + `NUMA <#elementsCPU>`__ is configured for the guest the ``memory`` elem= ent + can be omitted. In the case of crash, optional attribute ``dumpCore`` c= an be + used to control whether the guest memory should be included in the gene= rated + coredump or not (values "on", "off"). :since:```unit`` since 0.9.11` , + :since:```dumpCore`` since 0.10.2 (QEMU only)` +``maxMemory`` + The run time maximum memory allocation of the guest. The initial memory + specified by either the ```` element or the NUMA cell size + configuration can be increased by hot-plugging of memory to the limit + specified by this element. The ``unit`` attribute behaves the same as f= or + ````. The ``slots`` attribute specifies the number of slots ava= ilable + for adding memory to the guest. The bounds are hypervisor specific. Not= e that + due to alignment of the memory chunks added via memory hotplug the full= size + allocation specified by this element may be impossible to achieve. + :since:`Since 1.2.14 supported by the QEMU driver.` +``currentMemory`` + The actual allocation of memory for the guest. This value can be less t= han + the maximum allocation, to allow for ballooning up the guests memory on= the + fly. If this is omitted, it defaults to the same value as the ``memory`` + element. The ``unit`` attribute behaves the same as for ``memory``. + +:anchor:`` + +Memory Backing +-------------- + +:: + + + ... + + + + + + + + + + + + + ... + + +The optional ``memoryBacking`` element may contain several elements that +influence how virtual memory pages are backed by host pages. + +``hugepages`` + This tells the hypervisor that the guest should have its memory allocat= ed + using hugepages instead of the normal native page size. :since:`Since 1= .2.5` + it's possible to set hugepages more specifically per numa node. The ``p= age`` + element is introduced. It has one compulsory attribute ``size`` which + specifies which hugepages should be used (especially useful on systems + supporting hugepages of different sizes). The default unit for the ``si= ze`` + attribute is kilobytes (multiplier of 1024). If you want to use differe= nt + unit, use optional ``unit`` attribute. For systems with NUMA, the optio= nal + ``nodeset`` attribute may come handy as it ties given guest's NUMA node= s to + certain hugepage sizes. From the example snippet, one gigabyte hugepage= s are + used for every NUMA node except node number four. For the correct synta= x see + `this <#elementsNUMATuning>`__. +``nosharepages`` + Instructs hypervisor to disable shared pages (memory merge, KSM) for th= is + domain. :since:`Since 1.0.6` +``locked`` + When set and supported by the hypervisor, memory pages belonging to the + domain will be locked in host's memory and the host will not be allowed= to + swap them out, which might be required for some workloads such as real-= time. + For QEMU/KVM guests, the memory used by the QEMU process itself will be + locked too: unlike guest memory, this is an amount libvirt has no way of + figuring out in advance, so it has to remove the limit on locked memory + altogether. Thus, enabling this option opens up to a potential security= risk: + the host will be unable to reclaim the locked memory back from the gues= t when + it's running out of memory, which means a malicious guest allocating la= rge + amounts of locked memory could cause a denial-of-service attack on the = host. + Because of this, using this option is discouraged unless your workload + demands it; even then, it's highly recommended to set a ``hard_limit`` = (see + `memory tuning <#elementsMemoryTuning>`__) on memory allocation suitabl= e for + the specific environment at the same time to mitigate the risks describ= ed + above. :since:`Since 1.0.6` +``source`` + Using the ``type`` attribute, it's possible to provide "file" to utiliz= e file + memorybacking or keep the default "anonymous". :since:`Since 4.10.0` , = you + may choose "memfd" backing. (QEMU/KVM only) +``access`` + Using the ``mode`` attribute, specify if the memory is to be "shared" or + "private". This can be overridden per numa node by ``memAccess``. +``allocation`` + Using the ``mode`` attribute, specify when to allocate the memory by + supplying either "immediate" or "ondemand". +``discard`` + When set and supported by hypervisor the memory content is discarded ju= st + before guest shuts down (or when DIMM module is unplugged). Please note= that + this is just an optimization and is not guaranteed to work in all cases= (e.g. + when hypervisor crashes). :since:`Since 4.4.0` (QEMU/KVM only) + +:anchor:`` + +Memory Tuning +------------- + +:: + + + ... + + 1 + 128 + 2 + 67108864 + + ... + + +``memtune`` + The optional ``memtune`` element provides details regarding the memory + tunable parameters for the domain. If this is omitted, it defaults to t= he OS + provided defaults. For QEMU/KVM, the parameters are applied to the QEMU + process as a whole. Thus, when counting them, one needs to add up guest= RAM, + guest video RAM, and some memory overhead of QEMU itself. The last piec= e is + hard to determine so one needs guess and try. For each tunable, it is + possible to designate which unit the number is in on input, using the s= ame + values as for ````. For backwards compatibility, output is alwa= ys in + KiB. :since:```unit`` since 0.9.11` Possible values for all \*_limit + parameters are in range from 0 to VIR_DOMAIN_MEMORY_PARAM_UNLIMITED. +``hard_limit`` + The optional ``hard_limit`` element is the maximum memory the guest can= use. + The units for this value are kibibytes (i.e. blocks of 1024 bytes). Use= rs of + QEMU and KVM are strongly advised not to set this limit as domain may g= et + killed by the kernel if the guess is too low, and determining the memory + needed for a process to run is an `undecidable + problem `__; that sai= d, if + you already set ``locked`` in `memory backing <#elementsMemoryBacking>`= __ + because your workload demands it, you'll have to take into account the + specifics of your deployment and figure out a value for ``hard_limit`` = that + is large enough to support the memory requirements of your guest, but s= mall + enough to protect your host against a malicious guest locking all memor= y. +``soft_limit`` + The optional ``soft_limit`` element is the memory limit to enforce duri= ng + memory contention. The units for this value are kibibytes (i.e. blocks = of + 1024 bytes) +``swap_hard_limit`` + The optional ``swap_hard_limit`` element is the maximum memory plus swa= p the + guest can use. The units for this value are kibibytes (i.e. blocks of 1= 024 + bytes). This has to be more than hard_limit value provided +``min_guarantee`` + The optional ``min_guarantee`` element is the guaranteed minimum memory + allocation for the guest. The units for this value are kibibytes (i.e. = blocks + of 1024 bytes). This element is only supported by VMware ESX and OpenVZ + drivers. + +:anchor:`` + +NUMA Node Tuning +---------------- + +:: + + + ... + + + + + + ... + + +``numatune`` + The optional ``numatune`` element provides details of how to tune the + performance of a NUMA host via controlling NUMA policy for domain proce= ss. + NB, only supported by QEMU driver. :since:`Since 0.9.3` +``memory`` + The optional ``memory`` element specifies how to allocate memory for the + domain process on a NUMA host. It contains several optional attributes. + Attribute ``mode`` is either 'interleave', 'strict', or 'preferred', de= faults + to 'strict'. Attribute ``nodeset`` specifies the NUMA nodes, using the = same + syntax as attribute ``cpuset`` of element ``vcpu``. Attribute ``placeme= nt`` ( + :since:`since 0.9.12` ) can be used to indicate the memory placement mo= de for + domain process, its value can be either "static" or "auto", defaults to + ``placement`` of ``vcpu``, or "static" if ``nodeset`` is specified. "au= to" + indicates the domain process will only allocate memory from the advisory + nodeset returned from querying numad, and the value of attribute ``node= set`` + will be ignored if it's specified. If ``placement`` of ``vcpu`` is 'aut= o', + and ``numatune`` is not specified, a default ``numatune`` with ``placem= ent`` + 'auto' and ``mode`` 'strict' will be added implicitly. :since:`Since 0.= 9.3` +``memnode`` + Optional ``memnode`` elements can specify memory allocation policies pe= r each + guest NUMA node. For those nodes having no corresponding ``memnode`` el= ement, + the default from element ``memory`` will be used. Attribute ``cellid`` + addresses guest NUMA node for which the settings are applied. Attributes + ``mode`` and ``nodeset`` have the same meaning and syntax as in ``memor= y`` + element. This setting is not compatible with automatic placement. + :since:`QEMU Since 1.2.7` + +:anchor:`` + +Block I/O Tuning +---------------- + +:: + + + ... + + 800 + + /dev/sda + 1000 + + + /dev/sdb + 500 + 10000 + 10000 + 20000 + 20000 + + + ... + + +``blkiotune`` + The optional ``blkiotune`` element provides the ability to tune Blkio c= group + tunable parameters for the domain. If this is omitted, it defaults to t= he OS + provided defaults. :since:`Since 0.8.8` +``weight`` + The optional ``weight`` element is the overall I/O weight of the guest.= The + value should be in the range [100, 1000]. After kernel 2.6.39, the value + could be in the range [10, 1000]. +``device`` + The domain may have multiple ``device`` elements that further tune the + weights for each host block device in use by the domain. Note that mult= iple + `guest disks <#elementsDisks>`__ can share a single host block device, = if + they are backed by files within the same host file system, which is why= this + tuning parameter is at the global domain level rather than associated w= ith + each guest disk device (contrast this to the ` <#elementsDisks>= `__ + element which can apply to an individual ````). Each ``device`` e= lement + has two mandatory sub-elements, ``path`` describing the absolute path o= f the + device, and ``weight`` giving the relative weight of that device, in the + range [100, 1000]. After kernel 2.6.39, the value could be in the range= [10, + 1000]. :since:`Since 0.9.8` + Additionally, the following optional sub-elements can be used: + + ``read_bytes_sec`` + Read throughput limit in bytes per second. :since:`Since 1.2.2` + ``write_bytes_sec`` + Write throughput limit in bytes per second. :since:`Since 1.2.2` + ``read_iops_sec`` + Read I/O operations per second limit. :since:`Since 1.2.2` + ``write_iops_sec`` + Write I/O operations per second limit. :since:`Since 1.2.2` + +:anchor:`` + +Resource partitioning +--------------------- + +Hypervisors may allow for virtual machines to be placed into resource +partitions, potentially with nesting of said partitions. The ``resource`` +element groups together configuration related to resource partitioning. It +currently supports a child element ``partition`` whose content defines the +absolute path of the resource partition in which to place the domain. If no +partition is listed, then the domain will be placed in a default partition= . It +is the responsibility of the app/admin to ensure that the partition exists= prior +to starting the guest. Only the (hypervisor specific) default partition ca= n be +assumed to exist by default. + +:: + + ... + + /virtualmachines/production + + ... + +Resource partitions are currently supported by the QEMU and LXC drivers, w= hich +map partition paths to cgroups directories, in all mounted controllers. +:since:`Since 1.0.5` + +:anchor:`` + +CPU model and topology +---------------------- + +Requirements for CPU model, its features and topology can be specified usi= ng the +following collection of elements. :since:`Since 0.7.5` + +:: + + ... + + core2duo + Intel + + + + + ... + +:: + + + + + + ... + +:: + + + + + ... + +In case no restrictions need to be put on CPU model and its features, a si= mpler +``cpu`` element can be used. :since:`Since 0.7.6` + +:: + + ... + + + + ... + +``cpu`` + The ``cpu`` element is the main container for describing guest CPU + requirements. Its ``match`` attribute specifies how strictly the virtua= l CPU + provided to the guest matches these requirements. :since:`Since 0.7.6` = the + ``match`` attribute can be omitted if ``topology`` is the only element = within + ``cpu``. Possible values for the ``match`` attribute are: + + ``minimum`` + The specified CPU model and features describes the minimum requested= CPU. + A better CPU will be provided to the guest if it is possible with the + requested hypervisor on the current host. This is a constrained + ``host-model`` mode; the domain will not be created if the provided + virtual CPU does not meet the requirements. + ``exact`` + The virtual CPU provided to the guest should exactly match the + specification. If such CPU is not supported, libvirt will refuse to = start + the domain. + ``strict`` + The domain will not be created unless the host CPU exactly matches t= he + specification. This is not very useful in practice and should only b= e used + if there is a real reason. + + :since:`Since 0.8.5` the ``match`` attribute can be omitted and will de= fault + to ``exact``. Sometimes the hypervisor is not able to create a virtual = CPU + exactly matching the specification passed by libvirt. :since:`Since 3.2= .0` , + an optional ``check`` attribute can be used to request a specific way of + checking whether the virtual CPU matches the specification. It is usual= ly + safe to omit this attribute when starting a domain and stick with the d= efault + value. Once the domain starts, libvirt will automatically change the + ``check`` attribute to the best supported value to ensure the virtual C= PU + does not change when the domain is migrated to another host. The follow= ing + values can be used: + + ``none`` + Libvirt does no checking and it is up to the hypervisor to refuse to= start + the domain if it cannot provide the requested CPU. With QEMU this me= ans no + checking is done at all since the default behavior of QEMU is to emit + warnings, but start the domain anyway. + ``partial`` + Libvirt will check the guest CPU specification before starting a dom= ain, + but the rest is left on the hypervisor. It can still provide a diffe= rent + virtual CPU. + ``full`` + The virtual CPU created by the hypervisor will be checked against th= e CPU + specification and the domain will not be started unless the two CPUs + match. + + :since:`Since 0.9.10` , an optional ``mode`` attribute may be used to m= ake it + easier to configure a guest CPU to be as close to host CPU as possible. + Possible values for the ``mode`` attribute are: + + ``custom`` + In this mode, the ``cpu`` element describes the CPU that should be + presented to the guest. This is the default when no ``mode`` attribu= te is + specified. This mode makes it so that a persistent guest will see th= e same + hardware no matter what host the guest is booted on. + ``host-model`` + The ``host-model`` mode is essentially a shortcut to copying host CPU + definition from capabilities XML into domain XML. Since the CPU defi= nition + is copied just before starting a domain, exactly the same XML can be= used + on different hosts while still providing the best guest CPU each host + supports. The ``match`` attribute can't be used in this mode. Specif= ying + CPU model is not supported either, but ``model``'s ``fallback`` attr= ibute + may still be used. Using the ``feature`` element, specific flags may= be + enabled or disabled specifically in addition to the host model. This= may + be used to fine tune features that can be emulated. :since:`(Since 1= .1.1)` + . Libvirt does not model every aspect of each CPU so the guest CPU w= ill + not match the host CPU exactly. On the other hand, the ABI provided = to the + guest is reproducible. During migration, complete CPU model definiti= on is + transferred to the destination host so the migrated guest will see e= xactly + the same CPU model for the running instance of the guest, even if the + destination host contains more capable CPUs or newer kernel; but shu= tting + down and restarting the guest may present different hardware to the = guest + according to the capabilities of the new host. Prior to libvirt 3.2.= 0 and + QEMU 2.9.0 detection of the host CPU model via QEMU is not supported= . Thus + the CPU configuration created using ``host-model`` may not work as + expected. :since:`Since 3.2.0 and QEMU 2.9.0` this mode works the wa= y it + was designed and it is indicated by the ``fallback`` attribute set to + ``forbid`` in the host-model CPU definition advertised in `domain + capabilities XML `__. When ``fall= back`` + attribute is set to ``allow`` in the domain capabilities XML, it is + recommended to use ``custom`` mode with just the CPU model from the = host + capabilities XML. :since:`Since 1.2.11` PowerISA allows processors t= o run + VMs in binary compatibility mode supporting an older version of ISA. + Libvirt on PowerPC architecture uses the ``host-model`` to signify a= guest + mode CPU running in binary compatibility mode. Example: When a user = needs + a power7 VM to run in compatibility mode on a Power8 host, this can = be + described in XML as follows : + + :: + + + power7 + + ... + + ``host-passthrough`` + With this mode, the CPU visible to the guest should be exactly the s= ame as + the host CPU even in the aspects that libvirt does not understand. T= hough + the downside of this mode is that the guest environment cannot be + reproduced on different hardware. Thus, if you hit any bugs, you are= on + your own. Further details of that CPU can be changed using ``feature= `` + elements. Migration of a guest using host-passthrough is dangerous i= f the + source and destination hosts are not identical in both hardware, QEMU + version, microcode version and configuration. If such a migration is + attempted then the guest may hang or crash upon resuming execution o= n the + destination host. Depending on hypervisor version the virtual CPU ma= y or + may not contain features which may block migration even to an identi= cal + host. :since:`Since 6.5.0` optional ``migratable`` attribute may be = used + to explicitly request such features to be removed from (``on``) or k= ept in + (``off``) the virtual CPU. This attribute does not make migration to + another host safer: even with ``migratable=3D'on'`` migration will be + dangerous unless both hosts are identical as described above. + + Both ``host-model`` and ``host-passthrough`` modes make sense when a do= main + can run directly on the host CPUs (for example, domains with type ``kvm= ``). + The actual host CPU is irrelevant for domains with emulated virtual CPUs + (such as domains with type ``qemu``). However, for backward compatibili= ty + ``host-model`` may be implemented even for domains running on emulated = CPUs + in which case the best CPU the hypervisor is able to emulate may be used + rather then trying to mimic the host CPU model. +``model`` + The content of the ``model`` element specifies CPU model requested by t= he + guest. The list of available CPU models and their definition can be fou= nd in + ``cpu_map.xml`` file installed in libvirt's data directory. If a hyperv= isor + is not able to use the exact CPU model, libvirt automatically falls bac= k to a + closest model supported by the hypervisor while maintaining the list of= CPU + features. :since:`Since 0.9.10` , an optional ``fallback`` attribute ca= n be + used to forbid this behavior, in which case an attempt to start a domain + requesting an unsupported CPU model will fail. Supported values for + ``fallback`` attribute are: ``allow`` (this is the default), and ``forb= id``. + The optional ``vendor_id`` attribute ( :since:`Since 0.10.0` ) can be u= sed to + set the vendor id seen by the guest. It must be exactly 12 characters l= ong. + If not set the vendor id of the host is used. Typical possible values a= re + "AuthenticAMD" and "GenuineIntel". +``vendor`` + :since:`Since 0.8.3` the content of the ``vendor`` element specifies CPU + vendor requested by the guest. If this element is missing, the guest ca= n be + run on a CPU matching given features regardless on its vendor. The list= of + supported vendors can be found in ``cpu_map.xml``. +``topology`` + The ``topology`` element specifies requested topology of virtual CPU pr= ovided + to the guest. Four attributes, ``sockets``, ``dies``, ``cores``, and + ``threads``, accept non-zero positive integer values. They refer to the + number of CPU sockets per NUMA node, number of dies per socket, number = of + cores per die, and number of threads per core, respectively. The ``dies= `` + attribute is optional and will default to 1 if omitted, while the other + attributes are all mandatory. Hypervisors may require that the maximum = number + of vCPUs specified by the ``cpus`` element equals to the number of vcpus + resulting from the topology. +``feature`` + The ``cpu`` element can contain zero or more ``elements`` used to fine-= tune + features provided by the selected CPU model. The list of known feature = names + can be found in the same file as CPU models. The meaning of each ``feat= ure`` + element depends on its ``policy`` attribute, which has to be set to one= of + the following values: + + ``force`` + The virtual CPU will claim the feature is supported regardless of it= being + supported by host CPU. + ``require`` + Guest creation will fail unless the feature is supported by the host= CPU + or the hypervisor is able to emulate it. + ``optional`` + The feature will be supported by virtual CPU if and only if it is + supported by host CPU. + ``disable`` + The feature will not be supported by virtual CPU. + ``forbid`` + Guest creation will fail if the feature is supported by host CPU. + + :since:`Since 0.8.5` the ``policy`` attribute can be omitted and will d= efault + to ``require``. + + Individual CPU feature names are specified as part of the ``name`` attr= ibute. + For example, to explicitly specify the 'pcid' feature with Intel IvyBri= dge + CPU model: + + :: + + ... + + IvyBridge + Intel + + + ... + +``cache`` + :since:`Since 3.3.0` the ``cache`` element describes the virtual CPU ca= che. + If the element is missing, the hypervisor will use a sensible default. + + ``level`` + This optional attribute specifies which cache level is described by = the + element. Missing attribute means the element describes all CPU cache + levels at once. Mixing ``cache`` elements with the ``level`` attribu= te set + and those without the attribute is forbidden. + ``mode`` + The following values are supported: + + ``emulate`` + The hypervisor will provide a fake CPU cache data. + ``passthrough`` + The real CPU cache data reported by the host CPU will be passed t= hrough + to the virtual CPU. + ``disable`` + The virtual CPU will report no CPU cache of the specified level (= or no + cache at all if the ``level`` attribute is missing). + +Guest NUMA topology can be specified using the ``numa`` element. :since:`S= ince +0.9.8` + +:: + + ... + + ... + + + + + ... + + ... + +Each ``cell`` element specifies a NUMA cell or a NUMA node. ``cpus`` speci= fies +the CPU or range of CPUs that are part of the node. :since:`Since 6.5.0` F= or the +qemu driver, if the emulator binary supports disjointed ``cpus`` ranges in= each +``cell``, the sum of all CPUs declared in each ``cell`` will be matched wi= th the +maximum number of virtual CPUs declared in the ``vcpu`` element. This is d= one by +filling any remaining CPUs into the first NUMA ``cell``. Users are encoura= ged to +supply a complete NUMA topology, where the sum of the NUMA CPUs matches the +maximum virtual CPUs number declared in ``vcpus``, to make the domain cons= istent +across qemu and libvirt versions. ``memory`` specifies the node memory in +kibibytes (i.e. blocks of 1024 bytes). :since:`Since 6.6.0` the ``cpus`` +attribute is optional and if omitted a CPU-less NUMA node is created. +:since:`Since 1.2.11` one can use an additional +`unit <#elementsMemoryAllocation>`__ attribute to define units in which +``memory`` is specified. :since:`Since 1.2.7` all cells should have ``id`` +attribute in case referring to some cell is necessary in the code, otherwi= se the +cells are assigned ``id``\ s in the increasing order starting from 0. Mixi= ng +cells with and without the ``id`` attribute is not recommended as it may r= esult +in unwanted behaviour. :since:`Since 1.2.9` the optional attribute ``memAc= cess`` +can control whether the memory is to be mapped as "shared" or "private". T= his is +valid only for hugepages-backed memory and nvdimm modules. Each ``cell`` e= lement +can have an optional ``discard`` attribute which fine tunes the discard fe= ature +for given numa node as described under `Memory +Backing <#elementsMemoryBacking>`__. Accepted values are ``yes`` and ``no`= `. +:since:`Since 4.4.0` + +This guest NUMA specification is currently available only for QEMU/KVM and= Xen. + +A NUMA hardware architecture supports the notion of distances between NUMA +cells. :since:`Since 3.10.0` it is possible to define the distance between= NUMA +cells using the ``distances`` element within a NUMA ``cell`` description. = The +``sibling`` sub-element is used to specify the distance value between sibl= ing +NUMA cells. For more details, see the chapter explaining the system's SLIT +(System Locality Information Table) within the ACPI (Advanced Configuratio= n and +Power Interface) specification. + +:: + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + ... + +Describing distances between NUMA cells is currently only supported by Xen= and +QEMU. If no ``distances`` are given to describe the SLIT data between diff= erent +cells, it will default to a scheme using 10 for local and 20 for remote +distances. + +:anchor:`` + +ACPI Heterogeneous Memory Attribute Table +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + ... + + ... + + + + + + + + + + + + + + + + ... + + ... + +:since:`Since 6.6.0` the ``cell`` element can have a ``cache`` child eleme= nt +which describes memory side cache for memory proximity domains. The ``cach= e`` +element has a ``level`` attribute describing the cache level and thus the +element can be repeated multiple times to describe different levels of the +cache. + +The ``cache`` element then has following mandatory attributes: + +``level`` + Level of the cache this description refers to. +``associativity`` + Describes cache associativity (accepted values are ``none``, ``direct``= and + ``full``). +``policy`` + Describes cache write associativity (accepted values are ``none``, + ``writeback`` and ``writethrough``). + +The ``cache`` element has two mandatory child elements then: ``size`` and +``line`` which describe cache size and cache line size. Both elements acce= pt two +attributes: ``value`` and ``unit`` which set the value of corresponding ca= che +attribute. + +The NUMA description has an optional ``interconnects`` element that descri= bes +the normalized memory read/write latency, read/write bandwidth between Ini= tiator +Proximity Domains (Processor or I/O) and Target Proximity Domains (Memory). + +The ``interconnects`` element can have zero or more ``latency`` child elem= ents +to describe latency between two memory nodes and zero or more ``bandwidth`` +child elements to describe bandwidth between two memory nodes. Both these = have +the following mandatory attributes: + +``initiator`` + Refers to the source NUMA node +``target`` + Refers to the target NUMA node +``type`` + The type of the access. Accepted values: ``access``, ``read``, ``write`` +``value`` + The actual value. For latency this is delay in nanoseconds, for bandwid= th + this value is in kibibytes per second. Use additional ``unit`` attribut= e to + change the units. + +To describe latency from one NUMA node to a cache of another NUMA node the +``latency`` element has optional ``cache`` attribute which in combination = with +``target`` attribute creates full reference to distant NUMA node's cache l= evel. +For instance, ``target=3D'0' cache=3D'1'`` refers to the first level cache= of NUMA +node 0. + +:anchor:`` + +Events configuration +-------------------- + +It is sometimes necessary to override the default actions taken on various +events. Not all hypervisors support all events and actions. The actions ma= y be +taken as a result of calls to libvirt APIs +`virDomainReboot `__ , +`virDomainShutdown `__= , or +`virDomainShutdownFlags `__ +. Using ``virsh reboot`` or ``virsh shutdown`` would also trigger the even= t. + +:: + + ... + destroy + restart + restart + poweroff + ... + +The following collections of elements allow the actions to be specified wh= en a +guest OS triggers a lifecycle operation. A common use case is to force a r= eboot +to be treated as a poweroff when doing the initial OS installation. This a= llows +the VM to be re-configured for the first post-install bootup. + +``on_poweroff`` + The content of this element specifies the action to take when the guest + requests a poweroff. +``on_reboot`` + The content of this element specifies the action to take when the guest + requests a reboot. +``on_crash`` + The content of this element specifies the action to take when the guest + crashes. + +Each of these states allow for the same four possible actions. + +``destroy`` + The domain will be terminated completely and all resources released. +``restart`` + The domain will be terminated and then restarted with the same configur= ation. +``preserve`` + The domain will be terminated and its resource preserved to allow analy= sis. +``rename-restart`` + The domain will be terminated and then restarted with a new name. + +QEMU/KVM supports the ``on_poweroff`` and ``on_reboot`` events handling the +``destroy`` and ``restart`` actions. The ``preserve`` action for an +``on_reboot`` event is treated as a ``destroy`` and the ``rename-restart`` +action for an ``on_poweroff`` event is treated as a ``restart`` event. + +The ``on_crash`` event supports these additional actions :since:`since 0.8= .4` . + +``coredump-destroy`` + The crashed domain's core will be dumped, and then the domain will be + terminated completely and all resources released +``coredump-restart`` + The crashed domain's core will be dumped, and then the domain will be + restarted with the same configuration + +:since:`Since 3.9.0` , the lifecycle events can be configured via the +`virDomainSetLifecycleAction `__ +API. + +The ``on_lockfailure`` element ( :since:`since 1.0.0` ) may be used to con= figure +what action should be taken when a lock manager loses resource locks. The +following actions are recognized by libvirt, although not all of them need= to be +supported by individual lock managers. When no action is specified, each l= ock +manager will take its default action. + +``poweroff`` + The domain will be forcefully powered off. +``restart`` + The domain will be powered off and started up again to reacquire its lo= cks. +``pause`` + The domain will be paused so that it can be manually resumed when lock = issues + are solved. +``ignore`` + Keep the domain running as if nothing happened. + +:anchor:`` + +Power Management +---------------- + +:since:`Since 0.10.2` it is possible to forcibly enable or disable BIOS +advertisements to the guest OS. (NB: Only qemu driver support) + +:: + + ... + + + + + ... + +``pm`` + These elements enable ('yes') or disable ('no') BIOS support for S3 + (suspend-to-mem) and S4 (suspend-to-disk) ACPI sleep states. If nothing= is + specified, then the hypervisor will be left with its default value. + Note: This setting cannot prevent the guest OS from performing a suspen= d as + the guest OS itself can choose to circumvent the unavailability of the = sleep + states (e.g. S4 by turning off completely). + +:anchor:`` + +Hypervisor features +------------------- + +Hypervisors may allow certain CPU / machine features to be toggled on/off. + +:: + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 16 + + + + 48 + + + + + + + + + ... + +All features are listed within the ``features`` element, omitting a toggla= ble +feature tag turns it off. The available features can be found by asking fo= r the +`capabilities XML `__ and `domain capabilities +XML `__, but a common set for fully virtualized dom= ains +are: + +``pae`` + Physical address extension mode allows 32-bit guests to address more th= an 4 + GB of memory. +``acpi`` + ACPI is useful for power management, for example, with KVM guests it is + required for graceful shutdown to work. +``apic`` + APIC allows the use of programmable IRQ management. :since:`Since 0.10.2 + (QEMU only)` there is an optional attribute ``eoi`` with values ``on`` = and + ``off`` which toggles the availability of EOI (End of Interrupt) for the + guest. +``hap`` + Depending on the ``state`` attribute (values ``on``, ``off``) enable or + disable use of Hardware Assisted Paging. The default is ``on`` if the + hypervisor detects availability of Hardware Assisted Paging. +``viridian`` + Enable Viridian hypervisor extensions for paravirtualizing guest operat= ing + systems +``privnet`` + Always create a private network namespace. This is automatically set if= any + interface devices are defined. This feature is only relevant for contai= ner + based virtualization drivers, such as LXC. +``hyperv`` + Enable various features improving behavior of guests running Microsoft + Windows. + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + Feature Description = Value Since + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + relaxed Relax constraints on timers = on, off :since:`1.0.0 = (QEMU 2.0)` + vapic Enable virtual APIC = on, off :since:`1.1.0 = (QEMU 2.0)` + spinlocks Enable spinlock support = on, off; retries - at least 4095 :since:`1.1.0 = (QEMU 2.0)` + vpindex Virtual processor index = on, off :since:`1.3.3 = (QEMU 2.5)` + runtime Processor time spent on running guest code and on behal= f of guest code on, off :since:`1.3.3 = (QEMU 2.5)` + synic Enable Synthetic Interrupt Controller (SynIC) = on, off :since:`1.3.3 = (QEMU 2.6)` + stimer Enable SynIC timers, optionally with Direct Mode suppor= t on, off; direct - on,off :since:`1.3.3 = (QEMU 2.6), direct mode 5.7.0 (QEMU 4.1)` + reset Enable hypervisor reset = on, off :since:`1.3.3 = (QEMU 2.5)` + vendor_id Set hypervisor vendor id = on, off; value - string, up to 12 characters :since:`1.3.3 = (QEMU 2.5)` + frequencies Expose frequency MSRs = on, off :since:`4.7.0 = (QEMU 2.12)` + reenlightenment Enable re-enlightenment notification on migration = on, off :since:`4.7.0 = (QEMU 3.0)` + tlbflush Enable PV TLB flush support = on, off :since:`4.7.0 = (QEMU 3.0)` + ipi Enable PV IPI support = on, off :since:`4.10.0= (QEMU 3.1)` + evmcs Enable Enlightened VMCS = on, off :since:`4.10.0= (QEMU 3.1)` + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``pvspinlock`` + Notify the guest that the host supports paravirtual spinlocks for examp= le by + exposing the pvticketlocks mechanism. This feature can be explicitly di= sabled + by using ``state=3D'off'`` attribute. +``kvm`` + Various features to change the behavior of the KVM hypervisor. + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + Feature Description = Value Since + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + hidden Hide the KVM hypervisor from standard MSR based discover= y on, off :since:`1.2.8 (QEMU 2.1.0)` + hint-dedicated Allows a guest to enable optimizations when running on d= edicated vCPUs on, off :since:`5.7.0 (QEMU 2.12.0)` + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``xen`` + Various features to change the behavior of the Xen hypervisor. + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + Feature Description Value = Since + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + e820_host Expose the host e820 to the guest (PV only) on, off = :since:`6.3.0` + passthrough Enable IOMMU mappings allowing PCI passthrough on, off; mod= e - optional string sync_pt or share_pt :since:`6.3.0` + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +``pmu`` + Depending on the ``state`` attribute (values ``on``, ``off``, default `= `on``) + enable or disable the performance monitoring unit for the guest. + :since:`Since 1.2.12` +``vmport`` + Depending on the ``state`` attribute (values ``on``, ``off``, default `= `on``) + enable or disable the emulation of VMware IO port, for vmmouse etc. + :since:`Since 1.2.16` +``gic`` + Enable for architectures using a General Interrupt Controller instead o= f APIC + in order to handle interrupts. For example, the 'aarch64' architecture = uses + ``gic`` instead of ``apic``. The optional attribute ``version`` specifi= es the + GIC version; however, it may not be supported by all hypervisors. Accep= ted + values are ``2``, ``3`` and ``host``. :since:`Since 1.2.16` +``smm`` + Depending on the ``state`` attribute (values ``on``, ``off``, default `= `on``) + enable or disable System Management Mode. :since:`Since 2.1.0` + + Optional sub-element ``tseg`` can be used to specify the amount of memo= ry + dedicated to SMM's extended TSEG. That offers a fourth option size apar= t from + the existing ones (1 MiB, 2 MiB and 8 MiB) that the guest OS (or rather + loader) can choose from. The size can be specified as a value of that + element, optional attribute ``unit`` can be used to specify the unit of= the + aforementioned value (defaults to 'MiB'). If set to 0 the extended size= is + not advertised and only the default ones (see above) are available. + + **If the VM is booting you should leave this option alone, unless you a= re + very certain you know what you are doing.** + + This value is configurable due to the fact that the calculation cannot = be + done right with the guarantee that it will work correctly. In QEMU, the + user-configurable extended TSEG feature was unavailable up to and inclu= ding + ``pc-q35-2.9``. Starting with ``pc-q35-2.10`` the feature is available,= with + default size 16 MiB. That should suffice for up to roughly 272 vCPUs, 5= GiB + guest RAM in total, no hotplug memory range, and 32 GiB of 64-bit PCI M= MIO + aperture. Or for 48 vCPUs, with 1TB of guest RAM, no hotplug DIMM range= , and + 32GB of 64-bit PCI MMIO aperture. The values may also vary based on the + loader the VM is using. + + Additional size might be needed for significantly higher vCPU counts or + increased address space (that can be memory, maxMemory, 64-bit PCI MMIO + aperture size; roughly 8 MiB of TSEG per 1 TiB of address space) which = can + also be rounded up. + + Due to the nature of this setting being similar to "how much RAM should= the + guest have" users are advised to either consult the documentation of the + guest OS or loader (if there is any), or test this by trial-and-error + changing the value until the VM boots successfully. Yet another guiding= value + for users might be the fact that 48 MiB should be enough for pretty lar= ge + guests (240 vCPUs and 4TB guest RAM), but it is on purpose not set as d= efault + as 48 MiB of unavailable RAM might be too much for small guests (e.g. w= ith + 512 MiB of RAM). + + See `Memory Allocation <#elementsMemoryAllocation>`__ for more details = about + the ``unit`` attribute. :since:`Since 4.5.0` (QEMU only) + +``ioapic`` + Tune the I/O APIC. Possible values for the ``driver`` attribute are: ``= kvm`` + (default for KVM domains) and ``qemu`` which puts I/O APIC in userspace= which + is also known as a split I/O APIC mode. :since:`Since 3.4.0` (QEMU/KVM = only) +``hpt`` + Configure the HPT (Hash Page Table) of a pSeries guest. Possible values= for + the ``resizing`` attribute are ``enabled``, which causes HPT resizing t= o be + enabled if both the guest and the host support it; ``disabled``, which = causes + HPT resizing to be disabled regardless of guest and host support; and + ``required``, which prevents the guest from starting unless both the gu= est + and the host support HPT resizing. If the attribute is not defined, the + hypervisor default will be used. :since:`Since 3.10.0` (QEMU/KVM only). + + The optional ``maxpagesize`` subelement can be used to limit the usable= page + size for HPT guests. Common values are 64 KiB, 16 MiB and 16 GiB; when = not + specified, the hypervisor default will be used. :since:`Since 4.5.0` + (QEMU/KVM only). + +``vmcoreinfo`` + Enable QEMU vmcoreinfo device to let the guest kernel save debug detail= s. + :since:`Since 4.4.0` (QEMU only) +``htm`` + Configure HTM (Hardware Transational Memory) availability for pSeries g= uests. + Possible values for the ``state`` attribute are ``on`` and ``off``. If = the + attribute is not defined, the hypervisor default will be used. :since:`= Since + 4.6.0` (QEMU/KVM only) +``nested-hv`` + Configure nested HV availability for pSeries guests. This needs to be e= nabled + from the host (L0) in order to be effective; having HV support in the (= L1) + guest is very desiderable if it's planned to run nested (L2) guests ins= ide + it, because it will result in those nested guests having much better + performance than they would when using KVM PR or TCG. Possible values f= or the + ``state`` attribute are ``on`` and ``off``. If the attribute is not def= ined, + the hypervisor default will be used. :since:`Since 4.10.0` (QEMU/KVM on= ly) +``msrs`` + Some guests might require ignoring unknown Model Specific Registers (MS= Rs) + reads and writes. It's possible to switch this by setting ``unknown`` + attribute of ``msrs`` to ``ignore``. If the attribute is not defined, o= r set + to ``fault``, unknown reads and writes will not be ignored. :since:`Sin= ce + 5.1.0` (bhyve only) +``ccf-assist`` + Configure ccf-assist (Count Cache Flush Assist) availability for pSeries + guests. Possible values for the ``state`` attribute are ``on`` and ``of= f``. + If the attribute is not defined, the hypervisor default will be used. + :since:`Since 5.9.0` (QEMU/KVM only) +``cfpc`` + Configure cfpc (Cache Flush on Privilege Change) availability for pSeri= es + guests. Possible values for the ``value`` attribute are ``broken`` (no + protection), ``workaround`` (software workaround available) and ``fixed= `` + (fixed in hardware). If the attribute is not defined, the hypervisor de= fault + will be used. :since:`Since 6.3.0` (QEMU/KVM only) +``sbbc`` + Configure sbbc (Speculation Barrier Bounds Checking) availability for p= Series + guests. Possible values for the ``value`` attribute are ``broken`` (no + protection), ``workaround`` (software workaround available) and ``fixed= `` + (fixed in hardware). If the attribute is not defined, the hypervisor de= fault + will be used. :since:`Since 6.3.0` (QEMU/KVM only) +``ibs`` + Configure ibs (Indirect Branch Speculation) availability for pSeries gu= ests. + Possible values for the ``value`` attribute are ``broken`` (no protecti= on), + ``workaround`` (count cache flush), ``fixed-ibs`` (fixed by serializing + indirect branches), ``fixed-ccd`` (fixed by disabling the cache count) = and + ``fixed-na (fixed in hardware - no longer applicable)``. If t= he + attribute is not defined, the hypervisor default will be used. :since:`= Since + 6.3.0` (QEMU/KVM only) + +:anchor:`` + +Time keeping +------------ + +The guest clock is typically initialized from the host clock. Most operati= ng +systems expect the hardware clock to be kept in UTC, and this is the defau= lt. +Windows, however, expects it to be in so called 'localtime'. + +:: + + ... + + + + + + + ... + +``clock`` + The ``offset`` attribute takes four possible values, allowing fine grai= ned + control over how the guest clock is synchronized to the host. NB, not a= ll + hypervisors support all modes. + + ``utc`` + The guest clock will always be synchronized to UTC when booted. + :since:`Since 0.9.11` 'utc' mode can be converted to 'variable' mode, + which can be controlled by using the ``adjustment`` attribute. If the + value is 'reset', the conversion is never done (not all hypervisors = can + synchronize to UTC on each boot; use of 'reset' will cause an error = on + those hypervisors). A numeric value forces the conversion to 'variab= le' + mode using the value as the initial adjustment. The default ``adjust= ment`` + is hypervisor specific. + ``localtime`` + The guest clock will be synchronized to the host's configured timezo= ne + when booted, if any. :since:`Since 0.9.11,` the ``adjustment`` attri= bute + behaves the same as in 'utc' mode. + ``timezone`` + The guest clock will be synchronized to the requested timezone using= the + ``timezone`` attribute. :since:`Since 0.7.7` + ``variable`` + The guest clock will have an arbitrary offset applied relative to UT= C or + localtime, depending on the ``basis`` attribute. The delta relative = to UTC + (or localtime) is specified in seconds, using the ``adjustment`` + attribute. The guest is free to adjust the RTC over time and expect = that + it will be honored at next reboot. This is in contrast to 'utc' and + 'localtime' mode (with the optional attribute adjustment=3D'reset'),= where + the RTC adjustments are lost at each reboot. :since:`Since 0.7.7` + :since:`Since 0.9.11` the ``basis`` attribute can be either 'utc' + (default) or 'localtime'. + + A ``clock`` may have zero or more ``timer`` sub-elements. :since:`Since + 0.8.0` + +``timer`` + Each timer element requires a ``name`` attribute, and has other optional + attributes that depend on the ``name`` specified. Various hypervisors s= upport + different combinations of attributes. + + ``name`` + The ``name`` attribute selects which timer is being modified, and ca= n be + one of "platform" (currently unsupported), "hpet" (xen, qemu, lxc), + "kvmclock" (qemu), "pit" (qemu), "rtc" (qemu, lxc), "tsc" (xen, qemu= - + :since:`since 3.2.0` ), "hypervclock" (qemu - :since:`since 1.2.2` )= or + "armvtimer" (qemu - :since:`since 6.1.0` ). The ``hypervclock`` time= r adds + support for the reference time counter and the reference page for iT= SC + feature for guests running the Microsoft Windows operating system. + ``track`` + The ``track`` attribute specifies what the timer tracks, and can be + "boot", "guest", or "wall". Only valid for ``name=3D"rtc"`` or + ``name=3D"platform"``. + ``tickpolicy`` + The ``tickpolicy`` attribute determines what happens when QEMU misse= s a + deadline for injecting a tick to the guest. This can happen, for exa= mple, + because the guest was paused. + + ``delay`` + Continue to deliver ticks at the normal rate. The guest OS will n= ot + notice anything is amiss, as from its point of view time will have + continued to flow normally. The time in the guest should now be b= ehind + the time in the host by exactly the amount of time during which t= icks + have been missed. + ``catchup`` + Deliver ticks at a higher rate to catch up with the missed ticks.= The + guest OS will not notice anything is amiss, as from its point of = view + time will have continued to flow normally. Once the timer has man= aged + to catch up with all the missing ticks, the time in the guest and= in + the host should match. + ``merge`` + Merge the missed tick(s) into one tick and inject. The guest time= may + be delayed, depending on how the OS reacts to the merging of ticks + ``discard`` + Throw away the missed ticks and continue with future injection + normally. The guest OS will see the timer jump ahead by a potenti= ally + quite significant amount all at once, as if the intervening chunk= of + time had simply not existed; needless to say, such a sudden jump = can + easily confuse a guest OS which is not specifically prepared to d= eal + with it. Assuming the guest OS can deal correctly with the time j= ump, + the time in the guest and in the host should now match. + + If the policy is "catchup", there can be further details in the + ``catchup`` sub-element. + + ``catchup`` + The ``catchup`` element has three optional attributes, each a pos= itive + integer. The attributes are ``threshold``, ``slew``, and ``limit`= `. + + Note that hypervisors are not required to support all policies acros= s all + time sources + + ``frequency`` + The ``frequency`` attribute is an unsigned integer specifying the + frequency at which ``name=3D"tsc"`` runs. + ``mode`` + The ``mode`` attribute controls how the ``name=3D"tsc"`` timer is ma= naged, + and can be "auto", "native", "emulate", "paravirt", or "smpsafe". Ot= her + timers are always emulated. + ``present`` + The ``present`` attribute can be "yes" or "no" to specify whether a + particular timer is available to the guest. + +:anchor:`` + +Performance monitoring events +----------------------------- + +Some platforms allow monitoring of performance of the virtual machine and = the +code executed inside. To enable the performance monitoring events you can = either +specify them in the ``perf`` element or enable them via +``virDomainSetPerfEvents`` API. The performance values are then retrieved = using +the virConnectGetAllDomainStats API. :since:`Since 2.0.0` + +:: + + ... + + + + + + + + + + + + + + + + + + + + + + + + + ... + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +event name Description = = stats parame= ter name +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +``cmt`` usage of l3 cache in bytes by applications run= ning on the platform = ``perf.cmt`` +``mbmt`` total system bandwidth from one level of cache= = ``perf.mbmt`` +``mbml`` bandwidth of memory traffic for a memory contr= oller = ``perf.mbml`` +``cpu_cycles`` the count of CPU cycles (total/elapsed) = = ``perf.cpu_c= ycles`` +``instructions`` the count of instructions by applications runn= ing on the platform = ``perf.instr= uctions`` +``cache_references`` the count of cache hits by applications runnin= g on the platform = ``perf.cache= _references`` +``cache_misses`` the count of cache misses by applications runn= ing on the platform = ``perf.cache= _misses`` +``branch_instructions`` the count of branch instructions by applicatio= ns running on the platform = ``perf.branc= h_instructions`` +``branch_misses`` the count of branch misses by applications run= ning on the platform = ``perf.branc= h_misses`` +``bus_cycles`` the count of bus cycles by applications runnin= g on the platform = ``perf.bus_c= ycles`` +``stalled_cycles_frontend`` the count of stalled CPU cycles in the fronten= d of the instruction processor pipeline by applications running on the plat= form ``perf.stall= ed_cycles_frontend`` +``stalled_cycles_backend`` the count of stalled CPU cycles in the backend= of the instruction processor pipeline by applications running on the platf= orm ``perf.stall= ed_cycles_backend`` +``ref_cpu_cycles`` the count of total CPU cycles not affected by = CPU frequency scaling by applications running on the platform = ``perf.ref_c= pu_cycles`` +``cpu_clock`` the count of CPU clock time, as measured by a = monotonic high-resolution per-CPU timer, by applications running on the pla= tform ``perf.cpu_c= lock`` +``task_clock`` the count of task clock time, as measured by a= monotonic high-resolution CPU timer, specific to the task that is run by a= pplications running on the platform ``perf.task_= clock`` +``page_faults`` the count of page faults by applications runni= ng on the platform. This includes minor, major, invalid and other types of = page faults ``perf.page_= faults`` +``context_switches`` the count of context switches by applications = running on the platform = ``perf.conte= xt_switches`` +``cpu_migrations`` the count of CPU migrations, that is, where th= e process moved from one logical processor to another, by applications runn= ing on the platform ``perf.cpu_m= igrations`` +``page_faults_min`` the count of minor page faults, that is, where= the page was present in the page cache, and therefore the fault avoided lo= ading it from storage, by applications running on the platform ``perf.page_= faults_min`` +``page_faults_maj`` the count of major page faults, that is, where= the page was not present in the page cache, and therefore had to be fetche= d from storage, by applications running on the platform ``perf.page_= faults_maj`` +``alignment_faults`` the count of alignment faults, that is when th= e load or store is not aligned properly, by applications running on the pla= tform ``perf.align= ment_faults`` +``emulation_faults`` the count of emulation faults, that is when th= e kernel traps on unimplemented instrucions and emulates them for user spac= e, by applications running on the platform ``perf.emula= tion_faults`` +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +:anchor:`` + +Devices +------- + +The final set of XML elements are all used to describe devices provided to= the +guest domain. All devices occur as children of the main ``devices`` elemen= t. +:since:`Since 0.1.3` + +:: + + ... + + /usr/lib/xen/bin/qemu-dm + + ... + +``emulator`` + The contents of the ``emulator`` element specify the fully qualified pa= th to + the device model emulator binary. The `capabilities XML `__ + specifies the recommended default emulator to use for each particular d= omain + type / architecture combination. + +To help users identifying devices they care about, every device can have d= irect +child ``alias`` element which then has ``name`` attribute where users can = store +identifier for the device. The identifier has to have "ua-" prefix and mus= t be +unique within the domain. Additionally, the identifier must consist only o= f the +following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` + +:: + + + + + + + + + ... + + +:anchor:`` + +Hard drives, floppy disks, CDROMs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Any device that looks like a disk, be it a floppy, harddisk, cdrom, or +paravirtualized driver is specified via the ``disk`` element. + +:: + + ... + + + + + + + + + 10000000 + 400000 + 100000 + + + + ... + + + + ... + + + ... + + + + + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + somevalue + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + ... + +``disk`` + The ``disk`` element is the main container for describing disks and sup= ports + the following attributes: + + ``type`` + Valid values are "file", "block", "dir" ( :since:`since 0.7.5` ), + "network" ( :since:`since 0.8.7` ), or "volume" ( :since:`since 1.0.= 5` ), + or "nvme" ( :since:`since 6.0.0` ) and refer to the underlying sourc= e for + the disk. :since:`Since 0.0.3` + ``device`` + Indicates how the disk is to be exposed to the guest OS. Possible va= lues + for this attribute are "floppy", "disk", "cdrom", and "lun", default= ing to + "disk". + + Using "lun" ( :since:`since 0.9.10` ) is only valid when the ``type`= ` is + "block" or "network" for ``protocol=3D'iscsi'`` or when the ``type``= is + "volume" when using an iSCSI source ``pool`` for ``mode`` "host" or = as an + `NPIV `__ virtual Host= Bus + Adapter (vHBA) using a Fibre Channel storage pool. Configured in this + manner, the LUN behaves identically to "disk", except that generic S= CSI + commands from the guest are accepted and passed through to the physi= cal + device. Also note that device=3D'lun' will only be recognized for ac= tual raw + devices, but never for individual partitions or LVM partitions (in t= hose + cases, the kernel will reject the generic SCSI commands, making it + identical to device=3D'disk'). :since:`Since 0.1.4` + + ``model`` + Indicates the emulated device model of the disk. Typically this is + indicated solely by the ``bus`` property but for ``bus`` "virtio" the + model can be specified further with "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. :since:`S= ince + 5.2.0` + ``rawio`` + Indicates whether the disk needs rawio capability. Valid settings are + "yes" or "no" (default is "no"). If any one disk in a domain has + rawio=3D'yes', rawio capability will be enabled for all disks in the= domain + (because, in the case of QEMU, this capability can only be set on a + per-process basis). This attribute is only valid when device is "lun= ". NB, + ``rawio`` intends to confine the capability per-device, however, cur= rent + QEMU implementation gives the domain process broader capability than= that + (per-process basis, affects all the domain disks). To confine the + capability as much as possible for QEMU driver as this stage, ``sgio= `` is + recommended, it's more secure than ``rawio``. :since:`Since 0.9.10` + ``sgio`` + If supported by the hypervisor and OS, indicates whether unprivileged + SG_IO commands are filtered for the disk. Valid settings are "filter= ed" or + "unfiltered" where the default is "filtered". Only available when the + ``device`` is 'lun'. :since:`Since 1.0.2` + ``snapshot`` + Indicates the default behavior of the disk during disk snapshots: + "``internal``" requires a file format such as qcow2 that can store b= oth + the snapshot and the data changes since the snapshot; "``external``"= will + separate the snapshot from the live data; and "``no``" means the dis= k will + not participate in snapshots. Read-only disks default to "``no``", w= hile + the default for other disks depends on the hypervisor's capabilities= . Some + hypervisors allow a per-snapshot choice as well, during `domain snap= shot + creation `__. Not all snapshot modes are suppor= ted; + for example, enabling snapshots with a transient disk generally does= not + make sense. :since:`Since 0.9.5` + +``source`` + Representation of the disk ``source`` depends on the disk ``type`` attr= ibute + value as follows: + + ``file`` + The ``file`` attribute specifies the fully-qualified path to the file + holding the disk. :since:`Since 0.0.3` + ``block`` + The ``dev`` attribute specifies the fully-qualified path to the host + device to serve as the disk. :since:`Since 0.0.3` + ``dir`` + The ``dir`` attribute specifies the fully-qualified path to the dire= ctory + to use as the disk. :since:`Since 0.7.5` + ``network`` + The ``protocol`` attribute specifies the protocol to access to the + requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdo= g", + "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp". + + For any ``protocol`` other than ``nbd`` an additional attribute ``na= me`` + is mandatory to specify which volume/image will be used. + + For "nbd", the ``name`` attribute is optional. TLS transport for NBD= can + be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU + hypervisor, usage of a TLS environment can also be globally controll= ed on + the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in + /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` ) + + For protocols ``http`` and ``https`` an optional attribute ``query`` + specifies the query string. ( :since:`Since 6.2.0` ) + + For "iscsi" ( :since:`since 1.0.4` ), the ``name`` attribute may inc= lude a + logical unit number, separated from the target's name by a slash (e.= g., + ``iqn.2013-07.com.example:iscsi-pool/1``). If not specified, the def= ault + LUN is zero. + + For "vxhs" ( :since:`since 3.8.0` ), the ``name`` is the UUID of the + volume, assigned by the HyperScale server. Additionally, an optional + attribute ``tls`` (QEMU only) can be used to control whether a VxHS = block + device would utilize a hypervisor configured TLS X.509 certificate + environment in order to encrypt the data channel. For the QEMU hyper= visor, + usage of a TLS environment can also be globally controlled on the ho= st by + the ``vxhs_tls`` and ``vxhs_tls_x509_cert_dir`` or + ``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu= .conf. + If ``vxhs_tls`` is enabled, then unless the domain ``tls`` attribute= is + set to "no", libvirt will use the host configured TLS environment. I= f the + ``tls`` attribute is set to "yes", then regardless of the qemu.conf + setting, TLS authentication will be attempted. + + :since:`Since 0.8.7` + + ``volume`` + The underlying disk source is represented by attributes ``pool`` and + ``volume``. Attribute ``pool`` specifies the name of the `storage + pool `__ (managed by libvirt) where the disk sou= rce + resides. Attribute ``volume`` specifies the name of storage volume + (managed by libvirt) used as the disk source. The value for the ``vo= lume`` + attribute will be the output from the "Name" column of a + ``virsh vol-list [pool-name]`` command. + + Use the attribute ``mode`` ( :since:`since 1.1.1` ) to indicate how = to + represent the LUN as the disk source. Valid values are "direct" and + "host". If ``mode`` is not specified, the default is to use "host". = Using + "direct" as the ``mode`` value indicates to use the `storage + pool's `__ ``source`` element ``host`` attribute= as + the disk source to generate the libiscsi URI (e.g. + 'file=3Discsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/= 1'). + Using "host" as the ``mode`` value indicates to use the LUN's path a= s it + shows up on host (e.g. + 'file=3D/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.= example:iscsi-pool-lun-1'). + Using a LUN from an iSCSI source pool provides the same features as a + ``disk`` configured using ``type`` 'block' or 'network' and ``device= `` of + 'lun' with respect to how the LUN is presented to and may be used by= the + guest. :since:`Since 1.0.5` + + ``nvme`` + To specify disk source for NVMe disk the ``source`` element has the + following attributes: + + ``type`` + The type of address specified in ``address`` sub-element. Current= ly, + only ``pci`` value is accepted. + ``managed`` + This attribute instructs libvirt to detach NVMe controller + automatically on domain startup (``yes``) or expect the controlle= r to + be detached by system administrator (``no``). + ``namespace`` + The namespace ID which should be assigned to the domain. Accordin= g to + NVMe standard, namespace numbers start from 1, including. + + The difference between ```` and ```` i= s that + the latter is plain host device assignment with all its limitations = (e.g. + no live migration), while the former makes hypervisor to run the NVM= e disk + through hypervisor's block layer thus enabling all features provided= by + the layer (e.g. snapshots, domain migration, etc.). Moreover, since = the + NVMe disk is unbinded from its PCI driver, the host kernel storage s= tack + is not involved (compared to passing say ``/dev/nvme0n1`` via + ```` and therefore lower latencies can be achie= ved. + + With "file", "block", and "volume", one or more optional sub-elements + ``seclabel``, `described below <#seclabel>`__ (and :since:`since 0.9.9`= ), + can be used to override the domain security labeling policy for just th= at + source file. (NB, for "volume" type disk, ``seclabel`` is only valid wh= en the + specified storage volume is of 'file' or 'block' type). + + The ``source`` element may also have the ``index`` attribute with same + semantics the `index <#elementsDiskBackingStoreIndex>`__ attribute of + ``backingStore`` + + The ``source`` element may contain the following sub elements: + + ``host`` + When the disk ``type`` is "network", the ``source`` may have zero or= more + ``host`` sub-elements used to specify the hosts to connect. The ``ho= st`` + element supports 4 attributes, viz. "name", "port", "transport" and + "socket", which specify the hostname, the port number, transport typ= e and + path to socket, respectively. The meaning of this element and the nu= mber + of the elements depend on the protocol attribute. + + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + Protocol Meaning Num= ber of hosts Default port + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + nbd a server running nbd-server onl= y one 10809 + iscsi an iSCSI server onl= y one 3260 + rbd monitor servers of RBD one= or more librados default + sheepdog one of the sheepdog servers (default is localhost:7000) zer= o or one 7000 + gluster a server running glusterd daemon one= or more ( :since:`Since 2.1.0` ), just one prior to that 24007 + vxhs a server running Veritas HyperScale daemon onl= y one 9999 + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + gluster supports "tcp", "rdma", "unix" as valid values for the trans= port + attribute. nbd supports "tcp" and "unix". Others only support "tcp".= If + nothing is specified, "tcp" is assumed. If the transport is "unix", = the + socket attribute specifies the path to an AF_UNIX socket. + + ``snapshot`` + The ``name`` attribute of ``snapshot`` element can optionally specif= y an + internal snapshot name to be used as the source for storage protocol= s. + Supported for 'rbd' :since:`since 1.2.11 (QEMU only).` + ``config`` + The ``file`` attribute for the ``config`` element provides a fully + qualified path to a configuration file to be provided as a parameter= to + the client of a networked storage protocol. Supported for 'rbd' + :since:`since 1.2.11 (QEMU only).` + ``auth`` + :since:`Since libvirt 3.9.0` , the ``auth`` element is supported for= a + disk ``type`` "network" that is using a ``source`` element with the + ``protocol`` attributes "rbd" or "iscsi". If present, the ``auth`` e= lement + provides the authentication credentials needed to access the source.= It + includes a mandatory attribute ``username``, which identifies the us= ername + to use during authentication, as well as a sub-element ``secret`` wi= th + mandatory attribute ``type``, to tie back to a `libvirt secret + object `__ that holds the actual password or other + credentials (the domain XML intentionally does not expose the passwo= rd, + only the reference to the object that does manage the password). Kno= wn + secret types are "ceph" for Ceph RBD network sources and "iscsi" for= CHAP + authentication of iSCSI targets. Both will require either a ``uuid`` + attribute with the UUID of the secret object or a ``usage`` attribute + matching the key that was specified in the secret object. + ``encryption`` + :since:`Since libvirt 3.9.0` , the ``encryption`` can be a sub-eleme= nt of + the ``source`` element for encrypted storage sources. If present, + specifies how the storage source is encrypted See the `Storage + Encryption `__ page for more informati= on. + Note that the 'qcow' format of encryption is broken and thus is no l= onger + supported for use with disk images. ( :since:`Since libvirt 4.5.0` ) + ``reservations`` + :since:`Since libvirt 4.4.0` , the ``reservations`` can be a sub-ele= ment + of the ``source`` element for storage sources (QEMU driver only). If + present it enables persistent reservations for SCSI based disks. The + element has one mandatory attribute ``managed`` with accepted values + ``yes`` and ``no``. If ``managed`` is enabled libvirt prepares and m= anages + any resources needed. When the persistent reservations are unmanaged= , then + the hypervisor acts as a client and the path to the server socket mu= st be + provided in the child element ``source``, which currently accepts on= ly the + following attributes: ``type`` with one value ``unix``, ``path`` pat= h to + the socket, and finally ``mode`` which accepts one value ``client`` + specifying the role of hypervisor. It's recommended to allow libvirt + manage the persistent reservations. + ``initiator`` + :since:`Since libvirt 4.7.0` , the ``initiator`` element is supporte= d for + a disk ``type`` "network" that is using a ``source`` element with the + ``protocol`` attribute "iscsi". If present, the ``initiator`` element + provides the initiator IQN needed to access the source via mandatory + attribute ``name``. + ``address`` + For disk of type ``nvme`` this element specifies the PCI address of = the + host NVMe controller. :since:`Since 6.0.0` + ``slices`` + The ``slices`` element using its ``slice`` sub-elements allows confi= guring + offset and size of either the location of the image format + (``slice type=3D'storage'``) inside the storage source or the guest = data + inside the image format container (future expansion). The ``offset``= and + ``size`` values are in bytes. :since:`Since 6.1.0` + ``ssl`` + For ``https`` and ``ftps`` accessed storage it's possible to tweak t= he SSL + transport parameters with this element. The ``verify`` attribute all= ows to + turn on or off SSL certificate validation. Supported values are ``ye= s`` + and ``no``. :since:`Since 6.2.0` + ``cookies`` + For ``http`` and ``https`` accessed storage it's possible to pass on= e or + more cookies. The cookie name and value must conform to the HTTP + specification. :since:`Since 6.2.0` + ``readahead`` + Specifies the size of the readahead buffer for protocols which suppo= rt it. + (all 'curl' based drivers in qemu). The size is in bytes. Note that = '0' is + considered as if the value is not provided. :since:`Since 6.2.0` + ``timeout`` + Specifies the connection timeout for protocols which support it. Not= e that + '0' is considered as if the value is not provided. :since:`Since 6.2= .0` + + For a "file" or "volume" disk type which represents a cdrom or floppy (= the + ``device`` attribute), it is possible to define policy what to do with = the + disk if the source file is not accessible. (NB, ``startupPolicy`` is not + valid for "volume" disk unless the specified storage volume is of "file" + type). This is done by the ``startupPolicy`` attribute ( :since:`since = 0.9.7` + ), accepting these values: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + mandatory fail if missing for any reason (the default) + requisite fail if missing on boot up, drop if missing on migrate/restor= e/revert + optional drop if missing at any start attempt + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + + :since:`Since 1.1.2` the ``startupPolicy`` is extended to support hard = disks + besides cdrom and floppy. On guest cold bootup, if a certain disk is not + accessible or its disk chain is broken, with startupPolicy 'optional' t= he + guest will drop this disk. This feature doesn't support migration curre= ntly. + +``backingStore`` + This element describes the backing store used by the disk specified by + sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor dri= ver + does not support the + `backingStoreInput `__ ( + :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored = on + input and only used for output to describe the detected backing chains = of + running domains. If ``backingStoreInput`` is supported the ``backingSto= re`` + is used as the backing image of ``source`` or other ``backingStore`` + overriding any backing image information recorded in the image metadata= . An + empty ``backingStore`` element means the sibling source is self-contain= ed and + is not based on any backing store. For the detected backing chain infor= mation + to be accurate, the backing format must be correctly specified in the + metadata of each file of the chain (files created by libvirt satisfy th= is + property, but using existing external files for snapshot or block copy + operations requires the end user to pre-create the file correctly). The + following attributes are supported in ``backingStore``: + + ``type`` + The ``type`` attribute represents the type of disk used by the backi= ng + store, see disk type attribute above for more details and possible v= alues. + ``index`` + This attribute is only valid in output (and ignored on input) and it= can + be used to refer to a specific part of the disk chain when doing blo= ck + operations (such as via the ``virDomainBlockRebase`` API). For examp= le, + ``vda[2]`` refers to the backing store with ``index=3D'2'`` of the d= isk with + ``vda`` target. + + Moreover, ``backingStore`` supports the following sub-elements: + + ``format`` + The ``format`` element contains ``type`` attribute which specifies t= he + internal format of the backing store, such as ``raw`` or ``qcow2``. + ``source`` + This element has the same structure as the ``source`` element in ``d= isk``. + It specifies which file, device, or network location contains the da= ta of + the described backing store. + ``backingStore`` + If the backing store is not self-contained, the next element in the = chain + is described by nested ``backingStore`` element. + +``mirror`` + This element is present if the hypervisor has started a long-running bl= ock + job operation, where the mirror location in the ``source`` sub-element = will + eventually have the same contents as the source, and with the file form= at in + the sub-element ``format`` (which might differ from the format of the + source). The details of the ``source`` sub-element are determined by the + ``type`` attribute of the mirror, similar to what is done for the overa= ll + ``disk`` device element. The ``job`` attribute mentions which API start= ed the + operation ("copy" for the ``virDomainBlockRebase`` API, or "active-comm= it" + for the ``virDomainBlockCommit`` API), :since:`since 1.2.7` . The attri= bute + ``ready``, if present, tracks progress of the job: ``yes`` if the disk = is + known to be ready to pivot, or, :since:`since 1.2.7` , ``abort`` or ``p= ivot`` + if the job is in the process of completing. If ``ready`` is not present= , the + disk is probably still copying. For now, this element only valid in out= put; + it is ignored on input. The ``source`` sub-element exists for all two-p= hase + jobs :since:`since 1.2.6` . Older libvirt supported only block copy to a + file, :since:`since 0.9.12` ; for compatibility with older clients, suc= h jobs + include redundant information in the attributes ``file`` and ``format``= in + the ``mirror`` element. +``target`` + The ``target`` element controls the bus / device under which the disk is + exposed to the guest OS. The ``dev`` attribute indicates the "logical" = device + name. The actual device name specified is not guaranteed to map to the = device + name in the guest OS. Treat it as a device ordering hint. The optional + ``bus`` attribute specifies the type of disk device to emulate; possible + values are driver specific, with typical values being "ide", "scsi", + "virtio", "xen", "usb", "sata", or "sd" :since:`"sd" since 1.1.2` . If + omitted, the bus type is inferred from the style of the device name (e.= g. a + device named 'sda' will typically be exported using a SCSI bus). The op= tional + attribute ``tray`` indicates the tray status of the removable disks (i.= e. + CDROM or Floppy disk), the value can be either "open" or "closed", defa= ults + to "closed". NB, the value of ``tray`` could be updated while the domai= n is + running. The optional attribute ``removable`` sets the removable flag f= or USB + disks, and its value can be either "on" or "off", defaulting to "off". + :since:`Since 0.0.3; ``bus`` attribute since 0.4.3; ``tray`` attribute = since + 0.9.11; "usb" attribute value since after 0.4.4; "sata" attribute value= since + 0.9.7; "removable" attribute value since 1.1.3` +``iotune`` + The optional ``iotune`` element provides the ability to provide additio= nal + per-device I/O tuning, with values that can vary for each device (contr= ast + this to the ` <#elementsBlockTuning>`__ element, which appli= es + globally to the domain). Currently, the only tuning available is Block = I/O + throttling for qemu. This element has optional sub-elements; any sub-el= ement + not specified or given with a value of 0 implies no limit. :since:`Since + 0.9.8` + + ``total_bytes_sec`` + The optional ``total_bytes_sec`` element is the total throughput lim= it in + bytes per second. This cannot appear with ``read_bytes_sec`` or + ``write_bytes_sec``. + ``read_bytes_sec`` + The optional ``read_bytes_sec`` element is the read throughput limit= in + bytes per second. + ``write_bytes_sec`` + The optional ``write_bytes_sec`` element is the write throughput lim= it in + bytes per second. + ``total_iops_sec`` + The optional ``total_iops_sec`` element is the total I/O operations = per + second. This cannot appear with ``read_iops_sec`` or ``write_iops_se= c``. + ``read_iops_sec`` + The optional ``read_iops_sec`` element is the read I/O operations per + second. + ``write_iops_sec`` + The optional ``write_iops_sec`` element is the write I/O operations = per + second. + ``total_bytes_sec_max`` + The optional ``total_bytes_sec_max`` element is the maximum total + throughput limit in bytes per second. This cannot appear with + ``read_bytes_sec_max`` or ``write_bytes_sec_max``. + ``read_bytes_sec_max`` + The optional ``read_bytes_sec_max`` element is the maximum read thro= ughput + limit in bytes per second. + ``write_bytes_sec_max`` + The optional ``write_bytes_sec_max`` element is the maximum write + throughput limit in bytes per second. + ``total_iops_sec_max`` + The optional ``total_iops_sec_max`` element is the maximum total I/O + operations per second. This cannot appear with ``read_iops_sec_max``= or + ``write_iops_sec_max``. + ``read_iops_sec_max`` + The optional ``read_iops_sec_max`` element is the maximum read I/O + operations per second. + ``write_iops_sec_max`` + The optional ``write_iops_sec_max`` element is the maximum write I/O + operations per second. + ``size_iops_sec`` + The optional ``size_iops_sec`` element is the size of I/O operations= per + second. + + :since:`Throughput limits since 1.2.11 and QEMU 1.7` + + ``group_name`` + The optional ``group_name`` provides the cability to share I/O throt= tling + quota between multiple drives. This prevents end-users from circumve= nting + a hosting provider's throttling policy by splitting 1 large drive in= N + small drives and getting N times the normal throttling quota. Any na= me may + be used. + + :since:`group_name since 3.0.0 and QEMU 2.4` + + ``total_bytes_sec_max_length`` + The optional ``total_bytes_sec_max_length`` element is the maximum + duration in seconds for the ``total_bytes_sec_max`` burst period. On= ly + valid when the ``total_bytes_sec_max`` is set. + ``read_bytes_sec_max_length`` + The optional ``read_bytes_sec_max_length`` element is the maximum du= ration + in seconds for the ``read_bytes_sec_max`` burst period. Only valid w= hen + the ``read_bytes_sec_max`` is set. + ``write_bytes_sec_max`` + The optional ``write_bytes_sec_max_length`` element is the maximum + duration in seconds for the ``write_bytes_sec_max`` burst period. On= ly + valid when the ``write_bytes_sec_max`` is set. + ``total_iops_sec_max_length`` + The optional ``total_iops_sec_max_length`` element is the maximum du= ration + in seconds for the ``total_iops_sec_max`` burst period. Only valid w= hen + the ``total_iops_sec_max`` is set. + ``read_iops_sec_max_length`` + The optional ``read_iops_sec_max_length`` element is the maximum dur= ation + in seconds for the ``read_iops_sec_max`` burst period. Only valid wh= en the + ``read_iops_sec_max`` is set. + ``write_iops_sec_max`` + The optional ``write_iops_sec_max_length`` element is the maximum du= ration + in seconds for the ``write_iops_sec_max`` burst period. Only valid w= hen + the ``write_iops_sec_max`` is set. + + :since:`Throughput length since 2.4.0 and QEMU 2.6` + +``driver`` + The optional driver element allows specifying further details related t= o the + hypervisor driver used to provide the disk. :since:`Since 0.1.8` + + - If the hypervisor supports multiple backend drivers, then the ``name= `` + attribute selects the primary backend driver name, while the optional + ``type`` attribute provides the sub-type. For example, xen supports = a name + of "tap", "tap2", "phy", or "file", with a type of "aio", while qemu= only + supports a name of "qemu", but multiple types including "raw", "boch= s", + "qcow2", and "qed". + - The optional ``cache`` attribute controls the cache mechanism, possi= ble + values are "default", "none", "writethrough", "writeback", "directsy= nc" + (like "writethrough", but it bypasses the host page cache) and "unsa= fe" + (host may cache all disk io, and sync requests from guest are ignore= d). + :since:` Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7= ` + - The optional ``error_policy`` attribute controls how the hypervisor = will + behave on a disk read or write error, possible values are "stop", + "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" si= nce + 0.9.7` The default is left to the discretion of the hypervisor. Ther= e is + also an optional ``rerror_policy`` that controls behavior for read e= rrors + only. :since:`Since 0.9.7` . If no rerror_policy is given, error_pol= icy is + used for both read and write errors. If rerror_policy is given, it + overrides the ``error_policy`` for read errors. Also note that "enos= pace" + is not a valid policy for read errors, so if ``error_policy`` is set= to + "enospace" and no ``rerror_policy`` is given, the read error policy = will + be left at its default. + - The optional ``io`` attribute controls specific policies on I/O; qemu + guests support "threads" and "native" :since:`Since 0.8.8` , io_uring + :since:`Since 6.3.0 (QEMU 5.0)` . + - The optional ``ioeventfd`` attribute allows users to set `domain I/O + asynchronous handling `__= for + disk device. The default is left to the discretion of the hypervisor. + Accepted values are "on" and "off". Enabling this allows qemu to exe= cute + VM while a separate thread handles I/O. Typically guests experiencin= g high + system CPU utilization during I/O will benefit from this. On the oth= er + hand, on overloaded host it could increase guest I/O latency. + :since:`Since 0.9.3 (QEMU and KVM only)` **In general you should lea= ve + this option alone, unless you are very certain you know what you are + doing.** + - The optional ``event_idx`` attribute controls some aspects of device= event + processing. The value can be either 'on' or 'off' - if it is on, it = will + reduce the number of interrupts and exits for the guest. The default= is + determined by QEMU; usually if the feature is supported, default is = on. In + case there is a situation where this behavior is suboptimal, this + attribute provides a way to force the feature off. :since:`Since 0.9= .5 + (QEMU and KVM only)` **In general you should leave this option alone, + unless you are very certain you know what you are doing.** + - The optional ``copy_on_read`` attribute controls whether to copy read + backing file into the image file. The value can be either "on" or "o= ff". + Copy-on-read avoids accessing the same backing file sectors repeated= ly and + is useful when the backing file is over a slow network. By default + copy-on-read is off. :since:`Since 0.9.10 (QEMU and KVM only)` + - The optional ``discard`` attribute controls whether discard requests= (also + known as "trim" or "unmap") are ignored or passed to the filesystem.= The + value can be either "unmap" (allow the discard request to be passed)= or + "ignore" (ignore the discard request). :since:`Since 1.0.6 (QEMU and= KVM + only)` + - The optional ``detect_zeroes`` attribute controls whether to detect = zero + write requests. The value can be "off", "on" or "unmap". First two v= alues + turn the detection off and on, respectively. The third value ("unmap= ") + turns the detection on and additionally tries to discard such areas = from + the image based on the value of ``discard`` above (it will act as "o= n" if + ``discard`` is set to "ignore"). NB enabling the detection is a comp= ute + intensive operation, but can save file space and/or time on slow med= ia. + :since:`Since 2.0.0` + - The optional ``iothread`` attribute assigns the disk to an IOThread = as + defined by the range for the domain + `iothreads <#elementsIOThreadsAllocation>`__ value. Multiple disks m= ay be + assigned to the same IOThread and are numbered from 1 to the domain + iothreads value. Available for a disk device ``target`` configured t= o use + "virtio" ``bus`` and "pci" or "ccw" ``address`` types. :since:`Since= 1.2.8 + (QEMU 2.1)` + - The optional ``queues`` attribute specifies the number of virt queue= s for + virtio-blk. ( :since:`Since 3.9.0` ) + - For virtio disks, `Virtio-specific options <#elementsVirtio>`__ can = also + be set. ( :since:`Since 3.5.0` ) + +``backenddomain`` + The optional ``backenddomain`` element allows specifying a backend doma= in + (aka driver domain) hosting the disk. Use the ``name`` attribute to spe= cify + the backend domain name. :since:`Since 1.2.13 (Xen only)` +``boot`` + Specifies that the disk is bootable. The ``order`` attribute determines= the + order in which devices will be tried during boot sequence. On the S390 + architecture only the first boot device is used. The optional ``loadpar= m`` + attribute is an 8 character string which can be queried by guests on S3= 90 via + sclp or diag 308. Linux guests on S390 can use ``loadparm`` to select a= boot + entry. :since:`Since 3.5.0` The per-device ``boot`` elements cannot be = used + together with general boot elements in `BIOS bootloader <#elementsOSBIO= S>`__ + section. :since:`Since 0.8.8` +``encryption`` + Starting with :since:`libvirt 3.9.0` the ``encryption`` element is pref= erred + to be a sub-element of the ``source`` element. If present, specifies ho= w the + volume is encrypted using "qcow". See the `Storage + Encryption `__ page for more information. +``readonly`` + If present, this indicates the device cannot be modified by the guest. = For + now, this is the default for disks with attribute ``device=3D'cdrom'``. +``shareable`` + If present, this indicates the device is expected to be shared between + domains (assuming the hypervisor and OS support this), which means that + caching should be deactivated for that device. +``transient`` + If present, this indicates that changes to the device contents should be + reverted automatically when the guest exits. With some hypervisors, mar= king a + disk transient prevents the domain from participating in migration or + snapshots. :since:`Since 0.9.5` +``serial`` + If present, this specify serial number of virtual hard drive. For examp= le, it + may look like ``WD-WMAP9A966149``. Not supported for + scsi-block devices, that is those using disk ``type`` 'block' using + ``device`` 'lun' on ``bus`` 'scsi'. :since:`Since 0.7.1` +``wwn`` + If present, this element specifies the WWN (World Wide Name) of a virtu= al + hard disk or CD-ROM drive. It must be composed of 16 hexadecimal digits. + :since:`Since 0.10.1` +``vendor`` + If present, this element specifies the vendor of a virtual hard disk or + CD-ROM device. It must not be longer than 8 printable characters. + :since:`Since 1.0.1` +``product`` + If present, this element specifies the product of a virtual hard disk or + CD-ROM device. It must not be longer than 16 printable characters. + :since:`Since 1.0.1` +``address`` + If present, the ``address`` element ties the disk to a given slot of a + controller (the actual ```` device can often be inferred by + libvirt, although it can be `explicitly specified <#elementsControllers= >`__). + The ``type`` attribute is mandatory, and is typically "pci" or "drive".= For a + "pci" controller, additional attributes for ``bus``, ``slot``, and + ``function`` must be present, as well as optional ``domain`` and + ``multifunction``. Multifunction defaults to 'off'; any other value req= uires + QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, addit= ional + attributes ``controller``, ``bus``, ``target`` ( :since:`libvirt 0.9.11= ` ), + and ``unit`` are available, each defaulting to 0. +``auth`` + Starting with :since:`libvirt 3.9.0` the ``auth`` element is preferred = to be + a sub-element of the ``source`` element. The element is still read and + managed as a ``disk`` sub-element. It is invalid to use ``auth`` as bot= h a + sub-element of ``disk`` and ``source``. The ``auth`` element was introd= uced + as a ``disk`` sub-element in :since:`libvirt 0.9.7.` +``geometry`` + The optional ``geometry`` element provides the ability to override geom= etry + settings. This mostly useful for S390 DASD-disks or older DOS-disks. + :since:`0.10.0` + + ``cyls`` + The ``cyls`` attribute is the number of cylinders. + ``heads`` + The ``heads`` attribute is the number of heads. + ``secs`` + The ``secs`` attribute is the number of sectors per track. + ``trans`` + The optional ``trans`` attribute is the BIOS-Translation-Modus (none= , lba + or auto) + +``blockio`` + If present, the ``blockio`` element allows to override any of the block + device properties listed below. :since:`Since 0.10.2 (QEMU and KVM)` + + ``logical_block_size`` + The logical block size the disk will report to the guest OS. For Lin= ux + this would be the value returned by the BLKSSZGET ioctl and describe= s the + smallest units for disk I/O. + ``physical_block_size`` + The physical block size the disk will report to the guest OS. For Li= nux + this would be the value returned by the BLKPBSZGET ioctl and describ= es the + disk's hardware sector size which can be relevant for the alignment = of + disk data. + +:anchor:`` + +Filesystems +~~~~~~~~~~~ + +A directory on the host that can be accessed directly from the guest. +:since:`since 0.3.3, since 0.8.5 for QEMU/KVM` + +:: + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + ... + +``filesystem`` + The filesystem attribute ``type`` specifies the type of the ``source``.= The + possible values are: + + ``mount`` + A host directory to mount in the guest. Used by LXC, OpenVZ :since:`= (since + 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``= type`` + if one is not specified. This mode also has an optional sub-element + ``driver``, with an attribute ``type=3D'path'`` or ``type=3D'handle'= `` + :since:`(since 0.9.7)` . The driver block has an optional attribute + ``wrpolicy`` that further controls interaction with the host page ca= che; + omitting the attribute gives default behavior, while the value + ``immediate`` means that a host writeback is immediately triggered f= or all + pages touched during a guest file write operation :since:`(since 0.9= .10)` + . :since:`Since 6.2.0` , ``type=3D'virtiofs'`` is also supported. Us= ing + virtiofs requires setting up shared memory, see the guide: + `Virtio-FS `__ + ``template`` + OpenVZ filesystem template. Only used by OpenVZ driver. + ``file`` + A host file will be treated as an image and mounted in the guest. The + filesystem format will be autodetected. Only used by LXC driver. + ``block`` + A host block device to mount in the guest. The filesystem format wil= l be + autodetected. Only used by LXC driver :since:`(since 0.9.5)` . + ``ram`` + An in-memory filesystem, using memory from the host OS. The source e= lement + has a single attribute ``usage`` which gives the memory usage limit = in + KiB, unless units are specified by the ``units`` attribute. Only use= d by + LXC driver. :since:` (since 0.9.13)` + ``bind`` + A directory inside the guest will be bound to another directory insi= de the + guest. Only used by LXC driver :since:` (since 0.9.13)` + + The filesystem element has an optional attribute ``accessmode`` which + specifies the security mode for accessing the source :since:`(since 0.8= .5)` . + Currently this only works with ``type=3D'mount'`` for the QEMU/KVM driv= er. For + driver type ``virtiofs``, only ``passthrough`` is supported. For other = driver + types, the possible values are: + + ``passthrough`` + The ``source`` is accessed with the permissions of the user inside t= he + guest. This is the default ``accessmode`` if one is not specified. `= More + info `__ + ``mapped`` + The ``source`` is accessed with the permissions of the hypervisor (Q= EMU + process). `More + info `__ + ``squash`` + Similar to 'passthrough', the exception is that failure of privileged + operations like 'chown' are ignored. This makes a passthrough-like m= ode + usable for people who run the hypervisor as non-root. `More + info `__ + + :since:`Since 5.2.0` , the filesystem element has an optional attribute + ``model`` with supported values "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. + + The filesystem element has an optional attribute ``multidevs`` which + specifies how to deal with a filesystem export containing more than one + device, in order to avoid file ID collisions on guest when using 9pfs ( + :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not availa= ble + for virtiofs. The possible values are: + + ``default`` + Use QEMU's default setting (which currently is ``warn``). + ``remap`` + This setting allows guest to access multiple devices per export with= out + encountering misbehaviours. Inode numbers from host are automatically + remapped on guest to actively prevent file ID collisions if guest ac= cesses + one export containing multiple devices. + ``forbid`` + Only allow to access one device per export by guest. Attempts to acc= ess + additional devices on the same export will cause the individual file= system + access by guest to fail with an error and being logged (once) as err= or on + host side. + ``warn`` + This setting resembles the behaviour of 9pfs prior to QEMU 4.2, that= is no + action is performed to prevent any potential file ID collisions if an + export contains multiple devices, with the only exception: a warning= is + logged (once) on host side now. This setting may lead to misbehaviou= rs on + guest side if more than one device is exported per export, due to the + potential file ID collisions this may cause on guest side in that ca= se. + +``driver`` + The optional driver element allows specifying further details related t= o the + hypervisor driver used to provide the filesystem. :since:`Since 1.0.6` + + - If the hypervisor supports multiple backend drivers, then the ``type= `` + attribute selects the primary backend driver name, while the ``forma= t`` + attribute provides the format type. For example, LXC supports a type= of + "loop", with a format of "raw" or "nbd" with any format. QEMU suppor= ts a + type of "path" or "handle", but no formats. Virtuozzo driver support= s a + type of "ploop" with a format of "ploop". + - For virtio-backed devices, `Virtio-specific options <#elementsVirtio= >`__ + can also be set. ( :since:`Since 3.5.0` ) + - For ``virtiofs``, the ``queue`` attribute can be used to specify the= queue + size (i.e. how many requests can the queue fit). ( :since:`Since 6.2= .0` ) + +``binary`` + The optional ``binary`` element can tune the options for virtiofsd. All= of + the following attributes and elements are optional. The attribute ``pat= h`` + can be used to override the path to the daemon. Attribute ``xattr`` ena= bles + the use of filesystem extended attributes. Caching can be tuned via the + ``cache`` element, possible ``mode`` values being ``none`` and ``always= ``. + Locking can be controlled via the ``lock`` element - attributes ``posix= `` and + ``flock`` both accepting values ``on`` or ``off``. ( :since:`Since 6.2.= 0` ) +``source`` + The resource on the host that is being accessed in the guest. The ``nam= e`` + attribute must be used with ``type=3D'template'``, and the ``dir`` attr= ibute + must be used with ``type=3D'mount'``. The ``usage`` attribute is used w= ith + ``type=3D'ram'`` to set the memory limit in KiB, unless units are speci= fied by + the ``units`` attribute. +``target`` + Where the ``source`` can be accessed in the guest. For most drivers thi= s is + an automatic mount point, but for QEMU/KVM this is merely an arbitrary = string + tag that is exported to the guest as a hint for where to mount. +``readonly`` + Enables exporting filesystem as a readonly mount for guest, by default + read-write access is given (currently only works for QEMU/KVM driver). +``space_hard_limit`` + Maximum space available to this guest's filesystem. :since:`Since 0.9.1= 3` +``space_soft_limit`` + Maximum space available to this guest's filesystem. The container is + permitted to exceed its soft limits for a grace period of time. Afterwa= rds + the hard limit is enforced. :since:`Since 0.9.13` + +:anchor:`` + +Device Addresses +~~~~~~~~~~~~~~~~ + +Many devices have an optional ``
    `` sub-element to describe where = the +device is placed on the virtual bus presented to the guest. If an address = (or +any optional attribute within an address) is omitted on input, libvirt will +generate an appropriate address; but an explicit address is required if mo= re +control over layout is required. See below for device examples including an +address element. + +Every address has a mandatory attribute ``type`` that describes which bus = the +device is on. The choice of which address to use for a given device is +constrained in part by the device and the architecture of the guest. For +example, a ```` device uses ``type=3D'drive'``, while a ```= ` device +would use ``type=3D'pci'`` on i686 or x86_64 guests, or ``type=3D'spapr-vi= o'`` on +PowerPC64 pseries guests. Each address type has further optional attribute= s that +control where on the bus the device will be placed: + +``pci`` + PCI addresses have the following additional attributes: ``domain`` (a 2= -byte + hex integer, not currently used by qemu), ``bus`` (a hex value between = 0 and + 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive= ), and + ``function`` (a value between 0 and 7, inclusive). Also available is the + ``multifunction`` attribute, which controls turning on the multifunctio= n bit + for a particular slot/function in the PCI control register ( :since:`si= nce + 0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but = should + be set to 'on' for function 0 of a slot that will have multiple functio= ns + used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the + architecture are supported. For example, PCI addresses for S390 guests = will + have a ``zpci`` child element, with two attributes: ``uid`` (a hex value + between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between + 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for + User-defined Identifiers and Function Identifiers. + :since:`Since 1.3.5` , some hypervisor drivers may accept an + ``
    `` element with no other attributes as an expl= icit + request to assign a PCI address for the device rather than some other t= ype of + address that may also be appropriate for that same device (e.g. virtio-= mmio). + The relationship between the PCI addresses configured in the domain XML= and + those seen by the guest OS can sometime seem confusing: a separate docu= ment + describes `how PCI addresses work `__ in more detai= l. +``drive`` + Drive addresses have the following additional attributes: ``controller`= ` (a + 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` = (a + 2-digit target number), and ``unit`` (a 2-digit unit number on the bus). +``virtio-serial`` + Each virtio-serial address has the following additional attributes: + ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus nu= mber), + and ``slot`` (a 2-digit slot within the bus). +``ccid`` + A CCID address, for smart-cards, has the following additional attribute= s: + ``bus`` (a 2-digit bus number), and ``slot`` attribute (a 2-digit slot = within + the bus). :since:`Since 0.8.8.` +``usb`` + USB addresses have the following additional attributes: ``bus`` (a hex = value + between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up = to + four octets, such as 1.2 or 2.1.3.1). +``spapr-vio`` + On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus= . It + has a flat 32-bit address space; by convention, devices are generally + assigned at a non-zero multiple of 0x00001000, but other addresses are = valid + and permitted by libvirt. Each address has the following additional + attribute: ``reg`` (the hex value address of the starting register). + :since:`Since 0.9.9.` +``ccw`` + S390 guests with a ``machine`` value of s390-ccw-virtio use the native = CCW + bus for I/O devices. CCW bus addresses have the following additional + attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ss= id`` + (a value between 0 and 3, inclusive) and ``devno`` (a hex value between= 0 and + 0xffff, inclusive). Partially specified bus addresses are not allowed. = If + omitted, libvirt will assign a free bus address with cssid=3D0xfe and s= sid=3D0. + Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0= .4` +``virtio-mmio`` + This places the device on the virtio-mmio transport, which is currently= only + available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-= mmio + addresses do not have any additional attributes. :since:`Since 1.1.3` + If the guest architecture is ``aarch64`` and the machine type is ``virt= ``, + libvirt will automatically assign PCI addresses to devices; however, the + presence of a single device with virtio-mmio address in the guest + configuration will cause libvirt to assign virtio-mmio addresses to all + further devices. :since:`Since 3.0.0` +``isa`` + ISA addresses have the following additional attributes: ``iobase`` and + ``irq``. :since:`Since 1.2.1` +``unassigned`` + For PCI hostdevs, ``
    `` allows the admin to + include a PCI hostdev in the domain XML definition, without making it + available for the guest. This allows for configurations in which Libvirt + manages the device as a regular PCI hostdev, regardless of whether the = guest + will have access to it. ``
    `` is an invalid + address type for all other device types. :since:`Since 6.0.0` + +:anchor:`` + +Virtio-related options +~~~~~~~~~~~~~~~~~~~~~~ + +QEMU's virtio devices have some attributes related to the virtio transport= under +the ``driver`` element: The ``iommu`` attribute enables the use of emulated +IOMMU by the device. The attribute ``ats`` controls the Address Translation +Service support for PCIe devices. This is needed to make use of IOTLB supp= ort +(see `IOMMU device <#elementsIommu>`__). Possible values are ``on`` or ``o= ff``. +:since:`Since 3.5.0` + +The attribute ``packed`` controls if QEMU should try to use packed virtque= ues. +Compared to regular split queues, packed queues consist of only a single +descriptor ring replacing available and used ring, index and descriptor bu= ffer. +This can result in better cache utilization and performance. If packed +virtqueues are actually used depends on the feature negotiation between QE= MU, +vhost backends and guest drivers. Possible values are ``on`` or ``off``. +:since:`Since 6.3.0 (QEMU and KVM only)` + +:anchor:`` + +Virtio transitional devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 5.2.0` , some of QEMU's virtio devices, when used with PCI/P= CIe +machine types, accept the following ``model`` values: + +``virtio-transitional`` + This device can work both with virtio 0.9 and virtio 1.0 guest drivers,= so + it's the best choice when compatibility with older guest operating syst= ems is + desired. libvirt will plug the device into a conventional PCI slot. +``virtio-non-transitional`` + This device can only work with virtio 1.0 guest drivers, and it's the + recommended option unless compatibility with older guest operating syst= ems is + necessary. libvirt will plug the device into either a PCI Express slot = or a + conventional PCI slot based on the machine type, resulting in a more + optimized PCI topology. +``virtio`` + This device will work like a ``virtio-non-transitional`` device when pl= ugged + into a PCI Express slot, and like a ``virtio-transitional`` device othe= rwise; + libvirt will pick one or the other based on the machine type. This is t= he + best choice when compatibility with libvirt versions older than 5.2.0 is + necessary, but it's otherwise not recommended to use it. + +While the information outlined above applies to most virtio devices, there= are a +few exceptions: + +- for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`= ` for + backwards compatibility reasons; +- some devices, such as GPUs and input devices (keyboard, tablet and mous= e), + are only defined in the virtio 1.0 spec and as such don't have a transi= tional + variant: the only accepted model is ``virtio``, which will result in a + non-transitional device. + +For more details see the `qemu patch +posting `__ +and the `virtio-1.0 +spec `__. + +:anchor:`` + +Controllers +~~~~~~~~~~~ + +Depending on the guest architecture, some device buses can appear more than +once, with a group of virtual devices tied to a virtual controller. Normal= ly, +libvirt can automatically infer such controllers without requiring explici= t XML +markup, but sometimes it is necessary to provide an explicit controller el= ement, +notably when planning the `PCI topology `__ for guests w= here +device hotplug is expected. + +:: + + ... + + + + +
    + + + +
    + + + ... + + ... + +Each controller has a mandatory attribute ``type``, which must be one of '= ide', +'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mand= atory +attribute ``index`` which is the decimal integer describing in which order= the +bus controller is encountered (for use in ``controller`` attributes of +``
    `` elements). :since:`Since 1.3.5` the index is optional; if not +specified, it will be auto-assigned to be the lowest unused index for the = given +controller type. Some controller types have additional attributes that con= trol +specific features, such as: + +``virtio-serial`` + The ``virtio-serial`` controller has two additional optional attributes + ``ports`` and ``vectors``, which control how many devices can be connec= ted + through the controller. :since:`Since 5.2.0` , it supports an optional + attribute ``model`` which can be 'virtio', 'virtio-transitional', or + 'virtio-non-transitional'. See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. +``scsi`` + A ``scsi`` controller has an optional attribute ``model``, which is one= of + 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078', + 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitio= nal'. + See `Virtio transitional devices <#elementsVirtioTransitional>`__ for m= ore + details. +``usb`` + A ``usb`` controller has an optional attribute ``model``, which is one = of + "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-u= hci2", + "ich9-uhci3", "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pv= usb + with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu backend, + version 2.0) or "qemu-xhci". Additionally, :since:`since 0.10.0` , if t= he USB + bus needs to be explicitly disabled for the guest, ``model=3D'none'`` m= ay be + used. :since:`Since 1.0.5` , no default USB controller will be built on= s390. + :since:`Since 1.3.5` , USB controllers accept a ``ports`` attribute to + configure how many devices can be connected to the controller. +``ide`` + :since:`Since 3.10.0` for the vbox driver, the ``ide`` controller has an + optional attribute ``model``, which is one of "piix3", "piix4" or "ich6= ". +``xenbus`` + :since:`Since 5.2.0` , the ``xenbus`` controller has an optional attrib= ute + ``maxGrantFrames``, which specifies the maximum number of grant frames = the + controller makes available for connected devices. :since:`Since 6.3.0` = , the + xenbus controller supports the optional ``maxEventChannels`` attribute,= which + specifies maximum number of event channels (PV interrupts) that can be = used + by the guest. + +Note: The PowerPC64 "spapr-vio" addresses do not have an associated contro= ller. + +For controllers that are themselves devices on a PCI or USB bus, an option= al +sub-element ``
    `` can specify the exact relationship of the contro= ller +to its master bus, with semantics `given above <#elementsAddress>`__. + +An optional sub-element ``driver`` can specify the driver specific options: + +``queues`` + The optional ``queues`` attribute specifies the number of queues for the + controller. For best performance, it's recommended to specify a value + matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)` +``cmd_per_lun`` + The optional ``cmd_per_lun`` attribute specifies the maximum number of + commands that can be queued on devices controlled by the host. :since:`= Since + 1.2.7 (QEMU and KVM only)` +``max_sectors`` + The optional ``max_sectors`` attribute specifies the maximum amount of = data + in bytes that will be transferred to or from the device in a single com= mand. + The transfer length is measured in sectors, where a sector is 512 bytes. + :since:`Since 1.2.7 (QEMU and KVM only)` +``ioeventfd`` + The optional ``ioeventfd`` attribute specifies whether the controller s= hould + use `I/O asynchronous handling `__ + or not. Accepted values are "on" and "off". :since:`Since 1.2.18` +``iothread`` + Supported for controller type ``scsi`` using model ``virtio-scsi`` for + ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` .= The + optional ``iothread`` attribute assigns the controller to an IOThread as + defined by the range for the domain + `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk`` + assigned to use the specified ``controller`` will utilize the same IOTh= read. + If a specific IOThread is desired for a specific SCSI ``disk``, then mu= ltiple + controllers must be defined each having a specific ``iothread`` value. = The + ``iothread`` value must be within the range 1 to the domain iothreads v= alue. +virtio options + For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ c= an + also be set. ( :since:`Since 3.5.0` ) + +USB companion controllers have an optional sub-element ```` to spe= cify +the exact relationship of the companion to its master controller. A compan= ion +controller is on the same bus as its master, so the companion ``index`` va= lue +should be equal. Not all controller models can be used as companion contro= llers +and libvirt might provide some sensible defaults (settings of +``master startport`` and ``function`` of an address) for some particular m= odels. +Preferred companion controllers are ``ich-uhci[123]``. + +:: + + ... + + +
    + + + +
    + + ... + + ... + +PCI controllers have an optional ``model`` attribute; possible values for = this +attribute are + +- ``pci-root``, ``pci-bridge`` ( :since:`since 1.0.5` ) +- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` ) +- ``pcie-root-port``, ``pcie-switch-upstream-port``, + ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` ) +- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` ) +- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` ) + +The root controllers (``pci-root`` and ``pcie-root``) have an optional +``pcihole64`` element specifying how big (in kilobytes, or in the unit spe= cified +by ``pcihole64``'s ``unit`` attribute) the 64-bit PCI hole should be. Some +guests (like Windows XP or Windows Server 2003) might crash when QEMU and +Seabios are recent enough to support 64-bit PCI holes, unless this is disa= bled +(set to 0). :since:`Since 1.1.2 (QEMU only)` + +PCI controllers also have an optional subelement ```` with an attri= bute +``name``. The name attribute holds the name of the specific device that qe= mu is +emulating (e.g. "i82801b11-bridge") rather than simply the class of device +("pcie-to-pci-bridge", "pci-bridge"), which is set in the controller eleme= nt's +model **attribute**. In almost all cases, you should not manually add a +```` subelement to a controller, nor should you modify one that is +automatically generated by libvirt. :since:`Since 1.2.19 (QEMU only).` + +PCI controllers also have an optional subelement ```` with the +attributes and subelements listed below. These are configurable items that= 1) +are visible to the guest OS so must be preserved for guest ABI compatibili= ty, +and 2) are usually left to default values or derived automatically by libv= irt. +In almost all cases, you should not manually add a ```` subelement= to a +controller, nor should you modify the values in the those that are automat= ically +generated by libvirt. :since:`Since 1.2.19 (QEMU only).` + +``chassisNr`` + PCI controllers that have attribute model=3D"pci-bridge", can also have= a + ``chassisNr`` attribute in the ```` subelement, which is used to + control QEMU's "chassis_nr" option for the pci-bridge device (normally + libvirt automatically sets this to the same value as the index attribut= e of + the pci controller). If set, chassisNr must be between 1 and 255. +``chassis`` + pcie-root-port and pcie-switch-downstream-port controllers can also hav= e a + ``chassis`` attribute in the ```` subelement, which is used to = set + the controller's "chassis" configuration value, which is visible to the + virtual machine. If set, chassis must be between 0 and 255. +``port`` + pcie-root-port and pcie-switch-downstream-port controllers can also hav= e a + ``port`` attribute in the ```` subelement, which is used to set= the + controller's "port" configuration value, which is visible to the virtual + machine. If set, port must be between 0 and 255. +``hotplug`` + pcie-root-port and pcie-switch-downstream-port controllers can also hav= e a + ``hotplug`` attribute in the ```` subelement, which is used to + disable hotplug/unplug of devices on a particular controller. The defau= lt + setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable + hotplug/unplug of devices on a particular controller. :since:`Since 6.3= .0` +``busNr`` + pci-expander-bus and pcie-expander-bus controllers can have an optional + ``busNr`` attribute (1-254). This will be the bus number of the new bus= ; All + bus numbers between that specified and 255 will be available only for + assignment to PCI/PCIe controllers plugged into the hierarchy starting = with + this expander bus, and bus numbers less than the specified value will be + available to the next lower expander-bus (or the root-bus if there are = no + lower expander buses). If you do not specify a busNumber, libvirt will = find + the lowest existing busNumber in all other expander buses (or use 256 if + there are no others) and auto-assign the busNr of that found bus - 2, w= hich + provides one bus number for the pci-expander-bus and one for the pci-br= idge + that is automatically attached to it (if you plan on adding more pci-br= idges + to the hierarchy of the bus, you should manually set busNr to a lower v= alue). + + A similar algorithm is used for automatically determining the busNr att= ribute + for pcie-expander-bus, but since the pcie-expander-bus doesn't have any + built-in pci-bridge, the 2nd bus-number is just being reserved for the + pcie-root-port that must necessarily be connected to the bus in order to + actually plug in an endpoint device. If you intend to plug multiple dev= ices + into a pcie-expander-bus, you must connect a pcie-switch-upstream-port = to the + pcie-root-port that is plugged into the pcie-expander-bus, and multiple + pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of c= ourse + for this to work properly, you will need to decrease the pcie-expander-= bus' + busNr accordingly so that there are enough unused bus numbers above it = to + accommodate giving out one bus number for the upstream-port and one for= each + downstream-port (in addition to the pcie-root-port and the pcie-expande= r-bus + itself). + +``node`` + Some PCI controllers (``pci-expander-bus`` for the pc machine type, + ``pcie-expander-bus`` for the q35 machine type and, :since:`since 3.6.0= ` , + ``pci-root`` for the pseries machine type) can have an optional ```` + subelement within the ```` subelement, which is used to set the= NUMA + node reported to the guest OS for that bus - the guest OS will then kno= w that + all devices on that bus are a part of the specified NUMA node (it is up= to + the user of the libvirt API to attach host devices to the correct + pci-expander-bus when assigning them to the domain). +``index`` + pci-root controllers for pSeries guests use this attribute to record the + order they will show up in the guest. :since:`Since 3.6.0` + +For machine types which provide an implicit PCI bus, the pci-root controll= er +with index=3D0 is auto-added and required to use PCI devices. pci-root has= no +address. PCI bridges are auto-added if there are too many devices to fit o= n the +one bus provided by pci-root, or a PCI bus number greater than zero was +specified. PCI bridges can also be specified manually, but their addresses +should only refer to PCI buses provided by already specified PCI controlle= rs. +Leaving gaps in the PCI controller indexes might lead to an invalid +configuration. + +:: + + ... + + + +
    + + + ... + +For machine types which provide an implicit PCI Express (PCIe) bus (for ex= ample, +the machine types based on the Q35 chipset), the pcie-root controller with +index=3D0 is auto-added to the domain's configuration. pcie-root has also = no +address, provides 31 slots (numbered 1-31) that can be used to attach PCIe= or +PCI devices (although libvirt will never auto-assign a PCI device to a PCIe +slot, it will allow manual specification of such an assignment). Devices +connected to pcie-root cannot be hotplugged. If traditional PCI devices are +present in the guest configuration, a ``pcie-to-pci-bridge`` controller wi= ll +automatically be added: this controller, which plugs into a ``pcie-root-po= rt``, +provides 31 usable PCI slots (1-31) with hotplug support ( :since:`since 4= .3.0` +). If the QEMU binary doesn't support the corresponding device, then a +``dmi-to-pci-bridge`` controller will be added instead, usually at the def= acto +standard location of slot=3D0x1e. A dmi-to-pci-bridge controller plugs int= o a PCIe +slot (as provided by pcie-root), and itself provides 31 standard PCI slots +(which also do not support device hotplug). In order to have hot-pluggable= PCI +slots in the guest system, a pci-bridge controller will also be automatica= lly +created and connected to one of the slots of the auto-created dmi-to-pci-b= ridge +controller; all guest PCI devices with addresses that are auto-determined = by +libvirt will be placed on this pci-bridge device. ( :since:`since 1.1.2` ). + +Domains with an implicit pcie-root can also add controllers with +``model=3D'pcie-root-port'``, ``model=3D'pcie-switch-upstream-port'``, and +``model=3D'pcie-switch-downstream-port'``. pcie-root-port is a simple type= of +bridge device that can connect only to one of the 31 slots on the pcie-roo= t bus +on its upstream side, and makes a single (PCIe, hotpluggable) port availab= le on +the downstream side (at slot=3D'0'). pcie-root-port can be used to provide= a +single slot to later hotplug a PCIe device (but is not itself hotpluggable= - it +must be in the configuration when the domain is started). ( :since:`since +1.2.19` ) + +pcie-switch-upstream-port is a more flexible (but also more complex) devic= e that +can only plug into a pcie-root-port or pcie-switch-downstream-port on the +upstream side (and only before the domain is started - it is not hot-plugg= able), +and provides 32 ports on the downstream side (slot=3D'0' - slot=3D'31') th= at accept +only pcie-switch-downstream-port devices; each pcie-switch-downstream-port +device can only plug into a pcie-switch-upstream-port on its upstream side +(again, not hot-pluggable), and on its downstream side provides a single +hotpluggable pcie port that can accept any standard pci or pcie device (or +another pcie-switch-upstream-port), i.e. identical in function to a +pcie-root-port. ( :since:`since 1.2.19` ) + +:: + + ... + + + +
    + + +
    + + + ... + +:anchor:`` + +Device leases +~~~~~~~~~~~~~ + +When using a lock manager, it may be desirable to record device leases aga= inst a +VM. The lock manager will ensure the VM won't start unless the leases can = be +acquired. + +:: + + ... + + ... + + somearea + somekey + + + ... + + ... + +``lockspace`` + This is an arbitrary string, identifying the lockspace within which the= key + is held. Lock managers may impose extra restrictions on the format, or = length + of the lockspace name. +``key`` + This is an arbitrary string, uniquely identifying the lease to be acqui= red. + Lock managers may impose extra restrictions on the format, or length of= the + key. +``target`` + This is the fully qualified path of the file associated with the locksp= ace. + The offset specifies where the lease is stored within the file. If the = lock + manager does not require an offset, just pass 0. + +:anchor:`` + +Host device assignment +~~~~~~~~~~~~~~~~~~~~~~ + +:anchor:`` + +USB / PCI / SCSI devices +^^^^^^^^^^^^^^^^^^^^^^^^ + +USB, PCI and SCSI devices attached to the host can be passed through to the +guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.= 6.0 +for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` : + +:: + + ... + + + + + + + + + + ... + +or: + +:: + + ... + + + +
    + + + + + + ... + +or: + +:: + + ... + + + + +
    + + +
    + + + ... + +or: + +:: + + ... + + + + + + + + +
    + + + ... + +or: + +:: + + ... + + + + + + ... + +or: + +:: + + ... + + + +
    + + + + +
    + +
    + + + ... + +``hostdev`` + The ``hostdev`` element is the main container for describing host devic= es. + For each device, the ``mode`` is always "subsystem" and the ``type`` is= one + of the following values with additional attributes noted. + + ``usb`` + USB devices are detached from the host on guest startup and reattach= ed + after the guest exits or the device is hot-unplugged. + ``pci`` + For PCI devices, when ``managed`` is "yes" it is detached from the h= ost + before being passed on to the guest and reattached to the host after= the + guest exits. If ``managed`` is omitted or "no", the user is responsi= ble to + call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before + starting the guest or hot-plugging the device and + ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-= unplug + or stopping the guest. + ``scsi`` + For SCSI devices, user is responsible to make sure the device is not= used + by host. If supported by the hypervisor and OS, the optional ``sgio`= ` ( + :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO + commands are filtered for the disk. Valid settings are "filtered" or + "unfiltered", where the default is "filtered". The optional ``rawio`= ` ( + :since:`since 1.2.9` ) attribute indicates whether the lun needs the= rawio + capability. Valid settings are "yes" or "no". See the rawio descript= ion + within the `disk <#elementsDisks>`__ section. If a disk lun in the d= omain + already has the rawio capability, then this setting not required. + ``scsi_host`` + :since:`since 2.5.0` For SCSI devices, user is responsible to make s= ure + the device is not used by host. This ``type`` passes all LUNs presen= ted by + a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attri= bute + can be specified further with "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. + ``mdev`` + For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute + specifies the device API which determines how the host's vfio driver= will + expose the device to the guest. Currently, ``model=3D'vfio-pci'``, + ``model=3D'vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model=3D'vfio-= ap'`` ( + :since:`Since 4.9.0` ) is supported. `MDEV `__ + section provides more information about mediated devices as well as = how to + create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)= ` an + optional ``display`` attribute may be used to enable or disable supp= ort + for an accelerated remote desktop backed by a mediated device (such = as + NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video + devices <#elementsVideo>`__. This attribute is limited to + ``model=3D'vfio-pci'`` only. Supported values are either ``on`` or `= `off`` + (default is 'off'). It is required to use a `graphical + framebuffer <#elementsGraphics>`__ in order to use this attribute, + currently only supported with VNC, Spice and egl-headless graphics + devices. :since:`Since version 5.10.0` , there is an optional ``ramf= b`` + attribute for devices with ``model=3D'vfio-pci'``. Supported values = are + either ``on`` or ``off`` (default is 'off'). When enabled, this attr= ibute + provides a memory framebuffer device to the guest. This framebuffer = will + be used as a boot display when a vgpu device is the primary display. + + Note: There are also some implications on the usage of guest's addre= ss + type depending on the ``model`` attribute, see the ``address`` eleme= nt + below. + + Note: The ``managed`` attribute is only used with ``type=3D'pci'`` and = is + ignored by all the other device types, thus setting ``managed`` explici= tly + with other than a PCI device has the same effect as omitting it. Simila= rly, + ``model`` attribute is only supported by mediated devices and ignored b= y all + other device types. + +``source`` + The source element describes the device as seen from the host using the + following mechanism to describe: + + ``usb`` + The USB device can either be addressed by vendor / product id using = the + ``vendor`` and ``product`` elements or by the device's address on th= e host + using the ``address`` element. + + :since:`Since 1.0.0` , the ``source`` element of USB devices may con= tain + ``startupPolicy`` attribute which can be used to define policy what = to do + if the specified host USB device is not found. The attribute accepts= the + following values: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + mandatory fail if missing for any reason (the default) + requisite fail if missing on boot up, drop if missing on migrate/res= tore/revert + optional drop if missing at any start attempt + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + + ``pci`` + PCI devices can only be described by their ``address``. + ``scsi`` + SCSI devices are described by both the ``adapter`` and ``address`` + elements. The ``address`` element includes a ``bus`` attribute (a 2-= digit + bus number), a ``target`` attribute (a 10-digit target number), and a + ``unit`` attribute (a 20-digit unit number on the bus). Not all + hypervisors support larger ``target`` and ``unit`` values. It is up = to + each hypervisor to determine the maximum value supported for the ada= pter. + + :since:`Since 1.2.8` , the ``source`` element of a SCSI device may c= ontain + the ``protocol`` attribute. When the attribute is set to "iscsi", th= e host + device XML follows the network `disk <#elementsDisks>`__ device usin= g the + same ``name`` attribute and optionally using the ``auth`` element to + provide the authentication credentials to the iSCSI server. + + ``scsi_host`` + :since:`Since 2.5.0` , multiple LUNs behind a single SCSI HBA are + described by a ``protocol`` attribute set to "vhost" and a ``wwpn`` + attribute that is the vhost_scsi wwpn (16 hexadecimal digits with a = prefix + of "naa.") established in the host configfs. + ``mdev`` + Mediated devices ( :since:`Since 3.2.0` ) are described by the ``add= ress`` + element. The ``address`` element contains a single mandatory attribu= te + ``uuid``. + +``vendor``, ``product`` + The ``vendor`` and ``product`` elements each have an ``id`` attribute t= hat + specifies the USB vendor and product id. The ids can be given in decima= l, + hexadecimal (starting with 0x) or octal (starting with 0) form. +``boot`` + Specifies that the device is bootable. The ``order`` attribute determin= es the + order in which devices will be tried during boot sequence. The per-devi= ce + ``boot`` elements cannot be used together with general boot elements in= `BIOS + bootloader <#elementsOSBIOS>`__ section. :since:`Since 0.8.8` for PCI + devices, :since:`Since 1.0.1` for USB devices. +``rom`` + The ``rom`` element is used to change how a PCI device's ROM is present= ed to + the guest. The optional ``bar`` attribute can be set to "on" or "off", = and + determines whether or not the device's ROM will be visible in the guest= 's + memory map. (In PCI documentation, the "rombar" setting controls the pr= esence + of the Base Address Register for the ROM). If no rom bar is specified, = the + qemu default will be used (older versions of qemu used a default of "of= f", + while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU an= d KVM + only)` . The optional ``file`` attribute contains an absolute path to a + binary file to be presented to the guest as the device's ROM BIOS. This= can + be useful, for example, to provide a PXE boot ROM for a virtual functio= n of + an sr-iov capable ethernet device (which has no boot ROMs for the VFs). + :since:`Since 0.9.10 (QEMU and KVM only)` . The optional ``enabled`` + attribute can be set to ``no`` to disable PCI ROM loading completely fo= r the + device; if PCI ROM loading is disabled through this attribute, attempts= to + tweak the loading process further using the ``bar`` or ``file`` attribu= tes + will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)` . +``address`` + The ``address`` element for USB devices has a ``bus`` and ``device`` + attribute to specify the USB bus and device number the device appears a= t on + the host. The values of these attributes can be given in decimal, hexad= ecimal + (starting with 0x) or octal (starting with 0) form. For PCI devices the + element carries 4 attributes allowing to designate the device as can be= found + with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a '= drive' + address type must be used. For mediated devices, which are software-only + devices defining an allocation of resources on the physical parent devi= ce, + the address type used must conform to the ``model`` attribute of element + ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` devi= ce API + or any address type other than CCW for ``vfio-ccw`` device API will res= ult in + an error. `See above <#elementsAddress>`__ for more details on the addr= ess + element. +``driver`` + PCI devices can have an optional ``driver`` subelement that specifies w= hich + backend driver to use for PCI device assignment. Use the ``name`` attri= bute + to select either "vfio" (for the new VFIO device assignment backend, wh= ich is + compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment + handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU an= d KVM + only, requires kernel 3.6 or newer)` . When specified, device assignmen= t will + fail if the requested method of device assignment isn't available on the + host. When not specified, the default is "vfio" on systems where the VF= IO + driver is available and loaded, and "kvm" on older systems, or those wh= ere + the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that = the + default was always "kvm"). +``readonly`` + Indicates that the device is readonly, only supported by SCSI host devi= ce + now. :since:`Since 1.0.6 (QEMU and KVM only)` +``shareable`` + If present, this indicates the device is expected to be shared between + domains (assuming the hypervisor and OS support this). Only supported b= y SCSI + host device. :since:`Since 1.0.6` + + Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did = not + work as as expected until :since:`1.2.2` . + +:anchor:`` + +Block / character devices +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Block / character devices from the host can be passed through to the guest= using +the ``hostdev`` element. This is only possible with container based +virtualization. Devices are specified by a fully qualified path. :since:`s= ince +after 1.0.1 for LXC` : + +:: + + ... + + + /dev/sdf1 + + + ... + +:: + + ... + + + /dev/input/event3 + + + ... + +:: + + ... + + + eth0 + + + ... + +``hostdev`` + The ``hostdev`` element is the main container for describing host devic= es. + For block/character device passthrough ``mode`` is always "capabilities= " and + ``type`` is "storage" for a block device, "misc" for a character device= and + "net" for a host network interface. +``source`` + The source element describes the device as seen from the host. For block + devices, the path to the block device in the host OS is provided in the + nested "block" element, while for character devices the "char" element = is + used. For network interfaces, the name of the interface is provided in = the + "interface" element. + +:anchor:`` + +Redirected devices +~~~~~~~~~~~~~~~~~~ + +USB device redirection through a character device is supported :since:`sin= ce +after 0.9.5 (KVM only)` : + +:: + + ... + + + + + + + + + + + ... + +``redirdev`` + The ``redirdev`` element is the main container for describing redirected + devices. ``bus`` must be "usb" for a USB device. An additional attribute + ``type`` is required, matching one of the supported `serial + device <#elementsConsole>`__ types, to describe the host side of the tu= nnel; + ``type=3D'tcp'`` or ``type=3D'spicevmc'`` (which uses the usbredir chan= nel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. The redirdev + element has an optional sub-element ``
    `` which can tie the dev= ice to + a particular controller. Further sub-elements, such as ````, ma= y be + required according to the given type, although a ```` sub-eleme= nt is + not required (since the consumer of the character device is the hypervi= sor + itself, rather than a device visible in the guest). +``boot`` + Specifies that the device is bootable. The ``order`` attribute determin= es the + order in which devices will be tried during boot sequence. The per-devi= ce + ``boot`` elements cannot be used together with general boot elements in= `BIOS + bootloader <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` ) +``redirfilter`` + The\ ``redirfilter``\ element is used for creating the filter rule to f= ilter + out certain devices from redirection. It uses sub-element ```` = to + define each filter rule. ``class`` attribute is the USB Class code, for + example, 0x08 represents mass storage devices. The USB device can be + addressed by vendor / product id using the ``vendor`` and ``product`` + attributes. ``version`` is the device revision from the bcdDevice field= (not + the version of the USB protocol). These four attributes are optional and + ``-1`` can be used to allow any value for them. ``allow`` attribute is + mandatory, 'yes' means allow, 'no' for deny. + +:anchor:`` + +Smartcard devices +~~~~~~~~~~~~~~~~~ + +A virtual smartcard device can be supplied to the guest via the ``smartcar= d`` +element. A USB smartcard reader device on the host cannot be used on a gue= st +with simple device passthrough, since it will then not be available on the= host, +possibly locking the host computer when it is "removed". Therefore, some +hypervisors provide a specialized virtual device that can present a smartc= ard +interface to the guest, with several modes for describing how credentials = are +obtained from the host or even a from a channel created to a third-party +smartcard provider. :since:`Since 0.8.8` + +:: + + ... + + + + cert1 + cert2 + cert3 + /etc/pki/nssdb/ + + + + +
    + + + + ... + +The ```` element has a mandatory attribute ``mode``. The follow= ing +modes are supported; in each mode, the guest sees a device on its USB bus = that +behaves like a physical USB CCID (Chip/Smart Card Interface Device) card. + +``host`` + The simplest operation, where the hypervisor relays all requests from t= he + guest into direct access to the host's smartcard via NSS. No other attr= ibutes + or sub-elements are required. See below about the use of an optional + ``
    `` sub-element. +``host-certificates`` + Rather than requiring a smartcard to be plugged into the host, it is po= ssible + to provide three NSS certificate names residing in a database on the ho= st. + These certificates can be generated via the command + ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=3Dcert1 -n c= ert1``, + and the resulting three certificate names must be supplied as the conte= nt of + each of three ```` sub-elements. An additional sub-element + ```` can specify the absolute path to an alternate directory + (matching the ``-d`` option of the ``certutil`` command when creating t= he + certificates); if not present, it defaults to /etc/pki/nssdb. +``passthrough`` + Rather than having the hypervisor directly communicate with the host, i= t is + possible to tunnel all requests through a secondary character device to= a + third-party provider (which may in turn be talking to a smartcard or us= ing + three certificate files). In this mode of operation, an additional attr= ibute + ``type`` is required, matching one of the supported `serial + device <#elementsConsole>`__ types, to describe the host side of the tu= nnel; + ``type=3D'tcp'`` or ``type=3D'spicevmc'`` (which uses the smartcard cha= nnel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. Further + sub-elements, such as ````, may be required according to the gi= ven + type, although a ```` sub-element is not required (since the co= nsumer + of the character device is the hypervisor itself, rather than a device + visible in the guest). + +Each mode supports an optional sub-element ``
    ``, which fine-tunes= the +correlation between the smartcard and a ccid bus controller, `documented +above <#elementsAddress>`__. For now, qemu only supports at most one smart= card, +with an address of bus=3D0 slot=3D0. + +:anchor:`` + +Network interfaces +~~~~~~~~~~~~~~~~~~ + +:: + + ... + + + + + + + + + ... + +There are several possibilities for specifying a network interface visible= to +the guest. Each subsection below provides more details about common setup +options. + +:since:`Since 1.2.10` ), the ``interface`` element property +``trustGuestRxFilters`` provides the capability for the host to detect and= trust +reports from the guest regarding changes to the interface mac address and +receive filters by setting the attribute to ``yes``. The default setting f= or the +attribute is ``no`` for security reasons and support depends on the guest +network device model as well as the type of connection on the host - curre= ntly +it is only supported for the virtio device model and for macvtap connectio= ns on +the host. + +Each ```` element has an optional ``
    `` sub-element tha= t can +tie the interface to a particular pci slot, with attribute ``type=3D'pci'`= ` as +`documented above <#elementsAddress>`__. + +:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC addr= ess +when it's in the reserved VMware range by adding a ``type=3D"static"`` att= ribute +to the ```` element. Note that this attribute is useless if the prov= ided +MAC address is outside of the reserved VMWare ranges. + +:anchor:`` + +Virtual network +^^^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts w= ith +dynamic / wireless networking configs (or multi-host environments where th= e host +hardware details are described separately in a ```` definition +:since:`Since 0.9.4` ).** + +Provides a connection whose details are described by the named network +definition. Depending on the virtual network's "forward mode" configuratio= n, the +network may be totally isolated (no ```` element given), NAT'ing = to an +explicit network device or to the default route (```= `), +routed with no NAT (````), or connected directly = to one +of the host's network interfaces (via macvtap) or bridge devices +((```` :since:`Si= nce +0.9.4` ) + +For networks with a forward mode of bridge, private, vepa, and passthrough= , it +is assumed that the host has any necessary DNS and DHCP services already s= etup +outside the scope of libvirt. In the case of isolated, nat, and routed net= works, +DHCP and DNS are provided on the virtual network by libvirt, and the IP ra= nge +can be determined by examining the virtual network config with +'``virsh net-dumpxml [networkname]``'. There is one virtual network called +'default' setup out of the box which does NAT'ing to the default route and= has +an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an +associated tun device created with a name of vnetN, which can also be over= ridden +with the element (see `overriding the target +element <#elementsNICSTargetOverride>`__). + +When the source of an interface is a network, a ``portgroup`` can be speci= fied +along with the name of the network; one network may have multiple portgrou= ps +defined, with each portgroup containing slightly different configuration +information for different classes of network connections. :since:`Since 0.= 9.4` . + +When a guest is running an interface of type ``network`` may include a +``portid`` attribute. This provides the UUID of an associated virNetworkPo= rtPtr +object that records the association between the domain interface and the +network. This attribute is read-only since port objects are create and del= eted +automatically during startup and shutdown. :since:`Since 5.1.0` + +Also, similar to ``direct`` network connections (described below), a conne= ction +of type ``network`` may specify a ``virtualport`` element, with configurat= ion +data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch ( +:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Sin= ce +0.9.11` ). + +Since the actual type of switch may vary depending on the configuration in= the +```` on the host, it is acceptable to omit the virtualport ``type= `` +attribute, and specify attributes from multiple different virtualport type= s (and +also to leave out certain attributes); at domain startup time, a complete +```` element will be constructed by merging together the type= and +attributes defined in the network and the portgroup referenced by the inte= rface. +The newly-constructed virtualport is a combination of them. The attributes= from +lower virtualport can't make change on the ones defined in higher virtualp= ort. +Interface takes the highest priority, portgroup is lowest priority. ( +:since:`Since 0.10.0` ). For example, in order to work properly with both = an +802.1Qbh switch and an Open vSwitch switch, you may choose to specify no t= ype, +but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfa= ceid`` +(in case the switch is Open vSwitch) (you may also omit the other attribut= es, +such as managerid, typeid, or profileid, to be filled in from the network's +````). If you want to limit a guest to connecting only to cer= tain +types of switches, you can specify the virtualport type, but still omit so= me/all +of the parameters - in this case if the host's network has a different typ= e of +virtualport, connection of the interface will fail. + +:: + + ... + + + + + ... + + + + + + + + + + ... + +:anchor:`` + +Bridge to LAN +^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts w= ith +static wired networking configs.** + +Provides a bridge from the VM directly to the LAN. This assumes there is a +bridge device on the host which has one or more of the hosts physical NICs +attached. The guest VM will have an associated tun device created with a n= ame of +vnetN, which can also be overridden with the element (see `overri= ding +the target element <#elementsNICSTargetOverride>`__). The tun device will = be +attached to the bridge. The IP range / network configuration is whatever i= s used +on the LAN. This provides the guest VM full incoming & outgoing net access= just +like a physical machine. + +On Linux systems, the bridge device is normally a standard Linux host brid= ge. On +hosts that support Open vSwitch, it is also possible to connect to an Open +vSwitch bridge device by adding a ```` = to the +interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type +virtualport accepts two parameters in its ```` element - an +``interfaceid`` which is a standard uuid used to uniquely identify this +particular interface to Open vSwitch (if you do not specify one, a random +interfaceid will be generated for you when you first define the interface)= , and +an optional ``profileid`` which is sent to Open vSwitch as the interfaces +"port-profile". + +:: + + ... + + ... + + + + + + + + + + + + + + + ... + + ... + +On hosts that support Open vSwitch on the kernel side and have the Midonet= Host +Agent configured, it is also possible to connect to the 'midonet' bridge d= evice +by adding a ```` to the interface definitio= n. ( +:since:`Since 1.2.13` ). The Midonet virtualport type requires an +``interfaceid`` attribute in its ```` element. This interface = id is +the UUID that specifies which port in the virtual network topology will be= bound +to the interface. + +:: + + ... + + ... + + + + + + + + + + + + + + + ... + + ... + +:anchor:`` + +Userspace SLIRP stack +^^^^^^^^^^^^^^^^^^^^^ + +Provides a virtual LAN with NAT to the outside world. The virtual network = has +DHCP & DNS services and will give the guest VM addresses starting from +``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server = will +be ``10.0.2.3``. This networking is the only option for unprivileged users= who +need their VMs to have outgoing access. :since:`Since 3.8.0` it is possibl= e to +override the default network address by including an ``ip`` element specif= ying +an IPv4 address in its one mandatory attribute, ``address``. Optionally, a +second ``ip`` element with a ``family`` attribute set to "ipv6" can be spe= cified +to add an IPv6 address to the interface. ``address``. Optionally, address +``prefix`` can be specified. + +:: + + ... + + + ... + + + + + + + ... + +:anchor:`` + +Generic ethernet connection +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Provides a means to use a new or existing tap device (or veth device pair, +depening on the needs of the hypervisor driver) that is partially or wholly +setup external to libvirt (either prior to the guest starting, or while the +guest is being started via an optional script specified in the config). + +The name of the tap device can optionally be specified with the ``dev`` +attribute of the ```` element. If no target dev is specified, libv= irt +will create a new standard tap device with a name of the pattern "vnetN", = where +"N" is replaced with a number. If a target dev is specified and that device +doesn't exist, then a new standard tap device will be created with the exa= ct dev +name given. If the specified target dev does exist, then that existing dev= ice +will be used. Usually some basic setup of the device is done by libvirt, +including setting a MAC address, and the IFF_UP flag, but if the ``dev`` i= s a +pre-existing device, and the ``managed`` attribute of the ``target`` eleme= nt is +also set to "no" (the default value is "yes"), even this basic setup will = not be +performed - libvirt will simply pass the device on to the hypervisor with = no +setup at all. :since:`Since 5.7.0` Using managed=3D'no' with a pre-created= tap +device is useful because it permits a virtual machine managed by an unpriv= ileged +libvirtd to have emulated network devices based on tap devices. + +After creating/opening the tap device, an optional shell script (given in = the +``path`` attribute of the ``