Apache Guacamole: Browser-Based RDP, SSH and VNC Gateway

Apache Guacamole is a clientless remote desktop gateway. You open a web page, log in, and get RDP (Windows), SSH or VNC sessions inside the browser, with no client software on the device you’re using. It’s a common way to give staff or contractors access to internal servers through one secured, audited web entry point, or to reach your own machines from a locked-down computer.

Architecture

• guacd: the proxy daemon that speaks RDP, VNC, SSH and Telnet to the target machines.
• guacamole (web app): the Java web application (Tomcat) that users log into. It streams the session to the browser over WebSockets.
• Database (PostgreSQL or MySQL): users, connections and permissions. LDAP, OIDC/SAML and TOTP are available as extensions.

Users only ever connect to the web app over HTTPS. RDP and SSH ports on the targets stay private.

Requirements

• 2 vCPU and 2 GB RAM handles a small team. Each active graphical session uses some CPU and memory in guacd.
• Network reachability from the Guacamole server to the targets (same private network, VPN or allowed IPs).

Install with Docker Compose

mkdir -p /opt/guacamole/init && cd /opt/guacamole
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > init/initdb.sql

# /opt/guacamole/compose.yaml
services:
  guacd:
    image: guacamole/guacd:latest
    restart: unless-stopped
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: guacamole_db
      POSTGRES_USER: guacamole
      POSTGRES_PASSWORD: change-me
    volumes:
      - ./init:/docker-entrypoint-initdb.d:ro
      - ./pgdata:/var/lib/postgresql/data
  guacamole:
    image: guacamole/guacamole:latest
    restart: unless-stopped
    depends_on: [guacd, db]
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRESQL_HOSTNAME: db
      POSTGRESQL_DATABASE: guacamole_db
      POSTGRESQL_USER: guacamole
      POSTGRESQL_PASSWORD: change-me
      TOTP_ENABLED: "true"
    ports:
      - "127.0.0.1:8080:8080"

docker compose up -d

The UI is at /guacamole/. The default login is guacadmin / guacadmin: log in, create your own admin user, then delete or disable guacadmin.

Nginx with HTTPS

server {
    server_name remote.example.com;
    location / {
        proxy_pass http://127.0.0.1:8080/guacamole/;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        proxy_cookie_path /guacamole/ /;
        client_max_body_size 1g;          # file transfers
    }
    # listen 443 ssl; certbot --nginx -d remote.example.com
}

Without the WebSocket headers, Guacamole falls back to slower HTTP tunnelling. See Nginx WebSocket proxy and Let’s Encrypt.

Add connections

Settings → Connections → New connection:

• RDP (Windows): hostname/IP, port 3389, username and password (or prompt the user), security mode “Any” or “NLA”, and “Ignore server certificate” for self-signed RDP certificates. See Windows Server initial setup.
• SSH: host, port, username, and a private key or password. Colour scheme and font size are per connection.
• VNC: host, port (5900+), and password.

Group connections, and grant them to users or user groups. Users see only what’s assigned to them.

Security

• Enable TOTP 2FA (the TOTP extension, enabled above). Users enrol on their first login.
• Or put SSO in front (OIDC/SAML extensions, or Authelia/Authentik). See Authentik.
• Since Guacamole is your gateway, close RDP and SSH to the internet on the targets, and allow them only from the Guacamole server. Exposed RDP is a top attack target. See change the RDP port and Windows firewall.
• Add Fail2ban for repeated failed logins (Guacamole logs them). See Fail2ban.
• Keep the images updated.

Session recording and auditing

Guacamole can record sessions (graphical and typescript for SSH). Set “Recording path” on a connection, and mount a volume shared by guacd and the web app. The history (who connected where, and when) appears under Settings → History. This is useful for contractor access and compliance.

Clipboard and file transfer

• Clipboard: use the Guacamole menu (Ctrl+Alt+Shift) for copy/paste between your device and the session.
• File transfer: enable drive redirection (RDP) or SFTP (SSH and VNC), and drag files into the browser window.

Backups

Back up the PostgreSQL database (connections, users, history) and recordings. See pg_dump.

Quick reference

Item	Value
Components	guacd + guacamole web app + database
URL path	/guacamole/
Default login	guacadmin / guacadmin (change immediately)
Menu	Ctrl+Alt+Shift
2FA	TOTP_ENABLED=true

Related: RustDesk server and WireGuard VPN.

• Self-Hosting
• Remote Desktop
• Docker