Apache Guacamole is a clientless remote desktop gateway that gives you access to Project-based Virtual Machines (VMs) to perform computational analyses on your Project data. Guacamole supports standard protocols like VNC, RDP, and SSH. To learn more about the application, visit the Guacamole documentation and administration guide.

How it works

After the Guacamole application and the VMs have been set up by a Platform Administrator, Project members can request access to the Guacamole-connected VMs. After access is granted, Project members can fetch data from the Core storage, perform computational workflows on the data inside the VM, then write the derivative outputs back to the Core where other Project members can access them.

Prerequisites

• Project Collaborator role or higher.
• Guacamole application and connected virtual machines pre-configured for the Project by the Platform Administrator. See Getting Access to Guacamole.
• Workspace VM-specific credentials to login at VM(s). See Management of Workspace VM-specific credentials.

Data Stewardship

Users are reminded to abide by the Platform Terms of Use and any Project-specific restrictions when using Workspace tools to access data and code.

Getting Access to Guacamole

1. Launch your Project and click Guacamole in the workspace icon group.

   1. If you launch Guacamole and receive a notice that it hasn’t been deployed for your project, please contact your Platform Administrator.
   2. After the Platform Administrator has deployed Guacamole as a workspace tool for your Project, you can request access to the Guacamole-connected VMs. Every project member must complete this step to initialize their identity in the Guacamole system.
2. In the pop-up window, enter a message to the Project Administrator containing the details of your access request, then click Send Request.
3. A message confirms the request has been sent. Project Administrators receive a notification about your request in the portal notification system.

After the Project Administrator receives the notification and sets up the requested access to the Guacamole-connected VM(s), you can use Workspace VM(s) via Guacamole with your Workspace VM-specific credentials (see Management of Workspace VM-specific credentials).

Management of Workspace VM-specific credentials

Login to Workspace VMs via Guacamole requires your Workspace VM-specific credentials, i.e. username and password:

• Username: Your EBRAINS username
• Password: A password specific for login on Workspace VMs within the HDC (see Workspace VM-specific password)

Please note: The scope of your Workspace VM-specific credentials is platform-wide, i.e. they are valid for all VMs within the HDC to which you have access.

Workspace VM-specific password

You can create, change, and reset your Workspace VM-specific password via the HDC platform.

Create or Reset your Workspace VM-specific password

For the initial creation of your Workspace VM-specific password, or to reset it at any time:

1. Open your Account page in the HDC platform.
2. Depending on whether you are generating your Workspace VM-specific password for the first time, or are resetting it after initial creation, click on the Generate VM Password or Reset VM Password button, respectively (see below, which shows the Reset VM Password button). Please note: This button will be disabled for your account until a Project Admin approved your Guacamole access request.
   
3. A pop-up window will prompt you to confirm the generation or reset of your VM-specific password:
   1. Click on Cancel to abort the process.
   2. Click on Generate VM Password or Reset VM Password, respectively, to confirm the action
      
4. Once you confirmed the action, a new pop-up window will open and display your new Workspace VM-specific password to you. Please make sure to save it appropriately, as you won´t be able to view it again once you close this pop-up window. This randomly created password consists of lower case letters only. You will also receive a notification via email that your Workspace VM-specific password has been reset.  
   
5. You can now use this password to login to all Guacamole Workspace VMs you have access to within the HDC platform. We highly recommend changing it after your first login, see Change your Workspace VM-specific password below for more information.

Change your Workspace VM-specific password

In order to change your Workspace VM-specific password, please login to a Workspace VM (see Launching a Guacamole VM connection, and Establishing a Desktop VM Connection or Establishing a Command Line VM Connection, respectively).

a) Change your VM-specific password via a Desktop VM Connection:

1. After logging in to a Desktop VM using your current Workspace VM-specific credentials, open the Settings application.
2. One the left-hand menu click on Users.
3. Make sure your account is selected and then click in the Password field in the "Authentication & Login" section.
4. A pop-up will open and prompt you to confirm this action by providing your current password (i.e. your current Workspace VM-specific password), and to specify the new one. The new password must be at least 8 characters long.
5. Confirm to change your password by clicking on Change.

b) Change your VM-specific password via a Command Line VM Connection:

1. After logging in to a Command Line VM using your current Workspace VM-specific credentials, enter the command passwd
2. You are now prompted to provide your current Workspace VM-specific password.
3. Next, you are prompted to provide your new password. The new password must be at least 8 characters long.
4. You are prompted to confirm the new password by providing it again.
5. A message in the terminal will notify you about the successful update of your password.

After you changed your Workspace VM-specific password, the new password will be valid for all Workspace VMs within the HDC that you have access to.

Launching a Guacamole VM Connection

After the first-time setup has been completed, you can start using Guacamole to access your Project Virtual Machines (VMs). Both Desktop and Command Line Interface VM connections are possible, depending on which VMs have been deployed for the Project and which VMs you have access to.

1. Launch your Project and click Guacamole in the workspace icon group.

   1. If you have access to both Desktop and Command Line Interface VM connections, the Connections screen lists the available VMs. Each VM connection is identified by a name and ID number indicating
      whether it is a Desktop or Command Line connection. Click a VM connection to initiate it.
      
      
   2. If you only have access to either a Desktop connection or a Command Line Interface connection, the relevant login screen (Desktop or Command Line Interface) appears.
2. Follow the instructions for establishing a Desktop or Command Line Interface VM connection.

Establishing a Desktop VM Connection

1. On the Desktop login screen, enter your VM-specific credentials (see Management of Workspace VM-specific credentials), then click OK. 
2. The VM connection is established.
3. After connecting, you can begin working in your Desktop VM. To launch a Linux terminal, see Launching a Linux Terminal inside a Desktop VM.

Note: We recommend to change your VM-specific password upon first login to the VM. See Change your Workspace VM-specific password.

Establishing a Command Line VM connection

1. On the Command Line login screen, enter your VM-specific credentials (see Management of Workspace VM-specific credentials), .
2. The VM connection is established.

Note: We recommend to change your VM-specific password upon first login to the VM. See Change your Workspace VM-specific password.

Launching a Linux Terminal inside a Desktop VM

After successfully logging into a Desktop VM, the default desktop is displayed. To launch the pre-installed Linux applications such as a standard terminal,

1. Click Activities in the upper left corner.
2. Enter terminal in the search box.
3. The terminal launches in a new window.

Command Line Interface operations with different HDC zones

The Command Line Interface is deployed within each Workspace VM as extension resource. The file operations permitted by the Command Line Interface depend on the zone you want to interact with, as shown in the table below:

Copyright © 2023-2024 Indoc Systems.

HealthDataCloud is powered by Pilot technology, a product of Indoc Systems.