--- page/UsbRedir.rst | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 132 insertions(+), 5 deletions(-) diff --git a/page/UsbRedir.rst b/page/UsbRedir.rst index 958a086..00c8fbe 100644 --- a/page/UsbRedir.rst +++ b/page/UsbRedir.rst @@ -1,8 +1,6 @@ usbredir ############################################################################### -:slug: usbredir - usbredir is the name of a network protocol for sending usb device traffic over a network connection. It is also the name of the software @@ -23,8 +21,136 @@ The usbguest side is currently only implemented for qemu, and shipped as part of qemu (enabling this in qemu requires the libusbredirparser library to be available when building qemu). -usbredir supports USB device filtering configurable by `filter -string <http://people.fedoraproject.org/~jwrdegoede/spice-reference/SpiceUsbDeviceManager.html#SpiceUsbDeviceManager--auto-connect-filter>`__. +usbredir supports USB device filtering configurable by filter string + +Configuration +^^^^^^^^^^^^^ + +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. + +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 ++++++++++++++ + +.. code-block:: sh + + <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 +++++++++++ + +.. code-block:: sh + + -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 + +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 <http://www.spice-space.org/download/windows/usbdk/>`__ + + + + +Filter String Format +^^^^^^^^^^^^^^^^^^^^ + +A filter is being used for setting blocking or autoconnect rules for usb +devices. It consists of one or more rules, where each rule has the form of: + +**@class,@vendor,@product,@version,@allow** + +Use -1 for @class/@vendor/@product/@version to accept any value. + +And the rules themselves are concatenated like this: + +**@rule1|@rule2|@rule3** + +E.g. client's default setting filters out HID (class 0x03) USB devices from +auto connect and auto connects anything else. Note the explicit allow rule at +the end, this is necessary since by default all devices without a matching +filter rule will not auto-connect. + +Client's default filter string is 0x03,-1,-1,-1,0|-1,-1,-1,-1,1 + + +Client +^^^^^^ + +Set a string specifying a filter to use to determine which USB devices +to **autoconnect** when plugged in. + +.. code-block:: sh + + remote-viewer --spice-usbredir-redirect-on-connect="0x03,-1,-1,-1,0|-1,-1,-1,-1,1" + +Host +^^^^ + +Set a string specifying a filter to use to determine which USB devices +are **allowed\\blocked** to redirect usb traffic to the guest. + + + +Using QEMU +++++++++++ +.. code-block:: sh + + -device usb-redir,filter='0x03:-1:-1:-1:0|-1:-1:-1:-1:1',chardev=usbredirchardev1,id=usbredirdev1 + +Note that filter string in QEMU cmd should be used with **':'** rules separator. + +Using libvirt ++++++++++++++ + +.. code-block:: XML + + ... + <devices> + ... + <redirfilter> + <usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/> + <usbdev allow='no'/> + </redirfilter> + </devices> + ... download ++++++++ @@ -32,11 +158,12 @@ download Latest versions: - For use with qemu 1.3 and newer: - `usbredir-0.7.tar.bz2 <http://spice-space.org/download/usbredir/usbredir-0.7.tar.bz2>`__ + `usbredir-0.7.1.tar.bz2 <http://www.spice-space.org/download/usbredir/usbredir-0.7.1.tar.bz2>`__ - For use with qemu 1.0 / 1.1 / 1.2 release: `usbredir-0.4.4.tar.bz2 <http://spice-space.org/download/usbredir/usbredir-0.4.4.tar.bz2>`__ Older versions: +`0.7 <http://spice-space.org/download/usbredir/usbredir-0.7.tar.bz2>`__, `0.6 <http://spice-space.org/download/usbredir/usbredir-0.6.tar.bz2>`__, `0.5.2 <http://spice-space.org/download/usbredir/usbredir-0.5.2.tar.bz2>`__, `0.5.1 <http://spice-space.org/download/usbredir/usbredir-0.5.1.tar.bz2>`__, -- 2.9.3 _______________________________________________ Spice-devel mailing list Spice-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/spice-devel