path: root/x11vnc/misc/enhanced_tightvnc_viewer/README

       Enhanced TightVNC Viewer (SSVNC: SSL/SSH VNC viewer)

Copyright (c) 2006-2007 Karl J. Runge <runge@karlrunge.com>
All rights reserved.

These bundles provide 1) An enhanced TightVNC Viewer on Unix, 2) Binaries
for many Operating Systems (including Windows and Mac OS X) for your
convenience, 3) Wrapper scripts and a GUI for gluing them all together.

One can straight-forwardly download all of the components and get them
to work together by oneself: this bundle is mostly for your convenience
to combine and wrap together the freely available software.

Bundled software co-shipped is copyright and licensed by others.
See these sites and related ones for more information:

        http://www.tightvnc.com
        http://www.realvnc.com
        http://www.stunnel.org
        http://stunnel.mirt.net
        http://www.openssl.org
        http://www.chiark.greenend.org.uk/~sgtatham/putty/
	http://sourceforge.net/projects/cotvnc/

Note: Some of the binaries included contain cryptographic software that
you may not be allowed to download, use, or redistribute.  Please check
your situation first before downloading any of these bundles.  See the
survey http://rechten.uvt.nl/koops/cryptolaw/index.htm for useful
information.

All work done by Karl J. Runge in this project is
Copyright (c) 2006-2007 Karl J. Runge and is licensed under the GPL as
described in the file COPYING in this directory.

All the files and information in this project are provided "AS IS"
without any warranty of any kind.  Use them at your own risk.


=============================================================================

This bundle contains a convenient collection of enhanced TightVNC
viewers and stunnel binaries for different flavors of Unix and wrapper
scripts and a GUI front-end to glue them together.  Automatic SSL and
SSH encryption tunnelling is provided.

A Windows SSL wrapper for the bundled TightVNC binary and other utilities
are provided.  (Launch ssvnc.exe in the Windows subdirectory).

The short name of the project is "ssvnc" for SSL/SSH VNC Viewer.

It is a self-contained bundle, you could carry it around on, say,
a USB memory stick for secure VNC viewing from almost any machine,
Unix, Mac, or Windows.

Features:
--------

