README 26 KB
Newer Older
1
       Enhanced TightVNC Viewer (SSVNC: SSL/SSH VNC viewer)
2

3
Copyright (c) 2006-2009 Karl J. Runge <runge@karlrunge.com>
4 5
All rights reserved.

runge's avatar
runge committed
6 7 8
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.
9 10

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

runge's avatar
runge committed
14 15
Bundled software co-shipped is copyright and licensed by others.
See these sites and related ones for more information:
16 17 18 19

        http://www.tightvnc.com
        http://www.realvnc.com
        http://www.stunnel.org
runge's avatar
runge committed
20
        http://stunnel.mirt.net
21 22
        http://www.openssl.org
        http://www.chiark.greenend.org.uk/~sgtatham/putty/
23
	http://sourceforge.net/projects/cotvnc/
24

runge's avatar
runge committed
25 26 27 28 29 30 31
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
32
Copyright (c) 2006-2008 Karl J. Runge and is licensed under the GPL as
runge's avatar
runge committed
33
described in the file COPYING in this directory.
34

runge's avatar
runge committed
35
All the files and information in this project are provided "AS IS"
36 37 38 39 40
without any warranty of any kind.  Use them at your own risk.


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

runge's avatar
runge committed
41 42 43 44
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.
45

runge's avatar
runge committed
46 47
A Windows SSL wrapper for the bundled TightVNC binary and other utilities
are provided.  (Launch ssvnc.exe in the Windows subdirectory).
48

runge's avatar
runge committed
49 50 51
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,
runge's avatar
runge committed
52
a USB memory stick for secure VNC viewing from almost any machine,
runge's avatar
runge committed
53
Unix, Mac, or Windows.
54 55 56 57 58 59

Features:
--------

The enhanced TightVNC viewer features are:

runge's avatar
runge committed
60
	- SSL support for connections using the bundled stunnel program.
61 62

	- Automatic SSH connections from the GUI (ssh must already be
runge's avatar
runge committed
63
	  installed on Unix; bundled plink is used on Windows)
64

runge's avatar
runge committed
65 66
	- Ability to Save and Load VNC profiles for different hosts.

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

runge's avatar
runge committed
70 71
	- Create or Import SSL Certificates and Private Keys.

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

74 75 76 77 78 79 80 81 82 83
	- 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.)

84 85 86 87 88 89
	- 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.

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

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

95 96 97 98
	- 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.

99 100 101 102 103
        - 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.

runge's avatar
runge committed
104
	- Support for native MacOS X usage with bundled Chicken of the
105 106
	  VNC viewer (the Unix X11 viewer is also provided for MacOS X,
	  and is better IMHO).
runge's avatar
runge committed
107

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

112 113 114 115 116 117 118 119
        - 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).

120

121 122
	(the following features only apply to the bundled Unix tightvnc viewer
        including MacOS X)
runge's avatar
runge committed
123

runge's avatar
runge committed
124
	- rfbNewFBSize VNC support (screen resizing)
runge's avatar
runge committed
125

126 127
	- Client-side Scaling of the Viewer.

runge's avatar
runge committed
128 129
	- ZRLE VNC encoding support (RealVNC's encoding)

runge's avatar
runge committed
130 131 132
	- Support for the ZYWRLE encoding, a wavelet based extension to
	  ZRLE to improve compression of motion video and photo regions.

133 134 135 136 137 138 139
	- 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.)

140 141 142 143 144 145 146 147 148
	- 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

149
	- UltraVNC File Transfer via an auxiliary Java helper program
runge's avatar
runge committed
150 151
	  (java must be in $PATH). Note that the x11vnc server supports
	  UltraVNC file transfer.
152

153 154 155 156 157 158
	- Connection support for the UltraVNC repeater proxy (-repeater
	  option).

	- Support for UltraVNC Single Click operation. (both unencrypted:
	  SC I, and SSL encrypted: SC III)

