/opt/VirtualGL/bin/vglconnect is a script which wraps 
/opt/VirtualGL/bin/vglclient.  It can ssh to a server, select port
numbers for the client, and can use xauth to make a cookie so the
user's remote applications can access the client's X server.

vglconnect starts vglclient with the '-detach' switch, which causes
vglclient to print out a brief status message and then fork and detach
from the console.  vglclient attempts to read the _VGLCLIENT_PORT and
_VGLCLIENT_SSLPORT root X window properties.  If they exist, then
vglclient prints out a notice that there is already another instance of
itself running on this X display and it aborts.  Otherwise, it starts a
new instance and stores its listening port numbers in _VGLCLIENT_PORT
and _VGLCLIENT_SSLPORT.  In effect, this guarantees that only one
vglclient instance is running for the given X display and that it
remains running until either explicitly killed or until the X display
resets.  vglclient handles SIGTERM and SIGINT, so you can kill -2 it
and it will properly clean up its X properties.  You can also send it
SIGHUP (kill -1) to make it warm restart.  In the unforeseen event that
vglclient exits uncleanly and does not clean up its X properties, then
it may be necessary to invoke vglconnect with the '-force' argument the
next time you run it.  This, in turn, invokes vglclient with '-force'
and forces it to run, even if it detects that the X window properties
are already present.

vglconnect instructs vglclient to store its log files in ~/.vgl/ in the 
format vglconnect-`hostname`-$DISPLAY.log.

After vglconnect starts vglclient, it does one of three things, 
depending on the arguments you specified:

vglconnect [user@]hostname:

    The default is to tunnel X11 over SSh but not tunnel VGL, so vglconnect 
    simply does ssh -X [user@]hostname here (actually, it does ssh -Y if 
    your version of ssh supports that argument.  OpenSSH >= 3.8 uses an 
    untrusted xauth cookie when you invoke ssh -X, and this doesn't work 
    with VGL, so it is necessary to use ssh -Y to get a trusted cookie. 
    Older ssh versions always use a trusted cookie.)

vglconnect -s [user@]hostname

    vglconnect records the port that vglclient is listening on (Pc).  It 
    then opens a brief ssh session into hostname and runs 
    /opt/VirtualGL/bin/nettest -findport to determine a free port (Ps) on 
    the remote machine.  It then opens another ssh session with the -X or -Y 
    argument (as appropriate -- see above) and -RPs:localhost:Pc.  This 
    second ssh session invokes the /opt/VirtualGL/bin/vgllogin script on the 
    server with arguments that tell it that an SSh tunneling session is 
    occurring.  vgllogin sets the VGL_PORT environment variable to Ps and 
    the VGL_CLIENT environment variable to 'localhost', then execs the 
    user's default login shell.

    vglconnect is smart enough to handle multi-level SSh tunnels 
    automatically.  You can vglconnect -s into machinea, then vglconnect -s 
    into machineb from machinea, then vglrun an application, and it will 
    tunnel both X11 and the VGL transport from machineb to machinea to your 
    client.

    Note that unless you are using a password-less SSh login, connecting 
    with vglconnect -s will require you to enter your password twice (once 
    to run nettest -findport, and then the second time to actually make the 
    shell connection.)

vglconnect -x [user@]hostname

    This is the xauth mode we discussed, meant primarily to enable the VGL 
    image transport from a cluster (which will, presumably, be executing 
    your job on an arbitrary node) to a client which is not part of the 
    cluster (and possibly does not share a home directory with it.)

    vglconnect obtains a trusted cookie on the client's X display, invokes 
    vgllogin on the remote server (via. ssh), and passes the cookie to 
    vgllogin via. a command line argument.  It also passes its DISPLAY 
    environment variable to vgllogin.  Using this information, combined with 
    the SSH_CLIENT environment variable, vgllogin constructs an appropriate 
    DISPLAY environment variable for the server and then adds the xauth 
    cookie to the user's ~/.Xauthority file.

    Effectively, you should be able to vglconnect -x into an N1GE submit 
    host and then qsub a job using the VGL image transport.  As long as the 
    DISPLAY environment gets passed to the execute host, and as long as the 
    submit host and the execute host share the same home directories, then 
    it should "Just Work" (TM).

vglconnect -k
    
    This is similar to the -x option above, but does not ssh to a remote
    server.  This is useful in an SGE environment if the client host is an
    SGE submit host.  The user's ~/.Xauthority entry will allow that user's
    SGE jobs to connect back to the client host from any execution host in
    the same domain (sharing the user's $HOME).


Common usage scenarios:

    VGL client to single VGL server, secured LAN
    (must open ports in client's firewall):
	vglconnect

    VGL client to single VGL server, unsecured network
    (or if firewall can't be disabled):
	vglconnect -s
    [SSh tunneling will impact performance]

    VGL client to cluster of VGL servers, secured LAN
    (must open ports in client's firewall):
	vglconnect -x

    TurboVNC server to VGL server, secured LAN
	vglconnect
    then
	vglrun -c rgb (to avoid compressing the images twice)


More information in chapter 8 of the VirtualGL User's Guide at
http://lager.sfbay/adviz/virtualgl/vgldoc/head/#hd008