Interactive graphical sessions with VNC¶

VNC provides a full graphical desktop on a compute node, which is more responsive and reliable than X11 forwarding over SSH. It is the recommended way to run graphical applications (visualization tools, GUIs, IDEs) interactively on Hyperion.

The session runs inside a SLURM job, so it is confined to the resources you request and subject to the same QoS limits as any other job.

Step 1: Set a VNC password (first time only)¶

Before using VNC for the first time, set a password. Request a quick interactive session and run vncpasswd:

salloc --qos=test --time=00:10:00 srun --pty bash
/opt/TurboVNC/bin/vncpasswd

You will require a password to access your desktops.

Password:
Verify:
Would you like to enter a view-only password (y/n)? n

This password is stored in ~/.vnc/passwd and will be required every time you connect to a VNC session.

Step 2: Submit the batch script¶

Save the following as vnc_session.slurm:

#!/bin/bash
#SBATCH --qos=regular
#SBATCH --job-name=vnc_session
#SBATCH --partition=general
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --mem=16gb
#SBATCH --time=04:00:00
#SBATCH --output=%x.%j.out
#SBATCH --error=%x.%j.err

module load DIPC-Utils

vncserver-start

Submit it:

sbatch vnc_session.slurm

If you are not familiar with the #SBATCH flags, the SLURM reference explains each directive in detail.

Step 3: Check the log¶

Wait for the job to start running:

squeue -u $USER

Once the state changes to R (running), read the output file:

cat vnc_session.<JOBID>.out

You will see something like this:

==============================================================
VNC + noVNC Server Started Successfully
==============================================================

  Hostname:        hyperion-215
  VNC Display:     :1
  VNC Port:        5901
  WebSocket Port:  6081

==============================================================
Option 1: Connect via Web Browser (noVNC)
==============================================================

1. Open an SSH tunnel from your local machine:

   ssh -L 6081:hyperion-215:6081 <username>@hyperion.sw.ehu.es -N

2. Open in your web browser:

   http://localhost:6081/vnc.html

==============================================================
Option 2: Connect via VNC Client (TurboVNC, RealVNC, etc.)
==============================================================

1. Open an SSH tunnel from your local machine:

   ssh -L 5901:hyperion-215:5901 <username>@hyperion.sw.ehu.es -N

2. Connect your VNC client to:

   localhost:5901

==============================================================

The log gives you two connection options. Both require an SSH tunnel.

Step 4: Create the SSH tunnel and connect¶

ssh -L 6081:hyperion-215:6081 <username>@hyperion.sw.ehu.es -N

http://localhost:6081/vnc.html

ssh -L 5901:hyperion-215:5901 <username>@hyperion.sw.ehu.es -N

For more details on SSH tunneling, see the SSH tunneling section in the connection guide.

Multiple sessions¶

You can launch several VNC sessions simultaneously, even on the same node. Each session gets a different display (:1, :2, etc.) and separate ports for VNC and websockify. The system keeps each session isolated automatically, so there are no conflicts between them.

Customizing the desktop¶

By default, VNC sessions use the system-provided desktop startup script, which launches a full XFCE desktop. No additional configuration is needed.

If you want to customize the desktop startup, you can create your own script at ~/.vnc/xstartup.turbovnc. When this file exists and is executable, it takes priority over the system default.

If you create a custom xstartup.turbovnc, make sure it includes at least:

• A per-session XDG_RUNTIME_DIR that includes the display number, to avoid conflicts between multiple sessions:

  export XDG_RUNTIME_DIR="/tmp/runtime-$(id -u)-${DISPLAY#:}"
  mkdir -p "$XDG_RUNTIME_DIR"
  chmod 700 "$XDG_RUNTIME_DIR"
  

• A wait for the X server socket before launching the window manager, to avoid race conditions:

  DISPLAY_NUM="${DISPLAY#:}"
  while [ ! -e "/tmp/.X11-unix/X${DISPLAY_NUM}" ]; do
      sleep 0.1
  done
  

To revert to the system default at any time, simply remove or rename your custom script:

rm ~/.vnc/xstartup.turbovnc

Expected log warnings¶

The VNC log file (~/.vnc/<hostname>:<display>.log) may show warnings like the ones below. These are normal and do not indicate any problem:

Troubleshooting¶

See also¶