A graphical desktop sharing system that allows users to connect to remote computers

Introduction

VNC is a graphical desktop sharing system that allows users to connect to remote computers like Research Computing's clusters and use GUIs (graphical-user-interfaces) to interact with programs or to do visualization work. It is advantageous because it eliminates the need to send 3D data over the network via an X-Windows environment (which would be slower). Once you connect to a cluster through TurboVNC, you can then take advantage of the local CPU and GPU capabilities on that machine. It is highly recommended to use this for applications that do 3D rendering.

The instructions here describe how to connect to a remote desktop on stellar. 
(If you are looking to use TurboVNC with other visualization nodes–e.g., adroit-vis, della-vis1, stellar-vis1, etc.–please follow the instructions for Option 1 on our Working with Visualizations and GUI Applications page instead.)

Also, if you are working with 3D graphics, once you load your VNC desktop we highly recommend running your programs with VirtualGL (instructions below).

TurboVNC Installation and Use

1. Install TurboVNC

On your local machine (your computer), download and install the TurboVNC client from here: http://sourceforge.net/projects/turbovnc.

The most recent version should be fine, but we have tested with 2.2.5.

If you have trouble installing and configuring this software, visit the OIT Tech Store for help.

2. Start a VNC Session

Use your SSH shell window (such as the Terminal application on MacOS or Linux, or something like PuTTY or Mobaxterm on Windows) to ssh into stellar and start a vnc session.

Connect to stellar:

$ ssh <YourNetID>@stellar.princeton.edu

Load the turbovnc module to enable vnc commands:

$ module load turbovnc/2.2.1

Start a vnc session:

$ vncserver

NOTE: The first time you start vncserver you will be prompted to create a password to access your vnc desktops. This can be anything you like. Should you choose to change it in the future simply delete the file ~/.vnc/passwd, and the next time you start a vnc session you will be prompted to recreate a password.

You may also be prompted to setup a different, view-only password. This is for instances where you'd like to invite others to view your desktop, but others' keystrokes would be disabled. If you choose to set up a view-only password, use a password that you would feel comfortable sharing with others.

You should get an output that looks like this:

Desktop 'TurboVNC: stellar.princeton.edu:1 (NetID)' started on display stellar.princeton.edu:1
Creating default startup script /home/NetID/.vnc/xstartup.turbovnc
Starting applications specified in /home/NetID/.vnc/xstartup.turbovnc
Log file is /home/NetID/.vnc/stellar.princeton.edu:1.log

Note the session number from your output. In the above example the session number is :1. You can always check what vnc session(s) you have open with the following command:

$ vncserver -list
TurboVNC server sessions:
X DISPLAY # PROCESS ID
:1 18966

3. Connect to Your VNC Session, From Your Computer

In this step we'll use the TurboVNC viewer application (downloaded in step 1) to connect to the graphical desktop on stellar.

