* Using TurboVNC
{anchor: TurboVNC_Usage}

** Starting and Connecting to a TurboVNC Session

*** Procedure
#OPT: noList! plain!

	#. __Mac clients:__ Start the Mac X11 application.

	#. Open a new Command Prompt/terminal window on your client machine.
		(__Mac clients:__ in the X11 application, start a new xterm [Command-N] if
		one isn't already started.)

	#. In the new Command Prompt/terminal/xterm window, open a Secure Shell (SSH)
		session into the TurboVNC server machine:

		Linux/Unix/Mac clients :: {:}
		#Verb: <<---
		ssh {user}@{server}
		---

		Windows clients :: {:}
		#Verb: <<---
		"c:\program files\turbovnc\putty" {user}@{server}
		---

		Replace __''{user}''__ with your user account name on the TurboVNC server
		machine and __''{server}''__ with the hostname or IP address of that
		machine.

	#. In the SSH session, start a TurboVNC session:

		#Verb: <<---
		/opt/TurboVNC/bin/vncserver
		---

	#. Make a note of the X display number that the TurboVNC session is
		occupying, for instance:
		{nl}{nl}
		''New 'X' desktop is my_server:1''
		{nl}{nl}
		If this is the first time that a TurboVNC session has ever been run
		under this user account, and if VNC password authentication is enabled for
		the session, then TurboVNC will prompt for a VNC password.

	#. The SSH session can now be exited, if desired.

	#. On the client machine, start the TurboVNC Viewer.

		Linux/Unix/Mac clients :: {:}
		Open a new terminal/xterm and type
		#Verb: <<---
		/opt/TurboVNC/bin/vncviewer
		---

		Windows clients :: {:}
		Select __TurboVNC Viewer__ in the __TurboVNC__ Start Menu group.

	#. A small dialog box will appear.
		{nl}{nl}
		|| Windows TurboVNC Viewer || Linux/Unix/Mac TurboVNC Viewer ||
		| {img:turbovnc1.png} | {img:turbovnc2.png} |
		{nl}
		Enter the X display name (hostname/IP address and display number) of the
		TurboVNC session in the "VNC server" field, then click "Connect" (Windows)
		or press Enter (Linux/Unix/Mac.)

	#. Another dialog box appears, prompting for the password (if standard
		VNC authentication is being used) or for the username and password (if
		Unix login authentication is being used.)
		{nl}{nl}
		|| || Windows TurboVNC Viewer || Linux/Unix/Mac TurboVNC Viewer ||
		| Standard VNC Authentication Dialog | {img:turbovnc3.png} | {img:turbovnc4.png} |
		| Unix Login Authentication Dialog   | {img:turbovnc5.png} | {img:turbovnc6.png} |
		{nl}
		Enter the VNC session password or the Unix username/password and click
		"OK" (Windows) or press Enter (Linux/Unix/Mac.)
		{nl}{nl}
		A TurboVNC desktop window should appear on your client machine.  This
		window contains a virtual desktop with which you can interact to launch
		X-Windows applications on the TurboVNC server machine.

** Disconnecting and Killing a TurboVNC Session

Closing the TurboVNC Viewer disconnects from the TurboVNC session, but the
TurboVNC session will remain running on the TurboVNC server machine (as will
any applications that you may have started in the session), and you can
reconnect to the session at any time.

To kill a TurboVNC session:

	#. Using SSH (''c:\\Program Files\\TurboVNC\\putty.exe'' on Windows clients),
		log into the server that is running the TurboVNC session that you wish to
		kill.{nl} \
		... or ...{nl} \
		Using the TurboVNC Viewer, connect to the TurboVNC session that you wish to
		kill, and open a new terminal in that TurboVNC session.

	#. Type the following command:

		#Verb: <<---
		/opt/TurboVNC/bin/vncserver -kill :{n}
		---

	Replace __''{n}''__ with the X display number of the TurboVNC session you
	wish to kill.

To list the X display numbers and process ID's of all TurboVNC sessions that
are currently running under your user account on a particular machine, type the
following command:

	#Verb: <<---
	/opt/TurboVNC/bin/vncserver -list
	---

** Using TurboVNC in a Web Browser

When a TurboVNC session is created, it automatically launches a miniature web
server that serves up a Java TurboVNC Viewer applet.  This Java TurboVNC Viewer
can be used to connect to the TurboVNC session from a machine that does not
have a native TurboVNC Viewer installed (or a machine for which no native
TurboVNC Viewer is available.)  The Java viewer is significantly slower than
the native viewer on high-speed networks, but on low-speed networks the Java
viewer and native viewers have comparable performance.

