[Spice-devel] [PATCH spice-space-pages] usbredir documentation
Snir Sheriber
ssheribe at redhat.com
Sun Mar 19 16:47:17 UTC 2017
---
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, at vendor, at product, at version, at 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
More information about the Spice-devel
mailing list