Changeset 64187 in vbox for trunk/doc/manual

Timestamp:

Oct 10, 2016 1:20:32 PM (8 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

111175

Message:

Manual/AdvancedTopics: Add a section about USB/IP

File:

• trunk/doc/manual/en_US/user_AdvancedTopics.xml (modified) (1 diff)

trunk/doc/manual/en_US/user_AdvancedTopics.xml

@@ -4288 +4288 @@
   </sect1>
 
+  <sect1 id="usbip">
+    <title>Accessing USB devices exposed over the network with USB/IP</title>
+
+    <para>Starting with 5.1.0, VirtualBox supports passing through USB
+    devices which are exposed over the network using the USB over IP protocol
+    without needing to configure the client side provided by the kernel and
+    usbip tools. Furthermore this also works with VirtualBox running on any
+    supported host instead of just on Linux like it is the case with the official
+    client. </para>
+
+    <para>To enable support for passing through USB/IP devices the device server exporting
+    the devices must be added with the followig command:
+      <screen>VBoxManage usbdevsource add "Unique name" --backend "USBIP" --address "Device server"[:port]</screen>
+    USB devices exported on the device server are then accessile through the GUI
+    or VBoxManage just like any USB device attached locally. This can be used multiple times
+    to access different device servers.</para>
+
+    <para>To remove a device server the following command can be used:
+      <screen>VBoxManage usbdevsource remove "Unique name"</screen>
+    </para>
+
+    <sect2 id="usbip-setup-server">
+      <title>Setting up USB/IP support on a Linux system</title>
+
+      <para>This secton gives a brief overview on how to set up a Linux based system
+      to act as a USB device server. The system on the server requires the
+      <computeroutput>usbip-core.ko</computeroutput> and
+      <computeroutput>usbip-host.ko</computeroutput> kernel drivers
+      to be available and that the USB/IP tools package is installed.
+      How to install the necessary tools depends on the used distribution, for
+      Debian based systems the following command should install the required tools:
+      <screen>apt-get install usbip-utils</screen></para>
+
+      <para>Checking whether the necessary tools are installed can be done with
+      the following command which should produce a similar output like
+      in the example below:
+      <screen>
+$ usbip list -l
+ - busid 4-2 (0bda:0301)
+   Realtek Semiconductor Corp. : multicard reader (0bda:0301)
+
+ - busid 5-1 (046d:c52b)
+   Logitech, Inc. : Unifying Receiver (046d:c52b)
+      </screen></para>
+
+      <para>If everything is installed the USB/IP server needs to be started as
+      <computeroutput>root</computeroutput> with the following command,
+      consult the documentation of the used distribution on how to start the
+      service when the system boots:
+      <screen>usbipd -D</screen></para>
+
+      <para>By default no device on the server is exported which must be done manually
+      for each device. To export a device use: <screen>usbip bind -b "bus identifier"</screen>
+      To export the multicard reader from above for example use:
+      <screen>usbip bind -b 4-2</screen></para>
+    </sect2>
+
+    <sect2 id="usbip-security">
+      <title>Security considerations</title>
+
+      <para>The communiction between the server and client is not encrypted and
+      there is no authorization required to access exported devices. An attacker
+      might sniff sensitive data or gain control over a device. To mitigate this
+      risk the device should be exposed over a local network only trusted
+      clients have access to. To access the devie remotely over a public network
+      a VPN solution should be used to add the required protection.</para>
+    </sect2>
+  </sect1>
+
 </chapter>