* Using VirtualGL with the VGL Transport
{anchor: VGL_Transport_Usage}

*** Advantages of the VGL Transport
#OPT: noList! plain!

	* Seamless windows; every window from the 3D application appears as a
		separate window on the client
	* Supports stereographic rendering (see requirements in
		{ref prefix="Section ": Stereo_Requirements})
	* Consumes less memory and CPU time on the server, since the 2D (X11)
		rendering occurs on the client

*** Disadvantages of the VGL Transport
#OPT: noList! plain!

	* The VGL Transport is designed to be used with client-side 2D X servers, and
		thus it relies on the chatty remote X11 protocol to send the non-OpenGL
		elements of the 3D application's GUI to the client.  As a result, the VGL
		Transport is not recommended for use on high-latency or low-bandwidth
		networks.
	* No collaboration features
	* From the point of view of the 3D application, the client/server connection
		is not stateless.  As with any remote X11 environment, if the network
		connection drops, then the application will exit.

** VGL Transport with X11 Forwarding
{anchor: X11_Forwarding}

This mode is recommended for use only on secure local-area networks.  The X11
traffic is encrypted, but the VGL Transport is left unencrypted to
maximize performance.

*** Procedure

	#. Start the 2D X server if it isn't started already.

		Mac clients :: Start XQuartz.

		Cygwin clients :: Start Cygwin/X.

	#. Open a new terminal window.

		Mac clients :: In XQuartz, start a new xterm [Command-N] if one isn't
			already started.

		Cygwin clients :: Start a new xterm if one isn't already started
			(right-click on the Cygwin/X taskbar icon, then select
				{file: Applications-->xterm}.)

	#. In the same terminal/xterm window, open a Secure Shell (SSH) session into
		the VirtualGL server:

		#Pverb: <<---
		/opt/VirtualGL/bin/vglconnect __user__@__server__
		---

		Replace __''user''__ with your username on the VirtualGL server and
		__''server''__ with the hostname or IP address of that server.

	#. In the SSH session, start a 3D application with VirtualGL:

		#Pverb: <<---
		/opt/VirtualGL/bin/vglrun __[vglrun options]__ __3D-application-executable-or-script__ __[arguments]__
		---

	Consult {ref prefix="Chapter ": Advanced_Configuration} for more
	information on ''vglrun'' command-line options.

** VGL Transport with X11 Forwarding and SSH Tunneling
{anchor: SSH_Tunneling}

Both the VGL Transport and the X11 traffic are tunneled through SSH when
using this mode, and thus it provides a completely secure solution.  It is
also useful when either the client or the VirtualGL server is behind a
restrictive firewall and only SSH connections are allowed through.  Using
SSH tunneling on wide-area networks should not affect performance
significantly.  However, using SSH tunneling on a local-area network can reduce
the end-to-end performance of the VGL Transport by anywhere from 20-40%.

*** Procedure
#OPT: noList! plain!

The procedure for this mode is identical to the procedure for the
[[#X11_Forwarding][VGL Transport with X11 forwarding]], except that you should
pass a ''-s'' argument to ''vglconnect'' when connecting to the server:

	#Pverb: <<---
	/opt/VirtualGL/bin/vglconnect -s __user__@__server__
	---

''vglconnect'' will make two SSH connections into the server, the first to find
an open port on the server and the second to create the SSH tunnel for the VGL
Transport and open the secure shell.  If you are not using an SSH agent to
enable password-less logins, then you will have to enter your password twice.

''vglconnect -s'' can be used to create multi-layered SSH tunnels.  For
instance, if the VirtualGL server is not directly accessible from the Internet,
then you can run ''vglconnect -s'' on the client to connect to an SSH gateway
server, then you can run ''vglconnect -s'' again on the gateway server to
connect to the VirtualGL server (application server.)  Both the X11 traffic and
the VGL Transport will be forwarded from the VirtualGL server through the
gateway and to the client.

#IMG: sshtunnel.png

** The VirtualGL Client Application: Nuts and Bolts

The VirtualGL Client application (''vglclient'') receives encoded and/or
compressed frames on a dedicated TCP socket, decodes and/or decompresses the
frames, and draws the frames into the appropriate X window.  The ''vglconnect''
script wraps both ''vglclient'' and SSH to greatly simplify the process of
creating VGL Transport connections.

''vglconnect'' invokes ''vglclient'' with an argument of ''-detach'', which
causes the VirtualGL Client to completely detach from the console and run as a
background daemon.  It will remain running silently in the background,
accepting VGL Transport connections for the X server on which it was started,
until that X server is reset or until the VirtualGL Client process is
explicitly killed.  Logging out of the X server will reset the X server and
thus kill all VirtualGL Client instances that are attached to it.  You can also
explicitly kill all instances of the VirtualGL Client running under your user
account by invoking

	#Verb: <<---
	vglclient -kill
	---

(''vglclient'' is installed in {file: /opt/VirtualGL/bin} by default.)

''vglconnect'' instructs the VirtualGL Client to redirect all of its console
output to a log file named
{file: ~/.vgl/vglconnect-__hostname__-__display__.log}, where
{file: __hostname__} is the name of the computer on which ''vglconnect'' was
invoked and {file: __display__} is the display name of the X server on which
the VirtualGL Client was started (read from the ''DISPLAY'' environment or
passed to ''vglconnect'' using the ''-display'' argument.)  In the event that
something goes wrong, this log file is the first place to check.

When the VirtualGL Client successfully starts on a given X server, it stores
its listener port number in a root window property on the X server.  If
other VirtualGL Client instances attempt to start on the same X server, they
read the X window property, determine that another VirtualGL Client instance is
already running, and exit to allow the first instance to retain control.  The
VirtualGL Client will clean up the X property under most circumstances, even
if it is explicitly killed.  However, under rare circumstances (if sent a
SIGKILL signal, for instance), a VirtualGL Client instance may exit uncleanly
and leave the X property set.  In these cases, it may be necessary to add an
argument of ''-force'' to ''vglconnect'' the next time you use it.  This tells
''vglconnect'' to start a new VirtualGL Client instance, regardless of whether
the VirtualGL Client thinks that there is already an instance running on this
X server.  Alternately, you can simply reset the X server to clear the
orphaned X window property.

*** The VirtualGL Client and Firewalls

To retain compatibility with previous versions of VirtualGL, the first
VirtualGL Client instance on a given machine will attempt to listen on port
4242 for unencrypted connections and 4243 for SSL connections (if VirtualGL was
built with OpenSSL support.)  If it fails to obtain one of those ports, because
another application or another VirtualGL Client instance is already using them,
then the VirtualGL Client will try to obtain a free port in the range of
4200-4299.  Failing that, it will request a free port from the operating
system.

In a nutshell: if you only ever plan to run one X server at a time on the
client, which means that you'll only ever need one instance of the VirtualGL
Client at a time, then it is sufficient to open inbound port 4242 (and 4243 if
you plan to use SSL) in the client's firewall.  If you plan to run multiple X
servers on the client, which means that you will need to run multiple VirtualGL
Client instances, then you may wish to open ports 4200-4299.  Similarly, if you
are running the VirtualGL Client on a multi-user X proxy server that has a
firewall, then you may wish to open ports 4200-4299 in the server's firewall.
Opening ports 4200-4299 will accommodate up to 100 separate VirtualGL Client
instances (50 if OpenSSL support is enabled.)  More instances than that cannot
be accommodated on a firewalled machine, unless the firewall is able to create
rules based on application executables instead of listening ports.

Note that it is not necessary to open any inbound ports in the firewall to use
the VGL Transport with [[#SSH_Tunneling][SSH Tunneling]].
