Apache Guacamole on AWS User Guide

Overview

This image runs Apache Guacamole, the open source clientless remote desktop gateway. Guacamole lets you reach Windows machines over RDP, Linux and network devices over SSH or Telnet, and any desktop over VNC, entirely from a web browser. There is no client software and no browser plugin to install, so any device with a modern browser becomes a remote desktop client.

Guacamole has two halves, and both are preconfigured in this image. The first is guacd, the native proxy daemon that speaks the remote desktop protocols (RDP, VNC, SSH and Telnet) and relays them to the browser over a WebSocket tunnel. guacd is compiled from the official Apache source release and runs under systemd, listening only on the loopback interface. The second is the Guacamole web application, the guacamole.war web archive, which runs inside Apache Tomcat. The web application authenticates users against a MariaDB database through Guacamole's official JDBC extension, so users, connections and permissions are all stored in the database and managed from the web interface.

Guacamole's web application targets the javax.servlet API, so it runs on Apache Tomcat 9, which this image installs from the official Apache archive. An nginx reverse proxy publishes the portal on the standard web port 80 and forwards to Tomcat on the loopback interface, adding the WebSocket upgrade headers the remote desktop tunnel requires so a browser session works end to end.

The image is secure by default. The JDBC schema seeds a single administrator named guacadmin. On the first boot of every deployed instance a one shot service generates a fresh administrator password and a fresh MariaDB password, unique to that instance, rewrites the database credential in lock step, and writes the administrator user name and password to a root only file. Two instances launched from the same Amazon Machine Image never share a password, and the well known default guacadmin / guacadmin login never works on a deployed instance.

The Guacamole configuration tree, GUACAMOLE_HOME, and the MariaDB data directory each live on their own dedicated EBS data volume, separate from the operating system disk, so the configuration and database tiers can be resized independently of the root volume. The release available in this image is Apache Guacamole 1.6.0.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound port 80 (and optionally port 443 if you enable HTTPS as described later) from the trusted networks that will reach the Guacamole portal
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Apache Guacamole. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Guacamole runs a Java servlet container, a native proxy daemon and a database, and the remote desktop sessions it proxies benefit from memory and network throughput. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound port 80 from the trusted networks that will reach the portal. Do not open these ports to the public internet unless you intend the portal to be publicly reachable. Leave the root volume at the default size or larger; the configuration and database volumes are attached automatically.

Select Launch instance. First boot initialisation takes approximately one to two minutes after the instance state becomes Running and the status checks pass, while the first boot service generates the credentials and the services start.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Apache Guacamole Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 (and optionally 443) as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=guacamole-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Administrator Credentials

Connect over SSH with the key pair you selected and the public IP address from the previous step. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/apache-guacamole-credentials.txt

You will see a plain text file containing the Guacamole portal URL, the administrator user name (guacadmin) and the generated administrator password, along with the database name and credentials. Copy these values somewhere secure such as a password manager or an encrypted vault, and do not commit them to source control.

The credentials file is owned by root and readable only by root:

sudo ls -l /root/apache-guacamole-credentials.txt

-rw------- 1 root root 596 Jun 18 10:44 /root/apache-guacamole-credentials.txt

Step 4: Verify the Server is Healthy

guacd, Tomcat, nginx, MariaDB and the first boot service should all report active:

for u in guacd tomcat nginx mariadb guacamole-firstboot; do printf "%s: " "$u"; systemctl is-active "$u"; done

guacd: active
tomcat: active
nginx: active
mariadb: active
guacamole-firstboot: active

The deployed components are guacd 1.6.0, the OpenJDK 21 runtime, and Apache Tomcat 9, which the Guacamole web application requires:

guacd -v
java -version

Guacamole proxy daemon (guacd) version 1.6.0
openjdk version "21.0.11" 2026-04-21

nginx listens on port 80 and forwards to the Guacamole web application on Tomcat, which is bound to port 8080. guacd listens on the loopback interface on port 4822, and MariaDB on the loopback interface on port 3306, so neither the proxy nor the database is exposed off the instance:

sudo ss -tlnp | grep -E ':80 |:8080 |:4822 |:3306 '

LISTEN 0  511          0.0.0.0:80       0.0.0.0:*
LISTEN 0  80         127.0.0.1:3306     0.0.0.0:*
LISTEN 0  4096       127.0.0.1:4822     0.0.0.0:*
LISTEN 0  100              *:8080            *:*

A quick health check confirms the Guacamole web application is being served through nginx:

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/guacamole/

200

Step 5: Open the Guacamole Portal

Browse to http://<public-ip>/ from a machine on a network the security group allows. The root path redirects to the Guacamole portal at /guacamole/. Sign in as the guacadmin user with the password from the credentials file.

After you sign in, Guacamole presents the home screen. Because this is a fresh instance with no connections defined yet, the home screen lists no recent or available connections; you will add your first connection in the next step. The user menu in the top right shows the signed in administrator.

To enable HTTPS so the portal is reached over an encrypted connection, follow the Let's Encrypt section later in this guide.

Step 6: Add Your First Connection

Guacamole connections are managed from the administration settings. From the user menu in the top right choose Settings, then open the Connections tab and choose New Connection.

Give the connection a name, then choose the Protocol: RDP for a Windows machine, SSH or Telnet for a Linux host or network device, or VNC for any desktop running a VNC server. Fill in the Network parameters for the target, which at a minimum is the hostname or IP address and the port (3389 for RDP, 22 for SSH, 5900 for VNC, 23 for Telnet), along with any authentication parameters such as a username and password for the target. Save the connection.

