SupportConsoleDevelopersStart a trialContact

20.16. 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-9p-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 reccomended 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/lib/xen/bin/qemu-dm</emulator>
  </devices>
  ...

Figure 20.22. 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.

20.16.1. Hard Drives, Floppy Disks, CDROMs

This section of the domain XML specifies any device that looks like a disk, be it a floppy, harddisk, cdrom, or paravirtualized driver is specified via the disk element. 

 ...
  <devices>
    <disk type='file' snapshot='external'>
      <driver name="tap" type="aio" cache="default"/>
      <source file='/var/lib/xen/images/fv0' startupPolicy='optional'>
        <seclabel relabel='no'/>
      </source>
      <target dev='hda' bus='ide'/>
      <iotune>
        <total_bytes_sec>10000000</total_bytes_sec>
        <read_iops_sec>400000</read_iops_sec>
        <write_iops_sec>100000</write_iops_sec>
      </iotune>
      <boot order='2'/>
      <encryption type='...'>
        ...
      </encryption>
      <shareable/>
      <serial>
        ...
      </serial>
    </disk>
      ...
    <disk type='network'>
      <driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/>
      <source protocol="sheepdog" name="image_name">
        <host name="hostname" port="7000"/>
      </source>
      <target dev="hdb" bus="ide"/>
      <boot order='1'/>
      <transient/>
      <address type='drive' controller='0' bus='1' unit='0'/>
    </disk>
    <disk type='network'>
      <driver name="qemu" type="raw"/>
      <source protocol="rbd" name="image_name2">
        <host name="hostname" port="7000"/>
      </source>
      <target dev="hdd" bus="ide"/>
      <auth username='myuser'>
        <secret type='ceph' usage='mypassid'/>
      </auth>
    </disk>
    <disk type='block' device='cdrom'>
      <driver name='qemu' type='raw'/>
      <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>
    <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>
  </devices>
  ...

Figure 20.23. Devices - Hard drives, floppy disks, CDROMs

20.16.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:
  • file
  • block
  • dir
  • network
For more information, see Disk Elements

20.16.1.2. Source element

If the <disk type='file''>, then the file attribute specifies the fully-qualified path to the file holding the disk. If the <disk type='block'>, then the dev attribute specifies the path to the host physical machine device to serve as the disk. With both file and block, one or more optional sub-elements seclabel, described below, can be used to override the domain security labeling policy for just that source file. If the disk type is dir, then the dir attribute specifies the fully-qualified path to the directory to use as the disk. If the disk type is network, then the protocol attribute specifies the protocol to access to the requested image; possible values are nbd, rbd, sheepdog or gluster.
If the protocol attribute is rbd, sheepdog or gluster, an additional attribute name is mandatory to specify which volume and or image will be used. 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 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. This is done by manipulating the startupPolicy attribute, with the following values:
  • mandatory causes a failure if missing for any reason. This is the default setting.
  • requisite causes a failure if missing on boot up, drops if missing on migrate/restore/revert
  • optional drops if missing at any start attempt

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

20.16.1.4. Target element

The <target> element controls the bus / device under which the disk is exposed to the guest virtual machine 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 virtual machine OS. 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 or sata. If omitted, the bus type is inferred from the style of the device name. eg, a device named 'sda' will typically be exported using a SCSI bus. The optional attribute tray indicates the tray status of the removable disks (such as CD-ROM or Floppy disk), the value can be either open or closed. The default setting is closed. For more information, see target Elements

20.16.1.5. iotune

The optional <iotune> element provides the ability to provide additional per-device I/O tuning, with values that can vary for each device (contrast this to the blkiotune element, which applies globally to the domain). 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.

