Flux is primarily a batch-oriented system, however, it is possible and sometimes necessary to use the graphical interface to some software. This can be accomplished using an “interactive batch job” and VNC, a program that will display a remote graphical interface locally. The traditional method for doing so involved setting up X-forwarding, but that can be very slow, especially over slow or congested networks or when off-campus.

VNC creates a virtual desktop to which programs display, and VNC then handles sending changes to that desktop to a viewer that runs on your local computer. This results in much faster updates and much better performance of graphical applications.

There are four steps needed to create and display a VNC session.

  1. Run a batch job that starts the VNC server
  2. Determine the network port that VNC is using
  3. Create a tunnel (network connection) from your local machine to the VNC desktop
  4. Connect to the VNC desktop using the tunnel

Before going through those steps, there is some set up needed. The first is to set a VNC password. This is completely different from your login password. This password is used only when connecting to the desktop, and it is not secure, so please use a password that is not used for other things. To set the VNC password, from a Flux login node run

$ vncpasswd

To get a nicer desktop environment, we highly recommend that you use our xstartup file. To do so,

$ cp /usr/cac/rhel6/vnc/xstartup ~/.vnc/

When you are done working in the VNC session, you will use the

$ stopvnc

command in the provided terminal window to shut down the VNC session and end the job.

Step 1: Submit the batch job

You will need to have a PBS script to run the VNC job. Something like the following, which asks for two processors on one node for two hours.

####  PBS preamble

#PBS -N VNC
#PBS -M uniqname@umich.edu
#PBS -m ab

#PBS -A example_flux
#PBS -l qos=flux
#PBS -q flux

#PBS -l nodes=1:ppn=2,pmem=2gb
#PBS -l walltime=2:00:00
#PBS -j oe
#PBS -V
####  End PBS preamble
if [ -e $PBS_O_WORKDIR ] ; then
    cd $PBS_O_WORKDIR
fi
# Run the VNC server in the foreground so PBS does not end the job.
# You may wish to change 1024x768 to 1280x1024 if you have a large screen.
# On smaller laptops, 1024x768 is recommended.
vncserver -depth 24 -geometry 1024x768 -name ${USER} -AlwaysShared -fg

NOTE Remove any old log and pid files from your ~/.vnc folder before you run qsub with

$ rm ~/.vnc/*.log ~/.vnc/*.pid

If you call that vnc.pbs, then to complete step one of four, you would

$ qsub vnc.pbs

to run it.

We recommend not running more than one VNC job at a time. If you do, you should not delete all the .pid and .log files, but only those from VNC jobs that have finished. If you do, it is up to you to keep track of those files for active jobs.

Step 2: Determining your port

The line #PBS -m ab instructs PBS to send you an e-mail when the job starts, and it will contain something that looks like

PBS Job Id: 17528732.nyx.arc-ts.umich.edu
Job Name:   VNC
Exec host:  nyx5541/11
Begun execution

You will need the hostname, which in this case is nyx5541, from that message to set up the tunnel.

To complete step 2, take the hostname and use the command

$ ls $HOME/.vnc/nyx5541*.log
/home/bennet/.vnc/nyx5541.arc-ts.umich.edu:99.log

The number that follows the hostname, in this case 99, is the desktop number for VNC, and the port number is that plus 5900.

Step 3: Setting up the tunnel

You need to create a tunnel to the node on which your VNC server is running. The tunnel is a way to use one machine, in this case, we will use flux-xfer.arc-ts.umich.edu, to pass the network connection to another, in this case nyx5541.arc-ts.umich.edu. To do this, we use a special form of the ssh command.

From a Mac or a Linux machine, you would use

$ ssh -N -L5999:nyx5541.arc-ts.umich.edu:5999  flux-xfer.arc-ts.umich.edu

This will prompt you for your password and then do nothing except forward the VNC connection to the compute host. Note that we are using the Flux file transfer host and not the login host for this tunnel as it does not require two-factor authentication.

From Windows, we recommend that you use PuTTY, which is available as part of the UM Blue Disc. With PuTTY, you need to set the port forwarding from the configuration menu. You will need to reset this each time the VNC port changes. For more details: Configuring a VNC tunnel with PuTTY.

Step 4: Connect to the VNC desktop

Now that you have a port forwarded, you are ready to connect your VNC client to your running VNC server. Choose the link from menu at the top of this page that corresponds to your VNC client to see what the screens look like.

The VNC client will have a place for you to enter the host, which is usually localhost or the IP number 127.0.0.1, the Display (desktop number), and VNC password. Upon successful completion of the connection, you should get a screen that looks very much like the following.

The VNC session will start with a terminal window open. Run the commands there that you need for your application. When you are done with your VNC session, typing the command

$ stopvnc

in the terminal window will end the VNC session and the PBS job.