Tools you need

SSH Clients

Under Linux and Mac OS, command-line ssh clients are mostly already installed, or installable by the package management system of the OS.

Under Windows, several SSH clients are available. Recently, also the command-line SSH tool suite is available on Windows 10 (might be installed). In the same fashion, Cygwin or MobaXterm utilize the command-line SSH tool suite.
However, the most wide spread GUI based SSH tool suite for Windows is still PuTTY.

VNC Clients or WebBrowser

There are several VNC clients available: RealVNC, TightVNC, TigerVNC. The TigerVNC viewer in java was tested to work on several operating systems (Linux, Windows), with the nice features to have (VNC) server side rescaling when the local client window size changes. As we also use currently the TigerVNC server, the TigerVNC client is currently recommended.

Please also consider the noVNC-Mode on the Linux Cluster RVS, which does not require a VNC client, but a web-browser.

General Methodology (Please read first!!)

  1. Login to a login node via SSH
  2. Start the Remote Visualization (RV) job via respective provided tools
  3. Set up a SSH Tunnel
  4. Open locally on your device Viewer/Browser (depending on system and preference)
  5. Once finished, stop the RV job

Linux Cluster - rvsvnc

A normal session might look like the following (lxlogin1 can be replaced by any other Linux Cluster login node).

local> ssh <userID>@lxlogin1.lrz.de
cm2login1> module load rvsvnc
cm2login1> rvsvncstart -w
[INFO] Remote Visualization resources are available!
Submitted batch job 77 on cluster rvs
[INFO] A VNC job is already running (SLURM JOB ID 77 on Cluster rvs)!
[INFO] VNC Viewer Client mode:
       Please issue
         vncviewer -via <userID>@lxlogin1.lrz.de rvs2.cos.lrz.de:5901
       OR:
       Setup a SSH tunnel via:
         ssh -L 12345:rvs2.cos.lrz.de:5901 <userID>@lxlogin1.lrz.de
       and, open locally (on your device) a VNC viewer via
         vncviewer localhost:12345
[INFO] noVNC Webserver mode:
       Please, setup a SSH tunnel via:
         ssh -L 54321:rvs2.cos.lrz.de:6080 <userID>@lxlogin1.lrz.de
       Next, open the following url in a local web browser
         http://localhost:54321/vnc.html?resize=remote

There are several options possible. In any case, open a new terminal (locally). You can now choose:

  1. VNC-Mode: Enter (of course, use your own User ID)

    local> vncviewer -via <userID>@lxlogin1.lrz.de rvs2.cos.lrz.de:5901

    This might not work on all systems. In this case, open a SSH tunnel directly (still locally in new terminal)

    local> ssh -L 12345:rvs2.cos.lrz.de:5901 <userID>@lxlogin1.lrz.de

    As this opens also a session remotely, i.e. you are logged in on the login node, you need to start another terminal locally to issue the VNC client command:

    local> vncviewer localhost:12345

  2. noVNC-Mode: If no VNC client is available, or functional on your system, you can also use a web browser (Firefox/Chromium work well; see below). Open a new SSH tunnel locally

    local> ssh -L 54321:rvs2.cos.lrz.de:6080 <userID>@lxlogin1.lrz.de

    and, afterwards, a browser with the printed URL, here as example: http://localhost:54321/vnc.html?resize=remote. From here, you only need to connect, enter the VNC password. Ready!

Instead of lxlogin1.lrz.de, any other Linux Cluster login node can be used as well!

Once you finished your RV session, just enter

cm2login1> rvsvnckill

Your session will be killed - including all running programs - after the scheduled job time has passed. Please, keep an eye on that! After killing, it takes about half a minute until you can start another RV session.

If you interrupted your session, or lost SSH connection, or whatever conceivable, your RV session will probably still be running. So, you can login again. And issue

cm2login5> rvsvnccheck

in order to see the status of your job, and to retrieve the connection information again.

noVNC Mode

