VNC - nthu-ioa/cluster GitHub Wiki

VNC is a tool to access graphical desktop running on another machine over the internet. It is a cheaper and more efficient version of remote desktop / screen sharing software.

The main point of VNC on our cluster is to interact with software that has to create graphical windows, for example to do interactive visualisation.

:warning: These instructions are for Linux/Mac users only. They will not work directly for Windows. If you are using windows, see the limited notes at the end. :warning:

This page explains:

How to set up VNC, and how to start and stop VNC sessions
How to connect from another computer to a VNC session on fomalhaut

1. Setting up VNC (one-time only)

If you haven't used VNC before, follow these steps on fomalhaut. You only need to do this once. This also serves as a tutorial for starting and stopping VNC sessions.

1. Set a VNC password

Run vncpasswd. You will be guided through the steps to set your VNC password.

2. Start VNC server to create the default configuration files

Run the vncserver command, which starts a new VNC session with default options. You will see output like the following, with your username instead of sika. You may see extra output about .Xauthority or needing to use a different port. Just ignore that.

[sika@fomalhaut ~]$ vncserver

New 'fomalhaut:1 (sika)' desktop is fomalhaut:1

Creating default startup script /cluster/home/sika/.vnc/xstartup
Creating default config /cluster/home/sika/.vnc/config
Starting applications specified in /cluster/home/sika/.vnc/xstartup
Log file is /cluster/home/sika/.vnc/fomalhaut:1.log

This creates a directory $HOME/.vnc which holds all the configuration and log files related to VNC.

Because you ran vncserver, you have an active VNC session running. This will keep running even if you log out of your shell on fomalhaut. To see a list of your active VNC sessions, use vncserver -list.

[sika@fomalhaut .vnc]$ vncserver -list

TigerVNC server sessions:

X DISPLAY #     PROCESS ID
:1              28438

VNC sessions are identified by their display port number. In the example above, the display port number is 1. To stop a running VNC session, use vncserver -kill with the display port number, like this:

[sika@fomalhaut .vnc]$ vncserver -kill :1
Killing Xvnc process ID 28438

Use that command now to stop your running VNC session.

3. Install a VNC viewer on your machine

This is up to you. Some suggestions for different operating systems are given below.

2. Using VNC

Starting the server on fomalhaut

A typical command to start a new VNC session looks like this

vncserver --geometry 1680x900 :106

There are two options, which specify a screen size ('geometry') and a display port number.

--geometry sets the size of the VNC window on the client (width x height in pixels). Whichever machine you connect from, the "desktop" you will see on the cluster will have these dimensions. The dimensions should be no larger than the those of your client's screen, maybe a bit smaller. This needs some trial and error when you first start using VNC. 1680x900 works OK for a 15" Macbook laptop.

Tip: on a mac or linux machine, you can find the exact dimensions of your display with xdpyinfo:

> xdpyinfo | grep dim
  dimensions:    1680x1028 pixels (445x272 millimeters)

The VNC display port number (:106 in this example) will be used to identify your VNC session. For the rest of these instructions we refer to this as $VNCDISPLAY.

This is a display port number, not a network port. The network port number you use to communicate with VNC is VNCPORT = $VNCDISPLAY + 5900. In this example, VNCPORT is 106 + 5900 = 6006.

If the VNC display port number is already occupied by another program (most likely another VNC session owned by you or someone else), then VNC will automatically choose the first empty port stating from :1 (i.e. :5901).

Connecting to a VNC session

First create a ssh-tunnel from your local machine to the network port $VNCPORT on fomalhaut. In the example above, VNCPORT = 6006. You can write a shell script like the following to do this automatically, which takes $VNCDISPLAY as an input.

#!/bin/zsh
(( vncport = $1 + 5900 ))
echo Tunnelling to VNC port $vncport "(:$1)" on fomalhaut
ssh -L $vncport":localhost:"$vncport fomalhaut

This is the same tunnel procedure used to connect to a jupyter notebook on the cluster.

Finally, you need to use a VNC viewer on your local machine to connect to localhost:$VNCPORT. How exactly will depend on your VNC viewer. You will be prompted for your VNC password.

After entering your password, a window will appear with a basic desktop and terminal. This desktop is running on fomalhaut. You should be able to interact with it using your mouse. You can right-click to open a menu from which you can create new terminals and start applications.

If you run commands that create graphical windows, they should work as normal (for example, you can start firefox and browse the web directly from fomalhaut).

Fluxbox

The default window manager ("desktop") you will see is called Fluxbox. This is much simpler than the standard linux window managers (GNOME and KDE). This is important, because GNOME and KDE consume a lot of resources on fomalhaut. Most of those resources are spent on multimedia applications and fancy visual effects that you only need on your local machine, not on the cluster.

The default Fluxbox is very basic, on purpose. It is highly customizable if you want to spend time making it look nicer or adding features.

If you don't like fluxbox, you can install your own window manager in your homespace. The commands that VNC runs to start the window manager when you make a new session can be changed in the ~/.vnc/xstartup file. If you want to get the default file back, just delete or rename xstartup and run vncserver.

More VNC advice

Copy-and-paste between the VNC window and your local machine

This is usually difficult and requires some experiments with the settings of your VNC viewer.

Log files

Log files associated with a running VNC session are stored under ~/.vnc on fomalhaut. They look like fomalhaut:1.log, where the number is the VNC display port.

VNC Viewers For Linux

Install a VNC viewer client on your local machine (for example, TightVNC or TigerVNC). Whichever client you install, the command to start it will probably be called vncviewer. Different clients have slightly different options.

VNC Viewers For Mac

Download a recent pre-compiled binary (dmg file) for TigerVNC, for example version 1.10.1 from here: https://sourceforge.net/projects/tigervnc/files/stable/1.10.1/

TigerVNC installed via homebrew currently doesn't work well.

You could also use the "Screen Sharing" app built in to macOS. However, this seems to have some issues as well.

VNC Viewers For Windows

TigerVNC claims to work on Windows. If you can confirm this works, please let us know.

Can I use GNOME as the window manager?

We prefer you don't, because GNOME takes a lot more resources than fluxbox, and starts a lot of things that you don't need to run on the cluster (email client, calendar, music player). However, it is possible. Note that GNOME needs a more complicated set of commands in your xstartup file.

Can I use VNC with other machines in the cluster?

Yes, you can run VNC servers on m01 and m02. After you have started the server on one of those machines, you can connect to it by changing the command to create the ssh tunnel as follows (for m01):

ssh -L $vncport":m01:"$vncport fomalhaut

You still point your VNC viewer at localhost:$vncport.