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

(To Downloads)  (To Quick Start)

. .

The Enhanced TightVNC Viewer, SSVNC, adds encryption security to VNC connections.

The package provides a GUI for Windows, Mac OS X, and Unix that automatically starts up an STUNNEL SSL tunnel for SSL or ssh for SSH connections to x11vnc or any other VNC server, and then launches the VNC Viewer to use the encrypted tunnel.

SSL encrypted VNC connections to any VNC Server will work if they are running an SSL tunnel, such as STUNNEL, at their end. SSVNC can be used to perform SSH tunnelled connections to any VNC Server.

The Enhanced TightVNC Viewer package started as a project to add some patches to the long neglected Unix TightVNC Viewer. However, now the front-end GUI, encryption, and wrapper scripts features dwarf the Unix TightVNC Viewer patches (see the lists below).

The short name for this project is "ssvnc" for SSL/SSH VNC Viewer. This is the name of the command to start it.

There is a simplified SSH-Only mode (sshvnc). And an even more simplified Terminal-Services mode (tsvnc) for use with x11vnc on the remote side.

The tool has many additional features; see the descriptions below.

It is a self-contained bundle, you could carry it around on, say, a USB memory stick / flash drive for secure VNC viewing from almost any machine, Unix, Mac OS X, and Windows (and if you create a directory named "Home" in the toplevel ssvnc directory on the drive your VNC profiles and certs will be kept there as well).

 


Announcements:

Important: If you created any SSL certificates with SSVNC (or anything else) on a Debian or Ubuntu system from Sept. 2006 through May 2008, then those keys are likely extremely weak and can be easily cracked. The certificate files should be deleted and recreated on a non-Debian system or an updated one. See http://www.debian.org/security/2008/dsa-1571 for details. The same applies to SSH keys.

 


Wrappers and a tcl/tk GUI were written and patches were created for the TightVNC 1.3.9 vnc_unixsrc tree to add these features:

Unix TightVNC Viewer improvements (these only apply to the Unix VNC viewer):

The list of 3rd party software bundled in the archive files:

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 the frontend ssvnc straight from its directory.

Here is the Quick Start info from the README for how to do that:

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

Unix and Mac OS X:

    Inside a Terminal do something like the following.

    Unpack the archive:

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

    Run the GUI:

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

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

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

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

    On MacOSX if you don't like the Chicken of the VNC (e.g. no local
    cursors, no screen size rescaling, and no password prompting), and you
    have the XDarwin X server installed, you can set DISPLAY before starting
    ssvnc (or type DISPLAY=... in Host:Disp and hit Return).  Then our
    enhanced TightVNC viewer will be used instead of COTVNC.
    Update: there is now a 'Use X11 vncviewer on MacOSX' under Options ...


    If you want a SSH-only tool (without the distractions of SSL) run
    the command: 

                sshvnc

    instead of "ssvnc".  Or click "SSH-Only Mode" under Options.
    Control-h will toggle between the two modes.


    If you want a simple VNC Terminal Services only mode (requires x11vnc
    on the remote server) run the command:

                tsvnc

    instead of "ssvnc".  Or click "Terminal Services" under Options.
    Control-t will toggle between the two modes.

    "tsvnc profile-name" and "tsvnc user@hostname" work too.


Unix/MacOSX Install:

    There is no standard install, but you can make symlinks like so:

        cd /a/directory/in/PATH
        ln -s /path/to/ssvnc/bin/{s,t}* .

    Or put /path/to/ssvnc/bin, /path/to/ssvnc/Unix, or /path/to/ssvnc/MacOSX
    in your PATH.


Windows:

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

        ssvnc-1.0.20.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.20.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.


    If you want a SSH-only tool (without the distractions of SSL) run
    the command:

                sshvnc.bat

    Or click "SSH-Only Mode" under Options.


    If you want a simple VNC Terminal Services only mode (requires x11vnc
    on the remote server) run the command:

                tsvnc.bat

    Or click "Terminal Services" under Options.  Control-t will toggle
    between the two modes.  "tsvnc profile-name" and "tsvnc user@hostname"
    work too.

 

The bundle unpacks 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). See the README for more information.

The SSH-Only mode launcher program has name sshvnc. The Terminal Services mode launcher program (assumes x11vnc 0.8.4 or later and Xvfb installed on the server machine) has name tsvnc.

