Features/UsbNetworkRedirection

From FedoraProject

< Features(Difference between revisions)
Jump to: navigation, search
(Created page with "= USB redirection over the network == Summary == Allow redirecting a USB device to another machine over the network. For example use an USB webcam attached to machine A on mach...")
 
(Grammar fixes: then -> than)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= USB redirection over the network
+
= USB redirection over the network =
  
 
== Summary ==
 
== Summary ==
Line 13: Line 13:
 
== Current status ==
 
== Current status ==
 
* Targeted release: Fedora 16
 
* Targeted release: Fedora 16
* Last updated: Jun 27, 2011  
+
* Last updated: Sep 9, 2011  
* Percentage of completion: 25%
+
* Percentage of completion: 100%
  
 
== Detailed Description ==
 
== Detailed Description ==
 
The intend is to deliver the following for Fedora 16:
 
The intend is to deliver the following for Fedora 16:
* A usbredir package with libraries for:
+
* A usbredir package (done) with libraries for:
* parsing the usbnetredir protocol
+
** parsing the usbnetredir protocol
* redirecting a local attached usb-device through an application provided pipe
+
** redirecting a local attached usb-device through an application provided pipe
* Support for qemu to receive data from a usbredir pipe, and make the redirected USB device show up as being attached to the emulated host controller inside the virtual machine
+
* Support for qemu to receive data from a usbredir pipe, and make the redirected USB device show up as being attached to the emulated host controller inside the virtual machine (done)
 +
* Support for spice-server (done) and spice-gtk (the gtk spice client widget) to use usbredir
 +
* A nice UI for redirecting USB devices from a spice-gtk based virtual machine viewer (done, but only in spicy so far not in virt-manager / virt-viewer)
  
 
== Benefit to Fedora ==
 
== Benefit to Fedora ==
<!-- What is the benefit to the platform?  If this is a major capability update, what has changed?  If this is a new feature, what capabilities does it bring? Why will Fedora become a better distribution or project because of this feature?-->
+
Currently many Fedora users choose to not use qemu-kvm for virtual machines, but instead use a less open alternative not shipped with Fedora. One of the stated reasons for doing so is the less than stellar support for USB redirection with qemu-kvm. Besides adding support for USB redirection over the network, qemu's USB redirection support is being improved in general, including adding support for USB 2.
  
 
== Scope ==
 
== Scope ==
<!-- What work do the developers have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
+
The needed changes are isolated to the new usbredir package, qemu and spice. Work is already underway to try and get all changes upstream.
  
 
== How To Test ==
 
== How To Test ==
<!-- This does not need to be a full-fledged document. Describe the dimensions of tests that this feature is expected to pass when it is done.  If it needs to be tested with different hardware or software configurations, indicate them.  The more specific you can be, the better the community testing can be.  
+
First thing you need to do is download [http://cgit.freedesktop.org/spice/qemu/plain/docs/ich9-ehci-uhci.cfg this] file, and drop it in /etc/qemu.
  
Remember that you are writing this how to for interested testers to use to check out your feature - documenting what you do for testing is OK, but it's much better to document what *I* can do to test your feature.
+
Then create a new spice-enabled vm using using virt-manager, select spice as display type and qxl as video card model,
 +
when asked if you want to enable the agent channel, say yes.
  
A good "how to test" should answer these four questions:
+
When done, close virt-manager and edit the relevant /etc/libvirt/qemu/foo.xml file. Change the first line from:
 +
<pre><domain type='kvm'></pre>
 +
to:
 +
<pre><domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'></pre>
  
0. What special hardware / data / etc. is needed (if any)?
+
And add the following lines at the end, above the "<code></domain></code>" line:
1. How do I prepare my system to test this feature? What packages
+
 
need to be installed, config files edited, etc.?
+
<pre>
2. What specific actions do I perform to check that the feature is
+
  <qemu:commandline>
working like it's supposed to?
+
    <qemu:arg value='-readconfig'/>
3. What are the expected results of those actions?
+
    <qemu:arg value='/etc/qemu/ich9-ehci-uhci.cfg'/>
-->
+
    <qemu:arg value='-chardev'/>
 +
    <qemu:arg value='spicevmc,name=usbredir,id=usbredirchardev1'/>
 +
    <qemu:arg value='-device'/>
 +
    <qemu:arg value='usb-redir,chardev=usbredirchardev1,id=usbredirdev1,bus=ehci.0,debug=3'/>
 +
    <qemu:arg value='-chardev'/>
 +
    <qemu:arg value='spicevmc,name=usbredir,id=usbredirchardev2'/>
 +
    <qemu:arg value='-device'/>
 +
    <qemu:arg value='usb-redir,chardev=usbredirchardev2,id=usbredirdev2,bus=ehci.0,debug=3'/>
 +
    <qemu:arg value='-chardev'/>
 +
    <qemu:arg value='spicevmc,name=usbredir,id=usbredirchardev3'/>
 +
    <qemu:arg value='-device'/>
 +
    <qemu:arg value='usb-redir,chardev=usbredirchardev3,id=usbredirdev3,bus=ehci.0,debug=3'/>
 +
  </qemu:commandline>
 +
</pre>
 +
 
 +
Then close down any virtual machines you may have open, and restart libvirt:
 +
<pre>sudo service libvirtd restart</pre>
 +
 
 +
Now start the vm with virt-manager, open it, select the details view, click on Display Spice and lookup and remember the port mentioned there (this will be 5900 if it is the only running vm).
 +
 
 +
Close virt-manager, and connect to the vm with spicy, like this:
 +
<pre>sudo spicy -h localhost -p 5900</pre>
 +
 
 +
Where 5900 should be replaced by the port the vm is actually running on. Note that you need to start spicy as root, so that it can access the device nodes under <code>/dev/bus/usb</code>.
 +
 
 +
Select the options menu entry and make sure that the "auto redirect newly plugged in USB devices" option is checked. After this make sure the vm has keyboard focus (so close the options menu), plug in a new USB device and watch it show up in your vm :) Feel free to yank it out again at any time :)
 +
 
 +
