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.

<!-- Xen with fullvirt loader -->
...
<os>
  <type>hvm</type>
  <loader>/usr/lib/xen/boot/hvmloader</loader>
  <boot dev='hd'/>
</os>
...

<!-- QEMU with default firmware, serial console and SMBIOS -->
...
<os>
  <type>hvm</type>
  <boot dev='cdrom'/>
  <bootmenu enable='yes' timeout='3000'/>
  <smbios mode='sysinfo'/>
  <bios useserial='yes' rebootTimeout='0'/>
</os>
...

<!-- QEMU with UEFI manual firmware and secure boot -->
...
<os>
  <type>hvm</type>
  <loader readonly='yes' secure='yes' type='pflash'>/usr/share/OVMF/OVMF_CODE.fd</loader>
  <nvram template='/usr/share/OVMF/OVMF_VARS.fd'>/var/lib/libvirt/nvram/guest_VARS.fd</nvram>
  <boot dev='hd'/>
</os>
...

<!-- QEMU with UEFI manual firmware, secure boot and with NVRAM type 'file'-->
...
<os>
  <type>hvm</type>
  <loader readonly='yes' secure='yes' type='pflash'>/usr/share/OVMF/OVMF_CODE.fd</loader>
  <nvram type='file' template='/usr/share/OVMF/OVMF_VARS.fd'>
    <source file='/var/lib/libvirt/nvram/guest_VARS.fd'/>
  </nvram>
  <boot dev='hd'/>
</os>
...

<!-- QEMU with UEFI manual firmware, secure boot and with network backed NVRAM'-->
...
<os>
  <type>hvm</type>
  <loader readonly='yes' secure='yes' type='pflash'>/usr/share/OVMF/OVMF_CODE.fd</loader>
  <nvram type='network'>
    <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'>
      <host name='example.com' port='6000'/>
      <auth username='myname'>
        <secret type='iscsi' usage='mycluster_myname'/>
      </auth>
    </source>
  </nvram>
  <boot dev='hd'/>
</os>
...

<!-- QEMU with automatic UEFI firmware and secure boot -->
...
<os firmware='efi'>
  <type>hvm</type>
  <loader secure='yes'/>
  <boot dev='hd'/>
</os>
...

<!-- QEMU with automatic UEFI stateless firmware for AMD SEV -->
...
<os firmware='efi'>
  <type>hvm</type>
  <loader stateless='yes'/>
  <boot dev='hd'/>
</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 fulfills 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/Player)

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 referring 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, however, the i686 arch will always be chosen even on an x86_64 host. Since 0.0.1

firmware

Since 7.2.0 QEMU/KVM only

When using firmware auto-selection there are different features enabled in the firmwares. The list of features can be used to limit what firmware should be automatically selected for the VM. The list of features can be specified using zero or more feature elements. Libvirt will take into consideration only the listed features and ignore the rest when selecting the firmware.

feature

The list of mandatory attributes:

• enabled (accepted values are yes and no) is used to tell libvirt if the feature must be enabled or not in the automatically selected firmware

• name the name of the feature, the list of the features:

  • enrolled-keys whether the selected nvram template has default certificate enrolled. Firmware with Secure Boot feature but without enrolled keys will successfully boot non-signed binaries as well. Valid only for firmwares with Secure Boot feature.

  • secure-boot whether the firmware implements UEFI Secure boot feature.

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 to tell the hypervisor that the firmware is capable of Secure Boot feature. It cannot be used to enable or disable the feature itself in the firmware. Since 2.1.0. If the loader is marked as read-only, then with UEFI it is assumed that there will be a writable NVRAM available. In some cases, however, it may be desirable for the loader to run without any NVRAM, discarding any config changes on shutdown. The stateless flag (Since 8.6.0) can be used to control this behaviour, when set to yes NVRAM will never be created.

When firmware autoselection is enabled, the format attribute can be used to tell libvirt to only consider firmware builds that are in a specific format. Supported values are raw and qcow2. Since 9.2.0 (QEMU only)

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 started up libvirt copies so called master NVRAM store file either selected by the firmware autoselection process or defined in qemu.conf. If needed, the template attribute can be used to override the automatically chosen NVRAM template and templateFormat to specify the format for the template file (currently supported are raw and qcow2). When firmware auto-selection is in use the templateFormat field reflects the format of the picked template. Since 10.10.0 (QEMU only)

Note, that for transient domains 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 needed to be persistent). Since 1.2.8

Since 8.5.0, it's possible for the element to have type attribute (accepts values file, block and network) in that case the NVRAM storage is described by a <source> sub-element with the same syntax as disk's source. See Hard drives, floppy disks, CDROMs.

Note: network backed NVRAM the variables are not instantiated from the template and it's user's responsibility to provide a valid NVRAM image.

This element supports a format attribute, which specifies the format of the NVRAM image. Since 9.2.0 (QEMU only)

It is not valid to provide this element if the loader is marked as stateless.

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 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 from 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 Hard drives, floppy disks, CDROMs, Network interfaces, and Host device assignment sections below) were introduced and they are the preferred way providing full control over 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 SMBIOS System Information 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. 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 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 guest startup. The enable attribute can be either "yes" or "no". If not specified, the hypervisor default is used. 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 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. The rebootTimeout attribute (since 0.10.2 (QEMU only)) 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 capability 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=ttyS0 ks=http://example.com/f8-i386/os/</cmdline>
  <dtb>/root/ppc.dtb</dtb>
</os>
...

type

This element has the same semantics as described earlier in the BIOS bootloader section.

loader

This element has the same semantics as described earlier in the BIOS bootloader 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

Container boot¶

When booting a domain using container based virtualization, instead of a kernel / boot image, a path to the init binary is required, using 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 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 + 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='x86_64'>exe</type>
  <init>/bin/systemd</init>
  <initarg>--unit</initarg>
  <initarg>emergency.service</initarg>
  <initenv name='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 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.

<idmap>
  <uid start='0' target='1000' count='10'/>
  <gid start='0' target='1000' count='10'/>
</idmap>

Common <os> element configuration¶

These options apply to any form of booting of the guest OS.

...
<os>
  ...
  <acpi>
    <table type='slic'>/path/to/slic.dat</table>
  </acpi>
</os>
...

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)

ACPI Heterogeneous Memory Attribute Table¶

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

Since 6.6.0 the cell element 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 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 accept two attributes: value and unit which set the value of corresponding cache attribute.

