Guacd Connector - BYUHPC/7lbd GitHub Wiki

Guacamole Connector

Overview

This article describes the Guacamole connector implementation for the 7lbd project. The 7lbd project offers three different connector options for accessing Windows virtual desktops, with the Guacamole connector being one of these three available methods.

The Guacamole connector provides browser-based access to Windows virtual desktops with good performance through Open OnDemand.

Core Components

Client Side

Users access the Windows desktop through a standard web browser. The 7lbd Guacamole client is based off of the Apache Guacamole project. 7lbd does not use a full Guacamole server, but instead uses a custom coded implementation of Guacamole-lite. This is a very light-weight version of guacamole that just provides a connection to a single host without any of the organizational overhead of the full system.

All communication in Guacamole occurs over HTTPS, with 2FA authentication enforced by the Open OnDemand server. A token provided in the view.html.erb on the Open OnDemand card is also required to start the conversation. The client's browser loads Guacamole's JavaScript client to render the Windows desktop interface and transmit user interactions. The client JavaScript files are installed as part of the 7lbd Guacamole build process.

Open OnDemand Server

The Open OnDemand server functions as both the authentication gateway and reverse proxy for the system. It authenticates users with 2FA, allows them to submit and manage Windows VM jobs through a web interface, and securely routes web traffic between the user's browser and compute nodes where the Windows VMs operate.

Compute Node Environment

When a job is scheduled on a compute node, several integrated components work together:

  • Network Namespace: An isolated network environment created by the slurm_iso_netns plugin. This containment prevents the Windows VM from accessing external networks while allowing controlled internal communications.

  • Windows VM: A QEMU-based Windows virtual machine that uses an overlay file in /tmp for temporary session changes. This approach preserves the base VM image while allowing user customization during their session.

  • Samba Server (SMBD): Provides file sharing capabilities between the user's HPC environment and the Windows VM, allowing access to data files and storage.

  • Guacamole Components: Two key elements facilitate the remote desktop connection:

    • A Node.js server (guacd_connector.js) that handles WebSocket connections from the user's browser
    • The guacd service running in an Apptainer container that translates between the Guacamole protocol and RDP to communicate with the Windows VM

Workflow and Data Flow

Session Initialization

  1. The user authenticates to Open OnDemand with 2FA credentials.
  2. Upon submitting a Windows VM job request, Slurm schedules the job on an available compute node.
  3. The spank_iso_netns plugin establishes an isolated network namespace with a randomly assigned communication port for Guacamole.
  4. Within this namespace, the system launches the Windows VM with a temporary overlay file, starts the SMBD server for file access, and initializes the Guacamole connector and guacd apptainer container. 7lbd Guacd Architecture-2(1)

Connection Establishment

When the user accesses their job through the Open OnDemand interface:

  1. The browser loads Guacamole's client-side JavaScript and receives a session token.
  2. A WebSocket connection is established with this session token through the Open OnDemand reverse proxy to the guacd_connector.js Node.js connector. All of the Guacamole session details are contained in a separate encrypted token that the browser passes on to the connector.
  3. The Guacamole connector communicates with the guacd container, which connects to the Windows VM via RDP.
  4. The Windows desktop is rendered in the user's browser, with all interactions securely transmitted back and forth.

Session Termination

When the job completes or times out:

  1. All processes within the network namespace are terminated.
  2. The temporary overlay file containing session changes is deleted.
  3. Resources are released back to the compute node.

Security Architecture

The system implements multiple security layers:

  • Isolated network namespaces prevent Windows VMs from accessing external networks or other compute resources.
  • Two-factor authentication protects user access.
  • HTTPS encryption secures all web traffic.
  • RDP port 3389 is never exposed to network (remains inside network namespace)
  • Guacd port 4822 is never exposed to network (remains inside network namespace)
  • Token required to start conversation with 7lbd connector
  • Temporary overlay files ensure VM instances start fresh for each session.
  • The spank_iso_netns plugin temporarily elevates privileges in the job only for essential administrative components. Users cannot run code with elevated privileges.

Configuration

Enable/disable Guacamole access in before.sh.erb:

export guacd_rdp_enabled=1

Setting guacd_rdp_enabled=1 enables Guacamole client access, while guacd_rdp_enabled=0:

  • Disables guacd_rdp.sh script from running as part of the Open OnDemand job
  • Removes "Web" button from job card interface