Graphical access

There are multiple options to run applications with graphical interface (GUI) or simply to get graphical connection to MetaCentrum machines.

We recommend to use OnDemand as a first choice for GUI access.

Apart from OnDemand, there are other methods:

gui module - usage of specific module designed to run graphical jobs,
X-window - low-level solution using only system tools.

gui module - quick start

Using a web browser

The easiest way how to use GUI applications is by initialization of the entire GUI environment in your favourite web browser.

May not work perfectly for all browsers

Access to GUI through web browser may be sensitive to bugs and specific features of individual browsers. Try a different browser if it does not work with your default one.

Start an interactive job

For example,

(BULLSEYE)hoidekr@minos:~$ qsub -I -l select=1:ncpus=2:mem=30gb:scratch_local=40gb -l walltime=5:00:00

Load the gui module and start it

(BUSTER)hoidekr@elmo3-1:~$ module add gui
(BUSTER)hoidekr@elmo3-1:~$ gui start
*****************************************
 Your VNC session has been started.
 The connection details are as follows:
   Remote Host : localhost
   Port        : 10092
   Use SSH tun.: yes
   SSH Server  : elmo3-1.hw.elixir-czech.cz
   SSH User    : hoidekr
   VNC Password: 0x0nldJ8
   Display     : :24
   SSH tunnel  : ssh -TN -f hoidekr@elmo3-1.hw.elixir-czech.cz -L 10092:localhost:10092
*****************************************
      ---- EXPERIMENTAL ----
   URL         : https://gui.metacentrum.cz/hoidekr/elmo3-1/10092/vnc.html?path=hoidekr/elmo3-1/10092/websockify&password=0x0nldJ8&resize=scale&autoconnect=true
*****************************************

Open a browser

Paste the entire URL to your web browser, login with preferred identity provider (IdP) credentials. For example, when you select MetaCentrum as IdP, then use your MetaCentrum username and password.

Login process in a browser

Now the graphical connection to your interactive job is open. You can open an terminal and run any application with GUI using module add command.

Some on the most commonly used applications can be also found in the menu in bottom left corner of the desktop.

Logout in the end

The session will remain open until you log out or until the walltime runs out.

Logout from the session

Using a VNC session

Another easy way how to start GUI is via some VNC client. The following brief tutorial utilizes the TightVNC client.

Start an interactive job

For example,

(BULLSEYE)vorel@minos:~$ qsub -I -l select=1:ncpus=2:mem=30gb:scratch_local=40gb -l walltime=5:00:00

Load the gui module and start it

(BUSTER)vorel@elmo3-4:~$ module add gui
(BUSTER)vorel@elmo3-4:~$ gui start
*****************************************
 Your VNC session has been started.
 The connection details are as follows:
   Remote Host : localhost
   Port        : 11670
   Use SSH tun.: yes
   SSH Server  : elmo3-4.hw.elixir-czech.cz
   SSH User    : vorel
   VNC Password: KtXPCBcl
   Display     : :20
   SSH tunnel  : ssh -TN -f vorel@elmo3-4.hw.elixir-czech.cz -L 11670:localhost:11670
*****************************************
      ---- EXPERIMENTAL ----
   URL         : https://gui.metacentrum.cz/vorel/elmo3-4/11670/vnc.html?path=vorel/elmo3-4/11670/websockify&password=KtXPCBcl&resize=scale&autoconnect=true
*****************************************

Open a VNC connection

In the client interface, fill all required values according to the output of gui start command.

Click on the Connect button and, if necessary, agree with the access to the unknown machine.

You will be asked to fill two passwords. First one is an ordinary MetaCentrum password. Second one is a VNC Password generated by gui start command.

Finally, click on Login button and the GUI session will start.

Logout in the end

The session will remain open until you log out or until the walltime runs out.

Logout from the session

gui module - details

VNC session vs SSH tunneling

When using software with a graphical interface (GUI), the user needs to establish a connection for graphical output between their PC and a Metacentrum machine.

