USB/IP - ArchWiki

# USB/IP

From ArchWiki
Jump to navigation Jump to search

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 usbip.

## 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`.

List the connected devices:

    $ usbip list -l

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

    $ 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 and/or 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

### 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

If bus ids are inconsistent and dynamically assigned at each system boot, binding by USB 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 usbid 0924:3d68, one should start and/or enable `usbip-bind@0924:3d68.service`.

Note: Such a binding method can't work correctly for multiple devices with the same USB ID

Then client setup will be like this:

- Linux clients

    $ usbip attach -r server_IP_address --$(/usr/sbin/usbip list -p -l | grep '#usbid=0924:3d68#' | cut '-d#' -f1)

- 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

## Man page

See usbip(8).

## See also

- Official USB/IP project site
- Linux Kernel "README for usbip-utils"
- "How To Setup and use USB/IP"
- "USB/IP for Windows"

Category:

- Storage