View source for Setting Up VNC Session

[[wikipedia:Virtual_Network_Computing|Virtual Network Computing (VNC)]] is a cross-platform desktop sharing system to interact with a remote system's desktop using a graphical interface. This page covers basic instructions to access a desktop on [[Cheaha]] using VNC. These basic instructions support a variety of use-cases where access to graphical applications on the cluster is helpful or required. If you are interested in knowing more options or detailed technical information, then please take a look at man pages of specified commands.

== One Time Setup ==
VNC use on Cheaha requires a one-time-setup to configure settings to starting the virtual desktop. These instructions will configure the VNC server to use the Gnome desktop environment, the default desktop environment on the cluster. (Alternatively, you can run the vncserver command without this configure and and start a very basic (but harder to use) desktop environment.) To get started [[Cheaha_GettingStarted#Login | log in to cheaha via ssh.]]

=== Set VNC Session Password ===
You must maintain a password for your VNC server sessions using the vncpasswd command. The password is validated each time a connection comes in, so it can be changed on the fly using vncpasswd command anytime later.  '''Remember this password as you will be prompted for it when you access  your cluster desktop'''. By default, the command stores an obfuscated version of the password in the file $HOME/.vnc/passwd.

<pre>
$ vncpasswd 
</pre>

=== Configure the Cluster Desktop ===
The vncserver command relies on a configuration script to start your virtual desktop environment. The [[wikipedia:GNOME|GNOME]] desktop provides a familiar desktop experience and can be selected by creating the following vncserver startup script (~/.vnc/xstartup).

<pre>
mkdir $HOME/.vnc

cat > $HOME/.vnc/xstartup <<\EOF
#!/bin/sh

# Start up the standard system desktop
unset SESSION_MANAGER
exec /etc/X11/xinit/xinitrc

EOF

chmod +x $HOME/.vnc/xstartup
</pre>

By default a VNC server displays graphical environment using a tab-window-manager. If the above xstartup file is absent, then a file with the default tab-window-manager settings will be created by the vncserver command during startup.  If you want to switch to the GNOME desktop, simply replace this default file with the settings above. 

This completes the one-time setup on the cluster for creating a VNC server password and selecting the preferred desktop environment.

=== Select a VNC Client ===
You will also need a VNC client on your personal desktop in order to remotely access your cluster desktop.  

Mac OS comes with a native VNC client so you don't need to use any third-party software.  Chicken of the VNC is a popular alternative on Mac OS to the native VNC client, especially for older Mac OS, pre-10.7.

Most Linux systems have the VNC software installed so you can simply use the vncviewer command to access a VNC server. 

If you use MS Windows then you will need to install a VNC client. Here is a list of VNC client softwares and you can any one of it to access VNC server. 
 * http://www.tightvnc.com/ (Mac, Linux and Windows)
 * http://www.realvnc.com/ (Mac, Linux and Windows)
 * http://sourceforge.net/projects/cotvnc/ (Mac)

== Start your VNC Desktop == 
Your VNC desktop must be started before you can connect to it.  To start the VNC desktop you need to log into cheaha using an [[Cheaha_GettingStarted#Login|standard SSH connection]]. The VNC server is started by executing the vncserver command after you log in to cheaha. It will run in the background and continue running even after you log out of the SSH session that was used to run the vncserver command.

To start the VNC desktop run the vncserver command.  You will see a short message like the following from the vncserver before it goes into the background. You will need this information to connect to your desktop.
<pre>
$ vncserver 
New 'login001:24 (blazer)' desktop is login001:24

Starting applications specified in /home/blazer/.vnc/xstartup
Log file is /home/blazer/.vnc/login001:24.log
</pre>

The above command output indicates that a VNC server is started on VNC X-display number 24, which translates to system port 5924. The vncserver automatically selects this port from a list of available ports.

The actual system port on which VNC server is listening for connections is obtained by adding a VNC base port (default: port 5900) and a VNC X-display number (24 in above case). Alternatively you can specify a high numbered system port directly (e.g. 5927) using '-rfbport <port-number>' option and the vncserver will try to use it if it's available. See vncserver's man page for details.

Please note that the vncserver will continue to run in the backgound on the head node until it is explicitly stopped.  This allows you to reconnect to the same desktop session without having to first start the vncserver, leaving all your desktop applications active.  When you no longer need your desktop, simply log out of your desktop using the desktop's log out menu option or by explicitly ending the vncserver command with the 'vncserver -kill ' command.

=== Alternate Cluster Desktop Sizes ===
The default size of your cluster desktop is 1024x768 pixels.  If you want to start your desktop with an alternate geometry to match your application, personal desktop environment, or other preferences, simply add a "-geometry hieghtxwidth" argument to your vncserver command.  For example, if you want a wide screen geometry popular with laptops, you might start the VNC server with:
<pre>
vncserver -geometry 1280x800
</pre>

== Establish a Network Connection to your VNC Server ==

As indicated in the output from the vncserver command, the VNC desktop is listening for connections on a higher numbered port.  This port isn't directly accessible from the internet. Hence, we need to use SSH local port forwarding to connect to this server.

This SSH session provides the connection to your VNC desktop and must remain active while you use the desktop.  You can disconnect and reconnect to your desktop by establishing this SSH session whenever you need to access your desktop.  In other words, your desktop remains active across your connections to it. This supports a mobile work environment.

=== Port-forwarding from Linux or Mac Systems ===
Set up SSH port forwarding using the native SSH command. 
<pre>
# ssh -L <local-port>:<remote-system-host>:<remote-system-port> USERID@<SSH-server-host>
$ ssh -L 5924:localhost:5924 USERID@cheaha.rc.uab.edu
</pre>
Above command will forward connections on local port 5924 to a remote system's (same as SSH server host Cheaha - hence localhost) port 5924.

=== Port-forwarding from Windows Systems ===
Windows users need to establish the connection using whatever SSH software they commonly use. The following is an example configuration using Putty client on Windows. Be sure to press the "Add" button to save the configuration with the session and ensure the tunnel is opened when the connection is established.

[[File:Putty-SSH-Tunnel.png]]

== Access your Cluster Desktop ==

With the network connection to the VNC server established, you can access your cluster desktop using your preferred VNC client. When you access your cluster desktop you will be prompted for the VNC password you created during the one time setup above.

The VNC client will actually connect to your local machine, eg. "localhost", because it relies on the SSH port forwarding to connect to the VNC server on the cluster. You do this because you have already created the real connection to Cheaha using the SSH tunnel.  The SSH tunnel "listens" on your local host and forwards all of your VNC traffic across the network to your VNC server on the cluster.

You can access the VNC server using the following connection scenarios based on your personal desktop environment.

==== From Mac ====

'''For Mac OSX 10.8 and higher'''
Mac users can use the default VNC client and start it from Finder. Press '''cmd+k''' to bring up the "connect to server" window. Enter the following connection string in Finder: 
<pre>vnc://localhost:5924 </pre>
The connection string pattern is "vnc://<vnc-server>:<vnc-port>".  Adjust your port setting for the specific value of your cluster desktop given when you run vncserver above.

'''For Mac OSX 10.7 and lower'''
Download and install Chicken of the VNC from [http://sourceforge.net/projects/cotvnc/| sourceforge].
Start COTVNC and enter the following in the host window and provide the VNC password you created during set up when prompted:
<pre>localhost:5924</pre>


==== From Linux ====
Linux users can use the command
<pre>
vncviewer :24 
</pre>

===== Shortcut for Linux Users =====
Linux users can optionally skip the explicit SSH tunnel setup described above by using the -via argument to the vncviewer command. The "-via <gateway>" will set up the SSH tunnel implicitly. For the above example, the following command would be used:
<pre>
vncviewer -via cheaha.rc.uab.edu :24
</pre>
This option is preferred since it will also establish VNC settings that are more efficient for slow networks. See the man page for vncviewer for details on other encodings.

==== From Windows ====
Windows users should use whatever connection string is applicable to their VNC client. 

Remember to use "localhost" as the host address in your VNC client.  You do this because you have already created the real connection to Cheaha using the SSH tunnel.  The SSH tunnel "listens" on your local host and forwards all of your VNC traffic across the network to your VNC server on the cluster.

== Using your Desktop ==
Once we have a VNC session established with Gnome desktop environment, we can use it to launch any graphical application on Cheaha or use it to open GUI (X11) supported SSH session with a remote system in the cluster. 

VNC can be particularly useful when we are trying to access and X Windows application from MS Windows, as native X11 setup on Windows is typically more involved than the VNC setup above. For example, it's much easier to start X11 based SSH session with the remote system  on the cluster from above Gnome desktop environment than doing all X11 setup on Windows.
<pre> 
$ ssh -X $USER@172.x.x.x
</pre>

=== Performance Considerations for Slow Networks ===

If the network you are using to connect to your VNC session is slow (eg. wifi or off campus), you may be able to improve the responsiveness of the VNC session by adjusting simple desktop settings in your VNC desktop.  The VNC screen needs to be repainted every time your desktop is modified, eg. opening or moving a window.  Any bit of data you don't have to send will improve the drawing speed.  Most modern desktops default to a pretty picture.  While nice to look at these pictures contain lots data.  If you set your desktop background to a solid color (no gradients) the screen refresh will be much quicker (see System->Preferences->Desktop Background).  Also, if you change to a basic windowing theme it will also speed screen refreshes (see System->Preferences->Themes->Mist).