To use the Java TurboVNC Viewer, point your web browser to:

''http://''__''{turbovnc_server}''__'':{5800+''__''n''__''}''

where __''{turbovnc_server}''__ is the hostname or IP address of the TurboVNC
server machine, and __''n''__ is the X display number of the TurboVNC session
to which you want to connect.

__Example:__
If the TurboVNC session is occupying X display ''my_server:1'', then point your
web browser to:

''http://my_server:5801''

** Optimizing TurboVNC's Performance for Different Network Types

The level of image compression in TurboVNC can be adjusted to balance the
(sometimes conflicting) goals of high image quality and high performance.
There are four options that control the manner in which TurboVNC compresses
images:

	Allow JPEG compression :: {:}
		If this option is enabled, then TurboVNC will use JPEG compression for
		subrectangles that have a high number of unique colors and indexed color
		subencoding for subrectangles that have a low number of unique colors.  If
		this option is disabled, then TurboVNC will select between indexed color or
		raw subencoding, depending on the size of the subrectangle and its color
		count.

	JPEG image quality :: {:}
		Lower quality levels produce grainier JPEG images with more noticeable
		compression artifacts, but lower quality levels also use less network
		bandwidth and CPU time.

	JPEG chrominance subsampling :: {:}
		When compressing an image using JPEG, the RGB pixels are first converted to
		the YUV colorspace, a colorspace in which each pixel is represented as a
		brightness (Y, or "luminance") value and a pair of color (U & V, or
		"chrominance") values.  After this colorspace conversion, chrominance
		subsampling can be used to discard some of the chrominance components in
		order to save bandwidth.  1X subsampling (the default in TurboVNC) retains
		the chrominance components for all pixels, and thus it provides the best
		image quality but also uses the most network bandwidth and CPU time.  2X
		subsampling retains the chrominance components for every other pixel, and
		4X subsampling retains the chrominance components for every fourth pixel
		(this is typically implemented as 2X subsampling in both X and Y
		directions.)  Grayscale throws out all of the chrominance components,
		leaving only luminance.  2X and 4X subsampling will typically produce
		noticeable aliasing of lines and other sharp features, but with
		photographic or other "smooth" image content, it may be difficult to detect
		any difference between 1X, 2X, and 4X.

	Zlib compression level :: {:}
		If Zlib compression is enabled, then indexed color, mono, and raw-encoded
		subrectangles will be compressed with Zlib prior to transmission.  This
		decreases network bandwidth usage at the expense of increased CPU usage.
		If JPEG compression is enabled, then Zlib compression is always used with
		non-JPEG subrectangles.

In the Windows TurboVNC Viewer, these parameters can be adjusted by accessing
the Options dialog box (click on the "Options" button in the "TurboVNC
Connection" dialog box or, after connecting to the server, click on the
Connection Options button in the toolbar.)  In the Unix TurboVNC Viewer, press
F8 after connecting to bring up the options menu.  In the Java viewer, click on
the Options button at the top of the viewer window.

The TurboVNC Viewer provides five "encoding methods", corresponding
to the most useful combinations of the image compression options described
above:

|| Encoding method || Allow JPEG || JPEG image quality || \
	JPEG chrominance subsampling || Zlib compression level || Notes ||
| "Tight + Perceptually Lossless JPEG" | Yes | 95 | 1x | N/A | \
	This encoding method should be perceptually lossless (that is, any image \
	compression artifacts it produces should be imperceptible to the human \
	eye under most viewing conditions.)  This encoding method requires a great \
	deal of network bandwidth, however, and is generally not recommended except \
	on 50 Megabit/second and faster networks. |
| "Tight + Medium Quality JPEG" | Yes | 80 | 2x | N/A | \
	For subrectangles with a high number of unique colors, this encoding method \
	produces some minor, but generally not very noticeable, image compression \
	artifacts.  All else being equal, this encoding method typically uses about \
	twice the network bandwidth of the "Tight + Low Quality JPEG" encoding \
	method and about half the bandwidth of the "Tight + Perceptually Lossless \
	JPEG" encoding method, making it appropriate for medium-speed networks such \
	as 10 Megabit Ethernet. |
