[Spice-devel] [PATCH spice-space-pages v3] Update usbredir documentation

Jonathon Jongsma jjongsma at redhat.com
Wed Apr 19 15:04:00 UTC 2017 

On Wed, 2017-04-19 at 10:59 +0200, Pavel Grunt wrote:
> Hi Snir,
> 
> On Tue, 2017-04-18 at 09:29 -0500, Jonathon Jongsma wrote:
> > On Tue, 2017-04-18 at 12:08 +0300, Snir Sheriber wrote:
> 
> 
> You can add
> 
> Closes #3
> > > ---
> > > Several fixes and typos
> > > ---
> > >  page/UsbRedir.rst | 186
> 
> do not create it in subdirectory, rename it to usbredir.rst

Hmm, it seems that this patch is against the 'wiki' branch perhaps?

> 
> > > +++++++++++++++++++++++++++++++++++++++++++++++++++---
> > >  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
> 
> keep the slug, it is used by pelican for generating the html page
> 
> > >  
> > > -
> > > -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-refere
> > > n
> > > ce/
> > > 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=do
> > > c
> > > s/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/usbred
> > > i
> > > r/u
> > > sbredir-0.7.tar.bz2>`__
> > > +   `usbredir-0.7.1.tar.bz2 <http://www.spice-space.org/download/
> > > u
> > > sbr
> > > 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/usbr
> > > e
> > > dir
> > > /usbredir-0.4.4.tar.bz2>`__
> > >  
> > >  Older versions:
> > > +`0.7 <http://spice-space.org/download/usbredir/usbredir-0.7.tar.
> > > b
> > > z2>
> > > `__,
> > >  `0.6 <http://spice-space.org/download/usbredir/usbredir-0.6.tar.
> > > b
> > > z2>
> > > `__,
> > >  `0.5.2 <http://spice-space.org/download/usbredir/usbredir-0.5.2.
> > > t
> > > ar.
> > > bz2>`__,
> > >  `0.5.1 <http://spice-space.org/download/usbredir/usbredir-0.5.1.
> > > t
> > > ar.
> > > bz2>`__,
> > 
> > _______________________________________________
> > Spice-devel mailing list
> > Spice-devel at lists.freedesktop.org
> > https://lists.freedesktop.org/mailman/listinfo/spice-devel

More information about the Spice-devel mailing list