The enhanced TightVNC viewer features are:

	- SSL support for connections using the bundled stunnel program.

	- Automatic SSH connections from the GUI (ssh must already be
	  installed on Unix; bundled plink is used on Windows)

	- Ability to Save and Load VNC profiles for different hosts.

	- Create or Import SSL Certificates and Private Keys.

	- Automatic Service tunnelling via SSH for CUPS and SMB Printing,
	  ESD/ARTSD Audio, and SMB (Windows/Samba) filesystem mounting.

        - Port Knocking for "closed port" SSH/SSL connections.  In addition
          to a simple fixed port sequence and one-time-pad implementation,
          a hook is also provided to run any port knocking client before a
          connecting.

	- You can also use your own VNC Viewer, e.g. UltraVNC or RealVNC,
	  with the front-end GUI or scripts if you like.

	- Sets up any additional SSH port redirections that you want.

	- Support for native MacOS X usage with bundled Chicken of the
	  VNC viewer.

	- Reverse (viewer listening) VNC connections via SSL and SSH.

	- Dynamic VNC Server Port determination and redirection (using
	  ssh's builtin SOCKS proxy, -D) for servers like x11vnc that
	  print out PORT= at startup.


	(the following features only apply to the bundled Unix tightvnc viewer)

	- rfbNewFBSize VNC support (screen resizing)

	- ZRLE VNC encoding support (RealVNC's encoding)

	- Extremely low color modes: 64 and 8 colors in 8bpp
	  (-use64/-bgr222, -use8/-bgr111)

	- Medium color mode: 16bpp mode even for 32bpp Viewer display
	  (-16bpp/-bgr565)

	- Cursor alphablending with x11vnc at 32bpp (-alpha option)

	- Maintains its own BackingStore if the X server does not

	- x11vnc's client-side caching -ncache method cropping option
	  (-ycrop n). This will "hide" the large pixel buffer cache
	  below the actual display. Set to actual height or use -1 for
	  autodetection (tall screens are autodetected by default).

	- Scrollbar width setting: -sbwidth n, the default is very thin,
	  2 pixels, for less distracting -ycrop usage.

	- The default for localhost:0 connections is not raw encoding
	  (local machine). Default assumes you are using SSH tunnel. Use
	  -rawlocal to revert.

	- XGrabServer support for fullscreen mode, for old window managers
	  (-grab/-graball option).

	- Fix for Popup menu positioning for old window managers
	  (-popupfix option).

	- Improvements to the Popup menu, all of these can now be changed
	  dynamically via the menu: ViewOnly, Toggle Bell, CursorShape
	  updates, X11 Cursor, Cursor Alphablending, Toggle Tight/ZRLE,
	  Toggle JPEG, FullColor/16bpp/8bpp (256/64/8 colors), Greyscale
	  for low color modes.

	- Support for UltraVNC extensions: Single Window, Disable
	  Server-side Input, 1/n Server side scaling, Text Chat (shell
	  terminal UI). Both UltraVNC and x11vnc servers support these
	  extensions

	- Run vncviewer -help for all options.



The list of software bundled in the archive files:

        TightVNC Viewer           (windows, unix, macosx)
        Chicken of the VNC Viewer (macosx)
        Stunnel                   (windows, unix, macosx)
        Putty/Plink/Pageant       (windows)
        OpenSSL                   (windows)
        esound                    (windows)

These are all self-contained in the bundle directory: they will not be
installed on your system.  Just un-zip or un-tar the file you downloaded
and run it straight from its directory.


Quick Start:
-----------

Unix and Mac OS X:

    Inside a Terminal do something like the following.

    Unpack the archive:

        % gzip -dc ssvnc-1.0.15.tar.gz | tar xvf -

    Run the GUI:

        % ./ssvnc/Unix/ssvnc               (for Unix)

        % ./ssvnc/MacOSX/ssvnc             (for Mac OS X)

    On MacOSX you could also click on the SSVNC app in the Finder.

    The smaller file "ssvnc_no_windows-1.0.15.tar.gz"
    could have been used as well.

    On MacOSX there is also a SSVNC.app directory icon you can click on
    in Finder to start the application.


Windows:

    Unzip, using WinZip or a similar utility, the zip file:

        ssvnc-1.0.15.zip

    Run the GUI, e.g.:

	Start -> Run -> Browse

    and then navigate to

        .../ssvnc/Windows/ssvnc.exe

    select Open, and then OK to launch it.

    The smaller file "ssvnc_windows_only-1.0.15.zip"
    could have been used as well.

    You can make a Windows shortcut to this program if you want to.

    See the Windows/README.txt for more info.

    

Important Note for Windows Vista: One user reports that on Windows Vista
if you move or extract the "ssvnc" folder down to the "Program Files"
folder you will be prompted to do this as the Administrator. But then
when you start up ssvnc, as a regular user, it cannot create files in
that folder and so it fails to run properly. We recommend to not copy
or extract the "ssvnc" folder into "Program Files". Rather, extract
it to somewhere you have write permission (e.g. C:\ or your User dir)
and create a Shortcut to ssvnc.exe on the desktop.

If you must put a launcher file down in "Program Files", perhaps an
"ssvnc.bat" that looks like this:

C:
cd \ssvnc\Windows
ssvnc.exe


Bundle Info:
------------

The bundle files unpack a directory/folder named: ssvnc

It contains these programs to launch the GUI:

        Windows/ssvnc.exe        for Windows
        MacOSX/ssvnc             for Mac OS X
        Unix/ssvnc               for Unix

(the Mac OS X and Unix launchers are simply links to the bin directory).


Your bundle file should have included binaries for many OS's: Linux,
Solaris, FreeBSD, etc.  Unpack your archive and see the subdirectories of

	./bin

for the ones that were shipped in this project, e.g. ./bin/Linux.i686
Run "uname -sm" to see your OS+arch combination (n.b. all Linux x86 are
mapped to Linux.i686).   (See the ./bin/ssvnc_cmd -h output for how to
override platform autodection via the UNAME env. var).


Memory Stick Usage:
-------------------

If you create a directory named "Home" in that toplevel ssvnc directory
then that will be used as the base for storing VNC profiles and
certificates.  Also, for convenience, if you first run the command with
"." as an argument (e.g. "ssvnc .") it will automatically create that
"Home" directory for you.  This is handy if you want to place SSVNC
on a USB flash drive that you carry around for mobile use and you want
the profiles you create to stay with the drive (otherwise you'd have to
browse to the drive directory each time you load or save).

WARNING: if you use ssvnc from an "Internet Cafe", i.e.  an untrusted
computer, an intruder may be capturing keystrokes etc.


External Dependencies:
----------------------

On Windows everything is included.  Let us know if you find otherwise.

On Unix depending on what you do you need these programs installed:
	
	- basic unix utilities (sh, ls, cat, awk, sed, etc..)
	- tcl/tk (wish interpreter)
	- xterm
	- perl
	- ssh
	- openssl

    Lesser used ones: netcat, esd/artsd, smbclient, smbmount, cups
	
On Mac OS X depending on what you do you need these programs installed:
	
	- basic unix utilities (sh, ls, cat, awk, sed, etc..)
	- tcl/tk (wish interpreter)
	- Terminal
	- perl
	- ssh
	- openssl

    Lesser used ones: netcat, smbclient, cups


Most Mac OS X and Unix OS come with the main components installed. 
	

If you need to Build:
--------------------

If your OS/arch is not included or the provided binary has the wrong
library dependencies, etc. the script "build.unix" may be able to
successfully build on for you and deposit the binaries down in ./bin/...
using the included source code.

You MUST run the build.unix script from this directory (that this toplevel
README is in, i.e "ssvnc") and like this:

	./build.unix

To use custom locations for libraries see the LDFLAGS_OS and CPPFLAGS_OS
description at the top of the build.unix script.

Feel free to ask us if you need help running ./build.unix


The programs:
------------

Unpack your archive, and you will see "bin", "Windows", "src" directories
and other files.  The command line wrapper scripts: 

	./bin/ssvnc_cmd
	./bin/tightvncviewer

are the main programs that are run and will try to autodetect your OS+arch
combination and if binaries are present for it automatically use them.
(if not found try the running the build.unix script).

If you prefer a GUI to prompt for parameters and then start ssvnc_cmd
you can run this instead:

	./bin/ssvnc       

this is the same GUI that is run on Windows (the ssvnc.exe).

For convenience, you can make symlinks from a directory in your PATH to
any of the 3 programs above you wish to run.  That is all you usually
need to do for it to pick up all of the binaries, utils, etc. E.g.
assuming $HOME/bin is in your $PATH:

	cd $HOME/bin
	ln -s /path/to/ssvnc/bin/{s,t}* .

(note the "." at the end). The above commands is basically the way to
"install" this on Unix.

Also symlinks to the GUI launcher script are provided in:

	MacOSX/ssvnc
	Unix/ssvnc

On Windows unpack your archive and run:

	Windows/ssvnc.exe


Examples:
--------

The following assume you are in the toplevel directory of the
archive you unpacked.

Use enhanced TightVNC unix viewer to connect to x11vnc via SSL:

	./bin/ssvnc_cmd   far-away.east:0

	./bin/tightvncviewer -ssl  far-away.east:0   (same)

	./bin/ssvnc                                  (start GUI launcher)

Use enhanced TightVNC unix viewer without SSL:

	./bin/tightvncviewer far-away.east:0

Use SSL to connect to a x11vnc server, and also verify the server's
identity using the SSL Certificate in the file ./x11vnc.pem:

	./bin/ssvnc_cmd -alpha -verify ./x11vnc.pem far-away.east:0

(also turns on the viewer-side cursor alphablending hack). 


Brief description of the subdirectories:
---------------------------------------

	./bin/util		some utility scripts, e.g. ss_vncviewer
				and ssvnc.tcl

	./src			source code and patches.
	./src/zips		zip files of source code and binaries.

	./src/vnc_unixsrc	unpacked tightvnc source code tree.
	./src/stunnel-4.14	unpacked stunnel source code tree.
	./src/patches		patches to TightVNC viewer for the new
				features on Unix (used by build.unix).
	./src/tmp		temporary build dir for build.unix
				(the last four are used by build.unix)


	./man			man pages for TightVNC viewer and stunnel.

	./Windows		Stock TightVNC viewer and Stunnel, Openssl
				etc Windows binaries. ssvnc.exe is the
				program to run.

	./MacOSX		contains an unpacked Chicken of the VNC
				viewer and a symlink to ssvnc.

	./Unix			contains a symlink to ssvnc.

Depending on which bundle you use not all of the above may be present.
The smallest bundles with binaries are:

	ssvnc_windows_only-1.x.y.zip   Windows
	ssvnc_no_windows-1.x.y.tar.gz  Unix and MacOSX

however, the tiny scripts only one (only 60KB) will run properly on Unix
as long as you install external vncviewer and stunnel packages:

	ssvnc_unix_minimal-1.x.y.tar.gz


Help and Info:
-------------

For more help on other options and usage patterns run these:

	./bin/ssvnc_cmd -h
	./bin/util/ss_vncviewer -h

See also:

	http://www.karlrunge.com/x11vnc
	http://www.karlrunge.com/x11vnc/#faq
	x11vnc -h | more

	http://www.stunnel.org
	http://stunnel.mirt.net
	http://www.openssl.org
	http://www.tightvnc.com
        http://www.realvnc.com
        http://www.chiark.greenend.org.uk/~sgtatham/putty/
	http://sourceforge.net/projects/cotvnc/