2011-01-13 00:09:54 +00:00
|
|
|
## websockify: WebSockets support for any application/server
|
|
|
|
|
2011-01-13 06:17:01 +00:00
|
|
|
websockify was formerly named wsproxy and was part of the
|
2011-01-13 00:09:54 +00:00
|
|
|
[noVNC](https://github.com/kanaka/noVNC) project.
|
|
|
|
|
|
|
|
At the most basic level, websockify just translates WebSockets traffic
|
2011-10-06 16:56:36 +01:00
|
|
|
to normal socket traffic. Websockify accepts the WebSockets handshake,
|
2011-01-13 00:09:54 +00:00
|
|
|
parses it, and then begins forwarding traffic between the client and
|
2011-10-06 16:56:36 +01:00
|
|
|
the target in both directions.
|
2011-01-13 00:09:54 +00:00
|
|
|
|
2011-10-06 16:56:36 +01:00
|
|
|
### WebSockets binary data
|
|
|
|
|
|
|
|
Websockify supports all versions of the WebSockets protocol (Hixie and
|
|
|
|
HyBI). The older Hixie versions of the protocol only support UTF-8
|
|
|
|
text payloads. In order to transport binary data over UTF-8 an
|
|
|
|
encoding must used to encapsulate the data within UTF-8. Websockify
|
|
|
|
uses base64 to encode all traffic to and from the client. This does
|
|
|
|
not affect the data between websockify and the server.
|
2011-01-13 00:09:54 +00:00
|
|
|
|
2011-01-13 06:17:01 +00:00
|
|
|
### Websock Javascript library
|
|
|
|
|
2011-10-06 22:55:10 +01:00
|
|
|
|
2011-01-13 06:17:01 +00:00
|
|
|
The `include/websock.js` Javascript library library provides a Websock
|
|
|
|
object that is similar to the standard WebSocket object but Websock
|
|
|
|
enables communication with raw TCP sockets (i.e. the binary stream)
|
|
|
|
via websockify. This is accomplished by base64 encoding the data
|
|
|
|
stream between Websock and websockify.
|
|
|
|
|
|
|
|
Websock has built-in receive queue buffering; the message event
|
|
|
|
does not contain actual data but is simply a notification that
|
|
|
|
there is new data available. Several rQ* methods are available to
|
|
|
|
read binary data off of the receive queue.
|
|
|
|
|
2011-10-06 22:55:10 +01:00
|
|
|
The Websock API is documented on the [websock.js API wiki page](https://github.com/kanaka/websockify/wiki/websock.js)
|
|
|
|
|
2011-01-13 06:53:08 +00:00
|
|
|
See the "Wrap a Program" section below for an example of using Websock
|
|
|
|
and websockify as a browser telnet client (`wstelnet.html`).
|
|
|
|
|
2011-01-13 06:17:01 +00:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
### Additional websockify features
|
|
|
|
|
|
|
|
These are not necessary for the basic operation.
|
|
|
|
|
|
|
|
* Daemonizing: When the `-D` option is specified, websockify runs
|
|
|
|
in the background as a daemon process.
|
|
|
|
|
|
|
|
* SSL (the wss:// WebSockets URI): This is detected automatically by
|
|
|
|
websockify by sniffing the first byte sent from the client and then
|
|
|
|
wrapping the socket if the data starts with '\x16' or '\x80'
|
|
|
|
(indicating SSL).
|
|
|
|
|
|
|
|
* Flash security policy: websockify detects flash security policy
|
|
|
|
requests (again by sniffing the first packet) and answers with an
|
|
|
|
appropriate flash security policy response (and then closes the
|
|
|
|
port). This means no separate flash security policy server is needed
|
|
|
|
for supporting the flash WebSockets fallback emulator.
|
|
|
|
|
|
|
|
* Session recording: This feature that allows recording of the traffic
|
|
|
|
sent and received from the client to a file using the `--record`
|
|
|
|
option.
|
|
|
|
|
|
|
|
* Mini-webserver: websockify can detect and respond to normal web
|
|
|
|
requests on the same port as the WebSockets proxy and Flash security
|
|
|
|
policy. This functionality is activate with the `--web DIR` option
|
|
|
|
where DIR is the root of the web directory to serve.
|
|
|
|
|
|
|
|
* Wrap a program: see the "Wrap a Program" section below.
|
|
|
|
|
|
|
|
|
|
|
|
### Implementations of websockify
|
|
|
|
|
2011-07-14 18:30:07 +01:00
|
|
|
The primary implementation of websockify is in python. There are also
|
|
|
|
alternative implementations in the `other/` subdirectory.
|
2011-01-13 00:09:54 +00:00
|
|
|
|
|
|
|
Here is the feature support matrix for the the websockify
|
|
|
|
implementations:
|
|
|
|
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>Program</th>
|
2011-06-29 16:53:13 +01:00
|
|
|
<th>websockify</th>
|
|
|
|
<th>other/websockify</th>
|
|
|
|
<th>other/websockify.js</th>
|
2011-10-04 07:20:14 +01:00
|
|
|
<th>other/websockify.rb</th>
|
2011-07-14 18:27:04 +01:00
|
|
|
<th>other/kumina</th>
|
2011-09-29 22:17:16 +01:00
|
|
|
<th>VNCAuthProxy 1</th>
|
2011-01-13 00:09:54 +00:00
|
|
|
</tr> <tr>
|
2011-06-29 16:53:13 +01:00
|
|
|
<th>Language</th>
|
2011-01-13 00:09:54 +00:00
|
|
|
<td>python</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
<td>C</td>
|
|
|
|
<td>Node (node.js)</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>Ruby</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>C</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>python (twisted)</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
</tr> <tr>
|
|
|
|
<th>Multiproc</th>
|
2011-01-13 00:09:54 +00:00
|
|
|
<td>yes</td>
|
|
|
|
<td>yes</td>
|
2011-05-02 04:26:59 +01:00
|
|
|
<td>yes</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
2011-10-25 23:02:04 +01:00
|
|
|
<td>via inetd</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>yes</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
</tr> <tr>
|
|
|
|
<th>Daemon</th>
|
2011-05-02 04:26:59 +01:00
|
|
|
<td>yes</td>
|
|
|
|
<td>yes</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
2011-10-25 23:02:04 +01:00
|
|
|
<td>via inetd</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>yes</td>
|
2011-01-13 00:09:54 +00:00
|
|
|
</tr> <tr>
|
2011-06-29 16:53:13 +01:00
|
|
|
<th>SSL wss</th>
|
2011-09-29 22:17:16 +01:00
|
|
|
<td>yes 2</td>
|
2011-01-13 00:09:54 +00:00
|
|
|
<td>yes</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>no</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>yes</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
</tr> <tr>
|
|
|
|
<th>Flash Policy Server</th>
|
2011-01-13 00:09:54 +00:00
|
|
|
<td>yes</td>
|
|
|
|
<td>yes</td>
|
|
|
|
<td>no</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>yes</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>no</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
</tr> <tr>
|
|
|
|
<th>Session Record</th>
|
2011-07-14 18:32:06 +01:00
|
|
|
<td>yes</td>
|
2011-01-13 00:09:54 +00:00
|
|
|
<td>no</td>
|
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>no</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>no</td>
|
2011-01-13 00:09:54 +00:00
|
|
|
</tr> <tr>
|
2011-06-29 16:53:13 +01:00
|
|
|
<th>Web Server</th>
|
2011-01-13 00:09:54 +00:00
|
|
|
<td>yes</td>
|
|
|
|
<td>no</td>
|
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>no</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>no</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
</tr> <tr>
|
|
|
|
<th>Program Wrap</th>
|
|
|
|
<td>yes</td>
|
2011-01-13 00:09:54 +00:00
|
|
|
<td>no</td>
|
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>no</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
</tr> <tr>
|
2011-07-14 18:30:07 +01:00
|
|
|
<th>Multiple Targets</th>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
|
|
|
<td>no</td>
|
|
|
|
<td>no</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>yes</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
</tr> <tr>
|
2011-08-04 17:12:57 +01:00
|
|
|
<th>Hixie 75</th>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>yes</td>
|
|
|
|
<td>yes</td>
|
|
|
|
<td>yes</td>
|
|
|
|
<td>no</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>no</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>no</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
</tr> <tr>
|
2011-08-04 17:12:57 +01:00
|
|
|
<th>Hixie 76</th>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>yes</td>
|
2011-05-02 04:26:59 +01:00
|
|
|
<td>yes</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
<td>yes</td>
|
|
|
|
<td>yes</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>yes</td>
|
2011-10-04 07:20:14 +01:00
|
|
|
<td>yes</td>
|
2011-06-29 16:53:13 +01:00
|
|
|
</tr> <tr>
|
2011-10-06 16:56:36 +01:00
|
|
|
<th>IETF/HyBi (07+)</th>
|
2011-06-29 16:53:13 +01:00
|
|
|
<td>yes</td>
|
|
|
|
<td>no</td>
|
2011-05-02 04:26:59 +01:00
|
|
|
<td>no</td>
|
2011-07-14 18:27:04 +01:00
|
|
|
<td>no</td>
|
2011-10-25 23:02:04 +01:00
|
|
|
<td>yes</td>
|
2011-09-29 22:15:15 +01:00
|
|
|
<td>yes</td>
|
2011-01-13 00:09:54 +00:00
|
|
|
</tr>
|
|
|
|
</table>
|
2010-04-07 03:34:56 +01:00
|
|
|
|
|
|
|
|
2011-09-29 22:17:16 +01:00
|
|
|
* Note 1:
|
|
|
|
[http://code.osuosl.org/projects/twisted-vncauthproxy](VNCAuthProxy)
|
|
|
|
is part of Ganeti Web Manger and is not included with websockify.
|
|
|
|
|
|
|
|
* Note 2: to use SSL/wss with python 2.5 or older, see the following
|
2011-01-13 00:09:54 +00:00
|
|
|
section on *Building the Python ssl module*.
|
2010-04-07 03:34:56 +01:00
|
|
|
|
2011-09-29 22:17:16 +01:00
|
|
|
|
2011-08-04 17:12:57 +01:00
|
|
|
Protocol draft/specification links:
|
|
|
|
|
2011-08-04 17:13:28 +01:00
|
|
|
* [Hixie 75](http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75)
|
|
|
|
* [Hixie 76](http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76)
|
|
|
|
* [IETF/HyBi 07](http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-07)
|
|
|
|
* [IETF/HyBi 10](http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10)
|
2011-10-06 16:56:36 +01:00
|
|
|
* [IETF/HyBi 17](http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-17)
|
2010-04-07 03:34:56 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
### Wrap a Program
|
2010-07-09 17:41:36 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
In addition to proxying from a source address to a target address
|
|
|
|
(which may be on a different system), websockify has the ability to
|
|
|
|
launch a program on the local system and proxy WebSockets traffic to
|
|
|
|
a normal TCP port owned/bound by the program.
|
2010-07-23 18:30:31 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
The is accomplished with a small LD_PRELOAD library (`rebind.so`)
|
|
|
|
which intercepts bind() system calls by the program. The specified
|
|
|
|
port is moved to a new localhost/loopback free high port. websockify
|
|
|
|
then proxies WebSockets traffic directed to the original port to the
|
|
|
|
new (moved) port of the program.
|
2010-07-23 18:30:31 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
The program wrap mode is invoked by replacing the target with `--`
|
|
|
|
followed by the program command line to wrap.
|
2010-07-09 17:41:36 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`./websockify 2023 -- PROGRAM ARGS`
|
2010-07-09 16:52:42 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
The `--wrap-mode` option can be used to indicate what action to take
|
|
|
|
when the wrapped program exits or daemonizes.
|
2010-04-07 03:34:56 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
Here is an example of using websockify to wrap the vncserver command
|
|
|
|
(which backgrounds itself) for use with
|
|
|
|
[noVNC](https://github.com/kanaka/noVNC):
|
2010-07-09 17:41:36 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`./websockify 5901 --wrap-mode=ignore -- vncserver -geometry 1024x768 :1`
|
2010-07-09 17:41:36 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
Here is an example of wrapping telnetd (from krb5-telnetd).telnetd
|
|
|
|
exits after the connection closes so the wrap mode is set to respawn
|
|
|
|
the command:
|
2011-01-04 18:19:54 +00:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`sudo ./websockify 2023 --wrap-mode=respawn -- telnetd -debug 2023`
|
2011-01-04 18:19:54 +00:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
The `wstelnet.html` page demonstrates a simple WebSockets based telnet
|
|
|
|
client.
|
2011-01-04 18:19:54 +00:00
|
|
|
|
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
### Building the Python ssl module (for python 2.5 and older)
|
2011-01-04 18:19:54 +00:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
* Install the build dependencies. On Ubuntu use this command:
|
2011-01-04 18:19:54 +00:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`sudo aptitude install python-dev bluetooth-dev`
|
2010-09-24 16:29:42 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
* Download, build the ssl module and symlink to it:
|
2010-09-24 16:29:42 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`cd websockify/`
|
2010-09-24 16:29:42 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`wget http://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz`
|
2010-09-24 16:29:42 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`tar xvzf ssl-1.15.tar.gz`
|
2010-09-24 16:45:33 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`cd ssl-1.15`
|
2010-09-24 16:45:33 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`make`
|
2010-04-07 03:34:56 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`cd ../`
|
2010-04-07 03:34:56 +01:00
|
|
|
|
2011-01-13 00:09:54 +00:00
|
|
|
`ln -sf ssl-1.15/build/lib.linux-*/ssl ssl`
|
2010-04-07 03:34:56 +01:00
|
|
|
|