Apache Guacamole 1.6.0

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened WireGuard VPN & VPN, Proxy and Remote Access AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• When the subscription is active, choose Launch your software.
• Choose One-click launch from AWS Marketplace, or Launch from EC2 Console for the full launch wizard. In Version, choose Apache Guacamole 1.6.0 on Ubuntu 24.04, then choose your Region.
• Pick an instance type (m5.large is recommended; the software charge is $0.04 per vCPU per hour) and your key pair.
• For the security group, allow SSH (22) from your own address and HTTPS (443) from the ranges your users connect from. Nothing else is needed.
• Choose your VPC and a public subnet, or attach an Elastic IP later. Leave the metadata defaults, because the image already requires IMDSv2. Then choose Launch.

Option B: AWS CLI

Run this command on your own workstation. Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the VPC, subnet, key pair and CIDR ranges with your own:

SG=$(aws ec2 create-security-group --group-name apache-guacamole \
  --description "Apache Guacamole" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 443 --cidr <your-client-cidr>
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=apache-guacamole}]'

You do not need --metadata-options, because the AMI already requires IMDSv2.

Connect as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

First boot takes under a minute. It creates the database and the administrator, issues the certificate, starts the services, and then proves that the administrator can sign in. The details are in /root/guacamole-credentials.txt, which only root can read. This command prints everything except the password line:

sudo grep -v '^GUACAMOLE_ADMIN_PASSWORD=' /root/guacamole-credentials.txt

# Apache Guacamole 1.6.0 - generated on first boot by guacamole-firstboot.service.
# Every value below is unique to this instance; nothing was baked into the image. GUACAMOLE_URL=https://52.87.161.224/
# Sign in to Guacamole with this administrator (change the password under Settings > Preferences). GUACAMOLE_ADMIN_USER=sac-admin
# The certificate is self-signed and unique to this instance (browsers warn on the first visit). TLS_CERT_SHA256=51:71:EA:26:DC:3E:F5:98:14:32:82:A4:68:E2:04:28:7E:8C:44:07:C9:1A:92:89:59:5B:0F:7E:BC:C9:75:4F
# New DNS name or Elastic IP:
sudo guacamole-set-host <name-or-ip>
# Self-test:
sudo guacamole-selftest
# Guide: https://secureanycloud.com/stacks/apache-guacamole-1-6-0/

You sign in to Guacamole as sac-admin (GUACAMOLE_ADMIN_USER), a Guacamole administrator. Print the password only when you need it:

sudo sed -n 's/^GUACAMOLE_ADMIN_PASSWORD=//p' /root/guacamole-credentials.txt

All four services and the first-boot unit are active, and only SSH and HTTPS listen on a public address. Run:

systemctl is-active postgresql@16-main.service guacd.service tomcat.service nginx.service guacamole-firstboot.service /usr/local/sbin/guacd -v sudo ss -Htln | awk '{print $4}' | sort -u

active active active active active Guacamole proxy daemon (guacd) version 1.6.0 0.0.0.0:22 0.0.0.0:443 127.0.0.1:4822 127.0.0.1:5432 127.0.0.53%lo:53 127.0.0.54:53 [::]:22 [::]:443 [::ffff:127.0.0.1]:8080

127.0.0.53 and 127.0.0.54 are Ubuntu's local DNS resolver.

The self-test checks that every service is active and that guacd loads its RDP, VNC and SSH plugins. It then signs in as sac-admin through nginx and TLS exactly as a browser does, checks that the account is an administrator, and signs out again. It also proves that no guacadmin account exists. It makes no failed sign-in, which the brute-force ban would count, and it prints no password. Run:

sudo guacamole-selftest

services: postgresql@16-main, guacd, tomcat and nginx are active guacd plugins: rdp(88 params, VERSION_1_5_0) vnc(49 params, VERSION_1_5_0) ssh(42 params, VERSION_1_5_0) sign-in: the per-instance administrator signs in over HTTPS (PostgreSQL data source, ADMINISTER) and signs out defaults: the guacadmin account does not exist SELFTEST_OK