The NUMA description has an optional interconnects element that describes the normalized memory read/write latency, read/write bandwidth 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 node the latency element has optional cache attribute which in combination with target attribute creates full reference to distant NUMA node's cache level. For instance, target='0' cache='1' refers to the first level cache of NUMA node 0.

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='file' snapshot='external'>
    <driver name="tap" type="aio" cache="default"/>
    <source file='/var/lib/xen/images/fv0' startupPolicy='optional'>
      <seclabel relabel='no'/>
    </source>
    <target dev='hda' bus='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='2'/>
    <encryption type='...'>
      ...
    </encryption>
    <shareable/>
    <serial>
      ...
    </serial>
  </disk>
    ...
  <disk type='network'>
    <driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/>
    <source protocol="sheepdog" name="image_name">
      <host name="hostname" port="7000"/>
    </source>
    <target dev="hdb" bus="ide"/>
    <boot order='1'/>
    <transient/>
    <address type='drive' controller='0' bus='1' unit='0'/>
  </disk>
  <disk type='network'>
    <driver name="qemu" type="raw"/>
    <source protocol="rbd" name="image_name2">
      <host name="hostname" port="7000"/>
      <snapshot name="snapname"/>
      <config file="/path/to/file"/>
      <auth username='myuser'>
        <secret type='ceph' usage='mypassid'/>
      </auth>
    </source>
    <target dev="hdc" bus="ide"/>
  </disk>
  <disk type='block' device='cdrom'>
    <driver name='qemu' type='raw'/>
    <target dev='hdd' bus='ide' tray='open'/>
    <readonly/>
  </disk>
  <disk type='network' device='cdrom'>
    <driver name='qemu' type='raw'/>
    <source protocol="http" name="url_path" query="foo=bar&amp;baz=flurb>
      <host name="hostname" port="80"/>
      <cookies>
        <cookie name="test">somevalue</cookie>
      </cookies>
      <readahead size='65536'/>
      <timeout seconds='6'/>
    </source>
    <target dev='hde' bus='ide' tray='open'/>
    <readonly/>
  </disk>
  <disk type='network' device='cdrom'>
    <driver name='qemu' type='raw'/>
    <source protocol="https" name="url_path">
      <host name="hostname" port="443"/>
      <ssl verify="no"/>
    </source>
    <target dev='hdf' bus='ide' tray='open'/>
    <readonly/>
  </disk>
  <disk type='network' device='cdrom'>
    <driver name='qemu' type='raw'/>
    <source protocol="ftp" name="url_path">
      <host name="hostname" port="21"/>
    </source>
    <target dev='hdg' bus='ide' tray='open'/>
    <readonly/>
  </disk>
  <disk type='network' device='cdrom'>
    <driver name='qemu' type='raw'/>
    <source protocol="ftps" name="url_path">
      <host name="hostname" port="990"/>
    </source>
    <target dev='hdh' bus='ide' tray='open'/>
    <readonly/>
  </disk>
  <disk type='network' device='cdrom'>
    <driver name='qemu' type='raw'/>
    <source protocol="tftp" name="url_path">
      <host name="hostname" port="69"/>
    </source>
    <target dev='hdi' bus='ide' tray='open' rotation_rate='7200'/>
    <readonly/>
  </disk>
  <disk type='block' device='lun'>
    <driver name='qemu' type='raw'/>
    <source dev='/dev/sda'>
      <slices>
        <slice type='storage' offset='12345' size='123'/>
      </slices>
      <reservations managed='no'>
        <source type='unix' path='/path/to/qemu-pr-helper' mode='client'/>
      </reservations>
    </source>
    <target dev='sda' bus='scsi' rotation_rate='1'/>
    <address type='drive' controller='0' bus='0' target='3' unit='0'/>
  </disk>
  <disk type='block' device='disk'>
    <driver name='qemu' type='raw'/>
    <source dev='/dev/sda'/>
    <geometry cyls='16383' heads='16' secs='63' trans='lba'/>
    <blockio logical_block_size='512' physical_block_size='4096' discard_granularity='4096'/>
    <target dev='hdj' bus='ide'/>
  </disk>
  <disk type='volume' device='disk'>
    <driver name='qemu' type='raw'/>
    <source pool='blk-pool0' volume='blk-pool0-vol0'/>
    <target dev='hdk' bus='ide'/>
  </disk>
  <disk type='network' device='disk'>
    <driver name='qemu' type='raw'/>
    <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'>
      <host name='example.com' port='3260'/>
      <auth username='myuser'>
        <secret type='iscsi' usage='libvirtiscsi'/>
      </auth>
    </source>
    <target dev='vda' bus='virtio'/>
  </disk>
  <disk type='network' device='lun'>
    <driver name='qemu' type='raw'/>
    <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/1'>
      <host name='example.com' port='3260'/>
      <auth username='myuser'>
        <secret type='iscsi' usage='libvirtiscsi'/>
      </auth>
    </source>
    <target dev='sdb' bus='scsi'/>
  </disk>
  <disk type='network' device='disk'>
    <driver name='qemu' type='raw'/>
    <source protocol='nfs' name='PATH'>
      <host name='example.com'/>
      <identity user='USER' group='GROUP'/>
    </source>
    <target dev='vda' bus='virtio'/>
  </disk>
  <disk type='network' device='lun'>
    <driver name='qemu' type='raw'/>
    <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'>
      <host name='example.com' port='3260'/>
      <initiator>
        <iqn name='iqn.2013-07.com.example:client'/>
      </initiator>
    </source>
    <target dev='sdb' bus='scsi'/>
  </disk>
  <disk type='dir' device='floppy'>
    <driver name='qemu' type='fat'/>
    <source dir='/var/somefiles'>
    <target dev='fda'/>
    <readonly/>
  </disk>
  <disk type='volume' device='disk'>
    <driver name='qemu' type='raw'/>
    <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/>
    <target dev='vdb' bus='virtio'/>
  </disk>
  <disk type='volume' device='disk'>
    <driver name='qemu' type='raw'/>
    <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/>
    <target dev='vdc' bus='virtio'/>
  </disk>
  <disk type='file' device='disk'>
    <driver name='qemu' type='qcow2' queues='4' queue_size='256' />
    <source file='/var/lib/libvirt/images/domain.qcow'/>
    <backingStore type='file'>
      <format type='qcow2'/>
      <source file='/var/lib/libvirt/images/snapshot.qcow'/>
      <backingStore type='block'>
        <format type='raw'/>
        <source dev='/dev/mapper/base'/>
        <backingStore/>
      </backingStore>
    </backingStore>
    <target dev='vdd' bus='virtio'/>
  </disk>
  <disk type='nvme' device='disk'>
    <driver name='qemu' type='raw'/>
    <source type='pci' managed='yes' namespace='1'>
      <address domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
    </source>
    <target dev='vde' bus='virtio'/>
  </disk>
  <disk type='vhostuser' device='disk'>
    <driver name='qemu' type='raw'/>
    <source type='unix' path='/tmp/vhost-blk.sock'>
      <reconnect enabled='yes' timeout='10'/>
    </source>
    <target dev='vdf' bus='virtio'/>
  </disk>
  <disk type='vhostvdpa' device='disk'>
    <driver name='qemu' type='raw'/>
    <source dev='/dev/vhost-vdpa-0' />
    <target dev='vdg' bus='virtio'/>
  </disk>
  <disk type='file' device='disk'>
    <driver name='qemu' type='qcow2'/>
    <source file='/path/to/datastore.qcow2'>
      <dataStore type='file'>
        <format type='raw'/>
        <source file='/path/to/datastore'/>
      <dataStore/>
    </source>
    <backingStore type='file'>
      <format type='qcow2'/>
      <source file='/var/lib/libvirt/images/base-with-data-file.qcow'>
        <dataStore type='block'>
          <format type='raw'/>
          <source dev='/dev/mapper/base2'/>
        <dataStore/>
      </source>
    </backingStore>
    <target dev='vdh' bus='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 ), or "vhostuser" ( since 7.1.0 ), or "vhostvdpa" ( since 9.8.0 (QEMU 8.1.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. Possible 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='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 SCSI commands from the guest are accepted and passed through to the physical device. Also note that device='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='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 further with "virtio", "virtio-transitional" or "virtio-non-transitional". See virtio device models 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='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, current QEMU implementation gives the domain process broader capability than that (per-process basis, affects all the domain disks). 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 'lun'. The attribute exists Since 1.0.2, although currently it's no longer supported by any hypervisor.

snapshot

Indicates the default behavior of the disk during disk snapshots: internal requires a file format such as qcow2 that can store both the snapshot and the data changes since the snapshot; external will separate the snapshot from the live data; no means the disk will not participate in snapshots; and manual allows snapshotting done via an unmanaged storage provider. Read-only disks default to no, while the default for other disks depends on the hypervisor's capabilities. 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

Since 9.0.0 a new optional attribute fdgroup can be added instructing to access the disk via file descriptors associated to the domain object via the virDomainFDAssociate() API rather than opening the files. The files do not necessarily have to be accessible by libvirt via the filesystem. The filename passed via file can still be used to generate paths to write into image metadata when doing block operations but libvirt will not access these natively.

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

Note that most hypervisors that support dir disks do that by exposing an emulated block device with an emulated filesystem populated with contents of the configured directory. As guest operating system may cache the filesystem metadata, outside changes to the directory may not appear in the guest and/or may result in corrupted data being observable from the VM.

The format of the emulated filesystem is controlled by the format attribute of the <driver> driver element. Currently only the fat format is supported. Hypervisors may only support <readonly/> mode.

network

The protocol attribute specifies the protocol to access to the requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdog", "gluster", "vxhs", "nfs", "http", "https", "ftp", ftps", "tftp", or "ssh".

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. 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 controlled on the host by the nbd_tls and nbd_tls_x509_cert_dir in /etc/libvirt/qemu.conf. ('tls' Since 4.5.0 ) Since 8.2.0 the optional attribute tlsHostname can be used to override the expected host name of the NBD server used for TLS certificate verification.

For protocols http and https an optional attribute query specifies the query string. ( Since 6.2.0 )

For "iscsi" ( since 1.0.4 ), the name attribute may include 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 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 (managed by libvirt) used as the disk source. The value for the volume attribute will be the output from the "Name" 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 use the storage pool's source element host attribute as the disk source to generate the libiscsi URI (e.g. 'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1'). Using "host" as the mode value indicates to use the LUN's path as it shows up on host (e.g. 'file=/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 domain. According to NVMe standard, namespace numbers start from 1, including.

The difference between <disk type='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='block'> and therefore lower latencies can be achieved.

vhostuser

Enables the hypervisor to connect to another process using vhost-user protocol. Requires shared memory configured for the VM, for more details see access mode for memoryBacking element (See Memory Backing).

The source element has following mandatory attributes:

type

The type of char device. Currently only unix type is supported.

path

Path to the unix socket to be used as disk source.

Note that the vhost server replaces both the disk frontend and backend thus almost all of the disk properties can't be configured via the <disk> XML for this disk type. Additionally features such as blockjobs, incremental backups and snapshots are not supported for this disk type.

vhostvdpa

Enables the hypervisor to connect to a vDPA block device. Requires shared memory configured for the VM, for more details see access mode for memoryBacking element (See Memory Backing).

The source element has a mandatory attribute dev that specifies the fully-qualified path to the vhost-vdpa character device (e.g. /dev/vhost-vdpa-0).

With "file", "block", and "volume", one or more optional sub-elements seclabel (See Security label) 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). since 0.9.9

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 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 host element supports 4 attributes, viz. "name", "port", "transport" and "socket", which specify the hostname, the port number, transport type and path to socket, respectively. The meaning of this element and the number of the elements depend 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:7000)	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
nfs	a server running Network File System	only one ( Since 7.0.0 )	must be omitted

gluster supports "tcp", "rdma", "unix" as valid values for the transport 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. nfs only supports the use of a "tcp" transport, and does not support using a port at all so it must be omitted.

snapshot

The name attribute of snapshot element can optionally specify an internal snapshot name to be used as the source for storage protocols. Supported for 'rbd' 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 1.2.11 (QEMU only).

auth

Since 3.9.0, the auth element is supported for a disk type "network" that is using a source element with the protocol attributes "rbd", "iscsi", or "ssh". 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 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 is no longer supported for use with disk images. ( Since 4.5.0 )

reservations

Since 4.4.0, the reservations can be a sub-element 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 manages any resources needed. When the persistent reservations are unmanaged, then the hypervisor acts as a client and the path 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 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='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 6.1.0

ssl

For https and ftps accessed storage it's possible to tweak the SSL transport parameters with this element. 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

The readahead element has a size attribute which specifies the size of the readahead buffer in bytes for protocols which support it. Note that '0' is considered as if the value is not provided. Since 6.2.0

timeout

The timeout element has a seconds attribute which specifies the connection timeout in seconds for protocols which support it. Note that '0' is considered as if the value is not provided. Since 6.2.0

identity