159
        - Support for UltraVNC DSM Encryption Plugin mode. (ARC4 and
160
          AESV2, MSRC4, and SecureVNC)
161

162 163 164 165 166
        - 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.)
167

runge's avatar
runge committed
168 169 170 171 172 173 174 175 176 177 178 179 180
        - 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.
181

182 183 184 185 186
	- 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)

runge's avatar
runge committed
187 188 189 190 191 192 193 194 195 196 197
	- 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).

runge's avatar
runge committed
198 199 200 201 202
        - 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.

runge's avatar
runge committed
203 204 205
	- Scrollbar width setting: -sbwidth n, the default is very thin,
	  2 pixels, for less distracting -ycrop usage.

206 207 208 209 210 211
	- 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.)

212 213 214 215
	- 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
runge's avatar
runge committed
216
	  for low color modes, Scaling the Viewer resolution, Escape Keys,
217
	  Pipeline Updates, and others, including UltraVNC extensions.
218 219 220

	- Maintains its own BackingStore if the X server does not

runge's avatar
runge committed
221 222 223 224 225 226 227 228 229 230 231
	- 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.
runge's avatar
runge committed
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257



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:

258
        % gzip -dc ssvnc-1.0.25.tar.gz | tar xvf -
runge's avatar
runge committed
259 260 261 262 263 264 265

    Run the GUI:

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

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

266
    The smaller file "ssvnc_no_windows-1.0.25.tar.gz"
runge's avatar
runge committed
267 268
    could have been used as well.

269
    On MacOSX you could also click on the SSVNC app icon in the Finder.
runge's avatar
runge committed
270

271 272 273 274 275
    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.
276
    Update: there is now a 'Use X11 vncviewer on MacOSX' under Options ...
277

278

279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300
    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:

runge's avatar
runge committed
301 302
    There is no standard install for the bundles, but you can make
    symlinks like so:
303 304 305 306 307 308 309

	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.

runge's avatar
runge committed
310 311
    For the conventional source tarball it will compile and install, e.g.:

312 313
       gzip -dc ssvnc-1.0.25.src.tar.gz | tar xvf -
       cd ssvnc-1.0.25
runge's avatar
runge committed
314 315 316 317 318 319
       make config
       make all
       make PREFIX=/my/install/dir install

    then have /my/install/dir/bin in your PATH.

320

runge's avatar
runge committed
321 322 323
Windows:

    Unzip, using WinZip or a similar utility, the zip file:
runge's avatar
runge committed
324

325
        ssvnc-1.0.25.zip
runge's avatar
runge committed
326

runge's avatar
runge committed
327
    Run the GUI, e.g.:
328

runge's avatar
runge committed
329 330 331 332 333 334 335 336
	Start -> Run -> Browse

    and then navigate to

        .../ssvnc/Windows/ssvnc.exe

    select Open, and then OK to launch it.

337
    The smaller file "ssvnc_windows_only-1.0.25.zip"
runge's avatar
runge committed
338 339 340 341 342
    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.
runge's avatar
runge committed
343

344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362

    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.


runge's avatar
runge committed
363

runge's avatar
runge committed
364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380
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


381 382 383 384 385 386 387 388 389 390 391 392 393 394 395
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.


runge's avatar
runge committed
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411
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
412 413 414

	./bin

runge's avatar
runge committed
415
for the ones that were shipped in this project, e.g. ./bin/Linux.i686
416 417 418
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).
419 420


421 422 423 424 425 426 427 428 429 430 431 432
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).

433 434 435 436 437 438 439 440
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)

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


runge's avatar
runge committed
445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473
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. 
	
474 475
See the README.src for a more detailed description of dependencies.

runge's avatar
runge committed
476

477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
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.


501 502 503
If you need to Build:
--------------------

runge's avatar
runge committed
504 505
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
506
successfully build on for you and deposit the binaries down in ./bin/...
507
using the included source code.  It is a hack but usually works.
508

