From nobody Mon Feb 9 09:08:36 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) client-ip=207.211.31.81; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510561; cv=none; d=zohomail.com; s=zohoarc; b=Lg6wHrJxswDIezWBLkZWmYAI59M5SpsEkjfuba2j6i79Uwqn+dqfxcAWMx2mDpc9q+QyICjyU1f0KsLNNAcHgHM8tackVSrSMWk/fBEE+RPuOG9ejCW+gBSdDNy9imGw2/LLM94ZRLgCnitUHLoC8v4llzooD52V76Ym6Mwf2dY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510561; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Mx6CylfsBzFBelGG96VZs23RCxvXX1lerUH2KH4oihU=; b=mBDYmbLZhc1LgiIT4J9tAp0omcoX7zLLTS1CtQxVVEFvUxjtYGqtfABBcW5px4Ikaj/cq0hUhvQeQagy+IOgXksBep9EFzBj476bBniSvdn36p8b9Up5tHuioYAA7+MK/nsSIcFVNruyXxE/y2NBSTDtyZfh1Drq+++U220bxA0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [207.211.31.81]) by mx.zohomail.com with SMTPS id 1595510561020987.8975533066772; Thu, 23 Jul 2020 06:22:41 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-479-xx0ydLSoPo-Y9OVskCl7yw-1; Thu, 23 Jul 2020 09:22:08 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E0460100CCCC; Thu, 23 Jul 2020 13:22:02 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B40D06972C; Thu, 23 Jul 2020 13:22:02 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 75AC31809554; Thu, 23 Jul 2020 13:22:02 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDM0TC028439 for ; Thu, 23 Jul 2020 09:22:00 -0400 Received: by smtp.corp.redhat.com (Postfix) id 87ED219D7C; Thu, 23 Jul 2020 13:22:00 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id E7B9A1A921 for ; Thu, 23 Jul 2020 13:21:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510559; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Mx6CylfsBzFBelGG96VZs23RCxvXX1lerUH2KH4oihU=; b=R2H3mD0WpPTxPEMq6+FV5BEWESjn4EWdMsp/tGXk7miomZBgDCIx5c/TXVUty1AYU0JlOk k3EB8tb9oVihkzS10ifTF8VFHk9Z3m6iaaOMjCvu9TtYIyOK1hzCeIVimT8Szk3OvtdqiP g8c4CYwjpyr5mNrhWcVKVaVCP1oH/hI= X-MC-Unique: xx0ydLSoPo-Y9OVskCl7yw-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 06/32] docs: formatdomain: Split out Date: Thu, 23 Jul 2020 15:21:11 +0200 Message-Id: <13a0b07b16f7d9881f3ef096d6ee3885d3f330cc.1595510131.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Start splitting the massive document into smaller pieces using the .. include:: directive. Signed-off-by: Peter Krempa --- 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:`` + +Devices +------- + +The final set of XML elements are all used to describe devices provided to= the +guest domain. All devices occur as children of the main ``devices`` elemen= t. +:since:`Since 0.1.3` + +:: + + ... + + /usr/lib/xen/bin/qemu-dm + + ... + +``emulator`` + The contents of the ``emulator`` element specify the fully qualified pa= th to + the device model emulator binary. The `capabilities XML `__ + specifies the recommended default emulator to use for each particular d= omain + type / architecture combination. + +To help users identifying devices they care about, every device can have d= irect +child ``alias`` element which then has ``name`` attribute where users can = store +identifier for the device. The identifier has to have "ua-" prefix and mus= t be +unique within the domain. Additionally, the identifier must consist only o= f the +following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` + +:: + + + + + + + + + ... + + +:anchor:`` + +Hard drives, floppy disks, CDROMs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Any device that looks like a disk, be it a floppy, harddisk, cdrom, or +paravirtualized driver is specified via the ``disk`` element. + +:: + + ... + + + + + + + + + 10000000 + 400000 + 100000 + + + + ... + + + + ... + + + ... + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + somevalue + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + ... + +``disk`` + The ``disk`` element is the main container for describing disks and sup= ports + the following attributes: + + ``type`` + Valid values are "file", "block", "dir" ( :since:`since 0.7.5` ), + "network" ( :since:`since 0.8.7` ), or "volume" ( :since:`since 1.0.= 5` ), + or "nvme" ( :since:`since 6.0.0` ) and refer to the underlying sourc= e for + the disk. :since:`Since 0.0.3` + ``device`` + Indicates how the disk is to be exposed to the guest OS. Possible va= lues + for this attribute are "floppy", "disk", "cdrom", and "lun", default= ing to + "disk". + + Using "lun" ( :since:`since 0.9.10` ) is only valid when the ``type`= ` is + "block" or "network" for ``protocol=3D'iscsi'`` or when the ``type``= is + "volume" when using an iSCSI source ``pool`` for ``mode`` "host" or = as an + `NPIV `__ virtual Host= Bus + Adapter (vHBA) using a Fibre Channel storage pool. Configured in this + manner, the LUN behaves identically to "disk", except that generic S= CSI + commands from the guest are accepted and passed through to the physi= cal + device. Also note that device=3D'lun' will only be recognized for ac= tual raw + devices, but never for individual partitions or LVM partitions (in t= hose + cases, the kernel will reject the generic SCSI commands, making it + identical to device=3D'disk'). :since:`Since 0.1.4` + + ``model`` + Indicates the emulated device model of the disk. Typically this is + indicated solely by the ``bus`` property but for ``bus`` "virtio" the + model can be specified further with "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. :since:`S= ince + 5.2.0` + ``rawio`` + Indicates whether the disk needs rawio capability. Valid settings are + "yes" or "no" (default is "no"). If any one disk in a domain has + rawio=3D'yes', rawio capability will be enabled for all disks in the= domain + (because, in the case of QEMU, this capability can only be set on a + per-process basis). This attribute is only valid when device is "lun= ". NB, + ``rawio`` intends to confine the capability per-device, however, cur= rent + QEMU implementation gives the domain process broader capability than= that + (per-process basis, affects all the domain disks). To confine the + capability as much as possible for QEMU driver as this stage, ``sgio= `` is + recommended, it's more secure than ``rawio``. :since:`Since 0.9.10` + ``sgio`` + If supported by the hypervisor and OS, indicates whether unprivileged + SG_IO commands are filtered for the disk. Valid settings are "filter= ed" or + "unfiltered" where the default is "filtered". Only available when the + ``device`` is 'lun'. :since:`Since 1.0.2` + ``snapshot`` + Indicates the default behavior of the disk during disk snapshots: + "``internal``" requires a file format such as qcow2 that can store b= oth + the snapshot and the data changes since the snapshot; "``external``"= will + separate the snapshot from the live data; and "``no``" means the dis= k will + not participate in snapshots. Read-only disks default to "``no``", w= hile + the default for other disks depends on the hypervisor's capabilities= . Some + hypervisors allow a per-snapshot choice as well, during `domain snap= shot + creation `__. Not all snapshot modes are suppor= ted; + for example, enabling snapshots with a transient disk generally does= not + make sense. :since:`Since 0.9.5` + +``source`` + Representation of the disk ``source`` depends on the disk ``type`` attr= ibute + value as follows: + + ``file`` + The ``file`` attribute specifies the fully-qualified path to the file + holding the disk. :since:`Since 0.0.3` + ``block`` + The ``dev`` attribute specifies the fully-qualified path to the host + device to serve as the disk. :since:`Since 0.0.3` + ``dir`` + The ``dir`` attribute specifies the fully-qualified path to the dire= ctory + to use as the disk. :since:`Since 0.7.5` + ``network`` + The ``protocol`` attribute specifies the protocol to access to the + requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdo= g", + "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp". + + For any ``protocol`` other than ``nbd`` an additional attribute ``na= me`` + is mandatory to specify which volume/image will be used. + + For "nbd", the ``name`` attribute is optional. TLS transport for NBD= can + be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU + hypervisor, usage of a TLS environment can also be globally controll= ed on + the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in + /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` ) + + For protocols ``http`` and ``https`` an optional attribute ``query`` + specifies the query string. ( :since:`Since 6.2.0` ) + + For "iscsi" ( :since:`since 1.0.4` ), the ``name`` attribute may inc= lude a + logical unit number, separated from the target's name by a slash (e.= g., + ``iqn.2013-07.com.example:iscsi-pool/1``). If not specified, the def= ault + LUN is zero. + + For "vxhs" ( :since:`since 3.8.0` ), the ``name`` is the UUID of the + volume, assigned by the HyperScale server. Additionally, an optional + attribute ``tls`` (QEMU only) can be used to control whether a VxHS = block + device would utilize a hypervisor configured TLS X.509 certificate + environment in order to encrypt the data channel. For the QEMU hyper= visor, + usage of a TLS environment can also be globally controlled on the ho= st by + the ``vxhs_tls`` and ``vxhs_tls_x509_cert_dir`` or + ``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu= .conf. + If ``vxhs_tls`` is enabled, then unless the domain ``tls`` attribute= is + set to "no", libvirt will use the host configured TLS environment. I= f the + ``tls`` attribute is set to "yes", then regardless of the qemu.conf + setting, TLS authentication will be attempted. + + :since:`Since 0.8.7` + + ``volume`` + The underlying disk source is represented by attributes ``pool`` and + ``volume``. Attribute ``pool`` specifies the name of the `storage + pool `__ (managed by libvirt) where the disk sou= rce + resides. Attribute ``volume`` specifies the name of storage volume + (managed by libvirt) used as the disk source. The value for the ``vo= lume`` + attribute will be the output from the "Name" column of a + ``virsh vol-list [pool-name]`` command. + + Use the attribute ``mode`` ( :since:`since 1.1.1` ) to indicate how = to + represent the LUN as the disk source. Valid values are "direct" and + "host". If ``mode`` is not specified, the default is to use "host". = Using + "direct" as the ``mode`` value indicates to use the `storage + pool's `__ ``source`` element ``host`` attribute= as + the disk source to generate the libiscsi URI (e.g. + 'file=3Discsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/= 1'). + Using "host" as the ``mode`` value indicates to use the LUN's path a= s it + shows up on host (e.g. + 'file=3D/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.= example:iscsi-pool-lun-1'). + Using a LUN from an iSCSI source pool provides the same features as a + ``disk`` configured using ``type`` 'block' or 'network' and ``device= `` of + 'lun' with respect to how the LUN is presented to and may be used by= the + guest. :since:`Since 1.0.5` + + ``nvme`` + To specify disk source for NVMe disk the ``source`` element has the + following attributes: + + ``type`` + The type of address specified in ``address`` sub-element. Current= ly, + only ``pci`` value is accepted. + ``managed`` + This attribute instructs libvirt to detach NVMe controller + automatically on domain startup (``yes``) or expect the controlle= r to + be detached by system administrator (``no``). + ``namespace`` + The namespace ID which should be assigned to the domain. Accordin= g to + NVMe standard, namespace numbers start from 1, including. + + The difference between ```` and ```` i= s that + the latter is plain host device assignment with all its limitations = (e.g. + no live migration), while the former makes hypervisor to run the NVM= e disk + through hypervisor's block layer thus enabling all features provided= by + the layer (e.g. snapshots, domain migration, etc.). Moreover, since = the + NVMe disk is unbinded from its PCI driver, the host kernel storage s= tack + is not involved (compared to passing say ``/dev/nvme0n1`` via + ```` and therefore lower latencies can be achie= ved. + + With "file", "block", and "volume", one or more optional sub-elements + ``seclabel``, `described below <#seclabel>`__ (and :since:`since 0.9.9`= ), + can be used to override the domain security labeling policy for just th= at + source file. (NB, for "volume" type disk, ``seclabel`` is only valid wh= en the + specified storage volume is of 'file' or 'block' type). + + The ``source`` element may also have the ``index`` attribute with same + semantics the `index <#elementsDiskBackingStoreIndex>`__ attribute of + ``backingStore`` + + The ``source`` element may contain the following sub elements: + + ``host`` + When the disk ``type`` is "network", the ``source`` may have zero or= more + ``host`` sub-elements used to specify the hosts to connect. The ``ho= st`` + element supports 4 attributes, viz. "name", "port", "transport" and + "socket", which specify the hostname, the port number, transport typ= e and + path to socket, respectively. The meaning of this element and the nu= mber + of the elements depend on the protocol attribute. + + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + Protocol Meaning Num= ber of hosts Default port + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + nbd a server running nbd-server onl= y one 10809 + iscsi an iSCSI server onl= y one 3260 + rbd monitor servers of RBD one= or more librados default + sheepdog one of the sheepdog servers (default is localhost:7000) zer= o or one 7000 + gluster a server running glusterd daemon one= or more ( :since:`Since 2.1.0` ), just one prior to that 24007 + vxhs a server running Veritas HyperScale daemon onl= y one 9999 + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + gluster supports "tcp", "rdma", "unix" as valid values for the trans= port + attribute. nbd supports "tcp" and "unix". Others only support "tcp".= If + nothing is specified, "tcp" is assumed. If the transport is "unix", = the + socket attribute specifies the path to an AF_UNIX socket. + + ``snapshot`` + The ``name`` attribute of ``snapshot`` element can optionally specif= y an + internal snapshot name to be used as the source for storage protocol= s. + Supported for 'rbd' :since:`since 1.2.11 (QEMU only).` + ``config`` + The ``file`` attribute for the ``config`` element provides a fully + qualified path to a configuration file to be provided as a parameter= to + the client of a networked storage protocol. Supported for 'rbd' + :since:`since 1.2.11 (QEMU only).` + ``auth`` + :since:`Since libvirt 3.9.0` , the ``auth`` element is supported for= a + disk ``type`` "network" that is using a ``source`` element with the + ``protocol`` attributes "rbd" or "iscsi". If present, the ``auth`` e= lement + provides the authentication credentials needed to access the source.= It + includes a mandatory attribute ``username``, which identifies the us= ername + to use during authentication, as well as a sub-element ``secret`` wi= th + mandatory attribute ``type``, to tie back to a `libvirt secret + object `__ that holds the actual password or other + credentials (the domain XML intentionally does not expose the passwo= rd, + only the reference to the object that does manage the password). Kno= wn + secret types are "ceph" for Ceph RBD network sources and "iscsi" for= CHAP + authentication of iSCSI targets. Both will require either a ``uuid`` + attribute with the UUID of the secret object or a ``usage`` attribute + matching the key that was specified in the secret object. + ``encryption`` + :since:`Since libvirt 3.9.0` , the ``encryption`` can be a sub-eleme= nt of + the ``source`` element for encrypted storage sources. If present, + specifies how the storage source is encrypted See the `Storage + Encryption `__ page for more informati= on. + Note that the 'qcow' format of encryption is broken and thus is no l= onger + supported for use with disk images. ( :since:`Since libvirt 4.5.0` ) + ``reservations`` + :since:`Since libvirt 4.4.0` , the ``reservations`` can be a sub-ele= ment + of the ``source`` element for storage sources (QEMU driver only). If + present it enables persistent reservations for SCSI based disks. The + element has one mandatory attribute ``managed`` with accepted values + ``yes`` and ``no``. If ``managed`` is enabled libvirt prepares and m= anages + any resources needed. When the persistent reservations are unmanaged= , then + the hypervisor acts as a client and the path to the server socket mu= st be + provided in the child element ``source``, which currently accepts on= ly the + following attributes: ``type`` with one value ``unix``, ``path`` pat= h to + the socket, and finally ``mode`` which accepts one value ``client`` + specifying the role of hypervisor. It's recommended to allow libvirt + manage the persistent reservations. + ``initiator`` + :since:`Since libvirt 4.7.0` , the ``initiator`` element is supporte= d for + a disk ``type`` "network" that is using a ``source`` element with the + ``protocol`` attribute "iscsi". If present, the ``initiator`` element + provides the initiator IQN needed to access the source via mandatory + attribute ``name``. + ``address`` + For disk of type ``nvme`` this element specifies the PCI address of = the + host NVMe controller. :since:`Since 6.0.0` + ``slices`` + The ``slices`` element using its ``slice`` sub-elements allows confi= guring + offset and size of either the location of the image format + (``slice type=3D'storage'``) inside the storage source or the guest = data + inside the image format container (future expansion). The ``offset``= and + ``size`` values are in bytes. :since:`Since 6.1.0` + ``ssl`` + For ``https`` and ``ftps`` accessed storage it's possible to tweak t= he SSL + transport parameters with this element. The ``verify`` attribute all= ows to + turn on or off SSL certificate validation. Supported values are ``ye= s`` + and ``no``. :since:`Since 6.2.0` + ``cookies`` + For ``http`` and ``https`` accessed storage it's possible to pass on= e or + more cookies. The cookie name and value must conform to the HTTP + specification. :since:`Since 6.2.0` + ``readahead`` + Specifies the size of the readahead buffer for protocols which suppo= rt it. + (all 'curl' based drivers in qemu). The size is in bytes. Note that = '0' is + considered as if the value is not provided. :since:`Since 6.2.0` + ``timeout`` + Specifies the connection timeout for protocols which support it. Not= e that + '0' is considered as if the value is not provided. :since:`Since 6.2= .0` + + For a "file" or "volume" disk type which represents a cdrom or floppy (= the + ``device`` attribute), it is possible to define policy what to do with = the + disk if the source file is not accessible. (NB, ``startupPolicy`` is not + valid for "volume" disk unless the specified storage volume is of "file" + type). This is done by the ``startupPolicy`` attribute ( :since:`since = 0.9.7` + ), accepting these values: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + mandatory fail if missing for any reason (the default) + requisite fail if missing on boot up, drop if missing on migrate/restor= e/revert + optional drop if missing at any start attempt + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + + :since:`Since 1.1.2` the ``startupPolicy`` is extended to support hard = disks + besides cdrom and floppy. On guest cold bootup, if a certain disk is not + accessible or its disk chain is broken, with startupPolicy 'optional' t= he + guest will drop this disk. This feature doesn't support migration curre= ntly. + +``backingStore`` + This element describes the backing store used by the disk specified by + sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor dri= ver + does not support the + `backingStoreInput `__ ( + :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored = on + input and only used for output to describe the detected backing chains = of + running domains. If ``backingStoreInput`` is supported the ``backingSto= re`` + is used as the backing image of ``source`` or other ``backingStore`` + overriding any backing image information recorded in the image metadata= . An + empty ``backingStore`` element means the sibling source is self-contain= ed and + is not based on any backing store. For the detected backing chain infor= mation + to be accurate, the backing format must be correctly specified in the + metadata of each file of the chain (files created by libvirt satisfy th= is + property, but using existing external files for snapshot or block copy + operations requires the end user to pre-create the file correctly). The + following attributes are supported in ``backingStore``: + + ``type`` + The ``type`` attribute represents the type of disk used by the backi= ng + store, see disk type attribute above for more details and possible v= alues. + ``index`` + This attribute is only valid in output (and ignored on input) and it= can + be used to refer to a specific part of the disk chain when doing blo= ck + operations (such as via the ``virDomainBlockRebase`` API). For examp= le, + ``vda[2]`` refers to the backing store with ``index=3D'2'`` of the d= isk with + ``vda`` target. + + Moreover, ``backingStore`` supports the following sub-elements: + + ``format`` + The ``format`` element contains ``type`` attribute which specifies t= he + internal format of the backing store, such as ``raw`` or ``qcow2``. + ``source`` + This element has the same structure as the ``source`` element in ``d= isk``. + It specifies which file, device, or network location contains the da= ta of + the described backing store. + ``backingStore`` + If the backing store is not self-contained, the next element in the = chain + is described by nested ``backingStore`` element. + +``mirror`` + This element is present if the hypervisor has started a long-running bl= ock + job operation, where the mirror location in the ``source`` sub-element = will + eventually have the same contents as the source, and with the file form= at in + the sub-element ``format`` (which might differ from the format of the + source). The details of the ``source`` sub-element are determined by the + ``type`` attribute of the mirror, similar to what is done for the overa= ll + ``disk`` device element. The ``job`` attribute mentions which API start= ed the + operation ("copy" for the ``virDomainBlockRebase`` API, or "active-comm= it" + for the ``virDomainBlockCommit`` API), :since:`since 1.2.7` . The attri= bute + ``ready``, if present, tracks progress of the job: ``yes`` if the disk = is + known to be ready to pivot, or, :since:`since 1.2.7` , ``abort`` or ``p= ivot`` + if the job is in the process of completing. If ``ready`` is not present= , the + disk is probably still copying. For now, this element only valid in out= put; + it is ignored on input. The ``source`` sub-element exists for all two-p= hase + jobs :since:`since 1.2.6` . Older libvirt supported only block copy to a + file, :since:`since 0.9.12` ; for compatibility with older clients, suc= h jobs + include redundant information in the attributes ``file`` and ``format``= in + the ``mirror`` element. +``target`` + The ``target`` element controls the bus / device under which the disk is + exposed to the guest OS. The ``dev`` attribute indicates the "logical" = device + name. The actual device name specified is not guaranteed to map to the = device + name in the guest OS. Treat it as a device ordering hint. The optional + ``bus`` attribute specifies the type of disk device to emulate; possible + values are driver specific, with typical values being "ide", "scsi", + "virtio", "xen", "usb", "sata", or "sd" :since:`"sd" since 1.1.2` . If + omitted, the bus type is inferred from the style of the device name (e.= g. a + device named 'sda' will typically be exported using a SCSI bus). The op= tional + attribute ``tray`` indicates the tray status of the removable disks (i.= e. + CDROM or Floppy disk), the value can be either "open" or "closed", defa= ults + to "closed". NB, the value of ``tray`` could be updated while the domai= n is + running. The optional attribute ``removable`` sets the removable flag f= or USB + disks, and its value can be either "on" or "off", defaulting to "off". + :since:`Since 0.0.3; ``bus`` attribute since 0.4.3; ``tray`` attribute = since + 0.9.11; "usb" attribute value since after 0.4.4; "sata" attribute value= since + 0.9.7; "removable" attribute value since 1.1.3` +``iotune`` + The optional ``iotune`` element provides the ability to provide additio= nal + per-device I/O tuning, with values that can vary for each device (contr= ast + this to the ` <#elementsBlockTuning>`__ element, which appli= es + globally to the domain). Currently, the only tuning available is Block = I/O + throttling for qemu. This element has optional sub-elements; any sub-el= ement + not specified or given with a value of 0 implies no limit. :since:`Since + 0.9.8` + + ``total_bytes_sec`` + The optional ``total_bytes_sec`` element is the total throughput lim= it in + bytes per second. This cannot appear with ``read_bytes_sec`` or + ``write_bytes_sec``. + ``read_bytes_sec`` + The optional ``read_bytes_sec`` element is the read throughput limit= in + bytes per second. + ``write_bytes_sec`` + The optional ``write_bytes_sec`` element is the write throughput lim= it in + bytes per second. + ``total_iops_sec`` + The optional ``total_iops_sec`` element is the total I/O operations = per + second. This cannot appear with ``read_iops_sec`` or ``write_iops_se= c``. + ``read_iops_sec`` + The optional ``read_iops_sec`` element is the read I/O operations per + second. + ``write_iops_sec`` + The optional ``write_iops_sec`` element is the write I/O operations = per + second. + ``total_bytes_sec_max`` + The optional ``total_bytes_sec_max`` element is the maximum total + throughput limit in bytes per second. This cannot appear with + ``read_bytes_sec_max`` or ``write_bytes_sec_max``. + ``read_bytes_sec_max`` + The optional ``read_bytes_sec_max`` element is the maximum read thro= ughput + limit in bytes per second. + ``write_bytes_sec_max`` + The optional ``write_bytes_sec_max`` element is the maximum write + throughput limit in bytes per second. + ``total_iops_sec_max`` + The optional ``total_iops_sec_max`` element is the maximum total I/O + operations per second. This cannot appear with ``read_iops_sec_max``= or + ``write_iops_sec_max``. + ``read_iops_sec_max`` + The optional ``read_iops_sec_max`` element is the maximum read I/O + operations per second. + ``write_iops_sec_max`` + The optional ``write_iops_sec_max`` element is the maximum write I/O + operations per second. + ``size_iops_sec`` + The optional ``size_iops_sec`` element is the size of I/O operations= per + second. + + :since:`Throughput limits since 1.2.11 and QEMU 1.7` + + ``group_name`` + The optional ``group_name`` provides the cability to share I/O throt= tling + quota between multiple drives. This prevents end-users from circumve= nting + a hosting provider's throttling policy by splitting 1 large drive in= N + small drives and getting N times the normal throttling quota. Any na= me may + be used. + + :since:`group_name since 3.0.0 and QEMU 2.4` + + ``total_bytes_sec_max_length`` + The optional ``total_bytes_sec_max_length`` element is the maximum + duration in seconds for the ``total_bytes_sec_max`` burst period. On= ly + valid when the ``total_bytes_sec_max`` is set. + ``read_bytes_sec_max_length`` + The optional ``read_bytes_sec_max_length`` element is the maximum du= ration + in seconds for the ``read_bytes_sec_max`` burst period. Only valid w= hen + the ``read_bytes_sec_max`` is set. + ``write_bytes_sec_max`` + The optional ``write_bytes_sec_max_length`` element is the maximum + duration in seconds for the ``write_bytes_sec_max`` burst period. On= ly + valid when the ``write_bytes_sec_max`` is set. + ``total_iops_sec_max_length`` + The optional ``total_iops_sec_max_length`` element is the maximum du= ration + in seconds for the ``total_iops_sec_max`` burst period. Only valid w= hen + the ``total_iops_sec_max`` is set. + ``read_iops_sec_max_length`` + The optional ``read_iops_sec_max_length`` element is the maximum dur= ation + in seconds for the ``read_iops_sec_max`` burst period. Only valid wh= en the + ``read_iops_sec_max`` is set. + ``write_iops_sec_max`` + The optional ``write_iops_sec_max_length`` element is the maximum du= ration + in seconds for the ``write_iops_sec_max`` burst period. Only valid w= hen + the ``write_iops_sec_max`` is set. + + :since:`Throughput length since 2.4.0 and QEMU 2.6` + +``driver`` + The optional driver element allows specifying further details related t= o the + hypervisor driver used to provide the disk. :since:`Since 0.1.8` + + - If the hypervisor supports multiple backend drivers, then the ``name= `` + attribute selects the primary backend driver name, while the optional + ``type`` attribute provides the sub-type. For example, xen supports = a name + of "tap", "tap2", "phy", or "file", with a type of "aio", while qemu= only + supports a name of "qemu", but multiple types including "raw", "boch= s", + "qcow2", and "qed". + - The optional ``cache`` attribute controls the cache mechanism, possi= ble + values are "default", "none", "writethrough", "writeback", "directsy= nc" + (like "writethrough", but it bypasses the host page cache) and "unsa= fe" + (host may cache all disk io, and sync requests from guest are ignore= d). + :since:` Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7= ` + - The optional ``error_policy`` attribute controls how the hypervisor = will + behave on a disk read or write error, possible values are "stop", + "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" si= nce + 0.9.7` The default is left to the discretion of the hypervisor. Ther= e is + also an optional ``rerror_policy`` that controls behavior for read e= rrors + only. :since:`Since 0.9.7` . If no rerror_policy is given, error_pol= icy is + used for both read and write errors. If rerror_policy is given, it + overrides the ``error_policy`` for read errors. Also note that "enos= pace" + is not a valid policy for read errors, so if ``error_policy`` is set= to + "enospace" and no ``rerror_policy`` is given, the read error policy = will + be left at its default. + - The optional ``io`` attribute controls specific policies on I/O; qemu + guests support "threads" and "native" :since:`Since 0.8.8` , io_uring + :since:`Since 6.3.0 (QEMU 5.0)` . + - The optional ``ioeventfd`` attribute allows users to set `domain I/O + asynchronous handling `__= for + disk device. The default is left to the discretion of the hypervisor. + Accepted values are "on" and "off". Enabling this allows qemu to exe= cute + VM while a separate thread handles I/O. Typically guests experiencin= g high + system CPU utilization during I/O will benefit from this. On the oth= er + hand, on overloaded host it could increase guest I/O latency. + :since:`Since 0.9.3 (QEMU and KVM only)` **In general you should lea= ve + this option alone, unless you are very certain you know what you are + doing.** + - The optional ``event_idx`` attribute controls some aspects of device= event + processing. The value can be either 'on' or 'off' - if it is on, it = will + reduce the number of interrupts and exits for the guest. The default= is + determined by QEMU; usually if the feature is supported, default is = on. In + case there is a situation where this behavior is suboptimal, this + attribute provides a way to force the feature off. :since:`Since 0.9= .5 + (QEMU and KVM only)` **In general you should leave this option alone, + unless you are very certain you know what you are doing.** + - The optional ``copy_on_read`` attribute controls whether to copy read + backing file into the image file. The value can be either "on" or "o= ff". + Copy-on-read avoids accessing the same backing file sectors repeated= ly and + is useful when the backing file is over a slow network. By default + copy-on-read is off. :since:`Since 0.9.10 (QEMU and KVM only)` + - The optional ``discard`` attribute controls whether discard requests= (also + known as "trim" or "unmap") are ignored or passed to the filesystem.= The + value can be either "unmap" (allow the discard request to be passed)= or + "ignore" (ignore the discard request). :since:`Since 1.0.6 (QEMU and= KVM + only)` + - The optional ``detect_zeroes`` attribute controls whether to detect = zero + write requests. The value can be "off", "on" or "unmap". First two v= alues + turn the detection off and on, respectively. The third value ("unmap= ") + turns the detection on and additionally tries to discard such areas = from + the image based on the value of ``discard`` above (it will act as "o= n" if + ``discard`` is set to "ignore"). NB enabling the detection is a comp= ute + intensive operation, but can save file space and/or time on slow med= ia. + :since:`Since 2.0.0` + - The optional ``iothread`` attribute assigns the disk to an IOThread = as + defined by the range for the domain + `iothreads <#elementsIOThreadsAllocation>`__ value. Multiple disks m= ay be + assigned to the same IOThread and are numbered from 1 to the domain + iothreads value. Available for a disk device ``target`` configured t= o use + "virtio" ``bus`` and "pci" or "ccw" ``address`` types. :since:`Since= 1.2.8 + (QEMU 2.1)` + - The optional ``queues`` attribute specifies the number of virt queue= s for + virtio-blk. ( :since:`Since 3.9.0` ) + - For virtio disks, `Virtio-specific options <#elementsVirtio>`__ can = also + be set. ( :since:`Since 3.5.0` ) + +``backenddomain`` + The optional ``backenddomain`` element allows specifying a backend doma= in + (aka driver domain) hosting the disk. Use the ``name`` attribute to spe= cify + the backend domain name. :since:`Since 1.2.13 (Xen only)` +``boot`` + Specifies that the disk is bootable. The ``order`` attribute determines= the + order in which devices will be tried during boot sequence. On the S390 + architecture only the first boot device is used. The optional ``loadpar= m`` + attribute is an 8 character string which can be queried by guests on S3= 90 via + sclp or diag 308. Linux guests on S390 can use ``loadparm`` to select a= boot + entry. :since:`Since 3.5.0` The per-device ``boot`` elements cannot be = used + together with general boot elements in `BIOS bootloader <#elementsOSBIO= S>`__ + section. :since:`Since 0.8.8` +``encryption`` + Starting with :since:`libvirt 3.9.0` the ``encryption`` element is pref= erred + to be a sub-element of the ``source`` element. If present, specifies ho= w the + volume is encrypted using "qcow". See the `Storage + Encryption `__ page for more information. +``readonly`` + If present, this indicates the device cannot be modified by the guest. = For + now, this is the default for disks with attribute ``device=3D'cdrom'``. +``shareable`` + If present, this indicates the device is expected to be shared between + domains (assuming the hypervisor and OS support this), which means that + caching should be deactivated for that device. +``transient`` + If present, this indicates that changes to the device contents should be + reverted automatically when the guest exits. With some hypervisors, mar= king a + disk transient prevents the domain from participating in migration or + snapshots. :since:`Since 0.9.5` +``serial`` + If present, this specify serial number of virtual hard drive. For examp= le, it + may look like ``WD-WMAP9A966149``. Not supported for + scsi-block devices, that is those using disk ``type`` 'block' using + ``device`` 'lun' on ``bus`` 'scsi'. :since:`Since 0.7.1` +``wwn`` + If present, this element specifies the WWN (World Wide Name) of a virtu= al + hard disk or CD-ROM drive. It must be composed of 16 hexadecimal digits. + :since:`Since 0.10.1` +``vendor`` + If present, this element specifies the vendor of a virtual hard disk or + CD-ROM device. It must not be longer than 8 printable characters. + :since:`Since 1.0.1` +``product`` + If present, this element specifies the product of a virtual hard disk or + CD-ROM device. It must not be longer than 16 printable characters. + :since:`Since 1.0.1` +``address`` + If present, the ``address`` element ties the disk to a given slot of a + controller (the actual ```` device can often be inferred by + libvirt, although it can be `explicitly specified <#elementsControllers= >`__). + The ``type`` attribute is mandatory, and is typically "pci" or "drive".= For a + "pci" controller, additional attributes for ``bus``, ``slot``, and + ``function`` must be present, as well as optional ``domain`` and + ``multifunction``. Multifunction defaults to 'off'; any other value req= uires + QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, addit= ional + attributes ``controller``, ``bus``, ``target`` ( :since:`libvirt 0.9.11= ` ), + and ``unit`` are available, each defaulting to 0. +``auth`` + Starting with :since:`libvirt 3.9.0` the ``auth`` element is preferred = to be + a sub-element of the ``source`` element. The element is still read and + managed as a ``disk`` sub-element. It is invalid to use ``auth`` as bot= h a + sub-element of ``disk`` and ``source``. The ``auth`` element was introd= uced + as a ``disk`` sub-element in :since:`libvirt 0.9.7.` +``geometry`` + The optional ``geometry`` element provides the ability to override geom= etry + settings. This mostly useful for S390 DASD-disks or older DOS-disks. + :since:`0.10.0` + + ``cyls`` + The ``cyls`` attribute is the number of cylinders. + ``heads`` + The ``heads`` attribute is the number of heads. + ``secs`` + The ``secs`` attribute is the number of sectors per track. + ``trans`` + The optional ``trans`` attribute is the BIOS-Translation-Modus (none= , lba + or auto) + +``blockio`` + If present, the ``blockio`` element allows to override any of the block + device properties listed below. :since:`Since 0.10.2 (QEMU and KVM)` + + ``logical_block_size`` + The logical block size the disk will report to the guest OS. For Lin= ux + this would be the value returned by the BLKSSZGET ioctl and describe= s the + smallest units for disk I/O. + ``physical_block_size`` + The physical block size the disk will report to the guest OS. For Li= nux + this would be the value returned by the BLKPBSZGET ioctl and describ= es the + disk's hardware sector size which can be relevant for the alignment = of + disk data. + +:anchor:`` + +Filesystems +~~~~~~~~~~~ + +A directory on the host that can be accessed directly from the guest. +:since:`since 0.3.3, since 0.8.5 for QEMU/KVM` + +:: + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + ... + +``filesystem`` + The filesystem attribute ``type`` specifies the type of the ``source``.= The + possible values are: + + ``mount`` + A host directory to mount in the guest. Used by LXC, OpenVZ :since:`= (since + 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``= type`` + if one is not specified. This mode also has an optional sub-element + ``driver``, with an attribute ``type=3D'path'`` or ``type=3D'handle'= `` + :since:`(since 0.9.7)` . The driver block has an optional attribute + ``wrpolicy`` that further controls interaction with the host page ca= che; + omitting the attribute gives default behavior, while the value + ``immediate`` means that a host writeback is immediately triggered f= or all + pages touched during a guest file write operation :since:`(since 0.9= .10)` + . :since:`Since 6.2.0` , ``type=3D'virtiofs'`` is also supported. Us= ing + virtiofs requires setting up shared memory, see the guide: + `Virtio-FS `__ + ``template`` + OpenVZ filesystem template. Only used by OpenVZ driver. + ``file`` + A host file will be treated as an image and mounted in the guest. The + filesystem format will be autodetected. Only used by LXC driver. + ``block`` + A host block device to mount in the guest. The filesystem format wil= l be + autodetected. Only used by LXC driver :since:`(since 0.9.5)` . + ``ram`` + An in-memory filesystem, using memory from the host OS. The source e= lement + has a single attribute ``usage`` which gives the memory usage limit = in + KiB, unless units are specified by the ``units`` attribute. Only use= d by + LXC driver. :since:` (since 0.9.13)` + ``bind`` + A directory inside the guest will be bound to another directory insi= de the + guest. Only used by LXC driver :since:` (since 0.9.13)` + + The filesystem element has an optional attribute ``accessmode`` which + specifies the security mode for accessing the source :since:`(since 0.8= .5)` . + Currently this only works with ``type=3D'mount'`` for the QEMU/KVM driv= er. For + driver type ``virtiofs``, only ``passthrough`` is supported. For other = driver + types, the possible values are: + + ``passthrough`` + The ``source`` is accessed with the permissions of the user inside t= he + guest. This is the default ``accessmode`` if one is not specified. `= More + info `__ + ``mapped`` + The ``source`` is accessed with the permissions of the hypervisor (Q= EMU + process). `More + info `__ + ``squash`` + Similar to 'passthrough', the exception is that failure of privileged + operations like 'chown' are ignored. This makes a passthrough-like m= ode + usable for people who run the hypervisor as non-root. `More + info `__ + + :since:`Since 5.2.0` , the filesystem element has an optional attribute + ``model`` with supported values "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. + + The filesystem element has an optional attribute ``multidevs`` which + specifies how to deal with a filesystem export containing more than one + device, in order to avoid file ID collisions on guest when using 9pfs ( + :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not availa= ble + for virtiofs. The possible values are: + + ``default`` + Use QEMU's default setting (which currently is ``warn``). + ``remap`` + This setting allows guest to access multiple devices per export with= out + encountering misbehaviours. Inode numbers from host are automatically + remapped on guest to actively prevent file ID collisions if guest ac= cesses + one export containing multiple devices. + ``forbid`` + Only allow to access one device per export by guest. Attempts to acc= ess + additional devices on the same export will cause the individual file= system + access by guest to fail with an error and being logged (once) as err= or on + host side. + ``warn`` + This setting resembles the behaviour of 9pfs prior to QEMU 4.2, that= is no + action is performed to prevent any potential file ID collisions if an + export contains multiple devices, with the only exception: a warning= is + logged (once) on host side now. This setting may lead to misbehaviou= rs on + guest side if more than one device is exported per export, due to the + potential file ID collisions this may cause on guest side in that ca= se. + +``driver`` + The optional driver element allows specifying further details related t= o the + hypervisor driver used to provide the filesystem. :since:`Since 1.0.6` + + - If the hypervisor supports multiple backend drivers, then the ``type= `` + attribute selects the primary backend driver name, while the ``forma= t`` + attribute provides the format type. For example, LXC supports a type= of + "loop", with a format of "raw" or "nbd" with any format. QEMU suppor= ts a + type of "path" or "handle", but no formats. Virtuozzo driver support= s a + type of "ploop" with a format of "ploop". + - For virtio-backed devices, `Virtio-specific options <#elementsVirtio= >`__ + can also be set. ( :since:`Since 3.5.0` ) + - For ``virtiofs``, the ``queue`` attribute can be used to specify the= queue + size (i.e. how many requests can the queue fit). ( :since:`Since 6.2= .0` ) + +``binary`` + The optional ``binary`` element can tune the options for virtiofsd. All= of + the following attributes and elements are optional. The attribute ``pat= h`` + can be used to override the path to the daemon. Attribute ``xattr`` ena= bles + the use of filesystem extended attributes. Caching can be tuned via the + ``cache`` element, possible ``mode`` values being ``none`` and ``always= ``. + Locking can be controlled via the ``lock`` element - attributes ``posix= `` and + ``flock`` both accepting values ``on`` or ``off``. ( :since:`Since 6.2.= 0` ) +``source`` + The resource on the host that is being accessed in the guest. The ``nam= e`` + attribute must be used with ``type=3D'template'``, and the ``dir`` attr= ibute + must be used with ``type=3D'mount'``. The ``usage`` attribute is used w= ith + ``type=3D'ram'`` to set the memory limit in KiB, unless units are speci= fied by + the ``units`` attribute. +``target`` + Where the ``source`` can be accessed in the guest. For most drivers thi= s is + an automatic mount point, but for QEMU/KVM this is merely an arbitrary = string + tag that is exported to the guest as a hint for where to mount. +``readonly`` + Enables exporting filesystem as a readonly mount for guest, by default + read-write access is given (currently only works for QEMU/KVM driver). +``space_hard_limit`` + Maximum space available to this guest's filesystem. :since:`Since 0.9.1= 3` +``space_soft_limit`` + Maximum space available to this guest's filesystem. The container is + permitted to exceed its soft limits for a grace period of time. Afterwa= rds + the hard limit is enforced. :since:`Since 0.9.13` + +:anchor:`` + +Device Addresses +~~~~~~~~~~~~~~~~ + +Many devices have an optional ``
`` sub-element to describe where = the +device is placed on the virtual bus presented to the guest. If an address = (or +any optional attribute within an address) is omitted on input, libvirt will +generate an appropriate address; but an explicit address is required if mo= re +control over layout is required. See below for device examples including an +address element. + +Every address has a mandatory attribute ``type`` that describes which bus = the +device is on. The choice of which address to use for a given device is +constrained in part by the device and the architecture of the guest. For +example, a ```` device uses ``type=3D'drive'``, while a ```= ` device +would use ``type=3D'pci'`` on i686 or x86_64 guests, or ``type=3D'spapr-vi= o'`` on +PowerPC64 pseries guests. Each address type has further optional attribute= s that +control where on the bus the device will be placed: + +``pci`` + PCI addresses have the following additional attributes: ``domain`` (a 2= -byte + hex integer, not currently used by qemu), ``bus`` (a hex value between = 0 and + 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive= ), and + ``function`` (a value between 0 and 7, inclusive). Also available is the + ``multifunction`` attribute, which controls turning on the multifunctio= n bit + for a particular slot/function in the PCI control register ( :since:`si= nce + 0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but = should + be set to 'on' for function 0 of a slot that will have multiple functio= ns + used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the + architecture are supported. For example, PCI addresses for S390 guests = will + have a ``zpci`` child element, with two attributes: ``uid`` (a hex value + between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between + 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for + User-defined Identifiers and Function Identifiers. + :since:`Since 1.3.5` , some hypervisor drivers may accept an + ``
`` element with no other attributes as an expl= icit + request to assign a PCI address for the device rather than some other t= ype of + address that may also be appropriate for that same device (e.g. virtio-= mmio). + The relationship between the PCI addresses configured in the domain XML= and + those seen by the guest OS can sometime seem confusing: a separate docu= ment + describes `how PCI addresses work `__ in more detai= l. +``drive`` + Drive addresses have the following additional attributes: ``controller`= ` (a + 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` = (a + 2-digit target number), and ``unit`` (a 2-digit unit number on the bus). +``virtio-serial`` + Each virtio-serial address has the following additional attributes: + ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus nu= mber), + and ``slot`` (a 2-digit slot within the bus). +``ccid`` + A CCID address, for smart-cards, has the following additional attribute= s: + ``bus`` (a 2-digit bus number), and ``slot`` attribute (a 2-digit slot = within + the bus). :since:`Since 0.8.8.` +``usb`` + USB addresses have the following additional attributes: ``bus`` (a hex = value + between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up = to + four octets, such as 1.2 or 2.1.3.1). +``spapr-vio`` + On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus= . It + has a flat 32-bit address space; by convention, devices are generally + assigned at a non-zero multiple of 0x00001000, but other addresses are = valid + and permitted by libvirt. Each address has the following additional + attribute: ``reg`` (the hex value address of the starting register). + :since:`Since 0.9.9.` +``ccw`` + S390 guests with a ``machine`` value of s390-ccw-virtio use the native = CCW + bus for I/O devices. CCW bus addresses have the following additional + attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ss= id`` + (a value between 0 and 3, inclusive) and ``devno`` (a hex value between= 0 and + 0xffff, inclusive). Partially specified bus addresses are not allowed. = If + omitted, libvirt will assign a free bus address with cssid=3D0xfe and s= sid=3D0. + Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0= .4` +``virtio-mmio`` + This places the device on the virtio-mmio transport, which is currently= only + available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-= mmio + addresses do not have any additional attributes. :since:`Since 1.1.3` + If the guest architecture is ``aarch64`` and the machine type is ``virt= ``, + libvirt will automatically assign PCI addresses to devices; however, the + presence of a single device with virtio-mmio address in the guest + configuration will cause libvirt to assign virtio-mmio addresses to all + further devices. :since:`Since 3.0.0` +``isa`` + ISA addresses have the following additional attributes: ``iobase`` and + ``irq``. :since:`Since 1.2.1` +``unassigned`` + For PCI hostdevs, ``
`` allows the admin to + include a PCI hostdev in the domain XML definition, without making it + available for the guest. This allows for configurations in which Libvirt + manages the device as a regular PCI hostdev, regardless of whether the = guest + will have access to it. ``
`` is an invalid + address type for all other device types. :since:`Since 6.0.0` + +:anchor:`` + +Virtio-related options +~~~~~~~~~~~~~~~~~~~~~~ + +QEMU's virtio devices have some attributes related to the virtio transport= under +the ``driver`` element: The ``iommu`` attribute enables the use of emulated +IOMMU by the device. The attribute ``ats`` controls the Address Translation +Service support for PCIe devices. This is needed to make use of IOTLB supp= ort +(see `IOMMU device <#elementsIommu>`__). Possible values are ``on`` or ``o= ff``. +:since:`Since 3.5.0` + +The attribute ``packed`` controls if QEMU should try to use packed virtque= ues. +Compared to regular split queues, packed queues consist of only a single +descriptor ring replacing available and used ring, index and descriptor bu= ffer. +This can result in better cache utilization and performance. If packed +virtqueues are actually used depends on the feature negotiation between QE= MU, +vhost backends and guest drivers. Possible values are ``on`` or ``off``. +:since:`Since 6.3.0 (QEMU and KVM only)` + +:anchor:`` + +Virtio transitional devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 5.2.0` , some of QEMU's virtio devices, when used with PCI/P= CIe +machine types, accept the following ``model`` values: + +``virtio-transitional`` + This device can work both with virtio 0.9 and virtio 1.0 guest drivers,= so + it's the best choice when compatibility with older guest operating syst= ems is + desired. libvirt will plug the device into a conventional PCI slot. +``virtio-non-transitional`` + This device can only work with virtio 1.0 guest drivers, and it's the + recommended option unless compatibility with older guest operating syst= ems is + necessary. libvirt will plug the device into either a PCI Express slot = or a + conventional PCI slot based on the machine type, resulting in a more + optimized PCI topology. +``virtio`` + This device will work like a ``virtio-non-transitional`` device when pl= ugged + into a PCI Express slot, and like a ``virtio-transitional`` device othe= rwise; + libvirt will pick one or the other based on the machine type. This is t= he + best choice when compatibility with libvirt versions older than 5.2.0 is + necessary, but it's otherwise not recommended to use it. + +While the information outlined above applies to most virtio devices, there= are a +few exceptions: + +- for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`= ` for + backwards compatibility reasons; +- some devices, such as GPUs and input devices (keyboard, tablet and mous= e), + are only defined in the virtio 1.0 spec and as such don't have a transi= tional + variant: the only accepted model is ``virtio``, which will result in a + non-transitional device. + +For more details see the `qemu patch +posting `__ +and the `virtio-1.0 +spec `__. + +:anchor:`` + +Controllers +~~~~~~~~~~~ + +Depending on the guest architecture, some device buses can appear more than +once, with a group of virtual devices tied to a virtual controller. Normal= ly, +libvirt can automatically infer such controllers without requiring explici= t XML +markup, but sometimes it is necessary to provide an explicit controller el= ement, +notably when planning the `PCI topology `__ for guests w= here +device hotplug is expected. + +:: + + ... + + + + +
+ + + +
+ + + ... + + ... + +Each controller has a mandatory attribute ``type``, which must be one of '= ide', +'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mand= atory +attribute ``index`` which is the decimal integer describing in which order= the +bus controller is encountered (for use in ``controller`` attributes of +``
`` elements). :since:`Since 1.3.5` the index is optional; if not +specified, it will be auto-assigned to be the lowest unused index for the = given +controller type. Some controller types have additional attributes that con= trol +specific features, such as: + +``virtio-serial`` + The ``virtio-serial`` controller has two additional optional attributes + ``ports`` and ``vectors``, which control how many devices can be connec= ted + through the controller. :since:`Since 5.2.0` , it supports an optional + attribute ``model`` which can be 'virtio', 'virtio-transitional', or + 'virtio-non-transitional'. See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. +``scsi`` + A ``scsi`` controller has an optional attribute ``model``, which is one= of + 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078', + 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitio= nal'. + See `Virtio transitional devices <#elementsVirtioTransitional>`__ for m= ore + details. +``usb`` + A ``usb`` controller has an optional attribute ``model``, which is one = of + "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-u= hci2", + "ich9-uhci3", "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pv= usb + with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu backend, + version 2.0) or "qemu-xhci". Additionally, :since:`since 0.10.0` , if t= he USB + bus needs to be explicitly disabled for the guest, ``model=3D'none'`` m= ay be + used. :since:`Since 1.0.5` , no default USB controller will be built on= s390. + :since:`Since 1.3.5` , USB controllers accept a ``ports`` attribute to + configure how many devices can be connected to the controller. +``ide`` + :since:`Since 3.10.0` for the vbox driver, the ``ide`` controller has an + optional attribute ``model``, which is one of "piix3", "piix4" or "ich6= ". +``xenbus`` + :since:`Since 5.2.0` , the ``xenbus`` controller has an optional attrib= ute + ``maxGrantFrames``, which specifies the maximum number of grant frames = the + controller makes available for connected devices. :since:`Since 6.3.0` = , the + xenbus controller supports the optional ``maxEventChannels`` attribute,= which + specifies maximum number of event channels (PV interrupts) that can be = used + by the guest. + +Note: The PowerPC64 "spapr-vio" addresses do not have an associated contro= ller. + +For controllers that are themselves devices on a PCI or USB bus, an option= al +sub-element ``
`` can specify the exact relationship of the contro= ller +to its master bus, with semantics `given above <#elementsAddress>`__. + +An optional sub-element ``driver`` can specify the driver specific options: + +``queues`` + The optional ``queues`` attribute specifies the number of queues for the + controller. For best performance, it's recommended to specify a value + matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)` +``cmd_per_lun`` + The optional ``cmd_per_lun`` attribute specifies the maximum number of + commands that can be queued on devices controlled by the host. :since:`= Since + 1.2.7 (QEMU and KVM only)` +``max_sectors`` + The optional ``max_sectors`` attribute specifies the maximum amount of = data + in bytes that will be transferred to or from the device in a single com= mand. + The transfer length is measured in sectors, where a sector is 512 bytes. + :since:`Since 1.2.7 (QEMU and KVM only)` +``ioeventfd`` + The optional ``ioeventfd`` attribute specifies whether the controller s= hould + use `I/O asynchronous handling `__ + or not. Accepted values are "on" and "off". :since:`Since 1.2.18` +``iothread`` + Supported for controller type ``scsi`` using model ``virtio-scsi`` for + ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` .= The + optional ``iothread`` attribute assigns the controller to an IOThread as + defined by the range for the domain + `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk`` + assigned to use the specified ``controller`` will utilize the same IOTh= read. + If a specific IOThread is desired for a specific SCSI ``disk``, then mu= ltiple + controllers must be defined each having a specific ``iothread`` value. = The + ``iothread`` value must be within the range 1 to the domain iothreads v= alue. +virtio options + For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ c= an + also be set. ( :since:`Since 3.5.0` ) + +USB companion controllers have an optional sub-element ```` to spe= cify +the exact relationship of the companion to its master controller. A compan= ion +controller is on the same bus as its master, so the companion ``index`` va= lue +should be equal. Not all controller models can be used as companion contro= llers +and libvirt might provide some sensible defaults (settings of +``master startport`` and ``function`` of an address) for some particular m= odels. +Preferred companion controllers are ``ich-uhci[123]``. + +:: + + ... + + +
+ + + +
+ + ... + + ... + +PCI controllers have an optional ``model`` attribute; possible values for = this +attribute are + +- ``pci-root``, ``pci-bridge`` ( :since:`since 1.0.5` ) +- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` ) +- ``pcie-root-port``, ``pcie-switch-upstream-port``, + ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` ) +- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` ) +- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` ) + +The root controllers (``pci-root`` and ``pcie-root``) have an optional +``pcihole64`` element specifying how big (in kilobytes, or in the unit spe= cified +by ``pcihole64``'s ``unit`` attribute) the 64-bit PCI hole should be. Some +guests (like Windows XP or Windows Server 2003) might crash when QEMU and +Seabios are recent enough to support 64-bit PCI holes, unless this is disa= bled +(set to 0). :since:`Since 1.1.2 (QEMU only)` + +PCI controllers also have an optional subelement ```` with an attri= bute +``name``. The name attribute holds the name of the specific device that qe= mu is +emulating (e.g. "i82801b11-bridge") rather than simply the class of device +("pcie-to-pci-bridge", "pci-bridge"), which is set in the controller eleme= nt's +model **attribute**. In almost all cases, you should not manually add a +```` subelement to a controller, nor should you modify one that is +automatically generated by libvirt. :since:`Since 1.2.19 (QEMU only).` + +PCI controllers also have an optional subelement ```` with the +attributes and subelements listed below. These are configurable items that= 1) +are visible to the guest OS so must be preserved for guest ABI compatibili= ty, +and 2) are usually left to default values or derived automatically by libv= irt. +In almost all cases, you should not manually add a ```` subelement= to a +controller, nor should you modify the values in the those that are automat= ically +generated by libvirt. :since:`Since 1.2.19 (QEMU only).` + +``chassisNr`` + PCI controllers that have attribute model=3D"pci-bridge", can also have= a + ``chassisNr`` attribute in the ```` subelement, which is used to + control QEMU's "chassis_nr" option for the pci-bridge device (normally + libvirt automatically sets this to the same value as the index attribut= e of + the pci controller). If set, chassisNr must be between 1 and 255. +``chassis`` + pcie-root-port and pcie-switch-downstream-port controllers can also hav= e a + ``chassis`` attribute in the ```` subelement, which is used to = set + the controller's "chassis" configuration value, which is visible to the + virtual machine. If set, chassis must be between 0 and 255. +``port`` + pcie-root-port and pcie-switch-downstream-port controllers can also hav= e a + ``port`` attribute in the ```` subelement, which is used to set= the + controller's "port" configuration value, which is visible to the virtual + machine. If set, port must be between 0 and 255. +``hotplug`` + pcie-root-port and pcie-switch-downstream-port controllers can also hav= e a + ``hotplug`` attribute in the ```` subelement, which is used to + disable hotplug/unplug of devices on a particular controller. The defau= lt + setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable + hotplug/unplug of devices on a particular controller. :since:`Since 6.3= .0` +``busNr`` + pci-expander-bus and pcie-expander-bus controllers can have an optional + ``busNr`` attribute (1-254). This will be the bus number of the new bus= ; All + bus numbers between that specified and 255 will be available only for + assignment to PCI/PCIe controllers plugged into the hierarchy starting = with + this expander bus, and bus numbers less than the specified value will be + available to the next lower expander-bus (or the root-bus if there are = no + lower expander buses). If you do not specify a busNumber, libvirt will = find + the lowest existing busNumber in all other expander buses (or use 256 if + there are no others) and auto-assign the busNr of that found bus - 2, w= hich + provides one bus number for the pci-expander-bus and one for the pci-br= idge + that is automatically attached to it (if you plan on adding more pci-br= idges + to the hierarchy of the bus, you should manually set busNr to a lower v= alue). + + A similar algorithm is used for automatically determining the busNr att= ribute + for pcie-expander-bus, but since the pcie-expander-bus doesn't have any + built-in pci-bridge, the 2nd bus-number is just being reserved for the + pcie-root-port that must necessarily be connected to the bus in order to + actually plug in an endpoint device. If you intend to plug multiple dev= ices + into a pcie-expander-bus, you must connect a pcie-switch-upstream-port = to the + pcie-root-port that is plugged into the pcie-expander-bus, and multiple + pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of c= ourse + for this to work properly, you will need to decrease the pcie-expander-= bus' + busNr accordingly so that there are enough unused bus numbers above it = to + accommodate giving out one bus number for the upstream-port and one for= each + downstream-port (in addition to the pcie-root-port and the pcie-expande= r-bus + itself). + +``node`` + Some PCI controllers (``pci-expander-bus`` for the pc machine type, + ``pcie-expander-bus`` for the q35 machine type and, :since:`since 3.6.0= ` , + ``pci-root`` for the pseries machine type) can have an optional ```` + subelement within the ```` subelement, which is used to set the= NUMA + node reported to the guest OS for that bus - the guest OS will then kno= w that + all devices on that bus are a part of the specified NUMA node (it is up= to + the user of the libvirt API to attach host devices to the correct + pci-expander-bus when assigning them to the domain). +``index`` + pci-root controllers for pSeries guests use this attribute to record the + order they will show up in the guest. :since:`Since 3.6.0` + +For machine types which provide an implicit PCI bus, the pci-root controll= er +with index=3D0 is auto-added and required to use PCI devices. pci-root has= no +address. PCI bridges are auto-added if there are too many devices to fit o= n the +one bus provided by pci-root, or a PCI bus number greater than zero was +specified. PCI bridges can also be specified manually, but their addresses +should only refer to PCI buses provided by already specified PCI controlle= rs. +Leaving gaps in the PCI controller indexes might lead to an invalid +configuration. + +:: + + ... + + + +
+ + + ... + +For machine types which provide an implicit PCI Express (PCIe) bus (for ex= ample, +the machine types based on the Q35 chipset), the pcie-root controller with +index=3D0 is auto-added to the domain's configuration. pcie-root has also = no +address, provides 31 slots (numbered 1-31) that can be used to attach PCIe= or +PCI devices (although libvirt will never auto-assign a PCI device to a PCIe +slot, it will allow manual specification of such an assignment). Devices +connected to pcie-root cannot be hotplugged. If traditional PCI devices are +present in the guest configuration, a ``pcie-to-pci-bridge`` controller wi= ll +automatically be added: this controller, which plugs into a ``pcie-root-po= rt``, +provides 31 usable PCI slots (1-31) with hotplug support ( :since:`since 4= .3.0` +). If the QEMU binary doesn't support the corresponding device, then a +``dmi-to-pci-bridge`` controller will be added instead, usually at the def= acto +standard location of slot=3D0x1e. A dmi-to-pci-bridge controller plugs int= o a PCIe +slot (as provided by pcie-root), and itself provides 31 standard PCI slots +(which also do not support device hotplug). In order to have hot-pluggable= PCI +slots in the guest system, a pci-bridge controller will also be automatica= lly +created and connected to one of the slots of the auto-created dmi-to-pci-b= ridge +controller; all guest PCI devices with addresses that are auto-determined = by +libvirt will be placed on this pci-bridge device. ( :since:`since 1.1.2` ). + +Domains with an implicit pcie-root can also add controllers with +``model=3D'pcie-root-port'``, ``model=3D'pcie-switch-upstream-port'``, and +``model=3D'pcie-switch-downstream-port'``. pcie-root-port is a simple type= of +bridge device that can connect only to one of the 31 slots on the pcie-roo= t bus +on its upstream side, and makes a single (PCIe, hotpluggable) port availab= le on +the downstream side (at slot=3D'0'). pcie-root-port can be used to provide= a +single slot to later hotplug a PCIe device (but is not itself hotpluggable= - it +must be in the configuration when the domain is started). ( :since:`since +1.2.19` ) + +pcie-switch-upstream-port is a more flexible (but also more complex) devic= e that +can only plug into a pcie-root-port or pcie-switch-downstream-port on the +upstream side (and only before the domain is started - it is not hot-plugg= able), +and provides 32 ports on the downstream side (slot=3D'0' - slot=3D'31') th= at accept +only pcie-switch-downstream-port devices; each pcie-switch-downstream-port +device can only plug into a pcie-switch-upstream-port on its upstream side +(again, not hot-pluggable), and on its downstream side provides a single +hotpluggable pcie port that can accept any standard pci or pcie device (or +another pcie-switch-upstream-port), i.e. identical in function to a +pcie-root-port. ( :since:`since 1.2.19` ) + +:: + + ... + + + +
+ + +
+ + + ... + +:anchor:`` + +Device leases +~~~~~~~~~~~~~ + +When using a lock manager, it may be desirable to record device leases aga= inst a +VM. The lock manager will ensure the VM won't start unless the leases can = be +acquired. + +:: + + ... + + ... + + somearea + somekey + + + ... + + ... + +``lockspace`` + This is an arbitrary string, identifying the lockspace within which the= key + is held. Lock managers may impose extra restrictions on the format, or = length + of the lockspace name. +``key`` + This is an arbitrary string, uniquely identifying the lease to be acqui= red. + Lock managers may impose extra restrictions on the format, or length of= the + key. +``target`` + This is the fully qualified path of the file associated with the locksp= ace. + The offset specifies where the lease is stored within the file. If the = lock + manager does not require an offset, just pass 0. + +:anchor:`` + +Host device assignment +~~~~~~~~~~~~~~~~~~~~~~ + +:anchor:`` + +USB / PCI / SCSI devices +^^^^^^^^^^^^^^^^^^^^^^^^ + +USB, PCI and SCSI devices attached to the host can be passed through to the +guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.= 6.0 +for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` : + +:: + + ... + + + + + + + + + + ... + +or: + +:: + + ... + + + +
+ + + + + + ... + +or: + +:: + + ... + + + + +
+ + +
+ + + ... + +or: + +:: + + ... + + + + + + + + +
+ + + ... + +or: + +:: + + ... + + + + + + ... + +or: + +:: + + ... + + + +
+ + + + +
+ +
+ + + ... + +``hostdev`` + The ``hostdev`` element is the main container for describing host devic= es. + For each device, the ``mode`` is always "subsystem" and the ``type`` is= one + of the following values with additional attributes noted. + + ``usb`` + USB devices are detached from the host on guest startup and reattach= ed + after the guest exits or the device is hot-unplugged. + ``pci`` + For PCI devices, when ``managed`` is "yes" it is detached from the h= ost + before being passed on to the guest and reattached to the host after= the + guest exits. If ``managed`` is omitted or "no", the user is responsi= ble to + call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before + starting the guest or hot-plugging the device and + ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-= unplug + or stopping the guest. + ``scsi`` + For SCSI devices, user is responsible to make sure the device is not= used + by host. If supported by the hypervisor and OS, the optional ``sgio`= ` ( + :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO + commands are filtered for the disk. Valid settings are "filtered" or + "unfiltered", where the default is "filtered". The optional ``rawio`= ` ( + :since:`since 1.2.9` ) attribute indicates whether the lun needs the= rawio + capability. Valid settings are "yes" or "no". See the rawio descript= ion + within the `disk <#elementsDisks>`__ section. If a disk lun in the d= omain + already has the rawio capability, then this setting not required. + ``scsi_host`` + :since:`since 2.5.0` For SCSI devices, user is responsible to make s= ure + the device is not used by host. This ``type`` passes all LUNs presen= ted by + a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attri= bute + can be specified further with "virtio-transitional", + "virtio-non-transitional", or "virtio". See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. + ``mdev`` + For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute + specifies the device API which determines how the host's vfio driver= will + expose the device to the guest. Currently, ``model=3D'vfio-pci'``, + ``model=3D'vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model=3D'vfio-= ap'`` ( + :since:`Since 4.9.0` ) is supported. `MDEV `__ + section provides more information about mediated devices as well as = how to + create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)= ` an + optional ``display`` attribute may be used to enable or disable supp= ort + for an accelerated remote desktop backed by a mediated device (such = as + NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video + devices <#elementsVideo>`__. This attribute is limited to + ``model=3D'vfio-pci'`` only. Supported values are either ``on`` or `= `off`` + (default is 'off'). It is required to use a `graphical + framebuffer <#elementsGraphics>`__ in order to use this attribute, + currently only supported with VNC, Spice and egl-headless graphics + devices. :since:`Since version 5.10.0` , there is an optional ``ramf= b`` + attribute for devices with ``model=3D'vfio-pci'``. Supported values = are + either ``on`` or ``off`` (default is 'off'). When enabled, this attr= ibute + provides a memory framebuffer device to the guest. This framebuffer = will + be used as a boot display when a vgpu device is the primary display. + + Note: There are also some implications on the usage of guest's addre= ss + type depending on the ``model`` attribute, see the ``address`` eleme= nt + below. + + Note: The ``managed`` attribute is only used with ``type=3D'pci'`` and = is + ignored by all the other device types, thus setting ``managed`` explici= tly + with other than a PCI device has the same effect as omitting it. Simila= rly, + ``model`` attribute is only supported by mediated devices and ignored b= y all + other device types. + +``source`` + The source element describes the device as seen from the host using the + following mechanism to describe: + + ``usb`` + The USB device can either be addressed by vendor / product id using = the + ``vendor`` and ``product`` elements or by the device's address on th= e host + using the ``address`` element. + + :since:`Since 1.0.0` , the ``source`` element of USB devices may con= tain + ``startupPolicy`` attribute which can be used to define policy what = to do + if the specified host USB device is not found. The attribute accepts= the + following values: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + mandatory fail if missing for any reason (the default) + requisite fail if missing on boot up, drop if missing on migrate/res= tore/revert + optional drop if missing at any start attempt + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + + ``pci`` + PCI devices can only be described by their ``address``. + ``scsi`` + SCSI devices are described by both the ``adapter`` and ``address`` + elements. The ``address`` element includes a ``bus`` attribute (a 2-= digit + bus number), a ``target`` attribute (a 10-digit target number), and a + ``unit`` attribute (a 20-digit unit number on the bus). Not all + hypervisors support larger ``target`` and ``unit`` values. It is up = to + each hypervisor to determine the maximum value supported for the ada= pter. + + :since:`Since 1.2.8` , the ``source`` element of a SCSI device may c= ontain + the ``protocol`` attribute. When the attribute is set to "iscsi", th= e host + device XML follows the network `disk <#elementsDisks>`__ device usin= g the + same ``name`` attribute and optionally using the ``auth`` element to + provide the authentication credentials to the iSCSI server. + + ``scsi_host`` + :since:`Since 2.5.0` , multiple LUNs behind a single SCSI HBA are + described by a ``protocol`` attribute set to "vhost" and a ``wwpn`` + attribute that is the vhost_scsi wwpn (16 hexadecimal digits with a = prefix + of "naa.") established in the host configfs. + ``mdev`` + Mediated devices ( :since:`Since 3.2.0` ) are described by the ``add= ress`` + element. The ``address`` element contains a single mandatory attribu= te + ``uuid``. + +``vendor``, ``product`` + The ``vendor`` and ``product`` elements each have an ``id`` attribute t= hat + specifies the USB vendor and product id. The ids can be given in decima= l, + hexadecimal (starting with 0x) or octal (starting with 0) form. +``boot`` + Specifies that the device is bootable. The ``order`` attribute determin= es the + order in which devices will be tried during boot sequence. The per-devi= ce + ``boot`` elements cannot be used together with general boot elements in= `BIOS + bootloader <#elementsOSBIOS>`__ section. :since:`Since 0.8.8` for PCI + devices, :since:`Since 1.0.1` for USB devices. +``rom`` + The ``rom`` element is used to change how a PCI device's ROM is present= ed to + the guest. The optional ``bar`` attribute can be set to "on" or "off", = and + determines whether or not the device's ROM will be visible in the guest= 's + memory map. (In PCI documentation, the "rombar" setting controls the pr= esence + of the Base Address Register for the ROM). If no rom bar is specified, = the + qemu default will be used (older versions of qemu used a default of "of= f", + while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU an= d KVM + only)` . The optional ``file`` attribute contains an absolute path to a + binary file to be presented to the guest as the device's ROM BIOS. This= can + be useful, for example, to provide a PXE boot ROM for a virtual functio= n of + an sr-iov capable ethernet device (which has no boot ROMs for the VFs). + :since:`Since 0.9.10 (QEMU and KVM only)` . The optional ``enabled`` + attribute can be set to ``no`` to disable PCI ROM loading completely fo= r the + device; if PCI ROM loading is disabled through this attribute, attempts= to + tweak the loading process further using the ``bar`` or ``file`` attribu= tes + will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)` . +``address`` + The ``address`` element for USB devices has a ``bus`` and ``device`` + attribute to specify the USB bus and device number the device appears a= t on + the host. The values of these attributes can be given in decimal, hexad= ecimal + (starting with 0x) or octal (starting with 0) form. For PCI devices the + element carries 4 attributes allowing to designate the device as can be= found + with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a '= drive' + address type must be used. For mediated devices, which are software-only + devices defining an allocation of resources on the physical parent devi= ce, + the address type used must conform to the ``model`` attribute of element + ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` devi= ce API + or any address type other than CCW for ``vfio-ccw`` device API will res= ult in + an error. `See above <#elementsAddress>`__ for more details on the addr= ess + element. +``driver`` + PCI devices can have an optional ``driver`` subelement that specifies w= hich + backend driver to use for PCI device assignment. Use the ``name`` attri= bute + to select either "vfio" (for the new VFIO device assignment backend, wh= ich is + compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment + handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU an= d KVM + only, requires kernel 3.6 or newer)` . When specified, device assignmen= t will + fail if the requested method of device assignment isn't available on the + host. When not specified, the default is "vfio" on systems where the VF= IO + driver is available and loaded, and "kvm" on older systems, or those wh= ere + the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that = the + default was always "kvm"). +``readonly`` + Indicates that the device is readonly, only supported by SCSI host devi= ce + now. :since:`Since 1.0.6 (QEMU and KVM only)` +``shareable`` + If present, this indicates the device is expected to be shared between + domains (assuming the hypervisor and OS support this). Only supported b= y SCSI + host device. :since:`Since 1.0.6` + + Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did = not + work as as expected until :since:`1.2.2` . + +:anchor:`` + +Block / character devices +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Block / character devices from the host can be passed through to the guest= using +the ``hostdev`` element. This is only possible with container based +virtualization. Devices are specified by a fully qualified path. :since:`s= ince +after 1.0.1 for LXC` : + +:: + + ... + + + /dev/sdf1 + + + ... + +:: + + ... + + + /dev/input/event3 + + + ... + +:: + + ... + + + eth0 + + + ... + +``hostdev`` + The ``hostdev`` element is the main container for describing host devic= es. + For block/character device passthrough ``mode`` is always "capabilities= " and + ``type`` is "storage" for a block device, "misc" for a character device= and + "net" for a host network interface. +``source`` + The source element describes the device as seen from the host. For block + devices, the path to the block device in the host OS is provided in the + nested "block" element, while for character devices the "char" element = is + used. For network interfaces, the name of the interface is provided in = the + "interface" element. + +:anchor:`` + +Redirected devices +~~~~~~~~~~~~~~~~~~ + +USB device redirection through a character device is supported :since:`sin= ce +after 0.9.5 (KVM only)` : + +:: + + ... + + + + + + + + + + + ... + +``redirdev`` + The ``redirdev`` element is the main container for describing redirected + devices. ``bus`` must be "usb" for a USB device. An additional attribute + ``type`` is required, matching one of the supported `serial + device <#elementsConsole>`__ types, to describe the host side of the tu= nnel; + ``type=3D'tcp'`` or ``type=3D'spicevmc'`` (which uses the usbredir chan= nel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. The redirdev + element has an optional sub-element ``
`` which can tie the dev= ice to + a particular controller. Further sub-elements, such as ````, ma= y be + required according to the given type, although a ```` sub-eleme= nt is + not required (since the consumer of the character device is the hypervi= sor + itself, rather than a device visible in the guest). +``boot`` + Specifies that the device is bootable. The ``order`` attribute determin= es the + order in which devices will be tried during boot sequence. The per-devi= ce + ``boot`` elements cannot be used together with general boot elements in= `BIOS + bootloader <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` ) +``redirfilter`` + The\ ``redirfilter``\ element is used for creating the filter rule to f= ilter + out certain devices from redirection. It uses sub-element ```` = to + define each filter rule. ``class`` attribute is the USB Class code, for + example, 0x08 represents mass storage devices. The USB device can be + addressed by vendor / product id using the ``vendor`` and ``product`` + attributes. ``version`` is the device revision from the bcdDevice field= (not + the version of the USB protocol). These four attributes are optional and + ``-1`` can be used to allow any value for them. ``allow`` attribute is + mandatory, 'yes' means allow, 'no' for deny. + +:anchor:`` + +Smartcard devices +~~~~~~~~~~~~~~~~~ + +A virtual smartcard device can be supplied to the guest via the ``smartcar= d`` +element. A USB smartcard reader device on the host cannot be used on a gue= st +with simple device passthrough, since it will then not be available on the= host, +possibly locking the host computer when it is "removed". Therefore, some +hypervisors provide a specialized virtual device that can present a smartc= ard +interface to the guest, with several modes for describing how credentials = are +obtained from the host or even a from a channel created to a third-party +smartcard provider. :since:`Since 0.8.8` + +:: + + ... + + + + cert1 + cert2 + cert3 + /etc/pki/nssdb/ + + + + +
+ + + + ... + +The ```` element has a mandatory attribute ``mode``. The follow= ing +modes are supported; in each mode, the guest sees a device on its USB bus = that +behaves like a physical USB CCID (Chip/Smart Card Interface Device) card. + +``host`` + The simplest operation, where the hypervisor relays all requests from t= he + guest into direct access to the host's smartcard via NSS. No other attr= ibutes + or sub-elements are required. See below about the use of an optional + ``
`` sub-element. +``host-certificates`` + Rather than requiring a smartcard to be plugged into the host, it is po= ssible + to provide three NSS certificate names residing in a database on the ho= st. + These certificates can be generated via the command + ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=3Dcert1 -n c= ert1``, + and the resulting three certificate names must be supplied as the conte= nt of + each of three ```` sub-elements. An additional sub-element + ```` can specify the absolute path to an alternate directory + (matching the ``-d`` option of the ``certutil`` command when creating t= he + certificates); if not present, it defaults to /etc/pki/nssdb. +``passthrough`` + Rather than having the hypervisor directly communicate with the host, i= t is + possible to tunnel all requests through a secondary character device to= a + third-party provider (which may in turn be talking to a smartcard or us= ing + three certificate files). In this mode of operation, an additional attr= ibute + ``type`` is required, matching one of the supported `serial + device <#elementsConsole>`__ types, to describe the host side of the tu= nnel; + ``type=3D'tcp'`` or ``type=3D'spicevmc'`` (which uses the smartcard cha= nnel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. Further + sub-elements, such as ````, may be required according to the gi= ven + type, although a ```` sub-element is not required (since the co= nsumer + of the character device is the hypervisor itself, rather than a device + visible in the guest). + +Each mode supports an optional sub-element ``
``, which fine-tunes= the +correlation between the smartcard and a ccid bus controller, `documented +above <#elementsAddress>`__. For now, qemu only supports at most one smart= card, +with an address of bus=3D0 slot=3D0. + +:anchor:`` + +Network interfaces +~~~~~~~~~~~~~~~~~~ + +:: + + ... + + + + + + + + + ... + +There are several possibilities for specifying a network interface visible= to +the guest. Each subsection below provides more details about common setup +options. + +:since:`Since 1.2.10` ), the ``interface`` element property +``trustGuestRxFilters`` provides the capability for the host to detect and= trust +reports from the guest regarding changes to the interface mac address and +receive filters by setting the attribute to ``yes``. The default setting f= or the +attribute is ``no`` for security reasons and support depends on the guest +network device model as well as the type of connection on the host - curre= ntly +it is only supported for the virtio device model and for macvtap connectio= ns on +the host. + +Each ```` element has an optional ``
`` sub-element tha= t can +tie the interface to a particular pci slot, with attribute ``type=3D'pci'`= ` as +`documented above <#elementsAddress>`__. + +:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC addr= ess +when it's in the reserved VMware range by adding a ``type=3D"static"`` att= ribute +to the ```` element. Note that this attribute is useless if the prov= ided +MAC address is outside of the reserved VMWare ranges. + +:anchor:`` + +Virtual network +^^^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts w= ith +dynamic / wireless networking configs (or multi-host environments where th= e host +hardware details are described separately in a ```` definition +:since:`Since 0.9.4` ).** + +Provides a connection whose details are described by the named network +definition. Depending on the virtual network's "forward mode" configuratio= n, the +network may be totally isolated (no ```` element given), NAT'ing = to an +explicit network device or to the default route (```= `), +routed with no NAT (````), or connected directly = to one +of the host's network interfaces (via macvtap) or bridge devices +((```` :since:`Si= nce +0.9.4` ) + +For networks with a forward mode of bridge, private, vepa, and passthrough= , it +is assumed that the host has any necessary DNS and DHCP services already s= etup +outside the scope of libvirt. In the case of isolated, nat, and routed net= works, +DHCP and DNS are provided on the virtual network by libvirt, and the IP ra= nge +can be determined by examining the virtual network config with +'``virsh net-dumpxml [networkname]``'. There is one virtual network called +'default' setup out of the box which does NAT'ing to the default route and= has +an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an +associated tun device created with a name of vnetN, which can also be over= ridden +with the element (see `overriding the target +element <#elementsNICSTargetOverride>`__). + +When the source of an interface is a network, a ``portgroup`` can be speci= fied +along with the name of the network; one network may have multiple portgrou= ps +defined, with each portgroup containing slightly different configuration +information for different classes of network connections. :since:`Since 0.= 9.4` . + +When a guest is running an interface of type ``network`` may include a +``portid`` attribute. This provides the UUID of an associated virNetworkPo= rtPtr +object that records the association between the domain interface and the +network. This attribute is read-only since port objects are create and del= eted +automatically during startup and shutdown. :since:`Since 5.1.0` + +Also, similar to ``direct`` network connections (described below), a conne= ction +of type ``network`` may specify a ``virtualport`` element, with configurat= ion +data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch ( +:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Sin= ce +0.9.11` ). + +Since the actual type of switch may vary depending on the configuration in= the +```` on the host, it is acceptable to omit the virtualport ``type= `` +attribute, and specify attributes from multiple different virtualport type= s (and +also to leave out certain attributes); at domain startup time, a complete +```` element will be constructed by merging together the type= and +attributes defined in the network and the portgroup referenced by the inte= rface. +The newly-constructed virtualport is a combination of them. The attributes= from +lower virtualport can't make change on the ones defined in higher virtualp= ort. +Interface takes the highest priority, portgroup is lowest priority. ( +:since:`Since 0.10.0` ). For example, in order to work properly with both = an +802.1Qbh switch and an Open vSwitch switch, you may choose to specify no t= ype, +but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfa= ceid`` +(in case the switch is Open vSwitch) (you may also omit the other attribut= es, +such as managerid, typeid, or profileid, to be filled in from the network's +````). If you want to limit a guest to connecting only to cer= tain +types of switches, you can specify the virtualport type, but still omit so= me/all +of the parameters - in this case if the host's network has a different typ= e of +virtualport, connection of the interface will fail. + +:: + + ... + + + + + ... + + + + + + + + + + ... + +:anchor:`` + +Bridge to LAN +^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts w= ith +static wired networking configs.** + +Provides a bridge from the VM directly to the LAN. This assumes there is a +bridge device on the host which has one or more of the hosts physical NICs +attached. The guest VM will have an associated tun device created with a n= ame of +vnetN, which can also be overridden with the element (see `overri= ding +the target element <#elementsNICSTargetOverride>`__). The tun device will = be +attached to the bridge. The IP range / network configuration is whatever i= s used +on the LAN. This provides the guest VM full incoming & outgoing net access= just +like a physical machine. + +On Linux systems, the bridge device is normally a standard Linux host brid= ge. On +hosts that support Open vSwitch, it is also possible to connect to an Open +vSwitch bridge device by adding a ```` = to the +interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type +virtualport accepts two parameters in its ```` element - an +``interfaceid`` which is a standard uuid used to uniquely identify this +particular interface to Open vSwitch (if you do not specify one, a random +interfaceid will be generated for you when you first define the interface)= , and +an optional ``profileid`` which is sent to Open vSwitch as the interfaces +"port-profile". + +:: + + ... + + ... + + + + + + + + + + + + + + + ... + + ... + +On hosts that support Open vSwitch on the kernel side and have the Midonet= Host +Agent configured, it is also possible to connect to the 'midonet' bridge d= evice +by adding a ```` to the interface definitio= n. ( +:since:`Since 1.2.13` ). The Midonet virtualport type requires an +``interfaceid`` attribute in its ```` element. This interface = id is +the UUID that specifies which port in the virtual network topology will be= bound +to the interface. + +:: + + ... + + ... + + + + + + + + + + + + + + + ... + + ... + +:anchor:`` + +Userspace SLIRP stack +^^^^^^^^^^^^^^^^^^^^^ + +Provides a virtual LAN with NAT to the outside world. The virtual network = has +DHCP & DNS services and will give the guest VM addresses starting from +``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server = will +be ``10.0.2.3``. This networking is the only option for unprivileged users= who +need their VMs to have outgoing access. :since:`Since 3.8.0` it is possibl= e to +override the default network address by including an ``ip`` element specif= ying +an IPv4 address in its one mandatory attribute, ``address``. Optionally, a +second ``ip`` element with a ``family`` attribute set to "ipv6" can be spe= cified +to add an IPv6 address to the interface. ``address``. Optionally, address +``prefix`` can be specified. + +:: + + ... + + + ... + + + + + + + ... + +:anchor:`` + +Generic ethernet connection +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Provides a means to use a new or existing tap device (or veth device pair, +depening on the needs of the hypervisor driver) that is partially or wholly +setup external to libvirt (either prior to the guest starting, or while the +guest is being started via an optional script specified in the config). + +The name of the tap device can optionally be specified with the ``dev`` +attribute of the ```` element. If no target dev is specified, libv= irt +will create a new standard tap device with a name of the pattern "vnetN", = where +"N" is replaced with a number. If a target dev is specified and that device +doesn't exist, then a new standard tap device will be created with the exa= ct dev +name given. If the specified target dev does exist, then that existing dev= ice +will be used. Usually some basic setup of the device is done by libvirt, +including setting a MAC address, and the IFF_UP flag, but if the ``dev`` i= s a +pre-existing device, and the ``managed`` attribute of the ``target`` eleme= nt is +also set to "no" (the default value is "yes"), even this basic setup will = not be +performed - libvirt will simply pass the device on to the hypervisor with = no +setup at all. :since:`Since 5.7.0` Using managed=3D'no' with a pre-created= tap +device is useful because it permits a virtual machine managed by an unpriv= ileged +libvirtd to have emulated network devices based on tap devices. + +After creating/opening the tap device, an optional shell script (given in = the +``path`` attribute of the ``