When using an nfs protocol, this is used to provide information on the configuration of the user and group. The element has two attributes, user and group. The user can provide these elements as user or group strings, or as user and group ID numbers directly if the string is formatted using a "+" at the beginning of the ID number. If either of these attributes is omitted, then that field is assumed to be the default value for the current system. If both user and group are intended to be default, then the entire element may be omitted.

When using an ssh protocol, this element is used to enable authentication via ssh keys. In this configuration, the element has three possible attributes. The username attribute is required and specifies the name of the user on the remote server. ssh keys can be specified in one of two ways. The first way is by adding them to an ssh-agent and providing the path to the ssh-agent socket in the agentsock attribute. This method works for ssh keys with or without password protection. Alternatively, for ssh keys without a password, the ssh key can be specified directly by setting the keyfile attribute.

reconnect

For disk type vhostuser configures reconnect timeout if the connection is lost. This is set with the two mandatory attributes enabled and timeout. For disk type network and protocol nbd the QEMU NBD reconnect delay can be set via attribute delay:

enabled

If the reconnect feature is enabled, accepts yes and no

timeout

The amount of seconds after which hypervisor tries to reconnect.

delay

Only for NBD hosts. The amount of seconds during which all requests are paused and will be rerun after a successful reconnect. After that time, any delayed requests and all future requests before a successful reconnect will immediately fail. If not set the default QEMU value is 0.

knownHosts

For storage accessed via the ssh protocol, this element configures a path to a file that will be used to verify the remote host. This file must contain the expected host key for the remote host or the connection will fail. The location of the file is specified via the path attribute. Since 9.8.0

dataStore

This element describes external data store, which is storage holding the actual data blocks of the given storage image. In such case the disk source image holds only the metadata. This feature is currently supported only by the qcow2 format. Since 10.10.0

The following attribute is supported in dataStore:

type

The type attribute represents the type of storage used by the data store, see disk type attribute above for more details and possible values.

Moreover, dataStore supports the following sub-elements:

format

The format element contains type attribute which specifies the internal format of the data store. Only raw value is supported.

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 data store.

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 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 guest cold bootup, if a certain disk is not accessible or its disk chain is broken, with startupPolicy 'optional' the guest will drop this disk. 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 used 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 when doing block operations (such as via the virDomainBlockRebase API). For example, vda[2] refers to the backing store with index='2' of the disk with vda target.

Moreover, backingStore supports the following sub-elements:

format

The format element contains type attribute which specifies the internal format of the backing store, such as raw or qcow2.

The format element can contain metadata_cache subelement, which has identical semantics to the identically named subelement of driver of a disk.

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, 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 optional attribute tray indicates the tray status of the removable disks (i.e. CDROM or Floppy disk), the value can be either "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 or SCSI disks, and its value can be either "on" or "off", defaulting to "off". The optional attribute rotation_rate sets the rotation rate of the storage for disks on a SCSI, IDE, or SATA bus. Values in the range 1025 to 65534 are used to indicate rotational media speed in revolutions per minute. A value of one is used to indicate solid state, or otherwise non-rotational, storage. These values are not required to match the values of the underlying host storage. 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; "rotation_rate" attribute value since 7.3.0

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 (See Block I/O Tuning), 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 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 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 ability 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" (since 0.9.5; like "writethrough", but it bypasses the host page cache) and "unsafe" (since 0.9.7; host may cache all disk io, and sync requests from guest are ignored). Since 0.6.0

• The optional error_policy attribute controls how the hypervisor will behave on a disk read or write error, possible values are "stop", "report" (since 0.9.7), "ignore", and "enospace". The default is left to the discretion of the hypervisor. Since 0.8.0.

• The optional rerror_policy attribute controls behavior for read errors only. 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. Since 0.9.7

• 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 whether 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 based 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. (See IOThreads Allocation). 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 "virtio" bus and "pci" or "ccw" address types. Since 1.2.8 (QEMU 2.1) Note: iothread is mutually exclusive with iothreads.

• The optional iothreads sub-element allows specifying multiple IOThreads via the iothread sub-element with attribute id the disk will use for I/O operations. Optionally the iothread element can have multiple queue subelements specifying that given iothread should be used to handle given queues. Since 10.0.0 (QEMU 9.0, virtio disks only). Example:

  <driver name='qemu' queues='3'>
    <iothreads>
      <iothread id='2'>
        <queue id='1'/>
      </iothread>
      <iothread id='3'>
        <queue id='0'/>
        <queue id='2'/>
      </iothread>
    </iothreads>
  </driver>

• The optional queues attribute specifies the number of virt queues for virtio-blk ( Since 3.9.0 ) or vhost-user-blk ( Since 7.1.0 )

• The optional queue_size attribute specifies the size of each virt queue for virtio-blk or vhost-user-blk. ( Since 7.8.0 )

• For virtio disks, Virtio-related options can also be set. ( Since 3.5.0 )

• The optional metadata_cache subelement controls aspects related to the format specific caching of storage image metadata. Note that this setting applies only on the top level image; the identically named subelement of backingStore's format element can be used to specify cache settings for the backing image.

  Since 7.0.0 the maximum size of the metadata cache of qcow2 format driver of the qemu hypervisor can be controlled via the max_size subelement (see example below).

  The optional discard_no_unref attribute can be set to control the way the qemu hypervisor handles guest discard commands inside the qcow2 image. When enabled, a discard request from within the guest will mark the qcow2 cluster as zero, but will keep the reference/offset of that cluster. But it will still pass the discard further to the lower layer. This will resolve fragmentation within the qcow2 image. Since 9.5.0 (QEMU 8.1)

  In the majority of cases the default configuration used by the hypervisor is sufficient so modifying this setting should not be necessary. For specifics on how the metadata cache of qcow2 in qemu behaves refer to the qemu qcow2 cache docs

  Example:

  <disk type='file' device='disk'>
    <driver name='qemu' type='qcow2'>
      <metadata_cache>
        <max_size unit='bytes'>1234</max_size>
      </metadata_cache>
    </driver>
    <source file='/var/lib/libvirt/images/domain.qcow'/>
    <backingStore type='file'>
      <format type='qcow2'>
        <metadata_cache>
          <max_size unit='bytes'>1234</max_size>
        </metadata_cache>
      </format>
      <source file='/var/lib/libvirt/images/snapshot.qcow'/>
      <backingStore/>
    </backingStore>
    <target dev='vdd' bus='virtio'/>
  </disk>

backenddomain

The optional backenddomain element allows specifying 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 during boot sequence. On the S390 architecture only the first boot device is used. The optional loadparm attribute is an 8 character 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

since:Since 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 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='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, snapshots, or blockjobs. Only supported in vmx hypervisor (Since 0.9.5) and qemu hypervisor (Since 6.9.0).

In cases where the source image of the <transient/> disk is supposed to be shared between multiple concurrently running VMs the optional shareBacking attribute should be set to yes. Note that hypervisor drivers may need to hotplug such disk and thus it works only with configurations supporting hotplug. Since 7.4.0

Hypervisors may need to store a temporary file containing the data written by the domain while running, which may be stored in the same location as the original source of the disk (The qemu driver stores the temporary files as $(origsource).TRANSIENT-$(vmname), where $(origsource) is the full original path of the disk source and $(vmname) is the name of the domain).

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

Note that depending on hypervisor and device type the serial number may be truncated silently. IDE/SATA devices are commonly limited to 20 characters. SCSI devices depending on hypervisor version are limited to 20, 36 or 247 characters.

Hypervisors may also start rejecting overly long serials instead of truncating them in the future so it's advised to avoid the implicit truncation by testing the desired serial length range with the desired device and hypervisor combination.

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 be explicitly specified. See Controllers). 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 (since 0.9.7). Multifunction defaults to 'off'. For a "drive" controller, additional attributes controller, bus, target (since 0.9.11), and unit are available, each defaulting to 0.

auth

Since 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. Since 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. 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 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.

discard_granularity

The smallest amount of data that can be discarded in a single operation. It impacts the unmap operations and it must be a multiple of a logical_block_size. This is usually properly configured by the hypervisor.

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='template'>
    <source name='my-vm-template'/>
    <target dir='/'/>
  </filesystem>
  <filesystem type='mount' accessmode='passthrough' multidevs='remap'>
    <driver type='path' wrpolicy='immediate'/>
    <source dir='/export/to/guest'/>
    <target dir='/import/from/host'/>
    <readonly/>
  </filesystem>
  <filesystem type='mount' accessmode='mapped' fmode='644' dmode='755'>
    <driver type='path'/>
    <source dir='/export/to/guest'/>
    <target dir='/import/from/host'/>
    <readonly/>
  </filesystem>
  <filesystem type='file' accessmode='passthrough'>
    <driver type='loop' format='raw'/>
    <source file='/export/to/guest.img'/>
    <target dir='/import/from/host'/>
    <readonly/>
  </filesystem>
  <filesystem type='mount' accessmode='passthrough'>
      <driver type='virtiofs' queue='1024'/>
      <binary path='/usr/libexec/virtiofsd' xattr='on'>
         <cache mode='always'/>
         <sandbox mode='namespace'/>
         <lock posix='on' flock='on'/>
         <thread_pool size='16'/>
      </binary>
      <source dir='/path'/>
      <target dir='mount_tag'/>
      <idmap>
          <uid start='0' target='100000' count='65535'/>
          <gid start='0' target='100000' count='65535'/>
      </idmap>
  </filesystem>
  <filesystem type='mount'>
      <driver type='virtiofs' queue='1024'/>
      <source socket='/tmp/sock'/>
      <target dir='tag'/>
  </filesystem>
  <filesystem type='mount'>
      <driver type='mtp'/>
      <source dir='/export/to/guest'/>
      <target dir='mtptag'/>
  </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='path' or type='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='virtiofs' is also supported. Using virtiofs requires setting up shared memory, see the guide: Virtiofs

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='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", "virtio-transitional" or "virtio-non-transitional". See virtio device models for more details.