If you plug in a device while the vm does not have keyboard focus, it will not get redirected, so you can use usb devices
 +
normally as long as you don't have the vm focussed when you plug them in.
 +
 
 +
Enjoy, and be sure to send any feedback you may have my way!
  
 
== User Experience ==
 
== User Experience ==
<!-- If this feature is noticeable by its target audience, how will their experiences change as a result?  Describe what they will see or notice. -->
+
Users wishing to redirect USB devices to virtual machines can do so easily from the virtual machine viewer UI, and can do so even when connected to
 +
the virtual machine from another machine than the host.
  
 
== Dependencies ==
 
== Dependencies ==
<!-- What other packages (RPMs) depend on this package?  Are there changes outside the developers' control on which completion of this feature depends?  In other words, completion of another feature owned by someone else and might cause you to not be able to finish on time or that you would need to coordinate?  Other upstream projects like the kernel (if this is not a kernel feature)? -->
+
None
  
 
== Contingency Plan ==
 
== Contingency Plan ==
<!-- If you cannot complete your feature by the final development freeze, what is the backup plan?  This might be as simple as "None necessary, revert to previous release behaviour." Or it might not. If you feature is not completed in time we want to assure others that other parts of Fedora will not be in jeopardy. -->
+
The plan is to deliver the various bits mentioned under "Detailed Description" one by one. If time runs out before we can deliver the lower bullets, the
 +
already delivered bits will stay in place and can still be used, but only from the cmdline rather than from a nice integrated UI experience.
  
 
== Documentation ==
 
== Documentation ==
<!-- Is there upstream documentation on this feature, or notes you have written yourself?  Link to that material here so other interested developers can get involved. -->
+
See:
*
+
* http://hansdegoede.livejournal.com/9682.html
 +
* http://people.fedoraproject.org/~jwrdegoede/usb-redir.pdf
 +
* http://cgit.freedesktop.org/~jwrdegoede/usbredir/tree/usb-redirection-protocol.txt
  
 
== Release Notes ==
 
== Release Notes ==
<!-- The Fedora Release Notes inform end-users about what is new in the release. Examples of past release notes are here: http://docs.fedoraproject.org/release-notes/ -->
+
Fedora 16 now comes with improved USB support for qemu-kvm virtual machines. The virtual machines are now capable of emulating or passing through USB 2 devices. It is now
<!-- The release notes also help users know how to deal with platform changes such as ABIs/APIs, configuration or data file formats, or upgrade concerns. If there are any such changes involved in this feature, indicate them here.  You can also link to upstream documentation if it satisfies this need.  This information forms the basis of the release notes edited by the documentation team and shipped with the release. -->
+
also possible to redirect a USB device over the network, this allows passing through a USB device from another pc than the host to a virtual machine. See:  
*
+
http://fedoraproject.org/wiki/Features/UsbNetworkRedirection for detailed instructions on how to enable these new features.
  
 
== Comments and Discussion ==
 
== Comments and Discussion ==
* See [[Talk:Features/YourFeatureName]] <!-- This adds a link to the "discussion" tab associated with your page.  This provides the ability to have ongoing comments or conversation without bogging down the main feature page -->
+
* See [[Talk:Features/YourFeatureName]]
 
+
  
[[Category:FeaturePageIncomplete]]
+
[[Category:FeatureAcceptedF16]]
<!-- When your feature page is completed and ready for review -->
+
<!-- remove Category:FeaturePageIncomplete and change it to Category:FeatureReadyForWrangler -->
+
<!-- After review, the feature wrangler will move your page to Category:FeatureReadyForFesco... if it still needs more work it will move back to Category:FeaturePageIncomplete-->
+
<!-- A pretty picture of the page category usage is at: https://fedoraproject.org/wiki/Features/Policy/Process -->
+

Latest revision as of 13:56, 9 March 2012

Contents

[edit] USB redirection over the network

[edit] Summary