noVNC is based on HTML5 and serves as web socket proxy for a running VNC server. Or, more cogently expressed: You can use a browser instead of a VNC viewer. With the -w option of rvsvncstart, a noVNC web server is started together with the VNC server locally on the RV machine. Once connected via browser (via SSH tunnel), you should see something like this

first screen

Desktop ready to work

We tested noVNC successfully on Linux and Windows for Firefox and Chromium. Edge and Internet Explorer seem to have problems on our tested systems. If you don't need the full functionality of noVNC, and cannot change the browser available on your local system, try vnc_lite.html instead of vnc.html in the URL resulting from the RV job submission above. But easier is to download a browser like Firefox. As they are available also as portable app, you don't need administrator rights.

More Options of rvsvncstart

The module rvsvnc is a fully self-documented environmental module. Use manpage like

cm2login1> man rvsvnc

to obtain an overview of that tool suite. There are actually three tools - rvsvncstart, rvsvnccheck, and rvsvnckill - which comprise the RV job handling workflow.

Each of the command-line tools has a manpage. Or, use command-line option -h

cm2login1> rvsvncstart -h

in order to obtain a short help message - about the function and the command-line options available.

Currently, only rvsvcnstart - the tool to create a RV job - has several command-line options. Amongst others, the user can decide on the job duration

  • --time= (default: 2 hours),
  • -w whether to start also a noVNC web server on the RV machine (default: no web server),
  • --xstartup= to select a user supplied xstartup script (default: system xstartup),
  • --no-vgl to let the VNC server NOT run using Virtual GL (default: VNC server runs using vglrun)

Windows Users

SSH Clients are also available for MS Windows. If you use MobaXterm or Windows 10's own OpenSSH client (CMD), you can essentially follow the guide above.
Here, PuTTY usage is described in the context of the usage of the LRZ remote visualization in some more detail.

Troubleshooting

After rvsvncstart, I don't get information about the SSH connection.

Instead, some error message might appear about a non-running job, or unavailable information. The Slurm scheduler and the job startup mechanism might have latencies. So, the necessary connection information is then not available, yet, when the rvsvncstart script parses for it.
Solution: You can use rvsvnccheck any time later to retrieve the desired information - as long as a job is running, and the job output files are still there, the information is available somewhen. Just one advice: Be patient!

After killing a RV job, I cannot start a new one (immediately). (Limitations)

This is also a related to the latency of the cleaning phase of Slurm, and might last for about half a minute. Furthermore, a user can start only one RV session at a time, and obtains only one node during this session. So, if there is already one job - whether running or pending or whatever - the user can't schedule a new job, yet.
Solution: Please, kill the old job (if not already done), and wait patiently! You can use rvsvnccheck to check, whether the RV resources are again available for you.

The -via option of my VNC client does not work!

Solution: On the Linux-Cluster, the option to use a SSH tunnel is already specified. Use SSH tunnel if -via does not work!

Troubleshooting not related specifically to the RV subsystems

VNC password (What is it? Forgotten?).

The VNC server requires a password to secure the login (via vncviewer or otherwise) from access by other users (what you usually also don't want). If it is not set, yet, you are required to set one on the first usage.
Solution:
Enter a password which is convenient for you to remember, and not so easy to guess by others. And don't use the same password as that of your LRZ account!
If you forgot your password, you can set/change it any time by issuing vncpasswd on any login node. It has effect only on VNC servers started after the change!

Advices and Hints

Public-Private SSH Keys and SSH Agent

For convenience, we recommend the use of public-private key pairs and SSH agent (Pageant under PuTTY).

Add SSH Tunnel to existing OpenSSH connection on command-line

For advanced users: OpenSSH also admits to attach SSH tunnel on an existing SSH connection. Look for escape characters in the SSH documentation. The common way should be to issue <enter> ~C <enter>. Then a ssh> prompt should appear. Now you can simply enter, for instance, -L12345:rvs1.cos.lrz.de:5901 to add a tunnel from your local device port 12345 to rvs1.cos.lrz.de port 5901.
Diagnosing existing tunnels is but not as simple as for PuTTY. The best chance is probably, netstat -tulpn | grep ssh.