5. USB redirection

With USB redirection, USB devices plugged into the client machine can be transparently redirected to the guest OS. This redirection can either be automatic (all newly plugged devices are redirected), or manual (the user selects which devices (s)he wants to redirect).

For redirection to work, the virtual machine must have an USB2 EHCI controller (this implies 3 additional UHCI controllers). It also needs to have Spice channels for USB redirection. The number of such channels correspond to the number of USB devices that it will be possible to redirect at the same time.

5.1. Configuration

Using virt-manager. Virtual machines created with virt-manager should have a USB controller by default. In the virtual machine details, select "Controller USB" in the left pane, and make sure its model is set to USB2. You can then click on "Add Hardware" and add as many "USB Redirection" items as the number of USB devices you want to be able to redirect simultaneously.

Using libvirt. You need to add the needed USB controllers to the libvirt XML (make sure there is no pre-existing USB controller in your virtual machine XML before doing this), as well as one Spice USB redirection channel per device you want to redirect simultaneously.

<controller type='usb' index='0' model='ich9-ehci1'/>
<controller type='usb' index='0' model='ich9-uhci1'>
    <master startport='0'/>
</controller>
<controller type='usb' index='0' model='ich9-uhci2'>
    <master startport='2'/>
</controller>
<controller type='usb' index='0' model='ich9-uhci3'>
    <master startport='4'/>
</controller>
<redirdev bus='usb' type='spicevmc'/>
<redirdev bus='usb' type='spicevmc'/>
<redirdev bus='usb' type='spicevmc'/>
<redirdev bus='usb' type='spicevmc'/>

Using QEMU. Similarly to libvirt, we need to add EHCI/UHCI controllers to QEMU command line, and we also need to add one Spice redirection channel per device we want to redirect simultaneously.

-device ich9-usb-ehci1,id=usb \
-device ich9-usb-uhci1,masterbus=usb.0,firstport=0,multifunction=on \
-device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \
-device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \
-chardev spicevmc,name=usbredir,id=usbredirchardev1 \
-device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \
-chardev spicevmc,name=usbredir,id=usbredirchardev2 \
-device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \
-chardev spicevmc,name=usbredir,id=usbredirchardev3 \
-device usb-redir,chardev=usbredirchardev3,id=usbredirdev3

5.2. Client

The client needs to have support for USB redirection. In remote-viewer, you can select which USB devices to redirect in "File/USB device" selection once the Spice connection is established. There are also various command line redirection options which are described when running remote-viewer with --help-spice.

To get USB redirection working on Windows clients, you need to install UsbDk