VNC

MATLAB running via VNC.

It is often necessary to remotely start the graphical user interface for complex software packages such as MATLAB. The most widely-available way to do this is with SSH and X11 forwarding. However the performance of SSH+X11 is often too slow similar to MobaXTerm or Putty. An alternative is to use VNC to start and connect to a remote desktop.

Setup

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, install and configure TigerVNC securely 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.

Windows

Download and run the latest tigervnc64-x.y.z.exe installer. Be sure to uncheck both "Register new TigerVNC Server 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. Configure the default viewer settings by clicking the desktop TigerVNC Viewer icon. In the "VNC Viewer: Connection Details" window that appears click "Options -> Security" then tick all boxes except Encryption None and enter your C:\full\directory\pathto\cacert.pem in the "Path to X509 CA Certificate" field. To save the settings click OK and then click Connect. If Connect is not clicked the settings will not be saved.

MacOS

Download and run the latest tigerVNC-x.y.z.dmg package installer. Configure the default viewer settings by clicking the desktop TigerVNC Viewer icon. In the "VNC Viewer: Connection Details" window that appears click "Options -> Security" then tick all boxes except Encryption None and enter /etc/ssl/cert.pem in the "Path to X509 CA Certificate" field. To save the settings click OK and then click Connect. If Connect is not clicked the settings will not be saved.

Linux

First install TigerVNC viewer with the package manager for your linux version:

Linux Version	Install Command
Debian, Ubuntu	sudo apt-get install tigervnc-viewer
Fedora, CentOS, or RHEL	sudo yum install tigervnc
Gentoo	emerge -av net-misc/tigervnc

Next start TigerVNC by either finding it in the Applications menu or running vncviewer on the command line. In the "VNC Viewer: Connection Details" window that appears click "Options -> Security" then tick all boxes except Encryption None and enter one of the following paths in the "Path to X509 CA Certificate" field.

Linux Version	Path to X509 CA Certificate
Debian, Ubuntu	/etc/ssl/certs/ca-certificates.crt
Fedora, CentOS, or RHEL	/etc/pki/tls/certs/ca-bundle.crt
Gentoo	/etc/ssl/certs/ca-certificates.crt

To save the settings click OK and then click Connect. If Connect is not clicked the settings will not be saved.

Connect

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. VNC is not a heavyweight server, so you can certainly run lightweight sessions on cluster login nodes.

VDI Nodes

gra-vdi.computecanada.ca

Graham has dedicated VDI nodes collectively known as gra-vdi. These nodes provide a full graphical desktop, accelerated OpenGL, and shared access to graham's /home, /project, and /scratch filesystems.

To connect start your desktop VNC viewer (tigervnc) and input the address gra-vdi.computecanada.ca. This should bring up a login screen where you can enter your Compute Canada credentials and login.

As with regular login nodes, the VDI nodes are a shared resource and not intended for doing batch computation (that is what the compute nodes are for) so please only use them for graphics-related tasks. For example: graphical pre-processing such as mesh generation, graphical post-processing such as visualization, or graphical integrated development environments.

If you want to perform computational tasks within a gui please do so on a cluster compute node using the salloc command as described in the Compute Nodes section below. This will ensure the memory and cpu resources on gra-vdi are fully available for interactive graphical visualization purposes by other users when needed.

Login Nodes

To start a remote desktop on a cluster login node follow these steps:

1) Login to a cluster login node from your local laptop:

[laptop:~] ssh cedar.computecanada.ca
[laptop:~] ssh beluga.computecanada.ca
[laptop:~] ssh graham.computecanada.ca

2) Using graham for this example start a vncserver and determine listening port:

 [gra-login1:~] vncserver
   Log file is /home/username/.vnc/gra-login1:3.log

 [gra-login1:~] grep port /home/username/.vnc/gra-login1:3.log
   vncext: Listening for VNC connections on all interface(s), port 5903

3) Open another terminal on your desktop and run:

 [laptop:~] ssh graham.computecanada.ca -L 5901:gra-login1:5903

4) Open another terminal on your desktop and run:

 [laptop:~] vncviewer localhost:5901

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.

1) Starting a VNC server

