[Spice-devel] [PATCH spice-space-pages v3] Update usbredir documentation
Pavel Grunt
pgrunt at redhat.com
Wed Apr 19 08:59:46 UTC 2017
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
> > +++++++++++++++++++++++++++++++++++++++++++++++++++---
> > 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-referen
> > 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=doc
> > 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/usbredi
> > 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/usbre
> > 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