From CC Doc
Jump to: navigation, search
Other languages:
English • ‎français
MATLAB running via VNC.

It is sometimes useful to start a graphical user interface for certain software packages (like MATLAB for example). The most widely-available way to do this is with SSH and X11 forwarding, but the performance of SSH+X11 is often too slow to be useful. An alternative is to use VNC to start and connect to a remote desktop.


First you will need to install a VNC client on your machine to connect to the VNC server. We recommend using TigerVNC. A TigerVNC package is available for Windows, MacOS and most Linux distributions. The following shows how to download and install TigerVNC for each operating system. The certificate configuration steps are only required for connecting to VDI Nodes so the signing authority of the certificate presented by the vncserver is known. If a popup about a certificate issue occurs either you have not configured it properly or you are not connected to our server and should not enter your password.


Download and run the latest tigervnc64-x.y.z.exe installer (the 64 is for 64-bit Windows). Be sure to uncheck both "Register new TigerVNC Srever as a system service and "Start or restart TigerVNC service" - these options are for sharing your desktop and not for connecting to our systems. Next click to download cacert.pem to a local directory. When you start TigerVNC (click desktop icon) for the first time configure the viewer by clicking the desktop TigerVNC Viewer icon. In the "VNC Viewer: Connection Details" window that appears click "Options -> Security" then check all boxes and enter your C:\full\directory\pathto\cert.pem in the "Path to X509 certificates" field. Click OK to save the changes.


Download and run the latest tigerVNC-x.y.z.dmg package. When you start TigerVNC (click desktop icon) for the first time configure the viewer by clicking the desktop TigerVNC Viewer icon. In the “VNC Viewer: Connection Details” window that appears click “Options -> Security” then check all boxes and enter /etc/ssl/cert.pem in the “Path to X509 certificates” field. Click OK to save the changes.


Install the TigerVNC viewer with your package manager and then symlink ~/.vnc/x509_ca.pem to your system certificate authority list. To start TigerVNC either find it in the Applications menu or run vncviewer from the command line.

Debian or Ubuntu

  [name@local_computer]$ sudo apt-get install tigervnc-viewer
  [name@local_computer]$ mkdir ~/.vnc
  [name@local_computer]$ ln --symbolic --interactive --no-target-directory /etc/ssl/certs/ca-certificates.crt ~/.vnc/x509_ca.pem

Fedora, CentOS, or RHEL

  [name@local_computer]$ sudo yum install tigervnc
  [name@local_computer]$ mkdir ~/.vnc
  [name@local_computer]$ ln --symbolic --interactive --no-target-directory /etc/pki/tls/certs/ca-bundle.crt ~/.vnc/x509_ca.pem


  [name@local_computer]$ emerge -av net-misc/tigervnc
  [name@local_computer]$ mkdir ~/.vnc
  [name@local_computer]$ ln --symbolic --interactive --no-target-directory /etc/ssl/certs/ca-certificates.crt ~/.vnc/x509_ca.pem


Now you need a VNC server to connect to. This can be either a persistent vncserver running on dedicated VDI Nodes which are part of Graham, or a temporary vncserver you start on a cluster Compute Node.

VDI Nodes

Graham has dedicated VDI login nodes that provide a full graphical desktop, accelerated OpenGL, and access to /home, /project, and /scratch filesystems. You can connect to one of the VNC login nodes directly by starting your VNC viewer and entering the address This will bring up a login screen to which you can log in using your Compute Canada credentials.

As with regular login nodes, these VDI login nodes are a shared resource and are not intended for doing batch computation (that is what the compute nodes are for), so please limit your use of them to graphics-related tasks. A non-exclusive list of examples includes graphical pre-processing steps such as mesh generation, graphical post-processing steps such as visualization, and using graphical intergrated development environments (IDEs).

Installing software

Open-source software is provided by the nix module. The nix store on gra-vdi is preconfigured to use accelerated OpenGL whenever possible. To install a nix package into your environment click the black terminal icon on the top menu bar or pick Applications -> System Tools -> Terminal. Once a terminal window appears, run module load nix. Now you can search for programs using the nix search <regexp> command and install them in your environment using the nix-env --install --attr <attribute> command. As an example, say you wanted to install QGIS:

[name@gra-vdi4]$ module load nix
[name@gra-vdi4]$ nix search qgis
Attribute name: nixpkgs.qgis
Package name: qgis
Version: 2.18.20
Description: User friendly Open Source Geographic Information System
[name@gra-vdi4]$ nix-env --install --attr nixpkgs.qgis

Your nix environment persists from one login to the next, therefore you only need to run an install command once. Whatever you install today will be available anytime you load the nix module.

  [name@gra-vdi4]$ module load nix
  [name@gra-vdi4]$ qgis

Building OpenGL applications

For accelerated OpenGL to work, it is necessary to adjust compiled binaries to pre-load an appropriate version of the "" library from VirtualGL. This has already been done for software modules available on gra-vdi and any OpenGL based packages you build/install via nix. It is, however, something that has to be done for any pre-built software you download or any codes you compile without using nix.

The easiest way to do this is use the patchelf utility from nix (use nix-env --install --attr nixpkgs.patchelf to install it) to adjust the final binary. For example, say you built an OpenGL application against the system libraries and installed it as ~/.local/bin/myglapp. Then you need to add the system VirtualGL library /usr/lib64/VirtualGL/ as the first required library to it

  [name@gra-vdi4]$ module load nix
  [name@gra-vdi4]$ patchelf --add-needed /usr/lib64/VirtualGL/ ~/.local/bin/myglapp