The filesystem element has optional attributes fmode and dmode. These two attributes control the creation mode for files and directories when used with the mapped value for accessmode (since 6.10.0, requires QEMU 2.10 ). If not specified, QEMU creates files with mode 600 and directories with mode 700. The setuid, setgid, and sticky bit are unsupported.

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 are:

default

Use QEMU's default setting (which currently is warn).

remap

This setting allows guest to access multiple devices per export without encountering misbehaviours. Inode numbers from host are automatically 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 access 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, 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 misbehaviours 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.

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-related options can also be set. ( 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 6.2.0 )

• QEMU supports mtp which exposes a virtual USB MTP device to the guest. ( Since 10.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 to the daemon. Attribute xattr enables 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 6.2.0 ) The sandboxing method used by virtiofsd can be configured with the sandbox element, possible mode values being namespace and chroot, see the virtiofsd documentation for more details. ( Since 7.2.0 ) Element thread_pool accepts one attribute size which defines the maximum thread pool size. A value of "0" disables the pool. The thread pool helps increase the number of requests in flight when used with storage that has a higher latency. However, it has an overhead, and so for fast, low latency filesystems, it may be best to turn it off. ( Since 8.5.0 ) Element openfiles accepts one attribute max which defines the maximum number of file descriptors. Non-positive values are forbidden. The upper bound on the number of open files is implementation defined. ( Since 10.6.0 )

source

The resource on the host that is being accessed in the guest. The name attribute must be used with type='template', and the dir attribute must be used with type='mount'. For virtiofs, the socket attribute can be used to connect to a virtiofsd daemon launched outside of libvirt. In that case, the target element does not apply and neither do most virtiofs-related options, since they are controlled by virtiofsd, not libvirtd. The usage attribute is used with type='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.

idmap

For virtiofs, an idmap element can be specified to map IDs in the user namespace. See the Container boot section for the syntax of the element. Since 10.0.0

readonly

Enables exporting filesystem as a readonly mount for guest, by default read-write access is given (currently only works for QEMU/KVM driver; not with virtiofs).

space_hard_limit

Maximum space available to this guest's filesystem. Since 0.9.13 Only supported by the OpenVZ driver.

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. Afterwards the hard limit is enforced. Since 0.9.13 Only supported by the OpenVZ driver.

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='drive', while a <console> device would use type='pci' on i686 or x86_64 guests, or type='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='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=0xfe and ssid=0. 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='unassigned'/> 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. <address type='unassigned'/> is an invalid address type for all other device types. Since 6.0.0

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 support (see IOMMU devices). 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)

This optional attribute page_per_vq controls the layout of the notification capabilities exposed to the guest. When enabled, each virtio queue will have a dedicated page on the device BAR exposed to the guest. It is recommended to be used when vDPA is enabled on the hypervisor, as it enables mapping the notification area to the physical device, which is only supported in page granularity. The default is determined by QEMU. Since 7.9.0 (QEMU 2.8) Note: In general you should leave this option alone, unless you are very certain you know what you are doing.

Virtio device models¶

Virtio devices come in several variants, some of which are only applicable to certain machine types or scenarios. The variant can be chosen via the model attribute, which supports the following values:

virtio

This is the recommended choice in the absence of guest OS specific constraints, as it will will generally work correctly across a large range of architectures, machine types and libvirt versions.

Since 5.2.0, the following values can additionally be used with machine types based on PCI (either conventional PCI or PCI Express):

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.

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

• for SCSI controllers, there is no virtio model available due to historical reasons: use virtio-scsi instead, which behaves the same as virtio does for other devices. Both virtio-transitional and virtio-non-transitional work with SCSI controllers;

• 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 device.

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='ide' index='0'/>
  <controller type='virtio-serial' index='0' ports='16' vectors='4'/>
  <controller type='virtio-serial' index='1'>
    <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
  </controller>
  <controller type='scsi' index='0' model='virtio-scsi'>
    <driver iothread='4'/>
    <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/>
  </controller>
  <controller type='xenbus' maxGrantFrames='64' maxEventChannels='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 device models 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', 'ncr53c90' (as builtin implicit controller only), 'am53c974', 'dc390'. See virtio device models 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='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 described in the Device Addresses section.

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 maximum 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 maximum amount of data in bytes that will be transferred to or from the device in a single command. The transfer length is measured in sectors, where 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 (See IOThreads Allocation). Each SCSI disk assigned to use the specified controller will utilize the same IOThread. If a specific 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-related 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='usb' index='0' model='ich9-ehci1'>
    <address type='pci' domain='0' bus='0' slot='4' function='7'/>
  </controller>
  <controller type='usb' index='0' model='ich9-uhci1'>
    <master startport='0'/>
    <address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/>
  </controller>
  ...
</devices>
...

