Apache Guacamole

Sign in to the AWS Management Console, open the EC2 service, and choose Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Apache Guacamole. Select the SecureAnyCloud listing and choose Select, then choose 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. 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.

Choose Launch instance. First-boot initialisation takes approximately one to two minutes after the instance state becomes Running and the status checks pass. During that time the first-boot service generates the credentials and the services start.

The following command launches an instance from the SecureAnyCloud Apache Guacamole Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing. Replace <key-name> with your EC2 key pair name and <subnet-id> with your subnet ID. Replace <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}]'

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

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. For Apache Guacamole on Ubuntu 24.04, the login user is ubuntu.

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

The file is plain text. It contains 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. Do not commit them to source control.

Confirm that root owns the credentials file and that only root can read it:

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

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

Check that guacd, Tomcat, nginx, MariaDB and the first-boot service 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

Check the deployed components. They 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

Check the listening ports. 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. 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 *:*

Run a quick health check to confirm that nginx serves the Guacamole web application:

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

200

Browse to http://<public-ip>/ from a machine on a network that 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 shows the home screen. This is a fresh instance with no connections defined, so the home screen lists no recent or available connections. You add your first connection in the next step. The user menu in the top right shows the signed-in administrator.

To reach the portal over an encrypted connection, enable HTTPS by following the Let's Encrypt section later in this guide.

You manage Guacamole connections from the administration settings. From the user menu in the top right, choose Settings. Open the Connections tab and choose New Connection.

Give the connection a name, then choose the Protocol. Use RDP for a Windows machine, SSH or Telnet for a Linux host or network device, and VNC for any desktop running a VNC server.

Fill in the Network parameters for the target. At a minimum, enter the hostname or IP address and the port (3389 for RDP, 22 for SSH, 5900 for VNC, 23 for Telnet). Add 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. You can use clipboard integration, file transfer (for RDP and SSH) and on-screen scaling. To end the session, open the Guacamole menu with the keyboard shortcut shown on the connection screen.

Guacamole stores users, groups, connections and permissions in the MariaDB database, and you manage them all 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 SecureAnyCloud support for help wiring these into this image.

The Guacamole configuration tree, GUACAMOLE_HOME, is /etc/guacamole, 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. It also holds the JDBC authentication extension, the MariaDB Connector/J driver, and the session recording and drawing directories. List them with:

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. Both are separate from the operating system disk, so you can resize the configuration and database tiers independently. Confirm the mounts with:

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.

Manage the four services 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.

You can change the administrator password generated on first boot at any time from the web interface. Sign in as guacadmin and 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.

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

Out of the box, nginx serves the portal over plain HTTP on port 80. To serve it over HTTPS with a trusted certificate, point a DNS name at the instance and open port 443 in the security group. Then 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. You can also configure nginx to redirect plain HTTP to HTTPS.

Back up two things. The MariaDB database holds every user, connection and permission. The GUACAMOLE_HOME tree holds the configuration and extensions. Snapshot the two EBS data volumes on a schedule, and 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. Restart tomcat after you apply Java or Guacamole updates.

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.

• 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 your 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.