Note that it is also possible to pre-load via the LD_PRELOAD environment variable. This is generally a bad idea as it applies indiscriminately to all binaries, and those that require a different than that set in LD_PRELOAD will then fail, but it can be used safely in some cases in wrapper scripts.

Compute Nodes

Where VDI login nodes are unavailable you can start a VNC server on a compute node, and, with suitable port forwarding, connect to it from your desktop. This gives you dedicated access to the server, but does not provide a full graphical desktop or hardware-accelerated OpenGL.

Starting a VNC server

Before starting your VNC server, reserve a node on which to run it using salloc. As an example, to request an interactive job using 4 CPUs and 16GB of memory you could use the command:

[username@cedar5:~/project] salloc --time=1:00:0 --cpus-per-task=4 --mem=16000 --account=def-username
salloc: Pending job allocation 20067316
salloc: job 20067316 queued and waiting for resources
salloc: job 20067316 has been allocated resources
salloc: Granted job allocation 20067316
salloc: Waiting for resource configuration
salloc: Nodes cdr768 are ready for job

Once your interactive job has started, one environment variable must be set in order to avoid some repetitive desktop errors:

[username@cdr768:~/project] export XDG_RUNTIME_DIR=${SLURM_TMPDIR}

Then, start a VNC server with vncserver. Take note of which node your job is running on. If unsure, you can use the hostname command to check. The first time you do this you will be prompted to set a password for your VNC server. DO NOT LEAVE THIS BLANK. You may change it later using the vncpasswd command. Continuing with the example:

[username@cdr768:~/project] vncserver
You will require a password to access your desktops.
Would you like to enter a view-only password (y/n)? n
xauth:  file /home/username/.Xauthority does not exist
New ' (username)' desktop is
Creating default startup script /home/username/.vnc/xstartup
Creating default config /home/username/.vnc/config
Starting applications specified in /home/username/.vnc/xstartup
Log file is /home/username/.vnc/

Determine which port the VNC server is using by examining the log file:

[username@cdr768:~/project] grep port /home/username/.vnc/
 vncext:      Listening for VNC connections on all interface(s), port 5901

Setting up an SSH tunnel to the VNC server

Once your VNC server has been started, create a "bridge" to allow your local desktop computer to connect to the compute node directly. This bridge connection is created using an SSH tunnel. SSH tunnels are created on your computer using the same SSH connection command as usual, with an extra option added - this follows the format: ssh user@host -L port:compute_node:port.

An example of an SSH tunnel command run on your computer to connect to a VNC server running on Graham's gra768 node and port 5901 would be the following:

[name@local_computer]$ ssh -L 5902:cdr768:5901

The SSH tunnel operates like a normal SSH session: You may run commands over it, etc. However, keep in mind that this SSH session is also your connection to the VNC server. If you terminate the SSH session, your connection to the VNC server will be lost! For more information, please see SSH tunnelling.

Connecting to the VNC server

To connect to the VNC server via the tunnel you just need to tell your VNC client to connect to localhost:port. The following example uses TigerVNC's vncviewer to connect to the running VNC server on cdr768. You will be prompted for the VNC password that you set earlier in order to connect. If you are a MacOS user click the TigerVNC Viewer application icon instead of running vncviewer on the command line and enter the localhost:port information in the popup window that appears.

Command with sample output:

[name@local_computer]$ vncviewer localhost:5902
TigerVNC Viewer 64-bit v1.8.0
Built on: 2018-06-13 10:56
Copyright (C) 1999-2017 TigerVNC Team and many others (see README.txt)
See for information on TigerVNC.

Tue Jul 10 17:40:24 2018
 DecodeManager: Detected 8 CPU core(s)
 DecodeManager: Creating 4 decoder thread(s)
 CConn:       connected to host localhost port 5902
 CConnection: Server supports RFB protocol version 3.8
 CConnection: Using RFB protocol version 3.8
 CConnection: Choosing security type VeNCrypt(19)
 CVeNCrypt:   Choosing security type TLSVnc (258)

Tue Jul 10 17:40:27 2018
 CConn:       Using pixel format depth 24 (32bpp) little-endian rgb888
 CConn:       Using Tight encoding
 CConn:       Enabling continuous updates

The port number (here 5902) must match the local port (the first number) you specified when you set up the SSH tunnel. The default VNC port is 5900. If you specified 5900 for the local port of the SSH tunnel, you could omit it when you invoke vncviewer. However, Windows users may find that they cannot set up an SSH tunnel on local port 5900.

Once connected, you will be presented with an Xterm window and a blank desktop. To launch a program, simply invoke the command as you would normally within the Xterm window. xclock will start a sample clock application you can use to test things out. To start a more complicated program like MATLAB, load the module and launch the program as follows:

  [name@server ~]$ module load matlab
  [name@server ~]$ matlab

Locked MATE desktop

If you are running MATE desktop environment inside your VNC session and find it locked, you can kill the screensaver on the node where your VNC session is running:

  [name@server ~]$ killall -9 .mate-screensav

Resetting your VNC server Configuration

You can reset your VNC server password with the the vncpasswd command. Or you can completely remove your VNC configuration including your password by deleting your ~/.vnc directory; The next time you run vncserver you will be prompted to set a new password.