README.md 3.9 KB
Newer Older
1
## noVNC: HTML5 VNC Client
2 3


4
### Description
5

Joel Martin's avatar
Joel Martin committed
6
noVNC is a VNC client implemented using HTML5 technologies,
7
specifically Canvas and WebSockets (supports 'wss://' encryption).
Joel Martin's avatar
Joel Martin committed
8 9
noVNC is licensed under the
[LGPLv3](http://www.gnu.org/licenses/lgpl.html).
10

11 12
Special thanks to [Sentry Data Systems](http://www.sentryds.com) for
sponsoring ongoing development of this project (and for employing me).
13

14
There are many companies/projects that have integrated noVNC into
15
their products including: [Sentry Data Systems](http://www.sentryds.com), [Ganeti Web Manager](http://code.osuosl.org/projects/ganeti-webmgr), [Archipel](http://archipelproject.org), [openQRM](http://www.openqrm.com/), [OpenNode](http://www.opennodecloud.com/), [OpenStack](http://www.openstack.org), [Broadway (HTML5 GDK/GTK+ backend)](http://blogs.gnome.org/alexl/2011/03/15/gtk-html-backend-update/), [OpenNebula](http://opennebula.org/), [CloudSigma](http://www.cloudsigma.com/), [Zentyal (formerly eBox)](http://www.zentyal.org/), and [SlapOS](http://www.slapos.org). See [this wiki page](https://github.com/kanaka/noVNC/wiki/ProjectsCompanies-using-noVNC) for more info and links.
16

17 18 19 20
Notable commits, announcements and news are posted to
@<a href="http://www.twitter.com/noVNC">noVNC</a>


21 22
### Screenshots

23
Running in Chrome before and after connecting:
24

25
<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>
26

27 28 29
See more screenshots <a href="http://kanaka.github.com/noVNC/screenshots.html">here</a>.


30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
### Browser Requirements

* HTML5 Canvas: Except for Internet Explorer, most
  browsers have had Canvas support for quite some time. Internet
  Explorer 9 will have Canvas support (finally).

* HTML5 WebSockets: For browsers that do not have builtin
  WebSockets support, the project includes
  <a href="http://github.com/gimite/web-socket-js">web-socket-js</a>,
  a WebSockets emulator using Adobe Flash.

* Fast Javascript Engine: noVNC avoids using new Javascript
  functionality so it will run on older browsers, but decode and
  rendering happen in Javascript, so a slow Javascript engine will
  mean noVNC is painfully slow.

46
* I maintain a more detailed list of browser compatibility <a
Joel Martin's avatar
Joel Martin committed
47
  href="https://github.com/kanaka/noVNC/wiki/Browser-support">here</a>.
48 49


50
### Server Requirements
51

52 53 54
Unless you are using a VNC server with support for WebSockets
connections (only my [fork of libvncserver](http://github.com/kanaka/libvncserver)
currently), you need to use a WebSockets to TCP socket proxy. There is
55 56 57
a python proxy included ('websockify'). One advantage of using the
proxy is that it has builtin support for SSL/TLS encryption (i.e.
"wss://").
58

Joel Martin's avatar
Joel Martin committed
59
There a few reasons why a proxy is required:
60

61
  1. WebSockets is not a pure socket protocol. There is an initial HTTP
Joel Martin's avatar
Joel Martin committed
62
     like handshake to allow easy hand-off by web servers and allow
63
     some origin policy exchange. Also, each WebSockets frame begins
Joel Martin's avatar
Joel Martin committed
64
     with 0 ('\x00') and ends with 255 ('\xff').
Joel Martin's avatar
Joel Martin committed
65 66

  2. Javascript itself does not have the ability to handle pure byte
Joel Martin's avatar
Joel Martin committed
67 68
     arrays. The python proxy encodes the data as base64 so that the
     Javascript client can decode the data as an integer array.
Joel Martin's avatar
Joel Martin committed
69

70

71
### Quick Start
72

73
* Use the launch script to start a mini-webserver and the WebSockets
74
  proxy (websockify). The `--vnc` option is used to specify the location of
75 76 77 78 79 80 81 82 83
  a running VNC server:

    `./utils/launch.sh --vnc localhost:5901`

* Point your browser to the cut-and-paste URL that is output by the
  launch script. Enter a password if the VNC server has one
  configured. Hit the Connect button and enjoy!


84
### Other Pages
85

Joel Martin's avatar
Joel Martin committed
86
* [Advanced Usage](https://github.com/kanaka/noVNC/wiki/Advanced-usage). Generating an SSL
87
  certificate, starting a VNC server, advanced websockify usage, etc.
88

Joel Martin's avatar
Joel Martin committed
89
* [Integrating noVNC](https://github.com/kanaka/noVNC/wiki/Integration) into existing projects.
90

Joel Martin's avatar
Joel Martin committed
91
* [Troubleshooting noVNC](https://github.com/kanaka/noVNC/wiki/Troubleshooting) problems.
92

93