Dear all, This series of patches adds exporting device operation to USB/IP. NOTE: This patch set modifies only userspace codes in tools/usb/usbip. Existing operation is still available. New operation will not be enabled unless new daemon is started. 1. Background The motivation of this series is to utilize USB/IP as a platform for IoT. Or a platform to serve ubiquitous devices. Linux is major of server OS and various small linux node is distributed everywhere. USB devices are most easy-to-use for the small nodes. USB/IP is useful to serve USB devices of distributed linux nodes as if they are local devices without any modification to applications. 2. Goal The goal is to add flexibility to USB/IP for the platform for IoT. 1) To improve usability of operations When two Linux machines are in a small distance, it's OK to bind (makes importable) at device side machine and attach (import) at application side. If application is as cloud service or in blade server, it's not practical to attach from application side. It's useful to connect (export) from device side. This patch set adds the new operation to connect devices from device side machine. 2) To give flexibility to direction of connection Using USB/IP in internet, there can be two cases. a) an application is inside firewall and devices are outside. b) devices are inside firewall and an application is inside. In case-a, import works because the connection is from inside. In case-b, import doesn't works because the connection is from outside. Connection from device side is needed. This patch set adds the direction of connection establishment. NOTE: Directions of URB requests and responses are not changed. Only direction of connection establishment initiated with usbip command is added to exsiting one. 3. What's 'exporting' device Exporting devices is not new. The request and response PDU have already been defined in tools/usbip/usbip/src/usbip_network.h. #/* Export a USB device to a remote host. */ #define OP_EXPORT 0x06 #define OP_REQ_EXPORT (OP_REQUEST | OP_EXPORT) #define OP_REP_EXPORT (OP_REPLY | OP_EXPORT) # struct op_export_request # struct op_export_reply #/* un-Export a USB device from a remote host. */ #define OP_UNEXPORT 0x07 #define OP_REQ_UNEXPORT (OP_REQUEST | OP_UNEXPORT) #define OP_REP_UNEXPORT (OP_REPLY | OP_UNEXPORT) # struct op_unexport_request # struct op_unexport_reply But they have not been used yet. This series adds new operations: 'connect' and 'disconnect' using these PDUs. 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. 4. The use cases EXISTING) In existing way, computers in small distance, having same user account, can be easily managed by a same user. Bind in local machine and attach in remote machine by the user. The devices can be exporsed automatically in the local machine, for example, at strat up. They can be attached from remote. When there are distributes linux nodes with USB devices in internet, they are exposed by bind operation at start up, server behind firewall can list and attach the devices. Internet Exposed +----------+ +--------+ +--------+ +------+ |Linux |+ |Router, | |Service | +|device|--|Controller||-------------------|proxy, |----|on | |+------+ +----------+| |firewall| |Linux | +------+ +----------+ +--------+ +--------+ (server) (client) <--- attach(import) USB/IP + WS proxy WS proxy + USB/IP NEW) Assuming that a server computer which runs application and VHCI is in a server room and device side machines are small distributed nodes outside of the server room, the operator of the server compter is different form the distributed nodes. The server computer may be in unattended operation. In the new way, after the daemon has been started, device can be connected with connect command in the distributed nodes. If the distributed nodes doesn't have user interface, the connect command can be executed from start up procedure. In another senario to connect devices to a Linux based cloud service using WebSocket proxy, it's needed to establish connection from a device inside of firewall to a service outside. Exporting is suitable for the senario. Home/SOHO/Intranet Internet +----------+ +--------+ +--------+ +------+ |Linux |+ |Router, | |Internet| +|device|--|Controller||----|proxy, |-------------------|service | |+------+ +----------+| |firewall| |on Linux| +------+ +----------+ +--------+ +--------+ (client) (server) connect(export) --> USB/IP + WS proxy WS proxy + USB/IP ex) Device Service sensors ......................................... environment analysis cameras ......................................... monitoring, recording ID/biometric readers ............................ authentication Firewall, proxy, or router in front of internet usually blocks connections from internet regarding all TCP ports. They opens some ports, usually HTTP(80) and HTTPS(443), for connection from inside. In combination with WebSocket proxy, USB/IP can establish connection from inside of the firewall. EXISTING) Enterprise/SOHO/Home Firewall/Proxy/Router Internet APP# usbip attach -----------(passed)--------> DEV# usbipd DEV# usbipd (blocked)|| <--------- APP# usbip attach NEW) Enterprise/SOHO/Home Firewall/Proxy/Router Internet DEV# usbip connect ----------(passed)--------> DEV# usbipa APP# usbipa (blocked)|| <--------- APP# usbip connect Attach operation can invite devices in internet but cannot invite devices from internet. On the other hand, connect operation can dedicate devices to internet but cannot dedicate devices in internet. 5. Combination with vUDC New operations work with vUDC. --device option specifies vUDC mode as well as list operaion. With stub, connect and disconnect execute bind and unbind internally. With vUDC, they do not execute bind and unbind. They are done by UDC interface. 6. Security consideration When application side daemon is not started, this patch set doesn't affect exsiting security. 1) Connection level security 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. 2) Device level security 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. 7. Relationship between existing and new operation Both existing and new operation are independent each other. Existing operation is enabled when existing usbipd daemon is started. New operation is enabled when new usbipa daemon is started. Both existing and new operation work in same machines simultaneously. Status of devices and ports are controlled in stub and vhci driver. 8. Wording Adding the new operation, some inconsistnecies in wording are appeared in documentation, function name, etc. If needed, they are fixed. 'export' is used for bind and 'exported' is used for bound. They are changed to 'make importable' and 'imported' respectively. The words are not new. For example, in the output of port operation, 'imported devices' is already used. 'client' and 'server' are switched between existing and new operation. Sometimes they implies device-side and application-side. So, words 'device-side' and 'application-side' are used in documentations as needed for clarity. 9. Dependency This set depends to "usbip: auto retry for concurrent attach" patch. --- Version information This series is divided from "USB/IP over WebSocket" patch set. Rest of the set will be sent as another series. v14) # Recreated based on linux-next 20161224. # Added dependency to "usbip: auto retry for concurrent attach" patch. # Added background to cover letter. # Added server/client to each diagrams. # Updated ending part of usecase, firewall diagram and description. # Added device level security consideration to cover letter. # Added security consideration to README. # Added auto retry for false no-free-port in concurrent processing of export request. # Removed returncode from export and un-export reply. # Renamed abstraction of driver functions for daemons from usbip_.*_driver() to usbipd_driver_.*(). # Renamed usbip_update_driver() to usbipd_driver_set(). # Introduced usbipd_driver_ops for these driver functions for daemons. # Refactored recv_pdu functions as one. # Introduced usbipd_recv_pdu_ops. # Refactored libsrc/vhci_driver.c:read_record(). # Modified not to call read_record() for unused port from vhci_find_device. # Modified to use driver->ndevs is used insted of counting list in send_reply_devlist(). # Fixed according to review comments for v13. unnecessary zero clear for reply buffer. unnecessary read for empty struct. sizeof usage from struct name to variable name. implicit size for buffer arguments. # Added email address to copyrights. # Moved copyright position to bottom. v13) # Recreated based on linux-next 20161117. # Updated cover letter: added goal, rewrote overview as explanation of 'exporting' and added that this patch dosn't affect security condition in existing usage. # Moved protocol documentation as the last patch. # Added explanation to each patch. # Removed copyright from usbip_bind.c, usbip_unbind.c, usbip_network.h and usb_list.c in which size of modification is small and functional change is not included. # Fixed help string about position of --parsable option. v12) # Recreated based on linux-next 20161012. # Fixed checkpatch a warning about symbolic permission. # Fixed checkpatch warnings about traling space in a document. v11) # Corrected program name of each daemon which are used in version string, info messages and daemon name for tcp wrappers. # Added description about tcp wrappers in security consideration of cover letter. # Added security consideration for existing requests in contradistinction to new requests. # Recreated based on linux-next 20160928. v10) # Recreated based on linux-next 20160810. v9) # Moved a set_nodelay() from usbipd_dev.c to usbipd.c to affect both device side and application side daemon. # Removed redundant blank line at the end of files. v8) # Divided into smaller patches. # Excluded low-related patches. # Improved change log. # Changed info level logs in usbip_ux.c to debug level logs. # Added options to vUDC. # Tested with vUDC. v7) # Removed userspace transmission and WebSocket command/daemon. # Fixed checkpatch errors and warnings. v6) # Added __rcu annotation to a RCU pointer to clear sparse warnings. # Corrected a copy to RCU pointer with rcu_rcu_assign_pointer(). # Added __user annotations to arguments of read/write method. # Added static to some functions which are not called from other files. # Removed unnecessary EXPORT_SYMBOLs. v5) # Added vendor/pruduct name conversion to port command. # Put initial value to pool_head in name.c. # Fixed list command exception when host option is omitted. # Fixed exception in case gai_strerror() returns NULL. # Fixed WebSocket connection close via proxy. # Fixed to stop WebSocket ping-pong on connection close. # Removed redundant usbipd daemon option. # Removed redundant SSL code had not been deleted. # Removed an unused local variable in WebSocket code. # Modified C++ reserved word in names.c as same as headers. v4) # Fixed regression of usbip list --remote v3) # Coding style for goto err labels are fixed. # Defined magic numbers for open_hc_device() argument. # Corrected include .../uapi/linux/usbip_ux.h as <linux/usbip_ux.h>. # Modified parameter notation in manuals not to use '='. # Fixed inappropriate version definition in tools/.../websocket/configure.ac. # Remved unnecessary COPYING and AUTHORS fil from tools/.../websocket/. # Added -version-info to libraries in tools/.../src. v2) # Formatted patches from linux-next. # Fixed change log word wrapping. # Removed SSL patches. # Fixed a bug that vendor and product names are not shown by 'usbws list -l' because usbip_names_init() was not called in libusbip.la. Thank you, Nobuo Iwata <nobuo.iwata@xxxxxxxxxxxxxxx> // *** BLURB HERE *** Nobuo Iwata (10): usbip: exporting devices: modifications to network header usbip: exporting devices: modifications to host side libraries usbip: exporting devices: new connect operation usbip: exporting devices: new disconnect operation usbip: exporting devices: modifications to daemon usbip: exporting devices: modifications to attach and detach usbip: exporting devices: new application-side daemon usbip: exporting devices: change to usbip_list.c usbip: exporting devices: chage to documenattion usbip: exporting devices: modifications to protocol text Documentation/usb/usbip_protocol.txt | 238 ++++++++++++++++--- 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 +-- tools/usb/usbip/libsrc/usbip_host_common.c | 6 +- tools/usb/usbip/libsrc/usbip_host_common.h | 8 +- tools/usb/usbip/libsrc/vhci_driver.c | 197 ++++++++++++---- tools/usb/usbip/libsrc/vhci_driver.h | 4 + tools/usb/usbip/src/Makefile.am | 12 +- tools/usb/usbip/src/usbip.c | 13 ++ tools/usb/usbip/src/usbip.h | 8 + tools/usb/usbip/src/usbip_attach.c | 99 +++----- tools/usb/usbip/src/usbip_bind.c | 4 +- tools/usb/usbip/src/usbip_connect.c | 212 +++++++++++++++++ tools/usb/usbip/src/usbip_detach.c | 17 +- tools/usb/usbip/src/usbip_disconnect.c | 200 ++++++++++++++++ tools/usb/usbip/src/usbip_list.c | 21 +- tools/usb/usbip/src/usbip_network.c | 26 ++- tools/usb/usbip/src/usbip_network.h | 8 +- tools/usb/usbip/src/usbip_unbind.c | 4 +- tools/usb/usbip/src/usbipd.c | 259 +++++---------------- tools/usb/usbip/src/usbipd.h | 84 +++++++ tools/usb/usbip/src/usbipd_app.c | 200 ++++++++++++++++ tools/usb/usbip/src/usbipd_dev.c | 236 +++++++++++++++++++ 26 files changed, 1743 insertions(+), 448 deletions(-) create mode 100644 tools/usb/usbip/doc/usbipa.8 create mode 100644 tools/usb/usbip/src/usbip_connect.c create mode 100644 tools/usb/usbip/src/usbip_disconnect.c create mode 100644 tools/usb/usbip/src/usbipd.h create mode 100644 tools/usb/usbip/src/usbipd_app.c create mode 100644 tools/usb/usbip/src/usbipd_dev.c -- 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