]>
Commit | Line | Data |
---|---|---|
f2538f33 | 1 | ## WebSockets Proxy |
71ba9a7a JM |
2 | |
3 | ||
4 | ### wsproxy | |
e5d60a8b JM |
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 | ||
71ba9a7a | 18 | #### Additional wsproxy features |
e5d60a8b JM |
19 | |
20 | These are not necessary for the basic operation. | |
21 | ||
f2538f33 | 22 | * Daemonizing: When the `-D` option is specified, wsproxy runs |
e5d60a8b JM |
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 | ||
f2538f33 JM |
40 | * Mini-webserver: wsproxy can detect and respond to normal web |
41 | requests on the same port as the WebSockets proxy and Flash security | |
42 | policy. This functionality is activate with the `--web DIR` option | |
43 | where DIR is the root of the web directory to serve. | |
44 | ||
45 | * Wrap a program: see the "Wrap a Program" section below. | |
46 | ||
e5d60a8b | 47 | |
71ba9a7a | 48 | #### Implementations of wsproxy |
e5d60a8b | 49 | |
2574936f JM |
50 | There are three implementations of wsproxy: python, C, and Node |
51 | (node.js). wswrapper is only implemented in C. | |
e5d60a8b | 52 | |
f2538f33 JM |
53 | Here is the feature support matrix for the the wsproxy |
54 | implementations: | |
e5d60a8b | 55 | |
e5d60a8b JM |
56 | <table> |
57 | <tr> | |
6ace64d3 | 58 | <th>Program</th> |
2574936f | 59 | <th>Language</th> |
6ace64d3 JM |
60 | <th>Multiprocess</th> |
61 | <th>Daemonize</th> | |
62 | <th>SSL/wss</th> | |
63 | <th>Flash Policy Server</th> | |
64 | <th>Session Record</th> | |
65 | <th>Web Server</th> | |
f2538f33 | 66 | <th>Program Wrap</th> |
6ace64d3 JM |
67 | </tr> <tr> |
68 | <td>wsproxy.py</td> | |
e5d60a8b | 69 | <td>python</td> |
e5d60a8b | 70 | <td>yes</td> |
fd758dd3 | 71 | <td>yes</td> |
6ace64d3 | 72 | <td>yes 1</td> |
e5d60a8b JM |
73 | <td>yes</td> |
74 | <td>yes</td> | |
e5d60a8b | 75 | <td>yes</td> |
f2538f33 | 76 | <td>yes</td> |
6ace64d3 JM |
77 | </tr> <tr> |
78 | <td>wsproxy</td> | |
79 | <td>C</td> | |
6ace64d3 | 80 | <td>yes</td> |
e5d60a8b JM |
81 | <td>yes</td> |
82 | <td>yes</td> | |
fd758dd3 JM |
83 | <td>yes</td> |
84 | <td>no</td> | |
90966d62 | 85 | <td>no</td> |
f2538f33 | 86 | <td>no</td> |
fd758dd3 | 87 | </tr> |
6ace64d3 JM |
88 | </tr> <tr> |
89 | <td>wsproxy.js</td> | |
90 | <td>Node (node.js)</td> | |
fd758dd3 | 91 | <td>yes</td> |
fd758dd3 JM |
92 | <td>no</td> |
93 | <td>no</td> | |
94 | <td>no</td> | |
6ace64d3 JM |
95 | <td>no</td> |
96 | <td>no</td> | |
2574936f JM |
97 | <td>no</td> |
98 | </tr> | |
e5d60a8b JM |
99 | </table> |
100 | ||
6ace64d3 | 101 | |
e5d60a8b JM |
102 | * Note 1: to use SSL/wss with python 2.5 or older, see the following |
103 | section on *Building the Python ssl module*. | |
104 | ||
105 | ||
f2538f33 JM |
106 | ### Wrap a Program |
107 | ||
108 | In addition to proxying from a source address to a target address | |
109 | (which may be on a different system), wsproxy has the ability to | |
110 | launch a program on the local system and proxy WebSockets traffic to | |
111 | a normal TCP port owned/bound by the program. | |
112 | ||
113 | The is accomplished with a small LD_PRELOAD library (`rebind.so`) | |
114 | which intercepts bind() system calls by the program. The specified | |
115 | port is moved to a new localhost/loopback free high port. wsproxy | |
116 | then proxies WebSockets traffic directed to the original port to the | |
117 | new (moved) port of the program. | |
118 | ||
119 | The program wrap mode is invoked by replacing the target with `--` | |
120 | followed by the program command line to wrap. | |
121 | ||
122 | `./utils/wsproxy.py 2023 -- PROGRAM ARGS` | |
123 | ||
124 | The `--wrap-mode` option can be used to indicate what action to take | |
125 | when the wrapped program exits or daemonizes. | |
126 | ||
127 | Here is an example of using wsproxy to wrap the vncserver command | |
128 | (which backgrounds itself): | |
129 | ||
130 | `./utils/wsproxy.py 5901 --wrap-mode=ignore -- vncserver -geometry 1024x768 :1` | |
131 | ||
132 | Here is an example of wrapping telnetd (from krb5-telnetd).telnetd | |
133 | exits after the connection closes so the wrap mode is set to respawn | |
134 | the command: | |
135 | ||
136 | `sudo ./utils/wsproxy.py 2023 --wrap-mode=respawn -- telnetd -debug 2023` | |
137 | ||
138 | The `utils/wstelnet.html` page demonstrates a simple WebSockets based | |
139 | telnet client. | |
140 | ||
141 | ||
e5d60a8b JM |
142 | ### Building the Python ssl module (for python 2.5 and older) |
143 | ||
144 | * Install the build dependencies. On Ubuntu use this command: | |
145 | ||
6502293f | 146 | `sudo aptitude install python-dev bluetooth-dev` |
e5d60a8b JM |
147 | |
148 | * Download, build the ssl module and symlink to it: | |
149 | ||
6502293f | 150 | `cd noVNC/utils` |
3dc3135b | 151 | |
6502293f | 152 | `wget http://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz` |
3dc3135b | 153 | |
6502293f | 154 | `tar xvzf ssl-1.15.tar.gz` |
3dc3135b | 155 | |
6502293f | 156 | `cd ssl-1.15` |
3dc3135b | 157 | |
6502293f | 158 | `make` |
3dc3135b | 159 | |
6502293f | 160 | `cd ../` |
3dc3135b | 161 | |
6502293f | 162 | `ln -sf ssl-1.15/build/lib.linux-*/ssl ssl` |
e5d60a8b | 163 |