Running Interactive Jobs Through a VNC Server¶

Virtual Network Computing (VNC) is a powerful tool for High-Performance Computing (HPC) environments like Hyperion. It allows users to run interactive jobs on remote servers with a graphical desktop environment. This capability is particularly beneficial when tasks involve graphical applications or require a desktop interface.

When you launch an interactive job through VNC on Hyperion, you are allocated a virtual desktop session on the server. This session is confined to the resources (CPU, memory, etc.) you request in your batch script. It means that all processes run within this VNC session can only utilize the resources that you've specifically allocated for that job.

Initial Setup: Setting a VNC Server Password¶

Before using the VNC server for the first time, it is essential to set a password for accessing your VNC desktops. This step ensures that your VNC sessions are secure and only accessible by you or those with the password.

1. Running VNC Server Interactively: The first time you run the VNC server, do it interactively (through salloc or srun, not through a batch script) to set your password. You can do this by executing /opt/TurboVNC/bin/vncserver in the terminal.

2. Setting the Password:

   • Upon running vncserver, you will be prompted to enter a password. This password will be required every time you connect to your VNC session.
   • You will also be asked if you want to set a view-only password. Typically, you can choose 'n' for no unless you have specific requirements for a view-only session.

   You will require a password to access your desktops.
   
   Password: 
   Verify:   
   Would you like to enter a view-only password (y/n)? n
   

3. Confirmation of Startup: After setting the password, you will see a confirmation message indicating that the VNC server has started, including details about the display number and log file location:

   Desktop 'TurboVNC: hyperion-XXX:1 (username)' started on display hyperion-XXX:1
   
   Starting applications specified in /opt/TurboVNC/bin/xstartup.turbovnc
   Log file is /home/username/.vnc/hyperion-XXX:1.log
   

Setting Up Your Environment¶

Before you start using VNC, ensure that you have the necessary setup on your home directory:

1. VNC Startup Script: You must have a VNC startup script named xstartup.turbovnc in your ~/.vnc directory. This script initializes the desktop environment for your VNC session. Here's an example that starts the XFCE Desktop Environment:

   #!/bin/sh
   
   xrdb $HOME/.Xresources
   startxfce4 &
   

If this file does not exist, create it with the above contents. The script startxfce4 launches the XFCE Desktop, providing a full desktop experience.

Running Interactive Jobs Through a VNC Server¶

To start an interactive job on Hyperion using a VNC server, follow these steps:

• Preparing the Batch Script: Write a SLURM batch script to request the necessary resources. Here's an example script:

  #!/bin/bash
  #SBATCH --qos=regular
  #SBATCH --job-name=VNCJob
  #SBATCH --cpus-per-task=1
  #SBATCH --ntasks=4
  #SBATCH --mem=16gb
  #SBATCH --time=01:00:00
  
  vncserver-start
  

This script requests 4 CPUs, 16 GB of memory, and sets the job duration to 1 hour.

• Starting the VNC Server: Submit your batch script to SLURM using the sbatch command. Once the job starts, the VNC server will be initiated on the compute node, and connection details will be provided in the job's output file:

  Starting TurboVNC server...
    VNC server started on display :1 (port 5901)
  Starting websockify...
    websockify started (PID: 12345, port: 6081)
  
  ==============================================================
  VNC + noVNC Server Started Successfully
  ==============================================================
  
    Hostname:        hyperion-215
    VNC Display:     :1
    VNC Port:        5901
    WebSocket Port:  6081
  
  ==============================================================
  Option 1: Connect via Web Browser (noVNC) - No client needed
  ==============================================================
  
  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
  
  ==============================================================
  
  Log files:
    VNC:        /home/username/.vnc/hyperion-215:1.log
    websockify: /home/username/.vnc/websockify-1.log
  
  ==============================================================
  

Connection Methods¶

The following diagram illustrates how the VNC connection works, showing the data flow from your local machine through the SSH tunnel to the compute node:

You have two options to connect to your VNC session. Choose the one that best fits your needs:

Option 1: Web Browser Connection (noVNC)¶

This is the easiest method as it requires no additional software installation. You can connect directly from your web browser.

Steps¶

1. Establish SSH Tunnel: Open a terminal on your local machine and create the tunnel using the WebSocket port from your job output:

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

   Note

   Replace 6081 and hyperion-215 with the actual values from your job output.

2. Open Browser: Navigate to the following URL in your web browser:

   http://localhost:6081/vnc.html
   

3. Connect: Click the "Connect" button and enter your VNC password when prompted.

Browser Compatibility¶

noVNC works with all modern browsers: Google Chrome, Mozilla Firefox, Microsoft Edge, and Safari.

Windows Users¶

You can create the SSH tunnel using PowerShell:

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

Or using PuTTY:

1. Open PuTTY and enter hyperion.sw.ehu.es as the host
2. Go to Connection → SSH → Tunnels
3. Add a new forwarded port: Source port = 6081, Destination = hyperion-215:6081
4. Click "Add" and then "Open" to connect

Option 2: VNC Client Connection¶

For better performance, especially with graphics-intensive applications, you can use a dedicated VNC client.

Steps¶

1. Establish SSH Tunnel: Create a tunnel using the VNC port (not the WebSocket port):

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

   Note

   Replace 5901 and hyperion-215 with the actual values from your job output.

2. Connect with VNC Client: Open your VNC client and connect to:

   localhost:5901
   

Recommended VNC Clients¶

TurboVNC (Recommended)¶

TurboVNC is optimized for high-performance remote desktop and is available for Linux, macOS, and Windows. Download from: https://turbovnc.org

Other Clients¶

• RealVNC - Available for all major platforms
• TightVNC - Free and open-source
• macOS: Built-in Screen Sharing (connect to vnc://localhost:5901)

Quick Reference¶

noVNC (Browser) Connection¶

# 1. Create SSH tunnel (use WebSocket port from job output)
ssh -L 6081:hyperion-XXX:6081 <username>@hyperion.sw.ehu.es -N

# 2. Open browser
http://localhost:6081/vnc.html

VNC Client Connection¶

# 1. Create SSH tunnel (use VNC port from job output)
ssh -L 5901:hyperion-XXX:5901 <username>@hyperion.sw.ehu.es -N

# 2. Connect VNC client to
localhost:5901

Troubleshooting¶

Connection refused¶

• Verify the SSH tunnel is active (the terminal running the ssh command should remain open)
• Check that you're using the correct port numbers from your job output
• Ensure your job is still running: squeue -u $USER

Black screen after connecting¶

• Wait a few seconds for the desktop environment to initialize
• Check that ~/.vnc/xstartup.turbovnc exists and is executable: chmod +x ~/.vnc/xstartup.turbovnc

Password not accepted¶

• Reset your VNC password by running /opt/TurboVNC/bin/vncpasswd interactively on a compute node

noVNC shows "Disconnected"¶

• Refresh the browser page
• Check the websockify log for errors: cat ~/.vnc/websockify-<display>.log
• Try a different browser

VNC server won't start¶

• Check the VNC log file: cat ~/.vnc/<hostname>:<display>.log
• Remove stale lock files if you own them: rm ~/.vnc/*.pid
• If the job ended unexpectedly, the next job run will automatically clean up orphaned sessions

Port already in use¶

• This usually resolves automatically as TurboVNC assigns the next available display number
• If the problem persists, check for orphaned VNC processes: ps -u $USER | grep vnc