To do this, we use a so-called VNC session (Virtual Network Computing) between a Metacentrum machine (server side) and user's local PC (client side).

However, the protocol that VNC uses to transfer data between a remote server and a local PC is not very secure. That's why a VNC session must be covered by an additional layer of security that encrypts all communication.

As a default choice, we use SSH protocol as a method of encryption. This is so-called SSH tunneling, because the open communication is hidden ("tunneled") by SSH encryption.

Desktop resolution

Please note, that choosing the correct remote desktop resolution may be crucial for a good user experience. The default screen resolution of our VNC server is FHD (1920x1080). It can be changed via the -g option (an argument of gui start command) or scaled using -S option (see below).

The best results can be obtained when local and remote screen sizes are in a ratio 1:1. Otherwise, letter fonts are blurred. I.e. if your display is FHD and you plan run VNC client in fullscreen mode, the result should be fine. However, if you plan to run the VNC in windowed mode, the remote display must be a bit squeezed on your local screen because of window decorations (title bar, slides, frame) resulting in ugly font letters. In such a case it is better to decrease the size of the remote desktop when starting it (-g parameter).

In the case that icons and letter fonts are too small, consider start a smaller remote desktop and scale it either on client side (easy way, usually via some icon or menu checkbox) or on the server side (some VNC clients do not support local scaling) using -S option. I.e. combination of parameters -g 1000x800 -S 2000x1600 will start remote desktop with resolution 1000 x 800 px and scale it twice in X and Y direction. Again, uneven scaling may cause blurred results.

On screens with high resolution, the best results may be achieved simply by choosing bigger xterm font, either from xterm menu (Ctrl+right mouse button - note that Ctrl key is usually implemented as a SW key from menu of VNC client) or by using parameters like:

xterm -fs 16 -fa 'Monospace'

You can also specify xterm font in ~/.Xdefaults file. However, it's beyond the scope of this documentation. To give you an idea of what to expect, can check the following table:

Resolution comparison

-g 3840x2160 window maximized	-g 3840x2160 fullscreen mode	-g 1920x1080 window maximized

-g 1920x1080 fullscreen mode	-g 3840x2160 increased fonts

gui command options

There are several other parameters of gui command you may find useful (see gui --help):

gui start [-g GEOMETRY] [-c COLORS] ... starts a VNC session

    flag -g GEOMETRY ... specifies the required screen geometry (e.g. -g 1280x1024 - default is 1280x768)
    flag -S|--scale ... specifies the scaled geometry of base ("1920x1080") geometry (i.e. 3840x2160), changing the desktop size AND sizes of icons and fonts
    flag -c COLORS ... specifies the required color depth in bits(e.g. -c 16 - default is 24)
    flag -r|--repeat ... turn on keyboard autorepeat (may cause problem in case of slow/laggy connection, default is off)

gui info [-p] ... displays information about running VNC sessions on the local node

    flag -p ... allows to show the VNC session passwords as well

gui traverse [-p] ... displays information about running VNC sessions across all the MetaCentrum nodes

    flag -p ... allows to show the VNC session passwords as well
    warning: processing of this command may take long time

gui stop DISPLAYID ... stops a VNC session (DISPLAYID may be omitted if single session is running)
gui kill DISPLAYID ... kills a VNC session (DISPLAYID may be omitted if single session is running)

Example 1

gui info -p command will show information about running session/s on the actual node (minos1 for this example).

(BULLSEYE)hoidekr@minos1:~$ gui info -p
*****************************************
 Your running VNC sessions are:
   display tunnel machine:port (password)
   :62     SSH    minos36.zcu.cz:10222  (kizFGtpn)
*****************************************

Example 2

gui stop :62 command will terminate running session.

(BULLSEYE)hoidekr@minos1:~$ gui stop :62
The VNC session (display ':62') running at port 10222 has been successfully stopped...

Example 3

gui traverse command will search all nodes and show running sessions (if any).

