* Using TurboVNC
{anchor: TurboVNC_Usage}

** Starting and Connecting to a TurboVNC Session

*** Procedure
#OPT: noList! plain!

	#. Open a new Command Prompt/terminal window on your client machine.

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

		Linux/Un*x/Mac clients :: {:}
		#Verb: <<---
		ssh {user}@{server}
		---

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

		Replace __''{user}''__ with your username 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}
		''Desktop 'TurboVNC: my_server:1 (my_user)' started on display 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/Un*x clients :: {:}
		Open a new terminal/xterm and type
		#Verb: <<---
		/opt/TurboVNC/bin/vncviewer
		---

		Mac clients :: {:}
		Open the "TurboVNC Viewer" application, located in the "TurboVNC"
		Applications folder.

		Windows clients :: {:}
		Select "TurboVNC Viewer" in the "TurboVNC" Start Menu group.

	#. A small dialog box will appear.
		{nl}{nl}
		|| Windows TurboVNC Viewer || Linux/Un*x/Mac (Java) TurboVNC Viewer ||
		| {img:newconn-win.png} | {img:newconn-java.png} |
		{nl}
		Enter the X display name (hostname, or IP address, and display number) of
		the TurboVNC session in the "VNC server" field, then click "Connect".

	#. 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/Un*x/Mac (Java) TurboVNC Viewer ||
		| Standard VNC Authentication Dialog | {img:vncauth-win.png} | {img:vncauth-java.png} |
		| Unix Login Authentication Dialog   | {img:unixauth-win.png} | {img:unixauth-java.png} |
		{nl}
		Enter the VNC session password or the Unix username/password and click
		"OK" (Windows) or press Enter (Linux/Un*x/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 within 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 machine that is running the TurboVNC session you want
		to kill.{nl} \
		... or ...{nl} \
		Using the TurboVNC Viewer, connect to the TurboVNC session that you want 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
	want to kill.

To list the X display numbers and process ID's of all TurboVNC sessions
currently running under your user account on a particular server 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 the Java TurboVNC Viewer as either an applet or a Java
Web Start app.  This allows you to easily connect to the TurboVNC session from
a machine that does not have the TurboVNC Viewer installed locally.  The Java
TurboVNC Viewer, when launched in this manner, can use the libjpeg-turbo JNI
library to accelerate JPEG decoding, if the library is available on the client
machine.  If one of the official TurboVNC binary packages is installed on the
server, then it will automatically send the appropriate x86 or x86-64
libjpeg-turbo JNI library for Linux, OS X, or Windows clients when launching
the TurboVNC Viewer using Java Web Start.  If using the Java TurboVNC Viewer as
an applet, then you can install
[[http://www.sourceforge.net/projects/libjpeg-turbo/files][one of the official libjpeg-turbo packages]]
on the client machine to accelerate JPEG decoding.

To use the Java TurboVNC Viewer in a web browser, 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''

This will download a JNLP file to your computer, which you can open in Java
Web Start.  Add ''/applet'' to the URL to launch the viewer as a Java applet
instead (as of this writing, browsers are starting to do away with Java
plugins, so running the viewer as an applet is more of a legacy feature.)

You can add viewer parameters to the URL using the following format:

''http://''__''{turbovnc_server}''__'':{5800+''__''n''__''}?''__''{param1}''__''=''__''{value1}''__''&''__''{param2}''__''=''__''{value2}''__

Examples:

''http://my_server:5801/applet?embed=1&tunnel=1''

will run the viewer as an applet in the browser window and tunnel the VNC
connection through SSH.

''http://my_server:5801?tunnel=1&samp=2x&quality=80''

will run the viewer as a JWS app, tunnel the VNC connection through SSH, and
enable Medium-Quality JPEG.

	!!! NOTE: As of Java 7 Update 51, self-signed JARs are not allowed to run in
	the Java browser plug-in or JWS by default.  This is not an issue if you are
	using the official TurboVNC binary packages, but if you are building a
	self-signed version of the Java TurboVNC Viewer for development purposes,
	then you will need to add ''http://{turbovnc_server}:{http_port}''
	(for example, ''http://my_server:5801'') to Java's Exception Site List, which
	can be found under the "Security" tab in the Java Control Panel.

	!!! NOTE: On some newer OS X systems, downloading a JNLP file may result
	in an error: "xxxxxxxx.jnlp can't be opened because it it from an
	unidentified developer."  To work around this, you can either open the JNLP
	file directly from your Downloads folder, or you can change the application
	security settings in the "Security & Privacy" section of System Preferences
	to allow applications downloaded from anywhere.

** Deploying the Java TurboVNC Viewer Using Java Web Start

Accessing the Java TurboVNC Viewer through TurboVNC's built-in HTTP server, as
described above, is a quick and easy way of running the TurboVNC Viewer on
machines that don't already have a VNC viewer installed (for instance, for the
purpose of collaborating with colleagues who don't normally use TurboVNC.)

To set up a large-scale zero-install deployment of the Java TurboVNC Viewer,
it is desirable to serve up the JAR files from a dedicated web server.  When
deployed using JWS, the Java TurboVNC Viewer provides all of the advantages of
a standalone native viewer, including native levels of performance on most
platforms (see [[#MacJavaPerf][notes regarding performance on Mac platforms]].)

For the purposes of this guide, it is assumed that the reader has some
knowledge of web server administration.

	* Copy the Java TurboVNC Viewer JAR file (''VncViewer.jar'') into a directory
		on your web server.
		{nl}{nl}

	* Copy the libjpeg-turbo JNI JAR files into that same directory.  You can
		obtain these from one of the official TurboVNC 2.0 or later binary packages
		for Linux, or you can download ''libjpeg-turbo-{version}-jws.zip'' from
		libjpeg-turbo 1.3.0 or later (available at
		[[http://sourceforge.net/projects/libjpeg-turbo/files]].)  Note that only
		the JARs included in the official TurboVNC packages are signed using an
		official code signing certificate.
		{nl}{nl}

	* For large organizations, it is recommended that you obtain your own code
		signing certificate from a trusted certificate authority and use
		''jarsigner'' to sign all of the JARs with this certificate.  The specifics
		of this are left as an exercise for the reader.
		{nl}{nl}

	* Create a file called ''TurboVNC.jnlp'' in the same directory as
		''VncViewer.jar'' on the web server, and give it the following contents:

		#Verb: <<---
		<?xml version="1.0" encoding="utf-8"?>
		<jnlp codebase="{turbovnc_url}">
		  <information>
		    <title>TurboVNC Viewer</title>
		    <vendor>The VirtualGL Project</vendor>
		  </information>

		  <resources>
		    <j2se version="1.6+" java-vm-args="-server -Dsun.java2d.d3d=false"/>
		    <jar href="VncViewer.jar"/>
		  </resources>

		  <security>
		    <all-permissions/>
		  </security>

		  <resources os="Mac OS X">
		    <nativelib href="ljtosx.jar"/>
		  </resources>

		  <resources os="Windows" arch="x86">
		    <nativelib href="ljtwin32.jar"/>
		  </resources>

		  <resources os="Windows" arch="amd64">
		    <nativelib href="ljtwin64.jar"/>
		  </resources>

		  <resources os="Linux" arch="i386">
		    <nativelib href="ljtlinux32.jar"/>
		  </resources>

		  <resources os="Linux" arch="amd64">
		    <nativelib href="ljtlinux64.jar"/>
		  </resources>

		  <application-desc main-class="com.turbovnc.vncviewer.VncViewer"/>
		</jnlp>
		---

		!!! NOTE: ''{turbovnc_url}'' should be the absolute URL of the TurboVNC
		Viewer directory on the web server, e.g. ''http://my_server/turbovnc''.

		This is just a minimal example.  Refer to the
		[[http://docs.oracle.com/javase/6/docs/technotes/guides/javaws/][Java Web Start documentation]]
		for additional fields that you might want to add.
		{nl}{nl}

	* You should now be able to access ''{turbovnc_url}/TurboVNC.jnlp'' in your
		browser to launch the Java TurboVNC Viewer with full performance.

** 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/Un*x/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 username 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 want to connect to display '':1'' on server ''my_server''
using user account ''my_user'', you would type:

	Linux/Un*x/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.)

	!!! You can force PuTTY to use an IPv6 interface for the local end of the
	tunnel by replacing ''-L'' with ''-L6'' in the above command line.

	!!! For LAN connections and other high-speed networks, tunneling the TurboVNC
	connection through PuTTY will reduce performance by as much as 20%.

*** The ''-via'' and ''-tunnel'' Command-Line Options
#OPT: noList! plain!

If you are using the Java TurboVNC Viewer (which you are if you are using a
Mac, Linux, or Un*x platform), then you can simplify the above by using the
''-via'' and ''-tunnel'' command-line options, or the equivalent GUI options
(located under the "Security" tab in the Options dialog.)  For instance,
running

	#Verb: <<---
	{vncviewer} -via {user}@{server} localhost:{n}
	---

or

	#Verb: <<---
	{vncviewer} -tunnel {user}@{server}
	---

is the equivalent of running

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

where __''{fp}''__ is a free TCP port on the client machine (this is
automatically determined by the TurboVNC Viewer.)

	!!! In the above examples, ''{vncviewer}'' is the command used to launch the
	TurboVNC Viewer-- ''/opt/TurboVNC/bin/vncviewer'' on Mac/Linux/Un*x
	systems or ''c:\\Program Files\\TurboVNC\\vncviewer-java.bat'' if running
	the Java TurboVNC Viewer on Windows systems.

''-tunnel'' can be used as a shortcut whenever the SSH and VNC servers are the
same machine.  ''-via'' is more flexible, since it allows you to specify the
VNC server to which to connect.  The VNC server is specified from the point of
view of the SSH server, which is why we used ''localhost'' in the above
example.

The command used to establish the SSH tunnel is configurable by way of
environment variables.  See {ref prefix="Section ": VNC_VIA_CMD} for more
details.

	!!! NOTE: In this release of TurboVNC, the TurboVNC Viewer for Linux/Un*x
	and Mac platforms is actually the Java TurboVNC Viewer, which is packaged
	along with the libjpeg-turbo JNI library and necessary glueware to make the
	viewer behave and perform like a standalone native viewer.  Since the Java
	TurboVNC Viewer contains an embedded SSH client, the ''via'' and
	''tunnel'' parameters can also be used when the viewer is run as an applet
	or deployed using Java Web Start.

	!!! The Windows TurboVNC Viewer contains experimental support for the
	''-via'' and ''-tunnel'' command-line options.  Currently, the use of these
	requires Cygwin OpenSSH, since it is the only version of SSH on Windows that
	supports detaching the SSH process once the tunnel has been established.
	When using these options, a console window pops up and remains for the
	duration of the VNC connection.

*** 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 security
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
security configuration file, then that has the effect of enabling the
''-noreverse'' option for all new TurboVNC sessions that are started on
the machine.

** Further Reading

For more detailed instructions on the usage of TurboVNC:

	TurboVNC Server :: Refer to the TurboVNC man pages:
	#Verb: <<---
	man -M /opt/TurboVNC/man vncserver
	man -M /opt/TurboVNC/man Xvnc
	man -M /opt/TurboVNC/man vncconnect
	man -M /opt/TurboVNC/man vncpasswd
	---

	Windows TurboVNC Viewer :: Use the embedded help feature (the question mark
	button in the upper right of the TurboVNC Viewer dialogs.)  You can also
	run ''vncviewer.exe /?'' from a command prompt to get a full list of
	supported command-line options and their descriptions.

	Linux/Un*x/Mac (Java) TurboVNC Viewer :: Run
	#Verb: <<---
	/opt/TurboVNC/bin/vncviewer -?
	---
	to display a full list of supported command-line options/parameters and
	their descriptions.

	Java TurboVNC Viewer on Windows :: Run
	#Verb: <<---
	c:\Program Files\TurboVNC\vncviewer-java.bat -?
	---
	to display a full list of supported command-line options/parameters and
	their descriptions.
