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, a WebSocket emulator using Adobe Flash
  11 (http://github.com/gimite/web-socket-js).
  12
  13 In addition, as3crypto has been added to web-socket-js to implement
  14 WebSocket SSL/TLS encryption, i.e. the "wss://" URI scheme.
  15 (http://github.com/lyokato/as3crypto_patched).
  16
  17
  18 ### Requirements
  19
  20 Until there is VNC server support for WebSocket connections, you need
  21 to use a WebSocket to TCP socket proxy. There is a python proxy
  22 included ('wsproxy'). One advantage of using the proxy is that it has
  23 builtin support for SSL/TLS encryption (i.e. "wss://").
  24
  25 There a few reasons why a proxy is required:
  26
  27   1. WebSocket is not a pure socket protocol. There is an initial HTTP
  28      like handshake to allow easy hand-off by web servers and allow
  29      some origin policy exchange. Also, each WebSocket frame begins
  30      with 0 ('\x00') and ends with 255 ('\xff').
  31
  32   2. Javascript itself does not have the ability to handle pure byte
  33      strings (Unicode encoding messes with it) even though you can
  34      read them with WebSocket. The python proxy encodes the data so
  35      that the Javascript client can base64 decode the data into an
  36      array.
  37
  38   3. When using the web-socket-js as a fallback, WebSocket 'onmessage'
  39      events may arrive out of order. In order to compensate for this
  40      the client asks the proxy (using the initial query string) to add
  41      sequence numbers to each packet.
  42
  43
  44 ### Usage
  45
  46 * To encrypt the traffic using the WebSocket 'wss://' URI scheme you
  47   need to generate a certificate for the proxy to load. You can generate
  48   a self-signed certificate using openssl. The common name should be the
  49   hostname of the server where the proxy will be running:
  50
  51     `openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem`
  52
  53 * run a VNC server.
  54
  55     `vncserver :1`
  56
  57 * run the python proxy:
  58
  59     `./utils/wsproxy.py -f source_port target_addr:target_port
  60
  61     `./utils/wsproxy.py -f 8787 localhost:5901`
  62
  63
  64 * run the mini python web server to serve the directory:
  65
  66     `./utils/web.py PORT`
  67
  68     `./utils/web.py 8080`
  69
  70 * Point your web browser at http://localhost:8080/vnc.html
  71  (or whatever port you used above to run the web server).
  72
  73 * Specify the host and port where the proxy is running and the
  74   password that the vnc server is using (if any). Hit the Connect
  75   button and enjoy!
  76
  77
  78 ### Browser Support
  79
  80 #### Linux (Ubuntu 9.04)
  81
  82 <table>
  83     <tr>
  84         <th> OS </th> <th> Browser </th>
  85         <th> Status </th>
  86         <th> Notes </th>
  87     </tr> <tr>
  88         <td> Jaunty </td> <td> Chrome 5.0.375.29 </td>
  89         <td> Works great </td>
  90         <td> Very fast. Native WebSockets. </td>
  91     </tr> <tr>
  92         <td> Jaunty </td> <td> Firefox 3.5 </td>
  93         <td> Works well </td>
  94         <td> Large full-color images are somewhat slow due to
  95              web-socket-js overhead. </td>
  96     </tr> <tr>
  97         <td> Jaunty </td> <td> Opera 10.60 </td>
  98         <td> Works </td>
  99         <td> web-socket-js interaction makes it slower than firefox
 100              and causes occasional hangs. </td>
 101     </tr> <tr>
 102         <td> Jaunty </td> <td> Arora 0.5 </td>
 103         <td> Works </td>
 104         <td> Broken putImageData so large full-color images
 105              are slow. Uses web-socket-js. </td>
 106     </tr> <tr>
 107         <td> Jaunty </td> <td> Konqueror 4.2.2 </td>
 108         <td> <em>Broken</em> </td>
 109         <td> web-socket-js never loads </td>
 110     </tr> <tr>
 111         <td> </td>
 112         <td> </td>
 113         <td> </td>
 114         <td> </td>
 115     </tr> <tr>
 116         <td> WinXP </td> <td> Chrome 5.0.375.99 </td>
 117         <td> Works great </td>
 118         <td> Very fast. Native WebSockets. </td>
 119     </tr> <tr>
 120         <td> WinXP </td> <td> Firefox 3.0.19 </td>
 121         <td> Works well </td>
 122         <td> Some overhead from web-socket-js. </td>
 123     </tr> <tr>
 124         <td> WinXP </td> <td> Safari 5.0 </td>
 125         <td> Works </td>
 126         <td> Fast. Native WebSockets. Broken 'wss://'
 127              (SSL) - weird client header </td>
 128     </tr> <tr>
 129         <td> WinXP </td> <td> IE 6, 7, 8</td>
 130         <td> <em>Non-starter</em> </td>
 131         <td> No basic Canvas support. Javascript painfully slow. </td>
 132     </tr>
 133 </table>
 134
 135
 136 ### Integration
 137
 138 The client is designed to be easily integrated with existing web
 139 structure and style.
 140
 141 At a minimum you must include the `vnc.js` and `default_controls.js`
 142 scripts and call their load() functions. For example:
 143
 144     <head>
 145         <script src='include/vnc.js'></script>
 146         <script src="include/default_controls.js"></script>
 147     </head>
 148     <body>
 149         <div id='vnc'>Loading</div>
 150     </body>
 151     <script>
 152         window.onload = function () {
 153             DefaultControls.load('vnc');
 154             RFB.load(); };
 155     </script>
 156
 157 See `vnc.html` and `vnc_auto.html` for examples. The file
 158 `include/plain.css` has a list of stylable elements.
 159
 160 The `vnc.js` also includes other scripts within the `include`
 161 sub-directory. The `VNC_uri_prefix` variable can be use override the
 162 URL path to the directory that contains the `include` sub-directory.