This patch adds function and usage of new connect operation, disconnect
operation and application(vhci)-side daemon to README and manuals.
At this point, the wording, 'server' and 'client' are ambiguous in
several place.
For existing attach command, the daemon runs device side machine and
attach command is executed in application side machine. Then 'server'
is used for device side and 'client' is for application side.
For the new connect command, the daemon runs applications side machine
and connect command is executed in device side machine. Now, 'server'
and 'client' run in different machine than before.
To avoid confusion, to represent things to be done in device side node
by both command and daemon, words 'device-side' is used instead of
'server'. To represent things to be done is application side node by
both command and daemon, 'applicationr-side' are used instead of
'client'.
EXISTING) - invites devices from application(vhci)-side
+------+ +------------------+
device--+ STUB | | application/VHCI |
+------+ +------------------+
(server) (client)
1) # usbipd ... start daemon
= = =
2) # usbip list --local
3) # usbip bind
<--- list bound devices --- 4) # usbip list --remote
<--- import a device ------ 5) # usbip attach
= = =
X disconnected 6) # usbip detach
7) usbip unbind
NEW) - dedicates devices from device(stub)-side
+------+ +------------------+
device--+ STUB | | application/VHCI |
+------+ +------------------+
(client) (server)
1) # usbipa ... start daemon
= = =
2) # usbip list --local
3) # usbip connect --- export a device ------>
= = =
4) # usbip disconnect --- un-export a device --->
Bind and unbind are done in connect and disconnect internally.
Signed-off-by: Nobuo Iwata <nobuo.iwata@xxxxxxxxxxxxxxx>
---
tools/usb/usbip/Makefile.am | 2 +-
tools/usb/usbip/README | 81 ++++++++++++++++-----
tools/usb/usbip/doc/usbip.8 | 136 ++++++++++++++++++++++++++++-------
tools/usb/usbip/doc/usbipa.8 | 78 ++++++++++++++++++++
tools/usb/usbip/doc/usbipd.8 | 38 +++++-----
5 files changed, 275 insertions(+), 60 deletions(-)
diff --git a/tools/usb/usbip/Makefile.am b/tools/usb/usbip/Makefile.am
index 66f8bf0..f371ed9 100644
--- a/tools/usb/usbip/Makefile.am
+++ b/tools/usb/usbip/Makefile.am
@@ -3,4 +3,4 @@ includedir = @includedir@/usbip
include_HEADERS := $(addprefix libsrc/, \
usbip_common.h vhci_driver.h usbip_host_driver.h)
-dist_man_MANS := $(addprefix doc/, usbip.8 usbipd.8)
+dist_man_MANS := $(addprefix doc/, usbip.8 usbipd.8 usbipa.8)
diff --git a/tools/usb/usbip/README b/tools/usb/usbip/README
index 831f49f..d3cae75 100644
--- a/tools/usb/usbip/README
+++ b/tools/usb/usbip/README
@@ -3,6 +3,7 @@
#
# Copyright (C) 2011 matt mooney <mfm@xxxxxxxxxxxxx>
# 2005-2008 Takahiro Hirofuchi
+# Copyright (C) 2015-2016 Nobuo Iwata <nobuo.iwata@xxxxxxxxxxxxxxx>
[Requirements]
@@ -36,41 +37,70 @@
[Usage]
- server:# (Physically attach your USB device.)
+Device-side: a machine has USB device(s).
+Application-side: a machine runs an application software uses remote USB device.
- server:# insmod usbip-core.ko
- server:# insmod usbip-host.ko
+1) Connect from application-side to device-side.
- server:# usbipd -D
+ dev:# (Physically attach your USB device.)
+
+ dev:# insmod usbip-core.ko
+ dev:# insmod usbip-host.ko
+
+ dev:# usbipd -D
- Start usbip daemon.
- server:# usbip list -l
- - List driver assignments for USB devices.
+ dev:# usbip list -l
+ - List driver assignments for USB devices and their busid.
- server:# usbip bind --busid 1-2
- - Bind usbip-host.ko to the device with busid 1-2.
- - The USB device 1-2 is now exportable to other hosts!
- - Use `usbip unbind --busid 1-2' to stop exporting the device.
+ dev:# usbip bind --busid <busid>
+ - Bind usbip-host.ko to the device with <busid>.
+ - The USB device with <busid> is now exportable to other hosts!
+ - Use `usbip unbind --busid <busid>` to stop exporting the device.
- client:# insmod usbip-core.ko
- client:# insmod vhci-hcd.ko
+ app:# insmod usbip-core.ko
+ app:# insmod vhci-hcd.ko
- client:# usbip list --remote <host>
+ app:# usbip list --remote <host>
- List exported USB devices on the <host>.
- client:# usbip attach --remote <host> --busid 1-2
+ app:# usbip attach --remote <host> --busid <busid>
- Connect the remote USB device.
- client:# usbip port
+ app:# usbip port
- Show virtual port status.
- client:# usbip detach --port <port>
+ app:# usbip detach --port <port>
- Detach the USB device.
+2) Connect from device-side to application-side.
+
+ app:# insmod usbip-core.ko
+ app:# insmod vhci-hcd.ko
+
+ app:# usbipa -D
+ - Start usbip daemon.
+
+ dev:# (Physically attach your USB device.)
+
+ dev:# insmod usbip-core.ko
+ dev:# insmod usbip-host.ko
+
+ dev:# usbip list -l
+ - List driver assignments for USB devices and their busid.
+
+ dev:# usbip connect --remote <host> --busid <busid>
+ - Bind usbip-host.ko to the device with <busid>.
+ - The USB device of <busid> is connected to remote host!
+
+ dev:# usbip disconnect --remote <host> --busid <busid>
+ - The USB device with <busid> is disconnected from remote host.
+ - Unbind usbip-host.ko from the device.
+
[Example]
---------------------------
- SERVER SIDE
+ DEVICE SIDE
---------------------------
Physically attach your USB devices to this host.
@@ -131,7 +161,7 @@ Mark the device of busid 3-3.2 as exportable:
...
---------------------------
- CLIENT SIDE
+ APPLICATION SIDE
---------------------------
First, let's list available remote devices that are marked as
exportable on the host.
@@ -170,7 +200,7 @@ Attach a remote USB device:
deux:# usbip attach --remote 10.0.0.3 --busid 1-1
port 0 attached
-Show the devices attached to this client:
+Show the devices attached to this machine:
deux:# usbip port
Port 00: <Port in Use> at Full Speed(12Mbps)
@@ -187,6 +217,19 @@ Detach the imported device:
port 0 detached
+[Security consideration]
+
+Daemons accept following requests form network :
+ EXISTING) 'list --remote' and 'attach'
+ NEW) 'connect' and 'disconnect'
+
+TCP wrappers allows and/or denies network access. It is enabled when the daemons are compiled with ./configure --with-tcp-wrappers.
+
+When the daemons are running with SSL or Secure WebSocket tunneling proxy, the proxy can use client authentication with certificate files.
+
+Udev rules can allow only known devices. To identify whether a device is remote, the local bus-id (KERNEL parameter in the rule) will be found in the last column of /sys/devices/platform/vhci_hcd/status[.N]. When device is found, the port number of USB/IP can be found in the first column of the matched line. The udev script can finish the connection using detach operation with the port number.
+
+
[Checklist]
- See 'Debug Tips' on the project wiki.
- http://usbip.wiki.sourceforge.net/how-to-debug-usbip
diff --git a/tools/usb/usbip/doc/usbip.8 b/tools/usb/usbip/doc/usbip.8
index a6097be..523bb53 100644
--- a/tools/usb/usbip/doc/usbip.8
+++ b/tools/usb/usbip/doc/usbip.8
@@ -6,27 +6,30 @@ usbip \- manage USB/IP devices
[\fIoptions\fR] <\fIcommand\fR> <\fIargs\fR>
.SH DESCRIPTION
-On a USB/IP server, devices can be listed, bound, and unbound using
-this program. On a USB/IP client, devices exported by USB/IP servers
-can be listed, attached and detached.
+On a USB/IP device side computer,
+lists local devices, makes a device importable, makes not importable,
+connects a device and disconnects a device.
+
+On a USB/IP application side computer,
+lists devices importable from a remote computer, attaches a remote device and detaches an attached device.
.SH OPTIONS
.HP
-\fB\-\-debug\fR
+\fB\-d\fR, \fB\-\-debug\fR
.IP
Print debugging information.
.PP
.HP
-\fB\-\-log\fR
+\fB\-l\fR, \fB\-\-log\fR
.IP
Log to syslog.
.PP
.HP
-\fB\-\-tcp-port PORT\fR
+\fB\-tPORT\fR, \fB\-\-tcp-port PORT\fR
.IP
-Connect to PORT on remote host (used for attach and list --remote).
+TCP port number used by remote usbip daemon. Default is 3240.
.PP
.SH COMMANDS
@@ -44,52 +47,137 @@ then exit.
.PP
.HP
-\fBattach\fR \-\-remote=<\fIhost\fR> \-\-busid=<\fIbus_id\fR>
+\fBattach\fR \-\-remote <\fIhost\fR> \-\-busid <\fIbusid\fR>
.IP
-Attach a remote USB device.
+Attach a importable USB device from remote computer.
.PP
.HP
-\fBdetach\fR \-\-port=<\fIport\fR>
+\fBdetach\fR \-\-port <\fIport\fR>
.IP
Detach an imported USB device.
.PP
.HP
-\fBbind\fR \-\-busid=<\fIbusid\fR>
+\fBconnect\fR \-\-remote <\fIhost\fR> \-\-busid <\fIbusid\fR> [\-\-device]
+.IP
+Connect a USB device to remote computer.
+.PP
+
+.HP
+\fBdisconnect\fR \-\-remote <\fIhost\fR> \-\-busid <\fIbusid\fR> [\-\-device]
.IP
-Make a device exportable.
+Disconnect a USB device from remote computer. It allows to disconnet from a computer which issued connect operation.
.PP
.HP
-\fBunbind\fR \-\-busid=<\fIbusid\fR>
+\fBbind\fR \-\-busid <\fIbusid\fR>
.IP
-Stop exporting a device so it can be used by a local driver.
+Make a USB device importable from remote computer.
.PP
.HP
-\fBlist\fR \-\-remote=<\fIhost\fR>
+\fBunbind\fR \-\-busid <\fIbusid\fR>
.IP
-List USB devices exported by a remote host.
+Make a USB device not importable so it can be used by a local driver.
.PP
.HP
-\fBlist\fR \-\-local
+\fBlist\fR \-\-remote <\fIhost\fR>
+.IP
+List importable USB devices from a remote computer.
+.PP
+
+.HP
+\fBlist\fR [\-\-parsable] \-\-local
.IP
List local USB devices.
.PP
+.HP
+\fBlist\fR [\-\-parsable] \-\-device
+.IP
+List local USB devices with an alternate driver, e.g. vUDC.
+.PP
+
+.HP
+\fBport\fR
+.HP
+.IP
+List imported USB devices.
+.PP
-.SH EXAMPLES
- client:# usbip list --remote=server
- - List exportable usb devices on the server.
+.SH ARGUMENTS
+.HP
+\fB\-rHOST\fR, \fB\-\-remote HOST\fR
+.IP
+Remote host address.
+.PP
+
+.HP
+\fB\-bBUSID\fR, \fB\-\-busid BUSID\fR
+.IP
+Bus ID of a device to be handled.
+.PP
+
+.HP
+\fB\-pPORT\fR, \fB\-\-port PORT\fR
+.IP
+d.
+Port number of an imported device shown by port command.
+.PP
+
+.HP
+\fB\-l\fR, \fB\-\-local\fR
+.IP
+Target local devices.
+.PP
+
+.HP
+\fB\-p\fR, \fB\-\-parsable\fR
+.IP
+Parsable format.
+.PP
+
+.HP
+\fB\-d\fR, \fB\-\-device\fR
+.IP
+Run with with an alternate driver, e.g. vUDC.
+.PP
+
+
+.SH EXAMPLES
- client:# usbip attach --remote=server --busid=1-2
- - Connect the remote USB device.
+dev: at a device side computer
+.br
+app: at an application side computer
+
+Attach a device from a remote computer
+ dev:# usbip list
+ - List local USB devices.
+ dev:# usbip bind --busid 1-2
+ - Make a USB device importable from a remote computer.
+ app:# usbip list --remote 172.1.2.3
+ - List importable USB devices on the computer.
+ app:# usbip attach --remote 172.1.2.3 --busid 1-2
+ - Import a remote USB device.
+ app:# usbip port
+ - List imported USB devices.
+ app:# usbip detach --port 0
+ - Detach the USB device.
+ dev:# usbip unbind --busid 1-2
+ - Make a USB device not importable, then release to local.
+
+Connect a device to a remote computer
+ dev:# usbip list
+ - List local USB devices.
+ dev:# usbip connect --remote 172.4.5.6 --busid 1-2
+ - Export a USB device to a remote computer.
+ dev:# usbip disconnect --remote 172.4.5.6 --busid 1-2
+ - Unxport a USB device from a remote computer.
- client:# usbip detach --port=0
- - Detach the usb device.
.SH "SEE ALSO"
\fBusbipd\fP\fB(8)\fB\fP
+\fBusbipa\fP\fB(8)\fB\fP
diff --git a/tools/usb/usbip/doc/usbipa.8 b/tools/usb/usbip/doc/usbipa.8
new file mode 100644
index 0000000..0dd7a52
--- /dev/null
+++ b/tools/usb/usbip/doc/usbipa.8
@@ -0,0 +1,78 @@
+.TH USBIP "8" "March 2015" "usbip" "System Administration Utilities"
+.SH NAME
+usbipa \- USB/IP application side daemon
+.SH SYNOPSIS
+.B usbipa
+[\fIoptions\fR]
+
+.SH DESCRIPTION
+.B usbipa
+runs on an application side computer and make remote USB devices connected using \fBusbip connect\fR at remote computers accessible on the application side computer.
+
+.SH OPTIONS
+.HP
+\fB\-4\fR, \fB\-\-ipv4\fR
+.IP
+Bind to IPv4. Default is both.
+.PP
+
+.HP
+\fB\-6\fR, \fB\-\-ipv6\fR
+.IP
+Bind to IPv6. Default is both.
+.PP
+
+.HP
+\fB\-D\fR, \fB\-\-daemon\fR
+.IP
+Run as a daemon process.
+.PP
+
+.HP
+\fB\-d\fR, \fB\-\-debug\fR
+.IP
+Print debugging information.
+.PP
+
+.HP
+\fB\-PFILE\fR, \fB\-\-pid FILE\fR
+.IP
+Write process id to FILE.
+.br
+If no FILE specified, use /var/run/usbipd.pid
+.PP
+
+.HP
+\fB\-tPORT\fR, \fB\-\-tcp\-port PORT\fR
+.IP
+Listen on TCP/IP port PORT. Default is 3240.
+.PP
+
+.HP
+\fB\-h\fR, \fB\-\-help\fR
+.IP
+Print the program help message and exit.
+.PP
+
+.HP
+\fB\-v\fR, \fB\-\-version\fR
+.IP
+Show version.
+.PP
+
+.SH LIMITATIONS
+
+.B usbipa
+offers no authentication or authorization for USB/IP. Any
+USB/IP client can connect and use exported devices.
+
+.SH EXAMPLES
+
+ app:# modprobe vhci-hcd
+
+ app:# usbipa -D
+ - Start usbip daemon.
+
+.SH "SEE ALSO"
+\fBusbip\fP\fB(8)\fB\fP
+\fBusbipd\fP\fB(8)\fB\fP
diff --git a/tools/usb/usbip/doc/usbipd.8 b/tools/usb/usbip/doc/usbipd.8
index ac4635d..0c27182 100644
--- a/tools/usb/usbip/doc/usbipd.8
+++ b/tools/usb/usbip/doc/usbipd.8
@@ -1,20 +1,15 @@
.TH USBIP "8" "February 2009" "usbip" "System Administration Utilities"
.SH NAME
-usbipd \- USB/IP server daemon
+usbipd \- USB/IP device side daemon
.SH SYNOPSIS
.B usbipd
[\fIoptions\fR]
.SH DESCRIPTION
.B usbipd
-provides USB/IP clients access to exported USB devices.
+runs on a divice side computer and provides USB/IP access from remote computers.
-Devices have to explicitly be exported using
-.B usbip bind
-before usbipd makes them available to other hosts.
-
-The daemon accepts connections from USB/IP clients
-on TCP port 3240 by default.
+To make devices accessible from remote computers, they must be made importable using \fBusbip bind\fR.
.SH OPTIONS
.HP
@@ -49,11 +44,19 @@ Write process id to FILE.
If no FILE specified, use /var/run/usbipd.pid
.PP
+.HP
\fB\-tPORT\fR, \fB\-\-tcp\-port PORT\fR
.IP
-Listen on TCP/IP port PORT.
+Listen on TCP/IP port PORT. Default is 3240.
.PP
+.HP
+\fB\-e\fR, \fB\-\-device\fR
+.IP
+Run with with an alternate driver, e.g. vUDC.
+.PP
+
+.HP
\fB\-h\fR, \fB\-\-help\fR
.IP
Print the program help message and exit.
@@ -73,19 +76,22 @@ USB/IP client can connect and use exported devices.
.SH EXAMPLES
- server:# modprobe usbip
+ dev:# modprobe usbip-host
- server:# usbipd -D
+ dev:# usbipd -D
- Start usbip daemon.
- server:# usbip list --local
+ dev:# usbip list --local
- List driver assignments for usb devices.
- server:# usbip bind --busid=1-2
+ dev:# usbip bind --busid 1-2
- Bind usbip-host.ko to the device of busid 1-2.
- - A usb device 1-2 is now exportable to other hosts!
- - Use 'usbip unbind --busid=1-2' when you want to shutdown exporting and use the device locally.
+ - USB device 1-2 is now importable from other computer!
+
+ dev:# usbip unbind --busid 1-2
+ - Unind usbip-host.ko from the device of busid 1-2.
+ - USB device 1-2 is not importable from other computer.
.SH "SEE ALSO"
\fBusbip\fP\fB(8)\fB\fP
-
+\fBusbipa\fP\fB(8)\fB\fP
--
2.1.0
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
