Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.34. Devices - Hard drives, floppy disks, CD-ROMs Example 8

23.17.1.1. Disk element
Copiar o link

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 the libvirt upstream pages.

23.17.1.2. Source element
Copiar o link

Represents the disk source. The disk source depends on the disk type attribute, as follows:
  • <file> - The file attribute specifies the fully-qualified path to the file in which the disk is located.
  • <block> - The dev attribute specifies the fully-qualified path to the host device that serves as the disk.
  • <dir> - The dir attribute specifies the fully-qualified path to the directory used as the disk.
  • <network> - The protocol attribute specifies the protocol used to access the requested image. Possible values are: nbd, isci, rbd, sheepdog, and gluster.
    • If the protocol attribute is rbd, sheepdog, or gluster, an additional attribute, name is mandatory. This attribute specifies which volume and image will be used.
    • If the protocol attribute is nbd, the name attribute is optional.
    • If the protocol attribute is isci, the name attribute 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 the pool and volume attributes.
    • <pool> - The name of the storage pool (managed by libvirt) where the disk source resides.
    • <volume> - The name of the storage volume (managed by libvirt) used as the disk source.
      The value for the volume attribute is the output from the Name column of a virsh 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:
  • 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, or revert.
  • optional drops if missing at any start attempt.

23.17.1.3. Mirror element
Copiar o link

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
Copiar o link

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
Copiar o link

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
Copiar o link

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 name attribute selects the primary back-end driver name, while the optional type attribute provides the sub-type.
  • 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 I/O, and sync requests from guest 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 default setting, report will be used.
  • The optional io attribute controls specific policies on I/O; kvm guest virtual machines support threads and native. The optional ioeventfd attribute allows users to set domain I/O asynchronous handling for virtio disk devices. The default is determined by the hypervisor. Accepted values are on and off. 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

    The ioeventfd attribute is included in the <driver> element of the disk XML section and also the <driver> element of the device XML section. In the former case, it influences the virtIO disk, and in the latter case the SCSI disk.
  • The optional event_idx attribute controls some aspects of device event processing and can be set to either on or off. If set to on, 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 is on. When this behavior is not required, setting off forces 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_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.
  • The discard='unmap' can be set to enable discard support. The same line can be replaced with discard='ignore' to disable. discard='ignore' is the default setting.

