# USB/IP

From ArchWiki
Jump to navigation Jump to search
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

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

Category:

- Storage