Share and Attach USB Devices with usbip

A USB dongle is plugged into the wrong machine and moving it physically is not an option: usbip exports it over the network instead. This walkthrough exports a device on one host, finds it from another, attaches it, checks the imported port, then detaches it cleanly without unplugging anything. Allow about 20 minutes, plus time to identify the correct USB device.

This guide uses the command syntax in the installed usbip(8) manual. On this machine, the manual comes from linux-tools-common version 6.8.0-142.142. The installed /usr/bin/usbip is a version wrapper, and this host is running kernel 6.8.0-139 without the matching kernel-specific tool. If your command prints a warning that usbip is missing for the running kernel, install the matching tools through your normal package process before continuing. The wrapper's presence is not proof of a working client.

1. Decide which host is the server

The server is the machine with the physical USB device. It exports that device. The client is the machine that will use the device through its local USB/IP virtual host controller.

You need a reachable server, a USB device that no local application currently needs, and the USB/IP kernel support and userspace tools on both hosts. The Linux kernel project's USB/IP documentation describes the server-side host driver, the client-side virtual host controller, and the userspace utilities as separate parts. A server also needs its USB/IP daemon running before a remote client can discover an export.

Check the tool before changing anything:

$ command -v usbip
/usr/bin/usbip
$ usbip version
usbip version output depends on the matching kernel-specific tool

The second result is deliberately host-specific. If it ends with a missing-tool warning or a non-zero status, stop and resolve the kernel package mismatch first. Check the actual status with:

$ usbip version
$ printf 'status: %s\n' "$?"

Checkpoint: Continue only when usbip version reaches the real program rather than the wrapper warning.

2. Find the server's USB bus ID

Run this on the server. It only lists local USB devices:

server$ usbip list --local

Read the list and pick out the exact bus ID belonging to the device you intend to share, such as 1-2. Do not choose by a familiar product name alone if several devices look alike; confirm the physical device and its bus ID before binding it.

The bus ID is not the USB vendor or product ID. It is the identifier accepted by --busid. Record it for the next step. If the list is empty, check that the device is connected and visible to the server's normal USB tools, then check the USB/IP host support before attempting a bind.

3. Bind the device for export

Binding changes the device's driver assignment so USB/IP can export it. This is a service-disrupting action: any local program using the device can lose access. Close that program first, and use elevated privileges only for this operation:

server$ sudo usbip bind --busid=1-2

Replace 1-2 with the bus ID you recorded. A successful command normally returns to the shell without a long report. Verify the assignment by listing local devices again:

server$ usbip list --local

Look for the selected bus ID and confirm it is shown as available through the USB/IP host driver. If binding fails, stop rather than trying random bus IDs: the device may be in use, the host driver may be absent, or the command may not have enough privilege.

To undo this server-side change and return the device to its local driver, use the matching unbind command:

server$ sudo usbip unbind --busid=1-2

Warning: Only unbind after any remote client has detached the device. Unbinding a device while it is in use can interrupt the client and the application using it.

4. Discover the export from the client

Run the remote listing on the client. The host value is a name or address resolvable from the client:

client$ usbip list --remote=usb-server.example
- busid 1-2 (vendor:product)
  device description supplied by the server

The description and formatting vary with the device and tool version. What matters is that the chosen bus ID appears in the server's export list. If the connection fails, check name resolution, routing and the USB/IP daemon on the server. If the list connects but the expected device is absent, go back to the server and verify the bind.

USB/IP uses a TCP port. The default is used unless you supply the global option --tcp-port PORT, which goes before the command when you need a non-default port:

client$ usbip --tcp-port 4000 list --remote=usb-server.example

Use the same port choice for the later attach. Keep the service reachable only from the networks that need it, and protect the transport with your existing network controls; the usbip command itself is not an access policy for the server.

5. Attach the device on the client

Make the virtual USB host controller available, then attach the exact bus ID from the remote listing:

client$ sudo modprobe vhci-hcd
client$ sudo usbip attach --remote=usb-server.example --busid=1-2

The module command changes kernel state, so it normally needs elevated privileges. The attach command imports the remote device and also normally needs privilege. Do not run it twice just because the first command's output was quiet; check the imported ports instead:

client$ usbip port

Find the new imported device and note its local USB/IP port number. The port number is not necessarily the server bus ID. This is a common error trap: --busid identifies the exported device on the server, while --port identifies the imported connection on the client.

At this point, inspect the client with ordinary USB tools and start the application that needs the device. Keep the server-side physical device untouched while the client is using it.

6. Detach and restore the server

Once the client application has stopped using the device, detach the imported connection. This is the irreversible point for the current client session, so save any data handled by the USB device first:

client$ usbip port
client$ sudo usbip detach --port=0

Replace 0 with the imported port shown by your own usbip port output. Verify that the port no longer lists an imported device:

client$ usbip port

If the device should no longer be shared, return to the server and unbind the recorded bus ID:

server$ sudo usbip unbind --busid=1-2

There is no need to unbind merely because one client detached, if you intend to serve the same device again. Do not unbind while another client still depends on it.

Common failure checks

• Kernel-version warning from /usr/bin/usbip. The wrapper could not find the matching binary. Install the tools for the running kernel, then repeat usbip version.
• Empty local list. The device is not visible to USB/IP on the server. Check the cable, ordinary USB enumeration and the host driver before binding.
• Missing remote entry. The device was not exported, the client reached the wrong server, or the server daemon is not serving the expected port.
• Attach error after a successful listing. The virtual host controller may be unavailable, the device may already be imported, or the bus ID may be mistyped.
• Application stops seeing the device. Run usbip port on the client before detaching or rebinding, and keep the server-side device bound until the client is finished.

Done means

• Tooling matched. The client and server both run a kernel-matched usbip tool.
• Bus ID confirmed. The server's exact bus ID was listed and deliberately bound.
• Export found. The client found that export with usbip list --remote.
• Attach verified. The device was attached after loading vhci-hcd, then confirmed with usbip port.
• Clean teardown. The client detached by the imported port number before the server was unbound.