From 3d592ad85803dcf3f9de5acf5086b24e8cb26f1d Mon Sep 17 00:00:00 2001 From: Joel Martin Date: Tue, 18 Jan 2011 14:17:42 -0600 Subject: [PATCH] Add advanced usage, integration, troubleshooting. Move sections from main README here. --- Advanced-usage.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++ Home.md | 15 +++++++++--- Integration.md | 27 ++++++++++++++++++++++ Troubleshooting.md | 20 ++++++++++++++++ 4 files changed, 116 insertions(+), 3 deletions(-) create mode 100644 Advanced-usage.md create mode 100644 Integration.md create mode 100644 Troubleshooting.md diff --git a/Advanced-usage.md b/Advanced-usage.md new file mode 100644 index 0000000..f99028d --- /dev/null +++ b/Advanced-usage.md @@ -0,0 +1,57 @@ +* To encrypt the traffic using the WebSocket 'wss://' URI scheme you + need to generate a certificate for the proxy to load. By default the + proxy loads a certificate file name `self.pem` but the `--cert=CERT` + option can override the file name. You can generate a self-signed + certificate using openssl. When asked for the common name, use the + hostname of the server where the proxy will be running: + + `openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem` + +* `tightvnc` provide a nice startup script that can be used to run + a separate X desktop that is served by VNC. To install and run the + server under Ubuntu you would do something like this: + + `sudo apt-get install tightvncserver` + + `vncserver :1` + + The VNC server will run in the background. The port that it runs + on is the display number + 5900 (i.e. 5901 in the case above). + +* `x11vnc` can be used to share your current X desktop. Note that if + you run noVNC on the X desktop you are connecting to via VNC you + will get a neat hall of mirrors effect, but the the client and + server will fight over the mouse. + + `sudo apt-get install x11vnc` + + `x11vnc -forever -display :0` + + Without the `-forever` option, x11vnc will exit after the first + disconnect. The `-display` option indicates the exiting X display to + share. The port that it runs on is the display number + 5900 (i.e. + 5900 in the case above). + +* To run the python proxy directly without using launch script (to + pass additional options for example): + + `./utils/websockify source_port target_addr:target_port` + + `./utils/websockify 8787 localhost:5901` + +* To activate the mini-webserver in websockify use the `--web DIR` + option: + + `./utils/websockify --web ./ 8787 localhost:5901` + + +* Point your web browser at http://localhost:8787/vnc.html. On the + page enter the location where the proxy is running (localhost and + 8787) and the password that the vnc server is using (if any). Hit + the Connect button. + +* If you are using python 2.3 or 2.4 and you want websockify to + support 'wss://' (TLS) then see the + [websockify README](http://github.com/kanaka/websockify/blob/master/README.md) + for instructions on building the ssl module. + diff --git a/Home.md b/Home.md index 8089707..77e0d48 100644 --- a/Home.md +++ b/Home.md @@ -1,10 +1,19 @@ noVNC is a browser based VNC client implemented using HTML5 technologies (Web Sockets, Canvas) with encryption (wss://) support. + ### Wiki Pages -- [Browser Support](Browser-support) +- [Browser Support](wiki/Browser-support) + +- [Advanced Usage](wiki/Advanced-usage). Generating an SSL + certificate, starting a VNC server, advanced websockify usage, etc. + +- [Integrating noVNC](wiki/Integration) into existing projects. + +- [Troubleshooting noVNC problems](wiki/Troubleshooting). + +- [Performance Notes](wiki/Performance-notes) -- [Performance Notes](Performance-notes) ### Other noVNC pages: @@ -12,4 +21,4 @@ noVNC is a browser based VNC client implemented using HTML5 technologies (Web So - [Videos and Screenshots](http://kanaka.github.com/noVNC/screenshots.html) -- [Online demo/playback](http://kanaka.github.com/noVNC/demo1.html) \ No newline at end of file +- [Online demo/playback](http://kanaka.github.com/noVNC/demo1.html) diff --git a/Integration.md b/Integration.md new file mode 100644 index 0000000..d3bbd86 --- /dev/null +++ b/Integration.md @@ -0,0 +1,27 @@ +noVNC is designed to be easily integrated into existing web sites with +the existing structure and styling. + +At a minimum you must include the `vnc.js` and `ui.js` scripts and then call +UI.load(). For example: + + + + + + +
Loading
+ + + + +See `vnc.html` and `vnc_auto.html` for examples. The file +`include/plain.css` has a list of stylable elements. + +The `vnc.js` also includes other scripts within the `include` +sub-directory. The `VNC_uri_prefix` variable can be use override the +URL path to the `include` sub-directory. + diff --git a/Troubleshooting.md b/Troubleshooting.md new file mode 100644 index 0000000..1ff1190 --- /dev/null +++ b/Troubleshooting.md @@ -0,0 +1,20 @@ +You will need console logging support in the browser. Recent Chrome +and Opera versions have built in support. Firefox has a nice extension +called "firebug" that gives console logging support. + +First, load the noVNC page with `logging=debug` added to the query string. +For example `vnc.html?logging=debug`. + +Then, activate the console logger in your browser. With Chrome it can +be activate using Ctrl+Shift+J and then switching to the "Console" +tab. With firefox+firebug, it can be activated using Ctrl+F12. + +Now reproduce the problem. The console log output will give more +information about what is going wrong and where in the code the +problem is located. + +If you file a issue/bug, it is very helpful for me to have the last +page of console output leading up the problem in the issue report. +Other helpful issue/bug information: browser version, OS version, +noVNC git version, and VNC server name/version. +