Documentation / Tutorials

Using Guacamole with Enclave

This is a step-by-step guide to installing and using Guacamole with Enclave on Linux. Apache Guacamole is a clientless remote desktop gateway, which supports standard protocols like VNC, RDP, and SSH. To make the installation easier, we're going to use Docker, which you can read more about here. Once we're done, the resulting Guacamole server will only be visible to those systems which have an Enclave policy connecting them to the server.

If you'd like to dive more deeply into the installation process, please refer to the following documentation.

Installation

1. To begin with, install Docker. Installation instructions per Linux distro can be found here.

2. Open the terminal and navigate to a directory of your choice using the cd command. Enter mkdir guacamoleCompose to create a folder called guacamoleCompose and run cd guacamoleCompose to make it the current working directory.

3. Run nano docker-compose.yml to create and open an empty file called docker-compose.yml in the nano text editor. Copy and paste into it the YAML file below. Modify both POSTGRES_PASSWORD fields and enter an enrolment key into the ENCLAVE_ENROLMENT_KEY field. Whatever password you choose, its important that both fields match. Once you're done, save and exit by typing ctrl-x followed by y.

   Tip

   You may prefer to use an ephemeral enrolment key. Systems enrolled using an ephemeral enrolment key are automatically removed from your Enclave organisation when they disconnect. By adding a tag to the key, you can also automatically assign the Guacamole server the same DNS name on startup. You can read more about DNS here.

   version: '3.1'
   services:
     guacd:
       container_name: guacd
       image: guacamole/guacd
       restart: always
       volumes:
       - ./drive:/drive:rw
       - ./record:/record:rw
     postgres:
       container_name: postgres_guacamole
       environment:
         PGDATA: /var/lib/postgresql/data/guacamole
         POSTGRES_DB: guacamole_db
         POSTGRES_PASSWORD: [password]
         POSTGRES_USER: guacamole_user
       image: postgres:13.4-buster
       restart: always
       volumes:
       - ./init:/docker-entrypoint-initdb.d:z
       - ./data:/var/lib/postgresql/data:Z
     guacamole:
       container_name: guacamole
       depends_on:
       - guacd
       - postgres
       environment:
         GUACD_HOSTNAME: guacd
         POSTGRES_DATABASE: guacamole_db
         POSTGRES_HOSTNAME: postgres
         POSTGRES_PASSWORD: [password]
         POSTGRES_USER: guacamole_user
       image: guacamole/guacamole
       network_mode: service:enclave-fabric
       restart: always
     enclave-fabric:
       container_name: fabric
       image: enclavenetworks/enclave:latest
       restart: always
       cap_add:
         - NET_ADMIN
       devices:
         - /dev/net/tun
       environment:
         ENCLAVE_ENROLMENT_KEY: [enrolment_key]
       volumes:
         - enclave-config:/etc/enclave/profiles
         - enclave-logs:/var/log/enclave
   volumes:
     enclave-config:
     enclave-logs:
   

4. As above, create a file called prepare.sh and copy into it the text below. This file will initialise the Postgres database for us.

   #!/bin/sh
   #
   # check if docker is running
   if ! (docker ps >/dev/null 2>&1)
   then
     echo "docker daemon not running, will exit here!"
     exit
   fi
   echo "Preparing folder init and creating ./init/initdb.sql"
   mkdir ./init >/dev/null 2>&1
   chmod -R +x ./init
   docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgres > ./init/initdb.sql
   echo "done"
   

5. In the terminal, enter the command chmod +x prepare.sh to allow prepare.sh to be executed as a program. Run it using the command sudo ./prepare.sh.

6. Enter sudo docker compose up -d to build and run the docker containers for the service. Enclave and Guacamole should now be running.

7. Navigate to portal.enclave.io in your browser and identify the Guacamole server; it should have enrolled using ENCLAVE_ENROLMENT_KEY. Make sure the system is approved and connected to your local machine using a Direct Access policy. Modify the ACLs of the policy to restrict inbound traffic to TCP using port 8080 (the port you'll use to connect to Guacamole).

Usage

1. Find the Guacamole server in the Systems list. Click on it, and in the pop-out pane note down the virtual network address.

2. In your web browser, navigate to [YourVirtualNetworkAddress]:8080/guacamole. You should be redirected to the Guacamole login page. If you've registered a DNS name for the server, you can also use [YourDNSName]:8080/guacamole.

3. You're now connected to Guacamole via Enclave. Continue to use Guacamole as you normally would.

---

Having problems? Contact us at support@enclave.io or get help and advice in our community support channels.

Last updated January 26, 2023