Allow redirecting a USB device to another machine over the network. For example use an USB webcam attached to machine A on machine B. For Fedora 16 the focus will be on allowing using USB devices attached to some machine (not necessarily the host machine) inside a qemu-kvm virtual machine.

[edit] Owner

  • Name: Hans de Goede
  • Email: hdegoede@redhat.com

[edit] Current status

  • Targeted release: Fedora 16
  • Last updated: Sep 9, 2011
  • Percentage of completion: 100%

[edit] Detailed Description

The intend is to deliver the following for Fedora 16:

  • A usbredir package (done) with libraries for:
    • parsing the usbnetredir protocol
    • redirecting a local attached usb-device through an application provided pipe
  • Support for qemu to receive data from a usbredir pipe, and make the redirected USB device show up as being attached to the emulated host controller inside the virtual machine (done)
  • Support for spice-server (done) and spice-gtk (the gtk spice client widget) to use usbredir
  • A nice UI for redirecting USB devices from a spice-gtk based virtual machine viewer (done, but only in spicy so far not in virt-manager / virt-viewer)

[edit] Benefit to Fedora

Currently many Fedora users choose to not use qemu-kvm for virtual machines, but instead use a less open alternative not shipped with Fedora. One of the stated reasons for doing so is the less than stellar support for USB redirection with qemu-kvm. Besides adding support for USB redirection over the network, qemu's USB redirection support is being improved in general, including adding support for USB 2.

[edit] Scope

The needed changes are isolated to the new usbredir package, qemu and spice. Work is already underway to try and get all changes upstream.

[edit] How To Test

First thing you need to do is download this file, and drop it in /etc/qemu.

Then create a new spice-enabled vm using using virt-manager, select spice as display type and qxl as video card model, when asked if you want to enable the agent channel, say yes.

When done, close virt-manager and edit the relevant /etc/libvirt/qemu/foo.xml file. Change the first line from:

<domain type='kvm'>

to:

<domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>

And add the following lines at the end, above the "</domain>" line:

  <qemu:commandline>
     <qemu:arg value='-readconfig'/>
     <qemu:arg value='/etc/qemu/ich9-ehci-uhci.cfg'/>
     <qemu:arg value='-chardev'/>
     <qemu:arg value='spicevmc,name=usbredir,id=usbredirchardev1'/>
     <qemu:arg value='-device'/>
     <qemu:arg value='usb-redir,chardev=usbredirchardev1,id=usbredirdev1,bus=ehci.0,debug=3'/>
     <qemu:arg value='-chardev'/>
     <qemu:arg value='spicevmc,name=usbredir,id=usbredirchardev2'/>
     <qemu:arg value='-device'/>
     <qemu:arg value='usb-redir,chardev=usbredirchardev2,id=usbredirdev2,bus=ehci.0,debug=3'/>
     <qemu:arg value='-chardev'/>
     <qemu:arg value='spicevmc,name=usbredir,id=usbredirchardev3'/>
     <qemu:arg value='-device'/>
     <qemu:arg value='usb-redir,chardev=usbredirchardev3,id=usbredirdev3,bus=ehci.0,debug=3'/>
  </qemu:commandline>

Then close down any virtual machines you may have open, and restart libvirt:

sudo service libvirtd restart

Now start the vm with virt-manager, open it, select the details view, click on Display Spice and lookup and remember the port mentioned there (this will be 5900 if it is the only running vm).

Close virt-manager, and connect to the vm with spicy, like this:

sudo spicy -h localhost -p 5900

Where 5900 should be replaced by the port the vm is actually running on. Note that you need to start spicy as root, so that it can access the device nodes under /dev/bus/usb.

Select the options menu entry and make sure that the "auto redirect newly plugged in USB devices" option is checked. After this make sure the vm has keyboard focus (so close the options menu), plug in a new USB device and watch it show up in your vm :) Feel free to yank it out again at any time :)

If you plug in a device while the vm does not have keyboard focus, it will not get redirected, so you can use usb devices normally as long as you don't have the vm focussed when you plug them in.

Enjoy, and be sure to send any feedback you may have my way!

[edit] User Experience

Users wishing to redirect USB devices to virtual machines can do so easily from the virtual machine viewer UI, and can do so even when connected to the virtual machine from another machine than the host.

[edit] Dependencies

None

[edit] Contingency Plan

The plan is to deliver the various bits mentioned under "Detailed Description" one by one. If time runs out before we can deliver the lower bullets, the already delivered bits will stay in place and can still be used, but only from the cmdline rather than from a nice integrated UI experience.

[edit] Documentation

See:

[edit] Release Notes

Fedora 16 now comes with improved USB support for qemu-kvm virtual machines. The virtual machines are now capable of emulating or passing through USB 2 devices. It is now also possible to redirect a USB device over the network, this allows passing through a USB device from another pc than the host to a virtual machine. See: http://fedoraproject.org/wiki/Features/UsbNetworkRedirection for detailed instructions on how to enable these new features.

[edit] Comments and Discussion