Return to the home screen and select the connection you just created. Guacamole opens the remote desktop or terminal session in the browser tab, tunnelled through guacd. From here you can use clipboard integration, file transfer (for RDP and SSH), and on screen scaling. To end the session, use the Guacamole menu, which you open with the keyboard shortcut shown on the connection screen.

Step 7: Manage Users and Permissions

Guacamole stores users, groups, connections and permissions in the MariaDB database, all managed from the web interface. Open Settings and the Users tab to add users, set their passwords, and grant them access to specific connections. The administrator created on first boot, guacadmin, has full administrative rights.

Create a dedicated, non administrative user for each person who needs remote access, grant each user only the connections they require, and reserve the guacadmin account for administration. Guacamole also supports LDAP and SAML single sign on and TOTP two factor authentication through additional extensions; contact cloudimg support for help wiring these into this image.

Step 8: Filesystem and Service Layout

The Guacamole configuration tree, GUACAMOLE_HOME, is /etc/guacamole, which is a symbolic link to /opt/guacamole on a dedicated data volume. It holds guacamole.properties (which points the web application at the database and at guacd), the JDBC authentication extension, the MariaDB Connector/J driver, and the session recording and drawing directories:

ls -la /etc/guacamole/
ls /opt/guacamole/extensions/ /opt/guacamole/lib/

drwxr-xr-x 2 tomcat tomcat 4096 drawings
drwxr-xr-x 2 tomcat tomcat 4096 extensions
-rw-r----- 1 root   tomcat  508 guacamole.properties
drwxr-xr-x 2 tomcat tomcat 4096 lib
drwxr-xr-x 2 tomcat tomcat 4096 recordings

guacamole-auth-jdbc-mysql-1.6.0.jar
mariadb-java-client.jar

The configuration tree on /opt/guacamole and the MariaDB data directory on /var/lib/mysql are each mounted on their own dedicated EBS volume, separate from the operating system disk, so the configuration and database tiers can be resized independently:

df -h /var/lib/mysql /opt/guacamole

Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme1n1     20G  127M   19G   1% /var/lib/mysql
/dev/nvme2n1     20G   12M   19G   1% /opt/guacamole

The web application itself, guacamole.war, is deployed under Apache Tomcat in /opt/tomcat, and guacd is installed under /usr/local.

Step 9: Start, Stop, and Check Status

The four services are managed with systemctl. guacd is the protocol proxy, tomcat runs the Guacamole web application, nginx is the reverse proxy on port 80, and mariadb is the database:

sudo systemctl status guacd
sudo systemctl restart tomcat
sudo systemctl restart nginx

If you change guacamole.properties or add an extension under /opt/guacamole/extensions, restart tomcat so the web application picks up the change.

Step 10: Rotate the Administrator Password

The administrator password generated on first boot can be changed at any time from the web interface. Sign in as guacadmin, open the user menu in the top right, choose Settings, open the Preferences tab, and use the Change Password form. Guacamole updates the salted password hash in the database immediately, and the old password stops working.

You can also reset the password from the command line if you are locked out. Contact cloudimg support for the supported database procedure, which rewrites the salted SHA-256 hash that Guacamole stores in the guacamole_user table.

Step 11: Enable HTTPS with Let's Encrypt

The portal is served over plain HTTP on port 80 by nginx out of the box. To serve it over HTTPS with a trusted certificate, point a DNS name at the instance, open port 443 in the security group, and install a Let's Encrypt certificate with certbot:

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

certbot obtains the certificate, edits the nginx server block to listen on 443 with the certificate installed, and sets up automatic renewal. After it completes, the portal is reachable over HTTPS at your domain, and you can configure nginx to redirect plain HTTP to HTTPS.

Step 12: Backups and Maintenance

The state worth backing up is the MariaDB database, which holds every user, connection and permission, and the GUACAMOLE_HOME tree, which holds the configuration and extensions. Snapshot the two EBS data volumes on a schedule, and additionally dump the database for a portable backup:

sudo mysqldump --single-transaction guacamole_db | gzip > guacamole_db-$(date +%F).sql.gz

Keep the operating system patched with sudo apt-get update && sudo apt-get upgrade, and restart tomcat after applying Java or Guacamole updates. Because the data tiers are on dedicated volumes, you can grow them with an EBS volume modification and an online filesystem resize without touching the root volume.

Step 13: Security Recommendations

• Restrict the security group so that port 22 is reachable only from your management network and port 80 (or 443) only from the networks that need the portal
• Enable HTTPS as described in step 11 so credentials and session traffic are encrypted in transit
• Create a dedicated non administrative Guacamole user for each person and grant least privilege on connections; reserve guacadmin for administration
• Rotate the administrator password from the Preferences page after first sign in, and store it in a password manager
• Consider enabling TOTP two factor authentication or LDAP/SAML single sign on for the portal
• Keep the operating system, Tomcat and Guacamole patched

Screenshots

The Apache Guacamole sign-in page, served on port 80 through the nginx reverse proxy:

The Guacamole home screen, where signed in users select the RDP, SSH, VNC and Telnet connections available to them:

The Guacamole administration settings, where connections, users, groups and permissions are managed:

Support

cloudimg provides 24/7 technical support for this image, covering Guacamole deployment, upgrades, RDP, SSH, VNC and Telnet connection configuration, LDAP and SAML single sign on, TOTP two factor authentication, session recording, performance tuning and database administration. Contact the cloudimg support team through the channel listed on your AWS Marketplace subscription.