README.md

   1 noVNC: HTML5 VNC Client
   2 ======================
   3
   4
   5 Description
   6 -----------
   7
   8 noVNC is a VNC client implemented using HTML5 technologies,
   9 specifically Canvas and WebSocket (supports 'wss://' encryption).
  10
  11 For browsers that do not have builtin WebSocket support, the project
  12 includes web-socket-js, a WebSocket emulator using Adobe Flash
  13 (http://github.com/gimite/web-socket-js).
  14
  15 In addition, as3crypto has been added to web-socket-js to implement
  16 WebSocket SSL/TLS encryption, i.e. the "wss://" URI scheme.
  17 (http://github.com/lyokato/as3crypto_patched).
  18
  19
  20 Requirements
  21 ------------
  22
  23 Until there is VNC server support for WebSocket connections, you need
  24 to use a WebSocket to TCP socket proxy. There is a python proxy
  25 included ('wsproxy'). One advantage of using the proxy is that it has
  26 builtin support for SSL/TLS encryption (i.e. "wss://").
  27
  28 There a few reasons why a proxy is required:
  29
  30   1. WebSocket is not a pure socket protocol. There is an initial HTTP
  31      like handshake to allow easy hand-off by web servers and allow
  32      some origin policy exchange. Also, each WebSocket frame begins
  33      with 0 ('\x00') and ends with 255 ('\xff').
  34
  35   2. Javascript itself does not have the ability to handle pure byte
  36      strings (Unicode encoding messes with it) even though you can
  37      read them with WebSocket. The python proxy encodes the data so
  38      that the Javascript client can base64 decode the data into an
  39      array. The client requests this encoding
  40
  41   3. When using the web-socket-js as a fallback, WebSocket 'onmessage'
  42      events may arrive out of order. In order to compensate for this
  43      the client asks the proxy (using the initial query string) to add
  44      sequence numbers to each packet.
  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
  54 Usage
  55 -----
  56
  57 * run a VNC server.
  58
  59     `vncserver :1`
  60
  61 * run the python proxy:
  62
  63     `./wsproxy.py [listen_port] [vnc_host] [vnc_port]`
  64
  65     `./wsproxy.py 8787 localhost 5901`
  66
  67
  68 * run the mini python web server to serve the directory:
  69
  70     `./web.py PORT`
  71
  72     `./web.py 8080`
  73
  74 * Point your web browser at http://localhost:8080/vnc.html
  75  (or whatever port you used above to run the web server).
  76
  77 * Specify the host and port where the proxy is running and the
  78   password that the vnc server is using (if any). Hit the Connect
  79   button and enjoy!
  80
  81
  82 Integration
  83 -----------
  84
  85 The client is designed to be easily integrated with existing web
  86 structure and style.
  87
  88 At a minimum you must include the script and call the RFB.load()
  89 function which takes a parameter that is the ID of the DOM element to
  90 fill. For example:
  91
  92     <body>
  93         <div id='vnc'>Loading</div>
  94     </body>
  95     <script src='vnc.js'></script>
  96     <script> windows.onload = RFB.load('vnc'); </script>
  97
  98
  99 The file `include/plain.css` has a list of stylable elements.