23.17.1.7. Additional Device Elements
Copiar o link

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 with attribute <device='cdrom'>.
  • <shareable> Indicates the device is expected to be shared between domains (as long as hypervisor and operating system 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 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'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:
    • name - specifies the host name
    • port - specifies the port number
    • transport - specifies the transport type
    • socket - specifies the path to the socket
    The meaning of this element and the number of the elements depend on the protocol attribute as shown in Additional host attributes based on the protocol

    Additional host attributes based on the protocol

    • nbd - Specifies a server running nbd-server and 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 the sheepdog servers (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 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 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. multifunction 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.
  • 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, 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 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
Copiar o link

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-function attribute, 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' - drive addresses 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' - Each virtio-serial address 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 by libvirt. The additional reg attribute, which determines the hex value address of the starting register, can be assigned to this attribute.

23.17.3. Controllers
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.36. Devices - controllers - USB

23.17.4. Device Leases
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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 to 0.

23.17.5. Host Physical Machine Device Assignment
Copiar o link

23.17.5.1. USB / PCI devices
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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>
  ...
Copy to Clipboard Toggle word wrap

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>
  ..
Copy to Clipboard Toggle word wrap

Figure 23.40. Devices - host physical machine scsi device assignment

The components of this section of the domain XML are as follows:
Expand
Table 23.16. Host physical machine device assignment elements
Parameter Description
hostdev
This is the main element for describing host physical machine devices. It accepts the following options:
  • mode - the value is always subsystem for USB and PCI devices.
  • type - usb for USB devices and pci for PCI devices.
  • managed - Toggles the Managed mode of the device:
    • When set to yes for a PCI device, it attaches to the guest machine and detaches from the guest machine and re-attaches to the host machine as necessary. managed='yes' is recommended for general use of device assignment.
    • When set to no or omitted for PCI and for USB devices, the device stays attached to the guest. To make the device available to the host, the user must use the argument virNodeDeviceDettach or the virsh nodedev-dettach command before starting the guest or hot plugging the device. In addition, they must use virNodeDeviceReAttach or virsh nodedev-reattach after hot-unplugging the device or stopping the guest. managed='no' is mainly recommended for devices that are intended to be dedicated to a specific guest.
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:
  • mandatory - Fails if missing for any reason (the default).
  • requisite - Fails if missing on boot up, drops if missing on migrate/restore/revert.
  • optional - Drops if missing at any start attempt.
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
Copiar o link

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>
...
Copy to Clipboard Toggle word wrap

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>
...
Copy to Clipboard Toggle word wrap

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>
...
Copy to Clipboard Toggle word wrap

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:
Expand
Table 23.17. Block / character device elements
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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.44. Devices - redirected devices

The components of this section of the domain XML are as follows:
Expand
Table 23.18. Redirected device elements
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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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:
Expand
Table 23.19. Smartcard mode elements
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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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:
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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.47. Devices - network interfaces- virtual networks

23.17.8.2. Bridge to LAN
Copiar o link

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>
Copy to Clipboard Toggle word wrap

Figure 23.48. Devices - network interfaces- bridge to LAN

23.17.8.3. Setting a port masquerading range
Copiar o link

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>  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.50. Devices - network interfaces- User space SLIRP stack

23.17.8.5. Generic Ethernet connection
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.51. Devices - network interfaces- generic ethernet connection

23.17.8.6. Direct attachment to physical interfaces
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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”:
Expand
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”:
Expand
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>
  ...
Copy to Clipboard Toggle word wrap

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.55. Devices - network interfaces- PCI passthrough

23.17.8.8. Multicast tunnel
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.56. Devices - network interfaces- multicast tunnel

23.17.8.9. TCP tunnel
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.57. Devices - network interfaces- TCP tunnel

23.17.8.10. Setting NIC driver-specific options
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.58. Devices - network interfaces- setting NIC driver-specific options

The following attributes are available for the "virtio" NIC driver:
Expand
Table 23.22. virtio NIC driver elements
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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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)
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

Figure 23.62. Quality of service

23.17.8.15. Setting VLAN tag (on supported network types only)
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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.9. Input Devices
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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:
Expand
Table 23.23. Graphical framebuffer main elements
Parameter Description
sdl This displays a window on the host physical machine desktop. It accepts the following optional arguments:
  • A display attribute for the display to use
  • An xauth attribute for the authentication identifier
  • An optional fullscreen attribute accepting values yes or no
vnc Starts a VNC server.
  • The port attribute specifies the TCP port number (with -1 as legacy syntax indicating that it should be auto-allocated).
  • The autoport attribute is the preferred syntax for indicating auto-allocation of the TCP port to use.
  • The listen attribute is an IP address for the server to listen on.
  • The passwd attribute provides a VNC password in clear text.
  • The keymap attribute specifies the keymap to use. It is possible to set a limit on the validity of the password be giving an timestamp passwdValidTo='2010-04-09T15:51:00' assumed to be in UTC.
  • The connected attribute allows control of connected client during password changes. VNC accepts the keep value only; note that it may not be supported by all hypervisors.
  • Rather than using listen/port, KVM supports a socket attribute for listening on a UNIX domain socket path.
spice Starts a SPICE server.
  • The port attribute specifies the TCP port number (with -1 as legacy syntax indicating that it should be auto-allocated), while tlsPort gives an alternative secure port number.
  • The autoport attribute is the new preferred syntax for indicating auto-allocation of both port numbers.
  • The listen attribute is an IP address for the server to listen on.
  • The passwd attribute provides a SPICE password in clear text.
  • The keymap attribute specifies the keymap to use. It is possible to set a limit on the validity of the password be giving an timestamp passwdValidTo='2010-04-09T15:51:00' assumed to be in UTC.
  • The connected attribute allows control of a connected client during password changes. SPICE accepts keep to keep a client connected, disconnect to disconnect the client and fail to fail changing password. Note that this is not supported by all hypervisors.
  • The defaultMode attribute sets the default channel security policy; valid values are secure, insecure and the default any (which is secure if possible, but falls back to insecure rather than erroring out if no secure path is available).
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>
Copy to Clipboard Toggle word wrap

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:
  • image to set image compression (accepts auto_glz, auto_lz, quic, glz, lz, off)
  • jpeg for JPEG compression for images over WAN (accepts auto, never, always)
  • zlib for configuring WAN image compression (accepts auto, never, always) and playback for enabling audio stream compression (accepts on or off)
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:
Expand
Table 23.24. Additional graphical framebuffer elements
Parameter Description
rdp Starts an RDP server.
  • The port attribute specifies the TCP port number (with -1 as legacy syntax indicating that it should be auto-allocated).
  • The autoport attribute is the preferred syntax for indicating auto-allocation of the TCP port to use.
  • The replaceUser attribute is a boolean deciding whether multiple simultaneous connections to the virtual machine are permitted.
  • The multiUser attribute decides whether the existing connection must be dropped and a new connection must be established by the VRDP server, when a new client connects in single connection mode.
desktop This value is 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:
  • type - Set to either address or network. This tells whether this listen element is specifying the address to be used directly, or by naming a network (which will then be used to determine an appropriate address for listening).
  • address - This attribute will contain either an IP address or host name (which will be resolved to an IP address via a DNS query) to listen on. In the "live" XML of a running domain, this attribute will be set to the IP address used for listening, even if type='network'.
  • network - If type='network', the network attribute will contain the name of a network in libvirt's list of configured networks. The named network configuration will be examined to determine an appropriate listen address. For example, if the network has an IPv4 address in its configuration (for example, if it has a forward type of route, NAT, or an isolated type), the first IPv4 address listed in the network's configuration will be used. If the network is describing a host physical machine bridge, the first IPv4 address associated with that bridge device will be used. If the network is describing one of the 'direct' (macvtap) modes, the first IPv4 address of the first forward dev will be used.

23.17.12. Video Devices
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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:
Expand
Table 23.25. Graphical framebuffer elements
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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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 targetType attribute is set, then the default device type is according to the hypervisor's rules. The default type will 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 targetType attribute is serial, 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 targetType attribute is not serial, it will be treated normally.
  • Only the first <console> element may use a targetType of serial. Secondary consoles must all be paravirtualized.
  • On s390, the console element may use a targetType of sclp or sclplm (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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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. The target element 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 element name is specified, the configuration instead uses a /dev/virtio-ports/$name file. For more information, see the Fedora project's virtio-serial page. The optional element address can tie the channel to a particular type='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. The target element must be present, with attribute type='virtio'; an optional attribute name controls how the guest virtual machine will have access to the channel, and defaults to name='com.redhat.spice.0'. The optional <address> element can tie the channel to a particular type='virtio-serial' controller.

23.17.16. Host Physical Machine Interface
Copiar o link

A character device presents itself to the host physical machine as one of the following types:
Expand
Table 23.26. Character device elements
Parameter Description XML snippet
Domain logfile Disables all input on the character device, and sends output into the virtual machine's logfile. 
<devices>
   <console type='stdio'>
     <target port='1'/>
   </console>
</devices>
Copy to Clipboard Toggle word wrap
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. 
<devices>
   <serial type="file">
      <source path="/var/log/vm/vm-serial.log"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
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". 
<devices>
   <serial type='vc'>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
Null device Connects the character device to the void. No data is ever provided to the input. All data written is discarded. 
<devices>
   <serial type='null'>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
Pseudo TTY A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as virsh console can connect to interact with the serial port locally. 
<devices>
   <serial type="pty">
      <source path="/dev/pts/3"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
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. 
<devices>
   <serial type="dev">
      <source path="/dev/ttyS0"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
Named pipe The character device writes output to a named pipe. See the pipe(7) man page for more info. 
<devices>
   <serial type="pipe">
      <source path="/tmp/mypipe"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
TCP client-server The character device acts as a TCP client connecting to a remote server. 
<devices>
   <serial type="tcp">
      <source mode="connect" host="0.0.0.0" service="2445"/>
      <protocol type="raw"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
Or as a TCP server waiting for a client connection. 
<devices>
   <serial type="tcp">
      <source mode="bind" host="127.0.0.1" service="2445"/>
      <protocol type="raw"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
Alternatively you can use telnet instead of raw TCP. In addition, you can also use telnets (secure telnet) and tls. 
<devices>
   <serial type="tcp">
      <source mode="connect" host="0.0.0.0" service="2445"/>
      <protocol type="telnet"/>
      <target port="1"/>
   </serial>
      <serial type="tcp">
      <source mode="bind" host="127.0.0.1" service="2445"/>
      <protocol type="telnet"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
UDP network console The character device acts as a UDP netconsole service, sending and receiving packets. This is a lossy service. 
<devices>
   <serial type="udp">
      <source mode="bind" host="0.0.0.0" service="2445"/>
      <source mode="connect" host="0.0.0.0" service="2445"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap
UNIX domain socket client-server The character device acts as a UNIX domain socket server, accepting connections from local clients. 
<devices>
   <serial type="unix">
      <source mode="bind" path="/tmp/foo"/>
      <target port="1"/>
   </serial>
</devices>
Copy to Clipboard Toggle word wrap

23.17.17. Sound Devices
Copiar o link

A virtual sound card can be attached to the host physical machine using the sound element. 
  ...
  <devices>
    <sound model='ac97'/>
  </devices>
  ...
Copy to Clipboard Toggle word wrap

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>
  ...
Copy to Clipboard Toggle word wrap

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
Copiar o link

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>
...
Copy to Clipboard Toggle word wrap

Figure 23.76. Watchdog Device

The following attributes are declared in this XML:
  • model - The required model attribute specifies what real watchdog device is emulated. Valid values are specific to the underlying hypervisor.
  • The model attribute may take the following values:
    • i6300esb — the recommended device, emulating a PCI Intel 6300ESB
    • ib700 — emulates an ISA iBase IB700
  • action - The optional action attribute describes what action to take when the watchdog expires. Valid values are specific to the underlying hypervisor. The action attribute can have the following values:
    • reset — default setting, forcefully resets the guest virtual machine
    • shutdown — gracefully shuts down the guest virtual machine (not recommended)
    • poweroff — forcefully powers off the guest virtual machine
    • pause — pauses the guest virtual machine
    • none — does nothing
    • dump — 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
Copiar o link

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.conf file on the host machine. 
    auto_dump_path = "/var/lib/libvirt/qemu/dump"
    Copy to Clipboard Toggle word wrap
  • Run the virsh edit command to edit domain XML file of the specified guest, and add the panic into the devices parent element. 
    <devices>
  <panic>
    <address type='isa' iobase='0x505'/>
  </panic>
</devices>
    Copy to Clipboard Toggle word wrap
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
Copiar o link

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>
  ...
Copy to Clipboard Toggle word wrap

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>
...
Copy to Clipboard Toggle word wrap

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.
Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat