Tuesday, February 2, 2010

How To Set Up A USB-Over-IP Server And Client With Debian Lenny

This tutorial shows how to set up a USB-over-IP server with Debian Lenny as well as a USB-over-IP client (also running Debian Lenny).

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

USB-over-IP can be useful for virtual machines, for example, that don't have access to the host system's hardware - USB-over-IP allows virtual machines to use remote USB devices.

I do not issue any guarantee that this will work for you!


1 Preliminary Note
This tutorial is based on AliRezaTaleghani's tutorial How To Modify Your Gnu/Linux Box To Serve As A USB Over IP Server, but I've adjusted it for Debian Lenny (server and client).

If you want to use a Windows client, please take a look at AliRezaTaleghani's tutorial - that part is still the same.

In this tutorial I use the server server1.example.com with the IP address 192.168.0.100 and the client client1.example.com with the IP address 192.168.0.101, both running Debian Lenny.

These settings might differ for you, so you have to replace them where appropriate.


2 Installing And Using USB/IP On The Server
server1:
There's a usbip package for Debian Squeeze (testing), but not for Lenny. To install the usbip package from Squeeze on Lenny, we modify the following three files (take a look at my tutorial A Short Introduction To Apt-Pinning to understand what I'm doing here):

# vi /etc/apt/sources.list

Add the Debian Squeeze (testing) repositories at the end of the file:

[...]
## Squeeze / Testing
deb http://ftp2.de.debian.org/debian/ squeeze main
deb-src http://ftp2.de.debian.org/debian/ squeeze main

deb http://security.debian.org/ squeeze/updates main
deb-src http://security.debian.org/ squeeze/updates main

# vi /etc/apt/apt.conf

Put the following line into this file:

APT::Cache-Limit "100000000";

# vi /etc/apt/preferences

Make the file look as follows:

Package: *
Pin: release a=stable
Pin-Priority: 700

Package: *
Pin: release a=testing
Pin-Priority: 650

Update the package database...

# aptitude update

... and install usbip as follows:

aptitude install usbip usbip-source module-assistant

We need to build the usbip kernel modules for our Debian Lenny kernel, that's why we must install the usbip-source and module-assistant packages as well. We can now build the kernel modules as follows:

# m-a prepare
# m-a update
# m-a a-i usbip-source

Afterwards we load the usbip kernel modules:

# modprobe usbip
# modprobe usbip_common_mod

To check if they really got loaded, run:

# lsmod | grep usbip

The output should be similar to this one:

server1:~# lsmod | grep usbip
usbip                  18660  0
usbip_common_mod       17672  1 usbip
server1:~#

To make sure that both modules get loaded automatically whenever you boot the system, you can add them to /etc/modules:

# vi /etc/modules

[...]
usbip
usbip_common_mod

Now we can start the usbip daemon:

# usbipd -D
server1:~# usbipd -D

Bind usbip.ko to a usb device to be exportable!

server1:~#

Now attach a USB device that you want to export to the server - I'm using a SanDisk USB flash drive here.
Execute the command

# lsusb

to find the corresponding Vendor/Device ID which is in the form of:

Bus XXX Device YYY: ID VendorID:DeviceID

The output on my server is as follows:

server1:~# lsusb

Bus 004 Device 002: ID 0781:5151 SanDisk Corp. Cruzer Micro 256/512MB Flash Drive
Bus 004 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 003 Device 002: ID 058f:6362 Alcor Micro Corp. Hi-Speed 21-in-1 Flash Card Reader/Writer (Internal/External)
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 001 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
server1:~#

The Vendor/Device ID of my SanDisk USB flash drive is 0781:5151.

Now run

# usbip_bind_driver --list

The output on my server is as follows:
server1:~# usbip_bind_driver --list

List USB devices
 - busid 3-4 (058f:6362)
         3-4:1.0 -> usb-storage

 - busid 4-5 (0781:5151)
         4-5:1.0 -> usb-storage

server1:~#

As you see, the Vendor/Device ID of my SanDisk USB flash drive (0781:5151) corresponds to the BUSID 4-5. We need this BUSID to attach the USB device to the server:

# usbip_bind_driver --usbip 4-5

server1:~# usbip_bind_driver --usbip 4-5
** (process:7290): DEBUG:  4-5:1.0      -> usb-storage
** (process:7290): DEBUG: unbinding interface
** (process:7290): DEBUG: write "add 4-5" to /sys/bus/usb/drivers/usbip/match_busid
** Message: bind 4-5 to usbip, complete!
server1:~#

That's it, we can now use the SanDisk USB flash drive on a remote usbip client.
BTW, if you run...

# netstat -tap

... you should see that the usbip daemon is listening on port 3240 so please make sure that this port isn't blocked by your firewall:

server1:~# netstat -tap

Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 *:sunrpc                *:*                     LISTEN      2062/portmap
tcp        0      0 *:49008                 *:*                     LISTEN      2073/rpc.statd
tcp        0      0 *:ssh                   *:*                     LISTEN      3244/sshd
tcp        0      0 localhost.localdom:smtp *:*                     LISTEN      2546/exim4
tcp        0    172 192.168.0.15:ssh        192.168.0.199:4176      ESTABLISHED 3204/0
tcp        0    148 server1.example.com:ssh 192.168.0.199:4177      ESTABLISHED 3245/1
tcp6       0      0 [::]:3240               [::]:*                  LISTEN      7254/usbipd
tcp6       0      0 [::]:ssh                [::]:*                  LISTEN      3244/sshd

server1:~#


3 Installing And Using USB/IP On The Client
client1:
First we must install usbip on the client. The steps are the same as on the server:

# vi /etc/apt/sources.list

Add the Debian Squeeze (testing) repositories at the end of the file:

[...]
## Squeeze / Testing
deb http://ftp2.de.debian.org/debian/ squeeze main
deb-src http://ftp2.de.debian.org/debian/ squeeze main

deb http://security.debian.org/ squeeze/updates main
deb-src http://security.debian.org/ squeeze/updates main

# vi /etc/apt/apt.conf

Put the following line into this file:

APT::Cache-Limit "100000000";

# vi /etc/apt/preferences

Make the file look as follows:

Package: *
Pin: release a=stable
Pin-Priority: 700

Package: *
Pin: release a=testing
Pin-Priority: 650

Update the package database...

# aptitude update

... and install usbip as follows:

# aptitude install usbip usbip-source module-assistant

We need to build the usbip kernel modules for our Debian Lenny kernel, that's why we must install the usbip-source and module-assistant packages as well. We can now build the kernel modules as follows:

# m-a prepare
# m-a update
# m-a a-i usbip-source

Afterwards we load the vhci-hcd kernel module:

# modprobe vhci-hcd

To check if it really got loaded, run:

# lsmod | grep vhci_hcd

The output should be similar to this one:

client1:~# lsmod | grep vhci_hcd
vhci_hcd               15844  0
usbip_common_mod       11332  1 vhci_hcd
usbcore               118160  2 vhci_hcd

client1:~#

To make sure that the module gets loaded automatically whenever you boot the system, you can add it to /etc/modules:

# vi /etc/modules

[...]
vhci-hcd

Now connect to the usbip server and get a list of available USB devices:

# usbip -l 192.168.0.100

(192.168.0.100 is the IP address of the usbip server.)
You should find the SanDisk USB flash drive in the output (BUSID 4-5):

client1:~# usbip -l 192.168.0.100
- 192.168.0.100
     4-5: SanDisk Corp. : Cruzer Micro 256/512MB Flash Drive (0781:5151)
        : /sys/devices/pci0000:00/0000:00:04.1/usb4/4-5
        : (Defined at Interface level) (00/00/00)
        :  0 - Mass Storage / SCSI / Bulk (Zip) (08/06/50)

client1:~#

To attach that device to the client, run:

# usbip -a 192.168.0.100 4-5
client1:~# usbip -a 192.168.0.100 4-5
8 ports available
port 0 attached

client1:~#

Now run...

# lsusb

... and you should find the remote USB device in the output on the client:

client1:~# lsusb

Bus 001 Device 004: ID 0781:5151 SanDisk Corp. Cruzer Micro 256/512MB Flash Drive
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

client1:~#

You can now use the remote USB device as if it was a local USB device (e.g. mount it, format it, write to it, read form it, etc.).


4 Detaching A Remote USB Device
A remote USB device can be detached as follows:

client1:

Run...

# usbip --port

... to find out the port that the remote USB device uses on the client - in this case it's port 00:

client1:~# usbip --port
8 ports available

Port 00:  at High Speed(480Mbps)
       SanDisk Corp. : Cruzer Micro 256/512MB Flash Drive (0781:5151)
       1-1 -> usbip://192.168.0.100:3240/4-5  (remote devid 00040002 (bus/dev 004/002))
       1-1:1.0 used by usb-storage
           /sys/class/bsg/1:0:0:0/device
           /sys/class/scsi_device/1:0:0:0/device
           /sys/class/scsi_disk/1:0:0:0/device
           /sys/class/scsi_host/host1/device
           /sys/class/usb_endpoint/usbdev1.4_ep02/device
           /sys/class/usb_endpoint/usbdev1.4_ep81/device
           /sys/block/sdb/device
Port 01: 
Port 02: 
Port 03: 
Port 04: 
Port 05: 
Port 06: 
Port 07: 
client1:~#

We need the port number to detach the device:

# usbip -d 00
client1:~# usbip -d 00
8 ports available
port 0 detached
client1:~#

On the server, we use the BUSID (4-5) to bind the USB device to the local system (the --other switch binds the device to the local system so that it is not available over the network anymore):
server1:

# usbip_bind_driver --other 4-5
server1:~# usbip_bind_driver --other 4-5
** (process:7333): DEBUG: write "del 4-5" to /sys/bus/usb/drivers/usbip/match_busid
** Message: bind 4-5 to other drivers than usbip, complete!
server1:~#

Now go back to the client and check if the remote USB device is still available:
client1:

# lsusb

If all goes well, it shouldn't be listed anymore:
client1:~# lsusb

Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
client1:~#


5 Links

2 comments: