Guacamole 1.5.3 VDI / Jump Server Appliance Build Script

A menu based build & install script for Guacamole 1.5.3 with support for TLS reverse proxy, AD integration, multi-factor authentication and further security hardening.

Automatic build, install & config script

To install Guacamole, paste the following command into your terminal (do not run as sudo):

wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.sh && chmod +x 1-setup.sh && ./1-setup.sh

Prerequisites

PLEASE NOTE: DEBIAN 12 & Tomcat 10 NOT COMPATIBLE - SEE ISSUE #10

• Ubuntu 18.04 - 22.x / Debian 11 & 10 / Raspbian Buster or Bullseye
  • (if using OS vendor cloud images - you must use stable releases of the above OS variants. Daily cloud image builds are akin to rolling releases and may contain as yet unsupported updates that break Guacamole!)
• Minimum 8GB RAM and 40GB HDD
• Public or private DNS entries that match the default route interface IP address (required for TLS)
• Incoming access on TCP ports 22, 80, and 443
• The user executing the wget installer script must be a member of the sudo group

Setup Menu Flow

1. Confim the system hostname & local domain suffix

• Change or keep the current hostname and local DNS suffix

2. Select a MySQL instance type and security baseline

• Install a new local MySQL instance, or choose an existing/remote MySQL instance.
  • Optionally add MySQL mysql_secure_installation settings to the selected MySQL instance
  • Optionally provide an email address for backup messages and alerts

3. Pick an authentication extension

• DUO, TOTP, LDAP or None
  • Simultaneous TOTP and DUO not possible, but LDAP with TOTP is ok.

4. Choose the Guacamole front end

• Install Nginx reverse Proxy? [y/n]

  • No: Keep the Guacamole native front end & url http://server.local:8080/guacamole
    • Sub option: Change Guacamole's default url to http root? Yes = http://server.local:8080
  • Yes: Prompts for a reverse proxy local dns name (this can be different to the hostname)

• Install Nginx reverse proxy with a self-signed SSL certificate? [y/n]

  • No: Installs Nginx as http reverse proxy with the given local dns name e.g. http://server.local
  • Yes: Installs Nginx as https reverse proxy with the given local dns name e.g https://server.local
    • Auto configures Nginx with a self signed TLS certificate and http redirect
    • Auto generates Windows & Linux client browser certificates

• Install Nginx reverse proxy with a Let's Encrypt certificate? [y/n]

  • Yes: = Prompts for a webmaster email & public reverse proxy dns name e.g https://your-public-site.com
    • Installs Nginx with the given public dns name
    • Auto configures Nginx with a new LetsEncrypt certificate and http redirect
    • Auto configures certificate notifications to the webmaster email
    • Auto schedules recurring certificate renewals

Optional post install hardening

The installer downloads additional scripts to manually run:

• add-fail2ban.sh - Adds a conservative fail2ban lockdown policy to Guacamole & whitelists local LAN
• add-ssl-guac-gaucd.sh - Encrypts internal traffic between Guacamole application and Guacd daemon with TLS
• add-auth-ldap.sh - Template script for integrating with Active Directory (See ACTIVE-DIRECTORY-HOW-TO.md)
• add-smtp-relay-o365.sh - Template script for email alerts via MSO65 (SMTP auth, requires BYO app password)

Active Directory integration

See Active Directory authentication instructions here

Installation notes

To create a custom or unattended setup, follow these steps:

1. From a terminal session, change to your home directory then paste and run the above wget setup link.
2. Exit the 1-setup.sh script at the first prompt. (At this point only the scripts have downloaded).
3. Customise the installation variables in the "Silent setup options" section of 1-setup.sh as appropriate.
   • Note that script variables with an actual value (e.g. VARIABLE="value") will not prompt during the interactive setup. This means that with the right combination of script variable inputs, it is possible to mass deploy full Guacamole appliances with zero touch.
4. After setting your custom variable values in 1-setup.sh, you must now run the modified script saved locally with ./1-setup.sh Beware: If you run the setup script once again via the wget link you will overwrite all your changes!
   • There should be no need to customise any scripts other than 1-setup.sh as all install options are managed in this parent script.
   • If you must make changes to any other downloaded scripts, you must also comment out their corresponding wget lines in the "Download GitHub Setup" section at the top of 1-setup.sh to prevent a re-download and overwrite when re-running the setup.
   • Be aware that all optional (manually run) add-xxxx.sh scripts are dynamically updated during the installation with variables selected at install. Editing anything other than 1-setup.sh may break this functionality.
5. If the self signed SSL option is selected, client TLS certificates are saved to $DOWNLOAD_DIR/guac-setup.
6. If any TLS option is selected, Nginx is configured to only support connections using TLS 1.2 or above.

Setup download manifest

The setup command mentioned above downloads the following items into the $DOWNLOAD_DIR/guac-setup directory:

• 1-setup.sh: The parent install script itself
• 2-install-guacamole.sh: Guacamole installation script (inspired by MysticRyuujin/guac-install)
• 3-install-nginx.sh: Installs Nginx & auto-configures a front-end reverse proxy for Guacamole (optional)
• 4a-install-ssl-self-signed-nginx.sh: Configures self-signed TLS certificate for Nginx proxy (optional)
• 4b-install-ssl-letsencrypt-nginx.sh: Installs & configures Let's Encrypt for Nginx proxy (optional)
• add-auth-duo.sh: Adds the Duo MFA extension if not selected during install (optional)
• add-auth-ldap.sh: Adds the Active Directory extension and setup template if not selected at install (optional)
• add-auth-totp.sh: Adds the TOTP MFA extension if not selected at install (optional)
• add-ssl-guac-gaucd.sh: A hardening script to add a TLS wrapper between the guacd daemon and Guacamole client application traffic (optional, consider extra performance impact mitigations)
• add-fail2ban.sh: Adds a fail2ban policy (with local subnet override) to secure Guacamole against external brute force attacks
• add-smtp-relay-o365.sh: Sets up a TLS/SMTP auth relay with O365 for monitoring & alerts (BYO app password)
• backup-guacamole.sh: A simple MySQL Guacamole backup script
• branding.jar: An example template for a customised Guacamole login screen. The extension allows some measure of branding the user interface (or delete to keep the default interface). This is a version of https://github.com/Zer0CoolX/guacamole-customize-loginscreen-extension but with further tweaks to additionally support custom browser tab favicons. Much more extensive branding is possible via CSS inside this extension.