Assigning Host Devices to Virtual Machines
- WHAT?
Virtual machines can directly access host PCI or USB devices, such as graphics cards or network adapters.
- WHY?
A virtual machine that is assigned direct access to a host device can use all its capabilities, bypassing the virtualization layer. Such an approach offers near-native performance or hardware acceleration.
- GOAL
After completing the included procedures, you will be able to assign a host PCI or USB device to a virtual machine using both the graphical application Virtual Machine Manager and the command-line tool
virsh
.- EFFORT
It takes less than 30 minutes to understand and manage assigning a host device to a virtual machine.
- REQUIREMENTS
A
libvirt
-based VM Host Server running at least one virtual machinelibvirt-client and virt-manager packages installed on the host
root
privileges
1 libvirt
and device assignment #
libvirt
is a unified interface to multiple virtualization solutions. libvirt
virtual
machines are typically managed by either virsh
, a command-line utility, or Virtual Machine Manager, an
application with a graphical user interface. Assigning VM Host Server's PCI or USB devices to a
VM Guest dedicates the device's resources to the VM Guest. The reasons for assigning a host
device to a VM are near-native performance of the device, using its hardware acceleration
capabilities, or isolating the device from other VMs to increase security.
This article describes how to assign a VM Host Server's device to a VM Guest using both the virsh
command-line utility and the Virtual Machine Manager GUI application.
2 Assigning a device using Virtual Machine Manager #
The following procedure describes how to assign a host device to a VM Guest using the Virtual Machine Manager GUI application.
If SELinux is running on the VM Host Server, you need to allow managing the PCI or USB device configuration:
>
sudo
setsebool -P virt_use_sysfs 1
Double-click a VM Guest entry in the Virtual Machine Manager to open its console, then switch to the
view with › .Click
and choose the or from the left list. A list of available PCI devices appears in the right part of the window.Figure 1: Adding a PCI device #From the list of available devices, choose the one you want to pass to the guest. Confirm with
.Restart the domain if it is running for the changes to take effect.
3 Assigning a device using virsh
#
The following procedure describes how to assign a host device to a VM Guest using the
virsh
command-line tool.
KVM guests using the QEMU Q35 machine type have a PCI topology that includes a
pcie-root
controller and seven pcie-root-port
controllers. The pcie-root
controller does not support hotplugging. Each
pcie-root-port
controller supports hotplugging a single PCIe device. PCI
controllers cannot be hotplugged, so plan accordingly and add more
pcie-root-port
s if more than seven PCIe devices will be hotplugged. A
pcie-to-pci-bridge
controller can be added to support hotplugging legacy
PCI devices. See https://libvirt.org/pci-hotplug.html for more
information about PCI topology between QEMU machine types.
Identify the host PCI or USB device to assign to the VM Guest. The following example identifies a DEC network card:
>
sudo
lspci -nn
[...] 03:07.0 Ethernet controller [0200]: Digital Equipment Corporation DECchip \ 21140 [FasterNet] [1011:0009] (rev 22) [...]Write down the device ID, for example,
03:07.0
.Gather detailed information about the device using
virsh nodedev-dumpxml ID
. To get the ID, replace the colon and the period in the device ID (03:07.0
) with underscores. Prefix the result with “pci_0000_”:pci_0000_03_07_0
.>
sudo
virsh nodedev-dumpxml pci_0000_03_07_0
<device> <name>pci_0000_03_07_0</name> <path>/sys/devices/pci0000:00/0000:00:14.4/0000:03:07.0</path> <parent>pci_0000_00_14_4</parent> <driver> <name>tulip</name> </driver> <capability type='pci'> <domain>0</domain> <bus>3</bus> <slot>7</slot> <function>0</function> <product id='0x0009'>DECchip 21140 [FasterNet]</product> <vendor id='0x1011'>Digital Equipment Corporation</vendor> <numa node='0'/> </capability> </device>Write down the values for domain, bus and function.
Detach the device from the host system:
>
sudo
virsh nodedev-detach pci_0000_03_07_0
Device pci_0000_03_07_0 detachedConvert the domain, bus, slot, and function values from decimal to hexadecimal. In this example, domain = 0, bus = 3, slot = 7, and function = 0. Ensure that the values are inserted in the right order. Use
printf
to output the PCI source address line that you need when updating the domain XML specification, for example:>
printf "<address domain='0x%x' bus='0x%x' slot='0x%x' function='0x%x'/>\n" 0 3 7 0
<address domain='0x0' bus='0x3' slot='0x7' function='0x0'/>Run
virsh edit
on your domain, and add the following device entry in the<devices>
section using the result from the previous step:<hostdev mode='subsystem' type='pci' managed='yes'> <source> <address domain='0x0' bus='0x03' slot='0x07' function='0x0'/> </source> </hostdev>
Shut down the VM Guest:
>
sudo
shutdown -h nowIf SELinux is running on the VM Host Server, you need to allow managing the host device configuration:
>
sudo
setsebool -P virt_use_sysfs 1
Start your VM Guest to make the assigned device available:
>
sudo
virsh start VM_NAME
4 Managed and unmanaged devices #
When assigning a host device to a VM Guest, you can specify whether the device is
managed or unmanaged by using the
managed='yes'
(default) or managed='no'
option in the
libvirt
XML specification of the device, for example:
<hostdev mode='subsystem' type='pci' managed='yes'>
Managed devices are automatically detached from the host driver and
attached to the virtual vfio-pci
driver of the guest during the domain
startup. When the domain is terminated, the device is reattached to the original host driver.
For unmanaged devices, you need to take care of detaching the device from
the host and attaching it to the vfio-pci
driver manually, as suggested
by the following steps:
Before starting the domain, detach the device—for example, identified by pci_0000_03_07_0—from the host.
>
sudo
virsh nodedev-detach pci_0000_03_07_0Start the domain. It is automatically assigned the unmanaged device identified by pci_0000_03_07_0.
After you stop the domain, you can make the device available to the host again.
>
sudo
virsh nodedev-reattach pci_0000_03_07_0
5 Troubleshooting #
This topic lists common problems when assigning host devices to virtual machines.
5.1 PCI Pass-Through to fully virtualized (FV) Xen guest fails #
This issue is identified with certain Intel processor chipsets where the
iommu
boot parameter needs to be disabled by default for PCI Pass-Through to work
with paravirtualized (PV) guests. For both PV and FV guests to work with PCI Pass-Through, use the
no-intremap
option on the Xen hypervisor instead. No change is needed if
PCI devices are only passed through to PV guests. For example:
>
sudo
cat /boot/grub/menu.lst
###Don't change this comment - YaST2 identifier: Original name: xen### title Xen -- SUSE Linux Enterprise Desktop 15 SP5 - 6.1.0-0.6.6 root (hd0,5) kernel /boot/xen.gz vga=mode-0x314 iommu=no-intremap module /boot/vmlinuz-6.1.0-0.6.6-xen root=/dev/sda6 resume=/dev/sda5 splash=silent showopts vga=0x314 module /boot/initrd-6.1.0-0.6.6-xen
5.2 Virtual machine complains that the passthrough device is missing #
This often happens if you assign a removable host device—such as a USB flash drive—to a virtual machine (VM) and then try to start the VM with the assigned device unplugged. This breaks the VM start and you either need to remove the device assignment, or plug the device back in the host.
6 Legal Notice #
Copyright© 2006–2024 SUSE LLC and contributors. All rights reserved.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation License”.
For SUSE trademarks, see https://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.
All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.