usbip-rs

A USB/IP tool and library for Linux. Share physical USB devices over vsock or TCP, or export simulated devices for testing.

Overview

usbip-rs provides:

CLI tool (usbip-rs) — pass through real USB devices from a host to a client over vsock or TCP, using Linux's vhci_hcd kernel module
Rust library (usbip-rs crate) — implement custom USB/IP device handlers, with built-in HID keyboard and CDC ACM serial examples

Supported transfer types: control, bulk and interrupt. Isochronous support is being worked on.

Building

With Nix

nix build

With Cargo

Requires libusb and libudev (Linux) system dependencies.

cargo build --release

The CLI binary is at target/release/usbip-rs.

Usage

The CLI has three top-level commands: client, host, and test_hid. Transport addresses use the format vsock:<port>, vsock:<cid>:<port>, tcp:<port>, or tcp:<host>:<port>.

Pass through a real USB device

On the client machine (needs vhci_hcd kernel module):

usbip-rs client listen tcp:3240

On the host machine (where the USB device is plugged in):

usbip-rs host connect tcp:<client-ip>:3240 1-2

The device argument is a bus ID (e.g. 1-2) or device path (e.g. /dev/bus/usb/001/002).

Test with a simulated HID keyboard

# Client side
usbip-rs client listen vsock:5000

# Host side (simulated keyboard, no real device needed)
usbip-rs test_hid connect vsock:5000

Library examples

The lib/examples/ directory contains standalone USB/IP servers using the library directly:

hid_keyboard — simulated HID keyboard
cdc_acm_serial — simulated CDC ACM serial device
host — physical device passthrough (legacy, single-device)

cargo run -p usbip-rs --example hid_keyboard

These listen on the standard USB/IP port and work with the Linux usbip userspace tools:

usbip list -r <host-ip>
usbip attach -r <host-ip> -b <bus-id>

Project structure

├── cli/          CLI binary (usbip-rs)
├── lib/          Library crate (usbip-rs)
│   ├── src/
│   └── examples/
└── flake.nix     Nix build

License

MIT — see LICENSE.

2.2 KiB Raw Blame History