The Viewer SSL support is done via a wrapper script (bin/ssvnc_cmd that calls bin/util/ss_vncviewer) that starts up the STUNNEL tunnel first and then starts the TightVNC viewer pointed at that tunnel. The bin/ssvnc program is a GUI front-end to that script. See this FAQ for more details on SSL tunnelling. In SSH connection mode, the wrappers start up SSH appropriately.

 
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 the "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).

One user on Windows created a BAT file to launch SSVNC and needed to do this to get the Home directory correct:

cd \ssvnc\Windows
start \ssvnc\Windows\ssvnc.exe 
(an optional profile name can be supplied to the ssvnc.exe line)

WARNING: if you use ssvnc from an "Internet Cafe", i.e. some untrusted computer, please be aware that someone may have set up that machine to be capturing your keystrokes, etc.

 
SSH-Only version: The command "sshvnc" can be run instead of "ssvnc" to get an SSH-only version of the tool:

These also work: "sshvnc myprofile" and "sshvnc user@hostname". To switch from the regular SSVNC mode, click "SSH-Only Mode" under Options. This mode is less distracting if you never plan to use SSL, manage certificates, etc.

 
Terminal Services Only: The command "tsvnc" can be run instead of "ssvnc" to get a "Terminal Services" only version of the tool:

These also work: "tsvnc myprofile" and "tsvnc user@hostname". To switch from the regular SSVNC mode, click "Terminal Services" under Options.

This mode requires x11vnc (0.9.3 or later) installed on the remote machine to find, create, and manage the user sessions. SSH is used to create the encrypted and authenticated tunnel. The Xvfb (virtual framebuffer X server) program must also be installed on the remote system. However tsvnc will also connect to a real X session (i.e. on the physical hardware) if you are already logged into the X session; this is a useful access mode and does not require Xvfb on the remote system.

This mode should be very easy for beginner users to understand and use. On the remote end you only need to have x11vnc and Xvfb available in $PATH, and on the local end you just run something like:

   tsvnc myname@myhost.com
(or start up the tsvnc GUI first and then enter myname@myhost.com and press "Connect").

Normally the Terminal Services sessions created are virtual (RAM-only) ones (e.g. Xvfb, Xdummy, or Xvnc), however a nice feature is if you have a regular X session (i.e displaying on the physical hardware) on the remote machine that you are ALREADY logged into, then the x11vnc run from tsvnc will find it for you as well.

Also, there is setting "X Login" under Advanced Options that allows you to attach to a real X server with no one logged in yet (i.e. XDM/GDM/KDM Login Greeter screen) as long as you have sudo(1) permission on the remote machine.

Nice features to soon to be added to the tsvnc mode are easy CUPS printing (working fairly well) and Sound redirection (needs much work) of the Terminal Services Desktop session. It is easier in tsvnc mode because the entire desktop session can be started with the correct environment. ssvnc tries to handle the general case of an already started desktop and that is more difficult.

 
Proxies: Web proxies, SOCKS proxies, and the UltraVNC repeater proxy are supported to allow the SSVNC connection to go through the proxy to the otherwise unreachable VNC Server. SSH gateway machines can be used in the same way. Read
more about SSVNC proxy support here.

 
Dynamic VNC Server Port determination: If you are running SSVNC on Unix and are using SSH to start the remote VNC server and the VNC server prints out the line "PORT=NNNN" to indicate which dynamic port it is using (x11vnc does this), then if you prefix the SSH command with "PORT=" SSVNC will watch for the PORT=NNNN line and uses ssh's built in SOCKS proxy (ssh -D ...) to connect to the dynamic VNC server port through the SSH tunnel. For example:

        VNC Host:Display     user@somehost.com
        Remote SSH Command:  PORT= x11vnc -find
or "PORT= x11vnc -display :0 -localhost", etc. Or use "P= x11vnc ..."

There is also code to detect the display of the regular Unix vncserver(1). It extracts the display (and hence port) from the lines "New 'X' desktop is hostname:4" and also "VNC server is already running as :4". So you can use something like:

        PORT= vncserver; sleep 15
or:     PORT= vncserver :4; sleep 15
the latter is preferred because when you reconnect with it will find the already running one. The former one will keep creating new X sessions if called repeatedly.

