23.17. Devices
This set of XML elements are all used to describe devices provided to the guest virtual machine domain. All of the devices below are indicated as children of the main
<devices> element.
The following virtual devices are supported:
- virtio-scsi-pci - PCI bus storage device
- virtio-blk-pci - PCI bus storage device
- virtio-net-pci - PCI bus network device also known as virtio-net
- virtio-serial-pci - PCI bus input device
- virtio-balloon-pci - PCI bus memory balloon device
- virtio-rng-pci - PCI bus virtual random number generator device
Important
If a virtio device is created where the number of vectors is set to a value higher than 32, the device behaves as if it was set to a zero value on Red Hat Enterprise Linux 6, but not on Enterprise Linux 7. The resulting vector setting mismatch causes a migration error if the number of vectors on any virtio device on either platform is set to 33 or higher. It is, therefore, not recommended to set the vector value to be greater than 32. All virtio devices with the exception of
virtio-balloon-pci and virtio-rng-pci will accept a vector argument.
...
<devices>
<emulator>/usr/libexec/qemu-kvm</emulator>
</devices>
...
Figure 23.26. Devices - child elements
The contents of the
<emulator> element specify the fully qualified path to the device model emulator binary. The capabilities XML specifies the recommended default emulator to use for each particular domain type or architecture combination.
23.17.1. Hard Drives, Floppy Disks, and CD-ROMs
This section of the domain XML specifies any device that looks like a disk, including any floppy disk, hard disk, CD-ROM, or paravirtualized driver that is specified in the
<disk> element.
<disk type='network'>
<driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/>
<source protocol="sheepdog" name="image_name">
<host name="hostname" port="7000"/>
</source>
<target dev="hdb" bus="ide"/>
<boot order='1'/>
<transient/>
<address type='drive' controller='0' bus='1' unit='0'/>
</disk>Figure 23.27. Devices - Hard drives, floppy disks, CD-ROMs Example
<disk type='network'>
<driver name="qemu" type="raw"/>
<source protocol="rbd" name="image_name2">
<host name="hostname" port="7000"/>
</source>
<target dev="hdd" bus="ide"/>
<auth username='myuser'>
<secret type='ceph' usage='mypassid'/>
</auth>
</disk>Figure 23.28. Devices - Hard drives, floppy disks, CD-ROMs Example 2
<disk type='block' device='cdrom'>
<driver name='qemu' type='raw'/>
<target dev='hdc' bus='ide' tray='open'/>
<readonly/>
</disk>
<disk type='network' device='cdrom'>
<driver name='qemu' type='raw'/>
<source protocol="http" name="url_path">
<host name="hostname" port="80"/>
</source>
<target dev='hdc' bus='ide' tray='open'/>
<readonly/>
</disk>Figure 23.29. Devices - Hard drives, floppy disks, CD-ROMs Example 3
<disk type='network' device='cdrom'>
<driver name='qemu' type='raw'/>
<source protocol="https" name="url_path">
<host name="hostname" port="443"/>
</source>
<target dev='hdc' bus='ide' tray='open'/>
<readonly/>
</disk>
<disk type='network' device='cdrom'>
<driver name='qemu' type='raw'/>
<source protocol="ftp" name="url_path">
<host name="hostname" port="21"/>
</source>
<target dev='hdc' bus='ide' tray='open'/>
<readonly/>
</disk>Figure 23.30. Devices - Hard drives, floppy disks, CD-ROMs Example 4
<disk type='network' device='cdrom'>
<driver name='qemu' type='raw'/>
<source protocol="ftps" name="url_path">
<host name="hostname" port="990"/>
</source>
<target dev='hdc' bus='ide' tray='open'/>
<readonly/>
</disk>
<disk type='network' device='cdrom'>
<driver name='qemu' type='raw'/>
<source protocol="tftp" name="url_path">
<host name="hostname" port="69"/>
</source>
<target dev='hdc' bus='ide' tray='open'/>
<readonly/>
</disk>
<disk type='block' device='lun'>
<driver name='qemu' type='raw'/>
<source dev='/dev/sda'/>
<target dev='sda' bus='scsi'/>
<address type='drive' controller='0' bus='0' target='3' unit='0'/>
</disk>Figure 23.31. Devices - Hard drives, floppy disks, CD-ROMs Example 5
<disk type='block' device='disk'>
<driver name='qemu' type='raw'/>
<source dev='/dev/sda'/>
<geometry cyls='16383' heads='16' secs='63' trans='lba'/>
<blockio logical_block_size='512' physical_block_size='4096'/>
<target dev='hda' bus='ide'/>
</disk>
<disk type='volume' device='disk'>
<driver name='qemu' type='raw'/>
<source pool='blk-pool0' volume='blk-pool0-vol0'/>
<target dev='hda' bus='ide'/>
</disk>
<disk type='network' device='disk'>
<driver name='qemu' type='raw'/>
<source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'>
<host name='example.com' port='3260'/>
</source>
<auth username='myuser'>
<secret type='chap' usage='libvirtiscsi'/>
</auth>
<target dev='vda' bus='virtio'/>
</disk>Figure 23.32. Devices - Hard drives, floppy disks, CD-ROMs Example 6
<disk type='network' device='lun'>
<driver name='qemu' type='raw'/>
<source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/1'>
iqn.2013-07.com.example:iscsi-pool
<host name='example.com' port='3260'/>
</source>
<auth username='myuser'>
<secret type='chap' usage='libvirtiscsi'/>
</auth>
<target dev='sda' bus='scsi'/>
</disk>
<disk type='volume' device='disk'>
<driver name='qemu' type='raw'/>
<source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/>
<auth username='myuser'>
<secret type='chap' usage='libvirtiscsi'/>
</auth>
<target dev='vda' bus='virtio'/>
</disk>Figure 23.33. Devices - Hard drives, floppy disks, CD-ROMs Example 7
<disk type='volume' device='disk'>
<driver name='qemu' type='raw'/>
<source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/>
<auth username='myuser'>
<secret type='chap' usage='libvirtiscsi'/>
</auth>
<target dev='vda' bus='virtio'/>
</disk>
<disk type='file' device='disk'>
<driver name='qemu' type='raw' cache='none'/>
<source file='/tmp/test.img' startupPolicy='optional'/>
<target dev='sdb' bus='scsi'/>
<readonly/>
</disk>
<disk type='file' device='disk'>
<driver name='qemu' type='raw' discard='unmap'/>
<source file='/var/lib/libvirt/images/discard1.img'/>
<target dev='vdb' bus='virtio'/>
<alias name='virtio-disk1'/>
<address type='pci' domain='0x0000' bus='0x00' slot='0x09' function='0x0'/>
</disk>
</devices>
...
Figure 23.34. Devices - Hard drives, floppy disks, CD-ROMs Example 8
23.17.1.1. Disk element
The
<disk> element is the main container for describing disks. The attribute type can be used with the <disk> element. The following types are allowed:
fileblockdirnetwork
For more information, see the libvirt upstream pages.
23.17.1.2. Source element
Represents the disk source. The disk source depends on the disk type attribute, as follows:
<file>- Thefileattribute specifies the fully-qualified path to the file in which the disk is located.<block>- Thedevattribute specifies the fully-qualified path to the host device that serves as the disk.<dir>- Thedirattribute specifies the fully-qualified path to the directory used as the disk.<network>- Theprotocolattribute specifies the protocol used to access the requested image. Possible values are:nbd,isci,rbd,sheepdog, andgluster.- If the
protocolattribute isrbd,sheepdog, orgluster, an additional attribute,nameis mandatory. This attribute specifies which volume and image will be used. - If the
protocolattribute isnbd, thenameattribute is optional. - If the
protocolattribute isisci, thenameattribute may include a logical unit number, separated from the target's name with a slash. For example: iqn.2013-07.com.example:iscsi-pool/1. If not specified, the default LUN is zero.
<volume>- The underlying disk source is represented by thepoolandvolumeattributes.<pool>- The name of the storage pool (managed bylibvirt) where the disk source resides.<volume>- The name of the storage volume (managed bylibvirt) used as the disk source.The value for thevolumeattribute is the output from the Name column of avirsh vol-list [pool-name]
When the disk type is
network, the source may have zero or more host sub-elements used to specify the host physical machines to connect, including: type='dir' and type='network'. For a file disk type which represents a CD-ROM or floppy (the device attribute), it is possible to define the policy for what to do with the disk if the source file is not accessible. This is done by setting the startupPolicy attribute with one of the following values:
mandatorycauses a failure if missing for any reason. This is the default setting.requisitecauses a failure if missing on boot up, drops if missing on migrate, restore, or revert.optionaldrops if missing at any start attempt.
23.17.1.3. Mirror element
This element is present if the hypervisor has started a
BlockCopy operation, where the <mirror> location in the attribute file will eventually have the same contents as the source, and with the file format in attribute format (which might differ from the format of the source). If an attribute ready is present, then it is known the disk is ready to pivot; otherwise, the disk is probably still copying. For now, this element only valid in output; it is ignored on input.
23.17.1.4. Target element
The
<target> element controls the bus or device under which the disk is exposed to the guest virtual machine operating system. 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 virtual machine operating system. The optional bus attribute specifies the type of disk device to emulate; possible values are driver-specific, with typical values being ide, scsi, virtio, kvm, usb or sata. If omitted, the bus type is inferred from the style of the device name. For example, a device named 'sda' will typically be exported using a SCSI bus. The optional attribute tray indicates the tray status of the removable disks (for example, CD-ROM or Floppy disk), where the value can be either open or closed. The default setting is closed.
23.17.1.5. iotune element
The optional
<iotune> element provides the ability to provide additional per-device I/O tuning, with values that can vary for each device (contrast this to the blkiotune element, which applies globally to the domain). This element has the following optional sub-elements (note that any sub-element not specified or at all or specified with a value of 0 implies no limit):
<total_bytes_sec>- The total throughput limit in bytes per second. This element cannot be used with<read_bytes_sec>or<write_bytes_sec>.<read_bytes_sec>- The read throughput limit in bytes per second.<write_bytes_sec>- The write throughput limit in bytes per second.<total_iops_sec>- The total I/O operations per second. This element cannot be used with<read_iops_sec>or<write_iops_sec>.<read_iops_sec>- The read I/O operations per second.<write_iops_sec>- The write I/O operations per second.
23.17.1.6. Driver element
The optional
<driver> element allows specifying further details related to the hypervisor driver that is used to provide the disk. The following options may be used:
- If the hypervisor supports multiple back-end drivers, the
nameattribute selects the primary back-end driver name, while the optional type attribute provides the sub-type. - The optional
cacheattribute controls the cache mechanism. Possible values are:default,none,writethrough,writeback,directsync(similar towritethrough, but it bypasses the host physical machine page cache) andunsafe(host physical machine may cache all disk I/O, and sync requests from guest virtual machines are ignored). - The optional
error_policyattribute controls how the hypervisor behaves on a disk read or write error. Possible values arestop,report,ignore, andenospace. The default setting oferror_policyisreport. There is also an optionalrerror_policythat controls behavior for read errors only. If norerror_policyis given,error_policyis used for both read and write errors. Ifrerror_policyis given, it overrides theerror_policyfor read errors. Also note thatenospaceis not a valid policy for read errors, so iferror_policyis set toenospaceand norerror_policyis given, the read error default setting,reportwill be used. - The optional
ioattribute controls specific policies on I/O;kvmguest virtual machines supportthreadsandnative. The optionalioeventfdattribute allows users to set domain I/O asynchronous handling for virtio disk devices. The default is determined by the hypervisor. Accepted values areonandoff. Enabling this allows the guest virtual machine to be executed while a separate thread handles I/O. Typically, guest virtual machines experiencing high system CPU utilization during I/O will benefit from this. On the other hand, an overloaded host physical machine can increase guest virtual machine I/O latency. However, it is recommended that you do not change the default setting, and allow the hypervisor to determine the setting.Note
Theioeventfdattribute is included in the<driver>element of thediskXML section and also the<driver>element of thedeviceXML section. In the former case, it influences the virtIO disk, and in the latter case the SCSI disk. - The optional
event_idxattribute controls some aspects of device event processing and can be set to eitheronoroff. If set toon, it will reduce the number of interrupts and exits for the guest virtual machine. The default is determined by the hypervisor and the default setting ison. When this behavior is not required, settingoffforces the feature off. However, it is highly recommended that you not change the default setting, and allow the hypervisor to dictate the setting. - The optional
copy_on_readattribute controls whether to copy the read backing file into the image file. The accepted values can be eitheronor<off>.copy-on-readavoids accessing the same backing file sectors repeatedly, and is useful when the backing file is over a slow network. By defaultcopy-on-readisoff. - The
discard='unmap'can be set to enable discard support. The same line can be replaced withdiscard='ignore'to disable.discard='ignore'is the default setting.
23.17.1.7. Additional Device Elements
The following attributes may be used within the
device element:
<boot>- Specifies that the disk is bootable.Additional boot values
<order>- Determines the order in which devices will be tried during boot sequence.<per-device>Boot elements cannot be used together with general boot elements in the BIOS boot loader section.
<encryption>- Specifies how the volume is encrypted.<readonly>- Indicates the device cannot be modified by the guest virtual machine virtual machine. This setting is the default for disks withattribute<device='cdrom'>.<shareable>Indicates the device is expected to be shared between domains (as long as hypervisor and operating system support this). Ifshareableis used,cache='no'should be used for that device.<transient>- Indicates that changes to the device contents should be reverted automatically when the guest virtual machine exits. With some hypervisors, marking a disktransientprevents the domain from participating in migration or snapshots.<serial>- Specifies the serial number of guest virtual machine's hard drive. For example,<serial>WD-WMAP9A966149</serial>.<wwn>- Specifies the World Wide Name (WWN) of a virtual hard disk or CD-ROM drive. It must be composed of 16 hexadecimal digits.<vendor>- Specifies the vendor of a virtual hard disk or CD-ROM device. It must not be longer than 8 printable characters.<product>- Specifies the product of a virtual hard disk or CD-ROM device. It must not be longer than 16 printable characters<host>- Supports the following attributes:The meaning of this element and the number of the elements depend on thename- specifies the host nameport- specifies the port numbertransport- specifies the transport typesocket- specifies the path to the socket
protocolattribute as shown in Additional host attributes based on the protocolAdditional host attributes based on the protocol
nbd- Specifies a server runningnbd-serverand may only be used for only one host physical machine. The default port for this protcol is 10809.rbd- Monitors servers of RBD type and may be used for one or more host physical machines.sheepdog- Specifies one of thesheepdogservers (default is localhost:7000) and can be used with one or none of the host physical machines.gluster- Specifies a server running a glusterd daemon and may be used for only only one host physical machine. The valid values for transport attribute aretcp,rdmaorunix. If nothing is specified,tcpis assumed. If transport isunix, thesocketattribute specifies path tounixsocket.
<address>- Ties the disk to a given slot of a controller. The actual<controller>device can often be inferred but it can also be explicitly specified. Thetypeattribute is mandatory, and is typicallypciordrive. For apcicontroller, additional attributes forbus,slot, andfunctionmust be present, as well as optionaldomainandmultifunction.multifunctiondefaults tooff. For adrivecontroller, additional attributescontroller,bus,target, andunitare available, each with a default setting of0.auth- Provides the authentication credentials needed to access the source. It includes a mandatory attributeusername, which identifies the user name to use during authentication, as well as a sub-elementsecretwith mandatory attributetype.geometry- Provides the ability to override geometry settings. This mostly useful for S390 DASD-disks or older DOS-disks. It can have the following parameters:cyls- Specifies the number of cylinders.heads- Specifies the number of heads.secs- Specifies the number of sectors per track.trans- Specifies the BIOS-Translation-Modes and can have the following values:none,lbaorauto.
blockio- Allows the block device to be overridden with any of the block device properties listed below:blockio options
logical_block_size- Reports to the guest virtual machine operating system and describes the smallest units for disk I/O.physical_block_size- Reports to the guest virtual machine operating system and describes the disk's hardware sector size, which can be relevant for the alignment of disk data.
23.17.2. Device Addresses
Many devices have an optional
<address> sub-element to describe where the device placed on the virtual bus is presented to the guest virtual machine. If an address (or any optional attribute within an address) is omitted on input, libvirt will generate an appropriate address; but an explicit address is required if more control over layout is required. See below for device examples including an address element.
Every address has a mandatory attribute
type that describes which bus the device is on. The choice of which address to use for a given device is constrained in part by the device and the architecture of the guest virtual machine. For example, a disk device uses type='disk', while a console device would use type='pci' on the 32-bit AMD and Intel, or AMD64 and Intel 64, guest virtual machines, or type='spapr-vio' on PowerPC64 pseries guest virtual machines. Each address <type> has additional optional attributes that control where on the bus the device will be placed. The additional attributes are as follows:
type='pci'- PCI addresses have the following additional attributes:domain(a 2-byte hex integer, not currently used by KVM)bus(a hex value between 0 and 0xff, inclusive)slot(a hex value between 0x0 and 0x1f, inclusive)function(a value between 0 and 7, inclusive)- Also available is the
multi-functionattribute, which controls turning on the multi-function bit for a particular slot or function in the PCI control register. This multi-function attribute defaults to'off', but should be set to'on'for function 0 of a slot that will have multiple functions used.
type='drive'-driveaddresses have the following additional attributes:controller- (a 2-digit controller number)bus- (a 2-digit bus number)target- (a 2-digit bus number)unit- (a 2-digit unit number on the bus)
type='virtio-serial'- Eachvirtio-serialaddress has the following additional attributes:controller- (a 2-digit controller number)bus- (a 2-digit bus number)slot- (a 2-digit slot within the bus)
type='ccid'- A CCID address, used for smart-cards, has the following additional attributes:bus- (a 2-digit bus number)slot- (a 2-digit slot within the bus)
type='usb'- USB addresses have the following additional attributes:bus- (a hex value between 0 and 0xfff, inclusive)port- (a dotted notation of up to four octets, such as 1.2 or 2.1.3.1)
type='spapr-vio'- On PowerPC pseries guest virtual machines, devices can be assigned to the SPAPR-VIO bus. It has a flat 64-bit address space; by convention, devices are generally assigned at a non-zero multiple of 0x1000, but other addresses are valid and permitted bylibvirt. The additionalregattribute, which determines the hex value address of the starting register, can be assigned to this attribute.
23.17.3. Controllers
Depending on the guest virtual machine architecture, it is possible to assign many virtual devices to a single bus. Under normal circumstances libvirt can automatically infer which controller to use for the bus. However, it may be necessary to provide an explicit
<controller> element in the guest virtual machine XML:
...
<devices>
<controller type='ide' index='0'/>
<controller type='virtio-serial' index='0' ports='16' vectors='4'/>
<controller type='virtio-serial' index='1'>
<address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
<controller type='scsi' index='0' model='virtio-scsi' num_queues='8'/>
</controller>
...
</devices>
...
Figure 23.35. Controller Elements
Each controller has a mandatory attribute
type, which must be one of "ide", "fdc", "scsi", "sata", "usb", "ccid", or "virtio-serial", and a mandatory attribute index which is the decimal integer describing in which order the bus controller is encountered (for use in controller attributes of address elements). The "virtio-serial" controller has two additional optional attributes, ports and vectors, which control how many devices can be connected through the controller.
A
<controller type='scsi'> has an optional attribute model, which is one of "auto", "buslogic", "ibmvscsi", "lsilogic", "lsias1068", "virtio-scsi or "vmpvscsi". The <controller type='scsi'> also has an attribute num_queues which enables multi-queue support for the number of queues specified. In addition, a ioeventfd attribute can be used, which specifies whether the controller should use asynchronous handling on the SCSI disk. Accepted values are "on" and "off".
A
"usb" controller has an optional attribute model, which is one of "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3", "vt82c686b-uhci", "pci-ohci" or "nec-xhci". Additionally, if the USB bus needs to be explicitly disabled for the guest virtual machine, model='none' may be used. The PowerPC64 "spapr-vio" addresses do not have an associated controller.
For controllers that are themselves devices on a PCI or USB bus, an optional sub-element
address can specify the exact relationship of the controller to its master bus, with semantics given above.
USB companion controllers have an optional sub-element
master to specify the exact relationship of the companion to its master controller. A companion controller is on the same bus as its master, so the companion index value should be equal.
...
<devices>
<controller type='usb' index='0' model='ich9-ehci1'>
<address type='pci' domain='0' bus='0' slot='4' function='7'/>
</controller>
<controller type='usb' index='0' model='ich9-uhci1'>
<master startport='0'/>
<address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/>
</controller>
...
</devices>
...
Figure 23.36. Devices - controllers - USB
23.17.4. Device Leases
When using a lock manager, you have the option to record device leases against a guest virtual machine. The lock manager will ensure that the guest virtual machine does not start unless the leases can be acquired. When configured using conventional management tools, the following section of the domain XML is affected:
...
<devices>
...
<lease>
<lockspace>somearea</lockspace>
<key>somekey</key>
<target path='/some/lease/path' offset='1024'/>
</lease>
...
</devices>
...
Figure 23.37. Devices - device leases
The
lease section can have the following arguments:
lockspace- An arbitrary string that identifies lockspace within which the key is held. Lock managers may impose extra restrictions on the format, or length of the lockspace name.key- An arbitrary string that uniquely identifies the lease to be acquired. Lock managers may impose extra restrictions on the format, or length of the key.target- The fully qualified path of the file associated with the lockspace. The offset specifies where the lease is stored within the file. If the lock manager does not require a offset, set this value to0.
23.17.5. Host Physical Machine Device Assignment
23.17.5.1. USB / PCI devices
The host physical machine's USB and PCI devices can be passed through to the guest virtual machine using the
hostdev element, by modifying the host physical machine using a management tool, configure the following section of the domain XML file:
...
<devices>
<hostdev mode='subsystem' type='usb'>
<source startupPolicy='optional'>
<vendor id='0x1234'/>
<product id='0xbeef'/>
</source>
<boot order='2'/>
</hostdev>
</devices>
...
Figure 23.38. Devices - Host physical machine device assignment
Alternatively, the following can also be done:
...
<devices>
<hostdev mode='subsystem' type='pci' managed='yes'>
<source>
<address bus='0x06' slot='0x02' function='0x0'/>
</source>
<boot order='1'/>
<rom bar='on' file='/etc/fake/boot.bin'/>
</hostdev>
</devices>
...
Figure 23.39. Devices - Host physical machine device assignment alternative
Alternatively, the following can also be done:
...
<devices>
<hostdev mode='subsystem' type='scsi'>
<source>
<adapter name='scsi_host0'/>
<address type='scsi' bus='0' target='0' unit='0'/>
</source>
<readonly/>
<address type='drive' controller='0' bus='0' target='0' unit='0'/>
</hostdev>
</devices>
..
Figure 23.40. Devices - host physical machine scsi device assignment
The components of this section of the domain XML are as follows:
| Parameter | Description |
|---|---|
hostdev |
This is the main element for describing host physical machine devices. It accepts the following options:
|
source | Describes the device as seen from the host physical machine. The USB device can be addressed by vendor or product ID using the vendor and product elements or by the device's address on the host physical machines using the address element. PCI devices on the other hand can only be described by their address. Note that the source element of USB devices may contain a startupPolicy attribute which can be used to define a rule for what to do if the specified host physical machine USB device is not found. The attribute accepts the following values:
|
vendor, product | These elements each have an id attribute that specifies the USB vendor and product ID. The IDs can be given in decimal, hexadecimal (starting with 0x) or octal (starting with 0) form. |
boot | Specifies that the device is bootable. The attribute's order determines the order in which devices will be tried during boot sequence. The per-device boot elements cannot be used together with general boot elements in BIOS boot loader section. |
rom | Used to change how a PCI device's ROM is presented to the guest virtual machine. 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 virtual machine's memory map. (In PCI documentation, the rom bar setting controls the presence of the Base Address Register for the ROM). If no rom bar is specified, the default setting will be used. The optional file attribute is used to point to a binary file to be presented to the guest virtual machine as the device's ROM BIOS. This can be useful for example to provide a PXE boot ROM for a virtual function of an SR-IOV capable ethernet device (which has no boot ROMs for the VFs). |
address | Also has a bus and device attribute to specify the USB bus and device number the device appears at on the host physical machine. The values of these attributes can be given in decimal, hexadecimal (starting with 0x) or octal (starting with 0) form. For PCI devices, the element carries 3 attributes allowing to designate the device as can be found with lspci or with virsh nodedev-list. |
23.17.5.2. Block / character devices
The host physical machine's block / character devices can be passed through to the guest virtual machine by using management tools to modify the domain XML
hostdev element. Note that this is only possible with container-based virtualization.
...
<hostdev mode='capabilities' type='storage'>
<source>
<block>/dev/sdf1</block>
</source>
</hostdev>
...
Figure 23.41. Devices - Host physical machine device assignment block character devices
An alternative approach is this:
...
<hostdev mode='capabilities' type='misc'>
<source>
<char>/dev/input/event3</char>
</source>
</hostdev>
...
Figure 23.42. Devices - Host physical machine device assignment block character devices alternative 1
Another alternative approach is this:
...
<hostdev mode='capabilities' type='net'>
<source>
<interface>eth0</interface>
</source>
</hostdev>
...
Figure 23.43. Devices - Host physical machine device assignment block character devices alternative 2
The components of this section of the domain XML are as follows:
| Parameter | Description |
|---|---|
hostdev | This is the main container for describing host physical machine devices. For block/character devices, passthrough mode is always capabilities, and type is block for a block device and char for a character device. |
source | This describes the device as seen from the host physical machine. For block devices, the path to the block device in the host physical machine operating system is provided in the nested block element, while for character devices, the char element is used. |
23.17.6. Redirected devices
USB device redirection through a character device is configured by modifying the following section of the domain XML:
...
<devices>
<redirdev bus='usb' type='tcp'>
<source mode='connect' host='localhost' service='4000'/>
<boot order='1'/>
</redirdev>
<redirfilter>
<usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.00' allow='yes'/>
<usbdev allow='no'/>
</redirfilter>
</devices>
...
Figure 23.44. Devices - redirected devices
The components of this section of the domain XML are as follows:
| Parameter | Description |
|---|---|
redirdev | This is the main container for describing redirected devices. bus must be usb for a USB device. An additional attribute type is required, matching one of the supported serial device types, to describe the host physical machine side of the tunnel: type='tcp' or type='spicevmc' (which uses the usbredir channel of a SPICE graphics device) are typical. The redirdev element has an optional sub-element, address, which can tie the device to a particular controller. Further sub-elements, such as source, may be required according to the given type, although a target sub-element is not required (since the consumer of the character device is the hypervisor itself, rather than a device visible in the guest virtual machine). |
boot | Specifies that the device is bootable. The order attribute determines the order in which devices will be tried during boot sequence. The per-device boot elements cannot be used together with general boot elements in BIOS boot loader section. |
redirfilter | This is used for creating the filter rule to filter out certain devices from redirection. It uses sub-element usbdev to define each filter rule. The class attribute is the USB Class code. |
23.17.7. Smartcard Devices
A virtual smartcard device can be supplied to the guest virtual machine via the
smartcard element. A USB smartcard reader device on the host physical machine cannot be used on a guest virtual machine with device passthrough. This is because it cannot be made available to both the host physical machine and guest virtual machine, and can lock the host physical machine computer when it is removed from the guest virtual machine. Therefore, some hypervisors provide a specialized virtual device that can present a smartcard interface to the guest virtual machine, with several modes for describing how the credentials are obtained from the host physical machine or even a from a channel created to a third-party smartcard provider.
Configure USB device redirection through a character device with management tools to modify the following section of the domain XML:
...
<devices>
<smartcard mode='host'/>
<smartcard mode='host-certificates'>
<certificate>cert1</certificate>
<certificate>cert2</certificate>
<certificate>cert3</certificate>
<database>/etc/pki/nssdb/</database>
</smartcard>
<smartcard mode='passthrough' type='tcp'>
<source mode='bind' host='127.0.0.1' service='2001'/>
<protocol type='raw'/>
<address type='ccid' controller='0' slot='0'/>
</smartcard>
<smartcard mode='passthrough' type='spicevmc'/>
</devices>
...
Figure 23.45. Devices - smartcard devices
The
smartcard element has a mandatory attribute mode. In each mode, the guest virtual machine sees a device on its USB bus that behaves like a physical USB CCID (Chip/Smart Card Interface Device) card.
The mode attributes are as follows:
| Parameter | Description |
|---|---|
mode='host' | In this mode, the hypervisor relays all requests from the guest virtual machine into direct access to the host physical machine's smartcard via NSS. No other attributes or sub-elements are required. See below about the use of an optional address sub-element. |
mode='host-certificates' | This mode allows you to provide three NSS certificate names residing in a database on the host physical machine, rather than requiring a smartcard to be plugged into the host physical machine. These certificates can be generated using the command certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=cert1 -n cert1, and the resulting three certificate names must be supplied as the content of each of three certificate sub-elements. An additional sub-element database can specify the absolute path to an alternate directory (matching the -d flag of the certutil command when creating the certificates); if not present, it defaults to /etc/pki/nssdb. |
mode='passthrough' | Using this mode allows you to tunnel all requests through a secondary character device to a third-party provider (which may in turn be communicating to a smartcard or using three certificate files, rather than having the hypervisor directly communicate with the host physical machine. In this mode of operation, an additional attribute type is required, matching one of the supported serial device types, to describe the host physical machine side of the tunnel; type='tcp' or type='spicevmc' (which uses the smartcard channel of a SPICE graphics device) are typical. Further sub-elements, such as source, may be required according to the given type, although a target sub-element is not required (since the consumer of the character device is the hypervisor itself, rather than a device visible in the guest virtual machine). |
Each mode supports an optional sub-element
address, which fine-tunes the correlation between the smartcard and a ccid bus controller. For more information, see Section 23.17.2, “Device Addresses”).
23.17.8. Network Interfaces
Modify the network interface devices using management tools to configure the following part of the domain XML:
...
<devices>
<interface type='direct' trustGuestRxFilters='yes'>
<source dev='eth0'/>
<mac address='52:54:00:5d:c7:9e'/>
<boot order='1'/>
<rom bar='off'/>
</interface>
</devices>
...
Figure 23.46. Devices - network interfaces
There are several possibilities for configuring the network interface for the guest virtual machine. This is done by setting a value to the interface element's type attribute. The following values may be used:
"direct"- Attaches the guest virtual machine's NIC to the physical NIC on the host physical machine. For details and an example, see Section 23.17.8.6, “Direct attachment to physical interfaces”."network"- This is the recommended configuration for general guest virtual machine connectivity on host physical machines with dynamic or wireless networking configurations. For details and an example, see Section 23.17.8.1, “Virtual networks”."bridge"- This is the recommended configuration setting for guest virtual machine connectivity on host physical machines with static wired networking configurations. For details and an example, see Section 23.17.8.2, “Bridge to LAN”."ethernet"- Provides a means for the administrator to execute an arbitrary script to connect the guest virtual machine's network to the LAN. For details and an example, see Section 23.17.8.5, “Generic Ethernet connection”."hostdev"- Allows a PCI network device to be directly assigned to the guest virtual machine using generic device passthrough. For details and an example, see Section 23.17.8.7, “PCI passthrough”."mcast"- A multicast group can be used to represent a virtual network. For details and an example, see Section 23.17.8.8, “Multicast tunnel” ."user"- Using the user option sets the user space SLIRP stack parameters provides a virtual LAN with NAT to the outside world. For details and an example, see Section 23.17.8.4, “User space SLIRP stack”."server"- Using the server option creates a TCP client-server architecture in order to provide a virtual network where one guest virtual machine provides the server end of the network and all other guest virtual machines are configured as clients. For details and an example, see Section 23.17.8.9, “TCP tunnel”.
Each of these options has a link to give more details. Additionally, each
<interface> element can be defined with an optional <trustGuestRxFilters> attribute which allows host physical machine to detect and trust reports received from the guest virtual machine. These reports are sent each time the interface receives changes to the filter. This includes changes to the primary MAC address, the device address filter, or the vlan configuration. The <trustGuestRxFilters> attribute is disabled by default for security reasons. It should also be noted that support for this attribute depends on the guest network device model as well as on the host physical machine's connection type. Currently, it is only supported for the virtio device models and for macvtap connections on the host physical machine. A simple use case where it is recommended to set the optional parameter <trustGuestRxFilters> is if you want to give your guest virtual machines the permission to control host physical machine side filters, as any filters that are set by the guest will also be mirrored on the host.
In addition to the attributes listed above, each
<interface> element can take an optional <address> sub-element that can tie the interface to a particular PCI slot, with attribute type='pci'. For more information, see Section 23.17.2, “Device Addresses”.
23.17.8.1. Virtual networks
This is the recommended configuration for general guest virtual machine connectivity on host physical machines with dynamic or wireless networking configurations (or multi-host physical machine environments where the host physical machine hardware details, which are described separately in a
<network> definition). In addition, it provides a connection with details that are described by the named network definition. Depending on the virtual network's forward mode configuration, the network may be totally isolated (no <forward> element given), using NAT to connect to an explicit network device or to the default route (forward mode='nat'), routed with no NAT (forward mode='route'), or connected directly to one of the host physical machine's network interfaces (using macvtap) or bridge devices (forward mode='bridge|private|vepa|passthrough')
For networks with a forward mode of
bridge, private, vepa, and passthrough, it is assumed that the host physical machine has any necessary DNS and DHCP services already set up outside the scope of libvirt. In the case of isolated, nat, and routed networks, DHCP and DNS are provided on the virtual network by libvirt, and the IP range can be determined by examining the virtual network configuration with virsh net-dumpxml [networkname]. The 'default' virtual network, which is set up out of the box, uses NAT to connect to the default route and has an IP range of 192.168.122.0/255.255.255.0. Each guest virtual machine will have an associated tun device created with a name of vnetN, which can also be overridden with the <target> element (refer to Section 23.17.8.11, “Overriding the target element”).
When the source of an interface is a network, a port group can be specified along with the name of the network; one network may have multiple portgroups defined, with each portgroup containing slightly different configuration information for different classes of network connections. Also, similar to
<direct> network connections (described below), a connection of type network may specify a <virtualport> element, with configuration data to be forwarded to a 802.1Qbg or 802.1Qbh-compliant Virtual Ethernet Port Aggregator (VEPA)switch, or to an Open vSwitch virtual switch.
Since the type of switch is dependent on the configuration setting in the
<network> element on the host physical machine, it is acceptable to omit the <virtualport type> attribute. You will need to specify the <virtualport type> either once or many times. When the domain starts up a complete <virtualport> element is constructed by merging together the type and attributes defined. This results in a newly-constructed virtual port. Note that the attributes from lower virtual ports cannot make changes on the attributes defined in higher virtual ports. Interfaces take the highest priority, while port group is lowest priority.
For example, to create a properly working network with both an 802.1Qbh switch and an Open vSwitch switch, you may choose to specify no type, but both
profileid and an interfaceid must be supplied. The other attributes to be filled in from the virtual port, such as such as managerid, typeid, or profileid, are optional.
If you want to limit a guest virtual machine to connecting only to certain types of switches, you can specify the virtualport type, and only switches with the specified port type will connect. You can also further limit switch connectivity by specifying additional parameters. As a result, if the port was specified and the host physical machine's network has a different type of virtualport, the connection of the interface will fail. The virtual network parameters are defined using management tools that modify the following part of the domain XML:
...
<devices>
<interface type='network'>
<source network='default'/>
</interface>
...
<interface type='network'>
<source network='default' portgroup='engineering'/>
<target dev='vnet7'/>
<mac address="00:11:22:33:44:55"/>
<virtualport>
<parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
</virtualport>
</interface>
</devices>
...
Figure 23.47. Devices - network interfaces- virtual networks
23.17.8.2. Bridge to LAN
As mentioned in, Section 23.17.8, “Network Interfaces”, this is the recommended configuration setting for guest virtual machine connectivity on host physical machines with static wired networking configurations.
Bridge to LAN provides a bridge from the guest virtual machine directly onto the LAN. This assumes there is a bridge device on the host physical machine which has one or more of the host physical machines physical NICs enslaved. The guest virtual machine will have an associated
tun device created with a name of <vnetN>, which can also be overridden with the <target> element (refer to Section 23.17.8.11, “Overriding the target element”). The <tun> device will be enslaved to the bridge. The IP range or network configuration is the same as what is used on the LAN. This provides the guest virtual machine full incoming and outgoing network access, just like a physical machine.
On Linux systems, the bridge device is normally a standard Linux host physical machine bridge. On host physical machines that support Open vSwitch, it is also possible to connect to an Open vSwitch bridge device by adding
virtualport type='openvswitch'/ to the interface definition. The Open vSwitch type virtualport accepts two parameters in its parameters element: an interfaceid which is a standard UUID used to uniquely identify this particular interface to Open vSwitch (if you do no specify one, a random interfaceid will be generated when first defining the interface), and an optional profileid which is sent to Open vSwitch as the interfaces <port-profile>. To set the bridge to LAN settings, use a management tool that will configure the following part of the domain XML:
...
<devices>
...
<interface type='bridge'>
<source bridge='br0'/>
</interface>
<interface type='bridge'>
<source bridge='br1'/>
<target dev='vnet7'/>
<mac address="00:11:22:33:44:55"/>
</interface>
<interface type='bridge'>
<source bridge='ovsbr'/>
<virtualport type='openvswitch'>
<parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
</virtualport>
</interface>
...
</devices>
Figure 23.48. Devices - network interfaces- bridge to LAN
23.17.8.3. Setting a port masquerading range
In cases where you want to set the port masquerading range, set the port as follows:
<forward mode='nat'> <address start='1.2.3.4' end='1.2.3.10'/> </forward> ...
Figure 23.49. Port Masquerading Range
These values should be set using the
iptables commands as shown in Section 17.3, “Network Address Translation”
23.17.8.4. User space SLIRP stack
Setting the user space SLIRP stack parameters provides a virtual LAN with NAT to the outside world. The virtual network has DHCP and DNS services and will give the guest virtual machine an IP addresses starting from 10.0.2.15. The default router is 10.0.2.2 and the DNS server is 10.0.2.3. This networking is the only option for unprivileged users who need their guest virtual machines to have outgoing access.
The user space SLIRP stack parameters are defined in the following part of the domain XML:
...
<devices>
<interface type='user'/>
...
<interface type='user'>
<mac address="00:11:22:33:44:55"/>
</interface>
</devices>
...
Figure 23.50. Devices - network interfaces- User space SLIRP stack
23.17.8.5. Generic Ethernet connection
This provides a means for the administrator to execute an arbitrary script to connect the guest virtual machine's network to the LAN. The guest virtual machine will have a
<tun> device created with a name of vnetN, which can also be overridden with the <target> element. After creating the tun device a shell script will be run and complete the required host physical machine network integration. By default, this script is called /etc/qemu-ifup but can be overridden (refer to Section 23.17.8.11, “Overriding the target element”).
The generic ethernet connection parameters are defined in the following part of the domain XML:
...
<devices>
<interface type='ethernet'/>
...
<interface type='ethernet'>
<target dev='vnet7'/>
<script path='/etc/qemu-ifup-mynet'/>
</interface>
</devices>
...
Figure 23.51. Devices - network interfaces- generic ethernet connection
23.17.8.6. Direct attachment to physical interfaces
This directly attaches the guest virtual machine's NIC to the physical interface of the host physical machine, if the physical interface is specified.
This requires the Linux macvtap driver to be available. One of the following
mode attribute values vepa ( 'Virtual Ethernet Port Aggregator'), bridge or private can be chosen for the operation mode of the macvtap device. vepa is the default mode.
Manipulating direct attachment to physical interfaces involves setting the following parameters in this section of the domain XML:
...
<devices>
...
<interface type='direct'>
<source dev='eth0' mode='vepa'/>
</interface>
</devices>
...
Figure 23.52. Devices - network interfaces- direct attachment to physical interfaces
The individual modes cause the delivery of packets to behave as shown in Table 23.20, “Direct attachment to physical interface elements”:
| Element | Description |
|---|---|
vepa | All of the guest virtual machines' packets are sent to the external bridge. Packets whose destination is a guest virtual machine on the same host physical machine as where the packet originates from are sent back to the host physical machine by the VEPA capable bridge (today's bridges are typically not VEPA capable). |
bridge | Packets whose destination is on the same host physical machine as where they originate from are directly delivered to the target macvtap device. Both origin and destination devices need to be in bridge mode for direct delivery. If either one of them is in vepa mode, a VEPA capable bridge is required. |
private | All packets are sent to the external bridge and will only be delivered to a target virtual machine on the same host physical machine if they are sent through an external router or gateway and that device sends them back to the host physical machine. This procedure is followed if either the source or destination device is in private mode. |
passthrough | This feature attaches a virtual function of a SR-IOV capable NIC directly to a guest virtual machine without losing the migration capability. All packets are sent to the VF/IF of the configured network device. Depending on the capabilities of the device, additional prerequisites or limitations may apply; for example, this requires kernel 2.6.38 or later. |
The network access of directly attached virtual machines can be managed by the hardware switch to which the physical interface of the host physical machine is connected to.
The interface can have additional parameters as shown below, if the switch conforms to the IEEE 802.1Qbg standard. The parameters of the virtualport element are documented in more detail in the IEEE 802.1Qbg standard. The values are network specific and should be provided by the network administrator. In 802.1Qbg terms, the Virtual Station Interface (VSI) represents the virtual interface of a virtual machine.
Note that IEEE 802.1Qbg requires a non-zero value for the VLAN ID.
Additional elements that can be manipulated are described in Table 23.21, “Direct attachment to physical interface additional elements”:
| Element | Description |
|---|---|
managerid | The VSI Manager ID identifies the database containing the VSI type and instance definitions. This is an integer value and the value 0 is reserved. |
typeid | The VSI Type ID identifies a VSI type characterizing the network access. VSI types are typically managed by network administrator. This is an integer value. |
typeidversion | The VSI Type Version allows multiple versions of a VSI Type. This is an integer value. |
instanceid | The VSI Instance ID Identifier is generated when a VSI instance (a virtual interface of a virtual machine) is created. This is a globally unique identifier. |
profileid | The profile ID contains the name of the port profile that is to be applied onto this interface. This name is resolved by the port profile database into the network parameters from the port profile, and those network parameters will be applied to this interface. |
Additional parameters in the domain XML include:
...
<devices>
...
<interface type='direct'>
<source dev='eth0.2' mode='vepa'/>
<virtualport type="802.1Qbg">
<parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
</virtualport>
</interface>
</devices>
...
Figure 23.53. Devices - network interfaces- direct attachment to physical interfaces additional parameters
The interface can have additional parameters as shown below if the switch conforms to the IEEE 802.1Qbh standard. The values are network specific and should be provided by the network administrator.
Additional parameters in the domain XML include:
...
<devices>
...
<interface type='direct'>
<source dev='eth0' mode='private'/>
<virtualport type='802.1Qbh'>
<parameters profileid='finance'/>
</virtualport>
</interface>
</devices>
...
Figure 23.54. Devices - network interfaces - direct attachment to physical interfaces more additional parameters
The
profileid attribute contains the name of the port profile to be applied to this interface. This name is resolved by the port profile database into the network parameters from the port profile, and those network parameters will be applied to this interface.
23.17.8.7. PCI passthrough
A PCI network device (specified by the
source element) is directly assigned to the guest virtual machine using generic device passthrough, after first optionally setting the device's MAC address to the configured value, and associating the device with an 802.1Qbh capable switch using an optionally specified virtualport element (see the examples of virtualport given above for type='direct' network devices). Note that due to limitations in standard single-port PCI ethernet card driver design, only SR-IOV (Single Root I/O Virtualization) virtual function (VF) devices can be assigned in this manner. To assign a standard single-port PCI or PCIe ethernet card to a guest virtual machine, use the traditional hostdev device definition.
Note that this "intelligent passthrough" of network devices is very similar to the functionality of a standard
hostdev device, the difference being that this method allows specifying a MAC address and virtualport for the passed-through device. If these capabilities are not required, if you have a standard single-port PCI, PCIe, or USB network card that does not support SR-IOV (and hence would anyway lose the configured MAC address during reset after being assigned to the guest virtual machine domain), or if you are using libvirt version older than 0.9.11, use standard hostdev definition to assign the device to the guest virtual machine instead of interface type='hostdev'.
...
<devices>
<interface type='hostdev'>
<driver name='vfio'/>
<source>
<address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
</source>
<mac address='52:54:00:6d:90:02'>
<virtualport type='802.1Qbh'>
<parameters profileid='finance'/>
</virtualport>
</interface>
</devices>
...
Figure 23.55. Devices - network interfaces- PCI passthrough
23.17.8.8. Multicast tunnel
A multicast group can be used to represent a virtual network. Any guest virtual machine with network devices within the same multicast group will communicate with each other, even if they reside across multiple physical host physical machines. This mode may be used as an unprivileged user. There is no default DNS or DHCP support and no outgoing network access. To provide outgoing network access, one of the guest virtual machines should have a second NIC which is connected to one of the first 4 network types in order to provide appropriate routing. The multicast protocol is compatible with protocols used by
user mode Linux guest virtual machines as well. Note that the source address used must be from the multicast address block. A multicast tunnel is created by manipulating the interface type using a management tool and setting it to mcast, and providing a mac address and source address, for example:
...
<devices>
<interface type='mcast'>
<mac address='52:54:00:6d:90:01'>
<source address='230.0.0.1' port='5558'/>
</interface>
</devices>
...
Figure 23.56. Devices - network interfaces- multicast tunnel
23.17.8.9. TCP tunnel
Creating a TCP client-server architecture is another way to provide a virtual network where one guest virtual machine provides the server end of the network and all other guest virtual machines are configured as clients. All network traffic between the guest virtual machines is routed through the guest virtual machine that is configured as the server. This model is also available for use to unprivileged users. There is no default DNS or DHCP support and no outgoing network access. To provide outgoing network access, one of the guest virtual machines should have a second NIC which is connected to one of the first 4 network types thereby providing the appropriate routing. A TCP tunnel is created by manipulating the
interface type using a management tool and setting it to mcast, and providing a mac address and source address, for example:
...
<devices>
<interface type='server'>
<mac address='52:54:00:22:c9:42'>
<source address='192.168.0.1' port='5558'/>
</interface>
...
<interface type='client'>
<mac address='52:54:00:8b:c9:51'>
<source address='192.168.0.1' port='5558'/>
</interface>
</devices>
...
Figure 23.57. Devices - network interfaces- TCP tunnel
23.17.8.10. Setting NIC driver-specific options
Some NICs may have tunable driver-specific options. These options are set as attributes of the
driver sub-element of the interface definition. These options are set by using management tools to configure the following sections of the domain XML:
<devices>
<interface type='network'>
<source network='default'/>
<target dev='vnet1'/>
<model type='virtio'/>
<driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off'/>
</interface>
</devices>
...
Figure 23.58. Devices - network interfaces- setting NIC driver-specific options
The following attributes are available for the "virtio" NIC driver:
| Parameter | Description |
|---|---|
name | The optional name attribute forces which type of back-end driver to use. The value can be either kvm (a user-space back-end) or vhost (a kernel back-end, which requires the vhost module to be provided by the kernel); an attempt to require the vhost driver without kernel support will be rejected. The default setting is vhost if the vhost driver is present, but will silently fall back to kvm if not. |
txmode | Specifies how to handle transmission of packets when the transmit buffer is full. The value can be either iothread or timer. If set to iothread, packet tx is all done in an iothread in the bottom half of the driver (this option translates into adding "tx=bh" to the kvm command-line "-device" virtio-net-pci option). If set to timer, tx work is done in KVM, and if there is more tx data than can be sent at the present time, a timer is set before KVM moves on to do other things; when the timer fires, another attempt is made to send more data. It is not recommended to change this value. |
ioeventfd | Sets domain I/O asynchronous handling for the interface device. The default is left to the discretion of the hypervisor. Accepted values are on and off. Enabling this option allows KVM to execute a guest virtual machine while a separate thread handles I/O. Typically, guest virtual machines experiencing high system CPU utilization during I/O will benefit from this. On the other hand, overloading the physical host machine may also increase guest virtual machine I/O latency. It is not recommended to change this value. |
event_idx | The event_idx attribute controls some aspects of device event processing. The value can be either on or off. on is the default, which reduces the number of interrupts and exits for the guest virtual machine. In situations where this behavior is sub-optimal, this attribute provides a way to force the feature off. It is not recommended to change this value. |
23.17.8.11. Overriding the target element
To override the target element, use a management tool to make the following changes to the domain XML:
...
<devices>
<interface type='network'>
<source network='default'/>
<target dev='vnet1'/>
</interface>
</devices>
...
Figure 23.59. Devices - network interfaces- overriding the target element
If no target is specified, certain hypervisors will automatically generate a name for the created tun device. This name can be manually specified, however the name must not start with either
vnet or vif, which are prefixes reserved by libvirt and certain hypervisors. Manually-specified targets using these prefixes will be ignored.
23.17.8.12. Specifying boot order
To specify the boot order, use a management tool to make the following changes to the domain XML:
...
<devices>
<interface type='network'>
<source network='default'/>
<target dev='vnet1'/>
<boot order='1'/>
</interface>
</devices>
...Figure 23.60. Specifying boot order
In hypervisors which support it, you can set a specific NIC to be used for the network boot. The order of attributes determine the order in which devices will be tried during boot sequence. Note that the per-device boot elements cannot be used together with general boot elements in BIOS boot loader section.
23.17.8.13. Interface ROM BIOS configuration
To specify the ROM BIOS configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<interface type='network'>
<source network='default'/>
<target dev='vnet1'/>
<rom bar='on' file='/etc/fake/boot.bin'/>
</interface>
</devices>
...Figure 23.61. Interface ROM BIOS configuration
For hypervisors that support it, you can change how a PCI Network device's ROM is presented to the guest virtual machine. The
bar attribute can be set to on or off, and determines whether or not the device's ROM will be visible in the guest virtual machine's memory map. (In PCI documentation, the rom bar setting controls the presence of the Base Address Register for the ROM). If no rom baris specified, the KVM default will be used (older versions of KVM used off for the default, while newer KVM hypervisors default to on). The optional file attribute is used to point to a binary file to be presented to the guest virtual machine as the device's ROM BIOS. This can be useful to provide an alternative boot ROM for a network device.
23.17.8.14. Quality of service (QoS)
Incoming and outgoing traffic can be shaped independently to set Quality of Service (QoS). The
bandwidth element can have at most one inbound and one outbound child elements. Leaving any of these child elements out results in no QoS being applied on that traffic direction. Therefore, to shape only a domain's incoming traffic, use inbound only, and vice versa.
Each of these elements has one mandatory attribute
average (or floor as described below). Average specifies the average bit rate on the interface being shaped. In addition, there are two optional attributes:
peak- This attribute specifies the maximum rate at which the bridge can send data, in kilobytes a second. A limitation of this implementation is this attribute in the outbound element is ignored, as Linux ingress filters do not know it yet.burst- Specifies the amount of bytes that can be burst at peak speed. Accepted values for attributes are integer numbers.
The units for
average and peak attributes are kilobytes per second, whereas burst is only set in kilobytes. In addition, inbound traffic can optionally have a floor attribute. This guarantees minimal throughput for shaped interfaces. Using the floor requires that all traffic goes through one point where QoS decisions can take place. As such, it may only be used in cases where the interface type='network'/ with a forward type of route, nat, or no forward at all). Noted that within a virtual network, all connected interfaces are required to have at least the inbound QoS set (average at least) but the floor attribute does not require specifying average. However, peak and burst attributes still require average. At the present time, ingress qdiscs may not have any classes, and therefore, floor may only be applied only on inbound and not outbound traffic.
To specify the QoS configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<interface type='network'>
<source network='default'/>
<target dev='vnet0'/>
<bandwidth>
<inbound average='1000' peak='5000' floor='200' burst='1024'/>
<outbound average='128' peak='256' burst='256'/>
</bandwidth>
</interface>
<devices>
...Figure 23.62. Quality of service
23.17.8.15. Setting VLAN tag (on supported network types only)
To specify the VLAN tag configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<interface type='bridge'>
<vlan>
<tag id='42'/>
</vlan>
<source bridge='ovsbr0'/>
<virtualport type='openvswitch'>
<parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
</virtualport>
</interface>
<devices>
...
Figure 23.63. Setting VLAN tag (on supported network types only)
If the network connection used by the guest virtual machine supports VLAN tagging transparent to the guest virtual machine, an optional
vlan element can specify one or more VLAN tags to apply to the guest virtual machine's network traffic. Only OpenvSwitch and type='hostdev' SR-IOV interfaces support transparent VLAN tagging of guest virtual machine traffic; other interfaces, including standard Linux bridges and libvirt's own virtual networks, do not support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches provide their own methods (outside of libvirt) to tag guest virtual machine traffic onto specific VLANs. To allow for specification of multiple tags (in the case of VLAN trunking), the tag subelement specifies which VLAN tag to use (for example, tag id='42'/). If an interface has more than one vlan element defined, it is assumed that the user wants to do VLAN trunking using all the specified tags. If VLAN trunking with a single tag is needed, the optional attribute trunk='yes' can be added to the top-level vlan element.
23.17.8.16. Modifying virtual link state
This element sets the virtual network link state. Possible values for attribute
state are up and down. If down is specified as the value, the interface behaves as the network cable is disconnected. Default behavior if this element is unspecified is up.
To specify the virtual link state configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<interface type='network'>
<source network='default'/>
<target dev='vnet0'/>
<link state='down'/>
</interface>
<devices>
...Figure 23.64. Modifying virtual link state
23.17.9. Input Devices
Input devices allow interaction with the graphical framebuffer in the guest virtual machine. When enabling the framebuffer, an input device is automatically provided. It may be possible to add additional devices explicitly, for example to provide a graphics tablet for absolute cursor movement.
To specify the input device configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<input type='mouse' bus='usb'/>
</devices>
...
Figure 23.65. Input devices
The
<input> element has one mandatory attribute: type, which can be set to mouse or tablet. tablet provides absolute cursor movement, while mouse uses relative movement. The optional bus attribute can be used to refine the exact device type and can be set to kvm (paravirtualized), ps2, and usb.
The input element has an optional sub-element
<address>, which can tie the device to a particular PCI slot, as documented above.
23.17.10. Hub Devices
A hub is a device that expands a single port into several so that there are more ports available to connect devices to a host physical machine system.
To specify the hub device configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<hub type='usb'/>
</devices>
...Figure 23.66. Hub devices
The
hub element has one mandatory attribute, type, which can only be set to usb. The hub element has an optional sub-element, address, with type='usb', which can tie the device to a particular controller.
23.17.11. Graphical Framebuffers
A graphics device allows for graphical interaction with the guest virtual machine operating system. A guest virtual machine will typically have either a framebuffer or a text console configured to allow interaction with the user.
To specify the graphical framebuffer device configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<graphics type='sdl' display=':0.0'/>
<graphics type='vnc' port='5904'>
<listen type='address' address='1.2.3.4'/>
</graphics>
<graphics type='rdp' autoport='yes' multiUser='yes' />
<graphics type='desktop' fullscreen='yes'/>
<graphics type='spice'>
<listen type='network' network='rednet'/>
</graphics>
</devices>
...Figure 23.67. Graphical framebuffers
The
graphics element has a mandatory type attribute, which takes the value sdl, vnc, rdp, desktop or spice, as explained in the tables below:
| Parameter | Description |
|---|---|
sdl | This displays a window on the host physical machine desktop. It accepts the following optional arguments:
|
vnc | Starts a VNC server.
|
spice | Starts a SPICE server.
|
When SPICE has both a normal and a TLS-secured TCP port configured, it may be desirable to restrict what channels can be run on each port. To do this, add one or more
channel elements inside the main graphics element. Valid channel names include main, display, inputs, cursor, playback, record, smartcard, and usbredir.
To specify the SPICE configuration settings, use a mangement tool to make the following changes to the domain XML:
<graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
<channel name='main' mode='secure'/>
<channel name='record' mode='insecure'/>
<image compression='auto_glz'/>
<streaming mode='filter'/>
<clipboard copypaste='no'/>
<mouse mode='client'/>
</graphics>Figure 23.68. Sample SPICE configuration
SPICE supports variable compression settings for audio, images and streaming. These settings are configured using the
compression attribute in the following elements:
imageto set image compression (acceptsauto_glz,auto_lz,quic,glz,lz,off)jpegfor JPEG compression for images over WAN (acceptsauto,never,always)zlibfor configuring WAN image compression (acceptsauto,never,always) andplaybackfor enabling audio stream compression (acceptsonoroff)
The
streaming element sets streaming mode. The mode attribute can be set to filter, all or off.
In addition, copy and paste functionality (through the SPICE agent) is set by the
clipboard element. It is enabled by default, and can be disabled by setting the copypaste property to no.
The
mouse element sets mouse mode. The mode attribute can be set to server or client. If no mode is specified, the KVM default will be used (client mode).
Additional elements include:
| Parameter | Description |
|---|---|
rdp | Starts an RDP server.
|
desktop | This value is currently reserved for VirtualBox domains. It displays a window on the host physical machine desktop, similarly to sdl, but uses the VirtualBox viewer. Just like sdl, it accepts the optional attributes display and fullscreen. |
listen | Rather than inputting the address information used to set up the listening socket for graphics types vnc and spice, the listen attribute, a separate sub-element of graphics, can be specified (see the examples above). listen accepts the following attributes:
|
23.17.12. Video Devices
To specify the video device configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<video>
<model type='vga' vram='8192' heads='1'>
<acceleration accel3d='yes' accel2d='yes'/>
</model>
</video>
</devices>
...Figure 23.69. Video devices
The
graphics element has a mandatory type attribute which takes the value "sdl", "vnc", "rdp" or "desktop" as explained below:
| Parameter | Description |
|---|---|
video | The video element is the container for describing video devices. For backwards compatibility, if no video is set but there is a graphics element in the domain XML, then libvirt will add a default video according to the guest virtual machine type. If "ram" or "vram" are not supplied, a default value is used. |
model | This has a mandatory type attribute which takes the value vga, cirrus, vmvga, kvm, vbox, or qxl depending on the hypervisor features available. You can also provide the amount of video memory in kibibytes (blocks of 1024 bytes) using vram and the number of figure with heads. |
| acceleration | If acceleration is supported it should be enabled using the accel3d and accel2d attributes in the acceleration element. |
address | The optional address sub-element can be used to tie the video device to a particular PCI slot. |
23.17.13. Consoles, Serial, and Channel Devices
A character device provides a way to interact with the virtual machine. Paravirtualized consoles, serial ports, and channels are all classed as character devices and are represented using the same syntax.
To specify the consoles, channel and other device configuration settings, use a management tool to make the following changes to the domain XML:
...
<devices>
<serial type='pty'>
<source path='/dev/pts/3'/>
<target port='0'/>
</serial>
<console type='pty'>
<source path='/dev/pts/4'/>
<target port='0'/>
</console>
<channel type='unix'>
<source mode='bind' path='/tmp/guestfwd'/>
<target type='guestfwd' address='10.0.2.1' port='4600'/>
</channel>
</devices>
...Figure 23.70. Consoles, serial, and channel devices
In each of these directives, the top-level element name (
serial, console, channel) describes how the device is presented to the guest virtual machine. The guest virtual machine interface is configured by the target element. The interface presented to the host physical machine is given in the type attribute of the top-level element. The host physical machine interface is configured by the source element. The source element may contain an optional seclabel to override the way that labeling is done on the socket path. If this element is not present, the security label is inherited from the per-domain setting. Each character device element has an optional sub-element address which can tie the device to a particular controller or PCI slot.
Note
Parallel ports, as well as the
isa-parallel device, are no longer supported.
23.17.14. Guest Virtual Machine Interfaces
A character device presents itself to the guest virtual machine as one of the following types.
To set the serial port, use a management tool to make the following change to the domain XML:
...
<devices>
<serial type='pty'>
<source path='/dev/pts/3'/>
<target port='0'/>
</serial>
</devices>
...Figure 23.71. Guest virtual machine interface serial port
<target> can have a port attribute, which specifies the port number. Ports are numbered starting from 0. There are usually 0, 1 or 2 serial ports. There is also an optional type attribute, which has two choices for its value, isa-serial or usb-serial. If type is missing, isa-serial will be used by default. For usb-serial, an optional sub-element <address> with type='usb' can tie the device to a particular controller, documented above.
The
<console> element is used to represent interactive consoles. Depending on the type of guest virtual machine in use, the consoles might be paravirtualized devices, or they might be a clone of a serial device, according to the following rules:
- If no
targetTypeattribute is set, then the default devicetypeis according to the hypervisor's rules. The defaulttypewill be added when re-querying the XML fed into libvirt. For fully virtualized guest virtual machines, the default device type will usually be a serial port. - If the
targetTypeattribute isserial, and if no<serial>element exists, the console element will be copied to the<serial>element. If a<serial>element does already exist, the console element will be ignored. - If the
targetTypeattribute is notserial, it will be treated normally. - Only the first
<console>element may use atargetTypeofserial. Secondary consoles must all be paravirtualized. - On s390, the console element may use a
targetTypeofsclporsclplm(line mode). SCLP is the native console type for s390. There is no controller associated to SCLP consoles.
In the example below, a virtio console device is exposed in the guest virtual machine as
/dev/hvc[0-7] (for more information, see the Fedora project's virtio-serial page):
...
<devices>
<console type='pty'>
<source path='/dev/pts/4'/>
<target port='0'/>
</console>
<!-- KVM virtio console -->
<console type='pty'>
<source path='/dev/pts/5'/>
<target type='virtio' port='0'/>
</console>
</devices>
...
...
<devices>
<!-- KVM s390 sclp console -->
<console type='pty'>
<source path='/dev/pts/1'/>
<target type='sclp' port='0'/>
</console>
</devices>
...Figure 23.72. Guest virtual machine interface - virtio console device
If the console is presented as a serial port, the
<target> element has the same attributes as for a serial port. There is usually only one console.
23.17.15. Channel
This represents a private communication channel between the host physical machine and the guest virtual machine. It is manipulated by making changes to a guest virtual machine using a management tool to edit following section of the domain XML:
...
<devices>
<channel type='unix'>
<source mode='bind' path='/tmp/guestfwd'/>
<target type='guestfwd' address='10.0.2.1' port='4600'/>
</channel>
<!-- KVM virtio channel -->
<channel type='pty'>
<target type='virtio' name='arbitrary.virtio.serial.port.name'/>
</channel>
<channel type='unix'>
<source mode='bind' path='/var/lib/libvirt/kvm/f16x86_64.agent'/>
<target type='virtio' name='org.kvm.guest_agent.0'/>
</channel>
<channel type='spicevmc'>
<target type='virtio' name='com.redhat.spice.0'/>
</channel>
</devices>
...Figure 23.73. Channel
This can be implemented in a variety of ways. The specific type of
<channel> is given in the type attribute of the <target> element. Different channel types have different target attributes as follows:
guestfwd- Dictates that TCP traffic sent by the guest virtual machine to a given IP address and port is forwarded to the channel device on the host physical machine. Thetargetelement must have address and port attributes.virtio- a paravirtualized virtio channel. In a Linux guest operating system, the<channel>configuration changes the content of/dev/vport*files. If the optional elementnameis specified, the configuration instead uses a/dev/virtio-ports/$namefile. For more information, see the Fedora project's virtio-serial page. The optional elementaddresscan tie the channel to a particulartype='virtio-serial'controller, documented above. With KVM, if name is "org.kvm.guest_agent.0", then libvirt can interact with a guest agent installed in the guest virtual machine, for actions such as guest virtual machine shutdown or file system quiescing.spicevmc- Paravirtualized SPICE channel. The domain must also have a SPICE server as a graphics device, at which point the host physical machine piggy-backs messages across the main channel. Thetargetelement must be present, with attributetype='virtio';an optional attributenamecontrols how the guest virtual machine will have access to the channel, and defaults toname='com.redhat.spice.0'. The optional<address>element can tie the channel to a particulartype='virtio-serial'controller.
23.17.16. Host Physical Machine Interface
A character device presents itself to the host physical machine as one of the following types:
| Parameter | Description | XML snippet |
|---|---|---|
| Domain logfile | Disables all input on the character device, and sends output into the virtual machine's logfile. |
|
| Device logfile | A file is opened and all data sent to the character device is written to the file. Note that the destination directory must have the virt_log_t SELinux label for a guest with this setting to start successfully. |
|
| Virtual console | Connects the character device to the graphical framebuffer in a virtual console. This is typically accessed using a special hotkey sequence such as "ctrl+alt+3". |
|
| Null device | Connects the character device to the void. No data is ever provided to the input. All data written is discarded. |
|
| Pseudo TTY | A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as virsh console can connect to interact with the serial port locally. |
|
| NB Special case | NB special case if <console type='pty'>, then the TTY path is also duplicated as an attribute tty='/dev/pts/3' on the top level <console> tag. This provides compat with existing syntax for <console> tags. | |
| Host physical machine device proxy | The character device is passed through to the underlying physical character device. The device types must match, for example the emulated serial port should only be connected to a host physical machine serial port - do not connect a serial port to a parallel port. |
|
| Named pipe | The character device writes output to a named pipe. See the pipe(7) man page for more info. |
|
| TCP client-server | The character device acts as a TCP client connecting to a remote server. |
Or as a TCP server waiting for a client connection.
Alternatively you can use telnet instead of raw TCP. In addition, you can also use telnets (secure telnet) and tls.
|
| UDP network console | The character device acts as a UDP netconsole service, sending and receiving packets. This is a lossy service. |
|
| UNIX domain socket client-server | The character device acts as a UNIX domain socket server, accepting connections from local clients. |
|
23.17.17. Sound Devices
A virtual sound card can be attached to the host physical machine using the
sound element.
...
<devices>
<sound model='ac97'/>
</devices>
...Figure 23.74. Virtual sound card
The
sound element has one mandatory attribute, model, which specifies what real sound device is emulated. Valid values are specific to the underlying hypervisor, though typical choices are 'sb16', 'ac97', and 'ich6'. In addition, a sound element with 'ich6' model set can have optional codec sub-elements to attach various audio codecs to the audio device. If not specified, a default codec will be attached to allow playback and recording. Valid values are 'duplex' (advertises a line-in and a line-out) and 'micro' (advertises a speaker and a microphone).
...
<devices>
<sound model='ich6'>
<codec type='micro'/>
<sound/>
</devices>
...Figure 23.75. Sound Devices
Each sound element has an optional sub-element
<address> which can tie the device to a particular PCI slot, documented above.
Note
The es1370 sound device is no longer supported in Red Hat Enterprise Linux 7. Use ac97 instead.
23.17.18. Watchdog Device
A virtual hardware watchdog device can be added to the guest virtual machine using the
<watchdog> element. The watchdog device requires an additional driver and management daemon in the guest virtual machine. Currently there is no support notification when the watchdog fires.
...
<devices>
<watchdog model='i6300esb'/>
</devices>
...
...
<devices>
<watchdog model='i6300esb' action='poweroff'/>
</devices>
...Figure 23.76. Watchdog Device
The following attributes are declared in this XML:
model- The requiredmodelattribute specifies what real watchdog device is emulated. Valid values are specific to the underlying hypervisor.- The
modelattribute may take the following values:i6300esb— the recommended device, emulating a PCI Intel 6300ESBib700— emulates an ISA iBase IB700
action- The optionalactionattribute describes what action to take when the watchdog expires. Valid values are specific to the underlying hypervisor. Theactionattribute can have the following values:reset— default setting, forcefully resets the guest virtual machineshutdown— gracefully shuts down the guest virtual machine (not recommended)poweroff— forcefully powers off the guest virtual machinepause— pauses the guest virtual machinenone— does nothingdump— automatically dumps the guest virtual machine.
Note that the 'shutdown' action requires that the guest virtual machine is responsive to ACPI signals. In the sort of situations where the watchdog has expired, guest virtual machines are usually unable to respond to ACPI signals. Therefore, using 'shutdown' is not recommended. In addition, the directory to save dump files can be configured by auto_dump_path in file /etc/libvirt/kvm.conf.
23.17.19. Setting a Panic Device
Red Hat Enterprise Linux 7 hypervisor is capable of detecting Linux guest virtual machine kernel panics, using the
pvpanic mechanism. When invoked, pvpanic sends a message to the libvirtd daemon, which initiates a preconfigured reaction.
To enable the
pvpanic device, do the following:
- Add or uncomment the following line in the
/etc/libvirt/qemu.conffile on the host machine.auto_dump_path = "/var/lib/libvirt/qemu/dump"
- Run the
virsh editcommand to edit domain XML file of the specified guest, and add thepanicinto thedevicesparent element.<devices> <panic> <address type='isa' iobase='0x505'/> </panic> </devices>
The
<address> element specifies the address of panic. The default ioport is 0x505. In most cases, specifying an address is not needed.
The way in which
libvirtd reacts to the crash is determined by the <on_crash> element of the domain XML. The possible actions are as follows:
coredump-destroy- Captures the guest virtual machine's core dump and shuts the guest down.coredump-restart- Captures the guest virtual machine's core dump and restarts the guest.preserve- Halts the guest virtual machine to await further action.
Note
If the kdump service is enabled, it takes precedence over the
<on_crash> setting, and the selected <on_crash> action is not performed.
For more information on
pvpanic, see the related Knowledgebase article.
23.17.20. Memory Balloon Device
The balloon device can designate a part of a virtual machine's RAM as not being used (a process known as inflating the balloon), so that the memory can be freed for the host, or for other virtual machines on that host, to use. When the virtual machine needs the memory again, the balloon can be deflated and the host can distribute the RAM back to the virtual machine.
The size of the memory balloon is determined by the difference between the
<currentMemory> and <memory> settings. For example, if <memory> is set to 2 GiB and <currentMemory> to 1 GiB, the balloon contains 1 GiB. If manual configuration is necessary, the <currentMemory> value can be set by using the virsh setmem command and the <memory> value can be set by using the virsh setmaxmem command.
Warning
If modifying the
<currentMemory> value, make sure to leave sufficient memory for the guest OS to work properly. If the set value is too low, the guest may become unstable.
A virtual memory balloon device is automatically added to all KVM guest virtual machines. In the XML configuration, this is represented by the
<memballoon> element. Memory ballooning is managed by the libvirt service, and will be automatically added when appropriate. Therefore, it is not necessary to explicitly add this element in the guest virtual machine XML unless a specific PCI slot needs to be assigned. Note that if the <memballoon> device needs to be explicitly disabled, model='none' can be be used for this purpose.
The following example a shows a memballoon device automatically added by
libvirt:
...
<devices>
<memballoon model='virtio'/>
</devices>
...Figure 23.77. Memory balloon device
The following example shows a device that has been added manually with static PCI slot 2 requested:
...
<devices>
<memballoon model='virtio'>
<address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
</memballoon>
</devices>
...Figure 23.78. Memory balloon device added manually
The required
model attribute specifies what type of balloon device is provided. Valid values are specific to the virtualization platform; in the KVM hypervisor, 'virtio' is the default setting.