runge's avatar
runge committed
509 510
You MUST run the build.unix script from this directory (that this toplevel
README is in, i.e "ssvnc") and like this:
511 512 513

	./build.unix

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

517 518 519 520 521 522 523 524 525 526 527 528 529
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

runge's avatar
runge committed
530 531
Feel free to ask us if you need help running ./build.unix

532

533 534 535
Convential Build:

A more conventional source tarball is provided in ssvnc-x.y.z.src.tar.gz.
536
It uses a more or less familiar 'make config; make all; make PREFIX=path install'
537 538 539 540
method.  It does not include stunnel, so that must be installed on the
system separately.


541 542 543
The programs:
------------

runge's avatar
runge committed
544
Unpack your archive, and you will see "bin", "Windows", "src" directories
runge's avatar
runge committed
545
and other files.  The command line wrapper scripts: 
546

runge's avatar
runge committed
547
	./bin/ssvnc_cmd
548 549
	./bin/tightvncviewer

runge's avatar
runge committed
550
are the main programs that are run and will try to autodetect your OS+arch
551 552 553
combination and if binaries are present for it automatically use them.
(if not found try the running the build.unix script).

runge's avatar
runge committed
554
If you prefer a GUI to prompt for parameters and then start ssvnc_cmd
555 556
you can run this instead:

runge's avatar
runge committed
557
	./bin/ssvnc       
558

runge's avatar
runge committed
559
this is the same GUI that is run on Windows (the ssvnc.exe).
560 561 562 563
There are also:

	./bin/sshvnc	(SSH-Only)
	./bin/tsvnc	(Terminal Services Mode)
564 565 566 567 568 569 570

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
runge's avatar
runge committed
571
	ln -s /path/to/ssvnc/bin/{s,t}* .
572 573

(note the "." at the end). The above commands is basically the way to
574
"install" this on Unix or MacOS X.
575

576
Also links to the GUI launcher script are provided in:
577

runge's avatar
runge committed
578 579
	MacOSX/ssvnc
	Unix/ssvnc
580

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


runge's avatar
runge committed
585
On Windows unpack your archive and run:
586

runge's avatar
runge committed
587
	Windows/ssvnc.exe
588 589 590 591 592


Examples:
--------

runge's avatar
runge committed
593 594 595
The following assume you are in the toplevel directory of the
archive you unpacked.

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

runge's avatar
runge committed
598
	./bin/ssvnc_cmd   far-away.east:0
599 600 601

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

runge's avatar
runge committed
602
	./bin/ssvnc                                  (start GUI launcher)
603 604 605 606 607 608 609 610

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:

runge's avatar
runge committed
611
	./bin/ssvnc_cmd -alpha -verify ./x11vnc.pem far-away.east:0
612 613 614 615 616 617 618

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


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

runge's avatar
runge committed
619 620
	./bin/util		some utility scripts, e.g. ss_vncviewer
				and ssvnc.tcl
621 622 623 624 625 626 627 628 629 630 631 632 633 634 635

	./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
runge's avatar
runge committed
636 637 638 639 640 641 642
				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.
643

runge's avatar
runge committed
644 645 646 647 648 649 650 651 652 653
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
654 655


656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735
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.


736 737 738 739 740
Help and Info:
-------------

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

runge's avatar
runge committed
741 742
	./bin/ssvnc_cmd -h
	./bin/util/ss_vncviewer -h
743 744 745 746

See also:

	http://www.karlrunge.com/x11vnc
747
	http://www.karlrunge.com/x11vnc/faq.html
748 749 750
	x11vnc -h | more

	http://www.stunnel.org
runge's avatar
runge committed
751
	http://stunnel.mirt.net
752 753 754 755
	http://www.openssl.org
	http://www.tightvnc.com
        http://www.realvnc.com
        http://www.chiark.greenend.org.uk/~sgtatham/putty/
756
	http://sourceforge.net/projects/cotvnc/