If you use PORT= on Windows, a large random port is selected instead and the -rfbport option is passed to x11vnc (it does not work with vncserver).

 

 
Patches for Unix Tightvnc viewer:

The rfbNewFBSize support allows the enhanced TightVNC Unix viewer to resize when the server does (e.g. "x11vnc -R scale=3/4" remote control command).

The cursor alphablending is described here.

The RealVNC ZRLE encoding is supported, in addition to some low colors modes (16bpp and 8bpp at 256, 64, and even 8 colors, for use on very slow connections). Greyscales are also enabled for the low color modes.

The Popup menu (F8) is enhanced with the ability to change many things on the fly. F9 is added as a shortcut to toggle FullScreen mode.

Client Side Caching: The x11vnc client-side caching is handled nicely by this viewer. The very large pixel cache below the actual display in this caching method is distracting. Our Unix VNC viewer will automatically try to autodetect the actual display height if the framebuffer is very tall (more than twice as high as it is wide). One can also set the height to the known value via -ycrop n, or use -ycrop -1 to force autodection. In fullscreen mode one is not possible to scroll down to the pixel cache region. In non-fullscreen mode the window manager frame is "shrink-wrapped" around the actual screen display. You can still scroll down to the pixel cache region. The scrollbars are set to be very thin (2 pixels) to be less distracting. Use the -sbwidth n to make them wider.

Probably nobody is interested in the grabserver patch for old window managers when the viewer is in fullscreen mode... This and some other unfixed bugs have been fixed in our patches (fullscreen toggle works with KDE, -x11cursor has been fixed, and the dot cursor has been made smaller).

From the -help output:

TightVNC viewer version 1.3.9 (SSVNC)