Before starting your VNC server, login to a cluster (such as cedar) and create an allocation on a compute node using the salloc commmand (a 3hr maximum time limit applies). For 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
[username@cdr768:~/project]

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.
Password:
Verify:
Would you like to enter a view-only password (y/n)? n
xauth:  file /home/username/.Xauthority does not exist
New 'cdr768.int.cedar.computecanada.ca:1 (username)' desktop is cdr768.int.cedar.computecanada.ca:1
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/cdr768.int.cedar.computecanada.ca:1.log

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

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

2) 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 username@cedar.computecanada.ca -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.

3) 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 the TigerVNC vncviewer command to connect to the running VNC server on cdr768. You will be prompted for the VNC password that you setup earlier in order to connect.

[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 http://www.tigervnc.org 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

If you are on a Mac then simply click the TigerVNC Viewer application icon and enter the localhost:port information, for our example it becomes:

Please note the port number in localhost:port specified above (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 a Linux MATE desktop. To launch a terminal, click on the top menu on "Applications -> System Tools -> MATE Terminal". You may also add a shortcut to the top menu by right-clicking on "MATE Terminal" and by clicking on "Add this launcher to panel". Finally, to launch a program, simply invoke the command as you would normally within a Bash session. For example, 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:

module load matlab
matlab

Other

Vncserver password

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 so that the next time you run vncserver you will be prompted to set a new password.

Unlock screensaver

If your screensaver times out and requests a password, enter your cluster account password to unlock it (not your vncserver password). If you are running the MATE desktop and the screen saver will not unlock try running killall -9 .mate-screensaver otherwise open a ticket if problems persist.

Multiple vncservers

To list any vncservers still running on a login node run vncviewer -list. To reconnect to a particular vncserver 1) re-establish a port forwarded tunnel 2) run the vncviewer command again. If a server is no longer needed terminate it with vncserver -kill :display#. To kill all old vncserver run pkill Xvnc -u $USER.

Multiple vncviewers

Its possible to start multiple remote vncviewer connections to an existing vncviewer desktop. For example on a second machine at home while leaving the original vncviewer connection running at the office. To do this requires starting your server with a special option vncserver -AlwaysShared otherwise addtional vncviewer connections will by default close the original vncviewer connection.

Failures to connect

Failure to establish a new vncserver/vncviewer connection maybe a result of an old ssh tunnel still running on your desktop using the same port. To identify and kill them open a terminal window and run ps ux | grep ssh followed by kill PID.

Software

The VDI nodes have special hardware and virtual server configuration and extra layers of software modules compared to cluster Compute Nodes. Therefore before running graphical software on gra-vdi its important to have a high level understanding regarding which software modules are available and will produce the best results before making a selection.

NIX

The nix module on gra-vdi provides open-source software optimized to use accelerated OpenGL whenever possible. To load the nix module do:

[name@gra-vdi4]$ module load nix

The nix and nix-env commands are now in your path to install (and use) nix software packages within your personal nix environment.

Installing software

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, to install QGIS do the following:

[name@gra-vdi4]$ nix search qgis

[name@gra-vdi4]$ nix-env --install --attr nixpkgs.qgis

Your nix environment persists from one login to the next, so you only need to run an install command once. For example:

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

works! In summary whatever software you install today will be available next time you load the nix module.

Building OpenGL applications

For accelerated OpenGL to work, it is necessary to adjust compiled binaries to pre-load an appropriate version of the "vglfaker.so" 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, if 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/libvglfaker.so as the first required library.

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

Note that it is also possible to pre-load vglfaker.so 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 vglfaker.so than that set in LD_PRELOAD will then fail, but it can be used safely in some cases in wrapper scripts.

CVMFS

Compute Canada software modules reside under /cvmfs and are available by default when you log into graham, cedar and beluga cluster. These modules however are not loaded by default when you connect into gra-vdi over tigervnc. To load them open a terminal window and run the following:

[name@gra-vdi4]$ module load CcEnv StdEnv/2016.4
[name@gra-vdi4]$ module avail

all Compute Canada software modules will now be available on gra-vdi identical to the clusters. While these modules should always work reliably when running graphical applications on Compute Nodes some may have stability issues running on gra-vdi such as sudden crashing or strange graphical artifacts including transparent windows or missing menus. To work around such problems use an equivalent package from nix as described in the previous section, better graphics performance may also be realized. While the nix module provides a vast number of optimized/stable open-source packages for gra-vdi it does not provide commercial module equivalents for ansys, comsol or starccm. These can be found by loading the SnEnv module instead:

[name@gra-vdi4]$ module load SnEnv
[name@gra-vdi4]$ module avail

CernVM File System