mirror of https://github.com/docker/docs.git
Add a manual on using USB/IP in DD (#21533)
## Description Add a manual on using USB/IP in DD ## Related issues or tickets ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review Signed-off-by: Piotr Stankiewicz <piotr.stankiewicz@docker.com>
This commit is contained in:
Piotr
GitHub
parent
95cb86f173
commit
655a6c855a
|
|
@ -0,0 +1,145 @@
|
|||
---
|
||||
title: Using USB/IP with Docker Desktop
|
||||
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/
|
||||
params:
|
||||
sidebar:
|
||||
badge:
|
||||
color: green
|
||||
text: New
|
||||
---
|
||||
|
||||
{{< introduced desktop 4.35.0 "../../desktop/release-notes.md#4350" >}}
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> Available on Docker Desktop for Mac, Linux, and Windows with the Hyper-V backend.
|
||||
|
||||
USB/IP enables you to share USB devices over the network, which can then be accessed from within Docker containers. This page focuses on sharing USB devices connected to the machine you run Docker Desktop on. You can repeat the following process to attach and use additional USB devices as needed.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> The Docker Desktop VM kernel image comes pre-configured with drivers for many common USB devices, but Docker can't guarantee every possible USB device will work with this setup.
|
||||
|
||||
## Setup and use
|
||||
|
||||
### Step one: Run a USB/IP server
|
||||
|
||||
To use USB/IP, you need to run a USB/IP server. For this guide, the implementation provided by [jiegec/usbip](https://github.com/jiegec/usbip) will be used.
|
||||
|
||||
1. Clone the repository.
|
||||
|
||||
```console
|
||||
$ git clone https://github.com/jiegec/usbip
|
||||
$ cd usbip
|
||||
```
|
||||
|
||||
2. Run the emulated Human Interface Device (HID) device example.
|
||||
|
||||
```console
|
||||
$ env RUST_LOG=info cargo run --example hid_keyboard
|
||||
```
|
||||
|
||||
### Step two: Start a privileged Docker container
|
||||
|
||||
To attach the USB device, start a privileged Docker container with the PID namespace set to `host`:
|
||||
|
||||
```console
|
||||
$ docker run --rm -it --privileged --pid=host alpine
|
||||
```
|
||||
|
||||
### Step three: Enter the mount namespace of PID 1
|
||||
|
||||
Inside the container, enter the mount namespace of the `init` process to gain access to the pre-installed USB/IP tools:
|
||||
|
||||
```console
|
||||
$ nsenter -t 1 -m
|
||||
```
|
||||
|
||||
### Step four: Use USB/IP tools
|
||||
|
||||
Now you can use the USB/IP tools as you would on any other system:
|
||||
|
||||
#### List USB devices
|
||||
|
||||
To list exportable USB devices from the host:
|
||||
|
||||
```console
|
||||
$ usbip list -r host.docker.internal
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```console
|
||||
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)
|
||||
```
|
||||
|
||||
#### Attach a USB device
|
||||
|
||||
To attach a specific USB device, or the emulated keyboard in this case:
|
||||
|
||||
```console
|
||||
$ usbip attach -r host.docker.internal -d 0-0-0
|
||||
```
|
||||
|
||||
#### Verify device attachment
|
||||
|
||||
After attaching the emulated keyboard, check the `/dev/input` directory for the device node:
|
||||
|
||||
```console
|
||||
$ ls /dev/input/
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```console
|
||||
event0 mice
|
||||
```
|
||||
|
||||
### Step five: 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 from another container. For example:
|
||||
|
||||
1. Start a new container with the attached device.
|
||||
|
||||
```console
|
||||
$ docker run --rm -it --device "/dev/input/event0" alpine
|
||||
```
|
||||
|
||||
2. Install a tool like `evtest` to test the emulated keyboard.
|
||||
|
||||
```console
|
||||
$ apk add evtest
|
||||
$ evtest /dev/input/event0
|
||||
```
|
||||
|
||||
3. Interact with the device, and observe the output.
|
||||
|
||||
Example output:
|
||||
|
||||
```console
|
||||
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 ------------
|
||||
...
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> The initial container must remain running to maintain the connection to the USB device. Exiting the container will stop the device from working.
|
||||
|
|
@ -63,8 +63,7 @@ For more information and examples, see [how to connect from a container to a ser
|
|||
|
||||
### Can I pass through a USB device to a container?
|
||||
|
||||
It is not possible to pass through a USB device (or a
|
||||
serial port) to a container as it requires support at the hypervisor level.
|
||||
Docker Desktop does not support direct USB device passthrough. However, you can use USB over IP to connect common USB devices to the Docker Desktop VM and in turn be forwarded to a container. For more details, see [Using USB/IP with Docker Desktop](/manuals/desktop/features/usbip.md).
|
||||
|
||||
### How do I run Docker Desktop without administrator privileges?
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue