[PATCH 06/32] docs: formatdomain: Split out <devices>

Start splitting the massive document into smaller pieces using the .. include:: directive. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices.rst | 5053 ++++++++++++++++++++++++++++++++ docs/formatdomain.rst | 5054 +-------------------------------- docs/meson.build | 5 +- 3 files changed, 5058 insertions(+), 5054 deletions(-) create mode 100644 docs/formatdomain-devices.rst diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst new file mode 100644 index 0000000000..fef2bffef7 --- /dev/null +++ b/docs/formatdomain-devices.rst @@ -0,0 +1,5053 @@ +:anchor:`<a id="elementsDevices"/>` + +Devices +------- + +The final set of XML elements are all used to describe devices provided to the +guest domain. All devices occur as children of the main ``devices`` element. +:since:`Since 0.1.3` + +:: + + ... + <devices> + <emulator>/usr/lib/xen/bin/qemu-dm</emulator> + </devices> + ... + +``emulator`` + The contents of the ``emulator`` element specify the fully qualified path to + the device model emulator binary. The `capabilities XML <formatcaps.html>`__ + specifies the recommended default emulator to use for each particular domain + type / architecture combination. + +To help users identifying devices they care about, every device can have direct +child ``alias`` element which then has ``name`` attribute where users can store +identifier for the device. The identifier has to have "ua-" prefix and must be +unique within the domain. Additionally, the identifier must consist only of the +following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` + +:: + + <devices> + <disk type='file'> + <alias name='ua-myDisk'/> + </disk> + <interface type='network' trustGuestRxFilters='yes'> + <alias name='ua-myNIC'/> + </interface> + ... + </devices> + +:anchor:`<a id="elementsDisks"/>` + +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'/> + <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'/> + <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'/> + <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='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='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'/> + <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> + </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:`since 0.7.5` ), + "network" ( :since:`since 0.8.7` ), or "volume" ( :since:`since 1.0.5` ), + or "nvme" ( :since:`since 6.0.0` ) and refer to the underlying source for + the disk. :since:`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:`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 <http://wiki.libvirt.org/page/NPIV_in_libvirt>`__ 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:`Since 0.1.4` + + ``model`` + Indicates the emulated device model of the disk. Typically this is + indicated solely by the ``bus`` property but for ``bus`` "virtio" the + model can be specified further with "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. :since:`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). To confine the + capability as much as possible for QEMU driver as this stage, ``sgio`` is + recommended, it's more secure than ``rawio``. :since:`Since 0.9.10` + ``sgio`` + If supported by the hypervisor and OS, indicates whether unprivileged + SG_IO commands are filtered for the disk. Valid settings are "filtered" or + "unfiltered" where the default is "filtered". Only available when the + ``device`` is 'lun'. :since:`Since 1.0.2` + ``snapshot`` + Indicates the default behavior of the disk during disk snapshots: + "``internal``" requires a file format such as qcow2 that can store both + the snapshot and the data changes since the snapshot; "``external``" will + separate the snapshot from the live data; and "``no``" means the disk will + not participate in snapshots. 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 <formatsnapshot.html>`__. Not all snapshot modes are supported; + for example, enabling snapshots with a transient disk generally does not + make sense. :since:`Since 0.9.5` + +``source`` + Representation of the disk ``source`` depends on the disk ``type`` attribute + value as follows: + + ``file`` + The ``file`` attribute specifies the fully-qualified path to the file + holding the disk. :since:`Since 0.0.3` + ``block`` + The ``dev`` attribute specifies the fully-qualified path to the host + device to serve as the disk. :since:`Since 0.0.3` + ``dir`` + The ``dir`` attribute specifies the fully-qualified path to the directory + to use as the disk. :since:`Since 0.7.5` + ``network`` + The ``protocol`` attribute specifies the protocol to access to the + requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdog", + "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp". + + For any ``protocol`` other than ``nbd`` an additional attribute ``name`` + is mandatory to specify which volume/image will be used. + + For "nbd", the ``name`` attribute is optional. 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:`Since 4.5.0` ) + + For protocols ``http`` and ``https`` an optional attribute ``query`` + specifies the query string. ( :since:`Since 6.2.0` ) + + For "iscsi" ( :since:`since 1.0.4` ), the ``name`` attribute may 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:`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:`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 <formatstorage.html>`__ (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:`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 <formatstorage.html>`__ ``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:`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. + + With "file", "block", and "volume", one or more optional sub-elements + ``seclabel``, `described below <#seclabel>`__ (and :since:`since 0.9.9` ), + can be used to override the domain security labeling policy for just that + source file. (NB, for "volume" type disk, ``seclabel`` is only valid when the + specified storage volume is of 'file' or 'block' type). + + The ``source`` element may also have the ``index`` attribute with same + semantics the `index <#elementsDiskBackingStoreIndex>`__ attribute of + ``backingStore`` + + The ``source`` element may contain the following sub elements: + + ``host`` + When the disk ``type`` is "network", the ``source`` may have zero or more + ``host`` sub-elements used to specify the hosts to connect. The ``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:`Since 2.1.0` ), just one prior to that 24007 + vxhs a server running Veritas HyperScale daemon only one 9999 + ======== ======================================================= ============================================================ ================ + + gluster supports "tcp", "rdma", "unix" as valid values for the transport + attribute. nbd supports "tcp" and "unix". Others only support "tcp". If + nothing is specified, "tcp" is assumed. If the transport is "unix", the + socket attribute specifies the path to an AF_UNIX socket. + + ``snapshot`` + The ``name`` attribute of ``snapshot`` element can optionally specify an + internal snapshot name to be used as the source for storage protocols. + Supported for 'rbd' :since:`since 1.2.11 (QEMU only).` + ``config`` + The ``file`` attribute for the ``config`` element provides a fully + qualified path to a configuration file to be provided as a parameter to + the client of a networked storage protocol. Supported for 'rbd' + :since:`since 1.2.11 (QEMU only).` + ``auth`` + :since:`Since libvirt 3.9.0` , the ``auth`` element is supported for a + disk ``type`` "network" that is using a ``source`` element with the + ``protocol`` attributes "rbd" or "iscsi". If present, the ``auth`` 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 <formatsecret.html>`__ 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:`Since libvirt 3.9.0` , the ``encryption`` can be a sub-element of + the ``source`` element for encrypted storage sources. If present, + specifies how the storage source is encrypted See the `Storage + Encryption <formatstorageencryption.html>`__ 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:`Since libvirt 4.5.0` ) + ``reservations`` + :since:`Since libvirt 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:`Since libvirt 4.7.0` , the ``initiator`` element is supported for + a disk ``type`` "network" that is using a ``source`` element with the + ``protocol`` attribute "iscsi". If present, the ``initiator`` element + provides the initiator IQN needed to access the source via mandatory + attribute ``name``. + ``address`` + For disk of type ``nvme`` this element specifies the PCI address of the + host NVMe controller. :since:`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:`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:`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:`Since 6.2.0` + ``readahead`` + Specifies the size of the readahead buffer for protocols which support it. + (all 'curl' based drivers in qemu). The size is in bytes. Note that '0' is + considered as if the value is not provided. :since:`Since 6.2.0` + ``timeout`` + Specifies the connection timeout for protocols which support it. Note that + '0' is considered as if the value is not provided. :since:`Since 6.2.0` + + For a "file" or "volume" disk type which represents a cdrom or floppy (the + ``device`` attribute), it is possible to define policy what to do with the + disk if the source file is not accessible. (NB, ``startupPolicy`` is not + valid for "volume" disk unless the specified storage volume is of "file" + type). This is done by the ``startupPolicy`` attribute ( :since:`since 0.9.7` + ), accepting these values: + + ========= ===================================================================== + 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:`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:`Since 1.2.4.` If the hypervisor driver + does not support the + `backingStoreInput <formatdomaincaps.html#featureBackingStoreInput>`__ ( + :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on + input and only used for output to describe the detected backing chains of + running domains. If ``backingStoreInput`` is supported the ``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``. + ``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:`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:`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:`since 1.2.6` . Older libvirt supported only block copy to a + file, :since:`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" :since:`"sd" since 1.1.2` . If + omitted, the bus type is inferred from the style of the device name (e.g. a + device named 'sda' will typically be exported using a SCSI bus). The 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 + disks, and its value can be either "on" or "off", defaulting to "off". + :since:`Since 0.0.3; ``bus`` attribute since 0.4.3; ``tray`` attribute since + 0.9.11; "usb" attribute value since after 0.4.4; "sata" attribute value since + 0.9.7; "removable" attribute value since 1.1.3` +``iotune`` + The optional ``iotune`` element provides the ability to provide additional + per-device I/O tuning, with values that can vary for each device (contrast + this to the `<blkiotune> <#elementsBlockTuning>`__ element, which applies + globally to the domain). Currently, the only tuning available is Block I/O + throttling for qemu. This element has optional sub-elements; any sub-element + not specified or given with a value of 0 implies no limit. :since:`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. + + :since:`Throughput limits since 1.2.11 and QEMU 1.7` + + ``group_name`` + The optional ``group_name`` provides the cability to share I/O throttling + quota between multiple drives. This prevents end-users from circumventing + a hosting provider's throttling policy by splitting 1 large drive in N + small drives and getting N times the normal throttling quota. Any name may + be used. + + :since:`group_name since 3.0.0 and QEMU 2.4` + + ``total_bytes_sec_max_length`` + The optional ``total_bytes_sec_max_length`` element is the maximum + duration in seconds for the ``total_bytes_sec_max`` burst period. 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. + + :since:`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:`Since 0.1.8` + + - If the hypervisor supports multiple backend drivers, then the ``name`` + attribute selects the primary backend driver name, while the optional + ``type`` attribute provides the sub-type. For example, xen supports a name + of "tap", "tap2", "phy", or "file", with a type of "aio", while qemu only + supports a name of "qemu", but multiple types including "raw", "bochs", + "qcow2", and "qed". + - The optional ``cache`` attribute controls the cache mechanism, possible + values are "default", "none", "writethrough", "writeback", "directsync" + (like "writethrough", but it bypasses the host page cache) and "unsafe" + (host may cache all disk io, and sync requests from guest are ignored). + :since:` Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7 ` + - The optional ``error_policy`` attribute controls how the hypervisor will + behave on a disk read or write error, possible values are "stop", + "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" since + 0.9.7` The default is left to the discretion of the hypervisor. There is + also an optional ``rerror_policy`` that controls behavior for read errors + only. :since:`Since 0.9.7` . If no rerror_policy is given, error_policy is + used for both read and write errors. If rerror_policy is given, it + overrides the ``error_policy`` for read errors. Also note that "enospace" + is not a valid policy for read errors, so if ``error_policy`` is set to + "enospace" and no ``rerror_policy`` is given, the read error policy will + be left at its default. + - The optional ``io`` attribute controls specific policies on I/O; qemu + guests support "threads" and "native" :since:`Since 0.8.8` , io_uring + :since:`Since 6.3.0 (QEMU 5.0)` . + - The optional ``ioeventfd`` attribute allows users to set `domain I/O + asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__ 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:`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:`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:`Since 0.9.10 (QEMU and KVM only)` + - The optional ``discard`` attribute controls whether discard requests (also + known as "trim" or "unmap") are ignored or passed to the filesystem. The + value can be either "unmap" (allow the discard request to be passed) or + "ignore" (ignore the discard request). :since:`Since 1.0.6 (QEMU and KVM + only)` + - The optional ``detect_zeroes`` attribute controls whether to detect zero + write requests. The value can be "off", "on" or "unmap". First two 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:`Since 2.0.0` + - The optional ``iothread`` attribute assigns the disk to an IOThread as + defined by the range for the domain + `iothreads <#elementsIOThreadsAllocation>`__ value. Multiple disks 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:`Since 1.2.8 + (QEMU 2.1)` + - The optional ``queues`` attribute specifies the number of virt queues for + virtio-blk. ( :since:`Since 3.9.0` ) + - For virtio disks, `Virtio-specific options <#elementsVirtio>`__ can also + be set. ( :since:`Since 3.5.0` ) + +``backenddomain`` + The optional ``backenddomain`` element allows specifying a backend domain + (aka driver domain) hosting the disk. Use the ``name`` attribute to specify + the backend domain name. :since:`Since 1.2.13 (Xen only)` +``boot`` + Specifies that the disk is bootable. The ``order`` attribute determines the + order in which devices will be tried during boot sequence. On the S390 + architecture only the first boot device is used. The optional ``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:`Since 3.5.0` The per-device ``boot`` elements cannot be used + together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__ + section. :since:`Since 0.8.8` +``encryption`` + Starting with :since:`libvirt 3.9.0` the ``encryption`` element is preferred + to be a sub-element of the ``source`` element. If present, specifies how the + volume is encrypted using "qcow". See the `Storage + Encryption <formatstorageencryption.html>`__ 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 or + snapshots. :since:`Since 0.9.5` +``serial`` + If present, this specify serial number of virtual hard drive. For example, it + may look like ``<serial>WD-WMAP9A966149</serial>``. Not supported for + scsi-block devices, that is those using disk ``type`` 'block' using + ``device`` 'lun' on ``bus`` 'scsi'. :since:`Since 0.7.1` +``wwn`` + If present, this element specifies the WWN (World Wide Name) of a virtual + hard disk or CD-ROM drive. It must be composed of 16 hexadecimal digits. + :since:`Since 0.10.1` +``vendor`` + If present, this element specifies the vendor of a virtual hard disk or + CD-ROM device. It must not be longer than 8 printable characters. + :since:`Since 1.0.1` +``product`` + If present, this element specifies the product of a virtual hard disk or + CD-ROM device. It must not be longer than 16 printable characters. + :since:`Since 1.0.1` +``address`` + If present, the ``address`` element ties the disk to a given slot of a + controller (the actual ``<controller>`` device can often be inferred by + libvirt, although it can be `explicitly specified <#elementsControllers>`__). + The ``type`` attribute is mandatory, and is typically "pci" or "drive". For a + "pci" controller, additional attributes for ``bus``, ``slot``, and + ``function`` must be present, as well as optional ``domain`` and + ``multifunction``. Multifunction defaults to 'off'; any other value requires + QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, additional + attributes ``controller``, ``bus``, ``target`` ( :since:`libvirt 0.9.11` ), + and ``unit`` are available, each defaulting to 0. +``auth`` + Starting with :since:`libvirt 3.9.0` the ``auth`` element is preferred to be + a sub-element of the ``source`` element. The element is still read and + managed as a ``disk`` sub-element. It is invalid to use ``auth`` as both a + sub-element of ``disk`` and ``source``. The ``auth`` element was introduced + as a ``disk`` sub-element in :since:`libvirt 0.9.7.` +``geometry`` + The optional ``geometry`` element provides the ability to override geometry + settings. This mostly useful for S390 DASD-disks or older DOS-disks. + :since:`0.10.0` + + ``cyls`` + The ``cyls`` attribute is the number of cylinders. + ``heads`` + The ``heads`` attribute is the number of heads. + ``secs`` + The ``secs`` attribute is the number of sectors per track. + ``trans`` + The optional ``trans`` attribute is the BIOS-Translation-Modus (none, lba + or auto) + +``blockio`` + If present, the ``blockio`` element allows to override any of the block + device properties listed below. :since:`Since 0.10.2 (QEMU and KVM)` + + ``logical_block_size`` + The logical block size the disk will report to the guest OS. For 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. + +:anchor:`<a id="elementsFilesystems"/>` + +Filesystems +~~~~~~~~~~~ + +A directory on the host that can be accessed directly from the guest. +:since:`since 0.3.3, since 0.8.5 for QEMU/KVM` + +:: + + ... + <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='file' accessmode='passthrough'> + <driver type='loop' format='raw'/> + <driver type='path' wrpolicy='immediate'/> + <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'/> + <lock posix='on' flock='on'/> + </binary> + <source dir='/path'/> + <target dir='mount_tag'/> + </filesystem> + ... + </devices> + ... + +``filesystem`` + The filesystem attribute ``type`` specifies the type of the ``source``. The + possible values are: + + ``mount`` + A host directory to mount in the guest. Used by LXC, OpenVZ :since:`(since + 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``type`` + if one is not specified. This mode also has an optional sub-element + ``driver``, with an attribute ``type='path'`` or ``type='handle'`` + :since:`(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:`(since 0.9.10)` + . :since:`Since 6.2.0` , ``type='virtiofs'`` is also supported. Using + virtiofs requires setting up shared memory, see the guide: + `Virtio-FS <kbase/virtiofs.html>`__ + ``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:`(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:` (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:` (since 0.9.13)` + + The filesystem element has an optional attribute ``accessmode`` which + specifies the security mode for accessing the source :since:`(since 0.8.5)` . + Currently this only works with ``type='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 <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__ + ``mapped`` + The ``source`` is accessed with the permissions of the hypervisor (QEMU + process). `More + info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__ + ``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 <http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html>`__ + + :since:`Since 5.2.0` , the filesystem element has an optional attribute + ``model`` with supported values "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. + + The filesystem element has an optional attribute ``multidevs`` which + specifies how to deal with a filesystem export containing more than one + device, in order to avoid file ID collisions on guest when using 9pfs ( + :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not 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:`Since 1.0.6` + + - If the hypervisor supports multiple backend drivers, then the ``type`` + attribute selects the primary backend driver name, while the ``format`` + attribute provides the format type. For example, LXC supports a type of + "loop", with a format of "raw" or "nbd" with any format. QEMU supports a + type of "path" or "handle", but no formats. Virtuozzo driver supports a + type of "ploop" with a format of "ploop". + - For virtio-backed devices, `Virtio-specific options <#elementsVirtio>`__ + can also be set. ( :since:`Since 3.5.0` ) + - For ``virtiofs``, the ``queue`` attribute can be used to specify the queue + size (i.e. how many requests can the queue fit). ( :since:`Since 6.2.0` ) + +``binary`` + The optional ``binary`` element can tune the options for virtiofsd. All of + the following attributes and elements are optional. The attribute ``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:`Since 6.2.0` ) +``source`` + The resource on the host that is being accessed in the guest. The ``name`` + attribute must be used with ``type='template'``, and the ``dir`` attribute + must be used with ``type='mount'``. 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. +``readonly`` + Enables exporting filesystem as a readonly mount for guest, by default + read-write access is given (currently only works for QEMU/KVM driver). +``space_hard_limit`` + Maximum space available to this guest's filesystem. :since:`Since 0.9.13` +``space_soft_limit`` + Maximum space available to this guest's filesystem. The container is + permitted to exceed its soft limits for a grace period of time. Afterwards + the hard limit is enforced. :since:`Since 0.9.13` + +:anchor:`<a id="elementsAddress"/>` + +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:`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:`Since 4.10.0` ), PCI address extensions depending on the + architecture are supported. For example, PCI addresses for S390 guests will + have a ``zpci`` child element, with two attributes: ``uid`` (a hex value + between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between + 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for + User-defined Identifiers and Function Identifiers. + :since:`Since 1.3.5` , some hypervisor drivers may accept an + ``<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 <pci-addresses.html>`__ 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:`Since 0.8.8.` +``usb`` + USB addresses have the following additional attributes: ``bus`` (a hex value + between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up to + four octets, such as 1.2 or 2.1.3.1). +``spapr-vio`` + On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It + has a flat 32-bit address space; by convention, devices are generally + assigned at a non-zero multiple of 0x00001000, but other addresses are valid + and permitted by libvirt. Each address has the following additional + attribute: ``reg`` (the hex value address of the starting register). + :since:`Since 0.9.9.` +``ccw`` + S390 guests with a ``machine`` value of s390-ccw-virtio use the native CCW + bus for I/O devices. CCW bus addresses have the following additional + attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``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:`Since 1.0.4` +``virtio-mmio`` + This places the device on the virtio-mmio transport, which is currently only + available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-mmio + addresses do not have any additional attributes. :since:`Since 1.1.3` + If the guest architecture is ``aarch64`` and the machine type is ``virt``, + libvirt will automatically assign PCI addresses to devices; however, the + presence of a single device with virtio-mmio address in the guest + configuration will cause libvirt to assign virtio-mmio addresses to all + further devices. :since:`Since 3.0.0` +``isa`` + ISA addresses have the following additional attributes: ``iobase`` and + ``irq``. :since:`Since 1.2.1` +``unassigned`` + For PCI hostdevs, ``<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:`Since 6.0.0` + +:anchor:`<a id="elementsVirtio"/>` + +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 device <#elementsIommu>`__). Possible values are ``on`` or ``off``. +:since:`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:`Since 6.3.0 (QEMU and KVM only)` + +:anchor:`<a id="elementsVirtioTransitional"/>` + +Virtio transitional devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 5.2.0` , some of QEMU's virtio devices, when used with PCI/PCIe +machine types, accept the following ``model`` values: + +``virtio-transitional`` + This device can work both with virtio 0.9 and virtio 1.0 guest drivers, so + it's the best choice when compatibility with older guest operating systems is + desired. libvirt will plug the device into a conventional PCI slot. +``virtio-non-transitional`` + This device can only work with virtio 1.0 guest drivers, and it's the + recommended option unless compatibility with older guest operating systems is + necessary. libvirt will plug the device into either a PCI Express slot or a + conventional PCI slot based on the machine type, resulting in a more + optimized PCI topology. +``virtio`` + This device will work like a ``virtio-non-transitional`` device when plugged + into a PCI Express slot, and like a ``virtio-transitional`` device otherwise; + libvirt will pick one or the other based on the machine type. This is the + best choice when compatibility with libvirt versions older than 5.2.0 is + necessary, but it's otherwise not recommended to use it. + +While the information outlined above applies to most virtio devices, there are a +few exceptions: + +- for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`` for + backwards compatibility reasons; +- some devices, such as GPUs and input devices (keyboard, tablet and mouse), + are only defined in the virtio 1.0 spec and as such don't have a transitional + variant: the only accepted model is ``virtio``, which will result in a + non-transitional device. + +For more details see the `qemu patch +posting <https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html>`__ +and the `virtio-1.0 +spec <http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html>`__. + +:anchor:`<a id="elementsControllers"/>` + +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 <pci-hotplug.html>`__ 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:`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:`Since 5.2.0` , it supports an optional + attribute ``model`` which can be 'virtio', 'virtio-transitional', or + 'virtio-non-transitional'. See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. +``scsi`` + A ``scsi`` controller has an optional attribute ``model``, which is one of + 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078', + 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. + See `Virtio transitional devices <#elementsVirtioTransitional>`__ 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:`since 0.10.0` , if the USB + bus needs to be explicitly disabled for the guest, ``model='none'`` may be + used. :since:`Since 1.0.5` , no default USB controller will be built on s390. + :since:`Since 1.3.5` , USB controllers accept a ``ports`` attribute to + configure how many devices can be connected to the controller. +``ide`` + :since:`Since 3.10.0` for the vbox driver, the ``ide`` controller has an + optional attribute ``model``, which is one of "piix3", "piix4" or "ich6". +``xenbus`` + :since:`Since 5.2.0` , the ``xenbus`` controller has an optional attribute + ``maxGrantFrames``, which specifies the maximum number of grant frames the + controller makes available for connected devices. :since:`Since 6.3.0` , the + xenbus controller supports the optional ``maxEventChannels`` attribute, which + specifies maximum number of event channels (PV interrupts) that can be used + by the guest. + +Note: The PowerPC64 "spapr-vio" addresses do not have an associated controller. + +For controllers that are themselves devices on a PCI or USB bus, an optional +sub-element ``<address>`` can specify the exact relationship of the controller +to its master bus, with semantics `given above <#elementsAddress>`__. + +An optional sub-element ``driver`` can specify the driver specific options: + +``queues`` + The optional ``queues`` attribute specifies the number of queues for the + controller. For best performance, it's recommended to specify a value + matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)` +``cmd_per_lun`` + The optional ``cmd_per_lun`` attribute specifies the maximum number of + commands that can be queued on devices controlled by the host. :since:`Since + 1.2.7 (QEMU and KVM only)` +``max_sectors`` + The optional ``max_sectors`` attribute specifies the maximum amount of data + in bytes that will be transferred to or from the device in a single command. + The transfer length is measured in sectors, where a sector is 512 bytes. + :since:`Since 1.2.7 (QEMU and KVM only)` +``ioeventfd`` + The optional ``ioeventfd`` attribute specifies whether the controller should + use `I/O asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__ + or not. Accepted values are "on" and "off". :since:`Since 1.2.18` +``iothread`` + Supported for controller type ``scsi`` using model ``virtio-scsi`` for + ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` . The + optional ``iothread`` attribute assigns the controller to an IOThread as + defined by the range for the domain + `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk`` + assigned to use the specified ``controller`` will utilize the same 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-specific options <#elementsVirtio>`__ can + also be set. ( :since:`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:`since 1.0.5` ) +- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` ) +- ``pcie-root-port``, ``pcie-switch-upstream-port``, + ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` ) +- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` ) +- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` ) + +The root controllers (``pci-root`` and ``pcie-root``) have an optional +``pcihole64`` element specifying how big (in kilobytes, or in the unit 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:`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:`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:`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`` + pcie-root-port and pcie-switch-downstream-port controllers can also have a + ``hotplug`` attribute in the ``<target>`` subelement, which is used to + disable hotplug/unplug of devices on a particular controller. The default + setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable + hotplug/unplug of devices on a particular controller. :since:`Since 6.3.0` +``busNr`` + pci-expander-bus and pcie-expander-bus controllers can have an optional + ``busNr`` attribute (1-254). This will be the bus number of the new bus; All + bus numbers between that specified and 255 will be available only for + assignment to PCI/PCIe controllers plugged into the hierarchy starting with + this expander bus, and bus numbers less than the specified value will be + available to the next lower expander-bus (or the root-bus if there are no + lower expander buses). If you do not specify a busNumber, libvirt will find + the lowest existing busNumber in all other expander buses (or use 256 if + there are no others) and auto-assign the busNr of that found bus - 2, which + provides one bus number for the pci-expander-bus and one for the pci-bridge + that is automatically attached to it (if you plan on adding more pci-bridges + to the hierarchy of the bus, you should manually set busNr to a lower value). + + A similar algorithm is used for automatically determining the busNr attribute + for pcie-expander-bus, but since the pcie-expander-bus doesn't have any + built-in pci-bridge, the 2nd bus-number is just being reserved for the + pcie-root-port that must necessarily be connected to the bus in order to + actually plug in an endpoint device. If you intend to plug multiple devices + into a pcie-expander-bus, you must connect a pcie-switch-upstream-port to the + pcie-root-port that is plugged into the pcie-expander-bus, and multiple + pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of course + for this to work properly, you will need to decrease the pcie-expander-bus' + busNr accordingly so that there are enough unused bus numbers above it to + accommodate giving out one bus number for the upstream-port and one for each + downstream-port (in addition to the pcie-root-port and the pcie-expander-bus + itself). + +``node`` + Some PCI controllers (``pci-expander-bus`` for the pc machine type, + ``pcie-expander-bus`` for the q35 machine type and, :since:`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:`Since 3.6.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:`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:`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:`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:`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> + ... + +:anchor:`<a id="elementsLease"/>` + +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. + +:anchor:`<a id="elementsHostDev"/>` + +Host device assignment +~~~~~~~~~~~~~~~~~~~~~~ + +:anchor:`<a id="elementsHostDevSubsys"/>` + +USB / PCI / SCSI devices +^^^^^^^^^^^^^^^^^^^^^^^^ + +USB, PCI and SCSI devices attached to the host can be passed through to the +guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.6.0 +for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` : + +:: + + ... + <devices> + <hostdev mode='subsystem' type='usb'> + <source startupPolicy='optional'> + <vendor id='0x1234'/> + <product id='0xbeef'/> + </source> + <boot order='2'/> + </hostdev> + </devices> + ... + +or: + +:: + + ... + <devices> + <hostdev mode='subsystem' type='pci' managed='yes'> + <source> + <address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/> + </source> + <boot order='1'/> + <rom bar='on' file='/etc/fake/boot.bin'/> + </hostdev> + </devices> + ... + +or: + +:: + + ... + <devices> + <hostdev mode='subsystem' type='scsi' sgio='filtered' 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> + ... + +or: + +:: + + ... + <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> + </source> + <address type='drive' controller='0' bus='0' target='0' unit='0'/> + </hostdev> + </devices> + ... + +or: + +:: + + ... + <devices> + <hostdev mode='subsystem' type='scsi_host'> + <source protocol='vhost' wwpn='naa.50014057667280d8'/> + </hostdev> + </devices> + ... + +or: + +:: + + ... + <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`` + The ``hostdev`` element is the main container for describing host devices. + For each device, the ``mode`` is always "subsystem" and the ``type`` is one + of the following values with additional attributes noted. + + ``usb`` + USB devices are detached from the host on guest startup and reattached + after the guest exits or the device is hot-unplugged. + ``pci`` + For PCI devices, when ``managed`` is "yes" it is detached from the host + before being passed on to the guest and reattached to the host after the + guest exits. If ``managed`` is omitted or "no", the user is responsible to + call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before + starting the guest or hot-plugging the device and + ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug + or stopping the guest. + ``scsi`` + For SCSI devices, user is responsible to make sure the device is not used + by host. If supported by the hypervisor and OS, the optional ``sgio`` ( + :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO + commands are filtered for the disk. Valid settings are "filtered" or + "unfiltered", where the default is "filtered". The optional ``rawio`` ( + :since:`since 1.2.9` ) attribute indicates whether the lun needs the rawio + capability. Valid settings are "yes" or "no". See the rawio description + within the `disk <#elementsDisks>`__ section. If a disk lun in the domain + already has the rawio capability, then this setting not required. + ``scsi_host`` + :since:`since 2.5.0` For SCSI devices, user is responsible to make sure + the device is not used by host. This ``type`` passes all LUNs presented by + a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attribute + can be specified further with "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. + ``mdev`` + For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute + specifies the device API which determines how the host's vfio driver will + expose the device to the guest. Currently, ``model='vfio-pci'``, + ``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model='vfio-ap'`` ( + :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__ + section provides more information about mediated devices as well as how to + create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an + optional ``display`` attribute may be used to enable or disable support + for an accelerated remote desktop backed by a mediated device (such as + NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video + devices <#elementsVideo>`__. This attribute is limited to + ``model='vfio-pci'`` only. Supported values are either ``on`` or ``off`` + (default is 'off'). It is required to use a `graphical + framebuffer <#elementsGraphics>`__ in order to use this attribute, + currently only supported with VNC, Spice and egl-headless graphics + devices. :since:`Since version 5.10.0` , there is an optional ``ramfb`` + attribute for devices with ``model='vfio-pci'``. Supported values are + either ``on`` or ``off`` (default is 'off'). When enabled, this attribute + provides a memory framebuffer device to the guest. This framebuffer will + be used as a boot display when a vgpu device is the primary display. + + Note: There are also some implications on the usage of guest's address + type depending on the ``model`` attribute, see the ``address`` element + below. + + Note: The ``managed`` attribute is only used with ``type='pci'`` and is + ignored by all the other device types, thus setting ``managed`` explicitly + with other than a PCI device has the same effect as omitting it. Similarly, + ``model`` attribute is only supported by mediated devices and ignored by all + other device types. + +``source`` + The source element describes the device as seen from the host using the + following mechanism to describe: + + ``usb`` + The USB device can either be addressed by vendor / product id using the + ``vendor`` and ``product`` elements or by the device's address on the host + using the ``address`` element. + + :since:`Since 1.0.0` , the ``source`` element of USB devices may contain + ``startupPolicy`` attribute which can be used to define policy what to do + if the specified host USB device is not found. The attribute accepts the + following values: + + ========= ===================================================================== + mandatory fail if missing for any reason (the default) + requisite fail if missing on boot up, drop if missing on migrate/restore/revert + optional drop if missing at any start attempt + ========= ===================================================================== + + ``pci`` + PCI devices can only be described by their ``address``. + ``scsi`` + SCSI devices are described by both the ``adapter`` and ``address`` + elements. The ``address`` element includes a ``bus`` attribute (a 2-digit + bus number), a ``target`` attribute (a 10-digit target number), and a + ``unit`` attribute (a 20-digit unit number on the bus). Not all + hypervisors support larger ``target`` and ``unit`` values. It is up to + each hypervisor to determine the maximum value supported for the adapter. + + :since:`Since 1.2.8` , the ``source`` element of a SCSI device may contain + the ``protocol`` attribute. When the attribute is set to "iscsi", the host + device XML follows the network `disk <#elementsDisks>`__ device using the + same ``name`` attribute and optionally using the ``auth`` element to + provide the authentication credentials to the iSCSI server. + + ``scsi_host`` + :since:`Since 2.5.0` , multiple LUNs behind a single SCSI HBA are + described by a ``protocol`` attribute set to "vhost" and a ``wwpn`` + attribute that is the vhost_scsi wwpn (16 hexadecimal digits with a prefix + of "naa.") established in the host configfs. + ``mdev`` + Mediated devices ( :since:`Since 3.2.0` ) are described by the ``address`` + element. The ``address`` element contains a single mandatory attribute + ``uuid``. + +``vendor``, ``product`` + The ``vendor`` and ``product`` elements each have an ``id`` attribute that + specifies the USB vendor and product id. The ids can be given in decimal, + hexadecimal (starting with 0x) or octal (starting with 0) form. +``boot`` + Specifies that the device is bootable. The ``order`` attribute determines the + order in which devices will be tried during boot sequence. The per-device + ``boot`` elements cannot be used together with general boot elements in `BIOS + bootloader <#elementsOSBIOS>`__ section. :since:`Since 0.8.8` for PCI + devices, :since:`Since 1.0.1` for USB devices. +``rom`` + The ``rom`` element is used to change how a PCI device's ROM is presented to + the guest. The optional ``bar`` attribute can be set to "on" or "off", and + determines whether or not the device's ROM will be visible in the guest's + memory map. (In PCI documentation, the "rombar" setting controls the presence + of the Base Address Register for the ROM). If no rom bar is specified, the + qemu default will be used (older versions of qemu used a default of "off", + while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU and KVM + only)` . The optional ``file`` attribute contains an absolute path to a + binary file to be presented to the guest as the device's ROM BIOS. This can + be useful, for example, to provide a PXE boot ROM for a virtual function of + an sr-iov capable ethernet device (which has no boot ROMs for the VFs). + :since:`Since 0.9.10 (QEMU and KVM only)` . The optional ``enabled`` + attribute can be set to ``no`` to disable PCI ROM loading completely for the + device; if PCI ROM loading is disabled through this attribute, attempts to + tweak the loading process further using the ``bar`` or ``file`` attributes + will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)` . +``address`` + The ``address`` element for USB devices has a ``bus`` and ``device`` + attribute to specify the USB bus and device number the device appears at on + the host. The values of these attributes can be given in decimal, hexadecimal + (starting with 0x) or octal (starting with 0) form. For PCI devices the + element carries 4 attributes allowing to designate the device as can be found + with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a 'drive' + address type must be used. For mediated devices, which are software-only + devices defining an allocation of resources on the physical parent device, + the address type used must conform to the ``model`` attribute of element + ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` device API + or any address type other than CCW for ``vfio-ccw`` device API will result in + an error. `See above <#elementsAddress>`__ for more details on the address + element. +``driver`` + PCI devices can have an optional ``driver`` subelement that specifies which + backend driver to use for PCI device assignment. Use the ``name`` attribute + to select either "vfio" (for the new VFIO device assignment backend, which is + compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment + handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU and KVM + only, requires kernel 3.6 or newer)` . When specified, device assignment will + fail if the requested method of device assignment isn't available on the + host. When not specified, the default is "vfio" on systems where the VFIO + driver is available and loaded, and "kvm" on older systems, or those where + the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that the + default was always "kvm"). +``readonly`` + Indicates that the device is readonly, only supported by SCSI host device + now. :since:`Since 1.0.6 (QEMU and KVM only)` +``shareable`` + If present, this indicates the device is expected to be shared between + domains (assuming the hypervisor and OS support this). Only supported by SCSI + host device. :since:`Since 1.0.6` + + Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did not + work as as expected until :since:`1.2.2` . + +:anchor:`<a id="elementsHostDevCaps"/>` + +Block / character devices +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Block / character devices from the host can be passed through to the guest using +the ``hostdev`` element. This is only possible with container based +virtualization. Devices are specified by a fully qualified path. :since:`since +after 1.0.1 for LXC` : + +:: + + ... + <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> + ... + +``hostdev`` + The ``hostdev`` element is the main container for describing host devices. + For block/character device passthrough ``mode`` is always "capabilities" and + ``type`` is "storage" for a block device, "misc" for a character device and + "net" for a host network interface. +``source`` + The source element describes the device as seen from the host. For block + devices, the path to the block device in the host OS is provided in the + nested "block" element, while for character devices the "char" element is + used. For network interfaces, the name of the interface is provided in the + "interface" element. + +:anchor:`<a id="elementsRedir"/>` + +Redirected devices +~~~~~~~~~~~~~~~~~~ + +USB device redirection through a character device is supported :since:`since +after 0.9.5 (KVM only)` : + +:: + + ... + <devices> + <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 <#elementsConsole>`__ types, to describe the host side of the tunnel; + ``type='tcp'`` or ``type='spicevmc'`` (which uses the usbredir channel of a + `SPICE graphics device <#elementsGraphics>`__) 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 <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` ) +``redirfilter`` + The\ ``redirfilter``\ element is used for creating the filter rule to filter + out certain devices from redirection. It uses sub-element ``<usbdev>`` to + define each filter rule. ``class`` attribute is the USB Class code, for + example, 0x08 represents mass storage devices. The USB device can be + addressed by vendor / product id using the ``vendor`` and ``product`` + attributes. ``version`` is the device revision from the bcdDevice field (not + the version of the USB protocol). These four attributes are optional and + ``-1`` can be used to allow any value for them. ``allow`` attribute is + mandatory, 'yes' means allow, 'no' for deny. + +:anchor:`<a id="elementsSmartcard"/>` + +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:`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 <#elementsConsole>`__ types, to describe the host side of the tunnel; + ``type='tcp'`` or ``type='spicevmc'`` (which uses the smartcard channel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. Further + sub-elements, such as ``<source>``, may be required according to the given + type, although a ``<target>`` sub-element is not required (since the consumer + of the character device is the hypervisor itself, rather than a device + visible in the guest). + +Each mode supports an optional sub-element ``<address>``, which fine-tunes the +correlation between the smartcard and a ccid bus controller, `documented +above <#elementsAddress>`__. For now, qemu only supports at most one smartcard, +with an address of bus=0 slot=0. + +:anchor:`<a id="elementsNICS"/>` + +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'/> + </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:`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 above <#elementsAddress>`__. + +:since:`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. + +:anchor:`<a id="elementsNICSVirtual"/>` + +Virtual network +^^^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts with +dynamic / wireless networking configs (or multi-host environments where the host +hardware details are described separately in a ``<network>`` definition +:since:`Since 0.9.4` ).** + +Provides a connection whose details are described by the named network +definition. Depending on the virtual network's "forward mode" configuration, the +network may be totally isolated (no ``<forward>`` element given), NAT'ing to an +explicit network device or to the default route (``<forward mode='nat'>``), +routed with no NAT (``<forward mode='route'/>``), or connected directly to one +of the host's network interfaces (via macvtap) or bridge devices +((``<forward mode='bridge|private|vepa|passthrough'/>`` :since:`Since +0.9.4` ) + +For networks with a forward mode of bridge, private, vepa, and passthrough, it +is assumed that the host has any necessary DNS and DHCP services already setup +outside the scope of libvirt. In the case of isolated, nat, and routed networks, +DHCP and DNS are provided on the virtual network by libvirt, and the IP range +can be determined by examining the virtual network config with +'``virsh net-dumpxml [networkname]``'. There is one virtual network called +'default' setup out of the box which does NAT'ing to the default route and has +an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an +associated tun device created with a name of vnetN, which can also be overridden +with the <target> element (see `overriding the target +element <#elementsNICSTargetOverride>`__). + +When the source of an interface is a network, a ``portgroup`` can be specified +along with the name of the network; one network may have multiple portgroups +defined, with each portgroup containing slightly different configuration +information for different classes of network connections. :since:`Since 0.9.4` . + +When a guest is running an interface of type ``network`` may include a +``portid`` attribute. This provides the UUID of an associated virNetworkPortPtr +object that records the association between the domain interface and the +network. This attribute is read-only since port objects are create and deleted +automatically during startup and shutdown. :since:`Since 5.1.0` + +Also, similar to ``direct`` network connections (described below), a connection +of type ``network`` may specify a ``virtualport`` element, with configuration +data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch ( +:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Since +0.9.11` ). + +Since the actual type of switch may vary depending on the configuration in the +``<network>`` on the host, it is acceptable to omit the virtualport ``type`` +attribute, and specify attributes from multiple different virtualport types (and +also to leave out certain attributes); at domain startup time, a complete +``<virtualport>`` element will be constructed by merging together the type and +attributes defined in the network and the portgroup referenced by the interface. +The newly-constructed virtualport is a combination of them. The attributes from +lower virtualport can't make change on the ones defined in higher virtualport. +Interface takes the highest priority, portgroup is lowest priority. ( +:since:`Since 0.10.0` ). For example, in order to work properly with both an +802.1Qbh switch and an Open vSwitch switch, you may choose to specify no type, +but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfaceid`` +(in case the switch is Open vSwitch) (you may also omit the other attributes, +such as managerid, typeid, or profileid, to be filled in from the network's +``<virtualport>``). If you want to limit a guest to connecting only to certain +types of switches, you can specify the virtualport type, but still omit some/all +of the parameters - in this case if the host's network has a different type of +virtualport, connection of the interface will fail. + +:: + + ... + <devices> + <interface type='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> + ... + +:anchor:`<a id="elementsNICSBridge"/>` + +Bridge to LAN +^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts with +static wired networking configs.** + +Provides a bridge from the VM directly to the LAN. This assumes there is a +bridge device on the host which has one or more of the hosts physical NICs +attached. The guest VM will have an associated tun device created with a name of +vnetN, which can also be overridden with the <target> element (see `overriding +the target element <#elementsNICSTargetOverride>`__). The tun device will be +attached to the bridge. The IP range / network configuration is whatever is used +on the LAN. This provides the guest VM full incoming & outgoing net access just +like a physical machine. + +On Linux systems, the bridge device is normally a standard Linux host bridge. On +hosts that support Open vSwitch, it is also possible to connect to an Open +vSwitch bridge device by adding a ``<virtualport type='openvswitch'/>`` to the +interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type +virtualport accepts two parameters in its ``<parameters>`` element - an +``interfaceid`` which is a standard uuid used to uniquely identify this +particular interface to Open vSwitch (if you do not specify one, a random +interfaceid will be generated for you when you first define the interface), and +an optional ``profileid`` which is sent to Open vSwitch as the interfaces +"port-profile". + +:: + + ... + <devices> + ... + <interface type='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> + ... + +On hosts that support Open vSwitch on the kernel side and have the Midonet Host +Agent configured, it is also possible to connect to the 'midonet' bridge device +by adding a ``<virtualport type='midonet'/>`` to the interface definition. ( +:since:`Since 1.2.13` ). The Midonet virtualport type requires an +``interfaceid`` attribute in its ``<parameters>`` element. This interface id is +the UUID that specifies which port in the virtual network topology will be bound +to the interface. + +:: + + ... + <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> + ... + +:anchor:`<a id="elementsNICSSlirp"/>` + +Userspace SLIRP stack +^^^^^^^^^^^^^^^^^^^^^ + +Provides a virtual LAN with NAT to the outside world. The virtual network has +DHCP & DNS services and will give the guest VM addresses starting from +``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server will +be ``10.0.2.3``. This networking is the only option for unprivileged users who +need their VMs to have outgoing access. :since:`Since 3.8.0` it is possible to +override the default network address by including an ``ip`` element specifying +an IPv4 address in its one mandatory attribute, ``address``. Optionally, a +second ``ip`` element with a ``family`` attribute set to "ipv6" can be specified +to add an IPv6 address to the interface. ``address``. Optionally, address +``prefix`` can be specified. + +:: + + ... + <devices> + <interface type='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> + ... + +:anchor:`<a id="elementsNICSEthernet"/>` + +Generic ethernet connection +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Provides a means to use a new or existing tap device (or veth device pair, +depening on the needs of the hypervisor driver) that is partially or wholly +setup external to libvirt (either prior to the guest starting, or while the +guest is being started via an optional script specified in the config). + +The name of the tap device can optionally be specified with the ``dev`` +attribute of the ``<target>`` element. If no target dev is specified, libvirt +will create a new standard tap device with a name of the pattern "vnetN", where +"N" is replaced with a number. If a target dev is specified and that device +doesn't exist, then a new standard tap device will be created with the exact dev +name given. If the specified target dev does exist, then that existing device +will be used. Usually some basic setup of the device is done by libvirt, +including setting a MAC address, and the IFF_UP flag, but if the ``dev`` is a +pre-existing device, and the ``managed`` attribute of the ``target`` element is +also set to "no" (the default value is "yes"), even this basic setup will not be +performed - libvirt will simply pass the device on to the hypervisor with no +setup at all. :since:`Since 5.7.0` Using managed='no' with a pre-created tap +device is useful because it permits a virtual machine managed by an unprivileged +libvirtd to have emulated network devices based on tap devices. + +After creating/opening the tap device, an optional shell script (given in the +``path`` attribute of the ``<script>`` element) will be run. :since:`Since +0.2.1` Also, after detaching/closing the tap device, an optional shell script +(given in the ``path`` attribute of the ``<downscript>`` element) will be run. +:since:`Since 5.1.0` These can be used to do whatever extra host network +integration is required. + +:: + + ... + <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> + ... + +:anchor:`<a id="elementsNICSDirect"/>` + +Direct attachment to physical interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +| Provides direct attachment of the virtual machine's NIC to the given physical + interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)` +| This setup requires the Linux macvtap driver to be available. :since:`(Since + Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port + Aggregator' <http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modul...), + 'bridge' or 'private' can be chosen for the operation mode of the macvtap + device, 'vepa' being the default mode. The individual modes cause the delivery + of packets to behave as follows: + +If the model type is set to ``virtio`` and interface's ``trustGuestRxFilters`` +attribute is set to ``yes``, changes made to the interface mac address, +unicast/multicast receive filters, and vlan settings in the guest will be +monitored and propagated to the associated macvtap device on the host ( +:since:`Since 1.2.10` ). If ``trustGuestRxFilters`` is not set, or is not +supported for the device model in use, an attempted change to the mac address +originating from the guest side will result in a non-working network connection. + +``vepa`` + All VMs' packets are sent to the external bridge. Packets whose destination + is a VM on the same host as where the packet originates from are sent back to + the host by the VEPA capable bridge (today's bridges are typically not VEPA + capable). +``bridge`` + Packets whose destination is on the same host as where they originate from + are directly delivered to the target macvtap device. Both origin and + destination devices need to be in bridge mode for direct delivery. If either + one of them is in ``vepa`` mode, a VEPA capable bridge is required. +``private`` + All packets are sent to the external bridge and will only be delivered to a + target VM on the same host if they are sent through an external router or + gateway and that device sends them back to the host. This procedure is + followed if either the source or destination device is in ``private`` mode. +``passthrough`` + This feature attaches a virtual function of a SRIOV capable NIC directly to a + VM without losing the migration capability. All packets are sent to the VF/IF + of the configured network device. Depending on the capabilities of the device + additional prerequisites or limitations may apply; for example, on Linux this + requires kernel 2.6.38 or newer. :since:`Since 0.9.2` + +:: + + ... + <devices> + ... + <interface type='direct' trustGuestRxFilters='no'> + <source dev='eth0' mode='vepa'/> + </interface> + </devices> + ... + +The network access of direct attached virtual machines can be managed by the +hardware switch to which the physical interface of the host machine is connected +to. + +The interface can have additional parameters as shown below, if the switch is +conforming to the IEEE 802.1Qbg standard. The parameters of the virtualport +element are documented in more detail in the IEEE 802.1Qbg standard. The values +are network specific and should be provided by the network administrator. In +802.1Qbg terms, the Virtual Station Interface (VSI) represents the virtual +interface of a virtual machine. :since:`Since 0.8.2` + +Please note that IEEE 802.1Qbg requires a non-zero value for the VLAN ID. + +``managerid`` + The VSI Manager ID identifies the database containing the VSI type and + instance definitions. This is an integer value and the value 0 is reserved. +``typeid`` + The VSI Type ID identifies a VSI type characterizing the network access. VSI + types are typically managed by network administrator. This is an integer + value. +``typeidversion`` + The VSI Type Version allows multiple versions of a VSI Type. This is an + integer value. +``instanceid`` + The VSI Instance ID Identifier is generated when a VSI instance (i.e. a + virtual interface of a virtual machine) is created. This is a globally unique + identifier. + +:: + + ... + <devices> + ... + <interface type='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> + ... + +The interface can have additional parameters as shown below if the switch is +conforming to the IEEE 802.1Qbh standard. The values are network specific and +should be provided by the network administrator. :since:`Since 0.8.2` + +``profileid`` + The profile ID contains the name of the port profile that is to be applied to + this interface. This name is resolved by the port profile database into the + network parameters from the port profile, and those network parameters will + be applied to this interface. + +:: + + ... + <devices> + ... + <interface type='direct'> + <source dev='eth0' mode='private'/> + <virtualport type='802.1Qbh'> + <parameters profileid='finance'/> + </virtualport> + </interface> + </devices> + ... + +:anchor:`<a id="elementsNICSHostdev"/>` + +PCI Passthrough +^^^^^^^^^^^^^^^ + +A PCI network device (specified by the <source> element) is directly assigned to +the guest using generic device passthrough, after first optionally setting the +device's MAC address to the configured value, and associating the device with an +802.1Qbh capable switch using an optionally specified <virtualport> element (see +the examples of virtualport given above for type='direct' network devices). Note +that - due to limitations in standard single-port PCI ethernet card driver +design - only SR-IOV (Single Root I/O Virtualization) virtual function (VF) +devices can be assigned in this manner; to assign a standard single-port PCI or +PCIe ethernet card to a guest, use the traditional <hostdev> device definition +and :since:`Since 0.9.11` + +To use VFIO device assignment rather than traditional/legacy KVM device +assignment (VFIO is a new method of device assignment that is compatible with +UEFI Secure Boot), a type='hostdev' interface can have an optional ``driver`` +sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device +assignment you can set ``name`` to "kvm" (or simply omit the ``<driver>`` +element, since "kvm" is currently the default). :since:`Since 1.0.5 (QEMU and +KVM only, requires kernel 3.6 or newer)` + +Note that this "intelligent passthrough" of network devices is very similar to +the functionality of a standard <hostdev> device, the difference being that this +method allows specifying a MAC address and <virtualport> for the passed-through +device. If these capabilities are not required, if you have a standard +single-port PCI, PCIe, or USB network card that doesn't support SR-IOV (and +hence would anyway lose the configured MAC address during reset after being +assigned to the guest domain), or if you are using a version of libvirt older +than 0.9.11, you should use standard <hostdev> to assign the device to the guest +instead of <interface type='hostdev'/>. + +Similar to the functionality of a standard <hostdev> device, when ``managed`` is +"yes", it is detached from the host before being passed on to the guest, and +reattached to the host after the guest exits. If ``managed`` is omitted or "no", +the user is responsible to call ``virNodeDeviceDettach`` (or +``virsh nodedev-detach``) before starting the guest or hot-plugging the device, +and ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug +or stopping the guest. + +:: + + ... + <devices> + <interface type='hostdev' managed='yes'> + <driver name='vfio'/> + <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> + ... + +:anchor:`<a id="elementsTeaming"/>` + +Teaming a virtio/hostdev NIC pair +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:since:`Since 6.1.0 (QEMU and KVM only, requires QEMU 4.2.0 or newer and a guest +virtio-net driver supporting the "failover" feature, such as the one included in +Linux kernel 4.18 and newer) ` The ``<teaming>`` element of two interfaces can +be used to connect them as a team/bond device in the guest (assuming proper +support in the hypervisor and the guest network driver). + +:: + + ... + <devices> + <interface type='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> + ... + +The ``<teaming>`` element required attribute ``type`` will be set to either +``"persistent"`` to indicate a device that should always be present in the +domain, or ``"transient"`` to indicate a device that may periodically be +removed, then later re-added to the domain. When type="transient", there should +be a second attribute to ``<teaming>`` called ``"persistent"`` - this attribute +should be set to the alias name of the other device in the pair (the one that +has ``<teaming type="persistent'/>``). + +In the particular case of QEMU, libvirt's ``<teaming>`` element is used to setup +a virtio-net "failover" device pair. For this setup, the persistent device must +be an interface with ``<model type="virtio"/>``, and the transient device +must be ``<interface type='hostdev'/>`` (or ``<interface type='network'/>`` +where the referenced network defines a pool of SRIOV VFs). The guest will then +have a simple network team/bond device made of the virtio NIC + hostdev NIC +pair. In this configuration, the higher-performing hostdev NIC will normally be +preferred for all network traffic, but when the domain is migrated, QEMU will +automatically unplug the VF from the guest, and then hotplug a similar device +once migration is completed; while migration is taking place, network traffic +will use the virtio NIC. (Of course the emulated virtio NIC and the hostdev NIC +must be connected to the same subnet for bonding to work properly). + +NB1: Since you must know the alias name of the virtio NIC when configuring the +hostdev NIC, it will need to be manually set in the virtio NIC's configuration +(as with all other manually set alias names, this means it must start with +"ua-"). + +NB2: Currently the only implementation of the guest OS virtio-net driver +supporting virtio-net failover requires that the MAC addresses of the virtio and +hostdev NIC must match. Since that may not always be a requirement in the +future, libvirt doesn't enforce this limitation - it is up to the +person/management application that is creating the configuration to assure the +MAC addresses of the two devices match. + +NB3: Since the PCI addresses of the SRIOV VFs on the hosts that are the source +and destination of the migration will almost certainly be different, either +higher level management software will need to modify the ``<source>`` of the +hostdev NIC (``<interface type='hostdev'>``) at the start of migration, or (a +simpler solution) the configuration will need to use a libvirt "hostdev" virtual +network that maintains a pool of such devices, as is implied in the example's +use of the libvirt network named "hostdev-pool" - as long as the hostdev network +pools on both hosts have the same name, libvirt itself will take care of +allocating an appropriate device on both ends of the migration. Similarly the +XML for the virtio interface must also either work correctly unmodified on both +the source and destination of the migration (e.g. by connecting to the same +bridge device on both hosts, or by using the same virtual network), or the +management software must properly modify the interface XML during migration so +that the virtio device remains connected to the same network segment before and +after migration. + +:anchor:`<a id="elementsNICSMulticast"/>` + +Multicast tunnel +^^^^^^^^^^^^^^^^ + +A multicast group is setup to represent a virtual network. Any VMs whose network +devices are in the same multicast group can talk to each other even across +hosts. This mode is also available to unprivileged users. There is no default +DNS or DHCP support and no outgoing network access. To provide outgoing network +access, one of the VMs should have a 2nd NIC which is connected to one of the +first 4 network types and do the appropriate routing. The multicast protocol is +compatible with that used by user mode linux guests too. The source address used +must be from the multicast address block. + +:: + + ... + <devices> + <interface type='mcast'> + <mac address='52:54:00:6d:90:01'/> + <source address='230.0.0.1' port='5558'/> + </interface> + </devices> + ... + +:anchor:`<a id="elementsNICSTCP"/>` + +TCP tunnel +^^^^^^^^^^ + +A TCP client/server architecture provides a virtual network. One VM provides the +server end of the network, all other VMS are configured as clients. All network +traffic is routed between the VMs via the server. This mode is also available to +unprivileged users. There is no default DNS or DHCP support and no outgoing +network access. To provide outgoing network access, one of the VMs should have a +2nd NIC which is connected to one of the first 4 network types and do the +appropriate routing. + +:: + + ... + <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> + ... + +:anchor:`<a id="elementsNICSUDP"/>` + +UDP unicast tunnel +^^^^^^^^^^^^^^^^^^ + +A UDP unicast architecture provides a virtual network which enables connections +between QEMU instances using QEMU's UDP infrastructure. The xml "source" address +is the endpoint address to which the UDP socket packets will be sent from the +host running QEMU. The xml "local" address is the address of the interface from +which the UDP socket packets will originate from the QEMU host. :since:`Since +1.2.20` + +:: + + ... + <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> + ... + +:anchor:`<a id="elementsNICSModel"/>` + +Setting the NIC model +^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <target dev='vnet1'/> + <model type='ne2k_pci'/> + </interface> + </devices> + ... + +For hypervisors which support this, you can set the model of emulated network +interface card. + +The values for ``type`` aren't defined specifically by libvirt, but by what the +underlying hypervisor supports (if any). For QEMU and KVM you can get a list of +supported models with these commands: + +:: + + qemu -net nic,model=? /dev/null + qemu-kvm -net nic,model=? /dev/null + +Typical values for QEMU and KVM include: ne2k_isa i82551 i82557b i82559er +ne2k_pci pcnet rtl8139 e1000 virtio. :since:`Since 5.2.0` , +``virtio-transitional`` and ``virtio-non-transitional`` values are supported. +See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more +details. + +:anchor:`<a id="elementsDriverBackendOptions"/>` + +Setting NIC driver-specific options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <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> + ... + +Some NICs may have tunable driver-specific options. These are set as attributes +of the ``driver`` sub-element of the interface definition. Currently the +following attributes are available for the ``"virtio"`` NIC driver: + +``name`` + The optional ``name`` attribute forces which type of backend driver to use. + The value can be either 'qemu' (a user-space backend) or 'vhost' (a kernel + backend, which requires the vhost module to be provided by the kernel); an + attempt to require the vhost driver without kernel support will be rejected. + If this attribute is not present, then the domain defaults to 'vhost' if + present, but silently falls back to 'qemu' without error. :since:`Since 0.8.8 + (QEMU and KVM only)` + For interfaces of type='hostdev' (PCI passthrough devices) the ``name`` + attribute can optionally be set to "vfio" or "kvm". "vfio" tells libvirt to + use VFIO device assignment rather than traditional KVM device assignment + (VFIO is a new method of device assignment that is compatible with UEFI + Secure Boot), and "kvm" tells libvirt to use the legacy device assignment + performed directly by the kvm kernel module (the default is currently "kvm", + but is subject to change). :since:`Since 1.0.5 (QEMU and KVM only, requires + kernel 3.6 or newer)` + For interfaces of type='vhostuser', the ``name`` attribute is ignored. The + backend driver used is always vhost-user. +``txmode`` + The ``txmode`` attribute specifies how to handle transmission of packets when + the transmit buffer is full. The value can be either 'iothread' or 'timer'. + :since:`Since 0.8.8 (QEMU and KVM only)` + If set to 'iothread', packet tx is all done in an iothread in the bottom half + of the driver (this option translates into adding "tx=bh" to the qemu + commandline -device virtio-net-pci option). + If set to 'timer', tx work is done in qemu, and if there is more tx data than + can be sent at the present time, a timer is set before qemu moves on to do + other things; when the timer fires, another attempt is made to send more + data. + The resulting difference, according to the qemu developer who added the + option is: "bh makes tx more asynchronous and reduces latency, but + potentially causes more processor bandwidth contention since the CPU doing + the tx isn't necessarily the CPU where the guest generated the packets." + **In general you should leave this option alone, unless you are very certain + you know what you are doing.** +``ioeventfd`` + This optional attribute allows users to set `domain I/O asynchronous + handling <https://patchwork.kernel.org/patch/43390/>`__ for interface device. + The default is left to the discretion of the hypervisor. Accepted values are + "on" and "off". Enabling this allows qemu to execute VM while a separate + thread handles I/O. Typically guests experiencing high system CPU utilization + during I/O will benefit from this. On the other hand, on overloaded host it + could increase guest I/O latency. :since:`Since 0.9.3 (QEMU and KVM only)` + **In general you should leave this option alone, unless you are very certain + you know what you are doing.** +``event_idx`` + The ``event_idx`` attribute controls some aspects of device event processing. + The value can be either 'on' or 'off' - if it is on, it will reduce the + number of interrupts and exits for the guest. The default is determined by + QEMU; usually if the feature is supported, default is on. In case there is a + situation where this behavior is suboptimal, this attribute provides a way to + force the feature off. :since:`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.** +``queues`` + The optional ``queues`` attribute controls the number of queues to be used + for either `Multiqueue + virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or + `vhost-user <#elementVhostuser>`__ network interfaces. Use of multiple packet + processing queues requires the interface having the + ``<model type='virtio'/>`` element. Each queue will potentially be handled by + a different processor, resulting in much higher throughput. + :since:`virtio-net since 1.0.6 (QEMU and KVM only)` :since:`vhost-user since + 1.2.17 (QEMU and KVM only)` +``rx_queue_size`` + The optional ``rx_queue_size`` attribute controls the size of virtio ring for + each queue as described above. The default value is hypervisor dependent and + may change across its releases. Moreover, some hypervisors may pose some + restrictions on actual value. For instance, latest QEMU (as of 2016-09-01) + requires value to be a power of two from [256, 1024] range. :since:`Since + 2.3.0 (QEMU and KVM only)` + **In general you should leave this option alone, unless you are very certain + you know what you are doing.** +``tx_queue_size`` + The optional ``tx_queue_size`` attribute controls the size of virtio ring for + each queue as described above. The default value is hypervisor dependent and + may change across its releases. Moreover, some hypervisors may pose some + restrictions on actual value. For instance, QEMU v2.9 requires value to be a + power of two from [256, 1024] range. In addition to that, this may work only + for a subset of interface types, e.g. aforementioned QEMU enables this option + only for ``vhostuser`` type. :since:`Since 3.7.0 (QEMU and KVM only)` + **In general you should leave this option alone, unless you are very certain + you know what you are doing.** +virtio options + For virtio interfaces, `Virtio-specific options <#elementsVirtio>`__ can also + be set. ( :since:`Since 3.5.0` ) + +Offloading options for the host and guest can be configured using the following +sub-elements: + +``host`` + The ``csum``, ``gso``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes + with possible values ``on`` and ``off`` can be used to turn off host + offloading options. By default, the supported offloads are enabled by QEMU. + :since:`Since 1.2.9 (QEMU only)` The ``mrg_rxbuf`` attribute can be used to + control mergeable rx buffers on the host side. Possible values are ``on`` + (default) and ``off``. :since:`Since 1.2.13 (QEMU only)` +``guest`` + The ``csum``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes with + possible values ``on`` and ``off`` can be used to turn off guest offloading + options. By default, the supported offloads are enabled by QEMU. + :since:`Since 1.2.9 (QEMU only)` + +:anchor:`<a id="elementsBackendOptions"/>` + +Setting network backend-specific options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <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> + ... + +For tuning the backend of the network, the ``backend`` element can be used. The +``vhost`` attribute can override the default vhost device path +(``/dev/vhost-net``) for devices with ``virtio`` model. The ``tap`` attribute +overrides the tun/tap device path (default: ``/dev/net/tun``) for network and +bridge interfaces. This does not work in session mode. :since:`Since 1.2.9` + +For tap devices there is also ``sndbuf`` element which can adjust the size of +send buffer in the host. :since:`Since 0.8.8` + +:anchor:`<a id="elementsNICSTargetOverride"/>` + +Overriding the target element +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <target dev='vnet1'/> + </interface> + </devices> + ... + +If no target is specified, certain hypervisors will automatically generate a +name for the created tun device. This name can be manually specified, however +the name *should not start with either 'vnet', 'vif', 'macvtap', or 'macvlan'*, +which are prefixes reserved by libvirt and certain hypervisors. Manually +specified targets using these prefixes may be ignored. + +Note that for LXC containers, this defines the name of the interface on the host +side. :since:`Since 1.2.7` , to define the name of the device on the guest side, +the ``guest`` element should be used, as in the following snippet: + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <guest dev='myeth'/> + </interface> + </devices> + ... + +:anchor:`<a id="elementsNICSBoot"/>` + +Specifying boot order +^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <target dev='vnet1'/> + <boot order='1'/> + </interface> + </devices> + ... + +For hypervisors which support this, you can set a specific NIC to be used for +network boot. The ``order`` attribute determines the order in which devices will +be tried during boot sequence. The per-device ``boot`` elements cannot be used +together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__ +section. :since:`Since 0.8.8` + +:anchor:`<a id="elementsNICSROM"/>` + +Interface ROM BIOS configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <target dev='vnet1'/> + <rom bar='on' file='/etc/fake/boot.bin'/> + </interface> + </devices> + ... + +For hypervisors which support this, you can change how a PCI Network device's +ROM is presented to the guest. The ``bar`` attribute can be set to "on" or +"off", and determines whether or not the device's ROM will be visible in the +guest's memory map. (In PCI documentation, the "rombar" setting controls the +presence of the Base Address Register for the ROM). If no rom bar is specified, +the qemu default will be used (older versions of qemu used a default of "off", +while newer qemus have a default of "on"). The optional ``file`` attribute is +used to point to a binary file to be presented to the guest as the device's ROM +BIOS. This can be useful to provide an alternative boot ROM for a network +device. :since:`Since 0.9.10 (QEMU and KVM only)` . + +:anchor:`<a id="elementDomain"/>` + +Setting up a network backend in a driver domain +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + ... + <interface type='bridge'> + <source bridge='br0'/> + <backenddomain name='netvm'/> + </interface> + ... + </devices> + ... + +The optional ``backenddomain`` element allows specifying a backend domain (aka +driver domain) for the interface. Use the ``name`` attribute to specify the +backend domain name. You can use it to create a direct network link between +domains (so data will not go through host system). Use with type 'ethernet' to +create plain network link, or with type 'bridge' to connect to a bridge inside +the backend domain. :since:`Since 1.2.13 (Xen only)` + +:anchor:`<a id="elementQoS"/>` + +Quality of service +^^^^^^^^^^^^^^^^^^ + +:: + + ... + <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> + ... + +This part of interface XML provides setting quality of service. Incoming and +outgoing traffic can be shaped independently. The ``bandwidth`` element and its +child elements are described in the `QoS <formatnetwork.html#elementQoS>`__ +section of the Network XML. + +:anchor:`<a id="elementVlanTag"/>` + +Setting VLAN tag (on supported network types only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <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> + ... + +If (and only if) the network connection used by the guest supports VLAN tagging +transparent to the guest, an optional ``<vlan>`` element can specify one or more +VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` . +Network connections that support guest-transparent VLAN tagging include 1) +type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since +0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device +assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with +mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other +connection types, including standard linux bridges and libvirt's own virtual +networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches +provide their own way (outside of libvirt) to tag guest traffic onto a specific +VLAN. Each tag is given in a separate ``<tag>`` subelement of ``<vlan>`` (for +example: ``<tag id='42'/>``). For VLAN trunking of multiple tags (which is +supported only on Open vSwitch connections), multiple ``<tag>`` subelements can +be specified, which implies that the user wants to do VLAN trunking on the +interface for all the specified tags. In the case that VLAN trunking of a single +tag is desired, the optional attribute ``trunk='yes'`` can be added to the +toplevel ``<vlan>`` element to differentiate trunking of a single tag from +normal tagging. + +For network connections using Open vSwitch it is also possible to configure +'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is +done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement: +``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the +``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to +be the "native" VLAN for this interface, and the ``nativeMode`` attribute +determines whether or not traffic for that VLAN will be tagged. + +:anchor:`<a id="elementPort"/>` + +Isolating guests's network traffic from each other +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <port isolated='yes'/> + </interface> + </devices> + ... + +:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to +``yes`` (default setting is ``no``) is used to isolate this interface's network +traffic from that of other guest interfaces connected to the same network that +also have ``<port isolated='yes'/>``. This setting is only supported for +emulated interface devices that use a standard tap device to connect to the +network via a Linux host bridge. This property can be inherited from a libvirt +network, so if all guests that will be connected to the network should be +isolated, it is better to put the setting in the network configuration. (NB: +this only prevents guests that have ``isolated='yes'`` from communicating with +each other; if there is a guest on the same bridge that doesn't have +``isolated='yes'``, even the isolated guests will be able to communicate with +it.) + +:anchor:`<a id="elementLink"/>` + +Modifying virtual link state +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <target dev='vnet0'/> + <link state='down'/> + </interface> + </devices> + ... + +This element provides means of setting state of the virtual network link. +Possible values for attribute ``state`` are ``up`` and ``down``. If ``down`` is +specified as the value, the interface behaves as if it had the network cable +disconnected. Default behavior if this element is unspecified is to have the +link state ``up``. :since:`Since 0.9.5` + +:anchor:`<a id="mtu"/>` + +MTU configuration +^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <target dev='vnet0'/> + <mtu size='1500'/> + </interface> + </devices> + ... + +This element provides means of setting MTU of the virtual network link. +Currently there is just one attribute ``size`` which accepts a non-negative +integer which specifies the MTU size for the interface. :since:`Since 3.1.0` + +:anchor:`<a id="coalesce"/>` + +Coalesce settings +^^^^^^^^^^^^^^^^^ + +:: + + ... + <devices> + <interface type='network'> + <source network='default'/> + <target dev='vnet0'/> + <coalesce> + <rx> + <frames max='7'/> + </rx> + </coalesce> + </interface> + </devices> + ... + +This element provides means of setting coalesce settings for some interface +devices (currently only type ``network`` and ``bridge``. Currently there is just +one attribute, ``max``, to tweak, in element ``frames`` for the ``rx`` group, +which accepts a non-negative integer that specifies the maximum number of +packets that will be received before an interrupt. :since:`Since 3.3.0` + +:anchor:`<a id="ipconfig"/>` + +IP configuration +^^^^^^^^^^^^^^^^ + +:: + + ... + <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> + ... + +:since:`Since 1.2.12` network devices and hostdev devices with network +capabilities can optionally be provided one or more IP addresses to set on the +network device in the guest. Note that some hypervisors or network device types +will simply ignore them or only use the first one. The ``family`` attribute can +be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains +the IP address. The optional ``prefix`` is the number of 1 bits in the netmask, +and will be automatically set if not specified - for IPv4 the default prefix is +determined according to the network "class" (A, B, or C - see RFC870), and for +IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP +address of the other end of a point-to-point network device :since:`(since +2.1.0)` . + +:since:`Since 1.2.12` route elements can also be added to define IP routes to +add in the guest. The attributes of this element are described in the +documentation for the ``route`` element in `network +definitions <formatnetwork.html#elementsStaticroute>`__. This is used by the LXC +driver. + +:: + + ... + <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> + ... + +:since:`Since 2.1.0` network devices of type "ethernet" can optionally be +provided one or more IP addresses and one or more routes to set on the **host** +side of the network device. These are configured as subelements of the +``<source>`` element of the interface, and have the same attributes as the +similarly named elements used to configure the guest side of the interface +(described above). + +:anchor:`<a id="elementVhostuser"/>` + +vhost-user interface +^^^^^^^^^^^^^^^^^^^^ + +:since:`Since 1.2.7` the vhost-user enables the communication between a QEMU +virtual machine and other userspace process using the Virtio transport protocol. +A char dev (e.g. Unix socket) is used for the control plane, while the data +plane is based on shared memory. + +:: + + ... + <devices> + <interface type='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> + ... + +The ``<source>`` element has to be specified along with the type of char device. +Currently, only type='unix' is supported, where the path (the directory path of +the socket) and mode attributes are required. Both ``mode='server'`` and +``mode='client'`` are supported. vhost-user requires the virtio model type, thus +the ``<model>`` element is mandatory. :since:`Since 4.1.0` the element has an +optional child element ``reconnect`` which configures reconnect timeout if the +connection is lost. It has two attributes ``enabled`` (which accepts ``yes`` and +``no``) and ``timeout`` which specifies the amount of seconds after which +hypervisor tries to reconnect. + +:anchor:`<a id="elementNwfilter"/>` + +Traffic filtering with NWFilter +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:since:`Since 0.8.0` an ``nwfilter`` profile can be assigned to a domain +interface, which allows configuring traffic filter rules for the virtual +machine. See the `nwfilter <formatnwfilter.html>`__ documentation for more +complete details. + +:: + + ... + <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> + ... + +The ``filter`` attribute specifies the name of the nwfilter to use. Optional +``<parameter>`` elements may be specified for passing additional info to the +nwfilter via the ``name`` and ``value`` attributes. See the +`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters. + +:anchor:`<a id="elementsInput"/>` + +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> + </devices> + ... + +``input`` + The ``input`` element has one mandatory attribute, the ``type`` whose value + can be 'mouse', 'tablet', ( :since:`since 1.2.2` ) 'keyboard' or ( + :since:`since 1.3.0` ) 'passthrough'. The tablet provides absolute cursor + movement, while the mouse uses relative movement. The optional ``bus`` + attribute can be used to refine the exact device type. It takes values "xen" + (paravirtualized), "ps2" and "usb" or ( :since:`since 1.3.0` ) "virtio". + +The ``input`` element has an optional sub-element ``<address>`` which can tie +the device to a particular PCI slot, `documented above <#elementsAddress>`__. On +S390, ``address`` can be used to provide a CCW address for an input device ( +:since:`since 4.2.0` ). For type ``passthrough``, the mandatory sub-element +``source`` must have an ``evdev`` attribute containing the absolute path to the +event device passed through to guests. (KVM only) :since:`Since 5.2.0` , the +``input`` element accepts a ``model`` attribute which has the values 'virtio', +'virtio-transitional' and 'virtio-non-transitional'. See `Virtio transitional +devices <#elementsVirtioTransitional>`__ for more details. + +The subelement ``driver`` can be used to tune the virtio options of the device: +`Virtio-specific options <#elementsVirtio>`__ can also be set. ( :since:`Since +3.5.0` ) + +:anchor:`<a id="elementsHub"/>` + +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>`` with +``type='usb'``\ which can tie the device to a particular controller, `documented +above <#elementsAddress>`__. + +:anchor:`<a id="elementsGraphics"/>` + +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:`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:`since 1.0.6` . + + Rather than using listen/port, QEMU supports a ``socket`` attribute for + listening on a unix domain socket path :since:`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:`Since + 1.0.6` . + + 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. + + ``spice`` :since:`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:`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:`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:` since 0.8.6` ); ``smartcard`` ( :since:`since 0.8.8` ); and + ``usbredir`` ( :since:`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:`Since 0.9.1` + + Streaming mode is set by the ``streaming`` element, settings its ``mode`` + attribute to one of ``filter``, ``all`` or ``off``. :since:`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:`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:`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:`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:`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:`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:`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 :since:`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> + +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:`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:`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:`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:`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``. + +:anchor:`<a id="elementsVideo"/>` + +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:`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:`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:`since 0.8.6` + ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs" + ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" ( + :since:`since 4.6.0` , depending on the hypervisor features available. The + purpose of the type ``none`` is to instruct libvirt not to add a default + video device in the guest (see the paragraph above). This legacy behaviour + can be inconvenient in cases where GPU mediated devices are meant to be the + only rendering device within a guest and so specifying another ``video`` + device along with type ``none``. Refer to Host device assignment to see how + to add a mediated device into a guest. + + You can provide the amount of video memory in kibibytes (blocks of 1024 + bytes) using ``vram``. This is supported only for guest type of "vz", "qemu", + "vbox", "vmx" and "xen". If no value is provided the default is used. If the + size is not a 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", "vbox" and "vmx". + + For guest type of "kvm" or "qemu" and model type "qxl" there are optional + attributes. Attribute ``ram`` ( :since:` 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:`since 1.2.11` ) to set the size of + VGA framebuffer for fallback mode of QXL device. Attribute ``vram64`` ( + :since:`since 1.3.3` ) extends secondary bar and makes it addressable as + 64bit memory. + + :since:`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", and "virtio". + +``acceleration`` + Configure if video acceleration should be enabled. + + ``accel2d`` + Enable 2D acceleration (for vbox driver only, :since:`since 0.7.1` ) + ``accel3d`` + Enable 3D acceleration (for vbox driver :since:`since 0.7.1` , qemu driver + :since:`since 1.3.0` ) + ``rendernode`` + Absolute path to a host's DRI device to be used for rendering (for + 'vhostuser' driver only, :since:`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:` 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:`since 5.8.0` ). "qemu" is + the default QEMU backend. "vhostuser" will use a separate vhost-user + process backend (for ``virtio`` device). + virtio options + `Virtio-specific options <#elementsVirtio>`__ can also be set ( + :since:`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:`Since 3.5.0` ) + +:anchor:`<a id="elementsConsole"/>` + +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 <#seclabel>`__. + +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:`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:`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 <#elementsControllers>`__ 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:`Since 3.7.0 (QEMU driver +only)` . + +:anchor:`<a id="elementsCharGuestInterface"/>` + +Guest interface +^^^^^^^^^^^^^^^ + +A character device presents itself to the guest as one of the following types. + +:anchor:`<a id="elementCharParallel"/>` + +Parallel port +''''''''''''' + +:: + + ... + <devices> + <parallel type='pty'> + <source path='/dev/pts/2'/> + <target port='0'/> + </parallel> + </devices> + ... + +``target`` can have a ``port`` attribute, which specifies the port number. Ports +are numbered starting from 0. There are usually 0, 1 or 2 parallel ports. + +:anchor:`<a id="elementCharSerial"/>` + +Serial port +''''''''''' + +:: + + ... + <devices> + <!-- Serial port --> + <serial type='pty'> + <source path='/dev/pts/3'/> + <target port='0'/> + </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> + ... + +The ``target`` element can have an optional ``port`` attribute, which specifies +the port number (starting from 0), and an optional ``type`` attribute: valid +values are, :since:`since 1.0.2` , ``isa-serial`` (usable with x86 guests), +``usb-serial`` (usable whenever USB support is available) and ``pci-serial`` +(usable whenever PCI support is available); :since:`since 3.10.0` , +``spapr-vio-serial`` (usable with ppc64/pseries guests), ``system-serial`` +(usable with aarch64/virt and, :since:`since 4.7.0` , riscv/virt guests) and +``sclp-serial`` (usable with s390 and s390x guests) are available as well. + +:since:`Since 3.10.0` , the ``target`` element can have an optional ``model`` +subelement; valid values for its ``name`` attribute are: ``isa-serial`` (usable +with the ``isa-serial`` target type); ``usb-serial`` (usable with the +``usb-serial`` target type); ``pci-serial`` (usable with the ``pci-serial`` +target type); ``spapr-vty`` (usable with the ``spapr-vio-serial`` target type); +``pl011`` and, :since:`since 4.7.0` , ``16550a`` (usable with the +``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable +with the ``sclp-serial`` target type). Providing a target model is usually +unnecessary: libvirt will automatically pick one that's suitable for the chosen +target type, and overriding that value is generally not recommended. + +If any of the attributes is not specified by the user, libvirt will choose a +value suitable for most users. + +Most target types support configuring the guest-visible device address as +`documented above <#elementsAddress>`__; more specifically, acceptable address +types are ``isa`` (for ``isa-serial``), ``usb`` (for ``usb-serial``), ``pci`` +(for ``pci-serial``) and ``spapr-vio`` (for ``spapr-vio-serial``). The +``system-serial`` and ``sclp-serial`` target types don't support specifying an +address. + +For the relationship between serial ports and consoles, `see +below <#elementCharSerialAndConsole>`__. + +:anchor:`<a id="elementCharConsole"/>` + +Console +''''''' + +:: + + ... + <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> + ... + +The ``console`` element is used to represent interactive serial consoles. +Depending on the type of guest in use and the specifics of the configuration, +the ``console`` element might represent the same device as an existing +``serial`` element or a separate device. + +A ``target`` subelement is supported and works the same way as with the +``serial`` element (`see above <#elementCharSerial>`__ for details). Valid +values for the ``type`` attribute are: ``serial`` (described below); ``virtio`` +(usable whenever VirtIO support is available); ``xen``, ``lxc`` and ``openvz`` +(available when the corresponding hypervisor is in use). ``sclp`` and ``sclplm`` +(usable for s390 and s390x QEMU guests) are supported for compatibility reasons +but should not be used for new guests: use the ``sclpconsole`` and +``sclplmconsole`` target models, respectively, with the ``serial`` element +instead. + +Of the target types listed above, ``serial`` is special in that it doesn't +represents a separate device, but rather the same device as the first ``serial`` +element. Due to this, there can only be a single ``console`` element with target +type ``serial`` per guest. + +Virtio consoles are usually accessible as ``/dev/hvc[0-7]`` from inside the +guest; for more information, see +http://fedoraproject.org/wiki/Features/VirtioSerial. :since:`Since 0.8.3` + +For the relationship between serial ports and consoles, `see +below <#elementCharSerialAndConsole>`__. + +:anchor:`<a id="elementCharSerialAndConsole"/>` + +Relationship between serial ports and consoles +'''''''''''''''''''''''''''''''''''''''''''''' + +Due to hystorical reasons, the ``serial`` and ``console`` elements have +partially overlapping scopes. + +In general, both elements are used to configure one or more serial consoles to +be used for interacting with the guest. The main difference between the two is +that ``serial`` is used for emulated, usually native, serial consoles, whereas +``console`` is used for paravirtualized ones. + +Both emulated and paravirtualized serial consoles have advantages and +disadvantages: + +- emulated serial consoles are usually initialized much earlier than + paravirtualized ones, so they can be used to control the bootloader and + display both firmware and early boot messages; +- on several platforms, there can only be a single emulated serial console per + guest but paravirtualized consoles don't suffer from the same limitation. + +A configuration such as: + +:: + + ... + <devices> + <console type='pty'> + <target type='serial'/> + </console> + <console type='pty'> + <target type='virtio'/> + </console> + </devices> + ... + +will work on any platform and will result in one emulated serial console for +early boot logging / interactive / recovery use, and one paravirtualized serial +console to be used eg. as a side channel. Most people will be fine with having +just the first ``console`` element in their configuration, but if a specific +configuration is desired then both elements should be specified. + +Note that, due to the compatibility concerns mentioned earlier, all the +following configurations: + +:: + + ... + <devices> + <serial type='pty'/> + </devices> + ... + +:: + + ... + <devices> + <console type='pty'/> + </devices> + ... + +:: + + ... + <devices> + <serial type='pty'/> + <console type='pty'/> + </devices> + ... + +will be treated the same and will result in a single emulated serial console +being available to the guest. + +:anchor:`<a id="elementCharChannel"/>` + +Channel +''''''' + +This represents a private communication channel between the host and the guest. + +:: + + ... + <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> + ... + +This can be implemented in a variety of ways. The specific type of channel is +given in the ``type`` attribute of the ``target`` element. Different channel +types have different ``target`` attributes. + +``guestfwd`` + TCP traffic sent by the guest to a given IP address and port is forwarded to + the channel device on the host. The ``target`` element must have ``address`` + and ``port`` attributes. :since:`Since 0.7.3` +``virtio`` + Paravirtualized virtio channel. Channel is exposed in the guest under + /dev/vport*, and if the optional element ``name`` is specified, + /dev/virtio-ports/$name (for more info, please see + http://fedoraproject.org/wiki/Features/VirtioSerial). The optional element + ``address`` can tie the channel to a particular ``type='virtio-serial'`` + controller, `documented above <#elementsAddress>`__. With qemu, if ``name`` + is "org.qemu.guest_agent.0", then libvirt can interact with a guest agent + installed in the guest, for actions such as guest shutdown or file system + quiescing. :since:`Since 0.7.7, guest agent interaction since 0.9.10` + Moreover, :since:`since 1.0.6` it is possible to have source path auto + generated for virtio unix channels. This is very useful in case of a qemu + guest agent, where users don't usually care about the source path since it's + libvirt who talks to the guest agent. In case users want to utilize this + feature, they should leave ``<source>`` element out. :since:`Since 1.2.11` + the active XML for a virtio channel may contain an optional ``state`` + attribute that reflects whether a process in the guest is active on the + channel. This is an output-only attribute. Possible values for the ``state`` + attribute are ``connected`` and ``disconnected``. +``xen`` + Paravirtualized Xen channel. Channel is exposed in the guest as a Xen console + but identified with a name. Setup and consumption of a Xen channel depends on + software and configuration in the guest (for more info, please see + http://xenbits.xen.org/docs/unstable/misc/channel.txt). Channel source path + semantics are the same as the virtio target type. The ``state`` attribute is + not supported since Xen channels lack the necessary probing mechanism. + :since:`Since 2.3.0` +``spicevmc`` + Paravirtualized SPICE channel. The domain must also have a SPICE server as a + `graphics device <#elementsGraphics>`__, at which point the host piggy-backs + messages across the ``main`` channel. The ``target`` element must be present, + with attribute ``type='virtio'``; an optional attribute ``name`` controls how + the guest will have access to the channel, and defaults to + ``name='com.redhat.spice.0'``. The optional ``address`` element can tie the + channel to a particular ``type='virtio-serial'`` controller. :since:`Since + 0.8.8` + +:anchor:`<a id="elementsCharHostInterface"/>` + +Host interface +^^^^^^^^^^^^^^ + +A character device presents itself to the host as one of the following types. + +:anchor:`<a id="elementsCharSTDIO"/>` + +Domain logfile +'''''''''''''' + +This disables all input on the character device, and sends output into the +virtual machine's logfile + +:: + + ... + <devices> + <console type='stdio'> + <target port='1'/> + </console> + </devices> + ... + +:anchor:`<a id="elementsCharFle"/>` + +Device logfile +'''''''''''''' + +A file is opened and all data sent to the character device is written to the +file. + +:: + + ... + <devices> + <serial type="file"> + <source path="/var/log/vm/vm-serial.log"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharVC"/>` + +Virtual console +''''''''''''''' + +Connects the character device to the graphical framebuffer in a virtual console. +This is typically accessed via a special hotkey sequence such as "ctrl+alt+3" + +:: + + ... + <devices> + <serial type='vc'> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharNull"/>` + +Null device +''''''''''' + +Connects the character device to the void. No data is ever provided to the +input. All data written is discarded. + +:: + + ... + <devices> + <serial type='null'> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharPTY"/>` + +Pseudo TTY +'''''''''' + +A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as 'virsh +console' can connect to interact with the serial port locally. + +:: + + ... + <devices> + <serial type="pty"> + <source path="/dev/pts/3"/> + <target port="1"/> + </serial> + </devices> + ... + +NB special case if <console type='pty'>, then the TTY path is also duplicated as +an attribute tty='/dev/pts/3' on the top level <console> tag. This provides +compat with existing syntax for <console> tags. + +:anchor:`<a id="elementsCharHost"/>` + +Host device proxy +''''''''''''''''' + +The character device is passed through to the underlying physical character +device. The device types must match, eg the emulated serial port should only be +connected to a host serial port - don't connect a serial port to a parallel +port. + +:: + + ... + <devices> + <serial type="dev"> + <source path="/dev/ttyS0"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharPipe"/>` + +Named pipe +'''''''''' + +The character device writes output to a named pipe. See pipe(7) for more info. + +:: + + ... + <devices> + <serial type="pipe"> + <source path="/tmp/mypipe"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharTCP"/>` + +TCP client/server +''''''''''''''''' + +The character device acts as a TCP client connecting to a remote server. + +:: + + ... + <devices> + <serial type="tcp"> + <source mode="connect" host="0.0.0.0" service="2445"/> + <protocol type="raw"/> + <target port="1"/> + </serial> + </devices> + ... + +Or as a TCP server waiting for a client connection. + +:: + + ... + <devices> + <serial type="tcp"> + <source mode="bind" host="127.0.0.1" service="2445"/> + <protocol type="raw"/> + <target port="1"/> + </serial> + </devices> + ... + +Alternatively you can use ``telnet`` instead of ``raw`` TCP in order to utilize +the telnet protocol for the connection. + +:since:`Since 0.8.5,` some hypervisors support use of either ``telnets`` (secure +telnet) or ``tls`` (via secure sockets layer) as the transport protocol for +connections. + +:: + + ... + <devices> + <serial type="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> + ... + +:since:`Since 2.4.0,` the optional attribute ``tls`` can be used to control +whether a chardev TCP communication channel would utilize a hypervisor +configured TLS X.509 certificate environment in order to encrypt the data +channel. For the QEMU hypervisor, usage of a TLS environment can be controlled +on the host by the ``chardev_tls`` and ``chardev_tls_x509_cert_dir`` or +``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf. If +``chardev_tls`` is enabled, then unless the ``tls`` attribute is set to "no", +libvirt will use the host configured TLS environment. If ``chardev_tls`` is +disabled, but the ``tls`` attribute is set to "yes", then libvirt will attempt +to use the host TLS environment if either the ``chardev_tls_x509_cert_dir`` or +``default_tls_x509_cert_dir`` TLS directory structure exists. + +:: + + ... + <devices> + <serial type="tcp"> + <source mode='connect' host="127.0.0.1" service="5555" tls="yes"/> + <protocol type="raw"/> + <target port="0"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharUDP"/>` + +UDP network console +''''''''''''''''''' + +The character device acts as a UDP netconsole service, sending and receiving +packets. This is a lossy service. + +:: + + ... + <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> + ... + +:anchor:`<a id="elementsCharUNIX"/>` + +UNIX domain socket client/server +'''''''''''''''''''''''''''''''' + +The character device acts as a UNIX domain socket server, accepting connections +from local clients. + +:: + + ... + <devices> + <serial type="unix"> + <source mode="bind" path="/tmp/foo"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharSpiceport"/>` + +Spice channel +''''''''''''' + +The character device is accessible through spice connection under a channel name +specified in the ``channel`` attribute. :since:`Since 1.2.2` + +Note: depending on the hypervisor, spiceports might (or might not) be enabled on +domains with or without `spice graphics <#elementsGraphics>`__. + +:: + + ... + <devices> + <serial type="spiceport"> + <source channel="org.qemu.console.serial.0"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsNmdm"/>` + +Nmdm device +''''''''''' + +The nmdm device driver, available on FreeBSD, provides two tty devices connected +together by a virtual null modem cable. :since:`Since 1.2.4` + +:: + + ... + <devices> + <serial type="nmdm"> + <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/> + </serial> + </devices> + ... + +The ``source`` element has these attributes: + +``master`` + Master device of the pair, that is passed to the hypervisor. Device is + specified by a fully qualified path. +``slave`` + Slave device of the pair, that is passed to the clients for connection to the + guest console. Device is specified by a fully qualified path. + +:anchor:`<a id="elementsSound"/>` + +Sound devices +~~~~~~~~~~~~~ + +A virtual sound card can be attached to the host via the ``sound`` element. +:since:`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 'es1370', 'sb16', 'ac97', + 'ich6' and 'usb'. ( :since:` 'ac97' only since 0.6.0, 'ich6' only since + 0.8.8, 'usb' only since 1.2.7` ) + +:since:`Since 0.9.13` , a sound element with ``ich6`` model can have optional +sub-elements ``<codec>`` to attach various audio codecs to the audio device. If +not specified, a default codec will be attached to allow playback and recording. + +Valid values are: + +- 'duplex' - advertise a line-in and a line-out +- 'micro' - advertise a speaker and a microphone +- 'output' - advertise a line-out :since:`Since 4.4.0` + +:: + + ... + <devices> + <sound model='ich6'> + <codec type='micro'/> + </sound> + </devices> + ... + +Each ``sound`` element has an optional sub-element ``<address>`` which can tie +the device to a particular PCI slot, `documented above <#elementsAddress>`__. + +:anchor:`<a id="elementsWatchdog"/>` + +Watchdog device +~~~~~~~~~~~~~~~ + +A virtual hardware watchdog device can be added to the guest via the +``watchdog`` element. :since:`Since 0.7.3, QEMU and KVM only` + +The watchdog device requires an additional driver and management daemon in the +guest. Just enabling the watchdog in the libvirt configuration does not do +anything useful on its own. + +Currently libvirt does not support notification when the watchdog fires. This +feature is planned for a future version of libvirt. + +:: + + ... + <devices> + <watchdog model='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: + + - 'i6300esb' - the recommended device, emulating a PCI Intel 6300ESB + - 'ib700' - emulating an ISA iBase IB700 + - 'diag288' - emulating an S390 DIAG288 device :since:`Since 1.2.17` + +``action`` + The optional ``action`` attribute describes what action to take when the + watchdog expires. Valid values are specific to the underlying hypervisor. + + QEMU and KVM support: + + - 'reset' - default, forcefully reset the guest + - 'shutdown' - gracefully shutdown the guest (not recommended) + - 'poweroff' - forcefully power off the guest + - 'pause' - pause the guest + - 'none' - do nothing + - 'dump' - automatically dump the guest :since:`Since 0.8.7` + - 'inject-nmi' - inject a non-maskable interrupt into the guest + :since:`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. + +:anchor:`<a id="elementsMemBalloon"/>` + +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:`Since 0.8.3, Xen, QEMU +and KVM only` Additionally, :since:`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:`Since 5.2.0` + - 'virtio-non-transitional' :since:`Since 5.2.0` + - 'xen' - default with Xen + + See `Virtio transitional devices <#elementsVirtioTransitional>`__ 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:`Since 1.3.1, 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:`Since 1.1.1, requires QEMU 1.5` + +``driver`` + For model ``virtio`` memballoon, `Virtio-specific + options <#elementsVirtio>`__ can also be set. ( :since:`Since 3.5.0` ) + +:anchor:`<a id="elementsRng"/>` + +Random number generator device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The virtual random number generator device allows the host to pass through +entropy to guest operating systems. :since:`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:`Since 5.2.0` + - 'virtio-non-transitional' :since:`Since 5.2.0` + + See `Virtio transitional devices <#elementsVirtioTransitional>`__ 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:`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:`Since 1.3.4` any path is accepted. Before that ``/dev/random`` and + ``/dev/hwrng`` were the only accepted paths. When no file name is + specified, the hypervisor default is used. For QEMU, the default is + ``/dev/random``. However, the recommended source of entropy is + ``/dev/urandom`` (as it doesn't have the limitations of ``/dev/random``). + + ``egd`` + This backend connects to a source using the EGD protocol. The source is + specified as a character device. Refer to `character device host + interface <#elementsCharHostInterface>`__ for more information. + + ``builtin`` + This backend uses qemu builtin random generator, which uses + ``getrandom()`` syscall as the source of entropy. ( :since:`Since 6.1.0 + and QEMU 4.2` ) + +``driver`` + The subelement ``driver`` can be used to tune the device: + + virtio options + `Virtio-specific options <#elementsVirtio>`__ can also be set. ( + :since:`Since 3.5.0` ) + +:anchor:`<a id="elementsTpm"/>` + +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. :since:`'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:`'emulator' +since 4.5.0` The state of the TPM emulator can be encrypted by providing an +``encryption`` element. :since:`'encryption' since 5.6.0` + +Example: usage of the TPM Emulator + +:: + + ... + <devices> + <tpm model='tpm-tis'> + <backend type='emulator' version='2.0'> + <encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/> + </backend> + </tpm> + </devices> + ... + +``model`` + The ``model`` attribute specifies what device model QEMU provides to the + guest. If no model name is provided, ``tpm-tis`` will automatically be chosen + for non-PPC64 architectures. :since:`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:`Since 6.1.0` , pSeries guests on PPC64 are supported and the + default is ``tpm-spapr``. :since:`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:`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. + +``version`` + The ``version`` attribute indicates the version of the TPM. By default a TPM + 1.2 is created. This attribute only works with the ``emulator`` backend. The + following versions are supported: + + - '1.2' : creates a TPM 1.2 + - '2.0' : creates a TPM 2.0 + +``encryption`` + The ``encryption`` element allows the state of a TPM emulator to be + encrypted. The ``secret`` must reference a secret object that holds the + passphrase from which the encryption key will be derived. + +:anchor:`<a id="elementsNVRAM"/>` + +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:`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 + +:anchor:`<a id="elementsPanic"/>` + +panic device +~~~~~~~~~~~~ + +panic device enables libvirt to receive panic notification from a QEMU guest. +:since:`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:`Since 1.3.0, QEMU and + KVM only` + - 's390' - default for S390 guests. :since:`Since 1.3.5` + +``address`` + address of panic. The default ioport is 0x505. Most users don't need to + specify an address, and doing so is forbidden altogether for s390, pseries + and hyperv models. + +:anchor:`<a id="elementsShmem"/>` + +Shared memory device +~~~~~~~~~~~~~~~~~~~~ + +A shared memory device allows to share a memory region between different virtual +machines and the host. :since:`Since 1.2.10, QEMU and KVM only` + +:: + + ... + <devices> + <shmem name='my_shmem0'> + <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 ``/``. +``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. + +:anchor:`<a id="elementsMemory"/>` + +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'>4096</pagesize> + <nodemask>1-3</nodemask> + </source> + <target> + <size unit='KiB'>524287</size> + <node>1</node> + </target> + </memory> + <memory model='nvdimm'> + <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> + <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> + </devices> + ... + +``model`` + Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since + 1.2.14` Provide ``nvdimm`` model adds a Non-Volatile DIMM module. + :since:`Since 3.2.0` + +``access`` + An optional attribute ``access`` ( :since:`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 <#elementsMemoryBacking>`__: ``shared`` and + ``private``. For ``nvdimm`` model, if using real NVDIMM DAX device as + backend, ``shared`` is required. + +``discard`` + An optional attribute ``discard`` ( :since:`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 <#elementsMemoryBacking>`__. 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:`Since 6.2.0` + +``source`` + For model ``dimm`` this element is optional and allows to fine tune the + source of the memory used for the given memory device. If the element is not + provided defaults configured via ``numatune`` are used. If ``dimm`` is + provided, then the following optional elements can be provided as well: + + ``pagesize`` + This element can be used to override the default host page size used for + backing the memory device. The configured value must correspond to a page + size supported by the host. + + ``nodemask`` + This element can be used to override the default set of NUMA nodes where + the memory would be allocated. + + For model ``nvdimm`` this element is mandatory. The mandatory child element + ``path`` represents a path in the host that backs the nvdimm module in the + guest. The following optional elements may be used: + + ``alignsize`` + The ``alignsize`` element defines the page size alignment used to mmap the + address range for the backend ``path``. If not supplied the host page size + is 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:`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:`Since 5.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. + + 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. + + 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 + `here <#elementsMemoryAllocation>`__. ``label`` is mandatory for pSeries + guests and optional for all other architectures. For QEMU domains the + following restrictions apply: + + #. the minimum label size is 128KiB, + #. 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:`Since + 5.0.0` + +:anchor:`<a id="elementsIommu"/>` + +IOMMU devices +~~~~~~~~~~~~~ + +The ``iommu`` element can be used to add an IOMMU device. :since:`Since 2.1.0` + +Example: + +:: + + ... + <devices> + <iommu model='intel'> + <driver intremap='on'/> + </iommu> + </devices> + ... + +``model`` + Supported values are ``intel`` (for Q35 guests) and, :since:`since 5.5.0` , + ``smmuv3`` (for 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:`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:`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 <#elementsFeatures>`__), and + both interrupt remapping and EIM turned on for the IOMMU, will be able to + use more than 255 vCPUs. :since:`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:`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:`Since 6.5.0` (QEMU/KVM + only) + +:anchor:`<a id="vsock"/>` + +Vsock +----- + +A vsock host/guest interface. The ``model`` attribute defaults to ``virtio``. +:since:`Since 5.2.0` ``model`` can also be 'virtio-transitional' and +'virtio-non-transitional', see `Virtio transitional +devices <#elementsVirtioTransitional>`__ 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:`Since 4.4.0` + +:: + + ... + <devices> + <vsock model='virtio'> + <cid auto='no' address='3'/> + </vsock> + </devices> + ... diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 776dcf7e25..a6faf58767 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -2170,5059 +2170,7 @@ event name Description ``emulation_faults`` the count of emulation faults, that is when the kernel traps on unimplemented instrucions and emulates them for user space, by applications running on the platform ``perf.emulation_faults`` =========================== ======================================================================================================================================================================================= ================================ -:anchor:`<a id="elementsDevices"/>` - -Devices -------- - -The final set of XML elements are all used to describe devices provided to the -guest domain. All devices occur as children of the main ``devices`` element. -:since:`Since 0.1.3` - -:: - - ... - <devices> - <emulator>/usr/lib/xen/bin/qemu-dm</emulator> - </devices> - ... - -``emulator`` - The contents of the ``emulator`` element specify the fully qualified path to - the device model emulator binary. The `capabilities XML <formatcaps.html>`__ - specifies the recommended default emulator to use for each particular domain - type / architecture combination. - -To help users identifying devices they care about, every device can have direct -child ``alias`` element which then has ``name`` attribute where users can store -identifier for the device. The identifier has to have "ua-" prefix and must be -unique within the domain. Additionally, the identifier must consist only of the -following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` - -:: - - <devices> - <disk type='file'> - <alias name='ua-myDisk'/> - </disk> - <interface type='network' trustGuestRxFilters='yes'> - <alias name='ua-myNIC'/> - </interface> - ... - </devices> - -:anchor:`<a id="elementsDisks"/>` - -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'/> - <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'/> - <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'/> - <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='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='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'/> - <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> - </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:`since 0.7.5` ), - "network" ( :since:`since 0.8.7` ), or "volume" ( :since:`since 1.0.5` ), - or "nvme" ( :since:`since 6.0.0` ) and refer to the underlying source for - the disk. :since:`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:`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 <http://wiki.libvirt.org/page/NPIV_in_libvirt>`__ 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:`Since 0.1.4` - - ``model`` - Indicates the emulated device model of the disk. Typically this is - indicated solely by the ``bus`` property but for ``bus`` "virtio" the - model can be specified further with "virtio-transitional", - "virtio-non-transitional", or "virtio". See `Virtio transitional - devices <#elementsVirtioTransitional>`__ for more details. :since:`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). To confine the - capability as much as possible for QEMU driver as this stage, ``sgio`` is - recommended, it's more secure than ``rawio``. :since:`Since 0.9.10` - ``sgio`` - If supported by the hypervisor and OS, indicates whether unprivileged - SG_IO commands are filtered for the disk. Valid settings are "filtered" or - "unfiltered" where the default is "filtered". Only available when the - ``device`` is 'lun'. :since:`Since 1.0.2` - ``snapshot`` - Indicates the default behavior of the disk during disk snapshots: - "``internal``" requires a file format such as qcow2 that can store both - the snapshot and the data changes since the snapshot; "``external``" will - separate the snapshot from the live data; and "``no``" means the disk will - not participate in snapshots. 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 <formatsnapshot.html>`__. Not all snapshot modes are supported; - for example, enabling snapshots with a transient disk generally does not - make sense. :since:`Since 0.9.5` - -``source`` - Representation of the disk ``source`` depends on the disk ``type`` attribute - value as follows: - - ``file`` - The ``file`` attribute specifies the fully-qualified path to the file - holding the disk. :since:`Since 0.0.3` - ``block`` - The ``dev`` attribute specifies the fully-qualified path to the host - device to serve as the disk. :since:`Since 0.0.3` - ``dir`` - The ``dir`` attribute specifies the fully-qualified path to the directory - to use as the disk. :since:`Since 0.7.5` - ``network`` - The ``protocol`` attribute specifies the protocol to access to the - requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdog", - "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp". - - For any ``protocol`` other than ``nbd`` an additional attribute ``name`` - is mandatory to specify which volume/image will be used. - - For "nbd", the ``name`` attribute is optional. 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:`Since 4.5.0` ) - - For protocols ``http`` and ``https`` an optional attribute ``query`` - specifies the query string. ( :since:`Since 6.2.0` ) - - For "iscsi" ( :since:`since 1.0.4` ), the ``name`` attribute may 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:`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:`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 <formatstorage.html>`__ (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:`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 <formatstorage.html>`__ ``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:`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. - - With "file", "block", and "volume", one or more optional sub-elements - ``seclabel``, `described below <#seclabel>`__ (and :since:`since 0.9.9` ), - can be used to override the domain security labeling policy for just that - source file. (NB, for "volume" type disk, ``seclabel`` is only valid when the - specified storage volume is of 'file' or 'block' type). - - The ``source`` element may also have the ``index`` attribute with same - semantics the `index <#elementsDiskBackingStoreIndex>`__ attribute of - ``backingStore`` - - The ``source`` element may contain the following sub elements: - - ``host`` - When the disk ``type`` is "network", the ``source`` may have zero or more - ``host`` sub-elements used to specify the hosts to connect. The ``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:`Since 2.1.0` ), just one prior to that 24007 - vxhs a server running Veritas HyperScale daemon only one 9999 - ======== ======================================================= ============================================================ ================ - - gluster supports "tcp", "rdma", "unix" as valid values for the transport - attribute. nbd supports "tcp" and "unix". Others only support "tcp". If - nothing is specified, "tcp" is assumed. If the transport is "unix", the - socket attribute specifies the path to an AF_UNIX socket. - - ``snapshot`` - The ``name`` attribute of ``snapshot`` element can optionally specify an - internal snapshot name to be used as the source for storage protocols. - Supported for 'rbd' :since:`since 1.2.11 (QEMU only).` - ``config`` - The ``file`` attribute for the ``config`` element provides a fully - qualified path to a configuration file to be provided as a parameter to - the client of a networked storage protocol. Supported for 'rbd' - :since:`since 1.2.11 (QEMU only).` - ``auth`` - :since:`Since libvirt 3.9.0` , the ``auth`` element is supported for a - disk ``type`` "network" that is using a ``source`` element with the - ``protocol`` attributes "rbd" or "iscsi". If present, the ``auth`` 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 <formatsecret.html>`__ 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:`Since libvirt 3.9.0` , the ``encryption`` can be a sub-element of - the ``source`` element for encrypted storage sources. If present, - specifies how the storage source is encrypted See the `Storage - Encryption <formatstorageencryption.html>`__ 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:`Since libvirt 4.5.0` ) - ``reservations`` - :since:`Since libvirt 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:`Since libvirt 4.7.0` , the ``initiator`` element is supported for - a disk ``type`` "network" that is using a ``source`` element with the - ``protocol`` attribute "iscsi". If present, the ``initiator`` element - provides the initiator IQN needed to access the source via mandatory - attribute ``name``. - ``address`` - For disk of type ``nvme`` this element specifies the PCI address of the - host NVMe controller. :since:`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:`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:`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:`Since 6.2.0` - ``readahead`` - Specifies the size of the readahead buffer for protocols which support it. - (all 'curl' based drivers in qemu). The size is in bytes. Note that '0' is - considered as if the value is not provided. :since:`Since 6.2.0` - ``timeout`` - Specifies the connection timeout for protocols which support it. Note that - '0' is considered as if the value is not provided. :since:`Since 6.2.0` - - For a "file" or "volume" disk type which represents a cdrom or floppy (the - ``device`` attribute), it is possible to define policy what to do with the - disk if the source file is not accessible. (NB, ``startupPolicy`` is not - valid for "volume" disk unless the specified storage volume is of "file" - type). This is done by the ``startupPolicy`` attribute ( :since:`since 0.9.7` - ), accepting these values: - - ========= ===================================================================== - 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:`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:`Since 1.2.4.` If the hypervisor driver - does not support the - `backingStoreInput <formatdomaincaps.html#featureBackingStoreInput>`__ ( - :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on - input and only used for output to describe the detected backing chains of - running domains. If ``backingStoreInput`` is supported the ``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``. - ``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:`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:`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:`since 1.2.6` . Older libvirt supported only block copy to a - file, :since:`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" :since:`"sd" since 1.1.2` . If - omitted, the bus type is inferred from the style of the device name (e.g. a - device named 'sda' will typically be exported using a SCSI bus). The 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 - disks, and its value can be either "on" or "off", defaulting to "off". - :since:`Since 0.0.3; ``bus`` attribute since 0.4.3; ``tray`` attribute since - 0.9.11; "usb" attribute value since after 0.4.4; "sata" attribute value since - 0.9.7; "removable" attribute value since 1.1.3` -``iotune`` - The optional ``iotune`` element provides the ability to provide additional - per-device I/O tuning, with values that can vary for each device (contrast - this to the `<blkiotune> <#elementsBlockTuning>`__ element, which applies - globally to the domain). Currently, the only tuning available is Block I/O - throttling for qemu. This element has optional sub-elements; any sub-element - not specified or given with a value of 0 implies no limit. :since:`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. - - :since:`Throughput limits since 1.2.11 and QEMU 1.7` - - ``group_name`` - The optional ``group_name`` provides the cability to share I/O throttling - quota between multiple drives. This prevents end-users from circumventing - a hosting provider's throttling policy by splitting 1 large drive in N - small drives and getting N times the normal throttling quota. Any name may - be used. - - :since:`group_name since 3.0.0 and QEMU 2.4` - - ``total_bytes_sec_max_length`` - The optional ``total_bytes_sec_max_length`` element is the maximum - duration in seconds for the ``total_bytes_sec_max`` burst period. 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. - - :since:`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:`Since 0.1.8` - - - If the hypervisor supports multiple backend drivers, then the ``name`` - attribute selects the primary backend driver name, while the optional - ``type`` attribute provides the sub-type. For example, xen supports a name - of "tap", "tap2", "phy", or "file", with a type of "aio", while qemu only - supports a name of "qemu", but multiple types including "raw", "bochs", - "qcow2", and "qed". - - The optional ``cache`` attribute controls the cache mechanism, possible - values are "default", "none", "writethrough", "writeback", "directsync" - (like "writethrough", but it bypasses the host page cache) and "unsafe" - (host may cache all disk io, and sync requests from guest are ignored). - :since:` Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7 ` - - The optional ``error_policy`` attribute controls how the hypervisor will - behave on a disk read or write error, possible values are "stop", - "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" since - 0.9.7` The default is left to the discretion of the hypervisor. There is - also an optional ``rerror_policy`` that controls behavior for read errors - only. :since:`Since 0.9.7` . If no rerror_policy is given, error_policy is - used for both read and write errors. If rerror_policy is given, it - overrides the ``error_policy`` for read errors. Also note that "enospace" - is not a valid policy for read errors, so if ``error_policy`` is set to - "enospace" and no ``rerror_policy`` is given, the read error policy will - be left at its default. - - The optional ``io`` attribute controls specific policies on I/O; qemu - guests support "threads" and "native" :since:`Since 0.8.8` , io_uring - :since:`Since 6.3.0 (QEMU 5.0)` . - - The optional ``ioeventfd`` attribute allows users to set `domain I/O - asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__ 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:`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:`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:`Since 0.9.10 (QEMU and KVM only)` - - The optional ``discard`` attribute controls whether discard requests (also - known as "trim" or "unmap") are ignored or passed to the filesystem. The - value can be either "unmap" (allow the discard request to be passed) or - "ignore" (ignore the discard request). :since:`Since 1.0.6 (QEMU and KVM - only)` - - The optional ``detect_zeroes`` attribute controls whether to detect zero - write requests. The value can be "off", "on" or "unmap". First two 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:`Since 2.0.0` - - The optional ``iothread`` attribute assigns the disk to an IOThread as - defined by the range for the domain - `iothreads <#elementsIOThreadsAllocation>`__ value. Multiple disks 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:`Since 1.2.8 - (QEMU 2.1)` - - The optional ``queues`` attribute specifies the number of virt queues for - virtio-blk. ( :since:`Since 3.9.0` ) - - For virtio disks, `Virtio-specific options <#elementsVirtio>`__ can also - be set. ( :since:`Since 3.5.0` ) - -``backenddomain`` - The optional ``backenddomain`` element allows specifying a backend domain - (aka driver domain) hosting the disk. Use the ``name`` attribute to specify - the backend domain name. :since:`Since 1.2.13 (Xen only)` -``boot`` - Specifies that the disk is bootable. The ``order`` attribute determines the - order in which devices will be tried during boot sequence. On the S390 - architecture only the first boot device is used. The optional ``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:`Since 3.5.0` The per-device ``boot`` elements cannot be used - together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__ - section. :since:`Since 0.8.8` -``encryption`` - Starting with :since:`libvirt 3.9.0` the ``encryption`` element is preferred - to be a sub-element of the ``source`` element. If present, specifies how the - volume is encrypted using "qcow". See the `Storage - Encryption <formatstorageencryption.html>`__ 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 or - snapshots. :since:`Since 0.9.5` -``serial`` - If present, this specify serial number of virtual hard drive. For example, it - may look like ``<serial>WD-WMAP9A966149</serial>``. Not supported for - scsi-block devices, that is those using disk ``type`` 'block' using - ``device`` 'lun' on ``bus`` 'scsi'. :since:`Since 0.7.1` -``wwn`` - If present, this element specifies the WWN (World Wide Name) of a virtual - hard disk or CD-ROM drive. It must be composed of 16 hexadecimal digits. - :since:`Since 0.10.1` -``vendor`` - If present, this element specifies the vendor of a virtual hard disk or - CD-ROM device. It must not be longer than 8 printable characters. - :since:`Since 1.0.1` -``product`` - If present, this element specifies the product of a virtual hard disk or - CD-ROM device. It must not be longer than 16 printable characters. - :since:`Since 1.0.1` -``address`` - If present, the ``address`` element ties the disk to a given slot of a - controller (the actual ``<controller>`` device can often be inferred by - libvirt, although it can be `explicitly specified <#elementsControllers>`__). - The ``type`` attribute is mandatory, and is typically "pci" or "drive". For a - "pci" controller, additional attributes for ``bus``, ``slot``, and - ``function`` must be present, as well as optional ``domain`` and - ``multifunction``. Multifunction defaults to 'off'; any other value requires - QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, additional - attributes ``controller``, ``bus``, ``target`` ( :since:`libvirt 0.9.11` ), - and ``unit`` are available, each defaulting to 0. -``auth`` - Starting with :since:`libvirt 3.9.0` the ``auth`` element is preferred to be - a sub-element of the ``source`` element. The element is still read and - managed as a ``disk`` sub-element. It is invalid to use ``auth`` as both a - sub-element of ``disk`` and ``source``. The ``auth`` element was introduced - as a ``disk`` sub-element in :since:`libvirt 0.9.7.` -``geometry`` - The optional ``geometry`` element provides the ability to override geometry - settings. This mostly useful for S390 DASD-disks or older DOS-disks. - :since:`0.10.0` - - ``cyls`` - The ``cyls`` attribute is the number of cylinders. - ``heads`` - The ``heads`` attribute is the number of heads. - ``secs`` - The ``secs`` attribute is the number of sectors per track. - ``trans`` - The optional ``trans`` attribute is the BIOS-Translation-Modus (none, lba - or auto) - -``blockio`` - If present, the ``blockio`` element allows to override any of the block - device properties listed below. :since:`Since 0.10.2 (QEMU and KVM)` - - ``logical_block_size`` - The logical block size the disk will report to the guest OS. For 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. - -:anchor:`<a id="elementsFilesystems"/>` - -Filesystems -~~~~~~~~~~~ - -A directory on the host that can be accessed directly from the guest. -:since:`since 0.3.3, since 0.8.5 for QEMU/KVM` - -:: - - ... - <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='file' accessmode='passthrough'> - <driver type='loop' format='raw'/> - <driver type='path' wrpolicy='immediate'/> - <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'/> - <lock posix='on' flock='on'/> - </binary> - <source dir='/path'/> - <target dir='mount_tag'/> - </filesystem> - ... - </devices> - ... - -``filesystem`` - The filesystem attribute ``type`` specifies the type of the ``source``. The - possible values are: - - ``mount`` - A host directory to mount in the guest. Used by LXC, OpenVZ :since:`(since - 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``type`` - if one is not specified. This mode also has an optional sub-element - ``driver``, with an attribute ``type='path'`` or ``type='handle'`` - :since:`(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:`(since 0.9.10)` - . :since:`Since 6.2.0` , ``type='virtiofs'`` is also supported. Using - virtiofs requires setting up shared memory, see the guide: - `Virtio-FS <kbase/virtiofs.html>`__ - ``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:`(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:` (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:` (since 0.9.13)` - - The filesystem element has an optional attribute ``accessmode`` which - specifies the security mode for accessing the source :since:`(since 0.8.5)` . - Currently this only works with ``type='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 <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__ - ``mapped`` - The ``source`` is accessed with the permissions of the hypervisor (QEMU - process). `More - info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__ - ``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 <http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html>`__ - - :since:`Since 5.2.0` , the filesystem element has an optional attribute - ``model`` with supported values "virtio-transitional", - "virtio-non-transitional", or "virtio". See `Virtio transitional - devices <#elementsVirtioTransitional>`__ for more details. - - The filesystem element has an optional attribute ``multidevs`` which - specifies how to deal with a filesystem export containing more than one - device, in order to avoid file ID collisions on guest when using 9pfs ( - :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not 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:`Since 1.0.6` - - - If the hypervisor supports multiple backend drivers, then the ``type`` - attribute selects the primary backend driver name, while the ``format`` - attribute provides the format type. For example, LXC supports a type of - "loop", with a format of "raw" or "nbd" with any format. QEMU supports a - type of "path" or "handle", but no formats. Virtuozzo driver supports a - type of "ploop" with a format of "ploop". - - For virtio-backed devices, `Virtio-specific options <#elementsVirtio>`__ - can also be set. ( :since:`Since 3.5.0` ) - - For ``virtiofs``, the ``queue`` attribute can be used to specify the queue - size (i.e. how many requests can the queue fit). ( :since:`Since 6.2.0` ) - -``binary`` - The optional ``binary`` element can tune the options for virtiofsd. All of - the following attributes and elements are optional. The attribute ``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:`Since 6.2.0` ) -``source`` - The resource on the host that is being accessed in the guest. The ``name`` - attribute must be used with ``type='template'``, and the ``dir`` attribute - must be used with ``type='mount'``. 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. -``readonly`` - Enables exporting filesystem as a readonly mount for guest, by default - read-write access is given (currently only works for QEMU/KVM driver). -``space_hard_limit`` - Maximum space available to this guest's filesystem. :since:`Since 0.9.13` -``space_soft_limit`` - Maximum space available to this guest's filesystem. The container is - permitted to exceed its soft limits for a grace period of time. Afterwards - the hard limit is enforced. :since:`Since 0.9.13` - -:anchor:`<a id="elementsAddress"/>` - -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:`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:`Since 4.10.0` ), PCI address extensions depending on the - architecture are supported. For example, PCI addresses for S390 guests will - have a ``zpci`` child element, with two attributes: ``uid`` (a hex value - between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between - 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for - User-defined Identifiers and Function Identifiers. - :since:`Since 1.3.5` , some hypervisor drivers may accept an - ``<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 <pci-addresses.html>`__ 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:`Since 0.8.8.` -``usb`` - USB addresses have the following additional attributes: ``bus`` (a hex value - between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up to - four octets, such as 1.2 or 2.1.3.1). -``spapr-vio`` - On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It - has a flat 32-bit address space; by convention, devices are generally - assigned at a non-zero multiple of 0x00001000, but other addresses are valid - and permitted by libvirt. Each address has the following additional - attribute: ``reg`` (the hex value address of the starting register). - :since:`Since 0.9.9.` -``ccw`` - S390 guests with a ``machine`` value of s390-ccw-virtio use the native CCW - bus for I/O devices. CCW bus addresses have the following additional - attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``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:`Since 1.0.4` -``virtio-mmio`` - This places the device on the virtio-mmio transport, which is currently only - available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-mmio - addresses do not have any additional attributes. :since:`Since 1.1.3` - If the guest architecture is ``aarch64`` and the machine type is ``virt``, - libvirt will automatically assign PCI addresses to devices; however, the - presence of a single device with virtio-mmio address in the guest - configuration will cause libvirt to assign virtio-mmio addresses to all - further devices. :since:`Since 3.0.0` -``isa`` - ISA addresses have the following additional attributes: ``iobase`` and - ``irq``. :since:`Since 1.2.1` -``unassigned`` - For PCI hostdevs, ``<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:`Since 6.0.0` - -:anchor:`<a id="elementsVirtio"/>` - -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 device <#elementsIommu>`__). Possible values are ``on`` or ``off``. -:since:`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:`Since 6.3.0 (QEMU and KVM only)` - -:anchor:`<a id="elementsVirtioTransitional"/>` - -Virtio transitional devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:since:`Since 5.2.0` , some of QEMU's virtio devices, when used with PCI/PCIe -machine types, accept the following ``model`` values: - -``virtio-transitional`` - This device can work both with virtio 0.9 and virtio 1.0 guest drivers, so - it's the best choice when compatibility with older guest operating systems is - desired. libvirt will plug the device into a conventional PCI slot. -``virtio-non-transitional`` - This device can only work with virtio 1.0 guest drivers, and it's the - recommended option unless compatibility with older guest operating systems is - necessary. libvirt will plug the device into either a PCI Express slot or a - conventional PCI slot based on the machine type, resulting in a more - optimized PCI topology. -``virtio`` - This device will work like a ``virtio-non-transitional`` device when plugged - into a PCI Express slot, and like a ``virtio-transitional`` device otherwise; - libvirt will pick one or the other based on the machine type. This is the - best choice when compatibility with libvirt versions older than 5.2.0 is - necessary, but it's otherwise not recommended to use it. - -While the information outlined above applies to most virtio devices, there are a -few exceptions: - -- for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`` for - backwards compatibility reasons; -- some devices, such as GPUs and input devices (keyboard, tablet and mouse), - are only defined in the virtio 1.0 spec and as such don't have a transitional - variant: the only accepted model is ``virtio``, which will result in a - non-transitional device. - -For more details see the `qemu patch -posting <https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html>`__ -and the `virtio-1.0 -spec <http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html>`__. - -:anchor:`<a id="elementsControllers"/>` - -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 <pci-hotplug.html>`__ 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:`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:`Since 5.2.0` , it supports an optional - attribute ``model`` which can be 'virtio', 'virtio-transitional', or - 'virtio-non-transitional'. See `Virtio transitional - devices <#elementsVirtioTransitional>`__ for more details. -``scsi`` - A ``scsi`` controller has an optional attribute ``model``, which is one of - 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078', - 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. - See `Virtio transitional devices <#elementsVirtioTransitional>`__ 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:`since 0.10.0` , if the USB - bus needs to be explicitly disabled for the guest, ``model='none'`` may be - used. :since:`Since 1.0.5` , no default USB controller will be built on s390. - :since:`Since 1.3.5` , USB controllers accept a ``ports`` attribute to - configure how many devices can be connected to the controller. -``ide`` - :since:`Since 3.10.0` for the vbox driver, the ``ide`` controller has an - optional attribute ``model``, which is one of "piix3", "piix4" or "ich6". -``xenbus`` - :since:`Since 5.2.0` , the ``xenbus`` controller has an optional attribute - ``maxGrantFrames``, which specifies the maximum number of grant frames the - controller makes available for connected devices. :since:`Since 6.3.0` , the - xenbus controller supports the optional ``maxEventChannels`` attribute, which - specifies maximum number of event channels (PV interrupts) that can be used - by the guest. - -Note: The PowerPC64 "spapr-vio" addresses do not have an associated controller. - -For controllers that are themselves devices on a PCI or USB bus, an optional -sub-element ``<address>`` can specify the exact relationship of the controller -to its master bus, with semantics `given above <#elementsAddress>`__. - -An optional sub-element ``driver`` can specify the driver specific options: - -``queues`` - The optional ``queues`` attribute specifies the number of queues for the - controller. For best performance, it's recommended to specify a value - matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)` -``cmd_per_lun`` - The optional ``cmd_per_lun`` attribute specifies the maximum number of - commands that can be queued on devices controlled by the host. :since:`Since - 1.2.7 (QEMU and KVM only)` -``max_sectors`` - The optional ``max_sectors`` attribute specifies the maximum amount of data - in bytes that will be transferred to or from the device in a single command. - The transfer length is measured in sectors, where a sector is 512 bytes. - :since:`Since 1.2.7 (QEMU and KVM only)` -``ioeventfd`` - The optional ``ioeventfd`` attribute specifies whether the controller should - use `I/O asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__ - or not. Accepted values are "on" and "off". :since:`Since 1.2.18` -``iothread`` - Supported for controller type ``scsi`` using model ``virtio-scsi`` for - ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` . The - optional ``iothread`` attribute assigns the controller to an IOThread as - defined by the range for the domain - `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk`` - assigned to use the specified ``controller`` will utilize the same 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-specific options <#elementsVirtio>`__ can - also be set. ( :since:`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:`since 1.0.5` ) -- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` ) -- ``pcie-root-port``, ``pcie-switch-upstream-port``, - ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` ) -- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` ) -- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` ) - -The root controllers (``pci-root`` and ``pcie-root``) have an optional -``pcihole64`` element specifying how big (in kilobytes, or in the unit 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:`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:`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:`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`` - pcie-root-port and pcie-switch-downstream-port controllers can also have a - ``hotplug`` attribute in the ``<target>`` subelement, which is used to - disable hotplug/unplug of devices on a particular controller. The default - setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable - hotplug/unplug of devices on a particular controller. :since:`Since 6.3.0` -``busNr`` - pci-expander-bus and pcie-expander-bus controllers can have an optional - ``busNr`` attribute (1-254). This will be the bus number of the new bus; All - bus numbers between that specified and 255 will be available only for - assignment to PCI/PCIe controllers plugged into the hierarchy starting with - this expander bus, and bus numbers less than the specified value will be - available to the next lower expander-bus (or the root-bus if there are no - lower expander buses). If you do not specify a busNumber, libvirt will find - the lowest existing busNumber in all other expander buses (or use 256 if - there are no others) and auto-assign the busNr of that found bus - 2, which - provides one bus number for the pci-expander-bus and one for the pci-bridge - that is automatically attached to it (if you plan on adding more pci-bridges - to the hierarchy of the bus, you should manually set busNr to a lower value). - - A similar algorithm is used for automatically determining the busNr attribute - for pcie-expander-bus, but since the pcie-expander-bus doesn't have any - built-in pci-bridge, the 2nd bus-number is just being reserved for the - pcie-root-port that must necessarily be connected to the bus in order to - actually plug in an endpoint device. If you intend to plug multiple devices - into a pcie-expander-bus, you must connect a pcie-switch-upstream-port to the - pcie-root-port that is plugged into the pcie-expander-bus, and multiple - pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of course - for this to work properly, you will need to decrease the pcie-expander-bus' - busNr accordingly so that there are enough unused bus numbers above it to - accommodate giving out one bus number for the upstream-port and one for each - downstream-port (in addition to the pcie-root-port and the pcie-expander-bus - itself). - -``node`` - Some PCI controllers (``pci-expander-bus`` for the pc machine type, - ``pcie-expander-bus`` for the q35 machine type and, :since:`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:`Since 3.6.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:`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:`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:`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:`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> - ... - -:anchor:`<a id="elementsLease"/>` - -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. - -:anchor:`<a id="elementsHostDev"/>` - -Host device assignment -~~~~~~~~~~~~~~~~~~~~~~ - -:anchor:`<a id="elementsHostDevSubsys"/>` - -USB / PCI / SCSI devices -^^^^^^^^^^^^^^^^^^^^^^^^ - -USB, PCI and SCSI devices attached to the host can be passed through to the -guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.6.0 -for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` : - -:: - - ... - <devices> - <hostdev mode='subsystem' type='usb'> - <source startupPolicy='optional'> - <vendor id='0x1234'/> - <product id='0xbeef'/> - </source> - <boot order='2'/> - </hostdev> - </devices> - ... - -or: - -:: - - ... - <devices> - <hostdev mode='subsystem' type='pci' managed='yes'> - <source> - <address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/> - </source> - <boot order='1'/> - <rom bar='on' file='/etc/fake/boot.bin'/> - </hostdev> - </devices> - ... - -or: - -:: - - ... - <devices> - <hostdev mode='subsystem' type='scsi' sgio='filtered' 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> - ... - -or: - -:: - - ... - <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> - </source> - <address type='drive' controller='0' bus='0' target='0' unit='0'/> - </hostdev> - </devices> - ... - -or: - -:: - - ... - <devices> - <hostdev mode='subsystem' type='scsi_host'> - <source protocol='vhost' wwpn='naa.50014057667280d8'/> - </hostdev> - </devices> - ... - -or: - -:: - - ... - <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`` - The ``hostdev`` element is the main container for describing host devices. - For each device, the ``mode`` is always "subsystem" and the ``type`` is one - of the following values with additional attributes noted. - - ``usb`` - USB devices are detached from the host on guest startup and reattached - after the guest exits or the device is hot-unplugged. - ``pci`` - For PCI devices, when ``managed`` is "yes" it is detached from the host - before being passed on to the guest and reattached to the host after the - guest exits. If ``managed`` is omitted or "no", the user is responsible to - call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before - starting the guest or hot-plugging the device and - ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug - or stopping the guest. - ``scsi`` - For SCSI devices, user is responsible to make sure the device is not used - by host. If supported by the hypervisor and OS, the optional ``sgio`` ( - :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO - commands are filtered for the disk. Valid settings are "filtered" or - "unfiltered", where the default is "filtered". The optional ``rawio`` ( - :since:`since 1.2.9` ) attribute indicates whether the lun needs the rawio - capability. Valid settings are "yes" or "no". See the rawio description - within the `disk <#elementsDisks>`__ section. If a disk lun in the domain - already has the rawio capability, then this setting not required. - ``scsi_host`` - :since:`since 2.5.0` For SCSI devices, user is responsible to make sure - the device is not used by host. This ``type`` passes all LUNs presented by - a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attribute - can be specified further with "virtio-transitional", - "virtio-non-transitional", or "virtio". See `Virtio transitional - devices <#elementsVirtioTransitional>`__ for more details. - ``mdev`` - For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute - specifies the device API which determines how the host's vfio driver will - expose the device to the guest. Currently, ``model='vfio-pci'``, - ``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model='vfio-ap'`` ( - :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__ - section provides more information about mediated devices as well as how to - create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an - optional ``display`` attribute may be used to enable or disable support - for an accelerated remote desktop backed by a mediated device (such as - NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video - devices <#elementsVideo>`__. This attribute is limited to - ``model='vfio-pci'`` only. Supported values are either ``on`` or ``off`` - (default is 'off'). It is required to use a `graphical - framebuffer <#elementsGraphics>`__ in order to use this attribute, - currently only supported with VNC, Spice and egl-headless graphics - devices. :since:`Since version 5.10.0` , there is an optional ``ramfb`` - attribute for devices with ``model='vfio-pci'``. Supported values are - either ``on`` or ``off`` (default is 'off'). When enabled, this attribute - provides a memory framebuffer device to the guest. This framebuffer will - be used as a boot display when a vgpu device is the primary display. - - Note: There are also some implications on the usage of guest's address - type depending on the ``model`` attribute, see the ``address`` element - below. - - Note: The ``managed`` attribute is only used with ``type='pci'`` and is - ignored by all the other device types, thus setting ``managed`` explicitly - with other than a PCI device has the same effect as omitting it. Similarly, - ``model`` attribute is only supported by mediated devices and ignored by all - other device types. - -``source`` - The source element describes the device as seen from the host using the - following mechanism to describe: - - ``usb`` - The USB device can either be addressed by vendor / product id using the - ``vendor`` and ``product`` elements or by the device's address on the host - using the ``address`` element. - - :since:`Since 1.0.0` , the ``source`` element of USB devices may contain - ``startupPolicy`` attribute which can be used to define policy what to do - if the specified host USB device is not found. The attribute accepts the - following values: - - ========= ===================================================================== - mandatory fail if missing for any reason (the default) - requisite fail if missing on boot up, drop if missing on migrate/restore/revert - optional drop if missing at any start attempt - ========= ===================================================================== - - ``pci`` - PCI devices can only be described by their ``address``. - ``scsi`` - SCSI devices are described by both the ``adapter`` and ``address`` - elements. The ``address`` element includes a ``bus`` attribute (a 2-digit - bus number), a ``target`` attribute (a 10-digit target number), and a - ``unit`` attribute (a 20-digit unit number on the bus). Not all - hypervisors support larger ``target`` and ``unit`` values. It is up to - each hypervisor to determine the maximum value supported for the adapter. - - :since:`Since 1.2.8` , the ``source`` element of a SCSI device may contain - the ``protocol`` attribute. When the attribute is set to "iscsi", the host - device XML follows the network `disk <#elementsDisks>`__ device using the - same ``name`` attribute and optionally using the ``auth`` element to - provide the authentication credentials to the iSCSI server. - - ``scsi_host`` - :since:`Since 2.5.0` , multiple LUNs behind a single SCSI HBA are - described by a ``protocol`` attribute set to "vhost" and a ``wwpn`` - attribute that is the vhost_scsi wwpn (16 hexadecimal digits with a prefix - of "naa.") established in the host configfs. - ``mdev`` - Mediated devices ( :since:`Since 3.2.0` ) are described by the ``address`` - element. The ``address`` element contains a single mandatory attribute - ``uuid``. - -``vendor``, ``product`` - The ``vendor`` and ``product`` elements each have an ``id`` attribute that - specifies the USB vendor and product id. The ids can be given in decimal, - hexadecimal (starting with 0x) or octal (starting with 0) form. -``boot`` - Specifies that the device is bootable. The ``order`` attribute determines the - order in which devices will be tried during boot sequence. The per-device - ``boot`` elements cannot be used together with general boot elements in `BIOS - bootloader <#elementsOSBIOS>`__ section. :since:`Since 0.8.8` for PCI - devices, :since:`Since 1.0.1` for USB devices. -``rom`` - The ``rom`` element is used to change how a PCI device's ROM is presented to - the guest. The optional ``bar`` attribute can be set to "on" or "off", and - determines whether or not the device's ROM will be visible in the guest's - memory map. (In PCI documentation, the "rombar" setting controls the presence - of the Base Address Register for the ROM). If no rom bar is specified, the - qemu default will be used (older versions of qemu used a default of "off", - while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU and KVM - only)` . The optional ``file`` attribute contains an absolute path to a - binary file to be presented to the guest as the device's ROM BIOS. This can - be useful, for example, to provide a PXE boot ROM for a virtual function of - an sr-iov capable ethernet device (which has no boot ROMs for the VFs). - :since:`Since 0.9.10 (QEMU and KVM only)` . The optional ``enabled`` - attribute can be set to ``no`` to disable PCI ROM loading completely for the - device; if PCI ROM loading is disabled through this attribute, attempts to - tweak the loading process further using the ``bar`` or ``file`` attributes - will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)` . -``address`` - The ``address`` element for USB devices has a ``bus`` and ``device`` - attribute to specify the USB bus and device number the device appears at on - the host. The values of these attributes can be given in decimal, hexadecimal - (starting with 0x) or octal (starting with 0) form. For PCI devices the - element carries 4 attributes allowing to designate the device as can be found - with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a 'drive' - address type must be used. For mediated devices, which are software-only - devices defining an allocation of resources on the physical parent device, - the address type used must conform to the ``model`` attribute of element - ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` device API - or any address type other than CCW for ``vfio-ccw`` device API will result in - an error. `See above <#elementsAddress>`__ for more details on the address - element. -``driver`` - PCI devices can have an optional ``driver`` subelement that specifies which - backend driver to use for PCI device assignment. Use the ``name`` attribute - to select either "vfio" (for the new VFIO device assignment backend, which is - compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment - handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU and KVM - only, requires kernel 3.6 or newer)` . When specified, device assignment will - fail if the requested method of device assignment isn't available on the - host. When not specified, the default is "vfio" on systems where the VFIO - driver is available and loaded, and "kvm" on older systems, or those where - the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that the - default was always "kvm"). -``readonly`` - Indicates that the device is readonly, only supported by SCSI host device - now. :since:`Since 1.0.6 (QEMU and KVM only)` -``shareable`` - If present, this indicates the device is expected to be shared between - domains (assuming the hypervisor and OS support this). Only supported by SCSI - host device. :since:`Since 1.0.6` - - Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did not - work as as expected until :since:`1.2.2` . - -:anchor:`<a id="elementsHostDevCaps"/>` - -Block / character devices -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Block / character devices from the host can be passed through to the guest using -the ``hostdev`` element. This is only possible with container based -virtualization. Devices are specified by a fully qualified path. :since:`since -after 1.0.1 for LXC` : - -:: - - ... - <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> - ... - -``hostdev`` - The ``hostdev`` element is the main container for describing host devices. - For block/character device passthrough ``mode`` is always "capabilities" and - ``type`` is "storage" for a block device, "misc" for a character device and - "net" for a host network interface. -``source`` - The source element describes the device as seen from the host. For block - devices, the path to the block device in the host OS is provided in the - nested "block" element, while for character devices the "char" element is - used. For network interfaces, the name of the interface is provided in the - "interface" element. - -:anchor:`<a id="elementsRedir"/>` - -Redirected devices -~~~~~~~~~~~~~~~~~~ - -USB device redirection through a character device is supported :since:`since -after 0.9.5 (KVM only)` : - -:: - - ... - <devices> - <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 <#elementsConsole>`__ types, to describe the host side of the tunnel; - ``type='tcp'`` or ``type='spicevmc'`` (which uses the usbredir channel of a - `SPICE graphics device <#elementsGraphics>`__) 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 <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` ) -``redirfilter`` - The\ ``redirfilter``\ element is used for creating the filter rule to filter - out certain devices from redirection. It uses sub-element ``<usbdev>`` to - define each filter rule. ``class`` attribute is the USB Class code, for - example, 0x08 represents mass storage devices. The USB device can be - addressed by vendor / product id using the ``vendor`` and ``product`` - attributes. ``version`` is the device revision from the bcdDevice field (not - the version of the USB protocol). These four attributes are optional and - ``-1`` can be used to allow any value for them. ``allow`` attribute is - mandatory, 'yes' means allow, 'no' for deny. - -:anchor:`<a id="elementsSmartcard"/>` - -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:`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 <#elementsConsole>`__ types, to describe the host side of the tunnel; - ``type='tcp'`` or ``type='spicevmc'`` (which uses the smartcard channel of a - `SPICE graphics device <#elementsGraphics>`__) are typical. Further - sub-elements, such as ``<source>``, may be required according to the given - type, although a ``<target>`` sub-element is not required (since the consumer - of the character device is the hypervisor itself, rather than a device - visible in the guest). - -Each mode supports an optional sub-element ``<address>``, which fine-tunes the -correlation between the smartcard and a ccid bus controller, `documented -above <#elementsAddress>`__. For now, qemu only supports at most one smartcard, -with an address of bus=0 slot=0. - -:anchor:`<a id="elementsNICS"/>` - -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'/> - </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:`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 above <#elementsAddress>`__. - -:since:`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. - -:anchor:`<a id="elementsNICSVirtual"/>` - -Virtual network -^^^^^^^^^^^^^^^ - -**This is the recommended config for general guest connectivity on hosts with -dynamic / wireless networking configs (or multi-host environments where the host -hardware details are described separately in a ``<network>`` definition -:since:`Since 0.9.4` ).** - -Provides a connection whose details are described by the named network -definition. Depending on the virtual network's "forward mode" configuration, the -network may be totally isolated (no ``<forward>`` element given), NAT'ing to an -explicit network device or to the default route (``<forward mode='nat'>``), -routed with no NAT (``<forward mode='route'/>``), or connected directly to one -of the host's network interfaces (via macvtap) or bridge devices -((``<forward mode='bridge|private|vepa|passthrough'/>`` :since:`Since -0.9.4` ) - -For networks with a forward mode of bridge, private, vepa, and passthrough, it -is assumed that the host has any necessary DNS and DHCP services already setup -outside the scope of libvirt. In the case of isolated, nat, and routed networks, -DHCP and DNS are provided on the virtual network by libvirt, and the IP range -can be determined by examining the virtual network config with -'``virsh net-dumpxml [networkname]``'. There is one virtual network called -'default' setup out of the box which does NAT'ing to the default route and has -an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an -associated tun device created with a name of vnetN, which can also be overridden -with the <target> element (see `overriding the target -element <#elementsNICSTargetOverride>`__). - -When the source of an interface is a network, a ``portgroup`` can be specified -along with the name of the network; one network may have multiple portgroups -defined, with each portgroup containing slightly different configuration -information for different classes of network connections. :since:`Since 0.9.4` . - -When a guest is running an interface of type ``network`` may include a -``portid`` attribute. This provides the UUID of an associated virNetworkPortPtr -object that records the association between the domain interface and the -network. This attribute is read-only since port objects are create and deleted -automatically during startup and shutdown. :since:`Since 5.1.0` - -Also, similar to ``direct`` network connections (described below), a connection -of type ``network`` may specify a ``virtualport`` element, with configuration -data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch ( -:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Since -0.9.11` ). - -Since the actual type of switch may vary depending on the configuration in the -``<network>`` on the host, it is acceptable to omit the virtualport ``type`` -attribute, and specify attributes from multiple different virtualport types (and -also to leave out certain attributes); at domain startup time, a complete -``<virtualport>`` element will be constructed by merging together the type and -attributes defined in the network and the portgroup referenced by the interface. -The newly-constructed virtualport is a combination of them. The attributes from -lower virtualport can't make change on the ones defined in higher virtualport. -Interface takes the highest priority, portgroup is lowest priority. ( -:since:`Since 0.10.0` ). For example, in order to work properly with both an -802.1Qbh switch and an Open vSwitch switch, you may choose to specify no type, -but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfaceid`` -(in case the switch is Open vSwitch) (you may also omit the other attributes, -such as managerid, typeid, or profileid, to be filled in from the network's -``<virtualport>``). If you want to limit a guest to connecting only to certain -types of switches, you can specify the virtualport type, but still omit some/all -of the parameters - in this case if the host's network has a different type of -virtualport, connection of the interface will fail. - -:: - - ... - <devices> - <interface type='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> - ... - -:anchor:`<a id="elementsNICSBridge"/>` - -Bridge to LAN -^^^^^^^^^^^^^ - -**This is the recommended config for general guest connectivity on hosts with -static wired networking configs.** - -Provides a bridge from the VM directly to the LAN. This assumes there is a -bridge device on the host which has one or more of the hosts physical NICs -attached. The guest VM will have an associated tun device created with a name of -vnetN, which can also be overridden with the <target> element (see `overriding -the target element <#elementsNICSTargetOverride>`__). The tun device will be -attached to the bridge. The IP range / network configuration is whatever is used -on the LAN. This provides the guest VM full incoming & outgoing net access just -like a physical machine. - -On Linux systems, the bridge device is normally a standard Linux host bridge. On -hosts that support Open vSwitch, it is also possible to connect to an Open -vSwitch bridge device by adding a ``<virtualport type='openvswitch'/>`` to the -interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type -virtualport accepts two parameters in its ``<parameters>`` element - an -``interfaceid`` which is a standard uuid used to uniquely identify this -particular interface to Open vSwitch (if you do not specify one, a random -interfaceid will be generated for you when you first define the interface), and -an optional ``profileid`` which is sent to Open vSwitch as the interfaces -"port-profile". - -:: - - ... - <devices> - ... - <interface type='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> - ... - -On hosts that support Open vSwitch on the kernel side and have the Midonet Host -Agent configured, it is also possible to connect to the 'midonet' bridge device -by adding a ``<virtualport type='midonet'/>`` to the interface definition. ( -:since:`Since 1.2.13` ). The Midonet virtualport type requires an -``interfaceid`` attribute in its ``<parameters>`` element. This interface id is -the UUID that specifies which port in the virtual network topology will be bound -to the interface. - -:: - - ... - <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> - ... - -:anchor:`<a id="elementsNICSSlirp"/>` - -Userspace SLIRP stack -^^^^^^^^^^^^^^^^^^^^^ - -Provides a virtual LAN with NAT to the outside world. The virtual network has -DHCP & DNS services and will give the guest VM addresses starting from -``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server will -be ``10.0.2.3``. This networking is the only option for unprivileged users who -need their VMs to have outgoing access. :since:`Since 3.8.0` it is possible to -override the default network address by including an ``ip`` element specifying -an IPv4 address in its one mandatory attribute, ``address``. Optionally, a -second ``ip`` element with a ``family`` attribute set to "ipv6" can be specified -to add an IPv6 address to the interface. ``address``. Optionally, address -``prefix`` can be specified. - -:: - - ... - <devices> - <interface type='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> - ... - -:anchor:`<a id="elementsNICSEthernet"/>` - -Generic ethernet connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Provides a means to use a new or existing tap device (or veth device pair, -depening on the needs of the hypervisor driver) that is partially or wholly -setup external to libvirt (either prior to the guest starting, or while the -guest is being started via an optional script specified in the config). - -The name of the tap device can optionally be specified with the ``dev`` -attribute of the ``<target>`` element. If no target dev is specified, libvirt -will create a new standard tap device with a name of the pattern "vnetN", where -"N" is replaced with a number. If a target dev is specified and that device -doesn't exist, then a new standard tap device will be created with the exact dev -name given. If the specified target dev does exist, then that existing device -will be used. Usually some basic setup of the device is done by libvirt, -including setting a MAC address, and the IFF_UP flag, but if the ``dev`` is a -pre-existing device, and the ``managed`` attribute of the ``target`` element is -also set to "no" (the default value is "yes"), even this basic setup will not be -performed - libvirt will simply pass the device on to the hypervisor with no -setup at all. :since:`Since 5.7.0` Using managed='no' with a pre-created tap -device is useful because it permits a virtual machine managed by an unprivileged -libvirtd to have emulated network devices based on tap devices. - -After creating/opening the tap device, an optional shell script (given in the -``path`` attribute of the ``<script>`` element) will be run. :since:`Since -0.2.1` Also, after detaching/closing the tap device, an optional shell script -(given in the ``path`` attribute of the ``<downscript>`` element) will be run. -:since:`Since 5.1.0` These can be used to do whatever extra host network -integration is required. - -:: - - ... - <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> - ... - -:anchor:`<a id="elementsNICSDirect"/>` - -Direct attachment to physical interface -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -| Provides direct attachment of the virtual machine's NIC to the given physical - interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)` -| This setup requires the Linux macvtap driver to be available. :since:`(Since - Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port - Aggregator' <http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modul...), - 'bridge' or 'private' can be chosen for the operation mode of the macvtap - device, 'vepa' being the default mode. The individual modes cause the delivery - of packets to behave as follows: - -If the model type is set to ``virtio`` and interface's ``trustGuestRxFilters`` -attribute is set to ``yes``, changes made to the interface mac address, -unicast/multicast receive filters, and vlan settings in the guest will be -monitored and propagated to the associated macvtap device on the host ( -:since:`Since 1.2.10` ). If ``trustGuestRxFilters`` is not set, or is not -supported for the device model in use, an attempted change to the mac address -originating from the guest side will result in a non-working network connection. - -``vepa`` - All VMs' packets are sent to the external bridge. Packets whose destination - is a VM on the same host as where the packet originates from are sent back to - the host by the VEPA capable bridge (today's bridges are typically not VEPA - capable). -``bridge`` - Packets whose destination is on the same host as where they originate from - are directly delivered to the target macvtap device. Both origin and - destination devices need to be in bridge mode for direct delivery. If either - one of them is in ``vepa`` mode, a VEPA capable bridge is required. -``private`` - All packets are sent to the external bridge and will only be delivered to a - target VM on the same host if they are sent through an external router or - gateway and that device sends them back to the host. This procedure is - followed if either the source or destination device is in ``private`` mode. -``passthrough`` - This feature attaches a virtual function of a SRIOV capable NIC directly to a - VM without losing the migration capability. All packets are sent to the VF/IF - of the configured network device. Depending on the capabilities of the device - additional prerequisites or limitations may apply; for example, on Linux this - requires kernel 2.6.38 or newer. :since:`Since 0.9.2` - -:: - - ... - <devices> - ... - <interface type='direct' trustGuestRxFilters='no'> - <source dev='eth0' mode='vepa'/> - </interface> - </devices> - ... - -The network access of direct attached virtual machines can be managed by the -hardware switch to which the physical interface of the host machine is connected -to. - -The interface can have additional parameters as shown below, if the switch is -conforming to the IEEE 802.1Qbg standard. The parameters of the virtualport -element are documented in more detail in the IEEE 802.1Qbg standard. The values -are network specific and should be provided by the network administrator. In -802.1Qbg terms, the Virtual Station Interface (VSI) represents the virtual -interface of a virtual machine. :since:`Since 0.8.2` - -Please note that IEEE 802.1Qbg requires a non-zero value for the VLAN ID. - -``managerid`` - The VSI Manager ID identifies the database containing the VSI type and - instance definitions. This is an integer value and the value 0 is reserved. -``typeid`` - The VSI Type ID identifies a VSI type characterizing the network access. VSI - types are typically managed by network administrator. This is an integer - value. -``typeidversion`` - The VSI Type Version allows multiple versions of a VSI Type. This is an - integer value. -``instanceid`` - The VSI Instance ID Identifier is generated when a VSI instance (i.e. a - virtual interface of a virtual machine) is created. This is a globally unique - identifier. - -:: - - ... - <devices> - ... - <interface type='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> - ... - -The interface can have additional parameters as shown below if the switch is -conforming to the IEEE 802.1Qbh standard. The values are network specific and -should be provided by the network administrator. :since:`Since 0.8.2` - -``profileid`` - The profile ID contains the name of the port profile that is to be applied to - this interface. This name is resolved by the port profile database into the - network parameters from the port profile, and those network parameters will - be applied to this interface. - -:: - - ... - <devices> - ... - <interface type='direct'> - <source dev='eth0' mode='private'/> - <virtualport type='802.1Qbh'> - <parameters profileid='finance'/> - </virtualport> - </interface> - </devices> - ... - -:anchor:`<a id="elementsNICSHostdev"/>` - -PCI Passthrough -^^^^^^^^^^^^^^^ - -A PCI network device (specified by the <source> element) is directly assigned to -the guest using generic device passthrough, after first optionally setting the -device's MAC address to the configured value, and associating the device with an -802.1Qbh capable switch using an optionally specified <virtualport> element (see -the examples of virtualport given above for type='direct' network devices). Note -that - due to limitations in standard single-port PCI ethernet card driver -design - only SR-IOV (Single Root I/O Virtualization) virtual function (VF) -devices can be assigned in this manner; to assign a standard single-port PCI or -PCIe ethernet card to a guest, use the traditional <hostdev> device definition -and :since:`Since 0.9.11` - -To use VFIO device assignment rather than traditional/legacy KVM device -assignment (VFIO is a new method of device assignment that is compatible with -UEFI Secure Boot), a type='hostdev' interface can have an optional ``driver`` -sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device -assignment you can set ``name`` to "kvm" (or simply omit the ``<driver>`` -element, since "kvm" is currently the default). :since:`Since 1.0.5 (QEMU and -KVM only, requires kernel 3.6 or newer)` - -Note that this "intelligent passthrough" of network devices is very similar to -the functionality of a standard <hostdev> device, the difference being that this -method allows specifying a MAC address and <virtualport> for the passed-through -device. If these capabilities are not required, if you have a standard -single-port PCI, PCIe, or USB network card that doesn't support SR-IOV (and -hence would anyway lose the configured MAC address during reset after being -assigned to the guest domain), or if you are using a version of libvirt older -than 0.9.11, you should use standard <hostdev> to assign the device to the guest -instead of <interface type='hostdev'/>. - -Similar to the functionality of a standard <hostdev> device, when ``managed`` is -"yes", it is detached from the host before being passed on to the guest, and -reattached to the host after the guest exits. If ``managed`` is omitted or "no", -the user is responsible to call ``virNodeDeviceDettach`` (or -``virsh nodedev-detach``) before starting the guest or hot-plugging the device, -and ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug -or stopping the guest. - -:: - - ... - <devices> - <interface type='hostdev' managed='yes'> - <driver name='vfio'/> - <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> - ... - -:anchor:`<a id="elementsTeaming"/>` - -Teaming a virtio/hostdev NIC pair -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:since:`Since 6.1.0 (QEMU and KVM only, requires QEMU 4.2.0 or newer and a guest -virtio-net driver supporting the "failover" feature, such as the one included in -Linux kernel 4.18 and newer) ` The ``<teaming>`` element of two interfaces can -be used to connect them as a team/bond device in the guest (assuming proper -support in the hypervisor and the guest network driver). - -:: - - ... - <devices> - <interface type='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> - ... - -The ``<teaming>`` element required attribute ``type`` will be set to either -``"persistent"`` to indicate a device that should always be present in the -domain, or ``"transient"`` to indicate a device that may periodically be -removed, then later re-added to the domain. When type="transient", there should -be a second attribute to ``<teaming>`` called ``"persistent"`` - this attribute -should be set to the alias name of the other device in the pair (the one that -has ``<teaming type="persistent'/>``). - -In the particular case of QEMU, libvirt's ``<teaming>`` element is used to setup -a virtio-net "failover" device pair. For this setup, the persistent device must -be an interface with ``<model type="virtio"/>``, and the transient device -must be ``<interface type='hostdev'/>`` (or ``<interface type='network'/>`` -where the referenced network defines a pool of SRIOV VFs). The guest will then -have a simple network team/bond device made of the virtio NIC + hostdev NIC -pair. In this configuration, the higher-performing hostdev NIC will normally be -preferred for all network traffic, but when the domain is migrated, QEMU will -automatically unplug the VF from the guest, and then hotplug a similar device -once migration is completed; while migration is taking place, network traffic -will use the virtio NIC. (Of course the emulated virtio NIC and the hostdev NIC -must be connected to the same subnet for bonding to work properly). - -NB1: Since you must know the alias name of the virtio NIC when configuring the -hostdev NIC, it will need to be manually set in the virtio NIC's configuration -(as with all other manually set alias names, this means it must start with -"ua-"). - -NB2: Currently the only implementation of the guest OS virtio-net driver -supporting virtio-net failover requires that the MAC addresses of the virtio and -hostdev NIC must match. Since that may not always be a requirement in the -future, libvirt doesn't enforce this limitation - it is up to the -person/management application that is creating the configuration to assure the -MAC addresses of the two devices match. - -NB3: Since the PCI addresses of the SRIOV VFs on the hosts that are the source -and destination of the migration will almost certainly be different, either -higher level management software will need to modify the ``<source>`` of the -hostdev NIC (``<interface type='hostdev'>``) at the start of migration, or (a -simpler solution) the configuration will need to use a libvirt "hostdev" virtual -network that maintains a pool of such devices, as is implied in the example's -use of the libvirt network named "hostdev-pool" - as long as the hostdev network -pools on both hosts have the same name, libvirt itself will take care of -allocating an appropriate device on both ends of the migration. Similarly the -XML for the virtio interface must also either work correctly unmodified on both -the source and destination of the migration (e.g. by connecting to the same -bridge device on both hosts, or by using the same virtual network), or the -management software must properly modify the interface XML during migration so -that the virtio device remains connected to the same network segment before and -after migration. - -:anchor:`<a id="elementsNICSMulticast"/>` - -Multicast tunnel -^^^^^^^^^^^^^^^^ - -A multicast group is setup to represent a virtual network. Any VMs whose network -devices are in the same multicast group can talk to each other even across -hosts. This mode is also available to unprivileged users. There is no default -DNS or DHCP support and no outgoing network access. To provide outgoing network -access, one of the VMs should have a 2nd NIC which is connected to one of the -first 4 network types and do the appropriate routing. The multicast protocol is -compatible with that used by user mode linux guests too. The source address used -must be from the multicast address block. - -:: - - ... - <devices> - <interface type='mcast'> - <mac address='52:54:00:6d:90:01'/> - <source address='230.0.0.1' port='5558'/> - </interface> - </devices> - ... - -:anchor:`<a id="elementsNICSTCP"/>` - -TCP tunnel -^^^^^^^^^^ - -A TCP client/server architecture provides a virtual network. One VM provides the -server end of the network, all other VMS are configured as clients. All network -traffic is routed between the VMs via the server. This mode is also available to -unprivileged users. There is no default DNS or DHCP support and no outgoing -network access. To provide outgoing network access, one of the VMs should have a -2nd NIC which is connected to one of the first 4 network types and do the -appropriate routing. - -:: - - ... - <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> - ... - -:anchor:`<a id="elementsNICSUDP"/>` - -UDP unicast tunnel -^^^^^^^^^^^^^^^^^^ - -A UDP unicast architecture provides a virtual network which enables connections -between QEMU instances using QEMU's UDP infrastructure. The xml "source" address -is the endpoint address to which the UDP socket packets will be sent from the -host running QEMU. The xml "local" address is the address of the interface from -which the UDP socket packets will originate from the QEMU host. :since:`Since -1.2.20` - -:: - - ... - <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> - ... - -:anchor:`<a id="elementsNICSModel"/>` - -Setting the NIC model -^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <target dev='vnet1'/> - <model type='ne2k_pci'/> - </interface> - </devices> - ... - -For hypervisors which support this, you can set the model of emulated network -interface card. - -The values for ``type`` aren't defined specifically by libvirt, but by what the -underlying hypervisor supports (if any). For QEMU and KVM you can get a list of -supported models with these commands: - -:: - - qemu -net nic,model=? /dev/null - qemu-kvm -net nic,model=? /dev/null - -Typical values for QEMU and KVM include: ne2k_isa i82551 i82557b i82559er -ne2k_pci pcnet rtl8139 e1000 virtio. :since:`Since 5.2.0` , -``virtio-transitional`` and ``virtio-non-transitional`` values are supported. -See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more -details. - -:anchor:`<a id="elementsDriverBackendOptions"/>` - -Setting NIC driver-specific options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <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> - ... - -Some NICs may have tunable driver-specific options. These are set as attributes -of the ``driver`` sub-element of the interface definition. Currently the -following attributes are available for the ``"virtio"`` NIC driver: - -``name`` - The optional ``name`` attribute forces which type of backend driver to use. - The value can be either 'qemu' (a user-space backend) or 'vhost' (a kernel - backend, which requires the vhost module to be provided by the kernel); an - attempt to require the vhost driver without kernel support will be rejected. - If this attribute is not present, then the domain defaults to 'vhost' if - present, but silently falls back to 'qemu' without error. :since:`Since 0.8.8 - (QEMU and KVM only)` - For interfaces of type='hostdev' (PCI passthrough devices) the ``name`` - attribute can optionally be set to "vfio" or "kvm". "vfio" tells libvirt to - use VFIO device assignment rather than traditional KVM device assignment - (VFIO is a new method of device assignment that is compatible with UEFI - Secure Boot), and "kvm" tells libvirt to use the legacy device assignment - performed directly by the kvm kernel module (the default is currently "kvm", - but is subject to change). :since:`Since 1.0.5 (QEMU and KVM only, requires - kernel 3.6 or newer)` - For interfaces of type='vhostuser', the ``name`` attribute is ignored. The - backend driver used is always vhost-user. -``txmode`` - The ``txmode`` attribute specifies how to handle transmission of packets when - the transmit buffer is full. The value can be either 'iothread' or 'timer'. - :since:`Since 0.8.8 (QEMU and KVM only)` - If set to 'iothread', packet tx is all done in an iothread in the bottom half - of the driver (this option translates into adding "tx=bh" to the qemu - commandline -device virtio-net-pci option). - If set to 'timer', tx work is done in qemu, and if there is more tx data than - can be sent at the present time, a timer is set before qemu moves on to do - other things; when the timer fires, another attempt is made to send more - data. - The resulting difference, according to the qemu developer who added the - option is: "bh makes tx more asynchronous and reduces latency, but - potentially causes more processor bandwidth contention since the CPU doing - the tx isn't necessarily the CPU where the guest generated the packets." - **In general you should leave this option alone, unless you are very certain - you know what you are doing.** -``ioeventfd`` - This optional attribute allows users to set `domain I/O asynchronous - handling <https://patchwork.kernel.org/patch/43390/>`__ for interface device. - The default is left to the discretion of the hypervisor. Accepted values are - "on" and "off". Enabling this allows qemu to execute VM while a separate - thread handles I/O. Typically guests experiencing high system CPU utilization - during I/O will benefit from this. On the other hand, on overloaded host it - could increase guest I/O latency. :since:`Since 0.9.3 (QEMU and KVM only)` - **In general you should leave this option alone, unless you are very certain - you know what you are doing.** -``event_idx`` - The ``event_idx`` attribute controls some aspects of device event processing. - The value can be either 'on' or 'off' - if it is on, it will reduce the - number of interrupts and exits for the guest. The default is determined by - QEMU; usually if the feature is supported, default is on. In case there is a - situation where this behavior is suboptimal, this attribute provides a way to - force the feature off. :since:`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.** -``queues`` - The optional ``queues`` attribute controls the number of queues to be used - for either `Multiqueue - virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or - `vhost-user <#elementVhostuser>`__ network interfaces. Use of multiple packet - processing queues requires the interface having the - ``<model type='virtio'/>`` element. Each queue will potentially be handled by - a different processor, resulting in much higher throughput. - :since:`virtio-net since 1.0.6 (QEMU and KVM only)` :since:`vhost-user since - 1.2.17 (QEMU and KVM only)` -``rx_queue_size`` - The optional ``rx_queue_size`` attribute controls the size of virtio ring for - each queue as described above. The default value is hypervisor dependent and - may change across its releases. Moreover, some hypervisors may pose some - restrictions on actual value. For instance, latest QEMU (as of 2016-09-01) - requires value to be a power of two from [256, 1024] range. :since:`Since - 2.3.0 (QEMU and KVM only)` - **In general you should leave this option alone, unless you are very certain - you know what you are doing.** -``tx_queue_size`` - The optional ``tx_queue_size`` attribute controls the size of virtio ring for - each queue as described above. The default value is hypervisor dependent and - may change across its releases. Moreover, some hypervisors may pose some - restrictions on actual value. For instance, QEMU v2.9 requires value to be a - power of two from [256, 1024] range. In addition to that, this may work only - for a subset of interface types, e.g. aforementioned QEMU enables this option - only for ``vhostuser`` type. :since:`Since 3.7.0 (QEMU and KVM only)` - **In general you should leave this option alone, unless you are very certain - you know what you are doing.** -virtio options - For virtio interfaces, `Virtio-specific options <#elementsVirtio>`__ can also - be set. ( :since:`Since 3.5.0` ) - -Offloading options for the host and guest can be configured using the following -sub-elements: - -``host`` - The ``csum``, ``gso``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes - with possible values ``on`` and ``off`` can be used to turn off host - offloading options. By default, the supported offloads are enabled by QEMU. - :since:`Since 1.2.9 (QEMU only)` The ``mrg_rxbuf`` attribute can be used to - control mergeable rx buffers on the host side. Possible values are ``on`` - (default) and ``off``. :since:`Since 1.2.13 (QEMU only)` -``guest`` - The ``csum``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes with - possible values ``on`` and ``off`` can be used to turn off guest offloading - options. By default, the supported offloads are enabled by QEMU. - :since:`Since 1.2.9 (QEMU only)` - -:anchor:`<a id="elementsBackendOptions"/>` - -Setting network backend-specific options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <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> - ... - -For tuning the backend of the network, the ``backend`` element can be used. The -``vhost`` attribute can override the default vhost device path -(``/dev/vhost-net``) for devices with ``virtio`` model. The ``tap`` attribute -overrides the tun/tap device path (default: ``/dev/net/tun``) for network and -bridge interfaces. This does not work in session mode. :since:`Since 1.2.9` - -For tap devices there is also ``sndbuf`` element which can adjust the size of -send buffer in the host. :since:`Since 0.8.8` - -:anchor:`<a id="elementsNICSTargetOverride"/>` - -Overriding the target element -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <target dev='vnet1'/> - </interface> - </devices> - ... - -If no target is specified, certain hypervisors will automatically generate a -name for the created tun device. This name can be manually specified, however -the name *should not start with either 'vnet', 'vif', 'macvtap', or 'macvlan'*, -which are prefixes reserved by libvirt and certain hypervisors. Manually -specified targets using these prefixes may be ignored. - -Note that for LXC containers, this defines the name of the interface on the host -side. :since:`Since 1.2.7` , to define the name of the device on the guest side, -the ``guest`` element should be used, as in the following snippet: - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <guest dev='myeth'/> - </interface> - </devices> - ... - -:anchor:`<a id="elementsNICSBoot"/>` - -Specifying boot order -^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <target dev='vnet1'/> - <boot order='1'/> - </interface> - </devices> - ... - -For hypervisors which support this, you can set a specific NIC to be used for -network boot. The ``order`` attribute determines the order in which devices will -be tried during boot sequence. The per-device ``boot`` elements cannot be used -together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__ -section. :since:`Since 0.8.8` - -:anchor:`<a id="elementsNICSROM"/>` - -Interface ROM BIOS configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <target dev='vnet1'/> - <rom bar='on' file='/etc/fake/boot.bin'/> - </interface> - </devices> - ... - -For hypervisors which support this, you can change how a PCI Network device's -ROM is presented to the guest. The ``bar`` attribute can be set to "on" or -"off", and determines whether or not the device's ROM will be visible in the -guest's memory map. (In PCI documentation, the "rombar" setting controls the -presence of the Base Address Register for the ROM). If no rom bar is specified, -the qemu default will be used (older versions of qemu used a default of "off", -while newer qemus have a default of "on"). The optional ``file`` attribute is -used to point to a binary file to be presented to the guest as the device's ROM -BIOS. This can be useful to provide an alternative boot ROM for a network -device. :since:`Since 0.9.10 (QEMU and KVM only)` . - -:anchor:`<a id="elementDomain"/>` - -Setting up a network backend in a driver domain -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - ... - <interface type='bridge'> - <source bridge='br0'/> - <backenddomain name='netvm'/> - </interface> - ... - </devices> - ... - -The optional ``backenddomain`` element allows specifying a backend domain (aka -driver domain) for the interface. Use the ``name`` attribute to specify the -backend domain name. You can use it to create a direct network link between -domains (so data will not go through host system). Use with type 'ethernet' to -create plain network link, or with type 'bridge' to connect to a bridge inside -the backend domain. :since:`Since 1.2.13 (Xen only)` - -:anchor:`<a id="elementQoS"/>` - -Quality of service -^^^^^^^^^^^^^^^^^^ - -:: - - ... - <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> - ... - -This part of interface XML provides setting quality of service. Incoming and -outgoing traffic can be shaped independently. The ``bandwidth`` element and its -child elements are described in the `QoS <formatnetwork.html#elementQoS>`__ -section of the Network XML. - -:anchor:`<a id="elementVlanTag"/>` - -Setting VLAN tag (on supported network types only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <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> - ... - -If (and only if) the network connection used by the guest supports VLAN tagging -transparent to the guest, an optional ``<vlan>`` element can specify one or more -VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` . -Network connections that support guest-transparent VLAN tagging include 1) -type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since -0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device -assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with -mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other -connection types, including standard linux bridges and libvirt's own virtual -networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches -provide their own way (outside of libvirt) to tag guest traffic onto a specific -VLAN. Each tag is given in a separate ``<tag>`` subelement of ``<vlan>`` (for -example: ``<tag id='42'/>``). For VLAN trunking of multiple tags (which is -supported only on Open vSwitch connections), multiple ``<tag>`` subelements can -be specified, which implies that the user wants to do VLAN trunking on the -interface for all the specified tags. In the case that VLAN trunking of a single -tag is desired, the optional attribute ``trunk='yes'`` can be added to the -toplevel ``<vlan>`` element to differentiate trunking of a single tag from -normal tagging. - -For network connections using Open vSwitch it is also possible to configure -'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is -done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement: -``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the -``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to -be the "native" VLAN for this interface, and the ``nativeMode`` attribute -determines whether or not traffic for that VLAN will be tagged. - -:anchor:`<a id="elementPort"/>` - -Isolating guests's network traffic from each other -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <port isolated='yes'/> - </interface> - </devices> - ... - -:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to -``yes`` (default setting is ``no``) is used to isolate this interface's network -traffic from that of other guest interfaces connected to the same network that -also have ``<port isolated='yes'/>``. This setting is only supported for -emulated interface devices that use a standard tap device to connect to the -network via a Linux host bridge. This property can be inherited from a libvirt -network, so if all guests that will be connected to the network should be -isolated, it is better to put the setting in the network configuration. (NB: -this only prevents guests that have ``isolated='yes'`` from communicating with -each other; if there is a guest on the same bridge that doesn't have -``isolated='yes'``, even the isolated guests will be able to communicate with -it.) - -:anchor:`<a id="elementLink"/>` - -Modifying virtual link state -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <target dev='vnet0'/> - <link state='down'/> - </interface> - </devices> - ... - -This element provides means of setting state of the virtual network link. -Possible values for attribute ``state`` are ``up`` and ``down``. If ``down`` is -specified as the value, the interface behaves as if it had the network cable -disconnected. Default behavior if this element is unspecified is to have the -link state ``up``. :since:`Since 0.9.5` - -:anchor:`<a id="mtu"/>` - -MTU configuration -^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <target dev='vnet0'/> - <mtu size='1500'/> - </interface> - </devices> - ... - -This element provides means of setting MTU of the virtual network link. -Currently there is just one attribute ``size`` which accepts a non-negative -integer which specifies the MTU size for the interface. :since:`Since 3.1.0` - -:anchor:`<a id="coalesce"/>` - -Coalesce settings -^^^^^^^^^^^^^^^^^ - -:: - - ... - <devices> - <interface type='network'> - <source network='default'/> - <target dev='vnet0'/> - <coalesce> - <rx> - <frames max='7'/> - </rx> - </coalesce> - </interface> - </devices> - ... - -This element provides means of setting coalesce settings for some interface -devices (currently only type ``network`` and ``bridge``. Currently there is just -one attribute, ``max``, to tweak, in element ``frames`` for the ``rx`` group, -which accepts a non-negative integer that specifies the maximum number of -packets that will be received before an interrupt. :since:`Since 3.3.0` - -:anchor:`<a id="ipconfig"/>` - -IP configuration -^^^^^^^^^^^^^^^^ - -:: - - ... - <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> - ... - -:since:`Since 1.2.12` network devices and hostdev devices with network -capabilities can optionally be provided one or more IP addresses to set on the -network device in the guest. Note that some hypervisors or network device types -will simply ignore them or only use the first one. The ``family`` attribute can -be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains -the IP address. The optional ``prefix`` is the number of 1 bits in the netmask, -and will be automatically set if not specified - for IPv4 the default prefix is -determined according to the network "class" (A, B, or C - see RFC870), and for -IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP -address of the other end of a point-to-point network device :since:`(since -2.1.0)` . - -:since:`Since 1.2.12` route elements can also be added to define IP routes to -add in the guest. The attributes of this element are described in the -documentation for the ``route`` element in `network -definitions <formatnetwork.html#elementsStaticroute>`__. This is used by the LXC -driver. - -:: - - ... - <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> - ... - -:since:`Since 2.1.0` network devices of type "ethernet" can optionally be -provided one or more IP addresses and one or more routes to set on the **host** -side of the network device. These are configured as subelements of the -``<source>`` element of the interface, and have the same attributes as the -similarly named elements used to configure the guest side of the interface -(described above). - -:anchor:`<a id="elementVhostuser"/>` - -vhost-user interface -^^^^^^^^^^^^^^^^^^^^ - -:since:`Since 1.2.7` the vhost-user enables the communication between a QEMU -virtual machine and other userspace process using the Virtio transport protocol. -A char dev (e.g. Unix socket) is used for the control plane, while the data -plane is based on shared memory. - -:: - - ... - <devices> - <interface type='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> - ... - -The ``<source>`` element has to be specified along with the type of char device. -Currently, only type='unix' is supported, where the path (the directory path of -the socket) and mode attributes are required. Both ``mode='server'`` and -``mode='client'`` are supported. vhost-user requires the virtio model type, thus -the ``<model>`` element is mandatory. :since:`Since 4.1.0` the element has an -optional child element ``reconnect`` which configures reconnect timeout if the -connection is lost. It has two attributes ``enabled`` (which accepts ``yes`` and -``no``) and ``timeout`` which specifies the amount of seconds after which -hypervisor tries to reconnect. - -:anchor:`<a id="elementNwfilter"/>` - -Traffic filtering with NWFilter -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:since:`Since 0.8.0` an ``nwfilter`` profile can be assigned to a domain -interface, which allows configuring traffic filter rules for the virtual -machine. See the `nwfilter <formatnwfilter.html>`__ documentation for more -complete details. - -:: - - ... - <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> - ... - -The ``filter`` attribute specifies the name of the nwfilter to use. Optional -``<parameter>`` elements may be specified for passing additional info to the -nwfilter via the ``name`` and ``value`` attributes. See the -`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters. - -:anchor:`<a id="elementsInput"/>` - -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> - </devices> - ... - -``input`` - The ``input`` element has one mandatory attribute, the ``type`` whose value - can be 'mouse', 'tablet', ( :since:`since 1.2.2` ) 'keyboard' or ( - :since:`since 1.3.0` ) 'passthrough'. The tablet provides absolute cursor - movement, while the mouse uses relative movement. The optional ``bus`` - attribute can be used to refine the exact device type. It takes values "xen" - (paravirtualized), "ps2" and "usb" or ( :since:`since 1.3.0` ) "virtio". - -The ``input`` element has an optional sub-element ``<address>`` which can tie -the device to a particular PCI slot, `documented above <#elementsAddress>`__. On -S390, ``address`` can be used to provide a CCW address for an input device ( -:since:`since 4.2.0` ). For type ``passthrough``, the mandatory sub-element -``source`` must have an ``evdev`` attribute containing the absolute path to the -event device passed through to guests. (KVM only) :since:`Since 5.2.0` , the -``input`` element accepts a ``model`` attribute which has the values 'virtio', -'virtio-transitional' and 'virtio-non-transitional'. See `Virtio transitional -devices <#elementsVirtioTransitional>`__ for more details. - -The subelement ``driver`` can be used to tune the virtio options of the device: -`Virtio-specific options <#elementsVirtio>`__ can also be set. ( :since:`Since -3.5.0` ) - -:anchor:`<a id="elementsHub"/>` - -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>`` with -``type='usb'``\ which can tie the device to a particular controller, `documented -above <#elementsAddress>`__. - -:anchor:`<a id="elementsGraphics"/>` - -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:`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:`since 1.0.6` . - - Rather than using listen/port, QEMU supports a ``socket`` attribute for - listening on a unix domain socket path :since:`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:`Since - 1.0.6` . - - 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. - - ``spice`` :since:`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:`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:`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:` since 0.8.6` ); ``smartcard`` ( :since:`since 0.8.8` ); and - ``usbredir`` ( :since:`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:`Since 0.9.1` - - Streaming mode is set by the ``streaming`` element, settings its ``mode`` - attribute to one of ``filter``, ``all`` or ``off``. :since:`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:`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:`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:`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:`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:`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:`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 :since:`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> - -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:`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:`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:`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:`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``. - -:anchor:`<a id="elementsVideo"/>` - -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:`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:`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:`since 0.8.6` - ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs" - ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" ( - :since:`since 4.6.0` , depending on the hypervisor features available. The - purpose of the type ``none`` is to instruct libvirt not to add a default - video device in the guest (see the paragraph above). This legacy behaviour - can be inconvenient in cases where GPU mediated devices are meant to be the - only rendering device within a guest and so specifying another ``video`` - device along with type ``none``. Refer to Host device assignment to see how - to add a mediated device into a guest. - - You can provide the amount of video memory in kibibytes (blocks of 1024 - bytes) using ``vram``. This is supported only for guest type of "vz", "qemu", - "vbox", "vmx" and "xen". If no value is provided the default is used. If the - size is not a 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", "vbox" and "vmx". - - For guest type of "kvm" or "qemu" and model type "qxl" there are optional - attributes. Attribute ``ram`` ( :since:` 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:`since 1.2.11` ) to set the size of - VGA framebuffer for fallback mode of QXL device. Attribute ``vram64`` ( - :since:`since 1.3.3` ) extends secondary bar and makes it addressable as - 64bit memory. - - :since:`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", and "virtio". - -``acceleration`` - Configure if video acceleration should be enabled. - - ``accel2d`` - Enable 2D acceleration (for vbox driver only, :since:`since 0.7.1` ) - ``accel3d`` - Enable 3D acceleration (for vbox driver :since:`since 0.7.1` , qemu driver - :since:`since 1.3.0` ) - ``rendernode`` - Absolute path to a host's DRI device to be used for rendering (for - 'vhostuser' driver only, :since:`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:` 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:`since 5.8.0` ). "qemu" is - the default QEMU backend. "vhostuser" will use a separate vhost-user - process backend (for ``virtio`` device). - virtio options - `Virtio-specific options <#elementsVirtio>`__ can also be set ( - :since:`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:`Since 3.5.0` ) - -:anchor:`<a id="elementsConsole"/>` - -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 <#seclabel>`__. - -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:`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:`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 <#elementsControllers>`__ 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:`Since 3.7.0 (QEMU driver -only)` . - -:anchor:`<a id="elementsCharGuestInterface"/>` - -Guest interface -^^^^^^^^^^^^^^^ - -A character device presents itself to the guest as one of the following types. - -:anchor:`<a id="elementCharParallel"/>` - -Parallel port -''''''''''''' - -:: - - ... - <devices> - <parallel type='pty'> - <source path='/dev/pts/2'/> - <target port='0'/> - </parallel> - </devices> - ... - -``target`` can have a ``port`` attribute, which specifies the port number. Ports -are numbered starting from 0. There are usually 0, 1 or 2 parallel ports. - -:anchor:`<a id="elementCharSerial"/>` - -Serial port -''''''''''' - -:: - - ... - <devices> - <!-- Serial port --> - <serial type='pty'> - <source path='/dev/pts/3'/> - <target port='0'/> - </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> - ... - -The ``target`` element can have an optional ``port`` attribute, which specifies -the port number (starting from 0), and an optional ``type`` attribute: valid -values are, :since:`since 1.0.2` , ``isa-serial`` (usable with x86 guests), -``usb-serial`` (usable whenever USB support is available) and ``pci-serial`` -(usable whenever PCI support is available); :since:`since 3.10.0` , -``spapr-vio-serial`` (usable with ppc64/pseries guests), ``system-serial`` -(usable with aarch64/virt and, :since:`since 4.7.0` , riscv/virt guests) and -``sclp-serial`` (usable with s390 and s390x guests) are available as well. - -:since:`Since 3.10.0` , the ``target`` element can have an optional ``model`` -subelement; valid values for its ``name`` attribute are: ``isa-serial`` (usable -with the ``isa-serial`` target type); ``usb-serial`` (usable with the -``usb-serial`` target type); ``pci-serial`` (usable with the ``pci-serial`` -target type); ``spapr-vty`` (usable with the ``spapr-vio-serial`` target type); -``pl011`` and, :since:`since 4.7.0` , ``16550a`` (usable with the -``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable -with the ``sclp-serial`` target type). Providing a target model is usually -unnecessary: libvirt will automatically pick one that's suitable for the chosen -target type, and overriding that value is generally not recommended. - -If any of the attributes is not specified by the user, libvirt will choose a -value suitable for most users. - -Most target types support configuring the guest-visible device address as -`documented above <#elementsAddress>`__; more specifically, acceptable address -types are ``isa`` (for ``isa-serial``), ``usb`` (for ``usb-serial``), ``pci`` -(for ``pci-serial``) and ``spapr-vio`` (for ``spapr-vio-serial``). The -``system-serial`` and ``sclp-serial`` target types don't support specifying an -address. - -For the relationship between serial ports and consoles, `see -below <#elementCharSerialAndConsole>`__. - -:anchor:`<a id="elementCharConsole"/>` - -Console -''''''' - -:: - - ... - <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> - ... - -The ``console`` element is used to represent interactive serial consoles. -Depending on the type of guest in use and the specifics of the configuration, -the ``console`` element might represent the same device as an existing -``serial`` element or a separate device. - -A ``target`` subelement is supported and works the same way as with the -``serial`` element (`see above <#elementCharSerial>`__ for details). Valid -values for the ``type`` attribute are: ``serial`` (described below); ``virtio`` -(usable whenever VirtIO support is available); ``xen``, ``lxc`` and ``openvz`` -(available when the corresponding hypervisor is in use). ``sclp`` and ``sclplm`` -(usable for s390 and s390x QEMU guests) are supported for compatibility reasons -but should not be used for new guests: use the ``sclpconsole`` and -``sclplmconsole`` target models, respectively, with the ``serial`` element -instead. - -Of the target types listed above, ``serial`` is special in that it doesn't -represents a separate device, but rather the same device as the first ``serial`` -element. Due to this, there can only be a single ``console`` element with target -type ``serial`` per guest. - -Virtio consoles are usually accessible as ``/dev/hvc[0-7]`` from inside the -guest; for more information, see -http://fedoraproject.org/wiki/Features/VirtioSerial. :since:`Since 0.8.3` - -For the relationship between serial ports and consoles, `see -below <#elementCharSerialAndConsole>`__. - -:anchor:`<a id="elementCharSerialAndConsole"/>` - -Relationship between serial ports and consoles -'''''''''''''''''''''''''''''''''''''''''''''' - -Due to hystorical reasons, the ``serial`` and ``console`` elements have -partially overlapping scopes. - -In general, both elements are used to configure one or more serial consoles to -be used for interacting with the guest. The main difference between the two is -that ``serial`` is used for emulated, usually native, serial consoles, whereas -``console`` is used for paravirtualized ones. - -Both emulated and paravirtualized serial consoles have advantages and -disadvantages: - -- emulated serial consoles are usually initialized much earlier than - paravirtualized ones, so they can be used to control the bootloader and - display both firmware and early boot messages; -- on several platforms, there can only be a single emulated serial console per - guest but paravirtualized consoles don't suffer from the same limitation. - -A configuration such as: - -:: - - ... - <devices> - <console type='pty'> - <target type='serial'/> - </console> - <console type='pty'> - <target type='virtio'/> - </console> - </devices> - ... - -will work on any platform and will result in one emulated serial console for -early boot logging / interactive / recovery use, and one paravirtualized serial -console to be used eg. as a side channel. Most people will be fine with having -just the first ``console`` element in their configuration, but if a specific -configuration is desired then both elements should be specified. - -Note that, due to the compatibility concerns mentioned earlier, all the -following configurations: - -:: - - ... - <devices> - <serial type='pty'/> - </devices> - ... - -:: - - ... - <devices> - <console type='pty'/> - </devices> - ... - -:: - - ... - <devices> - <serial type='pty'/> - <console type='pty'/> - </devices> - ... - -will be treated the same and will result in a single emulated serial console -being available to the guest. - -:anchor:`<a id="elementCharChannel"/>` - -Channel -''''''' - -This represents a private communication channel between the host and the guest. - -:: - - ... - <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> - ... - -This can be implemented in a variety of ways. The specific type of channel is -given in the ``type`` attribute of the ``target`` element. Different channel -types have different ``target`` attributes. - -``guestfwd`` - TCP traffic sent by the guest to a given IP address and port is forwarded to - the channel device on the host. The ``target`` element must have ``address`` - and ``port`` attributes. :since:`Since 0.7.3` -``virtio`` - Paravirtualized virtio channel. Channel is exposed in the guest under - /dev/vport*, and if the optional element ``name`` is specified, - /dev/virtio-ports/$name (for more info, please see - http://fedoraproject.org/wiki/Features/VirtioSerial). The optional element - ``address`` can tie the channel to a particular ``type='virtio-serial'`` - controller, `documented above <#elementsAddress>`__. With qemu, if ``name`` - is "org.qemu.guest_agent.0", then libvirt can interact with a guest agent - installed in the guest, for actions such as guest shutdown or file system - quiescing. :since:`Since 0.7.7, guest agent interaction since 0.9.10` - Moreover, :since:`since 1.0.6` it is possible to have source path auto - generated for virtio unix channels. This is very useful in case of a qemu - guest agent, where users don't usually care about the source path since it's - libvirt who talks to the guest agent. In case users want to utilize this - feature, they should leave ``<source>`` element out. :since:`Since 1.2.11` - the active XML for a virtio channel may contain an optional ``state`` - attribute that reflects whether a process in the guest is active on the - channel. This is an output-only attribute. Possible values for the ``state`` - attribute are ``connected`` and ``disconnected``. -``xen`` - Paravirtualized Xen channel. Channel is exposed in the guest as a Xen console - but identified with a name. Setup and consumption of a Xen channel depends on - software and configuration in the guest (for more info, please see - http://xenbits.xen.org/docs/unstable/misc/channel.txt). Channel source path - semantics are the same as the virtio target type. The ``state`` attribute is - not supported since Xen channels lack the necessary probing mechanism. - :since:`Since 2.3.0` -``spicevmc`` - Paravirtualized SPICE channel. The domain must also have a SPICE server as a - `graphics device <#elementsGraphics>`__, at which point the host piggy-backs - messages across the ``main`` channel. The ``target`` element must be present, - with attribute ``type='virtio'``; an optional attribute ``name`` controls how - the guest will have access to the channel, and defaults to - ``name='com.redhat.spice.0'``. The optional ``address`` element can tie the - channel to a particular ``type='virtio-serial'`` controller. :since:`Since - 0.8.8` - -:anchor:`<a id="elementsCharHostInterface"/>` - -Host interface -^^^^^^^^^^^^^^ - -A character device presents itself to the host as one of the following types. - -:anchor:`<a id="elementsCharSTDIO"/>` - -Domain logfile -'''''''''''''' - -This disables all input on the character device, and sends output into the -virtual machine's logfile - -:: - - ... - <devices> - <console type='stdio'> - <target port='1'/> - </console> - </devices> - ... - -:anchor:`<a id="elementsCharFle"/>` - -Device logfile -'''''''''''''' - -A file is opened and all data sent to the character device is written to the -file. - -:: - - ... - <devices> - <serial type="file"> - <source path="/var/log/vm/vm-serial.log"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharVC"/>` - -Virtual console -''''''''''''''' - -Connects the character device to the graphical framebuffer in a virtual console. -This is typically accessed via a special hotkey sequence such as "ctrl+alt+3" - -:: - - ... - <devices> - <serial type='vc'> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharNull"/>` - -Null device -''''''''''' - -Connects the character device to the void. No data is ever provided to the -input. All data written is discarded. - -:: - - ... - <devices> - <serial type='null'> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharPTY"/>` - -Pseudo TTY -'''''''''' - -A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as 'virsh -console' can connect to interact with the serial port locally. - -:: - - ... - <devices> - <serial type="pty"> - <source path="/dev/pts/3"/> - <target port="1"/> - </serial> - </devices> - ... - -NB special case if <console type='pty'>, then the TTY path is also duplicated as -an attribute tty='/dev/pts/3' on the top level <console> tag. This provides -compat with existing syntax for <console> tags. - -:anchor:`<a id="elementsCharHost"/>` - -Host device proxy -''''''''''''''''' - -The character device is passed through to the underlying physical character -device. The device types must match, eg the emulated serial port should only be -connected to a host serial port - don't connect a serial port to a parallel -port. - -:: - - ... - <devices> - <serial type="dev"> - <source path="/dev/ttyS0"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharPipe"/>` - -Named pipe -'''''''''' - -The character device writes output to a named pipe. See pipe(7) for more info. - -:: - - ... - <devices> - <serial type="pipe"> - <source path="/tmp/mypipe"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharTCP"/>` - -TCP client/server -''''''''''''''''' - -The character device acts as a TCP client connecting to a remote server. - -:: - - ... - <devices> - <serial type="tcp"> - <source mode="connect" host="0.0.0.0" service="2445"/> - <protocol type="raw"/> - <target port="1"/> - </serial> - </devices> - ... - -Or as a TCP server waiting for a client connection. - -:: - - ... - <devices> - <serial type="tcp"> - <source mode="bind" host="127.0.0.1" service="2445"/> - <protocol type="raw"/> - <target port="1"/> - </serial> - </devices> - ... - -Alternatively you can use ``telnet`` instead of ``raw`` TCP in order to utilize -the telnet protocol for the connection. - -:since:`Since 0.8.5,` some hypervisors support use of either ``telnets`` (secure -telnet) or ``tls`` (via secure sockets layer) as the transport protocol for -connections. - -:: - - ... - <devices> - <serial type="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> - ... - -:since:`Since 2.4.0,` the optional attribute ``tls`` can be used to control -whether a chardev TCP communication channel would utilize a hypervisor -configured TLS X.509 certificate environment in order to encrypt the data -channel. For the QEMU hypervisor, usage of a TLS environment can be controlled -on the host by the ``chardev_tls`` and ``chardev_tls_x509_cert_dir`` or -``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf. If -``chardev_tls`` is enabled, then unless the ``tls`` attribute is set to "no", -libvirt will use the host configured TLS environment. If ``chardev_tls`` is -disabled, but the ``tls`` attribute is set to "yes", then libvirt will attempt -to use the host TLS environment if either the ``chardev_tls_x509_cert_dir`` or -``default_tls_x509_cert_dir`` TLS directory structure exists. - -:: - - ... - <devices> - <serial type="tcp"> - <source mode='connect' host="127.0.0.1" service="5555" tls="yes"/> - <protocol type="raw"/> - <target port="0"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharUDP"/>` - -UDP network console -''''''''''''''''''' - -The character device acts as a UDP netconsole service, sending and receiving -packets. This is a lossy service. - -:: - - ... - <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> - ... - -:anchor:`<a id="elementsCharUNIX"/>` - -UNIX domain socket client/server -'''''''''''''''''''''''''''''''' - -The character device acts as a UNIX domain socket server, accepting connections -from local clients. - -:: - - ... - <devices> - <serial type="unix"> - <source mode="bind" path="/tmp/foo"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharSpiceport"/>` - -Spice channel -''''''''''''' - -The character device is accessible through spice connection under a channel name -specified in the ``channel`` attribute. :since:`Since 1.2.2` - -Note: depending on the hypervisor, spiceports might (or might not) be enabled on -domains with or without `spice graphics <#elementsGraphics>`__. - -:: - - ... - <devices> - <serial type="spiceport"> - <source channel="org.qemu.console.serial.0"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsNmdm"/>` - -Nmdm device -''''''''''' - -The nmdm device driver, available on FreeBSD, provides two tty devices connected -together by a virtual null modem cable. :since:`Since 1.2.4` - -:: - - ... - <devices> - <serial type="nmdm"> - <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/> - </serial> - </devices> - ... - -The ``source`` element has these attributes: - -``master`` - Master device of the pair, that is passed to the hypervisor. Device is - specified by a fully qualified path. -``slave`` - Slave device of the pair, that is passed to the clients for connection to the - guest console. Device is specified by a fully qualified path. - -:anchor:`<a id="elementsSound"/>` - -Sound devices -~~~~~~~~~~~~~ - -A virtual sound card can be attached to the host via the ``sound`` element. -:since:`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 'es1370', 'sb16', 'ac97', - 'ich6' and 'usb'. ( :since:` 'ac97' only since 0.6.0, 'ich6' only since - 0.8.8, 'usb' only since 1.2.7` ) - -:since:`Since 0.9.13` , a sound element with ``ich6`` model can have optional -sub-elements ``<codec>`` to attach various audio codecs to the audio device. If -not specified, a default codec will be attached to allow playback and recording. - -Valid values are: - -- 'duplex' - advertise a line-in and a line-out -- 'micro' - advertise a speaker and a microphone -- 'output' - advertise a line-out :since:`Since 4.4.0` - -:: - - ... - <devices> - <sound model='ich6'> - <codec type='micro'/> - </sound> - </devices> - ... - -Each ``sound`` element has an optional sub-element ``<address>`` which can tie -the device to a particular PCI slot, `documented above <#elementsAddress>`__. - -:anchor:`<a id="elementsWatchdog"/>` - -Watchdog device -~~~~~~~~~~~~~~~ - -A virtual hardware watchdog device can be added to the guest via the -``watchdog`` element. :since:`Since 0.7.3, QEMU and KVM only` - -The watchdog device requires an additional driver and management daemon in the -guest. Just enabling the watchdog in the libvirt configuration does not do -anything useful on its own. - -Currently libvirt does not support notification when the watchdog fires. This -feature is planned for a future version of libvirt. - -:: - - ... - <devices> - <watchdog model='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: - - - 'i6300esb' - the recommended device, emulating a PCI Intel 6300ESB - - 'ib700' - emulating an ISA iBase IB700 - - 'diag288' - emulating an S390 DIAG288 device :since:`Since 1.2.17` - -``action`` - The optional ``action`` attribute describes what action to take when the - watchdog expires. Valid values are specific to the underlying hypervisor. - - QEMU and KVM support: - - - 'reset' - default, forcefully reset the guest - - 'shutdown' - gracefully shutdown the guest (not recommended) - - 'poweroff' - forcefully power off the guest - - 'pause' - pause the guest - - 'none' - do nothing - - 'dump' - automatically dump the guest :since:`Since 0.8.7` - - 'inject-nmi' - inject a non-maskable interrupt into the guest - :since:`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. - -:anchor:`<a id="elementsMemBalloon"/>` - -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:`Since 0.8.3, Xen, QEMU -and KVM only` Additionally, :since:`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:`Since 5.2.0` - - 'virtio-non-transitional' :since:`Since 5.2.0` - - 'xen' - default with Xen - - See `Virtio transitional devices <#elementsVirtioTransitional>`__ 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:`Since 1.3.1, 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:`Since 1.1.1, requires QEMU 1.5` - -``driver`` - For model ``virtio`` memballoon, `Virtio-specific - options <#elementsVirtio>`__ can also be set. ( :since:`Since 3.5.0` ) - -:anchor:`<a id="elementsRng"/>` - -Random number generator device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The virtual random number generator device allows the host to pass through -entropy to guest operating systems. :since:`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:`Since 5.2.0` - - 'virtio-non-transitional' :since:`Since 5.2.0` - - See `Virtio transitional devices <#elementsVirtioTransitional>`__ 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:`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:`Since 1.3.4` any path is accepted. Before that ``/dev/random`` and - ``/dev/hwrng`` were the only accepted paths. When no file name is - specified, the hypervisor default is used. For QEMU, the default is - ``/dev/random``. However, the recommended source of entropy is - ``/dev/urandom`` (as it doesn't have the limitations of ``/dev/random``). - - ``egd`` - This backend connects to a source using the EGD protocol. The source is - specified as a character device. Refer to `character device host - interface <#elementsCharHostInterface>`__ for more information. - - ``builtin`` - This backend uses qemu builtin random generator, which uses - ``getrandom()`` syscall as the source of entropy. ( :since:`Since 6.1.0 - and QEMU 4.2` ) - -``driver`` - The subelement ``driver`` can be used to tune the device: - - virtio options - `Virtio-specific options <#elementsVirtio>`__ can also be set. ( - :since:`Since 3.5.0` ) - -:anchor:`<a id="elementsTpm"/>` - -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. :since:`'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:`'emulator' -since 4.5.0` The state of the TPM emulator can be encrypted by providing an -``encryption`` element. :since:`'encryption' since 5.6.0` - -Example: usage of the TPM Emulator - -:: - - ... - <devices> - <tpm model='tpm-tis'> - <backend type='emulator' version='2.0'> - <encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/> - </backend> - </tpm> - </devices> - ... - -``model`` - The ``model`` attribute specifies what device model QEMU provides to the - guest. If no model name is provided, ``tpm-tis`` will automatically be chosen - for non-PPC64 architectures. :since:`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:`Since 6.1.0` , pSeries guests on PPC64 are supported and the - default is ``tpm-spapr``. :since:`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:`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. - -``version`` - The ``version`` attribute indicates the version of the TPM. By default a TPM - 1.2 is created. This attribute only works with the ``emulator`` backend. The - following versions are supported: - - - '1.2' : creates a TPM 1.2 - - '2.0' : creates a TPM 2.0 - -``encryption`` - The ``encryption`` element allows the state of a TPM emulator to be - encrypted. The ``secret`` must reference a secret object that holds the - passphrase from which the encryption key will be derived. - -:anchor:`<a id="elementsNVRAM"/>` - -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:`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 - -:anchor:`<a id="elementsPanic"/>` - -panic device -~~~~~~~~~~~~ - -panic device enables libvirt to receive panic notification from a QEMU guest. -:since:`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:`Since 1.3.0, QEMU and - KVM only` - - 's390' - default for S390 guests. :since:`Since 1.3.5` - -``address`` - address of panic. The default ioport is 0x505. Most users don't need to - specify an address, and doing so is forbidden altogether for s390, pseries - and hyperv models. - -:anchor:`<a id="elementsShmem"/>` - -Shared memory device -~~~~~~~~~~~~~~~~~~~~ - -A shared memory device allows to share a memory region between different virtual -machines and the host. :since:`Since 1.2.10, QEMU and KVM only` - -:: - - ... - <devices> - <shmem name='my_shmem0'> - <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 ``/``. -``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. - -:anchor:`<a id="elementsMemory"/>` - -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'>4096</pagesize> - <nodemask>1-3</nodemask> - </source> - <target> - <size unit='KiB'>524287</size> - <node>1</node> - </target> - </memory> - <memory model='nvdimm'> - <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> - <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> - </devices> - ... - -``model`` - Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since - 1.2.14` Provide ``nvdimm`` model adds a Non-Volatile DIMM module. - :since:`Since 3.2.0` - -``access`` - An optional attribute ``access`` ( :since:`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 <#elementsMemoryBacking>`__: ``shared`` and - ``private``. For ``nvdimm`` model, if using real NVDIMM DAX device as - backend, ``shared`` is required. - -``discard`` - An optional attribute ``discard`` ( :since:`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 <#elementsMemoryBacking>`__. 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:`Since 6.2.0` - -``source`` - For model ``dimm`` this element is optional and allows to fine tune the - source of the memory used for the given memory device. If the element is not - provided defaults configured via ``numatune`` are used. If ``dimm`` is - provided, then the following optional elements can be provided as well: - - ``pagesize`` - This element can be used to override the default host page size used for - backing the memory device. The configured value must correspond to a page - size supported by the host. - - ``nodemask`` - This element can be used to override the default set of NUMA nodes where - the memory would be allocated. - - For model ``nvdimm`` this element is mandatory. The mandatory child element - ``path`` represents a path in the host that backs the nvdimm module in the - guest. The following optional elements may be used: - - ``alignsize`` - The ``alignsize`` element defines the page size alignment used to mmap the - address range for the backend ``path``. If not supplied the host page size - is 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:`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:`Since 5.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. - - 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. - - 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 - `here <#elementsMemoryAllocation>`__. ``label`` is mandatory for pSeries - guests and optional for all other architectures. For QEMU domains the - following restrictions apply: - - #. the minimum label size is 128KiB, - #. 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:`Since - 5.0.0` - -:anchor:`<a id="elementsIommu"/>` - -IOMMU devices -~~~~~~~~~~~~~ - -The ``iommu`` element can be used to add an IOMMU device. :since:`Since 2.1.0` - -Example: - -:: - - ... - <devices> - <iommu model='intel'> - <driver intremap='on'/> - </iommu> - </devices> - ... - -``model`` - Supported values are ``intel`` (for Q35 guests) and, :since:`since 5.5.0` , - ``smmuv3`` (for 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:`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:`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 <#elementsFeatures>`__), and - both interrupt remapping and EIM turned on for the IOMMU, will be able to - use more than 255 vCPUs. :since:`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:`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:`Since 6.5.0` (QEMU/KVM - only) - -:anchor:`<a id="vsock"/>` - -Vsock ------ - -A vsock host/guest interface. The ``model`` attribute defaults to ``virtio``. -:since:`Since 5.2.0` ``model`` can also be 'virtio-transitional' and -'virtio-non-transitional', see `Virtio transitional -devices <#elementsVirtioTransitional>`__ 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:`Since 4.4.0` - -:: - - ... - <devices> - <vsock model='virtio'> - <cid auto='no' address='3'/> - </vsock> - </devices> - ... +.. include:: formatdomain-devices.rst :anchor:`<a id="seclabel"/>` diff --git a/docs/meson.build b/docs/meson.build index fc38efc9e2..4c6f7179e5 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -122,7 +122,10 @@ docs_rst_files = [ { 'name': 'developer-tooling' }, { 'name': 'formatbackup' }, { 'name': 'formatcheckpoint' }, - { 'name': 'formatdomain' }, + { 'name': 'formatdomain', + 'includes': [ 'formatdomain-devices.rst', + ] + }, { 'name': 'hacking' }, { 'name': 'libvirt-go' }, { 'name': 'libvirt-go-xml' }, -- 2.26.2