| "Tight + Low Quality JPEG" | Yes | 30 | 4x | N/A | \
	For subrectangles with a high number of unique colors, this encoding method \
	produces very noticeable image compression artifacts.  However, it performs \
	optimally on low-bandwidth connections.  If image quality is more critical \
	than performance, then use one of the other encoding methods or take \
	advantage of the Lossless Refresh feature. |
| "Lossless Tight" | No | N/A | N/A | 0 | \
	This encoding method uses indexed color subencoding for subrectangles with \
	a low number of unique colors but otherwise does not perform any image \
	compression at all.  It is thus suitable only for gigabit and faster \
	networks.  This encoding method uses significantly less CPU time than any \
	of the JPEG-based encoding methods. |
| "Lossless Tight + Zlib" | No | N/A | N/A | 1 | \
	This encoding method uses indexed color subencoding for subrectangles with \
	a low number of unique colors and raw subencoding for subrectangles with a \
	high number of unique colors.  It compresses all subrectangles using Zlib \
	with compression level 1.  For certain types of low-color workloads (CAD \
	applications, in particular), this encoding method may use less network \
	bandwidth than the "Tight + Perceptually Lossless JPEG" encoding method, \
	but it also uses significantly more CPU time than any of the JPEG-based \
	encoding methods. |

In the Windows TurboVNC Viewer, the encoding method can be set using
the Options dialog box (click on the "Options" button in the "TurboVNC
Connection" dialog box or, after connecting to the server, click on the
Connection Options button in the toolbar.)  In the Java viewer, the same thing
is accomplished by clicking on the "Options" button at the top of the browser
window.  With the Linux/Unix/Mac TurboVNC Viewer, the "Perceptually
Lossless" encoding method is the default, and you can use the following
command-line switches to select another encoding method:

''-medqual'' = select the "Tight + Medium Quality JPEG" encoding method {nl}
''-lowqual'' = select the "Tight + Low Quality JPEG" encoding method {nl}
''-lossless'' = select the "Lossless Tight" encoding method {nl}
''-losslesswan'' = select the "Lossless Tight + Zlib" encoding method {nl}

You can also press the F8 key after connecting to pop up a menu from which you
can select a different encoding method.

*** Lossless Refresh

Since both of TurboVNC's mathematically lossless encoding methods have
performance drawbacks, another option for image-quality-critical applications
is the "Lossless Refresh" feature.  When a lossless refresh is requested by a
TurboVNC viewer, the server will send a mathematically lossless image of the
current TurboVNC desktop to the requesting viewer.  So, for instance, a user
can rotate/pan/zoom an object in their 3D application using a very low-quality
JPEG setting, then when that user is ready to interpret or analyze the object,
they can request a lossless refresh of TurboVNC's virtual screen.

To perform a lossless refresh in the Windows or Unix TurboVNC Viewers, press
CTRL-ALT-SHIFT-L (in the Windows TurboVNC Viewer, you can also click on the
Lossless Refresh toolbar icon.)  In the Java TurboVNC Viewer, click on the
"Lossless Refresh" button at the top of the viewer window.

*** Automatic Lossless Refresh
{anchor: ALR}

Passing an argument of ''-alr ''__''{timeout}''__ to ''vncserver'' will
enable the automatic lossless refresh (ALR) feature for the TurboVNC
session.  ALR will monitor all of the VNC viewer connections, and if more than
__''{timeout}''__ seconds have elapsed since the last framebuffer update was
sent to a given viewer, then the TurboVNC Server will send to that viewer a
mathematically lossless copy of screen regions that have been affected by
lossy compression.  You can also pass arguments of ''-alrqual'' and
''-alrsamp'' to ''vncserver'' to specify that automatic lossless refreshes
should be sent using JPEG instead (see the ''Xvnc'' man page for details.)

The ALR feature is designed mainly for use by interactive visualization
applications.  The idea is that, on a low-bandwidth connection, low-quality
JPEG can be used while the user is rotating/panning/zooming a 3D scene, but
when the user stops manipulating the scene, then a fully lossless copy of the
3D image is sent for them to study in detail.

