Skip to main content

Apache Guacamole

Apache Guacamole enables web-based remote desktop access to virtual machines. Participants use it to access their VMs directly from the browser — without needing to install any additional software.

Optional

Apache Guacamole is an optional component. Without Guacamole, OpenVLE can still be used to manage VMs and VM templates, but without remote desktop access in the browser.

Architecture​

Apache Guacamole is an open-source software that provides access to remote resources via RDP, VNC, SSH, and other protocols through a standard web browser. The Guacamole stack consists of three components:

ComponentFunction
Guacamole WebWeb interface and API server
guacdConnection daemon that processes the actual remote protocols
Guacamole DBDatabase for users, connections, and configuration

Communication with OpenVLE​

OpenVLE manages Guacamole connections automatically. The backend communicates with the Guacamole server via the Guacamole API and creates, updates, and deletes connections on the following events:

  • Connection created — A new Guacamole connection is automatically created
  • VM deleted — The associated connection is removed
  • Event started/ended — Connections are activated or deactivated accordingly

For this, the OpenVLE backend requires a dedicated user account with administrative permissions in Guacamole.

Requirements​

The OpenVLE backend requires the following information to communicate with Guacamole:

InformationExample
URL of the Guacamole serverhttps://guacamole.example.com
Database type of Guacamolemysql
Username of the OpenVLE accountOpenVLE
Password of the OpenVLE account(secure password)

This information is configured in .env. Additionally, network access from the backend server to the Guacamole server must be possible (HTTPS 443/tcp by default).

Automatic management

After configuring the credentials, no further manual intervention in Guacamole is required. OpenVLE takes over the management of all connections fully automatically.

User authentication in Guacamole​

Guacamole should ideally be connected to the same identity provider (LDAP or OIDC) as OpenVLE. The reason: OpenVLE provisions Guacamole connections for the same usernames that users have in OpenVLE. If Guacamole uses the same IdP, users can log in to the remote desktop directly with their existing credentials.

Manual user management in Guacamole is not necessary — OpenVLE automatically creates Guacamole users if they do not yet exist. Therefore, only authentication needs to be configured in Guacamole, not provisioning.

Further reading​