(BULLSEYE)hoidekr@minos1:~$ gui traverse
*****************************************
 Your running VNC sessions across all the MetaCentrum machines are:
 (Warning: this may take a while...)
   display tunnel machine:port
   !!! NO VNC SESSIONS FOUND !!!
*****************************************

VNC clients

To open a GUI connection through VNC, you'll need to install a VNC client.

We recommend:

Remmina (Linux)

Simple VNC client, where desktop scaling seems to work seamlessly, even without fixed aspect ratio or in full screen mode.

sudo apt-get install remmina

TigerVNC (Linux, Windows, Intel-based macOS)

General purpose VNC viewer, available on many platforms.

sudo apt-get install xtigervncviewer

TightVNC (Linux, Windows, macOS)

Multiplatform VNC viewer TightVNC Java Viewer. It needs to have Java JRE installed. Please note, that build-in SSH tunnelling uses old libraries not supporting modern encryption ciphers, hence separate SSH tunnel will be probably needed.

sudo apt-get install xtightvncviewer

Long-standing desktop session

If you need a long-standing remote desktop session with a possibility to reconnect, you can use the following simple example script (for example, named as file.sh):

#!/bin/bash
#PBS -m abe

module add gui
gui -f start

The user must submit this script as a batch job (with the specification of requested memory, walltime, CPU, ...). E.g.

skirit$ qsub -l walltime=48:0:0 -l select=1:ncpus=2:mem=20gb:scratch_local=40gb file.sh

When the job starts, please log in to any frontend as soon as possible and type the commands:

skirit$ module add gui
skirit$ gui traverse -p
*****************************************
 Your running VNC sessions across all the MetaCentrum machines are:
 (Warning: this may take a while...)
   display tunnel machine:port (password)
   :24     SSH    elmo3-3.hw.elixir-czech.cz:10086  (ZSYPlpxc)
*****************************************

You will see all running VNC sessions with login information.

Use the VNC client for the connection to the running session. If you close the window of the VNC client, the job won't be stopped.

Connect with Putty in Windows

Open a new Putty connection.
Fill in the SSH server address field (e.g. elmo3-3.hw.elixir-czech.cz).
Select Connection > SSH > Tunnels in a side panel.
Enter the PORT number into Source port field (5923 in our example) and set Destination field to localhost:PORT (localhost:5923 in our example).
Choose Add and Open and enter your Metacentrum password.
Use any VNC client to connect to address localhost:PORT (here localhost:5923) and enter the VNC password (n0pTu237 in our example).

Connect with remote desktop: Windows 10 and newer

On Windows 10+ you can use a remote graphical desktop.

Requirements:

Installed X Server environment on your computer with Windows. You can directly download the latest version from this page.
Installed Windows Subsystem for Linux (WSL), version 1 or 2. You can find many tutorials describing this step on the Internet, e.g. https://docs.microsoft.com/en-us/windows/wsl/install-win10. Following steps are tested on Linux distribution Ubuntu 18.04 LTS and Ubuntu 20.04 LTS.
It is best practice to keep the WSL environment updated, you can enforce the update process by:

sudo apt update && sudo apt upgrade
In the WSL environment you have to install a VNC viewer, you can do it by the command:

sudo apt install xtightvncviewer
In case of using WSL1 - append this line at the end of your .bashrc file:

export DISPLAY=:0.0
In case of using WSL2 - append these two lines at the end of your .bashrc file:

export DISPLAY=$(awk '/nameserver / {print $2; exit}' /etc/resolv.conf 2>/dev/null):0 export LIBGL_ALWAYS_INDIRECT=1
Start VcXsrv X Server in your Windows environment, e.g. by clicking on the Icon XLaunch. While using WSL1 you can have all options to its default values. In the case of WSL 2 you should tick the option "Disable access control".
Now you can start WSL (open new terminal), and you can continue by steps described in section Linux.

Connect VNC in Linux

Open a new terminal and type the following command:

