Enhanced TightVNC Viewer (SSVNC: SSL/SSH VNC viewer) Copyright (c) 2006-2009 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-2008 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. - You can also use your own VNC Viewer, e.g. UltraVNC or RealVNC, with the front-end GUI or scripts if you like. - Create or Import SSL Certificates and Private Keys. - Reverse (viewer listening) VNC connections via SSL and SSH. - VeNCrypt SSL/TLS VNC encryption support (used by VeNCrypt, QEMU, ggi, libvirt/virt-manager/xen, vinagre/gvncviewer/gtk-vnc) - ANONTLS SSL/TLS VNC encryption support (used by Vino) - VeNCrypt and ANONTLS are also enabled for any 3rd party VNC Viewer (e.g. RealVNC, TightVNC, UltraVNC ...) on Unix, MacOSX, and Windows via the provided SSVNC VeNCrypt Viewer Bridge tool (use 'Change VNC Viewer' to select the one you want.) - Support for Web Proxies, SOCKS Proxies, and the UltraVNC repeater proxy (e.g. repeater://host:port+ID:1234). Multiple proxies may be chained together (3 max). - Support for SSH Gateway connections and non-standard SSH ports. - Automatic Service tunnelling via SSH for CUPS and SMB Printing, ESD/ARTSD Audio, and SMB (Windows/Samba) filesystem mounting. - Sets up any additional SSH port redirections that you want. - Zeroconf (aka Bonjour) is used on Unix and Mac OS X to find VNC servers on your local network if the avahi-browse or dns-sd program is available and in your PATH. - 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. - Support for native MacOS X usage with bundled Chicken of the VNC viewer (the Unix X11 viewer is also provided for MacOS X, and is better IMHO). - 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 including MacOS X) - rfbNewFBSize VNC support (screen resizing) - Client-side Scaling of the Viewer. - ZRLE VNC encoding support (RealVNC's encoding) - Support for the ZYWRLE encoding, a wavelet based extension to ZRLE to improve compression of motion video and photo regions. - TurboVNC support (VirtualGL's modified TightVNC encoding; requires TurboJPEG library) - Pipelined Updates of the framebuffer as in TurboVNC (asks for the next update before the current one has finished downloading; this gives some speedup on high latency connections.) - 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 the x11vnc server supports UltraVNC file transfer. - Connection support for the UltraVNC repeater proxy (-repeater option). - Support for UltraVNC Single Click operation. (both unencrypted: SC I, and SSL encrypted: SC III) - Support for UltraVNC DSM Encryption Plugin mode. (ARC4 and AESV2, MSRC4, and SecureVNC) - Support for UltraVNC MS-Logon authentication (NOTE: the UltraVNC MS-Logon key exchange implementation is very weak; an eavesdropper on the network can recover your Windows password easily in a few seconds; you need to use an additional encrypted tunnel with MS-Logon.) - Support for symmetric encryption (including blowfish and 3des ciphers) to Non-UltraVNC Servers. Any server using the same encryption method will work, e.g.: x11vnc -enc blowfish:./my.key - Instead of hostname:display one can also supply "exec=command args..." to connect the viewer to the stdio of an external command (e.g. stunnel or socat) rather than using a TCP/IP socket. Unix domain sockets, e.g. /path/to/unix/socket, and a previously opened file descriptor fd=0, work too. - Local Port Protections for STUNNEL and SSH: avoid having for long periods of time a listening port on the the local (VNC viewer) side that redirects to the remote side. - Reverse (viewer listening) VNC connections can show a Popup dialog asking whether to accept the connection or not (-acceptpopup.) The extra info provided by UltraVNC Single Click reverse connections is also supported (-acceptpopupsc) - 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). - Escape Keys: enable a set of modifier keys so when they are all pressed down you can invoke Popup menu actions via keystrokes. I.e., a set of 'Hot Keys'. One can also pan (move) the desktop inside the viewport via Arrow keys or a mouse drag. - Scrollbar width setting: -sbwidth n, the default is very thin, 2 pixels, for less distracting -ycrop usage. - Selection text sending and receiving can be fine-tuned with the -sendclipboard, -sendalways, and -recvtext options. - TightVNC compression and quality levels are automatically set based on observed network latency (n.b. not bandwidth.) - 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, Scaling the Viewer resolution, Escape Keys, Pipeline Updates, and others, including UltraVNC extensions. - 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. - 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.25.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.25.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 for the bundles, 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. For the conventional source tarball it will compile and install, e.g.: gzip -dc ssvnc-1.0.25.src.tar.gz | tar xvf - cd ssvnc-1.0.25 make config make all make PREFIX=/my/install/dir install then have /my/install/dir/bin in your PATH. Windows: Unzip, using WinZip or a similar utility, the zip file: ssvnc-1.0.25.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.25.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. See the README.src for a more detailed description of dependencies. TurboVNC Support: ---------------- TurboVNC is supported in an experimental way. To it build via the build.unix script described in the next section, do something like: env TURBOVNC='-L/DIR -Xlinker --rpath=/DIR -lturbojpeg' ./build.unix where you replace /DIR with the directory where the libturbojpeg.so (http://sourceforge.net/project/showfiles.php?group_id=117509&package_id=166100) is installed. You may not need to set rpath if libturbojpeg.so is installed in a standard location or you use LD_LIBRARY_PATH to point to it. See the turbovnc/README in the vnc_unixsrc/vncviewer directory for more info. You can find it in the ssvnc source tarball and also in: src/zips/vnc_unixsrc_vncviewer.patched.tar More TurboVNC features will be enabled in the future. 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. It is a hack but usually works. 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. You can set these env. vars to customize the build: SSVNC_BUILD_NO_STATIC=1 do not try to statically link libs SSVNC_BUILD_FORCE_OVERWRITE=1 do not prompt about existing binaries SSVNC_BUILD_SKIP_VIEWER=1 do not build vncviewer SSVNC_BUILD_SKIP_STUNNEL=1 do not build stunnel SSVNC_BUILD_ULTRAFTP=1 only build the file xfer helper jar here is an example to build only the vncviewer and with normal library linking (and in a more or less automated way): env SSVNC_BUILD_NO_STATIC=1 SSVNC_BUILD_FORCE_OVERWRITE=1 SSVNC_BUILD_SKIP_STUNNEL=1 ./build.unix Feel free to ask us if you need help running ./build.unix Convential Build: A more conventional source tarball is provided in ssvnc-x.y.z.src.tar.gz. It uses a more or less familiar 'make config; make all; make PREFIX=path install' method. It does not include stunnel, so that must be installed on the system separately. 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 Untrusted Local Users: --------------------- *IMPORTANT WARNING*: If you run SSVNC on a workstation or computer that other users can log into and you DO NOT TRUST these users (it is a shame but sometimes one has to work in an environment like this), then please note the following warning. By 'do not trust' we mean they might try to gain access to remote machines you connect to via SSVNC. Note that an untrusted local user can often obtain root access in a short amount of time; if a user has acheived that, then all bets are off for ANYTHING that you do on the workstation. It is best to get rid of Untrusted Local Users as soon as possible. Both the SSL and SSH tunnels set up by SSVNC listen on certain ports on the 'localhost' address and redirect TCP connections to the remote machine; usually the VNC server running there (but it could also be another service, e.g. CUPS printing). These are the stunnel(8) SSL redirection and the ssh(1) '-L' port redirection. Because 'localhost' is used only users or programs on the same workstation that is running SSVNC can connect to these ports, however this includes any local users (not just the user running SSVNC.) If the untrusted local user tries to connect to these ports, he may succeed in varying degrees to gain access to the remote machine. We now list some safeguards one can put in place to try to make this more difficult to acheive. It probably pays to have the VNC server require a password, even though there has already been SSL or SSH authentication (via certificates or passwords). In general if the VNC Server requires SSL authentication of the viewer that helps, unless the untrusted local user has gained access to your SSVNC certificate keys. If the VNC server is configured to only allow one viewer connection at a time, then the window of opportunity that the untrusted local user can use is greatly reduced: he might only have a second or two between the tunnel being set up and the SSVNC vncviewer connecting to it (i.e. if the VNC server only allows a single connection, the untrusted local user cannot connect once your session is established). Similarly, when you disconnect the tunnel is torn down quickly and there is little or no window of opportunity to connect (e.g. x11vnc in its default mode exits after the first client disconnects). Also for SSL tunnelling with stunnel(8) on Unix using one of the SSVNC prebuilt 'bundles', a patched stunnel is provided that denies all connections after the first one, and exits when the first one closes. This is not true if the system installed stunnel(8) is used and is not true when using SSVNC on Windows. The following are two experimental features that are added to SSVNC to improve the situation for the SSL/stunnel case. Set them via Options -> Advanced -> "STUNNEL Local Port Protections". 1) For SSL tunnelling with stunnel(8) on Unix there is a setting 'Use stunnel EXEC mode' (experimental) that will try to exec(2) stunnel instead of using a listening socket. This will require using the specially modified vncviewer unix viewer provided by SSVNC. If this mode proves stable it will become the default. 2) For SSL tunnelling with stunnel(8) on Unix there is a setting 'Use stunnel IDENT check' (experimental) to limit socket connections to be from you (this assumes the untrusted local user has not become root on your workstation and has modified your local IDENT check service; if he has you have much bigger problems to worry about...) There is also one simple LD_PRELOAD trick for SSH to limit the number of accepted port redirection connections. This makes the window of time the untrusted local user can connect to the tunnel much smaller. Enable it via Options -> Advanced -> "SSH Local Port Protections". You will need to have the lim_accept.so file in your SSVNC package. The main message is to 'Watch your Back' when you connect via the SSVNC tunnels and there are users you don't trust on your workstation. The same applies to ANY use of SSH '-L' port redirections or outgoing stunnel SSL redirection services. 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.html 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/