README.md

   1 ## noVNC: HTML5 VNC Client
   2
   3
   4 ### Description
   5
   6 noVNC is a VNC client implemented using HTML5 technologies,
   7 specifically Canvas and WebSocket (supports 'wss://' encryption).
   8
   9 For browsers that do not have builtin WebSocket support, the project
  10 includes [web-socket-js](http://github.com/gimite/web-socket-js),
  11 a WebSocket emulator using Adobe Flash .
  12
  13 In addition, [as3crypto](http://github.com/lyokato/as3crypto_patched)
  14 has been added to web-socket-js to implement WebSocket SSL/TLS
  15 encryption, i.e. the "wss://" URI scheme.
  16
  17 Running in Chrome before and after connecting:
  18 <img src="http://kanaka.github.com/noVNC/img/noVNC-1.jpg" width=400>&nbsp;<img src="http://kanaka.github.com/noVNC/img/noVNC-2.jpg" width=400>
  19
  20 ### Requirements
  21
  22 Until there is VNC server support for WebSocket connections, you need
  23 to use a WebSocket to TCP socket proxy. There is a python proxy
  24 included ('wsproxy'). One advantage of using the proxy is that it has
  25 builtin support for SSL/TLS encryption (i.e. "wss://").
  26
  27 There a few reasons why a proxy is required:
  28
  29   1. WebSocket is not a pure socket protocol. There is an initial HTTP
  30      like handshake to allow easy hand-off by web servers and allow
  31      some origin policy exchange. Also, each WebSocket frame begins
  32      with 0 ('\x00') and ends with 255 ('\xff').
  33
  34   2. Javascript itself does not have the ability to handle pure byte
  35      strings (Unicode encoding messes with it) even though you can
  36      read them with WebSocket. The python proxy encodes the data so
  37      that the Javascript client can base64 decode the data into an
  38      array.
  39
  40   3. When using the web-socket-js as a fallback, WebSocket 'onmessage'
  41      events may arrive out of order. In order to compensate for this
  42      the client asks the proxy (using the initial query string) to add
  43      sequence numbers to each packet.
  44
  45
  46 ### Usage
  47
  48 * To encrypt the traffic using the WebSocket 'wss://' URI scheme you
  49   need to generate a certificate for the proxy to load. You can generate
  50   a self-signed certificate using openssl. The common name should be the
  51   hostname of the server where the proxy will be running:
  52
  53     `openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem`
  54
  55 * run a VNC server.
  56
  57     `vncserver :1`
  58
  59 * run the python proxy:
  60
  61     `./utils/wsproxy.py -f source_port target_addr:target_port
  62
  63     `./utils/wsproxy.py -f 8787 localhost:5901`
  64
  65
  66 * run the mini python web server to serve the directory:
  67
  68     `./utils/web.py PORT`
  69
  70     `./utils/web.py 8080`
  71
  72 * Point your web browser at http://localhost:8080/vnc.html
  73  (or whatever port you used above to run the web server).
  74
  75 * Specify the host and port where the proxy is running and the
  76   password that the vnc server is using (if any). Hit the Connect
  77   button and enjoy!
  78
  79
  80 ### Browser Support
  81
  82 In the following table Jaunty is Ubuntu 9.04 and WinXP is Windows XP.
  83
  84 #### Linux (Ubuntu 9.04)
  85
  86 <table>
  87     <tr>
  88         <th>OS</th> <th>Browser</th>
  89         <th>Status</th>
  90         <th>Notes</th>
  91     </tr> <tr>
  92         <td>Jaunty</td> <td>Chrome 5.0.375.29</td>
  93         <td>Excellent</td>
  94         <td>Very fast. Native WebSockets.</td>
  95     </tr> <tr>
  96         <td>Jaunty</td> <td>Firefox 3.5</td>
  97         <td>Good</td>
  98         <td>Large full-color images are somewhat slow from web-socket-js overhead.</td>
  99     </tr> <tr>
 100         <td>Jaunty</td> <td>Opera 10.60</td>
 101         <td>Poor</td>
 102         <td>web-socket-js problems, mouse/keyboard issues. See note 1</td>
 103     </tr> <tr>
 104         <td>Jaunty</td> <td>Arora 0.5</td>
 105         <td>Good</td>
 106         <td>Broken putImageData so large full-color images
 107             are slow. Uses web-socket-js.</td>
 108     </tr> <tr>
 109         <td>Jaunty</td> <td>Konqueror 4.2.2</td>
 110         <td><strong>Broken</strong></td>
 111         <td>web-socket-js never loads</td>
 112     </tr> <tr>
 113         <td></td>
 114         <td></td>
 115         <td></td>
 116         <td></td>
 117     </tr> <tr>
 118         <td>WinXP</td> <td>Chrome 5.0.375.99</td>
 119         <td>Excellent</td>
 120         <td>Very fast. Native WebSockets.</td>
 121     </tr> <tr>
 122         <td>WinXP</td> <td>Firefox 3.0.19</td>
 123         <td>Good</td>
 124         <td>Some overhead from web-socket-js.</td>
 125     </tr> <tr>
 126         <td>WinXP</td> <td>Safari 5.0</td>
 127         <td>Fair</td>
 128         <td>Fast. Native WebSockets. Broken 'wss://' (SSL) - weird client header</td>
 129     </tr> <tr>
 130         <td>WinXP</td> <td>IE 6, 7, 8</td>
 131         <td><strong>Non-starter</strong></td>
 132         <td>No basic Canvas support. Javascript painfully slow.</td>
 133     </tr>
 134 </table>
 135
 136
 137 * Note 1: Opera interacts poorly with web-socket-js. After two
 138   disconnects the browser tab or Flash often hang. Although Javascript
 139   is faster than Firefox 3.5, the high variability of web-socket-js
 140   performance results in overall performance being lower. Middle mouse
 141   clicks and keyboard events need some work to work properly under
 142   Opera.
 143
 144
 145 ### Integration
 146
 147 The client is designed to be easily integrated with existing web
 148 structure and style.
 149
 150 At a minimum you must include the `vnc.js` and `default_controls.js`
 151 scripts and call their load() functions. For example:
 152
 153     <head>
 154         <script src='include/vnc.js'></script>
 155         <script src="include/default_controls.js"></script>
 156     </head>
 157     <body>
 158         <div id='vnc'>Loading</div>
 159     </body>
 160     <script>
 161         window.onload = function () {
 162             DefaultControls.load('vnc');
 163             RFB.load(); };
 164     </script>
 165
 166 See `vnc.html` and `vnc_auto.html` for examples. The file
 167 `include/plain.css` has a list of stylable elements.
 168
 169 The `vnc.js` also includes other scripts within the `include`
 170 sub-directory. The `VNC_uri_prefix` variable can be use override the
 171 URL path to the directory that contains the `include` sub-directory.
 172
 173
 174 ### Troubleshooting
 175
 176 You will need console logging support in the browser. Recent Chrome
 177 and Opera versions have built in support. Firefox has a nice extension
 178 called "firebug" that gives console logging support.
 179
 180 First, load the noVNC page with `logging=debug` added to the query string.
 181 For example `vnc.html?logging=debug`.
 182
 183 Then, activate the console logger in your browser.  With Chrome it can
 184 be activate using Ctrl+Shift+J and then switching to the "Console"
 185 tab. With firefox+firebug, it can be activated using Ctrl+F12.
 186
 187 Now reproduce the problem. The console log output will give more
 188 information about what is going wrong and where in the code the
 189 problem is located. If you file a issue/bug, it can be very helpful to
 190 copy the last page of console output leading up the problem into the
 191 issue report.