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