USB/IP

From ArchWiki

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