The default ALR behavior is to monitor and send lossless copies of only the
screen regions that were drawn using ''X[Shm]PutImage()''.  When used with
VirtualGL, this means that ALRs will mainly be sent for just the 3D screen
regions.  This should be fine for most 3D applications, since the 3D regions are
the ones that are quality-critical.  The default ALR behavior also prevents
what might best be termed the "blinking cursor dilemma."  Certain ill-behaved
window managers update a small region of the taskbar continuously, even though
none of the pixels in that region have changed.  Also, certain programs have a
blinking cursor that may update more frequently than the ALR timeout.  Since
an ALR is triggered based on a period of inactivity relative to the last
framebuffer update, these continuous updates prevent an ALR from ever being
sent.  Fortunately, these ill-behaved window managers and blinking cursors 
do not typically use ''X[Shm]PutImage()'' to perform their continuous updates,
so the problem can be worked around by limiting the regions that are
"eligible" for ALR to just the subset of regions that were drawn with the
''X[Shm]PutImage()'' functions.

You can override the default ALR behavior, thus making all screen regions
eligible for ALR, by setting the ''TVNC_ALRALL'' environment variable to ''1''
on the TurboVNC server machine prior to starting a TurboVNC session.

** Securing a TurboVNC Connection
{anchor: Secure_TurboVNC_Usage}

Normally, the connection between the TurboVNC Server and the TurboVNC Viewer is
completely unencrypted, but securing that connection can be easily
accomplished by using the port forwarding feature of Secure Shell (SSH.)  After
you have started a TurboVNC session on the TurboVNC server machine, open a new
SSH connection into the TurboVNC server machine using the following command
line:

	Linux/Unix/Mac clients :: {:}
	#Verb: <<---
	ssh -L {5900+n}:localhost:{5900+n} {user}@{server}
	---

	Windows clients :: {:}
	#Verb: <<---
	"c:\program files\turbovnc\putty" -L {5900+n}:localhost:{5900+n} {user}@{server}
	---

Replace __''{user}''__ with your user account name on the TurboVNC server
machine and __''{server}''__ with the hostname or IP address of that machine.
Replace __''n''__ with the X display number of the TurboVNC session to which
you want to connect.

For instance, if you wish to connect to display '':1'' on server ''my_server''
using user account ''my_user'', you would type:

	Linux/Unix/Mac clients :: {:}
	#Verb: <<---
	ssh -L 5901:localhost:5901 my_user@my_server
	---

	Windows clients :: {:}
	#Verb: <<---
	"c:\program files\turbovnc\putty" -L 5901:localhost:5901 my_user@my_server
	---

After the SSH connection has been established, you can then launch the
TurboVNC Viewer and point it to ''localhost:''__''{n}''__ (''localhost:1'' in the
above example.)

*** The ''-via'' Command-Line Option
#OPT: noList! plain!

If you are using the Unix/Linux TurboVNC Viewer, then you can simplify the
above by using the ''-via'' command-line option to ''vncviewer''.  For
instance, running

	#Verb: <<---
	/opt/TurboVNC/bin/vncviewer -via {user}@{server} localhost:{n}
	---

is the equivalent of running

	#Verb: <<---
	/usr/bin/ssh -L {5900+n}:localhost:{5900+n} {user}@{server}
	/opt/TurboVNC/bin/vncviewer localhost:{n}
	---

The command used to establish the SSH tunnel is configurable by way of
environment variables.  See the ''vncviewer'' man page for more details.

*** Forcing Secure Connections
#OPT: noList! plain!

Passing an argument of ''-localhost'' to ''vncserver'' will force the TurboVNC
Server session to accept inbound connections only from the server machine.
This effectively forces SSH tunneling to be used for remote connections.  If
the ''no-remote-connections'' directive is set in the TurboVNC authentication
configuration file, then that has the effect of enabling the ''-localhost''
option for all new TurboVNC sessions that are started on the machine.

Passing an argument of ''-noreverse'' to ''vncserver'' will disable the ability
to make outbound (reverse) connections from the TurboVNC Server session.
If the ''no-reverse-connections'' directive is set in the TurboVNC
authentication configuration file, then that has the effect of enabling the
''-noreverse'' option for all new TurboVNC sessions that are started on
the machine.

*** Performance Notes
#OPT: noList! plain!

For LAN connections and other high-speed networks, tunneling the TurboVNC
connection over SSH will reduce performance by as much as 20-40%.  For
wide-area networks, however, there is no performance penalty for using SSH
tunneling with TurboVNC.

** Further Reading

For more detailed instructions on the usage of TurboVNC:

	Linux/Unix/Mac :: Refer to the TurboVNC man pages:
	#Verb: <<---
	man -M /opt/TurboVNC/man {vncserver | Xvnc | vncviewer | vncconnect | vncpasswd}
	---

	Windows :: Use the embedded help feature (the question mark button in the
	upper right of the TurboVNC Viewer dialogs.)