20.16.1.6. driver

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, then the name attribute selects the primary back-end driver name, while the optional type attribute provides the sub-type. For a list of possible types refer to Driver Elements
  • The optional cache attribute controls the cache mechanism, possible values are: default, none, writethrough, writeback, directsync (similar to writethrough, but it bypasses the host physical machine page cache) and unsafe (host physical machine may cache all disk io, and sync requests from guest virtual machine virtual machines are ignored).
  • The optional error_policy attribute controls how the hypervisor behaves on a disk read or write error, possible values are stop, report, ignore, and enospace. The default setting of error_policy is report. There is also an optional rerror_policy that controls behavior for read errors only. If no rerror_policy is given, error_policy is used for both read and write errors. If rerror_policy is given, it overrides the error_policy for read errors. Also note that enospace is not a valid policy for read errors, so if error_policy is set to enospace and no rerror_policy is given, the read error the default setting, report will be used.
  • The optional io attribute controls specific policies on I/O; qemu guest virtual machine virtual machines support threads and native. 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 the guest virtual machine virtual machine to be executed while a separate thread handles I/O. Typically guest virtual machine 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 virtual machine I/O latency. Unless you are absolutely certian that the io needs to be manipulated, it is highly recommended that you not change the default setting and allow the hypervisor to dictate the setting.
  • The optional event_idx attribute controls some aspects of device event processing and can be set to either on or off - if it is on, it will reduce the number of interrupts and exits for the guest virtual machine virtual machine. The default is determined by the hypervisor and the default setting is on. In cases that there is a situation where this behavior is suboptimal, this attribute provides a way to force the feature off. Unless you are absolutely certian that the event_idx needs to be manipulated, it is highly recommended that you not change the default setting and allow the hypervisor to dictate the setting.
  • The optional copy_on_read attribute controls whether to copy the read backing file into the image file. The accepted values can be either on or <off>. copy-on-read avoids accessing the same backing file sectors repeatedly and is useful when the backing file is over a slow network. By default copy-on-read is off.

20.16.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 BIOS boot loader section
  • <encryption> - Specifies how the volume is encrypted. See the Storage Encryption page for more information.
  • <readonly> - Indicates the device cannot be modified by the guest virtual machine virtual machine. This setting is the default for disks with attribute device='cdrom'.
  • shareable Indicates the device is expected to be shared between domains (as long as hypervisor and OS support this). If shareable is 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 virtual machine exits. With some hypervisors, marking a disk transient prevents the domain from participating in migration or snapshots.
  • <serial>- Specifies the serial number of guest virtual machine virtual machine virtual machine's hard drive. For example, <serial>WD-WMAP9A966149</serial>.
  • <wwn> - Specifies the WWN (World Wide Name) 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 4 attributes: viz, name, port, transport and socket, which specify the host name, the port number, transport type and path to socket, respectively. The meaning of this element and the number of the elements depend on the protocol attribute as shown here:

    Additional host attributes

    • nbd - Specifies a server running nbd-server and may only be used for only one host physical machine
    • rbd - Monitors servers of RBD type and may be used for one or more host physical machines
    • sheepdog - Specifies one of the sheepdog servers (default is localhost:7000) and can be used 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 are tcp, rdma or unix. If nothing is specified, tcp is assumed. If transport is unix, the socket attribute specifies path to unix socket.
  • <address> - Ties the disk to a given slot of a controller. The actual <controller> device can often be inferred by but it can also be explicitly specified. The type attribute is mandatory, and is typically pci or drive. For a pci controller, additional attributes for bus, slot, and function must be present, as well as optional domain and multifunction. multifun ction defaults to off. For a drive controller, additional attributes controller, bus, target, and unit are available, each with a default setting of 0.
  • auth - Provides the authentication credentials needed to access the source. It includes a mandatory attribute username, which identifies the user name to use during authentication, as well as a sub-element secret with mandatory attribute type. More information can be found here at Device Elements
  • geometry - Provides the ability to override geometry settings. This mostly useful for S390 DASD-disks or older DOS-disks.
  • 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-Modus and can have the following values:none, lba or auto
  • 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 virtual machine OS and describes the smallest units for disk I/O.
    • physical_block_size - reports to the guest virtual machine virtual machine OS and describes the disk's hardware sector size which can be relevant for the alignment of disk data.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.