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 WebSockets (supports 'wss://' encryption).
   8
   9 For browsers that do not have builtin WebSockets support, the project
  10 includes [web-socket-js](http://github.com/gimite/web-socket-js),
  11 a WebSockets 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 WebSockets SSL/TLS
  15 encryption, i.e. the "wss://" URI scheme.
  16
  17 Special thanks to [Sentry Data Systems](http://www.sentryds.com) for
  18 sponsoring ongoing development of this project (and for employing me).
  19
  20 ### Screenshots
  21
  22 Running in Chrome before and after connecting:
  23
  24 <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>
  25
  26 See more screenshots <a href="http://kanaka.github.com/noVNC/screenshots.html">here</a>.
  27
  28
  29 ### Requirements
  30
  31 Unless you are using a VNC server with support for WebSockets
  32 connections (only my [fork of libvncserver](http://github.com/kanaka/libvncserver)
  33 currently), you need to use a WebSockets to TCP socket proxy. There is
  34 a python proxy included ('wsproxy'). One advantage of using the proxy
  35 is that it has builtin support for SSL/TLS encryption (i.e. "wss://").
  36
  37 There a few reasons why a proxy is required:
  38
  39   1. WebSockets is not a pure socket protocol. There is an initial HTTP
  40      like handshake to allow easy hand-off by web servers and allow
  41      some origin policy exchange. Also, each WebSockets frame begins
  42      with 0 ('\x00') and ends with 255 ('\xff').
  43
  44   2. Javascript itself does not have the ability to handle pure byte
  45      arrays. The python proxy encodes the data as base64 so that the
  46      Javascript client can decode the data as an integer array.
  47
  48
  49 ### Quick Start
  50
  51 * Use the launch script to start a mini-webserver and the WebSockets
  52   proxy. The `--vnc` option is used to specify the location of
  53   a running VNC server:
  54
  55     `./utils/launch.sh --vnc localhost:5901`
  56
  57 * Point your browser to the cut-and-paste URL that is output by the
  58   launch script. Enter a password if the VNC server has one
  59   configured. Hit the Connect button and enjoy!
  60
  61
  62 ### Advanced usage
  63
  64 * To encrypt the traffic using the WebSocket 'wss://' URI scheme you
  65   need to generate a certificate for the proxy to load. By default the
  66   proxy loads a certificate file name `self.pem` but the `--cert=CERT`
  67   option can override the file name. You can generate a self-signed
  68   certificate using openssl. When asked for the common name, use the
  69   hostname of the server where the proxy will be running:
  70
  71     `openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem`
  72
  73 * `tightvnc` provide a nice startup script that can be used to run
  74   a separate X desktop that is served by VNC. To install and run the
  75   server under Ubuntu you would do something like this:
  76
  77     `sudo apt-get install tightvncserver`
  78     `vncserver :1`
  79
  80     The VNC server will run in the background. The port that it runs
  81     on is the display number + 5900 (i.e. 5901 in the case above).
  82
  83 * `x11vnc` can be used to share your current X desktop. Note that if
  84   you run noVNC on the X desktop you are connecting to via VNC you
  85   will get a neat hall of mirrors effect, but the the client and
  86   server will fight over the mouse.
  87
  88     `sudo apt-get install x11vnc`
  89     `x11vnc -forever -display :0`
  90
  91   Without the `-forever` option, x11vnc will exit after the first
  92   disconnect. The `-display` option indicates the exiting X display to
  93   share. The port that it runs on is the display number + 5900 (i.e.
  94   5900 in the case above).
  95
  96 * To run the python proxy directly without using launch script (to
  97   pass additional options for example):
  98
  99     `./utils/wsproxy.py -f source_port target_addr:target_port`
 100
 101     `./utils/wsproxy.py -f 8787 localhost:5901`
 102
 103 * To run the mini python web server without the launch script:
 104
 105     `./utils/web.py PORT`
 106
 107     `./utils/web.py 8080`
 108
 109 * Point your web browser at http://localhost:8080/vnc.html
 110  (or whatever port you used above to run the web server). Specify the
 111  host and port where the proxy is running and the password that the
 112  vnc server is using (if any). Hit the Connect button.
 113
 114
 115 ### Browser Support
 116
 117 In the following table Jaunty is Ubuntu 9.04 and WinXP is Windows XP.
 118
 119 #### Linux (Ubuntu 9.04)
 120
 121 <table>
 122     <tr>
 123         <th>OS</th> <th>Browser</th>
 124         <th>Status</th>
 125         <th>Notes</th>
 126     </tr> <tr>
 127         <td>Jaunty</td> <td>Chrome 5.0.375.29</td>
 128         <td>Excellent</td>
 129         <td>Very fast. Native WebSockets.</td>
 130     </tr> <tr>
 131         <td>Jaunty</td> <td>Firefox 3.5</td>
 132         <td>Good</td>
 133         <td>Large full-color images are somewhat slow from web-socket-js overhead.</td>
 134     </tr> <tr>
 135         <td>Jaunty</td> <td>Firefox 3.0.17</td>
 136         <td>Fair</td>
 137         <td>Works fine but is slow.</td>
 138     </tr> <tr>
 139         <td>Jaunty</td> <td>Opera 10.60</td>
 140         <td>Poor</td>
 141         <td>web-socket-js problems, mouse/keyboard issues. See note 1</td>
 142     </tr> <tr>
 143         <td>Jaunty</td> <td>Arora 0.5</td>
 144         <td>Good</td>
 145         <td>Broken putImageData so large full-color images
 146             are slow. Uses web-socket-js.</td>
 147     </tr> <tr>
 148         <td>Jaunty</td> <td>Konqueror 4.2.2</td>
 149         <td><strong>Broken</strong></td>
 150         <td>web-socket-js never loads</td>
 151     </tr> <tr>
 152         <td></td>
 153         <td></td>
 154         <td></td>
 155         <td></td>
 156     </tr> <tr>
 157         <td>WinXP</td> <td>Chrome 5.0.375.99</td>
 158         <td>Excellent</td>
 159         <td>Very fast. Native WebSockets.</td>
 160     </tr> <tr>
 161         <td>WinXP</td> <td>Firefox 3.0.19</td>
 162         <td>Good</td>
 163         <td>Some overhead from web-socket-js.</td>
 164     </tr> <tr>
 165         <td>WinXP</td> <td>Safari 5.0</td>
 166         <td>Fair</td>
 167         <td>Fast. Native WebSockets. Broken 'wss://' (SSL) - weird client header</td>
 168     </tr> <tr>
 169         <td>WinXP</td> <td>IE 6, 7, 8</td>
 170         <td><strong>Non-starter</strong></td>
 171         <td>No basic Canvas support. Javascript painfully slow.</td>
 172     </tr>
 173 </table>
 174
 175
 176 * Note 1: Opera interacts poorly with web-socket-js. After two
 177   disconnects the browser tab or Flash often hang. Although Javascript
 178   is faster than Firefox 3.5, the high variability of web-socket-js
 179   performance results in overall performance being lower. Middle mouse
 180   clicks and keyboard events need some work to work properly under
 181   Opera. Also, Opera does not have support for setting the cursor
 182   style url to a data URI scheme, so cursor pseudo-encoding is
 183   disabled.
 184
 185
 186 ### Integration
 187
 188 The client is designed to be easily integrated with existing web
 189 structure and style.
 190
 191 At a minimum you must include the `vnc.js` and `default_controls.js`
 192 scripts and call their load() functions. For example:
 193
 194     <head>
 195         <script src='include/vnc.js'></script>
 196         <script src="include/default_controls.js"></script>
 197     </head>
 198     <body>
 199         <div id='vnc'>Loading</div>
 200     </body>
 201     <script>
 202         window.onload = function () {
 203             DefaultControls.load('vnc');
 204             RFB.load(); };
 205     </script>
 206
 207 See `vnc.html` and `vnc_auto.html` for examples. The file
 208 `include/plain.css` has a list of stylable elements.
 209
 210 The `vnc.js` also includes other scripts within the `include`
 211 sub-directory. The `VNC_uri_prefix` variable can be use override the
 212 URL path to the directory that contains the `include` sub-directory.
 213
 214
 215 ### Troubleshooting
 216
 217 You will need console logging support in the browser. Recent Chrome
 218 and Opera versions have built in support. Firefox has a nice extension
 219 called "firebug" that gives console logging support.
 220
 221 First, load the noVNC page with `logging=debug` added to the query string.
 222 For example `vnc.html?logging=debug`.
 223
 224 Then, activate the console logger in your browser.  With Chrome it can
 225 be activate using Ctrl+Shift+J and then switching to the "Console"
 226 tab. With firefox+firebug, it can be activated using Ctrl+F12.
 227
 228 Now reproduce the problem. The console log output will give more
 229 information about what is going wrong and where in the code the
 230 problem is located. If you file a issue/bug, it can be very helpful to
 231 copy the last page of console output leading up the problem into the
 232 issue report.