$ ssh -TN -f USERNAME@SSH_SERVER_NAME -L PORT:localhost:PORT 
$ ssh -TN -f user123@elmo3-3.hw.elixir-czech.cz -L 5923:localhost:5923 # e.g.

You will be prompted for your Metacentrum password type it and hit Enter. Nothing visible happens, and the terminal prompt stays at your local PC.

In the same terminal run any VNC client. In this example we use xtightvncviewer.

user123@user123-ThinkCentre-E93:~$ xtightvncviewer localhost:PORT
user123@user123-ThinkCentre-E93:~$ xtightvncviewer localhost:5923 # e.g.

You will be prompted for VNC password. Type it and hit Enter. You will see the splash (welcome) window.

You should now see a welcome splash screen:

At the bottom panel of the splash screen on the left, there is an icon for the terminal. Double-click on the icon. A terminal window opens on the splash screen.

To run chosen GUI application, proceed as in a standard interactive job. If you wish, for example, to run ANSYS Workbench, type

module add ansys/18.2
runwb2 # run new Ansys Workbench project

Then the application's GUI interface will appear on your screen.

X-window

X-window is a system for sharing the graphical interface of applications through network. In Metacentrum you can use it for accessing the graphical interface of certain application from the user's desktop.

GUI of unix systems are build on X-Window system, which supposes, that a program and his GUI run on different computers in net. Programs in X-Window system display their GUI on so called X-server which is defined by environment variable DISPLAY.

For example: We are sitting in front of computer named jenicek and start up X-Window program in machine called marenka. If we set variable DISPLAY=jenicek:0 on marenka and if X-server is running in jenicek, execution of a program will be running in a remote computer, but will be displaying on screen in front us and reacting on keyboard an mouse on our table.

There are X-servers for MS Windows, for example Xming, Cygwin/X, X-Win32, Exceed.

Info

This article describes a low-level method of how to run GUI applications on Metacentrum. Only system tools are used and it is therefore always available, but has also a few drawbacks. X-Windows connection will use all available bandwidth, can se used to run a single application only and if the session crashes, it cannot be reconnected. It is fairly useful over a LAN or if you need to run just single application.

X-protocol tunneling

Windows

PuTTy setting for X11 tunnel:

Install Xming. Run it.
Install PuTTy. Run it.
Set the connection parameters in PuTTy according the image on the right and click "Open".
Once you have a terminal window, proceed as a Linux user.

Linux

The simplest way how to use X-window in MetaCentrum is to submit an interactive job with X-protocol tunneling enabled by running both ssh -X and qsub -X:

jenicek$ ssh -X skirit.metacentrum.cz
skirit$ qsub -X -I -l select=1:ncpus=2:mem=4gb:scratch_local=10gb -l walltime=1:00:00 -l matlab=1
konos6$ module add matlab ; matlab

The graphical output should appear on your screen.

If you get error informing about missing rights to use Xserver occurs, logout both from interactive job and a frontend, type

jenicek$ xhost +

and repeat the procedure described above.

Direct connection by X-protocol

Only for specific usecases

Direct connection is faster than tunneling through SSH, but it cannot be used when NAT (network address translation) is applied, as is typical for routers and local networks. This method is therefore limited only to certain situations and cannot be taken as equivalent of X-protocol tunneling.

Direct connection by X-protocol is achieved by setting the DISPLAY variable on the computing machine to the IP address of your personal machine:

jenicek$ ssh skirit.metacentrum.cz
skirit$ qsub -I -l select=1:ncpus=2:mem=4gb:scratch_local=10gb -l walltime=1:00:00 -l matlab=1
konos6$ echo $DISPLAY
konos6$ export DISPLAY=jenicek.ics.muni.cz:0
konos6$ module add matlab ; matlab

On your machine (jenicek.ics.muni.cz in this example) you have to allow incoming connections by

jenicek$ xhost +

and make sure that your X-server does not have disabled incoming connections. For example, the standard setting on Ubuntu is to start X-server with the options -nolisten tcp that disables incoming connections.