[Spice-devel] [PATCH spice-space-pages v2] Update usbredir documentation
Snir Sheriber
ssheribe at redhat.com
Wed Apr 12 12:39:50 UTC 2017
---
Changes from v1: adding xhci configuration and some fixes
---
page/UsbRedir.rst | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 175 insertions(+), 9 deletions(-)
diff --git a/page/UsbRedir.rst b/page/UsbRedir.rst
index 958a086..3a09967 100644
--- a/page/UsbRedir.rst
+++ b/page/UsbRedir.rst
@@ -1,10 +1,8 @@
usbredir
###############################################################################
-:slug: usbredir
-
-usbredir is the name of a network protocol for sending usb device
+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
package offering a parsing library, a usbredirhost library and several
utilities implementing this protocol.
@@ -16,27 +14,195 @@ this document also explains what is meant with a usbhost and a usbguest.
usbredir was created for use with Spice, which is why it is hosted on
spice-space.org, but the protocol and the usbredirhost are completely
independent of spice, they could for example also be used to create a
-vnc extension for redirecting usb devices over a vnc connection to a
+vnc extension for redirecting USB devices over a vnc connection to a
qemu virtual machine.
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 a filter string
+
+
+Host Configuration
+^^^^^^^^^^^^^^^^^^
+
+For redirection to work, the virtual machine must have a supported USB
+controller (EHCI controller + companion UHCI controllers setup is recommended).
+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.
+
+More information about USB controllers in qemu could be found
+`here <http://git.qemu-project.org/?p=qemu.git;a=blob_plain;f=docs/usb2.txt;hb=HEAD>`__.
+
+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.
+
+For USB version 3.0 you may want to give a try to the XHCI controller (less
+tested), therefore you should select "USB3" in the model type instead of "USB2".
+
+Using libvirt
++++++++++++++
+
+Up to 3 simultaneously redirected devices configuration
+
+.. 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'/>
+
+For USB version 3.0 you may want to give a try to the XHCI controller (less
+tested) instead
+
+.. code-block:: sh
+
+ <controller type='usb' index='0' model='nec-xhci'/>
+ <redirdev bus='usb' type='spicevmc'/>
+ <redirdev bus='usb' type='spicevmc'/>
+ <redirdev bus='usb' type='spicevmc'/>
+
+Using QEMU
+++++++++++
+
+Up to 3 simultaneously redirected devices configuration
+
+.. 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
+
+For USB version 3.0 you may want to give a try to the XHCI controller (less
+tested) instead
+
+.. code-block:: sh
+
+ -device nec-usb-xhci,id=usb \
+ -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 Configuration
+^^^^^^^^^^^^^^^^^^^^
+
+The client needs to have support for USB redirection. In remote-viewer, you can
+select which USB devices to redirect under the "File->USB device selection" manu
+once the Spice connection is established. There are also various command line
+redirection options which are described below and 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
+are **allowed\\blocked** to redirect USB traffic to the guest.
+
+.. code-block:: sh
+
+ remote-viewer --spice-usbredir-auto-redirect-filter="0x03,-1,-1,-1,0|-1,-1,-1,-1,1"
+
+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
-++++++++
+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