USB/IP

From ArchWiki
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

From the USB/IP site:

USB/IP Project aims to develop a general USB device sharing system over IP network. To share USB devices between computers with their full functionality, USB/IP encapsulates "USB I/O messages" into TCP/IP payloads and transmits them between computers.

Installation

Install the usbip package.

Usage

Server setup

The server should have the physical USB device connected to it, and the usbip_host USB/IP kernel module loaded. Then start and enable the USB/IP systemd service usbipd.service. The daemon will accept connections on TCP port 3240.

List the connected devices: 

$ usbip list -l

Bind the required device. For example, to share the device having busid 1-1.5:

Note: The device needs to be bound again after suspending.
$ usbip bind -b 1-1.5

To unbind the device: 

$ usbip unbind -b 1-1.5

After binding, the device can be accessed from the client.

Binding with systemd service

In order to make binding persistent following systemd template unit file can be used: 

/etc/systemd/system/usbip-bind@.service
[Unit]
Description=USB-IP Binding on bus id %I
After=network-online.target usbipd.service
Wants=network-online.target
Requires=usbipd.service
#DefaultInstance=1-1.5

[Service]
Type=simple
ExecStart=/usr/bin/usbip bind -b %i
RemainAfterExit=yes
ExecStop=/usr/bin/usbip unbind -b %i  
Restart=on-failure

[Install]
WantedBy=multi-user.target

So, e.g., to share the device having busid 1-1, one should start/enable usbip-bind@1-1.service.

Client setup

Make sure the vhci-hcd kernel module is loaded.

Then list devices available on the server: 

$ usbip list -r server_IP_address

Attach the required device. For example, to attach the device having busid 1-1.5: 

$ usbip attach -r server_IP_address -b 1-1.5
Tip: To connect to an alternate TCP port use --tcp-port port.

Disconnecting devices

A device can be disconnected only after detaching it on the client.

List attached devices: 

$ usbip port

Detach the device: 

$ usbip detach -p port_number

Unbind the device on the server: 

$ usbip unbind -b busid
Note: USB/IP by default requires port 3240 to be open. If a firewall is running, make sure that this port is open. For detailed instruction on configuring the firewall, go to Category:Firewalls.

Tips and tricks

Binding by vendor/device ID

If bus ids are inconsistent and dynamically assigned at each system boot, binding by vendor/device ID can be used alternatively: 

/etc/systemd/system/usbip-bind@.service
[Unit]
Description=USB-IP Binding device id %I
After=network-online.target usbipd.service
Wants=network-online.target
Requires=usbipd.service

[Service]
Type=simple
ExecStart=/bin/sh -c "/usr/sbin/usbip bind --$(/usr/sbin/usbip list -p -l | grep '#usbid=%i#' | cut '-d#' -f1)"
RemainAfterExit=yes
ExecStop=/bin/sh -c "/usr/sbin/usbip unbind --$(/usr/sbin/usbip list -p -l | grep '#usbid=%i#' | cut '-d#' -f1)"
Restart=on-failure
 
[Install]
WantedBy=multi-user.target

So, e.g., to share the device having vendor/device ID 0924:3d68, one should start/enable usbip-bind@0924:3d68.service.

Note: Such a binding method cannot work correctly for multiple devices with the same vendor/device ID.

Then client setup will be like this:

  • Linux clients
$ usbip attach -r server_IP_address --$(/usr/sbin/usbip list -p -r server_IP_address | grep '#usbid=0924:3d68#' | cut '-d#' -f1)
Note: If the previous command fails, check if -p flag in usbip list -p -r server_IP_address is working properly. If not, use the following line instead: 
$ usbip attach -r server_IP_address -b $(/usr/sbin/usbip list -p -r server_IP_address | grep '0924:3d68' | cut '-d:' -f1 | awk '{print $1}')
  • Windows clients
c:\> for /f "tokens=1 delims=:, " %a in ('usbip list -r server_IP_address ^| findstr /r /c:"0924:3d68"') do start usbip attach -r server_IP_address -b %a

Sharing devices configured with files in /etc/..

usbip-systemdAUR provides systemd service files for binding by vendor/device id and for connecting by hostname and vendor/device id.

Server setup

For each device create a device.conf in /etc/usbip/bind-devices/ with USBIP_DEVICE set to the vendor/product id, e.g.: 

/etc/usbip/bind-devices/example-device.conf
USBIP_DEVICE=0924:3d68

To bind a cofigured device start/enable the service usbip-bind@example-device.service

Client setup

For each host/device create a device.conf in /etc/usbip/remote-devices/ with HOST set and USBIP_DEVICE set to the vendor/product id, e.g.: 

/etc/usbip/remote-devices/example-device.conf
USBIP_HOST=example-host
USBIP_DEVICE=0924:3d68

Make sure your server is running and the configured device is bound, then start or stop the service usbip@example-device.service

See also