PCI controllers have an optional model attribute; possible 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 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 disabled (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="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

pci-root (Since 7.9.0), pcie-root-port (Since 6.3.0) and pcie-switch-downstream-port controllers (Since 6.3.0) can also have a hotplug attribute in the <target> subelement, which is used to disable hotplug/unplug of devices on a particular controller. For the pci-root controller, the setting affects the ACPI based hotplug. For the rest, the setting affects both ACPI based hotplug as well as PCIE native hotplug. The default setting of hotplug is on; it should be set to off to disable hotplug/unplug of devices on a particular controller.

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

memReserve

Some PCI devices have non-prefetchable memory bar larger than 2MiB. Use this attribute to override value computed by firmware and thus make controller reserve more memory (in KiB) so that such PCI device can be hot plugged. For cold plugged PCI devices, the firmware will automatically reserve the correct amount of memory. Since 10.3.0

For machine types which provide an implicit PCI bus, the pci-root controller with index=0 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 on 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 controllers. Leaving gaps in the PCI controller indexes might lead to an invalid configuration.

...
<devices>
  <controller type='pci' index='0' model='pci-root'/>
  <controller type='pci' index='1' model='pci-bridge'>
    <address type='pci' domain='0' bus='0' slot='5' function='0' multifunction='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=0 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 QEMU 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=0x1e. 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='pcie-root-port', model='pcie-switch-upstream-port', and model='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-root bus on its upstream side, and makes a single (PCIe, hotpluggable) port available on the downstream side (at slot='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='0' - slot='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='pci' index='0' model='pcie-root'/>
  <controller type='pci' index='1' model='pcie-root-port'>
    <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/>
  </controller>
  <controller type='pci' index='2' model='pcie-to-pci-bridge'>
    <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
  </controller>
</devices>
...

Device leases¶

When using a lock manager, it may be desirable to record device leases 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='/some/lease/path' offset='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¶

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

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

...
<devices>
  <hostdev mode='subsystem' type='scsi' rawio='yes'>
    <source>
      <adapter name='scsi_host0'/>
      <address bus='0' target='0' unit='0'/>
    </source>
    <readonly/>
    <address type='drive' controller='0' bus='0' target='0' unit='0'/>
  </hostdev>
</devices>
...

...
<devices>
  <hostdev mode='subsystem' type='scsi'>
    <source protocol='iscsi' name='iqn.2014-08.com.example:iscsi-nopool/1'>
      <host name='example.com' port='3260'/>
      <auth username='myuser'>
        <secret type='iscsi' usage='libvirtiscsi'/>
      </auth>
      <initiator>
        <iqn name='iqn.2020-07.com.example:test'/>
      </initiator>
    </source>
    <address type='drive' controller='0' bus='0' target='0' unit='0'/>
  </hostdev>
</devices>
...

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

...
<devices>
  <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
  <source>
    <address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'/>
  </source>
  </hostdev>
  <hostdev mode='subsystem' type='mdev' model='vfio-ccw'>
    <source>
      <address uuid='9063cba3-ecef-47b6-abcf-3fef4fdcad85'/>
    </source>
  <address type='ccw' cssid='0xfe' ssid='0x0' devno='0x0001'/>
  </hostdev>
</devices>
...

...
<hostdev mode='capabilities' type='storage'>
  <source>
    <block>/dev/sdf1</block>
  </source>
</hostdev>
...

...
<hostdev mode='capabilities' type='misc'>
  <source>
    <char>/dev/input/event3</char>
  </source>
</hostdev>
...

...
<hostdev mode='capabilities' type='net'>
  <source>
    <interface>eth0</interface>
  </source>
</hostdev>
...

Redirected devices¶

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

...
<devices>
  <redirdev bus='usb' type='spicevmc'/>
  <redirdev bus='usb' type='tcp'>
    <source mode='connect' host='localhost' service='4000'/>
    <boot order='1'/>
  </redirdev>
  <redirfilter>
    <usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/>
    <usbdev allow='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 (See Consoles, serial, parallel & channel devices), to describe the host side of the tunnel; type='tcp' or type='spicevmc' (which uses the usbredir channel of a SPICE graphics device (See Graphical framebuffers)) 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-element 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

Theredirfilterelement is used for creating the filter rule to filter out certain devices from redirection. It uses sub-element <usbdev> 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.

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

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=cert1 -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 (See Consoles, serial, parallel & channel devices), to describe the host side of the tunnel; type='tcp' or type='spicevmc' (which uses the smartcard channel of a SPICE graphics device (See Graphical framebuffers)) 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> (See Device Addresses), which fine-tunes the correlation between the smartcard and a ccid bus controller. For now, qemu only supports at most one smartcard, with an address of bus=0 slot=0.

Network interfaces¶

...
<devices>
  <interface type='direct' trustGuestRxFilters='yes'>
    <source dev='eth0'/>
    <mac address='52:54:00:5d:c7:9e'/>
    <boot order='1'/>
    <rom bar='off'/>
    <acpi index='4'/>
  </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='pci' as documented in the Device Addresses section.

Since 6.6.0, one can force libvirt to keep the provided MAC address when it's in the reserved VMware range by adding a type="static" attribute to the <mac/> element. Note that this attribute is useless if the provided MAC address is outside of the reserved VMWare ranges.

Since 7.3.0, one can set the ACPI index against network interfaces. With some operating systems (eg Linux with systemd), the ACPI index is used to provide network interface device naming, that is stable across changes in PCI addresses assigned to the device. This value is required to be unique across all devices and be between 1 and (16*1024-1).

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

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

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

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

...
<devices>
  ...
  <interface type='user'>
    <backend type='passt' logFile='/run/user/$UID/passt-domain.log'/>
    <mac address="00:11:22:33:44:55"/>
    <source dev='eth0'/>
    <ip family='ipv4' address='172.17.2.4' prefix='24'/>
    <ip family='ipv6' address='2001:db8:ac10:fd01::20'/>
    <portForward proto='tcp'>
      <range start='2022' to='22'/>
    </portForward>
    <portForward proto='udp' address='1.2.3.4'>
      <range start='5000' end='5020' to='6000'/>
      <range start='5010' end='5015' exclude='yes'/>
    </portForward>
    <portForward proto='tcp' address='2001:db8:ac10:fd01::1:10' dev='eth0'>
      <range start='80'/>
      <range start='443' to='344'/>
    </portForward>
  </interface>
</devices>
...

...
<devices>
  <interface type='ethernet'>
    <script path='/etc/qemu-ifup-mynet'/>
    <downscript path='/etc/qemu-ifdown-mynet'/>
  </interface>
  ...
  <interface type='ethernet'>
    <target dev='mytap1' managed='no'/>
    <model type='virtio'/>
  </interface>
</devices>
...

...
<devices>
  ...
  <interface type='direct' trustGuestRxFilters='no'>
    <source dev='eth0' mode='vepa'/>
  </interface>
</devices>
...

...
<devices>
  ...
  <interface type='direct'>
    <source dev='eth0.2' mode='vepa'/>
    <virtualport type="802.1Qbg">
      <parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
    </virtualport>
  </interface>
</devices>
...

...
<devices>
  ...
  <interface type='direct'>
    <source dev='eth0' mode='private'/>
    <virtualport type='802.1Qbh'>
      <parameters profileid='finance'/>
    </virtualport>
  </interface>
</devices>
...

...
<devices>
  <interface type='hostdev' managed='yes'>
    <source>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
    </source>
    <mac address='52:54:00:6d:90:02'/>
    <virtualport type='802.1Qbh'>
      <parameters profileid='finance'/>
    </virtualport>
  </interface>
</devices>
...

...
<devices>
  <interface type='vdpa'>
    <source dev='/dev/vhost-vdpa-0'/>
  </interface>
</devices>
...

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

...
  <interface type='hostdev'>
    <source>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
    </source>
    <mac address='00:11:22:33:44:55'/>
    <teaming type='transient' persistent='ua-backup0'/>
  </interface>
...

...
  <hostdev mode='subsystem' type='pci' managed='no'>
    <source>
      <address domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
    </source>
    <teaming type='transient' persistent='ua-backup0'/>
  </hostdev>
...

ip link set enp2s0f1 vf 2 mac 52:54:00:11:22:33

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

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

...
<devices>
  <interface type='udp'>
    <mac address='52:54:00:22:c9:42'/>
    <source address='127.0.0.1' port='11115'>
      <local address='127.0.0.1' port='11116'/>
    </source>
  </interface>
</devices>
...

...
<devices>
  <interface type='null'>
    <mac address='52:54:00:22:c9:42'/>
  </interface>
</devices>
...

...
<devices>
  <interface type='vds'>
    <mac address='52:54:00:22:c9:42'/>
    <source switchid='12345678-1234-1234-1234-123456789abc' portid='6' portgroupid='pg-4321' connectionid='12345'/>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet1'/>
    <model type='ne2k_pci'/>
  </interface>
</devices>
...

qemu-system-x86_64 -net nic,model=?

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet1'/>
    <model type='virtio'/>
    <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'>
      <host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/>
      <guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/>
    </driver>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet1'/>
    <model type='virtio'/>
    <backend tap='/dev/net/tun' vhost='/dev/vhost-net'/>
    <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5'/>
    <tune>
      <sndbuf>1600</sndbuf>
    </tune>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet1'/>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <guest dev='myeth'/>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet1'/>
    <boot order='1'/>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet1'/>
    <rom bar='on' file='/etc/fake/boot.bin'/>
  </interface>
</devices>
...

...
<devices>
  ...
  <interface type='bridge'>
    <source bridge='br0'/>
    <backenddomain name='netvm'/>
  </interface>
  ...
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet0'/>
    <bandwidth>
      <inbound average='1000' peak='5000' floor='200' burst='1024'/>
      <outbound average='128' peak='256' burst='256'/>
    </bandwidth>
  </interface>
</devices>
...

...
<devices>
  <interface type='bridge'>
    <vlan>
      <tag id='42'/>
    </vlan>
    <source bridge='ovsbr0'/>
    <virtualport type='openvswitch'>
      <parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
    </virtualport>
  </interface>
  <interface type='bridge'>
    <vlan trunk='yes'>
      <tag id='42'/>
      <tag id='123' nativeMode='untagged'/>
    </vlan>
    ...
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <port isolated='yes'/>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet0'/>
    <link state='down'/>
  </interface>
</devices>
...

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet0'/>
    <mtu size='1500'/>
  </interface>
</devices>
...

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

...
<devices>
  <interface type='network'>
    <source network='default'/>
    <target dev='vnet0'/>
    <ip address='192.168.122.5' prefix='24'/>
    <ip address='192.168.122.5' prefix='24' peer='10.0.0.10'/>
    <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
    <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
  </interface>
  ...
  <hostdev mode='capabilities' type='net'>
    <source>
      <interface>eth0</interface>
    </source>
    <ip address='192.168.122.6' prefix='24'/>
    <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
    <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
  </hostdev>
  ...
</devices>
...

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

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

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

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='mouse' bus='usb'/>
  <input type='keyboard' bus='usb'/>
  <input type='mouse' bus='virtio'/>
  <input type='keyboard' bus='virtio'/>
  <input type='tablet' bus='virtio'/>
  <input type='passthrough' bus='virtio'>
    <source evdev='/dev/input/event1'/>
  </input>
  <input type='evdev'>
    <source dev='/dev/input/event1234' grab='all' repeat='on' grabToggle='ctrl-ctrl'/>
  </input>
</devices>
...

input

The input element has one mandatory attribute, the type whose value can be 'mouse', 'tablet', ( since 1.2.2 ) 'keyboard', ( since 1.3.0 ) 'passthrough' or ( since 7.4.0 ) 'evdev'. 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 in the Device Addresses section. On S390, address can be used to provide a CCW address for an input device ( since 4.2.0 ). For types passthrough and evdev, the mandatory sub-element source must have an evdev (for passthrough) or dev (for evdev) attribute containing the absolute path to the event device passed through to guests. For type evdev, source has three optional attributes grab with value 'all' which when enabled grabs all input devices instead of just one, repeat with value 'on'/'off' to enable/disable auto-repeat events and grabToggle (since 7.6.0) with values ctrl-ctrl, alt-alt, shift-shift, meta-meta, scrolllock or ctrl-scrolllock to change the grab key combination. input type evdev is currently supported only on linux devices. (KVM only) Since 5.2.0, the input element accepts a model attribute which has the values 'virtio', 'virtio-transitional' or 'virtio-non-transitional'. See virtio device models for more details.

The subelement driver can be used to tune the virtio options of the device: Virtio-related 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='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> (See Device Addresses) type='usb' which can tie the device to a particular controller.

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='sdl' display=':0.0'/>
  <graphics type='vnc' port='5904' sharePolicy='allow-exclusive'>
    <listen type='address' address='1.2.3.4'/>
  </graphics>
  <graphics type='rdp' autoport='yes' multiUser='yes' />
  <graphics type='desktop' fullscreen='yes'/>
  <graphics type='spice'>
    <listen type='network' network='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 optional arguments: a display attribute for the display to use, an xauth attribute for the authentication identifier, and an optional fullscreen attribute accepting values yes or no.

You can use a gl with the enable="yes" property to enable OpenGL support in SDL. Likewise you can explicitly disable OpenGL support with enable="no".

vnc

Starts a VNC server. The port attribute specifies the TCP port number (with -1 as legacy syntax indicating that it should be auto-allocated). The autoport attribute is the new preferred syntax for indicating auto-allocation of the 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. It is possible to set a limit on the validity of the password by giving a timestamp passwdValidTo='2010-04-09T15:51:00' assumed to be in UTC. The connected attribute allows control of connected client during password changes. VNC accepts 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 connections. Connecting multiple clients in parallel requires all clients asking for a shared session (vncviewer: -Shared switch). This is the default value. force-shared disables exclusive client access, every connection has to specify -Shared switch for vncviewer. ignore welcomes every connection unconditionally since 1.0.6.

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

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

For VNC, the powerControl attribute can be used to enable VM shutdown, reboot and reset power control features for the VNC client. This is appropriate if the authenticated VNC client user already has administrator privileges in the guest Since 7.1.0.

Although VNC doesn't support OpenGL natively, it can be paired with graphics type egl-headless (see below) which will instruct QEMU to open and use drm nodes for OpenGL rendering.

A VNC server could be optionally mapped to the specific host audio backend using the <audio> sub-element:

<graphics type='vnc' ...>
  <audio id='1'/>
</graphics>

Where 1 is an id of the audio device (See Audio backends). If no ID is specified, then the default audio backend will be used. Since 7.2.0, qemu.

spice Since 0.8.6

Starts a SPICE server. The port attribute specifies the TCP port number (with -1 as legacy syntax indicating that 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='2010-04-09T15:51:00' assumed to be in UTC.

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

The defaultMode attribute sets the default channel security policy, valid values are secure, insecure and the default any (which is secure if possible, but falls back to insecure rather than erroring out if no secure path is available). Since 0.9.12

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

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

Spice supports variable compression settings for audio, images and streaming. These settings are accessible via the compression attribute in all following elements: image to set image compression (accepts auto_glz, auto_lz, quic, glz, lz, off), jpeg for JPEG 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 the clipboard element. It is enabled by default, and 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 default will be used (client mode). Since 0.9.11

File transfer functionality (via Spice agent) is set using the 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 OpenGL. 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 render 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 specifies the TCP port number (with -1 as legacy syntax indicating that it should be auto-allocated). The autoport attribute is the new preferred syntax for indicating auto-allocation of the TCP port to use. In the VirtualBox driver, the autoport will make the hypervisor pick available port from 3389-3689 range when the VM is started. The chosen port will be reflected in the port attribute. The multiUser attribute is a boolean deciding whether multiple simultaneous connections to the VM are permitted. 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 connects 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", but using the VirtualBox viewer. Just like "sdl", it accepts the optional attributes display and fullscreen.

egl-headless Since 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 this display type doesn't provide any window or graphical console like the other types, for practical reasons it should be paired with either vnc or spice graphics types. This display type is only supported by QEMU domains (needs QEMU 2.10 or newer). Since 5.0.0 this element accepts a <gl/> sub-element with an optional attribute rendernode which can be used to specify an absolute path to a host's DRI device to be used for OpenGL rendering.

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

dbusSince 8.4.0

Export the display over D-Bus. By default, it will use a private bus, except when p2p or address are specified.

<graphics type='dbus'/>

p2p (accepts on or off) enables peer-to-peer connections, established through virDomainOpenGraphics() APIs.

address (accepts a D-Bus address), will connect to the specified bus address.

This element accepts a <gl/> sub-element with an optional attribute rendernode which can be used to specify an absolute path to a host's DRI device to be used for OpenGL rendering.

Copy & Paste functionality is provided thanks to the QEMU clipboard manager and the SPICE vdagent protocol. See qemu-vdagent for more details.

D-Bus can export an audio backend using the <audio> sub-element:

<graphics type='dbus' ...>
  <audio id='1'/>
</graphics>

Where 1 is an id of the audio device (See Audio backends).

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 query) to listen on.

It is possible to omit the address attribute in order to use an address from config files Since 1.3.5.

The address attribute is duplicated as listen attribute in graphics element for backward compatibility. 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 address attribute. For example, if the network has an IPv4 address in its configuration (e.g. if it has a forward type of route, 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 address associated with that bridge device will be used, and if the network is describing one of the 'direct' (macvtap) modes, the first IPv4 address 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 socket. 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 element is duplicated as socket attribute in graphics element. If graphics element contains a socket attribute all listen elements are ignored.

none since 2.0.0 (QEMU only)

This listen type doesn't have any other attribute. Libvirt supports 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 connect to this graphics device. Supported by graphics type vnc and spice.

Video devices¶

A video device.

...
<devices>
  <video>
    <model type='vga' vram='16384' heads='1'>
      <acceleration accel3d='yes' accel2d='yes'/>
    </model>
    <driver name='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 guest type.

For a guest of type "kvm", the default video is: type with value "cirrus", vram with value "16384" and heads with value "1". By default, the first 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 multiple 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 hypervisor features available.

Note: The purpose of the type none is to instruct libvirt not to add a default video device in the guest (see the video element description above), since such behaviour is inconvenient in cases where GPU mediated devices are meant to be the only rendering device within a guest. If this is your use case specify a none type video device in the XML to stop the default behaviour. 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", "kvm", "hvf", "vbox", "vmx" and "xen". If no value is provided the default is used. If the size is not a power 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", "hvf", "vbox" and "vmx".

For guest type of "kvm", "hvf" 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 default value is used. The ram should also be rounded to power 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 9.2.0 (QEMU driver only), devices with type "virtio" have an optional blob attribute that can be set to "on" or "off". Setting blob to "on" will enable the use of blob resources in the device. This can accelerate the display path by reducing or eliminating copying of pixel data between the guest and host. Note that blob resource support requires QEMU version 6.1 or newer.

Since 5.9.0, the model element may also have an optional resolution sub-element. 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", "gop", 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-related 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 model type ( Since 3.5.0 )

Consoles, serial, parallel & channel devices¶

A character device provides a way to interact with the virtual machine. Paravirtualized consoles, serial ports, parallel ports and channels are all classed as character devices and so represented using the same syntax.

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

In each of these directives, the top-level element name (parallel, serial, console, channel) describes how the device is presented to the guest. The guest interface is configured by the 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 attribute 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="/var/log/libvirt/qemu/guestname-serial0.log" append="off"/>
...

Each character device element has an optional sub-element <address> which can tie the device to a particular controller (See Controllers) 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).

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

...
<devices>
  <!-- Serial port -->
  <serial type='pty'>
    <source path='/dev/pts/3'/>
    <target port='0'/>
  </serial>
  <!-- Debug port for SeaBIOS / EDK II -->
  <serial type='file'>
    <target type='isa-debug'/>
    <address type='isa' iobase='0x402'/>
    <source path='/tmp/DOMAIN-ovmf.log'/>
  </serial>

</devices>
...

...
<devices>
  <!-- USB serial port -->
  <serial type='pty'>
    <target type='usb-serial' port='0'>
      <model name='usb-serial'/>
    </target>
    <address type='usb' bus='0' port='1'/>
  </serial>
</devices>
...

...
<devices>
  <!-- Serial console -->
  <console type='pty'>
    <source path='/dev/pts/2'/>
   <target type='serial' port='0'/>
  </console>
</devices>
...

...
<devices>
  <!-- KVM virtio console -->
  <console type='pty'>
    <source path='/dev/pts/5'/>
    <target type='virtio' port='0'/>
  </console>
</devices>
...

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

...
<devices>
  <serial type='pty'/>
</devices>
...

...
<devices>
  <console type='pty'/>
</devices>
...

...
<devices>
  <serial type='pty'/>
  <console type='pty'/>
</devices>
...

...
<devices>
  <channel type='unix'>
    <source mode='bind' path='/tmp/guestfwd'/>
    <target type='guestfwd' address='10.0.2.1' port='4600'/>
  </channel>

  <!-- KVM virtio channel -->
  <channel type='pty'>
    <target type='virtio' name='arbitrary.virtio.serial.port.name'/>
  </channel>
  <channel type='unix'>
    <source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/>
    <target type='virtio' name='org.qemu.guest_agent.0' state='connected'/>
  </channel>
  <channel type='spicevmc'>
    <target type='virtio' name='com.redhat.spice.0'/>
  </channel>
</devices>
...

...
<devices>
  <console type='stdio'>
    <target port='1'/>
  </console>
</devices>
...

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

...
<devices>
  <serial type='vc'>
    <target port="1"/>
  </serial>
</devices>
...

...
<devices>
  <serial type='null'>
    <target port="1"/>
  </serial>
</devices>
...

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

...
<devices>
  <serial type="dev">
    <source path="/dev/ttyS0"/>
    <target port="1"/>
  </serial>
</devices>
...

...
<devices>
  <serial type="pipe">
    <source path="/tmp/mypipe"/>
    <target port="1"/>
  </serial>
</devices>
...

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

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

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

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

...
<devices>
  <serial type="udp">
    <source mode="bind" host="0.0.0.0" service="2445"/>
    <source mode="connect" host="0.0.0.0" service="2445"/>
    <target port="1"/>
  </serial>
</devices>
...

...
<devices>
  <serial type="unix">
    <source mode="bind" path="/tmp/foo"/>
    <target port="1"/>
  </serial>
</devices>
...

...
<devices>
  <serial type="spiceport">
    <source channel="org.qemu.console.serial.0"/>
    <target port="1"/>
  </serial>
</devices>
...

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

Sound devices¶

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

...
<devices>
  <sound model='es1370'/>
</devices>
...

sound

The sound element has one mandatory attribute, model, which specifies what real sound device is emulated. Valid values are specific to the underlying hypervisor, though typical choices are sb16, es1370, pcspk, ac97 (Since 0.6.0), ich6 (Since 0.8.8), ich9 (Since 1.1.3), usb (Since 1.2.8), ich7 (Since 6.7.0, bhyve only) and virtio (Since 10.4.0 and QEMU 8.2.0).

Since 0.9.13, a sound element with ich6 or ich9 models 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='ich6'>
    <codec type='micro'/>
  </sound>
</devices>
...

Since 9.4.0 the usb sound device can be optionally switched into multi-channel mode by using the multichannel attribute:

<sound model='usb' multichannel='yes'/>

Since 10.4.0 and QEMU 8.2.0 the number of PCM streams in a virtio sound device can be configured by using the streams attribute, which defaults to 2 if left unspecified:

<sound model='virtio' streams='2'/>

Each sound element has an optional sub-element <address> which can tie the device to a particular PCI slot. See Device Addresses.

A sound device could be optionally mapped to the specific host audio backend using the <audio> sub-element:

...
<devices>
  <sound model='ich7'>
     <audio id='1'/>
  </sound>
</devices>
...

Where 1 is an id of the audio device (See Audio backends). If no ID is specified, then the default audio backend will be used. Since 6.7.0, bhyve; Since 7.2.0, qemu.

Audio backends¶

A virtual audio device corresponds to a host audio backend that is mapped to the guest sound device.

type

The required type attribute specifies audio backend type. Currently, the supported values are none, alsa, coreaudio, dbus, jack, oss, pipewire, pulseaudio, sdl, spice, file.

id

Integer id of the audio device. Must be greater than 0.

timerPeriod

Timer period in microseconds. Must be greater than 0. If omitted, the lowest possible period is used.

All the backends support child element for configuring input and output properties

...
<devices>
  <audio id='1' type='pulseaudio' timerPeriod='40'>
    <input mixingEngine='yes' fixedSettings='yes' voices='1' bufferLength='100'>
      <settings frequency='44100' channels='2' format='s16'/>
    </input>
    <output mixingEngine='yes' fixedSettings='yes' voices='2' bufferLength='100'>
      <settings frequency='22050' channels='4' format='f32'/>
    </output>
  </audio>
</devices>
...

The input and output elements support the same set of attributes and elements

• mixingEngine

  Control whether the host mixing engine is used to convert between different audio formats and sampling rates. When the mixing engine is disabled it is possible to make use of improved audio formats such as 5.1/7.1. If not specified, a hypervisor default applies.

• fixedSettings

  Control whether the mixing engine can dynamically choose settings to minimize format conversion. This is only valid when the mixing engine is explicitly enabled.

• voices

  The number of voices voices to use, usually defaults to 1

• bufferLength

  The length of the audio buffer in microseconds. Default is backend specific.

The <input> and <output> elements may also permit backend specific options.

When fixed settings are enabled, the <settings> child element is permitted with the following attributes.

• frequency

  The frequency in HZ, usually defaulting to 44100

• channels

  The number of channels, usually defaulting to 2. The permitted max number of channels is hypervisor specific.

• format

  The audio format, one of s8, u8, s16, u16, s32, u32, f32. The default is hypervisor specific.

Note: If no <audio/> element is defined, and the graphics element is set to either vnc or sdl, the libvirtd or virtqemud process will honor the following environment variables:

• SDL_AUDIODRIVER

  Valid values are pulseaudio, esd, alsa or arts.

• QEMU_AUDIO_DRV

  Valid values are pa, none, alsa, coreaudio, jack, oss, pipewire, sdl, spice or wav.

<audio id="1" type="alsa">
  <input dev="/dev/dsp0"/>
  <output dev="/dev/dsp1"/>
</audio>

<audio id="1" type="coreaudio">
  <input bufferCount="50"/>
  <output bufferCount="42"/>
</audio>

<audio id="1" type="jack">
  <input serverName="fish" clientName="food" connectPorts="system:capture_[13]" exactName="yes"/>
  <output serverName="fish" clientName="food" connectPorts="system:playback_[13]" exactName="yes"/>
</audio>

<audio type='oss' id='1' tryMMap='yes' exclusive='yes' dspPolicy='4'>
  <input dev='/dev/dsp0' bufferCount='40' tryPoll='yes'/>
  <output dev='/dev/dsp0' bufferCount='40' tryPoll='yes'/>
</audio>

<audio id="1" type="pipewire">
  <input name="fish" streamName="food" latency="100"/>
  <output name="fish" streamName="food" latency="200"/>
</audio>

<audio id="1" type="pipewire" runtimeDir='/run/user/1000'>
  <input name="fish" streamName="food" latency="100"/>
  <output name="fish" streamName="food" latency="200"/>
</audio>

<audio id="1" type="pulseaudio" serverName="acme.example.org">
  <input name="fish" streamName="food" latency="100"/>
  <output name="fish" streamName="food" latency="200"/>
</audio>

<audio type='sdl' id='1' driver='pulseaudio'>
  <input bufferCount='40'/>
  <output bufferCount='40'/>
</audio>

<audio type='spice' id='1'/>

<audio id="1" type="file" path="audio.wav"/>

Watchdog devices¶

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.

Having multiple watchdogs is usually not something very common, but be aware that this might happen, for example, when an implicit watchdog device is added as part of another device. For example the iTCO watchdog being part of the ich9 southbridge, which is used with the q35 machine type. Since 9.1.0

...
<devices>
  <watchdog model='i6300esb'/>
</devices>
...

  ...
  <devices>
    <watchdog model='i6300esb' action='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:

• 'itco' - included by default with q35 machine type Since 9.1.0

• '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, beware that after the dump the guest will be resumed 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='none' may be used.

Example: automatically added device with KVM

...
<devices>
  <memballoon model='virtio'/>
</devices>
...

Example: manually added device with static PCI slot 2 requested

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

• 'xen' - default with Xen

See virtio device models 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 moment before a guest's process get killed by Out of Memory killer. Since 1.3.1, QEMU and KVM only

freePageReporting

The optional freePageReporting attribute allows to enable/disable ("on"/"off", respectively) the ability of the QEMU virtio memory balloon to return unused pages back to the hypervisor to be used by other guests or processes. Please note that despite its name it has no effect on free memory as reported by virDomainMemoryStats() and/or virsh dommemstat. Since 6.9.0, QEMU and KVM only

period

The optional period allows the QEMU virtio memory balloon 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 add the option to the XML definition. The virsh dommemstat will accept the options --live, --current, or --config. If an option is not provided, the change 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 ignored. Since 1.1.1, requires QEMU 1.5

driver

For model virtio memballoon, Virtio-related 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='virtio'>
    <rate period="2000" bytes="1234"/>
    <backend model='random'>/dev/random</backend>
    <!-- OR -->
    <backend model='egd' type='udp'>
      <source mode='bind' service='1234'/>
      <source mode='connect' host='1.2.3.4' service='1234'/>
    </backend>
    <!-- OR -->
    <backend model='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

See virtio device models 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 permitted to be consumed per period. An optional period attribute 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 the 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-related 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='tpm-tis'>
    <backend type='passthrough'>
      <device path='/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. Since 4.5.0

Since 5.6.0, the state of the TPM emulator can be encrypted by providing an encryption element.

Example: usage of the TPM Emulator

...
<devices>
  <tpm model='tpm-tis'>
    <backend type='emulator' version='2.0' debug='5'>
      <encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/>
      <active_pcr_banks>
          <sha256/>
      </active_pcr_banks>
      <profile source='local:restricted' removeDisabled='check' name='custom:restricted'/>
    </backend>
  </tpm>
</devices>
...

Example: usage of external TPM emulator Since 9.0.0

...
<devices>
  <tpm model='tpm-tis'>
    <backend type='external'>
      <source type='unix' mode='connect' path='/tmp/path.sock'/>
    </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 choice 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 Ultravisor. Adding a TPM Proxy to a pSeries guest brings no security benefits unless the guest is running on a PPC64 host that has an Ultravisor and a TPM Resource 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 fully qualified file name is specified by path attribute of the source element. If no file name is specified then /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 installed on the host. Libvirt will automatically start an independent TPM emulator for each QEMU guest requesting access to it. 10.6.0, the debug parameter can be used to enable logging in the emulator backend, and accepts non-zero integer values.

external

For this backend, libvirt expects the TPM emulator to be started externally. The path to the unix socket where the emulator is listening is passed via the source element. Other backend sub-elements do not apply in this case, since they are controlled by the emulator command line.

version

The version attribute indicates the version of the TPM. 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

The default version used depends on the combination of hypervisor, guest architecture, TPM model and backend.

source

For the emulator backend, the source element specifies the location of the TPM state storage. Since v10.10.0

For the external backend, it specifies the socket of the externally started TPM emulator. Since v9.0.0

This element does not work with the passthrough backend.

When specified, it is the user's responsability to prevent files from being used by multiple VMs or emulators (swtpm will also use advisory locking). If not specified, the storage configuration is left to libvirt discretion.

This element requires that swtpm v0.7 or later is installed.

The following attributes are supported:

type

For external backend, only type unix is supported. For emulator backend, it's possible to provide file to utilize a single file or block device where the TPM state will be stored, or dir for the directory where the files will be stored.

mode

Connection mode for the unix socket. Only connect is supported. Can be omitted.

path

The path to the TPM state storage, or the unix socket.

persistent_state

The persistent_state attribute indicates whether 'swtpm' TPM state is kept or not when a transient domain is powered off or undefined. This option can be used for preserving TPM state. By default the value is no. This attribute only works with the emulator backend. The accepted values are yes and no. Since 7.0.0

active_pcr_banks

The active_pcr_banks node is used to define which of the PCR banks of a TPM 2.0 to activate. Valid names are for example sha1, sha256, sha384, and sha512. If this node is provided, the set of PCR banks are activated before every start of a VM and this step is logged in the swtpm's log. If this node is removed or omitted then libvirt will not modify the active PCR banks upon VM start but leave them at their last configuration. This attribute requires that swtpm_setup v0.7 or later is installed and may not have any effect otherwise. The selection of PCR banks only works with the emulator backend. Since 7.10.0

profile

The profile node is used to set a profile for a TPM 2.0 given in the source attribute. This profile will be set when the TPM is initially created and after that cannot be changed anymore. Once a profile has been set the name attribute will be updated with the name of the profile that is running. If no profile is provided, then swtpm will use the latest built-in 'default' profile or the default profile set in swtpm_setup.conf. Otherwise swtpm_setup will search for a profile with the given name with appended .json suffix in a configurable local and then in a distro directory. If none could be found in either, it will fall back trying to use a built-in one.

The built-in 'null' profile provides backwards compatibility with libtpms v0.9 but also restricts the user to use only TPM features that were available at the time of libtpms v0.9. The built-in 'custom' profile is the only profile that a user can modify and where the removeDisabled attribute has any effect. This attribute is particularly useful when a host is running in FIPS mode and therefore some crypto algorithms (camellia, tdes, unpadded RSA encryption, 1024-bit RSA keys, and others) are disabled. When it is set to check (recommended) then only those algorithms that are currently disabled will automatically be removed from the 'custom' profile, while when it is set to fips-host then all potentially disabled algorithms will be removed. Since 10.??.0

TPM profiles provided by a distro can be referenced with the 'distro:' prefix. Locally created TPM profiles can be referenced with the 'local:' prefix.

For further information about TPM profiles see the man pages for swtpm (swtpm v0.10).

encryption

The encryption element allows the state of a TPM emulator 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 address 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='spapr-vio' reg='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 QEMU 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 architecture

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

Example: usage of panic configuration

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

model

The optional model attribute specifies what type of panic device is provided. The panic model used when this attribute 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

• 'pvpanic' - for PCI pvpanic device Since 9.1.0, QEMU only

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='my_shmem0' role='peer'>
    <model type='ivshmem-plain'/>
    <size unit='M'>4</size>
  </shmem>
  <shmem name='shmem_server'>
    <model type='ivshmem-doorbell'/>
    <size unit='M'>2</size>
    <server path='/tmp/socket-shmem'/>
    <msi vectors='32' ioeventfd='on'/>
  </shmem>
</devices>
...

shmem

The shmem element has one mandatory attribute, name to identify the shared memory. This attribute cannot be directory specific to . or .. as well as it cannot involve path separator /.

The optional role (since 6.6.0) attribute specifies the shared memory is migratable or not. The value can be either "master" or "peer", the former will mean that upon migration, the data in the shared memory is migrated with the domain. There should be only one "master" per shared memory object. Migration with "peer" role is disabled. If migration of such domain is required, the shmem device needs to be unplugged before migration and plugged in at the destination upon successful migration. If the role not specified, the hypervisor default is used. This attribute is currently available only for model type ivshmem-plain and ivshmem-doorbell.

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, but is deprecated by newer QEMU in favour of the -plain and -doorbell variants), 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 shared 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 devices 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 the guests' memory resource needs. Some hypervisors may require NUMA configured for the guest.

Example: usage of the memory devices

...
<devices>
  <memory model='dimm' access='private' discard='yes'>
    <target>
      <size unit='KiB'>524287</size>
      <node>0</node>
    </target>
  </memory>
  <memory model='dimm'>
    <source>
      <pagesize unit='KiB'>2048</pagesize>
      <nodemask>1-3</nodemask>
    </source>
    <target>
      <size unit='KiB'>524287</size>
      <node>1</node>
    </target>
  </memory>
  <memory model='nvdimm'>
    <uuid>9066901e-c90a-46ad-8b55-c18868cf92ae</uuid>
    <source>
      <path>/tmp/nvdimm</path>
    </source>
    <target>
      <size unit='KiB'>524288</size>
      <node>1</node>
      <label>
        <size unit='KiB'>128</size>
      </label>
      <readonly/>
    </target>
  </memory>
  <memory model='nvdimm' access='shared'>
    <uuid>e39080c8-7f99-4b12-9c43-d80014e977b8</uuid>
    <source>
      <path>/dev/dax0.0</path>
      <alignsize unit='KiB'>2048</alignsize>
      <pmem/>
    </source>
    <target>
      <size unit='KiB'>524288</size>
      <node>1</node>
      <label>
        <size unit='KiB'>128</size>
      </label>
    </target>
  </memory>
  <memory model='virtio-pmem' access='shared'>
    <source>
      <path>/tmp/virtio_pmem</path>
    </source>
    <target>
      <size unit='KiB'>524288</size>
      <address base='0x140000000'/>
    </target>
  </memory>
  <memory model='virtio-mem'>
    <source>
      <nodemask>1-3</nodemask>
      <pagesize unit='KiB'>2048</pagesize>
    </source>
    <target>
      <size unit='KiB'>2097152</size>
      <node>0</node>
      <block unit='KiB'>2048</block>
      <requested unit='KiB'>1048576</requested>
      <current unit='KiB'>524288</current>
      <address base='0x150000000'/>
    </target>
  </memory>
  <memory model='sgx-epc'>
    <source>
      <nodemask>0-1</nodemask>
    </source>
    <target>
      <size unit='KiB'>16384</size>
      <node>0</node>
    </target>
  </memory>
  <memory model='sgx-epc'>
    <target>
      <size unit='KiB'>16384</size>
    </target>
  </memory>
</devices>
...

model

Provide dimm to add a virtual DIMM module to the guest. Since 1.2.14 Provide nvdimm model that adds a Non-Volatile DIMM module. Since 3.2.0 Provide virtio-pmem model to add a paravirtualized persistent memory device. Since 7.1.0 Provide virtio-mem model to add paravirtualized memory device. Since 7.9.0 Provide sgx-epc model to add a SGX enclave page cache (EPC) memory to the guest. Since 8.10.0 and QEMU 7.0.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. For virtio-pmem model 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='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='nvdimm' for pSeries guests. Since 6.2.0

source

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

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 the source 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 used. 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 hypervisor in order to guarantee the persistence of writes to the vNVDIMM backend, then use the pmem element in order to utilize the feature. Since 5.0.0

For model virtio-pmem the source element is mandatory. The following optional elements may be used:

path

Represents a path in the host that backs the virtio memory module in the guest. It is mandatory.

For model sgx-epc this element is optional. The following optional elements may be used:

nodemask

This element can be used to override the default set of NUMA nodes where the memory would be allocated. Since 8.10.0 and QEMU 7.0.0

target

The mandatory target element configures the placement and sizing of the added memory from the perspective of the guest.

The mandatory size subelement configures the size of the added memory as a scaled integer. For virtio-mem this represents the maximum possible size exposed to the guest.

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

For virtio-mem optional attribute dynamicMemslots can be specified (accepted values "yes"/"no") which allows hypervisor to spread memory into multiple memory slots (allocate them dynamically based on the amount of memory exposed to the guest), resulting in smaller memory footprint. But be aware this may affect vhost-user devices. When enabled, older vhost-user device implementations (such as virtiofs) may refuse to initialize resulting in failed domain startup or device hotplug. When only modern vhost-user based devices will be used or when no vhost-user devices are expected to be used it's beneficial to enable this feature. The current default is hypervisor dependant (for QEMU is "no"). If the default changes and you are having difficulties with vhost-user devices, try toggling this to "no". Since 10.1.0 and QEMU 8.2.0

The following optional elements may be used:

label

For NVDIMM type devices one can use label and its subelement size to configure the size of namespaces label storage within the NVDIMM module. The size element has usual meaning described in the Memory Allocation section. label is mandatory for pSeries guests and optional for all other architectures. For QEMU domains the following restrictions apply:

1. the minimum label size is 128KiB,

2. the remaining size (total-size - label-size), also called guest area, will be aligned to 4KiB as default. For pSeries guests, the guest area will be aligned down to 256MiB, and the minimum size of the guest area must be at least 256MiB.

readonly

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

block

For virtio-mem only. The size of an individual block, granularity of division of memory block. Must be power of two and at least equal to size of a transparent hugepage (2MiB on x84_64). The default is hypervisor dependent.

requested

For virtio-mem only. The total size exposed to the guest. Must respect block granularity and be smaller than or equal to size.

current

Active XML for virtio-mem model may contain current element that reflects the current size of the corresponding virtio memory device. The element is formatted into live XML and never parsed, i.e. it is output-only element.

address

For virtio-mem and virtio-pmem only. The physical address in memory, where device is mapped. Since 9.4.0

IOMMU devices¶

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

Example:

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

model

Supported values are intel (for Q35 guests) smmuv3 (since 5.5.0, for ARM virt guests), and virtio (since 8.3.0, for Q35 and 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 functionality. Currently this requires split I/O APIC (<ioapic driver='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)

dma_translation

The dma_translation attribute with possible values on and off can be used to turn off the dma translation for IOMMU. It is useful when only interrupt remapping is required but dma translation overhead is unwanted, for example to efficiently enable more than 255 vCPUs. Since 10.7.0 (QEMU/KVM only)

The virtio IOMMU devices can further have address element as described in Device addresses (address has to by type of pci).

Vsock¶

A vsock host/guest interface. The model attribute defaults to virtio. Since 5.2.0 model can also be 'virtio-transitional' or 'virtio-non-transitional', see virtio device models 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 The optional driver element allows to specify virtio options, see Virtio-related options for more details. Since 7.1.0

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

Crypto¶

A crypto device. The model attribute defaults to virtio. Since v9.0.0 model supports virtio only. The type attribute defaults to qemu. Since v9.0.0 type supports qemu only. The optional attribute backend is required if the type is qemu, the model attribute can be builtint and lkcf, the optional attribute queues specifies the number of virt queues for virtio crypto.

...
<devices>
  <crypto model='virtio' type='qemu'>
    <backend model='builtin' queues='1'/>
  </crypto>
</devices>
...

Pstore¶

Pstore is an oops/panic logger that writes its logs to a block device and non-block device before the system crashes. Currently only ACPI Error Record Serialization Table, ERST, is supported. This feature is designed for storing error records in persistent storage for future reference and/or debugging. Since v10.6.0

...
<pstore backend='acpi-erst'>
  <path>/tmp/guest_acpi_esrt</path>
  <size unit='KiB'>8</size>
  <address type='pci' domain='0x0000' bus='0x02' slot='0x01' function='0x0'/>
</pstore>
...

The pstore element has one mandatory attribute backend which selects desired backend (only acpi-erst is accepted for now). Then it has the following child elements:

path

Represents a path in the host that backs the pstore device in the guest.

size

Configures the size of the persistent storage available to the guest. It is mandatory.