i. First, open an ssh tunnel to your vnc session on stellar.

  • a. Open a new ssh shell window, and from your local machine (i.e. not in stellar) set up a a new ssh tunnel. This is necessary because TurboVNC is not encrypted.
    Below is an example for the above session (:1) when run on a Linux/Mac, but make sure to use the proper command for your operating system (see next bullet point, b.). Also remember to use your own session number and to enter your own NetID before "@stellar".
    • Example for the above session (:1) when using Linux/Mac:
      $ ssh -A -L 5901:localhost:5901 <YourNetID>@stellar.princeton.edu
  • b. Choose the appropriate command for your operating system (modify content within the <>'s, where "n" refers to the session number from earlier):
    • Linux/Mac: ssh -A -L <5900+n>:localhost:<5900+n> <YourNetID>@stellar.princeton.edu
    • Windows - 32-bit (from a command prompt, all on one line): "C:\Program Files (x86)\TurboVNC\putty" -L <5900+n>:localhost:<5900+n> <YourNetID>@stellar.princeton.edu
    • Windows - 64-bit (from a command prompt, all on one line): "C:\Program Files\TurboVNC\putty" -L <5900+n>:localhost:<5900+n> <YourNetID>@stellar.princeton.edu
  • c. You may see a message or dialog box similar to this: "The server's host key is not cached in the registry". If you do, type or click "yes". Enter the password associated with your netID.

ii. Second, connect to the graphical desktop on stellar by using the TurboVNC Viewer application on your computer.

  • a. Open the TurboVNC Viewer application that you downloaded in the first step, and in the VNC server box type "localhost:<n>" (for example: "localhost:1"). 
VNC Session
  • NOTE: If you receive an error message saying 'JRELoadError,' you need to install the Java software OpenJDK.
    • On a Mac machine:
      • Download OpenJDK to your computer by following the instructions in the 'Uninstall Oracle Java and Install OpenJDK Instructions' section of this article
      • Use a text editor like vim or emacs to add the following two lines to your ~/.bash_profile:
        export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home/jre
        launchctl setenv JAVA_HOME $JAVA_HOME
      • Then activate the changes by running:
        source ~/.bash_profile
    • On a Linux machine:
      • Install OpenJDK, currently jdk-13.0.1.  It downloads as a tar.gz file so it can be installed anywhere.
      • Use a text editor like vim or emacs to add the following line to the file ~/.bashrc:
        export PATH=/your/path/to/jdk-13.0.1/bin:$PATH
        Then activate the changes by running: source ~/.bashrc
  • b. Click connect.
  • c. Enter the password you set up when you created your vncserver session above.
    • You should now be able to see your stellar desktop.
VNC Desktop

iii. If you are working with 3D graphics, we highly recommend running your programs with VirtualGL. See below for instructions on how to use VirtualGL.

Troubleshooting the "Could not connect to session bus" Error

If you have installed Anaconda or Miniconda then you will need to remove the lines that those softwares write in your ~/.bashrc or ~/.bash_profile file on stellar. You can do this by creating a temporary, e.g., ~/.bashrc file without those lines. You must also make sure that you have not loaded the anaconda3 module. The dbus daemons between Anaconda/Miniconda and VNC are incompatible. The error associated with this problem is "Could not connect to session bus: Failed to connect to socket /tmp/dbus-jDltJXpQr3: Connection refused".

Closing TurboVNC and VNC Sessions

One advantage of this system is that you can take a break from your work, but your VNC session on stellar will remain open and you can reconnect to it at any time. In other words, if you close the ssh tunnel and/or the TurboVNC viewer application (both of which you opened in step 3), your VNC session on stellar (which you opened in step 2) will remain in tact. Just reconnect. However, in general it is best practice to close the VNC session when you are finished.

  • To reconnect at a later time and pick up right where you left off, repeat the procedure for connecting to a the remote VNC session on stellar (step 3).
  • When you are finished with a VNC session entirely, you should end it.
    • To end a vnc session:
      • ssh to stellar (see above)
      • If you haven't already, load the turbovnc module

$ module load turbovnc/2.2.1

  • Check the number of your vnc session with vncserver -list and note the display # of the session you want to end
  • Do "vncserver -kill :<n>" where n is the number (with a colon).
    • Example:

$ vncserver -kill :1

VirtualGL (and Troubleshooting)

To take full advantage of the local graphics hardware of stellar we use VirtualGL. Note this will only work within a VNC session, and it will only work on nodes with a GPU. The instructions here are for a Terminal opened on your VNC desktop.

Check to make sure you have the virtualgl module loaded, if not do:

$ module load virtualgl/2.6.1

Start a program as you normally would but precede the command with vglrun. Some examples:

$ vglrun visit (after doing "module load visit")

$ vglrun paraview (after doing "module load paraview")

$ vglrun matlab (after doing "module load matlab/R2020a")

Problems related to 3D graphics can often be solved by running the command under vglrun as shown above.

Simplify the Process to Connect to TurboVNC

For users who connect frequently to TurboVNC, the process described above can be simplified with the use of shell functions.

1. Add these two functions using a text editor to your ~/.bashrc file on stellar:

turbostart() {
    module load turbovnc/2.2.1;
    if [ $(vncserver -list | wc -l) -eq 4 ]; then
        vncserver;
    else
        echo -e "\n***SESSION ALREADY RUNNING***" && vncserver -list;
    fi
}
turbostopall() {
    module load turbovnc/2.2.1;
    for x in $(vncserver -list);
    do
        if [[ $x =~ ^: ]]; then
            vncserver -kill $x;
        fi;
    done
}

2. Add this shell function to the startup script on your local machine (e.g., ~/.bash_profile on macOS or ~/.bashrc on Linux) and be sure to replace <YourNetID> with your NetID:

turbossh() {
    if [ "$#" -eq 0 ]; then
        echo "\nMissing session number\n";
    else
        ssh -A -L $(( 5900 + $1 )):localhost:$(( 5900 + $1 )) <YourNetID>@stellar.princeton.edu;
    fi
}

3. Once you have entered these three functions and sourced your scripts - for example, source ~/.bashrc, source ~/.bash_profile, etc. - a typical session can be started as follows:

i. Connect to stellar and start a VNC session:

$ ssh <YourNetID>@stellar.princeton.edu
$ turbostart

ii. In a new shell, on your local machine open an SSH tunnel (if the session number is 42, for example):

$ turbossh 42

iii. Launch the TurboVNC Viewer application and in the VNC server box enter 'localhost:42'.

4. To end the session on stellar:

$ turbostopall