Open GUACAMOLE_URL from Step 2 (for example https://52.87.161.224/). The certificate is self-signed, so the browser warns you on the first visit. Compare the fingerprint it shows with TLS_CERT_SHA256 and continue. Step 9 replaces the certificate with your own. Guacamole shows its sign-in page:

Sign in as sac-admin with GUACAMOLE_ADMIN_PASSWORD. The home page lists your connections. It stays empty until you add one:

Change the generated password to one of your own under Settings > Preferences in the top-right user menu. sudo guacamole-selftest reads the password from the credentials file, so put the new password there too. Otherwise the sign-in check fails.

Open the user menu (top right), choose Settings, then Connections and New Connection. Give the connection a name and choose the protocol. Under Parameters > Network, fill in the target's Hostname and Port (3389 for RDP, 5900 for VNC, 22 for SSH). If you want Guacamole to sign in for the user, also enter the credentials under Authentication. Select Save, and the connection appears on the home page.

The guacd in this image supports RDP, VNC and SSH. The form also lists Telnet and Kubernetes, which this build does not include. Telnet is unencrypted.

The target must be reachable from the instance. On the target, allow RDP, VNC or SSH from the Guacamole instance's security group, not from the internet.

Choose Settings > Users > New User and set a user name and password. Under Connections, tick the connections (or connection groups) that the user may open. Tick Administer system only for people who should manage Guacamole itself.

Give every person their own user. Guacamole records each session under the user's name in Settings > History.

Guacamole also supports time-based one-time passwords (TOTP), LDAP, SAML and OpenID Connect through extensions published by the Apache Guacamole project. Download the 1.6.0 extension and place the .jar in /etc/guacamole/extensions/. Add its settings to /etc/guacamole/guacamole.properties, then restart Tomcat.

Guacamole loads the brute-force extension next to the PostgreSQL extension. Its settings are in guacamole.properties. Five failed sign-ins from one address ban that address for 300 seconds:

sudo ls /etc/guacamole/extensions
sudo grep -E '^ban-' /etc/guacamole/guacamole.properties

guacamole-auth-ban-1.6.0.jar guacamole-auth-jdbc-postgresql-1.6.0.jar ban-max-invalid-attempts: 5 ban-address-duration: 300

nginx passes the real client address and Tomcat trusts it from 127.0.0.1 only. The ban therefore applies to the attacker's address, not to everyone behind the proxy.

nginx, the certificate and the Origin check all name one host. First boot uses the instance's public IPv4 address.

If you stop and start the instance without an Elastic IP, the public address changes. The site then stops answering on the new address until you run the helper. The login message warns you when this happens. With no argument, guacamole-set-host reads the current address from the instance metadata:

sudo guacamole-set-host | tail -3

Host changed from 52.87.161.224 to 52.87.161.224: Guacamole https://52.87.161.224/ Certificate SHA-256: 16:23:A2:FA:D1:F1:59:EB:A5:3C:A6:BA:8A:1C:F5:33:FA:F4:CC:AA:53:23:68:68:F2:C5:7E:D4:C1:62:47:B1 SET_HOST_OK

To use your own name, point a DNS record at the instance and pass the name: sudo guacamole-set-host guac.example.com. Attach an Elastic IP first so that the address never changes.

The helper updates nginx and the URL in the credentials file, issues a new self-signed certificate for that name, reloads nginx, and proves the sign-in again. If nginx rejects the change, the helper restores the previous settings.

After Step 9 has set the name, copy your certificate (full chain) and key over the self-signed pair, then reload nginx:

sudo install -m 0644 fullchain.pem /etc/nginx/tls/server.crt
sudo install -m 0600 privkey.pem /etc/nginx/tls/server.key
sudo nginx -t && sudo systemctl reload nginx

Running guacamole-set-host again later issues a new self-signed certificate, so copy your certificate back afterwards. Alternatively, put an Application Load Balancer with an AWS Certificate Manager certificate in front of port 443, and keep the self-signed certificate between the load balancer and the instance.

Every service of the stack carries an IPAddressDeny rule for the metadata addresses. A connection that someone configures in Guacamole, or anything else a user can influence, therefore cannot reach the instance's credentials. Verify the rule:

for u in postgresql@16-main guacd tomcat nginx; do printf '%-20s %s\n' "$u" "$(systemctl show -p IPAddressDeny --value "$u.service")"; done

postgresql@16-main fd00:ec2::254/128 168.63.129.16/32 169.254.169.254/32 guacd fd00:ec2::254/128 168.63.129.16/32 169.254.169.254/32 tomcat fd00:ec2::254/128 168.63.129.16/32 169.254.169.254/32 nginx fd00:ec2::254/128 168.63.129.16/32 169.254.169.254/32

Every service is gated on /var/lib/sac/data/guacamole.ready, which first boot writes only after this instance's database, configuration and certificate exist. The files that hold secrets are readable only by root and the one service that needs them:

systemctl cat tomcat.service nginx.service | grep '^ConditionPathExists='
sudo stat -c '%a %U:%G %n' /root/guacamole-credentials.txt /etc/guacamole/guacamole.properties /etc/nginx/tls/server.key

ConditionPathExists=/var/lib/sac/data/guacamole.ready ConditionPathExists=/var/lib/sac/data/guacamole.ready 600 root:root /root/guacamole-credentials.txt 640 root:tomcat /etc/guacamole/guacamole.properties 600 root:root /etc/nginx/tls/server.key