[Spice-devel] [PATCH spice-space-pages v3] Update usbredir documentation
Jonathon Jongsma
jjongsma at redhat.com
Tue Apr 18 14:29:54 UTC 2017
On Tue, 2017-04-18 at 12:08 +0300, Snir Sheriber wrote:
> ---
> Several fixes and typos
> ---
> page/UsbRedir.rst | 186
> +++++++++++++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 177 insertions(+), 9 deletions(-)
>
> diff --git a/page/UsbRedir.rst b/page/UsbRedir.rst
> index 958a086..5009970 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,197 @@ 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. Qemu supports both USB2 and USB3, but at the time of
> +writing, USB3 has had less testing. For USB2 support, the guest must
> +have a EHCI controller and companion UHCI controller (companion UHCI
> is needed
> +in order to support also USB1.x devices). For USB3 support, an XHCI
> controller
> +is required.
> +It also needs to have Spice channels for USB redirection. The number
> of such
> +channels determine the number of USB devices that it's 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/u
> sb2.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. If you only need to support USB2 devices, make sure
> its
> +model is set to "USB2". For USB 3.0 support, select "USB3" for the
> +model type.
> +
> +You can then click on "Add Hardware" and add "USB Redirection" items
> as the
> +number of USB devices you want to be able to redirect
> simultaneously.
> +
> +Using libvirt
> ++++++++++++++
> +
> +The following libvirt XML will configure a guest with USB2 support
> and the
> +ability to redirect 3 devices simultaneously:
> +
> +.. 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 USB3 support, the configuration can be simplified to:
> +
> +.. 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
> +++++++++++
> +
> +The following libvirt XML will configure a guest with USB2 support
> and the
> +ability to redirect 3 devices simultaneously
Looks like a little copy/paste error here. Should be "commandline" or
"qemu options" or something similar instead of "libvirt XML"
Aside from that, the rest looks good to me.
Acked-by: Jonathon Jongsma <jjongsma at redhat.com>
> +
> +.. 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 USB3 support, the configuration can be simplified to:
> +
> +.. 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" menu
> +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 used to set 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**
> +
> +A client's default auto-connect filter string is 0x03,-1,-1,-1,0|-
> 1,-1,-1,-1,1
> +
> +This 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 Filtering
> +^^^^^^^^^^^^^^^^
> +
> +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 Filtering
> +^^^^^^^^^^^^^^
> +
> +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 in a QEMU command, the filter string should use a **':'**
> character as
> +a separator within the rule.
> +
> +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/u
> sbredir-0.7.tar.bz2>`__
> + `usbredir-0.7.1.tar.bz2 <http://www.spice-space.org/download/usbr
> edir/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>`__,
More information about the Spice-devel
mailing list