_{Updated 2022-08-08}

VNC Session Guide

Setting up a VNC Session on PACE's clusters

• You can run virtual desktop sessions on PACE clusters via Open OnDemand, entirely within a browser window.
• The older pace-vnc-job utility remains available on Moab/Torque clusters and requires an additional client.

Tip

PACE now recommends using Open OnDemand for virtual desktop sessions. The following information provides instructions for our prior utility and is recommended only for clusters without OnDemand.

• Install a VNC viewer client on your local machine. We recommend TurboVNC, but any viewer client will work.

Note

If you are using macOS, please install TurboVNC via homebrew with brew cask install turbovnc-viewer. If you would like to use a stand-alone package for macOS instead, you can use RealVNC.

• Start by connecting to the cluster. If you are not on GT network, please connect to the VPN first.

Warning

3rd-party applications such as Putty do not recognize the SSH escape character '~'. If you are using Windows, it is recommended that you use Powershell with OpenSSH (default on Windows 10), as other terminal applications do not establish port-forwarding correctly via instructions below.

• To start a remote VNC session, run the command pace-vnc-job -q <QUEUENAME>, where <QUEUENAME> should be replaced with the queue to which you wish to submit your job
  • Important: If you are using Phoenix or Firebird clusters, you must include the -A flag followed by your account name: pace-vnc-job -q <QUEUENAME> -A <ACCOUNTNAME>
    • Run pace-quota to see available accounts
  • By default, this will start a VNC job on 1 node, with 1 processor and 1 GB of memory, for 1 hour
  • If the requested resources need to be modified, use the standard qsub options:
    • -l can be used to set resource requests such as nodes, ppn, walltime, mem, pmem, etc.
    • -N can be used to set a custom name for the job
    • -j can be used to set the output flags (e.g. -j oe)
    • -o can be used to set the output file path
  • For example, to run a 4 hour VNC session with access to 2 nodes and 4 ppn, we could run the command
    pace-vnc-job -q inferno -A myAccount -l nodes=2:ppn=4,walltime=4:00:00
  • You can also specify a custom resolution for your VNC session to match your local resolution
    • By default, all VNC sessions are run with a resolution of 1024x768
    • To specify a different resolution, use the --geometry option
    • For example, to run a VNC session with a resolution of 1680x1050, the command would be
      pace-vnc-job -q <QUEUENAME> -A <ACCOUNTNAME> --geometry=1680x1050,
      where <QUEUENAME> is replaced by the queue in which the job should be run
• The script will print output to the screen as the job is started

Tip

The script will not allow you to run a VNC session without a session password. If ~/.vnc/passwd does not exist, run vncpasswd and enter a session password. You will need this password to connect your VNC viewer client to your remote session.

• To connect to your VNC server, you first need to establish port-forwarding through your current SSH session
  • The escape sequence SHIFT + ~ + C (hold the SHIFT key and press ~ then C) will open an SSH console to modify your current session
  • When successfully entered, a prompt displaying ssh> will appear on a new line

Tip

To be recognized as the SSH escape character, it MUST be the first character on a new line. If you see the ~ character appear when you start to type, delete it, hit ENTER to start a new line, and try again.

Tip

If your keyboard does not use the US Layout, you may need to remap the SSH escape character. To do this, exit any SSH sessions, add 'EscapeChar +' (without quotes) to the start of ~/.ssh/config, and login again. When you run pace-jupyter-notebook, type SHIFT + + and then SHIFT + C.

Caution

If you encounter the error that the port is already in use and forwarding failed, this means that you are already forwarding that port to your local machine. To fix this issue, cancel the existing port-forwarding by opening a new SSH interface (SHIFT+~+C) and entering -KL<PORT>, where <PORT> is the port number you wish to clear.

• Copy and paste the purple text that begins with -L into the SSH prompt and hit ENTER to begin port-forwarding
  • The port and compute node combination are unique to your job, so make sure you use the values provided
  • The prompt will display "Forwarding port." if successful; to return to your normal shell prompt, hit ENTER once more
• Open your local VNC viewer client (such as TurboVNC Viewer), and connect to the display specified by the green text
  • Again, the display is unique to your job, so be sure to copy the correct display number from the green text

• Enter your VNC password to connect to your VNC session
  • You will not need to enter a username

• Congratulations! You have connected to your remote VNC server

• Once in your VNC session, you can open a terminal to load any necessary modules (Matlab, COMSOL, etc.) and start your applications
  • Right click on an empty portion of the virtual desktop and select the option to open a terminal
    • On RHEL6 systems, choose "Open in a Terminal"
    • On RHEL7 systems, choose "Open Terminal"
• Once finished, close your VNC viewer client and log off
  • If you would like to clean up further, you can delete the job with qdel <JOBID>