Usage: ./vncviewer [<OPTIONS>] [<HOST>][:<DISPLAY#>]
       ./vncviewer [<OPTIONS>] [<HOST>][::<PORT#>]
       ./vncviewer [<OPTIONS>] -listen [<DISPLAY#>]
       ./vncviewer -help

<OPTIONS> are standard Xt options, or:
        -via <GATEWAY>
        -shared (set by default)
        -noshared
        -viewonly
        -fullscreen
        -noraiseonbeep
        -passwd <PASSWD-FILENAME> (standard VNC authentication)
        -user <USERNAME> (Unix login authentication)
        -encodings <ENCODING-LIST> (e.g. "tight copyrect")
        -bgr233
        -owncmap
        -truecolour
        -depth <DEPTH>
        -compresslevel <COMPRESS-VALUE> (0..9: 0-fast, 9-best)
        -quality <JPEG-QUALITY-VALUE> (0..9: 0-low, 9-high)
        -nojpeg
        -nocursorshape
        -x11cursor
        -autopass

Option names may be abbreviated, e.g. -bgr instead of -bgr233.
See the manual page for more information.


Enhanced TightVNC viewer (SSVNC) options:

   URL http://www.karlrunge.com/x11vnc/ssvnc.html

   Note: ZRLE and ZYWRLE encodings are now supported.

   Note: F9 is shortcut to Toggle FullScreen mode.

        -use64      In -bgr233 mode, use 64 colors instead of 256.
        -bgr222     Same as -use64.

        -use8       In -bgr233 mode, use 8 colors instead of 256.
        -bgr111     Same as -use8.

        -16bpp      If the vnc viewer X display is depth 24 at 32bpp
                    request a 16bpp format from the VNC server to cut
                    network traffic by up to 2X, then tranlate the
                    pixels to 32bpp locally.
        -bgr565     Same as -16bpp.

        -grey       Use a grey scale for the 16- and 8-bpp modes.

        -alpha      Use alphablending transparency for local cursors
                    requires: x11vnc server, both client and server
                    must be 32bpp and same endianness.

        -ycrop n    Only show the top n rows of the framebuffer.  For
                    use with x11vnc -ncache client caching option
                    to help "hide" the pixel cache region.
                    Use a negative value (e.g. -1) for autodetection.
                    Autodetection will always take place if the remote
                    fb height is more than 2 times the width.

        -sbwidth n  Scrollbar width for x11vnc -ncache mode (-ycrop),
                    default is very narrow: 2 pixels, it is narrow to
                    avoid distraction in -ycrop mode.

        -nobell     Disable bell.

        -rawlocal   Prefer raw encoding for localhost, default is
                    no, i.e. assumes you have a SSH tunnel instead.

        -graball    Grab the entire X server when in fullscreen mode,
                    needed by some old window managers like fvwm2.
        -popupfix   Warp the popup back to the pointer position,
                    needed by some old window managers like fvwm2.

        -grabkbd    Grab the X keyboard when in fullscreen mode,
                    needed by some window managers. Same as -grabkeyboard.
                    -grabkbd is the default, use -nograbkbd to disable.

        -bs, -nobs  Whether or not to use X server Backingstore for the
                    main viewer window.  The default is to not, mainly
                    because most Linux, etc, systems X servers disable
                    *all* Backingstore by default.  To re-enable it put

                        Option "Backingstore"

                    in the Device section of /etc/X11/xorg.conf.
                    In -bs mode with no X server backingstore, whenever an
                    area of the screen is re-exposed it must go out to the
                    VNC server to retrieve the pixels. This is too slow.

                    In -nobs mode, memory is allocated by the viewer to
                    provide its own backing of the main viewer window. This
                    actually makes some activities faster (changes in large
                    regions) but can appear to "flash" too much.

        -noshm      Disable use of MIT shared memory extension (not recommended)

        -termchat   Do the UltraVNC chat in the terminal vncviewer is in
                    instead of in an independent window.

        -unixpw str Useful for logging into x11vnc in -unixpw mode. "str" is a
                    string that allows many ways to enter the Unix Username
                    and Unix Password.  These characters: username, newline,
                    password, newline are sent to the VNC server after any VNC
                    authentication has taken place.  Under x11vnc they are
                    used for the -unixpw login.  Other VNC servers could do
                    something similar.

                    You can also indicate "str" via the environment
                    variable SSVNC_UNIXPW.

                    Note that the Escape key is actually sent first to tell
                    x11vnc to not echo the Unix Username back to the VNC
                    viewer. Set SSVNC_UNIXPW_NOESC=1 to override this.

                    If str is ".", then you are prompted at the command line
                    for the username and password in the normal way.  If str is
                    "-" the stdin is read via getpass(3) for username@password.
                    Otherwise if str is a file, it is opened and the first line
                    read is taken as the Unix username and the 2nd as the
                    password. If str prefixed by "rm:" the file is removed
                    after reading. Otherwise, if str has a "@" character,
                    it is taken as username@password. Otherwise, the program
                    exits with an error. Got all that?

     -repeater str  This is for use with UltraVNC repeater proxy described
                    here: http://www.uvnc.com/addons/repeater.html.  The "str"
                    is the ID string to be sent to the repeater.  E.g. ID:1234
                    In this case host:dpy on the command line is the repeater
                    server, not the VNC server.  The repeater will connect you.

   New Popup actions:

        ViewOnly:                ~ -viewonly
        Disable Bell:            ~ -nobell
        Cursor Shape:            ~ -nocursorshape
        X11 Cursor:              ~ -x11cursor
        Cursor Alphablend:       ~ -alpha
        Toggle Tight/ZRLE:       ~ -encodings ...
        Toggle ZRLE/ZYWRLE:      ~ -encodings zywrle...
        Quality Level            ~ -quality (both Tight and ZYWRLE)
        Compress Level           ~ -compresslevel
        Disable JPEG:            ~ -nojpeg  (Tight)
        Full Color                 as many colors as local screen allows.
        Grey scale (16 & 8-bpp)  ~ -grey, for low colors 16/8bpp modes only.
        16 bit color (BGR565)    ~ -16bpp / -bgr565
        8  bit color (BGR233)    ~ -bgr233
        256 colors               ~ -bgr233 default # of colors.
         64 colors               ~ -bgr222 / -use64
          8 colors               ~ -bgr111 / -use8
        Set Y Crop (y-max)       ~ -ycrop
        Set Scrollbar Width      ~ -sbwidth

        UltraVNC Extensions:

          Set 1/n Server Scale     Ultravnc ext. Scale desktop by 1/n.
          Text Chat                Ultravnc ext. Do Text Chat.
          File Transfer            Ultravnc ext. File xfer via Java helper.
          Single Window            Ultravnc ext. Grab and view a single window.
                                   (select then click on the window you want).
          Disable Remote Input     Ultravnc ext. Try to prevent input and
                                   viewing of monitor at physical display.

        Note: the Ultravnc extensions only apply to servers that support
              them.  x11vnc/libvncserver supports some of them.
Nearly all of these can be changed dynamically in the Popup menu (press F8 for it):

 


Windows:

For Windows, SSL Viewer support is provided by a GUI Windows/ssvnc.exe that prompts for the VNC display and then starts up STUNNEL followed by the Stock TightVNC Windows Viewer. Both are bundled in the package for your convenience. The GUI has other useful features. When the connection is finished, you will be asked if you want to terminate the STUNNEL program. For SSH connections from Windows the GUI will use PLINK instead of STUNNEL.

Unix and Mac OS X:

Run the GUI (ssvnc, see above) and let me know how it goes.



Hopefully this tool will make it convenient for people to help test and use the built-in SSL support in x11vnc. Extra testing of this feature is much appreciated!! Thanks.

Please Help Test the newly added features:

These allow you to print from the remote (VNC Server) machine to local printers, listen to sounds (with some limitations) from the remote VNC Server machine, and to mount your local Windows or Samba shares on the remote VNC Server machine. Basically these new features try to automate the tricks described here:
    http://www.karlrunge.com/x11vnc/#faq-smb-shares
    http://www.karlrunge.com/x11vnc/#faq-cups
    http://www.karlrunge.com/x11vnc/#faq-sound



Downloading: This project can be downloaded here, choose the archive file bundle that best suits you (e.g. no source code, windows only, unix only, zip, tar etc):

  ssvnc_windows_only-1.0.20.zip      Windows Binaries Only.  No source included (~6MB)
  ssvnc_no_windows-1.0.20.tar.gz     Unix and Mac OS X Only. No Windows binaries.  Source included. (~6MB)
  ssvnc_unix_only-1.0.20.tar.gz      Unix Binaries Only.     No source included. (~3.5MB)
  ssvnc_unix_minimal-1.0.20.tar.gz   Unix Minimal.  You must supply your own vncviewer and stunnel. (~0.1MB)

  ssvnc-1.0.20.tar.gz                All Unix, Mac OS X, and Windows binaries and source TGZ. (~11MB)
  ssvnc-1.0.20.zip                   All Unix, Mac OS X, and Windows binaries and source ZIP. (~11MB)
  ssvnc_all-1.0.20.zip               All Unix, Mac OS X, and Windows binaries and source AND full archives in the zip dir. (~15MB)
You can try for an older one by replacing, e.g. ".20" by ".15", etc.

Here are the corresponding development bundles:

Coming soon...

Please help test the UltraVNC File Transfer support in the native Unix VNC viewer! Let us know how it went.

A self-extracting and running file for the "ssvnc_unix_minimal" package is here: ssvnc. Save it as filename "ssvnc", type "chmod 755 ./ssvnc", and then launch the GUI via typing "./ssvnc". Note that this "ssvnc_unix_minimal" mode requires you install the "stunnel" and "vncviewer" programs externally (for example, install your distros' versions, e.g. on debian: "apt-get install stunnel4 xtightvncviewer".)

Current Unix binaries in the archives:

    FreeBSD.i386
    Linux.i686
    Linux.x86_64
    Linux.ppc64
    Linux.alpha
    SunOS.sun4u
    SunOS.i86pc
    Darwin.Power.Macintosh
    Darwin.i386
    HP-UX.9000
    NetBSD.i386
    OpenBSD.i386
(some of these are out of date because I no longer have access to machines running those OS's).

Note: some of the above binaries depend on libssl.so.0.9.7, whereas some recent distros only provide libssl.so.0.9.8 by default (for compatibility reasons they should install both by default but not all do). So you may need to instruct your distro to install the 0.9.7 library (it is fine to have both runtimes installed simultaneously since the libraries have different names). Update: I now try to statically link libssl.a for all of the binaries in the archive.

You can also run the included build.unix script to try to automatically build the binaries if your OS is not in the above list or the included binary does not run properly on your system. Let me know how that goes.



IMPORTANT: there may be restrictions for you to download, use, or redistribute the above because of cryptographic software they contain or for other reasons. Please check out your situation and information at the following and related sites:
	http://www.stunnel.org
	http://stunnel.mirt.net
	http://www.openssl.org
	http://www.chiark.greenend.org.uk/~sgtatham/putty/
        http://www.tightvnc.com
	http://www.realvnc.com
	http://sourceforge.net/projects/cotvnc/


Here is the toplevel README from the bundle:
       Enhanced TightVNC Viewer (SSVNC: SSL/SSH VNC viewer)

Copyright (c) 2006-2008 Karl J. Runge 
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.

        - Unix Username and Password entry for use with "x11vnc -unixpw"
	  type login dialogs.

	- Simplified mode launched by command "sshvnc" that is SSH Only.

	- Simplified mode launched by command "tsvnc" that provides a VNC
	  "Terminal Services" mode (uses x11vnc on the remote side).


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

	- rfbNewFBSize VNC support (screen resizing)

	- ZRLE VNC encoding support (RealVNC's encoding)

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

	- Option "-unixpw ..." for use with "x11vnc -unixpw" login dialogs.

	- 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

	- UltraVNC File Transfer via an auxiliary Java helper program
	  (java must be in $PATH). Note that x11vnc supports UltraVNC
	  file transfer.

	- 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)

	- 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.

	- 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.

	- Maintains its own BackingStore if the X server does not

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

	- Support for the ZYWRLE encoding, a wavelet based extension to
	  ZRLE to improve compression of motion video and photo regions.

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

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

	- 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.20.tar.gz | tar xvf -

    Run the GUI:

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

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

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

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

    On MacOSX if you don't like the Chicken of the VNC (e.g. no local
    cursors, no screen size rescaling, and no password prompting), and you
    have the XDarwin X server installed, you can set DISPLAY before starting
    ssvnc (or type DISPLAY=... in Host:Disp and hit Return).  Then our
    enhanced TightVNC viewer will be used instead of COTVNC.
    Update: there is now a 'Use X11 vncviewer on MacOSX' under Options ...


    If you want a SSH-only tool (without the distractions of SSL) run
    the command:

                sshvnc

    instead of "ssvnc".  Or click "SSH-Only Mode" under Options.
    Control-h will toggle between the two modes.

		
    If you want a simple VNC Terminal Services only mode (requires x11vnc
    on the remote server) run the command:

                tsvnc

    instead of "ssvnc".  Or click "Terminal Services" under Options.
    Control-t will toggle between the two modes.

    "tsvnc profile-name" and "tsvnc user@hostname" work too.


Unix/MacOSX Install:

    There is no standard install, but you can make symlinks like so:

	cd /a/directory/in/PATH
	ln -s /path/to/ssvnc/bin/{s,t}* .

    Or put /path/to/ssvnc/bin, /path/to/ssvnc/Unix, or /path/to/ssvnc/MacOSX
    in your PATH.


Windows:

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

        ssvnc-1.0.20.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.20.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.


    If you want a SSH-only tool (without the distractions of SSL) run
    the command:

                sshvnc.bat

    Or click "SSH-Only Mode" under Options.


    If you want a simple VNC Terminal Services only mode (requires x11vnc
    on the remote server) run the command:

                tsvnc.bat

    Or click "Terminal Services" under Options.  Control-t will toggle
    between the two modes.  "tsvnc profile-name" and "tsvnc user@hostname"
    work too.



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


SSH-ONLY Mode:
--------------

If you don't care for SSL and the distractions it provides in the GUI,
run "sshvnc" (unix/macosx) or "sshvnc.bat" (windows) to run an SSH only
version of the GUI.

Terminal Services Mode
----------------------

There is an even simpler mode that uses x11vnc on the remote side for the
session finding and management.  Run "tsvnc" (unix/macosx) or "tsvnc.bat"
(windows) to run the Terminal Services version of the GUI.


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).

One user on Windows created a BAT file to launch SSVNC and needed to
do this to get the Home directory correct:

cd \ssvnc\Windows
start \ssvnc\Windows\ssvnc.exe

(an optional profile name can be supplied to the ssvnc.exe line)

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).
There are also:

	./bin/sshvnc	(SSH-Only)
	./bin/tsvnc	(Terminal Services Mode)

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 or MacOS X.

Also links to the GUI launcher script are provided in:

	MacOSX/ssvnc
	Unix/ssvnc

and sshvnc and tsvnc.  You could also put the Unix or MacOSX directory
in your PATH.


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/