Add a manual on using USB/IP in DD

Signed-off-by: Piotr Stankiewicz <[email protected]>

Author: Piotr Stankiewicz

content/manuals/desktop/features/usbip.md

@@ -0,0 +1,140 @@
+linkTitle: USB/IP support
+weight: 80
+description: How to use USB/IP in Docker Desktop
+keywords: usb, usbip, docker desktop, macos, windows, linux
+toc_max: 3
+aliases:
+- /desktop/usbip/
+---
+
+> [!NOTE]
+>
+> This guide applies to all Docker Desktop backends apart from WSL2.
+
+# Using USB/IP with Docker Desktop
+
+This guide explains how to use USB/IP in Docker Desktop. USB/IP enables you to share USB devices over IP, which can then be accessed from within Docker containers.
+
+## Prerequsites
+
+- Docker Desktop version 4.35 or higher installed and confugured to use a backend other than WSL2
+
+## Steps to Use USB/IP
+
+### 1. Run a USB/IP Server
+
+To use USB/IP, you need to run a USB/IP server. For this guide, we'll use the implementation provided by [jiegec/usbip](https://github.com/jiegec/usbip). Follow these steps:
+
+1. Clone the repository:
+
+    ```bash
+    git clone https://github.com/jiegec/usbip
+    cd usbip
+    ```
+
+2. Run the emulated HID (Human Interface Device) device example:
+
+    ```bash
+    env RUST_LOG=info cargo run --example hid_keyboard
+    ```
+
+### 2. Start a Privileged Docker Container
+
+To attach the USB device, start a privileged Docker container with the PID namespace set to `host`:
+
+```bash
+docker run --rm -it --privileged --pid=host alpine
+```
+
+### 3. Enter the Mount Namespace of the Init Process
+
+Inside the container, enter the mount namespace of the `init` process to gain access to the pre-installed USB/IP tools:
+
+```bash
+nsenter -t 1 -m
+```
+
+### 4. Use USB/IP Tools
+
+Now you can use the USB/IP tools as you would on any other system.
+
+#### a. List USB Devices
+
+To list exportable USB devices from the host:
+
+```bash
+usbip list -r host.docker.internal
+```
+
+Expected output:
+
+```
+Exportable USB devices
+======================
+ - host.docker.internal
+      0-0-0: unknown vendor : unknown product (0000:0000)
+           : /sys/bus/0/0/0
+           : (Defined at Interface level) (00/00/00)
+           :  0 - unknown class / unknown subclass / unknown protocol (03/00/00)
+```
+
+#### b. Attach a USB Device
+
+To attach a specific USB device, or the emulated keyboard in our case:
+
+```bash
+usbip attach -r host.docker.internal -d 0-0-0
+```
+
+#### c. Verify Device Attachment
+
+After attaching the emulated keyboard, check the `/dev/input` directory for the device node:
+
+```bash
+ls /dev/input/
+```
+
+Example output:
+
+```
+event0  mice
+```
+
+### 5. Use the Attached Device in Another Container
+
+While the initial container remains running (to keep the USB device operational), you can access the attached device in another container. For example:
+
+1. Start a new container with the attached device:
+
+    ```bash
+    docker run --rm -it --device "/dev/input/event0" alpine
+    ```
+
+2. Install a tool like `evtest` to test the emulated keyboard:
+
+    ```bash
+    apk add evtest
+    evtest /dev/input/event0
+    ```
+
+3. Interact with the device, and observe the output:
+
+    Example output:
+
+    ```
+    Input driver version is 1.0.1
+    Input device ID: bus 0x3 vendor 0x0 product 0x0 version 0x111
+    ...
+    Properties:
+    Testing ... (interrupt to exit)
+    Event: time 1717575532.881540, type 4 (EV_MSC), code 4 (MSC_SCAN), value 7001e
+    Event: time 1717575532.881540, type 1 (EV_KEY), code 2 (KEY_1), value 1
+    Event: time 1717575532.881540, -------------- SYN_REPORT ------------
+    ...
+    ```
+
+### Notes
+
+- The initial container must remain running to maintain the connection to the USB device. Exiting the container will stop the device from working.
+- You can repeat the process to attach and use additional USB devices as needed.
+- The Docker Desktop VM kernel image comes pre-configured with drivers for many common USB devices, but we can not guarantee every possible USB device will work with this set up.