]>
Commit | Line | Data |
---|---|---|
e5d60a8b JM |
1 | ## wsproxy: WebSockets to TCP Proxy |
2 | ||
3 | ||
4 | ### How it works | |
5 | ||
6 | At the most basic level, wsproxy just translates WebSockets traffic | |
7 | to normal socket traffic. wsproxy accepts the WebSockets handshake, | |
8 | parses it, and then begins forwarding traffic between the client and | |
9 | the target in both directions. WebSockets payload data is UTF-8 | |
10 | encoded so in order to transport binary data it must use an encoding | |
11 | that can be encapsulated within UTF-8. wsproxy uses base64 to encode | |
12 | all traffic to and from the client. Also, WebSockets traffic starts | |
13 | with '\0' (0) and ends with '\xff' (255). Some buffering is done in | |
14 | case the data from the client is not a full WebSockets frame (i.e. | |
15 | does not end in 255). | |
16 | ||
17 | ||
18 | ### Additional features | |
19 | ||
20 | These are not necessary for the basic operation. | |
21 | ||
22 | * Daemonizing: When the `-f` option is not specified, wsproxy runs | |
23 | in the background as a daemon process. | |
24 | ||
25 | * SSL (the wss:// WebSockets URI): This is detected automatically by | |
26 | wsproxy by sniffing the first byte sent from the client and then | |
27 | wrapping the socket if the data starts with '\x16' or '\x80' | |
28 | (indicating SSL). | |
29 | ||
30 | * Flash security policy: wsproxy detects flash security policy | |
31 | requests (again by sniffing the first packet) and answers with an | |
32 | appropriate flash security policy response (and then closes the | |
33 | port). This means no separate flash security policy server is needed | |
34 | for supporting the flash WebSockets fallback emulator. | |
35 | ||
36 | * Session recording: This feature that allows recording of the traffic | |
37 | sent and received from the client to a file using the `--record` | |
38 | option. | |
39 | ||
40 | ||
41 | ### Implementations | |
42 | ||
fd758dd3 JM |
43 | There are three implementations of wsproxy included: python, C, and |
44 | Node (node.js). | |
e5d60a8b JM |
45 | |
46 | Here is the feature support matrix for the wsproxy implementations: | |
47 | ||
48 | ||
49 | <table> | |
50 | <tr> | |
51 | <th>Implementation</th> | |
52 | <th>Basic Proxying</th> | |
fd758dd3 | 53 | <th>Multi-process</th> |
e5d60a8b JM |
54 | <th>Daemonizing</th> |
55 | <th>SSL/wss</th> | |
56 | <th>Flash Policy Server</th> | |
57 | <th>Session Recording</th> | |
58 | </tr> <tr> | |
59 | <td>python</td> | |
60 | <td>yes</td> | |
61 | <td>yes</td> | |
fd758dd3 | 62 | <td>yes</td> |
e5d60a8b JM |
63 | <td>yes 1</td> |
64 | <td>yes</td> | |
65 | <td>yes</td> | |
66 | </tr> <tr> | |
67 | <td>C</td> | |
68 | <td>yes</td> | |
69 | <td>yes</td> | |
70 | <td>yes</td> | |
71 | <td>yes</td> | |
fd758dd3 JM |
72 | <td>yes</td> |
73 | <td>no</td> | |
74 | </tr> | |
75 | </tr> <tr> | |
76 | <td>Node (node.js)</td> | |
77 | <td>yes</td> | |
78 | <td>yes</td> | |
79 | <td>no</td> | |
80 | <td>no</td> | |
81 | <td>no</td> | |
e5d60a8b JM |
82 | <td>no</td> |
83 | </tr> | |
84 | </table> | |
85 | ||
86 | * Note 1: to use SSL/wss with python 2.5 or older, see the following | |
87 | section on *Building the Python ssl module*. | |
88 | ||
89 | ||
90 | ### Building the Python ssl module (for python 2.5 and older) | |
91 | ||
92 | * Install the build dependencies. On Ubuntu use this command: | |
93 | ||
6502293f | 94 | `sudo aptitude install python-dev bluetooth-dev` |
e5d60a8b JM |
95 | |
96 | * Download, build the ssl module and symlink to it: | |
97 | ||
6502293f | 98 | `cd noVNC/utils` |
3dc3135b | 99 | |
6502293f | 100 | `wget http://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz` |
3dc3135b | 101 | |
6502293f | 102 | `tar xvzf ssl-1.15.tar.gz` |
3dc3135b | 103 | |
6502293f | 104 | `cd ssl-1.15` |
3dc3135b | 105 | |
6502293f | 106 | `make` |
3dc3135b | 107 | |
6502293f | 108 | `cd ../` |
3dc3135b | 109 | |
6502293f | 110 | `ln -sf ssl-1.15/build/lib.linux-*/ssl ssl` |
e5d60a8b | 111 |